@open-everywhere/core 0.1.0

package/dist/agent/spend/store.d.ts

@@ -0,0 +1,139 @@
+import { type Partition } from "../memory/partition.js";
+import { type Usage } from "./spend.js";
+import { type SurfaceDisclosure } from "./dm-mask.js";
+import type { SpendLedgerFilter, SpendTotals, SurfaceMode } from "../operational/store.js";
+/** Inspectable backing location (sqlite path / "postgres") — for logging + views. */
+export declare function spendRoot(): string;
+/** One spend increment, as the RECORDING paths express it (the store's raw
+ *  SpendLedgerWrite plus the two rules this adapter owns — grain + pricing). */
+export interface SpendEntry {
+    /** Calendar month, "YYYY-MM" (spend.ts periodOf). */
+    readonly period: string;
+    readonly usage: Usage;
+    /** The acting principal; absent/'' = unattributed. */
+    readonly principalId?: string;
+    /** The routine this spend belongs to; absent/'' = not a routine turn. */
+    readonly routineId?: string;
+    /** The model this call ran on (the item-17 stamp); absent/'' = no model. */
+    readonly model?: string;
+    /**
+     * WHICH KIND OF CONVERSATION this spend happened in (OPE-1862) — read from the turn's own
+     * binding (`bindFrom(ctx).mode`), never from the shape of the surface id. It is what lets a
+     * report collapse a Discord or Teams DM into the `(dms)` bucket exactly as it collapses a
+     * Slack one.
+     *
+     * Absent ⇒ the row keeps whatever mode it already carries, and a new row is UNSTAMPED. Every
+     * report masks an unstamped row rather than name a surface it cannot classify, so a writer
+     * that can resolve the mode should pass it.
+     */
+    readonly surfaceMode?: SurfaceMode;
+    /**
+     * Explicit USD (micros) for NON-model spend — sandbox runtime (OPE-266), where no
+     * (model, tokens) key can express the cost. When absent, the entry is priced at
+     * write from tokens + model (pricing.ts usdMicrosAtWrite: the model's own rate, the
+     * sole-priced-model fallback for a stampless call, $0 for an unpriced model — never
+     * a guessed rate).
+     */
+    readonly usdMicros?: number;
+    /**
+     * The GATEWAY-MEASURED cost of this increment, in USD (OPE-369) — `usage.costUsd` as eve
+     * delivered it. Supplying it does NOT displace the derived figure: the row still stores a
+     * rate-derived `usd_micros` (so every cap keeps its denomination), and this lands beside it in
+     * `usd_micros_measured` with `cost_source = 'measured'`. Absent ⇒ the row is stamped 'derived'.
+     */
+    readonly measuredUsd?: number;
+}
+/** Record one spend increment against its (org, surface, principal, routine, model,
+ *  period) ledger row (atomic upsert-and-add). SPEND grain = domainKeyOf(p): a Discord
+ *  thread's usage accumulates against its PARENT channel's key — the scope caps are
+ *  declared and gated on (spend/check.ts reads the same grain) — matching Slack, where
+ *  threads share the channel key (item 22). Everywhere else the domain key IS the
+ *  surfaceKey. */
+export declare function recordSpend(p: Partition, entry: SpendEntry): Promise<void>;
+/** Billable tokens for one surface in a period (scoped to its org). */
+export declare function surfaceTokens(org: string, surfaceKey: string, period: string): Promise<number>;
+/** Billable tokens for a whole workspace in a period (all its surfaces, DMs included, within one org). */
+export declare function workspaceTokens(org: string, workspaceKey: string, period: string): Promise<number>;
+/** Estimated USD spent by one surface in a period — the ledger's write-time-priced
+ *  `usd_micros` sum (model spend + sandbox runtime), as dollars. */
+export declare function surfaceUsd(org: string, surfaceKey: string, period: string): Promise<number>;
+/** Estimated USD spent by a whole workspace in a period (all its surfaces, DMs included). */
+export declare function workspaceUsd(org: string, workspaceKey: string, period: string): Promise<number>;
+/**
+ * ONE PERSON's spend within ONE surface for a period — the person axis's read (OPE-268,
+ * spend/spend.ts checkCap). Both denominations come back from a SINGLE keyed sum because they
+ * are two columns of the same rows; splitting it into `principalSurfaceTokens` +
+ * `principalSurfaceUsd` (mirroring the surface/workspace helpers above) would double the query
+ * count on the one path that runs per DM turn, for no gain in clarity.
+ *
+ * ⭐ THIS IS THE DIMENSION OPE-265 ADDED. Before the ledger carried `principal_id`, "what has
+ * this person spent here" was not a keyed sum at all — it would have meant scanning
+ * usage_events, which no cap path is allowed to touch. The cap and the ledger therefore agree by
+ * construction: the number compared against a person's budget is the same number their rows
+ * contributed to the surface total.
+ *
+ * EXACT surface match (like surfaceTokens/surfaceUsd, not a prefix), and `principalId` is
+ * matched exactly — `""` is the ledger's UNATTRIBUTED marker, so passing it would sum the spend
+ * that belongs to nobody, which is never what a per-person cap means. Callers pass a real id or
+ * skip the axis entirely.
+ */
+export declare function principalSurfaceSpend(org: string, surfaceKey: string, principalId: string, period: string): Promise<{
+    tokens: number;
+    usd: number;
+}>;
+/** Arbitrary keyed SUM over one org's ledger — the general read behind the helpers
+ *  above (a routine's month, one principal's DM spend, …). */
+export declare function spendTotals(org: string, filter?: SpendLedgerFilter): Promise<SpendTotals>;
+/** One (org, surface, period) rollup line — what the report/admin views render. The
+ *  ledger's rows are finer-grained (principal × routine × model); this re-aggregates
+ *  them to the surface grain the old one-row-per-surface ledger used to hold. */
+export interface SurfacePeriodSpend {
+    readonly org: string;
+    readonly surfaceKey: string;
+    readonly period: string;
+    /** Billable tokens (input + output). */
+    readonly tokens: number;
+    /** Estimated USD (write-time-priced usd_micros, as dollars) — model spend + sandbox runtime.
+     *  ALWAYS the DERIVED figure, measured rows included: this is the number the caps enforce. */
+    readonly usd: number;
+    /** USD the GATEWAY measured, across this bucket's `cost_source = 'measured'` rows only (OPE-369).
+     *  0 when nothing here was measured. */
+    readonly usdMeasured: number;
+    /** The DERIVED figure for exactly those same measured rows — the comparable half of the drift
+     *  pair. Deliberately NOT `usd` (which also carries every unmeasured row, so comparing it against
+     *  `usdMeasured` would report divergence that is really just coverage). */
+    readonly usdDerivedOnMeasured: number;
+    /** Calls whose cost the gateway measured (a subset of `calls`). */
+    readonly measuredCalls: number;
+    readonly calls: number;
+    /** WHAT THIS LINE MAY BE PUBLISHED AS (OPE-1862) — folded from the conversation mode of the rows
+     *  behind it (spend/dm-mask.ts `foldDisclosure`), because this rollup drops the per-row stamp
+     *  the report mask reads. Without it every ledger line would reach the report unclassified. */
+    readonly disclosure: SurfaceDisclosure;
+}
+/**
+ * The (org, surface, period) rollup lines — for the admin views (spendView) + the report
+ * continuity tables.
+ *
+ * 🔴 PASS `org` ON ANY PATH A REMOTE CALLER CAN REACH (OPE-1446). Omitting it rolls up EVERY
+ * org's ledger rows, and a ledger row names a surface (`platform/workspace/channel`) with its
+ * token and USD totals. `spendView` — the read behind the `spend_report` control tool — omitted
+ * it, so a read-only service token (minted with roles `["admin"]`) received every tenant's spend.
+ * The org is not a role question and never a caller argument: it is a property of the deployment,
+ * read from `deploymentOrg()` exactly as `audit_query` reads it (control/auth.ts's
+ * `foreignOrgDenial` carries the full argument). `spend_report`'s room-side twin passes its
+ * resolved partition org for the same reason. The no-arg form is for the LOCAL operator scripts
+ * (scripts/spend.ts), which are cross-org by design.
+ *
+ * 🔴 PASS THE PERIOD TOO (OPE-1653). `filter` reaches the store's list read, so both adapters
+ * bound the read IN THE QUERY. Left out, this rolls up the org's whole ledger history and every
+ * caller that renders one month pays for every month ever written. A caller that renders one
+ * period passes `{ period }`; a caller with a window spanning one or two calendar months passes
+ * `{ periodFrom, periodTo }` (inclusive, "YYYY-MM" — see {@link SpendLedgerFilter}).
+ *
+ * The filter narrows the ROWS READ, never the aggregation: the returned lines are still keyed by
+ * (org, surface, period), so a caller that passes a two-month range still gets one line per month
+ * and must not read the result as a single period.
+ */
+export declare function spendRollup(org?: string, filter?: SpendLedgerFilter): Promise<SurfacePeriodSpend[]>;
+//# sourceMappingURL=store.d.ts.map

