ur-agent 1.45.6 → 1.47.0

package/docs/A2A.md

@@ -0,0 +1,180 @@
+# Agent2Agent (A2A)
+
+UR exposes an opt-in agent-to-agent server with two deliberately distinct API
+surfaces:
+
+| Surface | Path | Contract |
+| --- | --- | --- |
+| Agent Card | `/.well-known/agent-card.json` | Strict v1 card by default; send `A2A-Version: 0.3` for the separate v0.3 card |
+| A2A v1 JSON-RPC | `/` or `/a2a/v1/jsonrpc` | ProtoJSON, PascalCase lifecycle methods, `A2A-Version: 1.0` |
+| A2A v1 HTTP+JSON | `/message:send`, `/tasks`, or `/a2a/v1/...` | Versioned REST lifecycle with pagination, artifacts, references, and cancellation |
+| A2A v0.3 JSON-RPC | `/a2a/jsonrpc` | Stable v0.3 binding implemented with the official JavaScript SDK |
+| UR compatibility API | `/a2a/tasks` and `/a2a/tasks/:id` | UR-specific REST-style background-task controls; not an A2A REST binding |
+
+The two protocol versions deliberately use separate schemas and handlers. The
+stable SDK remains pinned for v0.3; UR's dependency-free v1 compatibility layer
+translates strict v1 messages and tasks onto the same bounded durable execution
+engine. It is covered by UR tests and the official A2A TCK, but does not claim
+certification by the prerelease JavaScript SDK.
+
+## Start the server
+
+Loopback without authentication is allowed for local development:
+
+```sh
+ur a2a serve --port 8765
+```
+
+For authenticated use, keep secrets out of process arguments:
+
+```sh
+UR_A2A_TOKEN='<random-secret>' ur a2a serve --port 8765
+```
+
+An off-loopback bind requires either `UR_A2A_TOKEN` or
+`UR_A2A_DELEGATION_SECRET`. A wildcard bind also requires a reachable external
+base URL so the Agent Card never advertises `0.0.0.0`:
+
+```sh
+UR_A2A_TOKEN='<random-secret>' \
+  ur a2a serve --host 0.0.0.0 --port 8765 \
+  --public-base-url https://agent.example.com
+```
+
+Terminate TLS at a trusted reverse proxy for non-loopback deployments; bearer
+tokens must not travel over plaintext networks.
+
+## Agent Card and protocol calls
+
+Inspect the live card:
+
+```sh
+curl -s http://127.0.0.1:8765/.well-known/agent-card.json
+```
+
+Without a version header, discovery returns the v1 ProtoJSON card with
+`supportedInterfaces` for JSON-RPC, HTTP+JSON, and the legacy v0.3 binding. Use
+`A2A-Version: 0.3` to retrieve the standalone v0.3 SDK card. Both cards report
+the installed UR version, skills, implemented capabilities, and only the
+authentication schemes configured for that server; responses include
+`Vary: A2A-Version`.
+
+Send a blocking v1 message over JSON-RPC:
+
+```sh
+curl -s http://127.0.0.1:8765/a2a/v1/jsonrpc \
+  -H 'content-type: application/json' \
+  -H 'A2A-Version: 1.0' \
+  -H "authorization: Bearer $UR_A2A_TOKEN" \
+  -d '{
+    "jsonrpc":"2.0",
+    "id":"request-v1",
+    "method":"SendMessage",
+    "params":{
+      "configuration":{"blocking":true},
+      "message":{
+        "messageId":"message-v1",
+        "role":"ROLE_USER",
+        "parts":[{"text":"Review the current diff."}]
+      }
+    }
+  }'
+```
+
+The v1 HTTP+JSON binding accepts `application/a2a+json` and exposes
+`message:send`, task list/get/cancel, continuation, and artifact/reference
+operations at the advertised transport root or under `/a2a/v1`. List cursors
+are opaque and filter-bound. An optional tenant segment, for example
+`/a2a/v1/acme/tasks`, requires a matching `tenant:acme` delegation scope.
+
+Send a blocking v0.3 message:
+
+```sh
+curl -s http://127.0.0.1:8765/a2a/jsonrpc \
+  -H 'content-type: application/json' \
+  -H 'A2A-Version: 0.3' \
+  -H "authorization: Bearer $UR_A2A_TOKEN" \
+  -d '{
+    "jsonrpc":"2.0",
+    "id":"request-1",
+    "method":"message/send",
+    "params":{
+      "configuration":{"blocking":true},
+      "metadata":{"skill":"coding-agent"},
+      "message":{
+        "kind":"message",
+        "messageId":"message-1",
+        "role":"user",
+        "parts":[{"kind":"text","text":"Review the current diff."}]
+      }
+    }
+  }'
+```
+
+Set `configuration.blocking` to `false` to receive a working task promptly,
+then call `tasks/get`; use `tasks/cancel` for a nonterminal task. The v0.3
+binding supports `message/send`, `tasks/get`, and `tasks/cancel`. Streaming,
+resubscription, push notifications, and authenticated extended cards are not
+advertised by either card and return protocol errors if requested.
+
+`params.metadata.skill` selects an advertised skill; the default is
+`coding-agent`. Requests with an unknown skill are rejected before execution.
+Prompts enter the child process through stdin, and the child uses fail-closed
+`dontAsk` permissions because this network binding has no interactive approval
+bridge.
+
+## Delegation tokens
+
+UR delegation tokens are short-lived HMAC-signed capabilities bound to a
+subject, one audience, an expiry, and explicit skill scopes:
+
+```sh
+export UR_A2A_DELEGATION_SECRET='<issuer-secret>'
+TOKEN=$(ur a2a token mint --sub peer-a --aud ur-nexus \
+  --scope coding-agent --ttl 900)
+printf '%s\n' "$TOKEN" | ur a2a token verify --token-stdin \
+  --aud ur-nexus --scope coding-agent
+```
+
+The HMAC secret belongs only to the trusted issuer. A narrower child token can
+be minted by that issuer, but an untrusted holder cannot attenuate the token
+without the root signing secret. Protocol and compatibility tasks are isolated
+by both delegation subject and skill, including get, continue, reference, and
+cancel operations.
+
+## UR compatibility task API
+
+The compatibility API preserves older UR-specific background options:
+
+- `POST /a2a/tasks` — submit `{ prompt, skill, mode, worktree, model, maxTurns }`
+- `GET /a2a/tasks` — list tasks visible to the caller
+- `GET /a2a/tasks/:id` — status
+- `GET /a2a/tasks/:id/output` — bounded output metadata and logs
+- `POST /a2a/tasks/:id/cancel` or `DELETE /a2a/tasks/:id` — cancel
+
+These routes do not use the A2A wire schema and must not be presented to A2A
+clients as an A2A REST endpoint. `skipPermissions` additionally requires the
+static operator token or a delegation scope of `permissions:bypass`.
+
+## Operational limits
+
+The server bounds work with these environment variables:
+
+- `UR_A2A_MAX_REQUEST_BYTES` and `UR_A2A_MAX_PROMPT_CHARS`
+- `UR_A2A_MAX_OUTPUT_BYTES`
+- `UR_A2A_MAX_SUBMISSIONS_PER_MINUTE`
+- `UR_A2A_MAX_CONCURRENT_SUBMISSIONS`
+- `UR_A2A_MAX_ACTIVE_TASKS`
+- `UR_A2A_MAX_ACTIVE_TASKS_PER_OWNER`
+- `UR_A2A_TASK_TIMEOUT_MS`
+
+Protocol task state and v1 artifacts are persisted with owner, tenant, skill,
+and version metadata under `.ur/a2a/` using owner-only permissions and atomic
+writes. Retrieval, continuation, reference lookup, listing, and cancellation
+all re-check the caller boundary. UR compatibility task state remains under the
+same directory and links to `.ur/background/` output files.
+
+References: [A2A v1 specification](https://a2a-protocol.org/latest/specification/),
+[A2A v1 announcement](https://a2a-protocol.org/latest/announcing-1.0/),
+[official JavaScript SDK](https://github.com/a2aproject/a2a-js), and
+[official TCK](https://github.com/a2aproject/a2a-tck).

package/docs/ACP.md

@@ -1,13 +1,14 @@
-# Agent Communication / Client Protocol (ACP)
+# Agent Client Protocol (ACP)
 
-UR exposes two ACP surfaces:
+UR exposes one native ACP transport and one separate HTTP integration surface:
 
-1. **Stdio ACP agent** (`ur acp stdio`) — newline-delimited JSON-RPC over stdio,
-   the protocol Zed and ACP-capable editors speak. Use this for native editor
-   integration.
-2. **HTTP JSON-RPC server** (`ur acp serve`) — a loopback HTTP endpoint for
-   scripting, task delegation, and custom clients. This is **not** Zed-style
-   stdio ACP; use the stdio agent for native ACP editors.
+1. **Stdio ACP agent** (`ur acp stdio`) — the stable ACP v1 wire protocol over
+   newline-delimited JSON-RPC, implemented with the official TypeScript SDK.
+   Use this for Zed and other native ACP clients.
+2. **UR HTTP JSON-RPC compatibility server** (`ur acp serve`) — a separate
+   loopback endpoint for scripting, the experimental JetBrains plugin, tool
+   calls, and background tasks. It is not an ACP transport binding and is not
+   advertised as one.
 
 ## Stdio ACP agent
 
@@ -16,6 +17,8 @@ ur acp stdio
 ```
 
 The editor launches this process and exchanges one JSON-RPC object per line.
+The official SDK owns wire parsing, request concurrency, notification
+semantics, and error envelopes.
 
 Methods:
 
@@ -24,9 +27,16 @@ Methods:
 | `initialize` | client → agent | `{ protocolVersion, agentCapabilities, authMethods }` |
 | `authenticate` | client → agent | `{}` (no auth required for local stdio) |
 | `session/new` | client → agent | `{ sessionId }` |
+| `session/list` | client → agent | returns a 50-item page and opaque, filter-bound cursor |
+| `session/load` | client → agent | restores a session and replays its exact ordered updates |
+| `session/delete` | client → agent | deletes private metadata and history after stopping active work |
+| `session/resume` | client → agent | restores identity without replaying history |
+| `session/close` | client → agent | cancels active work and releases the in-process session |
+| `session/set_mode` | client → agent | selects `default`, `acceptEdits`, or `plan` |
+| `session/set_config_option` | client → agent | selects full tool updates or permission-only updates |
 | `session/prompt` | client → agent | `{ stopReason }`, with streaming `session/update` notifications |
 | `session/cancel` | client → agent (notification) | aborts the in-flight prompt |
-| `shutdown` | client → agent | `null` |
+| `session/request_permission` | agent → client | asks the user to allow or reject a tool call |
 
 During `session/prompt` the agent emits `session/update` notifications:
 
@@ -38,22 +48,64 @@ During `session/prompt` the agent emits `session/update` notifications:
 ```
 
 `session/prompt` resolves with `{ "stopReason": "end_turn" }` (or `"cancelled"`
-if a `session/cancel` arrived). Configure it with `ur ide config zed`.
+if a `session/cancel` arrived). Repeated prompts resume the underlying UR CLI
+conversation for that ACP session. `session/resume` reconnects after an agent
+restart without replay; `session/load` emits the bounded, exact stored update
+sequence before current session information and available commands. UR stores
+the ACP-to-CLI identity, working directory, modes/options, and append-only
+history in private metadata under `~/.ur/acp/sessions/`. Writes are locked,
+atomic, bounded, migration-aware, and fail closed on malformed state. MCP
+credentials are never persisted there. Configure the agent with
+`ur ide config zed`.
+
+The stdio surface advertises text and resource-link prompt support, additional
+workspace directories, MCP stdio/HTTP/SSE transports, load/list/delete,
+resume/close, modes, configuration options, and available commands.
+Client-provided MCP configuration is validated, written to a mode-`0600`
+temporary file instead of argv, and removed after each turn. Image, audio, and
+embedded-context capabilities are not advertised.
+
+Tool calls that require approval are bridged to the client's native ACP
+permission UI with allow-once, reject, and (when UR supplies a durable rule)
+always-allow choices. Cancellation and client errors fail closed. The prompt is
+sent over stdin rather than argv. Session count, prompt size, output size, and
+runtime are bounded by `UR_ACP_STDIO_MAX_SESSIONS`,
+`UR_ACP_STDIO_MAX_PROMPT_CHARS`, `UR_ACP_STDIO_MAX_OUTPUT_CHARS`, and
+`UR_ACP_STDIO_PROMPT_TIMEOUT_MS`. History additionally enforces per-event,
+event-count, total-byte, and discovery-scan limits.
 
 ## HTTP JSON-RPC server
 
 ```sh
-ur acp serve --host 127.0.0.1 --port 8123 [--token <secret>] [--debug]
+UR_ACP_TOKEN='<secret>' ur acp serve --host 127.0.0.1 --port 8123 [--debug]
 ur acp status [--json]
 ur acp stop
 ```
 
-Binds to loopback only; binding off-loopback requires `--token`. `--debug` logs
-each method and outcome to stderr. POST JSON-RPC to `/acp`; `GET /healthz`
-returns `{ ok: true }`.
+Binds to loopback by default; binding off-loopback requires a bearer token.
+Prefer `UR_ACP_TOKEN` because command-line secrets may be visible to other
+local processes. `--debug` logs method names and outcomes—not request params or
+secrets—to stderr. POST JSON-RPC to `/acp`; `GET /healthz` returns `{ ok: true }`.
+
+Tool calls are schema-validated and pass through the normal permission engine.
+Because the HTTP API has no interactive approval channel, requests that need an
+approval fail closed. Requests, prompts, tool I/O, task submission rate, tool
+call rate, concurrency, retained sessions/tasks, response size, and runtime are
+bounded. A session may select an existing subdirectory of the configured server
+workspace, but cannot escape that root (including through symlinks). Deployments
+can tune these defaults with `UR_ACP_MAX_REQUESTS_PER_MINUTE`,
+`UR_ACP_MAX_CONCURRENT_REQUESTS`, `UR_ACP_MAX_REQUEST_BYTES`,
+`UR_ACP_MAX_RESPONSE_BYTES`, `UR_ACP_MAX_ERROR_CHARS`,
+`UR_ACP_MAX_PROMPT_CHARS`, `UR_ACP_MAX_SESSIONS`,
+`UR_ACP_MAX_ACTIVE_TASKS`, `UR_ACP_MAX_RETAINED_TASKS`,
+`UR_ACP_MAX_TASKS_PER_MINUTE`, `UR_ACP_MAX_CONCURRENT_TASKS`,
+`UR_ACP_MAX_TASK_OUTPUT_BYTES`, `UR_ACP_TASK_TIMEOUT_MS`,
+`UR_ACP_MAX_TOOL_CALLS_PER_MINUTE`, `UR_ACP_MAX_CONCURRENT_TOOL_CALLS`,
+`UR_ACP_TOOL_TIMEOUT_MS`, `UR_ACP_MAX_TOOL_INPUT_CHARS`, and
+`UR_ACP_MAX_TOOL_OUTPUT_CHARS` environment variables.
 
 Methods: `initialize` (returns `capabilities` and `workspaceRoot`),
-`session/new`, `session/prompt`, `session/cancel`, `tools/list`, `tools/call`,
+`session/new`, `session/prompt`, `session/cancel`, `session/close`, `tools/list`, `tools/call`,
 `tasks/send` / `tasks/get` / `tasks/cancel`, `ide/diffCapture`, `ide/select`,
 and `shutdown` (acknowledges, then stops the server).
 
@@ -75,8 +127,8 @@ curl -s http://127.0.0.1:8123/acp \
 
 ## Capabilities and limitations
 
-- The stdio agent streams via `session/update`; token-level granularity depends
-  on the active provider.
+- The stdio agent streams text deltas via `session/update`; chunk granularity
+  depends on the active provider's stream.
 - The HTTP server returns unary responses (`streaming: false`); use the stdio
   agent for incremental updates.
 - Neither surface silently falls back to another provider; dispatch failures are

package/docs/AGENT_FEATURES.md

@@ -9,6 +9,62 @@ reproducible autonomous software engineering agent: every substantial task can
 be driven as `spec -> plan -> patch -> test -> report -> rollback`, with the
 spec as the durable source of truth and command evidence as the success gate.
 
+## v1.47.0 Additions
+
+- `ur ag-ui serve` adds a secure AG-UI HTTP/SSE boundary for user-facing
+  applications. Official schemas and encoding, truthful capability discovery,
+  full text/tool/state lifecycle events, cancellation, exact CORS, bearer
+  protection, redacted errors, and independent resource bounds are covered by
+  provider-free regression tests.
+- A2A now runs v0.3 and v1 side by side. Strict v1 JSON-RPC and HTTP+JSON
+  bindings add version negotiation, tenant isolation, durable tasks and
+  artifacts, pagination, continuation, references, and cancellation without
+  removing the stable v0.3 SDK path.
+- ACP stdio now implements durable list/load/delete/resume/close, bounded exact
+  history replay, modes, configuration options, and available commands in
+  addition to streaming prompts, permission requests, MCP servers, and roots.
+- `ur mcp serve-http` exposes the opt-in stateless MCP 2026 compatibility
+  surface with Tasks and a self-contained Apps resource. It is loopback-only
+  without authentication and enforces request metadata, capability negotiation,
+  owner isolation, limits, private persistence, and corrupt-state quarantine.
+- OpenAI users can opt into the Responses transport with
+  `ur config set openai_transport responses`. Chat Completions remains the
+  default; Responses defaults to `store=false` and supports streaming,
+  background polling/cancellation, WebSocket continuation, compaction, and
+  deferred tool search through tested provider adapters.
+- OpenTelemetry export is explicit per signal. GenAI inference, agent,
+  workflow, tool, memory, duration, token, cache, response,
+  time-to-first-chunk, inter-output-chunk latency, and error fields follow
+  current semantic conventions, while prompts and tool/memory content stay
+  redacted unless the operator
+  separately opts in.
+- Agent Skills receive strict open-spec validation and deterministic provenance.
+  `ur skill verify|sign|keygen` supports Ed25519 integrity manifests and trusted
+  keys; loaded skills are re-hashed immediately before execution. Native
+  `.ur/skills/` and standard cross-client `.agents/skills/` project/user roots
+  use explicit, deterministic precedence.
+- Project task memory now has per-entry provenance, UUIDs, SHA-256 content
+  digests, an append-only hash chain, cross-process locks, private atomic writes,
+  and `ur context-pack memory verify|quarantine|rollback` recovery commands.
+
+## v1.46.0 Additions
+
+- Native ACP v1 stdio support now uses the official SDK and includes durable
+  sessions, resume/close, MCP server configuration, additional roots,
+  permission requests, cancellation, and streaming updates. The separate HTTP
+  automation API is documented as UR JSON-RPC rather than mislabelled ACP.
+- A2A interoperability now uses the official stable JavaScript SDK for the
+  advertised v0.3 JSON-RPC binding, with authenticated discovery, scoped
+  delegation, durable tasks, cancellation, and bounded request execution.
+- The VS Code Actions view can safely start, inspect, and cancel background
+  tasks, including isolated worktree execution. The JetBrains client now
+  propagates cancellation, rejects overlapping prompts, and closes sessions.
+- Background-task state uses locked, atomic, private manifest writes with
+  corruption detection, structural limits, and symlink-safe artifact paths.
+- Provider protocol handling, MCP validation, CI supply-chain controls, release
+  version checks, and secret-input paths received additional compatibility and
+  security coverage.
+
 ## v1.45.6 Additions
 
 - Project verification approval is deduplicated per user turn. The agent asks
@@ -41,6 +97,7 @@ ur automation run nightly --dry-run
 ur automation run-due
 ur model-doctor
 ur a2a serve --dry-run
+ur ag-ui serve --help
 ur bg run "fix the flaky parser test" --worktree --dry-run
 ur test-first detect
 ur test-first --dry-run
@@ -181,7 +238,7 @@ components instead of one giant prompt.
 
 | Addition | Surface | What it adds |
 | --- | --- | --- |
-| ACP server for IDE extensions | `ur acp serve\|stop\|status` | HTTP+JSON-RPC Agent Communication Protocol server that exposes tool listing, tool calls, task submission, and status for VS Code/Cursor/Zed-like editors. |
+| ACP and IDE transports | `ur acp stdio`; `ur acp serve\|stop\|status` | Official-SDK ACP v1 stdio agent for native ACP editors, plus a distinct UR HTTP JSON-RPC API for tools, tasks, scripts, and the experimental JetBrains plugin. |
 | Non-interactive pool execution | `ur exec [prompts...]` | Run one or more prompts headlessly with optional concurrency, worktrees, output capture, and dry-run. |
 | GitHub tool | `GitHub` | PR/issue/repo operations via the `gh` CLI. |
 | API tool | `Api` | REST HTTP calls with JSON/text output. |
@@ -199,8 +256,8 @@ while keeping them project-local and manifest-backed:
 | --- | --- | --- |
 | Agent | `ur`, `ur agents`, `ur crew`, `ur bg`, `ur agent-templates` | `.ur/agents/`, `AGENTS.md`, `UR.md` |
 | Rules | `ur context-pack scan`, `ur safety`, `/guardrails`, `/hooks` | `AGENTS.md`, `UR.md`, `.cursor/rules/*.mdc`, `.cursorrules`, `.ur/safety-policy.json`, `.ur/guardrails.json`, `.ur/hooks.json` |
-| MCP | `ur mcp`, built-in MCP server mode, MCP tools/resources | `.mcp.json`, `.ur/mcp/`, plugin manifests |
-| Skills | `/skills`, `/create-skill`, bundled skills, plugin skills | `.ur/skills/`, user skills, plugin skill folders |
+| MCP | `ur mcp`, stdio mode, opt-in MCP 2026 HTTP Tasks/Apps, tools/resources | `.mcp.json`, `.ur/mcp/`, plugin manifests |
+| Skills | `/skills`, `/create-skill`, `ur skill verify\|sign\|keygen`, bundled/plugin skills | `.ur/skills/`, `.agents/skills/`, user skills, plugin skill folders, trusted key store |
 | CLI | `ur --help`, `ur -p`, `ur exec`, `ur acp`, workflow subcommands | `package.json` scripts, `.ur/project-manifest.json`, `.ur/verify.json` |
 | Models | `/model`, `ur model-doctor`, model router, Ollama discovery | Ollama endpoint, settings, `OLLAMA_MODEL`, model metadata cache |
 
@@ -240,7 +297,7 @@ and route model work through the local Ollama-backed UR runtime.
 | Auto compaction and memory retention | `compaction.autoThreshold`, `ur memory retention` | Configurable context compaction threshold plus TTL/max/decay pruning for `.ur/memory/*.jsonl` |
 | Code-index auto-reindex | `codeIndex.autoReindex`, `ur code-index watch` | File watcher that rebuilds the local semantic code index after source changes |
 | Live artifact steering | `ur artifacts comment <id> --feedback ... --task <bg_id>` | Artifact feedback is queued into the linked background task inbox and injected into active stream-json background agents as `priority: "now"` turns |
-| Full opt-in A2A task server | `ur a2a serve`, `/a2a/tasks` lifecycle routes | Token/delegation-protected task submission, status, output, and cancel routes backed by local background tasks |
+| Opt-in A2A + compatibility server | `ur a2a serve`, `/a2a/jsonrpc`, `/a2a/v1/*`, `/a2a/tasks` | Negotiated v1 JSON-RPC/HTTP+JSON and stable-SDK v0.3, plus clearly separate protected UR background-task compatibility routes |
 | IDE inline diff bundles | `ur ide diff capture|list|show|comment|schema`, `extensions/vscode-ur-inline-diffs/` | Editor-readable `.ur/ide/diffs/` manifest, metadata, patch files, comments, plus a native VS Code tree/webview review extension |
 | Benchmark adapters | `ur eval bench swe-bench|terminal-bench|aider-polyglot` | Imports local benchmark JSON/JSONL exports into UR eval suites without external downloads |
 
@@ -253,12 +310,12 @@ and route model work through the local Ollama-backed UR runtime.
 | Model capability report | `ur model-doctor` | Local Ollama model inventory with context length, advertised capabilities, and likely vision/code readiness |
 | Reusable agent templates | `ur agent-templates install` | Project agents for review, tests, browser QA, docs research, security, release notes, PR fixes, and memory curation |
 | GitHub agent runner | `.github/workflows/ur.yml` scaffold | Opt-in CI entry point for manual prompts or `/ur` issue comments |
-| A2A adapter handoff | `ur a2a serve` | Loopback Agent Card and token-gated task execution endpoint |
+| A2A interoperability | `ur a2a serve` | Version-negotiated strict v1 JSON-RPC/HTTP+JSON plus stable-SDK v0.3, durable tenant-isolated protocol state, and a separate UR compatibility API |
 | Semantic memory index | `ur semantic-memory build|search` | Local memory index over durable memory, docs, README, and UR instructions |
 | Claim provenance ledger | `ur claim-ledger add|list|validate` | Maps generated claims to web, file, MCP, tool, or user sources |
 | Browser replay evals | `ur browser-qa list|validate|run` | Validates replay fixtures and performs lightweight target smoke checks |
 | Permission and safety policy | `ur safety status|init|check` | Project-aware shell safety checks for destructive operations, sandbox recommendations, permission classes, and secret exfiltration denial |
-| Project context pack | `ur context-pack scan|remember|compress` | Architecture manifest, durable task memory, and compressed context summaries based on manifests and instructions |
+| Project context pack | `ur context-pack scan|remember|memory|compress` | Architecture manifest, provenance/hash-chained task memory with verify/quarantine/rollback, and compressed context summaries |
 
 ## Design Notes
 
@@ -268,7 +325,7 @@ tasks, custom agents, memory files, browser workflows, evidence commands, A2A
 Agent Card export, and local Ollama routing; these surfaces make those
 capabilities easier to discover and reuse.
 
-Network-facing behavior, such as a full A2A task server or a GitHub bot that can
+Network-facing behavior, such as the opt-in A2A server or a GitHub bot that can
 push code, should remain explicitly opt-in because it changes the trust and
 permission boundary.
 

package/docs/AGENT_TRENDS.md

@@ -1,7 +1,10 @@
 # Agent Trend Coverage
 
-UR is a local-first terminal coding agent. This page tracks how UR maps to the
-current agent platform trends and where future work should go next.
+UR is a provider-flexible, local-first terminal coding agent. This page tracks
+how UR maps to current agent-platform trends and where future work should go
+next. The factual comparison below is a **2026-07-15 research snapshot**; run
+`ur agent-trends` for the versioned machine-readable report and re-check the
+linked primary sources before acting on prerelease standards.
 
 ## Quick Commands
 
@@ -10,6 +13,7 @@ ur agent-trends
 ur agent-trends --json
 ur a2a card
 ur a2a card --base-url https://example.com
+ur ag-ui serve --help
 ur agent-features
 ur agent-features init
 ur agent-templates install
@@ -66,12 +70,15 @@ Inside an interactive session:
 
 | Trend | UR status | Current coverage | Professional next step |
 | --- | --- | --- | --- |
-| Local-first model runtime | Covered | local Ollama app endpoint, local and Ollama Cloud-backed models exposed through that app, model auto-routing | Add model capability reporting for tools, vision, context length, and multimodal readiness |
-| MCP tool ecosystem | Covered | `ur mcp`, MCP OAuth/XAA helpers, elicitation, permission checks, shared tool registry | Keep MCP registry/security guidance current as the spec evolves |
-| A2A / Agent Card interoperability | Covered | `ur a2a card`, `/a2a-card`, and opt-in `ur a2a serve` with task lifecycle routes and bearer/delegation auth | Track A2A spec changes and keep the server disabled unless explicitly started |
+| Provider-flexible, local-first runtime | Covered | Local Ollama; direct OpenAI, Anthropic, Gemini, OpenRouter, and OpenAI-compatible APIs; authenticated subscription-CLI adapters; explicit provider selection | Normalize capability discovery across providers and make automatic per-step routing opt-in |
+| MCP tool ecosystem | Covered | `ur mcp`, MCP OAuth/XAA/elicitation, fail-closed bounded stdio tools, and the opt-in stateless MCP 2026 HTTP adapter | Track the final 2026 spec/SDK and add independent-client fixtures before promoting the adapter |
+| MCP Tasks and MCP Apps | Covered | Negotiated Tasks lifecycle, owner-isolated durable state, and a self-contained Apps resource through `ur mcp serve-http` | Reconcile final extension schemas and broaden client interoperability tests |
+| A2A / Agent Card interoperability | Covered | Stable-SDK v0.3 plus strict v1 ProtoJSON JSON-RPC/HTTP+JSON, negotiated cards, tenant isolation, durable artifacts, and TCK coverage | Adopt the stable v1 SDK when released; add signed-card verification and streaming only with truthful end-to-end tests |
+| AG-UI agent-to-frontend interoperability | Covered | Official-schema HTTP/SSE adapter, truthful capabilities, ordered state/text/tool events, cancellation, exact CORS, bounded requests/output, and loopback-or-bearer security | Add independent frontend fixtures before advertising optional interrupts, binary/WebSocket transport, or client tools |
 | Durable workflows and checkpoints | Covered | resume, rewind, `ur bg` background runs, optional worktrees/PRs, cron/workflow internals, file restore | Publish a checkpointed workflow format for repeated automations |
 | Multi-agent orchestration | Covered | built-in planning, exploration, verification, and general-purpose agents; custom agents | Document reusable team patterns and role selection |
-| Long-term memory | Covered | `/remember`, `/forget`, `.ur/memory`, semantic memory, research notes, team memory, consolidation, `ur memory retention` | Tune retention defaults from real long-run telemetry |
+| Long-term memory | Partial | Existing memory/retrieval plus a provenance-rich SHA-256 project task-memory chain with private atomic writes, verification, quarantine, and rollback | Extend the same deletion and integrity guarantees to team, semantic, embedding, and legacy stores |
+| Portable Agent Skills | Covered | Native and `.agents/skills/` project/user discovery, strict validation, deterministic tree/permission digests, Ed25519 signing, trusted keys, and invocation-time integrity checks | Require registry attestations and dependency review before community one-command installation |
 | Semantic codebase retrieval | Covered | local embedding-based code index (`ur code-index`), opt-in `CodeSearch` tool, incremental re-index, auto-reindex watcher, Ollama embeddings | Add richer symbol-aware ranking |
 | Reliable repo editing | Covered | `ur repo-edit` builds a file/symbol index, performs AST-aware JS/TS identifier rename planning, previews patches before writing, and applies multi-file edits transactionally with rollback on syntax or check failure | Extend AST edits beyond identifier rename into import moves and signature-aware refactors |
 | Permission and safety policy | Covered | `ur safety`, `.ur/safety-policy.json`, pre-Bash safety evaluation, read/write/execute/network command classes, destructive-command approval, sandbox recommendations, and secret exfiltration denial | Record sandbox attestation in every risky command's evidence trail |
@@ -79,18 +86,20 @@ Inside an interactive session:
 | AGENTS.md interoperability | Covered | `AGENTS.md` loaded as runtime project context (before `UR.md`), plus imported by the `/init` command | Keep aligned as the AGENTS.md spec evolves |
 | Browser and computer-use workflows | Covered | `/browser`, `/chrome`, Playwright-aware tasks, WebSearch, WebFetch, risky-action approval | Add more release fixtures with screenshots and replay assertions |
 | Provenance and citations | Partial | WebFetch source URLs, `/cite`, `/graph`, `/trace`, evidence ledgers | Add claim-to-source mapping for web/MCP answers |
-| Evals and observability | Covered | verifier gates, `.ur/verify.json`, `/verify`, `/trace`, OpenTelemetry hooks, release checks, eval dashboard, benchmark adapters | Publish benchmark numbers from local reproducible suites |
+| Evals and observability | Partial | verifier gates, `.ur/verify.json`, `/verify`, `/trace`, OpenTelemetry hooks, replayable evals, dashboard, benchmark adapters | Grade complete trajectories in CI and publish versioned pass rates by category |
+| Standard GenAI telemetry | Covered | Explicit OTLP/console exporters; GenAI inference, agent/workflow, tool, memory, token, cache, response, latency, streaming time-to-first-chunk/inter-output-chunk, and error semantics; content off by default | Add trajectory policy graders and cross-provider dashboards without increasing content capture/cardinality |
 | Test-first execution | Covered | `ur test-first` detects compile/test/lint commands, stores failure traces, retries through a fix agent, and installs detected commands into `.ur/verify.json` for edit-time gates | Add per-package command plans for large monorepos |
-| Security and prompt-injection resistance | Covered | allow/ask/deny permissions, shell safety analysis, secret scan, untrusted web-content guidance, OS-level execution sandbox (macOS Seatbelt, Linux bubblewrap) | Continuously test web/MCP injection cases |
-| Agent identity and delegated authorization | Covered | MCP OAuth/XAA helpers, A2A bearer/delegation tokens, local trust boundaries, permission rules | Keep delegated scopes narrow and auditable |
+| Security and prompt-injection resistance | Covered | allow/ask/deny permissions, shell safety analysis, secret scan, untrusted web-content guidance, OS-level execution sandbox (macOS Seatbelt, Linux bubblewrap) | Continuously test web/MCP/repository/skill/memory injection, confused-deputy, and tool-abuse cases |
+| Agent identity and delegated authorization | Covered | MCP OAuth/XAA helpers, issuer-minted A2A bearer/delegation tokens, subject/audience/expiry/skill binding, local trust boundaries, permission rules | Keep delegated scopes narrow and auditable; HMAC child-token narrowing remains issuer-side |
 | Multimodal workflows | Partial | `/image`, `/video`, `/youtube`, `/voice`, browser workflows | Add model-aware multimodal capability reporting for local Ollama setups |
 | Spec-driven development | Covered | `ur spec` scaffolds requirements/design/tasks under `.ur/specs/`, tracks phase/approvals, and runs the Spec Kit / Kiro task list one task at a time | Add bidirectional sync with an external `specs/` directory |
 | Capability-aware model escalation | Covered | `ur escalate` selects fast/oracle tiers from `model-doctor`, runs routine work fast, and auto-escalates hard/failed work to the strong local model | Learn per-model success rates to tune the difficulty threshold |
 | Best-of-N agent judging | Covered | `ur arena` runs N agents per task in isolated worktrees and judges diffs with the self-review gate; winner is selectable/appliable | Add an optional model judge alongside the deterministic scorer |
 | Self-healing CI | Covered | `ur ci-loop` reports its resolved cwd, preserves assertion/stack context, stops no-test configuration failures before invoking a fixer, and re-runs real failures with bounded retries; commits/pushes require explicit flags and are self-review gated | Wire to `ur trigger` so a failed CI webhook can explicitly launch the loop |
 | Verifiable artifacts | Covered | `ur artifacts` records plans/diffs/test-runs with approve/reject/feedback under `.ur/artifacts/`; comments steer active background agents through stream-json inbox injection | Attach browser-QA screenshots and link artifacts to claim-ledger entries |
-| Native IDE review | Covered | `ur ide diff` writes `.ur/ide/diffs/` bundles and `extensions/vscode-ur-inline-diffs/` provides a VS Code tree/webview/comment surface | Add JetBrains packaging if demand appears |
-| ACP / IDE agent server | Covered | `ur acp serve|stop|status` exposes an HTTP+JSON-RPC agent server so VS Code/Cursor/Zed extensions can list tools, call tools, and submit tasks | Ship reference editor extensions |
+| Native IDE review | Covered | `ur ide diff` bundles, a VS Code tree/webview/comment surface with background task controls, and a buildable JetBrains ACP client with cancellation | Add signed marketplace packaging and keep behavior parity covered in editor-host integration tests |
+| ACP / IDE agent server | Covered | Official-SDK ACP v1 with durable list/load/delete/resume/close, exact replay, modes, config options, commands, permissions, MCP, roots, streaming, and cancellation | Add editor-host interoperability fixtures before expanding optional UX capabilities |
+| Provider-native durable inference | Covered | Chat Completions remains default; opt-in Responses adds SSE, background polling/cancel, WebSocket continuation, compaction, deferred tools, and `store=false` | Generalize explicit provider capability discovery without silently emulating native features |
 | External tool integration | Covered | Built-in `GitHub`, `Api`, `Browser`, `Docker`, `TestRunner`, and `Database` tools complement existing file-system, terminal, web, and MCP tools | Add richer output parsing and error recovery |
 
 ## v1.13.9 Direct CLI Surfaces
@@ -111,18 +120,59 @@ ur artifacts capture-tests --command "bun test"
 
 ## A2A Position
 
-UR exports an Agent Card so other tools can discover what UR is and what it can
-do. `ur a2a serve` is the opt-in task server: it exposes health, Agent Card,
-task submission, task listing, task status, output, and cancellation routes. It
-refuses off-loopback binds unless bearer or delegation authentication is
-configured, and task execution stays backed by local UR background tasks.
+`ur a2a serve` keeps the official stable JavaScript SDK's v0.3 JSON-RPC binding
+at `/a2a/jsonrpc` and adds separate strict v1 ProtoJSON JSON-RPC and HTTP+JSON
+bindings. `/.well-known/agent-card.json` returns the v1 card by default and the
+v0.3 card for `A2A-Version: 0.3`; `Vary` prevents cache confusion. The v1
+routes provide durable tasks/artifacts, pagination, continuation, references,
+cancellation, and tenant isolation. Streaming and push notifications are not
+advertised.
+
+The existing `/a2a/tasks` submission/list/status/output/cancel routes are a
+separate **UR compatibility API**, not an A2A REST binding. They remain useful
+for UR background-task options such as worktrees and bounded turns. On these
+routes, `skipPermissions` is rejected unless the caller uses the static
+operator token or a token that grants `permissions:bypass`; the official A2A
+runner always uses fail-closed `dontAsk` permissions.
+
+The server refuses unauthenticated off-loopback binds and requires
+`--public-base-url` for wildcard binds so discovery never advertises
+`0.0.0.0`. Prefer `UR_A2A_TOKEN` and `UR_A2A_DELEGATION_SECRET` over argv
+secrets. Request size, prompt size, output size, submission rate, concurrent
+submissions, and active tasks are bounded by `UR_A2A_*` settings. UR's v1
+compatibility layer is covered by the official TCK while the JavaScript SDK's
+v1 line remains prerelease; the stable v0.3 path therefore stays available
+during the negotiated migration.
 
 ## Model Runtime Position
 
-UR intentionally sends model requests only to the local Ollama app. If that app
-exposes local models or Ollama Cloud-backed models, UR treats them the same way:
-as models available through the local Ollama endpoint. This keeps provider
-configuration out of UR and avoids direct model API key handling.
+UR is local-first, not local-only. Ollama supports private on-device execution;
+direct adapters support OpenAI, Anthropic, Gemini, OpenRouter, and compatible
+endpoints; subscription adapters use the provider's authenticated CLI. Provider
+and model selection are explicit, credentials are resolved through the
+credential layer, and the optional fallback setting is diagnostic advice rather
+than an automatic provider switch.
+
+## v1.47 Frontier Priorities
+
+The `1.46.0` frontier set is implemented in `1.47.0`. A second free/open-source
+scan after the version bump also closed AG-UI frontend interoperability,
+cross-client `.agents/skills/` discovery, and the latest OpenTelemetry
+`invoke_workflow`/streaming-chunk latency gap. The remaining ordered backlog keeps
+prerelease protocols opt-in and focuses on evidence and trust:
+
+1. Adopt final MCP 2026 and stable A2A v1 SDK artifacts when published, while
+   preserving dual-stack negotiation and independent-client fixtures.
+2. Add A2A signed-card verification, streaming/resubscription, and push only
+   with authenticated end-to-end conformance tests.
+3. Extend task-memory provenance, deletion proofs, quarantine, and rollback to
+   every team, semantic, embedding-backed, and legacy memory store.
+4. Turn trajectory graders for tool choice, handoffs, policy compliance,
+   recovery, and outcome quality into versioned CI regression gates.
+5. Require registry attestations, dependency review, revocation, and update
+   transparency before one-command community skill/plugin installation.
+6. Enforce claim-to-source links for final web/MCP answers and complete Windows
+   OS-sandbox parity.
 
 ## Source And Trust Policy
 
@@ -141,13 +191,28 @@ Professional answer requirements:
 
 ## References
 
-- OpenAI Agents SDK: https://openai.github.io/openai-agents-python/
-- OpenAI Agents SDK tracing: https://openai.github.io/openai-agents-python/tracing/
+- OpenAI Responses background mode: https://developers.openai.com/api/docs/guides/background
+- OpenAI Responses WebSocket mode: https://developers.openai.com/api/docs/guides/websocket-mode
+- OpenAI Responses compaction: https://developers.openai.com/api/docs/guides/compaction
+- OpenAI deferred tool search: https://developers.openai.com/api/docs/guides/tools-tool-search
+- OpenAI agent evals: https://developers.openai.com/api/docs/guides/agent-evals
 - Model Context Protocol: https://modelcontextprotocol.io/docs/getting-started/intro
-- MCP elicitation specification: https://modelcontextprotocol.io/specification/2025-06-18/client/elicitation
+- MCP 2026-07-28 release candidate: https://blog.modelcontextprotocol.io/posts/2026-07-28-release-candidate/
+- MCP Tasks extension: https://tasks.extensions.modelcontextprotocol.io/
+- MCP Apps extension: https://apps.extensions.modelcontextprotocol.io/
+- ACP v1 schema: https://agentclientprotocol.com/protocol/v1/schema
 - A2A protocol specification: https://a2a-protocol.org/latest/specification/
+- A2A JavaScript SDK: https://github.com/a2aproject/a2a-js
+- Agent Skills specification: https://agentskills.io/specification
+- Agent Skills integration guide: https://agentskills.io/client-implementation/adding-skills-support
+- AG-UI documentation: https://docs.ag-ui.com/
+- AG-UI reference implementation: https://github.com/ag-ui-protocol/ag-ui
+- OpenTelemetry GenAI semantic conventions: https://opentelemetry.io/docs/specs/semconv/registry/attributes/gen-ai/
+- OpenTelemetry GenAI metrics: https://github.com/open-telemetry/semantic-conventions-genai/blob/main/docs/gen-ai/gen-ai-metrics.md
+- OWASP AI Agent Security Cheat Sheet: https://cheatsheetseries.owasp.org/cheatsheets/AI_Agent_Security_Cheat_Sheet.html
+- OWASP Agent Memory Guard: https://owasp.org/www-project-agent-memory-guard/
 - LangGraph overview: https://docs.langchain.com/oss/python/langgraph/overview
-- OpenAI computer use guide: https://platform.openai.com/docs/guides/tools-computer-use
+- OpenAI computer use guide: https://developers.openai.com/api/docs/guides/tools-computer-use
 - Ollama docs: https://docs.ollama.com/
-- MCP authorization specification: https://modelcontextprotocol.io/specification/2025-06-18/basic/authorization
-- MCP security best practices: https://modelcontextprotocol.io/specification/2025-06-18/basic/security_best_practices
+- MCP authorization specification: https://modelcontextprotocol.io/specification/2025-11-25/basic/authorization
+- MCP security best practices: https://modelcontextprotocol.io/specification/2025-11-25/basic/security_best_practices