runtime

type AdmissionChecker interface {
	Admit(ctx context.Context) Decision
}

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"`

	// PrevHash carries the sha256 of the previous event's line bytes
	// on the sink stream (raw line without the trailing newline).
	// Together with the per-emit tail-hash update this forms a hash
	// chain over the stream — any post-hoc alteration to a prior
	// event breaks the chain at that point.
	//
	// The very first event of the AuditLogger's lifetime carries
	// AuditChainGenesis ("00…00" — 32 zero bytes hex-encoded); verifiers
	// treat that value as "no predecessor" and start their walk there.
	// The field is written on EVERY event (no omitempty) — its absence
	// is itself a tampering signal.
	//
	// PrevHash is covered by the Ed25519 signature (Sig) because the
	// signature is computed after PrevHash is stamped and with only
	// Sig blanked — so tampering with prev_hash breaks both the chain
	// verification AND the signature verification. See #212 (R5) and
	// #213 (R6) / docs/security/audit-tamper-evidence.md.
	PrevHash string `json:"prev_hash"`

	// Sigp identifies the canonicalization scheme used to produce the
	// bytes over which Sig is computed. Present iff Sig is present.
	// Currently one value:
	//
	//   "jcs-1" — RFC 8785 (JCS) applied to the event with `sig`
	//             removed. Numbers are ES6-formatted; object keys are
	//             UTF-16-lexicographic-sorted; strings use minimal
	//             RFC 8259 escaping; no whitespace.
	//
	// Marked on the wire so verifiers know exactly which
	// canonicalization to apply, and so future schemes can be added
	// without confusion. The signature covers Sigp itself
	// (canonicalize is called after Sigp is stamped, with only Sig
	// blanked), so a tamperer can't downgrade the scheme.
	Sigp string `json:"sigp,omitempty"`

	// Kid identifies the audit signing key used to produce Sig.
	// Consumers cross-reference it against the JWKS served at
	// /.well-known/forge-audit-keys (or an out-of-band published
	// keyset) to fetch the matching pubkey. Present iff the Forge
	// deployment has audit signing enabled — otherwise absent.
	// See docs/security/audit-signing.md (#213 / governance R6).
	Kid string `json:"kid,omitempty"`

	// Sig is the base64-encoded Ed25519 signature over the canonical
	// preimage of this event with Sig itself empty. The preimage
	// canonicalization is identified by Sigp (currently "jcs-1" — RFC
	// 8785 JCS). Using JCS lets non-Go verifiers compute the preimage
	// with any spec-compliant library, avoiding the "reproduce Go's
	// encoding/json quirks" burden. It also sidesteps the large-int
	// precision hole where json.Marshal(json.Unmarshal(x)) isn't a
	// fixed point (JSON numbers decode to float64; JCS carries all
	// numbers through the same ES6-double rule on both sides).
	//
	// The signature covers every other field including Sigp, Kid, and
	// PrevHash — tampering with any of them (including the chain
	// link or the canonicalization scheme) is detected at verify time.
	//
	// Present iff Kid is set. Absent (and never emitted) when
	// audit signing is off. See #213 / governance R6.
	Sig string `json:"sig,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 workflow DEFINITION that invoked this
	// agent. Stable across every run of the same workflow. Sourced
	// from X-Workflow-ID at request entry; absent for direct A2A
	// invocations. SIEM consumers join on this for definition-level
	// rollups ("top failing workflows"). FORGE-2 / issue #185 split.
	WorkflowID string `json:"workflow_id,omitempty"`

	// WorkflowExecutionID identifies the per-run instance of the
	// workflow that invoked this agent. Unique per workflow
	// execution. Sourced from X-Workflow-Execution-ID at request
	// entry; absent for direct A2A invocations. SIEM consumers join
	// on this for per-run timelines ("every event in this specific
	// run, across every agent the orchestrator dispatched to"). Added
	// in FORGE-2 / issue #185.
	WorkflowExecutionID string `json:"workflow_execution_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 lines up with the
	// library's own vocabulary 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

	// Redact runs the vendor-secret regex scrub
	// (content_redact.go:RedactSecrets) on each captured field
	// before truncation. The struct's zero value has Redact=false
	// purely as a Go-zero-value artifact — operators MUST go through
	// AuditPayloadCaptureFromEnv (which defaults Redact=true) or
	// explicitly set the field. The runner's resolver enforces this
	// by always passing through FromEnv before applying any
	// forge.yaml overrides.
	//
	// Disabling redact is a deliberate escape hatch: operators whose
	// downstream sink has its own scrubber and who explicitly want to
	// see the raw bytes for tuning. See issue #163.
	Redact 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 AuditSigner struct {
	// contains filtered or unexported fields
}

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 SessionStore
	// 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 Decision struct {
	// Allowed reports whether the invocation proceeds.
	Allowed bool

	// Reason is the platform's failure code on deny. Empty on admit.
	// Stable enough for SIEM grouping (`cost_limit_exceeded`,
	// `billing_overdue`, `rate_limit_exhausted`, …) — vocabulary
	// owned by the platform.
	Reason string

	// Scope names which level in the platform's billing hierarchy
	// tripped — `agent` / `workspace` / `org` / `""`. Purely
	// informational for audit + SRE runbook routing.
	Scope string

	// Window names the quota window that tripped — `hourly`,
	// `daily`, `monthly`, `billing_cycle`, … Platform-defined.
	// Lets the audit answer "was this a daily cap or a per-minute
	// burst?" without joining against platform state.
	Window string

	// ResetAt is when the deny clears (when the platform expects the
	// caller could retry successfully). Zero when unknown. Drives
	// the Retry-After header Forge stamps on the 402 response.
	ResetAt time.Time

	// Cached reports whether this decision came from Forge's local
	// per-agent TTL cache rather than a fresh platform call.
	// Reaches the audit event and span; helps operators debug
	// propagation lag when the platform "should have" already
	// re-admitted an agent.
	Cached bool

	// Fallback is true when Allowed=true was forced by a platform
	// call failure (timeout, 5xx, network error). The Decision is
	// indistinguishable from a real admit on the wire, but operators
	// alerting on `forge.admission.fallback=true` see the platform
	// outage rate even though no caller ever observed it as a deny.
	Fallback bool
}

