@openparachute/agent 0.1.1 → 0.2.0

package/src/spawn-deps.ts

@@ -0,0 +1,166 @@
+/**
+ * Resolve the REAL {@link SpawnAgentBaseDeps} from the environment — the hub origin,
+ * the manager bearer (`~/.parachute/operator.token`), the channel/vault URLs, the
+ * sessions dir, the read-only runtime binds, and the per-channel Claude-credential +
+ * env resolvers.
+ *
+ * This is the one place the spawn side-effects get their concrete wiring. The
+ * PROGRAMMATIC backend reads its slice of these for each `claude -p` turn
+ * (`createDefaultProgrammaticRegistry`, daemon.ts). The deps deliberately carry NO
+ * tmux launcher — the interactive (tmux) backend was retired 2026-06-19 (design
+ * 2026-06-19-retire-interactive-backend.md); its parked spawner
+ * (`src/_parked/interactive-spawn.ts`) wires its own `realTmuxLauncher` if ever
+ * revived.
+ */
+
+import { existsSync, readFileSync, realpathSync } from "node:fs";
+import { homedir } from "node:os";
+import { resolve, join, dirname } from "node:path";
+import { type SpawnAgentBaseDeps } from "./spawn-agent.ts";
+import { resolveClaudeCredential, resolveChannelEnv } from "./credentials.ts";
+import { defaultStateDir } from "./registry.ts";
+import { agentEnv } from "./env-compat.ts";
+import { getHubOrigin } from "./hub-jwt.ts";
+
+const DEFAULT_CHANNEL_PORT = 1941;
+const DEFAULT_VAULT_URL = "http://127.0.0.1:1940";
+
+/**
+ * No operator token on disk — the manager bearer the hub attenuates child mints
+ * against is missing, so no session can be launched. Carries an actionable
+ * message; callers map it to a clean CLI error or a 503 JSON body.
+ */
+export class SpawnDepsError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "SpawnDepsError";
+  }
+}
+
+/** Base for `operator.token` — `$PARACHUTE_HOME` else `~/.parachute`. */
+function parachuteHome(): string {
+  return process.env.PARACHUTE_HOME ?? resolve(homedir(), ".parachute");
+}
+
+/**
+ * The spawn-manager's OWN bearer — `~/.parachute/operator.token`, the local
+ * operator credential the hub attenuates child mints against (the same file
+ * vault's `readOperatorToken` reads). Returns null when absent/empty.
+ */
+function readManagerBearer(): string | null {
+  try {
+    const path = resolve(parachuteHome(), "operator.token");
+    if (!existsSync(path)) return null;
+    const raw = readFileSync(path, "utf-8").trim();
+    return raw.length > 0 ? raw : null;
+  } catch {
+    return null;
+  }
+}
+
+/** Default channel daemon base URL: PARACHUTE_AGENT_URL, else loopback:<port>. */
+function resolveChannelUrl(): string {
+  const explicit = agentEnv("URL")?.replace(/\/$/, "");
+  if (explicit) return explicit;
+  const port = parseInt(agentEnv("PORT") ?? "", 10) || DEFAULT_CHANNEL_PORT;
+  return `http://127.0.0.1:${port}`;
+}
+
+/**
+ * Resolve the `claude` binary to an ABSOLUTE path and the read binds the sandbox
+ * needs to actually exec it.
+ *
+ * Why this matters: the scoped-read policy DENIES the whole home tree (`/Users`)
+ * and re-allows only declared binds (mounts.ts §4.5). The claude CLI commonly
+ * installs UNDER the home tree (`~/.local/bin/claude` → `~/.local/share/claude/
+ * versions/<v>`), so without binding it the sandboxed launch fails with
+ * `claude: command not found` and the tmux session dies instantly. Relying on
+ * PATH alone is also fragile — the supervised daemon's PATH may differ from a
+ * login shell. So we resolve the absolute path (via the daemon's PATH) and bind
+ * the symlink + its realpath + the install dir read-only.
+ *
+ * Returns `null` when `claude` isn't found on the daemon's PATH — the caller
+ * falls back to the bare `"claude"` (PATH lookup at run) and binds nothing, which
+ * is correct when claude lives OUTSIDE the home tree (e.g. `/opt/homebrew/bin`,
+ * already readable) and the only honest option when it can't be located at all.
+ */
+function resolveClaudeBin(): { bin: string; reads: string[] } | null {
+  const sym = Bun.which("claude");
+  if (!sym) return null;
+  const reads = new Set<string>([sym]);
+  try {
+    const real = realpathSync(sym);
+    reads.add(real);
+    // The install dir + its parent — a versioned install keeps sibling files at
+    // `…/versions/<v>` under `…/share/claude`; binding both covers what the
+    // binary loads at runtime. Outside the home tree these are no-ops (already
+    // readable), so this is safe regardless of install layout.
+    reads.add(dirname(real));
+    reads.add(dirname(dirname(real)));
+  } catch {
+    // realpath failed (broken symlink?) — bind just the symlink we found.
+  }
+  return { bin: sym, reads: [...reads] };
+}
+
+/** Absolute path to the operator token file (for error messages). */
+export function operatorTokenPath(): string {
+  return resolve(parachuteHome(), "operator.token");
+}
+
+/**
+ * Build the real {@link SpawnAgentBaseDeps} from the environment. Throws
+ * {@link SpawnDepsError} when the operator token is missing (no manager bearer →
+ * no mint → no launch). Pure aside from reading the env + the token file.
+ */
+export function resolveSpawnDeps(): SpawnAgentBaseDeps {
+  const managerBearer = readManagerBearer();
+  if (!managerBearer) {
+    throw new SpawnDepsError(
+      `no operator token at ${operatorTokenPath()} — the manager bearer the hub attenuates ` +
+        `child mints against. Log in / provision the hub so the operator token exists ` +
+        `(it's what \`parachute auth mint-token\` uses), then retry.`,
+    );
+  }
+
+  const stateDir = defaultStateDir();
+  const sessionsDir = join(stateDir, "sessions");
+  const vaultUrl = process.env.PARACHUTE_VAULT_URL?.replace(/\/$/, "") || DEFAULT_VAULT_URL;
+
+  // Resolve the claude binary + the read binds it needs inside the sandbox (the
+  // home tree is denied, and claude commonly lives under it). null → fall back to
+  // bare "claude" on PATH (correct when claude is outside the home tree).
+  const claude = resolveClaudeBin();
+
+  // Read binds the sandboxed `claude` needs in CONFINED (scoped-read) mode: the
+  // claude BINARY + its install dir (commonly under the home tree, which confined
+  // mode denies). The agent's config/onboarding now lives in its own per-session
+  // HOME (seedAgentHome) under the workspace — re-allowed there — so we no longer
+  // bind (or expose) the operator's real ~/.claude. In TRUSTED mode reads are
+  // broad and these binds are harmless no-ops. System paths (/usr,/lib,/opt) stay
+  // readable; the per-session workspace (rw) is added by spawnAgent.
+  const runtimeReadOnly = [...(claude?.reads ?? [])];
+
+  return {
+    hubOrigin: getHubOrigin(),
+    managerBearer,
+    channelUrl: resolveChannelUrl(),
+    vaultUrl,
+    sessionsDir,
+    runtimeReadOnly,
+    // The real per-channel Claude OAuth resolver (channel override ?? default ?? throw).
+    resolveClaudeToken: (channel: string) => resolveClaudeCredential(channel, stateDir),
+    // The real per-channel env resolver (GH_TOKEN/CLOUDFLARE_*/… — { default, channel } merged).
+    resolveChannelEnv: (channel: string) => resolveChannelEnv(channel, stateDir),
+    // Absolute claude path so the sandbox doesn't depend on PATH resolution at run
+    // (and matches the bound binary). Omitted → spawnAgent defaults to "claude".
+    ...(claude ? { claudeBin: claude.bin } : {}),
+    // sandboxEngine omitted → spawnAgent's `new Sandbox()` uses the real, pinned,
+    // library-linked engine.
+  };
+}
+
+/** The sessions dir the agent ops enumerate workspaces under. */
+export function sessionsDir(): string {
+  return join(defaultStateDir(), "sessions");
+}

