@modelprofile.com/flexharness-agent 10.15.1 → 10.17.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/ts_agent/index.ts CHANGED
@@ -24,6 +24,8 @@ export type {
24
24
  TAgentPendingInputRejection,
25
25
  } from './smartagent.pendinginput.js';
26
26
  export { ToolRegistry } from './smartagent.classes.toolregistry.js';
27
+ export { AgentToolCallScheduler } from './smartagent.toolscheduler.js';
28
+ export type { IAgentToolExecutionOptions } from './smartagent.toolscheduler.js';
27
29
  export { AgentModelCallUsageRecorder } from './smartagent.usage.js';
28
30
  export type { IAgentModelCallUsageRecorderModel } from './smartagent.usage.js';
29
31
  export {
@@ -78,6 +80,7 @@ export type {
78
80
  TAgentModelCallUsageSource,
79
81
  TAgentObservedModelCallUsage,
80
82
  TAgentSessionChangeListener,
83
+ TAgentToolCallClassifier,
81
84
  TAgentToolCallFinishEvent,
82
85
  TAgentToolExecutionReconciliationOptions,
83
86
  } from './smartagent.interfaces.js';
@@ -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
@@ -29,6 +29,7 @@ export async function runAgentWithSession(
29
29
  model: options.model,
30
30
  system: options.system,
31
31
  tools: options.tools,
32
+ isReadOnlyToolCall: options.isReadOnlyToolCall,
32
33
  providerOptions: options.providerOptions,
33
34
  sessionId: options.sessionId,
34
35
  eventStore: options.eventStore,
@@ -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';