@harapter/transport-acp 0.1.1

package/dist/validation.js

@@ -0,0 +1,1181 @@
+import { createHash } from 'node:crypto';
+import { isAbsolute } from 'node:path';
+import { acpError } from './errors.js';
+import { ACP_PROTOCOL_VERSION, } from './types.js';
+const maximumStringLength = 1024 * 1024;
+const maximumIdentifierLength = 1024;
+const maximumRawDepth = 4;
+const maximumRawNodes = 64;
+const maximumRawItems = 16;
+const knownMethods = new Set(['session/update']);
+const structuralStringKeys = new Set([
+    'kind',
+    'outcome',
+    'sessionUpdate',
+    'status',
+    'type',
+]);
+const knownStructuralValues = new Set([
+    'agent_message_chunk',
+    'agent_thought_chunk',
+    'available_commands_update',
+    'cancelled',
+    'completed',
+    'config_option_update',
+    'content',
+    'diff',
+    'failed',
+    'in_progress',
+    'pending',
+    'plan',
+    'session_info_update',
+    'terminal',
+    'text',
+    'tool_call',
+    'tool_call_update',
+    'usage_update',
+    'user_message_chunk',
+]);
+const toolKinds = new Set([
+    'read',
+    'edit',
+    'delete',
+    'move',
+    'search',
+    'execute',
+    'think',
+    'fetch',
+    'switch_mode',
+    'other',
+]);
+const toolStatuses = new Set([
+    'pending',
+    'in_progress',
+    'completed',
+    'failed',
+]);
+const stopReasons = new Set([
+    'end_turn',
+    'max_tokens',
+    'max_turn_requests',
+    'refusal',
+    'cancelled',
+]);
+/** Validate and normalize the stable initialize payload sent to the Agent. */
+export function prepareInitializeInput(input = {}) {
+    const capabilities = prepareClientCapabilities(input.clientCapabilities);
+    const output = {
+        protocolVersion: ACP_PROTOCOL_VERSION,
+        clientCapabilities: capabilities,
+    };
+    if (input.clientInfo !== undefined) {
+        output['clientInfo'] = validateImplementation(input.clientInfo, 'client implementation', 'invalid_params');
+    }
+    attachMeta(output, input._meta, 'invalid_params');
+    return output;
+}
+/** Parse and normalize one stable initialize response. */
+export function parseInitializeResult(value) {
+    const response = messageRecord(value, 'initialize response');
+    const protocolVersion = response['protocolVersion'];
+    if (protocolVersion !== ACP_PROTOCOL_VERSION) {
+        if (nonNegativeInteger(protocolVersion) && protocolVersion <= 65_535) {
+            throw acpError('unsupported_protocol_version', 'The ACP peer selected an unsupported protocol version.');
+        }
+        throw invalidMessage('initialize response');
+    }
+    const capabilities = parseAgentCapabilities(response['agentCapabilities']);
+    const authMethods = response['authMethods'];
+    if (authMethods !== undefined && !Array.isArray(authMethods)) {
+        throw invalidMessage('initialize response');
+    }
+    const output = {
+        protocolVersion: ACP_PROTOCOL_VERSION,
+        capabilities,
+        authMethods: authMethods ?? [],
+    };
+    if (response['agentInfo'] !== undefined && response['agentInfo'] !== null) {
+        output.agentInfo = validateImplementation(response['agentInfo'], 'agent implementation', 'invalid_message');
+    }
+    attachParsedMeta(output, response, 'initialize response');
+    return output;
+}
+/** Validate a session/new request before it reaches the wire. */
+export function prepareNewSessionInput(input, capabilities) {
+    return prepareSessionConnectionInput(input, capabilities, true);
+}
+/** Validate a session/load request before it reaches the wire. */
+export function prepareLoadSessionInput(input, capabilities) {
+    const output = prepareSessionConnectionInput(input, capabilities, true);
+    return { ...output, sessionId: identifier(input.sessionId, 'session ID') };
+}
+/** Validate a session/resume request before it reaches the wire. */
+export function prepareResumeSessionInput(input, capabilities) {
+    const output = prepareSessionConnectionInput(input, capabilities, false);
+    return { ...output, sessionId: identifier(input.sessionId, 'session ID') };
+}
+/** Parse a session/new response. */
+export function parseNewSessionResult(value) {
+    const response = messageRecord(value, 'session/new response');
+    return {
+        sessionId: inboundIdentifier(response['sessionId'], 'session/new response'),
+        ...parseSessionState(response, 'session/new response'),
+    };
+}
+/** Parse a session/load or session/resume response. */
+export function parseSessionStateResult(value) {
+    return parseSessionState(messageRecord(value, 'session setup response'), 'session setup response');
+}
+/** Validate a session/list request. */
+export function prepareListSessionsInput(input = {}) {
+    const output = {};
+    if (input.cwd !== undefined && input.cwd !== null) {
+        output['cwd'] = absolutePath(input.cwd, 'session/list cwd');
+    }
+    else if (input.cwd === null) {
+        output['cwd'] = null;
+    }
+    if (input.cursor !== undefined && input.cursor !== null) {
+        output['cursor'] = identifier(input.cursor, 'session/list cursor');
+    }
+    else if (input.cursor === null) {
+        output['cursor'] = null;
+    }
+    attachMeta(output, input._meta, 'invalid_params');
+    return output;
+}
+/** Parse a session/list response. */
+export function parseListSessionsResult(value) {
+    const response = messageRecord(value, 'session/list response');
+    const sessions = response['sessions'];
+    if (!Array.isArray(sessions))
+        throw invalidMessage('session/list response');
+    const output = { sessions: sessions.map(parseSessionInfo) };
+    if (response['nextCursor'] !== undefined) {
+        const nextCursor = response['nextCursor'];
+        if (nextCursor !== null && typeof nextCursor !== 'string') {
+            throw invalidMessage('session/list response');
+        }
+        output.nextCursor = nextCursor;
+    }
+    attachParsedMeta(output, response, 'session/list response');
+    return output;
+}
+/** Parse an empty object response while retaining only ACP metadata. */
+export function parseEmptyResult(value) {
+    const response = messageRecord(value, 'empty ACP response');
+    const output = {};
+    attachParsedMeta(output, response, 'empty ACP response');
+    return output;
+}
+/** Validate a session/prompt request against negotiated content capabilities. */
+export function preparePromptInput(input, capabilities) {
+    const sessionId = identifier(input.sessionId, 'session ID');
+    if (!Array.isArray(input.prompt) || input.prompt.length === 0) {
+        throw invalidParams('ACP prompts must contain at least one content block.');
+    }
+    for (const block of input.prompt)
+        validateContentBlock(block, capabilities);
+    const output = { sessionId, prompt: input.prompt };
+    attachMeta(output, input._meta, 'invalid_params');
+    return output;
+}
+/** Parse the authoritative terminal result for one prompt turn. */
+export function parsePromptResult(value) {
+    const response = messageRecord(value, 'session/prompt response');
+    const reason = response['stopReason'];
+    if (typeof reason !== 'string' || !stopReasons.has(reason)) {
+        throw invalidMessage('session/prompt response');
+    }
+    const output = {
+        stopReason: reason,
+    };
+    attachParsedMeta(output, response, 'session/prompt response');
+    return output;
+}
+/** Parse one session/update notification, preserving future variants safely. */
+export function parseSessionNotification(value) {
+    const params = messageRecord(value, 'session/update notification');
+    const sessionId = inboundIdentifier(params['sessionId'], 'session/update notification');
+    const update = messageRecord(params['update'], 'session/update notification');
+    const tag = update['sessionUpdate'];
+    if (typeof tag !== 'string' || tag.length === 0) {
+        throw invalidMessage('session/update notification');
+    }
+    if (!knownSessionUpdate(tag)) {
+        return {
+            kind: 'unknown',
+            observation: redactAcpObservation('unknown_session_update', 'session/update', params),
+        };
+    }
+    return { kind: 'update', sessionId, update: parseKnownUpdate(update, tag) };
+}
+/** Parse one bidirectional permission request. */
+export function parsePermissionRequest(value) {
+    const request = messageRecord(value, 'permission request');
+    const sessionId = inboundIdentifier(request['sessionId'], 'permission request');
+    const toolCall = parseToolCallUpdate(request['toolCall'], 'permission request');
+    const options = request['options'];
+    if (!Array.isArray(options) || options.length === 0) {
+        throw invalidMessage('permission request');
+    }
+    const parsedOptions = options.map((option) => {
+        const item = messageRecord(option, 'permission option');
+        const kind = item['kind'];
+        if (kind !== 'allow_once' &&
+            kind !== 'allow_always' &&
+            kind !== 'reject_once' &&
+            kind !== 'reject_always') {
+            throw invalidMessage('permission option');
+        }
+        const output = {
+            optionId: inboundIdentifier(item['optionId'], 'permission option'),
+            name: inboundString(item['name'], 'permission option'),
+            kind,
+        };
+        attachParsedMeta(output, item, 'permission option');
+        return output;
+    });
+    const output = { sessionId, toolCall, options: parsedOptions };
+    attachParsedMeta(output, request, 'permission request');
+    return output;
+}
+/** Validate a host decision before replying to a permission request. */
+export function preparePermissionOutcome(value, request) {
+    if (value.outcome === 'cancelled') {
+        const outcome = { outcome: 'cancelled' };
+        attachMeta(outcome, value._meta, 'invalid_params');
+        return { outcome };
+    }
+    const optionId = identifier(value.optionId, 'permission option ID');
+    if (!request.options.some((option) => option.optionId === optionId)) {
+        throw invalidParams('The selected permission option was not advertised.');
+    }
+    const outcome = { outcome: 'selected', optionId };
+    attachMeta(outcome, value._meta, 'invalid_params');
+    return { outcome };
+}
+/** Produce a bounded structural view of unknown ACP traffic. */
+export function redactAcpObservation(kind, method, params) {
+    return {
+        kind,
+        method: publicMethod(method),
+        params: redact(params, 0, { nodes: 0 }),
+    };
+}
+/** Require a valid extension method name reserved by ACP. */
+export function extensionMethod(method) {
+    if (typeof method !== 'string' ||
+        !/^_[\u0021-\u007e]{0,255}$/u.test(method)) {
+        throw invalidParams('ACP extension methods must start with an underscore.');
+    }
+    return method;
+}
+/** Validate a public Session identifier for an outbound method. */
+export function sessionIdentifier(value) {
+    return identifier(value, 'session ID');
+}
+function prepareClientCapabilities(value) {
+    const fs = value?.fs;
+    const auth = value?.auth;
+    if (fs?.readTextFile === true ||
+        fs?.writeTextFile === true ||
+        value?.terminal === true ||
+        auth?.terminal === true) {
+        throw acpError('invalid_configuration', 'This ACP client profile cannot advertise unimplemented client services.');
+    }
+    assertOptionalBoolean(fs?.readTextFile, 'client fs capability');
+    assertOptionalBoolean(fs?.writeTextFile, 'client fs capability');
+    assertOptionalBoolean(value?.terminal, 'client terminal capability');
+    assertOptionalBoolean(auth?.terminal, 'client auth capability');
+    const fsOutput = {
+        readTextFile: false,
+        writeTextFile: false,
+    };
+    attachMeta(fsOutput, fs?._meta, 'invalid_params');
+    const authOutput = { terminal: false };
+    attachMeta(authOutput, auth?._meta, 'invalid_params');
+    const output = {
+        fs: fsOutput,
+        terminal: false,
+        auth: authOutput,
+    };
+    attachMeta(output, value?._meta, 'invalid_params');
+    return output;
+}
+function parseAgentCapabilities(value) {
+    const capabilities = value === undefined ? {} : messageRecord(value, 'agent capabilities');
+    const prompt = optionalRecord(capabilities, 'promptCapabilities', 'agent capabilities');
+    const mcp = optionalRecord(capabilities, 'mcpCapabilities', 'agent capabilities');
+    const session = optionalRecord(capabilities, 'sessionCapabilities', 'agent capabilities');
+    const output = {
+        loadSession: optionalBoolean(capabilities, 'loadSession', 'agent capabilities'),
+        prompt: {
+            image: optionalBoolean(prompt, 'image', 'prompt capabilities'),
+            audio: optionalBoolean(prompt, 'audio', 'prompt capabilities'),
+            embeddedContext: optionalBoolean(prompt, 'embeddedContext', 'prompt capabilities'),
+        },
+        mcp: {
+            http: optionalBoolean(mcp, 'http', 'MCP capabilities'),
+            sse: optionalBoolean(mcp, 'sse', 'MCP capabilities'),
+        },
+        session: {
+            list: optionalMarker(session, 'list', 'session capabilities'),
+            delete: optionalMarker(session, 'delete', 'session capabilities'),
+            additionalDirectories: optionalMarker(session, 'additionalDirectories', 'session capabilities'),
+            resume: optionalMarker(session, 'resume', 'session capabilities'),
+            close: optionalMarker(session, 'close', 'session capabilities'),
+        },
+        ...metaProperty(capabilities, 'agent capabilities'),
+    };
+    return output;
+}
+function prepareSessionConnectionInput(input, capabilities, requireMcpServers) {
+    const cwd = absolutePath(input.cwd, 'session cwd');
+    const mcpServers = input.mcpServers;
+    if (requireMcpServers && !Array.isArray(mcpServers)) {
+        throw invalidParams('ACP session setup requires an MCP server array.');
+    }
+    if (mcpServers !== undefined) {
+        if (!Array.isArray(mcpServers)) {
+            throw invalidParams('ACP MCP servers must be an array.');
+        }
+        for (const server of mcpServers)
+            validateMcpServer(server, capabilities);
+    }
+    const additionalDirectories = input.additionalDirectories;
+    if (additionalDirectories !== undefined) {
+        if (!Array.isArray(additionalDirectories)) {
+            throw invalidParams('ACP additional directories must be an array.');
+        }
+        if (additionalDirectories.length > 0 &&
+            !capabilities.session.additionalDirectories) {
+            throw acpError('capability_not_advertised', 'The ACP Agent did not advertise additional directory support.');
+        }
+        for (const directory of additionalDirectories) {
+            absolutePath(directory, 'additional directory');
+        }
+    }
+    const output = { cwd };
+    if (mcpServers !== undefined)
+        output['mcpServers'] = mcpServers;
+    if (additionalDirectories !== undefined) {
+        output['additionalDirectories'] = additionalDirectories;
+    }
+    attachMeta(output, input._meta, 'invalid_params');
+    return output;
+}
+function validateMcpServer(value, capabilities) {
+    const server = localRecord(value, 'MCP server');
+    identifier(server['name'], 'MCP server name');
+    if (server['type'] === 'http' || server['type'] === 'sse') {
+        if (!capabilities.mcp[server['type']]) {
+            throw acpError('capability_not_advertised', `The ACP Agent did not advertise ${server['type'].toUpperCase()} MCP support.`);
+        }
+        httpUrl(server['url'], 'MCP server URL');
+        validateNameValueArray(server['headers'], 'MCP headers');
+    }
+    else {
+        absolutePath(server['command'], 'MCP command');
+        stringArray(server['args'], 'MCP arguments', false);
+        validateNameValueArray(server['env'], 'MCP environment');
+    }
+    validateMeta(server['_meta'], 'invalid_params');
+}
+function parseSessionState(response, surface) {
+    const output = {};
+    if (response['modes'] !== undefined) {
+        const modes = response['modes'];
+        output.modes =
+            modes === null ? null : parseSessionModeState(modes, surface);
+    }
+    if (response['configOptions'] !== undefined) {
+        const options = response['configOptions'];
+        output.configOptions =
+            options === null ? null : parseSessionConfigOptions(options, surface);
+    }
+    attachParsedMeta(output, response, surface);
+    return output;
+}
+function parseSessionInfo(value) {
+    const session = messageRecord(value, 'session/list entry');
+    const output = {
+        sessionId: inboundIdentifier(session['sessionId'], 'session/list entry'),
+        cwd: inboundAbsolutePath(session['cwd'], 'session/list entry'),
+    };
+    if (session['additionalDirectories'] !== undefined) {
+        output.additionalDirectories = inboundStringArray(session['additionalDirectories'], 'session/list entry').map((directory) => inboundAbsolutePath(directory, 'session/list entry'));
+    }
+    optionalNullableString(output, session, 'title', 'session/list entry');
+    optionalNullableString(output, session, 'updatedAt', 'session/list entry');
+    attachParsedMeta(output, session, 'session/list entry');
+    return output;
+}
+function validateContentBlock(value, capabilities) {
+    const block = localRecord(value, 'content block');
+    validateLocalAnnotations(block['annotations'], 'content annotations');
+    validateMeta(block['_meta'], 'invalid_params');
+    switch (block['type']) {
+        case 'text':
+            boundedString(block['text'], 'text content');
+            break;
+        case 'image':
+            if (!capabilities.prompt.image)
+                capabilityContent('image');
+            boundedString(block['data'], 'image data');
+            boundedString(block['mimeType'], 'image MIME type');
+            validateOptionalLocalString(block, 'uri', 'image URI');
+            break;
+        case 'audio':
+            if (!capabilities.prompt.audio)
+                capabilityContent('audio');
+            boundedString(block['data'], 'audio data');
+            boundedString(block['mimeType'], 'audio MIME type');
+            break;
+        case 'resource_link': {
+            boundedString(block['name'], 'resource name');
+            boundedString(block['uri'], 'resource URI');
+            validateOptionalLocalString(block, 'title', 'resource title');
+            validateOptionalLocalString(block, 'description', 'resource description');
+            validateOptionalLocalString(block, 'mimeType', 'resource MIME type');
+            const size = block['size'];
+            if (size !== undefined &&
+                size !== null &&
+                (!Number.isSafeInteger(size) || Number(size) < 0)) {
+                throw invalidParams('The ACP resource size is invalid.');
+            }
+            break;
+        }
+        case 'resource': {
+            if (!capabilities.prompt.embeddedContext)
+                capabilityContent('embedded context');
+            const resource = localRecord(block['resource'], 'embedded resource');
+            boundedString(resource['uri'], 'embedded resource URI');
+            const hasText = typeof resource['text'] === 'string';
+            const hasBlob = typeof resource['blob'] === 'string';
+            if (hasText === hasBlob) {
+                throw invalidParams('Embedded resources require exactly one payload.');
+            }
+            boundedString(hasText ? resource['text'] : resource['blob'], 'embedded resource payload');
+            validateOptionalLocalString(resource, 'mimeType', 'embedded resource MIME type');
+            validateMeta(resource['_meta'], 'invalid_params');
+            break;
+        }
+        default:
+            throw invalidParams('The ACP content block type is invalid.');
+    }
+}
+function parseKnownUpdate(update, tag) {
+    switch (tag) {
+        case 'user_message_chunk':
+        case 'agent_message_chunk':
+        case 'agent_thought_chunk': {
+            const content = parseInboundContentBlock(update['content']);
+            const output = { sessionUpdate: tag, content };
+            optionalNullableString(output, update, 'messageId', 'content chunk');
+            attachParsedMeta(output, update, 'content chunk');
+            return output;
+        }
+        case 'tool_call': {
+            const toolCall = parseToolCallUpdate(update, 'tool call');
+            const title = inboundString(update['title'], 'tool call');
+            return { ...toolCall, sessionUpdate: tag, title };
+        }
+        case 'tool_call_update':
+            return {
+                ...parseToolCallUpdate(update, 'tool call update'),
+                sessionUpdate: tag,
+            };
+        case 'plan':
+            return {
+                sessionUpdate: tag,
+                entries: parsePlanEntries(update['entries']),
+                ...metaProperty(update, 'plan update'),
+            };
+        case 'available_commands_update':
+            return {
+                sessionUpdate: tag,
+                availableCommands: parseAvailableCommands(update['availableCommands']),
+                ...metaProperty(update, 'available commands update'),
+            };
+        case 'current_mode_update':
+            return {
+                sessionUpdate: tag,
+                currentModeId: inboundIdentifier(update['currentModeId'], 'mode update'),
+                ...metaProperty(update, 'mode update'),
+            };
+        case 'config_option_update':
+            return {
+                sessionUpdate: tag,
+                configOptions: parseSessionConfigOptions(update['configOptions'], 'config option update'),
+                ...metaProperty(update, 'config option update'),
+            };
+        case 'session_info_update': {
+            const output = { sessionUpdate: tag };
+            optionalNullableString(output, update, 'title', 'session info update');
+            optionalNullableString(output, update, 'updatedAt', 'session info update');
+            attachParsedMeta(output, update, 'session info update');
+            return output;
+        }
+        case 'usage_update': {
+            const used = nonNegativeSafeInteger(update['used'], 'usage update');
+            const size = nonNegativeSafeInteger(update['size'], 'usage update');
+            const output = { sessionUpdate: tag, used, size };
+            if (update['cost'] !== undefined) {
+                const cost = update['cost'];
+                if (cost === null)
+                    output.cost = null;
+                else {
+                    const costRecord = messageRecord(cost, 'usage cost');
+                    const amount = costRecord['amount'];
+                    if (typeof amount !== 'number' || !Number.isFinite(amount)) {
+                        throw invalidMessage('usage cost');
+                    }
+                    output.cost = {
+                        amount,
+                        currency: inboundString(costRecord['currency'], 'usage cost'),
+                        ...metaProperty(costRecord, 'usage cost'),
+                    };
+                }
+            }
+            attachParsedMeta(output, update, 'usage update');
+            return output;
+        }
+    }
+}
+function parseInboundContentBlock(value) {
+    const block = messageRecord(value, 'content block');
+    const type = block['type'];
+    switch (type) {
+        case 'text':
+            return {
+                type,
+                text: inboundString(block['text'], 'content block'),
+                ...annotationsProperty(block, 'content block'),
+                ...metaProperty(block, 'content block'),
+            };
+        case 'image':
+            return {
+                type,
+                data: inboundString(block['data'], 'content block'),
+                mimeType: inboundString(block['mimeType'], 'content block'),
+                ...nullableStringProperty(block, 'uri', 'content block'),
+                ...annotationsProperty(block, 'content block'),
+                ...metaProperty(block, 'content block'),
+            };
+        case 'audio':
+            return {
+                type,
+                data: inboundString(block['data'], 'content block'),
+                mimeType: inboundString(block['mimeType'], 'content block'),
+                ...annotationsProperty(block, 'content block'),
+                ...metaProperty(block, 'content block'),
+            };
+        case 'resource_link': {
+            const size = block['size'];
+            if (size !== undefined &&
+                size !== null &&
+                (!Number.isSafeInteger(size) || Number(size) < 0)) {
+                throw invalidMessage('content block');
+            }
+            return {
+                type,
+                name: inboundString(block['name'], 'content block'),
+                uri: inboundString(block['uri'], 'content block'),
+                ...nullableStringProperty(block, 'title', 'content block'),
+                ...nullableStringProperty(block, 'description', 'content block'),
+                ...nullableStringProperty(block, 'mimeType', 'content block'),
+                ...(size === undefined ? {} : { size: size }),
+                ...annotationsProperty(block, 'content block'),
+                ...metaProperty(block, 'content block'),
+            };
+        }
+        case 'resource': {
+            const resource = messageRecord(block['resource'], 'embedded resource');
+            const uri = inboundString(resource['uri'], 'embedded resource');
+            const hasText = typeof resource['text'] === 'string';
+            const hasBlob = typeof resource['blob'] === 'string';
+            if (hasText === hasBlob)
+                throw invalidMessage('embedded resource');
+            const shared = {
+                uri,
+                ...nullableStringProperty(resource, 'mimeType', 'embedded resource'),
+                ...metaProperty(resource, 'embedded resource'),
+            };
+            return {
+                type,
+                resource: hasText
+                    ? {
+                        ...shared,
+                        text: inboundString(resource['text'], 'embedded resource'),
+                    }
+                    : {
+                        ...shared,
+                        blob: inboundString(resource['blob'], 'embedded resource'),
+                    },
+                ...annotationsProperty(block, 'content block'),
+                ...metaProperty(block, 'content block'),
+            };
+        }
+        default:
+            throw invalidMessage('content block');
+    }
+}
+function parseToolCallUpdate(value, surface) {
+    const tool = messageRecord(value, surface);
+    const output = { toolCallId: inboundIdentifier(tool['toolCallId'], surface) };
+    optionalNullableString(output, tool, 'title', surface);
+    if (tool['kind'] !== undefined) {
+        const kind = tool['kind'];
+        if (kind !== null &&
+            (typeof kind !== 'string' || !toolKinds.has(kind))) {
+            throw invalidMessage(surface);
+        }
+        output.kind = kind;
+    }
+    if (tool['status'] !== undefined) {
+        const status = tool['status'];
+        if (status !== null &&
+            (typeof status !== 'string' ||
+                !toolStatuses.has(status))) {
+            throw invalidMessage(surface);
+        }
+        output.status = status;
+    }
+    if (tool['content'] !== undefined) {
+        const content = tool['content'];
+        if (content !== null && !Array.isArray(content))
+            throw invalidMessage(surface);
+        output.content =
+            content === null
+                ? null
+                : content.map((item) => parseToolCallContent(item, surface));
+    }
+    if (tool['locations'] !== undefined) {
+        const locations = tool['locations'];
+        if (locations !== null && !Array.isArray(locations))
+            throw invalidMessage(surface);
+        output.locations =
+            locations === null
+                ? null
+                : locations.map((item) => parseToolCallLocation(item, surface));
+    }
+    if (Object.hasOwn(tool, 'rawInput'))
+        output.rawInput = tool['rawInput'];
+    if (Object.hasOwn(tool, 'rawOutput'))
+        output.rawOutput = tool['rawOutput'];
+    attachParsedMeta(output, tool, surface);
+    return output;
+}
+function parseToolCallContent(value, surface) {
+    const content = messageRecord(value, surface);
+    switch (content['type']) {
+        case 'content':
+            return {
+                type: 'content',
+                content: parseInboundContentBlock(content['content']),
+                ...metaProperty(content, surface),
+            };
+        case 'diff': {
+            const output = {
+                type: 'diff',
+                path: inboundAbsolutePath(content['path'], surface),
+                newText: inboundString(content['newText'], surface),
+            };
+            optionalNullableString(output, content, 'oldText', surface);
+            attachParsedMeta(output, content, surface);
+            return output;
+        }
+        case 'terminal':
+            return {
+                type: 'terminal',
+                terminalId: inboundIdentifier(content['terminalId'], surface),
+                ...metaProperty(content, surface),
+            };
+        default:
+            throw invalidMessage(surface);
+    }
+}
+function parseToolCallLocation(value, surface) {
+    const location = messageRecord(value, surface);
+    const output = { path: inboundAbsolutePath(location['path'], surface) };
+    if (location['line'] !== undefined) {
+        const line = location['line'];
+        if (line !== null && !unsigned32BitInteger(line)) {
+            throw invalidMessage(surface);
+        }
+        output.line = line;
+    }
+    attachParsedMeta(output, location, surface);
+    return output;
+}
+function parsePlanEntries(value) {
+    if (!Array.isArray(value))
+        throw invalidMessage('plan update');
+    return value.map((entry) => {
+        const item = messageRecord(entry, 'plan entry');
+        const priority = item['priority'];
+        const status = item['status'];
+        if (priority !== 'high' && priority !== 'medium' && priority !== 'low') {
+            throw invalidMessage('plan entry');
+        }
+        if (status !== 'pending' &&
+            status !== 'in_progress' &&
+            status !== 'completed') {
+            throw invalidMessage('plan entry');
+        }
+        return {
+            content: inboundString(item['content'], 'plan entry'),
+            priority,
+            status,
+            ...metaProperty(item, 'plan entry'),
+        };
+    });
+}
+function parseAvailableCommands(value) {
+    if (!Array.isArray(value)) {
+        throw invalidMessage('available commands update');
+    }
+    return value.map((command) => {
+        const item = messageRecord(command, 'available command');
+        const output = {
+            name: inboundString(item['name'], 'available command'),
+            description: inboundString(item['description'], 'available command'),
+        };
+        if (item['input'] !== undefined) {
+            const input = item['input'];
+            if (input === null)
+                output.input = null;
+            else {
+                const inputRecord = messageRecord(input, 'available command input');
+                output.input = {
+                    hint: inboundString(inputRecord['hint'], 'available command input'),
+                    ...metaProperty(inputRecord, 'available command input'),
+                };
+            }
+        }
+        attachParsedMeta(output, item, 'available command');
+        return output;
+    });
+}
+function parseSessionModeState(value, surface) {
+    const state = messageRecord(value, surface);
+    const availableModes = state['availableModes'];
+    if (!Array.isArray(availableModes))
+        throw invalidMessage(surface);
+    return {
+        currentModeId: inboundIdentifier(state['currentModeId'], surface),
+        availableModes: availableModes.map((mode) => parseSessionMode(mode, surface)),
+        ...metaProperty(state, surface),
+    };
+}
+function parseSessionMode(value, surface) {
+    const mode = messageRecord(value, surface);
+    const output = {
+        id: inboundIdentifier(mode['id'], surface),
+        name: inboundString(mode['name'], surface),
+    };
+    optionalNullableString(output, mode, 'description', surface);
+    attachParsedMeta(output, mode, surface);
+    return output;
+}
+function parseSessionConfigOptions(value, surface) {
+    if (!Array.isArray(value))
+        throw invalidMessage(surface);
+    return value.map((option) => parseSessionConfigOption(option, surface));
+}
+function parseSessionConfigOption(value, surface) {
+    const option = messageRecord(value, surface);
+    const shared = {
+        id: inboundIdentifier(option['id'], surface),
+        name: inboundString(option['name'], surface),
+    };
+    optionalNullableString(shared, option, 'description', surface);
+    optionalNullableString(shared, option, 'category', surface);
+    attachParsedMeta(shared, option, surface);
+    if (option['type'] === 'boolean') {
+        if (typeof option['currentValue'] !== 'boolean') {
+            throw invalidMessage(surface);
+        }
+        return { ...shared, type: 'boolean', currentValue: option['currentValue'] };
+    }
+    if (option['type'] !== 'select')
+        throw invalidMessage(surface);
+    return {
+        ...shared,
+        type: 'select',
+        currentValue: inboundIdentifier(option['currentValue'], surface),
+        options: parseSessionConfigSelectOptions(option['options'], surface),
+    };
+}
+function parseSessionConfigSelectOptions(value, surface) {
+    if (!Array.isArray(value))
+        throw invalidMessage(surface);
+    if (value.length === 0)
+        return [];
+    const grouped = value.every((item) => isRecord(item) && Object.hasOwn(item, 'group'));
+    const ungrouped = value.every((item) => isRecord(item) && !Object.hasOwn(item, 'group'));
+    if (!grouped && !ungrouped)
+        throw invalidMessage(surface);
+    return grouped
+        ? value.map((group) => parseSessionConfigSelectGroup(group, surface))
+        : value.map((option) => parseSessionConfigSelectOption(option, surface));
+}
+function parseSessionConfigSelectOption(value, surface) {
+    const option = messageRecord(value, surface);
+    const output = {
+        value: inboundIdentifier(option['value'], surface),
+        name: inboundString(option['name'], surface),
+    };
+    optionalNullableString(output, option, 'description', surface);
+    attachParsedMeta(output, option, surface);
+    return output;
+}
+function parseSessionConfigSelectGroup(value, surface) {
+    const group = messageRecord(value, surface);
+    const options = group['options'];
+    if (!Array.isArray(options))
+        throw invalidMessage(surface);
+    return {
+        group: inboundIdentifier(group['group'], surface),
+        name: inboundString(group['name'], surface),
+        options: options.map((option) => parseSessionConfigSelectOption(option, surface)),
+        ...metaProperty(group, surface),
+    };
+}
+function knownSessionUpdate(value) {
+    return [
+        'user_message_chunk',
+        'agent_message_chunk',
+        'agent_thought_chunk',
+        'tool_call',
+        'tool_call_update',
+        'plan',
+        'available_commands_update',
+        'current_mode_update',
+        'config_option_update',
+        'session_info_update',
+        'usage_update',
+    ].includes(value);
+}
+function validateImplementation(value, surface, code) {
+    const input = code === 'invalid_message'
+        ? messageRecord(value, surface)
+        : localRecord(value, surface);
+    const output = {
+        name: code === 'invalid_message'
+            ? inboundString(input['name'], surface)
+            : boundedString(input['name'], surface),
+        version: code === 'invalid_message'
+            ? inboundString(input['version'], surface)
+            : boundedString(input['version'], surface),
+    };
+    optionalNullableString(output, input, 'title', surface, code);
+    if (code === 'invalid_message')
+        attachParsedMeta(output, input, surface);
+    else
+        attachMeta(output, input['_meta'], code);
+    return output;
+}
+function optionalBoolean(record, key, surface) {
+    const value = record[key];
+    if (value === undefined)
+        return false;
+    if (typeof value !== 'boolean')
+        throw invalidMessage(surface);
+    return value;
+}
+function optionalMarker(record, key, surface) {
+    const value = record[key];
+    if (value === undefined || value === null)
+        return false;
+    if (!isRecord(value))
+        throw invalidMessage(surface);
+    return true;
+}
+function optionalRecord(record, key, surface) {
+    const value = record[key];
+    if (value === undefined)
+        return {};
+    if (!isRecord(value))
+        throw invalidMessage(surface);
+    return value;
+}
+function annotationsProperty(source, surface) {
+    if (!Object.hasOwn(source, 'annotations'))
+        return {};
+    const value = source['annotations'];
+    return {
+        annotations: value === null ? null : parseAnnotations(value, surface),
+    };
+}
+function parseAnnotations(value, surface) {
+    const annotations = messageRecord(value, surface);
+    const output = {};
+    if (annotations['audience'] !== undefined) {
+        const audience = annotations['audience'];
+        if (audience !== null &&
+            (!Array.isArray(audience) ||
+                !audience.every((role) => role === 'assistant' || role === 'user'))) {
+            throw invalidMessage(surface);
+        }
+        output.audience = audience;
+    }
+    if (annotations['priority'] !== undefined) {
+        const priority = annotations['priority'];
+        if (priority !== null &&
+            (typeof priority !== 'number' || !Number.isFinite(priority))) {
+            throw invalidMessage(surface);
+        }
+        output.priority = priority;
+    }
+    optionalNullableString(output, annotations, 'lastModified', surface);
+    attachParsedMeta(output, annotations, surface);
+    return output;
+}
+function validateLocalAnnotations(value, surface) {
+    if (value === undefined || value === null)
+        return;
+    const annotations = localRecord(value, surface);
+    const audience = annotations['audience'];
+    if (audience !== undefined &&
+        audience !== null &&
+        (!Array.isArray(audience) ||
+            !audience.every((role) => role === 'assistant' || role === 'user'))) {
+        throw invalidParams(`The ACP ${surface} is invalid.`);
+    }
+    const priority = annotations['priority'];
+    if (priority !== undefined &&
+        priority !== null &&
+        (typeof priority !== 'number' || !Number.isFinite(priority))) {
+        throw invalidParams(`The ACP ${surface} is invalid.`);
+    }
+    validateOptionalLocalString(annotations, 'lastModified', `${surface} last-modified value`);
+    validateMeta(annotations['_meta'], 'invalid_params');
+}
+function validateOptionalLocalString(source, key, surface) {
+    const value = source[key];
+    if (value !== undefined && value !== null)
+        boundedString(value, surface);
+}
+function optionalNullableString(output, source, key, surface, code = 'invalid_message') {
+    if (!Object.hasOwn(source, key))
+        return;
+    const value = source[key];
+    if (value !== null && typeof value !== 'string') {
+        if (code === 'invalid_message')
+            throw invalidMessage(surface);
+        throw invalidParams(`The ACP ${surface} is invalid.`);
+    }
+    output[key] = value;
+}
+function nullableStringProperty(source, key, surface) {
+    const output = {};
+    optionalNullableString(output, source, key, surface);
+    return output;
+}
+function metaProperty(source, surface) {
+    const output = {};
+    attachParsedMeta(output, source, surface);
+    return output;
+}
+function attachParsedMeta(output, source, surface) {
+    if (!Object.hasOwn(source, '_meta'))
+        return;
+    const value = source['_meta'];
+    if (value !== null && !isRecord(value))
+        throw invalidMessage(surface);
+    output._meta = value;
+}
+function attachMeta(output, value, code) {
+    if (value === undefined)
+        return;
+    validateMeta(value, code);
+    output['_meta'] = value;
+}
+function validateMeta(value, code) {
+    if (value === undefined)
+        return;
+    if (value !== null && !isRecord(value)) {
+        if (code === 'invalid_message')
+            throw invalidMessage('ACP metadata');
+        throw invalidParams('ACP metadata must be an object or null.');
+    }
+}
+function assertOptionalBoolean(value, surface) {
+    if (value !== undefined && typeof value !== 'boolean') {
+        throw invalidParams(`The ACP ${surface} is invalid.`);
+    }
+}
+function validateNameValueArray(value, surface) {
+    if (!Array.isArray(value))
+        throw invalidParams(`ACP ${surface} must be an array.`);
+    for (const item of value) {
+        const entry = localRecord(item, surface);
+        identifier(entry['name'], `${surface} name`);
+        boundedString(entry['value'], `${surface} value`);
+        validateMeta(entry['_meta'], 'invalid_params');
+    }
+}
+function stringArray(value, surface, requireNonEmpty) {
+    if (!Array.isArray(value) || (requireNonEmpty && value.length === 0)) {
+        throw invalidParams(`ACP ${surface} must be an array.`);
+    }
+    for (const item of value)
+        boundedString(item, surface);
+    return value;
+}
+function inboundStringArray(value, surface) {
+    if (!Array.isArray(value) ||
+        !value.every((item) => typeof item === 'string')) {
+        throw invalidMessage(surface);
+    }
+    return value;
+}
+function nonNegativeSafeInteger(value, surface) {
+    if (!nonNegativeInteger(value))
+        throw invalidMessage(surface);
+    return value;
+}
+function identifier(value, surface) {
+    if (typeof value !== 'string' ||
+        value.length === 0 ||
+        value.length > maximumIdentifierLength) {
+        throw invalidParams(`The ACP ${surface} is invalid.`);
+    }
+    return value;
+}
+function inboundIdentifier(value, surface) {
+    if (typeof value !== 'string' ||
+        value.length === 0 ||
+        value.length > maximumIdentifierLength) {
+        throw invalidMessage(surface);
+    }
+    return value;
+}
+function boundedString(value, surface) {
+    if (typeof value !== 'string' ||
+        value.length === 0 ||
+        value.length > maximumStringLength) {
+        throw invalidParams(`The ACP ${surface} is invalid.`);
+    }
+    return value;
+}
+function inboundString(value, surface) {
+    if (typeof value !== 'string' ||
+        value.length === 0 ||
+        value.length > maximumStringLength) {
+        throw invalidMessage(surface);
+    }
+    return value;
+}
+function absolutePath(value, surface) {
+    const path = boundedString(value, surface);
+    if (!isAbsolute(path))
+        throw invalidParams(`The ACP ${surface} must be absolute.`);
+    return path;
+}
+function inboundAbsolutePath(value, surface) {
+    const path = inboundString(value, surface);
+    if (!isAbsolute(path))
+        throw invalidMessage(surface);
+    return path;
+}
+function httpUrl(value, surface) {
+    const encoded = boundedString(value, surface);
+    let parsed;
+    try {
+        parsed = new URL(encoded);
+    }
+    catch {
+        throw invalidParams(`The ACP ${surface} is invalid.`);
+    }
+    if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') {
+        throw invalidParams(`The ACP ${surface} must use HTTP or HTTPS.`);
+    }
+    return encoded;
+}
+function capabilityContent(name) {
+    throw acpError('capability_not_advertised', `The ACP Agent did not advertise ${name} prompt support.`);
+}
+function messageRecord(value, surface) {
+    if (!isRecord(value))
+        throw invalidMessage(surface);
+    return value;
+}
+function localRecord(value, surface) {
+    if (!isRecord(value))
+        throw invalidParams(`The ACP ${surface} is invalid.`);
+    return value;
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function nonNegativeInteger(value) {
+    return typeof value === 'number' && Number.isSafeInteger(value) && value >= 0;
+}
+function unsigned32BitInteger(value) {
+    return nonNegativeInteger(value) && value <= 4_294_967_295;
+}
+function invalidMessage(surface) {
+    return acpError('invalid_message', `The ACP peer sent an invalid ${surface}.`);
+}
+function invalidParams(message) {
+    return acpError('invalid_params', message);
+}
+function publicMethod(value) {
+    if (knownMethods.has(value) || /^_[\u0021-\u007e]{0,255}$/u.test(value)) {
+        return value;
+    }
+    return stableDiagnostic('method', value);
+}
+function redact(value, depth, state, key) {
+    state.nodes += 1;
+    if (state.nodes > maximumRawNodes || depth >= maximumRawDepth) {
+        return '[truncated]';
+    }
+    if (value === null)
+        return value;
+    if (typeof value === 'boolean' || typeof value === 'number') {
+        return '[redacted]';
+    }
+    if (typeof value === 'string') {
+        return key !== undefined && structuralStringKeys.has(key)
+            ? publicStructuralValue(value)
+            : '[redacted]';
+    }
+    if (Array.isArray(value)) {
+        const output = value
+            .slice(0, maximumRawItems)
+            .map((item) => redact(item, depth + 1, state));
+        if (value.length > maximumRawItems)
+            output.push('[truncated]');
+        return output;
+    }
+    if (!isRecord(value))
+        return '[redacted]';
+    const output = {};
+    const entries = Object.entries(value);
+    for (const [index, [entryKey, item]] of entries
+        .slice(0, maximumRawItems)
+        .entries()) {
+        const safeKey = structuralStringKeys.has(entryKey)
+            ? entryKey
+            : `[redacted-key-${String(index)}]`;
+        output[safeKey] = redact(item, depth + 1, state, entryKey);
+    }
+    if (entries.length > maximumRawItems || state.nodes > maximumRawNodes) {
+        output['__truncated__'] = '[truncated]';
+    }
+    return output;
+}
+function publicStructuralValue(value) {
+    return knownStructuralValues.has(value)
+        ? value
+        : stableDiagnostic('value', value);
+}
+function stableDiagnostic(prefix, value) {
+    const digest = createHash('sha256').update(value).digest('hex').slice(0, 16);
+    return `${prefix}-${digest}`;
+}
+//# sourceMappingURL=validation.js.map