@canonmsg/core 0.3.0 → 0.5.0

package/dist/browser.d.ts

@@ -1,4 +1,6 @@
 export { AGENT_CAPABILITIES, } from './types.js';
 export type { AgentCapabilities, AgentClientType, AgentRuntime, MediaAttachment, MediaAttachmentKind, ModelOption, SessionConfig, WorkspaceOption, } from './types.js';
-export { DEFAULT_RUNTIME_CAPABILITIES, isTurnOpen, normalizeTurnMetadata, normalizeTurnState, resolveTurnMessageSemantics, shouldPromoteConversationMessage, shouldTriggerAgentTurn, } from './turn-protocol.js';
+export type { AgentBehaviorSettings, ParticipationHistoryMessage, ParticipationHistorySnapshot, ParticipationStyle, ResolvedAgentBehaviorPolicy, } from './policy.js';
+export { buildParticipationHistorySnapshot, buildParticipationHistorySnapshots, buildBehaviorPolicyLines, DEFAULT_PARTICIPATION_HISTORY_FETCH_LIMIT, evaluateParticipationPolicy, getDefaultParticipationPolicy, resolveAgentBehaviorPolicy, } from './policy.js';
+export { DEFAULT_RUNTIME_CAPABILITIES, FINAL_MESSAGE_HANDOFF_MS, isTurnOpen, normalizeTurnMetadata, normalizeTurnState, resolveTurnMessageSemantics, shouldPromoteConversationMessage, shouldTriggerAgentTurn, } from './turn-protocol.js';
 export type { DeliveryIntent, InboundDisposition, RuntimeCapabilities, TriggerDecision, TurnLifecycleState, TurnMessageSemantics, TurnMetadata, TurnState, } from './turn-protocol.js';

package/dist/browser.js

@@ -1,2 +1,3 @@
 export { AGENT_CAPABILITIES, } from './types.js';
-export { DEFAULT_RUNTIME_CAPABILITIES, isTurnOpen, normalizeTurnMetadata, normalizeTurnState, resolveTurnMessageSemantics, shouldPromoteConversationMessage, shouldTriggerAgentTurn, } from './turn-protocol.js';
+export { buildParticipationHistorySnapshot, buildParticipationHistorySnapshots, buildBehaviorPolicyLines, DEFAULT_PARTICIPATION_HISTORY_FETCH_LIMIT, evaluateParticipationPolicy, getDefaultParticipationPolicy, resolveAgentBehaviorPolicy, } from './policy.js';
+export { DEFAULT_RUNTIME_CAPABILITIES, FINAL_MESSAGE_HANDOFF_MS, isTurnOpen, normalizeTurnMetadata, normalizeTurnState, resolveTurnMessageSemantics, shouldPromoteConversationMessage, shouldTriggerAgentTurn, } from './turn-protocol.js';

package/dist/client.d.ts

