@theoremjs/agents 0.3.5-next.897.g1c14afe → 0.3.5-next.898.gf800d9a

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.
Files changed (30) hide show
  1. package/esm/src/guardrails/canary.js +2 -0
  2. package/esm/src/host/client-turn.js +5 -2
  3. package/esm/src/kernel/engine/background.js +4 -1
  4. package/esm/src/kernel/engine/runner/gates.js +11 -8
  5. package/esm/src/kernel/engine/runner/mod.d.ts +4 -1
  6. package/esm/src/kernel/engine/runner/mod.js +47 -11
  7. package/esm/src/kernel/engine/runner/nested.js +20 -12
  8. package/esm/src/kernel/engine/runner/schema-validation.d.ts +7 -3
  9. package/esm/src/kernel/engine/runner/schema-validation.js +31 -11
  10. package/esm/src/kernel/engine/session/mod.js +2 -2
  11. package/esm/src/kernel/engine/session/session-trace.d.ts +2 -1
  12. package/esm/src/kernel/engine/session/session-trace.js +4 -1
  13. package/esm/src/kernel/field-docs.js +9 -9
  14. package/esm/src/kernel/hook-failure.d.ts +22 -0
  15. package/esm/src/kernel/hook-failure.js +49 -0
  16. package/esm/src/kernel/provider-dispatch.js +3 -1
  17. package/esm/src/kernel/stages.d.ts +4 -0
  18. package/esm/src/kernel/stages.js +23 -4
  19. package/esm/src/kernel/tools/background.d.ts +3 -0
  20. package/esm/src/kernel/tools/coordinate.js +104 -16
  21. package/esm/src/kernel/tools/invoke.js +16 -8
  22. package/esm/src/kernel/tools/resolve.d.ts +4 -0
  23. package/esm/src/kernel/tools/resolve.js +10 -0
  24. package/esm/src/kernel/tools/stage-run.js +12 -1
  25. package/esm/src/kernel/tools/types.d.ts +3 -3
  26. package/esm/src/kernel/turn-events.d.ts +20 -1
  27. package/esm/src/kernel/turn-events.js +19 -0
  28. package/esm/src/kernel/types.d.ts +17 -10
  29. package/esm/src/observability/trace-catalog.js +10 -0
  30. package/package.json +1 -1
@@ -881,6 +881,8 @@ function hostContentOf(event) {
881
881
  return [event.text];
882
882
  case 'error':
883
883
  return [event.error, event.errorCopy];
884
+ case 'hook_failed':
885
+ return [];
884
886
  case 'custom':
885
887
  return [event.data];
886
888
  case 'reasoning':
@@ -24,9 +24,12 @@ function builderWording(event) {
24
24
  }
25
25
  return event;
26
26
  }
