diff options
Diffstat (limited to 'README.md')
| -rw-r--r-- | README.md | 77 |
1 files changed, 57 insertions, 20 deletions
@@ -11,7 +11,14 @@ run several at once, and continue their conversations later. rocks = ["panto-subagents"] ``` -For a local checkout, use `paths = ["/path/to/panto-subagents"]` instead. +For a local checkout, use `paths = ["/path/to/panto-subagents"]` instead. A +`paths` entry loads the code but installs nothing, so put the dependencies below +in panto's own rocks tree first: + +```sh +panto lua -e 'require("luarocks.cmd").run("install", "toml2lua")' +panto lua -e 'require("luarocks.cmd").run("install", "lyaml")' +``` ### Dependencies @@ -21,7 +28,8 @@ Panto installs the rock's dependencies with it: 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. +- **toml2lua** reads the layered `config.toml` at activation and TOML workflows + afterwards. Pure Lua, nothing to install; without it activation fails. - **luv** backs profile and workflow discovery. Panto already ships it. Structured workflow output is validated against its JSON Schema by a built-in @@ -29,6 +37,18 @@ 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. +## Configuration + +At most five children run concurrently by default; additional children queue. +Override the limit in any layered `config.toml` (later layers win): + +```toml +[subagents] +max_concurrent = 10 +``` + +`max_concurrent` must be a positive integer. + ## Agent profiles Agents are Markdown files with YAML frontmatter: @@ -44,12 +64,11 @@ reasoning: high You are a focused code reviewer. Report only concrete findings. ``` -Profiles are loaded recursively from: - -- `${XDG_CONFIG_HOME:-$HOME/.config}/panto/agents/` -- `.panto/agents/` in the current project +Profiles are loaded recursively from `agents/` beneath every Panto config +layer, lowest precedence first: the built-in base layer, +`${XDG_CONFIG_HOME:-$HOME/.config}/panto/`, `.panto/`, and `.panto/local/`. -Project profiles override user profiles with the same name. `name` defaults to +A more local profile overrides an earlier one with the same name. `name` defaults to the filename. `model` and `reasoning` are optional; each value follows the same precedence: tool call, then profile, then the primary agent. Models use full `provider:model` names. @@ -65,6 +84,18 @@ subagents.run { } ``` +A one-off child can instead take an inline system prompt, without a saved +profile: + +```lua +subagents.run { + system_prompt = "You are a focused code reviewer.", + prompt = "Review the authentication changes.", +} +``` + +`agent`, `system_prompt`, and `id` are mutually exclusive. + Every started child returns an ID. Passing it back resumes the same conversation, including after restarting Panto and resuming the primary: @@ -75,9 +106,9 @@ subagents.run { } ``` -Children receive the primary's system and project context plus their own -profile prompt, but not the primary's conversation. They share its workspace -and tools except for `subagents.*`. +Children start a fresh conversation with the fixed child-role instruction and +their profile prompt; the primary's system prompt and conversation are not +copied. They share its workspace and tools except for `subagents.*`. Multiple calls in one tool batch run concurrently. Their tagged assistant and tool activity is visible in the TUI while they work. Child conversations are @@ -92,18 +123,24 @@ entire model catalog in every tool prompt. ## Workflows TOML workflows define fixed dependency graphs. They are loaded from -`${XDG_CONFIG_HOME:-$HOME/.config}/panto/workflows/` and -`.panto/workflows/`, then exposed as `/workflow:<name>` commands. Ready steps +`workflows/` beneath the same config layers as profiles, then exposed as +`/workflow:<name>` commands. Ready steps run concurrently; each dependent step receives its predecessors' labeled -outputs. +outputs. The workflow reports its terminal steps, or exactly the steps a +top-level `output = ["id", ...]` array names, in that order. + +The Lua workflow API handles dynamic branching and fan-out. `subagents.lua` +starts model-authored workflows in a restricted environment and returns a +session-scoped workflow ID immediately. Work continues on Pantograph's event +loop; completion wakes the primary, and later calls can inspect immutable +records through `subagents.workflows[id]`, including named child status and +outputs. Every `ctx:agent` needs a workflow-unique `name`, and the callback must +return the workflow's string result. -The Lua workflow API handles dynamic branching and fan-out. It can await one -job or a group, and supports one-turn workers whose validated tool input is -their structured result. `subagents.lua` may also define workflow-local agent -profiles inline, so a primary can create specialized workers without writing -profile files or restarting Panto; those profiles disappear when the tool call -ends. Panto extensions can use this API directly, while `subagents.lua` runs -model-authored one-off workflows in a restricted Lua environment. +Inline `agents` remain scoped to workflows started by that tool call. The API +can await one job or a group and supports one-turn workers whose validated tool +input is their structured result. Persistent TOML workflows remain the simpler +fixed-DAG surface. ## Development |