@theoremjs/agents 0.3.5-next.940.g78c83ac → 0.3.5-next.943.g77aa4ba
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.
- package/esm/src/kernel/engine/runner/stages.d.ts +4 -3
- package/esm/src/kernel/engine/runner/stages.js +6 -3
- package/esm/src/kernel/engine/runner/steps.js +4 -4
- package/esm/src/kernel/mod.d.ts +1 -0
- package/esm/src/kernel/mod.js +1 -0
- package/esm/src/kernel/schema.d.ts +1 -1
- package/esm/src/kernel/schema.js +1 -0
- package/esm/src/kernel/stages.d.ts +8 -1
- package/esm/src/kernel/stages.js +25 -2
- package/esm/src/kernel/tools/call-order.d.ts +8 -0
- package/esm/src/kernel/tools/call-order.js +27 -0
- package/esm/src/kernel/tools/operation.js +1 -0
- package/package.json +1 -1
|
@@ -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.
|
package/esm/src/kernel/mod.d.ts
CHANGED
|
@@ -65,6 +65,7 @@ export { systemPromptProblem } from './system-parts.js';
|
|
|
65
65
|
export { activityLabelProblem } from './tools/activity-label.js';
|
|
66
66
|
export { agentToolInputFor, agentToolOutput } from './tools/agent.js';
|
|
67
67
|
export type { ToolBackground, ToolBackgroundCall, ToolBackgroundHandle, ToolBackgroundService, ToolBackgroundSettled, ToolSteerReceipt, ToolSteerRefusal, } from './tools/background.js';
|
|
68
|
+
export { declaredInputSchema } from './tools/call-order.js';
|
|
68
69
|
export type { StatedToolFailure } from './tools/failed.js';
|
|
69
70
|
export { ToolFailed } from './tools/failed.js';
|
|
70
71
|
export { type AnsweredGate, answerGatedCall, GATE_DECISIONS, type GateAnswerRequest, type GateDecision, gateExpired, type HeldGatedCall, resolveGateTtlMs, sessionPermissionsAfterApproval, type ToolGateAuth, } from './tools/gate-answer.js';
|
package/esm/src/kernel/mod.js
CHANGED
|
@@ -39,6 +39,7 @@ export { systemLinesProblem, systemReading } from './system-lines.js';
|
|
|
39
39
|
export { systemPromptProblem } from './system-parts.js';
|
|
40
40
|
export { activityLabelProblem } from './tools/activity-label.js';
|
|
41
41
|
export { agentToolInputFor, agentToolOutput } from './tools/agent.js';
|
|
42
|
+
export { declaredInputSchema } from './tools/call-order.js';
|
|
42
43
|
export { ToolFailed } from './tools/failed.js';
|
|
43
44
|
export { answerGatedCall, GATE_DECISIONS, gateExpired, resolveGateTtlMs, sessionPermissionsAfterApproval, } from './tools/gate-answer.js';
|
|
44
45
|
export { createMemoryToolExecution } from './tools/memory-execution.js';
|
|
@@ -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. */
|
package/esm/src/kernel/schema.js
CHANGED
|
@@ -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 {
|
package/esm/src/kernel/stages.js
CHANGED
|
@@ -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([
|
|
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
|
|
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;
|
|
@@ -4,6 +4,14 @@ import type { StepCall } from '../stages.js';
|
|
|
4
4
|
export declare function withModelField<TIn>(name: string, input: z.ZodType<TIn>, field: string, shape: () => z.ZodType): z.ZodType<TIn>;
|
|
5
5
|
/** `input` with the model's `after` field. */
|
|
6
6
|
export declare function withCallOrder<TIn>(name: string, input: z.ZodType<TIn>): z.ZodType<TIn>;
|
|
7
|
+
/**
|
|
8
|
+
* A registered tool's input schema as the tool declared it, without the `after` field the kernel
|
|
9
|
+
* added for the model. Registering the tool again from it adds the field once.
|
|
10
|
+
*/
|
|
11
|
+
export declare function declaredInputSchema(tool: {
|
|
12
|
+
after?: boolean;
|
|
13
|
+
inputSchema: Record<string, unknown>;
|
|
14
|
+
}): Record<string, unknown>;
|
|
7
15
|
/** The call's input without `after`, and the tool names `after` held. */
|
|
8
16
|
export declare function splitCallOrder(tool: {
|
|
9
17
|
after?: boolean;
|
|
@@ -29,6 +29,33 @@ export function withModelField(name, input, field, shape) {
|
|
|
29
29
|
export function withCallOrder(name, input) {
|
|
30
30
|
return withModelField(name, input, FIELD, orderField);
|
|
31
31
|
}
|
|
32
|
+
/**
|
|
33
|
+
* A registered tool's input schema as the tool declared it, without the `after` field the kernel
|
|
34
|
+
* added for the model. Registering the tool again from it adds the field once.
|
|
35
|
+
*/
|
|
36
|
+
export function declaredInputSchema(tool) {
|
|
37
|
+
return tool.after ? withoutField(tool.inputSchema, FIELD) : tool.inputSchema;
|
|
38
|
+
}
|
|
39
|
+
function withoutField(schema, field) {
|
|
40
|
+
const out = { ...schema };
|
|
41
|
+
const properties = schema.properties;
|
|
42
|
+
if (properties && typeof properties === 'object' && Object.hasOwn(properties, field)) {
|
|
43
|
+
const { [field]: _added, ...rest } = properties;
|
|
44
|
+
out.properties = rest;
|
|
45
|
+
if (Array.isArray(schema.required)) {
|
|
46
|
+
out.required = schema.required.filter((name) => name !== field);
|
|
47
|
+
}
|
|
48
|
+
}
|
|
49
|
+
for (const key of ['oneOf', 'anyOf']) {
|
|
50
|
+
const options = schema[key];
|
|
51
|
+
if (Array.isArray(options)) {
|
|
52
|
+
out[key] = options.map((option) => option && typeof option === 'object'
|
|
53
|
+
? withoutField(option, field)
|
|
54
|
+
: option);
|
|
55
|
+
}
|
|
56
|
+
}
|
|
57
|
+
return out;
|
|
58
|
+
}
|
|
32
59
|
/** The call's input without `after`, and the tool names `after` held. */
|
|
33
60
|
export function splitCallOrder(tool, input) {
|
|
34
61
|
if (!tool.after || typeof input !== 'object' || input === null)
|
|
@@ -86,6 +86,7 @@ export const toolOperationOutcomeSchema = z.strictObject({
|
|
|
86
86
|
id: z.string().optional(),
|
|
87
87
|
messages: z.array(turnHistoryMessageSchema),
|
|
88
88
|
released: z.number().int().nonnegative().optional(),
|
|
89
|
+
promote: z.array(z.string().min(1)).optional(),
|
|
89
90
|
}))
|
|
90
91
|
.optional(),
|
|
91
92
|
ended: z.literal(true).optional(),
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@theoremjs/agents",
|
|
3
|
-
"version": "0.3.5-next.
|
|
3
|
+
"version": "0.3.5-next.943.g77aa4ba",
|
|
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",
|