decorated-pi 0.5.4 → 0.6.0

package/hooks/compaction.ts

@@ -0,0 +1,204 @@
+/**
+ * compaction — custom compaction model + auto-resume.
+ *
+ * Uses the configured compact model (from settings.ts) to summarize messages
+ * on session_before_compact. After auto-compaction, sends a "continue" message
+ * to resume the agent loop.
+ */
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { generateSummary, convertToLlm, serializeConversation } from "@earendil-works/pi-coding-agent";
+import type { Model } from "@earendil-works/pi-ai";
+import { isContextOverflow } from "@earendil-works/pi-ai";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import { resolve } from "node:path";
+import { getCompactModelKey } from "../settings.js";
+import { parseModelKey } from "../settings.js";
+import type { Module, Skeleton } from "./skeleton.js";
+
+interface PiCompactionSettings {
+  enabled: boolean;
+  reserveTokens: number;
+}
+
+interface AutoCompactionCandidate {
+  messages: any[];
+  usage: { tokens: number | null; contextWindow: number } | undefined;
+}
+
+const DEFAULT_PI_COMPACTION_SETTINGS: PiCompactionSettings = {
+  enabled: true,
+  reserveTokens: 16_384,
+};
+
+function readJsonObject(filePath: string): any | undefined {
+  try {
+    if (!fs.existsSync(filePath)) return undefined;
+    const parsed = JSON.parse(fs.readFileSync(filePath, "utf-8"));
+    return parsed && typeof parsed === "object" ? parsed : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+function loadPiCompactionSettings(cwd: string): PiCompactionSettings {
+  const globalSettings = readJsonObject(resolve(os.homedir(), ".pi", "agent", "settings.json"));
+  const projectSettings = readJsonObject(resolve(cwd, ".pi", "settings.json"));
+  const merged = {
+    ...DEFAULT_PI_COMPACTION_SETTINGS,
+    ...(globalSettings?.compaction ?? {}),
+    ...(projectSettings?.compaction ?? {}),
+  };
+  return {
+    enabled: merged.enabled !== false,
+    reserveTokens: typeof merged.reserveTokens === "number" ? merged.reserveTokens : DEFAULT_PI_COMPACTION_SETTINGS.reserveTokens,
+  };
+}
+
+function getLastAssistantMessage(messages: any[]): any | undefined {
+  for (let i = messages.length - 1; i >= 0; i--) {
+    if (messages[i]?.role === "assistant") return messages[i];
+  }
+  return undefined;
+}
+
+function shouldExpectAutoCompaction(
+  messages: any[],
+  usage: { tokens: number | null; contextWindow: number } | undefined,
+  settings: PiCompactionSettings,
+): boolean {
+  if (!settings.enabled) return false;
+  const lastAssistant = getLastAssistantMessage(messages);
+  if (!lastAssistant) return false;
+  const contextWindow = usage?.contextWindow ?? 0;
+  if (contextWindow > 0 && isContextOverflow(lastAssistant, contextWindow)) return true;
+  if (!usage || usage.tokens === null) return false;
+  return usage.tokens > usage.contextWindow - settings.reserveTokens;
+}
+
+function shouldAutoResumeCompaction(
+  prePromptCompactionPending: boolean,
+  postAgentEndCandidate: AutoCompactionCandidate | null,
+  settings: PiCompactionSettings,
+  customInstructions?: string,
+): boolean {
+  if (customInstructions !== undefined) return false;
+  if (prePromptCompactionPending) return true;
+  if (!postAgentEndCandidate) return false;
+  return shouldExpectAutoCompaction(postAgentEndCandidate.messages, postAgentEndCandidate.usage, settings);
+}
+
+function getConfiguredCompactModel(registry: any): Model<any> | null {
+  const key = getCompactModelKey();
+  if (!key) return null;
+  const parsed = parseModelKey(key);
+  if (!parsed) return null;
+  return registry.find(parsed.provider, parsed.modelId) ?? null;
+}
+
+const TURN_PREFIX_PROMPT = `Summarize this turn prefix to provide context for the retained suffix. Be concise. Focus on what's needed to understand the kept suffix.`;
+
+async function generateTurnPrefixSummary(
+  messages: any[], model: Model<any>, reserveTokens: number,
+  apiKey: string, headers: Record<string, string> | undefined, signal: AbortSignal,
+): Promise<string> {
+  const { complete } = await import("@earendil-works/pi-ai");
+  const ct = serializeConversation(convertToLlm(messages));
+  const resp = await complete(model, {
+    systemPrompt: "You are a context summarization assistant. Produce a structured summary only.",
+    messages: [{ role: "user" as const, content: [{ type: "text" as const, text: `<conversation>\n${ct}\n</conversation>\n\n${TURN_PREFIX_PROMPT}` }], timestamp: Date.now() }],
+  }, { maxTokens: Math.floor(0.5 * reserveTokens), signal, apiKey, headers });
+  if (resp.stopReason === "error") throw new Error(resp.errorMessage ?? "Turn prefix summarization failed");
+  return resp.content.filter((c): c is { type: "text"; text: string } => c.type === "text").map(c => c.text).join("\n");
+}
+
+let prePromptCompactionPending = false;
+let postAgentEndCandidate: AutoCompactionCandidate | null = null;
+let currentCompactionIsAuto = false;
+
+export const compactionModule: Module = {
+  name: "compaction",
+  hooks: {
+    input: [() => { prePromptCompactionPending = true; postAgentEndCandidate = null; }],
+    before_agent_start: [() => { prePromptCompactionPending = false; postAgentEndCandidate = null; }],
+    agent_start: [() => { prePromptCompactionPending = false; postAgentEndCandidate = null; }],
+    agent_end: [
+      (event, ctx) => {
+        prePromptCompactionPending = false;
+        postAgentEndCandidate = { messages: event.messages, usage: ctx.getContextUsage() };
+      },
+    ],
+    session_before_compact: [
+      async (event, ctx) => {
+        const compactionSettings = loadPiCompactionSettings(ctx.cwd);
+        const { isContextOverflow } = await import("@earendil-works/pi-ai");
+        const isAuto = shouldExpectAutoCompaction(
+          postAgentEndCandidate?.messages ?? [],
+          postAgentEndCandidate?.usage,
+          compactionSettings,
+        );
+        // For simplicity, treat session_before_compact as auto if recent agent_end was likely-overflow
+        // and no custom instructions given.
+        const isAutoResume = isAuto && !event.customInstructions;
+        currentCompactionIsAuto = isAutoResume;
+        prePromptCompactionPending = false;
+        postAgentEndCandidate = null;
+
+        const model = getConfiguredCompactModel(ctx.modelRegistry);
+        if (!model) return;
+        const auth = await ctx.modelRegistry.getApiKeyAndHeaders(model);
+        if (!auth.ok) {
+          if (ctx.hasUI) ctx.ui.notify(`Compact model auth failed: ${auth.error}`, "warning");
+          return;
+        }
+        const { preparation, customInstructions, signal } = event;
+        const { messagesToSummarize, turnPrefixMessages, isSplitTurn, tokensBefore, firstKeptEntryId, previousSummary, settings } = preparation;
+        if (ctx.hasUI) ctx.ui.notify(`🗜️ Compacting with ${model.id} (${tokensBefore.toLocaleString()} tokens)...`, "info");
+        try {
+          let summary: string;
+          if (isSplitTurn && turnPrefixMessages.length > 0) {
+            const [hs, ps] = await Promise.all([
+              messagesToSummarize.length > 0
+                ? generateSummary(messagesToSummarize, model, settings.reserveTokens, auth.apiKey ?? "", auth.headers, signal, customInstructions, previousSummary)
+                : Promise.resolve("No prior history."),
+              generateTurnPrefixSummary(turnPrefixMessages, model, settings.reserveTokens, auth.apiKey ?? "", auth.headers, signal),
+            ]);
+            summary = `${hs}\n\n---\n\n**Turn Context (split turn):**\n\n${ps}`;
+          } else {
+            summary = await generateSummary(messagesToSummarize, model, settings.reserveTokens, auth.apiKey ?? "", auth.headers, signal, customInstructions, previousSummary);
+          }
+          // session_before_compact is a parallel event — handlers may not
+          // return a value (skeleton discards compose returns for
+          // non-compose events). The summary is intentionally lost; the
+          // session_compact handler below only reads the
+          // currentCompactionIsAuto flag and does not consume the summary.
+        } catch (err) {
+          if (signal.aborted) return;
+          if (ctx.hasUI) ctx.ui.notify(`Compact failed: ${err instanceof Error ? err.message : err}`, "error");
+        }
+      },
+    ],
+    session_compact: [
+      (_event, _ctx, pi) => {
+        const shouldResume = currentCompactionIsAuto;
+        currentCompactionIsAuto = false;
+        if (!shouldResume) return;
+        pi.sendMessage({
+          customType: "auto_compact_resume",
+          content: "The context was just auto-compacted. Continue the current task based on the summary above. Do not repeat completed work. If unsure about progress, briefly summarize current state then continue.",
+          display: false,
+        }, { triggerTurn: true });
+      },
+    ],
+  },
+};
+
+export function setupCompaction(sk: Skeleton): void {
+  sk.register(compactionModule);
+}
+
+export const __modelIntegrationTest = {
+  shouldExpectAutoCompaction,
+  shouldAutoResumeCompaction,
+};

package/hooks/externalize.ts

@@ -0,0 +1,70 @@
+/**
+ * externalize — large tool_result → temp file.
+ *
+ * Keeps the messages segment small so the prompt cache stays warm across turns.
+ * Applies to ANY tool whose first text content exceeds OUTPUT_EXTERNALIZE_THRESHOLD
+ * bytes — read, bash, MCP tools, all the same. The tool name is preserved
+ * in the temp filename so users can correlate the truncation with the
+ * call that produced it.
+ */
+
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { randomBytes } from "node:crypto";
+import type { Module } from "./skeleton.js";
+
+export const TOOL_OUTPUT_TEMP_DIR = path.join(os.tmpdir(), "decorated-pi-results");
+export const OUTPUT_EXTERNALIZE_THRESHOLD = 30_000;
+
+/** Write content to a temp file under TOOL_OUTPUT_TEMP_DIR.
+ *  Returns the file path, or undefined on failure (e.g., /tmp full).
+ *  Exported so other modules (e.g. tools/mcp/externalize.ts) can
+ *  write to the same location. */
+export function writeOutputToTemp(
+  toolName: string,
+  toolCallId: string,
+  content: string,
+): string | undefined {
+  try {
+    if (!fs.existsSync(TOOL_OUTPUT_TEMP_DIR)) fs.mkdirSync(TOOL_OUTPUT_TEMP_DIR, { recursive: true });
+    const id = toolCallId ? toolCallId.slice(0, 12) : randomBytes(8).toString("hex");
+    const filePath = path.join(TOOL_OUTPUT_TEMP_DIR, `${toolName}-${id}.txt`);
+    fs.writeFileSync(filePath, content, "utf-8");
+    return filePath;
+  } catch {
+    return undefined;
+  }
+}
+
+/** Externalize a tool_result event if content is above the threshold.
+ *  Returns the modified event, or undefined to leave the original untouched. */
+export function maybeExternalizeToolResult(event: any): any | undefined {
+  if (!Array.isArray(event.content) || event.content.length === 0) return undefined;
+  const first = event.content[0];
+  if (!first || first.type !== "text" || typeof first.text !== "string") return undefined;
+  const text = first.text;
+  if (text.length <= OUTPUT_EXTERNALIZE_THRESHOLD) return undefined;
+
+  const filePath = writeOutputToTemp(event.toolName, event.toolCallId, text);
+  if (!filePath) return undefined;
+
+  return {
+    ...event,
+    content: [{
+      type: "text" as const,
+      text: `[Output truncated: ${text.length.toLocaleString()} chars. Full output: ${filePath}]`,
+    }],
+  };
+}
+
+export const externalizeModule: Module = {
+  name: "externalize",
+  hooks: {
+    tool_result: [
+      (event) => {
+        return maybeExternalizeToolResult(event);
+      },
+    ],
+  },
+};

package/hooks/image-vision.ts

@@ -0,0 +1,132 @@
+/**
+ * image-vision — when read is called on an image file, replace the result with
+ * a vision model analysis instead of returning raw bytes.
+ */
+
+import { fileTypeFromFile } from "file-type";
+import * as fs from "node:fs";
+import { extname, resolve } from "node:path";
+import OpenAI from "openai";
+import type { Model } from "@earendil-works/pi-ai";
+import { getImageModelKey, parseModelKey } from "../settings.js";
+import type { Module, Skeleton } from "./skeleton.js";
+
+const SUPPORTED_IMAGE_TYPES = new Set(["image/jpeg", "image/png", "image/gif", "image/webp"]);
+
+async function detectImageMimeType(filePath: string): Promise<string | null> {
+  try {
+    const type = await fileTypeFromFile(filePath);
+    if (!type || !SUPPORTED_IMAGE_TYPES.has(type.mime)) return null;
+    return type.mime;
+  } catch {
+    return null;
+  }
+}
+
+const DEFAULT_PROMPT = "Please describe this image in detail, including any text, diagrams, UI elements, or code visible in it.";
+
+export async function analyzeImage(
+  model: Model<any>, imageBase64: string, mediaType: string,
+  apiKey: string, extraHeaders: Record<string, string>,
+): Promise<string> {
+  if (model.api === "anthropic-messages") {
+    return analyzeAnthropic(model, imageBase64, mediaType, apiKey, extraHeaders);
+  }
+  return analyzeOpenAI(model, imageBase64, mediaType, apiKey, extraHeaders);
+}
+
+async function analyzeOpenAI(
+  model: Model<any>, imageBase64: string, mediaType: string,
+  apiKey: string, extraHeaders: Record<string, string>,
+): Promise<string> {
+  const client = new OpenAI({ apiKey, baseURL: model.baseUrl, defaultHeaders: extraHeaders });
+  const resp = await client.chat.completions.create({
+    model: model.id,
+    messages: [{ role: "user", content: [
+      { type: "text", text: DEFAULT_PROMPT },
+      { type: "image_url", image_url: { url: `data:${mediaType};base64,${imageBase64}` } },
+    ]}],
+    max_completion_tokens: 4096,
+  }, { signal: AbortSignal.timeout(60_000) });
+  return resp.choices[0]?.message?.content ?? "No analysis returned.";
+}
+
+async function analyzeAnthropic(
+  model: Model<any>, imageBase64: string, mediaType: string,
+  apiKey: string, extraHeaders: Record<string, string>,
+): Promise<string> {
+  const ep = `${model.baseUrl.replace(/\/+$/, "")}/messages`;
+  const resp = await fetch(ep, {
+    method: "POST",
+    headers: { "Content-Type": "application/json", "x-api-key": apiKey, "anthropic-version": "2023-06-01", ...extraHeaders },
+    body: JSON.stringify({
+      model: model.id, max_tokens: 4096,
+      messages: [{ role: "user", content: [
+        { type: "text", text: DEFAULT_PROMPT },
+        { type: "image", source: { type: "base64", media_type: mediaType, data: imageBase64 } },
+      ]}],
+    }),
+    signal: AbortSignal.timeout(60_000),
+  });
+  if (!resp.ok) throw new Error(`Vision API error ${resp.status}: ${(await resp.text()).slice(0, 300)}`);
+  const data = (await resp.json()) as any;
+  return data.content?.[0]?.text ?? "No analysis returned.";
+}
+
+const pendingImageFallbacks = new Set<string>();
+
+export const imageVisionModule: Module = {
+  name: "image-vision",
+  hooks: {
+    tool_call: [
+      async (event, ctx) => {
+        if (event.toolName !== "read") return;
+        const filePath: string | undefined = (event.input as any)?.file ?? (event.input as any)?.path;
+        if (!filePath) return;
+        const mimeType = await detectImageMimeType(resolve(ctx.cwd, filePath));
+        if (!mimeType) return;
+        if (!getImageModelKey()) return;
+        pendingImageFallbacks.add(event.toolCallId);
+      },
+    ],
+    tool_result: [
+      async (event, ctx) => {
+        if (!pendingImageFallbacks.delete(event.toolCallId)) return;
+        const filePath: string | undefined = (event.input as any)?.file ?? (event.input as any)?.path;
+        if (!filePath) return;
+        const imageKey = getImageModelKey();
+        if (!imageKey) return;
+        const parsed = parseModelKey(imageKey);
+        if (!parsed) return;
+        const imageModel = ctx.modelRegistry.find(parsed.provider, parsed.modelId);
+        if (!imageModel) return;
+        try {
+          const absPath = resolve(ctx.cwd, filePath);
+          const imageData = fs.readFileSync(absPath);
+          const imageBase64 = imageData.toString("base64");
+          const mimeType = (await detectImageMimeType(absPath)) ?? "image/png";
+          const auth = await ctx.modelRegistry.getApiKeyAndHeaders(imageModel as Model<any>);
+          if (!auth.ok) return;
+          const analysis = await analyzeImage(
+            imageModel as Model<any>, imageBase64, mimeType,
+            auth.apiKey ?? "", auth.headers ?? {},
+          );
+          return {
+            ...event,
+            content: [{ type: "text", text: `[Image analysis via ${parsed.provider}/${parsed.modelId}]\n\n${analysis}` }],
+            details: { imageModel: imageKey, originalPath: filePath },
+          };
+        } catch (error) {
+          return {
+            ...event,
+            content: [{ type: "text", text: `Image analysis failed: ${error instanceof Error ? error.message : error}` }],
+          };
+        }
+      },
+    ],
+  },
+};
+
+export function setupImageVision(sk: Skeleton): void {
+  sk.register(imageVisionModule);
+}

package/hooks/inject-agents-md.ts

@@ -0,0 +1,164 @@
+/**
+ * inject-agents-md — when read/edit is called, scan parent dirs for AGENTS.md/CLAUDE.md
+ * and inject their content into the tool result so the LLM sees the relevant context.
+ *
+ * State is persisted to session via pi.appendEntry so it survives resume/reload.
+ */
+
+import { dirname, resolve, relative, join, normalize } from "node:path";
+import { existsSync, readFileSync } from "node:fs";
+import type { Module } from "./skeleton.js";
+
+const CUSTOM_TYPE = "decorated-pi.subdir-agents";
+const AGENTS_NAMES = ["AGENTS.md", "AGENTS.MD", "CLAUDE.md", "CLAUDE.MD"];
+
+interface SessionLikeEntry {
+    type: string;
+    customType?: string;
+    data?: unknown;
+}
+
+const discovered = new Set<string>();
+const pendingPaths = new Map<string, string>();
+let lastCwd = "";
+
+function normalizeAbsPath(cwd: string, p: string): string {
+    return normalize(resolve(cwd, p));
+}
+
+function lastCompactionIndex(entries: SessionLikeEntry[]): number {
+    for (let i = entries.length - 1; i >= 0; i--) {
+        if (entries[i]?.type === "compaction") return i;
+    }
+    return -1;
+}
+
+function restoreFromBranch(ctx: {
+    cwd: string;
+    sessionManager: { getBranch: () => Array<SessionLikeEntry> };
+}) {
+    discovered.clear();
+    const branch = ctx.sessionManager.getBranch();
+    const start = lastCompactionIndex(branch) + 1;
+    for (const entry of branch.slice(start)) {
+        if (entry.type !== "custom" || entry.customType !== CUSTOM_TYPE)
+            continue;
+        const paths = entry.data as string[] | undefined;
+        if (!Array.isArray(paths)) continue;
+        for (const p of paths) {
+            if (typeof p === "string" && p.trim()) {
+                discovered.add(normalizeAbsPath(ctx.cwd, p));
+            }
+        }
+    }
+}
+
+function findNewAgents(
+    filePath: string,
+    cwd: string,
+): Array<{ path: string; content: string }> {
+    const resolvedCwd = resolve(cwd);
+    let dir = dirname(resolve(cwd, filePath));
+    const results: Array<{ path: string; content: string }> = [];
+
+    while (true) {
+        const rel = relative(resolvedCwd, dir);
+        if (rel === "" || rel.startsWith("..")) break;
+
+        for (const name of AGENTS_NAMES) {
+            const agentsPath = normalize(join(dir, name));
+            if (existsSync(agentsPath) && !discovered.has(agentsPath)) {
+                try {
+                    const content = readFileSync(agentsPath, "utf-8");
+                    discovered.add(agentsPath);
+                    results.push({ path: relative(cwd, agentsPath), content });
+                } catch {
+                    /* ignore */
+                }
+            }
+        }
+
+        const parent = dirname(dir);
+        if (parent === dir) break;
+        dir = parent;
+    }
+
+    return results.reverse();
+}
+
+export const __subdirAgentsTest = { restoreFromBranch, findNewAgents };
+
+export const injectAgentsMdModule: Module = {
+    name: "inject-agents-md",
+    hooks: {
+        session_start: [
+            (_event, ctx) => {
+                lastCwd = ctx.cwd;
+                restoreFromBranch({
+                    cwd: ctx.cwd,
+                    sessionManager: ctx.sessionManager as any,
+                });
+            },
+        ],
+        session_compact: [
+            () => {
+                discovered.clear();
+                pendingPaths.clear();
+            },
+        ],
+        tool_call: [
+            (event) => {
+                if (event.toolName !== "read" && event.toolName !== "edit")
+                    return;
+                const path = (event.input as { path?: string })?.path;
+                if (path) pendingPaths.set(event.toolCallId, path);
+            },
+        ],
+        tool_result: [
+            (event, ctx, pi) => {
+                const path = pendingPaths.get(event.toolCallId);
+                pendingPaths.delete(event.toolCallId);
+                if (!path || !event.content || !Array.isArray(event.content))
+                    return;
+                const cwd = ctx.cwd ?? lastCwd;
+                const agents = findNewAgents(path, cwd);
+                if (agents.length === 0) return;
+
+                const injections = agents
+                    .map((a) => `[Directory Context: ${a.path}]\n${a.content}`)
+                    .join("\n\n---\n\n");
+                const names = agents.map((a) => a.path).join(", ");
+                const label =
+                    agents.length === 1 ? "AGENTS.md" : "AGENTS.md files";
+                if (ctx.hasUI)
+                    ctx.ui.notify(`📋 Loaded ${label}: ${names}`, "info");
+
+                const relativePaths = agents
+                    .map((a) => resolve(cwd, a.path))
+                    .map((p) => relative(cwd, p));
+                pi.appendEntry(CUSTOM_TYPE, relativePaths);
+
+                const newContent = [...event.content];
+                newContent.push({ type: "text", text: `\n\n${injections}` });
+                return { ...event, content: newContent };
+            },
+        ],
+        session_shutdown: [
+            () => {
+                discovered.clear();
+                pendingPaths.clear();
+                lastCwd = "";
+            },
+        ],
+    },
+};
+
+/**
+ * System-prompt guidance for the inject-agents-md hook — tells the
+ * LLM not to waste tool calls re-reading AGENTS.md / CLAUDE.md, since
+ * this hook already auto-injects them.
+ */
+export const INJECT_AGENTS_MD_GUIDANCE = [
+    "### Context Loading, AGENTS.md / CLAUDE.md are auto-injected",
+    "- DO NOT read any **AGENTS.md** or **CLAUDE.md** files unless you're explicitly asked to, these files will loaded automatically if necessary.",
+].join("\n");