@docyrus/docyrus 0.0.22 → 0.0.23

package/resources/pi-agent/extensions/pi-custom-compaction/runtime/session-state.ts

@@ -0,0 +1,244 @@
+import type { ExtensionContext } from "@mariozechner/pi-coding-agent";
+import { Loader } from "@mariozechner/pi-tui";
+import { mergePolicy } from "../policy/merge.js";
+import { readProjectPolicyPatch } from "../policy/config.js";
+import { DEFAULT_POLICY, type ICompactionPolicy } from "../policy/types.js";
+
+const STATUS_KEY = "compact-policy";
+const WATCHDOG_MS = 120_000;
+
+interface IInFlightState {
+	active: boolean;
+	source: string;
+	timerId: NodeJS.Timeout | undefined;
+}
+
+export interface IRuntimeServices {
+	clearInFlight: () => void;
+	setInFlight: (source: string) => void;
+	isInFlight: () => boolean;
+	getLastProactiveAtMs: () => number | undefined;
+	setLastProactiveAtMs: (value: number | undefined) => void;
+	setActiveProfileName: (name: string | undefined) => void;
+	markPostCompact: () => void;
+	notify: (
+		ctx: ExtensionContext,
+		policy: ICompactionPolicy,
+		level: "info" | "warning" | "error",
+		message: string,
+		options?: { critical?: boolean; dedupeKey?: string },
+	) => boolean;
+	updateStatus: (ctx: ExtensionContext, policy: ICompactionPolicy) => void;
+	clearSessionScopedState: (ctx: ExtensionContext) => void;
+	loadEffectivePolicy: (
+		ctx: ExtensionContext,
+		options?: {
+			warnOnInvalidConfig?: boolean;
+		},
+	) => ICompactionPolicy;
+	triggerCompaction: (
+		ctx: ExtensionContext,
+		policy: ICompactionPolicy,
+		source: string,
+		customInstructions?: string,
+	) => boolean;
+}
+
+export function createRuntimeServices(): IRuntimeServices {
+  const inFlight: IInFlightState = { active: false, source: "", timerId: undefined };
+  let lastProactiveAtMs: number | undefined;
+  let activeProfileName: string | undefined;
+  let configWarningLatched = false;
+  const warnedReasons = new Set<string>();
+  let widgetCtx: ExtensionContext | undefined;
+  let postCompact = false;
+  const WIDGET_KEY = "compact-loader";
+
+  function showCompactionWidget(ctx: ExtensionContext) {
+    hideCompactionWidget();
+    ctx.ui.setWidget(WIDGET_KEY, (tui, theme) => {
+      const loader = new Loader(
+        tui,
+        (s) => theme.fg("accent", s),
+        (t) => theme.fg("muted", t),
+        "Compacting…",
+      );
+      return Object.assign(loader, { dispose: () => loader.stop() });
+    });
+    widgetCtx = ctx;
+  }
+
+  function hideCompactionWidget() {
+    if (!widgetCtx) {return;}
+    widgetCtx.ui.setWidget(WIDGET_KEY, undefined);
+    widgetCtx = undefined;
+  }
+
+  function clearInFlight() {
+    if (inFlight.timerId) {
+      clearTimeout(inFlight.timerId);
+      inFlight.timerId = undefined;
+    }
+    inFlight.active = false;
+    inFlight.source = "";
+  }
+
+  function setInFlight(source: string) {
+    clearInFlight();
+    inFlight.active = true;
+    inFlight.source = source;
+    inFlight.timerId = setTimeout(() => {
+      clearInFlight();
+      hideCompactionWidget();
+    }, WATCHDOG_MS);
+  }
+
+  function notify(
+    ctx: ExtensionContext,
+    policy: ICompactionPolicy,
+    level: "info" | "warning" | "error",
+    message: string,
+    options?: { critical?: boolean; dedupeKey?: string },
+  ): boolean {
+    if (policy.ui.quiet && !options?.critical && level !== "error") {return false;}
+    if (options?.dedupeKey) {
+      if (warnedReasons.has(options.dedupeKey)) {return false;}
+      warnedReasons.add(options.dedupeKey);
+    }
+    ctx.ui.notify(message, level);
+    return true;
+  }
+
+  function updateStatus(ctx: ExtensionContext, policy: ICompactionPolicy) {
+    if (!policy.enabled || !policy.ui.showStatus) {
+      ctx.ui.setStatus(STATUS_KEY, undefined);
+      return;
+    }
+
+    const base = policy.ui.name;
+    const prefix = activeProfileName ? `${base}: ${activeProfileName}` : base;
+
+    if (inFlight.active) {
+      ctx.ui.setStatus(STATUS_KEY, `${prefix} · compacting…`);
+      return;
+    }
+
+    const usage = ctx.getContextUsage();
+
+    if (!usage || usage.tokens === null) {
+      ctx.ui.setStatus(STATUS_KEY, postCompact ? prefix : `${prefix} · ?`);
+      return;
+    }
+    postCompact = false;
+
+    const { maxTokens } = policy.trigger;
+    const limit = maxTokens && maxTokens > 0 && maxTokens < usage.contextWindow
+      ? maxTokens
+      : usage.contextWindow;
+    const pct = limit > 0 ? (usage.tokens / limit) * 100 : 0;
+
+    ctx.ui.setStatus(
+      STATUS_KEY,
+      policy.ui.minimalStatus
+        ? `${prefix} · ${pct.toFixed(0)}%`
+        : `${prefix} · ${pct.toFixed(1)}% (${usage.tokens}/${limit})`,
+    );
+  }
+
+  function loadEffectivePolicy(
+    ctx: ExtensionContext,
+    options?: {
+			warnOnInvalidConfig?: boolean;
+		},
+  ): ICompactionPolicy {
+    const result = readProjectPolicyPatch(ctx.cwd);
+    if (result.ok) {
+      configWarningLatched = false;
+      return mergePolicy(DEFAULT_POLICY, result.value);
+    }
+    if (options?.warnOnInvalidConfig !== false && !configWarningLatched) {
+      const emitted = notify(
+        ctx,
+        DEFAULT_POLICY,
+        "warning",
+        `${result.error}. Using built-in defaults.`,
+      );
+      if (emitted) {configWarningLatched = true;}
+    }
+    return DEFAULT_POLICY;
+  }
+
+  function clearSessionScopedState(ctx: ExtensionContext) {
+    clearInFlight();
+    hideCompactionWidget();
+    lastProactiveAtMs = undefined;
+    activeProfileName = undefined;
+    postCompact = false;
+    configWarningLatched = false;
+    warnedReasons.clear();
+    ctx.ui.setStatus(STATUS_KEY, undefined);
+  }
+
+  function triggerCompaction(
+    ctx: ExtensionContext,
+    policy: ICompactionPolicy,
+    source: string,
+    customInstructions?: string,
+  ): boolean {
+    if (inFlight.active) {
+      notify(ctx, policy, "warning", `Compaction already in progress (${inFlight.source}).`);
+      updateStatus(ctx, policy);
+      return false;
+    }
+
+    setInFlight(source);
+    try {
+      showCompactionWidget(ctx);
+      ctx.compact({
+        customInstructions,
+        onComplete: () => {
+          clearInFlight();
+          hideCompactionWidget();
+          updateStatus(ctx, policy);
+        },
+        onError: (error) => {
+          clearInFlight();
+          hideCompactionWidget();
+          const message = error instanceof Error ? error.message : String(error);
+          notify(ctx, policy, "error", `Compaction failed: ${message}`, { critical: true });
+          updateStatus(ctx, policy);
+        },
+      });
+    } catch (error) {
+      clearInFlight();
+      hideCompactionWidget();
+      const message = error instanceof Error ? error.message : String(error);
+      notify(ctx, policy, "error", `Compaction failed: ${message}`, { critical: true });
+      updateStatus(ctx, policy);
+      return false;
+    }
+    updateStatus(ctx, policy);
+    return true;
+  }
+
+  return {
+    clearInFlight,
+    setInFlight,
+    isInFlight: () => inFlight.active,
+    getLastProactiveAtMs: () => lastProactiveAtMs,
+    setLastProactiveAtMs: (value: number | undefined) => {
+      lastProactiveAtMs = value;
+    },
+    setActiveProfileName: (name: string | undefined) => {
+      activeProfileName = name;
+    },
+    markPostCompact: () => {
+      postCompact = true;
+    },
+    notify,
+    updateStatus,
+    clearSessionScopedState,
+    loadEffectivePolicy,
+    triggerCompaction,
+  };
+}

