@crewhaus/runtime-core 0.3.2 → 0.4.2

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,24 +1,27 @@
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";
11
13
  import { ConfigError, EXIT_CODES, RunFailedError, RuntimeError, isRunFailedError, } from "@crewhaus/errors";
12
- import { openEventLog } from "@crewhaus/event-log";
14
+ import { DEFAULT_ROOT_DIR, openEventLog } from "@crewhaus/event-log";
13
15
  import { aggregateDecisions, runHooks } from "@crewhaus/hooks-engine";
14
16
  import { createFailoverChain, createPolicyRouter, createTierRouter, parseModelString, resolveModel, } from "@crewhaus/model-router";
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, evictExpiredApprovals, 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,12 +32,13 @@ 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";
39
+ import { FEEDBACK_EVENT_KIND, runExitRating } from "./exit-rating";
36
40
  import { attachIncidentCollector } from "./incident-collector";
37
- import { attachAdvisorPersistence, attachDefaultSubscribers, attachMcpStatsPersistence, } from "./observability";
41
+ import { attachAdvisorPersistence, attachDefaultSubscribers, attachMcpStatsPersistence, attachWatchmeCapture, } from "./observability";
38
42
  import { loadProjectMemory } from "./project-memory";
39
43
  import { createCliOutput, isSpinnerEnabled } from "./spinner";
