@theoremjs/agents 0.3.5-next.940.g78c83ac → 0.3.5-next.941.g7a0e355

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.
@@ -1,7 +1,7 @@
1
1
  import type { TurnInjectStage } from '../../schema.js';
2
2
  import { type InjectUnit, type StageApplyWarning, type StageCallBag, type StageContext, type StageHandler } from '../../stages.js';
3
3
  import type { ToolOperationOutcome } from '../../tools/operation.js';
4
- import type { Profile, ResolvedGeneration, TurnEvent, TurnHistoryMessage, TurnStage } from '../../types.js';
4
+ import type { Profile, ResolvedGeneration, TurnEvent, TurnHistoryMessage, TurnStage, TurnToolSnapshot } from '../../types.js';
5
5
  import { type StepExecutionState } from './state.js';
6
6
  export interface ApplyTurnStageArgs extends StageCallBag {
7
7
  profile: Profile;
@@ -33,9 +33,10 @@ export interface ApplyTurnStageResult {
33
33
  }
34
34
  /**
35
35
  * Sanitized stage injects extend portable history. An inject whose host says the user has only
36
- * part of the attempt's reply drops the rest first (`StageResult.released`).
36
+ * part of the attempt's reply drops the rest first (`StageResult.released`); the tools it brings
37
+ * go on the turn's list as it lands (`StageResult.promote`).
37
38
  */
38
- export declare function applyStageInjects(state: StepExecutionState, stage: TurnStage, units: readonly InjectUnit[], extra?: {
39
+ export declare function applyStageInjects(state: StepExecutionState, snapshot: TurnToolSnapshot, stage: TurnStage, units: readonly InjectUnit[], extra?: {
39
40
  callId?: string;
40
41
  toolName?: string;
41
42
  }): Generator<TurnEvent, number>;
@@ -2,6 +2,7 @@ import { throwIfAborted } from '../../../guardrails/error.js';
2
2
  import { hookFailed } from '../../hook-failure.js';
3
3
  import { injectedStageEvent, injectMessages, runStage, sanitizeInjects, stageAllowsAffordance, } from '../../stages.js';
4
4
  import { profileAllowsInject } from '../../stop.js';
5
+ import { promoteTurnTools } from '../../tools/resolve.js';
5
6
  import { landLateResults, unreadLateResults } from './state.js';
6
7
  /**
7
8
  * A model call's reply joins turn history. Its text message, whose text begins at `at` in the
@@ -77,14 +78,16 @@ function dropDraft(state, released) {
77
78
  }
78
79
  /**
79
80
  * Sanitized stage injects extend portable history. An inject whose host says the user has only
80
- * part of the attempt's reply drops the rest first (`StageResult.released`).
81
+ * part of the attempt's reply drops the rest first (`StageResult.released`); the tools it brings
82
+ * go on the turn's list as it lands (`StageResult.promote`).
81
83
  */
82
- export function* applyStageInjects(state, stage, units, extra) {
84
+ export function* applyStageInjects(state, snapshot, stage, units, extra) {
83
85
  const inject = injectMessages(units);
84
86
  if (inject.length === 0)
85
87
  return 0;
86
88
  const released = dropDraft(state, releasedOf(units));
87
89
  state.currentHistory.push(...inject);
90
+ promoteTurnTools(state.tools, snapshot, units.flatMap((unit) => unit.promote ?? []));
88
91
  const landed = injectedStageEvent(stage, units, {
89
92
  ...extra,
90
93
  ...(released === undefined ? {} : { released }),
@@ -199,7 +202,7 @@ export async function* applyTurnStage(args) {
199
202
  if (reply && (injectMessages(units).length > 0 || late.length > 0)) {
200
203
  recordReply(state, reply, replyAt);
201
204
  }
202
- const injectCount = yield* applyStageInjects(state, call.stage, units);
205
+ const injectCount = yield* applyStageInjects(state, generation.tools, call.stage, units);
203
206
  if (steers)
204
207
  state.steers?.joined(steers.waiting);
205
208
  const lateLanded = lateAt ? yield* landLateResultsAt(state, profile, late, lateAt) : false;
@@ -460,7 +460,7 @@ function recordProviderToolFailure(state, call, failure) {
460
460
  recordToolModelResult(state, call, modelResult);
461
461
  return event;
462
462
  }
463
- function* applyToolSettlement(settlement, state, call) {
463
+ function* applyToolSettlement(settlement, state, snapshot, call) {
464
464
  if (settlement.aborted) {
465
465
  state.lastStop = stageAbortStop(settlement.aborted);
466
466
  return 'stop_cancelled';
@@ -479,7 +479,7 @@ function* applyToolSettlement(settlement, state, call) {
479
479
  }
480
480
  recordToolModelResult(state, call, settlement.modelResult);
481
481
  if (settlement.pendingInject) {
482
- yield* applyStageInjects(state, 'post_tool', settlement.pendingInject, {
482
+ yield* applyStageInjects(state, snapshot, 'post_tool', settlement.pendingInject, {
483
483
  callId: call.callId,
484
484
  toolName: call.name,
485
485
  });
@@ -611,7 +611,7 @@ async function* handleModelCalls(outcome, generation, profile, state, system, {
611
611
  const settlement = settlements[index];
612
612
  if (!settlement)
613
613
  continue;
614
- const outcome = yield* applyToolSettlement(settlement, state, call);
614
+ const outcome = yield* applyToolSettlement(settlement, state, generation.tools, call);
615
615
  if (outcome === 'stop_cancelled')
616
616
  cancelled = true;
617
617
  if (outcome === 'gated')
@@ -623,7 +623,7 @@ async function* handleModelCalls(outcome, generation, profile, state, system, {
623
623
  if (!cancelled && !gated && !ended && calls.length > 0) {
624
624
  const steers = yield* steersToLand(state, profile, 'post_tool', stages.injectWouldExceedMaxSteps);
625
625
  if (steers) {
626
- yield* applyStageInjects(state, 'post_tool', steers.units);
626
+ yield* applyStageInjects(state, generation.tools, 'post_tool', steers.units);
627
627
  state.steers?.joined(steers.waiting);
628
628
  }
629
629
  // why: Late results land once a step too, after its steers, so a step's results stay together.
@@ -114,7 +114,7 @@ export declare const AWAITING_USER_INPUT_KINDS: readonly ["confirm", "choice", "
114
114
  /** One of {@linkcode AWAITING_USER_INPUT_KINDS}. */
115
115
  export type AwaitingUserInputKind = (typeof AWAITING_USER_INPUT_KINDS)[number];
116
116
  /** Why a stage handler's result was partly or wholly ignored. */
117
- export declare const STAGE_APPLY_WARNING_CODES: readonly ["affordance_not_allowed", "inject_not_allowed", "inject_rejected_max_steps", "inject_invalid_messages", "inject_id_invalid", "inject_released_invalid", "deny_invalid", "confirm_invalid", "mutate_invalid", "label_failed_invalid", "abort_invalid", "wait_for_invalid", "end_not_allowed", "end_invalid", "unknown_field", "result_invalid"];
117
+ export declare const STAGE_APPLY_WARNING_CODES: readonly ["affordance_not_allowed", "inject_not_allowed", "inject_rejected_max_steps", "inject_invalid_messages", "inject_id_invalid", "inject_released_invalid", "inject_promote_invalid", "deny_invalid", "confirm_invalid", "mutate_invalid", "label_failed_invalid", "abort_invalid", "wait_for_invalid", "end_not_allowed", "end_invalid", "unknown_field", "result_invalid"];
118
118
  /** One of {@linkcode STAGE_APPLY_WARNING_CODES}. */
119
119
  export type StageApplyWarningCode = (typeof STAGE_APPLY_WARNING_CODES)[number];
120
120
  /** The `status` of a tool output that asks the user a question. */
@@ -233,6 +233,7 @@ export const STAGE_APPLY_WARNING_CODES = [
233
233
  'inject_invalid_messages',
234
234
  'inject_id_invalid',
235
235
  'inject_released_invalid',
236
+ 'inject_promote_invalid',
236
237
  'deny_invalid',
237
238
  'confirm_invalid',
238
239
  'mutate_invalid',
@@ -3,7 +3,7 @@ import type { StageApplyWarningCode, TurnStage } from './schema.js';
3
3
  import type { TurnStop } from './stop.js';
4
4
  import type { ModelToolResult, ToolFailure, ToolGate } from './tools/types.js';
5
5
  import type { AwaitingUserInput, InjectedMessages, StageApplyWarning, TurnEventOf } from './turn-events.js';
6
- import type { Profile, TurnEvent, TurnHistoryMessage } from './types.js';
6
+ import type { Profile, ToolId, TurnEvent, TurnHistoryMessage } from './types.js';
7
7
  export type { AwaitingUserInput, ToolGate };
8
8
  /**
9
9
  * What a stage handler can ask for: inject messages, abort, deny a tool call, ask for
@@ -79,6 +79,11 @@ export interface StageResult {
79
79
  * after the part they have. Left out, they have all of it.
80
80
  */
81
81
  released?: number;
82
+ /**
83
+ * With `inject`: tools the model may call once the inject lands. Only a tool the turn could load
84
+ * goes on its list (`loadTier: 'T2'`, among the turn's gated tools); any other id is left out.
85
+ */
86
+ promote?: ToolId[];
82
87
  abort?: boolean | {
83
88
  reason?: string;
84
89
  };
@@ -162,6 +167,8 @@ export interface InjectUnit {
162
167
  messages: TurnHistoryMessage[];
163
168
  /** {@linkcode StageResult.released}: the reply text the user has when this inject lands. */
164
169
  released?: number;
170
+ /** {@linkcode StageResult.promote}: the tools the model may call once this inject lands. */
171
+ promote?: ToolId[];
165
172
  }
166
173
  /** A stage handler's result after validation: the parts the turn will act on. */
167
174
  export interface StageApplyOutput {
@@ -30,7 +30,12 @@ export const STAGE_AFFORDANCE_MATRIX = Object.freeze({
30
30
  before_end: Object.freeze(['inject', 'abort']),
31
31
  post_turn: Object.freeze([]),
32
32
  });
33
- const STAGE_RESULT_KEYS = new Set([...STAGE_AFFORDANCES, 'injectId', 'released']);
33
+ const STAGE_RESULT_KEYS = new Set([
34
+ ...STAGE_AFFORDANCES,
35
+ 'injectId',
36
+ 'released',
37
+ 'promote',
38
+ ]);
34
39
  /** True when the affordance is physically allowed at `stage` (ignores inject gate). */
35
40
  export function stageAllowsAffordance(stage, affordance) {
36
41
  return STAGE_AFFORDANCE_MATRIX[stage].includes(affordance);
@@ -115,13 +120,28 @@ function injectReleased(raw, warnings) {
115
120
  warn(warnings, 'inject_released_invalid', 'released', 'released must be a whole number of characters, 0 or more; ignored');
116
121
  return undefined;
117
122
  }
123
+ /** `promote` as a list of tool ids; anything else is a warning, and no tool is promoted. */
124
+ function injectPromote(raw, warnings) {
125
+ if (raw === undefined)
126
+ return undefined;
127
+ if (Array.isArray(raw) && raw.every((id) => typeof id === 'string' && id.trim() !== '')) {
128
+ return raw;
129
+ }
130
+ warn(warnings, 'inject_promote_invalid', 'promote', 'promote must be a list of tool ids; ignored');
131
+ return undefined;
132
+ }
118
133
  /** The inject's messages under its id; an unusable id refuses the inject whole. */
119
134
  function injectUnit(result, warnings) {
120
135
  const messages = coerceHistoryMessages(result.inject, warnings);
121
136
  if (!messages)
122
137
  return undefined;
123
138
  const released = injectReleased(result.released, warnings);
124
- const unit = { messages, ...(released === undefined ? {} : { released }) };
139
+ const promote = injectPromote(result.promote, warnings);
140
+ const unit = {
141
+ messages,
142
+ ...(released === undefined ? {} : { released }),
143
+ ...(promote === undefined ? {} : { promote }),
144
+ };
125
145
  if (result.injectId === undefined)
126
146
  return unit;
127
147
  if (typeof result.injectId === 'string' && result.injectId.trim()) {
@@ -138,6 +158,9 @@ function applyInjectField(result, input, out) {
138
158
  if (result.released !== undefined) {
139
159
  warn(out.warnings, 'inject_released_invalid', 'released', 'released without inject ignored'); // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
140
160
  }
161
+ if (result.promote !== undefined) {
162
+ warn(out.warnings, 'inject_promote_invalid', 'promote', 'promote without inject ignored'); // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
163
+ }
141
164
  return;
142
165
  }
143
166
  const { stage, injectAllowed, injectWouldExceedMaxSteps } = input;
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@theoremjs/agents",
3
- "version": "0.3.5-next.940.g78c83ac",
3
+ "version": "0.3.5-next.941.g7a0e355",
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",