@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.d.ts CHANGED
@@ -1,17 +1,22 @@
1
1
  import type Anthropic from "@anthropic-ai/sdk";
2
2
  import { type ProviderAdapter } from "@crewhaus/adapter-anthropic";
3
3
  import type { CrewMailbox, SpawnSubAgentFn, SubAgentDefinition } from "@crewhaus/agent-context-isolation";
4
+ import { type EmbedderFn } from "@crewhaus/compaction-curator";
4
5
  import { type EgressMatcher, type SinkScope } from "@crewhaus/egress-classifier";
6
+ import { type FailureReport } from "@crewhaus/errors";
5
7
  import { type EventLog } from "@crewhaus/event-log";
6
8
  import { type HookDef } from "@crewhaus/hooks-engine";
7
9
  import { type JustificationJudge, type PermissionMode, type RuleSet } from "@crewhaus/permission-engine";
8
- import type { RateLimiter } from "@crewhaus/rate-limiter";
10
+ import { type RateLimiter } from "@crewhaus/rate-limiter";
9
11
  import { type NamedFailureClass } from "@crewhaus/recovery-engine";
10
12
  import { type Scoreboard } from "@crewhaus/routing-store";
11
13
  import { type RunContext } from "@crewhaus/run-context";
14
+ import { type PendingApproval, type PendingApprovalStore } from "@crewhaus/session-store";
12
15
  import { type SkillRef } from "@crewhaus/skills-registry";
13
16
  import { type SlashCommand } from "@crewhaus/slash-commands";
14
17
  import type { RegisteredTool } from "@crewhaus/tool-catalog";
18
+ import { type ModelUsage } from "@crewhaus/trace-event-bus";
19
+ import { type ExitRatingFeedback } from "./exit-rating";
15
20
  import { type AlertSink } from "./observability";
16
21
  import type { SloMitigationSink, SloTargets } from "./slo-monitor";
