tokenmaxxing 1.7.0 → 1.8.0

package/src/lib/relay/markers.ts

@@ -0,0 +1,148 @@
+// Additive turn-done and permission-needed markers under relayDir.
+// Never writes into respawn/.
+
+import { existsSync, mkdirSync, readFileSync, rmSync, readdirSync } from "node:fs";
+import { z } from "zod";
+import { writeFileAtomic } from "../atomic.ts";
+import {
+  decisionPath,
+  pendingRequestPath,
+  relayDecisionsDir,
+  relayPendingDir,
+  relayTurnDoneDir,
+  turnDonePath,
+} from "./registry.ts";
+
+export const TurnDoneMarkerSchema = z.object({
+  sessionId: z.uuid(),
+  ts: z.number().int().nonnegative(),
+  source: z.enum(["claude-stop", "codex-stop", "test"]).default("claude-stop"),
+});
+export type TurnDoneMarker = z.infer<typeof TurnDoneMarkerSchema>;
+
+export const PendingRequestSchema = z.object({
+  requestId: z.string().min(1),
+  sessionId: z.uuid(),
+  summary: z.string(),
+  detail: z.string(),
+  ts: z.number().int().nonnegative(),
+});
+export type PendingRequest = z.infer<typeof PendingRequestSchema>;
+
+export const DecisionSchema = z.object({
+  requestId: z.string().min(1),
+  sessionId: z.uuid(),
+  approve: z.boolean(),
+  ts: z.number().int().nonnegative(),
+});
+export type Decision = z.infer<typeof DecisionSchema>;
+
+/** Write a turn-done marker for a relay session. Additive; never touches respawn/. */
+export function writeTurnDoneMarker(input: {
+  sessionId: string;
+  source?: TurnDoneMarker["source"];
+  now?: number;
+}): void {
+  mkdirSync(relayTurnDoneDir(), { recursive: true });
+  const payload = TurnDoneMarkerSchema.parse({
+    sessionId: input.sessionId,
+    ts: input.now ?? Date.now(),
+    source: input.source ?? "claude-stop",
+  });
+  writeFileAtomic(turnDonePath({ sessionId: input.sessionId }), JSON.stringify(payload) + "\n");
+}
+
+export function readTurnDoneMarker(input: { sessionId: string }): TurnDoneMarker | null {
+  const path = turnDonePath(input);
+  if (!existsSync(path)) return null;
+  return TurnDoneMarkerSchema.parse(JSON.parse(readFileSync(path, "utf8")));
+}
+
+export function clearTurnDoneMarker(input: { sessionId: string }): void {
+  rmSync(turnDonePath(input), { force: true });
+}
+
+export function writePendingRequest(input: {
+  sessionId: string;
+  requestId: string;
+  summary: string;
+  detail: string;
+  now?: number;
+}): PendingRequest {
+  const payload = PendingRequestSchema.parse({
+    requestId: input.requestId,
+    sessionId: input.sessionId,
+    summary: input.summary,
+    detail: input.detail,
+    ts: input.now ?? Date.now(),
+  });
+  writeFileAtomic(
+    pendingRequestPath({ sessionId: input.sessionId, requestId: input.requestId }),
+    JSON.stringify(payload, null, 2) + "\n",
+  );
+  return payload;
+}
+
+export function readPendingRequest(input: { sessionId: string; requestId: string }): PendingRequest | null {
+  const path = pendingRequestPath(input);
+  if (!existsSync(path)) return null;
+  return PendingRequestSchema.parse(JSON.parse(readFileSync(path, "utf8")));
+}
+
+export function listPendingRequests(input: { sessionId: string }): PendingRequest[] {
+  const dir = `${relayPendingDir()}/${input.sessionId}`;
+  if (!existsSync(dir)) return [];
+  const out: PendingRequest[] = [];
+  for (const name of readdirSync(dir)) {
+    if (!name.endsWith(".json")) continue;
+    try {
+      out.push(PendingRequestSchema.parse(JSON.parse(readFileSync(`${dir}/${name}`, "utf8"))));
+    } catch {
+      // skip
+    }
+  }
+  return out.sort((a, b) => a.ts - b.ts);
+}
+
+export function clearPendingRequest(input: { sessionId: string; requestId: string }): void {
+  rmSync(pendingRequestPath(input), { force: true });
+}
+
+export function writeDecision(input: {
+  sessionId: string;
+  requestId: string;
+  approve: boolean;
+  now?: number;
+}): Decision {
+  mkdirSync(`${relayDecisionsDir()}/${input.sessionId}`, { recursive: true });
+  const payload = DecisionSchema.parse({
+    requestId: input.requestId,
+    sessionId: input.sessionId,
+    approve: input.approve,
+    ts: input.now ?? Date.now(),
+  });
+  writeFileAtomic(
+    decisionPath({ sessionId: input.sessionId, requestId: input.requestId }),
+    JSON.stringify(payload, null, 2) + "\n",
+  );
+  return payload;
+}
+
+export function readDecision(input: { sessionId: string; requestId: string }): Decision | null {
+  const path = decisionPath(input);
+  if (!existsSync(path)) return null;
+  return DecisionSchema.parse(JSON.parse(readFileSync(path, "utf8")));
+}
+
+export function clearDecision(input: { sessionId: string; requestId: string }): void {
+  rmSync(decisionPath(input), { force: true });
+}
+
+/** Clear all marker artifacts for a session (destroy/gc). Does not touch respawn/. */
+export function clearSessionMarkers(input: { sessionId: string }): void {
+  clearTurnDoneMarker(input);
+  const pendingDir = `${relayPendingDir()}/${input.sessionId}`;
+  const decisionsDir = `${relayDecisionsDir()}/${input.sessionId}`;
+  rmSync(pendingDir, { recursive: true, force: true });
+  rmSync(decisionsDir, { recursive: true, force: true });
+}

