@groundnuty/macf-channel-server 0.2.27 → 0.2.32

package/dist/a2a-types.js

@@ -0,0 +1,286 @@
+/**
+ * A2A v1.0 protocol types for inbound JSON-RPC `message/send` handling.
+ *
+ * Hand-rolled Zod schemas per A2A v1.0 spec sections:
+ * - § 4.1.1 Task
+ * - § 4.1.2 TaskStatus
+ * - § 4.1.3 TaskState (8-state enum, SCREAMING_SNAKE_CASE)
+ * - § 4.1.4 Message
+ * - § 4.1.5 Part (OneOf semantics: text | file | data; v1.0 dropped the `kind` discriminator per Appendix A.2.1)
+ * - § 9 JSON-RPC Protocol Binding (method `"message/send"`)
+ *
+ * **SDK choice**: continuing hand-rolled (per Phase 1 #370 + #385 decision).
+ * `@a2a-js/sdk` is still v0.3.13 (A2A v0.3 target); v1.0 not released.
+ * Re-evaluate at Phase 3 (outbound A2A) when the bidirectional surface
+ * pushes the build-vs-buy delta further.
+ *
+ * **Verified against spec text**: 2026-05-19 via a2a-protocol.org WebFetch.
+ * Section references in JSDoc above each schema preserve the citation
+ * trail for future re-verification.
+ *
+ * **macf#390 Phase 2a scope**: full 8-state TaskState enum + Message
+ * schema + Part text-variant; happy-path SUBMITTED → WORKING → COMPLETED.
+ * INPUT_REQUIRED / AUTH_REQUIRED transitions + file/data Part variants
+ * declared in types but exercised in Phase 2b.
+ */
+import { z } from 'zod';
+// ---------------------------------------------------------------------------
+// TaskState — § 4.1.3 (SCREAMING_SNAKE_CASE per v1.0 enum convention)
+// ---------------------------------------------------------------------------
+export const TaskStateSchema = z.enum([
+    'TASK_STATE_SUBMITTED',
+    'TASK_STATE_WORKING',
+    'TASK_STATE_INPUT_REQUIRED',
+    'TASK_STATE_AUTH_REQUIRED',
+    'TASK_STATE_COMPLETED',
+    'TASK_STATE_FAILED',
+    'TASK_STATE_CANCELED',
+    'TASK_STATE_REJECTED',
+]);
+/** Terminal states — no further transitions allowed once entered. */
+export const TERMINAL_TASK_STATES = new Set([
+    'TASK_STATE_COMPLETED',
+    'TASK_STATE_FAILED',
+    'TASK_STATE_CANCELED',
+    'TASK_STATE_REJECTED',
+]);
+/** Interrupted states — task pauses awaiting client follow-up via `Message.taskId`. */
+export const INTERRUPTED_TASK_STATES = new Set([
+    'TASK_STATE_INPUT_REQUIRED',
+    'TASK_STATE_AUTH_REQUIRED',
+]);
+// ---------------------------------------------------------------------------
+// Role — § 4.1.4 (SCREAMING_SNAKE_CASE per v1.0)
+// ---------------------------------------------------------------------------
+export const RoleSchema = z.enum(['ROLE_USER', 'ROLE_AGENT']);
+// ---------------------------------------------------------------------------
+// Part — § 4.1.5 + canonical proto (spec/a2a.proto)
+// ---------------------------------------------------------------------------
+//
+// Per the canonical proto (single authoritative source per spec § 1.4 —
+// "spec/a2a.proto is the single authoritative normative definition"):
+//
+//   message Part {
+//     oneof content {
+//       string text = 1;
+//       bytes raw = 2;
+//       string url = 3;
+//       google.protobuf.Value data = 4;
+//     }
+//     google.protobuf.Struct metadata = 5;
+//     string filename = 6;
+//     string media_type = 7;
+//   }
+//
+// Four `oneof content` variants (text / raw / url / data) — exactly one
+// present. Optional top-level `metadata` + `filename` + `mediaType`
+// (NOT inside a nested FilePart wrapper; v1.0 flattened the v0.3 shape).
+//
+// JSON wire-form names per protobuf-to-JSON canonical mapping:
+// - `media_type` (proto snake_case) → `mediaType` (JSON camelCase)
+// - `filename` → `filename` (single word, no transform)
+// - `raw` is `bytes` in the proto → base64-encoded string on JSON wire
+// - `data` is `google.protobuf.Value` → arbitrary JSON value
+//
+// Encoded as `z.union` of 4 separate variants (matching the proto's
+// oneof discipline) rather than a single object with refine — clearer
+// type discrimination for downstream consumers.
+//
+// Phase 2a only exercises the text variant; declaring the full proto
+// shape so Phase 2b / Phase 3 don't need to refactor.
+/** Shared optional fields present on all Part variants per proto §§ 5–7. */
+const PartCommonFields = {
+    metadata: z.record(z.string(), z.unknown()).optional(),
+    filename: z.string().optional(),
+    mediaType: z.string().optional(),
+};
+const TextPartSchema = z.object({
+    text: z.string(),
+    ...PartCommonFields,
+});
+const RawPartSchema = z.object({
+    raw: z.string(), // base64-encoded bytes per proto3 JSON mapping
+    ...PartCommonFields,
+});
+const UrlPartSchema = z.object({
+    url: z.string(),
+    ...PartCommonFields,
+});
+// `data: z.unknown()` would accept undefined (Zod treats z.unknown as
+// also-undefined), making empty objects pass DataPartSchema spuriously.
+// The refine pins the key-presence requirement so the union correctly
+// rejects `{}` + `{ filename: '...' }`-only inputs.
+const DataPartSchema = z
+    .object({
+    data: z.unknown(),
+    ...PartCommonFields,
+})
+    .refine((obj) => Object.prototype.hasOwnProperty.call(obj, 'data'), {
+    message: 'Part: `data` property must be present (oneof discriminator)',
+});
+export const PartSchema = z.union([
+    TextPartSchema,
+    RawPartSchema,
+    UrlPartSchema,
+    DataPartSchema,
+]);
+// ---------------------------------------------------------------------------
+// Message — § 4.1.4
+// ---------------------------------------------------------------------------
+export const MessageSchema = z.object({
+    messageId: z.string().min(1),
+    role: RoleSchema,
+    parts: z.array(PartSchema).min(1),
+    contextId: z.string().optional(),
+    /**
+     * `taskId` — canonical A2A v1.0 resume reference. When set, the receiver
+     * dispatches to the existing task (used for INPUT_REQUIRED / AUTH_REQUIRED
+     * resume flows in Phase 2b). Phase 2a creates fresh tasks; the field
+     * lands in the schema but isn't exercised yet.
+     */
+    taskId: z.string().optional(),
+    metadata: z.record(z.string(), z.unknown()).optional(),
+    extensions: z.array(z.string()).optional(),
+    referenceTaskIds: z.array(z.string()).optional(),
+});
+// ---------------------------------------------------------------------------
+// TaskStatus — § 4.1.2
+// ---------------------------------------------------------------------------
+export const TaskStatusSchema = z.object({
+    state: TaskStateSchema,
+    /** Optional human-readable message accompanying the state. */
+    message: MessageSchema.optional(),
+    /** RFC 3339 / ISO 8601 timestamp of the last state change. */
+    timestamp: z.string().optional(),
+});
+// ---------------------------------------------------------------------------
+// Task — § 4.1.1
+// ---------------------------------------------------------------------------
+export const TaskSchema = z.object({
+    id: z.string().min(1),
+    status: TaskStatusSchema,
+    contextId: z.string().optional(),
+    /** History of all messages exchanged on this task. */
+    history: z.array(MessageSchema).optional(),
+    /** Artifacts produced by the agent (responses, files, etc.). */
+    artifacts: z.array(z.unknown()).optional(),
+    metadata: z.record(z.string(), z.unknown()).optional(),
+});
+// ---------------------------------------------------------------------------
+// JSON-RPC 2.0 envelope — § 9 (`method: "message/send"`)
+// ---------------------------------------------------------------------------
+/** JSON-RPC 2.0 request envelope. `id` is required for `message/send` (not a notification). */
+export const JsonRpcRequestSchema = z.object({
+    jsonrpc: z.literal('2.0'),
+    method: z.string().min(1),
+    id: z.union([z.string(), z.number()]),
+    params: z.unknown().optional(),
+});
+/** Params for `message/send` — wraps a Message. */
+export const MessageSendParamsSchema = z.object({
+    message: MessageSchema,
+    /** Optional `configuration` / `metadata` keys per spec § 9.4.1 (not exercised in Phase 2a). */
+    configuration: z.record(z.string(), z.unknown()).optional(),
+    metadata: z.record(z.string(), z.unknown()).optional(),
+});
+// ---------------------------------------------------------------------------
+// tasks/get + tasks/cancel params — § 9 + canonical proto (macf#398 Phase 2d)
+// ---------------------------------------------------------------------------
+//
+// Per canonical proto (a2a.proto):
+//   message GetTaskRequest    { string name = 1; ... }
+//   message CancelTaskRequest { string name = 1; ... }
+//
+// `name` is the resource path "tasks/{id}". The JSON-RPC binding in
+// practice accepts EITHER the bare `id` form (canonical in most A2A
+// client SDKs surveyed) OR the proto-canonical `name` form. We accept
+// both by branching on which key is present; the route handler reduces
+// to the bare taskId for TaskStore lookup.
+//
+// Why accept both: the Python a2a-sdk v1.0.3 client surface emits
+// `params: { id }` for tasks/get; the protobuf-canonical wire form
+// emits `params: { name: "tasks/{id}" }`. Rejecting either would break
+// a real client.
+/** Params for `tasks/get` + `tasks/cancel`. Accepts `{ id }` or proto-canonical `{ name: "tasks/{id}" }`. */
+export const TaskIdParamsSchema = z
+    .object({
+    id: z.string().min(1).optional(),
+    name: z.string().min(1).optional(),
+    metadata: z.record(z.string(), z.unknown()).optional(),
+})
+    .refine((obj) => (obj.id !== undefined) || (obj.name !== undefined), { message: 'Params: one of `id` or `name` must be present' });
+/**
+ * Resolve a TaskIdParams to the bare task id. `id` takes precedence
+ * over `name`; if only `name` is present, strip the `tasks/` resource
+ * prefix per the proto canonical mapping. Returns `undefined` if
+ * neither was present (the refine should have rejected, but defensive).
+ */
+export function resolveTaskId(params) {
+    if (params.id !== undefined && params.id.length > 0)
+        return params.id;
+    if (params.name !== undefined && params.name.length > 0) {
+        return params.name.startsWith('tasks/') ? params.name.slice('tasks/'.length) : params.name;
+    }
+    return undefined;
+}
+/**
+ * JSON-RPC 2.0 success response envelope. `result` for `message/send`
+ * is either a Task or a Message per spec § 9.4.1 — Phase 2a always
+ * returns a Task (synchronous happy-path COMPLETED).
+ */
+export const JsonRpcSuccessResponseSchema = z.object({
+    jsonrpc: z.literal('2.0'),
+    id: z.union([z.string(), z.number(), z.null()]),
+    result: TaskSchema,
+});
+/**
+ * JSON-RPC 2.0 error envelope. Per A2A v1.0 spec § 9 (and v1.0 change
+ * notes), errors use the `google.rpc.Status` representation with
+ * `ErrorInfo` extensions: `reason` in UPPER_SNAKE_CASE + domain
+ * `"a2a-protocol.org"`.
+ *
+ * Standard JSON-RPC `code`/`message` + `data.reason`/`data.domain` for
+ * the A2A-specific reason classification.
+ */
+export const JsonRpcErrorResponseSchema = z.object({
+    jsonrpc: z.literal('2.0'),
+    id: z.union([z.string(), z.number(), z.null()]),
+    error: z.object({
+        code: z.number(),
+        message: z.string(),
+        data: z
+            .object({
+            reason: z.string().optional(),
+            domain: z.string().optional(),
+        })
+            .passthrough()
+            .optional(),
+    }),
+});
+// ---------------------------------------------------------------------------
+// JSON-RPC error code constants (spec § 9 + JSON-RPC 2.0 §5.1)
+// ---------------------------------------------------------------------------
+/** JSON-RPC 2.0 standard error codes. */
+export const JSONRPC_PARSE_ERROR = -32700;
+export const JSONRPC_INVALID_REQUEST = -32600;
+export const JSONRPC_METHOD_NOT_FOUND = -32601;
+export const JSONRPC_INVALID_PARAMS = -32602;
+export const JSONRPC_INTERNAL_ERROR = -32603;
+/** A2A-specific reason codes (UPPER_SNAKE_CASE per v1.0 § 9 ErrorInfo). */
+export const A2A_ERROR_DOMAIN = 'a2a-protocol.org';
+export const A2A_REASON_INVALID_MESSAGE = 'INVALID_MESSAGE';
+export const A2A_REASON_TASK_NOT_FOUND = 'TASK_NOT_FOUND';
+export const A2A_REASON_METHOD_NOT_SUPPORTED = 'METHOD_NOT_SUPPORTED';
+/** Resume attempted against a terminal task (COMPLETED/FAILED/CANCELED/REJECTED) — macf#392 Phase 2b. */
+export const A2A_REASON_TASK_TERMINAL_STATE = 'TASK_TERMINAL_STATE';
+/** Resume attempted with non-resumable from-state (only INPUT_REQUIRED + AUTH_REQUIRED accept resume) — macf#392 Phase 2b. */
+export const A2A_REASON_TASK_NOT_RESUMABLE = 'TASK_NOT_RESUMABLE';
+/** Canonical JSON-RPC method string for the inbound message exchange (spec § 9 examples). */
+export const A2A_METHOD_MESSAGE_SEND = 'message/send';
+/** Canonical JSON-RPC method string for task lookup (macf#398 Phase 2d). */
+export const A2A_METHOD_TASKS_GET = 'tasks/get';
+/** Canonical JSON-RPC method string for task cancellation (macf#398 Phase 2d). */
+export const A2A_METHOD_TASKS_CANCEL = 'tasks/cancel';
+/** Canonical AgentCard.url path for this server's A2A endpoint. */
+export const A2A_ENDPOINT_PATH = '/a2a/v1';
+//# sourceMappingURL=a2a-types.js.map

