@sema-agent/core 5.61.0 → 5.62.0

package/dist/core/usage-window-store.d.ts

@@ -13,9 +13,9 @@
  * backends equivalent by construction rather than by two hand-written copies that drift.
  */
 /**
- * One governed window. Both fields are allowances, not hints: `windowMs` is the window's WIDTH and
- * `maxTokens` the tokens it admits. `anchor` picks between the two window shapes that actually exist in
- * the wild:
+ * One governed window. Its fields are allowances, not hints: `windowMs` is the window's WIDTH and
+ * `maxTokens` / `maxCostUsd` the two CEILINGS it admits work under. `anchor` picks between the two window
+ * shapes that actually exist in the wild:
  *  - `"first-use"` — the window OPENS at the key's first charge and lasts `windowMs`; when it lapses with
  *    no further use, the next charge opens a fresh one. This is the "5 hours from when you started"
  *    shape: bursty use is admitted at full width, and an idle key is never penalized for old traffic.
@@ -29,6 +29,28 @@ export interface UsageWindow {
     /** Tokens the window admits before it is exhausted. Must be finite and >= 0; `0` is a real, always-full
      *  window (an operator lock-out), not "unset". */
     maxTokens: number;
+    /**
+     * OPTIONAL second ceiling: the MONEY the window admits before it is exhausted, in absolute USD — the
+     * same quantity and unit `TaskLimits.maxCostUsd` names, one governance level up (a task's own allowance
+     * vs the allowance an operator grants a principal across tasks). Must be finite and >= 0; `0` is a real,
+     * always-full window, exactly as it is for `maxTokens`.
+     *
+     * The two ceilings are INDEPENDENT and both bind: a window is exhausted when EITHER its tokens reach
+     * `maxTokens` or its cost reaches `maxCostUsd` — whichever fills first. Absent (the default, and every
+     * pre-existing deployment) means THIS window governs tokens only — its own reading never asks for or
+     * enforces a cost. Whether cost is tracked/recorded at all is a DEPLOYMENT-level fact, not a
+     * per-window one (the `UsageSlot.costMicroUsd` / `UsageBucketRow` in-presence condition: "while the
+     * deployment governs at least one `maxCostUsd` window"): in a MIXED declaration the shared ledger
+     * rows carry cost under every window's bucket, and only a deployment with NO $ window anywhere keeps
+     * its rows byte-identical to the pre-cost-arm shape.
+     *
+     * **Requires a PRICED run.** Cost is not a number the engine can invent: a run whose model has neither a
+     * `RunnerDeps.pricing` entry nor a `Model.cost` declaration produces NO cost figure at all (not a zero),
+     * so a $ ceiling over it is unevaluable and the task is refused at the door
+     * (`config.usage_window_unpriced`) rather than charged a fabricated 0 that would let the ceiling
+     * silently stop applying.
+     */
+    maxCostUsd?: number;
     /** Which of the two window shapes above this is. */
     anchor: "first-use" | "rolling";
 }
