@canonmsg/backend-contracts 8.2.0 → 8.4.0

package/dist/cjs/index.js

@@ -35,3 +35,5 @@ __exportStar(require("./firestoreValues.js"), exports);
 __exportStar(require("./moderation.js"), exports);
 __exportStar(require("./selfContext.js"), exports);
 __exportStar(require("./replyAuthority.js"), exports);
+__exportStar(require("./runtimeDescriptor.js"), exports);
+__exportStar(require("./workSessions.js"), exports);

package/dist/cjs/runtimeDescriptor.js

@@ -0,0 +1,184 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MAX_PUBLIC_RUNTIME_COMMANDS = void 0;
+exports.normalizeRuntimeCommandAlias = normalizeRuntimeCommandAlias;
+exports.normalizeRuntimeCommandAliases = normalizeRuntimeCommandAliases;
+exports.isRuntimePrimitiveId = isRuntimePrimitiveId;
+exports.normalizePublicRuntimeCommands = normalizePublicRuntimeCommands;
+exports.normalizePublicRuntimeDescriptor = normalizePublicRuntimeDescriptor;
+exports.normalizePublicRuntimeFacts = normalizePublicRuntimeFacts;
+function normalizeRuntimeCommandAlias(value) {
+    const normalized = value.trim().replace(/^\/+/, '').replace(/\s+/g, '-');
+    return /^[A-Za-z0-9:_-]+$/.test(normalized) ? normalized : null;
+}
+function normalizeRuntimeCommandAliases(command) {
+    const rawAliases = command.aliases?.length ? command.aliases : [command.id];
+    const aliases = rawAliases
+        .map(normalizeRuntimeCommandAlias)
+        .filter((value) => Boolean(value));
+    return Array.from(new Set(aliases));
+}
+exports.MAX_PUBLIC_RUNTIME_COMMANDS = 256;
+function record(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value)
+        ? value : {};
+}
+function text(value, max) {
+    return typeof value === 'string' && value.length > 0 && value.length <= max ? value : undefined;
+}
+function member(value, choices) {
+    return choices.includes(value) ? value : undefined;
+}
+function members(value, choices) {
+    if (!Array.isArray(value))
+        return undefined;
+    return [...new Set(value.filter((entry) => choices.includes(entry)))];
+}
+function defined(value) {
+    return Object.fromEntries(Object.entries(value).filter(([, entry]) => entry !== undefined));
+}
+const PRIMITIVES = [
+    'runtime.status', 'runtime.reasoning.set', 'runtime.verbosity.set', 'runtime.usage',
+    'context.compact', 'session.new', 'session.reset',
+];
+function isRuntimePrimitiveId(value) {
+    return typeof value === 'string' && PRIMITIVES.includes(value);
+}
+function normalizeDispatch(value) {
+    const dispatch = record(value);
+    switch (dispatch.kind) {
+        case 'signal': {
+            const signal = member(dispatch.signal, ['interrupt', 'stop_and_drop', 'new_session']);
+            return signal ? { kind: 'signal', signal } : undefined;
+        }
+        case 'primitive': {
+            const primitive = member(dispatch.primitive, PRIMITIVES);
+            return primitive ? { kind: 'primitive', primitive } : undefined;
+        }
+        case 'control': {
+            const controlId = text(dispatch.controlId, 128);
+            return controlId ? defined({ kind: 'control', controlId, value: text(dispatch.value, 1024) }) : undefined;
+        }
+        case 'text_passthrough': {
+            const template = text(dispatch.template, 2048);
+            return template ? { kind: 'text_passthrough', template } : undefined;
+        }
+        case 'compose': {
+            const content = text(dispatch.text, 2048);
+            return content ? { kind: 'compose', text: content } : undefined;
+        }
+        case 'open_details':
+            return defined({ kind: 'open_details', target: text(dispatch.target, 128) });
+        default:
+            return undefined;
+    }
+}
+function normalizeArgument(value) {
+    const arg = record(value);
+    const id = text(arg.id, 128);
+    const label = text(arg.label, 160);
+    const kind = member(arg.kind, ['string', 'enum', 'boolean']);
+    if (!id || !label || !kind)
+        return undefined;
+    if (['required', 'captureRemaining'].some((key) => arg[key] !== undefined && typeof arg[key] !== 'boolean'))
+        return undefined;
+    if (arg.choices !== undefined && !Array.isArray(arg.choices))
+        return undefined;
+    const choices = Array.isArray(arg.choices) ? arg.choices.slice(0, 128).flatMap((value) => {
+        const choice = record(value);
+        const entry = text(choice.value, 1024);
+        const label = text(choice.label, 160);
+        return entry && label ? [defined({ value: entry, label, description: text(choice.description, 1024) })] : [];
+    }) : undefined;
+    // Do not advertise an argument whose required enum has no usable choices.
+    if (kind === 'enum' && !choices?.length)
+        return undefined;
+    return defined({ id, label, kind, choices,
+        required: typeof arg.required === 'boolean' ? arg.required : undefined,
+        captureRemaining: typeof arg.captureRemaining === 'boolean' ? arg.captureRemaining : undefined,
+    });
+}
+/** Public command metadata shared by REST and direct RTDB publishers. Never copies local configuration. */
+function normalizePublicRuntimeCommands(value) {
+    if (!Array.isArray(value))
+        return [];
+    const seenIds = new Set();
+    const seenAliases = new Set();
+    const result = [];
+    for (const item of value.slice(0, exports.MAX_PUBLIC_RUNTIME_COMMANDS)) {
+        const command = record(item);
+        const id = text(command.id, 128);
+        const label = text(command.label, 160);
+        const dispatch = normalizeDispatch(command.dispatch);
+        if (!id || !label || !dispatch || seenIds.has(id)
+            || command.visibility === 'hidden' || command.sensitive === true)
+            continue;
+        if (['ownerOnly', 'sensitive'].some((key) => command[key] !== undefined && typeof command[key] !== 'boolean'))
+            continue;
+        if (['aliases', 'args', 'placements', 'availability'].some((key) => command[key] !== undefined && !Array.isArray(command[key])))
+            continue;
+        const rawAliases = Array.isArray(command.aliases) && command.aliases.length ? command.aliases : [id];
+        const aliases = [...new Set(rawAliases.slice(0, 8).flatMap((value) => {
+                const alias = typeof value === 'string' && value.length <= 128 ? normalizeRuntimeCommandAlias(value) : null;
+                return alias && /^[A-Za-z0-9:_-]+$/.test(alias) && !seenAliases.has(alias.toLowerCase()) ? [alias] : [];
+            }))];
+        if (!aliases.length)
+            continue;
+        const args = Array.isArray(command.args) ? command.args.slice(0, 12).map(normalizeArgument) : undefined;
+        // A malformed argument must not silently turn a parameterized action into a different command.
+        if (args?.some((arg) => !arg) || (Array.isArray(command.args) && command.args.length > 12))
+            continue;
+        seenIds.add(id);
+        aliases.forEach((alias) => seenAliases.add(alias.toLowerCase()));
+        result.push(defined({ id, label, aliases, dispatch,
+            args: args,
+            description: text(command.description, 1024),
+            category: member(command.category, ['plan', 'turn', 'session', 'runtime', 'details', 'skill', 'custom']),
+            placements: members(command.placements, ['composer_slash', 'command_palette', 'session_strip']),
+            availability: members(command.availability, ['idle', 'busy', 'busy_with_queue', 'waiting_input', 'always']),
+            ownerOnly: typeof command.ownerOnly === 'boolean' ? command.ownerOnly : undefined,
+            disabledReason: text(command.disabledReason, 1024),
+            trailingTextBehavior: member(command.trailingTextBehavior, ['ignore', 'send_as_prompt']),
+            primitive: member(command.primitive, PRIMITIVES),
+            tier: member(command.tier, ['primary', 'detail', 'diagnostic']),
+        }));
+    }
+    return result;
+}
+function normalizePublicRuntimeDescriptor(value) {
+    const descriptor = record(value);
+    return defined({
+        supportsInterrupt: typeof descriptor.supportsInterrupt === 'boolean' ? descriptor.supportsInterrupt : undefined,
+        supportsInputInterrupt: typeof descriptor.supportsInputInterrupt === 'boolean' ? descriptor.supportsInputInterrupt : undefined,
+        streamingTextMode: member(descriptor.streamingTextMode, ['none', 'status', 'snapshot', 'block', 'delta']),
+        commands: Array.isArray(descriptor.commands) ? normalizePublicRuntimeCommands(descriptor.commands) : undefined,
+    });
+}
+const PUBLIC_RUNTIME_FACT_GROUPS = {
+    harness: 'runtime', runtime: 'runtime', provider: 'model', model: 'model',
+    reasoning: 'model', connection: 'connection', gateway: 'connection', route: 'route',
+};
+/** Read-only session facts, excluding local paths, inventories, and hidden/sensitive values. */
+function normalizePublicRuntimeFacts(value) {
+    if (!Array.isArray(value))
+        return [];
+    const seen = new Set();
+    return value.slice(0, 16).flatMap((entry) => {
+        const fact = record(entry);
+        const id = text(fact.id, 64);
+        const group = id && Object.hasOwn(PUBLIC_RUNTIME_FACT_GROUPS, id)
+            ? PUBLIC_RUNTIME_FACT_GROUPS[id] : undefined;
+        const label = text(fact.label, 80);
+        const content = text(fact.value, 512);
+        if (!id || !group || !label || !content || seen.has(id)
+            || fact.sensitive === true || fact.visibility === 'hidden')
+            return [];
+        seen.add(id);
+        return [defined({ id, group, label, value: content,
+                tier: member(fact.tier, ['primary', 'detail', 'diagnostic']),
+                tone: member(fact.tone, ['neutral', 'good', 'warning', 'danger']),
+                copyable: typeof fact.copyable === 'boolean' ? fact.copyable : undefined,
+                updatedAt: typeof fact.updatedAt === 'number' && Number.isFinite(fact.updatedAt) && fact.updatedAt >= 0
+                    ? fact.updatedAt : undefined, })];
+    });
+}

