@tyroneross/build-loop 0.30.3

package/skills/building-with-deepagents/SKILL.md

@@ -0,0 +1,195 @@
+---
+name: building-with-deepagents
+description: Use when building or refactoring an agent that imports OSS `deepagents` (`from deepagents import create_deep_agent`). Covers SubAgent API, middleware, tool scoping, streaming, checkpointing. Not for `.claude/agents/*.md`.
+user-invocable: false
+---
+
+<!-- SPDX-FileCopyrightText: 2025-2026 Tyrone Ross, Jr <46267523+tyroneross@users.noreply.github.com> | SPDX-License-Identifier: Apache-2.0 -->
+
+# Building With DeepAgents (OSS)
+
+This skill is for agents running on the open-source `deepagents` package (`pip install deepagents`) on top of LangChain / LangGraph, typically paired with a local model via `langchain-ollama`. It is **not** for the hosted LangChain/DeepAgents cloud product — if you find yourself reaching for LangSmith Platform or hosted subagents, stop: those features don't apply here. Prefer Arize Phoenix (self-hosted, OpenInference instrumentation) for observability in OSS deployments.
+
+Read this skill **before** writing or modifying code that calls `create_deep_agent`, defines agent "roles", or streams LangGraph events.
+
+## When this applies
+
+Triggers (check any):
+- Project imports `deepagents` (grep `from deepagents`)
+- Project has a multi-role agent concept (planner / researcher / writer / etc.)
+- Work touches tool binding, system prompts, focus/single-agent mode, or streaming of an existing DeepAgents app
+- Pain report mentions: tool-call hallucinations, "silent thinking" gaps, focus-mode prompt injection, per-agent model routing
+
+## Authoritative sources
+
+Read these in order when you need more detail than this skill:
+
+1. `references/api-quick-reference.md` — the `SubAgent` TypedDict, `create_deep_agent()` signature, middleware stack, cached on disk
+2. `references/anti-patterns.md` — concrete bugs we've hit and what DeepAgents does / doesn't prevent
+3. **Live source** — the installed package is always ground truth. Find it with:
+   ```bash
+   python3 -c "import deepagents; print(deepagents.__file__)"
+   ```
+   Read `graph.py` (the assembly logic) and `middleware/subagents.py` (the `SubAgent` TypedDict + dispatch).
+4. **GitHub**: `https://github.com/langchain-ai/deepagents` — CHANGELOG for recent middleware additions
+5. **LangGraph docs**: `https://langchain-ai.github.io/langgraph/` — streaming modes, checkpointing, interrupts. DeepAgents is a thin wrapper over LangGraph.
+6. **Context7 MCP**: `mcp__plugin_context7_context7__resolve-library-id("deepagents")` for on-demand doc lookups during build.
+
+## Core principles
+
+### Principle 1 — Per-subagent tool scoping is the hallucination fix
+
+Small local models (< 14B) emit fabricated tool-call namespaces when given a large flat tool set for a prompt that needs none (e.g. `repo_browser.write_todos` when only `write_todos` was requested). The canonical fix is **not** validation after the fact — it's restricting each subagent's tool surface so the model has fewer options to invent against.
+
+**Do**: pass `subagents=[{"name": "planner", "tools": [], ...}]` so the Planner only sees DeepAgents' built-in middleware tools.
+**Don't**: pass a single flat `tools=[...]` list and inject "You are the X agent" in the system prompt.
+
+Evidence: `middleware/subagents.py:65` — the `SubAgent["tools"]` field; `middleware/subagents.py:347` — per-subagent tool resolution falling back to `default_tools` if unspecified.
+
+### Principle 2 — The middleware stack is always-on; treat it as free
+
+DeepAgents injects by default (see `graph.py:192-260`):
+- `TodoListMiddleware` → provides `write_todos`
+- `FilesystemMiddleware` → `ls`, `read_file`, `write_file`, `edit_file`, `glob`, `grep`
+- `SummarizationMiddleware` → automatic context-window pruning
+- `PatchToolCallsMiddleware` → cleans up orphaned tool calls (missing `ToolMessage`)
+- `SubAgentMiddleware` → the `task` tool for main-agent delegation
+
+You do NOT need to re-implement any of these. If you wrote your own summarization, thread-storage loader, or orphan-tool-call cleanup before finding this skill — delete it.
+
+### Principle 3 — Focus mode = scoped main agent, NOT prompt injection
+
+"Single-agent" or "focus" mode (user pins one role, skips delegation) should be implemented by:
+
+```python
+# Focus mode: main agent IS the role.
+agent = create_deep_agent(
+    model=role_model,
+    tools=scoped_tools,           # only the role's allow-list
+    system_prompt=role_prompt,     # the role's system_focus verbatim
+    subagents=[],                  # no delegation — no `task` tool
+)
+```
+
+Not by appending `"\n\n## Single-Agent Mode\n\nYou are the X agent..."` to a shared system prompt. The prompt-injection approach leaves the full flat tool surface accessible, which is exactly the hallucination failure mode Principle 1 addresses.
+
+### Principle 4 — Keep local optimizations that DeepAgents doesn't cover
+
+DeepAgents is agnostic to:
+- Local-model cold-load (no Ollama awareness). Keep your warmup + heartbeat code.
+- SSE transport to a UI. DeepAgents emits LangGraph events; you still wire the HTTP.
+- Fast-path routing for trivial prompts. As of v0.4.x there is no "skip the graph" concept; future `middleware` additions could change this — re-check the changelog before removing a fast-path layer.
+- Tool-name validation as a defensive layer. DeepAgents' `PatchToolCallsMiddleware` only handles orphaned `ToolMessage`, not invalid tool names.
+
+Don't delete these when migrating to DeepAgents' native features. They solve different problems.
+
+## The `SubAgent` spec — quick reference
+
+```python
+from deepagents import create_deep_agent
+from deepagents.middleware.subagents import SubAgent  # TypedDict
+
+subagent: SubAgent = {
+    "name": "researcher",                    # required
+    "description": "Gathers web + file info",# required — main agent reads this to decide when to delegate
+    "system_prompt": "You are RESEARCHER...",# required
+    "tools": [web_search, scrape_url, ...],  # optional — if omitted, inherits main agent's tools
+    "model": "provider:model-name",          # optional — per-agent model routing
+    "skills": ["/path/to/skills/"],          # optional — markdown skills injection
+    "interrupt_on": {"dangerous_tool": True},# optional — human-in-the-loop
+    "permissions": [...],                    # optional — FilesystemPermission rules
+}
+
+agent = create_deep_agent(
+    model=main_model,
+    tools=[...],              # main agent's tools (subagents have their own)
+    system_prompt="...",
+    subagents=[subagent],     # ONE or more; ordering matters for main-agent selection
+    checkpointer=...,         # pass a real Checkpointer, not MemorySaver, for durable threads
+)
+```
+
+### Recommended checkpointer
+
+`MemorySaver` is volatile — threads vanish on restart. Use `SqliteSaver` for local apps:
+
+```python
+from langgraph.checkpoint.sqlite import SqliteSaver
+checkpointer = SqliteSaver.from_conn_string(".app/checkpoints.db")
+```
+
+Durable threads + resume-from-checkpoint come for free. You do not need a custom `threads.py` loader.
+
+## Streaming — match the UI's needs
+
+DeepAgents exposes LangGraph's stream API verbatim. Pick the mode based on what the UI consumes:
+
+| Mode | Emits | Good for |
+|---|---|---|
+| `"updates"` | Node outputs (messages list) on each step | Tool-event-level UI (our current bridge) |
+| `"messages"` | Token-by-token from the LLM node | Chat UI with per-token streaming |
+| `["updates", "messages"]` | Both | The usual answer — tool events **and** tokens |
+| `astream_events(version="v2")` | Typed `on_tool_start`, `on_chat_model_stream`, etc. | Clean disambiguation without message-sniffing |
+
+If your current SSE loop does `hasattr(msg, "tool_calls")` or `msg.type == "tool"` branching, consider `astream_events` instead — cleaner event types, forward-compatible.
+
+## Local model gotchas
+
+When paired with `langchain-ollama`:
+
+1. **Always set a read timeout** — default is infinite (`None`). A hung model blocks the UI forever:
+   ```python
+   ChatOllama(model=..., client_kwargs={"timeout": httpx.Timeout(connect=5, read=600, write=30, pool=5)})
+   ```
+2. **Add `.with_retry()`** for transient `httpx.TransportError` — common when a model is hot-unloaded mid-turn:
+   ```python
+   llm.with_retry(stop_after_attempt=2, wait_exponential_jitter=True,
+                  retry_if_exception_type=(httpx.TransportError, httpx.TimeoutException))
+   ```
+3. **`num_ctx` is sticky** — changing it between calls triggers full KV-cache re-allocation in Ollama. Pick one per role, don't vary.
+4. **Parallel tool calls are serialized** by Ollama's OpenAI-compat endpoint even when the flag is set. Don't prompt the model to "call tools in parallel."
+5. **Structured output (`format: json`) conflicts with tool calling** — use one or the other per turn.
+
+## Anti-patterns we've encountered
+
+- **Flat tool list + prompt-injected focus mode** → tool-name hallucinations. See Principle 1.
+- **Re-implementing summarization** → `SummarizationMiddleware` is already in the default stack.
+- **Using `MemorySaver` in production** → threads vanish on restart. Swap to `SqliteSaver`.
+- **Relying on `agent.stream("updates")` alone** → tokens are invisible until a tool boundary. UI appears frozen. Use multi-mode or events.
+- **Per-call `num_ctx` tuning** → forces KV cache re-alloc. Fix `num_ctx` per role.
+- **No `.with_retry()`** → a single `httpx.ReadError` kills the turn.
+
+## Before you code
+
+Run these checks:
+
+1. **Read the installed source**. `cat $(python3 -c 'import deepagents, os; print(os.path.dirname(deepagents.__file__))')/middleware/subagents.py | head -100`
+2. **Check the version**. `pip show deepagents` — know what API you have.
+3. **Grep the repo for anti-patterns** before adding new code:
+   ```bash
+   grep -rn "agent_focus_prompt\|## Single-Agent Mode\|flat tool" src/
+   grep -rn "MemorySaver" src/   # durable threads?
+   grep -rn "ChatOllama(" src/ | grep -v client_kwargs  # missing timeout?
+   ```
+
+## Output (what "done" looks like)
+
+A DeepAgents-based agent is well-built when:
+
+- [ ] Each role that exists conceptually has its own `SubAgent` spec with a scoped `tools` list
+- [ ] Focus/single-agent mode scopes the MAIN agent's tools — no prompt-level "You are the X agent" override
+- [ ] `ChatOllama` instances have `client_kwargs={"timeout": ...}` and `.with_retry()`
+- [ ] `checkpointer` is durable (SQLite/Postgres), not `MemorySaver`
+- [ ] `astream_events(version="v2")` or multi-mode streaming is used if the UI needs per-token updates
+- [ ] Local-only optimizations (warmup, heartbeat, fast-path, tool validator) are preserved — DeepAgents doesn't cover them
+- [ ] The tool-name validator is still present as a belt-and-braces guard against small-model fabrication
+
+## Related skills
+
+- `build-loop:debug-loop` — for investigating agent behavior (tool hallucinations, stuck streams)
+- `prompt-builder:prompt-builder` — for tightening per-role `system_prompt` text
+- `calm-precision` — if you're also building the UI side of the agent
+
+---
+
+*Version 1.0 — 2026-04-13. Based on `deepagents` v0.4.x. Re-read the installed package source when the CHANGELOG mentions middleware or SubAgent changes.*

