dsh-a2a-server 0.1.0

package/lib/projection.js

@@ -0,0 +1,98 @@
+/**
+ * The `a2aTask` projection unit: task state read back from the session log.
+ *
+ * Without this, task state lives only in the process-local slot table, and
+ * `settleSlot` removes a slot the moment it settles — so a peer that polls
+ * `tasks/get` is told the task never existed, moments after it completed. That
+ * breaks the polling path A2A treats as the baseline update mechanism
+ * (`message/stream` and push notifications are both optional capabilities;
+ * `tasks/get` is not).
+ *
+ * The unit is a pure left fold over the `a2a/task` edges the server already
+ * appends. It holds no subscriptions: the registry drives every committed event
+ * through `apply` once, and the persisted projection cache turns a cold read
+ * into a cache row plus a tail replay rather than a full log load.
+ *
+ * @module dsh-a2a/projection
+ */
+import { z } from 'zod';
+const STATES = [
+    'submitted', 'working', 'input-required', 'auth-required',
+    'completed', 'canceled', 'failed', 'rejected',
+];
+/** Validates the wire payload before it leaves the host. */
+export const A2A_TASK_VIEW_SCHEMA = z.object({
+    tasks: z.record(z.string(), z.object({
+        taskId: z.string(),
+        peer: z.string(),
+        state: z.enum(STATES),
+        output: z.string().optional(),
+        stopReason: z.string().optional(),
+        updatedAt: z.string(),
+    })),
+});
+/**
+ * The projection definition, in the shape `ctx.sessionProjections.register()` wants.
+ *
+ * Declared as a plain object rather than built inside `apply()` so the fold can
+ * be unit-tested without a Cordis context or a session.
+ */
+export const a2aTaskProjection = {
+    key: 'a2aTask',
+    schema: A2A_TASK_VIEW_SCHEMA,
+    stateVersion: 1,
+    /**
+     * State for the empty log.
+     * @returns the initial state.
+     */
+    init() {
+        return { tasks: {} };
+    },
+    /**
+     * Fold one committed event.
+     *
+     * Returns the SAME reference for every event that is not an `a2a/task` edge:
+     * the drive gates its change feed on `Object.is`, so a fresh object here would
+     * wake every downstream consumer on every unrelated event in the session.
+     * @param state - the state covering all prior events.
+     * @param event - the next committed session event.
+     * @returns the next state, or `state` unchanged.
+     */
+    apply(state, event) {
+        if (event.type !== 'a2a/task')
+            return state;
+        const data = event.data;
+        if (typeof data?.taskId !== 'string' || typeof data.state !== 'string')
+            return state;
+        const previous = state.tasks[data.taskId];
+        // Terminal states are final: a late edge must not reopen a settled task.
+        if (previous !== undefined && TERMINAL.has(previous.state))
+            return state;
+        return {
+            tasks: {
+                ...state.tasks,
+                [data.taskId]: {
+                    taskId: data.taskId,
+                    peer: data.peer,
+                    state: data.state,
+                    ...data.output === undefined ? {} : { output: data.output },
+                    ...data.stopReason === undefined ? {} : { stopReason: data.stopReason },
+                    // The log has no wall-clock of its own, so the fold stamps when it
+                    // observed the edge. A replay therefore restamps; consumers use this
+                    // for `Task.status.timestamp`, which A2A treats as advisory.
+                    updatedAt: new Date().toISOString(),
+                },
+            },
+        };
+    },
+    /**
+     * State → wire payload.
+     * @param state - the current state.
+     * @returns the whole current value.
+     */
+    view(state) {
+        return { tasks: state.tasks };
+    },
+};
+const TERMINAL = new Set(['completed', 'canceled', 'failed', 'rejected']);
+//# sourceMappingURL=projection.js.map

