runtime

type AgentExecutor interface {
	// Execute processes a message in the context of a task and returns a response.
	Execute(ctx context.Context, task *a2a.Task, msg *a2a.Message) (*a2a.Message, error)
	// ExecuteStream processes a message and returns a channel of response messages.
	ExecuteStream(ctx context.Context, task *a2a.Task, msg *a2a.Message) (<-chan *a2a.Message, error)
	// Close releases any resources held by the executor.
	Close() error
}

type AgentRuntime interface {
	// Start launches the agent backend.
	Start(ctx context.Context) error
	// Invoke sends a synchronous task request and returns the completed task.
	Invoke(ctx context.Context, taskID string, msg *a2a.Message) (*a2a.Task, error)
	// Stream sends a streaming task request and returns a channel of task updates.
	Stream(ctx context.Context, taskID string, msg *a2a.Message) (<-chan *a2a.Task, error)
	// Healthy reports whether the agent backend is responsive.
	Healthy(ctx context.Context) bool
	// Stop shuts down the agent backend.
	Stop() error
	// Restart stops and restarts the agent backend.
	Restart(ctx context.Context) error
}

type AuditEvent struct {
	Timestamp string `json:"ts"`
	Event     string `json:"event"`

	// SchemaVersion advertises the audit-event contract version every
	// emitted event conforms to. Consumers (initializ platform,
	// custom SIEM pipelines) read this once per agent run to detect
	// schema upgrades. Backward-compatible additions to the schema
	// do not bump the version; removals or semantic changes do.
	// See docs/security/audit-logging.md#schema-contract-fws-8.
	SchemaVersion string `json:"schema_version,omitempty"`

	// Sequence is a per-invocation monotonically increasing counter.
	// Starts at 1 for the first event of an invocation; advances by
	// 1 on each subsequent event from that invocation. Consumers
	// detect gaps (lost / out-of-order events) by comparing
	// Sequence values within a (correlation_id, task_id) group.
	//
	// Sequences are scoped to a single A2A invocation — different
	// invocations start their own counters. Events emitted outside
	// any invocation scope (startup events: policy_loaded,
	// agent_card_published, audit_export_status) have no Sequence
	// and omit the field.
	//
	// See issue #91 / FWS-8.
	Sequence int64 `json:"seq,omitempty"`

	// CorrelationID groups events from a single agent invocation —
	// generated by the A2A handler at request entry.
	CorrelationID string `json:"correlation_id,omitempty"`

	// TaskID is the A2A task identifier (params.id on tasks/send).
	TaskID string `json:"task_id,omitempty"`

	// WorkflowID identifies the orchestrator-level workflow run that
	// invoked this agent. Sourced from X-Workflow-ID at request entry;
	// absent for direct A2A invocations.
	WorkflowID string `json:"workflow_id,omitempty"`

	// StageID identifies the workflow stage that invoked this agent.
	StageID string `json:"stage_id,omitempty"`

	// StepID identifies the workflow step that invoked this agent.
	StepID string `json:"step_id,omitempty"`

	// InvocationCaller identifies the upstream caller (orchestrator
	// or upstream agent in an agent-to-agent flow).
	InvocationCaller string `json:"invocation_caller,omitempty"`

	// OrgID + WorkspaceID stamp the tenancy this agent run belongs
	// to. Sourced from one of three layers (highest precedence first):
	//
	//   1. Explicit value set on the event before emit.
	//   2. Per-request override headers parsed at the A2A boundary
	//      (X-Forge-Org-ID / X-Forge-Workspace-ID) and stashed on the
	//      context via WithTenancyContext.
	//   3. Deployment-time stamp installed on the AuditLogger via
	//      WithTenancy(orgID, workspaceID) — typically populated from
	//      FORGE_ORG_ID / FORGE_WORKSPACE_ID at agent startup.
	//
	// Both keys use omitempty so deployments that don't set tenancy
	// keep emitting the pre-tenancy JSON shape verbatim. The
	// AuditSchemaVersion is NOT bumped — additive optional fields are
	// schema-compatible per the documented policy. See issue #157.
	//
	// Distinct from the auth-derived `auth_verify.fields.org_id`,
	// which continues to carry whatever the inbound token claimed.
	// The top-level OrgID here is the operator's declared tenancy,
	// trusted because the deployment / orchestrator set it.
	OrgID       string `json:"org_id,omitempty"`
	WorkspaceID string `json:"workspace_id,omitempty"`

	// EntityID + EntityType identify which entity emitted this event.
	// Sourced from two layers (highest precedence first):
	//
	//   1. Explicit value set on the event before emit.
	//   2. Deployment-time stamp installed on the AuditLogger via
	//      WithEntity(entityType, entityID) — typically populated from
	//      FORGE_AGENT_ID / cfg.AgentID at agent startup, with
	//      EntityType hardcoded to "agent" for now.
	//
	// No per-request ctx layer: entity identity is fixed at process
	// startup. If an agent serves multiple tenancies per request, the
	// OrgID / WorkspaceID layer above already covers that.
	//
	// Field names + values match the guardrails library's BasePayload
	// vocabulary (EntityID, EntityType — "agent" / "workflow" /
	// "assistant"), so the Forge NDJSON stream and the library's
	// MongoDB GuardrailAuditEvent collection share columns 1:1 and
	// can be joined without a translation table. EntityType is
	// hardcoded to "agent" today since Forge only runs agents;
	// future entity types are an additive value change, not a schema
	// change.
	//
	// Both keys use omitempty so deployments that don't set agent_id
	// keep emitting the pre-#164 JSON shape verbatim.
	EntityID   string `json:"entity_id,omitempty"`
	EntityType string `json:"entity_type,omitempty"`

	// LLM call attribution (llm_call, llm_call_cancelled, invocation_complete).
	Model    string `json:"model,omitempty"`
	Provider string `json:"provider,omitempty"`

	// Token counts captured from provider response metadata. Nil when
	// the event is not an LLM call. Non-nil with zero values + a true
	// TokensUnavailable flag when the provider did not return usage
	// (e.g. some self-hosted Ollama setups).
	InputTokens       *int `json:"input_tokens,omitempty"`
	OutputTokens      *int `json:"output_tokens,omitempty"`
	TokensUnavailable bool `json:"tokens_unavailable,omitempty"`

	// DurationMs is the wall-clock duration in milliseconds. Populated on
	// llm_call, tool_exec, and invocation_complete events.
	DurationMs *int64 `json:"duration_ms,omitempty"`

	// RequestID is the provider-specific call identifier (Anthropic
	// `id`, OpenAI `id`, etc.) — kept as an opaque debug-correlation
	// handle, never used for cost attribution.
	RequestID string `json:"request_id,omitempty"`

	// TraceID + SpanID cross-link this audit event to the OTel trace
	// the same logical operation produced (Phase 4 of the OTel
	// Tracing v1 initiative — issue #105 / #108). Populated by
	// EmitFromContext when the context carries a recording span;
	// omitted when there is no span on the context or the tracer is
	// the noop default (tracing disabled).
	//
	// Format: lowercase hex, matching W3C traceparent semantics —
	// trace_id is 32 hex chars (128-bit), span_id is 16 hex chars
	// (64-bit). Operators paste these directly into their trace
	// backend's search box to pivot from an audit row to the parent
	// trace, and vice versa.
	//
	// Backward compatibility: both fields use omitempty so consumers
	// that have not been upgraded continue to see the pre-Phase-4
	// shape verbatim (no trace_id / span_id keys at all). The
	// AuditSchemaVersion is NOT bumped — adding optional fields is a
	// schema-compatible change per the documented policy.
	TraceID string `json:"trace_id,omitempty"`
	SpanID  string `json:"span_id,omitempty"`

	Fields map[string]any `json:"fields,omitempty"`
}

