@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/alert-watchdog.d.ts +138 -0
- package/dist/alert-watchdog.js +290 -0
- package/dist/incident-collector.d.ts +42 -0
- package/dist/incident-collector.js +125 -0
- package/dist/index.d.ts +222 -4
- package/dist/index.js +503 -28
- package/dist/janitor.d.ts +88 -0
- package/dist/janitor.js +287 -0
- package/dist/observability.d.ts +178 -2
- package/dist/observability.js +466 -2
- package/dist/project-memory.d.ts +17 -1
- package/dist/project-memory.js +42 -0
- package/dist/slo-monitor.d.ts +221 -0
- package/dist/slo-monitor.js +397 -0
- package/package.json +39 -39
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
|
|
302
|
-
* breaker before any `stream()` call. When the breaker trips,
|
|
303
|
-
* model calls reject immediately rather than hammering a
|
|
304
|
-
* upstream. Set
|
|
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.
|