TRC-1005 - Local Stdio JSON-RPC Task Brokering

Living Document Notice
Published 2026-09-17. The evolving architecture, revisions, and connected notes for this dispatch live in the Stax Digital Garden.

Local Stdio JSON-RPC Task Brokering

Summary

Integrating task tracking with editors, terminal status bars, and automated scripts should never require background HTTP daemons or listening ports. Trice communicates with the desktop ecosystem via standard I/O JSON-RPC 2.0 mediated by Harbormaster.

Zero-Port Desktop Integration

Desktop productivity plugins often spawn long-running Node.js or Python daemons listening on local loopback ports (http://localhost:4242). This architectural pattern consumes memory, leaks socket handles, and presents an attack surface for malicious browser scripts.

Trice implements the Knowledge Provider Protocol (KPP) standard: all inter-process queries and mutations flow strictly across standard input (stdin) and standard output (stdout) pipes managed by Harbormaster.

+-------------------------------------------------------------+
|                Trice Stdio JSON-RPC Architecture            |
|                                                             |
|   +-----------------------+       +-----------------------+ |
|   | Editor / CLI Client   | ----> | Stdin: JSON-RPC Call  | |
|   +-----------------------+       +-----------------------+ |
|                                               │             |
|                                               v             |
|   +-----------------------+       +-----------------------+ |
|   | Trice KPP Adapter     | <---- | trice.transition_state| |
|   | (Subprocess on Demand)| ----> | Stdout: JSON Response | |
|   +-----------------------+       +-----------------------+ |
+-------------------------------------------------------------+

RPC Method Catalog

Trice exposes five core methods defined in the fleet RPC registry:

Method	Parameters	Return Structure	Action
trice.list_active	{"horizon": str}	Array of active tasks	Retrieves actionable tasks
trice.get_task	{"id": UUID}	Full task document	Fetches single task record
trice.transition_state	{"id": UUID, "to": str}	Updated task payload	Mutates task state gate
trice.query_blockers	{"id": UUID}	Array of blocking tasks	Evaluates dependency DAG
trice.create_task	Task Frontmatter Payload	{"id": UUID, "path": str}	Scaffolds new task file

Example Wire Transaction

A terminal status bar querying the current focus task issues a call over stdin:

{
  "jsonrpc": "2.0",
  "id": "bar-001",
  "method": "trice.list_active",
  "params": {
    "limit": 1,
    "state": "active"
  }
}

Trice reads the local vault index and responds instantly over stdout:

{
  "jsonrpc": "2.0",
  "id": "bar-001",
  "result": {
    "count": 1,
    "tasks": [
      {
        "id": "0191fa30-3001-7000-8000-000000000001",
        "title": "TRC-1001: Implement Columnar WAL Ring Buffer",
        "priority": "p1",
        "time_remaining_mins": 90
      }
    ]
  }
}

Resilience and Subprocess Lifecycle

When the editor closes or the terminal command terminates, the Trice child process exits cleanly. Zero persistent background processes remain running, guaranteeing zero battery drain on mobile hardware.

---

• Directus Target: trice
• Garden Source Reference: MOC - Bosun PKM Tools, MOC - Fleet Operations
• Garden Source Reference: [TRC-1005 - Local Stdio JSON-RPC Task Brokering](TRC-1005 - Local Stdio JSON-RPC Task Brokering)