Merge main: wave-4 backend (activity abort endpoint, lastStep capture)

src/core/contracts/chat.ts

@@ -9,6 +9,7 @@
 import type { UIMessage } from "ai";
 import type { Phase3 } from "../phases.ts";
 import type { PlanNodeStatus, PlanTree } from "./plan.ts";
+import type { EmissionStats } from "./graph.ts";
 
 // ─── Chat records (the session store's on-disk format) ───────────────────────
 
@@ -32,6 +33,41 @@ export interface ChatRecord {
 	 * each entry onto its message; aggregates are folds over this log
 	 * (core/prices.ts). */
 	turns?: TurnUsage[];
+	/** Append-only background-extraction usage log (2026-09 observability):
+	 *  one entry per finished pipeline run on THIS chat — extraction is real
+	 *  spend too. Same parallel-log discipline as `turns` (nothing rides
+	 *  inside messages). Keyed by startedAt; idempotent appends. */
+	extractions?: ExtractionRunUsage[];
+}
+
+// ─── Background-extraction usage (the money channel, extraction side) ────────
+
+/** One pipeline stage's model usage — the stage's model + every step it
+ *  billed (CallUsage per agent step). Steps, not a sum: cost and context
+ *  folds happen at read time (core/prices.ts). */
+export interface ExtractionStageUsage {
+	/** The OpenRouter model id that ran this stage. */
+	model: string;
+	steps: CallUsage[];
+}
+
+/** One finished (or failed mid-flight) extraction run's usage record.
+ *  Appended to the chat's `extractions` log when the run ends — success or
+ *  failure, because money was spent either way; `stats` is present only
+ *  when the merger actually ran. */
+export interface ExtractionRunUsage {
+	/** The run's registry startedAt (ms) — the idempotency key. */
+	startedAt: number;
+	at: string;
+	durationMs: number;
+	/** What the run merged into the graph; absent when it failed first. */
+	stats?: EmissionStats;
+	/** Model usage per stage, in pipeline order (merger is deterministic —
+	 *  no model call, no entry). */
+	stages: {
+		extractor: ExtractionStageUsage;
+		auditor: ExtractionStageUsage;
+	};
 }
 
 // ─── Usage accounting (the money channel) ─────────────────────────────────────

src/core/contracts/graph.ts

@@ -22,6 +22,17 @@
  *  strength — strength is derived at read time from topology. */
 export type EdgeType = "follows" | "supports";
 
+/** What one extraction run merged into the graph ledgers — the merger's
+ *  output, also persisted in extraction-run usage records (contracts/chat). */
+export interface EmissionStats {
+	/** New graph nodes appended. */
+	nodes: number;
+	/** New edge assertions appended. */
+	edges: number;
+	/** Ledger events rebuilt (quiz outcomes + observations). */
+	events: number;
+}
+
 /** One provenance point — message-granular (DECIDED 2026-09-02): nodes and
  *  edges record every (chat, message) where they came up, deep-linkable to
  *  the exact transcript point. */

src/core/contracts/jobs.ts

@@ -7,6 +7,7 @@
  * of "ai" (safe everywhere: server, client, tests). See docs/vision.md.
  */
 import type { UIMessage } from "ai";
+import type { CallUsage } from "./chat.ts";
 
 // ─── Async sub-agent jobs (vision §2.5; plan.md Wave 0 protocol) ────────────
 
