@theoremjs/agents 0.3.0 → 0.3.2

package/esm/src/kernel/turn-events.js

@@ -1,9 +1,11 @@
-// Each type is paired with a zod schema checked against it (`Equals`), so a field in one and
+import { providerCheckpointSchema, providerWarningSchema, } from './checkpoint.js';
+// invariant: Each type is paired with a zod schema checked against it (`Equals`), so a field in one and
 // not the other fails the build. Schemas are plain `z.object`, never `.strict()`: an unlisted
 // field is dropped. An unmapped provider step is `evidence` of kind `provider_step`.
 import { z } from 'zod';
 import { errorCopiesSchema, errorKindSchema, guardrailEventSchema, } from '../guardrails/event-schemas.js';
-import { AWAITING_USER_INPUT_STATUS, COMPACTION_METERS, COMPACTION_OUTCOMES, MEDIA_INPUT_KIND_VALUES, PROVIDERS, STAGE_APPLY_WARNING_CODES, TOOL_AUTH_TYPES, TOOL_PERMISSION, TURN_STAGES, TURN_STOP_KINDS, } from './schema.js';
+import { jsonObjectSchema, jsonValueSchema } from './json.js';
+import { AWAITING_USER_INPUT_STATUS, COMPACTION_METERS, COMPACTION_OUTCOMES, MEDIA_INPUT_KIND_VALUES, STAGE_APPLY_WARNING_CODES, TOOL_ACCESS, TOOL_AUTH_TYPES, TOOL_PERMISSION, TURN_STAGES, TURN_STOP_KINDS, } from './schema.js';
 const jsonObject = z.record(z.string(), z.unknown());
 const nonEmptyText = z.string().trim().min(1);
 const interactionTextPart = z.object({ type: z.literal('text'), text: z.string() });
@@ -26,6 +28,19 @@ const interactionPart = z.union([
     interactionMediaRefPart,
 ]);
 true;
+export const interactionPartSchema = interactionPart;
+const reasoningOrigin = z.object({
+    protocol: z.string().min(1),
+    provider: z.string().min(1).optional(),
+    apiId: z.string().min(1).optional(),
+});
+true;
+export const reasoningPartSchema = z.object({
+    text: z.string().optional(),
+    data: jsonValueSchema,
+    origin: reasoningOrigin,
+});
+true;
 const turnHistoryMessage = z.object({
     role: z.enum(['system', 'user', 'assistant', 'tool']),
     content: z.string().optional(),
@@ -35,16 +50,21 @@ const turnHistoryMessage = z.object({
         id: z.string(),
         type: z.literal('function'),
         function: z.object({ name: z.string(), arguments: z.string() }),
-        thoughtSignature: z.string().optional(),
     }))
         .optional(),
+    reasoning: z.array(reasoningPartSchema).optional(),
     tool_call_id: z.string().optional(),
     name: z.string().optional(),
     metadata: jsonObject.optional(),
 });
 true;
+/** The schema a history message parses against. */
 export const turnHistoryMessageSchema = turnHistoryMessage;