package/resources/pi-agent/extensions/pi-custom-compaction/summary/generate.ts

@@ -0,0 +1,184 @@
+import type { AgentMessage } from "@mariozechner/pi-agent-core";
+import { completeSimple } from "@mariozechner/pi-ai";
+import type { Api, Model } from "@mariozechner/pi-ai";
+import {
+  convertToLlm,
+  serializeConversation,
+  type SessionBeforeCompactEvent,
+} from "@mariozechner/pi-coding-agent";
+import type { ICompactionDetails, ISummaryThinkingLevel } from "../policy/types.js";
+
+const SUMMARIZATION_SYSTEM_PROMPT = `You are a context summarization assistant. Your task is to read a conversation between a user and an AI coding assistant, then produce a structured summary following the exact format specified.
+
+Do NOT continue the conversation. Do NOT respond to any questions in the conversation. ONLY output the structured summary.`;
+
+const TURN_PREFIX_SUMMARIZATION_PROMPT = `This is the PREFIX of a turn that was too large to keep. The SUFFIX (recent work) is retained.
+
+Summarize the prefix to provide context for the retained suffix:
+
+## Original Request
+[What did the user ask for in this turn?]
+
+## Early Progress
+- [Key decisions and work done in the prefix]
+
+## Context for Suffix
+- [Information needed to understand the kept suffix]
+
+Be concise. Focus on what's needed to understand the retained recent work.`;
+
+export async function generateTemplateSummary(
+  messages: AgentMessage[],
+  model: Model<Api>,
+  apiKey: string,
+  promptText: string,
+  reserveTokens: number,
+  signal: AbortSignal,
+  thinkingLevel: ISummaryThinkingLevel,
+  previousSummary?: string,
+): Promise<string> {
+  const llmMessages = convertToLlm(messages);
+  const conversationText = serializeConversation(llmMessages);
+  let fullPrompt = `<conversation>\n${conversationText}\n</conversation>\n\n`;
+  if (previousSummary) {
+    fullPrompt += `<previous-summary>\n${previousSummary}\n</previous-summary>\n\n`;
+  }
+  fullPrompt += promptText;
+
+  const summarizationMessages = [
+    {
+      role: "user" as const,
+      content: [{ type: "text" as const, text: fullPrompt }],
+      timestamp: Date.now(),
+    },
+  ];
+
+  const completionOptions = getSummarizationCompletionOptions(
+    model,
+    apiKey,
+    signal,
+    reserveTokens,
+    0.8,
+    thinkingLevel,
+  );
+  const response = await completeSimple(
+    model,
+    { systemPrompt: SUMMARIZATION_SYSTEM_PROMPT, messages: summarizationMessages },
+    completionOptions,
+  );
+
+  if (response.stopReason === "error") {
+    throw new Error(`Summarization failed: ${response.errorMessage || "Unknown error"}`);
+  }
+
+  return response.content
+    .filter((content): content is { type: "text"; text: string } => content.type === "text")
+    .map((content) => content.text)
+    .join("\n");
+}
+
+export async function generateTurnPrefixSummary(
+  messages: AgentMessage[],
+  model: Model<Api>,
+  apiKey: string,
+  reserveTokens: number,
+  signal: AbortSignal,
+  thinkingLevel: ISummaryThinkingLevel,
+): Promise<string> {
+  const llmMessages = convertToLlm(messages);
+  const conversationText = serializeConversation(llmMessages);
+  const promptText = `<conversation>\n${conversationText}\n</conversation>\n\n${TURN_PREFIX_SUMMARIZATION_PROMPT}`;
+
+  const completionOptions = getSummarizationCompletionOptions(
+    model,
+    apiKey,
+    signal,
+    reserveTokens,
+    0.5,
+    thinkingLevel,
+  );
+  const response = await completeSimple(
+    model,
+    {
+      systemPrompt: SUMMARIZATION_SYSTEM_PROMPT,
+      messages: [
+        {
+          role: "user" as const,
+          content: [{ type: "text" as const, text: promptText }],
+          timestamp: Date.now(),
+        },
+      ],
+    },
+    completionOptions,
+  );
+
+  if (response.stopReason === "error") {
+    throw new Error(`Turn prefix summarization failed: ${response.errorMessage || "Unknown error"}`);
+  }
+
+  return response.content
+    .filter((content): content is { type: "text"; text: string } => content.type === "text")
+    .map((content) => content.text)
+    .join("\n");
+}
+
+function toFilePathSet(value: unknown): Set<string> {
+  if (value instanceof Set) {
+    const result = new Set<string>();
+    for (const item of value) {
+      if (typeof item === "string") {result.add(item);}
+    }
+    return result;
+  }
+  if (Array.isArray(value)) {
+    const result = new Set<string>();
+    for (const item of value) {
+      if (typeof item === "string") {result.add(item);}
+    }
+    return result;
+  }
+  return new Set<string>();
+}
+
+export function computeFileLists(fileOps: unknown): ICompactionDetails {
+  const raw = (fileOps as { read?: unknown; edited?: unknown; written?: unknown }) ?? {};
+  const read = toFilePathSet(raw.read);
+  const edited = toFilePathSet(raw.edited);
+  const written = toFilePathSet(raw.written);
+
+  const modified = new Set([...edited, ...written]);
+  const readFiles = [...read].filter((path) => !modified.has(path)).sort();
+  const modifiedFiles = [...modified].sort();
+  return { readFiles, modifiedFiles };
+}
+
+export function formatFileOperations(details: ICompactionDetails): string {
+  const sections: string[] = [];
+  if (details.readFiles.length > 0) {
+    sections.push(`<read-files>\n${details.readFiles.join("\n")}\n</read-files>`);
+  }
+  if (details.modifiedFiles.length > 0) {
+    sections.push(`<modified-files>\n${details.modifiedFiles.join("\n")}\n</modified-files>`);
+  }
+  if (sections.length === 0) {return "";}
+  return `\n\n${sections.join("\n\n")}`;
+}
+
+export function getReserveTokens(event: SessionBeforeCompactEvent): number {
+  return event.preparation.settings.reserveTokens || 16_384;
+}
+
+function getSummarizationCompletionOptions(
+  model: Model<Api>,
+  apiKey: string,
+  signal: AbortSignal,
+  reserveTokens: number,
+  ratio: number,
+  thinkingLevel: ISummaryThinkingLevel,
+): { maxTokens: number; signal: AbortSignal; apiKey: string; reasoning?: "low" | "medium" | "high" } {
+  const maxTokens = Math.max(256, Math.floor(reserveTokens * ratio));
+  if (!model.reasoning || thinkingLevel === "off") {
+    return { maxTokens, signal, apiKey };
+  }
+  return { maxTokens, signal, apiKey, reasoning: thinkingLevel };
+}

package/resources/pi-agent/extensions/pi-custom-compaction/summary/template.ts

@@ -0,0 +1,124 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { homedir } from "node:os";
+import type {
+  ICompactionPolicy,
+  IModelEntry,
+  ISummaryPolicy,
+  ITemplateResolution,
+} from "../policy/types.js";
+import { resolveAgentRootPath } from "../paths.js";
+
+const TEMPLATE_DIR = "compaction-templates";
+const TEMPLATE_FILE = "compaction-template.md";
+const UPDATE_TEMPLATE_FILE = "compaction-template-update.md";
+
+type ITryReadResult = { content: string; path: string } | { error: string; path: string } | undefined;
+
+function tryRead(path: string): ITryReadResult {
+  if (!existsSync(path)) {return undefined;}
+  try {
+    const content = readFileSync(path, "utf8").trim();
+    if (!content) {return { error: "template file is empty", path };}
+    return { content, path };
+  } catch (error) {
+    return { error: error instanceof Error ? error.message : String(error), path };
+  }
+}
+
+function tryReadExplicit(rawPath: string): ITryReadResult {
+  const resolved = rawPath.startsWith("~/") ? join(homedir(), rawPath.slice(2)) : rawPath;
+  return tryRead(resolved) ?? { error: "file not found", path: resolved };
+}
+
+function findTemplate(
+  cwd: string,
+  profileName: string | undefined,
+  defaultFile: string,
+  profileSuffix: string,
+  globalBase: string,
+): ReturnType<typeof tryRead> {
+  if (profileName) {
+    const profileFile = `${profileName}${profileSuffix}.md`;
+    const projectProfile = tryRead(resolve(cwd, ".pi", TEMPLATE_DIR, profileFile));
+    if (projectProfile) {return projectProfile;}
+    const globalProfile = tryRead(join(globalBase, TEMPLATE_DIR, profileFile));
+    if (globalProfile) {return globalProfile;}
+  }
+  const projectDefault = tryRead(resolve(cwd, ".pi", defaultFile));
+  if (projectDefault) {return projectDefault;}
+  return tryRead(join(globalBase, defaultFile));
+}
+
+export function discoverTemplate(
+  cwd: string,
+  profileName: string | undefined,
+  explicitPaths?: { template?: string; updateTemplate?: string },
+): ITemplateResolution {
+  const globalBase = resolveAgentRootPath();
+  const initial = explicitPaths?.template
+    ? tryReadExplicit(explicitPaths.template)
+    : findTemplate(cwd, profileName, TEMPLATE_FILE, "", globalBase);
+  if (!initial) {return {};}
+  if ("error" in initial) {return { resolvedPath: initial.path, fallbackReason: initial.error };}
+
+  const result: ITemplateResolution = { template: initial.content, resolvedPath: initial.path };
+
+  const update = explicitPaths?.updateTemplate
+    ? tryReadExplicit(explicitPaths.updateTemplate)
+    : findTemplate(cwd, profileName, UPDATE_TEMPLATE_FILE, "-update", globalBase);
+  if (update) {
+    if ("content" in update) {
+      result.updateTemplate = update.content;
+      result.updateResolvedPath = update.path;
+    } else {
+      result.updateResolvedPath = update.path;
+      result.updateFallbackReason = update.error;
+    }
+  }
+
+  return result;
+}
+
+export function resolveSummarySettings(policy: ICompactionPolicy, entry: IModelEntry): ISummaryPolicy {
+  return {
+    thinkingLevel: entry.thinkingLevel ?? policy.summary.thinkingLevel,
+    preservationInstruction: entry.preservationInstruction ?? policy.summary.preservationInstruction,
+  };
+}
+
+export function buildSummaryPrompt(
+  template: string,
+  updateTemplate: string | undefined,
+  previousSummary: string | undefined,
+  customInstructions: string | undefined,
+  preservationInstruction: string,
+): string {
+  const promptParts: string[] = [];
+  if (previousSummary) {
+    promptParts.push(
+      "The messages above are NEW conversation messages to incorporate into the existing summary provided in <previous-summary> tags.",
+      "",
+      "Update the existing structured summary with new information. RULES:",
+      "- PRESERVE all existing information from the previous summary",
+      "- ADD new progress, decisions, and context from the new messages",
+      "- Move completed items to Done, update Next Steps based on progress",
+      "- If something is no longer relevant, you may remove it",
+    );
+  } else {
+    promptParts.push(
+      "The messages above are a conversation to summarize. Create a structured context checkpoint summary that another LLM will use to continue the work.",
+    );
+  }
+
+  const activeTemplate = previousSummary && updateTemplate ? updateTemplate : template;
+  promptParts.push("", "Use this EXACT format:", "", activeTemplate, "", "Keep each section concise.");
+  if (preservationInstruction) {
+    promptParts.push(preservationInstruction);
+  }
+  if (customInstructions) {
+    promptParts.push("", `Additional focus: ${customInstructions}`);
+  }
+
+  return promptParts.join("\n");
+}