@@ -36,18 +37,64 @@ export interface JobRecord {
 
 /** A sub-agent run's accumulated usage — the same accounting shape as a
  * chat turn (contracts/chat.ts CallUsage), flattened to one running total
- * plus a step count. */
+ * plus a step count. Token fields are optional exactly like CallUsage: a
+ * field NO model call reported stays undefined — absent is not zero (the
+ * money-channel doctrine; cost renders "—", never $0). */
 export interface JobUsage {
 	/** The OpenRouter model id that ran the sub-agent. */
 	model: string;
 	/** Running totals summed over the run's model calls so far. */
-	inputTokens: number;
-	outputTokens: number;
-	cacheReadTokens: number;
-	cacheWriteTokens: number;
-	reasoningTokens: number;
+	inputTokens: number | undefined;
+	outputTokens: number | undefined;
+	cacheReadTokens: number | undefined;
+	cacheWriteTokens: number | undefined;
+	reasoningTokens: number | undefined;
 	/** How many model calls the run has made (each bills separately). */
 	steps: number;
+	/** The MOST RECENT model call's accounting (2026-09 dock contract): the
+	 * per-blob context line reads last-step input+output against the model's
+	 * CONTEXT_LIMITS — never the cumulative totals. Absent until the first
+	 * call completes; absent provider fields stay absent (never zero). */
+	lastStep?: CallUsage;
+}
+
+/** The per-model-call usage shape we fold into JobUsage — the SDK's
+ * LanguageModelUsage narrowed structurally (no runtime "ai" import: any
+ * object with these fields folds, including the real thing and test fakes). */
+export interface UsageStepLike {
+	inputTokens?: number | undefined;
+	inputTokenDetails?: { cacheReadTokens?: number; cacheWriteTokens?: number } | undefined;
+	outputTokens?: number | undefined;
+	outputTokenDetails?: { reasoningTokens?: number } | undefined;
+}
+
+/** Fold one model call's usage into the run's running total (pure). A
+ * field neither the total nor the step reported stays undefined; once
+ * reported, later unreported calls contribute 0. The `steps` counter is
+ * the billing count: one per model call, reported or not. */
+export function accumulateJobUsage(
+	total: JobUsage | undefined,
+	model: string,
+	step: UsageStepLike,
+): JobUsage {
+	const add = (a: number | undefined, b: number | undefined): number | undefined =>
+		a === undefined && b === undefined ? undefined : (a ?? 0) + (b ?? 0);
+	return {
+		model,
+		inputTokens: add(total?.inputTokens, step.inputTokens),
+		outputTokens: add(total?.outputTokens, step.outputTokens),
+		cacheReadTokens: add(total?.cacheReadTokens, step.inputTokenDetails?.cacheReadTokens),
+		cacheWriteTokens: add(total?.cacheWriteTokens, step.inputTokenDetails?.cacheWriteTokens),
+		reasoningTokens: add(total?.reasoningTokens, step.outputTokenDetails?.reasoningTokens),
+		steps: (total?.steps ?? 0) + 1,
+		lastStep: {
+			inputTokens: step.inputTokens,
+			outputTokens: step.outputTokens,
+			cacheReadTokens: step.inputTokenDetails?.cacheReadTokens,
+			cacheWriteTokens: step.inputTokenDetails?.cacheWriteTokens,
+			reasoningTokens: step.outputTokenDetails?.reasoningTokens,
+		},
+	};
 }
 
 /**
@@ -155,6 +202,11 @@ export interface SubagentResultMeta {
 	jobId: string;
 	kind: JobKind;
 	toolCallId: string;
+	/** Present only on an abort steer (2026-09 abort semantics): the
+	 * learner aborted the job (it lands as error "Aborted by learner");
+	 * the teacher is told so its promise of a result doesn't hang
+	 * silently in the lesson. */
+	aborted?: true;
 }
 
 /** The data-subagent-artifact part payload: what the UI renders. */
@@ -178,6 +230,20 @@ export interface SubagentSteerMessage extends UIMessage {
 	];
 }
 
