Add supervised logical agents and typed spawn_agent (#11) #30

Merged

lost-rob0t merged 20 commits from feature/issue-11-agent-supervision into main

2026-08-12 17:45:35 +00:00

lost-rob0t commented

2026-08-12 17:43:27 +00:00

(Migrated from github.com)

Closes #11.

Supervised logical-agent runtime

Replace the rlm_agent stub with a bounded actor-style runtime:

SWI engines hold logical agent state without a permanent OS thread per agent;
finite message queues implement mailboxes and explicit backpressure;
one bounded SWI thread pool per runtime executes trusted blocking worker work;
supervisor/child relationships are first-class;
child capabilities are narrowed through the existing capability algebra;
worker failures become structured agent failures and are observable by the parent;
parent cancellation recursively propagates to children and outstanding workers;
runtime traces are explicitly bounded.

Closed mailbox vocabulary

The runtime accepts typed messages for request/result/spawn/cancel/checkpoint/budget events. Arbitrary non-ground messages are rejected.

Typed-plan `spawn_agent`

Add term and JSON spawn_agent syntax, but deliberately desugar it into the existing closed trusted-tool operation tool(spawn_agent, ...).

That means agent spawning inherits the existing plan security/runtime boundaries:

tool(spawn_agent) capability is required before execution;
the trusted spawn adapter must be registered by host code;
plan step/tool/output budgets apply normally;
model data never becomes a Prolog callable;
capability denial occurs before child creation.

JSON-origin agent specs canonicalize anonymous JSON dict tags while actual metadata remains restricted to closed JSON-like values.

Public API

Expose runtime lifecycle, spawn/send/pump/status/children/cancel/trace operations and the trusted agent_tool_handler/4 adapter through the public rlm module.

Deterministic acceptance

Branch-head deterministic CI is green and covers:

child capability narrowing and widening rejection;
20 logical agents sharing a two-worker pool with no idle worker-per-agent allocation;
finite-mailbox backpressure;
worker result delivery through mailboxes;
child worker crash visibility at the supervisor;
parent-to-child cancellation propagation;
worker-pool saturation failing closed;
bounded runtime traces;
term-form spawn_agent execution;
JSON-form spawn_agent execution;
missing tool(spawn_agent) authority preventing child side effects.

Cleanup / safety

Temporary branch-only source-patch helpers and write-capable CI jobs used during connector-only development have been removed. The final workflow is back to contents: read.

Do not merge until exact-head deterministic CI and the same-repository REAL OpenRouter integration job are green, the final diff contains no temporary patch machinery or credential material, and the PR is mergeable.

Closes #11. ## Supervised logical-agent runtime Replace the `rlm_agent` stub with a bounded actor-style runtime: - SWI engines hold logical agent state without a permanent OS thread per agent; - finite message queues implement mailboxes and explicit backpressure; - one bounded SWI thread pool per runtime executes trusted blocking worker work; - supervisor/child relationships are first-class; - child capabilities are narrowed through the existing capability algebra; - worker failures become structured agent failures and are observable by the parent; - parent cancellation recursively propagates to children and outstanding workers; - runtime traces are explicitly bounded. ## Closed mailbox vocabulary The runtime accepts typed messages for request/result/spawn/cancel/checkpoint/budget events. Arbitrary non-ground messages are rejected. ## Typed-plan `spawn_agent` Add term and JSON `spawn_agent` syntax, but deliberately desugar it into the existing closed trusted-tool operation `tool(spawn_agent, ...)`. That means agent spawning inherits the existing plan security/runtime boundaries: - `tool(spawn_agent)` capability is required before execution; - the trusted spawn adapter must be registered by host code; - plan step/tool/output budgets apply normally; - model data never becomes a Prolog callable; - capability denial occurs before child creation. JSON-origin agent specs canonicalize anonymous JSON dict tags while actual metadata remains restricted to closed JSON-like values. ## Public API Expose runtime lifecycle, spawn/send/pump/status/children/cancel/trace operations and the trusted `agent_tool_handler/4` adapter through the public `rlm` module. ## Deterministic acceptance Branch-head deterministic CI is green and covers: - child capability narrowing and widening rejection; - 20 logical agents sharing a two-worker pool with no idle worker-per-agent allocation; - finite-mailbox backpressure; - worker result delivery through mailboxes; - child worker crash visibility at the supervisor; - parent-to-child cancellation propagation; - worker-pool saturation failing closed; - bounded runtime traces; - term-form `spawn_agent` execution; - JSON-form `spawn_agent` execution; - missing `tool(spawn_agent)` authority preventing child side effects. ## Cleanup / safety Temporary branch-only source-patch helpers and write-capable CI jobs used during connector-only development have been removed. The final workflow is back to `contents: read`. Do not merge until exact-head deterministic CI and the same-repository REAL OpenRouter integration job are green, the final diff contains no temporary patch machinery or credential material, and the PR is mergeable.