package/lib/projection.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"projection.js","sourceRoot":"","sources":["../src/projection.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AA0CvB,MAAM,MAAM,GAAG;IACb,WAAW,EAAE,SAAS,EAAE,gBAAgB,EAAE,eAAe;IACzD,WAAW,EAAE,UAAU,EAAE,QAAQ,EAAE,UAAU;CACrC,CAAA;AAEV,4DAA4D;AAC5D,MAAM,CAAC,MAAM,oBAAoB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC3C,KAAK,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,MAAM,CAAC;QACnC,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE;QAClB,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE;QAChB,KAAK,EAAE,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC;QACrB,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;QAC7B,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;QACjC,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE;KACtB,CAAC,CAAC;CACJ,CAAC,CAAA;AAiBF;;;;;GAKG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG;IAC/B,GAAG,EAAE,SAAkB;IACvB,MAAM,EAAE,oBAAoB;IAC5B,YAAY,EAAE,CAAC;IAEf;;;OAGG;IACH,IAAI;QACF,OAAO,EAAE,KAAK,EAAE,EAAE,EAAE,CAAA;IACtB,CAAC;IAED;;;;;;;;;OASG;IACH,KAAK,CAAC,KAAoB,EAAE,KAAmB;QAC7C,IAAI,KAAK,CAAC,IAAI,KAAK,UAAU;YAAE,OAAO,KAAK,CAAA;QAC3C,MAAM,IAAI,GAAG,KAAK,CAAC,IAA2B,CAAA;QAC9C,IAAI,OAAO,IAAI,EAAE,MAAM,KAAK,QAAQ,IAAI,OAAO,IAAI,CAAC,KAAK,KAAK,QAAQ;YAAE,OAAO,KAAK,CAAA;QAEpF,MAAM,QAAQ,GAAG,KAAK,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,CAAA;QACzC,yEAAyE;QACzE,IAAI,QAAQ,KAAK,SAAS,IAAI,QAAQ,CAAC,GAAG,CAAC,QAAQ,CAAC,KAAK,CAAC;YAAE,OAAO,KAAK,CAAA;QAExE,OAAO;YACL,KAAK,EAAE;gBACL,GAAG,KAAK,CAAC,KAAK;gBACd,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE;oBACb,MAAM,EAAE,IAAI,CAAC,MAAM;oBACnB,IAAI,EAAE,IAAI,CAAC,IAAI;oBACf,KAAK,EAAE,IAAI,CAAC,KAAK;oBACjB,GAAG,IAAI,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE;oBAC3D,GAAG,IAAI,CAAC,UAAU,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,UAAU,EAAE,IAAI,CAAC,UAAU,EAAE;oBACvE,mEAAmE;oBACnE,qEAAqE;oBACrE,6DAA6D;oBAC7D,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;iBACpC;aACF;SACF,CAAA;IACH,CAAC;IAED;;;;OAIG;IACH,IAAI,CAAC,KAAoB;QACvB,OAAO,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,EAAE,CAAA;IAC/B,CAAC;CACF,CAAA;AAED,MAAM,QAAQ,GAAG,IAAI,GAAG,CAAe,CAAC,WAAW,EAAE,UAAU,EAAE,QAAQ,EAAE,UAAU,CAAC,CAAC,CAAA"}

package/lib/protocol/brand.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Branded identifiers for the A2A wire vocabulary.
+ *
+ * Branding keeps a raw string from being used where a checked id is required —
+ * the same discipline `dsh-session` applies to `SessionId`.
+ *
+ * @module dsh-a2a/protocol/brand
+ */
+declare const contextIdBrand: unique symbol;
+declare const taskIdBrand: unique symbol;
+/** An A2A `contextId`. This server mints it verbatim from a `SessionId`. */
+export type A2AContextId = string & {
+    readonly [contextIdBrand]: true;
+};
+/** An A2A `Task.id`, minted per accepted message. */
+export type A2ATaskId = string & {
+    readonly [taskIdBrand]: true;
+};
+/**
+ * Brand a raw string as a context id.
+ * @param value - the raw identifier.
+ * @returns the same string, branded.
+ */
+export declare function A2AContextId(value: string): A2AContextId;
+/**
+ * Brand a raw string as a task id.
+ * @param value - the raw identifier.
+ * @returns the same string, branded.
+ */
+export declare function A2ATaskId(value: string): A2ATaskId;
+export {};
+//# sourceMappingURL=brand.d.ts.map

package/lib/protocol/brand.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"brand.d.ts","sourceRoot":"","sources":["../../src/protocol/brand.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,CAAC,MAAM,cAAc,EAAE,OAAO,MAAM,CAAA;AAC3C,OAAO,CAAC,MAAM,WAAW,EAAE,OAAO,MAAM,CAAA;AAExC,4EAA4E;AAC5E,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG;IAAE,QAAQ,CAAC,CAAC,cAAc,CAAC,EAAE,IAAI,CAAA;CAAE,CAAA;AAEvE,qDAAqD;AACrD,MAAM,MAAM,SAAS,GAAG,MAAM,GAAG;IAAE,QAAQ,CAAC,CAAC,WAAW,CAAC,EAAE,IAAI,CAAA;CAAE,CAAA;AAEjE;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,YAAY,CAExD;AAED;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,CAElD"}

package/lib/protocol/brand.js

@@ -0,0 +1,25 @@
+/**
+ * Branded identifiers for the A2A wire vocabulary.
+ *
+ * Branding keeps a raw string from being used where a checked id is required —
+ * the same discipline `dsh-session` applies to `SessionId`.
+ *
+ * @module dsh-a2a/protocol/brand
+ */
+/**
+ * Brand a raw string as a context id.
+ * @param value - the raw identifier.
+ * @returns the same string, branded.
+ */
+export function A2AContextId(value) {
+    return value;
+}
+/**
+ * Brand a raw string as a task id.
+ * @param value - the raw identifier.
+ * @returns the same string, branded.
+ */
+export function A2ATaskId(value) {
+    return value;
+}
+//# sourceMappingURL=brand.js.map

package/lib/protocol/brand.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"brand.js","sourceRoot":"","sources":["../../src/protocol/brand.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAWH;;;;GAIG;AACH,MAAM,UAAU,YAAY,CAAC,KAAa;IACxC,OAAO,KAAqB,CAAA;AAC9B,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,SAAS,CAAC,KAAa;IACrC,OAAO,KAAkB,CAAA;AAC3B,CAAC"}

