@canonmsg/agent-sdk 12.0.0 → 12.1.0

package/dist/chunks/{mls-crypto-NZDNSPAO.js → mls-crypto-LMNQZOS6.js}

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

package/dist/cli.js

@@ -1,20 +1,43 @@
 #!/usr/bin/env node
 import {
+  MLS_SETUP_ACTIONS,
   assertPrivateHome,
+  awaitErrand,
   checkCodex,
   claudeDriver,
   codeDriver,
   codexDriver,
+  connectorDriver,
   createRunner,
-  loadClaudeQuery
-} from "./chunks/chunk-6VK4UZHJ.js";
+  errandJournal,
+  errandsDirectory,
+  loadClaudeQuery,
+  loadInstructions,
+  loadMlsDevConfiguration,
+  loadRelayConfiguration,
+  queueErrand,
+  readRelayCredential,
+  relayRunnerHome,
+  runMlsDevSetup,
+  runnerLockName,
+  startRelayChannel,
+  writeRelayCredential
+} from "./chunks/chunk-N722GWCP.js";
 import {
+  CanonApiError,
+  CanonClient,
+  acquireLock,
+  isProfileLocked,
   loadProfiles,
-  runCli
-} from "./chunks/chunk-OLJ7H4E2.js";
+  readCliPackageVersion,
+  resolveCanonRuntimeConnection,
+  runCli,
+  verifyCanonRuntimeConnection
+} from "./chunks/chunk-QZ4PPRQW.js";
 import {
-  __name
-} from "./chunks/chunk-FPQFTTND.js";
+  __name,
+  isCanonClientVersion
+} from "./chunks/chunk-7N6OPPW4.js";
 
 // src/cli.ts
 import { realpathSync } from "node:fs";
@@ -22,6 +45,18 @@ 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:
@@ -31,9 +66,42 @@ Usage:
   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" or "codex".
+  --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:
@@ -52,6 +120,64 @@ Flags:
                          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.