package/dist/agent/spend/store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../../../agent/spend/store.ts"],"names":[],"mappings":"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"}

package/dist/agent/spend/store.js

@@ -0,0 +1,180 @@
+// Durable spend ledger — the DB-backed CAP store (OPE-265 redesign; see
+// operational/store.ts's spend_ledger section for the schema rationale). Operator pays
+// all inference, so per-surface / per-workspace budgets are a real guardrail; this is
+// the durable side of that (the pure accounting is spend.ts, recording is the spend
+// hook + the sandbox lifecycle adapter, enforcement is the inbound handler). Org is the
+// outermost partition (org_id column); one tenant can't read or aggregate another's
+// usage at rest.
+//
+// This file is a thin adapter over the OperationalStore seam (SQLite local / Postgres
+// deploy): the write applies SPEND GRAIN + write-time pricing, the reads are the SUMs
+// every cap denomination consults, plus the per-(org, surface, period) rollup the
+// report/admin views aggregate from.
+import { domainKeyOf } from "../memory/partition.js";
+import { billableTokens } from "./spend.js";
+import { usdMicrosAtWrite } from "./pricing.js";
+import { foldDisclosure } from "./dm-mask.js";
+import { getOperationalStore } from "../operational/provider.js";
+/** Inspectable backing location (sqlite path / "postgres") — for logging + views. */
+export function spendRoot() {
+    return getOperationalStore().root();
+}
+/** Record one spend increment against its (org, surface, principal, routine, model,
+ *  period) ledger row (atomic upsert-and-add). SPEND grain = domainKeyOf(p): a Discord
+ *  thread's usage accumulates against its PARENT channel's key — the scope caps are
+ *  declared and gated on (spend/check.ts reads the same grain) — matching Slack, where
+ *  threads share the channel key (item 22). Everywhere else the domain key IS the
+ *  surfaceKey. */
+export async function recordSpend(p, entry) {
+    const model = entry.model ?? "";
+    // WRITE-TIME PRICING IS FULLY SYNCHRONOUS (OPE-1148, replacing OPE-275's readiness await).
+    // Every rate is now code — the deployer table (agent/spend/model-pricing.ts) plus core's
+    // BUILT_IN — registered at boot before the first turn, so `usdMicrosAtWrite` can never resolve
+    // undefined because a fetch has not landed yet. That race was the whole reason this line used
+    // to await: a ledger row's $0 is PERMANENT (a read prices again next call; a written row does
+    // not), so every cold-instance step before the live catalog's first fetch under-counted the USD
+    // caps forever. With the catalog source deleted, the race cannot occur — and a model the
+    // COMMITTED config selects with no rate is now a red build (`lint:model-ids` RULE 4) rather than
+    // a silent $0 here. A model reached only through an env pin is outside what any offline gate can
+    // see, and still lands $0 — evidence-only, as before.
+    const usdMicros = entry.usdMicros ?? usdMicrosAtWrite(entry.usage, model || undefined);
+    // OPE-369 — the measured figure is recorded BESIDE the derived one, never instead of it, and the
+    // derived pricing above runs unconditionally either way. Two reasons, both load-bearing:
+    //   • CAP CONTINUITY. `usd_micros` is the one column every cap denomination sums (spend/check.ts).
+    //     If a measured row stopped writing it, a deployment's caps would silently start counting only
+    //     its unmeasured traffic — the "configured but unenforced budget" failure this package spends
+    //     most of its prose refusing. Measured cost is a gateway feature; a cap may not depend on one.
+    //   • DRIFT FOR FREE. Storing both on a row whose `cost_source` is part of the key makes the pair
+    //     comparable call-for-call, which is the whole basis of summariseCostDrift. The moment the two
+    //     disagree, the rate table is wrong — and that is a finding, not a rounding error.
+    // Micros are rounded the same way pricing.ts rounds a derived cost, so the two are commensurable.
+    const measuredMicros = entry.measuredUsd !== undefined && Number.isFinite(entry.measuredUsd) ? Math.round(entry.measuredUsd * 1_000_000) : undefined;
+    await getOperationalStore().recordSpend(p.org, {
+        surfaceKey: domainKeyOf(p),
+        principalId: entry.principalId ?? "",
+        routineId: entry.routineId ?? "",
+        model,
+        period: entry.period,
+        // OPE-1862 — the anti-doxxing fact. Omitted when the writer had no binding to read it from;
+        // the upsert then leaves an existing row's mode alone (operational/*.ts UPSERT_SPEND).
+        ...(entry.surfaceMode !== undefined ? { surfaceMode: entry.surfaceMode } : {}),
+        inputTokens: entry.usage.inputTokens ?? 0,
+        outputTokens: entry.usage.outputTokens ?? 0,
+        cacheReadTokens: entry.usage.cacheReadTokens ?? 0,
+        cacheWriteTokens: entry.usage.cacheWriteTokens ?? 0,
+        // OPE-1611 — ATTRIBUTION, and it deliberately does NOT reach `usdMicros` above: no rate table
+        // names a reasoning rate, so pricing these tokens would assert a number nothing billed. The
+        // dimension says where the tokens went; `usd_micros` (derived) and `usd_micros_measured` (the
+        // gateway's bill) keep saying what the call cost, exactly as before.
+        reasoningTokens: entry.usage.reasoningTokens ?? 0,
+        usdMicros,
+        ...(measuredMicros !== undefined ? { usdMicrosMeasured: measuredMicros, costSource: "measured" } : { costSource: "derived" }),
+    });
+}
+/** Billable tokens for one surface in a period (scoped to its org). */
+export async function surfaceTokens(org, surfaceKey, period) {
+    return billableTokens(await getOperationalStore().spendTotals(org, { surfaceKey, period }));
+}
+/** Billable tokens for a whole workspace in a period (all its surfaces, DMs included, within one org). */
+export async function workspaceTokens(org, workspaceKey, period) {
+    return billableTokens(await getOperationalStore().spendTotals(org, { surfaceKeyPrefix: `${workspaceKey}/`, period }));
+}
+/** Estimated USD spent by one surface in a period — the ledger's write-time-priced
+ *  `usd_micros` sum (model spend + sandbox runtime), as dollars. */
+export async function surfaceUsd(org, surfaceKey, period) {
+    return (await getOperationalStore().spendTotals(org, { surfaceKey, period })).usdMicros / 1_000_000;
+}
+/** Estimated USD spent by a whole workspace in a period (all its surfaces, DMs included). */
+export async function workspaceUsd(org, workspaceKey, period) {
+    return (await getOperationalStore().spendTotals(org, { surfaceKeyPrefix: `${workspaceKey}/`, period })).usdMicros / 1_000_000;
+}
+/**
+ * ONE PERSON's spend within ONE surface for a period — the person axis's read (OPE-268,
+ * spend/spend.ts checkCap). Both denominations come back from a SINGLE keyed sum because they
+ * are two columns of the same rows; splitting it into `principalSurfaceTokens` +
+ * `principalSurfaceUsd` (mirroring the surface/workspace helpers above) would double the query
+ * count on the one path that runs per DM turn, for no gain in clarity.
+ *
+ * ⭐ THIS IS THE DIMENSION OPE-265 ADDED. Before the ledger carried `principal_id`, "what has
+ * this person spent here" was not a keyed sum at all — it would have meant scanning
+ * usage_events, which no cap path is allowed to touch. The cap and the ledger therefore agree by
+ * construction: the number compared against a person's budget is the same number their rows
+ * contributed to the surface total.
+ *
+ * EXACT surface match (like surfaceTokens/surfaceUsd, not a prefix), and `principalId` is
+ * matched exactly — `""` is the ledger's UNATTRIBUTED marker, so passing it would sum the spend
+ * that belongs to nobody, which is never what a per-person cap means. Callers pass a real id or
+ * skip the axis entirely.
+ */
+export async function principalSurfaceSpend(org, surfaceKey, principalId, period) {
+    const totals = await getOperationalStore().spendTotals(org, { surfaceKey, principalId, period });
+    return { tokens: billableTokens(totals), usd: totals.usdMicros / 1_000_000 };
+}
+/** Arbitrary keyed SUM over one org's ledger — the general read behind the helpers
+ *  above (a routine's month, one principal's DM spend, …). */
+export async function spendTotals(org, filter = {}) {
+    return getOperationalStore().spendTotals(org, filter);
+}
+/** Aggregate raw ledger rows to (org, surface, period) grain (pure — testable without a store).
+ *  Collapses the `cost_source` key rung, keeping the measured half separately addressable so the
+ *  drift read (spend/reporting.ts summariseCostDrift) still has an apples-to-apples pair. */
+function aggregateSpendBySurfacePeriod(rows) {
+    const byKey = new Map();
+    for (const r of rows) {
+        const k = `${r.org}\u0000${r.surfaceKey}\u0000${r.period}`;
+        const acc = byKey.get(k) ?? { org: r.org, surfaceKey: r.surfaceKey, period: r.period, rows: [], tokens: 0, usdMicros: 0, measuredMicros: 0, derivedOnMeasuredMicros: 0, measuredCalls: 0, calls: 0 };
+        // The rows themselves, kept ONLY to fold their conversation mode (OPE-1862). The sums below
+        // answer "how much"; this answers "may the key be published", and the two cannot be separated
+        // without handing the report a line it cannot classify.
+        acc.rows.push(r);
+        acc.tokens += billableTokens(r);
+        acc.usdMicros += r.usdMicros;
+        acc.calls += r.calls;
+        if (r.costSource === "measured") {
+            acc.measuredMicros += r.usdMicrosMeasured;
+            acc.derivedOnMeasuredMicros += r.usdMicros;
+            acc.measuredCalls += r.calls;
+        }
+        byKey.set(k, acc);
+    }
+    return [...byKey.values()].map((a) => ({
+        org: a.org,
+        surfaceKey: a.surfaceKey,
+        period: a.period,
+        tokens: a.tokens,
+        usd: a.usdMicros / 1_000_000,
+        usdMeasured: a.measuredMicros / 1_000_000,
+        usdDerivedOnMeasured: a.derivedOnMeasuredMicros / 1_000_000,
+        measuredCalls: a.measuredCalls,
+        calls: a.calls,
+        disclosure: foldDisclosure(a.rows),
+    }));
+}
+/**
+ * The (org, surface, period) rollup lines — for the admin views (spendView) + the report
+ * continuity tables.
+ *
+ * 🔴 PASS `org` ON ANY PATH A REMOTE CALLER CAN REACH (OPE-1446). Omitting it rolls up EVERY
+ * org's ledger rows, and a ledger row names a surface (`platform/workspace/channel`) with its
+ * token and USD totals. `spendView` — the read behind the `spend_report` control tool — omitted
+ * it, so a read-only service token (minted with roles `["admin"]`) received every tenant's spend.
+ * The org is not a role question and never a caller argument: it is a property of the deployment,
+ * read from `deploymentOrg()` exactly as `audit_query` reads it (control/auth.ts's
+ * `foreignOrgDenial` carries the full argument). `spend_report`'s room-side twin passes its
+ * resolved partition org for the same reason. The no-arg form is for the LOCAL operator scripts
+ * (scripts/spend.ts), which are cross-org by design.
+ *
+ * 🔴 PASS THE PERIOD TOO (OPE-1653). `filter` reaches the store's list read, so both adapters
+ * bound the read IN THE QUERY. Left out, this rolls up the org's whole ledger history and every
+ * caller that renders one month pays for every month ever written. A caller that renders one
+ * period passes `{ period }`; a caller with a window spanning one or two calendar months passes
+ * `{ periodFrom, periodTo }` (inclusive, "YYYY-MM" — see {@link SpendLedgerFilter}).
+ *
+ * The filter narrows the ROWS READ, never the aggregation: the returned lines are still keyed by
+ * (org, surface, period), so a caller that passes a two-month range still gets one line per month
+ * and must not read the result as a single period.
+ */
+export async function spendRollup(org, filter = {}) {
+    return aggregateSpendBySurfacePeriod(await getOperationalStore().listSpendLedger(org, filter));
+}
+//# sourceMappingURL=store.js.map

