@gotgenes/pi-anthropic-auth 0.4.0 → 0.4.1

package/README.md

@@ -57,6 +57,34 @@ pnpm run build    # compile
 pi -e /absolute/path/to/pi-anthropic-auth/dist/index.js
 ```
 
+### Debug Logging
+
+Set `PI_ANTHROPIC_AUTH_DEBUG` to enable structured debug logs from the OAuth shaping layer.
+
+Modes:
+
+- `PI_ANTHROPIC_AUTH_DEBUG=all` — log all Anthropic OAuth shaping events
+- `PI_ANTHROPIC_AUTH_DEBUG=tool-use` — log only requests that include `tool_use`
+
+Example:
+
+```bash
+PI_ANTHROPIC_AUTH_DEBUG=tool-use \
+pi \
+  --model anthropic/claude-haiku-4-5 \
+  --no-session \
+  --tools read,grep,find,ls \
+  -e /absolute/path/to/pi-anthropic-auth/src/index.ts \
+  -p "How many lines are in @AGENTS.md ?"
+```
+
+## Similar Projects
+
+- [opencode-anthropic-auth](https://github.com/ex-machina-co/opencode-anthropic-auth/) — Anthropic OAuth compatibility work for [OpenCode](https://opencode.ai/).
+- [pi-anthropic-oauth](https://github.com/leohenon/pi-anthropic-oauth) — a Pi extension that takes a fuller provider-override approach.
+
+For notes on how this project compares to similar work, see [docs/comparison-to-similar-projects.md](docs/comparison-to-similar-projects.md).
+
 ## Acknowledgments
 
 This project was inspired by [opencode-anthropic-auth](https://github.com/ex-machina-co/opencode-anthropic-auth/), which solved the same Anthropic OAuth compatibility problem for [OpenCode](https://opencode.ai/).

package/dist/constants.d.ts

@@ -5,6 +5,14 @@
  * preamble so it can be replaced with the minimal neutral prompt.
  */
 export declare const PI_DEFAULT_PROMPT_PREFIX = "You are an expert coding assistant operating inside pi, a coding agent harness.";
+/**
+ * Final line of Pi's built-in default system prompt preamble.
+ *
+ * Used to replace the entire Pi-generated preamble body with the minimal
+ * neutral Anthropic OAuth prompt while preserving anything appended after the
+ * preamble (project context, skills, and date/cwd footer).
+ */
+export declare const PI_DEFAULT_PROMPT_TERMINATOR = "- Always read pi .md files completely and follow links to related docs (e.g., tui.md for TUI API details)";
 /**
  * Prefix of the minimal neutral Anthropic OAuth system prompt.
  *

package/dist/constants.js

@@ -5,6 +5,14 @@
  * preamble so it can be replaced with the minimal neutral prompt.
  */
 export const PI_DEFAULT_PROMPT_PREFIX = "You are an expert coding assistant operating inside pi, a coding agent harness.";
+/**
+ * Final line of Pi's built-in default system prompt preamble.
+ *
+ * Used to replace the entire Pi-generated preamble body with the minimal
+ * neutral Anthropic OAuth prompt while preserving anything appended after the
+ * preamble (project context, skills, and date/cwd footer).
+ */
+export const PI_DEFAULT_PROMPT_TERMINATOR = "- Always read pi .md files completely and follow links to related docs (e.g., tui.md for TUI API details)";
 /**
  * Prefix of the minimal neutral Anthropic OAuth system prompt.
  *

package/dist/debug.d.ts

@@ -0,0 +1,3 @@
+export declare function isDebugEnabled(): boolean;
+export declare function isToolUseOnlyDebugEnabled(): boolean;
+export declare function debugLog(scope: string, data: unknown): void;

package/dist/debug.js

@@ -0,0 +1,32 @@
+function getDebugMode(value) {
+    if (!value)
+        return "off";
+    switch (value.trim().toLowerCase()) {
+        case "1":
+        case "true":
+        case "yes":
+        case "on":
+        case "debug":
+        case "all":
+            return "all";
+        case "tool":
+        case "tools":
+        case "tool-use":
+        case "tool_use":
+            return "tool-use";
+        default:
+            return "off";
+    }
+}
+export function isDebugEnabled() {
+    return getDebugMode(process.env.PI_ANTHROPIC_AUTH_DEBUG) !== "off";
+}
+export function isToolUseOnlyDebugEnabled() {
+    return getDebugMode(process.env.PI_ANTHROPIC_AUTH_DEBUG) === "tool-use";
+}
+export function debugLog(scope, data) {
+    if (!isDebugEnabled()) {
+        return;
+    }
+    console.error(`[pi-anthropic-auth][debug] ${scope} ${JSON.stringify(data)}`);
+}

package/dist/request-shaping.js

@@ -1,5 +1,6 @@
 import { createHash } from "node:crypto";
 import { BILLING_HEADER_POSITIONS, BILLING_HEADER_SALT, CLAUDE_CODE_ENTRYPOINT, CLAUDE_CODE_IDENTITY_PREFIX, CLAUDE_CODE_VERSION, MINIMAL_ANTHROPIC_OAUTH_PROMPT_PREFIX, } from "./constants.js";
+import { debugLog, isToolUseOnlyDebugEnabled } from "./debug.js";
 import { shapeSystemBlocks } from "./system-prompt-shaping.js";
 function isRecord(value) {
     return value !== null && typeof value === "object" && !Array.isArray(value);
@@ -119,6 +120,36 @@ function splitAssistantToolUseTrailingContent(messages) {
         ];
     });
 }
+function getToolDefinitionNames(payload) {
+    const tools = payload.tools;
+    if (!Array.isArray(tools)) {
+        return [];
+    }
+    return tools
+        .map((tool) => isRecord(tool) && typeof tool.name === "string" ? tool.name : undefined)
+        .filter((name) => typeof name === "string");
+}
+function getToolUseNames(messages) {
+    return messages.flatMap((message) => {
+        if (!Array.isArray(message.content)) {
+            return [];
+        }
+        return message.content
+            .map((block) => block?.type === "tool_use" && typeof block.name === "string"
+            ? block.name
+            : undefined)
+            .filter((name) => typeof name === "string");
+    });
+}
+function countAssistantMessages(messages) {
+    return messages.filter((message) => message.role === "assistant").length;
+}
+function shouldLogRequestDebug(messages) {
+    if (!isToolUseOnlyDebugEnabled()) {
+        return true;
+    }
+    return getToolUseNames(messages).length > 0;
+}
 export function shapeAnthropicOAuthPayload(payload) {
     if (!isAnthropicMessagesPayload(payload)) {
         return payload;
@@ -131,9 +162,28 @@ export function shapeAnthropicOAuthPayload(payload) {
     const shapedSystem = Array.isArray(payload.system)
         ? shapeSystemBlocks(payload.system)
         : payload.system;
+    const finalSystem = prependBillingHeader(shapedSystem, normalizedMessages);
+    const toolUseNamesBefore = getToolUseNames(messages);
+    const toolUseNamesAfter = getToolUseNames(normalizedMessages);
+    if (shouldLogRequestDebug(messages)) {
+        debugLog("before-provider-request", {
+            model: payload.model,
+            systemBlockCountBefore: Array.isArray(payload.system)
+                ? payload.system.length
+                : 0,
+            systemBlockCountAfter: Array.isArray(finalSystem)
+                ? finalSystem.length
+                : 0,
+            assistantMessagesBefore: countAssistantMessages(messages),
+            assistantMessagesAfter: countAssistantMessages(normalizedMessages),
+            toolDefinitions: getToolDefinitionNames(payload),
+            toolUseNamesBefore,
+            toolUseNamesAfter,
+        });
+    }
     return {
         ...payload,
         messages: normalizedMessages,
-        system: prependBillingHeader(shapedSystem, normalizedMessages),
+        system: finalSystem,
     };
 }

package/dist/system-prompt-shaping.d.ts

@@ -1,3 +1,15 @@
+/**
+ * Reset the one-time terminator-missing warning latch. Exposed for tests.
+ */
+export declare function _resetShapingWarnings(): void;
+export type SanitizedSystemTextReport = {
+    text: string;
+    removedParagraphs: Array<{
+        anchor: string;
+        preview: string;
+    }>;
+    replacementMatches: string[];
+};
 /**
  * Sanitize system prompt text by removing paragraphs containing known
  * Pi-specific anchor strings and applying inline text replacements for
@@ -9,19 +21,20 @@
  * string still appears somewhere in the paragraph, removal works regardless
  * of how the surrounding text changes.
  */
+export declare function sanitizeSystemTextWithReport(text: string): SanitizedSystemTextReport;
 export declare function sanitizeSystemText(text: string): string;
 /**
  * Shape a system prompt string for Anthropic OAuth compatibility.
  *
- * Uses an anchor-driven sanitizer to remove Pi-specific paragraphs
- * (identity, documentation references, filler) while preserving
- * extension-contributed content (tool snippets, guidelines, appended
- * content, project context, skills, and date/cwd footer).
- *
- * Prepends a minimal neutral prompt to replace the removed Pi identity.
+ * For the normal upstream Pi prompt shape, sanitize only the known preamble
+ * span and replace its identity paragraph with the minimal neutral prompt.
+ * This preserves downstream configuration/extension points embedded in the
+ * preamble (tool snippets and guideline bullets) while still stripping the
+ * Pi-specific identity, filler, and documentation paragraphs.
  *
- * If the Pi default prompt prefix is not present, the prompt is returned
- * unchanged — this gates shaping so non-Pi prompts pass through.
+ * If Pi's known preamble terminator drifts upstream, we fall back to slicing
+ * from `# Project Context`. If that section is also absent, we return the
+ * minimal prompt only.
  */
 export declare function shapeAnthropicOAuthSystemPrompt(systemPrompt: string): string;
 type TextBlock = {

package/dist/system-prompt-shaping.js

@@ -1,4 +1,30 @@
-import { MINIMAL_ANTHROPIC_OAUTH_PROMPT, PARAGRAPH_REMOVAL_ANCHORS, PI_DEFAULT_PROMPT_PREFIX, TEXT_REPLACEMENTS, } from "./constants.js";
+import { MINIMAL_ANTHROPIC_OAUTH_PROMPT, PARAGRAPH_REMOVAL_ANCHORS, PI_DEFAULT_PROMPT_PREFIX, PI_DEFAULT_PROMPT_TERMINATOR, TEXT_REPLACEMENTS, } from "./constants.js";
+import { debugLog, isToolUseOnlyDebugEnabled } from "./debug.js";
+let warnedTerminatorMissing = false;
+function warnTerminatorMissingOnce() {
+    if (warnedTerminatorMissing) {
+        return;
+    }
+    warnedTerminatorMissing = true;
+    console.warn("[pi-anthropic-auth] Pi default preamble terminator not found; falling back to '# Project Context' anchor. " +
+        "Upstream Pi may have reworded its preamble — update PI_DEFAULT_PROMPT_TERMINATOR.");
+}
+/**
+ * Reset the one-time terminator-missing warning latch. Exposed for tests.
+ */
+export function _resetShapingWarnings() {
+    warnedTerminatorMissing = false;
+}
+function previewParagraph(paragraph) {
+    return paragraph.replace(/\s+/g, " ").trim().slice(0, 140);
+}
+function shouldLogPromptDebug(report) {
+    if (!isToolUseOnlyDebugEnabled()) {
+        return true;
+    }
+    return (report.removedParagraphs.length === 0 &&
+        report.replacementMatches.length > 0);
+}
 /**
  * Sanitize system prompt text by removing paragraphs containing known
  * Pi-specific anchor strings and applying inline text replacements for
@@ -10,43 +36,97 @@ import { MINIMAL_ANTHROPIC_OAUTH_PROMPT, PARAGRAPH_REMOVAL_ANCHORS, PI_DEFAULT_P
  * string still appears somewhere in the paragraph, removal works regardless
  * of how the surrounding text changes.
  */
-export function sanitizeSystemText(text) {
+export function sanitizeSystemTextWithReport(text) {
     const paragraphs = text.split(/\n\n+/);
+    const removedParagraphs = [];
     const filtered = paragraphs.filter((paragraph) => {
         for (const anchor of PARAGRAPH_REMOVAL_ANCHORS) {
-            if (paragraph.includes(anchor))
-                return false;
+            if (!paragraph.includes(anchor)) {
+                continue;
+            }
+            removedParagraphs.push({
+                anchor,
+                preview: previewParagraph(paragraph),
+            });
+            return false;
         }
         return true;
     });
     let result = filtered.join("\n\n");
+    const replacementMatches = [];
     for (const rule of TEXT_REPLACEMENTS) {
+        if (result.includes(rule.match)) {
+            replacementMatches.push(rule.match);
+        }
         result = result.replaceAll(rule.match, rule.replacement);
     }
-    return result.trim();
+    return {
+        text: result.trim(),
+        removedParagraphs,
+        replacementMatches,
+    };
+}
+export function sanitizeSystemText(text) {
+    return sanitizeSystemTextWithReport(text).text;
+}
+function findProjectContextStart(systemPrompt) {
+    const marker = "\n\n# Project Context\n\n";
+    return systemPrompt.indexOf(marker);
 }
 /**
  * Shape a system prompt string for Anthropic OAuth compatibility.
  *
- * Uses an anchor-driven sanitizer to remove Pi-specific paragraphs
- * (identity, documentation references, filler) while preserving
- * extension-contributed content (tool snippets, guidelines, appended
- * content, project context, skills, and date/cwd footer).
+ * For the normal upstream Pi prompt shape, sanitize only the known preamble
+ * span and replace its identity paragraph with the minimal neutral prompt.
+ * This preserves downstream configuration/extension points embedded in the
+ * preamble (tool snippets and guideline bullets) while still stripping the
+ * Pi-specific identity, filler, and documentation paragraphs.
  *
- * Prepends a minimal neutral prompt to replace the removed Pi identity.
- *
- * If the Pi default prompt prefix is not present, the prompt is returned
- * unchanged — this gates shaping so non-Pi prompts pass through.
+ * If Pi's known preamble terminator drifts upstream, we fall back to slicing
+ * from `# Project Context`. If that section is also absent, we return the
+ * minimal prompt only.
  */
 export function shapeAnthropicOAuthSystemPrompt(systemPrompt) {
-    if (!systemPrompt.includes(PI_DEFAULT_PROMPT_PREFIX)) {
+    const prefixIdx = systemPrompt.indexOf(PI_DEFAULT_PROMPT_PREFIX);
+    if (prefixIdx === -1) {
         return systemPrompt;
     }
-    const sanitized = sanitizeSystemText(systemPrompt);
-    if (!sanitized) {
+    const terminatorIdx = systemPrompt.indexOf(PI_DEFAULT_PROMPT_TERMINATOR, prefixIdx);
+    if (terminatorIdx !== -1) {
+        const terminatorEnd = terminatorIdx + PI_DEFAULT_PROMPT_TERMINATOR.length;
+        const preamble = systemPrompt.slice(prefixIdx, terminatorEnd);
+        const report = sanitizeSystemTextWithReport(preamble);
+        const shapedPreamble = report.text
+            ? `${MINIMAL_ANTHROPIC_OAUTH_PROMPT}\n\n${report.text}`
+            : MINIMAL_ANTHROPIC_OAUTH_PROMPT;
+        if (shouldLogPromptDebug(report)) {
+            debugLog("system-prompt-shaping", {
+                mode: "terminator",
+                originalLength: systemPrompt.length,
+                preambleLength: preamble.length,
+                sanitizedPreambleLength: report.text.length,
+                removedParagraphCount: report.removedParagraphs.length,
+                removedAnchors: report.removedParagraphs.map((entry) => entry.anchor),
+                removedParagraphPreviews: report.removedParagraphs.map((entry) => entry.preview),
+                replacementMatches: report.replacementMatches,
+            });
+        }
+        return (systemPrompt.slice(0, prefixIdx) +
+            shapedPreamble +
+            systemPrompt.slice(terminatorEnd));
+    }
+    warnTerminatorMissingOnce();
+    if (!isToolUseOnlyDebugEnabled()) {
+        debugLog("system-prompt-shaping", {
+            mode: "project-context-fallback",
+            originalLength: systemPrompt.length,
+        });
+    }
+    const projectContextStart = findProjectContextStart(systemPrompt);
+    if (projectContextStart === -1) {
         return MINIMAL_ANTHROPIC_OAUTH_PROMPT;
     }
-    return `${MINIMAL_ANTHROPIC_OAUTH_PROMPT}\n\n${sanitized}`;
+    return `${MINIMAL_ANTHROPIC_OAUTH_PROMPT}${systemPrompt.slice(projectContextStart)}`;
 }
 /**
  * Apply system prompt shaping to an array of Anthropic system text blocks.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gotgenes/pi-anthropic-auth",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "description": "Pi extension package for Anthropic OAuth compatibility",
   "author": {
     "name": "Chris Lasher"