pi-llm-debugging 0.1.0

package/README.md

@@ -0,0 +1,75 @@
+# pi-llm-debugging
+
+A [pi](https://shittycodingagent.ai) extension that captures the full LLM provider request payload to disk before each call — letting you inspect exactly what gets sent to the model, turn by turn.
+
+## Install
+
+```bash
+pi install npm:pi-llm-debugging
+```
+
+To uninstall:
+
+```bash
+pi remove npm:pi-llm-debugging
+```
+
+## How it works
+
+Every time pi is about to call the LLM, the extension intercepts the raw provider payload and writes it as a JSON file into your project's local `.pi` directory:
+
+```
+.pi/pi-llm-debugging/<session_id>/<seq>.json
+```
+
+- **`session_id`** — the current pi session identifier (visible in the footer bar). Resets on `/new`, `/resume`, and `/fork`.
+- **`seq`** — a zero-padded sequence number (`001`, `002`, ...) that increments with each LLM call within the session.
+
+For example, a session might produce:
+
+```
+.pi/pi-llm-debugging/
+└── abc123def/
+    ├── 001.json   ← first turn
+    ├── 002.json   ← second turn (after a tool call loops back)
+    └── 003.json
+```
+
+Each file is the exact payload the provider receives: the full message history, system prompt, tool definitions, model parameters, and any cache hints.
+
+## What you can debug
+
+**Session health** — Read through the messages array to see how the conversation is growing. Spot runaway context, unexpected role ordering, or missing tool results that might confuse the model.
+
+**Token usage** — Compare payloads across turns to see what's eating your context window. Identify large tool results or verbose system prompt sections that could be trimmed.
+
+**System prompt drift** — Check whether injected context from extensions or skills is accumulating correctly, being duplicated, or getting dropped.
+
+**Tool serialization** — Verify that tool definitions and arguments are serialized the way the provider expects, especially useful when debugging custom tools or provider-specific quirks.
+
+**Compaction quality** — Compare the payload just before and just after a `/compact` to see what the summary replaced and whether important context was preserved.
+
+## Tips
+
+Add the debugging output to your `.gitignore` so it doesn't end up in version control:
+
+```
+.pi/pi-llm-debugging/
+```
+
+Use `jq` to quickly inspect a payload:
+
+```bash
+# See just the messages
+jq '.messages' .pi/pi-llm-debugging/<session_id>/001.json
+
+# Count tokens approximation: check message content lengths
+jq '[.messages[].content | .. | strings | length] | add' .pi/pi-llm-debugging/<session_id>/001.json
+
+# Diff two consecutive turns to see what changed
+diff \
+  <(jq . .pi/pi-llm-debugging/<session_id>/001.json) \
+  <(jq . .pi/pi-llm-debugging/<session_id>/002.json)
+```
+
+Since files are scoped per-project under `.pi/`, each project manages its own debugging output independently — nothing bleeds into other projects or your global `~/.pi` directory.

package/extensions/pi-llm-debugging.ts

@@ -0,0 +1,53 @@
+/**
+ * Pi LLM Debugging — Saves the full provider request payload to disk before each LLM call.
+ *
+ * Files are written to <project>/.pi/pi-llm-debugging/<pi_session_id>/<sequence>.json
+ * where <sequence> is a zero-padded counter (001, 002, ...).
+ *
+ * Unlike the global save-llm-prompt extension, each project manages its own debugging
+ * files under its local .pi directory, making it easy to review, diff, and gitignore
+ * per-project LLM traffic.
+ *
+ * The current Pi session ID is shown in the footer bar and updates on /new, /resume, and /fork.
+ */
+
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import { mkdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+export default function (pi: ExtensionAPI) {
+  let outDir = "";
+  let sequence = 0;
+
+  function initSession(ctx: {
+    cwd: string;
+    sessionManager: { getSessionId(): string };
+    ui: { setStatus(key: string, value: string | undefined): void };
+  }) {
+    const sessionId = ctx.sessionManager.getSessionId();
+    outDir = join(ctx.cwd, ".pi", "pi-llm-debugging", sessionId);
+    sequence = 0;
+    mkdirSync(outDir, { recursive: true });
+    ctx.ui.setStatus("llm-debugging", `🐛 ${sessionId}`);
+  }
+
+  pi.on("session_start", async (_event, ctx) => {
+    initSession(ctx);
+  });
+
+  pi.on("session_switch", async (_event, ctx) => {
+    initSession(ctx);
+  });
+
+  pi.on("session_fork", async (_event, ctx) => {
+    initSession(ctx);
+  });
+
+  pi.on("before_provider_request", (_event, ctx) => {
+    if (!outDir) initSession(ctx);
+    sequence++;
+    const filename = `${String(sequence).padStart(3, "0")}.json`;
+    const filepath = join(outDir, filename);
+    writeFileSync(filepath, JSON.stringify(_event.payload, null, 2), "utf-8");
+  });
+}

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "pi-llm-debugging",
+  "version": "0.1.0",
+  "description": "Saves LLM provider request payloads to the project's .pi folder for per-project debugging",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ross-jill-ws/pi-llm-debugging.git"
+  },
+  "keywords": [
+    "pi-package",
+    "debugging",
+    "llm",
+    "prompt",
+    "token",
+    "context",
+    "inspect",
+    "logging",
+    "tracing",
+    "optimization"
+  ],
+  "peerDependencies": {
+    "@mariozechner/pi-coding-agent": "*",
+    "@mariozechner/pi-tui": "*",
+    "@mariozechner/pi-ai": "*",
+    "@sinclair/typebox": "*"
+  },
+  "pi": {
+    "extensions": ["./extensions"]
+  }
+}