@xynogen/pix-subagent 0.1.0

package/LICENSE

@@ -0,0 +1,27 @@
+MIT License
+
+Copyright (c) 2026 xynogen
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+---
+
+Portions of this software are ported from tintinweb/pi-subagents
+(https://github.com/tintinweb/pi-subagents), licensed under MIT.
+Copyright (c) tintinweb.

package/README.md

@@ -0,0 +1,114 @@
+# @xynogen/pix-subagent
+
+Pi extension — planner-driven sub-agents with 3 tools, live widget (model always visible), and explicit work-splitting.
+
+## Install
+
+Bundled by [`@xynogen/pix-core`](https://www.npmjs.com/package/@xynogen/pix-core) — no separate install needed.
+
+Standalone:
+
+```bash
+pi install npm:@xynogen/pix-subagent
+```
+
+## What it does
+
+Gives the parent agent (planner) three tools to delegate work to isolated child sessions:
+
+| Tool | Purpose |
+|---|---|
+| `agent` | Spawn a sub-agent (foreground or background) |
+| `agent_result` | Fetch latest output / full conversation by ID |
+| `agent_steer` | Inject a message into a running background agent |
+
+### The pix twist
+
+**Model name is always visible** — in the widget header and completion notification, regardless of whether the child uses the same model as the parent. Looks like:
+
+```
+● Agents
+├─ ⠹ Explore [haiku]  scout auth flow  · ↻2 · 3 tool uses · 12.4k · 1.2s
+│     ⎿  grep "middleware" src/
+└─ ✓ Plan [sonnet]  design refactor  · ↻5 · 2.1s
+```
+
+## Tools
+
+### `agent` — spawn a sub-agent
+
+```
+prompt           string    Self-contained task description
+description      string    3-5 words, shown in widget
+subagent_type    string    Agent type (see available types in tool description)
+model?           string    "provider/id" or fuzzy ("haiku") — from the live model list
+allowed_tools?   string[]  Restrict child's tools (intersected, never widens)
+thinking?        string    off|minimal|low|medium|high|xhigh
+max_turns?       number    Omit for unlimited
+run_in_background? bool    false (default) = foreground; true = background + notify
+resume?          string    Agent ID to continue
+isolated?        bool      No extension/MCP tools, builtins only
+inherit_context? bool      Fork parent conversation into child
+```
+
+**`allowed_tools[]`** is the work-splitting hook. Pass `["read","grep","find"]` to scope an Explore agent to read-only ops. The list is intersected with the agent type's default set — it can only narrow, never widen.
+
+**`model`** accepts `"provider/id"` or fuzzy strings like `"haiku"`, `"sonnet"`. The live list of available models (those with auth configured) is injected into the tool description so the planner can pick correctly. Unknown → error returned to planner to re-pick.
+
+### `agent_result` — fetch result
+
+```
+agent_id   string   ID returned by agent (background)
+verbose?   bool     true = full conversation; false (default) = latest text
+```
+
+Calling this suppresses the completion notification (result already consumed).
+
+### `agent_steer` — redirect running agent
+
+```
+agent_id   string   Running background agent ID
+message    string   Steering message to inject
+```
+
+Delivered after the agent's current tool execution. If the session isn't ready yet, the message is queued and delivered on session start.
+
+## Default agent types
+
+| Type | Tools | Model |
+|---|---|---|
+| `general-purpose` | all (read/bash/edit/write/grep/find/ls) | parent |
+| `Explore` | read/bash/grep/find/ls (read-only) | haiku |
+| `Plan` | read/bash/grep/find/ls (read-only) | parent |
+
+## Custom agents
+
+Drop a `.md` file in `.pi/agents/` (project) or `~/.pi/agent/agents/` (global):
+
+```markdown
+---
+description: Scout for auth-related code patterns
+tools: read, grep, find
+model: anthropic/claude-haiku-4-5
+thinking: low
+max_turns: 20
+---
+You are a read-only code scout. Find patterns, never write files.
+```
+
+Frontmatter fields: `description`, `tools` (CSV), `model`, `thinking`, `max_turns`, `extensions` (true/false/CSV), `skills` (true/false/CSV), `isolated`, `inherit_context`, `run_in_background`, `prompt_mode` (replace/append), `enabled` (false to disable).
+
+## Deferred (v2+)
+
+- Git worktree isolation (`isolation: "worktree"`)
+- Cron/interval scheduling (`schedule` param)
+- Cross-extension RPC event bus
+- `/agents` conversation viewer overlay
+- Persistent agent memory (user/project/local scope)
+- Smart group-join notifications for parallel fan-outs
+- Chain/parallel orchestration modes
+
+## Attribution
+
+Spawn engine ported from [tintinweb/pi-subagents](https://github.com/tintinweb/pi-subagents) (MIT).
+Work-splitting design inspired by [nicobailon/pi-subagents](https://github.com/nicobailon/pi-subagents) (MIT).

package/package.json

@@ -0,0 +1,46 @@
+{
+	"name": "@xynogen/pix-subagent",
+	"version": "0.1.0",
+	"description": "Pi tool — planner-driven sub-agents: spawn, fetch, steer scoped child agents",
+	"type": "module",
+	"main": "src/index.ts",
+	"scripts": {
+		"test": "bun test"
+	},
+	"files": [
+		"src",
+		"README.md",
+		"LICENSE"
+	],
+	"pi": {
+		"extensions": [
+			"src/extension.ts"
+		]
+	},
+	"keywords": [
+		"pi",
+		"pi-package",
+		"pi-extension",
+		"subagent",
+		"agent",
+		"autonomous"
+	],
+	"author": "xynogen",
+	"license": "MIT",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/xynogen/pix-mono.git",
+		"directory": "packages/pix-subagent"
+	},
+	"publishConfig": {
+		"access": "public"
+	},
+	"dependencies": {
+		"@sinclair/typebox": "^0.34.0"
+	},
+	"peerDependencies": {
+		"@earendil-works/pi-coding-agent": "*",
+		"@earendil-works/pi-ai": "*",
+		"@earendil-works/pi-tui": "*"
+	}
+}