ur-agent 1.28.1 → 1.30.1

package/docs/ACP.md

@@ -0,0 +1,85 @@
+# Agent Communication / Client Protocol (ACP)
+
+UR exposes two ACP surfaces:
+
+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.
+
+## Stdio ACP agent
+
+```sh
+ur acp stdio
+```
+
+The editor launches this process and exchanges one JSON-RPC object per line.
+
+Methods:
+
+| Method | Direction | Result |
+| --- | --- | --- |
+| `initialize` | client → agent | `{ protocolVersion, agentCapabilities, authMethods }` |
+| `authenticate` | client → agent | `{}` (no auth required for local stdio) |
+| `session/new` | client → agent | `{ sessionId }` |
+| `session/prompt` | client → agent | `{ stopReason }`, with streaming `session/update` notifications |
+| `session/cancel` | client → agent (notification) | aborts the in-flight prompt |
+| `shutdown` | client → agent | `null` |
+
+During `session/prompt` the agent emits `session/update` notifications:
+
+```json
+{ "jsonrpc": "2.0", "method": "session/update",
+  "params": { "sessionId": "sess_…",
+    "update": { "sessionUpdate": "agent_message_chunk",
+                "content": { "type": "text", "text": "…" } } } }
+```
+
+`session/prompt` resolves with `{ "stopReason": "end_turn" }` (or `"cancelled"`
+if a `session/cancel` arrived). Configure it with `ur ide config zed`.
+
+## HTTP JSON-RPC server
+
+```sh
+ur acp serve --host 127.0.0.1 --port 8123 [--token <secret>] [--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 }`.
+
+Methods: `initialize` (returns `capabilities` and `workspaceRoot`),
+`session/new`, `session/prompt`, `session/cancel`, `tools/list`, `tools/call`,
+`tasks/send` / `tasks/get` / `tasks/cancel`, `ide/diffCapture`, `ide/select`,
+and `shutdown` (acknowledges, then stops the server).
+
+Example:
+
+```sh
+curl -s http://127.0.0.1:8123/acp \
+  -H 'content-type: application/json' \
+  -d '{"jsonrpc":"2.0","id":1,"method":"initialize"}'
+```
+
+```json
+{ "jsonrpc": "2.0", "id": 1,
+  "result": { "name": "ur-agent", "protocolVersion": "0.1.0",
+    "workspaceRoot": "/path/to/project",
+    "capabilities": { "tools": true, "tasks": true, "sessions": true,
+      "ide": true, "streaming": false, "cancellation": true } } }
+```
+
+## Capabilities and limitations
+
+- The stdio agent streams via `session/update`; token-level granularity depends
+  on the active provider.
+- 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
+  reported with the selected provider, model, and runtime backend.
+- Errors use JSON-RPC error objects (`-32601` method not found, `-32602` bad
+  params, `-32001` unauthorized, `-32603` internal).

package/docs/IDE.md

