napkin-distill Extension: Auto-Distill and Session Management

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/cad0p/pi-napkin/llms.txt

Use this file to discover all available pages before exploring further.

​

Extension entry point

export default function (pi: ExtensionAPI) {
  // all closure-scoped state, handlers, strategies, commands, and tools
}

​

Closure-scoped state

​

Configuration interfaces

​

DistillConfig

export interface DistillConfig {
  enabled: boolean;
  intervalMinutes: number;
  maxDurationMinutes?: number;
  onShutdown: boolean;
  model?: { provider: string; id: string };
}

​

VaultConfig

export interface VaultConfig {
  showStatus: boolean;
  distill: DistillConfig;
}

​

MalformedVaultConfigError

export class MalformedVaultConfigError extends Error {
  readonly configPath: string;
  readonly parseError: string;
}

​

Constants

​

DEFAULT_DISTILL

export const DEFAULT_DISTILL: DistillConfig = {
  enabled: false,
  intervalMinutes: 60,
  maxDurationMinutes: 10,
  onShutdown: true,
};

​

session_start handler

1. Resets autoDistillSuppressed to false before any early-return paths.
2. Resolves the vault via new Napkin(ctx.cwd).vault. Returns early if no vault is reachable.
3. Calls loadVaultConfig(vaultConfigPath). On MalformedVaultConfigError: surfaces an error notify and returns. On any other throw: re-throws.
4. Checks config.enabled — if false, sets distill: off status and returns.
5. Checks process.env.NAPKIN_DISTILL_NO_RECURSE — if set, returns immediately to prevent recursive distill spawning inside a distill subprocess.
6. Calls ensureVaultReadyForDistill(vault, "fast") for the fast-level health check and auto-init (git-init + managed .gitignore block). Surfaces structured findings via surfaceHealthFindings. On LEGACY_EMBEDDED_LAYOUT_ERROR, surfaces a migration notice and sets setupFailed = true.
7. Calls cleanupStaleWorktrees({ contentPath: vaultContentPath }) to sweep dead worktrees. Best-effort — never throws.
8. Reads persisted autoDistillSuppressed from the session’s getBranch() entries (via readPersistedSuppressed). Overridden to true if setupFailed.
9. Sets lastDistillCompletionMessageCursor = ctx.sessionManager.getEntries().length — anchors the overlap cursor to the current session tail so resumed sessions don’t re-scan pre-resume entries.
10. Arms the countdown repaint interval (countdownHandle) and the distill interval (intervalHandle). Calls renderIdleStatus() immediately to paint initial state.

​

session_shutdown handler

1. Clears all three handles (intervalHandle, countdownHandle, pollHandle). Setting intervalHandle to null first prevents the rare race where the interval fires during shutdown.
2. Resets isRunning = false to avoid polluting a subsequent in-process session.
3. Re-reads vault and config (not cached from session_start — keeps closure small).
4. Calls shouldDistillOnShutdown(event, config, autoDistillSuppressed, sessionFile, currentSize, lastSpawnedSize, lastSessionSize) to decide whether to spawn a final distill.
5. If the vault has .git/ and shouldDistillOnShutdown returns true:
   • Runs ensureVaultReadyForDistill(vault, "full") — the full health check.
   • Surfaces findings via surfaceHealthFindings and surfaceSetupError.
   • If no errors: calls spawnDistillInWorktree(...) and updates lastSpawnedSize.
6. Resets uiRef = null. Any failure logs to stderr and falls through — shutdown is never blocked.

​

Distill strategies

​

worktreeSpawnFn

• Calls spawnDistillInWorktree(...) to create a git worktree, fork the session, and spawn the detached wrapper.
• Returns:
  {
    target: workspace.worktreePath,   // disappears when wrapper completes
    cleanup,                           // calls cleanupDistillWorkspace on timeout
    onComplete,                        // posts overlap notice on success
    checkFailure,                      // looks for wrapper error log
    checkOutcome                       // reads *.outcome sidecar
  }
  
• On DistillError from the workspace layer: paints distill: setup failed in the status bar and returns null (runner skips the poll loop).

​

legacySpawnFn

• Creates a tmpdir via fs.mkdtempSync, forks the session into it, spawns pi -p directly as a detached process.
• Returns:
  {
    target: tmpDir,       // disappears when the legacy subprocess removes it
    cleanup              // fs.rmSync(tmpDir, { recursive: true, force: true })
  }
  
• No checkFailure or checkOutcome — the legacy path has no wrapper sidecar.

​

Shared runner lifecycle (runDistillWith)

1. Returns immediately if isRunning.
2. Resolves vault and config; bails silently if cwd isn’t a vault.
3. Reads session file size; deduplicates against lastSessionSize.
4. Runs strategy.preflight if provided; short-circuits on { ok: false }.
5. Calls strategy.spawnFn; on null return, paints distill: spawn failed.
6. Sets lastSpawnedSize = currentSize, isRunning = true, starts pollHandle.
7. Poll ticks every DISTILL_POLL_TICK_MS. While target exists and no timeout: repaint in-flight status.
8. On timeout: calls spawnCleanup(), paints error, notifies.
9. On target gone: advances lastSessionSize and lastDistillTimestamp, calls onComplete (overlap notice), calls checkFailure (error log probe), calls checkOutcome (sidecar dispatch via formatOutcomeNotification), paints final status, notifies.

​

Slash commands

​

/distill

• If isRunning is true: calls ctx.ui.notify("Distill already running", "warning") and returns.
• Sets lastSessionSize = 0 to bypass the size-dedup check.
• Calls runDistill(ctx), which routes to worktreeSpawnFn when git is present, distill.enabled is true, and the vault uses the subdir layout. Falls back to legacySpawnFn otherwise.

​

/distill-auto-this-session [on|off|status]

distill is disabled in vault config — set distill.enabled=true in .napkin/config.json

​

/distill-status

​

Agent tool: napkin_distill_status

pi.registerTool({
  name: "napkin_distill_status",
  parameters: Type.Object({}),
  // ...
})

{ "error": "no vault in cwd" }

{
  "active": [
    {
      "pid": 12345,
      "branch": "distill/abc123-1715198400",
      "elapsedSeconds": 47,
      "session": "abc.jsonl",
      "alive": true,
      "startedAt": "2024-05-08T12:00:00.000Z",
      "startSha": "a1b2c3d"
    }
  ],
  "unmerged": ["distill/xyz456-1715100000"]
}

​

Exported functions

​

formatOutcomeNotification outcome mapping