@dynamicagents/core 0.9.0

package/dist/worker/define-agent.d.ts

@@ -0,0 +1,123 @@
+import type { AgentManifest } from "../a2a/card.js";
+import type { GatekeeperIdentity } from "../a2a/verify.js";
+import type { TaskAgent } from "../a2a/agent-stub.js";
+import { type AcceptedTurn } from "../a2a/executor.js";
+/**
+ * One agent's wiring, declared once.
+ *
+ * ## What this replaces
+ *
+ * Mounting an agent used to mean writing the same four things by hand and keeping
+ * them in agreement: a `getAgent(identity)` that guards `identity.key` and reads a
+ * Durable Object binding, a `startTurn` that derives an idempotent workflow id and
+ * swallows the already-exists race, an entry in the `tenants` map, and — in the
+ * agent's own Workflow entrypoint — a second reference to the same DO binding.
+ *
+ * Four copies of one fact, and only the first two were even adjacent. The wiring
+ * also type-checked when it was **wrong**: naming a sibling's workflow binding on
+ * a tenant compiles perfectly and fails at runtime, after auth, after the turn was
+ * accepted, as a task that simply never calls back.
+ *
+ * ```ts
+ * export const reactive = defineAgent({
+ *   tenant: "reactive",
+ *   manifest,
+ *   agent: (env: Env) => env.ReactiveAgent,
+ *   workflow: (env: Env) => env.HANDLE_TASK_WORKFLOW
+ * });
+ *
+ * // the Worker entry
+ * export default {
+ *   fetch: createA2AWorker<Env>({ manifest: hostManifest, agents: [reactive] })
+ * };
+ *
+ * // the agent's Workflow entrypoint
+ * await runHandleTask(event.payload, step, {
+ *   resolveAgent: (identity) => reactive.resolveAgent(this.env, identity),
+ *   …
+ * });
+ * ```
+ *
+ * ## Why accessors rather than binding names
+ *
+ * `agent` and `workflow` are functions of `env`, not strings. A string would have
+ * to be checked against `keyof Env` and then widened back to a namespace, which
+ * loses the Durable Object's own class — so the Workflow could not see the very
+ * methods it exists to drive. An accessor infers both: the tenant is mounted and
+ * the Workflow is driven from one declaration, `env.RactiveAgent` is a compile
+ * error, and `resolveAgent` comes back typed as the agent itself.
+ *
+ * `env` stays a parameter throughout, for the reason `src/env.ts` gives: core
+ * never reaches for a consumer's ambient bindings, and on Workers `env` does not
+ * exist at module scope anyway.
+ */
+/**
+ * What `createA2AWorker` needs in order to mount an agent. The Durable Object's
+ * own class is irrelevant to routing, so this shape forgets it —
+ * {@link AgentDefinition} keeps it for the agent's Workflow.
+ */
+export interface MountedAgent<TEnv> {
+    /** The tenant id a caller addresses this agent with. */
+    tenant: string;
+    /** The transport-independent half of this agent's card. */
+    manifest: AgentManifest;
+    resolveAgent(env: TEnv, identity: GatekeeperIdentity): TaskAgent;
+    startTurn(env: TEnv, turn: AcceptedTurn): Promise<void>;
+}
+/**
+ * {@link AgentDefinition} deliberately does **not** declare `extends
+ * MountedAgent`, even though every one satisfies it.
+ *
+ * A generic `DurableObjectStub<TAgent>` cannot be proven assignable to
+ * {@link TaskAgent} while `TAgent` is unresolved: the RPC stub type widens an
+ * *optional* method (`listTasks?`) to `Promise<undefined> | (…) => …`, and
+ * forcing the comparison also trips TypeScript's instantiation-depth limit — the
+ * same wall that made `PlainTask` necessary. At a concrete call site, where
+ * `TAgent` is a real agent class, the assignment resolves normally. So the check
+ * happens where it can actually succeed: passing `agents: [reactive]` to
+ * `createA2AWorker`.
+ */
+export interface DefineAgentOptions<TEnv, TAgent extends Rpc.DurableObjectBranded> {
+    /**
+     * The tenant id a caller addresses this agent with, and what a gatekeeper
+     * registers against. Renaming one is a re-registration, not a refactor.
+     */
+    tenant: string;
+    /** The transport-independent half of this agent's card. */
+    manifest: AgentManifest;
+    /**
+     * This agent's Durable Object namespace. One instance per verified caller —
+     * the tenant picks the agent, `identity.key` picks which instance of it.
+     */
+    agent: (env: TEnv) => DurableObjectNamespace<TAgent>;
+    /** The Workflow this agent's turns run on. */
+    workflow: (env: TEnv) => Workflow<AcceptedTurn>;
+}
+export interface AgentDefinition<TEnv, TAgent extends Rpc.DurableObjectBranded> {
+    /** The tenant id a caller addresses this agent with. */
+    tenant: string;
+    /** The transport-independent half of this agent's card. */
+    manifest: AgentManifest;
+    /**
+     * Resolve the per-caller agent DO stub, keyed by the verified `identity.key`.
+     *
+     * Typed as the agent's **own** class, so the Workflow that drives its round
+     * methods reaches them through the same declaration the tenant is mounted with
+     * — the two cannot address different Durable Objects.
+     *
+     * Refuses a caller with no key rather than falling back to a shared instance:
+     * that key is what makes one caller's tasks unreachable from another's, so a
+     * missing one is a routing failure, not a default.
+     */
+    resolveAgent(env: TEnv, identity: GatekeeperIdentity): DurableObjectStub<TAgent>;
+    /**
+     * Start this agent's durable turn, idempotently.
+     *
+     * The instance id is derived from the gatekeeper's `messageId`, which is stable
+     * across dispatch retries — so a retry finding its instance already running is
+     * the idempotency working, not a failure. {@link ignoreAlreadyExists} swallows
+     * exactly that race and rethrows everything else.
+     */
+    startTurn(env: TEnv, turn: AcceptedTurn): Promise<void>;
+}
+export declare function defineAgent<TEnv, TAgent extends Rpc.DurableObjectBranded>(options: DefineAgentOptions<TEnv, TAgent>): AgentDefinition<TEnv, TAgent>;

