tinker-agent 2.12.0 → 3.0.0

package/src/client/model-catalog.ts

@@ -0,0 +1,15 @@
+import type { ModelProfile } from "../cli/model-profiles";
+
+/** Display data only. Provider endpoints and credentials never cross the client boundary. */
+export type ClientModelProfile = Pick<
+  ModelProfile,
+  "name" | "model" | "contextWindowTokens" | "maxSupportedOutputTokens"
+>;
+export type ClientModelCatalog = {
+  defaultProfile: string;
+  profiles: readonly ClientModelProfile[];
+};
+export type ClientModelProfiles = {
+  defaultProfile: string;
+  profiles: ReadonlyMap<string, ClientModelProfile>;
+};

package/src/client/remote-images.ts

@@ -0,0 +1,80 @@
+import { constants } from "node:fs";
+import { lstat, open } from "node:fs/promises";
+import path from "node:path";
+import { IMAGE_INPUT_POLICY } from "../image/image-input-policy";
+import { probeImageBytes } from "../image/image-probe";
+import type { ImportedImageAsset } from "../image/image-asset-store";
+import type { ImageAssetRef } from "../image/image-types";
+import type { RemoteClient } from "../remote/client";
+
+/** Relative @-mentions name service workspace files; absolute paths name client files. */
+export class RemoteImages {
+  constructor(
+    private readonly transport: RemoteClient,
+    private readonly sessionId: string,
+    private readonly lifetime: AbortSignal,
+  ) {}
+  async import(
+    sourcePath: string,
+    signal: AbortSignal,
+    count: number,
+  ): Promise<ImportedImageAsset> {
+    const combined = AbortSignal.any([signal, this.lifetime]);
+    combined.throwIfAborted();
+    if (!path.isAbsolute(sourcePath))
+      return this.transport.request(
+        `/v1/sessions/${this.sessionId}/images`,
+        { sourcePath, count },
+        combined,
+      );
+    const stat = await lstat(sourcePath);
+    if (
+      !stat.isFile() ||
+      stat.isSymbolicLink() ||
+      stat.size < 1 ||
+      stat.size > IMAGE_INPUT_POLICY.maxBytesPerImage
+    )
+      throw new Error(
+        "Image must be a regular non-symlink file within the image size limit.",
+      );
+    const file = await open(sourcePath, constants.O_RDONLY | constants.O_NOFOLLOW);
+    let bytes: Buffer;
+    try {
+      const opened = await file.stat();
+      if (opened.dev !== stat.dev || opened.ino !== stat.ino || !opened.isFile())
+        throw new Error("Image file changed while opening.");
+      // A bounded read also protects against a file growing after stat().
+      bytes = Buffer.alloc(IMAGE_INPUT_POLICY.maxBytesPerImage + 1);
+      let used = 0;
+      while (used < bytes.length) {
+        combined.throwIfAborted();
+        const read = await file.read(bytes, used, bytes.length - used, used);
+        if (read.bytesRead === 0) break;
+        used += read.bytesRead;
+      }
+      bytes = bytes.subarray(0, used);
+    } finally {
+      await file.close();
+    }
+    await probeImageBytes(bytes, {
+      fullDecode: true,
+      sourceName: path.basename(sourcePath),
+    });
+    return this.transport.request(
+      `/v1/sessions/${this.sessionId}/images`,
+      {
+        bytes: bytes.toString("base64"),
+        originalName: path.basename(sourcePath),
+        count,
+      },
+      combined,
+    );
+  }
+  async verify(assets: readonly ImageAssetRef[], signal: AbortSignal): Promise<void> {
+    await this.transport.request(
+      `/v1/sessions/${this.sessionId}/verify-images`,
+      { assets },
+      AbortSignal.any([signal, this.lifetime]),
+    );
+  }
+}

package/src/client/remote-prompt-history.ts

