@canonmsg/backend-contracts 8.2.0 → 8.3.0

package/dist/cjs/index.js

@@ -35,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/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

@@ -19,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

@@ -19,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/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.2.0",
+  "version": "8.3.0",
   "description": "Canon backend contract helpers shared by Functions and stream-service",
   "type": "module",
   "main": "dist/cjs/index.js",