package/lib/protocol/card.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Agent Card construction.
+ *
+ * The card is the whole public product surface of an inbound-only A2A server:
+ * it is fetched anonymously, before any credential is presented. Skills are
+ * therefore whatever the deployment DECLARES, never a projection of the live
+ * tool registry — broadcasting the installed tool inventory to anyone who scans
+ * the port is information disclosure, not discovery.
+ *
+ * @module dsh-a2a/protocol/card
+ */
+import type { A2AAgentCard, A2AAgentSkill } from './wire.ts';
+/** Everything the card renderer needs from the deployment. */
+export interface CardInput {
+    name: string;
+    description: string;
+    version: string;
+    /** The routable URL peers should post to; already resolved past any proxy. */
+    url: string;
+    protocolVersion: string;
+    provider?: {
+        organization: string;
+        url: string;
+    };
+    skills: A2AAgentSkill[];
+    streaming: boolean;
+    pushNotifications: boolean;
+    /** Whether the RPC endpoint requires a bearer credential (it always does). */
+    authRequired: boolean;
+}
+/** The single skill advertised when a deployment declares none. */
+export declare const FALLBACK_SKILL: A2AAgentSkill;
+/**
+ * Build the Agent Card.
+ *
+ * Both interface spellings are emitted: `url` + `preferredTransport` for v0.3
+ * readers and `supportedInterfaces[]` for v1.0 readers. That costs a few bytes
+ * and removes an entire class of "peer could not find our endpoint" failure.
+ * @param input - the deployment-resolved card facts.
+ * @returns the card document to serve.
+ */
+export declare function buildAgentCard(input: CardInput): A2AAgentCard;
+//# sourceMappingURL=card.d.ts.map

package/lib/protocol/card.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"card.d.ts","sourceRoot":"","sources":["../../src/protocol/card.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,WAAW,CAAA;AAE5D,8DAA8D;AAC9D,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAA;IACZ,WAAW,EAAE,MAAM,CAAA;IACnB,OAAO,EAAE,MAAM,CAAA;IACf,8EAA8E;IAC9E,GAAG,EAAE,MAAM,CAAA;IACX,eAAe,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,EAAE;QAAE,YAAY,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,CAAA;IAChD,MAAM,EAAE,aAAa,EAAE,CAAA;IACvB,SAAS,EAAE,OAAO,CAAA;IAClB,iBAAiB,EAAE,OAAO,CAAA;IAC1B,8EAA8E;IAC9E,YAAY,EAAE,OAAO,CAAA;CACtB;AAED,mEAAmE;AACnE,eAAO,MAAM,cAAc,EAAE,aAK5B,CAAA;AAED;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,SAAS,GAAG,YAAY,CA6B7D"}

package/lib/protocol/card.js

@@ -0,0 +1,58 @@
+/**
+ * Agent Card construction.
+ *
+ * The card is the whole public product surface of an inbound-only A2A server:
+ * it is fetched anonymously, before any credential is presented. Skills are
+ * therefore whatever the deployment DECLARES, never a projection of the live
+ * tool registry — broadcasting the installed tool inventory to anyone who scans
+ * the port is information disclosure, not discovery.
+ *
+ * @module dsh-a2a/protocol/card
+ */
+/** The single skill advertised when a deployment declares none. */
+export const FALLBACK_SKILL = {
+    id: 'general',
+    name: 'general',
+    description: 'General-purpose agent task execution.',
+    tags: ['general'],
+};
+/**
+ * Build the Agent Card.
+ *
+ * Both interface spellings are emitted: `url` + `preferredTransport` for v0.3
+ * readers and `supportedInterfaces[]` for v1.0 readers. That costs a few bytes
+ * and removes an entire class of "peer could not find our endpoint" failure.
+ * @param input - the deployment-resolved card facts.
+ * @returns the card document to serve.
+ */
+export function buildAgentCard(input) {
+    const skills = input.skills.length > 0 ? input.skills : [FALLBACK_SKILL];
+    const card = {
+        protocolVersion: input.protocolVersion,
+        name: input.name,
+        description: input.description,
+        version: input.version,
+        url: input.url,
+        preferredTransport: 'JSONRPC',
+        supportedInterfaces: [{
+                url: input.url,
+                protocolBinding: 'JSONRPC',
+                protocolVersion: input.protocolVersion,
+            }],
+        capabilities: {
+            streaming: input.streaming,
+            pushNotifications: input.pushNotifications,
+            stateTransitionHistory: false,
+        },
+        defaultInputModes: ['text/plain'],
+        defaultOutputModes: ['text/plain'],
+        skills,
+        ...input.provider === undefined ? {} : { provider: input.provider },
+    };
+    if (input.authRequired) {
+        card.securitySchemes = { bearer: { type: 'http', scheme: 'bearer' } };
+        card.security = [{ bearer: [] }];
+    }
+    return card;
+}
+//# sourceMappingURL=card.js.map