@@ -36,6 +58,19 @@ export interface UsageWindow {
 export interface UsageSlot {
     at: number;
     tokens: number;
+    /** The charge's cost in integer micro-USD. **In-presence condition:** written only while the deployment
+     *  governs at least one {@link UsageWindow.maxCostUsd} window AND the charge had a cost figure at all — a
+     *  token-only deployment's ledger rows are byte-for-byte what they were before the cost arm existed, and
+     *  so is the row for spend nothing could price. Absent therefore reads as "no money recorded here": a row
+     *  written BEFORE a $ window was declared, or one whose model had no price table, contributes 0 to the
+     *  money lane rather than back-dating a number nobody recorded. */
+    costMicroUsd?: number;
+    /** This charge's spend could NOT be priced (see {@link UsageWindowStore.charge}'s `null` arm).
+     *  **In-presence condition:** only ever `true`, only on a row written while a $ window was governed and
+     *  nothing could price the spend. It is what keeps "no money here" apart from "no money spent here": a
+     *  window holding one of these reports a money figure that is a LOWER BOUND, and says so
+     *  ({@link UsageWindowReading.costUnknown}). */
+    costUnknown?: true;
 }
 /** The OPEN first-use window for one `windowMs` on one key. Rows for other widths coexist, so a
  *  deployment governing 5h and 7d windows keeps one row per width rather than one blended counter. */
@@ -46,6 +81,11 @@ export interface UsageBucketRow {
     openedAt: number;
     /** Tokens charged into it since it opened. */
     tokens: number;
+    /** Integer micro-USD charged into it since it opened. Same in-presence condition as {@link UsageSlot.costMicroUsd}. */
+    costMicroUsd?: number;
+    /** Some spend in this open window could not be priced. Same meaning and in-presence condition as
+     *  {@link UsageSlot.costUnknown}; sticky for the life of the open bucket. */
+    costUnknown?: true;
 }
 /** Everything one key's governance state consists of: the rolling lane's slots and the first-use lane's
  *  open buckets. Persisted verbatim by every backend (plain JSON, no methods). */
@@ -59,7 +99,20 @@ export interface UsageWindowReading {
     window: UsageWindow;
     /** Tokens the window currently holds. */
     tokens: number;
-    /** `tokens >= window.maxTokens` — the window admits no further work. */
+    /** Integer micro-USD the window currently holds. **In-presence condition:** present exactly when
+     *  `window.maxCostUsd !== undefined` — a reading for a token-only window is byte-identical to what it
+     *  was before the cost arm existed, and a MISSING value on a $ window means the store did not evaluate
+     *  the ceiling at all (refused loudly by {@link usageRetryAfterMs}, never read as an open ceiling). */
+    costMicroUsd?: number;
+    /** The window holds spend nothing could price, so `costMicroUsd` is a LOWER BOUND rather than the total.
+     *  **In-presence condition:** only ever `true`, and only on a window that declares `maxCostUsd`. The
+     *  ceiling still binds on what IS countable (an under-count can only postpone exhaustion, never invent
+     *  it), and the engine announces the gap on every run that reads it — the alternative, treating the
+     *  whole window as exhausted until the unpriced charge ages out, would lock a key out for as long as
+     *  `windowMs` over one degraded turn, which is a larger outage than the gap it answers. */
+    costUnknown?: true;
+    /** The window admits no further work: `tokens >= window.maxTokens`, OR (when the window declares one)
+     *  `costMicroUsd >= window.maxCostUsd` — the two ceilings are independent and either one binds. */
     exhausted: boolean;
     /** Ms until this window next frees capacity: for `first-use`, when the open window lapses; for
      *  `rolling`, when its OLDEST in-window slot ages out (which frees that slot's tokens, not
@@ -82,8 +135,19 @@ export interface UsageWindowStore {
      * needs it to know which first-use buckets to keep open and how far back the rolling lane must
      * remember, so the ledger stays bounded instead of growing for the life of the deployment.
      * Called once per accounting point; never with a negative or non-finite `tokens`.
+     *
+     * `costMicroUsd` is the same charge's MONEY, in integer micro-USD, or `null` when the spend is real but
+     * NOTHING could price it. **In-presence condition:** one of the two is supplied exactly when the
+     * deployment governs at least one {@link UsageWindow.maxCostUsd} window — a token-only deployment is
+     * called with the pre-cost-arm argument list and must behave identically.
+     *
+     * A store that governs $ windows MUST FORWARD it (into `chargeUsageRecord`, or into its own equivalent)
+     * and answer {@link UsageWindowReading.costMicroUsd} from what it persisted. A decorator written against
+     * the pre-cost-arm signature drops the argument silently — which is why the arithmetic refuses an absent
+     * cost outright (`usage_window.store_cost_unanswered`) instead of folding it to a 0 that would leave the
+     * money ceiling open forever with nothing able to notice.
      */
-    charge(key: string, tokens: number, at: number, windows: readonly UsageWindow[]): Promise<void>;
+    charge(key: string, tokens: number, at: number, windows: readonly UsageWindow[], costMicroUsd?: number | null): Promise<void>;
     /** Read `key`'s state for each window as of `now`, in the order the windows were given. */
     read(key: string, windows: readonly UsageWindow[], now: number): Promise<readonly UsageWindowReading[]>;
 }
@@ -99,6 +163,10 @@ export declare const EMPTY_USAGE_WINDOW_RECORD: UsageWindowRecord;
  * would govern a deployment by a number nobody chose. Refuses with `config.usage_window_invalid`.
  */
 export declare function resolveUsageWindows(windows: readonly UsageWindow[] | undefined): readonly UsageWindow[] | undefined;
+/** Does the deployment govern MONEY at all? The one predicate that decides whether a cost figure is asked
+ *  of the engine, written into the ledger, or answered in a reading — so a token-only deployment stays
+ *  byte-for-byte what it was before the cost arm existed. */
+export declare function windowsGovernCost(windows: readonly UsageWindow[]): boolean;
 /**
  * Fold one charge into a key's record and return the NEW record (pure — the input is never mutated, so a
  * store that keeps records in a Map cannot be corrupted by a half-applied charge).
@@ -107,8 +175,23 @@ export declare function resolveUsageWindows(windows: readonly UsageWindow[] | un
  * can never be read again, and a first-use bucket for a width the deployment no longer governs can never
  * be read again either, so both are dropped here. A record therefore stays bounded by (charges within the
  * widest rolling window) + (one row per governed first-use width).
+ *
+ * `costMicroUsd` rides the same fold as `tokens` (integer micro-USD, never a float USD: the ledger sums
+ * thousands of charges and a float would accumulate error into a money ceiling), and it is a THREE-state
+ * argument while the deployment governs a $ window:
+ *  - a NUMBER — the charge's cost, folded into the money lane;
+ *  - `null` — the tokens are known but their cost is NOT (an unpriced model served the spend). The row is
+ *    written with its tokens and NO cost field: the token ceiling stays exact, and the money lane counts
+ *    nothing rather than a fabricated 0. The engine refuses such a run anyway — this keeps the ledger
+ *    honest about the spend that already happened before the refusal;
+ *  - `undefined` — REFUSED. Core always supplies one of the two above when a $ window is governed, so an
+ *    absent argument means some store in the chain (a pre-cost-arm decorator, most likely) dropped it, and
+ *    folding it to 0 would leave the money ceiling permanently open with nothing able to detect it.
+ * With NO $ window governed the argument is ignored entirely and rows keep their pre-cost-arm bytes.
+ * Rows that already carry a cost keep it, so removing and re-adding a $ window neither loses the history
+ * nor rewrites rows that predate it.
  */
-export declare function chargeUsageRecord(record: UsageWindowRecord, tokens: number, at: number, windows: readonly UsageWindow[]): UsageWindowRecord;
+export declare function chargeUsageRecord(record: UsageWindowRecord, tokens: number, at: number, windows: readonly UsageWindow[], costMicroUsd?: number | null): UsageWindowRecord;
 /**
  * Read a key's record against the governed windows as of `now` (pure). The `first-use` lane reads the open
  * bucket; the `rolling` lane sums the slots inside `(now − windowMs, now]`.
@@ -119,8 +202,26 @@ export declare function readUsageRecord(record: UsageWindowRecord, windows: read
  * window would admit work again. `undefined` when nothing is exhausted. The MAXIMUM (not the minimum) of
  * the exhausted windows' hints — resuming when the shortest one clears would immediately re-suspend on
  * the longer one.
+ *
+ * It is also the ONE choke point every governance read in the engine goes through, so the integrity
+ * checks live here, in two arms:
+ *  - **coverage** (when the caller supplies the declared `windows`): one reading per declared window,
+ *    in the order the windows were given, with the window echoed verbatim on the fields that name the
+ *    allowance (`windowMs`/`anchor`/`maxTokens`/`maxCostUsd`). The per-reading arm below is
+ *    structurally blind to a reading that is MISSING — a decorator store that maps only the windows
+ *    it recognizes, reorders the answer, or echoes a normalized copy with `maxCostUsd` stripped would
+ *    otherwise un-govern a declared ceiling with zero symptoms. Every engine read passes its windows
+ *    through; the parameter stays optional so a bare-readings caller keeps the pre-coverage face.
+ *  - **per-reading**: a reading for a window that DECLARES `maxCostUsd` while carrying no
+ *    `costMicroUsd` means the store never evaluated the money ceiling — its `exhausted` verdict then
+ *    covers the token axis alone.
+ * Both arms refuse with ONE code (`usage_window.store_cost_unanswered`) rather than read as an open
+ * ceiling — an unanswered window and an answered-without-cost window are the same fact ("the store
+ * never proved it evaluated the declared ceiling"): a governance ceiling that silently stops applying
+ * is worse than one that never existed, which is the same posture the file backend takes when its
+ * ledger is unreadable.
  */
-export declare function usageRetryAfterMs(readings: readonly UsageWindowReading[]): number | undefined;
+export declare function usageRetryAfterMs(readings: readonly UsageWindowReading[], windows?: readonly UsageWindow[]): number | undefined;
 /**
  * Process-local {@link UsageWindowStore} reference implementation. Governs correctly within ONE Runner
  * process and loses its ledger on restart — the right choice for tests and single-process deployments,
@@ -129,6 +230,6 @@ export declare function usageRetryAfterMs(readings: readonly UsageWindowReading[
  */
 export declare class InMemoryUsageWindowStore implements UsageWindowStore {
     private readonly records;
-    charge(key: string, tokens: number, at: number, windows: readonly UsageWindow[]): Promise<void>;
+    charge(key: string, tokens: number, at: number, windows: readonly UsageWindow[], costMicroUsd?: number | null): Promise<void>;
     read(key: string, windows: readonly UsageWindow[], now: number): Promise<readonly UsageWindowReading[]>;
 }

package/dist/core/usage-window-store.js

@@ -24,6 +24,9 @@ export function resolveUsageWindows(windows) {
         if (typeof w.maxTokens !== "number" || !Number.isFinite(w.maxTokens) || w.maxTokens < 0) {
             throw usageConfigError("config.usage_window_invalid", `RunnerDeps.usageWindows[].maxTokens must be a finite, non-negative number (got ${String(w.maxTokens)})`);
         }
+        if (w.maxCostUsd !== undefined && (typeof w.maxCostUsd !== "number" || !Number.isFinite(w.maxCostUsd) || w.maxCostUsd < 0)) {
+            throw usageConfigError("config.usage_window_invalid", `RunnerDeps.usageWindows[].maxCostUsd must be a finite, non-negative number of USD when present (got ${String(w.maxCostUsd)})`);
+        }
         if (w.anchor !== "first-use" && w.anchor !== "rolling") {
             throw usageConfigError("config.usage_window_invalid", `RunnerDeps.usageWindows[].anchor must be "first-use" or "rolling" (got ${String(w.anchor)})`);
         }
@@ -40,11 +43,34 @@ function rollingHorizonMs(windows) {
     }
     return widest;
 }
-export function chargeUsageRecord(record, tokens, at, windows) {
+export function windowsGovernCost(windows) {
+    return windows.some((w) => w.maxCostUsd !== undefined);
+}
+function maxCostMicroUsdOf(w) {
+    return w.maxCostUsd === undefined ? undefined : Math.ceil(Number((w.maxCostUsd * 1e6).toPrecision(12)));
+}
+export function chargeUsageRecord(record, tokens, at, windows, costMicroUsd) {
     const horizon = rollingHorizonMs(windows);
-    const keptSlots = horizon === undefined ? [] : record.slots.filter((s) => s.at > at - horizon).map((s) => ({ at: s.at, tokens: s.tokens }));
-    if (horizon !== undefined && tokens > 0)
-        keptSlots.push({ at, tokens });
+    const governsCost = windowsGovernCost(windows);
+    if (governsCost && costMicroUsd === undefined) {
+        throw usageConfigError("usage_window.store_cost_unanswered", "a usage-window CHARGE for a deployment that governs maxCostUsd arrived with no cost figure at all. Core supplies one (a number, or an explicit null for spend nothing could price) on every such charge, so an absent one means a store in the chain does not carry the cost argument — folding it to 0 would leave the money ceiling open forever with nothing able to notice. Forward `costMicroUsd` from `UsageWindowStore.charge` into `chargeUsageRecord`.");
+    }
+    const cost = governsCost && costMicroUsd !== null ? costMicroUsd : undefined;
+    const unknown = governsCost && costMicroUsd === null;
+    const moves = tokens > 0 || (cost !== undefined && cost > 0) || unknown;
+    const keptSlots = horizon === undefined
+        ? []
+        : record.slots
+            .filter((s) => s.at > at - horizon)
+            .map((s) => ({
+            at: s.at,
+            tokens: s.tokens,
+            ...(s.costMicroUsd === undefined ? {} : { costMicroUsd: s.costMicroUsd }),
+            ...(s.costUnknown === true ? { costUnknown: true } : {}),
+        }));
+    if (horizon !== undefined && moves) {
+        keptSlots.push({ at, tokens, ...(cost === undefined ? {} : { costMicroUsd: cost }), ...(unknown ? { costUnknown: true } : {}) });
+    }
     const buckets = [];
     for (const w of windows) {
         if (w.anchor !== "first-use")
@@ -54,11 +80,21 @@ export function chargeUsageRecord(record, tokens, at, windows) {
         const prior = record.buckets.find((b) => b.windowMs === w.windowMs);
         const lapsed = prior === undefined || at >= prior.openedAt + w.windowMs;
         if (lapsed) {
-            if (tokens > 0)
-                buckets.push({ windowMs: w.windowMs, openedAt: at, tokens });
+            if (moves) {
+                buckets.push({ windowMs: w.windowMs, openedAt: at, tokens, ...(cost === undefined ? {} : { costMicroUsd: cost }), ...(unknown ? { costUnknown: true } : {}) });
+            }
             continue;
         }
-        buckets.push({ windowMs: w.windowMs, openedAt: prior.openedAt, tokens: prior.tokens + tokens });
+        const priorCost = prior.costMicroUsd;
+        const nextCost = cost === undefined ? priorCost : (priorCost ?? 0) + cost;
+        const nextUnknown = unknown || prior.costUnknown === true;
+        buckets.push({
+            windowMs: w.windowMs,
+            openedAt: prior.openedAt,
+            tokens: prior.tokens + tokens,
+            ...(nextCost === undefined ? {} : { costMicroUsd: nextCost }),
+            ...(nextUnknown ? { costUnknown: true } : {}),
+        });
     }
     return { slots: keptSlots, buckets };
 }
@@ -66,6 +102,8 @@ export function readUsageRecord(record, windows, now) {
     const readings = [];
     for (const w of windows) {
         let tokens = 0;
+        let costMicroUsd = 0;
+        let costUnknown = false;
         let freesAt;
         if (w.anchor === "rolling") {
             const floor = now - w.windowMs;
@@ -74,6 +112,9 @@ export function readUsageRecord(record, windows, now) {
                 if (s.at <= floor)
                     continue;
                 tokens += s.tokens;
+                costMicroUsd += s.costMicroUsd ?? 0;
+                if (s.costUnknown === true)
+                    costUnknown = true;
                 if (oldest === undefined || s.at < oldest)
                     oldest = s.at;
             }
@@ -84,18 +125,44 @@ export function readUsageRecord(record, windows, now) {
             const row = record.buckets.find((b) => b.windowMs === w.windowMs);
             if (row !== undefined && now < row.openedAt + w.windowMs) {
                 tokens = row.tokens;
+                costMicroUsd = row.costMicroUsd ?? 0;
+                if (row.costUnknown === true)
+                    costUnknown = true;
                 freesAt = row.openedAt + w.windowMs;
             }
         }
-        const exhausted = tokens >= w.maxTokens;
+        const maxCostMicroUsd = maxCostMicroUsdOf(w);
+        const exhausted = tokens >= w.maxTokens || (maxCostMicroUsd !== undefined && costMicroUsd >= maxCostMicroUsd);
         const retryAfterMs = exhausted ? Math.max(1, freesAt === undefined ? w.windowMs : freesAt - now) : 0;
-        readings.push({ window: w, tokens, exhausted, retryAfterMs });
+        readings.push({
+            window: w,
+            tokens,
+            ...(maxCostMicroUsd !== undefined ? { costMicroUsd } : {}),
+            ...(maxCostMicroUsd !== undefined && costUnknown ? { costUnknown: true } : {}),
+            exhausted,
+            retryAfterMs,
+        });
     }
     return readings;
 }
-export function usageRetryAfterMs(readings) {
+export function usageRetryAfterMs(readings, windows) {
+    if (windows !== undefined) {
+        if (readings.length !== windows.length) {
+            throw usageConfigError("usage_window.store_cost_unanswered", `the usage-window ledger answered ${String(readings.length)} reading(s) for ${String(windows.length)} declared window(s) — the read contract is one reading per window, in the order given. A window with no reading was never evaluated: refused rather than treated as open.`);
+        }
+        for (let i = 0; i < windows.length; i++) {
+            const w = windows[i];
+            const echoed = readings[i].window;
+            if (echoed === undefined || echoed.windowMs !== w.windowMs || echoed.anchor !== w.anchor || echoed.maxTokens !== w.maxTokens || echoed.maxCostUsd !== w.maxCostUsd) {
+                throw usageConfigError("usage_window.store_cost_unanswered", `the usage-window ledger's reading #${String(i)} does not echo declared window #${String(i)} verbatim (declared: windowMs ${String(w.windowMs)}, ${String(w.anchor)}, maxTokens ${String(w.maxTokens)}, maxCostUsd ${String(w.maxCostUsd)}) — the read contract requires the window back verbatim, in order, so its ceilings are provably the ones evaluated. Refused rather than re-attributed.`);
+            }
+        }
+    }
     let worst;
     for (const r of readings) {
+        if (r.window?.maxCostUsd !== undefined && r.costMicroUsd === undefined) {
+            throw usageConfigError("usage_window.store_cost_unanswered", `the usage-window ledger answered a window that declares maxCostUsd ${String(r.window.maxCostUsd)} (windowMs ${String(r.window.windowMs)}, ${String(r.window.anchor)}) with NO costMicroUsd — the money ceiling was never evaluated. Refused rather than treated as open: the store must persist the cost charged to it and report what the window holds.`);
+        }
         if (!r.exhausted)
             continue;
         if (worst === undefined || r.retryAfterMs > worst)
@@ -105,9 +172,9 @@ export function usageRetryAfterMs(readings) {
 }
 export class InMemoryUsageWindowStore {
     records = new Map();
-    async charge(key, tokens, at, windows) {
+    async charge(key, tokens, at, windows, costMicroUsd) {
         const prior = this.records.get(key) ?? EMPTY_USAGE_WINDOW_RECORD;
-        this.records.set(key, chargeUsageRecord(prior, tokens, at, windows));
+        this.records.set(key, chargeUsageRecord(prior, tokens, at, windows, costMicroUsd));
     }
     async read(key, windows, now) {
         return readUsageRecord(this.records.get(key) ?? EMPTY_USAGE_WINDOW_RECORD, windows, now);

package/dist/orchestration/run-workflow-tool.d.ts

@@ -278,8 +278,8 @@ export interface RunWorkflowToolDeps {
      *  (`RunnerDeps.onAsk`, else the fail-closed headless auto-deny). */
     parentOnAsk?: import("../core/tool-policy.js").OnAsk;
     /** The HOST run's display sink (its `RunInternals.onForwardEvent` behind the runner's ctx wrapper:
-     *  `task_progress` always, plus the children's content events — `text_delta`/`reasoning_delta`/
-     *  `tool_start`/`tool_end`, UNTRUSTED-RAW: the consumer must redact — when the HOST spec set
+     *  `task_progress` always, plus the children's content events — `text_delta`/`text_end`/
+     *  `reasoning_delta`/`tool_start`/`tool_end`, UNTRUSTED-RAW: the consumer must redact — when the HOST spec set
      *  `forwardSubagentEvents: true`) — threaded via `startWorkflow` into every spawned agent's trusted
      *  internals so a workflow child's events bubble to the deployment's one sink, the same
      *  channel a `createSubagentTool` delegation threads. Display-only; absent ⇒ ticks stay in each

package/dist/orchestration/workflow.d.ts

@@ -384,8 +384,8 @@ export interface RunWorkflowOptions {
     parentCenterArtifactDigest?: string;
     parentCenterSourceRevision?: string;
     /** The launching run's display sink (`RunInternals.onForwardEvent` behind the runner's ctx wrapper:
-     *  `task_progress` always, PLUS the children's content events — `text_delta`/`reasoning_delta`/
-     *  `tool_start`/`tool_end`, UNTRUSTED-RAW: the consumer must redact — when the HOST spec set
+     *  `task_progress` always, PLUS the children's content events — `text_delta`/`text_end`/
+     *  `reasoning_delta`/`tool_start`/`tool_end`, UNTRUSTED-RAW: the consumer must redact — when the HOST spec set
      *  `forwardSubagentEvents: true`) — threaded into every spawned agent's trusted internals so the
      *  children's events bubble out of their isolated streams to the deployment's one sink (fleet
      *  footer/monitor rows). Display-only; absent ⇒ ticks stay in each child's own stream. */

package/dist/prompt-assembly/event-registry.js

@@ -1,12 +1,14 @@
 export const EVENT_PROMPT_REGISTRY = new Map([
     { kind: "todo_reminder", carrier: "message.user-prefix", trust: "operator", dedupe: "replace-by-key", defaultPolicy: "off", rendererRef: "turn-attachments.ts#TODO_REMINDER_BASE" },
     { kind: "task_reminder", carrier: "message.user-prefix", trust: "operator", dedupe: "replace-by-key", defaultPolicy: "off", rendererRef: "turn-attachments.ts#TASK_REMINDER_BASE" },
+    { kind: "tool_search_usage_reminder", carrier: "message.user-prefix", trust: "operator", dedupe: "replace-by-key", defaultPolicy: "off", rendererRef: "turn-attachments.ts#renderToolSearchUsageReminder" },
     { kind: "changed_files", carrier: "message.user-prefix", trust: "operator", dedupe: "replace-by-key", defaultPolicy: "off", rendererRef: "turn-attachments.ts#renderChangedFiles" },
     { kind: "plan_mode", carrier: "message.user-prefix", trust: "operator", dedupe: "replace-by-key", defaultPolicy: "off", rendererRef: "turn-attachments.ts#PLAN_MODE_FULL_BODY" },
     { kind: "date_change", carrier: "message.user-prefix", trust: "operator", dedupe: "replace-by-key", defaultPolicy: "always", rendererRef: "turn-attachments.ts#renderDateChange" },
     { kind: "instructions_change", carrier: "message.user-prefix", trust: "operator", dedupe: "replace-by-key", maxBytes: 512, defaultPolicy: "always", rendererRef: "turn-attachments.ts#collectInstructionsChange" },
     { kind: "workflow_size_guideline_change", carrier: "message.user-prefix", trust: "operator", dedupe: "replace-by-key", defaultPolicy: "always", rendererRef: "runtask.ts#workflowSizeGuidelineChangeNotice" },
     { kind: "budget_usd", carrier: "message.user-prefix", trust: "operator", dedupe: "replace-by-key", defaultPolicy: "off", rendererRef: "turn-attachments.ts#renderBudgetUsd" },
+    { kind: "total_tokens_reminder", carrier: "message.user-prefix", trust: "operator", dedupe: "replace-by-key", defaultPolicy: "off", rendererRef: "turn-attachments.ts#renderTotalTokensReminder" },
     { kind: "background_tasks", carrier: "message.user-prefix", trust: "operator", dedupe: "replace-by-key", defaultPolicy: "on", rendererRef: "turn-attachments.ts#renderBackgroundTasks" },
     { kind: "tools_delta", carrier: "message.user-prefix", trust: "external", dedupe: "replace-by-key", defaultPolicy: "off", rendererRef: "turn-attachments.ts#renderToolsDelta" },
     { kind: "agent_listing", carrier: "message.user-prefix", trust: "operator", dedupe: "replace-by-key", defaultPolicy: "on", rendererRef: "turn-attachments.ts#renderAgentListingDelta" },

package/dist/server/http.d.ts

@@ -27,7 +27,7 @@ export interface TaskServerOptions {
 /**
  * Create an HTTP server exposing the runner over two endpoints:
  *   POST /task          → run to completion, returns TaskResult JSON
- *   POST /task/stream   → Server-Sent Events of TaskEvent (text_delta / reasoning_delta / tool_* / done)
+ *   POST /task/stream   → Server-Sent Events of TaskEvent (text_delta / text_end / reasoning_delta / tool_* / done)
  *
  * The request body provides { objective, sessionId?, images? }; `resolveSpec` supplies the rest
  * (model, tools, mcp, systemPrompt, limits) server-side.

package/dist/stores/file/usage-window-store.d.ts

@@ -22,6 +22,6 @@ export declare class FileUsageWindowStore implements UsageWindowStore {
      *  distinct principals can never share a ledger file). */
     private pathFor;
     private loadRecord;
-    charge(key: string, tokens: number, at: number, windows: readonly UsageWindow[]): Promise<void>;
+    charge(key: string, tokens: number, at: number, windows: readonly UsageWindow[], costMicroUsd?: number | null): Promise<void>;
     read(key: string, windows: readonly UsageWindow[], now: number): Promise<readonly UsageWindowReading[]>;
 }

package/dist/stores/file/usage-window-store.js

@@ -38,8 +38,8 @@ export class FileUsageWindowStore {
         const buckets = validateBuckets(rec.buckets, path);
         return { slots, buckets };
     }
-    async charge(key, tokens, at, windows) {
-        const next = chargeUsageRecord(this.loadRecord(key), tokens, at, windows);
+    async charge(key, tokens, at, windows, costMicroUsd) {
+        const next = chargeUsageRecord(this.loadRecord(key), tokens, at, windows, costMicroUsd);
         atomicWriteFile(join(this.dir, "tmp"), this.pathFor(key), JSON.stringify(next));
     }
     async read(key, windows, now) {
@@ -59,11 +59,21 @@ function validateSlots(value, path) {
     return value.map((s) => {
         if (s === null || typeof s !== "object")
             throw corrupt(path, "`slots` entry is not an object");
-        const { at, tokens } = s;
+        const { at, tokens, costMicroUsd, costUnknown } = s;
         if (typeof at !== "number" || !Number.isFinite(at) || typeof tokens !== "number" || !Number.isFinite(tokens)) {
             throw corrupt(path, "`slots` entry has a non-numeric `at`/`tokens`");
         }
-        return { at, tokens };
+        if (costMicroUsd !== undefined && (typeof costMicroUsd !== "number" || !Number.isFinite(costMicroUsd))) {
+            throw corrupt(path, "`slots` entry has a non-numeric `costMicroUsd`");
+        }
+        if (costUnknown !== undefined && costUnknown !== true)
+            throw corrupt(path, "`slots` entry has a `costUnknown` that is not `true`");
+        return {
+            at,
+            tokens,
+            ...(costMicroUsd === undefined ? {} : { costMicroUsd }),
+            ...(costUnknown === true ? { costUnknown: true } : {}),
+        };
     });
 }
 function validateBuckets(value, path) {
@@ -74,7 +84,7 @@ function validateBuckets(value, path) {
     return value.map((b) => {
         if (b === null || typeof b !== "object")
             throw corrupt(path, "`buckets` entry is not an object");
-        const { windowMs, openedAt, tokens } = b;
+        const { windowMs, openedAt, tokens, costMicroUsd, costUnknown } = b;
         if (typeof windowMs !== "number" ||
             !Number.isFinite(windowMs) ||
             typeof openedAt !== "number" ||
@@ -83,6 +93,17 @@ function validateBuckets(value, path) {
             !Number.isFinite(tokens)) {
             throw corrupt(path, "`buckets` entry has a non-numeric `windowMs`/`openedAt`/`tokens`");
         }
-        return { windowMs, openedAt, tokens };
+        if (costMicroUsd !== undefined && (typeof costMicroUsd !== "number" || !Number.isFinite(costMicroUsd))) {
+            throw corrupt(path, "`buckets` entry has a non-numeric `costMicroUsd`");
+        }
+        if (costUnknown !== undefined && costUnknown !== true)
+            throw corrupt(path, "`buckets` entry has a `costUnknown` that is not `true`");
+        return {
+            windowMs,
+            openedAt,
+            tokens,
+            ...(costMicroUsd === undefined ? {} : { costMicroUsd }),
+            ...(costUnknown === true ? { costUnknown: true } : {}),
+        };
     });
 }

package/dist/tools/loop-tick.js

@@ -68,7 +68,7 @@ function dynamicTick(push) {
 
 Run the autonomous check using the loop instructions established earlier in this conversation. If you cannot find them, treat this as a no-op tick.
 
-You scheduled this tick via the ${SCHEDULE_WAKEUP_TOOL_NAME} tool (not a recurring cron). To keep the loop alive, call ${SCHEDULE_WAKEUP_TOOL_NAME} again at the end of this turn with \`prompt\` set to the literal sentinel \`${AUTONOMOUS_LOOP_DYNAMIC_SENTINEL}\` — otherwise the loop ends after this tick.${DYNAMIC_APPENDIX}${push}`;
+You scheduled this tick via the ${SCHEDULE_WAKEUP_TOOL_NAME} tool (not a recurring cron). To keep the loop alive, call ${SCHEDULE_WAKEUP_TOOL_NAME} again at the end of this turn with \`prompt\` set to the literal sentinel \`${AUTONOMOUS_LOOP_DYNAMIC_SENTINEL}\` and \`noop\` set to \`true\` if this tick changed nothing (or \`false\` if it did) — otherwise the loop ends after this tick.${DYNAMIC_APPENDIX}${push}`;
 }
 export function resolveAutonomousLoopPrompt(prompt, opts) {
     if (prompt !== AUTONOMOUS_LOOP_SENTINEL && prompt !== AUTONOMOUS_LOOP_DYNAMIC_SENTINEL)

package/dist/tools/scheduler-tools.js

@@ -13,6 +13,8 @@ Do NOT schedule a short-interval wakeup to poll for background work you started
 
 Pass the same /loop prompt back via \`prompt\` each turn so the next firing repeats the task. For an autonomous /loop (no user prompt), pass the literal sentinel \`${AUTONOMOUS_LOOP_DYNAMIC_SENTINEL}\` as \`prompt\` instead — the runtime resolves it back to the autonomous-loop instructions at fire time. (There is a similar \`${AUTONOMOUS_LOOP_SENTINEL}\` sentinel for CronCreate-based autonomous loops; do not confuse the two — ${SCHEDULE_WAKEUP_TOOL_NAME} always uses the \`-dynamic\` variant.) To end the loop, call this tool with \`stop: true\` (omit every other field) — the loop ends immediately and no further wakeups fire.
 
+Set \`noop: true\` if nothing changed — you checked and there's nothing to report ("no change", "still waiting", "quiet hold"). Set \`noop: false\` if something happened worth keeping — you edited a file, posted a message, advanced state, or surfaced a finding. Consecutive \`noop: true\` ticks are collapsed in the user's terminal view and tracked as a streak, so long quiet holds stay legible to the user without scrolling. Omit \`noop\` when stopping (\`stop: true\`).
+
 ## Picking delaySeconds
 
 The provider prompt cache decides how expensive a wake-up is: waking inside the cache TTL re-reads your conversation context cached (fast, cheap); waking past it re-reads everything uncached. The TTL depends on the provider route this session uses — Anthropic-family routes default to about 5 minutes (1-hour optional), while some routes (e.g. DeepSeek) typically retain unused prefixes for hours, with no guaranteed TTL.
@@ -422,6 +424,9 @@ MOUNT NOTE: this host does not vouch for session-scoped scheduling, so a wakeup
             stop: Type.Optional(Type.Boolean({
                 description: "Immediately end the dynamic loop: cancel this session's pending wakeup(s) and schedule nothing. All other fields are ignored when true.",
             })),
+            noop: Type.Optional(Type.Boolean({
+                description: "true = nothing changed (you checked and there is nothing to report). false = something happened worth keeping (edited a file, posted a message, advanced state, surfaced a finding). Consecutive noop:true ticks are collapsed in the user's terminal view and tracked as a streak. Required unless `stop` is true.",
+            })),
         }),
         effect: "write",
         execute: async (args) => serializedWakeupOp(async () => {
@@ -439,6 +444,9 @@ MOUNT NOTE: this host does not vouch for session-scoped scheduling, so a wakeup
             if (a.delaySeconds === undefined || a.reason === undefined || a.prompt === undefined) {
                 return errorResult(`Error (${SCHEDULE_WAKEUP_TOOL_NAME}): delaySeconds, reason and prompt are required unless \`stop\` is true.`);
             }
+            if (a.noop === undefined) {
+                return errorResult(`Error (${SCHEDULE_WAKEUP_TOOL_NAME}): \`noop\` is required unless \`stop\` is true — pass \`noop: true\` if this tick changed nothing, \`noop: false\` if something happened worth keeping.`);
+            }
             if (sched.schedulerCapabilities.supportsSessionWakeup === false) {
                 return errorResult(`Error (${SCHEDULE_WAKEUP_TOOL_NAME}): this environment has no resident scheduler that can honor a session wakeup — the wakeup would never fire. Wait in the foreground instead, or start the work in a self-detaching form.`);
             }
@@ -468,7 +476,7 @@ MOUNT NOTE: this host does not vouch for session-scoped scheduling, so a wakeup
                 : " Note: this scheduler does not vouch for session-lifetime reap, so this wakeup is scheduled as a persistent one and may outlive the session — end the loop explicitly with `stop: true` rather than relying on the session ending.";
             return {
                 content: `Next wakeup scheduled for ${hhmmss} (in ${clampedDelaySeconds}s)${clampNote}. Nothing more to do this turn — the harness re-invokes you when the wakeup fires or a task-notification arrives.${reapNote}${cleanupNote}`,
-                details: { type: "schedule-wakeup", stopped: false, scheduledFor, clampedDelaySeconds, wasClamped, reason: a.reason },
+                details: { type: "schedule-wakeup", stopped: false, scheduledFor, clampedDelaySeconds, wasClamped, reason: a.reason, noop: a.noop },
             };
         }),
     });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sema-agent/core",
-  "version": "5.61.0",
+  "version": "5.62.0",
   "description": "Stateless, task-oriented AI agent core",
   "type": "module",
   "license": "BUSL-1.1",