@docyrus/docyrus 0.0.22 → 0.0.24

package/resources/pi-agent/extensions/pi-custom-compaction/events/register-events.ts

@@ -0,0 +1,229 @@
+import type { Api, Model } from "@mariozechner/pi-ai";
+import { compact, type ExtensionAPI, type ExtensionContext, type SessionBeforeCompactEvent } from "@mariozechner/pi-coding-agent";
+import type { ISummaryPolicy } from "../policy/types.js";
+import {
+  computeFileLists,
+  formatFileOperations,
+  generateTemplateSummary,
+  generateTurnPrefixSummary,
+  getReserveTokens,
+} from "../summary/generate.js";
+import { buildSummaryPrompt, discoverTemplate, resolveSummarySettings } from "../summary/template.js";
+import { getLastAssistantMessage, resolveSummaryModel } from "../runtime/model-resolution.js";
+import { resolveEffectivePolicy, shouldTriggerProactiveCompact } from "../runtime/pure.js";
+import type { IRuntimeServices } from "../runtime/session-state.js";
+
+async function generateCustomCompaction(
+  event: SessionBeforeCompactEvent,
+  template: string,
+  updateTemplate: string | undefined,
+  summarySettings: ISummaryPolicy,
+  model: Model<Api>,
+  apiKey: string,
+) {
+  const reserveTokens = getReserveTokens(event);
+  const summaryPrompt = buildSummaryPrompt(
+    template,
+    updateTemplate,
+    event.preparation.previousSummary,
+    event.customInstructions,
+    summarySettings.preservationInstruction,
+  );
+  const historySummary =
+		event.preparation.messagesToSummarize.length > 0
+		  ? await generateTemplateSummary(
+		    event.preparation.messagesToSummarize,
+		    model,
+		    apiKey,
+		    summaryPrompt,
+		    reserveTokens,
+		    event.signal,
+		    summarySettings.thinkingLevel,
+		    event.preparation.previousSummary,
+			  )
+		  : event.preparation.previousSummary ?? "No prior history.";
+  if (!historySummary.trim()) {
+    throw new Error("Custom template summarization returned empty summary");
+  }
+
+  const turnPrefixSummary =
+		event.preparation.isSplitTurn && event.preparation.turnPrefixMessages.length > 0
+		  ? await generateTurnPrefixSummary(
+		    event.preparation.turnPrefixMessages,
+		    model,
+		    apiKey,
+		    reserveTokens,
+		    event.signal,
+		    summarySettings.thinkingLevel,
+			  )
+		  : undefined;
+  if (turnPrefixSummary !== undefined && !turnPrefixSummary.trim()) {
+    throw new Error("Turn prefix summarization returned empty summary");
+  }
+
+  const mergedSummary = turnPrefixSummary
+    ? `${historySummary}\n\n---\n\n**Turn Context (split turn):**\n\n${turnPrefixSummary}`
+    : historySummary;
+  const details = computeFileLists(event.preparation.fileOps);
+  const summary = `${mergedSummary}${formatFileOperations(details)}`;
+  return {
+    summary,
+    firstKeptEntryId: event.preparation.firstKeptEntryId,
+    tokensBefore: event.preparation.tokensBefore,
+    details,
+  };
+}
+
+function initializeSessionStatus(ctx: ExtensionContext, runtime: IRuntimeServices): void {
+  const basePolicy = runtime.loadEffectivePolicy(ctx, { warnOnInvalidConfig: false });
+  if (!basePolicy.enabled) {return;}
+  const { policy, profileName } = resolveEffectivePolicy(ctx, basePolicy);
+  runtime.setActiveProfileName(profileName);
+  runtime.updateStatus(ctx, policy);
+}
+
+export function registerEvents(pi: ExtensionAPI, runtime: IRuntimeServices): void {
+  pi.on("agent_end", async(event, ctx) => {
+    const basePolicy = runtime.loadEffectivePolicy(ctx, { warnOnInvalidConfig: false });
+    if (!basePolicy.enabled) {
+      runtime.clearInFlight();
+      runtime.setActiveProfileName(undefined);
+      runtime.updateStatus(ctx, basePolicy);
+      return;
+    }
+
+    const { policy, profileName } = resolveEffectivePolicy(ctx, basePolicy);
+    runtime.setActiveProfileName(profileName);
+
+    const shouldTrigger = shouldTriggerProactiveCompact({
+      lastAssistantMessage: getLastAssistantMessage(event.messages),
+      usage: ctx.getContextUsage(),
+      inFlight: runtime.isInFlight(),
+      nowMs: Date.now(),
+      lastProactiveAtMs: runtime.getLastProactiveAtMs(),
+      policy,
+    });
+    if (!shouldTrigger) {
+      runtime.updateStatus(ctx, policy);
+      return;
+    }
+
+    const triggered = runtime.triggerCompaction(ctx, policy, "proactive");
+    if (triggered) {
+      runtime.setLastProactiveAtMs(Date.now());
+    }
+  });
+
+  pi.on("session_before_compact", async(event, ctx) => {
+    const basePolicy = runtime.loadEffectivePolicy(ctx, { warnOnInvalidConfig: false });
+    if (!basePolicy.enabled) {
+      runtime.clearInFlight();
+      runtime.setActiveProfileName(undefined);
+      runtime.updateStatus(ctx, basePolicy);
+      return undefined;
+    }
+
+    const { policy, profileName, profileTemplates } = resolveEffectivePolicy(ctx, basePolicy);
+    runtime.setActiveProfileName(profileName);
+    runtime.setInFlight("session_before_compact");
+    runtime.updateStatus(ctx, policy);
+
+    const resolved = await resolveSummaryModel(ctx, policy, runtime.notify);
+    if (!resolved) {
+      runtime.clearInFlight();
+      return undefined;
+    }
+
+    const summarySettings = resolveSummarySettings(policy, resolved.entry);
+    const templateResolution = discoverTemplate(ctx.cwd, profileName, profileTemplates);
+    if (templateResolution.fallbackReason) {
+      runtime.notify(
+        ctx,
+        policy,
+        "warning",
+        `Could not load summary template ${templateResolution.resolvedPath} (${templateResolution.fallbackReason}). Falling back to built-in compaction format.`,
+        { dedupeKey: `template-fallback:${templateResolution.resolvedPath}:${templateResolution.fallbackReason}` },
+      );
+    }
+    if (templateResolution.updateFallbackReason) {
+      runtime.notify(
+        ctx,
+        policy,
+        "warning",
+        `Could not load update summary template ${templateResolution.updateResolvedPath} (${templateResolution.updateFallbackReason}). Falling back to initial summary template.`,
+        {
+          dedupeKey: `template-update-fallback:${templateResolution.updateResolvedPath}:${templateResolution.updateFallbackReason}`,
+        },
+      );
+    }
+
+    try {
+      const result = templateResolution.template
+        ? await generateCustomCompaction(
+          event,
+          templateResolution.template,
+          templateResolution.updateTemplate,
+          summarySettings,
+          resolved.model,
+          resolved.apiKey,
+				  )
+        : await compact(
+          event.preparation,
+          resolved.model,
+          resolved.apiKey,
+          event.customInstructions,
+          event.signal,
+				  );
+
+      return {
+        compaction: {
+          summary: result.summary,
+          tokensBefore: result.tokensBefore,
+          details: result.details,
+          firstKeptEntryId: result.firstKeptEntryId,
+        },
+      };
+    } catch (error) {
+      runtime.clearInFlight();
+      if (event.signal.aborted) {return undefined;}
+      const message = error instanceof Error ? error.message : String(error);
+      runtime.notify(ctx, policy, "error", `Compaction policy summary failed: ${message}`, {
+        critical: true,
+      });
+      return undefined;
+    }
+  });
+
+  pi.on("session_compact", async(_event, ctx) => {
+    runtime.clearInFlight();
+    runtime.markPostCompact();
+    const basePolicy = runtime.loadEffectivePolicy(ctx, { warnOnInvalidConfig: false });
+    const { policy, profileName } = resolveEffectivePolicy(ctx, basePolicy);
+    runtime.setActiveProfileName(profileName);
+    runtime.updateStatus(ctx, policy);
+  });
+
+  pi.on("session_start", async(_event, ctx) => {
+    runtime.clearSessionScopedState(ctx);
+    initializeSessionStatus(ctx, runtime);
+  });
+
+  pi.on("session_switch", async(_event, ctx) => {
+    runtime.clearSessionScopedState(ctx);
+    initializeSessionStatus(ctx, runtime);
+  });
+
+  pi.on("session_fork", async(_event, ctx) => {
+    runtime.clearSessionScopedState(ctx);
+    initializeSessionStatus(ctx, runtime);
+  });
+
+  pi.on("session_tree", async(_event, ctx) => {
+    runtime.clearSessionScopedState(ctx);
+    initializeSessionStatus(ctx, runtime);
+  });
+
+  pi.on("session_shutdown", async(_event, ctx) => {
+    runtime.clearSessionScopedState(ctx);
+  });
+}