package/dist/cjs/workSessions.js

@@ -0,0 +1,162 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WORK_SESSION_REQUEST_TTL_MS = exports.WORK_SESSION_LEASE_MS = exports.WORK_SESSION_SCHEMA = void 0;
+exports.workSessionId = workSessionId;
+exports.parseWorkSessionSettings = parseWorkSessionSettings;
+exports.parseWorkSessionCatalog = parseWorkSessionCatalog;
+exports.parseWorkSessionSelection = parseWorkSessionSelection;
+exports.assertWorkSessionSelectionAvailable = assertWorkSessionSelectionAvailable;
+exports.parseWorkSessionRuntimeRegistration = parseWorkSessionRuntimeRegistration;
+exports.parseWorkSessionRuntimeAuth = parseWorkSessionRuntimeAuth;
+exports.parseRequestWorkSessionInput = parseRequestWorkSessionInput;
+exports.parseWorkSessionCompletion = parseWorkSessionCompletion;
+/** Private owner/operator workflow. None of this catalog belongs in public runtime descriptors. */
+exports.WORK_SESSION_SCHEMA = 'canon.work-sessions.v1';
+exports.WORK_SESSION_LEASE_MS = 90_000;
+exports.WORK_SESSION_REQUEST_TTL_MS = 5 * 60_000;
+const SETTINGS_KEYS = ['projectId', 'modelId', 'reasoningEffort', 'permissionMode', 'executionMode'];
+function object(value, keys, label) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        throw new Error(`Invalid ${label}`);
+    const result = value;
+    if (Object.keys(result).some((key) => !keys.includes(key)))
+        throw new Error(`Unsupported ${label} field`);
+    return result;
+}
+function workSessionId(value, label = 'identifier') {
+    if (typeof value !== 'string' || !/^[A-Za-z0-9_.:-]{1,160}$/.test(value))
+        throw new Error(`Invalid ${label}`);
+    return value;
+}
+function label(value, name, max = 160) {
+    if (typeof value !== 'string' || !value.trim() || value.length > max)
+        throw new Error(`Invalid ${name}`);
+    return value.trim();
+}
+function parseWorkSessionSettings(value) {
+    const input = object(value, SETTINGS_KEYS, 'settings');
+    return Object.fromEntries(Object.entries(input).map(([key, value]) => [key, workSessionId(value, key)]));
+}
+function choices(value, models = false) {
+    if (!Array.isArray(value) || value.length > 128)
+        throw new Error('Invalid choices');
+    const ids = new Set();
+    return value.map((entry) => {
+        const input = object(entry, ['id', 'label', 'description', ...(models ? ['reasoningEfforts', 'defaultReasoningEffort'] : [])], 'choice');
+        const id = workSessionId(input.id);
+        if (ids.has(id))
+            throw new Error('Duplicate choice identifier');
+        ids.add(id);
+        const result = { id, label: label(input.label, 'choice label') };
+        if (input.description !== undefined)
+            result.description = label(input.description, 'choice description', 512);
+        if (input.reasoningEfforts !== undefined)
+            result.reasoningEfforts = choices(input.reasoningEfforts);
+        if (input.defaultReasoningEffort !== undefined) {
+            result.defaultReasoningEffort = workSessionId(input.defaultReasoningEffort);
+            if (!result.reasoningEfforts?.some((choice) => choice.id === result.defaultReasoningEffort))
+                throw new Error('Invalid default reasoning effort');
+        }
+        return result;
+    });
+}
+function parseWorkSessionCatalog(value) {
+    const input = object(value, ['revision', 'provider', 'canCreate', 'canAttach', 'projects', 'models', 'reasoningEfforts', 'permissionModes', 'executionModes', 'defaults', 'sessions'], 'catalog');
+    if (typeof input.canCreate !== 'boolean' || typeof input.canAttach !== 'boolean')
+        throw new Error('Invalid catalog capabilities');
+    if (!Array.isArray(input.sessions) || input.sessions.length > 128)
+        throw new Error('Invalid loaded sessions');
+    const ids = new Set();
+    const result = {
+        revision: workSessionId(input.revision, 'catalog revision'), provider: workSessionId(input.provider, 'provider'),
+        canCreate: input.canCreate, canAttach: input.canAttach, projects: choices(input.projects),
+        sessions: input.sessions.map((entry) => {
+            const session = object(entry, ['id', 'title', 'status', 'settings', 'projectLabel', 'modelLabel'], 'loaded session');
+            const id = workSessionId(session.id, 'session identifier');
+            if (ids.has(id))
+                throw new Error('Duplicate loaded session');
+            ids.add(id);
+            if (session.status !== 'idle' && session.status !== 'running')
+                throw new Error('Invalid session status');
+            return {
+                id, title: label(session.title, 'session title'), status: session.status,
+                settings: parseWorkSessionSettings(session.settings),
+                ...(session.projectLabel !== undefined ? { projectLabel: label(session.projectLabel, 'project label') } : {}),
+                ...(session.modelLabel !== undefined ? { modelLabel: label(session.modelLabel, 'model label') } : {}),
+            };
+        }),
+    };
+    for (const key of ['models', 'reasoningEfforts', 'permissionModes', 'executionModes']) {
+        if (input[key] !== undefined)
+            result[key] = choices(input[key], key === 'models');
+    }
+    if (input.defaults !== undefined)
+        result.defaults = parseWorkSessionSettings(input.defaults);
+    if (result.canCreate && !result.projects.length)
+        throw new Error('Creating sessions requires an advertised project');
+    if (JSON.stringify(result).length > 65_536)
+        throw new Error('Work session catalog is too large');
+    return result;
+}
+function parseWorkSessionSelection(value) {
+    const mode = value?.mode;
+    if (mode === 'attach') {
+        const input = object(value, ['mode', 'sessionId'], 'attach selection');
+        return { mode, sessionId: workSessionId(input.sessionId, 'session identifier') };
+    }
+    if (mode === 'create') {
+        const { mode: _mode, ...settings } = object(value, ['mode', ...SETTINGS_KEYS], 'create selection');
+        return { mode, ...parseWorkSessionSettings(settings), projectId: workSessionId(settings.projectId, 'project identifier') };
+    }
+    throw new Error('Invalid work session selection');
+}
+function assertWorkSessionSelectionAvailable(selection, catalog) {
+    if (selection.mode === 'attach') {
+        if (!catalog.canAttach || !catalog.sessions.some((session) => session.id === selection.sessionId))
+            throw new Error('Selected loaded session is unavailable');
+        return;
+    }
+    if (!catalog.canCreate || !catalog.projects.some((project) => project.id === selection.projectId))
+        throw new Error('Selected project is unavailable');
+    const modelId = selection.modelId ?? catalog.defaults?.modelId;
+    const model = catalog.models?.find((choice) => choice.id === modelId);
+    const available = {
+        modelId: catalog.models, reasoningEffort: model?.reasoningEfforts ?? catalog.reasoningEfforts,
+        permissionMode: catalog.permissionModes, executionMode: catalog.executionModes,
+    };
+    for (const key of ['modelId', 'reasoningEffort', 'permissionMode', 'executionMode']) {
+        if (selection[key] !== undefined && !available[key]?.some((choice) => choice.id === selection[key]))
+            throw new Error(`Selected ${key} is unavailable`);
+    }
+}
+function parseWorkSessionRuntimeRegistration(value) {
+    const input = object(value, ['hostId', 'runtimeEpoch', 'displayName', 'catalog'], 'runtime registration');
+    return { hostId: workSessionId(input.hostId), runtimeEpoch: workSessionId(input.runtimeEpoch), displayName: label(input.displayName, 'host name'), catalog: parseWorkSessionCatalog(input.catalog) };
+}
+function parseWorkSessionRuntimeAuth(value, extraKeys = []) {
+    const input = object(value, ['hostId', 'runtimeEpoch', 'leaseToken', ...extraKeys], 'runtime request');
+    return { hostId: workSessionId(input.hostId), runtimeEpoch: workSessionId(input.runtimeEpoch), leaseToken: workSessionId(input.leaseToken, 'lease token') };
+}
+function parseRequestWorkSessionInput(value) {
+    const input = object(value, ['agentId', 'conversationId', 'requestId', 'hostId', 'runtimeEpoch', 'catalogRevision', 'selection'], 'work session request');
+    if (typeof input.requestId !== 'string' || !/^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(input.requestId))
+        throw new Error('requestId must be a UUID');
+    return {
+        agentId: workSessionId(input.agentId), conversationId: workSessionId(input.conversationId), requestId: input.requestId,
+        hostId: workSessionId(input.hostId), runtimeEpoch: workSessionId(input.runtimeEpoch), catalogRevision: workSessionId(input.catalogRevision),
+        selection: parseWorkSessionSelection(input.selection),
+    };
+}
+function parseWorkSessionCompletion(value) {
+    const status = value?.status;
+    if (status === 'attached') {
+        const input = object(value, ['status', 'nativeSessionId', 'settings'], 'attached result');
+        return { status, nativeSessionId: workSessionId(input.nativeSessionId), settings: parseWorkSessionSettings(input.settings) };
+    }
+    if (status === 'failed' || status === 'uncertain') {
+        const input = object(value, ['status', 'error'], 'failure result');
+        const error = object(input.error, ['code', 'message'], 'failure');
+        return { status, error: { code: workSessionId(error.code), message: label(error.message, 'failure message', 512) } };
+    }
+    throw new Error('Invalid work session result');
+}

