@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.
@@ -6,11 +6,13 @@ export { createAgentEvent, createAgentEventId, modelMessagesToAgentEvents, } fro
6
6
  export { AgentPendingInputQueue, AgentPendingInputRejectedError, } from './smartagent.pendinginput.js';
7
7
  export type { IAgentAppliedInput, IAgentPendingInput, TAgentPendingInputRejection, } from './smartagent.pendinginput.js';
8
8
  export { ToolRegistry } from './smartagent.classes.toolregistry.js';
9
+ export { AgentToolCallScheduler } from './smartagent.toolscheduler.js';
10
+ export type { IAgentToolExecutionOptions } from './smartagent.toolscheduler.js';
9
11
  export { AgentModelCallUsageRecorder } from './smartagent.usage.js';
10
12
  export type { IAgentModelCallUsageRecorderModel } from './smartagent.usage.js';
11
13
  export { AgentGenerationLeaseCleanupError, ContextOverflowError, } from './smartagent.interfaces.js';
12
14
  export { AGENT_TOOL_RESULT_FILE_MAX_BYTES, AgentEventStoreConflictError, InMemoryAgentEventStore, isAgentEventStoreV2, validateAgentEventArchiveV2, validateAgentEventSnapshotV2, } from './smartagent.persistence.js';
13
- export type { IAgentCacheOptions, ISmartAiCacheDispatch, IAgentContextOverflowInvocationOptions, IAgentContextBuildOptions, IAgentContextCompactionOptions, IAgentCompactOptions, IAgentEventRetentionOptions, IAgentBeginGenerationOptions, IAgentFinalizeGenerationOptions, IAgentGenerateOptions, IAgentGenerateResult, IAgentGenerationHandle, IAgentGenerationLease, IAgentGenerationPreparationContext, IAgentRunOptions, IAgentRunResult, IAgentSession, IAgentSessionAbortOptions, IAgentSessionChange, IAgentSessionOptions, IAgentScheduleGenerateOptions, IAgentToolCallRecord, IAgentToolCallStartEvent, IAgentToolCallUpdateEvent, IAgentUsage, ProviderOptions, TAgentCacheRetention, TAgentCacheSetting, TAgentPrompt, TAgentContextBuilder, TAgentContextCompactor, TAgentGenerationPrepare, TAgentModelCallUnreportedReason, TAgentModelCallUsage, TAgentModelCallUsageEvent, TAgentModelCallUsageReporter, TAgentModelCallUsageSource, TAgentObservedModelCallUsage, TAgentSessionChangeListener, TAgentToolCallFinishEvent, TAgentToolExecutionReconciliationOptions, } from './smartagent.interfaces.js';
15
+ export type { IAgentCacheOptions, ISmartAiCacheDispatch, IAgentContextOverflowInvocationOptions, IAgentContextBuildOptions, IAgentContextCompactionOptions, IAgentCompactOptions, IAgentEventRetentionOptions, IAgentBeginGenerationOptions, IAgentFinalizeGenerationOptions, IAgentGenerateOptions, IAgentGenerateResult, IAgentGenerationHandle, IAgentGenerationLease, IAgentGenerationPreparationContext, IAgentRunOptions, IAgentRunResult, IAgentSession, IAgentSessionAbortOptions, IAgentSessionChange, IAgentSessionOptions, IAgentScheduleGenerateOptions, IAgentToolCallRecord, IAgentToolCallStartEvent, IAgentToolCallUpdateEvent, IAgentUsage, ProviderOptions, TAgentCacheRetention, TAgentCacheSetting, TAgentPrompt, TAgentContextBuilder, TAgentContextCompactor, TAgentGenerationPrepare, TAgentModelCallUnreportedReason, TAgentModelCallUsage, TAgentModelCallUsageEvent, TAgentModelCallUsageReporter, TAgentModelCallUsageSource, TAgentObservedModelCallUsage, TAgentSessionChangeListener, TAgentToolCallClassifier, TAgentToolCallFinishEvent, TAgentToolExecutionReconciliationOptions, } from './smartagent.interfaces.js';
14
16
  export type { IAgentEventArchive, IAgentEventArchiveV2, IAgentEventSnapshot, IAgentEventSnapshotV2, IAgentEventStore, IAgentEventStoreV2, TAgentEventArchive, TAgentEventSnapshot, TAgentEventStore, } from './smartagent.persistence.js';
15
17
  export type { IAgentEventBase, IAgentRuntimeEventPayload, IArchivedAgentGenerationTransaction, IAssistantMessageEvent, IContextCompactionEvent, IGenerationBegunEvent, IGenerationExecutionCompletedEvent, IGenerationExecutionStartedEvent, IGenerationOutcomeEvent, IModelMessageEvent, IModelMessagesToEventsOptions, IModelMessageEventIdentityCoordinates, IRuntimeEvent, ISystemMessageEvent, IToolCallEvent, IToolExecutionIntentEvent, IToolExecutionReconciliationEvent, IToolResultEvent, IUserMessageEvent, TAgentAssistantMessage, TAgentConversationEvent, TAgentControlEvent, TAgentEvent, TAgentEventInput, TAgentSystemMessage, TAgentGenerationOutcome, TAgentToolCallPart, TAgentToolMessage, TAgentToolResultOutput, TAgentToolResultPart, TAgentUserMessage, TModelMessageEmittedEventKind, TModelMessageEventIdentityFactory, TToolExecutionReconciliation, } from './smartagent.events.js';
16
18
  export type { IAgentGenerationTransaction, TAgentGenerationTransactionState, } from './smartagent.transactions.js';