package/lib/protocol/card.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"card.js","sourceRoot":"","sources":["../../src/protocol/card.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAoBH,mEAAmE;AACnE,MAAM,CAAC,MAAM,cAAc,GAAkB;IAC3C,EAAE,EAAE,SAAS;IACb,IAAI,EAAE,SAAS;IACf,WAAW,EAAE,uCAAuC;IACpD,IAAI,EAAE,CAAC,SAAS,CAAC;CAClB,CAAA;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,cAAc,CAAC,KAAgB;IAC7C,MAAM,MAAM,GAAG,KAAK,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,cAAc,CAAC,CAAA;IACxE,MAAM,IAAI,GAAiB;QACzB,eAAe,EAAE,KAAK,CAAC,eAAe;QACtC,IAAI,EAAE,KAAK,CAAC,IAAI;QAChB,WAAW,EAAE,KAAK,CAAC,WAAW;QAC9B,OAAO,EAAE,KAAK,CAAC,OAAO;QACtB,GAAG,EAAE,KAAK,CAAC,GAAG;QACd,kBAAkB,EAAE,SAAS;QAC7B,mBAAmB,EAAE,CAAC;gBACpB,GAAG,EAAE,KAAK,CAAC,GAAG;gBACd,eAAe,EAAE,SAAS;gBAC1B,eAAe,EAAE,KAAK,CAAC,eAAe;aACvC,CAAC;QACF,YAAY,EAAE;YACZ,SAAS,EAAE,KAAK,CAAC,SAAS;YAC1B,iBAAiB,EAAE,KAAK,CAAC,iBAAiB;YAC1C,sBAAsB,EAAE,KAAK;SAC9B;QACD,iBAAiB,EAAE,CAAC,YAAY,CAAC;QACjC,kBAAkB,EAAE,CAAC,YAAY,CAAC;QAClC,MAAM;QACN,GAAG,KAAK,CAAC,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,KAAK,CAAC,QAAQ,EAAE;KACpE,CAAA;IACD,IAAI,KAAK,CAAC,YAAY,EAAE,CAAC;QACvB,IAAI,CAAC,eAAe,GAAG,EAAE,MAAM,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,EAAE,CAAA;QACrE,IAAI,CAAC,QAAQ,GAAG,CAAC,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC,CAAA;IAClC,CAAC;IACD,OAAO,IAAI,CAAA;AACb,CAAC"}

package/lib/protocol/index.d.ts

@@ -0,0 +1,23 @@
+/**
+ * The A2A wire protocol as a dependency-free library.
+ *
+ * Nothing here touches Cordis, HTTP, or the harness: it is types, framing,
+ * dialect normalization, and document construction, so the spec's own JSON
+ * examples can be used as golden tests without booting anything.
+ *
+ * @module dsh-a2a/protocol
+ */
+export { A2AContextId, A2ATaskId } from './brand.ts';
+export type { A2AContextId as A2AContextIdType, A2ATaskId as A2ATaskIdType } from './brand.ts';
+export { TERMINAL_STATES, isTerminal, } from './wire.ts';
+export type { A2AAgentCard, A2AAgentSkill, A2AArtifact, A2ADataPart, A2ADialect, A2AFilePart, A2AMessage, A2AMessageSendConfiguration, A2AMessageSendParams, A2APart, A2APushNotificationConfig, A2ARole, A2AStreamEvent, A2ATask, A2ATaskArtifactUpdateEvent, A2ATaskState, A2ATaskStatus, A2ATaskStatusUpdateEvent, A2ATextPart, } from './wire.ts';
+export { A2ARpcError, ERR_CONTENT_TYPE_NOT_SUPPORTED, ERR_INTERNAL, ERR_INVALID_PARAMS, ERR_INVALID_REQUEST, ERR_METHOD_NOT_FOUND, ERR_PARSE, ERR_PUSH_NOT_SUPPORTED, ERR_TASK_NOT_CANCELABLE, ERR_TASK_NOT_FOUND, ERR_UNSUPPORTED_OPERATION, invalidParams, jsonRpcError, jsonRpcResult, taskNotFound, } from './jsonrpc.ts';
+export type { JsonRpcFailure, JsonRpcRequest, JsonRpcResponse, JsonRpcSuccess } from './jsonrpc.ts';
+export { parsePart, parseSendParams, partsToText, renderArtifactUpdate, renderStatusUpdate, renderTask, resolveMethod, } from './normalize.ts';
+export type { A2AOperation } from './normalize.ts';
+export { buildAgentCard, FALLBACK_SKILL } from './card.ts';
+export type { CardInput } from './card.ts';
+export { sseFrame } from './sse.ts';
+/** ISO 8601 UTC with millisecond precision, the timestamp shape A2A uses. */
+export declare function nowIso(): string;
+//# sourceMappingURL=index.d.ts.map

package/lib/protocol/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/protocol/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,YAAY,CAAA;AACpD,YAAY,EAAE,YAAY,IAAI,gBAAgB,EAAE,SAAS,IAAI,aAAa,EAAE,MAAM,YAAY,CAAA;AAE9F,OAAO,EACL,eAAe,EACf,UAAU,GACX,MAAM,WAAW,CAAA;AAClB,YAAY,EACV,YAAY,EACZ,aAAa,EACb,WAAW,EACX,WAAW,EACX,UAAU,EACV,WAAW,EACX,UAAU,EACV,2BAA2B,EAC3B,oBAAoB,EACpB,OAAO,EACP,yBAAyB,EACzB,OAAO,EACP,cAAc,EACd,OAAO,EACP,0BAA0B,EAC1B,YAAY,EACZ,aAAa,EACb,wBAAwB,EACxB,WAAW,GACZ,MAAM,WAAW,CAAA;AAElB,OAAO,EACL,WAAW,EACX,8BAA8B,EAC9B,YAAY,EACZ,kBAAkB,EAClB,mBAAmB,EACnB,oBAAoB,EACpB,SAAS,EACT,sBAAsB,EACtB,uBAAuB,EACvB,kBAAkB,EAClB,yBAAyB,EACzB,aAAa,EACb,YAAY,EACZ,aAAa,EACb,YAAY,GACb,MAAM,cAAc,CAAA;AACrB,YAAY,EAAE,cAAc,EAAE,cAAc,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,cAAc,CAAA;AAEnG,OAAO,EACL,SAAS,EACT,eAAe,EACf,WAAW,EACX,oBAAoB,EACpB,kBAAkB,EAClB,UAAU,EACV,aAAa,GACd,MAAM,gBAAgB,CAAA;AACvB,YAAY,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAA;AAElD,OAAO,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,WAAW,CAAA;AAC1D,YAAY,EAAE,SAAS,EAAE,MAAM,WAAW,CAAA;AAE1C,OAAO,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAA;AAEnC,6EAA6E;AAC7E,wBAAgB,MAAM,IAAI,MAAM,CAE/B"}

