tinker-agent 2.8.0 → 2.10.0

package/src/agent/runtime-interactions.ts

@@ -0,0 +1,291 @@
+import type { AgentEventInput } from "../events/types";
+import { type AskUserRequest, type AskUserResponse } from "../tools/types";
+import {
+  type AskUserResolution,
+  type AskUserSnapshot,
+  type BashGuardSnapshot,
+  type BashGuardSource,
+  type CreateRuntimeSessionInput,
+} from "./runtime-session-contracts";
+import { cancellationError } from "./turn-cancellation";
+import type { ToolCallIdentity } from "./types";
+
+export class RuntimeInteractions {
+  private bashGuardMode: "guard" | "yolo";
+  private bashGuardSource: BashGuardSource;
+  private bashGuardSnapshot: BashGuardSnapshot;
+  private readonly bashGuardListeners = new Set<() => void>();
+  private askUserSnapshot: AskUserSnapshot = Object.freeze({});
+  private readonly askUserListeners = new Set<() => void>();
+  private pendingAskUser?: {
+    readonly request: AskUserRequest;
+    readonly startedAt: number;
+    readonly call: ToolCallIdentity;
+    readonly resolve: (response: AskUserResponse) => void;
+    readonly reject: (error: unknown) => void;
+    readonly removeAbortListener: () => void;
+  };
+
+  private pendingBashConfirmation?: {
+    readonly command: string;
+    readonly reason: string;
+    readonly startedAt: number;
+    readonly call: ToolCallIdentity;
+    readonly resolve: (decision: "allow" | "deny") => void;
+    readonly reject: (error: unknown) => void;
+    readonly removeAbortListener: () => void;
+  };
+
+  constructor(
+    private readonly bashGuardConfig: CreateRuntimeSessionInput["bashGuard"],
+    private readonly append: (event: AgentEventInput) => Promise<void>,
+  ) {
+    this.bashGuardMode = bashGuardConfig?.mode ?? "guard";
+    this.bashGuardSource = bashGuardConfig?.source ?? "default";
+    this.bashGuardSnapshot = Object.freeze({
+      mode: this.bashGuardMode,
+      source: this.bashGuardSource,
+    });
+  }
+
+  bashGuard(): BashGuardSnapshot {
+    return this.bashGuardSnapshot;
+  }
+
+  private refreshBashGuardSnapshot(): void {
+    this.bashGuardSnapshot = Object.freeze({
+      mode: this.bashGuardMode,
+      source: this.bashGuardSource,
+      ...(this.pendingBashConfirmation === undefined
+        ? {}
+        : {
+            pending: Object.freeze({
+              command: this.pendingBashConfirmation.command,
+              reason: this.pendingBashConfirmation.reason,
+            }),
+          }),
+    });
+  }
+
+  subscribeBashGuard(listener: () => void): () => void {
+    this.bashGuardListeners.add(listener);
+    return () => this.bashGuardListeners.delete(listener);
+  }
+
+  setYoloMode(enabled: boolean): void {
+    this.bashGuardMode = enabled ? "yolo" : "guard";
+    this.bashGuardSource = "session";
+    this.refreshBashGuardSnapshot();
+    this.notifyBashGuardListeners();
+  }
+
+  async resolveBashConfirmation(decision: "allow" | "deny"): Promise<void> {
+    const pending = this.pendingBashConfirmation;
+    if (pending === undefined) {
+      throw new Error("No Bash confirmation is pending.");
+    }
+    this.pendingBashConfirmation = undefined;
+    this.refreshBashGuardSnapshot();
+    pending.removeAbortListener();
+    await this.append({
+      type: "tool.confirmation.resolved",
+      ...pending.call,
+      data: {
+        command: pending.command,
+        reason: pending.reason,
+        decision,
+        durationMs: Date.now() - pending.startedAt,
+      },
+    });
+    pending.resolve(decision);
+    this.notifyBashGuardListeners();
+  }
+
+  async confirmBashCommand(
+    call: ToolCallIdentity,
+    request: { command: string; reason: string },
+    signal: AbortSignal,
+  ): Promise<"allow" | "deny"> {
+    const startedAt = Date.now();
+    await this.append({
+      type: "tool.confirmation.requested",
+      ...call,
+      data: request,
+    });
+
+    const surface = this.bashGuardConfig?.surface ?? "one-shot";
+    if (this.bashGuardMode === "yolo" || surface === "one-shot") {
+      const decision = this.bashGuardMode === "yolo" ? "allow" : "deny";
+      await this.append({
+        type: "tool.confirmation.resolved",
+        ...call,
+        data: {
+          ...request,
+          decision,
+          durationMs: Date.now() - startedAt,
+        },
+      });
+      return decision;
+    }
+
+    if (this.pendingBashConfirmation !== undefined) {
+      throw new Error("Another Bash confirmation is already pending.");
+    }
+
+    return new Promise<"allow" | "deny">((resolve, reject) => {
+      const onAbort = () => {
+        const pending = this.pendingBashConfirmation;
+        if (pending?.call.toolCallId !== call.toolCallId) {
+          return;
+        }
+        this.pendingBashConfirmation = undefined;
+        this.refreshBashGuardSnapshot();
+        void this.append({
+          type: "tool.confirmation.resolved",
+          ...call,
+          data: {
+            ...request,
+            decision: "cancelled",
+            durationMs: Date.now() - startedAt,
+          },
+        }).finally(() => {
+          reject(cancellationError(signal));
+          this.notifyBashGuardListeners();
+        });
+      };
+      signal.addEventListener("abort", onAbort, { once: true });
+      this.pendingBashConfirmation = {
+        ...request,
+        startedAt,
+        call,
+        resolve,
+        reject,
+        removeAbortListener: () => signal.removeEventListener("abort", onAbort),
+      };
+      this.refreshBashGuardSnapshot();
+      this.notifyBashGuardListeners();
+      if (signal.aborted) {
+        onAbort();
+      }
+    });
+  }
+
+  private notifyBashGuardListeners(): void {
+    for (const listener of this.bashGuardListeners) {
+      listener();
+    }
+  }
+
+  askUser(): AskUserSnapshot {
+    return this.askUserSnapshot;
+  }
+
+  subscribeAskUser(listener: () => void): () => void {
+    this.askUserListeners.add(listener);
+    return () => this.askUserListeners.delete(listener);
+  }
+
+  async resolveAskUser(response: AskUserResolution): Promise<void> {
+    const pending = this.pendingAskUser;
+    if (pending === undefined) {
+      throw new Error("No AskUser question is pending.");
+    }
+    let result: AskUserResponse;
+    if (response.outcome === "selected") {
+      if (!Number.isSafeInteger(response.selectedIndex)) {
+        throw new Error("AskUser selectedIndex must be an integer.");
+      }
+      const option = pending.request.options[response.selectedIndex];
+      if (option === undefined) {
+        throw new Error("AskUser selectedIndex is out of range.");
+      }
+      result = { outcome: "selected", answer: option.description };
+    } else {
+      result = { outcome: "dismissed" };
+    }
+    this.pendingAskUser = undefined;
+    this.askUserSnapshot = Object.freeze({});
+    pending.removeAbortListener();
+    await this.append({
+      type: "tool.user_question.resolved",
+      ...pending.call,
+      data: {
+        ...result,
+        durationMs: Date.now() - pending.startedAt,
+      },
+    });
+    pending.resolve(result);
+    this.notifyAskUserListeners();
+  }
+
+  async requestUserAnswer(
+    call: ToolCallIdentity,
+    request: AskUserRequest,
+    signal: AbortSignal,
+  ): Promise<AskUserResponse> {
+    if (this.pendingAskUser !== undefined) {
+      throw new Error("Another AskUser question is already pending.");
+    }
+    if (this.pendingBashConfirmation !== undefined) {
+      throw new Error("Cannot ask the user while a Bash confirmation is pending.");
+    }
+    if (signal.aborted) {
+      throw cancellationError(signal);
+    }
+    const startedAt = Date.now();
+    await this.append({
+      type: "tool.user_question.requested",
+      ...call,
+      data: request,
+    });
+    return new Promise<AskUserResponse>((resolve, reject) => {
+      const onAbort = () => {
+        const pending = this.pendingAskUser;
+        if (pending?.call.toolCallId !== call.toolCallId) {
+          return;
+        }
+        this.pendingAskUser = undefined;
+        this.askUserSnapshot = Object.freeze({});
+        void this.append({
+          type: "tool.user_question.resolved",
+          ...call,
+          data: {
+            outcome: "cancelled",
+            durationMs: Date.now() - startedAt,
+          },
+        }).finally(() => {
+          reject(cancellationError(signal));
+          this.notifyAskUserListeners();
+        });
+      };
+      signal.addEventListener("abort", onAbort, { once: true });
+      const immutableRequest = Object.freeze({
+        question: request.question,
+        options: Object.freeze(
+          request.options.map((option) =>
+            Object.freeze({ description: option.description }),
+          ),
+        ),
+      });
+      this.pendingAskUser = {
+        request: immutableRequest,
+        startedAt,
+        call,
+        resolve,
+        reject,
+        removeAbortListener: () => signal.removeEventListener("abort", onAbort),
+      };
+      this.askUserSnapshot = Object.freeze({ pending: immutableRequest });
+      this.notifyAskUserListeners();
+      if (signal.aborted) {
+        onAbort();
+      }
+    });
+  }
+
+  private notifyAskUserListeners(): void {
+    for (const listener of this.askUserListeners) {
+      listener();
+    }
+  }
+}

