orchestrating 0.1.0

package/README.md

@@ -0,0 +1,58 @@
+# orchestrating
+
+Stream terminal sessions to the [orchestrat.ing](https://orchestrat.ing) dashboard. Monitor and interact with AI coding agents (Claude Code, etc.) from anywhere.
+
+## Install
+
+```bash
+npm i -g orchestrating
+```
+
+**Requirements:** Node.js 18+, Python 3 (for PTY mode)
+
+## Authentication
+
+```bash
+orch login     # Opens browser for authentication
+orch logout    # Clears stored credentials
+```
+
+## Usage
+
+```bash
+# Wrap any command
+orch bash
+orch claude "refactor the auth module"
+
+# With a label
+orch -l "deploy fix" claude "fix the CI pipeline"
+
+# Continue a previous conversation
+orch claude -c "now add tests"
+
+# Auto-approve all permissions (yolo mode)
+orch -y claude "build a website"
+```
+
+## Environment Variables
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `ORC_URL` | WebSocket server URL | `wss://api.orchestrat.ing/ws` |
+| `ORC_TOKEN` | Auth token (overrides stored credentials) | — |
+
+## Local Development
+
+For local development, point to your local server:
+
+```bash
+ORC_URL=ws://localhost:3456/ws AUTH_TOKEN=dev-token-123 orch claude "hello"
+```
+
+## How It Works
+
+`orch` wraps your command in a PTY (or structured JSON mode for supported tools), streams the output over WebSocket to the orchestrat.ing server, and displays it in a web dashboard. You can interact with sessions remotely — send input, approve permissions, and monitor progress from any browser.
+
+## License
+
+MIT

package/bin/orch

@@ -0,0 +1,858 @@
+#!/usr/bin/env node
+
+import os from "os";
+import http from "http";
+import path from "path";
+import readline from "readline";
+import { readFileSync, writeFileSync, mkdirSync, unlinkSync, existsSync } from "fs";
+import { spawn, execSync } from "child_process";
+import { randomUUID } from "crypto";
+import { fileURLToPath } from "url";
+import WebSocket from "ws";
+
+// Load .env from project root (same dir as the server uses)
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const envPath = path.join(__dirname, "..", "..", ".env");
+try {
+  const envContent = readFileSync(envPath, "utf-8");
+  for (const line of envContent.split("\n")) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith("#")) continue;
+    const eqIdx = trimmed.indexOf("=");
+    if (eqIdx === -1) continue;
+    const key = trimmed.slice(0, eqIdx).trim();
+    const val = trimmed.slice(eqIdx + 1).trim();
+    if (!process.env[key]) {
+      process.env[key] = val;
+    }
+  }
+} catch {
+  // No .env file — use env vars directly
+}
+
+// --- Auth credentials ---
+const CONFIG_DIR = path.join(os.homedir(), ".config", "orchestrating");
+const AUTH_FILE = path.join(CONFIG_DIR, "auth.json");
+
+function loadStoredAuth() {
+  try {
+    return JSON.parse(readFileSync(AUTH_FILE, "utf-8"));
+  } catch {
+    return null;
+  }
+}
+
+function saveAuth(data) {
+  mkdirSync(CONFIG_DIR, { recursive: true });
+  writeFileSync(AUTH_FILE, JSON.stringify(data, null, 2) + "\n");
+}
+
+function clearAuth() {
+  try {
+    unlinkSync(AUTH_FILE);
+  } catch {}
+}
+
+function getAuthToken() {
+  // 1. Env var override
+  if (process.env.ORC_TOKEN || process.env.CAST_TOKEN || process.env.AUTH_TOKEN) {
+    return process.env.ORC_TOKEN || process.env.CAST_TOKEN || process.env.AUTH_TOKEN;
+  }
+  // 2. Stored credentials
+  const auth = loadStoredAuth();
+  if (auth && auth.access_token) {
+    // Check expiry — if expired and we have a refresh token, caller should refresh
+    if (auth.expires_at && Date.now() / 1000 > auth.expires_at) {
+      // Token expired — still return it, server will reject and CLI can prompt re-login
+      return auth.access_token;
+    }
+    return auth.access_token;
+  }
+  return "";
+}
+
+// --- Login command ---
+async function handleLogin() {
+  const loginUrl = process.env.ORC_LOGIN_URL || "https://orchestrat.ing/cli-auth";
+
+  return new Promise((resolve) => {
+    const server = http.createServer((req, res) => {
+      const url = new URL(req.url, `http://localhost`);
+      if (url.pathname === "/callback") {
+        const accessToken = url.searchParams.get("access_token");
+        const refreshToken = url.searchParams.get("refresh_token");
+        const expiresAt = url.searchParams.get("expires_at");
+
+        if (accessToken) {
+          saveAuth({
+            access_token: accessToken,
+            refresh_token: refreshToken || "",
+            expires_at: expiresAt ? Number(expiresAt) : 0,
+          });
+          res.writeHead(200, { "Content-Type": "text/html" });
+          res.end("<html><body><h2>Authenticated! You can close this tab.</h2><script>window.close()</script></body></html>");
+          console.log("\x1b[32mLogged in successfully.\x1b[0m");
+        } else {
+          res.writeHead(400, { "Content-Type": "text/html" });
+          res.end("<html><body><h2>Authentication failed. Please try again.</h2></body></html>");
+          console.error("Authentication failed — no token received.");
+        }
+
+        server.close();
+        resolve();
+      } else {
+        res.writeHead(404);
+        res.end();
+      }
+    });
+
+    server.listen(0, "127.0.0.1", () => {
+      const port = server.address().port;
+      const authUrl = `${loginUrl}?port=${port}`;
+      console.log(`Opening browser for authentication...`);
+      console.log(`If it doesn't open, visit: ${authUrl}`);
+
+      // Open browser
+      const openCmd = process.platform === "darwin" ? "open"
+        : process.platform === "win32" ? "start"
+        : "xdg-open";
+      try {
+        execSync(`${openCmd} "${authUrl}"`, { stdio: "ignore" });
+      } catch {
+        // Browser open failed — user can visit URL manually
+      }
+
+      // Timeout after 2 minutes
+      setTimeout(() => {
+        console.error("Login timed out.");
+        server.close();
+        resolve();
+      }, 120_000);
+    });
+  });
+}
+
+// --- Handle login/logout subcommands ---
+const firstArg = process.argv[2];
+if (firstArg === "login") {
+  await handleLogin();
+  process.exit(0);
+}
+if (firstArg === "logout") {
+  clearAuth();
+  console.log("Logged out.");
+  process.exit(0);
+}
+
+// --- Structured adapters ---
+// Commands that match an adapter key get spawned with structured JSON I/O
+// instead of PTY wrapping. Future adapters (codex, gemini) go here.
+const ADAPTERS = {
+  claude: {
+    buildArgs(prompt, flags) {
+      const args = [
+        "--output-format", "stream-json",
+        "--input-format", "stream-json",
+        "--verbose",
+      ];
+      if (flags.continue) {
+        args.push("-c");
+        if (prompt) args.push("-p", prompt);
+      } else {
+        args.push("-p", prompt);
+      }
+      return args;
+    },
+    mode: "structured",
+    provider: "claude-code",
+  },
+};
+
+// --- Parse args ---
+const args = process.argv.slice(2);
+let label = null;
+let yoloFlag = false;
+let commandArgs = [];
+
+// Parse flags before the command
+let i = 0;
+while (i < args.length) {
+  if (args[i] === "-l" && i + 1 < args.length) {
+    label = args[i + 1];
+    i += 2;
+  } else if (args[i] === "-y" || args[i] === "--yolo") {
+    yoloFlag = true;
+    i += 1;
+  } else if (args[i] === "--help" || args[i] === "-h") {
+    console.error("Usage: orch [-l label] [-y] <command> [args...]");
+    console.error("       orch login    — Authenticate with orchestrat.ing");
+    console.error("       orch logout   — Clear stored credentials");
+    console.error("");
+    console.error("  -l <label>   Optional human-readable session label");
+    console.error("  -y, --yolo   Skip all permission prompts (auto-approve everything)");
+    console.error("");
+    console.error("Examples:");
+    console.error('  orch claude "refactor auth"');
+    console.error('  orch -y claude "build a website"');
+    console.error('  orch -l "deploy fix" codex');
+    console.error("  orch bash");
+    console.error("");
+    console.error("Environment:");
+    console.error("  ORC_URL      WebSocket server URL (default: wss://api.orchestrat.ing/ws)");
+    console.error("  ORC_TOKEN    Auth token (overrides stored credentials)");
+    process.exit(0);
+  } else {
+    break;
+  }
+}
+commandArgs = args.slice(i);
+
+if (commandArgs.length === 0) {
+  console.error("Usage: orch [-l label] [-y] <command> [args...]");
+  console.error("       orch login | logout");
+  process.exit(1);
+}
+
+const command = commandArgs[0];
+const spawnArgs = commandArgs.slice(1);
+const sessionId = randomUUID();
+const hostname = os.hostname();
+const serverUrl = process.env.ORC_URL || process.env.CAST_URL || "wss://api.orchestrat.ing/ws";
+const authToken = getAuthToken();
+const effectiveLabel = label || commandArgs.join(" ") || "continue";
+
+// Warn if no auth and connecting to remote server
+if (!authToken && !serverUrl.includes("localhost") && !serverUrl.includes("127.0.0.1")) {
+  console.error("\x1b[33mNo credentials found. Run 'orch login' to authenticate.\x1b[0m");
+}
+
+// --- WebSocket connection with reconnect ---
+const BUFFER_MAX = 50 * 1024; // 50KB reconnect buffer
+let ws = null;
+let wsReady = false;
+let reconnectTimer = null;
+const sendBuffer = [];
+let bufferSize = 0;
+
+function sendToServer(msg) {
+  if (wsReady && ws && ws.readyState === WebSocket.OPEN) {
+    ws.send(JSON.stringify(msg));
+  } else {
+    const encoded = JSON.stringify(msg);
+    sendBuffer.push(encoded);
+    bufferSize += encoded.length;
+    while (bufferSize > BUFFER_MAX && sendBuffer.length > 1) {
+      const removed = sendBuffer.shift();
+      bufferSize -= removed.length;
+    }
+  }
+}
+
+// --- Terminal colors ---
+const CYAN = "\x1b[36m";
+const DIM = "\x1b[2m";
+const GREEN = "\x1b[32m";
+const RED = "\x1b[31m";
+const RESET = "\x1b[0m";
+const BOLD = "\x1b[1m";
+
+// --- Permission mode ---
+let yoloMode = yoloFlag;
+
+// --- Session-only permissions (cleaned up on exit) ---
+const sessionPermissions = []; // { settingsPath, tool }
+
+// --- Permission state helpers ---
+const projectSettingsPath = path.join(process.cwd(), ".claude", "settings.local.json");
+
+function readPermissions() {
+  const result = { project: [] };
+  try {
+    const ps = JSON.parse(readFileSync(projectSettingsPath, "utf-8"));
+    result.project = ps?.permissions?.allow || [];
+  } catch {}
+  return result;
+}
+
+function broadcastPermissions() {
+  const perms = readPermissions();
+  process.stderr.write(`${DIM}[perms] Broadcasting: ${perms.project.length} project${RESET}\n`);
+  sendToServer({ type: "agent_event", sessionId, event: { kind: "permission_state", ...perms } });
+}
+
+function removePermission(tool) {
+  try {
+    const settings = JSON.parse(readFileSync(projectSettingsPath, "utf-8"));
+    if (Array.isArray(settings?.permissions?.allow)) {
+      settings.permissions.allow = settings.permissions.allow.filter((t) => t !== tool);
+      writeFileSync(projectSettingsPath, JSON.stringify(settings, null, 2) + "\n");
+    }
+  } catch {}
+}
+
+// --- Determine mode: structured adapter or PTY ---
+const adapter = ADAPTERS[command];
+
+// Check for python3 in PTY mode
+if (!adapter) {
+  try {
+    execSync("python3 --version", { stdio: "ignore" });
+  } catch {
+    console.error("python3 is required for PTY mode. Please install Python 3.");
+    process.exit(1);
+  }
+}
+
+let child;
+let handleServerMessage; // set per-mode
+
+if (adapter) {
+  // ======== STRUCTURED MODE (Claude Code JSON streaming) ========
+  // Parse adapter-specific flags (e.g., -c for continue)
+  const adapterFlags = { continue: false };
+  const promptParts = [];
+  for (const arg of spawnArgs) {
+    if (arg === "-c" || arg === "--continue") {
+      adapterFlags.continue = true;
+    } else {
+      promptParts.push(arg);
+    }
+  }
+  const prompt = promptParts.join(" ");
+  if (!prompt && !adapterFlags.continue) {
+    console.error(`Usage: orch ${command} "your prompt here"`);
+    console.error(`       orch ${command} -c              # continue last conversation`);
+    console.error(`       orch ${command} -c "follow up"  # continue with message`);
+    process.exit(1);
+  }
+
+  const claudeArgs = adapter.buildArgs(prompt, adapterFlags);
+  if (yoloMode) {
+    claudeArgs.push("--dangerously-skip-permissions");
+  }
+  child = spawn(command, claudeArgs, {
+    stdio: ["pipe", "pipe", "pipe"],
+    cwd: process.cwd(),
+    env: (() => {
+      const e = { ...process.env };
+      delete e.CLAUDECODE;
+      delete e.ANTHROPIC_API_KEY;
+      return e;
+    })(),
+  });
+
+  // Parse NDJSON from stdout line-by-line
+  const rl = readline.createInterface({ input: child.stdout });
+
+  // Broadcast initial permission state once connected
+  let permissionsSent = false;
+
+  rl.on("line", (line) => {
+    if (!permissionsSent) {
+      permissionsSent = true;
+      broadcastPermissions();
+    }
+    if (!line.trim()) return;
+    let raw;
+    try {
+      raw = JSON.parse(line);
+    } catch {
+      return;
+    }
+
+    // Normalize and relay each event
+    const events = normalizeClaudeEvent(raw);
+    for (const event of events) {
+      printLocalEvent(event);
+      sendToServer({ type: "agent_event", sessionId, event });
+
+      // Yolo mode: auto-approve permission denials immediately
+      if (yoloMode && event.kind === "permission_denied") {
+        process.stderr.write(`${GREEN}[yolo] Auto-approving: ${event.toolName}${RESET}\n`);
+        approvePermission(event.toolName, "session");
+      }
+    }
+  });
+
+  child.stderr.on("data", (buf) => {
+    process.stderr.write(buf);
+  });
+
+  child.on("exit", (code) => {
+    const exitCode = code ?? 0;
+    sendToServer({ type: "exit", sessionId, exitCode });
+    setTimeout(() => process.exit(exitCode), 200);
+  });
+
+  child.on("error", (err) => {
+    console.error("Failed to start:", err.message);
+    process.exit(1);
+  });
+
+  // Confirmation-type tools — these need "yes" response, not permission grants
+  const CONFIRMATION_TOOLS = new Set(["ExitPlanMode", "EnterPlanMode"]);
+
+  // Auto-approve a tool permission (used by yolo mode and manual approval)
+  function approvePermission(toolName, scope) {
+    // For confirmation prompts, just send "yes" — no settings change needed
+    if (CONFIRMATION_TOOLS.has(toolName)) {
+      const confirmMsg = JSON.stringify({
+        type: "user",
+        message: { role: "user", content: "yes" },
+      });
+      child.stdin.write(confirmMsg + "\n");
+      return;
+    }
+
+    let permEntry = toolName;
+    const mcpMatch = toolName.match(/^(mcp__[^_]+(?:__[^_]+)?)__/);
+    if (mcpMatch) {
+      permEntry = mcpMatch[1] + "__*";
+    }
+
+    let settings = {};
+    try {
+      settings = JSON.parse(readFileSync(projectSettingsPath, "utf-8"));
+    } catch {}
+    if (!settings.permissions) settings.permissions = {};
+    if (!Array.isArray(settings.permissions.allow)) settings.permissions.allow = [];
+
+    const alreadyCovered = settings.permissions.allow.some((existing) => {
+      if (existing === permEntry) return true;
+      if (existing.endsWith("*") && permEntry.startsWith(existing.slice(0, -1))) return true;
+      return false;
+    });
+
+    if (!alreadyCovered) {
+      if (permEntry.endsWith("*")) {
+        const prefix = permEntry.slice(0, -1);
+        settings.permissions.allow = settings.permissions.allow.filter(
+          (e) => !e.startsWith(prefix) || e.endsWith("*")
+        );
+      }
+      settings.permissions.allow.push(permEntry);
+      mkdirSync(path.dirname(projectSettingsPath), { recursive: true });
+      writeFileSync(projectSettingsPath, JSON.stringify(settings, null, 2) + "\n");
+    }
+
+    if (scope === "session") {
+      sessionPermissions.push({ settingsPath: projectSettingsPath, tool: permEntry });
+    }
+
+    broadcastPermissions();
+
+    const retryMsg = JSON.stringify({
+      type: "user",
+      message: { role: "user", content: `Permission granted for ${toolName}. Please retry.` },
+    });
+    child.stdin.write(retryMsg + "\n");
+  }
+
+  // No local stdin forwarding in structured mode — input comes from server only
+  // (stdin is reserved for stream-json messages to Claude)
+
+  handleServerMessage = (msg) => {
+    if (msg.type === "agent_input" && (msg.text || msg.images)) {
+      // Forward user message from dashboard to Claude's stdin as stream-json
+      let content;
+      if (msg.images && msg.images.length > 0) {
+        // Build content array with images + optional text
+        content = [];
+        for (const img of msg.images) {
+          content.push({
+            type: "image",
+            source: { type: "base64", media_type: img.mediaType, data: img.data },
+          });
+        }
+        if (msg.text) {
+          content.push({ type: "text", text: msg.text });
+        }
+      } else {
+        content = msg.text;
+      }
+      const inputMsg = JSON.stringify({
+        type: "user",
+        message: { role: "user", content },
+      });
+      child.stdin.write(inputMsg + "\n");
+    } else if (msg.type === "agent_permission" && msg.tool && msg.action === "allow") {
+      const scope = msg.scope || "session";
+      approvePermission(msg.tool, scope);
+      process.stderr.write(`${GREEN}Permission granted (${scope}): ${msg.tool}${RESET}\n`);
+    } else if (msg.type === "agent_permission" && msg.tool && msg.action === "revoke") {
+      removePermission(msg.tool);
+      broadcastPermissions();
+      process.stderr.write(`${RED}Permission revoked: ${msg.tool}${RESET}\n`);
+    } else if (msg.type === "session_mode") {
+      const newMode = msg.mode;
+      yoloMode = newMode === "yolo";
+      process.stderr.write(`${BOLD}[mode] ${yoloMode ? "YOLO" : "Normal"}${RESET}\n`);
+    }
+  };
+
+} else {
+  // ======== PTY MODE (existing behavior for bash, etc.) ========
+  const cols = process.stdout.columns || 80;
+  const rows = process.stdout.rows || 24;
+  const shell = process.env.SHELL || "/bin/zsh";
+  const helperPath = path.join(__dirname, "pty-helper.py");
+
+  function shellEscape(arg) {
+    if (/^[a-zA-Z0-9_./:@=-]+$/.test(arg)) return arg;
+    return "'" + arg.replace(/'/g, "'\\''") + "'";
+  }
+  const shellCmd = commandArgs.map(shellEscape).join(" ");
+
+  child = spawn("python3", [helperPath, String(cols), String(rows), shell, "-c", shellCmd], {
+    stdio: ["pipe", "pipe", "pipe"],
+    cwd: process.cwd(),
+    env: (() => {
+      const e = { ...process.env, TERM: "xterm-256color" };
+      delete e.CLAUDECODE;
+      delete e.ANTHROPIC_API_KEY;
+      return e;
+    })(),
+  });
+
+  child.stdout.on("data", (buf) => {
+    process.stdout.write(buf);
+    sendToServer({ type: "output", sessionId, data: buf.toString("base64") });
+  });
+
+  child.stderr.on("data", (buf) => {
+    process.stderr.write(buf);
+  });
+
+  child.on("exit", (code) => {
+    const exitCode = code ?? 0;
+    sendToServer({ type: "exit", sessionId, exitCode });
+    if (process.stdin.isTTY) {
+      process.stdin.setRawMode(false);
+    }
+    setTimeout(() => process.exit(exitCode), 200);
+  });
+
+  child.on("error", (err) => {
+    console.error("Failed to start:", err.message);
+    process.exit(1);
+  });
+
+  if (process.stdin.isTTY) {
+    process.stdin.setRawMode(true);
+  }
+  process.stdin.resume();
+  process.stdin.on("data", (data) => {
+    child.stdin.write(data);
+  });
+
+  process.stdout.on("resize", () => {
+    const newCols = process.stdout.columns;
+    const newRows = process.stdout.rows;
+    child.stdin.write(`\x1b]R;${newCols};${newRows}\x07`);
+    sendToServer({ type: "resize", sessionId, cols: newCols, rows: newRows });
+  });
+
+  handleServerMessage = (msg) => {
+    if (msg.type === "input" && msg.data) {
+      child.stdin.write(Buffer.from(msg.data, "base64"));
+    } else if (msg.type === "resize" && msg.cols && msg.rows) {
+      child.stdin.write(`\x1b]R;${msg.cols};${msg.rows}\x07`);
+    }
+  };
+}
+
+// --- Normalize Claude Code stream-json events into provider-agnostic events ---
+
+let blockCounter = 0;
+const toolInfoMap = {}; // toolId -> { toolName, input }
+
+function normalizeClaudeEvent(raw) {
+  const events = [];
+
+  if (raw.type === "system" && raw.subtype === "init") {
+    events.push({
+      kind: "status",
+      status: "init",
+      sessionId: raw.session_id,
+      model: raw.model,
+      tools: raw.tools,
+    });
+    return events;
+  }
+
+  if (raw.type === "assistant") {
+    const msg = raw.message;
+    if (!msg || !msg.content) return events;
+
+    events.push({ kind: "message_start", messageId: msg.id });
+
+    for (const block of msg.content) {
+      if (block.type === "text") {
+        const blockId = `text-${++blockCounter}`;
+        events.push({ kind: "text_delta", blockId, text: block.text });
+      } else if (block.type === "thinking") {
+        const blockId = `thinking-${++blockCounter}`;
+        events.push({ kind: "thinking_delta", blockId, text: block.thinking });
+        events.push({ kind: "thinking_done", blockId });
+      } else if (block.type === "tool_use") {
+        toolInfoMap[block.id] = { toolName: block.name, input: block.input };
+        events.push({
+          kind: "tool_start",
+          blockId: block.id,
+          toolName: block.name,
+          toolId: block.id,
+          input: JSON.stringify(block.input),
+        });
+      }
+    }
+
+    events.push({
+      kind: "message_end",
+      messageId: msg.id,
+      stopReason: msg.stop_reason,
+    });
+    return events;
+  }
+
+  if (raw.type === "user" && raw.tool_use_result !== undefined) {
+    const content = raw.message?.content;
+    if (Array.isArray(content)) {
+      for (const block of content) {
+        if (block.type === "tool_result") {
+          const result = raw.tool_use_result || {};
+          // Handle content that may be string or array of content blocks
+          let outputText = "";
+          if (result.stdout) {
+            outputText = result.stdout;
+          } else if (typeof block.content === "string") {
+            outputText = block.content;
+          } else if (Array.isArray(block.content)) {
+            outputText = block.content
+              .filter((c) => c.type === "text")
+              .map((c) => c.text)
+              .join("\n");
+          }
+
+          events.push({
+            kind: "tool_result",
+            toolId: block.tool_use_id,
+            output: outputText,
+            isError: block.is_error || false,
+          });
+
+          // Detect permission denial errors
+          if (block.is_error && outputText) {
+            let toolName = null;
+
+            // "Claude requested permissions to use <ToolName>"
+            const useMatch = outputText.match(/Claude requested permissions? to use (\S+)/);
+            if (useMatch) {
+              toolName = useMatch[1].replace(/[,.]$/, "");
+            }
+            // "Claude requested permissions to write/edit/execute ..." — use actual tool name from tracker
+            if (!toolName && /Claude requested permissions? to (write|edit|execute|read|run|create|delete) /i.test(outputText)) {
+              const info = toolInfoMap[block.tool_use_id];
+              toolName = info?.toolName || "Write";
+            }
+            // "This command requires approval" — look up tool name from tracker
+            if (!toolName && /requires? approval/i.test(outputText)) {
+              const info = toolInfoMap[block.tool_use_id];
+              toolName = info?.toolName || "Unknown";
+            }
+            // Generic fallback: "Claude requested permissions..."
+            if (!toolName && /Claude requested permissions?/i.test(outputText)) {
+              const info = toolInfoMap[block.tool_use_id];
+              toolName = info?.toolName || "Unknown";
+            }
+            // "haven't granted it yet"
+            if (!toolName && /haven't granted/i.test(outputText)) {
+              const info = toolInfoMap[block.tool_use_id];
+              toolName = info?.toolName || "Unknown";
+            }
+            // Confirmation prompts (e.g., "Exit plan mode?") — short errors ending with "?"
+            if (!toolName && outputText.trim().endsWith("?") && outputText.length < 200) {
+              const info = toolInfoMap[block.tool_use_id];
+              toolName = info?.toolName || "Unknown";
+            }
+            // Broad fallback: any short error for a known tool that isn't a real error message
+            if (!toolName && outputText.length < 100) {
+              const info = toolInfoMap[block.tool_use_id];
+              if (info) {
+                toolName = info.toolName;
+              }
+            }
+
+            if (toolName) {
+              events.push({
+                kind: "permission_denied",
+                toolName,
+                toolId: block.tool_use_id,
+              });
+            }
+          }
+        }
+      }
+    }
+    return events;
+  }
+
+  if (raw.type === "result") {
+    events.push({
+      kind: "status",
+      status: raw.subtype === "success" ? "complete" : "error",
+      cost: raw.total_cost_usd,
+      duration: raw.duration_ms,
+      result: raw.result,
+    });
+    return events;
+  }
+
+  return events;
+}
+
+// --- Print structured events locally for terminal feedback ---
+
+function printLocalEvent(event) {
+  switch (event.kind) {
+    case "text_delta":
+      process.stdout.write(event.text);
+      break;
+    case "thinking_delta":
+      process.stdout.write(`${DIM}${event.text}${RESET}`);
+      break;
+    case "tool_start":
+      process.stdout.write(`\n${CYAN}${BOLD}Tool: ${event.toolName}${RESET}\n`);
+      if (event.input) {
+        try {
+          const parsed = JSON.parse(event.input);
+          const display = parsed.command || parsed.pattern || parsed.file_path || event.input;
+          process.stdout.write(`${DIM}${typeof display === "string" ? display : event.input}${RESET}\n`);
+        } catch {
+          process.stdout.write(`${DIM}${event.input}${RESET}\n`);
+        }
+      }
+      break;
+    case "tool_result":
+      if (event.isError) {
+        process.stdout.write(`${RED}Error: ${event.output.slice(0, 200)}${RESET}\n`);
+      } else if (event.output) {
+        const preview = event.output.length > 300
+          ? event.output.slice(0, 300) + "..."
+          : event.output;
+        process.stdout.write(`${DIM}${preview}${RESET}\n`);
+      }
+      break;
+    case "status":
+      if (event.status === "complete") {
+        process.stdout.write(`\n${GREEN}Done${RESET}${event.cost ? ` ($${event.cost.toFixed(4)})` : ""}\n`);
+      }
+      break;
+    case "message_end":
+      process.stdout.write("\n");
+      break;
+  }
+}
+
+// --- WebSocket connection ---
+
+function connectWs() {
+  if (ws) {
+    ws.removeAllListeners();
+    ws.close();
+  }
+
+  ws = new WebSocket(serverUrl);
+
+  ws.on("open", () => {
+    ws.send(JSON.stringify({
+      type: "register",
+      token: authToken,
+      sessionId,
+      label: effectiveLabel,
+      command,
+      args: spawnArgs,
+      cwd: process.cwd(),
+      hostname,
+      mode: adapter ? adapter.mode : "pty",
+      provider: adapter ? adapter.provider : null,
+      permissionMode: yoloMode ? "yolo" : "normal",
+      cols: process.stdout.columns || 80,
+      rows: process.stdout.rows || 24,
+    }));
+    wsReady = true;
+
+    for (const msg of sendBuffer) {
+      ws.send(msg);
+    }
+    sendBuffer.length = 0;
+    bufferSize = 0;
+
+    // Broadcast permission state after registration (structured mode only)
+    if (adapter) {
+      broadcastPermissions();
+    }
+  });
+
+  ws.on("message", (raw) => {
+    try {
+      const msg = JSON.parse(raw.toString());
+      handleServerMessage(msg);
+    } catch {}
+  });
+
+  ws.on("close", () => {
+    wsReady = false;
+    ws = null;
+    reconnectTimer = setTimeout(connectWs, 2000);
+  });
+
+  ws.on("error", () => {
+    // Will trigger close
+  });
+}
+
+connectWs();
+
+// --- Graceful shutdown ---
+function revokeSessionPermissions() {
+  // Group by settings file to minimize I/O
+  const byFile = {};
+  for (const { settingsPath, tool } of sessionPermissions) {
+    if (!byFile[settingsPath]) byFile[settingsPath] = [];
+    byFile[settingsPath].push(tool);
+  }
+  for (const [filePath, tools] of Object.entries(byFile)) {
+    try {
+      const settings = JSON.parse(readFileSync(filePath, "utf-8"));
+      if (Array.isArray(settings?.permissions?.allow)) {
+        settings.permissions.allow = settings.permissions.allow.filter((t) => !tools.includes(t));
+        writeFileSync(filePath, JSON.stringify(settings, null, 2) + "\n");
+      }
+    } catch {
+      // File gone or unreadable — nothing to revoke
+    }
+  }
+  sessionPermissions.length = 0;
+}
+
+function cleanup() {
+  revokeSessionPermissions();
+  if (reconnectTimer) clearTimeout(reconnectTimer);
+  if (ws) ws.close();
+}
+
+process.on("SIGINT", () => {
+  if (adapter) {
+    child.kill("SIGINT");
+  } else {
+    child.stdin.write("\x03");
+  }
+});
+
+process.on("SIGTERM", () => {
+  child.kill();
+  cleanup();
+  process.exit(0);
+});
+
+process.on("exit", cleanup);

package/bin/pty-helper.py

@@ -0,0 +1,139 @@
+#!/usr/bin/env python3
+"""
+Minimal PTY bridge: creates a real PTY, forks a child process onto it,
+and bridges stdin/stdout pipes to the PTY master. This lets Node.js
+get full PTY behavior (colors, cursor control, raw mode) without
+native modules like node-pty.
+
+Usage: pty-helper.py <cols> <rows> <command> [args...]
+
+Resize protocol: send \x1b]R;<cols>;<rows>\x07 on stdin to resize the PTY.
+"""
+import pty, os, sys, select, signal, struct, fcntl, termios, errno
+
+if len(sys.argv) < 4:
+    print("Usage: pty-helper.py <cols> <rows> <command> [args...]", file=sys.stderr)
+    sys.exit(1)
+
+cols = int(sys.argv[1])
+rows = int(sys.argv[2])
+cmd = sys.argv[3]
+cmd_args = sys.argv[3:]
+
+# Create PTY pair
+master_fd, slave_fd = pty.openpty()
+
+# Set initial window size
+winsize = struct.pack("HHHH", rows, cols, 0, 0)
+fcntl.ioctl(slave_fd, termios.TIOCSWINSZ, winsize)
+
+pid = os.fork()
+if pid == 0:
+    # Child: attach to slave PTY
+    os.close(master_fd)
+    os.setsid()
+    fcntl.ioctl(slave_fd, termios.TIOCSCTTY, 0)
+    os.dup2(slave_fd, 0)
+    os.dup2(slave_fd, 1)
+    os.dup2(slave_fd, 2)
+    if slave_fd > 2:
+        os.close(slave_fd)
+    os.execvp(cmd, cmd_args)
+else:
+    # Parent: bridge pipes <-> PTY master
+    os.close(slave_fd)
+
+    # Make master non-blocking
+    flags = fcntl.fcntl(master_fd, fcntl.F_GETFL)
+    fcntl.fcntl(master_fd, fcntl.F_SETFL, flags | os.O_NONBLOCK)
+
+    stdin_open = True
+    child_alive = True
+
+    try:
+        while child_alive:
+            fds = [master_fd]
+            if stdin_open:
+                fds.append(0)
+
+            try:
+                r, _, _ = select.select(fds, [], [], 0.05)
+            except (select.error, ValueError, OSError):
+                break
+
+            # Read from stdin -> write to PTY master
+            if 0 in r:
+                try:
+                    data = os.read(0, 65536)
+                    if not data:
+                        stdin_open = False
+                    else:
+                        # Check for resize escape: \x1b]R;<cols>;<rows>\x07
+                        while b"\x1b]R;" in data:
+                            idx = data.index(b"\x1b]R;")
+                            try:
+                                end = data.index(b"\x07", idx)
+                                resize_data = data[idx+4:end].decode()
+                                parts = resize_data.split(";")
+                                if len(parts) == 2:
+                                    c, rr = int(parts[0]), int(parts[1])
+                                    ws = struct.pack("HHHH", rr, c, 0, 0)
+                                    fcntl.ioctl(master_fd, termios.TIOCSWINSZ, ws)
+                                    os.kill(pid, signal.SIGWINCH)
+                                data = data[:idx] + data[end+1:]
+                            except (ValueError, IndexError):
+                                break
+                        if data:
+                            os.write(master_fd, data)
+                except OSError as e:
+                    if e.errno == errno.EIO:
+                        stdin_open = False
+                    elif e.errno != errno.EAGAIN:
+                        stdin_open = False
+
+            # Read from PTY master -> write to stdout
+            if master_fd in r:
+                try:
+                    data = os.read(master_fd, 65536)
+                    if data:
+                        os.write(1, data)
+                except OSError as e:
+                    if e.errno == errno.EIO:
+                        # PTY closed — child exited
+                        child_alive = False
+                    elif e.errno != errno.EAGAIN:
+                        child_alive = False
+
+            # Check if child exited (non-blocking)
+            try:
+                result = os.waitpid(pid, os.WNOHANG)
+                if result[0] != 0:
+                    # Drain remaining output from master
+                    while True:
+                        try:
+                            data = os.read(master_fd, 65536)
+                            if not data:
+                                break
+                            os.write(1, data)
+                        except OSError:
+                            break
+                    status = result[1]
+                    code = os.WEXITSTATUS(status) if os.WIFEXITED(status) else 1
+                    os.close(master_fd)
+                    sys.exit(code)
+            except ChildProcessError:
+                child_alive = False
+
+    except KeyboardInterrupt:
+        pass
+    finally:
+        try:
+            os.close(master_fd)
+        except OSError:
+            pass
+        try:
+            _, status = os.waitpid(pid, 0)
+            code = os.WEXITSTATUS(status) if os.WIFEXITED(status) else 1
+            sys.exit(code)
+        except ChildProcessError:
+            pass

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "orchestrating",
+  "version": "0.1.0",
+  "description": "Stream terminal sessions to the orchestrat.ing dashboard",
+  "type": "module",
+  "bin": {
+    "orch": "./bin/orch"
+  },
+  "files": [
+    "bin/orch",
+    "bin/pty-helper.py",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "homepage": "https://orchestrat.ing",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/orchestrating/orchestrating"
+  },
+  "license": "MIT",
+  "keywords": [
+    "cli",
+    "terminal",
+    "streaming",
+    "ai",
+    "claude",
+    "orchestration",
+    "dashboard"
+  ],
+  "dependencies": {
+    "ws": "^8.18.0"
+  }
+}