Advanced

// The conversation that triggers self-extensibility:
// You: "Add a tool that searches our PostgreSQL database for records by email"
 
// Pi writes this file autonomously:
// File: ~/.pi/extensions/pi-ext-db-search/index.ts
 
import { PiExtensionAPI, Tool } from "@earendil-works/pi-coding-agent";
import { Pool } from "pg"; // => pg is Node.js PostgreSQL client
 
// Pi reads DATABASE_URL from the environment — same pattern as project code
const pool = new Pool({
  connectionString: process.env.DATABASE_URL,
  // => Connection reused across tool calls (pooled)
});
 
const searchByEmailTool: Tool = {
  name: "search_by_email",
  description:
    "Search the database for user records matching an email address. " +
    "Returns the matching user record or 'not found'. Use this to look up " +
    "user data when debugging authentication or account issues.",
  parameters: {
    type: "object",
    properties: {
      email: {
        type: "string",
        description: "Email address to search for (exact match)",
      },
      table: {
        type: "string",
        description: "Table to search in (default: 'users')",
      },
    },
    required: ["email"],
  },
  execute: async ({ email, table = "users" }) => {
    // Parameterized query — never interpolate user input directly
    const result = await pool.query(
      `SELECT id, email, created_at, role FROM ${table} WHERE email = $1 LIMIT 1`,
      [email], // => $1 is bound to email — prevents SQL injection
    );
    // => pool.query uses prepared statement under the hood
 
    if (result.rows.length === 0) {
      return `No record found for email: ${email}`;
    }
 
    return JSON.stringify(result.rows[0], null, 2);
    // => Return as formatted JSON for LLM readability
  },
};
 
export default function setup(api: PiExtensionAPI): void {
  api.register(searchByEmailTool);
}

# Pi runs these commands autonomously during the self-extension workflow:
 
# 1. Write the extension files (Pi uses its Write tool)
 
# 2. Install dependencies
cd ~/.pi/extensions/pi-ext-db-search && npm install
# => added 8 packages in 2s
 
# 3. Compile TypeScript
npm run build
# => tsc -p tsconfig.json
# => (Output: dist/index.js)
 
# 4. Reload the extension into the live session
pi reload pi-ext-db-search
# => Extension reloaded: pi-ext-db-search
# => New tools available: search_by_email
 
# 5. Test the new tool
# (Pi sends a test message and observes the result in the same session)

// Complete domain-specific agent: automated code review
// This is a standalone TypeScript application built on pi-agent-core
 
import { Agent, AnthropicProvider } from "@earendil-works/pi-agent-core";
import { readFile, writeFile } from "fs/promises";
import { execSync } from "child_process";
import * as path from "path";
 
// System prompt for the code review agent — narrow, specific, with output format
const REVIEW_SYSTEM_PROMPT = `
You are a code review agent specialized in TypeScript API code quality.
 
Your responsibilities:
1. Read the files specified in your task
2. Identify issues in these categories: security, correctness, performance, maintainability
3. Write all findings to review-report.md in the format specified below
 
Finding format (one per issue):
**[SEVERITY]** \`file.ts:line\` — concise description
Severity: CRITICAL | HIGH | MEDIUM | LOW | INFO
 
Rules:
- Do not modify source files — use Write only for review-report.md
- Do not run the application — use Bash only for grep, git, and static analysis
- Stop when you have reviewed all requested files and written the report
- If a file has no issues, note it explicitly: "file.ts — no issues found"
`.trim();
 