type AuditExportConfig struct {
	// SocketPath is the absolute path to the in-pod Unix Domain Socket
	// the sidecar listens on. Empty disables the socket sink.
	SocketPath string

	// HTTPEndpoint is a localhost URL (e.g. "http://127.0.0.1:9097/v1/audit")
	// the fallback HTTP sink POSTs to. Empty disables the HTTP sink.
	// Ignored when SocketPath is set.
	HTTPEndpoint string

	// WriteTimeout bounds each per-event sink write. Default 50ms.
	// Applies to both the socket and HTTP sinks. The stderr safety-net
	// sink ignores this — stderr writes are bounded by the kernel's
	// pipe buffer, not by us.
	WriteTimeout time.Duration

	// DialTimeout bounds the initial socket dial. Default 1s. Ignored
	// by the HTTP sink (which sets its own per-request timeout to
	// match WriteTimeout).
	DialTimeout time.Duration
}

type AuditLogger struct {
	// contains filtered or unexported fields
}

type AuditPayloadCapture struct {
	// LLMMessages controls whether each `llm_call` event carries the
	// list of inbound chat messages (role + content) the agent sent
	// to the model. Off by default.
	LLMMessages bool
	// LLMResponse controls whether `llm_call` carries the model's
	// completion text. Off by default.
	LLMResponse bool
	// ToolArgs controls whether `tool_exec` carries the raw input
	// the agent passed to the tool. Off by default.
	ToolArgs bool
	// ToolResult controls whether `tool_exec` carries the raw
	// output the tool returned. Off by default.
	ToolResult bool

	// CapLLMMessagesBytes is the max bytes serialized for the
	// captured chat messages array. 0 = use the package default
	// (DefaultPayloadCaptureCapBytes).
	CapLLMMessagesBytes int
	// CapLLMResponseBytes — same shape, for completion text.
	CapLLMResponseBytes int
	// CapToolArgsBytes — same shape, for tool input.
	CapToolArgsBytes int
	// CapToolResultBytes — same shape, for tool output.
	CapToolResultBytes int
}