@@ -68,11 +194,19 @@ Environment:
 
 SIGTERM or Ctrl-C stops taking messages, lets running turns finish for 10 seconds,
 then stops them.`;
-var DRIVERS = ["code", "claude", "codex", "hermes"];
-var AVAILABLE = ["code", "claude", "codex"];
+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");
@@ -86,12 +220,25 @@ async function main() {
     throw new UsageError(error instanceof Error ? error.message : String(error));
   }
   const { values, positionals } = parsed;
-  if (positionals[0] !== "run" || positionals.length > 1) throw new UsageError('Expected the "run" command.');
+  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(", ")}.`);
@@ -103,17 +250,13 @@ async function main() {
   if (approvalPolicy !== void 0 && !APPROVAL_POLICIES.includes(approvalPolicy)) {
     throw new UsageError(`--approval-policy must be one of ${APPROVAL_POLICIES.join(", ")}.`);
   }
-  const environmentId = values.environment || process.env.CANON_ENVIRONMENT_ID;
-  if (!environmentId) throw new Error("CANON_ENVIRONMENT_ID (or --environment) is required.");
-  if (!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}.`);
-  }
-  const apiKey = process.env.CANON_API_KEY || profile.apiKey;
+  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({
@@ -121,7 +264,8 @@ async function main() {
       query: await loadClaudeQuery(),
       ...values.model ? { model: values.model } : {},
       ...permissionMode ? { permissionMode } : {},
-      ...values["claude-path"] ? { claudePath: resolve(values["claude-path"]) } : {}
+      ...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";
@@ -131,7 +275,8 @@ async function main() {
       codexPath,
       ...values.model ? { model: values.model } : {},
       ...sandbox ? { sandbox } : {},
-      ...approvalPolicy ? { approvalPolicy } : {}
+      ...approvalPolicy ? { approvalPolicy } : {},
+      ...instructions ? { instructions } : {}
     });
   } else {
     const modulePath = realpathSync(resolve(values.module));
@@ -144,10 +289,19 @@ async function main() {
     environmentId,
     home,
     driver,
-    baseUrl: process.env.CANON_BASE_URL || profile?.baseUrl,
-    streamUrl: process.env.CANON_STREAM_URL || profile?.streamUrl
+    ...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);
+  stopOnSignals(() => runner.stop());
   try {
     await runner.start();
   } catch (error) {
@@ -157,6 +311,100 @@ async function main() {
   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,
@@ -171,18 +419,144 @@ function parse() {
       "claude-path": { type: "string" },
       sandbox: { type: "string" },
       "approval-policy": { type: "string" },
-      "codex-path": { 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");
-function stopOnSignals(runner) {
+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.`);
-    runner.stop().then(() => process.exit(0), (error) => {
+    stop().then(() => process.exit(0), (error) => {
       console.error(`canon-agent: ${error instanceof Error ? error.message : String(error)}`);
       process.exit(1);
     });

package/dist/drivers/claude.d.ts

@@ -14,10 +14,16 @@ export interface ClaudeDriverOptions {
     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 anyone else's message
-     * may use only Canon's tools, AskUserQuestion and ToolSearch.
+     * `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). */

package/dist/drivers/codex.d.ts

@@ -8,9 +8,15 @@ export interface CodexDriverOptions {
     sandbox?: 'read-only' | 'workspace-write' | 'danger-full-access';
     /**
      * When Codex asks before acting in the owner's turns: `on-request` (the default), `untrusted` or `never`. Each request
-     * becomes a Canon approval. A turn holding anyone else's message is always read-only and approves nothing.
+     * becomes a Canon approval. A turn holding a message from anyone but the owner or a confirmed trusted agent of the owner
+     * (`TurnInputMessage.trustedAgent`) is always read-only and approves nothing.
      */
     approvalPolicy?: 'untrusted' | 'on-request' | 'never';
+    /**
+     * The owner's standing instructions for this agent (its role, say), appended to the thread's developer instructions
+     * after Canon's own framing. At most 32 KiB; the CLI reads them from `--instructions <file>`. Never sent to Canon.
+     */
+    instructions?: string;
     /** The Codex CLI (default: `codex` on the PATH). */
     codexPath?: string;
     /** How long an interrupted Codex may take to stop before its process is closed (default 5 s). */
@@ -23,7 +29,10 @@ export declare function checkCodex(codexPath?: string): string;
  * Codex's requests to its client, from the turn's thread or a subagent's. Approvals are scoped to exactly what they
  * allow: a session approval covers the same command with the same directory, network destination and permissions, the
  * same set of files or the same MCP tool, never "commands". A request whose scope is not fully known is approved once.
- * `rpcId` is the request's own JSON-RPC id, the identity of a request that names no item.
+ * A command's, file change's or permission request's key is `exec`, `apply_patch` or `permissions` and a digest of what
+ * it covers (`callScope`), which the runner keeps as it is and the cards offer as one exact call; an MCP approval's key
+ * names its server and tool, all of whose calls it covers. `rpcId` is the request's own JSON-RPC id, the identity of a
+ * request that names no item.
  */
 export declare function answerCodexRequest(turn: DriverTurn, method: string, params: Json, items: Map<string, Json>, rpcId: unknown): Promise<unknown>;
 /**

package/dist/drivers/connector.d.ts

@@ -0,0 +1,34 @@
+import { type ConnectorRelayAck, type ConnectorRelayClaim, type ConnectorRelayInputRef, type ConnectorRelaySettleOutcome } from '../internal/backend-contracts/index.js';
+import { type RuntimeDriver } from '../runner/types.js';
+/**
+ * The driver boundary (spec §11.3): what the relay channel calls on behalf of the remote assistant, through the
+ * connector's pickup tools. Each running turn is one pending input until the assistant claims it.
+ */
+export interface ConnectorInbox {
+    /** Unclaimed inputs in the room, oldest first. */
+    pending(conversationId: string, limit?: number): ConnectorRelayInputRef[];
+    /**
+     * The first claim gets `runAllowed` and the turn's input, once Canon confirms the agent may still act on it (its
+     * membership and the room's audience, read now, never from a hint); a repeat gets its state, never the input again.
+     * A claim that cannot be confirmed by `deadline` (epoch ms) is refused as busy and the input stays pending.
+     */
+    claim(inputId: string, requestId: string, options?: {
+        deadline?: number;
+    }): Promise<ConnectorRelayClaim>;
+    /** The turn's one final. */
+    reply(inputId: string, requestId: string, text: string): ConnectorRelayAck;
+    /** `completed` or `no_reply`: a silent turn; `failed`: the runner's failure notice. */
+    settle(inputId: string, requestId: string, outcome: ConnectorRelaySettleOutcome): ConnectorRelayAck;
+}
+export interface ConnectorDriver extends RuntimeDriver {
+    readonly name: 'connector';
+    readonly inbox: ConnectorInbox;
+}
+/**
+ * The `connector` driver: the runtime is an assistant its provider runs (ChatGPT, Claude.ai and the like), reached
+ * through Canon's remote MCP connector, so a turn waits, as one pending input, for the assistant to claim it and answer
+ * through the connector's pickup tools (spec §11.3). It keeps no timer: an assistant that never answers is the runner's
+ * no-progress deadline, which a claim restarts. It never calls Canon itself; the relay channel calls its inbox, and the
+ * runner confirms each claim with Canon.
+ */
+export declare function connectorDriver(): ConnectorDriver;