@canonmsg/backend-contracts 8.1.1 → 8.3.0

package/dist/cjs/index.js

@@ -17,6 +17,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./diffRedaction.js"), exports);
 __exportStar(require("./environment.js"), exports);
 __exportStar(require("./media.js"), exports);
+__exportStar(require("./media-url.js"), exports);
 __exportStar(require("./message.js"), exports);
 __exportStar(require("./messageText.js"), exports);
 __exportStar(require("./runtimeCardFields.js"), exports);
@@ -34,3 +35,4 @@ __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);

package/dist/cjs/media-origins.generated.js

@@ -0,0 +1,8 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MEDIA_ORIGINS = void 0;
+// Generated by scripts/sync-runtime-endpoints.mjs from canonical endpoints and storage policies.
+exports.MEDIA_ORIGINS = {
+    "canonmail-dev.firebasestorage.app": "https://dev.api.canonmail.com",
+    "canonmail-prod.firebasestorage.app": "https://api.canonmail.com"
+};

package/dist/cjs/media-url.js

@@ -0,0 +1,62 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildFirebaseMediaUrl = buildFirebaseMediaUrl;
+exports.buildMediaDownloadUrl = buildMediaDownloadUrl;
+exports.parseMediaStoragePath = parseMediaStoragePath;
+exports.canonMediaDownloadUrl = canonMediaDownloadUrl;
+const media_js_1 = require("./media.js");
+const media_origins_generated_js_1 = require("./media-origins.generated.js");
+function buildFirebaseMediaUrl(bucket, storagePath, token) {
+    return `https://firebasestorage.googleapis.com/v0/b/${encodeURIComponent(bucket)}/o/${encodeURIComponent(storagePath)}?alt=media&token=${encodeURIComponent(token)}`;
+}
+function validMediaPath(path) {
+    const parts = path.split('/');
+    return parts.length === 4 && parts[0] === 'media'
+        && parts.every((part) => Boolean(part) && part !== '.' && part !== '..' && !/[\u0000-\u001f\u007f\\]/.test(part));
+}
+function buildMediaDownloadUrl(bucket, storagePath, token) {
+    const origin = media_origins_generated_js_1.MEDIA_ORIGINS[bucket];
+    if (!origin || !validMediaPath(storagePath))
+        return buildFirebaseMediaUrl(bucket, storagePath, token);
+    return `${origin}/files/${storagePath.split('/').slice(1).map(encodeURIComponent).join('/')}?token=${encodeURIComponent(token)}`;
+}
+/** Accept historical Firebase URLs and Canon links, only for the expected bucket. */
+function parseMediaStoragePath(value, bucket) {
+    if (typeof value !== 'string')
+        return null;
+    try {
+        const url = new URL(value);
+        if (url.protocol !== 'https:' || url.username || url.password)
+            return null;
+        let path;
+        const prefix = `/v0/b/${bucket}/o/`;
+        if (url.origin === 'https://firebasestorage.googleapis.com' && url.pathname.startsWith(prefix)) {
+            path = decodeURIComponent(url.pathname.slice(prefix.length));
+        }
+        else if (url.origin === media_origins_generated_js_1.MEDIA_ORIGINS[bucket] && url.pathname.startsWith('/files/')) {
+            path = `media/${decodeURIComponent(url.pathname.slice('/files/'.length))}`;
+        }
+        else
+            return null;
+        return validMediaPath(path) ? path : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Presentation upgrade for existing messages without rewriting their stored URLs. */
+function canonMediaDownloadUrl(value, downloadFileName) {
+    for (const bucket of Object.keys(media_origins_generated_js_1.MEDIA_ORIGINS)) {
+        const path = parseMediaStoragePath(value, bucket);
+        if (path) {
+            const token = new URL(value).searchParams.get('token');
+            if (token) {
+                const url = new URL(buildMediaDownloadUrl(bucket, path, token));
+                if (downloadFileName !== undefined)
+                    url.searchParams.set('download', (0, media_js_1.sanitizeDownloadFileName)(downloadFileName));
+                return url.href;
+            }
+        }
+    }
+    return value;
+}

package/dist/cjs/media.js

@@ -1,11 +1,56 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.MEDIA_CACHE_CONTROL = void 0;
+exports.sanitizeDownloadFileName = sanitizeDownloadFileName;
+exports.buildMediaContentDisposition = buildMediaContentDisposition;
+exports.processedVideoFileName = processedVideoFileName;
 exports.inferMediaAttachmentKind = inferMediaAttachmentKind;
 exports.getStoredFileExtension = getStoredFileExtension;
 exports.normalizeStoredAttachments = normalizeStoredAttachments;
 exports.getMessageAttachments = getMessageAttachments;
 exports.getPrimaryAttachment = getPrimaryAttachment;
 exports.describeAttachment = describeAttachment;
+/** Allow private conditional caching, but recheck access before every reuse. */
+exports.MEDIA_CACHE_CONTROL = 'private, max-age=0, must-revalidate';
+/** Preserve Unicode and the extension while removing unsafe filesystem characters. */
+function sanitizeDownloadFileName(value, fallback = 'attachment') {
+    const baseName = typeof value === 'string'
+        ? value.trim().split(/[\\/]/).filter(Boolean).pop() ?? ''
+        : '';
+    let name = Array.from(baseName, (char) => /^[\ud800-\udfff]$/.test(char) ? '-' : char).join('').normalize('NFC')
+        .replace(/[\u0000-\u001f\u007f<>:"/\\|?*\u202a-\u202e\u2066-\u2069]+/g, '-')
+        .replace(/\s+/g, ' ')
+        .replace(/^[. -]+|[. -]+$/g, '');
+    if (!name)
+        return sanitizeDownloadFileName(fallback, 'attachment');
+    if (/^(?:con|prn|aux|nul|com[1-9]|lpt[1-9])(?:\.|$)/i.test(name))
+        name = `_${name}`;
+    const extension = name.match(/\.[a-z0-9]{1,16}$/i)?.[0] ?? '';
+    const stem = extension ? name.slice(0, -extension.length) : name;
+    // Stay below filesystem byte limits as well as the display-length limit.
+    let safeStem = '';
+    let bytes = extension.length;
+    for (const char of Array.from(stem).slice(0, 120 - extension.length)) {
+        bytes += encodeURIComponent(char).replace(/%[0-9A-F]{2}|./g, '_').length;
+        if (bytes > 240)
+            break;
+        safeStem += char;
+    }
+    return `${safeStem.replace(/[. -]+$/g, '')}${extension}`;
+}
+/** RFC 6266: readable ASCII fallback plus the exact UTF-8 filename. */
+function buildMediaContentDisposition(input) {
+    const fileName = sanitizeDownloadFileName(input.fileName, input.fallbackFileName);
+    const asciiName = fileName.replace(/[^\x20-\x7e]|%/g, '_');
+    const encodedName = encodeURIComponent(fileName).replace(/['()*]/g, (char) => `%${char.charCodeAt(0).toString(16).toUpperCase()}`);
+    return `${input.disposition ?? 'attachment'}; filename="${asciiName}"`
+        + (fileName === asciiName ? '' : `; filename*=UTF-8''${encodedName}`);
+}
+/** The processor changes the container to MP4; keep its name consistent everywhere. */
+function processedVideoFileName(value) {
+    const stem = typeof value === 'string' ? value.trim().replace(/\.[a-z0-9]{1,16}$/i, '') : '';
+    return sanitizeDownloadFileName(`${stem || 'video'}.mp4`, 'video.mp4');
+}
 function inferMediaAttachmentKind(mimeType) {
     if (mimeType.startsWith('image/'))
         return 'image';

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/index.d.ts

@@ -1,6 +1,7 @@
 export * from './diffRedaction.js';
 export * from './environment.js';
 export * from './media.js';
+export * from './media-url.js';
 export * from './message.js';
 export * from './messageText.js';
 export * from './runtimeCardFields.js';
@@ -18,3 +19,4 @@ export * from './firestoreValues.js';
 export * from './moderation.js';
 export * from './selfContext.js';
 export * from './replyAuthority.js';
+export * from './runtimeDescriptor.js';

package/dist/index.js

@@ -1,6 +1,7 @@
 export * from './diffRedaction.js';
 export * from './environment.js';
 export * from './media.js';
+export * from './media-url.js';
 export * from './message.js';
 export * from './messageText.js';
 export * from './runtimeCardFields.js';
@@ -18,3 +19,4 @@ export * from './firestoreValues.js';
 export * from './moderation.js';
 export * from './selfContext.js';
 export * from './replyAuthority.js';
+export * from './runtimeDescriptor.js';

package/dist/media-origins.generated.d.ts

@@ -0,0 +1 @@
+export declare const MEDIA_ORIGINS: Readonly<Record<string, string>>;

package/dist/media-origins.generated.js

@@ -0,0 +1,5 @@
+// Generated by scripts/sync-runtime-endpoints.mjs from canonical endpoints and storage policies.
+export const MEDIA_ORIGINS = {
+    "canonmail-dev.firebasestorage.app": "https://dev.api.canonmail.com",
+    "canonmail-prod.firebasestorage.app": "https://api.canonmail.com"
+};

package/dist/media-url.d.ts

@@ -0,0 +1,6 @@
+export declare function buildFirebaseMediaUrl(bucket: string, storagePath: string, token: string): string;
+export declare function buildMediaDownloadUrl(bucket: string, storagePath: string, token: string): string;
+/** Accept historical Firebase URLs and Canon links, only for the expected bucket. */
+export declare function parseMediaStoragePath(value: unknown, bucket: string): string | null;
+/** Presentation upgrade for existing messages without rewriting their stored URLs. */
+export declare function canonMediaDownloadUrl(value: string, downloadFileName?: string): string;

package/dist/media-url.js

@@ -0,0 +1,56 @@
+import { sanitizeDownloadFileName } from './media.js';
+import { MEDIA_ORIGINS } from './media-origins.generated.js';
+export function buildFirebaseMediaUrl(bucket, storagePath, token) {
+    return `https://firebasestorage.googleapis.com/v0/b/${encodeURIComponent(bucket)}/o/${encodeURIComponent(storagePath)}?alt=media&token=${encodeURIComponent(token)}`;
+}
+function validMediaPath(path) {
+    const parts = path.split('/');
+    return parts.length === 4 && parts[0] === 'media'
+        && parts.every((part) => Boolean(part) && part !== '.' && part !== '..' && !/[\u0000-\u001f\u007f\\]/.test(part));
+}
+export function buildMediaDownloadUrl(bucket, storagePath, token) {
+    const origin = MEDIA_ORIGINS[bucket];
+    if (!origin || !validMediaPath(storagePath))
+        return buildFirebaseMediaUrl(bucket, storagePath, token);
+    return `${origin}/files/${storagePath.split('/').slice(1).map(encodeURIComponent).join('/')}?token=${encodeURIComponent(token)}`;
+}
+/** Accept historical Firebase URLs and Canon links, only for the expected bucket. */
+export function parseMediaStoragePath(value, bucket) {
+    if (typeof value !== 'string')
+        return null;
+    try {
+        const url = new URL(value);
+        if (url.protocol !== 'https:' || url.username || url.password)
+            return null;
+        let path;
+        const prefix = `/v0/b/${bucket}/o/`;
+        if (url.origin === 'https://firebasestorage.googleapis.com' && url.pathname.startsWith(prefix)) {
+            path = decodeURIComponent(url.pathname.slice(prefix.length));
+        }
+        else if (url.origin === MEDIA_ORIGINS[bucket] && url.pathname.startsWith('/files/')) {
+            path = `media/${decodeURIComponent(url.pathname.slice('/files/'.length))}`;
+        }
+        else
+            return null;
+        return validMediaPath(path) ? path : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Presentation upgrade for existing messages without rewriting their stored URLs. */
+export function canonMediaDownloadUrl(value, downloadFileName) {
+    for (const bucket of Object.keys(MEDIA_ORIGINS)) {
+        const path = parseMediaStoragePath(value, bucket);
+        if (path) {
+            const token = new URL(value).searchParams.get('token');
+            if (token) {
+                const url = new URL(buildMediaDownloadUrl(bucket, path, token));
+                if (downloadFileName !== undefined)
+                    url.searchParams.set('download', sanitizeDownloadFileName(downloadFileName));
+                return url.href;
+            }
+        }
+    }
+    return value;
+}

package/dist/media.d.ts

@@ -1,4 +1,16 @@
 export type MediaAttachmentKind = 'image' | 'audio' | 'video' | 'file';
+/** Allow private conditional caching, but recheck access before every reuse. */
+export declare const MEDIA_CACHE_CONTROL = "private, max-age=0, must-revalidate";
+/** Preserve Unicode and the extension while removing unsafe filesystem characters. */
+export declare function sanitizeDownloadFileName(value: unknown, fallback?: string): string;
+/** RFC 6266: readable ASCII fallback plus the exact UTF-8 filename. */
+export declare function buildMediaContentDisposition(input: {
+    fileName?: unknown;
+    fallbackFileName: string;
+    disposition?: 'inline' | 'attachment';
+}): string;
+/** The processor changes the container to MP4; keep its name consistent everywhere. */
+export declare function processedVideoFileName(value: unknown): string;
 /** Lifecycle for newly uploaded videos that are normalized server-side. */
 export type VideoProcessingStatus = 'processing' | 'ready' | 'failed';
 /** Stable, display-safe reasons for a terminal video processing failure. */
@@ -7,9 +19,9 @@ export interface MediaAttachment {
     kind: MediaAttachmentKind;
     url: string;
     /**
-     * Server-issued identity for a finalized resumable upload. The send path
+     * Server-issued identity for a finalized upload. The send path
      * uses this to retain temporary canonical media atomically with the message.
-     * Legacy/base64 uploads intentionally omit it.
+     * Older attachments and forwarded copies may omit it.
      */
     uploadId?: string;
     mimeType?: string;

package/dist/media.js

@@ -1,3 +1,44 @@
+/** Allow private conditional caching, but recheck access before every reuse. */
+export const MEDIA_CACHE_CONTROL = 'private, max-age=0, must-revalidate';
+/** Preserve Unicode and the extension while removing unsafe filesystem characters. */
+export function sanitizeDownloadFileName(value, fallback = 'attachment') {
+    const baseName = typeof value === 'string'
+        ? value.trim().split(/[\\/]/).filter(Boolean).pop() ?? ''
+        : '';
+    let name = Array.from(baseName, (char) => /^[\ud800-\udfff]$/.test(char) ? '-' : char).join('').normalize('NFC')
+        .replace(/[\u0000-\u001f\u007f<>:"/\\|?*\u202a-\u202e\u2066-\u2069]+/g, '-')
+        .replace(/\s+/g, ' ')
+        .replace(/^[. -]+|[. -]+$/g, '');
+    if (!name)
+        return sanitizeDownloadFileName(fallback, 'attachment');
+    if (/^(?:con|prn|aux|nul|com[1-9]|lpt[1-9])(?:\.|$)/i.test(name))
+        name = `_${name}`;
+    const extension = name.match(/\.[a-z0-9]{1,16}$/i)?.[0] ?? '';
+    const stem = extension ? name.slice(0, -extension.length) : name;
+    // Stay below filesystem byte limits as well as the display-length limit.
+    let safeStem = '';
+    let bytes = extension.length;
+    for (const char of Array.from(stem).slice(0, 120 - extension.length)) {
+        bytes += encodeURIComponent(char).replace(/%[0-9A-F]{2}|./g, '_').length;
+        if (bytes > 240)
+            break;
+        safeStem += char;
+    }
+    return `${safeStem.replace(/[. -]+$/g, '')}${extension}`;
+}
+/** RFC 6266: readable ASCII fallback plus the exact UTF-8 filename. */
+export function buildMediaContentDisposition(input) {
+    const fileName = sanitizeDownloadFileName(input.fileName, input.fallbackFileName);
+    const asciiName = fileName.replace(/[^\x20-\x7e]|%/g, '_');
+    const encodedName = encodeURIComponent(fileName).replace(/['()*]/g, (char) => `%${char.charCodeAt(0).toString(16).toUpperCase()}`);
+    return `${input.disposition ?? 'attachment'}; filename="${asciiName}"`
+        + (fileName === asciiName ? '' : `; filename*=UTF-8''${encodedName}`);
+}
+/** The processor changes the container to MP4; keep its name consistent everywhere. */
+export function processedVideoFileName(value) {
+    const stem = typeof value === 'string' ? value.trim().replace(/\.[a-z0-9]{1,16}$/i, '') : '';
+    return sanitizeDownloadFileName(`${stem || 'video'}.mp4`, 'video.mp4');
+}
 export function inferMediaAttachmentKind(mimeType) {
     if (mimeType.startsWith('image/'))
         return 'image';

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@canonmsg/backend-contracts",
-  "version": "8.1.1",
+  "version": "8.3.0",
   "description": "Canon backend contract helpers shared by Functions and stream-service",
   "type": "module",
   "main": "dist/cjs/index.js",