@crewhaus/runtime-core 0.1.1 → 0.1.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/src/index.ts CHANGED
@@ -13,14 +13,21 @@ import type {
13
13
  SpawnSubAgentFn,
14
14
  SubAgentDefinition,
15
15
  } from "@crewhaus/agent-context-isolation";
16
+ import { setDefaultBoundaryLlmClassifier } from "@crewhaus/boundary-classifier";
16
17
  import { type WrappedAdapter, wrap as wrapWithCircuitBreaker } from "@crewhaus/circuit-breaker";
17
18
  import { autoCompact } from "@crewhaus/compaction-autocompact";
18
19
  import { snip } from "@crewhaus/compaction-snip";
19
- import { type EgressVerdict, classifyEgress, summarizeEgress } from "@crewhaus/egress-classifier";
20
- import { RuntimeError } from "@crewhaus/errors";
20
+ import {
21
+ type EgressMatcher,
22
+ type EgressVerdict,
23
+ type SinkScope,
24
+ classifyEgress,
25
+ summarizeEgress,
26
+ } from "@crewhaus/egress-classifier";
27
+ import { ConfigError, RuntimeError } from "@crewhaus/errors";
21
28
  import { type EventKind, type EventLog, openEventLog } from "@crewhaus/event-log";
22
29
  import { type HookDef, type HookEvent, aggregateDecisions, runHooks } from "@crewhaus/hooks-engine";
23
- import { resolveModel } from "@crewhaus/model-router";
30
+ import { parseModelString, resolveModel } from "@crewhaus/model-router";
24
31
  import {
25
32
  BUILTIN_DEFAULT_RULES,
26
33
  type JustificationJudge,
@@ -50,6 +57,7 @@ import { type SkillRef, formatSkillsForPrompt } from "@crewhaus/skills-registry"
50
57
  import { type SlashCommand, expand as expandSlash } from "@crewhaus/slash-commands";
51
58
  import { type Store, createStore } from "@crewhaus/state-store";
52
59
  import { executeStreaming } from "@crewhaus/streaming-tool-executor";
60
+ import { currentTenantContext } from "@crewhaus/tenancy";
53
61
  import { TokenBudget, estimateTokens } from "@crewhaus/token-budget";
54
62
  import type { RegisteredTool } from "@crewhaus/tool-catalog";
55
63
  import { executeTool } from "@crewhaus/tool-executor";
@@ -141,6 +149,10 @@ import { loadProjectMemory } from "./project-memory";
141
149
  */
142
150
 
143
151
  const DEFAULT_CONTEXT_LIMIT = 200_000;
152
+ // Hard per-turn cap on model→tool cycles. Generous enough that no realistic
153
+ // agentic turn reaches it, low enough to stop a runaway/injected tool loop
154
+ // before it burns a provider quota.
155
+ const DEFAULT_MAX_TOOL_ITERATIONS = 500;
144
156
  const DEFAULT_COMPACTION_THRESHOLD = 0.85;
145
157
  const DEFAULT_SNIP_KEEP_HEAD = 4;
146
158
  const DEFAULT_SNIP_KEEP_TAIL = 20;
@@ -201,6 +213,30 @@ export async function replayMessageHistory(log: EventLog): Promise<Anthropic.Mes
201
213
  return messages;
202
214
  }
203
215
 
