Pulse/docs/AGENT_SUBSTRATE.md

Pulse agent substrate

A short, plain-English summary of what landed across the agent-paradigm arc on pulse/v6-release. Suitable as the basis for release notes, a GitHub announcement, or just a reminder to yourself in three weeks of what shape this work took.

What it is

Pulse v6 ships an agent-paradigm substrate so external agents (Claude Desktop, Claude Code, OpenCode, other MCP clients, plain HTTP consumers) can drive Pulse with the same context an in-process Patrol or Assistant has. The substrate has four axes:

Discovery. A canonical manifest at /api/agent/capabilities lists every agent-consumable capability with its name, description, HTTP method and path, required auth scope, response shape, stable error codes, and the deduplicated requiredScopes summary for the current full surface. It also carries the Pulse Intelligence Core, Patrol, Assistant, and MCP surface contract, including which affordances each supported operator surface exposes. The manifest is unauthenticated so an agent without a token can introspect Pulse before asking for one.

Depth. /api/agent/resource-context/{id} returns the situated picture of one resource in a single read: identity, operator-set state, active findings, pending approvals, recent actions including refused dispatches and verification probe outcomes. Stable token prefixes (plan_drift:, resource_remediation_locked:) reach the wire verbatim so agents branch on codes, not human text.

Breadth. /api/agent/fleet-context returns a thin per-resource rollup across the whole org: identity, operator flags, per-severity finding counts, pending-approval count. One read for "where do I focus?", with the per-resource bundle for follow-up depth.

Write. Two write surfaces. The operator-state intent loop (/api/resources/{id}/operator-state) lets an agent record per-resource commitments (intentionally offline, never auto-remediate, maintenance window, criticality). The action governance loop (/api/actions/plan, /api/actions/{id}/decision, /api/actions/{id}/execute) lets an agent plan, approve, and execute capability invocations against a resource through the canonical audit store. The server populates attribution so client values cannot spoof who-did-it. Validation failures emit the operator_state_invalid and invalid_action_request stable 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 agents branch on the conflict rather than retrying blindly.

Push. /api/agent/events is an SSE stream that fires finding.created, approval.pending, and action.completed events as state changes. Each event is a small fixed-shape payload with enough context for an agent to decide whether to follow up. Refused dispatches preserve their stable error tokens; successful dispatches carry a verification block so agents close the certainty loop without polling the audit endpoint.

What ships consuming it

Three first-party consumers are built on the same manifest:

• Settings -> API Access -> Agent integrations is the in-app operator surface. It fetches /api/agent/capabilities from the running instance, lists the declared capabilities by category, shows the manifest-owned surface contract and affordance badges, shows each capability's method, path, scope, and stable error codes, and generates client-ready pulse-mcp config snippets from the manifest-owned MCP adapter setup contract: server name, command, base URL flag, token environment variable, and the supported client config families. The panel fills in the current Pulse URL for OpenCode's native opencode.json / mcp shape and the common mcpServers shape for Claude-style clients. Tokens are still minted in API Access, so the same settings tab covers "what agents can do" and "which token unlocks it."

• cmd/agent-probe is a small Go binary that walks the discovery, triage, depth, push flow against a running Pulse instance. Useful as a smoke test or worked example for someone building their own integration.

• cmd/pulse-mcp is the MCP server adapter. Wire it into any MCP client that can launch a local server; the README at cmd/pulse-mcp/README.md includes generated setup plus OpenCode, Claude Desktop, and Claude Code examples from the same adapter contract, and the in-app Agent integrations panel shows both OpenCode's native opencode.json shape and the common mcpServers block. The adapter projects each manifest capability into one MCP tool with auto-derived input schema; adding capabilities to Pulse extends the MCP surface without changes in the adapter. Run with --emit-notifications to also translate Pulse's SSE events (finding.created, approval.pending, action.completed) into JSON-RPC notifications on the stdio channel so autonomous MCP-bound agents can react to push events without holding a separate HTTP connection.

pulse-mcp also has a published distribution path: the one-line installers (install-mcp.sh and install-mcp.ps1) download the matching binary from the latest Pulse GitHub Release and verify the release checksum. Building from source remains available for local development.

What it does not do yet

• Real-world consumer feedback. The substrate ships with the in-app Agent integrations panel, two reference adapters (HTTP and MCP), release installers, and end-to-end contract tests, but no external integration has been load-bearing on it yet. The next meaningful work item is whatever friction first usage surfaces, not more substrate plumbing.

• macOS notarization and package-manager polish. The installer verifies release checksums, but the first launch of the unsigned macOS binary can still show a Gatekeeper warning. Homebrew or other package-manager distribution can sit on top of the release binary path when usage signal warrants the maintenance.

Provable claims

• Manifest is honest. A contract pin (TestContract_AgentSurfaceErrorCodesMatchManifestDeclarations) parses every writeJSONError call from agent-surface handlers and every ErrorCodes declaration from the manifest, asserting symmetry both directions. Drift either way fails the test.

• The substrate composes. Two paired end-to-end tests in internal/api/agent_substrate_e2e_test.go boot the full router stack and walk discovery, triage, depth, and the operator-state write loop through the actual HTTP boundary. They are the substantive proof that the four axes work as one.

• Discovery is unauthenticated. Pinned by TestContract_AgentCapabilitiesManifestIsPublic after a slice 47 fix added the path to publicPaths. Slice 40 had it 401'ing despite the docs.

• Stable error envelope is two-layer. Capability-specific codes (resource_not_found, operator_state_not_set, operator_state_invalid) are declared per-capability in the manifest. Cross-cutting codes (invalid_org, org_suspended, access_denied) come from the auth and multi-tenant middleware and apply to every authenticated endpoint. Documented in api-contracts.md; a contract test enforces no drift.

Where to read more

• Full contract: docs/release-control/v6/internal/subsystems/api-contracts.md, agent-surface paragraphs in the ## Current State section.
• Implementation: internal/api/agent_*.go and internal/api/resources_operator_state.go.
• In-app setup surface: frontend-modern/src/components/Settings/AgentIntegrationsPanel.tsx.
• MCP adapter: cmd/pulse-mcp/ (with README).
• MCP installers: scripts/install-mcp.sh and scripts/install-mcp.ps1.
• HTTP worked example: cmd/agent-probe/.
• Subsystem dependencies: relevant paragraphs in agent-lifecycle.md, performance-and-scalability.md, and storage-recovery.md under docs/release-control/v6/internal/subsystems/.