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

package/dist/index.d.cts

@@ -0,0 +1,124 @@
+import { d as OpenCodeClient, e as OpenCodeEvent, f as OpenCodeForm, g as OpenCodeFormValue, h as OpenCodeFormField, i as OpenCodeMcpEndpoint, O as OpenCodeTurns, a as OpenCodeEngineSettings } from './engine-C_WSZ0cZ.cjs';
+export { I as InMemoryOpenCodeSessionStore, M as Milestone, j as OpenCodeAmendment, k as OpenCodeCallContext, c as OpenCodeEngineOptions, b as OpenCodeHost, l as OpenCodeKeyValue, m as OpenCodeModelRef, n as OpenCodePermissionRequest, o as OpenCodePermissionRule, p as OpenCodeReplyMismatchError, q as OpenCodeRunResult, r as OpenCodeServer, s as OpenCodeSessionCreate, t as OpenCodeSessionRef, u as OpenCodeSessionStore, v as OpenCodeToolCall, w as OpenCodeToolRefusedError, x as OpenCodeToolsClaims, y as OpenCodeToolsOptions, z as OpenCodeToolsTokens, A as OpenCodeTurn, B as OpenCodeTurnContext, P as PendingAsk, S as SessionHandle, T as TurnOutcome, C as keyValueOpenCodeSessionStore, D as openCode, E as openCodeControllers, F as openCodeProviders } from './engine-C_WSZ0cZ.cjs';
+import { ElicitationRequest, ElicitationQuestion, AgentRunner, AgentRunInput, AgentRunStartOptions, HumanReply } from '@dudousxd/nestjs-agent-core';
+import { IncomingMessage, ServerResponse } from 'node:http';
+import '@dudousxd/nestjs-agent';
+import '@nestjs/common';
+import '@modelcontextprotocol/sdk/server/index.js';
+
+type Listener = (event: OpenCodeEvent) => void;
+/** The session an event belongs to. Form events carry it inside the form. */
+declare function sessionOf(event: OpenCodeEvent): string | undefined;
+/**
+ * One event subscription per OpenCode server, fanned out to the turns listening on its sessions. A
+ * server's stream closes when its last listener leaves; a stream that drops reconnects with backoff.
+ *
+ * `subscribe()` only describes the request: the client connects when the stream is first iterated,
+ * and the server registers the subscriber some time after that. A stream is therefore open when its
+ * first event arrives, not when it was asked for — events a prompt causes before then would be lost
+ * (the catch-up recovers permissions and forms, not text, tools or the end of the execution).
+ */
+declare class OpenCodeEventHub {
+    private readonly options;
+    private readonly logger;
+    private readonly streams;
+    constructor(options?: {
+        connectTimeoutMs?: number;
+    });
+    /**
+     * Listen to one session's events on a server. Resolves once the server's stream is open (its first
+     * event arrived), or after the connect timeout — the turn's safety nets cover a stream that is
+     * slow to open.
+     */
+    listen(serverKey: string, client: OpenCodeClient, sessionId: string, listener: Listener): Promise<() => void>;
+    close(): void;
+    /**
+     * The server's stream, opened on `client`. A different client for a known key (the host
+     * replaced the connection, e.g. a new sandbox under the same key) moves every listener to a stream
+     * on the new one: the old connection may be dead, and its sessions would never hear back.
+     */
+    private streamFor;
+    private pump;
+}
+
+/** An OpenCode form field as a stream-protocol question (`docs/stream-protocol.md`, *Asking the user*). */
+declare function toQuestion(field: OpenCodeFormField): ElicitationQuestion;
+/** The elicitation an OpenCode form streams as, under `id` (the tool-call id it is answered through). */
+declare function toElicitation(id: string, form: OpenCodeForm): ElicitationRequest;
+declare class FormAnswerError extends Error {
+}
+/**
+ * The protocol's answers (question id → canonical strings) as OpenCode's form reply: numbers as
+ * numbers, booleans as booleans, multiple choice as a list. Questions left out take their defaults;
+ * a value a question can't take throws {@link FormAnswerError}.
+ */
+declare function toFormAnswer(form: OpenCodeForm, answers?: Record<string, string[]>): Record<string, OpenCodeFormValue>;
+
+/**
+ * `POST <agent path>/opencode/mcp` — the endpoint the engine registers in every OpenCode session
+ * (`mcp.add`) when `tools` is set. It authenticates its callers itself (the bearer token the engine
+ * minted for the session), so the module's `guards` are not applied to it. Stateless: no
+ * server-sent stream to resume, no session to close.
+ */
+declare class OpenCodeMcpController {
+    private readonly endpoint;
+    constructor(endpoint: OpenCodeMcpEndpoint);
+    post(req: IncomingMessage, res: ServerResponse, body: unknown): Promise<void>;
+    get(res: ServerResponse): void;
+    delete(res: ServerResponse): void;
+}
+
+/**
+ * Runs OpenCode turns in this process: `begin → prompt → [observe → wait for a person → reply]* →
+ * settle`, with the waits on people held in memory. Like `InlineAgentRunner`, a run parked on a
+ * person lives in this process, so deploy it single-replica — or use `openCodeDurable()`
+ * (`@dudousxd/nestjs-agent-opencode/durable`), which checkpoints every step and waits on a durable
+ * signal.
+ */
+declare class OpenCodeAgentRunner implements AgentRunner {
+    private readonly turns;
+    private readonly settings;
+    private readonly live;
+    private readonly cancelled;
+    private readonly pending;
+    constructor(turns: OpenCodeTurns, settings: OpenCodeEngineSettings);
+    runIdFor(input: AgentRunInput): string;
+    isRunActive(runId: string): Promise<boolean>;
+    start(input: AgentRunInput, options?: AgentRunStartOptions): Promise<{
+        runId: string;
+    }>;
+    /**
+     * Deliver a person's reply. Answers addressed at an approval are refused
+     * ({@link OpenCodeReplyMismatchError}, a 409) and the approval keeps waiting: they say nothing
+     * about whether the action should run.
+     */
+    signal(runId: string, toolCallId: string, reply: HumanReply): Promise<void>;
+    /**
+     * Stop the run: what it waits on a person for is dropped, and OpenCode is interrupted — it answers
+     * `session.execution.interrupted`, which settles the run as cancelled.
+     */
+    cancel(runId: string): Promise<void>;
+    private readonly inputs;
+    private run;
+    /** Wait for a person's answer; a lapsed approval answers itself as expired. */
+    private park;
+}
+
+/** The host's {@link import('./host.js').OpenCodeHost}. */
+declare const OPENCODE_HOST: unique symbol;
+/** Where each thread's session is kept ({@link import('./host.js').OpenCodeSessionStore}). */
+declare const OPENCODE_SESSIONS: unique symbol;
+/** The engine's {@link import('./turns.js').OpenCodeEngineSettings}. */
+declare const OPENCODE_OPTIONS: unique symbol;
+/**
+ * The engine's turn steps ({@link import('./turns.js').OpenCodeTurns}): `callContext` for the MCP
+ * surface, `pushToSession`, `liveRuns`. Inject this token, not the class — the class a host imports
+ * from the main bundle is not the one `openCodeDurable()` (`/durable`) registers.
+ */
+declare const OPENCODE_TURNS: unique symbol;
+/** The engine's tools endpoint ({@link import('./mcp.js').OpenCodeMcpEndpoint}), when `tools` is set. */
+declare const OPENCODE_MCP_ENDPOINT: unique symbol;
+/** Mints and checks the tools endpoint's bearer tokens ({@link import('./mcp.js').OpenCodeToolsTokens}). */
+declare const OPENCODE_TOOLS_TOKENS: unique symbol;
+
+export { FormAnswerError, OPENCODE_HOST, OPENCODE_MCP_ENDPOINT, OPENCODE_OPTIONS, OPENCODE_SESSIONS, OPENCODE_TOOLS_TOKENS, OPENCODE_TURNS, OpenCodeAgentRunner, OpenCodeClient, OpenCodeEngineSettings, OpenCodeEvent, OpenCodeEventHub, OpenCodeForm, OpenCodeFormField, OpenCodeFormValue, OpenCodeMcpController, OpenCodeMcpEndpoint, OpenCodeTurns, sessionOf, toElicitation, toFormAnswer, toQuestion };

