@pikaa-ai/pikaa 0.2.5 → 0.3.0

package/skills/phylogenetics/scripts/phylogenetic_analysis.py

@@ -0,0 +1,272 @@
+"""
+Phylogenetic Analysis Pipeline
+===============================
+Complete workflow: MAFFT alignment → IQ-TREE tree → ETE3 visualization.
+
+Requirements:
+    conda install -c bioconda mafft iqtree
+    uv pip install ete3
+
+Usage:
+    python phylogenetic_analysis.py sequences.fasta --type nt --threads 4
+    python phylogenetic_analysis.py proteins.fasta --type aa --fasttree
+"""
+
+import argparse
+import os
+import subprocess
+import sys
+from pathlib import Path
+
+
+def check_dependencies():
+    """Check that required tools are installed."""
+    tools = {
+        "mafft": "conda install -c bioconda mafft",
+        "iqtree2": "conda install -c bioconda iqtree",
+    }
+    missing = []
+    for tool, install_cmd in tools.items():
+        result = subprocess.run(["which", tool], capture_output=True)
+        if result.returncode != 0:
+            missing.append(f"  {tool}: {install_cmd}")
+
+    if missing:
+        print("Missing dependencies:")
+        for m in missing:
+            print(m)
+        sys.exit(1)
+    print("All dependencies found.")
+
+
+def count_sequences(fasta_file: str) -> int:
+    """Count sequences in a FASTA file."""
+    with open(fasta_file) as f:
+        return sum(1 for line in f if line.startswith('>'))
+
+
+def run_mafft(input_fasta: str, output_fasta: str, n_threads: int = 4,
+               method: str = "auto") -> str:
+    """Run MAFFT multiple sequence alignment."""
+    n_seqs = count_sequences(input_fasta)
+    print(f"MAFFT: Aligning {n_seqs} sequences...")
+
+    # Auto-select method based on dataset size
+    if method == "auto":
+        if n_seqs <= 200:
+            cmd = ["mafft", "--localpair", "--maxiterate", "1000",
+                   "--thread", str(n_threads), "--inputorder", input_fasta]
+        elif n_seqs <= 1000:
+            cmd = ["mafft", "--auto", "--thread", str(n_threads),
+                   "--inputorder", input_fasta]
+        else:
+            cmd = ["mafft", "--fftns", "--thread", str(n_threads),
+                   "--inputorder", input_fasta]
+    else:
+        cmd = ["mafft", f"--{method}", "--thread", str(n_threads),
+               "--inputorder", input_fasta]
+
+    with open(output_fasta, 'w') as out:
+        result = subprocess.run(cmd, stdout=out, stderr=subprocess.PIPE, text=True)
+
+    if result.returncode != 0:
+        raise RuntimeError(f"MAFFT failed:\n{result.stderr[:500]}")
+
+    print(f"  Alignment complete → {output_fasta}")
+    return output_fasta
+
+
+def run_iqtree(aligned_fasta: str, prefix: str, seq_type: str = "nt",
+                bootstrap: int = 1000, n_threads: int = 4,
+                outgroup: str = None) -> str:
+    """Run IQ-TREE 2 phylogenetic inference."""
+    print(f"IQ-TREE 2: Building maximum likelihood tree...")
+
+    cmd = [
+        "iqtree2",
+        "-s", aligned_fasta,
+        "--prefix", prefix,
+        "-m", "TEST",           # Auto model selection
+        "-B", str(bootstrap),   # Ultrafast bootstrap
+        "-T", str(n_threads),
+        "--redo",
+        "-alrt", "1000",        # SH-aLRT test
+    ]
+
+    if outgroup:
+        cmd += ["-o", outgroup]
+
+    result = subprocess.run(cmd, capture_output=True, text=True)
+
+    if result.returncode != 0:
+        raise RuntimeError(f"IQ-TREE failed:\n{result.stderr[:500]}")
+
+    tree_file = f"{prefix}.treefile"
+
+    # Extract best model from log
+    log_file = f"{prefix}.log"
+    if os.path.exists(log_file):
+        with open(log_file) as f:
+            for line in f:
+                if "Best-fit model" in line:
+                    print(f"  {line.strip()}")
+
+    print(f"  Tree saved → {tree_file}")
+    return tree_file
+
+
+def run_fasttree(aligned_fasta: str, output_tree: str, seq_type: str = "nt") -> str:
+    """Run FastTree (faster alternative for large datasets)."""
+    print("FastTree: Building approximate ML tree (faster)...")
+
+    if seq_type == "nt":
+        cmd = ["FastTree", "-nt", "-gtr", "-gamma", aligned_fasta]
+    else:
+        cmd = ["FastTree", "-lg", "-gamma", aligned_fasta]
+
+    with open(output_tree, 'w') as out:
+        result = subprocess.run(cmd, stdout=out, stderr=subprocess.PIPE, text=True)
+
+    if result.returncode != 0:
+        raise RuntimeError(f"FastTree failed:\n{result.stderr[:500]}")
+
+    print(f"  Tree saved → {output_tree}")
+    return output_tree
+
+
+def visualize_tree(tree_file: str, output_png: str, outgroup: str = None) -> None:
+    """Visualize the phylogenetic tree with ETE3."""
+    try:
+        from ete3 import Tree, TreeStyle, NodeStyle
+    except ImportError as exc:
+        # TreeStyle and NodeStyle live in ete3's Qt-backed treeview module, so
+        # this also fires when ete3 itself imported fine but PyQt5 is missing.
+        print(f"ETE3 rendering unavailable ({exc}). Skipping visualization.")
+        print("  Install: uv pip install ete3 PyQt5")
+        return
+
+    t = Tree(tree_file)
+
+    # Root the tree
+    if outgroup and outgroup in [leaf.name for leaf in t.get_leaves()]:
+        t.set_outgroup(outgroup)
+        print(f"  Rooted at outgroup: {outgroup}")
+    else:
+        # Midpoint rooting
+        t.set_outgroup(t.get_midpoint_outgroup())
+        print("  Applied midpoint rooting")
+
+    # Style
+    ts = TreeStyle()
+    ts.show_leaf_name = True
+    ts.show_branch_support = True
+    ts.mode = "r"  # rectangular
+
+    try:
+        t.render(output_png, tree_style=ts, w=800, units="px")
+        print(f"  Visualization saved → {output_png}")
+    except Exception as e:
+        print(f"  Visualization failed (display issue?): {e}")
+        # Save tree in Newick format as fallback
+        rooted_nwk = output_png.replace(".png", "_rooted.nwk")
+        t.write(format=1, outfile=rooted_nwk)
+        print(f"  Rooted tree saved → {rooted_nwk}")
+
+
+def tree_summary(tree_file: str) -> dict:
+    """Print summary statistics for the tree."""
+    try:
+        from ete3 import Tree
+        t = Tree(tree_file)
+        t.set_outgroup(t.get_midpoint_outgroup())
+
+        leaves = t.get_leaves()
+        branch_lengths = [n.dist for n in t.traverse() if n.dist > 0]
+
+        stats = {
+            "n_taxa": len(leaves),
+            "total_branch_length": sum(branch_lengths),
+            "mean_branch_length": sum(branch_lengths) / len(branch_lengths) if branch_lengths else 0,
+            "max_branch_length": max(branch_lengths) if branch_lengths else 0,
+        }
+
+        print("\nTree Summary:")
+        for k, v in stats.items():
+            if isinstance(v, float):
+                print(f"  {k}: {v:.6f}")
+            else:
+                print(f"  {k}: {v}")
+
+        return stats
+    except Exception as e:
+        print(f"Could not compute tree stats: {e}")
+        return {}
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Phylogenetic analysis pipeline")
+    parser.add_argument("input", help="Input FASTA file (unaligned)")
+    parser.add_argument("--type", choices=["nt", "aa"], default="nt",
+                        help="Sequence type: nt (nucleotide) or aa (amino acid)")
+    parser.add_argument("--threads", type=int, default=4, help="Number of threads")
+    parser.add_argument("--bootstrap", type=int, default=1000,
+                        help="Bootstrap replicates for IQ-TREE")
+    parser.add_argument("--fasttree", action="store_true",
+                        help="Use FastTree instead of IQ-TREE (faster, less accurate)")
+    parser.add_argument("--outgroup", help="Outgroup taxon name for rooting")
+    parser.add_argument("--mafft-method", default="auto",
+                        choices=["auto", "linsi", "einsi", "fftnsi", "fftns"],
+                        help="MAFFT alignment method")
+    parser.add_argument("--output-dir", default="phylo_results",
+                        help="Output directory")
+
+    args = parser.parse_args()
+
+    # Setup
+    os.makedirs(args.output_dir, exist_ok=True)
+    prefix = os.path.join(args.output_dir, Path(args.input).stem)
+
+    print("=" * 60)
+    print("Phylogenetic Analysis Pipeline")
+    print("=" * 60)
+    print(f"Input: {args.input}")
+    print(f"Sequence type: {args.type}")
+    print(f"Output dir: {args.output_dir}")
+
+    # Step 1: Multiple Sequence Alignment
+    print("\n[Step 1/3] Multiple Sequence Alignment (MAFFT)")
+    aligned = run_mafft(
+        args.input,
+        f"{prefix}_aligned.fasta",
+        n_threads=args.threads,
+        method=args.mafft_method
+    )
+
+    # Step 2: Tree Inference
+    print("\n[Step 2/3] Tree Inference")
+    if args.fasttree:
+        tree_file = run_fasttree(aligned, f"{prefix}.tree", seq_type=args.type)
+    else:
+        tree_file = run_iqtree(
+            aligned, prefix,
+            seq_type=args.type,
+            bootstrap=args.bootstrap,
+            n_threads=args.threads,
+            outgroup=args.outgroup
+        )
+
+    # Step 3: Visualization
+    print("\n[Step 3/3] Visualization (ETE3)")
+    visualize_tree(tree_file, f"{prefix}_tree.png", outgroup=args.outgroup)
+    tree_summary(tree_file)
+
+    print("\n" + "=" * 60)
+    print("Analysis complete!")
+    print(f"Key outputs:")
+    print(f"  Aligned sequences: {aligned}")
+    print(f"  Tree file: {tree_file}")
+    print(f"  Visualization: {prefix}_tree.png")
+
+
+if __name__ == "__main__":
+    main()