package/lib/protocol/index.js

@@ -0,0 +1,20 @@
+/**
+ * The A2A wire protocol as a dependency-free library.
+ *
+ * Nothing here touches Cordis, HTTP, or the harness: it is types, framing,
+ * dialect normalization, and document construction, so the spec's own JSON
+ * examples can be used as golden tests without booting anything.
+ *
+ * @module dsh-a2a/protocol
+ */
+export { A2AContextId, A2ATaskId } from "./brand.js";
+export { TERMINAL_STATES, isTerminal, } from "./wire.js";
+export { A2ARpcError, ERR_CONTENT_TYPE_NOT_SUPPORTED, ERR_INTERNAL, ERR_INVALID_PARAMS, ERR_INVALID_REQUEST, ERR_METHOD_NOT_FOUND, ERR_PARSE, ERR_PUSH_NOT_SUPPORTED, ERR_TASK_NOT_CANCELABLE, ERR_TASK_NOT_FOUND, ERR_UNSUPPORTED_OPERATION, invalidParams, jsonRpcError, jsonRpcResult, taskNotFound, } from "./jsonrpc.js";
+export { parsePart, parseSendParams, partsToText, renderArtifactUpdate, renderStatusUpdate, renderTask, resolveMethod, } from "./normalize.js";
+export { buildAgentCard, FALLBACK_SKILL } from "./card.js";
+export { sseFrame } from "./sse.js";
+/** ISO 8601 UTC with millisecond precision, the timestamp shape A2A uses. */
+export function nowIso() {
+    return new Date().toISOString();
+}
+//# sourceMappingURL=index.js.map

package/lib/protocol/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/protocol/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,YAAY,CAAA;AAGpD,OAAO,EACL,eAAe,EACf,UAAU,GACX,MAAM,WAAW,CAAA;AAuBlB,OAAO,EACL,WAAW,EACX,8BAA8B,EAC9B,YAAY,EACZ,kBAAkB,EAClB,mBAAmB,EACnB,oBAAoB,EACpB,SAAS,EACT,sBAAsB,EACtB,uBAAuB,EACvB,kBAAkB,EAClB,yBAAyB,EACzB,aAAa,EACb,YAAY,EACZ,aAAa,EACb,YAAY,GACb,MAAM,cAAc,CAAA;AAGrB,OAAO,EACL,SAAS,EACT,eAAe,EACf,WAAW,EACX,oBAAoB,EACpB,kBAAkB,EAClB,UAAU,EACV,aAAa,GACd,MAAM,gBAAgB,CAAA;AAGvB,OAAO,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,WAAW,CAAA;AAG1D,OAAO,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAA;AAEnC,6EAA6E;AAC7E,MAAM,UAAU,MAAM;IACpB,OAAO,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAA;AACjC,CAAC"}

package/lib/protocol/jsonrpc.d.ts

