@modelprofile.com/flexharness-agent 13.2.1 → 14.0.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.
@@ -126,7 +126,7 @@ interface IEffectiveGenerationRuntime {
126
126
  tools: plugins.ToolSet;
127
127
  isReadOnlyToolCall?: TAgentToolCallClassifier;
128
128
  providerOptions?: plugins.ProviderOptions;
129
- maxSteps: number;
129
+ maxSteps?: number;
130
130
  maxOutputTokens?: number;
131
131
  /** The generation's cache setting gives this provider cache hints: its prefix may be read back. */
132
132
  cachesPrefix: boolean;
@@ -1640,6 +1640,10 @@ export class AgentSessionEngine implements IAgentSession {
1640
1640
  scheduler: AgentToolCallScheduler,
1641
1641
  isReadOnlyToolCall: TAgentToolCallClassifier | undefined,
1642
1642
  earlyStarts: Map<string, (toolCallId: string, input: unknown) => void>,
1643
+ observeEarlyExecution: (
1644
+ call: { toolCallId: string; toolName: string; input: unknown },
1645
+ run: () => unknown,
1646
+ ) => unknown,
1643
1647
  ): plugins.ToolSet {
1644
1648
  const wrappedTools: plugins.ToolSet = {};
1645
1649
  for (const [toolName, toolDefinition] of Object.entries(tools)) {
@@ -1674,7 +1678,10 @@ export class AgentSessionEngine implements IAgentSession {
1674
1678
  context: undefined,
1675
1679
  confirmed,
1676
1680
  };
1677
- return this.invokeGenerationCallback(() => originalExecute(input, earlyExecutionOptions));
1681
+ return observeEarlyExecution({ toolCallId, toolName, input }, () => {
1682
+ abortSignal.throwIfAborted();
1683
+ return this.invokeGenerationCallback(() => originalExecute(input, earlyExecutionOptions));
1684
+ });
1678
1685
  });
1679
1686
  });
1680
1687
  }
@@ -1714,6 +1721,7 @@ export class AgentSessionEngine implements IAgentSession {
1714
1721
  if (existing.signature !== signature) {
1715
1722
  throw new Error(`Tool call id collision for "${toolCallId}" in generation "${generationId}".`);
1716
1723
  }
1724
+ scheduler.adopt(toolCallId, signature, readOnly(input));
1717
1725
  return existing.promise;
1718
1726
  }
1719
1727
  const contextualExecutionOptions = {
@@ -1980,8 +1988,8 @@ export class AgentSessionEngine implements IAgentSession {
1980
1988
  ?? options.providerOptions
1981
1989
  ?? this.options.providerOptions;
1982
1990
  const cache = lease?.cache ?? options.cache ?? this.options.cache ?? 'auto';
1983
- const maxSteps = lease?.maxSteps ?? options.maxSteps ?? this.options.maxSteps ?? 20;
1984
- if (!Number.isSafeInteger(maxSteps) || maxSteps <= 0) {
1991
+ const maxSteps = lease?.maxSteps ?? options.maxSteps ?? this.options.maxSteps;
1992
+ if (maxSteps !== undefined && (!Number.isSafeInteger(maxSteps) || maxSteps <= 0)) {
1985
1993
  throw new Error('maxSteps must be a positive integer.');
1986
1994
  }
1987
1995
  const maxOutputTokens = lease?.maxOutputTokens;
@@ -2165,8 +2173,16 @@ export class AgentSessionEngine implements IAgentSession {
2165
2173
  const reportCompactionUsage: TAgentModelCallUsageReporter = (call) =>
2166
2174
  recordModelCallUsage({ ...call, source: 'compaction', generationId });
2167
2175
  let currentInferenceId: string | undefined;
2168
- /** Text the current inference streamed so far, kept if the inference is interrupted. */
2169
- let inferenceText = '';
2176
+ // Observations belong to one inference, not one generation or SDK retry. Completed steps
2177
+ // use the SDK response; failed/stopped steps retain only what actually reached onChunk.
2178
+ let inferenceContent: Exclude<IAssistantMessageEvent['content'], string> = [];
2179
+ const inferenceResultConverters = new Map<number, () => Promise<TAgentToolResultOutput>>();
2180
+ const inferenceConversions = new Map<string, Promise<TAgentToolResultOutput>>();
2181
+ const localToolConversionErrors: unknown[] = [];
2182
+ const inferenceTextParts = new Map<string, Extract<
2183
+ Exclude<IAssistantMessageEvent['content'], string>[number],
2184
+ { type: 'text' | 'reasoning' }
2185
+ >>();
2170
2186
  let latestInferenceVisibleIds = new Set(this.events.map((event) => event.id));
2171
2187
  const completedInferenceIds = new Set<string>();
2172
2188
  const reasoningTextById = new Map<string, string>();
@@ -2235,7 +2251,11 @@ export class AgentSessionEngine implements IAgentSession {
2235
2251
  : undefined,
2236
2252
  }));
2237
2253
  currentInferenceId = marker.id;
2238
- inferenceText = '';
2254
+ inferenceContent = [];
2255
+ inferenceTextParts.clear();
2256
+ inferenceResultConverters.clear();
2257
+ inferenceConversions.clear();
2258
+ localToolConversionErrors.length = 0;
2239
2259
  latestInferenceVisibleIds = new Set(this.events.map((event) => event.id));
2240
2260
  return marker.id;
2241
2261
  };
@@ -2281,42 +2301,265 @@ export class AgentSessionEngine implements IAgentSession {
2281
2301
  throw new AggregateError(callbackErrors, 'Reporting applied pending input failed.');
2282
2302
  }
2283
2303
  };
