@coralai/sps-cli 0.63.5 → 0.65.0

package/dist/runtime/contract/processProtocol.js

@@ -0,0 +1,779 @@
+/**
+ * Versioned NDJSON contract between an agent supervisor and a short-lived
+ * external agent worker. This protocol is independent from the agentd socket
+ * protocol: stdin carries commands, stdout carries events, and stderr is
+ * reserved for diagnostics.
+ */
+export const AGENT_PROCESS_PROTOCOL_VERSION = 1;
+export class AgentProcessProtocolError extends Error {
+    code;
+    line;
+    constructor(code, message, line) {
+        super(message);
+        this.code = code;
+        this.line = line;
+        this.name = 'AgentProcessProtocolError';
+    }
+}
+const EVENT_TYPES = new Set([
+    'session.started',
+    'capabilities',
+    'assistant.delta',
+    'assistant.message',
+    'tool.call',
+    'tool.progress',
+    'tool.result',
+    'agent.changed',
+    'interaction.required',
+    'context.compacted',
+    'usage.updated',
+    'system.warning',
+    'run.waiting_for_input',
+    'run.completed',
+    'run.failed',
+    'run.cancelled',
+]);
+const TERMINAL_EVENT_TYPES = new Set([
+    'run.waiting_for_input',
+    'run.completed',
+    'run.failed',
+    'run.cancelled',
+]);
+const ERROR_CODES = new Set([
+    'not_found',
+    'corrupt',
+    'unsupported_version',
+    'incompatible_agent_graph',
+    'missing_tool',
+    'workspace_unavailable',
+    'provider_state_unavailable',
+    'operator_reconciliation',
+    'provider_error',
+    'tool_error',
+    'guardrail_error',
+    'protocol_error',
+    'persistence_error',
+    'internal_error',
+]);
+export function isTerminalAgentProcessEventType(type) {
+    return TERMINAL_EVENT_TYPES.has(type);
+}
+export function parseAgentProcessCommandV1(value) {
+    const command = requireRecord(value, 'command');
+    requireProtocolVersion(command);
+    const kind = requireString(command, 'command');
+    if (kind === 'start') {
+        return parseStartCommand(command);
+    }
+    if (kind === 'cancel') {
+        return parseCancelCommand(command);
+    }
+    throw protocolError('unexpected_command', `Unsupported worker command: ${kind}`);
+}
+export function parseAgentProcessEventV1(value) {
+    const event = requireRecord(value, 'event');
+    assertAllowedKeys(event, 'event', [
+        'protocolVersion',
+        'eventId',
+        'sessionId',
+        'runId',
+        'turnId',
+        'sequence',
+        'timestamp',
+        'type',
+        'payload',
+        'backend',
+    ]);
+    requireProtocolVersion(event);
+    const type = requireString(event, 'type');
+    if (!EVENT_TYPES.has(type)) {
+        throw protocolError('invalid_shape', `Unknown worker event type: ${type}`);
+    }
+    const parsedType = type;
+    const sequence = requireInteger(event, 'sequence', 1);
+    const timestamp = requireString(event, 'timestamp');
+    if (!Number.isFinite(Date.parse(timestamp))) {
+        throw protocolError('invalid_shape', 'event.timestamp must be an ISO-compatible date');
+    }
+    const backend = parseBackendMetadata(event.backend);
+    const payload = parseEventPayload(parsedType, event.payload);
+    return {
+        protocolVersion: AGENT_PROCESS_PROTOCOL_VERSION,
+        eventId: requireNonEmptyString(event, 'eventId'),
+        sessionId: requireNonEmptyString(event, 'sessionId'),
+        runId: requireNonEmptyString(event, 'runId'),
+        turnId: requireNonEmptyString(event, 'turnId'),
+        sequence,
+        timestamp,
+        type: parsedType,
+        payload,
+        backend,
+    };
+}
+/**
+ * Stateful validation for a single run. It rejects identity changes,
+ * duplicate IDs, non-contiguous sequence numbers, and output after terminal.
+ */
+export class AgentProcessEventStreamValidator {
+    expected;
+    options;
+    eventIds = new Set();
+    nextSequence;
+    terminal = false;
+    constructor(expected, options = {}) {
+        this.expected = expected;
+        this.options = options;
+        this.nextSequence = (options.initialSequence ?? 0) + 1;
+    }
+    accept(value) {
+        const event = parseAgentProcessEventV1(value);
+        if (this.terminal) {
+            throw protocolError('after_terminal', `Event ${event.eventId} arrived after terminal`);
+        }
+        if ((this.expected?.sessionId !== undefined && event.sessionId !== this.expected.sessionId) ||
+            (this.expected?.runId !== undefined && event.runId !== this.expected.runId) ||
+            (this.expected?.turnId !== undefined && event.turnId !== this.expected.turnId)) {
+            throw protocolError('identity_mismatch', 'Event identity does not match the active run');
+        }
+        if (this.eventIds.has(event.eventId)) {
+            throw protocolError('duplicate_event_id', `Duplicate eventId: ${event.eventId}`);
+        }
+        if (event.sequence !== this.nextSequence) {
+            throw protocolError('out_of_order', `Expected sequence ${this.nextSequence}, received ${event.sequence}`);
+        }
+        this.eventIds.add(event.eventId);
+        this.nextSequence += 1;
+        this.terminal =
+            isTerminalAgentProcessEventType(event.type) &&
+                !(event.type === 'run.waiting_for_input' &&
+                    this.options.allowResumeAfterWaiting);
+        return event;
+    }
+    get lastSequence() {
+        return this.nextSequence - 1;
+    }
+    get hasTerminal() {
+        return this.terminal;
+    }
+}
+/**
+ * Stateful validation for worker stdin. Exactly one start command must be the
+ * first frame; subsequent frames may only cancel that same run.
+ */
+export class AgentProcessCommandStreamValidator {
+    activeStart = null;
+    accept(value) {
+        const command = parseAgentProcessCommandV1(value);
+        if (this.activeStart === null) {
+            if (command.command !== 'start') {
+                throw protocolError('unexpected_command', 'The first worker command must be start');
+            }
+            this.activeStart = command;
+            return command;
+        }
+        if (command.command === 'start') {
+            throw protocolError('unexpected_command', 'A worker process accepts only one start command');
+        }
+        if (command.sessionId !== this.activeStart.sessionId ||
+            command.runId !== this.activeStart.runId) {
+            throw protocolError('identity_mismatch', 'Cancel command does not match the active run');
+        }
+        return command;
+    }
+    get startCommand() {
+        return this.activeStart;
+    }
+}
+/**
+ * Incremental UTF-8 NDJSON decoder. It is safe for arbitrarily split or
+ * coalesced chunks and validates every non-empty stdout line.
+ */
+export class AgentProcessEventDecoder {
+    validator;
+    decoder = new TextDecoder();
+    buffer = '';
+    constructor(validator = new AgentProcessEventStreamValidator()) {
+        this.validator = validator;
+    }
+    push(chunk) {
+        this.buffer += typeof chunk === 'string' ? chunk : this.decoder.decode(chunk, { stream: true });
+        return this.drain(false);
+    }
+    finish() {
+        this.buffer += this.decoder.decode();
+        return this.drain(true);
+    }
+    drain(final) {
+        const events = [];
+        let newline = this.buffer.indexOf('\n');
+        while (newline >= 0) {
+            const line = this.buffer.slice(0, newline).replace(/\r$/, '');
+            this.buffer = this.buffer.slice(newline + 1);
+            if (line.trim() !== '')
+                events.push(this.parseLine(line));
+            newline = this.buffer.indexOf('\n');
+        }
+        if (final && this.buffer.trim() !== '') {
+            const line = this.buffer.replace(/\r$/, '');
+            this.buffer = '';
+            throw new AgentProcessProtocolError('incomplete_frame', 'Worker stdout ended without a newline-delimited frame', line);
+        }
+        if (final)
+            this.buffer = '';
+        return events;
+    }
+    parseLine(line) {
+        let parsed;
+        try {
+            parsed = JSON.parse(line);
+        }
+        catch {
+            const code = looksLikeJson(line) ? 'invalid_json' : 'stdout_pollution';
+            throw new AgentProcessProtocolError(code, 'Worker stdout contained an invalid frame', line);
+        }
+        try {
+            return this.validator.accept(parsed);
+        }
+        catch (error) {
+            if (error instanceof AgentProcessProtocolError && error.line === undefined) {
+                throw new AgentProcessProtocolError(error.code, error.message, line);
+            }
+            throw error;
+        }
+    }
+}
+/** Incremental NDJSON decoder for worker stdin commands. */
+export class AgentProcessCommandDecoder {
+    decoder = new TextDecoder();
+    validator = new AgentProcessCommandStreamValidator();
+    buffer = '';
+    push(chunk) {
+        this.buffer += typeof chunk === 'string' ? chunk : this.decoder.decode(chunk, { stream: true });
+        return this.drain(false);
+    }
+    finish() {
+        this.buffer += this.decoder.decode();
+        return this.drain(true);
+    }
+    drain(final) {
+        const commands = [];
+        let newline = this.buffer.indexOf('\n');
+        while (newline >= 0) {
+            const line = this.buffer.slice(0, newline).replace(/\r$/, '');
+            this.buffer = this.buffer.slice(newline + 1);
+            if (line.trim() !== '')
+                commands.push(this.parseLine(line));
+            newline = this.buffer.indexOf('\n');
+        }
+        if (final && this.buffer.trim() !== '') {
+            const line = this.buffer.replace(/\r$/, '');
+            this.buffer = '';
+            throw new AgentProcessProtocolError('incomplete_frame', 'Worker stdin ended without a newline-delimited frame', line);
+        }
+        if (final)
+            this.buffer = '';
+        return commands;
+    }
+    parseLine(line) {
+        let parsed;
+        try {
+            parsed = JSON.parse(line);
+        }
+        catch {
+            throw new AgentProcessProtocolError('invalid_json', 'Worker stdin contained invalid JSON', line);
+        }
+        try {
+            return this.validator.accept(parsed);
+        }
+        catch (error) {
+            if (error instanceof AgentProcessProtocolError && error.line === undefined) {
+                throw new AgentProcessProtocolError(error.code, error.message, line);
+            }
+            throw error;
+        }
+    }
+}
+function parseStartCommand(value) {
+    assertAllowedKeys(value, 'start command', [
+        'command',
+        'protocolVersion',
+        'sessionId',
+        'runId',
+        'turnId',
+        'prompt',
+        'cwd',
+        'provider',
+        'conversationOwner',
+        'sessionRoot',
+        'agentBundleVersion',
+        'sandbox',
+        'mcp',
+        'options',
+    ]);
+    const provider = requireRecord(value.provider, 'command.provider');
+    assertAllowedKeys(provider, 'command.provider', [
+        'providerId',
+        'model',
+        'transport',
+        'baseUrl',
+    ]);
+    const transport = requireEnum(provider, 'transport', ['responses', 'chat_completions', 'codex']);
+    const conversationOwner = parseConversationOwner(value.conversationOwner);
+    const sandbox = parseSandboxPolicy(value.sandbox);
+    const mcp = requireRecord(value.mcp, 'command.mcp');
+    assertAllowedKeys(mcp, 'command.mcp', ['servers']);
+    const servers = requireArray(mcp.servers, 'mcp.servers').map((entry, index) => parseMcpServer(entry, index));
+    const options = parseStartOptions(value.options);
+    return {
+        command: 'start',
+        protocolVersion: AGENT_PROCESS_PROTOCOL_VERSION,
+        sessionId: requireNonEmptyString(value, 'sessionId'),
+        runId: requireNonEmptyString(value, 'runId'),
+        turnId: requireNonEmptyString(value, 'turnId'),
+        prompt: requireString(value, 'prompt'),
+        cwd: requireAbsolutePath(value, 'cwd'),
+        provider: {
+            providerId: requireNonEmptyString(provider, 'providerId'),
+            model: requireNonEmptyString(provider, 'model'),
+            transport,
+            ...optionalStringProperty(provider, 'baseUrl'),
+        },
+        conversationOwner,
+        sessionRoot: requireAbsolutePath(value, 'sessionRoot'),
+        agentBundleVersion: requireNonEmptyString(value, 'agentBundleVersion'),
+        sandbox,
+        mcp: { servers },
+        options,
+    };
+}
+function parseCancelCommand(value) {
+    assertAllowedKeys(value, 'cancel command', [
+        'command',
+        'protocolVersion',
+        'sessionId',
+        'runId',
+        'reason',
+    ]);
+    return {
+        command: 'cancel',
+        protocolVersion: AGENT_PROCESS_PROTOCOL_VERSION,
+        sessionId: requireNonEmptyString(value, 'sessionId'),
+        runId: requireNonEmptyString(value, 'runId'),
+        ...optionalStringProperty(value, 'reason'),
+    };
+}
+function parseConversationOwner(value) {
+    const owner = requireRecord(value, 'conversationOwner');
+    const kind = requireEnum(owner, 'kind', ['local_session', 'openai_conversation', 'previous_response']);
+    if (kind === 'openai_conversation') {
+        assertAllowedKeys(owner, 'conversationOwner', ['kind', 'conversationId']);
+        return { kind, ...optionalStringProperty(owner, 'conversationId') };
+    }
+    if (kind === 'previous_response') {
+        assertAllowedKeys(owner, 'conversationOwner', ['kind', 'previousResponseId']);
+        return { kind, ...optionalStringProperty(owner, 'previousResponseId') };
+    }
+    assertAllowedKeys(owner, 'conversationOwner', ['kind']);
+    return { kind };
+}
+function parseSandboxPolicy(value) {
+    const sandbox = requireRecord(value, 'sandbox');
+    assertAllowedKeys(sandbox, 'sandbox', ['profile', 'provider', 'workspaceId']);
+    return {
+        profile: requireNonEmptyString(sandbox, 'profile'),
+        provider: requireEnum(sandbox, 'provider', ['none', 'unix_local', 'docker', 'hosted']),
+        ...optionalStringProperty(sandbox, 'workspaceId'),
+    };
+}
+function parseMcpServer(value, index) {
+    const server = requireRecord(value, `mcp.servers[${index}]`);
+    assertAllowedKeys(server, `mcp.servers[${index}]`, [
+        'name',
+        'transport',
+        'commandRef',
+        'url',
+        'authRef',
+        'allowedTools',
+    ]);
+    const allowedToolsValue = server.allowedTools;
+    const allowedTools = allowedToolsValue === undefined
+        ? undefined
+        : requireStringArray(allowedToolsValue, `mcp.servers[${index}].allowedTools`);
+    return {
+        name: requireNonEmptyString(server, 'name'),
+        transport: requireEnum(server, 'transport', ['stdio', 'sse', 'streamable_http']),
+        ...optionalStringProperty(server, 'commandRef'),
+        ...optionalStringProperty(server, 'url'),
+        ...optionalStringProperty(server, 'authRef'),
+        ...(allowedTools === undefined ? {} : { allowedTools }),
+    };
+}
+function parseStartOptions(value) {
+    const options = requireRecord(value, 'options');
+    assertAllowedKeys(options, 'options', [
+        'maxTurns',
+        'trace',
+        'outputTypeRef',
+        'interactionAnswers',
+        'resumeFromCheckpoint',
+        'replayAfterSequence',
+    ]);
+    const maxTurns = options.maxTurns === undefined ? undefined : requireInteger(options, 'maxTurns', 1);
+    const trace = options.trace === undefined ? undefined : requireBoolean(options, 'trace');
+    const outputTypeRef = options.outputTypeRef === undefined
+        ? undefined
+        : requireNonEmptyString(options, 'outputTypeRef');
+    const resumeFromCheckpoint = options.resumeFromCheckpoint === undefined
+        ? undefined
+        : requireBoolean(options, 'resumeFromCheckpoint');
+    const replayAfterSequence = options.replayAfterSequence === undefined
+        ? undefined
+        : requireInteger(options, 'replayAfterSequence', 0);
+    let interactionAnswers;
+    if (options.interactionAnswers !== undefined) {
+        const answers = requireRecord(options.interactionAnswers, 'options.interactionAnswers');
+        assertJsonValue(answers, 'options.interactionAnswers');
+        interactionAnswers = answers;
+    }
+    return {
+        ...(maxTurns === undefined ? {} : { maxTurns }),
+        ...(trace === undefined ? {} : { trace }),
+        ...(outputTypeRef === undefined ? {} : { outputTypeRef }),
+        ...(interactionAnswers === undefined ? {} : { interactionAnswers }),
+        ...(resumeFromCheckpoint === undefined
+            ? {}
+            : { resumeFromCheckpoint }),
+        ...(replayAfterSequence === undefined
+            ? {}
+            : { replayAfterSequence }),
+    };
+}
+function parseBackendMetadata(value) {
+    const backend = requireRecord(value, 'event.backend');
+    assertAllowedKeys(backend, 'event.backend', [
+        'name',
+        'provider',
+        'model',
+        'requestId',
+        'responseId',
+        'rawType',
+        'metadata',
+    ]);
+    const name = requireEnum(backend, 'name', ['openai', 'claude']);
+    const metadata = backend.metadata === undefined
+        ? undefined
+        : requireRecord(backend.metadata, 'event.backend.metadata');
+    if (metadata !== undefined)
+        assertJsonValue(metadata, 'event.backend.metadata');
+    return {
+        name,
+        provider: requireNonEmptyString(backend, 'provider'),
+        ...optionalStringProperty(backend, 'model'),
+        ...optionalStringProperty(backend, 'requestId'),
+        ...optionalStringProperty(backend, 'responseId'),
+        ...optionalStringProperty(backend, 'rawType'),
+        ...(metadata === undefined ? {} : { metadata }),
+    };
+}
+function parseEventPayload(type, value) {
+    const payload = requireRecord(value, `event.payload(${type})`);
+    switch (type) {
+        case 'session.started':
+            assertAllowedKeys(payload, type, ['resumed', 'conversationOwner']);
+            return {
+                resumed: requireBoolean(payload, 'resumed'),
+                conversationOwner: parseConversationOwner(payload.conversationOwner),
+            };
+        case 'capabilities':
+            assertAllowedKeys(payload, type, [
+                'tools',
+                'mcpServers',
+                'features',
+                'sandboxProvider',
+            ]);
+            return {
+                tools: requireStringArray(payload.tools, 'capabilities.tools'),
+                mcpServers: requireStringArray(payload.mcpServers, 'capabilities.mcpServers'),
+                features: requireStringArray(payload.features, 'capabilities.features'),
+                sandboxProvider: requireEnum(payload, 'sandboxProvider', ['none', 'unix_local', 'docker', 'hosted']),
+            };
+        case 'assistant.delta':
+            assertAllowedKeys(payload, type, ['delta']);
+            return { delta: requireString(payload, 'delta') };
+        case 'assistant.message':
+            assertAllowedKeys(payload, type, ['text', 'itemId']);
+            return {
+                text: requireString(payload, 'text'),
+                ...optionalStringProperty(payload, 'itemId'),
+            };
+        case 'tool.call': {
+            assertAllowedKeys(payload, type, [
+                'toolCallId',
+                'toolName',
+                'input',
+                'providerCallId',
+                'itemId',
+            ]);
+            assertJsonValue(payload.input, 'tool.call.input');
+            return {
+                toolCallId: requireNonEmptyString(payload, 'toolCallId'),
+                toolName: requireNonEmptyString(payload, 'toolName'),
+                input: payload.input,
+                ...optionalStringProperty(payload, 'providerCallId'),
+                ...optionalStringProperty(payload, 'itemId'),
+            };
+        }
+        case 'tool.progress':
+            assertAllowedKeys(payload, type, ['toolCallId', 'status', 'detail']);
+            return {
+                toolCallId: requireNonEmptyString(payload, 'toolCallId'),
+                status: requireEnum(payload, 'status', ['running', 'completed', 'failed']),
+                ...optionalStringProperty(payload, 'detail'),
+            };
+        case 'tool.result': {
+            assertAllowedKeys(payload, type, ['toolCallId', 'status', 'output', 'error']);
+            assertJsonValue(payload.output, 'tool.result.output');
+            return {
+                toolCallId: requireNonEmptyString(payload, 'toolCallId'),
+                status: requireEnum(payload, 'status', ['completed', 'failed']),
+                output: payload.output,
+                ...(payload.error === undefined ? {} : { error: parseProcessError(payload.error) }),
+            };
+        }
+        case 'agent.changed':
+            assertAllowedKeys(payload, type, ['agentName', 'previousAgentName']);
+            return {
+                agentName: requireNonEmptyString(payload, 'agentName'),
+                ...optionalStringProperty(payload, 'previousAgentName'),
+            };
+        case 'interaction.required': {
+            assertAllowedKeys(payload, type, [
+                'interactionId',
+                'kind',
+                'title',
+                'schema',
+                'toolCallId',
+                'revision',
+            ]);
+            assertJsonValue(payload.schema, 'interaction.required.schema');
+            return {
+                interactionId: requireNonEmptyString(payload, 'interactionId'),
+                kind: requireEnum(payload, 'kind', [
+                    'approval',
+                    'choices',
+                    'form',
+                    'operator_reconciliation',
+                ]),
+                title: requireNonEmptyString(payload, 'title'),
+                schema: payload.schema,
+                ...optionalStringProperty(payload, 'toolCallId'),
+                ...optionalIntegerProperty(payload, 'revision', 1),
+            };
+        }
+        case 'context.compacted':
+            assertAllowedKeys(payload, type, ['strategy', 'beforeItems', 'afterItems']);
+            return {
+                strategy: requireNonEmptyString(payload, 'strategy'),
+                ...optionalIntegerProperty(payload, 'beforeItems', 0),
+                ...optionalIntegerProperty(payload, 'afterItems', 0),
+            };
+        case 'usage.updated':
+            assertAllowedKeys(payload, type, ['usage', 'final']);
+            return {
+                usage: parseUsage(payload.usage),
+                final: requireBoolean(payload, 'final'),
+            };
+        case 'system.warning':
+            assertAllowedKeys(payload, type, ['code', 'message', 'recoverable']);
+            return {
+                code: requireNonEmptyString(payload, 'code'),
+                message: requireString(payload, 'message'),
+                recoverable: requireBoolean(payload, 'recoverable'),
+            };
+        case 'run.waiting_for_input':
+            assertAllowedKeys(payload, type, ['interactionId', 'checkpointRevision']);
+            return {
+                interactionId: requireNonEmptyString(payload, 'interactionId'),
+                checkpointRevision: requireInteger(payload, 'checkpointRevision', 0),
+            };
+        case 'run.completed':
+            assertAllowedKeys(payload, type, ['output', 'usage']);
+            if (payload.output !== undefined)
+                assertJsonValue(payload.output, 'run.completed.output');
+            return {
+                ...(payload.output === undefined ? {} : { output: payload.output }),
+                ...(payload.usage === undefined ? {} : { usage: parseUsage(payload.usage) }),
+            };
+        case 'run.failed':
+            assertAllowedKeys(payload, type, ['error', 'usage']);
+            return {
+                error: parseProcessError(payload.error),
+                ...(payload.usage === undefined ? {} : { usage: parseUsage(payload.usage) }),
+            };
+        case 'run.cancelled':
+            assertAllowedKeys(payload, type, ['reason', 'checkpointRevision', 'usage']);
+            return {
+                reason: requireString(payload, 'reason'),
+                ...optionalIntegerProperty(payload, 'checkpointRevision', 0),
+                ...(payload.usage === undefined ? {} : { usage: parseUsage(payload.usage) }),
+            };
+    }
+}
+function parseUsage(value) {
+    const usage = requireRecord(value, 'usage');
+    assertAllowedKeys(usage, 'usage', [
+        'inputTokens',
+        'outputTokens',
+        'reasoningTokens',
+        'cachedInputTokens',
+        'totalTokens',
+        'costUsd',
+    ]);
+    return {
+        ...optionalIntegerProperty(usage, 'inputTokens', 0),
+        ...optionalIntegerProperty(usage, 'outputTokens', 0),
+        ...optionalIntegerProperty(usage, 'reasoningTokens', 0),
+        ...optionalIntegerProperty(usage, 'cachedInputTokens', 0),
+        ...optionalIntegerProperty(usage, 'totalTokens', 0),
+        ...optionalNumberProperty(usage, 'costUsd', 0),
+    };
+}
+function parseProcessError(value) {
+    const error = requireRecord(value, 'error');
+    assertAllowedKeys(error, 'error', ['code', 'message', 'recoverable', 'details']);
+    const code = requireString(error, 'code');
+    if (!ERROR_CODES.has(code)) {
+        throw protocolError('invalid_shape', `Unknown agent process error code: ${code}`);
+    }
+    const details = error.details === undefined ? undefined : requireRecord(error.details, 'error.details');
+    if (details !== undefined)
+        assertJsonValue(details, 'error.details');
+    return {
+        code: code,
+        message: requireString(error, 'message'),
+        recoverable: requireBoolean(error, 'recoverable'),
+        ...(details === undefined ? {} : { details }),
+    };
+}
+function requireProtocolVersion(value) {
+    if (value.protocolVersion !== AGENT_PROCESS_PROTOCOL_VERSION) {
+        throw protocolError('unsupported_version', `Unsupported agent process protocol version: ${String(value.protocolVersion)}`);
+    }
+}
+function requireRecord(value, path) {
+    if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+        throw protocolError('invalid_shape', `${path} must be an object`);
+    }
+    return value;
+}
+function requireArray(value, path) {
+    if (!Array.isArray(value)) {
+        throw protocolError('invalid_shape', `${path} must be an array`);
+    }
+    return value;
+}
+function requireString(value, key) {
+    const current = value[key];
+    if (typeof current !== 'string') {
+        throw protocolError('invalid_shape', `${key} must be a string`);
+    }
+    return current;
+}
+function requireNonEmptyString(value, key) {
+    const current = requireString(value, key);
+    if (current.trim() === '') {
+        throw protocolError('invalid_shape', `${key} must not be empty`);
+    }
+    return current;
+}
+function requireBoolean(value, key) {
+    const current = value[key];
+    if (typeof current !== 'boolean') {
+        throw protocolError('invalid_shape', `${key} must be a boolean`);
+    }
+    return current;
+}
+function requireInteger(value, key, minimum) {
+    const current = value[key];
+    if (!Number.isInteger(current) || current < minimum) {
+        throw protocolError('invalid_shape', `${key} must be an integer >= ${minimum}`);
+    }
+    return current;
+}
+function requireEnum(value, key, allowed) {
+    const current = requireString(value, key);
+    if (!allowed.includes(current)) {
+        throw protocolError('invalid_shape', `${key} must be one of: ${allowed.join(', ')}`);
+    }
+    return current;
+}
+function requireAbsolutePath(value, key) {
+    const current = requireNonEmptyString(value, key);
+    if (!current.startsWith('/')) {
+        throw protocolError('invalid_shape', `${key} must be an absolute path`);
+    }
+    return current;
+}
+function requireStringArray(value, path) {
+    if (!Array.isArray(value) || !value.every((entry) => typeof entry === 'string')) {
+        throw protocolError('invalid_shape', `${path} must be a string array`);
+    }
+    return value;
+}
+function optionalStringProperty(value, key) {
+    const current = value[key];
+    if (current === undefined)
+        return {};
+    if (typeof current !== 'string') {
+        throw protocolError('invalid_shape', `${key} must be a string when provided`);
+    }
+    return { [key]: current };
+}
+function optionalIntegerProperty(value, key, minimum) {
+    if (value[key] === undefined)
+        return {};
+    return { [key]: requireInteger(value, key, minimum) };
+}
+function optionalNumberProperty(value, key, minimum) {
+    const current = value[key];
+    if (current === undefined)
+        return {};
+    if (typeof current !== 'number' || !Number.isFinite(current) || current < minimum) {
+        throw protocolError('invalid_shape', `${key} must be a number >= ${minimum}`);
+    }
+    return { [key]: current };
+}
+function assertJsonValue(value, path) {
+    if (value === null ||
+        typeof value === 'string' ||
+        typeof value === 'boolean' ||
+        (typeof value === 'number' && Number.isFinite(value))) {
+        return;
+    }
+    if (Array.isArray(value)) {
+        value.forEach((entry, index) => assertJsonValue(entry, `${path}[${index}]`));
+        return;
+    }
+    if (typeof value === 'object') {
+        for (const [key, entry] of Object.entries(value)) {
+            assertJsonValue(entry, `${path}.${key}`);
+        }
+        return;
+    }
+    throw protocolError('invalid_shape', `${path} must be JSON-serializable`);
+}
+function assertAllowedKeys(value, path, allowed) {
+    const allowedSet = new Set(allowed);
+    const unexpected = Object.keys(value).filter((key) => !allowedSet.has(key));
+    if (unexpected.length > 0) {
+        throw protocolError('invalid_shape', `${path} contains unsupported fields: ${unexpected.join(', ')}`);
+    }
+}
+function looksLikeJson(line) {
+    const trimmed = line.trimStart();
+    return trimmed.startsWith('{') || trimmed.startsWith('[');
+}
+function protocolError(code, message) {
+    return new AgentProcessProtocolError(code, message);
+}
+//# sourceMappingURL=processProtocol.js.map