@soft-boy/agentschema 0.1.0 → 0.1.1

package/README.md

@@ -1,20 +1,128 @@
 # agentschema
 
+Define a Claude Managed Agent as a folder of Markdown files.
+
+```
+my-agent/
+├── agent.md   # the agent
+└── env.md     # the environment it runs in
+```
+
+**Status:** v0.1 draft. `check`, `deploy` and `run` work.
+
+## 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
 ```
 
+## Example
+
+[`examples/coding-agent/agent.md`](examples/coding-agent/agent.md):
+
+```markdown
+---
+name: Coding Assistant
+model: claude-opus-5-5
+tools:
+  - type: agent_toolset_20260401
+---
+
+You are a helpful coding assistant. Write clean, well-documented code.
+```
+
+[`examples/coding-agent/env.md`](examples/coding-agent/env.md):
+
+```markdown
+---
+name: quickstart
+config:
+  type: cloud
+  networking:
+    type: limited
+    allow_package_managers: true
+---
+Cloud container with limited networking and package manager access.
+```
+
+## 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 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
+```
+
+`dir` defaults to the current directory.
+
+**`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.
+
+`deploy` authenticates with `ANTHROPIC_API_KEY`, or with a profile from `ant auth login`.
+
+`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 --session sesn_…`.
+
+```sh
+agentschema run [dir] --vault vlt_…        # attach a vault for MCP or other credentials (repeatable)
+agentschema run [dir] --title "Bug triage" # name the session
+agentschema run --session 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.
+
 ## 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,132 @@
 #!/usr/bin/env node
+import { readFileSync } from "node:fs";
+import { parseArgs } from "node:util";
+import Anthropic from "@anthropic-ai/sdk";
+import { chat } from "../src/chat.js";
+import { check } from "../src/check.js";
+import { DeployError, deploy } from "../src/deploy.js";
+import { SessionError, openSession } from "../src/session.js";
 
-console.log("hello world");
+const USAGE = `Usage: agentschema <command> [dir] [options]
+
+Commands:
+  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
+
+Options:
+  --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
+  --vault <id>      (run) Attach a vault (vlt_...) for MCP and other credentials; repeatable
+  --title <title>   (run) Title for the new session
+  --session <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. deploy and run authenticate with
+ANTHROPIC_API_KEY, or with a profile from \`ant auth login\`.`;
+
+const OPTIONS = {
+  "dry-run": { type: "boolean" },
+  force: { type: "boolean" },
+  vault: { type: "string", multiple: true },
+  title: { type: "string" },
+  session: { type: "string" },
+  help: { type: "boolean", short: "h" },
+  version: { type: "boolean", short: "v" },
+};
+const COMMAND_OPTIONS = {
+  check: [],
+  deploy: ["dry-run", "force"],
+  run: ["vault", "title", "session"],
+};
+
+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;
+  const [command, dir = ".", ...extra] = positionals;
+
+  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 in COMMAND_OPTIONS)) {
+    console.error(`agentschema: unknown command "${command}"\n\n${USAGE}`);
+    return 1;
+  }
+  const misplaced = Object.keys(values).filter((k) => !COMMAND_OPTIONS[command].includes(k));
+  if (extra.length > 0 || misplaced.length > 0) {
+    const arg = extra[0] ?? `--${misplaced[0]}`;
+    console.error(`agentschema: unexpected argument ${arg} for ${command}\n\n${USAGE}`);
+    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 === "run") {
+      const client = makeClient(false);
+      const { session, notes } = await openSession(dir, {
+        client,
+        sessionId: values.session,
+        vaultIds: values.vault ?? [],
+        title: values.title,
+      });
+      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 SessionError || err instanceof Anthropic.AnthropicError) {
+      console.error(`error: ${err.message}`);
+      return 1;
+    }
+    throw err;
+  }
+}
+
+// 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.1",
   "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 --session ${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 in a vault`);
+    }
+  }
+
+  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/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/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/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,130 @@
+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, vaultIds = [], title }) {
+  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,
+  };
+  if (vaultIds.length > 0) params.vault_ids = vaultIds;
+  const name = instance?.agent.data.name;
+  params.title = 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();
+  }
+}