package/dist/index.d.ts

@@ -19,3 +19,5 @@ export * from './firestoreValues.js';
 export * from './moderation.js';
 export * from './selfContext.js';
 export * from './replyAuthority.js';
+export * from './runtimeDescriptor.js';
+export * from './workSessions.js';

package/dist/index.js

@@ -19,3 +19,5 @@ export * from './firestoreValues.js';
 export * from './moderation.js';
 export * from './selfContext.js';
 export * from './replyAuthority.js';
+export * from './runtimeDescriptor.js';
+export * from './workSessions.js';

package/dist/runtimeDescriptor.d.ts

@@ -0,0 +1,88 @@
+export type CanonControlValue = string;
+export type CanonRuntimeStreamingMode = 'none' | 'status' | 'snapshot' | 'block' | 'delta';
+export type CanonRuntimeDetailTier = 'primary' | 'detail' | 'diagnostic';
+export type CanonRuntimeVisibility = 'conversation' | 'hidden';
+export type CanonRuntimeActionAvailability = 'idle' | 'busy' | 'busy_with_queue' | 'waiting_input' | 'always';
+export type CanonRuntimeActionPlacement = 'composer_slash' | 'command_palette' | 'session_strip';
+export type CanonRuntimeActionCategory = 'plan' | 'turn' | 'session' | 'runtime' | 'details' | 'skill' | 'custom';
+export type CanonRuntimePrimitiveId = 'runtime.status' | 'runtime.reasoning.set' | 'runtime.verbosity.set' | 'runtime.usage' | 'context.compact' | 'session.new' | 'session.reset';
+export type CanonRuntimeCommandArgumentKind = 'string' | 'enum' | 'boolean';
+export interface CanonRuntimeCommandArgumentChoice {
+    value: string;
+    label: string;
+    description?: string;
+}
+export interface CanonRuntimeCommandArgumentDescriptor {
+    id: string;
+    label: string;
+    kind: CanonRuntimeCommandArgumentKind;
+    required?: boolean;
+    captureRemaining?: boolean;
+    choices?: ReadonlyArray<CanonRuntimeCommandArgumentChoice>;
+}
+export type CanonRuntimeActionDispatch = {
+    kind: 'control';
+    controlId: string;
+    value?: CanonControlValue;
+} | {
+    kind: 'signal';
+    signal: 'interrupt' | 'stop_and_drop' | 'new_session';
+} | {
+    kind: 'primitive';
+    primitive: CanonRuntimePrimitiveId;
+} | {
+    kind: 'text_passthrough';
+    template: string;
+} | {
+    kind: 'compose';
+    text: string;
+} | {
+    kind: 'open_details';
+    target?: string;
+};
+export interface CanonRuntimeActionDescriptor {
+    id: string;
+    label: string;
+    description?: string;
+    visibility?: CanonRuntimeVisibility;
+    tier?: CanonRuntimeDetailTier;
+    sensitive?: boolean;
+    primitive?: CanonRuntimePrimitiveId;
+    aliases?: ReadonlyArray<string>;
+    category?: CanonRuntimeActionCategory;
+    placements?: ReadonlyArray<CanonRuntimeActionPlacement>;
+    availability?: ReadonlyArray<CanonRuntimeActionAvailability>;
+    ownerOnly?: boolean;
+    disabledReason?: string | null;
+    trailingTextBehavior?: 'ignore' | 'send_as_prompt';
+    args?: ReadonlyArray<CanonRuntimeCommandArgumentDescriptor>;
+    dispatch: CanonRuntimeActionDispatch;
+}
+export interface CanonRuntimeCommandDescriptor extends CanonRuntimeActionDescriptor {
+    primitive?: CanonRuntimePrimitiveId;
+    args?: ReadonlyArray<CanonRuntimeCommandArgumentDescriptor>;
+}
+export declare function normalizeRuntimeCommandAlias(value: string): string | null;
+export declare function normalizeRuntimeCommandAliases(command: Pick<CanonRuntimeCommandDescriptor, 'id' | 'aliases'>): string[];
+export declare const MAX_PUBLIC_RUNTIME_COMMANDS = 256;
+export declare function isRuntimePrimitiveId(value: unknown): value is CanonRuntimePrimitiveId;
+/** Public command metadata shared by REST and direct RTDB publishers. Never copies local configuration. */
+export declare function normalizePublicRuntimeCommands(value: unknown): CanonRuntimeCommandDescriptor[];
+export interface PublicRuntimeDescriptor {
+    supportsInterrupt?: boolean;
+    supportsInputInterrupt?: boolean;
+    streamingTextMode?: CanonRuntimeStreamingMode;
+    commands?: CanonRuntimeCommandDescriptor[];
+}
+export declare function normalizePublicRuntimeDescriptor(value: unknown): PublicRuntimeDescriptor;
+/** Read-only session facts, excluding local paths, inventories, and hidden/sensitive values. */
+export declare function normalizePublicRuntimeFacts(value: unknown): {
+    id: string;
+    group: "runtime" | "model" | "connection" | "route";
+    label: string;
+    value: string;
+    tier: "primary" | "detail" | "diagnostic" | undefined;
+    tone: "neutral" | "good" | "warning" | "danger" | undefined;
+    copyable: boolean | undefined;
+    updatedAt: number | undefined;
+}[];