package/skills/building-with-deepagents/references/anti-patterns.md

@@ -0,0 +1,141 @@
+<!-- SPDX-FileCopyrightText: 2025-2026 Tyrone Ross, Jr <46267523+tyroneross@users.noreply.github.com> | SPDX-License-Identifier: Apache-2.0 -->
+
+# DeepAgents Anti-Patterns
+
+Concrete bugs from real projects, mapped to what DeepAgents does or does not cover.
+
+## AP-1: Flat tool list + prompt-injected "focus mode"
+
+**Symptom**: user pins a single agent role (e.g. Planner). Model emits `repo_browser.write_todos` or `mcp.execute` — fabricated namespaces that don't exist in the tool registry. Loop detection fires, turn limit eventually triggers, UI shows a wall of red `tool_error` events for a trivial prompt.
+
+**Root cause**: the main agent had access to all tools (web_search, python_exec, ...). The "focus" was enforced via a `## Single-Agent Mode` system-prompt suffix saying "you are the Planner, use write_todos only." Small models (< 14B) don't reliably obey prompt-level constraints against an in-scope tool list. When the prompt needs no tool call (e.g. "capital of france"), the model invents plausible-looking namespaced tools from its training data.
+
+**Fix**: scope tools at the SubAgent level (or at main-agent level in focus mode). Never rely on the prompt alone to restrict tool access.
+
+**DeepAgents coverage**: ✅ supported via `SubAgent["tools"]`.
+
+---
+
+## AP-2: Re-implementing summarization middleware
+
+**Symptom**: code grows a custom `_truncate_old_messages()` or `_summarize_if_long()` function. Duplicates what DeepAgents already provides.
+
+**Root cause**: contributor didn't read the default middleware stack.
+
+**Fix**: delete the custom summarizer. `create_summarization_middleware` is injected automatically in `graph.py`.
+
+**DeepAgents coverage**: ✅ default stack.
+
+---
+
+## AP-3: `MemorySaver` in production
+
+**Symptom**: user asks "continue our research from yesterday" — all prior context gone after a backend restart.
+
+**Root cause**: `MemorySaver` is in-process; threads evaporate on process exit.
+
+**Fix**: swap to `SqliteSaver.from_conn_string(".app/checkpoints.db")`. LangGraph handles resume automatically.
+
+**DeepAgents coverage**: ✅ any LangGraph `Checkpointer` works.
+
+---
+
+## AP-4: UI looks frozen during LLM reasoning
+
+**Symptom**: user sends "write a 5-page report". UI shows "Thinking…" for 30 seconds, no tokens stream, then a giant block appears at the end.
+
+**Root cause**: stream loop uses `stream_mode="updates"` only. Updates fire on node boundaries (typically after an LLM call finishes). Per-token output is invisible.
+
+**Fix**: either multi-mode `stream_mode=["updates", "messages"]` or switch to `astream_events(version="v2")` and handle `on_chat_model_stream`.
+
+**DeepAgents coverage**: ✅ LangGraph's streaming API is exposed verbatim.
+
+---
+
+## AP-5: Cold-model load looks like a crash
+
+**Symptom**: first query after app launch hangs for 30–60s with no UI signal, then suddenly works. Intermediaries drop the SSE connection during the silence.
+
+**Root cause**: Ollama loads the model into VRAM on first request. DeepAgents doesn't know or care about this — it just hangs in the `ChatOllama.stream()` call.
+
+**Fix**: warm the model explicitly before the first query. POST to `/api/generate` with empty prompt and `keep_alive: "30m"` at backend startup. Emit a "loading" SSE event from your bridge so the UI can show a loading overlay. Add a heartbeat pulse every 15s during silent agent-stream gaps.
+
+**DeepAgents coverage**: ❌ — this is a local-model concern. Build it around DeepAgents, not into it.
+
+---
+
+## AP-6: Tool-name hallucinations still leak after scoping
+
+**Symptom**: even with scoped tools, an 8B model occasionally emits `write_todos.plan` or `filesystem.read_file` — dotted variants of real tools.
+
+**Root cause**: small model pulling patterns from training data. Scoping blocks the worst cases but doesn't eliminate fabrication.
+
+**Fix**: belt-and-braces tool-name validator that rejects any name containing `.` or `/` before it reaches the UI, with a clean `tool_error` event. DeepAgents' `PatchToolCallsMiddleware` only handles *orphaned* tool calls (missing `ToolMessage`), not invalid names.
+
+**DeepAgents coverage**: ⚠️ partial. Keep the validator.
+
+---
+
+## AP-7: `num_ctx` varying per request
+
+**Symptom**: noticeable stall when the system prompt size changes between requests. Ollama logs show KV cache re-allocation.
+
+**Root cause**: every unique `num_ctx` value triggers a full KV cache re-alloc in Ollama.
+
+**Fix**: pin `num_ctx` per role (e.g. 4096 for full agent, 2048 for fast-path). Don't vary it based on prompt size.
+
+**DeepAgents coverage**: ❌ Ollama-specific.
+
+---
+
+## AP-8: No retry on transient Ollama errors
+
+**Symptom**: user query fails with `httpx.ReadError: Server disconnected` a few seconds in. Usually happens right after a model switch.
+
+**Root cause**: Ollama hot-unloads the previous model when a new one is requested, and in-flight requests get dropped. No retry path.
+
+**Fix**: wrap `ChatOllama` in `.with_retry()`:
+```python
+llm.with_retry(stop_after_attempt=2, wait_exponential_jitter=True,
+               retry_if_exception_type=(httpx.TransportError, httpx.TimeoutException))
+```
+
+**DeepAgents coverage**: ❌ — LangChain core feature.
+
+---
+
+## AP-9: Stream cancellation doesn't stop the LLM (TAG:TIMEBOUND)
+
+**Symptom**: user clicks Stop. UI updates, but GPU/CPU stays pegged for seconds or minutes. Ollama logs show the model still generating.
+
+**Root cause**: `ThreadingHTTPServer` only detects client disconnect on the next `wfile.write`. And even then, cancelling the Python generator doesn't cancel the underlying `httpx` stream — `langchain-ollama` provides no abort token.
+
+**Fix**: partial — migrate the SSE bridge to ASGI (Starlette + `uvicorn`). `await request.is_disconnected()` inside the generator gives clean cancellation. Then thread that through the `ChatOllama` stream (requires monkey-patching or waiting for langchain-ollama to expose an `abort` hook).
+
+**TIMEBOUND**: the monkey-patch recommendation ages badly once `langchain-ollama` exposes a first-class abort. Re-check upstream before reaching for a patch — track the tracking issues in the langchain-ai/langchain-ollama repo.
+
+**DeepAgents coverage**: ❌ — transport-layer concern.
+
+---
+
+## AP-10: `ChatOllama` default timeout = infinite
+
+**Symptom**: a stuck or slow-loading model never returns. UI hangs forever.
+
+**Root cause**: `ChatOllama` passes `None` as the httpx timeout by default.
+
+**Fix**: always set `client_kwargs={"timeout": httpx.Timeout(connect=5, read=600, write=30, pool=5)}`.
+
+**DeepAgents coverage**: ❌ — LangChain-Ollama config.
+
+---
+
+## AP-11: Subagents with no `tools` field inherit everything
+
+**Symptom**: you define `{"name": "planner", "description": "..."}` without `tools`. The planner somehow calls `web_search`.
+
+**Root cause**: if `tools` is not in the SubAgent spec, it inherits `default_tools` (the main agent's tool set). See `subagents.py:347`.
+
+**Fix**: always set `tools=[]` explicitly for roles that should have no custom tools. An empty list is different from an omitted key.
+
+**DeepAgents coverage**: ⚠️ be explicit — the default is permissive.

package/skills/building-with-deepagents/references/api-quick-reference.md

@@ -0,0 +1,184 @@
+<!-- SPDX-FileCopyrightText: 2025-2026 Tyrone Ross, Jr <46267523+tyroneross@users.noreply.github.com> | SPDX-License-Identifier: Apache-2.0 -->
+
+# DeepAgents API Quick Reference
+
+Live source paths and exact signatures. Always verify against the installed version (`pip show deepagents`) — these notes track v0.4.x.
+
+## create_deep_agent signature
+
+File: `deepagents/graph.py:217`
+
+```python
+def create_deep_agent(
+    model: str | BaseChatModel | None = None,
+    tools: Sequence[BaseTool | Callable | dict] | None = None,
+    *,
+    system_prompt: str | SystemMessage | None = None,
+    middleware: Sequence[AgentMiddleware] = (),
+    subagents: Sequence[SubAgent | CompiledSubAgent | AsyncSubAgent] | None = None,
+    skills: list[str] | None = None,
+    memory: list[str] | None = None,
+    permissions: list[FilesystemPermission] | None = None,
+    response_format: ResponseFormat | type | dict | None = None,
+    context_schema: type | None = None,
+    checkpointer: Checkpointer | None = None,
+    store: BaseStore | None = None,
+    backend: BackendProtocol | BackendFactory | None = None,
+    interrupt_on: dict[str, bool | InterruptOnConfig] | None = None,
+    debug: bool = False,
+    name: str | None = None,
+    cache: BaseCache | None = None,
+) -> CompiledStateGraph: ...
+```
+
+Returns a LangGraph `CompiledStateGraph`. Stream/invoke it with standard LangGraph APIs.
+
+## SubAgent TypedDict
+
+File: `deepagents/middleware/subagents.py:22`
+
+```python
+class SubAgent(TypedDict):
+    name: str                                      # Required
+    description: str                               # Required
+    system_prompt: str                             # Required
+
+    tools: NotRequired[Sequence[...]]              # Optional — inherits if omitted
+    model: NotRequired[str | BaseChatModel]        # Optional — per-agent model
+    middleware: NotRequired[list[AgentMiddleware]] # Optional — extra middleware
+    interrupt_on: NotRequired[dict[str, ...]]      # Optional — human-in-the-loop per tool
+    skills: NotRequired[list[str]]                 # Optional — paths to skill markdown
+    permissions: NotRequired[list[FilesystemPermission]]  # Optional
+```
+
+**Important**: if you pass `tools=[]` (empty list), subagent still gets middleware-provided tools (`write_todos`, `ls`, `read_file`, `write_file`, `edit_file`, `glob`, `grep`). Only your custom tools are restricted.
+
+## Kwargs worth knowing (often missed)
+
+Not every arg to `create_deep_agent` is obvious at a glance. These four trip up new builders:
+
+- **`backend`** — instance of `BackendProtocol` (usually `FilesystemBackend(root_dir=..., virtual_mode=True)`). Sandboxes the filesystem-middleware tools (`ls`/`read_file`/`write_file`/`edit_file`/`glob`/`grep`) so they operate inside `root_dir` instead of the whole disk. Always pass one in a local-app context — otherwise the agent can read/write anywhere the process can.
+
+- **`store`** — a LangGraph `BaseStore` (distinct from `checkpointer`). Checkpointer = per-thread conversation state. Store = cross-thread long-term memory (facts, documents, user profile). Pair `SqliteSaver` (checkpointer) with an in-process or file-backed store if you want the agent to remember across threads.
+
+- **`response_format`** — typed final output. Pass a Pydantic model, TypedDict, or JSON schema; the final assistant message is coerced to it and exposed via `agent.invoke(...)["response"]`. **Conflicts with `format: "json"`** at the model layer — don't combine the two. For an 8B local model, Pydantic-schema validation on structured output is flaky; consider using a larger model for that turn only.
+
+- **`interrupt_on`** — dict mapping tool name → bool or config. Causes the graph to pause before the named tool fires; the caller then `Command(resume=...)` after human approval. Requires a checkpointer to save the paused state.
+
+## Async vs sync
+
+The returned graph is dual-API. SSE bridges on ASGI (Starlette, FastAPI) should prefer async:
+
+```python
+async for event in agent.astream_events(input, config=config, version="v2"):
+    ...
+result = await agent.ainvoke(input, config=config)
+```
+
+On the subagent side, an `AsyncSubAgent` variant (see `deepagents/async_subagents.py`) exists for purely async subagent bodies. If your runtime mixes — sync HTTP server + async Ollama calls — LangChain's adapters handle the boundary, but you pay a thread-pool hop per LLM call. Match the transport to the agent code.
+
+## Default middleware stack
+
+File: `deepagents/graph.py:192-260` (build order). In order of injection for the main agent. **If this list disagrees with the installed source, trust the source** — this file is a snapshot; the middleware stack is the most volatile surface DeepAgents exposes.
+
+1. `TodoListMiddleware` → exposes `write_todos`
+2. `FilesystemMiddleware` (from `backend` arg) → `ls`, `read_file`, `write_file`, `edit_file`, `glob`, `grep`
+3. `ShellCommandMiddleware` → `execute` (shell command runner)
+4. `SkillsMiddleware` (if `skills=` passed) → loads markdown into system prompt
+5. `MemoryMiddleware` (if `memory=` passed) → loads `AGENTS.md`
+6. `SubAgentMiddleware` (if `subagents=` passed) → the `task` tool
+7. `SummarizationMiddleware` → context-window pruning
+8. `PatchToolCallsMiddleware` → cleans orphaned tool calls
+9. Any `middleware=` arg (custom)
+10. `_PermissionMiddleware` (appended last if `permissions=` passed)
+
+Subagents get a subset of this stack — see `subagents.py:660-667` for per-subagent assembly.
+
+## Streaming
+
+DeepAgents returns a LangGraph graph. Stream APIs:
+
+```python
+# Node-level (default in most example code)
+for chunk in agent.stream(input, config=config, stream_mode="updates"):
+    ...
+
+# Token-level (per-token from LLM)
+for chunk in agent.stream(input, config=config, stream_mode="messages"):
+    ...
+
+# Multi-mode — most useful for SSE bridges
+for mode, payload in agent.stream(input, config=config, stream_mode=["updates", "messages"]):
+    if mode == "updates": ...
+    elif mode == "messages": ...
+
+# Typed events — v2
+async for event in agent.astream_events(input, config=config, version="v2"):
+    kind = event["event"]
+    # on_chat_model_start / on_chat_model_stream / on_chat_model_end
+    # on_tool_start / on_tool_end / on_tool_error
+    # on_chain_start / on_chain_end
+```
+
+`astream_events(include_types=["chat_model","tool"])` drops chain-level noise — ~5× fewer events.
+
+## Checkpointing
+
+```python
+from langgraph.checkpoint.memory import MemorySaver       # volatile
+from langgraph.checkpoint.sqlite import SqliteSaver       # local persistent
+# pip install langgraph-checkpoint-sqlite
+
+checkpointer = SqliteSaver.from_conn_string(".app/checkpoints.db")
+agent = create_deep_agent(..., checkpointer=checkpointer)
+
+# Resume a thread
+config = {"configurable": {"thread_id": "research_001"}}
+result = agent.invoke(input, config=config)
+```
+
+Postgres and async variants exist as separate packages (`langgraph-checkpoint-postgres`).
+
+## Interrupts (human-in-the-loop)
+
+```python
+subagent = {
+    "name": "executor",
+    ...,
+    "interrupt_on": {"python_exec": True},  # pause before every python_exec call
+}
+# Or full InterruptOnConfig for per-arg rules.
+```
+
+On interrupt, `astream` raises or yields an interrupt event. The UI approves/rejects, then:
+
+```python
+from langgraph.types import Command
+agent.invoke(Command(resume="approved"), config=config)
+```
+
+## Per-agent model routing
+
+`SubAgent["model"]` can be:
+- `"openai:gpt-4o-mini"` → parsed as `provider:model-name`
+- A `BaseChatModel` instance → used directly (e.g. a pre-configured `ChatOllama`)
+
+If omitted, inherits the main agent's model.
+
+## Common imports
+
+```python
+from deepagents import create_deep_agent
+from deepagents.backends import FilesystemBackend
+from deepagents.middleware.subagents import SubAgent, CompiledSubAgent
+# Optional:
+from deepagents.permissions import FilesystemPermission
+```
+
+## Verifying your version
+
+```bash
+python3 -c "import deepagents, os; print(deepagents.__version__ if hasattr(deepagents, '__version__') else 'unknown'); print(os.path.dirname(deepagents.__file__))"
+```
+
+Then read the actual `graph.py` and `middleware/subagents.py` — this reference may be stale.

package/skills/capabilities/SKILL.md

@@ -0,0 +1,91 @@
+---
+name: build-loop:capabilities
+description: Invoked by Phase 1 Assess to populate `state.json.activeCapabilities[<phase>]` with ≤8 relevant entries via plugin-surface collapse + trigger-aware demotion. Keeps the orchestrator below the empirical tool-selection ceiling. Not user-callable; orchestrator-internal.
+user-invocable: false
+model: sonnet
+tools: ["Read", "Bash"]
+---
+
+<!-- SPDX-FileCopyrightText: 2025-2026 Tyrone Ross, Jr <46267523+tyroneross@users.noreply.github.com> | SPDX-License-Identifier: Apache-2.0 -->
+
+# Capability shortlist
+
+Anthropic's Tool Search guidance recommends <=8 candidates per dispatch. The build-loop repo currently exposes ~112 surfaces (20 agents + 34 skills + 14 commands + 5 hooks + ~39 scripts) and no build-loop MCP server. Without filtering, the orchestrator chooses from a haystack on every phase.
+
+This skill is a deterministic, structured matcher: **(phase, intent text) → ≤8 capability entries**, drawn from the registry written by `scripts/build_capability_registry.py`.
+
+## Inputs
+
+| Input | Type | Required | Notes |
+|---|---|---|---|
+| `phase` | int (1–6) | yes | Phase number from build-loop's 5-phase loop (+1 Learn). |
+| `intent` | string | yes | Free-text description of the goal/task for this phase. |
+| `kind` | optional list | no | Filter by `agent | skill | command | hook | mcp_tool | script`. |
+| `workdir` | optional path | no | Repo root containing `.build-loop/capability-registry.json`. Defaults to `$PWD`. |
+
+## Phase → category routing
+
+Phases bias the shortlist toward categories the loop typically uses there:
+
+| Phase | Primary categories | Secondary |
+|---|---|---|
+| 1 Assess | architecture, planning, memory, observability | meta |
+| 2 Plan | planning, architecture, validation | meta |
+| 3 Execute | execution, debugging, ux-ui, deployment | testing |
+| 4 Review | validation, debugging, ux-ui, optimization | testing |
+| 5 Iterate | debugging, execution, validation | architecture |
+| 6 Learn | meta, memory, optimization | validation |
+
+When `phase` is outside 1–6, fall back to scoring purely on intent keyword matches.
+
+## Procedure
+
+1. Read `<workdir>/.build-loop/capability-registry.json`. If it doesn't exist, run:
+   ```bash
+   python3 <workdir>/scripts/build_capability_registry.py --workdir "<workdir>"
+   ```
+   Then re-read.
+2. Lowercase the `intent` string. Tokenize on whitespace and punctuation.
+3. For each registry entry, compute a relevance score:
+   - **+5** for every intent token that appears in `name`, `description`, or `triggers[]`.
+   - **+3** if the entry's `category` is in the phase's primary list.
+   - **+1** if the entry's `category` is in the phase's secondary list.
+   - **+1** if the entry's `tier` is `sonnet` or `opus` (preferred over `n/a` for substantive work).
+4. Apply optional `kind` filter.
+5. Sort by score descending, then by `name` ascending for stable tie-breaks.
+6. Return the top 8 with reason tokens (which intent words and which categories matched).
+
+## Output shape
+
+```json
+{
+  "phase": 1,
+  "intent": "<echoed>",
+  "shortlist_size": 8,
+  "registry_total": 113,
+  "results": [
+    {
+      "name": "<capability name>",
+      "kind": "agent|skill|command|hook|mcp_tool|script",
+      "category": "<routing label>",
+      "score": 12,
+      "reasons": ["matched_intent_token: scan", "matched_category: architecture"],
+      "source_path": "agents/architecture-scout.md",
+      "description": "<truncated to 240 chars>"
+    }
+  ]
+}
+```
+
+`shortlist_size` is always ≤ 8 (the registry's own size cap matches Anthropic's Tool Search guidance). When fewer than 8 entries score above 0, return all that scored. When zero match, return the top 4 by phase-category match alone — the orchestrator should never receive an empty shortlist if the registry is non-empty.
+
+## Caching
+
+Write the result to `<workdir>/.build-loop/state.json.activeCapabilities[]` with `{phase, intent, shortlist: [...], generated_at}`. The orchestrator's Phase 1 Assess step reads this directly without re-running the skill if `intent` and `phase` haven't changed.
+
+## What this skill does NOT do
+
+- Execute any of the capabilities it surfaces. It returns a shortlist; the orchestrator dispatches.
+- Mutate any source file. Read-only on the repo; write-only to `state.json` (single field).
+- Network-call. Runs purely against the local registry.
+- Disambiguate between two capabilities with the same name in different `kind` namespaces — both are surfaced and the orchestrator decides.