// Tools available to the review agent — intentionally restricted
function createReviewTools() {
  const readFileTool = {
    name: "Read",
    description: "Read a source file for review",
    parameters: {
      type: "object" as const,
      properties: {
        file_path: { type: "string" },
        offset: { type: "number" },
        limit: { type: "number" },
      },
      required: ["file_path"],
    },
    execute: async ({ file_path, offset, limit }: { file_path: string; offset?: number; limit?: number }) => {
      const content = await readFile(file_path, "utf-8");
      // => Read file contents — read-only, safe for untrusted repos
      const lines = content.split("\n");
      const start = offset ?? 0;
      const end = limit ? start + limit : lines.length;
      return lines.slice(start, end).join("\n");
    },
  };
 
  const writeTool = {
    name: "Write",
    description: "Write the review report to review-report.md only",
    parameters: {
      type: "object" as const,
      properties: {
        file_path: { type: "string" },
        content: { type: "string" },
      },
      required: ["file_path", "content"],
    },
    execute: async ({ file_path, content }: { file_path: string; content: string }) => {
      // Enforce the write restriction — only review-report.md is allowed
      if (!file_path.endsWith("review-report.md")) {
        return `Error: this agent may only write to review-report.md, not ${file_path}`;
        // => Return error string — agent sees it and adapts
      }
      await writeFile(file_path, content, "utf-8");
      return `Written: ${file_path}`;
    },
  };
 
  const bashTool = {
    name: "Bash",
    description: "Run grep, git log, or static analysis — no execution of application code",
    parameters: {
      type: "object" as const,
      properties: { command: { type: "string" } },
      required: ["command"],
    },
    execute: async ({ command }: { command: string }) => {
      // Allowlist: only safe, read-only commands
      const allowed = ["grep", "git log", "git diff", "git blame", "find", "wc", "cat"];
      const isAllowed = allowed.some((cmd) => command.trim().startsWith(cmd));
      // => Check command against allowlist
 
      if (!isAllowed) {
        return `Error: only read-only commands allowed (grep, git log, etc.)`;
        // => Reject disallowed commands explicitly
      }
 
      return execSync(command, { encoding: "utf-8" });
    },
  };
 
  return [readFileTool, writeTool, bashTool];
}
 
// The review agent application
async function runCodeReview(projectPath: string, filesToReview: string[]): Promise<string> {
  const agent = new Agent({
    provider: new AnthropicProvider({
      apiKey: process.env.ANTHROPIC_API_KEY!,
      model: "claude-opus-4-5", // => Strong model for nuanced review
    }),
    systemPrompt: REVIEW_SYSTEM_PROMPT,
    tools: createReviewTools(),
    maxTurns: 30, // => Safety limit for the agent loop
    cwd: projectPath, // => All file operations relative to project root
  });
 
  const fileList = filesToReview.map((f) => `- ${f}`).join("\n");
  const task = `Review these files and write findings to review-report.md:\n${fileList}`;
 
  const result = await agent.run(task); // => Runs the full agentic loop
  return result.response; // => Final text response (summary of what was done)
}
 
// Example usage
const findings = await runCodeReview("/path/to/project", [
  "src/auth/jwt.ts",
  "src/router/tasks.ts",
  "src/middleware/auth.ts",
]);
 
console.log(findings);
// => "I have reviewed 3 files and written findings to review-report.md.
// =>  Summary: 1 CRITICAL issue, 3 HIGH, 5 MEDIUM, 2 LOW, 3 INFO.
// =>  The CRITICAL issue is in src/auth/jwt.ts:47 — the JWT algorithm is not validated."

import { TUIComponent, Box, Text, Divider, Color, TUIEngine } from "@earendil-works/pi-tui";
 
// A complex widget: live token usage meter with color-coded thresholds
class TokenUsageMeter implements TUIComponent {
  private current: number = 0;
  private limit: number = 200_000; // => Default: claude-sonnet-4-5 context limit
 
  constructor(private title: string) {}
 
  // Update data — TUI engine will call render() on the next frame
  update(current: number, limit: number): void {
    this.current = current;
    this.limit = limit;
    // => Calling update() marks this component as dirty
    // => TUI engine re-renders only this component on next frame
  }
 
  // Focus management — called when user tabs to this component
  onFocus(): void {
    // => This widget is display-only — no focus behavior
  }
 