@@ -0,0 +1,77 @@
+# IDE Integration
+
+UR integrates with editors through three mechanisms, chosen per editor and stated
+honestly — nothing claims support it does not have:
+
+- **Native extension** — a UR extension/plugin runs inside the editor (VS Code
+  family, JetBrains). UR connects to it via the `/ide` flow.
+- **Stdio ACP** — the editor launches UR as an [Agent Client Protocol](ACP.md)
+  agent over stdio (`ur acp stdio`). Used by Zed and ACP-capable Neovim clients.
+- **Manual** — no auto-config; install a plugin and connect via `/ide`.
+
+## Supported targets
+
+| Editor | Mechanism | Auto config | Apply/reject | Notes |
+| --- | --- | --- | --- | --- |
+| VS Code | native extension | `.vscode/settings.json` | via UR extension | Install the UR Inline Diffs extension. |
+| Cursor | native extension (VS Code fork) | `.vscode/settings.json` | via UR extension | Same extension as VS Code. |
+| Windsurf | native extension (VS Code fork) | `.vscode/settings.json` | via UR extension | Same extension as VS Code. |
+| Zed | stdio ACP | `.zed/settings.json` | in-editor (ACP) | Real Agent Client Protocol over stdio. |
+| JetBrains | manual plugin | none | via plugin | Install the UR JetBrains plugin, then `/ide`. |
+| Neovim | stdio ACP | snippet | client-dependent | Requires a third-party ACP client plugin. |
+| Generic ACP | stdio ACP / HTTP | snippet | client-dependent | `ur acp stdio` (native ACP) or `ur acp serve` (HTTP JSON-RPC). |
+
+## Commands
+
+```sh
+ur ide status               # workspace, ACP server, provider/model, plugin count, warnings
+ur ide doctor               # pass/warn/fail checks; reports missing config clearly
+ur ide config <editor>      # print setup + config snippet for the chosen editor
+ur ide open                 # open the current project/worktree in a detected IDE
+ur ide diff capture         # capture the current diff as a review bundle
+ur ide diff list|show <id>  # inspect captured bundles
+ur ide diff approve|reject <id>
+```
+
+`ur ide config` targets: `vscode`, `cursor`, `windsurf`, `zed`, `jetbrains`,
+`neovim`, `generic-acp` (aliases like `nvim`, `intellij`, `code` also resolve).
+
+`ur ide status` reports the active workspace, whether the ACP server is running
+and on which port, the active provider/model and runtime backend, the number of
+loaded plugins, and any warnings. Add `--json` for machine-readable output.
+
+## Patch / diff workflow
+
+UR never writes to your files silently. Proposed changes are captured as bundles
+under `.ur/ide/diffs/` (`ur ide diff capture`), then previewed and explicitly
+applied or rejected:
+
+- **CLI:** `ur ide diff show <id>`, `ur ide diff approve <id>`, `ur ide diff reject <id>`.
+- **VS Code:** the UR Inline Diffs view lists bundles; right-click a bundle to
+  Open (preview), Apply (`git apply`, with a confirmation prompt), Reject, or
+  Comment. Applying is always an explicit, confirmed action.
+
+## VS Code extension
+
+The bundled `UR Inline Diffs` extension (`extensions/vscode-ur-inline-diffs`)
+provides:
+
+- a tree view of captured diff bundles;
+- a read-only webview preview of each patch and its comments;
+- **Apply** (confirmed `git apply`) and **Reject** actions;
+- **UR: Show Status**, which runs `ur ide status` and prints provider/model and
+  plugin information to the UR output channel.
+
+Install it with `ur ide install` (offers the bundled VSIX) or from the packaged
+`.vsix`. Apply/reject and status require the UR CLI on your `PATH`.
+
+## Troubleshooting
+
+- **`ur ide status` shows "ACP server: not running":** start it with
+  `ur acp serve` (HTTP) or `ur acp stdio` (for ACP editors).
+- **No IDE detected:** ensure the editor is running with the UR extension/plugin
+  installed, or generate config with `ur ide config <editor>`.
+- **Zed doesn't see UR:** confirm `.zed/settings.json` contains the
+  `agent_servers.UR` block from `ur ide config zed`, then reload Zed.
+- **Apply fails in VS Code:** the patch may not match the current tree; re-capture
+  with `ur ide diff capture`.

package/docs/USAGE.md

@@ -246,7 +246,7 @@ Interactive sessions include a compact bottom status bar when stdout is a real
 terminal:
 
 ```text
-UR-AGENT v1.25.3 | Provider: Ollama | Auth: local | model: qwen3-coder:480b-cloud | mode: ask | branch: main | tasks: idle | Update: 1.25.2 -> 1.25.3 available
+UR-AGENT v1.30.1 | Provider: Codex CLI | Auth: subscription | model: codex/gpt-5.5 | mode: ask | branch: main | tasks: idle | Update: 1.30.0 -> 1.30.1 available
 ```
 
 The bar is not rendered in non-interactive mode, CI, dumb terminals, or

package/docs/plugins.md

@@ -50,3 +50,80 @@ ur --plugin-dir ./plugins/community/my-plugin
 
 Plugins are loaded from local UR-AGENT paths first. Network marketplace installs
 remain explicit user actions and are subject to plugin policy checks.