package/dist/a2a-types.js.map

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

package/dist/agent-card.d.ts

@@ -35,21 +35,48 @@
  */
 import { z } from 'zod';
 /**
- * AgentSkill — per spec § 4.4.5. Required: id, name. Optional:
- * description, tags, examples, inputModes, outputModes, metadata,
- * extensions.
+ * AgentSkill — per canonical proto (`a2aproject/A2A:specification/a2a.proto`
+ * `message AgentSkill`). Required per proto: id, name, description, tags.
+ * Optional: examples, input_modes, output_modes, security_requirements.
+ *
+ * JSON wire form uses canonical lowerCamelCase mapping from proto
+ * snake_case (`input_modes` → `inputModes`, etc.) per proto3 JSON spec.
+ *
+ * **macf#393 Phase 2c**: `description` + `tags` upgraded from optional
+ * (Phase 1's lenient shape) to required per proto. Strict-validating
+ * external A2A clients (Bedrock AgentCore, Microsoft Agent Framework,
+ * etc.) reject AgentCards with skill entries missing required fields.
  */
 export declare const AgentSkillSchema: z.ZodObject<{
     id: z.ZodString;
     name: z.ZodString;
-    description: z.ZodOptional<z.ZodString>;
-    tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    description: z.ZodString;
+    tags: z.ZodArray<z.ZodString>;
     examples: z.ZodOptional<z.ZodArray<z.ZodString>>;
     inputModes: z.ZodOptional<z.ZodArray<z.ZodString>>;
     outputModes: z.ZodOptional<z.ZodArray<z.ZodString>>;
     metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
 }, z.core.$strip>;
 export type AgentSkill = z.infer<typeof AgentSkillSchema>;
