@groundnuty/macf-channel-server 0.2.28 → 0.2.32

package/dist/a2a-client.d.ts

@@ -0,0 +1,85 @@
+import type { Message, Task } from './a2a-types.js';
+import type { AgentCard } from './agent-card.js';
+/** Default per-target AgentCard cache TTL (5 minutes). */
+export declare const AGENT_CARD_CACHE_TTL_MS: number;
+export interface A2aClientConfig {
+    /** PEM-encoded client cert for mTLS handshake. */
+    readonly mTlsClientCertPem: string;
+    /** PEM-encoded client key for mTLS handshake. */
+    readonly mTlsClientKeyPem: string;
+    /** PEM-encoded CA cert chain to validate the remote server's cert. */
+    readonly caCertPem: string;
+    /** Optional override for per-request timeout (default 30s). */
+    readonly timeoutMs?: number;
+    /** Optional override for the AgentCard cache TTL (default 5min). */
+    readonly agentCardCacheTtlMs?: number;
+}
+/** Error class for A2A client failures. */
+export declare class A2aClientError extends Error {
+    readonly cause?: unknown | undefined;
+    readonly code: string;
+    constructor(code: string, message: string, cause?: unknown | undefined);
+}
+/**
+ * Outbound A2A v1.0 client. Single instance per channel-server process.
+ *
+ * Hold the keep-alive https.Agent + AgentCard cache as instance state.
+ * Stateless across calls otherwise — each `sendMessage` /
+ * `getAgentCard` invocation is independent.
+ */
+export declare class A2aClient {
+    #private;
+    constructor(config: A2aClientConfig);
+    /**
+     * Dispatch a `message/send` JSON-RPC call to a remote A2A v1.0 endpoint.
+     *
+     * Wraps in OTel CLIENT span named `invoke_agent {target}` per the
+     * canonical GenAI semconv (matches the existing `notify_peer` outbound
+     * pattern post-macf#369). The `target` is derived from the target URL's
+     * host:port pair when not explicitly provided.
+     *
+     * Returns the parsed `Task` on success.
+     *
+     * Throws `A2aClientError` on:
+     * - Transport failure (TLS, connect timeout, etc.) — code `'TRANSPORT_ERROR'`
+     * - HTTP non-200 — code `'HTTP_ERROR'`
+     * - JSON-RPC error envelope (`error` field set in response) — code `'JSONRPC_ERROR'`
+     *   with `.cause` carrying the structured error object
+     * - Schema validation failure on response body — code `'INVALID_RESPONSE'`
+     *
+     * Does NOT retry on failure (per design Q4 — `message/send` is not idempotent).
+     */
+    sendMessage(targetUrl: string, message: Message, opts?: {
+        readonly target?: string;
+        readonly requestId?: string;
+    }): Promise<Task>;
+    /**
+     * Fetch a target's AgentCard via the well-known URL. Caches the result
+     * per `targetUrl` for `agentCardCacheTtlMs` (default 5min).
+     *
+     * Returns `null` if:
+     * - The endpoint returns 404 (target doesn't publish an AgentCard)
+     * - The endpoint returns 401/403 (auth failure — cache miss + signals
+     *   to caller that they may need to refresh credentials)
+     *
+     * Throws `A2aClientError` on:
+     * - Transport failure (TLS, connect timeout) — code `'TRANSPORT_ERROR'`
+     * - HTTP 5xx — code `'HTTP_ERROR'` (caller may want to retry)
+     * - Body fails AgentCard schema validation — code `'INVALID_AGENT_CARD'`
+     *
+     * Retry on network errors: 3 attempts with exponential backoff
+     * (1s/2s/4s; total ~7s). HTTP responses (200, 404, 4xx, 5xx) are not
+     * retried — they're authoritative server signals.
+     */
+    getAgentCard(targetUrl: string): Promise<AgentCard | null>;
+    /** Diagnostic: count of cached AgentCard entries (testing aid). */
+    agentCardCacheSize(): number;
+    /** Manually invalidate a cached AgentCard (e.g., after detected target rotation). */
+    invalidateAgentCard(targetUrl: string): void;
+    /**
+     * Close the underlying https.Agent. Call on channel-server shutdown to
+     * release pooled sockets cleanly.
+     */
+    close(): void;
+}
+//# sourceMappingURL=a2a-client.d.ts.map

