@aiolah/cli 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ibnutron
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,125 @@
+# aiolah
+
+Terminal AI CLI (like opencode / Claude Code) with remote-control support: start a
+session on one machine and drive it from another. The model can read/write files
+and run shell commands in a scoped workspace.
+
+## Setup
+
+```bash
+npm install
+cp .env.example .env   # fill in ANTHROPIC_API_KEY
+npm run build
+npm link                # puts the `aiolah` binary on PATH globally
+```
+
+The `.env` next to the package is loaded automatically on every `aiolah` invocation
+(regardless of the current directory), so `npm run code` from another repo still
+finds the key. Variables already exported in the environment take precedence.
+
+## Commands
+
+- `aiolah chat` — interactive chat with tool-use (file read/write/edit, `run_bash`)
+  scoped to `--workspace` (default: current directory).
+- `aiolah serve` — host a chat session and print a token + WebSocket address that a
+  remote client can attach to. Tools always execute on the host, never on the
+  attach client.
+- `aiolah attach ws://<host>:<port>` — join a running `serve` session from another
+  machine, using the token it printed. You'll be prompted for the token; auth
+  uses an HMAC challenge/response so the token itself never crosses the wire.
+- `aiolah sessions list` — list saved sessions (id, last updated, workspace).
+
+### Flags
+
+- `-w, --workspace <dir>` — root directory tools are scoped to (default `.`).
+  File paths that resolve outside this directory are rejected.
+- `--resume <id>` / `--continue` — resume a specific saved session, or the most
+  recently updated one. Full history (including tool calls) is persisted to
+  `~/.aiolah/sessions/<id>.json` after every turn.
+- `--yolo` — skip the y/n confirmation prompt before `write_file`, `edit_file`,
+  or `run_bash`. Off by default: those three tools always ask first.
+- `--cert <path> --key <path>` (serve only) — serve over `wss://` (TLS) using a
+  self-signed cert or one from Tailscale/Let's Encrypt, for confidentiality
+  when attaching over a real network instead of localhost.
+
+## Wire protocol (for building other clients)
+
+`serve` speaks newline-free JSON messages over a single WebSocket. Any client
+(web page, mobile app, editor extension) can implement it:
+
+1. Server → `{type:"challenge", nonce}`; client → `{type:"auth", hmac}` where
+   `hmac = hex(HMAC-SHA256(key = token, message = nonce))`. Wrong answer →
+   `{type:"error", text:"unauthorized"}` and the socket closes (3 attempts per
+   socket, 5 per IP per minute).
+2. Server → `{type:"authed", sessionId, workspace, model, history}` where
+   `history` is the conversation so far, flattened for rendering:
+   `{role:"user"|"assistant", text}` and `{role:"tool", name, input, result}`.
+3. Client → `{type:"user", text}` starts a turn. While it runs the server sends
+   `{type:"busy"}`, then per tool call `{type:"tool", name, input}` and
+   `{type:"tool_result", name, result}`, then `{type:"assistant", text}` and
+   `{type:"idle"}`. A `user` message sent while busy gets `error: "busy"`.
+   Other connected clients receive the same `user` message so they stay in sync.
+4. Unless the host runs with `--yolo`, mutating tools (`write_file`,
+   `edit_file`, `run_bash`) pause with `{type:"confirm", id, description}` sent
+   to every client and printed on the host terminal. The first answer wins —
+   a client replies `{type:"confirm_reply", id, allow:true|false}`, or the host
+   operator types `y`/`n`. No answer within 5 minutes counts as denied.
+
+The token never crosses the wire, but everything else does: use `wss://` (see
+production notes below) whenever the connection leaves localhost. Browsers
+also refuse `ws://` from an `https://` page.
+
+## Remote-controlling another repo
+
+Any repo can expose its own `aiolah serve`, rooted at that repo, via an npm
+script, e.g.:
+
+```json
+{ "scripts": { "code": "aiolah serve --port 4318" } }
+```
+
+Then `npm run code` in that repo, and `aiolah attach ws://<host>:4318` from
+another machine to work on it remotely.
+
+## Running `aiolah serve` in production (exposed beyond localhost)
+
+`serve` is designed for one trusted operator driving one machine. Before
+exposing it past `localhost`, treat the following as required, not optional:
+
+1. **Always use TLS.** Auth is HMAC challenge/response (the token never crosses
+   the wire), but every prompt, tool call, file content, and command output
+   *does*. Run with `--cert/--key` (`wss://`), or terminate TLS in front of it
+   (nginx/Caddy/Cloudflare Tunnel proxying to `ws://127.0.0.1:<port>`). The
+   Tailscale + `tailscale cert` route is the least effort for a personal setup.
+2. **Set a long, fixed `AIOLAH_REMOTE_TOKEN`** in the package `.env` (32+ random
+   bytes, e.g. `node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"`).
+   Without it a new random token is printed at every start, which is fine for
+   an interactive terminal but useless for a service.
+3. **Bind narrowly / firewall the port.** `serve` listens on all interfaces.
+   Don't open the port on a public IP; put it behind a VPN (Tailscale/WireGuard),
+   an SSH tunnel (`ssh -L 4317:localhost:4317 host`), or a reverse proxy with
+   its own auth.
+4. **Never run with `--yolo` on a machine you care about.** Without it, every
+   `write_file` / `edit_file` / `run_bash` waits for a y/N on the *host*
+   terminal — which means an unattended service (stdin closed) will hang on
+   the first mutating tool call. For an unattended host, either accept
+   `--yolo` inside a sandboxed workspace/VM, or keep a terminal attached
+   (tmux/screen) to approve calls.
+5. **Scope the workspace** with `-w` to the single repo the session should
+   touch; `run_bash` still executes with the host user's full privileges inside
+   that cwd, so run the service as a low-privilege user.
+6. **Keep it alive** with a supervisor, e.g. `pm2 start aiolah --name aiolah-ai5 -- serve --port 4318 -w /srv/ai5`
+   or a `systemd` unit with `Restart=on-failure`; stdin will be closed, so
+   pair this with point 4.
+7. **Sessions are plaintext JSON** in `~/.aiolah/sessions/` (full conversation,
+   tool inputs, file contents). Protect that directory's permissions and
+   rotate/delete old sessions.
+
+Not yet live-tested: `wss://` against a real certificate, and `attach` across
+the public internet (only localhost so far).
+
+## Status
+
+Chat, tool-use, session persistence, and remote attach/serve work over a
+single shared conversation (verified end-to-end with real API calls); no
+multi-session concurrency within one process.

