@theoremjs/agents 0.3.5-next.932.g295cc67 → 0.3.5-next.935.ga3dc485

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.
@@ -786,7 +786,7 @@ export const LABEL_NOTES = {
786
786
  'tool.wait_cycle': "Told to the model when a call's pre_tool waitFor names calls that cannot settle before it, because they wait for it or run after it. Takes {tool} and {calls}.",
787
787
  'tool.background_field': "What the model reads on the background field of a tool that sets registerTool.background to ask. Read when the tool registers, so a profile's labels do not change it.",
788
788
  'tool.background_started': 'Told to the model when a call goes on after its reply: the call runs in the background and its result comes later. Takes {tool}.',
789
- 'tool.late_result': 'Put in front of a tool call result that a host passes in input.lateResults. Takes {tool}.',
789
+ 'tool.late_result': 'Put in front of a tool call result that a host gives from runTurn.lateResults. Takes {tool}.',
790
790
  'tool.after_field': "What the model reads on the after field of a tool that sets registerTool.after. Read when the tool registers, so a profile's labels do not change it.",
791
791
  'tool.not_visible': 'Told to the model when it calls a tool it cannot see this turn. Takes {tool}.',
792
792
  'tool.builtin_not_enabled': 'Told to the model when it calls a provider builtin not turned on this turn. Takes {tool}.',
@@ -16,12 +16,17 @@ export interface ToolDataRead {
16
16
  */
17
17
  declare function readToolData(content: string): ToolDataRead[];
18
18
  /**
19
- * Whether a role `user` message holds tool results that `input.lateResults` opened. It is no one's
19
+ * Whether a role `user` message holds tool results that `TurnRequest.lateResults` gave. It is no one's
20
20
  * word to the model. A person who types a fence only makes their own reply stricter.
21
21
  */
22
22
  declare function isLateResult(message: TurnHistoryMessage): boolean;
23
- /** The history message `input.lateResults` opens; its metadata names the calls it holds. */
24
- declare function lateResultsMessage(text: string, operationIds: readonly string[]): TurnHistoryMessage;
23
+ /**
24
+ * The history message `TurnRequest.lateResults` lands. Its metadata names the calls it holds, and
25
+ * says when it landed inside a reply rather than opening one.
26
+ */
27
+ declare function lateResultsMessage(text: string, operationIds: readonly string[], inReply: boolean): TurnHistoryMessage;
28
+ /** Whether `message` is a late result that landed inside a reply. Such a message opens no reply. */
29
+ declare function landedInReply(message: TurnHistoryMessage): boolean;
25
30
  /** The calls whose late results a history message holds. */
26
31
  declare function lateResultIds(message: TurnHistoryMessage): string[];
27
- export { isLateResult, lateResultIds, lateResultsMessage, readToolData, TOOL_CLOSE };
32
+ export { isLateResult, landedInReply, lateResultIds, lateResultsMessage, readToolData, TOOL_CLOSE };
@@ -25,7 +25,7 @@ function readToolData(content) {
25
25
  return reads;
26
26
  }
27
27
  /**
28
- * Whether a role `user` message holds tool results that `input.lateResults` opened. It is no one's
28
+ * Whether a role `user` message holds tool results that `TurnRequest.lateResults` gave. It is no one's
29
29
  * word to the model. A person who types a fence only makes their own reply stricter.
30
30
  */
31
31
  function isLateResult(message) {
@@ -33,13 +33,24 @@ function isLateResult(message) {
33
33
  message.content !== undefined &&
34
34
  readToolData(message.content).length > 0);
35
35
  }
36
- /** The history message `input.lateResults` opens; its metadata names the calls it holds. */
37
- function lateResultsMessage(text, operationIds) {
38
- return { role: 'user', content: text, metadata: { lateResults: [...operationIds] } };
36
+ /**
37
+ * The history message `TurnRequest.lateResults` lands. Its metadata names the calls it holds, and
38
+ * says when it landed inside a reply rather than opening one.
39
+ */
40
+ function lateResultsMessage(text, operationIds, inReply) {
41
+ return {
42
+ role: 'user',
43
+ content: text,
44
+ metadata: { lateResults: [...operationIds], ...(inReply ? { lateResultsInReply: true } : {}) },
45
+ };
46
+ }
47
+ /** Whether `message` is a late result that landed inside a reply. Such a message opens no reply. */
48
+ function landedInReply(message) {
49
+ return isLateResult(message) && message.metadata?.lateResultsInReply === true;
39
50
  }
40
51
  /** The calls whose late results a history message holds. */
41
52
  function lateResultIds(message) {
42
53
  const ids = message.metadata?.lateResults;
43
54
  return Array.isArray(ids) ? ids.filter((id) => typeof id === 'string') : [];
44
55
  }
45
- export { isLateResult, lateResultIds, lateResultsMessage, readToolData, TOOL_CLOSE };
56
+ export { isLateResult, landedInReply, lateResultIds, lateResultsMessage, readToolData, TOOL_CLOSE };
@@ -220,6 +220,7 @@ function standaloneBlock(event, idPrefix) {
220
220
  kind: 'late-results',
221
221
  text: event.text,
222
222
  operationIds: event.operationIds,
223
+ inReply: event.inReply,
223
224
  };
224
225
  case 'error':
225
226
  return event.error
@@ -161,7 +161,7 @@ function foldAssistantEvents(history, events, gated) {
161
161
  if (event.type === 'late_results') {
162
162
  flushStep();
163
163
  flushText();
164
- next = [...next, lateResultsMessage(event.text, event.operationIds)];
164
+ next = [...next, lateResultsMessage(event.text, event.operationIds, event.inReply)];
165
165
  continue;
166
166
  }
167
167
  if (event.type === 'stage' && event.injected) {
@@ -238,7 +238,7 @@ function historyFromTranscriptBlocks(blocks) {
238
238
  continue;
239
239
  }
240
240
  if (block.kind === 'late-results') {
241
- history = [...history, lateResultsMessage(block.text, block.operationIds)];
241
+ history = [...history, lateResultsMessage(block.text, block.operationIds, block.inReply)];
242
242
  continue;
243
243
  }
244
244
  if (block.kind === 'structured') {
@@ -242,7 +242,7 @@ export interface GuardrailBlock extends TranscriptBlockBase {
242
242
  guardrail: GuardrailEvent;
243
243
  }
244
244
  /**
245
- * The message `input.lateResults` put in the conversation, as the model read it. Theorem's own
245
+ * The message `TurnRequest.lateResults` put in the conversation, as the model read it. Theorem's own
246
246
  * transcript shows nothing for it: the block keeps it in a history rebuilt from blocks.
247
247
  */
248
248
  export interface LateResultsBlock extends TranscriptBlockBase {
@@ -250,6 +250,8 @@ export interface LateResultsBlock extends TranscriptBlockBase {
250
250
  text: string;
251
251
  /** The calls whose results the message holds. */
252
252
  operationIds: string[];
253
+ /** They landed inside a reply; otherwise they opened one. */
254
+ inReply: boolean;
253
255
  }
254
256
  export interface ErrorBlock extends TranscriptBlockBase {
255
257
  kind: 'error';
@@ -35,10 +35,6 @@ export const REQUEST_FIELDS = withFieldDocs({
35
35
  type: "Partial<Record<'client' | 'server', unknown>>",
36
36
  unset: 'No context',
37
37
  },
38
- 'runTurn.input.lateResults': {
39
- type: 'ToolOperationOutcome[]',
40
- unset: 'No late results',
41
- },
42
38
  'runTurn.input.attachments': {
43
39
  type: 'Array<TurnBlob | TurnMediaRef>',
44
40
  },
@@ -143,6 +139,10 @@ export const REQUEST_FIELDS = withFieldDocs({
143
139
  'runTurn.onStage': {
144
140
  type: 'StageHandler',
145
141
  },
142
+ 'runTurn.lateResults': {
143
+ type: 'LateResultsSource',
144
+ unset: 'No late results',
145
+ },
146
146
  'runTurn.onAgentCall': {
147
147
  type: 'AgentCallHook',
148
148
  unset: 'The agent runs on what the model sent',
@@ -1,15 +1,17 @@
1
1
  import { labelText } from '../../guardrails/labels.js';
2
+ import { landedInReply } from '../../guardrails/tool-fence.js';
2
3
  import { mediaChannelForMime } from '../registry/catalog.js';
3
4
  import { loadTokenEstimator } from './token-estimate.js';
4
5
  /** Effective meter; defaults to `'history'`. */
5
6
  export function compactionMeter(spec) {
6
7
  return spec.meter ?? 'history';
7
8
  }
8
- // why: An exchange starts at each `user` message; system messages before the first one belong to none.
9
+ // why: An exchange starts at each `user` message, except a late result that landed inside a reply;
10
+ // system messages before the first one belong to none.
9
11
  function findExchangeBoundaries(history) {
10
12
  const boundaries = [];
11
13
  for (let i = 0; i < history.length; i++) {
12
- if (history[i].role === 'user') {
14
+ if (history[i].role === 'user' && !landedInReply(history[i])) {
13
15
  boundaries.push(i);
14
16
  }
15
17
  }
@@ -611,7 +611,7 @@ async function* executeSingleAttemptCycle(args) {
611
611
  };
612
612
  return { status: 'terminal' };
613
613
  }
614
- if (beforeEnd.injectCount > 0) {
614
+ if (beforeEnd.injectCount > 0 || beforeEnd.lateLanded) {
615
615
  continue;
616
616
  }
617
617
  break;
@@ -24,7 +24,7 @@ import { endThrownSpan, endTurnSpan, guardrailAttributes, guardrailCheckAttribut
24
24
  import { sumEventTokens, sumTurnTokens } from '../usage.js';
25
25
  import { runAttemptsWithValidation } from './gates.js';
26
26
  import { createAgentCaller, NESTED_THROWS, turnError } from './nested.js';
27
- import { applyTurnStage } from './stages.js';
27
+ import { applyTurnStage, landLateResultsAt, unreadLateResultsAt, } from './stages.js';
28
28
  import { cutConversation, openTurnState, } from './state.js';
29
29
  import { shouldSkipStreamEvent } from './stream.js';
30
30
  function projectForObs(event, policy) {
@@ -265,11 +265,13 @@ async function* emitTurn(args) {
265
265
  ...(args.steers ? { steers: args.steers } : {}),
266
266
  });
267
267
  args.outState.state = state;
268
- if (state.lateResults !== undefined) {
269
- const late = { type: 'late_results', ...state.lateResults };
270
- state.allEmittedEvents.push(late);
271
- yield late;
272
- }
268
+ const opening = { stage: 'pre_turn', step: 0 };
269
+ const late = yield* unreadLateResultsAt(state, profile, {
270
+ ...opening,
271
+ host: generation.host,
272
+ ...(safe.signal ? { signal: safe.signal } : {}),
273
+ });
274
+ yield* landLateResultsAt(state, profile, late, opening);
273
275
  const pre = yield* applyTurnStage({
274
276
  profile,
275
277
  generation,
@@ -1,6 +1,8 @@
1
+ import type { TurnInjectStage } from '../../schema.js';
1
2
  import { type InjectUnit, type StageApplyWarning, type StageCallBag, type StageContext, type StageHandler } from '../../stages.js';
3
+ import type { ToolOperationOutcome } from '../../tools/operation.js';
2
4
  import type { Profile, ResolvedGeneration, TurnEvent, TurnHistoryMessage, TurnStage } from '../../types.js';
3
- import type { StepExecutionState } from './state.js';
5
+ import { type StepExecutionState } from './state.js';
4
6
  export interface ApplyTurnStageArgs extends StageCallBag {
5
7
  profile: Profile;
6
8
  generation: ResolvedGeneration;
@@ -25,6 +27,8 @@ export interface ApplyTurnStageResult {
25
27
  reason?: string;
26
28
  };
27
29
  injectCount: number;
30
+ /** Late results landed at this stage: the model takes another step to read them. */
31
+ lateLanded: boolean;
28
32
  warnings: StageApplyWarning[];
29
33
  }
30
34
  /**
@@ -43,6 +47,23 @@ export declare function steersToLand(state: StepExecutionState, profile: Profile
43
47
  waiting: readonly InjectUnit[];
44
48
  units: InjectUnit[];
45
49
  } | undefined>;
50
+ /** Where a turn asks its late-results source, and whether the model reads another step after it. */
51
+ export interface LateResultsAt {
52
+ stage: TurnInjectStage;
53
+ step: number;
54
+ host: unknown;
55
+ signal?: AbortSignal;
56
+ /** Another model step would pass `maxSteps`: mid-turn, nothing is asked. */
57
+ injectWouldExceedMaxSteps?: boolean;
58
+ }
59
+ /**
60
+ * The late results the turn's source gives at `at` that the conversation does not hold yet. It is
61
+ * asked only where the model reads what lands: as the turn opens, or mid-turn when the profile
62
+ * takes steering and another step fits. A source that throws is reported and gives nothing.
63
+ */
64
+ export declare function unreadLateResultsAt(state: StepExecutionState, profile: Profile, at: LateResultsAt): AsyncGenerator<TurnEvent, ToolOperationOutcome[]>;
65
+ /** Lands `unread` in turn history with the `late_results` event that records where. */
66
+ export declare function landLateResultsAt(state: StepExecutionState, profile: Profile, unread: readonly ToolOperationOutcome[], at: Pick<LateResultsAt, 'stage' | 'step'>): Generator<TurnEvent, boolean>;
46
67
  /**
47
68
  * Runs a turn stage: the host's handler, then the steers waiting for the turn. Both land together,
48
69
  * the host's first; an abort lands neither.
@@ -1,6 +1,8 @@
1
1
  import { throwIfAborted } from '../../../guardrails/error.js';
2
+ import { hookFailed } from '../../hook-failure.js';
2
3
  import { injectedStageEvent, injectMessages, runStage, sanitizeInjects, stageAllowsAffordance, } from '../../stages.js';
3
4
  import { profileAllowsInject } from '../../stop.js';
5
+ import { landLateResults, unreadLateResults } from './state.js';
4
6
  /**
5
7
  * A model call's reply joins turn history. Its text message, whose text begins at `at` in the
6
8
  * attempt's reply, is the one an inject's drop cuts.
@@ -114,6 +116,47 @@ export function* steersToLand(state, profile, stage, injectWouldExceedMaxSteps)
114
116
  }
115
117
  return { waiting, units: next.value };
116
118
  }
119
+ /**
120
+ * The late results the turn's source gives at `at` that the conversation does not hold yet. It is
121
+ * asked only where the model reads what lands: as the turn opens, or mid-turn when the profile
122
+ * takes steering and another step fits. A source that throws is reported and gives nothing.
123
+ */
124
+ export async function* unreadLateResultsAt(state, profile, at) {
125
+ const source = state.lateResults;
126
+ if (!source)
127
+ return [];
128
+ if (at.stage !== 'pre_turn' && (!profileAllowsInject(profile) || at.injectWouldExceedMaxSteps)) {
129
+ return [];
130
+ }
131
+ let given;
132
+ try {
133
+ given = await source({
134
+ stage: at.stage,
135
+ step: at.step,
136
+ host: at.host,
137
+ ...(at.signal ? { signal: at.signal } : {}),
138
+ });
139
+ }
140
+ catch (err) {
141
+ throwIfAborted(at.signal);
142
+ const failed = hookFailed('lateResults', err, { stage: at.stage, span: state.trace.root });
143
+ state.allEmittedEvents.push(failed);
144
+ yield failed;
145
+ return [];
146
+ }
147
+ throwIfAborted(at.signal);
148
+ return unreadLateResults(state, given);
149
+ }
150
+ /** Lands `unread` in turn history with the `late_results` event that records where. */
151
+ export function* landLateResultsAt(state, profile, unread, at) {
152
+ if (unread.length === 0)
153
+ return false;
154
+ const landed = landLateResults(state, unread, profile.labels, at.stage);
155
+ const event = { type: 'late_results', ...landed, stage: at.stage, step: at.step };
156
+ state.allEmittedEvents.push(event);
157
+ yield event;
158
+ return true;
159
+ }
117
160
  /**
118
161
  * Runs a turn stage: the host's handler, then the steers waiting for the turn. Both land together,
119
162
  * the host's first; an abort lands neither.
@@ -142,11 +185,23 @@ export async function* applyTurnStage(args) {
142
185
  ? undefined
143
186
  : yield* steersToLand(state, profile, call.stage, call.injectWouldExceedMaxSteps);
144
187
  const units = [...out.inject, ...(steers?.units ?? [])];
145
- // why: The model goes on after the inject, so it reads the answer it wrote before it.
146
- if (reply && injectMessages(units).length > 0)
188
+ // why: pre_turn's late results land as the turn opens, before this stage runs.
189
+ const lateAt = !out.abort && call.stage === 'before_end' ? { stage: call.stage, step: call.step } : undefined;
190
+ const late = lateAt
191
+ ? yield* unreadLateResultsAt(state, profile, {
192
+ ...lateAt,
193
+ host: host ?? generation.host,
194
+ ...(call.signal ? { signal: call.signal } : {}),
195
+ ...(call.injectWouldExceedMaxSteps ? { injectWouldExceedMaxSteps: true } : {}),
196
+ })
197
+ : [];
198
+ // why: The model goes on after the inject or the late results, so it reads the answer it wrote before them.
199
+ if (reply && (injectMessages(units).length > 0 || late.length > 0)) {
147
200
  recordReply(state, reply, replyAt);
201
+ }
148
202
  const injectCount = yield* applyStageInjects(state, call.stage, units);
149
203
  if (steers)
150
204
  state.steers?.joined(steers.waiting);
151
- return { abort: out.abort, injectCount, warnings: out.warnings };
205
+ const lateLanded = lateAt ? yield* landLateResultsAt(state, profile, late, lateAt) : false;
206
+ return { abort: out.abort, injectCount, lateLanded, warnings: out.warnings };
152
207
  }
@@ -3,12 +3,14 @@ import { type GivenUrlSets } from '../../../guardrails/egress-urls.js';
3
3
  import type { OwnTools } from '../../../guardrails/tool-leak.js';
4
4
  import type { GuardrailHit, TurnTaint } from '../../../guardrails/types.js';
5
5
  import type { SpanHandle } from '../../../observability/trace-span.js';
6
+ import type { TurnInjectStage } from '../../schema.js';
6
7
  import type { AgentCaller } from '../../tools/agent.js';
7
8
  import type { ToolBackgroundSupport } from '../../tools/background.js';
9
+ import type { ToolOperationOutcome } from '../../tools/operation.js';
8
10
  import type { ToolRegistry } from '../../tools/registry.js';
9
11
  import type { SteerQueue } from '../../tools/steer.js';
10
12
  import type { MediaRefused } from '../../turn-events.js';
11
- import type { InteractionPart, ModelBinding, Profile, ResolvedGeneration, TurnEvent, TurnHistoryMessage, TurnRequest, TurnStop, TurnToolResult } from '../../types.js';
13
+ import type { InteractionPart, LateResultsSource, ModelBinding, Profile, ResolvedGeneration, TurnEvent, TurnHistoryMessage, TurnRequest, TurnStop, TurnToolResult } from '../../types.js';
12
14
  import type { ItemFailure } from './schema-validation.js';
13
15
  import type { CallUsage } from './usage.js';
14
16
  interface TurnTraceState {
@@ -34,6 +36,8 @@ interface StepExecutionState {
34
36
  turnStart: number;
35
37
  /** Set by a retry: from then on the model reads this turn only, from `turnStart`. */
36
38
  turnOnly?: boolean;
39
+ /** This run goes on with a reply an earlier run began (`continuesReply`). */
40
+ continuesReply?: boolean;
37
41
  stepCount: number;
38
42
  /** Model calls sent again this turn under the profile's resumption (`executeResumedStep`). */
39
43
  resumes: number;
@@ -67,11 +71,8 @@ interface StepExecutionState {
67
71
  name: string;
68
72
  text: string;
69
73
  };
70
- /** The message `input.lateResults` opened and the calls it holds, until the run can emit it. */
71
- lateResults?: {
72
- text: string;
73
- operationIds: string[];
74
- };
74
+ /** Gives the late results the turn reads at its moments (`TurnRequest.lateResults`). */
75
+ lateResults?: LateResultsSource;
75
76
  /** The canary opening the last provider call ended on, read in front of the next call's reply. */
76
77
  canaryCarry?: string;
77
78
  /** What the last provider call's thoughts ended on, read in front of the next call's thoughts. */
@@ -117,6 +118,22 @@ interface AttemptFlowState {
117
118
  declare function recordStepEvent(event: TurnEvent, state: StepExecutionState): void;
118
119
  /** Append user parts to turn history as one user message (plain text stays a string). */
119
120
  declare function appendUserInput(state: StepExecutionState, parts: readonly InteractionPart[]): void;
121
+ /**
122
+ * Those of `outcomes` the conversation does not hold yet, each once.
123
+ *
124
+ * invariant: A history holds a late result once, however often the host gives it.
125
+ */
126
+ declare function unreadLateResults(state: StepExecutionState, outcomes: readonly ToolOperationOutcome[]): ToolOperationOutcome[];
127
+ /**
128
+ * Puts `unread` (from {@linkcode unreadLateResults}) into turn history as one message, and gives
129
+ * what it put there. A late result is read as a tool's result, so its message is no one's word to
130
+ * the model. Its marks count on each run.
131
+ */
132
+ declare function landLateResults(state: StepExecutionState, unread: readonly ToolOperationOutcome[], labels: Profile['labels'], stage: TurnInjectStage): {
133
+ text: string;
134
+ operationIds: string[];
135
+ inReply: boolean;
136
+ };
120
137
  /**
121
138
  * Step state for one turn. A text turn's history grows inside the turn (tool
122
139
  * steps, stage injects, repair retries), so its opening input moves into turn
@@ -141,4 +158,4 @@ declare function modelHistory(state: StepExecutionState): TurnHistoryMessage[];
141
158
  /** Whether the turn's checkpoint covers less than the conversation the host keeps. */
142
159
  declare function cutConversation(state: StepExecutionState): boolean;
143
160
  export type { AttemptFlowState, PendingItemFix, StepExecutionState, TurnTraceState };
144
- export { appendUserInput, cutConversation, modelHistory, openTurnState, recordStepEvent };
161
+ export { appendUserInput, cutConversation, landLateResults, modelHistory, openTurnState, recordStepEvent, unreadLateResults, };
@@ -2,7 +2,7 @@ import { addFencedDestinations, addGivenDestinations, addResultDestinations, tur
2
2
  import { addSeenUrls, givenUrlSets } from '../../../guardrails/egress-urls.js';
3
3
  import { TheoremError } from '../../../guardrails/error.js';
4
4
  import { labelText } from '../../../guardrails/labels.js';
5
- import { isLateResult, lateResultIds, lateResultsMessage, readToolData, } from '../../../guardrails/tool-fence.js';
5
+ import { isLateResult, landedInReply, lateResultIds, lateResultsMessage, readToolData, } from '../../../guardrails/tool-fence.js';
6
6
  import { isRemoteOrigin, recordTaint, wrapToolData } from '../../../guardrails/tool-result.js';
7
7
  import { originOfTool } from '../../tools/execute.js';
8
8
  import { isFramedToolFailure } from '../../tools/model-text.js';
@@ -28,11 +28,18 @@ function continuesReply({ continueFrom, input }) {
28
28
  return false;
29
29
  return input?.history?.at(-1)?.role === 'tool';
30
30
  }
31
- /** The reply's part of the history. Late results that opened it stand before its first message. */
31
+ /**
32
+ * The reply's part of the history. Late results that opened it stand before its first message; a
33
+ * late result that landed inside it is part of it.
34
+ */
32
35
  function replyTail(history) {
33
- let start = history.findLastIndex((message) => message.role === 'user');
34
- while (start > 0 && isLateResult(history[start - 1]))
36
+ let start = history.findLastIndex((message) => message.role === 'user' && !landedInReply(message));
37
+ while (start > 0) {
38
+ const before = history[start - 1];
39
+ if (!isLateResult(before) || landedInReply(before))
40
+ break;
35
41
  start -= 1;
42
+ }
36
43
  return history.slice(Math.max(start, 0));
37
44
  }
38
45
  /**
@@ -61,23 +68,30 @@ function carryReplyReads(state, history) {
61
68
  }
62
69
  }
63
70
  /**
64
- * A late result is read as a tool's result, so its message is no one's word to the model.
65
- * invariant: A history holds a late result once, however often the host passes it. Its marks count on each run.
71
+ * Those of `outcomes` the conversation does not hold yet, each once.
72
+ *
73
+ * invariant: A history holds a late result once, however often the host gives it.
66
74
  */
67
- function openLateResults(state, outcomes, labels) {
68
- if (outcomes.length === 0)
69
- return;
75
+ function unreadLateResults(state, outcomes) {
70
76
  const read = new Set(state.currentHistory.flatMap(lateResultIds));
71
- const unread = outcomes.filter(({ event }) => {
77
+ return outcomes.filter(({ event }) => {
72
78
  const { operationId } = event.tool;
73
79
  if (!operationId) {
74
80
  // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
75
81
  throw new TheoremError('request', 'A late result needs the operationId of its call');
76
82
  }
77
- return !read.has(operationId);
83
+ if (read.has(operationId))
84
+ return false;
85
+ read.add(operationId);
86
+ return true;
78
87
  });
79
- if (unread.length === 0)
80
- return;
88
+ }
89
+ /**
90
+ * Puts `unread` (from {@linkcode unreadLateResults}) into turn history as one message, and gives
91
+ * what it put there. A late result is read as a tool's result, so its message is no one's word to
92
+ * the model. Its marks count on each run.
93
+ */
94
+ function landLateResults(state, unread, labels, stage) {
81
95
  const blocks = unread.map(({ event, replay }) => {
82
96
  const { name, operationId = '', readBack = '' } = event.tool;
83
97
  const result = replay.modelResult;
@@ -95,10 +109,14 @@ function openLateResults(state, outcomes, labels) {
95
109
  });
96
110
  const text = blocks.map((block) => block.text).join('\n\n');
97
111
  const operationIds = blocks.map((block) => block.operationId);
98
- const message = lateResultsMessage(text, operationIds);
112
+ // why: At the opening, a reply is under way when the person's message came first or an earlier run began it.
113
+ const inReply = stage !== 'pre_turn' ||
114
+ state.continuesReply === true ||
115
+ state.currentHistory.length > state.turnStart;
116
+ const message = lateResultsMessage(text, operationIds, inReply);
99
117
  state.givenUrls.own.add(message);
100
118
  state.currentHistory.push(message);
101
- state.lateResults = { text, operationIds };
119
+ return { text, operationIds, inReply };
102
120
  }
103
121
  /**
104
122
  * Step state for one turn. A text turn's history grows inside the turn (tool
@@ -134,11 +152,14 @@ function openTurnState(args) {
134
152
  };
135
153
  if (profile.type === 'text') {
136
154
  if (args.request && continuesReply(args.request)) {
155
+ state.continuesReply = true;
137
156
  carryReplyReads(state, args.request.input?.history ?? []);
138
157
  }
139
158
  appendUserInput(state, generation.input);
140
159
  generation.input = [];
141
- openLateResults(state, args.request?.input?.lateResults ?? [], profile.labels);
160
+ // why: Only a text turn reads late results: an image or speech call reads its input alone.
161
+ if (args.request?.lateResults)
162
+ state.lateResults = args.request.lateResults;
142
163
  }
143
164
  return state;
144
165
  }
@@ -150,4 +171,4 @@ function modelHistory(state) {
150
171
  function cutConversation(state) {
151
172
  return state.turnOnly === true && state.turnStart > 0;
152
173
  }
153
- export { appendUserInput, cutConversation, modelHistory, openTurnState, recordStepEvent };
174
+ export { appendUserInput, cutConversation, landLateResults, modelHistory, openTurnState, recordStepEvent, unreadLateResults, };
@@ -21,7 +21,7 @@ import { findLast } from '../../util/find-last.js';
21
21
  import { startToolTrace } from '../tool-trace.js';
22
22
  import { startCallTrace } from '../turn-trace.js';
23
23
  import { canDropMedia, dropMedia, refusedReport, restoreMedia, } from './refused-media.js';
24
- import { applyStageInjects, recordReply, steersToLand } from './stages.js';
24
+ import { applyStageInjects, landLateResultsAt, recordReply, steersToLand, unreadLateResultsAt, } from './stages.js';
25
25
  import { modelHistory, recordStepEvent } from './state.js';
26
26
  import { inStep, runSideBySide, stepOrder } from './step-order.js';
27
27
  import { isWithheldOnBlock, StructuredDrafts, yieldProviderEvents, } from './stream.js';
@@ -626,6 +626,15 @@ async function* handleModelCalls(outcome, generation, profile, state, system, {
626
626
  yield* applyStageInjects(state, 'post_tool', steers.units);
627
627
  state.steers?.joined(steers.waiting);
628
628
  }
629
+ // why: Late results land once a step too, after its steers, so a step's results stay together.
630
+ const at = { stage: 'post_tool', step: state.stepCount };
631
+ const late = yield* unreadLateResultsAt(state, profile, {
632
+ ...at,
633
+ host: generation.host,
634
+ ...(signal ? { signal } : {}),
635
+ ...(stages.injectWouldExceedMaxSteps ? { injectWouldExceedMaxSteps: true } : {}),
636
+ });
637
+ yield* landLateResultsAt(state, profile, late, at);
629
638
  }
630
639
  if (cancelled)
631
640
  return false;
@@ -373,7 +373,6 @@ export const FIELD_DOCS = {
373
373
  'runTurn.input.history': 'The earlier messages of the conversation, when the host keeps them.',
374
374
  'runTurn.input.historyTokens': "Your count of the history's tokens, used by compaction that meters history.",
375
375
  'runTurn.input.inputTokens': "Your count of the whole prompt's tokens, used by compaction that meters input before the call.",
376
- 'runTurn.input.lateResults': 'Background tool calls that settled after their turn, as the host stored them. The model reads each as a tool result, and this reply counts it as a remote read when the call was remote. Pass each one once: the turn emits it as a late_results event, so a history built from events holds it.',
377
376
  'runTurn.input.messageId': 'Your id for the user\'s message, shown to the model on its fence as `<user_data id="…">`: 1 to 32 letters, digits, `.`, `_`, `:` or `-`; any other id is refused.',
378
377
  'runTurn.input.options': "The value a person picked for each option in the profile's inputs.options; an option or a value the profile does not declare is refused.",
379
378
  'runTurn.input.repair': 'A reply your host rejected and why, so that the model writes it again.',
@@ -384,6 +383,7 @@ export const FIELD_DOCS = {
384
383
  'runTurn.model': "The model id the turn or session picks from the profile's models; refused unless the profile sets allowModelSelect.",
385
384
  'runTurn.onAgentCall': 'Runs before each agent tool call, to shape the request to the called agent or to refuse the call.',
386
385
  'runTurn.onEvent': "Reads each of the turn's events as it leaves runTurn, before the caller gets it. A throw goes to the caller as hook_failed, which this function does not read, and the turn goes on.",
386
+ 'runTurn.lateResults': 'Your function that gives the background tool calls that settled after their turn, as you stored them. A text turn asks it when it opens, after each step whose calls settled, and once the model has answered. The model reads each result as a tool result, and the turn counts it as a remote read when the call was remote. A result lands once: one the conversation already holds is not read again. Each landing is a late_results event, so a history built from events holds it, and the event names the moment it landed. Once the model has answered, a landing runs another step, so the model answers what it read.',
387
387
  'runTurn.onStage': 'Your function that sees each stage of a text turn or a live session, and can answer with what the stage allows. A throw at pre_tool fails that call. A throw at any other stage is reported as hook_failed, and the turn goes on without its answer.',
388
388
  'runTurn.options': "The value the host's code sets for each option in the profile's identity.options but path; an option or a value the profile does not declare is refused.",
389
389
  'runTurn.pageExecution': 'Host-issued browser dispatch with a claimed operation and correlated result.',
@@ -3,7 +3,7 @@ import { z } from 'zod';
3
3
  import { type ErrorCopies, type GuardrailEvent } from '../guardrails/event-schemas.js';
4
4
  import type { ErrorKind } from '../guardrails/theorem-error.js';
5
5
  import { type JsonObject, type JsonValue } from './json.js';
6
- import { AWAITING_USER_INPUT_STATUS, type CompactionMeter, type CompactionOutcome, type MediaInputKind, type StageApplyWarningCode, type ToolAccess, type ToolAuthType, type ToolPermission, type TurnStage, type TurnStopKind } from './schema.js';
6
+ import { AWAITING_USER_INPUT_STATUS, type CompactionMeter, type CompactionOutcome, type MediaInputKind, type StageApplyWarningCode, type ToolAccess, type ToolAuthType, type ToolPermission, type TurnInjectStage, type TurnStage, type TurnStopKind } from './schema.js';
7
7
  export type { ErrorCopies, ErrorKind, GuardrailEvent };
8
8
  /** A text part of a history message. */
9
9
  export interface InteractionTextPart {
@@ -279,7 +279,7 @@ export type SessionEventOf<K extends SessionEventKind> = Extract<SessionEvent, {
279
279
  kind: K;
280
280
  }>;
281
281
  /** The host hooks whose crash the turn survives and reports as `hook_failed`. */
282
- declare const HOOK_NAMES: readonly ["execution", "background", "onStage", "onEvent", "onAgentCall", "tools.preTool", "tools.t1Policy", "outputs.validation", "compaction.trigger"];
282
+ declare const HOOK_NAMES: readonly ["execution", "background", "onStage", "lateResults", "onEvent", "onAgentCall", "tools.preTool", "tools.t1Policy", "outputs.validation", "compaction.trigger"];
283
283
  /** A host hook a `hook_failed` event names. */
284
284
  export type HookName = (typeof HOOK_NAMES)[number];
285
285
  /** Why a tool call failed, for the builder and for the user. */
@@ -684,13 +684,18 @@ export type TurnEvent = {
684
684
  reason: AttemptReason;
685
685
  }
686
686
  /**
687
- * The message `input.lateResults` put in the conversation, role `user`. It enters a history built
688
- * from events like any other message. `operationIds` are the calls whose results it holds.
687
+ * The message `lateResults` put in the conversation, role `user`. It enters a history built from
688
+ * events like any other message. `operationIds` are the calls whose results it holds; `stage` and
689
+ * `step` are where it landed. `inReply` is true when it landed inside a reply: after the person's
690
+ * message, mid-turn, or as a paused reply went on. Otherwise it opened the reply.
689
691
  */
690
692
  | {
691
693
  type: 'late_results';
692
694
  text: string;
693
695
  operationIds: string[];
696
+ stage: TurnInjectStage;
697
+ step: number;
698
+ inReply: boolean;
694
699
  } | {
695
700
  type: 'media';
696
701
  media: {
@@ -5,7 +5,7 @@ import { providerCheckpointSchema, providerWarningSchema, } from './checkpoint.j
5
5
  import { z } from 'zod';
6
6
  import { errorCopiesSchema, errorKindSchema, guardrailEventSchema, } from '../guardrails/event-schemas.js';
7
7
  import { jsonObjectSchema, jsonValueSchema } from './json.js';
8
- 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';
8
+ 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_INJECT_STAGES, TURN_STAGES, TURN_STOP_KINDS, } from './schema.js';
9
9
  const jsonObject = z.record(z.string(), z.unknown());
10
10
  const nonEmptyText = z.string().trim().min(1);
11
11
  const interactionTextPart = z.object({ type: z.literal('text'), text: z.string() });
@@ -178,6 +178,7 @@ const HOOK_NAMES = [
178
178
  'execution',
179
179
  'background',
180
180
  'onStage',
181
+ 'lateResults',
181
182
  'onEvent',
182
183
  'onAgentCall',
183
184
  'tools.preTool',
@@ -441,6 +442,9 @@ const TURN_EVENTS = {
441
442
  type: z.literal('late_results'),
442
443
  text: z.string(),
443
444
  operationIds: z.array(z.string()),
445
+ stage: z.enum(TURN_INJECT_STAGES),
446
+ step: z.number().int().nonnegative(),
447
+ inReply: z.boolean(),
444
448
  }),
445
449
  media: z.object({
446
450
  type: z.literal('media'),
@@ -1,6 +1,6 @@
1
1
  import type { ProviderCheckpoint, ProviderContinuationPolicy } from './checkpoint.js';
2
2
  import type { JsonObject } from './json.js';
3
- import type { CompactionMeter, CompactionOutcome, CompactionTiming, ContextSender, ContinueStopKind, FieldMeta, KeySlot, KeyVault, LiveActivityHandling, LiveEndSensitivity, LiveStartSensitivity, MediaInputKind, ProfileType, SpeechAudioFormat, StreamMode, SummaryMode, ThinkingLevel, ToolLoadTier, TurnStage, TurnStopKind } from './schema.js';
3
+ import type { CompactionMeter, CompactionOutcome, CompactionTiming, ContextSender, ContinueStopKind, FieldMeta, KeySlot, KeyVault, LiveActivityHandling, LiveEndSensitivity, LiveStartSensitivity, MediaInputKind, ProfileType, SpeechAudioFormat, StreamMode, SummaryMode, ThinkingLevel, ToolLoadTier, TurnInjectStage, TurnStage, TurnStopKind } from './schema.js';
4
4
  import type { StageHandler } from './stages.js';
5
5
  import type { ToolBackgroundService } from './tools/background.js';
6
6
  import type { GateDecision } from './tools/gate-answer.js';
@@ -1034,16 +1034,6 @@ export interface TurnInput {
1034
1034
  voice?: TurnBlob[];
1035
1035
  /** The earlier messages of the conversation, when the host keeps them. */
1036
1036
  history?: TurnHistoryMessage[];
1037
- /**
1038
- * Background tool calls that settled after their turn, as the host stored them. The model reads
1039
- * each as a tool result, and this reply counts it as a remote read when the call was remote. Pass
1040
- * each one once: the turn emits it as a late_results event, so a history built from events holds
1041
- * it.
1042
- *
1043
- * @remarks Tool calls that settled after their turn, as the host stored them. Each counts as read
1044
- * in this reply.
1045
- */
1046
- lateResults?: ToolOperationOutcome[];
1047
1037
  /** A reply your host rejected and why, so that the model writes it again. */
1048
1038
  repair?: TurnRepairRequest;
1049
1039
  /**
@@ -1179,6 +1169,21 @@ export interface AgentRunRequest extends RunControls, ModelChoice {
1179
1169
  }
1180
1170
  /** A request to `runTurn`: the shared controls and the turn's input. */
1181
1171
  export interface TurnRequest extends AgentRunRequest {
1172
+ /**
1173
+ * Your function that gives the background tool calls that settled after their turn, as you
1174
+ * stored them. A text turn asks it when it opens, after each step whose calls settled, and once
1175
+ * the model has answered. The model reads each result as a tool result, and the turn counts it
1176
+ * as a remote read when the call was remote. A result lands once: one the conversation already
1177
+ * holds is not read again. Each landing is a late_results event, so a history built from events
1178
+ * holds it, and the event names the moment it landed. Once the model has answered, a landing
1179
+ * runs another step, so the model answers what it read.
1180
+ *
1181
+ * @remarks Asked only where the model reads what it gives: not mid-turn when the profile's
1182
+ * `turnBehaviour.allowSteering` is false, and not when another step would pass `maxSteps`. What
1183
+ * it gives at a moment it is not asked waits for a later turn. A throw is reported as
1184
+ * hook_failed, and the turn goes on without results.
1185
+ */
1186
+ lateResults?: LateResultsSource;
1182
1187
  /**
1183
1188
  * A session key a provider may use to route and cache this session's calls together.
1184
1189
  *
@@ -1244,6 +1249,72 @@ export interface TurnRequest extends AgentRunRequest {
1244
1249
  /** What the user sent for the turn. */
1245
1250
  input?: TurnInput;
1246
1251
  }
1252
+ /** Where a text turn asks for late results. */
1253
+ export interface LateResultsMoment {
1254
+ /**
1255
+ * `pre_turn` as the turn opens, `post_tool` after a step whose calls settled, `before_end` once
1256
+ * the model has answered.
1257
+ */
1258
+ stage: TurnInjectStage;
1259
+ /** The model steps the turn has taken; 0 as it opens. */
1260
+ step: number;
1261
+ /** The turn's `host`: what the app makes of the request. */
1262
+ host: unknown;
1263
+ signal?: AbortSignal;
1264
+ }
1265
+ /** Gives the late results a turn reads at a moment; see {@linkcode TurnRequest.lateResults}. */
1266
+ export type LateResultsSource = (moment: LateResultsMoment) => readonly ToolOperationOutcome[] | Promise<readonly ToolOperationOutcome[]>;
1267
+ /** A background call's end that the model has not read. */
1268
+ export interface LateResult {
1269
+ /** The id the session keeps the call under. */
1270
+ operationId: string;
1271
+ outcome: ToolOperationOutcome;
1272
+ }
1273
+ /** A chat's ended results that no reply has read, as a {@linkcode LateResultsDecider} is asked. */
1274
+ export interface LateResultsAsk {
1275
+ /** The turn's `host`: what the app makes of the request. */
1276
+ host: unknown;
1277
+ /** The conversation reference the page holds. */
1278
+ conversation: string;
1279
+ results: readonly LateResult[];
1280
+ }
1281
+ /** A background call ended, and what Theorem lets the decider do about it. */
1282
+ export interface LateResultEnded {
1283
+ /** The `host` of the request that started the call. */
1284
+ host: unknown;
1285
+ result: LateResult;
1286
+ /**
1287
+ * Runs a reply to no message in `conversation`, as a page's wake does: the decider's `give` is
1288
+ * asked with `reason: 'wake'`. It runs nothing while a reply waits on gates or answers a
1289
+ * message, and a message posted meanwhile wins. The reference must stay the same across
1290
+ * writes, so a store whose reference changes with each write cannot wake from the server.
1291
+ */
1292
+ wake(conversation: string): Promise<void>;
1293
+ /** Tells the pages open on the session to read the chat again. */
1294
+ notify(): Promise<void>;
1295
+ }
1296
+ /**
1297
+ * Who tells the model that a background call ended. Theorem runs; the decider decides, and it
1298
+ * keeps its own count of what it told, such as a cap or quiet hours.
1299
+ */
1300
+ export interface LateResultsDecider {
1301
+ /**
1302
+ * The results a reply gives the model, by `operationId`. `reason` is `'message'` for a reply to
1303
+ * the person's message and `'wake'` for a reply to no message. Asked once for each reply, before
1304
+ * its model runs. The model reads each result you return once. One you leave out stays for a
1305
+ * later reply. A wake you give nothing runs no reply and leaves no mark.
1306
+ */
1307
+ give(ask: LateResultsAsk & {
1308
+ reason: 'message' | 'wake';
1309
+ }): readonly string[] | Promise<readonly string[]>;
1310
+ /**
1311
+ * Whether a page open on the chat wakes it now. Asked each time a page reads the chat, so it
1312
+ * must change nothing. Say yes only when `give` would give something. Unset, no page wakes it.
1313
+ */
1314
+ due?(ask: LateResultsAsk): boolean | Promise<boolean>;
1315
+ /** A background call ended. Use `wake` to reply from the server, with no page open. */
1316
+ ended?(ended: LateResultEnded): void | Promise<void>;
1317
+ }
1247
1318
  /**
1248
1319
  * How an application runs its turns: the one value its own call sites, its web handler and the
1249
1320
  * studio all use, so they cannot run a turn differently. An app that calls `runTurn` itself
@@ -1263,15 +1334,12 @@ export interface TurnWiring {
1263
1334
  */
1264
1335
  prepare?: (turn: NormalizedTurnRequest) => TurnRequest | Promise<TurnRequest>;
1265
1336
  /**
1266
- * Whether a wake may run: a reply to background results that no person asked for. Your limit on
1267
- * those replies, such as a cap or quiet hours. `host` is the turn's `host`, and `conversation` is
1268
- * the conversation reference the wake was posted with. A wake you refuse is not tried again for
1269
- * the same results; the next message reads them. Unset, every wake runs.
1337
+ * Who tells the model that a background call ended, and when. Theorem runs the replies; this
1338
+ * decides. Unset, the model is never told: no page wakes the chat, and no reply reads a late
1339
+ * result. `pageWakes` from `@theoremjs/web/server` lets the open page wake the chat, for an app
1340
+ * with no server of its own.
1270
1341
  */
1271
- authorizeWake?: (wake: {
1272
- host: unknown;
1273
- conversation: string;
1274
- }) => boolean | Promise<boolean>;
1342
+ lateResultsDecider?: LateResultsDecider;
1275
1343
  }
1276
1344
  /** A profile projected for a client, with its secrets and server-only fields removed. */
1277
1345
  export interface ProjectedProfile extends ProfileModelFields {
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@theoremjs/agents",
3
- "version": "0.3.5-next.932.g295cc67",
3
+ "version": "0.3.5-next.935.ga3dc485",
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",