@canonmsg/agent-sdk 11.2.1 → 12.1.0

package/dist/runner/errands.d.ts

@@ -0,0 +1,118 @@
+/** `tell` and `post` (§12.3, §12.4), `errand` (§12.6) and `cancel`, which ends an errand. */
+export declare const ERRAND_KINDS: readonly ["tell", "post", "errand", "cancel"];
+export type ErrandKind = (typeof ERRAND_KINDS)[number];
+/** At most what one encrypted message holds (§6), so a post is never cut. */
+export declare const ERRAND_TEXT_MAX_BYTES: number;
+/** An errand's why, at most. */
+export declare const ERRAND_WHY_MAX_BYTES: number;
+/** A command not taken within a day is refused, and a note no turn used within a day expires. */
+export declare const ERRAND_TTL_MS: number;
+/** An errand stays open for replies this long after the agent reached its recipient, or after the last reply. */
+export declare const ERRAND_OPEN_MS: number;
+/** What the operator asks for: a note or a post for a room, an errand, or the end of an errand. */
+export type ErrandInput = {
+    kind: 'tell' | 'post';
+    conversationId: string;
+    text: string;
+}
+/** `to`: a room the agent is in, or a person or agent to start a new conversation with; `text`: the instruction. */
+ | {
+    kind: 'errand';
+    to: string;
+    why: string;
+    text: string;
+    origin?: string;
+} | {
+    kind: 'cancel';
+    errand: string;
+};
+/** One command, as the CLI writes it into the inbox. */
+export type ErrandCommand = ErrandInput & {
+    version: 1;
+    id: string;
+    createdAt: string;
+};
+/**
+ * What the runner did with a command. A note: `pending` until its room's next turn marks it `used`. A post: `sending`,
+ * then `sent`. An errand: `pending`, `running` (its turn), then `waiting` once the agent reached the recipient, `replied`
+ * when a turn ran there on a reply, `done` when its turn ended without reaching them, `failed`, `cancelled` (Stop in the
+ * origin, or `cancel`), `interrupted` (the runner stopped during its turn, which never runs again) or `expired`. A cancel
+ * is `applied`. Any command: `refused` (valid, but the runner could not apply it), `rejected` (not a valid command file),
+ * `expired` (too old).
+ */
+export type ErrandStatus = 'pending' | 'used' | 'sending' | 'sent' | 'running' | 'waiting' | 'replied' | 'done' | 'failed' | 'cancelled' | 'interrupted' | 'applied' | 'refused' | 'rejected' | 'expired';
+export interface ErrandRecord {
+    version: 1;
+    id: string;
+    status: ErrandStatus;
+    updatedAt: string;
+    kind?: ErrandKind;
+    createdAt?: string;
+    reason?: string;
+    /** A note's or a post's room; an errand's once the agent reached its recipient there. */
+    conversationId?: string;
+    /** The installation scope it was taken under (§5): a note or an errand is acted on only under the same one. */
+    scope?: string;
+    /** A pending note's text, dropped once the note leaves `pending`; an errand's instruction. */
+    text?: string;
+    /** The turn that used a note; an errand's turn. */
+    turnId?: string;
+    /** An errand: its recipient (a room, or a person or agent to start a conversation with), why, and origin room. */
+    to?: string;
+    target?: 'room' | 'contact';
+    why?: string;
+    origin?: string;
+    /** An errand: when its turn reached the recipient, and the last reply there. */
+    reachedAt?: string;
+    repliedAt?: string;
+    /** An errand: its report kept here, when it may not go to the origin (§12.7), and how the one sent there went. */
+    report?: string;
+    reported?: 'sending' | 'sent' | 'refused';
+    /** A cancel: the errand it ends. */
+    errand?: string;
+}
+/** An agent's errands in the home: `runner/<env>/<agentId>/errands/` (spec §5). */
+export declare function errandsDirectory(home: string, environmentId: string, agentId: string): string;
+/** The inbox directory, created private if missing; one that is not this uid's private directory is refused. */
+export declare function errandInbox(directory: string): string;
+/** The operator's side (the CLI, or a library caller): one durable command file in the inbox. Throws on an invalid command. */
+export declare function queueErrand(directory: string, input: ErrandInput): ErrandCommand;
+/** The runner's records, one file per command taken (§12.2). */
+export declare function errandJournal(directory: string): {
+    has: (id: string) => boolean;
+    get: (id: string) => ErrandRecord | undefined;
+    put: (record: ErrandRecord) => void;
+    list(): ErrandRecord[];
+};
+export type ErrandJournal = ReturnType<typeof errandJournal>;
+/**
+ * `--wait` (§12.1): the command's record once the runner has answered it, or as it stands after `ms`, and whether it was
+ * accepted. A post (or an errand's report) Canon has not answered stays `sending` and is not accepted, though the runner
+ * keeps it and goes on delivering it: it may yet be refused.
+ */
+export declare function awaitErrand(directory: string, command: Pick<ErrandCommand, 'id' | 'kind'>, ms: number): Promise<{
+    record: ErrandRecord | undefined;
+    accepted: boolean;
+}>;
+export interface ErrandHandler {
+    /** The command was taken already (its record or its journaled output exists): its file is only removed. */
+    taken(id: string): boolean;
+    /**
+     * The command, or why its file is refused. True once its effect (or refusal) is journaled, so the file may go; false
+     * leaves it for the next scan. A throw is logged once per command and reason, and also leaves it.
+     */
+    take(id: string, command: ErrandCommand | {
+        problem: string;
+    }): Promise<boolean>;
+}
+/**
+ * §12.1: watches the inbox and scans it every `intervalMs` as a backstop (and at once), one scan at a time, files in
+ * name order. A file is removed only after the handler has journaled what it did with it.
+ */
+export declare function watchErrandInbox(directory: string, handler: ErrandHandler, options: {
+    log: (line: string) => void;
+    intervalMs?: number;
+}): {
+    close(): Promise<void>;
+};
+export type ErrandInbox = ReturnType<typeof watchErrandInbox>;

