@plurnk/plurnk-a2a 1.9.0

package/.env.defaults

@@ -0,0 +1,30 @@
+# @plurnk/plurnk-a2a — outbound peers and optional inbound exposure.
+# Alias blocks define available remote agents for every Worker's `agents` family;
+# PLURNK_A2A_ENABLED selects the aliases enabled by default (a Worker may change
+# its own enabledness through worker.agents.* or EXEC [agents]).
+PLURNK_A2A_ENABLED=[]
+PLURNK_A2A_CONNECT_TIMEOUT=30000
+PLURNK_A2A_REQUEST_TIMEOUT=86400000
+
+# PLURNK_A2A_RESEARCH=https://agent.example
+# PLURNK_A2A_RESEARCH_CARD_PATH=/.well-known/agent-card.json
+# PLURNK_A2A_RESEARCH_BEARER=${A2A_RESEARCH_TOKEN}
+# PLURNK_A2A_RESEARCH_HEADERS={"X-Tenant":"${A2A_RESEARCH_TENANT}"}
+
+# One optional Plurnk-hosted A2A exposure. Identity comes from this environment;
+# protocol claims come from the implementation and cannot be configured falsely.
+PLURNK_A2A_EXPOSE=0
+PLURNK_A2A_HOST=127.0.0.1
+PLURNK_A2A_PORT=4100
+PLURNK_A2A_ENDPOINT_PATH=/a2a
+PLURNK_A2A_ENDPOINT_URL=
+PLURNK_A2A_WORKSPACE=a2a
+PLURNK_A2A_PROJECT_ROOT=
+PLURNK_A2A_NAME=
+PLURNK_A2A_DESCRIPTION=
+PLURNK_A2A_VERSION=
+PLURNK_A2A_PROVIDER_ORGANIZATION=
+PLURNK_A2A_PROVIDER_URL=
+PLURNK_A2A_DOCUMENTATION_URL=
+PLURNK_A2A_ICON_URL=
+PLURNK_A2A_SKILLS=[]

package/README.md

@@ -0,0 +1,69 @@
+# @plurnk/plurnk-a2a
+
+The A2A v1 exterior adapter for
+[Plurnk](https://github.com/plurnk/plurnk-service). It exposes a Plurnk
+workspace as an A2A agent and discovers remote agents through their standard
+Agent Cards. The first implementation deliberately supports only the stable
+HTTP+JSON v1 binding.
+
+## Expose an agent
+
+The module is an exterior client of Core's `ApplicationPort`; it does not add
+an A2A scheduler or Task database. The installed service reads the ordinary
+Plurnk environment cascade. Enable one listener and describe its public
+identity in an operator or project `.env`:
+
+```dotenv
+PLURNK_A2A_EXPOSE=1
+PLURNK_A2A_WORKSPACE=research
+PLURNK_A2A_NAME="Research agent"
+PLURNK_A2A_DESCRIPTION="Researches questions in its Plurnk workspace"
+PLURNK_A2A_VERSION=1.0.0
+PLURNK_A2A_SKILLS=[{"id":"research","name":"Research","description":"Researches a question and returns a sourced answer","tags":["research"]}]
+```
+
+The module publishes the Agent Card at `/.well-known/agent-card.json` and the
+advertised HTTP+JSON interface at `/a2a`. It rejects security declarations
+until an authenticated exposure owns the corresponding enforcement path.
+Starting the listener or reading its card does not create or hydrate the named
+workspace; the first admitted Task does so.
+
+## Connect to an agent
+
+```ts
+import { connectHttpJsonAgent } from "@plurnk/plurnk-a2a";
+
+const client = await connectHttpJsonAgent("https://agent.example");
+```
+
+Available remote agents use parallel alias blocks in the same environment
+cascade. Their discovered standard Agent Cards remain authoritative:
+
+```dotenv
+PLURNK_A2A_RESEARCH=https://agent.example
+PLURNK_A2A_RESEARCH_BEARER=${A2A_RESEARCH_TOKEN}
+PLURNK_A2A_ENABLED=["research"]
+```
+
+In the service those definitions are the baseline of the Worker `agents`
+Functionality family (`OutboundModule`): every Worker lists, discovers, adds,
+enables, disables, and removes outbound agents through the common
+`worker.agents.*` actions or the generated `EXEC [agents]` manager, and the
+`a2a://<alias>` scheme resolves an alias against the Worker's own enabled
+snapshot. Enabled agents appear in Turn 0 as one `worker://~/_plurnk/agents/<alias>.md`
+catalog row each; the exact Agent Card stays pullable with `READ a2a://<alias>`.
+
+The package also exports the outbound `a2a://` scheme handler for embedding.
+Its resolver maps each URI authority, for the Worker the operation acts in, to
+one client while keeping alias and credential policy outside the
+protocol/resource owner:
+
+```ts
+import { A2a, connectHttpJsonAgent } from "@plurnk/plurnk-a2a";
+
+const scheme = new A2a(async (alias, ctx) =>
+    alias === "research" && ctx.functionalityWorkerId === 1 ? await connectHttpJsonAgent("https://agent.example") : null);
+```
+
+Messages, Tasks, and Artifacts then use ordinary Plurnk entries and live
+subscriptions. See [`SPEC.md`](./SPEC.md) for the current contract.

package/SPEC.md

@@ -0,0 +1,199 @@
+# Plurnk A2A specification
+
+## §a2a-http-json-discovery HTTP+JSON discovery
+
+`connectHttpJsonAgent` discovers the standard A2A Agent Card, selects an
+advertised `HTTP+JSON` interface at protocol version `1.0`, and returns the
+official SDK client. An explicit Agent Card path may replace the standard
+well-known path. No legacy protocol or alternate binding is enabled.
+
+## §a2a-environment-projection POSIX configuration projection
+
+The package `.env.defaults` is the complete configuration vocabulary. The
+ordinary service, user, project, and client environment cascade remains the
+only configuration authority; generated Agent Cards and discovered remote
+cards are protocol projections, not configuration files.
+
+| Family | Variables | Meaning |
+|---|---|---|
+| Outbound definition | `PLURNK_A2A_<ALIAS>=<absolute HTTP(S) URL>` plus optional `_CARD_PATH`, `_HEADERS`, and `_BEARER` companions | Defines one available remote agent without fetching or enabling it. `_BEARER` contains only a symbolic `${NAME}` reference; secrets remain environment-owned. |
+| Outbound defaults | `PLURNK_A2A_ENABLED` | JSON array selecting the exact aliases enabled by default for a Worker's `agents` family ({§a2a-agents-functionality}); the Worker's durable state may override enabledness only. |
+| Timeouts | `PLURNK_A2A_CONNECT_TIMEOUT`, `PLURNK_A2A_REQUEST_TIMEOUT` | Positive integer milliseconds owned by the A2A package. |
+| Inbound listener | `PLURNK_A2A_EXPOSE`, `_HOST`, `_PORT`, `_ENDPOINT_PATH`, `_ENDPOINT_URL` | `EXPOSE=1` admits one optional HTTP+JSON listener; `0` admits none. |
+| Inbound workspace | `PLURNK_A2A_WORKSPACE`, `_PROJECT_ROOT` | Names the lazily resolved execution workspace and its creation root. |
+| Hosted identity | `PLURNK_A2A_NAME`, `_DESCRIPTION`, `_VERSION`, optional provider/docs/icon fields, and `_SKILLS` | Supplies identity content for one generated standard Agent Card. `_SKILLS` is a JSON array; omitted per-skill examples and media modes receive the exposure's factual defaults. |
+
+Alias matching is case-insensitive but collision-intolerant, while the canonical
+global names use their documented spelling. Header values preserve symbolic
+environment references until connection admission. A remote Agent Card remains
+the authority for that remote agent; its discovered contents are never copied
+into this environment vocabulary.
+
+## §a2a-protocol-witness Protocol witness
+
+The integration witness places a discovery-first client and an independent
+agent on opposite sides of the official A2A v1 HTTP+JSON binding. It covers
+card discovery, blocking task completion, task retrieval, ordered streaming
+updates, cancellation, a direct Message without a fabricated Task,
+input-required continuation under the same Task and Context identities,
+multiple distinct Artifacts, and multiple Tasks sharing one Context. The
+independent agent may use the SDK's reference request handler and task store;
+those test actors establish wire behavior and are not the Plurnk task
+architecture.
+
+## §a2a-inbound-exposure Inbound exterior exposure
+
+The inbound HTTP+JSON listener is an exterior adapter over
+`ApplicationPort`. The official SDK owns A2A framing and request handling;
+Plurnk Workers, Loops, logs, and terminal results remain the only execution
+state. The SDK `TaskStore` implementation is a projection of that durable
+state, not an independent Task database.
+
+```mermaid
+flowchart LR
+    Caller["A2A caller"] --> Context["Context root Worker\nname = contextId"]
+    Context --> Task1["Task child Worker\nname = taskId"]
+    Context --> Task2["Task child Worker\nname = taskId"]
+    Task1 --> Loop1["one live Task Loop"]
+    Task2 --> Loop2["one live Task Loop"]
+```
+
+The SDK generates new Context and Task UUIDs before execution. Those UUIDs
+already satisfy Plurnk's worker-name contract, so their exact values name the
+root Context Worker and its Task child. No adapter binding table, synthetic
+actor, or second scheduler exists. Later Tasks fork the Context root and
+therefore receive the parent-visible prior Task evidence under Core's ordinary
+topology contract.
+
+Only a child Worker with a durable prompt source matching its exact A2A Context,
+Task, and Message identities projects as a Task. A root is reusable as an A2A
+Context only after this adapter created it in the running exposure or one such
+Task proves its durable ownership after restart. Ordinary model Workers in the
+same workspace are neither discoverable nor adoptable through A2A. A request
+rejected before Worker admission may yield the official SDK's ephemeral failed
+Task response, but it creates no durable Task state.
+
+| Durable Plurnk state | A2A projection |
+|---|---|
+| Loop `100` | `SUBMITTED` |
+| Loop `102` or `202` | `WORKING`; parking alone does not claim user input is required |
+| Pending client interaction on the Task Loop | `INPUT_REQUIRED` |
+| Successful terminal result | `COMPLETED`; a non-empty final SEND is the `result` Artifact |
+| External cancellation / Loop `499` | `CANCELED` |
+| Other terminal failure | `FAILED` with the exact Problem detail as its status Message |
+| Prompt rows carrying the adapter's causal source | User Message history |
+
+The first exposure accepts only text Message Parts, advertises HTTP+JSON v1
+streaming without push notifications, tenants, extended cards, or security
+schemes, and rejects a card that claims unsupported security. Those omitted
+surfaces are not silently simulated. The adapter subscribes to live
+application events for streaming and reads durable Worker/Loop/log projections
+for retrieval and restart truth.
+
+§a2a-hosted-card The service generates the hosted standard Agent Card from
+normalized environment identity plus actual adapter capabilities. The adapter,
+not configuration, fixes HTTP+JSON protocol `1.0`, streaming, no push
+notifications, no extended card, no tenant, no security, `text/plain` input,
+and `text/markdown` output. Unsupported security claims are structurally absent
+rather than configurable. The official SDK serializes the card served at the
+standard well-known path.
+
+§a2a-lazy-workspace Listener startup and Agent Card discovery perform no
+workspace creation, attachment, hydration, model selection, or inference. The
+first admitted Task resolves the configured workspace name, adopting the one
+existing match or creating it with the configured project root. A configured
+non-null root must match an existing workspace exactly. The resolution is
+shared across concurrent requests and a failed resolution remains retryable.
+
+## §a2a-agents-functionality Outbound agents as Worker Functionality
+
+The package registers, through `OutboundModule`, the `a2a` resource scheme and
+one Worker Functionality family named `agents` ({§functionality-adapter} in
+core). The family is not tagged `a2a` because every executor tag is also a
+scheme face and would collide with the `a2a://` resource scheme. Its definition
+is the `A2aAgentDefinition` contract — local alias `name`, remote `url`,
+optional `cardPath`, `headers`, and symbolic bearer `authorization` —
+exactly the environment's `PLURNK_A2A_<ALIAS>*` projection.
+
+*Available definitions* are the environment's aliases; `PLURNK_A2A_ENABLED`
+supplies their default enabledness. *Admission* (`add {alias, definition}`)
+requires `alias = name`. *Discovery is inert*: `discover {source}` fetches one
+standard Agent Card from that URL only and returns one candidate whose alias
+is the card name's slug, with `agent-card` provenance; `discover
+{configuration}` projects a client's own `PLURNK_A2A_*` environment as
+`client-configuration` candidates; `discover {query}` is 501
+`registry-not-configured` until a registry is configured. Discovery never
+adds, enables, authenticates beyond the named host, or persists.
+
+*Preparation* resolves symbolic `${NAME}` references at connection
+(`authorization-unresolved` when absent), discovers and validates the standard
+Agent Card at the definition's URL (`card-unreachable`), and connects only
+through an advertised HTTP+JSON `1.0` interface (`interface-unsupported`),
+reusing an unchanged attachment across publications. The outcome detail carries
+the card's name, version, description, skill identifiers, and streaming
+capability. The family publishes no runtimes; its snapshot is the Worker's
+`alias → client` map, and the `a2a` scheme resolves an authority against the
+Functionality of the Worker the operation acts in (`ctx.functionalityWorkerId`):
+an unknown or disabled alias is 404 `agent-not-configured`, an unavailable
+alias carries its one exact preparation Problem, and two Workers may hold the
+same textual alias with different definitions and credentials.
+
+§a2a-agents-catalog **Turn 0 shows enabled agents concisely.** Preparation
+publishes one `worker://~/_plurnk/agents/<alias>.md` document per active
+alias — an H1 alias, an H2 `Summary` whose one line is
+`a2a://<alias> — <card name> v<version>: <description>`, and the invocation
+form — and nothing for disabled or unavailable aliases. Core's seventh turn-0
+survey (`## FIND0 [+init,+agents] (worker://~/_plurnk/agents/*.md) <1,-1>`,
+{§actor-boundary-catalog-preview}) therefore presents every effective agent as
+one summary row. The document embeds neither the card nor its skills; both stay
+pullable exactly through `READ a2a://<alias>` ({§a2a-outbound-definition}).
+Hosted inbound exposure ({§a2a-inbound-exposure}) is unaffected by this family.
+
+## §a2a-outbound-resources Outbound resources
+
+The `a2a` scheme is an exterior client adapter over ordinary Plurnk resource
+and subscription contracts. Its URI authority is the configured remote-agent
+alias. The adapter is not a Worker producer, scheduler, Task store, or alternate
+operation runtime.
+
+§a2a-outbound-definition An enabled outbound alias resolves through its
+Worker's `agents` Functionality snapshot ({§a2a-agents-functionality}), whose
+preparation discovered and validated the remote standard Agent Card and
+selected only an advertised HTTP+JSON `1.0` interface. The local alias,
+target, optional card path, symbolic authentication, and provenance are local
+configuration; the discovered card's identity, capabilities, skills, and
+interfaces remain remote protocol authority.
+
+| Operation | Target | Result |
+|---|---|---|
+| READ | `a2a://<agent>` | Materialize the discovered Agent Card. |
+| SEND `[200]` | `a2a://<agent>` | Send a new user Message. A direct Message creates one static `/messages/<id>` resource and returns `200`; a Task creates one live `/tasks/<id>` resource and returns `102`. |
+| SEND `[200]` | Exact `/tasks/<id>` resource | Continue the same non-terminal Task identity, including an input-required or auth-required Task. |
+| SEND `[499]` | Live Task resource | Cancel the ordinary local subscription, which requests cancellation of the remote Task. |
+| READ | Exact Task or Artifact resource | Materialize the remote resource's current canonical snapshot. |
+
+§a2a-outbound-turn-rhythm A Task-backed call composes through ordinary model
+turns rather than an adapter-authored continuation. The directed disposition
+SEND is structurally the end of its emission ({§send-mid-reservation}), but its
+target makes `[200]` the A2A operation code rather than the local Loop
+disposition. Core therefore routes the request and naturally presents its
+`102` Task receipt in the next turn. If the model then chooses to wait, a
+pathless `SEND [202]` parks the Loop; subscription completion wakes that same
+Loop with the exact terminal READ, after which a pathless `SEND [200]` may
+conclude under {§wait-obligation-matrix}. No hidden adapter turn or synthetic
+local disposition fills any step.
+
+Task-backed calls use Core's ordinary live-resource path: the scheme seeds one
+entry, opens one subscription, returns its exact address with `102`, and closes
+that subscription with the remote Task result. Core alone owns parking, waking,
+the terminal next-turn READ, and cancellation propagation.
+
+## §a2a-resource-projection Resource projection
+
+Every retained Agent Card, Message, Task, and Artifact has a model-oriented
+Markdown `#body` and an exact protocol `#json` channel serialized by the pinned
+official SDK. A Task's Artifact identities remain distinct URI descendants and
+materialize independently; the adapter never flattens multiple Artifacts into
+one fabricated result. Projection wording is presentation rather than protocol
+identity: tests assert lifecycle state, content, media type, and addressability,
+not a prose template.

package/dist/A2a.d.ts

@@ -0,0 +1,12 @@
+import type { Client } from "@a2a-js/sdk/client";
+import { type PassthroughResult, type RepresentationPreparationRequest, type RepresentationPreparationResult, type SchemeCtx, type SchemeHandler, type SchemeManifest, type SendStatement } from "@plurnk/plurnk-schemes";
+export type A2aClientResolver = (authority: string, ctx: SchemeCtx) => Client | null | Promise<Client | null>;
+/** Outbound A2A v1 resources and Task obligations over the ordinary scheme API. */
+export default class A2a implements SchemeHandler {
+    #private;
+    static manifest: SchemeManifest;
+    constructor(resolveClient: A2aClientResolver);
+    prepareRepresentation(request: RepresentationPreparationRequest, ctx: SchemeCtx): Promise<RepresentationPreparationResult>;
+    send(statement: SendStatement, ctx: SchemeCtx): Promise<PassthroughResult>;
+}
+//# sourceMappingURL=A2a.d.ts.map

package/dist/A2a.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"A2a.d.ts","sourceRoot":"","sources":["../src/A2a.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AACjD,OAAO,EAIH,KAAK,iBAAiB,EACtB,KAAK,gCAAgC,EACrC,KAAK,+BAA+B,EACpC,KAAK,SAAS,EACd,KAAK,aAAa,EAClB,KAAK,cAAc,EAEnB,KAAK,aAAa,EAErB,MAAM,wBAAwB,CAAC;AAUhC,MAAM,MAAM,iBAAiB,GAAG,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,EAAE,SAAS,KAAK,MAAM,GAAG,IAAI,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;AAe9G,mFAAmF;AACnF,MAAM,CAAC,OAAO,OAAO,GAAI,YAAW,aAAa;;IAC7C,MAAM,CAAC,QAAQ,EAAE,cAAc,CAmB7B;IAIF,YAAY,aAAa,EAAE,iBAAiB,EAE3C;IAEK,qBAAqB,CACvB,OAAO,EAAE,gCAAgC,EACzC,GAAG,EAAE,SAAS,GACf,OAAO,CAAC,+BAA+B,CAAC,CAgE1C;IAEK,IAAI,CAAC,SAAS,EAAE,aAAa,EAAE,GAAG,EAAE,SAAS,GAAG,OAAO,CAAC,iBAAiB,CAAC,CA+G/E;CAyNJ"}