@arnilo/prism 0.2.8 → 0.3.0

package/docs/antigravity-agent.md

@@ -0,0 +1,207 @@
+# Antigravity delegated agent
+
+## What it does
+
+`@arnilo/prism-antigravity-agent` provides a delegated agent adapter for the official [Google Antigravity CLI (`agy`)](https://github.com/google/antigravity). It enables Prism applications to delegate complex, multi-step coding tasks to an authenticated Antigravity CLI runner while exposing host-owned Prism tools, resources, and prompts over a per-run Model Context Protocol (MCP) server.
+
+The package handles the end-to-end delegated execution lifecycle:
+- Spawns the official headless CLI (`agy --agent <name> --workspace <dir>`) as a managed subprocess.
+- Starts a run-bound loopback HTTP MCP server (`http://127.0.0.1:<port>/mcp`) authorized with an ephemeral Bearer token.
+- Writes ephemeral workspace configuration (`.agents/mcp_config.json` and custom agent instructions) with automatic backup and fail-safe restoration.
+- Parses the CLI's NDJSON output stream and projects steps into standard Prism `AgentEvent`s and [AG-UI](ag-ui.md) timeline activities.
+- Persists and resumes multi-turn conversations via `--conversation <id>`.
+- Provides an optional `createAntigravityDelegationTool` for Prism [supervisors](supervisors.md) and orchestrating agents.
+
+Prism does not manage Google OAuth tokens, cookies, or credentials; the host environment owns the official `agy` binary and interactive authentication state (`agy login` / Google AI Pro subscription).
+
+## When to use it
+
+Use `@arnilo/prism-antigravity-agent` when:
+- You want to delegate autonomous coding sessions to Google Antigravity while exposing host-owned Prism tools and capabilities via MCP.
+- You need structured event streaming, token telemetry, and [AG-UI](ag-ui.md) visual timeline integration for Antigravity executions.
+- You are orchestrating multi-agent workflows where a Prism supervisor or coding agent needs to delegate specialized subtasks to Antigravity.
+- You want conversation continuation across multiple user turns in a persistent session.
+
+Do **not** use it:
+- As a generic LLM model provider. For direct Gemini API or Vertex AI foundation model inference without an autonomous loop, use [`@arnilo/prism-provider-google`](providers/google.md) or [`@arnilo/prism-provider-vertex`](providers/vertex.md).
+- If you require step-by-step turn replacement of Antigravity's internal model loop, compaction, or planning strategy.
+- If you require unreleased raw internal chain-of-thought text. Antigravity reasoning effort is projected as token counts and timeline activity steps, not raw hidden thoughts.
+
+## Inputs / request
+
+`createAntigravityCliAgent(options)` accepts agent configuration:
+
+| Field | Type | Default | Purpose |
+| --- | --- | --- | --- |
+| `command` | `string` | `"agy"` | Path to the official `agy` executable on the host. |
+| `args` | `readonly string[]` | `[]` | Additional command-line arguments passed to the CLI. |
+| `cwd` | `string` | `process.cwd()` | Working directory for the runner process. |
+| `env` | `Record<string, string | undefined>` | `process.env` | Process environment variables. |
+| `timeoutMs` | `number` | `300000` (5m) | Maximum process execution time. |
+| `toolPolicy` | `AntigravityToolPolicy` | `"hybrid"` | Built-in CLI tool permissions (`"hybrid"`, `"all"`, `"none"`, or custom). |
+| `tools` | `ToolDefinition[]` | `[]` | Prism tools exposed to the agent via loopback MCP. |
+| `resources` | `ResourceDefinition[]` | `[]` | Prism resources exposed via loopback MCP. |
+| `prompts` | `PromptDefinition[]` | `[]` | Prism prompt templates exposed via loopback MCP. |
+| `exposure` | `AntigravityMcpExposure` | auto-created | Custom MCP server exposure handle if sharing an external server. |
+| `conversationStore` | `AntigravityConversationStore` | in-memory | Store for persisting conversation IDs across turns. |
+| `redactor` | `SecretRedactor` | auto | Secret redactor applied to events and process output. |
+| `agentName` | `string` | `"prism-agent"` | Ephemeral agent definition identifier. |
+| `systemPrompt` | `string` | built-in instructions | Custom instructions appended to the agent definition. |
+
+`agent.run(runOptions)` executes a prompt run:
+
+| Field | Type | Default | Purpose |
+| --- | --- | --- | --- |
+| `prompt` | `string` | required | User task or instruction for Antigravity. |
+| `workspace` | `string` | `agent.cwd` | Target workspace directory path for file modifications. |
+| `sessionId` | `string` | auto-generated | Prism session identifier for conversation persistence. |
+| `branchId` | `string` | `"main"` | Branch identifier for conversation isolation. |
+| `conversationId` | `string` | auto-resolved | Existing Antigravity conversation ID to resume. |
+| `signal` | `AbortSignal` | omitted | Cancellation signal to abort execution and clean up. |
+| `eventSink` | `(event: AgentEvent) => void` | omitted | Real-time event listener for streaming UI updates. |
+| `toolPolicy` | `AntigravityToolPolicy` | agent default | Per-run override for built-in tool policy. |
+
+## Outputs / response / events
+
+`agent.run()` returns a promise resolving to an `AntigravityRunResult`:
+
+| Field | Type | Purpose |
+| --- | --- | --- |
+| `text` | `string` | Final synthesized response text from the Antigravity CLI. |
+| `conversationId` | `string` | Antigravity conversation ID for subsequent multi-turn resumption. |
+| `exitCode` | `number` | Process exit status code (0 for success). |
+| `durationMs` | `number` | Total elapsed execution time in milliseconds. |
+| `events` | `readonly AgentEvent[]` | Complete sequence of projected Prism events emitted during the run. |
+| `usage` | `UsageReport` | Aggregated prompt, completion, total, and thinking token counts. |
+| `subagents` | `readonly AntigravitySubagentSummary[]` | Subagents spawned and completed during execution. |
+
+### Streamed events
+
+The runner emits standardized Prism `AgentEvent` objects to the provided `eventSink`:
+- `delegated_agent_step`: High-level step progression with step name, status, and duration.
+- `message_delta`: Incremental response text chunks.
+- `tool_call_start` / `tool_call_delta` / `tool_call_result`: MCP tool invocations and results.
+- `agent_thought_chunk`: Thinking activity indicators with token counts.
+- `usage`: Token usage telemetry updates.
+- `subagent_spawn` / `subagent_finish`: Internal subagent hierarchy lifecycle.
+
+## Request/response example
+
+```json
+{
+  "prompt": "Inspect the repository and add unit tests for the auth helper.",
+  "workspace": "/home/user/project",
+  "sessionId": "session-101",
+  "toolPolicy": "hybrid"
+}
+```
+
+```json
+{
+  "text": "Added 4 unit tests covering token refresh and validation in auth.test.ts.",
+  "conversationId": "conv_9876543210",
+  "exitCode": 0,
+  "durationMs": 4250,
+  "usage": {
+    "promptTokens": 1520,
+    "completionTokens": 380,
+    "totalTokens": 1900,
+    "thinkingTokens": 640
+  },
+  "subagents": []
+}
+```
+
+## Implementation example
+
+### Direct runner
+
+```ts
+import { createAntigravityCliAgent } from "@arnilo/prism-antigravity-agent";
+import { createReadTool, createWriteTool } from "@arnilo/prism-coding-agent";
+
+// Configure agent with host-owned Prism tools exposed over MCP
+const agent = createAntigravityCliAgent({
+  command: "agy",
+  tools: [
+    createReadTool({ workspaceRoot: "/home/user/project" }),
+    createWriteTool({ workspaceRoot: "/home/user/project" }),
+  ],
+  toolPolicy: "hybrid", // Built-in bash/editor tools enabled; Prism MCP tools added
+});
+
+// Run a task with real-time event streaming
+const result = await agent.run({
+  prompt: "Refactor error handling in src/utils.ts to use typed AppError",
+  workspace: "/home/user/project",
+  sessionId: "session-42",
+  eventSink: (event) => {
+    if (event.type === "message_delta") {
+      process.stdout.write(event.delta.text);
+    }
+  },
+});
+
+console.log(`\nCompleted in ${result.durationMs}ms with conversation ${result.conversationId}`);
+```
+
+### Supervisor delegation tool
+
+```ts
+import { createSupervisor } from "@arnilo/prism-supervisor";
+import {
+  createAntigravityCliAgent,
+  createAntigravityDelegationTool,
+} from "@arnilo/prism-antigravity-agent";
+
+const antigravity = createAntigravityCliAgent({
+  workspace: "/home/user/project",
+  toolPolicy: "hybrid",
+});
+
+const supervisor = createSupervisor({
+  tools: [
+    createAntigravityDelegationTool({
+      agent: antigravity,
+      name: "delegate_to_antigravity",
+      description: "Delegate complex coding tasks to Google Antigravity CLI",
+    }),
+  ],
+});
+```
+
+## Extension and configuration notes
+
+### Ephemeral workspace configuration
+
+During each execution, the adapter dynamically constructs:
+1. `.agents/mcp_config.json`: Configures the local loopback MCP server endpoint (`http://127.0.0.1:<port>/mcp`) and authorization header.
+2. `.agents/agents/<name>/agent.md`: Configures custom instructions and tool permissions.
+
+If pre-existing configuration files exist in `.agents/`, they are backed up before the run and restored atomically upon completion, failure, or cancellation.
+
+### Tool policies
+
+The `toolPolicy` setting controls built-in CLI capabilities:
+- `"hybrid"` (default): Enables built-in editor, terminal, and search tools while exposing configured Prism MCP tools.
+- `"all"`: Enables all built-in CLI tools and MCP tools.
+- `"none"`: Disables built-in tools; the agent relies exclusively on exposed Prism MCP tools.
+- Custom object `{ allow?: string[], deny?: string[] }`: Explicit allow/deny lists for fine-grained governance.
+
+## Security and performance notes
+
+- **Host-owned authentication**: Prism does not read, store, or forward Google credentials. Authentication state resides in the official `agy` CLI's session store managed via `agy login`.
+- **Loopback isolation**: The ephemeral MCP HTTP server binds exclusively to `127.0.0.1` on a dynamically assigned port, secured with a cryptographically random Bearer token.
+- **Fail-safe cleanup**: Workspace configuration files and HTTP listener ports are cleaned up in `finally` blocks under all exit conditions, including `SIGINT`, timeouts, and unhandled errors.
+- **Secret redaction**: All stdout, stderr, event payloads, and tool arguments are processed through Prism's secret redactor before event emission.
+- **Terms and quota**: Antigravity CLI execution utilizes Google AI Pro subscription quotas through the authenticated official binary. Host operators should verify compliance with their organization's terms of service.
+
+## Related APIs
+
+- [Frontend interoperability (AG-UI and ACP)](ag-ui.md): Connect Antigravity event streams to AG-UI and web interfaces.
+- [MCP client bridge and server exposure](mcp-tools.md): Core Model Context Protocol integration in Prism.
+- [Supervisor delegation](supervisors.md): Hierarchical multi-agent delegation patterns.
+- [Coding agent tools](coding-agent-tools.md): Native Prism file, edit, and terminal tools.
+- [Google Gemini provider](providers/google.md): Direct Gemini API model inference without CLI delegation.
+- [Google Vertex AI provider](providers/vertex.md): Enterprise cloud Vertex AI model inference.
+- [Public contracts](public-contracts.md): Core message, event, tool, and session types.

package/docs/caveman.md

@@ -37,9 +37,9 @@ Session custom entry shape:
 { "kind": "custom", "data": { "type": "caveman-level", "level": "full" } }
 ```
 
-Registered skills: `caveman`, `caveman-commit`, `caveman-review`, `caveman-stats`, `caveman-compress`, `caveman-help`, `cavecrew`.
+Required skills (fail closed if missing): `caveman`, `caveman-commit`, `caveman-review`, `caveman-stats`, `caveman-compress`, `caveman-help`, `cavecrew`. Extra `skills/*/SKILL.md` (v2.1 extras like `caveman-explore`) register as optional skills and `load_skill` commands. Dirs without `SKILL.md` (`*.mjs`, `registry.json`, `generated/`) are skipped.
 
-Registered commands: `caveman`, `caveman-init`, `caveman-commit`, `caveman-review`, `caveman-stats`, `caveman-compress`.
+Registered commands: `caveman` (level), `caveman-init`, plus one `load_skill` dispatch per registered skill except `caveman`.
 
 ## Outputs / response / events
 
@@ -110,6 +110,7 @@ See `examples/caveman-ponytail.ts` for progressive catalog + `load_skill` wiring
 - `caveman-stats` dispatches skill metadata only; full stats need host session-log integration.
 - `caveman-init` returns upstream guidance text; it does not write files in the host repo.
 - No TUI status bar; optional `caveman:status` events for host UI.
+- Caveman 2 compression proxy/engine is **not** a Prism runtime. Only `SKILL.md` files under `skills/` load.
 
 ## Security and performance notes
 

package/docs/coding-agent-tools.md

@@ -10,6 +10,7 @@
 | `createReadTool(cwd, options?)` | `read` tool: read a text or image file into `TextContent` / `ImageContent`. |
 | `createWriteTool(cwd, options?)` | `write` tool: create or overwrite a file, creating parent directories. |
 | `createEditTool(cwd, options?)` | `edit` tool: precise exact-then-fuzzy text replacement in an existing file. |
+| `createAcpFilesystemOperations(client)` | Map an ACP-shaped text-file client to `read`/`write`/`edit` operations; no local-disk fallback, binary/image support, or remote `mkdir`. |
 | `createRepoListTool(cwd, options?)` | `repo_list` tool: bounded deterministic repository listing. |
 | `createRepoSearchTool(cwd, options?)` | `repo_search` tool: bounded literal text search (`outputMode`: content / files_with_matches / count). |
 | `createGlobTool(cwd, options?)` | `glob` tool: bounded filename-pattern match (`*` / `?` / `**`; opt-in bounded `{a,b}` brace expansion via `braceExpansion`). |
@@ -50,6 +51,23 @@ const tools = createToolRegistry(createCodingTools(process.cwd()));
 
 Every tool carries an explicit `kind` (`shell`→`execute`, `read`/`repo_list`→`read`, `write`/`edit`→`edit`, `repo_search`/`glob`→`search`, `delete`→`delete`, `move`→`move`) so ACP `tool_call` updates and other consumers can classify tools without name heuristics.
 
+### ACP editor-buffer operations
+
+`createAcpFilesystemOperations` adapts any client with `readTextFile({ path, line?, limit? })` and `writeTextFile({ path, content })` methods to the `ReadOperations`, `WriteOperations`, and `EditOperations` seams. All reads and writes stay client-backed; `mkdir` is a no-op, `statFile` measures a bounded UTF-8 text read, and image MIME detection is always `null`.
+
+```ts
+import { createAcpFilesystemOperations, createCodingTools } from "@arnilo/prism-coding-agent";
+
+const operations = createAcpFilesystemOperations(clientFilesystem);
+const tools = createCodingTools(cwd, {
+  read: { operations: operations.read },
+  write: { operations: operations.write },
+  edit: { operations: operations.edit },
+});
+```
+
+This is an editor-buffer adapter, not a repository backend: `repo_list`, `repo_search`, `glob`, `delete`, and `move` remain disk-backed unless separately overridden. Binary/image and document reads are not silently delegated to local disk.
+
 ## When to use it
 
 Use this package when a host wants ready-made coding tools for an agent, session, or run, registered explicitly into a `ToolRegistry` and dispatched through the normal Prism tool harness. The tools perform **real** shell and filesystem operations on the host — they are not mocked or sandboxed. Use the individual factories when you need per-tool options or custom operation backends; use the aggregators when you want the default set.
@@ -144,8 +162,10 @@ Read a text or image file.
 | `path` | `string` | Path to the file (relative or absolute; `~` and `file://` expanded). Required. |
 | `offset` | `number` | Line to start reading from (1-indexed). |
 | `limit` | `number` | Maximum number of lines to read. |
+| `findText` | `string` | Literal substring to search for (no regex). When set, the tool pages through the file from `offset` and returns the page starting at the **first matching line** (re-read at the hit line so the match is the first line). No match is an error result with no file body. |
+| `findMode` | `"exact" \| "case-insensitive"` | Match mode for `findText` (default `"exact"`). Two literals only — no regex, no fuzzy. |
 
-**Outputs:** text files are scanned incrementally until one requested page, `maxLines`/`maxBytes`, EOF, or `maxScanBytes` (default 64 MiB scanned per call; 1 GiB hard cap). The default path never loads the complete file and returns a `Use offset=N to continue` footer when more remains. Exact total line count is reported only when EOF was already reached in the bounded scan. Image files (PNG/JPEG/GIF/WebP/BMP by **magic bytes**, not extension) become `[TextContent note, ImageContent]` with base64 `data` and `mimeType`. Oversize images are rejected by `stat` (when available) or `buffer.length` against `maxImageBytes` (default 10 MB) before base64 encoding. An optional `transformImage` callback lets hosts resize or re-encode images without adding image-processing dependencies to the base package. Read failures (missing file, offset beyond end, oversize image, abort) are error results.
+**Outputs:** text files are scanned incrementally until one requested page, `maxLines`/`maxBytes`, EOF, or `maxScanBytes` (default 64 MiB scanned per call; 1 GiB hard cap). The default path never loads the complete file and returns a `Use offset=N to continue` footer when more remains. Exact total line count is reported only when EOF was already reached in the bounded scan. When `findText` is set, the tool pages through `readText` output (in `maxLines`-sized pages) from `offset`, returns the page whose first line is the first match, and stops at the same `maxScanBytes` scan cap — the search is a literal substring scan (per `findMode`), never regex. Image files (PNG/JPEG/GIF/WebP/BMP by **magic bytes**, not extension) become `[TextContent note, ImageContent]` with base64 `data` and `mimeType`. Oversize images are rejected by `stat` (when available) or `buffer.length` against `maxImageBytes` (default 10 MB) before base64 encoding. An optional `transformImage` callback lets hosts resize or re-encode images without adding image-processing dependencies to the base package. Read failures (missing file, offset beyond end, oversize image, abort, findText scan limit) are error results.
 
 `read` tool options (via `createReadTool(cwd, options)` or `ToolsOptions.read`):
 
@@ -166,6 +186,14 @@ const read = createReadTool(cwd, {
   maxImageBytes: DEFAULT_MAX_IMAGE_BYTES,
   transformImage: async ({ buffer, mimeType }) => host.resizeImage(buffer, mimeType),
 });
+
+// jump to the first line containing the needle
+await read.execute({ path: "src/edit.ts", findText: "createEditTool" }, ctx);
+// case-insensitive search starting at offset 50
+await read.execute(
+  { path: "src/edit.ts", findText: "edittool", findMode: "case-insensitive", offset: 50 },
+  ctx,
+);
 ```
 
 `read` result `metadata`:
@@ -236,13 +264,13 @@ Precise text replacement in an existing file via exact-then-fuzzy matching.
 
 Each `edits[].oldText` must match a unique, non-overlapping region of the original file. Matching is exact first, then fuzzy (unicode normalization / whitespace collapse).
 
-**Fuzzy silent-success tradeoff (loud):** when exact match fails, fuzzy may still apply a replacement **without warning the model**. That can edit the wrong region if `oldText` is slightly off (extra/missing whitespace, unicode lookalikes). Prefer exact `oldText` copied from a fresh `read`. Duplicate / non-unique matches already **fail closed** and leave the file unchanged — ambiguity is not silently resolved by picking the first hit.
+**Fuzzy silent-success tradeoff (loud):** when exact match fails, fuzzy may still apply a replacement and is **reported** — both the confirmation text (`Successfully replaced N block(s) in {path} (fuzzy match).`) and `metadata.fuzzy: true`. That can edit the wrong region if `oldText` is slightly off (extra/missing whitespace, unicode lookalikes). Prefer exact `oldText` copied from a fresh `read`. On **no match**, the error lists up to 3 nearby lines (1-indexed, clipped to 120 chars) whose first-line substring matches the edit's first non-empty `oldText` line, so the model can correct its `oldText` (skipped when the needle is shorter than 4 chars or no line contains it). Duplicate / non-unique matches already **fail closed** and leave the file unchanged — ambiguity is not silently resolved by picking the first hit.
 
 A BOM is stripped before matching and re-prepended on write; original line endings are restored. Defaults reject targets over 8 MiB, aggregate old/new UTF-8 input over 2 MiB, or more than 100 edits (hard caps: 64 MiB, 16 MiB, and 1,000). Stat and bounded read checks run before matching or mutation. Default local `writeFile` uses same-directory temp + `rename` (crash-safe replace).
 
-**Outputs:** a `TextContent` confirmation (`Successfully replaced N block(s) in {path}.`) plus `metadata`. Any failure — missing/unreadable file, no match, duplicate (non-unique) match, overlap, empty `oldText`, no-op edit, or abort — is an error result, and the file is left **unchanged** (the match runs before the write).
+**Outputs:** a `TextContent` confirmation (`Successfully replaced N block(s) in {path}.`, with ` (fuzzy match)` appended when the replacement applied via fuzzy matching) plus `metadata`. Any failure — missing/unreadable file, no match (with nearby line context), duplicate (non-unique) match, overlap, empty `oldText`, no-op edit, or abort — is an error result, and the file is left **unchanged** (the match runs before the write).
 
-`edit` result `metadata`: `{ diff, patch, firstChangedLine }` — a display-oriented diff, a standard unified patch, and the first changed line in the new file. These are host-readable; the model only sees the short confirmation (keeps model context small).
+`edit` result `metadata`: `{ path, diff, patch, firstChangedLine, fuzzy? }` — the absolute path written, a display-oriented diff, a standard unified patch, the first changed line in the new file, and `fuzzy: true` present only when the replacement applied via fuzzy (not exact) matching. These are host-readable; the model only sees the short confirmation (keeps model context small).
 
 ### `repo_list`
 

package/docs/computer-use-linux.md

@@ -0,0 +1,122 @@
+# Linux desktop control
+
+## What it does
+
+`@arnilo/prism-computer-use-linux` wraps the host-owned [`computer-use-linux`](https://github.com/agent-sh/computer-use-linux) MCP binary as Prism `ToolDefinition`s. It connects over stdio only when `createComputerUseLinuxTools()` is called, keeps upstream tool names, filters unknown tools, and composes desktop admission, execution approval, result bounds, serialization, redaction, and trust labeling over Prism's existing seams.
+
+The package also exports `loadComputerUseLinuxSkill()`, which loads the short Prism-authored desktop procedure bundled at `skills/computer-use-linux/SKILL.md`. It does not resolve or vendor an upstream skill tree.
+
+## When to use it
+
+Use this package when a Linux host has installed and configured `computer-use-linux` and an agent must inspect or operate that host's desktop. Use the generic [Device adapters](device-adapters.md) contract when implementing another vendor adapter or when the host needs only admission and stream-bound primitives.
+
+Do not use it as a desktop launcher, a cross-platform adapter, or a permission bypass. The host owns the binary, desktop session, sandbox, approval decision, and execution policy.
+
+## Inputs / request
+
+`createComputerUseLinuxTools(options)` accepts:
+
+| Field | Type | Default | Purpose |
+| --- | --- | --- | --- |
+| `command` | `string` | `computer-use-linux` | Host-owned executable. |
+| `args` | `readonly string[]` | `["mcp"]` | MCP server arguments. |
+| `cwd`, `env`, `stderr` | stdio transport options | omitted | Host-owned process configuration. |
+| `serverId` | `string` | `computer-use-linux` | Bridge/error metadata identifier. |
+| `device` | `DeviceAdapter` | required | Must be enabled `desktop-control` with a sandbox. |
+| `runLimits` | `RunLimits` | required | Shared run accounting required by device admission. |
+| `executionPolicy` | `ExecutionPolicy` | omitted | High-risk mutator approval/policy seam. |
+| `approved` | `boolean` | `false` | Host approval for mutating calls. |
+| `includeSetupTools` | `boolean` | `false` | Explicitly expose host setup tools. |
+| `redactor` | `SecretRedactor` | omitted | Redacts returned external data. |
+| `platform` | `NodeJS.Platform` | `process.platform` | Test/host seam; production must be Linux. |
+| `connect` | MCP bridge factory | `connectMcpTools` | Test seam; not needed in production. |
+
+`loadComputerUseLinuxSkill()` takes no arguments and reads only the package-local skill file. The file is capped at 64 KiB.
+
+## Outputs / response / events
+
+| Export | Result |
+| --- | --- |
+| `createComputerUseLinuxTools` | `{ tools, close }`; `tools` contains known upstream tools returned by the bridge. |
+| `tools` | Read observations (`doctor`, app/window discovery, `get_app_state`, `screenshot`) plus mutators; setup tools are excluded by default. |
+| `close()` | Closes the MCP bridge and its host-owned process transport. |
+| `loadComputerUseLinuxSkill` | Prism `Skill` with name `computer-use-linux` and bounded instructions. |
+| `COMPUTER_USE_LINUX_*` constants | Read, mutating, setup, known-name, and skill-name lists for host filtering and registration. |
+| `MAX_SKILL_FILE_BYTES` | 64 KiB bundled-skill read ceiling. |
+| Tool result | External data with `metadata.trust = "untrusted_external"`; screenshot/app-state oversize results become `dropped_oversize`. |
+
+Mutating calls are serialized through one mutex and run `assertDeviceAdmit` plus `assertExecutionAllowed` before the remote MCP call. Read observations bypass per-call approval but still require an admitted device.
+
+## Request/response example
+
+```json
+{
+  "command": "computer-use-linux",
+  "args": ["mcp"],
+  "device": {
+    "kind": "desktop-control",
+    "enabled": true,
+    "requireApproval": true,
+    "sandbox": "linux-desktop"
+  },
+  "runLimits": {
+    "maxTurns": 32,
+    "maxToolCalls": 200
+  },
+  "approved": false,
+  "includeSetupTools": false
+}
+```
+
+## Implementation example
+
+```ts
+import { createToolRegistry, type Skill } from "@arnilo/prism";
+import {
+  createComputerUseLinuxTools,
+  loadComputerUseLinuxSkill,
+} from "@arnilo/prism-computer-use-linux";
+
+async function installDesktop(hostSkills: { register(skill: Skill): void }, hostApproved: boolean) {
+  const desktop = await createComputerUseLinuxTools({
+    device: {
+      kind: "desktop-control",
+      enabled: true,
+      requireApproval: true,
+      sandbox: "linux-desktop",
+    },
+    runLimits: { maxTurns: 32, maxToolCalls: 200 },
+    approved: hostApproved,
+  });
+  const tools = createToolRegistry(desktop.tools);
+  hostSkills.register(loadComputerUseLinuxSkill());
+
+  // Keep `desktop` alive while the run can call `tools`; close it at run end.
+  return { tools, close: () => desktop.close() };
+}
+```
+
+## Extension and configuration notes
+
+- Install and configure the host binary separately: `npm install -g @agent-sh/computer-use-linux` or another host-managed installation. Prism has no runtime dependency on that binary and never downloads it.
+- The factory exposes unprefixed upstream names. Unknown or future upstream names are omitted until Prism classifies them.
+- `setup_accessibility` and `setup_window_targeting` are host-only and omitted unless `includeSetupTools: true` is explicitly selected. The bundled skill never instructs agent turns to perform setup.
+- `connect` is an injectable bridge factory for fake MCP tests. The package's normal path uses `connectMcpTools` with stdio `{ command, args: ["mcp"] }`.
+- `loadComputerUseLinuxSkill()` is inert beyond reading its packaged file; it does not discover peers, resolve paths, or connect to MCP.
+
+## Security and performance notes
+
+- Construction fails closed on non-Linux hosts and requires `DeviceAdapter.kind = "desktop-control"`, explicit `enabled: true`, a sandbox, and shared `RunLimits` before connecting.
+- Mutators are high-risk external mutations: they require device admission, host approval when configured, and `ExecutionPolicy`; input calls are serialized to prevent concurrent desktop state changes.
+- Observation results are untrusted external content and pass the optional host redactor. Screenshot/app-state payloads pass `acceptDeviceChunk`; oversize payloads are replaced with `dropped_oversize`, not forwarded.
+- Imports are inert. The default setup surface is off, the skill file is capped at 64 KiB, and no full upstream skill tree is shipped.
+- The host must keep credentials, desktop session state, binary paths, sandbox identity, and approval state outside model-controlled arguments.
+
+## Related APIs
+
+- [Device adapters](device-adapters.md): generic admission, shared limits, chunk bounds, and telemetry redaction contract.
+- [MCP client bridge](mcp-tools.md): host-owned MCP transport and bounded tool mapping.
+- [Tools](tools.md): registry and dispatch lifecycle for the returned `ToolDefinition`s.
+- [Context and skills](context-and-skills.md): explicit skill registration, activation, and progressive disclosure.
+- [Host security](host-security.md): trust, approval, sandbox, and untrusted external-content boundaries.
+- [Upstream computer-use-linux](https://github.com/agent-sh/computer-use-linux): host binary and desktop prerequisites.

package/docs/context-and-skills.md

@@ -196,7 +196,7 @@ await agent.createSession().run("…", { activeSkills: ["ponytail"] });
 // Turn 1: catalog only. After load_skill({ name: "ponytail" }), later turns include instructions.
 ```
 
-### Third-party behavior packages (Caveman, Ponytail)
+### Third-party behavior packages (Caveman, Ponytail, Impeccable)
 
 `@arnilo/prism-caveman` and `@arnilo/prism-ponytail` register upstream skills into the extension kernel skill registry. Hosts should:
 
@@ -205,7 +205,7 @@ await agent.createSession().run("…", { activeSkills: ["ponytail"] });
 3. Keep `skillsDisclosure: "progressive"` and register `createLoadSkillTool` — full `SKILL.md` bodies stay catalog-only until `load_skill`.
 4. Select `instructionInjectors: ["caveman-mode", "ponytail-mode"]` (or subset) for mode/level slices **without** forcing `skillsDisclosure: "eager"`.
 
-Mode slices and skill bodies are independent: the injector can add `PONYTAIL MODE ACTIVE` while `ponytail-audit` remains catalog-only until loaded. See [Caveman](caveman.md), [Ponytail](ponytail.md), and `examples/caveman-ponytail.ts`.
+Mode slices and skill bodies are independent: the injector can add `PONYTAIL MODE ACTIVE` while `ponytail-audit` remains catalog-only until loaded. See [Caveman](caveman.md), [Ponytail](ponytail.md), [Impeccable](impeccable.md), and `examples/caveman-ponytail.ts`.
 
 Pure validation without the tool: `resolveSkillLoad({ registry, name, tools, loaded, activeSkillNames })`.
 

package/docs/credential-storage.md

@@ -234,7 +234,7 @@ const providers = createOpenAIProviderPackage({ apiKey });
 - Use distinct `namespace` or vault paths per tenant/environment.
 - Keychain `list()` / `listOAuth()` are intentionally unsupported — enumerate credentials through host configuration instead of scanning the OS store.
 - Combine with `createExplicitCredentialResolver()` so runtime overrides still win over stored values.
-- Wire `createOAuthCredentialStoreAdapter(store)` into `refreshOAuthCredential()` only for an OAuth flow explicitly selected by the host and authorized by that provider. In 0.0.12 that means OpenAI Codex; in 0.0.14 the Microsoft 365 / Google Workspace workload providers (`createMicrosoft365OAuthProvider` / `createGoogleWorkspaceOAuthProvider`) are added over the same seam with least-privilege read/mutation scope bundles. Anthropic and Google *model* packages still accept API keys only. Never import or migrate Claude Code/Gemini CLI credential files, setup tokens, browser sessions, or CLI OAuth rows into this store.
+- Wire `createOAuthCredentialStoreAdapter(store)` into `refreshOAuthCredential()` only for an OAuth flow explicitly selected by the host and authorized by that provider. That means OpenAI Codex, xAI SuperGrok / X Premium, and the Microsoft 365 / Google Workspace workload providers (`createMicrosoft365OAuthProvider` / `createGoogleWorkspaceOAuthProvider`) with least-privilege read/mutation scope bundles. Anthropic and Google *model* packages still accept API keys only. Never import or migrate Claude Code/Gemini CLI/`~/.grok` credential files, setup tokens, browser sessions, or CLI OAuth rows into this store.
 - Enterprise cloud providers (`azure` / `bedrock` / `vertex`) expect host workload-identity callbacks (Entra / IAM / ADC), not this local encrypted/keychain store as a cloud token minting service. Store may hold opaque refresh material only when the host already owns the cloud auth flow.
 
 ## Security and performance notes

package/docs/credentials-and-redaction.md

@@ -106,7 +106,7 @@ console.log(error.message);
 
 ### Subscription OAuth eligibility
 
-In 0.0.12, OpenAI Codex is Prism's only first-party subscription OAuth flow. It is explicit and host-invoked through `createOpenAICodexOAuthProvider()`; hosts own login UI and may use `createOAuthCredentialStoreAdapter()` for deliberately selected durable storage.
+First-party subscription OAuth is explicit and host-invoked: OpenAI Codex (`createOpenAICodexOAuthProvider()`) and xAI SuperGrok / X Premium (`createXaiOAuthProvider()`). Hosts own login UI and may use `createOAuthCredentialStoreAdapter()` for deliberately selected durable storage. Do not import `~/.grok` or grok-cli auth files.
 
 Anthropic and Google provider packages are API-key-only. Do not scrape or import Claude Code/Gemini CLI credential files, setup tokens, environment values, or browser sessions, and do not route a user's Claude.ai/Gemini subscription through Prism. Anthropic states that developers building products must use Claude Console API keys or a supported cloud provider and may not offer Claude.ai login or route Free/Pro/Max credentials ([legal and compliance](https://docs.anthropic.com/en/docs/claude-code/legal-and-compliance)). Gemini CLI states that third-party software using its OAuth to access backend services violates applicable terms; its FAQ names Vertex AI or Google AI Studio API keys as the supported third-party path ([terms](https://github.com/google-gemini/gemini-cli/blob/main/docs/resources/tos-privacy.md), [FAQ](https://github.com/google-gemini/gemini-cli/blob/main/docs/resources/faq.md)).
 
@@ -124,7 +124,7 @@ A future provider-local OAuth adapter needs published permission for third-party
 - `resolveCredentialValue()` and `createExplicitCredentialResolver()` do not cache values. Add host-side caching only if a real credential source needs it.
 - `refreshOAuthCredential()` only calls the supplied OAuth provider and optional store; it has no built-in persistence or retry loop.
 - OpenAI Codex device-code OAuth polls inside `createOpenAICodexOAuthProvider().login()` with bounded delays and abort support via `OAuthLoginCallbacks.signal`. Token-endpoint failures redact authorization codes, PKCE verifiers, device/user codes, and access/refresh tokens when those values are known.
-- The shared bounded device/token flow lives in core `pollDeviceCodeToken` (0.2.1) and is used by the OpenAI Codex provider and the credentials-node OAuth 2.0 provider (Microsoft 365 / Google Workspace). It owns the RFC 8628 device-code request and poll loop (`authorization_pending` continue, `slow_down` +5s backoff, expiry deadline, abort), reads every response body under the shared byte ceiling, parses success bodies with a fail-closed shape gate (an `access_token` string is required), and redacts device/user codes, authorization codes, PKCE verifiers, and tokens from every thrown error. Adapter-specific fields (message prefix, extra token params, account binding) are plain options, never subclasses.
+- The shared bounded device/token flow lives in core `pollDeviceCodeToken` (0.2.1) and is used by the OpenAI Codex provider and the credentials-node OAuth 2.0 provider (Microsoft 365 / Google Workspace). It owns the RFC 8628 device-code request and poll loop (`authorization_pending` continue, `slow_down` +5s backoff, expiry deadline, abort), reads every response body under the shared byte ceiling, parses success bodies with a fail-closed shape gate (an `access_token` string is required), and redacts device/user codes, authorization codes, PKCE verifiers, and tokens from every thrown error. Adapter-specific fields (message prefix, extra token params, account binding) are plain options, never subclasses. Optional `bodyEncoding: "form"` POSTs `application/x-www-form-urlencoded` for both the device-code request and every token poll (default remains `json` so existing callers stay byte-compatible). `extraDeviceParams` merge into the device-code body only. `verification_uri` and optional `verification_uri_complete` must be `https:`; the complete URI is what `onDeviceCode` receives when present.
 
 ## Related APIs
 

package/docs/device-adapters.md

@@ -2,7 +2,7 @@
 
 ## What it does
 
-Optional realtime voice and desktop OS / computer-control surface for Prism agents, shipped in 0.0.14 as a **contract + deny-by-default policy only** in `@arnilo/prism` (`src/devices.ts`). No vendor voice or desktop-control implementation ships in 0.0.14 — those are demand-gated to 0.1.x. The contract composes over the existing `PermissionPolicy`, `RunLimits`, approval (`tool_approval`), and redactor seams; it adds no second approval runtime and no device framework.
+Optional realtime voice and desktop OS / computer-control surface for Prism agents, shipped in 0.0.14 as a **contract + deny-by-default policy** in `@arnilo/prism` (`src/devices.ts`). The first vendor adapter, `@arnilo/prism-computer-use-linux`, wraps the host-owned `computer-use-linux` MCP binary without changing this generic contract. The contract composes over the existing `PermissionPolicy`, `RunLimits`, approval (`tool_approval`), and redactor seams; it adds no second approval runtime and no device framework.
 
 ## When to use it
 
@@ -79,7 +79,7 @@ if (chunk.accepted) emit(redactDeviceTelemetry(createSecretRedactor([token]), fr
 
 - Frozen caps: audio/screenshot/stream chunk **1 MiB / 8 MiB**; concurrent device sessions per identity **1 / 4**. Device wall time / turns / tool calls consume the shared `RunLimits` (admission fails closed without run accounting).
 - `enabled` resolves to `true` only on an explicit `true`; any other value is disabled. `requireApproval` stays `true` unless the host explicitly sets `false` (it should not).
-- Vendor voice / desktop-control packages are **deferred to 0.1.x** and ship only if Task 0 records measured demand. This page documents the contract they must satisfy via `runDevicePolicyConformance`.
+- `@arnilo/prism-computer-use-linux` is the first vendor package. It remains optional, Linux-only, host-binary-owned, and outside umbrella profiles; this page stays generic so future voice or desktop vendors can satisfy the same contract via `runDevicePolicyConformance`.
 
 ## Security and performance notes
 
@@ -91,7 +91,8 @@ if (chunk.accepted) emit(redactDeviceTelemetry(createSecretRedactor([token]), fr
 ## Related APIs
 
 - [Browser automation](browser-automation.md): verified-state checkpoints + reload/verify-before-side-effect for browser composition.
+- [Linux desktop control](computer-use-linux.md): first-party host-owned `computer-use-linux` MCP wrapper using this contract.
 - [Conversations](conversations.md): durable threads that own the runs device sessions bind to.
 - [Host security](host-security.md): approval, sandbox, and egress trust boundaries device adapters compose over.
 - [Performance and resource limits](performance.md): shared `RunLimits` accounting.
-- [Migration](migration.md): 0.0.14 additive seams and 0.1.x device vendor deferral.
+- [Migration](migration.md): historical 0.0.14 additive seams and device-vendor deferral; the 0.3.0 desktop wrapper is additive and optional.

package/docs/extensions.md

@@ -142,6 +142,7 @@ await kernel.middleware.run("provider_request", { metadata: {} });
 - [Observational memory compaction package](compaction-observational-memory.md): optional extension helper that registers an inert fast memory compaction strategy.
 - [Caveman behavior integration](caveman.md): optional `@arnilo/prism-caveman` upstream Caveman skills, commands, level injector, and session `caveman-level` persistence.
 - [Ponytail behavior integration](ponytail.md): optional `@arnilo/prism-ponytail` upstream Ponytail skills, commands, mode injector, and session `ponytail-mode` persistence.
+- [Impeccable behavior integration](impeccable.md): optional `@arnilo/prism-impeccable` upstream Impeccable skill and `load_skill` command.
 - [Public contracts](public-contracts.md): `Extension`, `ExtensionAPI`, and contribution contract types.
 - [Credentials and redaction](credentials-and-redaction.md): secret-redaction behavior used for extension errors.
 

package/docs/impeccable.md

@@ -0,0 +1,102 @@
+# Impeccable behavior integration
+
+## What it does
+
+`@arnilo/prism-impeccable` is an optional package that wires a host-supplied
+[Impeccable](https://github.com/pbakaus/impeccable) `SKILL.md` into Prism skill
+and command registries.
+
+It registers one skill (`impeccable`) and one command (`impeccable`) that
+dispatches `{ skill: "impeccable", dispatch: "load_skill" }`. Import and
+`setup` without a readable `SKILL.md` fail closed with a bounded redacted
+error and register zero contributions.
+
+Prism does not vendor skill bodies, run the detector CLI, spawn a browser,
+install hooks, or write `PRODUCT.md` / `DESIGN.md`.
+
+## When to use it
+
+Use it when a host has a compiled Impeccable checkout (or a linked skills dir)
+and wants the design skill in a Prism extension kernel via progressive
+`load_skill`.
+
+Skip it when you only need the detector CLI (`npx impeccable`) or live browser
+iteration — those stay host-owned.
+
+## Inputs / request
+
+`createImpeccableExtension(options)`:
+
+| Field | Type | Required | Purpose |
+| --- | --- | --- | --- |
+| `upstreamPath` | `string` | yes | Path to a tree with `skills/impeccable/SKILL.md` or `SKILL.md` at the path (e.g. `dist/universal/impeccable`). |
+
+No optional peer. npm `impeccable` is the detector CLI, not a skill tree.
+
+## Outputs / response / events
+
+| Export | Purpose |
+| --- | --- |
+| `createImpeccableExtension(options)` | Inert `Extension` until `kernel.load([...])`. |
+| `impeccable` skill | Parsed upstream `SKILL.md` (`name: impeccable`). |
+| `impeccable` command | Dispatch `{ skill: "impeccable", dispatch: "load_skill" }`. |
+
+No instruction injector. No session persistence. No 23 Prism-native craft/polish commands.
+
+## Request/response example
+
+```json
+{ "command": "impeccable", "args": {}, "sessionId": "s1" }
+```
+
+```json
+{ "skill": "impeccable", "dispatch": "load_skill" }
+```
+
+## Implementation example
+
+```ts
+import { createImpeccableExtension } from "@arnilo/prism-impeccable";
+import {
+  createExtensionKernel,
+  createLoadSkillTool,
+  createLoadedSkillSet,
+  createSkillRegistry,
+} from "@arnilo/prism";
+
+const kernel = createExtensionKernel({ errorPolicy: "throw" });
+await kernel.load([
+  createImpeccableExtension({
+    upstreamPath: "/path/to/impeccable/dist/universal/impeccable",
+  }),
+]);
+
+const registry = createSkillRegistry(kernel.registries.skills.list());
+const loaded = createLoadedSkillSet();
+const loadSkill = createLoadSkillTool({ registry, loaded });
+await kernel.registries.commands.get("impeccable")!.execute({}, { sessionId: "s1" });
+```
+
+Keep `skillsDisclosure: "progressive"` so the full `SKILL.md` stays catalog-only until `load_skill`.
+
+## Extension and configuration notes
+
+- `sideEffects: false`. Import registers nothing.
+- `kernel.load` resolves `SKILL.md` first; failure throws before any `register*`.
+- Point `upstreamPath` at a compiled skill dir or a parent that contains `skills/impeccable/SKILL.md`.
+- Do not invent per-command Prism wrappers for upstream `craft` / `polish` / `live`.
+- Not in `@arnilo/prism-all` / `prism-code` / `prism-sdk`.
+
+## Security and performance notes
+
+- Upstream `SKILL.md` is untrusted host content; reads capped at `MAX_SKILL_FILE_BYTES` (256 KiB).
+- Path escape rejected. Errors redact home and absolute paths.
+- No `npx`, hook install, env scan, or network on import/setup.
+- Setup is one bounded file read.
+
+## Related APIs
+
+- [Caveman behavior integration](caveman.md)
+- [Ponytail behavior integration](ponytail.md)
+- [Extension kernel and event bus](extensions.md)
+- [Context and skills](context-and-skills.md)