package/dist/agent/spend/store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.js","sourceRoot":"","sources":["../../../agent/spend/store.ts"],"names":[],"mappings":"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"}

package/dist/agent/spend/subagent-runs.d.ts

@@ -0,0 +1,79 @@
+import { MAX_OBSERVABLE_DELEGATION_DEPTH, type UsageEventEntry } from "../operational/store.js";
+export { MAX_OBSERVABLE_DELEGATION_DEPTH };
+/** The `usage_events.detail` key under which hooks/spend.ts stamps a delegated child's identity.
+ *  ONE name, shared by the writer and every reader, so a rename cannot silently un-attest. */
+export declare const SUBAGENT_RUN_DETAIL_KEY = "subagentRun";
+/** A delegated child's own identity, as stamped on the row that files under its parent. */
+export interface SubagentRunStamp {
+    /** The PARENT's tool-call id that created this child (eve's `SessionParent.callId`). */
+    readonly callId: string;
+    /** The CHILD's own session id — kept because filing under the parent would otherwise lose it. */
+    readonly sessionId: string;
+    /**
+     * The ROOT (user-facing) session at the top of this delegation chain (OPE-369), from eve's
+     * `SessionParent.rootSessionId`. Optional so a legacy row still parses.
+     *
+     * ⭐ WHY IT MATTERS AND WHAT IT DOESN'T CHANGE. A row files under its IMMEDIATE parent, so a
+     * GRANDCHILD's usage lands under the child session — a session id eve mints per run and nothing
+     * ever queries, which made a grandchild's cost unreachable from the conversation that ultimately
+     * caused it. The filing is deliberately left alone (it is what OPE-263's attestation is built on:
+     * "a delegated child ran under THIS session" is a claim about the immediate parent). The root is
+     * recorded instead, and mirrored onto the row's own `root_session_id` column, so the whole tree
+     * is one grouped read without any hop of the chain being re-interpreted.
+     */
+    readonly rootSessionId?: string;
+    /** How many hops from the root this child ran at — 1 for a direct child, and capped at
+     *  {@link MAX_OBSERVABLE_DELEGATION_DEPTH} for anything deeper (a BAND, not a count: eve
+     *  publishes the root and the immediate parent, never the hop count in between). */
+    readonly depth?: number;
+}
+/** Build the `detail` object for a delegated child's usage row. Optional lineage fields are
+ *  omitted rather than nulled, so a row written where eve gave us nothing extra is byte-identical
+ *  to a pre-OPE-369 one. */
+export declare function stampSubagentRun(run: SubagentRunStamp): Readonly<Record<string, unknown>>;
+/** Read the stamp back off a row, or undefined when the row is not a delegated child's. Total —
+ *  a hand-written or legacy `detail` shape yields undefined rather than a partial stamp. The two
+ *  OPE-369 lineage fields are read PERMISSIVELY (absent or malformed ⇒ simply absent), so a row
+ *  written before they existed still attests everything it always did. */
+export declare function subagentRunOf(row: {
+    readonly detail?: Readonly<Record<string, unknown>>;
+}): SubagentRunStamp | undefined;
+/**
+ * How deep a delegated run sits, from the ONLY lineage eve hands a hook: the immediate parent's
+ * session id and the denormalised root.
+ *
+ * `parentSessionId === rootSessionId` ⇒ this run's parent IS the root, so it is a DIRECT child
+ * (depth 1). Anything else is at least a grandchild, and the exact number of intervening hops is
+ * not observable — so it reports {@link MAX_OBSERVABLE_DELEGATION_DEPTH}, which is documented
+ * everywhere it surfaces as "two or more". An absent root (a legacy/foreign token-derived parent,
+ * where all we recovered was the parent id) degrades to 1: the parent is the deepest ancestor we
+ * can see, which is exactly what depth 1 asserts.
+ */
+export declare function delegationDepthOf(parentSessionId: string, rootSessionId?: string): number;
+/**
+ * Host-side evidence about delegation, for one session. Two states only — there is no "probably".
+ * `absent` always carries the REASON, because "we did not look" and "we looked and there was
+ * nothing" are different things a reader is entitled to tell apart.
+ */
+export type NarrationAttestation = {
+    readonly kind: "ledger";
+    /** Distinct delegated child sessions recorded under this session. */
+    readonly runs: number;
+    /** Rows — approximately model calls — across those children. */
+    readonly events: number;
+    readonly firstTs: string;
+    readonly lastTs: string;
+} | {
+    readonly kind: "absent";
+    readonly reason: string;
+};
+/** PURE: read the evidence out of rows already scoped to one session (org + session id). */
+export declare function attestSubagentRuns(rows: readonly UsageEventEntry[]): NarrationAttestation;
+/**
+ * The evidence for one session, read from the operational store. NEVER THROWS: a store failure is
+ * reported as an absence with the failure as its reason, so a caller cannot accidentally convert
+ * "the database was down" into "an independent reviewer definitely ran" — nor into a hard error that
+ * would delete the rest of a governance document.
+ */
+export declare function readSubagentAttestation(org: string, sessionId: string): Promise<NarrationAttestation>;
+//# sourceMappingURL=subagent-runs.d.ts.map

