tinker-agent 2.9.0 → 2.11.0

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);
+}

package/src/remote/protocol.ts

@@ -0,0 +1,228 @@
+import type {
+  RemoteHistoryPage,
+  RemoteMessage,
+} from "../session/remote-history-reader";
+
+export const REMOTE_PROTOCOL_VERSION = 1;
+export type OperationStatus =
+  | "accepted"
+  | "running"
+  | "waiting_input"
+  | "completed"
+  | "failed"
+  | "cancelled"
+  | "interrupted";
+
+export type RemoteOperationInput = { requestId: string } & (
+  | { kind: "create"; workspaceId: string; title?: string }
+  | { kind: "adopt"; workspaceId: string; sessionId: string }
+  | { kind: "prompt"; sessionId: string; prompt: string }
+  | { kind: "stop"; sessionId: string; targetRequestId: string }
+  | {
+      kind: "answer";
+      sessionId: string;
+      interactionId: string;
+      selectedIndex: number | null;
+    }
+  | {
+      kind: "confirm";
+      sessionId: string;
+      interactionId: string;
+      decision: "allow" | "deny";
+    }
+);
+
+export type OperationReceipt = {
+  requestId: string;
+  sessionId: string;
+  kind: RemoteOperationInput["kind"];
+  status: OperationStatus;
+  createdAt: string;
+  updatedAt: string;
+  turnId?: string;
+  prompt?: string;
+  error?: string;
+};
+
+export type RemoteSessionInfo = {
+  id: string;
+  workspaceId: string;
+  title: string;
+  modelName: string;
+  owner: "service" | "local";
+  status: string;
+  updatedAt: string;
+};
+
+export type RemoteInteraction =
+  | {
+      id: string;
+      kind: "question";
+      question: string;
+      options: readonly { description: string }[];
+    }
+  | { id: string; kind: "confirmation"; command: string; reason: string };
+
+export type RemoteTool = {
+  id: string;
+  name: string;
+  arguments: string;
+  status: "running" | "completed" | "failed" | "cancelled";
+  detail?: string;
+};
+
+export type RemoteActivity = {
+  session: RemoteSessionInfo;
+  status: "idle" | OperationStatus;
+  activeRequestId?: string;
+  activeTurnId?: string;
+  streaming?: { iterationId: string; attempt: number; text: string };
+  tools: RemoteTool[];
+  interaction?: RemoteInteraction;
+  operations: OperationReceipt[];
+  error?: string;
+};
+
+export type RemoteView = RemoteActivity & { history: RemoteHistoryPage };
+export type RemoteChange = { activity: RemoteActivity; messages: RemoteMessage[] };
+export type RemoteCursor = { epoch: string; sequence: number };
+export type RemoteFrame = { version: 1; epoch: string; sequence: number } & (
+  | { type: "snapshot"; view: RemoteView }
+  | { type: "event"; change: RemoteChange }
+);
+
+export class RemoteError extends Error {
+  constructor(
+    readonly status: number,
+    readonly code: string,
+    message: string,
+  ) {
+    super(message);
+    this.name = "RemoteError";
+  }
+}
+
+export function isTerminal(status: OperationStatus): boolean {
+  return ["completed", "failed", "cancelled", "interrupted"].includes(status);
+}
+
+const ID = /^[a-zA-Z0-9][a-zA-Z0-9_-]{0,100}$/;
+const UUID =
+  /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+export function requireId(value: unknown, name: string, uuid = false): string {
+  if (typeof value !== "string" || !(uuid ? UUID : ID).test(value)) {
+    throw new RemoteError(400, "INVALID_REQUEST", `${name} is invalid.`);
+  }
+  return value;
+}
+
+export function parseOperation(value: unknown): RemoteOperationInput {
+  const object = requireObject(value);
+  const requestId = requireId(object.requestId, "requestId", true);
+  const kind = object.kind;
+  const sessionId = () => requireId(object.sessionId, "sessionId", true);
+  let result: RemoteOperationInput;
+  switch (kind) {
+    case "create":
+      result = {
+        requestId,
+        kind,
+        workspaceId: requireId(object.workspaceId, "workspaceId"),
+        ...(object.title === undefined
+          ? {}
+          : { title: requireText(object.title, "title", 240) }),
+      };
+      break;
+    case "adopt":
+      result = {
+        requestId,
+        kind,
+        workspaceId: requireId(object.workspaceId, "workspaceId"),
+        sessionId: sessionId(),
+      };
+      break;
+    case "prompt":
+      result = {
+        requestId,
+        kind,
+        sessionId: sessionId(),
+        prompt: requireText(object.prompt, "prompt", 64 * 1024),
+      };
+      break;
+    case "stop":
+      result = {
+        requestId,
+        kind,
+        sessionId: sessionId(),
+        targetRequestId: requireId(object.targetRequestId, "targetRequestId", true),
+      };
+      break;
+    case "confirm":
+      if (object.decision !== "allow" && object.decision !== "deny") {
+        throw new RemoteError(
+          400,
+          "INVALID_REQUEST",
+          "decision must be allow or deny.",
+        );
+      }
+      result = {
+        requestId,
+        kind,
+        sessionId: sessionId(),
+        interactionId: requireId(object.interactionId, "interactionId", true),
+        decision: object.decision,
+      };
+      break;
+    case "answer": {
+      const selectedIndex = object.selectedIndex;
+      if (
+        selectedIndex !== null &&
+        (typeof selectedIndex !== "number" ||
+          !Number.isSafeInteger(selectedIndex) ||
+          selectedIndex < 0)
+      ) {
+        throw new RemoteError(
+          400,
+          "INVALID_REQUEST",
+          "selectedIndex must be a nonnegative integer or null.",
+        );
+      }
+      result = {
+        requestId,
+        kind,
+        sessionId: sessionId(),
+        interactionId: requireId(object.interactionId, "interactionId", true),
+        selectedIndex,
+      };
+      break;
+    }
+    default:
+      throw new RemoteError(400, "INVALID_REQUEST", "Unknown operation kind.");
+  }
+  if (Object.keys(object).some((key) => !(key in result))) {
+    throw new RemoteError(400, "INVALID_REQUEST", "Unexpected operation field.");
+  }
+  return result;
+}
+
+export function requireObject(value: unknown): Record<string, unknown> {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) {
+    throw new RemoteError(400, "INVALID_REQUEST", "Expected an object.");
+  }
+  return value as Record<string, unknown>;
+}
+
+export function requireText(value: unknown, name: string, maxBytes: number): string {
+  if (
+    typeof value !== "string" ||
+    !value.trim() ||
+    Buffer.byteLength(value) > maxBytes
+  ) {
+    throw new RemoteError(
+      400,
+      "INVALID_REQUEST",
+      `${name} must contain 1–${maxBytes} bytes.`,
+    );
+  }
+  return value;
+}

