@open-everywhere/core 0.1.0

package/agent/hooks/spend.ts

@@ -0,0 +1,368 @@
+// The `step.completed` adapter onto recordModelCall, which writes both spend rows for every model call OE pays for - a turn step and the vision call alike - so a second model-call site cannot grow a second account of the same money.
+// It also subscribes `step.started`, for the one fact that event carries and `step.completed` does not: the model reference the host will run (OPE-1878, see that handler).
+// Best-effort: a dropped cost row must never break the turn.
+
+import { defineHook, type HookContext } from "eve/hooks";
+import { domainKeyOf, resolvePartition } from "../memory/partition.js";
+import { recordSpend } from "../spend/store.js";
+import { appendUsageEvent, GENERATION_ID_DETAIL_KEY } from "../spend/usage-events.js";
+import { noteCompletedModelStep } from "../model/call-capture.js";
+import { periodOf, UNKNOWN_MODEL, type Usage } from "../spend/spend.js";
+import { bindFrom, type BindableContext } from "../identity/binding.js";
+import { routineMarker } from "../routines/routine.js";
+import { noteHostStepModel, readHostStepModel, readModelStamp } from "../model/model-stamp.js";
+import { readModelArm, MODEL_ARM_DETAIL_KEY, MODEL_AB_BUCKET_DETAIL_KEY, type ModelArmStamp } from "../model/ab-test.js";
+import { getOperationalStore } from "../operational/provider.js";
+import type { SurfaceMode } from "../operational/store.js";
+import { isSupervisorToken, standingSeatRegistryKey, unifiedWindowFromToken } from "../channels/unified-supervisor.js";
+import { parseDmSeatToken, dmSeatRegistryKey, bareTokenFromEveContext, parseSubagentToken } from "../channels/window-key.js";
+import { delegationDepthOf, stampSubagentRun } from "../spend/subagent-runs.js";
+import { isRunFireSeatWindowId } from "../routines/fire-window.js";
+
+/**
+ * The routine this turn belongs to, or undefined for an ordinary turn. Reads the SAME dispatcher-stamped marker turnKind classifies "routine" from, so the two can never disagree, and never throws - an unusual ctx degrades to an unattributed row.
+ * A delegated child inherits the parent's auth, so its rows attribute to the routine too: a routine's cost includes the work it delegated.
+ */
+export function routineIdOf(ctx: BindableContext): string | undefined {
+  try {
+    const auth = ctx.session?.auth;
+    return routineMarker(auth?.current?.attributes ?? auth?.initiator?.attributes)?.id;
+  } catch {
+    return undefined;
+  }
+}
+
+export type DelegatableContext = BindableContext;
+
+/**
+ * The PARENT this turn was delegated from, or undefined for a root turn: eve's typed `session.parent` first, then the minted `subagent:<parentSessionId>:<callId>` continuation token.
+ * Neither source is reachable from a tool input, so neither can be supplied by a model. Never throws, and `rootSessionId` is available only from the typed source.
+ */
+export function subagentParentOf(
+  ctx: DelegatableContext,
+  continuationToken?: unknown,
+): { parentSessionId: string; callId: string; rootSessionId?: string } | undefined {
+  try {
+    const p = ctx.session?.parent;
+    if (typeof p?.sessionId === "string" && p.sessionId.length > 0 && typeof p.callId === "string" && p.callId.length > 0) {
+      return {
+        parentSessionId: p.sessionId,
+        callId: p.callId,
+        ...(typeof p.rootSessionId === "string" && p.rootSessionId.length > 0 ? { rootSessionId: p.rootSessionId } : {}),
+      };
+    }
+    const parsed = parseSubagentToken(continuationToken);
+    return parsed ? { parentSessionId: parsed.parentSessionId, callId: parsed.callId } : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * WHICH KIND OF CONVERSATION this turn is in — the binding's own answer, and the ONE fact the
+ * anti-doxxing report mask reads (OPE-1862).
+ *
+ * 🔴 IT IS DELIBERATELY NOT {@link turnKind}, AND THE TWO MAY NOT BE MERGED. `turnKind` returns
+ * "routine", "supervisor" or "subagent" BEFORE it ever tests the mode, so a routine fired inside a
+ * DM is tagged "routine" and that tag can never answer "was this a DM". Before this function, the
+ * readers fell back to a SLACK id-shape test for such rows, which masked Slack DMs and published
+ * Discord and Teams ones. Each platform's own identity layer resolves the mode (`im`/`personal` →
+ * "dm"), so reading it here is how the mask stops caring what a surface id looks like.
+ *
+ * 🔴 IT REPORTS A RESOLVED MODE AND NOTHING ELSE (OPE-1867). Two ways to reach `undefined`, and
+ * both mean the same thing to a reader — this row cannot be classified, so mask it:
+ *   - the binding THROWS on an unusual ctx;
+ *   - the binding's mode is a GAP-FILL. `bindFrom` always returns a usable `mode`, defaulting to
+ *     "channel" when nothing classified the conversation, and a mapper that cannot read a scope
+ *     contributes none (teams-identity.ts `teamsResolvedMode`). Stamping that default published a
+ *     surface the platform never called a room — on Teams, an individual's personal chat whose
+ *     activity carried no `conversationType`. `binding.modeResolved` is what tells the two apart,
+ *     and this is the reader it exists for: the value is written to a row that a report posted in
+ *     a channel may name, so a default is not good enough here even though it is everywhere else.
+ *
+ * 🔴 AND IT IS ONLY AS GOOD AS THE MAPPER STILL. `modeResolved` says a mapper RETURNED a mode, not
+ * that it was sure of one, and today only Teams reports its own ignorance — `slackMode` still ends
+ * `return "channel"`. See the field's own doc on `SurfaceBinding` for what that does and does not
+ * cover; this reader cannot see past what the mapper told the binding.
+ */
+export function turnSurfaceMode(ctx: BindableContext): SurfaceMode | undefined {
+  try {
+    const binding = bindFrom(ctx);
+    if (!binding.modeResolved) return undefined;
+    const mode = binding.mode;
+    return mode === "dm" || mode === "mpim" || mode === "channel" ? mode : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * The turn's ORIGIN tag — `dm` | `channel` | `routine` | `supervisor` | `subagent` | `unclassified`.
+ *
+ * 🔴 `channel` IS A CLASSIFICATION HERE, NOT A DEFAULT (OPE-1867), because `spend/dm-mask.ts` reads
+ * this tag as its legacy fallback for rows written before `surface_mode` existed — and that arm
+ * PUBLISHES a surface on `kind === "channel"`. This function used to end
+ * `bindFrom(ctx).mode === "dm" ? "dm" : "channel"`, and `mode` gap-fills `channel` when nothing
+ * classified the conversation, so an unclassifiable turn was tagged as a room and its surface was
+ * named in reports — through this fallback, even after `turnSurfaceMode` correctly refused to stamp
+ * it. The mask's own doc already claimed `channel` here meant "the binding resolved something other
+ * than a DM"; now the code says so too.
+ *
+ * `unclassified` is what a turn gets when nothing could say what conversation it is — including the
+ * degraded arm below, where the binding threw. Both mask, which is the direction an origin tag may
+ * be wrong in.
+ */
+export function turnKind(ctx: DelegatableContext, continuationToken?: unknown): string {
+  try {
+    const auth = ctx.session?.auth;
+    const attrs = auth?.current?.attributes ?? auth?.initiator?.attributes;
+    if (routineMarker(attrs)) return "routine";
+    if (isSupervisorToken(continuationToken)) return "supervisor";
+    // A routine's delegated child tags "routine", not "subagent" - a routine's cost includes what it delegated - so a reader after delegation EVIDENCE must key on the row's stamp, never on this tag.
+    if (subagentParentOf(ctx, continuationToken)) return "subagent";
+    const binding = bindFrom(ctx);
+    if (!binding.modeResolved) return "unclassified";
+    return binding.mode === "dm" ? "dm" : "channel";
+  } catch {
+    return "unclassified";
+  }
+}
+
+/**
+ * This turn's continuation token, de-namespaced. eve reports it namespaced with the channel-definition name (`slack:D...:oe-dm:g2`) while registry rows store the BARE token OE minted, so every exact-match path misses every row without this.
+ * One helper for both call sites, because two spellings of this rule is how the defect comes back; the raw value is the fallback for a native or foreign token.
+ */
+function turnWindowToken(ctx: BindableContext): string | undefined {
+  return bareTokenFromEveContext(ctx.channel?.continuationToken) ?? ctx.channel?.continuationToken;
+}
+
+/** A context recordModelCall can attribute from - satisfied by eve's HookContext and by a tool's ToolContext alike, since both reach the spend plane's writer. */
+export type SpendAttributionContext = DelegatableContext & { readonly session?: { readonly id?: string } };
+
+export interface AttributedModelCall {
+  readonly usage: Usage;
+  /** The model that ran it. Omitted ⇒ recorded under {@link UNKNOWN_MODEL} with a warning — see
+   *  {@link recordModelCall}'s doc for why that is never silently absorbed. */
+  readonly model?: string;
+  readonly generationId?: string;
+  /** What produced the call, named in the stampless warning only ("a turn step", "describe_image"). */
+  readonly what?: string;
+  /**
+   * The model A/B arm this call ran on, when this session's routing stamped one. Absent on every deployment that has not armed the experiment, so its rows are byte-identical to before the experiment existed.
+   * PASSED IN, NOT READ HERE, for the same reason the model is: the per-session stamp is only readable inside the eve session context, so a writer that reached for it itself would record nothing from any other call site.
+   */
+  readonly arm?: ModelArmStamp;
+}
+
+/**
+ * The spend plane's ONE attributed model-call writer: every model call lands its cap row (spend_ledger, the only store a cap denomination reads) and its forensic row (usage_events) here, so a second call site cannot grow a second account of the same money.
+ * Best-effort and total - it never throws to its caller - and a call with no tokens AND no measured cost records nothing. It does not override `kind`: a vision call carries its turn's origin tag and is separated by the model column instead.
+ */
+export async function recordModelCall(ctx: SpendAttributionContext, call: AttributedModelCall): Promise<void> {
+  try {
+    const usage = call.usage;
+    // Nothing token-bearing and nothing the gateway billed ⇒ no model spend to record. (A measured
+    // cost with no token block is POSITIVE evidence of spend — OPE-369 — so it is admitted.)
+    if (!usage || (usage.inputTokens == null && usage.outputTokens == null && usage.costUsd == null)) return;
+    const p = resolvePartition(ctx);
+    const token = turnWindowToken(ctx);
+    const routineId = routineIdOf(ctx);
+    const delegatedFrom = subagentParentOf(ctx, token);
+    const sessionId = ctx.session?.id ?? "";
+
+    // A missed model id is recorded as UNKNOWN_MODEL, never absorbed into an absent one: an empty model id is the bucket sandbox-runtime rows use, and the stampless pricing arm would then price the call at the deployment's sole priced model. No rate table names UNKNOWN_MODEL, so rate-derived pricing skips itself.
+    // The row is ALWAYS written, because refusing it would make an unattributable call free and invisible to every cap - fail-open for the money gate - so the loud half is the warning below.
+    const model = call.model ?? UNKNOWN_MODEL;
+    if (call.model === undefined) {
+      console.warn(
+        `[open-everywhere:spend] a billable model call (${call.what ?? "unknown source"}) carried NO model id — recording as model="${UNKNOWN_MODEL}" and SKIPPING rate-derived pricing ` +
+          `(session=${sessionId || "?"} surface=${p.key} in=${usage.inputTokens ?? 0} out=${usage.outputTokens ?? 0}). ` +
+          `Tokens and (where the gateway measured it) exact $ are still recorded; only the rate-derived $ is withheld, because nothing observed which model ran.`,
+      );
+    }
+
+    // The gateway's own measured cost for this call. Absent on every direct-provider deployment, so everything downstream treats it as a bonus, never a dependency.
+    // Guarded on finiteness here rather than trusting the extractor, because this number reaches a money column.
+    const measuredUsd = typeof usage.costUsd === "number" && Number.isFinite(usage.costUsd) && usage.costUsd >= 0 ? usage.costUsd : undefined;
+
+    const delegationDepth = delegatedFrom ? delegationDepthOf(delegatedFrom.parentSessionId, delegatedFrom.rootSessionId) : 0;
+    const rootSessionId = delegatedFrom?.rootSessionId ?? delegatedFrom?.parentSessionId ?? sessionId;
+
+    try {
+      // THE CAP WRITE: one attributed, write-time-priced increment to the spend ledger - the only store any cap denomination reads.
+      // The principal is the ATTRIBUTED one, never the acting one: a routine fire binds as its attested creator and a per-user cap reads the same dimension, so charging this id while gating on `actingPrincipalId` would measure one person and bill another.
+      await recordSpend(p, {
+        period: periodOf(new Date().toISOString()),
+        usage,
+        principalId: bindFrom(ctx).principalId,
+        routineId,
+        model,
+        // OPE-1862: the conversation's own mode, so a report can mask this row's surface on EVERY
+        // platform. Absent on a ctx with no resolvable binding, which the readers mask.
+        ...((): { surfaceMode?: SurfaceMode } => {
+          const mode = turnSurfaceMode(ctx);
+          return mode ? { surfaceMode: mode } : {};
+        })(),
+        ...(measuredUsd !== undefined ? { measuredUsd } : {}),
+      });
+    } catch (err) {
+      console.log(`[open-everywhere:spend] record skipped: ${String(err)}`);
+    }
+
+    try {
+      await appendUsageEvent({
+        org: p.org,
+        // SPEND grain (domainKeyOf): a Discord thread's rows are stamped with the PARENT channel's surface key, which is the grain recordSpend buckets the cap ledger under and the exact key scopeUsdSpend matches when the gate checks.
+        // The domain key IS the surfaceKey everywhere else.
+        surfaceKey: domainKeyOf(p),
+        // WHICH SESSION THIS COSTS: a root turn files under itself, and a DELEGATED CHILD files under its PARENT while carrying its own identity in the row's subagentRun stamp, so a parent's cost stops under-reporting the work it delegated.
+        // A GRANDCHILD still files under its immediate parent - `rootSessionId` below is what makes the whole tree one grouped read, deliberately without changing what a row asserts.
+        sessionId: delegatedFrom?.parentSessionId ?? sessionId,
+        principalId: bindFrom(ctx).principalId,
+        kind: turnKind(ctx, token),
+        // OPE-1862: `kind` above is the turn's ORIGIN tag and a routine/supervisor/subagent turn
+        // wins it before the DM test runs, so the mask reads this instead.
+        ...((): { surfaceMode?: SurfaceMode } => {
+          const mode = turnSurfaceMode(ctx);
+          return mode ? { surfaceMode: mode } : {};
+        })(),
+        ...((): { detail?: Readonly<Record<string, unknown>> } => {
+          const arm = call.arm;
+          const detail = {
+            ...(delegatedFrom
+              ? stampSubagentRun({
+                  callId: delegatedFrom.callId,
+                  sessionId,
+                  ...(delegatedFrom.rootSessionId !== undefined ? { rootSessionId: delegatedFrom.rootSessionId } : {}),
+                  depth: delegationDepth,
+                })
+              : {}),
+            ...(call.generationId !== undefined ? { [GENERATION_ID_DETAIL_KEY]: call.generationId } : {}),
+            ...(arm ? { [MODEL_ARM_DETAIL_KEY]: arm.arm, [MODEL_AB_BUCKET_DETAIL_KEY]: arm.bucketKey } : {}),
+          };
+          return Object.keys(detail).length > 0 ? { detail } : {};
+        })(),
+        // No derived twin here: this table's derived cost is priced at READ time from model plus tokens, which is what lets a rate-table fix correct its history.
+        ...(measuredUsd !== undefined ? { usdMicrosMeasured: Math.round(measuredUsd * 1_000_000), costSource: "measured" as const } : { costSource: "derived" as const }),
+        // Delegation lineage as COLUMNS, so a query can group by them without reaching into `detail` JSON. `delegationDepth` is 0 on a root turn, and `rootSessionId` is total - its own session id at the root.
+        delegationDepth,
+        rootSessionId,
+        ...(routineId !== undefined ? { routineId } : {}),
+        model,
+        inputTokens: usage.inputTokens,
+        outputTokens: usage.outputTokens,
+        // PASSED THROUGH UNDEFINED-PRESERVING, NEVER `?? 0`. appendUsageEvent turns the presence of these two into the row's `cacheTokensReported` flag, so a `?? 0` here would assert that the source answered on every provider that simply omits the split.
+        // A published ZERO is not evidence of no caching either - see UsageEventEntry.cacheTokensReported for that limit.
+        cacheReadTokens: usage.cacheReadTokens,
+        cacheWriteTokens: usage.cacheWriteTokens,
+        // The third dimension, same discipline: absent on every step-driven row until eve's extractStepUsage carries `outputTokenDetails.reasoningTokens`, so those rows record "unreported" instead of a zero.
+        reasoningTokens: usage.reasoningTokens,
+      });
+    } catch (err) {
+      console.warn(`[open-everywhere:usage] event append skipped: ${String(err)}`);
+    }
+  } catch (err) {
+    console.warn(`[open-everywhere:spend] model-call record skipped: ${String(err)}`);
+  }
+}
+
+export default defineHook({
+  events: {
+    // THE MODEL A DELEGATED CALL RAN, RECORDED WHERE EVERY SESSION PASSES (OPE-1878). eve emits this
+    // event before every TURN STEP of every session and carries the session's own model reference
+    // on it, so one handler here names the model for the root agent, for a declared subagent, and
+    // for a delegated child at any depth, on every surface. `step.completed` below reads it back
+    // ONLY when this session stamped nothing of its own — see model/model-stamp.ts for the
+    // precedence and for the reporting gap this closes.
+    //
+    // 🔴 A TURN STEP, NOT EVERY MODEL CALL — and a non-step call must never be costed off this slot.
+    // eve's compaction calls `generateText` directly and emits no step event; OE's own non-step
+    // calls (the vision call, the judges) emit none either. Each already passes its OWN model to
+    // `recordModelCall`, which is what keeps them right. A future call site that instead leaned on
+    // this slot would attribute itself to the LAST TURN STEP's model, at that model's rate.
+    //
+    // 🔴 THIS HANDLER MUST NEVER THROW. eve wraps a throw from a `step.started` hook in a
+    // `BoundaryHookError` (node_modules/eve/dist/src/context/hook-lifecycle.js), which fails the
+    // step — so a bookkeeping detail would kill the turn. `noteHostStepModel` swallows its own
+    // failures; this catch covers the read of the event itself.
+    "step.started": (event) => {
+      try {
+        noteHostStepModel(event.data.modelId);
+      } catch (err) {
+        console.warn(`[open-everywhere:spend] host model reference not recorded: ${String(err)}`);
+      }
+    },
+    "step.completed": async (event, ctx: HookContext) => {
+      // THE CAPTURE CROSS-CHECK MUST RUN BEFORE EVERY EARLY RETURN BELOW. This is the deployment's one universal `step.completed` witness, counting a model step independently of which model instance served it, which is what makes a call that bypassed the capture wrapper visible.
+      // A zero-token step still completed, so counting it after the usage guard would under-count the witness and hide the gap. It no-ops entirely when capture is disarmed.
+      noteCompletedModelStep(ctx.session?.id, (event.data as { turnId?: string } | undefined)?.turnId, ctx);
+      const usage = event.data?.usage as Usage | undefined;
+      // A zero-token step is not model spend, and sandbox RUNTIME spend reaches the ledger through its own writer instead - but a step the gateway BILLED is admitted: eve emits `{ costUsd }` with no token fields when the provider returned a cost and no usage block.
+      // Nothing token-less and cost-less gets through.
+      if (!usage || (usage.inputTokens == null && usage.outputTokens == null && usage.costUsd == null)) return;
+      const token = turnWindowToken(ctx);
+
+      // The gateway's per-call trace id - the one value that JOINS an OE usage row to the gateway's own billing record. Read defensively: it is optional in eve's own event type.
+      const generationId = ((): string | undefined => {
+        const raw = (event.data as { providerMetadata?: { gateway?: { generationId?: unknown } } } | undefined)?.providerMetadata?.gateway?.generationId;
+        return typeof raw === "string" && raw.length > 0 ? raw : undefined;
+      })();
+
+      // `step.completed` carries no model field in this eve version, so the model comes from the per-session stamp model/routing.ts writes immediately before the call; steps within a session run sequentially, so the last stamp is the step now being costed. The A/B arm comes off its own slot for the same reason.
+      // A NON-TURN model call must NOT touch the stamp: the vision call runs BETWEEN two steps of this session, so stamping it would make the next step attribute the turn's tokens to the vision model.
+      // THE HOST REFERENCE IS THE FALLBACK, NEVER THE PREFERENCE (OPE-1878). OE's own stamp is the id the ROUTE resolved, in the registry's own spelling, and a routed session stamps on every path of model/routing.ts — so this second read answers only for a session that reaches no resolver at all, which is every DECLARED SUBAGENT (its agent declares a static model id). A session neither source can name still lands on UNKNOWN_MODEL below.
+      const stampedModel = readModelStamp() ?? readHostStepModel() ?? undefined;
+      const stampedArm = readModelArm() ?? undefined;
+      await recordModelCall(ctx, {
+        usage,
+        ...(stampedModel !== undefined ? { model: stampedModel } : {}),
+        ...(generationId !== undefined ? { generationId } : {}),
+        ...(stampedArm !== undefined ? { arm: stampedArm } : {}),
+        what: "a turn step",
+      });
+
+      // Re-derived rather than threaded out of recordModelCall: resolvePartition is a pure, fail-soft read of this same ctx, so a second call cannot disagree with the writer's.
+      const p = resolvePartition(ctx);
+
+      // For a SUPERVISOR step only, bump the live generation's registry row by measured `inputTokens + cacheReadTokens`. Token-guarded in the store, so a straggler step from a retired generation is a no-op.
+      // Its own best-effort try/catch: a counter-bump failure must never break the hook or the writes above, and the 150-turn backstop still binds if this under-counts.
+      if (isSupervisorToken(token)) {
+        try {
+          const delta = (usage.inputTokens ?? 0) + (usage.cacheReadTokens ?? 0);
+          // The bump targets the SYNTHETIC window row for a cross-surface supervisor, whose registry row is keyed by org and windowId rather than the woken message's per-container surfaceKey; standingSeatRegistryKey is the ONE shared derivation, because channels/session-park.ts must retire the same row.
+          // It is total over the token space, so the domainKeyOf fallback is unreachable inside isSupervisorToken and exists only to keep the type non-optional.
+          const registryKey = standingSeatRegistryKey(token, domainKeyOf(p)) ?? domainKeyOf(p);
+          if (delta > 0) {
+            const matched = await getOperationalStore().bumpChannelSessionUsage(p.org, registryKey, token, delta);
+            // A miss is EXPECTED for a PER-RUN fire seat, which is unique per fire and never gets a registry row, so warning on it would be noise on every run-seat turn forever.
+            // A rotation-boundary straggler and a JOB seat's miss stay real warnings: once adopted, a job seat's row token should always match, so a miss there means a starved counter.
+            const windowId = unifiedWindowFromToken(token);
+            if (matched === 0 && !(windowId !== undefined && isRunFireSeatWindowId(windowId))) {
+              console.warn(`[open-everywhere:spend] supervisor counter bump matched no row (org=${p.org} key=${registryKey} token=${token})`);
+            }
+          }
+        } catch (err) {
+          console.warn(`[open-everywhere:spend] supervisor token counter bump skipped: ${String(err)}`);
+        }
+      }
+
+      // LEGACY DM-SEAT counter. A first-classed DM seat's token is a degenerate WINDOW token, so the supervisor block above already bumps it at the same row; this block survives only for legacy tokens in flight and for seats not yet migrated.
+      // The explicit window-token exclusion in the diagnostic below is DELIBERATELY redundant: without it the silence would depend on the ordering inside turnKind, and a reordering there would warn on every DM turn forever.
+      const dmSeat = parseDmSeatToken(token);
+      if (!dmSeat && !isSupervisorToken(token) && turnKind(ctx, token) === "dm") {
+        console.warn(`[open-everywhere:spend] dm turn carried a token with no rotation lever (token=${JSON.stringify(token)}) — no seat counter bumped`);
+      }
+      if (dmSeat) {
+        try {
+          const delta = (usage.inputTokens ?? 0) + (usage.cacheReadTokens ?? 0);
+          if (delta > 0) {
+            const matched = await getOperationalStore().bumpChannelSessionUsage(p.org, dmSeatRegistryKey(dmSeat.channelId), token as string, delta);
+            if (matched === 0) console.warn(`[open-everywhere:spend] dm-seat counter bump matched no row (org=${p.org} key=${dmSeatRegistryKey(dmSeat.channelId)} token=${token})`);
+          }
+        } catch (err) {
+          console.warn(`[open-everywhere:spend] dm-seat token counter bump skipped: ${String(err)}`);
+        }
+      }
+    },
+  },
+});

package/agent/hooks/stall-guard.ts

@@ -0,0 +1,22 @@
+// Two subscriptions because `action.result` carries the output and tool name but not the call's input: `actions.requested` stashes each input by callId before the call runs.
+// A `rejected` result (an approval denial) is not a spin and is skipped; `completed` and `failed` both count. Subagent hooks do not fire here, so fan-out is excluded.
+
+import { defineHook } from "eve/hooks";
+import { recordActionRequest, recordActionResult } from "../stall/guard.js";
+
+export default defineHook({
+  events: {
+    "actions.requested": async (event) => {
+      const turnId = event.data.turnId;
+      for (const action of event.data.actions) {
+        if (action.kind === "tool-call") recordActionRequest(turnId, action.callId, action.toolName, action.input);
+      }
+    },
+    "action.result": async (event) => {
+      const result = event.data.result;
+      if (result.kind === "tool-result" && event.data.status !== "rejected") {
+        recordActionResult(event.data.turnId, result.callId, result.toolName, result.output);
+      }
+    },
+  },
+});

package/agent/hooks/telemetry.ts

@@ -0,0 +1,90 @@
+// Turn-level telemetry — emits the oe.turn.* events over a closed vocabulary: a surface TYPE and coarse buckets, never a surfaceKey, session or principal id.
+// The accumulator is observability/turn-clock.ts, a leaf, so a reader low in the import graph (the routine permission card's timed wait) can still read the turn's elapsed time.
+
+import { defineHook, type HookContext } from "eve/hooks";
+import { bindFrom, type BindableContext } from "../identity/binding.js";
+import { routineMarker } from "../routines/routine.js";
+import { readModelStamp } from "../model/model-stamp.js";
+import { emitTelemetry, flushTelemetry, maybeHeartbeat, tokensBucket, stepsBucket, latencyBucket } from "../observability/telemetry.js";
+import { bumpTurnClock, readTurnClock, resetTurnClock } from "../observability/turn-clock.js";
+
+function bumpTurn(usage: { inputTokens?: number; outputTokens?: number; cacheReadTokens?: number; cacheWriteTokens?: number } | undefined): void {
+  bumpTurnClock((usage?.inputTokens ?? 0) + (usage?.outputTokens ?? 0) + (usage?.cacheReadTokens ?? 0) + (usage?.cacheWriteTokens ?? 0));
+}
+
+/** The webhook-fire marker is stamped by webhooks/dispatch.ts's fireWebhook. */
+function isWebhookFire(ctx: BindableContext): boolean {
+  const attrs = ctx.session?.auth?.current?.attributes ?? ctx.session?.auth?.initiator?.attributes;
+  const v = attrs?.["open_everywhere_webhook_id"];
+  return typeof v === "string" ? v.length > 0 : Array.isArray(v) && v.length > 0;
+}
+
+function surfaceType(ctx: BindableContext): string {
+  if (isWebhookFire(ctx)) return "webhook";
+  try {
+    return bindFrom(ctx).platform;
+  } catch {
+    return "local";
+  }
+}
+
+/** Routine and webhook fires are checked FIRST: a fired session's surface mode is still "channel" or "dm" and would otherwise misclassify. */
+function turnKindForTelemetry(ctx: BindableContext): string {
+  try {
+    const auth = ctx.session?.auth;
+    const attrs = auth?.current?.attributes ?? auth?.initiator?.attributes;
+    if (routineMarker(attrs)) return "routine";
+    if (isWebhookFire(ctx)) return "webhook";
+    const mode = bindFrom(ctx).mode;
+    if (mode === "dm") return "dm";
+    if (mode === "mpim") return "mpim";
+    return "channel";
+  } catch {
+    return "channel";
+  }
+}
+
+export default defineHook({
+  events: {
+    "turn.started": async (event, ctx: HookContext) => {
+      // The SESSION id rides along because eve's turn id is session-local (`turn_${sequence}`,
+      // restarting at 0 per session), so it is not an identity on its own — see TurnClock's doc.
+      // Read defensively: a test double, or a future ctx shape, must not throw out of a hook.
+      resetTurnClock(event.data.turnId, Date.now(), (ctx as HookContext | undefined)?.session?.id ?? "");
+      maybeHeartbeat(); // turn-activity trigger (cheap: in-memory throttle only)
+    },
+    "step.completed": async (event, ctx: HookContext) => {
+      bumpTurn(event.data?.usage);
+      // TIME TO FIRST OUTPUT is an UPPER BOUND, never a floor: eve raises step.completed after the step's tool calls have run, so a first step that runs a three-minute command reports three minutes.
+      // It is a separate event rather than an attribute on oe.turn.completed, so a turn that hangs and never completes still leaves its first-output reading behind.
+      const turn = readTurnClock();
+      if (turn?.steps !== 1) return;
+      emitTelemetry("oe.turn.first_output", {
+        "oe.surface": surfaceType(ctx),
+        "oe.kind": turnKindForTelemetry(ctx),
+        "oe.latency.bucket": latencyBucket(Date.now() - turn.startedAt),
+      });
+    },
+    "turn.completed": async (_event, ctx: HookContext) => {
+      const turn = readTurnClock();
+      const now = Date.now();
+      const startedAt = turn?.startedAt ?? now;
+      emitTelemetry("oe.turn.completed", {
+        "oe.surface": surfaceType(ctx),
+        "oe.kind": turnKindForTelemetry(ctx),
+        "gen_ai.request.model": readModelStamp() ?? "unknown",
+        "oe.tokens.bucket": tokensBucket(turn?.tokens ?? 0),
+        "oe.steps.bucket": stepsBucket(turn?.steps ?? 0),
+        "oe.latency.bucket": latencyBucket(now - startedAt),
+      });
+      await flushTelemetry();
+    },
+    "turn.failed": async (event, ctx: HookContext) => {
+      emitTelemetry("oe.turn.failed", {
+        "oe.surface": surfaceType(ctx),
+        "oe.error.code": event.data?.code ?? "unknown",
+      });
+      await flushTelemetry();
+    },
+  },
+});