dsh-acp-replay 0.1.0

package/lib/index.js

@@ -0,0 +1,549 @@
+/**
+ * Automation-only Agent Client Protocol server over JSON-RPC stdio.
+ *
+ * The bridge exposes persistent harness sessions to trusted programmatic
+ * clients. It carries standard configuration, MCP mounts, prompt content,
+ * committed semantic updates, cancellation, and one-shot permission decisions;
+ * presentation and human-interaction features stay with the harness's UI modules.
+ *
+ * @module @deepseek-ai/dsh-acp
+ */
+import { Buffer } from 'node:buffer';
+import { randomUUID } from 'node:crypto';
+import { realpath } from 'node:fs/promises';
+import { isAbsolute, resolve } from 'node:path';
+import { Readable, Writable } from 'node:stream';
+import Schema from '@deepseek-ai/schemastery';
+import { brandString } from '@deepseek-ai/dsh-brand';
+import { errorChain } from '@deepseek-ai/dsh-llm';
+import { agent as createAcpAgentApp, methods, ndJsonStream, PROTOCOL_VERSION, RequestError, } from '@agentclientprotocol/sdk';
+import { supportsAcpImagePrompts } from "./content.js";
+import { AcpMcpConfigError } from "./mcp.js";
+import { AcpModelConfigError } from "./model-control.js";
+import { assertReplayHostSupport } from "./compat.js";
+import { replaySessionUpdates } from "./replay.js";
+import { AcpSession } from "./session.js";
+const DEFAULT_SESSION_LIST_PAGE_SIZE = 100;
+export const name = 'acp-replay';
+/** Core services required by the standard automation controls. */
+export const inject = ['agents', 'llm', 'sessionPersistence', 'sessions'];
+/** Preserve invalid-parameter detail in the SDK wire error message. */
+function invalidParams(detail) {
+    return RequestError.invalidParams(undefined, detail);
+}
+/** Preserve failed-turn detail; plain handler errors become a generic wire internal error. */
+function internalError(detail) {
+    return RequestError.internalError(undefined, detail);
+}
+export const Config = Schema.object({
+    provider: Schema.string(),
+    model: Schema.string(),
+    sessionListPageSize: Schema.natural().min(1).default(DEFAULT_SESSION_LIST_PAGE_SIZE),
+});
+/**
+ * Mount the automation-only ACP server.
+ * @param ctx - Cordis context carrying the agent factory and session events.
+ * @param config - Initial provider/model selection and optional test transport.
+ */
+export function apply(ctx, config) {
+    // ACP handlers execute outside this plugin's injection scope, so capture the
+    // injected service during apply rather than reading it lazily in a callback.
+    const persistence = ctx.sessionPersistence;
+    const logger = ctx.logger;
+    // One check at mount beats a broken bridge that only fails when a client
+    // asks for history, or when the provider has already been advertised.
+    assertReplayHostSupport({
+        persistence,
+        sessionLoadMethod: methods.agent.session.load,
+    });
+    logger.info('dsh-acp-replay: session/load replay enabled');
+    const sessionListPageSize = resolveSessionListPageSize(config.sessionListPageSize);
+    const sessions = new Map();
+    const activating = new Set();
+    let closed = false;
+    let imagePromptEnabled = false;
+    /** Return the bridge-owned record for an agent, rejecting same-id impostors. */
+    const ownedRecord = (agent) => {
+        const record = sessions.get(agent.session.id);
+        return record?.owns(agent) === true ? record : undefined;
+    };
+    const assertOpen = () => {
+        if (closed)
+            throw internalError('the ACP bridge has been disposed');
+    };
+    const requireSession = (sessionId) => {
+        const record = sessions.get(sessionId);
+        if (record === undefined)
+            throw invalidParams(`unknown session: ${sessionId}`);
+        return record;
+    };
+    /** Send one ordered protocol update while containing transport-only failure. */
+    const notify = async (notification) => {
+        try {
+            await conn.notify(methods.client.session.update, notification);
+            /* v8 ignore start -- the ACP SDK contains notification-handler failures; only a transport write failure reaches this guard. */
+        }
+        catch (error) {
+            logger.warn(`acp: session/update failed: ${String(error)}`);
+        }
+        /* v8 ignore stop */
+    };
+    ctx.on('session/event', (session, event) => {
+        const record = sessions.get(session.header.id);
+        if (record?.ownsSession(session) === true)
+            record.onSessionEvent(session, event);
+    });
+    ctx.on('agent/inbox/claimed', ({ agent, message, turn }) => {
+        ownedRecord(agent)?.onInboxClaimed(message, turn);
+    });
+    ctx.on('agent/error', ({ agent, turn, error }) => {
+        ownedRecord(agent)?.onAgentError(turn, error);
+    });
+    ctx.on('llm/adapters-updated', () => {
+        for (const record of sessions.values())
+            record.topologyChanged();
+    });
+    // Permission requests are a machine policy channel for ACP clients such as
+    // dsh-subagent-acp. The bridge offers one-shot choices only and never infers a
+    // durable grant from an unknown client response.
+    ctx.on('approval/request', (request, next) => {
+        const record = ownedRecord(request.agent);
+        if (record === undefined || request.callId === undefined)
+            return next();
+        const callId = request.callId;
+        return record.drainUpdates().then(() => {
+            const params = {
+                sessionId: record.agent.session.id,
+                toolCall: { toolCallId: callId },
+                options: [
+                    { optionId: 'allow-once', name: 'Allow once', kind: 'allow_once' },
+                    { optionId: 'reject-once', name: 'Reject', kind: 'reject_once' },
+                ],
+            };
+            return conn.request(methods.client.session.requestPermission, params);
+        }).then(({ outcome }) => {
+            if (outcome.outcome === 'cancelled')
+                return 'cancelled';
+            return outcome.optionId === 'allow-once' ? 'allowed-once' : 'rejected';
+        });
+    });
+    const implementation = {
+        async initialize(_params) {
+            // Single-version agent: the spec's "same version if supported, else
+            // the latest supported" both resolve to this server's one version.
+            imagePromptEnabled = await supportsAcpImagePrompts(ctx, config.provider, config.model);
+            return {
+                protocolVersion: PROTOCOL_VERSION,
+                agentInfo: { name: 'deepseek-harness-acp', version: '0.0.1' },
+                agentCapabilities: {
+                    mcpCapabilities: { http: true },
+                    promptCapabilities: { image: imagePromptEnabled, audio: false, embeddedContext: false },
+                    sessionCapabilities: { close: {}, list: {}, resume: {} },
+                    // Replaying a persisted log is what makes a resumed session visible
+                    // to the client that created it; `session/resume` alone does not.
+                    loadSession: true,
+                },
+                authMethods: [],
+            };
+        },
+        authenticate(_params) {
+            return Promise.resolve();
+        },
+        async newSession(params, signal) {
+            assertOpen();
+            validateWorkspaceParams(params);
+            const sessionId = brandString(randomUUID());
+            // No preset composition: the ACP bundle keeps the model-facing rows in
+            // the host plane, so this agent reads them from the global layer. A
+            // deployment that configures a roster has to join one here first
+            // (@deepseek-ai/dsh-agent-presets README, "Composing a child agent").
+            let record;
+            try {
+                record = await AcpSession.create(ctx, {
+                    sessionId,
+                    cwd: params.cwd,
+                    mcpServers: params.mcpServers,
+                    agentOptions: agentOptions(config),
+                    fallbackSelection: initialSelection(config),
+                    signal,
+                    notify,
+                });
+            }
+            catch (error) {
+                if (error instanceof AcpMcpConfigError)
+                    throw invalidParams(error.message);
+                throw error;
+            }
+            /* v8 ignore next 4 -- a real stdio close can race an in-flight create. */
+            if (closed) {
+                await record.close('connection closed during session/new');
+                throw internalError('connection closed during session/new');
+            }
+            sessions.set(sessionId, record);
+            try {
+                const configOptions = await record.configOptions(signal);
+                assertOpen();
+                // The attached log writer's flush materializes an empty session durably.
+                await ctx.sessions.flush(record.agent.session);
+                assertOpen();
+                return { sessionId, configOptions };
+            }
+            catch (error) {
+                sessions.delete(sessionId);
+                await record.close('session/new activation failed');
+                throw error;
+            }
+        },
+        async resumeSession(params, signal) {
+            assertOpen();
+            validateWorkspaceParams(params);
+            const sessionId = brandString(params.sessionId);
+            if (sessions.has(sessionId) || activating.has(sessionId) || ctx.sessions.get(sessionId) !== undefined) {
+                throw invalidParams(`session is already active: ${sessionId}`);
+            }
+            activating.add(sessionId);
+            return (async () => {
+                const persisted = (await persistence.stat(sessionId, { signal }))?.header;
+                if (persisted === undefined || persisted.origin === 'subagent' || persisted.parentSession !== undefined) {
+                    throw invalidParams(`session is not resumable: ${sessionId}`);
+                }
+                if (!await sameDirectory(persisted.cwd, params.cwd)) {
+                    throw invalidParams(`session cwd does not match: ${params.cwd}`);
+                }
+                let record;
+                try {
+                    record = await AcpSession.resume(ctx, {
+                        sessionId,
+                        cwd: params.cwd,
+                        mcpServers: params.mcpServers ?? [],
+                        agentOptions: agentOptions(config),
+                        fallbackSelection: initialSelection(config),
+                        signal,
+                        notify,
+                    });
+                }
+                catch (error) {
+                    if (error instanceof AcpMcpConfigError)
+                        throw invalidParams(error.message);
+                    throw error;
+                }
+                /* v8 ignore start -- the persisted header was checked before resume; the factory restores that exact header. */
+                if (!await sameDirectory(record.agent.session.header.cwd, params.cwd)) {
+                    await record.close('session/resume cwd mismatch');
+                    throw invalidParams(`session cwd does not match: ${params.cwd}`);
+                }
+                /* v8 ignore stop */
+                /* v8 ignore next 4 -- a real stdio close can race an in-flight resume. */
+                if (closed) {
+                    await record.close('connection closed during session/resume');
+                    throw internalError('connection closed during session/resume');
+                }
+                sessions.set(sessionId, record);
+                try {
+                    return { configOptions: await record.configOptions(signal) };
+                }
+                catch (error) {
+                    sessions.delete(sessionId);
+                    await record.close('session/resume option discovery failed');
+                    throw error;
+                }
+            })().finally(() => { activating.delete(sessionId); });
+        },
+        /**
+         * Restore a persisted session and replay its transcript.
+         *
+         * ACP expects the agent to stream the whole conversation back as
+         * `session/update` notifications before this call returns, so a client that
+         * treats the agent as the transcript authority can render history after its
+         * own restart.
+         */
+        async loadSession(params, signal) {
+            assertOpen();
+            validateWorkspaceParams(params);
+            const sessionId = brandString(params.sessionId);
+            if (sessions.has(sessionId) || activating.has(sessionId) || ctx.sessions.get(sessionId) !== undefined) {
+                throw invalidParams(`session is already active: ${sessionId}`);
+            }
+            activating.add(sessionId);
+            return (async () => {
+                // 'read' observes without taking the single write owner, so the log can
+                // be snapshotted before the restored Agent starts appending to it.
+                const handle = await persistence.open(sessionId, 'read', { signal });
+                let persisted;
+                let transcript;
+                try {
+                    persisted = handle.header;
+                    transcript = (await handle.read(0, undefined, { signal })).events;
+                }
+                finally {
+                    await handle.close();
+                }
+                if (persisted.origin === 'subagent' || persisted.parentSession !== undefined) {
+                    throw invalidParams(`session is not loadable: ${sessionId}`);
+                }
+                if (!await sameDirectory(persisted.cwd, params.cwd)) {
+                    throw invalidParams(`session cwd does not match: ${params.cwd}`);
+                }
+                let record;
+                try {
+                    record = await AcpSession.resume(ctx, {
+                        sessionId,
+                        cwd: params.cwd,
+                        mcpServers: params.mcpServers ?? [],
+                        agentOptions: agentOptions(config),
+                        fallbackSelection: initialSelection(config),
+                        signal,
+                        notify,
+                    });
+                }
+                catch (error) {
+                    if (error instanceof AcpMcpConfigError)
+                        throw invalidParams(error.message);
+                    throw error;
+                }
+                if (closed) {
+                    await record.close('connection closed during session/load');
+                    throw internalError('connection closed during session/load');
+                }
+                sessions.set(sessionId, record);
+                try {
+                    const configOptions = await record.configOptions(signal);
+                    for (const update of await replaySessionUpdates(ctx, record.agent.session, transcript)) {
+                        await notify({ sessionId, update });
+                    }
+                    return { configOptions };
+                }
+                catch (error) {
+                    sessions.delete(sessionId);
+                    await record.close('session/load replay failed');
+                    throw error;
+                }
+            })().finally(() => { activating.delete(sessionId); });
+        },
+        async listSessions(params, signal) {
+            assertOpen();
+            if (params.cwd !== undefined && params.cwd !== null && !isAbsolute(params.cwd)) {
+                throw invalidParams(`cwd must be an absolute path: ${params.cwd}`);
+            }
+            let cursor;
+            try {
+                cursor = decodeSessionListCursor(params.cursor);
+            }
+            catch (error) {
+                throw invalidParams(error.message);
+            }
+            const listed = await persistence.list({ signal });
+            const filtered = await Promise.all(listed.map(async ({ header }) => {
+                if (sessions.has(header.id)
+                    || activating.has(header.id)
+                    || ctx.sessions.get(header.id) !== undefined
+                    || header.origin === 'subagent'
+                    || header.parentSession !== undefined
+                    || header.cwd === undefined
+                    || !isAbsolute(header.cwd))
+                    return undefined;
+                if (params.cwd !== undefined && params.cwd !== null && !await sameDirectory(header.cwd, params.cwd)) {
+                    return undefined;
+                }
+                return { sessionId: header.id, cwd: header.cwd, createdAt: header.createdAt };
+            }));
+            const entries = filtered
+                .filter((entry) => entry !== undefined)
+                .sort((left, right) => right.createdAt - left.createdAt || compareSessionIds(left.sessionId, right.sessionId));
+            const remaining = cursor === undefined
+                ? entries
+                : entries.filter(entry => isAfterSessionListCursor(entry, cursor));
+            const page = remaining.slice(0, sessionListPageSize);
+            const next = remaining.length > page.length ? page.at(-1) : undefined;
+            return {
+                sessions: page.map(({ sessionId, cwd }) => ({ sessionId, cwd })),
+                ...next === undefined ? {} : { nextCursor: encodeSessionListCursor(next) },
+            };
+        },
+        async setSessionConfigOption(params, signal) {
+            assertOpen();
+            const record = requireSession(brandString(params.sessionId));
+            try {
+                return { configOptions: await record.setConfig(params.configId, params.value, signal) };
+            }
+            catch (error) {
+                if (error instanceof AcpModelConfigError)
+                    throw invalidParams(error.message);
+                throw error;
+            }
+        },
+        async closeSession(params) {
+            assertOpen();
+            const sessionId = brandString(params.sessionId);
+            const record = requireSession(sessionId);
+            try {
+                await record.close('ACP session closed');
+            }
+            catch (error) {
+                throw internalError(`session close failed: ${errorChain(error)}`);
+            }
+            finally {
+                if (sessions.get(sessionId) === record)
+                    sessions.delete(sessionId);
+            }
+            return {};
+        },
+        async prompt(params, requestSignal) {
+            assertOpen();
+            const record = requireSession(brandString(params.sessionId));
+            return record.prompt(params, imagePromptEnabled, requestSignal);
+        },
+        cancel(params) {
+            sessions.get(brandString(params.sessionId))?.cancel();
+            return Promise.resolve();
+        },
+    };
+    /* v8 ignore next 4 -- production stdio wiring; tests inject config.stream. */
+    const stream = config.stream ?? ndJsonStream(Writable.toWeb(process.stdout), Readable.toWeb(process.stdin));
+    const app = createAcpAgentApp({ name: 'deepseek-harness-acp' })
+        .onRequest(methods.agent.initialize, ({ params }) => implementation.initialize(params))
+        .onRequest(methods.agent.authenticate, async ({ params }) => {
+        await implementation.authenticate(params);
+        return {};
+    })
+        .onRequest(methods.agent.session.new, ({ params, signal }) => implementation.newSession(params, signal))
+        .onRequest(methods.agent.session.list, ({ params, signal }) => implementation.listSessions(params, signal))
+        .onRequest(methods.agent.session.resume, ({ params, signal }) => implementation.resumeSession(params, signal))
+        .onRequest(methods.agent.session.load, ({ params, signal }) => implementation.loadSession(params, signal))
+        .onRequest(methods.agent.session.close, ({ params }) => implementation.closeSession(params))
+        .onRequest(methods.agent.session.setConfigOption, ({ params, signal }) => implementation.setSessionConfigOption(params, signal))
+        .onRequest(methods.agent.session.prompt, ({ params, signal }) => implementation.prompt(params, signal))
+        .onNotification(methods.agent.session.cancel, ({ params }) => implementation.cancel(params));
+    const connection = app.connect(stream);
+    const conn = connection.client;
+    let quiescing;
+    const quiesce = () => {
+        if (quiescing !== undefined)
+            return quiescing;
+        closed = true;
+        const records = [...sessions.values()];
+        // AcpSession.close cancels synchronously before its first await, so every owned
+        // prompt stops before any descendant or persistence drain can block.
+        quiescing = (async () => {
+            const disposals = await Promise.allSettled(records.map(record => record.close('ACP bridge disposed')));
+            for (const record of records) {
+                /* v8 ignore next -- closed blocks concurrent handlers; each captured record remains mapped until this loop. */
+                if (sessions.get(record.agent.session.id) === record)
+                    sessions.delete(record.agent.session.id);
+            }
+            const failures = [];
+            for (const result of disposals) {
+                if (result.status === 'rejected')
+                    failures.push(result.reason);
+            }
+            if (failures.length > 0) {
+                // The production consumer logs this AggregateError through `String`,
+                // which renders only its message. Embed every per-session diagnostic,
+                // including nested causes and aggregate members, in that message.
+                const detail = failures.map(failure => errorChain(failure)).join('; ');
+                throw new AggregateError(failures, `ACP agent teardown failed for ${failures.length} session(s): ${detail}`);
+            }
+        })();
+        return quiescing;
+    };
+    /* v8 ignore start -- production transport rejection and teardown failure. */
+    void connection.closed
+        .catch((error) => {
+        logger.warn(`acp: connection closed with an error: ${String(error)}`);
+    })
+        .then(quiesce)
+        .catch((error) => {
+        logger.warn(`acp: connection-close teardown failed: ${String(error)}`);
+    });
+    /* v8 ignore stop */
+    ctx.effect(() => quiesce, 'acp.connection');
+}
+/**
+ * Build per-agent options from plugin config without assigning absent optional fields.
+ * @param config - ACP provider/model configuration.
+ * @returns the configured fields only.
+ */
+function agentOptions(config) {
+    return {
+        ...config.provider !== undefined ? { provider: config.provider } : {},
+        ...config.model !== undefined ? { model: config.model } : {},
+    };
+}
+/** Initial session selection when both deployment fields are present. */
+function initialSelection(config) {
+    return config.provider === undefined || config.model === undefined
+        ? undefined
+        : { provider: config.provider, model: config.model };
+}
+/** Resolve and validate the deployment-owned session page limit. */
+function resolveSessionListPageSize(value) {
+    const resolved = value ?? DEFAULT_SESSION_LIST_PAGE_SIZE;
+    /* v8 ignore start -- Cordis applies the positive-integer Config schema; this protects direct apply callers. */
+    if (!Number.isSafeInteger(resolved) || resolved < 1) {
+        throw new Error('acp: sessionListPageSize must be a positive safe integer');
+    }
+    /* v8 ignore stop */
+    return resolved;
+}
+/** Decode an opaque keyset cursor without assigning meaning to client metadata. */
+function decodeSessionListCursor(value) {
+    if (value === undefined || value === null)
+        return undefined;
+    if (!/^[A-Za-z0-9_-]+$/.test(value))
+        throw new Error('session/list cursor is invalid');
+    try {
+        const decoded = JSON.parse(Buffer.from(value, 'base64url').toString('utf8'));
+        const createdAt = Array.isArray(decoded) ? decoded[0] : undefined;
+        const sessionId = Array.isArray(decoded) ? decoded[1] : undefined;
+        if (!Array.isArray(decoded)
+            || decoded.length !== 2
+            || typeof createdAt !== 'number'
+            || !Number.isSafeInteger(createdAt)
+            || createdAt < 0
+            || typeof sessionId !== 'string'
+            || sessionId.length === 0)
+            throw new Error('invalid cursor fields');
+        const canonical = Buffer.from(JSON.stringify(decoded), 'utf8').toString('base64url');
+        if (canonical !== value)
+            throw new Error('non-canonical cursor');
+        return { createdAt, sessionId };
+    }
+    catch (_invalidCursor) {
+        throw new Error('session/list cursor is invalid');
+    }
+}
+/** Encode the last returned ordering key as an opaque continuation token. */
+function encodeSessionListCursor(entry) {
+    return Buffer.from(JSON.stringify([entry.createdAt, entry.sessionId]), 'utf8').toString('base64url');
+}
+/** Test whether an entry follows the cursor in newest-first list order. */
+function isAfterSessionListCursor(entry, cursor) {
+    return entry.createdAt < cursor.createdAt
+        || (entry.createdAt === cursor.createdAt && compareSessionIds(entry.sessionId, cursor.sessionId) > 0);
+}
+/** Compare opaque session ids by stable UTF-8 bytes, independent of process locale. */
+function compareSessionIds(left, right) {
+    return Buffer.compare(Buffer.from(left), Buffer.from(right));
+}
+/** Reject workspace features outside the automation contract. */
+function validateWorkspaceParams(params) {
+    if (!isAbsolute(params.cwd))
+        throw invalidParams(`cwd must be an absolute path: ${params.cwd}`);
+    if (params.additionalDirectories !== undefined
+        && params.additionalDirectories !== null
+        && params.additionalDirectories.length > 0) {
+        throw invalidParams('additionalDirectories is not supported');
+    }
+}
+/** Compare existing directories by physical identity and missing paths lexically. */
+async function sameDirectory(left, right) {
+    if (left === undefined)
+        return false;
+    try {
+        const [realLeft, realRight] = await Promise.all([realpath(left), realpath(right)]);
+        return realLeft === realRight;
+    }
+    catch (_unresolvablePath) {
+        return resolve(left) === resolve(right);
+    }
+}