package/src/telegram/api.ts

@@ -0,0 +1,153 @@
+/**
+ * Minimal Telegram Bot API client. Only the methods we actually use.
+ */
+
+export interface TelegramCallbackQuery {
+  id: string;
+  from: { id: number; first_name: string; username?: string; is_bot: boolean };
+  message?: TelegramMessage;
+  data?: string;
+}
+
+export interface TelegramUpdate {
+  update_id: number;
+  message?: TelegramMessage;
+  callback_query?: TelegramCallbackQuery;
+}
+
+export interface TelegramMessage {
+  message_id: number;
+  chat: { id: number; type: string; title?: string };
+  from?: { id: number; first_name: string; username?: string; is_bot: boolean };
+  date: number;
+  text?: string;
+  voice?: { file_id: string; file_unique_id: string; duration: number; mime_type?: string; file_size?: number };
+  audio?: { file_id: string; file_unique_id: string; duration: number; mime_type?: string; file_size?: number };
+  document?: { file_id: string; file_unique_id: string; file_name?: string; mime_type?: string; file_size?: number };
+  photo?: Array<{ file_id: string; file_unique_id: string; width: number; height: number; file_size?: number }>;
+  caption?: string;
+}
+
+export class TelegramApi {
+  private base: string;
+
+  constructor(private token: string) {
+    this.base = `https://api.telegram.org/bot${token}`;
+  }
+
+  async getUpdates(offset?: number, timeout = 30): Promise<TelegramUpdate[]> {
+    const params = new URLSearchParams({ timeout: String(timeout) });
+    if (offset !== undefined) params.set("offset", String(offset));
+    const res = await fetch(`${this.base}/getUpdates?${params}`);
+    if (!res.ok) throw new Error(`getUpdates ${res.status}: ${await res.text()}`);
+    const json = (await res.json()) as { ok: boolean; result: TelegramUpdate[] };
+    if (!json.ok) throw new Error(`getUpdates not ok: ${JSON.stringify(json)}`);
+    return json.result;
+  }
+
+  async sendMessage(chatId: number | string, text: string, opts?: { reply_to_message_id?: number; reply_markup?: unknown }): Promise<number> {
+    const body: Record<string, unknown> = { chat_id: chatId, text };
+    if (opts?.reply_to_message_id) body.reply_to_message_id = opts.reply_to_message_id;
+    if (opts?.reply_markup) body.reply_markup = opts.reply_markup;
+    const res = await fetch(`${this.base}/sendMessage`, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify(body),
+    });
+    if (!res.ok) throw new Error(`sendMessage ${res.status}: ${await res.text()}`);
+    const json = (await res.json()) as { ok: boolean; result: { message_id: number } };
+    return json.result.message_id;
+  }
+
+  async sendDocument(chatId: number | string, filePath: string, caption?: string): Promise<number> {
+    const form = new FormData();
+    form.append("chat_id", String(chatId));
+    const file = Bun.file(filePath);
+    form.append("document", file);
+    if (caption) form.append("caption", caption);
+    const res = await fetch(`${this.base}/sendDocument`, { method: "POST", body: form });
+    if (!res.ok) throw new Error(`sendDocument ${res.status}: ${await res.text()}`);
+    const json = (await res.json()) as { ok: boolean; result: { message_id: number } };
+    return json.result.message_id;
+  }
+
+  async sendPhoto(chatId: number | string, filePath: string, caption?: string): Promise<number> {
+    const form = new FormData();
+    form.append("chat_id", String(chatId));
+    const file = Bun.file(filePath);
+    form.append("photo", file);
+    if (caption) form.append("caption", caption);
+    const res = await fetch(`${this.base}/sendPhoto`, { method: "POST", body: form });
+    if (!res.ok) throw new Error(`sendPhoto ${res.status}: ${await res.text()}`);
+    const json = (await res.json()) as { ok: boolean; result: { message_id: number } };
+    return json.result.message_id;
+  }
+
+  async sendVoice(chatId: number | string, filePath: string, caption?: string): Promise<number> {
+    const form = new FormData();
+    form.append("chat_id", String(chatId));
+    const file = Bun.file(filePath);
+    form.append("voice", file);
+    if (caption) form.append("caption", caption);
+    const res = await fetch(`${this.base}/sendVoice`, { method: "POST", body: form });
+    if (!res.ok) throw new Error(`sendVoice ${res.status}: ${await res.text()}`);
+    const json = (await res.json()) as { ok: boolean; result: { message_id: number } };
+    return json.result.message_id;
+  }
+
+  async setMessageReaction(chatId: number | string, messageId: number, emoji: string): Promise<void> {
+    const res = await fetch(`${this.base}/setMessageReaction`, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({
+        chat_id: chatId,
+        message_id: messageId,
+        reaction: [{ type: "emoji", emoji }],
+      }),
+    });
+    if (!res.ok) throw new Error(`setMessageReaction ${res.status}: ${await res.text()}`);
+  }
+
+  async editMessageText(chatId: number | string, messageId: number, text: string, opts?: { reply_markup?: unknown }): Promise<void> {
+    const body: Record<string, unknown> = { chat_id: chatId, message_id: messageId, text };
+    if (opts?.reply_markup) body.reply_markup = opts.reply_markup;
+    const res = await fetch(`${this.base}/editMessageText`, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify(body),
+    });
+    if (!res.ok) throw new Error(`editMessageText ${res.status}: ${await res.text()}`);
+  }
+
+  async answerCallbackQuery(callbackQueryId: string, opts?: { text?: string }): Promise<void> {
+    const body: Record<string, unknown> = { callback_query_id: callbackQueryId };
+    if (opts?.text) body.text = opts.text;
+    const res = await fetch(`${this.base}/answerCallbackQuery`, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify(body),
+    });
+    if (!res.ok) throw new Error(`answerCallbackQuery ${res.status}: ${await res.text()}`);
+  }
+
+  async getFile(fileId: string): Promise<{ file_path: string }> {
+    const res = await fetch(`${this.base}/getFile?file_id=${fileId}`);
+    if (!res.ok) throw new Error(`getFile ${res.status}: ${await res.text()}`);
+    const json = (await res.json()) as { ok: boolean; result: { file_path: string } };
+    return json.result;
+  }
+
+  async downloadFile(filePath: string): Promise<Buffer> {
+    const url = `https://api.telegram.org/file/bot${this.token}/${filePath}`;
+    const res = await fetch(url);
+    if (!res.ok) throw new Error(`downloadFile ${res.status}`);
+    return Buffer.from(await res.arrayBuffer());
+  }
+
+  async getMe(): Promise<{ username: string; first_name: string }> {
+    const res = await fetch(`${this.base}/getMe`);
+    if (!res.ok) throw new Error(`getMe ${res.status}: ${await res.text()}`);
+    const json = (await res.json()) as { ok: boolean; result: { username: string; first_name: string } };
+    return json.result;
+  }
+}

