The cross-harness, self-improving memory layer for AI agents. Join our community: https://discord.com/invite/zdNChS2fBu
Go agent-ai-cliagent-harnessesagent-securitybrowser-extensionciclaude-codecloudcodexcursordetection-engineeringjevknowledge-basememorymobile-device-managementobservabilitysecuritysecurity-information-and-event-managementsecurity-toolstelemetrytraces
Document Prime Agent as a collected runtime
Claude785a8e478523
diff --git a/CLAUDE.md b/CLAUDE.mdindex ebde4abd..7ea035d9 100644--- a/CLAUDE.md+++ b/CLAUDE.md@@ -12,7 +12,7 @@ Beacon Endpoint Agent is a local-only endpoint telemetry agent for AI runtimes.- `packages/asymptote-sdk-js`: TypeScript SDK for cloud agent telemetry that exports Beacon-compatible OpenTelemetry spans.- `browser-extension`: optional Chrome MV3 collector that relays Claude.ai and ChatGPT chat telemetry into the local pipeline as OTLP.- `pkg/asymptoteobserve`: shared Go library — event schema, harness-name normalization, provenance markers, token usage, and the threat-rules engine. Imported by the CLI, the hook adapter, and the collector exporter, so a change here reaches all three.-- `plugins`: TypeScript sources for the managed runtime plugins/extensions (`opencode-beacon`, `cline-beacon`, `pi-beacon`, `omp-beacon`), each mirrored into an embedded copy under `cli/beacon/internal/endpoint/hooks/assets/`.+- `plugins`: TypeScript sources for the managed runtime plugins/extensions (`opencode-beacon`, `cline-beacon`, `pi-beacon`, `omp-beacon`, `prime-beacon`), each mirrored into an embedded copy under `cli/beacon/internal/endpoint/hooks/assets/`.- `rules` and `spec/threat-rules`: the open rule corpus and the Threat Rules format it conforms to.- `beacon-sandbox`: harness that runs a real Claude Code session in a disposable sandbox and checks what Beacon captured. See `beacon-sandbox/AGENTS.md`.- `packaging`: macOS, Linux, and Windows packaging and deployment assets.@@ -41,13 +41,14 @@ Supported runtime surfaces today:- Cline hook telemetry through a Beacon-managed local plugin (`~/.cline/plugins/beacon.ts`) covering prompts, task lifecycle, tool lifecycle, commands, file reads/edits with diffs, MCP activity, and task token usage. One plugin serves Cline's VS Code, JetBrains, and CLI hosts; Cline's own OTel export and hosted prompt storage are not used. Approval decisions are not exposed by Cline's hook payloads and are not synthesized.- Pi hook telemetry through a Beacon-managed local extension (`~/.pi/agent/extensions/beacon.ts`, or `.pi/extensions/beacon.ts` at project level) covering session lifecycle, prompts, tool lifecycle and results, commands including operator `!` commands, file reads/creates/edits with the unified patch, agent reasoning from assistant thinking parts, and token usage/cost. The extension subscribes to seven Pi event types and ignores the streaming and provider internals. Approval decisions are not exposed by Pi's extension API -- its `tool_call` handler can block, but that is an extension deciding rather than an operator being asked -- and are not synthesized, matching the Cline decision.- Oh My Pi (`omp`) hook telemetry through a Beacon-managed local extension (`~/.omp/agent/extensions/beacon.ts`, or `.omp/extensions/beacon.ts` at project level) covering session lifecycle, prompts, tool lifecycle and results, operator approval decisions, commands including operator `!` and `$` Python commands, file reads/creates/edits with the unified patch, MCP tool activity, agent reasoning, and token usage/cost. Oh My Pi is a fork of pi-mono and kept Pi's event payload shapes, so the two share one mapper (`cli/beacon-hooks/cmd/pi_family.go`) but never share identity: separate harness names, separate extension markers, separate install directories. Unlike Pi and Cline it does expose real operator approval decisions (`tool_approval_requested`/`tool_approval_resolved`), so those are recorded as `observed` approvals rather than withheld -- Beacon still never synthesizes one from a blocking `tool_call` handler. Those events carry no tool arguments, so the extension remembers each `tool_call`'s input by `toolCallId` and attaches it to the approval; without it the approval rules, which all match on `command.command` or `file.path`, could not read Oh My Pi approvals at all. The user-level install path honors `PI_CODING_AGENT_DIR` and `PI_CONFIG_DIR`; the project path is always `.omp/extensions`. `mcp_notification` is deliberately not subscribed to.+- Prime Agent (Prime Intellect) hook telemetry through a Beacon-managed local extension (`~/.prime/agent/extensions/beacon.ts`, or `.prime/agent/extensions/beacon.ts` at project level) covering session lifecycle, prompts, tool lifecycle and results, commands, file edits with the unified patch, agent reasoning, and token usage/cost. Prime Agent is the other hard fork of pi-mono, so it shares the `pi_family.go` mapper with Pi and Oh My Pi and never shares their identity: separate harness name (`prime_agent`), separate extension marker, separate install directory. Its subscription list is Pi's exactly, and that is a finding rather than a copy -- it has no `user_python` (its operator surface is `!` alone) and no approval event at all, so approvals are not synthesized, matching the Pi, Cline and fx decision. What is different is its single-tool design: the only default tool is `ipython`, a persistent Python kernel through which the agent reads files, writes files and runs shell commands via `bash()`, so a cell is recorded as `command.executed` with the code in `command.command` and a Python marker in `raw` -- filing it under `tool.completed` would hide essentially every action the agent took from the command-scoped rules. A cell's result carries its captured streams as `command.output`, the runtime's own duration and status (`ok`/`error`/`aborted`; an interrupted cell is not a failed one), and its exception class; no exit code is invented, because a Python cell has none. The diffs the kernel streams for files it rewrote become one `file.modified` each, built with `FromEditFragments` because the pair is a replaced span rather than the file before and after. Two path details are the runtime's own: its config directory name is the two-segment literal `.prime/agent`, joined under the working directory as well as the home directory, so its *project* scope keeps the `agent` segment Pi's and Oh My Pi's drop; and its agent-directory override is `PRIME_AGENT_CODING_AGENT_DIR`, derived from its own package name, so `PI_CODING_AGENT_DIR` is deliberately not honored. MCP is not separately attributed and cannot be: consistent with the single-tool design, Prime Agent does not expose MCP servers as agent tools -- each integration is a Python skill package the model imports and calls from inside the kernel -- so an MCP call arrives as part of a cell's code rather than as an `mcp.tool_invoked` event.- Muse Code (Meta) hook telemetry through a Beacon-owned managed hooks file (`$XDG_CONFIG_HOME/muse/beacon-endpoint-hooks.json`, else `~/.config/muse/...`) that Muse's own `settings.json` points at with the `managed_hooks_path` key. Covers session start, prompts, tool lifecycle, operator approval decisions from `PermissionRequest`, subagent start/stop, context compaction, commands, and file activity. Muse Spark is the model and Muse Code is the agent: the harness is `muse_code`, and Muse Spark spellings are deliberately unmapped in `NormalizeHarnessName` so a model id cannot masquerade as the runtime. `PreLLMCall`/`PostLLMCall` are deliberately not subscribed to -- both carry the full `messages` array and tool schemas on every model call, and `PostLLMCall` fires per response chunk. Not collected, because Muse exposes none of it on a hook: token usage/cost, a session-end event, and subagent-to-parent correlation. Muse publishes no hook API, so the contract is reverse-engineered from a shipped build and a bad hooks file is rejected in total silence -- which is why the installer's emitted shape and the payload readers are both pinned by tests. Implementation lives in `cli/beacon/internal/endpoint/hooks/muse.go` and the `muse` platform branches in `cli/beacon-hooks/cmd`.- OpenHands (All Hands) hook telemetry through the runtime's own `.openhands/hooks.json`, which Beacon merges its six commands into rather than owning. Covers session start and end, prompts, pre-tool and post-tool activity, commands with exit code and output, file reads and edits, MCP tool calls, and failed tools. The harness is `openhands`; OpenHands LM spellings are deliberately unmapped in `NormalizeHarnessName` so a model id cannot masquerade as the runtime. OpenHands rides the shared hook subcommands rather than getting a mapper of its own, because its six events line up one for one with them; the runtime-specific readers live in `cli/beacon-hooks/cmd/openhands.go` and the installer in `cli/beacon/internal/endpoint/hooks/openhands.go`. File diffs come from the observation's `old_content`/`new_content` rather than from the edit instruction, so they describe what landed on disk; one `apply_patch` call becomes one `file.modified` per changed file. Approval decisions are not exposed by OpenHands' hooks and are not synthesized, matching the Cline, Pi and fx decision. Not collected, because OpenHands exposes none of it on a hook: token usage and cost, a per-call tool id, and assistant response text. The verbatim payload is deliberately not retained under `raw`: its only unhoused field is `metadata`, which is empty on five of six events and constant on the sixth. `hooks.json` has a closed schema that rejects silently -- unknown top-level keys are fatal, a legacy `{"hooks": {...}}` wrapper replaces the whole document, and naming one event in both snake_case and PascalCase takes the file down -- so the installer refuses a file that already breaks one of those, and both the emitted shape and the payload readers are pinned by tests. Both scopes are real, but project scope is the one every host reads: the loader takes the first hooks file it finds rather than merging, and the agent server behind the CLI and the GUI reads only the project file.- Kiro (AWS) hook telemetry through a Beacon-owned hook file in the directory Kiro scans (`.kiro/hooks/beacon-endpoint.json` at project scope, `$KIRO_HOME`/`~/.kiro/hooks/` at user scope). Covers session start, prompts, pre-tool and post-tool activity, commands with output, file reads and edits, MCP tool calls, failed tools, and the agent's final response from `Stop`'s `assistant_response` as an `agent.message`. The harness is `kiro` -- one name for the IDE and the CLI, because they are one harness reading one hooks directory. Kiro rides the shared hook subcommands: its envelope is spelled exactly as Claude Code's (`hook_event_name`, `cwd`, `session_id`, `tool_name`, `tool_input`, `tool_response`, `prompt`), so `cli/beacon-hooks/cmd/kiro.go` holds no envelope readers at all -- only the tool taxonomy, the `operations`-array path reader, MCP `@server/tool` detection, and the write-`command` guard. Kiro publishes its tool names and not its tool argument schemas, so classification is keyed on names and the diff builder reads both the Amazon Q lineage spellings (`file_text`, `old_str`, `new_str`) and the ecosystem ones, returning no diff rather than a wrong one when neither resolves. Two contract details are load-bearing and easy to get wrong: hook stdout is *added to the agent's context* on `SessionStart` and `UserPromptSubmit`, so Beacon writes nothing to stdout on this platform (`hookStdoutIsConsumedAsAgentContext`); and a block is exit code 2 with the reason on stderr rather than a JSON object, which is why the policy seam's deny is a `policyDenial` carrying an exit code. Timeouts are seconds and `0` means no timeout at all, so every trigger carries an explicit value. Beacon owns one filename in a directory Kiro loads whole, so the installer never reads another file and refuses rather than overwriting one it did not write. Approval decisions are not exposed by Kiro's hooks and are not synthesized -- Kiro does ask the operator through `permissions.yaml` and a trust picker, and `PreToolUse` fires identically whether or not it will, so an inferred approval would claim a decision precisely where none was made. Not subscribed to: `PostFileCreate`/`PostFileSave`/`PostFileDelete`, which duplicate `PostToolUse` for the same write; `PreTaskExec`/`PostTaskExec`, whose stdin payload Kiro does not document; and `Manual`. Not collected, because Kiro exposes none of it on a hook: token usage and cost, a per-call tool id, and a session-end event. Implementation lives in `cli/beacon-hooks/cmd/kiro.go` and `cli/beacon/internal/endpoint/hooks/kiro.go`.- goose (Block) telemetry over two paths that are collected together because neither is sufficient alone. The hook path is a Beacon-owned plugin: goose discovers plugins as the immediate subdirectories of `.agents/plugins` (user scope honours `GOOSE_PATH_ROOT`; project scope is always `<project>/.agents/plugins`) and loads `<plugin-root>/hooks/hooks.json` from each, so Beacon owns the directory `beacon-endpoint` rather than a file. Seven of goose's twelve events are subscribed to -- `SessionStart`, `UserPromptSubmit`, `PreToolUse`, `PostToolUse`, `PostToolUseFailure`, `Stop`, `SessionEnd` -- covering session lifecycle, prompts, tool lifecycle, command lines, file creates and edits with diffs, and MCP tool calls. The OTLP path configures `otel_exporter_otlp_endpoint` in goose's own `config.yaml` and carries what no hook does: token usage including cache reads and writes, model and provider, response ids, finish reasons and agent reasoning, on OTel GenAI semconv `chat` and `execute_tool` spans the collector exporter already reads. The harness is `goose`; GooseAI spellings are deliberately unmapped in `NormalizeHarnessName` and unaccepted as targets, because that is a different company's inference service rather than this runtime. Four contract details are load-bearing. goose classifies a *blocking* hook's stdout, so `PreToolUse` and `Stop` must answer `{"decision":"allow"}` -- the `{}` every other runtime reads as no opinion is classified a failed hook, and on a rule configured `on_failure: block` it denies the tool call; the policy seam's deny is correspondingly `{"decision":"block"}`, because goose does not recognise "deny" and would read it as no verdict and allow. `developer` is registered with `unprefixed_tools`, so its tools arrive as bare `shell`, `write`, `edit`, `tree`, `read_image`, and MCP tools are identified only by their `<extension>__<tool>` prefix not naming a built-in extension -- there is no `mcp` in the name, no `mcp_*` argument and no result to inspect. `PostToolUseFailure` carries a payload identical to `PostToolUse`, so the `event` field is the only thing separating a write that landed from one that did not, and it is what the diff guard turns on. And goose exports OTLP over HTTP only, so it takes the collector's HTTP port where Claude Code, Codex and Gemini take gRPC; pointing it at 4317 fails silently. `BeforeShellExecution`, `AfterShellExecution`, `BeforeReadFile` and `AfterFileEdit` are deliberately not subscribed to -- each duplicates `PreToolUse`/`PostToolUse` for the same call and carries no `tool_call_id` -- and `PreToolUseResult` is deferred because it fires once per call to report an outcome that is almost always "allow". Not collected, because goose exposes none of it on a hook: tool output of any kind (so no command exit codes, no command output, no file-read contents), reported cost, and approval decisions -- goose does ask the operator through `ToolApprovalOperation`, exposes none of it, and its `PreToolUse` chain is a separate plugin-policy layer that runs after the operator's decision, so an approval derived from it would claim a decision precisely where Beacon cannot see one. `.agents/plugins` is the shared Open Plugins directory rather than goose's own namespace, so another host implementing that specification would also run these hooks and Beacon could not tell from the payload; that is a stated limitation with no fix on Beacon's side. **Only the adapter half of this is implemented.** `cli/beacon-hooks/cmd/goose.go` maps the payloads and `NormalizeHarnessName` pins the name, so a `hooks.json` that invokes `beacon-hooks --platform goose` is collected correctly today. There is no installer: `goose` is not an accepted `beacon endpoint hooks install --harness` target, there is no `cli/beacon/internal/endpoint/hooks/goose.go`, and no `harness.DiscoverGoose` configures `otel_exporter_otlp_endpoint` in goose's `config.yaml`. Both files must be written by hand. `docs/runtimes/goose.mdx` and the README runtime table both describe the install commands as if they shipped; they have not. Close that gap before treating goose as a supported install target.- fx (vercel-labs/fx) telemetry read from the session store fx commits under `~/.fx/sessions/`, covering session start, prompts, tool calls, commands with exit codes and output, file reads/creates/edits with diffs, MCP tool calls, agent messages, history compaction, and per-turn token usage plus reported cost. fx exposes no third-party hook, plugin, or OTLP surface -- its lifecycle hooks are compiled into the binary -- so collection is a read of fx's own records, run by `beacon endpoint fx sync`. Every event carries `harness.collection_method=poll`; approvals are not synthesized (fx persists permission feedback text, not a per-call decision, matching the Cline and Pi posture) and no session-end event is invented, since fx sessions are resumable. Implementation lives in `cli/beacon/internal/fxsession` and `cli/beacon/cmd/endpoint_fx.go`.- Claude Cowork admin-configured OpenTelemetry setup guidance and local validation.-- Runtimes that ride the shared hook and OTLP paths without a contract worth writing down here: Antigravity CLI, Devin CLI, Devin Desktop, Factory Droid, Gemini CLI, GitHub Copilot CLI, Grok Build, Hermes Agent, OpenCode (a Beacon-managed plugin, `plugins/opencode-beacon`), Qwen Code, and VS Code. OpenClaw Gateway is OTLP setup guidance and status checking under `cli/beacon/internal/endpoint/integrations/openclaw`, the same shape as Cowork, rather than a harness. The bullets above are the runtimes with a reverse-engineered or otherwise surprising contract, not the full supported set — `harness.DiscoverAll` in `cli/beacon/internal/endpoint/harness` and the install switch in `cli/beacon/cmd/endpoint_hooks.go` are the authoritative lists. Prime Agent has a reserved harness name and a `plugin` collection method but no collection path yet.+- Runtimes that ride the shared hook and OTLP paths without a contract worth writing down here: Antigravity CLI, Devin CLI, Devin Desktop, Factory Droid, Gemini CLI, GitHub Copilot CLI, Grok Build, Hermes Agent, OpenCode (a Beacon-managed plugin, `plugins/opencode-beacon`), Qwen Code, and VS Code. OpenClaw Gateway is OTLP setup guidance and status checking under `cli/beacon/internal/endpoint/integrations/openclaw`, the same shape as Cowork, rather than a harness. The bullets above are the runtimes with a reverse-engineered or otherwise surprising contract, not the full supported set — `harness.DiscoverAll` in `cli/beacon/internal/endpoint/harness` and the install switch in `cli/beacon/cmd/endpoint_hooks.go` are the authoritative lists.- Browser chat telemetry through an optional Chrome MV3 extension (`browser-extension/`) covering claude.ai and chatgpt.com. A main-world interceptor tees the streamed response, a per-site adapter parses it into a normalized turn, and the service worker POSTs OTLP GenAI logs to the local collector on `127.0.0.1:4318`; the extension never writes files and never contacts a remote endpoint. `harness.name` resolves to `claude_web` or `chatgpt_web` (already handled by `NormalizeHarnessName` in `pkg/asymptoteobserve/harness.go`, where the browser cases must stay above the generic `claude` rule) and `harness.collection_method` is `otlp`. Scope is deliberately narrow: only those origins' chat streams, never other tabs or general browsing. Retention defaults to `full`, so prompt and response text is retained by default; this is documented rather than defaulted down, because browser chat telemetry without content has no investigative value. Treat the adapters as experimental, since both sites' stream formats are private and undocumented.- `beaconjson` OpenTelemetry Collector exporter that converts OTLP logs, traces, metrics, and resource attributes into Beacon endpoint JSONL.- Endpoint inventory (`inventory.heartbeat` / `inventory.snapshot` in `inventory_state.jsonl`) is written by a scheduled job, `com.beacon.endpoint.inventory` (`service.InventoryManager`, user LaunchAgent or system LaunchDaemon, `beacon-inventory.timer` on systemd), every six hours and once at load, on by default and reconciled by `lifecycle.ReconcileInventoryJob` on every install, repair and package upgrade (`beacon endpoint inventory install-daemon`). Agent hooks do not trigger inventory any more; the hook binary's `--cli` flag and `inventory-heartbeat` subcommand survive only as no-ops for hook commands written by older versions, and `beacon endpoint inventory heartbeat --trigger hook` is likewise retired. A system-mode run inventories the active console user's home and still writes the liveness heartbeat when nobody is logged in; the scheduled scan has no working directory, so project-scoped config is only in `beacon endpoint inventory`.@@ -124,6 +125,7 @@ cd plugins/opencode-beacon && bun run check && bun testcd ../cline-beacon && bun run check && bun testcd ../pi-beacon && bun run check && bun testcd ../omp-beacon && bun run check && bun test+cd ../prime-beacon && bun run check && bun test```After editing a plugin or extension source, run `bun run sync` in its directory to update the@@ -491,7 +493,7 @@ unpacked through Chrome's developer mode.`.github/workflows/ci.yml` runs these jobs on every pull request and on pushes to `main`:-- `go-test` (macOS): `bun run check && bun test` in all four `plugins/*` directories, then `make build-hooks-current`, then `go test ./...` in `cli/beacon`, `go test -race ./internal/endpoint/...`, `go test ./...` in `cli/beacon-hooks`, `collector-builder/exporter/beaconjsonexporter`, and `pkg/asymptoteobserve` (includes threat-rules pack conformance), then CLI help smoke checks that also assert removed commands stay unexposed.+- `go-test` (macOS): `bun run check && bun test` in all five `plugins/*` directories, then `make build-hooks-current`, then `go test ./...` in `cli/beacon`, `go test -race ./internal/endpoint/...`, `go test ./...` in `cli/beacon-hooks`, `collector-builder/exporter/beaconjsonexporter`, and `pkg/asymptoteobserve` (includes threat-rules pack conformance), then CLI help smoke checks that also assert removed commands stay unexposed.- `linux-test` (ubuntu) and `windows-test` (windows-2025) rerun the Go suites per platform. The Windows job tests a measured package list rather than `./...`; the excluded packages are tracked in #318, and the scope must not be widened back to `./...`.- `typescript-sdk` (Node 20, 22, 24): `npm test`, `npm run check`, `npm run build`, `npm run pack:dry-run`, `npm run pack:smoke` in `packages/asymptote-sdk-js`.- `browser-extension` (Node 22): `npm run check`, `npm run test:unit`, `npm run build`, a check that the build is a loadable MV3 extension, and the Playwright replay e2e running the real extension in headless Chromium against a local HTTPS replay server; the HTML report and traces upload on failure.diff --git a/README.md b/README.mdindex 3dc5d504..43d8d3f2 100644--- a/README.md+++ b/README.md@@ -178,7 +178,7 @@ for the full breakdown by surface.| <img src="cli/beacon/internal/endpoint/dashboard/static/runtime-logos/opencode.png" alt="" width="16"> | [OpenCode](https://docs.asymptotelabs.ai/cli/supported-runtimes-opencode) | Plugin | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ || <img src="cli/beacon/internal/endpoint/dashboard/static/runtime-logos/openhands.png" alt="" width="16"> | [OpenHands](https://docs.asymptotelabs.ai/runtimes/openhands) | Hooks | ✅ | ✅ | ✅ | ✅ | ✅ | – | ✅ | – || <img src="cli/beacon/internal/endpoint/dashboard/static/runtime-logos/pi-agent.png" alt="" width="16"> | [Pi](https://docs.asymptotelabs.ai/runtimes/pi) | Extension | ✅ | ✅ | ✅ | ✅ | ✅ | – | – | ✅ |-| <img src="cli/beacon/internal/endpoint/dashboard/static/runtime-logos/prime-agent.png" alt="" width="16"> | [Prime Agent](https://docs.asymptotelabs.ai/runtimes/prime-agent) | Not yet collected | – | – | – | – | – | – | – | – |+| <img src="cli/beacon/internal/endpoint/dashboard/static/runtime-logos/prime-agent.png" alt="" width="16"> | [Prime Agent](https://docs.asymptotelabs.ai/runtimes/prime-agent) | Extension | ✅ | ✅ | ✅ | ✅ | ✅ | – | – | ✅ || <img src="cli/beacon/internal/endpoint/dashboard/static/runtime-logos/qwen-code.png" alt="" width="16"> | [Qwen Code](https://docs.asymptotelabs.ai/runtimes/qwen-code) | Hooks | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | – | – || <img src="cli/beacon/internal/endpoint/dashboard/static/runtime-logos/visual-studio-code.png" alt="" width="16"> | [VS Code](https://docs.asymptotelabs.ai/cli/supported-runtimes-vscode) | OTLP + hooks | ✅ | ✅ | ✅ | ~ | ~ | – | ~ | – |diff --git a/docs/cli/token-usage.mdx b/docs/cli/token-usage.mdxindex 12cf655b..b20770b7 100644--- a/docs/cli/token-usage.mdx+++ b/docs/cli/token-usage.mdx@@ -44,6 +44,7 @@ Token coverage is not uniform, and the reason is almost always the runtime rathe| OpenCode | input, output, cache read, cache creation, reasoning | Reported (`cost_usd`) | Yes | Yes || Pi | input, output, cache read, cache creation, reasoning | Reported (`cost_usd`) | Yes | Yes || Oh My Pi | input, output, cache read, cache creation, reasoning | Reported (`cost_usd`) | Yes | Yes |+| Prime Agent | input, output, cache read, cache creation, reasoning | Reported (`cost_usd`) | Yes | Yes || fx (Vercel Labs) | input, output, cache read, cache creation | Reported (`cost_usd`) | Yes | Yes |Cline reports usage once per task rather than per model call, because Beacon's rollups sum `gen_ai.usage` across events and reporting at both granularities would count every token twice. fx reports cumulative totals, which Beacon differences into per-turn deltas for the same reason.@@ -88,7 +89,6 @@ A runtime that reports occupancy and no spend still shows as `not_instrumented`| Qwen Code | The `Stop` payload carries session-level context counters, not per-call usage. Those counters are recorded as context occupancy rather than spend -- see [Context occupancy](#context-occupancy) below. See [Qwen Code](/runtimes/qwen-code) || OpenHands | None of the six hook payloads carries token counts, and OpenHands exposes no other hook that would. See [OpenHands](/runtimes/openhands) || Kiro | No Kiro hook payload carries token counts. See [Kiro](/runtimes/kiro) |-| Prime Agent | No managed extension ships yet, so nothing is collected || Claude.ai | The adapter parses counts, but no recorded claude.ai stream has carried a usage object. See [Claude.ai](/runtimes/claude-web#limits) || ChatGPT | The chat stream reports no token counts || Devin Cloud | Devin bills ACUs rather than tokens. The count is preserved in the Devin raw block; there is no token or USD equivalent to normalize it into |diff --git a/docs/runtimes/index.mdx b/docs/runtimes/index.mdxindex 7019b49e..42c9177d 100644--- a/docs/runtimes/index.mdx+++ b/docs/runtimes/index.mdx@@ -39,11 +39,11 @@ These integrations are grouped by where the agent runs and how telemetry is coll| [OpenCode](/runtimes/opencode) | Managed plugin hooks | Chat messages, session events, command execution, permission activity, diffs, and errors || [OpenHands](/runtimes/openhands) | Native hooks merged into the repository's own `.openhands/hooks.json` | Session start and end, prompts, pre-tool and post-tool activity, commands with exit codes and output, file reads and edits with exact before/after diffs, MCP tool calls, and failed tools. No approval decisions or token usage, because OpenHands exposes neither on a hook || [Pi](/runtimes/pi) | Managed extension hooks | Session lifecycle, prompts, tool lifecycle, commands including operator `!` commands, file reads and edits with the unified patch, agent reasoning, and token usage |-| [Prime Agent](/runtimes/prime-agent) | Not yet collected | Harness identity only. Prime Agent is recognized as its own runtime and its collection method is defined, but no managed extension ships yet, so no events are collected |+| [Prime Agent](/runtimes/prime-agent) | Managed extension hooks | Session lifecycle, prompts, tool lifecycle, commands including each `ipython` kernel cell and operator `!` commands, file edits with the unified patch, agent reasoning, and token usage. No approval decisions, because Prime Agent exposes none; MCP calls are not separately attributed, because it does not expose MCP as agent tools || [Qwen Code](/runtimes/qwen-code) | Native hooks | Session, prompt, pre-tool, post-tool, failed tool, permission request, subagent, stop, session-end, command, and file telemetry || [VS Code](/runtimes/vscode) | Copilot Chat OTel plus optional preview hooks | Copilot session, prompt, model, and tool activity through OTel; optional hooks for extra lifecycle and cross-agent detail |-Two rows in that table are not hook or OTLP integrations. [fx](/runtimes/vercel-fx) exposes no hook, plugin, or OpenTelemetry surface at all, so Asymptote reads the session records fx commits to disk; every fx event is marked `harness.collection_method=poll`, meaning it was read after the turn was committed rather than observed as the agent worked, and nothing on that path can hold or deny a tool call. [Prime Agent](/runtimes/prime-agent) is listed because Asymptote already recognizes it as its own harness, but no managed extension ships yet, so it collects nothing today.+One row in that table is not a hook or OTLP integration. [fx](/runtimes/vercel-fx) exposes no hook, plugin, or OpenTelemetry surface at all, so Asymptote reads the session records fx commits to disk; every fx event is marked `harness.collection_method=poll`, meaning it was read after the turn was committed rather than observed as the agent worked, and nothing on that path can hold or deny a tool call.### Local knowledge worker agent harnessesdiff --git a/docs/runtimes/integration-model.mdx b/docs/runtimes/integration-model.mdxindex 68369258..35164a40 100644--- a/docs/runtimes/integration-model.mdx+++ b/docs/runtimes/integration-model.mdx@@ -68,7 +68,7 @@ During install, Beacon configures the runtime surfaces it can safely manage:| [Cline](/runtimes/cline) | Managed local plugin through `beacon-hooks` | One plugin covers the VS Code, JetBrains, and CLI hosts; it forwards run and tool hooks for prompt, task lifecycle, tool, command, file, MCP, and token telemetry. || [Pi](/runtimes/pi) | Managed local extension through `beacon-hooks` | Pi has no hooks file and no OTLP export, so the TypeScript extension API is the only observation surface. Beacon's managed extension subscribes to seven Pi event types and forwards session, prompt, tool, command, file, reasoning, and usage telemetry. || [Oh My Pi](/runtimes/oh-my-pi) | Managed local extension through `beacon-hooks` | A pi-mono fork that kept Pi's event payload shapes, so the two share one mapper but never share identity: separate harness names, separate extension markers, separate install directories. Unlike Pi it exposes real operator approval decisions, which are recorded as `observed` approvals. |-| [Prime Agent](/runtimes/prime-agent) | Not yet collected | Another pi-mono fork with the same extension API. Harness identity and the plugin collection method ship today; the managed extension, discovery probe, and install target do not, so no Prime Agent events are collected yet. |+| [Prime Agent](/runtimes/prime-agent) | Managed local extension through `beacon-hooks` | The other pi-mono fork, sharing Pi's event payload shapes and so Pi's mapper, but never Pi's identity: separate harness name, separate extension marker, separate install directory. Its single-tool design is what makes it different to read -- the agent works through one persistent Python kernel rather than separate file and shell tools, so a cell is recorded as a command and the diffs the kernel streams become one file event per changed file. Like Pi, it exposes no operator approval decision, and Beacon does not synthesize one. || [fx (Vercel Labs)](/runtimes/vercel-fx) | Poll of fx's own session store | fx exposes no third-party observation surface: its lifecycle hooks are compiled into the binary, it has no OpenTelemetry export, and its plugin story is MCP. Beacon reads the append-only session records under `~/.fx/sessions` and marks every event `harness.collection_method=poll`, so a consumer knows nothing on this path could have been intercepted. || [Muse Code](/runtimes/muse-code) | Native hook payloads through `beacon-hooks` | Beacon writes a managed hooks file it owns outright and points Muse's own `settings.json` at it with the `managed_hooks_path` key, then maps session, prompt, tool, command, file, approval, subagent, and compaction events into endpoint events. Muse ships an OTLP export that cannot be pointed at a local collector, so hooks are the only collection path. || [goose](/runtimes/goose) | Native hook payloads through `beacon-hooks`, plus goose's own OTLP export | Beacon installs a plugin of its own into the `.agents/plugins` directory goose discovers, leaving every other plugin untouched, then maps session, prompt, tool, command, file and MCP events into endpoint events. goose populates no tool output on a hook, so the second path is not optional in practice: pointing goose's OpenTelemetry export at the local collector is what carries token usage, model, provider and reasoning. goose classifies a blocking hook's stdout, so Beacon answers `PreToolUse` and `Stop` with an explicit allow rather than the usual no-op object. |diff --git a/docs/runtimes/prime-agent.mdx b/docs/runtimes/prime-agent.mdxindex 4abe1f72..1d7bf262 100644--- a/docs/runtimes/prime-agent.mdx+++ b/docs/runtimes/prime-agent.mdx@@ -1,49 +1,153 @@---title: "Prime Agent"-description: "Asymptote support status for Prime Agent (Prime Intellect) endpoint telemetry"+description: "Asymptote support details for Prime Agent (Prime Intellect) endpoint telemetry"---## Runtime overview-[Prime Agent](https://github.com/PrimeIntellect-ai/prime-agent) is Prime Intellect's coding and research harness. Like [Oh My Pi](/runtimes/oh-my-pi), it is a hard fork of [pi-mono](https://github.com/badlogic/pi-mono) and kept its TypeScript extension API, so it fits the same integration shape as [Pi](/runtimes/pi): no hooks configuration file to merge a managed hook block into, and no OpenTelemetry export to point at the local collector.+Asymptote supports [Prime Agent](https://github.com/PrimeIntellect-ai/prime-agent), Prime Intellect's coding and research harness, through a managed local extension.++<Note>+Prime Agent is a hard fork of [pi-mono](https://github.com/badlogic/pi-mono), as [Oh My Pi](/runtimes/oh-my-pi) is. All three are supported separately and recorded under their own harness names, because they are separately installed products that one machine can run side by side.+</Note>++Prime Agent fits neither of Asymptote's two usual integration shapes. It has no hooks configuration file to merge a managed hook block into, and no OpenTelemetry export to point at the local collector. Its documented observation surface is the TypeScript extension API it inherited from Pi, so the integration is extension-shaped: one Asymptote-owned extension file forwards runtime events to `beacon-hooks`, the same shape as the [Pi](/runtimes/pi), [Oh My Pi](/runtimes/oh-my-pi), [OpenCode](/cli/supported-runtimes-opencode) and [Cline](/cli/supported-runtimes-cline) integrations.++```bash+beacon endpoint hooks install --harness prime+```++## The single-tool design changes what telemetry looks like++Prime Agent gives the model one tool by default: `ipython`, a persistent Python REPL. The agent reads files, writes files and runs shell commands through that kernel — `bash('cmd')` from inside Python — rather than through separate file and shell tools. `bash` and `edit` tool definitions do ship, but they are opt-in rather than part of the default tool set. Two consequences run through everything below.++**A cell is recorded as a command, not as an anonymous tool call.** The code goes into `command.command`, where the command-scoped rules can read it, and is marked as Python in `raw` so nobody mistakes it for a shell line. `import os; os.system("rm -rf /")` is a shell command wearing a Python hat, and a log that filed it under `tool.completed` would hide essentially every action the agent took. This is the same reading Oh My Pi's operator `$` code gets.++**The kernel's own file writes become file events.** Prime Agent streams a diff display for each file its kernel helpers rewrite, so one cell that edits three files produces three `file.modified` events, each carrying the unified patch and joined back to the cell by `gen_ai.tool.call.id`.++## Prerequisites++Before enabling Prime Agent telemetry, make sure:++- Prime Agent is installed and available as the `prime-agent` executable, or has a local state directory at `~/.prime/agent`.+- `beacon endpoint install` has run so shared endpoint config and runtime log paths exist.+- Prime Agent is restarted after install or removal so new sessions load the updated extension.++## Collection path++Asymptote's managed Prime Agent extension is a single TypeScript file at one of two auto-discovered extension locations:++| Level | Extension path |+|-------|----------------|+| User | `~/.prime/agent/extensions/beacon.ts` |+| Project | `./.prime/agent/extensions/beacon.ts` |++User level is the default, because it follows the operator rather than one checkout. `beacon endpoint discover` reports on the user path only, so a project-level extension does not appear in discovery output.<Warning>-**Partial support.** Harness identity ships today; collection does not. Asymptote recognizes Prime Agent as its own runtime and resolves every spelling to one canonical harness name, but there is no managed extension, no installer, and no discovery probe yet, so `beacon` collects no Prime Agent telemetry. There is nothing to install for this runtime at present.+The project path keeps the `agent` segment. Prime Agent's config directory name is the two-segment literal `.prime/agent`, and it joins that whole string under the working directory as well as under the home directory — where [Pi](/runtimes/pi) uses `.pi/extensions` and [Oh My Pi](/runtimes/oh-my-pi) uses `.omp/extensions` at project scope. A file written to `./.prime/extensions/` is never loaded.</Warning>-## What ships today+`PRIME_AGENT_CODING_AGENT_DIR` replaces the user-level agent directory outright, and Asymptote honors it — including a leading `~`, which the runtime expands before use. It does not move the project path, because Prime Agent does not consult it there. Asymptote deliberately ignores `PI_CODING_AGENT_DIR`: that is the variable the same upstream code produces for Pi and Oh My Pi, and reading it here would move this install whenever you had set it for a different product.++Asymptote identifies its own extension file by the marker `beacon-managed-prime-extension:v1`. The version suffix is part of the contract with the extension source: it is what lets a repair recognize a stale file instead of leaving it in place. A `beacon.ts` without the marker belongs to somebody else, so install will not overwrite it and discovery does not report it as Asymptote telemetry. The marker is distinct from Pi's and Oh My Pi's, so a file found at any of the three paths is attributed to the runtime that actually loads it.++Prime Agent has no OpenTelemetry export for Asymptote to configure, so there is no OTLP path for this runtime.++## Discovery and status++Asymptote detects Prime Agent through the `prime-agent` executable, and treats the `~/.prime/agent` state directory as an additional signal. Prime Agent installed through npm, or through its own installer into `~/.local/share/prime-agent`, is often missing from the `PATH` the endpoint process inherited, because a shell alias, a version manager, or a per-project install can all hide it while the state directory is still present. The Pi, Oh My Pi, OpenCode, Cursor, and Hermes probes use the same fallback.++The bare name `prime` is deliberately not probed for. It is an ordinary word another binary or an internal script could plausibly claim, and a false positive reports a runtime the machine does not have.++```bash title="Show Prime Agent discovery state"+beacon endpoint discover --all --json+```++Prime Agent reports as the `prime_agent` harness with capability `plugin`:++| Telemetry status | Meaning |+|------------------|---------|+| `missing` | No extension file at the user-level managed path |+| `disabled` | A `beacon.ts` exists but carries no Asymptote marker, so it is somebody else's extension sharing the filename |+| `enabled` | Asymptote's managed extension is in place |++An unmarked extension file reports `disabled` rather than `enabled`, because reporting it as enabled would show the runtime as covered while no events arrive.++## Install or configuration support++`beacon endpoint install` prepares shared endpoint config and runtime log paths. The extension is installed separately, because Prime Agent loads it from the user's own profile rather than from a machine-wide location:++```bash+beacon endpoint hooks install --harness prime # user level (default)+beacon endpoint hooks install --harness prime --level project+beacon endpoint hooks status --harness prime+beacon endpoint hooks uninstall --harness prime+```++`prime`, `prime-agent`, `prime_agent`, and `primeagent` all resolve to this runtime. Prime Intellect's model names are deliberately not accepted, so nobody can ask to install an extension for a model.++Install writes one file and refuses to touch a `beacon.ts` it did not write, so an extension of your own that happens to share the filename is left alone and the install fails loudly rather than replacing it. Uninstall removes only a file carrying this runtime's marker.++`status` reports `installed=false` when the extension exists but points at a hook binary that is no longer there, which happens after a Beacon uninstall, a partly applied update, or a home directory restored onto a different machine. In each case Prime Agent loads an extension that spawns nothing.++## Telemetry coverage| Area | Support ||------|---------|+| Runtime discovery | Supported through executable and `~/.prime/agent` detection, managed extension path, and telemetry status || Harness attribution | Supported. `prime`, `prime_agent`, `prime-agent`, `primeagent`, `prime_cli`, `prime-cli`, `prime_intellect`, and `prime-intellect` all normalize to `prime_agent` |-| Collection method | Defined. The `prime` platform is registered as a plugin-shaped integration, so any Prime Agent event carries `harness.collection_method=plugin` rather than defaulting to `hook` |-| Managed extension | Not shipped |-| Discovery and telemetry status | Not shipped. `beacon endpoint discover` does not probe for Prime Agent |-| Install, status, uninstall, repair | Not shipped. `beacon endpoint hooks install --harness prime` is not a supported target |-| Runtime event collection | Not shipped. No prompt, tool, command, file, MCP, reasoning, or token telemetry is collected |+| Extension install, status, uninstall, and repair | Supported |+| Session lifecycle | Supported. `session.started` and `session.ended`, carrying why the session started or stopped — a fork and a resume both produce a session with history behind it |+| Prompts | Supported. `prompt.submitted`, with whether the input was typed, delivered over RPC, or injected by another extension |+| Tool use | Supported. `tool.invoked` before execution, then `tool.completed` or `tool.failed` |+| Commands | Supported. `command.executed` for each `ipython` cell, for the optional `bash` tool, and for commands you run with the `!` prefix, which are marked as operator-initiated. A cell's result carries its captured output, the runtime's own duration, and its status |+| File activity | Supported. `file.modified` per file a kernel cell rewrote, with the unified patch; plus `file.modified` for the optional `edit` tool, carrying the unified diff it reports |+| Agent reasoning | Supported. `agent.reasoning` from an assistant message's thinking parts, in the OTel GenAI reasoning-part shape |+| Token usage and cost | Supported. `token.usage` normalized into `gen_ai.usage`, including cache and reasoning tokens and runtime-reported cost |+| Approval decisions | Not available. Prime Agent exposes no operator approval decision to observe. See [Known gaps](#known-gaps) |+| MCP activity | Not separately attributed. Prime Agent does not expose MCP as agent tools. See [Known gaps](#known-gaps) |+| Local JSONL and dashboard | Supported |+| MDM deployment | Supported for the endpoint agent. The Prime Agent extension installs separately in the logged-in user's context |++Harness names are matched against a closed set of spellings rather than by substring. `prime` is an ordinary English word that appears in model ids, file paths, and vendor names, so a substring rule would report any event whose harness attribute merely contained it as a Prime Agent session. Both the hook spelling (`--platform prime`) and the runtime's own name (`prime-agent`) are pinned, so one session cannot be recorded under two names.++## Data handling++Prime Agent content is handled like every other runtime. Prompts, cell code, command output, tool arguments, paths, diffs, and reasoning text are retained in local or customer-controlled logs, with local secret redaction and per-string limits applied before writing, and a hash and byte count on each content-bearing event. Events over the 64 KiB limit drop raw and retained content, preserve stable metadata, and set `field_truncated`.-## Why the harness name ships first+The extension itself sends nothing over the network. It spawns the local `beacon-hooks` binary with a fixed argv and writes the event to its stdin. A send that has not completed in two seconds is abandoned so Beacon cannot stall Prime Agent's agent loop, and a failure to spawn costs the event rather than the run.-`harness.name` is a release contract: dashboards, SIEM queries, and the rule pack group by it, so the name has to be pinned before any events are written under it. Two decisions are already fixed and will not change when collection lands.+## Known gaps-**Prime Agent is not Pi.** Recording its sessions as `pi_cli` would merge two separately installed products' activity under one name in every query that groups by harness — the one thing a security log must not do to two different runtimes on the same machine. It gets its own canonical name, as Oh My Pi does, for the same reason.+- **No approval telemetry.** Prime Agent's `tool_call` event lets an extension block a call, but that is an extension deciding rather than an operator being asked. It exposes no operator approval decision through the extension API, so Beacon records these as tool activity and writes no approval events. [Pi](/runtimes/pi) and [Cline](/cli/supported-runtimes-cline) work the same way for the same reason; [Oh My Pi](/runtimes/oh-my-pi) is the fork that does report real ones. Detections in `rules/approval-abuse/` do not fire on Prime Agent activity.+- **MCP calls are not separately attributed.** Consistent with its single-tool design, Prime Agent does not expose MCP servers as agent tools: each integration is a Python skill package the model imports and calls from inside the kernel. So an MCP call arrives as part of a cell's code in `command.command` rather than as an `mcp.tool_invoked` event with a server and tool name, and the two questions MCP telemetry usually answers — which server did this agent reach, and what did it call there — have no dedicated field to answer them here. This is a property of the runtime rather than a gap Beacon can close from its side.+- **No per-cell exit code.** A Python cell does not have one. The runtime reports a `status` of `ok`, `error`, or `aborted`, which Beacon records verbatim; deriving a `0`/`1` from it would put a shell's vocabulary on something that is not a shell. An interrupted cell is recorded as aborted rather than failed, so a Ctrl+C does not read as an agent error.+- **No enforcement.** As with every other runtime, enforcement stays behind the optional, off-by-default policy provider seam (`BEACON_POLICY_PROVIDER`), which is not wired to Prime Agent. Its blocking `tool_call` handler makes it a viable target for that seam later.+- **Streaming events are not collected.** The extension subscribes to seven of Prime Agent's event types and ignores the rest — provider request and response internals, streaming message updates, compaction, refinement and tree-navigation signals, and TUI plumbing. Assistant output is recorded once when a message finalizes rather than token by token, so Beacon stays out of the streaming path.+- **`.agents` and other hosts.** Prime Agent's extension directory is its own (`.prime/agent/extensions`), not a shared one, so unlike [goose](/runtimes/goose) there is no ambiguity about which runtime ran the extension.-**Matching is by equality against a closed set, not by substring.** "prime" is an ordinary English word that appears in model ids, file paths, and vendor names, so a substring rule would report any event whose harness attribute merely contained it as a Prime Agent session. Both the hook spelling (`--platform prime`) and the runtime's own name (`prime-agent`) are pinned, so one session cannot be recorded under two names.+## Deployment notes-## What collection will look like+The extension is loaded when Prime Agent starts, so an install taken while it is running takes effect on the next launch.-Prime Agent's observation surface is its extension API, the same one Pi and Oh My Pi expose, so support will follow the same shape those runtimes use: one Asymptote-owned TypeScript extension file, installed at user or project level, forwarding runtime events to the local `beacon-hooks` binary. That is why the platform is already registered as `plugin` rather than left to the `hook` default — a plugin platform reported as `hook` overstates vendor support.+Confirm discovery sees the runtime, then generate one Prime Agent event and check the log:-Two things will not change with it. Asymptote will not synthesize approval decisions from a blocking tool handler, matching the [Pi](/runtimes/pi) and [Cline](/runtimes/cline) posture, and enforcement will stay behind the optional, off-by-default policy provider seam (`BEACON_POLICY_PROVIDER`).+```bash+/opt/beacon/bin/beacon endpoint discover --all --json+/opt/beacon/bin/beacon endpoint hooks status --harness prime+/opt/beacon/bin/beacon endpoint doctor --system+grep '"name":"prime_agent"' ~/.beacon/endpoint/logs/runtime.jsonl | tail -3+```## Related<Columns cols={3}><Card title="Pi" icon="code" href="/runtimes/pi">- The upstream runtime Prime Agent forked, supported through a managed extension.+ The upstream runtime Prime Agent forked, supported through the same extension shape.</Card><Card title="Oh My Pi" icon="code" href="/runtimes/oh-my-pi">- Another pi-mono fork, and the shape Prime Agent support will follow.+ The other pi-mono fork, and the one that reports operator approval decisions.</Card><Card title="Supported agent harnesses" icon="list-check" href="/runtimes">Return to the runtime support overview.