@@ -5,6 +5,7 @@ export { filterModelVisibleAgentEvents, getAgentGenerationTransactions, getOpenA
5
5
  export { createAgentEvent, createAgentEventId, modelMessagesToAgentEvents, } from './smartagent.events.js';
6
6
  export { AgentPendingInputQueue, AgentPendingInputRejectedError, } from './smartagent.pendinginput.js';
7
7
  export { ToolRegistry } from './smartagent.classes.toolregistry.js';
8
+ export { AgentToolCallScheduler } from './smartagent.toolscheduler.js';
8
9
  export { AgentModelCallUsageRecorder } from './smartagent.usage.js';
9
10
  export { AgentGenerationLeaseCleanupError, ContextOverflowError, } from './smartagent.interfaces.js';
10
11
  export { AGENT_TOOL_RESULT_FILE_MAX_BYTES, AgentEventStoreConflictError, InMemoryAgentEventStore, isAgentEventStoreV2, validateAgentEventArchiveV2, validateAgentEventSnapshotV2, } from './smartagent.persistence.js';
@@ -13,4 +14,4 @@ export * from './tool.persistence.js';
13
14
  export * from './tool.adapter.js';
14
15
  export { tool, jsonSchema, stepCountIs, z } from './plugins.js';
15
16
  export { FileAgentEventStore } from './persistence.file.js';
16
- //# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi90c19hZ2VudC9pbmRleC50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQSxPQUFPLEVBQUUsUUFBUSxFQUFFLE1BQU0sK0JBQStCLENBQUM7QUFDekQsT0FBTyxFQUFFLFlBQVksRUFBRSxNQUFNLGlDQUFpQyxDQUFDO0FBQy9ELE9BQU8sRUFBRSxrQkFBa0IsRUFBRSxNQUFNLHlCQUF5QixDQUFDO0FBQzdELE9BQU8sRUFDTCw2QkFBNkIsRUFDN0IsOEJBQThCLEVBQzlCLGtDQUFrQyxFQUNsQyxnQ0FBZ0MsRUFDaEMsMEJBQTBCLEVBQzFCLHlCQUF5QixHQUMxQixNQUFNLDhCQUE4QixDQUFDO0FBQ3RDLE9BQU8sRUFDTCxnQkFBZ0IsRUFDaEIsa0JBQWtCLEVBQ2xCLDBCQUEwQixHQUMzQixNQUFNLHdCQUF3QixDQUFDO0FBQ2hDLE9BQU8sRUFDTCxzQkFBc0IsRUFDdEIsOEJBQThCLEdBQy9CLE1BQU0sOEJBQThCLENBQUM7QUFNdEMsT0FBTyxFQUFFLFlBQVksRUFBRSxNQUFNLHNDQUFzQyxDQUFDO0FBQ3BFLE9BQU8sRUFBRSwyQkFBMkIsRUFBRSxNQUFNLHVCQUF1QixDQUFDO0FBRXBFLE9BQU8sRUFDTCxnQ0FBZ0MsRUFDaEMsb0JBQW9CLEdBQ3JCLE1BQU0sNEJBQTRCLENBQUM7QUFDcEMsT0FBTyxFQUNMLGdDQUFnQyxFQUNoQyw0QkFBNEIsRUFDNUIsdUJBQXVCLEVBQ3ZCLG1CQUFtQixFQUNuQiwyQkFBMkIsRUFDM0IsNEJBQTRCLEdBQzdCLE1BQU0sNkJBQTZCLENBQUM7QUFnR3JDLGNBQWMscUJBQXFCLENBQUM7QUFDcEMsY0FBYyx1QkFBdUIsQ0FBQztBQUN0QyxjQUFjLG1CQUFtQixDQUFDO0FBQ2xDLE9BQU8sRUFBRSxJQUFJLEVBQUUsVUFBVSxFQUFFLFdBQVcsRUFBRSxDQUFDLEVBQUUsTUFBTSxjQUFjLENBQUM7QUFFaEUsT0FBTyxFQUFFLG1CQUFtQixFQUFvQyxNQUFNLHVCQUF1QixDQUFDIn0=
17
+ //# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi90c19hZ2VudC9pbmRleC50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQSxPQUFPLEVBQUUsUUFBUSxFQUFFLE1BQU0sK0JBQStCLENBQUM7QUFDekQsT0FBTyxFQUFFLFlBQVksRUFBRSxNQUFNLGlDQUFpQyxDQUFDO0FBQy9ELE9BQU8sRUFBRSxrQkFBa0IsRUFBRSxNQUFNLHlCQUF5QixDQUFDO0FBQzdELE9BQU8sRUFDTCw2QkFBNkIsRUFDN0IsOEJBQThCLEVBQzlCLGtDQUFrQyxFQUNsQyxnQ0FBZ0MsRUFDaEMsMEJBQTBCLEVBQzFCLHlCQUF5QixHQUMxQixNQUFNLDhCQUE4QixDQUFDO0FBQ3RDLE9BQU8sRUFDTCxnQkFBZ0IsRUFDaEIsa0JBQWtCLEVBQ2xCLDBCQUEwQixHQUMzQixNQUFNLHdCQUF3QixDQUFDO0FBQ2hDLE9BQU8sRUFDTCxzQkFBc0IsRUFDdEIsOEJBQThCLEdBQy9CLE1BQU0sOEJBQThCLENBQUM7QUFNdEMsT0FBTyxFQUFFLFlBQVksRUFBRSxNQUFNLHNDQUFzQyxDQUFDO0FBQ3BFLE9BQU8sRUFBRSxzQkFBc0IsRUFBRSxNQUFNLCtCQUErQixDQUFDO0FBRXZFLE9BQU8sRUFBRSwyQkFBMkIsRUFBRSxNQUFNLHVCQUF1QixDQUFDO0FBRXBFLE9BQU8sRUFDTCxnQ0FBZ0MsRUFDaEMsb0JBQW9CLEdBQ3JCLE1BQU0sNEJBQTRCLENBQUM7QUFDcEMsT0FBTyxFQUNMLGdDQUFnQyxFQUNoQyw0QkFBNEIsRUFDNUIsdUJBQXVCLEVBQ3ZCLG1CQUFtQixFQUNuQiwyQkFBMkIsRUFDM0IsNEJBQTRCLEdBQzdCLE1BQU0sNkJBQTZCLENBQUM7QUFpR3JDLGNBQWMscUJBQXFCLENBQUM7QUFDcEMsY0FBYyx1QkFBdUIsQ0FBQztBQUN0QyxjQUFjLG1CQUFtQixDQUFDO0FBQ2xDLE9BQU8sRUFBRSxJQUFJLEVBQUUsVUFBVSxFQUFFLFdBQVcsRUFBRSxDQUFDLEVBQUUsTUFBTSxjQUFjLENBQUM7QUFFaEUsT0FBTyxFQUFFLG1CQUFtQixFQUFvQyxNQUFNLHVCQUF1QixDQUFDIn0=
@@ -157,6 +157,11 @@ export interface IAgentSessionChange {
157
157
  events: readonly TAgentEvent[];
158
158
  }
159
159
  export type TAgentSessionChangeListener = (change: IAgentSessionChange) => void | Promise<void>;
160
+ /** Whether a tool call is read-only; see `isReadOnlyToolCall`. It may be asked more than once about one call. */
161
+ export type TAgentToolCallClassifier = (toolCall: {
162
+ toolName: string;
163
+ input: unknown;
164
+ }) => boolean;
160
165
  export interface IAgentSessionOptions {
161
166
  /** Default SmartAI language model. May be omitted when every generation supplies a model. */
162
167
  model?: TSmartAiLanguageModel;
@@ -164,6 +169,14 @@ export interface IAgentSessionOptions {
164
169
  system?: string;
165
170
  /** Tools available to the agent */
166
171
  tools?: ToolSet;
172
+ /**
173
+ * Tells read-only calls of these tools apart: they have no effect but their result. Read-only
174
+ * calls run concurrently, and one may start as soon as its input is complete while the model
175
+ * still streams; it is discarded, its abort signal fired, when that response fails. Every
176
+ * other call runs in the order the model issued it, after the calls before it settled. Without
177
+ * it, every call runs in order. It is taken from where the tools come from.
178
+ */
179
+ isReadOnlyToolCall?: TAgentToolCallClassifier;
167
180
  /** Provider-specific AI SDK request options passed through to streamText() */
168
181
  providerOptions?: ProviderOptions;
169
182
  /** Stable session id used as provider prompt-cache affinity key where supported. */
@@ -288,6 +301,14 @@ export interface IAgentGenerationLease {
288
301
  model?: TSmartAiLanguageModel;
289
302
  system?: string;
290
303
  tools?: ToolSet;
304
+ /**
305
+ * Tells read-only calls of these tools apart: they have no effect but their result. Read-only
306
+ * calls run concurrently, and one may start as soon as its input is complete while the model
307
+ * still streams; it is discarded, its abort signal fired, when that response fails. Every
308
+ * other call runs in the order the model issued it, after the calls before it settled. Without
309
+ * it, every call runs in order. It is taken from where the tools come from.
310
+ */
311
+ isReadOnlyToolCall?: TAgentToolCallClassifier;
291
312
  providerOptions?: ProviderOptions;
292
313
  cache?: TAgentCacheSetting;
293
314
  maxSteps?: number;
@@ -312,6 +333,14 @@ export interface IAgentGenerateOptions {
312
333
  system?: string;
313
334
  /** Per-generation tool override. A prepared lease takes precedence. */
314
335
  tools?: ToolSet;
336
+ /**
337
+ * Tells read-only calls of these tools apart: they have no effect but their result. Read-only
338
+ * calls run concurrently, and one may start as soon as its input is complete while the model
339
+ * still streams; it is discarded, its abort signal fired, when that response fails. Every
340
+ * other call runs in the order the model issued it, after the calls before it settled. Without
341
+ * it, every call runs in order. It is taken from where the tools come from.
342
+ */
343
+ isReadOnlyToolCall?: TAgentToolCallClassifier;
315
344
  /** Per-generation provider options override. A prepared lease takes precedence. */
316
345
  providerOptions?: ProviderOptions;
317
346
  /** Per-generation prompt-cache override. A prepared lease takes precedence. */
@@ -21,4 +21,4 @@ export class ContextOverflowError extends Error {
21
21
  this.name = 'ContextOverflowError';
22
22
  }
23
23
  }
24
- //# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoic21hcnRhZ2VudC5pbnRlcmZhY2VzLmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vdHNfYWdlbnQvc21hcnRhZ2VudC5pbnRlcmZhY2VzLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQStWQSxNQUFNLE9BQU8sZ0NBQWlDLFNBQVEsS0FBSztJQUN6QyxLQUFLLENBQXdCO0lBQzdCLFlBQVksQ0FBVTtJQUNyQixvQkFBb0IsQ0FBc0I7SUFFM0QsWUFDRSxLQUE0QixFQUM1QixZQUFxQixFQUNyQixvQkFBeUM7UUFFekMsS0FBSyxDQUNILG9DQUFvQyxZQUFZLFlBQVksS0FBSztZQUMvRCxDQUFDLENBQUMsWUFBWSxDQUFDLE9BQU87WUFDdEIsQ0FBQyxDQUFDLE1BQU0sQ0FBQyxZQUFZLENBQUMsRUFBRSxDQUMzQixDQUFDO1FBQ0YsSUFBSSxDQUFDLElBQUksR0FBRyxrQ0FBa0MsQ0FBQztRQUMvQyxJQUFJLENBQUMsS0FBSyxHQUFHLEtBQUssQ0FBQztRQUNuQixJQUFJLENBQUMsWUFBWSxHQUFHLFlBQVksQ0FBQztRQUNqQyxJQUFJLENBQUMsb0JBQW9CLEdBQUcsb0JBQW9CLENBQUM7SUFDbkQsQ0FBQztJQUVNLFlBQVk7UUFDakIsT0FBTyxJQUFJLENBQUMsb0JBQW9CLEVBQUUsQ0FBQztJQUNyQyxDQUFDO0NBQ0Y7QUE4SkQsTUFBTSxPQUFPLG9CQUFxQixTQUFRLEtBQUs7SUFDN0MsWUFBWSxPQUFPLEdBQUcsdUVBQXVFO1FBQzNGLEtBQUssQ0FBQyxPQUFPLENBQUMsQ0FBQztRQUNmLElBQUksQ0FBQyxJQUFJLEdBQUcsc0JBQXNCLENBQUM7SUFDckMsQ0FBQztDQUNGIn0=
24
+ //# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoic21hcnRhZ2VudC5pbnRlcmZhY2VzLmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vdHNfYWdlbnQvc21hcnRhZ2VudC5pbnRlcmZhY2VzLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQWtYQSxNQUFNLE9BQU8sZ0NBQWlDLFNBQVEsS0FBSztJQUN6QyxLQUFLLENBQXdCO0lBQzdCLFlBQVksQ0FBVTtJQUNyQixvQkFBb0IsQ0FBc0I7SUFFM0QsWUFDRSxLQUE0QixFQUM1QixZQUFxQixFQUNyQixvQkFBeUM7UUFFekMsS0FBSyxDQUNILG9DQUFvQyxZQUFZLFlBQVksS0FBSztZQUMvRCxDQUFDLENBQUMsWUFBWSxDQUFDLE9BQU87WUFDdEIsQ0FBQyxDQUFDLE1BQU0sQ0FBQyxZQUFZLENBQUMsRUFBRSxDQUMzQixDQUFDO1FBQ0YsSUFBSSxDQUFDLElBQUksR0FBRyxrQ0FBa0MsQ0FBQztRQUMvQyxJQUFJLENBQUMsS0FBSyxHQUFHLEtBQUssQ0FBQztRQUNuQixJQUFJLENBQUMsWUFBWSxHQUFHLFlBQVksQ0FBQztRQUNqQyxJQUFJLENBQUMsb0JBQW9CLEdBQUcsb0JBQW9CLENBQUM7SUFDbkQsQ0FBQztJQUVNLFlBQVk7UUFDakIsT0FBTyxJQUFJLENBQUMsb0JBQW9CLEVBQUUsQ0FBQztJQUNyQyxDQUFDO0NBQ0Y7QUFzS0QsTUFBTSxPQUFPLG9CQUFxQixTQUFRLEtBQUs7SUFDN0MsWUFBWSxPQUFPLEdBQUcsdUVBQXVFO1FBQzNGLEtBQUssQ0FBQyxPQUFPLENBQUMsQ0FBQztRQUNmLElBQUksQ0FBQyxJQUFJLEdBQUcsc0JBQXNCLENBQUM7SUFDckMsQ0FBQztDQUNGIn0=
@@ -0,0 +1,68 @@
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
+ interface IEarlyToolExecution {
13
+ signature: string;
14
+ controller: AbortController;
15
+ outcome: {
16
+ value: unknown;
17
+ } | {
18
+ error: unknown;
19
+ };
20
+ confirm: () => void;
21
+ reject: (reason: unknown) => void;
22
+ }
23
+ /**
24
+ * Orders the tool calls of one generation in the order the model issued them. Read-only calls run
25
+ * concurrently with each other; any other call starts after every earlier call settled, and later
26
+ * calls wait for it. A read-only call that no running or issued non-read call precedes starts as
27
+ * soon as its input is complete, while the model still streams the rest of its response: the
28
+ * SDK's execution adopts it, and a model call that ends without executing it discards it.
29
+ */
30
+ export declare class AgentToolCallScheduler {
31
+ private readonly signal;
32
+ private readonly calls;
33
+ private readonly order;
34
+ /** Calls that settled and left the order; their IDs are not issued again. */
35
+ private readonly finished;
36
+ constructor(signal: AbortSignal);
37
+ /** Records a call in issue order; a known or finished call keeps its place. */
38
+ issue(toolCallId: string, readOnly: boolean): void;
39
+ /**
40
+ * Starts a complete read-only call before the SDK executes it, when no unsettled non-read call
41
+ * precedes it. `start` receives the call's abort signal and its confirmation.
42
+ */
43
+ startEarly(toolCallId: string, readOnly: boolean, signature: string, start: (signal: AbortSignal, confirmed: Promise<void>) => unknown): void;
44
+ /** Records a call that starts without an early execution, such as a program's call, in issue order. */
45
+ begin(toolCallId: string, readOnly: boolean): void;
46
+ /**
47
+ * Takes over the call the SDK now executes. Returns the early execution's outcome when it
48
+ * started early with the same input; otherwise discards a mismatched early execution and returns
49
+ * undefined, and the caller starts the call after `waitForTurn`.
50
+ */
51
+ adopt(toolCallId: string, signature: string, readOnly: boolean): IEarlyToolExecution['outcome'] | undefined;
52
+ /**
53
+ * Resolves when the call may start, after every unsettled earlier call it must follow; undefined
54
+ * when it can start at once. Every issued call is executed or discarded at the end of its model
55
+ * call, so the calls it waits for settle.
56
+ */
57
+ waitForTurn(toolCallId: string, signal?: AbortSignal): Promise<void> | undefined;
58
+ /** Marks a call finished; the calls waiting for it may start. */
59
+ settle(toolCallId: string): void;
60
+ /**
61
+ * Ends a model call: an early execution the SDK did not adopt is aborted and its confirmation
62
+ * rejected, and an issued call it did not execute no longer holds later calls back.
63
+ */
64
+ endModelCall(reason: unknown): void;
65
+ private precedingCalls;
66
+ private discardEarly;
67
+ }
68
+ export {};
@@ -0,0 +1,163 @@
1
+ /**
2
+ * Orders the tool calls of one generation in the order the model issued them. Read-only calls run
3
+ * concurrently with each other; any other call starts after every earlier call settled, and later
4
+ * calls wait for it. A read-only call that no running or issued non-read call precedes starts as
5
+ * soon as its input is complete, while the model still streams the rest of its response: the
6
+ * SDK's execution adopts it, and a model call that ends without executing it discards it.
7
+ */
8
+ export class AgentToolCallScheduler {
9
+ signal;
10
+ calls = new Map();
11
+ order = [];
12
+ /** Calls that settled and left the order; their IDs are not issued again. */
13
+ finished = new Set();
14
+ constructor(signal) {
15
+ this.signal = signal;
16
+ }
17
+ /** Records a call in issue order; a known or finished call keeps its place. */
18
+ issue(toolCallId, readOnly) {
19
+ if (this.calls.has(toolCallId) || this.finished.has(toolCallId))
20
+ return;
21
+ let resolveDone;
22
+ const done = new Promise((resolve) => {
23
+ resolveDone = resolve;
24
+ });
25
+ const call = {
26
+ toolCallId, readOnly, started: false, settled: false, done, resolveDone,
27
+ };
28
+ this.calls.set(toolCallId, call);
29
+ this.order.push(call);
30
+ }
31
+ /**
32
+ * Starts a complete read-only call before the SDK executes it, when no unsettled non-read call
33
+ * precedes it. `start` receives the call's abort signal and its confirmation.
34
+ */
35
+ startEarly(toolCallId, readOnly, signature, start) {
36
+ this.issue(toolCallId, readOnly);
37
+ const call = this.calls.get(toolCallId);
38
+ if (!call || call.started || call.early || call.settled)
39
+ return;
40
+ call.readOnly = readOnly;
41
+ if (!readOnly || this.signal.aborted)
42
+ return;
43
+ if (this.precedingCalls(call).some((earlier) => !earlier.readOnly))
44
+ return;
45
+ const controller = new AbortController();
46
+ let confirm;
47
+ let reject;
48
+ const confirmed = new Promise((resolve, rejectConfirmation) => {
49
+ confirm = resolve;
50
+ reject = rejectConfirmation;
51
+ });
52
+ void confirmed.catch(() => undefined);
53
+ let outcome;
54
+ try {
55
+ outcome = { value: start(AbortSignal.any([this.signal, controller.signal]), confirmed) };
56
+ }
57
+ catch (error) {
58
+ outcome = { error };
59
+ }
60
+ if ('value' in outcome && isPromiseLike(outcome.value)) {
61
+ void Promise.resolve(outcome.value).catch(() => undefined);
62
+ }
63
+ call.early = { signature, controller, outcome, confirm, reject };
64
+ }
65
+ /** Records a call that starts without an early execution, such as a program's call, in issue order. */
66
+ begin(toolCallId, readOnly) {
67
+ this.issue(toolCallId, readOnly);
68
+ const call = this.calls.get(toolCallId);
69
+ if (call)
70
+ call.started = true;
71
+ }
72
+ /**
73
+ * Takes over the call the SDK now executes. Returns the early execution's outcome when it
74
+ * started early with the same input; otherwise discards a mismatched early execution and returns
75
+ * undefined, and the caller starts the call after `waitForTurn`.
76
+ */
77
+ adopt(toolCallId, signature, readOnly) {
78
+ this.issue(toolCallId, readOnly);
79
+ const call = this.calls.get(toolCallId);
80
+ if (!call)
81
+ return undefined;
82
+ call.started = true;
83
+ const early = call.early;
84
+ if (early?.signature === signature) {
85
+ early.confirm();
86
+ return early.outcome;
87
+ }
88
+ if (early) {
89
+ call.early = undefined;
90
+ this.discardEarly(early, new Error(`Tool call "${toolCallId}" changed after it started early.`));
91
+ }
92
+ call.readOnly = readOnly;
93
+ return undefined;
94
+ }
95
+ /**
96
+ * Resolves when the call may start, after every unsettled earlier call it must follow; undefined
97
+ * when it can start at once. Every issued call is executed or discarded at the end of its model
98
+ * call, so the calls it waits for settle.
99
+ */
100
+ waitForTurn(toolCallId, signal) {
101
+ const call = this.calls.get(toolCallId);
102
+ if (!call)
103
+ return undefined;
104
+ const blockers = this.precedingCalls(call)
105
+ .filter((earlier) => !call.readOnly || !earlier.readOnly)
106
+ .map((earlier) => earlier.done);
107
+ if (blockers.length === 0)
108
+ return undefined;
109
+ const signals = [this.signal, ...(signal ? [signal] : [])];
110
+ return new Promise((resolve, reject) => {
111
+ const onAbort = () => {
112
+ const aborted = signals.find((candidate) => candidate.aborted);
113
+ reject(aborted.reason ?? new DOMException('Aborted', 'AbortError'));
114
+ };
115
+ for (const candidate of signals) {
116
+ if (candidate.aborted)
117
+ return onAbort();
118
+ candidate.addEventListener('abort', onAbort, { once: true });
119
+ }
120
+ void Promise.all(blockers).then(() => {
121
+ for (const candidate of signals)
122
+ candidate.removeEventListener('abort', onAbort);
123
+ resolve();
124
+ });
125
+ });
126
+ }
127
+ /** Marks a call finished; the calls waiting for it may start. */
128
+ settle(toolCallId) {
129
+ const call = this.calls.get(toolCallId);
130
+ if (!call || call.settled)
131
+ return;
132
+ call.settled = true;
133
+ call.resolveDone();
134
+ while (this.order.length > 0 && this.order[0].settled) {
135
+ const settled = this.order.shift();
136
+ this.calls.delete(settled.toolCallId);
137
+ this.finished.add(settled.toolCallId);
138
+ }
139
+ }
140
+ /**
141
+ * Ends a model call: an early execution the SDK did not adopt is aborted and its confirmation
142
+ * rejected, and an issued call it did not execute no longer holds later calls back.
143
+ */
144
+ endModelCall(reason) {
145
+ for (const call of [...this.order]) {
146
+ if (call.started)
147
+ continue;
148
+ if (call.early)
149
+ this.discardEarly(call.early, reason);
150
+ this.settle(call.toolCallId);
151
+ }
152
+ }
153
+ precedingCalls(call) {
154
+ const index = this.order.indexOf(call);
155
+ return this.order.slice(0, index).filter((earlier) => !earlier.settled);
156
+ }
157
+ discardEarly(early, reason) {
158
+ early.reject(reason);
159
+ early.controller.abort(reason);
160
+ }
161
+ }
162
+ const isPromiseLike = (value) => typeof value?.then === 'function';
163
+ //# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoic21hcnRhZ2VudC50b29sc2NoZWR1bGVyLmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vdHNfYWdlbnQvc21hcnRhZ2VudC50b29sc2NoZWR1bGVyLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQStCQTs7Ozs7O0dBTUc7QUFDSCxNQUFNLE9BQU8sc0JBQXNCO0lBTUo7SUFMWixLQUFLLEdBQUcsSUFBSSxHQUFHLEVBQThCLENBQUM7SUFDOUMsS0FBSyxHQUF5QixFQUFFLENBQUM7SUFDbEQsNkVBQTZFO0lBQzVELFFBQVEsR0FBRyxJQUFJLEdBQUcsRUFBVSxDQUFDO0lBRTlDLFlBQTZCLE1BQW1CO1FBQW5CLFdBQU0sR0FBTixNQUFNLENBQWE7SUFBRyxDQUFDO0lBRXBELCtFQUErRTtJQUN4RSxLQUFLLENBQUMsVUFBa0IsRUFBRSxRQUFpQjtRQUNoRCxJQUFJLElBQUksQ0FBQyxLQUFLLENBQUMsR0FBRyxDQUFDLFVBQVUsQ0FBQyxJQUFJLElBQUksQ0FBQyxRQUFRLENBQUMsR0FBRyxDQUFDLFVBQVUsQ0FBQztZQUFFLE9BQU87UUFDeEUsSUFBSSxXQUF3QixDQUFDO1FBQzdCLE1BQU0sSUFBSSxHQUFHLElBQUksT0FBTyxDQUFPLENBQUMsT0FBTyxFQUFFLEVBQUU7WUFDekMsV0FBVyxHQUFHLE9BQU8sQ0FBQztRQUN4QixDQUFDLENBQUMsQ0FBQztRQUNILE1BQU0sSUFBSSxHQUF1QjtZQUMvQixVQUFVLEVBQUUsUUFBUSxFQUFFLE9BQU8sRUFBRSxLQUFLLEVBQUUsT0FBTyxFQUFFLEtBQUssRUFBRSxJQUFJLEVBQUUsV0FBVztTQUN4RSxDQUFDO1FBQ0YsSUFBSSxDQUFDLEtBQUssQ0FBQyxHQUFHLENBQUMsVUFBVSxFQUFFLElBQUksQ0FBQyxDQUFDO1FBQ2pDLElBQUksQ0FBQyxLQUFLLENBQUMsSUFBSSxDQUFDLElBQUksQ0FBQyxDQUFDO0lBQ3hCLENBQUM7SUFFRDs7O09BR0c7SUFDSSxVQUFVLENBQ2YsVUFBa0IsRUFD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
package/package.json CHANGED
@@ -2,7 +2,7 @@
2
2
  "author": "Task Venture Capital GmbH",
3
3
  "license": "MIT",
4
4
  "name": "@modelprofile.com/flexharness-agent",
5
- "version": "10.15.0",
5
+ "version": "10.16.0",
6
6
  "type": "module",
7
7
  "description": "Standalone event-driven agent runtime with generation transactions, context and tool execution contracts.",
8
8
  "main": "./dist_ts_agent/index.js",
@@ -18,7 +18,7 @@
18
18
  }
19
19
  },
20
20
  "dependencies": {
21
- "@modelprofile.com/flexharness-models": "10.15.0",
21
+ "@modelprofile.com/flexharness-models": "10.16.0",
22
22
  "ai": "^7.0.111",
23
23
  "zod": "^4.6.5",
24
24
  "@noble/hashes": "^2.4.0",
package/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
@@ -54,6 +54,7 @@ import {
54
54
  type TAgentModelCallUsageReporter,
55
55
  type TAgentModelCallUsageSource,
56
56
  type TAgentPrompt,
57
+ type TAgentToolCallClassifier,
57
58
  type TAgentToolCallFinishEvent,
58
59
  type TAgentToolExecutionReconciliationOptions,
59
60
  } from './smartagent.interfaces.js';
@@ -63,6 +64,8 @@ import {
63
64
  } from './smartagent.persistence.js';
64
65
  import { MAX_RETRY_ATTEMPTS, planModelCallRetry } from './smartagent.retry.js';
65
66
  import { AgentModelCallUsageRecorder } from './smartagent.usage.js';
67
+ import { AgentToolCallScheduler } from './smartagent.toolscheduler.js';
68
+ import type { IAgentToolExecutionOptions } from './smartagent.toolscheduler.js';
66
69
  import type {
67
70
  IAgentEventArchive,
68
71
  IAgentEventArchiveV2,
@@ -130,6 +133,7 @@ interface IEffectiveGenerationRuntime {
130
133
  model: plugins.TSmartAiLanguageModel;
131
134
  system?: string;
132
135
  tools: plugins.ToolSet;
136
+ isReadOnlyToolCall?: TAgentToolCallClassifier;
133
137
  providerOptions?: plugins.ProviderOptions;
134
138
  maxSteps: number;
135
139
  /** The generation's cache setting gives this provider cache hints: its prefix may be read back. */
@@ -1651,19 +1655,60 @@ export class AgentSessionEngine implements IAgentSession {
1651
1655
  ledger: Map<string, IToolExecutionLedgerEntry>,
1652
1656
  getMessages: () => plugins.ModelMessage[],
1653
1657
  onPreview: (event: IAgentToolCallUpdateEvent) => void,
1658
+ scheduler: AgentToolCallScheduler,
1659
+ isReadOnlyToolCall: TAgentToolCallClassifier | undefined,
1660
+ earlyStarts: Map<string, (toolCallId: string, input: unknown) => void>,
1654
1661
  ): plugins.ToolSet {
1655
1662
  const wrappedTools: plugins.ToolSet = {};
1656
1663
  for (const [toolName, toolDefinition] of Object.entries(tools)) {
1657
1664
  const executableTool = toolDefinition as typeof toolDefinition & {
1658
1665
  execute?: (input: unknown, options: plugins.ToolExecutionOptions<unknown>) => unknown;
1666
+ needsApproval?: unknown;
1667
+ contextSchema?: unknown;
1668
+ onInputAvailable?: (options: { toolCallId: string; input: unknown }) => unknown;
1659
1669
  };
1660
1670
  if (!executableTool.execute) {
1661
1671
  wrappedTools[toolName] = toolDefinition;
1662
1672
  continue;
1663
1673
  }
1664
1674
  const originalExecute = executableTool.execute.bind(executableTool);
1675
+ const originalOnInputAvailable = executableTool.onInputAvailable?.bind(executableTool);
1676
+ const readOnly = (input: unknown): boolean =>
1677
+ isReadOnlyToolCall?.({ toolName, input }) === true;
1678
+ // A call that waits for approval, or for a tool context the session does not pass, is not
1679
+ // executed with its response's calls; it runs outside the order.
1680
+ const scheduled = executableTool.needsApproval === undefined && executableTool.contextSchema === undefined;
1681
+ if (scheduled) {
1682
+ earlyStarts.set(toolName, (toolCallId, input) => {
1683
+ let callReadOnly: boolean;
1684
+ // A classifier that throws fails the call when it executes.
1685
+ try { callReadOnly = readOnly(input); } catch { return; }
1686
+ scheduler.startEarly(toolCallId, callReadOnly, toolSignature(toolName, input),
1687
+ (abortSignal, confirmed) => {
1688
+ const earlyExecutionOptions: plugins.ToolExecutionOptions<unknown> & IAgentToolExecutionOptions = {
1689
+ toolCallId,
1690
+ messages: getMessages(),
1691
+ abortSignal,
1692
+ context: undefined,
1693
+ confirmed,
1694
+ };
1695
+ return this.invokeGenerationCallback(() => originalExecute(input, earlyExecutionOptions));
1696
+ });
1697
+ });
1698
+ }
1665
1699
  wrappedTools[toolName] = {
1666
1700
  ...toolDefinition,
1701
+ // Records the call's place in issue order as soon as its input is complete.
1702
+ onInputAvailable: async (inputOptions: { toolCallId: string; input: unknown }) => {
1703
+ if (scheduled) {
1704
+ const input = parseToolInput(inputOptions.input);
1705
+ let callReadOnly = false;
1706
+ // A classifier that throws fails the call when it executes.
1707
+ try { callReadOnly = readOnly(input); } catch { /* reported by execute */ }
1708
+ scheduler.issue(inputOptions.toolCallId, callReadOnly);
1709
+ }
1710
+ await originalOnInputAvailable?.(inputOptions);
1711
+ },
1667
1712
  execute: (input: unknown, executionOptions: plugins.ToolExecutionOptions<unknown>) => {
1668
1713
  const toolCallId = executionOptions.toolCallId;
1669
1714
  const signature = toolSignature(toolName, input);
@@ -1693,13 +1738,18 @@ export class AgentSessionEngine implements IAgentSession {
1693
1738
  ...executionOptions,
1694
1739
  messages: getMessages(),
1695
1740
  };
1741
+ const callReadOnly = readOnly(input);
1742
+ const early = scheduler.adopt(toolCallId, signature, callReadOnly);
1696
1743
  let resolveCompletion!: (output: unknown) => void;
1697
1744
  let rejectCompletion!: (error: unknown) => void;
1698
1745
  const promise = new Promise<unknown>((resolve, reject) => {
1699
1746
  resolveCompletion = resolve;
1700
1747
  rejectCompletion = reject;
1701
1748
  });
1702
- void promise.catch(() => undefined);
1749
+ void promise.then(
1750
+ () => scheduler.settle(toolCallId),
1751
+ () => scheduler.settle(toolCallId),
1752
+ );
1703
1753
  ledger.set(toolCallId, { signature, promise });
1704
1754
  // Admission is possible only while a durably prepared local tool is executing.
1705
1755
  const jobOwner = this.generationBackgroundJobs;
@@ -1711,9 +1761,17 @@ export class AgentSessionEngine implements IAgentSession {
1711
1761
  );
1712
1762
  }
1713
1763
  try {
1714
- const result = this.invokeGenerationCallback(
1764
+ const run = () => this.invokeGenerationCallback(
1715
1765
  () => originalExecute(input, contextualExecutionOptions),
1716
1766
  );
1767
+ let result: unknown;
1768
+ if (early) {
1769
+ if ('error' in early) throw early.error;
1770
+ result = early.value;
1771
+ } else {
1772
+ const turn = scheduler.waitForTurn(toolCallId, executionOptions.abortSignal);
1773
+ result = turn ? turn.then(run) : run();
1774
+ }
1717
1775
  if (isAsyncIterable(result)) {
1718
1776
  return this.trackToolExecutionIterable(
1719
1777
  result,
@@ -1750,8 +1808,11 @@ export class AgentSessionEngine implements IAgentSession {
1750
1808
  wrappedTools.invalid = plugins.tool({
1751
1809
  description: 'Sink for unrecognised tool calls; returns an error message to the model',
1752
1810
  inputSchema: plugins.z.object({ tool: plugins.z.string(), error: plugins.z.string() }),
1753
- execute: async ({ tool, error }: { tool: string; error: string }) =>
1754
- `Unknown tool "${tool}": ${error}`,
1811
+ execute: async ({ tool, error }: { tool: string; error: string }, { toolCallId }: { toolCallId: string }) => {
1812
+ // A repaired call took its place in the order under the tool the model named.
1813
+ scheduler.adopt(toolCallId, '', true);
1814
+ return `Unknown tool "${tool}": ${error}`;
1815
+ },
1755
1816
  });
1756
1817
  return wrappedTools;
1757
1818
  }
@@ -1932,7 +1993,8 @@ export class AgentSessionEngine implements IAgentSession {
1932
1993
  );
1933
1994
  }
1934
1995
  const system = lease?.system ?? options.system ?? this.options.system;
1935
- const tools = lease?.tools ?? options.tools ?? this.options.tools ?? {};
1996
+ const toolSource = lease?.tools ? lease : options.tools ? options : this.options;
1997
+ const tools = toolSource.tools ?? {};
1936
1998
  if (Object.prototype.hasOwnProperty.call(tools, 'invalid')) {
1937
1999
  throw new Error('Tool name "invalid" is reserved for SmartAgent tool-call repair.');
1938
2000
  }
@@ -1981,6 +2043,7 @@ export class AgentSessionEngine implements IAgentSession {
1981
2043
  model: effectiveModel,
1982
2044
  system,
1983
2045
  tools,
2046
+ ...(toolSource.isReadOnlyToolCall ? { isReadOnlyToolCall: toolSource.isReadOnlyToolCall } : {}),
1984
2047
  providerOptions: effectiveProviderOptions,
1985
2048
  maxSteps,
1986
2049
  cachesPrefix: messageCacheProvider !== undefined
@@ -2262,6 +2325,13 @@ export class AgentSessionEngine implements IAgentSession {
2262
2325
  }));
2263
2326
  await this.flushPersistence();
2264
2327
  };
2328
+ const toolScheduler = new AgentToolCallScheduler(combinedAbort.signal);
2329
+ const earlyToolStarts = new Map<string, (toolCallId: string, input: unknown) => void>();
2330
+ /** Ends the current model call's tool calls the SDK did not execute. */
2331
+ const endModelCallToolCalls = (): void => toolScheduler.endModelCall(new DOMException(
2332
+ 'The model call ended without executing this tool call.',
2333
+ 'AbortError',
2334
+ ));
2265
2335
  const allTools = this.wrapToolsForGeneration(
2266
2336
  generationId,
2267
2337
  runtime.tools,
@@ -2277,6 +2347,9 @@ export class AgentSessionEngine implements IAgentSession {
2277
2347
  this.options.onToolCallUpdate?.(event);
2278
2348
  }
2279
2349
  },
2350
+ toolScheduler,
2351
+ runtime.isReadOnlyToolCall,
2352
+ earlyToolStarts,
2280
2353
  );
2281
2354
 
2282
2355
  const flushReasoning = (): void => {
@@ -2370,6 +2443,17 @@ export class AgentSessionEngine implements IAgentSession {
2370
2443
  reportProviderExecutedTool(chunk as Parameters<typeof reportProviderExecutedTool>[0]);
2371
2444
  return;
2372
2445
  }
2446
+ if (chunkType === 'tool-call') {
2447
+ // A read-only call may start now, while the model streams the rest of its response.
2448
+ const toolCallChunk = chunk as { toolCallId: string; toolName: string; input: unknown; invalid?: boolean };
2449
+ if (toolCallChunk.invalid !== true) {
2450
+ earlyToolStarts.get(toolCallChunk.toolName)?.(
2451
+ toolCallChunk.toolCallId,
2452
+ parseToolInput(toolCallChunk.input),
2453
+ );
2454
+ }
2455
+ return;
2456
+ }
2373
2457
  if (chunkType === 'tool-result') {
2374
2458
  const toolResultChunk = chunk as {
2375
2459
  preliminary?: boolean;
@@ -2514,6 +2598,7 @@ export class AgentSessionEngine implements IAgentSession {
2514
2598
  return promise;
2515
2599
  },
2516
2600
  onToolExecutionEnd: async (finish) => {
2601
+ toolScheduler.settle(finish.toolCall.toolCallId);
2517
2602
  finishedToolCallIds.add(finish.toolCall.toolCallId);
2518
2603
  preliminaryToolOutputs.delete(finish.toolCall.toolCallId);
2519
2604
  const inferenceId = currentInferenceId ?? await beginInference();
@@ -2591,6 +2676,7 @@ export class AgentSessionEngine implements IAgentSession {
2591
2676
  );
2592
2677
  },
2593
2678
  onStepEnd: async (step) => {
2679
+ endModelCallToolCalls();
2594
2680
  if (!currentInferenceId) throw new Error('Model step finished outside an inference.');
2595
2681
  if (!completedInferenceIds.has(currentInferenceId)) {
2596
2682
  completedInferenceIds.add(currentInferenceId);
@@ -2631,6 +2717,8 @@ export class AgentSessionEngine implements IAgentSession {
2631
2717
  await this.flushPersistence();
2632
2718
  finished = { text, finishReason };
2633
2719
  } catch (error) {
2720
+ // A read-only call that started early while the failed response streamed is discarded.
2721
+ endModelCallToolCalls();
2634
2722
  modelCalls.settle(combinedAbort.signal.aborted ? 'aborted' : 'failed');
2635
2723
  flushReasoning();
2636
2724
  const effectiveError = streamError ?? error;
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';