package/resources/pi-agent/extensions/pi-custom-compaction/index.ts

@@ -0,0 +1,10 @@
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import { registerCommands } from "./commands/register-commands.js";
+import { registerEvents } from "./events/register-events.js";
+import { createRuntimeServices } from "./runtime/session-state.js";
+
+export default function compactionPolicyExtension(pi: ExtensionAPI) {
+  const runtime = createRuntimeServices();
+  registerCommands(pi, runtime);
+  registerEvents(pi, runtime);
+}

package/resources/pi-agent/extensions/pi-custom-compaction/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "pi-custom-compaction",
+  "version": "0.2.0",
+  "description": "Custom compaction for pi — swap the model, template, and trigger for context compaction",
+  "keywords": [
+    "pi-package",
+    "pi",
+    "pi-coding-agent",
+    "compaction",
+    "context-management",
+    "extension"
+  ],
+  "homepage": "https://github.com/nicobailon/pi-custom-compaction#readme",
+  "bugs": {
+    "url": "https://github.com/nicobailon/pi-custom-compaction/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/nicobailon/pi-custom-compaction.git"
+  },
+  "license": "MIT",
+  "author": "Nico Bailon",
+  "type": "module",
+  "files": [
+    "index.ts",
+    "commands/register-commands.ts",
+    "events/register-events.ts",
+    "policy/config.ts",
+    "policy/merge.ts",
+    "policy/parse.ts",
+    "policy/types.ts",
+    "runtime/model-resolution.ts",
+    "runtime/pure.ts",
+    "runtime/session-state.ts",
+    "summary/generate.ts",
+    "summary/template.ts",
+    "banner.png",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "tsx --test test/**/*.test.ts"
+  },
+  "devDependencies": {
+    "@mariozechner/pi-agent-core": "^0.57.1",
+    "@mariozechner/pi-ai": "^0.57.1",
+    "@mariozechner/pi-coding-agent": "^0.57.1",
+    "@mariozechner/pi-tui": "^0.57.1",
+    "tsx": "^4.20.5"
+  },
+  "pi": {
+    "extensions": [
+      "./index.ts"
+    ]
+  }
+}

package/resources/pi-agent/extensions/pi-custom-compaction/paths.ts

@@ -0,0 +1,13 @@
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+const LEGACY_PI_AGENT_ROOT = join(homedir(), ".pi", "agent");
+
+export function resolveAgentRootPath(): string {
+  const agentDir = process.env.PI_CODING_AGENT_DIR?.trim();
+  return agentDir && agentDir.length > 0 ? agentDir : LEGACY_PI_AGENT_ROOT;
+}
+
+export function resolveGlobalCompactionPolicyPath(): string {
+  return join(resolveAgentRootPath(), "compaction-policy.json");
+}

package/resources/pi-agent/extensions/pi-custom-compaction/policy/config.ts

@@ -0,0 +1,32 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { parsePolicyPatch } from "./parse.js";
+import { resolveGlobalCompactionPolicyPath } from "../paths.js";
+import {
+  CONFIG_FILE,
+  type ICompactionPolicyPatch,
+  type IParseResult,
+} from "./types.js";
+
+function readConfigFile(configPath: string): IParseResult<ICompactionPolicyPatch> {
+  try {
+    const raw = readFileSync(configPath, "utf8");
+    const json = JSON.parse(raw);
+    const parsed = parsePolicyPatch(json);
+    if (!parsed.ok) {
+      return { ok: false, error: `Invalid ${configPath}: ${parsed.error}` };
+    }
+    return parsed;
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return { ok: false, error: `Invalid ${configPath}: ${message}` };
+  }
+}
+
+export function readProjectPolicyPatch(cwd: string): IParseResult<ICompactionPolicyPatch> {
+  const globalConfigPath = resolveGlobalCompactionPolicyPath();
+  const projectPath = join(cwd, CONFIG_FILE);
+  if (existsSync(projectPath)) {return readConfigFile(projectPath);}
+  if (existsSync(globalConfigPath)) {return readConfigFile(globalConfigPath);}
+  return { ok: true, value: {} };
+}

