@docyrus/docyrus 0.0.22 → 0.0.24

package/resources/pi-agent/extensions/notify.ts

@@ -9,80 +9,82 @@
  */
 
 import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
-import { Markdown, type MarkdownTheme } from "@mariozechner/pi-tui";
+
+export const DOCYRUS_NOTIFICATION_TITLE = "docyrus";
 
 /**
  * Send a desktop notification via OSC 777 escape sequence.
  */
 const notify = (title: string, body: string): void => {
 	// OSC 777 format: ESC ] 777 ; notify ; title ; body BEL
-	process.stdout.write(`\x1b]777;notify;${title};${body}\x07`);
+  process.stdout.write(`\x1b]777;notify;${title};${body}\x07`);
 };
 
 const isTextPart = (part: unknown): part is { type: "text"; text: string } =>
-	Boolean(part && typeof part === "object" && "type" in part && part.type === "text" && "text" in part);
-
-const extractLastAssistantText = (messages: Array<{ role?: string; content?: unknown }>): string | null => {
-	for (let i = messages.length - 1; i >= 0; i--) {
-		const message = messages[i];
-		if (message?.role !== "assistant") {
-			continue;
-		}
+  Boolean(part && typeof part === "object" && "type" in part && part.type === "text" && "text" in part);
 
-		const content = message.content;
-		if (typeof content === "string") {
-			return content.trim() || null;
-		}
+export const extractLastAssistantText = (messages: Array<{ role?: string; content?: unknown }>): string | null => {
+  for (let i = messages.length - 1; i >= 0; i--) {
+    const message = messages[i];
+    if (message?.role !== "assistant") {
+      continue;
+    }
 
-		if (Array.isArray(content)) {
-			const text = content.filter(isTextPart).map((part) => part.text).join("\n").trim();
-			return text || null;
-		}
+    const content = message.content;
+    if (typeof content === "string") {
+      return content.trim() || null;
+    }
 
-		return null;
-	}
+    if (Array.isArray(content)) {
+      const text = content.filter(isTextPart).map((part) => part.text).join("\n").trim();
+      return text || null;
+    }
 
-	return null;
-};
+    return null;
+  }
 
-const plainMarkdownTheme: MarkdownTheme = {
-	heading: (text) => text,
-	link: (text) => text,
-	linkUrl: () => "",
-	code: (text) => text,
-	codeBlock: (text) => text,
-	codeBlockBorder: () => "",
-	quote: (text) => text,
-	quoteBorder: () => "",
-	hr: () => "",
-	listBullet: () => "",
-	bold: (text) => text,
-	italic: (text) => text,
-	strikethrough: (text) => text,
-	underline: (text) => text,
+  return null;
 };
 
-const simpleMarkdown = (text: string, width = 80): string => {
-	const markdown = new Markdown(text, 0, 0, plainMarkdownTheme);
-	return markdown.render(width).join("\n");
+export const simpleMarkdown = (text: string, _width = 80): string => {
+  return text
+    .replace(/```[\s\S]*?```/g, (block) => block.replace(/^```[^\n]*\n?/, "").replace(/\n?```$/, ""))
+    .replace(/`([^`]+)`/g, "$1")
+    .replace(/!\[([^\]]*)\]\([^)]+\)/g, "$1")
+    .replace(/\[([^\]]+)\]\([^)]+\)/g, "$1")
+    .replace(/^#{1,6}\s*/gm, "")
+    .replace(/^>\s?/gm, "")
+    .replace(/^[-*+]\s+/gm, "")
+    .replace(/^\d+\.\s+/gm, "")
+    .replace(/^---+$/gm, "")
+    .replace(/^___+$/gm, "")
+    .replace(/^\*{3,}$/gm, "")
+    .replace(/(\*\*|__)(.*?)\1/g, "$2")
+    .replace(/(\*|_)(.*?)\1/g, "$2")
+    .replace(/~~(.*?)~~/g, "$1")
+    .split("\n")
+    .map((line) => line.trimEnd())
+    .join("\n");
 };
 
-const formatNotification = (text: string | null): { title: string; body: string } => {
-	const simplified = text ? simpleMarkdown(text) : "";
-	const normalized = simplified.replace(/\s+/g, " ").trim();
-	if (!normalized) {
-		return { title: "Ready for input", body: "" };
-	}
+// The Docyrus logo SVG is packaged for future notification backends that support
+// icons, but the current OSC 777 transport only supports title/body text.
+export const formatNotification = (text: string | null): { title: string; body: string } => {
+  const simplified = text ? simpleMarkdown(text) : "";
+  const normalized = simplified.replace(/\s+/g, " ").trim();
+  if (!normalized) {
+    return { title: DOCYRUS_NOTIFICATION_TITLE, body: "Ready for input" };
+  }
 
-	const maxBody = 200;
-	const body = normalized.length > maxBody ? `${normalized.slice(0, maxBody - 1)}…` : normalized;
-	return { title: "π", body };
+  const maxBody = 200;
+  const body = normalized.length > maxBody ? `${normalized.slice(0, maxBody - 1)}…` : normalized;
+  return { title: DOCYRUS_NOTIFICATION_TITLE, body };
 };
 
-export default function (pi: ExtensionAPI) {
-	pi.on("agent_end", async (event) => {
-		const lastText = extractLastAssistantText(event.messages ?? []);
-		const { title, body } = formatNotification(lastText);
-		notify(title, body);
-	});
+export default function(pi: ExtensionAPI) {
+  pi.on("agent_end", async(event) => {
+    const lastText = extractLastAssistantText(event.messages ?? []);
+    const { title, body } = formatNotification(lastText);
+    notify(title, body);
+  });
 }

package/resources/pi-agent/extensions/pi-custom-compaction/CHANGELOG.md

@@ -0,0 +1,27 @@
+# Changelog
+
+## 0.2.0 — 2026-03-22
+
+- **Profile model overrides** — profiles can now override the `models` list per session model. Use a different summarization model when chatting with Opus vs Codex.
+- **Profile template paths** — profiles can specify explicit `template` and `updateTemplate` paths, overriding convention-based discovery. Tilde-expanded.
+- **Compaction spinner widget** — animated `Loader` spinner displays during extension-initiated compaction, matching pi's built-in appearance.
+- **Post-compaction status fix** — status bar no longer shows `?` for 1-2 messages after compaction. Shows just the label until token counts are available again.
+- **Watchdog widget cleanup** — if compaction hangs and the 2-minute watchdog fires, the spinner widget is now properly removed.
+- **Test suite** — 62 tests across 6 files covering parse, merge, config, pure logic, model resolution, and template discovery. Run with `tsx --test test/*.test.ts`.
+
+## 0.1.0 — 2026-03-21
+
+Initial release.
+
+Custom compaction for Pi — swap the model used for compaction summaries, define your own summary template structure, and optionally trigger compaction at a specific token count. Everything is driven by a JSON config file with no UI overlay.
+
+Core features:
+
+- **Custom compaction model** with ordered fallback chain (`models`). If one provider's credits run out, the next model takes over. Per-model `thinkingLevel` and `preservationInstruction` overrides.
+- **Token-based trigger** (`trigger.maxTokens`). Omit to let Pi's built-in decide when to compact. Set a value to proactively compact at that token count.
+- **Custom summary templates** via convention-based markdown files. Separate initial and update templates so the model knows what to extract vs how to merge. Profile-specific templates supported. Entirely optional — Pi's built-in format works without one.
+- **Profiles** — named overrides for trigger and summary settings that activate based on the session model. Match on exact `provider/modelId`.
+- **Global and project config** — `~/.pi/agent/compaction-policy.json` (global) and `<project>/.pi/compaction-policy.json` (project, takes priority).
+- **Status bar** with configurable label (`ui.name`), showing token usage relative to the effective trigger point.
+- **Commands**: `/compact-policy` (show effective config) and `/compact-now [focus]` (trigger immediately).
+- **Builtin skip margin** prevents double-triggering when the extension's trigger is close to Pi's own compaction threshold.

package/resources/pi-agent/extensions/pi-custom-compaction/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nico Bailon
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/resources/pi-agent/extensions/pi-custom-compaction/README.md

@@ -0,0 +1,244 @@
+<p>
+  <img src="banner.png" alt="pi-custom-compaction" width="1100">
+</p>
+
+# pi-custom-compaction
+
+Swap the model and template Pi uses for compaction. Optionally trigger compaction at a specific token count.
+
+Once enabled, the extension intercepts every compaction — whether triggered by Pi's built-in or by the extension itself — and uses your configured model and template to generate the summary. If all configured models fail to resolve, it falls back to Pi's built-in compaction silently.
+
+Off by default. Pi's built-in compaction works normally until you enable it.
+
+## Installation
+
+```bash
+pi install npm:pi-custom-compaction
+```
+
+## Quick start
+
+Create `~/.pi/agent/compaction-policy.json` (global) or `<project>/.pi/compaction-policy.json` (project, takes priority):
+
+```json
+{
+  "enabled": true,
+  "models": [
+    { "model": "anthropic/claude-sonnet-4", "thinkingLevel": "medium" }
+  ]
+}
+```
+
+Run `/reload`. Done. Pi still decides when to compact — you just swapped the model.
+
+To also control **when** it triggers:
+
+```json
+{
+  "enabled": true,
+  "trigger": { "maxTokens": 350000 },
+  "ui": { "name": "ctx" },
+  "models": [
+    { "model": "anthropic/claude-haiku-4-5", "thinkingLevel": "medium" },
+    { "model": "openai-codex/gpt-5.3-codex", "thinkingLevel": "low" }
+  ]
+}
+```
+
+Status bar shows: `ctx · 24.7% (86426/350000)`
+
+## Commands
+
+| Command | What it does |
+| --- | --- |
+| `/compact-policy` | Shows effective config (models, trigger, profile, template) |
+| `/compact-now [focus]` | Triggers compaction immediately |
+
+## Models
+
+Ordered fallback chain. Tries each model in order, uses the first one that resolves. If credits run out on one, the next takes over.
+
+Plain strings inherit base `summary` settings. Objects let you override per model:
+
+```json
+"models": [
+  { "model": "anthropic/claude-sonnet-4", "thinkingLevel": "medium" },
+  "openai-codex/gpt-5.3-codex"
+]
+```
+
+## Trigger
+
+| Key | What it does | Default |
+| --- | --- | --- |
+| `maxTokens` | Compact at this token count. Omit to let Pi decide. | — |
+| `minTokens` | Won't trigger below this count | 100000 |
+| `cooldownMs` | Min time between proactive compactions | 60000 |
+
+`maxTokens` makes compaction happen sooner. Without it, Pi waits until the context window is almost full (~984K on a 1M model). With `maxTokens: 350000`, compaction fires at 350K instead.
+
+## How maxTokens interacts with the context window
+
+You don't need to tune `maxTokens` per model. One config works across models with different context sizes:
+
+- **Well below context window** (350K on a 1M model) — extension fires at 350K, plenty of room for the summary.
+- **Close to context window** (260K on a 272K model) — extension backs off and lets Pi's built-in fire at 256K with its own reserve, preventing double-compaction.
+- **Larger than context window** (350K on a 272K model) — proactive trigger can never fire, Pi handles it at 256K.
+
+<details>
+<summary>Advanced trigger tuning</summary>
+
+| Key | What it does | Default |
+| --- | --- | --- |
+| `builtinReserveTokens` | Tokens Pi's built-in reserves before triggering | 16384 |
+| `builtinSkipMarginPercent` | Skip if Pi's builtin would trigger within this margin | 5 |
+
+</details>
+
+## Profiles
+
+Override trigger, models, and summary settings per session model:
+
+```json
+"profiles": {
+  "opus-large-ctx": {
+    "match": "anthropic/claude-opus-4-6",
+    "trigger": { "maxTokens": 500000 },
+    "models": [{ "model": "anthropic/claude-haiku-4-5", "thinkingLevel": "medium" }],
+    "template": "~/.pi/agent/templates/opus.md",
+    "updateTemplate": "~/.pi/agent/templates/opus-update.md"
+  },
+  "fast-codex": {
+    "match": "openai-codex/gpt-5.3-codex",
+    "models": ["openai-codex/gpt-5.3-codex"],
+    "summary": { "thinkingLevel": "low" }
+  }
+}
+```
+
+`match` is the exact `provider/modelId` of the session model. First alphabetical match wins. Profile `models` replaces the base models list for that session. `template` and `updateTemplate` override template discovery with explicit paths (tilde-expanded). Active profile shows in the status bar.
+
+## Templates (optional)
+
+Without a template, Pi's built-in compaction format is used. To customize the summary structure, drop markdown files at convention paths — no config needed.
+
+Two template types:
+- **Initial** (`compaction-template.md`) — first compaction, brackets describe what to extract
+- **Update** (`compaction-template-update.md`) — subsequent compactions, brackets describe how to merge (optional, falls back to initial)
+
+Discovery order (first found wins):
+
+```
+Initial template:
+  <project>/.pi/compaction-templates/PROFILE.md
+  ~/.pi/agent/compaction-templates/PROFILE.md
+  <project>/.pi/compaction-template.md
+  ~/.pi/agent/compaction-template.md
+
+Update template:
+  <project>/.pi/compaction-templates/PROFILE-update.md
+  ~/.pi/agent/compaction-templates/PROFILE-update.md
+  <project>/.pi/compaction-template-update.md
+  ~/.pi/agent/compaction-template-update.md
+```
+
+Profile-specific paths are only checked when a profile is active. Template files are never modified — they're format definitions read on every compaction. The model fills in the brackets based on the conversation.
+
+Example initial template (`compaction-template.md`):
+
+```markdown
+## Goal
+[What is the user trying to accomplish? Can be multiple items if the session covers different tasks.]
+
+## Constraints & Preferences
+- [Any constraints, preferences, or requirements mentioned by user]
+- [Or "(none)" if none were mentioned]
+
+## Progress
+### Done
+- [x] [Completed tasks/changes]
+
+### In Progress
+- [ ] [Current work]
+
+### Blocked
+- [Issues preventing progress, if any]
+
+## Key Decisions
+- **[Decision]**: [Brief rationale]
+
+## Next Steps
+1. [Ordered list of what should happen next]
+
+## Critical Context
+- [Any data, examples, or references needed to continue]
+- [Or "(none)" if not applicable]
+```
+
+Example update template (`compaction-template-update.md`):
+
+```markdown
+## Goal
+[Preserve existing goals, add new ones if the task expanded]
+
+## Constraints & Preferences
+- [Preserve existing, add new ones discovered]
+
+## Progress
+### Done
+- [x] [Include previously done items AND newly completed items]
+
+### In Progress
+- [ ] [Current work - update based on progress]
+
+### Blocked
+- [Current blockers - remove if resolved]
+
+## Key Decisions
+- **[Decision]**: [Brief rationale] (preserve all previous, add new)
+
+## Next Steps
+1. [Update based on current state]
+
+## Critical Context
+- [Preserve important context, add new if needed]
+```
+
+`summary.preservationInstruction` is appended as an extra directive after the template.
+
+## UI options
+
+```json
+"ui": {
+  "name": "ctx",
+  "showStatus": true,
+  "minimalStatus": false,
+  "quiet": false
+}
+```
+
+| Key | What it does | Default |
+| --- | --- | --- |
+| `name` | Status bar label | `"compact"` |
+| `showStatus` | Show status bar | `true` |
+| `minimalStatus` | Short format (just percentage) | `false` |
+| `quiet` | Suppress non-critical notifications | `false` |
+
+Status bar examples:
+
+```
+ctx · 24.7% (86426/350000)
+ctx: opus-large-ctx · 50.1% (250500/500000)
+ctx · 31%
+```
+
+## Summary options
+
+```json
+"summary": {
+  "thinkingLevel": "medium",
+  "preservationInstruction": "Preserve exact file paths, function names, and error messages."
+}
+```
+
+These are base settings. Model entries and profiles can override `thinkingLevel` and `preservationInstruction` individually.

package/resources/pi-agent/extensions/pi-custom-compaction/VENDORED_FROM.md

@@ -0,0 +1,6 @@
+Vendored from [`nicobailon/pi-custom-compaction`](https://github.com/nicobailon/pi-custom-compaction)
+
+- Upstream commit: `ac69e833c4dc00b4961c65daa2807017bed86e8b`
+- Vendored for: `docyrus agent` / `docyrus coder`
+- Local adaptation:
+  - prefer `PI_CODING_AGENT_DIR` for global policy/template lookup so scoped Docyrus agent state works

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

@@ -0,0 +1,63 @@
+import type { ExtensionAPI, ExtensionCommandContext } from "@mariozechner/pi-coding-agent";
+import { resolveEffectivePolicy } from "../runtime/pure.js";
+import type { IRuntimeServices } from "../runtime/session-state.js";
+import { discoverTemplate } from "../summary/template.js";
+
+function formatModels(policy: { models: Array<{ model: string; thinkingLevel?: string }> }): string {
+  return policy.models
+    .map((e) => (e.thinkingLevel ? `${e.model} (thinking: ${e.thinkingLevel})` : e.model))
+    .join(" → ");
+}
+
+function formatTrigger(policy: {
+	trigger: { maxTokens?: number; minTokens: number; cooldownMs: number };
+}): string {
+  const { maxTokens, minTokens, cooldownMs } = policy.trigger;
+  const threshold = maxTokens && maxTokens > 0 ? `${maxTokens} tokens` : "inherited from pi";
+  return `${threshold} | minTokens: ${minTokens} | cooldown: ${cooldownMs}ms`;
+}
+
+export function registerCommands(pi: ExtensionAPI, runtime: IRuntimeServices): void {
+  pi.registerCommand("compact-policy", {
+    description: "Show current compaction policy",
+    handler: async(_args, ctx: ExtensionCommandContext) => {
+      const basePolicy = runtime.loadEffectivePolicy(ctx);
+      const { policy, profileName, sessionModel, profileTemplates } = resolveEffectivePolicy(ctx, basePolicy);
+      const template = discoverTemplate(ctx.cwd, profileName, profileTemplates);
+      const templatePath = template.fallbackReason
+        ? `${template.resolvedPath ?? "(unknown)"} (invalid: ${template.fallbackReason}; using built-in)`
+        : template.resolvedPath ?? "(none — using built-in)";
+      const updateTemplatePath = template.updateFallbackReason
+        ? `${template.updateResolvedPath ?? "(unknown)"} (invalid: ${template.updateFallbackReason}; using initial template)`
+        : template.updateResolvedPath ?? "(none — using initial template)";
+
+      const lines = [
+        `enabled: ${policy.enabled}`,
+        `models: ${formatModels(policy)}`,
+        `trigger: ${formatTrigger(policy)}`,
+        `summary: thinking=${policy.summary.thinkingLevel}`,
+        `session model: ${sessionModel ?? "unknown"}`,
+        `profile: ${profileName ?? "none"}`,
+        `template: ${templatePath}`,
+        `template update: ${updateTemplatePath}`,
+      ];
+      ctx.ui.notify(lines.join("\n"), "info");
+    },
+  });
+
+  pi.registerCommand("compact-now", {
+    description: "Trigger compaction immediately",
+    handler: async(args, ctx: ExtensionCommandContext) => {
+      const basePolicy = runtime.loadEffectivePolicy(ctx);
+      const { policy, profileName } = resolveEffectivePolicy(ctx, basePolicy);
+      runtime.setActiveProfileName(profileName);
+
+      const focus = args.trim() || undefined;
+      if (!policy.enabled) {
+        ctx.compact({ customInstructions: focus });
+        return;
+      }
+      runtime.triggerCompaction(ctx, policy, "compact-now", focus);
+    },
+  });
+}