package/dist/agent/spend/subagent-runs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"subagent-runs.d.ts","sourceRoot":"","sources":["../../../agent/spend/subagent-runs.ts"],"names":[],"mappings":"AAoCA,OAAO,EAAE,+BAA+B,EAAE,KAAK,eAAe,EAAE,MAAM,yBAAyB,CAAC;AAEhG,OAAO,EAAE,+BAA+B,EAAE,CAAC;AAE3C;8FAC8F;AAC9F,eAAO,MAAM,uBAAuB,gBAAgB,CAAC;AAErD,2FAA2F;AAC3F,MAAM,WAAW,gBAAgB;IAC/B,wFAAwF;IACxF,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,iGAAiG;IACjG,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B;;;;;;;;;;;OAWG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC;;wFAEoF;IACpF,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB;AAED;;4BAE4B;AAC5B,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,gBAAgB,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CASzF;AAED;;;0EAG0E;AAC1E,wBAAgB,aAAa,CAAC,GAAG,EAAE;IAAE,QAAQ,CAAC,MAAM,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAA;CAAE,GAAG,gBAAgB,GAAG,SAAS,CAWxH;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,iBAAiB,CAAC,eAAe,EAAE,MAAM,EAAE,aAAa,CAAC,EAAE,MAAM,GAAG,MAAM,CAGzF;AAED;;;;GAIG;AACH,MAAM,MAAM,oBAAoB,GAC5B;IACE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IACxB,qEAAqE;IACrE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,gEAAgE;IAChE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB,GACD;IAAE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAEzD,4FAA4F;AAC5F,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,SAAS,eAAe,EAAE,GAAG,oBAAoB,CAiBzF;AAED;;;;;GAKG;AACH,wBAAsB,uBAAuB,CAAC,GAAG,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,oBAAoB,CAAC,CAM3G"}

