@adcp/sdk 5.23.0

package/dist/lib/core/ProtocolResponseParser.js

@@ -0,0 +1,367 @@
+"use strict";
+/**
+ * Simple ADCP-compliant response parser
+ * Implements ADCP spec PR #77 for standardized status field
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.responseParser = exports.ProtocolResponseParser = exports.ADCP_STATUS = void 0;
+/**
+ * ADCP standardized status values as per spec PR #78
+ * Clear semantics for async task management:
+ * - submitted: Long-running tasks (hours to days) - webhook required
+ * - working: Processing tasks (<120 seconds) - keep connection open
+ * - input-required: Tasks needing user interaction via handler
+ * - completed: Successful task completion
+ */
+exports.ADCP_STATUS = {
+    SUBMITTED: 'submitted', // Long-running (hours/days) - webhook required
+    WORKING: 'working', // Processing (<120s) - keep connection open
+    INPUT_REQUIRED: 'input-required', // Needs user input via handler
+    COMPLETED: 'completed', // Task completed successfully
+    FAILED: 'failed', // Task failed
+    CANCELED: 'canceled', // Task was canceled
+    REJECTED: 'rejected', // Task was rejected
+    AUTH_REQUIRED: 'auth-required', // Authentication required
+    UNKNOWN: 'unknown', // Unknown status
+};
+/**
+ * Fields that belong to the task envelope, not to a domain payload. Derived
+ * from `ProtocolEnvelope` (core/protocol-envelope.json) plus the optional
+ * `errors` / `context` / `ext` fields that AdCP task-response schemas place at
+ * envelope level. Used to disambiguate `structuredContent.status` from AdCP v3
+ * domain status enums (MediaBuyStatus, CreativeStatus, etc.) that share
+ * literals like `completed` / `canceled` / `failed` / `rejected` — see #646.
+ */
+const TASK_ENVELOPE_FIELDS = new Set([
+    'status',
+    'message',
+    'timestamp',
+    'context_id',
+    'task_id',
+    'replayed',
+    'push_notification_config',
+    'governance_context',
+    'adcp_version',
+    'errors',
+    'context',
+    'ext',
+]);
+/**
+ * ADCP task-lifecycle statuses that never overlap with AdCP domain status
+ * enums and can be trusted from `structuredContent.status` unconditionally.
+ * The other literals (`completed` / `canceled` / `failed` / `rejected`) share
+ * values with `MediaBuyStatus` et al and require envelope-shape disambiguation.
+ */
+const EXCLUSIVE_TASK_STATUSES = new Set([
+    exports.ADCP_STATUS.SUBMITTED,
+    exports.ADCP_STATUS.WORKING,
+    exports.ADCP_STATUS.INPUT_REQUIRED,
+    exports.ADCP_STATUS.AUTH_REQUIRED,
+]);
+/**
+ * Max length for a server-issued session id (`contextId` / `taskId`) we
+ * will retain on the client. Well above any sane UUID, opaque token, or
+ * ADK-style hierarchical id — exceeding it signals a misbehaving seller,
+ * not a legitimate identifier.
+ */
+const SESSION_ID_MAX_LENGTH = 256;
+/**
+ * Printable ASCII only (0x20–0x7E). Rejects control characters (CR, LF,
+ * NUL, ANSI sequences) that would be retained verbatim on future sends
+ * and echoed into debug logs — a log-injection vector if those logs reach
+ * third-party observability stacks. This is stricter than the A2A spec,
+ * which treats the id as opaque, but matches every id format we've seen
+ * in the wild (UUIDs, KSUIDs, ADK `app/user/session` triples, etc.).
+ */
+const SESSION_ID_PATTERN = /^[\x20-\x7E]+$/;
+function isSafeSessionId(v) {
+    if (typeof v !== 'string')
+        return false;
+    if (v.length === 0 || v.length > SESSION_ID_MAX_LENGTH)
+        return false;
+    return SESSION_ID_PATTERN.test(v);
+}
+/**
+ * Extract the AdCP work-layer status from an A2A wrapped Task result,
+ * if present. The AdCP `submitted` / `working` / `completed` lifecycle
+ * lives on `artifact.parts[0].data.status` (per adcp-client#899's
+ * two-lifecycle contract); the transport-layer `result.status.state`
+ * tracks the HTTP-call lifecycle and is `'completed'` for AdCP
+ * submitted arms.
+ *
+ * Returns `undefined` for non-AdCP A2A responses (no artifact, no
+ * DataPart, or `data.status` not in the AdCP enum) so callers can
+ * fall back to the transport-layer status.
+ */
+function extractAdcpStatusFromA2aTaskResult(result) {
+    if (result == null || typeof result !== 'object' || Array.isArray(result))
+        return undefined;
+    if (result.kind !== 'task')
+        return undefined;
+    const artifacts = result.artifacts;
+    if (!Array.isArray(artifacts) || artifacts.length === 0)
+        return undefined;
+    const artifact = artifacts[0];
+    if (artifact == null || typeof artifact !== 'object')
+        return undefined;
+    const parts = artifact.parts;
+    if (!Array.isArray(parts) || parts.length === 0)
+        return undefined;
+    const firstPart = parts[0];
+    if (firstPart == null || typeof firstPart !== 'object' || firstPart.kind !== 'data')
+        return undefined;
+    const data = firstPart.data;
+    if (data == null || typeof data !== 'object' || Array.isArray(data))
+        return undefined;
+    const status = data.status;
+    if (typeof status === 'string' && Object.values(exports.ADCP_STATUS).includes(status)) {
+        return status;
+    }
+    return undefined;
+}
+/**
+ * Extract the AdCP task handle from an A2A wrapped Task result. The
+ * handle lives on `artifact.metadata.adcp_task_id` (per
+ * adcp-client#899). Returns `undefined` for non-AdCP A2A responses or
+ * when the metadata extension wasn't emitted, so callers fall back
+ * to the transport-layer `result.id`.
+ */
+function extractAdcpTaskIdFromA2aTaskResult(result) {
+    if (result == null || typeof result !== 'object' || Array.isArray(result))
+        return undefined;
+    if (result.kind !== 'task')
+        return undefined;
+    const artifacts = result.artifacts;
+    if (!Array.isArray(artifacts) || artifacts.length === 0)
+        return undefined;
+    const artifact = artifacts[0];
+    if (artifact == null || typeof artifact !== 'object')
+        return undefined;
+    const metadata = artifact.metadata;
+    if (metadata == null || typeof metadata !== 'object' || Array.isArray(metadata))
+        return undefined;
+    return firstSafeSessionId(metadata.adcp_task_id);
+}
+/** Return the first argument that passes {@link isSafeSessionId}, else `undefined`. */
+function firstSafeSessionId(...candidates) {
+    for (const c of candidates) {
+        if (isSafeSessionId(c))
+            return c;
+    }
+    return undefined;
+}
+/**
+ * Simple parser that follows ADCP spec exactly
+ */
+class ProtocolResponseParser {
+    /**
+     * Check if response indicates input is needed per ADCP spec
+     */
+    isInputRequest(response) {
+        // ADCP spec: check A2A JSON-RPC wrapped status first
+        if (response?.result?.status?.state === exports.ADCP_STATUS.INPUT_REQUIRED) {
+            return true;
+        }
+        // ADCP spec: check top-level status field
+        if (response?.status === exports.ADCP_STATUS.INPUT_REQUIRED) {
+            return true;
+        }
+        // Legacy fallback for backward compatibility
+        return (response?.type === 'input_request' ||
+            response?.question !== undefined ||
+            response?.input_required === true ||
+            response?.needs_clarification === true);
+    }
+    /**
+     * Parse input request from response
+     */
+    parseInputRequest(response) {
+        const question = response.message || response.question || response.prompt || 'Please provide input';
+        const field = response.field || response.parameter;
+        const suggestions = response.options || response.choices || response.suggestions;
+        return {
+            question,
+            field,
+            expectedType: this.parseExpectedType(response.expected_type || response.type),
+            suggestions,
+            required: response.required !== false,
+            validation: response.validation,
+            context: response.context || response.description,
+        };
+    }
+    /**
+     * Get ADCP status from response
+     */
+    getStatus(response) {
+        // For A2A wrapped Task responses (`result.kind === 'task'`), the
+        // transport-layer `result.status.state` reflects the HTTP-call
+        // lifecycle (always `'completed'` for AdCP submitted arms per
+        // adcp-client#899), NOT the AdCP work lifecycle. Prefer the AdCP
+        // status surfaced on the artifact's DataPart when it's set —
+        // that's the layer the buyer cares about for polling decisions.
+        // See adcp-client#973 for the regression class this catches.
+        const adcpStatusFromArtifact = extractAdcpStatusFromA2aTaskResult(response?.result);
+        if (adcpStatusFromArtifact)
+            return adcpStatusFromArtifact;
+        // Check A2A JSON-RPC wrapped status (result.status.state) — used
+        // when the artifact didn't surface an AdCP status (non-AdCP A2A
+        // responses, or sync-completed responses where transport state is
+        // authoritative).
+        if (response?.result?.status?.state && Object.values(exports.ADCP_STATUS).includes(response.result.status.state)) {
+            return response.result.status.state;
+        }
+        // Check top-level status first (A2A and direct responses)
+        if (response?.status && Object.values(exports.ADCP_STATUS).includes(response.status)) {
+            return response.status;
+        }
+        // Check MCP structuredContent.status.
+        // Exclusive task-lifecycle statuses (submitted/working/input-required/
+        // auth-required) never appear in domain enums and are trusted unconditionally.
+        // Shared literals (completed/canceled/failed/rejected) collide with AdCP v3
+        // domain status enums like MediaBuyStatus, so we only treat them as task
+        // status when the envelope has no keys outside the task-envelope allowlist.
+        // Otherwise we fall through to the structuredContent fallback below, so Zod
+        // validators parse the domain payload. See issue #646.
+        const sc = response?.structuredContent;
+        if (sc?.status && Object.values(exports.ADCP_STATUS).includes(sc.status)) {
+            if (EXCLUSIVE_TASK_STATUSES.has(sc.status)) {
+                return sc.status;
+            }
+            const hasDomainPayload = Object.keys(sc).some(k => !TASK_ENVELOPE_FIELDS.has(k));
+            if (!hasDomainPayload) {
+                return sc.status;
+            }
+            // Domain payload present alongside a shared-literal status — fall through.
+        }
+        // Check for MCP error responses
+        if (response?.isError === true) {
+            return exports.ADCP_STATUS.FAILED;
+        }
+        // If response has structuredContent or content, assume it's completed
+        if (response?.structuredContent || (response?.content && !response?.isError)) {
+            return exports.ADCP_STATUS.COMPLETED;
+        }
+        return null;
+    }
+    /**
+     * Extract the `replayed` field from a protocol response envelope.
+     *
+     * Returns `true` if the seller set `replayed: true` on the envelope,
+     * `false` if explicitly set to `false`, `undefined` if not present. Callers
+     * with side effects on response (notifications, LLM memory writes, downstream
+     * tool calls) MUST treat `undefined` as `false` — the spec says fresh
+     * executions MAY omit the field.
+     */
+    getReplayed(response) {
+        if (response == null)
+            return undefined;
+        // A2A JSON-RPC wrapped
+        if (response.result && typeof response.result.replayed === 'boolean') {
+            return response.result.replayed;
+        }
+        // MCP structuredContent
+        if (response.structuredContent && typeof response.structuredContent.replayed === 'boolean') {
+            return response.structuredContent.replayed;
+        }
+        // Top-level envelope (A2A direct, REST)
+        if (typeof response.replayed === 'boolean') {
+            return response.replayed;
+        }
+        return undefined;
+    }
+    /**
+     * Extract the A2A `contextId` / AdCP `context_id` that binds the response
+     * to a server-side conversation. Buyers retain this across calls on the
+     * same AgentClient so the server can route subsequent sends to the same
+     * session. Returns `undefined` when the server did not surface one (e.g.,
+     * MCP completed responses that don't need conversation continuity).
+     *
+     * Values that fail {@link isSafeSessionId} (overlong, control characters,
+     * non-string) are rejected and return `undefined` — retention falls back
+     * to the previously retained id. The server is the authoritative issuer
+     * but a compromised or buggy seller shouldn't be able to exhaust buyer
+     * memory or inject control sequences into buyer debug logs.
+     */
+    getContextId(response) {
+        if (response == null)
+            return undefined;
+        // A2A sendMessage returns either a Task (has `contextId`) or a Message
+        // (may have `contextId`). With the A2AClient SDK these arrive unwrapped
+        // on `response.result`; some transports surface them directly on the
+        // response envelope, so check both.
+        if (response.result) {
+            const fromResult = firstSafeSessionId(response.result.contextId, response.result.context_id);
+            if (fromResult)
+                return fromResult;
+        }
+        const fromEnvelope = firstSafeSessionId(response.contextId);
+        if (fromEnvelope)
+            return fromEnvelope;
+        // MCP structuredContent / top-level AdCP envelope.
+        const sc = response.structuredContent;
+        if (sc) {
+            const fromSc = firstSafeSessionId(sc.context_id);
+            if (fromSc)
+                return fromSc;
+        }
+        return firstSafeSessionId(response.context_id);
+    }
+    /**
+     * Extract the A2A `taskId` for the task the server is tracking (or just
+     * created) for this send. Retained across calls only while the last
+     * response was non-terminal (working / input-required / submitted /
+     * auth-required) so buyers can resume the same server-side task; cleared
+     * by the caller on terminal responses.
+     *
+     * Same sanitization rules as {@link getContextId}: malformed ids return
+     * `undefined`.
+     */
+    getTaskId(response) {
+        if (response == null)
+            return undefined;
+        if (response.result) {
+            // A2A wrapped Task with AdCP payload — `artifact.metadata.adcp_task_id`
+            // is the AdCP work handle (what the buyer polls with via AdCP
+            // `tasks/get`). The transport-layer `result.id` is the A2A
+            // Task.id (always pinned to one HTTP call per adcp-client#899's
+            // two-lifecycle contract); using it as a polling key would
+            // address the wrong thing. Prefer the AdCP handle when present;
+            // fall back to `result.id` for non-AdCP A2A responses where no
+            // artifact metadata was emitted. See adcp-client#973.
+            if (response.result.kind === 'task') {
+                const adcpHandle = extractAdcpTaskIdFromA2aTaskResult(response.result);
+                if (adcpHandle)
+                    return adcpHandle;
+                const taskKindId = firstSafeSessionId(response.result.id);
+                if (taskKindId)
+                    return taskKindId;
+            }
+            const fromResult = firstSafeSessionId(response.result.taskId, response.result.id, response.result.task_id);
+            if (fromResult)
+                return fromResult;
+        }
+        const fromEnvelope = firstSafeSessionId(response.taskId);
+        if (fromEnvelope)
+            return fromEnvelope;
+        const sc = response.structuredContent;
+        if (sc) {
+            const fromSc = firstSafeSessionId(sc.task_id);
+            if (fromSc)
+                return fromSc;
+        }
+        return firstSafeSessionId(response.task_id);
+    }
+    parseExpectedType(rawType) {
+        if (typeof rawType === 'string') {
+            const allowedTypes = ['string', 'number', 'boolean', 'object', 'array'];
+            return allowedTypes.includes(rawType)
+                ? rawType
+                : undefined;
+        }
+        return undefined;
+    }
+}
+exports.ProtocolResponseParser = ProtocolResponseParser;
+// Export singleton instance
+exports.responseParser = new ProtocolResponseParser();
+//# sourceMappingURL=ProtocolResponseParser.js.map