package/dist/runner/mls.d.ts

@@ -0,0 +1,97 @@
+import { type CanonEndpoint, type CanonMlsDevOptions, type MlsDevCurrentAudience } from '../internal/core/index.js';
+import { type MlsDevDeviceContext } from '../internal/backend-contracts/index.js';
+import type { ToolDefinition } from './types.js';
+/** What `createRunner({ mls })` takes: issuer pins and custody, plus the custody's own shutdown. */
+export type RunnerMlsOptions = CanonMlsDevOptions & {
+    close?(): Promise<void>;
+};
+/** A closed copy of the public audience (no provider input or key material), in a fixed field order. */
+export declare function snapshotMlsAudience(value: unknown): MlsDevCurrentAudience;
+/**
+ * The principals who can read the room, each with its admission (an agent also with its ownership version), sorted: the
+ * set the server's device-only re-ask rule compares (encrypted-interactions.md §4), never the devices themselves. A
+ * principal reading through a device Canon operates (a class-C relay, §11) counts apart, so a relay device joining or
+ * leaving is never a device-only change.
+ */
+export declare function mlsAudiencePrincipals(value: MlsDevCurrentAudience): string[];
+/**
+ * The audience's epoch: who can read the room, which is its principals with their admissions, the membership revision
+ * and this device's own place in the group. A device-only change (a member adds or removes a device and keeps one) is a
+ * re-key, not an audience change (§4), so the group head and the device set are left out, as is the feed cursor, which
+ * ordinary text moves.
+ */
+export declare function mlsAudienceEpoch(value: MlsDevCurrentAudience): string;
+/** What an encrypted room's text message is to the runner; Canon never learns it (`MlsIds.text`). */
+export type MlsTextKind = 'final' | 'failed' | 'restart' | 'said' | 'item';
+/**
+ * §6 ids. Canon sees the message id of everything the runner sends to an encrypted room, and a card's request id (its
+ * public binding), so these are keyed with a secret only this installation holds (`privateKey`): HMAC-SHA256 over
+ * domain-separated inputs, cut to 128 bits. Canon can test no guess of the text, question or turn an id names, and every
+ * text message (a final, a failure or restart notice, a `communicate` send, an item) has the same shape, `msg-<32 hex>`, so none
+ * says what kind it is. The same inputs give the same id after a restart, so journal replay, a repeated `communicate`,
+ * a re-asked card and a restart notice keep theirs.
+ */
+export interface MlsIds {
+    /** A text message's id: `parts` name it (the turn, or the turn and a `communicate` send's text). */
+    text(kind: MlsTextKind, conversationId: string, ...parts: string[]): string;
+    /** A card's request id, `ask-<32 hex>` (`MLS_DEV_INTERACTION_ID_PATTERN`), for the runtime's ask `askId` in turn `turnId`. */
+    request(conversationId: string, turnId: string, askId: string): string;
+}
+/** The installation's id key: random bytes, created once under CANON_HOME. */
+export declare const MLS_ID_KEY_BYTES = 32;
+export declare function createMlsIds(key: Uint8Array): MlsIds;
+/**
+ * Encrypted rooms are for agents whose outbound communication is not closed, in an environment with an MLS profile. Canon
+ * decides who joins a room under the invitation policies, as for plaintext rooms, and whether that environment runs MLS.
+ */
+export declare function requireMlsSupport(input: {
+    environmentId: string;
+    agent: {
+        outboundPolicy: string;
+    };
+}): void;
+/**
+ * Whether `text` @mentions any of `names` (an agent's display name, id or aliases). Encrypted text carries no `mentions[]`,
+ * so this is how one agent addresses another there: `@`, not preceded by a letter, digit, `_` or `@` (so no address
+ * like `ops@example.com`), then the name in any case, with any run of whitespace for a space, not followed by a letter,
+ * digit, mark or `_` (`@Cipher A` does not mention `Cipher AB`).
+ */
+export declare function mentionsAgent(text: string, names: ReadonlyArray<string | undefined>): boolean;
+/** An encrypted turn's `communicate`: listing, and text to its own room, which the runner encrypts. */
+export declare const ENCRYPTED_COMMUNICATE: ToolDefinition;
+/**
+ * The operator's MLS configuration file: public issuer pins and the custody helper's identity, never credentials or
+ * private keys. A canonical, current-user-owned regular file, not group- or other-writable, at most 64 KiB, read once.
+ * Its configuration must be for the environment the runner runs in.
+ */
+export declare function loadMlsDevConfiguration(filePath: string, input: {
+    environmentId: string;
+}): Promise<RunnerMlsOptions & {
+    provision?: (context: MlsDevDeviceContext) => Promise<void>;
+    close(): Promise<void>;
+}>;
+export declare const MLS_SETUP_ACTIONS: readonly ["status", "provision", "enroll", "renew", "publish", "refresh"];
+export type MlsSetupAction = typeof MLS_SETUP_ACTIONS[number];
+/** The KeyPackage an agent publishes for one room: stable for its installation, so a repeated publish is the same intent. */
+export declare function mlsDevRoomPackageId(identity: {
+    environmentId: string;
+    principalId: string;
+    installationId: string;
+    ownershipVersion?: number;
+}, room: string): string;
+/**
+ * One operator step for the agent's device (`canon-agent mls`), on the same engine store the runner uses. It never
+ * starts a model, and prints only public device state: no credentials, proofs, envelopes or history.
+ */
+export declare function runMlsDevSetup(endpoint: CanonEndpoint, action: MlsSetupAction, room?: string, provision?: (context: MlsDevDeviceContext) => Promise<void>): Promise<{
+    conversationId?: string | undefined;
+    version: number;
+    action: "status" | "publish" | "enroll" | "renew" | "provision" | "refresh";
+    environmentId: "canon-dev-v1" | "canon-prod-v1";
+    principalId: string;
+    installationId: string;
+    ownershipVersion: number | undefined;
+    status: "absent" | "identity_committed" | "registered" | "credential_committed" | "revoked";
+    deviceId: string | null;
+    credentialGeneration: number;
+}>;

