@theoremjs/agents 0.3.5-next.897.g1c14afe → 0.3.5-next.899.g4d53f7b

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 (34) hide show
  1. package/esm/src/guardrails/canary.js +2 -0
  2. package/esm/src/guardrails/labels.d.ts +1 -1
  3. package/esm/src/guardrails/labels.js +3 -0
  4. package/esm/src/host/client-turn.js +19 -4
  5. package/esm/src/kernel/engine/background.js +4 -1
  6. package/esm/src/kernel/engine/runner/gates.js +11 -8
  7. package/esm/src/kernel/engine/runner/mod.d.ts +4 -1
  8. package/esm/src/kernel/engine/runner/mod.js +47 -11
  9. package/esm/src/kernel/engine/runner/nested.js +21 -11
  10. package/esm/src/kernel/engine/runner/schema-validation.d.ts +7 -3
  11. package/esm/src/kernel/engine/runner/schema-validation.js +31 -11
  12. package/esm/src/kernel/engine/session/mod.js +2 -2
  13. package/esm/src/kernel/engine/session/session-trace.d.ts +2 -1
  14. package/esm/src/kernel/engine/session/session-trace.js +4 -1
  15. package/esm/src/kernel/field-docs.js +9 -9
  16. package/esm/src/kernel/hook-failure.d.ts +26 -0
  17. package/esm/src/kernel/hook-failure.js +54 -0
  18. package/esm/src/kernel/provider-dispatch.js +3 -1
  19. package/esm/src/kernel/stages.d.ts +4 -0
  20. package/esm/src/kernel/stages.js +23 -4
  21. package/esm/src/kernel/tools/background.d.ts +3 -0
  22. package/esm/src/kernel/tools/coordinate.d.ts +7 -1
  23. package/esm/src/kernel/tools/coordinate.js +110 -17
  24. package/esm/src/kernel/tools/execute.js +8 -1
  25. package/esm/src/kernel/tools/invoke.js +17 -9
  26. package/esm/src/kernel/tools/resolve.d.ts +4 -0
  27. package/esm/src/kernel/tools/resolve.js +10 -0
  28. package/esm/src/kernel/tools/stage-run.js +15 -1
  29. package/esm/src/kernel/tools/types.d.ts +3 -3
  30. package/esm/src/kernel/turn-events.d.ts +20 -1
  31. package/esm/src/kernel/turn-events.js +21 -0
  32. package/esm/src/kernel/types.d.ts +17 -10
  33. package/esm/src/observability/trace-catalog.js +10 -0
  34. 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':
@@ -1,7 +1,7 @@
1
1
  /** Values that fill a label template's `{param}` placeholders. */
2
2
  export type LabelParams = Record<string, string | number>;
3
3
  /** Keys are stable API. */
