@dudousxd/nestjs-agent-opencode 1.0.0 → 2.0.0

package/dist/{engine-BX6MLzxs.d.ts → engine-yFh3eD8j.d.ts}

@@ -260,12 +260,18 @@ interface OpenCodeMessagePart {
     state?: unknown;
 }
 
-/** How an OpenCode execution ended. */
+/**
+ * How an OpenCode execution ended. `stop` is set when a stop landed on the turn (a limit, or
+ * `stopTurn`): on a `failed` outcome the stop aborted it; on a `succeeded` one the answer was
+ * already settling and was kept.
+ */
 type TurnOutcome = {
     status: 'succeeded';
+    stop?: OpenCodeTurnStop;
 } | {
     status: 'failed';
     error: string;
+    stop?: OpenCodeTurnStop;
 } | {
     status: 'interrupted';
 };
@@ -320,6 +326,11 @@ interface TurnProgress {
     settled: string[];
     /** Assistant messages whose step's usage was counted. */
     steps: string[];
+    /** The rounds and compactions the turn's limits counted so far (absent before limits travelled). */
+    counts?: {
+        steps: number;
+        compactions: number;
+    };
 }
 /** What a turn says when it was rebuilt after a restart and the session left no answer for it. */
 declare const LOST_ANSWER_ERROR = "The answer was lost while the agent restarted; ask again.";
