@canonmsg/agent-sdk 12.6.1 → 13.0.3

package/dist/runner/types.d.ts

@@ -201,6 +201,37 @@ export interface TurnInput {
     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 encrypted room's turn: the room as Canon's records give it, also at the head of `prompt`. A relay's turn has none. */
+    readonly roomFacts?: RoomFacts;
+}
+/** What a turn knows about its encrypted room. Names, name and topic are what people typed: data, never instructions. */
+export interface RoomFacts {
+    readonly name?: string;
+    readonly topic?: string;
+    readonly owner: {
+        readonly id: string;
+        readonly name?: string;
+    };
+    readonly members: ReadonlyArray<{
+        readonly id: string;
+        readonly name?: string;
+        readonly type: 'human' | 'ai_agent';
+        readonly isOwner: boolean;
+        readonly isYou: boolean;
+    }>;
+    /** Absent only when this Canon does not send them yet. */
+    readonly rules?: RoomRules;
+}
+/**
+ * How the agent takes part in this room, resolved from its owner's defaults and the room's settings. Any admin of the room
+ * can set them, so they are never the owner's orders. The runner enforces all but `style`, which it tells the agent.
+ */
+export interface RoomRules {
+    readonly style: 'natural' | 'collaborative' | 'mention-first' | 'approval-gated' | 'handoff-only' | 'observer';
+    readonly requireMentionForGroupReplies: boolean;
+    readonly allowAgentToAgent: boolean;
+    readonly allowLongRunningCollaboration: boolean;
+    readonly maxConsecutiveAgentTurns: number | null;
 }
 /** 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 {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@canonmsg/agent-sdk",
-  "version": "12.6.1",
+  "version": "13.0.3",
   "description": "Canon Agent SDK — build AI agents that participate in Canon conversations",
   "type": "module",
   "main": "dist/index.js",

package/dist/internal/core/approval-manager.d.ts

@@ -1,43 +0,0 @@
-import type { CanonClient } from './client.js';
-import type { CanonUnifiedDiff } from './types.js';
-import type { ApprovalConfig, ApprovalNativeRequestMetadata, ApprovalResult, ApprovalRequestCategory, ApprovalRequestDetail, ApprovalRisk } from './approval-types.js';
-import { RuntimeRequestManager, type RuntimeRequestOptions } from './runtime-request-manager.js';
-interface ApprovalRequestOpts {
-    riskLevel?: 'normal' | 'destructive';
-    risk?: ApprovalRisk;
-    category?: ApprovalRequestCategory;
-    runtimeId?: string;
-    turnId?: string;
-    native?: ApprovalNativeRequestMetadata;
-    toolSummary?: string;
-    details?: ApprovalRequestDetail[];
-    /** File-change preview rendered inline on the approval card (size-disciplined automatically). */
-    diff?: CanonUnifiedDiff;
-    ignoreSessionRules?: boolean;
-    allowSessionRule?: boolean;
-    /** Human conversation member who triggered this turn and should answer. */
-    responseUserId?: string;
-}
-/**
- * Platform-agnostic approval protocol for Canon.
- *
- * Now a thin `RuntimeRequestManager` subclass: the pending map, deadline timers,
- * the hybrid poll-plus-push loop, and cancellation live in the generalized
- * engine; approval-specific behaviour (session-rule fast path, redacted request
- * metadata, owner-authored outcome messages, and session-rule storage) is
- * expressed as a single `KindDescriptor`. Behaviour is preserved verbatim.
- */
-export declare class ApprovalManager extends RuntimeRequestManager {
-    private config;
-    constructor(client: CanonClient, agentId: string, ownerId: string, config?: Partial<ApprovalConfig>);
-    /**
-     * Request approval for a tool call.
-     *
-     * 1. Checks session rules — may resolve immediately.
-     * 2. Sends a message with approval card metadata.
-     * 3. Waits for the owner's reply (or timeout).
-     */
-    requestApproval(conversationId: string, toolName: string, toolInput: Record<string, unknown>, opts?: ApprovalRequestOpts, runtimeOptions?: RuntimeRequestOptions): Promise<ApprovalResult>;
-    private buildApprovalDescriptor;
-}
-export {};