package/dist/agent/spend/subagent-runs.js

@@ -0,0 +1,124 @@
+// DELEGATED-RUN EVIDENCE (OPE-263) — the spend ledger as the host's ONE witness that a subagent
+// actually ran.
+//
+// ⭐⭐ WHY THE LEDGER IS THE WITNESS. eve lowers a declared subagent into a MODEL-VISIBLE TOOL named
+// after its directory (subagents/declared.ts): there is no host-side seam that invokes one, and none
+// that observes one being invoked. So a tool handed "the subagent's verdict" is handed a
+// model-authored object, and no amount of inspecting that object distinguishes a relayed verdict from
+// an invented one. A tool description saying "do not write your own" is an instruction to exactly the
+// thing it is trying to constrain.
+//
+// What the host DOES see is SPEND. Every declared subagent must author `hooks/spend.ts`
+// (checkDeclaredSubagents pins it, because hooks are not inherited across eve's isolation boundary),
+// so a delegated child's model calls are written to `usage_events` by OE's own hook, from eve's
+// `step.completed` stream, inside the child's own run. Nothing on any tool's input surface writes a
+// usage row and no model chooses a row's fields, so the rows are unforgeable from the model side.
+// hooks/spend.ts files a delegated row under its PARENT's session id and stamps
+// {@link SUBAGENT_RUN_DETAIL_KEY} with the child's own identity — which turns "did this conversation
+// delegate?" into the one indexed read a session can already make about itself (usageForSession).
+//
+// 🔴 WHAT A ROW ATTESTS, EXACTLY. This list is the point of the module: every consumer must quote it
+// rather than round it up.
+//   ✅ A delegated CHILD SESSION ran under this conversation, and made N model calls, at times the
+//      host recorded. That is host-observed and not model-passable.
+//   ❌ WHICH subagent it was. eve's parent linkage carries a call id, never a name — a declared
+//      subagent (`fresh_eyes_review`) and eve's built-in `agent` delegation mint the same shape.
+//      What IS true of any of them: `scripts/subagents-lint.ts` holds every declared subagent to a
+//      full set of `disableTool()` sentinels, so whichever declared one ran held no tools.
+//   ❌ THAT THE WORDS ARE ITS WORDS. eve returns a subagent's output to the MODEL, not to the host.
+//      Narration is therefore always relayed by the session being reviewed, which could edit,
+//      truncate or replace it in transit.
+//   ❌ THAT THE RUN WAS FOR THIS REQUEST. Any delegation earlier in the same session counts too.
+//
+// PURE except for {@link readSubagentAttestation}, which is one indexed read and never throws — an
+// unreadable ledger is an ABSENCE of evidence, which is exactly what it reports.
+import { usageForSession } from "./usage-events.js";
+import { MAX_OBSERVABLE_DELEGATION_DEPTH } from "../operational/store.js";
+export { MAX_OBSERVABLE_DELEGATION_DEPTH };
+/** The `usage_events.detail` key under which hooks/spend.ts stamps a delegated child's identity.
+ *  ONE name, shared by the writer and every reader, so a rename cannot silently un-attest. */
+export const SUBAGENT_RUN_DETAIL_KEY = "subagentRun";
+/** Build the `detail` object for a delegated child's usage row. Optional lineage fields are
+ *  omitted rather than nulled, so a row written where eve gave us nothing extra is byte-identical
+ *  to a pre-OPE-369 one. */
+export function stampSubagentRun(run) {
+    return {
+        [SUBAGENT_RUN_DETAIL_KEY]: {
+            callId: run.callId,
+            sessionId: run.sessionId,
+            ...(run.rootSessionId !== undefined ? { rootSessionId: run.rootSessionId } : {}),
+            ...(run.depth !== undefined ? { depth: run.depth } : {}),
+        },
+    };
+}
+/** Read the stamp back off a row, or undefined when the row is not a delegated child's. Total —
+ *  a hand-written or legacy `detail` shape yields undefined rather than a partial stamp. The two
+ *  OPE-369 lineage fields are read PERMISSIVELY (absent or malformed ⇒ simply absent), so a row
+ *  written before they existed still attests everything it always did. */
+export function subagentRunOf(row) {
+    const raw = row.detail?.[SUBAGENT_RUN_DETAIL_KEY];
+    if (typeof raw !== "object" || raw === null)
+        return undefined;
+    const { callId, sessionId, rootSessionId, depth } = raw;
+    if (typeof callId !== "string" || typeof sessionId !== "string" || sessionId.length === 0)
+        return undefined;
+    return {
+        callId,
+        sessionId,
+        ...(typeof rootSessionId === "string" && rootSessionId.length > 0 ? { rootSessionId } : {}),
+        ...(typeof depth === "number" && Number.isInteger(depth) && depth > 0 ? { depth } : {}),
+    };
+}
+/**
+ * How deep a delegated run sits, from the ONLY lineage eve hands a hook: the immediate parent's
+ * session id and the denormalised root.
+ *
+ * `parentSessionId === rootSessionId` ⇒ this run's parent IS the root, so it is a DIRECT child
+ * (depth 1). Anything else is at least a grandchild, and the exact number of intervening hops is
+ * not observable — so it reports {@link MAX_OBSERVABLE_DELEGATION_DEPTH}, which is documented
+ * everywhere it surfaces as "two or more". An absent root (a legacy/foreign token-derived parent,
+ * where all we recovered was the parent id) degrades to 1: the parent is the deepest ancestor we
+ * can see, which is exactly what depth 1 asserts.
+ */
+export function delegationDepthOf(parentSessionId, rootSessionId) {
+    if (rootSessionId === undefined || rootSessionId === parentSessionId)
+        return 1;
+    return MAX_OBSERVABLE_DELEGATION_DEPTH;
+}
+/** PURE: read the evidence out of rows already scoped to one session (org + session id). */
+export function attestSubagentRuns(rows) {
+    const children = new Set();
+    let events = 0;
+    let firstTs;
+    let lastTs;
+    for (const row of rows) {
+        const stamp = subagentRunOf(row);
+        if (!stamp)
+            continue;
+        children.add(stamp.sessionId);
+        events++;
+        if (firstTs === undefined || row.ts < firstTs)
+            firstTs = row.ts;
+        if (lastTs === undefined || row.ts > lastTs)
+            lastTs = row.ts;
+    }
+    if (children.size === 0 || firstTs === undefined || lastTs === undefined) {
+        return { kind: "absent", reason: "the spend ledger holds no delegated-subagent usage row for this session" };
+    }
+    return { kind: "ledger", runs: children.size, events, firstTs, lastTs };
+}
+/**
+ * The evidence for one session, read from the operational store. NEVER THROWS: a store failure is
+ * reported as an absence with the failure as its reason, so a caller cannot accidentally convert
+ * "the database was down" into "an independent reviewer definitely ran" — nor into a hard error that
+ * would delete the rest of a governance document.
+ */
+export async function readSubagentAttestation(org, sessionId) {
+    try {
+        return attestSubagentRuns(await usageForSession(org, sessionId));
+    }
+    catch (err) {
+        return { kind: "absent", reason: `the spend ledger could not be read (${err instanceof Error ? err.message : String(err)})` };
+    }
+}
+//# sourceMappingURL=subagent-runs.js.map

