@modelprofile.com/flexharness-agent 9.9.1 → 9.10.0

package/ts_agent/smartagent.interfaces.ts

@@ -17,6 +17,7 @@ import type {
   TAgentToolResultOutput,
 } from './smartagent.events.js';
 import type { TAgentEventArchive, TAgentEventStore } from './smartagent.persistence.js';
+import type { AgentPendingInputQueue, IAgentAppliedInput } from './smartagent.pendinginput.js';
 import type { IAgentRetryEvent } from './smartagent.retry.js';
 
 export type { ProviderOptions };
@@ -273,6 +274,14 @@ export interface IAgentBeginGenerationOptions {
   generationId?: string;
 }
 
+export interface IAgentFinalizeGenerationOptions {
+  /**
+   * With outcome `interrupted`: the owner stopped the generation, so what its model produced
+   * stays in the model context.
+   */
+  stopped?: boolean;
+}
+
 export interface IAgentGenerationPreparationContext {
   generationId: string;
   abortSignal: AbortSignal;
@@ -337,6 +346,13 @@ export interface IAgentGenerateOptions {
   maxSteps?: number;
   /** Cancels only this generation and its synchronous tool executions. */
   abort?: AbortSignal;
+  /**
+   * Stops a transactional generation the way a user stops a turn. It ends the generation like
+   * `abort`, but the interrupted outcome records the stop: the text the running model step
+   * streamed and the tool calls it issued are kept, and the generation stays in the model
+   * context once its model produced output. An aborted or failed generation is not kept.
+   */
+  stop?: AbortSignal;
   /** Opt-in transactional claim returned by beginGeneration(). */
   transaction?: IAgentGenerationHandle;
   /**
@@ -346,6 +362,14 @@ export interface IAgentGenerateOptions {
    * The callback owns cleanup of partial acquisition if it throws before returning a lease.
    */
   prepare?: TAgentGenerationPrepare;
+  /**
+   * User input the generation takes in at its step boundaries, recorded as user messages of
+   * the generation. The generation closes the queue when it ends; `close()` then returns the
+   * inputs it never took in.
+   */
+  pendingInput?: AgentPendingInputQueue;
+  /** Called once per input taken from `pendingInput`, after it is durable and before the next model call. */
+  onInputApplied?: (input: IAgentAppliedInput) => void | Promise<void>;
 }
 
 export interface IAgentScheduleGenerateOptions extends IAgentGenerateOptions {
@@ -413,6 +437,7 @@ export interface IAgentSession {
   finalizeGeneration(
     transaction: IAgentGenerationHandle,
     outcome: TAgentGenerationOutcome,
+    options?: IAgentFinalizeGenerationOptions,
   ): Promise<void>;
   listUncertainToolExecutions(): IToolExecutionIntentEvent[];
   reconcileToolExecution(

package/ts_agent/smartagent.pendinginput.ts

@@ -0,0 +1,116 @@
+import type { TAgentPrompt } from './smartagent.interfaces.js';
+
+/** One user input that a running generation takes in at its next step boundary. */
+export interface IAgentPendingInput {
+  /** Caller-chosen identity, unique within its queue. */
+  inputId: string;
+  content: TAgentPrompt;
+}
+
+/** A pending input the generation recorded as a user message of its own. */
+export interface IAgentAppliedInput {
+  inputId: string;
+  /** The `user-message` event that carries the input. */
+  eventId: string;
+  generationId: string;
+  /** Model steps the generation had completed when it took the input in. */
+  completedSteps: number;
+}
+
+export type TAgentPendingInputRejection = 'duplicate' | 'closed';
+
+/** The queue refused an input: its id was used before, or its generation has ended. */
+export class AgentPendingInputRejectedError extends Error {
+  constructor(
+    public readonly reason: TAgentPendingInputRejection,
+    public readonly inputId: string,
+  ) {
+    super(reason === 'duplicate'
+      ? `Pending input "${inputId}" was already added.`
+      : `Pending input "${inputId}" arrived after its generation stopped taking input.`);
+    this.name = 'AgentPendingInputRejectedError';
+  }
+}
+
+const assertPrompt = (content: TAgentPrompt): void => {
+  if (typeof content === 'string') {
+    if (!content.trim()) throw new Error('Pending input content must not be empty.');
+    return;
+  }
+  if (!Array.isArray(content) || content.length === 0) {
+    throw new Error('Pending input content must be a non-empty string or part list.');
+  }
+};
+
+/**
+ * The user input a generation takes in while it runs. A generation that receives the queue
+ * through `generate({ pendingInput })` drains it at every step boundary, after the tool results
+ * of its previous model step are recorded and before its next model call, and records each
+ * input as a user message of its own. A running tool call or permission wait is never
+ * interrupted: its input waits for the boundary that follows it.
+ *
+ * `close()` ends intake and returns the inputs the generation never took in: the ones still
+ * waiting, and the ones it drained but could not record durably, which it `restore()`s. An input
+ * added after it is refused with reason `closed`. The generation closes the queue when it ends,
+ * so every input is either applied or returned by `close()`. Once the generation has settled,
+ * `close()` returns the same inputs on every call; before that, a batch the generation `restore()`s
+ * after a failed save is added to what it returns.
+ */
+export class AgentPendingInputQueue {
+  /** Inputs not taken in, in arrival order. */
+  private readonly waiting: IAgentPendingInput[] = [];
+  private readonly inputIds = new Set<string>();
+  private isClosed = false;
+
+  /** True once `close()` ended intake. */
+  public get closed(): boolean {
+    return this.isClosed;
+  }
+
+  /** Inputs waiting for the next step boundary. */
+  public get size(): number {
+    return this.isClosed ? 0 : this.waiting.length;
+  }
+
+  public add(input: IAgentPendingInput): void {
+    if (typeof input.inputId !== 'string' || !input.inputId.trim()) {
+      throw new Error('Pending input id must be a non-empty string.');
+    }
+    assertPrompt(input.content);
+    if (this.inputIds.has(input.inputId)) {
+      throw new AgentPendingInputRejectedError('duplicate', input.inputId);
+    }
+    if (this.isClosed) throw new AgentPendingInputRejectedError('closed', input.inputId);
+    this.inputIds.add(input.inputId);
+    this.waiting.push({ inputId: input.inputId, content: structuredClone(input.content) });
+  }
+
+  /** Takes every waiting input in arrival order; a closed queue has none left to take. */
+  public drain(): IAgentPendingInput[] {
+    if (this.isClosed) return [];
+    return this.waiting.splice(0, this.waiting.length);
+  }
+
+  /**
+   * Gives back inputs a generation drained but could not record durably. They count as never
+   * taken in and go before the inputs that arrived after them; a closed queue returns them from
+   * `close()`, an open one hands them out again at the next `drain()`.
+   */
+  public restore(inputs: readonly IAgentPendingInput[]): void {
+    for (const input of inputs) {
+      if (!this.inputIds.has(input.inputId)) {
+        throw new Error(`Pending input "${input.inputId}" was never added to this queue.`);
+      }
+      if (this.waiting.some((waiting) => waiting.inputId === input.inputId)) {
+        throw new Error(`Pending input "${input.inputId}" is still waiting.`);
+      }
+    }
+    this.waiting.unshift(...inputs);
+  }
+
+  /** Ends intake and returns the inputs that were never taken in, in arrival order. */
+  public close(): readonly IAgentPendingInput[] {
+    this.isClosed = true;
+    return Object.freeze([...this.waiting]);
+  }
+}

package/ts_agent/smartagent.persistence.ts

@@ -392,6 +392,9 @@ const validateAgentEvents = (
           ? 'user'
           : 'assistant');
         assertProviderOptions(eventValue.providerOptions, `${eventPath}.providerOptions`);
+        if (eventValue.type === 'user-message' && eventValue.inputId !== undefined) {
+          assertNonEmptyString(eventValue.inputId, `${eventPath}.inputId`);
+        }
         break;
       case 'tool-call':
         assertNonEmptyString(eventValue.toolCallId, `${eventPath}.toolCallId`);
@@ -447,6 +450,9 @@ const validateAgentEvents = (
           && eventValue.outcome !== 'interrupted'
         ) validationError(`${eventPath}.outcome`, 'is invalid.');
         assertOptionalString(eventValue.reason, `${eventPath}.reason`);
+        if (eventValue.stopped !== undefined && (
+          eventValue.stopped !== true || eventValue.outcome !== 'interrupted'
+        )) validationError(`${eventPath}.stopped`, 'is only valid as true on an interrupted outcome.');
         break;
       case 'tool-execution-intent':
         assertRequiredGenerationId(eventValue, eventPath);

package/ts_agent/smartagent.transactions.ts

@@ -4,6 +4,7 @@ import type {
   IGenerationExecutionStartedEvent,
   IGenerationOutcomeEvent,
   IToolExecutionIntentEvent,
+  IToolResultEvent,
   TAgentControlEvent,
   TAgentEvent,
   TAgentGenerationOutcome,
@@ -138,11 +139,104 @@ export const isTransactionalGeneration = (
   generationId: string,
 ): boolean => getAgentGenerationTransactions(events).has(generationId);
 
+/** The model output that closes a tool call its stopped generation left without a result. */
+export const INTERRUPTED_TOOL_CALL_RESULT =
+  'The tool call was interrupted before its result was recorded; its effect is unknown.';
+
+const isModelOutputEvent = (event: TAgentEvent): boolean =>
+  event.type === 'assistant-message'
+  || event.type === 'tool-call'
+  || event.type === 'tool-result'
+  || event.type === 'model-message';
+
+/**
+ * Whether the events of a transactional generation are part of the model context. An accepted
+ * generation is, and so is the generation that is executing. A generation its owner stopped
+ * stays in the context once the model produced output in it: its prompt, the input it took in
+ * while it ran and what the model produced before the stop. One stopped before any model output
+ * left no trace in the conversation and is not shown, so its prompt can be sent again. Rejected
+ * generations, and generations interrupted by an abort, a failure or a restart, are not shown.
+ */
+const isModelVisibleTransaction = (
+  transaction: IAgentGenerationTransaction,
+  producedOutput: ReadonlySet<string>,
+): boolean =>
+  transaction.state === 'accepted'
+  || transaction.state === 'execution-started'
+  || (
+    transaction.state === 'interrupted'
+    && transaction.outcome?.stopped === true
+    && transaction.executionStarted !== undefined
+    && producedOutput.has(transaction.generationId)
+  );
+
+/** The generations whose model produced output in `events`. */
+const generationsWithModelOutput = (events: readonly TAgentEvent[]): Set<string> => {
+  const producedOutput = new Set<string>();
+  for (const event of events) {
+    if (event.generationId && isModelOutputEvent(event)) producedOutput.add(event.generationId);
+  }
+  return producedOutput;
+};
+
+/**
+ * Whether the transactional generation `generationId` is part of the model context of later
+ * generations, by the rule `filterModelVisibleAgentEvents` applies: it was accepted, is
+ * executing, or was stopped by its owner after its model produced output. False for a
+ * generation `events` holds no transaction of.
+ */
+export const isGenerationInModelContext = (
+  events: readonly TAgentEvent[],
+  generationId: string,
+): boolean => {
+  const transaction = getAgentGenerationTransactions(events).get(generationId);
+  return transaction !== undefined
+    && isModelVisibleTransaction(transaction, generationsWithModelOutput(events));
+};
+
+const interruptedToolResult = (
+  toolCallId: string,
+  toolName: string,
+  source: TAgentEvent,
+): IToolResultEvent => ({
+  id: `${source.id}:interrupted:${toolCallId}`,
+  timestamp: source.timestamp,
+  type: 'tool-result',
+  toolCallId,
+  toolName,
+  error: INTERRUPTED_TOOL_CALL_RESULT,
+  modelOutput: { type: 'error-text', value: INTERRUPTED_TOOL_CALL_RESULT },
+  generationId: source.generationId,
+  inferenceId: source.inferenceId,
+  causationId: source.causationId,
+  parentIds: [source.id],
+});
+
 export const filterModelVisibleAgentEvents = (
   events: readonly TAgentEvent[],
 ): TAgentEvent[] => {
   const transactions = getAgentGenerationTransactions(events);
+  const producedOutput = generationsWithModelOutput(events);
+  const resultedToolCalls = new Set<string>();
+  for (const event of events) {
+    if (!event.generationId) continue;
+    if (event.type === 'tool-result') resultedToolCalls.add(`${event.generationId}\0${event.toolCallId}`);
+    if (event.type === 'assistant-message' && Array.isArray(event.content)) {
+      for (const part of event.content) {
+        if (part.type === 'tool-result') {
+          resultedToolCalls.add(`${event.generationId}\0${part.toolCallId}`);
+        }
+      }
+    }
+  }
   const visibleEvents: TAgentEvent[] = [];
+  /** Closes each tool call a stopped generation left open, right after the call. */
+  const closeOpenToolCall = (toolCallId: string, toolName: string, source: TAgentEvent): void => {
+    const key = `${source.generationId}\0${toolCallId}`;
+    if (resultedToolCalls.has(key)) return;
+    resultedToolCalls.add(key);
+    visibleEvents.push(interruptedToolResult(toolCallId, toolName, source));
+  };
   for (const event of events) {
     if (isControlEvent(event)) continue;
     if (event.type === 'context-compaction' && event.archivedTransactions) {
@@ -154,11 +248,18 @@ export const filterModelVisibleAgentEvents = (
       continue;
     }
     const transaction = transactions.get(event.generationId);
-    if (
-      !transaction
-      || transaction.state === 'accepted'
-      || transaction.state === 'execution-started'
-    ) visibleEvents.push(event);
+    if (transaction && !isModelVisibleTransaction(transaction, producedOutput)) continue;
+    visibleEvents.push(event);
+    if (transaction?.state !== 'interrupted') continue;
+    if (event.type === 'tool-call' && event.providerExecuted !== true) {
+      closeOpenToolCall(event.toolCallId, event.toolName, event);
+    } else if (event.type === 'assistant-message' && Array.isArray(event.content)) {
+      for (const part of event.content) {
+        if (part.type === 'tool-call' && part.providerExecuted !== true) {
+          closeOpenToolCall(part.toolCallId, part.toolName, event);
+        }
+      }
+    }
   }
   return visibleEvents;
 };