@theoremjs/agents 0.3.5-next.896.g0fa6df9 → 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 (33) 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/system-lines.js +2 -0
  20. package/esm/src/kernel/tools/activity-label.d.ts +7 -1
  21. package/esm/src/kernel/tools/activity-label.js +47 -2
  22. package/esm/src/kernel/tools/background.d.ts +3 -0
  23. package/esm/src/kernel/tools/coordinate.js +104 -16
  24. package/esm/src/kernel/tools/invoke.js +16 -8
  25. package/esm/src/kernel/tools/resolve.d.ts +4 -0
  26. package/esm/src/kernel/tools/resolve.js +10 -0
  27. package/esm/src/kernel/tools/stage-run.js +12 -1
  28. package/esm/src/kernel/tools/types.d.ts +3 -3
  29. package/esm/src/kernel/turn-events.d.ts +20 -1
  30. package/esm/src/kernel/turn-events.js +19 -0
  31. package/esm/src/kernel/types.d.ts +17 -10
  32. package/esm/src/observability/trace-catalog.js +10 -0
  33. package/package.json +1 -1
@@ -207,7 +207,7 @@ export interface ToolHostHooks<TIn = unknown> {
207
207
  */
208
208
  outputSchema: Record<string, unknown>;
209
209
  /**
210
- * Runs before the host's pre_tool onStage.
210
+ * Runs before the host's pre_tool onStage. A throw fails the call, and the model reads why.
211
211
  *
212
212
  * @remarks Runs before the host's `pre_tool` `onStage`.
213
213
  */
@@ -529,7 +529,7 @@ export interface AgentToolDef extends ToolBase {
529
529
  * them.
530
530
  */
531
531
  hostOnly?: AgentToolChannel[];
532
- /** Runs before the host's pre_tool onStage. */
532
+ /** Runs before the host's pre_tool onStage. A throw fails the call, and the model reads why. */
533
533
  preTool?: ToolHostHooks<AgentToolInput>['preTool'];
534
534
  /**
535
535
  * Gives the model an after field on this tool: the tools called in the same step that must settle
@@ -727,7 +727,7 @@ export interface ProfileToolsSpec {
727
727
  allow: ToolId[];
728
728
  /**
729
729
  * Your function that picks, at the start of each turn, which T2 tools to load up front; the rest
730
- * wait for tools.t2Loader.
730
+ * wait for tools.t2Loader. A throw loads none up front, reported as hook_failed.
731
731
  *
732
732
  * @remarks Returns ids already allowed with `loadTier: 'T2'` to load at turn start. Not supported
733
733
  * on `type: 'live'`.
@@ -270,6 +270,10 @@ export type SessionEventKind = SessionEvent['kind'];
270
270
  export type SessionEventOf<K extends SessionEventKind> = Extract<SessionEvent, {
271
271
  kind: K;
272
272
  }>;
273
+ /** The host hooks whose crash the turn survives and reports as `hook_failed`. */
274
+ declare const HOOK_NAMES: readonly ["execution", "background", "onStage", "onEvent", "tools.t1Policy", "outputs.validation", "compaction.trigger"];
275
+ /** A host hook a `hook_failed` event names. */
276
+ export type HookName = (typeof HOOK_NAMES)[number];
273
277
  /** Why a tool call failed, for the builder and for the user. */
274
278
  export interface ToolFailure {
275
279
  /** What went wrong, for the builder. Stable per failure site. */
@@ -756,7 +760,22 @@ export type TurnEvent = {
756
760
  errorInternal?: string;
757
761
  } | ({
758
762
  type: 'done';
759
- } & DoneEvent) | {
763
+ } & DoneEvent)
764
+ /**
765
+ * A host hook threw, and the turn went on without its answer. A crash at a tool call's gate
766
+ * fails that call instead and is reported on the call's own `tool` event.
767
+ */
768
+ | {
769
+ type: 'hook_failed';
770
+ hook: HookName;
771
+ /** The stage whose `onStage` threw. */
772
+ stage?: TurnStage;
773
+ /** The tool call the hook ran for. */
774
+ callId?: string;
775
+ errorKind: ErrorKind;
776
+ /** The thrown reason and its causes, for the builder only (`forClient` strips it). */
777
+ errorInternal?: string;
778
+ } | {
760
779
  type: 'error';
761
780
  errorKind: ErrorKind;
762
781
  /** Public-safe failure text for hosts to show users: the wording for `errorKind`. */
@@ -166,6 +166,16 @@ const sessionEvent = z.discriminatedUnion('kind', [
166
166
  z.object({ kind: z.enum(['waiting_for_input', 'turn_complete', 'working', 'idle']) }),
167
167
  ]);
168
168
  true;
169
+ /** The host hooks whose crash the turn survives and reports as `hook_failed`. */
170
+ const HOOK_NAMES = [
171
+ 'execution',
172
+ 'background',
173
+ 'onStage',
174
+ 'onEvent',
175
+ 'tools.t1Policy',
176
+ 'outputs.validation',
177
+ 'compaction.trigger',
178
+ ];
169
179
  const toolFailure = z.object({
170
180
  code: z.string(),
171
181
  kind: errorKindSchema,
@@ -488,6 +498,14 @@ const TURN_EVENTS = {
488
498
  tool: toolCallEvent,
489
499
  errorInternal: z.string().optional(),
490
500
  }),
501
+ hook_failed: z.object({
502
+ type: z.literal('hook_failed'),
503
+ hook: z.enum(HOOK_NAMES),
504
+ stage: z.enum(TURN_STAGES).optional(),
505
+ callId: z.string().optional(),
506
+ errorKind: errorKindSchema,
507
+ errorInternal: z.string().optional(),
508
+ }),
491
509
  error: z.object({
492
510
  type: z.literal('error'),
493
511
  errorKind: errorKindSchema,
@@ -519,6 +537,7 @@ const turnEvent = z.union([
519
537
  TURN_EVENTS.stage,
520
538
  TURN_EVENTS.tool_draft,
521
539
  TURN_EVENTS.tool,
540
+ TURN_EVENTS.hook_failed,
522
541
  TURN_EVENTS.error,
523
542
  ]),
524
543
  TURN_EVENTS.done,
@@ -144,7 +144,8 @@ export interface CompactionSpec {
144
144
  */
145
145
  meter?: CompactionMeter;
146
146
  /**
147
- * Your function that decides when to compact, in place of compactAt and maxTokens.
147
+ * Your function that decides when to compact, in place of compactAt and maxTokens. A throw is
148
+ * reported as hook_failed, and compactAt and maxTokens decide.
148
149
  *
149
150
  * @remarks Replaces the default `tokens > compactAt * maxTokens` check.
150
151
  */
@@ -296,7 +297,8 @@ export type ProfileItemCheck = (item: unknown, turn: ItemCheckTurn) => Validatio
296
297
  export interface ProfileItemRule {
297
298
  /**
298
299
  * Your check on one item, given what the tools of the turn returned (turn.toolResults); its error
299
- * is the reason the model reads on a rewrite and the host reads on the removed item.
300
+ * is the reason the model reads on a rewrite and the host reads on the removed item. A throw
301
+ * refuses the item, reported as hook_failed.
300
302
  */
301
303
  check: ProfileItemCheck;
302
304
  /**
@@ -316,7 +318,7 @@ export interface ProfileValidationSpec {
316
318
  * `diagram.mermaid`). Presence/required is owned by the JSON Schema; these run only for required
317
319
  * paths and for optional paths that are present.
318
320
  *
319
- * @catalog 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.
321
+ * @catalog 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.
320
322
  */
321
323
  fields?: Record<string, ProfileValidator>;
322
324
  /**
@@ -1088,11 +1090,15 @@ export interface TurnTraceLink {
1088
1090
  }
1089
1091
  /** What `runTurn` and `runSession` both take: an agent's profile, its model, and the host's hooks and keys. */
1090
1092
  export interface AgentRunRequest extends RunControls, ModelChoice {
1091
- /** Host-owned atomic tool claims and outcomes. Never sent to providers. */
1093
+ /**
1094
+ * Host-owned atomic tool claims and outcomes. Never sent to providers. A throw before the call
1095
+ * runs fails the call. A throw after it ran keeps the result, marks the call uncertain and is
1096
+ * reported as hook_failed. A TheoremError is its answer and ends the turn.
1097
+ */
1092
1098
  execution?: ToolExecutionCoordinator;
1093
1099
  /**
1094
1100
  * Host-issued service for tool calls that go on after their reply. It needs a coordinator with
1095
- * detach. Without it every tool runs inline.
1101
+ * detach. Without it every tool runs inline. A throw from its event goes on the call's own trace.
1096
1102
  */
1097
1103
  background?: ToolBackgroundService;
1098
1104
  /** Host-issued browser dispatch with a claimed operation and correlated result. */
@@ -1164,7 +1170,8 @@ export interface AgentRunRequest extends RunControls, ModelChoice {
1164
1170
  fetch?: typeof fetch;
1165
1171
  /**
1166
1172
  * Your function that sees each stage of a text turn or a live session, and can answer with what
1167
- * the stage allows.
1173
+ * the stage allows. A throw at pre_tool fails that call. A throw at any other stage is reported as
1174
+ * hook_failed, and the turn goes on without its answer.
1168
1175
  *
1169
1176
  * @remarks Text `runTurn` and `runSession` emit stages and apply the returned affordances. A
1170
1177
  * session's is set once.
@@ -1228,13 +1235,13 @@ export interface TurnRequest extends AgentRunRequest {
1228
1235
  */
1229
1236
  stepsTaken?: number;
1230
1237
  /**
1231
- * Reads each of the turn's events as it leaves runTurn, before the caller gets it. A throw ends
1232
- * the turn with that error.
1238
+ * Reads each of the turn's events as it leaves runTurn, before the caller gets it. A throw goes
1239
+ * to the caller as hook_failed, which this function does not read, and the turn goes on.
1233
1240
  *
1234
1241
  * @remarks Reads each of this turn's events as it leaves `runTurn`, before the caller gets it.
1235
1242
  * The app sets it in `TurnWiring.prepare` to act on a turn someone else runs, such as saving the
1236
- * reply when `done` arrives. A throw ends the turn with that error. `invokeTool` does not call
1237
- * it.
1243
+ * reply when `done` arrives. A throw is reported to the caller as `hook_failed`, and the turn
1244
+ * goes on. `invokeTool` does not call it.
1238
1245
  */
1239
1246
  onEvent?: (event: TurnEvent) => void | Promise<void>;
1240
1247
  /**
@@ -649,6 +649,16 @@ const TRACE_EVENTS = {
649
649
  warnings: attr('error', 'Warnings', 'list', 'Warning codes the hooks raised.'),
650
650
  },
651
651
  },
652
+ 'theorem.hook_failed': {
653
+ label: 'Hook failed',
654
+ doc: 'A host hook threw, and the turn went on without its answer.',
655
+ attributes: {
656
+ hook: attr('error', 'Hook', 'id', 'Which host hook threw.'),
657
+ stage: attr('agent', 'Stage', 'text', 'The stage whose hook threw.', TURN_STAGE_OPTIONS),
658
+ error_kind: attr('error', 'Error', 'text', 'The kind of what it threw.', ERROR_KIND_OPTIONS),
659
+ reason: attr('error', 'Reason', 'content', 'What it threw, in its own words.'),
660
+ },
661
+ },
652
662
  'theorem.guardrail': {
653
663
  label: 'Guardrail',
654
664
  doc: 'A guardrail checked some text: what it did, or `allow` for a timed check that let the text through.',
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@theoremjs/agents",
3
- "version": "0.3.5-next.896.g0fa6df9",
3
+ "version": "0.3.5-next.898.gf800d9a",
4
4
  "description": "A flat TypeScript agent kernel for typed profiles, deterministic turn execution, registered tools, provider adapters, guardrails, and host-injected traces.",
5
5
  "keywords": [
6
6
  "agent",