salmon-loop 0.3.0 → 0.3.1

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

@@ -1,20 +1,22 @@
-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 { toAcpPublicModes } from '../../public-capabilities/projections.js';
 import { buildPublicCapabilityRegistry } from '../../public-capabilities/registry.js';
 import { parseSlashInput } from '../../slash/parser.js';
+import { Phase } from '../../types/runtime.js';
 import { buildCanonicalExecutionRequest } from '../shared/execution-request.js';
 import { parseAcpFlowMode } from '../shared/flow-mode-mapping.js';
+import { probeCheckpoint, probeCheckpointForNewSession, } from './acp-checkpoint-probe.js';
 import { createAcpCommandRunner } from './acp-command-runner.js';
 import { createAcpFileSystem } from './acp-filesystem.js';
+import { createAcpSessionPersistence } from './acp-session-persistence.js';
+import { ACP_PERMISSION_POLICY_ASK, ACP_PERMISSION_POLICY_ALLOW_ALL, ACP_PERMISSION_POLICY_DENY_ALL, hashRepoPath, isPermissionPolicyValue, parseTimestamp, } from './acp-types.js';
 import { createAcpSessionStore, isTerminalTaskEvent } from './handlers.js';
 import { createAcpToolAuthorizationProvider } from './permission-provider.js';
+import { mapToolKind } from './tool-kind-mapping.js';
 function formatInputRequiredMessage(inputRequired) {
     if (!inputRequired || !Array.isArray(inputRequired.questions))
         return null;
@@ -36,9 +38,6 @@ function formatInputRequiredMessage(inputRequired) {
 }
 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_PERMISSION_POLICY_ALLOW_ALL = 'allow_all';
 const ACP_DEFAULT_MODE_ID = 'autopilot';
 const ACP_SESSION_STORE_MAX_ENTRIES = 200;
 const ACP_SESSION_STORE_MAX_AGE_MS = 1000 * 60 * 60 * 24 * 30;
@@ -46,6 +45,8 @@ 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;
+const ACP_SESSION_LIST_PAGE_SIZE = 50;
+const ACP_SUPPORTED_PROTOCOL_VERSIONS = new Set([PROTOCOL_VERSION]);
 function isAbsolutePath(filePath) {
     if (defaultPathAdapter.isAbsolute(filePath))
         return true;
@@ -86,6 +87,33 @@ function buildJsonResourceContentBlock(data) {
         },
     };
 }
+function encodeSessionListCursor(input) {
+    return `${input.offset}:${input.cwd ?? ''}`;
+}
+function decodeSessionListCursor(cursor) {
+    const colon = cursor.indexOf(':');
+    if (colon < 0) {
+        throw new RequestError(-32602, 'Invalid params: invalid session/list cursor');
+    }
+    const offset = Number(cursor.slice(0, colon));
+    if (!Number.isInteger(offset) || offset < 0) {
+        throw new RequestError(-32602, 'Invalid params: invalid session/list cursor');
+    }
+    const cwd = cursor.slice(colon + 1) || null;
+    return { offset, cwd };
+}
+function isReplayableSessionContentBlock(block) {
+    if (!block || typeof block !== 'object')
+        return false;
+    switch (block.type) {
+        case 'text':
+            return typeof block.text === 'string';
+        case 'resource_link':
+            return typeof block.name === 'string' && typeof block.uri === 'string';
+        default:
+            return false;
+    }
+}
 const ACP_AVAILABLE_COMMANDS = [
     { name: 'help', description: text.acp.slashHelpDescription },
 ];
@@ -130,17 +158,17 @@ function extractTextFromPrompt(prompt, capabilities) {
                 break;
             case 'image':
                 if (!capabilities.image) {
-                    throw new RequestError(-32000, 'Prompt content type image is not supported');
+                    throw new RequestError(-32602, 'Prompt content type image is not supported');
                 }
                 break;
             case 'audio':
                 if (!capabilities.audio) {
-                    throw new RequestError(-32000, 'Prompt content type audio is not supported');
+                    throw new RequestError(-32602, 'Prompt content type audio is not supported');
                 }
                 break;
             case 'resource':
                 if (!capabilities.embeddedContext) {
-                    throw new RequestError(-32000, 'Prompt content type resource is not supported');
+                    throw new RequestError(-32602, 'Prompt content type resource is not supported');
                 }
                 parts.push(formatEmbeddedResource(block));
                 break;
@@ -150,46 +178,6 @@ function extractTextFromPrompt(prompt, capabilities) {
     }
     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) }];
 }
