tinker-agent 2.12.0 → 3.0.0

package/src/remote/local-service-discovery.ts

@@ -0,0 +1,361 @@
+import { createHash, randomUUID } from "node:crypto";
+import { createConnection, createServer } from "node:net";
+import {
+  chmod,
+  lstat,
+  mkdir,
+  readFile,
+  realpath,
+  rename,
+  unlink,
+  writeFile,
+} from "node:fs/promises";
+import path from "node:path";
+import { defaultHomeRoot } from "../session/workspace-storage";
+import { loadRemoteConfig, type RemoteServiceConfig } from "./config";
+
+export type LocalServiceTarget = {
+  configPath: string;
+  config: RemoteServiceConfig;
+  fingerprint: string;
+  homeRoot: string;
+};
+export type LocalServiceInstance = {
+  version: 1;
+  appVersion?: string;
+  packageRoot?: string;
+  instanceId: string;
+  pid: number;
+  startedAt: string;
+  configPath: string;
+  stateDirectory: string;
+  fingerprint: string;
+  url: string;
+};
+
+export function defaultServiceConfigPath(env: NodeJS.ProcessEnv): string {
+  return path.resolve(defaultHomeRoot(env), ".tinker/service/service.json");
+}
+
+export async function loadLocalServiceTarget(
+  configPath: string,
+  env: NodeJS.ProcessEnv,
+): Promise<LocalServiceTarget> {
+  const canonicalPath = await realpath(configPath).catch((error: unknown) => {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT")
+      throw new Error(
+        `Service configuration not found: ${configPath}. Create it or use --config <path>.`,
+      );
+    throw error;
+  });
+  const config = await loadRemoteConfig(canonicalPath);
+  const homeRoot = await realpath(defaultHomeRoot(env));
+  const fingerprint = createHash("sha256")
+    .update(JSON.stringify({ config, homeRoot }))
+    .update(await readFile(config.tls.certFile))
+    .update(await readFile(config.tls.keyFile))
+    .digest("hex");
+  return { configPath: canonicalPath, config, fingerprint, homeRoot };
+}
+
+export function localServicePaths(directory: string) {
+  // Keep Unix paths short even when workspaces/state live deep in macOS temp roots.
+  const socketRoot = `/tmp/tinker-service-${process.getuid?.() ?? "unknown"}`;
+  const name = createHash("sha256").update(directory).digest("hex").slice(0, 32);
+  return {
+    socket: path.join(socketRoot, `${name}.sock`),
+    instance: path.join(directory, "service-instance.json"),
+    log: path.join(directory, "service.log"),
+    startup: path.join(directory, "startup"),
+  };
+}
+
+/** Live, read-only local probe. A PID or a leftover descriptor never proves readiness. */
+export async function discoverLocalService(
+  target: LocalServiceTarget,
+  allowDifferentConfig = false,
+): Promise<LocalServiceInstance | undefined> {
+  return (await requestLocalService(target, undefined, undefined, allowDifferentConfig))
+    ?.instance;
+}
+
+export async function shutdownLocalService(
+  target: LocalServiceTarget,
+  force: boolean,
+): Promise<LocalServiceInstance | undefined> {
+  return (await requestLocalService(target, undefined, { force }))?.instance;
+}
+
+export async function registerLocalWorkspace(
+  target: LocalServiceTarget,
+  directory: string,
+): Promise<RemoteServiceConfig["workspaces"][number]> {
+  const response = await requestLocalService(target, directory);
+  if (!response?.workspace)
+    throw new Error("Local service is not ready for workspace registration.");
+  return response.workspace;
+}
+
+type LocalServiceReply = {
+  instance: LocalServiceInstance;
+  workspace?: RemoteServiceConfig["workspaces"][number];
+  error?: string;
+};
+
+async function requestLocalService(
+  target: LocalServiceTarget,
+  directory?: string,
+  shutdown?: { force: boolean },
+  allowDifferentConfig = false,
+): Promise<LocalServiceReply | undefined> {
+  if (process.platform === "win32")
+    throw new Error("Local service discovery currently requires macOS/Linux.");
+  const socketPath = localServicePaths(target.config.stateDirectory).socket;
+  try {
+    const root = await lstat(path.dirname(socketPath));
+    if (
+      !root.isDirectory() ||
+      root.isSymbolicLink() ||
+      root.uid !== process.getuid?.() ||
+      (root.mode & 0o077) !== 0
+    )
+      throw new Error(
+        "Local discovery socket directory has unsafe ownership or permissions.",
+      );
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return undefined;
+    throw error;
+  }
+  const nonce = randomUUID();
+  const response = await new Promise<LocalServiceReply | undefined>(
+    (resolve, reject) => {
+      const socket = createConnection(socketPath);
+      socket.setEncoding("utf8");
+      let text = "";
+      let settled = false;
+      const finish = (value?: LocalServiceReply, error?: Error) => {
+        if (settled) return;
+        settled = true;
+        socket.destroy();
+        if (error) reject(error);
+        else resolve(value);
+      };
+      socket.setTimeout(
+        shutdown
+          ? (target.config.resident?.shutdownGraceMs ?? 30000) + 15000
+          : directory === undefined
+            ? 1000
+            : 10000,
+        () => finish(),
+      );
+      socket.once("error", (error: NodeJS.ErrnoException) => {
+        if (["ENOENT", "ECONNREFUSED", "ECONNRESET"].includes(error.code ?? ""))
+          finish();
+        else finish(undefined, error);
+      });
+      socket.once("connect", () =>
+        socket.write(
+          `${shutdown ? JSON.stringify({ nonce, command: "shutdown", force: shutdown.force }) : directory === undefined ? nonce : JSON.stringify({ nonce, command: "register-workspace", directory, fingerprint: target.fingerprint })}\n`,
+        ),
+      );
+      socket.on("data", (chunk: string) => {
+        text += chunk;
+        if (text.length > 16384)
+          return finish(undefined, new Error("Invalid local service response."));
+        if (!text.includes("\n")) return;
+        try {
+          const response = JSON.parse(text.trim()) as LocalServiceReply & {
+            nonce?: unknown;
+          };
+          const value = response.instance;
+          if (
+            response.nonce !== nonce ||
+            value?.version !== 1 ||
+            typeof value.instanceId !== "string" ||
+            !Number.isInteger(value.pid) ||
+            typeof value.url !== "string" ||
+            typeof value.fingerprint !== "string"
+          )
+            throw new Error("Invalid local service response.");
+          finish(response);
+        } catch (error) {
+          finish(
+            undefined,
+            error instanceof Error
+              ? error
+              : new Error("Invalid local service response."),
+          );
+        }
+      });
+      socket.once("end", () => finish());
+    },
+  );
+  if (
+    !shutdown &&
+    !allowDifferentConfig &&
+    response &&
+    response.instance.fingerprint !== target.fingerprint
+  )
+    throw new Error(
+      "The running service uses different configuration or TINKER_HOME. Stop it before changing configuration.",
+    );
+  if (shutdown && response?.error?.startsWith("Invalid local workspace registration"))
+    throw new Error(
+      `This older service cannot drain through the control endpoint. Stop its verified live pid ${response.instance.pid} explicitly, then retry.`,
+    );
+  if (response?.error) throw new Error(response.error);
+  return response;
+}
+
+/** Called only while the canonical service lease is held, after HTTPS is listening. */
+export async function publishLocalService(
+  target: LocalServiceTarget,
+  instanceId: string,
+  port: number,
+  registerWorkspace?: (
+    directory: string,
+  ) => Promise<RemoteServiceConfig["workspaces"][number]>,
+  administration?: {
+    appVersion: string;
+    status(): Record<string, unknown>;
+    shutdown(force: boolean): Promise<() => void>;
+  },
+): Promise<() => Promise<void>> {
+  const files = localServicePaths(target.config.stateDirectory);
+  const socketRoot = path.dirname(files.socket);
+  await mkdir(socketRoot, { recursive: true, mode: 0o700 });
+  const rootStat = await lstat(socketRoot);
+  if (
+    !rootStat.isDirectory() ||
+    rootStat.isSymbolicLink() ||
+    rootStat.uid !== process.getuid?.() ||
+    (rootStat.mode & 0o077) !== 0
+  )
+    throw new Error(
+      "Local discovery socket directory has unsafe ownership or permissions.",
+    );
+  const instance: LocalServiceInstance = {
+    version: 1,
+    appVersion: administration?.appVersion,
+    packageRoot: await realpath(new URL("../../", import.meta.url)),
+    instanceId,
+    pid: process.pid,
+    startedAt: new Date().toISOString(),
+    configPath: target.configPath,
+    stateDirectory: target.config.stateDirectory,
+    fingerprint: target.fingerprint,
+    url: `https://${target.config.hostname === "::1" ? "[::1]" : target.config.hostname}:${port}`,
+  };
+  await removeIfMissing(files.socket);
+  const server = createServer((socket) => {
+    socket.setEncoding("utf8");
+    let input = "";
+    let handling = false;
+    socket.setTimeout(1000, () => socket.destroy());
+    socket.on("error", () => socket.destroy());
+    socket.on("data", (chunk: string) => {
+      if (handling) return;
+      input += chunk;
+      if (input.length > 8192) {
+        socket.destroy();
+        return;
+      }
+      if (!input.includes("\n")) return;
+      handling = true;
+      socket.setTimeout(
+        (target.config.resident?.shutdownGraceMs ?? 30000) + 15000,
+        () => socket.destroy(),
+      );
+      const reply = async () => {
+        let nonce = input.trim();
+        try {
+          if (!input.startsWith("{")) {
+            socket.end(
+              `${JSON.stringify({ nonce, instance: { ...instance, ...administration?.status() } })}\n`,
+            );
+            return;
+          }
+          const command = JSON.parse(input.trim()) as {
+            nonce: string;
+            command: string;
+            directory: string;
+            fingerprint: string;
+            force?: boolean;
+          };
+          nonce = command.nonce;
+          if (
+            command.command === "shutdown" &&
+            administration &&
+            typeof nonce === "string" &&
+            nonce.length <= 100 &&
+            typeof command.force === "boolean"
+          ) {
+            const stop = await administration.shutdown(command.force);
+            socket.end(`${JSON.stringify({ nonce, instance })}\n`);
+            setTimeout(stop, 100);
+            return;
+          }
+          if (
+            typeof nonce !== "string" ||
+            nonce.length > 100 ||
+            command.command !== "register-workspace" ||
+            typeof command.directory !== "string" ||
+            command.fingerprint !== target.fingerprint ||
+            !registerWorkspace
+          )
+            throw new Error(
+              "Invalid local workspace registration request or service configuration changed.",
+            );
+          const workspace = await registerWorkspace(command.directory);
+          socket.end(`${JSON.stringify({ nonce, instance, workspace })}\n`);
+        } catch (error) {
+          socket.end(
+            `${JSON.stringify({ nonce, instance, error: error instanceof Error ? error.message : String(error) })}\n`,
+          );
+        }
+      };
+      void reply();
+    });
+  });
+  let listening = false;
+  const temp = `${files.instance}.${instanceId}.tmp`;
+  const discoveryTemp = `${files.socket}.json.${instanceId}.tmp`;
+  try {
+    await new Promise<void>((resolve, reject) => {
+      server.once("error", reject);
+      server.listen(files.socket, () => {
+        listening = true;
+        resolve();
+      });
+    });
+    await chmod(files.socket, 0o600);
+    await writeFile(temp, `${JSON.stringify(instance)}\n`, { mode: 0o600 });
+    await rename(temp, files.instance);
+    await writeFile(discoveryTemp, `${JSON.stringify(instance)}\n`, {
+      mode: 0o600,
+    });
+    await rename(discoveryTemp, `${files.socket}.json`);
+  } catch (error) {
+    await removeIfMissing(discoveryTemp);
+    if (listening) await new Promise<void>((resolve) => server.close(() => resolve()));
+    await removeIfMissing(temp);
+    throw error;
+  }
+  return async () => {
+    await new Promise<void>((resolve) => server.close(() => resolve()));
+    await removeIfMissing(files.instance);
+    // Keep the installation guard while launchd may restart this process.
+    if (
+      !(await Bun.file(
+        path.join(target.config.stateDirectory, "supervisor.enabled"),
+      ).exists())
+    )
+      await removeIfMissing(`${files.socket}.json`);
+  };
+}
+
+async function removeIfMissing(filename: string): Promise<void> {
+  await unlink(filename).catch((error: unknown) => {
+    if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+  });
+}