  render(): Box {
    const pct = this.current / this.limit; // => 0.0 to 1.0
    const barWidth = 40; // => Total width of the progress bar in characters
    const filled = Math.round(pct * barWidth);
    // => Number of filled characters
 
    // Color coding: green below 60%, yellow 60–80%, red above 80%
    const barColor: Color =
      pct < 0.6
        ? "green" // => WCAG AA: green on dark terminal background
        : pct < 0.8
          ? "yellow" // => WCAG AA: yellow visible against dark background
          : "red"; // => WCAG AA: red signals critical threshold
 
    const bar = "█".repeat(filled) + "░".repeat(barWidth - filled);
    // => Unicode block characters for progress bar
    const percentage = `${Math.round(pct * 100)}%`;
    const counts = `${this.current.toLocaleString()} / ${this.limit.toLocaleString()} tokens`;
 
    return new Box({
      border: "single",
      title: this.title,
      width: 50, // => Fixed width — content clips if terminal narrower
      children: [
        new Text({
          content: bar,
          color: barColor, // => Color determined by threshold
        }),
        new Text({
          content: `${percentage}  ${counts}`,
          // => No color — white on dark terminal (default, highest contrast)
        }),
      ],
    });
    // => render() returns a pure virtual tree — no side effects
    // => The TUI engine diffs this against the previous frame
    // => Only changed cells are written to the terminal
  }
}
 
// Use the widget in a Pi extension
import { PiExtensionAPI } from "@earendil-works/pi-coding-agent";
 
export default function setup(api: PiExtensionAPI): void {
  const meter = new TokenUsageMeter("Context Window");
 
  api.registerComponent({
    id: "token-meter",
    position: "sidebar",
    component: meter,
  });
 
  // Update the meter on every turn
  api.onAfterTurn(async (turn, { session }) => {
    meter.update(session.contextTokens, session.modelContextLimit);
    // => Triggers re-render of only the meter widget
    // => Rest of the TUI is not redrawn
  });
}

import { TUIComponent, Box, Input, Key } from "@earendil-works/pi-tui";
 
// An interactive widget: a filter input for a log viewer
class FilterInput implements TUIComponent {
  private value: string = "";
  private focused: boolean = false;
  private onFilterChange: (filter: string) => void;
 
  constructor(onFilterChange: (filter: string) => void) {
    this.onFilterChange = onFilterChange;
  }
 
  onFocus(): void {
    this.focused = true; // => Mark as focused — render() shows active border
  }
 
  onBlur(): void {
    this.focused = false; // => Mark as unfocused — render() shows inactive border
  }
 
  onKeyPress(key: Key): boolean {
    if (key.name === "backspace") {
      this.value = this.value.slice(0, -1);
      // => Remove last character
    } else if (key.name === "escape") {
      this.value = ""; // => Clear filter on Escape
    } else if (key.char && !key.ctrl) {
      this.value += key.char; // => Append printable characters
    } else {
      return false; // => Key not handled — pass to parent
    }
 
    this.onFilterChange(this.value); // => Notify parent of filter change
    return true; // => Key handled — stop propagation
  }
 
  render(): Box {
    return new Box({
      border: this.focused ? "double" : "single",
      // => Double border when focused — visual feedback
      title: "Filter",
      children: [
        new Input({
          value: this.value,
          placeholder: "Type to filter...",
          focused: this.focused,
        }),
      ],
    });
  }
}

# --- Ollama setup (fully local, no external API calls) ---
 
# Install Ollama (macOS)
brew install ollama
 
# Start the Ollama server (runs locally on localhost:11434)
ollama serve
# => Ollama is running on http://localhost:11434
 
# Pull a code-capable model (done once; stored locally)
ollama pull codellama:13b
# => pulling manifest
# => pulling model weights: 7.4 GB
# => (This is the last network call — everything after is local)
 
# Pull a smaller model for faster iteration (less capable but faster)
ollama pull llama3.2:3b
# => pulling manifest
# => pulling model weights: 2.0 GB
 
# Start Pi with Ollama provider
pi --provider ollama --model codellama:13b
# => Pi v0.75.4
# => Provider: ollama (local) · Model: codellama:13b · Context: 0 tokens
# => (All LLM calls go to localhost:11434 — no external network traffic)
 
# Or configure in AGENTS.md for a project:
# pi-config:
#   provider: ollama
#   model: codellama:13b
#   api-base: http://localhost:11434  # Optional: change if Ollama runs on a different host