package/dist/lib/core/ProtocolResponseParser.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ProtocolResponseParser.js","sourceRoot":"","sources":["../../../src/lib/core/ProtocolResponseParser.ts"],"names":[],"mappings":"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"}

package/dist/lib/core/ResponseValidator.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Response validator for agent responses
+ *
+ * Validates that agent responses match expected structures for both
+ * MCP and A2A protocols, and validates data against AdCP schemas.
+ */
+import { z } from 'zod';
+export interface ValidationResult {
+    valid: boolean;
+    errors: string[];
+    warnings: string[];
+    protocol?: 'mcp' | 'a2a' | 'unknown';
+    schemaErrors?: z.ZodIssue[];
+}
+export interface ValidationOptions {
+    /** Enable strict mode - fail on warnings */
+    strict?: boolean;
+    /** Expected data fields (e.g., ['products'] for get_products) */
+    expectedFields?: string[];
+    /** Allow empty responses */
+    allowEmpty?: boolean;
+    /** Validate against AdCP Zod schemas */
+    validateSchema?: boolean;
+}
+export declare class ResponseValidator {
+    /**
+     * Validate an agent response structure
+     */
+    validate(response: any, toolName?: string, options?: ValidationOptions): ValidationResult;
+    /**
+     * Validate MCP response structure
+     */
+    private validateMCPResponse;
+    /**
+     * Validate A2A response structure
+     */
+    private validateA2AResponse;
+    /**
+     * Validate expected fields are present in the response
+     */
+    private validateExpectedFields;
+    /**
+     * Validate response is not empty
+     */
+    private validateNotEmpty;
+    /**
+     * Quick validation helper - returns true if valid, throws if invalid
+     */
+    validateOrThrow(response: any, toolName?: string, options?: ValidationOptions): void;
+    /**
+     * Check if a response looks like a valid protocol response
+     */
+    isValidProtocolResponse(response: any): boolean;
+    /**
+     * Extract response data based on protocol for validation.
+     */
+    private extractDataForValidation;
+    /**
+     * Validate response data against AdCP Zod schema
+     */
+    private validateWithSchema;
+    /**
+     * Get Zod schema for a given tool
+     */
+    private getSchemaForTool;
+}
+export declare const responseValidator: ResponseValidator;
+//# sourceMappingURL=ResponseValidator.d.ts.map

