/** * A2A Handoff Observation Extension Schema (v0.14.1). * * Records observational events emitted alongside A2A v1.0 task lifecycle * transitions. Strictly observational: helpers do NOT verify Agent Card * signatures, do NOT fetch upstream events, and do NOT derive auth or trust * decisions. PEAC records what an external A2A v1 host or client attested. * * Extension namespace: `org.peacprotocol/a2a-handoff`. * * Type URIs (10): * - org.peacprotocol/a2a-agent-card-observation * - org.peacprotocol/a2a-task-submitted * - org.peacprotocol/a2a-task-accepted * - org.peacprotocol/a2a-task-rejected * - org.peacprotocol/a2a-task-state-changed * - org.peacprotocol/a2a-task-completed * - org.peacprotocol/a2a-task-failed * - org.peacprotocol/a2a-human-review-requested * - org.peacprotocol/a2a-human-approved * - org.peacprotocol/a2a-human-rejected * * Schema invariants: * - `card_ref` (3 places: top-level, from_agent, to_agent) is a strict * `sha256:<64 lowercase hex>` digest. Agent Cards are stable artifacts; * digest references are portable across vendors. * - `task_id`, `parent_task_id`, `upstream_event_ref`, `method_ref`, * `observed_by_ref` are opaque references validated by `OpaqueRefSchema` * (multi-prefix grammar: `ref:` `urn:` `did:` `sha256:` `peac:` `https://`). * - `event` and `type` MUST agree per the 9 task-event variants. * - All observation-payload schemas are `strict()` (extra keys rejected). * - `validateA2AHandoff()` returns structured `{ ok: false, errors: [{code,path,message}] }` * mapping common failures to stable error codes. */ import { z } from 'zod'; export declare const A2A_HANDOFF_EXTENSION_KEY: "org.peacprotocol/a2a-handoff"; export declare const A2A_AGENT_CARD_OBSERVATION_TYPE: "org.peacprotocol/a2a-agent-card-observation"; export declare const A2A_TASK_EVENT_TYPES: readonly ["task.submitted", "task.accepted", "task.rejected", "task.state_changed", "task.completed", "task.failed", "human.review_requested", "human.approved", "human.rejected"]; export type A2ATaskEvent = (typeof A2A_TASK_EVENT_TYPES)[number]; export declare const A2A_TASK_TYPE_URIS: Record; /** All 10 type URIs (Agent Card observation + 9 task-lifecycle events). */ export declare const A2A_HANDOFF_TYPE_URIS: readonly ["org.peacprotocol/a2a-agent-card-observation", ...string[]]; /** Stable error codes for `validateA2AHandoff`. */ export declare const A2A_HANDOFF_ERROR_CODES: { readonly observationDecisionBlocked: "a2a.observation_decision_blocked"; readonly cardRefDigestInvalid: "a2a.card_ref_digest_invalid"; readonly opaqueRefGrammarViolation: "a2a.opaque_ref_grammar_violation"; readonly legacySignatureShapeBlocked: "a2a.legacy_signature_shape_blocked"; readonly typeEventMismatch: "a2a.type_event_mismatch"; readonly timestampInvalid: "a2a.timestamp_invalid"; readonly unknownField: "a2a.unknown_field"; readonly schemaRejection: "a2a.schema_rejection"; }; /** Agent Card observation payload. */ export declare const A2AAgentCardObservationSchema: z.ZodObject<{ type: z.ZodLiteral<"org.peacprotocol/a2a-agent-card-observation">; card_ref: z.ZodString; selected_interface_url: z.ZodOptional; signature_observation: z.ZodObject<{ present: z.ZodBoolean; caller_reported_verification: z.ZodEnum<{ verified: "verified"; unverified: "unverified"; not_checked: "not_checked"; }>; method_ref: z.ZodOptional; kid: z.ZodOptional; observed_by_ref: z.ZodOptional; }, z.core.$strict>; discovered_at: z.ZodString; discovery_path: z.ZodEnum<{ "/.well-known/agent-card.json": "/.well-known/agent-card.json"; "/.well-known/peac.json": "/.well-known/peac.json"; "header-probe": "header-probe"; }>; }, z.core.$strict>; /** * Nine explicit per-event schemas. Used as members of the discriminated union * so `type` and `event` cannot drift apart. */ export declare const A2A_TASK_EVENT_SCHEMAS: { readonly 'task.submitted': z.ZodObject<{ type: z.ZodLiteral; event: z.ZodLiteral<"task.submitted">; task_id: z.ZodString; parent_task_id: z.ZodOptional; from_agent: z.ZodObject<{ card_ref: z.ZodString; selected_interface_url: z.ZodOptional; }, z.core.$strict>; to_agent: z.ZodOptional; selected_interface_url: z.ZodOptional; }, z.core.$strict>>; state: z.ZodOptional; reason: z.ZodOptional; observed_at: z.ZodString; upstream_event_ref: z.ZodOptional; upstream_event_digest: z.ZodOptional; }, z.core.$strict>; readonly 'task.accepted': z.ZodObject<{ type: z.ZodLiteral; event: z.ZodLiteral<"task.accepted">; task_id: z.ZodString; parent_task_id: z.ZodOptional; from_agent: z.ZodObject<{ card_ref: z.ZodString; selected_interface_url: z.ZodOptional; }, z.core.$strict>; to_agent: z.ZodOptional; selected_interface_url: z.ZodOptional; }, z.core.$strict>>; state: z.ZodOptional; reason: z.ZodOptional; observed_at: z.ZodString; upstream_event_ref: z.ZodOptional; upstream_event_digest: z.ZodOptional; }, z.core.$strict>; readonly 'task.rejected': z.ZodObject<{ type: z.ZodLiteral; event: z.ZodLiteral<"task.rejected">; task_id: z.ZodString; parent_task_id: z.ZodOptional; from_agent: z.ZodObject<{ card_ref: z.ZodString; selected_interface_url: z.ZodOptional; }, z.core.$strict>; to_agent: z.ZodOptional; selected_interface_url: z.ZodOptional; }, z.core.$strict>>; state: z.ZodOptional; reason: z.ZodOptional; observed_at: z.ZodString; upstream_event_ref: z.ZodOptional; upstream_event_digest: z.ZodOptional; }, z.core.$strict>; readonly 'task.state_changed': z.ZodObject<{ type: z.ZodLiteral; event: z.ZodLiteral<"task.state_changed">; task_id: z.ZodString; parent_task_id: z.ZodOptional; from_agent: z.ZodObject<{ card_ref: z.ZodString; selected_interface_url: z.ZodOptional; }, z.core.$strict>; to_agent: z.ZodOptional; selected_interface_url: z.ZodOptional; }, z.core.$strict>>; state: z.ZodOptional; reason: z.ZodOptional; observed_at: z.ZodString; upstream_event_ref: z.ZodOptional; upstream_event_digest: z.ZodOptional; }, z.core.$strict>; readonly 'task.completed': z.ZodObject<{ type: z.ZodLiteral; event: z.ZodLiteral<"task.completed">; task_id: z.ZodString; parent_task_id: z.ZodOptional; from_agent: z.ZodObject<{ card_ref: z.ZodString; selected_interface_url: z.ZodOptional; }, z.core.$strict>; to_agent: z.ZodOptional; selected_interface_url: z.ZodOptional; }, z.core.$strict>>; state: z.ZodOptional; reason: z.ZodOptional; observed_at: z.ZodString; upstream_event_ref: z.ZodOptional; upstream_event_digest: z.ZodOptional; }, z.core.$strict>; readonly 'task.failed': z.ZodObject<{ type: z.ZodLiteral; event: z.ZodLiteral<"task.failed">; task_id: z.ZodString; parent_task_id: z.ZodOptional; from_agent: z.ZodObject<{ card_ref: z.ZodString; selected_interface_url: z.ZodOptional; }, z.core.$strict>; to_agent: z.ZodOptional; selected_interface_url: z.ZodOptional; }, z.core.$strict>>; state: z.ZodOptional; reason: z.ZodOptional; observed_at: z.ZodString; upstream_event_ref: z.ZodOptional; upstream_event_digest: z.ZodOptional; }, z.core.$strict>; readonly 'human.review_requested': z.ZodObject<{ type: z.ZodLiteral; event: z.ZodLiteral<"human.review_requested">; task_id: z.ZodString; parent_task_id: z.ZodOptional; from_agent: z.ZodObject<{ card_ref: z.ZodString; selected_interface_url: z.ZodOptional; }, z.core.$strict>; to_agent: z.ZodOptional; selected_interface_url: z.ZodOptional; }, z.core.$strict>>; state: z.ZodOptional; reason: z.ZodOptional; observed_at: z.ZodString; upstream_event_ref: z.ZodOptional; upstream_event_digest: z.ZodOptional; }, z.core.$strict>; readonly 'human.approved': z.ZodObject<{ type: z.ZodLiteral; event: z.ZodLiteral<"human.approved">; task_id: z.ZodString; parent_task_id: z.ZodOptional; from_agent: z.ZodObject<{ card_ref: z.ZodString; selected_interface_url: z.ZodOptional; }, z.core.$strict>; to_agent: z.ZodOptional; selected_interface_url: z.ZodOptional; }, z.core.$strict>>; state: z.ZodOptional; reason: z.ZodOptional; observed_at: z.ZodString; upstream_event_ref: z.ZodOptional; upstream_event_digest: z.ZodOptional; }, z.core.$strict>; readonly 'human.rejected': z.ZodObject<{ type: z.ZodLiteral; event: z.ZodLiteral<"human.rejected">; task_id: z.ZodString; parent_task_id: z.ZodOptional; from_agent: z.ZodObject<{ card_ref: z.ZodString; selected_interface_url: z.ZodOptional; }, z.core.$strict>; to_agent: z.ZodOptional; selected_interface_url: z.ZodOptional; }, z.core.$strict>>; state: z.ZodOptional; reason: z.ZodOptional; observed_at: z.ZodString; upstream_event_ref: z.ZodOptional; upstream_event_digest: z.ZodOptional; }, z.core.$strict>; }; /** Aggregate task-observation schema (union over the 9 strict per-event variants). */ export declare const A2ATaskObservationSchema: z.ZodUnion; event: z.ZodLiteral<"task.submitted">; task_id: z.ZodString; parent_task_id: z.ZodOptional; from_agent: z.ZodObject<{ card_ref: z.ZodString; selected_interface_url: z.ZodOptional; }, z.core.$strict>; to_agent: z.ZodOptional; selected_interface_url: z.ZodOptional; }, z.core.$strict>>; state: z.ZodOptional; reason: z.ZodOptional; observed_at: z.ZodString; upstream_event_ref: z.ZodOptional; upstream_event_digest: z.ZodOptional; }, z.core.$strict>, z.ZodObject<{ type: z.ZodLiteral; event: z.ZodLiteral<"task.accepted">; task_id: z.ZodString; parent_task_id: z.ZodOptional; from_agent: z.ZodObject<{ card_ref: z.ZodString; selected_interface_url: z.ZodOptional; }, z.core.$strict>; to_agent: z.ZodOptional; selected_interface_url: z.ZodOptional; }, z.core.$strict>>; state: z.ZodOptional; reason: z.ZodOptional; observed_at: z.ZodString; upstream_event_ref: z.ZodOptional; upstream_event_digest: z.ZodOptional; }, z.core.$strict>, z.ZodObject<{ type: z.ZodLiteral; event: z.ZodLiteral<"task.rejected">; task_id: z.ZodString; parent_task_id: z.ZodOptional; from_agent: z.ZodObject<{ card_ref: z.ZodString; selected_interface_url: z.ZodOptional; }, z.core.$strict>; to_agent: z.ZodOptional; selected_interface_url: z.ZodOptional; }, z.core.$strict>>; state: z.ZodOptional; reason: z.ZodOptional; observed_at: z.ZodString; upstream_event_ref: z.ZodOptional; upstream_event_digest: z.ZodOptional; }, z.core.$strict>, z.ZodObject<{ type: z.ZodLiteral; event: z.ZodLiteral<"task.state_changed">; task_id: z.ZodString; parent_task_id: z.ZodOptional; from_agent: z.ZodObject<{ card_ref: z.ZodString; selected_interface_url: z.ZodOptional; }, z.core.$strict>; to_agent: z.ZodOptional; selected_interface_url: z.ZodOptional; }, z.core.$strict>>; state: z.ZodOptional; reason: z.ZodOptional; observed_at: z.ZodString; upstream_event_ref: z.ZodOptional; upstream_event_digest: z.ZodOptional; }, z.core.$strict>, z.ZodObject<{ type: z.ZodLiteral; event: z.ZodLiteral<"task.completed">; task_id: z.ZodString; parent_task_id: z.ZodOptional; from_agent: z.ZodObject<{ card_ref: z.ZodString; selected_interface_url: z.ZodOptional; }, z.core.$strict>; to_agent: z.ZodOptional; selected_interface_url: z.ZodOptional; }, z.core.$strict>>; state: z.ZodOptional; reason: z.ZodOptional; observed_at: z.ZodString; upstream_event_ref: z.ZodOptional; upstream_event_digest: z.ZodOptional; }, z.core.$strict>, z.ZodObject<{ type: z.ZodLiteral; event: z.ZodLiteral<"task.failed">; task_id: z.ZodString; parent_task_id: z.ZodOptional; from_agent: z.ZodObject<{ card_ref: z.ZodString; selected_interface_url: z.ZodOptional; }, z.core.$strict>; to_agent: z.ZodOptional; selected_interface_url: z.ZodOptional; }, z.core.$strict>>; state: z.ZodOptional; reason: z.ZodOptional; observed_at: z.ZodString; upstream_event_ref: z.ZodOptional; upstream_event_digest: z.ZodOptional; }, z.core.$strict>, z.ZodObject<{ type: z.ZodLiteral; event: z.ZodLiteral<"human.review_requested">; task_id: z.ZodString; parent_task_id: z.ZodOptional; from_agent: z.ZodObject<{ card_ref: z.ZodString; selected_interface_url: z.ZodOptional; }, z.core.$strict>; to_agent: z.ZodOptional; selected_interface_url: z.ZodOptional; }, z.core.$strict>>; state: z.ZodOptional; reason: z.ZodOptional; observed_at: z.ZodString; upstream_event_ref: z.ZodOptional; upstream_event_digest: z.ZodOptional; }, z.core.$strict>, z.ZodObject<{ type: z.ZodLiteral; event: z.ZodLiteral<"human.approved">; task_id: z.ZodString; parent_task_id: z.ZodOptional; from_agent: z.ZodObject<{ card_ref: z.ZodString; selected_interface_url: z.ZodOptional; }, z.core.$strict>; to_agent: z.ZodOptional; selected_interface_url: z.ZodOptional; }, z.core.$strict>>; state: z.ZodOptional; reason: z.ZodOptional; observed_at: z.ZodString; upstream_event_ref: z.ZodOptional; upstream_event_digest: z.ZodOptional; }, z.core.$strict>, z.ZodObject<{ type: z.ZodLiteral; event: z.ZodLiteral<"human.rejected">; task_id: z.ZodString; parent_task_id: z.ZodOptional; from_agent: z.ZodObject<{ card_ref: z.ZodString; selected_interface_url: z.ZodOptional; }, z.core.$strict>; to_agent: z.ZodOptional; selected_interface_url: z.ZodOptional; }, z.core.$strict>>; state: z.ZodOptional; reason: z.ZodOptional; observed_at: z.ZodString; upstream_event_ref: z.ZodOptional; upstream_event_digest: z.ZodOptional; }, z.core.$strict>]>; /** * A2A handoff extension payload: discriminated union over Agent Card vs the * 9 strict per-event task observations. */ export declare const A2AHandoffSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{ type: z.ZodLiteral<"org.peacprotocol/a2a-agent-card-observation">; card_ref: z.ZodString; selected_interface_url: z.ZodOptional; signature_observation: z.ZodObject<{ present: z.ZodBoolean; caller_reported_verification: z.ZodEnum<{ verified: "verified"; unverified: "unverified"; not_checked: "not_checked"; }>; method_ref: z.ZodOptional; kid: z.ZodOptional; observed_by_ref: z.ZodOptional; }, z.core.$strict>; discovered_at: z.ZodString; discovery_path: z.ZodEnum<{ "/.well-known/agent-card.json": "/.well-known/agent-card.json"; "/.well-known/peac.json": "/.well-known/peac.json"; "header-probe": "header-probe"; }>; }, z.core.$strict>, z.ZodObject<{ type: z.ZodLiteral; event: z.ZodLiteral<"task.submitted">; task_id: z.ZodString; parent_task_id: z.ZodOptional; from_agent: z.ZodObject<{ card_ref: z.ZodString; selected_interface_url: z.ZodOptional; }, z.core.$strict>; to_agent: z.ZodOptional; selected_interface_url: z.ZodOptional; }, z.core.$strict>>; state: z.ZodOptional; reason: z.ZodOptional; observed_at: z.ZodString; upstream_event_ref: z.ZodOptional; upstream_event_digest: z.ZodOptional; }, z.core.$strict>, z.ZodObject<{ type: z.ZodLiteral; event: z.ZodLiteral<"task.accepted">; task_id: z.ZodString; parent_task_id: z.ZodOptional; from_agent: z.ZodObject<{ card_ref: z.ZodString; selected_interface_url: z.ZodOptional; }, z.core.$strict>; to_agent: z.ZodOptional; selected_interface_url: z.ZodOptional; }, z.core.$strict>>; state: z.ZodOptional; reason: z.ZodOptional; observed_at: z.ZodString; upstream_event_ref: z.ZodOptional; upstream_event_digest: z.ZodOptional; }, z.core.$strict>, z.ZodObject<{ type: z.ZodLiteral; event: z.ZodLiteral<"task.rejected">; task_id: z.ZodString; parent_task_id: z.ZodOptional; from_agent: z.ZodObject<{ card_ref: z.ZodString; selected_interface_url: z.ZodOptional; }, z.core.$strict>; to_agent: z.ZodOptional; selected_interface_url: z.ZodOptional; }, z.core.$strict>>; state: z.ZodOptional; reason: z.ZodOptional; observed_at: z.ZodString; upstream_event_ref: z.ZodOptional; upstream_event_digest: z.ZodOptional; }, z.core.$strict>, z.ZodObject<{ type: z.ZodLiteral; event: z.ZodLiteral<"task.state_changed">; task_id: z.ZodString; parent_task_id: z.ZodOptional; from_agent: z.ZodObject<{ card_ref: z.ZodString; selected_interface_url: z.ZodOptional; }, z.core.$strict>; to_agent: z.ZodOptional; selected_interface_url: z.ZodOptional; }, z.core.$strict>>; state: z.ZodOptional; reason: z.ZodOptional; observed_at: z.ZodString; upstream_event_ref: z.ZodOptional; upstream_event_digest: z.ZodOptional; }, z.core.$strict>, z.ZodObject<{ type: z.ZodLiteral; event: z.ZodLiteral<"task.completed">; task_id: z.ZodString; parent_task_id: z.ZodOptional; from_agent: z.ZodObject<{ card_ref: z.ZodString; selected_interface_url: z.ZodOptional; }, z.core.$strict>; to_agent: z.ZodOptional; selected_interface_url: z.ZodOptional; }, z.core.$strict>>; state: z.ZodOptional; reason: z.ZodOptional; observed_at: z.ZodString; upstream_event_ref: z.ZodOptional; upstream_event_digest: z.ZodOptional; }, z.core.$strict>, z.ZodObject<{ type: z.ZodLiteral; event: z.ZodLiteral<"task.failed">; task_id: z.ZodString; parent_task_id: z.ZodOptional; from_agent: z.ZodObject<{ card_ref: z.ZodString; selected_interface_url: z.ZodOptional; }, z.core.$strict>; to_agent: z.ZodOptional; selected_interface_url: z.ZodOptional; }, z.core.$strict>>; state: z.ZodOptional; reason: z.ZodOptional; observed_at: z.ZodString; upstream_event_ref: z.ZodOptional; upstream_event_digest: z.ZodOptional; }, z.core.$strict>, z.ZodObject<{ type: z.ZodLiteral; event: z.ZodLiteral<"human.review_requested">; task_id: z.ZodString; parent_task_id: z.ZodOptional; from_agent: z.ZodObject<{ card_ref: z.ZodString; selected_interface_url: z.ZodOptional; }, z.core.$strict>; to_agent: z.ZodOptional; selected_interface_url: z.ZodOptional; }, z.core.$strict>>; state: z.ZodOptional; reason: z.ZodOptional; observed_at: z.ZodString; upstream_event_ref: z.ZodOptional; upstream_event_digest: z.ZodOptional; }, z.core.$strict>, z.ZodObject<{ type: z.ZodLiteral; event: z.ZodLiteral<"human.approved">; task_id: z.ZodString; parent_task_id: z.ZodOptional; from_agent: z.ZodObject<{ card_ref: z.ZodString; selected_interface_url: z.ZodOptional; }, z.core.$strict>; to_agent: z.ZodOptional; selected_interface_url: z.ZodOptional; }, z.core.$strict>>; state: z.ZodOptional; reason: z.ZodOptional; observed_at: z.ZodString; upstream_event_ref: z.ZodOptional; upstream_event_digest: z.ZodOptional; }, z.core.$strict>, z.ZodObject<{ type: z.ZodLiteral; event: z.ZodLiteral<"human.rejected">; task_id: z.ZodString; parent_task_id: z.ZodOptional; from_agent: z.ZodObject<{ card_ref: z.ZodString; selected_interface_url: z.ZodOptional; }, z.core.$strict>; to_agent: z.ZodOptional; selected_interface_url: z.ZodOptional; }, z.core.$strict>>; state: z.ZodOptional; reason: z.ZodOptional; observed_at: z.ZodString; upstream_event_ref: z.ZodOptional; upstream_event_digest: z.ZodOptional; }, z.core.$strict>], "type">; export type A2AAgentCardObservation = z.infer; export type A2ATaskObservation = z.infer; export type A2AHandoffPayload = z.infer; export interface A2AValidationError { code: string; path?: string; message?: string; } export type A2AValidationResult = { ok: true; value: A2AHandoffPayload; } | { ok: false; errors: A2AValidationError[]; }; /** * Validate an A2A handoff payload (Agent Card observation or task observation). * * Returns a structured result with stable error codes for downstream * conformance vector assertions. The mapping prioritizes the most specific * applicable code when multiple issues are present in the same payload. */ export declare function validateA2AHandoff(data: unknown): A2AValidationResult; //# sourceMappingURL=a2a-handoff.d.ts.map