package/dist/a2a-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"a2a-client.d.ts","sourceRoot":"","sources":["../src/a2a-client.ts"],"names":[],"mappings":"AAiEA,OAAO,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,gBAAgB,CAAC;AAEpD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAKjD,0DAA0D;AAC1D,eAAO,MAAM,uBAAuB,QAAgB,CAAC;AAQrD,MAAM,WAAW,eAAe;IAC9B,kDAAkD;IAClD,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;IACnC,iDAAiD;IACjD,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC,sEAAsE;IACtE,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,+DAA+D;IAC/D,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,oEAAoE;IACpE,QAAQ,CAAC,mBAAmB,CAAC,EAAE,MAAM,CAAC;CACvC;AAQD,2CAA2C;AAC3C,qBAAa,cAAe,SAAQ,KAAK;aAE6B,KAAK,CAAC,EAAE,OAAO;IADnF,SAAgB,IAAI,EAAE,MAAM,CAAC;gBACjB,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAA2B,KAAK,CAAC,EAAE,OAAO,YAAA;CAKpF;AAED;;;;;;GAMG;AACH,qBAAa,SAAS;;gBAKR,MAAM,EAAE,eAAe;IAanC;;;;;;;;;;;;;;;;;;OAkBG;IACG,WAAW,CACf,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,OAAO,EAChB,IAAI,GAAE;QAAE,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAA;KAAO,GACnE,OAAO,CAAC,IAAI,CAAC;IA8EhB;;;;;;;;;;;;;;;;;OAiBG;IACG,YAAY,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,GAAG,IAAI,CAAC;IAqChE,mEAAmE;IACnE,kBAAkB,IAAI,MAAM;IAI5B,qFAAqF;IACrF,mBAAmB,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI;IAI5C;;;OAGG;IACH,KAAK,IAAI,IAAI;CAsKd"}

package/dist/a2a-client.js

@@ -0,0 +1,381 @@
+/**
+ * A2A v1.0 outbound client primitive (groundnuty/macf#396 Phase 3).
+ *
+ * MACF channel-server's outbound A2A capability — dispatches `message/send`
+ * JSON-RPC to remote A2A v1.0-compliant agents + fetches their AgentCard
+ * via `/.well-known/agent-card.json`.
+ *
+ * **Hand-rolled SDK** (consistent with Phase 1 + 2a + 2c decisions):
+ * `@a2a-js/sdk` is at v0.3.13 (A2A v0.3 target); v1.0 not released.
+ * Hand-rolled Zod schemas (Message + Task + JSON-RPC envelopes) +
+ * `node:https` request are the minimal-blast-radius approach + reuse
+ * the same shapes the inbound side validates. Re-evaluate at Phase 3.5
+ * or Phase 4 if SDK reaches v1.0 stable.
+ *
+ * **Spec verification** (2026-05-19 via a2a-protocol.org):
+ * - § 9 JSON-RPC binding: method `"message/send"`; envelope `{ jsonrpc: "2.0", id, method, params }`
+ * - § 4.1.4 Message schema (reused from `a2a-types.ts`)
+ * - § 4.1.1 Task return shape (reused from `a2a-types.ts`)
+ * - § 14.3 well-known URL convention for AgentCard discovery
+ * - W3C tracecontext propagation via HTTP `traceparent` header
+ *   (`propagation.inject()` from `@opentelemetry/api`)
+ *
+ * **Design references**: design proposal posted on `#396` 2026-05-19
+ * (science-agent approved with two notes — both addressed):
+ * - Span name: `invoke_agent {target}` via `buildInvokeAgentSpanName()`
+ *   helper from `tracing.ts:60-65`; NOT `macf.invoke_agent`
+ * - AgentCard cache: folded into this file (NOT a separate `agent-card-cache.ts`);
+ *   extract only if cache surface grows in a future phase
+ *
+ * **Retry policy** (per design Q4):
+ * - `getAgentCard()`: idempotent + safe to retry. Up to 3 attempts on
+ *   network errors with exponential backoff (1s/2s/4s; ~7s total).
+ * - `sendMessage()`: NOT retried. The spec doesn't mandate `messageId`
+ *   deduplication on the server side; re-sending may create a new task.
+ *   Caller responsibility to handle network errors with explicit retry
+ *   semantics (and a fresh `messageId` if they choose to).
+ *
+ * **AgentCard cache** (per design Q6):
+ * - Per-target in-memory Map; 5-min TTL
+ * - Fresh fetch on miss + on auth-failure (401/403)
+ * - Sweep on process exit (matches Phase 2a TaskStore lifecycle)
+ *
+ * **mTLS configuration**:
+ * - Per-project CA chain reused (DR-010 + DR-022)
+ * - `node:https.Agent` with `keepAlive: true` for connection reuse
+ * - `checkServerIdentity: () => undefined` since channel-server certs
+ *   advertise CN-based identity, not SAN-matched hostname (matches
+ *   existing `notify-peer.ts` outbound pattern)
+ */
+import { request as httpsRequest, Agent as HttpsAgent } from 'node:https';
+import { randomUUID } from 'node:crypto';
+import { context, propagation, SpanKind, SpanStatusCode, trace, } from '@opentelemetry/api';
+import { buildInvokeAgentSpanName, Attr, GenAiAttr } from './tracing.js';
+import { JsonRpcSuccessResponseSchema, JsonRpcErrorResponseSchema, A2A_METHOD_MESSAGE_SEND, A2A_ENDPOINT_PATH, } from './a2a-types.js';
+import { AgentCardSchema } from './agent-card.js';
+/** Default request timeout for outbound A2A calls (synchronous message/send). */
+const DEFAULT_TIMEOUT_MS = 30_000;
+/** Default per-target AgentCard cache TTL (5 minutes). */
+export const AGENT_CARD_CACHE_TTL_MS = 5 * 60 * 1000;
+/** Well-known URL path for AgentCard discovery (A2A spec § 14.3). */
+const AGENT_CARD_PATH = '/.well-known/agent-card.json';
+/** Retry policy for idempotent operations (AgentCard fetch). */
+const IDEMPOTENT_RETRY_DELAYS_MS = [1000, 2000, 4000];
+/** Error class for A2A client failures. */
+export class A2aClientError extends Error {
+    cause;
+    code;
+    constructor(code, message, cause) {
+        super(message);
+        this.cause = cause;
+        this.name = 'A2aClientError';
+        this.code = code;
+    }
+}
+/**
+ * Outbound A2A v1.0 client. Single instance per channel-server process.
+ *
+ * Hold the keep-alive https.Agent + AgentCard cache as instance state.
+ * Stateless across calls otherwise — each `sendMessage` /
+ * `getAgentCard` invocation is independent.
+ */
+export class A2aClient {
+    #config;
+    #agent;
+    #agentCardCache = new Map();
+    constructor(config) {
+        this.#config = config;
+        // keepAlive lets us reuse TLS sessions across per-target calls; the
+        // agent-card-discovery flow typically does 2 calls (card fetch then
+        // message/send) so keepAlive saves a TLS handshake on the second.
+        this.#agent = new HttpsAgent({
+            keepAlive: true,
+            // Per-host concurrency cap. Channel-server's outbound is
+            // typically low-concurrency (1-2 in flight), so default is fine.
+            maxSockets: 8,
+        });
+    }
+    /**
+     * Dispatch a `message/send` JSON-RPC call to a remote A2A v1.0 endpoint.
+     *
+     * Wraps in OTel CLIENT span named `invoke_agent {target}` per the
+     * canonical GenAI semconv (matches the existing `notify_peer` outbound
+     * pattern post-macf#369). The `target` is derived from the target URL's
+     * host:port pair when not explicitly provided.
+     *
+     * Returns the parsed `Task` on success.
+     *
+     * Throws `A2aClientError` on:
+     * - Transport failure (TLS, connect timeout, etc.) — code `'TRANSPORT_ERROR'`
+     * - HTTP non-200 — code `'HTTP_ERROR'`
+     * - JSON-RPC error envelope (`error` field set in response) — code `'JSONRPC_ERROR'`
+     *   with `.cause` carrying the structured error object
+     * - Schema validation failure on response body — code `'INVALID_RESPONSE'`
+     *
+     * Does NOT retry on failure (per design Q4 — `message/send` is not idempotent).
+     */
+    async sendMessage(targetUrl, message, opts = {}) {
+        const tracer = trace.getTracer('macf');
+        const spanTarget = opts.target ?? this.#deriveTargetHandle(targetUrl);
+        const requestId = opts.requestId ?? `req-${randomUUID()}`;
+        return tracer.startActiveSpan(buildInvokeAgentSpanName(spanTarget), {
+            kind: SpanKind.CLIENT,
+            attributes: {
+                [GenAiAttr.System]: 'macf',
+                [GenAiAttr.OperationName]: 'invoke_agent',
+                ...(spanTarget !== '' ? { [GenAiAttr.AgentName]: spanTarget } : {}),
+                // macf#396 Phase 3: distinguish A2A outbound from legacy
+                // notify_peer outbound under a single span name (both emit
+                // `invoke_agent` per OTel GenAI semconv; the `macf.outbound.
+                // protocol` attribute tells operators which dispatch path
+                // ran). Sister to the SERVER-side `macf.a2a.dispatch`
+                // attribute set in https.ts.
+                [Attr.OutboundProtocol]: 'a2a',
+                [Attr.OutboundTargetUrl]: targetUrl,
+            },
+        }, async (span) => {
+            try {
+                const envelope = {
+                    jsonrpc: '2.0',
+                    id: requestId,
+                    method: A2A_METHOD_MESSAGE_SEND,
+                    params: { message },
+                };
+                const response = await this.#postJsonRpc(`${targetUrl}${A2A_ENDPOINT_PATH}`, envelope);
+                // Try success-shape first; fall through to error-shape.
+                const success = JsonRpcSuccessResponseSchema.safeParse(response);
+                if (success.success) {
+                    const task = success.data.result;
+                    span.setAttribute(Attr.A2aTaskId, task.id);
+                    span.setAttribute(Attr.A2aTaskState, task.status.state);
+                    span.setStatus({ code: SpanStatusCode.OK });
+                    return task;
+                }
+                const errorEnv = JsonRpcErrorResponseSchema.safeParse(response);
+                if (errorEnv.success) {
+                    const err = new A2aClientError('JSONRPC_ERROR', `A2A server returned JSON-RPC error: ${errorEnv.data.error.message}`, errorEnv.data.error);
+                    span.recordException(err);
+                    span.setStatus({ code: SpanStatusCode.ERROR, message: err.message });
+                    throw err;
+                }
+                const err = new A2aClientError('INVALID_RESPONSE', `Response matches neither success nor error envelope`);
+                span.recordException(err);
+                span.setStatus({ code: SpanStatusCode.ERROR, message: err.message });
+                throw err;
+            }
+            catch (err) {
+                if (!(err instanceof A2aClientError)) {
+                    span.recordException(err);
+                    span.setStatus({
+                        code: SpanStatusCode.ERROR,
+                        message: err instanceof Error ? err.message : String(err),
+                    });
+                }
+                throw err;
+            }
+            finally {
+                span.end();
+            }
+        });
+    }
+    /**
+     * Fetch a target's AgentCard via the well-known URL. Caches the result
+     * per `targetUrl` for `agentCardCacheTtlMs` (default 5min).
+     *
+     * Returns `null` if:
+     * - The endpoint returns 404 (target doesn't publish an AgentCard)
+     * - The endpoint returns 401/403 (auth failure — cache miss + signals
+     *   to caller that they may need to refresh credentials)
+     *
+     * Throws `A2aClientError` on:
+     * - Transport failure (TLS, connect timeout) — code `'TRANSPORT_ERROR'`
+     * - HTTP 5xx — code `'HTTP_ERROR'` (caller may want to retry)
+     * - Body fails AgentCard schema validation — code `'INVALID_AGENT_CARD'`
+     *
+     * Retry on network errors: 3 attempts with exponential backoff
+     * (1s/2s/4s; total ~7s). HTTP responses (200, 404, 4xx, 5xx) are not
+     * retried — they're authoritative server signals.
+     */
+    async getAgentCard(targetUrl) {
+        const cached = this.#agentCardCache.get(targetUrl);
+        const ttl = this.#config.agentCardCacheTtlMs ?? AGENT_CARD_CACHE_TTL_MS;
+        if (cached !== undefined && Date.now() - cached.fetchedAt < ttl) {
+            return cached.card;
+        }
+        let lastError;
+        for (let attempt = 0; attempt <= IDEMPOTENT_RETRY_DELAYS_MS.length; attempt++) {
+            try {
+                const result = await this.#fetchAgentCardOnce(targetUrl);
+                if (result === null) {
+                    // Auth/missing — don't cache; signal to caller.
+                    this.#agentCardCache.delete(targetUrl);
+                    return null;
+                }
+                this.#agentCardCache.set(targetUrl, { card: result, fetchedAt: Date.now() });
+                return result;
+            }
+            catch (err) {
+                lastError = err;
+                if (err instanceof A2aClientError && err.code !== 'TRANSPORT_ERROR') {
+                    // HTTP-level error or schema-validation failure — authoritative;
+                    // don't retry.
+                    throw err;
+                }
+                // Transport error — back off + retry (if attempts remain).
+                if (attempt < IDEMPOTENT_RETRY_DELAYS_MS.length) {
+                    await new Promise((r) => setTimeout(r, IDEMPOTENT_RETRY_DELAYS_MS[attempt]));
+                }
+            }
+        }
+        // Exhausted retries — surface the last error.
+        throw lastError;
+    }
+    /** Diagnostic: count of cached AgentCard entries (testing aid). */
+    agentCardCacheSize() {
+        return this.#agentCardCache.size;
+    }
+    /** Manually invalidate a cached AgentCard (e.g., after detected target rotation). */
+    invalidateAgentCard(targetUrl) {
+        this.#agentCardCache.delete(targetUrl);
+    }
+    /**
+     * Close the underlying https.Agent. Call on channel-server shutdown to
+     * release pooled sockets cleanly.
+     */
+    close() {
+        this.#agent.destroy();
+        this.#agentCardCache.clear();
+    }
+    // -------------------------------------------------------------------------
+    // Private helpers
+    // -------------------------------------------------------------------------
+    /**
+     * Derive a span-attribute target handle from a target URL. Prefer the
+     * host:port pair; fall back to the bare URL if parsing fails.
+     */
+    #deriveTargetHandle(targetUrl) {
+        try {
+            const u = new URL(targetUrl);
+            return `${u.hostname}:${u.port}`;
+        }
+        catch {
+            return targetUrl;
+        }
+    }
+    /**
+     * Single AgentCard fetch attempt. Returns null on 404/401/403; throws
+     * on transport / 5xx / schema-validation failure.
+     */
+    async #fetchAgentCardOnce(targetUrl) {
+        const fullUrl = `${targetUrl}${AGENT_CARD_PATH}`;
+        const { status, body } = await this.#httpsGet(fullUrl);
+        if (status === 404 || status === 401 || status === 403) {
+            return null;
+        }
+        if (status >= 500) {
+            throw new A2aClientError('HTTP_ERROR', `AgentCard fetch returned HTTP ${status}`);
+        }
+        if (status !== 200) {
+            throw new A2aClientError('HTTP_ERROR', `AgentCard fetch returned unexpected HTTP ${status}`);
+        }
+        let parsed;
+        try {
+            parsed = JSON.parse(body);
+        }
+        catch (err) {
+            throw new A2aClientError('INVALID_AGENT_CARD', `AgentCard body is not valid JSON`, err);
+        }
+        const validated = AgentCardSchema.safeParse(parsed);
+        if (!validated.success) {
+            throw new A2aClientError('INVALID_AGENT_CARD', `AgentCard body fails schema validation: ${validated.error.message}`, validated.error);
+        }
+        return validated.data;
+    }
+    /**
+     * Issue a JSON-RPC POST. Returns the parsed response body on HTTP 200
+     * (whether success or error envelope — caller discriminates). Throws
+     * on transport / non-200 / non-JSON.
+     *
+     * Tracecontext is injected via `propagation.inject(context.active(),
+     * headers)` — picks up the active span (set by `sendMessage`'s tracer
+     * scope) and writes `traceparent` + `tracestate` headers.
+     */
+    async #postJsonRpc(url, envelope) {
+        const bodyStr = JSON.stringify(envelope);
+        const headers = {
+            'Content-Type': 'application/json',
+            'Content-Length': Buffer.byteLength(bodyStr).toString(),
+        };
+        propagation.inject(context.active(), headers);
+        const { status, body } = await this.#httpsSend(url, 'POST', headers, bodyStr);
+        if (status !== 200) {
+            throw new A2aClientError('HTTP_ERROR', `JSON-RPC POST returned HTTP ${status}: ${body.slice(0, 200)}`);
+        }
+        try {
+            return JSON.parse(body);
+        }
+        catch (err) {
+            throw new A2aClientError('INVALID_RESPONSE', `JSON-RPC response body is not valid JSON`, err);
+        }
+    }
+    /** Issue an HTTPS GET. */
+    async #httpsGet(url) {
+        const headers = {};
+        propagation.inject(context.active(), headers);
+        return this.#httpsSend(url, 'GET', headers, null);
+    }
+    /**
+     * Low-level HTTPS request with mTLS client cert + connection pooling.
+     * Returns `{ status, body }` on completion; rejects on transport error
+     * with `A2aClientError` `code: 'TRANSPORT_ERROR'`.
+     */
+    #httpsSend(url, method, headers, body) {
+        return new Promise((resolve, reject) => {
+            let parsedUrl;
+            try {
+                parsedUrl = new URL(url);
+            }
+            catch (err) {
+                reject(new A2aClientError('TRANSPORT_ERROR', `Invalid URL: ${url}`, err));
+                return;
+            }
+            const req = httpsRequest({
+                hostname: parsedUrl.hostname,
+                port: parsedUrl.port,
+                path: `${parsedUrl.pathname}${parsedUrl.search}`,
+                method,
+                headers,
+                cert: this.#config.mTlsClientCertPem,
+                key: this.#config.mTlsClientKeyPem,
+                ca: this.#config.caCertPem,
+                rejectUnauthorized: true,
+                // Same rationale as notify-peer.ts: channel-server certs use
+                // CN-based identity, not SAN-matched hostname.
+                checkServerIdentity: () => undefined,
+                agent: this.#agent,
+                timeout: this.#config.timeoutMs ?? DEFAULT_TIMEOUT_MS,
+            }, (res) => {
+                const chunks = [];
+                res.on('data', (c) => chunks.push(c));
+                res.on('end', () => {
+                    resolve({
+                        status: res.statusCode ?? 0,
+                        body: Buffer.concat(chunks).toString('utf-8'),
+                    });
+                });
+            });
+            req.on('error', (err) => {
+                reject(new A2aClientError('TRANSPORT_ERROR', err.message, err));
+            });
+            req.on('timeout', () => {
+                req.destroy();
+                reject(new A2aClientError('TRANSPORT_ERROR', 'request timeout'));
+            });
+            if (body !== null) {
+                req.write(body);
+            }
+            req.end();
+        });
+    }
+}
+//# sourceMappingURL=a2a-client.js.map