package/dist/runner/relay.d.ts

@@ -0,0 +1,87 @@
+import { type ConnectorRelayCredentialDelivery } from '../internal/backend-contracts/index.js';
+import type { ConnectorInbox } from '../drivers/connector.js';
+import type { Runner } from './runner.js';
+/** What the channel serves: the relay's runner (history and sends) and its connector driver's inbox (pickup). */
+export interface RelayTarget {
+    runner: Pick<Runner, 'relayRead' | 'relaySend'>;
+    inbox: ConnectorInbox;
+}
+/** Canon's credential for this relay, as delivered: the connection it serves is the delivering request's. */
+export type RelayCredentialDelivery = ConnectorRelayCredentialDelivery & {
+    grantId: string;
+};
+export interface RelayChannelOptions {
+    /** The runner and inbox to serve from the start; `serve` sets or replaces them. Until then only `credential` is answered. */
+    runner?: Pick<Runner, 'relayRead' | 'relaySend'>;
+    inbox?: ConnectorInbox;
+    /** The relayed agent: requests naming another agent are refused. */
+    agentId: string;
+    /**
+     * The connector connection served: requests naming another are refused. A credential delivery (the owner's approval)
+     * names its own connection and moves the relay to it.
+     */
+    grantId?: string;
+    /** The Standard Webhooks secret (`whsec_…`) Functions signs with: this agent's alone. */
+    secret: string;
+    /**
+     * Canon delivers the relay's credential here when the owner approves, or re-approves, the relay; the channel confirms
+     * the delivery once this resolves, so it should keep the credential durably first. Without it, deliveries are refused.
+     */
+    onCredential?: (delivery: RelayCredentialDelivery) => void | Promise<void>;
+    /** Default 127.0.0.1 and a random port. */
+    host?: string;
+    port?: number;
+    /** Never receives message text. */
+    log?: (line: string) => void;
+    /** Test seam: the clock signatures are checked against. */
+    now?: () => number;
+    /** Test seam: how long an exchange may take before it is answered (default `CONNECTOR_RELAY_ANSWER_WITHIN_MS`). */
+    answerWithinMs?: number;
+}
+export interface RelayChannel {
+    readonly url: string;
+    /** Serves this runner and inbox for `grantId` (default: the connection already served), or nothing (`undefined`). */
+    serve(target: RelayTarget | undefined, grantId?: string): void;
+    close(): Promise<void>;
+}
+export declare function relaySecretKey(secret: string): Buffer;
+/** The headers Functions sends (as the `standardwebhooks` library signs them); the tests' stand-in for Functions uses it. */
+export declare function signRelayRequest(secret: string, id: string, body: string, nowMs?: number): Record<string, string>;
+/** Starts the channel. Every request is authenticated before its body is parsed; refusals carry no detail. */
+export declare function startRelayChannel(options: RelayChannelOptions): Promise<RelayChannel>;
+export interface RelayConfiguration {
+    environmentId: string;
+    agentId: string;
+    listen: {
+        host: string;
+        port: number;
+    };
+    secret: string;
+}
+/**
+ * The operator's relay configuration (`--relay-config`): which agent this process relays, where the channel listens, and
+ * the path of the channel secret, itself a private file. The connection, installation and credential come from Canon,
+ * with the credential, when the owner approves the relay.
+ */
+export declare function loadRelayConfiguration(path: string, input: {
+    environmentId: string;
+}): Promise<RelayConfiguration>;
+/** The relay's credential as it keeps it: `<CANON_HOME>/relay/credential.json`, 0600, written whole or not at all. */
+export interface StoredRelayCredential {
+    version: 1;
+    environmentId: string;
+    agentId: string;
+    grantId: string;
+    installationId: string;
+    generation: number;
+    credential: string;
+}
+/** The credential Canon delivered to this relay, if any; one for another agent or environment is refused. */
+export declare function readRelayCredential(home: string, relay: Pick<RelayConfiguration, 'environmentId' | 'agentId'>): Promise<StoredRelayCredential | undefined>;
+/** Keeps a delivered credential durably (fsync, then rename), private to this user, before the delivery is confirmed. */
+export declare function writeRelayCredential(home: string, relay: Pick<RelayConfiguration, 'environmentId' | 'agentId'>, delivery: RelayCredentialDelivery): StoredRelayCredential;
+/**
+ * Where the runner for one relay installation keeps its state (engine store, journal, lock): a private directory per
+ * installation, so a new approval (a new installation and device) starts clean beside the old one.
+ */
+export declare function relayRunnerHome(home: string, installationId: string): string;

