@canonmsg/agent-sdk 11.2.0 → 12.0.0

package/dist/runner/types.d.ts

@@ -0,0 +1,168 @@
+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';
+    /** 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;
+}
+/** `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;
+    /** 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 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.
+ */
+{
+    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;
+    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;
+    };
+    /** 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>;
+}
+/** 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;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@canonmsg/agent-sdk",
-  "version": "11.2.0",
+  "version": "12.0.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.3.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"

package/dist/attached-session.d.ts

@@ -1,58 +0,0 @@
-import { CanonClient, CanonStream, type AttachedNativeSessionAdapter, type AttachedSessionBinding, type AttachedSessionPublisher, type AttachedSessionState, type AttachedSessionStore, type ResolvedAgent, type RuntimeStatePublisher } from '@canonmsg/core';
-export type CanonAttachedSessionConnection = Pick<ResolvedAgent, 'apiKey' | 'environmentId' | 'baseUrl' | 'streamUrl' | 'rtdbUrl' | 'firebaseApiKey' | 'clientType'> & {
-    agentId: string;
-};
-export interface CanonAttachedSessionStatus {
-    status: 'connecting' | 'connected' | 'disconnected' | 'native' | 'accepted' | 'blocked' | 'stopped';
-    reason?: string;
-    messageId?: string;
-    nativeState?: AttachedSessionState;
-    /** REST history is an observation, not fresh permission to execute. */
-    pendingMessageIds?: string[];
-}
-export interface CanonAttachedSessionOptions {
-    connection: CanonAttachedSessionConnection;
-    binding: AttachedSessionBinding;
-    native: AttachedNativeSessionAdapter;
-    /** Exclusive durable store; the Core attachment closes it on stop/failure. */
-    store: AttachedSessionStore;
-    reconcileIntervalMs?: number;
-    onStatus?: (status: CanonAttachedSessionStatus) => void;
-    onError?: (error: unknown, operation: string) => void;
-    /** An account coordinator may supply its authenticated transport for several rooms. */
-    transport?: CanonAttachedSessionTransport;
-}
-export type CanonAttachedSessionStreamHandler = ConstructorParameters<typeof CanonStream>[0]['handler'];
-/** Account resources stay with the coordinator; an individual room never closes them. */
-export interface CanonAttachedSessionTransport {
-    agentId: string;
-    environmentId: string;
-    client: CanonClient;
-    publisher: RuntimeStatePublisher;
-    subscribe(handler: CanonAttachedSessionStreamHandler): () => void;
-    hasPendingInteraction?(conversationId: string): boolean;
-    /** A prepared observer can wait for its owner's durable setup acknowledgement. */
-    isRouteActive?(conversationId: string): boolean;
-}
-export interface CanonAttachedSession {
-    /** Resolves after native attachment and Canon transport startup, not stream termination. */
-    start(): Promise<void>;
-    /** Terminal: closes this attachment; the native session keeps running. */
-    stop(): Promise<void>;
-    getState(): AttachedSessionState;
-    /** Republish an external native interaction's waiting state. */
-    refreshRuntimeState(): void;
-}
-/**
- * Connect one existing native session to one existing Canon conversation.
- * This is account-level participation, not a second group member. The caller
- * must hold exclusive account and native-session ownership so no competing
- * runtime writes this account's live state or republishes the native thread.
- */
-export declare function createCanonAttachedSession(options: CanonAttachedSessionOptions): CanonAttachedSession;
-/**
- * Observed native turns may combine local and Canon input. They are proactive
- * agent transcript publications, never replies authorized by a particular
- * Canon input. Core persists these immutable parts before calling send.
- */
-export declare function createCanonAttachedSessionPublisher(client: Pick<CanonClient, 'sendProactiveMessage'>, binding: AttachedSessionBinding): AttachedSessionPublisher;