@canonmsg/agent-sdk 10.2.1 → 10.3.0

package/README.md

@@ -54,7 +54,7 @@ Runtime heartbeats and Firebase token refresh come from Core, using the same mac
 | `autoMarkRead` | `boolean` | `true` | Advance Canon's read cursor after successful handler completion. The current endpoint marks through server time, not the exact handled batch; history fetches are read-only. |
 | `sessions` | `SessionOptions` | `undefined` | Enable per-conversation session queues and persistent metadata |
 | `clientType` | `AgentClientType` | `'generic'` | Agent runtime label used for Canon capability detection |
-| `runtimeDescriptor` | `CanonRuntimeDescriptor` | minimal generic descriptor | Optional setup/live controls and runtime capability metadata for Canon UI |
+| `runtimeDescriptor` | `CanonRuntimeDescriptor` | minimal generic descriptor | Supported live actions and runtime capability metadata for Canon UI |
 | `runtimeControls` | `RuntimeControlHandlers` | `undefined` | Optional `onInterrupt` / `onStopAndDrop` / `onNewSession` handlers for Canon working-state controls |
 | `runtimeControlSurface` | `'agent' \| 'host'` | `'agent'` | Runtime publishing surface. Use `host` when this SDK agent owns live runtime controls. |
 | `runtimePrimitives` | `RuntimePrimitiveHandlers` | `undefined` | Optional typed primitive command handlers for descriptor-backed runtime commands |
@@ -63,49 +63,7 @@ Runtime heartbeats and Firebase token refresh come from Core, using the same mac
 
 ### Optional runtime controls
 
-Generic SDK agents publish no setup controls by default. If your SDK runtime has local workspace access, you can opt in by publishing a descriptor with explicit project choices:
-
-```typescript
-const agent = new CanonAgent({
-  apiKey: process.env.CANON_API_KEY!,
-  environmentId: process.env.CANON_ENVIRONMENT_ID!,
-  runtimeDescriptor: {
-    coreControls: [
-      {
-        id: 'workspace',
-        label: 'Project',
-        options: [
-          {
-            value: 'workspace-canon',
-            label: 'canon',
-            description: 'dev/canon',
-            workspaceRootId: 'dev',
-            workspaceRelativePath: 'canon',
-            source: 'discovered',
-          },
-          {
-            value: 'workspace-yumyumv2',
-            label: 'yumyumv2',
-            description: 'dev/yumyumv2',
-            workspaceRootId: 'dev',
-            workspaceRelativePath: 'yumyumv2',
-            source: 'discovered',
-          },
-        ],
-        defaultValue: 'workspace-canon',
-        availability: 'setup',
-        liveBehavior: 'none',
-        selectionPolicy: 'inherit',
-        description: 'Choose one of the local projects this SDK host is configured to use.',
-      },
-    ],
-    runtimeControls: [],
-    workspaceRoots: [
-      { id: 'dev', label: '~/dev' },
-    ],
-  },
-});
-```
+Runtime descriptors describe supported live actions and status. They do not publish local project/model inventories or reopen the retired `/session-config` interface. Native work-session setup uses the owner-private workflow below.
 
 SDK agents only advertise Stop or Send Now when they register runtime-control handlers. Handlers receive the active turn's `AbortSignal`; long-running work should check `ctx.abortSignal.aborted` or pass the signal into cancellable APIs.
 
@@ -131,25 +89,21 @@ agent.on('message', async ({ messages, replyFinal, abortSignal }) => {
 });
 ```
 
-The descriptor only drives Canon UI and validation. Your SDK agent is still responsible for reading session config and safely mapping selected values to local directories.
-
-Node SDK builders can reuse `buildConfiguredWorkspaceOptionsWithRoots` from `@canonmsg/core` to produce the same stable project IDs and root metadata used by the first-party Claude Code and Codex hosts.
-
-Current rules of thumb:
-
-- Canon does not infer real runtime support from `clientType`; if you do not publish a descriptor, Canon should behave as a mostly status-only generic agent surface.
-- `availability` controls where a setting appears:
-  - `setup`: session creation only
-  - `live`: live strip only
-  - `setup_and_live`: both surfaces
-- `liveBehavior` controls how truthful live editing should be:
-  - `immediate`: Canon may show a pending state until the runtime snapshot reflects the applied value
-  - `next_turn`: Canon may let the user queue the change, but should label it as applying on the next turn
-  - `none`: Canon never exposes it as live-editable
-- `selectionPolicy: 'required_explicit'` means Canon should require the user to make a choice instead of silently inheriting a default
-- `workspaceRoots` and `writableRoots` document allowed roots and let Canon group project choices. Canon still stores the selected concrete `workspaceId`; it does not send arbitrary root-relative paths to generic SDK agents.
-- Publishing a descriptor does not automatically make your SDK agent enforce those controls. If you advertise model, workspace, execution mode, or runtime-native controls, your runtime must actually read and apply the stored config.
-- Message handlers receive `ctx.provenance`, a Canon-computed sender/conversation context for the latest inbound message in the batch. Use it when your runtime wants owner-only tools, group mention policy, or self-context-aware behavior; Canon does not impose a sandbox on SDK agents.
+Canon does not infer support from `clientType`. Advertise only actions your runtime implements. Message handlers receive Canon-computed `ctx.provenance`; use it to enforce your runtime's owner and group policies.
+
+### Native work sessions
+
+Use `createCanonWorkSessionHost` when Canon should share actual sessions from another runtime. Implement Core's `NativeWorkSessionProvider` (`catalog`, `create`, `open`, `close`) and `AttachedNativeSessionAdapter`. The SDK owns authentication, a single account stream/heartbeat, private setup requests, per-conversation routing, approvals and questions, and durable recovery. Codex is one provider of this API.
+
+The host requires a stable `hostId`, a durable `createFileWorkSessionHostStore`, a per-room attachment store, and an exclusive native-session lock. Its `connection` identifies the Canon account and environment. `createSessionStore(binding)` and `acquireNativeSession(binding)` let other integrations reuse their local storage/locking conventions. Start the host once per account; it can serve many conversations.
+
+The owner sees only choices advertised by the local provider. Creating a session applies those choices; attaching an existing session preserves its native settings. Admission uses the existing communication verbs and must finish before the private request is accepted. Each account has one session per Canon conversation. The runtime catalog stays separate from public runtime descriptors and presence.
+
+The host persists creation intent before native work and the exact returned native ID before attachment. A replayed claim never creates another session. Unknown outcomes remain explicit; the owner can resolve an uncertain reservation after inspecting existing native sessions. Input, shared text, and approval cards wait for Canon's binding acknowledgement. Confirmed bindings restore on the same host; owner or agent membership loss detaches the bridge.
+
+Native approval/input interactions use the existing Core request manager, exact owner identity, stable IDs and deadlines, and durable results. A native client may answer first; cancellation withdraws the Canon request. Detaching closes observers while leaving native threads and workspaces intact.
+
+See the [Codex workflow](../codex-plugin/README.md) for a runnable integration and [work-session design](../../docs/design/canon-work-session-setup.md) for boundaries and recovery behavior.
 
 ### Runtime primitives
 

package/dist/attached-session.d.ts

@@ -0,0 +1,58 @@
+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;