gennady 0.8.3 → 0.8.4-draft.2

package/dist/services/agent-inbox/modules/inbox-opencode/opencode.port.d.ts

@@ -0,0 +1,272 @@
+import type { OpenCodeCallResult } from './errors.js';
+/** @purpose Lifecycle status of an AI-node session. */
+export type SessionStatus = 'idle' | 'running' | 'completed' | 'error' | 'terminated';
+/** @purpose Handle returned when a session is created — carries id, metadata, and current status. */
+export type SessionHandle = {
+    /** @purpose Unique session identifier */
+    sid: string;
+    /** @purpose Human-readable label for the session */
+    title: string;
+    /** @purpose Working directory bound to the session (cwd) */
+    directory: string;
+    /** @purpose Current lifecycle status */
+    status: SessionStatus;
+};
+/**
+ * @purpose Fine-grained per-tool allowlist (D-118..D-123, AI-41) — real enforcement, not declarative.
+ * @invariant Keys are server tool names (`bash`/`read`/`grep`/`write`/`edit`/...). A name absent
+ *   from the map is DENIED — composed fail-closed by `OpenCodeReal#_composeToolsGate`.
+ */
+export type ToolGate = Record<string, boolean>;
+/**
+ * @purpose True when a tools gate grants access to at least one tool — used to gate telemetry.
+ * @param gate The gate stored from `CreateSessionOpts.tools` (possibly absent).
+ * @returns Whether any tool is reachable under this gate.
+ */
+export declare function toolsGateActive(gate: boolean | ToolGate | undefined): boolean;
+/** @purpose Options for creating a new AI-node session. */
+export type CreateSessionOpts = {
+    /** @purpose Human-readable label for the session */
+    title: string;
+    /** @purpose Working directory — must exist, becomes the session cwd */
+    directory: string;
+    /**
+     * @purpose Tool access gate for this session.
+     * @invariant `true` → full default toolset; `false`/absent → no tools; a `ToolGate` object →
+     *   fine-grained allowlist, unlisted tool names denied (D-118..D-123).
+     */
+    tools?: boolean | ToolGate;
+    /**
+     * @purpose Default model for this session's turns, e.g. `llm-proxy/deepseek-v4-pro` |
+     *   @invariant Per-prompt `PromptOpts.model` overrides this default — the SDK has no
+     *   session-level model field, so adapters re-apply this as a fallback on every prompt() call.
+     */
+    model?: string;
+};
+/** @purpose A single tool invocation recorded during an agent turn — telemetry fact, not agent self-report. */
+export type ToolCall = {
+    /** @purpose Tool that performed the call (read/grep/git) */
+    tool: string;
+    /** @purpose File path touched by the tool call, relative to the session directory */
+    path: string;
+};
+/** @purpose Per-tool call-count + duration rollup for one session — localizes slowness to a tool. */
+export type ToolCallStat = {
+    /** @purpose Tool name as reported by the agent turn (e.g. 'bash', 'read', 'grep') */
+    tool: string;
+    /** @purpose Number of invocations of this tool in the session, any status */
+    count: number;
+    /** @purpose Summed wall-clock duration across completed invocations, in ms */
+    totalMs: number;
+};
+/** @purpose One tool call in session order, with its input — for the deterministic-vs-agent audit. */
+export type ToolTraceEntry = {
+    /** @purpose 0-based position of this call in the session's tool sequence */
+    seq: number;
+    /** @purpose Tool name (e.g. 'bash', 'read', 'glob') */
+    tool: string;
+    /** @purpose Short one-line input summary (bash command / file path / pattern), truncated */
+    input: string;
+    /** @purpose Wall-clock duration of the call in ms, or 0 when not completed */
+    ms: number;
+    /** @purpose Tool state status (e.g. 'completed', 'running', 'error') */
+    status: string;
+    /** @purpose Byte length of the tool's raw output text, when available (detail-report sizing). */
+    outputBytes?: number;
+    /** @purpose Newline-delimited line count of the tool's raw output, when available. */
+    outputLines?: number;
+    /** @purpose Error message text when status is 'error' — why the call was denied/failed. */
+    errorSummary?: string;
+};
+/** @purpose Structured output format descriptor — schema-driven JSON output. */
+export type OpenCodeFormat = {
+    /** @purpose Format kind — always json_schema */
+    type: 'json_schema';
+    /** @purpose JSON Schema definition for the expected output shape */
+    schema: Record<string, unknown>;
+};
+/** @purpose Options for a prompt call — system message, user text, and optional format. */
+export type PromptOpts = {
+    /** @purpose System-level instruction */
+    system?: string;
+    /** @purpose User-level prompt text */
+    text?: string;
+    /** @purpose Optional structured output format (schema-driven JSON) */
+    format?: OpenCodeFormat;
+    /** @purpose Per-call timeout for the whole agent turn, in minutes (overrides adapter default) | @invariant Unit is minutes, not ms/s — an agent turn is multi-step and long-running */
+    timeout?: number;
+    /**
+     * @purpose Per-phase model override for this one prompt call, e.g. `llm-proxy/deepseek-v4-pro` |
+     *   `llm-proxy/deepseek-v4-flash` — format is `providerID/modelID`.
+     * @invariant Absent → adapter omits the model field (falls back to `CreateSessionOpts.model`,
+     *   then the server's own configured default) — never silently forces a specific model.
+     */
+    model?: string;
+};
+/** @purpose A normalized session message retained by OpenCode adapters for lifecycle telemetry. */
+export type OpenCodeMessage = {
+    /** @purpose Author role reported by OpenCode. */
+    role: string;
+    /** @purpose Raw message parts, intentionally adapter-neutral. */
+    parts: Array<Record<string, unknown>>;
+};
+/** @purpose Attributed request for one structured agent-runtime turn. */
+export type AgentRuntimeRequest = {
+    /** @purpose Existing session selected by semantic routing. */
+    sessionId: string;
+    /** @purpose Stable task identity carried into outcome provenance. */
+    taskId: string;
+    /** @purpose Explicit model identity carried into outcome provenance. */
+    model: string;
+    /** @purpose Adapter-neutral prompt payload for this turn. */
+    prompt: PromptOpts;
+};
+/** @purpose Provenance attached to every successful or failed runtime result. */
+export type AgentRuntimeAttribution = {
+    /** @purpose Session that produced or failed the turn. */
+    sessionId: string;
+    /** @purpose Logical task that requested the turn. */
+    taskId: string;
+    /** @purpose Model selected for the turn. */
+    model: string;
+};
+/** @purpose Exhaustive attributed outcome returned by AgentRuntimePort. */
+export type AgentRuntimeResult = (AgentRuntimeAttribution & {
+    ok: true;
+    output: Record<string, unknown>;
+    trace: ToolTraceEntry[];
+}) | (AgentRuntimeAttribution & {
+    ok: false;
+    outcome: Exclude<import('./errors.ts').OutcomeClass, 'OK'>;
+    signal: string;
+    raw?: string;
+    retry: import('./errors.ts').AgentRetryMetadata;
+    trace: ToolTraceEntry[];
+});
+/** @purpose Observable live session state and accumulated factual trace. */
+export type AgentRuntimeInspection = AgentRuntimeAttribution & {
+    /** @purpose Current adapter lifecycle state. */
+    status: SessionStatus;
+    /** @purpose Complete conversation history exposed by the adapter. */
+    messages: OpenCodeMessage[];
+    /** @purpose Accumulated factual tool activity; empty means coverage is unproven. */
+    trace: ToolTraceEntry[];
+};
+/**
+ * @purpose Abstraction over an OpenCode AI-node session for structured prompting.
+ * @invariant Preconditions: non-empty system/text; existing directory path.
+ * @invariant Postconditions: success → structured output; failure → classified error.
+ * @invariant Agentic: one session = one AI-node; `tools: true` binds read/grep/git;
+ * prompt() returns after turn completes; unreachable after close().
+ * @consumers SessionPool, inbox-roles
+ */
+export declare abstract class AgentRuntimePort {
+    /**
+     * @purpose Execute one attributed turn in an existing semantically selected session.
+     * @invariant A transport/schema/task failure remains a failed result and never fabricates output.
+     * @param request Session, task, model and prompt identity for the turn.
+     * @returns Attributed success or visible failure with retry metadata and factual trace.
+     */
+    run(request: AgentRuntimeRequest): Promise<AgentRuntimeResult>;
+    /**
+     * @purpose Continue the same producer session for correction or coverage recovery.
+     * @invariant Continuation never allocates or substitutes another session.
+     * @param request Existing producer-session turn identity.
+     * @returns Attributed continuation outcome with accumulated trace.
+     */
+    continue(request: AgentRuntimeRequest): Promise<AgentRuntimeResult>;
+    /**
+     * @purpose Expose the runtime turn as an async stream while preserving one canonical run path.
+     * @param request Attributed turn identity.
+     * @returns Async iterable yielding the terminal attributed result.
+     */
+    stream(request: AgentRuntimeRequest): AsyncIterable<AgentRuntimeResult>;
+    /** @purpose Cancel one in-flight session turn through the existing adapter abort surface. */
+    cancel(sessionId: string): Promise<void>;
+    /**
+     * @purpose Inspect current session outcome context without inferring coverage from absent trace.
+     * @param attribution Session, task and model identity expected by the consumer.
+     * @returns Current lifecycle, messages and factual trace.
+     */
+    inspect(attribution: AgentRuntimeAttribution): Promise<AgentRuntimeInspection>;
+    /**
+     * @purpose Create a new AI-node session bound to a working directory.
+     * @param opts Title and directory for the session.
+     * @returns Session handle with unique id and initial 'idle' status.
+     * @throws {Error} When directory does not exist or session creation fails.
+     */
+    abstract createSession(opts: CreateSessionOpts): Promise<SessionHandle>;
+    /**
+     * @purpose Send a prompt to an existing session and await structured output or error.
+     * @param sid Session identifier from createSession.
+     * @param opts System message, user text, and optional format schema.
+     * @returns Discriminated result — ok: true with output or ok: false with classified error.
+     * @throws {Error} When sid is unknown or session is in a terminal state.
+     */
+    abstract prompt(sid: string, opts: PromptOpts): Promise<OpenCodeCallResult>;
+    /**
+     * @purpose Retrieve the current lifecycle status of a session.
+     * @param sid Session identifier.
+     * @returns Current status — may be stale by a few ms.
+     */
+    abstract status(sid: string): Promise<SessionStatus>;
+    /** @purpose Keep a live server session idle and eligible for same-session continuation. */
+    abstract park(sid: string): Promise<void>;
+    /** @purpose Resume a previously parked live server session. */
+    abstract resume(sid: string): Promise<boolean>;
+    /** @purpose Return the complete message history used by tool-trace and continuation checks. */
+    abstract messages(sid: string): Promise<OpenCodeMessage[]>;
+    /**
+     * @purpose Retrieve tool-call telemetry accumulated during the session's last agent turn —
+     * which files were opened/grepped, as fact rather than agent self-report.
+     * @invariant Default: empty array. Adapters exposing telemetry override. Not abstract — keeps
+     * pre-existing implementers compiling; telemetry is additive.
+     * @param sid Session identifier.
+     * @returns Ordered tool-call log for `ArtifactValidator` cross-check; empty when unavailable.
+     */
+    toolCalls(_sid: string): Promise<ToolCall[]>;
+    /**
+     * @purpose Retrieve per-tool call-count and duration telemetry for a session — localizes
+     * slowness to a specific tool (e.g. bash over-calling) rather than only per-node.
+     * @invariant Default: empty array. Adapters exposing telemetry override. Not abstract — keeps
+     * pre-existing implementers compiling; telemetry is additive.
+     * @param sid Session identifier.
+     * @returns Per-tool stats sorted by totalMs descending; empty when unavailable.
+     */
+    toolCallStats(_sid: string): Promise<ToolCallStat[]>;
+    /**
+     * @purpose Retrieve the ordered tool-call trace (name + input) for a session — the raw sequence
+     * for classifying each call as deterministic-precomputable vs needs-agent.
+     * @invariant Default: empty array. Adapters exposing telemetry override. Not abstract — keeps
+     * pre-existing implementers compiling; telemetry is additive.
+     * @param sid Session identifier.
+     * @returns Tool calls in session order; empty when unavailable.
+     */
+    toolCallTrace(_sid: string): Promise<ToolTraceEntry[]>;
+    /**
+     * @purpose Send a continuation signal to a session that hit an error — semantically the
+     * same as prompt but signals intent to recover, not start.
+     * @param sid Session identifier.
+     * @param opts Remediation prompt — system message, user text, and optional format.
+     * @returns Discriminated result.
+     */
+    abstract continueSignal(sid: string, opts: PromptOpts): Promise<OpenCodeCallResult>;
+    /**
+     * @purpose Abort an in-flight prompt and transition the session to 'terminated'.
+     * @param sid Session identifier.
+     * @sideEffect Session state transition: running/idle → terminated.
+     */
+    abstract abort(sid: string): Promise<void>;
+    /**
+     * @purpose Close the session and release all resources — session is unreachable afterward.
+     * @param sid Session identifier.
+     * @sideEffect Session state transition to 'terminated' if not already; resource release.
+     */
+    abstract close(sid: string): Promise<void>;
+    /** @purpose Reject incomplete provenance before any adapter side effect occurs. */
+    protected _assertRuntimeRequest(request: AgentRuntimeRequest): void;
+    /** @purpose Attach provenance, retry policy and factual trace to one legacy adapter outcome. */
+    protected _attributeRuntimeResult(request: AgentRuntimeRequest, result: OpenCodeCallResult): Promise<AgentRuntimeResult>;
+}
+/** @purpose Legacy name for the same AgentRuntimePort hierarchy during consumer migration. */
+export { AgentRuntimePort as OpenCodePort };

package/dist/services/agent-inbox/modules/inbox-opencode/opencode.real.d.ts

@@ -0,0 +1,220 @@
+import { type OpencodeClient } from '@opencode-ai/sdk';
+import { Agent as UndiciAgent } from 'undici';
+import { AgentRuntimePort, type SessionHandle, type CreateSessionOpts, type PromptOpts, type SessionStatus, type ToolCall, type ToolCallStat, type ToolTraceEntry, type ToolGate, type OpenCodeMessage } from './opencode.port.js';
+import { type OpenCodeCallResult } from './errors.js';
+/** @purpose Configuration for the OpenCodeReal adapter. */
+export type OpenCodeRealOpts = {
+    /** @purpose Base URL of the running opencode server (default: http://localhost:4096). */
+    baseUrl?: string;
+    /** @purpose Default working directory for all sessions (optional — can be set per-session). */
+    directory?: string;
+    /** @purpose Prompt timeout in milliseconds (default: 300_000 = 5min). */
+    timeout?: number;
+    /**
+     * @purpose Dispatcher for the SDK's fetch calls — disable timeouts, or undici kills a long
+     *   agentic turn with a bare "fetch failed" at 300s.
+     * @invariant Absent → SDK's default fetch, unmodified — required so tests intercepting the
+     *   network via `setGlobalDispatcher`/`MockAgent` are not silently bypassed.
+     */
+    dispatcher?: UndiciAgent;
+};
+/**
+ * @purpose Production adapter that delegates all AgentRuntimePort operations to a real
+ *          opencode server through @opencode-ai/sdk (HTTP client mode).
+ * @implements {AgentRuntimePort} in ./opencode.port.ts
+ * @invariant Connects to an existing `opencode serve` instance.
+ * @invariant When format is requested: embeds JSON schema in system prompt,
+ *           extracts JSON from response text as fallback (SDK v1.x lacks
+ *           native json_schema support).
+ * @consumer DI container (replaces OpenCodeMock in production)
+ */
+export declare class OpenCodeAgentAdapter extends AgentRuntimePort {
+    /** @purpose Base URL of the opencode server. */
+    protected _baseUrl: string;
+    /** @purpose Default directory for session binding. */
+    protected _directory: string | undefined;
+    /** @purpose Prompt timeout. */
+    protected _timeout: number;
+    /** @purpose Lazily initialized SDK client — created on first use. */
+    protected _client: OpencodeClient | null;
+    /** @purpose Optional long-timeout dispatcher (see `OpenCodeRealOpts.dispatcher`) — undefined in tests. */
+    protected _dispatcher: UndiciAgent | undefined;
+    /** @purpose Track session directory mappings (sid → directory) for per-session binding. */
+    protected _sessionDirs: Map<string, string>;
+    /** @purpose Track pending schemas per session for JSON extraction validation. */
+    protected _pendingSchemas: Map<string, Record<string, unknown>>;
+    /** @purpose Track per-session tools gate (sid → CreateSessionOpts.tools) | @invariant SDK has no session-level tools flag — re-applied on every prompt() call */
+    protected _sessionTools: Map<string, boolean | ToolGate>;
+    /** @purpose Track per-session default model (sid → CreateSessionOpts.model) | @invariant SDK has no session-level model field — re-applied on every prompt() call unless PromptOpts.model overrides it */
+    protected _sessionModels: Map<string, string>;
+    /** @purpose Track parked sessions — sid → parkedAt ISO timestamp | @invariant Only sessions marked via park() appear here */
+    protected _parkedSessions: Map<string, string>;
+    /** @purpose Directory for tool-trace JSONL output | @invariant Default: 'telemetry' relative to session directory */
+    protected _toolTraceDir: string;
+    /**
+     * @purpose Create an OpenCodeReal adapter bound to a running opencode server.
+     * @param [opts] Connection options — baseUrl, default directory, timeout.
+     */
+    constructor(opts?: OpenCodeRealOpts);
+    /**
+     * @purpose Lazily initialise the SDK client on first use.
+     * @returns The SDK client instance.
+     * @sideEffect Creates a new OpencodeClient if not already created.
+     */
+    protected _ensureClient(): OpencodeClient;
+    /**
+     * @param opts Session title and directory.
+     * @throws Wraps network errors as OpenCodeCallResult-style errors.
+     * @returns Session handle with server-assigned id.
+     * @see {AgentRuntimePort#createSession} in ./opencode.port.ts
+     */
+    createSession(opts: CreateSessionOpts): Promise<SessionHandle>;
+    /**
+     * @param sid Session identifier.
+     * @param opts System message, user text, and optional format schema.
+     * @returns Discriminated result — ok: true with output or ok: false with error.
+     * @see {AgentRuntimePort#prompt} in ./opencode.port.ts
+     */
+    prompt(sid: string, opts: PromptOpts): Promise<OpenCodeCallResult>;
+    /**
+     * @param sid Session identifier.
+     * @returns Current lifecycle status mapped from SDK SessionStatus.
+     * @see {AgentRuntimePort#status} in ./opencode.port.ts
+     */
+    status(sid: string): Promise<SessionStatus>;
+    /**
+     * @invariant `session.prompt()` returns only the LAST assistant message of the turn —
+     *           tool-call parts live on earlier messages, recoverable only via `session.messages`.
+     * @param sid Session identifier.
+     * @returns Tool calls that touched a file, path relative to the session directory.
+     * @see {AgentRuntimePort#toolCalls} in ./opencode.port.ts
+     */
+    toolCalls(sid: string): Promise<ToolCall[]>;
+    /**
+     * @invariant Counts every tool part regardless of status; only 'completed' parts with numeric
+     *   time.start/end contribute to totalMs — running/errored calls count with 0ms.
+     * @param sid Session identifier.
+     * @returns Per-tool count + totalMs, sorted by totalMs descending; empty on any error.
+     * @see {AgentRuntimePort#toolCallStats} in ./opencode.port.ts
+     */
+    toolCallStats(sid: string): Promise<ToolCallStat[]>;
+    /**
+     * @invariant Preserves message + part order; input summarized per tool and truncated to 300 chars.
+     * @param sid Session identifier.
+     * @returns Tool calls in session order with input summaries; empty on any error.
+     * @see {AgentRuntimePort#toolCallTrace} in ./opencode.port.ts
+     */
+    toolCallTrace(sid: string): Promise<ToolTraceEntry[]>;
+    /**
+     * @purpose Retrieve the full message history for a session — the raw SDK response with
+     *   role-annotated parts.
+     * @param sid Session identifier.
+     * @returns Array of messages from the session, or empty on error / not found.
+     */
+    messages(sid: string): Promise<OpenCodeMessage[]>;
+    /**
+     * @purpose Mark a session as parked — keeps it alive on the server but idle.
+     * @invariant Parked sessions can be resumed via resume(); no HTTP call — purely local state.
+     * @param sid Session identifier.
+     * @returns Promise that resolves when the park state is recorded.
+     */
+    park(sid: string): Promise<void>;
+    /**
+     * @purpose Resume a parked session — clears park state, keeps session alive.
+     * @invariant No HTTP call — the session was kept alive on the server. Caller should verify
+     *   TTL before resuming (use SessionLifecycle).
+     * @param sid Session identifier.
+     * @returns true when the session was parked and is now resumed; false if it wasn't parked.
+     */
+    resume(sid: string): Promise<boolean>;
+    /**
+     * @param sid Session identifier.
+     * @param opts Remediation prompt.
+     * @returns Discriminated result.
+     * @see {AgentRuntimePort#continueSignal} in ./opencode.port.ts
+     */
+    continueSignal(sid: string, opts: PromptOpts): Promise<OpenCodeCallResult>;
+    /**
+     * @param sid Session identifier.
+     * @returns Promise that resolves when abort completes.
+     * @sideEffect Calls POST /session/{id}/abort on the server.
+     * @see {AgentRuntimePort#abort} in ./opencode.port.ts
+     */
+    abort(sid: string): Promise<void>;
+    /**
+     * @param sid Session identifier.
+     * @returns Promise that resolves when close completes.
+     * @sideEffect Calls DELETE /session/{id} to release server resources.
+     * @see {AgentRuntimePort#close} in ./opencode.port.ts
+     */
+    close(sid: string): Promise<void>;
+    /**
+     * @purpose Core prompt logic: builds request body with system, text, optional JSON format.
+     * Extracts JSON from response when format is specified.
+     * @param sid Session identifier.
+     * @param opts Prompt options.
+     * @returns Discriminated call result.
+     */
+    protected _sendPrompt(sid: string, opts: PromptOpts): Promise<OpenCodeCallResult>;
+    /**
+     * @purpose Compose the stored tools gate into the SDK request body's `tools` shape (D-118..D-123).
+     * @invariant `true` → undefined (full toolset). `false` → deny all. A `ToolGate` → fail-closed
+     *   merge; only its explicit `true` entries are granted.
+     * @param gate The stored `CreateSessionOpts.tools` value for this session.
+     * @returns The SDK body's `tools` map, or undefined to omit the field.
+     */
+    protected _composeToolsGate(gate: boolean | ToolGate): Record<string, boolean> | undefined;
+    /**
+     * @purpose Wrap a promise with a timeout — rejects if the promise does not settle within ms.
+     * @invariant On expiry, `onTimeout` runs BEFORE reject — used to abort the server-side turn.
+     * @param promise The promise to protect.
+     * @param ms Timeout in milliseconds.
+     * @param [onTimeout] Fire-and-forget callback invoked exactly once on expiry.
+     * @returns The promise result, or throws TIMEOUT error.
+     */
+    protected _withTimeout<T>(promise: Promise<T>, ms: number, onTimeout?: () => void): Promise<T>;
+    /**
+     * @purpose Parse a port-level model string (`providerID/modelID`) into the SDK's
+     *   `session.prompt` body shape.
+     * @param modelStr e.g. `llm-proxy/deepseek-v4-pro`; undefined when no model was selected.
+     * @returns `{ providerID, modelID }` or undefined when `modelStr` is absent/malformed.
+     */
+    protected _parseModel(modelStr: string | undefined): {
+        providerID: string;
+        modelID: string;
+    } | undefined;
+    /**
+     * @purpose Strip the session directory prefix from an absolute tool-call path.
+     * @param absolutePath Absolute path reported by `ToolPart.state.input.filePath`.
+     * @param directory Session directory to strip; undefined → path returned unchanged.
+     * @returns Path relative to the session directory (port contract for `ToolCall.path`).
+     */
+    protected _relativeToSessionDirectory(absolutePath: string, directory: string | undefined): string;
+    /**
+     * @purpose Write the session's tool-call trace to telemetry/tool-trace.jsonl.
+     * @invariant Appends one JSON line per tool call to the trace file — durable record for
+     *   coverage-gate and deterministic-vs-agent audit (D-316).
+     * @param sid Session identifier.
+     * @param [directory] Session directory for building the telemetry path.
+     * @returns Promise that resolves when the trace is written.
+     * @sideEffect Appends lines to telemetry/tool-trace.jsonl in the session directory.
+     */
+    protected _writeToolTrace(sid: string, directory?: string): Promise<void>;
+    /**
+     * @purpose Generate a plausible example JSON from a JSON Schema for the prompt.
+     * @param schema The JSON Schema to generate an example from.
+     * @returns An example object matching the schema structure.
+     */
+    protected _generateExample(schema: Record<string, unknown>): Record<string, unknown>;
+    /**
+     * @purpose Perform basic structural validation of parsed JSON against a schema.
+     * Checks required fields and primitive type matching. Not a full JSON Schema validator.
+     * @param schema The expected JSON Schema.
+     * @param data The parsed JSON data to validate.
+     * @returns Array of human-readable error messages (empty = valid).
+     */
+    protected _validateSchema(schema: Record<string, unknown>, data: Record<string, unknown>): string[];
+}
+export { classifyOutcome, resolveOutcomeLadder, type LadderAction, } from './agent-outcome-classifier.js';
+/** @purpose Legacy name for the same production adapter during consumer migration. */
+export { OpenCodeAgentAdapter as OpenCodeReal };

