tinker-agent 2.9.0 → 2.10.0

package/src/remote/client.ts

@@ -0,0 +1,350 @@
+import { readFile, chmod, writeFile, rename, mkdir } from "node:fs/promises";
+import path from "node:path";
+import { randomUUID } from "node:crypto";
+import type { WebSocketOptions } from "bun";
+import type {
+  RemoteHistoryPage,
+  RemoteMessage,
+} from "../session/remote-history-reader";
+import {
+  requireObject,
+  requireText,
+  type RemoteOperationInput,
+  type RemoteView,
+  type RemoteFrame,
+  type OperationReceipt,
+  type RemoteSessionInfo,
+} from "./protocol";
+
+export type RemoteClientConfig = {
+  url: string;
+  token: string;
+  ca?: string;
+  statePath: string;
+};
+export async function loadRemoteClientConfig(
+  filename: string,
+): Promise<RemoteClientConfig> {
+  const raw = requireObject(JSON.parse(await readFile(filename, "utf8")));
+  const url = new URL(requireText(raw.url, "url", 4096));
+  if (
+    url.protocol !== "https:" ||
+    url.username ||
+    url.password ||
+    url.search ||
+    url.hash ||
+    url.pathname !== "/"
+  )
+    throw new Error("Pairing URL must be an HTTPS origin.");
+  const token = requireText(raw.token, "token", 128);
+  if (!/^[A-Za-z0-9_-]{43,128}$/.test(token))
+    throw new Error("Pairing token is invalid.");
+  const ca =
+    raw.caFile === undefined
+      ? undefined
+      : await readFile(
+          path.resolve(path.dirname(filename), requireText(raw.caFile, "caFile", 4096)),
+          "utf8",
+        );
+  return { url: url.origin, token, ca, statePath: `${filename}.state.json` };
+}
+
+type ClientState = {
+  sessionId?: string;
+  workspaceId?: string;
+  outbox: RemoteOperationInput[];
+  failures: { requestId: string; message: string }[];
+};
+export type ClientSnapshot = {
+  connection: "connecting" | "online" | "offline" | "closed";
+  view?: RemoteView;
+  pending: number;
+  error?: string;
+};
+
+export function mergeRemoteMessages(
+  before: readonly RemoteMessage[],
+  after: readonly RemoteMessage[],
+): RemoteMessage[] {
+  const all = new Map(before.map((message) => [message.id, message]));
+  for (const message of after) all.set(message.id, message);
+  return [...all.values()].sort((a, b) => a.ordinal - b.ordinal);
+}
+
+export function applyRemoteFrame(
+  current: RemoteFrame | undefined,
+  frame: RemoteFrame,
+): RemoteFrame {
+  if (frame.version !== 1) throw new Error("Unsupported remote protocol version.");
+  if (frame.type === "snapshot") return frame;
+  if (!current || current.type !== "snapshot" || frame.epoch !== current.epoch)
+    throw new Error("A full snapshot is required.");
+  if (frame.sequence <= current.sequence) return current;
+  if (frame.sequence !== current.sequence + 1)
+    throw new Error("Missing event; a full snapshot is required.");
+  return {
+    version: 1,
+    type: "snapshot",
+    epoch: frame.epoch,
+    sequence: frame.sequence,
+    view: {
+      ...frame.change.activity,
+      history: {
+        ...current.view.history,
+        messages: mergeRemoteMessages(
+          current.view.history.messages,
+          frame.change.messages,
+        ),
+      },
+    },
+  };
+}
+
+/** Optional terminal transport. Disk outbox IDs survive a lost HTTP response/restart. */
+export class RemoteClient {
+  private state: ClientState = { outbox: [], failures: [] };
+  private frame?: RemoteFrame;
+  private socket?: WebSocket;
+  private reconnectTimer?: ReturnType<typeof setTimeout>;
+  private retryDelay = 500;
+  private closed = false;
+  private flushing = false;
+  private diskTail: Promise<void> = Promise.resolve();
+  private snapshot: ClientSnapshot = { connection: "connecting", pending: 0 };
+  private readonly listeners = new Set<() => void>();
+  constructor(readonly config: RemoteClientConfig) {}
+  async initialize(): Promise<void> {
+    try {
+      this.state = JSON.parse(
+        await readFile(this.config.statePath, "utf8"),
+      ) as ClientState;
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+    }
+    this.emit({ pending: this.state.outbox.length });
+    if (this.state.sessionId) this.watch(this.state.sessionId);
+    void this.flush();
+  }
+  getSnapshot = (): ClientSnapshot => this.snapshot;
+  subscribe = (listener: () => void): (() => void) => {
+    this.listeners.add(listener);
+    return () => this.listeners.delete(listener);
+  };
+  get sessionId(): string | undefined {
+    return this.state.sessionId;
+  }
+  get workspaceId(): string | undefined {
+    return this.state.workspaceId;
+  }
+  workspaces(): Promise<{ workspaces: { id: string; name: string }[] }> {
+    return this.request("/v1/workspaces");
+  }
+  sessions(workspaceId: string): Promise<{ sessions: RemoteSessionInfo[] }> {
+    return this.request(`/v1/workspaces/${workspaceId}/sessions`);
+  }
+  operation(id: string): Promise<OperationReceipt> {
+    return this.request(`/v1/operations/${id}`);
+  }
+
+  async select(sessionId: string, workspaceId: string): Promise<void> {
+    this.state.sessionId = sessionId;
+    this.state.workspaceId = workspaceId;
+    await this.persist();
+    this.frame = undefined;
+    this.emit({ view: undefined });
+    this.watch(sessionId);
+  }
+  async submit(
+    input: Omit<RemoteOperationInput, "requestId"> & Record<string, unknown>,
+  ): Promise<string> {
+    const request = { ...input, requestId: randomUUID() } as RemoteOperationInput;
+    this.state.outbox.push(request);
+    await this.persist();
+    this.emit({ pending: this.state.outbox.length });
+    void this.flush();
+    return request.requestId;
+  }
+  async loadOlderHistory(): Promise<void> {
+    if (this.frame?.type !== "snapshot") return;
+    const id = this.state.sessionId;
+    const before = this.frame.view.history.beforeOrdinal;
+    if (!id || !before) return;
+    const page = await this.request<RemoteHistoryPage>(
+      `/v1/sessions/${id}/history?before=${before}`,
+    );
+    if (id !== this.state.sessionId || this.frame?.type !== "snapshot") return;
+    this.frame = {
+      ...this.frame,
+      view: {
+        ...this.frame.view,
+        history: {
+          ...page,
+          messages: mergeRemoteMessages(
+            page.messages,
+            this.frame.view.history.messages,
+          ),
+        },
+      },
+    };
+    this.emit({ view: this.frame.view });
+  }
+  private async flush(): Promise<void> {
+    if (this.flushing || this.closed) return;
+    this.flushing = true;
+    try {
+      while (this.state.outbox.length && !this.closed) {
+        const input = this.state.outbox[0];
+        try {
+          const receipt = await this.request<OperationReceipt>("/v1/operations", input);
+          this.state.outbox.shift();
+          await this.persist();
+          if (input.kind === "create" || input.kind === "adopt")
+            await this.select(receipt.sessionId, input.workspaceId);
+          this.emit({ pending: this.state.outbox.length, error: undefined });
+        } catch (error) {
+          this.emit({
+            error: error instanceof Error ? error.message : String(error),
+            connection: "offline",
+          });
+          if (
+            error instanceof ClientHttpError &&
+            error.status >= 400 &&
+            error.status < 500 &&
+            error.status !== 429
+          ) {
+            this.state.outbox.shift();
+            this.state.failures.push({
+              requestId: input.requestId,
+              message: error.message,
+            });
+            this.state.failures = this.state.failures.slice(-20);
+            await this.persist();
+            this.emit({ pending: this.state.outbox.length });
+          } else {
+            this.reconnect();
+            break;
+          }
+        }
+      }
+    } finally {
+      this.flushing = false;
+    }
+  }
+  private watch(id: string): void {
+    this.socket?.close();
+    if (this.closed) return;
+    const url = new URL(`/v1/sessions/${id}/events`, this.config.url);
+    url.protocol = "wss:";
+    if (this.frame) {
+      url.searchParams.set("epoch", this.frame.epoch);
+      url.searchParams.set("after", String(this.frame.sequence));
+    }
+    this.emit({ connection: "connecting" });
+    const BunWebSocket = WebSocket as unknown as {
+      new (url: URL, options: WebSocketOptions): WebSocket;
+    };
+    const socket = new BunWebSocket(url, {
+      headers: { Authorization: `Bearer ${this.config.token}` },
+      ...(this.config.ca
+        ? { tls: { ca: this.config.ca, rejectUnauthorized: true } }
+        : {}),
+    });
+    this.socket = socket;
+    socket.onmessage = (event) => {
+      if (socket !== this.socket || this.closed) return;
+      try {
+        this.frame = applyRemoteFrame(
+          this.frame,
+          JSON.parse(String(event.data)) as RemoteFrame,
+        );
+        this.retryDelay = 500;
+        this.emit({
+          connection: "online",
+          view: this.frame.type === "snapshot" ? this.frame.view : undefined,
+          error: undefined,
+        });
+        void this.flush();
+      } catch {
+        this.frame = undefined;
+        socket.close();
+      }
+    };
+    socket.onclose = () => {
+      if (socket === this.socket && !this.closed) {
+        this.emit({ connection: "offline" });
+        this.reconnect();
+      }
+    };
+    socket.onerror = () => {
+      if (socket === this.socket && !this.closed) {
+        this.emit({ connection: "offline" });
+        socket.close();
+        this.reconnect();
+      }
+    };
+  }
+  private reconnect(): void {
+    if (this.closed || this.reconnectTimer) return;
+    this.reconnectTimer = setTimeout(() => {
+      this.reconnectTimer = undefined;
+      if (this.state.sessionId) this.watch(this.state.sessionId);
+      void this.flush();
+    }, this.retryDelay);
+    this.retryDelay = Math.min(this.retryDelay * 2, 10000);
+  }
+  async request<T>(route: string, input?: unknown): Promise<T> {
+    const response = await fetch(new URL(route, this.config.url), {
+      method: input === undefined ? "GET" : "POST",
+      redirect: "error",
+      headers: {
+        Authorization: `Bearer ${this.config.token}`,
+        "Content-Type": "application/json",
+      },
+      ...(input === undefined ? {} : { body: JSON.stringify(input) }),
+      ...(this.config.ca
+        ? { tls: { ca: this.config.ca, rejectUnauthorized: true } }
+        : {}),
+      signal: AbortSignal.timeout(15000),
+    });
+    const result = (await response.json()) as T & { error?: { message: string } };
+    if (!response.ok)
+      throw new ClientHttpError(
+        response.status,
+        result.error?.message ?? `HTTP ${response.status}`,
+      );
+    return result;
+  }
+  private persist(): Promise<void> {
+    const data = JSON.stringify(this.state);
+    this.diskTail = this.diskTail.then(async () => {
+      await mkdir(path.dirname(this.config.statePath), {
+        recursive: true,
+        mode: 0o700,
+      });
+      const temp = `${this.config.statePath}.${process.pid}.tmp`;
+      await writeFile(temp, data, { mode: 0o600 });
+      await chmod(temp, 0o600);
+      await rename(temp, this.config.statePath);
+    });
+    return this.diskTail;
+  }
+  private emit(patch: Partial<ClientSnapshot>): void {
+    this.snapshot = { ...this.snapshot, ...patch };
+    for (const listener of this.listeners) listener();
+  }
+  async close(): Promise<void> {
+    this.closed = true;
+    if (this.reconnectTimer) clearTimeout(this.reconnectTimer);
+    this.socket?.close();
+    await this.diskTail;
+    this.emit({ connection: "closed" });
+  }
+}
+class ClientHttpError extends Error {
+  constructor(
+    readonly status: number,
+    message: string,
+  ) {
+    super(message);
+  }
+}