package/dist/a2a-client.js.map

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

package/dist/a2a-task.d.ts

@@ -0,0 +1,135 @@
+import type { Task, TaskState, Message } from './a2a-types.js';
+/** True iff `from → to` is a legal transition per the v1.0 spec table. */
+export declare function isTransitionAllowed(from: TaskState, to: TaskState): boolean;
+/** Error class for illegal state transitions. */
+export declare class InvalidTaskTransitionError extends Error {
+    readonly from: TaskState;
+    readonly to: TaskState;
+    readonly taskId: string;
+    readonly code = "INVALID_TASK_TRANSITION";
+    constructor(from: TaskState, to: TaskState, taskId: string);
+}
+/** Error class for resume attempts against unknown task ids (macf#392 Phase 2b). */
+export declare class TaskNotFoundError extends Error {
+    readonly taskId: string;
+    readonly code = "TASK_NOT_FOUND";
+    constructor(taskId: string);
+}
+/** Error class for resume attempts against non-resumable from-states (macf#392 Phase 2b). */
+export declare class TaskNotResumableError extends Error {
+    readonly taskId: string;
+    readonly currentState: TaskState;
+    readonly code = "TASK_NOT_RESUMABLE";
+    constructor(taskId: string, currentState: TaskState);
+}
+/** Error class for cancel attempts against terminal tasks (macf#398 Phase 2d). */
+export declare class TaskNotCancelableError extends Error {
+    readonly taskId: string;
+    readonly currentState: TaskState;
+    readonly code = "TASK_NOT_CANCELABLE";
+    constructor(taskId: string, currentState: TaskState);
+}
+/**
+ * In-memory task store. NOT durable across channel-server restarts;
+ * Phase 2.5 will revisit if longer-lived persistence becomes a need.
+ *
+ * Concurrency: single-threaded Node.js event loop; no locking needed
+ * between request handlers. Map operations are atomic per-event-loop-turn.
+ */
+export declare class TaskStore {
+    #private;
+    /**
+     * Create a fresh task in SUBMITTED state. Returns the task; caller
+     * is responsible for any subsequent transition.
+     *
+     * `contextId` is propagated from the inbound Message if present
+     * (per spec § 4.1.4 — contextId associates with a conversational
+     * group); otherwise undefined.
+     */
+    create(initialMessage: Message, opts: {
+        readonly nowIso: string;
+    }): Task;
+    /**
+     * Look up a task by ID. Used for resume flows (Message.taskId set)
+     * + idempotent retries. Returns `undefined` if no such task.
+     */
+    get(taskId: string): Task | undefined;
+    /**
+     * Apply a state transition. Validates against the spec table; throws
+     * `InvalidTaskTransitionError` on illegal moves. Returns the updated
+     * task (mutated in-place + immutable references returned for callers).
+     *
+     * Side effect: updates `task.status.state` + `task.status.timestamp`.
+     * `task.status.message` is set when the caller provides an
+     * accompanying message (e.g., agent's response).
+     */
+    transition(taskId: string, to: TaskState, opts: {
+        readonly nowIso: string;
+        readonly message?: Message;
+    }): Task;
+    /** True iff a task's current state is terminal. */
+    isTerminal(taskId: string): boolean;
+    /** Diagnostic: count of currently-tracked tasks. */
+    size(): number;
+    /**
+     * Phase 2a helper: drive a fresh task through the happy path
+     * SUBMITTED → WORKING → COMPLETED in one call. Returns the final
+     * task. Used by the inbound `message/send` route when the message
+     * is a non-resume submission with no intermediate-state needs.
+     *
+     * `responseMessage` is the agent's reply (role=ROLE_AGENT) attached
+     * to the COMPLETED status. Phase 2b will replace this with a real
+     * dispatch to MACF tooling that can return INPUT_REQUIRED.
+     */
+    completeHappyPath(initialMessage: Message, responseMessage: Message, opts: {
+        readonly nowIso: string;
+    }): Task;
+    /**
+     * Resume a task currently in INPUT_REQUIRED or AUTH_REQUIRED state
+     * (macf#392 Phase 2b). Validates ROLE_USER on the resume message
+     * (canonical client→server direction per spec § 4.1.5), the
+     * from-state is resumable, and transitions back to WORKING with
+     * the resume message appended to history.
+     *
+     * Errors:
+     * - `TaskNotFoundError` if `taskId` doesn't match any tracked task
+     * - `TaskNotResumableError` if from-state isn't INPUT_REQUIRED or AUTH_REQUIRED
+     * - `Error` (generic) if message.role !== 'ROLE_USER'
+     */
+    resume(taskId: string, resumeMessage: Message, opts: {
+        readonly nowIso: string;
+    }): Task;
+    /**
+     * Drive a fresh task to REJECTED state (macf#392 Phase 2b test
+     * fixture). SUBMITTED → REJECTED is a legal transition per the
+     * canonical proto table. Used by route handler test trigger when
+     * the inbound Message text matches a synthetic rejection pattern.
+     *
+     * NOT a production-policy rejection layer — real refusal logic
+     * comes in Phase 3+ when the skill-name → MCP-tool dispatcher
+     * needs to refuse certain inputs.
+     */
+    rejectFresh(initialMessage: Message, reason: Message, opts: {
+        readonly nowIso: string;
+    }): Task;
+    /**
+     * Cancel a non-terminal task (macf#398 Phase 2d). Cancellable from
+     * SUBMITTED / WORKING / INPUT_REQUIRED / AUTH_REQUIRED per the spec
+     * transition table; terminal tasks (COMPLETED / FAILED / CANCELED /
+     * REJECTED) reject with TaskNotCancelableError.
+     *
+     * Idempotent on already-CANCELED tasks would be ergonomic, but the
+     * spec doesn't mandate it + the transition table makes CANCELED a
+     * terminal state — so re-cancel returns the error. Callers can
+     * detect the terminal state via tasks/get first if they need to
+     * disambiguate.
+     *
+     * Errors:
+     * - `TaskNotFoundError` if `taskId` is unknown
+     * - `TaskNotCancelableError` if task is already terminal
+     */
+    cancel(taskId: string, opts: {
+        readonly nowIso: string;
+    }): Task;
+}
+//# sourceMappingURL=a2a-task.d.ts.map