+/**
+ * AgentInterface — per canonical proto `message AgentInterface`.
+ * Per AgentCard `supported_interfaces` (proto field 3, REQUIRED): the
+ * endpoint URL + protocol binding the agent serves. v1.0 moves the
+ * endpoint URL OUT of AgentCard top-level into the (repeated)
+ * AgentInterface entries.
+ *
+ * Required per proto: url, protocol_binding, protocol_version.
+ * Optional: tenant.
+ *
+ * JSON wire form: `protocolBinding` (lowerCamelCase) + `protocolVersion`.
+ */
+export declare const AgentInterfaceSchema: z.ZodObject<{
+    url: z.ZodString;
+    protocolBinding: z.ZodString;
+    tenant: z.ZodOptional<z.ZodString>;
+    protocolVersion: z.ZodString;
+}, z.core.$strip>;
+export type AgentInterface = z.infer<typeof AgentInterfaceSchema>;
 /**
  * MutualTlsSecurityScheme — per spec § 4.5.6. Type discriminator
  * `mutualTls`. No additional fields required at the scheme level;
@@ -84,42 +111,67 @@ export declare const AgentCapabilitiesSchema: z.ZodObject<{
 }, z.core.$catchall<z.ZodUnknown>>;
 export type AgentCapabilities = z.infer<typeof AgentCapabilitiesSchema>;
 /**
- * AgentCard — per spec § 4.4.1. Required: id, name, url, version,
- * provider, capabilities, securitySchemes. Optional: description,
- * defaultInputModes, defaultOutputModes, skills, extensions, security,
- * metadata.
+ * AgentCard — per canonical proto `message AgentCard` (verified verbatim
+ * from `a2aproject/A2A:specification/a2a.proto` 2026-05-19).
+ *
+ * Required per proto: name, description, supported_interfaces,
+ * version, capabilities, default_input_modes, default_output_modes, skills.
+ * Optional: provider, documentation_url, security_schemes,
+ * security_requirements, signatures, icon_url.
+ *
+ * JSON wire form uses canonical lowerCamelCase mapping from proto
+ * snake_case (`supported_interfaces` → `supportedInterfaces`, etc.).
+ *
+ * **macf#393 Phase 2c** — schema realignment to canonical proto:
+ * - REMOVED top-level `id` (no such field in proto)
+ * - REMOVED top-level `url` (moves to `supportedInterfaces[0].url`)
+ * - ADDED `description` as required (was optional in Phase 1)
+ * - ADDED `supportedInterfaces` as required (endpoint URL lives here per v1.0)
+ * - ADDED `defaultInputModes` + `defaultOutputModes` as required
+ * - `skills` upgraded from optional to required (proto says REQUIRED)
+ *
+ * The schema change is structurally breaking for any consumer that parsed
+ * Phase 1's AgentCard shape; pre-flight grep on 2026-05-19 confirmed zero
+ * external consumers (Phase 1 shipped ~24h prior). Migration documented
+ * in DR-022 Amendment M.
  */
 export declare const AgentCardSchema: z.ZodObject<{
-    id: z.ZodString;
     name: z.ZodString;
-    url: z.ZodString;
+    description: z.ZodString;
+    supportedInterfaces: z.ZodArray<z.ZodObject<{
+        url: z.ZodString;
+        protocolBinding: z.ZodString;
+        tenant: z.ZodOptional<z.ZodString>;
+        protocolVersion: z.ZodString;
+    }, z.core.$strip>>;
     version: z.ZodString;
-    provider: z.ZodObject<{
+    provider: z.ZodOptional<z.ZodObject<{
         organization: z.ZodString;
         url: z.ZodOptional<z.ZodString>;
-    }, z.core.$strip>;
+    }, z.core.$strip>>;
     capabilities: z.ZodObject<{
         streaming: z.ZodOptional<z.ZodBoolean>;
         pushNotifications: z.ZodOptional<z.ZodBoolean>;
     }, z.core.$catchall<z.ZodUnknown>>;
-    securitySchemes: z.ZodRecord<z.ZodString, z.ZodObject<{
+    securitySchemes: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
         type: z.ZodLiteral<"mutualTls">;
         description: z.ZodOptional<z.ZodString>;
-    }, z.core.$strip>>;
-    description: z.ZodOptional<z.ZodString>;
-    defaultInputModes: z.ZodOptional<z.ZodArray<z.ZodString>>;
-    defaultOutputModes: z.ZodOptional<z.ZodArray<z.ZodString>>;
-    skills: z.ZodOptional<z.ZodArray<z.ZodObject<{
+    }, z.core.$strip>>>;
+    defaultInputModes: z.ZodArray<z.ZodString>;
+    defaultOutputModes: z.ZodArray<z.ZodString>;
+    skills: z.ZodArray<z.ZodObject<{
         id: z.ZodString;
         name: z.ZodString;
-        description: z.ZodOptional<z.ZodString>;
-        tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        description: z.ZodString;
+        tags: z.ZodArray<z.ZodString>;
         examples: z.ZodOptional<z.ZodArray<z.ZodString>>;
         inputModes: z.ZodOptional<z.ZodArray<z.ZodString>>;
         outputModes: z.ZodOptional<z.ZodArray<z.ZodString>>;
         metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
-    }, z.core.$strip>>>;
+    }, z.core.$strip>>;
     security: z.ZodOptional<z.ZodArray<z.ZodRecord<z.ZodString, z.ZodArray<z.ZodString>>>>;