@@ -0,0 +1,93 @@
+/**
+ * JSON-RPC 2.0 framing and the A2A error-code vocabulary.
+ *
+ * Authentication, rate limiting, and the trust gate deliberately do NOT get
+ * JSON-RPC codes: A2A puts transport security at the HTTP layer, and the
+ * `-32050…` range some implementations invent is not reserved, so no peer SDK
+ * recognizes it. Those failures answer with an HTTP status whose body is still
+ * a valid JSON-RPC error envelope, so a client that blindly parses the body
+ * and one that reads the status are both served.
+ *
+ * @module dsh-a2a/protocol/jsonrpc
+ */
+/** Standard JSON-RPC 2.0 codes. */
+export declare const ERR_PARSE = -32700;
+export declare const ERR_INVALID_REQUEST = -32600;
+export declare const ERR_METHOD_NOT_FOUND = -32601;
+export declare const ERR_INVALID_PARAMS = -32602;
+export declare const ERR_INTERNAL = -32603;
+/** A2A-reserved codes, used only with their spec semantics. */
+export declare const ERR_TASK_NOT_FOUND = -32001;
+export declare const ERR_TASK_NOT_CANCELABLE = -32002;
+export declare const ERR_PUSH_NOT_SUPPORTED = -32003;
+export declare const ERR_UNSUPPORTED_OPERATION = -32004;
+export declare const ERR_CONTENT_TYPE_NOT_SUPPORTED = -32005;
+/** A JSON-RPC request as received from a peer. */
+export interface JsonRpcRequest {
+    jsonrpc?: string;
+    id?: string | number | null;
+    method?: string;
+    params?: unknown;
+}
+/** A successful JSON-RPC response. */
+export interface JsonRpcSuccess {
+    jsonrpc: '2.0';
+    id: string | number | null;
+    result: unknown;
+}
+/** A failed JSON-RPC response. */
+export interface JsonRpcFailure {
+    jsonrpc: '2.0';
+    id: string | number | null;
+    error: {
+        code: number;
+        message: string;
+        data?: unknown;
+    };
+}
+/** Either shape of JSON-RPC response. */
+export type JsonRpcResponse = JsonRpcSuccess | JsonRpcFailure;
+/**
+ * Build a success envelope.
+ * @param id - the request id being answered.
+ * @param result - the method's result value.
+ * @returns the response envelope.
+ */
+export declare function jsonRpcResult(id: string | number | null, result: unknown): JsonRpcSuccess;
+/**
+ * Build an error envelope.
+ * @param id - the request id being answered, or null when unknown.
+ * @param code - the JSON-RPC or A2A error code.
+ * @param message - a human-readable explanation carrying no internal paths.
+ * @param data - optional structured detail.
+ * @returns the response envelope.
+ */
+export declare function jsonRpcError(id: string | number | null, code: number, message: string, data?: unknown): JsonRpcFailure;
+/** An error carrying the JSON-RPC code a handler wants reported. */
+export declare class A2ARpcError extends Error {
+    readonly code: number;
+    readonly httpStatus: number;
+    /**
+     * @param code - the JSON-RPC or A2A error code.
+     * @param message - the human-readable explanation.
+     * @param httpStatus - the HTTP status to answer with; defaults to 200 because
+     * an ordinary JSON-RPC error is a successful HTTP exchange.
+     */
+    constructor(code: number, message: string, httpStatus?: number);
+}
+/**
+ * Reject a malformed or unsupported parameter.
+ * @param detail - what was wrong.
+ * @returns the error to throw.
+ */
+export declare function invalidParams(detail: string): A2ARpcError;
+/**
+ * Report a task that does not exist, or that this identity may not see.
+ *
+ * A task owned by another peer answers with this same error rather than a 403,
+ * so a peer cannot probe which task ids exist by comparing responses.
+ * @param taskId - the id the peer asked about.
+ * @returns the error to throw.
+ */
+export declare function taskNotFound(taskId: string): A2ARpcError;
+//# sourceMappingURL=jsonrpc.d.ts.map

package/lib/protocol/jsonrpc.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"jsonrpc.d.ts","sourceRoot":"","sources":["../../src/protocol/jsonrpc.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,mCAAmC;AACnC,eAAO,MAAM,SAAS,SAAS,CAAA;AAC/B,eAAO,MAAM,mBAAmB,SAAS,CAAA;AACzC,eAAO,MAAM,oBAAoB,SAAS,CAAA;AAC1C,eAAO,MAAM,kBAAkB,SAAS,CAAA;AACxC,eAAO,MAAM,YAAY,SAAS,CAAA;AAElC,+DAA+D;AAC/D,eAAO,MAAM,kBAAkB,SAAS,CAAA;AACxC,eAAO,MAAM,uBAAuB,SAAS,CAAA;AAC7C,eAAO,MAAM,sBAAsB,SAAS,CAAA;AAC5C,eAAO,MAAM,yBAAyB,SAAS,CAAA;AAC/C,eAAO,MAAM,8BAA8B,SAAS,CAAA;AAEpD,kDAAkD;AAClD,MAAM,WAAW,cAAc;IAC7B,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAA;IAC3B,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,MAAM,CAAC,EAAE,OAAO,CAAA;CACjB;AAED,sCAAsC;AACtC,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,KAAK,CAAA;IACd,EAAE,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAA;IAC1B,MAAM,EAAE,OAAO,CAAA;CAChB;AAED,kCAAkC;AAClC,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,KAAK,CAAA;IACd,EAAE,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAA;IAC1B,KAAK,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,OAAO,CAAA;KAAE,CAAA;CACzD;AAED,yCAAyC;AACzC,MAAM,MAAM,eAAe,GAAG,cAAc,GAAG,cAAc,CAAA;AAE7D;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,EAAE,MAAM,EAAE,OAAO,GAAG,cAAc,CAEzF;AAED;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAC1B,EAAE,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,EAC1B,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,EACf,IAAI,CAAC,EAAE,OAAO,GACb,cAAc,CAEhB;AAED,oEAAoE;AACpE,qBAAa,WAAY,SAAQ,KAAK;IAQlC,QAAQ,CAAC,IAAI,EAAE,MAAM;IAErB,QAAQ,CAAC,UAAU,EAAE,MAAM;IAT7B;;;;;OAKG;gBAEQ,IAAI,EAAE,MAAM,EACrB,OAAO,EAAE,MAAM,EACN,UAAU,GAAE,MAAY;CAKpC;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,WAAW,CAEzD;AAED;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,WAAW,CAExD"}

package/lib/protocol/jsonrpc.js

