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.
Go aialertsdashboarddockerdocker-monitoringgohomelabinfrastructure-monitoringkubernetesmonitoringmspproxmoxproxmox-backup-serverproxmox-mail-gatewayproxmox-veself-hostedtruenastypescriptvspherewebhooks
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.mdindex 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 tokenPulse 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 identicalcontent 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 surfacesserver-initiated notifications. Enable it when wiring an autonomousagent 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 isbehind 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/responseshaped). 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 notesdiff --git a/docs/AGENT_SUBSTRATE.md b/docs/AGENT_SUBSTRATE.mdindex 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, andplain 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-severityfinding counts, and pending-approval count. It answers "where do I focus" inone 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 suchas intentionally offline, never auto-remediate, maintenance window, andcriticality. 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 onthe 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 orinvalid. 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 anagent-surface handler can emit is declared in the manifest, and every codethe 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 withoutcredentials 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-statewrite 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 otherpackage-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 morediff --git a/frontend-modern/public/docs/AGENT_SUBSTRATE.md b/frontend-modern/public/docs/AGENT_SUBSTRATE.mdindex 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, andplain 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-severityfinding counts, and pending-approval count. It answers "where do I focus" inone 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 suchas intentionally offline, never auto-remediate, maintenance window, andcriticality. 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 onthe 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 orinvalid. 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 anagent-surface handler can emit is declared in the manifest, and every codethe 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 withoutcredentials 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-statewrite 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 otherpackage-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 morediff --git a/frontend-modern/src/features/docs/__tests__/externalAgentGuide.test.ts b/frontend-modern/src/features/docs/__tests__/externalAgentGuide.test.tsnew file mode 100644index 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.pynew file mode 100644index 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()