@archmax-ai/harness 0.0.0

package/dist/core/usage.d.ts

@@ -0,0 +1,114 @@
+/**
+ * Token accounting: what a session cost, in tokens and (when priced) in money.
+ *
+ * Providers report usage on each AI message as LangChain `usage_metadata`. This
+ * module is the single place that reads those shapes (including the cached-prefix
+ * detail that makes prompt caching observable), sums them, and turns them into a
+ * cost using a caller-supplied price table. Cost is **omitted, never guessed**:
+ * an unpriced model reports tokens only, so a number on screen is always a
+ * number someone configured.
+ */
+import type { WorkflowEventHandler } from "./events.js";
+/** Tokens consumed by one model call, one turn, or a whole session. */
+export interface TokenUsage {
+    /** Total input tokens; the two cache counts below are a breakdown of it, not a peer. */
+    inputTokens: number;
+    outputTokens: number;
+    /** Input tokens served from the provider's prompt cache (billed at a discount). */
+    cacheReadTokens: number;
+    /** Input tokens written to the provider's prompt cache (billed at a premium). */
+    cacheCreationTokens: number;
+}
+/** A run's usage plus its cost when the model is priced. */
+export interface UsageSummary extends TokenUsage {
+    costUsd?: number;
+}
+/** Prices in USD per 1,000,000 tokens. Omitted rates contribute nothing. */
+export interface ModelPricing {
+    input?: number;
+    output?: number;
+    /** Cache-read rate (Anthropic bills ~10% of input). */
+    cacheRead?: number;
+    /** Cache-write rate (Anthropic bills ~125% of input). */
+    cacheWrite?: number;
+}
+/**
+ * Price table keyed by model id. Lookup is: exact id, then the longest key that
+ * is a substring of the id (so `claude-sonnet` prices
+ * `anthropic/claude-sonnet-4.6`), then the `default` key.
+ */
+export type PricingTable = Record<string, ModelPricing>;
+/** The key used when a price applies to whatever model is configured. */
+export declare const DEFAULT_PRICING_KEY = "default";
+/** A zeroed usage record. */
+export declare function emptyUsage(): TokenUsage;
+/** Sum two usage records into a new one. */
+export declare function addUsage(a: TokenUsage, b: TokenUsage): TokenUsage;
+/** Whether any counter is non-zero. */
+export declare function hasUsage(usage: TokenUsage): boolean;
+/**
+ * The provider shapes this reads, in order of preference:
+ *  - LangChain normalized: `usage_metadata.input_token_details.{cache_read,cache_creation}`
+ *  - OpenAI-compatible raw: `response_metadata.usage.prompt_tokens_details.cached_tokens`
+ *  - Anthropic raw: `…usage.{cache_read_input_tokens,cache_creation_input_tokens}`
+ *
+ * `inputTokens` is the **total** input count, of which `cacheReadTokens` and
+ * `cacheCreationTokens` are a breakdown — LangChain's own `usage_metadata`
+ * contract (`input_tokens` is the "sum of all input token types"), and what the
+ * OpenAI-compatible raw shape reports too (`prompt_tokens` includes
+ * `prompt_tokens_details.cached_tokens`). Anthropic's raw shape is the one
+ * exception: its `usage.input_tokens` counts only what was neither read from nor
+ * written to cache, so the cache counts are folded back in. One invariant then
+ * holds downstream whatever the provider sent, which is what lets
+ * {@link computeCostUsd} price without a per-provider branch.
+ */
+export declare function extractUsage(message: unknown): {
+    usage: TokenUsage;
+    model?: string;
+} | null;
+/**
+ * Resolve the price entry for `model`: exact id, then the longest substring key,
+ * then `default`. Returns `undefined` when nothing matches — the caller must
+ * then omit cost rather than assume free.
+ */
+export declare function resolveModelPricing(table: PricingTable | undefined, model: string | undefined): ModelPricing | undefined;
+/**
+ * Cost in USD for `usage` under `pricing`, or `undefined` when no rate applies.
+ *
+ * The cache counts are a breakdown of `inputTokens`, not a peer of it (see
+ * {@link extractUsage}), so the input rate applies to the **remainder** — what
+ * was neither served from nor written to cache — and each cache rate to its own
+ * count. Charging the whole input count *and* the cache counts on top would bill
+ * a cached token twice, which on a warm prompt-caching workload is most of the
+ * bill. A missing cache rate falls back to the input rate for reads and writes,
+ * since every provider prices cached tokens relative to input.
+ */
+export declare function computeCostUsd(usage: TokenUsage, pricing: ModelPricing | undefined): number | undefined;
+/** Build a summary: usage plus cost when the model is priced. */
+export declare function summarizeUsage(usage: TokenUsage, table: PricingTable | undefined, model: string | undefined): UsageSummary;
+/**
+ * Sum two summaries, tokens and cost together. Cost is present only when at
+ * least one side has it — summing an unpriced summary must not invent a `0`.
+ * This is the single place summaries are combined (the tracker's cross-session
+ * totals and the CLI's per-test-case totals both use it).
+ */
+export declare function addSummaries(a: UsageSummary, b: UsageSummary): UsageSummary;
+/** Human-readable one-liner, e.g. `in 12,004 · out 318 · cache r 9,801/w 0 · $0.0421`. */
+export declare function formatUsage(summary: UsageSummary): string;
+export interface UsageTracker {
+    /**
+     * Event handler to pass as the runtime `onEvent` (it forwards to the
+     * `onEvent` given at construction, when any).
+     */
+    handler: WorkflowEventHandler;
+    /** Totals for one session, or across every observed session when omitted. */
+    totals(sessionId?: string): UsageSummary;
+    /** Per-session totals, keyed by session id. */
+    bySession(): Map<string, UsageSummary>;
+    /** Drop accumulated totals for one session, or for all of them. */
+    reset(sessionId?: string): void;
+}
+/** Create a tracker that accumulates usage and cost from the event stream. */
+export declare function createUsageTracker(options?: {
+    onEvent?: WorkflowEventHandler;
+}): UsageTracker;