@@ -0,0 +1,81 @@
+/**
+ * JSON-RPC 2.0 framing and the A2A error-code vocabulary.
+ *
+ * Authentication, rate limiting, and the trust gate deliberately do NOT get
+ * JSON-RPC codes: A2A puts transport security at the HTTP layer, and the
+ * `-32050…` range some implementations invent is not reserved, so no peer SDK
+ * recognizes it. Those failures answer with an HTTP status whose body is still
+ * a valid JSON-RPC error envelope, so a client that blindly parses the body
+ * and one that reads the status are both served.
+ *
+ * @module dsh-a2a/protocol/jsonrpc
+ */
+/** Standard JSON-RPC 2.0 codes. */
+export const ERR_PARSE = -32700;
+export const ERR_INVALID_REQUEST = -32600;
+export const ERR_METHOD_NOT_FOUND = -32601;
+export const ERR_INVALID_PARAMS = -32602;
+export const ERR_INTERNAL = -32603;
+/** A2A-reserved codes, used only with their spec semantics. */
+export const ERR_TASK_NOT_FOUND = -32001;
+export const ERR_TASK_NOT_CANCELABLE = -32002;
+export const ERR_PUSH_NOT_SUPPORTED = -32003;
+export const ERR_UNSUPPORTED_OPERATION = -32004;
+export const ERR_CONTENT_TYPE_NOT_SUPPORTED = -32005;
+/**
+ * Build a success envelope.
+ * @param id - the request id being answered.
+ * @param result - the method's result value.
+ * @returns the response envelope.
+ */
+export function jsonRpcResult(id, result) {
+    return { jsonrpc: '2.0', id, result };
+}
+/**
+ * Build an error envelope.
+ * @param id - the request id being answered, or null when unknown.
+ * @param code - the JSON-RPC or A2A error code.
+ * @param message - a human-readable explanation carrying no internal paths.
+ * @param data - optional structured detail.
+ * @returns the response envelope.
+ */
+export function jsonRpcError(id, code, message, data) {
+    return { jsonrpc: '2.0', id, error: { code, message, ...data === undefined ? {} : { data } } };
+}
+/** An error carrying the JSON-RPC code a handler wants reported. */
+export class A2ARpcError extends Error {
+    code;
+    httpStatus;
+    /**
+     * @param code - the JSON-RPC or A2A error code.
+     * @param message - the human-readable explanation.
+     * @param httpStatus - the HTTP status to answer with; defaults to 200 because
+     * an ordinary JSON-RPC error is a successful HTTP exchange.
+     */
+    constructor(code, message, httpStatus = 200) {
+        super(message);
+        this.code = code;
+        this.httpStatus = httpStatus;
+        this.name = 'A2ARpcError';
+    }
+}
+/**
+ * Reject a malformed or unsupported parameter.
+ * @param detail - what was wrong.
+ * @returns the error to throw.
+ */
+export function invalidParams(detail) {
+    return new A2ARpcError(ERR_INVALID_PARAMS, detail);
+}
+/**
+ * Report a task that does not exist, or that this identity may not see.
+ *
+ * A task owned by another peer answers with this same error rather than a 403,
+ * so a peer cannot probe which task ids exist by comparing responses.
+ * @param taskId - the id the peer asked about.
+ * @returns the error to throw.
+ */
+export function taskNotFound(taskId) {
+    return new A2ARpcError(ERR_TASK_NOT_FOUND, `task not found: ${taskId}`);
+}
+//# sourceMappingURL=jsonrpc.js.map

package/lib/protocol/jsonrpc.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"jsonrpc.js","sourceRoot":"","sources":["../../src/protocol/jsonrpc.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,mCAAmC;AACnC,MAAM,CAAC,MAAM,SAAS,GAAG,CAAC,KAAK,CAAA;AAC/B,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAC,KAAK,CAAA;AACzC,MAAM,CAAC,MAAM,oBAAoB,GAAG,CAAC,KAAK,CAAA;AAC1C,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAAC,KAAK,CAAA;AACxC,MAAM,CAAC,MAAM,YAAY,GAAG,CAAC,KAAK,CAAA;AAElC,+DAA+D;AAC/D,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAAC,KAAK,CAAA;AACxC,MAAM,CAAC,MAAM,uBAAuB,GAAG,CAAC,KAAK,CAAA;AAC7C,MAAM,CAAC,MAAM,sBAAsB,GAAG,CAAC,KAAK,CAAA;AAC5C,MAAM,CAAC,MAAM,yBAAyB,GAAG,CAAC,KAAK,CAAA;AAC/C,MAAM,CAAC,MAAM,8BAA8B,GAAG,CAAC,KAAK,CAAA;AA2BpD;;;;;GAKG;AACH,MAAM,UAAU,aAAa,CAAC,EAA0B,EAAE,MAAe;IACvE,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,EAAE,EAAE,MAAM,EAAE,CAAA;AACvC,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,YAAY,CAC1B,EAA0B,EAC1B,IAAY,EACZ,OAAe,EACf,IAAc;IAEd,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,EAAE,EAAE,KAAK,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,EAAE,EAAE,CAAA;AAChG,CAAC;AAED,oEAAoE;AACpE,MAAM,OAAO,WAAY,SAAQ,KAAK;IAQzB;IAEA;IATX;;;;;OAKG;IACH,YACW,IAAY,EACrB,OAAe,EACN,aAAqB,GAAG;QAEjC,KAAK,CAAC,OAAO,CAAC,CAAA;QAJL,SAAI,GAAJ,IAAI,CAAQ;QAEZ,eAAU,GAAV,UAAU,CAAc;QAGjC,IAAI,CAAC,IAAI,GAAG,aAAa,CAAA;IAC3B,CAAC;CACF;AAED;;;;GAIG;AACH,MAAM,UAAU,aAAa,CAAC,MAAc;IAC1C,OAAO,IAAI,WAAW,CAAC,kBAAkB,EAAE,MAAM,CAAC,CAAA;AACpD,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,YAAY,CAAC,MAAc;IACzC,OAAO,IAAI,WAAW,CAAC,kBAAkB,EAAE,mBAAmB,MAAM,EAAE,CAAC,CAAA;AACzE,CAAC"}

