@theoremjs/agents 0.3.5-next.939.g227994b → 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.
- package/esm/src/conversation/run.d.ts +1 -1
- package/esm/src/conversation/run.js +1 -1
- package/esm/src/conversation/testing.js +22 -0
- package/esm/src/conversation/types.d.ts +9 -3
- 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/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/package.json +1 -1
|
@@ -12,7 +12,7 @@ export interface RunConversationOptions<Item extends InboxItem> {
|
|
|
12
12
|
inbox: ConversationInbox<Item>;
|
|
13
13
|
policy: InboxPolicy<Item>;
|
|
14
14
|
start: ReplyStart;
|
|
15
|
-
/** Makes the ids of
|
|
15
|
+
/** Makes the ids of replies, and of holds the start does not name. */
|
|
16
16
|
newId: () => string;
|
|
17
17
|
/** How often the hold renews its lease while the reply runs, in milliseconds. */
|
|
18
18
|
renewEveryMs: number;
|
|
@@ -8,7 +8,7 @@
|
|
|
8
8
|
/** Runs one reply under a hold of the conversation. See {@link ConversationRun}. */
|
|
9
9
|
export async function runConversation(options) {
|
|
10
10
|
const { conversation, inbox, start } = options;
|
|
11
|
-
const hold = start.
|
|
11
|
+
const hold = start.hold ?? options.newId();
|
|
12
12
|
// why: A follow-up's hold is checked where it acts: handing, giving up, and before `continue`.
|
|
13
13
|
if (start.opening === 'message' && start.takeOver) {
|
|
14
14
|
await inbox.takeOver(conversation, hold);
|
|
@@ -117,6 +117,28 @@ export function conversationScenarios(options) {
|
|
|
117
117
|
fail('a wake with nothing waiting ran a reply');
|
|
118
118
|
expectOutcome(await s.run({ opening: 'message' }), 'released', 'the next message');
|
|
119
119
|
}),
|
|
120
|
+
scenario('a message under the hold the app already took runs, and lets go', async (s) => {
|
|
121
|
+
await s.h.arrive('r');
|
|
122
|
+
const opened = await s.h.inbox.open(s.h.conversation, 'app-hold');
|
|
123
|
+
if (opened.outcome !== 'opened')
|
|
124
|
+
fail('the app did not take the conversation');
|
|
125
|
+
const ran = await s.run({ opening: 'message', hold: 'app-hold' });
|
|
126
|
+
expectOutcome(ran, 'released', 'the message');
|
|
127
|
+
await s.expectTold(['r']);
|
|
128
|
+
}),
|
|
129
|
+
scenario('a message under a hold the app does not have is held', async (s) => {
|
|
130
|
+
const opened = await s.h.inbox.open(s.h.conversation, 'other-hold');
|
|
131
|
+
if (opened.outcome !== 'opened')
|
|
132
|
+
fail('the other hold did not take the conversation');
|
|
133
|
+
let replied = false;
|
|
134
|
+
const ran = await s.run({ opening: 'message', hold: 'app-hold' }, () => {
|
|
135
|
+
replied = true;
|
|
136
|
+
return Promise.resolve();
|
|
137
|
+
});
|
|
138
|
+
expectOutcome(ran, 'held', 'the message');
|
|
139
|
+
if (replied)
|
|
140
|
+
fail('a message under a hold it does not have ran a reply');
|
|
141
|
+
}),
|
|
120
142
|
scenario('an item that arrives during a step is read at the next moment', async (s) => {
|
|
121
143
|
const ran = await s.run({ opening: 'message' }, async (reply) => {
|
|
122
144
|
await s.h.arrive('b');
|
|
@@ -98,15 +98,21 @@ export interface ConversationInbox<Item extends InboxItem = InboxItem> {
|
|
|
98
98
|
release(conversation: string, hold: string, version: string): Promise<'released' | 'moved' | 'lost'>;
|
|
99
99
|
}
|
|
100
100
|
/**
|
|
101
|
-
* What opens a reply. A `message` or a `wake` opens the conversation under a new hold
|
|
102
|
-
* with `takeOver` takes it from any hold that has it. A
|
|
103
|
-
* before it returned with `continue`.
|
|
101
|
+
* What opens a reply. A `message` or a `wake` opens the conversation under a new hold, or under
|
|
102
|
+
* `hold` when the app names it; a message with `takeOver` takes it from any hold that has it. A
|
|
103
|
+
* `follow_up` runs under the hold a run before it returned with `continue`.
|
|
104
|
+
*
|
|
105
|
+
* @remarks Name the `hold` when the app takes the conversation itself, such as in the write that
|
|
106
|
+
* saves the person's message. `open` with the hold that has the conversation keeps it, so the run
|
|
107
|
+
* goes on under that hold.
|
|
104
108
|
*/
|
|
105
109
|
export type ReplyStart = {
|
|
106
110
|
opening: 'message';
|
|
107
111
|
takeOver?: boolean;
|
|
112
|
+
hold?: string;
|
|
108
113
|
} | {
|
|
109
114
|
opening: 'wake';
|
|
115
|
+
hold?: string;
|
|
110
116
|
} | {
|
|
111
117
|
opening: 'follow_up';
|
|
112
118
|
hold: string;
|
|
@@ -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. */
|
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;
|
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.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",
|