@atcn/adapter-a2a 1.5.0

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,86 @@
+# @atcn/adapter-a2a
+
+Connects [A2A](https://a2a-protocol.org) (Agent2Agent v1.0) agents to [ATCN](https://github.com/fadnisnikhil/atcn), so paid work handed from one agent to another ends up in a cost record that anyone can verify offline. ATCN only records: it never blocks, holds or releases money.
+
+What it gives each side:
+
+- **The agent doing the work** signs its task events as it goes (started, evidence submitted, completed) and can sign its estimate and how the task ended.
+- **The agent paying for it** turns A2A tasks into delegations, matches the worker's bills to them through a declared billing reference, and records estimates, signed outcomes and sub-tasks handed further down the chain.
+
+```bash
+npm install @atcn/adapter-a2a
+```
+
+## Signed task events
+
+The working agent runs the bridge on its own task stream:
+
+| A2A | ATCN |
+| --- | --- |
+| `TASK_STATE_WORKING` | `obligation.started` |
+| Artifact with `metadata.atcn` (`evidence_type`, `verifier`, `deliverable_ids`) | `evidence.submitted` |
+| `TASK_STATE_COMPLETED` | `completion.proposed` |
+| `FAILED`, `CANCELED`, `REJECTED` | Nothing signed on the obligation (only the issuer may cancel it); the bridge returns a `terminal` action naming the subledger claim to record (`provider_failure` or `cancellation`) |
+
+Every event is signed with the working agent's key. Clearing, payment and the task closure follow from those events.
+
+```ts
+import { StreamResponse } from "@a2a-js/sdk";
+import { A2AObligationBridge, localObligationClient, obligationIdFromMetadata } from "@atcn/adapter-a2a";
+
+// In the working agent's AgentExecutor:
+const obligationId = obligationIdFromMetadata(requestContext.userMessage.metadata);
+const bridge = new A2AObligationBridge({ client: localObligationClient(network), worker: signer, obligationId });
+await bridge.handle(StreamResponse.toJSON({ payload: { $case: "statusUpdate", value: statusUpdate } }));
+```
+
+`client` is either an `AtcnClient` from `@atcn/sdk` (hosted API) or `localObligationClient(network)` for the in-memory network from `@atcn/local-runner`, which needs no account. The bridge reads A2A wire JSON, so it works with any A2A SDK; with `@a2a-js/sdk`, `StreamResponse.toJSON` produces it.
+
+The delegating agent puts `obligationTaskMetadata(obligationId)` on the A2A message so the worker knows which obligation the task is for. `obligationTaskMetadata(obligationId, { skillId })` also names the AgentSkill it wants; the worker reads it with `skillIdFromMetadata`.
+
+Pass `execution` to describe the run in `obligation.started`, so attestations can cite exactly which run, agent version and skill they judged:
+
+```ts
+import { AgentCard } from "@a2a-js/sdk";
+
+const bridge = new A2AObligationBridge({
+  client,
+  worker: signer,
+  obligationId,
+  execution: { agentCard: AgentCard.toJSON(card), skillId: skillIdFromMetadata(metadata) ?? undefined },
+});
+```
+
+The run's `execution_id` is `a2a:<task id>`. It records the A2A task and context ids, the card's `version` and digest, and the skill (namespace `a2a`). Optional `model` and `configDigest` are recorded as given; the agent declares them itself. When the obligation's terms name a skill, the network refuses a run of any other skill. After `obligation.started`, `bridge.execution` holds the descriptor; an attestation cites it as `executionBinding(bridge.execution)` from `@atcn/schema`.
+
+## Billing reference
+
+An agent declares what its bills reference with the [billing-reference extension](https://github.com/fadnisnikhil/atcn/blob/main/docs/extensions/billing-ref-v1.md): `billingRefExtension({ billing_ref: "task_id", currency: "USD" })` goes in its Agent Card's `capabilities.extensions`. The buyer records the delegation with `delegationFromA2A({ card, task, currency })`, which takes `provider_job_ref` from that declaration, so the agent's charges match the delegation without a hand-written mapping. Pass `parentDelegationId` when an agent records a sub-task under its own delegation.
+
+## Estimates
+
+An agent can sign its own estimate and send it in task or artifact metadata: `signedEstimateMetadata(estimate, { keyId, privateKey })`. The buyer reads it with `estimateFromMetadata` and records it with `estimateEventFromA2A(estimate, { match, binding })`. With a key binding for the agent's `key_id` it is `provider_key_signed`; without one it is relayed unsigned. Estimates are records only: nothing is reserved and they never count toward net cost. See [ESTIMATES.md](https://github.com/fadnisnikhil/atcn/blob/main/docs/ESTIMATES.md).
+
+## Signed outcomes
+
+An agent signs how its task ended, over its A2A task id, its note and pointers to its evidence:
+
+```ts
+import { signedOutcomeMetadata, terminalClaimType } from "@atcn/adapter-a2a";
+
+// Agent side, on a failed task (the same works for "completion" or "partial_completion"):
+const metadata = signedOutcomeMetadata(
+  { type: terminalClaimType("TASK_STATE_FAILED"), task_id: taskId, occurred_at: new Date().toISOString(), note: "index unavailable; charge refunded", evidence: [] },
+  { keyId: "gamma-key", privateKey },
+);
+```
+
+The buyer reads it from the status update with `outcomeFromMetadata` and records `outcomeClaimFromA2A(outcome, { binding })` on the delegation whose `provider_job_ref` is the task id. The claim is `provider_key_signed` only when the buyer bound the agent's key; the closure verifier re-checks the signature offline (check `signed_claims`). A failed or cancelled delegation that is still billed raises `charge_after_cancellation` until a refund, credit or reversal nets it to zero. The [A2A example](https://github.com/fadnisnikhil/atcn/tree/main/examples/a2a-delegation) publishes the signing key in a card extension (`npm run demo:a2a -- --search-fails`).
+
+## Multi-hop lineage
+
+When an agent hands part of its task to another agent, `lineageMetadata(parentTask, agentName)` on the message that starts the sub-task carries the chain of tasks above it (`metadata.atcn.lineage`, root first; read it with `lineageFromMetadata`). The agent reports its sub-tasks back up with `downstreamMetadata(edges)`, each with the sub-agent's own signed outcome relayed unchanged. The buyer records every edge from `downstreamFromMetadata` as a child delegation (`childDelegationFromA2A(edge, { parentDelegationId, currency, providerId })`) and its outcome with `outcomeClaimFromA2A`. A sub-agent's signed outcome verifies against its own key even though the buyer never dealt with it. An edge that arrives with no outcome is a broken edge: record `brokenEdgeGap(edge, childDelegationId)` as a capture gap, and the closure shows lineage as incomplete with an `incomplete_lineage` exception.
+
+A runnable example with two A2A agents over HTTP is in [`examples/a2a-delegation`](https://github.com/fadnisnikhil/atcn/tree/main/examples/a2a-delegation).
+
+Part of [ATCN](https://github.com/fadnisnikhil/atcn). Apache-2.0.

package/dist/billing.d.ts

@@ -0,0 +1,63 @@
+import { type AgentCardExtension, type BillingRefParams } from "@atcn/schema";
+import type { A2AAgentCard, A2ATask } from "./types.js";
+/** The capabilities.extensions[] entry an agent adds to its Agent Card to declare what its bills reference. */
+export declare function billingRefExtension(params: BillingRefParams): AgentCardExtension;
+export interface DelegationFromA2AOptions {
+    card: A2AAgentCard;
+    task: Pick<A2ATask, "id" | "contextId" | "metadata">;
+    currency: string;
+    externalRef?: string;
+    /** The AgentSkill id the task performs; recorded in the delegation's run descriptor. */
+    skillId?: string;
+    /** The agent's ATCN agent id when it has one; otherwise the card's name identifies it. */
+    agentId?: string;
+    /** Used only when the card declares no billing-reference extension (today's hand mapping). */
+    fallbackProviderJobRef?: string | null;
+    /** The buyer's delegation this task was sent under, when an agent delegates further and records its own sub-task. */
+    parentDelegationId?: string;
+}
+/**
+ * A subledger delegation body for work sent to an A2A agent: provider_job_ref comes from the card's declared
+ * billing reference, and the run descriptor records the card's digest. Pass it to createDelegation (hosted API, SDK
+ * or local runner). An agent without the extension falls back to `fallbackProviderJobRef`.
+ */
+export declare function delegationFromA2A(options: DelegationFromA2AOptions): Record<string, unknown>;
+/** An agent's own estimate, as it travels in task or artifact metadata under metadata.atcn.estimate. */
+export interface A2AEstimate {
+    source: string;
+    source_event_id: string;
+    amount_minor: number;
+    currency: string;
+    issued_at: string;
+    basis: string | null;
+    expires_at: string | null;
+    supersedes: string | null;
+    source_ref: string | null;
+    /** The agent's signing key and its signature over the expectation statement; absent for an unsigned estimate. */
+    key_id?: string;
+    signature?: string;
+}
+/**
+ * Agent side: metadata carrying a signed estimate. The agent signs with its own key; the buyer binds that key to
+ * the agent's provider record and records the estimate as provider_key_signed. Record only: nothing is reserved.
+ */
+export declare function signedEstimateMetadata(estimate: Omit<A2AEstimate, "key_id" | "signature">, signing: {
+    keyId: string;
+    privateKey: string;
+}): Record<string, unknown>;
+/** The estimate in metadata.atcn.estimate, or null when there is none. */
+export declare function estimateFromMetadata(metadata: Record<string, unknown> | undefined): A2AEstimate | null;
+/**
+ * Buyer side: the financial event body for an agent's estimate, matched like a charge (usually by the delegation's
+ * provider_job_ref). A signed
+ * estimate needs the buyer's provider_id and key binding for the agent's key_id; without them the agent's estimate is
+ * relayed unsigned and stays buyer_recorded, so a signature by a key the buyer has not bound is never claimed.
+ */
+export declare function estimateEventFromA2A(estimate: A2AEstimate, options: {
+    match: Record<string, string>;
+    binding?: {
+        provider_id: string;
+        binding_id: string;
+        key_id: string;
+    };
+}): Record<string, unknown>;

package/dist/billing.js

@@ -0,0 +1,81 @@
+import { BILLING_REF_EXTENSION_URI, BillingRefParamsSchema, digestOf, providerJobRefFor, } from "@atcn/schema";
+import { buildExpectationStatement, signExpectation } from "@atcn/sdk";
+import { A2A_SKILL_NAMESPACE, ATCN_METADATA_KEY } from "./bridge.js";
+/** The capabilities.extensions[] entry an agent adds to its Agent Card to declare what its bills reference. */
+export function billingRefExtension(params) {
+    return {
+        uri: BILLING_REF_EXTENSION_URI,
+        description: "Bills reference this value; buyers match charges to the delegated task by it",
+        required: false,
+        params: BillingRefParamsSchema.parse(params),
+    };
+}
+/**
+ * A subledger delegation body for work sent to an A2A agent: provider_job_ref comes from the card's declared
+ * billing reference, and the run descriptor records the card's digest. Pass it to createDelegation (hosted API, SDK
+ * or local runner). An agent without the extension falls back to `fallbackProviderJobRef`.
+ */
+export function delegationFromA2A(options) {
+    const { card, task } = options;
+    const execution = {
+        execution_id: `a2a:${task.id}`,
+        protocol: { name: "a2a", task_id: task.id, ...(task.contextId ? { context_id: task.contextId } : {}) },
+        agent: { agent_id: options.agentId ?? card.name, agent_version: card.version, card_digest: digestOf(JSON.parse(JSON.stringify(card))) },
+        ...(options.skillId ? { skill: { namespace: A2A_SKILL_NAMESPACE, skill_id: options.skillId } } : {}),
+    };
+    return {
+        ...(options.externalRef ? { external_ref: options.externalRef } : {}),
+        ...(options.parentDelegationId ? { parent_delegation_id: options.parentDelegationId } : {}),
+        provider_name_stated: card.name,
+        provider_job_ref: providerJobRefFor(card, task) ?? options.fallbackProviderJobRef ?? null,
+        currency: options.currency,
+        execution,
+    };
+}
+/**
+ * Agent side: metadata carrying a signed estimate. The agent signs with its own key; the buyer binds that key to
+ * the agent's provider record and records the estimate as provider_key_signed. Record only: nothing is reserved.
+ */
+export function signedEstimateMetadata(estimate, signing) {
+    const statement = buildExpectationStatement({
+        type: "estimate",
+        source: estimate.source,
+        source_event_id: estimate.source_event_id,
+        amount_minor: estimate.amount_minor,
+        currency: estimate.currency,
+        issued_at: estimate.issued_at,
+        expectation: { issued_by: "agent", source_ref: estimate.source_ref, basis: estimate.basis, expires_at: estimate.expires_at, supersedes: estimate.supersedes },
+    });
+    return { [ATCN_METADATA_KEY]: { estimate: { ...estimate, issued_at: statement.issued_at, expires_at: statement.expires_at, key_id: signing.keyId, signature: signExpectation(statement, signing.privateKey) } } };
+}
+/** The estimate in metadata.atcn.estimate, or null when there is none. */
+export function estimateFromMetadata(metadata) {
+    const value = metadata?.[ATCN_METADATA_KEY]?.estimate;
+    return value && typeof value.amount_minor === "number" && typeof value.source_event_id === "string" ? value : null;
+}
+/**
+ * Buyer side: the financial event body for an agent's estimate, matched like a charge (usually by the delegation's
+ * provider_job_ref). A signed
+ * estimate needs the buyer's provider_id and key binding for the agent's key_id; without them the agent's estimate is
+ * relayed unsigned and stays buyer_recorded, so a signature by a key the buyer has not bound is never claimed.
+ */
+export function estimateEventFromA2A(estimate, options) {
+    const signed = estimate.signature !== undefined && options.binding !== undefined && options.binding.key_id === estimate.key_id;
+    return {
+        type: "estimate",
+        source: estimate.source,
+        source_event_id: estimate.source_event_id,
+        amount_minor: estimate.amount_minor,
+        currency: estimate.currency,
+        event_date: estimate.issued_at,
+        match: options.match,
+        expectation: {
+            issued_by: "agent",
+            source_ref: estimate.source_ref,
+            basis: estimate.basis,
+            expires_at: estimate.expires_at,
+            supersedes: estimate.supersedes,
+            ...(signed ? { signer: { provider_id: options.binding.provider_id, binding_id: options.binding.binding_id, key_id: options.binding.key_id, value: estimate.signature } } : {}),
+        },
+    };
+}

package/dist/bridge.d.ts

@@ -0,0 +1,117 @@
+import { type ExecutionDescriptor, type SignedEvent } from "@atcn/schema";
+import { type EventSigner } from "@atcn/sdk";
+import type { A2AAgentCard, A2AStreamResponse, A2ATaskState } from "./types.js";
+/** Metadata namespace the bridge reads on A2A messages, tasks and artifacts. */
+export declare const ATCN_METADATA_KEY = "atcn";
+/** SkillRef namespace for A2A: the skill_id is an AgentSkill id from the worker's agent card. */
+export declare const A2A_SKILL_NAMESPACE = "a2a";
+/**
+ * Evidence id derived from the obligation, the artifact id and the artifact's content digest. Every task snapshot
+ * (tasks/get returns all artifacts each time) yields the same id for the same artifact, so it is recorded once.
+ */
+export declare function artifactEvidenceId(obligationId: string, artifactId: string, contentDigest: string): string;
+/** Metadata a delegating agent attaches to the A2A message (or task) it sends for an ATCN obligation. */
+export declare function obligationTaskMetadata(obligationId: string, options?: {
+    skillId?: string;
+}): Record<string, unknown>;
+/** The obligation id written by obligationTaskMetadata, or null when the metadata carries none. */
+export declare function obligationIdFromMetadata(metadata: Record<string, unknown> | undefined): string | null;
+/** The skill id written by obligationTaskMetadata, or null when the metadata names none. */
+export declare function skillIdFromMetadata(metadata: Record<string, unknown> | undefined): string | null;
+/**
+ * Artifact metadata marking an artifact as ATCN evidence. url parts must carry content_digest,
+ * because ATCN verifies digests of bytes the producer actually held.
+ */
+export interface ArtifactEvidenceMetadata {
+    evidence_type: string;
+    verifier: string;
+    /** Every verifier that may read the evidence, when more than one does (an agent_trace for agent_trace and usage_cost). Defaults to [verifier]. */
+    verifiers?: string[];
+    deliverable_ids: string[];
+    content_digest?: string;
+}
+/** The calls the bridge makes. `AtcnClient` from @atcn/sdk has them; localObligationClient adapts the local runner. */
+export interface ObligationClient {
+    getObligation(obligationId: string): Promise<unknown>;
+    appendEvent(obligationId: string, signed: SignedEvent): Promise<unknown>;
+    uploadBlob(bytes: Uint8Array, mediaType?: string): Promise<{
+        uri: string;
+    }>;
+    submitEvidence(obligationId: string, signed: SignedEvent): Promise<unknown>;
+}
+/** The parts of the local runner's `LocalNetwork` (@atcn/local-runner) the bridge uses. */
+export interface LocalNetworkLike {
+    obligation(obligationId: string): {
+        state: string;
+    };
+    appendLifecycleEvent(body: unknown): unknown;
+    uploadBlob(content: Uint8Array): string;
+    submitEvidence(body: unknown): unknown;
+}
+/** Lets the bridge write to the local runner's in-memory network instead of the hosted API. */
+export declare function localObligationClient(network: LocalNetworkLike): ObligationClient;
+export type BridgeAction = {
+    kind: "event";
+    eventType: "obligation.started" | "completion.proposed";
+    eventId: string;
+} | {
+    kind: "evidence";
+    artifactId: string;
+    evidenceId: string;
+}
+/** The task ended undelivered. Record `claimType` on the buyer's delegation (see outcomeClaimFromA2A); the issuer may cancel the obligation. */
+ | {
+    kind: "terminal";
+    state: A2ATaskState;
+    claimType: "provider_failure" | "cancellation";
+    taskId: string;
+} | {
+    kind: "skipped";
+    detail: string;
+};
+export interface BridgeOptions {
+    client: ObligationClient;
+    /** Signer for the remote (working) agent, i.e. the obligation's counterparty. */
+    worker: EventSigner;
+    obligationId: string;
+    /**
+     * Describes the run in obligation.started, so attestations can cite it: the A2A task and context ids, the agent
+     * card's version and digest, and the skill. Without it, obligation.started carries no run.
+     */
+    execution?: {
+        agentCard: A2AAgentCard;
+        agentCardUrl?: string;
+        skillId?: string;
+        model?: {
+            provider: string;
+            name: string;
+            version: string;
+        };
+        configDigest?: string;
+    };
+    /**
+     * Evidence ids the obligation already holds (for example from listEvidence), so a bridge restarted mid-task skips
+     * them. Without it, the service refuses the repeated id ("evidence_id already registered") and records nothing twice.
+     */
+    submittedEvidenceIds?: string[];
+}
+/**
+ * Translates an A2A task stream from the worker's side into ATCN signed events:
+ * WORKING -> obligation.started, evidence-tagged artifacts -> evidence.submitted,
+ * COMPLETED -> completion.proposed. Terminal FAILED/CANCELED/REJECTED states sign nothing on the obligation (only the
+ * issuer may cancel it); they come back as "terminal" actions naming the subledger claim to record.
+ */
+export declare class A2AObligationBridge {
+    private readonly options;
+    private started;
+    private completed;
+    private readonly pendingChunks;
+    private readonly submittedEvidenceIds;
+    /** The run this bridge declared in obligation.started, once it has. */
+    execution: ExecutionDescriptor | null;
+    constructor(options: BridgeOptions);
+    handle(response: A2AStreamResponse): Promise<BridgeAction[]>;
+    private onState;
+    private describeRun;
+    private onArtifact;
+}

package/dist/bridge.js

@@ -0,0 +1,196 @@
+import { createHash } from "node:crypto";
+import { digestOf, sha256Digest } from "@atcn/schema";
+import { buildEvidenceEnvelope } from "@atcn/sdk";
+/** Metadata namespace the bridge reads on A2A messages, tasks and artifacts. */
+export const ATCN_METADATA_KEY = "atcn";
+/** SkillRef namespace for A2A: the skill_id is an AgentSkill id from the worker's agent card. */
+export const A2A_SKILL_NAMESPACE = "a2a";
+const CROCKFORD = "0123456789ABCDEFGHJKMNPQRSTVWXYZ";
+/**
+ * Evidence id derived from the obligation, the artifact id and the artifact's content digest. Every task snapshot
+ * (tasks/get returns all artifacts each time) yields the same id for the same artifact, so it is recorded once.
+ */
+export function artifactEvidenceId(obligationId, artifactId, contentDigest) {
+    const hash = createHash("sha256").update(`${obligationId}\n${artifactId}\n${contentDigest}`).digest();
+    let body = "";
+    for (let i = 0; i < 26; i++)
+        body += CROCKFORD[hash[i] % 32];
+    return `evd_${body}`;
+}
+/** Metadata a delegating agent attaches to the A2A message (or task) it sends for an ATCN obligation. */
+export function obligationTaskMetadata(obligationId, options = {}) {
+    return { [ATCN_METADATA_KEY]: { obligation_id: obligationId, ...(options.skillId ? { skill_id: options.skillId } : {}) } };
+}
+/** The obligation id written by obligationTaskMetadata, or null when the metadata carries none. */
+export function obligationIdFromMetadata(metadata) {
+    const value = metadata?.[ATCN_METADATA_KEY];
+    return typeof value?.obligation_id === "string" ? value.obligation_id : null;
+}
+/** The skill id written by obligationTaskMetadata, or null when the metadata names none. */
+export function skillIdFromMetadata(metadata) {
+    const value = metadata?.[ATCN_METADATA_KEY];
+    return typeof value?.skill_id === "string" ? value.skill_id : null;
+}
+/** Lets the bridge write to the local runner's in-memory network instead of the hosted API. */
+export function localObligationClient(network) {
+    return {
+        getObligation: async (obligationId) => network.obligation(obligationId),
+        appendEvent: async (_obligationId, signed) => network.appendLifecycleEvent(signed),
+        uploadBlob: async (bytes) => ({ uri: network.uploadBlob(bytes) }),
+        submitEvidence: async (_obligationId, signed) => network.submitEvidence(signed),
+    };
+}
+/**
+ * Translates an A2A task stream from the worker's side into ATCN signed events:
+ * WORKING -> obligation.started, evidence-tagged artifacts -> evidence.submitted,
+ * COMPLETED -> completion.proposed. Terminal FAILED/CANCELED/REJECTED states sign nothing on the obligation (only the
+ * issuer may cancel it); they come back as "terminal" actions naming the subledger claim to record.
+ */
+export class A2AObligationBridge {
+    options;
+    started = false;
+    completed = false;
+    pendingChunks = new Map();
+    submittedEvidenceIds;
+    /** The run this bridge declared in obligation.started, once it has. */
+    execution = null;
+    constructor(options) {
+        this.options = options;
+        this.submittedEvidenceIds = new Set(options.submittedEvidenceIds ?? []);
+    }
+    async handle(response) {
+        if ("task" in response) {
+            const actions = await this.onState(response.task.status.state, response.task.id, response.task.contextId);
+            for (const artifact of response.task.artifacts ?? [])
+                actions.push(await this.onArtifact(artifact));
+            return actions;
+        }
+        if ("statusUpdate" in response)
+            return this.onState(response.statusUpdate.status.state, response.statusUpdate.taskId, response.statusUpdate.contextId);
+        if ("artifactUpdate" in response) {
+            const update = response.artifactUpdate;
+            const previous = update.append ? (this.pendingChunks.get(update.artifact.artifactId) ?? []) : [];
+            const parts = appendParts(previous, update.artifact.parts);
+            if (update.lastChunk === false) {
+                this.pendingChunks.set(update.artifact.artifactId, parts);
+                return [];
+            }
+            this.pendingChunks.delete(update.artifact.artifactId);
+            return [await this.onArtifact({ ...update.artifact, parts })];
+        }
+        return [];
+    }
+    async onState(state, taskId, contextId) {
+        const { client, worker, obligationId } = this.options;
+        const actions = [];
+        if ((state === "TASK_STATE_WORKING" || state === "TASK_STATE_COMPLETED") && !this.started) {
+            const current = (await client.getObligation(obligationId));
+            if (current.state === "accepted") {
+                const execution = this.describeRun(taskId, contextId);
+                const signed = worker.sign("obligation.started", obligationId, execution ? { execution } : {});
+                await client.appendEvent(obligationId, signed);
+                this.execution = execution;
+                actions.push({ kind: "event", eventType: "obligation.started", eventId: signed.payload.event_id });
+            }
+            this.started = true;
+        }
+        if (state === "TASK_STATE_COMPLETED" && !this.completed) {
+            const signed = worker.sign("completion.proposed", obligationId, { note: "A2A task completed" });
+            await client.appendEvent(obligationId, signed);
+            this.completed = true;
+            actions.push({ kind: "event", eventType: "completion.proposed", eventId: signed.payload.event_id });
+        }
+        if (state === "TASK_STATE_FAILED" || state === "TASK_STATE_CANCELED" || state === "TASK_STATE_REJECTED") {
+            actions.push({ kind: "terminal", state, claimType: state === "TASK_STATE_FAILED" ? "provider_failure" : "cancellation", taskId });
+        }
+        return actions;
+    }
+    describeRun(taskId, contextId) {
+        const options = this.options.execution;
+        if (!options)
+            return null;
+        return {
+            execution_id: `a2a:${taskId}`,
+            protocol: { name: "a2a", task_id: taskId, ...(contextId ? { context_id: contextId } : {}) },
+            agent: {
+                agent_id: this.options.worker.actorId,
+                agent_version: options.agentCard.version,
+                card_digest: digestOf(JSON.parse(JSON.stringify(options.agentCard))),
+                ...(options.model ? { model: options.model } : {}),
+                ...(options.configDigest ? { config_digest: options.configDigest } : {}),
+            },
+            ...(options.skillId
+                ? { skill: { namespace: A2A_SKILL_NAMESPACE, skill_id: options.skillId, ...(options.agentCardUrl ? { agent_card_url: options.agentCardUrl } : {}) } }
+                : {}),
+        };
+    }
+    async onArtifact(artifact) {
+        const meta = artifact.metadata?.[ATCN_METADATA_KEY];
+        if (!meta)
+            return { kind: "skipped", detail: `artifact ${artifact.artifactId} has no ${ATCN_METADATA_KEY} evidence metadata` };
+        const { client, worker, obligationId } = this.options;
+        const part = artifact.parts[0];
+        if (!part || artifact.parts.length !== 1)
+            return { kind: "skipped", detail: `artifact ${artifact.artifactId} must have exactly one part to be evidence` };
+        if (part.url !== undefined && !meta.content_digest)
+            return { kind: "skipped", detail: `url artifact ${artifact.artifactId} needs metadata.atcn.content_digest` };
+        const bytes = part.url === undefined ? partBytes(part) : null;
+        const contentDigest = bytes ? sha256Digest(bytes) : meta.content_digest;
+        const evidenceId = artifactEvidenceId(obligationId, artifact.artifactId, contentDigest);
+        if (this.submittedEvidenceIds.has(evidenceId))
+            return { kind: "skipped", detail: `artifact ${artifact.artifactId} was already submitted as ${evidenceId}` };
+        let envelope;
+        if (part.url !== undefined) {
+            envelope = {
+                ...buildEvidenceEnvelope({
+                    evidenceType: meta.evidence_type,
+                    producerId: worker.actorId,
+                    content: "",
+                    uri: part.url,
+                    retrievalMethod: "https",
+                    mediaType: part.mediaType ?? "application/octet-stream",
+                    verifiers: meta.verifiers ?? [meta.verifier],
+                    deliverableIds: meta.deliverable_ids,
+                }),
+                content_digest: contentDigest,
+            };
+        }
+        else {
+            const mediaType = part.mediaType ?? (part.data !== undefined ? "application/json" : "text/plain");
+            const blob = await client.uploadBlob(bytes, mediaType);
+            envelope = buildEvidenceEnvelope({
+                evidenceType: meta.evidence_type,
+                producerId: worker.actorId,
+                content: bytes,
+                uri: blob.uri,
+                retrievalMethod: "atcn-blob",
+                mediaType,
+                verifiers: meta.verifiers ?? [meta.verifier],
+                deliverableIds: meta.deliverable_ids,
+            });
+        }
+        envelope = { ...envelope, evidence_id: evidenceId };
+        await client.submitEvidence(obligationId, worker.sign("evidence.submitted", obligationId, { envelope }));
+        this.submittedEvidenceIds.add(evidenceId);
+        return { kind: "evidence", artifactId: artifact.artifactId, evidenceId };
+    }
+}
+/** Streamed text chunks continue the previous text part; other parts are kept as they are. */
+function appendParts(previous, next) {
+    const result = [...previous];
+    for (const part of next) {
+        const last = result.at(-1);
+        if (last?.text !== undefined && part.text !== undefined)
+            result[result.length - 1] = { ...last, text: last.text + part.text };
+        else
+            result.push(part);
+    }
+    return result;
+}
+function partBytes(part) {
+    if (part.raw !== undefined)
+        return new Uint8Array(Buffer.from(part.raw, "base64"));
+    if (part.text !== undefined)
+        return new TextEncoder().encode(part.text);
+    return new TextEncoder().encode(JSON.stringify(part.data ?? null));
+}

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export { A2A_SKILL_NAMESPACE, A2AObligationBridge, ATCN_METADATA_KEY, artifactEvidenceId, localObligationClient, obligationIdFromMetadata, obligationTaskMetadata, skillIdFromMetadata, type ArtifactEvidenceMetadata, type BridgeAction, type BridgeOptions, type LocalNetworkLike, type ObligationClient, } from "./bridge.js";
+export { billingRefExtension, delegationFromA2A, estimateEventFromA2A, estimateFromMetadata, signedEstimateMetadata, type A2AEstimate, type DelegationFromA2AOptions, } from "./billing.js";
+export { TERMINAL_CLAIM_BY_STATE, outcomeClaimFromA2A, outcomeFromMetadata, signOutcome, signedOutcomeMetadata, terminalClaimType, type A2AOutcome, } from "./outcome.js";
+export { brokenEdgeGap, childDelegationFromA2A, downstreamFromMetadata, downstreamMetadata, lineageFromMetadata, lineageMetadata, type A2ADownstreamEdge, type A2ALineageHop, } from "./lineage.js";
+export { BILLING_REF_EXTENSION_URI, billingRefFromAgentCard, providerJobRefFor, statedSkillPrice, type BillingRef, type BillingRefParams } from "@atcn/schema";
+export type * from "./types.js";

package/dist/index.js

@@ -0,0 +1,5 @@
+export { A2A_SKILL_NAMESPACE, A2AObligationBridge, ATCN_METADATA_KEY, artifactEvidenceId, localObligationClient, obligationIdFromMetadata, obligationTaskMetadata, skillIdFromMetadata, } from "./bridge.js";
+export { billingRefExtension, delegationFromA2A, estimateEventFromA2A, estimateFromMetadata, signedEstimateMetadata, } from "./billing.js";
+export { TERMINAL_CLAIM_BY_STATE, outcomeClaimFromA2A, outcomeFromMetadata, signOutcome, signedOutcomeMetadata, terminalClaimType, } from "./outcome.js";
+export { brokenEdgeGap, childDelegationFromA2A, downstreamFromMetadata, downstreamMetadata, lineageFromMetadata, lineageMetadata, } from "./lineage.js";
+export { BILLING_REF_EXTENSION_URI, billingRefFromAgentCard, providerJobRefFor, statedSkillPrice } from "@atcn/schema";

package/dist/lineage.d.ts

@@ -0,0 +1,48 @@
+import type { A2AOutcome } from "./outcome.js";
+import type { A2ATask } from "./types.js";
+/**
+ * Multi-hop lineage over A2A. When an agent delegates part of its task to another agent, the message that starts the
+ * sub-task carries the chain of tasks above it (metadata.atcn.lineage), and the agent reports its sub-tasks back up
+ * (metadata.atcn.downstream) with each sub-agent's outcome relayed unchanged. The buyer records every reported sub-task
+ * as a child delegation; a sub-agent's signed outcome verifies against its own key even though the buyer never dealt
+ * with it, and a sub-task with no outcome is recorded as a broken edge (a capture gap) rather than silently dropped.
+ */
+/** One hop of the chain: a task an agent was working on when it delegated further. */
+export interface A2ALineageHop {
+    task_id: string;
+    context_id: string | null;
+    agent: string;
+}
+/** The chain in metadata.atcn.lineage, root first; empty when there is none. */
+export declare function lineageFromMetadata(metadata: Record<string, unknown> | undefined): A2ALineageHop[];
+/**
+ * Delegating agent's side: metadata for the message that starts a sub-task. The chain is the one the agent's own task
+ * arrived with, plus its own task.
+ */
+export declare function lineageMetadata(parentTask: Pick<A2ATask, "id" | "contextId" | "metadata">, agent: string): Record<string, unknown>;
+/** A sub-task an agent delegated, as it reports it upstream. outcome is the sub-agent's own (signed) outcome, or null when none arrived. */
+export interface A2ADownstreamEdge {
+    agent: string;
+    task_id: string;
+    context_id: string | null;
+    outcome: A2AOutcome | null;
+}
+/** Delegating agent's side: task or status metadata reporting its sub-tasks. */
+export declare function downstreamMetadata(edges: A2ADownstreamEdge[]): Record<string, unknown>;
+/** The sub-tasks in metadata.atcn.downstream; empty when there are none. */
+export declare function downstreamFromMetadata(metadata: Record<string, unknown> | undefined): A2ADownstreamEdge[];
+/**
+ * Buyer side: the child delegation body for a reported sub-task, under the delegation of the agent that reported it.
+ * Pass providerId when the sub-agent is a known provider with a bound key, so its signed outcome counts.
+ */
+export declare function childDelegationFromA2A(edge: A2ADownstreamEdge, options: {
+    parentDelegationId: string;
+    currency: string;
+    providerId?: string;
+}): Record<string, unknown>;
+/** Buyer side: the capture gap body for a sub-task that reported no outcome. */
+export declare function brokenEdgeGap(edge: A2ADownstreamEdge, childDelegationId: string): {
+    delegation_id: string;
+    kind: "broken_edge";
+    detail: string;
+};

package/dist/lineage.js

@@ -0,0 +1,44 @@
+import { ATCN_METADATA_KEY } from "./bridge.js";
+/** The chain in metadata.atcn.lineage, root first; empty when there is none. */
+export function lineageFromMetadata(metadata) {
+    const value = metadata?.[ATCN_METADATA_KEY]?.lineage;
+    if (!Array.isArray(value))
+        return [];
+    return value.filter((hop) => typeof hop?.task_id === "string" && typeof hop?.agent === "string");
+}
+/**
+ * Delegating agent's side: metadata for the message that starts a sub-task. The chain is the one the agent's own task
+ * arrived with, plus its own task.
+ */
+export function lineageMetadata(parentTask, agent) {
+    const hop = { task_id: parentTask.id, context_id: parentTask.contextId ?? null, agent };
+    return { [ATCN_METADATA_KEY]: { lineage: [...lineageFromMetadata(parentTask.metadata), hop] } };
+}
+/** Delegating agent's side: task or status metadata reporting its sub-tasks. */
+export function downstreamMetadata(edges) {
+    return { [ATCN_METADATA_KEY]: { downstream: edges } };
+}
+/** The sub-tasks in metadata.atcn.downstream; empty when there are none. */
+export function downstreamFromMetadata(metadata) {
+    const value = metadata?.[ATCN_METADATA_KEY]?.downstream;
+    if (!Array.isArray(value))
+        return [];
+    return value.filter((edge) => typeof edge?.task_id === "string" && typeof edge?.agent === "string");
+}
+/**
+ * Buyer side: the child delegation body for a reported sub-task, under the delegation of the agent that reported it.
+ * Pass providerId when the sub-agent is a known provider with a bound key, so its signed outcome counts.
+ */
+export function childDelegationFromA2A(edge, options) {
+    return {
+        parent_delegation_id: options.parentDelegationId,
+        ...(options.providerId ? { provider_id: options.providerId } : {}),
+        provider_name_stated: edge.agent,
+        provider_job_ref: edge.task_id,
+        currency: options.currency,
+    };
+}
+/** Buyer side: the capture gap body for a sub-task that reported no outcome. */
+export function brokenEdgeGap(edge, childDelegationId) {
+    return { delegation_id: childDelegationId, kind: "broken_edge", detail: `${edge.agent} task ${edge.task_id} reported no outcome` };
+}

package/dist/outcome.d.ts

@@ -0,0 +1,47 @@
+import { type EvidenceRef, type SignedClaimType } from "@atcn/sdk";
+import type { A2ATaskState } from "./types.js";
+/** A2A terminal states where the work ended undelivered, and the subledger claim each one becomes. */
+export declare const TERMINAL_CLAIM_BY_STATE: Partial<Record<A2ATaskState, "provider_failure" | "cancellation">>;
+/** The subledger claim type for an A2A task that ended undelivered; throws for any other state. */
+export declare function terminalClaimType(state: A2ATaskState): "provider_failure" | "cancellation";
+/**
+ * An agent's statement of how its A2A task ended, as it travels under metadata.atcn.outcome: completed, partly
+ * completed, cancelled or failed, with pointers to its evidence.
+ */
+export interface A2AOutcome {
+    type: SignedClaimType;
+    task_id: string;
+    occurred_at: string;
+    note: string | null;
+    evidence: EvidenceRef[];
+    /** The agent's signing key and its signature over the outcome statement; absent when unsigned. */
+    key_id?: string;
+    signature?: string;
+}
+/** Agent side: the outcome with the agent's signature over the A2A task id, note and evidence. */
+export declare function signOutcome(outcome: Omit<A2AOutcome, "key_id" | "signature">, signing: {
+    keyId: string;
+    privateKey: string;
+}): A2AOutcome;
+/**
+ * Agent side: task or status metadata carrying a signed outcome. The buyer binds the agent's key to its provider
+ * record and records the claim as provider_key_signed.
+ */
+export declare function signedOutcomeMetadata(outcome: Omit<A2AOutcome, "key_id" | "signature">, signing: {
+    keyId: string;
+    privateKey: string;
+}): Record<string, unknown>;
+/** The outcome in metadata.atcn.outcome, or null when there is none. */
+export declare function outcomeFromMetadata(metadata: Record<string, unknown> | undefined): A2AOutcome | null;
+/**
+ * Buyer side: the delivery claim body for an agent's outcome. Record it on the delegation whose provider_job_ref is
+ * the task id. A signature counts only with the buyer's key binding for the agent's key_id; otherwise the claim is
+ * relayed unsigned and stays buyer_recorded.
+ */
+export declare function outcomeClaimFromA2A(outcome: A2AOutcome, options?: {
+    binding?: {
+        provider_id: string;
+        binding_id: string;
+        key_id: string;
+    };
+}): Record<string, unknown>;

package/dist/outcome.js

@@ -0,0 +1,49 @@
+import { buildOutcomeStatement, signOutcomeStatement } from "@atcn/sdk";
+import { ATCN_METADATA_KEY } from "./bridge.js";
+/** A2A terminal states where the work ended undelivered, and the subledger claim each one becomes. */
+export const TERMINAL_CLAIM_BY_STATE = {
+    TASK_STATE_FAILED: "provider_failure",
+    TASK_STATE_CANCELED: "cancellation",
+    TASK_STATE_REJECTED: "cancellation",
+};
+/** The subledger claim type for an A2A task that ended undelivered; throws for any other state. */
+export function terminalClaimType(state) {
+    const type = TERMINAL_CLAIM_BY_STATE[state];
+    if (!type)
+        throw new Error(`${state} is not a terminal non-success A2A state; use TASK_STATE_FAILED, TASK_STATE_CANCELED or TASK_STATE_REJECTED`);
+    return type;
+}
+/** Agent side: the outcome with the agent's signature over the A2A task id, note and evidence. */
+export function signOutcome(outcome, signing) {
+    const statement = buildOutcomeStatement({ type: outcome.type, provider_job_ref: outcome.task_id, occurred_at: outcome.occurred_at, note: outcome.note, evidence: outcome.evidence });
+    return { ...outcome, occurred_at: statement.occurred_at, key_id: signing.keyId, signature: signOutcomeStatement(statement, signing.privateKey) };
+}
+/**
+ * Agent side: task or status metadata carrying a signed outcome. The buyer binds the agent's key to its provider
+ * record and records the claim as provider_key_signed.
+ */
+export function signedOutcomeMetadata(outcome, signing) {
+    return { [ATCN_METADATA_KEY]: { outcome: signOutcome(outcome, signing) } };
+}
+/** The outcome in metadata.atcn.outcome, or null when there is none. */
+export function outcomeFromMetadata(metadata) {
+    const value = metadata?.[ATCN_METADATA_KEY]?.outcome;
+    return value && typeof value.task_id === "string" && typeof value.type === "string" ? value : null;
+}
+/**
+ * Buyer side: the delivery claim body for an agent's outcome. Record it on the delegation whose provider_job_ref is
+ * the task id. A signature counts only with the buyer's key binding for the agent's key_id; otherwise the claim is
+ * relayed unsigned and stays buyer_recorded.
+ */
+export function outcomeClaimFromA2A(outcome, options = {}) {
+    const binding = options.binding;
+    const signed = outcome.signature !== undefined && binding !== undefined && binding.key_id === outcome.key_id;
+    return {
+        type: outcome.type,
+        asserted_by: "provider",
+        note: outcome.note,
+        occurred_at: outcome.occurred_at,
+        evidence: outcome.evidence,
+        ...(signed ? { signer: { provider_id: binding.provider_id, binding_id: binding.binding_id, key_id: binding.key_id, value: outcome.signature } } : {}),
+    };
+}

package/dist/types.d.ts

@@ -0,0 +1,68 @@
+/** A2A v1.0 shapes used by the bridge (a2a-protocol.org, camelCase JSON). */
+export type A2ATaskState = "TASK_STATE_UNSPECIFIED" | "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";
+/** One unified part: exactly one of text, raw (base64 bytes), url, or data. */
+export interface A2APart {
+    text?: string;
+    raw?: string;
+    url?: string;
+    data?: unknown;
+    filename?: string;
+    mediaType?: string;
+    metadata?: Record<string, unknown>;
+}
+export interface A2AArtifact {
+    artifactId: string;
+    name?: string;
+    description?: string;
+    parts: A2APart[];
+    metadata?: Record<string, unknown>;
+}
+export interface A2ATaskStatus {
+    state: A2ATaskState;
+    message?: unknown;
+    timestamp?: string;
+}
+export interface A2ATask {
+    id: string;
+    contextId: string;
+    status: A2ATaskStatus;
+    artifacts?: A2AArtifact[];
+    metadata?: Record<string, unknown>;
+}
+export interface A2ATaskStatusUpdateEvent {
+    taskId: string;
+    contextId: string;
+    status: A2ATaskStatus;
+    metadata?: Record<string, unknown>;
+}
+export interface A2ATaskArtifactUpdateEvent {
+    taskId: string;
+    contextId: string;
+    artifact: A2AArtifact;
+    append?: boolean;
+    lastChunk?: boolean;
+    index?: number;
+    metadata?: Record<string, unknown>;
+}
+/** The agent card fields the bridge reads, in A2A wire JSON (with @a2a-js/sdk, `AgentCard.toJSON(card)`). */
+export interface A2AAgentCard {
+    name: string;
+    version: string;
+    skills?: {
+        id: string;
+    }[];
+    [field: string]: unknown;
+}
+/**
+ * Stream responses are discriminated by member name. With @a2a-js/sdk, `StreamResponse.toJSON(event)` produces
+ * this shape from the SDK's objects.
+ */
+export type A2AStreamResponse = {
+    task: A2ATask;
+} | {
+    message: unknown;
+} | {
+    statusUpdate: A2ATaskStatusUpdateEvent;
+} | {
+    artifactUpdate: A2ATaskArtifactUpdateEvent;
+};

package/dist/types.js

@@ -0,0 +1,2 @@
+/** A2A v1.0 shapes used by the bridge (a2a-protocol.org, camelCase JSON). */
+export {};

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@atcn/adapter-a2a",
+  "version": "1.5.0",
+  "description": "Record paid A2A (Agent2Agent) work in ATCN: signed task events, billing references, estimates, signed outcomes and sub-task lineage",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/fadnisnikhil/atcn.git",
+    "directory": "packages/adapter-a2a"
+  },
+  "homepage": "https://github.com/fadnisnikhil/atcn/tree/main/packages/adapter-a2a#readme",
+  "bugs": {
+    "url": "https://github.com/fadnisnikhil/atcn/issues"
+  },
+  "type": "module",
+  "engines": {
+    "node": ">=20"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "atcn-source": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json"
+  },
+  "dependencies": {
+    "@atcn/schema": "1.5.0",
+    "@atcn/sdk": "1.5.0"
+  }
+}