package/src/remote/prompt-history.ts

@@ -0,0 +1,36 @@
+import { PromptHistory } from "../tui/prompt-history";
+import { validatePromptDraft, type PromptDraft } from "../tui/prompt-draft";
+import { promptHistoryPath } from "../cli/config";
+import { RemoteError, requireObject } from "./protocol";
+
+const pending = new Map<string, Promise<void>>();
+export async function readPromptHistory(workspaceRoot: string, homeRoot?: string) {
+  const filename = await promptHistoryPath(workspaceRoot, homeRoot);
+  await pending.get(filename);
+  return (await PromptHistory.load(filename)).records;
+}
+export async function appendPromptHistory(
+  request: Request,
+  workspaceRoot: string,
+  homeRoot?: string,
+): Promise<void> {
+  const body = await request.text();
+  if (Buffer.byteLength(body) > 96 * 1024)
+    throw new RemoteError(413, "BODY_TOO_LARGE", "Prompt history entry is too large.");
+  const input = requireObject(JSON.parse(body));
+  const prompt = input.prompt as string | PromptDraft;
+  if (typeof prompt !== "string") validatePromptDraft(prompt);
+  const filename = await promptHistoryPath(workspaceRoot, homeRoot);
+  const next = (pending.get(filename) ?? Promise.resolve())
+    .catch(() => undefined)
+    .then(async () => {
+      const history = await PromptHistory.load(filename);
+      await history.append(prompt);
+    });
+  pending.set(filename, next);
+  try {
+    await next;
+  } finally {
+    if (pending.get(filename) === next) pending.delete(filename);
+  }
+}

package/src/remote/protocol.ts

@@ -1,3 +1,12 @@
+import type { RemoteFailure } from "./failures";
+import {
+  parseSessionOperation,
+  type SessionOperation,
+  type SessionOperationResult,
+} from "./session-operations";
+import { validateUserMessage, type UserImageAttachment } from "../image/image-types";
+import type { RunAgentResult } from "../agent/types";
+import type { QueueFollowUpResult } from "../agent/runtime-session-contracts";
 import type {
   RemoteHistoryPage,
   RemoteMessage,
@@ -14,9 +23,23 @@ export type OperationStatus =
   | "interrupted";
 
 export type RemoteOperationInput = { requestId: string } & (
-  | { kind: "create"; workspaceId: string; title?: string }
+  | { kind: "create"; workspaceId: string; title?: string; profileName?: string }
+  | { kind: "delete_session"; sessionId: string; targetSessionId: string }
+  | SessionOperation
   | { kind: "adopt"; workspaceId: string; sessionId: string }
-  | { kind: "prompt"; sessionId: string; prompt: string }
+  | {
+      kind: "prompt";
+      sessionId: string;
+      prompt: string;
+      attachments?: readonly UserImageAttachment[];
+    }
+  | {
+      kind: "provider_retry";
+      sessionId: string;
+      interactionId: string;
+      decision: "retry" | "stop";
+    }
+  | { kind: "follow_up"; sessionId: string; targetRequestId: string; prompt: string }
   | { kind: "stop"; sessionId: string; targetRequestId: string }
   | {
       kind: "answer";
@@ -33,6 +56,7 @@ export type RemoteOperationInput = { requestId: string } & (
 );
 
 export type OperationReceipt = {
+  shutdownInterrupted?: boolean;
   requestId: string;
   sessionId: string;
   kind: RemoteOperationInput["kind"];
@@ -41,7 +65,13 @@ export type OperationReceipt = {
   updatedAt: string;
   turnId?: string;
   prompt?: string;
+  attachments?: readonly UserImageAttachment[];
+  sessionResult?: SessionOperationResult;
+  failure?: RemoteFailure;
   error?: string;
+  result?: RunAgentResult;
+  followUp?: QueueFollowUpResult;
+  hasFollowUps?: boolean;
 };
 
 export type RemoteSessionInfo = {
@@ -123,16 +153,37 @@ export function parseOperation(value: unknown): RemoteOperationInput {
   const sessionId = () => requireId(object.sessionId, "sessionId", true);
   let result: RemoteOperationInput;
   switch (kind) {
+    case "compact":
+    case "retire":
+    case "undo":
+    case "fork":
+    case "reasoning":
+    case "yolo":
+    case "switch_model":
+    case "default_profile":
+      result = { requestId, ...parseSessionOperation(object) };
+      break;
     case "create":
       result = {
         requestId,
         kind,
         workspaceId: requireId(object.workspaceId, "workspaceId"),
+        ...(object.profileName === undefined
+          ? {}
+          : { profileName: requireText(object.profileName, "profileName", 240) }),
         ...(object.title === undefined
           ? {}
           : { title: requireText(object.title, "title", 240) }),
       };
       break;
+    case "delete_session":
+      result = {
+        kind,
+        requestId,
+        sessionId: sessionId(),
+        targetSessionId: requireId(object.targetSessionId, "targetSessionId", true),
+      };
+      break;
     case "adopt":
       result = {
         requestId,
@@ -147,6 +198,31 @@ export function parseOperation(value: unknown): RemoteOperationInput {
         kind,
         sessionId: sessionId(),
         prompt: requireText(object.prompt, "prompt", 64 * 1024),
+        ...(object.attachments === undefined
+          ? {}
+          : { attachments: object.attachments as readonly UserImageAttachment[] }),
+      };
+      try {
+        validateUserMessage({
+          role: "user",
+          content: result.prompt,
+          attachments: result.attachments,
+        });
+      } catch (error) {
+        throw new RemoteError(
+          400,
+          "INVALID_IMAGE_MESSAGE",
+          error instanceof Error ? error.message : String(error),
+        );
+      }
+      break;
+    case "follow_up":
+      result = {
+        requestId,
+        kind,
+        sessionId: sessionId(),
+        targetRequestId: requireId(object.targetRequestId, "targetRequestId", true),
+        prompt: requireText(object.prompt, "prompt", 64 * 1024),
       };
       break;
     case "stop":
@@ -157,6 +233,21 @@ export function parseOperation(value: unknown): RemoteOperationInput {
         targetRequestId: requireId(object.targetRequestId, "targetRequestId", true),
       };
       break;
+    case "provider_retry":
+      if (object.decision !== "retry" && object.decision !== "stop")
+        throw new RemoteError(
+          400,
+          "INVALID_REQUEST",
+          "decision must be retry or stop.",
+        );
+      result = {
+        requestId,
+        kind,
+        sessionId: sessionId(),
+        interactionId: requireId(object.interactionId, "interactionId", true),
+        decision: object.decision,
+      };
+      break;
     case "confirm":
       if (object.decision !== "allow" && object.decision !== "deny") {
         throw new RemoteError(

package/src/remote/resident-policy.ts

@@ -0,0 +1,96 @@
+import { RemoteError } from "./protocol";
+
+export type ResidentPolicy = {
+  maxLoadedSessions: number;
+  maxConcurrentTurns: number;
+  maxPendingTurns: number;
+  idleTimeoutMs: number;
+  shutdownGraceMs: number;
+};
+export const DEFAULT_RESIDENT_POLICY: Readonly<ResidentPolicy> = Object.freeze({
+  maxLoadedSessions: 16,
+  maxConcurrentTurns: 4,
+  maxPendingTurns: 32,
+  idleTimeoutMs: 5 * 60 * 1000,
+  shutdownGraceMs: 30 * 1000,
+});
+export function parseResidentPolicy(value: unknown): ResidentPolicy {
+  if (value === undefined) return { ...DEFAULT_RESIDENT_POLICY };
+  if (!value || typeof value !== "object" || Array.isArray(value))
+    throw new Error("resident must be an object.");
+  const entries = value as Record<string, unknown>;
+  for (const key of Object.keys(entries))
+    if (!(key in DEFAULT_RESIDENT_POLICY))
+      throw new Error(`Unknown resident setting: ${key}`);
+  const result = { ...DEFAULT_RESIDENT_POLICY };
+  for (const key of Object.keys(result) as (keyof ResidentPolicy)[]) {
+    const candidate = entries[key] ?? result[key];
+    const maximum = key.endsWith("Ms") ? 86400000 : 4096;
+    if (
+      typeof candidate !== "number" ||
+      !Number.isInteger(candidate) ||
+      candidate < 1 ||
+      candidate > maximum
+    )
+      throw new Error(
+        `Invalid resident.${key}; expected an integer from 1 to ${maximum}.`,
+      );
+    result[key] = candidate;
+  }
+  if (
+    result.maxConcurrentTurns > result.maxLoadedSessions ||
+    result.maxPendingTurns < result.maxConcurrentTurns
+  )
+    throw new Error(
+      "resident requires maxConcurrentTurns <= maxLoadedSessions and maxPendingTurns >= maxConcurrentTurns.",
+    );
+  return result;
+}
+
+/** FIFO execution slots. Queued cancellation never enters the runtime. */
+export class TurnSlots {
+  private active = 0;
+  private readonly waiting: (() => void)[] = [];
+  constructor(private readonly maximum: number) {}
+  get running() {
+    return this.active;
+  }
+  get queued() {
+    return this.waiting.length;
+  }
+  acquire(signal: AbortSignal): Promise<() => void> {
+    return new Promise((resolve, reject) => {
+      const abort = () => {
+        const index = this.waiting.indexOf(start);
+        if (index >= 0) this.waiting.splice(index, 1);
+        reject(
+          new RemoteError(409, "TURN_CANCELLED", "Queued execution was cancelled."),
+        );
+      };
+      const start = () => {
+        signal.removeEventListener("abort", abort);
+        if (signal.aborted) {
+          abort();
+          return;
+        }
+        this.active++;
+        let released = false;
+        resolve(() => {
+          if (released) return;
+          released = true;
+          this.active--;
+          this.waiting.shift()?.();
+        });
+      };
+      if (signal.aborted) {
+        abort();
+        return;
+      }
+      if (this.active < this.maximum) start();
+      else {
+        this.waiting.push(start);
+        signal.addEventListener("abort", abort, { once: true });
+      }
+    });
+  }
+}