@@ -1,4 +1,4 @@
-import { type CanonMessage, type CanonConversation, type AgentContext, type MediaAttachment, type SendMessageOptions, type CreateConversationOptions, type RegistrationStatus, type SetStreamingOptions } from './types.js';
+import { type CanonMessage, type CanonConversation, type CanonMessagesPage, type AgentContext, type MediaAttachment, type SendMessageOptions, type CreateConversationOptions, type RegistrationStatus, type SetStreamingOptions } from './types.js';
 import type { InboundDisposition } from './turn-protocol.js';
 /**
  * Thin REST client for Canon's agent API.
@@ -17,6 +17,7 @@ export declare class CanonClient {
     getAgentMe(): Promise<AgentContext>;
     getConversations(): Promise<CanonConversation[]>;
     getMessages(conversationId: string, limit?: number, before?: string): Promise<CanonMessage[]>;
+    getMessagesPage(conversationId: string, limit?: number, before?: string): Promise<CanonMessagesPage>;
     sendMessage(conversationId: string, text: string, options?: SendMessageOptions): Promise<{
         messageId: string;
     }>;
@@ -46,6 +47,7 @@ export declare class CanonClient {
         developerInfo: string;
         avatarUrl?: string;
         clientType?: string;
+        requestedAgentId?: string;
     }): Promise<{
         requestId: string;
     }>;

package/dist/client.js

@@ -53,6 +53,16 @@ export class CanonClient {
         const data = await res.json();
         return data.messages;
     }
+    async getMessagesPage(conversationId, limit = 50, before) {
+        const params = new URLSearchParams({ limit: String(limit) });
+        if (before)
+            params.set('before', before);
+        params.set('includeBehavior', '1');
+        const res = await fetch(`${this.baseUrl}/conversations/${conversationId}/messages?${params}`, { headers: this.authHeaders() });
+        if (!res.ok)
+            throw new CanonApiError(res.status, await res.text());
+        return res.json();
+    }
     async sendMessage(conversationId, text, options) {
         const res = await fetch(`${this.baseUrl}/messages/send`, {
             method: 'POST',

package/dist/execution-environment.d.ts

@@ -0,0 +1,59 @@
+import type { WorkspaceOption } from './types.js';
+export type ExecutionEnvironmentMode = 'worktree' | 'locked';
+export interface PreparedExecutionEnvironment {
+    cwd: string;
+    baseCwd: string;
+    mode: ExecutionEnvironmentMode;
+    repoRoot?: string;
+    branch?: string;
+    worktreePath?: string;
+    lockPath?: string;
+    reason?: string;
+}
+export declare class ExecutionEnvironmentError extends Error {
+    readonly userMessage: string;
+    constructor(message: string, userMessage?: string);
+}
+interface WorkspaceResolverOption {
+    id: string;
+    cwd: string;
+}
+export interface ConfiguredWorkspaceOption extends WorkspaceResolverOption {
+    label: string;
+}
+export interface SessionWorkspaceConfig {
+    workspaceId?: string;
+    legacyCwd?: string;
+    model?: string;
+}
+export declare function normalizeOptionalString(value: unknown): string | undefined;
+export declare function isEnabledFlag(value: unknown): boolean;
+export declare function buildConversationEnvironmentKey(conversationId: string, workspaceCwd: string): string;
+export declare function buildWorkspaceOptionId(workspaceCwd: string): string;
+export declare function buildConfiguredWorkspaceOptions(primaryCwd: string, configured: string[]): ConfiguredWorkspaceOption[];
+export declare function buildPublicWorkspaceOptions(workspaceOptions: Array<Pick<ConfiguredWorkspaceOption, 'id' | 'label'>>): WorkspaceOption[];
+export declare function readSessionWorkspaceConfig(raw: unknown): SessionWorkspaceConfig | null;
+export declare function resolveConfiguredWorkspaceCwd(input: {
+    workspaceOptions: WorkspaceResolverOption[];
+    config: {
+        workspaceId?: string;
+        legacyCwd?: string;
+    } | null;
+    defaultCwd: string;
+}): string;
+export declare function buildConversationWorktreeSpec(input: {
+    agentId: string;
+    conversationId: string;
+    workspaceCwd: string;
+}): {
+    branch: string;
+    worktreePath: string;
+};
+export declare function prepareConversationEnvironment(input: {
+    agentId: string;
+    conversationId: string;
+    workspaceCwd: string;
+    allowWorktrees?: boolean;
+}): PreparedExecutionEnvironment;
+export declare function releaseConversationEnvironment(environment: Pick<PreparedExecutionEnvironment, 'lockPath'>): void;
+export {};

package/dist/execution-environment.js

@@ -0,0 +1,284 @@
+import { spawnSync } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync, } from 'node:fs';
+import { basename, dirname, join, relative, resolve } from 'node:path';
+import { CANON_DIR, isProcessAlive } from './agent-profiles.js';
+export class ExecutionEnvironmentError extends Error {
+    userMessage;
+    constructor(message, userMessage = message) {
+        super(message);
+        this.name = 'ExecutionEnvironmentError';
+        this.userMessage = userMessage;
+    }
+}
+const WORKTREE_ROOT = join(CANON_DIR, 'conversation-worktrees');
+const WORKSPACE_LOCKS_ROOT = join(CANON_DIR, 'workspace-locks');
+export function normalizeOptionalString(value) {
+    if (typeof value !== 'string')
+        return undefined;
+    const trimmed = value.trim();
+    return trimmed ? trimmed : undefined;
+}
+export function isEnabledFlag(value) {
+    if (value === true)
+        return true;
+    if (typeof value !== 'string')
+        return false;
+    const normalized = value.trim().toLowerCase();
+    return normalized === '1' || normalized === 'true' || normalized === 'yes' || normalized === 'on';
+}
+function shortHash(value) {
+    return createHash('sha256').update(value).digest('hex').slice(0, 12);
+}
+function sanitizeSegment(value) {
+    const normalized = value
+        .toLowerCase()
+        .replace(/[^a-z0-9._-]+/g, '-')
+        .replace(/^-+|-+$/g, '');
+    return normalized.slice(0, 24) || 'workspace';
+}
+function runGit(cwd, args) {
+    const result = spawnSync('git', ['-C', cwd, ...args], {
+        encoding: 'utf-8',
+    });
+    return {
+        ok: result.status === 0,
+        stdout: result.stdout ?? '',
+        stderr: result.stderr ?? '',
+    };
+}
+function detectRepoRoot(cwd) {
+    const result = runGit(cwd, ['rev-parse', '--show-toplevel']);
+    if (!result.ok)
+        return null;
+    const repoRoot = result.stdout.trim();
+    return repoRoot ? resolve(repoRoot) : null;
+}
+function isRepoClean(repoRoot) {
+    const result = runGit(repoRoot, ['status', '--porcelain']);
+    return result.ok && result.stdout.trim() === '';
+}
+function branchExists(repoRoot, branch) {
+    return runGit(repoRoot, ['show-ref', '--verify', '--quiet', `refs/heads/${branch}`]).ok;
+}
+function loadWorkspaceLock(lockPath) {
+    try {
+        return JSON.parse(readFileSync(lockPath, 'utf-8'));
+    }
+    catch {
+        return null;
+    }
+}
+function cleanupStaleWorkspaceLock(lockPath) {
+    const record = loadWorkspaceLock(lockPath);
+    if (!record) {
+        try {
+            unlinkSync(lockPath);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    if (isProcessAlive(record.pid))
+        return false;
+    try {
+        unlinkSync(lockPath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function acquireWorkspaceLock(input) {
+    mkdirSync(WORKSPACE_LOCKS_ROOT, { recursive: true });
+    const workspaceCwd = resolve(input.workspaceCwd);
+    const lockPath = join(WORKSPACE_LOCKS_ROOT, `${shortHash(workspaceCwd)}.json`);
+    const record = {
+        pid: process.pid,
+        agentId: input.agentId,
+        conversationId: input.conversationId,
+        workspaceCwd,
+        createdAt: new Date().toISOString(),
+    };
+    while (true) {
+        try {
+            writeFileSync(lockPath, JSON.stringify(record, null, 2), { flag: 'wx' });
+            return lockPath;
+        }
+        catch (error) {
+            const code = error.code;
+            if (code !== 'EEXIST') {
+                throw error;
+            }
+            const existing = loadWorkspaceLock(lockPath);
+            if (!existing) {
+                if (cleanupStaleWorkspaceLock(lockPath))
+                    continue;
+                throw new Error(`Workspace lock file is unreadable: ${workspaceCwd}`);
+            }
+            if (!isProcessAlive(existing.pid)) {
+                if (cleanupStaleWorkspaceLock(lockPath))
+                    continue;
+            }
+            if (existing.pid === process.pid
+                && existing.agentId === input.agentId
+                && existing.conversationId === input.conversationId) {
+                return lockPath;
+            }
+            throw new ExecutionEnvironmentError(`Workspace is already in use by Canon session ${existing.conversationId.slice(0, 8)} (PID ${existing.pid}).`, 'That workspace is already in use by another Canon coding session on this machine.');
+        }
+    }
+}
+export function buildConversationEnvironmentKey(conversationId, workspaceCwd) {
+    return `${conversationId}:${resolve(workspaceCwd)}`;
+}
+export function buildWorkspaceOptionId(workspaceCwd) {
+    return `workspace-${shortHash(resolve(workspaceCwd))}`;
+}
+export function buildConfiguredWorkspaceOptions(primaryCwd, configured) {
+    const uniqueDirs = Array.from(new Set([primaryCwd, ...configured].map((dir) => resolve(dir))));
+    const seenLabels = new Map();
+    return uniqueDirs.map((cwd) => {
+        const baseLabel = basename(cwd) || cwd;
+        const seenCount = (seenLabels.get(baseLabel) ?? 0) + 1;
+        seenLabels.set(baseLabel, seenCount);
+        return {
+            id: buildWorkspaceOptionId(cwd),
+            label: seenCount === 1 ? baseLabel : `${baseLabel} (${seenCount})`,
+            cwd,
+        };
+    });
+}
+export function buildPublicWorkspaceOptions(workspaceOptions) {
+    return workspaceOptions.map(({ id, label }) => ({ id, label }));
+}
+export function readSessionWorkspaceConfig(raw) {
+    if (!raw || typeof raw !== 'object')
+        return null;
+    const data = raw;
+    return {
+        workspaceId: normalizeOptionalString(data.workspaceId),
+        legacyCwd: normalizeOptionalString(data.cwd),
+        model: normalizeOptionalString(data.model),
+    };
+}
+function findWorkspaceByLegacyCwd(workspaceOptions, legacyCwd) {
+    if (!legacyCwd)
+        return undefined;
+    const resolvedLegacyCwd = resolve(legacyCwd);
+    return workspaceOptions.find((workspace) => resolve(workspace.cwd) === resolvedLegacyCwd);
+}
+export function resolveConfiguredWorkspaceCwd(input) {
+    const fallbackCwd = input.workspaceOptions[0]?.cwd ?? resolve(input.defaultCwd);
+    if (!input.config)
+        return fallbackCwd;
+    const legacyWorkspace = findWorkspaceByLegacyCwd(input.workspaceOptions, input.config.legacyCwd);
+    const workspaceId = input.config.workspaceId;
+    if (workspaceId) {
+        const workspace = input.workspaceOptions.find((option) => option.id === workspaceId);
+        if (workspace)
+            return workspace.cwd;
+        if (workspaceId === 'default') {
+            return fallbackCwd;
+        }
+        const legacyWorkspaceMatch = /^workspace-(\d+)$/.exec(workspaceId);
+        if (legacyWorkspaceMatch) {
+            const legacyIndex = Number.parseInt(legacyWorkspaceMatch[1] ?? '', 10) - 1;
+            if (legacyIndex >= 0 && input.workspaceOptions[legacyIndex]) {
+                return input.workspaceOptions[legacyIndex].cwd;
+            }
+        }
+        if (legacyWorkspace)
+            return legacyWorkspace.cwd;
+        throw new ExecutionEnvironmentError(`Workspace ${workspaceId} is not configured on this machine.`, 'The workspace saved for this Canon coding session is no longer configured on this machine.');
+    }
+    if (legacyWorkspace)
+        return legacyWorkspace.cwd;
+    return fallbackCwd;
+}
+export function buildConversationWorktreeSpec(input) {
+    const resolvedWorkspace = resolve(input.workspaceCwd);
+    const baseLabel = sanitizeSegment(basename(resolvedWorkspace) || 'workspace');
+    const workspaceHash = shortHash(resolvedWorkspace);
+    const conversationHash = shortHash(`${input.agentId}:${input.conversationId}`);
+    return {
+        branch: `canon/${baseLabel}-${workspaceHash.slice(0, 6)}-${conversationHash.slice(0, 8)}`,
+        worktreePath: join(WORKTREE_ROOT, baseLabel, workspaceHash, conversationHash),
+    };
+}
+export function prepareConversationEnvironment(input) {
+    const baseCwd = resolve(input.workspaceCwd);
+    const allowWorktrees = input.allowWorktrees === true;
+    if (!allowWorktrees) {
+        return {
+            cwd: baseCwd,
+            baseCwd,
+            mode: 'locked',
+            lockPath: acquireWorkspaceLock({
+                agentId: input.agentId,
+                conversationId: input.conversationId,
+                workspaceCwd: baseCwd,
+            }),
+            reason: 'Worktree isolation is disabled for this host',
+        };
+    }
+    const repoRoot = detectRepoRoot(baseCwd);
+    if (repoRoot) {
+        const spec = buildConversationWorktreeSpec(input);
+        const relativeCwd = relative(repoRoot, baseCwd);
+        const sessionCwd = relativeCwd ? join(spec.worktreePath, relativeCwd) : spec.worktreePath;
+        if (existsSync(spec.worktreePath)) {
+            if (detectRepoRoot(spec.worktreePath)) {
+                return {
+                    cwd: sessionCwd,
+                    baseCwd,
+                    mode: 'worktree',
+                    repoRoot,
+                    branch: spec.branch,
+                    worktreePath: spec.worktreePath,
+                };
+            }
+        }
+        else if (isRepoClean(repoRoot)) {
+            mkdirSync(dirname(spec.worktreePath), { recursive: true });
+            const addArgs = branchExists(repoRoot, spec.branch)
+                ? ['worktree', 'add', spec.worktreePath, spec.branch]
+                : ['worktree', 'add', '-b', spec.branch, spec.worktreePath, 'HEAD'];
+            const addResult = runGit(repoRoot, addArgs);
+            if (addResult.ok && detectRepoRoot(spec.worktreePath)) {
+                return {
+                    cwd: sessionCwd,
+                    baseCwd,
+                    mode: 'worktree',
+                    repoRoot,
+                    branch: spec.branch,
+                    worktreePath: spec.worktreePath,
+                };
+            }
+        }
+    }
+    return {
+        cwd: baseCwd,
+        baseCwd,
+        mode: 'locked',
+        lockPath: acquireWorkspaceLock({
+            agentId: input.agentId,
+            conversationId: input.conversationId,
+            workspaceCwd: baseCwd,
+        }),
+        reason: repoRoot
+            ? 'Base repository is dirty or worktree creation failed'
+            : 'Workspace is not a git repository',
+    };
+}
+export function releaseConversationEnvironment(environment) {
+    if (!environment.lockPath)
+        return;
+    try {
+        unlinkSync(environment.lockPath);
+    }
+    catch {
+        // Ignore lock cleanup failures; stale locks are cleaned up on next acquire.
+    }
+}

package/dist/index.d.ts

@@ -1,10 +1,11 @@
 export { AGENT_CAPABILITIES, } from './types.js';
-export type { AgentCapabilities, AgentClientType, CanonMessage, CanonConversation, AgentContext, MediaAttachment, MediaAttachmentKind, MessageCreatedPayload, TypingPayload, PresencePayload, SendMessageOptions, CreateConversationOptions, RegistrationInput, RegistrationResult, RegistrationStatus, StreamingStatus, SetStreamingOptions, SessionControl, SessionState, SessionConfig, AgentRuntime, ModelOption, WorkspaceOption, } from './types.js';
+export type { AgentCapabilities, AgentClientType, CanonMessage, CanonConversation, CanonMessagesPage, AgentContext, MediaAttachment, MediaAttachmentKind, MessageCreatedPayload, TypingPayload, PresencePayload, SendMessageOptions, CreateConversationOptions, RegistrationInput, RegistrationResult, RegistrationStatus, StreamingStatus, SetStreamingOptions, SessionControl, SessionState, SessionConfig, AgentRuntime, ModelOption, WorkspaceOption, } from './types.js';
 export { CanonClient, CanonApiError } from './client.js';
 export { CanonStream } from './stream.js';
 export type { StreamHandler } from './stream.js';
-export type { PolicyRole, ParticipationStyle, RepresentationMode, PermissionLevel, ConversationScope, Participant, Relationship, ContextOverlay, BehaviorProfile, AdmissionPolicy, RuntimeControlPolicy, ActionApprovalPolicy, ParticipationPolicy, WorkSession, ResolvedPolicy, ResolvedTurnEligibility, } from './policy.js';
-export { DEFAULT_RUNTIME_CAPABILITIES, isTurnOpen, normalizeTurnMetadata, normalizeTurnState, resolveTurnMessageSemantics, shouldPromoteConversationMessage, shouldTriggerAgentTurn, } from './turn-protocol.js';
+export type { PolicyRole, ParticipationStyle, RepresentationMode, PermissionLevel, ConversationScope, AgentBehaviorSettings, Participant, Relationship, ContextOverlay, BehaviorProfile, AdmissionPolicy, RuntimeControlPolicy, ActionApprovalPolicy, ParticipationPolicy, WorkSession, ResolvedPolicy, ResolvedTurnEligibility, ResolvedAgentBehaviorPolicy, ParticipationHistoryMessage, ParticipationHistorySnapshot, ParticipationDecisionInput, ParticipationDecision, } from './policy.js';
+export { buildParticipationHistorySnapshot, buildParticipationHistorySnapshots, buildBehaviorPolicyLines, DEFAULT_PARTICIPATION_HISTORY_FETCH_LIMIT, evaluateParticipationPolicy, getDefaultParticipationPolicy, resolveAgentBehaviorPolicy, } from './policy.js';
+export { DEFAULT_RUNTIME_CAPABILITIES, FINAL_MESSAGE_HANDOFF_MS, isTurnOpen, normalizeTurnMetadata, normalizeTurnState, resolveTurnMessageSemantics, shouldPromoteConversationMessage, shouldTriggerAgentTurn, } from './turn-protocol.js';
 export type { DeliveryIntent, TurnMessageSemantics, InboundDisposition, TurnLifecycleState, RuntimeCapabilities, TurnState, TurnMetadata, TriggerDecision, } from './turn-protocol.js';
 export { registerAndWaitForApproval } from './registration.js';
 export { ApprovalManager } from './approval-manager.js';
@@ -17,6 +18,8 @@ export { loadProfiles, isProfileLocked, acquireLock, releaseLock, isProcessAlive
 export type { AgentProfile } from './agent-profiles.js';
 export { resolveCanonAgent, resolveCanonProfile, getActiveProfile } from './agent-resolver.js';
 export type { ResolvedAgent } from './agent-resolver.js';
+export { buildConfiguredWorkspaceOptions, buildConversationEnvironmentKey, buildConversationWorktreeSpec, buildPublicWorkspaceOptions, buildWorkspaceOptionId, isEnabledFlag, normalizeOptionalString, readSessionWorkspaceConfig, resolveConfiguredWorkspaceCwd, ExecutionEnvironmentError, prepareConversationEnvironment, releaseConversationEnvironment, } from './execution-environment.js';
+export type { ConfiguredWorkspaceOption, ExecutionEnvironmentMode, PreparedExecutionEnvironment, SessionWorkspaceConfig, } from './execution-environment.js';
 export { initRTDBAuth, rtdbWrite, rtdbRead, writeSessionState, clearSessionState, writeTurnState, clearTurnState, } from './rtdb-rest.js';
 export type { SessionStatePayload, TurnStatePayload } from './rtdb-rest.js';
 export { DEFAULT_BASE_URL, DEFAULT_STREAM_URL, DEFAULT_RTDB_URL, FIREBASE_WEB_API_KEY } from './constants.js';

package/dist/index.js

@@ -4,8 +4,9 @@ export { AGENT_CAPABILITIES, } from './types.js';
 export { CanonClient, CanonApiError } from './client.js';
 // Stream
 export { CanonStream } from './stream.js';
+export { buildParticipationHistorySnapshot, buildParticipationHistorySnapshots, buildBehaviorPolicyLines, DEFAULT_PARTICIPATION_HISTORY_FETCH_LIMIT, evaluateParticipationPolicy, getDefaultParticipationPolicy, resolveAgentBehaviorPolicy, } from './policy.js';
 // Turn protocol
-export { DEFAULT_RUNTIME_CAPABILITIES, isTurnOpen, normalizeTurnMetadata, normalizeTurnState, resolveTurnMessageSemantics, shouldPromoteConversationMessage, shouldTriggerAgentTurn, } from './turn-protocol.js';
+export { DEFAULT_RUNTIME_CAPABILITIES, FINAL_MESSAGE_HANDOFF_MS, isTurnOpen, normalizeTurnMetadata, normalizeTurnState, resolveTurnMessageSemantics, shouldPromoteConversationMessage, shouldTriggerAgentTurn, } from './turn-protocol.js';
 // Registration
 export { registerAndWaitForApproval } from './registration.js';
 // Approval
@@ -18,6 +19,8 @@ export { createStreamingHelper } from './streaming.js';
 export { loadProfiles, isProfileLocked, acquireLock, releaseLock, isProcessAlive, CANON_DIR, AGENTS_PATH, LOCKS_DIR, } from './agent-profiles.js';
 // Agent resolver
 export { resolveCanonAgent, resolveCanonProfile, getActiveProfile } from './agent-resolver.js';
+// Execution environments for host-mode coding sessions
+export { buildConfiguredWorkspaceOptions, buildConversationEnvironmentKey, buildConversationWorktreeSpec, buildPublicWorkspaceOptions, buildWorkspaceOptionId, isEnabledFlag, normalizeOptionalString, readSessionWorkspaceConfig, resolveConfiguredWorkspaceCwd, ExecutionEnvironmentError, prepareConversationEnvironment, releaseConversationEnvironment, } from './execution-environment.js';
 // RTDB REST helpers (token exchange, session state, generic read/write)
 export { initRTDBAuth, rtdbWrite, rtdbRead, writeSessionState, clearSessionState, writeTurnState, clearTurnState, } from './rtdb-rest.js';
 // Constants

package/dist/policy.d.ts

@@ -1,11 +1,11 @@
-export type PolicyRole = 'owner' | 'conversation_member' | 'group_admin' | 'external_requester' | 'agent_self';
-export type ParticipationStyle = 'natural' | 'collaborative' | 'mention-first' | 'approval-gated' | 'handoff-only' | 'observer';
-export type RepresentationMode = 'self' | 'delegate';
-export type PermissionLevel = 'deny' | 'allow' | 'require_approval';
-export type ConversationScope = 'global' | 'relationship' | 'conversation' | 'work_session' | 'message';
+export type PolicyRole = "owner" | "conversation_member" | "group_admin" | "external_requester" | "agent_self";
+export type ParticipationStyle = "natural" | "collaborative" | "mention-first" | "approval-gated" | "handoff-only" | "observer";
+export type RepresentationMode = "self" | "delegate";
+export type PermissionLevel = "deny" | "allow" | "require_approval";
+export type ConversationScope = "global" | "relationship" | "conversation" | "work_session" | "message";
 export interface Participant {
     id: string;
-    type: 'human' | 'ai_agent';
+    type: "human" | "ai_agent";
     ownerId?: string | null;
     relationshipIds?: string[];
 }
@@ -21,6 +21,16 @@ export interface ContextOverlay {
     instructions?: string | null;
     notes?: string | null;
 }
+export interface AgentBehaviorSettings {
+    participationStyle?: ParticipationStyle | null;
+    allowAgentToAgent?: boolean | null;
+    allowLongRunningCollaboration?: boolean | null;
+    requireMentionForGroupReplies?: boolean | null;
+    /** @deprecated Use requireMentionForGroupReplies instead. */
+    requireMentionForGroupAgentReplies?: boolean | null;
+    maxConsecutiveAgentTurns?: number | null;
+    instructions?: string | null;
+}
 export interface BehaviorProfile {
     id: string;
     label: string;
@@ -28,7 +38,7 @@ export interface BehaviorProfile {
     defaultRepresentation: RepresentationMode;
     allowAgentToAgent: boolean;
     allowLongRunningCollaboration: boolean;
-    requireMentionForGroupAgentReplies: boolean;
+    requireMentionForGroupReplies: boolean;
     maxConsecutiveAgentTurns?: number | null;
 }
 export interface AdmissionPolicy {
@@ -54,7 +64,7 @@ export interface ParticipationPolicy {
     allowAgentToAgent: boolean;
     allowHumanToAgent: boolean;
     allowLongRunningCollaboration: boolean;
-    requireMentionForGroupAgentReplies: boolean;
+    requireMentionForGroupReplies: boolean;
     maxConsecutiveAgentTurns?: number | null;
 }
 export interface WorkSession {
@@ -65,7 +75,7 @@ export interface WorkSession {
     participationStyle?: ParticipationStyle;
     activeParticipantIds: string[];
     overlayIds?: string[];
-    status: 'active' | 'paused' | 'completed';
+    status: "active" | "paused" | "completed";
 }
 export interface ResolvedPolicy {
     admission: AdmissionPolicy;
@@ -97,3 +107,50 @@ export interface ResolvedTurnEligibility {
     mayInitiateExternalFirstContact: boolean;
     reasonCodes: string[];
 }
+export interface ResolvedAgentBehaviorPolicy {
+    participation: ParticipationPolicy;
+    instructions: string[];
+    source: {
+        hasAgentDefault: boolean;
+        hasConversationOverride: boolean;
+    };
+}
+export interface ParticipationDecisionInput {
+    conversationType: "direct" | "group" | "unknown";
+    senderType: "human" | "ai_agent";
+    isOwner: boolean;
+    mentionedAgent: boolean;
+    recentHumanCount?: number;
+    consecutiveAgentTurns?: number;
+    currentAgentStreakStartedByHuman?: boolean;
+}
+export interface ParticipationDecision {
+    allow: boolean;
+    reasonCode: string;
+    reason: string;
+}
+export interface ParticipationHistoryMessage {
+    id?: string;
+    senderId: string;
+    senderType: "human" | "ai_agent";
+    metadata?: unknown;
+}
+export interface ParticipationHistorySnapshot {
+    recentSenderTypes: Array<"human" | "ai_agent">;
+    recentHumanCount: number;
+    recentAgentCount: number;
+    consecutiveAgentTurns: number;
+    currentAgentStreakStartedByHuman: boolean;
+}
+export declare const DEFAULT_PARTICIPATION_HISTORY_FETCH_LIMIT = 50;
+export declare function getDefaultParticipationPolicy(): ParticipationPolicy;
+export declare function resolveAgentBehaviorPolicy(input?: {
+    agentDefault?: AgentBehaviorSettings | null;
+    conversationOverride?: AgentBehaviorSettings | null;
+}): ResolvedAgentBehaviorPolicy;
+export declare function evaluateParticipationPolicy(policy: ResolvedAgentBehaviorPolicy | null | undefined, input: ParticipationDecisionInput): ParticipationDecision;
+export declare function buildBehaviorPolicyLines(policy: ResolvedAgentBehaviorPolicy | null | undefined): string[];
+export declare function buildParticipationHistorySnapshot(messages: ParticipationHistoryMessage[], agentId: string): ParticipationHistorySnapshot;
+export declare function buildParticipationHistorySnapshots<TMessage extends ParticipationHistoryMessage & {
+    id: string;
+}>(messages: TMessage[], agentId: string): Map<string, ParticipationHistorySnapshot>;

package/dist/policy.js

@@ -1 +1,189 @@
-export {};
+import { resolveTurnMessageSemantics } from "./turn-protocol.js";
+export const DEFAULT_PARTICIPATION_HISTORY_FETCH_LIMIT = 50;
+const DEFAULT_PARTICIPATION_POLICY = {
+    style: "natural",
+    allowAgentToAgent: true,
+    allowHumanToAgent: true,
+    allowLongRunningCollaboration: true,
+    requireMentionForGroupReplies: false,
+    maxConsecutiveAgentTurns: null,
+};
+function coalesceBoolean(overrideValue, fallbackValue, defaultValue = false) {
+    if (typeof overrideValue === "boolean")
+        return overrideValue;
+    if (typeof fallbackValue === "boolean")
+        return fallbackValue;
+    return defaultValue;
+}
+function coalesceStyle(overrideValue, fallbackValue) {
+    return overrideValue ?? fallbackValue ?? DEFAULT_PARTICIPATION_POLICY.style;
+}
+function resolveGroupMentionRequirement(value) {
+    if (typeof value?.requireMentionForGroupReplies === "boolean") {
+        return value.requireMentionForGroupReplies;
+    }
+    if (typeof value?.requireMentionForGroupAgentReplies === "boolean") {
+        return value.requireMentionForGroupAgentReplies;
+    }
+    if (value?.requireMentionForGroupReplies === null ||
+        value?.requireMentionForGroupAgentReplies === null) {
+        return null;
+    }
+    return undefined;
+}
+function coalesceMaxConsecutiveAgentTurns(overrideValue, fallbackValue) {
+    if (overrideValue === null)
+        return null;
+    if (typeof overrideValue === "number")
+        return overrideValue;
+    if (fallbackValue === null)
+        return null;
+    if (typeof fallbackValue === "number")
+        return fallbackValue;
+    return DEFAULT_PARTICIPATION_POLICY.maxConsecutiveAgentTurns ?? null;
+}
+function normalizedInstructions(value) {
+    if (typeof value !== "string")
+        return null;
+    const trimmed = value.trim();
+    return trimmed.length > 0 ? trimmed : null;
+}
+export function getDefaultParticipationPolicy() {
+    return { ...DEFAULT_PARTICIPATION_POLICY };
+}
+export function resolveAgentBehaviorPolicy(input) {
+    const agentDefault = input?.agentDefault ?? null;
+    const conversationOverride = input?.conversationOverride ?? null;
+    const defaultInstructions = normalizedInstructions(agentDefault?.instructions);
+    const overrideInstructions = normalizedInstructions(conversationOverride?.instructions);
+    return {
+        participation: {
+            style: coalesceStyle(conversationOverride?.participationStyle, agentDefault?.participationStyle),
+            allowAgentToAgent: coalesceBoolean(conversationOverride?.allowAgentToAgent, agentDefault?.allowAgentToAgent, DEFAULT_PARTICIPATION_POLICY.allowAgentToAgent),
+            allowHumanToAgent: DEFAULT_PARTICIPATION_POLICY.allowHumanToAgent,
+            allowLongRunningCollaboration: coalesceBoolean(conversationOverride?.allowLongRunningCollaboration, agentDefault?.allowLongRunningCollaboration, DEFAULT_PARTICIPATION_POLICY.allowLongRunningCollaboration),
+            requireMentionForGroupReplies: coalesceBoolean(resolveGroupMentionRequirement(conversationOverride), resolveGroupMentionRequirement(agentDefault), DEFAULT_PARTICIPATION_POLICY.requireMentionForGroupReplies),
+            maxConsecutiveAgentTurns: coalesceMaxConsecutiveAgentTurns(conversationOverride?.maxConsecutiveAgentTurns, agentDefault?.maxConsecutiveAgentTurns),
+        },
+        instructions: [
+            ...(defaultInstructions ? [defaultInstructions] : []),
+            ...(overrideInstructions ? [overrideInstructions] : []),
+        ],
+        source: {
+            hasAgentDefault: agentDefault != null,
+            hasConversationOverride: conversationOverride != null,
+        },
+    };
+}
+export function evaluateParticipationPolicy(policy, input) {
+    const resolved = policy ?? resolveAgentBehaviorPolicy();
+    const participation = resolved.participation;
+    const consecutiveAgentTurns = Math.max(input.consecutiveAgentTurns ?? (input.senderType === "ai_agent" ? 1 : 0), input.senderType === "ai_agent" ? 1 : 0);
+    const currentAgentStreakStartedByHuman = input.currentAgentStreakStartedByHuman === true;
+    if (input.isOwner) {
+        return {
+            allow: true,
+            reasonCode: "owner_sender",
+            reason: "owner messages always pass through",
+        };
+    }
+    if (input.conversationType === "group" &&
+        participation.requireMentionForGroupReplies &&
+        !input.mentionedAgent) {
+        return {
+            allow: false,
+            reasonCode: "group_mention_required",
+            reason: "group replies require a direct mention",
+        };
+    }
+    if (input.senderType !== "ai_agent") {
+        return {
+            allow: true,
+            reasonCode: "human_sender",
+            reason: "latest sender is human",
+        };
+    }
+    if (!participation.allowAgentToAgent) {
+        return {
+            allow: false,
+            reasonCode: "agent_to_agent_disabled",
+            reason: "agent-to-agent participation is disabled by policy",
+        };
+    }
+    if (!participation.allowLongRunningCollaboration &&
+        (consecutiveAgentTurns > 1 || !currentAgentStreakStartedByHuman)) {
+        return {
+            allow: false,
+            reasonCode: "human_reset_required",
+            reason: "a fresh human steer is required before continuing agent collaboration",
+        };
+    }
+    if (typeof participation.maxConsecutiveAgentTurns === "number" &&
+        participation.maxConsecutiveAgentTurns >= 0 &&
+        consecutiveAgentTurns > participation.maxConsecutiveAgentTurns) {
+        return {
+            allow: false,
+            reasonCode: "agent_turn_limit_reached",
+            reason: "maximum consecutive agent turns reached",
+        };
+    }
+    return {
+        allow: true,
+        reasonCode: input.conversationType === "group"
+            ? "group_agent_allowed"
+            : "direct_agent_allowed",
+        reason: participation.requireMentionForGroupReplies
+            ? "policy allows this directly mentioned group reply"
+            : "agent-to-agent participation allowed by policy",
+    };
+}
+export function buildBehaviorPolicyLines(policy) {
+    const resolved = policy ?? resolveAgentBehaviorPolicy();
+    const maxTurns = resolved.participation.maxConsecutiveAgentTurns;
+    return [
+        `Canon guidance: participation posture is ${resolved.participation.style}.`,
+        `Canon rule: group replies require direct mention: ${resolved.participation.requireMentionForGroupReplies ? "yes" : "no"}`,
+        `Canon rule: agent-to-agent collaboration allowed: ${resolved.participation.allowAgentToAgent ? "yes" : "no"}`,
+        `Canon rule: long-running collaboration allowed: ${resolved.participation.allowLongRunningCollaboration ? "yes" : "no"}`,
+        `Canon rule: max consecutive agent turns without a human reset: ${typeof maxTurns === "number" ? String(maxTurns) : "unlimited"}`,
+        ...resolved.instructions.map((instruction, index) => `Canon guidance ${index + 1}: ${instruction}`),
+    ];
+}
+function toHistorySenderType(message) {
+    if (message.senderType !== "ai_agent") {
+        return "human";
+    }
+    return resolveTurnMessageSemantics({
+        senderType: message.senderType,
+        metadata: message.metadata,
+    }) === "turn_complete"
+        ? "ai_agent"
+        : null;
+}
+export function buildParticipationHistorySnapshot(messages, agentId) {
+    const recentSenderTypes = messages.flatMap((message) => {
+        const senderType = toHistorySenderType(message);
+        return senderType ? [senderType] : [];
+    });
+    let consecutiveAgentTurns = 0;
+    for (const senderType of recentSenderTypes) {
+        if (senderType !== "ai_agent")
+            break;
+        consecutiveAgentTurns += 1;
+    }
+    return {
+        recentSenderTypes,
+        recentHumanCount: recentSenderTypes.filter((senderType) => senderType === "human").length,
+        recentAgentCount: recentSenderTypes.filter((senderType) => senderType === "ai_agent").length,
+        consecutiveAgentTurns,
+        currentAgentStreakStartedByHuman: consecutiveAgentTurns > 0 &&
+            recentSenderTypes[consecutiveAgentTurns] === "human",
+    };
+}
+export function buildParticipationHistorySnapshots(messages, agentId) {
+    const snapshots = new Map();
+    for (let index = 0; index < messages.length; index += 1) {
+        snapshots.set(messages[index].id, buildParticipationHistorySnapshot(messages.slice(index + 1), agentId));
+    }
+    return snapshots;
+}

package/dist/registration.js

@@ -17,6 +17,7 @@ export async function registerAndWaitForApproval(input, callbacks) {
         developerInfo: input.developerInfo || 'Canon agent',
         avatarUrl: input.avatarUrl,
         clientType: input.clientType,
+        requestedAgentId: input.requestedAgentId,
     });
     callbacks?.onSubmitted?.(requestId);
     const deadline = Date.now() + POLL_TIMEOUT_MS;

package/dist/rtdb-rest.d.ts

@@ -13,6 +13,8 @@ export interface SessionStatePayload {
     permissionMode?: string;
     effort?: string;
     cwd?: string;
+    executionMode?: 'worktree' | 'locked';
+    executionBranch?: string;
     hostMode?: boolean;
     clientType?: string;
     isActive: boolean;

package/dist/turn-protocol.d.ts

@@ -9,6 +9,7 @@ export interface RuntimeCapabilities {
     supportsRequiresAction: boolean;
     supportsNonFinalPermanentMessages: boolean;
 }
+export declare const FINAL_MESSAGE_HANDOFF_MS = 750;
 export interface TurnState {
     turnId?: string | null;
     state: TurnLifecycleState;

package/dist/turn-protocol.js

@@ -1,3 +1,4 @@
+export const FINAL_MESSAGE_HANDOFF_MS = 750;
 const TURN_STATES = [
     'idle',
     'thinking',

package/dist/types.d.ts

@@ -1,3 +1,4 @@
+import type { ResolvedAgentBehaviorPolicy } from './policy.js';
 export type MediaAttachmentKind = 'image' | 'audio' | 'file';
 export interface MediaAttachment {
     kind: MediaAttachmentKind;
@@ -36,6 +37,7 @@ export interface CanonConversation {
     topic: string | null;
     memberIds: string[];
     isAgentChat: boolean;
+    behavior?: ResolvedAgentBehaviorPolicy;
     hasUnread?: boolean;
     lastMessage: {
         text: string;
@@ -45,6 +47,10 @@ export interface CanonConversation {
     } | null;
     createdAt: string;
 }
+export interface CanonMessagesPage {
+    messages: CanonMessage[];
+    behavior?: ResolvedAgentBehaviorPolicy;
+}
 export type AgentClientType = 'claude-code' | 'openclaw' | 'codex' | 'generic';
 /** Declares what session controls an agent type supports. */
 export interface AgentCapabilities {
@@ -77,9 +83,11 @@ export interface AgentContext {
     accessLevel: 'open' | 'owner-only';
     /** Identifies the agent's client platform for UI feature detection */
     clientType?: AgentClientType;
+    defaultBehavior?: ResolvedAgentBehaviorPolicy;
 }
 export interface MessageCreatedPayload {
     conversationId: string;
+    behavior?: ResolvedAgentBehaviorPolicy;
     message: {
         id: string;
         senderId: string;
@@ -152,6 +160,8 @@ export interface SessionState {
     permissionMode?: string;
     effort?: string;
     cwd?: string;
+    executionMode?: 'worktree' | 'locked';
+    executionBranch?: string;
     /** True when the agent is running under the host wrapper (host.ts) which can apply control signals */
     hostMode?: boolean;
     isActive: boolean;
@@ -192,6 +202,7 @@ export interface RegistrationInput {
     avatarUrl?: string;
     baseUrl?: string;
     clientType?: AgentClientType;
+    requestedAgentId?: string;
 }
 export interface RegistrationResult {
     status: 'approved' | 'rejected' | 'timeout';

package/dist/types.js

@@ -1,4 +1,3 @@
-// ── Message ────────────────────────────────────────────────────────────
 const DEFAULT_CAPABILITIES = {
     supportsModelSwitch: false,
     supportsPermissionMode: false,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@canonmsg/core",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "Canon core — shared types, REST client, SSE stream, and registration for Canon messaging",
   "type": "module",
   "main": "dist/index.js",