package/dist/a2a-task.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"a2a-task.d.ts","sourceRoot":"","sources":["../src/a2a-task.ts"],"names":[],"mappings":"AAoBA,OAAO,KAAK,EAAE,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM,gBAAgB,CAAC;AAsD/D,0EAA0E;AAC1E,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,SAAS,EAAE,EAAE,EAAE,SAAS,GAAG,OAAO,CAE3E;AAED,iDAAiD;AACjD,qBAAa,0BAA2B,SAAQ,KAAK;aAGjC,IAAI,EAAE,SAAS;aACf,EAAE,EAAE,SAAS;aACb,MAAM,EAAE,MAAM;IAJhC,SAAgB,IAAI,6BAA6B;gBAE/B,IAAI,EAAE,SAAS,EACf,EAAE,EAAE,SAAS,EACb,MAAM,EAAE,MAAM;CAKjC;AAED,oFAAoF;AACpF,qBAAa,iBAAkB,SAAQ,KAAK;aAEd,MAAM,EAAE,MAAM;IAD1C,SAAgB,IAAI,oBAAoB;gBACZ,MAAM,EAAE,MAAM;CAI3C;AAED,6FAA6F;AAC7F,qBAAa,qBAAsB,SAAQ,KAAK;aAG5B,MAAM,EAAE,MAAM;aACd,YAAY,EAAE,SAAS;IAHzC,SAAgB,IAAI,wBAAwB;gBAE1B,MAAM,EAAE,MAAM,EACd,YAAY,EAAE,SAAS;CAK1C;AAED,kFAAkF;AAClF,qBAAa,sBAAuB,SAAQ,KAAK;aAG7B,MAAM,EAAE,MAAM;aACd,YAAY,EAAE,SAAS;IAHzC,SAAgB,IAAI,yBAAyB;gBAE3B,MAAM,EAAE,MAAM,EACd,YAAY,EAAE,SAAS;CAK1C;AAMD;;;;;;GAMG;AACH,qBAAa,SAAS;;IAGpB;;;;;;;OAOG;IACH,MAAM,CAAC,cAAc,EAAE,OAAO,EAAE,IAAI,EAAE;QAAE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI;IAexE;;;OAGG;IACH,GAAG,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS;IAIrC;;;;;;;;OAQG;IACH,UAAU,CACR,MAAM,EAAE,MAAM,EACd,EAAE,EAAE,SAAS,EACb,IAAI,EAAE;QAAE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAA;KAAE,GAC5D,IAAI;IA4BP,mDAAmD;IACnD,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO;IAMnC,oDAAoD;IACpD,IAAI,IAAI,MAAM;IAId;;;;;;;;;OASG;IACH,iBAAiB,CACf,cAAc,EAAE,OAAO,EACvB,eAAe,EAAE,OAAO,EACxB,IAAI,EAAE;QAAE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;KAAE,GAChC,IAAI;IASP;;;;;;;;;;;OAWG;IACH,MAAM,CACJ,MAAM,EAAE,MAAM,EACd,aAAa,EAAE,OAAO,EACtB,IAAI,EAAE;QAAE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;KAAE,GAChC,IAAI;IAmBP;;;;;;;;;OASG;IACH,WAAW,CACT,cAAc,EAAE,OAAO,EACvB,MAAM,EAAE,OAAO,EACf,IAAI,EAAE;QAAE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;KAAE,GAChC,IAAI;IAQP;;;;;;;;;;;;;;;OAeG;IACH,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE;QAAE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI;CAUhE"}