package/dist/runtimeDescriptor.js

@@ -0,0 +1,175 @@
+export function normalizeRuntimeCommandAlias(value) {
+    const normalized = value.trim().replace(/^\/+/, '').replace(/\s+/g, '-');
+    return /^[A-Za-z0-9:_-]+$/.test(normalized) ? normalized : null;
+}
+export function normalizeRuntimeCommandAliases(command) {
+    const rawAliases = command.aliases?.length ? command.aliases : [command.id];
+    const aliases = rawAliases
+        .map(normalizeRuntimeCommandAlias)
+        .filter((value) => Boolean(value));
+    return Array.from(new Set(aliases));
+}
+export const MAX_PUBLIC_RUNTIME_COMMANDS = 256;
+function record(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value)
+        ? value : {};
+}
+function text(value, max) {
+    return typeof value === 'string' && value.length > 0 && value.length <= max ? value : undefined;
+}
+function member(value, choices) {
+    return choices.includes(value) ? value : undefined;
+}
+function members(value, choices) {
+    if (!Array.isArray(value))
+        return undefined;
+    return [...new Set(value.filter((entry) => choices.includes(entry)))];
+}
+function defined(value) {
+    return Object.fromEntries(Object.entries(value).filter(([, entry]) => entry !== undefined));
+}
+const PRIMITIVES = [
+    'runtime.status', 'runtime.reasoning.set', 'runtime.verbosity.set', 'runtime.usage',
+    'context.compact', 'session.new', 'session.reset',
+];
+export function isRuntimePrimitiveId(value) {
+    return typeof value === 'string' && PRIMITIVES.includes(value);
+}
+function normalizeDispatch(value) {
+    const dispatch = record(value);
+    switch (dispatch.kind) {
+        case 'signal': {
+            const signal = member(dispatch.signal, ['interrupt', 'stop_and_drop', 'new_session']);
+            return signal ? { kind: 'signal', signal } : undefined;
+        }
+        case 'primitive': {
+            const primitive = member(dispatch.primitive, PRIMITIVES);
+            return primitive ? { kind: 'primitive', primitive } : undefined;
+        }
+        case 'control': {
+            const controlId = text(dispatch.controlId, 128);
+            return controlId ? defined({ kind: 'control', controlId, value: text(dispatch.value, 1024) }) : undefined;
+        }
+        case 'text_passthrough': {
+            const template = text(dispatch.template, 2048);
+            return template ? { kind: 'text_passthrough', template } : undefined;
+        }
+        case 'compose': {
+            const content = text(dispatch.text, 2048);
+            return content ? { kind: 'compose', text: content } : undefined;
+        }
+        case 'open_details':
+            return defined({ kind: 'open_details', target: text(dispatch.target, 128) });
+        default:
+            return undefined;
+    }
+}
+function normalizeArgument(value) {
+    const arg = record(value);
+    const id = text(arg.id, 128);
+    const label = text(arg.label, 160);
+    const kind = member(arg.kind, ['string', 'enum', 'boolean']);
+    if (!id || !label || !kind)
+        return undefined;
+    if (['required', 'captureRemaining'].some((key) => arg[key] !== undefined && typeof arg[key] !== 'boolean'))
+        return undefined;
+    if (arg.choices !== undefined && !Array.isArray(arg.choices))
+        return undefined;
+    const choices = Array.isArray(arg.choices) ? arg.choices.slice(0, 128).flatMap((value) => {
+        const choice = record(value);
+        const entry = text(choice.value, 1024);
+        const label = text(choice.label, 160);
+        return entry && label ? [defined({ value: entry, label, description: text(choice.description, 1024) })] : [];
+    }) : undefined;
+    // Do not advertise an argument whose required enum has no usable choices.
+    if (kind === 'enum' && !choices?.length)
+        return undefined;
+    return defined({ id, label, kind, choices,
+        required: typeof arg.required === 'boolean' ? arg.required : undefined,
+        captureRemaining: typeof arg.captureRemaining === 'boolean' ? arg.captureRemaining : undefined,
+    });
+}
+/** Public command metadata shared by REST and direct RTDB publishers. Never copies local configuration. */
+export function normalizePublicRuntimeCommands(value) {
+    if (!Array.isArray(value))
+        return [];
+    const seenIds = new Set();
+    const seenAliases = new Set();
+    const result = [];
+    for (const item of value.slice(0, MAX_PUBLIC_RUNTIME_COMMANDS)) {
+        const command = record(item);
+        const id = text(command.id, 128);
+        const label = text(command.label, 160);
+        const dispatch = normalizeDispatch(command.dispatch);
+        if (!id || !label || !dispatch || seenIds.has(id)
+            || command.visibility === 'hidden' || command.sensitive === true)
+            continue;
+        if (['ownerOnly', 'sensitive'].some((key) => command[key] !== undefined && typeof command[key] !== 'boolean'))
+            continue;
+        if (['aliases', 'args', 'placements', 'availability'].some((key) => command[key] !== undefined && !Array.isArray(command[key])))
+            continue;
+        const rawAliases = Array.isArray(command.aliases) && command.aliases.length ? command.aliases : [id];
+        const aliases = [...new Set(rawAliases.slice(0, 8).flatMap((value) => {
+                const alias = typeof value === 'string' && value.length <= 128 ? normalizeRuntimeCommandAlias(value) : null;
+                return alias && /^[A-Za-z0-9:_-]+$/.test(alias) && !seenAliases.has(alias.toLowerCase()) ? [alias] : [];
+            }))];
+        if (!aliases.length)
+            continue;
+        const args = Array.isArray(command.args) ? command.args.slice(0, 12).map(normalizeArgument) : undefined;
+        // A malformed argument must not silently turn a parameterized action into a different command.
+        if (args?.some((arg) => !arg) || (Array.isArray(command.args) && command.args.length > 12))
+            continue;
+        seenIds.add(id);
+        aliases.forEach((alias) => seenAliases.add(alias.toLowerCase()));
+        result.push(defined({ id, label, aliases, dispatch,
+            args: args,
+            description: text(command.description, 1024),
+            category: member(command.category, ['plan', 'turn', 'session', 'runtime', 'details', 'skill', 'custom']),
+            placements: members(command.placements, ['composer_slash', 'command_palette', 'session_strip']),
+            availability: members(command.availability, ['idle', 'busy', 'busy_with_queue', 'waiting_input', 'always']),
+            ownerOnly: typeof command.ownerOnly === 'boolean' ? command.ownerOnly : undefined,
+            disabledReason: text(command.disabledReason, 1024),
+            trailingTextBehavior: member(command.trailingTextBehavior, ['ignore', 'send_as_prompt']),
+            primitive: member(command.primitive, PRIMITIVES),
+            tier: member(command.tier, ['primary', 'detail', 'diagnostic']),
+        }));
+    }
+    return result;
+}
+export function normalizePublicRuntimeDescriptor(value) {
+    const descriptor = record(value);
+    return defined({
+        supportsInterrupt: typeof descriptor.supportsInterrupt === 'boolean' ? descriptor.supportsInterrupt : undefined,
+        supportsInputInterrupt: typeof descriptor.supportsInputInterrupt === 'boolean' ? descriptor.supportsInputInterrupt : undefined,
+        streamingTextMode: member(descriptor.streamingTextMode, ['none', 'status', 'snapshot', 'block', 'delta']),
+        commands: Array.isArray(descriptor.commands) ? normalizePublicRuntimeCommands(descriptor.commands) : undefined,
+    });
+}
+const PUBLIC_RUNTIME_FACT_GROUPS = {
+    harness: 'runtime', runtime: 'runtime', provider: 'model', model: 'model',
+    reasoning: 'model', connection: 'connection', gateway: 'connection', route: 'route',
+};
+/** Read-only session facts, excluding local paths, inventories, and hidden/sensitive values. */
+export function normalizePublicRuntimeFacts(value) {
+    if (!Array.isArray(value))
+        return [];
+    const seen = new Set();
+    return value.slice(0, 16).flatMap((entry) => {
+        const fact = record(entry);
+        const id = text(fact.id, 64);
+        const group = id && Object.hasOwn(PUBLIC_RUNTIME_FACT_GROUPS, id)
+            ? PUBLIC_RUNTIME_FACT_GROUPS[id] : undefined;
+        const label = text(fact.label, 80);
+        const content = text(fact.value, 512);
+        if (!id || !group || !label || !content || seen.has(id)
+            || fact.sensitive === true || fact.visibility === 'hidden')
+            return [];
+        seen.add(id);
+        return [defined({ id, group, label, value: content,
+                tier: member(fact.tier, ['primary', 'detail', 'diagnostic']),
+                tone: member(fact.tone, ['neutral', 'good', 'warning', 'danger']),
+                copyable: typeof fact.copyable === 'boolean' ? fact.copyable : undefined,
+                updatedAt: typeof fact.updatedAt === 'number' && Number.isFinite(fact.updatedAt) && fact.updatedAt >= 0
+                    ? fact.updatedAt : undefined, })];
+    });
+}