@@ -0,0 +1,22 @@
+import { PromptHistory, type LoadedPromptHistoryRecord } from "../tui/prompt-history";
+import type { PromptDraft } from "../tui/prompt-draft";
+
+/** Draft navigation stays synchronous; persistence belongs to the service workspace. */
+export class RemotePromptHistory extends PromptHistory {
+  private pending: Promise<void> = Promise.resolve();
+  constructor(
+    records: LoadedPromptHistoryRecord[],
+    private readonly persist: (prompt: string | PromptDraft) => Promise<void>,
+  ) {
+    super({ records });
+  }
+  override async append(prompt: string | PromptDraft): Promise<void> {
+    await super.append(prompt);
+    const next = this.pending.catch(() => undefined).then(() => this.persist(prompt));
+    this.pending = next;
+    await next;
+  }
+  async flush(): Promise<void> {
+    await this.pending.catch(() => undefined);
+  }
+}

package/src/client/remote-tasks.ts

@@ -0,0 +1,231 @@
+import { decodeFailure } from "../remote/failures";
+import type {
+  SessionOperation,
+  SessionOperationResult,
+} from "../remote/session-operations";
+import { TurnCancelledError } from "../agent/turn-cancellation";
+import { randomUUID } from "node:crypto";
+import { ClientHttpError, type RemoteClient } from "../remote/client";
+import {
+  isTerminal,
+  type OperationReceipt,
+  type RemoteOperationInput,
+} from "../remote/protocol";
+import type { RemoteTuiSnapshot } from "../remote/tui-protocol";
+import type {
+  AcceptedTurn,
+  QueueFollowUpResult,
+} from "../agent/runtime-session-contracts";
+import type { RunAgentResult, UserMessage } from "../agent/types";
+import type { TurnId } from "../ids/runtime-id";
+import { validateUserMessage } from "../image/image-types";
+
+/** Commands retain their UUID across uncertain HTTP responses. Detach only stops observation. */
+export class RemoteTasks {
+  constructor(
+    private readonly transport: RemoteClient,
+    private readonly sessionId: string,
+    private readonly snapshot: () => RemoteTuiSnapshot,
+    private readonly lifetime: AbortSignal,
+    private readonly reportError: (message: string) => void,
+  ) {}
+
+  async admitTurn(
+    userMessage: UserMessage,
+    signal: AbortSignal,
+  ): Promise<AcceptedTurn> {
+    validateUserMessage(userMessage);
+    signal.throwIfAborted();
+    const requestId = randomUUID();
+    const stop = () => {
+      if (
+        signal.reason instanceof TurnCancelledError &&
+        signal.reason.source === "session_dispose"
+      )
+        return;
+      if (!this.lifetime.aborted)
+        void this.stop(requestId).catch((error: unknown) => {
+          if (!this.lifetime.aborted)
+            this.reportError(`Stop failed: ${message(error)}`);
+        });
+    };
+    // Wait for acceptance before sending stop; a lost response is retried with the same ID.
+    let receipt = await this.submit({
+      kind: "prompt",
+      requestId,
+      sessionId: this.sessionId,
+      prompt: userMessage.content,
+      ...(userMessage.attachments ? { attachments: userMessage.attachments } : {}),
+    });
+    signal.addEventListener("abort", stop, { once: true });
+    if (signal.aborted) stop();
+    try {
+      while (!receipt.turnId && !isTerminal(receipt.status)) {
+        await pause(100, this.lifetime);
+        receipt = await this.read(requestId);
+      }
+      if (!receipt.turnId && receipt.failure) throw decodeFailure(receipt.failure);
+      if (!receipt.turnId)
+        throw new Error(
+          receipt.error ?? `Task ${receipt.status} before turn admission.`,
+        );
+      const completion = this.complete(receipt).finally(() =>
+        signal.removeEventListener("abort", stop),
+      );
+      return { turnId: receipt.turnId as TurnId, userMessage, completion };
+    } catch (error) {
+      signal.removeEventListener("abort", stop);
+      throw error;
+    }
+  }
+
+  async queueFollowUp(userMessage: UserMessage): Promise<QueueFollowUpResult> {
+    plainText(userMessage);
+    const targetRequestId = this.snapshot().activity.activeRequestId;
+    if (!targetRequestId) throw new Error("No execution is running in this session.");
+    const receipt = await this.settled(
+      await this.submit({
+        kind: "follow_up",
+        requestId: randomUUID(),
+        sessionId: this.sessionId,
+        targetRequestId,
+        prompt: userMessage.content,
+      }),
+    );
+    if (receipt.status !== "completed" || !receipt.followUp)
+      throw new Error(receipt.error ?? `Follow-up ${receipt.status}.`);
+    return receipt.followUp;
+  }
+
+  async deleteSession(targetSessionId: string): Promise<void> {
+    const receipt = await this.settled(
+      await this.submit({
+        kind: "delete_session",
+        sessionId: this.sessionId,
+        targetSessionId,
+        requestId: randomUUID(),
+      }),
+    );
+    if (receipt.status !== "completed")
+      throw new Error(receipt.error ?? `Session deletion ${receipt.status}.`);
+  }
+
+  async operate(
+    input: Omit<SessionOperation, "sessionId"> & Record<string, unknown>,
+  ): Promise<SessionOperationResult> {
+    const receipt = await this.settled(
+      await this.submit({
+        ...input,
+        sessionId: this.sessionId,
+        requestId: randomUUID(),
+      } as RemoteOperationInput),
+    );
+    if (receipt.failure) throw decodeFailure(receipt.failure);
+    if (receipt.status !== "completed" || !receipt.sessionResult)
+      throw new Error(receipt.error ?? `Session operation ${receipt.status}.`);
+    return receipt.sessionResult;
+  }
+
+  async respond(
+    input:
+      | { kind: "answer"; interactionId: string; selectedIndex: number | null }
+      | { kind: "confirm"; interactionId: string; decision: "allow" | "deny" }
+      | { kind: "provider_retry"; interactionId: string; decision: "retry" | "stop" },
+  ): Promise<void> {
+    const receipt = await this.settled(
+      await this.submit({
+        ...input,
+        requestId: randomUUID(),
+        sessionId: this.sessionId,
+      }),
+    );
+    if (receipt.status !== "completed")
+      throw new Error(receipt.error ?? `Interaction ${receipt.status}.`);
+  }
+
+  async stopTurn(): Promise<void> {
+    const target = this.snapshot().activity.activeRequestId;
+    if (!target) throw new Error("No execution is running in this session.");
+    await this.stop(target);
+  }
+  private async stop(targetRequestId: string): Promise<void> {
+    const receipt = await this.settled(
+      await this.submit({
+        kind: "stop",
+        requestId: randomUUID(),
+        sessionId: this.sessionId,
+        targetRequestId,
+      }),
+    );
+    if (receipt.status !== "completed")
+      throw new Error(receipt.error ?? `Stop ${receipt.status}.`);
+    await this.settled(await this.read(targetRequestId));
+  }
+  private async complete(initial: OperationReceipt): Promise<RunAgentResult> {
+    const receipt = await this.settled(initial);
+    if (receipt.result) return receipt.result;
+    throw new Error(
+      receipt.error ?? `Task ${receipt.status}; its execution result is unavailable.`,
+    );
+  }
+  private async settled(initial: OperationReceipt): Promise<OperationReceipt> {
+    let receipt = initial;
+    while (!isTerminal(receipt.status)) {
+      await pause(100, this.lifetime);
+      receipt = await this.read(receipt.requestId);
+    }
+    return receipt;
+  }
+  private submit(input: RemoteOperationInput): Promise<OperationReceipt> {
+    return this.retry(() =>
+      this.transport.request("/v1/operations", input, this.lifetime),
+    );
+  }
+  private read(id: string): Promise<OperationReceipt> {
+    return this.retry(() =>
+      this.transport.request(`/v1/operations/${id}`, undefined, this.lifetime),
+    );
+  }
+  private async retry<T>(request: () => Promise<T>): Promise<T> {
+    for (;;) {
+      this.lifetime.throwIfAborted();
+      try {
+        return await request();
+      } catch (error) {
+        this.lifetime.throwIfAborted();
+        if (
+          error instanceof ClientHttpError &&
+          error.status < 500 &&
+          error.status !== 429
+        )
+          throw error;
+        this.reportError(`Waiting for service: ${message(error)}`);
+        await pause(500, this.lifetime);
+      }
+    }
+  }
+}
+function plainText(userMessage: UserMessage): void {
+  validateUserMessage(userMessage);
+  if (userMessage.attachments !== undefined)
+    throw new Error("Service TUI image input is not enabled yet.");
+}
+function message(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+function pause(ms: number, signal: AbortSignal): Promise<void> {
+  signal.throwIfAborted();
+  return new Promise((resolve, reject) => {
+    const abort = () => {
+      clearTimeout(timer);
+      reject(
+        signal.reason instanceof Error ? signal.reason : new Error("Client closed."),
+      );
+    };
+    const timer = setTimeout(() => {
+      signal.removeEventListener("abort", abort);
+      resolve();
+    }, ms);
+    signal.addEventListener("abort", abort, { once: true });
+  });
+}

package/src/client/remote-tui-view.ts

@@ -0,0 +1,69 @@
+import { type TuiProjectionState } from "../tui/event-store";
+import type { TuiTimelineLog } from "../tui/tui-projection-store";
+import type { RemoteTuiSnapshot } from "../remote/tui-protocol";
+
+/** Retains printed history across refreshes; service status is separate from the timeline. */
+export class RemoteTuiView {
+  private readonly listeners = new Set<() => void>();
+  private readonly printed = new Set<string>();
+  private state: TuiProjectionState;
+  private log: TuiTimelineLog = { committed: [], live: [] };
+  private connection = "connecting";
+  private error?: string;
+  private activity = "idle";
+  private epoch?: string;
+  private live: TuiTimelineLog["live"] = [];
+
+  constructor(snapshot: RemoteTuiSnapshot) {
+    this.state = snapshot.history;
+    this.update(snapshot);
+  }
+  readonly getServiceStatus = () => ({
+    connection: this.connection,
+    activity: this.activity,
+    error: this.error,
+  });
+  readonly getPresentationRevision = () => this.epoch;
+  readonly getSnapshot = () => this.state;
+  readonly getLogSnapshot = () => this.log;
+  readonly subscribe = (listener: () => void) => {
+    this.listeners.add(listener);
+    return () => {
+      this.listeners.delete(listener);
+    };
+  };
+  update(snapshot: RemoteTuiSnapshot): void {
+    // Runtime-generated row IDs are not stable across a service restart. Replace
+    // the old projection with canonical recovery and request a terminal redraw.
+    if (this.epoch !== snapshot.cursor.epoch) {
+      this.epoch = snapshot.cursor.epoch;
+      this.printed.clear();
+      this.log = { committed: [], live: [] };
+    }
+    this.error = undefined;
+    this.activity = snapshot.activity.status;
+    this.state = {
+      ...snapshot.history,
+      ...(snapshot.activity.activeRequestId ? { status: "running" as const } : {}),
+    };
+    this.live = snapshot.timeline.live;
+    const added = snapshot.timeline.committed.filter(
+      (item) => !this.printed.has(item.id),
+    );
+    for (const item of added) this.printed.add(item.id);
+    this.log = { committed: [...this.log.committed, ...added], live: [] };
+    this.refresh();
+  }
+  setConnection(connection: string, error?: string): void {
+    this.connection = connection;
+    this.error = error;
+    this.refresh();
+  }
+  private refresh(): void {
+    this.log = {
+      ...this.log,
+      live: this.live,
+    };
+    for (const listener of this.listeners) listener();
+  }
+}