2284
- /**
2285
- * Keeps what a stopped inference produced: the text it streamed and the tool calls it
2286
- * issued, as one assistant message of the generation. Tool calls without a result are
2287
- * closed when the stopped generation is rendered for the model.
2288
- */
2289
- const commitInterruptedInference = async (): Promise<void> => {
2304
+ /** Preserve observed output on failure as well as Stop, without inventing a result. */
2305
+ const commitInterruptedInference = async (): Promise<unknown[]> => {
2290
2306
  const inferenceId = currentInferenceId;
2291
- if (!options.stop?.aborted || !inferenceId || completedInferenceIds.has(inferenceId)) return;
2292
- completedInferenceIds.add(inferenceId);
2307
+ if (!inferenceId || completedInferenceIds.has(inferenceId)) return [];
2293
2308
  if (this.events.some((event) =>
2294
- event.type === 'assistant-message' && event.inferenceId === inferenceId)) return;
2295
- const toolCallParts: TAgentToolCallPart[] = this.events
2296
- .filter((event): event is IToolCallEvent =>
2309
+ event.type === 'assistant-message' && event.inferenceId === inferenceId)) return [];
2310
+ const conversionErrors: unknown[] = [];
2311
+ for (const [index, convert] of inferenceResultConverters) {
2312
+ const part = inferenceContent[index];
2313
+ try {
2314
+ if (part.type === 'tool-result') part.output = await convert();
2315
+ } catch (error) {
2316
+ // Conversion is not execution: keep the observed result, not an invented tool
2317
+ // failure or unknown effect. Report the conversion failure after history is durable.
2318
+ conversionErrors.push(error);
2319
+ }
2320
+ }
2321
+ inferenceResultConverters.clear();
2322
+ const content = [...inferenceContent];
2323
+ // Execution hooks can precede the corresponding onChunk notification.
2324
+ for (const event of this.events) {
2325
+ if (event.type !== 'tool-call' || event.generationId !== generationId
2326
+ || event.inferenceId !== inferenceId) continue;
2327
+ if (content.some((part) => part.type === 'tool-call' && part.toolCallId === event.toolCallId)) continue;
2328
+ content.push({
2329
+ type: 'tool-call', toolCallId: event.toolCallId, toolName: event.toolName,
2330
+ input: event.input, providerExecuted: event.providerExecuted,
2331
+ providerOptions: event.providerOptions,
2332
+ });
2333
+ }
2334
+ for (const part of inferenceContent) {
2335
+ if (part.type !== 'tool-call' || part.providerExecuted !== true) continue;
2336
+ if (content.some((result) => result.type === 'tool-result' && result.toolCallId === part.toolCallId)) continue;
2337
+ content.push({ type: 'text', text:
2338
+ `[Provider-executed tool "${part.toolName}" (${part.toolCallId}): no result was observed; its effect is unknown. Do not automatically repeat its effects.]`,
2339
+ });
2340
+ }
2341
+ if (content.length === 0) return conversionErrors;
2342
+ this.commitResponseMessages([{ role: 'assistant', content }], generationId, inferenceId, executionIntentIds);
2343
+ await this.flushPersistence();
2344
+ return conversionErrors;
2345
+ };
2346
+ const prepareToolCall = (toolCall: { toolCallId: string; toolName: string; input: unknown }): Promise<void> => {
2347
+ const input = parseToolInput(toolCall.input);
2348
+ const signature = toolSignature(toolCall.toolName, input);
2349
+ const existing = preparations.get(toolCall.toolCallId);
2350
+ if (existing) {
2351
+ if (existing.signature !== signature) {
2352
+ throw new Error(`Tool call id collision for "${toolCall.toolCallId}" in generation "${generationId}".`);
2353
+ }
2354
+ return existing.promise;
2355
+ }
2356
+ const promise = Promise.resolve().then(async () => {
2357
+ const startedBeforeInference = !currentInferenceId;
2358
+ const inferenceId = currentInferenceId ?? beginInference();
2359
+ const approvalAssistantEvent = startedBeforeInference
2360
+ ? [...this.events].reverse().find((candidate): candidate is IAssistantMessageEvent =>
2361
+ candidate.type === 'assistant-message'
2362
+ && Array.isArray(candidate.content)
2363
+ && candidate.content.some((part) =>
2364
+ part.type === 'tool-call' && part.toolCallId === toolCall.toolCallId,
2365
+ ),
2366
+ )
2367
+ : undefined;
2368
+ let callEvent = [...this.events].reverse().find((event): event is IToolCallEvent =>
2297
2369
  event.type === 'tool-call'
2298
- && event.generationId === generationId
2299
- && event.inferenceId === inferenceId)
2300
- .map((event) => ({
2301
- type: 'tool-call',
2302
- toolCallId: event.toolCallId,
2303
- toolName: event.toolName,
2304
- input: event.input,
2305
- ...(event.providerExecuted === undefined ? {} : { providerExecuted: event.providerExecuted }),
2306
- ...(event.providerOptions === undefined ? {} : { providerOptions: event.providerOptions }),
2307
- }));
2308
- if (!inferenceText && toolCallParts.length === 0) return;
2309
- this.commitEvent(createAgentEvent<IAssistantMessageEvent>({
2310
- type: 'assistant-message',
2311
- content: [
2312
- ...(inferenceText ? [{ type: 'text' as const, text: inferenceText }] : []),
2313
- ...toolCallParts,
2314
- ],
2370
+ && event.toolCallId === toolCall.toolCallId
2371
+ && (
2372
+ event.generationId === generationId
2373
+ || (
2374
+ !!approvalAssistantEvent?.id
2375
+ && event.parentIds?.includes(approvalAssistantEvent.id) === true
2376
+ )
2377
+ ));
2378
+ if (callEvent && toolSignature(callEvent.toolName, callEvent.input) !== signature) {
2379
+ throw new Error(`Tool call id collision for "${toolCall.toolCallId}" in generation "${generationId}".`);
2380
+ }
2381
+ if (!callEvent) {
2382
+ callEvent = this.commitEvent(createAgentEvent<IToolCallEvent>({
2383
+ type: 'tool-call',
2384
+ toolCallId: toolCall.toolCallId,
2385
+ toolName: toolCall.toolName,
2386
+ input,
2387
+ generationId,
2388
+ inferenceId,
2389
+ causationId: inferenceId,
2390
+ parentIds: [inferenceId],
2391
+ }));
2392
+ }
2393
+ if (options.transaction) {
2394
+ let intent = [...this.events].reverse().find(
2395
+ (event): event is IToolExecutionIntentEvent =>
2396
+ event.type === 'tool-execution-intent'
2397
+ && event.generationId === generationId
2398
+ && event.toolCallId === toolCall.toolCallId,
2399
+ );
2400
+ if (intent && toolSignature(intent.toolName, intent.input) !== signature) {
2401
+ throw new Error(`Tool call id collision for "${toolCall.toolCallId}" in generation "${generationId}".`);
2402
+ }
2403
+ if (!intent) {
2404
+ intent = this.commitEvent(createAgentEvent<IToolExecutionIntentEvent>({
2405
+ type: 'tool-execution-intent',
2406
+ generationId,
2407
+ inferenceId: callEvent.inferenceId,
2408
+ causationId: callEvent.id,
2409
+ toolCallId: toolCall.toolCallId,
2410
+ toolName: toolCall.toolName,
2411
+ input,
2412
+ parentIds: [callEvent.id],
2413
+ }));
2414
+ }
2415
+ executionIntentIds.set(toolCall.toolCallId, intent.id);
2416
+ }
2417
+ // One save makes the call and its execution intent durable before the tool runs.
2418
+ await this.flushPersistence();
2419
+ recordToolCall(toolCalls, toolCallIndexes, toolCall);
2420
+ completedPreparations.add(toolCall.toolCallId);
2421
+ const callbackEvent: IAgentToolCallStartEvent = {
2422
+ toolCallId: toolCall.toolCallId,
2423
+ toolName: toolCall.toolName,
2424
+ input,
2425
+ };
2426
+ this.options.onToolCallStart?.(callbackEvent);
2427
+ this.options.onToolCall?.(callbackEvent.toolName, callbackEvent.input);
2428
+ });
2429
+ preparations.set(toolCall.toolCallId, { signature, promise });
2430
+ void promise.catch((error) => {
2431
+ if (!completedPreparations.has(toolCall.toolCallId)) {
2432
+ preparationErrors.set(toolCall.toolCallId, error);
2433
+ }
2434
+ });
2435
+ return promise;
2436
+ };
2437
+ const finishToolCall = async (finish: {
2438
+ toolCall: { toolCallId: string; toolName: string; input: unknown };
2439
+ toolOutput: { type: 'tool-result'; output: unknown } | { type: 'tool-error'; error: unknown };
2440
+ }, unknownEffect = false): Promise<void> => {
2441
+ toolScheduler.settle(finish.toolCall.toolCallId);
2442
+ finishedToolCallIds.add(finish.toolCall.toolCallId);
2443
+ preliminaryToolOutputs.delete(finish.toolCall.toolCallId);
2444
+ const inferenceId = currentInferenceId ?? beginInference();
2445
+ const previousResult = this.currentGenerationEvent(
2446
+ generationId,
2447
+ 'tool-result',
2448
+ finish.toolCall.toolCallId,
2449
+ );
2450
+ if (this.currentGenerationEvent(
2451
+ generationId,
2452
+ 'tool-result',
2453
+ finish.toolCall.toolCallId,
2454
+ inferenceId,
2455
+ )) return;
2456
+ const input = parseToolInput(finish.toolCall.input);
2457
+ const startEvent: IAgentToolCallStartEvent = {
2458
+ toolCallId: finish.toolCall.toolCallId,
2459
+ toolName: finish.toolCall.toolName,
2460
+ input,
2461
+ };
2462
+ const finishEvent: TAgentToolCallFinishEvent = finish.toolOutput.type === 'tool-result'
2463
+ ? { ...startEvent, success: true, output: finish.toolOutput.output }
2464
+ : { ...startEvent, success: false, error: errorToString(finish.toolOutput.error) };
2465
+ const parentCall = this.currentGenerationEvent(
2466
+ generationId,
2467
+ 'tool-call',
2468
+ finish.toolCall.toolCallId,
2469
+ inferenceId,
2470
+ );
2471
+ const toolWithModelOutput = allTools[finish.toolCall.toolName] as {
2472
+ toModelOutput?: (options: {
2473
+ toolCallId: string;
2474
+ input: unknown;
2475
+ output: unknown;
2476
+ }) => Promise<TAgentToolResultOutput> | TAgentToolResultOutput;
2477
+ } | undefined;
2478
+ let modelOutput: TAgentToolResultOutput | undefined;
2479
+ let conversionFailed = false;
2480
+ let conversionError: unknown;
2481
+ try {
2482
+ modelOutput = finishEvent.success && toolWithModelOutput?.toModelOutput
2483
+ ? await this.invokeGenerationCallback(
2484
+ () => toolWithModelOutput.toModelOutput!({
2485
+ toolCallId: finish.toolCall.toolCallId,
2486
+ input,
2487
+ output: finishEvent.output,
2488
+ }),
2489
+ )
2490
+ : fallbackModelOutput(
2491
+ finishEvent.success ? finishEvent.output : undefined,
2492
+ finishEvent.success ? undefined : finishEvent.error,
2493
+ );
2494
+ } catch (error) {
2495
+ // Presentation failed, not execution. Save the actual outcome without inventing
2496
+ // model output, then propagate the converter error after observations are durable.
2497
+ conversionFailed = true;
2498
+ conversionError = error;
2499
+ localToolConversionErrors.push(error);
2500
+ }
2501
+ // A protocol-closing unknown result must not settle the recovery intent.
2502
+ const executionIntentId = unknownEffect ? undefined : executionIntentIds.get(finish.toolCall.toolCallId);
2503
+ this.commitEvent(createAgentEvent<IToolResultEvent>({
2504
+ type: 'tool-result',
2505
+ toolCallId: finish.toolCall.toolCallId,
2506
+ toolName: finish.toolCall.toolName,
2507
+ ...(executionIntentId ? { executionIntentId } : {}),
2508
+ output: finishEvent.success ? finishEvent.output : undefined,
2509
+ error: finishEvent.success ? undefined : finishEvent.error,
2510
+ modelOutput,
2315
2511
  generationId,
2316
2512
  inferenceId,
2317
2513
  causationId: inferenceId,
2514
+ parentIds: parentCall ? [parentCall.id] : [inferenceId],
2318
2515
  }));
2319
2516
  await this.flushPersistence();
2517
+ recordToolCall(
2518
+ toolCalls,
2519
+ toolCallIndexes,
2520
+ finish.toolCall,
2521
+ finishEvent.success ? { output: finishEvent.output } : { error: finishEvent.error },
2522
+ );
2523
+ if (!previousResult) {
2524
+ this.options.onToolCallFinish?.(finishEvent);
2525
+ this.options.onToolResult?.(
2526
+ finishEvent.toolName,
2527
+ finishEvent.success ? finishEvent.output : undefined,
2528
+ );
2529
+ }
2530
+ if (conversionFailed) throw conversionError;
2531
+ };
2532
+ // Track actual early executions independently of SDK adoption. A failed transport does
2533
+ // not undo a tool that already ran, nor authorize replay of a still-unknown execution.
2534
+ const earlyExecutions = new Map<string, {
2535
+ call: { toolCallId: string; toolName: string; input: unknown };
2536
+ promise: Promise<unknown>;
2537
+ outcome?: { type: 'tool-result'; output: unknown } | { type: 'tool-error'; error: unknown };
2538
+ }>();
2539
+ let unknownEarlyExecution = false;
2540
+ const retainUnadoptedEarlyExecutions = async (): Promise<unknown[]> => {
2541
+ const errors: unknown[] = [];
2542
+ for (const [id, execution] of earlyExecutions) {
2543
+ if (ledger.has(id)) continue; // SDK adoption already owns its result.
2544
+ try {
2545
+ await preparations.get(id)?.promise;
2546
+ const outcome = execution.outcome;
2547
+ const unknown = new Error(
2548
+ 'The early tool call ended before its result was observed; its effect is unknown. Do not automatically repeat its effects.',
2549
+ );
2550
+ if (!outcome) unknownEarlyExecution = true;
2551
+ const promise = outcome ? execution.promise : Promise.reject(unknown);
2552
+ void promise.catch(() => undefined);
2553
+ ledger.set(id, { signature: toolSignature(execution.call.toolName, execution.call.input), promise });
2554
+ await finishToolCall({ toolCall: execution.call,
2555
+ toolOutput: outcome ?? { type: 'tool-error', error: unknown } }, !outcome);
2556
+ } catch (error) {
2557
+ // One result's conversion/reporting must not abandon any other actual execution.
2558
+ errors.push(error);
2559
+ }
2560
+ }
2561
+ earlyExecutions.clear();
2562
+ return errors;
2320
2563
  };
2321
2564
  const toolScheduler = new AgentToolCallScheduler(combinedAbort.signal);
2322
2565
  const earlyToolStarts = new Map<string, (toolCallId: string, input: unknown) => void>();
@@ -2343,8 +2586,56 @@ export class AgentSessionEngine implements IAgentSession {
2343
2586
  toolScheduler,
2344
2587
  runtime.isReadOnlyToolCall,
2345
2588
  earlyToolStarts,
2589
+ (call, run) => {
2590
+ const existing = ledger.get(call.toolCallId);
2591
+ if (existing) {
2592
+ if (existing.signature !== toolSignature(call.toolName, call.input)) {
2593
+ throw new Error(`Tool call id collision for "${call.toolCallId}" in generation "${generationId}".`);
2594
+ }
2595
+ return existing.promise;
2596
+ }
2597
+ const execution: {
2598
+ call: typeof call;
2599
+ promise: Promise<unknown>;
2600
+ outcome?: { type: 'tool-result'; output: unknown } | { type: 'tool-error'; error: unknown };
2601
+ } = { call, promise: Promise.resolve() };
2602
+ execution.promise = prepareToolCall(call).then(run).then((value) => {
2603
+ if (isAsyncIterable(value)) {
2604
+ return this.trackToolExecutionIterable(value,
2605
+ (output) => { execution.outcome = { type: 'tool-result', output }; },
2606
+ (error) => { execution.outcome = { type: 'tool-error', error }; },
2607
+ () => undefined);
2608
+ }
2609
+ execution.outcome = { type: 'tool-result', output: value };
2610
+ return value;
2611
+ }, (error: unknown) => {
2612
+ execution.outcome = { type: 'tool-error', error };
2613
+ throw error;
2614
+ });
2615
+ earlyExecutions.set(call.toolCallId, execution);
2616
+ return execution.promise;
2617
+ },
2346
2618
  );
2347
2619
 
2620
+ // The SDK converts completed responses; interrupted responses convert here instead.
2621
+ // Share the attempt so an SDK conversion failure is neither retried nor allowed to
2622
+ // erase the actual provider result when the interrupted history is committed.
2623
+ for (const [toolName, definition] of Object.entries(allTools)) {
2624
+ if (definition.type !== 'provider' || !definition.toModelOutput) continue;
2625
+ const convert = definition.toModelOutput;
2626
+ allTools[toolName] = {
2627
+ ...definition,
2628
+ toModelOutput: (options: Parameters<typeof convert>[0]) => {
2629
+ let conversion = inferenceConversions.get(options.toolCallId);
2630
+ if (!conversion) {
2631
+ conversion = Promise.resolve().then(() => this.invokeGenerationCallback(() => convert(options)));
2632
+ inferenceConversions.set(options.toolCallId, conversion);
2633
+ }
2634
+ return conversion;
2635
+ },
2636
+ };
2637
+ }
2638
+
2348
2639
  const flushReasoning = (): void => {
2349
2640
  for (const [id, reasoningText] of reasoningTextById) {
2350
2641
  this.options.onReasoningEnd?.(id, reasoningText);
@@ -2353,15 +2644,19 @@ export class AgentSessionEngine implements IAgentSession {
2353
2644
  };
2354
2645
 
2355
2646
  while (true) {
2356
- const remainingSteps = maxSteps - stepCount;
2357
- if (remainingSteps <= 0) {
2647
+ const remainingSteps = maxSteps === undefined ? undefined : maxSteps - stepCount;
2648
+ if (remainingSteps !== undefined && remainingSteps <= 0) {
2358
2649
  throw new Error(`Agent generation exhausted its ${maxSteps} step limit during retry.`);
2359
2650
  }
2360
2651
  let streamError: unknown;
2361
2652
  let finished!: { text: string; finishReason: IAgentGenerateResult['finishReason'] };
2362
2653
  try {
2363
2654
  currentInferenceId = undefined;
2364
- inferenceText = '';
2655
+ inferenceContent = [];
2656
+ inferenceTextParts.clear();
2657
+ inferenceResultConverters.clear();
2658
+ inferenceConversions.clear();
2659
+ localToolConversionErrors.length = 0;
2365
2660
  const result = plugins.streamText({
2366
2661
  model: runtime.model,
2367
2662
  instructions: runtime.system,
@@ -2372,7 +2667,10 @@ export class AgentSessionEngine implements IAgentSession {
2372
2667
  ...(runtime.maxOutputTokens === undefined ? {} : { maxOutputTokens: runtime.maxOutputTokens }),
2373
2668
  // A step whose stream reported an error fails the model call, and no step follows it,
2374
2669
  // even when the provider still finished the stream and its tool calls executed.
2375
- stopWhen: [plugins.stepCountIs(remainingSteps), () => streamError !== undefined],
2670
+ stopWhen: [
2671
+ ...(remainingSteps === undefined ? [] : [plugins.stepCountIs(remainingSteps)]),
2672
+ () => streamError !== undefined,
2673
+ ],
2376
2674
  maxRetries: 0,
2377
2675
  abortSignal: combinedAbort.signal,
2378
2676
  ...(attachmentDownload ? { experimental_download: attachmentDownload } : {}),
@@ -2424,11 +2722,55 @@ export class AgentSessionEngine implements IAgentSession {
2424
2722
  };
2425
2723
  },
2426
2724
  onChunk: ({ chunk }) => {
2725
+ if (chunk.type === 'text-start' || chunk.type === 'reasoning-start'
2726
+ || chunk.type === 'text-delta' || chunk.type === 'reasoning-delta'
2727
+ || chunk.type === 'text-end' || chunk.type === 'reasoning-end') {
2728
+ const type: 'text' | 'reasoning' = chunk.type.startsWith('text-') ? 'text' : 'reasoning';
2729
+ const key = `${type}:${chunk.id}`;
2730
+ const existingPart = inferenceTextParts.get(key);
2731
+ const part = existingPart ?? (type === 'text'
2732
+ ? { type: 'text' as const, text: '' }
2733
+ : { type: 'reasoning' as const, text: '' });
2734
+ if (!existingPart) {
2735
+ inferenceTextParts.set(key, part);
2736
+ inferenceContent.push(part);
2737
+ }
2738
+ if (chunk.type === 'text-delta' || chunk.type === 'reasoning-delta') part.text += chunk.text;
2739
+ if (chunk.providerMetadata !== undefined) part.providerOptions = chunk.providerMetadata;
2740
+ }
2741
+ if (chunk.type === 'tool-call') {
2742
+ inferenceContent.push({
2743
+ type: 'tool-call', toolCallId: chunk.toolCallId, toolName: chunk.toolName,
2744
+ input: chunk.input, providerExecuted: chunk.providerExecuted,
2745
+ providerOptions: chunk.providerMetadata,
2746
+ });
2747
+ }
2748
+ if ((chunk.type === 'tool-result' || chunk.type === 'tool-error')
2749
+ && chunk.providerExecuted === true
2750
+ && !(chunk.type === 'tool-result' && chunk.preliminary === true)) {
2751
+ const definition = allTools[chunk.toolName];
2752
+ const jsonError = chunk.type === 'tool-error'
2753
+ ? fallbackModelOutput(chunk.error) as Extract<TAgentToolResultOutput, { type: 'text' | 'json' }>
2754
+ : undefined;
2755
+ const output: TAgentToolResultOutput = chunk.type === 'tool-error'
2756
+ ? { type: 'error-json', value: jsonError!.value }
2757
+ : fallbackModelOutput(chunk.output);
2758
+ if (chunk.type === 'tool-result' && definition?.toModelOutput) {
2759
+ inferenceResultConverters.set(inferenceContent.length, async () => this.invokeGenerationCallback(
2760
+ () => definition.toModelOutput!({
2761
+ toolCallId: chunk.toolCallId, input: chunk.input, output: chunk.output,
2762
+ }),
2763
+ ));
2764
+ }
2765
+ inferenceContent.push({
2766
+ type: 'tool-result', toolCallId: chunk.toolCallId, toolName: chunk.toolName,
2767
+ output, providerOptions: chunk.providerMetadata,
2768
+ });
2769
+ }
2427
2770
  const chunkType = String((chunk as { type?: unknown }).type ?? '');
2428
2771
  if (chunkType === 'text-delta') {
2429
2772
  const textChunk = chunk as { delta?: string; textDelta?: string; text?: string };
2430
2773
  const delta = textChunk.delta ?? textChunk.textDelta ?? textChunk.text ?? '';
2431
- inferenceText += delta;
2432
2774
  this.options.onToken?.(delta);
2433
2775
  return;
2434
2776
  }
@@ -2503,180 +2845,33 @@ export class AgentSessionEngine implements IAgentSession {
2503
2845
  this.options.onReasoningEnd?.(id, text, reasoningChunk.providerMetadata);
2504
2846
  }
2505
2847
  },
2506
- onToolExecutionStart: ({ toolCall }) => {
2507
- const input = parseToolInput(toolCall.input);
2508
- const signature = toolSignature(toolCall.toolName, input);
2509
- const existing = preparations.get(toolCall.toolCallId);
2510
- if (existing) {
2511
- if (existing.signature !== signature) {
2512
- throw new Error(`Tool call id collision for "${toolCall.toolCallId}" in generation "${generationId}".`);
2513
- }
2514
- return existing.promise;
2848
+ onToolExecutionStart: ({ toolCall }) => prepareToolCall(toolCall),
2849
+ onToolExecutionEnd: finishToolCall,
2850
+ onStepEnd: async (step) => {
2851
+ endModelCallToolCalls();
2852
+ const earlyErrors = await retainUnadoptedEarlyExecutions();
2853
+ if (earlyErrors.length === 1) throw earlyErrors[0];
2854
+ if (earlyErrors.length > 1) {
2855
+ throw new AggregateError(earlyErrors, 'Retaining early tool executions failed.');
2515
2856
  }
2516
- const promise = Promise.resolve().then(async () => {
2517
- const startedBeforeInference = !currentInferenceId;
2518
- const inferenceId = currentInferenceId ?? beginInference();
2519
- const approvalAssistantEvent = startedBeforeInference
2520
- ? [...this.events].reverse().find((candidate): candidate is IAssistantMessageEvent =>
2521
- candidate.type === 'assistant-message'
2522
- && Array.isArray(candidate.content)
2523
- && candidate.content.some((part) =>
2524
- part.type === 'tool-call' && part.toolCallId === toolCall.toolCallId,
2525
- ),
2526
- )
2527
- : undefined;
2528
- let callEvent = [...this.events].reverse().find((event): event is IToolCallEvent =>
2529
- event.type === 'tool-call'
2530
- && event.toolCallId === toolCall.toolCallId
2531
- && (
2532
- event.generationId === generationId
2533
- || (
2534
- !!approvalAssistantEvent?.id
2535
- && event.parentIds?.includes(approvalAssistantEvent.id) === true
2536
- )
2537
- ));
2538
- if (callEvent && toolSignature(callEvent.toolName, callEvent.input) !== signature) {
2539
- throw new Error(`Tool call id collision for "${toolCall.toolCallId}" in generation "${generationId}".`);
2540
- }
2541
- if (!callEvent) {
2542
- callEvent = this.commitEvent(createAgentEvent<IToolCallEvent>({
2543
- type: 'tool-call',
2544
- toolCallId: toolCall.toolCallId,
2545
- toolName: toolCall.toolName,
2546
- input,
2547
- generationId,
2548
- inferenceId,
2549
- causationId: inferenceId,
2550
- parentIds: [inferenceId],
2551
- }));
2552
- }
2553
- if (options.transaction) {
2554
- let intent = [...this.events].reverse().find(
2555
- (event): event is IToolExecutionIntentEvent =>
2556
- event.type === 'tool-execution-intent'
2557
- && event.generationId === generationId
2558
- && event.toolCallId === toolCall.toolCallId,
2559
- );
2560
- if (intent && toolSignature(intent.toolName, intent.input) !== signature) {
2561
- throw new Error(`Tool call id collision for "${toolCall.toolCallId}" in generation "${generationId}".`);
2562
- }
2563
- if (!intent) {
2564
- intent = this.commitEvent(createAgentEvent<IToolExecutionIntentEvent>({
2565
- type: 'tool-execution-intent',
2566
- generationId,
2567
- inferenceId: callEvent.inferenceId,
2568
- causationId: callEvent.id,
2569
- toolCallId: toolCall.toolCallId,
2570
- toolName: toolCall.toolName,
2571
- input,
2572
- parentIds: [callEvent.id],
2573
- }));
2857
+ // Failed steps are committed from observations in the catch path, not from an
2858
+ // SDK response that may be incomplete or include unobserved content.
2859
+ if (streamError !== undefined) {
2860
+ // The SDK already converted these outputs. Reuse that conversion, but retain
2861
+ // only results we observed; abrupt streams use the deferred converter instead.
2862
+ for (const message of step.response.messages) {
2863
+ if (message.role !== 'assistant' || !Array.isArray(message.content)) continue;
2864
+ for (const part of message.content) {
2865
+ if (part.type !== 'tool-result') continue;
2866
+ const index = inferenceContent.findIndex((observed) =>
2867
+ observed.type === 'tool-result' && observed.toolCallId === part.toolCallId);
2868
+ if (index < 0) continue;
2869
+ inferenceContent[index] = part;
2870
+ inferenceResultConverters.delete(index);
2574
2871
  }
2575
- executionIntentIds.set(toolCall.toolCallId, intent.id);
2576
2872
  }
2577
- // One save makes the call and its execution intent durable before the tool runs.
2578
- await this.flushPersistence();
2579
- recordToolCall(toolCalls, toolCallIndexes, toolCall);
2580
- completedPreparations.add(toolCall.toolCallId);
2581
- const callbackEvent: IAgentToolCallStartEvent = {
2582
- toolCallId: toolCall.toolCallId,
2583
- toolName: toolCall.toolName,
2584
- input,
2585
- };
2586
- this.options.onToolCallStart?.(callbackEvent);
2587
- this.options.onToolCall?.(callbackEvent.toolName, callbackEvent.input);
2588
- });
2589
- preparations.set(toolCall.toolCallId, { signature, promise });
2590
- void promise.catch((error) => {
2591
- if (!completedPreparations.has(toolCall.toolCallId)) {
2592
- preparationErrors.set(toolCall.toolCallId, error);
2593
- }
2594
- });
2595
- return promise;
2596
- },
2597
- onToolExecutionEnd: async (finish) => {
2598
- toolScheduler.settle(finish.toolCall.toolCallId);
2599
- finishedToolCallIds.add(finish.toolCall.toolCallId);
2600
- preliminaryToolOutputs.delete(finish.toolCall.toolCallId);
2601
- const inferenceId = currentInferenceId ?? beginInference();
2602
- const previousResult = this.currentGenerationEvent(
2603
- generationId,
2604
- 'tool-result',
2605
- finish.toolCall.toolCallId,
2606
- );
2607
- if (this.currentGenerationEvent(
2608
- generationId,
2609
- 'tool-result',
2610
- finish.toolCall.toolCallId,
2611
- inferenceId,
2612
- )) return;
2613
- const input = parseToolInput(finish.toolCall.input);
2614
- const startEvent: IAgentToolCallStartEvent = {
2615
- toolCallId: finish.toolCall.toolCallId,
2616
- toolName: finish.toolCall.toolName,
2617
- input,
2618
- };
2619
- const finishEvent: TAgentToolCallFinishEvent = finish.toolOutput.type === 'tool-result'
2620
- ? { ...startEvent, success: true, output: finish.toolOutput.output }
2621
- : { ...startEvent, success: false, error: errorToString(finish.toolOutput.error) };
2622
- const parentCall = this.currentGenerationEvent(
2623
- generationId,
2624
- 'tool-call',
2625
- finish.toolCall.toolCallId,
2626
- inferenceId,
2627
- );
2628
- const toolWithModelOutput = allTools[finish.toolCall.toolName] as {
2629
- toModelOutput?: (options: {
2630
- toolCallId: string;
2631
- input: unknown;
2632
- output: unknown;
2633
- }) => Promise<TAgentToolResultOutput> | TAgentToolResultOutput;
2634
- } | undefined;
2635
- const modelOutput = finishEvent.success && toolWithModelOutput?.toModelOutput
2636
- ? await this.invokeGenerationCallback(
2637
- () => toolWithModelOutput.toModelOutput!({
2638
- toolCallId: finish.toolCall.toolCallId,
2639
- input,
2640
- output: finishEvent.output,
2641
- }),
2642
- )
2643
- : fallbackModelOutput(
2644
- finishEvent.success ? finishEvent.output : undefined,
2645
- finishEvent.success ? undefined : finishEvent.error,
2646
- );
2647
- const executionIntentId = executionIntentIds.get(finish.toolCall.toolCallId);
2648
- this.commitEvent(createAgentEvent<IToolResultEvent>({
2649
- type: 'tool-result',
2650
- toolCallId: finish.toolCall.toolCallId,
2651
- toolName: finish.toolCall.toolName,
2652
- ...(executionIntentId ? { executionIntentId } : {}),
2653
- output: finishEvent.success ? finishEvent.output : undefined,
2654
- error: finishEvent.success ? undefined : finishEvent.error,
2655
- modelOutput,
2656
- generationId,
2657
- inferenceId,
2658
- causationId: inferenceId,
2659
- parentIds: parentCall ? [parentCall.id] : [inferenceId],
2660
- }));
2661
- await this.flushPersistence();
2662
- recordToolCall(
2663
- toolCalls,
2664
- toolCallIndexes,
2665
- finish.toolCall,
2666
- finishEvent.success ? { output: finishEvent.output } : { error: finishEvent.error },
2667
- );
2668
- if (previousResult) return;
2669
- this.options.onToolCallFinish?.(finishEvent);
2670
- this.options.onToolResult?.(
2671
- finishEvent.toolName,
2672
- finishEvent.success ? finishEvent.output : undefined,
2673
- );
2674
- },
2675
- onStepEnd: async (step) => {
2676
- endModelCallToolCalls();
2677
- // The model call failed: it is retried or fails the generation, and like a call whose
2678
- // stream threw, its partial response is not committed.
2679
- if (streamError !== undefined) return;
2873
+ return;
2874
+ }
2680
2875
  if (!currentInferenceId) throw new Error('Model step finished outside an inference.');
2681
2876
  if (!completedInferenceIds.has(currentInferenceId)) {
2682
2877
  completedInferenceIds.add(currentInferenceId);
@@ -2718,17 +2913,29 @@ export class AgentSessionEngine implements IAgentSession {
2718
2913
  await this.flushPersistence();
2719
2914
  finished = { text, finishReason };
2720
2915
  } catch (error) {
2721
- // A read-only call that started early while the failed response streamed is discarded.
2916
+ // Abort unadopted calls and reject confirmation, but retain their observed outcomes.
2722
2917
  endModelCallToolCalls();
2918
+ const earlyErrors = await retainUnadoptedEarlyExecutions();
2723
2919
  modelCalls.settle(combinedAbort.signal.aborted ? 'aborted' : 'failed');
2724
2920
  flushReasoning();
2725
2921
  const effectiveError = streamError ?? error;
2922
+ const conversionErrors = [
2923
+ ...localToolConversionErrors,
2924
+ ...earlyErrors,
2925
+ ...await commitInterruptedInference(),
2926
+ ];
2927
+ if (conversionErrors.length > 0) {
2928
+ const cause = combinedAbort.signal.aborted
2929
+ ? combinedAbort.signal.reason ?? new DOMException('Aborted', 'AbortError')
2930
+ : effectiveError;
2931
+ const errors = [...new Set([cause, ...conversionErrors])];
2932
+ if (errors.length === 1) throw errors[0];
2933
+ throw new AggregateError(errors,
2934
+ `Inference interrupted and observed tool output conversion failed: ${errors.map(errorToString).join('; ')}`);
2935
+ }
2726
2936
  if (combinedAbort.signal.aborted) {
2727
- await commitInterruptedInference();
2728
2937
  throw combinedAbort.signal.reason ?? new DOMException('Aborted', 'AbortError');
2729
2938
  }
2730
- // A failed attempt is retried or fails the generation; its partial text is not kept.
2731
- inferenceText = '';
2732
2939
  if (effectiveError instanceof DOMException && effectiveError.name === 'AbortError') {
2733
2940
  throw effectiveError;
2734
2941
  }
@@ -2746,7 +2953,12 @@ export class AgentSessionEngine implements IAgentSession {
2746
2953
  stepCount++;
2747
2954
  }
2748
2955
 
2749
- const retry = stepCount < maxSteps
2956
+ // Provider execution is outside our local exactly-once ledger. Once observed, a
2957
+ // retry could repeat remote effects, even when its result never arrived.
2958
+ const providerExecutionObserved = inferenceContent.some((part) =>
2959
+ part.type === 'tool-call' && part.providerExecuted === true);
2960
+ if (providerExecutionObserved || unknownEarlyExecution) throw effectiveError;
2961
+ const retry = (maxSteps === undefined || stepCount < maxSteps)
2750
2962
  ? planModelCallRetry(effectiveError, {
2751
2963
  attempt,
2752
2964
  retriedMs,
@@ -2797,7 +3009,7 @@ export class AgentSessionEngine implements IAgentSession {
2797
3009
 
2798
3010
  // The model ended the generation. Input committed to it after its model's last look,
2799
3011
  // such as a background result, is taken in with another step while steps remain.
2800
- if (stepCount < maxSteps && (options.beforeFinish || this.generationBackgroundJobs?.entries.size)) {
3012
+ if ((maxSteps === undefined || stepCount < maxSteps) && (options.beforeFinish || this.generationBackgroundJobs?.entries.size)) {
2801
3013
  // Finish waits are scoped to this boundary. Steering, owned completions and the
2802
3014
  // bounded timer all lead back to normal inference without cancelling background work.
2803
3015
  const finishWait = new AbortController();
@@ -2853,7 +3065,7 @@ export class AgentSessionEngine implements IAgentSession {
2853
3065
  }
2854
3066
  if ((options.pendingInput?.size ?? 0) > 0) continue;
2855
3067
  }
2856
- if (stepCount < maxSteps && this.events.some((event) =>
3068
+ if ((maxSteps === undefined || stepCount < maxSteps) && this.events.some((event) =>
2857
3069
  event.type === 'user-message'
2858
3070
  && event.generationId === generationId
2859
3071
  && !latestInferenceVisibleIds.has(event.id))) {
@@ -2869,7 +3081,7 @@ export class AgentSessionEngine implements IAgentSession {
2869
3081
  messages: this.buildContext(this.eventsByIds(resultVisibleIds)),
2870
3082
  steps: stepCount,
2871
3083
  finishReason: finished.finishReason,
2872
- terminationReason: stepCount >= maxSteps && (
3084
+ terminationReason: maxSteps !== undefined && stepCount >= maxSteps && (
2873
3085
  finished.finishReason === 'tool-calls'
2874
3086
  || (this.generationBackgroundJobs?.entries.size ?? 0) > 0
2875
3087
  || (options.pendingInput?.size ?? 0) > 0