@alisio/plugin-subagents 0.1.0-alpha.6 → 0.1.0-alpha.8

package/README.md

@@ -1,20 +1,77 @@
 # @alisio/plugin-subagents
 
-Subagents for [Alisio](https://github.com/GustavoGutierrez/alisio), shipped as a built-in plugin of the
-`alisio` CLI (disable with `--disable-plugin subagents`). The parent agent delegates work with the
-`task` tool to specialized agents that run in separate child sessions: fresh context, narrowed
-permissions, their own model and limits. It depends only on `@alisio/sdk` (generic
-`api.sessions`, `api.ui.panel`, `api.ui.select`) plus `zod` and `yaml`.
-
-- Agent definitions: Markdown + YAML frontmatter (`name`, `description`, `tools`, `model`,
-  `permission`, `maxTurns`, …) from `--agents`, `.alisio/agents`, `.agents/agents`, `.claude/agents`,
-  `.opencode/agent(s)`, user directories and plugins; built-ins `general`, `explore`, `plan`.
-- Tools: `task`, `task_status`, `task_wait`, `send_message`; parallel and background tasks, bounded
-  waits, `<task …>` results, `<task-notification>` on background completion.
-- Limits: depth, concurrency per parent and total, bounded queue, turns, timeout and token budget.
-- Parallel writes in git: worktree per subagent (merge/discard with `/agents`), serial or shared.
-- A live agent tree in the TUI with keyboard navigation and read-only child views.
-
-Docs: [Subagents](https://gustavogutierrez.github.io/alisio/subagents).
-
-Maintainer: Gustavo Gutiérrez · License: MIT
+**Subagents for [Alisio](https://github.com/GustavoGutierrez/alisio).** The parent agent delegates
+work with the `task` tool to specialized agents that run in separate child sessions: fresh context,
+narrowed permissions, their own model and limits.
+
+## What it is
+
+Shipped as a built-in plugin of the `alisio` CLI (disable with `--disable-plugin subagents` or
+`builtinPlugins.subagents.enabled: false`). It is built on the generic `api.sessions` service,
+`api.ui.panel` and `api.ui.select`, so it depends only on `@alisio/sdk` plus `zod` and `yaml`.
+
+## Installation
+
+Preinstalled in the `alisio` CLI. For an embedded host, register it through `createApplication`'s
+`builtins` list.
+
+## Tools
+
+| Tool | Input | Behavior |
+| --- | --- | --- |
+| `task` | `description`, `prompt`, `subagent_type`, optional `model`, `task_id`, `background` | Start an agent (or continue `task_id` with full history) and return its final report; several calls in one turn run in parallel |
+| `task_status` | `task_id` | Status, agent, background flag and tokens; does not wait |
+| `task_wait` | `task_id`, optional `timeout_ms` | Wait for a result, bounded by `waitMaxMs` |
+| `send_message` | `task_id`, `text` | One-way message: queued for a running child's next turn, or resumes a finished child |
+
+Results are wrapped in `<task …>` elements; background tasks deliver a `<task-notification>` when
+they finish. Failures are structured tool errors that keep the `task_id`, so a task can be resumed.
+
+## Agent definitions
+
+Markdown + YAML frontmatter (`name`, `description`, `tools`, `model`, `permission`, `maxTurns`, …)
+discovered from `--agents` (JSON), `.alisio/agents`, `.agents/agents`, `.claude/agents`,
+`.opencode/agent(s)`, user directories and plugin resources. Built-ins: `general` (multi-step
+tasks), `explore` (read-only exploration) and `plan` (read-only implementation plans).
+
+## Parallel writes in git
+
+With `parallelWrites: "worktree"`, each write-capable child works in its own git worktree
+(`worktreeDir`, default `<state home>/worktrees`); the TUI `/agents` command offers
+`open|cancel|kill|resume` and `merge|discard <id>` for worktrees. `ask`, `serial` and `shared` are
+the other modes.
+
+## Configuration
+
+Under `builtinPlugins.subagents`:
+
+| Field | Default | Description |
+| --- | --- | --- |
+| `maxDepth` | `3` | Maximum nesting (1–8) |
+| `maxConcurrentPerParent` | `4` | Running children per parent (1–32) |
+| `maxConcurrentTotal` | `8` | Running children in total (1–64) |
+| `maxQueued` | `16` | Waiting tasks beyond the concurrency limits (0–256) |
+| `maxTurns` | `50` | Default turn limit per child |
+| `timeoutMs` | `600000` | Timeout per child run |
+| `maxTokensPerChild` | core budget | Per-child cumulative token budget |
+| `maxOutputTokensPerChild` | `16384` | Per-child per-call output token budget |
+| `parallelWrites` | `ask` | `ask`, `worktree`, `serial` or `shared` |
+| `resultMaxBytes` | `50000` | Result size cap |
+| `worktreeDir` | `<state home>/worktrees` | Where worktrees are created |
+
+Children never exceed their parent: a read-only parent (or `--read-only`) makes every descendant
+read-only, and approvals bubble up to the TUI labeled with the agent path.
+
+## Docs
+
+[Subagents](https://gustavogutierrez.github.io/alisio/subagents) ·
+[Configuration](https://gustavogutierrez.github.io/alisio/configuration).
+
+## Requirements
+
+Node.js **>= 22.16** or Bun **>= 1.4.2**.
+
+## License
+
+MIT. Maintained by Gustavo Gutiérrez Mercado. Source: <https://github.com/GustavoGutierrez/alisio> ·
+npm: <https://www.npmjs.com/settings/alisio/packages>.

package/dist/config.d.ts

@@ -9,6 +9,7 @@ export declare const subagentsConfigSchema: z.ZodObject<{
     maxTurns: z.ZodDefault<z.ZodNumber>;
     timeoutMs: z.ZodDefault<z.ZodNumber>;
     maxTokensPerChild: z.ZodOptional<z.ZodNumber>;
+    maxOutputTokensPerChild: z.ZodDefault<z.ZodNumber>;
     parallelWrites: z.ZodDefault<z.ZodEnum<{
         ask: "ask";
         serial: "serial";

package/dist/config.js

@@ -18,6 +18,11 @@ export const subagentsConfigSchema = z
     timeoutMs: z.number().int().min(1_000).default(600_000),
     /** Per-child cumulative token budget; default follows the core proportional budget. */
     maxTokensPerChild: z.number().int().positive().optional(),
+    /**
+     * Per-child per-call output token budget. Children forward this (never the global agent-loop
+     * default) so reasoning-heavy models are not starved; 4096 would be spent on reasoning alone.
+     */
+    maxOutputTokensPerChild: z.number().int().positive().default(16_384),
     /** Parallel write-capable children in a git repository. */
     parallelWrites: z.enum(["ask", "worktree", "serial", "shared"]).default("ask"),
     waitMaxMs: z.number().int().min(100).default(600_000),

package/dist/manager.js

@@ -284,6 +284,7 @@ export class SubagentManager {
             maxTurns: agent.maxTurns ?? this.config.maxTurns,
             timeoutMs: this.config.timeoutMs,
             ...(this.config.maxTokensPerChild ? { maxTokens: this.config.maxTokensPerChild } : {}),
+            maxOutputTokens: this.config.maxOutputTokensPerChild,
         });
         const task = {
             id: info.id,
@@ -341,6 +342,8 @@ export class SubagentManager {
                 task.tokens = Math.max(task.tokens, result.usage.input + result.usage.output);
                 if (task.worktree && result.status === "completed")
                     await this.summarizeWorktree(task);
+                if (result.status === "completed" && result.turnsExceeded)
+                    task.notes.push("This subagent reached its turn limit; the report above may be incomplete. Ask it to continue or raise its maxTurns in the agent definition.");
                 task.result =
                     result.status === "completed"
                         ? this.wrap(task, "completed", result.text || "(no final message)")

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alisio/plugin-subagents",
-  "version": "0.1.0-alpha.6",
+  "version": "0.1.0-alpha.8",
   "description": "Subagents for Alisio: delegate tasks to specialized agents in separate child sessions with narrowed permissions, parallel execution, git worktree isolation and a live agent tree. Built-in, disableable plugin.",
   "author": "Gustavo Gutiérrez",
   "license": "MIT",
@@ -46,10 +46,10 @@
     "zod": "4.6.5"
   },
   "peerDependencies": {
-    "@alisio/sdk": "^0.1.0-alpha.5"
+    "@alisio/sdk": "^0.1.0-alpha.7"
   },
   "devDependencies": {
-    "@alisio/sdk": "0.1.0-alpha.5"
+    "@alisio/sdk": "0.1.0-alpha.7"
   },
   "publishConfig": {
     "access": "public",