package/dist/core/usage.js

@@ -0,0 +1,226 @@
+/**
+ * Token accounting: what a session cost, in tokens and (when priced) in money.
+ *
+ * Providers report usage on each AI message as LangChain `usage_metadata`. This
+ * module is the single place that reads those shapes (including the cached-prefix
+ * detail that makes prompt caching observable), sums them, and turns them into a
+ * cost using a caller-supplied price table. Cost is **omitted, never guessed**:
+ * an unpriced model reports tokens only, so a number on screen is always a
+ * number someone configured.
+ */
+/** The key used when a price applies to whatever model is configured. */
+export const DEFAULT_PRICING_KEY = "default";
+/** A zeroed usage record. */
+export function emptyUsage() {
+    return { inputTokens: 0, outputTokens: 0, cacheReadTokens: 0, cacheCreationTokens: 0 };
+}
+/** Sum two usage records into a new one. */
+export function addUsage(a, b) {
+    return {
+        inputTokens: a.inputTokens + b.inputTokens,
+        outputTokens: a.outputTokens + b.outputTokens,
+        cacheReadTokens: a.cacheReadTokens + b.cacheReadTokens,
+        cacheCreationTokens: a.cacheCreationTokens + b.cacheCreationTokens,
+    };
+}
+/** Whether any counter is non-zero. */
+export function hasUsage(usage) {
+    return (usage.inputTokens > 0 ||
+        usage.outputTokens > 0 ||
+        usage.cacheReadTokens > 0 ||
+        usage.cacheCreationTokens > 0);
+}
+function num(value) {
+    return typeof value === "number" && Number.isFinite(value) ? value : 0;
+}
+/**
+ * The provider shapes this reads, in order of preference:
+ *  - LangChain normalized: `usage_metadata.input_token_details.{cache_read,cache_creation}`
+ *  - OpenAI-compatible raw: `response_metadata.usage.prompt_tokens_details.cached_tokens`
+ *  - Anthropic raw: `…usage.{cache_read_input_tokens,cache_creation_input_tokens}`
+ *
+ * `inputTokens` is the **total** input count, of which `cacheReadTokens` and
+ * `cacheCreationTokens` are a breakdown — LangChain's own `usage_metadata`
+ * contract (`input_tokens` is the "sum of all input token types"), and what the
+ * OpenAI-compatible raw shape reports too (`prompt_tokens` includes
+ * `prompt_tokens_details.cached_tokens`). Anthropic's raw shape is the one
+ * exception: its `usage.input_tokens` counts only what was neither read from nor
+ * written to cache, so the cache counts are folded back in. One invariant then
+ * holds downstream whatever the provider sent, which is what lets
+ * {@link computeCostUsd} price without a per-provider branch.
+ */
+export function extractUsage(message) {
+    if (typeof message !== "object" || message === null)
+        return null;
+    const meta = message.usage_metadata;
+    const response = message.response_metadata;
+    const raw = (response?.usage ?? response?.token_usage);
+    if (!meta && !raw)
+        return null;
+    const details = (meta?.input_token_details ?? {});
+    const promptDetails = (raw?.prompt_tokens_details ?? {});
+    const cacheReadTokens = num(details.cache_read) ||
+        num(promptDetails.cached_tokens) ||
+        num(raw?.cache_read_input_tokens);
+    const cacheCreationTokens = num(details.cache_creation) || num(raw?.cache_creation_input_tokens);
+    // Which shape reported the input count decides whether the cache counts are
+    // already inside it. Read from the keys rather than from a zero, so a prompt
+    // served entirely from cache is classified the same way as any other.
+    const reportsNumber = (record, key) => typeof record?.[key] === "number";
+    const isAnthropicRaw = !reportsNumber(meta, "input_tokens") &&
+        !reportsNumber(raw, "prompt_tokens") &&
+        reportsNumber(raw, "input_tokens");
+    const reportedInput = num(meta?.input_tokens) || num(raw?.prompt_tokens) || num(raw?.input_tokens);
+    const usage = {
+        inputTokens: isAnthropicRaw
+            ? reportedInput + cacheReadTokens + cacheCreationTokens
+            : reportedInput,
+        outputTokens: num(meta?.output_tokens) || num(raw?.completion_tokens) || num(raw?.output_tokens),
+        cacheReadTokens,
+        cacheCreationTokens,
+    };
+    const model = typeof response?.model_name === "string"
+        ? response.model_name
+        : typeof response?.model === "string"
+            ? response.model
+            : undefined;
+    return { usage, ...(model ? { model } : {}) };
+}
+/**
+ * Resolve the price entry for `model`: exact id, then the longest substring key,
+ * then `default`. Returns `undefined` when nothing matches — the caller must
+ * then omit cost rather than assume free.
+ */
+export function resolveModelPricing(table, model) {
+    if (!table)
+        return undefined;
+    if (model) {
+        if (table[model])
+            return table[model];
+        const keys = Object.keys(table)
+            .filter((key) => key !== DEFAULT_PRICING_KEY && model.includes(key))
+            .sort((a, b) => b.length - a.length);
+        if (keys.length > 0)
+            return table[keys[0]];
+    }
+    return table[DEFAULT_PRICING_KEY];
+}
+const PER_MILLION = 1_000_000;
+/**
+ * Cost in USD for `usage` under `pricing`, or `undefined` when no rate applies.
+ *
+ * The cache counts are a breakdown of `inputTokens`, not a peer of it (see
+ * {@link extractUsage}), so the input rate applies to the **remainder** — what
+ * was neither served from nor written to cache — and each cache rate to its own
+ * count. Charging the whole input count *and* the cache counts on top would bill
+ * a cached token twice, which on a warm prompt-caching workload is most of the
+ * bill. A missing cache rate falls back to the input rate for reads and writes,
+ * since every provider prices cached tokens relative to input.
+ */
+export function computeCostUsd(usage, pricing) {
+    if (!pricing)
+        return undefined;
+    const { input, output, cacheRead, cacheWrite } = pricing;
+    if (input === undefined && output === undefined)
+        return undefined;
+    // Clamped: a provider's breakdown is not obliged to fit inside its own total,
+    // and a negative remainder would credit cost back rather than fail loudly.
+    const fullRateInput = Math.max(0, usage.inputTokens - usage.cacheReadTokens - usage.cacheCreationTokens);
+    const cost = (num(input) * fullRateInput +
+        num(output) * usage.outputTokens +
+        num(cacheRead ?? input) * usage.cacheReadTokens +
+        num(cacheWrite ?? input) * usage.cacheCreationTokens) /
+        PER_MILLION;
+    // Sub-cent runs are common; keep six decimals so a cost is never rounded to 0.
+    return Math.round(cost * 1e6) / 1e6;
+}
+/** Build a summary: usage plus cost when the model is priced. */
+export function summarizeUsage(usage, table, model) {
+    const costUsd = computeCostUsd(usage, resolveModelPricing(table, model));
+    return { ...usage, ...(costUsd !== undefined ? { costUsd } : {}) };
+}
+/**
+ * Sum two summaries, tokens and cost together. Cost is present only when at
+ * least one side has it — summing an unpriced summary must not invent a `0`.
+ * This is the single place summaries are combined (the tracker's cross-session
+ * totals and the CLI's per-test-case totals both use it).
+ */
+export function addSummaries(a, b) {
+    const costUsd = a.costUsd !== undefined || b.costUsd !== undefined
+        ? Math.round(((a.costUsd ?? 0) + (b.costUsd ?? 0)) * 1e6) / 1e6
+        : undefined;
+    return { ...addUsage(a, b), ...(costUsd !== undefined ? { costUsd } : {}) };
+}
+/** Human-readable one-liner, e.g. `in 12,004 · out 318 · cache r 9,801/w 0 · $0.0421`. */
+export function formatUsage(summary) {
+    const n = (value) => value.toLocaleString("en-US");
+    const parts = [
+        `in ${n(summary.inputTokens)}`,
+        `out ${n(summary.outputTokens)}`,
+        `cache r ${n(summary.cacheReadTokens)}/w ${n(summary.cacheCreationTokens)}`,
+    ];
+    if (summary.costUsd !== undefined) {
+        parts.push(`$${summary.costUsd < 0.01 ? summary.costUsd.toFixed(6) : summary.costUsd.toFixed(4)}`);
+    }
+    return parts.join(" · ");
+}
+/**
+ * `createUsageTracker()` — the supported way to read what a session cost.
+ *
+ * Usage arrives as one `model-usage` event per model call. A host could sum
+ * those by hand; this tracker exists so nobody has to, and so per-session
+ * demultiplexing (concurrent runs on one assembled agent) is done once, from the
+ * event envelope's `sessionId`.
+ *
+ * For the consumer holding `invoke`, there is deliberately nothing to wait for:
+ * `invoke` returning *is* the end of the turn, and that is where `totals()` is
+ * read. The runtime keeps one of these internally so a session's usage can be
+ * written into its artifacts.
+ *
+ * A consumer that only sees the **event stream** has no `invoke` to observe, and
+ * for a durable session "`invoke` returned" means the turn ended, not the run — a
+ * parked session returns with the run very much alive. Those consumers get the
+ * `run-metrics` event instead, which reports the session's cumulative ledger
+ * (usage included) whenever a turn settles. See `core/metrics.ts`.
+ *
+ * ```ts
+ * const usage = createUsageTracker();
+ * const runtime = await createAgent({ onEvent: usage.handler });
+ * await runtime.graph.invoke(input, { configurable: { thread_id: "t1" } });
+ * usage.totals("t1"); // { inputTokens, cacheReadTokens, …, costUsd? }
+ * ```
+ *
+ * To keep your own subscriber, pass it in: `createUsageTracker({ onEvent: mine })`.
+ */
+/** Key used for events that arrive without a bound session id. */
+const UNSCOPED = "__unscoped__";
+/** Create a tracker that accumulates usage and cost from the event stream. */
+export function createUsageTracker(options = {}) {
+    const sessions = new Map();
+    return {
+        handler: (event) => {
+            if (event.type === "model-usage") {
+                const key = event.sessionId ?? UNSCOPED;
+                sessions.set(key, addSummaries(sessions.get(key) ?? emptyUsage(), {
+                    inputTokens: event.inputTokens,
+                    outputTokens: event.outputTokens,
+                    cacheReadTokens: event.cacheReadTokens ?? 0,
+                    cacheCreationTokens: event.cacheCreationTokens ?? 0,
+                    ...(event.costUsd !== undefined ? { costUsd: event.costUsd } : {}),
+                }));
+            }
+            options.onEvent?.(event);
+        },
+        totals: (sessionId) => sessionId !== undefined
+            ? (sessions.get(sessionId) ?? emptyUsage())
+            : [...sessions.values()].reduce(addSummaries, emptyUsage()),
+        bySession: () => new Map(sessions),
+        reset: (sessionId) => {
+            if (sessionId === undefined)
+                sessions.clear();
+            else
+                sessions.delete(sessionId);
+        },
+    };
+}
+//# sourceMappingURL=usage.js.map

