@plurnk/plurnk-a2a 1.17.0 → 1.19.0

package/docs/a2a.md

@@ -1,22 +1,61 @@
-# A2A
+# a2a
 
-## Summary
+An A2A agent is another agent reachable over HTTP that advertises an Agent
+Card. Once added, it is addressed as `a2a://<alias>` and worked like a worker
+you cannot see inside: `SEND` it a task, wait for its result, `READ` what it
+returned. It is not a tool with a schema; it is a peer that takes instructions
+in prose.
 
-Call configured A2A v1 agents and retain their current Messages, Tasks, and
-Artifacts as addressable Plurnk resources.
+## When to reach for an agent
 
-## Invocation
+- The user names an agent, or the turn-0 catalog lists an enabled one whose
+  card describes the job at hand. `READ (a2a://<alias>)` shows its card and
+  skills before you commit work to it.
+- Delegation you could do yourself with a worker (`WORK`) stays a worker:
+  an agent is for capability that lives elsewhere.
 
-````SEND (a2a://researcher)
-Compare the two proposals and return a recommendation with evidence.
+## discover, then add
+
+`discover` takes `{"source": "<agent base URL>"}`, fetches the Agent Card, and
+returns one inert candidate carrying the exact definition. `add` persists and
+enables it for this workspace (a host effect, run on acceptance):
+
+````a2a (add)
+{"alias": "planner", "definition": {"name": "planner", "url": "https://agents.example.com/planner"}}
+````
+
+Authentication is the definition's business (headers or a token the operator
+configured), never something you type into a body. An agent whose card is
+unreachable is listed `unavailable` with its exact Problem. `disable` and
+`remove` follow the family lifecycle; operator-configured agents
+(`PLURNK_A2A_*`) can only be disabled.
+
+## Working with an added agent
+
+````SEND (a2a://planner) <!-- start a task -->
+Compare the two proposals in docs/ and return a recommendation with evidence.
 ````
 
-`SEND` to an agent root starts new work. A Task response returns `102` and an
-exact `a2a://<agent>/tasks/<id>` resource; a direct Message returns `200` and an
-exact `a2a://<agent>/messages/<id>` resource. Continue an interrupted Task by
-sending the requested input to its Task resource.
+A task answers `102` with its `a2a://planner/tasks/<id>` resource and wakes
+your next turn when it concludes; a direct message answers `200` with an
+`a2a://planner/messages/<id>` resource. `READ` the task for its status,
+artifacts, and any input it requests; `SEND` to the task resource to continue
+it; `KILL` it to cancel, which also asks the remote agent to stop.
+
+A task resource defaults to a concise `#body` and keeps the protocol snapshot
+in `#json`. Its Artifacts and binary Parts are retained as linked resources;
+`READ` a link to inspect its content. Supplied URLs are not fetched on arrival.
+
+## Attachments
+
+````SEND (a2a://planner) [{"attachments":["report.pdf","data/results.json"]}]
+Review these results.
+````
 
-Task resources default to a concise `#body` and retain the protocol snapshot in
-`#json`. Their Artifact addresses are listed in the body and materialize on
-READ. ````` ````KILL ````` of a live Task resource cancels the local obligation and
-requests remote cancellation.
+Select exact resource paths or channels. SEND captures their current bytes;
+creating or reading a file alone never sends it. A missing source fails the
+SEND before delivery. To answer an incoming A2A request with files, omit the
+target and use the same attachment option. The caller receives standard
+Artifacts. Incoming files arrive as ordinary resource links; READ them normally.
+Incoming response-format preferences appear beside the message when supplied.
+Attachment media types remain those of the selected resources.

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@plurnk/plurnk-a2a",
-    "version": "1.17.0",
+    "version": "1.19.0",
     "description": "A2A v1 exterior adapter for Plurnk",
     "type": "module",
     "license": "MIT",
@@ -30,8 +30,8 @@
     "scripts": {
         "test": "npm run test:lint && npm run test:unit && npm run test:intg",
         "test:lint": "tsc --noEmit",
-        "test:unit": "node --conditions=plurnk-dev --test src/*.test.ts",
-        "test:intg": "node --conditions=plurnk-dev --test test/intg/*.test.ts",
+        "test:unit": "node --conditions=plurnk-dev --env-file=.env.defaults --test src/*.test.ts",
+        "test:intg": "node --conditions=plurnk-dev --env-file=.env.defaults --test test/intg/*.test.ts",
         "build:clean": "rm -rf dist",
         "build:dist": "tsc -p tsconfig.build.json",
         "build": "npm run build:clean && npm run build:dist",
@@ -39,12 +39,12 @@
         "prepublishOnly": "npm audit --audit-level=moderate && npm test"
     },
     "dependencies": {
-        "@a2a-js/sdk": "1.1.0",
+        "@a2a-js/sdk": "1.2.0",
         "express": "5.2.1"
     },
     "peerDependencies": {
-        "@plurnk/plurnk-contracts": "^1.17.0",
-        "@plurnk/plurnk-schemes": "^1.17.0"
+        "@plurnk/plurnk-contracts": "^1.19.0",
+        "@plurnk/plurnk-schemes": "^1.19.0"
     },
     "devDependencies": {
         "@types/express": "5.0.6"

package/docs/agents.md

@@ -1,42 +0,0 @@
-# agents
-
-An A2A agent is another agent reachable over HTTP that advertises an Agent
-Card. Once added, it is addressed as `a2a://<alias>` and worked like a worker
-you cannot see inside: `SEND` it a task, wait for its result, `READ` what it
-returned. It is not a tool with a schema; it is a peer that takes instructions
-in prose.
-
-## When to reach for an agent
-
-- The user names an agent, or the turn-0 catalog lists an enabled one whose
-  card describes the job at hand. `READ (a2a://<alias>)` shows its card and
-  skills before you commit work to it.
-- Delegation you could do yourself with a worker (`WORK`) stays a worker:
-  an agent is for capability that lives elsewhere.
-
-## discover, then add
-
-`discover` takes `{"source": "<agent base URL>"}`, fetches the Agent Card, and
-returns one inert candidate carrying the exact definition. `add` persists and
-enables it for this workspace (a host effect, run on acceptance):
-
-````agents (add)
-{"alias": "planner", "definition": {"name": "planner", "url": "https://agents.example.com/planner"}}
-````
-
-Authentication is the definition's business (headers or a token the operator
-configured), never something you type into a body. An agent whose card is
-unreachable is listed `unavailable` with its exact Problem.
-
-## Working with an added agent
-
-````SEND (a2a://planner) <!-- start a task -->
-Compare the two proposals in docs/ and return a recommendation with evidence.
-````
-
-A task answers `102` with its `a2a://planner/tasks/<id>` resource and wakes
-your next turn when it concludes; a direct message answers `200` with an
-`a2a://planner/messages/<id>` resource. `READ` the task for its status,
-artifacts, and any input it requests; `SEND` to the task resource to continue
-it; `KILL` it to cancel. `disable` and `remove` follow the family lifecycle;
-operator-configured agents (`PLURNK_A2A_*`) can only be disabled.