package/skills/pi-agent/SKILL.md

@@ -0,0 +1,83 @@
+---
+name: pi-agent
+description: Build with and use Pi, the minimal terminal coding harness. Use for installing Pi, configuring providers/models/settings/environment variables, creating Pi skills/extensions/packages/themes/prompt templates, embedding Pi through the SDK, integrating over RPC or JSON event streams, parsing sessions, running local models through the llama.cpp router, developing custom Pi providers and TUI components, or using ecosystem packages such as pi-subagents (delegation/orchestration), pi-mcp-adapter (MCP servers), pi-interview (interactive forms), and pi-web-access (web search, fetching, video understanding).
+license: MIT
+compatibility: Requires Node.js >= 22.19 and npm for Pi CLI and SDK usage. Pi package name is @earendil-works/pi-coding-agent.
+metadata:
+  version: "1.3"
+  skill-author: K-Dense Inc.
+---
+
+# Pi Agent
+
+Use this skill when the user wants to operate Pi or build on top of Pi. Pi is a minimal terminal coding harness extended through TypeScript extensions, skills, prompt templates, themes, packages, custom models/providers, SDK integrations, RPC mode, JSON event streams, and TUI components.
+
+## First Decision
+
+Pick the reference before answering or coding:
+
+| User intent | Read |
+|---|---|
+| What Pi is, docs map, install methods | `references/overview.md` |
+| Install, authenticate, first run | `references/quickstart.md` |
+| Day-to-day CLI usage, commands, modes, flags, project trust | `references/usage.md` |
+| Provider auth, API keys, cloud provider setup | `references/providers.md` |
+| Custom model entries, local models, proxies, compat flags | `references/models.md` |
+| Local llama.cpp router, `/llama`, model download/load | `references/llama-cpp.md` |
+| Settings keys and defaults | `references/settings.md` |
+| `PI_*` and other environment variables | `references/environment-variables.md` |
+| Extension development, custom tools, events, commands | `references/extensions.md` |
+| Custom provider implementation, OAuth, custom streaming | `references/custom-provider.md` |
+| Embed Pi in Node/TypeScript | `references/sdk.md` |
+| Integrate from another process/language | `references/rpc.md` |
+| Consume JSONL event output | `references/json.md` |
+| Build terminal UI components | `references/tui.md` |
+| Package extensions/skills/prompts/themes | `references/packages.md` |
+| Delegate to subagents, chains, parallel runs, orchestration | `references/pi-subagents.md` |
+| Connect MCP servers, MCP tool discovery/config | `references/pi-mcp-adapter.md` |
+| Interactive interview forms, structured user input | `references/pi-interview.md` |
+| Web search, URL/PDF/repo fetching, video understanding | `references/pi-web-access.md` |
+| Author Pi skills | `references/skills.md` |
+| Prompt templates or themes | `references/prompt-templates.md`, `references/themes.md` |
+| Sessions, branching, compaction, parsing JSONL | `references/sessions.md`, `references/compaction.md`, `references/session-format.md` |
+| Security, sandboxing, trust | `references/security.md`, `references/containerization.md` |
+| Keyboard or terminal issues | `references/keybindings.md`, `references/terminal-setup.md`, `references/tmux.md`, `references/windows.md`, `references/termux.md`, `references/shell-aliases.md` |
+| Working on Pi itself | `references/development.md` |
+
+## Build-On-Pi Defaults
+
+Prefer the SDK for Node/TypeScript apps that need type safety, direct state access, in-process custom tools/extensions, or custom resource loading. Use `createAgentSession()` for a single stable session; use `createAgentSessionRuntime()` when the app must replace sessions through new/resume/fork/clone/import flows. Auth and model lookup go through `ModelRuntime.create()`.
+
+Prefer RPC mode when the client is not Node.js, needs process isolation, or wants a language-agnostic JSONL protocol. Start with `pi --mode rpc --no-session` for stateless subprocess integration, then add session flags when persistence matters. Split records on `\n` only — Node `readline` is not protocol-compliant.
+
+Prefer JSON mode for one-shot command-line pipelines that only need streamed events, not bidirectional control: `pi --mode json "prompt"`.
+
+Use extensions for Pi-native behavior: custom tools, command handlers, event hooks, provider registration, custom compaction, path protection, project trust policy, UI prompts, widgets, and TUI components.
+
+Use packages when sharing or installing reusable extensions, skills, prompt templates, or themes across machines or projects.
+
+## Safety Defaults
+
+Pi is local and not sandboxed by default. Treat extensions, packages, skills, shell commands, and project-local `.pi` resources as code with the permissions of the Pi process. Project trust only guards which project inputs load — it is not a sandbox. For untrusted repos or unattended automation, isolate with Docker, OpenShell, Gondolin, a VM, or a remote sandbox.
+
+Do not store secrets in project files. Prefer env vars, `~/.pi/agent/auth.json`, OAuth via `/login`, or command-backed secret lookups in `models.json`/provider config.
+
+## Common Commands
+
+```bash
+npm install -g --ignore-scripts @earendil-works/pi-coding-agent
+pi
+pi -p "Summarize this codebase"
+pi --mode json "List files"
+pi --mode rpc --no-session
+pi --provider anthropic --model claude-sonnet-4-5
+pi --model sonnet:high "Solve this complex problem"
+pi --tools read,grep,find,ls -p "Review this repository"
+pi --tui-mode fullscreen
+pi install npm:pi-subagents
+pi update --all
+```
+
+## Source Coverage
+
+These references summarize the Pi documentation at `https://pi.dev/docs/latest` and every docs page found under it, as of Pi **0.84.2** (docs source: `packages/coding-agent/docs/` in `https://github.com/earendil-works/pi`, formerly `pi-mono`). They also cover the package pages for `pi-subagents`, `pi-mcp-adapter`, `pi-interview`, and `pi-web-access` at `https://pi.dev/packages/`, cross-checked against the published npm READMEs and package docs (`pi-web-access` 0.22.0, `pi-mcp-adapter` 2.25.0, `pi-subagents` 0.49.0, `pi-interview` 0.11.0). When exact API behavior matters, prefer the cited reference page and inspect installed TypeScript definitions under `node_modules/@earendil-works/pi-coding-agent/dist/` and `node_modules/@earendil-works/pi-ai/dist/`.

