@dudousxd/nestjs-agent-opencode 0.0.0-stage → 0.1.1

package/dist/engine-Bij6AdoF.d.ts

@@ -0,0 +1,849 @@
+import { AgentDepsFactory, ChatQueueService, AgentEngine } from '@dudousxd/nestjs-agent';
+import { ConflictException, Logger, OnApplicationShutdown, Type, InjectionToken, Provider } from '@nestjs/common';
+import { ElicitationRequest, AgentRunInput, SinkWriter, AgentStore, ApprovalRequirement, AgentUiComponent, HumanReply, Actor, StoredMessage, ToolRegistry, TokenStreamSink, SkillsConfig, MemoryConfig, RolesPolicy, RememberToolInput, AiToolCtx } from '@dudousxd/nestjs-agent-core';
+import { IncomingMessage, ServerResponse } from 'node:http';
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+
+/**
+ * The part of OpenCode 2's server API (`@opencode/client`, the v2 routes `/api/session`,
+ * `/api/event`, …) this engine calls — structural, so the engine has no runtime dependency on the
+ * client package and a test can hand it a fake. A real `@opencode/client` client satisfies it.
+ */
+interface OpenCodeClient {
+    session: {
+        create(args: OpenCodeSessionCreate): Promise<{
+            id: string;
+        }>;
+        prompt(args: {
+            sessionID: string;
+            text: string;
+            files?: OpenCodePromptFile[];
+        }): Promise<unknown>;
+        /** Stops the running execution; OpenCode answers with `session.execution.interrupted`. */
+        interrupt(args: {
+            sessionID: string;
+        }): Promise<unknown>;
+        instructions: {
+            entry: {
+                put(args: {
+                    sessionID: string;
+                    key: string;
+                    value: string;
+                }): Promise<unknown>;
+            };
+        };
+        /** The session's info. Optional: finds the thread of a session (its `metadata.threadId`). */
+        get?(args: {
+            sessionID: string;
+        }): Promise<{
+            id: string;
+            metadata?: {
+                readonly [key: string]: OpenCodeJson;
+            };
+        }>;
+        /** Resolves when the session goes idle. Optional: a safety net for a missed terminal event. */
+        wait?(args: {
+            sessionID: string;
+        }): Promise<unknown>;
+        /** Rewind the session to before a message (regenerate). Optional. */
+        revert?: {
+            stage(args: {
+                sessionID: string;
+                messageID: string;
+                files?: boolean;
+            }): Promise<unknown>;
+            commit(args: {
+                sessionID: string;
+            }): Promise<unknown>;
+        };
+        form: {
+            /** The session's open forms. Optional: lets a resumed turn find questions asked while nobody listened. */
+            list?(args: {
+                sessionID: string;
+            }): Promise<OpenCodeForm[]>;
+            reply(args: {
+                sessionID: string;
+                formID: string;
+                answer: Record<string, OpenCodeFormValue>;
+            }): Promise<unknown>;
+            cancel(args: {
+                sessionID: string;
+                formID: string;
+            }): Promise<unknown>;
+        };
+    };
+    permission: {
+        /** The session's open permission requests. Optional, like `session.form.list`. */
+        list?(args: {
+            sessionID: string;
+        }): Promise<OpenCodePermissionRequest[]>;
+        reply(args: {
+            sessionID: string;
+            requestID: string;
+            decision: 'once' | 'reject';
+            message?: string;
+        }): Promise<unknown>;
+    };
+    /** The session's messages, newest first with `order: 'desc'`. Optional (regenerate). */
+    message?: {
+        list(args: {
+            sessionID: string;
+            order?: 'asc' | 'desc';
+            limit?: number;
+        }): Promise<{
+            data: Array<{
+                id: string;
+                type: string;
+            }>;
+        }>;
+    };
+    /** Register an MCP server at a location. Optional (exposing the module's tools). */
+    mcp?: {
+        add(args: {
+            server: string;
+            location?: {
+                directory: string;
+            };
+            config: {
+                type: 'remote';
+                url: string;
+                headers?: Record<string, string>;
+                /** `false`: never start OAuth for this server (the headers authenticate it). */
+                oauth?: false;
+            };
+        }): Promise<unknown>;
+    };
+    /** Write a file on the server. Optional (writing the module's skills where OpenCode finds them). */
+    file?: {
+        write(args: {
+            location?: {
+                directory: string;
+            };
+            path: string;
+            payload: Uint8Array;
+        }): Promise<unknown>;
+    };
+    event: {
+        /** Every event of the server, for every session, until `signal` aborts. */
+        subscribe(args: {
+            signal: AbortSignal;
+        }): AsyncIterable<OpenCodeEvent>;
+    };
+}
+/** A file attached to a prompt: a URI OpenCode can read (`file://…`, `data:…`, `https://…`). */
+interface OpenCodePromptFile {
+    uri: string;
+    name?: string;
+    description?: string;
+}
+/** A JSON value — what OpenCode stores as metadata. */
+type OpenCodeJson = string | number | boolean | null | OpenCodeJson[] | {
+    readonly [key: string]: OpenCodeJson;
+};
+interface OpenCodeSessionCreate {
+    /** A named OpenCode agent (`.opencode/agents/<name>`), when the location defines one. */
+    agent?: string;
+    model?: OpenCodeModelRef;
+    location?: {
+        directory: string;
+    };
+    /** OpenCode permission rules (`{ action, resource, effect: 'allow' | 'deny' | 'ask' }`). */
+    permissions?: OpenCodePermissionRule[];
+    metadata?: {
+        readonly [key: string]: OpenCodeJson;
+    };
+}
+interface OpenCodeModelRef {
+    providerID: string;
+    id: string;
+    variant?: string;
+}
+interface OpenCodePermissionRule {
+    action: string;
+    resource: string;
+    effect: 'allow' | 'deny' | 'ask';
+}
+/** What a form reply takes for one field. */
+type OpenCodeFormValue = string | number | boolean | string[];
+/** One server event. `data.sessionID` (or `data.form.sessionID` on form events) names its session. */
+interface OpenCodeEvent {
+    type: string;
+    data?: any;
+}
+/** A permission OpenCode is waiting on (`permission.asked`): an `ask` rule matched a tool call. */
+interface OpenCodePermissionRequest {
+    id: string;
+    sessionID: string;
+    /** The rule's action, e.g. `company.send_email` or `webfetch`. */
+    action: string;
+    resources?: string[];
+    /**
+     * About the call. A built-in tool's arguments sit straight here (`webfetch` → `{ url, format }`);
+     * calls that wrap others nest them under `input` or `args`.
+     */
+    metadata?: Record<string, unknown>;
+}
+/** A form the model put to the user through OpenCode's question tool (`form.created`). */
+interface OpenCodeForm {
+    id: string;
+    sessionID: string;
+    title?: string;
+    fields?: OpenCodeFormField[];
+}
+interface OpenCodeFormField {
+    key: string;
+    type?: string;
+    title?: string;
+    description?: string;
+    required?: boolean;
+    options?: Array<{
+        value: string;
+        label?: string;
+        description?: string;
+    }>;
+    /** The user may type their own answer instead of picking one of `options`. */
+    custom?: boolean;
+}
+
+/** How an OpenCode execution ended. */
+type TurnOutcome = {
+    status: 'succeeded';
+} | {
+    status: 'failed';
+    error: string;
+} | {
+    status: 'interrupted';
+};
+/**
+ * Something the turn put to a person, with everything needed to hand the answer back to OpenCode
+ * later — serializable, so a durable run journals it and replies from another process.
+ */
+type PendingAsk = {
+    kind: 'approval';
+    /** The OpenCode permission request id — also the tool-call id the decision is signalled under. */
+    id: string;
+    action: string;
+    approver: string;
+    expiresAt?: string;
+    /** The assistant message the call hangs on (absent for a request recovered after a restart). */
+    messageId?: string;
+} | {
+    kind: 'form';
+    id: string;
+    form: OpenCodeForm;
+    request: ElicitationRequest;
+    messageId?: string;
+};
+/** Where a turn stands: it needs a person, or it is over. */
+type Milestone = {
+    kind: 'ask';
+    ask: PendingAsk;
+    timeoutMs?: number;
+} | {
+    kind: 'finished';
+    outcome: TurnOutcome;
+};
+interface OpenCodeTurnArgs {
+    runId: string;
+    input: AgentRunInput;
+    client: OpenCodeClient;
+    sessionId: string;
+    writer: SinkWriter;
+    store: AgentStore;
+    /** What an action needs before it runs (the module's `ApprovalPolicy`). */
+    approvalFor: (action: string) => Promise<ApprovalRequirement>;
+    /** The model label usage is recorded under. */
+    modelLabel: string;
+    logger: Logger;
+    /**
+     * An action OpenCode was allowed to run (a person approved it, or the policy did): the approval
+     * the tools endpoint spends when OpenCode calls it. Called BEFORE OpenCode is told yes.
+     */
+    onGranted?: (action: string, permissionId: string) => void;
+}
+/**
+ * Answers (a form reply, a skip) sent to a call waiting for an approve/reject. They say nothing
+ * about whether the action should run — and treating them as a "no" would record a rejection the
+ * person never made — so the reply is refused (409) and the call keeps waiting.
+ */
+declare class OpenCodeReplyMismatchError extends ConflictException {
+    readonly runId: string;
+    readonly toolCallId: string;
+    constructor(runId: string, toolCallId: string);
+}
+/**
+ * One turn of an OpenCode session, as the library's stream and store see it. Fed the session's
+ * events in order, it writes the protocol's frames (`docs/stream-protocol.md`) and persists what the
+ * loop would have — the assistant messages with their tool calls and results, the calls put to a
+ * person (so the approve/answer routes find their run), usage per model step — and reports
+ * {@link Milestone}s: a person was asked something, or the execution ended.
+ *
+ * The turn does not wait for people itself. Whoever drives it (`OpenCodeTurns`, under an in-memory
+ * or a durable runner) takes the `ask` milestone, waits however it waits, and hands the answer back
+ * with {@link decide} — which is what lets a durable run wait across a restart and reply from
+ * another process, with a fresh turn object fed the journaled {@link PendingAsk}.
+ */
+declare class OpenCodeTurn {
+    private readonly a;
+    /** Serializes the handling of events, so frames and rows land in the order OpenCode sent them. */
+    private chain;
+    private segment;
+    private readonly tools;
+    /** Results already persisted per message, so a late settlement adds to them rather than replacing. */
+    private readonly messageResults;
+    private readonly asked;
+    /** Calls of {@link HIDDEN_TOOLS}, by id. */
+    private readonly hidden;
+    private readonly milestones;
+    private waiting;
+    private readonly usage;
+    private costUsd;
+    private stepOpen;
+    private sawText;
+    private separator;
+    private reasoningSince;
+    private wroteMessage;
+    private ended;
+    private stepError;
+    constructor(a: OpenCodeTurnArgs);
+    get sessionId(): string;
+    get finished(): boolean;
+    /** Feed one of the session's events. */
+    handle(event: OpenCodeEvent): void;
+    /** End the turn as failed without an event (the prompt was refused, the stream is gone). */
+    fail(error: string): void;
+    /**
+     * A component a tool pushed (`ctx.emitUi`, through the MCP surface): streamed as a `ui` frame and
+     * persisted on the message being written, in the order it arrived. Pushing the same id again
+     * replaces it.
+     */
+    pushUi(component: AgentUiComponent): Promise<void>;
+    /** The next milestone: one already reached, or the next one to come. */
+    next(): Promise<Milestone>;
+    /** Whether a milestone is waiting to be taken. */
+    hasMilestone(): boolean;
+    /**
+     * Requests OpenCode raised while nobody listened (this process started after them, or the event
+     * stream dropped): its open permissions and forms, handled as if their events had just arrived.
+     * One already recorded in the store is reported without being recorded or streamed again.
+     */
+    catchUp(): Promise<void>;
+    /**
+     * Hand a person's answer to what the turn asked, and let OpenCode go on. `tellOpenCode: false`
+     * only settles the call (stream and store): the request died with a restarted server, and the
+     * new session is told the answer in its prompt instead.
+     */
+    decide(ask: PendingAsk, reply: HumanReply, opts?: {
+        tellOpenCode?: boolean;
+    }): Promise<void>;
+    private reach;
+    private enqueue;
+    private write;
+    private step;
+    private endReasoning;
+    private tool;
+    private announce;
+    private makeAvailable;
+    private setInput;
+    private innerCalls;
+    private onEvent;
+    private settleTool;
+    private stepEnded;
+    /**
+     * Persist what the turn produced since the last flush as one assistant message — the message a
+     * call put to a person hangs on, or the turn's last one. Returns its id.
+     */
+    private flush;
+    /** A request recorded by an earlier process (a turn resumed after a restart). */
+    private alreadyRecorded;
+    /** The persisted assistant message carrying call `id`, so its result lands on the same message. */
+    private messageOf;
+    private onPermission;
+    private decided;
+    private onForm;
+    private answered;
+    private addResult;
+    private end;
+}
+
+/**
+ * Where a turn runs and how its OpenCode session is set up — the part only the host knows. The
+ * engine owns everything between the library and OpenCode (sessions per thread, the event stream,
+ * the turn's frames, approvals and questions, cancel); the host answers these questions.
+ */
+interface OpenCodeHost {
+    /**
+     * The OpenCode server this actor's turns run on — one per tenant in a sandbox, one for the whole
+     * deployment, anything. Asked once per turn, so a server that restarted is picked up.
+     */
+    server(actor: Actor): Promise<OpenCodeServer>;
+    /**
+     * How to create a session for a thread: location, model, OpenCode agent, permission rules.
+     * Asked only when the thread has no live session on this server (its first turn, or the server
+     * restarted since). `input.model` is the model the caller picked for this turn, when it picked one.
+     */
+    session(context: OpenCodeTurnContext): Promise<OpenCodeSessionCreate>;
+    /**
+     * Instructions entries refreshed on every turn (key → text), on top of the agent's own prompt
+     * (`@SystemPrompt` and the contributors, under `aviary.system`). Profile, memories, the project
+     * a chat is about… An entry that disappears is not cleared: put an empty value to drop it.
+     */
+    instructions?(context: OpenCodeTurnContext & {
+        sessionId: string;
+    }): Promise<Record<string, string>>;
+    /**
+     * What the session is prompted with, when it is more than the user message: documents read into
+     * the text, images as files the model can see. Omit → the user message, and `files`.
+     */
+    promptFor?(context: OpenCodeTurnContext & {
+        sessionId: string;
+    }): Promise<{
+        text: string;
+        files?: OpenCodePromptFile[];
+    }>;
+    /**
+     * The user message's attachments (`input.attachments`) in the form `session.prompt` takes them.
+     * Omit → attachments are not sent to OpenCode. Not asked when `promptFor` answers.
+     */
+    files?(context: OpenCodeTurnContext): Promise<OpenCodePromptFile[]>;
+    /**
+     * Anything else to do on a NEW session before its first prompt — register MCP servers
+     * (`client.mcp.add`), write skill files… Runs right after `session` and before `instructions`.
+     */
+    prepare?(context: OpenCodeTurnContext & {
+        sessionId: string;
+        client: OpenCodeClient;
+    }): Promise<void>;
+    /**
+     * `openCodeDurable()` only: the turn's workflow start options (tags, search attributes, a
+     * concurrency quota) — like `settings.durable.start`, from a host that has its services in DI.
+     */
+    startOptions?(input: AgentRunInput, runId: string): Promise<Record<string, unknown>>;
+    /** `openCodeDurable()` only: what a refused start becomes (e.g. a concurrency limit → a 429). */
+    startError?(error: unknown, input: AgentRunInput): unknown;
+    /**
+     * May this turn keep the thread's session? Asked when the session is still on its server; `false`
+     * opens a new one (told the conversation so far) — e.g. the person the session's tools act for
+     * changed. Omit → always reuse.
+     */
+    reuse?(context: OpenCodeTurnContext & {
+        session: OpenCodeSessionRef;
+    }): Promise<boolean>;
+    /**
+     * Every turn, once the session is known (`created`: opened for this turn) and before the prompt:
+     * bring it up to date — the turn's model, permission rules that changed, tools, skills.
+     */
+    beforePrompt?(context: OpenCodeTurnContext & {
+        sessionId: string;
+        client: OpenCodeClient;
+        created: boolean;
+    }): Promise<void>;
+    /**
+     * A person was asked something (an approval or a question form): post it where else they are —
+     * a Slack thread, a Teams chat — or wake whoever waits on the run. May run again for the same ask
+     * after a restart: make it idempotent.
+     */
+    onAsk?(context: OpenCodeTurnContext & {
+        sessionId: string;
+        ask: PendingAsk;
+    }): Promise<void>;
+    /** A tool pushed a component into the run (`ctx.emitUi` over MCP). */
+    onUi?(context: OpenCodeTurnContext & {
+        component: AgentUiComponent;
+    }): Promise<void>;
+    /**
+     * The run is over and about to settle: the last word on the answer — components appended to it
+     * (a guardrail notice), and for a failed run the error the person reads instead of OpenCode's.
+     */
+    beforeSettle?(result: OpenCodeRunResult): Promise<OpenCodeAmendment | undefined>;
+    /**
+     * The run settled (the stream ended, the thread moved on): deliver the answer elsewhere, record
+     * spend and telemetry. Errors are logged, never the run's.
+     */
+    onSettled?(result: OpenCodeRunResult): Promise<void>;
+}
+/** What a run produced, as the host's settle hooks see it. */
+interface OpenCodeRunResult {
+    runId: string;
+    input: AgentRunInput;
+    outcome: TurnOutcome;
+    /** The run's answer: its assistant messages' text, in order. */
+    text: string;
+    /** The run's assistant messages, as stored. */
+    messages: StoredMessage[];
+    usage: {
+        inputTokens: number;
+        outputTokens: number;
+        costUsd: number;
+    };
+    durationMs: number;
+}
+/** See {@link OpenCodeHost.beforeSettle}. */
+interface OpenCodeAmendment {
+    ui?: AgentUiComponent[];
+    /** For a failed run: what the person reads. */
+    error?: string;
+}
+interface OpenCodeServer {
+    client: OpenCodeClient;
+    /** Identifies the server across turns; sessions are only reused on the server that holds them. */
+    key: string;
+    /**
+     * Changes whenever the server restarts and loses its sessions (a sandbox boot id). Omit for a
+     * server whose sessions outlive restarts.
+     */
+    bootId?: string;
+}
+interface OpenCodeTurnContext {
+    input: AgentRunInput;
+    runId: string;
+}
+/** The session a thread talks to, and where it lives. */
+interface OpenCodeSessionRef {
+    sessionId: string;
+    serverKey: string;
+    bootId?: string;
+    /** The session's directory (`location.directory`), when it has one. */
+    directory?: string;
+    /**
+     * The agent (and persona id) the thread's latest turn ran as — what the tools endpoint checks a
+     * call against when it lands on a process that is not following the turn.
+     */
+    agentName?: string;
+    persona?: string;
+}
+/**
+ * Which OpenCode session each thread uses. The default keeps it in memory, which is enough for one
+ * process; a deployment with several replicas (or that wants sessions to survive a restart of its
+ * own) persists it — on the thread row, typically.
+ */
+interface OpenCodeSessionStore {
+    get(threadId: string): Promise<OpenCodeSessionRef | null>;
+    set(threadId: string, ref: OpenCodeSessionRef): Promise<void>;
+}
+declare class InMemoryOpenCodeSessionStore implements OpenCodeSessionStore {
+    private readonly refs;
+    get(threadId: string): Promise<OpenCodeSessionRef | null>;
+    set(threadId: string, ref: OpenCodeSessionRef): Promise<void>;
+}
+/** The two calls of a key-value store a session store needs — an ioredis or node-redis client fits. */
+interface OpenCodeKeyValue {
+    get(key: string): Promise<string | null | undefined>;
+    set(key: string, value: string): Promise<unknown>;
+}
+/**
+ * Sessions kept in a shared key-value store (Redis…), so every process of a deployment finds the
+ * session a thread already has — what running more than one process needs, alongside a
+ * cross-process `TokenStreamSink`. Keys are `<prefix><threadId>`.
+ */
+declare function keyValueOpenCodeSessionStore(kv: OpenCodeKeyValue, prefix?: string): OpenCodeSessionStore;
+
+/** What a tools token says: whose turns it may serve, on which OpenCode server, until when. */
+interface OpenCodeToolsClaims {
+    v: 1;
+    actor: Actor;
+    /** The OpenCode server key (`OpenCodeServer.key`) the token was registered on. */
+    server: string;
+    /** Epoch ms after which the token is refused. */
+    exp: number;
+}
+/**
+ * Signs and checks the bearer tokens the engine registers its tools endpoint with (`mcp.add`). A
+ * token names an actor and an OpenCode server, and expires; it is HMAC-SHA256 over its claims with
+ * a key derived from `tools.secret`.
+ *
+ * A token on its own runs nothing: the endpoint also needs the call to come from a session that is
+ * running a turn of that actor right now (see `OpenCodeTurns.callContext`), and an `action` tool
+ * needs an approval the turn granted (see `OpenCodeTurns.spendApproval`).
+ */
+declare class OpenCodeToolsTokens {
+    readonly ttlMs: number;
+    private readonly key;
+    constructor(secret: string | undefined, ttlMs: number);
+    mint(actor: Actor, server: string, now?: number): string;
+    verify(token: string, now?: number): OpenCodeToolsClaims | null;
+    private sign;
+}
+/** A call this endpoint will not run, said to the model as the tool's error. */
+declare class OpenCodeToolRefusedError extends Error {
+    readonly name = "OpenCodeToolRefusedError";
+}
+/**
+ * The MCP endpoint OpenCode sessions reach the module's tools through — `POST <agent path>/opencode/mcp`,
+ * mounted by the engine when `tools` is set. Stateless Streamable HTTP (one server per request), so
+ * any process answers.
+ *
+ * - `tools/list`: the registry's tools the token's actor may reach (roles, `enabled`, `canUse`), the
+ *   kinds only the loop serves left out; with `_meta` naming a running turn, its agent's (and
+ *   persona's) allow-list too. Plus `remember`, when the memory provider writes — served HERE only,
+ *   never registered in the module's shared registry.
+ * - `tools/call`: only for a call `_meta` ties to a turn of the token's actor running on that
+ *   session, on the token's server; the turn's allow-list and the registry's own checks apply, an
+ *   `action` runs only against an approval the turn granted (one call per approval), and the tool's
+ *   `ctx` is the turn's (thread, run, `emitUi` into its stream and message).
+ */
+declare class OpenCodeMcpEndpoint {
+    private readonly turns;
+    private readonly tokens;
+    constructor(turns: OpenCodeTurns, tokens: OpenCodeToolsTokens);
+    /** The claims of a request's bearer token, or `null`. */
+    authenticate(authorization: string | string[] | undefined): OpenCodeToolsClaims | null;
+    handle(req: IncomingMessage, res: ServerResponse, body: unknown): Promise<void>;
+    /** One MCP server for one request, answering as the token's actor. */
+    server(claims: OpenCodeToolsClaims): Server;
+    private invoke;
+    /** `remember`: one fact, at the actor's own scope only — as the loop serves it. */
+    private remember;
+}
+
+/**
+ * The module's `@AiTool`s, served to sessions over the engine's own MCP endpoint
+ * (`POST <agent path>/opencode/mcp`, mounted by the engine — not `AgentMcpServerModule`).
+ */
+interface OpenCodeToolsOptions {
+    /**
+     * The URL the OpenCode server calls that endpoint at, passed to it verbatim (no default, nothing
+     * derived). It is resolved from where OpenCode runs, not from the app: e.g.
+     * `http://127.0.0.1:3000/agent/opencode/mcp` on the same machine, the app's Compose service or
+     * Kubernetes Service name otherwise. `/agent` is `AgentModule`'s `path`; it must reach a process
+     * that mounts controllers (not `surface: 'engine'`).
+     */
+    url: string;
+    /** The MCP server's name in OpenCode; its tools are `<server>.<tool>` / `<server>_<tool>`. Default `'aviary'`. */
+    server?: string;
+    /**
+     * The secret the endpoint's bearer tokens are signed with — the same in every process that serves
+     * the agent. Omit → a random per-process secret (one process only; a warning says so).
+     */
+    secret?: string;
+    /**
+     * How long a token OpenCode is given stays valid. A token only ever reaches a turn of its own
+     * actor that is running on the session that calls, and it is re-issued on a kept session's turns
+     * once it is half-way through. Default 7 days.
+     */
+    ttlMs?: number;
+}
+interface OpenCodeEngineSettings {
+    /** The id a run gets (e.g. a tenant prefix your durable store partitions by). Default: a random UUID. */
+    runId?: (input: AgentRunInput) => string;
+    /**
+     * `openCodeDurable()` only: how each turn's workflow run starts — tags, search attributes, a
+     * concurrency quota (`WorkflowService.start` options) — and what a refused start becomes (e.g. a
+     * concurrency limit → a 429 for the person sending).
+     */
+    durable?: {
+        start?: (input: AgentRunInput, runId: string) => Record<string, unknown> | Promise<Record<string, unknown>>;
+        startError?: (error: unknown, input: AgentRunInput) => unknown;
+    };
+    /** How many earlier messages a NEW session is told about (a thread whose session was lost). Default 20. */
+    historyMessages?: number;
+    /** The instructions key the agent's own prompt is put under. Default `'aviary.system'`. */
+    systemKey?: string;
+    /** Serve the module's `@AiTool`s to the sessions. Omit → the session has the host's tools only. */
+    tools?: OpenCodeToolsOptions;
+    /** Where skills are written, relative to the session's directory. Default `'.opencode/skills'`. */
+    skillsDir?: string;
+    /**
+     * How long `observe` waits for a milestone before failing the turn. Default 30 minutes. A turn
+     * parked on a person is not observing: this bounds one stretch of OpenCode working on its own.
+     */
+    turnTimeoutMs?: number;
+}
+/** A thread's session, as the steps of a turn pass it along (and a durable run journals it). */
+interface SessionHandle {
+    sessionId: string;
+    serverKey: string;
+    bootId?: string;
+    directory?: string;
+}
+/** What the engine's MCP endpoint tells the turns about the call it is serving. */
+interface OpenCodeToolCall {
+    actor: Actor;
+    /** The OpenCode server the endpoint's token was issued for. */
+    serverKey: string;
+    /** The MCP request id, so two calls' unnamed components stay apart. */
+    requestId?: string;
+    /** The call's `_meta` — OpenCode names its session there (`ai.opencode/sessionID`). */
+    meta: Readonly<Record<string, unknown>> | undefined;
+}
+/** The turn a tool call over MCP belongs to — see {@link OpenCodeTurns.callContext}. */
+interface OpenCodeCallContext {
+    input: AgentRunInput;
+    runId: string;
+    ctx: Pick<AiToolCtx, 'threadId' | 'runId' | 'emitUi'>;
+}
+/**
+ * The steps of an OpenCode turn — `begin` (thread, session, instructions), `prompt`, `observe`
+ * (until a person is asked something or the execution ends), `reply`, `settle` — so an in-memory
+ * runner can run them in a row and a durable one can checkpoint each. A step may run in a process
+ * that did not run the one before (a durable run resumed elsewhere): the live turn is rebuilt from
+ * the session, catching up on what OpenCode asked while nobody listened.
+ */
+declare class OpenCodeTurns implements OnApplicationShutdown {
+    private readonly host;
+    private readonly sessions;
+    private readonly settings;
+    private readonly store;
+    private readonly sink;
+    private readonly deps;
+    readonly registry: ToolRegistry;
+    private readonly skills?;
+    private readonly memory?;
+    private readonly queue?;
+    private readonly toolsTokens?;
+    private readonly logger;
+    private readonly events;
+    private readonly live;
+    /** Actions approved per run, and the approvals the MCP endpoint already spent. */
+    private readonly grants;
+    private readonly spent;
+    /** When the tools endpoint was last registered for a location (`server|boot|directory|actor`). */
+    private readonly toolsIssued;
+    constructor(host: OpenCodeHost, sessions: OpenCodeSessionStore, settings: OpenCodeEngineSettings, store: AgentStore, sink: TokenStreamSink, deps: AgentDepsFactory, registry: ToolRegistry, skills?: SkillsConfig | undefined, memory?: MemoryConfig | undefined, queue?: ChatQueueService | undefined, toolsTokens?: (OpenCodeToolsTokens | null) | undefined);
+    /** The tools server's name in OpenCode. */
+    get toolsServer(): string;
+    /** The roles policy a turn's tools are gated by (the agent's own). */
+    rolesPolicyFor(input: Pick<AgentRunInput, 'agentName'>): RolesPolicy;
+    /** The tools a turn may reach: the agent's allow-list, narrowed by its persona's. */
+    allowedTools(input: Pick<AgentRunInput, 'agentName' | 'persona'>): string[] | undefined;
+    /**
+     * Whether the tools endpoint serves `remember`: the module's tools are served and the memory
+     * provider writes. Served by the engine's own endpoint only — never put in the module's shared
+     * registry, where every MCP client and the `/tools` catalog would see it.
+     */
+    memoryWritable(): boolean;
+    /** `remember` for a turn: one fact, at the actor's own scope only — as the loop serves it. */
+    remember(input: RememberToolInput, turn: OpenCodeCallContext): Promise<string>;
+    /**
+     * The turn a tool call over the engine's MCP endpoint belongs to, or `undefined` when it belongs
+     * to none — which the endpoint refuses: it exists only to serve turns. OpenCode names its session in
+     * every call's `_meta` (`ai.opencode/sessionID`); the call is that session's running turn's, and
+     * only when the endpoint's caller is the person that turn runs for, on the server the token was
+     * issued for. A session this process is not following is found through OpenCode (`session.get` →
+     * the thread it was created for → the thread's running turn); its components still reach the
+     * stream, as a message of their own.
+     */
+    callContext(call: OpenCodeToolCall): Promise<OpenCodeCallContext | undefined>;
+    /**
+     * Spend one approval of `tool` in `runId` — what the MCP endpoint asks before it runs an `action`.
+     * OpenCode asks the person (or the policy answers) before it calls an action tool; the endpoint
+     * runs it only against an approval this engine saw granted, so a caller that skipped OpenCode's
+     * permission rules (a model in code mode that read the endpoint's headers, anything else that got
+     * hold of the token) cannot run an action unapproved. One approval, one call. The approval is the
+     * run's own: live in this process, else read off the run's persisted calls (spent marks are kept
+     * per process).
+     */
+    spendApproval(runId: string, tool: string, input: Pick<AgentRunInput, 'threadId'>): Promise<boolean>;
+    private activeRun;
+    private uiPushed;
+    /**
+     * Push a component into the run an OpenCode session is serving, for the host's own trusted
+     * callers (no caller check — {@link callContext} is the one for MCP requests). `false` when no run
+     * is live on that session.
+     */
+    pushToSession(sessionId: string, component: AgentUiComponent): Promise<boolean>;
+    /** The runs this process is following now (an updater drains on it). */
+    liveRuns(): string[];
+    private threadOfSession;
+    onApplicationShutdown(): void;
+    /**
+     * Persist the user message (or rewind the thread for a regenerate), find or create the thread's
+     * session, and refresh what the session is told this turn. Safe to run again for the same run (a
+     * durable `begin` re-run after a crash): the run's user message is written once.
+     */
+    begin(runId: string, input: AgentRunInput): Promise<SessionHandle>;
+    private createSession;
+    /** The user message, as the loop persists it (or, on a regenerate, the thread rewound to it). */
+    private prepareThread;
+    /** Rewind the session to before its last user message, so the regenerated answer replaces it. */
+    private revertLastExchange;
+    /** The agent's prompt, the memory block and the host's entries — refreshed every turn. */
+    private refreshInstructions;
+    /** The agent's base prompt (`@Agent({ systemPrompt })` / `@SystemPrompt()`) and the contributors. */
+    private systemPrompt;
+    private scopeContext;
+    /** What is on file about the actor (`forRoot({ memory })`); writable when `remember` is served. */
+    private memoryBlock;
+    /**
+     * The module's skills (`forRoot({ skills })` / `@Skill`) as `SKILL.md` files under the session's
+     * directory, where OpenCode's own `skill` tool finds them. Returns the names written.
+     */
+    private writeSkills;
+    /**
+     * Permission rules for the module's tools: the MCP server allowed as a whole (OpenCode offers a
+     * server's tools only when the server itself is allowed), then each `action` tool asked — the last
+     * matching rule wins, so an action still lands on an approval card. Tools outside the agent's
+     * (and persona's) allow-list, and the kinds only the loop serves, are denied. The endpoint enforces
+     * all of it again on every call: these rules are what OpenCode offers, not what keeps a call out.
+     */
+    private toolRules;
+    /**
+     * Register the tools endpoint at the session's location, with a bearer token for the turn's actor
+     * on this server. On a new session always; on a kept one when this process has not registered it
+     * yet or its token is half-way through its life.
+     */
+    private addTools;
+    /** Start listening to the session (so nothing it says is missed), then send the user message. */
+    prompt(runId: string, input: AgentRunInput, handle: SessionHandle): Promise<void>;
+    /**
+     * Wait for the turn's next milestone. In a process that was not following the turn (a resumed
+     * durable run), the turn is rebuilt and first catches up on requests OpenCode raised meanwhile;
+     * `session.wait` is the safety net for a terminal event that was missed.
+     */
+    observe(runId: string, input: AgentRunInput, handle: SessionHandle): Promise<Milestone>;
+    /**
+     * Hand a person's answer back to OpenCode. When the server restarted while the turn waited, the
+     * request is gone with it: a new session is opened, told what the person decided, and prompted
+     * to go on.
+     */
+    reply(runId: string, input: AgentRunInput, handle: SessionHandle, ask: PendingAsk, reply: HumanReply): Promise<SessionHandle>;
+    private continueAfterRestart;
+    /** Interrupt the thread's session (cancel). */
+    interrupt(input: AgentRunInput): Promise<void>;
+    private ensureLive;
+    /** Stop following a run in this process. */
+    drop(runId: string): void;
+    /** Stop following a run and drop the approvals it was granted: it is over. */
+    private forget;
+    /** A person was asked something: tell the host (cards in other channels, wake-ups). */
+    private reached;
+    /** What the run produced, as the host's settle hooks see it. */
+    private runResult;
+    /**
+     * The host's last word on the answer before the stream ends: components to append (a guardrail
+     * notice), or, for a failed run, the error the person reads instead of OpenCode's.
+     */
+    private amend;
+    /** Delivery, telemetry, spend: after the run settled. Errors are the host's, never the run's. */
+    private settled;
+    /** End the run's stream and bookkeeping for how its execution ended. */
+    settle(runId: string, input: AgentRunInput, outcome: TurnOutcome, durationMs: number): Promise<void>;
+    settleFailed(runId: string, input: AgentRunInput, error: string, durationMs?: number): Promise<void>;
+    /** Starts the next queued message of the thread; set by the runner (it owns `start`). */
+    startNext: ((next: AgentRunInput, runId: string) => Promise<unknown>) | undefined;
+    /** As `InlineAgentRunner`: hand the thread to its next queued message, and say so on the stream. */
+    private handoff;
+}
+
+interface OpenCodeEngineOptions extends OpenCodeEngineSettings {
+    /**
+     * The host: an {@link OpenCodeHost} instance, or a provider class / token resolved from DI (so it
+     * can inject the services that know where the server is and how to set sessions up). A class is
+     * registered as a provider; a token must be provided by a module the agent module can see.
+     */
+    host: OpenCodeHost | Type<OpenCodeHost> | InjectionToken;
+    /** Where each thread's session is kept. Same forms as `host`. Omit → in memory. */
+    sessions?: OpenCodeSessionStore | Type<OpenCodeSessionStore> | InjectionToken;
+}
+/**
+ * Run the agent's turns on OpenCode 2 — `AgentModule.forRoot({ engine: openCode({ host }) })`.
+ * The routes, threads, stream protocol, approvals and queue stay the library's; OpenCode runs the
+ * model, the tools, skills and the context, on the server and sessions the host provides.
+ */
+declare function openCode(options: OpenCodeEngineOptions): AgentEngine;
+/** The engine's own controllers: the tools endpoint, when `tools` is set. */
+declare function openCodeControllers(options: OpenCodeEngineSettings): Type<object>[];
+/** The providers every OpenCode engine needs: host, session store, settings and the turn steps. */
+declare function openCodeProviders(options: OpenCodeEngineOptions): Provider[];
+
+export { OpenCodeTurn as A, type OpenCodeTurnContext as B, keyValueOpenCodeSessionStore as C, openCode as D, openCodeControllers as E, openCodeProviders as F, InMemoryOpenCodeSessionStore as I, type Milestone as M, OpenCodeTurns as O, type PendingAsk as P, type SessionHandle as S, type TurnOutcome as T, type OpenCodeEngineSettings as a, type OpenCodeHost as b, type OpenCodeEngineOptions as c, type OpenCodeClient as d, type OpenCodeEvent as e, type OpenCodeForm as f, type OpenCodeFormValue as g, type OpenCodeFormField as h, OpenCodeMcpEndpoint as i, type OpenCodeAmendment as j, type OpenCodeCallContext as k, type OpenCodeKeyValue as l, type OpenCodeModelRef as m, type OpenCodePermissionRequest as n, type OpenCodePermissionRule as o, OpenCodeReplyMismatchError as p, type OpenCodeRunResult as q, type OpenCodeServer as r, type OpenCodeSessionCreate as s, type OpenCodeSessionRef as t, type OpenCodeSessionStore as u, type OpenCodeToolCall as v, OpenCodeToolRefusedError as w, type OpenCodeToolsClaims as x, type OpenCodeToolsOptions as y, OpenCodeToolsTokens as z };