@theoremjs/agents 0.0.0-stage → 0.3.1

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

@@ -0,0 +1,543 @@
+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 { 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() });
+true;
+const interactionMediaPart = z.object({
+    type: z.enum(MEDIA_INPUT_KIND_VALUES),
+    mimeType: z.string(),
+    data: z.string(),
+});
+true;
+const interactionMediaRefPart = z.object({
+    type: z.enum(MEDIA_INPUT_KIND_VALUES),
+    mimeType: z.string(),
+    uri: z.string(),
+});
+true;
+const interactionPart = z.union([
+    interactionTextPart,
+    interactionMediaPart,
+    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(),
+    parts: z.array(interactionPart).optional(),
+    tool_calls: z
+        .array(z.object({
+        id: z.string(),
+        type: z.literal('function'),
+        function: z.object({ name: z.string(), arguments: z.string() }),
+    }))
+        .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;
+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({
+    usd: z.number(),
+    upstreamUsd: z.number().optional(),
+    partial: z.literal(true).optional(),
+});
+true;
+const turnGroundingCount = z.object({
+    type: z.string(),
+    count: z.number(),
+    searchQueryCount: z.number().optional(),
+});
+true;
+const turnTokens = z.object({
+    input: z.number(),
+    output: z.number(),
+    thinking: z.number().optional(),
+    toolUse: z.number().optional(),
+    cached: z.number().optional(),
+    cacheWrite: z.number().optional(),
+    total: z.number(),
+    cost: turnCost.optional(),
+    estimated: z.array(z.enum(TURN_TOKEN_SIDES)).optional(),
+    unknownMedia: z
+        .object({ input: z.number().optional(), output: z.number().optional() })
+        .optional(),
+    byModality: z
+        .object({
+        input: z.record(z.string(), z.number()).optional(),
+        output: z.record(z.string(), z.number()).optional(),
+    })
+        .optional(),
+    grounding: z.array(turnGroundingCount).optional(),
+});
+true;
+const turnResponse = z.object({ id: z.string().optional(), model: z.string().optional() });
+true;
+const SOURCE_TYPES = ['web', 'maps'];
+const source = z.object({
+    title: z.string(),
+    uri: z.string(),
+    type: z.enum(SOURCE_TYPES),
+    placeId: z.string().optional(),
+});
+true;
+export const sourceSchema = source;
+const groundingEvent = z.object({
+    metadata: jsonObject.optional(),
+    chunks: z.array(z.unknown()).optional(),
+    searchHtml: z.string().optional(),
+});
+true;
+const evidenceBase = {
+    provider: z.string().min(1),
+    raw: jsonObject.optional(),
+    partial: z.boolean().optional(),
+};
+const providerEvidence = z.discriminatedUnion('kind', [
+    z.object({
+        ...evidenceBase,
+        kind: z.literal('code_execution_call'),
+        code: z.string(),
+        language: z.string().optional(),
+        id: z.string(),
+    }),
+    z.object({
+        ...evidenceBase,
+        kind: z.literal('code_execution_result'),
+        result: z.string().optional(),
+        isError: z.boolean().optional(),
+        callId: z.string().optional(),
+    }),
+    z.object({
+        ...evidenceBase,
+        kind: z.enum(['input_transcription', 'output_transcription']),
+        interim: z.boolean().optional(),
+    }),
+    z.object({ ...evidenceBase, kind: z.enum(['voice_activity', 'url_context']) }),
+    z.object({ ...evidenceBase, kind: z.literal('session_resumption'), resumable: z.boolean() }),
+    z.object({ ...evidenceBase, kind: z.literal('provider_step'), step: z.string() }),
+]);
+true;
+const sessionEnded = z.object({
+    cause: z.literal('go_away'),
+    code: z.number(),
+    closedAfterMs: z.number(),
+    errorKind: errorKindSchema.optional(),
+});
+true;
+const sessionEvent = z.discriminatedUnion('kind', [
+    z.object({ kind: z.literal('closing_soon'), timeLeftMs: z.number().optional() }),
+    z.object({
+        kind: z.literal('ended'),
+        timeLeftMs: z.number().optional(),
+        ended: sessionEnded,
+        message: z.string(),
+    }),
+    z.object({ kind: z.enum(['waiting_for_input', 'turn_complete', 'working', 'idle']) }),
+]);
+true;
+const toolFailure = z.object({
+    code: z.string(),
+    kind: errorKindSchema,
+    message: z.string(),
+    error: z.string().optional(),
+    details: z.unknown().optional(),
+});
+true;
+const toolAuthChallenge = z.object({
+    slot: nonEmptyText,
+    authType: z.enum(TOOL_AUTH_TYPES),
+    service: nonEmptyText,
+    message: nonEmptyText,
+    authorizationUrl: z.string().optional(),
+    state: z.string().optional(),
+    issuer: z.string().optional(),
+    resource: z.string().optional(),
+    requiredScopes: z.array(nonEmptyText).optional(),
+});
+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', '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(),
+    message: z.string(),
+    severity: z.enum(['info', 'warning', 'error']).optional(),
+});
+true;
+const toolTraceStep = z.object({
+    name: z.string(),
+    kind: z.string(),
+    status: z.string(),
+    inputs: jsonObject.optional(),
+    outputs: jsonObject.optional(),
+});
+true;
+const awaitingBase = { status: z.literal(AWAITING_USER_INPUT_STATUS), prompt: nonEmptyText };
+const awaitingUserInput = z.discriminatedUnion('kind', [
+    z.object({
+        ...awaitingBase,
+        kind: z.enum(['confirm', 'text']),
+        options: z.array(nonEmptyText).optional(),
+    }),
+    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(),
+    description: z.string(),
+    parameters: jsonObject,
+});
+true;
+const turnToolSnapshot = z.object({
+    builtins: z.array(z.string()),
+    gated: z.array(z.string()),
+    visible: z.array(z.string()),
+    executable: z.array(z.string()),
+    path: z.string().optional(),
+    sessionPermissions: z.array(z.string()).optional(),
+    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,
+    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() };
+const toolPhaseEvent = z.discriminatedUnion('phase', [
+    z.object({
+        ...toolPhaseBase,
+        phase: z.literal('running'),
+        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 }),
+    z.object({
+        ...toolPhaseBase,
+        phase: z.literal('complete'),
+        output: z.unknown(),
+        awaiting: z.boolean().optional(),
+        readBack: z.string().optional(),
+        parts: z.array(interactionPart).optional(),
+        activityPast: z.string().optional(),
+        tokens: turnTokens.optional(),
+    }),
+    z.object({
+        ...toolPhaseBase,
+        phase: z.literal('gate'),
+        gate: toolGate,
+        readBack: z.string().optional(),
+    }),
+    z.object({
+        ...toolPhaseBase,
+        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])
+    .and(z.object({ operationId: z.string().min(1).max(256).optional() }));
+true;
+const stageApplyWarning = z.object({
+    code: z.enum(STAGE_APPLY_WARNING_CODES),
+    message: z.string(),
+    field: z.string(),
+});
+true;
+const compactionSignal = z.object({
+    needed: z.boolean(),
+    meter: z.enum(COMPACTION_METERS),
+    tokens: z.number(),
+    unknownMedia: z.number(),
+    promptTokens: z.number().optional(),
+    promptTokensEstimated: z.boolean().optional(),
+    history: z.array(turnHistoryMessage),
+});
+true;
+const compactionFailure = z.object({
+    stop: z.enum(TURN_STOP_KINDS).optional(),
+    error: errorKindSchema.optional(),
+    empty: z.literal(true).optional(),
+    unreadable: z.literal(true).optional(),
+});
+true;
+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;
+    if (kind === 'tool' || kind === 'gate') {
+        return tools ? { type: 'done', ...rest, stop: { ...stop, kind }, tools } : undefined;
+    }
+    return { type: 'done', ...rest, stop: { ...stop, kind } };
+}
+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(),
+    compaction: compactionSignal.optional(),
+    interrupted: z.boolean().optional(),
+    interactionId: z.string().optional(),
+};
+const doneEvent = z.union([
+    z.object({
+        ...doneBase,
+        stop: z.object({ kind: snapshotStopKind, native: z.string().optional() }),
+        tools: turnToolSnapshot,
+    }),
+    z.object({
+        ...doneBase,
+        stop: z.object({ kind: otherStopKind, native: z.string().optional() }),
+        tools: z.undefined().optional(),
+    }),
+]);
+/** 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() }),
+    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() }),
+    }),
+    grounding: z.object({ type: z.literal('grounding'), grounding: groundingEvent }),
+    citation: z.object({
+        type: z.literal('citation'),
+        sources: z.array(source),
+        callId: z.string().optional(),
+    }),
+    compaction: z.object({
+        type: z.literal('compaction'),
+        timing: z.literal('before'),
+        meter: z.enum(COMPACTION_METERS),
+        tokensBefore: z.number(),
+        unknownMedia: z.number(),
+        messagesBefore: z.number(),
+        messagesAfter: z.number(),
+        outcome: z.enum(COMPACTION_OUTCOMES),
+        history: z.array(turnHistoryMessage),
+        summary: z.string().optional(),
+        failure: compactionFailure.optional(),
+        droppedMedia: z.number(),
+        tokens: turnTokens.optional(),
+    }),
+    evidence: z.object({
+        type: z.literal('evidence'),
+        evidence: providerEvidence,
+        text: z.string().optional(),
+        sessionResumptionHandle: z.string().optional(),
+    }),
+    tokens: z.object({
+        type: z.literal('tokens'),
+        tokens: turnTokens,
+        interactionId: z.string().optional(),
+    }),
+    session: z.object({
+        type: z.literal('session'),
+        session: sessionEvent,
+        errorInternal: z.string().optional(),
+    }),
+    guardrail: z.object({ type: z.literal('guardrail'), guardrail: guardrailEventSchema }),
+    stage: z.object({
+        type: z.literal('stage'),
+        stage: z.enum(TURN_STAGES),
+        callId: z.string().optional(),
+        toolName: z.string().optional(),
+        callNotStarted: z.boolean().optional(),
+        awaiting: z.boolean().optional(),
+        gate: toolGate.optional(),
+        stop: turnStop.optional(),
+        stageWarnings: z.array(stageApplyWarning).optional(),
+        injected: z
+            .array(z.object({ id: z.string().regex(/\S/) }))
+            .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,
+        errorInternal: z.string().optional(),
+    }),
+    error: z.object({
+        type: z.literal('error'),
+        errorKind: errorKindSchema,
+        error: z.string().optional(),
+        errorCopy: errorCopiesSchema.optional(),
+        errorInternal: z.string().optional(),
+    }),
+    done: doneEvent,
+};
+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,
+        TURN_EVENTS.compaction,
+        TURN_EVENTS.evidence,
+        TURN_EVENTS.tokens,
+        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;
+}