package/dist/runner/runner.d.ts

@@ -0,0 +1,98 @@
+import { type ConnectorRelayPage, type ConnectorRelaySent } from '../internal/backend-contracts/index.js';
+import { type CanonEndpoint, type CanonRuntimeDescriptor, type CommunicateInput, type CommunicateResult } from '../internal/core/index.js';
+import { type RunnerMlsOptions } from './mls.js';
+import { type RuntimeDriver } from './types.js';
+export interface RunnerOptions {
+    /** Canon refused this runner for good (its client floor, mls-cutover-operator.md §2 15b); the CLI stops and exits. */
+    onFatal?(error: Error): void;
+    /** How the runner names itself to Canon's client floor (`X-Canon-Client`); the CLI passes agent-sdk's version. */
+    client?: {
+        kind: 'runner';
+        version: string;
+    };
+    apiKey: string;
+    environmentId: string;
+    /** CANON_HOME: a private 0700 directory, checked before anything is opened. */
+    home: string;
+    driver: RuntimeDriver;
+    /** Test seam: an injected endpoint engine. Production never sets it. */
+    endpoint?: CanonEndpoint;
+    /** Test seam: HTTP outside the endpoint protocol (health, identity). Production never sets it. */
+    fetch?: typeof fetch;
+    /** Test-only origin overrides (the CLI's CANON_BASE_URL and CANON_STREAM_URL). */
+    baseUrl?: string;
+    streamUrl?: string;
+    /**
+     * The agent's MLS device (Dev only, spec §6): issuer pins and custody, from `loadMlsDevConfiguration`. With it the
+     * runner takes part in encrypted rooms; without it each encrypted room is refused, once, in the log. An injected
+     * `endpoint` that already has an MLS device counts as configured. `close` runs last on shutdown.
+     */
+    mls?: RunnerMlsOptions;
+    /**
+     * Relay mode, the class-C relay (spec §11.4): only encrypted rooms are served, which is what lets a `remote` driver
+     * (the connector) into them. Plaintext input is cancelled with no turn (the connector's own installation serves it),
+     * control hints are read only for encrypted rooms, no runtime descriptor is published, and `relayRead` and `relaySend`
+     * serve the relay channel. It needs the agent's MLS device.
+     */
+    relay?: boolean;
+    /** The engine's installation: the relay's reserved one, from its configuration. A store opened under another refuses to start. */
+    installationId?: string;
+    /**
+     * Team rooms: agents the owner trusts. A message from one of them counts as the owner's for tool permissions (the
+     * drivers' guards read `TurnInputMessage.trustedAgent`) only in a room that holds no one but this agent, its owner and
+     * listed agents, all of which Canon confirms at the start of the turn are active agents of this agent's own owner; in
+     * a plaintext room only for a final its runner marked as answering the owner or confirmed teammates alone, and in an
+     * encrypted room never with a relay device in the group. A `remote` runtime has no tools on this host: a relay ignores it.
+     */
+    trustedAgents?: string[];
+    /**
+     * Encrypted rooms (§6): how many messages from other agents that @mention this agent a room may wake it with before a
+     * person's message is admitted there again (default 6; 0 never wakes on an agent). Past the cap they are settled with
+     * no turn, logged once. Plaintext rooms are Canon's to dispatch (RUN-29).
+     */
+    agentTurnCap?: number;
+    /** Encrypted rooms: names besides the agent's display name and id that @mention it, such as a role (`@engineer`). */
+    mentionAliases?: string[];
+    /** How long an aborted turn may take to settle before its session is reset (default 10 s). */
+    abortGraceMs?: number;
+    /** A turn with no text or activity for this long fails (default 30 min); the clock waits while an `ask` is pending. */
+    noProgressMs?: number;
+    /** How long an `ask` waits for its answer before it expires (default 1 h; an expired approval is a denial). */
+    askExpiryMs?: number;
+    /**
+     * Encrypted rooms (encrypted-interactions.md §3): whether an approval the runtime's harness marked `risk: 'destructive'`
+     * may offer the owner a session rule. Off by default, so each such action asks; other approvals keep session rules.
+     */
+    sessionApprovalForDestructive?: boolean;
+    /** How long running turns may finish on shutdown before they are aborted (default 10 s). */
+    shutdownGraceMs?: number;
+    /** Never receives prompt or reply text. */
+    log?: (line: string) => void;
+}
+export interface Runner {
+    /** Connects and starts taking input; resolves once listening is set up. */
+    start(): Promise<void>;
+    /** Stops intake, releases unsubmitted input, lets running turns finish within the shutdown grace. */
+    stop(): Promise<void>;
+    /** A proactive send outside any turn (cron): the `communicate` tool's handler, under the runner's identity. */
+    communicate(input: CommunicateInput): Promise<CommunicateResult>;
+    /**
+     * Relay mode (§11.6): an encrypted room's history as this device verified it and Canon accepted it, newest first, cut
+     * to the channel's response budget. `deadline` (epoch ms, default the channel's answer budget) bounds the read.
+     */
+    relayRead(conversationId: string, page?: {
+        limit?: number;
+        before?: string;
+        deadline?: number;
+    }): Promise<ConnectorRelayPage>;
+    /**
+     * Relay mode (§11.6): encrypted text to a room outside any turn, journaled first; the same `messageId` is the same
+     * message. It answers by `deadline`: `pending` only once journaled, a busy refusal (nothing journaled) before that.
+     */
+    relaySend(conversationId: string, messageId: string, text: string, options?: {
+        deadline?: number;
+    }): Promise<ConnectorRelaySent>;
+}
+/** RUN-27: generated once from the driver's declarations; no static capability table. */
+export declare function runtimeDescriptor(driver: RuntimeDriver): CanonRuntimeDescriptor;
+export declare function createRunner(options: RunnerOptions): Promise<Runner>;