package/src/agent/runtime-prompt-scheduler.ts

@@ -0,0 +1,182 @@
+import type { AgentEventInput } from "../events/types";
+import { validateUserMessage, type UserMessage } from "../image/image-types";
+import {
+  type AcceptedTurn,
+  type ExecuteTurnInput,
+  type PromptSchedulerSnapshot,
+  type QueueFollowUpResult,
+  type RuntimeSessionState,
+} from "./runtime-session-contracts";
+import { type AgentTurnLedger } from "./session-ledger";
+import type { RunAgentResult, TurnIdentity } from "./types";
+import { projectUserMessage } from "./user-prompt-projection";
+
+type QueuedPrompt = {
+  readonly userMessage: UserMessage;
+};
+const MAX_QUEUED_PROMPTS = 8;
+const MAX_QUEUED_PROMPT_TEXT_BYTES = 64 * 1024;
+/** Owns queued prompts and their execution chain; admission stays in the runtime. */
+export class RuntimePromptScheduler {
+  private executionChainRunning = false;
+  private readonly queuedPrompts: QueuedPrompt[] = [];
+  private promptSchedulerSnapshot: PromptSchedulerSnapshot = Object.freeze({
+    state: "idle",
+    pendingCount: 0,
+  });
+  private readonly promptSchedulerListeners = new Set<() => void>();
+  constructor(
+    private readonly getState: () => RuntimeSessionState,
+    private readonly getActiveTurn: () => { turn: TurnIdentity } | undefined,
+    private readonly admitSingleTurn: (
+      input: ExecuteTurnInput,
+    ) => Promise<AcceptedTurn>,
+    private readonly append: (event: AgentEventInput) => Promise<void>,
+  ) {}
+
+  get isRunning(): boolean {
+    return this.executionChainRunning;
+  }
+
+  get pendingCount(): number {
+    return this.queuedPrompts.length;
+  }
+
+  clear(): void {
+    this.queuedPrompts.splice(0);
+    this.executionChainRunning = false;
+    this.notifyPromptScheduler();
+  }
+
+  promptScheduler(): PromptSchedulerSnapshot {
+    return this.promptSchedulerSnapshot;
+  }
+
+  subscribePromptScheduler(listener: () => void): () => void {
+    this.promptSchedulerListeners.add(listener);
+    return () => this.promptSchedulerListeners.delete(listener);
+  }
+
+  queueFollowUp(userMessage: UserMessage): QueueFollowUpResult {
+    if (!this.executionChainRunning) {
+      throw new Error("Cannot queue a follow-up while no execution chain is running.");
+    }
+    validateUserMessage(userMessage);
+    if (userMessage.attachments !== undefined) {
+      throw new Error("Active-turn follow-ups do not support image attachments.");
+    }
+    if (this.queuedPrompts.length >= MAX_QUEUED_PROMPTS) {
+      throw new Error(`At most ${MAX_QUEUED_PROMPTS} follow-ups may be queued.`);
+    }
+    const queuedBytes = this.queuedPrompts.reduce(
+      (total, entry) => total + Buffer.byteLength(entry.userMessage.content, "utf8"),
+      0,
+    );
+    const nextBytes = Buffer.byteLength(userMessage.content, "utf8");
+    if (queuedBytes + nextBytes > MAX_QUEUED_PROMPT_TEXT_BYTES) {
+      throw new Error("Queued follow-ups exceed the 64 KiB text limit.");
+    }
+    this.queuedPrompts.push({
+      userMessage: Object.freeze({ ...userMessage }),
+    });
+    this.notifyPromptScheduler();
+    const activeTurn = this.getActiveTurn();
+    return Object.freeze({
+      kind: "queued",
+      pendingCount: this.queuedPrompts.length,
+      ...(activeTurn === undefined ? {} : { activeTurnId: activeTurn.turn.turnId }),
+    });
+  }
+
+  async admitTurn(input: ExecuteTurnInput): Promise<AcceptedTurn> {
+    if (this.executionChainRunning) {
+      throw new Error(
+        `Cannot execute a turn while RuntimeSession is ${this.getState()}; a prompt chain is already executing.`,
+      );
+    }
+    this.executionChainRunning = true;
+    this.notifyPromptScheduler();
+    try {
+      const accepted = await this.admitSingleTurn(input);
+      const completion = this.continueExecutionChain(accepted.completion, input.signal);
+      return Object.freeze({ ...accepted, completion });
+    } catch (error) {
+      this.executionChainRunning = false;
+      this.notifyPromptScheduler();
+      throw error;
+    }
+  }
+
+  private async continueExecutionChain(
+    initialCompletion: Promise<RunAgentResult>,
+    signal: AbortSignal,
+  ): Promise<RunAgentResult> {
+    let completion = initialCompletion;
+    let finalResult: RunAgentResult;
+    try {
+      for (;;) {
+        finalResult = await completion;
+        if (finalResult.status !== "completed" || this.queuedPrompts.length === 0) {
+          return finalResult;
+        }
+        const next = this.queuedPrompts[0];
+        if (next === undefined) {
+          return finalResult;
+        }
+        const accepted = await this.admitSingleTurn({
+          userMessage: next.userMessage,
+          signal,
+        });
+        this.queuedPrompts.shift();
+        this.notifyPromptScheduler();
+        completion = accepted.completion;
+      }
+    } finally {
+      this.queuedPrompts.splice(0);
+      this.executionChainRunning = false;
+      this.notifyPromptScheduler();
+    }
+  }
+
+  notifyPromptScheduler(): void {
+    const activeTurn = this.getActiveTurn();
+    this.promptSchedulerSnapshot = Object.freeze({
+      state: this.executionChainRunning ? "running" : "idle",
+      ...(activeTurn === undefined ? {} : { activeTurnId: activeTurn.turn.turnId }),
+      pendingCount: this.queuedPrompts.length,
+    });
+    for (const listener of this.promptSchedulerListeners) listener();
+  }
+
+  async applyQueuedSteering(input: {
+    turn: TurnIdentity;
+    ledger: AgentTurnLedger;
+  }): Promise<number> {
+    const activeTurn = this.getActiveTurn();
+    if (activeTurn?.turn.turnId !== input.turn.turnId) {
+      throw new Error("Cannot apply steering outside the active turn.");
+    }
+    if (this.queuedPrompts.length === 0) return 0;
+    const drained = this.queuedPrompts.splice(0);
+    const records = input.ledger.appendSteeringUserMessages(
+      drained.map((entry) => entry.userMessage),
+    );
+    this.notifyPromptScheduler();
+    for (let index = 0; index < records.length; index += 1) {
+      const record = records[index];
+      const queued = drained[index];
+      if (record === undefined || queued === undefined) {
+        throw new Error("Steering ledger result did not match the drained queue.");
+      }
+      await this.append({
+        type: "turn.steering.applied",
+        ...input.turn,
+        data: {
+          userPrompt: projectUserMessage(queued.userMessage),
+          ordinal: record.ordinal,
+        },
+      });
+    }
+    return records.length;
+  }
+}