Plugin boundary, Go implementation, Windows collectors, protocol design, documentation, and delivery setup.
Project case study
Alpha · Active developmentGo · Windows · JSON · gopsutil · Windows SCM
Focal Agent Inventory Plugin
A small, read-only system inventory process that gives Focal Agent structured Windows context without embedding platform-specific inspection code—or mutation authority—inside the AI host.
focal-agent-inventory.exeRead only
> echo {"method":"inventory.collect"} | focal-agent-inventory.exe
{
"success": true,
"data": {
"hostname": "DESKTOP-12345",
"os": "Microsoft Windows 11",
"arch": "amd64",
"cpu_count": 32
}
}
System summary, disks, network interfaces, running processes, and Windows services.
The core collectors and JSON dispatch path exist; broader platform support, protocol evolution, tests, and documentation remain future work.
The challenge
Give an AI agent system context without giving it a system shell.
Useful desktop assistance depends on facts: operating-system version, available memory, mounted storage, network adapters, active processes, and service state. Building each platform query directly into the host would couple Focal Agent to Windows APIs and expand the trusted codebase.
The inventory plugin moves that knowledge behind a process boundary. Focal Agent asks for one named operation, the Go executable gathers local facts through focused collectors, and the result returns as a language-neutral JSON envelope. No command mutates the machine.
System design
A language-independent plugin contract over ordinary process I/O.
The integration uses mechanisms every host language already understands: launch a child process, write JSON to standard input, and decode JSON from standard output. Platform code stays inside a disposable executable.
HostFocal AgentLaunch and supervise plugin
JSON requeststdin
Plugin boundaryGo dispatcherRoute one named method
Read-only callWindows
CollectorsSystem APIsFacts → JSON response
Run out of process
Collector failures and platform dependencies remain outside the Focal Agent runtime and can be upgraded independently.
Use JSON over stdin/stdout
The protocol does not require a language-specific SDK, network listener, service registration, or shared library ABI.
Keep every operation read only
The implemented dispatch table contains inventory queries—not process termination, service changes, disk writes, or shell execution.
Engineering decisions
Choose simple boundaries that can grow without hiding authority.
The alpha implementation is compact by design. The host sees named capabilities, collectors own platform details, and every invocation produces a uniform success or error response.
Go for a small native executable
- Constraint
- The plugin should start quickly, ship without a separate runtime, and call operating-system APIs predictably.
- Decision
- Compile collectors and protocol handling into one Go executable that Focal Agent can launch on demand.
- Tradeoff
- Platform-specific files and build targets require deliberate CI coverage, but distribution stays straightforward.
gopsutil for common inventory
- Constraint
- CPU, memory, host, disk, interface, and process data involve different native Windows mechanisms.
- Decision
- Use gopsutil to normalize those queries into Go values before producing the external JSON shape.
- Tradeoff
- The dependency simplifies collection but its raw platform values still require stable schema and error-policy decisions.
Use the native Windows service manager
- Constraint
- Service inventory needs authoritative state from the Windows Service Control Manager.
- Decision
- Connect through
x/sys/windows/svc/mgr, query each accessible service, and map native states to stable strings. - Tradeoff
- Inaccessible services are skipped, so callers receive usable partial inventory rather than an all-or-nothing failure.
One envelope for success and failure
- Constraint
- The host needs to distinguish collector output from protocol or platform failures without parsing human console text.
- Decision
- Return a JSON object containing
successplus either structureddataor anerrorstring. - Tradeoff
- The current envelope is intentionally small; typed error codes and protocol-version negotiation remain roadmap work.
Engineering deep dive
Each method reveals one bounded slice of the machine.
The dispatcher is an explicit allowlist. A request can arrive as a JSON object on stdin or as a method name argument, but both paths resolve to the same five cases. Unknown methods return a structured error rather than falling through to command execution.
Collectors handle partial access pragmatically. Disk entries whose usage cannot be queried, service handles that cannot be opened, and individual process fields that cannot be read do not prevent the rest of the inventory from being returned.
inventory.collect
Hostname, Windows platform and version, kernel, architecture, CPU model/count, and total/available memory.
disks.list · network.list
Mounted partitions and usage plus interface names, MAC addresses, assigned addresses, and flags.
processes.list
Process IDs, names, users, CPU percentage, and memory percentage where Windows permits inspection.
services.list
Service names and normalized stopped, pending, running, or paused states from the Windows SCM.
Repository evidence · August 2026
The implemented surface is compact and inspectable.
These figures come from the current public main branch. They distinguish shipped alpha behavior from the broader cross-platform roadmap described in the README.
Every accepted operation appears in one explicit dispatch switch.
Disk, network, process, and service collectors complement the complete system summary.
Native SCM states map to stable JSON strings, with an explicit unknown fallback.
Focal Agent can provide a JSON stdin envelope; developers can invoke a method directly by argument.
Where it stands
A useful Windows proof of the plugin model, deliberately labeled alpha.
The repository demonstrates the process and capability boundary with working Windows collectors. It is not yet a production-grade, cross-platform inventory subsystem, and the portfolio should make that distinction visible.
Implemented
- JSON request and response envelopes
- Explicit five-method dispatch allowlist
- Windows host, CPU, memory, and OS inventory
- Disk and network interface enumeration
- Process resource summaries
- Windows service names and lifecycle states
- Structured errors for decoding, collection, and unknown methods
Next hardening steps
- Automated tests for dispatch and collector schemas
- Windows-target CI and clean CodeQL configuration
- Populate the scaffolded architecture, protocol, security, and command documentation
- Protocol version negotiation and typed errors
- Field limits, timeouts, cancellation, and output-size budgets
- Linux and macOS collector implementations
- Installed software, GPU, update, sensor, and security inventory
Go deeper
Inspect the current plugin contract and collectors.
The public repository shows the alpha implementation directly; roadmap items are documented separately in the README.