+
+## Manifest reference
+
+A plugin is a directory containing `.ur-plugin/plugin.json`. UR uses a
+**declarative component model** — a manifest points at markdown/JSON components
+rather than a JS entry point.
+
+| Field | Type | Purpose |
+| --- | --- | --- |
+| `name` | string (required) | Unique plugin id. |
+| `version` | string | Semver; recommended for updates. |
+| `description` | string | Shown in `ur plugin list`. |
+| `author` | object | `{ name, url, email }`. |
+| `commands` | string \| string[] \| object | Path(s) to markdown commands. |
+| `agents` | string \| string[] | Path(s) to agent definitions. |
+| `skills` | string \| string[] | Path(s) to `SKILL.md` skills. |
+| `templates` | string \| string[] | Path(s) to templates. |
+| `validators` | string \| string[] | Path(s) to JSON validators. |
+| `outputStyles` | string \| string[] | Path(s) to output styles. |
+| `hooks` | object | Lifecycle hooks (see below). |
+| `mcpServers` | object | MCP servers the plugin registers. |
+| `lspServers` | object | LSP servers for language adapters. |
+| `languageAdapters` | object | Language → engine/LSP metadata. |
+| `dependencies` | object | Other plugins that must be enabled. |
+
+Validate a manifest strictly at any time:
+
+```sh
+ur plugin validate <path-to-plugin-or-manifest>
+ur plugin doctor                 # validate all installed/project/bundled plugins
+ur plugin doctor --path plugins/core --json
+```
+
+`ur plugin doctor` reports, per plugin, whether the manifest is valid, its
+version, the declared components, and the **capability surface** it touches
+(commands, skills, templates, validators, hooks, mcpServers, lspServers,
+languageAdapters). A broken plugin is reported but never crashes the scan or UR.
+
+## Hooks
+
+Hooks run on lifecycle events and are ordered, isolated, and load-error safe:
+`BeforeEdit`, `AfterEdit`, `BeforeCommand`, `AfterCommand`, `BeforeCommit`, and
+`OnFailure`. Declare them under `hooks` in the manifest. A hook failure is
+isolated to that plugin.
+
+## Plugin commands
+
+```sh
+ur plugin list [--json]          # installed plugins
+ur plugin doctor [--json]        # validate manifests + capability report
+ur plugin validate <path>        # validate a single manifest
+ur plugin install <name>         # install from a marketplace
+ur plugin enable <name>          # enable an installed plugin
+ur plugin disable <name>         # disable (not loaded until re-enabled)
+ur plugin uninstall <name>
+```
+
+Disabled plugins are not loaded. Enable/disable state persists in user settings.
+
+## Permissions
+
+UR's declarative model grants only what a plugin declares. Components run in the
+same trust model as the CLI: commands/skills/templates are content, MCP and LSP
+servers are launched only when the plugin is enabled, and network marketplace
+installs are always explicit user actions gated by plugin policy. `ur plugin
+doctor` surfaces the capability surface so you can review what a plugin touches
+before enabling it.
+
+## Troubleshooting
+
+- **Plugin not loaded:** run `ur plugin list` to confirm it is installed and
+  enabled; `ur plugin doctor` to confirm the manifest validates.
+- **Manifest rejected:** `ur plugin doctor` prints the exact schema errors
+  (field path + message).
+- **Command not found after install:** ensure the manifest `commands` path
+  points at existing markdown files; re-run `ur plugin doctor`.
+

package/docs/providers.md

@@ -158,7 +158,7 @@ ur config set provider anthropic-api
 
 | Provider type | Model discovery | Source label |
 | --- | --- | --- |
-| Subscription CLI (codex-cli, claude-code-cli, gemini-cli, antigravity-cli) | Static list of provider-specific models | static |
+| Subscription CLI (codex-cli, claude-code-cli, gemini-cli, antigravity-cli) | Static list of provider-scoped CLI model aliases/names | static |
 | API providers (openai-api, anthropic-api, gemini-api, openrouter) | Static list of provider-specific models | static |
 | Local/server providers (ollama, lmstudio, llama.cpp, vllm) | Dynamic discovery from the selected provider endpoint | live |
 | OpenAI-compatible | Dynamic discovery from configured endpoint | live |