package/dist/lib/core/ResponseValidator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ResponseValidator.d.ts","sourceRoot":"","sources":["../../../src/lib/core/ResponseValidator.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAIxB,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,OAAO,CAAC;IACf,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,QAAQ,CAAC,EAAE,KAAK,GAAG,KAAK,GAAG,SAAS,CAAC;IACrC,YAAY,CAAC,EAAE,CAAC,CAAC,QAAQ,EAAE,CAAC;CAC7B;AAED,MAAM,WAAW,iBAAiB;IAChC,4CAA4C;IAC5C,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,iEAAiE;IACjE,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAC1B,4BAA4B;IAC5B,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,wCAAwC;IACxC,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B;AAED,qBAAa,iBAAiB;IAC5B;;OAEG;IACH,QAAQ,CAAC,QAAQ,EAAE,GAAG,EAAE,QAAQ,CAAC,EAAE,MAAM,EAAE,OAAO,GAAE,iBAAsB,GAAG,gBAAgB;IAyE7F;;OAEG;IACH,OAAO,CAAC,mBAAmB;IAgC3B;;OAEG;IACH,OAAO,CAAC,mBAAmB;IA0D3B;;OAEG;IACH,OAAO,CAAC,sBAAsB;IAiC9B;;OAEG;IACH,OAAO,CAAC,gBAAgB;IAiBxB;;OAEG;IACH,eAAe,CAAC,QAAQ,EAAE,GAAG,EAAE,QAAQ,CAAC,EAAE,MAAM,EAAE,OAAO,GAAE,iBAAsB,GAAG,IAAI;IAQxF;;OAEG;IACH,uBAAuB,CAAC,QAAQ,EAAE,GAAG,GAAG,OAAO;IAuB/C;;OAEG;IACH,OAAO,CAAC,wBAAwB;IAUhC;;OAEG;IACH,OAAO,CAAC,kBAAkB;IAkB1B;;OAEG;IACH,OAAO,CAAC,gBAAgB;CAGzB;AAGD,eAAO,MAAM,iBAAiB,mBAA0B,CAAC"}