package/dist/index.d.ts

@@ -0,0 +1,124 @@
+import { d as OpenCodeClient, e as OpenCodeEvent, f as OpenCodeForm, g as OpenCodeFormValue, h as OpenCodeFormField, i as OpenCodeMcpEndpoint, O as OpenCodeTurns, a as OpenCodeEngineSettings } from './engine-C_WSZ0cZ.js';
+export { I as InMemoryOpenCodeSessionStore, M as Milestone, j as OpenCodeAmendment, k as OpenCodeCallContext, c as OpenCodeEngineOptions, b as OpenCodeHost, l as OpenCodeKeyValue, m as OpenCodeModelRef, n as OpenCodePermissionRequest, o as OpenCodePermissionRule, p as OpenCodeReplyMismatchError, q as OpenCodeRunResult, r as OpenCodeServer, s as OpenCodeSessionCreate, t as OpenCodeSessionRef, u as OpenCodeSessionStore, v as OpenCodeToolCall, w as OpenCodeToolRefusedError, x as OpenCodeToolsClaims, y as OpenCodeToolsOptions, z as OpenCodeToolsTokens, A as OpenCodeTurn, B as OpenCodeTurnContext, P as PendingAsk, S as SessionHandle, T as TurnOutcome, C as keyValueOpenCodeSessionStore, D as openCode, E as openCodeControllers, F as openCodeProviders } from './engine-C_WSZ0cZ.js';
+import { ElicitationRequest, ElicitationQuestion, AgentRunner, AgentRunInput, AgentRunStartOptions, HumanReply } from '@dudousxd/nestjs-agent-core';
+import { IncomingMessage, ServerResponse } from 'node:http';
+import '@dudousxd/nestjs-agent';
+import '@nestjs/common';
+import '@modelcontextprotocol/sdk/server/index.js';
+
+type Listener = (event: OpenCodeEvent) => void;
+/** The session an event belongs to. Form events carry it inside the form. */
+declare function sessionOf(event: OpenCodeEvent): string | undefined;
+/**
+ * One event subscription per OpenCode server, fanned out to the turns listening on its sessions. A
+ * server's stream closes when its last listener leaves; a stream that drops reconnects with backoff.
+ *
+ * `subscribe()` only describes the request: the client connects when the stream is first iterated,
+ * and the server registers the subscriber some time after that. A stream is therefore open when its
+ * first event arrives, not when it was asked for — events a prompt causes before then would be lost
+ * (the catch-up recovers permissions and forms, not text, tools or the end of the execution).
+ */
+declare class OpenCodeEventHub {
+    private readonly options;
+    private readonly logger;
+    private readonly streams;
+    constructor(options?: {
+        connectTimeoutMs?: number;
+    });
+    /**
+     * Listen to one session's events on a server. Resolves once the server's stream is open (its first
+     * event arrived), or after the connect timeout — the turn's safety nets cover a stream that is
+     * slow to open.
+     */
+    listen(serverKey: string, client: OpenCodeClient, sessionId: string, listener: Listener): Promise<() => void>;
+    close(): void;
+    /**
+     * The server's stream, opened on `client`. A different client for a known key (the host
+     * replaced the connection, e.g. a new sandbox under the same key) moves every listener to a stream
+     * on the new one: the old connection may be dead, and its sessions would never hear back.
+     */
+    private streamFor;
+    private pump;
+}
+
+/** An OpenCode form field as a stream-protocol question (`docs/stream-protocol.md`, *Asking the user*). */
+declare function toQuestion(field: OpenCodeFormField): ElicitationQuestion;
+/** The elicitation an OpenCode form streams as, under `id` (the tool-call id it is answered through). */
+declare function toElicitation(id: string, form: OpenCodeForm): ElicitationRequest;
+declare class FormAnswerError extends Error {
+}
+/**
+ * The protocol's answers (question id → canonical strings) as OpenCode's form reply: numbers as
+ * numbers, booleans as booleans, multiple choice as a list. Questions left out take their defaults;
+ * a value a question can't take throws {@link FormAnswerError}.
+ */
+declare function toFormAnswer(form: OpenCodeForm, answers?: Record<string, string[]>): Record<string, OpenCodeFormValue>;
+
+/**
+ * `POST <agent path>/opencode/mcp` — the endpoint the engine registers in every OpenCode session
+ * (`mcp.add`) when `tools` is set. It authenticates its callers itself (the bearer token the engine
+ * minted for the session), so the module's `guards` are not applied to it. Stateless: no
+ * server-sent stream to resume, no session to close.
+ */
+declare class OpenCodeMcpController {
+    private readonly endpoint;
+    constructor(endpoint: OpenCodeMcpEndpoint);
+    post(req: IncomingMessage, res: ServerResponse, body: unknown): Promise<void>;
+    get(res: ServerResponse): void;
+    delete(res: ServerResponse): void;
+}
+
+/**
+ * Runs OpenCode turns in this process: `begin → prompt → [observe → wait for a person → reply]* →
+ * settle`, with the waits on people held in memory. Like `InlineAgentRunner`, a run parked on a
+ * person lives in this process, so deploy it single-replica — or use `openCodeDurable()`
+ * (`@dudousxd/nestjs-agent-opencode/durable`), which checkpoints every step and waits on a durable
+ * signal.
+ */
+declare class OpenCodeAgentRunner implements AgentRunner {
+    private readonly turns;
+    private readonly settings;
+    private readonly live;
+    private readonly cancelled;
+    private readonly pending;
+    constructor(turns: OpenCodeTurns, settings: OpenCodeEngineSettings);
+    runIdFor(input: AgentRunInput): string;
+    isRunActive(runId: string): Promise<boolean>;
+    start(input: AgentRunInput, options?: AgentRunStartOptions): Promise<{
+        runId: string;
+    }>;
+    /**
+     * Deliver a person's reply. Answers addressed at an approval are refused
+     * ({@link OpenCodeReplyMismatchError}, a 409) and the approval keeps waiting: they say nothing
+     * about whether the action should run.
+     */
+    signal(runId: string, toolCallId: string, reply: HumanReply): Promise<void>;
+    /**
+     * Stop the run: what it waits on a person for is dropped, and OpenCode is interrupted — it answers
+     * `session.execution.interrupted`, which settles the run as cancelled.
+     */
+    cancel(runId: string): Promise<void>;
+    private readonly inputs;
+    private run;
+    /** Wait for a person's answer; a lapsed approval answers itself as expired. */
+    private park;
+}
+
+/** The host's {@link import('./host.js').OpenCodeHost}. */
+declare const OPENCODE_HOST: unique symbol;
+/** Where each thread's session is kept ({@link import('./host.js').OpenCodeSessionStore}). */
+declare const OPENCODE_SESSIONS: unique symbol;
+/** The engine's {@link import('./turns.js').OpenCodeEngineSettings}. */
+declare const OPENCODE_OPTIONS: unique symbol;
+/**
+ * The engine's turn steps ({@link import('./turns.js').OpenCodeTurns}): `callContext` for the MCP
+ * surface, `pushToSession`, `liveRuns`. Inject this token, not the class — the class a host imports
+ * from the main bundle is not the one `openCodeDurable()` (`/durable`) registers.
+ */
+declare const OPENCODE_TURNS: unique symbol;
+/** The engine's tools endpoint ({@link import('./mcp.js').OpenCodeMcpEndpoint}), when `tools` is set. */
+declare const OPENCODE_MCP_ENDPOINT: unique symbol;
+/** Mints and checks the tools endpoint's bearer tokens ({@link import('./mcp.js').OpenCodeToolsTokens}). */
+declare const OPENCODE_TOOLS_TOKENS: unique symbol;
+
+export { FormAnswerError, OPENCODE_HOST, OPENCODE_MCP_ENDPOINT, OPENCODE_OPTIONS, OPENCODE_SESSIONS, OPENCODE_TOOLS_TOKENS, OPENCODE_TURNS, OpenCodeAgentRunner, OpenCodeClient, OpenCodeEngineSettings, OpenCodeEvent, OpenCodeEventHub, OpenCodeForm, OpenCodeFormField, OpenCodeFormValue, OpenCodeMcpController, OpenCodeMcpEndpoint, OpenCodeTurns, sessionOf, toElicitation, toFormAnswer, toQuestion };