package/dist/services/agent-inbox/modules/inbox-opencode/prompt-compile.d.ts

@@ -0,0 +1,88 @@
+import Handlebars from 'handlebars';
+/** @purpose Context for prompt compilation — task pointer, artifacts, mr, model, and role. */
+export type AgentPromptContext = {
+    /** @purpose Path to the task file (pointer, not inline content) */
+    taskPointer: string;
+    /** @purpose Stable repository root pointer used by the runtime tool boundary. */
+    repositoryRoot: string;
+    /** @purpose Immutable commit identity for every repository read in this turn. */
+    sha: string;
+    /** @purpose Stable artifact addresses produced by prior sessions. */
+    artifactAddresses: string[];
+    /** @purpose MR webUrl this prompt operates on */
+    mr: string;
+    /** @purpose Model identifier for the prompt header */
+    model?: string;
+    /** @purpose Role identifier driving directive selection */
+    role?: string;
+};
+/** @purpose Legacy compile-context name for the same strict pointer contract. */
+export type CompileContext = AgentPromptContext;
+/** @purpose Compiled prompt result — system directives and task text. */
+export type CompiledPrompt = {
+    /** @purpose System-level instructions — compiled from directive partials */
+    system: string;
+    /** @purpose Task text — carries pointers to files, schema inline */
+    task: string;
+};
+/** @purpose Configuration for the prompt compiler. */
+export type PromptCompilerConfig = {
+    /** @purpose Root directory for templates and partials | @invariant Must exist and contain .hbs templates */
+    templateDir?: string;
+};
+/**
+ * @purpose Compiles prompts from Handlebars templates in ai/kit.
+ * @invariant System = directive partials; task = file pointers (not inline); schema in task text (not system).
+ * @invariant Handlebars partials are registered from XML files in the template directory tree.
+ */
+export declare class AgentPromptCompiler {
+    /** @purpose Root directory for template and partial resolution. */
+    protected _templateDir: string;
+    /** @purpose Compiled system template — loaded once on construction. */
+    protected _systemTemplate: Handlebars.TemplateDelegate | null;
+    /** @purpose Compiled task template — loaded once on construction. */
+    protected _taskTemplate: Handlebars.TemplateDelegate | null;
+    /**
+     * @purpose Create a prompt compiler bound to a template directory.
+     * @param [config] Optional template directory override — defaults to ai/kit.
+     */
+    constructor(config?: PromptCompilerConfig);
+    /**
+     * @purpose Compile a prompt from the given context.
+     * @param context Task pointer, artifacts, mr, model, and role.
+     * @returns Compiled system and task texts.
+     */
+    compile(context: AgentPromptContext): CompiledPrompt;
+    /**
+     * @purpose Compile the system prompt from directive partials — role selects which directives apply.
+     * @param context Compilation context with role and model.
+     * @returns Compiled system prompt text.
+     */
+    protected _compileSystem(context: AgentPromptContext): string;
+    /**
+     * @purpose Compile the task text — contains pointers to files and inline schema.
+     * @invariant Task text carries file paths, not file contents — the agent reads files itself.
+     * @invariant JSON schema is inlined in the task text, never in the system prompt.
+     * @param context Compilation context with task pointer and artifacts.
+     * @returns Compiled task text.
+     */
+    protected _compileTask(context: AgentPromptContext): string;
+    /**
+     * @purpose Reject mutable, incomplete or line-breaking pointer provenance before compilation.
+     * @param context Pointer provenance to validate before template evaluation.
+     */
+    protected _assertPointerContext(context: AgentPromptContext): void;
+    /**
+     * @purpose Register Handlebars partials from XML files in the template directory tree.
+     * @sideEffect Mutates Handlebars.partials — global registration for template compilation.
+     */
+    protected _registerPartials(): void;
+    /**
+     * @purpose Load and compile a Handlebars template file.
+     * @param relativePath Path relative to the template directory.
+     * @returns Compiled template delegate, or null when the file is absent.
+     */
+    protected _loadTemplate(relativePath: string): Handlebars.TemplateDelegate | null;
+}
+/** @purpose Legacy name for the same pointer compiler during consumer migration. */
+export { AgentPromptCompiler as PromptCompiler };

