@canonmsg/agent-sdk 10.2.1 → 10.4.0

package/dist/work-session-interactions.js

@@ -0,0 +1,173 @@
+import { createHash } from 'node:crypto';
+const INTERACTION_TIMEOUT_MS = 5 * 60_000;
+const cancelled = () => ({ kind: 'cancelled' });
+/** Object property order does not change a request's content identity. */
+function canonical(value) {
+    if (value === null || typeof value !== 'object') {
+        const result = JSON.stringify(value);
+        if (result === undefined)
+            throw new Error('Unsupported native request value');
+        return result;
+    }
+    if (Array.isArray(value))
+        return `[${value.map(canonical).join(',')}]`;
+    return `{${Object.entries(value).filter(([, entry]) => entry !== undefined)
+        .sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0)
+        .map(([key, entry]) => `${JSON.stringify(key)}:${canonical(entry)}`).join(',')}}`;
+}
+function digest(value) { return createHash('sha256').update(canonical(value)).digest('hex'); }
+function validAnswers(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value)
+        && Object.values(value).every((entry) => entry !== null && typeof entry === 'object'
+            && Array.isArray(entry.answers)
+            && entry.answers.every((answer) => typeof answer === 'string'));
+}
+function validateResult(request, result) {
+    if (result?.kind === 'cancelled')
+        return cancelled();
+    if (request.kind === 'approval' && result?.kind === 'approval' && ['allow', 'deny'].includes(result.decision))
+        return result;
+    if (request.kind === 'input' && result?.kind === 'input' && validAnswers(result.answers))
+        return result;
+    return cancelled();
+}
+/** Audience-scoped durability around the shared request manager; it owns all Canon polling and cancellation. */
+export function createWorkSessionInteractionBridge(options) {
+    const { manager, journal, hostId, conversationId, ownerId, onPendingChange } = options;
+    const active = new Map();
+    const revoked = new Set();
+    let pending = 0;
+    const pendingChange = (delta) => {
+        const wasPending = pending > 0;
+        pending += delta;
+        if (wasPending !== (pending > 0)) {
+            try {
+                onPendingChange?.(pending > 0);
+            }
+            catch { /* Observability cannot authorize or strand a native request. */ }
+        }
+    };
+    const link = (signal, controller) => {
+        const abort = () => controller.abort(signal.reason);
+        if (signal.aborted)
+            abort();
+        else
+            signal.addEventListener('abort', abort, { once: true });
+        return () => signal.removeEventListener('abort', abort);
+    };
+    async function execute(request, id, fingerprint, signal) {
+        pendingChange(1);
+        try {
+            if (signal.aborted || revoked.has(id))
+                return cancelled();
+            const record = await journal.mutate((state) => {
+                const existing = state.interactions.find((entry) => entry.id === id);
+                if (existing)
+                    return existing;
+                const next = { id, fingerprint, expiresAt: Date.now() + INTERACTION_TIMEOUT_MS };
+                state.interactions.push(next);
+                return next;
+            });
+            if (record.fingerprint !== fingerprint || record.expiresAt <= Date.now())
+                return cancelled();
+            if (signal.aborted) {
+                revoked.add(id);
+                await persistCancellation(id, fingerprint);
+                return cancelled();
+            }
+            if (record.result)
+                return validateResult(request, record.result);
+            const runtimeOptions = { requestId: id, expiresAt: record.expiresAt, signal };
+            let result;
+            if (request.kind === 'approval') {
+                const { toolName, toolInput, ...approvalOptions } = request.approval;
+                const reply = await manager.requestApproval(conversationId, toolName, toolInput, {
+                    ...approvalOptions,
+                    runtimeId: hostId,
+                    ...(request.turnId ? { turnId: request.turnId } : {}),
+                    responseUserId: ownerId,
+                    ignoreSessionRules: true,
+                    allowSessionRule: false,
+                }, runtimeOptions);
+                result = { kind: 'approval', decision: reply.decision === 'allow' && reply.respondedBy === ownerId ? 'allow' : 'deny' };
+            }
+            else {
+                const reply = await manager.request('input', conversationId, {
+                    ...request.input, responseUserId: ownerId, ...(request.turnId ? { turnId: request.turnId } : {}),
+                }, runtimeOptions);
+                result = reply.status === 'submitted' && validAnswers(reply.answers)
+                    ? { kind: 'input', answers: reply.answers }
+                    : cancelled();
+            }
+            if (signal.aborted || record.expiresAt <= Date.now())
+                result = cancelled();
+            result = await journal.mutate((state) => {
+                const current = state.interactions.find((entry) => entry.id === id);
+                if (!current || current.fingerprint !== fingerprint)
+                    throw new Error('Native interaction changed while pending');
+                current.result = signal.aborted || current.expiresAt <= Date.now() ? cancelled() : result;
+                return current.result;
+            });
+            // Native resolution can win while the result is being committed to disk.
+            if (signal.aborted || record.expiresAt <= Date.now()) {
+                revoked.add(id);
+                await persistCancellation(id, fingerprint);
+                return cancelled();
+            }
+            return structuredClone(result);
+        }
+        catch {
+            revoked.add(id);
+            // A failed durable write is never an authorization. Preserve the pending
+            // journal if even cancellation cannot be committed, and decline natively.
+            await persistCancellation(id, fingerprint).catch(() => { });
+            return cancelled();
+        }
+        finally {
+            pendingChange(-1);
+        }
+    }
+    async function persistCancellation(id, fingerprint) {
+        await journal.mutate((state) => {
+            const current = state.interactions.find((entry) => entry.id === id);
+            if (current?.fingerprint === fingerprint)
+                current.result = cancelled();
+        });
+    }
+    return {
+        request(request, { signal }) {
+            if (signal.aborted || !ownerId || !hostId || !conversationId || !request.nativeSessionId || !request.nativeRequestId)
+                return Promise.resolve(cancelled());
+            let id;
+            let fingerprint;
+            try {
+                id = `work_${digest([hostId, request.nativeSessionId, request.nativeRequestId, request.turnId ?? null])}`;
+                fingerprint = digest({ ownerId, conversationId, request });
+                if (revoked.has(id))
+                    return Promise.resolve(cancelled());
+                const prior = journal.read().interactions.find((entry) => entry.id === id);
+                if (prior) {
+                    if (prior.fingerprint !== fingerprint || prior.expiresAt <= Date.now())
+                        return Promise.resolve(cancelled());
+                    if (prior.result)
+                        return Promise.resolve(validateResult(request, prior.result));
+                }
+            }
+            catch {
+                return Promise.resolve(cancelled());
+            }
+            const existing = active.get(id);
+            if (existing) {
+                if (existing.fingerprint !== fingerprint)
+                    return Promise.resolve(cancelled());
+                const unlink = link(signal, existing.controller);
+                return existing.result.finally(unlink);
+            }
+            const controller = new AbortController();
+            const unlink = link(signal, controller);
+            const result = execute(request, id, fingerprint, controller.signal).finally(() => { active.delete(id); unlink(); });
+            active.set(id, { fingerprint, controller, result });
+            return result;
+        },
+    };
+}

