@noetic-tools/types 3.4.0 → 3.5.0

package/dist/types/context-harness.d.ts

@@ -120,6 +120,8 @@ export interface ContextHarness {
     detachedSpawn<I, O>(step: unknown, input: I, parentCtx: Context, overrides?: ContextDetachedSpawnOverrides): DetachedHandle<O>;
     createContext(opts?: {
         parent?: Context;
+        /** Charge this context's usage to `parent` as it is spent. Default `true`. */
+        rollUpUsage?: boolean;
         items?: Item[];
         state?: unknown;
         threadId?: string;

package/dist/types/context.d.ts

@@ -42,6 +42,8 @@ export interface CwdState {
 export interface RestoreContextOptions {
     /** Live parent context, when the restored execution hangs under one. */
     parent?: Context;
+    /** Charge the restored context's usage to `parent`, same as `createContext({ rollUpUsage })`. Default `true`. */
+    rollUpUsage?: boolean;
     /** Opaque per-execution state, same as `createContext({ state })`. */
     state?: unknown;
     /** Context layers for the restored context. Defaults to the harness's configured layers. */
@@ -56,6 +58,17 @@ export interface Context<TContext = ContextData, TState = unknown> {
     readonly cost: number;
     state: TState;
     readonly parent: Context<ContextData> | null;
+    /**
+     * Where this context's token/cost usage is also charged. Every charge
+     * recorded here is added to this context and then to each ancestor along
+     * this chain, so `tokens` / `cost` cover this context plus every descendant,
+     * live — whether the descendant succeeds, fails, or is abandoned.
+     *
+     * Equals `parent` unless the context was created with `rollUpUsage: false`,
+     * in which case it is `null` and the context keeps its spend to itself. When
+     * absent (a hand-rolled `Context` implementation), `parent` is used.
+     */
+    readonly usageParent?: Context<ContextData> | null;
     readonly depth: number;
     readonly span: Span;
     readonly threadId: string;

package/dist/types/runtime.d.ts

@@ -253,6 +253,12 @@ export interface AgentHarnessContract<TParams extends Record<string, unknown> =
     }): DetachedHandle<O>;
     createContext(opts?: {
         parent?: Context;
+        /**
+         * Charge this context's token/cost usage to `parent` as it is spent, so
+         * the parent's `tokens` / `cost` include it. Default `true`; pass `false`
+         * to keep the child's spend off the parent.
+         */
+        rollUpUsage?: boolean;
         items?: Item[];
         state?: unknown;
         threadId?: string;

package/dist/util/message-helpers.d.ts

@@ -33,5 +33,23 @@ export declare function createMessage(text: string, role: 'user' | 'developer'):
 export declare function extractAssistantText(items: ReadonlyArray<Item>): string;
 /** Naive token estimate: ~4 chars per token */
 export declare function estimateTokens(text: string): number;
-/** Accumulate token usage and cost from an LLM response onto a mutable context. */
+/** @public One unit of spend to charge to a context: a model call, or any other billed work. */
+export interface UsageCharge {
+    inputTokens: number;
+    outputTokens: number;
+    cachedTokens?: number;
+    /** USD. */
+    cost?: number;
+}
+/**
+ * @public Charge `charge` to `ctx` and to every ancestor on its `usageParent`
+ * chain. Charging at the moment of spend — rather than merging a child's
+ * totals into its parent when the child settles — is what keeps spend from a
+ * failed spawn, a fork path, or an abandoned `race` loser from being lost, and
+ * lets `until.maxCost` / `checkBudget` on an ancestor see siblings' spend live.
+ * Use this, not direct writes to `ctx.cost`, for any billed work outside a
+ * model call; a direct write stays on that one context.
+ */
+export declare function recordUsage(ctx: Context, charge: UsageCharge): void;
+/** Accumulate token usage and cost from an LLM response onto a context and its usage ancestors. */
 export declare function trackUsage(ctx: Context, response: LLMResponse): void;

package/dist/util/message-helpers.js

@@ -90,23 +90,50 @@ export function extractAssistantText(items) {
 export function estimateTokens(text) {
     return Math.ceil(text.length / 4);
 }
-/** Accumulate token usage and cost from an LLM response onto a mutable context. */
-export function trackUsage(ctx, response) {
-    if (!canTrackUsage(ctx)) {
-        return;
-    }
-    ctx.tokens.input += response.usage.inputTokens;
-    ctx.tokens.output += response.usage.outputTokens;
-    ctx.tokens.total += response.usage.inputTokens + response.usage.outputTokens;
-    // Only write `cached` when the response actually carried a figure. Defaulting
+function addCharge(ctx, charge) {
+    ctx.tokens.input += charge.inputTokens;
+    ctx.tokens.output += charge.outputTokens;
+    ctx.tokens.total += charge.inputTokens + charge.outputTokens;
+    // Only write `cached` when the charge actually carried a figure. Defaulting
     // a missing report to 0 would erase the `RoundUsage` invariant that
     // `undefined` means "this provider says nothing about caching" — callers that
     // steer on cache behaviour could no longer tell that from "nothing was
-    // cached". Mirrors the child→parent merge in execute-action.
-    if (response.usage.cachedTokens !== undefined) {
-        ctx.tokens.cached = (ctx.tokens.cached ?? 0) + response.usage.cachedTokens;
+    // cached".
+    if (charge.cachedTokens !== undefined) {
+        ctx.tokens.cached = (ctx.tokens.cached ?? 0) + charge.cachedTokens;
+    }
+    if (charge.cost) {
+        ctx.cost = ctx.cost + charge.cost;
     }
-    if (response.cost) {
-        ctx.cost = ctx.cost + response.cost;
+}
+function usageParentOf(ctx) {
+    return ctx.usageParent !== undefined ? ctx.usageParent : ctx.parent;
+}
+/**
+ * @public Charge `charge` to `ctx` and to every ancestor on its `usageParent`
+ * chain. Charging at the moment of spend — rather than merging a child's
+ * totals into its parent when the child settles — is what keeps spend from a
+ * failed spawn, a fork path, or an abandoned `race` loser from being lost, and
+ * lets `until.maxCost` / `checkBudget` on an ancestor see siblings' spend live.
+ * Use this, not direct writes to `ctx.cost`, for any billed work outside a
+ * model call; a direct write stays on that one context.
+ */
+export function recordUsage(ctx, charge) {
+    // The chain is acyclic for every ContextImpl (parents are fixed at
+    // construction); the guard only protects against a hand-rolled Context.
+    const seen = new Set();
+    for (let current = ctx; current && !seen.has(current);) {
+        seen.add(current);
+        if (canTrackUsage(current)) {
+            addCharge(current, charge);
+        }
+        current = usageParentOf(current);
     }
 }
+/** Accumulate token usage and cost from an LLM response onto a context and its usage ancestors. */
+export function trackUsage(ctx, response) {
+    recordUsage(ctx, {
+        ...response.usage,
+        cost: response.cost,
+    });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@noetic-tools/types",
-  "version": "3.4.0",
+  "version": "3.5.0",
   "type": "module",
   "description": "Foundational type contracts and primitives shared across the Noetic framework (items, LLM config, adapters, steering, errors).",
   "license": "Apache-2.0",
@@ -60,8 +60,8 @@
     "zod": "^4.0.0"
   },
   "scripts": {
-    "build": "bunx tsc -p tsconfig.build.json && bun scripts/add-js-extensions.ts",
-    "verify:esm": "bun scripts/verify-node-esm.ts",
+    "build": "bunx tsc -p tsconfig.build.json && bun ../../scripts/add-js-extensions.ts",
+    "verify:esm": "bun ../../scripts/verify-node-esm.ts",
     "prepublishOnly": "rm -rf dist && bun run build && bun run verify:esm && bun scripts/strip-dev-conditions.ts",
     "test": "bun test",
     "test:coverage": "bun test --coverage --coverage-reporter=text --coverage-reporter=lcov",