138 lines
4.3 KiB
Markdown
138 lines
4.3 KiB
Markdown
---
|
|
name: subagent-registry
|
|
description: Manage named subagent instances with persistent provider pinning and memory. Use when spawning, resuming, listing, or deleting subagents.
|
|
---
|
|
|
|
# Subagent Registry
|
|
|
|
Manage named subagent instances. Each agent gets a human-readable name, persistent memory, and pinned provider for KV cache continuity.
|
|
|
|
## Registry File
|
|
|
|
`<project>/.pi/subagents.json`:
|
|
|
|
```json
|
|
{
|
|
"session": "<session-name>",
|
|
"agents": [
|
|
{
|
|
"name": "<human-readable-name>",
|
|
"id": "<agent-uuid>",
|
|
"type": "<agent-type>",
|
|
"provider": "<provider-config>",
|
|
"status": "running|completed|error",
|
|
"created": "<ISO-timestamp>"
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
## Rules
|
|
|
|
1. **Always ask for a name** when spawning a new subagent. Never auto-generate. Ask: "What should I name this subagent?"
|
|
2. **One agent per name.** If name exists, ask for a different name.
|
|
3. **Store the agent ID** in the registry immediately after spawn.
|
|
4. **Use the same provider** when resuming — read from registry.
|
|
5. **Each named agent gets its own memory** directory via `memory: project` in agent frontmatter.
|
|
6. **No auto-cleanup.** Agents persist until explicitly deleted.
|
|
7. **Session-scoped.** Registry is per-project directory.
|
|
|
|
## Workflow: Spawn
|
|
|
|
1. User requests a subagent
|
|
2. **Ask for a name** if not provided: "What should I name this subagent?"
|
|
3. Call `Agent({ subagent_type, prompt, run_in_background: true, ... })`
|
|
4. Wait for completion notification with agent ID
|
|
5. Append to `.pi/subagents.json`:
|
|
```json
|
|
{
|
|
"name": "<user-given-name>",
|
|
"id": "<agent-uuid>",
|
|
"type": "<subagent_type>",
|
|
"provider": "<provider-config-from-agent-frontmatter>",
|
|
"status": "running",
|
|
"created": "<ISO-timestamp>"
|
|
}
|
|
```
|
|
6. Inform user: "Created subagent '<name>' (<id-short>) using <provider>"
|
|
|
|
## Workflow: Resume
|
|
|
|
1. User says "resume <name>" or "tell <name> to..."
|
|
2. Read `.pi/subagents.json`, find agent by name
|
|
3. If not found: "No subagent named '<name>'. Use /subagent-list to see available agents."
|
|
4. If found: `Agent({ subagent_type, resume: "<agent-id>", prompt: "<new-task>", run_in_background: true })`
|
|
5. Update status in registry to "running"
|
|
6. Inform user: "Resumed '<name>' (<id-short>) — <provider> cache warm"
|
|
|
|
## Workflow: List
|
|
|
|
Display all agents in a compact table:
|
|
|
|
```
|
|
Name Type Provider Status Created
|
|
---- ---- -------- ------ -------
|
|
coder-login coder-pro DeepInfra ✓ done 20:00
|
|
coder-nav coder-pro DeepInfra ↻ run 20:05
|
|
obsidian-edit obsidian StreamLake ✓ done 19:30
|
|
```
|
|
|
|
Show: name, type, provider (from config), status, created time.
|
|
|
|
## Workflow: Delete
|
|
|
|
1. User says "delete <name>" or "kill <name>"
|
|
2. Read registry, find agent
|
|
3. If running: call `TaskStop` or steer to abort
|
|
4. Remove entry from registry
|
|
5. Inform user: "Deleted '<name>' (<id-short>)"
|
|
|
|
## Workflow: Delete Session
|
|
|
|
1. User says "delete session <name>" or "clear all subagents for <session>"
|
|
2. Find all agents where `session == <name>`
|
|
3. Abort any running agents
|
|
4. Remove all matching entries from registry
|
|
5. Inform user: "Deleted <N> subagents from session '<name>'"
|
|
|
|
## Provider Config Format
|
|
|
|
Store as string: `"only:<provider-slug>"`
|
|
|
|
Examples:
|
|
- `"only:DeepInfra"`
|
|
- `"only:Baidu"`
|
|
- `"only:StreamLake"`
|
|
- `"only:Moonshot AI"`
|
|
|
|
When resuming, parse and reconstruct the provider field:
|
|
```
|
|
"only:DeepInfra" → { "only": ["DeepInfra"] }
|
|
```
|
|
|
|
## Memory
|
|
|
|
Each named agent should have `memory: project` in its frontmatter. This gives it a persistent memory directory at `.pi/agent-memory/<agent-name>/` that survives across resume calls.
|
|
|
|
## Session Name
|
|
|
|
The `session` field in the registry should match the pi session name. If no session name is set, use the project directory name.
|
|
|
|
## Example Interaction
|
|
|
|
```
|
|
User: "Spawn a coder-pro to fix the login module"
|
|
LLM: "What should I name this subagent?"
|
|
User: "auth-login"
|
|
LLM: *spawns agent, gets ID 7efad0d8-5a78-415*
|
|
LLM: "Created subagent 'auth-login' (7efad0d8) using DeepInfra"
|
|
|
|
User: "What subagents do we have?"
|
|
LLM: *reads registry, displays table*
|
|
auth-login coder-pro DeepInfra ✓ done 20:00
|
|
|
|
User: "Resume auth-login and tell it to add password reset"
|
|
LLM: *reads registry, finds ID, resumes with same provider*
|
|
LLM: "Resumed 'auth-login' (7efad0d8) — DeepInfra cache warm"
|
|
```
|