40
44
  /**
@@ -355,11 +359,32 @@ export async function mapWithConcurrency(items, limit, fn) {
355
359
  // moved into `@crewhaus/adapter-anthropic`. Re-exported here so legacy
356
360
  // importers (eval-judge fallback, downstream tests) keep compiling.
357
361
  export { CLAUDE_CODE_HEADERS, CLAUDE_CODE_SYSTEM_PREFIX, OAUTH_BETAS, createAnthropicClient, resolveAuth, } from "@crewhaus/adapter-anthropic";
362
+ // G12 — the platform-neutral loop core lives in `@crewhaus/worker-runtime`
363
+ // (imports no `node:*`); runtime-core CONSUMES it, re-exports its contract as
364
+ // the single source of truth, and supplies the NODE `WorkerPlatform` impl
365
+ // (`./worker-platform`). `runChatLoop`'s own node-coupled services
366
+ // (event-log, session-store, compaction, recovery, audit sinks) wrap this
367
+ // shared core; the three cf-worker emitters call `runWorkerLoop` directly
368
+ // with a stateless platform. These re-exports are purely additive — every
369
+ // existing `runChatLoop` / `RunChatLoopOptions` consumer is unchanged.
370
+ export { createInMemoryKV, createNodeWorkerPlatform } from "./worker-platform";
371
+ export { createEdgeAnthropicAdapter, classifyEdgeTool, EDGE_SAFE_TOOLS, HOST_ONLY_TOOLS, isEdgeSafeTool, partitionEdgeTools, runWorkerLoop, } from "@crewhaus/worker-runtime";
358
372
  // Ops item 36 — boot-time self-heal janitor for daemon shapes. Lives in its
359
373
  // own module (`./janitor`) but is re-exported here because emitted bundles
360
374
  // only import the package root.
361
375
  export { createJanitor } from "./janitor";
362
376
  export { JANITOR_BUILTIN_STEPS } from "./janitor";
377
+ // Loop contract 0.4 (Batch C, item 4) — agent identity generation. Lives in
378
+ // its own module (`./identity`) but is re-exported here because emitted
379
+ // bundles and the CLI only import the package root. The CLI calls
380
+ // `loadOrCreateAgentIdentity()` at boot and threads the resulting `agentId`
381
+ // into `RunChatLoopOptions.agentId` (and onto any bus it constructs itself).
382
+ export { AGENT_IDENTITY_SCHEMA_VERSION, DEFAULT_IDENTITY_DIR, IDENTITY_FILENAME, agentFingerprint, loadOrCreateAgentIdentity, } from "./identity";
383
+ // Loop contract 0.4 (Batch C, G11) — the pending-approval persistence seam is
384
+ // owned by `@crewhaus/session-store`; re-exported here so the CLI/codegen can
385
+ // build the store + input hash it passes as `RunChatLoopOptions.approvals`
386
+ // without depending on session-store directly.
387
+ export { createPendingApprovalStore, evictExpiredApprovals, generateApprovalId, hashApprovalInput, } from "@crewhaus/session-store";
363
388
  // Ops item 31 — alert watchdog seams re-exported so the CLI/codegen can build
364
389
  // the durable + off-box alert sink (audit append + settings.json alert hook /
365
390
  // webhook) it passes as `RunChatLoopOptions.alertSink`.
@@ -371,6 +396,10 @@ export { DEFAULT_SLO_WINDOW_MS, MIN_SLO_SAMPLES, SloWindow, attachSloMonitor, de
371
396
  // Ops item 32 — incident collector seams re-exported so the CLI can share the
372
397
  // raw-capture shape + trigger classifier with `incident collect`.
373
398
  export { attachIncidentCollector, classifyIncidentTrigger, } from "./incident-collector";
399
+ // Item 1 — the exit rating prompt now lives in the runtime (so a COMPILED
400
+ // bundle gets it too, not just `crewhaus run`). Re-exported so the CLI can
401
+ // document the same opt-out env and share the record shape.
402
+ export { EXIT_RATING_PROMPT, EXIT_RATING_TIMEOUT_MS, NO_EXIT_RATING_ENV, buildExitRatingRecord, parseExitRatingKey, runExitRating, shouldPromptExitRating, } from "./exit-rating";
374
403
  /**
375
404
  * Reconcile a message history by dropping "orphan" `tool_use` blocks — a
376
405
  * `tool_use` with no answering `tool_result` anywhere later in the
@@ -593,7 +622,75 @@ function poolFingerprint(pool) {
593
622
  hash = ((hash << 5) + hash + canonical.charCodeAt(i)) >>> 0;
594
623
  return `pool-${hash.toString(36)}`;
595
624
  }
625
+ /** Read the branded timeout reason off an aborted signal, or undefined when
626
+ * the signal is not aborted / was aborted for another cause (SIGINT, EOF). */
627
+ export function timeoutAbortReason(signal) {
628
+ if (!signal.aborted)
629
+ return undefined;
630
+ const reason = signal.reason;
631
+ if (reason === null || typeof reason !== "object")
632
+ return undefined;
633
+ const scope = reason.crewhausTimeout;
634
+ if (scope !== "run" && scope !== "turn" && scope !== "model_call")
635
+ return undefined;
636
+ return {
637
+ crewhausTimeout: scope,
638
+ limitMs: typeof reason.limitMs === "number" ? reason.limitMs : 0,
639
+ };
640
+ }
641
+ /** Spec key each scope lowers from — used in detail/remediation copy. */
642
+ const TIMEOUT_SPEC_KEYS = {
643
+ run: "limits.deadline_ms",
644
+ turn: "limits.turn_timeout_ms",
645
+ model_call: "limits.model_call_timeout_ms",
646
+ };
647
+ const TIMEOUT_TITLES = {
648
+ run: "run deadline exceeded",
649
+ turn: "turn wall-clock limit exceeded",
650
+ model_call: "model call wall-clock limit exceeded",
651
+ };
652
+ /**
653
+ * G10 — build the classified terminal report for a fired wall-clock limit.
654
+ * `class: "timeout"` / exit {@link EXIT_CODES.timeout} joins the failure
655
+ * taxonomy beside `crewhaus_budget`: like the spend cap, the stop was
656
+ * CrewHaus's OWN configured ceiling, not a provider failure. Exported for
657
+ * emitters/tests that render or assert on the report.
658
+ */
659
+ export function buildTimeoutFailureReport(timeout) {
660
+ const scope = timeout.crewhausTimeout;
661
+ return {
662
+ class: "timeout",
663
+ title: TIMEOUT_TITLES[scope],
664
+ detail: `the configured ${TIMEOUT_SPEC_KEYS[scope]} (${timeout.limitMs}ms) elapsed before the ${scope === "run" ? "run" : scope === "turn" ? "turn" : "model call"} completed`,
665
+ remediation: `raise ${TIMEOUT_SPEC_KEYS[scope]} in the spec's limits block (or remove it), then rerun.`,
666
+ exitCode: EXIT_CODES.timeout,
667
+ };
668
+ }
669
+ /**
670
+ * Item 3 (G32) — merge plugin-contributed tools into the run's advertised tool
671
+ * set. First-party `base` tools WIN any name collision, so an activated plugin
672
+ * can augment the catalog but never silently shadow a built-in. Returns the
673
+ * `base` array unchanged (same reference) when there are no plugin tools, so a
674
+ * run without the `plugins` option is byte-identical to a pre-G32 runtime.
675
+ */
676
+ function mergeEffectiveTools(base, pluginTools) {
677
+ if (pluginTools === undefined || pluginTools.length === 0)
678
+ return base;
679
+ const byName = new Set(base.map((t) => t.name));
680
+ const merged = [...base];
681
+ for (const tool of pluginTools) {
682
+ if (byName.has(tool.name))
683
+ continue; // first-party wins the collision
684
+ byName.add(tool.name);
685
+ merged.push(tool);
686
+ }
687
+ return merged;
688
+ }
596
689
  export async function runChatLoop(opts) {
690
+ // Item 3 (G32) — resolve the advertised tool set ONCE, up front, folding in
691
+ // any plugin-contributed tools so the tool-capable-model feature gate and the
692
+ // per-turn advertisement below read the same list.
693
+ const effectiveTools = mergeEffectiveTools(opts.tools ?? [], opts.plugins?.tools);
597
694
  // Pillar 3 — make the model-backed Layer-3 classifier reachable at EVERY
598
695
  // trust boundary (MCP / sub-agent / channel / federation / skill /
599
696
  // compaction / chain / orchestrator). Boundary call sites don't thread an
@@ -684,7 +781,7 @@ export async function runChatLoop(opts) {
684
781
  // adapter that doesn't speak tool use (e.g. Bedrock Llama/Mistral
685
782
  // families). Fail with a clear ConfigError naming the model instead of
686
783
  // letting the provider 400 (or silently drop the tools) mid-run.
687
- if ((opts.tools ?? []).length > 0 && adapter.features.tool_use === false) {
784
+ if (effectiveTools.length > 0 && adapter.features.tool_use === false) {
688
785
  throw new ConfigError(`model "${opts.model}" (provider ${providerId}) does not support tool use — remove tools or pick a tool-capable model`);
689
786
  }
690
787
  let compactionAdapter;
@@ -734,6 +831,16 @@ export async function runChatLoop(opts) {
734
831
  // Item 26 — tool_use blocks the PREVIOUS turn produced (a tier-routing
735
832
  // signal). Persists across `runOneTurn` calls; 0 on the first turn.
736
833
  let priorTurnToolUseCount = 0;
834
+ // Item 4 / G28 — the provider's ACTUAL input_tokens (input + cache read +
835
+ // cache create) from the MOST RECENT `model_response`. Updated after every
836
+ // main-turn model call; feeds the pre-turn compaction trigger and the
837
+ // tier/pool routing `contextTokens` signal a real count instead of the
838
+ // chars/4 heuristic. `undefined` before the first response — the heuristic
839
+ // is used only pre-first-call.
840
+ let lastModelInputTokens;
841
+ /** The context-size signal for routing/compaction: the provider's real
842
+ * last-call input_tokens once available, else the chars/4 estimate. */
843
+ const contextTokenSignal = (msgs) => lastModelInputTokens ?? estimateTokens(msgs);
737
844
  // Default model max OUTPUT tokens for one turn. Callers thread the spec's
738
845
  // `agent.max_tokens` here when set (the CLI target's codegen + apps/cli);
739
846
  // this fallback applies when the spec is silent. Kept comfortably above the
@@ -743,6 +850,34 @@ export async function runChatLoop(opts) {
743
850
  // `max_tokens` recovery + `sanitizeOrphanToolUses`), but a higher ceiling
744
851
  // avoids the churn. Raise it per spec with `agent.max_tokens`.
745
852
  const maxTokens = opts.maxTokens ?? 8192;
853
+ // G01 — resolve the extended-thinking request fields ONCE at boot. The
854
+ // budget form maps verbatim; the effort form sets BOTH `thinking`
855
+ // (converted through the shared preset table for budget-style providers)
856
+ // and `reasoningEffort` (passed through for native-effort providers) —
857
+ // adapters ignore whichever field they don't support, and anthropic's
858
+ // translate gives the explicit `thinking` precedence, so the two agree.
859
+ const thinkingRequest = opts.thinking === undefined
860
+ ? undefined
861
+ : "budgetTokens" in opts.thinking
862
+ ? { thinking: { type: "enabled", budgetTokens: opts.thinking.budgetTokens } }
863
+ : {
864
+ thinking: {
865
+ type: "enabled",
866
+ budgetTokens: EFFORT_THINKING_BUDGET_TOKENS[opts.thinking.effort],
867
+ },
868
+ reasoningEffort: opts.thinking.effort,
869
+ };
870
+ // Anthropic (and the other budget-style providers) require
871
+ // `max_tokens > thinking.budget_tokens` — thinking tokens spend from the
872
+ // same output ceiling. When the configured budget crowds the ceiling out,
873
+ // lift the per-request ceiling to `budget + maxTokens` so the declared
874
+ // output budget survives intact instead of 400-ing every call (e.g.
875
+ // `effort: high` = 24576 over the 8192 default). The spec-declared
876
+ // `maxTokens` stays the bridge/sub-agent value — only main-turn requests
877
+ // (the only ones that carry `thinking`) use the lifted ceiling.
878
+ const effectiveMaxTokens = thinkingRequest !== undefined && thinkingRequest.thinking.budgetTokens >= maxTokens
879
+ ? thinkingRequest.thinking.budgetTokens + maxTokens
880
+ : maxTokens;
746
881
  // Mutual exclusion: resume takes priority and replaces any seedMessages
747
882
  // in REPL mode (the resume payload becomes the seed). Section 12 carves
748
883
  // out an exception for singleTurn + resume: the seed is the NEW inbound
@@ -768,6 +903,21 @@ export async function runChatLoop(opts) {
768
903
  // Housekeeping side-effect: evicts any session whose mtime is older than
769
904
  // the TTL (default 30 days). The returned list is intentionally discarded.
770
905
  await sessionStore.list();
906
+ // Loop contract 0.4 (G11) — the same sweep for the approvals log sitting
907
+ // beside those sessions. It has no other unattended pruner: only `list()`
908
+ // compacts it, and `list()`'s only production callers are the human-invoked
909
+ // `crewhaus approvals` verbs — so on a daemon or a cron'd run the file grew
910
+ // forever, carrying the raw tool input of every park.
911
+ //
912
+ // Deliberately NOT routed through `opts.approvals.store`: that option is
913
+ // narrowed to `persist | get | resolve` so callers can inject minimal twins,
914
+ // and widening the Pick would break them. Unconditional (not gated on
915
+ // `opts.approvals`) so a harness that has since switched to `ask_mode: deny`
916
+ // still gets its old parks pruned; it costs one ENOENT when the file does
917
+ // not exist. Best-effort, exactly like the session sweep above.
918
+ await evictExpiredApprovals({
919
+ ...(sessionRootDir !== undefined ? { rootDir: sessionRootDir } : {}),
920
+ }).catch(() => undefined);
771
921
  // Adaptive model routing (spec `agent.model_pool`). Resolve every candidate
772
922
  // adapter ONCE at boot (mirroring the tier router), open the durable reward
773
923
  // scoreboard beside the sessions dir, and build the PolicyRouter. The
@@ -899,7 +1049,29 @@ export async function runChatLoop(opts) {
899
1049
  // sessionId; otherwise build a fresh context bound to that sessionId.
900
1050
  // Tests that pass their own runContext rely on observing turnNumber on
901
1051
  // it after the loop returns, so we never silently swap it out.
902
- const runContext = opts.runContext ?? createRunContext({ sessionId });
1052
+ //
1053
+ // Loop contract 0.4 (Batch C, item 4) — when the caller supplies an
1054
+ // `agentId` and lets runChatLoop own the context, build the bus with that
1055
+ // identity so `envelope()` stamps every trace event with it. runId is minted
1056
+ // here (matching run-context's `run_<8 hex>` shape) and threaded into BOTH
1057
+ // the bus and the context so their ids stay coherent. When `opts.runContext`
1058
+ // is supplied the caller owns `agentId` on its bus, so this is skipped.
1059
+ const runContext = opts.runContext ??
1060
+ (opts.agentId !== undefined
1061
+ ? (() => {
1062
+ const runId = `run_${randomUUID().slice(0, 8)}`;
1063
+ const eventBus = new TraceEventBus({ runId, sessionId, agentId: opts.agentId });
1064
+ return createRunContext({ runId, sessionId, eventBus });
1065
+ })()
1066
+ : createRunContext({ sessionId }));
1067
+ // G01 — surface the max-tokens lift once, at boot (see `effectiveMaxTokens`).
1068
+ if (effectiveMaxTokens !== maxTokens) {
1069
+ runContext.logger.info("thinking budget >= max_tokens — lifting the per-request ceiling", {
1070
+ thinkingBudgetTokens: thinkingRequest?.thinking.budgetTokens,
1071
+ maxTokens,
1072
+ effectiveMaxTokens,
1073
+ });
1074
+ }
903
1075
  // Adaptive model routing — ε-greedy exploration seed. A spec-fixed
904
1076
  // `learning.seed` reproduces exploration across runs (tests); otherwise the
905
1077
  // sessionId seeds it, so each run explores differently yet still replays
@@ -911,7 +1083,6 @@ export async function runChatLoop(opts) {
911
1083
  // mints a no-subscriber bus; here we attach the env-gated set so a fresh
912
1084
  // run with `OTEL_EXPORTER_OTLP_ENDPOINT` set automatically exports.
913
1085
  const bus = runContext.eventBus;
914
- void TraceEventBus; // keep type import alive for future direct constructions
915
1086
  // Item 22 — re-point the failover chain's late-bound bus getter at the
916
1087
  // run's real bus (see the chain construction above): the chain and its
917
1088
  // per-candidate breakers publish model_failover / circuit_state_changed
@@ -1028,9 +1199,14 @@ export async function runChatLoop(opts) {
1028
1199
  // byte-identical to before. `out.write` is the spinner-aware stdout sink:
1029
1200
  // every interactive write that can land while the animation is live goes
1030
1201
  // through it so the two never collide. `opts.spinner` overrides the auto
1031
- // decision.
1202
+ // decision. `opts.stdout` redirects the whole human-facing surface (item 20
1203
+ // — concurrent eval samples each get their own sink instead of splicing
1204
+ // token deltas into one shared stdout).
1032
1205
  const spinnerEnabled = opts.spinner ?? (opts.singleTurn !== true && opts.input === undefined && isSpinnerEnabled());
1033
- const out = createCliOutput({ enabled: spinnerEnabled });
1206
+ const out = createCliOutput({
1207
+ enabled: spinnerEnabled,
1208
+ ...(opts.stdout !== undefined ? { write: opts.stdout } : {}),
1209
+ });
1034
1210
  // M2.1 — CLI markdown renderer (env-gated). When CREWHAUS_CLI_MARKDOWN=1,
1035
1211
  // text-delta chunks flow through a streaming markdown → ANSI transform so
1036
1212
  // the user sees rendered bold/italic/headers/lists/code-fences instead of
@@ -1112,6 +1288,11 @@ export async function runChatLoop(opts) {
1112
1288
  // score per-server MCP health offline. Shares the advisor's DEFAULT-ON gate
1113
1289
  // (CREWHAUS_ADVISOR_EVENTS=0 disables both). See observability.ts.
1114
1290
  const mcpStatsPersist = attachMcpStatsPersistence(bus, eventLog, runContext);
1291
+ // "Watch me" — live capture tap (CREWHAUS_WATCHME-gated, off by default):
1292
+ // append the bus-only TraceEvent kinds to the `sessions/<id>.events.jsonl`
1293
+ // sibling that `sessions export` already reads. Mirrored/ephemeral kinds are
1294
+ // skipped, so the sibling stays metadata-grade. See observability.ts.
1295
+ const watchmeCapture = attachWatchmeCapture(bus, sessionRootDir ?? DEFAULT_ROOT_DIR, sessionId);
1115
1296
  // Per-run state container — coordination surface for hooks/skills/tools.
1116
1297
  // Shipped as plumbing in Section 10; v0.3.0 Goal 1 (§2.5) lands its first
1117
1298
  // consumer: plan-mutating tools set `PLAN_DIRTY_STATE_KEY` here (via the
@@ -1169,6 +1350,34 @@ export async function runChatLoop(opts) {
1169
1350
  runContext.logger.warn("memory auto-capture failed", { error: err.message });
1170
1351
  }
1171
1352
  };
1353
+ // Item 1 — how many turns produced a non-empty assistant answer. The exit
1354
+ // rating prompt's "this session actually said something worth rating" floor.
1355
+ let assistantAnswers = 0;
1356
+ /**
1357
+ * Item 1 — the exit rating prompt (spec `feedback:`). Runs in the REPL
1358
+ * teardown AFTER readline has released stdin (the read is raw-mode) and
1359
+ * BEFORE the event log closes, so the rating lands in this session's own
1360
+ * transcript. Best-effort by contract: a prompt/append failure must never
1361
+ * turn a clean session into a non-zero exit.
1362
+ */
1363
+ const maybeExitRating = async (cleanExit) => {
1364
+ await runExitRating({
1365
+ feedback: opts.feedback,
1366
+ // A caller-supplied `input` stream means the runtime does not own the
1367
+ // terminal (tests, piped hosts), so it is never a prompt target.
1368
+ stdinIsTTY: opts.input === undefined && process.stdin.isTTY === true,
1369
+ env: process.env,
1370
+ assistantTurns: assistantAnswers,
1371
+ cleanExit,
1372
+ sessionId,
1373
+ turnNumber: runContext.turnNumber,
1374
+ append: async (record) => {
1375
+ await eventLog.append({ kind: FEEDBACK_EVENT_KIND, payload: record });
1376
+ },
1377
+ write: (line) => out.write(line),
1378
+ onError: (err) => runContext.logger.warn("exit rating prompt failed", { error: err.message }),
1379
+ });
1380
+ };
1172
1381
  // -------------------------------------------------------------------------
1173
1382
  // v0.3.0 Goal 1 — continuity wiring (§2.3 ledger, §2.5 tail, §2.8 handoff).
1174
1383
  // Everything below is inert when `opts.continuity` is absent: no tail
@@ -1314,6 +1523,28 @@ export async function runChatLoop(opts) {
1314
1523
  const compactionThreshold = opts.compactionThreshold ?? DEFAULT_COMPACTION_THRESHOLD;
1315
1524
  const snipKeepHead = opts.snipKeepHead ?? DEFAULT_SNIP_KEEP_HEAD;
1316
1525
  const snipKeepTail = opts.snipKeepTail ?? DEFAULT_SNIP_KEEP_TAIL;
1526
+ // Item 1 / G19 — active-context curation config (present ⇒ the pre-pass
1527
+ // runs, gated by the emitter on `ir.compaction.curate`) and the shared
1528
+ // extra `maybeCompact` args threaded at both call sites: the injected
1529
+ // curate config, the `curate`-event publisher, and the real-token trigger.
1530
+ const curateConfig = opts.curate;
1531
+ const publishCurate = async (info) => {
1532
+ bus.publish({
1533
+ ...bus.envelope(),
1534
+ kind: "curate",
1535
+ before: info.before,
1536
+ after: info.after,
1537
+ dropped: info.dropped,
1538
+ bytesSaved: info.bytesSaved,
1539
+ embedded: info.embedded,
1540
+ });
1541
+ };
1542
+ /** The extra `maybeCompact` args (Item 1 curation + Item 4 real tokens),
1543
+ * recomputed per call so `realInputTokens` reflects the newest response. */
1544
+ const compactionExtras = () => ({
1545
+ ...(lastModelInputTokens !== undefined ? { realInputTokens: lastModelInputTokens } : {}),
1546
+ ...(curateConfig !== undefined ? { curate: curateConfig, onCurate: publishCurate } : {}),
1547
+ });
1317
1548
  const permissionMode = opts.permissionMode ?? "default";
1318
1549
  const permissionRules = opts.permissionRules ?? {
1319
1550
  ...emptyRuleSet,
@@ -1371,47 +1602,83 @@ export async function runChatLoop(opts) {
1371
1602
  ]
1372
1603
  : [];
1373
1604
  if (projectMemory.files.length > 0) {
1374
- process.stdout.write(`[memory] loaded ${projectMemory.files.length} project memory file(s): ${projectMemory.files
1605
+ // Human-facing loop output → the same sink as everything else, so a
1606
+ // fanned-out caller (eval samples) can attribute the line (item 20).
1607
+ out.write(`[memory] loaded ${projectMemory.files.length} project memory file(s): ${projectMemory.files
1375
1608
  .map((f) => f.filename)
1376
1609
  .join(", ")}\n`);
1377
1610
  }
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.
1611
+ // Feature #53 / Item 2 (G21) — cross-session auto-recall. `recallMode`
1612
+ // decides WHERE the recalled evidence lives:
1613
+ // - "session-start" (default): pull the top-K relevant memories ONCE at
1614
+ // boot and inject them into the frozen, cache-marked system prefix
1615
+ // below — the pre-0.4 behaviour.
1616
+ // - "per-turn": leave the frozen prefix empty and instead refresh a
1617
+ // VOLATILE recalled block every `refreshEvery` turns (see
1618
+ // `maybePerTurnRecall`), so a long daemon's evidence tracks the
1619
+ // conversation instead of drifting from a stale boot-time snapshot.
1620
+ // The caller supplies the `recall` seam (runtime-core stays independent of
1621
+ // memory-store). Best-effort: a recall failure never aborts the run.
1622
+ const recallMode = opts.memory?.recallMode ?? "session-start";
1623
+ const autoRecallOn = opts.memory?.autoRecall === true && opts.memory?.recall !== undefined;
1383
1624
  let memoryRecallBlock = [];
1384
- if (opts.memory?.autoRecall === true && opts.memory.recall !== undefined) {
1625
+ if (autoRecallOn && recallMode !== "per-turn" && opts.memory?.recall !== undefined) {
1385
1626
  try {
1386
1627
  const seed = opts.memory.recallSeed ?? opts.instructions;
1387
1628
  const k = opts.memory.recallK ?? 5;
1629
+ // Pillar 3 — a recalled memory can embed content shaped by untrusted
1630
+ // tool output from an earlier session; `renderRecalledMemory` applies
1631
+ // the same delimiter-safety + boundary-classification defenses the
1632
+ // security fabric uses for every other prompt-bound source (#53).
1388
1633
  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);
1634
+ const text = await renderRecalledMemory(lines);
1635
+ if (text !== undefined) {
1407
1636
  memoryRecallBlock = [{ type: "text", text, cache_control: { type: "ephemeral" } }];
1408
- process.stdout.write(`[memory] recalled ${lines.length} memory(ies) into the prompt\n`);
1637
+ out.write(`[memory] recalled ${lines.length} memory(ies) into the prompt\n`);
1409
1638
  }
1410
1639
  }
1411
1640
  catch (err) {
1412
1641
  runContext.logger.warn("memory auto-recall failed", { error: err.message });
1413
1642
  }
1414
1643
  }
1644
+ // Item 2 (G21) — per-turn recall state. The volatile block sits in the
1645
+ // mutable tail region (never the frozen prefix), so swapping it each turn
1646
+ // re-tokenizes only the tail and never busts the cached system prefix. The
1647
+ // refresh cadence counter starts "due" so the first applicable turn recalls.
1648
+ const perTurnRecallEnabled = autoRecallOn && recallMode === "per-turn";
1649
+ const perTurnRefreshEvery = Math.max(1, opts.memory?.refreshEvery ?? 1);
1650
+ let volatileRecallBlocks = [];
1651
+ let turnsSinceRecall = perTurnRefreshEvery;
1652
+ const maybePerTurnRecall = async (msgs) => {
1653
+ if (!perTurnRecallEnabled)
1654
+ return;
1655
+ if (turnsSinceRecall < perTurnRefreshEvery) {
1656
+ turnsSinceRecall++;
1657
+ return;
1658
+ }
1659
+ turnsSinceRecall = 1;
1660
+ const recall = opts.memory?.recall;
1661
+ if (recall === undefined)
1662
+ return;
1663
+ // Recall against the LATEST user message (the interactive cadence), falling
1664
+ // back to the seed/instructions when the tail carries no human text.
1665
+ const query = latestUserText(msgs) ?? opts.memory?.recallSeed ?? opts.instructions;
1666
+ const k = opts.memory?.recallK ?? 5;
1667
+ try {
1668
+ const lines = await recall(query, k);
1669
+ const text = await renderRecalledMemory(lines);
1670
+ volatileRecallBlocks = text !== undefined ? [{ type: "text", text }] : [];
1671
+ if (lines.length > 0) {
1672
+ out.write(`[memory] refreshed ${lines.length} recalled memory(ies) for this turn\n`);
1673
+ }
1674
+ }
1675
+ catch (err) {
1676
+ // Keep the prior volatile block on a transient recall failure.
1677
+ runContext.logger.warn("per-turn memory recall failed", {
1678
+ error: err.message,
1679
+ });
1680
+ }
1681
+ };
1415
1682
  // Section 17 — runtime-core no longer prepends the Claude Code OAuth
1416
1683
  // prefix; `adapter-anthropic` handles that internally so each adapter
1417
1684
  // owns its provider-specific auth-shape requirements.
@@ -1466,7 +1733,7 @@ export async function runChatLoop(opts) {
1466
1733
  }
1467
1734
  }
1468
1735
  }
1469
- const tools = opts.tools ?? [];
1736
+ const tools = effectiveTools;
1470
1737
  const anthropicTools = tools.length > 0
1471
1738
  ? tools.map((t) => ({
1472
1739
  name: t.name,
@@ -1475,6 +1742,33 @@ export async function runChatLoop(opts) {
1475
1742
  }))
1476
1743
  : undefined;
1477
1744
  const toolByName = new Map(tools.map((t) => [t.name, t]));
1745
+ // G17 — per-tool rate limiter, built once at loop start from the lowered
1746
+ // `agent.rate_limits` map. One token bucket per entry: `rpm` is the
1747
+ // sustained refill (per-minute → per-second), `burst` the instantaneous
1748
+ // capacity (defaults to `rpm`, the standard token-bucket parameterization
1749
+ // where a full window's allowance may burst). The `"*"` key becomes the
1750
+ // limiter's per-dimension `tool:*` default, which `acquire` falls back to
1751
+ // for any tool without a named bucket — each such tool still gets its OWN
1752
+ // bucket instance (state keys on the specific `tool:<name>`), so the
1753
+ // default is a per-tool limit, not one shared pool. `hasToolRateBucket`
1754
+ // gates the acquire call site: tools outside the map (no named entry, no
1755
+ // `"*"`) are not rate-gated at all — the limiter itself is fail-closed on
1756
+ // unknown keys, so the guard is what keeps unlisted tools ungated.
1757
+ const rateLimitEntries = Object.entries(opts.rateLimits ?? {});
1758
+ let toolRateLimiter;
1759
+ if (rateLimitEntries.length > 0) {
1760
+ const buckets = new Map();
1761
+ for (const [name, limit] of rateLimitEntries) {
1762
+ buckets.set(`tool:${name}`, {
1763
+ kind: "token-bucket",
1764
+ capacity: limit.burst ?? limit.rpm,
1765
+ refillPerSec: limit.rpm / 60,
1766
+ });
1767
+ }
1768
+ toolRateLimiter = createRateLimiter({ buckets });
1769
+ }
1770
+ const hasToolRateBucket = (toolName) => opts.rateLimits !== undefined &&
1771
+ (opts.rateLimits[toolName] !== undefined || opts.rateLimits["*"] !== undefined);
1478
1772
  // Root abort tree for the whole run; each turn gets a child.
1479
1773
  const runAbort = createAbortTree(runContext.abortSignal);
1480
1774
  // Per-turn abort tree, replaced at the start of each turn so a SIGINT
@@ -1482,17 +1776,97 @@ export async function runChatLoop(opts) {
1482
1776
  let turnAbort = runAbort.child();
1483
1777
  // Latest error captured from a model call, fed to recover() on entry to NeedRecovery.
1484
1778
  let lastErrorForRecovery = undefined;
1779
+ const fireTimeout = (tree, scope, limitMs) => {
1780
+ out.spinner.stop();
1781
+ const noun = scope === "run" ? "run deadline" : scope === "turn" ? "turn timeout" : "model call timeout";
1782
+ out.write(`\n[${noun}: ${limitMs}ms elapsed — aborting]\n`);
1783
+ runContext.logger.warn("wall-clock limit fired", { scope, limitMs });
1784
+ tree.abort({ crewhausTimeout: scope, limitMs });
1785
+ };
1786
+ const armTimer = (tree, scope, limitMs) => {
1787
+ const timer = setTimeout(() => fireTimeout(tree, scope, limitMs), limitMs);
1788
+ timer.unref();
1789
+ return timer;
1790
+ };
1791
+ let deadlineTimer;
1792
+ if (opts.deadlineMs !== undefined && opts.deadlineMs > 0) {
1793
+ deadlineTimer = armTimer(runAbort, "run", opts.deadlineMs);
1794
+ }
1795
+ let turnTimer;
1796
+ const armTurnTimer = () => {
1797
+ if (opts.turnTimeoutMs === undefined || opts.turnTimeoutMs <= 0)
1798
+ return;
1799
+ turnTimer = armTimer(turnAbort, "turn", opts.turnTimeoutMs);
1800
+ };
1801
+ const clearTurnTimer = () => {
1802
+ if (turnTimer !== undefined)
1803
+ clearTimeout(turnTimer);
1804
+ turnTimer = undefined;
1805
+ };
1806
+ let modelCallTimer;
1807
+ const armModelCallTimer = () => {
1808
+ if (opts.modelCallTimeoutMs === undefined || opts.modelCallTimeoutMs <= 0)
1809
+ return;
1810
+ modelCallTimer = armTimer(turnAbort, "model_call", opts.modelCallTimeoutMs);
1811
+ };
1812
+ const clearModelCallTimer = () => {
1813
+ if (modelCallTimer !== undefined)
1814
+ clearTimeout(modelCallTimer);
1815
+ modelCallTimer = undefined;
1816
+ };
1817
+ const clearAllTimers = () => {
1818
+ if (deadlineTimer !== undefined)
1819
+ clearTimeout(deadlineTimer);
1820
+ deadlineTimer = undefined;
1821
+ clearTurnTimer();
1822
+ clearModelCallTimer();
1823
+ };
1485
1824
  // Permission-ask prompter. Set in REPL mode after the readline interface
1486
1825
  // exists; remains undefined in single-turn mode (where ask collapses to deny).
1487
1826
  // The initial assignment makes the second assignment legal under biome's
1488
1827
  // `useConst` rule (which fires on exactly-one-assignment lets).
1489
1828
  let askApproval = undefined;
1829
+ // Loop contract 0.4 (Batch C, G11) — headless ask-approval parking. `askMode`
1830
+ // is the lowered `permissions.ask_mode` (absent ⇒ "pause"); `approvals` is
1831
+ // the injected persistence seam. Parking is active only when BOTH a store is
1832
+ // present AND the mode is "pause" — otherwise a headless `ask` collapses to
1833
+ // the pre-0.4 deny. `approvalSurface` classifies the `approval_requested`
1834
+ // event; it never affects the REPL path (which prompts on stdin).
1835
+ const askMode = opts.askMode ?? "pause";
1836
+ const approvals = opts.approvals;
1837
+ const approvalSurface = approvals?.surface ?? (opts.singleTurn === true ? "single-turn" : "headless");
1490
1838
  // Per-run state for tool-loop detection and warning de-dup. Both span
1491
1839
  // turns within a single `runChatLoop` invocation so cross-turn loops
1492
1840
  // (e.g. "keep running date") get caught and warned at most once per
1493
1841
  // signature.
1842
+ //
1843
+ // G27 — `loopSignatureStage` replaces the old warned-signature Set with a
1844
+ // two-stage ladder per signature: first detection → `"warned"` (the
1845
+ // pre-0.4 one-time warning, all escalation modes), a REPEAT detection of
1846
+ // the same signature → the configured escalation (`justify` demand or
1847
+ // turn `abort`), recorded as `"escalated"` so it fires at most once per
1848
+ // signature too. In the default `"warn"` mode the second stage is a
1849
+ // no-op — byte-identical behaviour to the pre-0.4 runtime.
1494
1850
  const toolUseHistory = [];
1495
- const warnedLoopSignatures = new Set();
1851
+ const loopSignatureStage = new Map();
1852
+ const loopEscalation = opts.loopDetection?.escalation ?? "warn";
1853
+ // Loop contract 0.4 (Batch C, item 7) — per-tool cost attribution. When a
1854
+ // NON-streaming model response that emitted tool_use blocks is priceable, the
1855
+ // response's cost is split evenly across those calls and stashed here by
1856
+ // tool_use id, then stamped as `attributedCostUsdMicros` on each `tool_use`
1857
+ // event-log record. Keyed by id (unique per call) and consumed (deleted) on
1858
+ // read to bound growth. The streaming path dispatches tools BEFORE the
1859
+ // response's usage is known, so it never populates this map — precisely the
1860
+ // "where the model usage split is computable" boundary: absent ⇒ no field.
1861
+ const toolCostAttribution = new Map();
1862
+ // Response cost in USD-micros, or undefined when the served model isn't on the
1863
+ // pricing table (the split is then not computable — no attribution stamped).
1864
+ const responseCostMicros = (provider, wireModelId, usage) => {
1865
+ const row = resolvePricing(DEFAULT_PRICING, provider, wireModelId);
1866
+ if (row === undefined)
1867
+ return undefined;
1868
+ return computeCostMicros(row, usage.input, usage.output, usage.cacheRead ?? 0, usage.cacheCreate ?? 0);
1869
+ };
1496
1870
  // Working-indicator bookkeeping for tool execution. A single shared spinner
1497
1871
  // serves the whole loop, so the set tracks which tools are mid-flight to
1498
1872
  // support the concurrent (read-only) partition: the label reflects how many
@@ -1534,7 +1908,18 @@ export async function runChatLoop(opts) {
1534
1908
  if (activeToolNames.length === 0)
1535
1909
  out.spinner.stop();
1536
1910
  out.write(`[tool: ${tu.name}]\n`);
1537
- await logEvent("tool_use", { id: tu.id, name: tu.name, input: tu.input });
1911
+ // Item 7 — stamp the per-tool cost attribution when the producing response
1912
+ // was priceable (non-streaming path only; see `toolCostAttribution`).
1913
+ // Consume the entry so the map stays bounded across a long run.
1914
+ const attributedCostUsdMicros = toolCostAttribution.get(tu.id);
1915
+ if (attributedCostUsdMicros !== undefined)
1916
+ toolCostAttribution.delete(tu.id);
1917
+ await logEvent("tool_use", {
1918
+ id: tu.id,
1919
+ name: tu.name,
1920
+ input: tu.input,
1921
+ ...(attributedCostUsdMicros !== undefined ? { attributedCostUsdMicros } : {}),
1922
+ });
1538
1923
  const inputBytes = Buffer.byteLength(JSON.stringify(tu.input ?? null), "utf8");
1539
1924
  const toolStartEnvelope = bus.envelope();
1540
1925
  bus.publish({
@@ -1627,22 +2012,90 @@ export async function runChatLoop(opts) {
1627
2012
  }
1628
2013
  else if (decision === "ask") {
1629
2014
  if (askApproval !== undefined) {
2015
+ // Interactive REPL path — unchanged: prompt on stdin.
1630
2016
  approved = await askApproval(tu.name, tu.input);
1631
2017
  if (!approved)
1632
2018
  denialMessage = "tool denied by user";
1633
2019
  }
2020
+ else if (approvals !== undefined && askMode === "pause") {
2021
+ // G11 headless parking/resume. Consult the store for a prior decision
2022
+ // on this exact (toolName, inputHash).
2023
+ const inputHash = hashApprovalInput(tu.name, tu.input);
2024
+ const existing = await approvals.store.get(tu.name, inputHash);
2025
+ if (existing?.decision === "grant") {
2026
+ // One-shot allow: consume the grant so a later identical call re-asks.
2027
+ approved = true;
2028
+ await approvals.store.persist({ ...existing, consumedAt: new Date().toISOString() });
2029
+ }
2030
+ else if (existing?.decision === "deny") {
2031
+ approved = false;
2032
+ denialMessage = `tool denied: \`${tu.name}\` approval was denied${existing.decidedBy !== undefined ? ` by ${existing.decidedBy}` : ""}.`;
2033
+ }
2034
+ else {
2035
+ // No decision yet. Reuse an existing pending record for this key
2036
+ // (idempotent re-park across resumed runs) or persist a fresh one,
2037
+ // fire the out-of-band notification, publish `approval_requested`,
2038
+ // and PARK: throw the classified `approval_pending` report. The
2039
+ // NeedTools catch (non-streaming) publishes `run_failed` + rethrows;
2040
+ // the streaming path reaches the same halt through recovery's
2041
+ // classified-report passthrough. On the next execution the store
2042
+ // carries a grant/deny and the call re-resolves pre-decided.
2043
+ const pending = existing ?? {
2044
+ id: generateApprovalId(),
2045
+ toolName: tu.name,
2046
+ inputHash,
2047
+ input: tu.input,
2048
+ runId: bus.runId,
2049
+ sessionId,
2050
+ surface: approvalSurface,
2051
+ createdAt: new Date().toISOString(),
2052
+ };
2053
+ if (existing === null)
2054
+ await approvals.store.persist(pending);
2055
+ if (approvals.notify !== undefined) {
2056
+ await approvals.notify(pending).catch((err) => {
2057
+ runContext.logger.warn("approvals.notify failed", {
2058
+ approvalId: pending.id,
2059
+ error: err.message,
2060
+ });
2061
+ });
2062
+ }
2063
+ bus.publish({
2064
+ ...bus.envelope(),
2065
+ kind: "approval_requested",
2066
+ approvalId: pending.id,
2067
+ toolName: tu.name,
2068
+ surface: approvalSurface,
2069
+ });
2070
+ runContext.logger.info("tool approval parked", {
2071
+ approvalId: pending.id,
2072
+ toolName: tu.name,
2073
+ surface: approvalSurface,
2074
+ });
2075
+ throw new RunFailedError({
2076
+ class: "approval_pending",
2077
+ title: "awaiting tool approval",
2078
+ detail: `\`${tu.name}\` requires approval on a non-interactive surface (${approvalSurface}); the run is parked as approval ${pending.id}`,
2079
+ remediation: `grant or deny approval ${pending.id} out of band (e.g. \`crewhaus approvals grant ${pending.id}\`), then rerun`,
2080
+ exitCode: EXIT_CODES.approval_pending,
2081
+ });
2082
+ }
2083
+ }
1634
2084
  else {
2085
+ // Pre-0.4 collapse-to-deny: no interactive surface, and either
2086
+ // `ask_mode: "deny"` or no approvals store is wired to park against.
1635
2087
  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.`;
2088
+ `tool denied: \`${tu.name}\` defaulted to "ask" and this non-interactive surface has no way to prompt` +
2089
+ `${approvals === undefined ? " (no approvals store wired)" : ' (ask_mode: "deny")'}. ` +
2090
+ `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
2091
  }
1639
2092
  // 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.
2093
+ // above fired BEFORE the approval resolved (decision "ask", no outcome);
2094
+ // this one fires after the REPL prompt / store decision / collapse
2095
+ // resolves — so offline advice mining can measure how each tool's prompts
2096
+ // are actually answered. The advisor persistence subscriber
2097
+ // (observability.ts) keys on `askOutcome` to persist exactly this resolved
2098
+ // form. Unreached on the PARK path, which throws above.
1646
2099
  bus.publish({
1647
2100
  ...bus.envelope(),
1648
2101
  kind: "permission_decision",
@@ -1830,6 +2283,32 @@ export async function runChatLoop(opts) {
1830
2283
  });
1831
2284
  }
1832
2285
  }
2286
+ // G17 — per-tool rate gate. Sits AFTER every deny-capable gate
2287
+ // (permission / justification / egress) so a denied call never burns a
2288
+ // token, and BEFORE dispatch so the pacing wait is what the model
2289
+ // experiences as tool latency. Only tools with a named bucket or under
2290
+ // a `"*"` default are gated (the limiter is fail-closed on unknown
2291
+ // keys, so the guard is what keeps unlisted tools ungated). Exhausting
2292
+ // the limiter's wait budget fails just THIS call with an `is_error`
2293
+ // result the model can adapt to — never the run.
2294
+ if (toolRateLimiter !== undefined && hasToolRateBucket(tu.name)) {
2295
+ try {
2296
+ await toolRateLimiter.acquire([{ dimension: "tool", id: tu.name }], 1);
2297
+ }
2298
+ catch (err) {
2299
+ runContext.logger.warn("tool rate limit exhausted", {
2300
+ toolUseId: tu.id,
2301
+ toolName: tu.name,
2302
+ error: err.message,
2303
+ });
2304
+ return finish({
2305
+ type: "tool_result",
2306
+ tool_use_id: tu.id,
2307
+ content: `[rate-limited] ${err.message}. Wait before retrying "${tu.name}", or proceed another way.`,
2308
+ is_error: true,
2309
+ });
2310
+ }
2311
+ }
1833
2312
  const toolAbort = turnAbort.child();
1834
2313
  // Build the bridge for this call. Built on EVERY run (#160 follow-up):
1835
2314
  // it carries `runContext`, which Pillar-3 boundary-site tools (tool-mcp,
@@ -1865,6 +2344,13 @@ export async function runChatLoop(opts) {
1865
2344
  ...(skills.length > 0 ? { skills } : {}),
1866
2345
  ...(opts.failureTaxonomy !== undefined ? { failureTaxonomy: opts.failureTaxonomy } : {}),
1867
2346
  ...(bridgeContinuitySeam !== undefined ? { continuity: bridgeContinuitySeam } : {}),
2347
+ // Loop contract 0.4 (G11) — the approval seam, so a Task child's
2348
+ // headless `ask` parks against the SAME store the parent parks against
2349
+ // instead of collapsing to a denial. `askMode` is spread only when the
2350
+ // caller set it, so an unset parent leaves the child on this loop's own
2351
+ // `"pause"` default — identical resolution, no double-defaulting.
2352
+ ...(opts.askMode !== undefined ? { askMode: opts.askMode } : {}),
2353
+ ...(opts.approvals !== undefined ? { approvals: opts.approvals } : {}),
1868
2354
  };
1869
2355
  // Spin "running <tool>…" for exactly the execution window — started after
1870
2356
  // every gate (permission/justification/egress) so it never overlaps the
@@ -2092,28 +2578,77 @@ export async function runChatLoop(opts) {
2092
2578
  }
2093
2579
  return results;
2094
2580
  }
2581
+ function evaluateToolLoop() {
2582
+ const detection = detectLoop(toolUseHistory, opts.loopDetection?.window, opts.loopDetection?.threshold);
2583
+ if (detection === null)
2584
+ return { kind: "none" };
2585
+ const stage = loopSignatureStage.get(detection.signature);
2586
+ if (stage === undefined) {
2587
+ loopSignatureStage.set(detection.signature, "warned");
2588
+ runContext.logger.warn("tool loop detected", {
2589
+ signature: detection.signature,
2590
+ toolName: detection.toolName,
2591
+ count: detection.count,
2592
+ tier: detection.tier,
2593
+ escalation: loopEscalation,
2594
+ });
2595
+ const how = detection.tier === "exact"
2596
+ ? "with the same input"
2597
+ : "with near-identical inputs (differing only in numbers/ids)";
2598
+ return {
2599
+ kind: "message",
2600
+ stage: "warn",
2601
+ detection,
2602
+ message: {
2603
+ role: "user",
2604
+ 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.`,
2605
+ },
2606
+ };
2607
+ }
2608
+ if (stage !== "warned")
2609
+ return { kind: "none" };
2610
+ if (loopEscalation === "justify") {
2611
+ loopSignatureStage.set(detection.signature, "escalated");
2612
+ runContext.logger.warn("tool loop persists — demanding justification", {
2613
+ signature: detection.signature,
2614
+ toolName: detection.toolName,
2615
+ count: detection.count,
2616
+ tier: detection.tier,
2617
+ });
2618
+ return {
2619
+ kind: "message",
2620
+ stage: "justify",
2621
+ detection,
2622
+ message: {
2623
+ role: "user",
2624
+ 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.`,
2625
+ },
2626
+ };
2627
+ }
2628
+ if (loopEscalation === "abort") {
2629
+ loopSignatureStage.set(detection.signature, "escalated");
2630
+ return { kind: "abort", detection };
2631
+ }
2632
+ // escalation "warn" — the warning already fired once; stay quiet.
2633
+ return { kind: "none" };
2634
+ }
2095
2635
  /**
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.
2636
+ * G27 `escalation: "abort"` bookkeeping — the ToolLoopLimit-style
2637
+ * classified error record (named `error` event + logger line), shared by
2638
+ * the streaming and non-streaming tool-batch call sites. The caller takes
2639
+ * the `Aborted` state transition itself (the two sites sit at different
2640
+ * points in the state machine).
2100
2641
  */
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,
2642
+ async function recordLoopAbort(detection) {
2643
+ await logEvent("error", {
2644
+ name: "ToolLoopAbort",
2645
+ 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"`,
2646
+ });
2647
+ runContext.logger.error("tool loop escalation — aborting turn", {
2110
2648
  toolName: detection.toolName,
2111
- count: detection.count,
2649
+ signature: detection.signature,
2650
+ tier: detection.tier,
2112
2651
  });
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
2652
  }
2118
2653
  /**
2119
2654
  * Run one user→assistant turn through the state machine. Mutates
@@ -2121,9 +2656,62 @@ export async function runChatLoop(opts) {
2121
2656
  * Returns the final assistant content blocks so callers can extract
2122
2657
  * text. Closes over client/model/maxTokens/etc.
2123
2658
  */
2659
+ // v0.3.0 Goal 6 — one structured report on every terminal path, published
2660
+ // to the bus AND appended to the session event log BEFORE the throw (a
2661
+ // throw is invisible to structured consumers; the event is what the UI
2662
+ // host, printers, exporters, and incident capture render). Used by the
2663
+ // recovery `halt`/`fail` arms, the §7.1 sub-agent escalation path in
2664
+ // `NeedTools`, and (G10) the wall-clock timeout stops — including the REPL
2665
+ // deadline-at-prompt path, which is why this lives at run scope rather
2666
+ // than inside `runOneTurn`.
2667
+ const publishRunFailed = async (report) => {
2668
+ const failureMessage = `${report.title}: ${report.detail}`;
2669
+ bus.publish({
2670
+ ...bus.envelope(),
2671
+ kind: "run_failed",
2672
+ class: report.class,
2673
+ message: failureMessage,
2674
+ ...(report.remediation !== undefined ? { remediation: report.remediation } : {}),
2675
+ exitCode: report.exitCode,
2676
+ });
2677
+ await logEvent("run_failed", {
2678
+ class: report.class,
2679
+ message: failureMessage,
2680
+ ...(report.remediation !== undefined ? { remediation: report.remediation } : {}),
2681
+ exitCode: report.exitCode,
2682
+ });
2683
+ };
2684
+ /**
2685
+ * G10 — convert a fired wall-clock limit into the classified terminal
2686
+ * stop: publish + log the `run_failed` report (class `"timeout"`), then
2687
+ * throw the matching `RunFailedError`. Callers invoke this only on the
2688
+ * paths where a timeout IS terminal (any scope in `singleTurn` mode; the
2689
+ * run deadline everywhere).
2690
+ */
2691
+ const throwTimeout = async (timeout) => {
2692
+ const report = buildTimeoutFailureReport(timeout);
2693
+ await publishRunFailed(report);
2694
+ throw new RunFailedError(report);
2695
+ };
2124
2696
  async function runOneTurn(messages) {
2125
2697
  let state = initialState;
2126
2698
  let terminalContent = [];
2699
+ // G02 — aggregate token usage across every MAIN-turn model call this
2700
+ // turn makes (each tool iteration streams once). Handed to the in-loop
2701
+ // evaluator so a judge can weigh cost/verbosity; side-calls (compaction,
2702
+ // the injected judge itself) publish no accumulation here.
2703
+ const turnUsage = {
2704
+ input: 0,
2705
+ output: 0,
2706
+ cacheRead: 0,
2707
+ cacheCreate: 0,
2708
+ };
2709
+ const accrueTurnUsage = (u) => {
2710
+ turnUsage.input += u.input;
2711
+ turnUsage.output += u.output;
2712
+ turnUsage.cacheRead += u.cacheRead ?? 0;
2713
+ turnUsage.cacheCreate += u.cacheCreate ?? 0;
2714
+ };
2127
2715
  let recovery = initialRecoveryState;
2128
2716
  const maxToolIterations = opts.maxToolIterations ?? DEFAULT_MAX_TOOL_ITERATIONS;
2129
2717
  let toolIterations = 0;
@@ -2139,29 +2727,6 @@ export async function runChatLoop(opts) {
2139
2727
  // strongest candidate for the rest of the run (misroute recovery, mirroring
2140
2728
  // the tier router's fast→default escalation latch).
2141
2729
  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
2730
  while (state.kind !== "Done") {
2166
2731
  if (turnAbort.signal.aborted) {
2167
2732
  state = transition(state, { kind: "Aborted" });
@@ -2241,7 +2806,7 @@ export async function runChatLoop(opts) {
2241
2806
  // two are mutually exclusive in the spec).
2242
2807
  if (poolRouter !== undefined) {
2243
2808
  const base = poolRouter.route({
2244
- contextTokens: estimateTokens(messages),
2809
+ contextTokens: contextTokenSignal(messages),
2245
2810
  toolsInPlay: (anthropicTools?.length ?? 0) > 0,
2246
2811
  turnIndex: Math.max(0, runContext.turnNumber - 1),
2247
2812
  priorTurnToolUseCount,
@@ -2301,7 +2866,7 @@ export async function runChatLoop(opts) {
2301
2866
  const decision = escalateTier
2302
2867
  ? { tier: "default", reason: "escalated after fast-tier failure" }
2303
2868
  : tierRouter.route({
2304
- contextTokens: estimateTokens(messages),
2869
+ contextTokens: contextTokenSignal(messages),
2305
2870
  toolsInPlay: (anthropicTools?.length ?? 0) > 0,
2306
2871
  // `turnNumber` is 1-based (incremented before the turn
2307
2872
  // runs); the router wants a 0-based index so its
@@ -2360,6 +2925,19 @@ export async function runChatLoop(opts) {
2360
2925
  // `[]` when the seam is absent — the request payload is then
2361
2926
  // byte-identical to a pre-0.3.0 runtime.
2362
2927
  const continuityTail = await buildContinuityTail();
2928
+ // G10 — arm the per-model-call watchdog for exactly the stream's
2929
+ // lifetime: cleared right after each drain below and (throw
2930
+ // paths) at the top of the catch. G01 — every MAIN-turn request
2931
+ // (and only these: compaction/judge side-calls build their own
2932
+ // requests) carries the resolved thinking fields, and the token
2933
+ // ceiling is the thinking-aware `effectiveMaxTokens`.
2934
+ armModelCallTimer();
2935
+ // Item 9 / G79 — cache the settled transcript prefix when the
2936
+ // serving adapter supports explicit caching. A request-local copy;
2937
+ // the persisted `messages` array never carries the marker.
2938
+ const reqMessages = turnAdapter.features.caching === "explicit"
2939
+ ? withMessageCacheBreakpoint(messages)
2940
+ : messages;
2363
2941
  const reqStream = turnAdapter.stream({
2364
2942
  model: reqWireModelId,
2365
2943
  system: [
@@ -2368,9 +2946,13 @@ export async function runChatLoop(opts) {
2368
2946
  text: b.text,
2369
2947
  ...(b.cache_control !== undefined ? { cache_control: b.cache_control } : {}),
2370
2948
  })),
2949
+ // Item 2 / G21 — the volatile recalled-memory block: rebuilt
2950
+ // per-turn in per-turn recall mode, NO cache marker, sits in
2951
+ // the mutable tail so a swap never busts the frozen prefix.
2952
+ ...volatileRecallBlocks.map((b) => ({ type: "text", text: b.text })),
2371
2953
  ...continuityTail.map((b) => ({ type: "text", text: b.text })),
2372
2954
  ],
2373
- messages: messages,
2955
+ messages: reqMessages,
2374
2956
  tools: anthropicTools !== undefined
2375
2957
  ? anthropicTools.map((t) => ({
2376
2958
  name: t.name,
@@ -2378,7 +2960,8 @@ export async function runChatLoop(opts) {
2378
2960
  input_schema: t.input_schema,
2379
2961
  }))
2380
2962
  : undefined,
2381
- maxTokens,
2963
+ maxTokens: effectiveMaxTokens,
2964
+ ...(thinkingRequest !== undefined ? thinkingRequest : {}),
2382
2965
  signal: turnAbort.signal,
2383
2966
  });
2384
2967
  if (opts.streaming) {
@@ -2412,7 +2995,9 @@ export async function runChatLoop(opts) {
2412
2995
  runContext.logger.debug("streaming-tool", { ...e });
2413
2996
  },
2414
2997
  });
2998
+ clearModelCallTimer();
2415
2999
  endTurn();
3000
+ accrueTurnUsage(usage);
2416
3001
  // On `stop_reason: "max_tokens"` the model may have been cut off
2417
3002
  // mid-`tool_use`; the streaming executor only runs a call once its
2418
3003
  // input JSON closes, so a truncated call has no `tool_result`.
@@ -2460,6 +3045,15 @@ export async function runChatLoop(opts) {
2460
3045
  usage,
2461
3046
  durationMs: performance.now() - t0Model,
2462
3047
  });
3048
+ // Item 4 / G28 — record the provider's real input_tokens for the
3049
+ // next pre-turn compaction trigger + routing signal. A response
3050
+ // that reports NO usage (sum 0) means "unknown", not "empty":
3051
+ // keep the last known count (undefined pre-first-call) so both the
3052
+ // trigger and the router fall back to the chars/4 estimate instead
3053
+ // of reading the context as empty and silently disabling compaction.
3054
+ const reportedInputTokens = responseInputTokens(usage);
3055
+ if (reportedInputTokens > 0)
3056
+ lastModelInputTokens = reportedInputTokens;
2463
3057
  // Adaptive model routing — fold this successful turn into the
2464
3058
  // reward scoreboard so the learned policy improves next run.
2465
3059
  if (poolTurn !== undefined) {
@@ -2486,21 +3080,31 @@ export async function runChatLoop(opts) {
2486
3080
  }
2487
3081
  messages.push({ role: "user", content: [...toolResults] });
2488
3082
  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 });
3083
+ const loopOutcome = evaluateToolLoop();
3084
+ if (loopOutcome.kind === "message") {
3085
+ messages.push(loopOutcome.message);
3086
+ await logEvent("user_message", {
3087
+ content: loopOutcome.message.content,
3088
+ synthetic: true,
3089
+ });
2493
3090
  }
2494
3091
  // Synthesize the two transitions the state machine expects:
2495
3092
  // tools have already executed during the stream so we
2496
3093
  // collapse ModelReturnedToolUse → ToolsExecuted into a
2497
- // single hop back to NeedModel.
3094
+ // single hop back to NeedModel. (G27: on an `abort` loop
3095
+ // escalation the second hop is the Aborted transition — the
3096
+ // NeedTools state accepts it — ending the turn instead.)
2498
3097
  const tsmBlocks = toolUses.map((t) => ({
2499
3098
  id: t.id,
2500
3099
  name: t.name,
2501
3100
  input: t.input,
2502
3101
  }));
2503
3102
  state = transition(state, { kind: "ModelReturnedToolUse", toolUses: tsmBlocks });
3103
+ if (loopOutcome.kind === "abort") {
3104
+ await recordLoopAbort(loopOutcome.detection);
3105
+ state = transition(state, { kind: "Aborted" });
3106
+ break;
3107
+ }
2504
3108
  state = transition(state, { kind: "ToolsExecuted" });
2505
3109
  break;
2506
3110
  }
@@ -2517,7 +3121,9 @@ export async function runChatLoop(opts) {
2517
3121
  }, { ephemeral: true });
2518
3122
  },
2519
3123
  });
3124
+ clearModelCallTimer();
2520
3125
  endTurn();
3126
+ accrueTurnUsage(final.usage);
2521
3127
  // Item 22 — lastServed() is exact: the candidate that actually
2522
3128
  // streamed this response. Cost-tracker prices off this pair.
2523
3129
  const servedCandidate = failoverChain?.lastServed();
@@ -2540,6 +3146,15 @@ export async function runChatLoop(opts) {
2540
3146
  usage: final.usage,
2541
3147
  durationMs: performance.now() - t0Model,
2542
3148
  });
3149
+ // Item 4 / G28 — record the provider's real input_tokens for the
3150
+ // next pre-turn compaction trigger + routing signal. A response that
3151
+ // reports NO usage (sum 0) means "unknown", not "empty": keep the
3152
+ // last known count (undefined pre-first-call) so both the trigger and
3153
+ // the router fall back to the chars/4 estimate instead of reading the
3154
+ // context as empty and silently disabling compaction.
3155
+ const reportedInputTokens = responseInputTokens(final.usage);
3156
+ if (reportedInputTokens > 0)
3157
+ lastModelInputTokens = reportedInputTokens;
2543
3158
  // Adaptive model routing — fold this successful turn into the
2544
3159
  // reward scoreboard so the learned policy improves next run.
2545
3160
  if (poolTurn !== undefined) {
@@ -2608,10 +3223,23 @@ export async function runChatLoop(opts) {
2608
3223
  }));
2609
3224
  for (const tu of tsmBlocks)
2610
3225
  toolUseHistory.push(tu);
3226
+ // Item 7 — the response fully drained (usage known) before these
3227
+ // calls dispatch in `NeedTools`, so the split IS computable here:
3228
+ // split the priceable response cost evenly across its tool_use
3229
+ // blocks, keyed by id for `executeOneToolUse` to stamp. Skipped
3230
+ // (no attribution) when the model isn't on the pricing table.
3231
+ const respCost = responseCostMicros(respProvider, respWireModelId, final.usage);
3232
+ if (respCost !== undefined) {
3233
+ const perTool = Math.round(respCost / toolUses.length);
3234
+ for (const tu of tsmBlocks)
3235
+ toolCostAttribution.set(tu.id, perTool);
3236
+ }
2611
3237
  state = transition(state, { kind: "ModelReturnedToolUse", toolUses: tsmBlocks });
2612
3238
  }
2613
3239
  }
2614
3240
  catch (err) {
3241
+ // G10 — the watchdog must not outlive the call it watched.
3242
+ clearModelCallTimer();
2615
3243
  // Tear down the "thinking" animation before any error/abort output.
2616
3244
  out.spinner.stop();
2617
3245
  if (isAbortError(err)) {
@@ -2692,10 +3320,20 @@ export async function runChatLoop(opts) {
2692
3320
  }
2693
3321
  messages.push({ role: "user", content: toolResults });
2694
3322
  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 });
3323
+ const loopOutcome = evaluateToolLoop();
3324
+ if (loopOutcome.kind === "message") {
3325
+ messages.push(loopOutcome.message);
3326
+ await logEvent("user_message", {
3327
+ content: loopOutcome.message.content,
3328
+ synthetic: true,
3329
+ });
3330
+ }
3331
+ else if (loopOutcome.kind === "abort") {
3332
+ // G27 escalation "abort" — the warned signature tripped again:
3333
+ // end the TURN, ToolLoopLimit-style (see recordLoopAbort).
3334
+ await recordLoopAbort(loopOutcome.detection);
3335
+ state = transition(state, { kind: "Aborted" });
3336
+ break;
2699
3337
  }
2700
3338
  state = transition(state, { kind: "ToolsExecuted" });
2701
3339
  break;
@@ -2887,7 +3525,135 @@ export async function runChatLoop(opts) {
2887
3525
  // Item 26 — hand this turn's tool_use count to the next turn's tier
2888
3526
  // decision (the prior-tool-density signal).
2889
3527
  priorTurnToolUseCount = thisTurnToolUseCount;
2890
- return { terminalContent };
3528
+ // G10 — the turn wound down through the Aborted transition; if a
3529
+ // wall-clock timer (not a SIGINT) is what aborted it, classify the stop.
3530
+ // The abort tree propagates reasons parent→child, so a run-deadline
3531
+ // reason is readable off the TURN signal too; checking both covers the
3532
+ // window where the deadline fires between turns. Terminal when the
3533
+ // deadline fired (any mode) or in `singleTurn` mode (the turn IS the
3534
+ // run); in REPL mode a turn/model-call timeout already printed its
3535
+ // notice at fire time — record the named error and hand control back to
3536
+ // the prompt, mirroring the first-SIGINT semantics.
3537
+ const timedOut = timeoutAbortReason(turnAbort.signal) ?? timeoutAbortReason(runAbort.signal);
3538
+ if (timedOut !== undefined) {
3539
+ if (timedOut.crewhausTimeout === "run" || opts.singleTurn === true) {
3540
+ await throwTimeout(timedOut);
3541
+ }
3542
+ await logEvent("error", {
3543
+ name: timedOut.crewhausTimeout === "turn" ? "TurnTimeout" : "ModelCallTimeout",
3544
+ message: `turn aborted: the configured ${TIMEOUT_SPEC_KEYS[timedOut.crewhausTimeout]} (${timedOut.limitMs}ms) elapsed`,
3545
+ });
3546
+ }
3547
+ return { terminalContent, usage: turnUsage };
3548
+ }
3549
+ /** Concatenated text of a terminal content-block array (the same
3550
+ * projection the `singleTurn` return value uses). */
3551
+ const terminalText = (blocks) => blocks
3552
+ .filter((b) => b.type === "text")
3553
+ .map((b) => b.text)
3554
+ .join("");
3555
+ /**
3556
+ * G02 — one COMPLETED turn plus its in-loop evaluation gate. Wraps
3557
+ * `runOneTurn` so evaluation fires only at turn completion (the tool
3558
+ * inner-loop lives INSIDE `runOneTurn`, so tool-only intermediate
3559
+ * iterations can never reach the grader by construction), on both the
3560
+ * `singleTurn` and REPL paths. Without `opts.evaluation` this is exactly
3561
+ * `runOneTurn` — zero behaviour change.
3562
+ *
3563
+ * The retry ladder: grade attempt 0 (`retryIndex` 0); a failing verdict
3564
+ * with `onFail: "retry"` appends the grader rationale as a synthetic
3565
+ * corrective user message and re-runs the turn, re-grading each re-run
3566
+ * (`retryIndex` n) up to `maxRetries`. Every re-run streams real model
3567
+ * calls through the normal `NeedModel` path, so its spend is metered by
3568
+ * the always-on budget cost path exactly like any other call. `halt`
3569
+ * publishes + logs the classified `run_failed` (class `"evaluation"`)
3570
+ * and throws; `note` and an exhausted retry cap leave the last attempt
3571
+ * standing. An ABORTED (SIGINT / wall-clock) attempt never completed —
3572
+ * it is returned un-graded.
3573
+ */
3574
+ async function runEvaluatedTurn(messages) {
3575
+ const evaluation = opts.evaluation;
3576
+ let attempt = await runOneTurn(messages);
3577
+ if (evaluation === undefined)
3578
+ return attempt;
3579
+ const maxRetries = Math.max(0, Math.floor(evaluation.maxRetries));
3580
+ for (let retryIndex = 0;; retryIndex += 1) {
3581
+ // A turn the abort tree stopped (SIGINT, turn/model-call/run timer)
3582
+ // did not COMPLETE — grading its partial output would be noise, and
3583
+ // a retry would fight the very signal that stopped it.
3584
+ if (turnAbort.signal.aborted || runAbort.signal.aborted)
3585
+ return attempt;
3586
+ let graded;
3587
+ out.spinner.start("evaluating");
3588
+ try {
3589
+ graded = await evaluation.evaluate({
3590
+ finalText: terminalText(attempt.terminalContent),
3591
+ messages,
3592
+ usage: attempt.usage,
3593
+ });
3594
+ }
3595
+ catch (err) {
3596
+ // Grading INFRASTRUCTURE failure (judge model down, evaluator bug)
3597
+ // is not a verdict. Fail open: record it and let the turn stand —
3598
+ // a flaky judge must not kill an otherwise healthy run.
3599
+ const errObj = err;
3600
+ const name = typeof errObj.name === "string" ? errObj.name : "EvaluationError";
3601
+ const message = typeof errObj.message === "string" ? errObj.message : String(err);
3602
+ runContext.logger.warn("evaluation: grader threw — turn stands un-graded", {
3603
+ name,
3604
+ message,
3605
+ });
3606
+ await logEvent("error", { name, message: `evaluation grader failed: ${message}` });
3607
+ return attempt;
3608
+ }
3609
+ finally {
3610
+ out.spinner.stop();
3611
+ }
3612
+ // A rogue evaluator returning NaN/±Infinity must not poison the
3613
+ // trace surface; treat non-finite as 0 (an unambiguous fail).
3614
+ const score = Number.isFinite(graded.score) ? graded.score : 0;
3615
+ const rationale = graded.rationale;
3616
+ const verdict = score >= evaluation.threshold ? "pass" : "fail";
3617
+ bus.publish({
3618
+ ...bus.envelope(),
3619
+ kind: "eval_graded",
3620
+ score,
3621
+ threshold: evaluation.threshold,
3622
+ verdict,
3623
+ graderType: evaluation.graderType,
3624
+ retryIndex,
3625
+ // The cap is only knowable HERE. Without it a downstream reader
3626
+ // (`dataset mine`'s eval-fail signal) cannot distinguish a ladder that
3627
+ // was fully spent from one cut short, and over-claims "exhausted".
3628
+ maxRetries,
3629
+ });
3630
+ if (verdict === "pass" || evaluation.onFail === "note")
3631
+ return attempt;
3632
+ const rationaleNote = rationale !== undefined && rationale.trim().length > 0 ? ` — ${rationale.trim()}` : "";
3633
+ if (evaluation.onFail === "halt") {
3634
+ const detail = `the ${evaluation.graderType} grader scored the final answer ${score.toFixed(2)}, below the required ${evaluation.threshold} threshold${rationaleNote}`;
3635
+ const report = {
3636
+ class: "evaluation",
3637
+ title: "in-loop evaluation gate failed",
3638
+ detail,
3639
+ remediation: "improve the agent (instructions/model), lower evaluation.threshold, or soften evaluation.on_fail to retry/note",
3640
+ exitCode: EXIT_CODES.evaluation,
3641
+ };
3642
+ await publishRunFailed(report);
3643
+ throw new RunFailedError(report);
3644
+ }
3645
+ // onFail: "retry" — bounded by the resolved cap; when spent, the last
3646
+ // attempt stands (the failing eval_graded trail tells the story).
3647
+ if (retryIndex >= maxRetries)
3648
+ return attempt;
3649
+ const feedback = rationale !== undefined && rationale.trim().length > 0
3650
+ ? ` Grader feedback: ${rationale.trim()}`
3651
+ : "";
3652
+ 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.`;
3653
+ messages.push({ role: "user", content: correction });
3654
+ await logEvent("user_message", { content: correction, synthetic: true });
3655
+ attempt = await runOneTurn(messages);
3656
+ }
2891
3657
  }
2892
3658
  // Single-shot path used by the workflow target and (Section 12) the
2893
3659
  // channel-bot session router. Runs one user→assistant turn (with the tool
@@ -2938,6 +3704,7 @@ export async function runChatLoop(opts) {
2938
3704
  logger: runContext.logger,
2939
3705
  onEvict: externalizeEvicted,
2940
3706
  getLedgerText: ledgerAnchorText,
3707
+ ...compactionExtras(),
2941
3708
  }, async (info) => {
2942
3709
  await logEvent("compaction", info);
2943
3710
  bus.publish({
@@ -2956,19 +3723,29 @@ export async function runChatLoop(opts) {
2956
3723
  await fireHook("pre-compact", { ...info, phase: "pre-turn" });
2957
3724
  await fireHook("post-compact", { ...info, phase: "pre-turn" });
2958
3725
  });
2959
- const { terminalContent } = await runOneTurn(messages);
3726
+ // Item 2 / G21 — refresh the volatile recalled block against this turn's
3727
+ // latest user message (no-op unless per-turn recall is enabled + due).
3728
+ await maybePerTurnRecall(messages);
3729
+ // G10 — the single turn IS the run: arm the per-turn ceiling around
3730
+ // it (the deadline timer is already live from boot). Fired timers
3731
+ // surface as a classified RunFailedError out of runOneTurn; the
3732
+ // finally below tears every timer down on all paths. (G02 — the
3733
+ // evaluated wrapper re-runs the turn on a failing verdict, all
3734
+ // attempts inside the same armed window: a retried turn is still ONE
3735
+ // turn against `turn_timeout_ms`.)
3736
+ armTurnTimer();
3737
+ const { terminalContent } = await runEvaluatedTurn(messages);
3738
+ clearTurnTimer();
2960
3739
  bus.publish({
2961
3740
  ...bus.envelope(),
2962
3741
  kind: "turn_end",
2963
3742
  turn: runContext.turnNumber,
2964
3743
  durationMs: performance.now() - t0SingleTurn,
2965
3744
  });
2966
- return terminalContent
2967
- .filter((b) => b.type === "text")
2968
- .map((b) => b.text)
2969
- .join("");
3745
+ return terminalText(terminalContent);
2970
3746
  }
2971
3747
  finally {
3748
+ clearAllTimers();
2972
3749
  out.spinner.stop();
2973
3750
  await fireHook("stop", {
2974
3751
  sessionId,
@@ -2986,6 +3763,7 @@ export async function runChatLoop(opts) {
2986
3763
  budgetMeter?.unsubscribe();
2987
3764
  advisorPersist?.unsubscribe();
2988
3765
  mcpStatsPersist?.unsubscribe();
3766
+ watchmeCapture?.unsubscribe();
2989
3767
  printAdvisorDigest(advisorPersist);
2990
3768
  await sessionStore
2991
3769
  .update(sessionId, { lastTurnIndex: runContext.turnNumber })
@@ -3018,6 +3796,18 @@ export async function runChatLoop(opts) {
3018
3796
  const closedSignal = new Promise((resolve) => {
3019
3797
  rl.once("close", () => resolve(STDIN_CLOSED));
3020
3798
  });
3799
+ // G10 — a fired run deadline must also interrupt an IDLE `rl.question`
3800
+ // wait (the loop-top abort check only runs once input arrives), so each
3801
+ // prompt races this alongside the stdin-close sentinel.
3802
+ const RUN_ABORTED = Symbol("run-aborted");
3803
+ const runAbortedSignal = new Promise((resolve) => {
3804
+ if (runAbort.signal.aborted) {
3805
+ resolve(RUN_ABORTED);
3806
+ }
3807
+ else {
3808
+ runAbort.signal.addEventListener("abort", () => resolve(RUN_ABORTED), { once: true });
3809
+ }
3810
+ });
3021
3811
  // Wire the permission-ask prompter once the readline interface exists.
3022
3812
  // Treats a closed stdin as "deny" so a piped non-interactive input does
3023
3813
  // not stall on the approval prompt.
@@ -3076,6 +3866,10 @@ export async function runChatLoop(opts) {
3076
3866
  if (shouldInstallSigint) {
3077
3867
  process.on("SIGINT", sigintHandler);
3078
3868
  }
3869
+ // Item 1 — set once the REPL loop has run to completion without throwing.
3870
+ // The exit rating prompt fires only on such a clean exit: an aborted or
3871
+ // crashed session is not one anyone wants to be asked to rate.
3872
+ let replExitedCleanly = false;
3079
3873
  try {
3080
3874
  while (true) {
3081
3875
  if (runAbort.signal.aborted)
@@ -3085,8 +3879,8 @@ export async function runChatLoop(opts) {
3085
3879
  sigintPresses = 0;
3086
3880
  let userInput;
3087
3881
  try {
3088
- const result = await Promise.race([rl.question("\nyou> "), closedSignal]);
3089
- if (result === STDIN_CLOSED)
3882
+ const result = await Promise.race([rl.question("\nyou> "), closedSignal, runAbortedSignal]);
3883
+ if (result === STDIN_CLOSED || result === RUN_ABORTED)
3090
3884
  break;
3091
3885
  userInput = result.trim();
3092
3886
  }
@@ -3147,7 +3941,7 @@ export async function runChatLoop(opts) {
3147
3941
  turn: runContext.turnNumber,
3148
3942
  messages: messages.length,
3149
3943
  });
3150
- // Pre-turn budget check: snip first (free), then autocompact if still over.
3944
+ // Pre-turn budget check: (curate) → snip → autocompact if still over.
3151
3945
  messages = await maybeCompact({
3152
3946
  messages,
3153
3947
  adapter: compactionAdapter,
@@ -3159,6 +3953,7 @@ export async function runChatLoop(opts) {
3159
3953
  logger: runContext.logger,
3160
3954
  onEvict: externalizeEvicted,
3161
3955
  getLedgerText: ledgerAnchorText,
3956
+ ...compactionExtras(),
3162
3957
  }, async (info) => {
3163
3958
  await logEvent("compaction", info);
3164
3959
  bus.publish({
@@ -3172,8 +3967,22 @@ export async function runChatLoop(opts) {
3172
3967
  await fireHook("pre-compact", { ...info, phase: "pre-turn" });
3173
3968
  await fireHook("post-compact", { ...info, phase: "pre-turn" });
3174
3969
  });
3970
+ // Item 2 / G21 — refresh the volatile recalled block against this turn's
3971
+ // latest user message (no-op unless per-turn recall is enabled + due).
3972
+ await maybePerTurnRecall(messages);
3973
+ // G10 — per-turn wall-clock ceiling: armed for exactly the
3974
+ // `runOneTurn` window, torn down on every exit (finally). A fired
3975
+ // turn/model-call timer aborts the turn and (REPL posture) control
3976
+ // returns to the prompt below — mirroring the first-SIGINT semantics;
3977
+ // a fired run deadline makes `runOneTurn` throw the classified
3978
+ // RunFailedError, which the catch rethrows.
3979
+ armTurnTimer();
3175
3980
  try {
3176
- await runOneTurn(messages);
3981
+ const { terminalContent } = await runEvaluatedTurn(messages);
3982
+ // Item 1 — the exit rating prompt's "worth rating" floor: count only
3983
+ // turns that ended in a real assistant answer.
3984
+ if (terminalText(terminalContent).trim() !== "")
3985
+ assistantAnswers += 1;
3177
3986
  }
3178
3987
  catch (err) {
3179
3988
  // Defensive: tear down any animation a thrown turn left spinning.
@@ -3186,6 +3995,9 @@ export async function runChatLoop(opts) {
3186
3995
  throw err;
3187
3996
  }
3188
3997
  }
3998
+ finally {
3999
+ clearTurnTimer();
4000
+ }
3189
4001
  bus.publish({
3190
4002
  ...bus.envelope(),
3191
4003
  kind: "turn_end",
@@ -3196,8 +4008,21 @@ export async function runChatLoop(opts) {
3196
4008
  turn: runContext.turnNumber,
3197
4009
  });
3198
4010
  }
4011
+ // G10 — the loop exited on an aborted run root: when the RUN DEADLINE
4012
+ // (not a SIGINT/EOF) is what aborted it, the stop is terminal and
4013
+ // classified. Published here — still inside the try, BEFORE the finally
4014
+ // tears the bus subscribers down — then thrown so `crewhaus run`/bundle
4015
+ // wrappers render the report and exit with EXIT_CODES.timeout. (A
4016
+ // deadline that fired MID-turn already threw from inside runOneTurn and
4017
+ // never reaches this check.)
4018
+ const runTimeout = timeoutAbortReason(runAbort.signal);
4019
+ if (runTimeout !== undefined) {
4020
+ await throwTimeout(runTimeout);
4021
+ }
4022
+ replExitedCleanly = !runAbort.signal.aborted;
3199
4023
  }
3200
4024
  finally {
4025
+ clearAllTimers();
3201
4026
  out.spinner.stop();
3202
4027
  await fireHook("stop", {
3203
4028
  sessionId,
@@ -3215,11 +4040,15 @@ export async function runChatLoop(opts) {
3215
4040
  budgetMeter?.unsubscribe();
3216
4041
  advisorPersist?.unsubscribe();
3217
4042
  mcpStatsPersist?.unsubscribe();
4043
+ watchmeCapture?.unsubscribe();
3218
4044
  printAdvisorDigest(advisorPersist);
3219
4045
  if (shouldInstallSigint) {
3220
4046
  process.removeListener("SIGINT", sigintHandler);
3221
4047
  }
3222
4048
  rl.close();
4049
+ // Item 1 — after readline released stdin (the rating read is raw-mode) and
4050
+ // before the event log closes (the rating is appended to this session).
4051
+ await maybeExitRating(replExitedCleanly);
3223
4052
  await sessionStore.update(sessionId, { lastTurnIndex: runContext.turnNumber }).catch((err) => {
3224
4053
  runContext.logger.warn("session-store: lastTurnIndex update failed", {
3225
4054
  error: err.message,
@@ -3250,6 +4079,272 @@ function isAbortError(err) {
3250
4079
  const name = err.name;
3251
4080
  return typeof name === "string" && (name === "AbortError" || name === "APIUserAbortError");
3252
4081
  }
4082
+ // ---------------------------------------------------------------------------
4083
+ // Loop contract 0.4 (Batch E) — shared helpers for active-context curation
4084
+ // (Item 1 / G19), per-turn recall (Item 2 / G21) and message-level cache
4085
+ // breakpoints (Item 9 / G79).
4086
+ // ---------------------------------------------------------------------------
4087
+ /** Item 4 / G28 — the provider's real INPUT token count for one response:
4088
+ * fresh input + cache-read + cache-create (the whole prompt the provider
4089
+ * counted), the accurate context-size signal chars/4 approximates. */
4090
+ function responseInputTokens(u) {
4091
+ return u.input + (u.cacheRead ?? 0) + (u.cacheCreate ?? 0);
4092
+ }
4093
+ /**
4094
+ * The latest USER *text* message — the relevance query for the curator
4095
+ * (Item 1) and the per-turn recall refresh (Item 2). Tool-result user
4096
+ * messages carry no human words, so they're skipped: the query is what the
4097
+ * person actually said, not a tool payload. Returns `undefined` when no
4098
+ * text-bearing user message exists (a bare tool-result tail).
4099
+ */
4100
+ function latestUserText(messages) {
4101
+ for (let i = messages.length - 1; i >= 0; i--) {
4102
+ const m = messages[i];
4103
+ if (m === undefined || m.role !== "user")
4104
+ continue;
4105
+ if (typeof m.content === "string") {
4106
+ if (m.content.length > 0)
4107
+ return m.content;
4108
+ continue;
4109
+ }
4110
+ const text = m.content
4111
+ .filter((b) => b.type === "text")
4112
+ .map((b) => b.text)
4113
+ .join("\n");
4114
+ if (text.length > 0)
4115
+ return text;
4116
+ }
4117
+ return undefined;
4118
+ }
4119
+ /**
4120
+ * Item 1 / G19 — a message is CURATABLE (safe for the curator to drop) only
4121
+ * when it is pure conversational text: no `tool_use` / `tool_result` blocks,
4122
+ * whose pairing the Anthropic API enforces (a dropped half orphans the other
4123
+ * and 400s the request). Removing a pure-text message can never orphan a pair
4124
+ * — consecutive same-role messages are merged server-side, exactly the
4125
+ * tolerance the snip marker path already relies on.
4126
+ */
4127
+ function isCuratableMessage(m) {
4128
+ const c = m.content;
4129
+ if (typeof c === "string")
4130
+ return true;
4131
+ for (const b of c) {
4132
+ if (b.type === "tool_use" || b.type === "tool_result")
4133
+ return false;
4134
+ }
4135
+ return true;
4136
+ }
4137
+ /** Item 1 / G19 — flatten a message's text for curator similarity + the
4138
+ * `bytesSaved` accounting. Non-text blocks contribute nothing (they never
4139
+ * reach the curator — only pure-text messages are curatable). */
4140
+ function curatorItemText(m) {
4141
+ const c = m.content;
4142
+ if (typeof c === "string")
4143
+ return c;
4144
+ return c
4145
+ .filter((b) => b.type === "text")
4146
+ .map((b) => b.text)
4147
+ .join("\n");
4148
+ }
4149
+ const LEXICAL_TOKEN_RE = /[a-z0-9]+/gi;
4150
+ /** Item 1 / G19 — token set for the BM25-family lexical fallback. */
4151
+ function lexicalTokens(text) {
4152
+ const out = new Set();
4153
+ const matches = text.toLowerCase().match(LEXICAL_TOKEN_RE);
4154
+ if (matches !== null)
4155
+ for (const t of matches)
4156
+ out.add(t);
4157
+ return out;
4158
+ }
4159
+ /** Jaccard overlap of two token sets (the lexical similarity used by the
4160
+ * no-embedder curation path). Two empty sets are identical (1). */
4161
+ function jaccard(a, b) {
4162
+ if (a.size === 0 && b.size === 0)
4163
+ return 1;
4164
+ if (a.size === 0 || b.size === 0)
4165
+ return 0;
4166
+ const [small, large] = a.size <= b.size ? [a, b] : [b, a];
4167
+ let inter = 0;
4168
+ for (const t of small)
4169
+ if (large.has(t))
4170
+ inter++;
4171
+ const union = a.size + b.size - inter;
4172
+ return union === 0 ? 0 : inter / union;
4173
+ }
4174
+ /**
4175
+ * Item 1 / G19 — order-preserving lexical dedupe, the BM25-family fallback
4176
+ * when no embedder resolves (a vector store is unavailable). Mirrors the
4177
+ * curator's cosine `dedupeBySimilarity` structure but over token-set Jaccard:
4178
+ * an item is dropped when a PRIOR kept item's Jaccard >= threshold, so the
4179
+ * first occurrence (the head of the conversation, which carries goal-setting
4180
+ * context) always wins.
4181
+ */
4182
+ function lexicalDedupe(texts, threshold) {
4183
+ const tokenSets = texts.map(lexicalTokens);
4184
+ const kept = [];
4185
+ const dropped = [];
4186
+ for (let i = 0; i < texts.length; i++) {
4187
+ let isDuplicate = false;
4188
+ const ti = tokenSets[i];
4189
+ if (ti !== undefined) {
4190
+ for (const k of kept) {
4191
+ const tk = tokenSets[k];
4192
+ if (tk !== undefined && jaccard(ti, tk) >= threshold) {
4193
+ isDuplicate = true;
4194
+ break;
4195
+ }
4196
+ }
4197
+ }
4198
+ (isDuplicate ? dropped : kept).push(i);
4199
+ }
4200
+ return { kept, dropped };
4201
+ }
4202
+ /**
4203
+ * Item 1 / G19 — the active-context curation pass. Runs `curate()` (cosine,
4204
+ * when an embedder is injected) or the lexical fallback over the CURATABLE
4205
+ * middle messages (pure-text, outside the snip-protected head/tail), then
4206
+ * REBUILDS the transcript keeping survivors in their original order. The
4207
+ * curator's relevance ranking is used only to SELECT which messages survive a
4208
+ * `relevanceTopK` trim — never to reorder the conversation, which would
4209
+ * scramble role alternation and tool pairing. Returns `null` when nothing was
4210
+ * eligible or nothing changed, so the caller skips the trace event. Best-
4211
+ * effort at the call site: an embedder throw propagates and the caller
4212
+ * degrades to the plain snip→autocompact ladder.
4213
+ */
4214
+ async function curateActiveContext(messages, snipKeepHead, snipKeepTail, cfg) {
4215
+ const firstCuratable = Math.max(0, snipKeepHead);
4216
+ const lastCuratable = messages.length - Math.max(0, snipKeepTail);
4217
+ const curatableIdx = [];
4218
+ for (let i = firstCuratable; i < lastCuratable; i++) {
4219
+ const m = messages[i];
4220
+ if (m !== undefined && isCuratableMessage(m))
4221
+ curatableIdx.push(i);
4222
+ }
4223
+ // Need at least two comparable items for a dedupe/relevance decision.
4224
+ if (curatableIdx.length < 2)
4225
+ return null;
4226
+ const texts = curatableIdx.map((i) => curatorItemText(messages[i]));
4227
+ const threshold = cfg.dedupeThreshold ?? DEFAULT_DEDUPE_THRESHOLD;
4228
+ const query = latestUserText(messages);
4229
+ const embedded = cfg.embedder !== undefined;
4230
+ // `keepLocal` — indices INTO `curatableIdx`/`texts` that survive, ascending
4231
+ // (transcript order).
4232
+ let keepLocal;
4233
+ if (embedded) {
4234
+ const items = texts.map((t) => ({ text: t }));
4235
+ const result = await curateItems(items, {
4236
+ dedupeThreshold: threshold,
4237
+ embedder: cfg.embedder,
4238
+ // A query only matters for the topK trim — the relevance re-order is
4239
+ // undone by the re-sort below. Skip it (and its embedder call) unless a
4240
+ // topK cap is actually set.
4241
+ ...(cfg.relevanceTopK !== undefined && query !== undefined
4242
+ ? { query, relevanceTopK: cfg.relevanceTopK }
4243
+ : {}),
4244
+ });
4245
+ keepLocal = [...result.originalIndices].sort((a, b) => a - b);
4246
+ }
4247
+ else {
4248
+ const { kept } = lexicalDedupe(texts, threshold);
4249
+ let survivors = kept;
4250
+ if (cfg.relevanceTopK !== undefined &&
4251
+ query !== undefined &&
4252
+ survivors.length > cfg.relevanceTopK) {
4253
+ const q = lexicalTokens(query);
4254
+ survivors = [...survivors]
4255
+ .sort((a, b) => {
4256
+ const sa = jaccard(q, lexicalTokens(texts[a] ?? ""));
4257
+ const sb = jaccard(q, lexicalTokens(texts[b] ?? ""));
4258
+ if (sa !== sb)
4259
+ return sb - sa;
4260
+ return a - b;
4261
+ })
4262
+ .slice(0, cfg.relevanceTopK)
4263
+ .sort((a, b) => a - b);
4264
+ }
4265
+ keepLocal = survivors;
4266
+ }
4267
+ const before = curatableIdx.length;
4268
+ const after = keepLocal.length;
4269
+ if (after >= before)
4270
+ return null; // dedupe + topK dropped nothing
4271
+ const textByGlobal = new Map();
4272
+ curatableIdx.forEach((g, l) => textByGlobal.set(g, texts[l]));
4273
+ const keepGlobal = new Set(keepLocal.map((l) => curatableIdx[l]));
4274
+ const curatableSet = new Set(curatableIdx);
4275
+ const out = [];
4276
+ let bytesSaved = 0;
4277
+ for (let i = 0; i < messages.length; i++) {
4278
+ if (curatableSet.has(i) && !keepGlobal.has(i)) {
4279
+ bytesSaved += Buffer.byteLength(textByGlobal.get(i) ?? "", "utf8");
4280
+ continue; // curated away
4281
+ }
4282
+ out.push(messages[i]);
4283
+ }
4284
+ return { messages: out, before, after, dropped: before - after, bytesSaved, embedded };
4285
+ }
4286
+ /**
4287
+ * Item 2 / G21 — render the recalled-memory system block body with the SAME
4288
+ * two defenses the session-start recall uses (#53): neutralize any
4289
+ * `</recalled_memory>` breakout delimiter inside a recalled line, and run the
4290
+ * assembled block through `classifyBoundary` with origin `"user"` (recalled
4291
+ * lines may embed content shaped by untrusted tool output in an earlier
4292
+ * session). Returns `undefined` when there is nothing to recall.
4293
+ */
4294
+ async function renderRecalledMemory(lines) {
4295
+ if (lines.length === 0)
4296
+ return undefined;
4297
+ const body = lines.map((l) => `- ${escapeBoundaryDelimiter(l, "recalled_memory")}`).join("\n");
4298
+ const text = `<recalled_memory>\nRelevant facts remembered from earlier sessions:\n${body}\n</recalled_memory>`;
4299
+ await classifyBoundary(text, { origin: "user" }).catch(() => undefined);
4300
+ return text;
4301
+ }
4302
+ /**
4303
+ * Item 9 / G79 — stamp ONE message-level cache breakpoint so the settled
4304
+ * transcript prefix is a cache read on the next call instead of full-price
4305
+ * input every turn/tool-iteration. Marks the last message that carries
4306
+ * ARRAY content (an assistant turn or a tool_result) — never a bare string,
4307
+ * so the freshest user input stays OUTSIDE the cached prefix and a new turn
4308
+ * EXTENDS the cache rather than rebuilding it (Anthropic's recommended
4309
+ * incremental pattern), and string-content messages round-trip untouched.
4310
+ * A request-local copy: the persisted `messages` array never carries a
4311
+ * marker. One breakpoint here plus the single frozen system-prefix marker is
4312
+ * two — well under Anthropic's four. Caller gates on
4313
+ * `adapter.features.caching === "explicit"`.
4314
+ */
4315
+ function withMessageCacheBreakpoint(messages) {
4316
+ let target = -1;
4317
+ for (let i = messages.length - 1; i >= 0; i--) {
4318
+ const c = messages[i]?.content;
4319
+ if (Array.isArray(c) && c.length > 0) {
4320
+ target = i;
4321
+ break;
4322
+ }
4323
+ }
4324
+ if (target === -1)
4325
+ return [...messages];
4326
+ return messages.map((m, i) => (i === target ? stampCacheControlTail(m) : m));
4327
+ }
4328
+ /** Add `cache_control: { type: "ephemeral" }` to the last cache-eligible block
4329
+ * of an ARRAY-content message. Walks back past `thinking`/`redacted_thinking`
4330
+ * blocks (which reject the marker). */
4331
+ function stampCacheControlTail(m) {
4332
+ const content = m.content;
4333
+ if (typeof content === "string" || content.length === 0)
4334
+ return m;
4335
+ let idx = -1;
4336
+ for (let i = content.length - 1; i >= 0; i--) {
4337
+ const t = content[i]?.type;
4338
+ if (t !== "thinking" && t !== "redacted_thinking") {
4339
+ idx = i;
4340
+ break;
4341
+ }
4342
+ }
4343
+ if (idx === -1)
4344
+ return m;
4345
+ const next = content.map((b, i) => i === idx ? { ...b, cache_control: { type: "ephemeral" } } : b);
4346
+ return { ...m, content: next };
4347
+ }
3253
4348
  /** The messages `snip` dropped: input entries absent (by reference — snip
3254
4349
  * copies references) from the output. The inserted marker is a fresh
3255
4350
  * object, so it never shows up as "kept". */
@@ -3263,36 +4358,95 @@ function summaryTextOf(tuple) {
3263
4358
  return summary !== undefined && typeof summary.content === "string" ? summary.content : undefined;
3264
4359
  }
3265
4360
  /**
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.
4361
+ * Pre-turn compaction ladder: (curate) → estimate → snip → re-estimate →
4362
+ * autocompact. Returns the (possibly replaced) messages array. Pure with
4363
+ * respect to the input array; callers reassign. The optional `onCompaction`
4364
+ * callback fires once per applied step so the runtime can append a
4365
+ * `compaction` event to the session log without duplicating the
4366
+ * cost-estimation logic.
4367
+ *
4368
+ * Item 1 / G19 — when `args.curate` is set, the active-context curation pass
4369
+ * runs FIRST (only once the context is already approaching the limit): it
4370
+ * dedupes/relevance-trims the transcript, and when that alone frees enough
4371
+ * headroom the snip→autocompact ladder is skipped entirely (the whole point —
4372
+ * cheap dedupe before an expensive summarizer call). Item 4 / G28 — the
4373
+ * trigger + every re-check use the provider's real `input_tokens`
4374
+ * (`args.realInputTokens`) as the base, calibrating the chars/4 heuristic for
4375
+ * the post-stage deltas; absent (pre-first-call) → the pure heuristic.
3271
4376
  */
3272
4377
  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)) {
4378
+ const { messages, adapter, model, contextLimit, compactionThreshold, snipKeepHead, snipKeepTail, logger, onEvict, getLedgerText, realInputTokens, curate: curateCfg, onCurate, } = args;
4379
+ // Item 4 / G28 — real-token calibration. The initial array's real size is
4380
+ // `realInputTokens` (the provider's count); every later stage subtracts the
4381
+ // ESTIMATED tokens it freed. Pre-first-call (`realInputTokens` undefined) →
4382
+ // the pure chars/4 estimate, byte-identical to the pre-0.4 trigger.
4383
+ const baseEstimate = estimateTokens(messages);
4384
+ const effectiveTokens = (msgs) => {
4385
+ const est = estimateTokens(msgs);
4386
+ if (realInputTokens === undefined)
4387
+ return est;
4388
+ return Math.max(0, realInputTokens - (baseEstimate - est));
4389
+ };
4390
+ const approaching = (msgs) => {
4391
+ const budget = new TokenBudget(contextLimit);
4392
+ budget.add(effectiveTokens(msgs), 0);
4393
+ return budget.isApproachingLimit(compactionThreshold);
4394
+ };
4395
+ if (!approaching(messages)) {
3277
4396
  return messages;
3278
4397
  }
3279
- const snipped = snip(messages, snipKeepHead, snipKeepTail);
4398
+ // Item 1 / G19 — active-context curation pre-pass. Dedupe + relevance-trim
4399
+ // the transcript before the snip→autocompact ladder; if it frees enough,
4400
+ // the ladder (and the summarizer model call) is skipped. Best-effort: an
4401
+ // embedder/curator failure degrades to the plain ladder below.
4402
+ let working = messages;
4403
+ if (curateCfg !== undefined) {
4404
+ try {
4405
+ const outcome = await curateActiveContext(working, snipKeepHead, snipKeepTail, curateCfg);
4406
+ if (outcome !== null) {
4407
+ working = outcome.messages;
4408
+ logger.info("active-context curation applied", {
4409
+ before: outcome.before,
4410
+ after: outcome.after,
4411
+ dropped: outcome.dropped,
4412
+ bytesSaved: outcome.bytesSaved,
4413
+ embedded: outcome.embedded,
4414
+ });
4415
+ if (onCurate !== undefined) {
4416
+ await onCurate({
4417
+ before: outcome.before,
4418
+ after: outcome.after,
4419
+ dropped: outcome.dropped,
4420
+ bytesSaved: outcome.bytesSaved,
4421
+ embedded: outcome.embedded,
4422
+ });
4423
+ }
4424
+ if (!approaching(working)) {
4425
+ return working; // curation alone freed enough — no snip/autocompact
4426
+ }
4427
+ }
4428
+ }
4429
+ catch (err) {
4430
+ logger.warn("active-context curation failed; falling back to snip/autocompact", {
4431
+ error: err.message,
4432
+ });
4433
+ }
4434
+ }
4435
+ const snipped = snip(working, snipKeepHead, snipKeepTail);
3280
4436
  // §2.3 — externalize what snip is about to drop BEFORE the drop commits.
3281
4437
  if (onEvict !== undefined) {
3282
- const evicted = snippedAway(messages, snipped);
4438
+ const evicted = snippedAway(working, snipped);
3283
4439
  if (evicted.length > 0)
3284
4440
  await onEvict(evicted);
3285
4441
  }
3286
- logger.info("snip applied", { before: messages.length, after: snipped.length });
4442
+ logger.info("snip applied", { before: working.length, after: snipped.length });
3287
4443
  if (onCompaction !== undefined) {
3288
- await onCompaction({ kind: "snip", before: messages.length, after: snipped.length });
4444
+ await onCompaction({ kind: "snip", before: working.length, after: snipped.length });
3289
4445
  }
3290
- const postSnipBudget = new TokenBudget(contextLimit);
3291
- postSnipBudget.add(estimateTokens(snipped), 0);
3292
- if (!postSnipBudget.isApproachingLimit(compactionThreshold)) {
4446
+ if (!approaching(snipped)) {
3293
4447
  return snipped;
3294
4448
  }
3295
- logger.info("autocompact triggered", { tokensAfterSnip: postSnipBudget.used });
4449
+ logger.info("autocompact triggered", { tokensAfterSnip: effectiveTokens(snipped) });
3296
4450
  // §2.3 — autocompact replaces the ENTIRE history; externalize all of it
3297
4451
  // before the summarizer model call so the records survive even a
3298
4452
  // summarizer failure. The ledger anchor is read afterwards so this