package/dist/runner/types.d.ts

@@ -0,0 +1,215 @@
+import type { MediaAttachment } from '../internal/core/index.js';
+/**
+ * A runtime adapter: it only runs turns. Canon semantics (inbox, queue, Stop,
+ * turn identity, delivery, descriptor) belong to the runner. Experimental until
+ * the claude and codex drivers pass the conformance suite.
+ */
+export interface RuntimeDriver {
+    readonly name: 'code' | 'claude' | 'codex' | 'hermes' | 'connector';
+    /** Input to the generated runtime descriptor; never a static table. */
+    readonly capabilities: DriverCapabilities;
+    runTurn(turn: DriverTurn): Promise<DriverResult>;
+    /** Discard the native session, even mid-turn. */
+    reset?(session: string): Promise<void>;
+    /** Process shutdown only. */
+    close?(): Promise<void>;
+}
+export interface DriverTurn {
+    /** Native-session key: the conversation id. */
+    session: string;
+    /** Canon-rendered input for the model. */
+    prompt: string;
+    /** The same facts, structured and read-only; no Canon handle. */
+    input: TurnInput;
+    /** Absolute paths of this turn's materialized inbound attachments. */
+    files: string[];
+    /** The only control: Stop, no_reply, deadline, membership loss, shutdown. */
+    signal: AbortSignal;
+    /** The full visible answer so far (never a delta); preview only, never durable. */
+    onText(snapshot: string): void;
+    /** Minimal "working on…" status; replaces the row with the same id. */
+    onActivity(event: ActivityEvent): void;
+    ask(request: AskRequest): Promise<AskAnswer>;
+    /** Persisted by the runner, scoped to (installation, driver, session). */
+    state: DriverState;
+    /** Runner tools bound to this turn by a per-turn token. */
+    tools: TurnTools;
+    /**
+     * For a `remote` runtime, before its input first leaves this host (the connector's claim): the runner reads the
+     * agent's membership, and an encrypted room's audience, from Canon now and counts the pickup as progress (RUN-12).
+     * It rejects, and ends the turn, when the agent may no longer act on this input; a transient failure only rejects.
+     */
+    confirmPickup(): Promise<void>;
+}
+/** `reply: null` is deliberate silence. */
+export interface DriverResult {
+    reply: string | null;
+    files?: string[];
+}
+export interface DriverCapabilities {
+    /** 'none': every prompt carries the recent history window. */
+    sessionMemory: 'native' | 'none';
+    ask: ReadonlyArray<'approve' | 'choose' | 'text'>;
+    streaming: boolean;
+    activity: boolean;
+    /** The runtime can call TurnTools; required for model-driven no_reply. */
+    tools: boolean;
+    /**
+     * The runtime has a question tool of its own that the driver maps to `ask` (Claude Code's AskUserQuestion). Without
+     * one, a driver declaring `choose` and `text` gets the runner's `ask_question` tool, so a runtime never has two.
+     */
+    nativeQuestions?: boolean;
+    outboundFiles: {
+        roots: string[];
+    } | false;
+    /**
+     * The runtime runs off the runner's host (the class-C connector, spec §11.3): it gets no local files (inbound
+     * attachments are named in the prompt, never materialized), and since its plaintext leaves this host, the runner
+     * takes it into encrypted rooms only in relay mode, whose installation discloses that.
+     */
+    remote?: boolean;
+    /** Across rooms; runner default 8. */
+    maxConcurrentTurns?: number;
+}
+export type ActivityEvent = {
+    id: string;
+    kind: 'tool' | 'status';
+    title: string;
+    state: 'running' | 'done' | 'failed';
+};
+export type AskRequest = 
+/**
+ * `scopeKey`: what a session approval covers, e.g. the exact call (a tool and its whole input). Asks with the same key
+ * share the owner's session rule; without one, a rule covers only this exact title. A key of letters, digits, `_`, `:`
+ * and `-` (up to 64) is kept as the card's tool name and compared without regard to case; any other key is hashed.
+ */
+{
+    kind: 'approve';
+    id: string;
+    title: string;
+    detail?: string;
+    risk?: 'normal' | 'destructive';
+    allowSession?: boolean;
+    scopeKey?: string;
+} | {
+    kind: 'choose';
+    id: string;
+    question: string;
+    options: Array<{
+        id: string;
+        label: string;
+    }>;
+    multiple?: boolean;
+}
+/** `secret`: owner only, the value is never posted. */
+ | {
+    kind: 'text';
+    id: string;
+    question: string;
+    secret?: boolean;
+};
+export type AskAnswer = {
+    status: 'answered';
+    by: string;
+    allow?: boolean;
+    scope?: 'once' | 'session';
+    choices?: string[];
+    text?: string;
+} | {
+    status: 'expired' | 'cancelled';
+};
+/** JSON only, at most 64 KiB per session; durable before the turn's inputs settle. */
+export interface DriverState {
+    get<T>(key: string): T | undefined;
+    set(key: string, value: unknown): void;
+    delete(key: string): void;
+}
+export interface ToolDefinition {
+    name: string;
+    description: string;
+    inputSchema: Record<string, unknown>;
+}
+export interface ToolResult {
+    content: Array<{
+        type: 'text';
+        text: string;
+    }>;
+    isError?: boolean;
+}
+export interface TurnTools {
+    /** 128-bit, valid only while this turn is open. */
+    token: string;
+    /** http://127.0.0.1:<port>/mcp/t/<token> (MCP Streamable HTTP). */
+    url: string;
+    /** no_reply, communicate, react, send_file (with outbound roots) and ask_question (without native questions). */
+    definitions: ToolDefinition[];
+    /** The same handlers, in process. */
+    call(name: string, args: unknown): Promise<ToolResult>;
+}
+export interface TurnInputMessage {
+    readonly id: string;
+    readonly senderId: string;
+    readonly senderName?: string;
+    readonly senderType: 'human' | 'ai_agent';
+    readonly isOwner: boolean;
+    /**
+     * Set only on a message from an agent the owner listed as trusted (`RunnerOptions.trustedAgents`), in a room of the
+     * owner's agents that Canon confirmed at this turn's start (see `trustedAgents` for the whole rule). Drivers treat such
+     * a message as the owner's for tool permissions; it is never the owner (`isOwner` stays false), and approvals still go
+     * to the owner.
+     */
+    readonly trustedAgent?: true;
+    readonly text: string;
+    readonly contentType: string;
+    readonly attachments: ReadonlyArray<MediaAttachment>;
+    readonly mentions: ReadonlyArray<string>;
+    readonly replyTo?: string;
+    readonly createdAt: string;
+}
+export interface TurnInput {
+    readonly conversationId: string;
+    readonly room: 'direct' | 'group';
+    /** Sender of the newest input (the turn's trigger). */
+    readonly sender: {
+        readonly id: string;
+        readonly name?: string;
+        readonly type: 'human' | 'ai_agent';
+        readonly isOwner: boolean;
+        readonly trustedAgent?: true;
+    };
+    /** This turn's inputs, oldest first. */
+    readonly messages: ReadonlyArray<TurnInputMessage>;
+    /** For drivers without session memory: up to 20 earlier messages since the agent's admission, oldest first. */
+    readonly history: ReadonlyArray<TurnInputMessage>;
+    /**
+     * The owner's private notes for this turn (`canon-agent tell`, spec §12.3), oldest first, also at the head of `prompt`:
+     * context from the machine the runner runs on, never a message in the conversation. They do not change whose turn it is.
+     */
+    readonly ownerNotes?: ReadonlyArray<string>;
+    /**
+     * An errand turn (`canon-agent errand`, spec §12.6): the owner's errand, also in `prompt`. Its one message is the owner's,
+     * written by the runner; its final is the report to the owner.
+     */
+    readonly errand?: ErrandFacts;
+    /** Open errands that brought the agent into this conversation (§12.6), also at the head of `prompt`. */
+    readonly errands?: ReadonlyArray<ErrandFacts>;
+}
+/** An errand as a turn sees it: why the owner sent the agent, what to do, the recipient and the origin conversation. */
+export interface ErrandFacts {
+    readonly id: string;
+    readonly why: string;
+    readonly instruction: string;
+    readonly to: string;
+    readonly origin?: string;
+}
+/** Thrown by a driver whose native session is unusable: the turn fails and the runner resets the session. */
+export declare class DriverSessionError extends Error {
+    name: string;
+}
+/** A relay channel refusal (spec §11.6): the channel answers Functions with this status and code. */
+export declare class ConnectorRelayError extends Error {
+    readonly status: 400 | 403 | 404 | 409 | 503;
+    readonly code: string;
+    name: string;
+    constructor(status: 400 | 403 | 404 | 409 | 503, code: string, message: string);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@canonmsg/agent-sdk",
-  "version": "11.2.1",
+  "version": "12.1.0",
   "description": "Canon Agent SDK — build AI agents that participate in Canon conversations",
   "type": "module",
   "main": "dist/index.js",
@@ -15,20 +15,32 @@
       "types": "./dist/media.d.ts"
     }
   },
