@crewhaus/runtime-core 0.3.2 → 0.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/index.js CHANGED
@@ -1,10 +1,12 @@
1
+ import { randomUUID } from "node:crypto";
1
2
  import { dirname as pathDirname } from "node:path";
2
3
  import * as readline from "node:readline/promises";
3
4
  import { createAbortTree } from "@crewhaus/abort-controller";
4
- import { collectFinalMessage, consumeStream, } from "@crewhaus/adapter-anthropic";
5
+ import { EFFORT_THINKING_BUDGET_TOKENS, collectFinalMessage, consumeStream, } from "@crewhaus/adapter-anthropic";
5
6
  import { classifyBoundary, setDefaultBoundaryLlmClassifier } from "@crewhaus/boundary-classifier";
6
7
  import { wrap as wrapWithCircuitBreaker } from "@crewhaus/circuit-breaker";
7
8
  import { autoCompact } from "@crewhaus/compaction-autocompact";
9
+ import { DEFAULT_DEDUPE_THRESHOLD, curate as curateItems, } from "@crewhaus/compaction-curator";
8
10
  import { snip } from "@crewhaus/compaction-snip";
9
11
  import { DEFAULT_PRICING, computeCostMicros, createCostTracker, resolvePricing, } from "@crewhaus/cost-tracker";
10
12
  import { classifyEgress, summarizeEgress, } from "@crewhaus/egress-classifier";