+/** The abort steer: user-role like any steer, but NO artifact part —
+ * there is no result to render, only the teacher-facing text. Shares the
+ * result steer's deterministic id space (`steer_${jobId}`): steerDelivered
+ * matches on metadata jobId, so an abort and a (racing) result steer
+ * can never BOTH deliver — exactly one wakes the teacher. */
+export interface AbortSteerMessage extends UIMessage {
+	role: "user";
+	metadata: { subagentResult: SubagentResultMeta & { aborted: true } };
+	parts: [{ type: "text"; text: string }];
+}
+
+/** Anything the wake pipeline may queue and deliver. */
+export type SteerMessage = SubagentSteerMessage | AbortSteerMessage;
+
 /** Whether a result is the failure shape (html/svg empty, failure brief). */
 export function isSubagentFailure(kind: JobKind, result: ResearchResult | DemoResult | VisualResult): boolean {
 	if (kind === "research") {
@@ -234,6 +300,32 @@ export function buildSubagentSteer(
 	};
 }
 
+/** Build the abort steer for an aborted job (pure — shared by the
+ * abort path in src/server/jobs.ts and tests). Same id space as the result
+ * steer; see AbortSteerMessage. */
+export function buildAbortSteer(
+	job: Pick<JobRecord, "id" | "kind" | "toolCallId">,
+): AbortSteerMessage {
+	return {
+		id: `steer_${job.id}`,
+		role: "user",
+		metadata: {
+			subagentResult: { jobId: job.id, kind: job.kind, toolCallId: job.toolCallId, aborted: true },
+		},
+		parts: [{ type: "text", text: abortText(job.kind) }],
+	};
+}
+
+/** What the teacher reads: one line telling it the result is not coming,
+ * how to acknowledge, and that re-dispatching is allowed. */
+function abortText(kind: JobKind): string {
+	if (kind === "research")
+		return "Research aborted — the learner aborted the research job, so no brief is coming. Acknowledge it in one line and continue teaching without it (or offer to re-dispatch it).";
+	if (kind === "demo")
+		return "The demo job was aborted by the learner — no demo is coming. Acknowledge it in one line and teach the topic in prose instead (a re-dispatch is fine if the learner wants it).";
+	return "The figure job was aborted by the learner — no figure is coming. Acknowledge it in one line and teach without it (a re-dispatch is fine if the learner wants it).";
+}
+
 /** True when the transcript already carries this job's steer (idempotent delivery). */
 export function steerDelivered(messages: UIMessage[], jobId: string): boolean {
 	return messages.some(

src/core/graph.ts

@@ -42,6 +42,7 @@ import { randomBytes } from "node:crypto";
 import { isToolUIPart, type UIMessage } from "ai";
 import type {
 	AuditResult,
+	EmissionStats,
 	GraphEdge,
 	GraphNode,
 	ProvenancePoint,
@@ -108,15 +109,6 @@ const samePoint = (a: ProvenancePoint, b: ProvenancePoint): boolean =>
 
 // ─── the merger (extraction pipeline stage 3 — deterministic) ────────────────
 
-export interface EmissionStats {
-	/** New graph nodes appended. */
-	nodes: number;
-	/** New edge assertions appended. */
-	edges: number;
-	/** New ledger events appended. */
-	events: number;
-}
-
 /**
  * Merge one chat's audited findings into the graph ledgers — the pipeline's
  * apply stage. Deterministic + idempotent: re-merging the same verdicts (or
@@ -470,3 +462,6 @@ export function graphSnapshot(deps: GraphDeps): GraphSnapshot {
 
 	return { nodes, edges, sessions, nodeSessions, nodeObservations };
 }
+
+// Re-export: the contract owns the shape; legacy importers still reach it.
+export type { EmissionStats };

src/core/ports.ts

@@ -18,6 +18,7 @@ import type {
 	JobKind,
 	JobRecord,
 	LedgerEvent,
+	ExtractionRunUsage,
 	NodeMapping,
 	PlanTree,
 	SessionCheckpoint,
@@ -41,6 +42,8 @@ export interface ChatStore {
 	 * 2026-09): idempotent per messageId — a turn persisted twice (abort
 	 * replays, wake-turn retries) appends exactly once. */
 	appendTurnUsage(id: string, entry: TurnUsage): void;
+	/** Append one extraction-run usage entry — idempotent per startedAt. */
+	appendExtractionUsage(id: string, entry: ExtractionRunUsage): void;
 }
 
 // ─── GraphStore — the append-only evidence ledgers (data/graph) ──────────────