@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/alert-watchdog.js +7 -0
- package/dist/exit-rating.d.ts +92 -0
- package/dist/exit-rating.js +163 -0
- package/dist/identity.d.ts +29 -0
- package/dist/identity.js +85 -0
- package/dist/index.d.ts +379 -1
- package/dist/index.js +1282 -128
- package/dist/observability.d.ts +20 -0
- package/dist/observability.js +97 -1
- package/dist/worker-platform.d.ts +14 -0
- package/dist/worker-platform.js +65 -0
- package/package.json +43 -41
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
|
|
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>;
|