@@ -15,10 +17,11 @@ import { createFailoverChain, createPolicyRouter, createTierRouter, parseModelSt
15
17
  import { BUILTIN_DEFAULT_RULES, emptyRuleSet, evaluateJustification, evaluateWithReason, ruleBasedJustificationJudge, } from "@crewhaus/permission-engine";
16
18
  import { manage as manageCacheMarkers } from "@crewhaus/prompt-cache-manager";
17
19
  import { buildRedactionNotice, classifyText, llmClassifierEnabled, } from "@crewhaus/prompt-injection-detector";
20
+ import { createRateLimiter } from "@crewhaus/rate-limiter";
18
21
  import { advanceState, initialRecoveryState, recover, } from "@crewhaus/recovery-engine";
19
22
  import { computeReward, openScoreboard, } from "@crewhaus/routing-store";
20
23
  import { createRunContext, tagContent } from "@crewhaus/run-context";
21
- import { createSessionStore } from "@crewhaus/session-store";
24
+ import { createSessionStore, generateApprovalId, hashApprovalInput, } from "@crewhaus/session-store";
22
25
  import { formatSkillsForPrompt } from "@crewhaus/skills-registry";
23
26
  import { expand as expandSlash } from "@crewhaus/slash-commands";
24
27
  import { createStore } from "@crewhaus/state-store";
@@ -29,7 +32,7 @@ import { executeTool } from "@crewhaus/tool-executor";
29
32
  import { detectLoop } from "@crewhaus/tool-loop-detection";
30
33
  import { partitionToolCalls } from "@crewhaus/tool-orchestrator";
31
34
  import { storeAndPreview } from "@crewhaus/tool-result-store";
32
- import { TraceEventBus } from "@crewhaus/trace-event-bus";
35
+ import { TraceEventBus, } from "@crewhaus/trace-event-bus";
33
36
  import { initialState, transition, } from "@crewhaus/turn-state-machine";
34
37
  import { zodToJsonSchema } from "zod-to-json-schema";
35
38
  import { createCliMarkdownRenderer, isCliMarkdownEnabled, } from "./cli-markdown";
@@ -355,11 +358,32 @@ export async function mapWithConcurrency(items, limit, fn) {
355
358
  // moved into `@crewhaus/adapter-anthropic`. Re-exported here so legacy
356
359
  // importers (eval-judge fallback, downstream tests) keep compiling.
357
360
  export { CLAUDE_CODE_HEADERS, CLAUDE_CODE_SYSTEM_PREFIX, OAUTH_BETAS, createAnthropicClient, resolveAuth, } from "@crewhaus/adapter-anthropic";
361
+ // G12 — the platform-neutral loop core lives in `@crewhaus/worker-runtime`
362
+ // (imports no `node:*`); runtime-core CONSUMES it, re-exports its contract as
363
+ // the single source of truth, and supplies the NODE `WorkerPlatform` impl
364
+ // (`./worker-platform`). `runChatLoop`'s own node-coupled services
365
+ // (event-log, session-store, compaction, recovery, audit sinks) wrap this
366
+ // shared core; the three cf-worker emitters call `runWorkerLoop` directly
367
+ // with a stateless platform. These re-exports are purely additive — every
368
+ // existing `runChatLoop` / `RunChatLoopOptions` consumer is unchanged.
369
+ export { createInMemoryKV, createNodeWorkerPlatform } from "./worker-platform";
370
+ export { createEdgeAnthropicAdapter, classifyEdgeTool, EDGE_SAFE_TOOLS, HOST_ONLY_TOOLS, isEdgeSafeTool, partitionEdgeTools, runWorkerLoop, } from "@crewhaus/worker-runtime";
358
371
  // Ops item 36 — boot-time self-heal janitor for daemon shapes. Lives in its
359
372
  // own module (`./janitor`) but is re-exported here because emitted bundles
360
373
  // only import the package root.
361
374
  export { createJanitor } from "./janitor";
362
375
  export { JANITOR_BUILTIN_STEPS } from "./janitor";
376
+ // Loop contract 0.4 (Batch C, item 4) — agent identity generation. Lives in
377
+ // its own module (`./identity`) but is re-exported here because emitted
378
+ // bundles and the CLI only import the package root. The CLI calls
379
+ // `loadOrCreateAgentIdentity()` at boot and threads the resulting `agentId`
380
+ // into `RunChatLoopOptions.agentId` (and onto any bus it constructs itself).
381
+ export { AGENT_IDENTITY_SCHEMA_VERSION, DEFAULT_IDENTITY_DIR, IDENTITY_FILENAME, agentFingerprint, loadOrCreateAgentIdentity, } from "./identity";
382
+ // Loop contract 0.4 (Batch C, G11) — the pending-approval persistence seam is
383
+ // owned by `@crewhaus/session-store`; re-exported here so the CLI/codegen can
384
+ // build the store + input hash it passes as `RunChatLoopOptions.approvals`
385
+ // without depending on session-store directly.
386
+ export { createPendingApprovalStore, generateApprovalId, hashApprovalInput, } from "@crewhaus/session-store";
363
387
  // Ops item 31 — alert watchdog seams re-exported so the CLI/codegen can build
364
388
  // the durable + off-box alert sink (audit append + settings.json alert hook /
365
389
  // webhook) it passes as `RunChatLoopOptions.alertSink`.
@@ -593,7 +617,75 @@ function poolFingerprint(pool) {
593
617
  hash = ((hash << 5) + hash + canonical.charCodeAt(i)) >>> 0;
594
618
  return `pool-${hash.toString(36)}`;
595
619
  }
620
+ /** Read the branded timeout reason off an aborted signal, or undefined when
621
+ * the signal is not aborted / was aborted for another cause (SIGINT, EOF). */
622
+ export function timeoutAbortReason(signal) {
623
+ if (!signal.aborted)
624
+ return undefined;
625
+ const reason = signal.reason;
626
+ if (reason === null || typeof reason !== "object")
627
+ return undefined;
628
+ const scope = reason.crewhausTimeout;
629
+ if (scope !== "run" && scope !== "turn" && scope !== "model_call")
630
+ return undefined;
631
+ return {
632
+ crewhausTimeout: scope,
633
+ limitMs: typeof reason.limitMs === "number" ? reason.limitMs : 0,
634
+ };
635
+ }
636
+ /** Spec key each scope lowers from — used in detail/remediation copy. */
637
+ const TIMEOUT_SPEC_KEYS = {
638
+ run: "limits.deadline_ms",
639
+ turn: "limits.turn_timeout_ms",
640
+ model_call: "limits.model_call_timeout_ms",
641
+ };
642
+ const TIMEOUT_TITLES = {
643
+ run: "run deadline exceeded",
644
+ turn: "turn wall-clock limit exceeded",
645
+ model_call: "model call wall-clock limit exceeded",
646
+ };
647
+ /**
648
+ * G10 — build the classified terminal report for a fired wall-clock limit.
649
+ * `class: "timeout"` / exit {@link EXIT_CODES.timeout} joins the failure
650
+ * taxonomy beside `crewhaus_budget`: like the spend cap, the stop was
651
+ * CrewHaus's OWN configured ceiling, not a provider failure. Exported for
652
+ * emitters/tests that render or assert on the report.
653
+ */
654
+ export function buildTimeoutFailureReport(timeout) {
655
+ const scope = timeout.crewhausTimeout;
656
+ return {
657
+ class: "timeout",
658
+ title: TIMEOUT_TITLES[scope],
659
+ detail: `the configured ${TIMEOUT_SPEC_KEYS[scope]} (${timeout.limitMs}ms) elapsed before the ${scope === "run" ? "run" : scope === "turn" ? "turn" : "model call"} completed`,
660
+ remediation: `raise ${TIMEOUT_SPEC_KEYS[scope]} in the spec's limits block (or remove it), then rerun.`,
661
+ exitCode: EXIT_CODES.timeout,
662
+ };
663
+ }
664
+ /**
665
+ * Item 3 (G32) — merge plugin-contributed tools into the run's advertised tool
666
+ * set. First-party `base` tools WIN any name collision, so an activated plugin
667
+ * can augment the catalog but never silently shadow a built-in. Returns the
668
+ * `base` array unchanged (same reference) when there are no plugin tools, so a
669
+ * run without the `plugins` option is byte-identical to a pre-G32 runtime.
670
+ */
671
+ function mergeEffectiveTools(base, pluginTools) {
672
+ if (pluginTools === undefined || pluginTools.length === 0)
673
+ return base;
674
+ const byName = new Set(base.map((t) => t.name));
675
+ const merged = [...base];
676
+ for (const tool of pluginTools) {
677
+ if (byName.has(tool.name))
678
+ continue; // first-party wins the collision
679
+ byName.add(tool.name);
680
+ merged.push(tool);
681
+ }
682
+ return merged;
683
+ }
596
684
  export async function runChatLoop(opts) {
685
+ // Item 3 (G32) — resolve the advertised tool set ONCE, up front, folding in
686
+ // any plugin-contributed tools so the tool-capable-model feature gate and the
687
+ // per-turn advertisement below read the same list.
688
+ const effectiveTools = mergeEffectiveTools(opts.tools ?? [], opts.plugins?.tools);
597
689
  // Pillar 3 — make the model-backed Layer-3 classifier reachable at EVERY
598
690
  // trust boundary (MCP / sub-agent / channel / federation / skill /
599
691
  // compaction / chain / orchestrator). Boundary call sites don't thread an
@@ -684,7 +776,7 @@ export async function runChatLoop(opts) {
684
776
  // adapter that doesn't speak tool use (e.g. Bedrock Llama/Mistral
685
777
  // families). Fail with a clear ConfigError naming the model instead of
686
778
  // letting the provider 400 (or silently drop the tools) mid-run.
687
- if ((opts.tools ?? []).length > 0 && adapter.features.tool_use === false) {
779
+ if (effectiveTools.length > 0 && adapter.features.tool_use === false) {
688
780
  throw new ConfigError(`model "${opts.model}" (provider ${providerId}) does not support tool use — remove tools or pick a tool-capable model`);
689
781
  }
690
782
  let compactionAdapter;
@@ -734,6 +826,16 @@ export async function runChatLoop(opts) {
734
826
  // Item 26 — tool_use blocks the PREVIOUS turn produced (a tier-routing
735
827
  // signal). Persists across `runOneTurn` calls; 0 on the first turn.
736
828
  let priorTurnToolUseCount = 0;
829
+ // Item 4 / G28 — the provider's ACTUAL input_tokens (input + cache read +
830
+ // cache create) from the MOST RECENT `model_response`. Updated after every
831
+ // main-turn model call; feeds the pre-turn compaction trigger and the
832
+ // tier/pool routing `contextTokens` signal a real count instead of the
833
+ // chars/4 heuristic. `undefined` before the first response — the heuristic
834
+ // is used only pre-first-call.
835
+ let lastModelInputTokens;
836
+ /** The context-size signal for routing/compaction: the provider's real
837
+ * last-call input_tokens once available, else the chars/4 estimate. */
838
+ const contextTokenSignal = (msgs) => lastModelInputTokens ?? estimateTokens(msgs);
737
839
  // Default model max OUTPUT tokens for one turn. Callers thread the spec's
738
840
  // `agent.max_tokens` here when set (the CLI target's codegen + apps/cli);
739
841
  // this fallback applies when the spec is silent. Kept comfortably above the
@@ -743,6 +845,34 @@ export async function runChatLoop(opts) {
743
845
  // `max_tokens` recovery + `sanitizeOrphanToolUses`), but a higher ceiling
744
846
  // avoids the churn. Raise it per spec with `agent.max_tokens`.
745
847
  const maxTokens = opts.maxTokens ?? 8192;
848
+ // G01 — resolve the extended-thinking request fields ONCE at boot. The
849
+ // budget form maps verbatim; the effort form sets BOTH `thinking`
850
+ // (converted through the shared preset table for budget-style providers)
851
+ // and `reasoningEffort` (passed through for native-effort providers) —
852
+ // adapters ignore whichever field they don't support, and anthropic's
853
+ // translate gives the explicit `thinking` precedence, so the two agree.
854
+ const thinkingRequest = opts.thinking === undefined
855
+ ? undefined
856
+ : "budgetTokens" in opts.thinking
857
+ ? { thinking: { type: "enabled", budgetTokens: opts.thinking.budgetTokens } }
858
+ : {
859
+ thinking: {
860
+ type: "enabled",
861
+ budgetTokens: EFFORT_THINKING_BUDGET_TOKENS[opts.thinking.effort],
862
+ },
863
+ reasoningEffort: opts.thinking.effort,
864
+ };
865
+ // Anthropic (and the other budget-style providers) require
866
+ // `max_tokens > thinking.budget_tokens` — thinking tokens spend from the
867
+ // same output ceiling. When the configured budget crowds the ceiling out,
868
+ // lift the per-request ceiling to `budget + maxTokens` so the declared
869
+ // output budget survives intact instead of 400-ing every call (e.g.
870
+ // `effort: high` = 24576 over the 8192 default). The spec-declared
871
+ // `maxTokens` stays the bridge/sub-agent value — only main-turn requests
872
+ // (the only ones that carry `thinking`) use the lifted ceiling.
873
+ const effectiveMaxTokens = thinkingRequest !== undefined && thinkingRequest.thinking.budgetTokens >= maxTokens
874
+ ? thinkingRequest.thinking.budgetTokens + maxTokens
875
+ : maxTokens;
746
876
  // Mutual exclusion: resume takes priority and replaces any seedMessages
747
877
  // in REPL mode (the resume payload becomes the seed). Section 12 carves
748
878
  // out an exception for singleTurn + resume: the seed is the NEW inbound
@@ -899,7 +1029,29 @@ export async function runChatLoop(opts) {
899
1029
  // sessionId; otherwise build a fresh context bound to that sessionId.
900
1030
  // Tests that pass their own runContext rely on observing turnNumber on
901
1031
  // it after the loop returns, so we never silently swap it out.
902
- const runContext = opts.runContext ?? createRunContext({ sessionId });
1032
+ //
1033
+ // Loop contract 0.4 (Batch C, item 4) — when the caller supplies an
1034
+ // `agentId` and lets runChatLoop own the context, build the bus with that
1035
+ // identity so `envelope()` stamps every trace event with it. runId is minted
1036
+ // here (matching run-context's `run_<8 hex>` shape) and threaded into BOTH
1037
+ // the bus and the context so their ids stay coherent. When `opts.runContext`
1038
+ // is supplied the caller owns `agentId` on its bus, so this is skipped.
1039
+ const runContext = opts.runContext ??
1040
+ (opts.agentId !== undefined
1041
+ ? (() => {
1042
+ const runId = `run_${randomUUID().slice(0, 8)}`;
1043
+ const eventBus = new TraceEventBus({ runId, sessionId, agentId: opts.agentId });
1044
+ return createRunContext({ runId, sessionId, eventBus });
1045
+ })()
1046
+ : createRunContext({ sessionId }));
1047
+ // G01 — surface the max-tokens lift once, at boot (see `effectiveMaxTokens`).
1048
+ if (effectiveMaxTokens !== maxTokens) {
1049
+ runContext.logger.info("thinking budget >= max_tokens — lifting the per-request ceiling", {
1050
+ thinkingBudgetTokens: thinkingRequest?.thinking.budgetTokens,
1051
+ maxTokens,
1052
+ effectiveMaxTokens,
1053
+ });
1054
+ }
903
1055
  // Adaptive model routing — ε-greedy exploration seed. A spec-fixed
904
1056
  // `learning.seed` reproduces exploration across runs (tests); otherwise the
905
1057
  // sessionId seeds it, so each run explores differently yet still replays
@@ -911,7 +1063,6 @@ export async function runChatLoop(opts) {
911
1063
  // mints a no-subscriber bus; here we attach the env-gated set so a fresh
912
1064
  // run with `OTEL_EXPORTER_OTLP_ENDPOINT` set automatically exports.
913
1065
  const bus = runContext.eventBus;
914
- void TraceEventBus; // keep type import alive for future direct constructions
915
1066
  // Item 22 — re-point the failover chain's late-bound bus getter at the
916
1067
  // run's real bus (see the chain construction above): the chain and its
917
1068
  // per-candidate breakers publish model_failover / circuit_state_changed
@@ -1314,6 +1465,28 @@ export async function runChatLoop(opts) {
1314
1465
  const compactionThreshold = opts.compactionThreshold ?? DEFAULT_COMPACTION_THRESHOLD;
1315
1466
  const snipKeepHead = opts.snipKeepHead ?? DEFAULT_SNIP_KEEP_HEAD;
1316
1467
  const snipKeepTail = opts.snipKeepTail ?? DEFAULT_SNIP_KEEP_TAIL;
1468
+ // Item 1 / G19 — active-context curation config (present ⇒ the pre-pass
1469
+ // runs, gated by the emitter on `ir.compaction.curate`) and the shared
1470
+ // extra `maybeCompact` args threaded at both call sites: the injected
1471
+ // curate config, the `curate`-event publisher, and the real-token trigger.
1472
+ const curateConfig = opts.curate;
1473
+ const publishCurate = async (info) => {
1474
+ bus.publish({
1475
+ ...bus.envelope(),
1476
+ kind: "curate",
1477
+ before: info.before,
1478
+ after: info.after,
1479
+ dropped: info.dropped,
1480
+ bytesSaved: info.bytesSaved,
1481
+ embedded: info.embedded,
1482
+ });
1483
+ };
1484
+ /** The extra `maybeCompact` args (Item 1 curation + Item 4 real tokens),
1485
+ * recomputed per call so `realInputTokens` reflects the newest response. */
1486
+ const compactionExtras = () => ({
1487
+ ...(lastModelInputTokens !== undefined ? { realInputTokens: lastModelInputTokens } : {}),
1488
+ ...(curateConfig !== undefined ? { curate: curateConfig, onCurate: publishCurate } : {}),
1489
+ });
1317
1490
  const permissionMode = opts.permissionMode ?? "default";
1318
1491
  const permissionRules = opts.permissionRules ?? {
1319
1492
  ...emptyRuleSet,
@@ -1375,35 +1548,31 @@ export async function runChatLoop(opts) {
1375
1548
  .map((f) => f.filename)
1376
1549
  .join(", ")}\n`);
1377
1550
  }
1378
- // Feature #53 — auto-recall: at session start, pull the top-K relevant
1379
- // cross-session memories and inject them as a system block, mirroring the
1380
- // project-memory auto-load above. The caller supplies the `recall` seam
1381
- // (runtime-core stays independent of memory-store). Best-effort: a recall
1382
- // failure never aborts the run.
1551
+ // Feature #53 / Item 2 (G21) — cross-session auto-recall. `recallMode`
1552
+ // decides WHERE the recalled evidence lives:
1553
+ // - "session-start" (default): pull the top-K relevant memories ONCE at
1554
+ // boot and inject them into the frozen, cache-marked system prefix
1555
+ // below — the pre-0.4 behaviour.
1556
+ // - "per-turn": leave the frozen prefix empty and instead refresh a
1557
+ // VOLATILE recalled block every `refreshEvery` turns (see
1558
+ // `maybePerTurnRecall`), so a long daemon's evidence tracks the
1559
+ // conversation instead of drifting from a stale boot-time snapshot.
1560
+ // The caller supplies the `recall` seam (runtime-core stays independent of
1561
+ // memory-store). Best-effort: a recall failure never aborts the run.
1562
+ const recallMode = opts.memory?.recallMode ?? "session-start";
1563
+ const autoRecallOn = opts.memory?.autoRecall === true && opts.memory?.recall !== undefined;
1383
1564
  let memoryRecallBlock = [];
1384
- if (opts.memory?.autoRecall === true && opts.memory.recall !== undefined) {
1565
+ if (autoRecallOn && recallMode !== "per-turn" && opts.memory?.recall !== undefined) {
1385
1566
  try {
1386
1567
  const seed = opts.memory.recallSeed ?? opts.instructions;
1387
1568
  const k = opts.memory.recallK ?? 5;
1569
+ // Pillar 3 — a recalled memory can embed content shaped by untrusted
1570
+ // tool output from an earlier session; `renderRecalledMemory` applies
1571
+ // the same delimiter-safety + boundary-classification defenses the
1572
+ // security fabric uses for every other prompt-bound source (#53).
1388
1573
  const lines = await opts.memory.recall(seed, k);
1389
- if (lines.length > 0) {
1390
- // Pillar 3 — a recalled memory can embed content shaped by untrusted
1391
- // tool output from an earlier session, so it is NOT verbatim-safe like
1392
- // the developer's own repo files. Two defenses, mirroring how the rest
1393
- // of the security fabric treats injected content:
1394
- // 1. Delimiter safety — neutralize any `</recalled_memory>` closing
1395
- // tag inside a recalled line so a poisoned memory can't break out
1396
- // of its block and inject trailing instructions.
1397
- // 2. Classification — run the assembled block through the SAME
1398
- // `classifyBoundary(text, { origin: "user" })` best-effort path
1399
- // `loadProjectMemory()` uses (pass policy: classify + emit trace
1400
- // events without mutating), so recalled content flows through the
1401
- // boundary classifier exactly like every other prompt-bound source.
1402
- const body = lines
1403
- .map((l) => `- ${escapeBoundaryDelimiter(l, "recalled_memory")}`)
1404
- .join("\n");
1405
- const text = `<recalled_memory>\nRelevant facts remembered from earlier sessions:\n${body}\n</recalled_memory>`;
1406
- await classifyBoundary(text, { origin: "user" }).catch(() => undefined);
1574
+ const text = await renderRecalledMemory(lines);
1575
+ if (text !== undefined) {
1407
1576
  memoryRecallBlock = [{ type: "text", text, cache_control: { type: "ephemeral" } }];
1408
1577
  process.stdout.write(`[memory] recalled ${lines.length} memory(ies) into the prompt\n`);
1409
1578
  }
@@ -1412,6 +1581,44 @@ export async function runChatLoop(opts) {
1412
1581
  runContext.logger.warn("memory auto-recall failed", { error: err.message });
1413
1582
  }
1414
1583
  }
1584
+ // Item 2 (G21) — per-turn recall state. The volatile block sits in the
1585
+ // mutable tail region (never the frozen prefix), so swapping it each turn
1586
+ // re-tokenizes only the tail and never busts the cached system prefix. The
1587
+ // refresh cadence counter starts "due" so the first applicable turn recalls.
1588
+ const perTurnRecallEnabled = autoRecallOn && recallMode === "per-turn";
1589
+ const perTurnRefreshEvery = Math.max(1, opts.memory?.refreshEvery ?? 1);
1590
+ let volatileRecallBlocks = [];
1591
+ let turnsSinceRecall = perTurnRefreshEvery;
1592
+ const maybePerTurnRecall = async (msgs) => {
1593
+ if (!perTurnRecallEnabled)
1594
+ return;
1595
+ if (turnsSinceRecall < perTurnRefreshEvery) {
1596
+ turnsSinceRecall++;
1597
+ return;
1598
+ }
1599
+ turnsSinceRecall = 1;
1600
+ const recall = opts.memory?.recall;
1601
+ if (recall === undefined)
1602
+ return;
1603
+ // Recall against the LATEST user message (the interactive cadence), falling
1604
+ // back to the seed/instructions when the tail carries no human text.
1605
+ const query = latestUserText(msgs) ?? opts.memory?.recallSeed ?? opts.instructions;
1606
+ const k = opts.memory?.recallK ?? 5;
1607
+ try {
1608
+ const lines = await recall(query, k);
1609
+ const text = await renderRecalledMemory(lines);
1610
+ volatileRecallBlocks = text !== undefined ? [{ type: "text", text }] : [];
1611
+ if (lines.length > 0) {
1612
+ process.stdout.write(`[memory] refreshed ${lines.length} recalled memory(ies) for this turn\n`);
1613
+ }
1614
+ }
1615
+ catch (err) {
1616
+ // Keep the prior volatile block on a transient recall failure.
1617
+ runContext.logger.warn("per-turn memory recall failed", {
1618
+ error: err.message,
1619
+ });
1620
+ }
1621
+ };
1415
1622
  // Section 17 — runtime-core no longer prepends the Claude Code OAuth
1416
1623
  // prefix; `adapter-anthropic` handles that internally so each adapter
1417
1624
  // owns its provider-specific auth-shape requirements.
@@ -1466,7 +1673,7 @@ export async function runChatLoop(opts) {
1466
1673
  }
1467
1674
  }
1468
1675
  }
1469
- const tools = opts.tools ?? [];
1676
+ const tools = effectiveTools;
1470
1677
  const anthropicTools = tools.length > 0
1471
1678
  ? tools.map((t) => ({
1472
1679
  name: t.name,
@@ -1475,6 +1682,33 @@ export async function runChatLoop(opts) {
1475
1682
  }))
1476
1683
  : undefined;
1477
1684
  const toolByName = new Map(tools.map((t) => [t.name, t]));
1685
+ // G17 — per-tool rate limiter, built once at loop start from the lowered
1686
+ // `agent.rate_limits` map. One token bucket per entry: `rpm` is the
1687
+ // sustained refill (per-minute → per-second), `burst` the instantaneous
1688
+ // capacity (defaults to `rpm`, the standard token-bucket parameterization
1689
+ // where a full window's allowance may burst). The `"*"` key becomes the
1690
+ // limiter's per-dimension `tool:*` default, which `acquire` falls back to
1691
+ // for any tool without a named bucket — each such tool still gets its OWN
1692
+ // bucket instance (state keys on the specific `tool:<name>`), so the
1693
+ // default is a per-tool limit, not one shared pool. `hasToolRateBucket`
1694
+ // gates the acquire call site: tools outside the map (no named entry, no
1695
+ // `"*"`) are not rate-gated at all — the limiter itself is fail-closed on
1696
+ // unknown keys, so the guard is what keeps unlisted tools ungated.
1697
+ const rateLimitEntries = Object.entries(opts.rateLimits ?? {});
1698
+ let toolRateLimiter;
1699
+ if (rateLimitEntries.length > 0) {
1700
+ const buckets = new Map();
1701
+ for (const [name, limit] of rateLimitEntries) {
1702
+ buckets.set(`tool:${name}`, {
1703
+ kind: "token-bucket",
1704
+ capacity: limit.burst ?? limit.rpm,
1705
+ refillPerSec: limit.rpm / 60,
1706
+ });
1707
+ }
1708
+ toolRateLimiter = createRateLimiter({ buckets });
1709
+ }
1710
+ const hasToolRateBucket = (toolName) => opts.rateLimits !== undefined &&
1711
+ (opts.rateLimits[toolName] !== undefined || opts.rateLimits["*"] !== undefined);
1478
1712
  // Root abort tree for the whole run; each turn gets a child.
1479
1713
  const runAbort = createAbortTree(runContext.abortSignal);
1480
1714
  // Per-turn abort tree, replaced at the start of each turn so a SIGINT
@@ -1482,17 +1716,97 @@ export async function runChatLoop(opts) {
1482
1716
  let turnAbort = runAbort.child();
1483
1717
  // Latest error captured from a model call, fed to recover() on entry to NeedRecovery.
1484
1718
  let lastErrorForRecovery = undefined;
1719
+ const fireTimeout = (tree, scope, limitMs) => {
1720
+ out.spinner.stop();
1721
+ const noun = scope === "run" ? "run deadline" : scope === "turn" ? "turn timeout" : "model call timeout";
1722
+ out.write(`\n[${noun}: ${limitMs}ms elapsed — aborting]\n`);
1723
+ runContext.logger.warn("wall-clock limit fired", { scope, limitMs });
1724
+ tree.abort({ crewhausTimeout: scope, limitMs });
1725
+ };
1726
+ const armTimer = (tree, scope, limitMs) => {
1727
+ const timer = setTimeout(() => fireTimeout(tree, scope, limitMs), limitMs);
1728
+ timer.unref();
1729
+ return timer;
1730
+ };
1731
+ let deadlineTimer;
1732
+ if (opts.deadlineMs !== undefined && opts.deadlineMs > 0) {
1733
+ deadlineTimer = armTimer(runAbort, "run", opts.deadlineMs);
1734
+ }
1735
+ let turnTimer;
1736
+ const armTurnTimer = () => {
1737
+ if (opts.turnTimeoutMs === undefined || opts.turnTimeoutMs <= 0)
1738
+ return;
1739
+ turnTimer = armTimer(turnAbort, "turn", opts.turnTimeoutMs);
1740
+ };
1741
+ const clearTurnTimer = () => {
1742
+ if (turnTimer !== undefined)
1743
+ clearTimeout(turnTimer);
1744
+ turnTimer = undefined;
1745
+ };
1746
+ let modelCallTimer;
1747
+ const armModelCallTimer = () => {
1748
+ if (opts.modelCallTimeoutMs === undefined || opts.modelCallTimeoutMs <= 0)
1749
+ return;
1750
+ modelCallTimer = armTimer(turnAbort, "model_call", opts.modelCallTimeoutMs);
1751
+ };
1752
+ const clearModelCallTimer = () => {
1753
+ if (modelCallTimer !== undefined)
1754
+ clearTimeout(modelCallTimer);
1755
+ modelCallTimer = undefined;
1756
+ };
1757
+ const clearAllTimers = () => {
1758
+ if (deadlineTimer !== undefined)
1759
+ clearTimeout(deadlineTimer);
1760
+ deadlineTimer = undefined;
1761
+ clearTurnTimer();
1762
+ clearModelCallTimer();
1763
+ };
1485
1764
  // Permission-ask prompter. Set in REPL mode after the readline interface
1486
1765
  // exists; remains undefined in single-turn mode (where ask collapses to deny).
1487
1766
  // The initial assignment makes the second assignment legal under biome's
1488
1767
  // `useConst` rule (which fires on exactly-one-assignment lets).
1489
1768
  let askApproval = undefined;
1769
+ // Loop contract 0.4 (Batch C, G11) — headless ask-approval parking. `askMode`
1770
+ // is the lowered `permissions.ask_mode` (absent ⇒ "pause"); `approvals` is
1771
+ // the injected persistence seam. Parking is active only when BOTH a store is
1772
+ // present AND the mode is "pause" — otherwise a headless `ask` collapses to
1773
+ // the pre-0.4 deny. `approvalSurface` classifies the `approval_requested`
1774
+ // event; it never affects the REPL path (which prompts on stdin).
1775
+ const askMode = opts.askMode ?? "pause";
1776
+ const approvals = opts.approvals;
1777
+ const approvalSurface = approvals?.surface ?? (opts.singleTurn === true ? "single-turn" : "headless");
1490
1778
  // Per-run state for tool-loop detection and warning de-dup. Both span
1491
1779
  // turns within a single `runChatLoop` invocation so cross-turn loops
1492
1780
  // (e.g. "keep running date") get caught and warned at most once per
1493
1781
  // signature.
1782
+ //
1783
+ // G27 — `loopSignatureStage` replaces the old warned-signature Set with a
1784
+ // two-stage ladder per signature: first detection → `"warned"` (the
1785
+ // pre-0.4 one-time warning, all escalation modes), a REPEAT detection of
1786
+ // the same signature → the configured escalation (`justify` demand or
1787
+ // turn `abort`), recorded as `"escalated"` so it fires at most once per
1788
+ // signature too. In the default `"warn"` mode the second stage is a
1789
+ // no-op — byte-identical behaviour to the pre-0.4 runtime.
1494
1790
  const toolUseHistory = [];
1495
- const warnedLoopSignatures = new Set();
1791
+ const loopSignatureStage = new Map();
1792
+ const loopEscalation = opts.loopDetection?.escalation ?? "warn";
1793
+ // Loop contract 0.4 (Batch C, item 7) — per-tool cost attribution. When a
1794
+ // NON-streaming model response that emitted tool_use blocks is priceable, the
1795
+ // response's cost is split evenly across those calls and stashed here by
1796
+ // tool_use id, then stamped as `attributedCostUsdMicros` on each `tool_use`
1797
+ // event-log record. Keyed by id (unique per call) and consumed (deleted) on
1798
+ // read to bound growth. The streaming path dispatches tools BEFORE the
1799
+ // response's usage is known, so it never populates this map — precisely the
1800
+ // "where the model usage split is computable" boundary: absent ⇒ no field.
1801
+ const toolCostAttribution = new Map();
1802
+ // Response cost in USD-micros, or undefined when the served model isn't on the
1803
+ // pricing table (the split is then not computable — no attribution stamped).
1804
+ const responseCostMicros = (provider, wireModelId, usage) => {
1805
+ const row = resolvePricing(DEFAULT_PRICING, provider, wireModelId);
1806
+ if (row === undefined)
1807
+ return undefined;
1808
+ return computeCostMicros(row, usage.input, usage.output, usage.cacheRead ?? 0, usage.cacheCreate ?? 0);
1809
+ };
1496
1810
  // Working-indicator bookkeeping for tool execution. A single shared spinner
1497
1811
  // serves the whole loop, so the set tracks which tools are mid-flight to
1498
1812
  // support the concurrent (read-only) partition: the label reflects how many
@@ -1534,7 +1848,18 @@ export async function runChatLoop(opts) {
1534
1848
  if (activeToolNames.length === 0)
1535
1849
  out.spinner.stop();
1536
1850
  out.write(`[tool: ${tu.name}]\n`);
1537
- await logEvent("tool_use", { id: tu.id, name: tu.name, input: tu.input });
1851
+ // Item 7 — stamp the per-tool cost attribution when the producing response
1852
+ // was priceable (non-streaming path only; see `toolCostAttribution`).
1853
+ // Consume the entry so the map stays bounded across a long run.
1854
+ const attributedCostUsdMicros = toolCostAttribution.get(tu.id);
1855
+ if (attributedCostUsdMicros !== undefined)
1856
+ toolCostAttribution.delete(tu.id);
1857
+ await logEvent("tool_use", {
1858
+ id: tu.id,
1859
+ name: tu.name,
1860
+ input: tu.input,
1861
+ ...(attributedCostUsdMicros !== undefined ? { attributedCostUsdMicros } : {}),
1862
+ });
1538
1863
  const inputBytes = Buffer.byteLength(JSON.stringify(tu.input ?? null), "utf8");
1539
1864
  const toolStartEnvelope = bus.envelope();
1540
1865
  bus.publish({
@@ -1627,22 +1952,90 @@ export async function runChatLoop(opts) {
1627
1952
  }
1628
1953
  else if (decision === "ask") {
1629
1954
  if (askApproval !== undefined) {
1955
+ // Interactive REPL path — unchanged: prompt on stdin.
1630
1956
  approved = await askApproval(tu.name, tu.input);
1631
1957
  if (!approved)
1632
1958
  denialMessage = "tool denied by user";
1633
1959
  }
1960
+ else if (approvals !== undefined && askMode === "pause") {
1961
+ // G11 headless parking/resume. Consult the store for a prior decision
1962
+ // on this exact (toolName, inputHash).
1963
+ const inputHash = hashApprovalInput(tu.name, tu.input);
1964
+ const existing = await approvals.store.get(tu.name, inputHash);
1965
+ if (existing?.decision === "grant") {
1966
+ // One-shot allow: consume the grant so a later identical call re-asks.
1967
+ approved = true;
1968
+ await approvals.store.persist({ ...existing, consumedAt: new Date().toISOString() });
1969
+ }
1970
+ else if (existing?.decision === "deny") {
1971
+ approved = false;
1972
+ denialMessage = `tool denied: \`${tu.name}\` approval was denied${existing.decidedBy !== undefined ? ` by ${existing.decidedBy}` : ""}.`;
1973
+ }
1974
+ else {
1975
+ // No decision yet. Reuse an existing pending record for this key
1976
+ // (idempotent re-park across resumed runs) or persist a fresh one,
1977
+ // fire the out-of-band notification, publish `approval_requested`,
1978
+ // and PARK: throw the classified `approval_pending` report. The
1979
+ // NeedTools catch (non-streaming) publishes `run_failed` + rethrows;
1980
+ // the streaming path reaches the same halt through recovery's
1981
+ // classified-report passthrough. On the next execution the store
1982
+ // carries a grant/deny and the call re-resolves pre-decided.
1983
+ const pending = existing ?? {
1984
+ id: generateApprovalId(),
1985
+ toolName: tu.name,
1986
+ inputHash,
1987
+ input: tu.input,
1988
+ runId: bus.runId,
1989
+ sessionId,
1990
+ surface: approvalSurface,
1991
+ createdAt: new Date().toISOString(),
1992
+ };
1993
+ if (existing === null)
1994
+ await approvals.store.persist(pending);
1995
+ if (approvals.notify !== undefined) {
1996
+ await approvals.notify(pending).catch((err) => {
1997
+ runContext.logger.warn("approvals.notify failed", {
1998
+ approvalId: pending.id,
1999
+ error: err.message,
2000
+ });
2001
+ });
2002
+ }
2003
+ bus.publish({
2004
+ ...bus.envelope(),
2005
+ kind: "approval_requested",
2006
+ approvalId: pending.id,
2007
+ toolName: tu.name,
2008
+ surface: approvalSurface,
2009
+ });
2010
+ runContext.logger.info("tool approval parked", {
2011
+ approvalId: pending.id,
2012
+ toolName: tu.name,
2013
+ surface: approvalSurface,
2014
+ });
2015
+ throw new RunFailedError({
2016
+ class: "approval_pending",
2017
+ title: "awaiting tool approval",
2018
+ detail: `\`${tu.name}\` requires approval on a non-interactive surface (${approvalSurface}); the run is parked as approval ${pending.id}`,
2019
+ remediation: `grant or deny approval ${pending.id} out of band (e.g. \`crewhaus approvals grant ${pending.id}\`), then rerun`,
2020
+ exitCode: EXIT_CODES.approval_pending,
2021
+ });
2022
+ }
2023
+ }
1634
2024
  else {
2025
+ // Pre-0.4 collapse-to-deny: no interactive surface, and either
2026
+ // `ask_mode: "deny"` or no approvals store is wired to park against.
1635
2027
  denialMessage =
1636
- `tool denied: \`${tu.name}\` defaulted to "ask" and single-turn mode has no interactive surface to prompt on. ` +
1637
- `Add an explicit rule to permissions.rules in your spec, e.g. \`{ type: alwaysAllow, pattern: ${tu.name} }\`, or run in REPL mode where "ask" can prompt.`;
2028
+ `tool denied: \`${tu.name}\` defaulted to "ask" and this non-interactive surface has no way to prompt` +
2029
+ `${approvals === undefined ? " (no approvals store wired)" : ' (ask_mode: "deny")'}. ` +
2030
+ `Add an explicit rule to permissions.rules in your spec, e.g. \`{ type: alwaysAllow, pattern: ${tu.name} }\`, run in REPL mode where "ask" can prompt, or set ask_mode: pause with an approvals store to park for out-of-band approval.`;
1638
2031
  }
1639
2032
  // Advisor groundwork (item 14) — event the ask RESOLUTION. The publish
1640
- // above fired BEFORE the approval prompt (decision "ask", no outcome);
1641
- // this one fires after `askApproval` resolves — or after the
1642
- // single-turn fallback collapses the ask to a deny — so offline advice
1643
- // mining can measure how each tool's prompts are actually answered.
1644
- // The advisor persistence subscriber (observability.ts) keys on
1645
- // `askOutcome` to persist exactly this resolved form.
2033
+ // above fired BEFORE the approval resolved (decision "ask", no outcome);
2034
+ // this one fires after the REPL prompt / store decision / collapse
2035
+ // resolves — so offline advice mining can measure how each tool's prompts
2036
+ // are actually answered. The advisor persistence subscriber
2037
+ // (observability.ts) keys on `askOutcome` to persist exactly this resolved
2038
+ // form. Unreached on the PARK path, which throws above.
1646
2039
  bus.publish({
1647
2040
  ...bus.envelope(),
1648
2041
  kind: "permission_decision",
@@ -1830,6 +2223,32 @@ export async function runChatLoop(opts) {
1830
2223
  });
1831
2224
  }
1832
2225
  }
2226
+ // G17 — per-tool rate gate. Sits AFTER every deny-capable gate
2227
+ // (permission / justification / egress) so a denied call never burns a
2228
+ // token, and BEFORE dispatch so the pacing wait is what the model
2229
+ // experiences as tool latency. Only tools with a named bucket or under
2230
+ // a `"*"` default are gated (the limiter is fail-closed on unknown
2231
+ // keys, so the guard is what keeps unlisted tools ungated). Exhausting
2232
+ // the limiter's wait budget fails just THIS call with an `is_error`
2233
+ // result the model can adapt to — never the run.
2234
+ if (toolRateLimiter !== undefined && hasToolRateBucket(tu.name)) {
2235
+ try {
2236
+ await toolRateLimiter.acquire([{ dimension: "tool", id: tu.name }], 1);
2237
+ }
2238
+ catch (err) {
2239
+ runContext.logger.warn("tool rate limit exhausted", {
2240
+ toolUseId: tu.id,
2241
+ toolName: tu.name,
2242
+ error: err.message,
2243
+ });
2244
+ return finish({
2245
+ type: "tool_result",
2246
+ tool_use_id: tu.id,
2247
+ content: `[rate-limited] ${err.message}. Wait before retrying "${tu.name}", or proceed another way.`,
2248
+ is_error: true,
2249
+ });
2250
+ }
2251
+ }
1833
2252
  const toolAbort = turnAbort.child();
1834
2253
  // Build the bridge for this call. Built on EVERY run (#160 follow-up):
1835
2254
  // it carries `runContext`, which Pillar-3 boundary-site tools (tool-mcp,
@@ -2092,28 +2511,77 @@ export async function runChatLoop(opts) {
2092
2511
  }
2093
2512
  return results;
2094
2513
  }
2514
+ function evaluateToolLoop() {
2515
+ const detection = detectLoop(toolUseHistory, opts.loopDetection?.window, opts.loopDetection?.threshold);
2516
+ if (detection === null)
2517
+ return { kind: "none" };
2518
+ const stage = loopSignatureStage.get(detection.signature);
2519
+ if (stage === undefined) {
2520
+ loopSignatureStage.set(detection.signature, "warned");
2521
+ runContext.logger.warn("tool loop detected", {
2522
+ signature: detection.signature,
2523
+ toolName: detection.toolName,
2524
+ count: detection.count,
2525
+ tier: detection.tier,
2526
+ escalation: loopEscalation,
2527
+ });
2528
+ const how = detection.tier === "exact"
2529
+ ? "with the same input"
2530
+ : "with near-identical inputs (differing only in numbers/ids)";
2531
+ return {
2532
+ kind: "message",
2533
+ stage: "warn",
2534
+ detection,
2535
+ message: {
2536
+ role: "user",
2537
+ content: `[runtime] possible loop detected: tool "${detection.toolName}" has been called ${detection.count} times ${how} within the last ${detection.windowSize} calls. Reconsider before repeating; respond with a different approach or final text.`,
2538
+ },
2539
+ };
2540
+ }
2541
+ if (stage !== "warned")
2542
+ return { kind: "none" };
2543
+ if (loopEscalation === "justify") {
2544
+ loopSignatureStage.set(detection.signature, "escalated");
2545
+ runContext.logger.warn("tool loop persists — demanding justification", {
2546
+ signature: detection.signature,
2547
+ toolName: detection.toolName,
2548
+ count: detection.count,
2549
+ tier: detection.tier,
2550
+ });
2551
+ return {
2552
+ kind: "message",
2553
+ stage: "justify",
2554
+ detection,
2555
+ message: {
2556
+ role: "user",
2557
+ content: `[runtime] the loop on tool "${detection.toolName}" persists after a warning. Before calling "${detection.toolName}" again you MUST state, in one sentence, a justification tying the repeat to the session goal and the NEW outcome you expect (the same discipline requireJustification-gated tools demand). If you cannot, do not repeat the call — take a different approach or answer with final text.`,
2558
+ },
2559
+ };
2560
+ }
2561
+ if (loopEscalation === "abort") {
2562
+ loopSignatureStage.set(detection.signature, "escalated");
2563
+ return { kind: "abort", detection };
2564
+ }
2565
+ // escalation "warn" — the warning already fired once; stay quiet.
2566
+ return { kind: "none" };
2567
+ }
2095
2568
  /**
2096
- * Convert a freshly-detected loop into a synthetic user message that
2097
- * nudges the model to break the cycle. Returns `null` if no loop is
2098
- * currently detected, or if this signature has already produced a
2099
- * warning earlier in the run.
2569
+ * G27 `escalation: "abort"` bookkeeping — the ToolLoopLimit-style
2570
+ * classified error record (named `error` event + logger line), shared by
2571
+ * the streaming and non-streaming tool-batch call sites. The caller takes
2572
+ * the `Aborted` state transition itself (the two sites sit at different
2573
+ * points in the state machine).
2100
2574
  */
2101
- function maybeBuildLoopWarning() {
2102
- const detection = detectLoop(toolUseHistory);
2103
- if (detection === null)
2104
- return null;
2105
- if (warnedLoopSignatures.has(detection.signature))
2106
- return null;
2107
- warnedLoopSignatures.add(detection.signature);
2108
- runContext.logger.warn("tool loop detected", {
2109
- signature: detection.signature,
2575
+ async function recordLoopAbort(detection) {
2576
+ await logEvent("error", {
2577
+ name: "ToolLoopAbort",
2578
+ message: `aborting turn: tool "${detection.toolName}" still looping (${detection.count}x in the last ${detection.windowSize} calls) after a warning — limits.loop_detection.escalation is "abort"`,
2579
+ });
2580
+ runContext.logger.error("tool loop escalation — aborting turn", {
2110
2581
  toolName: detection.toolName,
2111
- count: detection.count,
2582
+ signature: detection.signature,
2583
+ tier: detection.tier,
2112
2584
  });
2113
- return {
2114
- role: "user",
2115
- content: `[runtime] possible loop detected: tool "${detection.toolName}" has been called ${detection.count} times with the same input within the last ${detection.windowSize} calls. Reconsider before repeating; respond with a different approach or final text.`,
2116
- };
2117
2585
  }
2118
2586
  /**
2119
2587
  * Run one user→assistant turn through the state machine. Mutates
@@ -2121,9 +2589,62 @@ export async function runChatLoop(opts) {
2121
2589
  * Returns the final assistant content blocks so callers can extract
2122
2590
  * text. Closes over client/model/maxTokens/etc.
2123
2591
  */
2592
+ // v0.3.0 Goal 6 — one structured report on every terminal path, published
2593
+ // to the bus AND appended to the session event log BEFORE the throw (a
2594
+ // throw is invisible to structured consumers; the event is what the UI
2595
+ // host, printers, exporters, and incident capture render). Used by the
2596
+ // recovery `halt`/`fail` arms, the §7.1 sub-agent escalation path in
2597
+ // `NeedTools`, and (G10) the wall-clock timeout stops — including the REPL
2598
+ // deadline-at-prompt path, which is why this lives at run scope rather
2599
+ // than inside `runOneTurn`.
2600
+ const publishRunFailed = async (report) => {
2601
+ const failureMessage = `${report.title}: ${report.detail}`;
2602
+ bus.publish({
2603
+ ...bus.envelope(),
2604
+ kind: "run_failed",
2605
+ class: report.class,
2606
+ message: failureMessage,
2607
+ ...(report.remediation !== undefined ? { remediation: report.remediation } : {}),
2608
+ exitCode: report.exitCode,
2609
+ });
2610
+ await logEvent("run_failed", {
2611
+ class: report.class,
2612
+ message: failureMessage,
2613
+ ...(report.remediation !== undefined ? { remediation: report.remediation } : {}),
2614
+ exitCode: report.exitCode,
2615
+ });
2616
+ };
2617
+ /**
2618
+ * G10 — convert a fired wall-clock limit into the classified terminal
2619
+ * stop: publish + log the `run_failed` report (class `"timeout"`), then
2620
+ * throw the matching `RunFailedError`. Callers invoke this only on the
2621
+ * paths where a timeout IS terminal (any scope in `singleTurn` mode; the
2622
+ * run deadline everywhere).
2623
+ */
2624
+ const throwTimeout = async (timeout) => {
2625
+ const report = buildTimeoutFailureReport(timeout);
2626
+ await publishRunFailed(report);
2627
+ throw new RunFailedError(report);
2628
+ };
2124
2629
  async function runOneTurn(messages) {
2125
2630
  let state = initialState;
2126
2631
  let terminalContent = [];
2632
+ // G02 — aggregate token usage across every MAIN-turn model call this
2633
+ // turn makes (each tool iteration streams once). Handed to the in-loop
2634
+ // evaluator so a judge can weigh cost/verbosity; side-calls (compaction,
2635
+ // the injected judge itself) publish no accumulation here.
2636
+ const turnUsage = {
2637
+ input: 0,
2638
+ output: 0,
2639
+ cacheRead: 0,
2640
+ cacheCreate: 0,
2641
+ };
2642
+ const accrueTurnUsage = (u) => {
2643
+ turnUsage.input += u.input;
2644
+ turnUsage.output += u.output;
2645
+ turnUsage.cacheRead += u.cacheRead ?? 0;
2646
+ turnUsage.cacheCreate += u.cacheCreate ?? 0;
2647
+ };
2127
2648
  let recovery = initialRecoveryState;
2128
2649
  const maxToolIterations = opts.maxToolIterations ?? DEFAULT_MAX_TOOL_ITERATIONS;
2129
2650
  let toolIterations = 0;
@@ -2139,29 +2660,6 @@ export async function runChatLoop(opts) {
2139
2660
  // strongest candidate for the rest of the run (misroute recovery, mirroring
2140
2661
  // the tier router's fast→default escalation latch).
2141
2662
  let escalatePool = false;
2142
- // v0.3.0 Goal 6 — one structured report on every terminal path,
2143
- // published to the bus AND appended to the session event log BEFORE the
2144
- // throw (a throw is invisible to structured consumers; the event is what
2145
- // the UI host, printers, exporters, and incident capture render). Used
2146
- // by the recovery `halt`/`fail` arms below and by the §7.1 sub-agent
2147
- // escalation path in `NeedTools`.
2148
- const publishRunFailed = async (report) => {
2149
- const failureMessage = `${report.title}: ${report.detail}`;
2150
- bus.publish({
2151
- ...bus.envelope(),
2152
- kind: "run_failed",
2153
- class: report.class,
2154
- message: failureMessage,
2155
- ...(report.remediation !== undefined ? { remediation: report.remediation } : {}),
2156
- exitCode: report.exitCode,
2157
- });
2158
- await logEvent("run_failed", {
2159
- class: report.class,
2160
- message: failureMessage,
2161
- ...(report.remediation !== undefined ? { remediation: report.remediation } : {}),
2162
- exitCode: report.exitCode,
2163
- });
2164
- };
2165
2663
  while (state.kind !== "Done") {
2166
2664
  if (turnAbort.signal.aborted) {
2167
2665
  state = transition(state, { kind: "Aborted" });
@@ -2241,7 +2739,7 @@ export async function runChatLoop(opts) {
2241
2739
  // two are mutually exclusive in the spec).
2242
2740
  if (poolRouter !== undefined) {
2243
2741
  const base = poolRouter.route({
2244
- contextTokens: estimateTokens(messages),
2742
+ contextTokens: contextTokenSignal(messages),
2245
2743
  toolsInPlay: (anthropicTools?.length ?? 0) > 0,
2246
2744
  turnIndex: Math.max(0, runContext.turnNumber - 1),
2247
2745
  priorTurnToolUseCount,
@@ -2301,7 +2799,7 @@ export async function runChatLoop(opts) {
2301
2799
  const decision = escalateTier
2302
2800
  ? { tier: "default", reason: "escalated after fast-tier failure" }
2303
2801
  : tierRouter.route({
2304
- contextTokens: estimateTokens(messages),
2802
+ contextTokens: contextTokenSignal(messages),
2305
2803
  toolsInPlay: (anthropicTools?.length ?? 0) > 0,
2306
2804
  // `turnNumber` is 1-based (incremented before the turn
2307
2805
  // runs); the router wants a 0-based index so its
@@ -2360,6 +2858,19 @@ export async function runChatLoop(opts) {
2360
2858
  // `[]` when the seam is absent — the request payload is then
2361
2859
  // byte-identical to a pre-0.3.0 runtime.
2362
2860
  const continuityTail = await buildContinuityTail();
2861
+ // G10 — arm the per-model-call watchdog for exactly the stream's
2862
+ // lifetime: cleared right after each drain below and (throw
2863
+ // paths) at the top of the catch. G01 — every MAIN-turn request
2864
+ // (and only these: compaction/judge side-calls build their own
2865
+ // requests) carries the resolved thinking fields, and the token
2866
+ // ceiling is the thinking-aware `effectiveMaxTokens`.
2867
+ armModelCallTimer();
2868
+ // Item 9 / G79 — cache the settled transcript prefix when the
2869
+ // serving adapter supports explicit caching. A request-local copy;
2870
+ // the persisted `messages` array never carries the marker.
2871
+ const reqMessages = turnAdapter.features.caching === "explicit"
2872
+ ? withMessageCacheBreakpoint(messages)
2873
+ : messages;
2363
2874
  const reqStream = turnAdapter.stream({
2364
2875
  model: reqWireModelId,
2365
2876
  system: [
@@ -2368,9 +2879,13 @@ export async function runChatLoop(opts) {
2368
2879
  text: b.text,
2369
2880
  ...(b.cache_control !== undefined ? { cache_control: b.cache_control } : {}),
2370
2881
  })),
2882
+ // Item 2 / G21 — the volatile recalled-memory block: rebuilt
2883
+ // per-turn in per-turn recall mode, NO cache marker, sits in
2884
+ // the mutable tail so a swap never busts the frozen prefix.
2885
+ ...volatileRecallBlocks.map((b) => ({ type: "text", text: b.text })),
2371
2886
  ...continuityTail.map((b) => ({ type: "text", text: b.text })),
2372
2887
  ],
2373
- messages: messages,
2888
+ messages: reqMessages,
2374
2889
  tools: anthropicTools !== undefined
2375
2890
  ? anthropicTools.map((t) => ({
2376
2891
  name: t.name,
@@ -2378,7 +2893,8 @@ export async function runChatLoop(opts) {
2378
2893
  input_schema: t.input_schema,
2379
2894
  }))
2380
2895
  : undefined,
2381
- maxTokens,
2896
+ maxTokens: effectiveMaxTokens,
2897
+ ...(thinkingRequest !== undefined ? thinkingRequest : {}),
2382
2898
  signal: turnAbort.signal,
2383
2899
  });
2384
2900
  if (opts.streaming) {
@@ -2412,7 +2928,9 @@ export async function runChatLoop(opts) {
2412
2928
  runContext.logger.debug("streaming-tool", { ...e });
2413
2929
  },
2414
2930
  });
2931
+ clearModelCallTimer();
2415
2932
  endTurn();
2933
+ accrueTurnUsage(usage);
2416
2934
  // On `stop_reason: "max_tokens"` the model may have been cut off
2417
2935
  // mid-`tool_use`; the streaming executor only runs a call once its
2418
2936
  // input JSON closes, so a truncated call has no `tool_result`.
@@ -2460,6 +2978,15 @@ export async function runChatLoop(opts) {
2460
2978
  usage,
2461
2979
  durationMs: performance.now() - t0Model,
2462
2980
  });
2981
+ // Item 4 / G28 — record the provider's real input_tokens for the
2982
+ // next pre-turn compaction trigger + routing signal. A response
2983
+ // that reports NO usage (sum 0) means "unknown", not "empty":
2984
+ // keep the last known count (undefined pre-first-call) so both the
2985
+ // trigger and the router fall back to the chars/4 estimate instead
2986
+ // of reading the context as empty and silently disabling compaction.
2987
+ const reportedInputTokens = responseInputTokens(usage);
2988
+ if (reportedInputTokens > 0)
2989
+ lastModelInputTokens = reportedInputTokens;
2463
2990
  // Adaptive model routing — fold this successful turn into the
2464
2991
  // reward scoreboard so the learned policy improves next run.
2465
2992
  if (poolTurn !== undefined) {
@@ -2486,21 +3013,31 @@ export async function runChatLoop(opts) {
2486
3013
  }
2487
3014
  messages.push({ role: "user", content: [...toolResults] });
2488
3015
  await logEvent("user_message", { content: [...toolResults] });
2489
- const warning = maybeBuildLoopWarning();
2490
- if (warning !== null) {
2491
- messages.push(warning);
2492
- await logEvent("user_message", { content: warning.content, synthetic: true });
3016
+ const loopOutcome = evaluateToolLoop();
3017
+ if (loopOutcome.kind === "message") {
3018
+ messages.push(loopOutcome.message);
3019
+ await logEvent("user_message", {
3020
+ content: loopOutcome.message.content,
3021
+ synthetic: true,
3022
+ });
2493
3023
  }
2494
3024
  // Synthesize the two transitions the state machine expects:
2495
3025
  // tools have already executed during the stream so we
2496
3026
  // collapse ModelReturnedToolUse → ToolsExecuted into a
2497
- // single hop back to NeedModel.
3027
+ // single hop back to NeedModel. (G27: on an `abort` loop
3028
+ // escalation the second hop is the Aborted transition — the
3029
+ // NeedTools state accepts it — ending the turn instead.)
2498
3030
  const tsmBlocks = toolUses.map((t) => ({
2499
3031
  id: t.id,
2500
3032
  name: t.name,
2501
3033
  input: t.input,
2502
3034
  }));
2503
3035
  state = transition(state, { kind: "ModelReturnedToolUse", toolUses: tsmBlocks });
3036
+ if (loopOutcome.kind === "abort") {
3037
+ await recordLoopAbort(loopOutcome.detection);
3038
+ state = transition(state, { kind: "Aborted" });
3039
+ break;
3040
+ }
2504
3041
  state = transition(state, { kind: "ToolsExecuted" });
2505
3042
  break;
2506
3043
  }
@@ -2517,7 +3054,9 @@ export async function runChatLoop(opts) {
2517
3054
  }, { ephemeral: true });
2518
3055
  },
2519
3056
  });
3057
+ clearModelCallTimer();
2520
3058
  endTurn();
3059
+ accrueTurnUsage(final.usage);
2521
3060
  // Item 22 — lastServed() is exact: the candidate that actually
2522
3061
  // streamed this response. Cost-tracker prices off this pair.
2523
3062
  const servedCandidate = failoverChain?.lastServed();
@@ -2540,6 +3079,15 @@ export async function runChatLoop(opts) {
2540
3079
  usage: final.usage,
2541
3080
  durationMs: performance.now() - t0Model,
2542
3081
  });
3082
+ // Item 4 / G28 — record the provider's real input_tokens for the
3083
+ // next pre-turn compaction trigger + routing signal. A response that
3084
+ // reports NO usage (sum 0) means "unknown", not "empty": keep the
3085
+ // last known count (undefined pre-first-call) so both the trigger and
3086
+ // the router fall back to the chars/4 estimate instead of reading the
3087
+ // context as empty and silently disabling compaction.
3088
+ const reportedInputTokens = responseInputTokens(final.usage);
3089
+ if (reportedInputTokens > 0)
3090
+ lastModelInputTokens = reportedInputTokens;
2543
3091
  // Adaptive model routing — fold this successful turn into the
2544
3092
  // reward scoreboard so the learned policy improves next run.
2545
3093
  if (poolTurn !== undefined) {
@@ -2608,10 +3156,23 @@ export async function runChatLoop(opts) {
2608
3156
  }));
2609
3157
  for (const tu of tsmBlocks)
2610
3158
  toolUseHistory.push(tu);
3159
+ // Item 7 — the response fully drained (usage known) before these
3160
+ // calls dispatch in `NeedTools`, so the split IS computable here:
3161
+ // split the priceable response cost evenly across its tool_use
3162
+ // blocks, keyed by id for `executeOneToolUse` to stamp. Skipped
3163
+ // (no attribution) when the model isn't on the pricing table.
3164
+ const respCost = responseCostMicros(respProvider, respWireModelId, final.usage);
3165
+ if (respCost !== undefined) {
3166
+ const perTool = Math.round(respCost / toolUses.length);
3167
+ for (const tu of tsmBlocks)
3168
+ toolCostAttribution.set(tu.id, perTool);
3169
+ }
2611
3170
  state = transition(state, { kind: "ModelReturnedToolUse", toolUses: tsmBlocks });
2612
3171
  }
2613
3172
  }
2614
3173
  catch (err) {
3174
+ // G10 — the watchdog must not outlive the call it watched.
3175
+ clearModelCallTimer();
2615
3176
  // Tear down the "thinking" animation before any error/abort output.
2616
3177
  out.spinner.stop();
2617
3178
  if (isAbortError(err)) {
@@ -2692,10 +3253,20 @@ export async function runChatLoop(opts) {
2692
3253
  }
2693
3254
  messages.push({ role: "user", content: toolResults });
2694
3255
  await logEvent("user_message", { content: toolResults });
2695
- const warning = maybeBuildLoopWarning();
2696
- if (warning !== null) {
2697
- messages.push(warning);
2698
- await logEvent("user_message", { content: warning.content, synthetic: true });
3256
+ const loopOutcome = evaluateToolLoop();
3257
+ if (loopOutcome.kind === "message") {
3258
+ messages.push(loopOutcome.message);
3259
+ await logEvent("user_message", {
3260
+ content: loopOutcome.message.content,
3261
+ synthetic: true,
3262
+ });
3263
+ }
3264
+ else if (loopOutcome.kind === "abort") {
3265
+ // G27 escalation "abort" — the warned signature tripped again:
3266
+ // end the TURN, ToolLoopLimit-style (see recordLoopAbort).
3267
+ await recordLoopAbort(loopOutcome.detection);
3268
+ state = transition(state, { kind: "Aborted" });
3269
+ break;
2699
3270
  }
2700
3271
  state = transition(state, { kind: "ToolsExecuted" });
2701
3272
  break;
@@ -2887,7 +3458,131 @@ export async function runChatLoop(opts) {
2887
3458
  // Item 26 — hand this turn's tool_use count to the next turn's tier
2888
3459
  // decision (the prior-tool-density signal).
2889
3460
  priorTurnToolUseCount = thisTurnToolUseCount;
2890
- return { terminalContent };
3461
+ // G10 — the turn wound down through the Aborted transition; if a
3462
+ // wall-clock timer (not a SIGINT) is what aborted it, classify the stop.
3463
+ // The abort tree propagates reasons parent→child, so a run-deadline
3464
+ // reason is readable off the TURN signal too; checking both covers the
3465
+ // window where the deadline fires between turns. Terminal when the
3466
+ // deadline fired (any mode) or in `singleTurn` mode (the turn IS the
3467
+ // run); in REPL mode a turn/model-call timeout already printed its
3468
+ // notice at fire time — record the named error and hand control back to
3469
+ // the prompt, mirroring the first-SIGINT semantics.
3470
+ const timedOut = timeoutAbortReason(turnAbort.signal) ?? timeoutAbortReason(runAbort.signal);
3471
+ if (timedOut !== undefined) {
3472
+ if (timedOut.crewhausTimeout === "run" || opts.singleTurn === true) {
3473
+ await throwTimeout(timedOut);
3474
+ }
3475
+ await logEvent("error", {
3476
+ name: timedOut.crewhausTimeout === "turn" ? "TurnTimeout" : "ModelCallTimeout",
3477
+ message: `turn aborted: the configured ${TIMEOUT_SPEC_KEYS[timedOut.crewhausTimeout]} (${timedOut.limitMs}ms) elapsed`,
3478
+ });
3479
+ }
3480
+ return { terminalContent, usage: turnUsage };
3481
+ }
3482
+ /** Concatenated text of a terminal content-block array (the same
3483
+ * projection the `singleTurn` return value uses). */
3484
+ const terminalText = (blocks) => blocks
3485
+ .filter((b) => b.type === "text")
3486
+ .map((b) => b.text)
3487
+ .join("");
3488
+ /**
3489
+ * G02 — one COMPLETED turn plus its in-loop evaluation gate. Wraps
3490
+ * `runOneTurn` so evaluation fires only at turn completion (the tool
3491
+ * inner-loop lives INSIDE `runOneTurn`, so tool-only intermediate
3492
+ * iterations can never reach the grader by construction), on both the
3493
+ * `singleTurn` and REPL paths. Without `opts.evaluation` this is exactly
3494
+ * `runOneTurn` — zero behaviour change.
3495
+ *
3496
+ * The retry ladder: grade attempt 0 (`retryIndex` 0); a failing verdict
3497
+ * with `onFail: "retry"` appends the grader rationale as a synthetic
3498
+ * corrective user message and re-runs the turn, re-grading each re-run
3499
+ * (`retryIndex` n) up to `maxRetries`. Every re-run streams real model
3500
+ * calls through the normal `NeedModel` path, so its spend is metered by
3501
+ * the always-on budget cost path exactly like any other call. `halt`
3502
+ * publishes + logs the classified `run_failed` (class `"evaluation"`)
3503
+ * and throws; `note` and an exhausted retry cap leave the last attempt
3504
+ * standing. An ABORTED (SIGINT / wall-clock) attempt never completed —
3505
+ * it is returned un-graded.
3506
+ */
3507
+ async function runEvaluatedTurn(messages) {
3508
+ const evaluation = opts.evaluation;
3509
+ let attempt = await runOneTurn(messages);
3510
+ if (evaluation === undefined)
3511
+ return attempt;
3512
+ const maxRetries = Math.max(0, Math.floor(evaluation.maxRetries));
3513
+ for (let retryIndex = 0;; retryIndex += 1) {
3514
+ // A turn the abort tree stopped (SIGINT, turn/model-call/run timer)
3515
+ // did not COMPLETE — grading its partial output would be noise, and
3516
+ // a retry would fight the very signal that stopped it.
3517
+ if (turnAbort.signal.aborted || runAbort.signal.aborted)
3518
+ return attempt;
3519
+ let graded;
3520
+ out.spinner.start("evaluating");
3521
+ try {
3522
+ graded = await evaluation.evaluate({
3523
+ finalText: terminalText(attempt.terminalContent),
3524
+ messages,
3525
+ usage: attempt.usage,
3526
+ });
3527
+ }
3528
+ catch (err) {
3529
+ // Grading INFRASTRUCTURE failure (judge model down, evaluator bug)
3530
+ // is not a verdict. Fail open: record it and let the turn stand —
3531
+ // a flaky judge must not kill an otherwise healthy run.
3532
+ const errObj = err;
3533
+ const name = typeof errObj.name === "string" ? errObj.name : "EvaluationError";
3534
+ const message = typeof errObj.message === "string" ? errObj.message : String(err);
3535
+ runContext.logger.warn("evaluation: grader threw — turn stands un-graded", {
3536
+ name,
3537
+ message,
3538
+ });
3539
+ await logEvent("error", { name, message: `evaluation grader failed: ${message}` });
3540
+ return attempt;
3541
+ }
3542
+ finally {
3543
+ out.spinner.stop();
3544
+ }
3545
+ // A rogue evaluator returning NaN/±Infinity must not poison the
3546
+ // trace surface; treat non-finite as 0 (an unambiguous fail).
3547
+ const score = Number.isFinite(graded.score) ? graded.score : 0;
3548
+ const rationale = graded.rationale;
3549
+ const verdict = score >= evaluation.threshold ? "pass" : "fail";
3550
+ bus.publish({
3551
+ ...bus.envelope(),
3552
+ kind: "eval_graded",
3553
+ score,
3554
+ threshold: evaluation.threshold,
3555
+ verdict,
3556
+ graderType: evaluation.graderType,
3557
+ retryIndex,
3558
+ });
3559
+ if (verdict === "pass" || evaluation.onFail === "note")
3560
+ return attempt;
3561
+ const rationaleNote = rationale !== undefined && rationale.trim().length > 0 ? ` — ${rationale.trim()}` : "";
3562
+ if (evaluation.onFail === "halt") {
3563
+ const detail = `the ${evaluation.graderType} grader scored the final answer ${score.toFixed(2)}, below the required ${evaluation.threshold} threshold${rationaleNote}`;
3564
+ const report = {
3565
+ class: "evaluation",
3566
+ title: "in-loop evaluation gate failed",
3567
+ detail,
3568
+ remediation: "improve the agent (instructions/model), lower evaluation.threshold, or soften evaluation.on_fail to retry/note",
3569
+ exitCode: EXIT_CODES.evaluation,
3570
+ };
3571
+ await publishRunFailed(report);
3572
+ throw new RunFailedError(report);
3573
+ }
3574
+ // onFail: "retry" — bounded by the resolved cap; when spent, the last
3575
+ // attempt stands (the failing eval_graded trail tells the story).
3576
+ if (retryIndex >= maxRetries)
3577
+ return attempt;
3578
+ const feedback = rationale !== undefined && rationale.trim().length > 0
3579
+ ? ` Grader feedback: ${rationale.trim()}`
3580
+ : "";
3581
+ const correction = `[evaluation failed: scored ${score.toFixed(2)}, threshold ${evaluation.threshold}]${feedback}\nPlease revise your previous answer to address the feedback, then give the corrected answer in full.`;
3582
+ messages.push({ role: "user", content: correction });
3583
+ await logEvent("user_message", { content: correction, synthetic: true });
3584
+ attempt = await runOneTurn(messages);
3585
+ }
2891
3586
  }
2892
3587
  // Single-shot path used by the workflow target and (Section 12) the
2893
3588
  // channel-bot session router. Runs one user→assistant turn (with the tool
@@ -2938,6 +3633,7 @@ export async function runChatLoop(opts) {
2938
3633
  logger: runContext.logger,
2939
3634
  onEvict: externalizeEvicted,
2940
3635
  getLedgerText: ledgerAnchorText,
3636
+ ...compactionExtras(),
2941
3637
  }, async (info) => {
2942
3638
  await logEvent("compaction", info);
2943
3639
  bus.publish({
@@ -2956,19 +3652,29 @@ export async function runChatLoop(opts) {
2956
3652
  await fireHook("pre-compact", { ...info, phase: "pre-turn" });
2957
3653
  await fireHook("post-compact", { ...info, phase: "pre-turn" });
2958
3654
  });
2959
- const { terminalContent } = await runOneTurn(messages);
3655
+ // Item 2 / G21 — refresh the volatile recalled block against this turn's
3656
+ // latest user message (no-op unless per-turn recall is enabled + due).
3657
+ await maybePerTurnRecall(messages);
3658
+ // G10 — the single turn IS the run: arm the per-turn ceiling around
3659
+ // it (the deadline timer is already live from boot). Fired timers
3660
+ // surface as a classified RunFailedError out of runOneTurn; the
3661
+ // finally below tears every timer down on all paths. (G02 — the
3662
+ // evaluated wrapper re-runs the turn on a failing verdict, all
3663
+ // attempts inside the same armed window: a retried turn is still ONE
3664
+ // turn against `turn_timeout_ms`.)
3665
+ armTurnTimer();
3666
+ const { terminalContent } = await runEvaluatedTurn(messages);
3667
+ clearTurnTimer();
2960
3668
  bus.publish({
2961
3669
  ...bus.envelope(),
2962
3670
  kind: "turn_end",
2963
3671
  turn: runContext.turnNumber,
2964
3672
  durationMs: performance.now() - t0SingleTurn,
2965
3673
  });
2966
- return terminalContent
2967
- .filter((b) => b.type === "text")
2968
- .map((b) => b.text)
2969
- .join("");
3674
+ return terminalText(terminalContent);
2970
3675
  }
2971
3676
  finally {
3677
+ clearAllTimers();
2972
3678
  out.spinner.stop();
2973
3679
  await fireHook("stop", {
2974
3680
  sessionId,
@@ -3018,6 +3724,18 @@ export async function runChatLoop(opts) {
3018
3724
  const closedSignal = new Promise((resolve) => {
3019
3725
  rl.once("close", () => resolve(STDIN_CLOSED));
3020
3726
  });
3727
+ // G10 — a fired run deadline must also interrupt an IDLE `rl.question`
3728
+ // wait (the loop-top abort check only runs once input arrives), so each
3729
+ // prompt races this alongside the stdin-close sentinel.
3730
+ const RUN_ABORTED = Symbol("run-aborted");
3731
+ const runAbortedSignal = new Promise((resolve) => {
3732
+ if (runAbort.signal.aborted) {
3733
+ resolve(RUN_ABORTED);
3734
+ }
3735
+ else {
3736
+ runAbort.signal.addEventListener("abort", () => resolve(RUN_ABORTED), { once: true });
3737
+ }
3738
+ });
3021
3739
  // Wire the permission-ask prompter once the readline interface exists.
3022
3740
  // Treats a closed stdin as "deny" so a piped non-interactive input does
3023
3741
  // not stall on the approval prompt.
@@ -3085,8 +3803,8 @@ export async function runChatLoop(opts) {
3085
3803
  sigintPresses = 0;
3086
3804
  let userInput;
3087
3805
  try {
3088
- const result = await Promise.race([rl.question("\nyou> "), closedSignal]);
3089
- if (result === STDIN_CLOSED)
3806
+ const result = await Promise.race([rl.question("\nyou> "), closedSignal, runAbortedSignal]);
3807
+ if (result === STDIN_CLOSED || result === RUN_ABORTED)
3090
3808
  break;
3091
3809
  userInput = result.trim();
3092
3810
  }
@@ -3147,7 +3865,7 @@ export async function runChatLoop(opts) {
3147
3865
  turn: runContext.turnNumber,
3148
3866
  messages: messages.length,
3149
3867
  });
3150
- // Pre-turn budget check: snip first (free), then autocompact if still over.
3868
+ // Pre-turn budget check: (curate) → snip → autocompact if still over.
3151
3869
  messages = await maybeCompact({
3152
3870
  messages,
3153
3871
  adapter: compactionAdapter,
@@ -3159,6 +3877,7 @@ export async function runChatLoop(opts) {
3159
3877
  logger: runContext.logger,
3160
3878
  onEvict: externalizeEvicted,
3161
3879
  getLedgerText: ledgerAnchorText,
3880
+ ...compactionExtras(),
3162
3881
  }, async (info) => {
3163
3882
  await logEvent("compaction", info);
3164
3883
  bus.publish({
@@ -3172,8 +3891,18 @@ export async function runChatLoop(opts) {
3172
3891
  await fireHook("pre-compact", { ...info, phase: "pre-turn" });
3173
3892
  await fireHook("post-compact", { ...info, phase: "pre-turn" });
3174
3893
  });
3894
+ // Item 2 / G21 — refresh the volatile recalled block against this turn's
3895
+ // latest user message (no-op unless per-turn recall is enabled + due).
3896
+ await maybePerTurnRecall(messages);
3897
+ // G10 — per-turn wall-clock ceiling: armed for exactly the
3898
+ // `runOneTurn` window, torn down on every exit (finally). A fired
3899
+ // turn/model-call timer aborts the turn and (REPL posture) control
3900
+ // returns to the prompt below — mirroring the first-SIGINT semantics;
3901
+ // a fired run deadline makes `runOneTurn` throw the classified
3902
+ // RunFailedError, which the catch rethrows.
3903
+ armTurnTimer();
3175
3904
  try {
3176
- await runOneTurn(messages);
3905
+ await runEvaluatedTurn(messages);
3177
3906
  }
3178
3907
  catch (err) {
3179
3908
  // Defensive: tear down any animation a thrown turn left spinning.
@@ -3186,6 +3915,9 @@ export async function runChatLoop(opts) {
3186
3915
  throw err;
3187
3916
  }
3188
3917
  }
3918
+ finally {
3919
+ clearTurnTimer();
3920
+ }
3189
3921
  bus.publish({
3190
3922
  ...bus.envelope(),
3191
3923
  kind: "turn_end",
@@ -3196,8 +3928,20 @@ export async function runChatLoop(opts) {
3196
3928
  turn: runContext.turnNumber,
3197
3929
  });
3198
3930
  }
3931
+ // G10 — the loop exited on an aborted run root: when the RUN DEADLINE
3932
+ // (not a SIGINT/EOF) is what aborted it, the stop is terminal and
3933
+ // classified. Published here — still inside the try, BEFORE the finally
3934
+ // tears the bus subscribers down — then thrown so `crewhaus run`/bundle
3935
+ // wrappers render the report and exit with EXIT_CODES.timeout. (A
3936
+ // deadline that fired MID-turn already threw from inside runOneTurn and
3937
+ // never reaches this check.)
3938
+ const runTimeout = timeoutAbortReason(runAbort.signal);
3939
+ if (runTimeout !== undefined) {
3940
+ await throwTimeout(runTimeout);
3941
+ }
3199
3942
  }
3200
3943
  finally {
3944
+ clearAllTimers();
3201
3945
  out.spinner.stop();
3202
3946
  await fireHook("stop", {
3203
3947
  sessionId,
@@ -3250,6 +3994,272 @@ function isAbortError(err) {
3250
3994
  const name = err.name;
3251
3995
  return typeof name === "string" && (name === "AbortError" || name === "APIUserAbortError");
3252
3996
  }
3997
+ // ---------------------------------------------------------------------------
3998
+ // Loop contract 0.4 (Batch E) — shared helpers for active-context curation
3999
+ // (Item 1 / G19), per-turn recall (Item 2 / G21) and message-level cache
4000
+ // breakpoints (Item 9 / G79).
4001
+ // ---------------------------------------------------------------------------
4002
+ /** Item 4 / G28 — the provider's real INPUT token count for one response:
4003
+ * fresh input + cache-read + cache-create (the whole prompt the provider
4004
+ * counted), the accurate context-size signal chars/4 approximates. */
4005
+ function responseInputTokens(u) {
4006
+ return u.input + (u.cacheRead ?? 0) + (u.cacheCreate ?? 0);
4007
+ }
4008
+ /**
4009
+ * The latest USER *text* message — the relevance query for the curator
4010
+ * (Item 1) and the per-turn recall refresh (Item 2). Tool-result user
4011
+ * messages carry no human words, so they're skipped: the query is what the
4012
+ * person actually said, not a tool payload. Returns `undefined` when no
4013
+ * text-bearing user message exists (a bare tool-result tail).
4014
+ */
4015
+ function latestUserText(messages) {
4016
+ for (let i = messages.length - 1; i >= 0; i--) {
4017
+ const m = messages[i];
4018
+ if (m === undefined || m.role !== "user")
4019
+ continue;
4020
+ if (typeof m.content === "string") {
4021
+ if (m.content.length > 0)
4022
+ return m.content;
4023
+ continue;
4024
+ }
4025
+ const text = m.content
4026
+ .filter((b) => b.type === "text")
4027
+ .map((b) => b.text)
4028
+ .join("\n");
4029
+ if (text.length > 0)
4030
+ return text;
4031
+ }
4032
+ return undefined;
4033
+ }
4034
+ /**
4035
+ * Item 1 / G19 — a message is CURATABLE (safe for the curator to drop) only
4036
+ * when it is pure conversational text: no `tool_use` / `tool_result` blocks,
4037
+ * whose pairing the Anthropic API enforces (a dropped half orphans the other
4038
+ * and 400s the request). Removing a pure-text message can never orphan a pair
4039
+ * — consecutive same-role messages are merged server-side, exactly the
4040
+ * tolerance the snip marker path already relies on.
4041
+ */
4042
+ function isCuratableMessage(m) {
4043
+ const c = m.content;
4044
+ if (typeof c === "string")
4045
+ return true;
4046
+ for (const b of c) {
4047
+ if (b.type === "tool_use" || b.type === "tool_result")
4048
+ return false;
4049
+ }
4050
+ return true;
4051
+ }
4052
+ /** Item 1 / G19 — flatten a message's text for curator similarity + the
4053
+ * `bytesSaved` accounting. Non-text blocks contribute nothing (they never
4054
+ * reach the curator — only pure-text messages are curatable). */
4055
+ function curatorItemText(m) {
4056
+ const c = m.content;
4057
+ if (typeof c === "string")
4058
+ return c;
4059
+ return c
4060
+ .filter((b) => b.type === "text")
4061
+ .map((b) => b.text)
4062
+ .join("\n");
4063
+ }
4064
+ const LEXICAL_TOKEN_RE = /[a-z0-9]+/gi;
4065
+ /** Item 1 / G19 — token set for the BM25-family lexical fallback. */
4066
+ function lexicalTokens(text) {
4067
+ const out = new Set();
4068
+ const matches = text.toLowerCase().match(LEXICAL_TOKEN_RE);
4069
+ if (matches !== null)
4070
+ for (const t of matches)
4071
+ out.add(t);
4072
+ return out;
4073
+ }
4074
+ /** Jaccard overlap of two token sets (the lexical similarity used by the
4075
+ * no-embedder curation path). Two empty sets are identical (1). */
4076
+ function jaccard(a, b) {
4077
+ if (a.size === 0 && b.size === 0)
4078
+ return 1;
4079
+ if (a.size === 0 || b.size === 0)
4080
+ return 0;
4081
+ const [small, large] = a.size <= b.size ? [a, b] : [b, a];
4082
+ let inter = 0;
4083
+ for (const t of small)
4084
+ if (large.has(t))
4085
+ inter++;
4086
+ const union = a.size + b.size - inter;
4087
+ return union === 0 ? 0 : inter / union;
4088
+ }
4089
+ /**
4090
+ * Item 1 / G19 — order-preserving lexical dedupe, the BM25-family fallback
4091
+ * when no embedder resolves (a vector store is unavailable). Mirrors the
4092
+ * curator's cosine `dedupeBySimilarity` structure but over token-set Jaccard:
4093
+ * an item is dropped when a PRIOR kept item's Jaccard >= threshold, so the
4094
+ * first occurrence (the head of the conversation, which carries goal-setting
4095
+ * context) always wins.
4096
+ */
4097
+ function lexicalDedupe(texts, threshold) {
4098
+ const tokenSets = texts.map(lexicalTokens);
4099
+ const kept = [];
4100
+ const dropped = [];
4101
+ for (let i = 0; i < texts.length; i++) {
4102
+ let isDuplicate = false;
4103
+ const ti = tokenSets[i];
4104
+ if (ti !== undefined) {
4105
+ for (const k of kept) {
4106
+ const tk = tokenSets[k];
4107
+ if (tk !== undefined && jaccard(ti, tk) >= threshold) {
4108
+ isDuplicate = true;
4109
+ break;
4110
+ }
4111
+ }
4112
+ }
4113
+ (isDuplicate ? dropped : kept).push(i);
4114
+ }
4115
+ return { kept, dropped };
4116
+ }
4117
+ /**
4118
+ * Item 1 / G19 — the active-context curation pass. Runs `curate()` (cosine,
4119
+ * when an embedder is injected) or the lexical fallback over the CURATABLE
4120
+ * middle messages (pure-text, outside the snip-protected head/tail), then
4121
+ * REBUILDS the transcript keeping survivors in their original order. The
4122
+ * curator's relevance ranking is used only to SELECT which messages survive a
4123
+ * `relevanceTopK` trim — never to reorder the conversation, which would
4124
+ * scramble role alternation and tool pairing. Returns `null` when nothing was
4125
+ * eligible or nothing changed, so the caller skips the trace event. Best-
4126
+ * effort at the call site: an embedder throw propagates and the caller
4127
+ * degrades to the plain snip→autocompact ladder.
4128
+ */
4129
+ async function curateActiveContext(messages, snipKeepHead, snipKeepTail, cfg) {
4130
+ const firstCuratable = Math.max(0, snipKeepHead);
4131
+ const lastCuratable = messages.length - Math.max(0, snipKeepTail);
4132
+ const curatableIdx = [];
4133
+ for (let i = firstCuratable; i < lastCuratable; i++) {
4134
+ const m = messages[i];
4135
+ if (m !== undefined && isCuratableMessage(m))
4136
+ curatableIdx.push(i);
4137
+ }
4138
+ // Need at least two comparable items for a dedupe/relevance decision.
4139
+ if (curatableIdx.length < 2)
4140
+ return null;
4141
+ const texts = curatableIdx.map((i) => curatorItemText(messages[i]));
4142
+ const threshold = cfg.dedupeThreshold ?? DEFAULT_DEDUPE_THRESHOLD;
4143
+ const query = latestUserText(messages);
4144
+ const embedded = cfg.embedder !== undefined;
4145
+ // `keepLocal` — indices INTO `curatableIdx`/`texts` that survive, ascending
4146
+ // (transcript order).
4147
+ let keepLocal;
4148
+ if (embedded) {
4149
+ const items = texts.map((t) => ({ text: t }));
4150
+ const result = await curateItems(items, {
4151
+ dedupeThreshold: threshold,
4152
+ embedder: cfg.embedder,
4153
+ // A query only matters for the topK trim — the relevance re-order is
4154
+ // undone by the re-sort below. Skip it (and its embedder call) unless a
4155
+ // topK cap is actually set.
4156
+ ...(cfg.relevanceTopK !== undefined && query !== undefined
4157
+ ? { query, relevanceTopK: cfg.relevanceTopK }
4158
+ : {}),
4159
+ });
4160
+ keepLocal = [...result.originalIndices].sort((a, b) => a - b);
4161
+ }
4162
+ else {
4163
+ const { kept } = lexicalDedupe(texts, threshold);
4164
+ let survivors = kept;
4165
+ if (cfg.relevanceTopK !== undefined &&
4166
+ query !== undefined &&
4167
+ survivors.length > cfg.relevanceTopK) {
4168
+ const q = lexicalTokens(query);
4169
+ survivors = [...survivors]
4170
+ .sort((a, b) => {
4171
+ const sa = jaccard(q, lexicalTokens(texts[a] ?? ""));
4172
+ const sb = jaccard(q, lexicalTokens(texts[b] ?? ""));
4173
+ if (sa !== sb)
4174
+ return sb - sa;
4175
+ return a - b;
4176
+ })
4177
+ .slice(0, cfg.relevanceTopK)
4178
+ .sort((a, b) => a - b);
4179
+ }
4180
+ keepLocal = survivors;
4181
+ }
4182
+ const before = curatableIdx.length;
4183
+ const after = keepLocal.length;
4184
+ if (after >= before)
4185
+ return null; // dedupe + topK dropped nothing
4186
+ const textByGlobal = new Map();
4187
+ curatableIdx.forEach((g, l) => textByGlobal.set(g, texts[l]));
4188
+ const keepGlobal = new Set(keepLocal.map((l) => curatableIdx[l]));
4189
+ const curatableSet = new Set(curatableIdx);
4190
+ const out = [];
4191
+ let bytesSaved = 0;
4192
+ for (let i = 0; i < messages.length; i++) {
4193
+ if (curatableSet.has(i) && !keepGlobal.has(i)) {
4194
+ bytesSaved += Buffer.byteLength(textByGlobal.get(i) ?? "", "utf8");
4195
+ continue; // curated away
4196
+ }
4197
+ out.push(messages[i]);
4198
+ }
4199
+ return { messages: out, before, after, dropped: before - after, bytesSaved, embedded };
4200
+ }
4201
+ /**
4202
+ * Item 2 / G21 — render the recalled-memory system block body with the SAME
4203
+ * two defenses the session-start recall uses (#53): neutralize any
4204
+ * `</recalled_memory>` breakout delimiter inside a recalled line, and run the
4205
+ * assembled block through `classifyBoundary` with origin `"user"` (recalled
4206
+ * lines may embed content shaped by untrusted tool output in an earlier
4207
+ * session). Returns `undefined` when there is nothing to recall.
4208
+ */
4209
+ async function renderRecalledMemory(lines) {
4210
+ if (lines.length === 0)
4211
+ return undefined;
4212
+ const body = lines.map((l) => `- ${escapeBoundaryDelimiter(l, "recalled_memory")}`).join("\n");
4213
+ const text = `<recalled_memory>\nRelevant facts remembered from earlier sessions:\n${body}\n</recalled_memory>`;
4214
+ await classifyBoundary(text, { origin: "user" }).catch(() => undefined);
4215
+ return text;
4216
+ }
4217
+ /**
4218
+ * Item 9 / G79 — stamp ONE message-level cache breakpoint so the settled
4219
+ * transcript prefix is a cache read on the next call instead of full-price
4220
+ * input every turn/tool-iteration. Marks the last message that carries
4221
+ * ARRAY content (an assistant turn or a tool_result) — never a bare string,
4222
+ * so the freshest user input stays OUTSIDE the cached prefix and a new turn
4223
+ * EXTENDS the cache rather than rebuilding it (Anthropic's recommended
4224
+ * incremental pattern), and string-content messages round-trip untouched.
4225
+ * A request-local copy: the persisted `messages` array never carries a
4226
+ * marker. One breakpoint here plus the single frozen system-prefix marker is
4227
+ * two — well under Anthropic's four. Caller gates on
4228
+ * `adapter.features.caching === "explicit"`.
4229
+ */
4230
+ function withMessageCacheBreakpoint(messages) {
4231
+ let target = -1;
4232
+ for (let i = messages.length - 1; i >= 0; i--) {
4233
+ const c = messages[i]?.content;
4234
+ if (Array.isArray(c) && c.length > 0) {
4235
+ target = i;
4236
+ break;
4237
+ }
4238
+ }
4239
+ if (target === -1)
4240
+ return [...messages];
4241
+ return messages.map((m, i) => (i === target ? stampCacheControlTail(m) : m));
4242
+ }
4243
+ /** Add `cache_control: { type: "ephemeral" }` to the last cache-eligible block
4244
+ * of an ARRAY-content message. Walks back past `thinking`/`redacted_thinking`
4245
+ * blocks (which reject the marker). */
4246
+ function stampCacheControlTail(m) {
4247
+ const content = m.content;
4248
+ if (typeof content === "string" || content.length === 0)
4249
+ return m;
4250
+ let idx = -1;
4251
+ for (let i = content.length - 1; i >= 0; i--) {
4252
+ const t = content[i]?.type;
4253
+ if (t !== "thinking" && t !== "redacted_thinking") {
4254
+ idx = i;
4255
+ break;
4256
+ }
4257
+ }
4258
+ if (idx === -1)
4259
+ return m;
4260
+ const next = content.map((b, i) => i === idx ? { ...b, cache_control: { type: "ephemeral" } } : b);
4261
+ return { ...m, content: next };
4262
+ }
3253
4263
  /** The messages `snip` dropped: input entries absent (by reference — snip
3254
4264
  * copies references) from the output. The inserted marker is a fresh
3255
4265
  * object, so it never shows up as "kept". */
@@ -3263,36 +4273,95 @@ function summaryTextOf(tuple) {
3263
4273
  return summary !== undefined && typeof summary.content === "string" ? summary.content : undefined;
3264
4274
  }
3265
4275
  /**
3266
- * Pre-turn compaction ladder: estimate → snip → re-estimate → autocompact.
3267
- * Returns the (possibly replaced) messages array. Pure with respect to
3268
- * the input array; callers reassign. The optional `onCompaction` callback
3269
- * fires once per applied step so the runtime can append a `compaction`
3270
- * event to the session log without duplicating the cost-estimation logic.
4276
+ * Pre-turn compaction ladder: (curate) → estimate → snip → re-estimate →
4277
+ * autocompact. Returns the (possibly replaced) messages array. Pure with
4278
+ * respect to the input array; callers reassign. The optional `onCompaction`
4279
+ * callback fires once per applied step so the runtime can append a
4280
+ * `compaction` event to the session log without duplicating the
4281
+ * cost-estimation logic.
4282
+ *
4283
+ * Item 1 / G19 — when `args.curate` is set, the active-context curation pass
4284
+ * runs FIRST (only once the context is already approaching the limit): it
4285
+ * dedupes/relevance-trims the transcript, and when that alone frees enough
4286
+ * headroom the snip→autocompact ladder is skipped entirely (the whole point —
4287
+ * cheap dedupe before an expensive summarizer call). Item 4 / G28 — the
4288
+ * trigger + every re-check use the provider's real `input_tokens`
4289
+ * (`args.realInputTokens`) as the base, calibrating the chars/4 heuristic for
4290
+ * the post-stage deltas; absent (pre-first-call) → the pure heuristic.
3271
4291
  */
3272
4292
  async function maybeCompact(args, onCompaction) {
3273
- const { messages, adapter, model, contextLimit, compactionThreshold, snipKeepHead, snipKeepTail, logger, onEvict, getLedgerText, } = args;
3274
- const initialBudget = new TokenBudget(contextLimit);
3275
- initialBudget.add(estimateTokens(messages), 0);
3276
- if (!initialBudget.isApproachingLimit(compactionThreshold)) {
4293
+ const { messages, adapter, model, contextLimit, compactionThreshold, snipKeepHead, snipKeepTail, logger, onEvict, getLedgerText, realInputTokens, curate: curateCfg, onCurate, } = args;
4294
+ // Item 4 / G28 — real-token calibration. The initial array's real size is
4295
+ // `realInputTokens` (the provider's count); every later stage subtracts the
4296
+ // ESTIMATED tokens it freed. Pre-first-call (`realInputTokens` undefined) →
4297
+ // the pure chars/4 estimate, byte-identical to the pre-0.4 trigger.
4298
+ const baseEstimate = estimateTokens(messages);
4299
+ const effectiveTokens = (msgs) => {
4300
+ const est = estimateTokens(msgs);
4301
+ if (realInputTokens === undefined)
4302
+ return est;
4303
+ return Math.max(0, realInputTokens - (baseEstimate - est));
4304
+ };
4305
+ const approaching = (msgs) => {
4306
+ const budget = new TokenBudget(contextLimit);
4307
+ budget.add(effectiveTokens(msgs), 0);
4308
+ return budget.isApproachingLimit(compactionThreshold);
4309
+ };
4310
+ if (!approaching(messages)) {
3277
4311
  return messages;
3278
4312
  }
3279
- const snipped = snip(messages, snipKeepHead, snipKeepTail);
4313
+ // Item 1 / G19 — active-context curation pre-pass. Dedupe + relevance-trim
4314
+ // the transcript before the snip→autocompact ladder; if it frees enough,
4315
+ // the ladder (and the summarizer model call) is skipped. Best-effort: an
4316
+ // embedder/curator failure degrades to the plain ladder below.
4317
+ let working = messages;
4318
+ if (curateCfg !== undefined) {
4319
+ try {
4320
+ const outcome = await curateActiveContext(working, snipKeepHead, snipKeepTail, curateCfg);
4321
+ if (outcome !== null) {
4322
+ working = outcome.messages;
4323
+ logger.info("active-context curation applied", {
4324
+ before: outcome.before,
4325
+ after: outcome.after,
4326
+ dropped: outcome.dropped,
4327
+ bytesSaved: outcome.bytesSaved,
4328
+ embedded: outcome.embedded,
4329
+ });
4330
+ if (onCurate !== undefined) {
4331
+ await onCurate({
4332
+ before: outcome.before,
4333
+ after: outcome.after,
4334
+ dropped: outcome.dropped,
4335
+ bytesSaved: outcome.bytesSaved,
4336
+ embedded: outcome.embedded,
4337
+ });
4338
+ }
4339
+ if (!approaching(working)) {
4340
+ return working; // curation alone freed enough — no snip/autocompact
4341
+ }
4342
+ }
4343
+ }
4344
+ catch (err) {
4345
+ logger.warn("active-context curation failed; falling back to snip/autocompact", {
4346
+ error: err.message,
4347
+ });
4348
+ }
4349
+ }
4350
+ const snipped = snip(working, snipKeepHead, snipKeepTail);
3280
4351
  // §2.3 — externalize what snip is about to drop BEFORE the drop commits.
3281
4352
  if (onEvict !== undefined) {
3282
- const evicted = snippedAway(messages, snipped);
4353
+ const evicted = snippedAway(working, snipped);
3283
4354
  if (evicted.length > 0)
3284
4355
  await onEvict(evicted);
3285
4356
  }
3286
- logger.info("snip applied", { before: messages.length, after: snipped.length });
4357
+ logger.info("snip applied", { before: working.length, after: snipped.length });
3287
4358
  if (onCompaction !== undefined) {
3288
- await onCompaction({ kind: "snip", before: messages.length, after: snipped.length });
4359
+ await onCompaction({ kind: "snip", before: working.length, after: snipped.length });
3289
4360
  }
3290
- const postSnipBudget = new TokenBudget(contextLimit);
3291
- postSnipBudget.add(estimateTokens(snipped), 0);
3292
- if (!postSnipBudget.isApproachingLimit(compactionThreshold)) {
4361
+ if (!approaching(snipped)) {
3293
4362
  return snipped;
3294
4363
  }
3295
- logger.info("autocompact triggered", { tokensAfterSnip: postSnipBudget.used });
4364
+ logger.info("autocompact triggered", { tokensAfterSnip: effectiveTokens(snipped) });
3296
4365
  // §2.3 — autocompact replaces the ENTIRE history; externalize all of it
3297
4366
  // before the summarizer model call so the records survive even a
3298
4367
  // summarizer failure. The ledger anchor is read afterwards so this