package/skills/pi-agent/references/compaction.md

@@ -0,0 +1,76 @@
+# Compaction and Branch Summarization
+
+Source: https://pi.dev/docs/latest/compaction
+
+Pi has two summarization mechanisms that share the same structured summary format and track file operations cumulatively.
+
+| Mechanism | Trigger | Purpose |
+|---|---|---|
+| Compaction | context exceeds threshold, or `/compact` | Summarize old messages to free context |
+| Branch summarization | `/tree` navigation | Preserve context when switching branches |
+
+Both use fresh routing session IDs and, where the provider supports it, disable prompt-cache writes because these one-off prompts are unlikely to be reused.
+
+## Auto-Compaction
+
+Triggers when `contextTokens > contextWindow - reserveTokens`. Defaults: `reserveTokens` 16384, `keepRecentTokens` 20000, configured under `compaction` in global or project settings. `/compact [instructions]` works even with auto-compaction disabled.
+
+Steps: walk backwards from the newest message accumulating token estimates until `keepRecentTokens` is reached (the cut point) → collect messages from the previous kept boundary (or session start) to the cut point → summarize with the structured format, passing any previous summary as iterative context → append a `CompactionEntry` → rebuild the context for the next request as summary plus messages from `firstKeptEntryId`.
+
+On repeated compactions the summarized span starts at the previous compaction's kept boundary (`firstKeptEntryId`), not at the compaction entry, falling back to the entry after the previous compaction when that kept entry is not on the path. This re-includes messages that survived the earlier pass. `tokensBefore` is recalculated from the rebuilt context before writing the new entry.
+
+Valid cut points: user messages, assistant messages, bash execution messages, and custom messages (`custom_message`, `branch_summary`). Pi never cuts at tool results.
+
+## Split Turns
+
+A turn starts with a user message and includes all assistant responses and tool calls until the next user message. When a single turn exceeds `keepRecentTokens`, the cut lands mid-turn at an assistant message (`isSplitTurn`). Pi then generates two summaries — a history summary for previous context and a turn-prefix summary for the early part of the split turn — and merges them.
+
+## Branch Summarization
+
+On `/tree` navigation to a different branch: find the deepest common ancestor, walk from the old leaf back to it, include messages up to the token budget newest-first, summarize, and append a `BranchSummaryEntry` at the navigation point — the summary lands on the destination branch's new leaf, not on the branch being left.
+
+Both mechanisms extract file operations from the tool calls being summarized **and** from previous compaction/branch-summary `details`, so read/modified file tracking accumulates across passes.
+
+## Entry Shapes
+
+`CompactionEntry`: `type`, `id`, `parentId`, `timestamp`, `summary`, `firstKeptEntryId`, `tokensBefore`, optional `usage` (LLM usage that generated the summary; counted in session totals), optional `fromHook` (legacy name for "provided by extension"), optional `details`.
+
+`BranchSummaryEntry`: same plus `fromId` instead of `firstKeptEntryId`.
+
+Default `details` is `{ readFiles: string[], modifiedFiles: string[] }`; extensions may store any JSON-serializable structure. Newer harness-generated compactions also embed `retainedTail` — see `references/session-format.md`.
+
+## Summary Format
+
+Sections: `## Goal`, `## Constraints & Preferences`, `## Progress` (Done / In Progress / Blocked), `## Key Decisions`, `## Next Steps`, `## Critical Context`, then `<read-files>` and `<modified-files>` blocks.
+
+## Message Serialization
+
+`serializeConversation()` renders messages as `[User]:`, `[Assistant thinking]:`, `[Assistant]:`, `[Assistant tool calls]:`, `[Tool result]:` lines so the model does not treat the input as a conversation to continue. Tool results are truncated to 2000 characters during serialization, with a marker showing how many characters were dropped — `read` and `bash` results are usually the largest contributors to context.
+
+## Extension Hooks
+
+`session_before_compact` receives `{ preparation, branchEntries, customInstructions, reason, willRetry, signal }`. `preparation` exposes `messagesToSummarize`, `turnPrefixMessages`, `previousSummary`, `fileOps`, `tokensBefore`, `firstKeptEntryId`, and `settings`; `reason` is `"manual"`, `"threshold"`, or `"overflow"`; `willRetry` indicates overflow recovery. Return `{ cancel: true }` or `{ compaction: { summary, firstKeptEntryId, tokensBefore, usage?, details? } }`.
+
+To summarize with your own model, convert messages first:
+
+```ts
+import { convertToLlm, serializeConversation } from "@earendil-works/pi-coding-agent";
+
+const text = serializeConversation(convertToLlm(preparation.messagesToSummarize));
+```
+
+`session_before_tree` receives `{ preparation, signal }` with `targetId`, `oldLeafId`, `commonAncestorId`, `entriesToSummarize`, and `userWantsSummary`. It always fires, whether or not the user chose to summarize. Return `{ cancel: true }` to cancel navigation, or `{ summary: { summary, usage?, details? } }` (used only when `userWantsSummary`).
+
+For direct programmatic summarization, `generateSummary()` returns the text and `generateSummaryWithUsage()` returns `{ text, usage }`.
+
+## Settings
+
+```json
+{
+  "compaction": {
+    "enabled": true,
+    "reserveTokens": 16384,
+    "keepRecentTokens": 20000
+  }
+}
+```

