Skip to content

armgit / Pulse

Public Imported from GitHub
0

Real-time monitoring dashboard for Proxmox VE, PBS, Docker, Kubernetes, TrueNAS and vSphere. Self-hosted, with alerts for failed backups, full disks, unhealthy containers and offline nodes.

Keep external-agent setup read-only and outcomes evidence-bound

pulse-triage[bot]0615b692ed6f
diff --git a/cmd/pulse-mcp/README.md b/cmd/pulse-mcp/README.md
index 256b3f49f4..a6f81ceb5a 100644
--- a/cmd/pulse-mcp/README.md
+++ b/cmd/pulse-mcp/README.md
@@ -104,22 +104,43 @@ Use any of the install paths above. The rest of this guide assumes
### 2. Mint an API token
Pulse fetches the live capabilities manifest first, and every tool
-description includes its required auth scope. For a read-only external
-agent, start with `monitoring:read`. For the full published Pulse
-Intelligence surface, mint a token with the current manifest scopes:
+description includes its required auth scope. Start with a dedicated, suitably
+expiring `monitoring:read` token, retaining its organisation/resource
+restrictions. The whole-surface scope union below is **not a recommended default
+or the minimum for read-only use**:
<!-- pulse-mcp-scope-list:start -->
`monitoring:read`, `monitoring:write`, `settings:read`, `settings:write`, `ai:execute`, `actions:plan`, `actions:approve`, and `actions:execute`
<!-- pulse-mcp-scope-list:end -->
-You can also mint narrower tokens for specific workflows. For example,
-omit `settings:write` if the client should not add or edit monitored
-infrastructure sources, and omit `ai:execute` if it should not review
-Patrol findings or plan, approve, or execute governed actions. Mint the
-token in **Settings →
-Security → API Tokens**.
+Grant additional scopes only for the specific workflow you intend to delegate,
+not to make every tool callable or an all-scope readiness indicator pass.
+`monitoring:write` can change operator state without the action-plan approval
+loop, and `settings:write` can change infrastructure configuration. Planning,
+approval and execution have separate action scopes; the legacy `ai:execute`
+scope also permits those stages. Omitting it is not a control boundary if you
+still grant `actions:approve` or `actions:execute`. A scope alone does not bypass
+actor binding, permissions, separation of duties, step-up or live readiness.
+Mint the token in **Settings → API Access** and follow the
+[read-only connection and action boundaries](../../docs/AGENT_SUBSTRATE.md#connect-without-granting-control).
+A tool listing is not permission to call every listed tool.
### 3. Wire it into your client
+**The generated snippets below contain placeholders, not secret storage.** Keep
+real tokens in your client's private, user-local configuration or supported
+secret store, outside shared projects and repositories. Do not put a real token
+in a project-shared `.mcp.json` or `opencode.json`, command argument, URL or
+transcript. Do not export a token through a shell command containing its value.
+The adapter reads its environment; the client process and local administrators
+can still read that environment. Use only a client and model provider permitted
+to receive the returned infrastructure context, findings and action output.
+
+`http://localhost:7655` applies only when the client runs on the Pulse host.
+Otherwise use your existing verified HTTPS origin and preserve the proxy's
+access policy. Do not expose the backend or disable certificate verification to
+make a desktop client connect. Revoke an unused or exposed token in **API
+Access**; deleting the client configuration alone does not revoke it.
+
<!-- pulse-mcp-client-config:start -->
Most MCP clients need the same manifest-owned runtime facts: server name `pulse`, command `pulse-mcp`, base URL flag `--base-url`, default URL `http://localhost:7655`, and token environment variable `PULSE_API_TOKEN`.
The generated examples below cover the currently declared config families: `OpenCode`, `Claude-style clients`, and `custom MCP clients`.
@@ -183,8 +204,9 @@ Use command `pulse-mcp`, pass `--base-url http://localhost:7655`, set `PULSE_API
| `--token-env` | `PULSE_API_TOKEN` | Env var holding the API token |
| `--emit-notifications` | `false` | Translate Pulse SSE events into JSON-RPC notifications on stdout |
-The token is always read from an environment variable, never a flag, so
-it does not appear in process listings.
+The token is read from an environment variable, never a token flag, keeping it
+out of command arguments. This does not make the environment or the client's
+saved configuration inaccessible to local administrators.
### About `--emit-notifications`
@@ -203,6 +225,14 @@ agent that already knows the substrate's wire shape sees identical
content to what an HTTP SSE consumer would. Transport plumbing
(`stream.connected`, `heartbeat`) is filtered out.
+`action.completed` also covers failed or refused terminal actions; its name
+alone is not a successful dispatch or recovery receipt. Inspect the result and
+verification evidence. Missing checks or `ran: false` do not establish the
+intended state. Even a verified check establishes only that postcondition at
+its recorded time. After a timeout or lost response, a change may already have
+happened: retain the action identity and inspect existing context/history rather
+than executing again. See [outcome interpretation](../../docs/AGENT_SUBSTRATE.md#read-action-outcomes-without-repeating-them).
+
It is off by default because not every MCP client surfaces
server-initiated notifications. Enable it when wiring an autonomous
agent that processes the JSON-RPC stream programmatically. Claude
@@ -354,23 +384,29 @@ make sure your client's `env` block (or shell environment) sets
**"manifest GET returned 401" on startup.**
Discovery is supposed to be unauthenticated. If your Pulse instance is
behind a reverse proxy that adds auth in front of the public paths,
-the proxy is gating the manifest endpoint. Make sure
-`/api/agent/capabilities` is reachable without a credential, the same
-way `/api/health` is.
+the proxy may be enforcing its own access policy. Public inside Pulse does not
+mean publicly reachable through your proxy. Check the existing authorised client
+path; do not exempt discovery or health from proxy authentication, expose a
+backend or copy a browser session cookie into the adapter to bypass that policy.
+The environment API token authenticates Pulse, not an unrelated proxy login.
**Tools work, but a write or action tool returns 403 access_denied.**
-Your token is missing that tool's required scope. Run `tools/list` and
-check the `required scope` line in the tool description. Operator-state
-writes need `monitoring:write`, provisioning tools need `settings:read`
-or `settings:write`, and Patrol finding plus governed action tools need
-`ai:execute`. Mint a narrower or broader token depending on which
-external-agent workflows you want to allow.
+Read the relevant error and live tool metadata privately. A 403 is not by
+itself proof of a missing scope: permissions, organisation/resource boundaries
+or action policy can also refuse it. If the client is meant to be read-only,
+leave it denied. Do not add `ai:execute`, approval or execution scopes merely to
+clear an error. For an intended write, check the specific scope and authority
+against [the separate action steps](../../docs/API.md#unified-action-planning);
+operator-state writes instead use `monitoring:write` and scope-only policy.
+Do not run a write, induce a finding or enable Debug as a connectivity test.
**Tools list is empty.**
The adapter filters `subscribe_events` out (it is not request/response
shaped). If literally nothing else shows up, your Pulse instance's
-manifest is empty, which is a Pulse-side bug; check
-`curl http://your-pulse/api/agent/capabilities` directly.
+manifest may be empty or the client may not have completed initialisation.
+Inspect the existing manifest and client error privately before diagnosing it.
+Use the [bounded private-response HTTP reads](../../docs/AGENT_SUBSTRATE.md#connect-without-granting-control),
+not credential-bearing logs, a public backend or an action as a probe.
## Implementation notes
diff --git a/docs/AGENT_SUBSTRATE.md b/docs/AGENT_SUBSTRATE.md
index c1014723ea..2c6b296143 100644
--- a/docs/AGENT_SUBSTRATE.md
+++ b/docs/AGENT_SUBSTRATE.md
@@ -6,8 +6,60 @@ Assistant have. Claude Desktop, Claude Code, OpenCode, other MCP clients, and
plain HTTP consumers can all drive it.
This page explains what those endpoints offer and what ships to help you
-connect to them. To generate a ready-made client configuration for your own
-instance, open Settings, then API Access, then Agent integrations.
+connect to them. Open **Settings → API Access → Agent integrations** to inspect
+your running instance's manifest and generate a client configuration.
+
+**Start read-only.** Connecting an external client is a separate trust decision:
+it can read infrastructure context and, with broader credentials, change
+monitoring or act on workloads. A tool listing or readiness badge is not an
+execution grant or proof of recovery. Use only a client and model provider
+permitted to receive the data in those responses.
+
+## Connect without granting control
+
+1. Inspect the manifest on the running server, not just this page. Its
+ `requiredScopes` is the union for the whole advertised surface, **not the
+ minimum for a read-only client**. Read each capability's `scope`, `actionMode`
+ and `approvalPolicy`; `scope_only` writes do not use the action approval loop.
+2. Create a dedicated, suitably expiring **`monitoring:read`** token for fleet
+ and resource context. Keep its organisation/resource restrictions. Do not
+ grant `monitoring:write`, `settings:write`, `ai:execute` or action scopes to
+ remove a denied-tool error or make an all-scope readiness indicator pass.
+ A client can list tools its token cannot call.
+3. Keep the credential in your client's private, user-local secret configuration
+ or supported secret store. `pulse-mcp` reads `PULSE_API_TOKEN` from its
+ environment, not a token flag. Do not enter a real token in a project-shared
+ `.mcp.json` or `opencode.json`, command argument, URL, repository or transcript.
+ Generated snippets contain placeholders; they do not secure the saved file.
+ Local administrators and the client process can still read its environment.
+4. Use loopback only when the client runs on the Pulse host. For another machine,
+ configure your existing verified **HTTPS** origin; keep certificate and
+ authentication checks enabled. A URL copied from the browser is not proof
+ that a desktop client can reach or trust it. Do not expose a backend port or
+ weaken a proxy boundary merely to connect a client.
+5. Read existing context for one intended resource and check the organisation,
+ canonical ID and observation time privately. Names and VMIDs can repeat
+ across installations. A successful response does not establish complete or
+ current provider collection. Keep findings, notes, command output and
+ infrastructure identities out of public diagnostic logs and reports.
+
+For a bounded HTTP check, prepare the private header file and define `pulse_api`
+**in the same Bash session** using [API authentication](API.md#-authentication).
+That helper saves responses to new owner-only files, ignores curl defaults and
+uses deadlines without redirects or retries. It is example code, not an installed
+Pulse command. Adapt its origin for remote HTTPS as that guide describes.
+
+```bash
+pulse_api GET /api/agent/capabilities
+pulse_api GET /api/agent/fleet-context
+```
+
+These are separate read-only checks, not an action walkthrough. Discovery is
+public; only the protected fleet read checks token access. Inspect each saved
+response privately. A 401/403, redirect or incomplete response is not an empty
+fleet. Do not run a workload action, change operator state, induce a finding or
+enable Debug just to test connectivity. Revoke an unused or exposed token in
+**API Access**; deleting a client configuration alone does not revoke it.
## What the endpoints offer
@@ -31,25 +83,59 @@ across the whole organisation, covering identity, operator flags, per-severity
finding counts, and pending-approval count. It answers "where do I focus" in
one read, with the per-resource endpoint available for follow-up depth.
-**Write.** There are two write surfaces. The operator-state intent loop
+**Write.** There are two different write surfaces. The operator-state intent loop
(`/api/resources/{id}/operator-state`) records per-resource commitments such
as intentionally offline, never auto-remediate, maintenance window, and
criticality. The action governance loop (`/api/actions/plan`,
`/api/actions/{id}/decision`, `/api/actions/{id}/execute`) plans, approves,
and executes capability invocations against a resource through the canonical
-audit store. Pulse populates attribution itself, so a client cannot spoof who
-did something. Validation failures emit the `operator_state_invalid` and
+audit store. Operator-state writes require `monitoring:write` and use
+`scope_only` policy, not action-plan approval. PUT replaces the whole saved
+record: read it first, preserve unrelated fields and coordinate other writers.
+Deleting it can remove maintenance and remediation protections as well as notes.
+See [operator-state semantics](API.md#resource-maintenance-and-operator-state).
+
+Action planning, approval and execution have separate scopes and permission
+checks; a scope does not bypass actor binding, separation of duties, step-up or
+live readiness. The legacy `ai:execute` scope also permits these action stages,
+so it is not a read-only substitute. Follow the
+[separate action steps](API.md#unified-action-planning), inspect the target,
+blast radius and `planHash`, and retain any refusal. Do not grant an external
+client all stages unless that is the authority you intend to delegate.
+Pulse derives attribution from the authenticated identity, not a caller-supplied
+actor. Validation failures emit the `operator_state_invalid` and
`invalid_action_request` codes. Lifecycle conflicts on the action loop emit
`action_not_pending`, `action_not_approved`, `action_already_executing`,
`action_execution_final`, and `action_dry_run_only`, so an agent can branch on
the specific conflict instead of retrying blindly.
**Push.** `/api/agent/events` is an SSE stream that fires `finding.created`,
-`approval.pending`, and `action.completed` as state changes. Each event is a
-small fixed-shape payload carrying enough context for an agent to decide
-whether to follow up. Refused dispatches keep their stable error tokens, and
-successful dispatches carry a verification block, so an agent can confirm an
-outcome without polling the audit endpoint.
+`approval.pending`, and `action.completed` as state changes. `action.completed`
+means a terminal action record, **including failed or refused actions**, not
+necessarily a successful dispatch. Inspect its result and verification evidence;
+the event name alone does not confirm the intended outcome. An idle stream is
+normal and is not a reason to create a finding or execute something.
+
+## Read action outcomes without repeating them
+
+Keep HTTP success, planning, approval, dispatch and post-action verification
+separate. An allowed plan has not executed; an approval is not an execution
+receipt; a successful dispatch or command exit does not prove workload recovery.
+
+| Verification evidence | Meaning |
+| --- | --- |
+| `unknown`, absent evidence or legacy record | No established post-action check |
+| `unverified` or `ran: false` | The intended state was not established; for example, no usable check or an unreachable agent |
+| `failed` | A postcondition was checked and did not match |
+| `verified`, with a successful check that ran | That particular postcondition matched at its recorded time, not every application or filesystem health requirement |
+
+Where the response exposes `ran`, `success`, `ranAt` and `note`, read them
+together, not `success` alone. Review the existing resource context and, with
+the required licensed audit access, its action history. Retain the same action
+identity after a timeout or lost response: **a change may already have happened**.
+Do not resend execution, invent another request ID or repeat an action to obtain
+better evidence. Use the workload's established safe checks independently of
+Pulse; verification can be unavailable without proving that nothing ran.
## What ships to help you connect
@@ -76,16 +162,23 @@ outcome without polling the audit endpoint.
They refuse installation when any integrity evidence is unavailable or
invalid. Building from source stays available.
-- **`cmd/agent-probe`** is a small Go binary that walks the discovery,
- triage, depth, and push flow against a running instance. Use it as a smoke
- test, or as a worked example if you are building your own HTTP integration.
+- **`cmd/agent-probe`** is a worked source example for discovery, triage,
+ depth and push, not a production diagnostic tool. Its current credential input
+ is `--token`, which exposes the token in process arguments, and it prints
+ resource context and event bodies. **Do not use it with a real token or
+ production data.** Use an isolated synthetic fixture for development, or the
+ private-response HTTP checks above for operator reads. Its final summary and
+ an idle event window do not prove that an event was received or a workload
+ recovered.
-## Guarantees
+## Contracts and limits
- **The manifest matches the implementation.** Every error code an
agent-surface handler can emit is declared in the manifest, and every code
the manifest declares is one a handler can emit. Drift in either direction
- fails the build, so the manifest can be trusted as the contract.
+ is covered by source contract tests. Use the manifest served by the running
+ version; a test pass or a newer repository page does not update an installed
+ server or establish an external client's compatibility.
- **Discovery needs no token.** `/api/agent/capabilities` serves without
credentials by design. The capabilities it describes keep their own auth
@@ -100,7 +193,8 @@ outcome without polling the audit endpoint.
- **The surfaces compose.** Discovery, triage, depth, and the operator-state
write loop are exercised together through the real HTTP boundary on every
- build, rather than only in isolation.
+ build, rather than only in isolation. These fixture checks are not evidence
+ of ordinary installed use, complete provider collection or recovered workloads.
## Known rough edges
@@ -109,11 +203,12 @@ outcome without polling the audit endpoint.
warning because the binary is not notarised. Homebrew and other
package-manager distribution may follow.
-- **Limited field usage.** These endpoints ship with the in-app panel, two
- reference adapters, release installers, and end-to-end contract tests, but
- no external integration has been load-bearing on them yet. If something is
- awkward in practice, open an issue, because that feedback is what shapes
- what comes next.
+- **Field acceptance is separate.** The in-app panel, adapters and contract
+ fixtures do not establish every external client's compatibility, scale or
+ privacy behaviour. Report a consequential integration gap with the running
+ version, client type, capability name and relevant redacted error. Keep tokens,
+ client configuration, full responses and model transcripts private; do not
+ recreate an action or send production data just to make a report.
## Where to read more
diff --git a/frontend-modern/public/docs/AGENT_SUBSTRATE.md b/frontend-modern/public/docs/AGENT_SUBSTRATE.md
index c1014723ea..2c6b296143 100644
--- a/frontend-modern/public/docs/AGENT_SUBSTRATE.md
+++ b/frontend-modern/public/docs/AGENT_SUBSTRATE.md
@@ -6,8 +6,60 @@ Assistant have. Claude Desktop, Claude Code, OpenCode, other MCP clients, and
plain HTTP consumers can all drive it.
This page explains what those endpoints offer and what ships to help you
-connect to them. To generate a ready-made client configuration for your own
-instance, open Settings, then API Access, then Agent integrations.
+connect to them. Open **Settings → API Access → Agent integrations** to inspect
+your running instance's manifest and generate a client configuration.
+
+**Start read-only.** Connecting an external client is a separate trust decision:
+it can read infrastructure context and, with broader credentials, change
+monitoring or act on workloads. A tool listing or readiness badge is not an
+execution grant or proof of recovery. Use only a client and model provider
+permitted to receive the data in those responses.
+
+## Connect without granting control
+
+1. Inspect the manifest on the running server, not just this page. Its
+ `requiredScopes` is the union for the whole advertised surface, **not the
+ minimum for a read-only client**. Read each capability's `scope`, `actionMode`
+ and `approvalPolicy`; `scope_only` writes do not use the action approval loop.
+2. Create a dedicated, suitably expiring **`monitoring:read`** token for fleet
+ and resource context. Keep its organisation/resource restrictions. Do not
+ grant `monitoring:write`, `settings:write`, `ai:execute` or action scopes to
+ remove a denied-tool error or make an all-scope readiness indicator pass.
+ A client can list tools its token cannot call.
+3. Keep the credential in your client's private, user-local secret configuration
+ or supported secret store. `pulse-mcp` reads `PULSE_API_TOKEN` from its
+ environment, not a token flag. Do not enter a real token in a project-shared
+ `.mcp.json` or `opencode.json`, command argument, URL, repository or transcript.
+ Generated snippets contain placeholders; they do not secure the saved file.
+ Local administrators and the client process can still read its environment.
+4. Use loopback only when the client runs on the Pulse host. For another machine,
+ configure your existing verified **HTTPS** origin; keep certificate and
+ authentication checks enabled. A URL copied from the browser is not proof
+ that a desktop client can reach or trust it. Do not expose a backend port or
+ weaken a proxy boundary merely to connect a client.
+5. Read existing context for one intended resource and check the organisation,
+ canonical ID and observation time privately. Names and VMIDs can repeat
+ across installations. A successful response does not establish complete or
+ current provider collection. Keep findings, notes, command output and
+ infrastructure identities out of public diagnostic logs and reports.
+
+For a bounded HTTP check, prepare the private header file and define `pulse_api`
+**in the same Bash session** using [API authentication](API.md#-authentication).
+That helper saves responses to new owner-only files, ignores curl defaults and
+uses deadlines without redirects or retries. It is example code, not an installed
+Pulse command. Adapt its origin for remote HTTPS as that guide describes.
+
+```bash
+pulse_api GET /api/agent/capabilities
+pulse_api GET /api/agent/fleet-context
+```
+
+These are separate read-only checks, not an action walkthrough. Discovery is
+public; only the protected fleet read checks token access. Inspect each saved
+response privately. A 401/403, redirect or incomplete response is not an empty
+fleet. Do not run a workload action, change operator state, induce a finding or
+enable Debug just to test connectivity. Revoke an unused or exposed token in
+**API Access**; deleting a client configuration alone does not revoke it.
## What the endpoints offer
@@ -31,25 +83,59 @@ across the whole organisation, covering identity, operator flags, per-severity
finding counts, and pending-approval count. It answers "where do I focus" in
one read, with the per-resource endpoint available for follow-up depth.
-**Write.** There are two write surfaces. The operator-state intent loop
+**Write.** There are two different write surfaces. The operator-state intent loop
(`/api/resources/{id}/operator-state`) records per-resource commitments such
as intentionally offline, never auto-remediate, maintenance window, and
criticality. The action governance loop (`/api/actions/plan`,
`/api/actions/{id}/decision`, `/api/actions/{id}/execute`) plans, approves,
and executes capability invocations against a resource through the canonical
-audit store. Pulse populates attribution itself, so a client cannot spoof who
-did something. Validation failures emit the `operator_state_invalid` and
+audit store. Operator-state writes require `monitoring:write` and use
+`scope_only` policy, not action-plan approval. PUT replaces the whole saved
+record: read it first, preserve unrelated fields and coordinate other writers.
+Deleting it can remove maintenance and remediation protections as well as notes.
+See [operator-state semantics](API.md#resource-maintenance-and-operator-state).
+
+Action planning, approval and execution have separate scopes and permission
+checks; a scope does not bypass actor binding, separation of duties, step-up or
+live readiness. The legacy `ai:execute` scope also permits these action stages,
+so it is not a read-only substitute. Follow the
+[separate action steps](API.md#unified-action-planning), inspect the target,
+blast radius and `planHash`, and retain any refusal. Do not grant an external
+client all stages unless that is the authority you intend to delegate.
+Pulse derives attribution from the authenticated identity, not a caller-supplied
+actor. Validation failures emit the `operator_state_invalid` and
`invalid_action_request` codes. Lifecycle conflicts on the action loop emit
`action_not_pending`, `action_not_approved`, `action_already_executing`,
`action_execution_final`, and `action_dry_run_only`, so an agent can branch on
the specific conflict instead of retrying blindly.
**Push.** `/api/agent/events` is an SSE stream that fires `finding.created`,
-`approval.pending`, and `action.completed` as state changes. Each event is a
-small fixed-shape payload carrying enough context for an agent to decide
-whether to follow up. Refused dispatches keep their stable error tokens, and
-successful dispatches carry a verification block, so an agent can confirm an
-outcome without polling the audit endpoint.
+`approval.pending`, and `action.completed` as state changes. `action.completed`
+means a terminal action record, **including failed or refused actions**, not
+necessarily a successful dispatch. Inspect its result and verification evidence;
+the event name alone does not confirm the intended outcome. An idle stream is
+normal and is not a reason to create a finding or execute something.
+
+## Read action outcomes without repeating them
+
+Keep HTTP success, planning, approval, dispatch and post-action verification
+separate. An allowed plan has not executed; an approval is not an execution
+receipt; a successful dispatch or command exit does not prove workload recovery.
+
+| Verification evidence | Meaning |
+| --- | --- |
+| `unknown`, absent evidence or legacy record | No established post-action check |
+| `unverified` or `ran: false` | The intended state was not established; for example, no usable check or an unreachable agent |
+| `failed` | A postcondition was checked and did not match |
+| `verified`, with a successful check that ran | That particular postcondition matched at its recorded time, not every application or filesystem health requirement |
+
+Where the response exposes `ran`, `success`, `ranAt` and `note`, read them
+together, not `success` alone. Review the existing resource context and, with
+the required licensed audit access, its action history. Retain the same action
+identity after a timeout or lost response: **a change may already have happened**.
+Do not resend execution, invent another request ID or repeat an action to obtain
+better evidence. Use the workload's established safe checks independently of
+Pulse; verification can be unavailable without proving that nothing ran.
## What ships to help you connect
@@ -76,16 +162,23 @@ outcome without polling the audit endpoint.
They refuse installation when any integrity evidence is unavailable or
invalid. Building from source stays available.
-- **`cmd/agent-probe`** is a small Go binary that walks the discovery,
- triage, depth, and push flow against a running instance. Use it as a smoke
- test, or as a worked example if you are building your own HTTP integration.
+- **`cmd/agent-probe`** is a worked source example for discovery, triage,
+ depth and push, not a production diagnostic tool. Its current credential input
+ is `--token`, which exposes the token in process arguments, and it prints
+ resource context and event bodies. **Do not use it with a real token or
+ production data.** Use an isolated synthetic fixture for development, or the
+ private-response HTTP checks above for operator reads. Its final summary and
+ an idle event window do not prove that an event was received or a workload
+ recovered.
-## Guarantees
+## Contracts and limits
- **The manifest matches the implementation.** Every error code an
agent-surface handler can emit is declared in the manifest, and every code
the manifest declares is one a handler can emit. Drift in either direction
- fails the build, so the manifest can be trusted as the contract.
+ is covered by source contract tests. Use the manifest served by the running
+ version; a test pass or a newer repository page does not update an installed
+ server or establish an external client's compatibility.
- **Discovery needs no token.** `/api/agent/capabilities` serves without
credentials by design. The capabilities it describes keep their own auth
@@ -100,7 +193,8 @@ outcome without polling the audit endpoint.
- **The surfaces compose.** Discovery, triage, depth, and the operator-state
write loop are exercised together through the real HTTP boundary on every
- build, rather than only in isolation.
+ build, rather than only in isolation. These fixture checks are not evidence
+ of ordinary installed use, complete provider collection or recovered workloads.
## Known rough edges
@@ -109,11 +203,12 @@ outcome without polling the audit endpoint.
warning because the binary is not notarised. Homebrew and other
package-manager distribution may follow.
-- **Limited field usage.** These endpoints ship with the in-app panel, two
- reference adapters, release installers, and end-to-end contract tests, but
- no external integration has been load-bearing on them yet. If something is
- awkward in practice, open an issue, because that feedback is what shapes
- what comes next.
+- **Field acceptance is separate.** The in-app panel, adapters and contract
+ fixtures do not establish every external client's compatibility, scale or
+ privacy behaviour. Report a consequential integration gap with the running
+ version, client type, capability name and relevant redacted error. Keep tokens,
+ client configuration, full responses and model transcripts private; do not
+ recreate an action or send production data just to make a report.
## Where to read more
diff --git a/frontend-modern/src/features/docs/__tests__/externalAgentGuide.test.ts b/frontend-modern/src/features/docs/__tests__/externalAgentGuide.test.ts
new file mode 100644
index 0000000000..9c95b01596
--- /dev/null
+++ b/frontend-modern/src/features/docs/__tests__/externalAgentGuide.test.ts
@@ -0,0 +1,63 @@
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { describe, expect, it } from 'vitest';
+import { renderDocMarkdown } from '../docMarkdown';
+
+const read = (file: string) => readFileSync(resolve(process.cwd(), '..', file), 'utf8');
+const article = (name: string) => {
+ const element = document.createElement('article');
+ element.innerHTML = renderDocMarkdown(read(`docs/${name}.md`), name);
+ return element;
+};
+const text = (element: Element) => element.textContent?.replace(/\s+/g, ' ').trim() ?? '';
+
+describe('external-agent operator guidance', () => {
+ it('puts read-only trust and private credentials before advertised controls', () => {
+ expect(read('frontend-modern/public/docs/AGENT_SUBSTRATE.md')).toBe(
+ read('docs/AGENT_SUBSTRATE.md'),
+ );
+ const guide = article('AGENT_SUBSTRATE');
+ const warning = [...guide.querySelectorAll('strong')].find((node) =>
+ text(node).includes('Start read-only'),
+ );
+ expect(warning).toBeDefined();
+ const setup = guide.querySelector('#connect-without-granting-control');
+ expect(setup?.nextElementSibling?.tagName).toBe('OL');
+ expect(setup?.nextElementSibling?.querySelectorAll('li')).toHaveLength(5);
+ expect(text(setup!.nextElementSibling!)).toContain('not the minimum for a read-only client');
+ expect(text(setup!.nextElementSibling!)).toContain('project-shared .mcp.json');
+ expect(text(guide)).toContain('only the protected fleet read checks token access');
+ expect([...guide.querySelectorAll('pre')].map((node) => text(node))).toEqual([
+ 'pulse_api GET /api/agent/capabilities pulse_api GET /api/agent/fleet-context',
+ ]);
+ });
+
+ it('shows terminal-event, partial-verification and legacy-probe limits', () => {
+ const guide = article('AGENT_SUBSTRATE');
+ const table = guide.querySelector('table');
+ expect(table?.querySelectorAll('tbody tr')).toHaveLength(4);
+ expect(text(table!)).toContain('unknown');
+ expect(text(table!)).toContain('ran: false');
+ expect(text(table!)).toContain('not every application or filesystem health requirement');
+ expect(text(guide)).toContain('including failed or refused actions');
+ expect(text(guide)).toContain('a change may already have happened');
+ expect(text(guide)).toContain('Do not resend execution, invent another request ID');
+ expect(text(guide)).toContain('Do not use it with a real token or production data');
+ expect(text(guide)).not.toContain('so an agent can confirm an outcome without polling');
+ });
+
+ it('navigates all API boundaries and the local outcome heading', () => {
+ const guide = article('AGENT_SUBSTRATE');
+ const api = article('API');
+ for (const fragment of [
+ '-authentication',
+ 'resource-maintenance-and-operator-state',
+ 'unified-action-planning',
+ ]) {
+ const link = guide.querySelector(`a[href="/docs/API#${fragment}"]`);
+ expect(link?.hasAttribute('data-doc-link')).toBe(true);
+ expect(api.querySelector(`[id="${fragment}"]`)).not.toBeNull();
+ }
+ expect(guide.querySelector('#read-action-outcomes-without-repeating-them')).not.toBeNull();
+ });
+});
diff --git a/scripts/tests/test_external_agent_docs.py b/scripts/tests/test_external_agent_docs.py
new file mode 100644
index 0000000000..3563ecbcc4
--- /dev/null
+++ b/scripts/tests/test_external_agent_docs.py
@@ -0,0 +1,127 @@
+#!/usr/bin/env python3
+"""Check safe operator entry points, not external-client or workload recovery.
+
+The copied HTTP recipes run only against synthetic guest-local fixtures.
+"""
+
+from pathlib import Path
+import re
+import subprocess
+import tempfile
+import unittest
+
+from test_api_auth_docs import (
+ ROOT, TEST_TOKEN, exercise_curl, private_recording_server, request_helper,
+)
+
+
+def guide():
+ return (ROOT / "docs/AGENT_SUBSTRATE.md").read_text(encoding="utf-8")
+
+
+def adapter_readme():
+ return (ROOT / "cmd/pulse-mcp/README.md").read_text(encoding="utf-8")
+
+
+def compact(value):
+ return " ".join(value.split())
+
+
+def requests():
+ blocks = re.findall(r"```bash\n(.*?)```", guide(), re.DOTALL)
+ return [line.strip() for block in blocks for line in block.splitlines() if line.strip()]
+
+
+class ExternalAgentDocsTest(unittest.TestCase):
+ def test_shipped_guide_matches_canonical(self):
+ self.assertEqual(guide(), (ROOT / "frontend-modern/public/docs/AGENT_SUBSTRATE.md").read_text())
+
+ def test_read_only_setup_does_not_grant_whole_surface_authority(self):
+ text = compact(guide())
+ self.assertLess(text.index("Start read-only"), text.index("## What the endpoints offer"))
+ for boundary in ("not the minimum for a read-only client", "monitoring:read",
+ "client can list tools its token cannot call", "scope_only",
+ "writes do not use the action approval loop", "organisation/resource restrictions",
+ "not a read-only substitute", "PUT replaces the whole saved record",
+ "preserve unrelated fields", "separation of duties", "live readiness"):
+ with self.subTest(boundary=boundary):
+ self.assertIn(boundary, text)
+
+ def test_credentials_data_and_proxy_access_stay_private(self):
+ for source in (guide(), adapter_readme()):
+ text = compact(source)
+ for boundary in ("project-shared", ".mcp.json", "opencode.json", "HTTPS",
+ "client process", "local administrators", "model provider",
+ "deleting", "does not revoke it"):
+ with self.subTest(boundary=boundary):
+ self.assertIn(boundary, text)
+ readme = compact(adapter_readme())
+ self.assertIn("not a recommended default", readme)
+ self.assertIn("do not exempt discovery or health from proxy authentication", readme)
+ self.assertIn("403 is not by itself proof of a missing scope", readme)
+ self.assertIn("leave it denied", readme)
+ self.assertNotIn("Make sure `/api/agent/capabilities` is reachable without a credential", readme)
+
+ def test_probe_is_not_a_real_credential_diagnostic(self):
+ text = compact(guide())
+ for boundary in ("not a production diagnostic tool", "--token", "process arguments",
+ "prints resource context and event bodies", "Do not use it with a real token",
+ "isolated synthetic fixture", "private-response HTTP checks",
+ "do not prove that an event was received"):
+ self.assertIn(boundary, text)
+ # Bind the warning to the unchanged reference-client behaviour, rather
+ # than claiming a safer credential input or redacted output exists.
+ source = (ROOT / "cmd/agent-probe/main.go").read_text()
+ self.assertIn('flag.String("token",', source)
+ self.assertIn('fmt.Println(" " + string(out))', source)
+
+ def test_terminal_events_and_partial_checks_do_not_claim_recovery(self):
+ text = compact(guide())
+ for boundary in ("including failed or refused actions", "not necessarily a successful dispatch",
+ "unknown", "unverified", "ran: false", "failed", "verified",
+ "ranAt", "particular postcondition", "recorded time",
+ "does not prove workload recovery", "a change may already have happened",
+ "Do not resend execution, invent another request ID", "independently of Pulse"):
+ with self.subTest(boundary=boundary):
+ self.assertIn(boundary, text)
+ self.assertNotIn("so an agent can confirm an outcome without polling", text)
+ self.assertIn("failed or refused terminal actions", compact(adapter_readme()))
+
+ def test_copied_checks_are_only_two_bounded_private_reads(self):
+ self.assertEqual(requests(), ["pulse_api GET /api/agent/capabilities",
+ "pulse_api GET /api/agent/fleet-context"])
+ text = compact(guide())
+ for boundary in ("same Bash session", "API.md#-authentication", "owner-only files",
+ "without redirects or retries", "not an installed Pulse command",
+ "only the protected fleet read checks token access", "not an empty fleet",
+ "Do not run a workload action, change operator state, induce a finding"):
+ self.assertIn(boundary, text)
+ for step in requests():
+ subprocess.run(["bash", "-n", "-c", request_helper() + "\n" + step],
+ check=True, capture_output=True)
+
+ def test_exact_copied_reads_keep_synthetic_credentials_and_responses_private(self):
+ for step in requests():
+ with self.subTest(step=step), tempfile.TemporaryDirectory() as temporary:
+ with private_recording_server() as (port, recorded):
+ result = exercise_curl(self, Path(temporary), "X-API-Token: " + TEST_TOKEN,
+ port, request_helper() + "\n" + step, private_response=True)
+ self.assertEqual(result.returncode, 0, result.stderr)
+ self.assertEqual([(r[0], r[2], r[3]) for r in recorded],
+ [(step.split()[2], "GET", b"")])
+
+ def test_denied_redirect_and_incomplete_reads_stop_without_mutation_or_retry(self):
+ for step in requests():
+ for status, partial in ((401, False), (403, False), (302, False), (200, True)):
+ with self.subTest(step=step, status=status, partial=partial):
+ with tempfile.TemporaryDirectory() as temporary:
+ with private_recording_server(status, partial) as (port, recorded):
+ result = exercise_curl(self, Path(temporary), "X-API-Token: " + TEST_TOKEN,
+ port, request_helper() + "\n" + step,
+ private_response=True)
+ self.assertNotEqual(result.returncode, 0)
+ self.assertEqual([(r[0], r[2]) for r in recorded], [(step.split()[2], "GET")])
+
+
+if __name__ == "__main__":
+ unittest.main()