216
+ /**
217
+ * Pillar 3 (FR-004) intent gate — the durable audit sink the justification
218
+ * gate appends to. Structurally a subset of `@crewhaus/audit-log`'s
219
+ * `AuditLog` (its `append({ kind, payload })`), declared here as a minimal
220
+ * interface so runtime-core does NOT take a dependency on (or a cycle with)
221
+ * `@crewhaus/audit-log`. The CLI/codegen passes a real `openAuditLog(...)`
222
+ * instance; tests pass an in-memory or tmp-dir-backed one. When omitted (the
223
+ * default for every existing caller), the gate writes nothing durable and the
224
+ * trace-bus `permission_decision` event remains the only surface — i.e. zero
225
+ * behaviour change unless a caller opts in.
226
+ *
227
+ * The `kind` the gate appends is exactly `"permission_justification_evaluated"`,
228
+ * the AuditKind `@crewhaus/audit-log` reserves for this signal; the payload is
229
+ * the documented verbatim shape `{ toolName, justification, verdict, reason,
230
+ * judgeModel, confidence? }` (the justification IS the audit artifact — stored
231
+ * verbatim, never redacted).
232
+ */
233
+ export type JustificationAuditSink = {
234
+ append(input: {
235
+ readonly kind: "permission_justification_evaluated";
236
+ readonly payload: unknown;
237
+ }): Promise<unknown>;
238
+ };
239
+
204
240
  export type RunChatLoopOptions = {
205
241
  model: string;
206
242
  instructions: string;
@@ -374,6 +410,50 @@ export type RunChatLoopOptions = {
374
410
  * against the session goal with model-quality reasoning.
375
411
  */
376
412
  justificationJudge?: JustificationJudge;
413
+ /**
414
+ * Pillar 3 (FR-004) intent gate — durable audit sink. When supplied,
415
+ * every justification-evaluated tool call appends a
416
+ * `permission_justification_evaluated` record (verbatim payload) to this
417
+ * hash-chained sink IN ADDITION to publishing the `permission_decision`
418
+ * trace event. This is the durable, tamper-evident audit artifact the
419
+ * `permission_justification_evaluated` AuditKind was created for; the
420
+ * trace-bus event is ephemeral. Omitting it leaves the trace bus as the
421
+ * only surface (no behaviour change for existing callers). The CLI `run`
422
+ * path wires a real `@crewhaus/audit-log` instance rooted at
423
+ * `.crewhaus/audit`.
424
+ */
425
+ justificationAuditSink?: JustificationAuditSink;
426
+ /**
427
+ * Pillar 3 sink-side fabric (FR-006) — pluggable egress-matching
428
+ * strategy. When supplied, every external-scope tool call routes its
429
+ * payload through this matcher inside `classifyEgress` instead of the
430
+ * built-in `SubstringEgressMatcher`. The matcher only decides *which*
431
+ * tagged data-lineage entries the payload contains; the per-origin/
432
+ * per-sink policy and the three audit outcomes (`egress-passed |
433
+ * egress-warned | egress-blocked`) are unchanged. Omitting it preserves
434
+ * the substring default (zero behaviour change for existing callers).
435
+ * Production deployments that opt into semantic detection pass an
436
+ * instance of `@crewhaus/egress-matcher-semantic`.
437
+ */
438
+ egressMatcher?: EgressMatcher;
439
+ /**
440
+ * Pillar 3 sink-side — classify a tool sink as `"external-configured"` (a
441
+ * spec-declared sink → warn on non-user content) or `"external-dynamic"` (a
442
+ * runtime-joined sink → block on non-user content). Defaults to treating
443
+ * `mcp__*` sinks as dynamic and everything else as configured (#144); wire
444
+ * this to mark federation-joined or other runtime-discovered sinks dynamic.
445
+ */
446
+ resolveSinkScope?: (toolName: string) => SinkScope;
447
+ /**
448
+ * Hard cap on the number of model→tool cycles in a single turn. The loop
449
+ * detector is advisory (it only injects a one-time warning and is defeated
450
+ * by trivial argument churn), so this is the ENFORCING bound: a prompt-
451
+ * injected model steered into an unbounded tool loop is aborted here rather
452
+ * than burning tokens/tool calls until a provider quota or OOM trips.
453
+ * Defaults to `DEFAULT_MAX_TOOL_ITERATIONS`; set higher for genuinely long
454
+ * agentic turns, or lower to tighten.
455
+ */
456
+ maxToolIterations?: number;
377
457
  /**
378
458
  * Section 27 — wrap the resolved primary `ProviderAdapter` in a circuit
379
459
  * breaker before any `stream()` call. When the breaker trips, subsequent
@@ -416,17 +496,119 @@ export type RunChatLoopOptions = {
416
496
  * message history and returns the concatenated text content of the final
417
497
  * assistant message. Does not touch stdin.
418
498
  */
499
+ /**
500
+ * Resolve the root directory for session + event-log persistence (and the
501
+ * sub-agent storage it threads onward).
502
+ *
503
+ * Tenant isolation is MANDATORY at the storage layer, not cooperative: the
504
+ * managed daemon wraps every gateway request in `withTenant(...)`, so when a
505
+ * tenant context is active we use that tenant's path-rebased `sessionRoot`
506
+ * and never fall back to the process-global default — one tenant's prompts
507
+ * and transcripts can no longer land in another tenant's directory (#142).
508
+ *
509
+ * Precedence: an explicit per-call `optsRoot` (set only by trusted callers
510
+ * such as a target emitter or a test) wins; then the active tenant's
511
+ * `sessionRoot`; then `CREWHAUS_SESSION_DIR`; otherwise `undefined` (which
512
+ * lets `session-store` apply its own non-tenant default). The env var and the
513
+ * global default are only consulted OUTSIDE any tenant scope.
514
+ */
515
+ export function resolveSessionRootDir(optsRoot: string | undefined): string | undefined {
516
+ if (optsRoot !== undefined) return optsRoot;
517
+ const tenant = currentTenantContext()?.tenant;
518
+ if (tenant !== undefined) return tenant.sessionRoot;
519
+ return process.env["CREWHAUS_SESSION_DIR"] ?? undefined;
520
+ }
521
+
522
+ /**
523
+ * Tenant-scoped root for the tool-result spill store, mirroring
524
+ * resolveSessionRootDir (#150). Inside a tenant scope the tenant's rebased
525
+ * `toolResultRoot` is used so one tenant's persisted tool outputs never share
526
+ * a directory with another's; otherwise `undefined` lets tool-result-store
527
+ * apply its own non-tenant default.
528
+ */
529
+ export function resolveToolResultRoot(): string | undefined {
530
+ return currentTenantContext()?.tenant.toolResultRoot;
531
+ }
532
+
533
+ /**
534
+ * Sinks whose DESTINATION is chosen at runtime by the (prompt-injectable)
535
+ * model — a fetched/navigated URL, an on-chain recipient — are effectively
536
+ * dynamic even though they are spec-declared built-in tools: an attacker who
537
+ * steers the model picks where the data goes. So non-user cross-origin content
538
+ * reaching them must reach the egress BLOCK tier, not merely warn. Fixed-
539
+ * destination sinks are intentionally NOT here: `SendMessage` replies to the
540
+ * operator-configured channel, `WebSearch`/`ImageGenerate` hit a fixed provider
541
+ * API — classifying those dynamic would block legitimate replies, so they stay
542
+ * `"external-configured"` (warn) and can be tightened per-deployment via the
543
+ * `resolveSinkScope` override or the spec's egress policy.
544
+ */
545
+ const MODEL_DESTINATION_SINKS: ReadonlySet<string> = new Set([
546
+ "Fetch",
547
+ "WebFetch",
548
+ "Navigate",
549
+ "EvmSendTransaction",
550
+ ]);
551
+
552
+ /**
553
+ * Default egress sink-scope. Runtime-joined MCP sinks (`mcp__*`) are the
554
+ * canonical dynamically-discovered external sink, and the model-destination
555
+ * built-ins above are dynamic by virtue of their model-chosen target — both
556
+ * classify as `"external-dynamic"` so the egress block tier is reachable for
557
+ * non-user-origin payloads (#144). Other spec-declared built-in sinks stay
558
+ * `"external-configured"` (warn). Override via `runChatLoop({ resolveSinkScope })`
559
+ * to mark federation-joined or other runtime sinks dynamic too.
560
+ */
561
+ export function defaultSinkScope(toolName: string): SinkScope {
562
+ if (toolName.startsWith("mcp__")) return "external-dynamic";
563
+ if (MODEL_DESTINATION_SINKS.has(toolName)) return "external-dynamic";
564
+ return "external-configured";
565
+ }
566
+
567
+ /**
568
+ * Strip the model-string provider grammar down to the wire model id
569
+ * (`"bedrock/us.anthropic.claude-..."` → `"us.anthropic.claude-..."`)
570
+ * WITHOUT loading the provider package. Used on the `_adapter` injection
571
+ * path where `resolveModel` is bypassed entirely; synthetic ids that
572
+ * don't parse (`"test-model"`) pass through verbatim so existing test
573
+ * stubs keep their ids untouched.
574
+ */
575
+ function bestEffortWireModelId(modelString: string): string {
576
+ try {
577
+ return parseModelString(modelString).modelId;
578
+ } catch {
579
+ return modelString;
580
+ }
581
+ }
582
+
419
583
  export async function runChatLoop(opts: RunChatLoopOptions): Promise<string> {
584
+ // Pillar 3 — make the model-backed Layer-3 classifier reachable at EVERY
585
+ // trust boundary (MCP / sub-agent / channel / federation / skill /
586
+ // compaction / chain / orchestrator). Boundary call sites don't thread an
587
+ // `llmClassifier` through, so we register the runtime's classifier as the
588
+ // process-wide default — gated on the same `llmClassifierEnabled` env switch
589
+ // as the post-tool path. Set-or-clear on each entry keeps boundary behaviour
590
+ // consistent with that gate; idempotent re-registration is a no-op.
591
+ setDefaultBoundaryLlmClassifier(
592
+ opts.promptInjectionLlmClassifier !== undefined && llmClassifierEnabled(process.env)
593
+ ? opts.promptInjectionLlmClassifier
594
+ : undefined,
595
+ );
420
596
  // Section 17 — resolve the primary adapter via the model-router.
421
597
  // The router lazy-loads the matching provider package; an
422
598
  // Anthropic-only spec never pulls AWS / OpenAI / Gemini SDKs.
423
599
  // Section 17 — resolve the primary adapter via the model-router and
424
600
  // capture the *stripped* modelId (the form the provider expects, e.g.
425
601
  // `openai/gpt-4o-mini` → `gpt-4o-mini`). When the caller injects an
426
- // `_adapter`, default to `opts.model` for the wire model id — tests
427
- // typically pass synthetic ids the stub adapter ignores.
602
+ // `_adapter`, still strip any provider prefix grammar (best-effort) so
603
+ // trace events carry the same wire model id either way — but fall back
604
+ // to `opts.model` verbatim for the synthetic ids tests typically pass
605
+ // (`"test-model"`), which the stub adapter ignores.
428
606
  const primaryResolution = opts._adapter
429
- ? { adapter: opts._adapter, modelId: opts.model, providerId: opts._adapter.providerId }
607
+ ? {
608
+ adapter: opts._adapter,
609
+ modelId: bestEffortWireModelId(opts.model),
610
+ providerId: opts._adapter.providerId,
611
+ }
430
612
  : await resolveModel(opts.model);
431
613
  // Section 27 — wrap the primary adapter in a circuit breaker when
432
614
  // `circuitBreaker` opts are set (or by default in production codegen).
@@ -446,6 +628,15 @@ export async function runChatLoop(opts: RunChatLoopOptions): Promise<string> {
446
628
  void breakerWrap; // exposed via runtime stats once gateway/eval consumers land
447
629
  const providerId: ProviderId = primaryResolution.providerId;
448
630
  const wireModelId: string = primaryResolution.modelId;
631
+ // Section 17 — feature gate: a spec that declares tools cannot run on an
632
+ // adapter that doesn't speak tool use (e.g. Bedrock Llama/Mistral
633
+ // families). Fail with a clear ConfigError naming the model instead of
634
+ // letting the provider 400 (or silently drop the tools) mid-run.
635
+ if ((opts.tools ?? []).length > 0 && adapter.features.tool_use === false) {
636
+ throw new ConfigError(
637
+ `model "${opts.model}" (provider ${providerId}) does not support tool use — remove tools or pick a tool-capable model`,
638
+ );
639
+ }
449
640
  let compactionAdapter: ProviderAdapter;
450
641
  let compactionWireModelId: string;
451
642
  if (opts._compactionAdapter !== undefined) {
@@ -488,7 +679,7 @@ export async function runChatLoop(opts: RunChatLoopOptions): Promise<string> {
488
679
  // Persistence boot: session create/resume + event log open. Runs first
489
680
  // so the run context's sessionId — possibly carried over from a prior
490
681
  // run — is the one the rest of the loop logs against.
491
- const sessionRootDir = opts.sessionRootDir ?? process.env["CREWHAUS_SESSION_DIR"] ?? undefined;
682
+ const sessionRootDir = resolveSessionRootDir(opts.sessionRootDir);
492
683
  const sessionStore: SessionStore = createSessionStore({ rootDir: sessionRootDir });
493
684
  // Housekeeping side-effect: evicts any session whose mtime is older than
494
685
  // the TTL (default 30 days). The returned list is intentionally discarded.
@@ -761,7 +952,12 @@ export async function runChatLoop(opts: RunChatLoopOptions): Promise<string> {
761
952
  content:
762
953
  typeof result.content === "string"
763
954
  ? result.content
764
- : summariseNonStringContent(result.content),
955
+ : summariseNonStringContent(
956
+ result.content as Exclude<
957
+ Anthropic.ToolResultBlockParam["content"],
958
+ string | undefined
959
+ >,
960
+ ),
765
961
  isError: result.is_error === true,
766
962
  });
767
963
  const outputContent = result.content;
@@ -890,6 +1086,15 @@ export async function runChatLoop(opts: RunChatLoopOptions): Promise<string> {
890
1086
  decision: verdict.allow ? "allow" : "deny",
891
1087
  mode: permissionMode,
892
1088
  reason: `justification: ${verdict.reason} [judge=${verdict.judgeModel}]`,
1089
+ // FR-004 — promote the judge identity (and confidence) to
1090
+ // first-class fields on the canonical permission_decision event so
1091
+ // the `permission_justification_evaluated` audit story records WHO
1092
+ // judged, not just an embedded substring of `reason`. Absent on
1093
+ // ordinary (non-justification) permission decisions.
1094
+ judgeModel: verdict.judgeModel,
1095
+ ...(verdict.confidence !== undefined
1096
+ ? { justificationConfidence: verdict.confidence }
1097
+ : {}),
893
1098
  });
894
1099
  runContext.logger.info("justification evaluated", {
895
1100
  toolUseId: tu.id,
@@ -898,6 +1103,37 @@ export async function runChatLoop(opts: RunChatLoopOptions): Promise<string> {
898
1103
  judgeModel: verdict.judgeModel,
899
1104
  confidence: verdict.confidence,
900
1105
  });
1106
+ // FR-004 — emit the durable `permission_justification_evaluated` audit
1107
+ // record. The trace event above is ephemeral; THIS is the hash-chained,
1108
+ // tamper-evident artifact the AuditKind was created for. We append one
1109
+ // record per justification-evaluated call (allow OR deny — the audit
1110
+ // trail must capture denials too), storing the justification VERBATIM
1111
+ // alongside the verdict and the judge identity, exactly the payload
1112
+ // shape `@crewhaus/audit-log` documents for this kind. Best-effort but
1113
+ // surfaced: an I/O failure on the audit trail is logged and swallowed so
1114
+ // a full audit disk does not crash a governed run, mirroring how the
1115
+ // egress fabric treats its own audit surface. Absent sink → no-op.
1116
+ if (opts.justificationAuditSink !== undefined) {
1117
+ try {
1118
+ await opts.justificationAuditSink.append({
1119
+ kind: "permission_justification_evaluated",
1120
+ payload: {
1121
+ toolName: tu.name,
1122
+ justification,
1123
+ verdict: verdict.allow ? "allow" : "deny",
1124
+ reason: verdict.reason,
1125
+ judgeModel: verdict.judgeModel,
1126
+ ...(verdict.confidence !== undefined ? { confidence: verdict.confidence } : {}),
1127
+ },
1128
+ });
1129
+ } catch (err) {
1130
+ runContext.logger.warn("justification audit append failed", {
1131
+ toolUseId: tu.id,
1132
+ toolName: tu.name,
1133
+ error: (err as Error).message,
1134
+ });
1135
+ }
1136
+ }
901
1137
  if (!verdict.allow) {
902
1138
  return finish({
903
1139
  type: "tool_result",
@@ -914,16 +1150,22 @@ export async function runChatLoop(opts: RunChatLoopOptions): Promise<string> {
914
1150
  // tagged from a non-`"user"` origin and policy disallows transmission;
915
1151
  // we deny the call before it fires. `warn` logs but proceeds.
916
1152
  //
917
- // The runtime treats every external tool as `"external-configured"`
918
- // (the spec listed it). Dynamically-discovered sinks (an MCP server
919
- // the agent loaded mid-session) should use `"external-dynamic"` to
920
- // get stricter default policy; that wiring lives in `tool-mcp`'s
921
- // dynamic-tool path and is a v0.3.x follow-up.
1153
+ // Resolve the sink-scope so the egress block tier is actually reachable
1154
+ // (#144): runtime-joined MCP sinks default to `"external-dynamic"` (block
1155
+ // non-user-origin content), while spec-declared sinks stay
1156
+ // `"external-configured"` (warn). Callers can override via
1157
+ // `opts.resolveSinkScope` to mark federation-joined or other dynamic sinks.
922
1158
  if (tool.scope === "external") {
923
1159
  const payload = JSON.stringify(tu.input ?? null);
1160
+ const sinkScope = (opts.resolveSinkScope ?? defaultSinkScope)(tu.name);
924
1161
  const egress = await classifyEgress(payload, runContext, {
925
1162
  sinkId: tu.name,
926
- sinkScope: "external-configured",
1163
+ sinkScope,
1164
+ // FR-006: forward the caller-selected matcher when present. Absent
1165
+ // (every existing caller) → classifyEgress defaults to the
1166
+ // substring matcher, so the scope gate / sinkScope / policy fold
1167
+ // below are byte-for-byte unchanged.
1168
+ ...(opts.egressMatcher !== undefined ? { matcher: opts.egressMatcher } : {}),
927
1169
  });
928
1170
  const egressOutcome =
929
1171
  egress.verdict === "pass"
@@ -962,29 +1204,42 @@ export async function runChatLoop(opts: RunChatLoopOptions): Promise<string> {
962
1204
  }
963
1205
 
964
1206
  const toolAbort = turnAbort.child();
965
- // Build the bridge for this call. Skipped (left undefined) when no
966
- // spawnSubAgent injection is provided — non-Task tools don't need it.
967
- const bridge: RuntimeBridge | undefined =
968
- opts.spawnSubAgent !== undefined || opts.crewMailbox !== undefined
969
- ? {
970
- runContext,
971
- eventLog,
972
- permissionMode,
973
- permissionRules,
974
- tools,
975
- model: opts.model,
976
- maxTokens,
977
- ...(sessionRootDir !== undefined ? { sessionRootDir } : {}),
978
- hooks,
979
- ...(opts.subAgents !== undefined ? { subAgents: opts.subAgents } : {}),
980
- ...(opts.spawnSubAgent !== undefined ? { spawnSubAgent: opts.spawnSubAgent } : {}),
981
- ...(opts.crewMailbox !== undefined ? { crewMailbox: opts.crewMailbox } : {}),
982
- }
983
- : undefined;
1207
+ // Build the bridge for this call. Built on EVERY run (#160 follow-up):
1208
+ // it carries `runContext`, which Pillar-3 boundary-site tools (tool-mcp,
1209
+ // skills-registry) read to tag their external content's provenance under
1210
+ // the precise "mcp"/"skill" origin. Previously the bridge was skipped
1211
+ // unless `spawnSubAgent`/`crewMailbox` was injected, so a plain top-level
1212
+ // run gave those tools no RunContext and their content fell back to the
1213
+ // coarse "tool" origin. The Task-tool-only fields (`spawnSubAgent`,
1214
+ // `crewMailbox`, `subAgents`) stay conditional — they're omitted when not
1215
+ // wired, and the Task tool already checks for undefined before using them.
1216
+ const bridge: RuntimeBridge = {
1217
+ runContext,
1218
+ eventLog,
1219
+ permissionMode,
1220
+ permissionRules,
1221
+ tools,
1222
+ model: opts.model,
1223
+ maxTokens,
1224
+ ...(sessionRootDir !== undefined ? { sessionRootDir } : {}),
1225
+ hooks,
1226
+ ...(opts.subAgents !== undefined ? { subAgents: opts.subAgents } : {}),
1227
+ ...(opts.spawnSubAgent !== undefined ? { spawnSubAgent: opts.spawnSubAgent } : {}),
1228
+ ...(opts.crewMailbox !== undefined ? { crewMailbox: opts.crewMailbox } : {}),
1229
+ };
984
1230
  const raw = await executeTool(tool, tu.input, {
985
1231
  toolUseId: tu.id,
986
1232
  signal: toolAbort.signal,
987
- ...(bridge !== undefined ? { bridge } : {}),
1233
+ // #160 follow-up — the bridge (built on every run, above) carries
1234
+ // `runContext`, which boundary-site tools (tool-mcp, skills-registry)
1235
+ // read to tag their external content under the precise "mcp"/"skill"
1236
+ // origin. `tool-executor` forwards `bridge` verbatim; those tools read
1237
+ // `ctx.runContext` first and fall back to `ctx.bridge.runContext`, so
1238
+ // the bridge is what activates the precise tag today. (Threading
1239
+ // `runContext` as a first-class field on this call would also require
1240
+ // adding it to `tool-executor`'s `ExecutionContext`, which is owned
1241
+ // elsewhere; the bridge path needs no such change.)
1242
+ bridge,
988
1243
  // Section 18 — runtime-core wires this so streaming tools
989
1244
  // (`tool-code-execution`) can publish `tool_stream_chunk` events as
990
1245
  // they pipe stdout/stderr from the sandbox container.
@@ -1003,9 +1258,14 @@ export async function runChatLoop(opts: RunChatLoopOptions): Promise<string> {
1003
1258
  );
1004
1259
  },
1005
1260
  });
1261
+ const toolResultRoot = resolveToolResultRoot();
1006
1262
  const stored = await storeAndPreview(
1007
1263
  { toolUseId: raw.toolUseId, content: raw.content, isError: raw.isError },
1008
- { runId: runContext.runId, toolUseId: tu.id },
1264
+ {
1265
+ runId: runContext.runId,
1266
+ toolUseId: tu.id,
1267
+ ...(toolResultRoot !== undefined ? { rootDir: toolResultRoot } : {}),
1268
+ },
1009
1269
  );
1010
1270
  if (stored.persisted) {
1011
1271
  runContext.logger.info("tool result persisted", {
@@ -1020,21 +1280,24 @@ export async function runChatLoop(opts: RunChatLoopOptions): Promise<string> {
1020
1280
  // notice; on suspicious it's kept but the trace event records a
1021
1281
  // warning. Tools opt out by setting `classifyOutput: false` (only the
1022
1282
  // in-process Task wrapper does today).
1023
- const finalPreview = await applyInjectionClassification(
1024
- tool,
1025
- tu,
1026
- stored.previewContent,
1027
- raw.isError,
1028
- );
1283
+ const finalPreview = await applyInjectionClassification(tool, tu, stored.previewContent);
1029
1284
  // Pillar 3 sink-side fabric — tag the (post-classification) tool result
1030
1285
  // into run-context's dataLineage so the egress classifier can detect
1031
1286
  // exfiltration of this content on a subsequent external-tool call.
1032
1287
  // Skipped for the in-process Task wrapper (`classifyOutput: false`)
1033
1288
  // because the sub-agent's finalMessage is already tagged at the
1034
1289
  // sub-agent-spawner boundary with the more-specific "subagent" origin.
1035
- // MCP tools tag separately inside tool-mcp with the "mcp" origin so
1036
- // their lineage carries the more-precise provenance.
1037
- if (tool.classifyOutput !== false && !raw.isError) {
1290
+ // MCP tools additionally tag their FULL response under the more-precise
1291
+ // "mcp" origin inside tool-mcp; since #160 follow-up the runtime threads
1292
+ // a RunContext (via `bridge`/`ctx.runContext`) on EVERY run, so that
1293
+ // precise tag now fires unconditionally. This coarse "tool" tag of the
1294
+ // (possibly truncated) preview still fires for them as a redundant
1295
+ // backstop so the content has lineage even if the precise tag is missed.
1296
+ // ERROR results are tagged too: an `is_error` tool result is just as
1297
+ // attacker-controllable and just as exfiltratable as a successful one, so
1298
+ // it must carry lineage (the `!raw.isError` skip here used to let the
1299
+ // egress fabric lose track of error-sourced content entirely).
1300
+ if (tool.classifyOutput !== false) {
1038
1301
  const taggable =
1039
1302
  typeof finalPreview === "string"
1040
1303
  ? finalPreview
@@ -1070,10 +1333,11 @@ export async function runChatLoop(opts: RunChatLoopOptions): Promise<string> {
1070
1333
  tool: RegisteredTool,
1071
1334
  tu: TsmToolUseBlock,
1072
1335
  previewContent: string | ReadonlyArray<Anthropic.TextBlockParam | Anthropic.ImageBlockParam>,
1073
- isError: boolean,
1074
1336
  ): Promise<string | ReadonlyArray<Anthropic.TextBlockParam | Anthropic.ImageBlockParam>> {
1337
+ // Runs on ALL tool results, including `is_error` ones: an error preview is
1338
+ // just as prompt-injectable as a successful one (e.g. an MCP error string),
1339
+ // so it must be scrubbed before the model sees it.
1075
1340
  if (tool.classifyOutput === false) return previewContent;
1076
- if (isError) return previewContent;
1077
1341
  // Concatenate text-only content for classification. Image blocks are
1078
1342
  // never injection vectors at the byte level we examine here.
1079
1343
  const textForClassification =
@@ -1137,10 +1401,13 @@ export async function runChatLoop(opts: RunChatLoopOptions): Promise<string> {
1137
1401
  * full content still reaches the model via tool_result.content above; the
1138
1402
  * audit log just gets a length-aware tag.
1139
1403
  */
1140
- function summariseNonStringContent(content: Anthropic.ToolResultBlockParam["content"]): string {
1141
- if (content === undefined || typeof content === "string") {
1142
- return content === undefined ? "[no content]" : `[${content.length} chars]`;
1143
- }
1404
+ // Takes the non-string member of ToolResultBlockParam["content"] — the
1405
+ // sole caller (`finish`) only invokes this on the non-string branch of a
1406
+ // `typeof result.content === "string"` ternary, so the string/undefined
1407
+ // case is statically excluded here and no dead guard is needed.
1408
+ function summariseNonStringContent(
1409
+ content: Exclude<Anthropic.ToolResultBlockParam["content"], string | undefined>,
1410
+ ): string {
1144
1411
  let images = 0;
1145
1412
  let texts = 0;
1146
1413
  let other = 0;
@@ -1177,27 +1444,27 @@ export async function runChatLoop(opts: RunChatLoopOptions): Promise<string> {
1177
1444
  concurrent: partition.concurrent.map((b) => b.length),
1178
1445
  serial: partition.serial.length,
1179
1446
  });
1180
- const byId = new Map<string, Anthropic.ToolResultBlockParam>();
1447
+ // Map each tool_use's identity to its slot in the original order so
1448
+ // results can be placed back in order regardless of the
1449
+ // concurrent/serial execution shape. `partitionToolCalls` is total —
1450
+ // every input block lands in exactly one partition bucket — and
1451
+ // `executeOneToolUse` always resolves to a result, so every slot is
1452
+ // filled; there is no missing-result case to defend against.
1453
+ const indexByBlock = new Map<TsmToolUseBlock, number>();
1454
+ toolUses.forEach((tu, idx) => indexByBlock.set(tu, idx));
1455
+ const results = new Array<Anthropic.ToolResultBlockParam>(toolUses.length);
1181
1456
  for (const batch of partition.concurrent) {
1182
1457
  const settled = await Promise.all(batch.map((tu) => executeOneToolUse(tu)));
1183
- for (const r of settled) byId.set(r.tool_use_id, r);
1458
+ batch.forEach((tu, i) => {
1459
+ // biome-ignore lint/style/noNonNullAssertion: every block came from toolUses, so its index is registered.
1460
+ results[indexByBlock.get(tu)!] = settled[i] as Anthropic.ToolResultBlockParam;
1461
+ });
1184
1462
  }
1185
1463
  for (const tu of partition.serial) {
1186
- const r = await executeOneToolUse(tu);
1187
- byId.set(r.tool_use_id, r);
1464
+ // biome-ignore lint/style/noNonNullAssertion: every block came from toolUses, so its index is registered.
1465
+ results[indexByBlock.get(tu)!] = await executeOneToolUse(tu);
1188
1466
  }
1189
- return toolUses.map((tu) => {
1190
- const r = byId.get(tu.id);
1191
- if (r === undefined) {
1192
- return {
1193
- type: "tool_result",
1194
- tool_use_id: tu.id,
1195
- content: "internal error: missing tool result",
1196
- is_error: true,
1197
- };
1198
- }
1199
- return r;
1200
- });
1467
+ return results;
1201
1468
  }
1202
1469
 
1203
1470
  /**
@@ -1234,6 +1501,8 @@ export async function runChatLoop(opts: RunChatLoopOptions): Promise<string> {
1234
1501
  let state: TurnState = initialState;
1235
1502
  let terminalContent: Anthropic.ContentBlock[] = [];
1236
1503
  let recovery: RecoveryState = initialRecoveryState;
1504
+ const maxToolIterations = opts.maxToolIterations ?? DEFAULT_MAX_TOOL_ITERATIONS;
1505
+ let toolIterations = 0;
1237
1506
 
1238
1507
  while (state.kind !== "Done") {
1239
1508
  if (turnAbort.signal.aborted) {
@@ -1276,10 +1545,16 @@ export async function runChatLoop(opts: RunChatLoopOptions): Promise<string> {
1276
1545
  await opts.rateLimiter.acquire(opts.rateLimitKeys, 1);
1277
1546
  }
1278
1547
  const modelStartEnv = bus.envelope();
1548
+ // Section 27 — `model` carries the WIRE model id (the stripped
1549
+ // form the provider bills against, e.g. `bedrock/us.anthropic.…`
1550
+ // → `us.anthropic.…`) so cost-tracker pricing lookups and the
1551
+ // OTel `gen_ai.request.model` attribute match; the original
1552
+ // spec string rides along as `specModel` when it differs.
1279
1553
  bus.publish({
1280
1554
  ...modelStartEnv,
1281
1555
  kind: "model_request",
1282
- model: opts.model,
1556
+ model: wireModelId,
1557
+ ...(opts.model !== wireModelId ? { specModel: opts.model } : {}),
1283
1558
  provider: providerId,
1284
1559
  messageCount: messages.length,
1285
1560
  toolCount: anthropicTools?.length ?? 0,
@@ -1368,7 +1643,10 @@ export async function runChatLoop(opts: RunChatLoopOptions): Promise<string> {
1368
1643
  ...bus.envelope(),
1369
1644
  spanId: modelStartEnv.spanId,
1370
1645
  kind: "model_response",
1371
- model: opts.model,
1646
+ // Wire model id, NOT the spec string — cost-tracker resolves
1647
+ // pricing on this field (see the model_request publish above).
1648
+ model: wireModelId,
1649
+ ...(opts.model !== wireModelId ? { specModel: opts.model } : {}),
1372
1650
  provider: providerId,
1373
1651
  stopReason: stopReason ?? "end_turn",
1374
1652
  usage,
@@ -1434,7 +1712,10 @@ export async function runChatLoop(opts: RunChatLoopOptions): Promise<string> {
1434
1712
  ...bus.envelope(),
1435
1713
  spanId: modelStartEnv.spanId,
1436
1714
  kind: "model_response",
1437
- model: opts.model,
1715
+ // Wire model id, NOT the spec string — cost-tracker resolves
1716
+ // pricing on this field (see the model_request publish above).
1717
+ model: wireModelId,
1718
+ ...(opts.model !== wireModelId ? { specModel: opts.model } : {}),
1438
1719
  provider: providerId,
1439
1720
  stopReason: final.stopReason,
1440
1721
  usage: final.usage,
@@ -1505,6 +1786,21 @@ export async function runChatLoop(opts: RunChatLoopOptions): Promise<string> {
1505
1786
  }
1506
1787
 
1507
1788
  case "NeedTools": {
1789
+ toolIterations += 1;
1790
+ if (toolIterations > maxToolIterations) {
1791
+ // Enforcing loop bound — the advisory loop-detector can't stop a
1792
+ // runaway tool loop (it only warns and is defeated by argument
1793
+ // churn), so fail closed here.
1794
+ await logEvent("error", {
1795
+ name: "ToolLoopLimit",
1796
+ message: `aborting turn: exceeded maxToolIterations (${maxToolIterations}) — possible runaway tool loop`,
1797
+ });
1798
+ runContext.logger.error("tool-iteration cap exceeded — aborting turn", {
1799
+ maxToolIterations,
1800
+ });
1801
+ state = transition(state, { kind: "Aborted" });
1802
+ break;
1803
+ }
1508
1804
  const toolResults = await runToolBatch(state.toolUses);
1509
1805
  messages.push({ role: "user", content: toolResults });
1510
1806
  await logEvent("user_message", { content: toolResults });
@@ -1517,11 +1813,14 @@ export async function runChatLoop(opts: RunChatLoopOptions): Promise<string> {
1517
1813
  break;
1518
1814
  }
1519
1815
 
1520
- case "NeedCompaction":
1521
- // Reserved: pre-turn compaction is run outside the state machine;
1522
- // the recovery branch handles in-turn reactive compaction inline.
1523
- state = transition(state, { kind: "CompactionDone" });
1524
- break;
1816
+ // NOTE: there is no `case "NeedCompaction"` here, and it is
1817
+ // unreachable by construction: the turn-state-machine only enters
1818
+ // `NeedCompaction` on a `BudgetExceeded` event, and this loop never
1819
+ // emits one — pre-turn compaction runs outside the state machine (see
1820
+ // `maybeCompact`) and in-turn reactive compaction is handled inline by
1821
+ // the `compact` recovery action below. If a future change starts
1822
+ // emitting `BudgetExceeded` from `runOneTurn`, restore a
1823
+ // `NeedCompaction` → `CompactionDone` arm (and cover it) here.
1525
1824
 
1526
1825
  case "NeedRecovery": {
1527
1826
  const action = recover(lastErrorForRecovery, recovery);
@@ -1585,10 +1884,13 @@ export async function runChatLoop(opts: RunChatLoopOptions): Promise<string> {
1585
1884
  break;
1586
1885
  }
1587
1886
  case "tombstone": {
1588
- const lastIdx = messages.length - 1;
1589
- if (lastIdx >= 0 && messages[lastIdx]?.role === "assistant") {
1590
- messages.pop();
1591
- }
1887
+ // A tombstone fires on an `invalid_request` from the model call.
1888
+ // The model stream is atomic with respect to history: it either
1889
+ // fully succeeds (pushing exactly one assistant message, after
1890
+ // which the turn transitions to Done/NeedTools — never into
1891
+ // recovery) or it throws before pushing anything. So when we
1892
+ // reach here the tail is never a dangling assistant turn, and
1893
+ // there is nothing to pop — we just append the retry nudge.
1592
1894
  const tombstoneMsg =
1593
1895
  "[previous assistant turn was rejected as invalid; please retry]";
1594
1896
  messages.push({ role: "user", content: tombstoneMsg });