package/src/terminal-assets.test.ts

@@ -0,0 +1,50 @@
+/**
+ * Tests for same-origin terminal asset serving (`src/terminal-assets.ts`) — the
+ * fix for "xterm.js failed to load (CDN blocked?)". Proves the vendored xterm JS +
+ * CSS resolve from the installed packages and serve with the right content-type,
+ * and that an unknown asset name is a clean miss (the daemon 404s it).
+ */
+
+import { describe, test, expect } from "bun:test";
+import { serveTerminalAsset, TERMINAL_ASSET_NAMES } from "./terminal-assets.ts";
+
+describe("serveTerminalAsset", () => {
+  test("serves xterm.js as JavaScript with a real body", async () => {
+    const res = serveTerminalAsset("xterm.js");
+    expect(res).not.toBeNull();
+    expect(res!.status).toBe(200);
+    expect(res!.headers.get("content-type")).toContain("javascript");
+    const body = await res!.text();
+    // The UMD bundle defines the Terminal global — a non-trivial body proves the
+    // file resolved from the package (not an empty/placeholder response).
+    expect(body.length).toBeGreaterThan(1000);
+    expect(body).toContain("Terminal");
+  });
+
+  test("serves xterm.css as CSS", async () => {
+    const res = serveTerminalAsset("xterm.css");
+    expect(res!.status).toBe(200);
+    expect(res!.headers.get("content-type")).toContain("css");
+    expect((await res!.text()).length).toBeGreaterThan(100);
+  });
+
+  test("serves addon-fit.js", async () => {
+    const res = serveTerminalAsset("addon-fit.js");
+    expect(res!.status).toBe(200);
+    expect(res!.headers.get("content-type")).toContain("javascript");
+  });
+
+  test("sets an immutable cache header (version-pinned)", () => {
+    const res = serveTerminalAsset("xterm.js");
+    expect(res!.headers.get("cache-control")).toContain("immutable");
+  });
+
+  test("an unknown asset name → null (caller 404s)", () => {
+    expect(serveTerminalAsset("evil.js")).toBeNull();
+    expect(serveTerminalAsset("../../etc/passwd")).toBeNull();
+  });
+
+  test("the known names are the three xterm assets", () => {
+    expect(TERMINAL_ASSET_NAMES.sort()).toEqual(["addon-fit.js", "xterm.css", "xterm.js"]);
+  });
+});