package/dist/workSessions.d.ts

@@ -0,0 +1,156 @@
+/** Private owner/operator workflow. None of this catalog belongs in public runtime descriptors. */
+export declare const WORK_SESSION_SCHEMA: "canon.work-sessions.v1";
+export declare const WORK_SESSION_LEASE_MS = 90000;
+export declare const WORK_SESSION_REQUEST_TTL_MS: number;
+export interface WorkSessionChoice {
+    id: string;
+    label: string;
+    description?: string;
+}
+export interface WorkSessionModelChoice extends WorkSessionChoice {
+    reasoningEfforts?: WorkSessionChoice[];
+    defaultReasoningEffort?: string;
+}
+export interface WorkSessionSettings {
+    projectId?: string;
+    modelId?: string;
+    reasoningEffort?: string;
+    permissionMode?: string;
+    executionMode?: string;
+}
+export type WorkSessionSelection = ({
+    mode: 'create';
+    projectId: string;
+} & Omit<WorkSessionSettings, 'projectId'>) | {
+    mode: 'attach';
+    sessionId: string;
+};
+export interface WorkSessionLoadedSession {
+    id: string;
+    title: string;
+    status: 'idle' | 'running';
+    settings: WorkSessionSettings;
+    projectLabel?: string;
+    modelLabel?: string;
+}
+export interface WorkSessionCatalog {
+    revision: string;
+    provider: string;
+    canCreate: boolean;
+    canAttach: boolean;
+    projects: WorkSessionChoice[];
+    models?: WorkSessionModelChoice[];
+    reasoningEfforts?: WorkSessionChoice[];
+    permissionModes?: WorkSessionChoice[];
+    executionModes?: WorkSessionChoice[];
+    defaults?: WorkSessionSettings;
+    sessions: WorkSessionLoadedSession[];
+}
+export interface WorkSessionRuntimeIdentity {
+    hostId: string;
+    runtimeEpoch: string;
+}
+export interface WorkSessionRuntimeLease extends WorkSessionRuntimeIdentity {
+    /** Agent-only fencing credential. Never expose in the owner catalog or request status. */
+    leaseToken: string;
+    expiresAt: number;
+}
+export interface WorkSessionRuntimeRegistration extends WorkSessionRuntimeIdentity {
+    displayName: string;
+    catalog: WorkSessionCatalog;
+}
+export interface WorkSessionBinding {
+    workSessionId: string;
+    conversationId: string;
+    hostId: string;
+    provider: string;
+    nativeSessionId: string;
+    settings: WorkSessionSettings;
+    createdAt: number;
+}
+export interface WorkSessionRuntimeState {
+    ownerId: string;
+    lease: WorkSessionRuntimeLease;
+    bindings: WorkSessionBinding[];
+}
+export interface WorkSessionCatalogResult {
+    status: 'available' | 'offline' | 'unavailable';
+    agentId: string;
+    hostId?: string;
+    runtimeEpoch?: string;
+    displayName?: string;
+    expiresAt?: number;
+    catalog?: WorkSessionCatalog;
+    bindings: WorkSessionBinding[];
+}
+export interface RequestWorkSessionInput extends WorkSessionRuntimeIdentity {
+    agentId: string;
+    conversationId: string;
+    requestId: string;
+    catalogRevision: string;
+    selection: WorkSessionSelection;
+}
+export type WorkSessionRequestStatus = 'pending' | 'claimed' | 'attached' | 'failed' | 'uncertain' | 'expired';
+export interface WorkSessionRequest extends RequestWorkSessionInput {
+    schema: typeof WORK_SESSION_SCHEMA;
+    requestedBy: string;
+    status: WorkSessionRequestStatus;
+    createdAt: number;
+    updatedAt: number;
+    expiresAt: number;
+    binding?: WorkSessionBinding;
+    error?: {
+        code: string;
+        message: string;
+    };
+}
+export type WorkSessionCompletion = {
+    status: 'attached';
+    nativeSessionId: string;
+    settings: WorkSessionSettings;
+} | {
+    status: 'failed' | 'uncertain';
+    error: {
+        code: string;
+        message: string;
+    };
+};
+export type WorkSessionRuntimeAuth = Pick<WorkSessionRuntimeLease, 'hostId' | 'runtimeEpoch' | 'leaseToken'>;
+export interface WorkSessionClaimInput extends WorkSessionRuntimeAuth {
+    requestId?: string;
+}
+export interface WorkSessionClaimResult {
+    request: WorkSessionRequest | null;
+    /** Previously claimed: reconcile the durable host journal, never blindly execute again. */
+    replayed: boolean;
+}
+export interface CompleteWorkSessionInput extends WorkSessionRuntimeAuth {
+    requestId: string;
+    result: WorkSessionCompletion;
+}
+export interface WorkSessionHeartbeatInput extends WorkSessionRuntimeAuth {
+    catalog?: WorkSessionCatalog;
+}
+export interface ReleaseWorkSessionBindingInput extends WorkSessionRuntimeAuth {
+    conversationId: string;
+    workSessionId: string;
+}
+export interface ResolveWorkSessionRequestInput {
+    agentId: string;
+    requestId: string;
+}
+export interface GetWorkSessionRequestInput {
+    agentId: string;
+    /** Exactly one selector. Conversation lookup recovers the latest operation after reload. */
+    requestId?: string;
+    conversationId?: string;
+}
+export declare function workSessionId(value: unknown, label?: string): string;
+export declare function parseWorkSessionSettings(value: unknown): WorkSessionSettings;
+export declare function parseWorkSessionCatalog(value: unknown): WorkSessionCatalog;
+export declare function parseWorkSessionSelection(value: unknown): WorkSessionSelection;
+export declare function assertWorkSessionSelectionAvailable(selection: WorkSessionSelection, catalog: WorkSessionCatalog): void;
+export declare function parseWorkSessionRuntimeRegistration(value: unknown): WorkSessionRuntimeRegistration;
+export declare function parseWorkSessionRuntimeAuth(value: unknown, extraKeys?: string[]): WorkSessionRuntimeAuth;
+export declare function parseRequestWorkSessionInput(value: unknown): RequestWorkSessionInput;
+export declare function parseWorkSessionCompletion(value: unknown): WorkSessionCompletion;

