tinker-agent 2.13.0 → 3.0.0

package/src/remote/client.ts

@@ -1,3 +1,4 @@
+import { decodeFailure, type RemoteFailure } from "./failures";
 import { readFile, chmod, writeFile, rename, mkdir } from "node:fs/promises";
 import path from "node:path";
 import { randomUUID } from "node:crypto";
@@ -56,6 +57,7 @@ type ClientState = {
   failures: { requestId: string; message: string }[];
 };
 export type ClientSnapshot = {
+  cursor?: { epoch: string; sequence: number };
   connection: "connecting" | "online" | "offline" | "closed";
   view?: RemoteView;
   pending: number;
@@ -112,8 +114,12 @@ export class RemoteClient {
   private diskTail: Promise<void> = Promise.resolve();
   private snapshot: ClientSnapshot = { connection: "connecting", pending: 0 };
   private readonly listeners = new Set<() => void>();
-  constructor(readonly config: RemoteClientConfig) {}
+  constructor(
+    readonly config: RemoteClientConfig,
+    private readonly persistent = true,
+  ) {}
   async initialize(): Promise<void> {
+    if (!this.persistent) return;
     try {
       this.state = JSON.parse(
         await readFile(this.config.statePath, "utf8"),
@@ -139,6 +145,14 @@ export class RemoteClient {
   workspaces(): Promise<{ workspaces: { id: string; name: string }[] }> {
     return this.request("/v1/workspaces");
   }
+  async resolveWorkspace(
+    directory: string,
+  ): Promise<{ id: string; name: string; path: string }> {
+    const result = await this.request<{
+      workspace: { id: string; name: string; path: string };
+    }>(`/v1/workspaces/resolve?${new URLSearchParams({ directory })}`);
+    return result.workspace;
+  }
   sessions(workspaceId: string): Promise<{ sessions: RemoteSessionInfo[] }> {
     return this.request(`/v1/workspaces/${workspaceId}/sessions`);
   }
@@ -259,6 +273,7 @@ export class RemoteClient {
         );
         this.retryDelay = 500;
         this.emit({
+          cursor: { epoch: this.frame.epoch, sequence: this.frame.sequence },
           connection: "online",
           view: this.frame.type === "snapshot" ? this.frame.view : undefined,
           error: undefined,
@@ -292,7 +307,7 @@ export class RemoteClient {
     }, this.retryDelay);
     this.retryDelay = Math.min(this.retryDelay * 2, 10000);
   }
-  async request<T>(route: string, input?: unknown): Promise<T> {
+  async request<T>(route: string, input?: unknown, signal?: AbortSignal): Promise<T> {
     const response = await fetch(new URL(route, this.config.url), {
       method: input === undefined ? "GET" : "POST",
       redirect: "error",
@@ -304,9 +319,15 @@ export class RemoteClient {
       ...(this.config.ca
         ? { tls: { ca: this.config.ca, rejectUnauthorized: true } }
         : {}),
-      signal: AbortSignal.timeout(15000),
+      signal: signal
+        ? AbortSignal.any([signal, AbortSignal.timeout(15000)])
+        : AbortSignal.timeout(15000),
     });
-    const result = (await response.json()) as T & { error?: { message: string } };
+    const result = (await response.json()) as T & {
+      error?: { message: string };
+      failure?: RemoteFailure;
+    };
+    if (!response.ok && result.failure) throw decodeFailure(result.failure);
     if (!response.ok)
       throw new ClientHttpError(
         response.status,
@@ -315,6 +336,7 @@ export class RemoteClient {
     return result;
   }
   private persist(): Promise<void> {
+    if (!this.persistent) return Promise.resolve();
     const data = JSON.stringify(this.state);
     this.diskTail = this.diskTail.then(async () => {
       await mkdir(path.dirname(this.config.statePath), {
@@ -340,7 +362,7 @@ export class RemoteClient {
     this.emit({ connection: "closed" });
   }
 }
-class ClientHttpError extends Error {
+export class ClientHttpError extends Error {
   constructor(
     readonly status: number,
     message: string,

package/src/remote/config.ts

@@ -1,3 +1,4 @@
+import { parseResidentPolicy, type ResidentPolicy } from "./resident-policy";
 import { createHash, timingSafeEqual } from "node:crypto";
 import { readFile, realpath, stat } from "node:fs/promises";
 import path from "node:path";
@@ -10,6 +11,7 @@ export type RemoteWorkspaceConfig = {
   profile?: string;
 };
 export type RemoteServiceConfig = {
+  resident?: ResidentPolicy;
   stateDirectory: string;
   hostname: string;
   port: number;
@@ -27,12 +29,11 @@ export async function loadRemoteConfig(file: string): Promise<RemoteServiceConfi
     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)
+  if (typeof port !== "number" || !Number.isInteger(port) || port < 0 || 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.");
+  if (!Array.isArray(raw.workspaces)) throw new Error("Workspaces must be an array.");
   const devices = raw.devices.map((entry) => {
     const device = requireObject(entry);
     const tokenSha256 = requireText(device.tokenSha256, "tokenSha256", 64);
@@ -69,7 +70,10 @@ export async function loadRemoteConfig(file: string): Promise<RemoteServiceConfi
   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"),
+    resident: parseResidentPolicy(raw.resident),
+    stateDirectory: await canonicalDirectory(
+      resolve(raw.stateDirectory ?? "./state", "stateDirectory"),
+    ),
     hostname,
     port,
     tls: {
@@ -81,6 +85,17 @@ export async function loadRemoteConfig(file: string): Promise<RemoteServiceConfi
   };
 }
 
+async function canonicalDirectory(directory: string): Promise<string> {
+  try {
+    return await realpath(directory);
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+    const parent = path.dirname(directory);
+    if (parent === directory) throw error;
+    return path.join(await canonicalDirectory(parent), path.basename(directory));
+  }
+}
+
 export function authenticateDevice(
   header: string | null,
   devices: RemoteServiceConfig["devices"],

package/src/remote/failures.ts

@@ -0,0 +1,68 @@
+import { ContextManagerError } from "../context/context-manager";
+import { ContextBudgetExceededError } from "../model/model-request-preflight";
+import { ModelRequestMediaAggregateError } from "../model/model-client";
+import { ImageNotRecognizedError } from "../image/image-probe";
+
+export type RemoteFailure = {
+  name: string;
+  message: string;
+  maintenance?: Pick<ContextManagerError, "stage" | "code" | "fatal" | "committed">;
+  context?: Pick<
+    ContextBudgetExceededError,
+    "projectedInputTokens" | "inputBudgetTokens" | "triggerTokens" | "source"
+  >;
+};
+export function encodeFailure(error: unknown): RemoteFailure {
+  return {
+    name: error instanceof Error ? error.name : "Error",
+    message: error instanceof Error ? error.message : String(error),
+    ...(error instanceof ContextManagerError
+      ? {
+          maintenance: {
+            stage: error.stage,
+            code: error.code,
+            fatal: error.fatal,
+            committed: error.committed,
+          },
+        }
+      : {}),
+    ...(error instanceof ContextBudgetExceededError
+      ? {
+          context: {
+            projectedInputTokens: error.projectedInputTokens,
+            inputBudgetTokens: error.inputBudgetTokens,
+            triggerTokens: error.triggerTokens,
+            source: error.source,
+          },
+        }
+      : {}),
+    ...(error instanceof ModelRequestMediaAggregateError
+      ? { name: "ModelRequestMediaAggregateError" }
+      : {}),
+    ...(error instanceof ImageNotRecognizedError
+      ? { name: "ImageNotRecognizedError" }
+      : {}),
+  };
+}
+export function decodeFailure(failure: RemoteFailure): Error {
+  if (failure.name === "ContextManagerError" && failure.maintenance) {
+    const m = failure.maintenance;
+    return new ContextManagerError(
+      m.stage,
+      m.code,
+      m.fatal,
+      m.committed,
+      failure.message,
+    );
+  }
+  if (failure.name === "ContextBudgetExceededError" && failure.context) {
+    const error = new Error(failure.message);
+    Object.setPrototypeOf(error, ContextBudgetExceededError.prototype);
+    return Object.assign(error, { name: failure.name }, failure.context);
+  }
+  if (failure.name === "ModelRequestMediaAggregateError")
+    return new ModelRequestMediaAggregateError(failure.message);
+  if (failure.name === "ImageNotRecognizedError")
+    return new ImageNotRecognizedError(failure.message);
+  return new Error(failure.message);
+}

package/src/remote/http-server.ts

@@ -1,3 +1,6 @@
+import { sessionPost, sessionRead } from "./session-reads";
+import { resolveServiceWorkspace } from "./workspace-resolution";
+import { IMAGE_INPUT_POLICY } from "../image/image-input-policy";
 import type { ServerWebSocket } from "bun";
 import { authenticateDevice, type RemoteServiceConfig } from "./config";
 import {
@@ -14,6 +17,7 @@ type SocketData = {
   session: HostedSession;
   cursor?: RemoteCursor;
   unsubscribe?: () => void;
+  release?: () => void;
   device: string;
 };
 const SOCKET_BUFFER_LIMIT = 2 * 1024 * 1024;
@@ -30,9 +34,10 @@ export function startRemoteHttpServer(
       cert: Bun.file(config.tls.certFile),
       key: Bun.file(config.tls.keyFile),
     },
-    maxRequestBodySize: 72 * 1024,
+    maxRequestBodySize: Math.ceil(IMAGE_INPUT_POLICY.maxBytesPerImage / 3) * 4 + 4096,
     idleTimeout: 30,
     async fetch(request, server) {
+      let releaseRequest: (() => void) | undefined;
       try {
         // Native clients authenticate in headers. Browser-origin requests are not supported.
         if (request.headers.has("origin"))
@@ -55,6 +60,28 @@ export function startRemoteHttpServer(
         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/service")
+          return json({
+            version: 1,
+            instanceId: service.epoch,
+            ...service.residentStatus(),
+          });
+        if (request.method === "GET" && url.pathname === "/v1/workspaces/resolve") {
+          const directory = url.searchParams.get("directory");
+          if (!directory || directory.length > 4096)
+            throw new RemoteError(
+              400,
+              "INVALID_DIRECTORY",
+              "Provide a workspace directory of at most 4096 characters.",
+            );
+          const workspace = await resolveServiceWorkspace(
+            service.workspaces,
+            directory,
+          );
+          return json({
+            workspace: { id: workspace.id, name: workspace.name, path: workspace.path },
+          });
+        }
         if (request.method === "GET" && url.pathname === "/v1/workspaces") {
           return json({
             version: 1,
@@ -64,6 +91,19 @@ export function startRemoteHttpServer(
             })),
           });
         }
+        if (
+          request.method === "GET" &&
+          parts.length === 5 &&
+          parts[1] === "workspaces" &&
+          parts[3] === "tui-sessions"
+        ) {
+          return json({
+            session: await service.getTuiSession(
+              requireId(parts[2], "workspaceId"),
+              requireId(parts[4], "sessionId", true),
+            ),
+          });
+        }
         if (
           request.method === "GET" &&
           parts.length === 4 &&
@@ -74,20 +114,83 @@ export function startRemoteHttpServer(
             sessions: await service.listSessions(requireId(parts[2], "workspaceId")),
           });
         }
+        if (
+          request.method === "GET" &&
+          parts.length === 4 &&
+          parts[1] === "workspaces" &&
+          parts[3] === "tui-sessions"
+        ) {
+          return json({
+            sessions: await service.listTuiSessions(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());
+            const body = await request.text();
+            if (Buffer.byteLength(body) > 72 * 1024)
+              throw new RemoteError(
+                413,
+                "BODY_TOO_LARGE",
+                "Operation body is too large.",
+              );
+            const input = parseOperation(JSON.parse(body));
             // 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 === "POST" &&
+          parts.length === 4 &&
+          parts[1] === "sessions"
+        ) {
+          if (service.residentStatus().phase !== "ready")
+            throw new RemoteError(
+              503,
+              "SERVICE_DRAINING",
+              "Service is draining; new mutations are not accepted.",
+            );
+          const session = service.session(requireId(parts[2], "sessionId", true));
+          releaseRequest = session.attach(true);
+          await session.open();
+          session.assertAvailable();
+          const response = await sessionPost(
+            session,
+            parts[3],
+            request,
+            service.homeRoot,
+          );
+          if (response) return response;
+        }
         if (request.method === "GET" && parts.length === 4 && parts[1] === "sessions") {
           const session = service.session(requireId(parts[2], "sessionId", true));
+          releaseRequest = session.attach(true);
           await session.open();
+          session.assertAvailable();
+          if (
+            [
+              "files",
+              "last-response",
+              "view-file",
+              "memories",
+              "prompt-history",
+              "project-commands",
+              "git-branch",
+            ].includes(parts[3])
+          )
+            return json(
+              await sessionRead(
+                session,
+                parts[3],
+                url,
+                request.signal,
+                service.homeRoot,
+              ),
+            );
+          if (parts[3] === "tui-snapshot") return json(session.tuiSnapshot());
           if (parts[3] === "snapshot") return json(session.hub.snapshot());
           if (parts[3] === "history") {
             return json(
@@ -116,7 +219,17 @@ export function startRemoteHttpServer(
             );
             const cursor =
               epoch && sequence !== undefined ? { epoch, sequence } : undefined;
-            if (server.upgrade(request, { data: { session, cursor, device } })) return;
+            const release = session.attach();
+            try {
+              if (
+                server.upgrade(request, { data: { session, cursor, device, release } })
+              )
+                return;
+            } catch (error) {
+              release();
+              throw error;
+            }
+            release();
             throw new RemoteError(
               400,
               "WEBSOCKET_REQUIRED",
@@ -151,6 +264,8 @@ export function startRemoteHttpServer(
           },
           500,
         );
+      } finally {
+        releaseRequest?.();
       }
     },
     websocket: {
@@ -185,6 +300,7 @@ export function startRemoteHttpServer(
       close(socket) {
         sockets.delete(socket);
         socket.data.unsubscribe?.();
+        socket.data.release?.();
         // Detach only. The hosted runtime and its AbortController stay alive.
       },
     },
@@ -194,6 +310,7 @@ export function startRemoteHttpServer(
     async stopTransport() {
       for (const socket of sockets) {
         socket.data.unsubscribe?.();
+        socket.data.release?.();
         socket.terminate();
       }
       // Bun 1.3.14 can leave stop's promise pending after a closing TLS socket