@@ -236,7 +224,7 @@ function loopEventToSessionUpdate(event) {
                 toolCallId: event.callId,
                 status: 'pending',
                 title: event.toolName,
-                kind: mapToolKind(event.toolName, event.toolIntent),
+                kind: mapToolKind(event.toolName, { intent: event.toolIntent }),
                 content: [],
                 rawInput: event.input,
                 locations: extractLocationFromInput(event.input),
@@ -259,11 +247,6 @@ function loopEventToSessionUpdate(event) {
             return null;
     }
 }
-function isPermissionPolicyValue(value) {
-    return (value === ACP_PERMISSION_POLICY_ASK ||
-        value === ACP_PERMISSION_POLICY_DENY_ALL ||
-        value === ACP_PERMISSION_POLICY_ALLOW_ALL);
-}
 function buildConfigOptions(state) {
     return [
         {
@@ -293,8 +276,8 @@ function buildConfigOptions(state) {
         {
             type: 'select',
             id: ACP_MODE_CONFIG_ID,
-            name: 'Execution Flow',
-            description: 'Choose how the agent should execute this session.',
+            name: text.acp.executionFlowName,
+            description: text.acp.executionFlowDescription,
             currentValue: state.modeId,
             options: ACP_PUBLIC_MODES.map((mode) => ({
                 value: mode.id,
@@ -355,16 +338,6 @@ function buildCurrentModeUpdateIfChanged(state) {
     state.lastModeDigest = digest;
     return buildCurrentModeUpdate(state.modeId);
 }
-function getLegacyPermissionPolicyForModeValue(value) {
-    const normalized = String(value ?? '')
-        .trim()
-        .toLowerCase();
-    if (normalized === 'interactive')
-        return ACP_PERMISSION_POLICY_ASK;
-    if (normalized === 'yolo')
-        return ACP_PERMISSION_POLICY_ALLOW_ALL;
-    return null;
-}
 function getPermissionPolicyForAuthorization(state) {
     return state.permissionPolicy;
 }
@@ -466,19 +439,36 @@ function buildPlanUpdateFromCoreIfChanged(read, state) {
         entries,
     };
 }
-function envListToRecord(env) {
+function namedPairsToRecord(pairs) {
     const record = {};
-    for (const entry of env) {
+    for (const entry of pairs) {
         record[entry.name] = entry.value;
     }
     return record;
 }
-function headersListToRecord(headers) {
-    const record = {};
-    for (const entry of headers) {
-        record[entry.name] = entry.value;
-    }
-    return record;
+function defaultAcpMcpCapabilities() {
+    return {
+        tools: {
+            exposeToModel: true,
+            allow: ['*'],
+            phases: [Phase.VERIFY],
+            approval: 'ask',
+        },
+        resources: {
+            allowUris: [],
+            autoInclude: false,
+            subscribe: false,
+            maxBytes: 64_000,
+            ttlMs: 30_000,
+        },
+        prompts: {
+            exposeAs: 'none',
+            allow: [],
+        },
+        roots: { mode: 'none' },
+        sampling: { enabled: false, maxTokens: 0, maxDepth: 0 },
+        elicitation: { enabled: false },
+    };
 }
 function acpMcpServersToResolved(mcpServers) {
     if (!Array.isArray(mcpServers))
@@ -494,11 +484,14 @@ function acpMcpServersToResolved(mcpServers) {
             resolved.push({
                 name: httpServer.name,
                 enabled: true,
-                transport: 'http',
-                url: httpServer.url,
-                headers: headersListToRecord(httpServer.headers),
-                allowTools: ['*'],
-                allowResources: [],
+                transport: {
+                    type: 'http',
+                    url: httpServer.url,
+                    headers: namedPairsToRecord(httpServer.headers),
+                },
+                auth: { type: 'none', scopes: [] },
+                trust: 'remote',
+                capabilities: defaultAcpMcpCapabilities(),
                 scope: 'repo',
             });
             continue;
@@ -510,12 +503,15 @@ function acpMcpServersToResolved(mcpServers) {
         resolved.push({
             name: stdioServer.name,
             enabled: true,
-            transport: 'stdio',
-            command: stdioServer.command,
-            args: stdioServer.args,
-            env: envListToRecord(stdioServer.env),
-            allowTools: ['*'],
-            allowResources: [],
+            transport: {
+                type: 'stdio',
+                command: stdioServer.command,
+                args: stdioServer.args,
+                env: namedPairsToRecord(stdioServer.env),
+            },
+            auth: { type: 'none', scopes: [] },
+            trust: 'local',
+            capabilities: defaultAcpMcpCapabilities(),
             scope: 'repo',
         });
     }
@@ -534,6 +530,17 @@ function acpMcpServersToExtensions(mcpServers) {
 function validateAcpMcpServers(mcpServers) {
     void acpMcpServersToResolved(mcpServers);
 }
+function validateUnsupportedAdditionalDirectories(additionalDirectories) {
+    if (Array.isArray(additionalDirectories) && additionalDirectories.length > 0) {
+        throw new RequestError(-32602, 'Invalid params: additionalDirectories is not supported by this agent');
+    }
+}
+function negotiateProtocolVersion(clientProtocolVersion) {
+    if (ACP_SUPPORTED_PROTOCOL_VERSIONS.has(clientProtocolVersion)) {
+        return clientProtocolVersion;
+    }
+    return PROTOCOL_VERSION;
+}
 function extractSlashInput(prompt) {
     if (prompt.length !== 1)
         return null;
@@ -556,6 +563,9 @@ function isKnownSlashCommand(commandName) {
     const normalized = normalizeSlashName(commandName);
     return ACP_AVAILABLE_COMMANDS.some((cmd) => cmd.name.toLowerCase() === normalized);
 }
+function isPersistableSession(session) {
+    return session.materialized || session.history.length > 0 || typeof session.taskId === 'string';
+}
 async function awaitTerminalEvent(params) {
     if (!params.eventBus)
         return null;
@@ -603,368 +613,17 @@ export function createAcpFormalAgent(deps) {
         lockAcquireTimeoutMs: deps.sessionStorePolicy?.lockAcquireTimeoutMs ?? ACP_SESSION_STORE_LOCK_ACQUIRE_TIMEOUT_MS,
     };
     const executionBinding = deps.executionBinding ?? 'local';
-    let sessionsHydrated = false;
-    let hydratePromise = null;
-    const deletedSessionIds = new Map();
-    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 normalizeDeletedSessionRecords(input) {
-        if (!Array.isArray(input))
-            return [];
-        const byId = new Map();
-        for (const entry of input) {
-            if (!entry || typeof entry !== 'object')
-                continue;
-            const record = entry;
-            if (typeof record.id !== 'string' || !record.id)
-                continue;
-            if (typeof record.deletedAt !== 'string' || !record.deletedAt)
-                continue;
-            const current = byId.get(record.id);
-            if (!current || parseTimestamp(record.deletedAt) > parseTimestamp(current.deletedAt)) {
-                byId.set(record.id, { id: record.id, deletedAt: record.deletedAt });
-            }
-        }
-        return Array.from(byId.values());
-    }
-    function pruneDeletedSessionRecords(records) {
-        const cutoff = Date.now() - sessionStorePolicy.maxAgeMs;
-        return normalizeDeletedSessionRecords(records)
-            .filter((record) => parseTimestamp(record.deletedAt) >= cutoff)
-            .sort((a, b) => parseTimestamp(b.deletedAt) - parseTimestamp(a.deletedAt));
-    }
-    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: isPermissionPolicyValue(String(deps.defaultPermissionPolicy))
-                        ? deps.defaultPermissionPolicy
-                        : ACP_PERMISSION_POLICY_ASK,
-                    modeId: resolveExposedAcpModeId(deps.defaultModeId),
-                })),
-                deletedSessions: [],
-            };
-        }
-        if (raw.schemaVersion === 2) {
-            return {
-                schemaVersion: 2,
-                sessions: raw.sessions,
-                deletedSessions: pruneDeletedSessionRecords(raw.deletedSessions),
-            };
-        }
-        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 payloadDeletedSessions = pruneDeletedSessionRecords(Array.from(deletedSessionIds, ([id, deletedAt]) => ({ id, deletedAt })));
-        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();
-                const mergedDeletedSessions = pruneDeletedSessionRecords([
-                    ...(existing.deletedSessions ?? []),
-                    ...payloadDeletedSessions,
-                ]);
-                const mergedDeletedIds = new Set(mergedDeletedSessions.map((record) => record.id));
-                for (const record of mergedDeletedSessions) {
-                    deletedSessionIds.set(record.id, record.deletedAt);
-                }
-                for (const entry of existing.sessions)
-                    merged.set(entry.id, entry);
-                for (const entry of payload.sessions)
-                    merged.set(entry.id, entry);
-                for (const id of mergedDeletedIds)
-                    merged.delete(id);
-                const mergedPayload = {
-                    schemaVersion: 2,
-                    sessions: pruneSessionRecords(Array.from(merged.values())),
-                    deletedSessions: mergedDeletedSessions,
-                };
-                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));
-                const deletedIds = new Set(parsed.deletedSessions?.map((record) => record.id) ?? []);
-                for (const record of parsed.deletedSessions ?? []) {
-                    deletedSessionIds.set(record.id, record.deletedAt);
-                }
-                for (const stored of pruneSessionRecords(parsed.sessions)) {
-                    if (deletedIds.has(stored.id))
-                        continue;
-                    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,
-                            defaultPermissionPolicy: deps.defaultPermissionPolicy,
-                            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.',
-                };
-        }
-    }
+    const sessionPersistence = createAcpSessionPersistence({
+        path: sessionPersistencePath ?? '',
+        storePolicy: sessionStorePolicy,
+        defaultPermissionPolicy: deps.defaultPermissionPolicy ?? ACP_PERMISSION_POLICY_ASK,
+        defaultModeId: deps.defaultModeId,
+        sessions,
+        sessionRuntime,
+        isPersistableSession,
+        ensureSessionRuntimeState,
+        resolveExposedAcpModeId,
+    });
     async function emitSessionUpdate(sessionId, update) {
         await deps.conn.sessionUpdate({ sessionId, update });
     }
@@ -987,15 +646,13 @@ export function createAcpFormalAgent(deps) {
         if (!shouldRefreshPlanForEvent(params.event))
             return;
         const { state, event } = params;
-        const planReader = deps.planReader ?? {
-            readBySession: async ({ repoPath, sessionId }) => await readPlan({ persistenceRoot: repoPath, sessionId }),
-        };
+        const planReader = deps.planReader;
         if (event?.type === 'plan.runtime.ready') {
             state.runtimePlanSessionId = event.sessionId;
             state.runtimePlanPathHint = event.planPathHint;
             state.lastPlanDigest = null;
         }
-        if (!state.runtimePlanSessionId)
+        if (!state.runtimePlanSessionId || !planReader)
             return;
         try {
             const read = await planReader.readBySession({
@@ -1017,8 +674,9 @@ export function createAcpFormalAgent(deps) {
             }, { source: 'acp', severity: 'low', scope: 'session', phase: 'PLAN' });
         }
     }
-    async function loadSessionInternal(params) {
-        await hydrateSessionsOnce();
+    async function resolveExistingSession(params) {
+        await sessionPersistence.hydrate();
+        validateUnsupportedAdditionalDirectories(params.additionalDirectories);
         validateAcpMcpServers(params.mcpServers);
         const session = sessions.get(params.sessionId);
         if (!session) {
@@ -1028,30 +686,12 @@ export function createAcpFormalAgent(deps) {
             throw new RequestError(-32602, 'Invalid params: cwd does not match session cwd');
         }
         if (params.mcpServers) {
+            const mcpServers = params.mcpServers;
             sessions.update(params.sessionId, (current) => ({
                 ...current,
-                mcpServers: params.mcpServers,
+                mcpServers,
             }));
-            await persistSessionsBestEffort();
-        }
-        return session;
-    }
-    async function resumeSessionInternal(params) {
-        await hydrateSessionsOnce();
-        validateAcpMcpServers(params.mcpServers);
-        const session = sessions.get(params.sessionId);
-        if (!session) {
-            throw new RequestError(-32004, `Session not found: ${params.sessionId}`);
-        }
-        if (session.cwd !== params.cwd) {
-            throw new RequestError(-32602, 'Invalid params: cwd does not match session cwd');
-        }
-        if (params.mcpServers) {
-            sessions.update(params.sessionId, (current) => ({
-                ...current,
-                mcpServers: params.mcpServers ?? [],
-            }));
-            await persistSessionsBestEffort();
+            await sessionPersistence.persist();
         }
         return session;
     }
@@ -1067,29 +707,62 @@ export function createAcpFormalAgent(deps) {
         const existing = sessionRuntime.get(sessionId);
         if (existing)
             return existing;
+        const session = sessions.get(sessionId);
         const created = createSessionRuntimeStateFromPersisted({
+            permissionPolicy: session?.permissionPolicy,
             defaultPermissionPolicy: deps.defaultPermissionPolicy,
+            modeId: session?.modeId,
             defaultModeId: deps.defaultModeId,
         });
         sessionRuntime.set(sessionId, created);
         return created;
     }
+    async function cancelSessionTaskBestEffort(session) {
+        sessions.update(session.id, (current) => ({ ...current, cancelRequested: true }));
+        if (session.taskId) {
+            await deps.facade.cancelTask(session.taskId);
+        }
+    }
+    async function closeSessionRecord(params) {
+        const session = sessions.get(params.sessionId);
+        if (!session)
+            return;
+        const runtimeState = ensureSessionRuntimeState(params.sessionId);
+        sessions.update(params.sessionId, (current) => ({
+            ...current,
+            permissionPolicy: runtimeState.permissionPolicy,
+            modeId: runtimeState.modeId,
+        }));
+        await cancelSessionTaskBestEffort(session);
+        const latestSession = sessions.get(params.sessionId) ?? session;
+        if (!isPersistableSession(latestSession)) {
+            sessionRuntime.delete(params.sessionId);
+            sessions.delete(params.sessionId);
+            await sessionPersistence.persist();
+            return;
+        }
+        sessions.update(params.sessionId, (current) => ({ ...current, cancelRequested: false }));
+        await sessionPersistence.persist();
+        sessionRuntime.delete(params.sessionId);
+    }
+    async function deleteSessionRecord(params) {
+        const session = sessions.get(params.sessionId);
+        if (!session)
+            return;
+        await cancelSessionTaskBestEffort(session);
+        sessionPersistence.markDeleted(params.sessionId);
+        sessionRuntime.delete(params.sessionId);
+        sessions.delete(params.sessionId);
+        await sessionPersistence.persist();
+    }
     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;
-            // Protocol version negotiation:
-            // - If the client's requested version is supported, return the same version
-            // - Otherwise, return the latest version the agent supports
-            // Currently, the agent only supports protocol version 1
-            const supportedProtocolVersion = PROTOCOL_VERSION;
-            const negotiatedVersion = params.protocolVersion <= supportedProtocolVersion
-                ? params.protocolVersion
-                : supportedProtocolVersion;
             return {
-                protocolVersion: negotiatedVersion,
+                protocolVersion: negotiateProtocolVersion(params.protocolVersion),
                 agentInfo: deps.agentInfo,
                 authMethods: [],
                 agentCapabilities: {
@@ -1100,25 +773,30 @@ export function createAcpFormalAgent(deps) {
                         list: {},
                         resume: {},
                         close: {},
+                        delete: {},
                     },
                 },
             };
         },
-        async authenticate() {
-            return;
+        async authenticate(params) {
+            throw new RequestError(-32602, `Invalid params: unsupported auth methodId "${params.methodId}"`);
         },
         async newSession(params) {
-            await hydrateSessionsOnce();
+            await sessionPersistence.hydrate();
             if (!isAbsolutePath(params.cwd)) {
                 throw new RequestError(-32602, 'Invalid params: cwd must be an absolute path');
             }
+            validateUnsupportedAdditionalDirectories(params.additionalDirectories);
             validateAcpMcpServers(params.mcpServers);
             const session = sessions.create({
                 cwd: params.cwd,
                 mcpServers: params.mcpServers ?? [],
                 title: deriveSessionTitleFromCwd(params.cwd),
+                permissionPolicy: isPermissionPolicyValue(String(deps.defaultPermissionPolicy))
+                    ? deps.defaultPermissionPolicy
+                    : ACP_PERMISSION_POLICY_ASK,
+                modeId: resolveExposedAcpModeId(deps.defaultModeId),
             });
-            await persistSessionsBestEffort();
             const runtimeState = ensureSessionRuntimeState(session.id);
             await emitSessionInfoUpdateBestEffort(session.id);
             // Restore session state on creation
@@ -1130,18 +808,11 @@ export function createAcpFormalAgent(deps) {
                 await emitSessionUpdate(session.id, modeUpdate);
             let sessionMeta;
             if (deps.checkpointReader) {
-                const checkpoints = await deps.checkpointReader.listBySession({
+                const result = await probeCheckpointForNewSession(deps.checkpointReader, {
                     repoPath: params.cwd,
                     sessionId: session.id,
-                    limit: 1,
                 });
-                const latest = checkpoints.at(-1);
-                sessionMeta = {
-                    salmonloop: {
-                        latestCheckpointId: latest?.id ?? null,
-                        checkpoint: toCheckpointMeta(latest),
-                    },
-                };
+                sessionMeta = result._meta;
             }
             return {
                 sessionId: session.id,
@@ -1152,9 +823,9 @@ export function createAcpFormalAgent(deps) {
         },
         async loadSession(params) {
             if (!loadSessionCapability) {
-                throw new RequestError(-32601, '"Method not found": session/load');
+                throw new RequestError(-32601, 'Method not found: session/load');
             }
-            await loadSessionInternal(params);
+            await resolveExistingSession(params);
             let session = sessions.get(params.sessionId);
             const runtimeState = ensureSessionRuntimeState(session.id);
             if (typeof session.title !== 'string' || !session.title.trim()) {
@@ -1163,7 +834,7 @@ export function createAcpFormalAgent(deps) {
                         ...current,
                         title: deriveSessionTitleFromCwd(current.cwd),
                     })) ?? session;
-                await persistSessionsBestEffort();
+                await sessionPersistence.persist();
             }
             runtimeState.lastSessionInfoDigest = null;
             await emitSessionInfoUpdateBestEffort(session.id);
@@ -1183,10 +854,10 @@ export function createAcpFormalAgent(deps) {
                 await emitSessionUpdate(session.id, modeUpdate);
             for (const entry of session.history) {
                 for (const block of entry.content) {
-                    if (block.type === 'text' && typeof block.text === 'string' && block.text.trim()) {
+                    if (isReplayableSessionContentBlock(block)) {
                         await emitSessionUpdate(session.id, {
                             sessionUpdate: entry.role === 'assistant' ? 'agent_message_chunk' : 'user_message_chunk',
-                            content: buildTextContentBlock(block.text),
+                            content: block,
                         });
                     }
                 }
@@ -1196,56 +867,12 @@ export function createAcpFormalAgent(deps) {
                 modes: buildModesState(runtimeState.modeId),
             };
             if (deps.checkpointReader) {
-                const startedAt = Date.now();
-                const checkpoints = await deps.checkpointReader.listBySession({
+                const result = await probeCheckpoint(deps.checkpointReader, {
                     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,
-                    },
-                };
+                });
+                response._meta = result._meta;
             }
             else {
                 recordAuditEvent('acp.checkpoint.read', {
@@ -1259,23 +886,39 @@ export function createAcpFormalAgent(deps) {
             return response;
         },
         async listSessions(params) {
-            await hydrateSessionsOnce();
+            await sessionPersistence.hydrate();
             if (typeof params.cwd === 'string' && params.cwd && !isAbsolutePath(params.cwd)) {
                 throw new RequestError(-32602, 'Invalid params: cwd must be an absolute path');
             }
+            const cwdFilter = typeof params.cwd === 'string' && params.cwd ? params.cwd : null;
+            let offset = 0;
+            if (typeof params.cursor === 'string' && params.cursor) {
+                const decodedCursor = decodeSessionListCursor(params.cursor);
+                if (decodedCursor.cwd !== cwdFilter) {
+                    throw new RequestError(-32602, 'Invalid params: cursor does not match cwd filter');
+                }
+                offset = decodedCursor.offset;
+            }
             const filtered = sessions
                 .list()
-                .filter((session) => !params.cwd || session.cwd === params.cwd)
+                .filter((session) => !cwdFilter || session.cwd === cwdFilter)
                 .sort((a, b) => parseTimestamp(b.updatedAt) - parseTimestamp(a.updatedAt));
+            const page = filtered.slice(offset, offset + ACP_SESSION_LIST_PAGE_SIZE);
+            const nextOffset = offset + page.length;
+            const nextCursor = nextOffset < filtered.length
+                ? encodeSessionListCursor({ offset: nextOffset, cwd: cwdFilter })
+                : undefined;
             return {
-                sessions: filtered.map(toSessionInfo),
+                sessions: page.map(toSessionInfo),
+                ...(nextCursor ? { nextCursor } : {}),
             };
         },
         async resumeSession(params) {
-            const session = await resumeSessionInternal({
+            const session = await resolveExistingSession({
                 sessionId: params.sessionId,
                 cwd: params.cwd,
                 mcpServers: params.mcpServers,
+                additionalDirectories: params.additionalDirectories,
             });
             const runtimeState = ensureSessionRuntimeState(session.id);
             runtimeState.lastSessionInfoDigest = null;
@@ -1286,57 +929,64 @@ export function createAcpFormalAgent(deps) {
             const modeUpdate = buildCurrentModeUpdateIfChanged(runtimeState);
             if (modeUpdate)
                 await emitSessionUpdate(session.id, modeUpdate);
-            return {
+            const response = {
                 configOptions: buildConfigOptions(runtimeState),
                 modes: buildModesState(runtimeState.modeId),
             };
+            if (deps.checkpointReader) {
+                const result = await probeCheckpoint(deps.checkpointReader, {
+                    repoPath: session.cwd,
+                    sessionId: params.sessionId,
+                    repoPathHash: hashRepoPath(session.cwd),
+                });
+                response._meta = result._meta;
+            }
+            return response;
         },
         async closeSession(params) {
-            await hydrateSessionsOnce();
-            const session = sessions.get(params.sessionId);
-            if (!session)
-                return {};
-            sessions.update(params.sessionId, (current) => ({ ...current, cancelRequested: true }));
-            if (session.taskId) {
-                await deps.facade.cancelTask(session.taskId);
-            }
-            deletedSessionIds.set(params.sessionId, new Date().toISOString());
-            sessionRuntime.delete(params.sessionId);
-            sessions.delete(params.sessionId);
-            await persistSessionsBestEffort();
+            await sessionPersistence.hydrate();
+            await closeSessionRecord({ sessionId: params.sessionId });
+            return {};
+        },
+        async unstable_deleteSession(params) {
+            await sessionPersistence.hydrate();
+            await deleteSessionRecord({ sessionId: params.sessionId });
             return {};
         },
         async setSessionConfigOption(params) {
-            await hydrateSessionsOnce();
+            await sessionPersistence.hydrate();
             if (!sessions.get(params.sessionId)) {
                 throw new RequestError(-32004, `Session not found: ${params.sessionId}`);
             }
             const runtimeState = ensureSessionRuntimeState(params.sessionId);
-            if (typeof params.value !== 'string') {
-                throw new RequestError(-32602, `Invalid params: unsupported non-string value for "${params.configId}"`);
-            }
             if (params.configId === ACP_PERMISSION_POLICY_CONFIG_ID) {
+                if (typeof params.value !== 'string') {
+                    throw new RequestError(-32602, `Invalid params: "${params.configId}" does not support boolean values`);
+                }
                 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 (typeof params.value !== 'string') {
+                    throw new RequestError(-32602, `Invalid params: "${params.configId}" does not support boolean values`);
+                }
                 const parsedModeId = parseAcpFlowMode(params.value);
                 if (!parsedModeId || !ACP_PUBLIC_MODE_IDS.has(parsedModeId)) {
                     throw new RequestError(-32602, `Invalid params: unsupported value "${params.value}" for "${params.configId}"`);
                 }
                 runtimeState.modeId = parsedModeId;
-                const legacyPermissionPolicy = getLegacyPermissionPolicyForModeValue(params.value);
-                if (legacyPermissionPolicy) {
-                    runtimeState.permissionPolicy = legacyPermissionPolicy;
-                }
             }
             else {
                 throw new RequestError(-32602, `Invalid params: unsupported configId "${params.configId}"`);
             }
-            sessions.update(params.sessionId, (current) => ({ ...current }));
-            await persistSessionsBestEffort();
+            sessions.update(params.sessionId, (current) => ({
+                ...current,
+                permissionPolicy: runtimeState.permissionPolicy,
+                modeId: runtimeState.modeId,
+            }));
+            await sessionPersistence.persist();
             await emitSessionInfoUpdateBestEffort(params.sessionId);
             const update = buildConfigOptionUpdateIfChanged(runtimeState);
             if (update) {
@@ -1349,7 +999,7 @@ export function createAcpFormalAgent(deps) {
             return { configOptions: buildConfigOptions(runtimeState) };
         },
         async setSessionMode(params) {
-            await hydrateSessionsOnce();
+            await sessionPersistence.hydrate();
             if (!sessions.get(params.sessionId)) {
                 throw new RequestError(-32004, `Session not found: ${params.sessionId}`);
             }
@@ -1359,12 +1009,12 @@ export function createAcpFormalAgent(deps) {
                 throw new RequestError(-32602, `Invalid params: unsupported modeId "${params.modeId}"`);
             }
             runtimeState.modeId = resolvedModeId;
-            const legacyPermissionPolicy = getLegacyPermissionPolicyForModeValue(params.modeId);
-            if (legacyPermissionPolicy) {
-                runtimeState.permissionPolicy = legacyPermissionPolicy;
-            }
-            sessions.update(params.sessionId, (current) => ({ ...current }));
-            await persistSessionsBestEffort();
+            sessions.update(params.sessionId, (current) => ({
+                ...current,
+                permissionPolicy: runtimeState.permissionPolicy,
+                modeId: runtimeState.modeId,
+            }));
+            await sessionPersistence.persist();
             await emitSessionInfoUpdateBestEffort(params.sessionId);
             const configUpdate = buildConfigOptionUpdateIfChanged(runtimeState);
             if (configUpdate) {
@@ -1378,7 +1028,7 @@ export function createAcpFormalAgent(deps) {
             return {};
         },
         async prompt(params) {
-            await hydrateSessionsOnce();
+            await sessionPersistence.hydrate();
             const session = sessions.get(params.sessionId);
             if (!session) {
                 throw new RequestError(-32004, `Session not found: ${params.sessionId}`);
@@ -1391,7 +1041,10 @@ export function createAcpFormalAgent(deps) {
             const runtimeState = ensureSessionRuntimeState(params.sessionId);
             // Check for cancellation before starting processing
             if (sessions.get(params.sessionId)?.cancelRequested === true) {
-                return { stopReason: 'cancelled' };
+                return {
+                    stopReason: 'cancelled',
+                    ...(params.messageId ? { userMessageId: params.messageId } : {}),
+                };
             }
             sessions.update(params.sessionId, (current) => {
                 const title = typeof current.title === 'string' && current.title.trim()
@@ -1401,13 +1054,16 @@ export function createAcpFormalAgent(deps) {
                     ...current,
                     cancelRequested: false,
                     title,
+                    materialized: true,
+                    permissionPolicy: runtimeState.permissionPolicy,
+                    modeId: runtimeState.modeId,
                     history: [
                         ...current.history,
                         { role: 'user', content: params.prompt },
                     ],
                 };
             });
-            await persistSessionsBestEffort();
+            await sessionPersistence.persist();
             await emitSessionInfoUpdateBestEffort(params.sessionId);
             const configUpdate = buildConfigOptionUpdateIfChanged(runtimeState);
             if (configUpdate) {
@@ -1439,14 +1095,20 @@ export function createAcpFormalAgent(deps) {
                             { role: 'assistant', content: [buildTextContentBlock(responseText)] },
                         ],
                     }));
-                    await persistSessionsBestEffort();
+                    await sessionPersistence.persist();
                     await emitSessionInfoUpdateBestEffort(params.sessionId);
-                    return { stopReason: 'end_turn' };
+                    return {
+                        stopReason: 'end_turn',
+                        ...(params.messageId ? { userMessageId: params.messageId } : {}),
+                    };
                 }
             }
             // Check for cancellation again before creating task
             if (sessions.get(params.sessionId)?.cancelRequested === true) {
-                return { stopReason: 'cancelled' };
+                return {
+                    stopReason: 'cancelled',
+                    ...(params.messageId ? { userMessageId: params.messageId } : {}),
+                };
             }
             const pendingUpdates = [];
             const executionRequest = buildCanonicalExecutionRequest({
@@ -1489,34 +1151,39 @@ export function createAcpFormalAgent(deps) {
                 },
             });
             sessions.update(params.sessionId, (current) => ({ ...current, taskId: task.id }));
-            await persistSessionsBestEffort();
+            await sessionPersistence.persist();
             if (signal.aborted) {
                 await emitSessionUpdate(params.sessionId, {
                     sessionUpdate: 'agent_message_chunk',
-                    content: buildTextContentBlock(ensureMarkdownParagraphBreak('Task cancelled.')),
+                    content: buildTextContentBlock(ensureMarkdownParagraphBreak(text.acp.taskCancelled)),
                 });
-                return { stopReason: 'cancelled' };
+                return {
+                    stopReason: 'cancelled',
+                    ...(params.messageId ? { userMessageId: params.messageId } : {}),
+                };
             }
             const terminalEvent = await awaitTerminalEvent({ taskId: task.id, eventBus: deps.eventBus });
             let stopReason = 'end_turn';
-            let assistantText = 'Task completed.';
+            let assistantText = text.acp.taskCompleted;
             let assistantMeta;
             let latest;
             const cancelRequested = sessions.get(params.sessionId)?.cancelRequested === true;
             if (cancelRequested) {
-                assistantText = 'Task cancelled.';
+                assistantText = text.acp.taskCancelled;
                 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.';
+                assistantText = failureMessage
+                    ? text.acp.taskFailedWithReason(failureMessage)
+                    : text.acp.taskFailed;
                 const inferred = inferTurnStopReasonFromFailure(latest?.failure);
                 if (inferred)
                     stopReason = inferred;
             }
             else if (terminalEvent?.type === 'task.awaiting_input') {
-                assistantText = 'Task awaiting input.';
+                assistantText = text.acp.taskAwaitingInput;
                 latest = await deps.facade.getTask(task.id);
                 const formatted = latest?.inputRequired
                     ? formatInputRequiredMessage(latest.inputRequired)
@@ -1528,7 +1195,7 @@ export function createAcpFormalAgent(deps) {
                 }
             }
             else if (terminalEvent?.type === 'task.cancelled') {
-                assistantText = 'Task cancelled.';
+                assistantText = text.acp.taskCancelled;
                 stopReason = 'cancelled';
             }
             await emitSessionUpdate(params.sessionId, {
@@ -1549,7 +1216,7 @@ export function createAcpFormalAgent(deps) {
                     { role: 'assistant', content: [buildTextContentBlock(assistantText)] },
                 ],
             }));
-            await persistSessionsBestEffort();
+            await sessionPersistence.persist();
             const latestSession = sessions.get(params.sessionId);
             if (latestSession) {
                 const sessionInfoUpdate = buildSessionInfoUpdateIfChanged(latestSession, runtimeState);
@@ -1561,16 +1228,19 @@ export function createAcpFormalAgent(deps) {
             }
             // Wait for all pending session updates to be sent before responding
             await Promise.all(pendingUpdates);
-            return { stopReason };
+            return {
+                stopReason,
+                ...(params.messageId ? { userMessageId: params.messageId } : {}),
+            };
         },
         async cancel(params) {
-            await hydrateSessionsOnce();
+            await sessionPersistence.hydrate();
             const session = sessions.get(params.sessionId);
             if (!session)
                 return;
             // Mark the session as cancelled
             sessions.update(params.sessionId, (current) => ({ ...current, cancelRequested: true }));
-            await persistSessionsBestEffort();
+            await sessionPersistence.persist();
             await emitSessionInfoUpdateBestEffort(params.sessionId);
             // If a task is running, cancel it
             if (session.taskId) {
@@ -1579,8 +1249,6 @@ export function createAcpFormalAgent(deps) {
             // Note: The prompt method will check the cancelRequested flag and return
             // StopReason::Cancelled as required by the protocol
         },
-        extMethod: async () => ({}),
-        extNotification: async () => { },
     };
 }
 //# sourceMappingURL=formal-agent.js.map