@amaster.ai/dsh-a2a 0.1.34 → 0.1.35

package/README.md

@@ -14,11 +14,21 @@ dsh plugin --profile my-agent add @amaster.ai/dsh-a2a
 
 ## Native inbox execution
 
-`inbox.enabled: true` uses the official DSH inbox (`Agent.send`) for ordinary `next-turn` input and `next-step` steering. Tested with the unmodified npm runtime `0.2.1-rc.4`; no core patch is required. The queue and its durable projection belong to DSH. The plugin only materializes messages, attaches A2A task identities, and translates execution events.
+`inbox.enabled: true` uses the official DSH inbox (`Agent.send`) for ordinary `next-turn` input and `next-step` steering. Tested with the unmodified npm runtime `0.2.1-rc.5`; no core patch is required. The queue and its durable projection belong to DSH. The plugin only materializes messages, attaches A2A task identities, and translates execution events.
 
-Standard `SendMessage` / `SendStreamingMessage`, task queries, cancellation and subscriptions remain the wire interface. The negotiated inbox extension forwards `target` and `wakeup` to DSH. `wakeup: false` leaves an idle driver parked; it does not prevent an active driver from consuming pending input. A later real waking message releases pending input.
+Standard `SendMessage` / `SendStreamingMessage`, task queries, cancellation and task subscriptions keep their official meanings. The negotiated inbox extension forwards `target` and `wakeup` to DSH. `wakeup: false` leaves an idle driver parked; it does not prevent an active driver from consuming pending input. A later real waking message releases pending input.
 
