@theoremjs/agents 0.3.4-next.407.gd93ec2c → 0.3.4-next.413.gb7a2b75

package/esm/src/interface/blocks.js

@@ -152,6 +152,36 @@ function appendPromotedToolMedia(blocks, tool, idPrefix, seenUrls) {
         });
     }
 }
+/**
+ * A named inject's user messages as the user's own blocks, where the reply took them in: its
+ * text, then a block per file. A message from anyone else (a host's note) is not the user's to show.
+ */
+function injectedBlocks(inject, idPrefix) {
+    return inject.messages.flatMap((message) => {
+        if (message.role !== 'user')
+            return [];
+        const parts = message.parts ?? [];
+        const text = [message.content ?? '', ...parts.map((part) => ('text' in part ? part.text : ''))]
+            .join('')
+            .trim();
+        return [
+            ...(text ? [{ id: nextBlockId(idPrefix), kind: 'user-text', text }] : []),
+            ...parts.flatMap((part) => 'text' in part
+                ? []
+                : [
+                    {
+                        id: nextBlockId(idPrefix),
+                        kind: part.type === 'audio' ? 'user-voice' : 'user-attachment',
+                        name: part.mimeType,
+                        mimeType: part.mimeType,
+                        ...('data' in part
+                            ? { sizeBytes: Math.floor((part.data.length * 3) / 4), data: part.data }
+                            : { sizeBytes: 0 }),
+                    },
+                ]),
+        ];
+    });
+}
 /** Turns a user draft into transcript blocks: a `user-text` block for the trimmed text, then one block per attachment and per voice clip. */
 function buildUserTurnBlocks(draft, idPrefix = 'user') {
     const blocks = [];
@@ -185,6 +215,39 @@ function buildUserTurnBlocks(draft, idPrefix = 'user') {
     }
     return blocks;
 }