type CancellationReason string

type CancellationRegistry struct {
	// contains filtered or unexported fields
}

type Compactor struct {
	// contains filtered or unexported fields
}

type CompactorConfig struct {
	// Client is the LLM client for abstractive summarization. If nil,
	// only extractive (bullet-point) summarization is used.
	Client llm.Client
	// Store persists sessions to disk after compaction. If nil, compaction
	// still reduces in-memory messages but nothing is flushed.
	Store *MemoryStore
	// Logger for compaction events.
	Logger Logger
	// CharBudget is the total character budget. Compaction triggers when
	// totalChars exceeds CharBudget * TriggerRatio. Default: 200,000.
	CharBudget int
	// TriggerRatio is the fraction of CharBudget at which compaction fires.
	// Default: 0.6.
	TriggerRatio float64
	// MemoryFlusher flushes key observations to long-term memory before
	// compaction discards old messages. Optional.
	MemoryFlusher MemoryFlusher
}

type FallbackModelConfig struct {
	Provider string
	Client   llm.ClientConfig
}

type GuardrailChecker interface {
	// CheckInbound validates an inbound (user) message — InputGate.
	CheckInbound(ctx context.Context, msg *a2a.Message) error

	// CheckOutbound validates an outbound (agent) message —
	// OutputGate. Implementations should prefer redacting sensitive
	// content over blocking.
	CheckOutbound(ctx context.Context, msg *a2a.Message) error

	// CheckToolCall validates the arguments the agent is about to
	// pass to a tool — ToolCallGate. Called from the BeforeToolExec
	// hook. Returns the (possibly redacted) args string and any
	// blocking error. Empty args short-circuit to (args, nil).
	CheckToolCall(ctx context.Context, toolName, args string) (string, error)

	// CheckToolOutput scans tool output text — OutputGate with tool
	// metadata so the emitted guardrail_check carries `tool` for
	// SIEM grouping. Returns the (possibly redacted) text.
	CheckToolOutput(ctx context.Context, toolName, text string) (string, error)

	// CheckContext validates retrieved context (RAG chunks, memory
	// recall, dynamic system-prompt content) before it is injected
	// into the LLM prompt — ContextGate. Returns the (possibly
	// redacted) content. Empty content short-circuits.
	//
	// The current Forge call site is the BeforeLLMCall hook, which
	// scans system-role messages assembled by the loop. Future memory
	// / RAG work can call this directly from the recall path when a
	// dedicated context-injection seam exists.
	CheckContext(ctx context.Context, content string) (string, error)

	// CheckStream validates a single chunk emitted by a streaming
	// LLM call — StreamGate. Returns the (possibly redacted) chunk.
	//
	// Forge's current Execute loop does not call provider streaming
	// (ExecuteStream is a buffered wrapper around non-streaming
	// Execute), so this is not auto-wired yet. The method is exposed
	// for callers that consume llm.Client.ChatStream directly and
	// for future loop work that adds a real per-chunk seam.
	CheckStream(ctx context.Context, chunk string) (string, error)
}

type Hook func(ctx context.Context, hctx *HookContext) error

type HookContext struct {
	Messages      []llm.ChatMessage
	Response      *llm.ChatResponse
	ToolName      string
	ToolInput     string
	ToolOutput    string
	Error         error
	TaskID        string
	CorrelationID string

	// LLMCallDuration is the wall-clock time spent in the provider
	// client.Chat call. Populated for AfterLLMCall hooks.
	LLMCallDuration time.Duration
	// Provider / Model identify the LLM provider + model used for the
	// call. Populated for AfterLLMCall hooks so audit + A2A-header
	// emitters can stamp attribution without re-walking config.
	Provider string
	Model    string
	// ToolExecDuration is the wall-clock time spent executing the tool.
	// Populated for AfterToolExec hooks.
	ToolExecDuration time.Duration
}

type HookPoint int

type HookRegistry struct {
	// contains filtered or unexported fields
}

type JSONLogger struct {
	// contains filtered or unexported fields
}

type LLMCallAuditArgs struct {
	Model     string
	Provider  string
	RequestID string
	Usage     LLMUsage
	Duration  time.Duration
	// Cancelled flips the emitted event from llm_call to llm_call_cancelled.
	// Used for streaming calls aborted mid-flight; partial usage counts are
	// still carried.
	Cancelled bool
	// Fields carries optional extra metadata to fold into the emitted
	// event's `fields` map. Populated by the runner's hook layer when
	// AuditPayloadCapture has any flag enabled (issue #91 / FWS-8):
	// captured prompt_messages, completion_text, etc. Nil for the
	// default metadata-only audit posture.
	Fields map[string]any
}