package/src/lib/relay/modes.ts

@@ -0,0 +1,82 @@
+// Claude Code permission-mode vocabulary for the relay worker, plus the Codex
+// sandbox / ask-for-approval mapping. Host terms only: never invent alternate
+// security labels. `manual` aliases Claude's `default` (≥2.1.200 UI name).
+
+import { z } from "zod";
+
+export const ClaudePermissionModes = [
+  "default",
+  "acceptEdits",
+  "plan",
+  "auto",
+  "dontAsk",
+  "bypassPermissions",
+] as const;
+
+export const ClaudePermissionModeSchema = z.enum(ClaudePermissionModes);
+export type ClaudePermissionMode = z.infer<typeof ClaudePermissionModeSchema>;
+
+const AliasSchema = z.enum(["manual", "yolo", "dangerous"]);
+
+/** Parse a host/CLI permission-mode token into a Claude mode. */
+export function parsePermissionMode(input: { raw: string }): ClaudePermissionMode {
+  const trimmed = input.raw.trim();
+  const alias = AliasSchema.safeParse(trimmed);
+  if (alias.success) {
+    if (alias.data === "manual") return "default";
+    return "bypassPermissions";
+  }
+  return ClaudePermissionModeSchema.parse(trimmed);
+}
+
+export function tryParsePermissionMode(input: { raw: string }): ClaudePermissionMode | null {
+  try {
+    return parsePermissionMode(input);
+  } catch {
+    return null;
+  }
+}
+
+export type CodexAskForApproval = "untrusted" | "on-failure" | "on-request" | "never";
+
+export type CodexSpawnFlags = {
+  sandbox: "read-only" | "workspace-write" | "danger-full-access";
+  askForApproval: CodexAskForApproval;
+};
+
+/** Map a Claude permission-mode name onto Codex CLI flags. */
+export function codexFlagsForMode(input: { mode: ClaudePermissionMode }): CodexSpawnFlags {
+  switch (input.mode) {
+    case "plan":
+    case "default":
+      return { sandbox: "read-only", askForApproval: "on-request" };
+    case "acceptEdits":
+      return { sandbox: "workspace-write", askForApproval: "on-request" };
+    case "auto":
+      return { sandbox: "workspace-write", askForApproval: "on-request" };
+    case "dontAsk":
+      return { sandbox: "read-only", askForApproval: "never" };
+    case "bypassPermissions":
+      return { sandbox: "danger-full-access", askForApproval: "never" };
+  }
+}
+
+/** Claude argv fragment for a permission mode (includes allow-dangerously when needed). */
+export function claudeArgvForMode(input: { mode: ClaudePermissionMode }): string[] {
+  const args = ["--permission-mode", input.mode];
+  if (input.mode === "bypassPermissions") {
+    args.push("--dangerously-skip-permissions");
+  }
+  return args;
+}
+
+/** Codex argv fragment for a Claude-named mode. */
+export function codexArgvForMode(input: { mode: ClaudePermissionMode }): string[] {
+  const flags = codexFlagsForMode(input);
+  return ["--sandbox", flags.sandbox, "--ask-for-approval", flags.askForApproval];
+}
+
+/** Under bypassPermissions, worker permission pings must not surface to main. */
+export function permissionPingsEnabled(input: { mode: ClaudePermissionMode }): boolean {
+  return input.mode !== "bypassPermissions";
+}