@@ -211,6 +211,10 @@ Warning: Current model "gpt-5.5" is not available for provider "anthropic-api" a
   After changing provider, run /model or: ur config set model claude-sonnet-5
 ```
 
+For subscription CLIs, UR stores scoped IDs such as `claude-code/sonnet` and
+passes only the CLI model name (`sonnet`) to the official command. Stale scoped
+IDs such as `claude-code/sonnet-5` are rejected before runtime dispatch.
+
 ### Troubleshooting
 
 **Check active provider and model:**

package/documentation/index.html

@@ -44,7 +44,7 @@
     <main id="content" class="content">
       <header class="topbar">
         <div>
-          <p class="eyebrow">Version 1.25.3</p>
+          <p class="eyebrow">Version 1.30.1</p>
           <h1>UR-AGENT Documentation</h1>
           <p class="lead">A practical, tutorial-style reference for installing, configuring, automating, extending, and operating UR-AGENT.</p>
         </div>
@@ -159,7 +159,7 @@ ur config set provider.fallback ollama</code></pre>
           </article>
           <article>
             <h3>Status bar and updates</h3>
-            <pre><code>UR-AGENT v1.25.3 | Provider: Ollama | Auth: local | model: qwen3-coder:480b-cloud | mode: ask | branch: main | tasks: idle | Update: 1.25.2 -&gt; 1.25.3 available</code></pre>
+            <pre><code>UR-AGENT v1.30.1 | Provider: Codex CLI | Auth: subscription | model: codex/gpt-5.5 | mode: ask | branch: main | tasks: idle | Update: 1.30.0 -&gt; 1.30.1 available</code></pre>
             <p>The interactive status bar shows provider, auth mode, model, branch, task state, checks status when known, and update availability. It is hidden in CI, dumb terminals, and non-interactive mode.</p>
           </article>
         </div>

package/extensions/vscode-ur-inline-diffs/extension.js

@@ -1,7 +1,11 @@
 const fs = require('node:fs')
 const path = require('node:path')
+const { execFile } = require('node:child_process')
+const { promisify } = require('node:util')
 const vscode = require('vscode')
 
+const execFileAsync = promisify(execFile)
+
 function workspaceRoot() {
   return vscode.workspace.workspaceFolders?.[0]?.uri.fsPath
 }
@@ -171,13 +175,96 @@ async function commentDiff(item, provider) {
   vscode.window.showInformationMessage(`Added UR comment to ${bundle.id}.`)
 }
 
+function setBundleStatus(root, bundleId, status) {
+  const manifest = loadManifest(root)
+  const bundle = manifest.diffs.find(diff => diff.id === bundleId)
+  if (!bundle) return null
+  bundle.status = status
+  bundle.updatedAt = new Date().toISOString()
+  writeJson(manifestPath(root), manifest)
+  writeJson(metadataPath(root, bundle), bundle)
+  return bundle
+}
+
+// Apply the captured patch to the working tree. Never silent: the user is asked
+// to confirm, and the result is reported. Uses `git apply` from the repo root.
+async function applyDiff(item, provider) {
+  const root = workspaceRoot()
+  const bundle = item?.bundle
+  if (!root || !bundle) {
+    vscode.window.showWarningMessage('No UR inline diff selected.')
+    return
+  }
+  const patch = patchPath(root, bundle)
+  if (!fs.existsSync(patch)) {
+    vscode.window.showErrorMessage(`UR patch file missing for ${bundle.id}.`)
+    return
+  }
+  const choice = await vscode.window.showWarningMessage(
+    `Apply UR patch ${bundle.id} to your working tree? This modifies ${bundle.files?.length ?? 0} file(s).`,
+    { modal: true },
+    'Apply',
+  )
+  if (choice !== 'Apply') return
+  try {
+    await execFileAsync('git', ['apply', '--whitespace=nowarn', patch], { cwd: root })
+    setBundleStatus(root, bundle.id, 'applied')
+    provider.refresh()
+    vscode.window.showInformationMessage(`Applied UR patch ${bundle.id}.`)
+  } catch (error) {
+    const message = error?.stderr || error?.message || String(error)
+    vscode.window.showErrorMessage(`Failed to apply UR patch ${bundle.id}: ${message}`)
+  }
+}
+
+async function rejectDiff(item, provider) {
+  const root = workspaceRoot()
+  const bundle = item?.bundle
+  if (!root || !bundle) {
+    vscode.window.showWarningMessage('No UR inline diff selected.')
+    return
+  }
+  const updated = setBundleStatus(root, bundle.id, 'rejected')
+  if (!updated) {
+    vscode.window.showErrorMessage(`UR inline diff not found: ${bundle.id}`)
+    return
+  }
+  provider.refresh()
+  vscode.window.showInformationMessage(`Rejected UR patch ${bundle.id} (no files changed).`)
+}
+
+async function showStatus(channel) {
+  const root = workspaceRoot()
+  if (!root) {
+    vscode.window.showWarningMessage('Open a workspace folder to query UR status.')
+    return
+  }
+  channel.clear()
+  channel.show(true)
+  channel.appendLine('Running: ur ide status')
+  try {
+    const { stdout } = await execFileAsync('ur', ['ide', 'status'], { cwd: root })
+    channel.appendLine(stdout.trim())
+  } catch (error) {
+    channel.appendLine(
+      `Could not run \`ur ide status\`: ${error?.message || String(error)}\n` +
+        'Ensure the UR CLI is installed and on PATH.',
+    )
+  }
+}
+
 function activate(context) {
   const provider = new DiffProvider()
+  const channel = vscode.window.createOutputChannel('UR')
   context.subscriptions.push(
+    channel,
     vscode.window.registerTreeDataProvider('urInlineDiffs', provider),
     vscode.commands.registerCommand('urInlineDiffs.refresh', () => provider.refresh()),
     vscode.commands.registerCommand('urInlineDiffs.open', item => openDiff(item)),
     vscode.commands.registerCommand('urInlineDiffs.comment', item => commentDiff(item, provider)),
+    vscode.commands.registerCommand('urInlineDiffs.apply', item => applyDiff(item, provider)),
+    vscode.commands.registerCommand('urInlineDiffs.reject', item => rejectDiff(item, provider)),
+    vscode.commands.registerCommand('urInlineDiffs.status', () => showStatus(channel)),
   )
 }
 