package/src/terminal-assets.ts

@@ -0,0 +1,79 @@
+/**
+ * Serve the vendored xterm.js assets SAME-ORIGIN (design §5; fixes the "xterm.js
+ * failed to load — CDN blocked?" failure).
+ *
+ * The terminal page originally loaded xterm + the fit addon from a public CDN
+ * (jsdelivr). That breaks whenever the operator's network or the hub's CSP blocks
+ * the CDN — and an operator-only terminal that silently won't load is a
+ * showstopper. So we vendor `@xterm/xterm` + `@xterm/addon-fit` as dependencies
+ * and serve their dist files from the daemon at `/terminal/assets/<file>`: no
+ * third-party origin, no CSP `script-src` widening (the bundle is `'self'`), works
+ * offline / behind strict networks.
+ *
+ * The files are resolved from the installed packages (works under both the
+ * bun-linked checkout and an npm install — they're real deps) and read+cached on
+ * first request. Version-pinned in package.json, so the responses are immutable.
+ */
+
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+
+/** The asset routes the terminal page loads, mapped to package-relative files. */
+interface AssetSpec {
+  /** Package specifier whose dir anchors the file. */
+  pkg: string;
+  /** File path relative to the package root. */
+  rel: string;
+  /** Content-Type to serve. */
+  type: string;
+}
+
+const ASSETS: Record<string, AssetSpec> = {
+  "xterm.js": { pkg: "@xterm/xterm/package.json", rel: "lib/xterm.js", type: "text/javascript; charset=utf-8" },
+  "xterm.css": { pkg: "@xterm/xterm/package.json", rel: "css/xterm.css", type: "text/css; charset=utf-8" },
+  "addon-fit.js": { pkg: "@xterm/addon-fit/package.json", rel: "lib/addon-fit.js", type: "text/javascript; charset=utf-8" },
+};
+
+/** Cache of read file bodies (text — xterm js/css are all text), by asset name. */
+const bodyCache = new Map<string, string>();
+
+/** Resolve an asset's absolute path from its package root (works linked + installed). */
+function assetPath(spec: AssetSpec): string {
+  // Bun.resolveSync resolves the package's own package.json (always exported), and
+  // we join the known dist-relative path — robust to packages whose `exports` map
+  // doesn't expose deep subpaths directly.
+  const pkgRoot = dirname(Bun.resolveSync(spec.pkg, import.meta.dir));
+  return join(pkgRoot, spec.rel);
+}
+
+/**
+ * Serve a terminal asset by name (the segment after `/terminal/assets/`), or
+ * null if the name isn't a known asset (caller 404s). Read-once + cached;
+ * immutable cache headers since the version is pinned.
+ */
+export function serveTerminalAsset(name: string): Response | null {
+  const spec = ASSETS[name];
+  if (!spec) return null;
+  let body = bodyCache.get(name);
+  if (body === undefined) {
+    try {
+      body = readFileSync(assetPath(spec), "utf8");
+    } catch (err) {
+      return new Response(
+        `/* terminal asset "${name}" unavailable: ${(err as Error).message} */`,
+        { status: 500, headers: { "content-type": spec.type } },
+      );
+    }
+    bodyCache.set(name, body);
+  }
+  return new Response(body, {
+    headers: {
+      "content-type": spec.type,
+      // Version-pinned in package.json → safe to cache hard.
+      "cache-control": "public, max-age=31536000, immutable",
+    },
+  });
+}
+
+/** The known asset names (for routing/tests). */
+export const TERMINAL_ASSET_NAMES = Object.keys(ASSETS);