# --- AWS Bedrock setup (hosted Claude, in your AWS account) ---
 
# Configure AWS credentials (IAM role or access keys)
aws configure
# => AWS Access Key ID: AKIA...
# => AWS Secret Access Key: ...
# => Default region name: us-east-1
# => Default output format: json
 
# Ensure Claude models are enabled in Bedrock (AWS Console → Bedrock → Model access)
# Request access to: anthropic.claude-sonnet-4-5-v1  (or the version available in your region)
 
# Start Pi with Bedrock provider
pi --provider bedrock --model anthropic.claude-sonnet-4-5-v1
# => Pi v0.75.4
# => Provider: bedrock (us-east-1) · Model: anthropic.claude-sonnet-4-5-v1 · Context: 0 tokens
# => (LLM calls go to your AWS account's Bedrock endpoint — not to api.anthropic.com)
 
# Bedrock with a custom endpoint (for PrivateLink or VPC endpoint configurations)
pi --provider bedrock \
   --model anthropic.claude-sonnet-4-5-v1 \
   --api-base https://vpce-xxx.bedrock.us-east-1.vpce.amazonaws.com
# => (All traffic stays within your VPC — no public internet egress)

// Configuring Bedrock with session-level token tracking for cost attribution
 
import { createProvider } from "@earendil-works/pi-ai";
 
const bedrockProvider = createProvider("bedrock", {
  region: "us-east-1",
  model: "anthropic.claude-sonnet-4-5-v1",
  // Optional: override the endpoint for PrivateLink
  endpoint: process.env.BEDROCK_ENDPOINT,
  // => Undefined uses default Bedrock endpoint
  // Optional: tag requests for AWS cost attribution
  requestTags: {
    "pi:project": process.env.PROJECT_NAME ?? "unknown",
    "pi:environment": process.env.ENVIRONMENT ?? "development",
  },
  // => Tags appear in AWS Cost Explorer under Bedrock usage
  // => Useful for attributing LLM costs to specific teams or projects
});

// The Pi session file schema (TypeScript representation)
 
interface SessionFile {
  metadata: {
    id: string; // => UUID v4 — unique session identifier
    name: string; // => Human-readable name (from first message)
    createdAt: string; // => ISO 8601 timestamp
    updatedAt: string; // => ISO 8601 timestamp, updated on every turn
    parentId?: string; // => Present if this session is a branch
    branchPoint?: number; // => Turn index where this session branched
    provider: string; // => LLM provider name ("anthropic", "openai", etc.)
    model: string; // => Model name used in this session
    cwd: string; // => Working directory when session was created
    agentsMd?: string; // => Content of AGENTS.md at session start (snapshot)
    systemMd?: string; // => Content of SYSTEM.md if present (snapshot)
  };
  messages: Array<
    | { role: "user"; content: string }
    | { role: "assistant"; content: string | null; tool_calls?: ToolCall[] }
    | { role: "tool"; tool_call_id: string; content: string }
  >; // => Standard LLM message format with tool calls
  state: Record<string, unknown>; // => Extension-managed key-value store
}
 
interface ToolCall {
  id: string; // => Unique ID correlating tool call with tool result
  name: string; // => Tool name ("Read", "Write", "Edit", "Bash", or custom)
  arguments: Record<string, unknown>; // => Arguments the LLM passed to the tool
}

import { PiExtensionAPI } from "@earendil-works/pi-coding-agent";
 
