@canonmsg/agent-sdk 11.2.1 → 12.1.0

package/dist/chunks/mls-crypto-LMNQZOS6.js

@@ -0,0 +1,10 @@
+import {
+  createMlsDevCredentialVerifier,
+  mlsDevDeviceHttpConfiguration,
+  parseMlsDevClientConfiguration
+} from "./chunk-7N6OPPW4.js";
+export {
+  createMlsDevCredentialVerifier,
+  mlsDevDeviceHttpConfiguration,
+  parseMlsDevClientConfiguration
+};

package/dist/cli.js

@@ -0,0 +1,572 @@
+#!/usr/bin/env node
+import {
+  MLS_SETUP_ACTIONS,
+  assertPrivateHome,
+  awaitErrand,
+  checkCodex,
+  claudeDriver,
+  codeDriver,
+  codexDriver,
+  connectorDriver,
+  createRunner,
+  errandJournal,
+  errandsDirectory,
+  loadClaudeQuery,
+  loadInstructions,
+  loadMlsDevConfiguration,
+  loadRelayConfiguration,
+  queueErrand,
+  readRelayCredential,
+  relayRunnerHome,
+  runMlsDevSetup,
+  runnerLockName,
+  startRelayChannel,
+  writeRelayCredential
+} from "./chunks/chunk-N722GWCP.js";
+import {
+  CanonApiError,
+  CanonClient,
+  acquireLock,
+  isProfileLocked,
+  loadProfiles,
+  readCliPackageVersion,
+  resolveCanonRuntimeConnection,
+  runCli,
+  verifyCanonRuntimeConnection
+} from "./chunks/chunk-QZ4PPRQW.js";
+import {
+  __name,
+  isCanonClientVersion
+} from "./chunks/chunk-7N6OPPW4.js";
+
+// src/cli.ts
+import { realpathSync } from "node:fs";
+import { homedir, tmpdir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+import { parseArgs } from "node:util";
+var RUNNER_VERSION = readCliPackageVersion(import.meta.url);
+var RUNNER_CLIENT = isCanonClientVersion(RUNNER_VERSION) ? { kind: "runner", version: RUNNER_VERSION } : void 0;
+function once(handler) {
+  let called = false;
+  return (error) => {
+    if (!called) {
+      called = true;
+      handler(error);
+    }
+  };
+}
+__name(once, "once");
+var HELP = `canon-agent: run a Canon agent on the unified runner
+
+Usage:
+  canon-agent run --driver code --module <path> [--profile <name>] [--environment <id>]
+  canon-agent run --driver claude [--cwd <dir>] [--model <id>] [--permission-mode <mode>]
+                  [--claude-path <path>] [--profile <name>] [--environment <id>]
+  canon-agent run --driver codex [--cwd <dir>] [--model <id>] [--sandbox <mode>]
+                  [--approval-policy <policy>] [--codex-path <path>] [--profile <name>]
+                  [--environment <id>]
+  canon-agent run --driver connector --relay-config <path> --mls-dev-config <path>
+                  [--profile <name>] [--environment <id>]
+  canon-agent mls --action <action> --mls-dev-config <path> [--room <id>]
+                  [--relay-config <path>] [--profile <name>] [--environment <id>]
+  canon-agent tell --room <id> --text <text> (--agent <id> | --profile <name>)
+                  [--environment <id>] [--wait]
+  canon-agent post --room <id> --text <text> (--agent <id> | --profile <name>)
+                  [--environment <id>] [--wait]
+  canon-agent errand --to <room or contact id> --why <why> --text <instruction>
+                  [--origin <room id>] (--agent <id> | --profile <name>)
+                  [--environment <id>] [--wait]
+  canon-agent errands [--follow] [--cancel <errand id>] (--agent <id> | --profile <name>)
+                  [--environment <id>]
+
+Every run command also takes --mls-dev-config <path> (Dev only), which gives the agent
+its MLS device so it can take part in encrypted rooms. Without it, the agent refuses
+encrypted rooms and logs each one once.
+
+Team rooms (an owner's agents working together): claude and codex also take
+[--instructions <file>] [--trust-agent <agentId>]...; every run command takes
+[--agent-turn-cap <n>] [--mention-alias <name>]..., which apply in encrypted rooms.
+code, claude and codex take [--allow-session-for-destructive] for encrypted cards.
+
+Errands: tell, post and errand direct a running agent from the machine it runs on:
+whoever can write $CANON_HOME commands it, and the CLI itself uses no network. tell
+leaves a private note for the agent's next turn in a room: never posted, it starts no
+turn. post sends the text as the agent's own message, with no turn (encrypted in an
+encrypted room). errand runs one owner-authorised turn that carries the instruction to
+the recipient (a room the agent is in, or a new conversation with a person or agent),
+reports to --origin, and tells later turns there why the agent came. What concerns an
+encrypted room is reported only to an encrypted origin; otherwise the report stays
+local (canon-agent errands). Canon's policies, blocks and rate limits apply as to any
+message from the agent.
+
+Flags:
+  --driver <name>        The runtime driver: "code", "claude", "codex" or "connector".
+  --module <path>        code: an ES module whose default export answers a turn.
+                         Its directory is one the agent may send files from.
+  --cwd <dir>            claude, codex: the directory the runtime works in (default:
+                         the current one). The agent may send files from it.
+  --model <id>           claude, codex: the model (default: the runtime's).
+  --permission-mode <m>  claude: "default" puts each tool call Claude Code would ask
+                         about to Canon as an approval; "acceptEdits" and
+                         "bypassPermissions" allow more without asking, and then
+                         only the owner's messages may lead to tool use.
+  --claude-path <path>   claude: a Claude Code executable to use instead of the
+                         SDK's bundled one.
+  --sandbox <mode>       codex: "workspace-write" (default), "read-only" or
+                         "danger-full-access", for the owner's turns.
+  --approval-policy <p>  codex: "on-request" (default), "untrusted" or "never": when
+                         Codex asks the owner (as a Canon approval) before acting.
+                         Turns holding anyone else's message are always read-only,
+                         approve nothing and get only Canon's tools.
+  --codex-path <path>    codex: the Codex CLI (default: codex on the PATH).
+  --instructions <file>  claude, codex: standing instructions from the owner (a role,
+                         say), appended to the runtime's system or developer
+                         instructions. A UTF-8 file of at most 32 KiB, owned by you
+                         and not writable by others, read once at start; never sent
+                         to Canon.
+  --trust-agent <id>     claude, codex: an agent of the same owner whose messages count
+                         as the owner's for tool use (repeat for several), only in a
+                         room whose other members are all listed agents that Canon
+                         confirms at each turn as active agents of this agent's
+                         owner (and, in plaintext, only for a final that agent's own
+                         runner marked as answering its owner). Otherwise they are
+                         guarded like any other agent's. Approvals still go to the
+                         owner.
+  --agent-turn-cap <n>   Encrypted rooms: another agent's message wakes this agent only
+                         when it @mentions it (by display name, id or an alias), at
+                         most n times in a row per room until a person writes there
+                         (default 6; 0: agents never wake it). Plaintext rooms
+                         follow Canon's group rules.
+  --mention-alias <name> Encrypted rooms: another name that @mentions this agent, such
+                         as its role (repeat for several).
+  --allow-session-for-destructive
+                         Encrypted rooms: let the owner allow an action the runtime
+                         marks destructive (Claude Code's default-to-no prompts,
+                         Codex's risky commands and deletions) for the rest of the
+                         session. Off by default: each such action asks.
+  --relay-config <path>  connector (Dev only): run as Canon's class-C relay for one agent
+                         connected through Canon's MCP connector. A private JSON file
+                         naming the agent, where the channel to Canon's Functions
+                         listens, and the path of the channel secret. Canon delivers
+                         the relay's own credential over that channel when the owner
+                         enables the relay (no API key is used); it is kept in
+                         $CANON_HOME/relay. The relay serves only encrypted rooms,
+                         which are then not end-to-end encrypted to that agent. With
+                         "mls", it sets up the relay's device with that credential.
+  --mls-dev-config <p>   The operator's MLS configuration: an absolute path to a private
+                         JSON file with the Dev issuer pins and the custody helper (no
+                         keys or credentials). Dev only.
+  --action <action>      mls: status (public device state), provision (create the
+                         portable vault, once), enroll, renew, publish (this device's
+                         KeyPackage for --room) or refresh (catch up --room). It never
+                         starts a model, and uses the same home as "run": stop the
+                         agent first.
+  --room <id>            mls: the encrypted room, for publish and refresh. tell, post:
+                         the conversation.
+  --text <text>          tell: the note. post: the message. errand: the instruction.
+                         At most 32 KiB.
+  --to <id>              errand: a conversation the agent is in, or else a person or
+                         agent to start a new (plaintext) conversation with.
+  --why <why>            errand: why the owner sends the agent (at most 4 KiB).
+  --origin <id>          errand: the conversation the report goes to. A report about an
+                         encrypted recipient goes only to an encrypted origin.
+  --follow               errands: go on printing each change.
+  --cancel <id>          errands: cancel that errand (Stop in its origin also stops it).
+  --agent <id>           tell, post, errand, errands: the agent (or --profile).
+  --wait                 tell, post, errand: wait up to 30 s for the running agent to take
+                         it (an errand: to finish its turn), print the outcome, and exit
+                         1 unless it was accepted (a note kept, a post sent, an errand's
+                         turn ended and any report it sent to --origin accepted).
+  --profile <name>       A profile in $CANON_HOME/agents.json (key and endpoints).
+  --environment <id>     canon-prod-v1 or canon-dev-v1 (default: CANON_ENVIRONMENT_ID).
+  --help, -h             Show this help.
+  --version, -V          Show the package version.
+
+Environment:
+  CANON_API_KEY          The agent's key (or use --profile).
+  CANON_ENVIRONMENT_ID   Required; a profile from another environment is refused.
+  CANON_HOME             Agent state, default ~/.canon. It must be private (0700).
+  ANTHROPIC_API_KEY      claude: use this API key instead of a Claude subscription
+                         login. The claude driver needs @anthropic-ai/claude-agent-sdk.
+  OPENAI_API_KEY         codex: use this API key instead of Codex's own login, unless
+                         Codex is configured for another model provider.
+
+SIGTERM or Ctrl-C stops taking messages, lets running turns finish for 10 seconds,
+then stops them.`;
+var DRIVERS = ["code", "claude", "codex", "hermes", "connector"];
+var AVAILABLE = ["code", "claude", "codex", "connector"];
+var PERMISSION_MODES = ["default", "acceptEdits", "bypassPermissions"];
+var SANDBOXES = ["workspace-write", "read-only", "danger-full-access"];
+var APPROVAL_POLICIES = ["on-request", "untrusted", "never"];
+function teamOptions(values) {
+  const cap = values["agent-turn-cap"];
+  if (cap !== void 0 && (!/^\d{1,4}$/.test(cap) || Number(cap) > 1e3)) throw new UsageError("--agent-turn-cap must be a whole number from 0 to 1000.");
+  const aliases = values["mention-alias"] ?? [];
+  if (aliases.some((alias) => !alias.replace(/^@+/, "").trim())) throw new UsageError("--mention-alias needs a name.");
+  return { ...cap !== void 0 ? { agentTurnCap: Number(cap) } : {}, ...aliases.length ? { mentionAliases: aliases } : {} };
+}
+__name(teamOptions, "teamOptions");
+var UsageError = class extends Error {
+  static {
+    __name(this, "UsageError");
+  }
+};
+async function main() {
+  let parsed;
+  try {
+    parsed = parse();
+  } catch (error) {
+    throw new UsageError(error instanceof Error ? error.message : String(error));
+  }
+  const { values, positionals } = parsed;
+  if (!["run", "mls", "tell", "post", "errand", "errands"].includes(positionals[0] ?? "") || positionals.length > 1) {
+    throw new UsageError('Expected the "run", "mls", "tell", "post", "errand" or "errands" command.');
+  }
+  if (positionals[0] === "mls") return mlsSetup(values);
+  if (positionals[0] === "errands") return errands(values);
+  if (positionals[0] === "tell" || positionals[0] === "post" || positionals[0] === "errand") return errand(positionals[0], values);
+  if (!values.driver) throw new UsageError("--driver is required.");
+  if (!AVAILABLE.includes(values.driver)) {
+    throw new Error(DRIVERS.includes(values.driver) ? `The "${values.driver}" driver is not yet available; ${AVAILABLE.join(", ")} run today.` : `Unknown driver "${values.driver}". Available: ${AVAILABLE.join(", ")}.`);
+  }
+  if (values.driver === "code" && !values.module) throw new UsageError("--driver code needs --module <path>.");
+  if (values.driver === "connector" !== !!values["relay-config"]) throw new UsageError("--relay-config goes with --driver connector, which needs it.");
+  if (values.driver === "connector" && !values["mls-dev-config"]) throw new UsageError("--driver connector needs --mls-dev-config <path>: the relay holds the agent's MLS device.");
+  if (!["claude", "codex"].includes(values.driver) && (values.instructions !== void 0 || values["trust-agent"]?.length)) {
+    throw new UsageError("--instructions and --trust-agent go with --driver claude or codex.");
+  }
+  const team = teamOptions(values);
+  if (values.driver === "connector" && values["allow-session-for-destructive"]) throw new UsageError("--allow-session-for-destructive goes with a driver that asks.");
+  if (values.driver === "connector") return runRelay(values, team);
+  const permissionMode = values["permission-mode"];
+  if (permissionMode !== void 0 && !PERMISSION_MODES.includes(permissionMode)) {
+    throw new UsageError(`--permission-mode must be one of ${PERMISSION_MODES.join(", ")}.`);
+  }
+  const { sandbox, "approval-policy": approvalPolicy } = values;
+  if (sandbox !== void 0 && !SANDBOXES.includes(sandbox)) {
+    throw new UsageError(`--sandbox must be one of ${SANDBOXES.join(", ")}.`);
+  }
+  if (approvalPolicy !== void 0 && !APPROVAL_POLICIES.includes(approvalPolicy)) {
+    throw new UsageError(`--approval-policy must be one of ${APPROVAL_POLICIES.join(", ")}.`);
+  }
+  const trustedAgents = values["trust-agent"] ?? [];
+  if (trustedAgents.some((id) => !/^[\w.:-]{1,200}$/.test(id))) throw new UsageError("--trust-agent takes an agent id.");
+  const instructions = values.instructions !== void 0 ? await loadInstructions(resolve(values.instructions)) : void 0;
+  const { environmentId, home, profile, apiKey } = await settings(values);
+  const mls = values["mls-dev-config"] ? await loadMlsDevConfiguration(values["mls-dev-config"], { environmentId }) : void 0;
+  const baseUrl = process.env.CANON_BASE_URL || profile?.baseUrl;
+  const streamUrl = process.env.CANON_STREAM_URL || profile?.streamUrl;
+  let driver;
+  if (values.driver === "claude") {
+    driver = claudeDriver({
+      cwd: resolve(values.cwd ?? "."),
+      query: await loadClaudeQuery(),
+      ...values.model ? { model: values.model } : {},
+      ...permissionMode ? { permissionMode } : {},
+      ...values["claude-path"] ? { claudePath: resolve(values["claude-path"]) } : {},
+      ...instructions ? { instructions } : {}
+    });
+  } else if (values.driver === "codex") {
+    const codexPath = values["codex-path"] ? resolve(values["codex-path"]) : "codex";
+    checkCodex(codexPath);
+    driver = codexDriver({
+      cwd: resolve(values.cwd ?? "."),
+      codexPath,
+      ...values.model ? { model: values.model } : {},
+      ...sandbox ? { sandbox } : {},
+      ...approvalPolicy ? { approvalPolicy } : {},
+      ...instructions ? { instructions } : {}
+    });
+  } else {
+    const modulePath = realpathSync(resolve(values.module));
+    const handler = (await import(pathToFileURL(modulePath).href)).default;
+    if (typeof handler !== "function") throw new Error(`${values.module} must export a turn handler as its default export.`);
+    driver = codeDriver(handler, { outboundFiles: { roots: [dirname(modulePath), realpathSync(tmpdir())] } });
+  }
+  const runner = await createRunner({
+    apiKey,
+    environmentId,
+    home,
+    driver,
+    ...mls ? { mls } : {},
+    baseUrl,
+    streamUrl,
+    ...team,
+    ...trustedAgents.length ? { trustedAgents } : {},
+    ...values["allow-session-for-destructive"] ? { sessionApprovalForDestructive: true } : {},
+    ...RUNNER_CLIENT ? { client: RUNNER_CLIENT } : {},
+    onFatal: once((error) => {
+      console.error(`canon-agent: ${error.message}`);
+      void runner.stop().catch(() => void 0).finally(() => process.exit(1));
+    })
+  });
+  stopOnSignals(() => runner.stop());
+  try {
+    await runner.start();
+  } catch (error) {
+    await runner.stop().catch(() => void 0);
+    throw error;
+  }
+  console.error(`canon-agent: running the ${values.driver} driver in ${environmentId}. Ctrl-C stops it.`);
+}
+__name(main, "main");
+async function runRelay(values, team) {
+  const { environmentId, home, profile } = await settings(values, { key: false });
+  const relay = await loadRelayConfiguration(values["relay-config"], { environmentId });
+  const baseUrl = process.env.CANON_BASE_URL || profile?.baseUrl;
+  const streamUrl = process.env.CANON_STREAM_URL || profile?.streamUrl;
+  let current;
+  let latest;
+  let switching = Promise.resolve();
+  const switchTo = /* @__PURE__ */ __name((stored2, what) => {
+    latest = stored2;
+    switching = switching.then(() => runUnder(stored2)).catch((error) => {
+      console.error(`canon-agent: the relay could not start under ${what} (${error instanceof Error ? error.message : String(error)}); waiting for the owner to enable the relay again.`);
+    });
+  }, "switchTo");
+  const channel = await startRelayChannel({
+    agentId: relay.agentId,
+    secret: relay.secret,
+    host: relay.listen.host,
+    port: relay.listen.port,
+    // Durable before the channel confirms the delivery; the runner switches over once Canon has committed it.
+    onCredential: /* @__PURE__ */ __name((delivery) => switchTo(writeRelayCredential(home, relay, delivery), "its new credential"), "onCredential")
+  });
+  async function accepted(stored2) {
+    for (let attempt = 0; attempt < 60; attempt += 1) {
+      if (latest !== stored2) return false;
+      try {
+        await assertRelayAgent(relay, stored2, baseUrl, streamUrl);
+        return true;
+      } catch (error) {
+        if (!(error instanceof CanonApiError) || error.status !== 401) throw error;
+      }
+      await new Promise((resolve2) => setTimeout(resolve2, 1e3));
+    }
+    throw new Error("Canon did not accept the relay's credential");
+  }
+  __name(accepted, "accepted");
+  async function runUnder(stored2) {
+    if (!await accepted(stored2)) return;
+    channel.serve(void 0);
+    await current?.stop();
+    current = void 0;
+    const mls = await loadMlsDevConfiguration(values["mls-dev-config"], { environmentId });
+    const driver = connectorDriver();
+    const runner = await createRunner({
+      apiKey: stored2.credential,
+      environmentId,
+      home: relayRunnerHome(home, stored2.installationId),
+      driver,
+      mls,
+      baseUrl,
+      streamUrl,
+      relay: true,
+      installationId: stored2.installationId,
+      ...team,
+      ...RUNNER_CLIENT ? { client: RUNNER_CLIENT } : {},
+      onFatal: once((error) => {
+        console.error(`canon-agent: ${error.message}`);
+        void Promise.resolve().then(() => channel.close()).then(() => runner.stop()).catch(() => void 0).finally(() => process.exit(1));
+      })
+    });
+    try {
+      await runner.start();
+    } catch (error) {
+      await runner.stop().catch(() => void 0);
+      throw error;
+    }
+    current = runner;
+    channel.serve({ runner, inbox: driver.inbox }, stored2.grantId);
+    console.error(`canon-agent: relaying ${relay.agentId} under ${stored2.installationId} in ${environmentId}.`);
+  }
+  __name(runUnder, "runUnder");
+  stopOnSignals(async () => {
+    await channel.close();
+    latest = void 0;
+    await switching;
+    await current?.stop();
+  });
+  console.error(`canon-agent: relay channel for ${relay.agentId} listening on ${channel.url}. Ctrl-C stops it.`);
+  const stored = await readRelayCredential(home, relay);
+  if (stored) switchTo(stored, "its stored credential");
+  else console.error("canon-agent: waiting for Canon to deliver this relay's credential (the owner enables the relay for the connection).");
+}
+__name(runRelay, "runRelay");
+async function assertRelayAgent(relay, stored, baseUrl, streamUrl) {
+  const connection = resolveCanonRuntimeConnection({ environmentId: relay.environmentId, apiBaseUrl: baseUrl, streamUrl });
+  const client = new CanonClient(stored.credential, connection.apiBaseUrl, { environmentId: relay.environmentId });
+  try {
+    const me = await client.getAgentMe();
+    if (me.agentId !== relay.agentId) throw new Error(`The relay credential names agent ${me.agentId}, but the relay configuration names ${relay.agentId}.`);
+  } finally {
+    await client.close();
+  }
+}
+__name(assertRelayAgent, "assertRelayAgent");
+function parse() {
+  return parseArgs({
+    allowPositionals: true,
+    options: {
+      driver: { type: "string" },
+      module: { type: "string" },
+      profile: { type: "string" },
+      environment: { type: "string" },
+      cwd: { type: "string" },
+      model: { type: "string" },
+      "permission-mode": { type: "string" },
+      "claude-path": { type: "string" },
+      sandbox: { type: "string" },
+      "approval-policy": { type: "string" },
+      "codex-path": { type: "string" },
+      "mls-dev-config": { type: "string" },
+      action: { type: "string" },
+      room: { type: "string" },
+      "relay-config": { type: "string" },
+      instructions: { type: "string" },
+      "trust-agent": { type: "string", multiple: true },
+      "agent-turn-cap": { type: "string" },
+      "mention-alias": { type: "string", multiple: true },
+      "allow-session-for-destructive": { type: "boolean" },
+      text: { type: "string" },
+      agent: { type: "string" },
+      wait: { type: "boolean" },
+      to: { type: "string" },
+      why: { type: "string" },
+      origin: { type: "string" },
+      follow: { type: "boolean" },
+      cancel: { type: "string" }
+    }
+  });
+}
+__name(parse, "parse");
+async function settings(values, { key = true } = {}) {
+  const environmentId = values.environment || process.env.CANON_ENVIRONMENT_ID;
+  if (!environmentId) throw new Error("CANON_ENVIRONMENT_ID (or --environment) is required.");
+  if (key && !values.profile && !process.env.CANON_API_KEY) throw new Error("CANON_API_KEY (or --profile <name>) is required.");
+  const home = resolve(process.env.CANON_HOME || join(homedir(), ".canon"));
+  await assertPrivateHome(home);
+  const profile = values.profile ? loadProfiles(home)[values.profile] : void 0;
+  if (values.profile && !profile) throw new Error(`No profile "${values.profile}" in ${join(home, "agents.json")}.`);
+  if (profile && profile.environmentId !== environmentId) {
+    throw new Error(`Profile "${values.profile}" belongs to ${profile.environmentId}, not ${environmentId}.`);
+  }
+  return { environmentId, home, profile, apiKey: process.env.CANON_API_KEY || profile?.apiKey || "" };
+}
+__name(settings, "settings");
+async function mlsSetup(values) {
+  const action = values.action;
+  if (!action || !MLS_SETUP_ACTIONS.includes(action)) throw new UsageError(`--action must be one of ${MLS_SETUP_ACTIONS.join(", ")}.`);
+  if ((action === "publish" || action === "refresh") !== !!values.room) throw new UsageError("--room is needed for publish and refresh, and only for them.");
+  if (!values["mls-dev-config"]) throw new UsageError("--mls-dev-config <path> is required.");
+  const settled = await settings(values, { key: !values["relay-config"] });
+  const { environmentId, profile } = settled;
+  const relay = values["relay-config"] ? await loadRelayConfiguration(values["relay-config"], { environmentId }) : void 0;
+  const stored = relay ? await readRelayCredential(settled.home, relay) : void 0;
+  if (relay && !stored) {
+    throw new Error("This relay has no credential yet: start it (canon-agent run --driver connector) and have the owner enable the relay.");
+  }
+  const apiKey = stored ? stored.credential : settled.apiKey;
+  const home = stored ? relayRunnerHome(settled.home, stored.installationId) : settled.home;
+  const config = await loadMlsDevConfiguration(values["mls-dev-config"], { environmentId });
+  let client;
+  let lock;
+  try {
+    const connection = resolveCanonRuntimeConnection({
+      environmentId,
+      apiBaseUrl: process.env.CANON_BASE_URL || profile?.baseUrl,
+      streamUrl: process.env.CANON_STREAM_URL || profile?.streamUrl
+    });
+    await verifyCanonRuntimeConnection(connection);
+    client = new CanonClient(apiKey, connection.apiBaseUrl, {
+      environmentId,
+      streamUrl: connection.streamUrl,
+      stateDirectory: join(home, "endpoint"),
+      mlsDev: { configuration: config.configuration, custody: config.custody },
+      ...stored ? { installationId: stored.installationId } : {},
+      ...RUNNER_CLIENT ? { client: RUNNER_CLIENT } : {}
+    });
+    const me = await client.getAgentMe();
+    lock = acquireLock(runnerLockName(environmentId, me.agentId), home);
+    console.log(JSON.stringify(await runMlsDevSetup(await client.getEndpoint(), action, values.room, config.provision)));
+  } finally {
+    try {
+      await client?.close();
+    } finally {
+      try {
+        await config.close();
+      } finally {
+        lock?.release();
+      }
+    }
+  }
+}
+__name(mlsSetup, "mlsSetup");
+async function errandHome(values) {
+  if (!values.agent && !values.profile) throw new UsageError("--agent <id> or --profile <name> names the agent.");
+  if (values.agent !== void 0 && (!/^[\w.:-]{1,200}$/.test(values.agent) || /^\.+$/.test(values.agent))) throw new UsageError("--agent takes an agent id.");
+  const { environmentId, home, profile } = await settings(values, { key: false });
+  if (values.agent && profile && profile.agentId !== values.agent) throw new UsageError("--agent and --profile name different agents.");
+  const agentId = values.agent ?? profile.agentId;
+  return { agentId, directory: errandsDirectory(home, environmentId, agentId), running: isProfileLocked(runnerLockName(environmentId, agentId), home).locked };
+}
+__name(errandHome, "errandHome");
+async function errand(kind, values) {
+  const input = kind === "errand" ? { kind, to: values.to ?? "", why: values.why ?? "", text: values.text ?? "", ...values.origin ? { origin: values.origin } : {} } : { kind, conversationId: values.room ?? "", text: values.text ?? "" };
+  if (kind === "errand" && (!values.to || values.why === void 0)) throw new UsageError("errand needs --to <room or contact id> and --why <why>.");
+  if (kind !== "errand" && !values.room) throw new UsageError("--room <conversation id> is required.");
+  if (values.text === void 0) throw new UsageError("--text <text> is required.");
+  const { agentId, directory, running } = await errandHome(values);
+  const command = queueErrand(directory, input);
+  if (!running) console.error(`canon-agent: no runner of ${agentId} is running in this home; it takes the ${kind} when it starts.`);
+  await report(directory, command, !!values.wait, running);
+}
+__name(errand, "errand");
+async function report(directory, command, wait, running) {
+  if (!wait) return console.log(JSON.stringify({ id: command.id, kind: command.kind, record: join(directory, "journal", `${command.id}.json`) }));
+  const { record: found, accepted } = await awaitErrand(directory, command, running ? 3e4 : 0);
+  const { text: _text, ...outcome } = found ?? { version: 1, id: command.id, status: "queued", updatedAt: command.createdAt };
+  console.log(JSON.stringify({ ...outcome, kind: command.kind }));
+  if (!accepted) process.exitCode = 1;
+}
+__name(report, "report");
+async function errands(values) {
+  const { directory, running } = await errandHome(values);
+  if (values.cancel !== void 0) {
+    if (!/^[0-9a-f]{32}$/.test(values.cancel)) throw new UsageError("--cancel takes an errand id.");
+    return report(directory, queueErrand(directory, { kind: "cancel", errand: values.cancel }), running, running);
+  }
+  const journal = errandJournal(directory);
+  const shown = /* @__PURE__ */ new Map();
+  const show = /* @__PURE__ */ __name(() => {
+    for (const record of journal.list().filter((candidate) => candidate.kind === "errand").sort((a, b) => (a.createdAt ?? "").localeCompare(b.createdAt ?? "") || a.id.localeCompare(b.id))) {
+      if (shown.get(record.id) === record.updatedAt) continue;
+      shown.set(record.id, record.updatedAt);
+      console.log(JSON.stringify(record));
+    }
+  }, "show");
+  show();
+  if (values.follow) setInterval(show, 500);
+}
+__name(errands, "errands");
+function stopOnSignals(stop) {
+  let stopping = false;
+  const onSignal = /* @__PURE__ */ __name((signal) => {
+    if (stopping) process.exit(1);
+    stopping = true;
+    console.error(`canon-agent: ${signal}, stopping.`);
+    stop().then(() => process.exit(0), (error) => {
+      console.error(`canon-agent: ${error instanceof Error ? error.message : String(error)}`);
+      process.exit(1);
+    });
+  }, "onSignal");
+  process.on("SIGTERM", onSignal);
+  process.on("SIGINT", onSignal);
+}
+__name(stopOnSignals, "stopOnSignals");
+runCli(import.meta.url, main, (error) => {
+  console.error(`canon-agent: ${error instanceof Error ? error.message : String(error)}`);
+  if (error instanceof UsageError) console.error(HELP.split("\n\nFlags:")[0]);
+  process.exit(1);
+}, { name: "canon-agent", help: HELP });

package/dist/drivers/claude.d.ts

@@ -0,0 +1,42 @@
+import { type RuntimeDriver } from '../runner/types.js';
+/** The Claude Agent SDK's `query()` as the driver uses it: one prompt, one native turn. */
+export type ClaudeQuery = (params: {
+    prompt: string;
+    options: Record<string, unknown>;
+}) => AsyncIterable<unknown> & {
+    interrupt(): Promise<void>;
+    close(): void;
+};
+export interface ClaudeDriverOptions {
+    /** The directory Claude Code works in. The agent may also send files from it. */
+    cwd: string;
+    /** A model id; Claude Code's default otherwise. */
+    model?: string;
+    /**
+     * `default` (the default) puts every tool call Claude Code would ask about to the owner as a Canon approval.
+     * `acceptEdits` and `bypassPermissions` approve more on their own. In every mode, a turn holding a message from anyone
+     * but the owner or a confirmed trusted agent of the owner (`TurnInputMessage.trustedAgent`) may use only Canon's
+     * tools, AskUserQuestion and ToolSearch.
+     */
+    permissionMode?: 'default' | 'acceptEdits' | 'bypassPermissions';
+    /**
+     * The owner's standing instructions for this agent (its role, say), appended to Claude Code's system prompt after
+     * Canon's own framing. At most 32 KiB; the CLI reads them from `--instructions <file>`. Never sent to Canon.
+     */
+    instructions?: string;
+    /** A Claude Code executable to run instead of the one bundled with the SDK. */
+    claudePath?: string;
+    /** How long an interrupted Claude Code may take to stop before its process is closed (default 5 s). */
+    interruptGraceMs?: number;
+    /** The SDK's `query()` (see `loadClaudeQuery`), loaded on the first turn when unset; tests pass a stand-in. */
+    query?: ClaudeQuery;
+}
+/** Loads the SDK's `query()`; it is an optional peer dependency, installed by whoever runs the `claude` driver. */
+export declare function loadClaudeQuery(): Promise<ClaudeQuery>;
+/**
+ * Runs each turn as one Claude Agent SDK `query()` that resumes the room's native session, whose id the runner keeps in
+ * the driver state. Canon's tools reach Claude only through the runner's per-turn MCP server; Stop interrupts the native
+ * turn and closes its process if it does not stop. One process per session at a time: a room's next turn starts only
+ * after the previous one has exited.
+ */
+export declare function claudeDriver(options: ClaudeDriverOptions): RuntimeDriver;

package/dist/drivers/code.d.ts

@@ -0,0 +1,18 @@
+import type { ActivityEvent, AskAnswer, AskRequest, DriverCapabilities, DriverResult, DriverState, RuntimeDriver, TurnInput, TurnTools } from '../runner/types.js';
+/** The `DriverTurn` an in-process handler sees, with friendlier names. */
+export interface CodeTurn {
+    readonly input: TurnInput;
+    readonly prompt: string;
+    readonly files: readonly string[];
+    readonly signal: AbortSignal;
+    /** The full visible answer so far; a preview, never the final. */
+    stream(text: string): void;
+    activity(event: ActivityEvent): void;
+    ask(request: AskRequest): Promise<AskAnswer>;
+    readonly state: DriverState;
+    readonly tools: TurnTools;
+}
+/** Return the turn's one final: text, `null` for deliberate silence, or text with files. */
+export type CodeHandler = (turn: CodeTurn) => Promise<string | null | DriverResult> | string | null | DriverResult;
+/** Runs a turn as an in-process function. The runner owns every Canon behaviour around it. */
+export declare function codeDriver(handler: CodeHandler, capabilities?: Partial<DriverCapabilities>): RuntimeDriver;