package/dist/agent/spend/subagent-runs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"subagent-runs.js","sourceRoot":"","sources":["../../../agent/spend/subagent-runs.ts"],"names":[],"mappings":"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"}

package/dist/agent/spend/usage-events.d.ts

@@ -0,0 +1,79 @@
+import type { UsageEventEntry, UsageEventInput, UsageSummaryFilter, UsageSummaryRow } from "../operational/store.js";
+export type { UsageEventEntry, UsageEventInput, UsageSummaryFilter, UsageSummaryRow } from "../operational/store.js";
+/**
+ * The `usage_events.detail` key carrying the GATEWAY'S OWN TRACE ID for one model call (OPE-369)
+ * — eve extracts it from `providerMetadata.gateway.generationId` (extractStepProviderMetadata) and
+ * puts it on the `step.completed` event; hooks/spend.ts stamps it here.
+ *
+ * ⭐ WHAT IT BUYS. Every other field on a usage row is OE's OWN account of a call. This is the
+ * single value that JOINS that account to the gateway's: an unexplained cost spike, a suspected
+ * mis-attribution, a row whose measured and derived $ disagree — each becomes one lookup in the
+ * gateway's console against a specific generation, instead of an argument about which of our rows
+ * corresponds to which of their line items. It is a correlation id, not a secret and not evidence:
+ * it names a record we do not own and cannot verify from here.
+ *
+ * ONE name, shared by the writer and every reader, exactly like SUBAGENT_RUN_DETAIL_KEY.
+ */
+export declare const GENERATION_ID_DETAIL_KEY = "generationId";
+/** Read the gateway generation id back off a row, or undefined when it carries none (every
+ *  pre-OPE-369 row, every non-gateway deployment, every non-model row). Total. */
+export declare function generationIdOf(row: {
+    readonly detail?: Readonly<Record<string, unknown>>;
+}): string | undefined;
+/** The `spend.usageEventsTtlDays` setting (`spend.usageEventsTtlDays` overrides it) — the
+ *  opportunistic retention window, 90 days as shipped. */
+export declare function usageEventsTtlDays(): number;
+/**
+ * Did this call's source REPORT a cache split (OPE-1611)? Returns the `cacheTokensReported` half
+ * of a usage row, or `{}` when the question does not apply.
+ *
+ * THE RULE, in order:
+ *   1. an explicit `cacheTokensReported` on the input always wins — a writer that positively knows
+ *      the answer (a direct provider call reading the raw usage object) states it;
+ *   2. otherwise, only a row that NAMES A MODEL is asked at all. A model-less row is sandbox
+ *      RUNTIME billing (vercel-lifecycle.ts's OPE-266 writer) or another non-model source: it has
+ *      no prompt, so "did the prompt hit a cache" is not a question it can answer, and NULL —
+ *      the question was never asked — is the honest column;
+ *   3. for a model call, the answer is whether the source gave EITHER cache figure. eve's
+ *      `extractStepUsage` omits both keys entirely when the provider reported no
+ *      `inputTokenDetails`, so their presence is exactly "the provider published a figure", and
+ *      their absence is exactly "it did not".
+ *
+ * 🔴 WHAT THIS CANNOT ANSWER, and why no caller may read `true` as "the split is known": a
+ * PUBLISHED ZERO counts as published, because the rule is about the field, not its value. That is
+ * the honest reading of the input, and it is also why a zero must never be reported as "no
+ * caching" — see {@link import("../operational/store.js").UsageEventEntry.cacheTokensReported} and
+ * `spend/reporting.ts`'s `tokenAttributionNote`, which keys on the token COUNT for exactly this
+ * reason. A writer that positively knows better (a transport reading the raw provider result)
+ * overrides the inference through rule 1.
+ *
+ * Pure and total. Exported for the spend suite, which pins each arm.
+ */
+export declare function cacheReportedness(entry: {
+    readonly cacheTokensReported?: boolean;
+    readonly cacheReadTokens?: number;
+    readonly cacheWriteTokens?: number;
+    readonly model?: string;
+}): {
+    cacheTokensReported?: boolean;
+};
+/**
+ * Append one usage event. Best-effort: never throws — a failure is logged, not
+ * raised, so cost capture can never break the turn/hook/tool it's recording.
+ *
+ * Also rides an OPPORTUNISTIC prune (~1-in-20 writes), same idiom as event_dedupe's
+ * TTL prune — no scheduled job, the cost is amortized across normal writes. A prune
+ * failure never taints the append that already succeeded (own try/catch); on
+ * Postgres it's a documented no-op (see operational/postgres.ts).
+ */
+export declare function appendUsageEvent(entry: UsageEventInput): Promise<void>;
+/** Every usage event for one session (org-scoped), oldest-first — see the store's
+ *  doc comment for why this returns raw rows rather than a pre-summed total. */
+export declare function usageForSession(org: string, sessionId: string): Promise<UsageEventEntry[]>;
+/** Grouped rollup by (surfaceKey, principalId, kind, routineId, surfaceMode, model) within an org. */
+export declare function usageSummary(org: string, filter?: UsageSummaryFilter): Promise<UsageSummaryRow[]>;
+/** Manual/administrative prune (tests, ops scripts) — production relies on the
+ *  opportunistic path inside appendUsageEvent. Returns the count removed (0 on
+ *  Postgres, by design — see operational/postgres.ts). */
+export declare function pruneUsageEvents(org: string, olderThanTs: string): Promise<number>;
+//# sourceMappingURL=usage-events.d.ts.map