package/dist/work-session-state.d.ts

@@ -0,0 +1,36 @@
+import { type ExclusiveJsonFileStore, type NativeSessionInteractionResult, type WorkSessionCompletion, type WorkSessionRequest, type WorkSessionSettings } from '@canonmsg/core';
+export interface WorkSessionOperation {
+    request: WorkSessionRequest;
+    fingerprint: string;
+    phase: 'creating' | 'created' | 'attaching' | 'complete';
+    nativeSessionId?: string;
+    settings?: WorkSessionSettings;
+    completion?: WorkSessionCompletion;
+    acknowledged?: boolean;
+    /** Retain inaccessible operations for audit without blocking unrelated rooms. */
+    quarantined?: string;
+}
+export interface WorkSessionInteractionRecord {
+    id: string;
+    fingerprint: string;
+    expiresAt: number;
+    result?: NativeSessionInteractionResult;
+}
+export interface WorkSessionHostJournal {
+    schema: 'canon.work-session-host.v1';
+    environmentId: string;
+    agentId: string;
+    hostId: string;
+    operations: WorkSessionOperation[];
+    interactions: WorkSessionInteractionRecord[];
+}
+export type WorkSessionHostStore = ExclusiveJsonFileStore<WorkSessionHostJournal>;
+export declare function createFileWorkSessionHostStore(path: string): WorkSessionHostStore;
+/** Commit before advancing memory; simultaneous room events cannot overwrite one another. */
+export declare function createWorkSessionJournal(store: WorkSessionHostStore, identity: Pick<WorkSessionHostJournal, 'environmentId' | 'agentId' | 'hostId'>): {
+    load(): Promise<void>;
+    read(): WorkSessionHostJournal;
+    mutate<T>(change: (journal: WorkSessionHostJournal) => T): Promise<T>;
+    close(): Promise<void>;
+};
+export type WorkSessionJournal = ReturnType<typeof createWorkSessionJournal>;

