@canonmsg/backend-contracts 8.3.0 → 8.5.0

package/dist/canon-verbs.schema.json

@@ -1427,7 +1427,6 @@
       "type": "object",
       "description": "Create a group conversation. Each target's groupJoinPolicy is enforced server-side with staged admission: directly-addable members join at creation, approval-required members become pending group_invite requests; hard-denied members are skipped (see the result). A creator-only group is valid when at least one requested member has a pending invite. Under MLS, membership changes are Add/Remove proposals + Commit — a group operation is a cryptographic state change, not a codec swap.",
       "required": [
-        "name",
         "memberIds"
       ],
       "additionalProperties": false,

package/dist/cjs/conversationMembership.js

@@ -0,0 +1,48 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.normalizeConversationRole = normalizeConversationRole;
+exports.isConversationAdminRole = isConversationAdminRole;
+exports.readMembershipRevision = readMembershipRevision;
+exports.resolveConversationPolicyScope = resolveConversationPolicyScope;
+exports.buildConversationParticipantSummary = buildConversationParticipantSummary;
+exports.readConversationInvitationPolicy = readConversationInvitationPolicy;
+const communication_js_1 = require("./communication.js");
+/** `owner` is a read-only legacy spelling, never superior to another admin. */
+function normalizeConversationRole(value) {
+    return value === 'admin' || value === 'owner' ? 'admin' : value === 'member' ? 'member' : null;
+}
+function isConversationAdminRole(value) {
+    return normalizeConversationRole(value) === 'admin';
+}
+function readMembershipRevision(value) {
+    return typeof value === 'number' && Number.isSafeInteger(value) && value >= 0 ? value : 0;
+}
+/** Behavioral scope follows the current roster, never the legacy shape label. */
+function resolveConversationPolicyScope(memberIdsOrCount) {
+    const count = Array.isArray(memberIdsOrCount)
+        ? new Set(memberIdsOrCount.filter((id) => typeof id === 'string' && id.length > 0)).size
+        : memberIdsOrCount;
+    if (typeof count !== 'number' || !Number.isSafeInteger(count))
+        return 'unknown';
+    return count === 2 ? 'direct' : count > 2 ? 'group' : 'unknown';
+}
+function buildConversationParticipantSummary(participants) {
+    const participantTypes = Object.fromEntries(participants.map(({ userId, userType }) => [userId, userType === 'ai_agent' ? 'ai_agent' : 'human']));
+    const types = Object.values(participantTypes);
+    const agentCount = types.filter((type) => type === 'ai_agent').length;
+    return {
+        participantTypes,
+        participantSummary: { humanCount: types.length - agentCount, agentCount, totalCount: types.length },
+        isAgentChat: agentCount > 0,
+    };
+}
+/** Legacy fields are compatibility inputs to one conservative invitation policy. */
+function readConversationInvitationPolicy(data) {
+    const inbound = (0, communication_js_1.readCommunicationRule)(data?.inboundPolicy);
+    const group = (0, communication_js_1.readCommunicationRule)(data?.groupJoinPolicy);
+    if (inbound === 'closed' || group === 'closed')
+        return 'closed';
+    if (inbound === 'approval-required' || group === 'approval-required')
+        return 'approval-required';
+    return 'open';
+}

package/dist/cjs/index.js

@@ -36,3 +36,5 @@ __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);
+__exportStar(require("./conversationMembership.js"), exports);

package/dist/cjs/verbSchemas.js