export default function setup(api: PiExtensionAPI): void {
  // Initialize extension state on first turn
  api.onSessionStart(async (session) => {
    if (!session.state["file-tracker"]) {
      session.state["file-tracker"] = {
        filesRead: [], // => Track which files the agent has read
        filesModified: [], // => Track which files the agent has modified
        startedAt: new Date().toISOString(),
      };
      await session.save(); // => Persist state to disk immediately
    }
  });
 
  // Update state when files are read or written
  api.onToolCall(async (toolCall, session) => {
    const tracker = session.state["file-tracker"] as {
      filesRead: string[];
      filesModified: string[];
      startedAt: string;
    };
 
    if (toolCall.name === "Read") {
      const path = toolCall.arguments.file_path as string;
      if (!tracker.filesRead.includes(path)) {
        tracker.filesRead.push(path); // => Track unique files read
        await session.save(); // => Persist after each update
      }
    }
 
    if (toolCall.name === "Write" || toolCall.name === "Edit") {
      const path = toolCall.arguments.file_path as string;
      if (!tracker.filesModified.includes(path)) {
        tracker.filesModified.push(path); // => Track unique files modified
        await session.save();
      }
    }
  });
 
  // Register a slash command to show the tracking summary
  api.registerCommand({
    name: "files",
    description: "Show files read and modified in this session",
    execute: async (_, { session }) => {
      const tracker = session.state["file-tracker"] as {
        filesRead: string[];
        filesModified: string[];
      };
      return [
        `Files read (${tracker.filesRead.length}):`,
        ...tracker.filesRead.map((f) => `  ${f}`),
        "",
        `Files modified (${tracker.filesModified.length}):`,
        ...tracker.filesModified.map((f) => `  ${f}`),
      ].join("\n");
    },
  });
}

// Migration script — run when upgrading Pi across major versions
import { readdir, readFile, writeFile } from "fs/promises";
import * as path from "path";
 
async function migrateSessions(sessionDir: string): Promise<void> {
  const files = await readdir(sessionDir);
  const sessionFiles = files.filter((f) => f.endsWith(".json"));
 
  for (const file of sessionFiles) {
    const filePath = path.join(sessionDir, file);
    const content = await readFile(filePath, "utf-8");
    const session = JSON.parse(content);
 
    // Example migration: v1 sessions had no 'state' field — add it
    if (!session.state) {
      session.state = {}; // => Initialize empty state for v1 sessions
      session.metadata.migratedAt = new Date().toISOString();
      // => Record migration timestamp
      await writeFile(filePath, JSON.stringify(session, null, 2), "utf-8");
      console.log(`Migrated: ${file}`);
    }
  }
}
 
await migrateSessions(path.join(process.env.HOME!, ".pi/sessions"));

# Start Pi with watch mode — auto-reloads extension on file change
pi --watch-extension pi-ext-my-tool
# => Pi v0.75.4
# => Extensions loaded: pi-ext-my-tool
# => Watching: ~/.pi/extensions/pi-ext-my-tool/src/ for changes
 
# Now edit your extension source file — Pi will recompile and reload automatically
# (In another terminal or editor:)
# vim ~/.pi/extensions/pi-ext-my-tool/src/index.ts
# (Make a change and save)
 
# Pi detects the change and reloads:
# => [hot-reload] Change detected: index.ts
# => [hot-reload] Compiling pi-ext-my-tool...
# => [hot-reload] Compilation success (0.8s)
# => [hot-reload] Unregistering old tools: my_tool
# => [hot-reload] Registering new tools: my_tool, my_tool_v2
# => [hot-reload] Extension reloaded in 1.2s

// Triggering hot-reload programmatically from the Pi CLI API
// (This is what the self-extensibility workflow uses internally)
 
import { exec } from "child_process";
import { promisify } from "util";
const execAsync = promisify(exec);
 
async function buildAndReload(extensionName: string): Promise<string> {
  const extPath = `${process.env.HOME}/.pi/extensions/${extensionName}`;
 
  // Step 1: compile the TypeScript
  const { stdout: buildOutput } = await execAsync("npm run build", {
    cwd: extPath, // => Run tsc in the extension directory
  });
  // => buildOutput: "" on success, error text on failure
 
  // Step 2: reload via the Pi CLI API
  const { stdout: reloadOutput } = await execAsync(`pi reload ${extensionName}`);
  // => pi reload sends a reload signal to the running Pi session
  // => The session must be running in the same terminal (or RPC mode)
 
  return reloadOutput.trim();
  // => "Extension reloaded: my-extension\nNew tools: my_tool_v2"
}
 
// The Pi agent can call this function from a Bash tool call:
// Bash("node -e \"import('./build-reload.mjs').then(m => m.buildAndReload('pi-ext-my-tool'))\"")

// Extension that enables explicit hot-reload via slash command
import { PiExtensionAPI } from "@earendil-works/pi-coding-agent";
import { exec } from "child_process";
import { promisify } from "util";
const execAsync = promisify(exec);
 
export default function setup(api: PiExtensionAPI): void {
  // /rebuild <extension-name> — compile and reload an extension on demand
  api.registerCommand({
    name: "rebuild",
    description: "Compile and reload an extension: /rebuild <extension-name>",
    execute: async (args, { session }) => {
      const extensionName = args.trim();
      if (!extensionName) {
        return "Usage: /rebuild <extension-name>";
      }
 
      const extPath = `${process.env.HOME}/.pi/extensions/${extensionName}`;
 
      try {
        // Compile
        await execAsync("npm run build", { cwd: extPath });
        // => Throws if compilation fails
 
        // Reload
        const { stdout } = await execAsync(`pi reload ${extensionName}`);
 
        return `Rebuilt and reloaded: ${extensionName}\n${stdout.trim()}`;
      } catch (error) {
        return `Build failed: ${(error as Error).message}`;
        // => Return error so agent can see and fix it
      }
    },
  });
}

// A SKILL.md that works identically in both Pi and OpenClaw
// The format is the same — copy this file to either system's skills directory
 
/*
# Git Workflow Skill
 
## When to use this skill
Apply this skill when the user asks about git operations, branch management,
committing changes, or reviewing git history.
 
## Conventions
- Always check `git status` before making any git operations
- Use conventional commit format: type(scope): description
- Never force-push to main or master
- Create a branch before making changes if on main
 
## Common operations
- Check status: `git status`
- Stage specific files: `git add path/to/file` (never `git add .`)
- Commit: `git commit -m "type(scope): description"`
- Push: `git push origin branch-name`
*/

# GitHub Actions workflow: pi-code-review.yml
name: Pi Code Review
 
on:
  pull_request:
    types: [opened, synchronize]
 
jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0 # => Fetch full history for git diff
 
      - uses: actions/setup-node@v4
        with:
          node-version: "20"
 
      - name: Install Pi
        run: npm install -g @earendil-works/pi-coding-agent
 
      - name: Run Pi code review
        id: review
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        run: |
          # Get list of changed TypeScript files
          CHANGED_FILES=$(git diff --name-only origin/${{ github.base_ref }}...HEAD \
            | grep '\.ts$' | head -20)
          # => Limit to 20 files — prevents runaway context usage on large PRs
 
          if [ -z "$CHANGED_FILES" ]; then
            echo "No TypeScript files changed — skipping review"
            exit 0
          fi
 
          FILE_LIST=$(echo "$CHANGED_FILES" | tr '\n' ' ')
 
          # Run Pi in JSON mode with a review task
          REVIEW_OUTPUT=$(pi --json --system-prompt-file .ci/review-system.md \
            "Review these changed files for CRITICAL and HIGH severity issues: $FILE_LIST")
          # => --json wraps the response in a JSON envelope
          # => --system-prompt-file loads the review system prompt from the repo
 
          # Save the full review output
          echo "$REVIEW_OUTPUT" > /tmp/pi-review.json
 
          # Extract the text response
          RESPONSE=$(echo "$REVIEW_OUTPUT" | jq -r '.result.response')
          echo "Review findings:"
          echo "$RESPONSE"
 
          # Fail if CRITICAL or HIGH issues are found
          if echo "$RESPONSE" | grep -qE '\*\*(CRITICAL|HIGH)\*\*'; then
            echo "::error::Pi review found CRITICAL or HIGH severity issues"
            exit 1
          fi

<!-- .ci/review-system.md — Pi system prompt for CI review -->
<!-- Loaded with --system-prompt-file in the CI step above -->
 
You are an automated code review agent running in CI.
 
Your task: review the specified TypeScript files for issues.
 
Output format — for each issue found, write exactly:
**[SEVERITY]** `file.ts:line` — concise description
 
Severity levels:
 
- CRITICAL: security vulnerability, data loss risk, will cause production incident
- HIGH: likely bug, significant performance issue, violates security best practice
- MEDIUM: maintainability concern, unclear logic, missing error handling
- LOW: style concern, minor inefficiency, could be improved
 
After listing issues, write one line:
SUMMARY: N_CRITICAL critical, N_HIGH high, N_MEDIUM medium, N_LOW low
 
Rules:
 
- Do not modify files — Read and Bash only
- If a file has no issues above MEDIUM severity, write: `file.ts` — no critical issues
- Stop after reviewing all requested files

# Test the CI workflow locally before pushing
# (Set ANTHROPIC_API_KEY in your environment first)
 
CHANGED_FILES="src/auth/jwt.ts src/router/tasks.ts"
pi --json --system-prompt-file .ci/review-system.md \
  "Review these files: $CHANGED_FILES" | jq -r '.result.response'
# => **[HIGH]** `src/auth/jwt.ts:47` — JWT algorithm not validated against allowlist
# => **[MEDIUM]** `src/router/tasks.ts:23` — Missing input validation on 'limit' parameter
# => SUMMARY: 0 critical, 1 high, 1 medium, 0 low

# --- Execution isolation using Docker ---
 
# Run Pi in a Docker container with restricted capabilities
docker run \
  --rm \                                 # => Remove container after session ends
  --network none \                      # => No network access (for fully isolated review)
  --read-only \                         # => Root filesystem is read-only
  --tmpfs /tmp:rw,noexec,size=100m \   # => Writable /tmp, no exec, 100MB limit
  --tmpfs /workspace:rw,size=500m \    # => Writable workspace, 500MB limit
  -v "$(pwd):/workspace:ro" \          # => Mount project as read-only
  -e ANTHROPIC_API_KEY \               # => Pass API key from environment
  earendil/pi:0.75.4 \                 # => Pinned version — not :latest
  pi --cwd /workspace --json "Review /workspace/src/ for security issues"
# => (Pi runs inside the container — no write access to host filesystem)
# => (No network means the agent cannot call external APIs via Bash)

// Input sanitization for Bash tool in an extension that processes untrusted input
 
import { Tool } from "@earendil-works/pi-coding-agent";
import { execSync } from "child_process";
 
// Sanitized Bash tool — replaces the default Bash for untrusted repo sessions
const sanitizedBashTool: Tool = {
  name: "Bash",
  description:
    "Execute read-only shell commands. Only grep, find, cat, head, tail, wc, " +
    "git log, git diff, and git blame are permitted.",
  parameters: {
    type: "object",
    properties: {
      command: { type: "string" },
    },
    required: ["command"],
  },
  execute: async ({ command }) => {
    // Allowlist: only safe, read-only commands
    const ALLOWED_PREFIXES = [
      "grep ",
      "find ",
      "cat ",
      "head ",
      "tail ",
      "wc ",
      "git log",
      "git diff",
      "git blame",
      "ls ",
      "stat ",
    ];
 
    const trimmed = command.trim();
    const isAllowed = ALLOWED_PREFIXES.some((prefix) => trimmed.startsWith(prefix));
 
    if (!isAllowed) {
      return `Command not permitted in sandboxed mode: ${trimmed.split(" ")[0]}`;
      // => Return error string — agent adapts behavior
    }
 
    // Additional check: no semicolons or pipes that could chain unsafe commands
    if (trimmed.includes(";") || trimmed.includes("|") || trimmed.includes("&&")) {
      return "Command chaining is not permitted in sandboxed mode";
    }
 
    try {
      return execSync(trimmed, {
        encoding: "utf-8",
        timeout: 10_000, // => 10-second timeout prevents hung commands
        maxBuffer: 1_000_000, // => 1MB output limit prevents context flooding
      });
    } catch (error) {
      return `Command failed: ${(error as Error).message}`;
    }
  },
};

// Rate limiting: prevent runaway sessions from exhausting API quota
 
import { PiExtensionAPI } from "@earendil-works/pi-coding-agent";
 
export default function setup(api: PiExtensionAPI): void {
  let turnCount = 0;
  let tokenCount = 0;
  const MAX_TURNS = 50; // => Stop after 50 turns (prevents infinite loops)
  const MAX_TOKENS = 500_000; // => Stop after 500K tokens (cost guard)
 
  api.onBeforeTurn(async (turn, { session, abort }) => {
    turnCount++;
    tokenCount = session.contextTokens;
 
    if (turnCount > MAX_TURNS) {
      abort(`Session limit reached: ${MAX_TURNS} turns. Start a new session.`);
      // => abort() stops the turn and sends message to user
    }
 
    if (tokenCount > MAX_TOKENS) {
      abort(`Token limit reached: ${tokenCount.toLocaleString()} tokens. Compact or branch.`);
    }
  });
 
  // Audit log: write every tool call to a structured log file
  api.onToolCall(async (toolCall, session) => {
    const logEntry = {
      timestamp: new Date().toISOString(),
      sessionId: session.metadata.id,
      tool: toolCall.name,
      arguments: toolCall.arguments, // => Full arguments — review for sensitive data
    };
 
    const logLine = JSON.stringify(logEntry) + "\n";
    await import("fs/promises").then((fs) => fs.appendFile("/var/log/pi-audit.log", logLine, "utf-8"));
    // => One JSON line per tool call — parseable with jq for auditing
  });
}

# Clone the Pi monorepo
git clone https://github.com/earendil-works/pi.git
cd pi
 
# Install dependencies for all packages (Turborepo manages the workspace)
npm install
# => (Installs dependencies for all packages in packages/)
 
# Explore the monorepo structure
ls packages/
# => pi-ai/           — Unified LLM API (@earendil-works/pi-ai)
# => pi-agent-core/   — Agent runtime (@earendil-works/pi-agent-core)
# => pi-coding-agent/ — CLI + TUI (@earendil-works/pi-coding-agent)
# => pi-tui/          — Terminal UI library (@earendil-works/pi-tui)
 
# Build all packages in dependency order (Turborepo handles ordering)
npm run build
# => turbo run build
# => pi-ai: tsc completed in 1.2s
# => pi-tui: tsc completed in 0.9s
# => pi-agent-core: tsc completed in 1.8s
# => pi-coding-agent: tsc completed in 2.1s
 
# Run the full test suite
npm run test
# => turbo run test
# => pi-ai: 47 tests passed
# => pi-tui: 23 tests passed
# => pi-agent-core: 89 tests passed
# => pi-coding-agent: 134 tests passed
# => All packages: 293 tests passed
 
# Run tests for a specific package
cd packages/pi-agent-core
npm run test
# => 89 tests passed in 4.2s
 
# Build and link locally for development testing
npm run build
npm link                                 # => Makes @earendil-works/pi-agent-core available locally
# => In another project: npm link @earendil-works/pi-agent-core

# Run integration tests (requires ANTHROPIC_API_KEY or OPENAI_API_KEY)
PI_RUN_INTEGRATION_TESTS=1 npm run test
# => (Runs live LLM calls — takes longer and costs real API tokens)
 
# Check TypeScript types without building
npm run typecheck
# => turbo run typecheck
 
# Lint all packages
npm run lint
# => turbo run lint
 
# Format code
npm run format
# => prettier --write "packages/**/src/**/*.ts"

// Future pi-agent-core v2 streaming API (planned, not yet released)
 
// Current (v0.x):
const result = await agent.run("Review src/auth.ts");
// => Waits for entire turn to complete before returning
// => result.response = "I found 2 issues..."
 
// Planned (v2):
for await (const event of agent.stream("Review src/auth.ts")) {
  if (event.type === "tool_call") {
    console.log(`Tool: ${event.name}(${JSON.stringify(event.arguments)})`);
    // => Printed immediately when the LLM decides to call a tool
  } else if (event.type === "tool_result") {
    console.log(`Result: ${event.result.slice(0, 100)}...`);
    // => Printed immediately after the tool executes
  } else if (event.type === "text_delta") {
    process.stdout.write(event.delta); // => Stream text token by token as it arrives
  } else if (event.type === "done") {
    console.log("\nTurn complete"); // => Turn is fully complete
  }
}
// => Callers see tool calls and responses progressively — no waiting for completion