package/dist/internal/core/runtime-request-manager.d.ts

@@ -1,283 +0,0 @@
-import type { CanonClient } from './client.js';
-import type { SessionRule } from './approval-types.js';
-import type { RuntimeCardV1, RuntimeCardNativeMetadata, RuntimeInputAnswers, RuntimeInputChoice, RuntimeInputKind, RuntimeInputNativeMetadata, RuntimeInputQuestion } from './runtime-cards.js';
-/**
- * The five runtime request families. `contact` is non-interactive (no pending
- * node / no manager loop); the other four flow through {@link RuntimeRequestManager}.
- */
-export type RuntimeRequestKind = 'contact' | 'approval' | 'input' | 'plan' | 'card';
-export interface RuntimeRequestContext {
-    agentId: string;
-    ownerId: string;
-}
-/** Normalized outcome of a single consume poll. */
-export type RuntimeConsumeOutcome<Result> = {
-    state: 'pending';
-} | {
-    state: 'resolved';
-    result: Result;
-} | {
-    state: 'timeout';
-};
-/** Outcome message the host emits after a request settles (via `onOutcome`). */
-export interface RuntimeOutcomeMessage {
-    text: string;
-    metadata: Record<string, unknown>;
-}
-/**
- * Everything the descriptor's create step surfaced to the host, handed to
- * `onCreated`. Hosts that must sequence side effects on the server response
- * (turn blocks, streaming state, display-vs-poll control flow) read these
- * instead of re-deriving them.
- */
-export interface RuntimeCreateResult {
-    requestId: string;
-    messageId?: string;
-    /** Card family: whether the created card is interactive (a response is pending). */
-    interactive?: boolean;
-    expiresAt?: number;
-}
-/**
- * How the built-in input/card descriptors pick `responseUserId` when the payload
- * does not set it explicitly. An explicit `payload.responseUserId` always wins.
- * - `'owner'` — fall back to `ctx.ownerId` (omit when that is empty).
- * - `'infer'` — omit, so the backend targets the owner if present else the sole
- *   other member (correct for agent→user DMs where the owner is not a member).
- */
-export type ResponderPolicy = 'owner' | 'infer';
-export interface RuntimeRequestOptions {
-    /** Caller-chosen request id. When omitted the descriptor generates one. */
-    requestId?: string;
-    /** Absolute deadline (epoch ms). Overrides `timeoutMs`. */
-    expiresAt?: number;
-    timeoutMs?: number;
-    pollMs?: number;
-    signal?: AbortSignal;
-    /** Responder fallback for the built-in input/card create (see {@link ResponderPolicy}). */
-    responderPolicy?: ResponderPolicy;
-    /** Host side effects immediately after the server request is created (turn block, typing). */
-    onCreated?: (created: RuntimeCreateResult) => void | Promise<void>;
-    /** Host emits the durable outcome message after the request settles. */
-    onOutcome?: (outcome: RuntimeOutcomeMessage) => void | Promise<void>;
-}
-/** Error used to reject an in-flight request that is explicitly cancelled. */
-export declare class RuntimeRequestCancelledError extends Error {
-    constructor(message?: string);
-}
-export interface RuntimeRequestCallInput<Payload, State> {
-    client: CanonClient;
-    ctx: RuntimeRequestContext;
-    conversationId: string;
-    requestId: string;
-    payload: Payload;
-    /** Resolved absolute deadline (epoch ms). */
-    expiresAt: number;
-    state: State | undefined;
-}
-export interface RuntimeRequestPreflightInput<Payload> {
-    client: CanonClient;
-    ctx: RuntimeRequestContext;
-    conversationId: string;
-    payload: Payload;
-    options: RuntimeRequestOptions;
-}
-export interface RuntimeRequestPushInput {
-    conversationId: string;
-    message: {
-        senderId: string;
-        metadata?: Record<string, unknown>;
-    };
-    ctx: RuntimeRequestContext;
-}
-export interface RuntimeRequestPushMatch {
-    requestId: string;
-}
-/**
- * Everything that varies per request family. The engine ({@link RuntimeRequestManager})
- * owns the pending map, timers, poll/notify/abort loop and cancellation; the
- * descriptor supplies only the family-specific pieces.
- */
-export interface KindDescriptor<Payload = unknown, Result = unknown, State = unknown> {
-    readonly kind: RuntimeRequestKind;
-    /** Fresh request id when the caller supplies none. */
-    generateId(payload: Payload): string;
-    /** Deadline for this request (epoch ms). Falls back to options / default when omitted. */
-    resolveExpiry?(input: {
-        payload: Payload;
-        options: RuntimeRequestOptions;
-    }): number | undefined;
-    /** Poll cadence (ms). Defaults to the manager default. */
-    pollMs?(payload: Payload): number;
-    /**
-     * Optional immediate resolution BEFORE any server request is created (e.g. the
-     * approval session-rule fast path). Returning a result skips create + poll.
-     */
-    preflight?(input: RuntimeRequestPreflightInput<Payload>): Result | null;
-    /**
-     * Create the server-side request; returns the effective id + optional per-request
-     * state, plus any create-response fields the host needs back (surfaced via
-     * {@link RuntimeCreateResult} to `onCreated`).
-     */
-    create(input: RuntimeRequestCallInput<Payload, State> & {
-        options: RuntimeRequestOptions;
-    }): Promise<{
-        requestId: string;
-        expiresAt?: number;
-        state?: State;
-        messageId?: string;
-        interactive?: boolean;
-    }>;
-    /** Poll the server once and interpret the response. */
-    consume(input: RuntimeRequestCallInput<Payload, State>): Promise<RuntimeConsumeOutcome<Result>>;
-    /** Best-effort cancellation (abort / explicit cancel / dispose). */
-    cancel?(input: RuntimeRequestCallInput<Payload, State>): Promise<void>;
-    /** Result produced when the local deadline fires. */
-    timeoutResult(input: RuntimeRequestCallInput<Payload, State>): Result;
-    /**
-     * Finalization side effects + optional result override. Runs on `replied` /
-     * `timeout` (never `aborted`). Approval uses this to store the accepted session
-     * rule and emit its own outcome messages; returning a result lets it narrow the
-     * accepted rule into the returned value.
-     */
-    finalize?(input: RuntimeRequestCallInput<Payload, State> & {
-        result: Result;
-        reason: 'replied' | 'timeout';
-    }): Result | void;
-    /** Outcome message for the host to emit via `onOutcome` (input/card families). */
-    buildOutcome?(input: RuntimeRequestCallInput<Payload, State> & {
-        result: Result;
-        reason: 'replied' | 'timeout';
-    }): RuntimeOutcomeMessage | null;
-    /** Map an inbound push message to a pending request that should poll now. */
-    matchPush?(input: RuntimeRequestPushInput): RuntimeRequestPushMatch | null;
-}
-/**
- * Platform-agnostic engine for Canon's interactive runtime requests.
- *
- * Generalizes the former `ApprovalManager`: it owns the pending map, deadline
- * timers, the poll-with-abort loop that races an inbound push wakeup, and
- * cancellation — all keyed by {@link KindDescriptor}. Approval, runtime input,
- * runtime card, and plan families register over the same primitive; the former
- * hand-written await-loops collapse into `request()`.
- *
- * Session-rule storage lives here because the approval descriptor's preflight /
- * finalize read and write it; other families ignore it.
- */
-export declare class RuntimeRequestManager {
-    protected client: CanonClient;
-    protected ctx: RuntimeRequestContext;
-    private descriptors;
-    private pending;
-    private rules;
-    constructor(client: CanonClient, ctx: RuntimeRequestContext);
-    /** Register (or override) the descriptor for a kind. */
-    register<Payload, Result, State>(kind: RuntimeRequestKind, descriptor: KindDescriptor<Payload, Result, State>): void;
-    /** Built-in input, card, and plan descriptors. Subclasses add approval policy. */
-    protected registerBuiltins(): void;
-    get pendingCount(): number;
-    /**
-     * Run one interactive runtime request end to end:
-     * preflight → create → onCreated → register pending → poll (racing push wakeup
-     * and abort) → post-deadline consume → finalize → onOutcome → resolve.
-     */
-    request<Payload, Result, State = unknown>(kind: RuntimeRequestKind, conversationId: string, payload: Payload, options?: RuntimeRequestOptions): Promise<Result>;
-    /** Push short-circuit: wake the pending request's poll to consume immediately. */
-    notify(kind: RuntimeRequestKind, conversationId: string, requestId: string): void;
-    /**
-     * Feed an inbound message to the manager. Returns true when a matching pending
-     * request was woken to consume canonical state. Receipt metadata never settles
-     * the request directly. Fails closed on unknown / mismatched ids.
-     */
-    handleMessage(conversationId: string, message: {
-        senderId: string;
-        metadata?: Record<string, unknown>;
-    }): boolean;
-    /** Cancel a specific pending request (rejects its promise, best-effort server cancel). */
-    cancel(kind: RuntimeRequestKind, conversationId: string, requestId: string): Promise<void>;
-    checkSessionRules(toolName: string, conversationId?: string): SessionRule | null;
-    addSessionRule(conversationId: string, rule: SessionRule): void;
-    getSessionRules(): SessionRule[];
-    clearSessionRules(): void;
-    dispose(): void;
-    protected pruneExpiredRules(): void;
-    /** Sleep that resolves on timeout, on `notify()` wakeup, or when the request settles. */
-    private sleep;
-}
-/** Interactive runtime input (`AskUserQuestion`, secret prompts, choices). */
-export interface RuntimeInputRequestPayload {
-    kind: RuntimeInputKind;
-    title?: string;
-    prompt?: string;
-    choices?: RuntimeInputChoice[];
-    questions?: RuntimeInputQuestion[];
-    secretName?: string;
-    native?: RuntimeInputNativeMetadata;
-    sensitive?: boolean;
-    responseUserId?: string;
-    turnId?: string;
-}
-export type RuntimeInputRequestResult = {
-    status: 'submitted';
-    inputId: string;
-    value: string;
-    answers?: RuntimeInputAnswers;
-} | {
-    status: 'cancelled';
-    inputId: string;
-} | {
-    status: 'timeout';
-    inputId: string;
-};
-export declare const runtimeInputDescriptor: KindDescriptor<RuntimeInputRequestPayload, RuntimeInputRequestResult>;
-/** Interactive runtime card (canon.card.v1 with an actions block). */
-export interface RuntimeCardRequestPayload {
-    card: RuntimeCardV1;
-    responseUserId?: string;
-    runtimeId?: string;
-    turnId?: string;
-    native?: RuntimeCardNativeMetadata;
-}
-export type RuntimeCardRequestResult = {
-    status: 'submitted';
-    cardId: string;
-    actionId?: string;
-    values?: Record<string, unknown>;
-    respondedBy?: string;
-} | {
-    status: 'cancelled';
-    cardId: string;
-    respondedBy?: string;
-} | {
-    status: 'timeout';
-    cardId: string;
-};
-export declare const runtimeCardDescriptor: KindDescriptor<RuntimeCardRequestPayload, RuntimeCardRequestResult>;
-/** Blocking plan review produced by coding runtimes. */
-export interface RuntimePlanRequestPayload {
-    title?: string;
-    summary?: string;
-    body?: string;
-    allowedPrompts?: ReadonlyArray<{
-        tool: string;
-        prompt: string;
-    }>;
-    responseUserId?: string;
-    turnId?: string;
-}
-export type RuntimePlanRequestResult = {
-    status: 'approve' | 'revise' | 'reject';
-    planId: string;
-    feedback?: string;
-    grantedPrompts?: Array<{
-        tool: string;
-        prompt: string;
-    }>;
-    receiptId?: string;
-} | {
-    status: 'cancelled';
-    planId: string;
-} | {
-    status: 'timeout';
-    planId: string;
-};
-export declare const runtimePlanDescriptor: KindDescriptor<RuntimePlanRequestPayload, RuntimePlanRequestResult>;

