@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.
- package/esm/src/guardrails/canary.js +2 -0
- package/esm/src/host/client-turn.js +5 -2
- package/esm/src/kernel/engine/background.js +4 -1
- package/esm/src/kernel/engine/runner/gates.js +11 -8
- package/esm/src/kernel/engine/runner/mod.d.ts +4 -1
- package/esm/src/kernel/engine/runner/mod.js +47 -11
- package/esm/src/kernel/engine/runner/nested.js +20 -12
- package/esm/src/kernel/engine/runner/schema-validation.d.ts +7 -3
- package/esm/src/kernel/engine/runner/schema-validation.js +31 -11
- package/esm/src/kernel/engine/session/mod.js +2 -2
- package/esm/src/kernel/engine/session/session-trace.d.ts +2 -1
- package/esm/src/kernel/engine/session/session-trace.js +4 -1
- package/esm/src/kernel/field-docs.js +9 -9
- package/esm/src/kernel/hook-failure.d.ts +22 -0
- package/esm/src/kernel/hook-failure.js +49 -0
- package/esm/src/kernel/provider-dispatch.js +3 -1
- package/esm/src/kernel/stages.d.ts +4 -0
- package/esm/src/kernel/stages.js +23 -4
- package/esm/src/kernel/system-lines.js +2 -0
- package/esm/src/kernel/tools/activity-label.d.ts +7 -1
- package/esm/src/kernel/tools/activity-label.js +47 -2
- package/esm/src/kernel/tools/background.d.ts +3 -0
- package/esm/src/kernel/tools/coordinate.js +104 -16
- package/esm/src/kernel/tools/invoke.js +16 -8
- package/esm/src/kernel/tools/resolve.d.ts +4 -0
- package/esm/src/kernel/tools/resolve.js +10 -0
- package/esm/src/kernel/tools/stage-run.js +12 -1
- package/esm/src/kernel/tools/types.d.ts +3 -3
- package/esm/src/kernel/turn-events.d.ts +20 -1
- package/esm/src/kernel/turn-events.js +19 -0
- package/esm/src/kernel/types.d.ts +17 -10
- package/esm/src/observability/trace-catalog.js +10 -0
- 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
|
-
/**
|
|
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
|
|
1232
|
-
* the turn
|
|
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
|
|
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.
|
|
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",
|