type DeferSpec struct {
	// To identifies the decision target. Free-form string so the
	// runtime can route to the right channel/notifier — typical
	// shapes:
	//   - "channel:slack:#oncall"
	//   - "channel:telegram:@sec-lead"
	//   - "human:user-42"
	//   - "external:https://approvals.internal/decisions"
	// The defer engine relays this verbatim; interpretation lives
	// in the notify adapter.
	To string

	// Timeout is the maximum wait before the deferral auto-DENYs.
	// Zero → 10 minutes (a sensible ceiling; sync callers holding
	// HTTP connections open longer than that risk proxy timeouts).
	Timeout time.Duration

	// ContextForApprover is a short (< 4KB) human-readable payload
	// the approver sees to make the decision. Should NOT contain
	// secrets or raw PII — the audit stream captures a truncated
	// copy on the `task_deferred` event. Include: the tool name,
	// the exact args the LLM chose, why the guardrail thought this
	// needed a human decision.
	ContextForApprover string
}

type FallbackModelConfig struct {
	Provider string
	Client   llm.ClientConfig
}

type GuardrailChecker interface {
	// CheckInbound validates an inbound (user) message — InputGate.
	// Returns a PolicyResult carrying the engine's decision. On
	// DecisionModify the implementation SHOULD have already mutated
	// msg in place so the caller's downstream reads see the redacted
	// content; PolicyResult.Modified is provided for audit-trail use.
	// On DecisionDeny the caller MUST NOT admit the message.
	CheckInbound(ctx context.Context, msg *a2a.Message) (PolicyResult, error)

	// CheckOutbound validates an outbound (agent) message —
	// OutputGate. Same semantics as CheckInbound: MODIFY mutates
	// msg in place, DENY blocks.
	CheckOutbound(ctx context.Context, msg *a2a.Message) (PolicyResult, 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 JWK struct {
	Kty string `json:"kty"`           // "OKP"
	Crv string `json:"crv"`           // "Ed25519"
	X   string `json:"x"`             // base64url of pubkey (no padding)
	Kid string `json:"kid,omitempty"` // operator-supplied key id
	Use string `json:"use,omitempty"` // "sig"
	Alg string `json:"alg,omitempty"` // "EdDSA"
}

type JWKS struct {
	Keys []JWK `json:"keys"`
}

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
	// Failed flips the emitted event to llm_call_failed (#361): the provider
	// or gateway errored/rejected the call. ErrorText carries the bounded
	// error detail (e.g. an input_schema validation message) into
	// fields.error so the failure reason reaches the audit stream, not just
	// pod logs. Failed takes precedence over Cancelled.
	//
	// Privacy: fields.error is NOT subject to the payload-capture toggle
	// (an operator who disabled capture still needs failure reasons), so it
	// is ALWAYS secret-scrubbed (RedactSecrets) and capped at 512B — a
	// provider that echoes a request fragment in an error body can't leak a
	// credential into the stream (review #362).
	Failed    bool
	ErrorText string
	// 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          SessionStore
	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)
	// DeferToolResultTruncation applies the tool-result size cap after the
	// AfterToolExec hooks instead of before, behind a pre-hook safety
	// ceiling (16x the cap, absolute max 4MB). Enable when a compression
	// hook is registered: pre-hook truncation both destroys data and breaks
	// the JSON envelopes the compressor could otherwise shrink losslessly.
	DeferToolResultTruncation bool
	// 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 LoadedKey struct {
	Private ed25519.PrivateKey
	Public  ed25519.PublicKey
	Kid     string
}

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 NoopAdmissionChecker struct{}