type LLMExecutor struct {
	// contains filtered or unexported fields
}

type LLMExecutorConfig struct {
	Client         llm.Client
	Tools          ToolExecutor
	Hooks          *HookRegistry
	SystemPrompt   string
	MaxIterations  int
	Compactor      *Compactor
	Store          *MemoryStore
	Logger         Logger
	ModelName      string        // model name for context-aware budgeting
	Provider       string        // provider name (anthropic, openai, ollama, custom) — for audit attribution
	CharBudget     int           // explicit char budget override (0 = auto from model)
	FilesDir       string        // directory for file_create output (default: $TMPDIR/forge-files)
	SessionMaxAge  time.Duration // max idle time before session recovery is skipped (0 = 30m default)
	WorkflowPhases []string      // workflow phases from skills (edit, finalize, query)
	// TracingConfig is the same observability.TracingConfig the cli
	// runner resolves and passes to NewTracerProvider. The executor
	// reads CaptureContent + Redact to decide whether to stamp
	// prompt / completion / tool I/O content on Phase 3 spans
	// (issue #130). Zero value disables content capture.
	TracingConfig observability.TracingConfig
}

type LLMUsage struct {
	InputTokens  int
	OutputTokens int
	TotalTokens  int
}

type LLMUsageAccumulator struct {
	// contains filtered or unexported fields
}

type LLMUsageSnapshot struct {
	InputTokens        int
	OutputTokens       int
	LLMTimeTotal       time.Duration // sum of per-LLM-call durations
	InvocationDuration time.Duration // wall-clock since accumulator creation
	PrimaryModel       string
	PrimaryProvider    string
	LLMCallCount       int
	TokensUnavailable  bool
}

type Logger interface {
	Info(msg string, fields map[string]any)
	Warn(msg string, fields map[string]any)
	Error(msg string, fields map[string]any)
	Debug(msg string, fields map[string]any)
}

type Memory struct {
	// contains filtered or unexported fields
}

type MemoryFlusher interface {
	AppendDailyLog(ctx context.Context, observation string) error
}

type MemoryStore struct {
	// contains filtered or unexported fields
}

type ModelConfig struct {
	Provider  string
	Client    llm.ClientConfig
	Fallbacks []FallbackModelConfig
}

type NoopGuardrailChecker struct{}

type ProgressEmitter func(event ProgressEvent)

type ProgressEvent struct {
	Phase   string // "tool_start", "tool_end"
	Tool    string
	Message string
}

type SequenceCounter = atomic.Int64

type SessionData struct {
	TaskID    string            `json:"task_id"`
	Messages  []llm.ChatMessage `json:"messages"`
	Summary   string            `json:"summary,omitempty"`
	CreatedAt time.Time         `json:"created_at"`
	UpdatedAt time.Time         `json:"updated_at"`
}

type Sink interface {
	// Write delivers a single event. The event is already marshaled
	// NDJSON (one line, trailing newline included). Returns nil even
	// on transient failure; sinks are responsible for their own
	// retry/buffering policy. A non-nil error indicates a permanent
	// sink failure that should be logged once.
	Write(ctx context.Context, eventBytes []byte) error

	// Close flushes any buffered events and releases resources. Called
	// during agent shutdown. Implementations must honor any deadline
	// on the passed context and never block beyond it.
	Close(ctx context.Context) error

	// Name returns a stable identifier ("stderr" / "unix-socket" /
	// "localhost-http") used in self-reporting and operator logs.
	Name() string

	// Stats returns counters describing sink health since process
	// start. Keys are stable strings (writes_ok, drops_timeout,
	// drops_dial, connected); values are monotonic counts or 0/1
	// flags. Used by the periodic audit_export_status emitter and
	// the /health endpoint.
	Stats() map[string]int64
}

type SkillGuardrailEngine struct {
	// contains filtered or unexported fields
}

type TenancyContext struct {
	OrgID       string
	WorkspaceID string
}

type ToolExecutor interface {
	Execute(ctx context.Context, name string, arguments json.RawMessage) (string, error)
	ToolDefinitions() []llm.ToolDefinition
}

type WorkflowContext struct {
	// WorkflowID identifies the orchestrator-level workflow run.
	WorkflowID string

	// StageID identifies a stage within the workflow (a group of
	// steps that may run in parallel).
	StageID string

	// StepID identifies the specific step within the stage that
	// invoked this agent.
	StepID string

	// InvocationCaller identifies the upstream caller — typically the
	// orchestrator's identity, but for agent-to-agent calls within a
	// workflow it carries the upstream agent's identifier.
	InvocationCaller string
}