@vamsitalupula/pi-debug 0.0.0-stage → 2.0.0

package/LICENSE

@@ -0,0 +1,15 @@
+ISC License
+
+Copyright (c) 2026 Talupula Vamsi
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
+AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
+LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
+OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
+PERFORMANCE OF THIS SOFTWARE.

package/README.md

@@ -1,3 +1,104 @@
-# Temporary Holding Version
+# pi-debug
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+This is a [Pi](https://pi.dev) extension for Pi extension developers. It enables running Typescript within the Node.js context of the Pi coding agent
+
+<p align="center">
+    <img src="https://raw.githubusercontent.com/tanavamsikrishna/pi-debug/refs/heads/main/screenshot.png" width="500" alt="Alt text description">
+</p>
+
+## Installation
+
+To install the extension only in Pi's configuration directory (`~/.pi`) or local extension directories, `cd` into that folder and run:
+
+```sh
+pi install --local npm:@vamsitalupula/pi-debug
+```
+
+## How to use?
+
+1. Create a new file by running `/pi-debug ./debug.ts` in Pi user prompt
+2. You should see a new file called `debug.ts` created in the current folder
+
+```ts
+import type {
+    ExtensionAPI,
+    ExtensionContext,
+} from "@earendil-works/pi-coding-agent";
+
+export default function (pi: ExtensionAPI, getCtx: () => ExtensionContext) {
+    // Your code here
+    // return getCtx().getSystemPrompt();
+    return pi.getActiveTools();
+}
+```
+
+3. Now run the file with `/pi-debug ./debug.ts`
+4. The data/object returned by the `default export function` is shown as a pi notification
+5. The package `@earendil-works/pi-coding-agent` is available in the node environment running *pi*. But if you need LSP/linting support in your editor, you need to point your editor tools to the install location of the package one way or an other. The easiest is to just run `pnpm i --save-dev @earendil-works/pi-coding-agent` in the project or local directory
+
+## AI tool
+
+`pi-debug` is also a tool the model can call. Pass the whole module, the same shape as `TEMPLATE.ts`, not a function body. It runs on the same jiti instance as `/pi-debug`, and the return value is the tool result. The tool description includes the template.
+
+## Examples
+
+**To see the runtime system prompt**
+
+```ts
+export default function (pi: ExtensionAPI, getCtx: () => ExtensionContext) {
+    return getCtx().getSystemPrompt();
+}
+```
+
+**To log tool results to a file**
+
+```ts
+import { appendFileSync } from "node:fs";
+
+export default function (pi: ExtensionAPI, getCtx: () => ExtensionContext) {
+    pi.on("tool_result", async (event, ctx) => {
+        const logEntry = JSON.stringify({
+            timestamp: new Date().toISOString(),
+            toolName: event.toolName,
+            toolCallId: event.toolCallId,
+            isError: event.isError,
+            content: event.content,
+        }, null, 2);
+
+        appendFileSync("/tmp/pi-tool-results.log", logEntry + "\n");
+    });
+}
+```
+
+**To get assistant message details with decreasing cache reads**
+
+```ts
+    const ctx = getCtx();
+    const branch = ctx.sessionManager.getBranch();
+
+    const messages = branch
+        .filter((entry) => entry.type === "message")
+        .map((entry) => entry.message);
+
+    return messages
+        .slice(1)
+        .filter((msg, index) => {
+            if (msg.role !== "assistant" || !msg.usage) return false;
+
+            const prevMsg = messages[index];
+            const prevCache =
+                prevMsg?.role === "assistant"
+                    ? (prevMsg.usage?.cacheRead ?? 0)
+                    : 0;
+            const currCache = msg.usage.cacheRead ?? 0;
+
+            return currCache > prevCache;
+        })
+        .map((msg) => {
+            return {
+                timestamp: msg.timestamp,
+                responseId: msg.responseId,
+                usage: msg.usage,
+            };
+        });
+```

package/extensions/TEMPLATE.ts

@@ -0,0 +1,10 @@
+import type {
+    ExtensionAPI,
+    ExtensionContext,
+} from "@earendil-works/pi-coding-agent";
+
+export default function (pi: ExtensionAPI, getCtx: () => ExtensionContext) {
+    // Your code here
+    // return getCtx().getSystemPrompt();
+    return pi.getActiveTools();
+}

package/extensions/index.js

@@ -0,0 +1,166 @@
+// src/index.ts
+import { existsSync, readFileSync, writeFileSync } from "fs";
+import { mkdtemp, writeFile } from "fs/promises";
+import { tmpdir } from "os";
+import path from "path";
+import { fileURLToPath } from "url";
+import {
+  DEFAULT_MAX_BYTES,
+  DEFAULT_MAX_LINES,
+  formatSize,
+  truncateHead,
+  withFileMutationQueue
+} from "@earendil-works/pi-coding-agent";
+import { createJiti } from "jiti";
+import { Type } from "typebox";
+function templateFilePath() {
+  const dir = path.dirname(fileURLToPath(import.meta.url));
+  const beside = path.join(dir, "TEMPLATE.ts");
+  if (existsSync(beside)) return beside;
+  return path.join(dir, "../static/TEMPLATE.ts");
+}
+function readCommandSource(fullPath) {
+  const existing = existsSync(fullPath) ? readFileSync(fullPath, "utf8") : "";
+  if (existing.trim()) return existing;
+  writeFileSync(fullPath, readFileSync(templateFilePath()));
+  return void 0;
+}
+async function invokeDefaultExport(mod, pi, getCtx) {
+  const exported = mod?.default ?? mod;
+  if (typeof exported !== "function") {
+    throw new Error("No default export function found");
+  }
+  return await exported(pi, getCtx);
+}
+async function runDefaultExport(load, pi, getCtx) {
+  try {
+    const value = await invokeDefaultExport(await load(), pi, getCtx);
+    const text = value === void 0 ? "Done (no return value)" : typeof value === "object" ? JSON.stringify(value, null, 2) : String(value);
+    return { ok: true, value, text };
+  } catch (error) {
+    return {
+      ok: false,
+      text: `Error: ${error instanceof Error ? error.message : String(error)}`
+    };
+  }
+}
+function toolDescription(template) {
+  return [
+    "Evaluates a TypeScript module on this session's jiti instance and returns what its default export returns.",
+    "The default export is called as (pi, getCtx) => result. pi is the agent ExtensionAPI. getCtx() returns the current ExtensionContext. Listeners registered on pi remain after this call. The module runs in the agent process with this extension's privileges. There is no sandbox.",
+    "Imports resolve from the session working directory and are read again on each call. import.meta.url is not a file on disk.",
+    'An object or array result is JSON. undefined is the text "Done (no return value)". Any other result is String(value). A thrown error, or a module with no default-export function, is an error result whose text starts with "Error: ".',
+    `Output is truncated to ${DEFAULT_MAX_LINES} lines or ${formatSize(DEFAULT_MAX_BYTES)}, whichever is hit first. The notice names the temp file that holds the full text.`,
+    "Module shape:",
+    template.trimEnd()
+  ].join("\n\n");
+}
+async function present(text) {
+  const truncation = truncateHead(text);
+  if (!truncation.truncated) {
+    return { text, details: { truncated: false } };
+  }
+  const dir = await mkdtemp(path.join(tmpdir(), "pi-debug-"));
+  const fullOutputPath = path.join(dir, "output.txt");
+  await withFileMutationQueue(fullOutputPath, async () => {
+    await writeFile(fullOutputPath, text, "utf8");
+  });
+  const notice = truncation.firstLineExceedsLimit ? `[Output truncated: first line exceeds ${formatSize(DEFAULT_MAX_BYTES)}. Full output saved to: ${fullOutputPath}]` : `
+
+[Output truncated: showing ${truncation.outputLines} of ${truncation.totalLines} lines (${formatSize(truncation.outputBytes)} of ${formatSize(truncation.totalBytes)}). Full output saved to: ${fullOutputPath}]`;
+  const shown = truncation.firstLineExceedsLimit ? notice : truncation.content + notice;
+  return { text: shown, details: { truncated: true, fullOutputPath } };
+}
+async function toolResult(text, isError = false) {
+  const presented = await present(text);
+  return {
+    content: [{ type: "text", text: presented.text }],
+    details: presented.details,
+    ...isError ? { isError: true } : {}
+  };
+}
+function index_default(pi) {
+  let lastCtx = null;
+  let jiti;
+  const getJiti = () => {
+    jiti ||= createJiti(import.meta.url, {
+      fsCache: false,
+      moduleCache: false
+    });
+    return jiti;
+  };
+  const getCtx = () => lastCtx;
+  const loadSource = (code, cwd) => getJiti().evalModule(code, {
+    filename: path.join(cwd, ".pi-debug-eval.ts"),
+    async: true
+  });
+  for (const event of ["session_start", "turn_start"]) {
+    pi.on(event, (_event, ctx) => {
+      lastCtx = ctx;
+    });
+  }
+  pi.registerCommand("pi-debug", {
+    description: "Run a .ts file with default export function",
+    handler: async (args, ctx) => {
+      lastCtx = ctx;
+      let filePath = args?.trim() || "";
+      if (filePath.startsWith("@")) filePath = filePath.slice(1);
+      if (!filePath) {
+        ctx.ui.notify("Usage: /pi-debug <file-path>", "info");
+        return;
+      }
+      const fullPath = path.resolve(ctx.cwd, filePath);
+      const code = readCommandSource(fullPath);
+      if (code === void 0) {
+        ctx.ui.notify(`${filePath} updated with a code template`);
+        return;
+      }
+      const run = await runDefaultExport(
+        () => loadSource(code, ctx.cwd),
+        pi,
+        getCtx
+      );
+      if (!run.ok) {
+        ctx.ui.notify(run.text, "error");
+        return;
+      }
+      ctx.ui.notify(
+        run.value === void 0 ? run.text : `Result:
+${run.text}`,
+        "info"
+      );
+    }
+  });
+  pi.registerTool({
+    name: "pi-debug",
+    label: "Pi Debug",
+    description: toolDescription(readFileSync(templateFilePath(), "utf8")),
+    promptSnippet: "Run TypeScript inside the live Pi agent",
+    promptGuidelines: [
+      "Use pi-debug when the answer depends on live agent state, such as the system prompt, active tools, or session entries, instead of inferring that state from files.",
+      "Do not use bash or a subprocess instead of pi-debug for live agent state; a subprocess cannot see this process.",
+      "After pi-debug returns, use that result, and call pi-debug again only if agent state may have changed."
+    ],
+    parameters: Type.Object({
+      code: Type.String({
+        description: "TypeScript module source to evaluate. Include imports and the default export; not a function body."
+      })
+    }),
+    executionMode: "sequential",
+    async execute(_toolCallId, params, signal, _onUpdate, ctx) {
+      if (signal?.aborted) return toolResult("Cancelled", true);
+      lastCtx = ctx;
+      if (!params.code.trim())
+        return toolResult("Error: No code provided", true);
+      const run = await runDefaultExport(
+        () => loadSource(params.code, ctx.cwd),
+        pi,
+        getCtx
+      );
+      return toolResult(run.text, !run.ok);
+    }
+  });
+}
+export {
+  index_default as default
+};

package/package.json

@@ -1,6 +1,44 @@
 {
   "name": "@vamsitalupula/pi-debug",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "repository": "github:tanavamsikrishna/pi-debug",
+  "version": "2.0.0",
+  "description": "Run Typescript within the Node.js context of the Pi coding agent",
+  "type": "module",
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --clean --outDir extensions --publicDir ./static/ --external @earendil-works/pi-coding-agent",
+    "dev": "tsup src/index.ts --format esm --watch --outDir extensions --publicDir ./static/ --external @earendil-works/pi-coding-agent",
+    "test": "node --experimental-strip-types --test test/pi-debug.test.ts"
+  },
+  "files": [
+    "extensions",
+    "package.json"
+  ],
+  "main": "extensions/index.js",
+  "keywords": [
+    "pi",
+    "pi-package",
+    "extension",
+    "typescript",
+    "jiti",
+    "devtool",
+    "runner"
+  ],
+  "author": "",
+  "license": "ISC",
+  "dependencies": {
+    "jiti": "^2.7.0",
+    "typebox": "^1.1.24"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-coding-agent": "^0.74.2",
+    "tsup": "^8.5.1",
+    "typescript": "^5.9.3"
+  },
+  "access": "public",
+  "pi": {
+    "extensions": [
+      "extensions/"
+    ],
+    "image": "https://raw.githubusercontent.com/tanavamsikrishna/pi-debug/refs/heads/main/screenshot.png"
+  }
+}