package/lib/mcp.js

@@ -0,0 +1,130 @@
+/** Standard ACP MCP-server declarations translated into Agent-scoped DSH MCP clients. */
+import { createHash } from 'node:crypto';
+import { validateHeaderName, validateHeaderValue } from 'node:http';
+import { isAbsolute } from 'node:path';
+import * as McpClient from '@deepseek-ai/dsh-mcp-client';
+const VALID_SERVER_NAME = /^[A-Za-z0-9_-]{1,32}$/;
+/** Caller-correctable MCP declaration failure. */
+export class AcpMcpConfigError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'AcpMcpConfigError';
+    }
+}
+/**
+ * Validate and mount one session's complete standard MCP server list before Agent publication.
+ * @param agentCtx - unpublished Agent scope that owns the MCP clients and tools.
+ * @param servers - stable ACP stdio or HTTP server declarations.
+ * @param sessionCwd - canonical primary workspace used by stdio servers.
+ */
+export async function mountAcpMcpServers(agentCtx, servers, sessionCwd) {
+    const configs = resolveMcpConfigs(servers, sessionCwd);
+    for (const config of configs)
+        await agentCtx.plugin(McpClient, config);
+}
+/** Convert the stable stdio/HTTP ACP transports and reject every other transport. */
+function resolveMcpConfigs(servers, sessionCwd) {
+    const names = new Set();
+    return servers.map((server, index) => {
+        const serverName = normalizeServerName(server.name);
+        if (names.has(serverName)) {
+            throw new AcpMcpConfigError(`mcpServers contains duplicate normalized name: ${serverName}`);
+        }
+        names.add(serverName);
+        if (!('type' in server)) {
+            if (!isAbsolute(server.command)) {
+                throw new AcpMcpConfigError(`mcpServers[${index}].command must be an absolute path`);
+            }
+            const env = entriesToRecord(server.env, `mcpServers[${index}].env`, 'environment');
+            const config = validateClientConfig(index, () => McpClient.Config({
+                transport: 'stdio',
+                serverName,
+                command: server.command,
+                args: server.args,
+                env,
+                cwd: sessionCwd,
+                failOnStartupError: true,
+            }));
+            return { ...config, env };
+        }
+        if (server.type === 'http') {
+            assertHttpUrl(server.url, `mcpServers[${index}].url`);
+            const headers = entriesToRecord(server.headers, `mcpServers[${index}].headers`, 'header');
+            const config = validateClientConfig(index, () => McpClient.Config({
+                transport: 'streamable-http',
+                serverName,
+                url: server.url,
+                headers,
+                failOnStartupError: true,
+            }));
+            return { ...config, headers };
+        }
+        throw new AcpMcpConfigError(`mcpServers[${index}] transport ${server.type} is not supported`);
+    });
+}
+/** Convert ordered ACP name/value entries without silently accepting duplicate keys. */
+function entriesToRecord(entries, field, kind) {
+    // Valid environment and header names include "__proto__"; a null prototype
+    // keeps that entry as data instead of invoking Object.prototype's setter.
+    const result = Object.create(null);
+    const names = new Set();
+    for (const entry of entries) {
+        if (kind === 'header') {
+            try {
+                validateHeaderName(entry.name);
+                validateHeaderValue(entry.name, entry.value);
+            }
+            catch (_invalidHeader) {
+                throw new AcpMcpConfigError(`${field} contains an invalid header entry`);
+            }
+        }
+        else if (entry.name.length === 0
+            || entry.name.includes('=')
+            || entry.name.includes('\0')
+            || entry.value.includes('\0')) {
+            throw new AcpMcpConfigError(`${field} contains an invalid environment entry`);
+        }
+        const identity = kind === 'header' ? entry.name.toLowerCase() : entry.name;
+        if (names.has(identity))
+            throw new AcpMcpConfigError(`${field} contains duplicate name: ${entry.name}`);
+        names.add(identity);
+        result[entry.name] = entry.value;
+    }
+    return result;
+}
+/** Produce a stable DSH tool namespace from ACP's human-readable server name. */
+function normalizeServerName(name) {
+    if (name.trim().length === 0 || /[\u0000-\u001f\u007f]/.test(name)) {
+        throw new AcpMcpConfigError('mcpServers contains an invalid server name');
+    }
+    if (VALID_SERVER_NAME.test(name))
+        return name;
+    const slug = name.normalize('NFKD')
+        .replace(/[^A-Za-z0-9_-]+/g, '_')
+        .replace(/^_+|_+$/g, '')
+        .slice(0, 20) || 'server';
+    const digest = createHash('sha256').update(name).digest('hex').slice(0, 8);
+    return `${slug}_${digest}`.slice(0, 32);
+}
+/** Require the stable Streamable HTTP transport URL schemes. */
+function assertHttpUrl(value, field) {
+    try {
+        const url = new URL(value);
+        if (url.protocol !== 'http:' && url.protocol !== 'https:')
+            throw new Error('unsupported protocol');
+    }
+    catch (_invalidUrl) {
+        throw new AcpMcpConfigError(`${field} must be an absolute HTTP(S) URL`);
+    }
+}
+/** Map the existing MCP provider's schema error into ACP invalid params. */
+function validateClientConfig(index, parse) {
+    try {
+        return parse();
+    }
+    catch (error) {
+        /* v8 ignore next -- Schemastery validation rejects with Error instances. */
+        const detail = error instanceof Error ? error.message : String(error);
+        throw new AcpMcpConfigError(`mcpServers[${index}] is invalid: ${detail}`);
+    }
+}