foreman/agent-watcher
1
0
Fork 0
Code Issues Pull requests 1 Projects Releases Packages Wiki Activity Actions
No description
4 commits 4 branches 0 tags 165 KiB
Find a file
bob-boat f9d81471c4 Collector milestone 2: source interface + drop-folder source 
source.Source is the contract every Collector input implements: Name +
Run(ctx, emit). Sources don't own state — they convert external events
into emit calls. Dispatcher routes.

internal/source/dropfolder: watches ~/Nyx/workspace/incoming/ for
*.json drop files. fsnotify-driven with periodic poll fallback (default
30s safety net for missed events). Each file:

1. Parsed against the spec §3.1.2 schema with DisallowUnknownFields.
2. Valid → emitted, then file deleted.
3. Invalid (missing fields, bad type/priority, unknown fields, garbage)
   → moved to .dead-letter/ with a sidecar .reason file for forensics.
4. Emit failure → file retained in place for retry (transient errors
   shouldn't be permanent dead-letters).

Also: initial-scan on Run() drains files that landed before the watcher
attached, catching up after a Collector restart.

14 tests in the package — schema validation table for all error cases,
initial-scan, live inotify drop, post-emit delete, dead-letter +
sidecar, emit-failure retention. Plus the 7 inbox tests still passing.

Pinned fsnotify v1.7.0 (Go 1.22 compatible; 1.10.x demanded toolchain
1.23 which isn't in apt yet). go.mod stays at 1.22 to match VPS.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-05-06 16:14:03 -04:00
docs/channels Add Channels reference docs snapshot for Layer 2 implementation 2026-05-06 16:04:32 -04:00
internal Collector milestone 2: source interface + drop-folder source 2026-05-06 16:14:03 -04:00
spec Initial: README, spec/agent-watcher.md v1 (signed off by Bob 2026-05-06), .gitignore 2026-05-06 14:36:45 -04:00
.gitignore Initial: README, spec/agent-watcher.md v1 (signed off by Bob 2026-05-06), .gitignore 2026-05-06 14:36:45 -04:00
go.mod Collector milestone 2: source interface + drop-folder source 2026-05-06 16:14:03 -04:00
go.sum Collector milestone 2: source interface + drop-folder source 2026-05-06 16:14:03 -04:00
README.md Initial: README, spec/agent-watcher.md v1 (signed off by Bob 2026-05-06), .gitignore 2026-05-06 14:36:45 -04:00

README.md

agent-watcher

Push-delivery layer for agent-ping. The "secondary nervous system" for Claude Code agents on this network.

agent-ping queues messages in inbox files; agent-watcher notices them (and other external events) and wakes the recipient agent without a human in the loop.

Two layers:

  • Collector — small Go daemon, systemd --user, always on, brain-blind. Converts external events (HTTP webhooks, drop-folder file arrivals) into ping inbox writes. Runs whether or not any agent is alive.
  • MCP Watcher — Claude Code MCP subprocess, declared in each agent's mcp.json. Watches the agent's inbox via inotify and surfaces events into the live session via Channels (research preview). Provides reply tools (ack, respond, mark_handled).

Filesystem is the queue. OpenBrain is not involved.

Spec

spec/agent-watcher.md. Read that for architecture, decisions, scope.

Status

v1 spec signed off by Bob (VPS) 2026-05-06. Implementation pending.

Install

Per CLAUDE.md rule #2, Angus runs the install commands — agents do not modify their own configuration. Install script will land alongside INSTALL.md once the binaries are built.