package/dist/services/agent-inbox/modules/inbox-opencode/schema-registry.d.ts

@@ -0,0 +1,57 @@
+import type { OpenCodeErrorResult } from './errors.js';
+/** @purpose Result of validating one raw structured runtime outcome. */
+export type AgentSchemaValidation = {
+    ok: true;
+    output: Record<string, unknown>;
+} | {
+    ok: false;
+    error: OpenCodeErrorResult & {
+        class: 'SCHEMA_MISMATCH';
+        raw: string;
+    };
+};
+/**
+ * @purpose Collect strict object/property/required mismatches for the supported schema subset.
+ * @param schema JSON schema applied at the shared runtime boundary.
+ * @param value Parsed structured output candidate.
+ * @param [path] Current diagnostic path during recursive validation.
+ * @returns Stable list of schema mismatches; empty means valid.
+ */
+export declare function validateAgentSchema(schema: Record<string, unknown>, value: unknown, path?: string): string[];
+/**
+ * @purpose Registry of JSON Schemas keyed by AI-node identifier (not by role).
+ * @invariant One node maps to exactly one schema. Overwriting with register() replaces.
+ * @consumers inbox-roles (RoleInstance.step for session nodes)
+ */
+export declare class AgentSchemaRegistry {
+    /** @purpose Internal store: nodeId → JSON Schema definition */
+    protected _schemas: Map<string, Record<string, unknown>>;
+    /**
+     * @purpose Create an empty schema registry.
+     */
+    constructor();
+    /**
+     * @purpose Look up the JSON Schema for a given AI-node identifier.
+     * @param nodeId The AI-node identifier (e.g. 'node_scaffold', 'node_review').
+     * @returns The JSON Schema object, or undefined when not registered.
+     */
+    get(nodeId: string): Record<string, unknown> | undefined;
+    /**
+     * @purpose Register (or replace) a JSON Schema for a given AI-node identifier.
+     * @param nodeId The AI-node identifier.
+     * @param schema The JSON Schema definition.
+     * @sideEffect Mutates internal state — overwrites any existing mapping for nodeId.
+     */
+    register(nodeId: string, schema: Record<string, unknown>): void;
+    /**
+     * @purpose Validate a structured output and retain its raw evidence when the schema rejects it.
+     * @param schemaId Registered versioned task-schema identity.
+     * @param output Parsed runtime output candidate.
+     * @param raw Original runtime text retained for an exact retry.
+     * @throws {Error} When the requested schema identity is not registered.
+     * @returns Valid output or retryable schema mismatch with raw evidence.
+     */
+    validate(schemaId: string, output: unknown, raw: string): AgentSchemaValidation;
+}
+/** @purpose Legacy name for the same strict schema registry during consumer migration. */
+export { AgentSchemaRegistry as SchemaRegistry };