@dudousxd/nestjs-agent-opencode 0.1.2 → 0.2.1

package/dist/{engine-Bij6AdoF.d.cts → engine-0YkBLWZR.d.cts}

@@ -1,6 +1,6 @@
 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 { ElicitationRequest, CostSource, AgentRunInput, SinkWriter, AgentStore, ApprovalRequirement, MessageUsage, AgentUiComponent, HumanReply, Actor, StoredMessage, ToolRegistry, TokenStreamSink, SkillsConfig, MemoryConfig, AgentPricingStore, PriceCatalogOptions, RolesPolicy, RememberToolInput, AiToolCtx } from '@dudousxd/nestjs-agent-core';
 import { IncomingMessage, ServerResponse } from 'node:http';
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 
@@ -40,6 +40,9 @@ interface OpenCodeClient {
             metadata?: {
                 readonly [key: string]: OpenCodeJson;
             };
+            /** What the session spent so far, every model call OpenCode made for it (the title too). */
+            cost?: number;
+            tokens?: OpenCodeTokens;
         }>;
         /** Resolves when the session goes idle. Optional: a safety net for a missed terminal event. */
         wait?(args: {
@@ -204,6 +207,16 @@ interface OpenCodeFormField {
     /** The user may type their own answer instead of picking one of `options`. */
     custom?: boolean;
 }
+/** A token count as OpenCode reports it: `input` is the uncached input, the cache beside it. */
+interface OpenCodeTokens {
+    input: number;
+    output: number;
+    reasoning?: number;
+    cache?: {
+        read: number;
+        write: number;
+    };
+}
 
 /** How an OpenCode execution ended. */
 type TurnOutcome = {
@@ -234,14 +247,46 @@ type PendingAsk = {
     request: ElicitationRequest;
     messageId?: string;
 };
-/** Where a turn stands: it needs a person, or it is over. */
+/**
+ * What a turn spent. `inputTokens` is the whole input side, cached input included (as the library's
+ * `MessageUsage` counts it — OpenCode's own `tokens.input` leaves the cache out); `cacheReadTokens`,
+ * `cacheWriteTokens` and `reasoningTokens` are subsets. `costUsd` sums every priced call.
+ */
+interface OpenCodeUsage {
+    inputTokens: number;
+    outputTokens: number;
+    cacheReadTokens: number;
+    cacheWriteTokens: number;
+    reasoningTokens: number;
+    costUsd: number;
+}
+declare function emptyUsage(): OpenCodeUsage;
+/** `a + b`; a missing side (a milestone journaled before usage travelled) counts as nothing. */
+declare function addUsage(a: OpenCodeUsage | undefined, b: OpenCodeUsage | undefined): OpenCodeUsage;
+/** The model a step ran on, as OpenCode names it (`session.step.started`). */
+interface StepModel {
+    providerID: string;
+    id: string;
+}
+/** What a model call cost, and where the figure came from. */
+interface StepCost {
+    costUsd?: number;
+    costSource?: CostSource;
+}
+/**
+ * Where a turn stands: it needs a person, or it is over. `usage` is what the turn spent since its
+ * previous milestone — journaled with the milestone, so a run resumed in another process still adds
+ * up what every process saw.
+ */
 type Milestone = {
     kind: 'ask';
     ask: PendingAsk;
     timeoutMs?: number;
+    usage?: OpenCodeUsage;
 } | {
     kind: 'finished';
     outcome: TurnOutcome;
+    usage?: OpenCodeUsage;
 };
 interface OpenCodeTurnArgs {
     runId: string;
@@ -252,8 +297,19 @@ interface OpenCodeTurnArgs {
     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. */
+    /** The model label usage is recorded under until OpenCode names the step's model. */
     modelLabel: string;
+    /**
+     * What a model call cost: OpenCode's reported figure, or the library's estimate. Omit → OpenCode's
+     * figure as reported.
+     */
+    priceStep?: (step: {
+        model: StepModel | undefined;
+        usage: MessageUsage;
+        reportedCostUsd: number | undefined;
+    }) => Promise<StepCost>;
+    /** What the run spent before this turn object existed (an earlier process, an earlier session). */
+    carried?: OpenCodeUsage;
     logger: Logger;
     /**
      * An action OpenCode was allowed to run (a person approved it, or the policy did): the approval
@@ -296,8 +352,15 @@ declare class OpenCodeTurn {
     private readonly hidden;
     private readonly milestones;
     private waiting;
-    private readonly usage;
-    private costUsd;
+    /** What this turn object saw spent, and how much of it a milestone already reported. */
+    private spent;
+    private reported;
+    private priced;
+    private model;
+    /** What the session had spent when this turn prompted it; what OpenCode reported since. */
+    private baseline;
+    private readonly seen;
+    private compacted;
     private stepOpen;
     private sawText;
     private separator;
@@ -306,6 +369,18 @@ declare class OpenCodeTurn {
     private ended;
     private stepError;
     constructor(a: OpenCodeTurnArgs);
+    /**
+     * What the session had spent before this turn prompted it (`session.get`). When the execution
+     * ends, what the session spent since that this turn's events did not report — the title OpenCode
+     * generates, a compaction: OpenCode records those calls on the session without streaming them — is
+     * recorded as a usage row of its own.
+     */
+    setBaseline(info: {
+        cost?: number;
+        tokens?: OpenCodeTokens;
+    } | undefined): void;
+    /** What the run spent so far: carried from before this turn object, plus what it saw. */
+    totalUsage(): OpenCodeUsage;
     get sessionId(): string;
     get finished(): boolean;
     /** Feed one of the session's events. */
@@ -348,12 +423,19 @@ declare class OpenCodeTurn {
     private innerCalls;
     private onEvent;
     private settleTool;
+    private modelId;
+    /** One model call's usage and cost, into the ledger and the run's total. */
+    private spend;
+    /** `session.usage.recorded`: a call OpenCode made besides the steps (the title, a compaction). */
+    private usageRecorded;
     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;
+    /** The run's usage as its last message carries it: the whole run, cache tokens included. */
+    private messageUsage;
     /** 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. */
@@ -363,8 +445,16 @@ declare class OpenCodeTurn {
     private onForm;
     private answered;
     private addResult;
+    /** What the session spent since the baseline that no event of this turn reported. */
+    private unreported;
     private end;
 }
+/**
+ * OpenCode's token counts as the library's `MessageUsage`. OpenCode reports the uncached input in
+ * `input` and the cache reads and writes beside it; the library counts the whole input side in
+ * `inputTokens`, the cache counts being subsets of it.
+ */
+declare function usageOf(tokens: any): MessageUsage;
 
 /**
  * Where a turn runs and how its OpenCode session is set up — the part only the host knows. The
@@ -471,11 +561,12 @@ interface OpenCodeRunResult {
     text: string;
     /** The run's assistant messages, as stored. */
     messages: StoredMessage[];
-    usage: {
-        inputTokens: number;
-        outputTokens: number;
-        costUsd: number;
-    };
+    /**
+     * What the run spent, over every model call OpenCode made for it (its steps, the title, a
+     * compaction) and every process that ran a part of it. `inputTokens` counts cached input too;
+     * `cacheReadTokens`/`cacheWriteTokens` are subsets of it.
+     */
+    usage: OpenCodeUsage;
     durationMs: number;
 }
 /** See {@link OpenCodeHost.beforeSettle}. */
@@ -648,6 +739,19 @@ interface OpenCodeEngineSettings {
      * parked on a person is not observing: this bounds one stretch of OpenCode working on its own.
      */
     turnTimeoutMs?: 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):
+     *
+     * - `'reported'` (default) — OpenCode's figure when it has one (`cost_source` `'provider'`); a call
+     *   OpenCode priced at 0 (no price for the model) is estimated from the library's price instead
+     *   (`priceCatalog`, the pricing store, the built-in GovCloud Bedrock table, models.dev;
+     *   `cost_source` `'estimate'`).
+     * - `'estimate'` — the library's price whenever it has one, OpenCode's figure otherwise. For
+     *   models OpenCode prices at a list price that is not yours (Bedrock in GovCloud, a negotiated
+     *   rate) when you would rather not declare `cost` in OpenCode's config.
+     */
+    cost?: 'reported' | 'estimate';
 }
 /** A thread's session, as the steps of a turn pass it along (and a durable run journals it). */
 interface SessionHandle {
@@ -699,7 +803,20 @@ 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;
-    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);
+    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, pricingStore?: AgentPricingStore, agentOptions?: {
+        priceCatalog?: PriceCatalogOptions | false;
+    });
+    private readonly prices;
+    /**
+     * What a model call OpenCode made cost, by the same rule the library's loop records its own steps
+     * at: a reported figure wins, else an estimate off the model's price — see
+     * {@link OpenCodeEngineSettings.cost}.
+     */
+    priceStep(step: {
+        model: StepModel | undefined;
+        usage: MessageUsage;
+        reportedCostUsd: number | undefined;
+    }): Promise<StepCost>;
     /** The tools server's name in OpenCode. */
     get toolsServer(): string;
     /** The roles policy a turn's tools are gated by (the agent's own). */
@@ -784,20 +901,25 @@ declare class OpenCodeTurns implements OnApplicationShutdown {
      */
     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>;
+    prompt(runId: string, input: AgentRunInput, handle: SessionHandle, spent?: OpenCodeUsage): 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.
+     *
+     * `spent` is what the run spent before (the sum of the `usage` of its earlier milestones): a turn
+     * rebuilt here starts from it, so the answer it persists carries the whole run's usage.
      */
-    observe(runId: string, input: AgentRunInput, handle: SessionHandle): Promise<Milestone>;
+    observe(runId: string, input: AgentRunInput, handle: SessionHandle, spent?: OpenCodeUsage): 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>;
+    reply(runId: string, input: AgentRunInput, handle: SessionHandle, ask: PendingAsk, reply: HumanReply, spent?: OpenCodeUsage): Promise<SessionHandle>;
     private continueAfterRestart;
+    /** What a session spent so far (`session.get`), or nothing when OpenCode does not say. */
+    private sessionUsage;
     /** Interrupt the thread's session (cancel). */
     interrupt(input: AgentRunInput): Promise<void>;
     private ensureLive;
@@ -807,7 +929,11 @@ declare class OpenCodeTurns implements OnApplicationShutdown {
     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. */
+    /**
+     * What the run produced, as the host's settle hooks see it. `usage` is what the run spent — the
+     * runner's sum of its milestones' usage, which a resumed run reads back from its journal — else
+     * what the turn this process follows saw.
+     */
     private runResult;
     /**
      * The host's last word on the answer before the stream ends: components to append (a guardrail
@@ -816,9 +942,18 @@ declare class OpenCodeTurns implements OnApplicationShutdown {
     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>;
+    /**
+     * What the run spent: the runner's sum of its milestones, or what the turn this process follows
+     * saw (which starts from that sum) when it saw more — a run that failed or was cancelled between
+     * two milestones.
+     */
+    private spentBy;
+    /**
+     * 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>;
     /** 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. */
@@ -846,4 +981,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 { 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 };
+export { OpenCodeTurn as A, type OpenCodeTurnContext as B, type OpenCodeUsage as C, type StepCost as D, type StepModel as E, addUsage as F, emptyUsage as G, keyValueOpenCodeSessionStore as H, InMemoryOpenCodeSessionStore as I, openCode as J, openCodeControllers as K, openCodeProviders as L, type Milestone as M, usageOf as N, 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 };

package/dist/{engine-Bij6AdoF.d.ts → engine-0YkBLWZR.d.ts}

@@ -1,6 +1,6 @@
 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 { ElicitationRequest, CostSource, AgentRunInput, SinkWriter, AgentStore, ApprovalRequirement, MessageUsage, AgentUiComponent, HumanReply, Actor, StoredMessage, ToolRegistry, TokenStreamSink, SkillsConfig, MemoryConfig, AgentPricingStore, PriceCatalogOptions, RolesPolicy, RememberToolInput, AiToolCtx } from '@dudousxd/nestjs-agent-core';
 import { IncomingMessage, ServerResponse } from 'node:http';
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 
@@ -40,6 +40,9 @@ interface OpenCodeClient {
             metadata?: {
                 readonly [key: string]: OpenCodeJson;
             };
+            /** What the session spent so far, every model call OpenCode made for it (the title too). */
+            cost?: number;
+            tokens?: OpenCodeTokens;
         }>;
         /** Resolves when the session goes idle. Optional: a safety net for a missed terminal event. */
         wait?(args: {
@@ -204,6 +207,16 @@ interface OpenCodeFormField {
     /** The user may type their own answer instead of picking one of `options`. */
     custom?: boolean;
 }
+/** A token count as OpenCode reports it: `input` is the uncached input, the cache beside it. */
+interface OpenCodeTokens {
+    input: number;
+    output: number;
+    reasoning?: number;
+    cache?: {
+        read: number;
+        write: number;
+    };
+}
 
 /** How an OpenCode execution ended. */
 type TurnOutcome = {
@@ -234,14 +247,46 @@ type PendingAsk = {
     request: ElicitationRequest;
     messageId?: string;
 };
-/** Where a turn stands: it needs a person, or it is over. */
+/**
+ * What a turn spent. `inputTokens` is the whole input side, cached input included (as the library's
+ * `MessageUsage` counts it — OpenCode's own `tokens.input` leaves the cache out); `cacheReadTokens`,
+ * `cacheWriteTokens` and `reasoningTokens` are subsets. `costUsd` sums every priced call.
+ */
+interface OpenCodeUsage {
+    inputTokens: number;
+    outputTokens: number;
+    cacheReadTokens: number;
+    cacheWriteTokens: number;
+    reasoningTokens: number;
+    costUsd: number;
+}
+declare function emptyUsage(): OpenCodeUsage;
+/** `a + b`; a missing side (a milestone journaled before usage travelled) counts as nothing. */
+declare function addUsage(a: OpenCodeUsage | undefined, b: OpenCodeUsage | undefined): OpenCodeUsage;
+/** The model a step ran on, as OpenCode names it (`session.step.started`). */
+interface StepModel {
+    providerID: string;
+    id: string;
+}
+/** What a model call cost, and where the figure came from. */
+interface StepCost {
+    costUsd?: number;
+    costSource?: CostSource;
+}
+/**
+ * Where a turn stands: it needs a person, or it is over. `usage` is what the turn spent since its
+ * previous milestone — journaled with the milestone, so a run resumed in another process still adds
+ * up what every process saw.
+ */
 type Milestone = {
     kind: 'ask';
     ask: PendingAsk;
     timeoutMs?: number;
+    usage?: OpenCodeUsage;
 } | {
     kind: 'finished';
     outcome: TurnOutcome;
+    usage?: OpenCodeUsage;
 };
 interface OpenCodeTurnArgs {
     runId: string;
@@ -252,8 +297,19 @@ interface OpenCodeTurnArgs {
     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. */
+    /** The model label usage is recorded under until OpenCode names the step's model. */
     modelLabel: string;
+    /**
+     * What a model call cost: OpenCode's reported figure, or the library's estimate. Omit → OpenCode's
+     * figure as reported.
+     */
+    priceStep?: (step: {
+        model: StepModel | undefined;
+        usage: MessageUsage;
+        reportedCostUsd: number | undefined;
+    }) => Promise<StepCost>;
+    /** What the run spent before this turn object existed (an earlier process, an earlier session). */
+    carried?: OpenCodeUsage;
     logger: Logger;
     /**
      * An action OpenCode was allowed to run (a person approved it, or the policy did): the approval
@@ -296,8 +352,15 @@ declare class OpenCodeTurn {
     private readonly hidden;
     private readonly milestones;
     private waiting;
-    private readonly usage;
-    private costUsd;
+    /** What this turn object saw spent, and how much of it a milestone already reported. */
+    private spent;
+    private reported;
+    private priced;
+    private model;
+    /** What the session had spent when this turn prompted it; what OpenCode reported since. */
+    private baseline;
+    private readonly seen;
+    private compacted;
     private stepOpen;
     private sawText;
     private separator;
@@ -306,6 +369,18 @@ declare class OpenCodeTurn {
     private ended;
     private stepError;
     constructor(a: OpenCodeTurnArgs);
+    /**
+     * What the session had spent before this turn prompted it (`session.get`). When the execution
+     * ends, what the session spent since that this turn's events did not report — the title OpenCode
+     * generates, a compaction: OpenCode records those calls on the session without streaming them — is
+     * recorded as a usage row of its own.
+     */
+    setBaseline(info: {
+        cost?: number;
+        tokens?: OpenCodeTokens;
+    } | undefined): void;
+    /** What the run spent so far: carried from before this turn object, plus what it saw. */
+    totalUsage(): OpenCodeUsage;
     get sessionId(): string;
     get finished(): boolean;
     /** Feed one of the session's events. */
@@ -348,12 +423,19 @@ declare class OpenCodeTurn {
     private innerCalls;
     private onEvent;
     private settleTool;
+    private modelId;
+    /** One model call's usage and cost, into the ledger and the run's total. */
+    private spend;
+    /** `session.usage.recorded`: a call OpenCode made besides the steps (the title, a compaction). */
+    private usageRecorded;
     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;
+    /** The run's usage as its last message carries it: the whole run, cache tokens included. */
+    private messageUsage;
     /** 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. */
@@ -363,8 +445,16 @@ declare class OpenCodeTurn {
     private onForm;
     private answered;
     private addResult;
+    /** What the session spent since the baseline that no event of this turn reported. */
+    private unreported;
     private end;
 }
+/**
+ * OpenCode's token counts as the library's `MessageUsage`. OpenCode reports the uncached input in
+ * `input` and the cache reads and writes beside it; the library counts the whole input side in
+ * `inputTokens`, the cache counts being subsets of it.
+ */
+declare function usageOf(tokens: any): MessageUsage;
 
 /**
  * Where a turn runs and how its OpenCode session is set up — the part only the host knows. The
@@ -471,11 +561,12 @@ interface OpenCodeRunResult {
     text: string;
     /** The run's assistant messages, as stored. */
     messages: StoredMessage[];
-    usage: {
-        inputTokens: number;
-        outputTokens: number;
-        costUsd: number;
-    };
+    /**
+     * What the run spent, over every model call OpenCode made for it (its steps, the title, a
+     * compaction) and every process that ran a part of it. `inputTokens` counts cached input too;
+     * `cacheReadTokens`/`cacheWriteTokens` are subsets of it.
+     */
+    usage: OpenCodeUsage;
     durationMs: number;
 }
 /** See {@link OpenCodeHost.beforeSettle}. */
@@ -648,6 +739,19 @@ interface OpenCodeEngineSettings {
      * parked on a person is not observing: this bounds one stretch of OpenCode working on its own.
      */
     turnTimeoutMs?: 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):
+     *
+     * - `'reported'` (default) — OpenCode's figure when it has one (`cost_source` `'provider'`); a call
+     *   OpenCode priced at 0 (no price for the model) is estimated from the library's price instead
+     *   (`priceCatalog`, the pricing store, the built-in GovCloud Bedrock table, models.dev;
+     *   `cost_source` `'estimate'`).
+     * - `'estimate'` — the library's price whenever it has one, OpenCode's figure otherwise. For
+     *   models OpenCode prices at a list price that is not yours (Bedrock in GovCloud, a negotiated
+     *   rate) when you would rather not declare `cost` in OpenCode's config.
+     */
+    cost?: 'reported' | 'estimate';
 }
 /** A thread's session, as the steps of a turn pass it along (and a durable run journals it). */
 interface SessionHandle {
@@ -699,7 +803,20 @@ 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;
-    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);
+    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, pricingStore?: AgentPricingStore, agentOptions?: {
+        priceCatalog?: PriceCatalogOptions | false;
+    });
+    private readonly prices;
+    /**
+     * What a model call OpenCode made cost, by the same rule the library's loop records its own steps
+     * at: a reported figure wins, else an estimate off the model's price — see
+     * {@link OpenCodeEngineSettings.cost}.
+     */
+    priceStep(step: {
+        model: StepModel | undefined;
+        usage: MessageUsage;
+        reportedCostUsd: number | undefined;
+    }): Promise<StepCost>;
     /** The tools server's name in OpenCode. */
     get toolsServer(): string;
     /** The roles policy a turn's tools are gated by (the agent's own). */
@@ -784,20 +901,25 @@ declare class OpenCodeTurns implements OnApplicationShutdown {
      */
     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>;
+    prompt(runId: string, input: AgentRunInput, handle: SessionHandle, spent?: OpenCodeUsage): 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.
+     *
+     * `spent` is what the run spent before (the sum of the `usage` of its earlier milestones): a turn
+     * rebuilt here starts from it, so the answer it persists carries the whole run's usage.
      */
-    observe(runId: string, input: AgentRunInput, handle: SessionHandle): Promise<Milestone>;
+    observe(runId: string, input: AgentRunInput, handle: SessionHandle, spent?: OpenCodeUsage): 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>;
+    reply(runId: string, input: AgentRunInput, handle: SessionHandle, ask: PendingAsk, reply: HumanReply, spent?: OpenCodeUsage): Promise<SessionHandle>;
     private continueAfterRestart;
+    /** What a session spent so far (`session.get`), or nothing when OpenCode does not say. */
+    private sessionUsage;
     /** Interrupt the thread's session (cancel). */
     interrupt(input: AgentRunInput): Promise<void>;
     private ensureLive;
@@ -807,7 +929,11 @@ declare class OpenCodeTurns implements OnApplicationShutdown {
     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. */
+    /**
+     * What the run produced, as the host's settle hooks see it. `usage` is what the run spent — the
+     * runner's sum of its milestones' usage, which a resumed run reads back from its journal — else
+     * what the turn this process follows saw.
+     */
     private runResult;
     /**
      * The host's last word on the answer before the stream ends: components to append (a guardrail
@@ -816,9 +942,18 @@ declare class OpenCodeTurns implements OnApplicationShutdown {
     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>;
+    /**
+     * What the run spent: the runner's sum of its milestones, or what the turn this process follows
+     * saw (which starts from that sum) when it saw more — a run that failed or was cancelled between
+     * two milestones.
+     */
+    private spentBy;
+    /**
+     * 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>;
     /** 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. */
@@ -846,4 +981,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 { 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 };
+export { OpenCodeTurn as A, type OpenCodeTurnContext as B, type OpenCodeUsage as C, type StepCost as D, type StepModel as E, addUsage as F, emptyUsage as G, keyValueOpenCodeSessionStore as H, InMemoryOpenCodeSessionStore as I, openCode as J, openCodeControllers as K, openCodeProviders as L, type Milestone as M, usageOf as N, 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 };