package/skills/pi-agent/references/containerization.md

@@ -0,0 +1,80 @@
+# Containerization
+
+Source: https://pi.dev/docs/latest/containerization
+
+Pi runs with all permissions by default. Two general approaches: run the whole `pi` process inside an isolated environment, or run `pi` on the host and route tool execution into an isolated environment.
+
+| Pattern | What is isolated | Best for | Notes |
+|---|---|---|---|
+| Gondolin extension | Built-in tools and `!` commands | Local micro-VM isolation while keeping auth on host | `examples/extensions/gondolin/` |
+| Plain Docker | Whole `pi` process | Simplest local container boundary | Provider API keys enter the container |
+| OpenShell | Whole `pi` process | Local or remote policy-controlled sandbox | Requires an OpenShell gateway |
+
+Extensions run wherever the `pi` process runs. If host Pi routes built-ins into a VM, other custom extension tools still run on the host unless they delegate too.
+
+## Gondolin
+
+[Gondolin](https://github.com/earendil-works/gondolin) is a local Linux micro-VM.
+
+```bash
+cp -R packages/coding-agent/examples/extensions/gondolin ~/.pi/agent/extensions/gondolin
+cd ~/.pi/agent/extensions/gondolin
+npm install --ignore-scripts
+
+cd /path/to/project
+pi -e ~/.pi/agent/extensions/gondolin
+```
+
+The extension mounts the host cwd at `/workspace` in the VM and overrides `read`, `write`, `edit`, `bash`, `grep`, `find`, and `ls`. User `!` commands are routed into the VM as well, and file changes under `/workspace` write through to the host.
+
+Requirements: Node.js >= 23.6.0 for `@earendil-works/gondolin`, plus QEMU installed through your package manager.
+
+## Plain Docker
+
+`Dockerfile.pi`:
+
+```dockerfile
+FROM node:24-bookworm-slim
+
+RUN apt-get update \
+  && apt-get install -y --no-install-recommends bash ca-certificates git ripgrep \
+  && rm -rf /var/lib/apt/lists/*
+RUN npm install -g --ignore-scripts @earendil-works/pi-coding-agent
+
+WORKDIR /workspace
+ENTRYPOINT ["pi"]
+```
+
+```bash
+docker build -t pi-sandbox -f Dockerfile.pi .
+
+docker run --rm -it \
+  -e ANTHROPIC_API_KEY \
+  -v "$PWD:/workspace" \
+  -v pi-agent-home:/root/.pi/agent \
+  pi-sandbox
+```
+
+`-v "$PWD:/workspace"` means reads and writes inside `/workspace` affect host files directly. Use a named volume for `/root/.pi/agent` if you want container-local settings and sessions — mounting host `~/.pi/agent` exposes host auth and session files to the container.
+
+## OpenShell
+
+[NVIDIA OpenShell](https://docs.nvidia.com/openshell/about/overview) provides a policy-controlled sandbox with filesystem, process, network, credential, and inference controls. It runs sandboxes through a local gateway backed by Docker, Podman, or a VM runtime, or through a remote Kubernetes gateway. Every sandbox requires an active gateway:
+
+```bash
+openshell gateway add <gateway-url> --name <name>
+openshell gateway select <name>
+
+openshell sandbox create --name pi-sandbox --from pi -- pi
+```
+
+The whole `pi` process runs inside the sandbox, so built-in tools, `!` commands, and extension tools all execute inside the boundary.
+
+Remote gateways do not bind-mount host project files, so sandbox writes are not reflected on your machine. Clone the repository inside the sandbox or transfer files explicitly:
+
+```bash
+openshell sandbox upload pi-sandbox ./repo /workspace
+openshell sandbox download pi-sandbox /workspace/repo ./repo-out
+```
+
+OpenShell providers can keep raw model API keys outside the sandbox: with inference routing configured, code inside the sandbox calls `https://inference.local` and the gateway injects provider credentials upstream. Point Pi at the corresponding OpenAI-compatible or Anthropic-compatible endpoint to use that route.

package/skills/pi-agent/references/custom-provider.md

@@ -0,0 +1,131 @@
+# Custom Providers
+
+Source: https://pi.dev/docs/latest/custom-provider
+
+Extensions register providers with `pi.registerProvider()` for proxies, private deployments, OAuth/SSO, and non-standard streaming APIs. Two forms exist: a complete pi-ai `Provider` (preferred when you need custom authentication, filtering, refresh, or streaming) and the legacy provider-config object. `models.json` overrides compose **above** registered native providers.
+
+## Complete Provider Form
+
+```ts
+import { createProvider, openAICompletionsApi } from "@earendil-works/pi-ai";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+export default function (pi: ExtensionAPI) {
+  pi.registerProvider(createProvider({
+    id: "native-local",
+    name: "Native Local",
+    baseUrl: "http://localhost:8080/v1",
+    auth: {
+      apiKey: {
+        name: "Local server API key",
+        async login(interaction) {
+          return { type: "api_key", key: await interaction.prompt({ type: "secret", message: "API key" }) };
+        },
+        async resolve({ credential }) {
+          return credential?.key ? { auth: { apiKey: credential.key }, source: "stored API key" } : undefined;
+        },
+      },
+    },
+    models: [],
+    api: openAICompletionsApi(),
+  }));
+}
+```
+
+The object form accepts a complete `Provider`, including native `auth`, `getModels`, `refreshModels`, `filterModels`, `stream`, and `streamSimple`.
+
+## Legacy Config Form
+
+```ts
+// Override baseUrl and/or headers only — existing models are preserved
+pi.registerProvider("anthropic", { baseUrl: "https://proxy.example.com" });
+pi.registerProvider("openai", { headers: { "X-Custom-Header": "value" } });
+
+// New provider with models — replaces all existing models for that provider
+pi.registerProvider("my-provider", {
+  name: "My Provider",
+  baseUrl: "https://api.example.com",
+  apiKey: "$MY_API_KEY",
+  api: "openai-completions",
+  models: [{
+    id: "my-model",
+    name: "My Model",
+    reasoning: false,
+    input: ["text", "image"],
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 128000,
+    maxTokens: 4096,
+  }],
+});
+```
+
+Use an **async extension factory** for dynamic model discovery so models are registered before startup finishes and are visible to `pi --list-models`. Dynamic providers can also implement `refreshModels({ signal, store, ... })`; Pi calls it during model refresh and publishes the result synchronously. Persist through `context.store` only when the catalog should survive — live servers such as llama.cpp can ignore it.
+
+`pi.unregisterProvider(name)` removes that provider's dynamic models, API key fallback, OAuth registration, and custom stream handlers, restoring overridden built-in behavior. Calls made after the initial load phase take effect immediately — no `/reload`.
+
+## API Types
+
+`anthropic-messages`, `openai-completions`, `openai-responses`, `azure-openai-responses`, `openai-codex-responses`, `mistral-conversations`, `google-generative-ai`, `google-vertex`, `bedrock-converse-stream`.
+
+Most OpenAI-compatible providers work with `openai-completions`; use model-level `thinkingLevelMap` for thinking levels and `compat` for quirks (full flag list in `references/models.md`). `xhigh` and `max` are opt-in and require non-null map entries. Mistral moved from `openai-completions` to `mistral-conversations` (native Mistral Chat Completions streaming) — use the latter for native Mistral models.
+
+## Auth Header and Secrets
+
+`authHeader: true` adds `Authorization: Bearer <apiKey>`; the key is resolved per request and an explicit request `Authorization` header wins. `apiKey` and custom header values use the same syntax as `models.json`: leading `!command` executes for the whole value, `$ENV`/`${ENV}` interpolate, `$$` and `$!` escape literals.
+
+## OAuth
+
+```ts
+oauth: {
+  name: "Corporate AI (SSO)",
+  async login(callbacks: OAuthLoginCallbacks): Promise<OAuthCredentials>,
+  async refreshToken(credentials: OAuthCredentials, signal: AbortSignal): Promise<OAuthCredentials>,
+  getApiKey(credentials: OAuthCredentials): string,
+}
+```
+
+`OAuthLoginCallbacks`: `onAuth({ url })` (open in browser), `onDeviceCode({ userCode, verificationUri, intervalSeconds?, expiresInSeconds? })`, `onProgress?(message)`, `onPrompt({ message }): Promise<string>`, `onSelect({ message, options: { id, label }[] }): Promise<string | undefined>`.
+
+`OAuthCredentials` is `{ refresh, access, expires }` (expiry in ms), persisted in `~/.pi/agent/auth.json`. Users authenticate with `/login <provider-name>`. `refreshToken` receives an `AbortSignal` — pass it to blocking I/O and call `signal.throwIfAborted()` early.
+
+## Custom Streaming
+
+Implement `streamSimple(model, context, options?)` returning an `AssistantMessageEventStream` from `createAssistantMessageEventStream()`. Initialize an `AssistantMessage` (`role`, `content: []`, `api`, `provider`, `model`, zeroed `usage`, `stopReason: "pending"`, `timestamp`), then:
+
+1. `stream.push({ type: "start", partial: output })`
+2. Content events, tracking `contentIndex` per block: `text_start`, `text_delta`, `text_end`, `thinking_start`, `thinking_delta`, `thinking_end`, `toolcall_start`, `toolcall_delta`, `toolcall_end`
+3. `stream.push({ type: "done", reason, message })` or `{ type: "error", reason, error }`, then `stream.end()`
+
+`stopReason: "pending"` marks the partial message; set a terminal reason before pushing `done` (throw for `"error"`/`"aborted"`). Every event carries `partial` with the current `AssistantMessage` state — mutate `output.content` as data arrives and pass `output`. Tool calls accumulate JSON deltas, parse into `{ id, name, arguments }`, and finish with `toolcall_end` carrying the full `toolCall`. Update usage from the API response and call `calculateCost(model, output.usage)`. Register with `streamSimple` on the provider config.
+
+Reference implementations in `packages/ai/src/providers/`: `anthropic.ts`, `mistral.ts`, `openai-completions.ts`, `openai-responses.ts`, `google.ts`, `amazon-bedrock.ts`.
+
+## Context Overflow Errors
+
+Pi auto-recovers from context overflow by compacting and retrying once, but only when it recognizes the failure: `stopReason === "error"` and `errorMessage` matching a known pattern (see `packages/ai/src/utils/overflow.ts`). If your provider's message is unrecognized, normalize it from the same extension with a `message_end` handler so `errorMessage` starts with a recognized phrase — `context_length_exceeded` is the safest:
+
+```ts
+pi.on("message_end", (event, ctx) => {
+  const message = event.message;
+  if (message.role !== "assistant" || message.stopReason !== "error") return;
+  if (message.provider !== "my-provider" && ctx.model?.provider !== "my-provider") return;
+  const errorMessage = message.errorMessage ?? "";
+  if (errorMessage.includes("context_length_exceeded")) return;
+  if (!MY_PROVIDER_OVERFLOW_PATTERN.test(errorMessage)) return;
+  return { message: { ...message, errorMessage: `context_length_exceeded: ${errorMessage}` } };
+});
+```
+
+`message_end` runs before Pi tracks the message for auto-compaction, so the rewrite is what Pi checks. Scope it to your provider, match a provider-specific pattern (never Pi's generic ones — rewriting rate-limit errors would trigger compaction instead of retry-with-backoff), and skip when the phrase is already present so the handler is idempotent.
+
+## Testing
+
+Adapt the suites in `packages/ai/test/` for your provider/model pairs: `stream.test.ts`, `tokens.test.ts`, `abort.test.ts`, `empty.test.ts`, `context-overflow.test.ts`, `image-limits.test.ts`, `unicode-surrogate.test.ts`, `tool-call-without-result.test.ts`, `image-tool-result.test.ts`, `total-tokens.test.ts`, `cross-provider-handoff.test.ts`. Verify registration with `pi --list-models`, then exercise auth, tools, thinking levels, image input, cache behavior, retries, and context overflow.
+
+## Config Reference
+
+`ProviderConfig`: `name?`, `baseUrl?`, `apiKey?`, `api?`, `streamSimple?`, `headers?`, `authHeader?`, `models?`, `refreshModels?`, `oauth?`.
+
+`ProviderModelConfig`: `id`, `name`, `api?`, `baseUrl?` (per-model endpoint override), `reasoning`, `thinkingLevelMap?`, `input`, `cost` (`input`, `output`, `cacheRead`, `cacheWrite` per million tokens), `contextWindow`, `maxTokens`, `headers?`, `compat?`.
+
+Example extensions: `examples/extensions/custom-provider-anthropic/` and `examples/extensions/custom-provider-gitlab-duo/`.