@alisio/plugin-subagents 0.1.0-alpha.7 → 0.1.0-alpha.9

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

@@ -23,6 +23,11 @@ export declare const subagentsConfigSchema: z.ZodObject<{
         prompt: z.ZodDefault<z.ZodString>;
         tools: z.ZodOptional<z.ZodArray<z.ZodString>>;
         model: z.ZodOptional<z.ZodString>;
+        mode: z.ZodOptional<z.ZodEnum<{
+            all: "all";
+            primary: "primary";
+            subagent: "subagent";
+        }>>;
     }, z.core.$strip>>>;
     worktreeDir: z.ZodOptional<z.ZodString>;
 }, z.core.$strict>;

package/dist/config.js

@@ -4,6 +4,8 @@ const cliAgent = z.object({
     prompt: z.string().default(""),
     tools: z.array(z.string()).optional(),
     model: z.string().optional(),
+    /** `primary`/`all` makes the definition available as an ACTIVE (main-session) agent in `/agents`. */
+    mode: z.enum(["subagent", "primary", "all"]).optional(),
 });
 /** Options under `builtinPlugins.subagents`. */
 export const subagentsConfigSchema = z

package/dist/definitions.d.ts

@@ -37,6 +37,7 @@ export interface CliAgent {
     prompt: string;
     tools?: string[];
     model?: string;
+    mode?: "subagent" | "primary" | "all";
 }
 /**
  * Discovery, first match wins by name: CLI `--agents` > project `.alisio/agents` >

package/dist/definitions.js

@@ -224,7 +224,13 @@ export async function discoverAgents(options) {
             agents.set(definition.name, definition);
     };
     for (const [name, spec] of Object.entries(options.cli ?? {})) {
-        const { definition, warnings: w } = parseAgentDefinition(`---\n${JSON.stringify({ name, description: spec.description, ...(spec.tools ? { tools: spec.tools } : {}), ...(spec.model ? { model: spec.model } : {}) })}\n---\n${spec.prompt ?? ""}`, { source: "cli" });
+        const { definition, warnings: w } = parseAgentDefinition(`---\n${JSON.stringify({
+            name,
+            description: spec.description,
+            ...(spec.tools ? { tools: spec.tools } : {}),
+            ...(spec.model ? { model: spec.model } : {}),
+            ...(spec.mode ? { mode: spec.mode } : {}),
+        })}\n---\n${spec.prompt ?? ""}`, { source: "cli" });
         warnings.push(...w);
         if (definition)
             add(definition);

package/dist/index.d.ts

@@ -2,6 +2,8 @@ import { type Plugin } from "@alisio/sdk";
 export type { AgentDefinition } from "./definitions.ts";
 export { BUILTIN_AGENTS, discoverAgents, parseAgentDefinition } from "./definitions.ts";
 export { SubagentManager } from "./manager.ts";
+/** Plugin-state key under which the plugin publishes main-session-capable (mode primary/all) agents. */
+export declare const MAIN_AGENTS_STATE_KEY = "mainAgents";
 export interface SubagentsPluginContext {
     workspace: string;
     stateHome: string;

package/dist/index.js

@@ -11,6 +11,8 @@ import { SubagentManager } from "./manager.js";
 import { loadVersion } from "./version.js";
 export { BUILTIN_AGENTS, discoverAgents, parseAgentDefinition } from "./definitions.js";
 export { SubagentManager } from "./manager.js";
+/** Plugin-state key under which the plugin publishes main-session-capable (mode primary/all) agents. */
+export const MAIN_AGENTS_STATE_KEY = "mainAgents";
 const schema = (properties, required) => ({
     type: "object",
     properties,
@@ -46,6 +48,20 @@ export function createSubagentsPlugin(rawOptions, context) {
                 plugins: api.resources.list("agents"),
             });
             warnings = found.warnings;
+            // Publish the main-session-capable definitions (mode `primary`/`all`) for the TUI's `/agents`
+            // picker. The host reads them through `pluginState`, so the TUI never imports this package.
+            // Only the fields the ACTIVE agent needs are persisted; prompts stay bounded.
+            api.state.set(MAIN_AGENTS_STATE_KEY, [...found.agents.values()]
+                .filter((a) => a.mode !== "subagent" && !a.hidden)
+                .map((a) => ({
+                name: a.name,
+                description: a.description,
+                prompt: a.prompt.slice(0, 24_000),
+                ...(a.model ? { model: a.model } : {}),
+                ...(a.readOnly ? { readOnly: true } : {}),
+                source: a.source,
+                ...(a.path ? { path: a.path } : {}),
+            })));
             const m = new SubagentManager(api, config, context, found.agents);
             manager = m;
             const status = () => {

package/dist/manager.js

@@ -342,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.7",
+  "version": "0.1.0-alpha.9",
   "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.6"
+    "@alisio/sdk": "^0.1.0-alpha.8"
   },
   "devDependencies": {
-    "@alisio/sdk": "0.1.0-alpha.6"
+    "@alisio/sdk": "0.1.0-alpha.8"
   },
   "publishConfig": {
     "access": "public",