@pi-unipi/unipi 3.0.0-alpha.2 → 3.0.0-alpha.21

package/packages/compactor/src/tools/register.ts

@@ -1,53 +1,17 @@
 /**
- * Tool registration — register all compactor tools with Pi's ExtensionAPI
- *
- * Each tool is registered via pi.registerTool() with proper TypeBox schemas
- * so the LLM can discover and invoke them.
- *
- * Tool names:
- *   compact, session_recall, sandbox, sandbox_file, sandbox_batch,
- *   compactor_stats, compactor_doctor, context_budget
- *
- * Deprecated aliases for backward compatibility:
- *   vcc_recall, ctx_execute, ctx_execute_file, ctx_batch_execute,
- *   ctx_stats, ctx_doctor
+ * Tool registration — the compactor's agent-facing tools:
+ *   session_recall  search the full session history, including compacted-away parts
+ *   context_budget  how full the context is and what happens next
  */
 
 import { Type } from "typebox";
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { vccRecall } from "./vcc-recall.js";
-import { ctxExecute, type CtxExecuteInput } from "./ctx-execute.js";
-import { ctxExecuteFile, type CtxExecuteFileInput } from "./ctx-execute-file.js";
-import { ctxBatchExecute, type BatchItem } from "./ctx-batch-execute.js";
-import { ctxStats, type CtxStatsResult } from "./ctx-stats.js";
-import { ctxDoctor, type DoctorResult } from "./ctx-doctor.js";
 import { contextBudgetTool } from "./context-budget.js";
 import { recallBlocksFromContext } from "../session/recall-blocks.js";
 import { filterNoise } from "../compaction/filter-noise.js";
 import { loadConfig } from "../config/manager.js";
-import type { SessionDB } from "../session/db.js";
-import type { Language, NormalizedBlock, RuntimeCounters } from "../types.js";
-import type { PolyglotExecutor } from "../executor/executor.js";
-
-// --- TypeBox Schemas for each tool ---
-
-const LanguageSchema = Type.Union([
-  Type.Literal("javascript"),
-  Type.Literal("typescript"),
-  Type.Literal("python"),
-  Type.Literal("shell"),
-  Type.Literal("ruby"),
-  Type.Literal("go"),
-  Type.Literal("rust"),
-  Type.Literal("php"),
-  Type.Literal("perl"),
-  Type.Literal("r"),
-  Type.Literal("elixir"),
-]);
-
-const CompactParams = Type.Object({
-  dryRun: Type.Optional(Type.Boolean({ description: "If true, report what would be compacted without actually compacting" })),
-});
+import type { RuntimeCounters } from "../types.js";
 
 const RecallParams = Type.Object({
   query: Type.Optional(Type.String({ description: "What to recall, in plain keywords (e.g. 'redis cache decision'). Multi-word queries are ranked by relevance. A regex pattern also works. #N:path drills into a file's content from an entry." })),
@@ -61,111 +25,17 @@ const RecallParams = Type.Object({
   })),
 });
 
-const SandboxParams = Type.Object({
-  language: LanguageSchema,
-  code: Type.String({ description: "Code to execute in the sandbox" }),
-  timeout: Type.Optional(Type.Number({ description: "Timeout in ms (default 30000)", minimum: 1000 })),
-});
-
-const SandboxFileParams = Type.Object({
-  language: LanguageSchema,
-  path: Type.String({ description: "Path to file to execute" }),
-  timeout: Type.Optional(Type.Number({ description: "Timeout in ms (default 30000)", minimum: 1000 })),
-});
-
-const SandboxBatchParams = Type.Object({
-  items: Type.Array(
-    Type.Union([
-      Type.Object({
-        type: Type.Literal("execute"),
-        language: LanguageSchema,
-        code: Type.String(),
-        timeout: Type.Optional(Type.Number()),
-      }),
-    ]),
-    { description: "Array of execute commands to run atomically" },
-  ),
-});
-
-const StatsParams = Type.Object({});
-
-const DoctorParams = Type.Object({});
-
-// --- Helpers ---
-
-function textResult(text: string, details?: Record<string, unknown>): any {
-  return {
-    content: [{ type: "text", text }],
-    details,
-  };
-}
-
-function jsonResult(data: unknown, label?: string): any {
-  const text = label ? `${label}:\n${JSON.stringify(data, null, 2)}` : JSON.stringify(data, null, 2);
-  return {
-    content: [{ type: "text", text }],
-    details: data as Record<string, unknown>,
-  };
-}
-
-// --- Registration ---
-
 export interface CompactorToolDeps {
-  sessionDB: SessionDB;
-  getSessionId: () => string;
-  getBlocks: () => NormalizedBlock[];
-  getCounters?: () => RuntimeCounters;
-  sandbox?: {
-    executor: PolyglotExecutor;
-    allowedLanguages: Language[];
-  };
+  counters: RuntimeCounters;
 }
 