4
- export declare const LABEL_KEYS: readonly ["provider.decision_failed", "provider.decision_unavailable", "provider.decision_model_missing", "provider.decision_ended", "provider.decision_images_off", "provider.decision_box_model", "provider.budget_exhausted", "provider.adapter_version", "provider.adapter_methods", "provider.adapter_schemas", "provider.fallback_slot", "provider.model_fallback_slot", "provider.host_model", "turn.media_refused_image", "turn.media_refused_video", "turn.media_refused_file", "provider.turn_profile", "provider.model_binding_missing", "provider.session_closed", "provider.settled_call", "provider.session_unavailable", "provider.live_input", "provider.tool_cancel_missing", "provider.kernel_gate", "provider.event_invalid", "provider.response_identity", "provider.credential_resolution", "provider.credential_shape", "provider.stored_continuation", "provider.continuation_mismatch", "provider.continuation_contract", "provider.stateless_history", "provider.events_after_completion", "provider.duplicate_call", "provider.tool_cancel_live", "provider.complete_unavailable", "provider.parallel_tools", "provider.binding_identity", "provider.profile_type", "provider.event_type", "provider.feature", "provider.input_kind", "provider.output_kind", "provider.builtin", "provider.credential_missing", "provider.profile_configuration", "continue.instruction", "canary.bind_note", "user_data.note", "context.note", "taint.blocked", "taint.reason_steered", "taint.reason_tainted", "taint.destination_blocked", "taint.destination_confirm", "advisory.notice_elevated", "advisory.notice_high", "advisory.guidance", "attachments.too_many_files", "attachments.too_many_of_kind", "attachments.file_too_large", "attachments.turn_too_large", "attachments.not_accepted", "attachments.mime_not_allowed", "attachments.limits_unconfigured", "quota.exhausted", "quota.busy", "error.config", "error.request", "error.conflict", "error.not_found", "error.input", "error.action", "error.auth", "error.rate_limit", "error.busy", "error.unsupported", "error.unavailable", "error.bad_response", "error.network", "error.timeout", "error.safety", "error.blocked", "error.declined", "error.failed", "error.cancelled", "error.internal", "repair.default_guidance", "repair.items_guidance", "repair.cut_off_guidance", "repair.reply_cut_off", "repair.call_cut_off", "repair.call_cut_off_guidance", "repair.nothing_written", "repair.nothing_written_guidance", "repair.prompt_header", "repair.prompt_intro", "repair.prompt_instructions", "repair.history_heading", "repair.section_previous_output", "repair.section_validator_rejection", "repair.section_repair_guidance", "repair.section_instructions", "structured.answer_tool", "structured.answer_missing", "structured.cut_off", "structured.not_json", "compaction.request", "compaction.tool_call", "compaction.tool_result", "compaction.tool_files", "decision.box_image", "detect.blocked", "detect.call_blocked", "detect.output_blocked", "detect.shown_blocked", "detect.hint.ids", "detect.hint.financial", "detect.hint.network", "detect.hint.credentials", "detect.hint.email", "detect.hint.phone", "detect.hint.bank_account", "detect.hint.injection", "detect.hint.canary_leak", "detect.hint.prompt_leak", "detect.hint.marker_leak", "detect.hint.ungiven_images", "detect.hint.ungiven_links", "detect.hint.tool_leak", "detect.hint.own", "egress.default_repair_guidance", "egress.refusal", "egress.refusal_cut", "egress.rejection", "egress.rejection_found", "egress.hint_unscannable", "egress.hint_provider_tool_leak", "thought.omitted_image", "thought.omitted_link", "thought.omitted_instructions", "session.abandon_gated", "session.tool_denied", "session.tool_aborted", "session.sign_in", "sign_in.link", "sign_in.pending", "sign_in.done", "sign_in.declined", "sign_in.expired", "sign_in.out_of_scope", "session.gate_expired", "session.provider_state_unowned", "session.conversation_unknown", "session.full", "session.busy", "session.turn_ended", "session.gate_pending", "session.part_skipped", "live.session_ended", "voice.unsupported", "voice.permission", "voice.unavailable", "voice.failed", "voice.empty", "stop.cancelled", "stop.interrupted", "stop.length", "stop.filtered", "stop.provider_error", "stop.stream_incomplete", "stop.step_limit", "stop.answer_missing", "composer.model", "composer.effort", "tool.awaiting_user", "tool.completed_hidden", "tool.t2_loader_needs_snapshot", "tool.t2_loader_shape", "tool.t2_loader_output_invalid", "tool.execution_uncertain", "tool.input_invalid", "tool.input_invalid_after_mutate", "tool.output_invalid_after_mutate", "tool.handler_no_output", "tool.did_not_run", "tool.unreachable", "tool.page_no_answer", "tool.page_timed_out", "tool.output_invalid", "tool.not_loaded_t2", "tool.wait_unknown", "tool.wait_cycle", "tool.after_field", "tool.background_field", "tool.background_started", "tool.late_result", "tool.not_visible", "tool.builtin_not_enabled", "tool.provider_native", "tool.not_registered", "tool.builtin_needs_snapshot", "tool.not_allowed", "tool.not_eligible", "tool.unsupported_type", "tool.agent_call_limit", "tool.agent_failed", "tool.activity_failed", "protocol.not_served", "protocol.profile_type", "protocol.options", "protocol.option_clash", "protocol.base_options", "protocol.id_clash", "protocol.ws_headers", "protocol.builtin_unwritten", "protocol.provider_missing", "protocol.connection", "protocol.part_schema", "protocol.part_invalid", "protocol.key_invalid", "protocol.no_key", "protocol.reply_shape", "protocol.endpoint_url", "protocol.endpoint_host", "protocol.http", "protocol.no_operation", "protocol.definition", "protocol.provider_id_clash", "protocol.history_needed"];
4
+ export declare const LABEL_KEYS: readonly ["provider.decision_failed", "provider.decision_unavailable", "provider.decision_model_missing", "provider.decision_ended", "provider.decision_images_off", "provider.decision_box_model", "provider.budget_exhausted", "provider.adapter_version", "provider.adapter_methods", "provider.adapter_schemas", "provider.fallback_slot", "provider.model_fallback_slot", "provider.host_model", "turn.media_refused_image", "turn.media_refused_video", "turn.media_refused_file", "provider.turn_profile", "provider.model_binding_missing", "provider.session_closed", "provider.settled_call", "provider.session_unavailable", "provider.live_input", "provider.tool_cancel_missing", "provider.kernel_gate", "provider.event_invalid", "provider.response_identity", "provider.credential_resolution", "provider.credential_shape", "provider.stored_continuation", "provider.continuation_mismatch", "provider.continuation_contract", "provider.stateless_history", "provider.events_after_completion", "provider.duplicate_call", "provider.tool_cancel_live", "provider.complete_unavailable", "provider.parallel_tools", "provider.binding_identity", "provider.profile_type", "provider.event_type", "provider.feature", "provider.input_kind", "provider.output_kind", "provider.builtin", "provider.credential_missing", "provider.profile_configuration", "continue.instruction", "canary.bind_note", "user_data.note", "context.note", "taint.blocked", "taint.reason_steered", "taint.reason_tainted", "taint.destination_blocked", "taint.destination_confirm", "advisory.notice_elevated", "advisory.notice_high", "advisory.guidance", "attachments.too_many_files", "attachments.too_many_of_kind", "attachments.file_too_large", "attachments.turn_too_large", "attachments.not_accepted", "attachments.mime_not_allowed", "attachments.limits_unconfigured", "quota.exhausted", "quota.busy", "error.config", "error.request", "error.conflict", "error.not_found", "error.input", "error.action", "error.auth", "error.rate_limit", "error.busy", "error.unsupported", "error.unavailable", "error.bad_response", "error.network", "error.timeout", "error.safety", "error.blocked", "error.declined", "error.failed", "error.cancelled", "error.internal", "repair.default_guidance", "repair.items_guidance", "repair.cut_off_guidance", "repair.reply_cut_off", "repair.call_cut_off", "repair.call_cut_off_guidance", "repair.nothing_written", "repair.nothing_written_guidance", "repair.prompt_header", "repair.prompt_intro", "repair.prompt_instructions", "repair.history_heading", "repair.section_previous_output", "repair.section_validator_rejection", "repair.section_repair_guidance", "repair.section_instructions", "structured.answer_tool", "structured.answer_missing", "structured.cut_off", "structured.not_json", "compaction.request", "compaction.tool_call", "compaction.tool_result", "compaction.tool_files", "decision.box_image", "detect.blocked", "detect.call_blocked", "detect.output_blocked", "detect.shown_blocked", "detect.hint.ids", "detect.hint.financial", "detect.hint.network", "detect.hint.credentials", "detect.hint.email", "detect.hint.phone", "detect.hint.bank_account", "detect.hint.injection", "detect.hint.canary_leak", "detect.hint.prompt_leak", "detect.hint.marker_leak", "detect.hint.ungiven_images", "detect.hint.ungiven_links", "detect.hint.tool_leak", "detect.hint.own", "egress.default_repair_guidance", "egress.refusal", "egress.refusal_cut", "egress.rejection", "egress.rejection_found", "egress.hint_unscannable", "egress.hint_provider_tool_leak", "thought.omitted_image", "thought.omitted_link", "thought.omitted_instructions", "session.abandon_gated", "session.tool_denied", "session.tool_aborted", "session.sign_in", "sign_in.link", "sign_in.pending", "sign_in.done", "sign_in.declined", "sign_in.expired", "sign_in.out_of_scope", "session.gate_expired", "session.provider_state_unowned", "session.conversation_unknown", "session.full", "session.busy", "session.turn_ended", "session.gate_pending", "session.part_skipped", "live.session_ended", "voice.unsupported", "voice.permission", "voice.unavailable", "voice.failed", "voice.empty", "stop.cancelled", "stop.interrupted", "stop.length", "stop.filtered", "stop.provider_error", "stop.stream_incomplete", "stop.step_limit", "stop.answer_missing", "composer.model", "composer.effort", "tool.awaiting_user", "tool.completed_hidden", "tool.t2_loader_needs_snapshot", "tool.t2_loader_shape", "tool.t2_loader_output_invalid", "tool.execution_uncertain", "tool.input_invalid", "tool.hook_failed", "tool.input_invalid_after_mutate", "tool.output_invalid_after_mutate", "tool.handler_no_output", "tool.did_not_run", "tool.unreachable", "tool.page_no_answer", "tool.page_timed_out", "tool.output_invalid", "tool.not_loaded_t2", "tool.wait_unknown", "tool.wait_cycle", "tool.after_field", "tool.background_field", "tool.background_started", "tool.late_result", "tool.not_visible", "tool.builtin_not_enabled", "tool.provider_native", "tool.not_registered", "tool.builtin_needs_snapshot", "tool.not_allowed", "tool.not_eligible", "tool.unsupported_type", "tool.agent_call_limit", "tool.agent_failed", "tool.activity_failed", "protocol.not_served", "protocol.profile_type", "protocol.options", "protocol.option_clash", "protocol.base_options", "protocol.id_clash", "protocol.ws_headers", "protocol.builtin_unwritten", "protocol.provider_missing", "protocol.connection", "protocol.part_schema", "protocol.part_invalid", "protocol.key_invalid", "protocol.no_key", "protocol.reply_shape", "protocol.endpoint_url", "protocol.endpoint_host", "protocol.http", "protocol.no_operation", "protocol.definition", "protocol.provider_id_clash", "protocol.history_needed"];
5
5
  /** One of {@linkcode LABEL_KEYS}. */