type NoopGuardrailChecker struct{}

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

type PlatformCommandMatch struct {
	Pattern     string
	Message     string
	LayerSource string
	LayerPath   string
}

type PlatformCommandSpec struct {
	Pattern     string
	Message     string
	LayerSource string // "system" / "user" / "workspace"
	LayerPath   string
}

type PolicyDecision int

type PolicyResult struct {
	Decision PolicyDecision
	Modified string
	Reason   string

	// RequiredAcr is populated only when Decision == DecisionStepUp
	// (governance R4b / #210). Names the auth-context class the
	// caller MUST re-authenticate under before the action is admitted.
	// The runner turns this into an RFC 9470 WWW-Authenticate challenge
	// on the 401 response: `Bearer error="step_up_required",
	// acr_values="<value>"`. Consumers (SDKs, browsers) trigger a
	// higher-assurance authentication and retry.
	//
	// Typical values follow the ACR conventions of the caller's IdP:
	//   - "acr:mfa"          — arbitrary MFA method acceptable
	//   - "urn:mace:incommon:iap:silver" — InCommon Silver
	//   - "0"/"1"/"2"        — SAML/oidc-style tier numbers
	// Forge doesn't interpret the value; it just relays it end-to-end
	// so operator + IdP + caller agree on the semantics.
	RequiredAcr string

	// Defer carries the R4c (#211) deferral parameters. Populated
	// only when Decision == DecisionDefer. See runtime.DeferSpec.
	Defer *DeferSpec
}

type ProgressEmitter func(event ProgressEvent)

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

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

type RemoteSessionStoreConfig struct {
	BaseURL       string
	AgentID       string
	OrgID         string
	WorkspaceID   string
	PlatformToken string
	Logger        Logger
	// HTTPClient overrides the default client (tests inject one).
	HTTPClient *http.Client
}

type SequenceCounter = atomic.Int64

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

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 SessionStore interface {
	// Load returns the persisted session for taskID, or (nil, nil) when
	// none exists.
	Load(taskID string) (*SessionData, error)
	// Save persists a full snapshot for data.TaskID.
	Save(data *SessionData) error
	// Delete removes the persisted session for taskID (no error if absent).
	Delete(taskID string) error
}

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 VerifyOptions struct {
	// Pubkeys is a map from Kid to Ed25519 public key. When empty,
	// signature verification is skipped entirely. Events that carry
	// a Sig field are still walked structurally + chain-verified, and
	// a soft-warning note is added to Errors so operators know the
	// signatures were not checked.
	Pubkeys map[string]ed25519.PublicKey

	// SkipChain, when true, verifies signatures only and does NOT
	// walk the hash chain. Useful for tooling that ingests a stream
	// mid-flight (SIEM tail) where the head-of-stream genesis is
	// out of view. Default false — full tamper-evidence checks
	// require both chain and signature verification.
	SkipChain bool
}

type VerifyResult struct {
	// EventCount is the total number of well-formed events read.
	EventCount int

	// FirstBadLine is the 1-indexed input line at which verification
	// first failed. Zero when the whole stream verifies.
	FirstBadLine int

	// BadEvent is the parsed body of the bad event (best effort —
	// may be empty if the line failed to parse).
	BadEvent AuditEvent

	// Reason is a short, human-readable classification of the failure.
	// Empty when OK.
	Reason string

	// SigChecked counts how many events had their Ed25519 signature
	// verified (only when the caller supplied a pubkey source).
	SigChecked int

	// ChainChecked counts how many events had their prev_hash link
	// verified against the previous line's computed hash.
	ChainChecked int

	// GenesisSeen is true when the first well-formed event carried
	// PrevHash == AuditChainGenesis. A false value on a non-empty
	// stream signals HEAD truncation (the run's initial event has
	// been stripped) — surfaced via Errors as a soft warning, not
	// a hard failure, because a partial-stream fragment is a
	// legitimate use case for external SIEMs that ingest continuously.
	GenesisSeen bool

	// Errors accumulates non-fatal issues that don't stop verification.
	// Populated even on OK() streams — used for head-truncation
	// warnings and "signed events but no --pubkey" notes.
	Errors []string
}

type WorkflowContext struct {
	// WorkflowID identifies the workflow DEFINITION — stable across
	// all runs of the same workflow. Sourced from X-Workflow-ID.
	// Audit consumers join on this for definition-level rollups:
	// "top failing workflows," "latency by workflow definition."
	WorkflowID string

	// WorkflowExecutionID identifies the PER-RUN instance — unique
	// per workflow execution. Sourced from X-Workflow-Execution-ID.
	// Audit consumers join on this for per-run timelines: "show me
	// every event in this specific run, across every agent the
	// orchestrator dispatched to." Added in FORGE-2 / issue #185.
	WorkflowExecutionID 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
}

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