@@ -787,7 +787,7 @@ const create_group_input = {
         + 'pending invite. Under MLS, membership '
         + 'changes are Add/Remove proposals + Commit — a group operation is a '
         + 'cryptographic state change, not a codec swap.',
-    required: ['name', 'memberIds'],
+    required: ['memberIds'],
     additionalProperties: false,
     properties: {
         name: { type: 'string', minLength: 1, maxLength: verbContract_js_1.VERB_LIMITS.groupNameChars },

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

@@ -1,3 +1,4 @@
+import type { ListConversationsResult } from './verbContract.js';
 import type { DiscoverAgentsInput, DiscoverAgentsResult } from './agentDirectory.js';
 /** The deliberately small policy vocabulary for principal communication. */
 export type CommunicationRule = 'open' | 'approval-required' | 'closed';
@@ -20,14 +21,14 @@ export type CommunicateInput = ({
     text: string;
     messageId?: string;
 } | {
-    action: 'start_direct';
+    action: 'start_direct' | 'start_conversation';
     principalId: string;
     text: string;
     selection?: DirectConversationSelection;
     messageId?: string;
 } | {
-    action: 'create_group';
-    name: string;
+    action: 'create_group' | 'create_conversation';
+    name?: string;
     memberIds: string[];
 } | {
     action: 'forward_message';
@@ -42,12 +43,23 @@ export type CommunicateInput = ({
     text?: string;
     messageId?: string;
 } | {
-    action: 'manage_group_members';
+    action: 'manage_group_members' | 'manage_participants';
     conversationId: string;
     userId: string;
     operation: 'add' | 'remove';
+} | {
+    action: 'list_conversations';
+    limit?: number;
+} | {
+    action: 'leave_conversation';
+    conversationId: string;
 };
 export type CommunicateResult = ({
+    status: 'listed';
+} & ListConversationsResult) | {
+    status: 'left';
+    conversationId: string;
+} | ({
     status: 'discovered';
 } & DiscoverAgentsResult) | {
     status: 'messaged';

package/dist/conversationMembership.d.ts

@@ -0,0 +1,28 @@
+import { type CommunicationRule } from './communication.js';
+/** Shared social membership semantics; presentation and runtime ownership are separate. */
+export type ConversationRole = 'admin' | 'member';
+export type ConversationParticipantType = 'human' | 'ai_agent';
+export interface ConversationParticipantSummary {
+    humanCount: number;
+    agentCount: number;
+    totalCount: number;
+}
+/** `owner` is a read-only legacy spelling, never superior to another admin. */
+export declare function normalizeConversationRole(value: unknown): ConversationRole | null;
+export declare function isConversationAdminRole(value: unknown): boolean;
+export declare function readMembershipRevision(value: unknown): number;
+/** Behavioral scope follows the current roster, never the legacy shape label. */
+export declare function resolveConversationPolicyScope(memberIdsOrCount: unknown): 'direct' | 'group' | 'unknown';
+export declare function buildConversationParticipantSummary(participants: readonly {
+    userId: string;
+    userType: unknown;
+}[]): {
+    participantTypes: Record<string, ConversationParticipantType>;
+    participantSummary: ConversationParticipantSummary;
+    isAgentChat: boolean;
+};
+/** Legacy fields are compatibility inputs to one conservative invitation policy. */
+export declare function readConversationInvitationPolicy(data: {
+    inboundPolicy?: unknown;
+    groupJoinPolicy?: unknown;
+} | null | undefined): CommunicationRule;

package/dist/conversationMembership.js

@@ -0,0 +1,40 @@
+import { readCommunicationRule } from './communication.js';
+/** `owner` is a read-only legacy spelling, never superior to another admin. */
+export function normalizeConversationRole(value) {
+    return value === 'admin' || value === 'owner' ? 'admin' : value === 'member' ? 'member' : null;
+}
+export function isConversationAdminRole(value) {
+    return normalizeConversationRole(value) === 'admin';
+}
+export function readMembershipRevision(value) {
+    return typeof value === 'number' && Number.isSafeInteger(value) && value >= 0 ? value : 0;
+}
+/** Behavioral scope follows the current roster, never the legacy shape label. */
+export function resolveConversationPolicyScope(memberIdsOrCount) {
+    const count = Array.isArray(memberIdsOrCount)
+        ? new Set(memberIdsOrCount.filter((id) => typeof id === 'string' && id.length > 0)).size
+        : memberIdsOrCount;
+    if (typeof count !== 'number' || !Number.isSafeInteger(count))
+        return 'unknown';
+    return count === 2 ? 'direct' : count > 2 ? 'group' : 'unknown';
+}
+export function buildConversationParticipantSummary(participants) {
+    const participantTypes = Object.fromEntries(participants.map(({ userId, userType }) => [userId, userType === 'ai_agent' ? 'ai_agent' : 'human']));
+    const types = Object.values(participantTypes);
+    const agentCount = types.filter((type) => type === 'ai_agent').length;
+    return {
+        participantTypes,
+        participantSummary: { humanCount: types.length - agentCount, agentCount, totalCount: types.length },
+        isAgentChat: agentCount > 0,
+    };
+}
+/** Legacy fields are compatibility inputs to one conservative invitation policy. */
+export function readConversationInvitationPolicy(data) {
+    const inbound = readCommunicationRule(data?.inboundPolicy);
+    const group = readCommunicationRule(data?.groupJoinPolicy);
+    if (inbound === 'closed' || group === 'closed')
+        return 'closed';
+    if (inbound === 'approval-required' || group === 'approval-required')
+        return 'approval-required';
+    return 'open';
+}

package/dist/index.d.ts

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

package/dist/index.js

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

package/dist/replyAuthority.d.ts

@@ -9,4 +9,6 @@ export interface AgentReplyAuthorityV1 {
     sourceMessageId: string;
     token: string;
     expiresAt: string;
+    /** Agent membership admission at issuance; absent/null only for legacy membership. */
+    admissionId?: string | null;
 }

package/dist/verbContract.d.ts

@@ -580,8 +580,8 @@ export interface ForwardResult {
     forwardedFrom?: unknown;
 }
 export interface CreateGroupInput {
-    /** Group name (authoring cap VERB_LIMITS.groupNameChars). */
-    name: string;
+    /** Optional conversation title (authoring cap VERB_LIMITS.groupNameChars). */
+    name?: string;
     /** Other members; the caller is added automatically. Cap
      * VERB_LIMITS.groupMembers including the creator. Each target's
      * groupJoinPolicy is enforced server-side. */
@@ -658,6 +658,17 @@ export interface VerbConversationSummary {
     name?: string | null;
     topic: string | null;
     memberIds: string[];
+    membershipModel?: 'unified';
+    membershipRevision?: number;
+    participantTypes?: Record<string, 'human' | 'ai_agent'>;
+    participantSummary?: {
+        humanCount: number;
+        agentCount: number;
+        totalCount: number;
+    };
+    runtimeSessionKind?: 'direct' | 'group';
+    admissionId?: string | null;
+    historyStartAt?: string | null;
     isAgentChat: boolean;
     hasUnread?: boolean;
     lastMessage: {

package/dist/verbSchemas.d.ts

@@ -1298,7 +1298,7 @@ export declare const CANON_VERBS_JSON_SCHEMA: {
         readonly create_group_input: {
             readonly type: "object";
             readonly description: string;
-            readonly required: readonly ["name", "memberIds"];
+            readonly required: readonly ["memberIds"];
             readonly additionalProperties: false;
             readonly properties: {
                 readonly name: {

package/dist/verbSchemas.js

@@ -782,7 +782,7 @@ const create_group_input = {
         + 'pending invite. Under MLS, membership '
         + 'changes are Add/Remove proposals + Commit — a group operation is a '
         + 'cryptographic state change, not a codec swap.',
-    required: ['name', 'memberIds'],
+    required: ['memberIds'],
     additionalProperties: false,
     properties: {
         name: { type: 'string', minLength: 1, maxLength: VERB_LIMITS.groupNameChars },

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.3.0",
+  "version": "8.5.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"
+  }
 }