package/dist/core/usage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"usage.js","sourceRoot":"","sources":["../../src/core/usage.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAqCH,yEAAyE;AACzE,MAAM,CAAC,MAAM,mBAAmB,GAAG,SAAS,CAAC;AAE7C,6BAA6B;AAC7B,MAAM,UAAU,UAAU;IACxB,OAAO,EAAE,WAAW,EAAE,CAAC,EAAE,YAAY,EAAE,CAAC,EAAE,eAAe,EAAE,CAAC,EAAE,mBAAmB,EAAE,CAAC,EAAE,CAAC;AACzF,CAAC;AAED,4CAA4C;AAC5C,MAAM,UAAU,QAAQ,CAAC,CAAa,EAAE,CAAa;IACnD,OAAO;QACL,WAAW,EAAE,CAAC,CAAC,WAAW,GAAG,CAAC,CAAC,WAAW;QAC1C,YAAY,EAAE,CAAC,CAAC,YAAY,GAAG,CAAC,CAAC,YAAY;QAC7C,eAAe,EAAE,CAAC,CAAC,eAAe,GAAG,CAAC,CAAC,eAAe;QACtD,mBAAmB,EAAE,CAAC,CAAC,mBAAmB,GAAG,CAAC,CAAC,mBAAmB;KACnE,CAAC;AACJ,CAAC;AAED,uCAAuC;AACvC,MAAM,UAAU,QAAQ,CAAC,KAAiB;IACxC,OAAO,CACL,KAAK,CAAC,WAAW,GAAG,CAAC;QACrB,KAAK,CAAC,YAAY,GAAG,CAAC;QACtB,KAAK,CAAC,eAAe,GAAG,CAAC;QACzB,KAAK,CAAC,mBAAmB,GAAG,CAAC,CAC9B,CAAC;AACJ,CAAC;AAED,SAAS,GAAG,CAAC,KAAc;IACzB,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;AACzE,CAAC;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,YAAY,CAAC,OAAgB;IAC3C,IAAI,OAAO,OAAO,KAAK,QAAQ,IAAI,OAAO,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC;IACjE,MAAM,IAAI,GAAI,OAAwD,CAAC,cAAc,CAAC;IACtF,MAAM,QAAQ,GAAI,OAA2D,CAAC,iBAAiB,CAAC;IAChG,MAAM,GAAG,GAAG,CAAC,QAAQ,EAAE,KAAK,IAAI,QAAQ,EAAE,WAAW,CAAwC,CAAC;IAC9F,IAAI,CAAC,IAAI,IAAI,CAAC,GAAG;QAAE,OAAO,IAAI,CAAC;IAE/B,MAAM,OAAO,GAAG,CAAC,IAAI,EAAE,mBAAmB,IAAI,EAAE,CAA4B,CAAC;IAC7E,MAAM,aAAa,GAAG,CAAC,GAAG,EAAE,qBAAqB,IAAI,EAAE,CAA4B,CAAC;IAEpF,MAAM,eAAe,GACnB,GAAG,CAAC,OAAO,CAAC,UAAU,CAAC;QACvB,GAAG,CAAC,aAAa,CAAC,aAAa,CAAC;QAChC,GAAG,CAAC,GAAG,EAAE,uBAAuB,CAAC,CAAC;IACpC,MAAM,mBAAmB,GAAG,GAAG,CAAC,OAAO,CAAC,cAAc,CAAC,IAAI,GAAG,CAAC,GAAG,EAAE,2BAA2B,CAAC,CAAC;IAEjG,4EAA4E;IAC5E,6EAA6E;IAC7E,sEAAsE;IACtE,MAAM,aAAa,GAAG,CAAC,MAA2C,EAAE,GAAW,EAAW,EAAE,CAC1F,OAAO,MAAM,EAAE,CAAC,GAAG,CAAC,KAAK,QAAQ,CAAC;IACpC,MAAM,cAAc,GAClB,CAAC,aAAa,CAAC,IAAI,EAAE,cAAc,CAAC;QACpC,CAAC,aAAa,CAAC,GAAG,EAAE,eAAe,CAAC;QACpC,aAAa,CAAC,GAAG,EAAE,cAAc,CAAC,CAAC;IAErC,MAAM,aAAa,GACjB,GAAG,CAAC,IAAI,EAAE,YAAY,CAAC,IAAI,GAAG,CAAC,GAAG,EAAE,aAAa,CAAC,IAAI,GAAG,CAAC,GAAG,EAAE,YAAY,CAAC,CAAC;IAE/E,MAAM,KAAK,GAAe;QACxB,WAAW,EAAE,cAAc;YACzB,CAAC,CAAC,aAAa,GAAG,eAAe,GAAG,mBAAmB;YACvD,CAAC,CAAC,aAAa;QACjB,YAAY,EAAE,GAAG,CAAC,IAAI,EAAE,aAAa,CAAC,IAAI,GAAG,CAAC,GAAG,EAAE,iBAAiB,CAAC,IAAI,GAAG,CAAC,GAAG,EAAE,aAAa,CAAC;QAChG,eAAe;QACf,mBAAmB;KACpB,CAAC;IAEF,MAAM,KAAK,GACT,OAAO,QAAQ,EAAE,UAAU,KAAK,QAAQ;QACtC,CAAC,CAAC,QAAQ,CAAC,UAAU;QACrB,CAAC,CAAC,OAAO,QAAQ,EAAE,KAAK,KAAK,QAAQ;YACnC,CAAC,CAAC,QAAQ,CAAC,KAAK;YAChB,CAAC,CAAC,SAAS,CAAC;IAElB,OAAO,EAAE,KAAK,EAAE,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC;AAChD,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,mBAAmB,CACjC,KAA+B,EAC/B,KAAyB;IAEzB,IAAI,CAAC,KAAK;QAAE,OAAO,SAAS,CAAC;IAC7B,IAAI,KAAK,EAAE,CAAC;QACV,IAAI,KAAK,CAAC,KAAK,CAAC;YAAE,OAAO,KAAK,CAAC,KAAK,CAAC,CAAC;QACtC,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC;aAC5B,MAAM,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,KAAK,mBAAmB,IAAI,KAAK,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC;aACnE,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,MAAM,CAAC,CAAC;QACvC,IAAI,IAAI,CAAC,MAAM,GAAG,CAAC;YAAE,OAAO,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC;IAC7C,CAAC;IACD,OAAO,KAAK,CAAC,mBAAmB,CAAC,CAAC;AACpC,CAAC;AAED,MAAM,WAAW,GAAG,SAAS,CAAC;AAE9B;;;;;;;;;;GAUG;AACH,MAAM,UAAU,cAAc,CAC5B,KAAiB,EACjB,OAAiC;IAEjC,IAAI,CAAC,OAAO;QAAE,OAAO,SAAS,CAAC;IAC/B,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,UAAU,EAAE,GAAG,OAAO,CAAC;IACzD,IAAI,KAAK,KAAK,SAAS,IAAI,MAAM,KAAK,SAAS;QAAE,OAAO,SAAS,CAAC;IAClE,8EAA8E;IAC9E,2EAA2E;IAC3E,MAAM,aAAa,GAAG,IAAI,CAAC,GAAG,CAC5B,CAAC,EACD,KAAK,CAAC,WAAW,GAAG,KAAK,CAAC,eAAe,GAAG,KAAK,CAAC,mBAAmB,CACtE,CAAC;IACF,MAAM,IAAI,GACR,CAAC,GAAG,CAAC,KAAK,CAAC,GAAG,aAAa;QACzB,GAAG,CAAC,MAAM,CAAC,GAAG,KAAK,CAAC,YAAY;QAChC,GAAG,CAAC,SAAS,IAAI,KAAK,CAAC,GAAG,KAAK,CAAC,eAAe;QAC/C,GAAG,CAAC,UAAU,IAAI,KAAK,CAAC,GAAG,KAAK,CAAC,mBAAmB,CAAC;QACvD,WAAW,CAAC;IACd,+EAA+E;IAC/E,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,GAAG,GAAG,CAAC,GAAG,GAAG,CAAC;AACtC,CAAC;AAED,iEAAiE;AACjE,MAAM,UAAU,cAAc,CAC5B,KAAiB,EACjB,KAA+B,EAC/B,KAAyB;IAEzB,MAAM,OAAO,GAAG,cAAc,CAAC,KAAK,EAAE,mBAAmB,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC,CAAC;IACzE,OAAO,EAAE,GAAG,KAAK,EAAE,GAAG,CAAC,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC;AACrE,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,YAAY,CAAC,CAAe,EAAE,CAAe;IAC3D,MAAM,OAAO,GACX,CAAC,CAAC,OAAO,KAAK,SAAS,IAAI,CAAC,CAAC,OAAO,KAAK,SAAS;QAChD,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,OAAO,IAAI,CAAC,CAAC,CAAC,GAAG,GAAG,CAAC,GAAG,GAAG;QAC/D,CAAC,CAAC,SAAS,CAAC;IAChB,OAAO,EAAE,GAAG,QAAQ,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,GAAG,CAAC,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC;AAC9E,CAAC;AAED,0FAA0F;AAC1F,MAAM,UAAU,WAAW,CAAC,OAAqB;IAC/C,MAAM,CAAC,GAAG,CAAC,KAAa,EAAU,EAAE,CAAC,KAAK,CAAC,cAAc,CAAC,OAAO,CAAC,CAAC;IACnE,MAAM,KAAK,GAAG;QACZ,MAAM,CAAC,CAAC,OAAO,CAAC,WAAW,CAAC,EAAE;QAC9B,OAAO,CAAC,CAAC,OAAO,CAAC,YAAY,CAAC,EAAE;QAChC,WAAW,CAAC,CAAC,OAAO,CAAC,eAAe,CAAC,MAAM,CAAC,CAAC,OAAO,CAAC,mBAAmB,CAAC,EAAE;KAC5E,CAAC;IACF,IAAI,OAAO,CAAC,OAAO,KAAK,SAAS,EAAE,CAAC;QAClC,KAAK,CAAC,IAAI,CAAC,IAAI,OAAO,CAAC,OAAO,GAAG,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;IACrG,CAAC;IACD,OAAO,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;AAC3B,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,kEAAkE;AAClE,MAAM,QAAQ,GAAG,cAAc,CAAC;AAgBhC,8EAA8E;AAC9E,MAAM,UAAU,kBAAkB,CAAC,UAA8C,EAAE;IACjF,MAAM,QAAQ,GAAG,IAAI,GAAG,EAAwB,CAAC;IAEjD,OAAO;QACL,OAAO,EAAE,CAAC,KAAK,EAAE,EAAE;YACjB,IAAI,KAAK,CAAC,IAAI,KAAK,aAAa,EAAE,CAAC;gBACjC,MAAM,GAAG,GAAG,KAAK,CAAC,SAAS,IAAI,QAAQ,CAAC;gBACxC,QAAQ,CAAC,GAAG,CACV,GAAG,EACH,YAAY,CAAC,QAAQ,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,UAAU,EAAE,EAAE;oBAC9C,WAAW,EAAE,KAAK,CAAC,WAAW;oBAC9B,YAAY,EAAE,KAAK,CAAC,YAAY;oBAChC,eAAe,EAAE,KAAK,CAAC,eAAe,IAAI,CAAC;oBAC3C,mBAAmB,EAAE,KAAK,CAAC,mBAAmB,IAAI,CAAC;oBACnD,GAAG,CAAC,KAAK,CAAC,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;iBACnE,CAAC,CACH,CAAC;YACJ,CAAC;YACD,OAAO,CAAC,OAAO,EAAE,CAAC,KAAK,CAAC,CAAC;QAC3B,CAAC;QACD,MAAM,EAAE,CAAC,SAAS,EAAE,EAAE,CACpB,SAAS,KAAK,SAAS;YACrB,CAAC,CAAC,CAAC,QAAQ,CAAC,GAAG,CAAC,SAAS,CAAC,IAAI,UAAU,EAAE,CAAC;YAC3C,CAAC,CAAC,CAAC,GAAG,QAAQ,CAAC,MAAM,EAAE,CAAC,CAAC,MAAM,CAAC,YAAY,EAAE,UAAU,EAAE,CAAC;QAC/D,SAAS,EAAE,GAAG,EAAE,CAAC,IAAI,GAAG,CAAC,QAAQ,CAAC;QAClC,KAAK,EAAE,CAAC,SAAS,EAAE,EAAE;YACnB,IAAI,SAAS,KAAK,SAAS;gBAAE,QAAQ,CAAC,KAAK,EAAE,CAAC;;gBACzC,QAAQ,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;QAClC,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/core/workspace-context.d.ts

@@ -0,0 +1,136 @@
+import { type BackendProtocolV2 } from "deepagents";
+import { type SessionStore } from "./session-store.js";
+import { SessionZoneRouter } from "./session-zone.js";
+import { Workspace } from "./workspace.js";
+import { type MountPrefixes, type MountSpec } from "./mounts.js";
+export interface WorkspaceContextOptions {
+    /**
+     * Agent workspace root: where the zero-config filesystem defaults — the
+     * conventional mount table, the `sessions/` store, the authoring backend —
+     * are built. With **none** of `backend`, `mounts`, `sessionStore` and
+     * `authoring` supplied it defaults to the consumer's current working
+     * directory, as documented. Once any of them is supplied, a default that still
+     * needs a root is refused with {@link WorkspaceRootRequiredError} rather than
+     * built over the cwd; and when nothing needs one, none is resolved
+     * ({@link WorkspaceContext.rootDir} is absent).
+     */
+    rootDir?: string;
+    /**
+     * Declares that authored content comes from somewhere other than the local
+     * filesystem root — a store, sandbox, or remote Deep Agents backend.
+     *
+     * Supplying it does **not** by itself serve anything: this backend reaches the
+     * workspace only through the `mounts` table below, and its presence is what
+     * withdraws every zero-config default (the conventional mount table, the local
+     * `<rootDir>/sessions` store). Omit it for a filesystem
+     * workspace, where those defaults apply.
+     */
+    backend?: BackendProtocolV2;
+    /**
+     * Physical storage for the writable session zone — the agent's workspace root
+     * (checkpoints, artifacts, output, scratchpad, offloaded context). With the
+     * default authored backend this defaults to a filesystem store at
+     * `<rootDir>/sessions`; with a custom authored `backend` it is required — assembly
+     * throws {@link SessionStoreRequiredError} rather than silently running without
+     * session-scoped run routing or writing to local disk beside a virtual
+     * workspace.
+     */
+    sessionStore?: SessionStore;
+    /**
+     * Authored mounts as a {@link CompositeBackend} route table: key → backend, or
+     * `{ backend, readOnly }`. A key ending in `/` is a directory mount; a key
+     * without one (`"/AGENTS.md"`) is an exact-path file mount. Mounts are
+     * read-only unless a spec declares otherwise.
+     *
+     * Omitted on the default filesystem backend, {@link defaultMounts} is applied
+     * over the workspace root. Omitted with a custom `backend`, nothing authored is
+     * served — exposing that backend is an explicit act (compose it with
+     * `mountSubtree(backend, "skills")`).
+     */
+    mounts?: Record<string, MountSpec>;
+    /**
+     * Backend serving the **authored governance plane** — `workflows/<slug>/`:
+     * machine specs, prose addenda, lifecycle hook scripts, and offline test
+     * cases. Read by the runtime, never routed into the agent's workspace
+     * composite, so no agent tool and no PTC call can address it.
+     *
+     * Defaults to the authored `backend` when one is supplied, and otherwise to a
+     * filesystem backend over the resolved root. Declaring it separately is what
+     * lets governance live somewhere the agent's workspace does not: a store, a
+     * service, a signed bundle.
+     */
+    authoring?: BackendProtocolV2;
+}
+/**
+ * Thrown when the authoring backend is also served by a **writable** mount. A
+ * writable route onto the authoring backend would let a session edit the machine
+ * that governs it, which no downstream rule can undo — so it is refused at
+ * assembly rather than diagnosed later.
+ */
+export declare class AuthoringBackendExposedError extends Error {
+    readonly key: string;
+    constructor(key: string);
+}
+/** @deprecated Older spelling of {@link AuthoringBackendExposedError}; kept for one release. Same class. */
+export declare const AuthoringPlaneExposedError: typeof AuthoringBackendExposedError;
+/**
+ * Thrown when a workspace is partly composed — some of `mounts`, `sessionStore`
+ * and `authoring` supplied, no `backend` — and a filesystem default for the rest
+ * would have to be built over the process's working directory because no
+ * `rootDir` was given. A service's cwd is not an agent root; the option that
+ * needed one is named so the caller supplies it, or the source it stands for.
+ */
+export declare class WorkspaceRootRequiredError extends Error {
+    readonly option: "mounts" | "sessionStore" | "authoring";
+    constructor(option: "mounts" | "sessionStore" | "authoring");
+}
+/**
+ * Resolved workspace context shared by assembly, scaffold validation,
+ * and offline test execution. Centralizing this keeps root resolution, backend
+ * selection, platform-prompt directory choice, and run-store resolution
+ * consistent across every entrypoint.
+ */
+export interface WorkspaceContext {
+    /**
+     * Absolute resolved workspace root — present when one was given or when a
+     * filesystem default was built over it; absent when every source was supplied
+     * and nothing was read from local disk to compose this context.
+     */
+    rootDir?: string;
+    /** Backend serving workspace file access. */
+    backend: BackendProtocolV2;
+    /** Workspace wrapper over {@link backend}. */
+    workspace: Workspace;
+    /**
+     * Workspace over the authoring backend — the runtime's read path for
+     * `workflows/**`. Deliberately *not* the agent's {@link workspace}: nothing
+     * reachable from here is reachable from a tool call.
+     */
+    authoring: Workspace;
+    /** The resolved session store (explicit, or the zero-config filesystem default). */
+    sessionStore: SessionStore;
+    /** Whether the authored source is the default filesystem backend over `rootDir`. */
+    usingDefaultBackend: boolean;
+    /**
+     * This workspace's resolved mount keys — the single source every consumer
+     * classifies against: mount routing, agent-visible root shaping, the decision
+     * kernel's zone rules, and static validation. Derived from the very keys the
+     * composite routes on, so the two cannot drift.
+     */
+    mountPrefixes: MountPrefixes;
+    /**
+     * Router serving the workspace root's session-scoped, id-free addressing. Bind
+     * it to a session id (`sessionScoped`) around a turn's `agent.invoke` so
+     * agent-visible `scratchpad/…` and offload paths for that turn
+     * resolve against that session without the session id embedded.
+     */
+    sessionZone: SessionZoneRouter;
+}
+/**
+ * Build a {@link WorkspaceContext} from caller options. With no custom backend,
+ * a filesystem backend is created over the resolved root, the platform prompt
+ * directory defaults to the bundled platform assets, and the session store
+ * defaults to `<rootDir>/sessions` on the local filesystem. With a custom backend,
+ * an explicit {@link SessionStore} is required.
+ */
+export declare function createWorkspaceContext(options?: WorkspaceContextOptions): WorkspaceContext;

package/dist/core/workspace-context.js

@@ -0,0 +1,178 @@
+import { join } from "node:path";
+import { CompositeBackend, FilesystemBackend } from "deepagents";
+import { resolveWorkspaceRoot } from "../env.js";
+import { mountSubtree } from "./path-mapping.js";
+import { createFilesystemSessionStore, DEFAULT_SESSIONS_DIR, SessionStoreRequiredError, } from "./session-store.js";
+import { SessionZoneRouter } from "./session-zone.js";
+import { Workspace } from "./workspace.js";
+import { createWorkspaceRouter } from "./workspace-router.js";
+import { defaultMounts, resolveMounts, } from "./mounts.js";
+/**
+ * Thrown when the authoring backend is also served by a **writable** mount. A
+ * writable route onto the authoring backend would let a session edit the machine
+ * that governs it, which no downstream rule can undo — so it is refused at
+ * assembly rather than diagnosed later.
+ */
+export class AuthoringBackendExposedError extends Error {
+    key;
+    constructor(key) {
+        super(`Mount '${key}' is writable and is served by the same backend as the authoring backend. ` +
+            `The authoring backend must not be agent-writable — mount a different backend, or declare ` +
+            `the mount read-only.`);
+        this.key = key;
+        this.name = "AuthoringBackendExposedError";
+    }
+}
+/** @deprecated Older spelling of {@link AuthoringBackendExposedError}; kept for one release. Same class. */
+export const AuthoringPlaneExposedError = AuthoringBackendExposedError;
+/**
+ * Thrown when a workspace is partly composed — some of `mounts`, `sessionStore`
+ * and `authoring` supplied, no `backend` — and a filesystem default for the rest
+ * would have to be built over the process's working directory because no
+ * `rootDir` was given. A service's cwd is not an agent root; the option that
+ * needed one is named so the caller supplies it, or the source it stands for.
+ */
+export class WorkspaceRootRequiredError extends Error {
+    option;
+    constructor(option) {
+        super(`No 'rootDir' was given, and the filesystem default for '${option}' needs one. ` +
+            `The working directory is not used as an agent root once the workspace is composed ` +
+            `explicitly: pass 'rootDir', or supply '${option}' yourself.`);
+        this.option = option;
+        this.name = "WorkspaceRootRequiredError";
+    }
+}
+/**
+ * Build a {@link WorkspaceContext} from caller options. With no custom backend,
+ * a filesystem backend is created over the resolved root, the platform prompt
+ * directory defaults to the bundled platform assets, and the session store
+ * defaults to `<rootDir>/sessions` on the local filesystem. With a custom backend,
+ * an explicit {@link SessionStore} is required.
+ */
+export function createWorkspaceContext(options = {}) {
+    // Nothing serves `options.backend` directly: a custom authored backend reaches
+    // the workspace only where the consumer mounts it (see `mounts`). What its
+    // presence decides here is that this is not the zero-config filesystem
+    // workspace — so neither the conventional mount table, the local session store,
+    // nor the bundled platform directory may be assumed.
+    const usingDefaultBackend = options.backend === undefined;
+    // Which filesystem defaults this call would build over a root. The cwd stands
+    // in for a root only in the fully zero-config case; a workspace the caller has
+    // started composing gets no silent root, and one composed entirely gets none at all.
+    const defaults = usingDefaultBackend
+        ? ["mounts", "sessionStore", "authoring"].filter((option) => options[option] === undefined)
+        : [];
+    const composed = options.backend !== undefined ||
+        options.mounts !== undefined ||
+        options.sessionStore !== undefined ||
+        options.authoring !== undefined;
+    let rootDir;
+    if (options.rootDir !== undefined)
+        rootDir = resolveWorkspaceRoot(options.rootDir);
+    else if (defaults.length > 0) {
+        if (composed)
+            throw new WorkspaceRootRequiredError(defaults[0]);
+        rootDir = resolveWorkspaceRoot();
+    }
+    /** The root a filesystem default is built over; only reached when one was resolved above. */
+    const rootFor = (option) => {
+        if (rootDir === undefined)
+            throw new WorkspaceRootRequiredError(option);
+        return rootDir;
+    };
+    // The consumer owns physical run-state storage; the SDK owns the logical
+    // namespace. Zero-config (default backend, no store) keeps the documented
+    // local default; a custom backend must name its store explicitly — never
+    // infer storage or drop session routing based on how the authored backend
+    // was supplied.
+    if (!usingDefaultBackend && options.sessionStore === undefined) {
+        throw new SessionStoreRequiredError();
+    }
+    const sessionStore = options.sessionStore ??
+        createFilesystemSessionStore({ dir: join(rootFor("sessionStore"), DEFAULT_SESSIONS_DIR) });
+    // The session zone is the workspace root: checkpoints, artifacts, governed
+    // the agent's `scratchpad/…` working area and the runtime's context-offload
+    // areas all resolve per session through one router. Authored content is
+    // mounted read-only beside it — each mount maps paths in both directions so
+    // the authored backend sees authored paths and results come back in
+    // workspace form.
+    const sessionZone = new SessionZoneRouter(sessionStore.backend);
+    // Which directories are authored is workspace shape, not framework knowledge:
+    // the consumer composes a route table of backends. The conventional table is a
+    // default value applied only on the zero-config filesystem path.
+    const table = options.mounts ?? (usingDefaultBackend ? defaultMounts(rootFor("mounts")) : {});
+    const { mounts, prefixes: mountPrefixes } = resolveMounts(table);
+    // Directory mounts become composite routes; file mounts are matched exactly by
+    // the router, since a prefix route can neither address a single file nor
+    // distinguish `AGENTS.md` from `AGENTS.md.bak`.
+    const dirMounts = mounts.filter((m) => m.isDir);
+    const routes = Object.fromEntries(dirMounts.map((m) => [m.key, guard(m)]));
+    const fileMounts = new Map(mounts.filter((m) => !m.isDir).map((m) => [m.name, guard(m)]));
+    const composite = new CompositeBackend(sessionZone, routes);
+    // A root-wide search fans out to every route the composite has, and one
+    // route's `{ error }` is fatal to the whole search. A mount declared
+    // `searchable: false` is therefore left out of the composite that serves
+    // searches — the same default route and the same guarded route objects, so
+    // nothing else about routing differs — and reached only by a search
+    // addressed at it, which the router delegates to the route directly. With
+    // no such mount the search composite *is* the routing composite, so an
+    // existing table behaves byte-identically.
+    const unsearchable = dirMounts.filter((m) => !m.searchable);
+    const searchComposite = unsearchable.length === 0
+        ? composite
+        : new CompositeBackend(sessionZone, Object.fromEntries(dirMounts.filter((m) => m.searchable).map((m) => [m.key, routes[m.key]])));
+    const unsearchableRoutes = new Map(unsearchable.map((m) => [m.name, routes[m.key]]));
+    const backend = createWorkspaceRouter({
+        composite,
+        searchComposite,
+        unsearchableRoutes,
+        fileMounts,
+        mountPrefixes,
+        boundSessionId: () => sessionZone.boundSessionId(),
+    });
+    const workspace = new Workspace(backend);
+    // The governance plane is served beside the agent's workspace, never inside
+    // it. With a custom authored backend that backend is the natural source (it
+    // already holds the authored tree); the agent still cannot reach `workflows/**`
+    // through it, because the composite has no route there and `resolveMounts`
+    // refuses one.
+    const authoringBackend = options.authoring ??
+        options.backend ??
+        new FilesystemBackend({ rootDir: rootFor("authoring"), virtualMode: true });
+    for (const mount of mounts) {
+        if (!mount.readOnly && mount.backend === authoringBackend) {
+            throw new AuthoringBackendExposedError(mount.key);
+        }
+    }
+    const authoring = new Workspace(authoringBackend);
+    return {
+        ...(rootDir !== undefined ? { rootDir } : {}),
+        backend,
+        workspace,
+        authoring,
+        sessionStore,
+        usingDefaultBackend,
+        sessionZone,
+        mountPrefixes,
+    };
+}
+/**
+ * A read-only mount refuses writes at the mount itself, so authored content
+ * cannot be modified even by a caller that bypasses governance; the kernel's
+ * `zone.read-only` rule remains the agent-facing diagnostic. A mount the consumer
+ * declared writable is delegated as-is.
+ *
+ * A directory mount is addressed with its route prefix already stripped by the
+ * composite, so the refusal is told that prefix (`data`) to re-apply when naming
+ * the rejected path; a file mount is addressed by its exact key, which needs no
+ * re-application.
+ */
+function guard(mount) {
+    return mount.readOnly
+        ? mountSubtree(mount.backend, "", {
+            readOnly: true,
+            ...(mount.isDir ? { displayPrefix: mount.name } : {}),
+        })
+        : mount.backend;
+}
+//# sourceMappingURL=workspace-context.js.map