@soft-boy/agentschema 0.1.1 → 0.1.2

package/README.md

@@ -1,6 +1,6 @@
 # agentschema
 
-Define a Claude Managed Agent as a folder of Markdown files.
+Define an AI-Agent as a folder of Markdown files.
 
 ```
 my-agent/
@@ -8,7 +8,7 @@ my-agent/
 └── env.md     # the environment it runs in
 ```
 
-**Status:** v0.1 draft. `check`, `deploy` and `run` work.
+**Status:** v0.1 draft.
 
 ## Philosophy
 
@@ -22,35 +22,6 @@ my-agent/
 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
@@ -79,13 +50,26 @@ Field reference: [Environments](https://platform.claude.com/docs/en/managed-agen
 ## Usage
 
 ```sh
+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
@@ -100,8 +84,6 @@ Unknown fields are only warnings, because they're sent to the API as written. `c
 - **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.
@@ -109,16 +91,39 @@ Unknown fields are only warnings, because they're sent to the API as written. `c
 - **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_…`.
+- **Resuming:** quitting leaves the session in place, and `run` prints a command to resume it: `agentschema run --resume 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
+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

package/bin/agentschema.js

@@ -1,44 +1,58 @@
 #!/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";
 
 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
+  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
-  --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
+  --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. deploy and run authenticate with
+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" },
-  vault: { type: "string", multiple: true },
-  title: { type: "string" },
-  session: { type: "string" },
+  resume: { type: "string" },
   help: { type: "boolean", short: "h" },
   version: { type: "boolean", short: "v" },
 };
-const COMMAND_OPTIONS = {
-  check: [],
-  deploy: ["dry-run", "force"],
-  run: ["vault", "title", "session"],
+// 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) {
@@ -50,7 +64,8 @@ async function main(argv) {
     return 1;
   }
   const { values, positionals } = parsed;
-  const [command, dir = ".", ...extra] = positionals;
+  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"));
@@ -61,16 +76,38 @@ async function main(argv) {
     console.log(USAGE);
     return command || values.help ? 0 : 1;
   }
-  if (!(command in COMMAND_OPTIONS)) {
+  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 misplaced = Object.keys(values).filter((k) => !COMMAND_OPTIONS[command].includes(k));
-  if (extra.length > 0 || misplaced.length > 0) {
-    const arg = extra[0] ?? `--${misplaced[0]}`;
+  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);
@@ -94,13 +131,26 @@ async function main(argv) {
       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.session,
-        vaultIds: values.vault ?? [],
-        title: values.title,
+        sessionId: values.resume,
       });
       for (const note of notes) console.warn(`warning: ${note}`);
       await chat(client, session, { agentName: session.agent?.name ?? "agent" });
@@ -111,7 +161,7 @@ async function main(argv) {
       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) {
+    if (err instanceof DeployError || err instanceof DeleteError || err instanceof SessionError || err instanceof Anthropic.AnthropicError) {
       console.error(`error: ${err.message}`);
       return 1;
     }
@@ -119,6 +169,17 @@ async function main(argv) {
   }
 }
 
+// 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 {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@soft-boy/agentschema",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "Markdown based AI agent schema",
   "type": "module",
   "bin": {

package/src/chat.js

@@ -131,5 +131,5 @@ export async function chat(client, session, { agentName, input = process.stdin,
     conversation.close();
     rl.close();
   }
-  if (!ended) output.write(dim(`Resume this conversation with: agentschema run --session ${session.id}\n`));
+  if (!ended) output.write(dim(`Resume this conversation with: agentschema run --resume ${session.id}\n`));
 }

package/src/check.js

@@ -27,7 +27,7 @@ export function check(dir) {
   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`);
+      if (pattern.test(parsed.raw)) errors.push(`${file}: looks like it contains ${what}; keep secrets out of these files`);
     }
   }
 

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/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/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/session.js

@@ -6,7 +6,7 @@ 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 }) {
+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`);
@@ -33,9 +33,8 @@ export async function openSession(dir, { client, sessionId, vaultIds = [], title
     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");
+  params.title = name ? `${name} (agentschema run)` : "agentschema run";
   return { session: await client.beta.sessions.create(params), notes };
 }