Skip to content

feat(netwatch): Network/Connections agent (observe→graph→detect→consent-gated propose) - #41

Merged
mdheller merged 1 commit into
mainfrom
feat/network-connections-agent
Aug 3, 2026
Merged

feat(netwatch): Network/Connections agent (observe→graph→detect→consent-gated propose)#41
mdheller merged 1 commit into
mainfrom
feat/network-connections-agent

Conversation

@mdheller

@mdheller mdheller commented Aug 3, 2026

Copy link
Copy Markdown

Implements the one built-in agent the Agent-First Node Architecture was missing — recon (2026-08-02) confirmed the Network/Connections agent ABSENT across prophet-mesh / agent-registry / TurtleTerm / Noetica, corroborated by prophet-platform/docs/AGENT_OS_NODE_BINDING.md seam #3. Binds to existing anchors; does not rebuild.

turtle-netwatch (peer of turtle-watch / turtle-diagnose)

verb effect
snapshot portable connection capture — ss (Linux) / lsof (macOS/BSD)
observe emit agent.v1 Observation events to the netwatch sink
graph project into a System Graph subgraph (KnowledgeUpdate delta) for hellgraph AtomSpace — Process/Host/Port nodes, CONNECTS_TO edges
detect beaconing (low-variance periodic contact) + egress fan-out anomalies
propose build an Action (net.block/net.throttle) that is admitted-or-refused by the consent plane

The gate is real (the whole point)

A network mutation is an operate purpose in system-space. propose calls the real policy-fabric purpose_admissibility_gate:

  • engine present → ADMIT → routed to the Governor (guardrail-fabric) as awaiting-governor-approval, never auto-applied (needs --apply + an approval token);
  • engine absent / error → DENY fail-closed — a network mutation never proceeds ungated.

Every decision is a hash-sealed receipt. Proven both ways in tests + live (this mac: 57 real connections captured; real engine admits net.throttle, missing engine denies).

Ships as a runbook (user- and agent-executable)

runbooks/netwatch.yaml sequences the whole vertical as a turtle-runbook (turtle-runbook run netwatch) — each step a plain, inspectable command, safe to hand to an agent because every mutation is consent-gated + Governor-approved.

Also

  • schemas/agent/{observation,action,knowledge_update}.avsc — the agent.v1 contracts (net-new).
  • tests/test_turtle_netwatch.py — 7 tests, offline (synthetic fixtures).
  • turtle-netwatch added to all packaging bin lists (flatpak/rpm/arch/deb-stage/chocolatey).

Net-new per the corpus; closes the missing built-in agent. The System Graph OS-observer collectors are the genuinely new piece; everything else binds to shipped repos.

…ent-gated propose

The one built-in agent the Agent-First Node Architecture was missing (recon
2026-08-02 confirmed ABSENT; corroborated by prophet-platform
AGENT_OS_NODE_BINDING.md seam #3). Binds to existing anchors, does not rebuild.

assets/sourceos/bin/turtle-netwatch (peer of turtle-watch/turtle-diagnose):
- snapshot: portable connection capture (ss on Linux, lsof on macOS/BSD)
- observe:  emit agent.v1 Observation events to the netwatch sink
- graph:    project into a System Graph subgraph (KnowledgeUpdate delta) for
            hellgraph AtomSpace ingestion (Process/Host/Port nodes, CONNECTS_TO)
- detect:   beaconing (low-variance periodic contact) + egress fan-out
- propose:  build an Action (net.block/net.throttle) that is ADMITTED-OR-REFUSED
            by the consent plane (operate purpose, system-space) via the real
            policy-fabric purpose_admissibility_gate; admit -> routed to the
            Governor (guardrail-fabric), never auto-applied; deny -> refused
            fail-closed. Every decision is a hash-sealed receipt.

- schemas/agent/{observation,action,knowledge_update}.avsc  (agent.v1, net-new)
- runbooks/netwatch.yaml  — the whole vertical as a turtle-runbook a user OR
  agent can execute step by step
- tests/test_turtle_netwatch.py — 7 tests (graph, beaconing, fan-out, quiet,
  fail-closed consent gate, live snapshot); proven end-to-end: real engine ADMITS
  (awaiting-governor-approval), missing engine DENIES.
- packaging: turtle-netwatch added to flatpak/rpm/arch/deb-stage/chocolatey lists.
@mdheller
mdheller merged commit 56d8a43 into main Aug 3, 2026
6 of 13 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant