@plurnk/plurnk-a2a 1.17.0 → 1.19.0

package/.env.defaults

@@ -1,7 +1,8 @@
 # @plurnk/plurnk-a2a — remote agents and optional hosted exposure.
 
 # --- Outbound agents ---
-# Initially enabled aliases, JSON array; [] = none. Workers manage their own agents Functionality.
+# An empty alias target masks its definition, companions and ENABLED selection.
+# Initially enabled workspace agent aliases, JSON array; [] = none.
 PLURNK_A2A_ENABLED=[]
 # Connection/discovery deadline, positive ms.
 PLURNK_A2A_CONNECT_TIMEOUT=30000
@@ -15,21 +16,24 @@ PLURNK_A2A_ERROR_DETAIL_LIMIT=512
 # PLURNK_A2A_research_BEARER=${A2A_RESEARCH_TOKEN}
 # PLURNK_A2A_research_HEADERS={"X-Tenant":"${A2A_RESEARCH_TENANT}"}
 
-# --- Inbound exposure (unauthenticated; protect nonlocal deployments externally) ---
-# 1 = expose a Plurnk agent; 0 = off. Protocol capabilities come from the implementation.
+# --- Inbound exposure ---
+# 1 = expose a Plurnk agent on the service listener (PLURNK_HOST:PLURNK_PORT); 0 = off. Protocol
+# capabilities come from the implementation.
 PLURNK_A2A_EXPOSE=0
-# Listener bind address.
-PLURNK_A2A_HOST=127.0.0.1
-# Listener TCP port; 0 = choose an available port.
-PLURNK_A2A_PORT=4100
+# Bearer required on the endpoint, declared by the card; empty = an unauthenticated exposure, so
+# protect a nonlocal deployment externally. The card at /.well-known/agent-card.json is public.
+PLURNK_A2A_TOKEN=
 # Absolute endpoint URL pathname, without query or fragment.
 PLURNK_A2A_ENDPOINT_PATH=/a2a
-# Public HTTP(S) endpoint advertised in the card; empty = derive from listener.
+# Public HTTP(S) endpoint advertised in the card; empty = derive from the service listener.
 PLURNK_A2A_ENDPOINT_URL=
 # Workspace used for inbound tasks.
 PLURNK_A2A_WORKSPACE=a2a
 # Absolute project root for a new inbound workspace; empty = headless.
 PLURNK_A2A_PROJECT_ROOT=
+# What an inbound task's loop does with a proposal: accept applies it, reject refuses it.
+# A2A carries no review channel, so review is not a choice here.
+PLURNK_A2A_PROPOSALS=reject
 # Agent card name; required when EXPOSE=1.
 PLURNK_A2A_NAME=
 # Agent card description; required when EXPOSE=1.

package/README.md

@@ -10,7 +10,7 @@ HTTP+JSON v1 binding.
 
 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
+Plurnk environment cascade. Enable the exposure and describe its public
 identity in an operator or project `.env`:
 
 ```dotenv
@@ -22,11 +22,13 @@ 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.
+The module mounts the Agent Card at `/.well-known/agent-card.json` and the
+advertised HTTP+JSON interface at `/a2a` on the service listener
+(`PLURNK_HOST:PLURNK_PORT`); it opens no socket of its own. With
+`PLURNK_A2A_TOKEN` set, the card declares an HTTP bearer scheme and the
+interface requires that bearer; the card itself stays public. Starting the
+service or reading the card does not create or hydrate the named workspace;
+the first admitted Task does so.
 
 ## Connect to an agent
 
@@ -45,23 +47,24 @@ PLURNK_A2A_RESEARCH_BEARER=${A2A_RESEARCH_TOKEN}
 PLURNK_A2A_ENABLED=["research"]
 ```
 
-In the service those definitions are the baseline of the workspace `agents`
+In the service those definitions are the baseline of the workspace `a2a`
 Functionality family (`OutboundModule`): every Worker lists, discovers, adds,
 enables, disables, and removes outbound agents through the common
-`workspace.agents.*` actions or the generated ```` ```agents ```` manager, and the
+`workspace.a2a.*` actions or the generated ```` ```a2a ```` manager, and the
 `a2a://<alias>` scheme resolves an alias against the workspace's enabled
-snapshot. Enabled agents appear in Turn 0 as one `worker:///_plurnk/agents/<alias>.md`
+snapshot. Enabled agents appear in Turn 0 as one `worker:///_plurnk/a2a/<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, in the operation's workspace, to
-one client while keeping alias and credential policy outside the
+The package also exports the scheme's live face for embedding: a runtime named
+`a2a` carries it as its `scheme`, and it claims every coordinate that opens
+with an alias. Its resolver maps each URI authority, in the operation's
+workspace, 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) =>
+const face = new A2a(async (alias, ctx) =>
     alias === "research" && ctx.workspaceId === 1 ? await connectHttpJsonAgent("https://agent.example") : null);
 ```
 

package/SPEC.md

@@ -17,10 +17,10 @@ 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 the workspace's `agents` family ({§a2a-agents-functionality}); workspace state may override enabledness. |
+| Outbound defaults | `PLURNK_A2A_ENABLED` | JSON array selecting the exact aliases enabled by default for the workspace's `a2a` family ({§a2a-functionality}); workspace state may override enabledness. `[]` is the one spelling of none: an absent or empty key is refused by name. |
 | Timeouts | `PLURNK_A2A_CONNECT_TIMEOUT`, `PLURNK_A2A_REQUEST_TIMEOUT` | Positive integer milliseconds owned by the A2A package. |
 | Diagnostics | `PLURNK_A2A_ERROR_DETAIL_LIMIT` | Non-negative character bound for one caught upstream diagnostic admitted to a model-facing A2A Problem; complete causes remain internal. |
-| Inbound listener | `PLURNK_A2A_EXPOSE`, `_HOST`, `_PORT`, `_ENDPOINT_PATH`, `_ENDPOINT_URL` | `EXPOSE=1` admits one optional HTTP+JSON listener; `0` admits none. |
+| Inbound exposure | `PLURNK_A2A_EXPOSE`, `_TOKEN`, `_ENDPOINT_PATH`, `_ENDPOINT_URL` | `EXPOSE=1` mounts one HTTP+JSON exposure on the service listener ({§http-host}); `0` mounts none. `_TOKEN` is the bearer the endpoint requires and the card declares ({§a2a-hosted-bearer}); empty is an unauthenticated exposure. |
 | 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. |
 
@@ -30,6 +30,11 @@ 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.
 
+An explicitly empty outbound target omits that definition, ignores its companion
+values and drops its inherited `ENABLED` selection. It does not remove a
+workspace-owned definition or prohibit adding one. Genuinely undeclared aliases
+and case-fold collisions still fail validation.
+
 ## §a2a-protocol-witness Protocol witness
 
 The integration witness places a discovery-first client and an independent