package/dist/worker/define-agent.js

@@ -0,0 +1,20 @@
+import { ignoreAlreadyExists, workflowIdForMessage } from "../a2a/executor.js";
+export function defineAgent(options) {
+    return {
+        tenant: options.tenant,
+        manifest: options.manifest,
+        resolveAgent(env, identity) {
+            if (!identity.key) {
+                throw new Error("identity.key is required to route to the agent DO");
+            }
+            const ns = options.agent(env);
+            return ns.get(ns.idFromName(identity.key));
+        },
+        startTurn(env, turn) {
+            return ignoreAlreadyExists(() => options.workflow(env).create({
+                id: workflowIdForMessage(turn.messageId),
+                params: { ...turn }
+            }));
+        }
+    };
+}

package/dist/worker/index.d.ts

@@ -0,0 +1,218 @@
+import { type AgentManifest } from "../a2a/card.js";
+import { type TurnStarter } from "../a2a/executor.js";
+import type { AgentResolver } from "../a2a/agent-stub.js";
+import { type A2ASecretsEnv } from "../env.js";
+import type { MountedAgent } from "./define-agent.js";
+/**
+ * The A2A Worker: the zero-trust, no-shared-secrets edge every Dynamic Agents agent
+ * puts in front of its Durable Object.
+ *
+ * Trust flows entirely on domains and asymmetric (Ed25519) signatures over
+ * public JWKS: a gatekeeper verifies and pins this agent's identity from its signed
+ * card at registration ("G knows R"), and this Worker verifies the gatekeeper's
+ * identity JWT on every JSON-RPC call ("R knows G"). No secret is ever shared in
+ * either direction.
+ *
+ * **Several agents share one Worker, addressed by `tenant`.** They share one
+ * origin, one endpoint, one signing key and one card at the well-known path;
+ * what differs is the tenant id on every request. That is the A2A mechanism for
+ * exactly this — `AgentInterface.tenant` is "an opaque string used for routing
+ * requests to a specific agent or tenant when multiple agents are served behind
+ * a single A2A endpoint", and §8.3.2 requires a client to send the value the
+ * selected interface declared.
+ *
+ * A tenant is **required on every request**. There is no default and no
+ * implicit routing: an absent tenant is an error, because guessing one would
+ * mean picking an agent the caller never named.
+ *
+ * This replaces mounting a handler per path prefix. That could not work: the
+ * card is a **well-known URI**, which RFC 8615 defines per-authority, so only
+ * one card per origin is discoverable at the registered path — a gatekeeper
+ * resolving `…/.well-known/agent-card.json` against the origin found whichever
+ * agent owned the bare path and pinned *its* key for all of them.
+ *
+ * Three routes:
+ *
+ *  1. `GET jwksPath` — the card-signing public JWKS, resolving every card's
+ *     `jku`.
+ *  2. `GET …/.well-known/agent-card.json` — the signed **stub** card for the
+ *     origin. Matched by suffix, since that path is fixed by the spec.
+ *  3. `POST rpcPath` — gatekeeper-authenticated JSON-RPC, routed to the named
+ *     tenant. `GetExtendedAgentCard` returns that tenant's own signed card;
+ *     everything else runs a turn against its Durable Object.
+ *
+ * Two independent checks keep one tenant's traffic out of another's:
+ * `audience` proves the token was minted for this deployment, and
+ * {@link file://../a2a/verify.ts TENANT_CLAIM} proves it was minted for *this
+ * agent on it*. The second is what makes `tenant` more than an unauthenticated
+ * routing hint in the request body.
+ */
+export { defineAgent, type AgentDefinition, type DefineAgentOptions, type MountedAgent } from "./define-agent.js";
+/**
+ * Default path serving the card-signing public JWKS (the card's `jku`).
+ *
+ * From `@dynamicagents/g2a-protocol`, because the gatekeeper serves its own JWKS at
+ * the same path and fetches ours from whatever `jku` says — see
+ * {@link file://../a2a/verify.ts} for why the two sides share a package rather
+ * than a comment. Re-exported so this stays importable from
+ * `@dynamicagents/core/worker`, where it has always lived.
+ */
+export { JWKS_PATH } from "@dynamicagents/g2a-protocol";
+/** The two secrets a mount signs and verifies with, already read off `env`. */
+export interface A2ASecrets {
+    /** Ed25519 private JWK, as JSON. See {@link A2ASecretsEnv.A2A_SIGNING_KEY}. */
+    signingKey: string;
+    /** Origin allowlist. See {@link A2ASecretsEnv.GATEKEEPER_ORIGINS}. */
+    gatekeeperOrigins: string;
+}
+/** One agent served on this origin — everything that differs between tenants. */
+export interface TenantAgent {
+    /** The transport-independent half of this agent's card. */
+    manifest: AgentManifest;
+    /** Resolve the agent DO stub for a verified caller. */
+    resolveAgent: AgentResolver;
+    /** Start the durable turn. Must be idempotent — see {@link TurnStarter}. */
+    startTurn: TurnStarter;
+}
+export interface A2AWorkerOptions<TEnv = A2ASecretsEnv> {
+    /**
+     * The **stub** card served at the well-known path.
+     *
+     * It describes the origin, not an agent. Every agent here is a tenant and its
+     * card is reached through `GetExtendedAgentCard`, so this card exists to be
+     * the one conformant, signed AgentCard at the URI RFC 8615 and the A2A IANA
+     * registration reserve — advertising the endpoint, the protocol binding and
+     * `extendedAgentCard`.
+     *
+     * It cannot enumerate the tenants: a card carries one interface entry and
+     * spec §8.3.2 has clients take the first, so listing siblings there would
+     * just make every client address the same one. Put their names in
+     * `description` for a human, and register them out of band.
+     */
+    manifest: AgentManifest;
+    /**
+     * The agents on this origin, keyed by tenant id.
+     *
+     * The id is opaque to the protocol — "an opaque string used for routing
+     * requests to a specific agent or tenant when multiple agents are served
+     * behind a single A2A endpoint". A caller names one on every request and this
+     * Worker refuses a request that does not.
+     *
+     * The tenant chooses *which agent*; the verified `identity.key` still chooses
+     * *which instance of it*, so two callers of one tenant stay in separate
+     * Durable Objects exactly as before.
+     *
+     * The escape hatch, and still fully supported: use it for an agent whose
+     * routing or turn-start is genuinely its own. {@link A2AWorkerOptions.agents}
+     * is the shorter form for the ordinary case. Supply at least one of the two.
+     */
+    tenants?: Record<string, TenantAgent>;
+    /**
+     * The agents on this origin, each declared once with
+     * {@link file://./define-agent.ts defineAgent}.
+     *
+     * Prefer this to {@link A2AWorkerOptions.tenants}: one declaration produces the
+     * tenant entry here *and* the resolver the agent's Workflow entrypoint uses, so
+     * the two cannot drift, and the binding names are type-constrained to bindings
+     * of the right kind. Merged over `tenants`, which is checked for duplicate
+     * tenant ids rather than silently overriding.
+     */
+    agents?: readonly MountedAgent<TEnv>[];
+    /** Path serving the public JWKS. Defaults to {@link JWKS_PATH}. */
+    jwksPath?: string;
+    /** Path this agent answers JSON-RPC on. Defaults to `/a2a`. */
+    rpcPath?: string;
+    /**
+     * Where to read this deployment's two secrets. Defaults to the documented
+     * names, `env.A2A_SIGNING_KEY` and `env.GATEKEEPER_ORIGINS`.
+     *
+     * There is **one signing key per origin**, not one per tenant: the card is
+     * per-origin now, so the key the gatekeeper pins is too. Nothing was lost — the
+     * tenants share a Worker and an `env`, so they could always read each other's
+     * secrets, and separate keys never expressed a boundary that existed.
+     *
+     * ```ts
+     * secrets: (env) => ({
+     *   signingKey: env.AGENT_KEY,
+     *   gatekeeperOrigins: env.ALLOWED_GATEKEEPERS
+     * })
+     * ```
+     *
+     * Renaming does not weaken anything: the same key is still Ed25519, still
+     * signs the cards and every callback JWT, and its public half is still what
+     * the gatekeeper pins. Only where it is read from changes.
+     */
+    secrets?: (env: TEnv) => A2ASecrets;
+    /**
+     * The audience a gatekeeper JWT must carry.
+     *
+     * Defaults to this deployment's **own endpoint** — `${origin}${rpcPath}`, the
+     * same URL its cards advertise as their interface — and that default is
+     * almost certainly what you want. Setting this is for a gatekeeper that mints
+     * something else.
+     *
+     * The audience is one half of a two-sided contract: whatever is required here
+     * has to be exactly what the calling gatekeeper *mints*, and a mismatch is a 401
+     * on every request. slack-gatekeeper mints
+     * `new URL(agent.a2aEndpoint).origin + pathname`, which is what this default
+     * matches.
+     *
+     * It proves the token was minted for **this deployment**, and deliberately
+     * says nothing about which agent on it — every tenant shares one endpoint and
+     * therefore one audience. {@link file://../a2a/verify.ts TENANT_CLAIM} is what
+     * separates them, and is the check to look at when reasoning about one agent
+     * spending another's token.
+     */
+    audience?: string | ((url: URL) => string);
+    /**
+     * Advertise `securitySchemes` on the card. **Defaults to `false`** — see
+     * `BuildCardOptions.advertiseSecuritySchemes` for why, and read that note
+     * before turning it on.
+     */
+    advertiseSecuritySchemes?: boolean;
+    /** Claim carrying the caller identity. Defaults to the Dynamic Agents namespace. */
+    identityClaim?: string;
+    /**
+     * Claim carrying the authorized tenant. Defaults to the Dynamic Agents namespace.
+     *
+     * Both claim names are one side of the same contract as `audience`: whatever
+     * is named here has to be exactly what the calling gatekeeper *mints*. Override
+     * them together, or not at all — a deployment fronted by something other than
+     * slack-gatekeeper that renames only the identity claim keeps reading the
+     * tenant from a key its gatekeeper never sets, and every request 401s on the
+     * empty-tenant comparison below.
+     */
+    tenantClaim?: string;
+    /**
+     * Require a `taskPushNotificationConfig` on every `SendMessage`.
+     *
+     * Defaults to `true`, which is the accept-and-notify contract: the agent
+     * accepts synchronously and delivers out of band, so a send with nowhere to
+     * call back is a request that can never be answered. Set `false` only for an
+     * agent that replies inline.
+     */
+    requirePushConfig?: boolean;
+}
+/**
+ * Build the Worker `fetch` handler.
+ *
+ * ```ts
+ * const handler = createA2AWorker({
+ *   manifest: hostManifest,
+ *   tenants: {
+ *     reactive: { manifest, resolveAgent: getAgent, startTurn }
+ *   }
+ * });
+ * export default { fetch: handler } satisfies ExportedHandler<Env>;
+ * ```
+ *
+ * Two overloads, because `secrets` is optional for exactly one shape of `env`.
+ * An `env` carrying the two documented names needs no reader; anything else has
+ * to say where its keys live, and the type system is where that gets enforced —
+ * the alternative is a `parsePrivateJwk` failure on the first request, which is
+ * both later and much harder to read.
+ */
+export declare function createA2AWorker<TEnv extends A2ASecretsEnv>(options: A2AWorkerOptions<TEnv>): (request: Request, env: TEnv) => Promise<Response>;
+export declare function createA2AWorker<TEnv extends object>(options: A2AWorkerOptions<TEnv> & {
+    secrets: (env: TEnv) => A2ASecrets;
+}): (request: Request, env: TEnv) => Promise<Response>;