27
- /** Raw diagnostics ride on error events, an ended session's close, and a tool call's failure. */
27
+ /** Raw diagnostics ride on error events, an ended session's close, a tool call's failure, and a hook's crash. */
28
28
  function stripErrorInternal(event) {
29
- if ((event.type !== 'error' && event.type !== 'session' && event.type !== 'tool') ||
29
+ if ((event.type !== 'error' &&
30
+ event.type !== 'session' &&
31
+ event.type !== 'tool' &&
32
+ event.type !== 'hook_failed') ||
30
33
  event.errorInternal === undefined) {
31
34
  return event;
32
35
  }
@@ -1,7 +1,9 @@
1
1
  import { startTrace } from '../../observability/trace-span.js';
2
+ import { detachedCrashes } from '../hook-failure.js';
2
3
  /** A detached call's record, written at its real end: a span in its turn's tree cannot outlive the turn. */
3
4
  export function detachedTrace(args) {
4
5
  let tree;
6
+ const crashes = detachedCrashes(() => tree?.root);
5
7
  return {
6
8
  open: (name, attributes) => {
7
9
  tree = startTrace(name, {
@@ -10,9 +12,10 @@ export function detachedTrace(args) {
10
12
  });
11
13
  return tree.root;
12
14
  },
15
+ hookFailed: (hook, err) => crashes.report(hook, err),
13
16
  end: () => {
14
17
  if (tree)
15
- return args.write(tree.collect());
18
+ return args.write(crashes.into(tree.collect()));
16
19
  },
17
20
  };
18
21
  }
@@ -9,6 +9,7 @@ import { resolveGuardrailPolicy } from '../../../guardrails/policy.js';
9
9
  import { replyIsJudged } from '../../../guardrails/progressive-yield.js';
10
10
  import { sanitizeTurnRequest } from '../../../guardrails/sanitize.js';
11
11
  import { ANSWER_TOOL, answersByTool } from '../../answer-tool.js';
12
+ import { hookFailed } from '../../hook-failure.js';
12
13
  import { resolveInputParts } from '../../registry/ingress.js';
13
14
  import { turnFacts } from '../../registry/options.js';
14
15
  import { profileTurnOutputs } from '../../registry/profile-outputs.js';
@@ -115,7 +116,7 @@ function evaluateEgressOutcome(args) {
115
116
  };
116
117
  }
117
118
  async function evaluateValidationOutcome(args) {
118
- const { profile, validation, generation, latestStructured, request, canRetry } = args;
119
+ const { profile, validation, generation, latestStructured, request, canRetry, crashes } = args;
119
120
  if (latestStructured === undefined) {
120
121
  return { action: 'pass' };
121
122
  }
@@ -123,7 +124,7 @@ async function evaluateValidationOutcome(args) {
123
124
  if (!structured) {
124
125
  throw new TheoremError('config', 'outputs.validation requires outputs.structured with a JSON Schema');
125
126
  }
126
- const failures = await collectValidationFailures(structured.jsonSchema, latestStructured, validation.fields, turnFacts(profile, request));
127
+ const failures = await collectValidationFailures(structured.jsonSchema, latestStructured, validation.fields, turnFacts(profile, request), crashes);
127
128
  if (failures.length === 0)
128
129
  return { action: 'pass' };
129
130
  if (!canRetry)
@@ -418,7 +419,7 @@ function parsesAsJson(text) {
418
419
  return false;
419
420
  }
420
421
  }
421
- async function handleValidationGate(validation, flow, state, profile, latestStructured) {
422
+ async function handleValidationGate(validation, flow, state, profile, latestStructured, crashes) {
422
423
  const canRetry = flow.currentAttempt < (validation.maxRetries ?? 0);
423
424
  const fix = flow.pendingItemFix;
424
425
  let reply = latestStructured;
@@ -441,6 +442,7 @@ async function handleValidationGate(validation, flow, state, profile, latestStru
441
442
  latestStructured: reply,
442
443
  request: flow.currentReq,
443
444
  canRetry,
445
+ crashes,
444
446
  });
445
447
  if (outcome.action === 'retry') {
446
448
  return updateFlowForRetry(flow, state, profile, outcome.nextRequest, 'validation');
@@ -449,10 +451,7 @@ async function handleValidationGate(validation, flow, state, profile, latestStru
449
451
  return 'pass';
450
452
  if (outcome.failed)
451
453
  markFailed(state, outcome.failed);
452
- const refused = await collectItemFailures(reply, validation.items, {
453
- options: turnFacts(profile, flow.currentReq),
454
- toolResults: state.toolResults,
455
- });
454
+ const refused = await collectItemFailures(reply, validation.items, { options: turnFacts(profile, flow.currentReq), toolResults: state.toolResults }, crashes);
456
455
  if (refused.length === 0)
457
456
  return 'pass';
458
457
  const fixable = refused.filter((failure) => failure.onFail === 'fix');
@@ -637,7 +636,11 @@ async function* checkAttemptReply(flow, state, profile, system, structured) {
637
636
  return { status: 'continue' };
638
637
  }
639
638
  if (validation) {
640
- const status = await handleValidationGate(validation, flow, state, profile, latestStructured);
639
+ const crashes = [];
640
+ const status = await handleValidationGate(validation, flow, state, profile, latestStructured, crashes);
641
+ for (const crash of crashes) {
642
+ yield hookFailed('outputs.validation', crash, { span: state.trace.root });
643
+ }
641
644
  if (status !== 'pass') {
642
645
  yield status;
643
646
  return { status: 'continue' };
@@ -4,7 +4,10 @@ import type { KernelRegistry } from '../../registry/kernel-registry.js';
4
4
  import type { AgentCaller } from '../../tools/agent.js';
5
5
  import type { InvokeToolRequest } from '../../tools/types.js';
6
6
  import type { CompactHistoryRequest, CompactionResult, SessionRequest, TurnEvent, TurnModel, TurnRequest } from '../../types.js';
7
- /** A turn's events, each read by `req.onEvent` before the caller gets it. */
7
+ /**
8
+ * A turn's events, each read by `req.onEvent` before the caller gets it. A listener that throws
9
+ * misses that event, and the caller gets a `hook_failed` after it, which the listener never reads.
10
+ */
8
11
  declare function runTurnInRegistry(registry: KernelRegistry, req: TurnRequest, provider: TurnModel, sinkOverride?: TraceSink): AsyncGenerator<TurnEvent>;
9
12
  /**
10
13
  * A host's own call's agent tools: the host's provider, or the one `onAgentCall`
@@ -8,17 +8,18 @@ import { resolveObservabilityPolicy } from '../../../observability/resolve-polic
8
8
  import { writeTrace } from '../../../observability/trace.js';
9
9
  import { buildRecord } from '../../../observability/trace-record.js';
10
10
  import { startTrace, traceContent, } from '../../../observability/trace-span.js';
11
+ import { hookFailed } from '../../hook-failure.js';
11
12
  import { profileTypesForField } from '../../profile-scope.js';
12
13
  import { hostAgentModel, nestedTurnModel } from '../../provider-dispatch.js';
13
14
  import { profileInputs, requireModelBinding } from '../../registry/catalog.js';
14
15
  import { resolveTurnInRegistry } from '../../registry/resolve.js';
15
16
  import { bindSystem } from '../../system-parts.js';
16
17
  import { assertBackgroundCoordinator } from '../../tools/background.js';
17
- import { cloneTurnToolSnapshot, expandT1Policy, promoteTurnTools } from '../../tools/resolve.js';
18
+ import { applyT1Policy, cloneTurnToolSnapshot, promoteTurnTools } from '../../tools/resolve.js';
18
19
  import { keptReply, turnDoneOf } from '../../turn-events.js';
19
20
  import { findLast } from '../../util/find-last.js';
20
21
  import { detachedTrace } from '../background.js';
21
- import { compactionMeter, compactionResult, compactorHistory, resolveCompactionTokens, shouldCompact, splitForCompaction, } from '../compaction.js';
22
+ import { compactionMeter, compactionNeeded, compactionResult, compactorHistory, resolveCompactionTokens, shouldCompact, splitForCompaction, } from '../compaction.js';
22
23
  import { endThrownSpan, endTurnSpan, guardrailAttributes, guardrailCheckAttributes, OutputFold, turnSpanOptions, } from '../turn-trace.js';
23
24
  import { sumEventTokens, sumTurnTokens } from '../usage.js';
24
25
  import { runAttemptsWithValidation } from './gates.js';
@@ -179,12 +180,23 @@ function compactionOutcome(result, messagesBefore) {
179
180
  ...(result.summary === undefined ? {} : { summary: traceContent(result.summary) }),
180
181
  };
181
182
  }
183
+ /** `shouldCompact`. A trigger that throws gives way to the token threshold, and its crash goes into `crashes`. */
184
+ async function compactionDecided(decision, spec, span, crashes) {
185
+ try {
186
+ return await shouldCompact(decision, spec);
187
+ }
188
+ catch (err) {
189
+ crashes.push(hookFailed('compaction.trigger', err, { span }));
190
+ return compactionNeeded(decision.tokens, spec);
191
+ }
192
+ }
182
193
  async function compactHistoryBeforeTurn(args) {
183
194
  const decision = await resolveCompactionTokens({
184
195
  spec: args.spec,
185
196
  input: args.input,
186
197
  });
187
- const needed = decision !== undefined && (await shouldCompact(decision, args.spec));
198
+ const needed = decision !== undefined &&
199
+ (await compactionDecided(decision, args.spec, args.parent, args.crashes));
188
200
  const attributes = compactionDecision(args.spec, decision, needed);
189
201
  if (!(needed && decision)) {
190
202
  args.parent.event('theorem.compaction', attributes);
@@ -221,7 +233,8 @@ async function attachAfterCompaction(event, args) {
221
233
  input: args.input,
222
234
  prompt,
223
235
  });
224
- const needed = decision !== undefined && (await shouldCompact(decision, args.spec));
236
+ const needed = decision !== undefined &&
237
+ (await compactionDecided(decision, args.spec, args.span, args.crashes));
225
238
  args.span.event('theorem.compaction', compactionDecision(args.spec, decision, needed));
226
239
  if (!(needed && decision))
227
240
  return event;
@@ -322,7 +335,10 @@ async function* streamTurnEvents(ctx, profile, gen, provider, compactionSpec) {
322
335
  steers: ctx.steers,
323
336
  outState: ctx,
324
337
  })) {
325
- const attached = await maybeAttachAfter(event, ctx, gen, compactionSpec);
338
+ const crashes = [];
339
+ const attached = await maybeAttachAfter(event, ctx, gen, compactionSpec, crashes);
340
+ for (const crash of crashes)
341
+ yield deliver(ctx, crash);
326
342
  const out = projectForObs(attached, ctx.observability);
327
343
  if (!shouldSkipStreamEvent(out, profile))
328
344
  yield deliver(ctx, out);
@@ -465,11 +481,23 @@ async function* emitCancelledDoneAfterAbort(ctx) {
465
481
  yield* emitObservedStage(ctx, stageEv, profile);
466
482
  }
467
483
  }
468
- /** A turn's events, each read by `req.onEvent` before the caller gets it. */
484
+ /**
485
+ * A turn's events, each read by `req.onEvent` before the caller gets it. A listener that throws
486
+ * misses that event, and the caller gets a `hook_failed` after it, which the listener never reads.
487
+ */
469
488
  async function* runTurnInRegistry(registry, req, provider, sinkOverride) {
470
489
  for await (const event of tracedTurnInRegistry(registry, req, provider, sinkOverride)) {
471
- await req.onEvent?.(event);
490
+ let crashed;
491
+ try {
492
+ await req.onEvent?.(event);
493
+ }
494
+ catch (err) {
495
+ throwIfAborted(req.signal);
496
+ crashed = hookFailed('onEvent', err);
497
+ }
472
498
  yield event;
499
+ if (crashed)
500
+ yield crashed;
473
501
  }
474
502
  }
475
503
  async function* runTurnBody(ctx, provider) {
@@ -494,7 +522,10 @@ async function* runTurnBody(ctx, provider) {
494
522
  if (sanitized.refusal)
495
523
  throw sanitized.refusal;
496
524
  const { profile, generation: gen } = resolveTurnInRegistry(ctx.registry, ctx.safe);
497
- await expandT1Policy(ctx.registry.tools, gen.tools, profile, ctx.safe);
525
+ const t1Policy = await applyT1Policy(ctx.registry.tools, gen.tools, profile, ctx.safe);
526
+ if (t1Policy) {
527
+ yield deliver(ctx, hookFailed('tools.t1Policy', t1Policy.crashed, { span: ctx.root }));
528
+ }
498
529
  promoteTurnTools(ctx.registry.tools, gen.tools, ctx.safe.promoted);
499
530
  if (ctx.compacting === 'self')
500
531
  gen.tools = noTools();
@@ -511,7 +542,10 @@ async function* runTurnBody(ctx, provider) {
511
542
  ctx.agents = agentCallerFor(ctx, provider, binding);
512
543
  throwIfAborted(ctx.safe.signal);
513
544
  const compactionSpec = ctx.compacting ? undefined : getCompactionSpec(profile, gen.model);
514
- const compaction = await maybeCompactBefore(ctx, profile, gen, compactionSpec, provider);
545
+ const crashes = [];
546
+ const compaction = await maybeCompactBefore(ctx, profile, gen, compactionSpec, provider, crashes);
547
+ for (const crash of crashes)
548
+ yield deliver(ctx, crash);
515
549
  if (compaction)
516
550
  yield deliver(ctx, projectForObs(compaction, ctx.observability));
517
551
  ctx.system = bindSystem(gen.resolvedSystem, [
@@ -570,7 +604,7 @@ function sessionAgentCaller(registry, req, options, canaries) {
570
604
  function compactorProvider(ctx, profile, spec, provider) {
571
605
  return nestedTurnModel(provider, spec.profile ?? profile.id, spec.profile ? undefined : ctx.req.model);
572
606
  }
573
- async function maybeCompactBefore(ctx, profile, gen, compactionSpec, provider) {
607
+ async function maybeCompactBefore(ctx, profile, gen, compactionSpec, provider, crashes) {
574
608
  if (!(compactionSpec?.timing === 'before' && ctx.safe))
575
609
  return undefined;
576
610
  const compactor = compactorProvider(ctx, profile, compactionSpec, provider);
@@ -587,12 +621,13 @@ async function maybeCompactBefore(ctx, profile, gen, compactionSpec, provider) {
587
621
  parent: ctx.root,
588
622
  canaries: ctx.canaries,
589
623
  signal: ctx.safe.signal,
624
+ crashes,
590
625
  });
591
626
  if (compaction)
592
627
  gen.history = compaction.history;
593
628
  return compaction;
594
629
  }
595
- async function maybeAttachAfter(event, ctx, gen, compactionSpec) {
630
+ async function maybeAttachAfter(event, ctx, gen, compactionSpec, crashes) {
596
631
  if (!(event.type === 'done' && compactionSpec?.timing === 'after' && ctx.safe)) {
597
632
  return event;
598
633
  }
@@ -602,6 +637,7 @@ async function maybeAttachAfter(event, ctx, gen, compactionSpec) {
602
637
  input: ctx.safe.input,
603
638
  seen: ctx.seen,
604
639
  span: ctx.root,
640
+ crashes,
605
641
  });
606
642
  }
607
643
  /**
@@ -1,4 +1,4 @@
1
- import { errorCopyText, isAbortError, TheoremError, throwIfAborted, toErrorEvent, } from '../../../guardrails/error.js';
1
+ import { describeError, errorCopyText, errorKind, isAbortError, TheoremError, throwIfAborted, toErrorEvent, } from '../../../guardrails/error.js';
2
2
  import { labelText } from '../../../guardrails/labels.js';
3
3
  import { nestedTurnModel, resolveRegisteredTurnModel } from '../../provider-dispatch.js';
4
4
  import { profileAllowsInject } from '../../stop.js';
@@ -43,17 +43,25 @@ function createAgentCaller(args) {
43
43
  if (hostInput && !req.onAgentCall) {
44
44
  throw new TheoremError('config', `Agent tool "${tool.name}" declares host fields, which need the request's onAgentCall`);
45
45
  }
46
- const shaped = await req.onAgentCall?.({
47
- tool: tool.name,
48
- callId,
49
- profile: tool.profile,
50
- input: modelInput,
51
- ...(hostInput ? { hostInput } : {}),
52
- caller: caller.id,
53
- depth: args.depth + 1,
54
- ...(req.metadata ? { metadata: req.metadata } : {}),
55
- ...(signal ? { signal } : {}),
56
- });
46
+ let shaped;
47
+ try {
48
+ shaped = await req.onAgentCall?.({
49
+ tool: tool.name,
50
+ callId,
51
+ profile: tool.profile,
52
+ input: modelInput,
53
+ ...(hostInput ? { hostInput } : {}),
54
+ caller: caller.id,
55
+ depth: args.depth + 1,
56
+ ...(req.metadata ? { metadata: req.metadata } : {}),
57
+ ...(signal ? { signal } : {}),
58
+ });
59
+ }
60
+ catch (err) {
61
+ throwIfAborted(signal);
62
+ // why: The hook threw before the agent was sent, so no agent turn ran.
63
+ return settled('hook_failed', errorKind(err), describeError(err));
64
+ }
57
65
  if (shaped && 'refuse' in shaped) {
58
66
  return settled('refused_by_host', 'declined', shaped.refuse);
59
67
  }
@@ -7,8 +7,9 @@ declare function isAbsent(value: unknown): boolean;
7
7
  /**
8
8
  * Required vs optional comes only from the JSON Schema; host field validators run for required
9
9
  * paths and for optional paths that are present. Throws when the root is not an object schema.
10
+ * A validator that throws fails its path, and its error goes into `crashes`.
10
11
  */
11
- declare function collectValidationFailures(jsonSchema: Record<string, unknown>, structured: unknown, fields: Record<string, ProfileValidator> | undefined, options?: Readonly<Record<string, string>>): Promise<ValidationFailure[]>;
12
+ declare function collectValidationFailures(jsonSchema: Record<string, unknown>, structured: unknown, fields: Record<string, ProfileValidator> | undefined, options?: Readonly<Record<string, string>>, crashes?: unknown[]): Promise<ValidationFailure[]>;
12
13
  /**
13
14
  * Whether a validator keyed by `path` can run against `jsonSchema`: each segment is a
14
15
  * property or required key of an object schema, as `collectValidationFailures` walks it.
@@ -27,8 +28,11 @@ interface ItemFailure {
27
28
  declare function valueAt(structured: unknown, path: string): unknown;
28
29
  /** `structured` with the list at `path` replaced; every object on the way is copied. */
29
30
  declare function withListAt(structured: unknown, path: string, list: unknown[]): unknown;
30
- /** Each item an item rule refuses, in the reply's own order. A path with no list has no items. */
31
- declare function collectItemFailures(structured: unknown, items: Record<string, ProfileItemRule> | undefined, turn: ItemCheckTurn): Promise<ItemFailure[]>;
31
+ /**
32
+ * Each item an item rule refuses, in the reply's own order. A path with no list has no items. A
33
+ * check that throws refuses its item, and its error goes into `crashes`.
34
+ */
35
+ declare function collectItemFailures(structured: unknown, items: Record<string, ProfileItemRule> | undefined, turn: ItemCheckTurn, crashes?: unknown[]): Promise<ItemFailure[]>;
32
36
  /** The schema of one item of the list at `path`, or `undefined` when the path reaches no list with one. */
33
37
  declare function itemSchemaAt(jsonSchema: Record<string, unknown>, path: string): Record<string, unknown> | undefined;
34
38
  export type { ItemFailure, ValidationFailure };
@@ -35,11 +35,19 @@ function joinPath(prefix, key) {
35
35
  function pushMissing(path, failures) {
36
36
  failures.push({ path, error: `required field '${path}' is missing` }); // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
37
37
  }
38
- async function runFieldValidator(path, value, validator, options, failures) {
38
+ async function runFieldValidator(path, value, validator, options, failures, crashes) {
39
39
  if (!validator) {
40
40
  return;
41
41
  }
42
- const check = await validator(value, options);
42
+ let check;
43
+ try {
44
+ check = await validator(value, options);
45
+ }
46
+ catch (error) {
47
+ // invariant: A check that cannot answer is a no.
48
+ crashes.push(error);
49
+ check = { isValid: false };
50
+ }
43
51
  if (check.isValid) {
44
52
  return;
45
53
  }
@@ -49,21 +57,21 @@ async function runFieldValidator(path, value, validator, options, failures) {
49
57
  });
50
58
  }
51
59
  async function visitProperty(args) {
52
- const { path, propSchema, child, isRequired, fields, options, failures } = args;
60
+ const { path, propSchema, child, isRequired, fields, options, failures, crashes } = args;
53
61
  if (isAbsent(child)) {
54
62
  if (isRequired) {
55
63
  pushMissing(path, failures);
56
64
  }
57
65
  return;
58
66
  }
59
- await runFieldValidator(path, child, fields?.[path], options, failures);
67
+ await runFieldValidator(path, child, fields?.[path], options, failures, crashes);
60
68
  const nested = asObjectSchema(propSchema);
61
69
  const nestedValue = nested ? asRecord(child) : null;
62
70
  if (nested && nestedValue) {
63
- await walkObject(nested, nestedValue, path, fields, options, failures);
71
+ await walkObject(nested, nestedValue, path, fields, options, failures, crashes);
64
72
  }
65
73
  }
66
- async function walkObject(schema, value, pathPrefix, fields, options, failures) {
74
+ async function walkObject(schema, value, pathPrefix, fields, options, failures, crashes) {
67
75
  const props = propertySchemas(schema);
68
76
  const required = new Set(requiredKeys(schema));
69
77
  const keys = new Set([...Object.keys(props), ...required]);
@@ -77,14 +85,16 @@ async function walkObject(schema, value, pathPrefix, fields, options, failures)
77
85
  fields,
78
86
  options,
79
87
  failures,
88
+ crashes,
80
89
  });
81
90
  }
82
91
  }
83
92
  /**
84
93
  * Required vs optional comes only from the JSON Schema; host field validators run for required
85
94
  * paths and for optional paths that are present. Throws when the root is not an object schema.
95
+ * A validator that throws fails its path, and its error goes into `crashes`.
86
96
  */
87
- async function collectValidationFailures(jsonSchema, structured, fields, options) {
97
+ async function collectValidationFailures(jsonSchema, structured, fields, options, crashes = []) {
88
98
  const root = asObjectSchema(jsonSchema);
89
99
  if (!root) {
90
100
  throw new TheoremError('config', 'structured validation requires a JSON Schema object root'); // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
@@ -96,7 +106,7 @@ async function collectValidationFailures(jsonSchema, structured, fields, options
96
106
  }
97
107
  return failures;
98
108
  }
99
- await walkObject(root, structured, '', fields, options, failures);
109
+ await walkObject(root, structured, '', fields, options, failures, crashes);
100
110
  return failures;
101
111
  }
102
112
  /**
@@ -140,15 +150,25 @@ function withListAt(structured, path, list) {
140
150
  [key]: rest.length ? withListAt(record[key], rest.join('.'), list) : list,
141
151
  };
142
152
  }
143
- /** Each item an item rule refuses, in the reply's own order. A path with no list has no items. */
144
- async function collectItemFailures(structured, items, turn) {
153
+ /**
154
+ * Each item an item rule refuses, in the reply's own order. A path with no list has no items. A
155
+ * check that throws refuses its item, and its error goes into `crashes`.
156
+ */
157
+ async function collectItemFailures(structured, items, turn, crashes = []) {
145
158
  const failures = [];
146
159
  for (const [path, rule] of Object.entries(items ?? {})) {
147
160
  const list = valueAt(structured, path);
148
161
  if (!Array.isArray(list))
149
162
  continue;
150
163
  for (const [index, item] of list.entries()) {
151
- const check = await rule.check(item, turn);
164
+ let check;
165
+ try {
166
+ check = await rule.check(item, turn);
167
+ }
168
+ catch (error) {
169
+ crashes.push(error);
170
+ check = { isValid: false };
171
+ }
152
172
  if (check.isValid)
153
173
  continue;
154
174
  failures.push({
@@ -361,8 +361,8 @@ function buildLiveSession(args) {
361
361
  service: args.background,
362
362
  project: (event) => projectGuardrailTurnEvent(withPublicLabels(event, profile.labels), includeMatch),
363
363
  openTrace: (callId) => {
364
- const { open, finish } = trace.toolRecord(callId);
365
- return { open, end: finish };
364
+ const { open, hookFailed, finish } = trace.toolRecord(callId);
365
+ return { open, hookFailed, end: finish };
366
366
  },
367
367
  };
368
368
  let cycle = 'idle';
@@ -2,7 +2,7 @@ import type { TraceSink } from '../../../observability/trace-sink.js';
2
2
  import { type SpanHandle, type TraceAttributes, type TraceTree } from '../../../observability/trace-span.js';
3
3
  import type { ResolvedObservabilityPolicy } from '../../../observability/types.js';
4
4
  import { type LiveQueueItem } from '../../../providers/types.js';
5
- import type { TurnEventOf } from '../../turn-events.js';
5
+ import type { HookName, TurnEventOf } from '../../turn-events.js';
6
6
  import type { ModelBinding, ModelRequest, Profile, ResolvedGeneration, SessionRequest, TurnEvent } from '../../types.js';
7
7
  type LiveCloser = 'host' | 'provider' | 'theorem';
8
8
  interface LiveTraceBinding {
@@ -90,6 +90,7 @@ declare class LiveTrace {
90
90
  */
91
91
  toolRecord(callId: string): {
92
92
  open: (name: string, attributes: TraceAttributes) => SpanHandle;
93
+ hookFailed: (hook: HookName, err: unknown) => void;
93
94
  finish: () => void;
94
95
  };
95
96
  /** End the session: close what is open, write the session record, wait for every write. */
@@ -5,6 +5,7 @@ import { buildRecord } from '../../../observability/trace-record.js';
5
5
  import { startTrace, traceJson, } from '../../../observability/trace-span.js';
6
6
  import { liveSentInput } from '../../../providers/live.js';
7
7
  import { KEY_FALLBACK_ROW } from '../../../providers/types.js';
8
+ import { detachedCrashes } from '../../hook-failure.js';
8
9
  import { base64ToBytes, bytesToBase64 } from '../../util/base64.js';
9
10
  import { asRecord } from '../record.js';
10
11
  import { callTokensEvent, heldAfter, observeCallEvent, startCallUsage, } from '../runner/usage.js';
@@ -285,6 +286,7 @@ class LiveTrace {
285
286
  */
286
287
  toolRecord(callId) {
287
288
  let tree;
289
+ const crashes = detachedCrashes(() => tree?.root);
288
290
  return {
289
291
  open: (name, attributes) => {
290
292
  tree = startTrace(name, {
@@ -294,9 +296,10 @@ class LiveTrace {
294
296
  });
295
297
  return tree.root;
296
298
  },
299
+ hookFailed: (hook, err) => crashes.report(hook, err),
297
300
  finish: () => {
298
301
  if (tree)
299
- this.write(tree.collect());
302
+ this.write(crashes.into(tree.collect()));
300
303
  },
301
304
  };
302
305
  }
@@ -233,7 +233,7 @@ export const FIELD_DOCS = {
233
233
  'models.*.compaction.previousExchanges': 'How much recent history compaction keeps: a number of exchanges (1 or more), a fraction of maxTokens below compactAt, or 0 to compact it all.',
234
234
  'models.*.compaction.profile': 'The text profile that writes the summary; register it before this one. Leave it out and a text agent summarises its own history, with its own instructions and model and no tools. Its registered model binding selects the provider independently of the calling agent.',
235
235
  'models.*.compaction.timing': 'Whether the kernel compacts before the turn or tells the host to compact after it.',
236
- 'models.*.compaction.trigger': 'Your function that decides when to compact, in place of compactAt and maxTokens.',
236
+ 'models.*.compaction.trigger': 'Your function that decides when to compact, in place of compactAt and maxTokens. A throw is reported as hook_failed, and compactAt and maxTokens decide.',
237
237
  'models.*.defaultEffort': "The effort a turn gets when it doesn't pick one.",
238
238
  'models.*.efforts': 'Named thinking levels. A turn picks one when allowEffortSelect is on. A provider refuses a level its model does not take. Speech ignores them, and so may an image profile without includeText.',
239
239
  'models.*.efforts.*': 'The thinking level sent to the provider for this name.',
@@ -281,10 +281,10 @@ export const FIELD_DOCS = {
281
281
  'outputs.structured': 'The registered JSON schema the reply must follow, which can vary by option; register it before the profile.',
282
282
  'outputs.validation': 'Your checks on a structured reply, and how many rewrites a failure gets.',
283
283
  'outputs.validation.fields': 'Your checks, each keyed by a dotted path into the structured reply, such as diagram.mermaid; a path no structured schema reaches is refused when the profile registers.',
284
- 'outputs.validation.fields.*': 'Your check on this part of the reply, reached through object properties only; a failure sends its error back to the model to rewrite while retries remain.',
284
+ 'outputs.validation.fields.*': 'Your check on this part of the reply, reached through object properties only; a failure sends its error back to the model to rewrite while retries remain. A throw is a failure, reported as hook_failed.',
285
285
  'outputs.validation.items': 'Your checks on the items of a list, each keyed by the dotted path of that list in the structured reply, such as claims; a path no structured schema reaches as a list is refused when the profile registers.',
286
286
  'outputs.validation.items.*': 'Your check on each item of this list. A refused item never fails the reply and the rest of the reply is kept.',
287
- 'outputs.validation.items.*.check': 'Your check on one item, given what the tools of the turn returned (turn.toolResults); its error is the reason the model reads on a rewrite and the host reads on the removed item.',
287
+ 'outputs.validation.items.*.check': 'Your check on one item, given what the tools of the turn returned (turn.toolResults); its error is the reason the model reads on a rewrite and the host reads on the removed item. A throw refuses the item, reported as hook_failed.',
288
288
  'outputs.validation.items.*.onFail': 'drop removes a refused item. fix first asks the model to rewrite the refused items alone, once and while retries remain, then removes any refused again. Removed items leave on the structured event as removed.',
289
289
  'outputs.validation.maxRetries': "How many times the model may rewrite a reply that fails your checks or the schema's required keys before it goes out as it is; under sse, an attempt that gets rewritten has already streamed. A rewrite of a blocked reply (guardrails.blockedReply) counts against this too.",
290
290
  'profile.allowModelSelect': 'Lets a turn name the model it runs on; a name the profile does not declare is refused.',
@@ -347,7 +347,7 @@ export const FIELD_DOCS = {
347
347
  'registerTool.outputSchema': "The tool's result as a JSON Schema, which a function tool's stand-in result is built from.",
348
348
  'registerTool.paths': 'The turn paths this tool is offered on, where * means every path; a turn with no path gets only * tools. Host profiles ignore it.',
349
349
  'registerTool.permission': "Whether the host must approve a call before it runs; the provider's own tools never ask.",
350
- 'registerTool.preTool': "Runs before the host's pre_tool onStage.",
350
+ 'registerTool.preTool': "Runs before the host's pre_tool onStage. A throw fails the call, and the model reads why.",
351
351
  'registerTool.profile': 'The profile this agent tool runs: text, image, or speech. Register it first. Nothing it calls may stop on a gate.',
352
352
  'registerTool.serverUrl': "The MCP server's URL.",
353
353
  'registerTool.session': "How long and how many of an MCP tool's server sessions the kernel keeps.",
@@ -357,14 +357,14 @@ export const FIELD_DOCS = {
357
357
  'registerTool.timeoutMs': 'How long the service may take to answer, its body read included. Past it the call fails timeout and frees its place in the limit.',
358
358
  'registerTool.type': 'How the tool runs.',
359
359
  'runTurn.answersHeldCall': "Set on the turn TurnWiring.prepare is given for a held call that goes on once answered: no model runs, and input is the paused turn's.",
360
- 'runTurn.background': 'Host-issued service for tool calls that go on after their reply. It needs a coordinator with detach. Without it every tool runs inline.',
360
+ 'runTurn.background': "Host-issued service for tool calls that go on after their reply. It needs a coordinator with detach. Without it every tool runs inline. A throw from its event goes on the call's own trace.",
361
361
  'runTurn.builtInArgs': "Args for the provider's own tools on the chosen model's builtInTools, by tool id; each is checked by the schema the provider declares for that tool.",
362
362
  'runTurn.continuation': 'Which continue attempt this is, from 1; checked against the maxContinues of the profile.',
363
363
  'runTurn.continueFrom': 'Continues a turn that stopped in a way the profile lets a turn continue.',
364
364
  'runTurn.conversationId': 'Your conversation id, recorded on the trace.',
365
365
  'runTurn.credentials': 'Where an HTTP or MCP tool gets the credential for its auth slot.',
366
366
  'runTurn.effort': "The effort the turn or session picks from the model's efforts; refused unless the model sets allowEffortSelect.",
367
- 'runTurn.execution': 'Host-owned atomic tool claims and outcomes. Never sent to providers.',
367
+ 'runTurn.execution': 'Host-owned atomic tool claims and outcomes. Never sent to providers. A throw before the call runs fails the call. A throw after it ran keeps the result, marks the call uncertain and is reported as hook_failed. A TheoremError is its answer and ends the turn.',
368
368
  'runTurn.fetch': "Sends each request a remote tool makes, once that request's network checks pass. A page whose tools cannot reach a host directly sends them through its own server here.",
369
369
  'runTurn.host': 'Your own context, handed to tool handlers as ctx.host; Theorem never reads or records it.',
370
370
  'runTurn.input': 'What the user sent for the turn.',
@@ -382,8 +382,8 @@ export const FIELD_DOCS = {
382
382
  'runTurn.metadata': 'Your own values, kept on the trace; Theorem does not read them.',
383
383
  'runTurn.model': "The model id the turn or session picks from the profile's models; refused unless the profile sets allowModelSelect.",
384
384
  'runTurn.onAgentCall': 'Runs before each agent tool call, to shape the request to the called agent or to refuse the call.',
385
- 'runTurn.onEvent': "Reads each of the turn's events as it leaves runTurn, before the caller gets it. A throw ends the turn with that error.",
386
- 'runTurn.onStage': 'Your function that sees each stage of a text turn or a live session, and can answer with what the stage allows.',
385
+ 'runTurn.onEvent': "Reads each of the turn's events as it leaves runTurn, before the caller gets it. A throw goes to the caller as hook_failed, which this function does not read, and the turn goes on.",
386
+ 'runTurn.onStage': 'Your function that sees each stage of a text turn or a live session, and can answer with what the stage allows. A throw at pre_tool fails that call. A throw at any other stage is reported as hook_failed, and the turn goes on without its answer.',
387
387
  'runTurn.options': "The value the host's code sets for each option in the profile's identity.options but path; an option or a value the profile does not declare is refused.",
388
388
  'runTurn.pageExecution': 'Host-issued browser dispatch with a claimed operation and correlated result.',
389
389
  'runTurn.path': 'The channel the turn or session comes from; only tools whose paths name it, or *, are offered.',
@@ -412,7 +412,7 @@ export const FIELD_DOCS = {
412
412
  tools: 'The registered tools this profile may use, and how they load. Built-in tools are set per model.',
413
413
  'tools.allow': "Your registered tools this agent may use; the provider's own tools go on the model's builtInTools instead.",
414
414
  'tools.parallel': 'true: the calls of one step run side by side, and a call whose pre_tool answers waitFor starts its body once those calls settle. Left out or false: they run one at a time, in the order the model made them. A step is the calls the model makes together in a turn, or the calls a host runs through invokeToolStep.',
415
- 'tools.t1Policy': 'Your function that picks, at the start of each turn, which T2 tools to load up front; the rest wait for tools.t2Loader.',
415
+ 'tools.t1Policy': 'Your function that picks, at the start of each turn, which T2 tools to load up front; the rest wait for tools.t2Loader. A throw loads none up front, reported as hook_failed.',
416
416
  'tools.t2Loader': "The function tool that loads T2 tools. It must be in allow and return { loaded: ToolId[] }. One forbidden id fails the load. Ids off the turn path are skipped. The tools it loads can be called from the next step: a step's calls see the tools as they stood when the step began.",
417
417
  turnBehaviour: 'Whether a reply that stopped early can be continued, and whether a running turn can be steered.',
418
418
  'turnBehaviour.allowSteering': 'Lets your onStage hook add messages to a running turn. Text profiles also let the user steer.',
@@ -0,0 +1,22 @@
1
+ import type { TraceSpan } from '../observability/trace-schema.js';
2
+ import type { SpanHandle } from '../observability/trace-span.js';
3
+ import type { TurnStage } from './schema.js';
4
+ import type { HookName, ToolFailure, TurnEventOf } from './turn-events.js';
5
+ /** The report of a host hook that threw: the one the host reads, with its copy on the span. */
6
+ export declare function hookFailed(hook: HookName, err: unknown, at?: {
7
+ stage?: TurnStage;
8
+ callId?: string;
9
+ span?: SpanHandle | undefined;
10
+ }): TurnEventOf<'hook_failed'>;
11
+ /** A call a host hook could not approve, start or keep: it fails, and the model reads why. */
12
+ export declare function hookCrashFailure(err: unknown): ToolFailure;
13
+ /**
14
+ * The crash reports of a call that runs past its turn, on its own trace. Its span ends when the
15
+ * call answers, so a crash after that, such as a failed late save, is kept and added to the span
16
+ * when the record is written.
17
+ */
18
+ export declare function detachedCrashes(root: () => SpanHandle | undefined): {
19
+ report(hook: HookName, err: unknown): void;
20
+ /** The written spans, root first, with the late reports on the root. */
21
+ into(spans: TraceSpan[]): TraceSpan[];
22
+ };