@@ -557,12 +568,113 @@ declare class OpenCodeTurn {
  */
 declare function usageOf(tokens: any): MessageUsage;
 
+/** Why a turn was stopped by one of its {@link OpenCodeTurnLimits}. */
+type OpenCodeStopReason = 'steps' | 'compactions' | 'wall-clock';
+/**
+ * Bounds on one turn, counted from OpenCode's own events for the turn's session. Every bound is
+ * optional; a turn without any runs until OpenCode ends it (or `turnTimeoutMs`). The counts are
+ * what the turn may do: a limit of N allows N, and the one after stops the turn.
+ */
+interface OpenCodeTurnLimits {
+    /** Model rounds (`session.step.started`) the turn may run; the round after the last stops it. */
+    steps?: number;
+    /** Compactions (`session.compaction.started`) the turn may run; the one after the last stops it. */
+    compactions?: number;
+    /**
+     * Milliseconds from the turn's start (its `begin`) to stop at, time parked on a person included.
+     * A limit that passes while the turn is parked lands as soon as it observes OpenCode again.
+     */
+    wallClockMs?: number;
+}
+/** What the turn had done when it was stopped. */
+interface OpenCodeTurnCounts {
+    steps: number;
+    compactions: number;
+    elapsedMs: number;
+}
+/**
+ * A stop that landed on a turn: one of the limits, or the reason the app gave
+ * {@link OpenCodeTurns.stopTurn}. On the turn's outcome (`OpenCodeRunResult.outcome.stop`), on
+ * `onTurnEnd`, and on the durable workflow's result.
+ */
+interface OpenCodeTurnStop {
+    reason: OpenCodeStopReason | (string & {});
+    counts: OpenCodeTurnCounts;
+}
+/**
+ * What a stop did:
+ *
+ * - `aborted`: the session was aborted; the turn ends failed with `outcome.stop` (code `opencode_stopped`).
+ * - `settling`: the answer was already settling; it is kept, and `outcome.stop` still reports the stop.
+ * - `pending`: the turn is parked on a person; the stop lands when it observes OpenCode again.
+ * - `ignored`: the turn has ended, is not executed in this process (any more), no longer owns its
+ *   session, the thread's store says another run holds the thread, or the turn was already stopped.
+ * - `unconfirmed`: the thread's store could not be read, so nothing was aborted (the abort could
+ *   have landed on the thread's next turn). Ask again.
+ */
+type OpenCodeStopResult = 'aborted' | 'settling' | 'pending' | 'ignored' | 'unconfirmed';
+/**
+ * How a turn ended for the process that executed it: its outcome when it settled here, or
+ * `released` when this process stopped executing it without it ending here (another worker took
+ * the run over, or this process shut down).
+ */
+type OpenCodeTurnEndStatus = TurnOutcome['status'] | 'released';
+/**
+ * Lifecycle hooks of a turn, always called in the process that executes the turn's steps (with
+ * `openCodeDurable()`, the worker that runs them, which may not be the one that admitted the
+ * question). They carry ids and event types only, never prompts, tool input or output. Errors are
+ * logged and never fail the turn. Only `onTurnStart` is waited for, at most `hookTimeoutMs`.
+ *
+ * Every process that gets `onTurnStart` for a turn gets exactly one `onTurnEnd` for it.
+ */
+interface OpenCodeTurnHooks {
+    /**
+     * This process starts executing the turn: its `begin`, or (`resumed: true`) a later step after the
+     * run moved here — a crash, a run resumed elsewhere after a person answered.
+     */
+    onTurnStart?(event: {
+        turnId: string;
+        threadId: string;
+        sessionId: string;
+        resumed: boolean;
+    }): void | Promise<void>;
+    /** One OpenCode event of the turn's own session: its type and the session, nothing else. */
+    onTurnEvent?(event: {
+        turnId: string;
+        type: string;
+        sessionId: string;
+    }): void;
+    /** A stop landed on the turn (a limit, or `stopTurn`): revoke what it holds, record it. */
+    onStop?(event: {
+        turnId: string;
+        reason: OpenCodeTurnStop['reason'];
+        counts: OpenCodeTurnCounts;
+    }): void | Promise<void>;
+    /**
+     * This process is done with the turn: it settled here (`succeeded`, `failed`, `interrupted`), it
+     * was cancelled while parked here (`interrupted`), or this process let it go (`released`: another
+     * worker took it over, or shutdown). `stop` is set when a stop landed on it and is on its outcome.
+     */
+    onTurnEnd?(event: {
+        turnId: string;
+        status: OpenCodeTurnEndStatus;
+        stop?: OpenCodeTurnStop;
+    }): void | Promise<void>;
+}
+/** The limits as an option: fixed, or per turn. */
+type OpenCodeTurnLimitsOption = OpenCodeTurnLimits | ((input: AgentRunInput) => OpenCodeTurnLimits | undefined);
+/** The error code a stopped turn's run row and stream failure carry. */
+declare const STOPPED_ERROR_CODE = "opencode_stopped";
+
 /**
  * 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.
+ *
+ * The turn lifecycle hooks (`onTurnStart`, `onTurnEvent`, `onStop`, `onTurnEnd`) can be set here
+ * as well as on the engine's options; both are called, the options' first.
  */
-interface OpenCodeHost {
+interface OpenCodeHost extends OpenCodeTurnHooks {
     /**
      * 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.
@@ -817,7 +929,7 @@ interface OpenCodeToolsOptions {
      */
     ttlMs?: number;
 }
-interface OpenCodeEngineSettings {
+interface OpenCodeEngineSettings extends OpenCodeTurnHooks {
     /** The id a run gets (e.g. a tenant prefix your durable store partitions by). Default: a random UUID. */
     runId?: (input: AgentRunInput) => string;
     /**
@@ -842,6 +954,19 @@ interface OpenCodeEngineSettings {
      * parked on a person is not observing: this bounds one stretch of OpenCode working on its own.
      */
     turnTimeoutMs?: number;
+    /**
+     * Bounds on each turn: model rounds, compactions, wall-clock time — fixed, or per turn. A turn that
+     * passes one is stopped: its session is aborted (while the turn still owns it) and the turn ends
+     * failed with `outcome.stop` (code `opencode_stopped`), or, when its answer was already settling,
+     * succeeded with the answer kept and `outcome.stop` set. Omit → no bounds besides `turnTimeoutMs`.
+     */
+    limits?: OpenCodeTurnLimitsOption;
+    /**
+     * How long a step waits for `onTurnStart` before going on. The other hooks are not waited for (they
+     * observe); each is still given this long before a warning is logged. Default 5 seconds; it must
+     * be a positive number (anything else is refused when the module starts).
+     */
+    hookTimeoutMs?: number;
     /**
      * Whose figure a model call is recorded at. OpenCode prices each call itself, off its model
      * catalog (the `cost` its config declares, else models.dev's list price):
@@ -862,6 +987,8 @@ interface SessionHandle {
     serverKey: string;
     bootId?: string;
     directory?: string;
+    /** When the turn began (epoch ms): what `limits.wallClockMs` is measured from, in any process. */
+    startedAt?: number;
 }
 /** What the engine's MCP endpoint tells the turns about the call it is serving. */
 interface OpenCodeToolCall {
@@ -907,6 +1034,16 @@ declare class OpenCodeTurns implements OnApplicationShutdown {
     private readonly spent;
     /** When the tools endpoint was last registered for a location (`server|boot|directory|actor`). */
     private readonly toolsIssued;
+    /**
+     * What a turn let go of here had spent, for a settle that follows here (a cancel in this process
+     * that settles after the turn was released). Dropped when the run settles here, or after
+     * {@link RELEASED_USAGE_MS} when it settles elsewhere, so no run is kept for good.
+     */
+    private readonly releasedUsage;
+    private keepReleasedUsage;
+    /** The turns this process executes, and which turn owns each session (`server|session`). */
+    private readonly watches;
+    private readonly owners;
     constructor(host: OpenCodeHost, sessions: OpenCodeSessionStore, settings: OpenCodeEngineSettings, 
     /** Read by the MCP endpoint too (genui telemetry of the calls OpenCode makes). */
     store: AgentStore, sink: TokenStreamSink, deps: AgentDepsFactory, registry: ToolRegistry, skills?: SkillsConfig | undefined, memory?: MemoryConfig | undefined, queue?: ChatQueueService | undefined, toolsTokens?: (OpenCodeToolsTokens | null) | undefined, pricingStore?: AgentPricingStore, agentOptions?: {
@@ -1024,12 +1161,18 @@ declare class OpenCodeTurns implements OnApplicationShutdown {
      * back from the session's messages, when the execution ends, what nobody heard after that.
      */
     observe(runId: string, input: AgentRunInput, handle: SessionHandle, spent?: OpenCodeUsage, progress?: TurnProgress): Promise<Milestone>;
+    private observeLive;
     /**
      * 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, spent?: OpenCodeUsage, progress?: TurnProgress): Promise<SessionHandle>;
+    /**
+     * A stopping turn whose OpenCode server restarted while it waited: there is no session left to
+     * abort, and none is opened or prompted. The ask is settled as refused and the turn ends stopped.
+     */
+    private stopAfterRestart;
     private continueAfterRestart;
     /** What a session spent so far (`session.get`), or nothing when OpenCode does not say. */
     private sessionUsage;
@@ -1038,8 +1181,23 @@ declare class OpenCodeTurns implements OnApplicationShutdown {
     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. */
+    /**
+     * Stop following a run and drop the approvals it was granted: it is over. Returns the turn this
+     * process executed, now settled (no stop reaches it any more), for its `onTurnEnd`.
+     */
     private forget;
+    /**
+     * A run that ended without settling here (cancelled while this process executed it; whoever
+     * cancelled settled it): stop following it, and end the turn this process executed.
+     */
+    abandon(runId: string): Promise<void>;
+    /**
+     * Let go of a turn this process executed without settling it here: it was cancelled while parked
+     * (its session ended under it, `interrupted`), another worker took it over, or this process shuts
+     * down (`released`). The per-turn state goes, `onTurnEnd` fires once, and a later stop of the turn
+     * here is ignored. Nothing settles the run here afterwards: whoever answered or cancelled it does.
+     */
+    private release;
     /** A person was asked something: tell the host (cards in other channels, wake-ups). */
     private reached;
     /**
@@ -1065,8 +1223,84 @@ declare class OpenCodeTurns implements OnApplicationShutdown {
      * End the run's stream and bookkeeping for how its execution ended. `spent` is what the run spent
      * (the sum of its milestones' `usage`); omit → what the turn this process follows saw.
      */
-    settle(runId: string, input: AgentRunInput, outcome: TurnOutcome, durationMs: number, spent?: OpenCodeUsage): Promise<void>;
-    settleFailed(runId: string, input: AgentRunInput, error: string, durationMs?: number, spent?: OpenCodeUsage): Promise<void>;
+    settle(runId: string, input: AgentRunInput, ended: TurnOutcome, durationMs: number, spent?: OpenCodeUsage): Promise<TurnOutcome>;
+    settleFailed(runId: string, input: AgentRunInput, error: string, durationMs?: number, spent?: OpenCodeUsage, stop?: OpenCodeTurnStop): Promise<TurnOutcome>;
+    /**
+     * Stop a turn's own work: abort its session so OpenCode starts no new round, only while the turn
+     * still owns the session (a thread's session is reused by its next turn) — checked immediately
+     * before the abort. Acts in the process executing the turn; see {@link OpenCodeStopResult}. The
+     * turn ends failed with `outcome.stop` (code `opencode_stopped`), and `onStop` is called.
+     */
+    stopTurn(turnId: string, reason: OpenCodeTurnStop['reason']): Promise<OpenCodeStopResult>;
+    /** The turn this process executes, made known here on its first step in this process. */
+    private adopt;
+    private limitsFor;
+    /**
+     * One event of the turn's session: counted for the limits, and told to `onTurnEvent`. While the
+     * turn is parked on a person here, it may also say the turn went on without this process
+     * ({@link wentOnElsewhere}).
+     */
+    private sawEvent;
+    /**
+     * Whether a turn parked here went on without this process, which then lets it go. While a tool of
+     * the step waits on a person, OpenCode keeps running the step's other tools, so their events say
+     * nothing. What does: a new round (`session.step.started`, which cannot begin while the step
+     * waits), or the store showing the parked ask decided by someone else (another worker answered
+     * it, or a cancel elsewhere settled it) — this process clears the park before it answers. When
+     * the session's execution ends while parked, the store is asked again for a while, as a cancel
+     * elsewhere settles the ask just after it interrupted the session; with the ask still open, the
+     * turn stays here for its answer.
+     */
+    private wentOnElsewhere;
+    /**
+     * Ask the store whether the parked ask was decided elsewhere, and let the turn go when it was —
+     * one read at a time, at most one every {@link PARKED_READ_GAP_MS}. `series`: the session's
+     * execution ended, so the store is asked again over {@link parkedRechecksMs}. An execution that
+     * was interrupted under a parked turn means a cancel elsewhere: when the store cannot say (it has
+     * no `toolCallApproval`, the read fails, the ask is not on file) past the first recheck, or the
+     * rechecks run out with the ask still open, the turn is let go as `interrupted` anyway.
+     */
+    private checkParked;
+    /**
+     * The checks of {@link checkParked}. `checking` is cleared in the same step the loop returns in,
+     * so a check asked for afterwards starts a new loop; one asked for while it ran (`again`) but not
+     * read because the loop returned starts one too.
+     */
+    private runParkedChecks;
+    private parkedChecks;
+    /** What the store says of an ask: decided, still open, or nothing it can tell. */
+    private parkedAsk;
+    /**
+     * The waits between the store's rereads of a parked ask after its execution ended (cumulative
+     * 0.25, 1.25, 4.25, 14.25 and 44.25 seconds after the first). Overridden by tests only.
+     *
+     * @internal
+     */
+    parkedRechecksMs: readonly number[];
+    /** A limit's stop: what it did is the engine's to log, there is no caller to tell. */
+    private limitStop;
+    /** The wall-clock bound of an observation: a timer for what is left of it, if anything. */
+    private watchClock;
+    private counts;
+    private requestStop;
+    /** A stop that arrived while the answer settles: recorded and reported, the answer kept. */
+    private landed;
+    /** The milestone as the runner journals it: the limits' counts on an ask, the stop on an end. */
+    private marked;
+    /**
+     * How a turn a stop landed on ends. An answer that settled anyway is kept, with the stop on it; an
+     * execution that failed on its own keeps its error, with the stop on it; an execution the stop
+     * aborted ends failed with the stop's own text. One interrupted by a person's cancel stays so.
+     */
+    private withStop;
+    /** `onTurnEnd`, once per turn this process executed; not waited for. */
+    private ended;
+    /**
+     * A lifecycle hook, from the settings and the host, called at once. The promise settles when both
+     * have, or after `hookTimeoutMs` (default 5 s) — only `onTurnStart` is waited for. Errors are
+     * logged, never the turn's.
+     */
+    private hook;
     /** 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. */
@@ -1094,4 +1328,4 @@ declare function openCodeControllers(options: OpenCodeEngineSettings): Type<obje
 /** The providers every OpenCode engine needs: host, session store, settings and the turn steps. */
 declare function openCodeProviders(options: OpenCodeEngineOptions): Provider[];
 
-export { type OpenCodeToolsOptions as A, OpenCodeToolsTokens as B, OpenCodeTurn as C, type OpenCodeTurnContext as D, type OpenCodeUsage as E, type StepCost as F, type StepModel as G, type TurnProgress as H, InMemoryOpenCodeSessionStore as I, addUsage as J, emptyUsage as K, LOST_ANSWER_ERROR as L, type Milestone as M, keyValueOpenCodeSessionStore as N, OpenCodeTurns as O, type PendingAsk as P, openCode as Q, openCodeControllers as R, type SessionHandle as S, type TurnOutcome as T, openCodeProviders as U, usageOf as V, 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 OpenCodeMessage as m, type OpenCodeMessagePart as n, type OpenCodeModelRef as o, type OpenCodePermissionRequest as p, type OpenCodePermissionRule as q, OpenCodeReplyMismatchError as r, type OpenCodeRunResult as s, type OpenCodeServer as t, type OpenCodeSessionCreate as u, type OpenCodeSessionRef as v, type OpenCodeSessionStore as w, type OpenCodeToolCall as x, OpenCodeToolRefusedError as y, type OpenCodeToolsClaims as z };
+export { openCode as $, type OpenCodeToolCall as A, OpenCodeToolRefusedError as B, type OpenCodeToolsClaims as C, type OpenCodeToolsOptions as D, OpenCodeToolsTokens as E, OpenCodeTurn as F, type OpenCodeTurnContext as G, type OpenCodeTurnCounts as H, InMemoryOpenCodeSessionStore as I, type OpenCodeTurnEndStatus as J, type OpenCodeTurnHooks as K, LOST_ANSWER_ERROR as L, type Milestone as M, type OpenCodeTurnLimits as N, OpenCodeTurns as O, type OpenCodeTurnLimitsOption as P, type OpenCodeUsage as Q, type PendingAsk as R, STOPPED_ERROR_CODE as S, type SessionHandle as T, type StepCost as U, type StepModel as V, type TurnOutcome as W, type TurnProgress as X, addUsage as Y, emptyUsage as Z, keyValueOpenCodeSessionStore as _, type OpenCodeEngineSettings as a, openCodeControllers as a0, openCodeProviders as a1, usageOf as a2, type OpenCodeHost as b, type OpenCodeTurnStop as c, type OpenCodeEngineOptions as d, type OpenCodeClient as e, type OpenCodeEvent as f, type OpenCodeForm as g, type OpenCodeFormValue as h, type OpenCodeFormField as i, OpenCodeMcpEndpoint as j, type OpenCodeAmendment as k, type OpenCodeCallContext as l, type OpenCodeKeyValue as m, type OpenCodeMessage as n, type OpenCodeMessagePart as o, type OpenCodeModelRef as p, type OpenCodePermissionRequest as q, type OpenCodePermissionRule as r, OpenCodeReplyMismatchError as s, type OpenCodeRunResult as t, type OpenCodeServer as u, type OpenCodeSessionCreate as v, type OpenCodeSessionRef as w, type OpenCodeSessionStore as x, type OpenCodeStopReason as y, type OpenCodeStopResult as z };