package/src/remote/config.ts

@@ -0,0 +1,95 @@
+import { createHash, timingSafeEqual } from "node:crypto";
+import { readFile, realpath, stat } from "node:fs/promises";
+import path from "node:path";
+import { requireId, requireObject, requireText } from "./protocol";
+
+export type RemoteWorkspaceConfig = {
+  id: string;
+  name: string;
+  path: string;
+  profile?: string;
+};
+export type RemoteServiceConfig = {
+  stateDirectory: string;
+  hostname: string;
+  port: number;
+  tls: { certFile: string; keyFile: string };
+  devices: { id: string; name: string; tokenSha256: string }[];
+  workspaces: RemoteWorkspaceConfig[];
+};
+
+export async function loadRemoteConfig(file: string): Promise<RemoteServiceConfig> {
+  const absolute = path.resolve(file);
+  const raw = requireObject(JSON.parse(await readFile(absolute, "utf8")));
+  if (raw.version !== 1)
+    throw new Error("Remote service configuration version must be 1.");
+  const resolve = (value: unknown, name: string) =>
+    path.resolve(path.dirname(absolute), requireText(value, name, 4096));
+  const tls = requireObject(raw.tls);
+  const port = raw.port ?? 9443;
+  if (typeof port !== "number" || !Number.isInteger(port) || port < 1 || port > 65535)
+    throw new Error("Invalid service port.");
+  if (!Array.isArray(raw.devices) || raw.devices.length === 0)
+    throw new Error("At least one paired device is required.");
+  if (!Array.isArray(raw.workspaces) || raw.workspaces.length === 0)
+    throw new Error("At least one workspace is required.");
+  const devices = raw.devices.map((entry) => {
+    const device = requireObject(entry);
+    const tokenSha256 = requireText(device.tokenSha256, "tokenSha256", 64);
+    if (!/^[0-9a-f]{64}$/.test(tokenSha256))
+      throw new Error("Device tokenSha256 must be a lowercase SHA-256 digest.");
+    return {
+      id: requireId(device.id, "device.id"),
+      name: requireText(device.name, "device.name", 240),
+      tokenSha256,
+    };
+  });
+  const workspaces: RemoteWorkspaceConfig[] = [];
+  for (const entry of raw.workspaces) {
+    const workspace = requireObject(entry);
+    const root = await realpath(resolve(workspace.path, "workspace.path"));
+    if (!(await stat(root)).isDirectory())
+      throw new Error("Workspace must be a directory.");
+    workspaces.push({
+      id: requireId(workspace.id, "workspace.id"),
+      name: requireText(workspace.name, "workspace.name", 240),
+      path: root,
+      ...(workspace.profile === undefined
+        ? {}
+        : { profile: requireText(workspace.profile, "workspace.profile", 240) }),
+    });
+  }
+  if (
+    new Set(devices.map((d) => d.id)).size !== devices.length ||
+    new Set(workspaces.map((w) => w.id)).size !== workspaces.length ||
+    new Set(workspaces.map((w) => w.path)).size !== workspaces.length
+  )
+    throw new Error("Duplicate device/workspace identity.");
+  const hostname = raw.hostname ?? "127.0.0.1";
+  if (hostname !== "127.0.0.1" && hostname !== "::1")
+    throw new Error("Bind the service to loopback; expose only the relay TCP port.");
+  return {
+    stateDirectory: resolve(raw.stateDirectory, "stateDirectory"),
+    hostname,
+    port,
+    tls: {
+      certFile: resolve(tls.certFile, "tls.certFile"),
+      keyFile: resolve(tls.keyFile, "tls.keyFile"),
+    },
+    devices,
+    workspaces,
+  };
+}
+
+export function authenticateDevice(
+  header: string | null,
+  devices: RemoteServiceConfig["devices"],
+): string | undefined {
+  if (!header?.startsWith("Bearer ") || header.length > 256) return undefined;
+  const token = header.slice(7);
+  if (!/^[A-Za-z0-9_-]{43,128}$/.test(token)) return undefined;
+  const digest = createHash("sha256").update(token).digest();
+  return devices.find((device) =>
+    timingSafeEqual(digest, Buffer.from(device.tokenSha256, "hex")),
+  )?.id;
+}