@@ -44,8 +49,11 @@ 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;
+The inbound HTTP+JSON exposure is an exterior adapter over
+`ApplicationPort`, mounted on the daemon's one listener ({§http-host}): the
+public Agent Card at the standard well-known path and the interface at
+`PLURNK_A2A_ENDPOINT_PATH`, both on the service address, and it opens no
+socket of its own. 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.
@@ -60,58 +68,94 @@ flowchart LR
 ```
 
 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
+already satisfy Plurnk's worker-name contract ({§worker-name}), 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,
+Only a child Worker with a durable message 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.
+same workspace are neither discoverable nor adoptable through A2A. Foreign
+Task identities that cannot name a local Worker are unknown Tasks, not Core
+validation failures. Unsupported Message content and invalid answers to a
+pending interaction are rejected before execution with the standard protocol
+error; they do not create Workers or alter an existing Task. Other executor
+failures follow the SDK's failed-Task behavior.
 
 | 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 |
+| Successful terminal result | `COMPLETED`; the current Loop's last non-empty delivered reply from message history is the `result` Artifact. The lifecycle result is not a message body. |
 | 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
+| Inbox messages carrying the adapter's causal source | Complete admitted user Message history from {§message-envelope-evidence}, including accepted interaction answers; independent of log curation and publication. |
+| Delivered replies answering this Task's A2A messages | Only replies whose `answers` name this Task's A2A messages contribute text or attachments. Native or other-protocol replies do not become A2A Artifacts. |
+| Such replies' attachment receipts | Distinct standard Artifacts holding send-time bytes from {§send-resource-attachments}, independent of later source changes. |
+
+The exposure accepts text, data, URL, and raw Message Parts, advertises HTTP+JSON v1
+streaming without push notifications, tenants, or extended cards, declares no
+security beyond the bearer it enforces ({§a2a-hosted-bearer}), and rejects a
+card that claims any security of its own. 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
+notifications, no extended card, no tenant, the security it enforces
+({§a2a-hosted-bearer}), and `*/*` input/output.
+Arbitrary media are resources; native model interpretation still depends on its route.
+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
+§a2a-hosted-bearer With `PLURNK_A2A_TOKEN` set, the card declares one `http`
+bearer scheme as its whole security requirement, and the endpoint refuses any
+request without that exact bearer — `401`, `UNAUTHENTICATED`,
+`WWW-Authenticate: Bearer`, in the binding's own error shape — before the SDK
+reads anything. The card at the well-known path is never behind the bearer, so a
+caller can discover the scheme. Empty is an unauthenticated exposure: the panel
+states it, the adapter never infers it.
+
+§a2a-hosted-proposals A2A carries no review channel, so an inbound Task's loop
+settles its own proposals: `PLURNK_A2A_PROPOSALS` states `accept` or `reject`,
+and `review` is outside its vocabulary. That one field is all the adapter states
+about the loop's policy; attendance is the daemon's to supply, because a remote
+agent can answer an interaction through `input-required`.
+
+§a2a-lazy-workspace Mounting the exposure, Agent Card discovery, Task observations,
+and rejected Task lookups perform no workspace creation, attachment, hydration,
+model selection, or inference. An absent workspace yields an empty Task list or
+the standard Task-not-found result, not implicit creation. 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 workspace Functionality
+### §a2a-task-listing Task listing
 
-The package registers, through `OutboundModule`, the `a2a` resource scheme and
-one workspace 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
+`ListTasks` follows the [A2A listing contract](https://a2a-protocol.org/latest/specification/#314-list-tasks),
+not the Worker directory's creation order.
+
+| Concern | Projection |
+|---|---|
+| Ordering | Status timestamp descending; equal or absent timestamps use Task ID ascending. Absent timestamps sort last. |
+| Pagination | Opaque cursor after the last returned timestamp/ID, not an offset. Newer Tasks do not shift subsequent pages. This is a live listing, not a frozen snapshot. |
+| Filtering | Context, state, and inclusive status timestamp bound apply before paging; `totalSize` counts the filtered Tasks. |
+| Content | Artifacts are omitted unless requested; the SDK applies the requested history limit. |
+| Invalid cursor | Standard `RequestMalformedError`; never silently restart at the first page. |
+
+## §a2a-functionality Outbound agents as workspace Functionality
+
+The package registers, through `OutboundModule`, one workspace Functionality
+family named `a2a` ({§functionality-adapter} in core): the package, its keys,
+the family and the scheme share one name. 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.
@@ -132,9 +176,10 @@ 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 workspace's
-`alias → client` map, and the `a2a` scheme resolves an authority against the
-Functionality of the operation's workspace (`ctx.workspaceId`):
+capability. The family publishes no runtimes of its own; its snapshot is the
+workspace's `alias → client` map, and its scheme face ({§a2a-scheme-face})
+resolves an authority against the Functionality of the operation's workspace
+(`ctx.workspaceId`):
 an unknown or disabled alias is 404 `agent-not-configured`, an unavailable
 alias carries its one exact preparation Problem. Every worker in a workspace
 resolves the same alias definition; independent workspaces may differ.
@@ -145,12 +190,12 @@ prose. A decision-relevant caught configuration, discovery, or interface
 diagnostic is admitted only through `PLURNK_A2A_ERROR_DETAIL_LIMIT`; the exact
 cause remains attached for daemon diagnostics.
 
-§a2a-agents-catalog **Turn 0 shows enabled agents concisely.** Preparation
-publishes one `worker:///_plurnk/agents/<alias>.md` document per active
+§a2a-catalog **Turn 0 shows enabled agents concisely.** Preparation
+publishes one `worker:///_plurnk/a2a/<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 (```` ```FIND (worker:///_plurnk/agents/*.md) <1,-1> ````,
+survey (```` ```FIND (worker:///_plurnk/a2a/*.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}).
@@ -163,8 +208,21 @@ 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-scheme-face **The scheme is the live half of the family's own runtime.**
+Every executor tag is a scheme of the same name, so the `a2a` manager and the
+`a2a://` resources are one scheme with two halves ({§runtime-resource-binding}
+in core). The manager's stored executions keep `a2a:///<loop>/<turn>/<sequence>`,
+numeric throughout; the package's face claims every other coordinate — one that
+opens with an agent alias, or with `contexts` for a hosted message — and owns
+READ, FIND preparation and SEND there; KILL of a live Task is the ordinary
+stream control. The face declares its own representation — resource authority,
+`#body` and `#json` — so a resource keeps the one address `a2a://planner/tasks/7`
+in what the model writes, in its log, and in the wake that concludes a Task.
+The family states the `web` trait, so a capability policy that selects on it
+covers the manager and every resource alike.
+
 §a2a-outbound-definition An enabled outbound alias resolves through its
-workspace's `agents` Functionality snapshot ({§a2a-agents-functionality}), whose
+workspace's `a2a` Functionality snapshot ({§a2a-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
@@ -180,11 +238,11 @@ interfaces remain remote protocol authority.
 | READ | Exact Task resource | Materialize the remote Task's current canonical snapshot. |
 | READ | Stored Artifact resource | Read the workspace's retained bytes without requiring an active agent connection. |
 
-§a2a-outbound-turn-rhythm SEND delivers a Message; TASK independently declares
-the local Loop's inventory under {§task-inventory-intent}. A Task-backed SEND
-creates an ordinary live obligation. An `in_progress` inventory continues work;
-a `waiting` inventory joins that obligation. Subscription settlement wakes the
-same Loop with its terminal READ, and a later terminal inventory concludes
+§a2a-outbound-turn-rhythm SEND delivers a Message; lifecycle verbs independently
+declare the local Loop's intent under {§turn-disposition}. A Task-backed SEND
+creates an ordinary live obligation. Ordinary operations continue work;
+WAIT joins that obligation. Subscription settlement wakes the
+same Loop with its terminal READ, and an answered, observed and settled loop concludes
 under {§wait-obligation-matrix}. KILL cancels through that same subscription.
 No adapter-authored turn or alternate disposition path fills any step.
 
@@ -193,6 +251,14 @@ 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.
 
+Reaching a remote agent is a host effect, so the SEND proposes first
+({§http-outbound-proposes}) and the seeding above happens on the settlement. The
+`102` is then what the applied operation returns to the settlement, not what the
+model reads: an accepted proposal answers `200` ({§proposal-accept-applies}), so
+the Task's first snapshot arrives by ordinary observation of the resource rather
+than on the SEND row. The model sees the same canonical entry either way, one
+turn later; a rejected proposal reaches no agent at all.
+
 §a2a-outbound-replay A card or resource READ and connection discovery are
 replay-safe observations. A SEND is not: once dispatch begins, a transport or
 stream-protocol failure cannot prove that the remote agent rejected the
@@ -202,6 +268,41 @@ automatic identical replay that could duplicate remote work.
 
 ## §a2a-resource-projection Resource projection
 
+§a2a-hosted-message-resources Hosted input uses the ordinary inbox and
+{§send-resource-attachments}, not the outbound alias resolver. An incoming
+caller needs neither an Agent Card nor a configured remote alias.
+
+| Input Part | Model-facing arrival |
+|---|---|
+| Text | Authored text. |
+| Data | Pretty-printed JSON. |
+| URL | Literal supplied URL; no arrival-time fetch. |
+| Raw | Link to `worker://<task>/attachments/<eight-character-id>/<name>`, with ordinary typed bytes; unnamed/colliding names use {§resource-publication-names}. |
+
+The complete admitted SDK SendMessageRequest envelope preserves configuration,
+request metadata, and its inner Message's Part order, media types, filenames,
+metadata, and assigned Task/Context identity. Accepted interaction
+answers enter that same evidence path before the operation resumes; invalid
+answers do not. Task history selects the envelope's inner Message, including
+those awaiting log publication. Derived status Messages describe the current
+pending interaction or terminal Problem; they are not additional inbox arrivals.
+Task retrieval reconstructs these facts after adapter/daemon restart.
+
+§a2a-response-preferences Nonempty `configuration.acceptedOutputModes` appears
+as labeled response preferences beside the model-facing arrival, for normal
+requests and accepted interaction answers. Omitted or empty preferences add
+nothing. This projection neither edits the protocol Message nor changes
+interaction validation. Other request configuration remains adapter-owned;
+opaque request metadata is evidence, not additional instructions. Preferences
+do not relabel source bytes or promise an unavailable output representation.
+
+Explicit resource selections in a hosted worker's targetless SEND become
+standard raw-Part Artifacts, one per selected resource in order. Artifact IDs
+are stable within the Task. The ordinary final textual result retains its
+`result` Artifact. A directed A2A SEND instead transmits its selected resources
+as raw Parts of that user Message. Resource creation and READ never export;
+the selected send-time snapshot survives both source mutation and log curation.
+
 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
@@ -209,3 +310,20 @@ 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.
+
+§a2a-part-resources Received raw Parts are ordinary typed resources, not base64
+placeholders. Their parent Message or Artifact links to them in Part order;
+the exact protocol JSON remains independently readable.
+
+| Part | Ordinary resource projection |
+|---|---|
+| Text / structured data | Text / pretty JSON in the parent body. |
+| URL | The supplied URL; arrival does not fetch it or bypass its scheme's acquisition policy. |
+| Raw bytes | `<parent>/resources/<name>` with exact bytes and media type (or `application/octet-stream` if absent). Supplied names and stable eight-character fallback names use {§resource-publication-names}. |
+
+A received Task snapshot retains its Artifacts and Messages with their Part
+resources before publishing links or settling its subscription. Retained
+Message, Artifact, and Part READs need no active remote connection. READ alone
+controls native attachment delivery through {§packet-attachment-parts}; listing
+a resource does not inject its bytes into model context. Log curation does not
+delete the retained source.

package/dist/A2a.d.ts

@@ -1,12 +1,26 @@
 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";
+import { type PassthroughResult, type ProposalResult, type ProposalApplyRequest, type ProposalApplyResult, type RepresentationPreparationRequest, type RepresentationPreparationResult, type SchemeCtx, type SchemeResult, type SendStatement, type FindStatement } 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 {
+/**
+ * {§a2a-scheme-face} Outbound A2A v1 resources and Task obligations: the live half of the `a2a`
+ * runtime's scheme. The family manager's stored executions keep `a2a:///<loop>/<turn>/<sequence>`;
+ * every other coordinate opens with an agent alias, or with `contexts` for a hosted message.
+ */
+export default class A2a {
     #private;
-    static manifest: SchemeManifest;
+    readonly manifest: {
+        readonly authority: "resource";
+        readonly channels: {
+            readonly body: "text/markdown";
+            readonly json: "application/json";
+        };
+        readonly defaultChannel: "body";
+    };
+    claims(pathname: string): boolean;
+    prepareFind(_statement: FindStatement, ctx: SchemeCtx): Promise<SchemeResult>;
     constructor(resolveClient: A2aClientResolver);
     prepareRepresentation(request: RepresentationPreparationRequest, ctx: SchemeCtx): Promise<RepresentationPreparationResult>;
-    send(statement: SendStatement, ctx: SchemeCtx): Promise<PassthroughResult>;
+    send(statement: SendStatement, ctx: SchemeCtx): Promise<PassthroughResult | ProposalResult>;
+    applyResolution(request: ProposalApplyRequest, ctx: SchemeCtx): Promise<ProposalApplyResult>;
 }
 //# sourceMappingURL=A2a.d.ts.map