package/dist/workSessions.js

@@ -0,0 +1,150 @@
+/** Private owner/operator workflow. None of this catalog belongs in public runtime descriptors. */
+export const WORK_SESSION_SCHEMA = 'canon.work-sessions.v1';
+export const WORK_SESSION_LEASE_MS = 90_000;
+export const WORK_SESSION_REQUEST_TTL_MS = 5 * 60_000;
+const SETTINGS_KEYS = ['projectId', 'modelId', 'reasoningEffort', 'permissionMode', 'executionMode'];
+function object(value, keys, label) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        throw new Error(`Invalid ${label}`);
+    const result = value;
+    if (Object.keys(result).some((key) => !keys.includes(key)))
+        throw new Error(`Unsupported ${label} field`);
+    return result;
+}
+export function workSessionId(value, label = 'identifier') {
+    if (typeof value !== 'string' || !/^[A-Za-z0-9_.:-]{1,160}$/.test(value))
+        throw new Error(`Invalid ${label}`);
+    return value;
+}
+function label(value, name, max = 160) {
+    if (typeof value !== 'string' || !value.trim() || value.length > max)
+        throw new Error(`Invalid ${name}`);
+    return value.trim();
+}
+export function parseWorkSessionSettings(value) {
+    const input = object(value, SETTINGS_KEYS, 'settings');
+    return Object.fromEntries(Object.entries(input).map(([key, value]) => [key, workSessionId(value, key)]));
+}
+function choices(value, models = false) {
+    if (!Array.isArray(value) || value.length > 128)
+        throw new Error('Invalid choices');
+    const ids = new Set();
+    return value.map((entry) => {
+        const input = object(entry, ['id', 'label', 'description', ...(models ? ['reasoningEfforts', 'defaultReasoningEffort'] : [])], 'choice');
+        const id = workSessionId(input.id);
+        if (ids.has(id))
+            throw new Error('Duplicate choice identifier');
+        ids.add(id);
+        const result = { id, label: label(input.label, 'choice label') };
+        if (input.description !== undefined)
+            result.description = label(input.description, 'choice description', 512);
+        if (input.reasoningEfforts !== undefined)
+            result.reasoningEfforts = choices(input.reasoningEfforts);
+        if (input.defaultReasoningEffort !== undefined) {
+            result.defaultReasoningEffort = workSessionId(input.defaultReasoningEffort);
+            if (!result.reasoningEfforts?.some((choice) => choice.id === result.defaultReasoningEffort))
+                throw new Error('Invalid default reasoning effort');
+        }
+        return result;
+    });
+}
+export function parseWorkSessionCatalog(value) {
+    const input = object(value, ['revision', 'provider', 'canCreate', 'canAttach', 'projects', 'models', 'reasoningEfforts', 'permissionModes', 'executionModes', 'defaults', 'sessions'], 'catalog');
+    if (typeof input.canCreate !== 'boolean' || typeof input.canAttach !== 'boolean')
+        throw new Error('Invalid catalog capabilities');
+    if (!Array.isArray(input.sessions) || input.sessions.length > 128)
+        throw new Error('Invalid loaded sessions');
+    const ids = new Set();
+    const result = {
+        revision: workSessionId(input.revision, 'catalog revision'), provider: workSessionId(input.provider, 'provider'),
+        canCreate: input.canCreate, canAttach: input.canAttach, projects: choices(input.projects),
+        sessions: input.sessions.map((entry) => {
+            const session = object(entry, ['id', 'title', 'status', 'settings', 'projectLabel', 'modelLabel'], 'loaded session');
+            const id = workSessionId(session.id, 'session identifier');
+            if (ids.has(id))
+                throw new Error('Duplicate loaded session');
+            ids.add(id);
+            if (session.status !== 'idle' && session.status !== 'running')
+                throw new Error('Invalid session status');
+            return {
+                id, title: label(session.title, 'session title'), status: session.status,
+                settings: parseWorkSessionSettings(session.settings),
+                ...(session.projectLabel !== undefined ? { projectLabel: label(session.projectLabel, 'project label') } : {}),
+                ...(session.modelLabel !== undefined ? { modelLabel: label(session.modelLabel, 'model label') } : {}),
+            };
+        }),
+    };
+    for (const key of ['models', 'reasoningEfforts', 'permissionModes', 'executionModes']) {
+        if (input[key] !== undefined)
+            result[key] = choices(input[key], key === 'models');
+    }
+    if (input.defaults !== undefined)
+        result.defaults = parseWorkSessionSettings(input.defaults);
+    if (result.canCreate && !result.projects.length)
+        throw new Error('Creating sessions requires an advertised project');
+    if (JSON.stringify(result).length > 65_536)
+        throw new Error('Work session catalog is too large');
+    return result;
+}
+export function parseWorkSessionSelection(value) {
+    const mode = value?.mode;
+    if (mode === 'attach') {
+        const input = object(value, ['mode', 'sessionId'], 'attach selection');
+        return { mode, sessionId: workSessionId(input.sessionId, 'session identifier') };
+    }
+    if (mode === 'create') {
+        const { mode: _mode, ...settings } = object(value, ['mode', ...SETTINGS_KEYS], 'create selection');
+        return { mode, ...parseWorkSessionSettings(settings), projectId: workSessionId(settings.projectId, 'project identifier') };
+    }
+    throw new Error('Invalid work session selection');
+}
+export function assertWorkSessionSelectionAvailable(selection, catalog) {
+    if (selection.mode === 'attach') {
+        if (!catalog.canAttach || !catalog.sessions.some((session) => session.id === selection.sessionId))
+            throw new Error('Selected loaded session is unavailable');
+        return;
+    }
+    if (!catalog.canCreate || !catalog.projects.some((project) => project.id === selection.projectId))
+        throw new Error('Selected project is unavailable');
+    const modelId = selection.modelId ?? catalog.defaults?.modelId;
+    const model = catalog.models?.find((choice) => choice.id === modelId);
+    const available = {
+        modelId: catalog.models, reasoningEffort: model?.reasoningEfforts ?? catalog.reasoningEfforts,
+        permissionMode: catalog.permissionModes, executionMode: catalog.executionModes,
+    };
+    for (const key of ['modelId', 'reasoningEffort', 'permissionMode', 'executionMode']) {
+        if (selection[key] !== undefined && !available[key]?.some((choice) => choice.id === selection[key]))
+            throw new Error(`Selected ${key} is unavailable`);
+    }
+}
+export function parseWorkSessionRuntimeRegistration(value) {
+    const input = object(value, ['hostId', 'runtimeEpoch', 'displayName', 'catalog'], 'runtime registration');
+    return { hostId: workSessionId(input.hostId), runtimeEpoch: workSessionId(input.runtimeEpoch), displayName: label(input.displayName, 'host name'), catalog: parseWorkSessionCatalog(input.catalog) };
+}
+export function parseWorkSessionRuntimeAuth(value, extraKeys = []) {
+    const input = object(value, ['hostId', 'runtimeEpoch', 'leaseToken', ...extraKeys], 'runtime request');
+    return { hostId: workSessionId(input.hostId), runtimeEpoch: workSessionId(input.runtimeEpoch), leaseToken: workSessionId(input.leaseToken, 'lease token') };
+}
+export function parseRequestWorkSessionInput(value) {
+    const input = object(value, ['agentId', 'conversationId', 'requestId', 'hostId', 'runtimeEpoch', 'catalogRevision', 'selection'], 'work session request');
+    if (typeof input.requestId !== 'string' || !/^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(input.requestId))
+        throw new Error('requestId must be a UUID');
+    return {
+        agentId: workSessionId(input.agentId), conversationId: workSessionId(input.conversationId), requestId: input.requestId,
+        hostId: workSessionId(input.hostId), runtimeEpoch: workSessionId(input.runtimeEpoch), catalogRevision: workSessionId(input.catalogRevision),
+        selection: parseWorkSessionSelection(input.selection),
+    };
+}
+export function parseWorkSessionCompletion(value) {
+    const status = value?.status;
+    if (status === 'attached') {
+        const input = object(value, ['status', 'nativeSessionId', 'settings'], 'attached result');
+        return { status, nativeSessionId: workSessionId(input.nativeSessionId), settings: parseWorkSessionSettings(input.settings) };
+    }
+    if (status === 'failed' || status === 'uncertain') {
+        const input = object(value, ['status', 'error'], 'failure result');
+        const error = object(input.error, ['code', 'message'], 'failure');
+        return { status, error: { code: workSessionId(error.code), message: label(error.message, 'failure message', 512) } };
+    }
+    throw new Error('Invalid work session result');
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@canonmsg/backend-contracts",
-  "version": "8.2.0",
+  "version": "8.4.0",
   "description": "Canon backend contract helpers shared by Functions and stream-service",
   "type": "module",
   "main": "dist/cjs/index.js",
@@ -33,21 +33,19 @@
     "contracts",
     "wire"
   ],
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/HeyBobChan/canon",
-    "directory": "packages/backend-contracts"
-  },
-  "homepage": "https://github.com/HeyBobChan/canon/tree/main/packages/backend-contracts",
+  "homepage": "https://canonmail.com/agents/contracts",
   "publishConfig": {
     "access": "public"
   },
   "devDependencies": {
-    "@canonmsg/rich-cards": "^0.10.3",
+    "@canonmsg/rich-cards": "^0.10.5",
     "@types/node": "^22.0.0",
     "ajv": "^8.20.0",
     "typescript": "~5.7.0",
     "vitest": "^4.1.8"
   },
-  "license": "MIT"
+  "license": "MIT",
+  "bugs": {
+    "url": "https://canonmail.com/support"
+  }
 }