package/dist/cli.js

@@ -0,0 +1,749 @@
+#!/usr/bin/env node
+
+// src/cli.ts
+import { readFileSync as readFileSync4 } from "fs";
+import { dirname as dirname2, join as join3 } from "path";
+import { fileURLToPath } from "url";
+import { parseEnv } from "util";
+import { Command } from "commander";
+
+// src/commands/chat.ts
+import * as readline from "readline/promises";
+import { stdin, stdout } from "process";
+import { resolve as resolve2 } from "path";
+
+// src/session.ts
+import { EventEmitter } from "events";
+import Anthropic from "@anthropic-ai/sdk";
+
+// src/tools/fileTools.ts
+import { existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync } from "fs";
+import { dirname, isAbsolute, join, relative, resolve } from "path";
+var WorkspaceViolationError = class extends Error {
+};
+function resolveInWorkspace(workspaceRoot, targetPath) {
+  const resolved = isAbsolute(targetPath) ? resolve(targetPath) : resolve(workspaceRoot, targetPath);
+  const rel = relative(workspaceRoot, resolved);
+  if (rel.startsWith("..") || isAbsolute(rel)) {
+    throw new WorkspaceViolationError(`Path "${targetPath}" is outside the workspace`);
+  }
+  return resolved;
+}
+function readFile(workspaceRoot, path) {
+  return readFileSync(resolveInWorkspace(workspaceRoot, path), "utf8");
+}
+function writeFile(workspaceRoot, path, content) {
+  const absolute = resolveInWorkspace(workspaceRoot, path);
+  mkdirSync(dirname(absolute), { recursive: true });
+  writeFileSync(absolute, content, "utf8");
+}
+function editFile(workspaceRoot, path, oldString, newString) {
+  const absolute = resolveInWorkspace(workspaceRoot, path);
+  const content = readFileSync(absolute, "utf8");
+  const occurrences = content.split(oldString).length - 1;
+  if (occurrences === 0) {
+    throw new Error(`old_string not found in ${path}`);
+  }
+  if (occurrences > 1) {
+    throw new Error(`old_string is not unique in ${path} (${occurrences} matches)`);
+  }
+  writeFileSync(absolute, content.replace(oldString, newString), "utf8");
+}
+function listDir(workspaceRoot, path) {
+  const absolute = resolveInWorkspace(workspaceRoot, path);
+  return readdirSync(absolute).map((entry) => {
+    const isDir = statSync(join(absolute, entry)).isDirectory();
+    return isDir ? `${entry}/` : entry;
+  });
+}
+
+// src/tools/bashTool.ts
+import { exec } from "child_process";
+var MAX_OUTPUT_CHARS = 2e4;
+var TIMEOUT_MS = 12e4;
+function truncate(text) {
+  return text.length > MAX_OUTPUT_CHARS ? `${text.slice(0, MAX_OUTPUT_CHARS)}
+...[truncated]` : text;
+}
+function runBash(workspaceRoot, command) {
+  return new Promise((resolvePromise) => {
+    exec(
+      command,
+      { cwd: workspaceRoot, timeout: TIMEOUT_MS, maxBuffer: 10 * 1024 * 1024 },
+      (error, stdout5, stderr) => {
+        resolvePromise({
+          stdout: truncate(stdout5),
+          stderr: truncate(stderr),
+          exitCode: error && typeof error.code === "number" ? error.code : error ? 1 : 0
+        });
+      }
+    );
+  });
+}
+
+// src/tools/index.ts
+var TOOL_SCHEMAS = [
+  {
+    name: "read_file",
+    description: "Read a text file from the workspace.",
+    input_schema: {
+      type: "object",
+      properties: { path: { type: "string", description: "Path relative to the workspace root" } },
+      required: ["path"]
+    }
+  },
+  {
+    name: "write_file",
+    description: "Create or overwrite a text file in the workspace. Requires user confirmation.",
+    input_schema: {
+      type: "object",
+      properties: {
+        path: { type: "string", description: "Path relative to the workspace root" },
+        content: { type: "string", description: "Full file content to write" }
+      },
+      required: ["path", "content"]
+    }
+  },
+  {
+    name: "edit_file",
+    description: "Replace a unique occurrence of old_string with new_string in an existing file. Requires user confirmation.",
+    input_schema: {
+      type: "object",
+      properties: {
+        path: { type: "string", description: "Path relative to the workspace root" },
+        old_string: { type: "string", description: "Exact text to find (must be unique in the file)" },
+        new_string: { type: "string", description: "Replacement text" }
+      },
+      required: ["path", "old_string", "new_string"]
+    }
+  },
+  {
+    name: "list_dir",
+    description: "List the contents of a directory in the workspace.",
+    input_schema: {
+      type: "object",
+      properties: { path: { type: "string", description: 'Path relative to the workspace root, "." for root' } },
+      required: ["path"]
+    }
+  },
+  {
+    name: "run_bash",
+    description: "Run a shell command in the workspace root. Requires user confirmation.",
+    input_schema: {
+      type: "object",
+      properties: { command: { type: "string", description: "Shell command to execute" } },
+      required: ["command"]
+    }
+  }
+];
+async function executeTool(name, input, context) {
+  const { workspaceRoot, confirm } = context;
+  switch (name) {
+    case "read_file":
+      return readFile(workspaceRoot, String(input.path));
+    case "list_dir":
+      return listDir(workspaceRoot, String(input.path)).join("\n");
+    case "write_file": {
+      const path = String(input.path);
+      if (!await confirm(`write_file: ${path}`)) {
+        return "User declined this action.";
+      }
+      writeFile(workspaceRoot, path, String(input.content));
+      return `Wrote ${path}`;
+    }
+    case "edit_file": {
+      const path = String(input.path);
+      if (!await confirm(`edit_file: ${path}`)) {
+        return "User declined this action.";
+      }
+      editFile(workspaceRoot, path, String(input.old_string), String(input.new_string));
+      return `Edited ${path}`;
+    }
+    case "run_bash": {
+      const command = String(input.command);
+      if (!await confirm(`run_bash: ${command}`)) {
+        return "User declined this action.";
+      }
+      const result = await runBash(workspaceRoot, command);
+      return `exit code: ${result.exitCode}
+stdout:
+${result.stdout}
+stderr:
+${result.stderr}`;
+    }
+    default:
+      throw new Error(`Unknown tool: ${name}`);
+  }
+}
+
+// src/persistence.ts
+import { mkdirSync as mkdirSync2, readFileSync as readFileSync2, readdirSync as readdirSync2, writeFileSync as writeFileSync2 } from "fs";
+import { homedir } from "os";
+import { join as join2 } from "path";
+import { randomBytes } from "crypto";
+var SESSIONS_DIR = join2(homedir(), ".aiolah", "sessions");
+function ensureDir() {
+  mkdirSync2(SESSIONS_DIR, { recursive: true });
+}
+function generateSessionId() {
+  return `${Date.now().toString(36)}-${randomBytes(4).toString("hex")}`;
+}
+function pathFor(id) {
+  return join2(SESSIONS_DIR, `${id}.json`);
+}
+function saveSession(record) {
+  ensureDir();
+  writeFileSync2(pathFor(record.id), JSON.stringify(record, null, 2), "utf8");
+}
+function loadSession(id) {
+  return JSON.parse(readFileSync2(pathFor(id), "utf8"));
+}
+function listSessions() {
+  ensureDir();
+  return readdirSync2(SESSIONS_DIR).filter((file) => file.endsWith(".json")).map((file) => JSON.parse(readFileSync2(join2(SESSIONS_DIR, file), "utf8"))).sort((a, b) => b.updatedAt.localeCompare(a.updatedAt));
+}
+function findLatestSession() {
+  return listSessions()[0];
+}
+
+// src/session.ts
+var ChatSession = class extends EventEmitter {
+  client;
+  model;
+  workspaceRoot;
+  confirm;
+  id;
+  createdAt;
+  history;
+  constructor(options) {
+    super();
+    const apiKey = options.apiKey ?? process.env.ANTHROPIC_API_KEY;
+    if (!apiKey) {
+      throw new Error("ANTHROPIC_API_KEY is not set. Copy .env.example to .env and fill it in.");
+    }
+    this.client = new Anthropic({ apiKey });
+    this.model = options.model;
+    this.workspaceRoot = options.workspaceRoot;
+    this.confirm = options.confirm;
+    if (options.resumeId) {
+      const record = loadSession(options.resumeId);
+      this.id = record.id;
+      this.createdAt = record.createdAt;
+      this.history = record.history;
+    } else {
+      this.id = generateSessionId();
+      this.createdAt = (/* @__PURE__ */ new Date()).toISOString();
+      this.history = [];
+    }
+  }
+  get sessionId() {
+    return this.id;
+  }
+  get modelId() {
+    return this.model;
+  }
+  get workspace() {
+    return this.workspaceRoot;
+  }
+  /** Conversation flattened to what a client renders (tool_use/tool_result pairs joined by id). */
+  renderHistory() {
+    const items = [];
+    const pendingTools = /* @__PURE__ */ new Map();
+    for (const message of this.history) {
+      if (typeof message.content === "string") {
+        items.push({ role: message.role, text: message.content });
+        continue;
+      }
+      for (const block of message.content) {
+        if (block.type === "text" && block.text.trim()) {
+          items.push({ role: message.role, text: block.text });
+        } else if (block.type === "tool_use") {
+          pendingTools.set(block.id, { name: block.name, input: block.input });
+        } else if (block.type === "tool_result") {
+          const call = pendingTools.get(block.tool_use_id);
+          const result = typeof block.content === "string" ? block.content : (block.content ?? []).map((part) => part.type === "text" ? part.text : "").join("");
+          items.push({ role: "tool", name: call?.name ?? "unknown", input: call?.input, result });
+          pendingTools.delete(block.tool_use_id);
+        }
+      }
+    }
+    return items;
+  }
+  async send(userMessage) {
+    this.history.push({ role: "user", content: userMessage });
+    while (true) {
+      const response = await this.client.messages.create({
+        model: this.model,
+        max_tokens: 4096,
+        tools: TOOL_SCHEMAS,
+        messages: this.history
+      });
+      this.history.push({ role: "assistant", content: response.content });
+      this.persist();
+      if (response.stop_reason !== "tool_use") {
+        const reply = response.content.filter((block) => block.type === "text").map((block) => block.text).join("\n");
+        return { reply };
+      }
+      const toolResults = [];
+      for (const block of response.content) {
+        if (block.type !== "tool_use") {
+          continue;
+        }
+        this.emit("tool", { name: block.name, input: block.input });
+        let content;
+        try {
+          content = await executeTool(block.name, block.input, {
+            workspaceRoot: this.workspaceRoot,
+            confirm: this.confirm
+          });
+        } catch (error) {
+          content = `Error: ${error instanceof Error ? error.message : String(error)}`;
+        }
+        this.emit("tool_result", { name: block.name, result: content });
+        toolResults.push({ type: "tool_result", tool_use_id: block.id, content });
+      }
+      this.history.push({ role: "user", content: toolResults });
+      this.persist();
+    }
+  }
+  persist() {
+    const record = {
+      id: this.id,
+      model: this.model,
+      workspace: this.workspaceRoot,
+      createdAt: this.createdAt,
+      updatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+      history: this.history
+    };
+    saveSession(record);
+  }
+};
+
+// src/prompt.ts
+async function ask(rl, prompt) {
+  try {
+    return await rl.question(prompt);
+  } catch (error) {
+    if (error.code === "ERR_USE_AFTER_CLOSE") {
+      return null;
+    }
+    throw error;
+  }
+}
+
+// src/commands/chat.ts
+async function chatCommand(options) {
+  const rl = readline.createInterface({ input: stdin, output: stdout });
+  const workspaceRoot = resolve2(options.workspace);
+  const resumeId = options.resume ?? (options.continue ? findLatestSession()?.id : void 0);
+  const confirm = options.yolo ? async () => true : async (description) => {
+    const answer = await ask(rl, `Allow ${description}? [y/N] `);
+    return answer?.trim().toLowerCase() === "y";
+  };
+  const session = new ChatSession({ model: options.model, workspaceRoot, confirm, resumeId });
+  session.on("tool", ({ name, input }) => {
+    stdout.write(`
+[tool] ${name} ${JSON.stringify(input)}
+`);
+  });
+  stdout.write(
+    `aiolah chat \u2014 model ${options.model}, workspace ${workspaceRoot}, session ${session.sessionId}
+Type "exit" to quit.
+`
+  );
+  try {
+    while (true) {
+      const input = await ask(rl, "you> ");
+      if (input === null || input.trim().toLowerCase() === "exit") {
+        break;
+      }
+      if (!input.trim()) {
+        continue;
+      }
+      const { reply } = await session.send(input);
+      stdout.write(`
+assistant> ${reply}
+
+`);
+    }
+  } finally {
+    rl.close();
+  }
+}
+
+// src/commands/serve.ts
+import * as readline2 from "readline/promises";
+import { stdin as stdin2, stdout as stdout2 } from "process";
+import { randomBytes as randomBytes3 } from "crypto";
+import { readFileSync as readFileSync3 } from "fs";
+import { createServer as createHttpsServer } from "https";
+import { resolve as resolve3 } from "path";
+import { WebSocketServer } from "ws";
+
+// src/auth.ts
+import { createHmac, randomBytes as randomBytes2, timingSafeEqual } from "crypto";
+function generateNonce() {
+  return randomBytes2(24).toString("hex");
+}
+function signChallenge(token, nonce) {
+  return createHmac("sha256", token).update(nonce).digest("hex");
+}
+function verifyChallenge(token, nonce, hmac) {
+  const expected = Buffer.from(signChallenge(token, nonce), "hex");
+  const actual = Buffer.from(hmac, "hex");
+  return expected.length === actual.length && timingSafeEqual(expected, actual);
+}
+
+// src/commands/serve.ts
+var MAX_AUTH_ATTEMPTS = 3;
+var RATE_LIMIT_WINDOW_MS = 6e4;
+var RATE_LIMIT_MAX_ATTEMPTS = 5;
+var CONFIRM_TIMEOUT_MS = 5 * 6e4;
+async function serveCommand(options) {
+  const token = process.env.AIOLAH_REMOTE_TOKEN ?? randomBytes3(16).toString("hex");
+  const port = Number(options.port);
+  const workspaceRoot = resolve3(options.workspace);
+  const resumeId = options.resume ?? (options.continue ? findLatestSession()?.id : void 0);
+  const clients = /* @__PURE__ */ new Set();
+  const attemptsByIp = /* @__PURE__ */ new Map();
+  const pendingConfirms = /* @__PURE__ */ new Map();
+  let busy = false;
+  const confirm = options.yolo ? async () => true : (description) => new Promise((resolveConfirm) => {
+    const id = randomBytes3(6).toString("hex");
+    const timer = setTimeout(() => settle(false), CONFIRM_TIMEOUT_MS);
+    const settle = (allow) => {
+      if (!pendingConfirms.has(id)) {
+        return;
+      }
+      clearTimeout(timer);
+      pendingConfirms.delete(id);
+      resolveConfirm(allow);
+    };
+    pendingConfirms.set(id, settle);
+    broadcast({ type: "confirm", id, description });
+    stdout2.write(`
+[confirm] Allow ${description}? Type y or n here, or answer from a client.
+`);
+  });
+  const session = new ChatSession({ model: options.model, workspaceRoot, confirm, resumeId });
+  session.on("tool", ({ name, input }) => {
+    stdout2.write(`
+[tool] ${name} ${JSON.stringify(input)}
+`);
+    broadcast({ type: "tool", name, input });
+  });
+  session.on("tool_result", ({ name, result }) => {
+    broadcast({ type: "tool_result", name, result });
+  });
+  const wss = options.cert && options.key ? new WebSocketServer({
+    server: createHttpsServer({
+      cert: readFileSync3(options.cert),
+      key: readFileSync3(options.key)
+    }).listen(port)
+  }) : new WebSocketServer({ port });
+  wss.on("connection", (socket, request) => {
+    const ip = request.socket.remoteAddress ?? "unknown";
+    if (isRateLimited(ip)) {
+      send(socket, { type: "error", text: "rate limited" });
+      socket.close();
+      return;
+    }
+    const nonce = generateNonce();
+    let attempts = 0;
+    let authed = false;
+    send(socket, { type: "challenge", nonce });
+    socket.on("message", (raw, isBinary) => {
+      void handleIncoming(isBinary ? raw.toString() : raw.toString("utf8"));
+    });
+    socket.on("close", () => clients.delete(socket));
+    async function handleIncoming(raw) {
+      let message;
+      try {
+        message = JSON.parse(raw);
+      } catch {
+        send(socket, { type: "error", text: "invalid message" });
+        return;
+      }
+      if (!authed) {
+        if (message.type !== "auth") {
+          send(socket, { type: "error", text: "expected auth" });
+          return;
+        }
+        attempts += 1;
+        recordAttempt(ip);
+        if (attempts > MAX_AUTH_ATTEMPTS || !verifyChallenge(token, nonce, message.hmac)) {
+          send(socket, { type: "error", text: "unauthorized" });
+          socket.close();
+          return;
+        }
+        authed = true;
+        clients.add(socket);
+        send(socket, {
+          type: "authed",
+          sessionId: session.sessionId,
+          workspace: workspaceRoot,
+          model: session.modelId,
+          history: session.renderHistory()
+        });
+        if (busy) {
+          send(socket, { type: "busy" });
+        }
+        stdout2.write("\n[remote client connected]\n");
+        return;
+      }
+      if (message.type === "confirm_reply") {
+        pendingConfirms.get(message.id)?.(message.allow);
+        return;
+      }
+      if (message.type === "user") {
+        if (busy) {
+          send(socket, { type: "error", text: "busy" });
+          return;
+        }
+        stdout2.write(`
+remote> ${message.text}
+`);
+        broadcast({ type: "user", text: message.text }, socket);
+        await runTurn(message.text);
+      }
+    }
+  });
+  async function runTurn(text) {
+    busy = true;
+    broadcast({ type: "busy" });
+    try {
+      const { reply } = await session.send(text);
+      broadcast({ type: "assistant", text: reply });
+      stdout2.write(`
+assistant> ${reply}
+
+`);
+    } catch (error) {
+      const text2 = error instanceof Error ? error.message : String(error);
+      broadcast({ type: "error", text: text2 });
+      stdout2.write(`
+[error] ${text2}
+
+`);
+    } finally {
+      busy = false;
+      broadcast({ type: "idle" });
+    }
+  }
+  function broadcast(message, except) {
+    for (const client of clients) {
+      if (client !== except) {
+        send(client, message);
+      }
+    }
+  }
+  function isRateLimited(ip) {
+    const now = Date.now();
+    const attempts = (attemptsByIp.get(ip) ?? []).filter((t) => now - t < RATE_LIMIT_WINDOW_MS);
+    attemptsByIp.set(ip, attempts);
+    return attempts.length >= RATE_LIMIT_MAX_ATTEMPTS;
+  }
+  function recordAttempt(ip) {
+    const attempts = attemptsByIp.get(ip) ?? [];
+    attempts.push(Date.now());
+    attemptsByIp.set(ip, attempts);
+  }
+  const scheme = options.cert && options.key ? "wss" : "ws";
+  stdout2.write(
+    `aiolah serve \u2014 listening on ${scheme}://localhost:${port}, workspace ${workspaceRoot}, session ${session.sessionId}
+Share this token with attach clients (never sent over the wire): ${token}
+Type here to chat locally too. Ctrl+C to stop.
+
+`
+  );
+  const hostRl = readline2.createInterface({ input: stdin2, output: stdout2 });
+  while (true) {
+    const input = await ask(hostRl, "you> ");
+    if (input === null) {
+      stdout2.write("[local stdin closed \u2014 serving remote clients only]\n");
+      return new Promise(() => {
+      });
+    }
+    const trimmed = input.trim();
+    if (!trimmed) {
+      continue;
+    }
+    const [pendingId] = pendingConfirms.keys();
+    if (pendingId !== void 0 && /^[yn]$/i.test(trimmed)) {
+      pendingConfirms.get(pendingId)?.(trimmed.toLowerCase() === "y");
+      continue;
+    }
+    if (busy) {
+      stdout2.write("[busy \u2014 wait for the current turn to finish]\n");
+      continue;
+    }
+    broadcast({ type: "user", text: input });
+    await runTurn(input);
+  }
+}
+function send(socket, message) {
+  socket.send(JSON.stringify(message));
+}
+
+// src/commands/attach.ts
+import * as readline3 from "readline/promises";
+import { stdin as stdin3, stdout as stdout3 } from "process";
+import WebSocket from "ws";
+var RESULT_PREVIEW_CHARS = 300;
+async function attachCommand(address) {
+  const rl = readline3.createInterface({ input: stdin3, output: stdout3 });
+  const token = process.env.AIOLAH_REMOTE_TOKEN ?? await rl.question("Remote token: ");
+  const socket = new WebSocket(address);
+  const pendingConfirms = [];
+  await new Promise((resolveOpen, reject) => {
+    socket.once("open", resolveOpen);
+    socket.once("error", reject);
+  });
+  const authed = new Promise((resolveAuthed, reject) => {
+    socket.on("message", (raw) => {
+      const message = JSON.parse(raw.toString());
+      switch (message.type) {
+        case "challenge":
+          send2(socket, { type: "auth", hmac: signChallenge(token, message.nonce) });
+          return;
+        case "authed":
+          stdout3.write(`session ${message.sessionId} \u2014 model ${message.model}, workspace ${message.workspace}
+`);
+          for (const item of message.history) {
+            renderHistoryItem(item);
+          }
+          resolveAuthed();
+          return;
+        case "error":
+          if (message.text === "unauthorized" || message.text === "rate limited") {
+            reject(new Error(message.text));
+          } else {
+            stdout3.write(`
+[error] ${message.text}
+`);
+          }
+          return;
+        case "user":
+          stdout3.write(`
+other> ${message.text}
+`);
+          return;
+        case "assistant":
+          stdout3.write(`
+assistant> ${message.text}
+
+`);
+          return;
+        case "tool":
+          stdout3.write(`
+[tool] ${message.name} ${JSON.stringify(message.input)}
+`);
+          return;
+        case "tool_result":
+          stdout3.write(`[tool_result] ${message.name}: ${preview(message.result)}
+`);
+          return;
+        case "confirm":
+          pendingConfirms.push(message.id);
+          stdout3.write(`
+[confirm] Allow ${message.description}? Type y or n.
+`);
+          return;
+        case "busy":
+          stdout3.write("[working\u2026]\n");
+          return;
+        case "idle":
+        case "auth":
+        case "confirm_reply":
+          return;
+      }
+    });
+  });
+  await authed;
+  stdout3.write(`aiolah attach \u2014 connected to ${address}. Type "exit" to quit.
+
+`);
+  try {
+    while (true) {
+      const input = await ask(rl, "you> ");
+      if (input === null || input.trim().toLowerCase() === "exit") {
+        break;
+      }
+      const trimmed = input.trim();
+      if (!trimmed) {
+        continue;
+      }
+      if (pendingConfirms.length > 0 && /^[yn]$/i.test(trimmed)) {
+        const id = pendingConfirms.shift();
+        send2(socket, { type: "confirm_reply", id, allow: trimmed.toLowerCase() === "y" });
+        continue;
+      }
+      send2(socket, { type: "user", text: input });
+    }
+  } finally {
+    rl.close();
+    socket.close();
+  }
+}
+function renderHistoryItem(item) {
+  if (item.role === "user") {
+    stdout3.write(`you> ${item.text}
+`);
+  } else if (item.role === "assistant") {
+    stdout3.write(`assistant> ${item.text}
+
+`);
+  } else {
+    stdout3.write(`[tool] ${item.name} ${JSON.stringify(item.input)} \u2192 ${preview(item.result)}
+`);
+  }
+}
+function preview(text) {
+  const flat = text.replace(/\s+/g, " ").trim();
+  return flat.length > RESULT_PREVIEW_CHARS ? `${flat.slice(0, RESULT_PREVIEW_CHARS)}\u2026` : flat;
+}
+function send2(socket, message) {
+  socket.send(JSON.stringify(message));
+}
+
+// src/commands/sessions.ts
+import { stdout as stdout4 } from "process";
+function sessionsListCommand() {
+  const sessions2 = listSessions();
+  if (sessions2.length === 0) {
+    stdout4.write("No saved sessions.\n");
+    return;
+  }
+  for (const session of sessions2) {
+    const firstUserMessage = session.history.find((message) => message.role === "user");
+    const snippet = typeof firstUserMessage?.content === "string" ? firstUserMessage.content.slice(0, 60) : "(tool result)";
+    stdout4.write(
+      `${session.id}  ${session.updatedAt}  ${session.workspace}
+  ${snippet}
+`
+    );
+  }
+}
+
+// src/cli.ts
+loadPackageEnv();
+var program = new Command();
+program.name("aiolah").description("Terminal AI CLI with remote control support").version("0.1.0");
+program.command("chat").description("Start an interactive chat session in this terminal").option("-m, --model <model>", "Anthropic model id", "claude-sonnet-5").option("-w, --workspace <dir>", "workspace root for file/bash tools", ".").option("--resume <id>", "resume a saved session by id").option("--continue", "resume the most recently updated session").option("--yolo", "skip confirmation prompts for write_file/edit_file/run_bash").action(chatCommand);
+program.command("serve").description('Host the current chat session so a remote "aiolah attach" client can join').option("-p, --port <port>", "port to listen on", "4317").option("-m, --model <model>", "Anthropic model id", "claude-sonnet-5").option("-w, --workspace <dir>", "workspace root for file/bash tools", ".").option("--resume <id>", "resume a saved session by id").option("--continue", "resume the most recently updated session").option("--yolo", "skip confirmation prompts for write_file/edit_file/run_bash").option("--cert <path>", "TLS certificate path (enables wss)").option("--key <path>", "TLS private key path (enables wss)").action(serveCommand);
+program.command("attach <address>").description('Attach to a running "aiolah serve" session, e.g. aiolah attach ws://host:4317').action(attachCommand);
+var sessions = program.command("sessions").description("Manage saved chat sessions");
+sessions.command("list").description("List saved sessions").action(sessionsListCommand);
+program.parse();
+function loadPackageEnv() {
+  const envPath = join3(dirname2(fileURLToPath(import.meta.url)), "..", ".env");
+  let contents;
+  try {
+    contents = readFileSync4(envPath, "utf8");
+  } catch {
+    return;
+  }
+  for (const [key, value] of Object.entries(parseEnv(contents))) {
+    process.env[key] ??= value;
+  }
+}

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@aiolah/cli",
+  "version": "0.1.0",
+  "description": "Terminal AI CLI with remote control support",
+  "type": "module",
+  "bin": {
+    "aiolah": "dist/cli.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ibnutron/aiocli.git"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "scripts": {
+    "build": "tsup src/cli.ts --format esm --target node22 --clean",
+    "prepublishOnly": "npm run build",
+    "dev": "tsx src/cli.ts",
+    "lint": "eslint .",
+    "format": "prettier --write .",
+    "typecheck": "tsc --noEmit"
+  },
+  "license": "MIT",
+  "dependencies": {
+    "@anthropic-ai/sdk": "^0.35.0",
+    "commander": "^13.0.0",
+    "ws": "^8.18.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "@types/ws": "^8.5.13",
+    "eslint": "^9.16.0",
+    "prettier": "^3.4.0",
+    "tsup": "^8.3.5",
+    "tsx": "^4.19.2",
+    "typescript": "^5.7.2",
+    "typescript-eslint": "^8.18.0"
+  }
+}