package/extensions/vscode-ur-inline-diffs/package.json

@@ -1,8 +1,8 @@
 {
   "name": "ur-inline-diffs",
   "displayName": "UR Inline Diffs",
-  "description": "Review UR inline diff bundles from .ur/ide/diffs inside VS Code.",
-  "version": "1.25.3",
+  "description": "Review, apply, and reject UR inline diff bundles from .ur/ide/diffs inside VS Code.",
+  "version": "1.30.1",
   "publisher": "ur-agent",
   "engines": {
     "vscode": "^1.92.0"
@@ -14,7 +14,10 @@
     "onView:urInlineDiffs",
     "onCommand:urInlineDiffs.refresh",
     "onCommand:urInlineDiffs.open",
-    "onCommand:urInlineDiffs.comment"
+    "onCommand:urInlineDiffs.comment",
+    "onCommand:urInlineDiffs.apply",
+    "onCommand:urInlineDiffs.reject",
+    "onCommand:urInlineDiffs.status"
   ],
   "main": "./extension.js",
   "contributes": {
@@ -47,6 +50,18 @@
       {
         "command": "urInlineDiffs.comment",
         "title": "UR: Comment On Inline Diff"
+      },
+      {
+        "command": "urInlineDiffs.apply",
+        "title": "UR: Apply Inline Diff"
+      },
+      {
+        "command": "urInlineDiffs.reject",
+        "title": "UR: Reject Inline Diff"
+      },
+      {
+        "command": "urInlineDiffs.status",
+        "title": "UR: Show Status (provider, model, plugins)"
       }
     ],
     "menus": {
@@ -55,6 +70,11 @@
           "command": "urInlineDiffs.refresh",
           "when": "view == urInlineDiffs",
           "group": "navigation"
+        },
+        {
+          "command": "urInlineDiffs.status",
+          "when": "view == urInlineDiffs",
+          "group": "navigation"
         }
       ],
       "view/item/context": [
@@ -63,10 +83,20 @@
           "when": "view == urInlineDiffs && viewItem == diff",
           "group": "inline"
         },
+        {
+          "command": "urInlineDiffs.apply",
+          "when": "view == urInlineDiffs && viewItem == diff",
+          "group": "1_actions"
+        },
+        {
+          "command": "urInlineDiffs.reject",
+          "when": "view == urInlineDiffs && viewItem == diff",
+          "group": "1_actions"
+        },
         {
           "command": "urInlineDiffs.comment",
           "when": "view == urInlineDiffs && viewItem == diff",
-          "group": "inline"
+          "group": "2_review"
         }
       ]
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ur-agent",
-  "version": "1.28.1",
+  "version": "1.30.1",
   "description": "UR-AGENT — autonomous engineering workflow engine (plan, execute, test, verify, document, benchmark, reproduce)",
   "type": "module",
   "packageManager": "bun@1.3.14",