@canonmsg/agent-sdk 12.0.0 → 12.2.0

package/dist/runner/runner.d.ts

@@ -1,6 +1,15 @@
+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. */
@@ -13,12 +22,48 @@ export interface RunnerOptions {
     /** 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. */
@@ -31,6 +76,22 @@ export interface Runner {
     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;

package/dist/runner/types.d.ts

@@ -5,7 +5,7 @@ import type { MediaAttachment } from '../internal/core/index.js';
  * the claude and codex drivers pass the conformance suite.
  */
 export interface RuntimeDriver {
-    readonly name: 'code' | 'claude' | 'codex' | 'hermes';
+    readonly name: 'code' | 'claude' | 'codex' | 'connector';
     /** Input to the generated runtime descriptor; never a static table. */
     readonly capabilities: DriverCapabilities;
     runTurn(turn: DriverTurn): Promise<DriverResult>;
@@ -34,6 +34,12 @@ export interface DriverTurn {
     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 {
@@ -56,6 +62,12 @@ export interface DriverCapabilities {
     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;
 }
@@ -67,9 +79,9 @@ export type ActivityEvent = {
 };
 export type AskRequest = 
 /**
- * `scopeKey`: what a session approval covers, e.g. the runtime's tool name. 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.
+ * `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';
@@ -140,6 +152,13 @@ export interface TurnInputMessage {
     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>;
@@ -156,13 +175,41 @@ export interface TurnInput {
         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": "12.0.0",
+  "version": "12.2.0",
   "description": "Canon Agent SDK — build AI agents that participate in Canon conversations",
   "type": "module",
   "main": "dist/index.js",