package/src/lib/relay/protocol.ts

@@ -0,0 +1,61 @@
+// Shared stdout contract for cheap host relay agents.
+
+import type { ClaudePermissionMode } from "./modes.ts";
+
+export type TurnOutput = {
+  sessionId: string;
+  permissionMode: ClaudePermissionMode;
+  kind: "turn-done";
+  text: string;
+};
+
+export type PermissionNeededOutput = {
+  sessionId: string;
+  permissionMode: ClaudePermissionMode;
+  kind: "permission-needed";
+  requestId: string;
+  summary: string;
+  detail: string;
+};
+
+export type RelayStdout = TurnOutput | PermissionNeededOutput;
+
+export function formatRelayStdout(input: { payload: RelayStdout }): string {
+  const p = input.payload;
+  const lines = [
+    `session: ${p.sessionId}`,
+    `permission-mode: ${p.permissionMode}`,
+  ];
+  if (p.kind === "permission-needed") {
+    lines.push(`permission-needed: ${p.requestId}`);
+    lines.push(`summary: ${p.summary}`);
+    lines.push(`detail: ${p.detail}`);
+    lines.push(`session: ${p.sessionId}`);
+    lines.push(`permission-mode: ${p.permissionMode}`);
+  } else if (p.text.trim() !== "") {
+    lines.push(p.text.replace(/\s+$/, ""));
+  }
+  return lines.join("\n") + "\n";
+}
+
+export function parseRelayStdout(input: { text: string }): {
+  sessionId: string | null;
+  permissionMode: string | null;
+  requestId: string | null;
+  summary: string | null;
+  detail: string | null;
+} {
+  let sessionId: string | null = null;
+  let permissionMode: string | null = null;
+  let requestId: string | null = null;
+  let summary: string | null = null;
+  let detail: string | null = null;
+  for (const line of input.text.split("\n")) {
+    if (line.startsWith("session: ")) sessionId = line.slice("session: ".length).trim();
+    else if (line.startsWith("permission-mode: ")) permissionMode = line.slice("permission-mode: ".length).trim();
+    else if (line.startsWith("permission-needed: ")) requestId = line.slice("permission-needed: ".length).trim();
+    else if (line.startsWith("summary: ")) summary = line.slice("summary: ".length);
+    else if (line.startsWith("detail: ")) detail = line.slice("detail: ".length);
+  }
+  return { sessionId, permissionMode, requestId, summary, detail };
+}

package/src/lib/relay/registry.ts