package/dist/work-session-state.js

@@ -0,0 +1,62 @@
+import { createExclusiveJsonFileStore, } from '@canonmsg/core';
+export function createFileWorkSessionHostStore(path) {
+    return createExclusiveJsonFileStore(path, 'Work session host');
+}
+/** Commit before advancing memory; simultaneous room events cannot overwrite one another. */
+export function createWorkSessionJournal(store, identity) {
+    let current;
+    let writes = Promise.resolve();
+    let closed = false;
+    return {
+        async load() {
+            const loaded = await store.load();
+            if (loaded) {
+                if (loaded.schema !== 'canon.work-session-host.v1'
+                    || loaded.environmentId !== identity.environmentId || loaded.agentId !== identity.agentId
+                    || loaded.hostId !== identity.hostId || !Array.isArray(loaded.operations)
+                    || !Array.isArray(loaded.interactions)
+                    || loaded.operations.some((entry) => !entry?.request?.requestId || !entry.fingerprint
+                        || !['creating', 'created', 'attaching', 'complete'].includes(entry.phase)
+                        || (entry.phase === 'complete' && !entry.completion))
+                    || loaded.interactions.some((entry) => !entry?.id || !entry.fingerprint || !Number.isFinite(entry.expiresAt))) {
+                    throw new Error('Work-session journal cannot be verified; retain it for recovery.');
+                }
+                current = structuredClone(loaded);
+            }
+            else {
+                const initial = { schema: 'canon.work-session-host.v1', ...identity, operations: [], interactions: [] };
+                await store.save(initial);
+                current = initial;
+            }
+        },
+        read() {
+            if (!current)
+                throw new Error('Work-session journal is not loaded.');
+            return structuredClone(current);
+        },
+        mutate(change) {
+            if (closed)
+                return Promise.reject(new Error('Work-session journal is closed.'));
+            let result;
+            const mutation = writes.then(async () => {
+                if (!current)
+                    throw new Error('Work-session journal is not loaded.');
+                const next = structuredClone(current);
+                result = change(next);
+                await store.save(next);
+                current = next;
+            });
+            writes = mutation.catch(() => { });
+            return mutation.then(() => result);
+        },
+        async close() {
+            closed = true;
+            try {
+                await writes;
+            }
+            finally {
+                await store.close();
+            }
+        },
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@canonmsg/agent-sdk",
-  "version": "10.2.1",
+  "version": "10.4.0",
   "description": "Canon Agent SDK — build AI agents that participate in Canon conversations",
   "type": "module",
   "main": "dist/index.js",
@@ -28,7 +28,7 @@
     "node": ">=18.0.0"
   },
   "dependencies": {
-    "@canonmsg/core": "^12.3.0"
+    "@canonmsg/core": "^12.5.0"
   },
   "publishConfig": {
     "access": "public"
@@ -38,5 +38,9 @@
     "typescript": "~5.7.0",
     "vitest": "^4.1.8"
   },
-  "license": "MIT"
+  "license": "MIT",
+  "homepage": "https://canonmail.com/agents/build#agent-sdk",
+  "bugs": {
+    "url": "https://canonmail.com/support"
+  }
 }