6
6
  export type LabelKey = (typeof LABEL_KEYS)[number];
7
7
  /**
@@ -186,6 +186,7 @@ export const LABEL_KEYS = [
186
186
  'tool.t2_loader_output_invalid',
187
187
  'tool.execution_uncertain',
188
188
  'tool.input_invalid',
189
+ 'tool.hook_failed',
189
190
  'tool.input_invalid_after_mutate',
190
191
  'tool.output_invalid_after_mutate',
191
192
  'tool.handler_no_output',
@@ -538,6 +539,7 @@ const DEFAULTS = {
538
539
  'tool.t2_loader_output_invalid': 'T2 loader output validation failed after promotion',
539
540
  'tool.execution_uncertain': 'This action has an unresolved execution. Check the destination before trying it again.',
540
541
  'tool.input_invalid': 'Tool input validation failed',
542
+ 'tool.hook_failed': 'This tool call did not run: the app hit an error before it could start.',
541
543
  'tool.did_not_run': "Tool '{tool}' did not run.",
542
544
  'tool.unreachable': "Sorry, a tool couldn't be reached. Please try again.",
543
545
  'tool.input_invalid_after_mutate': 'Tool input validation failed after mutate',
@@ -767,6 +769,7 @@ export const LABEL_NOTES = {
767
769
  'tool.t2_loader_output_invalid': "Told to the model when the T2 loader's output fails its schema after promotion.",
768
770
  'tool.execution_uncertain': 'Shown when a tool operation has no confirmed outcome and cannot execute again.',
769
771
  'tool.input_invalid': "Told to the model when a tool call's input fails the tool's input schema.",
772
+ 'tool.hook_failed': "Told to the model when a host hook threw before a tool call could start. The hook's own error goes to the host as hook_failed.",
770
773
  'tool.did_not_run': 'Given by runTool and runToolStep for a call that never settled when the invoke gave no error of its own. Takes {tool}.',
771
774
  'tool.unreachable': 'Shown to the user when a tool call never reached its host. Takes {tool}.',
772
775
  'tool.input_invalid_after_mutate': "Told to the model when a tool call's input fails its schema after a guardrail changed it.",
@@ -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
  }
@@ -62,14 +65,26 @@ function stripEvidenceRaw(event) {
62
65
  const { raw: _raw, ...evidence } = event.evidence;
63
66
  return { ...event, evidence };
64
67
  }
68
+ /** A called agent's event, which rides in its call's progress, is copied by the same rule. */
69
+ function nestedForClient(event, options) {
70
+ if (event.type !== 'tool' || event.tool.phase !== 'progress')
71
+ return event;
72
+ const { data } = event.tool;
73
+ if (typeof data !== 'object' || data === null || !('agent' in data) || !('event' in data)) {
74
+ return event;
75
+ }
76
+ const inner = forClient(data.event, options);
77
+ return { ...event, tool: { ...event.tool, data: { ...data, event: inner } } };
78
+ }
65
79
  /**
66
80
  * The copy of an event its reader may have. For a visitor (the default) host-only diagnostics are
67
81
  * stripped, so the copy is safe to forward to browsers or end-user SSE.
68
82
  */