package/lib/protocol/normalize.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Dialect normalization between A2A v0.3.0 and v1.0.
+ *
+ * Inbound is permissive, outbound is strict: a request in either spelling is
+ * parsed into the internal v0.3 shape, and the response is rendered back in the
+ * dialect that request declared. Nothing mixes the two spellings in one reply.
+ *
+ * @module dsh-a2a/protocol/normalize
+ */
+import type { A2ADialect, A2AMessageSendParams, A2APart, A2ATask, A2ATaskStatusUpdateEvent, A2ATaskArtifactUpdateEvent } from './wire.ts';
+/** The internal operation a peer's method name resolves to. */
+export type A2AOperation = 'send' | 'stream' | 'get' | 'cancel' | 'resubscribe' | 'push_set' | 'push_get' | 'push_list' | 'push_delete';
+/** One row of the method table: which operation, and which dialect it implies. */
+interface MethodEntry {
+    operation: A2AOperation;
+    dialect: A2ADialect;
+}
+/**
+ * Resolve a method name to its operation and implied dialect.
+ * @param method - the raw `method` string from the request.
+ * @returns the entry, or undefined for an unknown method.
+ */
+export declare function resolveMethod(method: string): MethodEntry | undefined;
+/**
+ * Read a `Part` written in any of the three known spellings.
+ *
+ * v0.3 discriminates on `kind`, v1.0 on member presence, and pre-0.3 peers used
+ * `type`. Unknown shapes yield undefined rather than throwing, so one odd part
+ * cannot fail a request whose other parts are usable.
+ * @param raw - one element of a `parts` array.
+ * @returns the normalized part, or undefined when unrecognizable.
+ */
+export declare function parsePart(raw: unknown): A2APart | undefined;
+/**
+ * Render every part as text the model can read.
+ *
+ * File and data parts become bracketed references rather than being dropped, so
+ * the agent knows something was attached and can ask about it. This is the same
+ * flattening `dsh-acp` applies to baseline resource links.
+ * @param parts - normalized parts, in order.
+ * @returns the joined text, empty when nothing rendered.
+ */
+export declare function partsToText(parts: readonly A2APart[]): string;
+/**
+ * Parse `message/send` and `message/stream` parameters from either dialect.
+ * @param raw - the request's `params` value.
+ * @returns the normalized parameters, or undefined when the shape is unusable.
+ */
+export declare function parseSendParams(raw: unknown): A2AMessageSendParams | undefined;
+/**
+ * Render a task in the requested dialect.
+ * @param task - the internal v0.3-shaped task.
+ * @param dialect - the dialect the peer spoke.
+ * @returns the wire object to serialize.
+ */
+export declare function renderTask(task: A2ATask, dialect: A2ADialect): unknown;
+/**
+ * Render a status-update stream event in the requested dialect.
+ * @param event - the internal event.
+ * @param dialect - the dialect the peer spoke.
+ * @returns the wire object to serialize.
+ */
+export declare function renderStatusUpdate(event: A2ATaskStatusUpdateEvent, dialect: A2ADialect): unknown;
+/**
+ * Render an artifact-update stream event in the requested dialect.
+ * @param event - the internal event.
+ * @param dialect - the dialect the peer spoke.
+ * @returns the wire object to serialize.
+ */
+export declare function renderArtifactUpdate(event: A2ATaskArtifactUpdateEvent, dialect: A2ADialect): unknown;
+export {};
+//# sourceMappingURL=normalize.d.ts.map

package/lib/protocol/normalize.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"normalize.d.ts","sourceRoot":"","sources":["../../src/protocol/normalize.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,OAAO,KAAK,EACV,UAAU,EAGV,oBAAoB,EACpB,OAAO,EAEP,OAAO,EAEP,wBAAwB,EACxB,0BAA0B,EAC3B,MAAM,WAAW,CAAA;AAElB,+DAA+D;AAC/D,MAAM,MAAM,YAAY,GACpB,MAAM,GACN,QAAQ,GACR,KAAK,GACL,QAAQ,GACR,aAAa,GACb,UAAU,GACV,UAAU,GACV,WAAW,GACX,aAAa,CAAA;AAEjB,kFAAkF;AAClF,UAAU,WAAW;IACnB,SAAS,EAAE,YAAY,CAAA;IACvB,OAAO,EAAE,UAAU,CAAA;CACpB;AAiCD;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,WAAW,GAAG,SAAS,CAErE;AAmBD;;;;;;;;GAQG;AACH,wBAAgB,SAAS,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,GAAG,SAAS,CAsB3D;AAmCD;;;;;;;;GAQG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,SAAS,OAAO,EAAE,GAAG,MAAM,CAc7D;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,OAAO,GAAG,oBAAoB,GAAG,SAAS,CAqC9E;AAcD;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,OAAO,EAAE,OAAO,EAAE,UAAU,GAAG,OAAO,CAOtE;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,wBAAwB,EAAE,OAAO,EAAE,UAAU,GAAG,OAAO,CAGhG;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,0BAA0B,EACjC,OAAO,EAAE,UAAU,GAClB,OAAO,CAET"}