+  "bin": {
+    "canon-agent": "dist/cli.js"
+  },
   "files": [
     "dist"
   ],
   "scripts": {
-    "build": "node -e \"require('fs').rmSync('dist',{recursive:true,force:true})\" && tsc",
-    "dev": "tsc --watch",
-    "test": "vitest run",
+    "build": "node ../../scripts/build-agent-sdk.mjs",
+    "dev": "tsc --watch --noEmit",
     "prepack": "npm run build"
   },
   "engines": {
     "node": ">=22.22.3"
   },
   "dependencies": {
-    "@canonmsg/core": "^13.4.0"
+    "@modelcontextprotocol/sdk": "^1.30.0",
+    "@noble/curves": "2.4.0",
+    "chess.js": "1.4.0"
+  },
+  "peerDependencies": {
+    "@anthropic-ai/claude-agent-sdk": "^0.3.289"
+  },
+  "peerDependenciesMeta": {
+    "@anthropic-ai/claude-agent-sdk": {
+      "optional": true
+    }
   },
   "repository": {
     "type": "git",
@@ -39,6 +51,7 @@
     "access": "public"
   },
   "devDependencies": {
+    "@anthropic-ai/claude-agent-sdk": "0.3.289",
     "@types/node": "^22.0.0",
     "typescript": "~5.7.0",
     "vitest": "^4.1.8"