69
83
  function forClient(event, options) {
84
+ const outer = nestedForClient(event, options);
70
85
  let out = options?.reader === 'builder'
71
- ? builderWording(event)
72
- : stripMediaRefused(stripCompactionInternal(stripGuardrailInternal(stripErrorInternal(event))));
86
+ ? builderWording(outer)
87
+ : stripMediaRefused(stripCompactionInternal(stripGuardrailInternal(stripErrorInternal(outer))));
73
88
  if (!options?.includeEvidenceRaw) {
74
89
  out = stripEvidenceRaw(out);
75
90
  }
@@ -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,5 +1,6 @@
1
1
  import { errorCopyText, isAbortError, TheoremError, throwIfAborted, toErrorEvent, } from '../../../guardrails/error.js';
2
2
  import { labelText } from '../../../guardrails/labels.js';
3
+ import { hookCrashFailure, hookFailed } from '../../hook-failure.js';
3
4
  import { nestedTurnModel, resolveRegisteredTurnModel } from '../../provider-dispatch.js';
4
5
  import { profileAllowsInject } from '../../stop.js';
5
6
  import { agentProfileProblem, agentToolOutputOf, splitHostInput, } from '../../tools/agent.js';
@@ -43,17 +44,26 @@ function createAgentCaller(args) {
43
44
  if (hostInput && !req.onAgentCall) {
44
45
  throw new TheoremError('config', `Agent tool "${tool.name}" declares host fields, which need the request's onAgentCall`);
45
46
  }
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
- });
47
+ let shaped;
48
+ try {
49
+ shaped = await req.onAgentCall?.({
50
+ tool: tool.name,
51
+ callId,
52
+ profile: tool.profile,
53
+ input: modelInput,
54
+ ...(hostInput ? { hostInput } : {}),
55
+ caller: caller.id,
56
+ depth: args.depth + 1,
57
+ ...(req.metadata ? { metadata: req.metadata } : {}),
58
+ ...(signal ? { signal } : {}),
59
+ });
60
+ }
61
+ catch (err) {
62
+ throwIfAborted(signal);
63
+ // why: The hook threw before the agent was sent, so no agent turn ran.
64
+ yield hookFailed('onAgentCall', err, { callId, span });
65
+ return { failure: hookCrashFailure(err, labels) };
66
+ }
57
67
  if (shaped && 'refuse' in shaped) {
58
68
  return settled('refused_by_host', 'declined', shaped.refuse);
59
69
  }
@@ -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
  }