package/src/remote/http-server.ts

@@ -0,0 +1,240 @@
+import type { ServerWebSocket } from "bun";
+import { authenticateDevice, type RemoteServiceConfig } from "./config";
+import {
+  RemoteError,
+  parseOperation,
+  requireId,
+  type RemoteCursor,
+  type RemoteFrame,
+} from "./protocol";
+import { RemoteService } from "./service";
+import type { HostedSession } from "../agent/runtime-hosted-session";
+
+type SocketData = {
+  session: HostedSession;
+  cursor?: RemoteCursor;
+  unsubscribe?: () => void;
+  device: string;
+};
+const SOCKET_BUFFER_LIMIT = 2 * 1024 * 1024;
+
+export function startRemoteHttpServer(
+  service: RemoteService,
+  config: RemoteServiceConfig,
+) {
+  const sockets = new Set<ServerWebSocket<SocketData>>();
+  const server = Bun.serve<SocketData>({
+    hostname: config.hostname,
+    port: config.port,
+    tls: {
+      cert: Bun.file(config.tls.certFile),
+      key: Bun.file(config.tls.keyFile),
+    },
+    maxRequestBodySize: 72 * 1024,
+    idleTimeout: 30,
+    async fetch(request, server) {
+      try {
+        // Native clients authenticate in headers. Browser-origin requests are not supported.
+        if (request.headers.has("origin"))
+          throw new RemoteError(
+            403,
+            "ORIGIN_REJECTED",
+            "Browser origins are not enabled.",
+          );
+        const device = authenticateDevice(
+          request.headers.get("authorization"),
+          config.devices,
+        );
+        if (!device)
+          throw new RemoteError(
+            401,
+            "AUTH_REQUIRED",
+            "Pair this device with the Mac before connecting.",
+          );
+        const url = new URL(request.url);
+        const parts = url.pathname.split("/").filter(Boolean);
+        if (parts[0] !== "v1")
+          throw new RemoteError(404, "NOT_FOUND", "Unknown API version or route.");
+        if (request.method === "GET" && url.pathname === "/v1/workspaces") {
+          return json({
+            version: 1,
+            workspaces: service.workspaces.map(({ id, name }) => ({
+              id,
+              name,
+            })),
+          });
+        }
+        if (
+          request.method === "GET" &&
+          parts.length === 4 &&
+          parts[1] === "workspaces" &&
+          parts[3] === "sessions"
+        ) {
+          return json({
+            sessions: await service.listSessions(requireId(parts[2], "workspaceId")),
+          });
+        }
+        if (parts[1] === "operations") {
+          if (request.method === "POST" && parts.length === 2) {
+            if (!request.headers.get("content-type")?.startsWith("application/json"))
+              throw new RemoteError(415, "JSON_REQUIRED", "Send application/json.");
+            const input = parseOperation(await request.json());
+            // Never use request.signal as a runtime cancellation signal.
+            return json(await service.submit(input, device), 202);
+          }
+          if (request.method === "GET" && parts.length === 3)
+            return json(service.store.get(requireId(parts[2], "requestId", true)));
+        }
+        if (request.method === "GET" && parts.length === 4 && parts[1] === "sessions") {
+          const session = service.session(requireId(parts[2], "sessionId", true));
+          await session.open();
+          if (parts[3] === "snapshot") return json(session.hub.snapshot());
+          if (parts[3] === "history") {
+            return json(
+              session.history(
+                optionalInteger(
+                  url.searchParams.get("before"),
+                  1,
+                  Number.MAX_SAFE_INTEGER,
+                ),
+                optionalInteger(url.searchParams.get("limit"), 1, 100),
+              ),
+            );
+          }
+          if (parts[3] === "events") {
+            if (sockets.size >= 64)
+              throw new RemoteError(
+                429,
+                "CONNECTION_LIMIT",
+                "Too many connected clients.",
+              );
+            const epoch = url.searchParams.get("epoch");
+            const sequence = optionalInteger(
+              url.searchParams.get("after"),
+              0,
+              Number.MAX_SAFE_INTEGER,
+            );
+            const cursor =
+              epoch && sequence !== undefined ? { epoch, sequence } : undefined;
+            if (server.upgrade(request, { data: { session, cursor, device } })) return;
+            throw new RemoteError(
+              400,
+              "WEBSOCKET_REQUIRED",
+              "Upgrade this request to WebSocket.",
+            );
+          }
+        }
+        throw new RemoteError(404, "NOT_FOUND", "Unknown API route.");
+      } catch (error) {
+        if (error instanceof RemoteError)
+          return json(
+            { error: { code: error.code, message: error.message } },
+            error.status,
+          );
+        if (error instanceof SyntaxError)
+          return json(
+            {
+              error: {
+                code: "INVALID_JSON",
+                message: "Request body is not valid JSON.",
+              },
+            },
+            400,
+          );
+        return json(
+          {
+            error: {
+              code: "LOCAL_SERVICE_ERROR",
+              message:
+                error instanceof Error ? error.message : "The local operation failed.",
+            },
+          },
+          500,
+        );
+      }
+    },
+    websocket: {
+      maxPayloadLength: 1024,
+      backpressureLimit: SOCKET_BUFFER_LIMIT,
+      closeOnBackpressureLimit: true,
+      idleTimeout: 60,
+      sendPings: true,
+      open(socket) {
+        sockets.add(socket);
+        const send = (frame: RemoteFrame) => {
+          try {
+            if (socket.getBufferedAmount() > SOCKET_BUFFER_LIMIT) {
+              socket.close(1013, "Reconnect to resynchronize");
+              return;
+            }
+            const text = JSON.stringify(frame);
+            if (socket.send(text) === -1)
+              socket.close(1013, "Reconnect to resynchronize");
+          } catch {
+            socket.close(1011, "Reconnect to resynchronize");
+          }
+        };
+        socket.data.unsubscribe = socket.data.session.hub.subscribe(
+          socket.data.cursor,
+          send,
+        );
+      },
+      message(socket) {
+        socket.close(1008, "Submit operations over HTTPS");
+      },
+      close(socket) {
+        sockets.delete(socket);
+        socket.data.unsubscribe?.();
+        // Detach only. The hosted runtime and its AbortController stay alive.
+      },
+    },
+  });
+  return {
+    port: server.port!,
+    async stopTransport() {
+      for (const socket of sockets) {
+        socket.data.unsubscribe?.();
+        socket.terminate();
+      }
+      // Bun 1.3.14 can leave stop's promise pending after a closing TLS socket
+      // is terminated. stop(true) synchronously closes the listener/connections;
+      // bound its completion wait so runtime disposal can always proceed.
+      let timer: ReturnType<typeof setTimeout> | undefined;
+      try {
+        await Promise.race([
+          server.stop(true),
+          new Promise<void>((resolve) => {
+            timer = setTimeout(resolve, 250);
+          }),
+        ]);
+      } finally {
+        if (timer) clearTimeout(timer);
+      }
+    },
+  };
+}
+
+function json(value: unknown, status = 200): Response {
+  return Response.json(value, {
+    status,
+    headers: {
+      "Cache-Control": "no-store",
+      "X-Content-Type-Options": "nosniff",
+    },
+  });
+}
+function optionalInteger(
+  value: string | null,
+  minimum: number,
+  maximum: number,
+): number | undefined {
+  if (value === null) return undefined;
+  if (
+    !/^\d+$/.test(value) ||
+    !Number.isSafeInteger(Number(value)) ||
+    Number(value) < minimum ||
+    Number(value) > maximum
+  )
+    throw new RemoteError(400, "INVALID_CURSOR", "Invalid history or event cursor.");
+  return Number(value);
+}