salmon-loop 0.2.3

package/dist/core/protocols/acp/formal-agent.js

@@ -0,0 +1,1201 @@
+import { createHash } from 'crypto';
+import { PROTOCOL_VERSION, RequestError, } from '@agentclientprotocol/sdk';
+import { text } from '../../../locales/index.js';
+import { mkdir, open, readFile, rename, stat, unlink, writeFile, } from '../../adapters/fs/node-fs.js';
+import { defaultPathAdapter } from '../../adapters/path/path-adapter.js';
+import { inferTurnStopReasonFromFailure } from '../../interaction/turn-stop-reason.js';
+import { recordAuditEvent } from '../../observability/audit-trail.js';
+import { readPlan } from '../../plan/index.js';
+import { parseSlashInput } from '../../slash/parser.js';
+import { createAcpCommandRunner } from './acp-command-runner.js';
+import { createAcpFileSystem } from './acp-filesystem.js';
+import { createAcpSessionStore, isTerminalTaskEvent } from './handlers.js';
+import { createAcpToolAuthorizationProvider } from './permission-provider.js';
+function formatInputRequiredMessage(inputRequired) {
+    if (!inputRequired || !Array.isArray(inputRequired.questions))
+        return null;
+    const questions = inputRequired.questions;
+    if (questions.length === 0)
+        return null;
+    const lines = [text.acp.askUserHeader];
+    for (const q of questions) {
+        lines.push(text.acp.askUserQuestion(q.question));
+        lines.push(text.acp.askUserOptionsHeader);
+        for (const option of q.options) {
+            lines.push(text.acp.askUserOption(option.label, option.description));
+        }
+        if (q.multiSelect) {
+            lines.push(text.acp.askUserMultiSelectHint);
+        }
+    }
+    return lines.join('\n');
+}
+const ACP_PERMISSION_POLICY_CONFIG_ID = '_salmonloop_permission_policy';
+const ACP_MODE_CONFIG_ID = '_salmonloop_mode';
+const ACP_PERMISSION_POLICY_ASK = 'ask';
+const ACP_PERMISSION_POLICY_DENY_ALL = 'deny_all';
+const ACP_DEFAULT_MODE_ID = 'interactive';
+const ACP_SESSION_STORE_MAX_ENTRIES = 200;
+const ACP_SESSION_STORE_MAX_AGE_MS = 1000 * 60 * 60 * 24 * 30;
+const ACP_SESSION_STORE_LOCK_STALE_MS = 1000 * 30;
+const ACP_SESSION_STORE_LOCK_HEARTBEAT_MS = 1000 * 5;
+const ACP_SESSION_STORE_LOCK_ACQUIRE_TIMEOUT_MS = 1000 * 5;
+const ACP_SESSION_HISTORY_MAX_ENTRIES = 40;
+function isAbsolutePath(filePath) {
+    if (defaultPathAdapter.isAbsolute(filePath))
+        return true;
+    // Cross-platform absolute check for Windows paths on non-Windows runtimes.
+    // ACP requires absolute paths, but the runtime OS may not match the client OS.
+    if (/^[a-zA-Z]:[\\/]/.test(filePath))
+        return true; // drive letter
+    if (filePath.startsWith('\\\\'))
+        return true; // UNC path
+    return false;
+}
+function ensureMarkdownParagraphBreak(text) {
+    if (!text)
+        return text;
+    const trimmed = text.replace(/\r?\n$/, '');
+    return `${trimmed}\n\n`;
+}
+function buildTextContentBlock(text) {
+    return { type: 'text', text };
+}
+function buildJsonResourceContentBlock(data) {
+    return {
+        type: 'resource',
+        resource: {
+            mimeType: 'application/json',
+            uri: 's8p://input-required',
+            text: JSON.stringify(data),
+        },
+    };
+}
+const defaultPromptCapabilities = {
+    image: false,
+    audio: false,
+    embeddedContext: false,
+};
+const ACP_AVAILABLE_COMMANDS = [
+    { name: 'help', description: text.acp.slashHelpDescription },
+];
+function formatResourceLink(block) {
+    const title = block.title ?? block.name ?? block.uri;
+    const description = block.description ? ` - ${block.description}` : '';
+    return `Resource: ${title} (${block.uri})${description}`;
+}
+function extractTextFromPrompt(prompt, capabilities) {
+    const parts = [];
+    for (const block of prompt) {
+        switch (block.type) {
+            case 'text':
+                parts.push(block.text);
+                break;
+            case 'resource_link':
+                parts.push(formatResourceLink(block));
+                break;
+            case 'image':
+                if (!capabilities.image) {
+                    throw new RequestError(-32000, 'Prompt content type image is not supported');
+                }
+                break;
+            case 'audio':
+                if (!capabilities.audio) {
+                    throw new RequestError(-32000, 'Prompt content type audio is not supported');
+                }
+                break;
+            case 'resource':
+                if (!capabilities.embeddedContext) {
+                    throw new RequestError(-32000, 'Prompt content type resource is not supported');
+                }
+                break;
+            default:
+                throw new RequestError(-32602, 'Invalid params: unsupported content block type');
+        }
+    }
+    return parts.join('\n');
+}
+function mapToolKind(toolName, intent) {
+    if (intent) {
+        switch (intent.toUpperCase()) {
+            case 'READ':
+                return 'read';
+            case 'LIST':
+                return 'read';
+            case 'SEARCH':
+                return 'search';
+            case 'WRITE':
+                return 'edit';
+            case 'INFRA':
+                return 'execute';
+            case 'AGENT':
+                return 'think';
+        }
+    }
+    const name = toolName.toLowerCase();
+    if (name.includes('read') ||
+        name.includes('get') ||
+        name.includes('view') ||
+        name.includes('ls') ||
+        name.includes('list'))
+        return 'read';
+    if (name.includes('write') || name.includes('edit') || name.includes('patch'))
+        return 'edit';
+    if (name.includes('delete') || name.includes('remove') || name.includes('rm'))
+        return 'delete';
+    if (name.includes('move') || name.includes('rename') || name.includes('mv'))
+        return 'move';
+    if (name.includes('grep') || name.includes('search') || name.includes('find'))
+        return 'search';
+    if (name.includes('run') || name.includes('exec') || name.includes('spawn'))
+        return 'execute';
+    if (name.includes('plan') || name.includes('think') || name.includes('reason'))
+        return 'think';
+    if (name.includes('fetch') || name.includes('curl') || name.includes('http'))
+        return 'fetch';
+    return 'other';
+}
+function buildToolCallContent(textValue) {
+    return [{ type: 'content', content: buildTextContentBlock(textValue) }];
+}
+function extractLocationFromInput(input) {
+    if (!input || typeof input !== 'object')
+        return undefined;
+    const typedInput = input;
+    const pathCandidate = typedInput.path ?? typedInput.file ?? typedInput.uri;
+    if (typeof pathCandidate === 'string' && pathCandidate.trim()) {
+        let path = pathCandidate.replace(/^file:\/\/\//, '/').replace(/^file:\/\//, '');
+        if (/^\/[a-zA-Z]:/.test(path)) {
+            path = path.slice(1);
+        }
+        return [
+            {
+                path,
+                line: typeof typedInput.line === 'number' ? typedInput.line : undefined,
+            },
+        ];
+    }
+    return undefined;
+}
+function formatToolCallEnd(event) {
+    if (event.outputSummary)
+        return event.outputSummary;
+    const status = event.status === 'ok' ? 'completed' : 'failed';
+    return `Tool call ${status}: ${event.toolName}`;
+}
+function loopEventToSessionUpdate(event) {
+    switch (event.type) {
+        case 'llm.stream.delta':
+            return {
+                sessionUpdate: event.kind === 'assistant_message' ? 'agent_message_chunk' : 'agent_thought_chunk',
+                content: buildTextContentBlock(event.content || ''),
+            };
+        case 'llm.output':
+            return {
+                sessionUpdate: event.kind === 'assistant_message' ? 'agent_message_chunk' : 'agent_thought_chunk',
+                content: buildTextContentBlock(event.content || ''),
+            };
+        case 'tool.call.start':
+            return {
+                sessionUpdate: 'tool_call',
+                toolCallId: event.callId,
+                status: 'pending',
+                title: event.toolName,
+                kind: mapToolKind(event.toolName, event.toolIntent),
+                content: [],
+                rawInput: event.input,
+                locations: extractLocationFromInput(event.input),
+            };
+        case 'tool.call.end':
+            return {
+                sessionUpdate: 'tool_call_update',
+                toolCallId: event.callId,
+                status: event.status === 'ok' ? 'completed' : 'failed',
+                content: event.status !== 'ok' ? buildToolCallContent(formatToolCallEnd(event)) : [],
+                rawOutput: event.outputSummary,
+            };
+        case 'phase.start':
+            return null;
+        case 'phase.end':
+            return null;
+        case 'log':
+            return null;
+        default:
+            return null;
+    }
+}
+function createSessionRuntimeState() {
+    return createSessionRuntimeStateFromPersisted();
+}
+function isPermissionPolicyValue(value) {
+    return value === ACP_PERMISSION_POLICY_ASK || value === ACP_PERMISSION_POLICY_DENY_ALL;
+}
+function buildConfigOptions(state) {
+    return [
+        {
+            type: 'select',
+            id: ACP_PERMISSION_POLICY_CONFIG_ID,
+            name: text.acp.permissionPolicyName,
+            description: text.acp.permissionPolicyDescription,
+            currentValue: state.permissionPolicy,
+            options: [
+                {
+                    value: ACP_PERMISSION_POLICY_ASK,
+                    name: text.acp.permissionPolicyAskName,
+                    description: text.acp.permissionPolicyAskDescription,
+                },
+                {
+                    value: ACP_PERMISSION_POLICY_DENY_ALL,
+                    name: text.acp.permissionPolicyDenyAllName,
+                    description: text.acp.permissionPolicyDenyAllDescription,
+                },
+            ],
+        },
+        {
+            type: 'select',
+            id: ACP_MODE_CONFIG_ID,
+            name: 'Session Mode',
+            description: text.acp.modeInteractiveDescription,
+            currentValue: state.modeId,
+            options: [
+                {
+                    value: 'interactive',
+                    name: 'Interactive',
+                    description: text.acp.modeInteractiveDescription,
+                },
+                {
+                    value: 'yolo',
+                    name: 'YOLO',
+                    description: text.acp.modeYoloDescription,
+                },
+            ],
+        },
+    ];
+}
+function buildConfigOptionUpdateIfChanged(state) {
+    const configOptions = buildConfigOptions(state);
+    const digest = JSON.stringify(configOptions);
+    if (digest === state.lastConfigDigest)
+        return null;
+    state.lastConfigDigest = digest;
+    return {
+        sessionUpdate: 'config_option_update',
+        configOptions,
+    };
+}
+function buildAvailableCommandsUpdateIfChanged(state) {
+    const availableCommands = ACP_AVAILABLE_COMMANDS;
+    const digest = JSON.stringify(availableCommands);
+    if (digest === state.lastCommandsDigest)
+        return null;
+    state.lastCommandsDigest = digest;
+    return {
+        sessionUpdate: 'available_commands_update',
+        availableCommands,
+    };
+}
+function isSessionModeId(value) {
+    return value === 'interactive' || value === 'yolo';
+}
+function buildCurrentModeUpdate(modeId) {
+    return { sessionUpdate: 'current_mode_update', currentModeId: modeId };
+}
+function buildCurrentModeUpdateIfChanged(state) {
+    const digest = state.modeId;
+    if (digest === state.lastModeDigest)
+        return null;
+    state.lastModeDigest = digest;
+    return buildCurrentModeUpdate(state.modeId);
+}
+function getPermissionPolicyForAuthorization(state) {
+    if (state.modeId === 'yolo')
+        return 'allow_all';
+    return state.permissionPolicy;
+}
+function createSessionRuntimeStateFromPersisted(input) {
+    const permissionPolicy = isPermissionPolicyValue(String(input?.permissionPolicy))
+        ? input?.permissionPolicy
+        : ACP_PERMISSION_POLICY_ASK;
+    const modeId = isSessionModeId(String(input?.modeId))
+        ? input?.modeId
+        : (input?.defaultModeId ?? ACP_DEFAULT_MODE_ID);
+    const state = {
+        runtimePlanSessionId: null,
+        runtimePlanPathHint: null,
+        lastPlanDigest: null,
+        lastCommandsDigest: null,
+        lastConfigDigest: null,
+        lastModeDigest: null,
+        permissionPolicy,
+        modeId,
+    };
+    state.lastConfigDigest = JSON.stringify(buildConfigOptions(state));
+    return state;
+}
+function loopEventToSessionUpdates(event, _state) {
+    const updates = [];
+    const mapped = loopEventToSessionUpdate(event);
+    if (mapped)
+        updates.push(mapped);
+    return updates;
+}
+function shouldRefreshPlanForEvent(event) {
+    if (!event)
+        return true;
+    if (event.type === 'plan.runtime.ready')
+        return true;
+    if (event.type === 'tool.call.end' &&
+        (event.toolName === 'plan.init' || event.toolName === 'plan.update') &&
+        event.status === 'ok') {
+        return true;
+    }
+    if (event.type === 'plan.runtime.journal' &&
+        event.phase === 'PLAN' &&
+        event.kind === 'end' &&
+        event.ok) {
+        return true;
+    }
+    return false;
+}
+function mapCorePlanToAcpEntries(read) {
+    const entries = [];
+    const seen = new Set();
+    const parsePriority = (text) => {
+        const trimmed = text.trim();
+        if (trimmed.startsWith('!')) {
+            return { priority: 'high', content: trimmed.slice(1).trim() };
+        }
+        if (trimmed.startsWith('·')) {
+            return { priority: 'medium', content: trimmed.slice(1).trim() };
+        }
+        if (trimmed.startsWith('‐')) {
+            return { priority: 'low', content: trimmed.slice(1).trim() };
+        }
+        return { priority: 'medium', content: trimmed };
+    };
+    const push = (step, status) => {
+        if (!step?.stepId || seen.has(step.stepId))
+            return;
+        seen.add(step.stepId);
+        const { priority, content } = parsePriority(step.text || step.stepId);
+        entries.push({
+            content,
+            status,
+            priority,
+        });
+    };
+    for (const step of read.active)
+        push(step, 'in_progress');
+    for (const step of read.pending)
+        push(step, 'pending');
+    for (const step of read.recentDone)
+        push(step, 'completed');
+    return entries;
+}
+function buildPlanUpdateFromCoreIfChanged(read, state) {
+    const entries = mapCorePlanToAcpEntries(read);
+    const digest = JSON.stringify({
+        sessionId: read.sessionId,
+        baseHash: read.baseHash,
+        entries,
+    });
+    if (digest === state.lastPlanDigest)
+        return null;
+    state.lastPlanDigest = digest;
+    return {
+        sessionUpdate: 'plan',
+        entries,
+    };
+}
+function extractSlashInput(prompt) {
+    if (prompt.length !== 1)
+        return null;
+    const block = prompt[0];
+    if (!block || block.type !== 'text')
+        return null;
+    const raw = block.text ?? '';
+    if (!raw.trimStart().startsWith('/'))
+        return null;
+    return raw;
+}
+function buildSlashHelpMessage() {
+    const names = ACP_AVAILABLE_COMMANDS.map((cmd) => `/${cmd.name}`).join(', ');
+    return text.acp.slashHelpResponse(names);
+}
+function normalizeSlashName(commandName) {
+    return commandName.replace(/^\/+/, '').toLowerCase();
+}
+function isKnownSlashCommand(commandName) {
+    const normalized = normalizeSlashName(commandName);
+    return ACP_AVAILABLE_COMMANDS.some((cmd) => cmd.name.toLowerCase() === normalized);
+}
+async function awaitTerminalEvent(params) {
+    if (!params.eventBus)
+        return null;
+    const history = params.eventBus.list(params.taskId);
+    const terminal = history.find(isTerminalTaskEvent);
+    if (terminal)
+        return terminal;
+    return await new Promise((resolve) => {
+        const unsubscribe = params.eventBus.subscribe((event) => {
+            if (event.taskId !== params.taskId)
+                return;
+            if (!isTerminalTaskEvent(event))
+                return;
+            unsubscribe();
+            resolve(event);
+        });
+    });
+}
+export function createAcpFormalAgent(deps) {
+    const sessions = createAcpSessionStore();
+    const sessionRuntime = new Map();
+    let clientCapabilities;
+    const defaultClientCapabilities = {
+        fs: { readTextFile: false, writeTextFile: false },
+        terminal: false,
+    };
+    const loadSessionCapability = deps.capabilityPolicy?.loadSession ?? true;
+    const sessionPersistencePath = deps.sessionPersistencePath;
+    const sessionStorePolicy = {
+        maxEntries: deps.sessionStorePolicy?.maxEntries ?? ACP_SESSION_STORE_MAX_ENTRIES,
+        maxAgeMs: deps.sessionStorePolicy?.maxAgeMs ?? ACP_SESSION_STORE_MAX_AGE_MS,
+        historyMaxEntries: deps.sessionStorePolicy?.historyMaxEntries ?? ACP_SESSION_HISTORY_MAX_ENTRIES,
+        lockStaleMs: deps.sessionStorePolicy?.lockStaleMs ?? ACP_SESSION_STORE_LOCK_STALE_MS,
+        lockHeartbeatMs: deps.sessionStorePolicy?.lockHeartbeatMs ?? ACP_SESSION_STORE_LOCK_HEARTBEAT_MS,
+        lockAcquireTimeoutMs: deps.sessionStorePolicy?.lockAcquireTimeoutMs ?? ACP_SESSION_STORE_LOCK_ACQUIRE_TIMEOUT_MS,
+    };
+    const executionBinding = deps.executionBinding ?? 'local';
+    let sessionsHydrated = false;
+    let hydratePromise = null;
+    function parseTimestamp(value) {
+        if (typeof value !== 'string' || value.length === 0)
+            return 0;
+        const parsed = Date.parse(value);
+        return Number.isFinite(parsed) ? parsed : 0;
+    }
+    function pruneSessionRecords(records) {
+        const cutoff = Date.now() - sessionStorePolicy.maxAgeMs;
+        return [...records]
+            .filter((record) => parseTimestamp(record.updatedAt) >= cutoff)
+            .sort((a, b) => parseTimestamp(b.updatedAt) - parseTimestamp(a.updatedAt))
+            .slice(0, sessionStorePolicy.maxEntries);
+    }
+    function normalizePersistedSessionStore(input) {
+        if (!input || typeof input !== 'object') {
+            return { schemaVersion: 2, sessions: [] };
+        }
+        const raw = input;
+        if (!Array.isArray(raw.sessions))
+            return { schemaVersion: 2, sessions: [] };
+        if (raw.schemaVersion === 1) {
+            return {
+                schemaVersion: 2,
+                sessions: raw.sessions.map((entry) => ({
+                    id: entry.id,
+                    cwd: entry.cwd,
+                    mcpServers: entry.mcpServers,
+                    createdAt: entry.createdAt,
+                    updatedAt: entry.updatedAt,
+                    title: entry.title,
+                    taskId: undefined,
+                    history: [],
+                    permissionPolicy: ACP_PERMISSION_POLICY_ASK,
+                    modeId: deps.defaultModeId ?? ACP_DEFAULT_MODE_ID,
+                })),
+            };
+        }
+        if (raw.schemaVersion === 2) {
+            return { schemaVersion: 2, sessions: raw.sessions };
+        }
+        return { schemaVersion: 2, sessions: [] };
+    }
+    function isPidAlive(pid) {
+        if (!Number.isInteger(pid) || pid <= 0)
+            return false;
+        try {
+            process.kill(pid, 0);
+            return true;
+        }
+        catch (error) {
+            if (error &&
+                typeof error === 'object' &&
+                'code' in error &&
+                error.code === 'EPERM') {
+                return true;
+            }
+            return false;
+        }
+    }
+    function isFileMissing(error) {
+        return Boolean(error &&
+            typeof error === 'object' &&
+            'code' in error &&
+            (error.code === 'ENOENT' ||
+                error.code === 'ENOTDIR'));
+    }
+    async function persistSessionsBestEffort() {
+        if (!sessionPersistencePath)
+            return;
+        const dir = defaultPathAdapter.dirname(sessionPersistencePath);
+        const lockPath = `${sessionPersistencePath}.lock`;
+        const baseRecords = sessions.list().map((session) => {
+            const runtimeState = ensureSessionRuntimeState(session.id);
+            return {
+                id: session.id,
+                cwd: session.cwd,
+                mcpServers: session.mcpServers,
+                createdAt: session.createdAt,
+                updatedAt: session.updatedAt,
+                title: session.title,
+                taskId: session.taskId,
+                history: session.history.slice(-sessionStorePolicy.historyMaxEntries),
+                permissionPolicy: runtimeState.permissionPolicy,
+                modeId: runtimeState.modeId,
+            };
+        });
+        const prunedRecords = pruneSessionRecords(baseRecords);
+        const keepIds = new Set(prunedRecords.map((record) => record.id));
+        for (const record of sessions.list()) {
+            if (!keepIds.has(record.id)) {
+                sessions.delete(record.id);
+            }
+        }
+        const payload = { schemaVersion: 2, sessions: prunedRecords };
+        const primaryRepoPath = prunedRecords[0]?.cwd;
+        const lockAuditDetails = {
+            lockPath,
+            lockPathHash: createHash('sha256').update(lockPath).digest('hex').slice(0, 16),
+            repoPathHash: primaryRepoPath ? hashRepoPath(primaryRepoPath) : undefined,
+        };
+        const tryClearStaleLock = async () => {
+            try {
+                const raw = await readFile(lockPath, 'utf8');
+                const parsed = JSON.parse(raw);
+                const createdAtMs = typeof parsed.createdAtMs === 'number' && Number.isFinite(parsed.createdAtMs)
+                    ? parsed.createdAtMs
+                    : null;
+                if (createdAtMs === null)
+                    return;
+                if (Date.now() - createdAtMs <= sessionStorePolicy.lockStaleMs)
+                    return;
+                if (typeof parsed.pid === 'number' && isPidAlive(parsed.pid))
+                    return;
+                await unlink(lockPath);
+                recordAuditEvent('acp.session.lock.stale_reclaimed', lockAuditDetails, {
+                    source: 'acp',
+                    severity: 'low',
+                    scope: 'session',
+                    phase: 'PREFLIGHT',
+                });
+            }
+            catch {
+                try {
+                    const lockStat = await stat(lockPath);
+                    const ageMs = Date.now() - lockStat.mtimeMs;
+                    if (Number.isFinite(ageMs) && ageMs > sessionStorePolicy.lockStaleMs * 2) {
+                        await unlink(lockPath);
+                        recordAuditEvent('acp.session.lock.corrupted_reclaimed', {
+                            ...lockAuditDetails,
+                            ageMs: Math.max(0, Math.floor(ageMs)),
+                        }, { source: 'acp', severity: 'medium', scope: 'session', phase: 'PREFLIGHT' });
+                    }
+                }
+                catch {
+                    // ignore
+                }
+            }
+        };
+        let lockHandle;
+        try {
+            await mkdir(dir, { recursive: true });
+            const acquireDeadlineMs = Date.now() + Math.max(250, sessionStorePolicy.lockAcquireTimeoutMs);
+            for (let attempt = 0; Date.now() < acquireDeadlineMs; attempt += 1) {
+                try {
+                    lockHandle = await open(lockPath, 'wx');
+                    await lockHandle.writeFile(JSON.stringify({ pid: process.pid, createdAtMs: Date.now() }), 'utf8');
+                    break;
+                }
+                catch {
+                    await tryClearStaleLock();
+                    const delayMs = Math.min(250, 20 * (attempt + 1));
+                    await new Promise((resolve) => setTimeout(resolve, delayMs));
+                }
+            }
+            if (!lockHandle) {
+                recordAuditEvent('acp.session.lock.acquire_timeout', lockAuditDetails, {
+                    source: 'acp',
+                    severity: 'medium',
+                    scope: 'session',
+                    phase: 'PREFLIGHT',
+                });
+                throw new Error('ACP_SESSION_PERSIST_LOCK_TIMEOUT');
+            }
+            const heartbeat = setInterval(() => {
+                void writeFile(lockPath, JSON.stringify({ pid: process.pid, createdAtMs: Date.now() }), 'utf8');
+            }, Math.max(1000, sessionStorePolicy.lockHeartbeatMs));
+            const tempPath = defaultPathAdapter.join(dir, `.sessions.v1.json.tmp-${process.pid}-${Date.now()}`);
+            try {
+                let existing = { schemaVersion: 2, sessions: [] };
+                try {
+                    const existingRaw = await readFile(sessionPersistencePath, 'utf8');
+                    existing = normalizePersistedSessionStore(JSON.parse(existingRaw));
+                }
+                catch {
+                    // ignore read failure; writing fresh payload is acceptable
+                }
+                const merged = new Map();
+                for (const entry of existing.sessions)
+                    merged.set(entry.id, entry);
+                for (const entry of payload.sessions)
+                    merged.set(entry.id, entry);
+                const mergedPayload = {
+                    schemaVersion: 2,
+                    sessions: pruneSessionRecords(Array.from(merged.values())),
+                };
+                await writeFile(tempPath, JSON.stringify(mergedPayload, null, 2), 'utf8');
+                await rename(tempPath, sessionPersistencePath);
+            }
+            finally {
+                clearInterval(heartbeat);
+            }
+        }
+        catch (error) {
+            recordAuditEvent('acp.session.persist.failed', {
+                errorName: error instanceof Error ? error.name : typeof error,
+            }, { source: 'acp', severity: 'low', scope: 'session', phase: 'PREFLIGHT' });
+        }
+        finally {
+            if (lockHandle) {
+                try {
+                    await lockHandle.close();
+                }
+                catch {
+                    // ignore
+                }
+                try {
+                    await unlink(lockPath);
+                }
+                catch {
+                    // ignore
+                }
+            }
+        }
+    }
+    async function hydrateSessionsOnce() {
+        if (sessionsHydrated)
+            return;
+        if (hydratePromise)
+            return hydratePromise;
+        hydratePromise = (async () => {
+            sessionsHydrated = true;
+            if (!sessionPersistencePath)
+                return;
+            try {
+                const raw = await readFile(sessionPersistencePath, 'utf8');
+                const parsed = normalizePersistedSessionStore(JSON.parse(raw));
+                for (const stored of pruneSessionRecords(parsed.sessions)) {
+                    sessions.upsert({
+                        id: stored.id,
+                        cwd: stored.cwd,
+                        mcpServers: Array.isArray(stored.mcpServers) ? stored.mcpServers : [],
+                        createdAt: stored.createdAt,
+                        updatedAt: stored.updatedAt,
+                        title: stored.title,
+                        taskId: stored.taskId,
+                        history: Array.isArray(stored.history)
+                            ? stored.history.slice(-sessionStorePolicy.historyMaxEntries)
+                            : [],
+                        cancelRequested: false,
+                    });
+                    if (!sessionRuntime.has(stored.id)) {
+                        sessionRuntime.set(stored.id, createSessionRuntimeStateFromPersisted({
+                            permissionPolicy: stored.permissionPolicy,
+                            modeId: stored.modeId,
+                            defaultModeId: deps.defaultModeId,
+                        }));
+                    }
+                }
+            }
+            catch (error) {
+                if (isFileMissing(error))
+                    return;
+                recordAuditEvent('acp.session.hydrate.failed', {
+                    errorName: error instanceof Error ? error.name : typeof error,
+                }, { source: 'acp', severity: 'low', scope: 'session', phase: 'PREFLIGHT' });
+            }
+        })();
+        return hydratePromise;
+    }
+    function hashRepoPath(repoPath) {
+        return createHash('sha256').update(repoPath).digest('hex').slice(0, 16);
+    }
+    function toCheckpointMeta(input) {
+        if (!input)
+            return null;
+        return {
+            id: input.id,
+            createdAt: input.createdAt ?? null,
+            strategy: input.strategy ?? null,
+            backend: input.backend ?? null,
+        };
+    }
+    function toResumeHint(probe) {
+        if (!probe || probe.valid)
+            return null;
+        switch (probe.reason) {
+            case 'not_found':
+                return {
+                    code: 'CHECKPOINT_NOT_FOUND',
+                    message: 'Checkpoint not found. Start a new session.',
+                };
+            case 'manifest_parse_error':
+                return {
+                    code: 'CHECKPOINT_MANIFEST_PARSE_ERROR',
+                    message: 'Checkpoint metadata is corrupted. Recreate checkpoint metadata and retry.',
+                };
+            case 'manifest_io_error':
+                return {
+                    code: 'CHECKPOINT_MANIFEST_IO_ERROR',
+                    message: 'Checkpoint metadata is unreadable due to filesystem I/O issues.',
+                };
+            case 'manifest_lock_timeout':
+                return {
+                    code: 'CHECKPOINT_MANIFEST_LOCK_TIMEOUT',
+                    message: 'Checkpoint metadata is busy (lock timeout). Retry shortly.',
+                };
+            case 'manifest_unavailable':
+                return {
+                    code: 'CHECKPOINT_MANIFEST_UNAVAILABLE',
+                    message: 'Checkpoint metadata is unavailable in current runtime.',
+                };
+            default:
+                return {
+                    code: 'CHECKPOINT_RESUME_UNAVAILABLE',
+                    message: 'Checkpoint resume is unavailable. Start a new session or retry.',
+                };
+        }
+    }
+    async function emitSessionUpdate(sessionId, update) {
+        await deps.conn.sessionUpdate({ sessionId, update });
+    }
+    async function emitRuntimePlanUpdateIfNeeded(params) {
+        if (!shouldRefreshPlanForEvent(params.event))
+            return;
+        const { state, event } = params;
+        const planReader = deps.planReader ?? {
+            readBySession: async ({ repoPath, sessionId }) => await readPlan({ persistenceRoot: repoPath, sessionId }),
+        };
+        if (event?.type === 'plan.runtime.ready') {
+            state.runtimePlanSessionId = event.sessionId;
+            state.runtimePlanPathHint = event.planPathHint;
+            state.lastPlanDigest = null;
+        }
+        if (!state.runtimePlanSessionId)
+            return;
+        try {
+            const read = await planReader.readBySession({
+                repoPath: params.repoPath,
+                sessionId: state.runtimePlanSessionId,
+            });
+            const planUpdate = buildPlanUpdateFromCoreIfChanged(read, state);
+            if (planUpdate) {
+                await emitSessionUpdate(params.sessionId, planUpdate);
+            }
+        }
+        catch (error) {
+            recordAuditEvent('acp.plan.read.failed', {
+                sessionId: params.sessionId,
+                repoPathHash: hashRepoPath(params.repoPath),
+                runtimePlanSessionId: state.runtimePlanSessionId,
+                runtimePlanPathHint: state.runtimePlanPathHint,
+                errorName: error instanceof Error ? error.name : typeof error,
+            }, { source: 'acp', severity: 'low', scope: 'session', phase: 'PLAN' });
+        }
+    }
+    async function loadSessionInternal(params) {
+        await hydrateSessionsOnce();
+        const session = sessions.get(params.sessionId);
+        if (!session) {
+            throw new RequestError(-32004, `Session not found: ${params.sessionId}`);
+        }
+        if (session.cwd !== params.cwd) {
+            sessions.update(params.sessionId, (current) => ({
+                ...current,
+                cwd: params.cwd,
+                mcpServers: params.mcpServers ?? [],
+            }));
+            await persistSessionsBestEffort();
+        }
+        return session;
+    }
+    function ensureSessionRuntimeState(sessionId) {
+        const existing = sessionRuntime.get(sessionId);
+        if (existing)
+            return existing;
+        const created = createSessionRuntimeState();
+        if (deps.defaultModeId) {
+            created.modeId = deps.defaultModeId;
+        }
+        sessionRuntime.set(sessionId, created);
+        return created;
+    }
+    return {
+        async initialize(params) {
+            if (typeof params.protocolVersion !== 'number' || !Number.isFinite(params.protocolVersion)) {
+                throw new RequestError(-32602, 'Invalid params: protocolVersion is required');
+            }
+            clientCapabilities = params.clientCapabilities;
+            return {
+                protocolVersion: PROTOCOL_VERSION,
+                agentInfo: deps.agentInfo,
+                authMethods: [],
+                agentCapabilities: {
+                    loadSession: loadSessionCapability,
+                    promptCapabilities: defaultPromptCapabilities,
+                    mcpCapabilities: { http: false, sse: false },
+                    sessionCapabilities: {},
+                },
+            };
+        },
+        async authenticate() {
+            return;
+        },
+        async newSession(params) {
+            await hydrateSessionsOnce();
+            if (!isAbsolutePath(params.cwd)) {
+                throw new RequestError(-32602, 'Invalid params: cwd must be an absolute path');
+            }
+            const session = sessions.create({ cwd: params.cwd, mcpServers: params.mcpServers ?? [] });
+            await persistSessionsBestEffort();
+            const runtimeState = ensureSessionRuntimeState(session.id);
+            // Restore session state on creation
+            const commandsUpdate = buildAvailableCommandsUpdateIfChanged(runtimeState);
+            if (commandsUpdate)
+                await emitSessionUpdate(session.id, commandsUpdate);
+            const modeUpdate = buildCurrentModeUpdateIfChanged(runtimeState);
+            if (modeUpdate)
+                await emitSessionUpdate(session.id, modeUpdate);
+            let sessionMeta;
+            if (deps.checkpointReader) {
+                const checkpoints = await deps.checkpointReader.listBySession({
+                    repoPath: params.cwd,
+                    sessionId: session.id,
+                    limit: 1,
+                });
+                const latest = checkpoints.at(-1);
+                sessionMeta = {
+                    salmonloop: {
+                        latestCheckpointId: latest?.id ?? null,
+                        checkpoint: toCheckpointMeta(latest),
+                    },
+                };
+            }
+            return {
+                sessionId: session.id,
+                configOptions: buildConfigOptions(runtimeState),
+                ...(sessionMeta ? { _meta: sessionMeta } : {}),
+            };
+        },
+        async loadSession(params) {
+            if (!loadSessionCapability) {
+                throw new RequestError(-32601, '"Method not found": session/load');
+            }
+            await loadSessionInternal(params);
+            const session = sessions.get(params.sessionId);
+            const runtimeState = ensureSessionRuntimeState(session.id);
+            // Restore plan state if session was running a task
+            if (session.taskId && session.cwd) {
+                await emitRuntimePlanUpdateIfNeeded({
+                    sessionId: session.id,
+                    repoPath: session.cwd,
+                    state: runtimeState,
+                });
+            }
+            const commandsUpdate = buildAvailableCommandsUpdateIfChanged(runtimeState);
+            if (commandsUpdate)
+                await emitSessionUpdate(session.id, commandsUpdate);
+            const modeUpdate = buildCurrentModeUpdateIfChanged(runtimeState);
+            if (modeUpdate)
+                await emitSessionUpdate(session.id, modeUpdate);
+            for (const entry of session.history) {
+                if (entry.role !== 'assistant')
+                    continue;
+                for (const block of entry.content) {
+                    if (block.type === 'text' && typeof block.text === 'string' && block.text.trim()) {
+                        await emitSessionUpdate(session.id, {
+                            sessionUpdate: 'agent_message_chunk',
+                            content: buildTextContentBlock(block.text),
+                        });
+                    }
+                }
+            }
+            const response = {
+                configOptions: buildConfigOptions(runtimeState),
+            };
+            if (deps.checkpointReader) {
+                const startedAt = Date.now();
+                const checkpoints = await deps.checkpointReader.listBySession({
+                    repoPath: params.cwd,
+                    sessionId: params.sessionId,
+                    limit: 1,
+                });
+                const latest = checkpoints.at(-1);
+                let resumeProbe = null;
+                if (latest?.id && deps.checkpointReader.probeById) {
+                    const probed = await deps.checkpointReader.probeById({
+                        repoPath: params.cwd,
+                        checkpointId: latest.id,
+                    });
+                    resumeProbe = {
+                        checkpointId: latest.id,
+                        valid: probed.valid,
+                        reason: probed.reason,
+                    };
+                }
+                else if (latest?.id && deps.checkpointReader.getById) {
+                    const found = await deps.checkpointReader.getById({
+                        repoPath: params.cwd,
+                        checkpointId: latest.id,
+                    });
+                    resumeProbe = {
+                        checkpointId: latest.id,
+                        valid: Boolean(found),
+                        reason: found ? 'ok' : 'not_found',
+                    };
+                }
+                const resumeReady = resumeProbe?.valid ?? Boolean(latest);
+                recordAuditEvent('acp.checkpoint.read', {
+                    sessionId: params.sessionId,
+                    repoPathHash: hashRepoPath(params.cwd),
+                    latestCheckpointId: latest?.id ?? null,
+                    hit: Boolean(latest),
+                    latencyMs: Date.now() - startedAt,
+                    resumeProbe: resumeProbe ?? undefined,
+                }, { source: 'acp', severity: 'low', scope: 'session', phase: 'PREFLIGHT' });
+                const resumeHint = toResumeHint(resumeProbe);
+                response._meta = {
+                    salmonloop: {
+                        latestCheckpointId: latest?.id ?? null,
+                        checkpoint: toCheckpointMeta(latest),
+                        resumeReady,
+                        resumeProbe,
+                        resumeHint: resumeHint?.message ?? null,
+                        resumeHintCode: resumeHint?.code ?? null,
+                    },
+                };
+            }
+            else {
+                recordAuditEvent('acp.checkpoint.read', {
+                    sessionId: params.sessionId,
+                    repoPathHash: hashRepoPath(params.cwd),
+                    latestCheckpointId: null,
+                    hit: false,
+                    reason: 'checkpoint_reader_missing',
+                }, { source: 'acp', severity: 'low', scope: 'session', phase: 'PREFLIGHT' });
+            }
+            return response;
+        },
+        async setSessionConfigOption(params) {
+            await hydrateSessionsOnce();
+            if (!sessions.get(params.sessionId)) {
+                throw new RequestError(-32004, `Session not found: ${params.sessionId}`);
+            }
+            const runtimeState = ensureSessionRuntimeState(params.sessionId);
+            if (params.configId === ACP_PERMISSION_POLICY_CONFIG_ID) {
+                if (!isPermissionPolicyValue(params.value)) {
+                    throw new RequestError(-32602, `Invalid params: unsupported value "${params.value}" for "${params.configId}"`);
+                }
+                runtimeState.permissionPolicy = params.value;
+            }
+            else if (params.configId === ACP_MODE_CONFIG_ID) {
+                if (!isSessionModeId(params.value)) {
+                    throw new RequestError(-32602, `Invalid params: unsupported value "${params.value}" for "${params.configId}"`);
+                }
+                runtimeState.modeId = params.value;
+            }
+            else {
+                throw new RequestError(-32602, `Invalid params: unsupported configId "${params.configId}"`);
+            }
+            sessions.update(params.sessionId, (current) => ({ ...current }));
+            await persistSessionsBestEffort();
+            const update = buildConfigOptionUpdateIfChanged(runtimeState);
+            if (update) {
+                await emitSessionUpdate(params.sessionId, update);
+            }
+            const modeUpdate = buildCurrentModeUpdateIfChanged(runtimeState);
+            if (modeUpdate) {
+                await emitSessionUpdate(params.sessionId, modeUpdate);
+            }
+            return { configOptions: buildConfigOptions(runtimeState) };
+        },
+        async prompt(params) {
+            await hydrateSessionsOnce();
+            const session = sessions.get(params.sessionId);
+            if (!session) {
+                throw new RequestError(-32004, `Session not found: ${params.sessionId}`);
+            }
+            const caps = clientCapabilities ?? defaultClientCapabilities;
+            const fsCaps = caps.fs;
+            const clientExecutionReady = caps.terminal === true && Boolean(fsCaps?.readTextFile) && Boolean(fsCaps?.writeTextFile);
+            const effectiveExecutionBinding = executionBinding === 'client' && !clientExecutionReady ? 'local' : executionBinding;
+            const promptText = extractTextFromPrompt(params.prompt, defaultPromptCapabilities);
+            const runtimeState = ensureSessionRuntimeState(params.sessionId);
+            sessions.update(params.sessionId, (current) => {
+                return {
+                    ...current,
+                    cancelRequested: false,
+                    history: [
+                        ...current.history,
+                        { role: 'user', content: params.prompt },
+                    ],
+                };
+            });
+            await persistSessionsBestEffort();
+            const configUpdate = buildConfigOptionUpdateIfChanged(runtimeState);
+            if (configUpdate) {
+                await emitSessionUpdate(params.sessionId, configUpdate);
+            }
+            const modeUpdate = buildCurrentModeUpdateIfChanged(runtimeState);
+            if (modeUpdate) {
+                await emitSessionUpdate(params.sessionId, modeUpdate);
+            }
+            const commandsUpdate = buildAvailableCommandsUpdateIfChanged(runtimeState);
+            if (commandsUpdate) {
+                await emitSessionUpdate(params.sessionId, commandsUpdate);
+            }
+            const slashInput = extractSlashInput(params.prompt);
+            if (slashInput) {
+                const parsed = parseSlashInput(slashInput);
+                if (parsed.kind === 'slash' &&
+                    parsed.commandName &&
+                    isKnownSlashCommand(parsed.commandName)) {
+                    const responseText = buildSlashHelpMessage();
+                    await emitSessionUpdate(params.sessionId, {
+                        sessionUpdate: 'agent_message_chunk',
+                        content: buildTextContentBlock(ensureMarkdownParagraphBreak(responseText)),
+                    });
+                    sessions.update(params.sessionId, (current) => ({
+                        ...current,
+                        history: [
+                            ...current.history,
+                            { role: 'assistant', content: [buildTextContentBlock(responseText)] },
+                        ],
+                    }));
+                    await persistSessionsBestEffort();
+                    return { stopReason: 'end_turn' };
+                }
+            }
+            const { task, signal } = await deps.facade.createTask({
+                capability: 'patch',
+                request: {
+                    instruction: promptText,
+                    checkpointSessionId: params.sessionId,
+                    repoPath: session.cwd,
+                },
+                commandRunner: effectiveExecutionBinding === 'client'
+                    ? createAcpCommandRunner({ conn: deps.conn, sessionId: params.sessionId })
+                    : undefined,
+                fileSystemOverride: effectiveExecutionBinding === 'client'
+                    ? createAcpFileSystem({ conn: deps.conn, sessionId: params.sessionId })
+                    : undefined,
+                authorizationProvider: createAcpToolAuthorizationProvider({
+                    conn: deps.conn,
+                    sessionId: params.sessionId,
+                    clientCapabilities: caps,
+                    getPermissionPolicy: () => getPermissionPolicyForAuthorization(runtimeState),
+                    enforceClientCapabilities: effectiveExecutionBinding === 'client',
+                }),
+                authorizationMode: 'blocking',
+                onEvent: (event) => {
+                    for (const update of loopEventToSessionUpdates(event, runtimeState)) {
+                        void emitSessionUpdate(params.sessionId, update);
+                    }
+                    void emitRuntimePlanUpdateIfNeeded({
+                        sessionId: params.sessionId,
+                        repoPath: session.cwd,
+                        event,
+                        state: runtimeState,
+                    });
+                },
+            });
+            sessions.update(params.sessionId, (current) => ({ ...current, taskId: task.id }));
+            await persistSessionsBestEffort();
+            if (signal.aborted) {
+                await emitSessionUpdate(params.sessionId, {
+                    sessionUpdate: 'agent_message_chunk',
+                    content: buildTextContentBlock(ensureMarkdownParagraphBreak('Task cancelled.')),
+                });
+                return { stopReason: 'cancelled' };
+            }
+            const terminalEvent = await awaitTerminalEvent({ taskId: task.id, eventBus: deps.eventBus });
+            let stopReason = 'end_turn';
+            let assistantText = 'Task completed.';
+            let assistantMeta;
+            let latest;
+            const cancelRequested = sessions.get(params.sessionId)?.cancelRequested === true;
+            if (cancelRequested) {
+                assistantText = 'Task cancelled.';
+                stopReason = 'cancelled';
+            }
+            else if (terminalEvent?.type === 'task.failed') {
+                latest = await deps.facade.getTask(task.id);
+                const failureMessage = typeof latest?.failure?.message === 'string' ? latest.failure.message : undefined;
+                assistantText = failureMessage ? `Task failed: ${failureMessage}` : 'Task failed.';
+                const inferred = inferTurnStopReasonFromFailure(latest?.failure);
+                if (inferred)
+                    stopReason = inferred;
+            }
+            else if (terminalEvent?.type === 'task.awaiting_input') {
+                assistantText = 'Task awaiting input.';
+                latest = await deps.facade.getTask(task.id);
+                const formatted = latest?.inputRequired
+                    ? formatInputRequiredMessage(latest.inputRequired)
+                    : null;
+                if (formatted)
+                    assistantText = formatted;
+                if (latest?.inputRequired) {
+                    assistantMeta = { inputRequired: latest.inputRequired };
+                }
+            }
+            else if (terminalEvent?.type === 'task.cancelled') {
+                assistantText = 'Task cancelled.';
+                stopReason = 'cancelled';
+            }
+            await emitSessionUpdate(params.sessionId, {
+                sessionUpdate: 'agent_message_chunk',
+                content: buildTextContentBlock(ensureMarkdownParagraphBreak(assistantText)),
+                ...(assistantMeta ? { _meta: assistantMeta } : {}),
+            });
+            if (latest?.inputRequired) {
+                await emitSessionUpdate(params.sessionId, {
+                    sessionUpdate: 'agent_message_chunk',
+                    content: buildJsonResourceContentBlock(latest.inputRequired),
+                });
+            }
+            sessions.update(params.sessionId, (current) => ({
+                ...current,
+                history: [
+                    ...current.history,
+                    { role: 'assistant', content: [buildTextContentBlock(assistantText)] },
+                ],
+            }));
+            await persistSessionsBestEffort();
+            return { stopReason };
+        },
+        async cancel(params) {
+            await hydrateSessionsOnce();
+            const session = sessions.get(params.sessionId);
+            if (!session)
+                return;
+            sessions.update(params.sessionId, (current) => ({ ...current, cancelRequested: true }));
+            await persistSessionsBestEffort();
+            if (session.taskId) {
+                await deps.facade.cancelTask(session.taskId);
+            }
+        },
+        extMethod: async () => ({}),
+        extNotification: async () => { },
+    };
+}
+//# sourceMappingURL=formal-agent.js.map