@crewhaus/runtime-core 0.1.8 → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/index.d.ts CHANGED
@@ -6,12 +6,20 @@ import { type EventLog } from "@crewhaus/event-log";
6
6
  import { type HookDef } from "@crewhaus/hooks-engine";
7
7
  import { type JustificationJudge, type PermissionMode, type RuleSet } from "@crewhaus/permission-engine";
8
8
  import type { RateLimiter } from "@crewhaus/rate-limiter";
9
+ import { type NamedFailureClass } from "@crewhaus/recovery-engine";
9
10
  import { type RunContext } from "@crewhaus/run-context";
10
11
  import { type SkillRef } from "@crewhaus/skills-registry";
11
12
  import { type SlashCommand } from "@crewhaus/slash-commands";
12
13
  import type { RegisteredTool } from "@crewhaus/tool-catalog";
14
+ import { type AlertSink } from "./observability";
15
+ import type { SloMitigationSink, SloTargets } from "./slo-monitor";
13
16
  export { CLAUDE_CODE_HEADERS, CLAUDE_CODE_SYSTEM_PREFIX, OAUTH_BETAS, createAnthropicClient, resolveAuth, } from "@crewhaus/adapter-anthropic";
14
17
  export type { ResolvedAuth } from "@crewhaus/adapter-anthropic";