17
22
  /**
@@ -112,12 +117,19 @@ export declare function renderContinuityTail(input: {
112
117
  export declare function mapWithConcurrency<T, R>(items: ReadonlyArray<T>, limit: number, fn: (item: T, index: number) => Promise<R>): Promise<R[]>;
113
118
  export { CLAUDE_CODE_HEADERS, CLAUDE_CODE_SYSTEM_PREFIX, OAUTH_BETAS, createAnthropicClient, resolveAuth, } from "@crewhaus/adapter-anthropic";
114
119
  export type { ResolvedAuth } from "@crewhaus/adapter-anthropic";
120
+ export { createInMemoryKV, createNodeWorkerPlatform } from "./worker-platform";
121
+ export { createEdgeAnthropicAdapter, classifyEdgeTool, EDGE_SAFE_TOOLS, HOST_ONLY_TOOLS, isEdgeSafeTool, partitionEdgeTools, runWorkerLoop, } from "@crewhaus/worker-runtime";
122
+ export type { EdgeToolPartition, EdgeToolVerdict, KVLike, RunWorkerLoopOptions, TraceSink as WorkerTraceSink, WorkerLimits, WorkerLoopResult, WorkerPlatform, WorkerStopReason, WorkerThinking, WorkerTraceEvent, } from "@crewhaus/worker-runtime";
115
123
  export { createJanitor } from "./janitor";
116
124
  export { JANITOR_BUILTIN_STEPS } from "./janitor";
117
125
  export type { CreateJanitorOptions, Janitor, JanitorBuiltinStepName, JanitorReservationStore, JanitorRunResult, JanitorStep, JanitorStepName, JanitorStepOutcome, JanitorStepResult, JanitorStepStatus, } from "./janitor";
126
+ export { AGENT_IDENTITY_SCHEMA_VERSION, DEFAULT_IDENTITY_DIR, IDENTITY_FILENAME, agentFingerprint, loadOrCreateAgentIdentity, } from "./identity";
127
+ export type { AgentIdentityFile } from "./identity";
128
+ export { type ApprovalDecision, type PendingApproval, type PendingApprovalStore, type PendingApprovalStoreOptions, createPendingApprovalStore, evictExpiredApprovals, generateApprovalId, hashApprovalInput, } from "@crewhaus/session-store";
118
129
  export { type AlertBreachPayload, type AlertSink, type AttachDefaultSubscribersOptions, attachDefaultSubscribers, } from "./observability";
119
130
  export { type AttachedSloMonitor, type AttachSloMonitorOptions, type SloBreach, type SloMitigationEvent, type SloMitigationRung, type SloMitigationSink, type SloTargets, type SloWindowMetrics, DEFAULT_SLO_WINDOW_MS, MIN_SLO_SAMPLES, SloWindow, attachSloMonitor, detectSloBreaches, } from "./slo-monitor";
120
131
  export { type AttachIncidentCollectorOptions, type IncidentCapture, type IncidentTriggerKind, attachIncidentCollector, classifyIncidentTrigger, } from "./incident-collector";
132
+ export { type ExitRatingChoice, type ExitRatingDecision, type ExitRatingFeedback, type ExitRatingRecord, EXIT_RATING_PROMPT, EXIT_RATING_TIMEOUT_MS, NO_EXIT_RATING_ENV, buildExitRatingRecord, parseExitRatingKey, runExitRating, shouldPromptExitRating, } from "./exit-rating";
121
133
  /**
122
134
  * Reconcile a message history by dropping "orphan" `tool_use` blocks — a
123
135
  * `tool_use` with no answering `tool_result` anywhere later in the
@@ -200,6 +212,71 @@ export type EgressAuditSink = {
200
212
  readonly payload: unknown;
201
213
  }): Promise<unknown>;
202
214
  };
215
+ /**
216
+ * Loop contract 0.4 (G02) — the observable output of ONE completed
217
+ * user→assistant turn, handed to the injected in-loop evaluator. A "turn"
218
+ * here is the whole tool inner-loop until the state machine reaches Done —
219
+ * the evaluator NEVER sees tool-only intermediate iterations.
220
+ */
221
+ export type EvaluationTurn = {
222
+ /**
223
+ * Concatenated text of the terminal assistant message (`""` when the
224
+ * turn produced no text blocks). This is exactly the string a
225
+ * `singleTurn` run returns to its caller.
226
+ */
227
+ readonly finalText: string;
228
+ /**
229
+ * The full conversation history as of turn completion (read-only view —
230
+ * evaluators must not mutate it; the runtime owns the array).
231
+ */
232
+ readonly messages: ReadonlyArray<Anthropic.MessageParam>;
233
+ /**
234
+ * Aggregate token usage across every MAIN-turn model call this attempt
235
+ * made (all tool iterations included; compaction/judge side-calls are
236
+ * not main-turn calls and are excluded). On an evaluation-triggered
237
+ * retry the re-run attempt gets a fresh accumulator, so each `evaluate`
238
+ * invocation sees the usage of exactly the attempt it is grading.
239
+ */
240
+ readonly usage: ModelUsage;
241
+ };
242
+ /** The injected grader's verdict for one graded attempt. */
243
+ export type EvaluationResult = {
244
+ /** Score in [0,1]; compared against `threshold` (>= passes). A non-finite
245
+ * score is treated as 0 (fail) defensively. */
246
+ readonly score: number;
247
+ /** Grader explanation; appended to the retry nudge when `onFail: "retry"`. */
248
+ readonly rationale?: string;
249
+ };
250
+ /**
251
+ * Loop contract 0.4 (G02) — the in-loop evaluation seam (spec
252
+ * `evaluation:` on cli/channel/managed). See
253
+ * {@link RunChatLoopOptions.evaluation} for semantics.
254
+ */
255
+ export type RunEvaluation = {
256
+ /**
257
+ * The grader, INJECTED by the caller (target emitters construct it from
258
+ * the IR's `evaluation.grader` — an llm_judge side-call or a
259
+ * deterministic contains/regex check). runtime-core never constructs a
260
+ * judge itself, so it gains no eval dependency. A grader that throws is
261
+ * treated as grading INFRASTRUCTURE failure, not a verdict: the error is
262
+ * logged (`error` event) and the turn stands un-gated (fail-open) — a
263
+ * flaky judge model must not kill an otherwise healthy run.
264
+ */
265
+ readonly evaluate: (turn: EvaluationTurn) => Promise<EvaluationResult>;
266
+ /** Passing bar: `score >= threshold` passes. (The compiler resolves the
267
+ * spec default: 0.7 for llm_judge; deterministic graders use 1.) */
268
+ readonly threshold: number;
269
+ /** What a failing verdict does — see the option docblock. */
270
+ readonly onFail: "retry" | "halt" | "note";
271
+ /** Hard cap on evaluation-triggered re-runs (>= 0; resolved default 1). */
272
+ readonly maxRetries: number;
273
+ /**
274
+ * Which grader kind produced the score — stamped verbatim onto every
275
+ * `eval_graded` trace event (the event field is required, and only the
276
+ * caller knows what it built `evaluate` from).
277
+ */
278
+ readonly graderType: "llm_judge" | "contains" | "regex";
279
+ };
203
280
  export type RunChatLoopOptions = {
204
281
  model: string;
205
282
  instructions: string;
@@ -248,6 +325,25 @@ export type RunChatLoopOptions = {
248
325
  input?: NodeJS.ReadableStream;
249
326
  /** Tools the model may invoke. When empty/undefined, tools are not advertised. */
250
327
  tools?: ReadonlyArray<RegisteredTool>;
328
+ /**
329
+ * Item 3 (G32) — plugin-contributed pieces to fold into this run. The caller
330
+ * activates the spec's `plugins:` list (or the `--plugins` override) via
331
+ * `@crewhaus/plugin-loader`'s `activatePlugins` and passes the result here.
332
+ *
333
+ * Only `tools` are the chat loop's to bind: they are APPENDED to `opts.tools`
334
+ * and advertised to the model, with first-party tools winning any name
335
+ * collision (a plugin can augment the catalog but not silently shadow a
336
+ * built-in). The other contribution kinds bind at their own hosts — channels
337
+ * at the channel daemon, models at the model-router, graders at the eval
338
+ * stack, target emitters at the compiler — so they are deliberately not
339
+ * accepted here. A compiled bundle instead registers plugin tools directly on
340
+ * its `defaultCatalog`; this option is the interpreter path's equivalent so a
341
+ * `runChatLoop` caller need not mutate a global catalog. Absent → the run is
342
+ * byte-identical to a pre-G32 runtime.
343
+ */
344
+ plugins?: {
345
+ readonly tools?: ReadonlyArray<RegisteredTool>;
346
+ };
251
347
  /** Per-run identity, abort signal, and logger. Defaults to a fresh `createRunContext()`. */
252
348
  runContext?: RunContext;
253
349
  /** Context-window limit in tokens. Defaults to 200_000 (Claude opus/sonnet 4.x). */
@@ -299,6 +395,20 @@ export type RunChatLoopOptions = {
299
395
  * `singleTurn` and injected-`input` runs never spin.
300
396
  */
301
397
  spinner?: boolean;
398
+ /**
399
+ * Sink for the loop's HUMAN-facing output — the `agent> ` prefix, streamed
400
+ * assistant text, `[tool: X]` headers, the `[memory]` notices, abort/timeout
401
+ * notes. Defaults to `process.stdout`.
402
+ *
403
+ * The seam exists because concurrent runs share one stdout: an eval or
404
+ * optimizer pass runs N samples at once, and with every loop writing raw
405
+ * token deltas to the same file descriptor the terminal splices sentences
406
+ * from different samples together mid-word (audit item 20). Callers that
407
+ * fan out give each run its own sink — see eval-runner's per-sample
408
+ * line-buffered writer — so every line stays whole and attributable. A
409
+ * single interactive run passes nothing and is byte-identical to before.
410
+ */
411
+ stdout?: (chunk: string) => void;
302
412
  /**
303
413
  * Override the directory under which session metadata `.json` files and
304
414
  * event-log `.jsonl` files live. Defaults to `.crewhaus/sessions`.
@@ -348,6 +458,22 @@ export type RunChatLoopOptions = {
348
458
  * `pre-slash` first; deny falls through to the original input.
349
459
  */
350
460
  slashCommands?: ReadonlyMap<string, SlashCommand>;
461
+ /**
462
+ * Item 1 — the spec's `feedback:` block (the `IrFeedback` subset the runtime
463
+ * consumes). Presence opts the REPL into the one-keystroke exit rating
464
+ * prompt at clean exit; the answer is appended as the same durable
465
+ * `user_feedback` event `crewhaus rate` writes, so `distill` /
466
+ * `optimize --ratings` read it whichever surface produced it.
467
+ *
468
+ * Owned here rather than in the caller so a COMPILED bundle gets the prompt
469
+ * too: it used to live in the CLI's own teardown, and the cli emitter
470
+ * dropped the block, so a compiled harness silently had no rating capture at
471
+ * all. `enabled: false` disables the block; `exitPrompt: false` disables
472
+ * just the prompt; `CREWHAUS_NO_EXIT_RATING=1` is the per-run opt-out.
473
+ * Never prompts in non-TTY/piped mode, nor in `singleTurn` mode (the prompt
474
+ * is a REPL affordance, not a scripting one).
475
+ */
476
+ feedback?: ExitRatingFeedback;
351
477
  /**
352
478
  * Feature #53 — cross-session memory auto-recall/auto-capture wiring. When
353
479
  * `store` is supplied (the caller builds it from `createMemoryStore`), the
@@ -374,6 +500,49 @@ export type RunChatLoopOptions = {
374
500
  /** Invoked at teardown with the completed user-text turn count and the
375
501
  * run's session id (so the callback can read the transcript to summarize). */
376
502
  readonly onCapture?: (completedTurns: number, sessionId: string) => Promise<void>;
503
+ /**
504
+ * Loop contract 0.4 (Batch E, G21) — WHEN auto-recall runs, lowered from
505
+ * `IrMemory.recallMode`. `"session-start"` (the implicit default) recalls
506
+ * ONCE at boot into the frozen, cache-marked system prefix — the pre-0.4
507
+ * behaviour. `"per-turn"` instead re-runs `recall` against the LATEST user
508
+ * message every `refreshEvery` turns and swaps a VOLATILE recalled block
509
+ * that sits in the mutable tail region (alongside the continuity tail),
510
+ * NEVER re-injecting into the frozen cache prefix — so a long daemon's
511
+ * recalled evidence tracks the conversation instead of drifting from a
512
+ * stale boot-time snapshot. Requires `recall` + `autoRecall: true`.
513
+ */
514
+ readonly recallMode?: "session-start" | "per-turn";
515
+ /**
516
+ * Loop contract 0.4 (Batch E, G21) — turns between per-turn recall
517
+ * refreshes (`IrMemory.refreshEvery`, int > 0; runtime clamps to >= 1 and
518
+ * defaults to 1). Only meaningful when `recallMode` is `"per-turn"`.
519
+ */
520
+ readonly refreshEvery?: number;
521
+ };
522
+ /**
523
+ * Loop contract 0.4 (Batch E, G19) — the active-context curation pre-pass
524
+ * (spec `compaction.curate`, lowered from `IrCompaction`; presence GATES the
525
+ * pass). Once the pre-turn compaction ladder decides the context is already
526
+ * approaching the limit, the runtime runs `@crewhaus/compaction-curator`
527
+ * BEFORE snip→autocompact: it drops semantically-duplicate transcript
528
+ * messages (embedding cosine when an `embedder` is injected, a BM25-family
529
+ * lexical fallback when not) and — when `relevanceTopK` is set — keeps only
530
+ * the top-K most relevant to the latest user message, re-sorted back into
531
+ * transcript order (the curator's relevance ranking SELECTS survivors; it
532
+ * never scrambles the conversation, and messages carrying tool_use/tool_result
533
+ * pairs or inside the snip-protected head/tail are never touched). When the
534
+ * pass frees enough headroom the expensive summarizer call is skipped
535
+ * entirely. Every pass publishes a `curate` trace event
536
+ * (`before`/`after`/`dropped`/`bytesSaved`/`embedded`). The embedder is
537
+ * INJECTED (runtime-core carries no embedder dependency): callers resolve it
538
+ * from `memory.embedder ?? memory.wiki.embedder`; absent → lexical dedupe
539
+ * (`embedded: false`). Absent block → no curation, byte-identical to a
540
+ * pre-0.4 runtime.
541
+ */
542
+ curate?: {
543
+ readonly embedder?: EmbedderFn;
544
+ readonly dedupeThreshold?: number;
545
+ readonly relevanceTopK?: number;
377
546
  };
378
547
  /**
379
548
  * v0.3.0 Goal 1 — the continuity seam (§2.3 requirements ledger, §2.5
@@ -763,6 +932,194 @@ export type RunChatLoopOptions = {
763
932
  readonly model: string;
764
933
  };
765
934
  };
935
+ /**
936
+ * Loop contract 0.4 (G10) — whole-run wall-clock ceiling in ms (spec
937
+ * `limits.deadline_ms`). Armed once at loop start; on fire it aborts the
938
+ * ROOT of the abort tree (`runAbort`) with a branded reason, the in-flight
939
+ * turn winds down through the normal cancellation paths, and the run ends
940
+ * with a classified `run_failed` (class `"timeout"`, exit
941
+ * `EXIT_CODES.timeout`) + `RunFailedError` throw — in REPL mode too (a
942
+ * deadline is terminal everywhere, including while idle at the prompt).
943
+ * Absent → no timer (zero behaviour change).
944
+ */
945
+ deadlineMs?: number;
946
+ /**
947
+ * Loop contract 0.4 (G10) — per-turn wall-clock ceiling in ms (spec
948
+ * `limits.turn_timeout_ms`). Armed when a user→assistant turn starts and
949
+ * cleared when it ends; on fire it aborts the TURN (`turnAbort`) with a
950
+ * branded reason, cancelling the in-flight model call / tool children.
951
+ * In `singleTurn` mode the turn IS the run, so the stop is terminal:
952
+ * classified `run_failed` (class `"timeout"`) + `RunFailedError`. In REPL
953
+ * mode it mirrors the first-SIGINT semantics — the turn aborts with a
954
+ * printed notice and an `error` event (name `"TurnTimeout"`), and the
955
+ * session continues at the prompt (no `run_failed`: the run didn't end).
956
+ */
957
+ turnTimeoutMs?: number;
958
+ /**
959
+ * Loop contract 0.4 (G10) — per-model-call wall-clock ceiling in ms (spec
960
+ * `limits.model_call_timeout_ms`), the hung-stream watchdog. Re-armed
961
+ * before EVERY main-turn stream and cleared when the stream drains; on
962
+ * fire it aborts the turn (`turnAbort` — the turn cannot proceed without
963
+ * its model call) with a branded reason. Terminal/REPL posture identical
964
+ * to `turnTimeoutMs` (error-event name `"ModelCallTimeout"`). Note: under
965
+ * `streaming: true` the drain overlaps mid-stream tool dispatch, so the
966
+ * window covers those tools too — use `turnTimeoutMs` for tool-inclusive
967
+ * bounds and keep this one comfortably above normal stream latency.
968
+ */
969
+ modelCallTimeoutMs?: number;
970
+ /**
971
+ * Loop contract 0.4 (G27) — tool-loop detection tuning + escalation
972
+ * ladder (spec `limits.loop_detection`). `window`/`threshold` thread to
973
+ * `@crewhaus/tool-loop-detection.detectLoop` (defaults 10 / 3). The
974
+ * detector now has a NEAR-DUPLICATE tier — same tool, inputs identical
975
+ * after volatile-substring stripping (numbers/UUIDs/hashes/whitespace),
976
+ * counted at reduced weight — so trivial argument churn no longer defeats
977
+ * it. `escalation` picks what happens when a signature trips detection
978
+ * AGAIN after its one-time warning was ignored:
979
+ * - `"warn"` (default) — nothing further; byte-identical to the pre-0.4
980
+ * warn-once behaviour.
981
+ * - `"justify"` — inject a requireJustification-STYLE demand as a
982
+ * synthetic user message: the model must state a one-sentence
983
+ * justification tied to the session goal before repeating the call.
984
+ * (Deliberately NOT the permission-engine justification gate: that
985
+ * gate is a per-tool-descriptor compile-time contract whose schema
986
+ * advertises a `justification` input field — retrofitting descriptors
987
+ * mid-run would change the advertised tool schema under the model.
988
+ * The synthetic nudge is the proportionate in-band mechanism.)
989
+ * - `"abort"` — abort the TURN, ToolLoopLimit-style: an `error` event
990
+ * (name `"ToolLoopAbort"`) is logged and the state machine takes the
991
+ * Aborted transition, exactly like the `maxToolIterations` cap.
992
+ */
993
+ loopDetection?: {
994
+ readonly window?: number;
995
+ readonly threshold?: number;
996
+ readonly escalation?: "warn" | "justify" | "abort";
997
+ };
998
+ /**
999
+ * Loop contract 0.4 (G17) — per-tool rate limits (spec
1000
+ * `agent.rate_limits`): tool name (or `"*"` for the every-tool default)
1001
+ * → sustained `rpm` + optional short-burst allowance. At loop start the
1002
+ * runtime builds a `@crewhaus/rate-limiter` with one token bucket per
1003
+ * entry (`refillPerSec = rpm/60`, `capacity = burst ?? rpm`) and every
1004
+ * tool execution acquires `tool:<name>` BEFORE dispatch (after the
1005
+ * permission/justification/egress gates, so denied calls never consume
1006
+ * tokens). Tools with neither a named bucket nor a `"*"` default are not
1007
+ * gated. An acquire that exhausts the limiter's wait budget fails just
1008
+ * that call with an `is_error` tool_result (`[rate-limited] …`) so the
1009
+ * model can adapt — it never kills the run. Independent of the
1010
+ * model-call `rateLimiter`/`rateLimitKeys` pair above.
1011
+ */
1012
+ rateLimits?: Readonly<Record<string, {
1013
+ readonly rpm: number;
1014
+ readonly burst?: number;
1015
+ }>>;
1016
+ /**
1017
+ * Loop contract 0.4 (G01) — extended thinking for every MAIN-TURN model
1018
+ * stream (spec `thinking`; same two forms as `IrThinking`). Compaction
1019
+ * and judge side-calls are deliberately untouched — they build their own
1020
+ * `ProviderRequest`s and summarization/grading gains nothing from
1021
+ * spending thinking tokens.
1022
+ * - `{ budgetTokens }` → `ProviderRequest.thinking =
1023
+ * { type: "enabled", budget_tokens }` verbatim.
1024
+ * - `{ effort }` → BOTH fields are set: `thinking` converted through
1025
+ * `EFFORT_THINKING_BUDGET_TOKENS` (for budget-style providers:
1026
+ * anthropic/bedrock/gemini) AND `reasoningEffort` passed through (for
1027
+ * native-effort providers: openai). Adapters ignore the field they
1028
+ * don't support; anthropic's translate gives an explicit `thinking`
1029
+ * precedence, so setting both is convergent.
1030
+ * When the resolved budget crowds out the output budget (Anthropic
1031
+ * requires `max_tokens > thinking.budget_tokens`), the per-request token
1032
+ * ceiling is lifted to `budget + maxTokens` so the declared output budget
1033
+ * survives intact (logged once at boot).
1034
+ */
1035
+ thinking?: {
1036
+ readonly budgetTokens: number;
1037
+ } | {
1038
+ readonly effort: "low" | "medium" | "high";
1039
+ };
1040
+ /**
1041
+ * Loop contract 0.4 (G02) — in-loop evaluation of every COMPLETED turn
1042
+ * (spec `evaluation:` on cli/channel/managed; both `singleTurn` and REPL
1043
+ * paths). After the turn's tool inner-loop reaches Done — never on a
1044
+ * tool-only intermediate iteration — the injected `evaluate` grades the
1045
+ * terminal assistant text and one `eval_graded` trace event is published
1046
+ * per grading pass (`retryIndex` 0 for the original attempt, n for the
1047
+ * n-th evaluation-triggered retry). On `score < threshold`:
1048
+ *
1049
+ * - `onFail: "retry"` — the grader rationale is appended to history as a
1050
+ * synthetic corrective user message (event-logged `synthetic: true`,
1051
+ * like the recovery/loop nudges) and the turn re-runs, up to
1052
+ * `maxRetries` times. Each re-run makes REAL model calls, so its spend
1053
+ * accrues through the existing cost path (`model_response` → budget
1054
+ * meter) and counts against `budget:` exactly like any other call.
1055
+ * Retries exhausted → the last attempt stands and the run continues
1056
+ * (the failing verdict trail is on the trace bus).
1057
+ * - `onFail: "halt"` — classified terminal stop: `run_failed` (class
1058
+ * `"evaluation"`, exit {@link EXIT_CODES.evaluation}) is published +
1059
+ * event-logged and the matching `RunFailedError` is thrown, in REPL
1060
+ * mode too (a quality-floor halt is terminal everywhere).
1061
+ * - `onFail: "note"` — the failing `eval_graded` event is the whole
1062
+ * story; the turn stands and the run continues.
1063
+ *
1064
+ * A turn that ABORTED (SIGINT / wall-clock timer) never completed, so it
1065
+ * is not evaluated. Absent → zero behaviour change for existing callers.
1066
+ */
1067
+ evaluation?: RunEvaluation;
1068
+ /**
1069
+ * Loop contract 0.4 (Batch C, item 4) — the publishing agent's identity
1070
+ * fingerprint (the `agentId` from `loadOrCreateAgentIdentity`). When set AND
1071
+ * runChatLoop constructs the run context itself (no `opts.runContext`), the
1072
+ * run's `TraceEventBus` is built with this `agentId` so every trace envelope
1073
+ * carries it and audit sinks can attribute the run to one agent. When the
1074
+ * caller supplies `opts.runContext`, they own `agentId` on its bus (a
1075
+ * sub-agent spawner threads the parent's `agentId` into the child bus) and
1076
+ * this field is ignored — matching how `runContext` overrides the other
1077
+ * per-run construction inputs. Absent → no stamping (byte-identical to a
1078
+ * pre-0.4 runtime).
1079
+ */
1080
+ agentId?: string;
1081
+ /**
1082
+ * Loop contract 0.4 (Batch C, G11) — how a tool permission that resolves to
1083
+ * `ask` behaves on a NON-interactive surface (`permissions.ask_mode`,
1084
+ * lowered from the IR; absent ⇒ `"pause"`):
1085
+ * - `"pause"` (default) — WITH an `approvals` store, PARK the run: persist
1086
+ * a `PendingApproval`, publish `approval_requested`, and end with the
1087
+ * `approval_pending` failure class so the call can be granted/denied out
1088
+ * of band and re-resolved on the next execution. WITHOUT an `approvals`
1089
+ * store there is nowhere to park, so it collapses to the pre-0.4 deny.
1090
+ * - `"deny"` — the pre-0.4 collapse-in-place: the ask denies immediately
1091
+ * with a note (never parks), regardless of any `approvals` store.
1092
+ * The interactive REPL path is unaffected either way — an `ask` there always
1093
+ * prompts on stdin.
1094
+ */
1095
+ askMode?: "pause" | "deny";
1096
+ /**
1097
+ * Loop contract 0.4 (Batch C, G11) — the pending-approval seam. When
1098
+ * supplied AND `askMode` is `"pause"` (the default), a headless `ask`
1099
+ * consults `store.get(toolName, inputHash)`:
1100
+ * - a `"grant"` → allow this ONE call (the grant is one-shot: consumed via
1101
+ * `store.persist`, so a later identical call re-asks);
1102
+ * - a `"deny"` → deny with a note;
1103
+ * - nothing yet → persist a fresh `PendingApproval`, fire `notify` (if
1104
+ * given), publish `approval_requested`, and PARK the run.
1105
+ * The store is injected (the CLI builds `createPendingApprovalStore`); the
1106
+ * `surface` classifier stamps the `approval_requested` event (defaults to
1107
+ * `"single-turn"` under `singleTurn`, else `"headless"`). Omitted → no
1108
+ * parking (headless `ask` collapses to the pre-0.4 deny).
1109
+ */
1110
+ approvals?: {
1111
+ /**
1112
+ * The persistence seam. Only `{ persist, get, resolve }` are contracted;
1113
+ * the runtime calls `get` (look up a prior decision) and `persist` (park a
1114
+ * fresh request / consume a one-shot grant), while `resolve` is the
1115
+ * out-of-band CLI/Slack surface's entry point on the SAME store. Narrowed
1116
+ * from the full `PendingApprovalStore` so a caller may inject a minimal
1117
+ * store; the concrete `createPendingApprovalStore` satisfies it.
1118
+ */
1119
+ readonly store: Pick<PendingApprovalStore, "persist" | "get" | "resolve">;
1120
+ readonly notify?: (approval: PendingApproval) => Promise<void>;
1121
+ readonly surface?: string;
1122
+ };
766
1123
  };
767
1124
  /**
768
1125
  * Runs the streaming chat loop and returns the terminal assistant text.
@@ -808,4 +1165,25 @@ export declare function resolveToolResultRoot(): string | undefined;
808
1165
  * to mark federation-joined or other runtime sinks dynamic too.
809
1166
  */
810
1167
  export declare function defaultSinkScope(toolName: string): SinkScope;
1168
+ /** Which configured limit fired. `run` = `limits.deadline_ms`,
1169
+ * `turn` = `limits.turn_timeout_ms`, `model_call` = `limits.model_call_timeout_ms`. */
1170
+ export type TimeoutScope = "run" | "turn" | "model_call";
1171
+ /** The branded abort reason a G10 timer aborts with. Carried on
1172
+ * `AbortSignal.reason` (the abort tree propagates reasons parent→child, so
1173
+ * a run-deadline reason is visible on the turn signal too). */
1174
+ export type TimeoutAbortReason = {
1175
+ readonly crewhausTimeout: TimeoutScope;
1176
+ readonly limitMs: number;
1177
+ };
1178
+ /** Read the branded timeout reason off an aborted signal, or undefined when
1179
+ * the signal is not aborted / was aborted for another cause (SIGINT, EOF). */
1180
+ export declare function timeoutAbortReason(signal: AbortSignal): TimeoutAbortReason | undefined;
1181
+ /**
1182
+ * G10 — build the classified terminal report for a fired wall-clock limit.
1183
+ * `class: "timeout"` / exit {@link EXIT_CODES.timeout} joins the failure
1184
+ * taxonomy beside `crewhaus_budget`: like the spend cap, the stop was
1185
+ * CrewHaus's OWN configured ceiling, not a provider failure. Exported for
1186
+ * emitters/tests that render or assert on the report.
1187
+ */
1188
+ export declare function buildTimeoutFailureReport(timeout: TimeoutAbortReason): FailureReport;
811
1189
  export declare function runChatLoop(opts: RunChatLoopOptions): Promise<string>;