-const turnStop = z.object({ kind: z.enum(TURN_STOP_KINDS), native: z.string().optional() });
+export const turnStopSchema = z.object({
+    kind: z.enum(TURN_STOP_KINDS),
+    native: z.string().optional(),
+});
+const turnStop = turnStopSchema;
 true;
 const TURN_TOKEN_SIDES = ['input', 'output'];
 const turnCost = z.object({
@@ -99,7 +119,7 @@ const groundingEvent = z.object({
 });
 true;
 const evidenceBase = {
-    provider: z.enum(PROVIDERS),
+    provider: z.string().min(1),
     raw: jsonObject.optional(),
     partial: z.boolean().optional(),
 };
@@ -167,15 +187,19 @@ const toolAuthChallenge = z.object({
 });
 true;
 const toolGateBase = {
+    preparedArguments: z.record(z.string(), z.unknown()).optional(),
     tool: nonEmptyText,
     permission: z.enum(TOOL_PERMISSION).optional(),
     summary: nonEmptyText.optional(),
+    request: nonEmptyText.optional(),
+    access: z.enum(TOOL_ACCESS).optional(),
 };
 const toolGate = z.discriminatedUnion('kind', [
-    z.object({ ...toolGateBase, kind: z.enum(['confirmation', 'permission']) }),
+    z.object({ ...toolGateBase, kind: z.enum(['confirmation', 'permission', 'page']) }),
     z.object({ ...toolGateBase, kind: z.literal('auth'), authChallenge: toolAuthChallenge }),
 ]);
 true;
+/** The schema a tool gate parses against. */
 export const toolGateSchema = toolGate;
 const toolWarning = z.object({
     code: z.string(),
@@ -201,7 +225,12 @@ const awaitingUserInput = z.discriminatedUnion('kind', [
     z.object({ ...awaitingBase, kind: z.literal('choice'), options: z.array(nonEmptyText).min(1) }),
 ]);
 true;
+/** The schema a pause for user input parses against. */
 export const awaitingUserInputSchema = awaitingUserInput;
+/** True when a tool output asks the turn to pause for the user. */
+export function isAwaitingUserInput(output) {
+    return awaitingUserInputSchema.safeParse(output).success;
+}
 const wireFunctionTool = z.object({
     type: z.literal('function'),
     name: z.string(),
@@ -219,14 +248,20 @@ const turnToolSnapshot = z.object({
     wire: z.array(wireFunctionTool),
 });
 true;
+/** The schema a tool snapshot parses against. */
 export const turnToolSnapshotSchema = turnToolSnapshot;
+export const gateReferenceSchema = z.strictObject({
+    callId: z.string().min(1),
+    operationId: z.string().min(1).max(256),
+});
 const toolEventBase = { name: z.string(), callId: z.string() };
 const toolCallRequest = z.object({
     ...toolEventBase,
     phase: z.undefined().optional(),
     arguments: jsonObject,
-    thoughtSignature: z.string().min(1).optional(),
+    reasoning: z.array(reasoningPartSchema).optional(),
     stepId: z.string().min(1).optional(),
+    stepCallCount: z.number().int().min(1).optional(),
 });
 true;
 const toolPhaseBase = { ...toolEventBase, at: z.number() };
@@ -237,7 +272,14 @@ const toolPhaseEvent = z.discriminatedUnion('phase', [
         edited: z.object({ from: jsonObject, to: jsonObject }).optional(),
         activity: z.string().optional(),
     }),
+    z.object({
+        ...toolPhaseBase,
+        phase: z.literal('dispatch'),
+        grantId: z.string().min(1),
+        arguments: jsonObject,
+    }),
     z.object({ ...toolPhaseBase, phase: z.literal('progress'), data: z.unknown() }),
+    z.object({ ...toolPhaseBase, phase: z.literal('draft'), text: z.string() }),
     z.object({ ...toolPhaseBase, phase: z.literal('trace'), step: toolTraceStep }),
     z.object({ ...toolPhaseBase, phase: z.literal('artifact'), artifact: z.unknown() }),
     z.object({ ...toolPhaseBase, phase: z.literal('warning'), warning: toolWarning }),
@@ -249,6 +291,7 @@ const toolPhaseEvent = z.discriminatedUnion('phase', [
         readBack: z.string().optional(),
         parts: z.array(interactionPart).optional(),
         activityPast: z.string().optional(),
+        tokens: turnTokens.optional(),
     }),
     z.object({
         ...toolPhaseBase,
@@ -261,11 +304,15 @@ const toolPhaseEvent = z.discriminatedUnion('phase', [
         phase: z.literal('error'),
         failure: toolFailure,
         readBack: z.string().optional(),
+        activityPast: z.string().optional(),
+        tokens: turnTokens.optional(),
     }),
     z.object({ ...toolPhaseBase, phase: z.literal('cancel') }),
 ]);
 true;
-const toolCallEvent = z.union([toolPhaseEvent, toolCallRequest]);
+const toolCallEvent = z
+    .union([toolPhaseEvent, toolCallRequest])
+    .and(z.object({ operationId: z.string().min(1).max(256).optional() }));
 true;
 const stageApplyWarning = z.object({
     code: z.enum(STAGE_APPLY_WARNING_CODES),
@@ -294,6 +341,7 @@ const TOOL_SNAPSHOT_STOP_KINDS = [
     'tool',
     'gate',
 ];
+/** Builds the `done` event from a model call's end, or `undefined` when it carries no stop. */
 export function turnDoneOf(done, tools) {
     const { stop, ...rest } = done;
     const { kind } = stop;
@@ -305,6 +353,7 @@ export function turnDoneOf(done, tools) {
 const snapshotStopKind = z.enum(TOOL_SNAPSHOT_STOP_KINDS);
 const otherStopKind = z.enum(TURN_STOP_KINDS).exclude(TOOL_SNAPSHOT_STOP_KINDS);
 const doneBase = {
+    providerState: providerCheckpointSchema.optional(),
     type: z.literal('done'),
     tokens: turnTokens.optional(),
     traceparent: z.string().optional(),
@@ -326,9 +375,39 @@ const doneEvent = z.union([
 ]);
 /** Each kind's own schema: a wire parser checks a line against its kind's alone, so a failure names the field that broke. */
 const TURN_EVENTS = {
+    provider_checkpoint: z.object({
+        type: z.literal('provider_checkpoint'),
+        providerState: providerCheckpointSchema,
+        history: z.array(turnHistoryMessageSchema).optional(),
+    }),
+    provider_warning: z.object({
+        type: z.literal('provider_warning'),
+        warning: providerWarningSchema,
+    }),
     text: z.object({ type: z.literal('text'), text: z.string() }),
     thought: z.object({ type: z.literal('thought'), text: z.string() }),
-    structured: z.object({ type: z.literal('structured'), structured: z.unknown() }),
+    custom: z.object({
+        type: z.literal('custom'),
+        kind: z.string().min(1),
+        data: jsonObjectSchema,
+    }),
+    structured: z.object({
+        type: z.literal('structured'),
+        structured: z.unknown(),
+        removed: z
+            .array(z.object({ path: z.string(), reason: z.string(), item: z.unknown() }))
+            .optional(),
+        failed: z.array(z.object({ path: z.string(), error: z.string() })).optional(),
+    }),
+    structured_draft: z.object({
+        type: z.literal('structured_draft'),
+        text: z.string(),
+    }),
+    attempt: z.object({
+        type: z.literal('attempt'),
+        attempt: z.number().int().positive(),
+        reason: z.enum(['validation', 'egress']),
+    }),
     media: z.object({
         type: z.literal('media'),
         media: z.object({ mimeType: z.string(), data: z.string() }),
@@ -386,6 +465,12 @@ const TURN_EVENTS = {
             .min(1)
             .optional(),
     }),
+    tool_draft: z.object({
+        type: z.literal('tool_draft'),
+        callId: z.string().min(1),
+        name: z.string(),
+        text: z.string(),
+    }),
     tool: z.object({
         type: z.literal('tool'),
         tool: toolCallEvent,
@@ -402,9 +487,14 @@ const TURN_EVENTS = {
 };
 const turnEvent = z.union([
     z.discriminatedUnion('type', [
+        TURN_EVENTS.provider_warning,
+        TURN_EVENTS.provider_checkpoint,
         TURN_EVENTS.text,
         TURN_EVENTS.thought,
+        TURN_EVENTS.custom,
         TURN_EVENTS.structured,
+        TURN_EVENTS.structured_draft,
+        TURN_EVENTS.attempt,
         TURN_EVENTS.media,
         TURN_EVENTS.grounding,
         TURN_EVENTS.citation,
@@ -414,12 +504,40 @@ const turnEvent = z.union([
         TURN_EVENTS.session,
         TURN_EVENTS.guardrail,
         TURN_EVENTS.stage,
+        TURN_EVENTS.tool_draft,
         TURN_EVENTS.tool,
         TURN_EVENTS.error,
     ]),
     TURN_EVENTS.done,
 ]);
 true;
+/** The schema any turn event parses against. */
 export const turnEventSchema = turnEvent;
 /** Every `TurnEvent` kind and its schema: a wire parser tells a kind it doesn't know from a malformed one it does. */
 export const TURN_EVENT_SCHEMAS = TURN_EVENTS;
+/** Events that make up a reply, and that an `attempt` throws away. */
+function isReply(event) {
+    return (event.type === 'text' ||
+        event.type === 'media' ||
+        event.type === 'structured' ||
+        event.type === 'structured_draft');
+}
+/**
+ * `events` without the replies a retry threw away: each `attempt` drops the text, media and
+ * structured output before it, back to the turn's start or its last `done`. Tool calls, thoughts
+ * and everything else stay, since they happened.
+ */
+export function keptReply(events) {
+    const kept = [];
+    let turnStart = 0;
+    for (const event of events) {
+        if (event.type === 'attempt') {
+            const before = kept.splice(turnStart);
+            kept.push(...before.filter((each) => !isReply(each)));
+        }
+        kept.push(event);
+        if (event.type === 'done')
+            turnStart = kept.length;
+    }
+    return kept;
+}