From 8d3ee7114446c9d95abd47d826678a186a6562af Mon Sep 17 00:00:00 2001 From: Sam Rolfe Date: Mon, 15 Jun 2026 13:35:24 +1000 Subject: [PATCH] sam-4screen-desktop 2026-6-15:13:35:24 --- .obsidian/workspace.json | 14 +- .../350 AI/Pi Agent Extensions & Skills.md | 29 +- 300 areas/350 AI/Pi Subagent.md | 253 ++++++++++++++++++ 3 files changed, 273 insertions(+), 23 deletions(-) create mode 100644 300 areas/350 AI/Pi Subagent.md diff --git a/.obsidian/workspace.json b/.obsidian/workspace.json index 4cd8a64..9cc8d3e 100644 --- a/.obsidian/workspace.json +++ b/.obsidian/workspace.json @@ -13,12 +13,12 @@ "state": { "type": "markdown", "state": { - "file": "300 areas/350 AI/Pi Agent Extensions & Skills.md", + "file": "300 areas/350 AI/Pi Subagent.md", "mode": "source", "source": false }, "icon": "lucide-file", - "title": "Pi Agent Extensions & Skills" + "title": "Pi Subagent" } } ] @@ -181,10 +181,10 @@ "state": { "type": "file-properties", "state": { - "file": "300 areas/350 AI/Pi Agent Extensions & Skills.md" + "file": "300 areas/350 AI/Pi Subagent.md" }, "icon": "lucide-info", - "title": "File properties for Pi Agent Extensions & Skills" + "title": "File properties for Pi Subagent" } } ], @@ -207,10 +207,11 @@ "templater-obsidian:Templater": false } }, - "active": "7066c9273c6fb936", + "active": "c431d71763a4e2d5", "lastOpenFiles": [ - "100 inbox/test.md", "300 areas/350 AI/Pi Agent Extensions & Skills.md", + "300 areas/350 AI/Pi Subagent.md", + "100 inbox/test.md", "300 areas/350 AI/Moonshot AI Launches Kimi Work, a Local Desktop Agent Reportedly Running on Kimi K2.6 With a 300-Sub-Agent Agent Swarm.md", "200 projects/210 AI Resume/Tools.md", "200 projects/210 AI Resume/Local Hybrid Vector + Graph RAG Setup.md", @@ -234,7 +235,6 @@ "300 areas/360 Dev-Ops Network Computers/Pi MCP.md", "300 areas/360 Dev-Ops Network Computers/Bumblebee - The Open-Source Scanner for Messy Dev Machines.md", "300 areas/360 Dev-Ops Network Computers/Untitled.md", - "100 inbox/Docker Containers.md", "Clippings", "Untitled.canvas", "500 archive/540 Resources", diff --git a/300 areas/350 AI/Pi Agent Extensions & Skills.md b/300 areas/350 AI/Pi Agent Extensions & Skills.md index 8895af2..b28b428 100644 --- a/300 areas/350 AI/Pi Agent Extensions & Skills.md +++ b/300 areas/350 AI/Pi Agent Extensions & Skills.md @@ -36,7 +36,7 @@ aliases: [] | **plannotator** | `~/.agents` | Interactive plan review with browser UI, annotations, code review | | **caveman** | `~/.agents` | Ultra-compressed communication mode | | **markitdown** | `~/.agents` | Convert files (PDF, Word, Excel, PPTX, images, HTML, etc.) to Markdown. Image analysis via Qwen 2.5 VL 72B on OpenRouter. | -| **@tintinweb/pi-subagents** | npm (global) | 18 custom agent types, background agents, mid-run steering, session resume, worktree isolation, scheduling, cross-extension RPC | +| **@tintinweb/pi-subagents** | npm (global) | 18 custom agent types, background agents, mid-run steering, session resume, worktree isolation, scheduling, cross-extension RPC. See [[Pi Subagent]] for full documentation | | **@tintinweb/pi-tasks** | npm (global) | Task management with dependency tracking, auto-cascade, background process tracking, TaskExecute spawns subagents via RPC | | **gentle-engram** | `~/.agents` | Memory service connecting to engram via ENGRAM_URL. Replaces memory-vault. Session capture, compaction recovery | | **headroom-bridge** | `~/.agents` | `compress_for_agent` tool — compresses >20K chars via Headroom Docker on .13:8787. 60-95% token reduction | @@ -44,7 +44,7 @@ aliases: [] ### pi-subagents (@tintinweb) -v0.10.2, installed globally. 18 custom agent types in `~/.pi/agent/agents/` → `~/.agents/agents/`. Tools: `Agent()`, `get_subagent_result()`, `steer_subagent()`. `/agents` command for interactive management. Features: background agents with concurrency (4 default), mid-run steering, session resume, worktree isolation, scheduling, persistent widget showing live agent status. Cross-extension RPC event bus. +v0.10.2, installed globally. 18 custom agent types in `~/.pi/agent/agents/` → `~/.agents/agents/`. Tools: `Agent()`, `get_subagent_result()`, `steer_subagent()`. `/agents` command for interactive management. Features: background agents with concurrency (4 default), mid-run steering, session resume, worktree isolation, scheduling, persistent widget showing live agent status. Cross-extension RPC event bus. Patched: 24h agent survival (was 10min), clearDisabled on session start. See [[Pi Subagent]] for full documentation. ### pi-tasks (@tintinweb) @@ -377,19 +377,16 @@ compress_for_agent({ content }) ## Tasks -- [x] Rebuild NixOS to activate new packages (Google provider, ffmpeg/yt-dlp, pi-prompt-template-model, pi-mcp-adapter, pi-subagents) ✅ 2026-06-11 -- [x] Migrate pi-subagents to @tintinweb version with 18 agent types -- [x] Define all 18 agent types in subagents.json -- [x] Deploy models.json with OpenRouter provider routing -- [x] Deploy engram + gentle-engram memory service on .13 -- [x] Install pi-tasks (@tintinweb/pi-tasks) v0.7.0 -- [x] Set up Zellij layout for Pi dev environment -- [ ] Add MCP servers to `~/.config/mcp/mcp.json` or `.mcp.json` as needed (Home Assistant, databases, etc.) -- [ ] Run `/reload` in Pi to activate filechanges and new templates -- [ ] Add more prompt templates to `~/.pi/agent/prompts/` as needed +- [x] Rebuild NixOS to activate new packages ✅ 2026-06-11 +- [x] Migrate to @tintinweb/pi-subagents with 18 agent types ✅ 2026-06-14 +- [x] Deploy models.json with OpenRouter provider pinning (only: provider) ✅ 2026-06-14 +- [x] Deploy engram + gentle-engram memory service on .13 ✅ 2026-06-13 +- [x] Install pi-tasks (@tintinweb/pi-tasks) v0.7.0 ✅ 2026-06-13 +- [x] Patch pi-subagents: 24h cleanup, disable clearCompleted ✅ 2026-06-14 +- [x] Add memory: project to all 18 agent frontmats ✅ 2026-06-14 +- [x] Remove custom subagent-registry skill (built-in /agents menu is sufficient) ✅ 2026-06-14 +- [x] Update Pi Subagent.md and Pi Agent Extensions & Skills.md documentation ✅ 2026-06-14 +- [x] Update pi-subagents to v0.10.3 ✅ 2026-06-14 +- [x] Update pi-tasks to v0.7.0 ✅ 2026-06-13 - [ ] Verify video-extract works with Gemini -- [x] Add markitdown skill to Obsidian skills page ✅ 2026-06-11 -- [x] Add smart-router extension and update Obsidian docs ✅ 2026-06-11 -- [x] Deploy Headroom Docker compression on .13, integrate with smart-router ✅ 2026-06-11 -- [x] Replace smart-router with headroom-bridge and update all references - [ ] Clean up workspace-map.json entries for any stale memory packs diff --git a/300 areas/350 AI/Pi Subagent.md b/300 areas/350 AI/Pi Subagent.md new file mode 100644 index 0000000..fcf9d26 --- /dev/null +++ b/300 areas/350 AI/Pi Subagent.md @@ -0,0 +1,253 @@ +--- +created: 2026-06-15 +modified: 2026-06-15 +type: note +tags: + - ai + - pi + - subagent + - pi-subagents +aliases: [] +--- + +# Pi Subagent System + +Persistent named subagents with provider-pinned KV cache continuity. + +## What It Is + +Pi-subagents (@tintinweb v0.10.2) lets you spawn named, persistent subagents that: + +- **Run in background** — don't block the main session +- **Keep their context** — resume later with full conversation history +- **Pin to a provider** — KV cache stays warm across resume calls (= massive token savings) +- **Have persistent memory** — `memory: project` gives each agent its own memory directory +- **Survive session restarts** — patched to keep agents alive 24h, not 10 minutes + +--- + +## Key Concepts + +### Named Agents + +Every subagent gets a **human-readable name** so you can reference it later: + +- `coder-login` — coder-pro working on auth +- `searcher-1` — chat-search for web lookups +- `obsidian-docs` — obsidian agent for note editing + +Multiple instances of the same type can run simultaneously: + +- `coder-login` + `coder-nav-bar` — two coder-pro agents, different tasks +- `searcher-1` + `searcher-2` — parallel web searches + +### Provider Pinning + +Each agent is pinned to a specific OpenRouter provider via `only: [...]` in models.json. This ensures: + +- **KV cache continuity** — same provider = cache hits on resume +- **Predictable latency** — always route through the same serving host +- **Cost control** — token savings when context prefix is cached + +See [[Pi Agent Extensions & Skills#models.json]] for the full routing table. + +### Persistent Memory + +Agents with `memory: project` in their frontmatter get a persistent directory: + +``` +.pi/agent-memory// ← per-project, committed to git +.pi/agent-memory-local// ← per-project, gitignored +~/.pi/agent-memory// ← global, across all projects +``` + +Memory survives across resume calls. Agents build up knowledge over time. + +### Session-Scoped Registry + +Agents belong to a **pi session** (per-project directory). When you `/new` or `/resume`, the session's agents are available. + +--- + +## Creating Agents + +### Ask the LLM + +Simply describe what you need. The LLM will ask for a name if you don't provide one: + +``` +You: "Find all authentication files" +LLM: "What should I name this agent?" +You: "auth-finder" +LLM: *spawns agent, saves to registry* + "Created 'auth-finder' (chat-search, Google). ID: 7efad0d8" +``` + +### Agent Types Available + +| Type | Model | Provider | Memory | Tools | Use For | +|------|-------|----------|--------|-------|---------| +| `chat-search` | gemini-2.5-flash:free | Google | project | read, bash, grep, find | Web search, quick lookups | +| `coder-basic` | deepseek-chat | DeepInfra | project | read, bash, write, grep, find | Simple code edits | +| `coder-pro` | deepseek-v4-pro | DeepInfra | project | read, bash, write, grep, find, edit | Complex architecture | +| `code-analysis` | deepseek-r1-distill-qwen-32b | opencode-go | project | read, bash, grep, find | Security review, analysis | +| `code-ingest` | gemini-2.5-flash:free | Google | project | read, bash, grep, find | Scan/ingest docs, GitHub | +| `database` | deepseek-r1-distill-qwen-32b | opencode-go | project | read, bash, write, grep | SQL, schema design | +| `devops-basic` | deepseek-chat | DeepInfra | project | read, bash, write, grep, find | Docker, YAML, NixOS | +| `devops-pro` | deepseek-v4-pro | DeepInfra | project | read, bash, write, grep, find, edit | Complex infrastructure | +| `document-writer` | deepseek-r1-distill-qwen-32b | opencode-go | project | read, bash, write | Documents, letters | +| `file-ops` | qwen-coder-32b-instruct | opencode-go | project | read, bash, grep, find, write | Filesystem, drives | +| `home-automation` | deepseek-r1-distill-qwen-32b | opencode-go | project | read, bash, write, grep | MQTT, Home Assistant | +| `image-maker` | flux-1-schnell | Venice | project | read, bash, write | Image generation | +| `iot-coder` | qwen-coder-32b-instruct | opencode-go | project | read, bash, write, grep, find | Arduino, ESP32 | +| `iot-hardware` | kimi-k2.6 | Moonshot AI | project | read, bash, grep, find | Hardware specs, boards | +| `obsidian` | deepseek-r1-distill-qwen-14b | opencode-go | project | read, bash, write, grep, find | Obsidian notes | +| `research` | gemini-2.5-flash:free | Google | project | read, bash, grep, find | Web search, docs | +| `video-analyze` | qwen-2.5-vl | Alibaba | project | read, bash, grep, find | Video/image analysis | +| `vscode-setup` | qwen-3-coder-next | StreamLake | project | read, bash, grep, find | VS Code, AI tooling | +| `Explore` | haiku/inherit | default | — | read, bash, grep, find, ls | Fast codebase search (built-in) | +| `Plan` | inherit | default | — | read, bash, grep, find, ls | Implementation planning (built-in) | +| `general-purpose` | inherit | default | — | all tools | General tasks (built-in) | + +--- + +## Managing Agents + +### List Agents + +Type `/agents` to open the interactive menu: + +``` +Running agents (2) — 1 running, 1 done +Agent types (21) +Create new agent +Settings +``` + +Select **"Running agents"** to see active agents with status, tool uses, and duration. + +### View Conversation + +From `/agents` → "Running agents" → select an agent: + +- **Live scrolling overlay** of the agent's full conversation +- **Auto-follows** new output +- **Press `x`** to stop a running agent +- **Scroll up** to pause auto-follow + +### Resume an Agent + +``` +You: "Resume auth-finder and also check the logout module" +LLM: *looks up agent ID from context* + Agent({ subagent_type: "chat-search", resume: "7efad0d8-...", prompt: "Also check the logout module" }) +``` + +The agent continues with its full context preserved. Provider KV cache is warm. + +### Steer a Running Agent + +``` +You: "Tell auth-finder to focus on the API routes only" +LLM: steer_subagent({ agent_id: "7efaf0d8-...", message: "Focus on API routes only, ignore UI" }) +``` + +The agent receives the message after its current tool execution and adjusts course. + +### Delete an Agent + +``` +You: "Delete auth-finder" +LLM: *removes from registry, aborts if running* + "Deleted 'auth-finder'" +``` + +Or delete all agents for a session: + +``` +You: "Clear all subagents for computer-software" +LLM: *removes all matching entries* + "Deleted 4 subagents from session 'computer-software'" +``` + +--- + +## Function Calls + +### Create + +``` +Agent({ + subagent_type, // string — agent type (e.g. "coder-pro") + prompt, // string — the task + description, // string — 3-5 word summary + model?, // string — provider/model override + thinking?, // string — off|minimal|low|medium|high|xhigh + max_turns?, // number — max agentic turns (default: unlimited) + run_in_background?, // boolean — run async (default: false) + resume?, // string — agent ID to resume a previous session + isolated?, // boolean — no extension/MCP tools + isolation?, // "worktree" — run in isolated git worktree + inherit_context? // boolean — fork parent conversation into agent +}) +``` + +### Retrieve + +``` +get_subagent_result({ + agent_id, // string — the agent ID from spawn notification + wait?, // boolean — block until complete (default: false) + verbose? // boolean — include full conversation (default: false) +}) +``` + +### Steer + +``` +steer_subagent({ + agent_id, // string — running agent ID + message // string — message injected after current tool execution +}) +``` + +### Compress + +``` +compress_for_agent({ + content // string — content >20K chars to compress via Headroom +}) +// Returns: { compressed, originalLength, compressedLength, tokensBefore, tokensAfter, savingsPercent } +``` + +--- + +## Token Savings + +The entire purpose is to **minimize context tokens** on the API provider: + +| Scenario | Context Uploaded | Cost | +|----------|-----------------|------| +| Fresh agent every request | Full system prompt + context (~10K tokens) | ~$0.50-1.00 per request | +| Resume same agent | Only new prompt (~100 tokens) + cached prefix hits KV cache | ~$0.01-0.05 per request | +| **Savings** | **90-95% reduction** | **~$0.50 vs $5.00 for 5 questions** | + +--- + +## Files + +| File | Purpose | +|------|---------| +| `~/.local/share/npm-global/lib/node_modules/@tintinweb/pi-subagents/` | Extension source | +| `~/.pi/agent/agents/*.md` | Agent type definitions (18 custom + 3 built-in) | +| `~/.pi/agent/models.json` | OpenRouter provider pinning (only: provider) | +| `.pi/agent-memory//` | Per-agent persistent memory (project scope) | +| `.pi/agent-memory-local//` | Per-agent persistent memory (gitignored) | +| `~/.pi/agent/subagents.json` | pi-subagents settings (maxConcurrent, etc.) | + +## Related + +- [[Pi Agent Extensions & Skills]] — full extensions/skills reference +- [[Engram Memory]] — persistent memory service on .13 +- [[Headroom Compression]] — context compression via .13:8787 +- [[OpenRouter Provider Routing]] — provider pinning for cache continuity