@@ -0,0 +1,175 @@
+// Per-session registry under $TOKENMAXXING_HOME/relay/sessions/<id>.json.
+// Per-session flock only (high churn); never a global relay lock for turns.
+
+import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { z } from "zod";
+import { paths } from "../paths.ts";
+import { writeFileAtomic } from "../atomic.ts";
+import { withLock } from "../lock.ts";
+import { ClaudePermissionModeSchema, type ClaudePermissionMode } from "./modes.ts";
+import { loadRelayConfig, type RelayWorker } from "./config.ts";
+
+export const RelaySessionStateSchema = z.enum([
+  "idle",
+  "running",
+  "permission-needed",
+  "destroyed",
+]);
+export type RelaySessionState = z.infer<typeof RelaySessionStateSchema>;
+
+export const RelayRegistryEntrySchema = z.object({
+  sessionId: z.uuid(),
+  tmuxName: z.string().min(1),
+  worker: z.enum(["claude", "codex"]),
+  permissionMode: ClaudePermissionModeSchema,
+  cwd: z.string().min(1),
+  state: RelaySessionStateSchema,
+  createdAt: z.number().int().nonnegative(),
+  lastActiveAt: z.number().int().nonnegative(),
+  pendingRequestId: z.string().min(1).optional(),
+});
+export type RelayRegistryEntry = z.infer<typeof RelayRegistryEntrySchema>;
+
+export function relaySessionsDir(): string {
+  return join(paths.relayDir, "sessions");
+}
+
+export function relayLocksDir(): string {
+  return join(paths.relayDir, "locks");
+}
+
+export function relayTurnDoneDir(): string {
+  return join(paths.relayDir, "turn-done");
+}
+
+export function relayPendingDir(): string {
+  return join(paths.relayDir, "pending");
+}
+
+export function relayDecisionsDir(): string {
+  return join(paths.relayDir, "decisions");
+}
+
+export function sessionEntryPath(input: { sessionId: string }): string {
+  return join(relaySessionsDir(), `${input.sessionId}.json`);
+}
+
+export function sessionLockPath(input: { sessionId: string }): string {
+  return join(relayLocksDir(), input.sessionId);
+}
+
+export function turnDonePath(input: { sessionId: string }): string {
+  return join(relayTurnDoneDir(), input.sessionId);
+}
+
+export function pendingRequestPath(input: { sessionId: string; requestId: string }): string {
+  return join(relayPendingDir(), input.sessionId, `${input.requestId}.json`);
+}
+
+export function decisionPath(input: { sessionId: string; requestId: string }): string {
+  return join(relayDecisionsDir(), input.sessionId, `${input.requestId}.json`);
+}
+
+export function tmuxNameFor(input: { sessionId: string; prefix?: string }): string {
+  const prefix = input.prefix ?? loadRelayConfig().sessionPrefix;
+  return `${prefix}${input.sessionId}`;
+}
+
+export function newSessionId(): string {
+  return crypto.randomUUID();
+}
+
+export function readEntry(input: { sessionId: string }): RelayRegistryEntry | null {
+  const path = sessionEntryPath(input);
+  if (!existsSync(path)) return null;
+  return RelayRegistryEntrySchema.parse(JSON.parse(readFileSync(path, "utf8")));
+}
+
+export function writeEntry(input: { entry: RelayRegistryEntry }): void {
+  mkdirSync(relaySessionsDir(), { recursive: true });
+  writeFileAtomic(sessionEntryPath({ sessionId: input.entry.sessionId }), JSON.stringify(input.entry, null, 2) + "\n");
+}
+
+export function deleteEntry(input: { sessionId: string }): void {
+  rmSync(sessionEntryPath(input), { force: true });
+}
+
+export async function withSessionLock<T>(input: {
+  sessionId: string;
+  fn: () => Promise<T> | T;
+}): Promise<T> {
+  mkdirSync(relayLocksDir(), { recursive: true });
+  return withLock(sessionLockPath({ sessionId: input.sessionId }), input.fn);
+}
+
+export function listEntries(): RelayRegistryEntry[] {
+  const dir = relaySessionsDir();
+  if (!existsSync(dir)) return [];
+  const out: RelayRegistryEntry[] = [];
+  for (const name of readdirSync(dir)) {
+    if (!name.endsWith(".json")) continue;
+    const path = join(dir, name);
+    try {
+      out.push(RelayRegistryEntrySchema.parse(JSON.parse(readFileSync(path, "utf8"))));
+    } catch {
+      // skip corrupt; gc can reap
+    }
+  }
+  return out;
+}
+
+export function createEntry(input: {
+  sessionId: string;
+  worker: RelayWorker;
+  permissionMode: ClaudePermissionMode;
+  cwd: string;
+  now?: number;
+}): RelayRegistryEntry {
+  const now = input.now ?? Date.now();
+  const entry = RelayRegistryEntrySchema.parse({
+    sessionId: input.sessionId,
+    tmuxName: tmuxNameFor({ sessionId: input.sessionId }),
+    worker: input.worker,
+    permissionMode: input.permissionMode,
+    cwd: input.cwd,
+    state: "idle",
+    createdAt: now,
+    lastActiveAt: now,
+  });
+  writeEntry({ entry });
+  return entry;
+}
+
+export function touchEntry(input: {
+  sessionId: string;
+  state?: RelaySessionState;
+  permissionMode?: ClaudePermissionMode;
+  pendingRequestId?: string | null;
+  now?: number;
+}): RelayRegistryEntry {
+  const prev = readEntry({ sessionId: input.sessionId });
+  if (prev == null) throw new Error(`relay session not found: ${input.sessionId}`);
+  const next = RelayRegistryEntrySchema.parse({
+    ...prev,
+    state: input.state ?? prev.state,
+    permissionMode: input.permissionMode ?? prev.permissionMode,
+    lastActiveAt: input.now ?? Date.now(),
+    pendingRequestId: input.pendingRequestId === null
+      ? undefined
+      : (input.pendingRequestId ?? prev.pendingRequestId),
+  });
+  writeEntry({ entry: next });
+  return next;
+}
+
+/** True when a registry entry exists for this relay session id. */
+export function registryHas(input: { sessionId: string }): boolean {
+  return readEntry(input) != null;
+}
+
+export function entryMtimeMs(input: { sessionId: string }): number | null {
+  const path = sessionEntryPath(input);
+  if (!existsSync(path)) return null;
+  return statSync(path).mtimeMs;
+}

package/src/lib/relay/tmux.ts