+/** The block an event adds on its own, beside the blocks before it; `undefined` for one that adds none. */
+function standaloneBlock(event, idPrefix) {
+    switch (event.type) {
+        case 'media':
+            return event.media
+                ? {
+                    id: nextBlockId(idPrefix),
+                    kind: 'media',
+                    mimeType: event.media.mimeType,
+                    data: event.media.data,
+                }
+                : undefined;
+        case 'grounding':
+            return { id: nextBlockId(idPrefix), kind: 'grounding', grounding: event.grounding };
+        case 'evidence':
+            return { id: nextBlockId(idPrefix), kind: 'evidence', evidence: event.evidence };
+        case 'error':
+            return event.error
+                ? { id: nextBlockId(idPrefix), kind: 'error', message: event.error }
+                : undefined;
+        case 'done':
+            return {
+                id: nextBlockId(idPrefix),
+                kind: 'turn-done',
+                stop: event.stop,
+                tokens: event.tokens,
+                interactionId: event.interactionId,
+                compaction: event.compaction !== undefined,
+            };
+        default:
+            return undefined;
+    }
+}
 /** Resets only the turn id sequence, so streaming refolds keep stable `turn-*` keys. */
 function foldTurnEvents(events, options = {}) {
     const idPrefix = options.idPrefix ?? 'turn';
@@ -217,33 +280,9 @@ function foldTurnEvents(events, options = {}) {
             case 'structured':
                 settleStructured(blocks, event.structured, idPrefix);
                 break;
-            case 'media':
-                if (event.media) {
-                    blocks.push({
-                        id: nextBlockId(idPrefix),
-                        kind: 'media',
-                        mimeType: event.media.mimeType,
-                        data: event.media.data,
-                    });
-                }
-                break;
-            case 'grounding':
-                blocks.push({
-                    id: nextBlockId(idPrefix),
-                    kind: 'grounding',
-                    grounding: event.grounding,
-                });
-                break;
             case 'citation':
                 foldCitation(blocks, event, idPrefix);
                 break;
-            case 'evidence':
-                blocks.push({
-                    id: nextBlockId(idPrefix),
-                    kind: 'evidence',
-                    evidence: event.evidence,
-                });
-                break;
             case 'guardrail':
                 addGuardrailBlock(blocks, {
                     id: nextBlockId(idPrefix),
@@ -251,27 +290,15 @@ function foldTurnEvents(events, options = {}) {
                     guardrail: event.guardrail,
                 });
                 break;
-            case 'error':
-                if (event.error) {
-                    blocks.push({
-                        id: nextBlockId(idPrefix),
-                        kind: 'error',
-                        message: event.error,
-                    });
-                }
-                break;
-            case 'done':
-                blocks.push({
-                    id: nextBlockId(idPrefix),
-                    kind: 'turn-done',
-                    stop: event.stop,
-                    tokens: event.tokens,
-                    interactionId: event.interactionId,
-                    compaction: event.compaction !== undefined,
-                });
-                break;
-            default:
+            case 'stage':
+                for (const steer of event.injected ?? [])
+                    blocks.push(...injectedBlocks(steer, idPrefix));
                 break;
+            default: {
+                const block = standaloneBlock(event, idPrefix);
+                if (block)
+                    blocks.push(block);
+            }
         }
     }
     return blocks;

package/esm/src/interface/history.js

@@ -165,6 +165,13 @@ function foldAssistantEvents(history, events, gated) {
             textBuf += event.text;
             continue;
         }
+        if (event.type === 'stage' && event.injected) {
+            // why: A steer is a message in the conversation, after what the reply said and did before it.
+            flushStep();
+            flushText();
+            next = [...next, ...event.injected.flatMap((inject) => inject.messages)];
+            continue;
+        }
         if (event.type === 'structured' && event.structured !== undefined) {
             flushStep();
             // why: The streamed text is this reply's JSON as the model wrote it; the structured output is the reply as kept.

package/esm/src/kernel/engine/runner/stages.d.ts

@@ -12,8 +12,6 @@ export interface ApplyTurnStageArgs extends StageCallBag {
     /** Another provider step would exceed maxSteps — reject inject. */
     injectWouldExceedMaxSteps?: boolean;
     host?: unknown;
-    /** `before_end`: the answer the model just wrote, which goes into turn history ahead of an inject. */
-    reply?: readonly TurnHistoryMessage[];
     /** Where that answer's text begins in the attempt's reply. */
     replyAt?: number;
 }

package/esm/src/kernel/engine/runner/stages.js

@@ -93,6 +93,7 @@ export async function* applyTurnStage(args) {
     throwIfAborted(call.signal);
     const run = runStage({
         ...call,
+        ...(reply ? { reply } : {}),
         history: state.currentHistory,
         handlers: onStage ? [onStage] : [],
         guardrails: profile.guardrails,

package/esm/src/kernel/stages.d.ts

@@ -2,7 +2,7 @@ import type { SpanHandle } from '../observability/trace-span.js';
 import type { StageApplyWarningCode, TurnStage } from './schema.js';
 import type { TurnStop } from './stop.js';
 import type { ModelToolResult, ToolFailure, ToolGate } from './tools/types.js';
-import type { AwaitingUserInput, StageApplyWarning, TurnEventOf } from './turn-events.js';
+import type { AwaitingUserInput, InjectedMessages, StageApplyWarning, TurnEventOf } from './turn-events.js';
 import type { Profile, TurnEvent, TurnHistoryMessage } from './types.js';
 export type { AwaitingUserInput, ToolGate };
 /**
@@ -37,6 +37,11 @@ export type StageCallBag = {
     awaiting?: boolean;
     stop?: TurnStop;
     gate?: ToolGate;
+    /**
+     * `before_end` on text: the answer the model just wrote, before any guardrail verdict on it and
+     * not yet in `history`. Its last step wrote no text when no message here carries any.
+     */
+    reply?: readonly TurnHistoryMessage[];
 };
 /** What a stage handler is given: the stage, the step, and what has happened so far. */
 export interface StageContext extends StageCallBag {
@@ -145,9 +150,7 @@ export type StageEventExtra = {
     awaiting?: boolean;
     gate?: ToolGate;
     stop?: TurnStop;
-    injected?: {
-        id: string;
-    }[];
+    injected?: InjectedMessages[];
     released?: number;
 };
 /** Build a stream `stage` event. Unknown extra keys are not copied. */
@@ -155,7 +158,7 @@ export declare function stageEventFields(stage: TurnStage, extra?: Partial<Stage
 export declare function injectMessages(units: readonly InjectUnit[]): TurnHistoryMessage[];
 /**
  * The `stage` event recording that `units` landed, naming the ones the host
- * named, and the reply text the user has when they dropped a draft (`released`);
+ * named with the messages they put in the conversation, and the reply text the user has when they dropped a draft (`released`);
  * `undefined` when there is neither. Emit it where the messages land, never
  * before: an inject that never lands is never reported.
  */

package/esm/src/kernel/stages.js

@@ -328,12 +328,12 @@ export function injectMessages(units) {
 }
 /**
  * The `stage` event recording that `units` landed, naming the ones the host
- * named, and the reply text the user has when they dropped a draft (`released`);
+ * named with the messages they put in the conversation, and the reply text the user has when they dropped a draft (`released`);
  * `undefined` when there is neither. Emit it where the messages land, never
  * before: an inject that never lands is never reported.
  */
 export function injectedStageEvent(stage, units, extra) {
-    const injected = units.flatMap((unit) => (unit.id === undefined ? [] : [{ id: unit.id }]));
+    const injected = units.flatMap((unit) => unit.id === undefined ? [] : [{ id: unit.id, messages: unit.messages }]);
     if (injected.length === 0 && extra?.released === undefined)
         return undefined;
     return stageEventFields(stage, { ...extra, ...(injected.length > 0 ? { injected } : {}) });

package/esm/src/kernel/turn-events.d.ts

@@ -67,6 +67,14 @@ export interface TurnHistoryMessage {
 }
 /** The schema a history message parses against. */
 export declare const turnHistoryMessageSchema: z.ZodType<TurnHistoryMessage>;
+/**
+ * A named inject as it landed: the host's id for it and the messages it added to the conversation,
+ * after the `injected` guardrails, so a steer reads as the model read it.
+ */
+export interface InjectedMessages {
+    id: string;
+    messages: TurnHistoryMessage[];
+}
 /** Why a turn or live utterance ended. */
 export interface TurnStop {
     kind: TurnStopKind;
@@ -686,10 +694,8 @@ export type TurnEvent = {
     stop?: TurnStop;
     /** Stage result fields the kernel dropped. */
     stageWarnings?: StageApplyWarning[];
-    /** The named injects (`StageResult.injectId`) that landed in the conversation at this stage. */
-    injected?: {
-        id: string;
-    }[];
+    /** The named injects (`StageResult.injectId`) that landed in the conversation at this stage, each with the messages it added. */
+    injected?: InjectedMessages[];
     /**
      * An inject at this stage dropped a draft the user never got: of the reply text since the
      * turn began or its last `attempt`, only the first `released` characters stay the reply.

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

@@ -461,7 +461,7 @@ const TURN_EVENTS = {
         stop: turnStop.optional(),
         stageWarnings: z.array(stageApplyWarning).optional(),
         injected: z
-            .array(z.object({ id: z.string().regex(/\S/) }))
+            .array(z.object({ id: z.string().regex(/\S/), messages: z.array(turnHistoryMessage) }))
             .min(1)
             .optional(),
         released: z.number().int().nonnegative().optional(),

package/esm/src/kernel/types.d.ts

@@ -5,8 +5,8 @@ import type { StageHandler } from './stages.js';
 import type { GateDecision } from './tools/gate-answer.js';
 import type { PageToolExecution, ToolExecutionCoordinator } from './tools/operation.js';
 import type { AgentCall, AgentCallHook, AgentCallRequest, AgentToolDef, AgentToolInput, AgentToolOutput, HostProfileToolsSpec, InvokeToolRequest, InvokeToolResume, InvokeToolStepCall, InvokeToolStepRequest, LiveProfileToolsSpec, ModelToolResult, PageAnswer, ProfileToolsSpec, RegisteredTool, ToolCallEvent, ToolFailure, ToolGate, ToolLoadContext, ToolPolicy, TurnToolSnapshot, WireFunctionTool } from './tools/types.js';
-import type { AttemptReason, CallDone, CompactionFailure, CompactionResult, CompactionSignal, DoneFields, GroundingEvent, InteractionMediaPart, InteractionMediaRefPart, InteractionPart, InteractionTextPart, InvalidField, ModelEvent, ProviderEvidence, RemovedItem, SessionEnded, SessionEvent, SessionEventKind, SessionEventOf, Source, TurnCost, TurnEvent, TurnEventOf, TurnEventType, TurnGroundingCount, TurnHistoryMessage, TurnResponse, TurnTokenSide, TurnTokens } from './turn-events.js';
-export type { AgentCall, AgentCallHook, AgentCallRequest, AgentToolDef, AgentToolInput, AgentToolOutput, AttemptReason, CacheMode, CacheTtl, CallDone, CompactionFailure, CompactionMeter, CompactionOutcome, CompactionResult, CompactionSignal, CompactionTiming, ContinueStopKind, DoneFields, FieldMeta, GroundingEvent, HostProfileToolsSpec, InteractionMediaPart, InteractionMediaRefPart, InteractionPart, InteractionTextPart, InvalidField, InvokeToolRequest, InvokeToolResume, InvokeToolStepCall, InvokeToolStepRequest, KeySlot, KeyVault, LiveActivityHandling, LiveEndSensitivity, LiveProfileToolsSpec, LiveStartSensitivity, MediaInputKind, ModelEvent, ProfileToolsSpec, ProfileType, ProviderEvidence, RegisteredTool, RemovedItem, SessionEnded, SessionEvent, SessionEventKind, SessionEventOf, Source, SpeechAudioFormat, StreamMode, SummaryMode, ThinkingLevel, ToolCallEvent, ToolFailure, ToolGate, ToolLoadContext, ToolLoadTier, ToolPolicy, TurnCost, TurnEvent, TurnEventOf, TurnEventType, TurnGroundingCount, TurnHistoryMessage, TurnResponse, TurnStage, TurnStopKind, TurnTokenSide, TurnTokens, TurnToolSnapshot, WireFunctionTool, };
+import type { AttemptReason, CallDone, CompactionFailure, CompactionResult, CompactionSignal, DoneFields, GroundingEvent, InjectedMessages, InteractionMediaPart, InteractionMediaRefPart, InteractionPart, InteractionTextPart, InvalidField, ModelEvent, ProviderEvidence, RemovedItem, SessionEnded, SessionEvent, SessionEventKind, SessionEventOf, Source, TurnCost, TurnEvent, TurnEventOf, TurnEventType, TurnGroundingCount, TurnHistoryMessage, TurnResponse, TurnTokenSide, TurnTokens } from './turn-events.js';
+export type { AgentCall, AgentCallHook, AgentCallRequest, AgentToolDef, AgentToolInput, AgentToolOutput, AttemptReason, CacheMode, CacheTtl, CallDone, CompactionFailure, CompactionMeter, CompactionOutcome, CompactionResult, CompactionSignal, CompactionTiming, ContinueStopKind, DoneFields, FieldMeta, GroundingEvent, HostProfileToolsSpec, InjectedMessages, InteractionMediaPart, InteractionMediaRefPart, InteractionPart, InteractionTextPart, InvalidField, InvokeToolRequest, InvokeToolResume, InvokeToolStepCall, InvokeToolStepRequest, KeySlot, KeyVault, LiveActivityHandling, LiveEndSensitivity, LiveProfileToolsSpec, LiveStartSensitivity, MediaInputKind, ModelEvent, ProfileToolsSpec, ProfileType, ProviderEvidence, RegisteredTool, RemovedItem, SessionEnded, SessionEvent, SessionEventKind, SessionEventOf, Source, SpeechAudioFormat, StreamMode, SummaryMode, ThinkingLevel, ToolCallEvent, ToolFailure, ToolGate, ToolLoadContext, ToolLoadTier, ToolPolicy, TurnCost, TurnEvent, TurnEventOf, TurnEventType, TurnGroundingCount, TurnHistoryMessage, TurnResponse, TurnStage, TurnStopKind, TurnTokenSide, TurnTokens, TurnToolSnapshot, WireFunctionTool, };
 /** A host-chosen key naming one model binding in a profile's `models`. */
 export type ModelId = string;
 /** The id of a provider-side tool such as web search. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@theoremjs/agents",
-  "version": "0.3.4-next.407.gd93ec2c",
+  "version": "0.3.4-next.413.gb7a2b75",
   "description": "A flat TypeScript agent kernel for typed profiles, deterministic turn execution, registered tools, provider adapters, guardrails, and host-injected traces.",
   "keywords": [
     "agent",