@modelprofile.com/flexharness-agent 10.15.0 → 10.16.0
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/dist_ts_agent/classes.sessionengine.js +83 -7
- package/dist_ts_agent/index.d.ts +3 -1
- package/dist_ts_agent/index.js +2 -1
- package/dist_ts_agent/smartagent.interfaces.d.ts +29 -0
- package/dist_ts_agent/smartagent.interfaces.js +1 -1
- package/dist_ts_agent/smartagent.toolscheduler.d.ts +68 -0
- package/dist_ts_agent/smartagent.toolscheduler.js +163 -0
- package/package.json +2 -2
- package/readme.md +14 -0
- package/ts_agent/classes.sessionengine.ts +93 -5
- package/ts_agent/index.ts +3 -0
- package/ts_agent/readme.md +14 -0
- package/ts_agent/smartagent.interfaces.ts +27 -0
- package/ts_agent/smartagent.toolscheduler.ts +197 -0
package/ts_agent/readme.md
CHANGED
|
@@ -351,6 +351,20 @@ The root exports the AI SDK `tool`, `jsonSchema` and `stepCountIs` helpers, plus
|
|
|
351
351
|
|
|
352
352
|
Your tool implementations own access to application services and external effects. `IToolExecutionContext` defines optional filesystem, shell, browser, background-job and permission interfaces for host integrations. Supplying a context does not install tools or create isolation. Reusable tools live in `@modelprofile.com/flexharness/tools`; Node execution integrations live in `/tools/node`. Permission checks and isolation must be implemented by the chosen host/tool integration.
|
|
353
353
|
|
|
354
|
+
### Call order and early start
|
|
355
|
+
|
|
356
|
+
A model response can issue several tool calls. The session runs a call in the order the model issued it unless `isReadOnlyToolCall({ toolName, input })` returns `true` for it: read-only calls run concurrently, and any other call starts once every call before it settled, with the calls after it waiting for it. Without a classifier every call is ordered. Pass `isReadOnlyToolCall` next to `tools`, on the session, `generate()` or the generation lease; it is taken from wherever the tools come from.
|
|
357
|
+
|
|
358
|
+
```typescript
|
|
359
|
+
const session = new AgentSession({
|
|
360
|
+
model,
|
|
361
|
+
tools: { readFile, writeFile },
|
|
362
|
+
isReadOnlyToolCall: ({ toolName }) => toolName === 'readFile',
|
|
363
|
+
});
|
|
364
|
+
```
|
|
365
|
+
|
|
366
|
+
A read-only call that no call that writes precedes in its response starts as soon as its input is complete, while the model still streams the rest of the response. When the SDK executes the response's calls, the session adopts the running call instead of starting it again. A response that fails, is retried, or ends without executing the call discards it: its abort signal fires and no tool-call or tool-result event, no `onToolCallStart` and no part of it is recorded. Such a call gets `confirmed`, a promise in its execution options (`IAgentToolExecutionOptions`), which resolves when the response adopted it and rejects when it was discarded; work that must not happen for an unfinished call, such as asking for permission, waits for it. A transactional generation writes a read-only call's execution intent when the response adopts it, after the call started: read-only calls have no effect to recover.
|
|
367
|
+
|
|
354
368
|
For generation-scoped resources, `generate({ prepare })` accepts a callback that returns an `IAgentGenerationLease`. Its model/tool/settings overrides take precedence over per-generation options and session defaults. The runtime calls the lease's `close()` after execution. The host must clean up partial acquisition if `prepare` throws; lease cleanup must tolerate repeated or overlapping attempts after a failure or timeout.
|
|
355
369
|
|
|
356
370
|
## Cancellation, retries and cleanup
|
|
@@ -199,6 +199,9 @@ export type TAgentSessionChangeListener = (
|
|
|
199
199
|
change: IAgentSessionChange,
|
|
200
200
|
) => void | Promise<void>;
|
|
201
201
|
|
|
202
|
+
/** Whether a tool call is read-only; see `isReadOnlyToolCall`. It may be asked more than once about one call. */
|
|
203
|
+
export type TAgentToolCallClassifier = (toolCall: { toolName: string; input: unknown }) => boolean;
|
|
204
|
+
|
|
202
205
|
export interface IAgentSessionOptions {
|
|
203
206
|
/** Default SmartAI language model. May be omitted when every generation supplies a model. */
|
|
204
207
|
model?: TSmartAiLanguageModel;
|
|
@@ -206,6 +209,14 @@ export interface IAgentSessionOptions {
|
|
|
206
209
|
system?: string;
|
|
207
210
|
/** Tools available to the agent */
|
|
208
211
|
tools?: ToolSet;
|
|
212
|
+
/**
|
|
213
|
+
* Tells read-only calls of these tools apart: they have no effect but their result. Read-only
|
|
214
|
+
* calls run concurrently, and one may start as soon as its input is complete while the model
|
|
215
|
+
* still streams; it is discarded, its abort signal fired, when that response fails. Every
|
|
216
|
+
* other call runs in the order the model issued it, after the calls before it settled. Without
|
|
217
|
+
* it, every call runs in order. It is taken from where the tools come from.
|
|
218
|
+
*/
|
|
219
|
+
isReadOnlyToolCall?: TAgentToolCallClassifier;
|
|
209
220
|
/** Provider-specific AI SDK request options passed through to streamText() */
|
|
210
221
|
providerOptions?: ProviderOptions;
|
|
211
222
|
/** Stable session id used as provider prompt-cache affinity key where supported. */
|
|
@@ -339,6 +350,14 @@ export interface IAgentGenerationLease {
|
|
|
339
350
|
model?: TSmartAiLanguageModel;
|
|
340
351
|
system?: string;
|
|
341
352
|
tools?: ToolSet;
|
|
353
|
+
/**
|
|
354
|
+
* Tells read-only calls of these tools apart: they have no effect but their result. Read-only
|
|
355
|
+
* calls run concurrently, and one may start as soon as its input is complete while the model
|
|
356
|
+
* still streams; it is discarded, its abort signal fired, when that response fails. Every
|
|
357
|
+
* other call runs in the order the model issued it, after the calls before it settled. Without
|
|
358
|
+
* it, every call runs in order. It is taken from where the tools come from.
|
|
359
|
+
*/
|
|
360
|
+
isReadOnlyToolCall?: TAgentToolCallClassifier;
|
|
342
361
|
providerOptions?: ProviderOptions;
|
|
343
362
|
cache?: TAgentCacheSetting;
|
|
344
363
|
maxSteps?: number;
|
|
@@ -386,6 +405,14 @@ export interface IAgentGenerateOptions {
|
|
|
386
405
|
system?: string;
|
|
387
406
|
/** Per-generation tool override. A prepared lease takes precedence. */
|
|
388
407
|
tools?: ToolSet;
|
|
408
|
+
/**
|
|
409
|
+
* Tells read-only calls of these tools apart: they have no effect but their result. Read-only
|
|
410
|
+
* calls run concurrently, and one may start as soon as its input is complete while the model
|
|
411
|
+
* still streams; it is discarded, its abort signal fired, when that response fails. Every
|
|
412
|
+
* other call runs in the order the model issued it, after the calls before it settled. Without
|
|
413
|
+
* it, every call runs in order. It is taken from where the tools come from.
|
|
414
|
+
*/
|
|
415
|
+
isReadOnlyToolCall?: TAgentToolCallClassifier;
|
|
389
416
|
/** Per-generation provider options override. A prepared lease takes precedence. */
|
|
390
417
|
providerOptions?: ProviderOptions;
|
|
391
418
|
/** Per-generation prompt-cache override. A prepared lease takes precedence. */
|
|
@@ -0,0 +1,197 @@
|
|
|
1
|
+
/** What a session adds to the execution options a tool's `execute` receives. */
|
|
2
|
+
export interface IAgentToolExecutionOptions {
|
|
3
|
+
/**
|
|
4
|
+
* Set on a read-only call that started while the model still streamed its response. Resolves
|
|
5
|
+
* when the response completed and executes the call; rejects when the response failed or ended
|
|
6
|
+
* without executing it, and the call's abort signal fires then as well. Work that must not
|
|
7
|
+
* happen for a call the model did not finish issuing, such as asking for permission, waits for
|
|
8
|
+
* it.
|
|
9
|
+
*/
|
|
10
|
+
confirmed?: Promise<void>;
|
|
11
|
+
}
|
|
12
|
+
|
|
13
|
+
interface IEarlyToolExecution {
|
|
14
|
+
signature: string;
|
|
15
|
+
controller: AbortController;
|
|
16
|
+
outcome: { value: unknown } | { error: unknown };
|
|
17
|
+
confirm: () => void;
|
|
18
|
+
reject: (reason: unknown) => void;
|
|
19
|
+
}
|
|
20
|
+
|
|
21
|
+
interface IScheduledToolCall {
|
|
22
|
+
toolCallId: string;
|
|
23
|
+
readOnly: boolean;
|
|
24
|
+
/** The SDK began executing the call. */
|
|
25
|
+
started: boolean;
|
|
26
|
+
settled: boolean;
|
|
27
|
+
done: Promise<void>;
|
|
28
|
+
resolveDone: () => void;
|
|
29
|
+
early?: IEarlyToolExecution;
|
|
30
|
+
}
|
|
31
|
+
|
|
32
|
+
/**
|
|
33
|
+
* Orders the tool calls of one generation in the order the model issued them. Read-only calls run
|
|
34
|
+
* concurrently with each other; any other call starts after every earlier call settled, and later
|
|
35
|
+
* calls wait for it. A read-only call that no running or issued non-read call precedes starts as
|
|
36
|
+
* soon as its input is complete, while the model still streams the rest of its response: the
|
|
37
|
+
* SDK's execution adopts it, and a model call that ends without executing it discards it.
|
|
38
|
+
*/
|
|
39
|
+
export class AgentToolCallScheduler {
|
|
40
|
+
private readonly calls = new Map<string, IScheduledToolCall>();
|
|
41
|
+
private readonly order: IScheduledToolCall[] = [];
|
|
42
|
+
/** Calls that settled and left the order; their IDs are not issued again. */
|
|
43
|
+
private readonly finished = new Set<string>();
|
|
44
|
+
|
|
45
|
+
constructor(private readonly signal: AbortSignal) {}
|
|
46
|
+
|
|
47
|
+
/** Records a call in issue order; a known or finished call keeps its place. */
|
|
48
|
+
public issue(toolCallId: string, readOnly: boolean): void {
|
|
49
|
+
if (this.calls.has(toolCallId) || this.finished.has(toolCallId)) return;
|
|
50
|
+
let resolveDone!: () => void;
|
|
51
|
+
const done = new Promise<void>((resolve) => {
|
|
52
|
+
resolveDone = resolve;
|
|
53
|
+
});
|
|
54
|
+
const call: IScheduledToolCall = {
|
|
55
|
+
toolCallId, readOnly, started: false, settled: false, done, resolveDone,
|
|
56
|
+
};
|
|
57
|
+
this.calls.set(toolCallId, call);
|
|
58
|
+
this.order.push(call);
|
|
59
|
+
}
|
|
60
|
+
|
|
61
|
+
/**
|
|
62
|
+
* Starts a complete read-only call before the SDK executes it, when no unsettled non-read call
|
|
63
|
+
* precedes it. `start` receives the call's abort signal and its confirmation.
|
|
64
|
+
*/
|
|
65
|
+
public startEarly(
|
|
66
|
+
toolCallId: string,
|
|
67
|
+
readOnly: boolean,
|
|
68
|
+
signature: string,
|
|
69
|
+
start: (signal: AbortSignal, confirmed: Promise<void>) => unknown,
|
|
70
|
+
): void {
|
|
71
|
+
this.issue(toolCallId, readOnly);
|
|
72
|
+
const call = this.calls.get(toolCallId);
|
|
73
|
+
if (!call || call.started || call.early || call.settled) return;
|
|
74
|
+
call.readOnly = readOnly;
|
|
75
|
+
if (!readOnly || this.signal.aborted) return;
|
|
76
|
+
if (this.precedingCalls(call).some((earlier) => !earlier.readOnly)) return;
|
|
77
|
+
const controller = new AbortController();
|
|
78
|
+
let confirm!: () => void;
|
|
79
|
+
let reject!: (reason: unknown) => void;
|
|
80
|
+
const confirmed = new Promise<void>((resolve, rejectConfirmation) => {
|
|
81
|
+
confirm = resolve;
|
|
82
|
+
reject = rejectConfirmation;
|
|
83
|
+
});
|
|
84
|
+
void confirmed.catch(() => undefined);
|
|
85
|
+
let outcome: IEarlyToolExecution['outcome'];
|
|
86
|
+
try {
|
|
87
|
+
outcome = { value: start(AbortSignal.any([this.signal, controller.signal]), confirmed) };
|
|
88
|
+
} catch (error) {
|
|
89
|
+
outcome = { error };
|
|
90
|
+
}
|
|
91
|
+
if ('value' in outcome && isPromiseLike(outcome.value)) {
|
|
92
|
+
void Promise.resolve(outcome.value).catch(() => undefined);
|
|
93
|
+
}
|
|
94
|
+
call.early = { signature, controller, outcome, confirm, reject };
|
|
95
|
+
}
|
|
96
|
+
|
|
97
|
+
/** Records a call that starts without an early execution, such as a program's call, in issue order. */
|
|
98
|
+
public begin(toolCallId: string, readOnly: boolean): void {
|
|
99
|
+
this.issue(toolCallId, readOnly);
|
|
100
|
+
const call = this.calls.get(toolCallId);
|
|
101
|
+
if (call) call.started = true;
|
|
102
|
+
}
|
|
103
|
+
|
|
104
|
+
/**
|
|
105
|
+
* Takes over the call the SDK now executes. Returns the early execution's outcome when it
|
|
106
|
+
* started early with the same input; otherwise discards a mismatched early execution and returns
|
|
107
|
+
* undefined, and the caller starts the call after `waitForTurn`.
|
|
108
|
+
*/
|
|
109
|
+
public adopt(
|
|
110
|
+
toolCallId: string,
|
|
111
|
+
signature: string,
|
|
112
|
+
readOnly: boolean,
|
|
113
|
+
): IEarlyToolExecution['outcome'] | undefined {
|
|
114
|
+
this.issue(toolCallId, readOnly);
|
|
115
|
+
const call = this.calls.get(toolCallId);
|
|
116
|
+
if (!call) return undefined;
|
|
117
|
+
call.started = true;
|
|
118
|
+
const early = call.early;
|
|
119
|
+
if (early?.signature === signature) {
|
|
120
|
+
early.confirm();
|
|
121
|
+
return early.outcome;
|
|
122
|
+
}
|
|
123
|
+
if (early) {
|
|
124
|
+
call.early = undefined;
|
|
125
|
+
this.discardEarly(early, new Error(`Tool call "${toolCallId}" changed after it started early.`));
|
|
126
|
+
}
|
|
127
|
+
call.readOnly = readOnly;
|
|
128
|
+
return undefined;
|
|
129
|
+
}
|
|
130
|
+
|
|
131
|
+
/**
|
|
132
|
+
* Resolves when the call may start, after every unsettled earlier call it must follow; undefined
|
|
133
|
+
* when it can start at once. Every issued call is executed or discarded at the end of its model
|
|
134
|
+
* call, so the calls it waits for settle.
|
|
135
|
+
*/
|
|
136
|
+
public waitForTurn(toolCallId: string, signal?: AbortSignal): Promise<void> | undefined {
|
|
137
|
+
const call = this.calls.get(toolCallId);
|
|
138
|
+
if (!call) return undefined;
|
|
139
|
+
const blockers = this.precedingCalls(call)
|
|
140
|
+
.filter((earlier) => !call.readOnly || !earlier.readOnly)
|
|
141
|
+
.map((earlier) => earlier.done);
|
|
142
|
+
if (blockers.length === 0) return undefined;
|
|
143
|
+
const signals = [this.signal, ...(signal ? [signal] : [])];
|
|
144
|
+
return new Promise<void>((resolve, reject) => {
|
|
145
|
+
const onAbort = () => {
|
|
146
|
+
const aborted = signals.find((candidate) => candidate.aborted)!;
|
|
147
|
+
reject(aborted.reason ?? new DOMException('Aborted', 'AbortError'));
|
|
148
|
+
};
|
|
149
|
+
for (const candidate of signals) {
|
|
150
|
+
if (candidate.aborted) return onAbort();
|
|
151
|
+
candidate.addEventListener('abort', onAbort, { once: true });
|
|
152
|
+
}
|
|
153
|
+
void Promise.all(blockers).then(() => {
|
|
154
|
+
for (const candidate of signals) candidate.removeEventListener('abort', onAbort);
|
|
155
|
+
resolve();
|
|
156
|
+
});
|
|
157
|
+
});
|
|
158
|
+
}
|
|
159
|
+
|
|
160
|
+
/** Marks a call finished; the calls waiting for it may start. */
|
|
161
|
+
public settle(toolCallId: string): void {
|
|
162
|
+
const call = this.calls.get(toolCallId);
|
|
163
|
+
if (!call || call.settled) return;
|
|
164
|
+
call.settled = true;
|
|
165
|
+
call.resolveDone();
|
|
166
|
+
while (this.order.length > 0 && this.order[0].settled) {
|
|
167
|
+
const settled = this.order.shift()!;
|
|
168
|
+
this.calls.delete(settled.toolCallId);
|
|
169
|
+
this.finished.add(settled.toolCallId);
|
|
170
|
+
}
|
|
171
|
+
}
|
|
172
|
+
|
|
173
|
+
/**
|
|
174
|
+
* Ends a model call: an early execution the SDK did not adopt is aborted and its confirmation
|
|
175
|
+
* rejected, and an issued call it did not execute no longer holds later calls back.
|
|
176
|
+
*/
|
|
177
|
+
public endModelCall(reason: unknown): void {
|
|
178
|
+
for (const call of [...this.order]) {
|
|
179
|
+
if (call.started) continue;
|
|
180
|
+
if (call.early) this.discardEarly(call.early, reason);
|
|
181
|
+
this.settle(call.toolCallId);
|
|
182
|
+
}
|
|
183
|
+
}
|
|
184
|
+
|
|
185
|
+
private precedingCalls(call: IScheduledToolCall): IScheduledToolCall[] {
|
|
186
|
+
const index = this.order.indexOf(call);
|
|
187
|
+
return this.order.slice(0, index).filter((earlier) => !earlier.settled);
|
|
188
|
+
}
|
|
189
|
+
|
|
190
|
+
private discardEarly(early: IEarlyToolExecution, reason: unknown): void {
|
|
191
|
+
early.reject(reason);
|
|
192
|
+
early.controller.abort(reason);
|
|
193
|
+
}
|
|
194
|
+
}
|
|
195
|
+
|
|
196
|
+
const isPromiseLike = (value: unknown): value is PromiseLike<unknown> =>
|
|
197
|
+
typeof (value as { then?: unknown } | null)?.then === 'function';
|