@canonmsg/core 0.12.0 → 0.14.0

package/dist/registration.js

@@ -10,7 +10,12 @@ const POLL_TIMEOUT_MS = 5 * 60 * 1000; // 5 minutes
  * 3. On approval, returns the API key
  */
 export async function registerAndWaitForApproval(input, callbacks) {
-    const { requestId } = await CanonClient.register(input.baseUrl, {
+    const submitted = await submitRegistrationRequest(input);
+    callbacks?.onSubmitted?.(submitted.requestId, submitted.pollToken);
+    return waitForRegistrationApproval(input.baseUrl, submitted.requestId, submitted.pollToken, callbacks);
+}
+export async function submitRegistrationRequest(input) {
+    return CanonClient.register(input.baseUrl, {
         name: input.name,
         description: input.description,
         ownerPhone: input.ownerPhone,
@@ -18,29 +23,47 @@ export async function registerAndWaitForApproval(input, callbacks) {
         avatarUrl: input.avatarUrl,
         clientType: input.clientType,
         requestedAgentId: input.requestedAgentId,
+        localRegistrationId: input.localRegistrationId,
     });
-    callbacks?.onSubmitted?.(requestId);
+}
+export async function waitForRegistrationApproval(baseUrl, requestId, pollToken, callbacks) {
     const deadline = Date.now() + POLL_TIMEOUT_MS;
     while (Date.now() < deadline) {
         await sleep(POLL_INTERVAL_MS);
-        const result = await CanonClient.checkStatus(input.baseUrl, requestId);
+        const result = await CanonClient.checkStatus(baseUrl, requestId, pollToken);
         callbacks?.onPollUpdate?.(result);
         if (result.status === 'approved') {
+            if (!result.apiKey) {
+                return {
+                    status: 'timeout',
+                    requestId,
+                    pollToken,
+                    agentId: result.agentId,
+                    agentName: result.agentName,
+                };
+            }
             return {
                 status: 'approved',
                 apiKey: result.apiKey,
                 agentId: result.agentId,
                 agentName: result.agentName,
+                requestId,
+                pollToken,
             };
         }
         if (result.status === 'rejected') {
             return {
                 status: 'rejected',
                 agentName: result.agentName,
+                requestId,
+                pollToken,
             };
         }
     }
-    return { status: 'timeout' };
+    return { status: 'timeout', requestId, pollToken };
+}
+export async function ackRegistrationApproval(baseUrl, requestId, pollToken) {
+    await CanonClient.ackRegistrationStatus(baseUrl, requestId, pollToken);
 }
 function sleep(ms) {
     return new Promise((resolve) => setTimeout(resolve, ms));

package/dist/rtdb-rest.d.ts

@@ -114,7 +114,7 @@ interface RTDBAuthOptions {
     rtdbUrl?: string;
     firebaseApiKey?: string;
 }
-interface RTDBClientHandle {
+export interface RTDBClientHandle {
     read(path: string): Promise<unknown>;
     write(path: string, data: unknown): Promise<void>;
     patch(path: string, data: unknown): Promise<void>;

package/dist/runtime-descriptor.d.ts

@@ -0,0 +1,50 @@
+import type { ExecutionEnvironmentMode } from './execution-environment-mode.js';
+import { type AgentClientType, type CanonControlDescriptor, type CanonRuntimeActionDescriptor, type CanonRuntimeDescriptor, type CanonRuntimeStreamingMode, type CanonWorkspaceRootMetadata, type ModelOption, type PermissionModeOption, type WorkspaceOption } from './types.js';
+import type { HostAdmissionActionCapabilities } from './turn-protocol.js';
+export declare const CLAUDE_EFFORT_OPTIONS: readonly [{
+    readonly value: "low";
+    readonly label: "Low";
+}, {
+    readonly value: "medium";
+    readonly label: "Medium";
+}, {
+    readonly value: "high";
+    readonly label: "High";
+}];
+export declare const EXECUTION_MODE_CONTROL_OPTIONS: ReadonlyArray<{
+    value: ExecutionEnvironmentMode;
+    label: string;
+    description: string;
+}>;
+export declare function buildRuntimeWorkspaceControlOptions(workspaces: ReadonlyArray<WorkspaceOption>): ModelOption[];
+export declare function buildRuntimeExecutionModeOptions(modes: ReadonlyArray<ExecutionEnvironmentMode>): ModelOption[];
+export declare function buildRuntimeModelControl(input: {
+    models: ReadonlyArray<ModelOption>;
+    liveBehavior: 'immediate' | 'next_turn';
+    defaultValue?: string | null;
+}): CanonControlDescriptor;
+export declare function buildRuntimeWorkspaceControl(input: {
+    workspaces: ReadonlyArray<WorkspaceOption>;
+    workspaceRoots?: ReadonlyArray<CanonWorkspaceRootMetadata>;
+    label?: string;
+    defaultValue?: string | null;
+}): CanonControlDescriptor;
+export declare function buildRuntimeExecutionModeControl(executionModes: ReadonlyArray<ExecutionEnvironmentMode>): CanonControlDescriptor;
+export declare function buildRuntimePermissionModeControl(input: {
+    clientType: 'claude-code' | 'codex';
+    options: ReadonlyArray<PermissionModeOption>;
+    defaultValue?: string | null;
+}): CanonControlDescriptor;
+export declare function buildRuntimeEffortControl(): CanonControlDescriptor;
+export declare function buildFirstPartyCodingRuntimeDescriptor(input: {
+    clientType: Extract<AgentClientType, 'claude-code' | 'codex'>;
+    models: ReadonlyArray<ModelOption>;
+    workspaces: ReadonlyArray<WorkspaceOption>;
+    workspaceRoots?: ReadonlyArray<CanonWorkspaceRootMetadata>;
+    executionModes: ReadonlyArray<ExecutionEnvironmentMode>;
+    permissionModes?: ReadonlyArray<PermissionModeOption>;
+    defaultPermissionMode?: string | null;
+    actions?: ReadonlyArray<CanonRuntimeActionDescriptor>;
+    streamingTextMode: CanonRuntimeStreamingMode;
+    admissionActions?: HostAdmissionActionCapabilities;
+}): CanonRuntimeDescriptor;

package/dist/runtime-descriptor.js

@@ -0,0 +1,128 @@
+import { CLAUDE_PERMISSION_MODE_OPTIONS, } from './types.js';
+export const CLAUDE_EFFORT_OPTIONS = [
+    { value: 'low', label: 'Low' },
+    { value: 'medium', label: 'Medium' },
+    { value: 'high', label: 'High' },
+];
+export const EXECUTION_MODE_CONTROL_OPTIONS = [
+    {
+        value: 'worktree',
+        label: 'Isolated worktree',
+        description: 'Creates or reuses a per-conversation git worktree under ~/.canon/conversation-worktrees when the selected project is a git repo.',
+    },
+    {
+        value: 'locked',
+        label: 'Use shared project',
+        description: 'Runs directly in the selected project folder. Changes happen there.',
+    },
+];
+export function buildRuntimeWorkspaceControlOptions(workspaces) {
+    return workspaces.map((workspace) => ({
+        value: workspace.id,
+        label: workspace.label,
+        ...(workspace.description ? { description: workspace.description } : {}),
+        ...(workspace.workspaceRootId ? { workspaceRootId: workspace.workspaceRootId } : {}),
+        ...(workspace.workspaceRelativePath ? { workspaceRelativePath: workspace.workspaceRelativePath } : {}),
+        ...(workspace.source ? { source: workspace.source } : {}),
+    }));
+}
+export function buildRuntimeExecutionModeOptions(modes) {
+    return modes.map((mode) => {
+        const option = EXECUTION_MODE_CONTROL_OPTIONS.find((candidate) => candidate.value === mode);
+        return option
+            ? { ...option }
+            : { value: mode, label: mode, description: mode };
+    });
+}
+export function buildRuntimeModelControl(input) {
+    return {
+        id: 'model',
+        label: 'Model',
+        options: input.models,
+        defaultValue: input.defaultValue ?? input.models[0]?.value ?? null,
+        availability: 'setup_and_live',
+        liveBehavior: input.liveBehavior,
+        selectionPolicy: 'inherit',
+    };
+}
+export function buildRuntimeWorkspaceControl(input) {
+    return {
+        id: 'workspace',
+        label: input.label ?? 'Project',
+        options: buildRuntimeWorkspaceControlOptions(input.workspaces),
+        defaultValue: input.defaultValue ?? input.workspaces[0]?.id ?? null,
+        availability: 'setup',
+        liveBehavior: 'none',
+        selectionPolicy: 'inherit',
+        description: input.workspaceRoots?.length
+            ? 'Choose one of the projects discovered inside the approved local roots for this host.'
+            : 'Choose one of the local projects advertised by this host.',
+    };
+}
+export function buildRuntimeExecutionModeControl(executionModes) {
+    return {
+        id: 'executionMode',
+        label: 'Execution mode',
+        options: buildRuntimeExecutionModeOptions(executionModes),
+        defaultValue: null,
+        availability: 'setup',
+        liveBehavior: 'none',
+        selectionPolicy: 'required_explicit',
+    };
+}
+export function buildRuntimePermissionModeControl(input) {
+    const isCodex = input.clientType === 'codex';
+    return {
+        id: 'permissionMode',
+        label: isCodex ? 'Execution policy' : 'Permission mode',
+        options: input.options,
+        defaultValue: input.defaultValue ?? null,
+        availability: isCodex ? 'setup' : 'setup_and_live',
+        liveBehavior: isCodex ? 'none' : 'immediate',
+        selectionPolicy: 'inherit',
+    };
+}
+export function buildRuntimeEffortControl() {
+    return {
+        id: 'effort',
+        label: 'Thinking level',
+        options: [...CLAUDE_EFFORT_OPTIONS],
+        defaultValue: 'medium',
+        availability: 'setup_and_live',
+        liveBehavior: 'immediate',
+        selectionPolicy: 'inherit',
+    };
+}
+export function buildFirstPartyCodingRuntimeDescriptor(input) {
+    const permissionModes = input.permissionModes
+        ?? (input.clientType === 'claude-code' ? CLAUDE_PERMISSION_MODE_OPTIONS : []);
+    return {
+        coreControls: [
+            buildRuntimeModelControl({
+                models: input.models,
+                liveBehavior: input.clientType === 'codex' ? 'next_turn' : 'immediate',
+            }),
+            buildRuntimeWorkspaceControl({
+                workspaces: input.workspaces,
+                workspaceRoots: input.workspaceRoots,
+            }),
+            buildRuntimeExecutionModeControl(input.executionModes),
+        ],
+        runtimeControls: [
+            ...(permissionModes.length > 0
+                ? [buildRuntimePermissionModeControl({
+                        clientType: input.clientType,
+                        options: permissionModes,
+                        defaultValue: input.defaultPermissionMode
+                            ?? (input.clientType === 'claude-code' ? 'default' : null),
+                    })]
+                : []),
+            ...(input.clientType === 'claude-code' ? [buildRuntimeEffortControl()] : []),
+        ],
+        actions: input.actions,
+        workspaceRoots: input.workspaceRoots,
+        supportsInterrupt: true,
+        streamingTextMode: input.streamingTextMode,
+        admissionActions: input.admissionActions,
+    };
+}

package/dist/runtime-state-publisher.d.ts

@@ -0,0 +1,31 @@
+import type { AgentClientType, AgentRuntime, RuntimeInfoPayload } from './types.js';
+import { type AgentSessionSnapshotPatch, type RTDBClientHandle, type SessionStatePayload, type TurnStatePayload } from './rtdb-rest.js';
+export interface RuntimeStatePublisherOptions {
+    agentId: string;
+    clientType: AgentClientType;
+    hostMode: boolean;
+    rtdb?: RTDBClientHandle;
+}
+export interface RuntimeStreamingPayload {
+    text: string;
+    status: 'thinking' | 'streaming' | 'tool';
+    messageId?: string;
+    updatedAt?: number | {
+        '.sv': 'timestamp';
+    };
+}
+export interface RuntimeStatePublisher {
+    publishAgentRuntime(runtime: AgentRuntime): Promise<void>;
+    clearAgentRuntime(): Promise<void>;
+    writeSessionState(conversationId: string, state: Omit<SessionStatePayload, 'updatedAt'>): Promise<void>;
+    clearSessionState(conversationId: string): Promise<void>;
+    writeTurnState(conversationId: string, state: Omit<TurnStatePayload, 'updatedAt'>): Promise<void>;
+    clearTurnState(conversationId: string): Promise<void>;
+    patchAgentSessionSnapshot(conversationId: string, snapshot: Omit<AgentSessionSnapshotPatch, 'updatedAt'>): Promise<void>;
+    writeRuntimeInfo(conversationId: string, payload: Omit<RuntimeInfoPayload, 'updatedAt'>): Promise<void>;
+    patchRuntimeInfo(conversationId: string, payload: Partial<Omit<RuntimeInfoPayload, 'updatedAt'>>): Promise<void>;
+    clearRuntimeInfo(conversationId: string): Promise<void>;
+    writeStreaming(conversationId: string, payload: RuntimeStreamingPayload): Promise<void>;
+    clearStreaming(conversationId: string): Promise<void>;
+}
+export declare function createRuntimeStatePublisher(options: RuntimeStatePublisherOptions): RuntimeStatePublisher;

package/dist/runtime-state-publisher.js

@@ -0,0 +1,68 @@
+import { clearRuntimeInfo, clearSessionState, clearTurnState, patchAgentSessionSnapshot, patchRuntimeInfo, rtdbWrite, writeRuntimeInfo, writeSessionState, writeTurnState, } from './rtdb-rest.js';
+const SERVER_TIMESTAMP = { '.sv': 'timestamp' };
+export function createRuntimeStatePublisher(options) {
+    const { agentId, clientType, hostMode, rtdb } = options;
+    const writePath = (path, data) => (rtdb ? rtdb.write(path, data) : rtdbWrite(path, data));
+    return {
+        async publishAgentRuntime(runtime) {
+            await writePath(`/agent-runtime/${agentId}`, {
+                clientType,
+                hostMode,
+                ...runtime,
+                updatedAt: SERVER_TIMESTAMP,
+            });
+        },
+        async clearAgentRuntime() {
+            await writePath(`/agent-runtime/${agentId}`, null);
+        },
+        async writeSessionState(conversationId, state) {
+            await (rtdb
+                ? rtdb.writeSessionState(conversationId, agentId, state)
+                : writeSessionState(conversationId, agentId, state));
+        },
+        async clearSessionState(conversationId) {
+            await (rtdb
+                ? rtdb.clearSessionState(conversationId, agentId)
+                : clearSessionState(conversationId, agentId));
+        },
+        async writeTurnState(conversationId, state) {
+            await (rtdb
+                ? rtdb.writeTurnState(conversationId, agentId, state)
+                : writeTurnState(conversationId, agentId, state));
+        },
+        async clearTurnState(conversationId) {
+            await (rtdb
+                ? rtdb.clearTurnState(conversationId, agentId)
+                : clearTurnState(conversationId, agentId));
+        },
+        async patchAgentSessionSnapshot(conversationId, snapshot) {
+            await (rtdb
+                ? rtdb.patchAgentSessionSnapshot(conversationId, agentId, snapshot)
+                : patchAgentSessionSnapshot(conversationId, agentId, snapshot));
+        },
+        async writeRuntimeInfo(conversationId, payload) {
+            await (rtdb
+                ? rtdb.writeRuntimeInfo(conversationId, agentId, payload)
+                : writeRuntimeInfo(conversationId, agentId, payload));
+        },
+        async patchRuntimeInfo(conversationId, payload) {
+            await (rtdb
+                ? rtdb.patchRuntimeInfo(conversationId, agentId, payload)
+                : patchRuntimeInfo(conversationId, agentId, payload));
+        },
+        async clearRuntimeInfo(conversationId) {
+            await (rtdb
+                ? rtdb.clearRuntimeInfo(conversationId, agentId)
+                : clearRuntimeInfo(conversationId, agentId));
+        },
+        async writeStreaming(conversationId, payload) {
+            await writePath(`/streaming/${conversationId}/${agentId}`, {
+                ...payload,
+                updatedAt: payload.updatedAt ?? SERVER_TIMESTAMP,
+            });
+        },
+        async clearStreaming(conversationId) {
+            await writePath(`/streaming/${conversationId}/${agentId}`, null);
+        },
+    };
+}

package/dist/types.d.ts

@@ -605,15 +605,18 @@ export interface RegistrationInput {
     baseUrl?: string;
     clientType?: AgentClientType;
     requestedAgentId?: string;
+    localRegistrationId?: string;
 }
 export interface RegistrationResult {
     status: 'approved' | 'rejected' | 'timeout';
     apiKey?: string;
     agentId?: string;
     agentName?: string;
+    requestId?: string;
+    pollToken?: string;
 }
 export interface RegistrationStatus {
-    status: 'pending' | 'approved' | 'rejected';
+    status: 'pending' | 'approving' | 'approved' | 'rejected';
     agentName: string;
     agentId?: string;
     apiKey?: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@canonmsg/core",
-  "version": "0.12.0",
+  "version": "0.14.0",
   "description": "Canon core — shared types, REST client, SSE stream, and registration for Canon messaging",
   "type": "module",
   "main": "dist/index.js",