@loopingai/core 0.1.0

package/README.md

@@ -0,0 +1,279 @@
+# @loopingai/core
+
+**The mandatory foundation for a Looping agent on Cloudflare Workers.**
+
+Zero-trust A2A (signed AgentCard, gateway-JWT verification, no shared secrets), the
+durable task lifecycle, the delegation and subagent runtime, and the test harness.
+
+You bring the loop and the prompts. Core brings everything you cannot choose not to have.
+
+```bash
+npm install @loopingai/core
+```
+
+> Part of a three-package split:
+> **`@loopingai/core`** (this) ·
+> [`looping-plugins`](https://github.com/Looping-AI/looping-plugins) (optional, composable capabilities) ·
+> [`looping-starter`](https://github.com/Looping-AI/looping-starter) (a working agent that composes them).
+
+---
+
+## Why this exists
+
+An agent that talks to other agents has to answer one question before anything else:
+_is the caller who they claim to be, and can they prove it without a shared secret?_
+That answer — and the durable machinery for accepting a turn, decomposing it, and
+delivering a result out of band — is identical for every agent. It is also the part
+that is easy to get subtly and silently wrong.
+
+So it ships once, here, with the security-critical paths pinned by tests. Anything
+optional is a plugin. Anything opinionated belongs to your app.
+
+---
+
+## Quick start
+
+### 1. Generate a signing key
+
+```bash
+npx looping-keys
+```
+
+Set the private JWK as `A2A_SIGNING_KEY` (`.dev.vars` locally, `wrangler secret put`
+when deployed) and the origins you accept calls from as `GATEWAY_ORIGINS`:
+
+```ini
+# .dev.vars
+A2A_SIGNING_KEY={"crv":"Ed25519","d":"…","x":"…","kty":"OKP","kid":"a2a-2026-08-01"}
+GATEWAY_ORIGINS=["https://gateway.example.com"]
+```
+
+The public half is never configured anywhere — the Worker derives it from the private
+key and serves it at the card's `jku`.
+
+### 2. Put the A2A edge in front of your Durable Object
+
+```ts
+import { createA2AWorker } from "@loopingai/core/worker";
+
+const manifest = {
+  name: "my-agent",
+  description: "Does a useful thing.",
+  version: "1.0.0",
+  capabilities: { streaming: false, pushNotifications: true, extensions: [] },
+  defaultInputModes: ["text/plain"],
+  defaultOutputModes: ["text/plain"],
+  skills: []
+};
+
+export default {
+  fetch: createA2AWorker({
+    manifest,
+    // One DO instance per verified caller — this is what makes a task
+    // unreachable from any other caller by construction.
+    resolveAgent: (identity) =>
+      env.MY_AGENT.get(env.MY_AGENT.idFromName(identity.key!)),
+    // Must be idempotent: the gateway retries dispatch.
+    startTurn: async (turn) => {
+      await env.TURN_WORKFLOW.create({ id: turn.messageId, params: turn });
+    }
+  })
+} satisfies ExportedHandler<Env>;
+```
+
+That handler serves three routes: the public JWKS, a **signed** AgentCard at
+`/.well-known/agent-card.json`, and gateway-authenticated JSON-RPC. Every POST is
+verified before a Durable Object is ever addressed.
+
+### 3. Build the runtime in your Durable Object
+
+Everything that would otherwise be a module-level constant is resolved once per DO
+instance, from your config and your installed plugins:
+
+```ts
+import { Agent } from "agents";
+import { createAgentRuntime } from "@loopingai/core";
+import { AgentDB } from "@loopingai/core/db";
+
+export class MyAgent extends Agent<Env> {
+  runtime!: ReturnType<typeof createAgentRuntime>;
+  db!: AgentDB;
+
+  async onStart() {
+    this.runtime = createAgentRuntime({
+      config: { model: { chatModelId: "@cf/zai-org/glm-5.2" } },
+      plugins: [scraper({ apiKey: this.env.SCRAPER_API_KEY })],
+      env: this.env // opt in to verifying every plugin's declared bindings exist
+    });
+
+    this.db = new AgentDB(this.ctx.storage, {
+      maxSubtasks: this.runtime.config.maxSubtasks,
+      stores: this.runtime.stores
+    });
+    await this.db.ensureReady();
+  }
+}
+```
+
+Resolving a registry at _import_ time is the one thing this package exists to
+prevent: it freezes the registry before `env` exists (which on Workers is always),
+defeats tree-shaking, and makes runtime plugin selection impossible.
+
+---
+
+## Exports
+
+No root barrel. Each area is its own subpath, so importing the delegation layer does
+not drag in the A2A adapter, and the test harness cannot reach a production bundle.
+
+| Subpath                        | What's in it                                                                |
+| ------------------------------ | --------------------------------------------------------------------------- |
+| `@loopingai/core`              | `createAgentRuntime`, the plugin contract, config shapes, platform facts    |
+| `@loopingai/core/a2a`          | card signing, JWKS, gateway-JWT verify, push notify, task store, executor   |
+| `@loopingai/core/worker`       | `createA2AWorker()` — the whole zero-trust edge                             |
+| `@loopingai/core/agent`        | session, history, model runtime, inference, budget, control tools           |
+| `@loopingai/core/subtasks`     | delegation types, decomposition, the `delegate` tool, wave scheduler        |
+| `@loopingai/core/subagent`     | `RecipeSubagentBase`, resumable runs, fingerprinting, workspace             |
+| `@loopingai/core/db`           | `AgentDB`, `notify_tasks` + `subtasks` schema, migrations, `PluginStore`    |
+| `@loopingai/core/testing`      | VCR, `FakeSession`, `mockModel`, DO helpers, JWK fixtures — _workerd realm_ |
+| `@loopingai/core/testing/node` | the VCR recorder — _Node realm, never import from a spec_                   |
+| `@loopingai/core/eslint`       | the `no-deprecated-object-properties` rule                                  |
+
+`/testing*` and `/eslint` are structurally incapable of entering a runtime graph, and
+`npm run verify:exports` asserts exactly that before every publish.
+
+---
+
+## The zero-trust model
+
+No secret ever crosses the boundary, in either direction.
+
+```
+Gateway ──── EdDSA JWT, jku → its public JWKS ────▶ Agent    "the agent knows the gateway"
+Agent   ──── signed AgentCard, jku → its JWKS  ────▶ Gateway  "the gateway knows the agent"
+```
+
+`verifyGatewayToken` runs four checks, in this order, on every single call:
+
+1. **`jku` present** in the protected header (RFC 7515 §4.1.2).
+2. **`jku` origin is allowlisted** — validated _before_ the fetch, so an attacker
+   cannot point `jku` at a JWKS they control.
+3. **`iss` origin equals `jku` origin** — one listed gateway cannot impersonate another.
+4. **`jwtVerify` pinned to EdDSA.**
+
+All four are load-bearing. Do not make any of them optional, and do not add a
+local-development bypass — run a local gateway instead. `verify.spec.ts` asserts each
+one negatively, including that an unlisted `jku` is rejected _before_ any network
+call happens.
+
+The agent's card is signed over its **wire (protobuf-JSON) encoding**, which is what
+makes the served document a fixed point under the repeated decoding a verifier
+performs. A gateway pins the card's `kid` + `jku` on first registration
+(Trust-On-First-Use).
+
+---
+
+## Plugins
+
+A capability is a plugin. Core never imports one — your app registers it, which keeps
+bundle size proportional to what you actually installed.
+
+```ts
+import { definePlugin } from "@loopingai/core";
+
+export const scraper = (config: { apiKey: string }) =>
+  definePlugin({
+    key: "scraper",
+    subtaskType: {
+      key: "scrape",
+      description: "fetch a page and summarize it",
+      params: z.object({ url: z.string().describe("page to fetch") }),
+      recipe
+    },
+    toolFamilies: { web: (ctx) => ({ tools: { fetchPage: /* … */ } }) },
+    capability: "You can scrape a page and summarize it.",
+    requires: { secrets: ["SCRAPER_API_KEY"] },
+    store: { plugin: "scraper", version: 1, ensureTables: (sql, from) => { /* … */ } }
+  });
+```
+
+`createAgentRuntime` fails at DO start — never mid-request — on a duplicate plugin
+key, a duplicate tool family, a missing declared binding, or a
+`PLUGIN_CONTRACT_VERSION` mismatch. Because core, plugins, and starter publish from
+separate repos, one of them is always briefly behind; that version assert turns the
+skew into a readable sentence instead of a structural-type error several frames from
+its cause.
+
+The contract is **additive-only within a major**: new capabilities arrive as optional
+fields on `AgentPlugin`.
+
+---
+
+## Testing
+
+The harness both predecessor agents grew, shipped so you don't grow it a third time.
+
+```ts
+import {
+  FakeSession,
+  mockModel,
+  makeGatewayToken,
+  makeDoHelpers
+} from "@loopingai/core/testing";
+
+const { withDb } = makeDoHelpers(env.MY_AGENT);
+
+await withDb("accepts a turn once", async (db) => {
+  await db.ensureReady();
+  db.tasks.begin({ messageId: "m1", taskId: "t1", contextId: "c1" });
+});
+```
+
+- **VCR** — record/replay real HTTP against on-disk cassettes, split across the Node
+  and workerd realms because specs run in workerd, which has no filesystem. Point
+  vitest's `globalSetup` at `@loopingai/core/testing/vcr-global-setup`.
+- **Fakes** — `FakeSession` (a `SessionLike` reference implementation) and `mockModel`
+  (a scripted `LanguageModel`), so a loop can be driven with no model call at all.
+- **Fixtures** — Ed25519 keypairs and a gateway-JWT signer, so the zero-trust path is
+  exercisable end to end without a real gateway.
+
+---
+
+## What core deliberately does _not_ contain
+
+- The turn loop, triage, and the DO / Workflow class bodies. Core ships the argument
+  and budget types; you write the loop.
+- The main agent's soul. Core ships no prompt copy.
+- Config _values_ — model ids, budgets, limits. Core ships the shapes and safe
+  defaults, and `resolveConfig` validates your overrides.
+- Vectorize recall, browser tools, shell. All optional → plugins.
+
+---
+
+## Requirements
+
+- **Node** ≥ 24 (for build and test only — the package itself runs on workerd)
+- **Bindings:** `AI`, one Durable Object, one Workflow
+- **Secrets:** `A2A_SIGNING_KEY`, `GATEWAY_ORIGINS`
+- **Peers, never bundled:** `agents`, `ai`, `workers-ai-provider`
+
+That last point is not stylistic: two copies of `agents` in one Worker breaks the
+`Session` / `SessionMessage` types and every `instanceof`. For local development
+across the three repos use `file:` overrides, or `npm pack` plus a tarball install —
+**not `npm link`**, which duplicates peer dependencies.
+
+---
+
+## Contributing
+
+[`AGENTS.md`](./AGENTS.md) documents the constraints this package is guardian of.
+
+```bash
+npm run check           # prettier + eslint + tsc (src) + tsc (test) + build
+npm test                # vitest, inside real workerd
+npm run verify:exports  # the publish gate: subpaths, ESM specifiers, realm isolation
+```
+
+## License
+
+[GPL-3.0-only](./LICENSE).

package/dist/a2a/agent-stub.d.ts

@@ -0,0 +1,61 @@
+import type { Task, TaskState } from "@a2a-js/sdk";
+import type { GatewayIdentity } from "./verify.js";
+import type { PlainTask } from "./task.js";
+/**
+ * The task-lifecycle surface core calls on an agent Durable Object, declared
+ * structurally so core never imports a consumer's DO class.
+ *
+ * A consumer's `DurableObjectStub<MyAgent>` satisfies this by construction:
+ * Cloudflare's RPC type mapping wraps each return in `Promise<Serializable<T>>`,
+ * and every type below is already `Serializable` — that is precisely why
+ * {@link PlainTask} exists (see {@link file://./task.ts}).
+ *
+ * `listTasks` is optional. `ListTasks` is new in A2A v1.0 and an agent that does
+ * not keep a queryable task history simply omits it; {@link DurableTaskStore}
+ * then answers the RPC with `UnsupportedOperationError` instead of failing at
+ * the binding. Everything else is mandatory — they are the accept-and-notify
+ * contract.
+ */
+export interface TaskAgent {
+    /**
+     * Record (or reuse) the `submitted` task for a turn. **Must be idempotent on
+     * `messageId`**: the gateway retries dispatch, and the executor relies on this
+     * plus a deterministic workflow id to make a turn run exactly once.
+     */
+    beginTask(input: {
+        messageId: string;
+        taskId: string;
+        contextId: string;
+    }): Promise<PlainTask>;
+    getTask(taskId: string): Promise<PlainTask | null>;
+    /** Returns false when the write was refused (e.g. the task is already terminal). */
+    saveTask(task: Task): Promise<boolean>;
+    /** Marks the task canceled and returns it, or null when there is no such task. */
+    cancelTask(taskId: string): Promise<PlainTask | null>;
+    listTasks?(query: TaskListQuery): Promise<TaskListPage>;
+}
+export interface TaskListQuery {
+    contextId?: string;
+    state?: TaskState;
+    /** Epoch ms; matches the `updated_at` column stamped on every status write. */
+    updatedAfter?: number;
+    includeArtifacts: boolean;
+    historyLength?: number;
+    limit: number;
+    offset: number;
+}
+export interface TaskListPage {
+    tasks: Task[];
+    /** Total matching rows, ignoring `limit`/`offset` — drives `nextPageToken`. */
+    totalSize: number;
+}
+/**
+ * Resolve the agent DO stub for a verified caller.
+ *
+ * Supplied by the consumer because addressing is theirs: core does not know the
+ * binding name, and the identity→instance mapping is a product decision. The
+ * conventional implementation keys one DO instance per `identity.key`, which is
+ * what makes a task unreachable from any other caller by construction.
+ */
+export type AgentResolver = (identity: GatewayIdentity) => TaskAgent;
+//# sourceMappingURL=agent-stub.d.ts.map

package/dist/a2a/agent-stub.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-stub.d.ts","sourceRoot":"","sources":["../../src/a2a/agent-stub.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACnD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AACnD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAE3C;;;;;;;;;;;;;;GAcG;AACH,MAAM,WAAW,SAAS;IACxB;;;;OAIG;IACH,SAAS,CAAC,KAAK,EAAE;QACf,SAAS,EAAE,MAAM,CAAC;QAClB,MAAM,EAAE,MAAM,CAAC;QACf,SAAS,EAAE,MAAM,CAAC;KACnB,GAAG,OAAO,CAAC,SAAS,CAAC,CAAC;IAEvB,OAAO,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,GAAG,IAAI,CAAC,CAAC;IAEnD,oFAAoF;IACpF,QAAQ,CAAC,IAAI,EAAE,IAAI,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAEvC,kFAAkF;IAClF,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,GAAG,IAAI,CAAC,CAAC;IAEtD,SAAS,CAAC,CAAC,KAAK,EAAE,aAAa,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC;CACzD;AAED,MAAM,WAAW,aAAa;IAC5B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,SAAS,CAAC;IAClB,+EAA+E;IAC/E,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,gBAAgB,EAAE,OAAO,CAAC;IAC1B,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,IAAI,EAAE,CAAC;IACd,+EAA+E;IAC/E,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;;GAOG;AACH,MAAM,MAAM,aAAa,GAAG,CAAC,QAAQ,EAAE,eAAe,KAAK,SAAS,CAAC"}

package/dist/a2a/agent-stub.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=agent-stub.js.map

package/dist/a2a/agent-stub.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-stub.js","sourceRoot":"","sources":["../../src/a2a/agent-stub.ts"],"names":[],"mappings":""}

package/dist/a2a/card.d.ts

@@ -0,0 +1,119 @@
+import type { JWK } from "jose";
+import { AgentCard } from "@a2a-js/sdk";
+/** The default JSON-RPC path an agent answers on (the card's only interface). */
+export declare const A2A_RPC_PATH = "/a2a";
+/**
+ * The transport-independent half of an {@link AgentCard} — everything that does
+ * not depend on the request origin. {@link buildBaseCard} adds
+ * `supportedInterfaces` and the security fields.
+ *
+ * Derived from the SDK `AgentCard` rather than hand-declared so a protocol field
+ * that gains a requirement fails the build here instead of silently going
+ * unadvertised.
+ */
+export type AgentManifest = Pick<AgentCard, "name" | "description" | "version" | "capabilities" | "defaultInputModes" | "defaultOutputModes" | "skills">;
+/**
+ * An AgentCard in its **protobuf-JSON** encoding — the form served at the
+ * well-known path and the exact document a signature is computed over. Distinct
+ * from the in-memory `AgentCard`: the wire form omits proto defaults and renders
+ * oneofs (`securitySchemes`, `Part.content`) as a single key rather than a
+ * `$case` tag.
+ */
+export type WireAgentCard = Record<string, unknown>;
+export interface CardSigningConfig {
+    /** Ed25519 private JWK (with `kid`) that signs the card. */
+    privateJwk: JWK & {
+        kid: string;
+    };
+    /** Public URL serving this agent's JWKS — embedded as the JWS `jku`. */
+    jku: string;
+}
+export interface BuildCardOptions {
+    /** Origin the card is served from; the interface `url` is built under it. */
+    origin: string;
+    /** Path this agent answers JSON-RPC on. Defaults to {@link A2A_RPC_PATH}. */
+    rpcPath?: string;
+    /**
+     * Advertise the gateway's Bearer-JWT scheme in `securitySchemes`.
+     *
+     * **Defaults to `false` for historical reasons that no longer hold — see
+     * below before relying on the default.**
+     *
+     * `SecurityScheme` is the card's only protobuf *oneof*, and in earlier SDK
+     * releases `SecurityScheme.fromJSON` read only the wire spelling
+     * (`{ httpAuthSecurityScheme: … }`) and not the decoded `$case` form. A
+     * verifier that decodes the fetched card and then canonicalizes it through
+     * `toJSON(fromJSON(card))` decodes twice, and the second pass collapsed
+     * `{ gatewayJwt: { httpAuthSecurityScheme: … } }` to `{ gatewayJwt: {} }` — a
+     * different document from the one that was signed, so the signature failed.
+     * looping-gateway's `canonicalCardPayload` double-decodes exactly this way.
+     *
+     * **As of the pinned `@a2a-js/sdk` (1.0.1) that is fixed.** `card.spec.ts`
+     * asserts it directly: an advertised-schemes card is a fixed point under
+     * repeated decoding, and its signature verifies both as served and after a
+     * double decode. So the safety argument for the `false` default is gone, and
+     * the remaining reason to keep it is deployment ordering — a gateway pinned to
+     * an older SDK copy would still collapse the oneof. Flip the default once the
+     * gateways in play are known to be on ≥1.0.1; the specs will hold the line if
+     * a later SDK regresses.
+     *
+     * `securityRequirements` is unaffected either way — it is a plain map, not a
+     * oneof — so the card always declares that auth is *required*, it just may not
+     * describe the scheme.
+     */
+    advertiseSecuritySchemes?: boolean;
+}
+/**
+ * Build the (unsigned) AgentCard.
+ *
+ * v1.0 replaced the card's flat `url` / `preferredTransport` / `protocolVersion`
+ * fields with an ordered `supportedInterfaces` list, where each entry pins its
+ * own protocol binding *and* protocol version. That per-interface
+ * `protocolVersion` is what a client's transport factory matches on and what the
+ * Worker validates the `A2A-Version` request header against, so it must be the
+ * real protocol version rather than the agent's own version string.
+ */
+export declare function buildBaseCard(manifest: AgentManifest, opts: BuildCardOptions): AgentCard;
+/**
+ * Sign the card with a detached-payload EdDSA flattened JWS, returning the
+ * signed **wire** card to serve. v1.0 standardized this (A2A spec §8.4), so the
+ * canonicalization and JWS construction are the SDK's rather than a local
+ * scheme: a JCS (RFC 8785) canonicalization of the card with `signatures`
+ * removed, under a protected header carrying `alg`, `kid` and `typ` (all three
+ * are required — the SDK verifier rejects a signature missing any of them).
+ *
+ * The card is normalized to its wire form *before* signing because that is what
+ * the verifier canonicalizes: `verifyAgentCardSignature` re-encodes whatever
+ * document it fetched through `AgentCard.toJSON(AgentCard.fromJSON(card))`.
+ * Signing the in-memory proto object instead would canonicalize `$case` tags and
+ * proto defaults that never appear on the wire, and every signature would fail.
+ *
+ * A verifying gateway strips the `signatures` array, recomputes the canonical
+ * payload, and verifies — pinning this key's `kid`+`jku` on first registration
+ * (Trust-On-First-Use).
+ */
+export declare function signCard(card: AgentCard, cfg: CardSigningConfig): Promise<WireAgentCard>;
+/**
+ * The card's protobuf-JSON encoding. Typed back as `AgentCard` for the SDK
+ * signer, which is generic over "the document to canonicalize" rather than over
+ * the in-memory shape specifically.
+ *
+ * Encode-only — never `toJSON(fromJSON(card))`. `fromJSON` reads the *wire*
+ * spelling of a oneof, so running it over an in-memory card silently drops every
+ * `$case`-tagged field. The verifier's round trip is the mirror image and stable:
+ * it decodes the document it fetched and re-encodes it to exactly this.
+ */
+export declare function wireCard(card: AgentCard): AgentCard;
+/**
+ * Parse and validate the `A2A_SIGNING_KEY` secret into the private JWK used to
+ * sign the card. Throws if the JWK is missing its `kid` (required for the JWS
+ * protected header and gateway key-pinning).
+ */
+export declare function parsePrivateJwk(raw: string): CardSigningConfig["privateJwk"];
+/** Public card-signing JWKS (served at the `jku`): the private JWK minus `d`. */
+export declare function publicCardJwks(privateJwk: JWK & {
+    kid: string;
+}): {
+    keys: JWK[];
+};
+//# sourceMappingURL=card.d.ts.map

package/dist/a2a/card.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"card.d.ts","sourceRoot":"","sources":["../../src/a2a/card.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,MAAM,CAAC;AAChC,OAAO,EAEL,SAAS,EAEV,MAAM,aAAa,CAAC;AAKrB,iFAAiF;AACjF,eAAO,MAAM,YAAY,SAAS,CAAC;AAEnC;;;;;;;;GAQG;AACH,MAAM,MAAM,aAAa,GAAG,IAAI,CAC9B,SAAS,EACP,MAAM,GACN,aAAa,GACb,SAAS,GACT,cAAc,GACd,mBAAmB,GACnB,oBAAoB,GACpB,QAAQ,CACX,CAAC;AAEF;;;;;;GAMG;AACH,MAAM,MAAM,aAAa,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAEpD,MAAM,WAAW,iBAAiB;IAChC,4DAA4D;IAC5D,UAAU,EAAE,GAAG,GAAG;QAAE,GAAG,EAAE,MAAM,CAAA;KAAE,CAAC;IAClC,wEAAwE;IACxE,GAAG,EAAE,MAAM,CAAC;CACb;AAED,MAAM,WAAW,gBAAgB;IAC/B,6EAA6E;IAC7E,MAAM,EAAE,MAAM,CAAC;IACf,6EAA6E;IAC7E,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2BG;IACH,wBAAwB,CAAC,EAAE,OAAO,CAAC;CACpC;AAUD;;;;;;;;;GASG;AACH,wBAAgB,aAAa,CAC3B,QAAQ,EAAE,aAAa,EACvB,IAAI,EAAE,gBAAgB,GACrB,SAAS,CAiCX;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAsB,QAAQ,CAC5B,IAAI,EAAE,SAAS,EACf,GAAG,EAAE,iBAAiB,GACrB,OAAO,CAAC,aAAa,CAAC,CASxB;AAED;;;;;;;;;GASG;AACH,wBAAgB,QAAQ,CAAC,IAAI,EAAE,SAAS,GAAG,SAAS,CAEnD;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,iBAAiB,CAAC,YAAY,CAAC,CAI5E;AAED,iFAAiF;AACjF,wBAAgB,cAAc,CAAC,UAAU,EAAE,GAAG,GAAG;IAAE,GAAG,EAAE,MAAM,CAAA;CAAE,GAAG;IACjE,IAAI,EAAE,GAAG,EAAE,CAAC;CACb,CAIA"}

package/dist/a2a/card.js

@@ -0,0 +1,115 @@
+import { A2A_PROTOCOL_VERSION, AgentCard, generateAgentCardSignature } from "@a2a-js/sdk";
+/** JWS algorithm for the card signature — must match the gateway (`EdDSA`). */
+const ALG = "EdDSA";
+/** The default JSON-RPC path an agent answers on (the card's only interface). */
+export const A2A_RPC_PATH = "/a2a";
+/**
+ * The `httpAuthSecurityScheme` describing the gateway's Bearer JWT, and the
+ * requirement that references it. Split out so the requirement can be advertised
+ * even when {@link BuildCardOptions.advertiseSecuritySchemes} keeps the scheme
+ * itself off the wire.
+ */
+const GATEWAY_SCHEME_ID = "gatewayJwt";
+/**
+ * Build the (unsigned) AgentCard.
+ *
+ * v1.0 replaced the card's flat `url` / `preferredTransport` / `protocolVersion`
+ * fields with an ordered `supportedInterfaces` list, where each entry pins its
+ * own protocol binding *and* protocol version. That per-interface
+ * `protocolVersion` is what a client's transport factory matches on and what the
+ * Worker validates the `A2A-Version` request header against, so it must be the
+ * real protocol version rather than the agent's own version string.
+ */
+export function buildBaseCard(manifest, opts) {
+    const rpcPath = opts.rpcPath ?? A2A_RPC_PATH;
+    return {
+        ...manifest,
+        supportedInterfaces: [
+            {
+                url: `${opts.origin}${rpcPath}`,
+                protocolBinding: "JSONRPC",
+                protocolVersion: A2A_PROTOCOL_VERSION,
+                // Single-tenant agent: one DO per verified gateway identity, so the
+                // protocol-level tenant slot goes unused.
+                tenant: ""
+            }
+        ],
+        provider: undefined,
+        documentationUrl: undefined,
+        iconUrl: undefined,
+        securitySchemes: opts.advertiseSecuritySchemes
+            ? {
+                [GATEWAY_SCHEME_ID]: {
+                    scheme: {
+                        $case: "httpAuthSecurityScheme",
+                        value: { description: "", scheme: "bearer", bearerFormat: "JWT" }
+                    }
+                }
+            }
+            : {},
+        // v0.3's `security: [{ gatewayJwt: [] }]`. The empty `list` means the scheme
+        // is required but carries no scopes. Safe to advertise unconditionally: this
+        // is a plain map, so it survives the round trip that eats `securitySchemes`.
+        securityRequirements: [{ schemes: { [GATEWAY_SCHEME_ID]: { list: [] } } }],
+        signatures: []
+    };
+}
+/**
+ * Sign the card with a detached-payload EdDSA flattened JWS, returning the
+ * signed **wire** card to serve. v1.0 standardized this (A2A spec §8.4), so the
+ * canonicalization and JWS construction are the SDK's rather than a local
+ * scheme: a JCS (RFC 8785) canonicalization of the card with `signatures`
+ * removed, under a protected header carrying `alg`, `kid` and `typ` (all three
+ * are required — the SDK verifier rejects a signature missing any of them).
+ *
+ * The card is normalized to its wire form *before* signing because that is what
+ * the verifier canonicalizes: `verifyAgentCardSignature` re-encodes whatever
+ * document it fetched through `AgentCard.toJSON(AgentCard.fromJSON(card))`.
+ * Signing the in-memory proto object instead would canonicalize `$case` tags and
+ * proto defaults that never appear on the wire, and every signature would fail.
+ *
+ * A verifying gateway strips the `signatures` array, recomputes the canonical
+ * payload, and verifies — pinning this key's `kid`+`jku` on first registration
+ * (Trust-On-First-Use).
+ */
+export async function signCard(card, cfg) {
+    const sign = generateAgentCardSignature(cfg.privateJwk, {
+        alg: ALG,
+        kid: cfg.privateJwk.kid,
+        typ: "JOSE",
+        jku: cfg.jku
+    });
+    const signed = await sign(wireCard(card));
+    return signed;
+}
+/**
+ * The card's protobuf-JSON encoding. Typed back as `AgentCard` for the SDK
+ * signer, which is generic over "the document to canonicalize" rather than over
+ * the in-memory shape specifically.
+ *
+ * Encode-only — never `toJSON(fromJSON(card))`. `fromJSON` reads the *wire*
+ * spelling of a oneof, so running it over an in-memory card silently drops every
+ * `$case`-tagged field. The verifier's round trip is the mirror image and stable:
+ * it decodes the document it fetched and re-encodes it to exactly this.
+ */
+export function wireCard(card) {
+    return AgentCard.toJSON(card);
+}
+/**
+ * Parse and validate the `A2A_SIGNING_KEY` secret into the private JWK used to
+ * sign the card. Throws if the JWK is missing its `kid` (required for the JWS
+ * protected header and gateway key-pinning).
+ */
+export function parsePrivateJwk(raw) {
+    const jwk = JSON.parse(raw);
+    if (!jwk.kid)
+        throw new Error("A2A_SIGNING_KEY must include a `kid`");
+    return jwk;
+}
+/** Public card-signing JWKS (served at the `jku`): the private JWK minus `d`. */
+export function publicCardJwks(privateJwk) {
+    const { d: _d, ...pub } = privateJwk;
+    void _d;
+    return { keys: [{ ...pub, use: "sig", alg: ALG }] };
+}
+//# sourceMappingURL=card.js.map

package/dist/a2a/card.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"card.js","sourceRoot":"","sources":["../../src/a2a/card.ts"],"names":[],"mappings":"AACA,OAAO,EACL,oBAAoB,EACpB,SAAS,EACT,0BAA0B,EAC3B,MAAM,aAAa,CAAC;AAErB,+EAA+E;AAC/E,MAAM,GAAG,GAAG,OAAO,CAAC;AAEpB,iFAAiF;AACjF,MAAM,CAAC,MAAM,YAAY,GAAG,MAAM,CAAC;AA0EnC;;;;;GAKG;AACH,MAAM,iBAAiB,GAAG,YAAY,CAAC;AAEvC;;;;;;;;;GASG;AACH,MAAM,UAAU,aAAa,CAC3B,QAAuB,EACvB,IAAsB;IAEtB,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,IAAI,YAAY,CAAC;IAC7C,OAAO;QACL,GAAG,QAAQ;QACX,mBAAmB,EAAE;YACnB;gBACE,GAAG,EAAE,GAAG,IAAI,CAAC,MAAM,GAAG,OAAO,EAAE;gBAC/B,eAAe,EAAE,SAAS;gBAC1B,eAAe,EAAE,oBAAoB;gBACrC,oEAAoE;gBACpE,0CAA0C;gBAC1C,MAAM,EAAE,EAAE;aACX;SACF;QACD,QAAQ,EAAE,SAAS;QACnB,gBAAgB,EAAE,SAAS;QAC3B,OAAO,EAAE,SAAS;QAClB,eAAe,EAAE,IAAI,CAAC,wBAAwB;YAC5C,CAAC,CAAC;gBACE,CAAC,iBAAiB,CAAC,EAAE;oBACnB,MAAM,EAAE;wBACN,KAAK,EAAE,wBAAwB;wBAC/B,KAAK,EAAE,EAAE,WAAW,EAAE,EAAE,EAAE,MAAM,EAAE,QAAQ,EAAE,YAAY,EAAE,KAAK,EAAE;qBAClE;iBACF;aACF;YACH,CAAC,CAAC,EAAE;QACN,6EAA6E;QAC7E,6EAA6E;QAC7E,6EAA6E;QAC7E,oBAAoB,EAAE,CAAC,EAAE,OAAO,EAAE,EAAE,CAAC,iBAAiB,CAAC,EAAE,EAAE,IAAI,EAAE,EAAE,EAAE,EAAE,EAAE,CAAC;QAC1E,UAAU,EAAE,EAAE;KACf,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,CAAC,KAAK,UAAU,QAAQ,CAC5B,IAAe,EACf,GAAsB;IAEtB,MAAM,IAAI,GAAG,0BAA0B,CAAC,GAAG,CAAC,UAAU,EAAE;QACtD,GAAG,EAAE,GAAG;QACR,GAAG,EAAE,GAAG,CAAC,UAAU,CAAC,GAAG;QACvB,GAAG,EAAE,MAAM;QACX,GAAG,EAAE,GAAG,CAAC,GAAG;KACb,CAAC,CAAC;IACH,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC;IAC1C,OAAO,MAAkC,CAAC;AAC5C,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,QAAQ,CAAC,IAAe;IACtC,OAAO,SAAS,CAAC,MAAM,CAAC,IAAI,CAAc,CAAC;AAC7C,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,eAAe,CAAC,GAAW;IACzC,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAqB,CAAC;IAChD,IAAI,CAAC,GAAG,CAAC,GAAG;QAAE,MAAM,IAAI,KAAK,CAAC,sCAAsC,CAAC,CAAC;IACtE,OAAO,GAAsC,CAAC;AAChD,CAAC;AAED,iFAAiF;AACjF,MAAM,UAAU,cAAc,CAAC,UAAiC;IAG9D,MAAM,EAAE,CAAC,EAAE,EAAE,EAAE,GAAG,GAAG,EAAE,GAAG,UAAU,CAAC;IACrC,KAAK,EAAE,CAAC;IACR,OAAO,EAAE,IAAI,EAAE,CAAC,EAAE,GAAG,GAAG,EAAE,GAAG,EAAE,KAAK,EAAE,GAAG,EAAE,GAAG,EAAE,CAAC,EAAE,CAAC;AACtD,CAAC"}

package/dist/a2a/context.d.ts

@@ -0,0 +1,14 @@
+import { type ServerCallContext } from "@a2a-js/sdk/server";
+import type { GatewayIdentity } from "./verify.js";
+/**
+ * Build the call context for one verified JSON-RPC request. The default builder
+ * stashes the raw headers in the context's state bag, so an executor can reach
+ * them the same way it would under the Express binding.
+ *
+ * `tenant` is deliberately unset: one agent DO instance *is* the tenant, keyed
+ * by the verified caller, so there is no second axis to scope on.
+ */
+export declare function buildCallContext(request: Request, identity: GatewayIdentity): ServerCallContext;
+/** Echo back the extensions the handler actually activated (spec §14.2.2). */
+export declare function extensionHeaders(context: ServerCallContext): HeadersInit;
+//# sourceMappingURL=context.d.ts.map

package/dist/a2a/context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../../src/a2a/context.ts"],"names":[],"mappings":"AAKA,OAAO,EAGL,KAAK,iBAAiB,EAEvB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AA6BnD;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAC9B,OAAO,EAAE,OAAO,EAChB,QAAQ,EAAE,eAAe,GACxB,iBAAiB,CAYnB;AAED,8EAA8E;AAC9E,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,iBAAiB,GAAG,WAAW,CAIxE"}

package/dist/a2a/context.js

@@ -0,0 +1,55 @@
+import { A2A_VERSION_HEADER, Extensions, HTTP_EXTENSION_HEADER } from "@a2a-js/sdk";
+import { defaultServerCallContextBuilder } from "@a2a-js/sdk/server";
+/**
+ * The per-call {@link ServerCallContext} bridge for a Workers `fetch` handler.
+ *
+ * v1.0 made the call context mandatory on every request-handler and task-store
+ * method, and the SDK only ships Express and gRPC bindings that build one; this
+ * is the equivalent seam for `fetch`.
+ */
+/**
+ * The verified calling gateway-agent, as the SDK's {@link User}. `userName` is
+ * the canonical instance key (e.g. `custom:7:analytics`) — the same value the
+ * agent Durable Object is keyed by, so the SDK's owner-scoped bookkeeping lines
+ * up with the isolation this Worker already enforces by routing.
+ */
+class GatewayUser {
+    identity;
+    constructor(identity) {
+        this.identity = identity;
+    }
+    get isAuthenticated() {
+        return true;
+    }
+    get userName() {
+        // The Worker rejects a keyless identity (400) before a context is built.
+        return this.identity.key ?? "";
+    }
+}
+/**
+ * Build the call context for one verified JSON-RPC request. The default builder
+ * stashes the raw headers in the context's state bag, so an executor can reach
+ * them the same way it would under the Express binding.
+ *
+ * `tenant` is deliberately unset: one agent DO instance *is* the tenant, keyed
+ * by the verified caller, so there is no second axis to scope on.
+ */
+export function buildCallContext(request, identity) {
+    const headers = {};
+    for (const [name, value] of request.headers)
+        headers[name] = value;
+    return defaultServerCallContextBuilder({
+        extensions: Extensions.parseServiceParameter(request.headers.get(HTTP_EXTENSION_HEADER) ?? undefined),
+        user: new GatewayUser(identity),
+        headers,
+        requestedVersion: request.headers.get(A2A_VERSION_HEADER) ?? undefined
+    });
+}
+/** Echo back the extensions the handler actually activated (spec §14.2.2). */
+export function extensionHeaders(context) {
+    const activated = context.activatedExtensions;
+    if (!activated?.length)
+        return {};
+    return { [HTTP_EXTENSION_HEADER]: Extensions.toServiceParameter(activated) };
+}
+//# sourceMappingURL=context.js.map