-The same-process `a2aInbox` service exposes `resolve(contextId)`, `content(message, contextId)`, `enqueue(taskId, message, { target?, wakeup? })`, `promote(contextId, nativeMessageId, activeTaskId)`, and `cancel(taskId)`. There is no separate pause, wake-only, resume, or retained-task restart operation. Cancellation is terminal and removes that task's pending input. Other tasks' input is retained according to official DSH cancellation semantics, and may wait for the next waking message. Clearing a context discards all its pending work.
+The same-process `a2aInbox` service exposes `resolve`, `content`, `enqueue`, `promote`, `cancel`, `get`, `update`, `move`, `remove`, `clearPending`, and `executePending`, plus the existing pause/wake/resume controls. Pending-only clearing preserves active work; context clearing discards all work.
+
+For external clients, the [native inbox extension specification](#native-inbox-extension-v1) defines `dsh/inbox/get`, `update`, `move`, `remove`, `clear`, `execute`, `steer`, and `subscribe` at the advertised JSONRPC endpoint. Activate it with the `A2A-Extensions` header set to the extension URI. Updates use standard A2A 1.0 user Messages; operations address native inbox IDs. REST/gRPC clients use the advertised JSONRPC endpoint for these extension methods. No extra queue or consumer is created.
+
+`dsh/inbox/subscribe` streams checkpointed invalidations `{contextId, version}` over SSE, including native consumption and edits. It registers before its initial checkpoint and sends only after owner-scoped `ctx.sessions.flush()` returns true. A false/rejected checkpoint sends no success notification. Re-read the live inbox on invalidation and reconnect; there is no replay or durable outbox. Slow clients disconnect instead of accumulating notifications. To publish the same invalidations to host listeners on `a2a/inbox-checkpointed` without an SSE subscriber, enable `inbox.notifications: true` (default false). Hosts retain authentication, authorization and product-specific fan-out.
+
+Existing native agents keep their setup and lifecycle owner. Reading/subscribing does not block their producers. Plugin shutdown detaches its own queued A2A inputs from a borrowed agent, retaining recovery data when configured; native work and the caller's agent remain available.
+
+Wire snapshots are paginated: 50 entries by default, `pageSize: 1..100`, with `totalSize` and `nextPageToken`. Read `dsh/inbox/get` until the token is empty, traversing next-step before next-turn. Any session-version change invalidates the cursor; restart from the first page. Mutations accept `pageSize` and return the first page. Same-process calls without page options still return the full snapshot. Adjacent reorders log only their affected interval, and slow notification checkpoints keep one pending version/error observer per batch.
+
+The `E2E (dsh-a2a.inbox-api)` matrix leg installs the packed plugin into the pinned CLI and uses the real model gateway. It checks queue editing/reordering/removal/clearing, execution and steering, two checkpointed SSE subscribers, native consumption, and model recall in a subsequent context turn. A local loopback forwarder only gates the first model request to make steering deterministic; it never generates model responses.
 
 `a2a/before-followup` validates admission; `a2a/before-step` runs at the official pre-step boundary, after system-prompt assembly and before model execution. It cannot change the already assembled system prompt. Original request headers remain process-local. DSH persistence restores its own pending projection; the plugin does not replay splice logs or recover consumed claims. Graceful disposal cancels tasks by default; `inbox.shutdown: retain-pending` opts into the retention policy below. Durable A2A task snapshots require a filesystem, Redis or GCS TaskStore; an in-memory store is sufficient without restart requirements.
 
@@ -65,6 +75,109 @@ node .github/scripts/check-inbox.mjs -t 'native ownership'
 DSH_NATIVE_OWNERSHIP_LANGFUSE_LIVE=true node .github/scripts/check-inbox.mjs -t 'native ownership.*reports Goal continuation'
 ```
 
+## Native inbox extension v1
+
+Stable protocol identifier: `https://github.com/TGYD-helige/dsh-plugins/blob/main/docs/protocol/inbox-v1.md`
+
+The identifier stays unchanged for existing messages and retained task metadata;
+this README is the canonical specification. Agent Card extension params advertise
+`documentationUrl` pointing to this section.
+
+This is a project extension, not an official A2A extension. It follows the
+[A2A extension mechanism](https://a2a-protocol.org/v1.0.1/topics/extensions/).
+The Agent Card advertises it when `inbox.enabled` is true. Activate it with the
+`A2A-Extensions` HTTP header. Responses echo that header. Standard task methods,
+states, subscriptions and Push configurations keep their official meanings.
+
+### Methods
+
+Send JSON-RPC 2.0 requests to the advertised JSONRPC endpoint. All methods take
+`contextId`. IDs named `id` below are **native inbox message IDs**, not task IDs.
+The extension adds no REST or gRPC service; those clients can discover and use
+the advertised JSONRPC endpoint for these operations.
+
+| Method | Additional parameters | Result |
+| --- | --- | --- |
+| `dsh/inbox/get` | Optional `pageSize`, `pageToken` | Live inbox snapshot page |
+| `dsh/inbox/update` | `id`, `message` (A2A 1.0 user Message) | Updated snapshot |
+| `dsh/inbox/move` | `id`, `index` (zero-based destination in the same list) | Updated snapshot |
+| `dsh/inbox/remove` | `id` | Updated snapshot |
+| `dsh/inbox/clear` | — | Snapshot after clearing pending input |
+| `dsh/inbox/execute` | Optional `id` to move first in the next-turn list | Snapshot after waking pending work |
+| `dsh/inbox/steer` | `id`, `taskId` (active target) | Snapshot after promotion |
+| `dsh/inbox/subscribe` | — | SSE JSON-RPC result stream of `{contextId, version}` |
+
+A snapshot is `{contextId, version, nextTurn, nextStep, totalSize, nextPageToken}`. Each entry is
+`{id, message, editable}`: `message` uses the standard A2A 1.0 Message JSON shape.
+Native inputs without A2A ownership expose text and have `editable: false`;
+editing them requires the originating producer. Queue removal/reordering still
+uses native IDs. Updates preserve native/protocol IDs, context and task ownership;
+they cannot replace message identity or edit already claimed input. Index is
+evaluated after removing the selected item. Execute preserves other pending
+items and their order; steer reuses the existing task-ownership promotion rules.
+Explicit execution also drives native-producer input without inventing an A2A
+Task for it; its conversation events remain in the native session history.
+Reading or subscribing does not gate input from native producers. An already
+live native agent is reused with its existing setup and lifecycle owner. Plugin
+shutdown leaves native work running; it detaches plugin-owned queued A2A input,
+retaining it in task metadata only under the configured retention policy.
+Clearing pending input does not cancel an active turn; use standard CancelTask
+for task cancellation. Removed independent queued tasks become canceled.
+
+HTTP snapshots default to 50 entries, with `pageSize` from 1 to 100. Pages also
+limit serialized entries to about 1 MiB; one oversized Message is returned intact
+to ensure progress, so a page may contain fewer items than requested. All mutation
+methods accept `pageSize` for their returned first page; invalid values reject
+before changing the queue. Pages traverse `nextStep` before `nextTurn`, keeping
+native order within each list. Continue via `dsh/inbox/get` and `nextPageToken`
+until the token is empty. Tokens bind the context and session version; a changed
+version rejects stale tokens instead of silently skipping or duplicating input.
+Re-read from the first page after invalidation. Same-process `get(contextId)`
+and mutation calls without page options retain full-snapshot behavior; passing
+`{pageSize}` opts into bounded materialization there too.
+
+Reordering uses one atomic native splice over only the affected interval;
+executing an input already at the head skips the reorder. Notifications retain
+one pending version and one error observer per context checkpoint batch,
+including when a slow checkpoint sees many changes.
+
+Methods use SDK JSON-RPC error serialization. Invalid parameters and stale
+claims are RequestMalformedError; missing extension activation is
+ExtensionSupportRequiredError. Unknown extension methods return method-not-found.
+No tenant namespace or authorization model is added: sessions are native DSH
+contexts. The host must authenticate/authorize access before exposing this
+loopback-default server. A nonempty tenant is rejected for these methods.
+
+### Checkpointed invalidation
+
+`version` is a session event sequence (last included event, initially -1), not a
+task revision. Snapshots describe the live queue and may include newer changes
+than a previously notified checkpoint. Do not treat a snapshot as a durability
+acknowledgement. Mutation failures may occur after a native mutation; re-read
+the authoritative queue before retrying. Same-process host observers opt in with
+`inbox.notifications: true` (default false); an SSE subscription activates its
+own session feed without enabling unused contexts.
+
+Subscribe registers before checkpointing, then sends an initial invalidation
+only after `ctx.sessions.flush(session)` returns true. Subsequent invalidations
+observe native `agent/inbox/spliced` events, including edits and consumption,
+coalesce changes per context, and checkpoint before publishing. A rejected or
+false checkpoint produces no success notification. Later changes or reconnects
+retry the current state; there is no durable outbox, replay or exactly-once
+delivery. A host can consume the same feed through `a2a/inbox-checkpointed`.
+Notification data contains no message bodies. Re-read `dsh/inbox/get` after an
+invalidation and on reconnect. Each context checkpoints independently; slow SSE
+clients disconnect instead of creating an unbounded notification backlog.
+Closing the plugin unregisters observers/subscriptions and suppresses late sends.
+
+### Existing admission metadata
+
+Standard SendMessage/SendStreamingMessage continues to accept
+`metadata[URI] = {target: 'next-turn' | 'next-step', wakeup: boolean}` on its
+Message, negotiated as before. Prefer those standard methods for new input.
+The operations above control already queued input; they do not add another
+queue, consumer, task-state machine or webhook configuration store.
+
 ## Configuration
 
 Disabled by default. Configure via the profile's `cordis.patch.yml`:
@@ -83,6 +196,9 @@ Disabled by default. Configure via the profile's `cordis.patch.yml`:
           intervalMs: 15000  # positive integer, at most 2147483647
         cwd: /srv/agent-workspaces
         uploadsDir: ''         # file-part upload root; empty = <OS temp>/dsh-a2a-uploads/<date>
+        urlDownloads:
+          allowPrivate: false  # true = allow all private/loopback hosts in a trusted intranet
+          allowedHosts: []     # or allow only these private/loopback hosts; public hosts need no entry
         subagentTools:
           enabled: false      # opt in to attributed local descendant tool calls/results
         agent:
@@ -109,6 +225,75 @@ Disabled by default. Configure via the profile's `cordis.patch.yml`:
 
 ## Endpoints
 
+All eleven A2A 1.0 operations use the official `@a2a-js/sdk` handlers. JSON-RPC
+is the default binding; HTTP+JSON/REST and gRPC are opt-in and share the same
+TaskStore, executor, subscriptions, and push configuration store.
+
+| Operation | JSON-RPC | HTTP+JSON/REST, relative to `<basePath>/rest` | gRPC |
+| --- | --- | --- | --- |
+| Send message | `SendMessage` | `POST /message:send` | `SendMessage` |
+| Stream message | `SendStreamingMessage` | `POST /message:stream` | `SendStreamingMessage` |
+| Get / list tasks | `GetTask`, `ListTasks` | `GET /tasks/{id}`, `GET /tasks` | `GetTask`, `ListTasks` |
+| Cancel task | `CancelTask` | `POST /tasks/{id}:cancel` | `CancelTask` |
+| Subscribe | `SubscribeToTask` | `GET` or `POST /tasks/{id}:subscribe` | `SubscribeToTask` |
+| Create / list push configs | `CreateTaskPushNotificationConfig`, `ListTaskPushNotificationConfigs` | `POST` / `GET /tasks/{id}/pushNotificationConfigs` | Same operation names |
+| Get / delete push config | `GetTaskPushNotificationConfig`, `DeleteTaskPushNotificationConfig` | `GET` / `DELETE /tasks/{id}/pushNotificationConfigs/{configId}` | Same operation names |
+| Extended card | `GetExtendedAgentCard` | `GET /extendedAgentCard` | `GetExtendedAgentCard` |
+
+Push operations require `pushNotifications: true`. The extended card operation
+requires a host provider; otherwise the SDK returns its standard unsupported
+error. Requests use `A2A-Version: 1.0` and JSON bodies accept
+`application/a2a+json` or `application/json`. REST SSE carries event objects
+directly, while JSON-RPC SSE carries JSON-RPC response envelopes. REST tenant
+routes prepend `/{tenant}`; gRPC requests carry the standard `tenant` field.
+
+```yaml
+rest: true                 # default: false; uses the HTTP listener
+grpc:
+  enabled: true            # default: false; separate plaintext HTTP/2 listener
+  port: 41242              # same bind host as HTTP, default 127.0.0.1
+  publicUrl: ''            # advertised gRPC host:port; empty uses bound address
+```
+
+Install `@grpc/grpc-js` and `@bufbuild/protobuf` in the host when enabling gRPC.
+They are optional peer dependencies and are loaded only when gRPC is enabled.
+Both gRPC versions use the SDK service descriptors and coexist on this listener;
+the Agent Card advertises only enabled bindings, including their v0.3 mirrors.
+REST v0.3 uses the SDK's `/v1/...` routes and protobuf JSON shapes (for example,
+`ROLE_USER`); it is distinct from v0.3 JSON-RPC `kind`-tagged messages. Use the
+matching SDK client rather than copying payloads between bindings.
+
+A small connection adapter releases an individual subscription's SDK queue when
+its client disconnects; it never cancels the task or other subscribers. Disconnected
+sends continue draining task events for persistence, independently of client read
+speed. After a stream writer first reports backpressure, it may queue at most
+1 MiB of additional HTTP output or 16 additional gRPC messages (plus the frame
+that crosses the limit). A writer that exceeds this allowance is disconnected;
+clients can retrieve the persisted task or resubscribe. A single large frame is
+allowed, and a `drain` resets the allowance. This bounds the plugin's Node output
+backlog, not individual frame size or the SDK's internal event/push queues.
+
+The host can register an SDK `ExtendedAgentCardProvider` with
+`ctx.provide('a2aExtendedCard', provider)` **before loading this plugin**. The
+type is also exported by this package. The provider receives the SDK
+`ServerCallContext` and must authenticate and authorize the caller before
+returning private card data. The SDK stores HTTP headers or gRPC metadata at
+`context.state.get(STATE_HEADERS_KEY)` (`STATE_HEADERS_KEY` is exported by
+`@a2a-js/sdk/server`); tenant and requested version are also available. A rejected
+provider call returns an error, and the public discovery card stays public.
+Enabling the provider advertises `capabilities.extendedAgentCard: true`.
+
+The plugin does not supply an identity provider or TLS certificates. Keep the
+loopback default or use a host gateway for authentication, authorization and TLS
+on **every enabled listener**. Application session listing, queue editing and
+optional card signing are separate from these eleven operations. This support
+matrix describes the wired SDK surface, not independent protocol certification.
+
+The secret-free `E2E (dsh-a2a protocol bindings)` job runs HTTP/gRPC contract tests
+and real DSH runtime turns with scripted model responses. It covers cross-binding
+task state, authenticated push callbacks, extended cards, reconnect cleanup and
+slow readers independently of the LLM/Langfuse integration gate.
+
 - `GET /.well-known/agent-card.json` — agent card: A2A 1.0 shape for `A2A-Version: 1.0` clients, the 0.3 shape for headerless clients (the legacy `/.well-known/agent.json` path is served as an alias)
 - `POST <basePath>/` — JSON-RPC. v1 methods: `SendMessage` (blocking by default, `configuration.returnImmediately: true` returns after the first event), `SendStreamingMessage` (SSE), `GetTask`, `ListTasks` (filter + cursor pagination), `CancelTask`, `SubscribeToTask` (the current task is the first event; the bus stays alive while the task is interrupted, so interrupted tasks can be re-followed live). v0.3 spellings (`message/send`, `message/stream`, `tasks/get`, `tasks/cancel`, `tasks/resubscribe`) keep working through the compat layer. Legacy SSE status updates that end an interaction carry `final: true`, including `input-required` after a completed turn or an approval wait; this ends the stream without making the task terminal. Resubscribe snapshots keep waiting for future events while a live task bus exists. Legacy `tasks/get` also accepts `contextId` without `id` on this path or root `/`, returning the latest stored task or `result: null` when absent.
 
@@ -119,13 +304,13 @@ Disabled by default. Configure via the profile's `cordis.patch.yml`:
 - **Host admission and settlement.** `ctx.on('a2a/before-followup', async (detail) => { ... })` runs before every user message enters the agent inbox. Its detail contains `agent`, `contextId`, `taskId`, the original `a2aMessage`, `dshMessageId`, `requestHeaders`, and an abort `signal`; rejection fails the A2A task without enqueueing the message. A host may inspect its own A2A message metadata here; the plugin does not interpret it. The existing `a2a/message-admitted` event remains an observational tap after insertion. A host can register `ctx.on('a2a/task-settlement', async ({ agent, contextId, taskId, reason, signal }, next) => { await hostWork; return next(); })`. The hook starts after the first completed turn and may wait for any number of autonomous follow-ups, including none. The plugin streams their events under the same task ID and publishes the latest turn's final status when the hook resolves. Cancel, clear, and disposal abort the signal and release the waiter. Without this hook, the first completed turn settles as before. The host must end its wait when its work is done; the plugin does not infer that from product metadata.
 - **Agents are full preset citizens.** Each task's agent is created with the deployment's default model selection (`agentDefaultModel`) and mounts its agent preset (the web profile keeps all tools inside presets — without one the agent would see an empty tool catalog). `agent.preset` pins a specific preset.
 - **Streaming aggregation.** Text deltas of a turn share one `messageId`, so clients accumulate them into a single message; reasoning deltas ride a separate `messageId` and are marked `metadata.dshAgent.kind: 'thought'`. The turn-final event's message carries the full assembled text, so blocking `SendMessage` clients read the answer from `result.task.status.message`. Tool calls/results are data parts marked `tool-call` / `tool-result`; token usage lands in `metadata.usage` of the final event. A2A 1.0 has no `final` flag — terminal and interrupted states close the stream.
-- **Message parts beyond text.** File parts can carry inline bytes or a `url`; the plugin downloads URLs over http/https, bounded to 64 MiB and 30 s. Supported images use the composed attachment store (`ctx.attachments`, e.g. `@deepseek-ai/dsh-attachment-local`) to reach vision-capable models. Non-image files use a configured materializer or persist under `uploadsDir` (default `<OS temp>/dsh-a2a-uploads/<date>/`, names sanitized cross-platform, collisions suffixed), even when an attachment store exists. The prompt references the resulting readable path inside a `<document>` tag. Ensure the local directory is readable by the agent's tools. `data` parts become `<data>` JSON text. A turn never fails because a part kind is unsupported.
+- **Message parts beyond text.** File parts can carry inline bytes or a `url`; the plugin downloads URLs over http/https, bounded to 64 MiB and 30 s. Downloads default to public IP addresses and revalidate every redirect. In a trusted intranet, set `urlDownloads.allowPrivate: true` to allow every private or loopback host without an allowlist; `urlDownloads.allowedHosts` remains available to allow only named hosts. Supported images use the composed attachment store (`ctx.attachments`, e.g. `@deepseek-ai/dsh-attachment-local`) to reach vision-capable models. Non-image files use a configured materializer or persist under `uploadsDir` (default `<OS temp>/dsh-a2a-uploads/<date>/`, names sanitized cross-platform, collisions suffixed), even when an attachment store exists. The prompt references the resulting readable path inside a `<document>` tag. Ensure the local directory is readable by the agent's tools. `data` parts become `<data>` JSON text. A turn never fails because a part kind is unsupported.
 - **Remote execution files.** A deployment can register `ctx.provide('a2aFileMaterializer', { materializeFile })`, using the exported `A2aFileMaterializer` type. The callback receives `{ contextId, bytes, filename, mediaType }` (with a sanitized basename) and returns `{ readablePath }`, a path readable by that context's file/shell tools. When configured, non-image FileParts use the materializer instead of `ctx.attachments.saveFile()`; the model receives the returned `<document path="...">`. Images keep the existing attachment handling. A failed callback yields a delivery note, never a host-path fallback. The deployment owns sandbox selection, upload, and lifetime; no E2B SDK is required by this plugin.
 - **Local execution files.** Without a remote materializer, inline and downloaded non-image FileParts persist under `uploadsDir`; the `<document>` envelope carries the path, source URL, media type, size, and original filename when sanitization or a collision changes it. Images still use native attachment handling.
 - **Tool approvals.** When the profile composes `@deepseek-ai/dsh-user-approval` with policy `ask`, A2A-owned agents answer `approval/request` by publishing `input-required` with a DataPart `{ requestId, toolName, reason?, callId? }`. Reply on the same `taskId`/`contextId` with one DataPart `{ requestId, callId?, outcome: "allowed-once" | "rejected" }`. The reply settles the waiting tool call inside the original dsh turn; it does not create another user message or billing turn. Invalid, duplicate, and withdrawn replies are rejected. `never` policy rejects inside dsh before the A2A answerer is called. The approval service is optional; without it, `ask` fails closed as usual.
 - **Custom approval payloads.** A deployment may register `ctx.provide('a2aApprovalCodec', codec)` before this plugin starts. The exported `A2aApprovalCodec` has `encode(request)` and `decode(message)` methods; `decode` returns `{ requestId?, callId?, outcome }` only for a supported one-shot decision. A unique `callId` can replace `requestId` for legacy clients. Reject unsupported outcomes in the decoder; never translate `proceed_always` into `allowed-once`. Other message types, including question, plan, and UI markup, remain outside this plugin.
 - **Requests for one task execute in order.** Autonomous turns covered by a settlement hook finish before the next user request starts. Approval confirmations settle a pending decision inside its current turn.
-- **Restart**: persisted task shells survive in Redis/GCS. With `sessionPersistence` composed, a `contextId` already present on disk resumes its dsh session after restart; a new id creates a new session.
+- **Restart and workers**: persisted task shells survive in Redis/GCS. With `sessionPersistence` composed, a `contextId` already present on disk resumes its dsh session after restart; a new id creates a new session. Shared stores do not provide multi-active execution: route a working task/context to its owning worker. A non-owner cancellation fails fast instead of reporting a cancel while the original agent continues.
 - **Clear**: the same-process gateway can call `ctx.get('a2aTasks').clearContext(contextId)` before reporting `messages/clear` success. It cancels and drains the live turn, removes the binding and every TaskStore shell for that context, and returns the removed task IDs. The gateway owns the separate session-surface replacement and client-visible history-ID update.
 
 ## SSE heartbeats
@@ -185,9 +370,95 @@ dsh ships **no authentication or authorization**. The server binds `127.0.0.1` b
 
 ## Compatibility
 
-Optional Goal integration requires `@deepseek-ai/dsh-goal >=0.2.0-rc.2 || >=0.2.1-alpha.1` and the official Goal round driver (both tested at `0.2.1-rc.4`).
+Optional Goal integration requires `@deepseek-ai/dsh-goal >=0.2.0-rc.2 || >=0.2.1-alpha.1` and the official Goal round driver (both tested at `0.2.1-rc.5`).
+
+Pinned dsh/cordis versions live in the [root compat matrix](../../README.md#compatibility). Event payloads ride pre-release dsh APIs (`@deepseek-ai/dsh-{agent,session,llm,attachment,tools}@0.2.1-rc.5` — the attachment store is an optional peer) — the session peer floor is `>=0.2.1-rc.5` for the owner-scoped `SessionStore.flush` checkpoint barrier; check the `TODO(verify)` markers in `src/` before upgrading dsh.
+
+## Standard A2A notifications
+
+Use `SendStreamingMessage` / `SubscribeToTask` for live task updates, `GetTask`
+for task snapshots/history, and `ListTasks` scoped by `contextId` for discovery.
+Multiple clients can subscribe independently. Use streaming for interactive UI;
+use official task Push Notifications for a receiver that cannot keep a stream open.
+See the [official streaming and push guide](https://a2a-protocol.org/v1.0.1/topics/streaming-and-async/).
+
+Enable the SDK's standard push capability explicitly (default: `false`):
+
+```yaml
+config:
+  enabled: true
+  pushNotifications: true
+```
+
+The Agent Card then advertises `capabilities.pushNotifications: true`. This plugin
+passes the official SDK's `InMemoryPushNotificationStore` and
+`createLegacyAwarePushNotificationSender` into its `DefaultRequestHandler`.
+Configuration CRUD, dispatch, authentication headers, serialization and timeouts
+are SDK behavior. Restored native task events use that same sender after their
+existing SDK ResultManager persistence drain; there is no separate notification protocol, sender adapter,
+queue-change channel, message correlation cache or plugin retry scheduler.
+
+A v1.0 client can register its webhook while sending a message:
+
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 1,
+  "method": "SendMessage",
+  "params": {
+    "message": {
+      "messageId": "fixture-message-1",
+      "role": "user",
+      "parts": [{ "text": "Run this task" }]
+    },
+    "configuration": {
+      "taskPushNotificationConfig": {
+        "url": "https://receiver.example.invalid/a2a-notifications",
+        "authentication": { "scheme": "Bearer", "credentials": "placeholder-token" }
+      }
+    }
+  }
+}
+```
 
-Pinned dsh/cordis versions live in the [root compat matrix](../../README.md#compatibility). Event payloads ride pre-release dsh APIs (`@deepseek-ai/dsh-{agent,session,llm,attachment,tools}@0.2.1-rc.4` — the attachment store is an optional peer) — the session peer floor is `>=0.2.0-rc.1` because child attribution uses `firstLifecycleSeq` to reject restored sessions; check the `TODO(verify)` markers in `src/` before upgrading dsh.
+Send `A2A-Version: 1.0`. For an existing task use
+`CreateTaskPushNotificationConfig` with `{ taskId, url, authentication }`.
+The SDK assigns the returned config ID. Manage it with
+`GetTaskPushNotificationConfig`, `ListTaskPushNotificationConfigs` and
+`DeleteTaskPushNotificationConfig` (Get and Delete use
+`{ taskId, id }`). Configuration access uses the SDK's tenant/owner scope.
+The existing legacy methods and `configuration.pushNotificationConfig` are
+handled by the SDK's v0.3 compatibility layer.
+
+The receiver gets HTTP POSTs with `Content-Type: application/a2a+json` and a
+standard `StreamResponse`: `{ task }`, `{ message }`, `{ statusUpdate }` or
+`{ artifactUpdate }`. The configured Bearer credentials become `Authorization`;
+incoming application identity headers are not automatically forwarded. A webhook
+registered over v0.3 receives the SDK's v0.3 task snapshots and `application/json`,
+even if a later triggering request uses a different wire version.
+
+The host verifies webhook authentication and resolves application/context
+ownership before bridging the update to its existing WebSocket/UI refresh
+logic. Product topics, permission rules, and snapshot selection stay in the
+host. Native queue editing/reordering still uses the existing inbox API and
+snapshots; this plugin does not manufacture new A2A task states for queue edits.
+A task update does not promise that a separate application database mirror has
+flushed. `GetTask` returns the authoritative A2A task snapshot instead.
+
+The official store is in memory. Configs and their credentials are lost on
+restart, independently of the chosen durable TaskStore backend; clients must
+register again. Delete configurations that are no longer needed. The SDK uses
+its default five-second webhook request timeout and logs delivery failures
+without failing task execution. No plugin-level retries, shutdown drain or
+persistent delivery guarantee are added. Read task snapshots on initial
+connection/reconnection and tolerate missing or duplicate notifications.
+
+Keep the loopback default. Push registration lets callers choose outbound
+webhook destinations; enable it only behind host authentication/authorization
+and an appropriate outbound-network policy. The SDK wiring does not add an
+application identity provider or a webhook URL allowlist. Use placeholder
+credentials and temporary session directories such as `/tmp/dsh-a2a-example`
+when testing locally.
 
 ## License
 

package/lib/admission.js

@@ -0,0 +1,25 @@
+/** Small keyed FIFO gate. Cleanup runs only when the releasing tail is still current. */
+export class AdmissionGate {
+    tails = new Map();
+    acquire(key) {
+        const previous = this.tails.get(key) ?? Promise.resolve();
+        let open;
+        const gate = new Promise((resolve) => (open = resolve));
+        const tail = previous.then(() => gate);
+        this.tails.set(key, tail);
+        let released = false;
+        return {
+            ready: previous,
+            release: (onCurrent) => {
+                if (released)
+                    return;
+                released = true;
+                open();
+                if (this.tails.get(key) !== tail)
+                    return;
+                this.tails.delete(key);
+                onCurrent?.();
+            },
+        };
+    }
+}

package/lib/bridge.js

@@ -25,6 +25,7 @@ import { installModelSelection } from '@deepseek-ai/dsh-agent';
 // modules import packages that are not on npm yet (dsh-timeout, dsh-scope).
 import { createUserMessage } from '@deepseek-ai/dsh-llm/message';
 import { SessionId } from '@deepseek-ai/dsh-session/types';
+import { AdmissionGate } from './admission.js';
 import { ApprovalReplyError, defaultApprovalCodec, } from './approval.js';
 import { buildMessageContent, uploadsDir } from './content.js';
 import { agentTextMessage, SessionTranslator, terminalStatusUpdate } from './translator.js';
@@ -36,6 +37,7 @@ export class A2aBridge {
     bySession = new Map(); // sessionId (== contextId) → entry
     clearing = new Set();
     creating = new Map();
+    admissions = new AdmissionGate();
     executing = new Map();
     asked = new Map();
     approvals = new Map();
@@ -103,7 +105,8 @@ export class A2aBridge {
      * a new task id for `message/send` calls that omit `taskId`.
      */
     async ensureTask(taskId, contextId) {
-        const creation = this.ensureTaskInner(taskId, contextId);
+        const admission = this.admissions.acquire(contextId);
+        const creation = admission.ready.then(() => this.ensureTaskInner(taskId, contextId));
         let pending = this.creating.get(contextId);
         if (!pending) {
             pending = new Set();
@@ -117,6 +120,7 @@ export class A2aBridge {
             pending.delete(creation);
             if (pending.size === 0)
                 this.creating.delete(contextId);
+            admission.release();
         }
     }
     async ensureTaskInner(taskId, contextId, clearing = false) {
@@ -149,6 +153,31 @@ export class A2aBridge {
             return { entry: forContext, freshTask: true };
         }
         const sessionId = SessionId(contextId);
+        const borrowed = this.inbox ? this.ctx.agents.get?.(sessionId) : undefined;
+        const handle = borrowed
+            ? { agent: borrowed, dispose: async () => { } }
+            : await this.createAgent(sessionId);
+        const entry = {
+            taskId,
+            sessionId,
+            handle,
+            borrowed: !!borrowed,
+            translator: new SessionTranslator(taskId, contextId, this.options.agentOptions?.model),
+            bus: null,
+            turnActive: false,
+            staleTurn: false,
+            settled: [],
+            running: new Set(),
+            pendingMessageAborts: new Set(),
+            settlementAbort: new AbortController(),
+            settling: false,
+            interrupted: false,
+        };
+        this.tasks.set(taskId, entry);
+        this.bySession.set(contextId, entry);
+        return { entry, freshTask: true };
+    }
+    async createAgent(sessionId) {
         const selection = this.resolveSelection();
         // The web profile disables the host-plane tool plugins — agents get tools
         // only through a mounted agent preset (dsh-host-apiproxy's composeAgent is
@@ -186,42 +215,29 @@ export class A2aBridge {
         // absence: let it fail instead of trying create() against an existing id.
         const persistence = this.ctx.get('sessionPersistence');
         const persisted = await persistence?.stat(sessionId);
-        const handle = persisted
+        return persisted
             ? await this.ctx.agents.resume({
                 resumeSessionId: sessionId,
                 agentOptions,
                 setup,
+                ...(this.inbox ? { keepInboxOnDispose: true } : {}),
             })
             : await this.ctx.agents.create({
                 sessionId,
                 meta: { cwd: this.options.cwd, ...(agentPreset ? { agentPreset } : {}) },
                 agentOptions,
                 setup,
+                ...(this.inbox ? { keepInboxOnDispose: true } : {}),
             });
-        const entry = {
-            taskId,
-            sessionId,
-            handle,
-            translator: new SessionTranslator(taskId, contextId, this.options.agentOptions?.model),
-            bus: null,
-            turnActive: false,
-            staleTurn: false,
-            settled: [],
-            running: new Set(),
-            pendingMessageAborts: new Set(),
-            settlementAbort: new AbortController(),
-            settling: false,
-            interrupted: false,
-        };
-        this.tasks.set(taskId, entry);
-        this.bySession.set(contextId, entry);
-        return { entry, freshTask: true };
     }
     /** A2A parts → dsh content blocks; throws only when no part is usable. */
     async buildContent(message, contextId) {
         const attachments = this.ctx.get('attachments');
         const materializer = this.ctx.get('a2aFileMaterializer');
-        return buildMessageContent(message.parts, attachments, uploadsDir(this.options.uploadsDir), materializer ? { contextId, materializer } : undefined);
+        return buildMessageContent(message.parts, attachments, uploadsDir(this.options.uploadsDir), materializer ? { contextId, materializer } : undefined, {
+            allowPrivate: this.options.downloadAllowPrivate,
+            allowedHosts: this.options.downloadAllowedHosts,
+        });
     }
     isClearing(contextId) {
         return this.clearing.has(contextId);
@@ -356,8 +372,12 @@ export class A2aBridge {
         }
         finally {
             pending.delete(execution);
-            if (pending.size === 0)
+            if (pending.size === 0) {
                 this.executing.delete(contextId);
+                const entry = this.bySession.get(contextId);
+                if (entry && entry.running.size === 0)
+                    entry.terminalState = undefined;
+            }
         }
     }
     /** Queue one user-message turn on the task's agent and await its `turn/end`. */
@@ -391,7 +411,9 @@ export class A2aBridge {
         }
         finally {
             entry.running.delete(running);
-            if (entry.running.size === 0)
+            // Keep a failure visible to messages already admitted into this execution
+            // batch; trackExecution clears it once a genuinely new batch can arrive.
+            if (entry.running.size === 0 && !this.executing.get(entry.sessionId)?.size)
                 entry.terminalState = undefined;
         }
     }