package/dist/A2a.d.ts.map

@@ -1 +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;AAShC,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,CAa7B;IAIF,YAAY,aAAa,EAAE,iBAAiB,EAE3C;IAEK,qBAAqB,CACvB,OAAO,EAAE,gCAAgC,EACzC,GAAG,EAAE,SAAS,GACf,OAAO,CAAC,+BAA+B,CAAC,CAsE1C;IAEK,IAAI,CAAC,SAAS,EAAE,aAAa,EAAE,GAAG,EAAE,SAAS,GAAG,OAAO,CAAC,iBAAiB,CAAC,CA4G/E;CAyNJ"}
+{"version":3,"file":"A2a.d.ts","sourceRoot":"","sources":["../src/A2a.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AACjD,OAAO,EAMH,KAAK,iBAAiB,EACtB,KAAK,cAAc,EACnB,KAAK,oBAAoB,EACzB,KAAK,mBAAmB,EACxB,KAAK,gCAAgC,EACrC,KAAK,+BAA+B,EACpC,KAAK,SAAS,EACd,KAAK,YAAY,EACjB,KAAK,aAAa,EAGlB,KAAK,aAAa,EACrB,MAAM,wBAAwB,CAAC;AAQhC,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;;;;GAIG;AACH,MAAM,CAAC,OAAO,OAAO,GAAG;;IAEpB,QAAQ,CAAC,QAAQ;iBACb,SAAS,EAAE,UAAU;iBACrB,QAAQ;qBAAI,IAAI,EAAE,eAAe;qBAAE,IAAI,EAAE,kBAAkB;;iBAC3D,cAAc,EAAE,MAAM;MACf;IASX,MAAM,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAEhC;IAEK,WAAW,CAAC,UAAU,EAAE,aAAa,EAAE,GAAG,EAAE,SAAS,GAAG,OAAO,CAAC,YAAY,CAAC,CAElF;IAID,YAAY,aAAa,EAAE,iBAAiB,EAE3C;IAEK,qBAAqB,CACvB,OAAO,EAAE,gCAAgC,EACzC,GAAG,EAAE,SAAS,GACf,OAAO,CAAC,+BAA+B,CAAC,CA0E1C;IAMK,IAAI,CAAC,SAAS,EAAE,aAAa,EAAE,GAAG,EAAE,SAAS,GAAG,OAAO,CAAC,iBAAiB,GAAG,cAAc,CAAC,CA8BhG;IAEK,eAAe,CAAC,OAAO,EAAE,oBAAoB,EAAE,GAAG,EAAE,SAAS,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAmBjG;CAuVJ"}