@soft-boy/agentschema 0.1.0 → 0.1.2

package/README.md

@@ -1,20 +1,133 @@
 # agentschema
 
+Define an AI-Agent as a folder of Markdown files.
+
+```
+my-agent/
+├── agent.md   # the agent
+└── env.md     # the environment it runs in
+```
+
+**Status:** v0.1 draft.
+
+## Philosophy
+
+1. **One folder, one agent.** A folder defines one agent and the one environment it runs in. Sessions, credentials, mounted files and repositories, and schedules are supplied by whatever runs the agent.
+2. **Everything is a Markdown file.** An agent is plain files you can read, diff, review and version like any other code. Structured settings go in YAML frontmatter, and prose the model reads goes in the Markdown body.
+3. **Inspired by Claude Managed Agents, not tied to it.** The fields follow the Claude Managed Agents schema because it's a well-documented vocabulary for agents. The format itself assumes no particular infrastructure, so any runtime that can read the files can run the agent.
+
 ## Install
 
 ```sh
 npm install -g @soft-boy/agentschema
 ```
 
+## Specification
+
+### Files
+
+An instance is a folder of Markdown files.
+
+```
+my-agent/
+├── agent.md   # the agent
+└── env.md     # the environment it runs in
+```
+
+### `agent.md`
+Field reference: [Agent setup](https://platform.claude.com/docs/en/managed-agents/agent-setup).
+
+- **Frontmatter** uses the fields of a Claude Managed Agents agent (the `POST /v1/agents` request body), written as YAML. `name` and `model` are required. Every other field (`description`, `tools`, `mcp_servers`, `skills`, `multiagent`, `metadata`, …) is optional and uses the same names and shapes.
+- **Body** is the agent's system prompt, sent as `system` exactly as written (leading and trailing whitespace trimmed). An empty body means no system prompt.
+- Setting `system` in the frontmatter is an error, because the body is the system prompt.
+
+### `env.md`
+Field reference: [Environments](https://platform.claude.com/docs/en/managed-agents/environments).
+
+- **Frontmatter** uses the fields of a Claude Managed Agents environment (the `POST /v1/environments` request body), written as YAML: `name`, `config`, and any other field the schema defines. 
+- **Body** is a note for people reading the folder. It is not sent anywhere.
+
 ## Usage
 
 ```sh
-agentschema
+agentschema init <name>               # scaffold a new agent folder
+agentschema check [dir]               # validate the folder, no network
+agentschema deploy [dir]              # create or update the agent and environment
+agentschema run [dir]                 # chat with the deployed agent in the terminal
+agentschema list                      # list the agents in your workspace
+agentschema delete <agent_id>         # archive an agent
+agentschema sessions list             # list the sessions in your workspace
+agentschema sessions delete <id>      # delete a session
+```
+
+`dir` defaults to the current directory.
+
+**`init`** creates the folder `<name>` with an `agent.md` and an `env.md` that pass `check`. It asks for:
+- the agent's name and model
+- its system prompt
+- whether it gets the built-in tools, and how tool calls are approved (`auto`, `always_allow` or `always_ask`)
+- the environment's name and networking
+
+Press Enter to keep the default shown, or pass `--yes` to skip the questions. `init` won't write into a folder that already has files in it.
+
+**`check`** reads both files and reports every problem it finds:
+- a missing file, or a name that isn't lowercase
+- frontmatter that is missing, unclosed, or invalid YAML
+- a missing `name` or `model`, or a `system` key in `agent.md`'s frontmatter
+- values over the API's limits
+- anything that looks like an API key or token
+
+Unknown fields are only warnings, because they're sent to the API as written. `check` exits with status 1 when there are errors.
+
+**`deploy`** runs `check` first, then creates or updates the environment and the agent, and records their IDs in `claude-lock.json` in the folder. Commit that file.
+- **Later runs update the same resources.** A file that hasn't changed since the last deploy is skipped. Each change to `agent.md` adds a new version of the agent, and sessions already running keep the version they started on.
+- **The files are the source of truth.** A field you delete from a file is cleared on the next deploy, rather than left at its old value.
+- **Changes made elsewhere aren't overwritten silently.** If the agent was changed outside the folder since the last deploy, `deploy` stops; `--force` overwrites it.
+
+`claude-lock.json` uses the same layout as `ant apply`'s, so `deploy` updates resources that `ant apply` created. The two tools hash files differently, though, so the first `deploy` after an `ant apply` updates both resources even if nothing changed.
+
+**`run`** starts a session on the agent and environment in `claude-lock.json`, then opens a chat in the terminal. Deploy first; if you've edited the files since, `run` warns you and still uses the deployed version.
+- **Messages:** type a message and press Enter. The agent's replies stream in, with a one-line summary of each tool call.
+- **Approvals:** when a tool call needs approval (`always_ask`, or `auto` when the server can't decide), `run` asks you. Answer `y` to allow it, or type a reason to deny it; the agent sees the reason.
+- **Custom tools:** `run` shows the call's input and asks you to type the result.
+- **Interrupting:** Ctrl+C interrupts the agent mid-turn, and a second Ctrl+C quits. Ctrl+D quits at the prompt.
+- **Resuming:** quitting leaves the session in place, and `run` prints a command to resume it: `agentschema run --resume sesn_…`.
+
+```sh
+agentschema run --resume sesn_…   # resume an existing session
 ```
 
+To run the agent from your own code, create a session with the agent and environment IDs from the lock file.
+
+**`list`** prints every agent in your workspace, with its ID, latest version, model and when it was last updated. It includes agents that weren't deployed with agentschema, and leaves out archived ones.
+
+**`sessions list`** prints every session in your workspace, newest first, with its status, the agent and version it runs, and its title. Pass an ID to `run --resume` to pick a session back up.
+
+**`delete`** archives an agent. The API can't delete agents outright, so this is as close as it gets. An archived agent drops out of `list`, and the API has no way to unarchive it. If the agent is in a folder's `claude-lock.json`, remove its entry so the next `deploy` creates a new one.
+
+**`sessions delete`** permanently deletes a session and its event history. A running session can't be deleted; wait for it to go idle, or interrupt it, first.
+
+Both ask for confirmation first, showing the agent's name or the session's title. Pass `--yes` to skip that, for example in scripts; without a terminal to ask in, they refuse unless you pass `--yes`.
+
+### Authentication
+
+agentschema has no account setting of its own. Every command except `init` and `check` uses whichever Anthropic credentials are in your shell:
+
+1. `ANTHROPIC_API_KEY`, if it's set
+2. otherwise, the profile you signed in to with `ant auth login` (the active one, or the one `ANTHROPIC_PROFILE` names)
+
+An API key belongs to one workspace, and the agent and environment are created in that workspace. Each person deploys with their own key, and to deploy somewhere else you switch the key:
+
+```sh
+ANTHROPIC_API_KEY=sk-ant-… agentschema deploy my-agent
+```
+
+`claude-lock.json` holds the IDs from one workspace. A committed lock works for everyone whose key is in that workspace, and they all update the same agent. If you deploy the folder from a key in a different workspace, `deploy` can't find those IDs and stops. In that case, deploy from a copy of the folder, or don't commit that lock file.
+
 ## Development
 
 ```sh
+npm install
+npm test    # unit tests; deploy runs against a fake API client
 npm link    # makes `agentschema` available globally from this checkout
-agentschema
 ```

package/bin/agentschema.js

@@ -1,3 +1,193 @@
 #!/usr/bin/env node
+import { readFileSync } from "node:fs";
+import { createInterface } from "node:readline/promises";
+import { parseArgs } from "node:util";
+import Anthropic from "@anthropic-ai/sdk";
+import { chat } from "../src/chat.js";
+import { check } from "../src/check.js";
+import { DeleteError, deleteAgent, deleteSession } from "../src/delete.js";
+import { DeployError, deploy } from "../src/deploy.js";
+import { InitError, init } from "../src/init.js";
+import { listAgents, listSessions } from "../src/list.js";
+import { SessionError, openSession } from "../src/session.js";
 
-console.log("hello world");
+const USAGE = `Usage: agentschema <command> [dir] [options]
+
+Commands:
+  init <name>           Scaffold a new agent folder, asking a few questions
+  check [dir]           Validate agent.md and env.md, without calling the API
+  deploy [dir]          Create or update the agent and environment, and write claude-lock.json
+  run [dir]             Chat with the deployed agent in a new session
+  list                  List the agents in your workspace
+  delete <agent_id>     Archive an agent (agents can't be deleted outright)
+  sessions list         List the sessions in your workspace, newest first
+  sessions delete <id>  Delete a session and its history
+
+Options:
+  -y, --yes         (init) Skip the questions and use the defaults
+                    (delete) Don't ask for confirmation
+  --dry-run         (deploy) Show what would be created or updated, change nothing
+  --force           (deploy) Update the agent even if it was changed outside this folder
+  --resume <id>     (run) Resume an existing session (sesn_...) instead of starting one
+  -h, --help        Show this help
+  -v, --version     Show the version
+
+dir defaults to the current directory. Every command but init and check authenticates with
+ANTHROPIC_API_KEY, or with a profile from \`ant auth login\`.`;
+
+const OPTIONS = {
+  yes: { type: "boolean", short: "y" },
+  "dry-run": { type: "boolean" },
+  force: { type: "boolean" },
+  resume: { type: "string" },
+  help: { type: "boolean", short: "h" },
+  version: { type: "boolean", short: "v" },
+};
+// For each command: how many positional arguments it takes, and which options.
+const COMMANDS = {
+  init: { args: [1, 1], options: ["yes"] },
+  check: { args: [0, 1], options: [] },
+  deploy: { args: [0, 1], options: ["dry-run", "force"] },
+  run: { args: [0, 1], options: ["resume"] },
+  list: { args: [0, 0], options: [] },
+  delete: { args: [1, 1], options: ["yes"] },
+  "sessions list": { args: [0, 0], options: [] },
+  "sessions delete": { args: [1, 1], options: ["yes"] },
+};
+
+async function main(argv) {
+  let parsed;
+  try {
+    parsed = parseArgs({ args: argv, options: OPTIONS, allowPositionals: true });
+  } catch (err) {
+    console.error(`agentschema: ${err.message}\n\n${USAGE}`);
+    return 1;
+  }
+  const { values, positionals } = parsed;
+  let [command, ...args] = positionals;
+  if (command === "sessions") command = `sessions ${args.shift() ?? ""}`.trim();
+
+  if (values.version) {
+    const pkg = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
+    console.log(pkg.version);
+    return 0;
+  }
+  if (!command || values.help) {
+    console.log(USAGE);
+    return command || values.help ? 0 : 1;
+  }
+  if (command.startsWith("sessions") && !(command in COMMANDS)) {
+    console.error(`agentschema: usage: agentschema sessions list | sessions delete <id>`);
+    return 1;
+  }
+  if (!(command in COMMANDS)) {
+    console.error(`agentschema: unknown command "${command}"\n\n${USAGE}`);
+    return 1;
+  }
+  const spec = COMMANDS[command];
+  const misplaced = Object.keys(values).filter((k) => !spec.options.includes(k));
+  if (args.length > spec.args[1] || misplaced.length > 0) {
+    const arg = args[spec.args[1]] ?? `--${misplaced[0]}`;
+    console.error(`agentschema: unexpected argument ${arg} for ${command}\n\n${USAGE}`);
+    return 1;
+  }
+  if (args.length < spec.args[0]) {
+    const example = { init: "init my-agent", delete: "delete agent_…", "sessions delete": "sessions delete sesn_…" }[command];
+    console.error(`agentschema: ${command} needs an argument, e.g. agentschema ${example}`);
+    return 1;
+  }
+  const dir = args[0] ?? ".";
+
+  if (command === "init") {
+    try {
+      await init(dir, { yes: values.yes ?? false });
+      return 0;
+    } catch (err) {
+      if (!(err instanceof InitError)) throw err;
+      console.error(`error: ${err.message}`);
+      return 1;
+    }
+  }
+
+  if (command === "check") {
+    const { errors, warnings } = check(dir);
+    for (const w of warnings) console.warn(`warning: ${w}`);
+    for (const e of errors) console.error(`error: ${e}`);
+    if (errors.length > 0) return 1;
+    console.log(`${dir}: ok`);
+    return 0;
+  }
+
+  try {
+    if (command === "deploy") {
+      for (const w of check(dir).warnings) console.warn(`warning: ${w}`);
+      const dryRun = values["dry-run"] ?? false;
+      await deploy(dir, {
+        client: makeClient(dryRun),
+        dryRun,
+        force: values.force ?? false,
+        log: (line) => console.log(line),
+      });
+      return 0;
+    }
+
+    if (command === "list" || command === "sessions list") {
+      const lines = command === "list" ? await listAgents(makeClient(false)) : await listSessions(makeClient(false));
+      for (const line of lines) console.log(line);
+      return 0;
+    }
+
+    if (command === "delete" || command === "sessions delete") {
+      const remove = command === "delete" ? deleteAgent : deleteSession;
+      await remove(makeClient(false), args[0], {
+        confirm: values.yes ? async () => true : confirm,
+        log: (line) => console.log(line),
+      });
+      return 0;
+    }
+
+    if (command === "run") {
+      const client = makeClient(false);
+      const { session, notes } = await openSession(dir, {
+        client,
+        sessionId: values.resume,
+      });
+      for (const note of notes) console.warn(`warning: ${note}`);
+      await chat(client, session, { agentName: session.agent?.name ?? "agent" });
+      return 0;
+    }
+  } catch (err) {
+    if (err instanceof Anthropic.APIError) {
+      console.error(`error: ${err.status ?? "network error"}: ${err.error?.error?.message ?? err.message}`);
+      return 1;
+    }
+    if (err instanceof DeployError || err instanceof DeleteError || err instanceof SessionError || err instanceof Anthropic.AnthropicError) {
+      console.error(`error: ${err.message}`);
+      return 1;
+    }
+    throw err;
+  }
+}
+
+// Asks a yes/no question in the terminal; without one, there's no one to ask.
+async function confirm(question) {
+  if (!process.stdin.isTTY) throw new DeleteError("not a terminal, so can't ask for confirmation; pass --yes");
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  try {
+    return /^(y|yes)$/i.test((await rl.question(`${question} [y/N] `)).trim());
+  } finally {
+    rl.close();
+  }
+}
+
+// A dry run makes no API calls, so it works without credentials.
+function makeClient(dryRun) {
+  try {
+    return new Anthropic();
+  } catch (err) {
+    if (!dryRun) throw err;
+    return { baseURL: process.env.ANTHROPIC_BASE_URL ?? "https://api.anthropic.com" };
+  }
+}
+
+process.exitCode = await main(process.argv.slice(2));

package/package.json

@@ -1,13 +1,14 @@
 {
   "name": "@soft-boy/agentschema",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Markdown based AI agent schema",
   "type": "module",
   "bin": {
     "agentschema": "bin/agentschema.js"
   },
   "files": [
-    "bin"
+    "bin",
+    "src"
   ],
   "engines": {
     "node": ">=18"
@@ -15,5 +16,12 @@
   "license": "MIT",
   "publishConfig": {
     "access": "public"
+  },
+  "dependencies": {
+    "@anthropic-ai/sdk": "^1.4.0",
+    "yaml": "^2.9.1"
+  },
+  "scripts": {
+    "test": "node --test test/*.test.js"
   }
 }

package/src/chat.js

@@ -0,0 +1,135 @@
+import { createInterface } from "node:readline";
+import { Conversation } from "./session.js";
+
+const color = (code) => (text) => (process.stdout.isTTY ? `\x1b[${code}m${text}\x1b[0m` : text);
+const dim = color(2);
+const red = color(31);
+const bold = color(1);
+
+// Prints a session's events as a terminal transcript.
+export function formatEvent(event) {
+  switch (event.type) {
+    case "agent.message":
+      return event.content.filter((b) => b.type === "text").map((b) => b.text).join("");
+    case "agent.tool_use":
+    case "agent.mcp_tool_use": {
+      const name = event.type === "agent.mcp_tool_use" ? `${event.mcp_server_name}.${event.name}` : event.name;
+      const denied = event.evaluated_permission === "deny" ? red(" (denied)") : "";
+      return dim(`· ${name} ${summarize(event.input)}`) + denied;
+    }
+    case "agent.custom_tool_use":
+      return dim(`· ${event.name} ${summarize(event.input)}`);
+    case "agent.tool_result":
+    case "agent.mcp_tool_result":
+      if (!event.is_error) return null;
+      return red(`  ↳ ${firstLine(event.content)}`);
+    case "session.error":
+      return red(`error: ${event.error?.message ?? event.error?.type ?? "unknown error"}`);
+    case "session.status_idle": {
+      const reason = event.stop_reason?.type;
+      if (reason === "retries_exhausted") return red("The agent gave up after repeated errors.");
+      if (reason === "budget_reached") return red("The session reached its budget and paused.");
+      return null;
+    }
+    case "session.status_terminated":
+      return dim("The session has ended.");
+    default:
+      return null;
+  }
+}
+
+// One line describing a tool call's input: the command, path or query when there is one.
+function summarize(input = {}) {
+  for (const key of ["command", "file_path", "path", "pattern", "url", "query"]) {
+    if (typeof input[key] === "string") return truncate(input[key]);
+  }
+  return truncate(JSON.stringify(input));
+}
+
+function firstLine(content = []) {
+  const text = content.find((b) => b.type === "text")?.text ?? "tool error";
+  return truncate(text.split("\n")[0]);
+}
+
+const truncate = (s, n = 100) => (s.length > n ? `${s.slice(0, n - 1)}…` : s);
+
+// Runs an interactive chat in the terminal until the user quits or the session ends.
+export async function chat(client, session, { agentName, input = process.stdin, output = process.stdout }) {
+  const rl = createInterface({ input, output, terminal: input.isTTY });
+  const lines = rl[Symbol.asyncIterator]();
+  let running = false;
+  let interrupted = false;
+  let quit = false;
+
+  const ask = async (prompt) => {
+    output.write(prompt);
+    const { value, done } = await lines.next();
+    if (done) quit = true;
+    return done ? null : value;
+  };
+
+  const ui = {
+    event(event) {
+      const text = formatEvent(event);
+      if (text) output.write(`${text}\n`);
+    },
+    async confirm(event) {
+      const answer = await ask(bold(`Allow ${event.name}? `) + dim("[y/N, or type why not] "));
+      if (answer && /^(y|yes)$/i.test(answer.trim())) return { result: "allow" };
+      const reason = answer?.trim();
+      return { result: "deny", deny_message: reason && !/^(n|no)$/i.test(reason) ? reason : undefined };
+    },
+    async customToolResult(event) {
+      output.write(dim(`${event.name} is a custom tool, so you supply its result.\n`));
+      output.write(dim(`input: ${JSON.stringify(event.input)}\n`));
+      return (await ask(bold("result> "))) ?? "The user didn't provide a result.";
+    },
+  };
+
+  const conversation = new Conversation(client, session.id, ui);
+  let ended = false;
+
+  // Ctrl+C interrupts the agent while it works; a second Ctrl+C, or one at the prompt, quits.
+  rl.on("SIGINT", () => {
+    if (running && !interrupted) {
+      interrupted = true;
+      output.write(dim("\nInterrupting… (Ctrl+C again to quit)\n"));
+      conversation.interrupt().catch(() => {});
+      return;
+    }
+    quit = true;
+    conversation.close();
+    rl.close();
+  });
+
+  output.write(dim(`${agentName} · session ${session.id}\nCtrl+C interrupts the agent, Ctrl+D quits.\n\n`));
+
+  try {
+    while (!quit) {
+      const text = await ask(bold("> "));
+      if (text === null) break;
+      if (text.trim() === "") continue;
+
+      running = true;
+      interrupted = false;
+      let outcome;
+      try {
+        outcome = await conversation.send(text);
+      } catch (err) {
+        if (quit) break;
+        throw err;
+      } finally {
+        running = false;
+      }
+      output.write("\n");
+      if (outcome === "terminated") {
+        ended = true;
+        break;
+      }
+    }
+  } finally {
+    conversation.close();
+    rl.close();
+  }
+  if (!ended) output.write(dim(`Resume this conversation with: agentschema run --resume ${session.id}\n`));
+}

package/src/check.js

@@ -0,0 +1,107 @@
+import { AGENT_FILE, ENV_FILE, readInstance } from "./instance.js";
+
+const AGENT_FIELDS = new Set([
+  "name", "model", "description", "tools", "mcp_servers", "skills",
+  "multiagent", "metadata", "execution_identity",
+]);
+const ENV_FIELDS = new Set(["name", "config", "description", "metadata", "scope"]);
+
+const SECRET_PATTERNS = [
+  [/sk-ant-[A-Za-z0-9_-]{8,}/, "an Anthropic API key"],
+  [/\bghp_[A-Za-z0-9]{20,}/, "a GitHub token"],
+  [/\bgithub_pat_[A-Za-z0-9_]{20,}/, "a GitHub token"],
+  [/\bxox[bpas]-[A-Za-z0-9-]{10,}/, "a Slack token"],
+  [/\bAKIA[0-9A-Z]{16}\b/, "an AWS access key"],
+];
+
+const isObject = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+
+// Validates an instance folder without calling the API.
+// Returns { errors, warnings, instance }; instance is null when the files can't be read.
+export function check(dir) {
+  const { agent, env, errors } = readInstance(dir);
+  const warnings = [];
+
+  if (agent) checkAgent(agent, errors, warnings);
+  if (env) checkEnv(env, errors, warnings);
+  for (const [file, parsed] of [[AGENT_FILE, agent], [ENV_FILE, env]]) {
+    if (!parsed) continue;
+    for (const [pattern, what] of SECRET_PATTERNS) {
+      if (pattern.test(parsed.raw)) errors.push(`${file}: looks like it contains ${what}; keep secrets out of these files`);
+    }
+  }
+
+  return { errors, warnings, instance: agent && env ? { agent, env } : null };
+}
+
+function checkAgent({ data, body }, errors, warnings) {
+  const err = (msg) => errors.push(`${AGENT_FILE}: ${msg}`);
+
+  if (typeof data.name !== "string" || data.name.trim() === "") err("`name` is required");
+  else if (data.name.length > 256) err("`name` must be at most 256 characters");
+
+  if (data.model === undefined) err("`model` is required");
+  else if (isObject(data.model) ? typeof data.model.id !== "string" : typeof data.model !== "string") {
+    err("`model` must be a model ID, or a mapping with an `id`");
+  }
+
+  if ("system" in data) err("`system` is not allowed in frontmatter; the Markdown body is the system prompt");
+  if (body.length > 100_000) err(`system prompt is ${body.length} characters; the limit is 100,000`);
+
+  if (data.description !== undefined && data.description !== null) {
+    if (typeof data.description !== "string") err("`description` must be a string");
+    else if (data.description.length > 2048) err("`description` must be at most 2048 characters");
+  }
+
+  for (const [field, max] of [["tools", 256], ["mcp_servers", 20], ["skills", 500]]) {
+    if (data[field] === undefined) continue;
+    if (!Array.isArray(data[field])) err(`\`${field}\` must be a list`);
+    else if (data[field].length > max) err(`\`${field}\` has ${data[field].length} entries; the limit is ${max}`);
+  }
+
+  checkMetadata(data.metadata, 16, err);
+
+  for (const key of Object.keys(data)) {
+    if (!AGENT_FIELDS.has(key) && key !== "system") {
+      warnings.push(`${AGENT_FILE}: unknown field \`${key}\` will be sent to the API as written`);
+    }
+  }
+}
+
+function checkEnv({ data }, errors, warnings) {
+  const err = (msg) => errors.push(`${ENV_FILE}: ${msg}`);
+
+  if (typeof data.name !== "string" || data.name.trim() === "") err("`name` is required");
+
+  if (data.config !== undefined) {
+    const { config } = data;
+    if (!isObject(config)) err("`config` must be a mapping");
+    else {
+      if (!["cloud", "self_hosted"].includes(config.type)) err("`config.type` must be `cloud` or `self_hosted`");
+      const net = config.networking;
+      if (net !== undefined && !(isObject(net) && ["limited", "unrestricted"].includes(net.type))) {
+        err("`config.networking.type` must be `limited` or `unrestricted`");
+      }
+    }
+  }
+
+  if (data.description !== undefined && data.description !== null && typeof data.description !== "string") {
+    err("`description` must be a string");
+  }
+
+  checkMetadata(data.metadata, Infinity, err);
+
+  for (const key of Object.keys(data)) {
+    if (!ENV_FIELDS.has(key)) warnings.push(`${ENV_FILE}: unknown field \`${key}\` will be sent to the API as written`);
+  }
+}
+
+function checkMetadata(metadata, maxKeys, err) {
+  if (metadata === undefined) return;
+  if (!isObject(metadata)) return err("`metadata` must be a mapping");
+  const keys = Object.keys(metadata);
+  if (keys.length > maxKeys) err(`\`metadata\` has ${keys.length} keys; the limit is ${maxKeys}`);
+  for (const key of keys) {
+    if (typeof metadata[key] !== "string") err(`\`metadata.${key}\` must be a string (quote numbers and booleans)`);
+  }
+}

package/src/delete.js

@@ -0,0 +1,25 @@
+export class DeleteError extends Error {}
+
+// Agents can't be deleted, only archived: an archived agent drops out of `list`, and
+// there's no unarchive. `confirm(question)` resolves to true to go ahead.
+export async function deleteAgent(client, agentId, { confirm, log }) {
+  const agent = await client.beta.agents.retrieve(agentId);
+  if (agent.archived_at) throw new DeleteError(`${agentId} is already archived`);
+  const ok = await confirm(`Archive agent "${agent.name}" (${agentId})? It can't be undone.`);
+  if (!ok) return log("Nothing changed.");
+  await client.beta.agents.archive(agentId);
+  log(`Archived ${agentId}.`);
+}
+
+// Deletes a session and its event history for good.
+export async function deleteSession(client, sessionId, { confirm, log }) {
+  const session = await client.beta.sessions.retrieve(sessionId);
+  if (session.status === "running") {
+    throw new DeleteError(`${sessionId} is running; wait for it to go idle, or interrupt it, then try again`);
+  }
+  const label = session.title ? `"${session.title}" (${sessionId})` : sessionId;
+  const ok = await confirm(`Delete session ${label} and its history? It can't be undone.`);
+  if (!ok) return log("Nothing changed.");
+  await client.beta.sessions.delete(sessionId);
+  log(`Deleted ${sessionId}.`);
+}

package/src/deploy.js

@@ -0,0 +1,143 @@
+import Anthropic from "@anthropic-ai/sdk";
+import { check } from "./check.js";
+import { AGENT_FILE, ENV_FILE, agentBody, envBody } from "./instance.js";
+import { LOCK_FILE, hashBody, readLock, writeLock } from "./lock.js";
+
+export class DeployError extends Error {}
+
+// Creates or updates the environment and agent a folder defines, recording their IDs in claude-lock.json.
+// Returns the plan: one { file, kind, action, id, version } entry per resource.
+export async function deploy(dir, { client, dryRun = false, force = false, log = () => {} }) {
+  const { errors, instance } = check(dir);
+  if (errors.length > 0) throw new DeployError(`check failed:\n  ${errors.join("\n  ")}`);
+
+  const baseURL = client.baseURL;
+  const lock = readLock(dir) ?? { version: 1, origin: { base_url: baseURL }, resources: {} };
+  lock.resources ??= {};
+  if (lock.origin?.base_url && lock.origin.base_url !== baseURL) {
+    throw new DeployError(
+      `${LOCK_FILE} was written for ${lock.origin.base_url}, but this client uses ${baseURL}`,
+    );
+  }
+
+  const steps = [
+    { file: ENV_FILE, kind: "environment", body: envBody(instance.env) },
+    { file: AGENT_FILE, kind: "agent", body: agentBody(instance.agent) },
+  ];
+  for (const step of steps) {
+    step.key = `./${step.file}`;
+    step.hash = hashBody(step.body);
+    step.entry = lock.resources[step.key];
+    if (step.entry && step.entry.kind !== step.kind) {
+      throw new DeployError(`${LOCK_FILE}: entry for ${step.key} is a ${step.entry.kind}, expected ${step.kind}`);
+    }
+    step.action = !step.entry ? "create" : step.entry.hash === step.hash ? "unchanged" : "update";
+  }
+
+  for (const step of steps) {
+    if (dryRun || step.action === "unchanged") {
+      log(`${step.action.padEnd(9)} ${step.kind} ${step.entry?.id ?? ""}`.trimEnd());
+      continue;
+    }
+    const result = step.kind === "environment"
+      ? await deployEnvironment(client, step)
+      : await deployAgent(client, step, force);
+
+    lock.resources[step.key] = step.kind === "agent"
+      ? { kind: "agent", id: result.id, version: String(result.version), hash: step.hash }
+      : { kind: "environment", id: result.id, hash: step.hash };
+    // Record each resource as soon as it exists, so a failure later doesn't orphan it.
+    writeLock(dir, lock);
+
+    const version = step.kind === "agent" ? ` (version ${result.version})` : "";
+    log(`${(step.action === "create" ? "created" : "updated").padEnd(9)} ${step.kind} ${result.id}${version}`);
+  }
+
+  return steps.map(({ file, kind, action, key }) => ({
+    file, kind, action,
+    id: lock.resources[key]?.id,
+    version: lock.resources[key]?.version,
+  }));
+}
+
+async function deployEnvironment(client, step) {
+  if (step.action === "create") return call(step, () => client.beta.environments.create(step.body));
+
+  const { id } = step.entry;
+  const remote = await retrieve(step, () => client.beta.environments.retrieve(id));
+  const body = { ...step.body };
+  // Updates keep any field you omit, so clear what was removed from env.md.
+  if (!("description" in body)) body.description = null;
+  body.metadata = metadataWithDeletions(body.metadata, remote.metadata);
+  return call(step, () => client.beta.environments.update(id, body));
+}
+
+async function deployAgent(client, step, force) {
+  if (step.action === "create") return call(step, () => client.beta.agents.create(step.body));
+
+  const { id, version } = step.entry;
+  const remote = await retrieve(step, () => client.beta.agents.retrieve(id));
+  const body = { ...step.body };
+  // Updates keep any field you omit, so clear what was removed from agent.md.
+  if (!("system" in body)) body.system = null;
+  for (const field of ["description", "multiagent"]) if (!(field in body)) body[field] = null;
+  for (const field of ["tools", "mcp_servers", "skills"]) if (!(field in body)) body[field] = [];
+  body.metadata = metadataWithDeletions(body.metadata, remote.metadata);
+  // Sending the locked version makes the API refuse the update if someone changed the agent since.
+  if (!force && version !== undefined) body.version = Number(version);
+
+  try {
+    return await client.beta.agents.update(id, body);
+  } catch (err) {
+    if (err instanceof Anthropic.APIError && err.status === 409) {
+      throw new DeployError(
+        `agent ${id} was changed outside this folder (${LOCK_FILE} has version ${version}, ` +
+          `the agent is at version ${remote.version}). Re-run with --force to overwrite it.`,
+      );
+    }
+    throw apiError(step, err);
+  }
+}
+
+// Metadata updates merge, so keys removed from the file are sent as null to delete them.
+function metadataWithDeletions(local = {}, remote = {}) {
+  const merged = { ...local };
+  for (const key of Object.keys(remote ?? {})) if (!(key in merged)) merged[key] = null;
+  return merged;
+}
+
+async function retrieve(step, fn) {
+  let remote;
+  try {
+    remote = await fn();
+  } catch (err) {
+    if (err instanceof Anthropic.APIError && err.status === 404) {
+      throw new DeployError(
+        `${step.kind} ${step.entry.id} in ${LOCK_FILE} no longer exists. ` +
+          `Remove the "${step.key}" entry from ${LOCK_FILE} to create a new one.`,
+      );
+    }
+    throw apiError(step, err);
+  }
+  if (remote.archived_at) {
+    throw new DeployError(
+      `${step.kind} ${step.entry.id} is archived and can't be updated. ` +
+        `Remove the "${step.key}" entry from ${LOCK_FILE} to create a new one.`,
+    );
+  }
+  return remote;
+}
+
+async function call(step, fn) {
+  try {
+    return await fn();
+  } catch (err) {
+    throw apiError(step, err);
+  }
+}
+
+function apiError(step, err) {
+  if (!(err instanceof Anthropic.APIError)) return err;
+  const message = err.error?.error?.message ?? err.message;
+  return new DeployError(`${step.file}: the API rejected the ${step.kind} (${err.status ?? "network error"}): ${message}`);
+}

package/src/init.js

@@ -0,0 +1,186 @@
+import { existsSync, mkdirSync, readdirSync, writeFileSync } from "node:fs";
+import { basename, resolve } from "node:path";
+import { createInterface, emitKeypressEvents } from "node:readline";
+import { stringify } from "yaml";
+import { AGENT_FILE, ENV_FILE } from "./instance.js";
+
+export class InitError extends Error {}
+
+export const MODELS = ["claude-opus-5-5", "claude-sonnet-5-5", "claude-haiku-5-5"];
+export const APPROVALS = ["auto", "always_allow", "always_ask"];
+export const NETWORKING = ["limited", "unrestricted"];
+
+// The answers used when a question is skipped (--yes, or input ends early).
+export function defaults(dir) {
+  const slug = basename(resolve(dir)).toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "") || "agent";
+  return {
+    name: slug.split("-").map((w) => w[0].toUpperCase() + w.slice(1)).join(" "),
+    model: MODELS[0],
+    system: "You are a helpful assistant.",
+    tools: true,
+    approval: "auto",
+    environment: slug,
+    networking: "limited",
+    packageManagers: true,
+  };
+}
+
+// Returns { "agent.md": text, "env.md": text } for a set of answers.
+export function scaffold(answers) {
+  const agent = { name: answers.name, model: answers.model };
+  if (answers.tools) {
+    const toolset = { type: "agent_toolset_20260401" };
+    // always_allow is the toolset's default, so it needs no config.
+    if (answers.approval !== "always_allow") toolset.default_config = { permission_policy: { type: answers.approval } };
+    agent.tools = [toolset];
+  }
+
+  const networking = { type: answers.networking };
+  if (answers.networking === "limited") networking.allow_package_managers = answers.packageManagers;
+  const env = { name: answers.environment, config: { type: "cloud", networking } };
+
+  const access = answers.networking === "unrestricted"
+    ? "unrestricted network access"
+    : answers.packageManagers ? "limited networking and package manager access" : "limited networking";
+  return {
+    [AGENT_FILE]: `---\n${stringify(agent)}---\n\n${answers.system.trim()}\n`,
+    [ENV_FILE]: `---\n${stringify(env)}---\nCloud container with ${access}.\n`,
+  };
+}
+
+// Asks the setup questions, then writes agent.md and env.md into a new folder `dir`.
+export async function init(dir, { yes = false, input = process.stdin, output = process.stdout } = {}) {
+  if (existsSync(dir) && readdirSync(dir).length > 0) {
+    throw new InitError(`${dir} already exists and isn't empty`);
+  }
+
+  const answers = defaults(dir);
+  if (!yes) await ask(answers, input, output);
+
+  mkdirSync(dir, { recursive: true });
+  const files = scaffold(answers);
+  for (const [file, text] of Object.entries(files)) writeFileSync(resolve(dir, file), text);
+
+  output.write(`\nCreated ${dir}/${AGENT_FILE} and ${dir}/${ENV_FILE}.\n\nNext:\n`);
+  output.write(`  agentschema deploy ${dir}\n  agentschema run ${dir}\n`);
+  return files;
+}
+
+// Fills in `answers` from the user's replies; an empty reply keeps the default shown.
+async function ask(answers, input, output) {
+  const io = input.isTTY ? terminalPrompts(input, output) : linePrompts(input, output);
+  const confirm = async (question, fallback) => {
+    while (true) {
+      const reply = (await io.text(`${question} [y/n]`, fallback ? "y" : "n")).toLowerCase();
+      if (/^(y|yes)$/.test(reply)) return true;
+      if (/^(n|no)$/.test(reply)) return false;
+      output.write("Answer y or n\n");
+    }
+  };
+
+  try {
+    answers.name = await io.text("Agent name?", answers.name);
+    answers.model = await io.select("Model?", MODELS, answers.model);
+    answers.system = await io.text("System prompt?", answers.system);
+    answers.tools = await confirm("Give it the built-in tools (bash, files, web)?", answers.tools);
+    if (answers.tools) answers.approval = await io.select("Tool approvals?", APPROVALS, answers.approval);
+    answers.environment = await io.text("Environment name?", answers.environment);
+    answers.networking = await io.select("Networking?", NETWORKING, answers.networking);
+    if (answers.networking === "limited") {
+      answers.packageManagers = await confirm("Allow package managers (npm, pip, …)?", answers.packageManagers);
+    }
+  } finally {
+    io.close();
+  }
+}
+
+// Prompts for piped input: one answer per line, and choices picked by name or number.
+function linePrompts(input, output) {
+  const rl = createInterface({ input, output, terminal: false });
+  const lines = rl[Symbol.asyncIterator]();
+  let ended = false;
+
+  const text = async (question, fallback) => {
+    if (ended) return fallback;
+    output.write(`${question} (${fallback}) `);
+    const { value, done } = await lines.next();
+    if (done) {
+      ended = true;
+      output.write("\n");
+      return fallback;
+    }
+    return value.trim() || fallback;
+  };
+  const select = async (question, choices, fallback) => {
+    const listed = choices.map((c, i) => `${i + 1}) ${c}`).join("  ");
+    while (true) {
+      const reply = await text(`${question} ${listed}`, String(choices.indexOf(fallback) + 1));
+      const picked = choices[Number(reply) - 1] ?? choices.find((c) => c === reply);
+      if (picked) return picked;
+      output.write(`Pick one of: ${choices.join(", ")}\n`);
+    }
+  };
+  return { text, select, close: () => rl.close() };
+}
+
+const ESC = "\x1b[";
+const cyan = (s) => `${ESC}36m${s}${ESC}0m`;
+const dim = (s) => `${ESC}2m${s}${ESC}0m`;
+
+// Prompts for a terminal: choices are picked with the arrow keys and Enter.
+function terminalPrompts(input, output) {
+  const cancelled = () => new InitError("cancelled");
+
+  // A fresh readline per question, so it doesn't fight the raw-mode select for the arrow keys.
+  const text = (question, fallback) =>
+    new Promise((resolve, reject) => {
+      const rl = createInterface({ input, output, terminal: true });
+      rl.on("SIGINT", () => {
+        rl.close();
+        output.write("\n");
+        reject(cancelled());
+      });
+      rl.question(`${question} ${dim(`(${fallback})`)} `, (reply) => {
+        rl.close();
+        resolve(reply.trim() || fallback);
+      });
+    });
+
+  const select = (question, choices, fallback) =>
+    new Promise((resolve, reject) => {
+      let index = Math.max(0, choices.indexOf(fallback));
+      const render = (first) => {
+        if (!first) output.write(`${ESC}${choices.length}A`);
+        for (const [i, choice] of choices.entries()) {
+          output.write(`${ESC}2K${i === index ? cyan(`❯ ${choice}`) : `  ${choice}`}\n`);
+        }
+      };
+      const finish = (err) => {
+        input.off("keypress", onKey);
+        input.setRawMode(false);
+        input.pause();
+        // Collapse the list to one line with the answer.
+        output.write(`${ESC}${choices.length + 1}A${ESC}J${ESC}?25h`);
+        output.write(`${question} ${err ? dim("cancelled") : cyan(choices[index])}\n`);
+        err ? reject(err) : resolve(choices[index]);
+      };
+      const onKey = (str, key = {}) => {
+        if (key.ctrl && key.name === "c") return finish(cancelled());
+        if (key.name === "return" || key.name === "enter") return finish();
+        if (key.name === "up" || key.name === "k") index = (index - 1 + choices.length) % choices.length;
+        else if (key.name === "down" || key.name === "j" || key.name === "tab") index = (index + 1) % choices.length;
+        else if (/^[1-9]$/.test(str ?? "") && Number(str) <= choices.length) index = Number(str) - 1;
+        else return;
+        render(false);
+      };
+
+      emitKeypressEvents(input);
+      input.setRawMode(true);
+      input.resume();
+      output.write(`${question} ${dim("(↑/↓, Enter)")}\n${ESC}?25l`);
+      render(true);
+      input.on("keypress", onKey);
+    });
+
+  return { text, select, close() {} };
+}

package/src/instance.js

@@ -0,0 +1,78 @@
+import { readFileSync, readdirSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { parseDocument } from "yaml";
+
+export const AGENT_FILE = "agent.md";
+export const ENV_FILE = "env.md";
+
+export class FileError extends Error {}
+
+// Splits a Markdown file into YAML frontmatter (between `---` fences) and body.
+export function parseMarkdown(text, file) {
+  const normalized = text.replace(/^/, "").replace(/\r\n/g, "\n");
+  if (!normalized.startsWith("---\n")) {
+    throw new FileError(`${file}: must start with YAML frontmatter between --- lines`);
+  }
+  const closing = /^---[ \t]*$/m.exec(normalized.slice(4));
+  if (!closing) throw new FileError(`${file}: frontmatter is not closed with a --- line`);
+  const end = 4 + closing.index;
+  const afterFence = normalized.slice(end + closing[0].length);
+
+  const doc = parseDocument(normalized.slice(4, end));
+  if (doc.errors.length > 0) {
+    // The YAML library counts lines from the start of the frontmatter; +1 for the opening fence.
+    const err = doc.errors[0];
+    const line = err.linePos?.[0]?.line;
+    const where = line ? `:${line + 1}` : "";
+    throw new FileError(`${file}${where}: invalid YAML: ${err.message.split("\n")[0]}`);
+  }
+
+  const data = doc.toJS() ?? {};
+  if (typeof data !== "object" || Array.isArray(data)) {
+    throw new FileError(`${file}: frontmatter must be a YAML mapping (key: value pairs)`);
+  }
+  return { data, body: afterFence.trim(), raw: text };
+}
+
+// Reads agent.md and env.md from an instance folder.
+// Returns { agent, env, errors }; a file that can't be read is null and has an entry in errors.
+export function readInstance(dir) {
+  let stat;
+  try {
+    stat = statSync(dir);
+  } catch {
+    return { agent: null, env: null, errors: [`${dir}: no such directory`] };
+  }
+  if (!stat.isDirectory()) return { agent: null, env: null, errors: [`${dir}: not a directory`] };
+
+  // Compare exact names: macOS file systems would otherwise open AGENT.md as agent.md.
+  const names = readdirSync(dir);
+  const errors = [];
+  const read = (name) => {
+    try {
+      if (!names.includes(name)) {
+        const wrongCase = names.find((n) => n.toLowerCase() === name);
+        const hint = wrongCase ? ` (found ${wrongCase}; the name must be lowercase)` : "";
+        throw new FileError(`${name}: missing${hint}`);
+      }
+      return parseMarkdown(readFileSync(join(dir, name), "utf8"), name);
+    } catch (err) {
+      if (!(err instanceof FileError)) throw err;
+      errors.push(err.message);
+      return null;
+    }
+  };
+
+  return { agent: read(AGENT_FILE), env: read(ENV_FILE), errors };
+}
+
+// The bodies sent to POST /v1/agents and POST /v1/environments.
+export function agentBody(agent) {
+  const body = { ...agent.data };
+  if (agent.body) body.system = agent.body;
+  return body;
+}
+
+export function envBody(env) {
+  return { ...env.data };
+}

package/src/list.js

@@ -0,0 +1,49 @@
+// Lists the agents and sessions in the workspace the credentials belong to.
+
+export async function listAgents(client) {
+  const rows = [];
+  for await (const agent of client.beta.agents.list()) {
+    rows.push({
+      name: agent.name,
+      id: agent.id,
+      version: String(agent.version),
+      model: agent.model?.id ?? "",
+      updated: formatDate(agent.updated_at),
+    });
+  }
+  return table(rows, { name: "NAME", id: "ID", version: "VERSION", model: "MODEL", updated: "UPDATED" }, "No agents.");
+}
+
+export async function listSessions(client) {
+  const rows = [];
+  // Newest first, the API's default order.
+  for await (const session of client.beta.sessions.list()) {
+    rows.push({
+      id: session.id,
+      status: session.status,
+      agent: session.agent ? `${session.agent.name} v${session.agent.version}` : "",
+      title: truncate(session.title ?? "", 40),
+      created: formatDate(session.created_at),
+    });
+  }
+  return table(rows, { id: "ID", status: "STATUS", agent: "AGENT", title: "TITLE", created: "CREATED" }, "No sessions.");
+}
+
+// Lines of a plain-text table, with columns padded to their widest value.
+function table(rows, headers, empty) {
+  if (rows.length === 0) return [empty];
+  const keys = Object.keys(headers);
+  const widths = keys.map((k) => Math.max(headers[k].length, ...rows.map((r) => r[k].length)));
+  const line = (r) => keys.map((k, i) => (i === keys.length - 1 ? r[k] : r[k].padEnd(widths[i]))).join("  ").trimEnd();
+  return [line(headers), ...rows.map(line)];
+}
+
+// "2026-11-03 14:02" in local time.
+function formatDate(iso) {
+  if (!iso) return "";
+  const d = new Date(iso);
+  const pad = (n) => String(n).padStart(2, "0");
+  return `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())} ${pad(d.getHours())}:${pad(d.getMinutes())}`;
+}
+
+const truncate = (s, n) => (s.length > n ? `${s.slice(0, n - 1)}…` : s);

package/src/lock.js

@@ -0,0 +1,34 @@
+import { createHash } from "node:crypto";
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+export const LOCK_FILE = "claude-lock.json";
+
+// Same layout as the lock file `ant apply` writes: one entry per file, keyed by "./<file>".
+export function readLock(dir) {
+  const path = join(dir, LOCK_FILE);
+  if (!existsSync(path)) return null;
+  try {
+    return JSON.parse(readFileSync(path, "utf8"));
+  } catch (err) {
+    throw new Error(`${LOCK_FILE}: not valid JSON (${err.message})`);
+  }
+}
+
+export function writeLock(dir, lock) {
+  writeFileSync(join(dir, LOCK_FILE), JSON.stringify(lock, null, 2) + "\n");
+}
+
+// Hash of a request body with keys sorted, so key order in the YAML doesn't count as a change.
+export function hashBody(body) {
+  return createHash("md5").update(canonicalJSON(body)).digest("hex");
+}
+
+function canonicalJSON(value) {
+  if (Array.isArray(value)) return `[${value.map(canonicalJSON).join(",")}]`;
+  if (value && typeof value === "object") {
+    const keys = Object.keys(value).sort();
+    return `{${keys.map((k) => `${JSON.stringify(k)}:${canonicalJSON(value[k])}`).join(",")}}`;
+  }
+  return JSON.stringify(value);
+}

package/src/session.js

@@ -0,0 +1,129 @@
+import { check } from "./check.js";
+import { AGENT_FILE, ENV_FILE, agentBody, envBody } from "./instance.js";
+import { LOCK_FILE, hashBody, readLock } from "./lock.js";
+
+export class SessionError extends Error {}
+
+// Starts a session on the agent and environment recorded in claude-lock.json, or resumes `sessionId`.
+// Returns { session, notes }: notes are warnings worth showing, such as files changed since the last deploy.
+export async function openSession(dir, { client, sessionId }) {
+  if (sessionId) {
+    const session = await client.beta.sessions.retrieve(sessionId);
+    if (session.status === "terminated") throw new SessionError(`session ${sessionId} has terminated`);
+    return { session, notes: [] };
+  }
+
+  const lock = readLock(dir);
+  const agent = lock?.resources?.[`./${AGENT_FILE}`];
+  const env = lock?.resources?.[`./${ENV_FILE}`];
+  if (!agent || !env) {
+    throw new SessionError(`${dir} hasn't been deployed (no agent or environment in ${LOCK_FILE}); run agentschema deploy first`);
+  }
+
+  const notes = [];
+  const { instance } = check(dir);
+  if (instance) {
+    if (hashBody(agentBody(instance.agent)) !== agent.hash) notes.push(`${AGENT_FILE} has changed since the last deploy`);
+    if (hashBody(envBody(instance.env)) !== env.hash) notes.push(`${ENV_FILE} has changed since the last deploy`);
+    if (notes.length > 0) notes.push(`this session uses the deployed version; run agentschema deploy to pick up the changes`);
+  }
+
+  // Pin the deployed version, so the session runs exactly what deploy last sent.
+  const params = {
+    agent: { type: "agent", id: agent.id, version: Number(agent.version) },
+    environment_id: env.id,
+  };
+  const name = instance?.agent.data.name;
+  params.title = name ? `${name} (agentschema run)` : "agentschema run";
+  return { session: await client.beta.sessions.create(params), notes };
+}
+
+// Drives a session one turn at a time. `ui` answers what only a person can:
+//   ui.event(event)          show an event
+//   ui.confirm(event)        -> { result: "allow" | "deny", deny_message? } for a paused tool call
+//   ui.customToolResult(event) -> string, the result of a custom tool call
+export class Conversation {
+  constructor(client, sessionId, ui) {
+    this.client = client;
+    this.sessionId = sessionId;
+    this.ui = ui;
+    this.seen = new Set();
+    this.stream = null;
+  }
+
+  // Sends a message and handles events until the agent finishes its turn.
+  // Returns the idle stop reason, or "terminated".
+  async send(text) {
+    return this.#turn([{ type: "user.message", content: [{ type: "text", text }] }]);
+  }
+
+  // Asks the agent to stop at the next safe point; the running turn then ends normally.
+  async interrupt() {
+    await this.client.beta.sessions.events.send(this.sessionId, { events: [{ type: "user.interrupt" }] });
+  }
+
+  async #turn(events) {
+    // Stream first: events emitted before the stream opens would never reach us.
+    this.stream = await this.client.beta.sessions.events.stream(this.sessionId);
+    await this.client.beta.sessions.events.send(this.sessionId, { events });
+
+    for (let attempt = 0; ; attempt++) {
+      try {
+        for await (const event of this.stream) {
+          const done = await this.#handle(event);
+          if (done) return done;
+        }
+        throw new Error("event stream closed");
+      } catch (err) {
+        if (this.closed || attempt >= 3) throw err;
+        // The stream has no replay: reopen it, then catch up from the event history.
+        this.stream = await this.client.beta.sessions.events.stream(this.sessionId);
+        for await (const event of this.client.beta.sessions.events.list(this.sessionId)) {
+          const done = await this.#handle(event);
+          if (done) return done;
+        }
+      }
+    }
+  }
+
+  // Returns a value when the turn is over.
+  async #handle(event) {
+    // Events are deduped by ID: the history and the live stream overlap after a reconnect,
+    // and a queued user event is echoed twice.
+    if (event.id) {
+      if (this.seen.has(event.id)) return null;
+      this.seen.add(event.id);
+    }
+    this.ui.event(event);
+
+    const send = (e) => this.client.beta.sessions.events.send(this.sessionId, { events: [e] });
+    switch (event.type) {
+      case "agent.tool_use":
+      case "agent.mcp_tool_use":
+        if (event.evaluated_permission === "ask") {
+          const { result, deny_message } = await this.ui.confirm(event);
+          const reply = { type: "user.tool_confirmation", tool_use_id: event.id, result };
+          if (result === "deny" && deny_message) reply.deny_message = deny_message;
+          await send(reply);
+        }
+        return null;
+      case "agent.custom_tool_use": {
+        const text = await this.ui.customToolResult(event);
+        await send({ type: "user.custom_tool_result", custom_tool_use_id: event.id, content: [{ type: "text", text }] });
+        return null;
+      }
+      case "session.status_idle":
+        // requires_action means the session is waiting on one of the replies above.
+        return event.stop_reason?.type === "requires_action" ? null : (event.stop_reason?.type ?? "end_turn");
+      case "session.status_terminated":
+        return "terminated";
+      default:
+        return null;
+    }
+  }
+
+  close() {
+    this.closed = true;
+    this.stream?.controller?.abort();
+  }
+}