-/**
- * Register all compactor tools with Pi's ExtensionAPI.
- * Call this during session_start after services are initialized.
- */
-export function registerCompactorTools(pi: ExtensionAPI, deps: CompactorToolDeps): void {
-  // 1. compact — trigger manual compaction (with optional dryRun)
-  pi.registerTool(({
-    name: "compact",
-    label: "Compact",
-    description: "Trigger manual context compaction. Reduces session history while preserving continuity. Use dryRun:true to preview without compacting.",
-    parameters: CompactParams,
-    async execute(_toolCallId: string, params: any): Promise<import("@earendil-works/pi-coding-agent").AgentToolResult<unknown>> {
-      if (params.dryRun) {
-        const blocks = deps.getBlocks();
-        const totalMessages = blocks.length;
-        const estimated = Math.round(totalMessages * 0.15);
-        return jsonResult({
-          dryRun: true,
-          wouldCompact: totalMessages,
-          estimatedKept: estimated,
-          message: `Would compact ${totalMessages} messages → ~${estimated} kept.`,
-        }, "Dry run — no compaction performed");
-      }
-      const c = deps.getCounters?.();
-      if (c) { c.compactions++; }
-      return jsonResult({ success: true, message: "Compaction triggered. Stats will be available after next compact event." }, "Compaction triggered");
-    },
-  } as any));
+const textResult = (text: string, details?: Record<string, unknown>): any => ({
+  content: [{ type: "text", text }],
+  details,
+});
 
-  // 2. session_recall (new) / vcc_recall (deprecated) — search session history
-  const recallExec = async (_toolCallId: string, params: any, _signal?: AbortSignal, _onUpdate?: unknown, ctx?: ExtensionContext): Promise<import("@earendil-works/pi-coding-agent").AgentToolResult<unknown>> => {
-    const c = deps.getCounters?.();
-    if (c) { c.recallQueries++; }
-    const config = loadConfig(ctx?.cwd ?? process.cwd());
-    const liveBlocks = ctx ? filterNoise(recallBlocksFromContext(ctx), config.pipeline?.customNoisePatterns) : [];
-    const blocks = liveBlocks.length > 0 ? liveBlocks : deps.getBlocks();
-    const result = vccRecall(blocks, {
-      query: params.query,
-      scope: params.scope,
-      mode: params.mode,
-      page: params.page,
-      expand: params.expand,
-    });
-    return textResult(result.text, { query: params.query ?? null });
-  };
+/** Register the compactor's tools (once, at extension load). */
+export function registerCompactorTools(pi: ExtensionAPI, deps: CompactorToolDeps): void {
   pi.registerTool({
     name: "session_recall",
     label: "Session Recall",
@@ -177,139 +47,29 @@ export function registerCompactorTools(pi: ExtensionAPI, deps: CompactorToolDeps
       "and #N:path to drill into a file's content from an entry (#N:path:full for all lines). Only the current session is " +
       "searchable — earlier sessions are not.",
     parameters: RecallParams,
-    execute: recallExec,
-  } as any);
-
-  // Sandbox tools are session-scoped and only registered when enabled.
-  if (deps.sandbox) {
-  const { executor, allowedLanguages } = deps.sandbox;
-  const assertAllowedLanguage = (language: Language): void => {
-    if (!allowedLanguages.includes(language)) {
-      throw new Error(`Language "${language}" is disabled by Compactor sandbox settings. Allowed: ${allowedLanguages.join(", ") || "none"}`);
-    }
-  };
-
-  // 3. sandbox (new) / ctx_execute (deprecated) — run code in sandbox
-  const sandboxExec = async (_toolCallId: string, params: any): Promise<import("@earendil-works/pi-coding-agent").AgentToolResult<unknown>> => {
-    try {
-      const c = deps.getCounters?.();
-      if (c) { c.sandboxRuns++; }
-      deps.sessionDB.incrementSandboxRuns(deps.getSessionId());
-      assertAllowedLanguage(params.language as Language);
-      const result = await ctxExecute(params as CtxExecuteInput, executor);
-      const parts: string[] = [];
-      if (result.stdout) parts.push(result.stdout);
-      if (result.stderr) parts.push(`[stderr] ${result.stderr}`);
-      if (result.timedOut) parts.push("[timed out]");
-      if (result.exitCode !== 0) parts.push(`[exit code: ${result.exitCode}]`);
-      return textResult(parts.join("\n") || "(no output)", result as unknown as Record<string, unknown>);
-    } catch (err) {
-      return textResult(`Execution error: ${err}`, { error: true });
-    }
-  };
-  pi.registerTool({ name: "sandbox", label: "Sandbox", description: "Run code in a sandboxed environment. Supports 11 languages. Only stdout enters context.", parameters: SandboxParams, execute: sandboxExec } as any);
-
-  // 4. sandbox_file (new) / ctx_execute_file (deprecated) — execute file
-  const sandboxFileExec = async (_toolCallId: string, params: any): Promise<import("@earendil-works/pi-coding-agent").AgentToolResult<unknown>> => {
-    try {
-      const c = deps.getCounters?.();
-      if (c) { c.sandboxRuns++; }
-      deps.sessionDB.incrementSandboxRuns(deps.getSessionId());
-      assertAllowedLanguage(params.language as Language);
-      const result = await ctxExecuteFile(params as CtxExecuteFileInput, executor);
-      const parts: string[] = [];
-      if (result.stdout) parts.push(result.stdout);
-      if (result.stderr) parts.push(`[stderr] ${result.stderr}`);
-      if (result.timedOut) parts.push("[timed out]");
-      return textResult(parts.join("\n") || "(no output)", result as unknown as Record<string, unknown>);
-    } catch (err) {
-      return textResult(`Execution error: ${err}`, { error: true });
-    }
-  };
-  pi.registerTool({ name: "sandbox_file", label: "Sandbox File", description: "Execute a file in the sandbox. File content is injected as FILE_CONTENT variable.", parameters: SandboxFileParams, execute: sandboxFileExec } as any);
-
-  // 5. sandbox_batch (new) / ctx_batch_execute (deprecated) — atomic batch (execute only)
-  const sandboxBatchExec = async (_toolCallId: string, params: any): Promise<import("@earendil-works/pi-coding-agent").AgentToolResult<unknown>> => {
-    try {
-      const c = deps.getCounters?.();
-      if (c) { c.sandboxRuns++; }
-      deps.sessionDB.incrementSandboxRuns(deps.getSessionId());
-      for (const item of params.items as BatchItem[]) assertAllowedLanguage(item.language);
-      const result = await ctxBatchExecute(params.items as BatchItem[], executor);
-      const summaries = result.results.map((r, i) => {
-        const s = r.result.stdout?.slice(0, 200) || "(no output)";
-        return `[${i}] execute → ${r.result.exitCode === 0 ? "ok" : "fail"}: ${s}`;
+    async execute(_toolCallId: string, params: any, _signal?: AbortSignal, _onUpdate?: unknown, ctx?: ExtensionContext) {
+      deps.counters.recallQueries++;
+      const blocks = ctx ? filterNoise(recallBlocksFromContext(ctx)) : [];
+      const result = vccRecall(blocks, {
+        query: params.query,
+        scope: params.scope,
+        mode: params.mode,
+        page: params.page,
+        expand: params.expand,
       });
-      return textResult(`Batch results (${result.results.length} items):\n${summaries.join("\n")}`, result as unknown as Record<string, unknown>);
-    } catch (err) {
-      return textResult(`Batch error: ${err}`, { error: true });
-    }
-  };
-  pi.registerTool({ name: "sandbox_batch", label: "Sandbox Batch", description: "Run multiple code executions atomically as a batch.", parameters: SandboxBatchParams, execute: sandboxBatchExec } as any);
-  }
-
-  // 6. compactor_stats (new) / ctx_stats (deprecated) — context savings dashboard
-  const statsExec = async (): Promise<import("@earendil-works/pi-coding-agent").AgentToolResult<unknown>> => {
-    try {
-      const result = await ctxStats(deps.sessionDB, deps.getSessionId(), deps.getCounters?.());
-      const lines = [
-        `📊 Compactor Stats`,
-        `Session events: ${result.sessionEvents}`,
-        `Compactions: ${result.compactions}`,
-        `Tokens saved: ${result.tokensSaved}`,
-        `Sandbox runs: ${result.sandboxRuns}`,
-        `Search queries: ${result.searchQueries}`,
-      ];
-      return textResult(lines.join("\n"), result as unknown as Record<string, unknown>);
-    } catch (err) {
-      return textResult(`Stats error: ${err}`, { error: true });
-    }
-  };
-  pi.registerTool({ name: "compactor_stats", label: "Compactor Stats", description: "Show context savings dashboard — session events, compactions, tool usage.", parameters: StatsParams, execute: statsExec } as any);
-
-  // 7. compactor_doctor (new) / ctx_doctor (deprecated) — diagnostics checklist
-  const doctorExec = async (): Promise<import("@earendil-works/pi-coding-agent").AgentToolResult<unknown>> => {
-    try {
-      const result = await ctxDoctor(deps.sessionDB);
-      const icon = (s: string) => (s === "pass" ? "✅" : s === "warn" ? "⚠️" : "❌");
-      const lines = [
-        result.healthy ? "🩺 All checks passed" : "🩺 Issues found",
-        "",
-        ...result.checks.map((c) => `${icon(c.status)} ${c.name}: ${c.message}`),
-      ];
-      return jsonResult(result, lines.join("\n"));
-    } catch (err) {
-      return textResult(`Doctor error: ${err}`, { error: true });
-    }
-  };
-  pi.registerTool({ name: "compactor_doctor", label: "Compactor Doctor", description: "Run diagnostics checklist — validate config, DB, runtimes.", parameters: DoctorParams, execute: doctorExec } as any);
+      return textResult(result.text, { query: params.query ?? null });
+    },
+  } as any);
 
-  // 8. context_budget — estimate remaining context window
-  pi.registerTool(({
+  pi.registerTool({
     name: "context_budget",
     label: "Context Budget",
-    description: "Estimate remaining context window (% full, tokens left) and get advice on whether to compact.",
+    description: "Estimate how full the context window is (% full, tokens left). Compaction is automatic; this never needs to be acted on.",
     parameters: Type.Object({}),
-    async execute(_toolCallId: string, _params: any, _signal?: AbortSignal, _onUpdate?: unknown, ctx?: ExtensionContext): Promise<import("@earendil-works/pi-coding-agent").AgentToolResult<unknown>> {
+    async execute(_toolCallId: string, _params: any, _signal?: AbortSignal, _onUpdate?: unknown, ctx?: ExtensionContext) {
       const config = loadConfig(ctx?.cwd ?? process.cwd());
-      const liveUsage = ctx?.getContextUsage?.();
-      let estimatedTokens: number | undefined = liveUsage?.tokens ?? undefined;
-      let contextWindow = liveUsage?.contextWindow;
-
-      if (estimatedTokens === undefined) {
-        const blocks = deps.getBlocks();
-        estimatedTokens = blocks.reduce((sum, b) => {
-          const text = b.kind === "tool_call"
-            ? `${b.name} ${JSON.stringify((b as any).args ?? {})}`
-            : b.kind === "tool_result"
-              ? `${b.name} ${(b as any).text ?? ""}`
-              : (b as any).text ?? "";
-          return sum + Math.ceil(text.length / 4);
-        }, 0);
-      }
-
-      const message = contextBudgetTool(estimatedTokens, contextWindow, config.autoCompaction);
-      return textResult(message);
+      const usage = ctx?.getContextUsage?.();
+      return textResult(contextBudgetTool(usage?.tokens ?? undefined, usage?.contextWindow, config));
     },
-  } as any));
+  } as any);
 }

package/packages/compactor/src/types.ts

@@ -2,8 +2,6 @@
  * @pi-unipi/compactor — Shared TypeScript types
  */
 
-import type { Message } from "@earendil-works/pi-ai";
-
 // ─────────────────────────────────────────────────────────
 // Normalized blocks (from pi-vcc)
 // ─────────────────────────────────────────────────────────
@@ -23,39 +21,16 @@ export interface FileOps {
 }
 
 // ─────────────────────────────────────────────────────────
-// Section data (from pi-vcc)
-// ─────────────────────────────────────────────────────────
-
-export interface SectionData {
-  sessionGoal: string[];
-  filesAndChanges: string[];
-  commits: string[];
-  outstandingContext: string[];
-  userPreferences: string[];
-  briefTranscript: string;
-}
-
-export interface BriefLine {
-  header: string;
-  lines: string[];
-}
-
-// ─────────────────────────────────────────────────────────
-// Compaction input / output
+// Compaction stats
 // ─────────────────────────────────────────────────────────
 
-export interface CompileInput {
-  messages: Message[];
-  previousSummary?: string;
-}
-
 export interface CompactionStats {
   summarized: number;
   kept: number;
   totalMessages?: number;
   /** Actual token count from Pi's preparation */
   tokensBefore?: number;
-  /** Estimated tokens after compaction (proportional from kept/total chars) */
+  /** Estimated tokens after compaction: summary + kept tail. */
   tokensAfterEst?: number;
   keptUserTurns: number;
   totalUserTurns: number;
@@ -73,37 +48,58 @@ export interface CompactionStats {
 
 export type BudgetCutKind = "no_anchor" | "oversized_tail";
 
-export type OwnCutCancelReason =
-  | "no_live_messages"
-  | "too_few_live_messages";
-
-export type OwnCutResult =
-  | {
-      ok: true;
-      messages: Message[];
-      firstKeptEntryId: string;
-      compactAll: boolean;
-      keptUserTurns: number;
-      totalUserTurns: number;
-      requestedKeepUserTurns: number;
-      keepFallbackToCompactAll: boolean;
-      budgetCut?: BudgetCutKind;
-    }
-  | { ok: false; reason: OwnCutCancelReason };
-
 // ─────────────────────────────────────────────────────────
 // Configuration
 // ─────────────────────────────────────────────────────────
 
-export interface CompactorStrategyConfig {
-  enabled: boolean;
-  mode: string;
-  autoDetect?: "git" | null;
+/**
+ * vcc = UniPi's lossless zero-LLM summary; llm = a model-written summary.
+ */
+export type CompactionMethod = "vcc" | "llm";
+
+/** Summary sections that can be switched off (Advanced). */
+export interface SummarySections {
+  activeWork: boolean;
+  requests: boolean;
+  state: boolean;
+  decisions: boolean;
+  files: boolean;
+  commits: boolean;
+  errors: boolean;
+  lessons: boolean;
+  transcript: boolean;
 }
 
-/** UniPi-managed percentage auto-compaction trigger settings. */
+export interface CompactorConfig {
+  /** How automatic compactions are summarized. */
+  method: CompactionMethod;
+  /** What Pi's own /compact does: follow `method`, or force one. */
+  piCompact: "follow" | CompactionMethod;
+  /** When to compact: Pi's own context limit, or a percentage of the window. */
+  trigger: "pi" | "percent";
+  /** Context % that triggers compaction when trigger = "percent". */
+  thresholdPercent: number;
+  /** Notices when compaction runs or fails. */
+  notify: boolean;
+
+  // ── Advanced ──
+  /** Grow the kept tail when it would be tiny (≤5k tok, capped 25k). */
+  smartKeepTail: boolean;
+  /** Lossless summary budget in tokens; 0 = auto (scales with session size). */
+  summaryBudgetTokens: number;
+  sections: SummarySections;
+  /** Percentage trigger: minimum delay between compactions. */
+  cooldownMs: number;
+  /** Percentage trigger: new tokens needed to compact again while still above threshold. */
+  repeatMinGrowthTokens: number;
+  /** Extra instructions for model-written summaries. */
+  llmInstructions: string;
+  /** Write compaction diagnostics to /tmp/compactor-debug.json. */
+  debug: boolean;
+}
+
+/** Percentage auto-compaction trigger settings (decision input). */
 export interface AutoCompactionConfig {
-  /** Enable the extension-managed percentage trigger. Disabled by default for backward compatibility. */
   enabled: boolean;
   /** Trigger when Pi reports context usage at or above this percent (0-100 scale). */
   thresholdPercent: number;
@@ -115,142 +111,7 @@ export interface AutoCompactionConfig {
   notify: boolean;
 }
 
-export interface CompactorConfig {
-  // Compaction strategies
-  sessionGoals: CompactorStrategyConfig & { mode: "full" | "brief" | "off" };
-  filesAndChanges: CompactorStrategyConfig & { mode: "all" | "modified-only" | "off"; maxPerCategory: number };
-  commits: CompactorStrategyConfig & { mode: "full" | "brief" | "off"; maxCommits: number };
-  outstandingContext: CompactorStrategyConfig & { mode: "full" | "critical-only" | "off"; maxItems: number };
-  userPreferences: CompactorStrategyConfig & { mode: "all" | "recent-only" | "off"; maxPreferences: number };
-  briefTranscript: CompactorStrategyConfig & { mode: "full" | "compact" | "minimal" | "off"; userTokenLimit: number; assistantTokenLimit: number; toolCallLimit: number };
-  sessionContinuity: CompactorStrategyConfig & {
-    mode: "full" | "essential-only" | "off";
-    /** @deprecated Category filtering was never implemented; ignored by runtime. */
-    eventCategories: string[];
-  };
-  /** @deprecated Retained for config compatibility. */
-  fts5Index: CompactorStrategyConfig & { mode: "auto" | "manual" | "off"; chunkSize: number; cacheTtlHours: number };
-  sandboxExecution: CompactorStrategyConfig & { mode: "all" | "safe-only" | "off"; allowedLanguages: Language[]; outputLimit: number };
-
-  // Pipeline features
-  pipeline: {
-    autoInjection: boolean;
-    customNoisePatterns: string[];
-  };
-
-  // Auto compaction trigger
-  autoCompaction: AutoCompactionConfig;
-
-  // Global settings
-  overrideDefaultCompaction: boolean;
-  /** Boost default keep:1 to a larger tail when it is small (≤5k tok, capped 25k). Explicit keep:N always respected. */
-  smartKeepTail: boolean;
-  /** Ask the agent to continue after automatic (threshold/overflow) compaction. */
-  continueAfterThresholdCompact: boolean;
-  /** Write detailed compaction diagnostics to /tmp/compactor-debug.json. */
-  debug: boolean;
-}
-
-export type CompactorPreset = "precise" | "balanced" | "thorough" | "lean" | "opencode" | "verbose" | "minimal" | "custom";
-
-// ─────────────────────────────────────────────────────────
-// Session events (from context-mode)
-// ─────────────────────────────────────────────────────────
-
-export interface SessionEvent {
-  type: string;
-  category: string;
-  data: string;
-  priority: number;
-  data_hash: string;
-  project_dir?: string;
-  attribution_source?: string;
-  attribution_confidence?: number;
-}
-
-export interface StoredEvent {
-  id: number;
-  session_id: string;
-  type: string;
-  category: string;
-  priority: number;
-  data: string;
-  project_dir: string;
-  attribution_source: string;
-  attribution_confidence: number;
-  source_hook: string;
-  created_at: string;
-  data_hash: string;
-}
-
-export interface SessionMeta {
-  session_id: string;
-  project_dir: string;
-  started_at: string;
-  last_event_at: string | null;
-  event_count: number;
-  compact_count: number;
-}
-
-export interface ResumeRow {
-  snapshot: string;
-  event_count: number;
-  consumed: number;
-}
-
-export interface ResumeSnapshot {
-  generatedAt: string;
-  summary: string;
-  events: SessionEvent[];
-}
-
-// ─────────────────────────────────────────────────────────
-// Execution (from context-mode)
-// ─────────────────────────────────────────────────────────
-
-export interface ExecResult {
-  stdout: string;
-  stderr: string;
-  exitCode: number;
-  timedOut: boolean;
-  backgrounded?: boolean;
-}
-
-export type Language =
-  | "javascript"
-  | "typescript"
-  | "python"
-  | "shell"
-  | "ruby"
-  | "go"
-  | "rust"
-  | "php"
-  | "perl"
-  | "r"
-  | "elixir";
-
-// ─────────────────────────────────────────────────────────
-// Content store — REMOVED
-// SearchResult, IndexResult, StoreStats types no longer needed.
-// ─────────────────────────────────────────────────────────
-
 export interface RuntimeCounters {
-  sandboxRuns: number;
-  searchQueries: number;
   recallQueries: number;
   compactions: number;
-  totalTokensCompacted: number;
-}
-
-// ─────────────────────────────────────────────────────────
-// Info-screen integration
-// ─────────────────────────────────────────────────────────
-
-export interface CompactorInfoData {
-  tokensSaved: { value: string; detail: string };
-  costSaved: { value: string; detail: string };
-  pctReduction: { value: string; detail: string };
-  topTools: { value: string; detail: string };
-  compactions: { value: string; detail: string };
-  toolCalls: { value: string; detail: string };
 }

package/packages/core/README.md

@@ -21,6 +21,31 @@ emitEvent(pi, UNIPI_EVENTS.MODULE_READY, {
 const safeName = sanitize("my/feature: branch");
 ```
 
+## Hints (Unicrab)
+
+The hints system introduces **Unicrab**, a friendly pixel-crab mascot providing contextual onboarding and workflow guidance:
+
+- **What shows when**:
+  - **Startup**: One least-shown, least-recent hint on `session_start` (whatsnew hints prioritized after version upgrades; lore and whatsnew excluded from regular startup rotation).
+  - **Start Screen**: If `hints.header` is enabled, a custom startup header features 22×10 (≥72 cols) or 14×6 (40–71 cols) truecolor half-block crab pixel art, colored wordmark, and random lore line.
+  - **Widget**: A compact single-row hint above the editor (`<crab> <text>  <category · alt+h ›>`) rendered with a 7-column half-block mascot in truecolor/256-color (or opt-in Kitty image mode).
+  - **Events**: Contextual hints triggered by derived thresholds (`hints:context-high`, `hints:long-bash`, `hints:tool-errors`, `hints:long-prompt`, `hints:remember`, `hints:image-input`) and bus events. Capped at 4 event hints per session; never replaces a hint shown in the same turn.
+- **Shortcuts**:
+  - `Alt+H`: Cycle to the next startup hint (ordered least-shown first).
+  - `Alt+Shift+H`: Navigate backward in the session hint history stack.
+- **Commands**:
+  - `/unipi:hint`: Opens an interactive hub-kit overlay browser with live filtering, category headers, and seen/unseen/learned status tags.
+  - `/unipi:hint next`: Same as Alt+H.
+  - `/unipi:hint reset`: Resets show counts and learned state in `~/.unipi/global/hints/hints.json`.
+- **Settings (`hints` namespace)**:
+  - `hints.enabled` (boolean, default true)
+  - `hints.header` (boolean, default true): Unicrab start screen banner.
+  - `hints.crab` (enum: `auto` | `blocks` | `image`, default `auto`): `auto` resolves to half-blocks; `image` is opt-in experimental Kitty terminal graphics.
+  - `hints.reset` (action): Clears hint history.
+- **Lines (`src/hints/lines.ts`)**:
+  - Central lines file containing audited hints across command, shortcut, setting, capability, explain, trouble, whatsnew, workflow, and lore categories.
+  - **Rule**: Every named command, key, setting, or tool must be strictly verified against package source code before inclusion.
+
 ## Exports
 
 ### Constants

package/packages/core/child-agent.ts

@@ -0,0 +1 @@
+export * from "./src/child-agent/index.js";