package/src/remote/service-store.ts

@@ -0,0 +1,175 @@
+import { Database } from "bun:sqlite";
+import { chmod, mkdir } from "node:fs/promises";
+import path from "node:path";
+import { stableJsonStringify, sha256 } from "../model/model-request-preflight";
+import { parseSessionId } from "../ids/runtime-id";
+import { SessionLease } from "../session/session-lock";
+import {
+  RemoteError,
+  type RemoteOperationInput,
+  type OperationReceipt,
+  type RemoteSessionInfo,
+} from "./protocol";
+
+export type ManagedSessionRecord = RemoteSessionInfo & {
+  workspacePath: string;
+  initialized: boolean;
+};
+type ReceiptRow = {
+  device: string;
+  fingerprint: string;
+  receipt: string;
+  input: string;
+};
+const SERVICE_LEASE_ID = parseSessionId("00000000-0000-7000-8000-000000000001");
+
+/** Durable acceptance receipts, separate from the canonical conversation databases. */
+export class RemoteServiceStore {
+  private constructor(
+    private readonly db: Database,
+    private readonly lease: SessionLease,
+  ) {}
+
+  static async open(directory: string): Promise<RemoteServiceStore> {
+    await mkdir(directory, { recursive: true, mode: 0o700 });
+    await chmod(directory, 0o700);
+    const lease = await SessionLease.acquire({
+      sessionDirectory: directory,
+      sessionId: SERVICE_LEASE_ID,
+    });
+    let db: Database | undefined;
+    try {
+      const filename = path.join(directory, "remote.sqlite");
+      db = new Database(filename, { create: true, strict: true });
+      await chmod(filename, 0o600);
+      db.exec(
+        "PRAGMA journal_mode=WAL; PRAGMA synchronous=FULL; PRAGMA busy_timeout=5000;",
+      );
+      const version = (
+        db.query("PRAGMA user_version").get() as { user_version: number }
+      ).user_version;
+      if (version !== 0 && version !== 1)
+        throw new Error("Unsupported remote state schema.");
+      db.exec(`CREATE TABLE IF NOT EXISTS managed_sessions (id TEXT PRIMARY KEY, record TEXT NOT NULL) STRICT;
+        CREATE TABLE IF NOT EXISTS operations (id TEXT PRIMARY KEY, session_id TEXT NOT NULL, device TEXT NOT NULL, fingerprint TEXT NOT NULL, input TEXT NOT NULL, receipt TEXT NOT NULL) STRICT;
+        CREATE INDEX IF NOT EXISTS operations_session ON operations(session_id);
+        PRAGMA user_version=1;`);
+      const store = new RemoteServiceStore(db, lease);
+      for (const row of db.query("SELECT receipt FROM operations").all() as {
+        receipt: string;
+      }[]) {
+        const receipt = JSON.parse(row.receipt) as OperationReceipt;
+        if (["accepted", "running", "waiting_input"].includes(receipt.status)) {
+          store.update({
+            ...receipt,
+            status: "interrupted",
+            error:
+              "The local service process stopped. This request will not be replayed automatically.",
+          });
+        }
+      }
+      return store;
+    } catch (error) {
+      db?.close();
+      await lease.release();
+      throw error;
+    }
+  }
+
+  sessions(): ManagedSessionRecord[] {
+    return (
+      this.db.query("SELECT record FROM managed_sessions").all() as { record: string }[]
+    ).map((row) => JSON.parse(row.record) as ManagedSessionRecord);
+  }
+  session(id: string): ManagedSessionRecord | undefined {
+    const row = this.db
+      .query("SELECT record FROM managed_sessions WHERE id = ?")
+      .get(id) as { record: string } | null;
+    return row ? (JSON.parse(row.record) as ManagedSessionRecord) : undefined;
+  }
+  saveSession(record: ManagedSessionRecord): void {
+    this.db
+      .query(
+        "INSERT INTO managed_sessions VALUES (?, ?) ON CONFLICT(id) DO UPDATE SET record=excluded.record",
+      )
+      .run(record.id, JSON.stringify(record));
+  }
+  existing(input: RemoteOperationInput, device: string): OperationReceipt | undefined {
+    const row = this.db
+      .query("SELECT * FROM operations WHERE id = ?")
+      .get(input.requestId) as ReceiptRow | null;
+    if (!row) return undefined;
+    if (row.device !== device || row.fingerprint !== sha256(stableJsonStringify(input)))
+      throw new RemoteError(
+        409,
+        "REQUEST_ID_REUSED",
+        "This request ID was already used with different data or by another device.",
+      );
+    return JSON.parse(row.receipt) as OperationReceipt;
+  }
+  accept(
+    input: RemoteOperationInput,
+    device: string,
+    sessionId: string,
+    session?: ManagedSessionRecord,
+  ): OperationReceipt {
+    const now = new Date().toISOString();
+    const receipt: OperationReceipt = {
+      requestId: input.requestId,
+      kind: input.kind,
+      sessionId,
+      status: "accepted",
+      createdAt: now,
+      updatedAt: now,
+      ...(input.kind === "prompt" ? { prompt: input.prompt } : {}),
+    };
+    this.db.transaction(() => {
+      this.db
+        .query("INSERT INTO operations VALUES (?, ?, ?, ?, ?, ?)")
+        .run(
+          input.requestId,
+          sessionId,
+          device,
+          sha256(stableJsonStringify(input)),
+          JSON.stringify(input),
+          JSON.stringify(receipt),
+        );
+      if (session) this.saveSession(session);
+    })();
+    return receipt;
+  }
+  get(id: string): OperationReceipt {
+    const row = this.db
+      .query("SELECT receipt FROM operations WHERE id = ?")
+      .get(id) as { receipt: string } | null;
+    if (!row)
+      throw new RemoteError(
+        404,
+        "REQUEST_NOT_FOUND",
+        "Request was not accepted by this service.",
+      );
+    return JSON.parse(row.receipt) as OperationReceipt;
+  }
+  operations(sessionId: string): OperationReceipt[] {
+    return (
+      this.db
+        .query(
+          "SELECT receipt FROM operations WHERE session_id = ? ORDER BY rowid DESC LIMIT 100",
+        )
+        .all(sessionId) as { receipt: string }[]
+    )
+      .reverse()
+      .map((row) => JSON.parse(row.receipt) as OperationReceipt);
+  }
+  update(receipt: OperationReceipt): OperationReceipt {
+    const next = { ...receipt, updatedAt: new Date().toISOString() };
+    this.db
+      .query("UPDATE operations SET receipt = ? WHERE id = ?")
+      .run(JSON.stringify(next), receipt.requestId);
+    return next;
+  }
+  async close(): Promise<void> {
+    this.db.close();
+    await this.lease.release();
+  }
+}