18
+ export { createJanitor } from "./janitor";
19
+ export type { CreateJanitorOptions, Janitor, JanitorReservationStore, JanitorRunResult, JanitorStepName, JanitorStepResult, JanitorStepStatus, } from "./janitor";
20
+ export { type AlertBreachPayload, type AlertSink, type AttachDefaultSubscribersOptions, attachDefaultSubscribers, } from "./observability";
21
+ 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";
22
+ export { type AttachIncidentCollectorOptions, type IncidentCapture, type IncidentTriggerKind, attachIncidentCollector, classifyIncidentTrigger, } from "./incident-collector";
15
23
  /**
16
24
  * Reconcile a message history by dropping "orphan" `tool_use` blocks — a
17
25
  * `tool_use` with no answering `tool_result` anywhere later in the
@@ -69,6 +77,31 @@ export type JustificationAuditSink = {
69
77
  readonly payload: unknown;
70
78
  }): Promise<unknown>;
71
79
  };
80
+ /**
81
+ * Pillar 3 sink-side fabric — the durable audit sink the egress classifier
82
+ * appends to. Structurally the same subset of `@crewhaus/audit-log`'s
83
+ * `AuditLog` as {@link JustificationAuditSink} (its `append({ kind, payload })`),
84
+ * declared as a minimal interface so runtime-core takes no dependency on (or
85
+ * cycle with) `@crewhaus/audit-log`.
86
+ *
87
+ * BACKGROUND (AUTOMATION-OPPORTUNITIES.md item 20): the `egress_decision`
88
+ * AuditKind was declared but had NO writer — egress verdicts existed ONLY as
89
+ * ephemeral trace-bus `permission_decision` events (outcome: `egress-*`), so
90
+ * nothing could triage egress history offline. This seam closes that: when a
91
+ * caller wires it, every NON-PASS egress verdict (warn OR block) appends one
92
+ * durable `egress_decision` record so `crewhaus egress review` can mine it.
93
+ * The RAW outbound payload is never stored — only the lineage summary the
94
+ * digest documents (`{ sinkId, sinkScope, verdict, originsFound, matchCount }`),
95
+ * exactly as `@crewhaus/audit-log`'s AuditKind header specifies. Pass verdicts
96
+ * are NOT written (they are the overwhelming common case and carry no triage
97
+ * signal). Omitting the sink is zero behaviour change for existing callers.
98
+ */
99
+ export type EgressAuditSink = {
100
+ append(input: {
101
+ readonly kind: "egress_decision";
102
+ readonly payload: unknown;
103
+ }): Promise<unknown>;
104
+ };
72
105
  export type RunChatLoopOptions = {
73
106
  model: string;
74
107
  instructions: string;
@@ -98,6 +131,21 @@ export type RunChatLoopOptions = {
98
131
  * When omitted, defaults to `_adapter` (or the routed primary).
99
132
  */
100
133
  _compactionAdapter?: ProviderAdapter;
134
+ /**
135
+ * Item 22 — same injection contract as `_adapter`, for the failover
136
+ * chain's fallback candidates: pre-built adapters keyed by their spec
137
+ * model string, bypassing the model-router. Only consulted when
138
+ * `modelFallbacks` is non-empty. Tests script per-candidate failures
139
+ * through this map; production callers leave it undefined.
140
+ */
141
+ _failoverAdapters?: ReadonlyMap<string, ProviderAdapter>;
142
+ /**
143
+ * Item 27 — test injection for the budget-degrade target: a pre-built
144
+ * adapter used in place of `resolveModel(budget.onExceed.model)` when a
145
+ * `degrade` breach fires. Production callers leave it undefined (the
146
+ * runtime resolves the degrade model through the normal router path).
147
+ */
148
+ _budgetDegradeAdapter?: ProviderAdapter;
101
149
  /** Override the input stream (testing). Defaults to process.stdin. */
102
150
  input?: NodeJS.ReadableStream;
103
151
  /** Tools the model may invoke. When empty/undefined, tools are not advertised. */
@@ -202,6 +250,40 @@ export type RunChatLoopOptions = {
202
250
  * `pre-slash` first; deny falls through to the original input.
203
251
  */
204
252
  slashCommands?: ReadonlyMap<string, SlashCommand>;
253
+ /**
254
+ * Feature #53 — cross-session memory auto-recall/auto-capture wiring. When
255
+ * `store` is supplied (the caller builds it from `createMemoryStore`), the
256
+ * runtime honours the auto-* switches:
257
+ * - `autoRecall`: at session start, recall the top-`recallK` memories for
258
+ * the current context and inject them into the system prompt (mirrors
259
+ * the project-memory auto-load block). `recallSeed` is the query used
260
+ * (defaults to the agent instructions).
261
+ * - `autoCapture`: at run teardown (in the same finally where the `stop`
262
+ * hook fires — NOT a credential-stripped hook), the caller-supplied
263
+ * `onCapture` is invoked with the completed-turn count so it can
264
+ * summarize the session's durable outcomes into the store.
265
+ * Omitted → no memory injection or capture (Remember/Recall passed via
266
+ * `tools` still work). Kept as an injected seam so runtime-core does not
267
+ * depend on memory-store.
268
+ */
269
+ memory?: {
270
+ readonly autoRecall?: boolean;
271
+ readonly recallK?: number;
272
+ readonly recallSeed?: string;
273
+ /** Return recalled memory lines to inject; runtime wraps them in a block. */
274
+ readonly recall?: (query: string, k: number) => Promise<readonly string[]>;
275
+ readonly autoCapture?: boolean;
276
+ /** Invoked at teardown with the completed user-text turn count and the
277
+ * run's session id (so the callback can read the transcript to summarize). */
278
+ readonly onCapture?: (completedTurns: number, sessionId: string) => Promise<void>;
279
+ };
280
+ /**
281
+ * Item #56 — absolute paths to per-user preference files injected at run
282
+ * start via the project-memory auto-load path (alongside LESSONS.md, which
283
+ * is now a canonical memory file). The CLI resolves the current user's
284
+ * `.crewhaus/preferences/<user>.md` and threads it here. Absent → no-op.
285
+ */
286
+ preferenceFiles?: ReadonlyArray<string>;
205
287
  /**
206
288
  * Section 13 — inline sub-agent definitions exposed via the `Task` tool.
207
289
  * Threaded into the `RuntimeBridge` and surfaced to framework-aware
@@ -266,6 +348,41 @@ export type RunChatLoopOptions = {
266
348
  * `.crewhaus/audit`.
267
349
  */
268
350
  justificationAuditSink?: JustificationAuditSink;
351
+ /**
352
+ * Ops item 31 — durable + off-box delivery for the alert watchdog (gated by
353
+ * CREWHAUS_ALERTS). When supplied, a baseline-threshold breach appends an
354
+ * audit record and/or fires the settings.json `alert` hook / webhook via
355
+ * these callbacks. Omitted → the watchdog still persists its per-session
356
+ * metrics snapshot and publishes the `alert_raised` trace event, it just has
357
+ * no durable/off-box delivery (zero behaviour change for existing callers).
358
+ * The CLI `run` path wires the audit log + settings.json alert hook here.
359
+ */
360
+ alertSink?: AlertSink;
361
+ /** Item 31 — override the per-session metrics-history dir (tests/tenants). */
362
+ alertMetricsDir?: string;
363
+ /**
364
+ * Ops item 37 — lowered `observability.slo` targets (gated by CREWHAUS_SLO).
365
+ * When supplied, the runtime SLO monitor folds live events into rolling
366
+ * windows and walks the declared mitigation ladder on a sustained breach.
367
+ * Omitted → no monitor (zero behaviour change). The CLI `run` path lowers
368
+ * the cwd spec's `observability.slo` block and wires the mitigation sink.
369
+ */
370
+ sloTargets?: SloTargets;
371
+ /** Item 37 — injected SLO mitigation ladder delivery (audit / pause-intake /
372
+ * rollback), supplied by the CLI so runtime-core owns no deploy/gateway I/O. */
373
+ sloSink?: SloMitigationSink;
374
+ /**
375
+ * Ops item 32 — spec identity stamped into an auto-assembled incident
376
+ * capture (gated by CREWHAUS_INCIDENTS). Absent → the capture records a null
377
+ * spec; the CLI `run` path passes `{ name, version?, hash? }`.
378
+ */
379
+ incidentSpec?: {
380
+ readonly name: string;
381
+ readonly version?: string;
382
+ readonly hash?: string;
383
+ };
384
+ /** Item 32 — override the incidents dir (tests/tenants). */
385
+ incidentsDir?: string;
269
386
  /**
270
387
  * Pillar 3 sink-side fabric (FR-006) — pluggable egress-matching
271
388
  * strategy. When supplied, every external-scope tool call routes its
@@ -279,6 +396,17 @@ export type RunChatLoopOptions = {
279
396
  * instance of `@crewhaus/egress-matcher-semantic`.
280
397
  */
281
398
  egressMatcher?: EgressMatcher;
399
+ /**
400
+ * Pillar 3 sink-side fabric — durable egress audit sink (item 20). When
401
+ * supplied, every NON-PASS egress verdict (warn OR block) appends one
402
+ * `egress_decision` record (lineage summary only, never the raw payload) to
403
+ * this hash-chained sink IN ADDITION to the ephemeral `permission_decision`
404
+ * trace event. This is what makes egress history triageable offline by
405
+ * `crewhaus egress review`. Omitting it leaves the trace bus as the only
406
+ * surface (no behaviour change for existing callers). The CLI `run` path
407
+ * wires a real `@crewhaus/audit-log` instance rooted at `.crewhaus/audit`.
408
+ */
409
+ egressAuditSink?: EgressAuditSink;
282
410
  /**
283
411
  * Pillar 3 sink-side — classify a tool sink as `"external-configured"` (a
284
412
  * spec-declared sink → warn on non-user content) or `"external-dynamic"` (a
@@ -298,16 +426,76 @@ export type RunChatLoopOptions = {
298
426
  */
299
427
  maxToolIterations?: number;
300
428
  /**
301
- * Section 27 — wrap the resolved primary `ProviderAdapter` in a circuit
302
- * breaker before any `stream()` call. When the breaker trips, subsequent
303
- * model calls reject immediately rather than hammering a degraded
304
- * upstream. Set via codegen when the spec lists `circuit_breaker:` opts.
429
+ * Section 27 / item 22 — wrap the resolved primary `ProviderAdapter` in a
430
+ * circuit breaker before any `stream()` call. When the breaker trips,
431
+ * subsequent model calls reject immediately rather than hammering a
432
+ * degraded upstream. Set by codegen (and the `crewhaus run` path) from the
433
+ * spec's `agent.circuit_breaker` block; field names mirror
434
+ * `CircuitBreakerOptions` in `@crewhaus/circuit-breaker`. When
435
+ * `modelFallbacks` is also set, this tuning applies to EVERY candidate's
436
+ * breaker in the failover chain.
305
437
  */
306
438
  circuitBreaker?: {
307
439
  readonly failureThreshold?: number;
308
440
  readonly windowMs?: number;
309
441
  readonly cooldownMs?: number;
310
442
  };
443
+ /**
444
+ * Item 22 — ordered fallback model strings (spec `agent.model_fallbacks`).
445
+ * When non-empty, the primary adapter is replaced by a
446
+ * `@crewhaus/model-router` failover chain: every candidate (primary
447
+ * first) gets its own circuit breaker, each model call routes to the
448
+ * first candidate whose breaker admits traffic, and routing changes are
449
+ * published as `model_failover` trace events. Fallbacks resolve their
450
+ * credentials lazily via the normal `resolveModel` path — a candidate
451
+ * with a missing key warns at boot (doctor-style, stderr) and is skipped
452
+ * when actually tried, never hard-failing boot. v1 scope: only the
453
+ * primary agent model gets the chain — `compactionModel` (when it names
454
+ * its own model) and judge/grader slots keep their single adapters. When
455
+ * compaction reuses the primary model (no `compactionModel`), it flows
456
+ * through the same chain by construction.
457
+ */
458
+ modelFallbacks?: ReadonlyArray<string>;
459
+ /**
460
+ * Item 26 — opt-in two-tier turn-difficulty router (spec `agent.model_tiers`).
461
+ * When set, BOTH tier adapters resolve at boot (mirroring the compaction
462
+ * second-adapter wiring), and each turn the loop picks a tier from
463
+ * deterministic signals (estimated context tokens, tools-in-play, turn
464
+ * index, prior-turn tool_use density), streams through the chosen tier's
465
+ * adapter, and publishes a `model_tier_route` trace event. A `fast`-tier
466
+ * turn that FAILS is re-run on `default` (misroute recovery). Absent → the
467
+ * single primary adapter path, unchanged. Mutually independent of
468
+ * `modelFallbacks`: when both are set the primary chain still governs the
469
+ * `default` tier; the `fast` tier is its own single adapter (v1 scope).
470
+ */
471
+ modelTiers?: {
472
+ readonly fast: string;
473
+ readonly default: string;
474
+ readonly routing?: {
475
+ readonly contextTokenThreshold?: number;
476
+ readonly toolsToDefault?: boolean;
477
+ readonly firstTurnToDefault?: boolean;
478
+ readonly priorToolDensityThreshold?: number;
479
+ };
480
+ };
481
+ /**
482
+ * Item 26 — test injection for the two tier adapters, keyed by their spec
483
+ * model string (mirrors `_failoverAdapters`). Production callers leave it
484
+ * undefined (the runtime resolves both tiers through the normal router).
485
+ */
486
+ _tierAdapters?: ReadonlyMap<string, ProviderAdapter>;
487
+ /**
488
+ * Section 55 (Track A) / item 23 — the spec's `failure_taxonomy`, lowered
489
+ * from the IR. Consulted by `recovery-engine.recover()` BEFORE its
490
+ * built-in classify+recover flow so user-named error classes take
491
+ * precedence (their declared `recovery` action wins). Item 23 adds the
492
+ * `switch-model` action: a matched entry reroutes the same turn onto the
493
+ * next provider-failover candidate (opening the active breaker) instead
494
+ * of exhausting backoff retries — only meaningful with `modelFallbacks`
495
+ * set; a no-op re-issue otherwise. When absent, recovery is the built-in
496
+ * taxonomy exactly as before (zero behaviour change for existing callers).
497
+ */
498
+ failureTaxonomy?: ReadonlyArray<NamedFailureClass>;
311
499
  /**
312
500
  * Section 27 — pre-call rate gating. The runtime calls
313
501
  * `rateLimiter.acquire(rateLimitKeys, 1)` before each model invocation.
@@ -328,6 +516,36 @@ export type RunChatLoopOptions = {
328
516
  * Pass `0` (or omit) to force a refresh on the first turn.
329
517
  */
330
518
  promptCacheLastRotatedAt?: number;
519
+ /**
520
+ * Item 27 — run-level spend cap with a degradation ladder. Generalizes
521
+ * the optimizer's `BudgetMeter` to normal runs (`crewhaus run
522
+ * --budget-usd` / spec `budget: { usd, on_exceed }`). An always-on cost
523
+ * meter (independent of `CREWHAUS_COST_TRACKING`) accrues per-response
524
+ * spend priced off the WIRE model that actually served, and a PRE-TURN
525
+ * check — beside the token-budget/compaction check — enforces the cap
526
+ * before the next user turn opens:
527
+ * - `on_exceed.kind: "stop"` ends the run cleanly with a `[budget]`
528
+ * notice (the current turn always completes; the cap gates the NEXT
529
+ * turn, so an in-flight turn is never severed mid-tool-call).
530
+ * - `on_exceed.kind: "degrade"` re-resolves the primary model to
531
+ * `on_exceed.model` ONCE (the cheaper rung of the ladder) and
532
+ * continues; a `model_failover` event (reason `budget_degrade`)
533
+ * records the switch. If spend later crosses the cap AGAIN on the
534
+ * degraded model, the run stops (the ladder has one rung in v1).
535
+ * `usdMicros` is the ceiling in USD-micros (1 USD = 1_000_000). Absent →
536
+ * no cap (zero behaviour change for existing callers). A model the
537
+ * pricing table can't price accrues $0, so an all-unpriced run degrades
538
+ * to uncapped — same posture as cost-tracker's pricing-miss handling.
539
+ */
540
+ budget?: {
541
+ readonly usdMicros: number;
542
+ readonly onExceed: {
543
+ readonly kind: "stop";
544
+ } | {
545
+ readonly kind: "degrade";
546
+ readonly model: string;
547
+ };
548
+ };
331
549
  };
332
550
  /**
333
551
  * Runs the streaming chat loop and returns the terminal assistant text.