package/resources/pi-agent/extensions/pi-custom-compaction/policy/merge.ts

@@ -0,0 +1,67 @@
+import type {
+  ICompactionPolicy,
+  ICompactionPolicyPatch,
+  IPolicyKey,
+  IProfileOverride,
+  ISummaryThinkingLevel,
+} from "./types.js";
+
+export function setPatchValue(patch: ICompactionPolicyPatch, key: IPolicyKey, value: unknown): void {
+  switch (key) {
+    case "trigger.maxTokens":
+      patch.trigger = { ...patch.trigger, maxTokens: value as number };
+      return;
+    case "trigger.minTokens":
+      patch.trigger = { ...patch.trigger, minTokens: value as number };
+      return;
+    case "trigger.cooldownMs":
+      patch.trigger = { ...patch.trigger, cooldownMs: value as number };
+      return;
+    case "trigger.builtinReserveTokens":
+      patch.trigger = { ...patch.trigger, builtinReserveTokens: value as number };
+      return;
+    case "trigger.builtinSkipMarginPercent":
+      patch.trigger = { ...patch.trigger, builtinSkipMarginPercent: value as number };
+      return;
+    case "ui.name":
+      patch.ui = { ...patch.ui, name: value as string };
+      return;
+    case "ui.quiet":
+      patch.ui = { ...patch.ui, quiet: value as boolean };
+      return;
+    case "ui.showStatus":
+      patch.ui = { ...patch.ui, showStatus: value as boolean };
+      return;
+    case "ui.minimalStatus":
+      patch.ui = { ...patch.ui, minimalStatus: value as boolean };
+      return;
+    case "summary.thinkingLevel":
+      patch.summary = { ...patch.summary, thinkingLevel: value as ISummaryThinkingLevel };
+      return;
+    case "summary.preservationInstruction":
+      patch.summary = { ...patch.summary, preservationInstruction: value as string };
+      return;
+    default:
+      return;
+  }
+}
+
+export function mergePolicy(base: ICompactionPolicy, patch: ICompactionPolicyPatch): ICompactionPolicy {
+  return {
+    enabled: patch.enabled ?? base.enabled,
+    trigger: { ...base.trigger, ...(patch.trigger ?? {}) },
+    models: patch.models ?? base.models,
+    ui: { ...base.ui, ...(patch.ui ?? {}) },
+    summary: { ...base.summary, ...(patch.summary ?? {}) },
+    profiles: patch.profiles !== undefined ? patch.profiles : base.profiles,
+  };
+}
+
+export function applyProfileOverrides(policy: ICompactionPolicy, profile: IProfileOverride): ICompactionPolicy {
+  return {
+    ...policy,
+    trigger: { ...policy.trigger, ...(profile.trigger ?? {}) },
+    models: profile.models ?? policy.models,
+    summary: { ...policy.summary, ...(profile.summary ?? {}) },
+  };
+}