@gotgenes/pi-anthropic-auth 0.3.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.
  *
@@ -43,3 +51,28 @@ export declare const BILLING_HEADER_SALT = "59cf53e54c78";
 export declare const BILLING_HEADER_POSITIONS: readonly [4, 7, 20];
 /** Entrypoint identifier included in the billing header. */
 export declare const CLAUDE_CODE_ENTRYPOINT = "sdk-cli";
+/**
+ * Strings whose presence in a paragraph marks it as Pi-specific and droppable.
+ *
+ * Each entry is checked with `paragraph.includes(anchor)`.
+ */
+export declare const PARAGRAPH_REMOVAL_ANCHORS: readonly string[];
+/**
+ * Inline text replacements applied after paragraph removal.
+ *
+ * These handle known Anthropic classifier trigger phrases that may appear
+ * in paragraphs we want to keep.  Each rule is applied with `replaceAll`.
+ *
+ * The "Here is some useful information..." phrase was isolated by
+ * `opencode-anthropic-auth` via sliding-window bisection of a 10KB failing
+ * prompt.  When it reaches Anthropic combined with typical agent context,
+ * /v1/messages responds with a 400 disguised as "You're out of extra usage."
+ * Replacing the word "useful" is enough to unblock the request.
+ *
+ * We don't currently emit this phrase, but it's included as a documented
+ * future risk per Issue #10.
+ */
+export declare const TEXT_REPLACEMENTS: readonly {
+    match: string;
+    replacement: string;
+}[];

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.
  *
@@ -60,3 +68,49 @@ export const BILLING_HEADER_SALT = "59cf53e54c78";
 export const BILLING_HEADER_POSITIONS = [4, 7, 20];
 /** Entrypoint identifier included in the billing header. */
 export const CLAUDE_CODE_ENTRYPOINT = "sdk-cli";
+// ---------------------------------------------------------------------------
+// Anchor-driven sanitizer constants
+//
+// Used by the system prompt sanitizer to remove Pi-specific paragraphs
+// (identity, documentation references, filler) while preserving extension-
+// contributed content (tool snippets, guidelines, appended content).
+//
+// A paragraph is any text between blank lines.  If a paragraph contains any
+// anchor string, it is dropped entirely.  This is resilient to upstream
+// rewording — as long as the anchor still appears somewhere in the paragraph,
+// removal works regardless of surrounding text changes.
+// ---------------------------------------------------------------------------
+/**
+ * Strings whose presence in a paragraph marks it as Pi-specific and droppable.
+ *
+ * Each entry is checked with `paragraph.includes(anchor)`.
+ */
+export const PARAGRAPH_REMOVAL_ANCHORS = [
+    // Pi identity sentence
+    "operating inside pi, a coding agent harness",
+    // Pi-specific filler about custom tools
+    "In addition to the tools above",
+    // Pi documentation block — references Pi-specific docs/paths
+    "Pi documentation (read only when the user asks about pi itself",
+];
+/**
+ * Inline text replacements applied after paragraph removal.
+ *
+ * These handle known Anthropic classifier trigger phrases that may appear
+ * in paragraphs we want to keep.  Each rule is applied with `replaceAll`.
+ *
+ * The "Here is some useful information..." phrase was isolated by
+ * `opencode-anthropic-auth` via sliding-window bisection of a 10KB failing
+ * prompt.  When it reaches Anthropic combined with typical agent context,
+ * /v1/messages responds with a 400 disguised as "You're out of extra usage."
+ * Replacing the word "useful" is enough to unblock the request.
+ *
+ * We don't currently emit this phrase, but it's included as a documented
+ * future risk per Issue #10.
+ */
+export const TEXT_REPLACEMENTS = [
+    {
+        match: "Here is some useful information about the environment you are running in:",
+        replacement: "Environment context you are running in:",
+    },
+];

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,7 +1,7 @@
 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";
-const ANTHROPIC_OAUTH_BETAS = ["claude-code-20250219", "oauth-2025-04-20"];
 function isRecord(value) {
     return value !== null && typeof value === "object" && !Array.isArray(value);
 }
@@ -90,13 +90,6 @@ function prependBillingHeader(system, messages) {
     const billingBlock = { type: "text", text: billingHeader };
     return [billingBlock, ...systemBlocks];
 }
-function mergeAnthropicBetas(betaHeader) {
-    const existing = (betaHeader ?? "")
-        .split(",")
-        .map((value) => value.trim())
-        .filter(Boolean);
-    return [...new Set([...ANTHROPIC_OAUTH_BETAS, ...existing])].join(",");
-}
 /**
  * Splits assistant messages that interleave text and tool_use blocks.
  *
@@ -127,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;
@@ -139,13 +162,28 @@ export function shapeAnthropicOAuthPayload(payload) {
     const shapedSystem = Array.isArray(payload.system)
         ? shapeSystemBlocks(payload.system)
         : payload.system;
-    const shapedPayload = {
+    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,
     };
-    shapedPayload["anthropic-beta"] = mergeAnthropicBetas(typeof payload["anthropic-beta"] === "string"
-        ? payload["anthropic-beta"]
-        : undefined);
-    return shapedPayload;
 }

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

@@ -1,9 +1,40 @@
+/**
+ * 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
+ * known Anthropic classifier trigger phrases.
+ *
+ * A paragraph is any text between blank lines (`\n\n`).
+ *
+ * This approach is resilient to upstream rewording — as long as the anchor
+ * 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.
  *
- * Replaces Pi's verbose default preamble with a minimal neutral prompt while
- * preserving any project context that follows.  Returns the original string
- * unchanged when Pi's default preamble is not detected.
+ * 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 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,74 @@
-import { MINIMAL_ANTHROPIC_OAUTH_PROMPT, PI_DEFAULT_PROMPT_PREFIX, } 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
+ * known Anthropic classifier trigger phrases.
+ *
+ * A paragraph is any text between blank lines (`\n\n`).
+ *
+ * This approach is resilient to upstream rewording — as long as the anchor
+ * string still appears somewhere in the paragraph, removal works regardless
+ * of how the surrounding text changes.
+ */
+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)) {
+                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 {
+        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);
@@ -6,14 +76,52 @@ function findProjectContextStart(systemPrompt) {
 /**
  * Shape a system prompt string for Anthropic OAuth compatibility.
  *
- * Replaces Pi's verbose default preamble with a minimal neutral prompt while
- * preserving any project context that follows.  Returns the original string
- * unchanged when Pi's default preamble is not detected.
+ * 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 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 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;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gotgenes/pi-anthropic-auth",
-  "version": "0.3.0",
+  "version": "0.4.1",
   "description": "Pi extension package for Anthropic OAuth compatibility",
   "author": {
     "name": "Chris Lasher"
@@ -38,7 +38,8 @@
     "lint:md": "markdownlint-cli2 '*.md'",
     "lint:all": "pnpm run lint && pnpm run lint:md",
     "format": "biome format --write .",
-    "test": "tsx --test test/**/*.test.ts",
+    "test": "vitest run",
+    "test:watch": "vitest",
     "prepublishOnly": "pnpm run check && pnpm run test && pnpm run build"
   },
   "pi": {
@@ -56,7 +57,7 @@
     "@mariozechner/pi-ai": "^0.68.0",
     "@mariozechner/pi-coding-agent": "^0.68.0",
     "markdownlint-cli2": "^0.22.0",
-    "tsx": "^4.20.6",
-    "typescript": "^6.0.3"
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.5"
   }
 }