+    documentationUrl: z.ZodOptional<z.ZodString>;
+    iconUrl: z.ZodOptional<z.ZodString>;
     metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
 }, z.core.$strip>;
 export type AgentCard = z.infer<typeof AgentCardSchema>;
@@ -149,10 +201,25 @@ export interface AgentCardInputs {
  * clients SHOULD NOT depend on it. A source-level test in
  * `test/agent-card.test.ts` pins this invariant.
  *
- * Skills in Phase 1: empty array. The MACF coordination surfaces
- * (POST /notify for inbound peer notifications) are framework-internal,
- * not user-invocable agent skills in the A2A sense. Phase 2+ may add
- * skills as A2A's task lifecycle surfaces materialize.
+ * Skills in Phase 2a (macf#390): MACF domain capabilities — what the
+ * agent can DO, not what JSON-RPC methods it serves. Per spec § 4.4.5,
+ * skills describe agent-specific actions on top of the A2A protocol
+ * methods. Initial mapping (Phase 2a):
+ *
+ * - `macf.notify_peer` — Cross-Agent Notification (the canonical MACF
+ *   coordination primitive; #267)
+ * - `macf.checkpoint_to_memory` — Persist Context to Memory (the PreCompact
+ *   checkpoint MCP tool; #271 DR-023 §UC-3)
+ *
+ * Phase 3+ will add role-specific skills if the MACF MCP-tool surface
+ * grows. `/macf/sign` is intentionally absent — live cryptographic
+ * attestation stays MACF-only per DR-010 Path 2 + #371; a source-level
+ * test pins this invariant.
+ *
+ * `url` field: Phase 2a points AgentCard.url to the JSON-RPC endpoint
+ * (`<inputs.url>/a2a/v1`). A2A clients discover via
+ * `/.well-known/agent-card.json` then POST `message/send` to the
+ * advertised url.
  */
 export declare function buildAgentCard(inputs: AgentCardInputs): AgentCard;
 //# sourceMappingURL=agent-card.d.ts.map

package/dist/agent-card.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"agent-card.d.ts","sourceRoot":"","sources":["../src/agent-card.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAMxB;;;;GAIG;AACH,eAAO,MAAM,gBAAgB;;;;;;;;;iBAS3B,CAAC;AAEH,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAE1D;;;;;GAKG;AACH,eAAO,MAAM,6BAA6B;;;iBAGxC,CAAC;AAEH,MAAM,MAAM,uBAAuB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,6BAA6B,CAAC,CAAC;AAEpF;;;GAGG;AACH,eAAO,MAAM,mBAAmB;;;iBAG9B,CAAC;AAEH,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAEhE;;;;;;;GAOG;AACH,eAAO,MAAM,uBAAuB;;;kCAGZ,CAAC;AAEzB,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,uBAAuB,CAAC,CAAC;AAExE;;;;;GAKG;AACH,eAAO,MAAM,eAAe;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAmB1B,CAAC;AAEH,MAAM,MAAM,SAAS,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,CAAC;AAMxD;;;;;GAKG;AACH,MAAM,WAAW,eAAe;IAC9B,uFAAuF;IACvF,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,iEAAiE;IACjE,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,6EAA6E;IAC7E,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,+DAA+D;IAC/D,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,uFAAuF;IACvF,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,eAAe,GAAG,SAAS,CA8BjE"}
+{"version":3,"file":"agent-card.d.ts","sourceRoot":"","sources":["../src/agent-card.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAOxB;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,gBAAgB;;;;;;;;;iBAS3B,CAAC;AAEH,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAE1D;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,oBAAoB;;;;;iBAQ/B,CAAC;AAEH,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC;AAElE;;;;;GAKG;AACH,eAAO,MAAM,6BAA6B;;;iBAGxC,CAAC;AAEH,MAAM,MAAM,uBAAuB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,6BAA6B,CAAC,CAAC;AAEpF;;;GAGG;AACH,eAAO,MAAM,mBAAmB;;;iBAG9B,CAAC;AAEH,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAEhE;;;;;;;GAOG;AACH,eAAO,MAAM,uBAAuB;;;kCAGZ,CAAC;AAEzB,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,uBAAuB,CAAC,CAAC;AAExE;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,eAAO,MAAM,eAAe;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAoB1B,CAAC;AAEH,MAAM,MAAM,SAAS,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,CAAC;AAMxD;;;;;GAKG;AACH,MAAM,WAAW,eAAe;IAC9B,uFAAuF;IACvF,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,iEAAiE;IACjE,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,6EAA6E;IAC7E,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,+DAA+D;IAC/D,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,uFAAuF;IACvF,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,eAAe,GAAG,SAAS,CA0DjE"}