From 4f0a91ef55fe96835172bdad34feec1e2a0a0977 Mon Sep 17 00:00:00 2001 From: t Date: Sun, 16 Aug 2026 20:42:43 -0600 Subject: subagents extension on the generic host surfaces The rock now owns all subagent policy on top of libpanto-lua's generic APIs: children are ordinary panto.agent instances over rock-constructed stores, started with agent:run_async and awaited by arming uv.new_poll on each job's wake_fd from the tool handler's coroutine. subagents/jobs.lua carries the session policy the host used to own: the concurrency gate (4 running, FIFO queue, cancel-while-queued never starts), the await contract (results in input order; "first" returns settled plus remaining by identity), and settle-time shaping. subagents/spawn.lua seeds new children (primary system context, child role, profile body with manifest metadata), resolves model/reasoning through panto.ext.resolve_model, filters subagents.* out of the inherited tool set via agent:set_tools, and reads resume defaults back from stored message metadata. One-shot structured workers are a null_store agent with a declaration-only output tool, tool_choice forced, dispatch_tools=false. subagents/progress.lua renders per-tool-entry cards through the component handle's invalidate seam; turn_interrupt cancels live children, turn_end closes them. Spec suite rewritten against fakes of the new surfaces (98 cases), including gate/queue/cancel bounds, resume-default extraction, one-shot capture via unresolved tool calls, tool filtering, and manifest seeding. --- README.md | 39 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 39 insertions(+) (limited to 'README.md') diff --git a/README.md b/README.md index 8c24c36..713ea60 100644 --- a/README.md +++ b/README.md @@ -13,6 +13,22 @@ rocks = ["panto-subagents"] For a local checkout, use `paths = ["/path/to/panto-subagents"]` instead. +### Dependencies + +Panto installs the rock's dependencies with it: + +- **lyaml** parses profile frontmatter. It binds the system libyaml, which + LuaRocks does not vendor — install it first (`brew install libyaml`, or + `apt install libyaml-dev`), otherwise the rock fails to build and panto + quietly starts without the `subagents.*` tools. +- **toml2lua** reads TOML workflows. Pure Lua, nothing to install. +- **luv** backs profile and workflow discovery. Panto already ships it. + +Structured workflow output is validated against its JSON Schema by a built-in +validator covering the schema subset those results use. Installing the +`jsonschema` rock switches validation over to it; that rock needs a system PCRE, +so it is not a declared dependency. + ## Agent profiles Agents are Markdown files with YAML frontmatter: @@ -87,4 +103,27 @@ their structured result. Panto extensions can use this API directly, while `subagents.lua` runs model-authored one-off workflows in a restricted Lua environment. +## Development + +[mise](https://mise.jdx.dev) provides Lua 5.4 and LuaRocks: + +```sh +mise run deps # install the rocks into ./.rocks (gitignored) +mise run check # run the specs against that tree +``` + +`mise run deps` passes Homebrew's libyaml prefix to lyaml when brew is +available. Without mise, install the same rocks with any LuaRocks targeting Lua +5.4 and run `lua spec/run.lua` from the repo root. `panto lua spec/run.lua` runs +the suite inside panto's own interpreter and rocks tree, skipping whatever cases +that tree has no rock for. + +The specs are plain Lua asserts — no framework. `spec/run.lua` loads every +`spec/test_*.lua`, each of which returns an ordered array of `{ name, function }` +cases. A case asserts and returns nothing to pass, or returns `"skip", reason` +when an optional rock is missing; skips do not fail the run. `spec/fake_ext.lua` +is a scriptable stand-in for the `panto.ext` host seam: it queues the result each +spawned child settles with, records every spawn spec, tool, and command the +extension produced, and settles awaits synchronously. + See [DESIGN.md](DESIGN.md) for the runtime and persistence design. -- cgit v1.3