@@ -0,0 +1,109 @@
+// Thin tmux wrapper. Exact session names only; never pattern-kill. Injectable
+// for hermetic tests that must not require a real tmux server or workers.
+
+import { z } from "zod";
+
+export type TmuxBackend = {
+  hasSession: (input: { name: string }) => boolean;
+  newSession: (input: { name: string; cwd: string; command: string }) => void;
+  killSession: (input: { name: string }) => void;
+  sendKeys: (input: { name: string; text: string; enter?: boolean }) => void;
+  capturePane: (input: { name: string }) => string;
+  listSessions: () => string[];
+};
+
+function runTmux(args: string[]): { ok: boolean; stdout: string; stderr: string; code: number } {
+  const res = Bun.spawnSync(["tmux", ...args], {
+    stdout: "pipe",
+    stderr: "pipe",
+    env: process.env,
+  });
+  return {
+    ok: res.exitCode === 0,
+    code: res.exitCode ?? 1,
+    stdout: res.stdout.toString(),
+    stderr: res.stderr.toString(),
+  };
+}
+
+export const liveTmux: TmuxBackend = {
+  hasSession: ({ name }) => runTmux(["has-session", "-t", name]).ok,
+  newSession: ({ name, cwd, command }) => {
+    const res = runTmux(["new-session", "-d", "-s", name, "-c", cwd, command]);
+    if (!res.ok) throw new Error(`tmux new-session failed for ${name}: ${res.stderr.trim() || res.stdout.trim()}`);
+  },
+  killSession: ({ name }) => {
+    // Exact name only. Missing session is success for destroy/gc idempotence.
+    runTmux(["kill-session", "-t", name]);
+  },
+  sendKeys: ({ name, text, enter = true }) => {
+    const res = runTmux(["send-keys", "-t", name, "-l", "--", text]);
+    if (!res.ok) throw new Error(`tmux send-keys failed for ${name}: ${res.stderr.trim()}`);
+    if (enter) {
+      const enterRes = runTmux(["send-keys", "-t", name, "Enter"]);
+      if (!enterRes.ok) throw new Error(`tmux send-keys Enter failed for ${name}: ${enterRes.stderr.trim()}`);
+    }
+  },
+  capturePane: ({ name }) => {
+    const res = runTmux(["capture-pane", "-p", "-t", name, "-S", "-200"]);
+    if (!res.ok) return "";
+    return res.stdout;
+  },
+  listSessions: () => {
+    const res = runTmux(["list-sessions", "-F", "#{session_name}"]);
+    if (!res.ok) return [];
+    return res.stdout.split("\n").map((s) => s.trim()).filter((s) => s.length > 0);
+  },
+};
+
+let backend: TmuxBackend = liveTmux;
+
+export function getTmux(): TmuxBackend {
+  return backend;
+}
+
+/** Test-only: replace the tmux backend. */
+export function setTmuxBackend(input: { backend: TmuxBackend }): void {
+  backend = input.backend;
+}
+
+export function resetTmuxBackend(): void {
+  backend = liveTmux;
+}
+
+const MemorySessionSchema = z.object({
+  name: z.string(),
+  cwd: z.string(),
+  command: stringOrEmpty(),
+  keys: z.array(z.string()).default([]),
+  pane: z.string().default(""),
+});
+
+function stringOrEmpty() {
+  return z.string();
+}
+
+/** In-memory tmux for hermetic tests. */
+export function createMemoryTmux(): TmuxBackend & { sessions: Map<string, z.infer<typeof MemorySessionSchema>> } {
+  const sessions = new Map<string, z.infer<typeof MemorySessionSchema>>();
+  const api: TmuxBackend & { sessions: typeof sessions } = {
+    sessions,
+    hasSession: ({ name }) => sessions.has(name),
+    newSession: ({ name, cwd, command }) => {
+      if (sessions.has(name)) throw new Error(`tmux session already exists: ${name}`);
+      sessions.set(name, MemorySessionSchema.parse({ name, cwd, command, keys: [], pane: "" }));
+    },
+    killSession: ({ name }) => {
+      sessions.delete(name);
+    },
+    sendKeys: ({ name, text, enter = true }) => {
+      const s = sessions.get(name);
+      if (!s) throw new Error(`no tmux session: ${name}`);
+      s.keys.push(enter ? `${text}\n` : text);
+      s.pane += enter ? `${text}\n` : text;
+    },
+    capturePane: ({ name }) => sessions.get(name)?.pane ?? "",
+    listSessions: () => [...sessions.keys()],
+  };
+  return api;
+}