package/dist/internal/core/turn-verbosity.d.ts

@@ -1,79 +0,0 @@
-/**
- * Turn verbosity — how much of a turn's middle the reader sees.
- *
- * `quiet` = the thinking indicator and the final message only: no `/streaming`
- * narration and no runtime-generated per-tool-call step output. Emission the
- * DEVELOPER asks for explicitly is not narration and survives — owner ruling
- * D1: `replyProgress(text, { durable: true })` keeps its durable send, and only
- * the implicit `/streaming` half is gated. Interaction requests and their
- * `control` outcome receipts are real interactions, not steps, and are
- * untouched in both modes; the duplicate trail rows that summarize them go with
- * the trail (D4).
- *
- * Owner ruling 5, 2026-07-31 (docs/history/group-behavior-2026-08-01.md): configured
- * by the AGENT DEVELOPER per host/SDK, never by Canon and never per
- * conversation by users. ONE resolver so five integrations cannot disagree.
- *
- * This lives in @canonmsg/core rather than @canonmsg/backend-contracts because
- * quiet mode has no server participant: it is emission control at the agent
- * side. Nothing on the server reads it, no verb carries it, and clients need
- * no change — they simply have nothing to render.
- *
- * Notes for the runtimes that consume this (the guards are per-integration):
- * - Suppress by CALL SITE, never by `turnSemantics === 'progress'` (D5): the
- *   leading parts of a chunked final carry that semantic and are answer body.
- * - A quiet turn still clears `/streaming` at turn open (a surviving node from
- *   an earlier turn would otherwise strand a stale bubble), still writes
- *   `/turn-state`, and still writes `/typing`. Quiet removes the narration,
- *   not the fact that the agent is working.
- */
-/** The resolved mode a turn runs in. Named `turnVerbosity`, never `verbosity` —
- * `runtime.verbosity.set` is a different, user-facing primitive. */
-export type TurnVerbosity = 'verbose' | 'quiet';
-/** What a developer may write in config. `'auto'` === unset. */
-export type TurnVerbosityConfig = TurnVerbosity | 'auto';
-/**
- * A direct chat is `'direct'`; the type is `'unknown'` when the conversation
- * fetch failed (host-runtime.ts HostInboundParticipantContext).
- */
-export type TurnVerbosityConversationType = 'direct' | 'group' | 'unknown';
-/** The per-conversation-type defaults. */
-export declare const DEFAULT_TURN_VERBOSITY_BY_CONVERSATION_TYPE: {
-    readonly direct: "verbose";
-    readonly group: "quiet";
-    readonly unknown: "verbose";
-};
-/**
- * Folds every spelling a runtime might hand us onto the three keys the
- * defaults map has. Accepts a raw string because the value arrives from
- * provenance or a conversation fetch.
- */
-export declare function normalizeTurnVerbosityConversationType(value: string | null | undefined): 'direct' | 'group' | 'unknown';
-/**
- * An explicit `'verbose'`/`'quiet'` wins outright; `'auto'`, unset and any
- * unrecognized value fall through to the per-conversation-type default.
- *
- * `configured` goes through `parseTurnVerbosityConfig` on the way in, so a
- * caller handing over a raw config value gets the same answer as one that
- * pre-parsed. That matters because the escape hatch is the whole point of the
- * field: an operator who writes `Verbose` in a group is opting OUT of quiet,
- * and a byte-exact comparison would drop that back onto the group default —
- * i.e. into silence — with nothing anywhere to warn about it.
- */
-export declare function resolveTurnVerbosity(input: {
-    configured?: TurnVerbosityConfig | null;
-    conversationType?: TurnVerbosityConversationType | null;
-}): TurnVerbosity;
-/**
- * Shared parser for CLI flags, env vars and config files, so four TS runtimes
- * agree on what a developer typed. Case-insensitive and trimmed.
- *
- * `null` means absent OR unrecognized — `''`, whitespace, `null` and `undefined`
- * land there alongside a genuine typo. A host that warns on `null` must first
- * check the raw input was a non-empty string, or a declared-but-empty
- * `CANON_TURN_VERBOSITY=` (routine in launchd plists, Docker `ENV` and `.env`
- * files) gets reported as a mistake the operator never made. Absent stays `null`
- * rather than collapsing to `'auto'` so that the usual flag-then-env fallback,
- * `parse(flag) ?? parse(env)`, keeps working.
- */
-export declare function parseTurnVerbosityConfig(raw: string | null | undefined): TurnVerbosityConfig | null;