From d1306506aa7f504b0e91c9c6ed7314afbf99978e Mon Sep 17 00:00:00 2001 From: t Date: Wed, 19 Aug 2026 19:02:30 -0600 Subject: Add background Lua workflows, inline child prompts, and layered config subagents.lua now starts a workflow on its own coroutine and returns a session-scoped id immediately, so fan-out continues while the primary keeps working; completion wakes the primary, and later calls read immutable records from subagents.workflows. Every ctx:agent takes a workflow-unique name so those records are addressable. A session_start guidance message tells the primary when to reach for run vs lua. Children no longer inherit the primary's system context: a child starts from the fixed child-role instruction plus its profile, and subagents.run/ctx:agent accept an inline system_prompt instead of a profile. The now-redundant `agent` form of subagents.models is gone. Concurrency defaults to five and is configurable through [subagents] max_concurrent in any layered config.toml; turn boundaries reap only settled jobs so background workflows survive, while interrupt and session end cancel. Config roots come from panto.ext.dirs.layers rather than a hand-rolled XDG lookup, which picks up the base and git-ignored local layers for both agents/ and workflows/. TOML workflows tighten up: the subagents.workflow tool takes a discovered name only (inline `steps` duplicated subagents.lua at less power), an optional top-level `output` array chooses the reported steps and their order instead of the terminal set, a step with no workflow input gets no empty input heading, and a workflow naming an undiscovered agent is rejected at discovery rather than part-way through a run. --- README.md | 79 ++++++++++++++++++++++++++++++++++++++++++++++----------------- 1 file changed, 58 insertions(+), 21 deletions(-) (limited to 'README.md') diff --git a/README.md b/README.md index 73a3146..aadf719 100644 --- a/README.md +++ b/README.md @@ -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: +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/`. -- `${XDG_CONFIG_HOME:-$HOME/.config}/panto/agents/` -- `.panto/agents/` in the current project - -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:` commands. Ready steps +`workflows/` beneath the same config layers as profiles, then exposed as +`/workflow:` commands. Ready steps run concurrently; each dependent step receives its predecessors' labeled -outputs. - -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. +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. + +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 -- cgit v1.3