@pencil-agent/nano-pencil 1.13.8 → 1.13.10

package/dist/build-meta.json

@@ -1,6 +1,6 @@
 {
-  "version": "1.13.8",
-  "commitHash": "66ecf7f",
+  "version": "1.13.10",
+  "commitHash": "027d681",
   "branch": "main",
-  "builtAt": "2026-04-26T15:41:55.811Z"
+  "builtAt": "2026-04-27T10:15:14.235Z"
 }

package/dist/builtin-extensions.js

@@ -20,10 +20,12 @@ const BUNDLED_PRESENCE_EXTENSION = join(__dirname, "extensions", "defaults", "pr
 const BUNDLED_INTERVIEW_EXTENSION = join(__dirname, "extensions", "defaults", "interview", "index.js");
 const BUNDLED_LOOP_EXTENSION = join(__dirname, "extensions", "defaults", "loop", "index.js");
 const BUNDLED_PLAN_EXTENSION = join(__dirname, "extensions", "defaults", "plan", "index.js");
+const BUNDLED_DIAGNOSTICS_EXTENSION = join(__dirname, "extensions", "defaults", "diagnostics", "index.js");
 const BUNDLED_SAL_EXTENSION = join(__dirname, "extensions", "defaults", "sal", "index.js");
 const BUNDLED_GRUB_EXTENSION = join(__dirname, "extensions", "defaults", "grub", "index.js");
 const BUNDLED_SUBAGENT_EXTENSION = join(__dirname, "extensions", "defaults", "subagent", "index.js");
 const BUNDLED_TEAM_EXTENSION = join(__dirname, "extensions", "defaults", "team", "index.js");
+const BUNDLED_IDLE_THINK_EXTENSION = join(__dirname, "extensions", "defaults", "idle-think", "index.js");
 const BUNDLED_BTW_EXTENSION = join(__dirname, "extensions", "defaults", "btw", "index.js");
 const BUNDLED_DEBUG_EXTENSION = join(__dirname, "extensions", "defaults", "debug", "index.js");
 const BUNDLED_MCP_EXTENSION = join(__dirname, "extensions", "defaults", "mcp", "index.js");
@@ -67,6 +69,17 @@ function findPackageRoot(startDir) {
  */
 export function getBuiltinExtensionPaths() {
     const paths = [];
+    // === Diagnostics extension (extension-owned issue buffer and reporting) ===
+    // Loaded first so it can subscribe to diagnostic:event before producer
+    // extensions such as SAL publish background failures.
+    if (existsSync(BUNDLED_DIAGNOSTICS_EXTENSION)) {
+        paths.push(BUNDLED_DIAGNOSTICS_EXTENSION);
+    }
+    else {
+        const diagnosticsTs = join(__dirname, "extensions", "defaults", "diagnostics", "index.ts");
+        if (existsSync(diagnosticsTs))
+            paths.push(diagnosticsTs);
+    }
     // === SAL extension (Structural Anchor Localization, default-on, experimental) ===
     // Loaded ahead of NanoMem because turn-context producers must publish before
     // turn-context consumers read. SAL is a producer of structuralAnchor; NanoMem
@@ -211,6 +224,15 @@ export function getBuiltinExtensionPaths() {
         if (existsSync(teamTs))
             paths.push(teamTs);
     }
+    // === IdleThink extension (background code exploration during idle) ===
+    if (existsSync(BUNDLED_IDLE_THINK_EXTENSION)) {
+        paths.push(BUNDLED_IDLE_THINK_EXTENSION);
+    }
+    else {
+        const idleThinkTs = join(__dirname, "extensions", "defaults", "idle-think", "index.ts");
+        if (existsSync(idleThinkTs))
+            paths.push(idleThinkTs);
+    }
     // === BTW extension (quick side question without interrupting) ===
     if (existsSync(BUNDLED_BTW_EXTENSION)) {
         paths.push(BUNDLED_BTW_EXTENSION);

package/dist/core/config/settings-manager.d.ts

@@ -105,6 +105,13 @@ export interface Settings {
     presence?: {
         enabled?: boolean;
     };
+    /** IdleThink extension settings - background code exploration during idle */
+    idleThink?: {
+        enabled?: boolean;
+        idleMinutes?: number;
+        dailyBudget?: number;
+        maxDurationMinutes?: number;
+    };
     /** Auto-update setting: 'always' = auto-update on startup, 'prompt' = ask user (default), 'never' = never check */
     autoUpdate?: "always" | "prompt" | "never";
     /** Last skipped version for update prompts */

package/dist/core/runtime/pencil-agent.d.ts

@@ -6,6 +6,7 @@
  */
 import { type SDKLogger } from "./sdk.js";
 import { type AgentSessionEvent } from "./agent-session.js";
+import type { Api } from "@pencil-agent/ai";
 import type { ThinkingLevel } from "@pencil-agent/agent-core";
 /**
  * Simplified options for PencilAgent wrapper.
@@ -13,10 +14,21 @@ import type { ThinkingLevel } from "@pencil-agent/agent-core";
 export interface PencilAgentOptions {
     /** API key for the provider. If omitted, uses environment variable. */
     apiKey?: string;
-    /** Provider name: 'anthropic', 'openai', 'google', etc. */
+    /** Provider name: 'anthropic', 'openai', 'google', or any custom provider in models.json. */
     provider?: string;
     /** Model ID: 'claude-4-5-20250920', 'gpt-4o', etc. */
     model?: string;
+    /**
+     * Optional base URL when registering a custom provider on the fly.
+     * Required when `provider` + `model` is not already defined in
+     * ~/.nanopencil/agent/models.json. Ignored when the model is found.
+     */
+    baseUrl?: string;
+    /**
+     * Optional API protocol for the dynamically-registered provider.
+     * Defaults to "openai-completions". Ignored when the model is found.
+     */
+    api?: Api;
     /** Thinking level: 'off' | 'low' | 'medium' | 'high' */
     thinkingLevel?: ThinkingLevel;
     /** Working directory. Default: process.cwd() */
@@ -69,6 +81,21 @@ export declare class PencilAgent {
      * Must be called before run/chat.
      */
     init(): Promise<void>;
+    /**
+     * Resolve constructor-provided provider/model into a Model<any>.
+     *
+     * Lookup order:
+     *   1. Existing entry in modelRegistry (e.g. ~/.nanopencil/agent/models.json
+     *      already declares this provider/model — common case for users who ran
+     *      /sal:setup or hand-edited models.json).
+     *   2. Dynamic registration when caller supplied baseUrl + apiKey — lets a
+     *      one-line constructor call wire up a brand-new OpenAI-compatible
+     *      endpoint without touching disk.
+     *   3. Otherwise return undefined and let createAgentSession fall back to
+     *      findInitialModel() (built-in default). The logger surfaces a warning
+     *      in this case so the caller knows their args were not honoured.
+     */
+    private resolveRequestedModel;
     /**
      * Handle session events - collects text for run()
      */

package/dist/core/runtime/pencil-agent.js

@@ -63,6 +63,10 @@ export class PencilAgent {
                 key: this.options.apiKey,
             });
         }
+        // Resolve user-specified provider/model into a Model<any> for createAgentSession.
+        // Without this, createAgentSession falls back to findInitialModel() which
+        // picks the first available built-in — silently ignoring constructor args.
+        const resolvedModel = this.resolveRequestedModel(modelRegistry);
         // Resolve tools
         let tools = undefined;
         if (this.options.tools && this.options.tools.length > 0) {
@@ -73,6 +77,7 @@ export class PencilAgent {
         // Create session
         this.sessionResult = await createAgentSession({
             cwd: this.cwd,
+            model: resolvedModel,
             thinkingLevel: this.options.thinkingLevel,
             tools,
             authStorage,
@@ -94,6 +99,57 @@ export class PencilAgent {
         this.session.subscribe(this.handleEvent.bind(this));
         this.initialized = true;
     }
+    /**
+     * Resolve constructor-provided provider/model into a Model<any>.
+     *
+     * Lookup order:
+     *   1. Existing entry in modelRegistry (e.g. ~/.nanopencil/agent/models.json
+     *      already declares this provider/model — common case for users who ran
+     *      /sal:setup or hand-edited models.json).
+     *   2. Dynamic registration when caller supplied baseUrl + apiKey — lets a
+     *      one-line constructor call wire up a brand-new OpenAI-compatible
+     *      endpoint without touching disk.
+     *   3. Otherwise return undefined and let createAgentSession fall back to
+     *      findInitialModel() (built-in default). The logger surfaces a warning
+     *      in this case so the caller knows their args were not honoured.
+     */
+    resolveRequestedModel(registry) {
+        const provider = this.options.provider;
+        const modelId = this.options.model;
+        if (!provider || !modelId)
+            return undefined;
+        const existing = registry.find(provider, modelId);
+        if (existing)
+            return existing;
+        if (this.options.baseUrl) {
+            try {
+                registry.registerProvider(provider, {
+                    api: this.options.api ?? "openai-completions",
+                    baseUrl: this.options.baseUrl,
+                    apiKey: this.options.apiKey,
+                    models: [{
+                            id: modelId,
+                            name: modelId,
+                            reasoning: false,
+                            input: ["text"],
+                            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+                            contextWindow: 128_000,
+                            maxTokens: 8192,
+                        }],
+                });
+                const registered = registry.find(provider, modelId);
+                if (registered)
+                    return registered;
+            }
+            catch (err) {
+                this.logger.warn(`[PencilAgent] dynamic provider registration failed for ${provider}/${modelId}: ${err.message}`);
+            }
+        }
+        this.logger.warn(`[PencilAgent] model ${provider}/${modelId} not found in registry. ` +
+            `Either add it to ~/.nanopencil/agent/models.json or pass { baseUrl, apiKey } to register it dynamically. ` +
+            `Falling back to default model selection.`);
+        return undefined;
+    }
     /**
      * Handle session events - collects text for run()
      */

package/dist/core/sub-agent/index.d.ts

@@ -8,4 +8,4 @@ export { SubAgentRuntime, subAgentRuntime } from "./sub-agent-runtime.js";
 export { InProcessSubAgentBackend } from "./sub-agent-backend.js";
 export { SubprocessSubAgentBackend } from "./subprocess-backend.js";
 export type { SubprocessBackendOptions } from "./subprocess-backend.js";
-export type { SubAgentSpec, SubAgentResult, SubAgentHandle, SubAgentBackend, } from "./sub-agent-types.js";
+export type { SubAgentSpec, SubAgentEvent, SubAgentResult, SubAgentHandle, SubAgentBackend, } from "./sub-agent-types.js";

package/dist/core/sub-agent/sub-agent-backend.js

@@ -32,6 +32,12 @@ export class InProcessSubAgentBackend {
             model: spec.model,
         };
         const { session } = await createAgentSession(options);
+        const unsubscribe = session.subscribe((event) => {
+            const subAgentEvent = toSubAgentEvent(id, event);
+            if (subAgentEvent) {
+                spec.onEvent?.(subAgentEvent);
+            }
+        });
         const timeoutMs = spec.timeoutMs;
         let status = "running";
         let result;
@@ -44,21 +50,10 @@ export class InProcessSubAgentBackend {
                 }
             }, timeoutMs);
         }
-        // Extract text from assistant message content
-        const extractTextFromContent = (content) => {
-            if (typeof content === "string")
-                return content;
-            if (Array.isArray(content)) {
-                return content
-                    .filter((part) => typeof part === "object" && part !== null && "type" in part && part.type === "text" && typeof part.text === "string")
-                    .map((part) => part.text)
-                    .join("\n");
-            }
-            return "";
-        };
         // Start the prompt
         const promptPromise = (async () => {
             try {
+                spec.onEvent?.({ type: "agent_start", subAgentId: id, timestamp: Date.now() });
                 await session.prompt(prompt, {
                     images: spec.images,
                 });
@@ -107,6 +102,14 @@ export class InProcessSubAgentBackend {
                 }
                 // Clean up signal handler
                 spec.signal.removeEventListener("abort", signalHandler);
+                unsubscribe();
+                spec.onEvent?.({
+                    type: "agent_end",
+                    subAgentId: id,
+                    timestamp: Date.now(),
+                    success: result?.success ?? false,
+                    error: result?.error,
+                });
             }
         })();
         return {
@@ -132,6 +135,69 @@ export class InProcessSubAgentBackend {
         };
     }
 }
+function toSubAgentEvent(subAgentId, event) {
+    const timestamp = Date.now();
+    switch (event.type) {
+        case "message_update":
+            return {
+                type: "message_update",
+                subAgentId,
+                timestamp,
+                text: extractMessageText(event.message),
+                deltaType: event.assistantMessageEvent.type,
+            };
+        case "message_end":
+            return {
+                type: "message_end",
+                subAgentId,
+                timestamp,
+                text: extractMessageText(event.message),
+            };
+        case "tool_execution_start":
+            return {
+                type: "tool_start",
+                subAgentId,
+                timestamp,
+                toolName: event.toolName,
+                args: event.args,
+            };
+        case "tool_execution_update":
+            return {
+                type: "tool_update",
+                subAgentId,
+                timestamp,
+                toolName: event.toolName,
+                partialResult: event.partialResult,
+            };
+        case "tool_execution_end":
+            return {
+                type: "tool_end",
+                subAgentId,
+                timestamp,
+                toolName: event.toolName,
+                isError: event.isError,
+            };
+        default:
+            return undefined;
+    }
+}
+function extractTextFromContent(content) {
+    if (typeof content === "string")
+        return content;
+    if (Array.isArray(content)) {
+        return content
+            .filter((part) => typeof part === "object" && part !== null && "type" in part && part.type === "text" && typeof part.text === "string")
+            .map((part) => part.text)
+            .join("\n");
+    }
+    return "";
+}
+function extractMessageText(message) {
+    if (typeof message !== "object" || message === null || !("content" in message)) {
+        return "";
+    }
+    return extractTextFromContent(message.content);
+}
 async function buildPromptWithContextFiles(spec) {
     if (!spec.contextFiles?.length) {
         return spec.prompt;

package/dist/core/sub-agent/sub-agent-types.d.ts

@@ -1,5 +1,5 @@
 /**
- * [WHO]: SubAgent types - SubAgentSpec, SubAgentHandle, SubAgentBackend, SubAgentResult
+ * [WHO]: SubAgent types - SubAgentSpec, SubAgentEvent, SubAgentHandle, SubAgentBackend, SubAgentResult
  * [FROM]: Depends on @pencil-agent/agent-core, @pencil-agent/ai, core/tools
  * [TO]: Consumed by ./sub-agent-runtime, ./sub-agent-backend, ./index.ts, extensions/defaults/subagent/*, extensions/defaults/team/*
  * [HERE]: core/sub-agent/sub-agent-types.ts - SubAgent type definitions
@@ -7,6 +7,47 @@
  */
 import type { ImageContent, Model } from "@pencil-agent/ai";
 import type { Tool } from "../tools/index.js";
+/** Realtime lifecycle event emitted by a running SubAgent. */
+export type SubAgentEvent = {
+    type: "agent_start";
+    subAgentId: string;
+    timestamp: number;
+} | {
+    type: "message_update";
+    subAgentId: string;
+    timestamp: number;
+    text: string;
+    deltaType?: string;
+} | {
+    type: "message_end";
+    subAgentId: string;
+    timestamp: number;
+    text: string;
+} | {
+    type: "tool_start";
+    subAgentId: string;
+    timestamp: number;
+    toolName: string;
+    args: unknown;
+} | {
+    type: "tool_update";
+    subAgentId: string;
+    timestamp: number;
+    toolName: string;
+    partialResult: unknown;
+} | {
+    type: "tool_end";
+    subAgentId: string;
+    timestamp: number;
+    toolName: string;
+    isError: boolean;
+} | {
+    type: "agent_end";
+    subAgentId: string;
+    timestamp: number;
+    success: boolean;
+    error?: string;
+};
 /**
  * Specification for spawning a SubAgent.
  */
@@ -29,6 +70,8 @@ export interface SubAgentSpec {
     contextFiles?: string[];
     /** Optional callback invoked after the run result is available */
     exitHook?: (result: SubAgentResult) => Promise<void> | void;
+    /** Optional realtime observer for TUI/status integrations */
+    onEvent?: (event: SubAgentEvent) => void;
 }
 /**
  * Result from a completed SubAgent run.

package/dist/core/sub-agent/sub-agent-types.js

@@ -1,5 +1,5 @@
 /**
- * [WHO]: SubAgent types - SubAgentSpec, SubAgentHandle, SubAgentBackend, SubAgentResult
+ * [WHO]: SubAgent types - SubAgentSpec, SubAgentEvent, SubAgentHandle, SubAgentBackend, SubAgentResult
  * [FROM]: Depends on @pencil-agent/agent-core, @pencil-agent/ai, core/tools
  * [TO]: Consumed by ./sub-agent-runtime, ./sub-agent-backend, ./index.ts, extensions/defaults/subagent/*, extensions/defaults/team/*
  * [HERE]: core/sub-agent/sub-agent-types.ts - SubAgent type definitions

package/dist/extensions/defaults/AGENT.md

@@ -3,6 +3,11 @@
 > P2 | Parent: ../AGENT.md
 
 Member List
+diagnostics/index.ts: Diagnostics extension entry, subscribes to diagnostic:event, buffers session-local diagnostic records, prompts only after threshold at agent_end, registers /report-issue
+diagnostics/types.ts: Diagnostic event/report type contract and diagnostic:event channel name
+diagnostics/diagnostic-buffer.ts: DiagnosticBuffer, event coercion, fingerprint dedupe, prompt gating
+diagnostics/reporter.ts: User-approved InsForge pencil_issue_events reporter, configured via NANOPENCIL_ISSUE_* env vars
+diagnostics/redaction.ts: Diagnostic message normalization and secret/path redaction helpers
 link-world/index.ts: Internet access extension, provides internet-search Skill after setup
 mcp/index.ts: MCP protocol integration extension, MCP guidance resources
 presence/index.ts: AI-driven opening + idle presence lines, uses NanoMemEngine episodes/preferences/lessons + git/cwd snapshot, injects latest line into agent systemPrompt every turn for main-conversation perception, 30s debounce + idle in-flight lock, configurable via settings.presence.enabled, PRESENCE_MESSAGE_TYPE renderer
@@ -37,12 +42,12 @@ loop/scheduler-controller.ts: SchedulerController - in-memory recurring task sto
 loop/scheduler-parser.ts: Loop command parsing with flags/subcommands, parseSchedulerCommand/parseDurationSpec/buildSchedulerHelp, --name/--max/--quiet
 loop/scheduler-types.ts: Scheduled loop types, LoopPayloadKind/ScheduledLoopTask/LoopStartSpec/ParsedSchedulerCommand
 loop/README.md: Loop extension documentation - recurring scheduler usage and flags
-sal/index.ts: SAL extension entry, enabled by default, registers --nosal/--sal-ab/--sal-rebuild-terrain flags, /sal:coverage /sal:status /sal:setup commands, before_agent_start/tool_execution_start/agent_end hooks; /sal:setup writes ~/.memory-experiments/credentials.json with adapter inference (insforge/jsonl/noop); publishes structuralAnchor via core/runtime/turn-context (no SAL-specific globals); emits run_start/turn_anchor/run_end eval events through pluggable EvalSink with best-effort shutdown flushing; writes local .memory-experiments sidecar anchors only when --sal-ab or NANOPENCIL_SAL_AB=1 is enabled; runtime no-op when --nosal is set
+sal/index.ts: SAL extension entry, enabled by default, registers --nosal/--sal-ab/--sal-rebuild-terrain flags, /sal:coverage /sal:status /sal:setup commands, before_agent_start/tool_execution_start/agent_end hooks; /sal:setup writes ~/.memory-experiments/credentials.json with adapter inference (insforge/jsonl/noop); publishes structuralAnchor via core/runtime/turn-context (no SAL-specific globals); emits run_start/turn_anchor/run_end eval events through pluggable EvalSink with best-effort shutdown flushing; publishes SAL eval background failures to diagnostic:event; writes local .memory-experiments sidecar anchors only when --sal-ab or NANOPENCIL_SAL_AB=1 is enabled; runtime no-op when --nosal is set
 sal/terrain.ts: TerrainSnapshot/TerrainNode/TerrainEdge model, buildTerrainIndex(), checkDipCoverage(), isSnapshotStale(), moduleIdForPath(), parses P2 AGENT.md and P3 file headers
 sal/anchors.ts: StructuralAnchor/AnchorResolution model, locateTask(), locateAction(), evidence-driven scoring with tunable SalWeights, CJK bigram tokenization
 sal/weights.ts: SalWeights interface, SAL_DEFAULT_WEIGHTS, loadSalWeights() reads sal-config.json from workspace or .memory-experiments/sal/
 sal/eval/index.ts: createEvalSink() factory + barrel re-exports; adapter selection via options.adapter or endpoint scheme inference (http(s)→insforge, file://|/|./|../→jsonl, missing→noop); ONLY entry point SAL imports from
-sal/eval/types.ts: EvalSink interface, EvalEventEnvelope/EvalEventType (run_start/run_end/turn_anchor), EvalAdapterId ("insforge"|"jsonl"|"noop"), CreateEvalSinkOptions, createEvalEvent factory; zero-dependency type surface
+sal/eval/types.ts: EvalSink interface, EvalEventEnvelope/EvalEventType (run_start/run_end/turn_anchor), EvalAdapterId ("insforge"|"jsonl"|"noop"), CreateEvalSinkOptions with optional onDiagnostic callback, createEvalEvent factory; zero-dependency type surface
 sal/eval/noop-sink.ts: noopSink — silent EvalSink used when eval disabled or no adapter configured
 sal/eval/insforge-sink.ts: InsForgeEvalSink — PostgREST adapter, routes run_start→eval_runs INSERT (merge-duplicates) with legacy-schema fallback, writes turn_anchor/tool_trace/memory_recalls/run_end only after parent run confirmation, tool_trace→eval_tool_traces with PGRST204 fallback, memory_recalls→eval_memory_recalls batch INSERT, run_end→eval_runs PATCH; allowSelfSigned TLS option logs only in development runtime, batching with default 2000ms interval
 sal/eval/jsonl-sink.ts: JsonlEvalSink — append-only filesystem adapter, one JSON object per line, accepts file:// URLs or plain paths, auto-creates parent dir, batched writes

package/dist/extensions/defaults/CLAUDE.md

@@ -17,10 +17,11 @@ security-audit/engine/interceptor.ts: Request/response interception, Interceptor
 security-audit/engine/logger.ts: Security event logging, JSON file audit trail
 security-audit/engine/detector.ts: Vulnerability detection, pattern matching for dangerous commands
 soul/index.ts: AI personality evolution extension, persistent personality across sessions
-grub/index.ts: Grub extension entry - long-running autonomous harness, dual-phase system prompts (initializer/coding), /grub command (start/status/resume/stop) + grub renderer, session_start auto-adopt, git harness commit, pruneStale cleanup
-grub/grub-controller.ts: GrubController - state machine for /grub iterations, durable persistState on every transition, adoptResumedTask for cross-session resume, validateCompletion downgrades premature complete when feature-list still has pending entries
-grub/grub-parser.ts: Grub command parsing - parseGrubCommand/buildGrubHelp with resume subcommand, status --json, --max-iter/--max-fail flags
-grub/grub-types.ts: Grub types - GrubStatus/GrubDecisionStatus/GrubDecision/GrubPhase/GrubTaskState/GrubTaskSnapshot/ParsedGrubCommand + FeatureItem/FeatureList (version 1 schema) + PersistedGrubState envelope
+grub/index.ts: Grub extension entry - long-running autonomous harness, locale-aware dual-phase system prompts (initializer/coding), /grub command (start/status/resume/stop) + grub renderer, session_start auto-adopt, git harness commit, pruneStale cleanup
+grub/grub-controller.ts: GrubController - state machine for /grub iterations, locale-persisted prompt generation, durable persistState on every transition, adoptResumedTask for cross-session resume, validateCompletion downgrades premature complete when feature-list still has pending entries
+grub/grub-parser.ts: Grub command parsing - parseGrubCommand/buildGrubHelp with localized help, resume subcommand, status --json, --max-iter/--max-fail flags
+grub/grub-types.ts: Grub types - GrubStatus/GrubDecisionStatus/GrubDecision/GrubPhase/GrubLocale/GrubTaskState/GrubTaskSnapshot/ParsedGrubCommand + FeatureItem/FeatureList (version 1 schema) + PersistedGrubState envelope
+grub/grub-i18n.ts: Grub localization helper - detectGrubLocale(), grubText(), languageName(), English/Chinese TUI strings
 grub/grub-feature-list.ts: feature-list.json IO - readFeatureList/writeFeatureList atomic write, validateFeatureListDiff enforces passes/evidence-only mutations, createInitialFeatureList placeholder, migrateChecklistToFeatureList legacy converter, countPassing/allPassing/firstPending helpers
 grub/grub-persistence.ts: Cross-session persistence - persistState atomic JSON write to .grub/<id>/state.json, loadState shape-validated read, discoverActiveTasks scans .grub/ for running records, pruneStale removes terminal harnesses older than 30 days by default
 grub/README.md: Grub extension documentation - long-running harness contract, feature-list.json schema, completion guard, cross-session resume, legacy migration

package/dist/extensions/defaults/diagnostics/diagnostic-buffer.d.ts

@@ -0,0 +1,19 @@
+/**
+ * [WHO]: DiagnosticBuffer, coerceDiagnosticEvent()
+ * [FROM]: Depends on ./types.js and ./redaction.js for event schema and privacy normalization
+ * [TO]: Consumed by extensions/defaults/diagnostics/index.ts
+ * [HERE]: extensions/defaults/diagnostics/diagnostic-buffer.ts - session-local dedupe and prompt gating state
+ */
+import { type DiagnosticEvent, type DiagnosticRecord } from "./types.js";
+export declare class DiagnosticBuffer {
+    private records;
+    add(event: DiagnosticEvent): DiagnosticRecord;
+    all(): DiagnosticRecord[];
+    last(): DiagnosticRecord | undefined;
+    findPromptCandidate(): DiagnosticRecord | undefined;
+    findUnreported(): DiagnosticRecord[];
+    markPrompted(fingerprint: string): void;
+    markReported(fingerprint: string): void;
+    private trim;
+}
+export declare function coerceDiagnosticEvent(value: unknown): DiagnosticEvent | undefined;

package/dist/extensions/defaults/diagnostics/diagnostic-buffer.js

@@ -0,0 +1,125 @@
+/**
+ * [WHO]: DiagnosticBuffer, coerceDiagnosticEvent()
+ * [FROM]: Depends on ./types.js and ./redaction.js for event schema and privacy normalization
+ * [TO]: Consumed by extensions/defaults/diagnostics/index.ts
+ * [HERE]: extensions/defaults/diagnostics/diagnostic-buffer.ts - session-local dedupe and prompt gating state
+ */
+import { normalizeDiagnosticMessage, sanitizeDiagnosticValue } from "./redaction.js";
+const MAX_RECORDS = 100;
+export class DiagnosticBuffer {
+    records = new Map();
+    add(event) {
+        const now = event.created_at ?? new Date().toISOString();
+        const sanitized = {
+            source: event.source,
+            severity: event.severity,
+            category: event.category,
+            message: normalizeDiagnosticMessage(event.message),
+            detail: sanitizeDiagnosticValue(event.detail),
+            context: sanitizeDiagnosticValue(event.context),
+            created_at: now,
+        };
+        const fingerprint = event.fingerprint ?? buildFingerprint(sanitized);
+        const existing = this.records.get(fingerprint);
+        if (existing) {
+            existing.last_seen_at = now;
+            existing.occurrence_count += 1;
+            existing.severity = maxSeverity(existing.severity, sanitized.severity);
+            existing.detail = sanitized.detail;
+            existing.context = { ...(existing.context ?? {}), ...(sanitized.context ?? {}) };
+            // New occurrences invalidate a prior auto-report so the next
+            // agent_end batch uploads the updated count.
+            existing.reported = false;
+            return existing;
+        }
+        const record = {
+            ...sanitized,
+            fingerprint,
+            first_seen_at: now,
+            last_seen_at: now,
+            occurrence_count: 1,
+            prompted: false,
+            reported: false,
+        };
+        this.records.set(fingerprint, record);
+        this.trim();
+        return record;
+    }
+    all() {
+        return Array.from(this.records.values()).sort((a, b) => b.last_seen_at.localeCompare(a.last_seen_at));
+    }
+    last() {
+        return this.all()[0];
+    }
+    findPromptCandidate() {
+        return this.all().find((record) => !record.prompted && shouldPrompt(record));
+    }
+    findUnreported() {
+        return this.all().filter((record) => !record.reported);
+    }
+    markPrompted(fingerprint) {
+        const record = this.records.get(fingerprint);
+        if (record)
+            record.prompted = true;
+    }
+    markReported(fingerprint) {
+        const record = this.records.get(fingerprint);
+        if (record)
+            record.reported = true;
+    }
+    trim() {
+        if (this.records.size <= MAX_RECORDS)
+            return;
+        const sorted = this.all();
+        for (const record of sorted.slice(MAX_RECORDS)) {
+            this.records.delete(record.fingerprint);
+        }
+    }
+}
+export function coerceDiagnosticEvent(value) {
+    if (!value || typeof value !== "object")
+        return undefined;
+    const input = value;
+    const source = typeof input.source === "string" ? input.source : undefined;
+    const severity = isSeverity(input.severity) ? input.severity : undefined;
+    const category = isCategory(input.category) ? input.category : "unknown";
+    const message = typeof input.message === "string" ? input.message : undefined;
+    if (!source || !severity || !message)
+        return undefined;
+    return {
+        source,
+        severity,
+        category,
+        message,
+        detail: input.detail,
+        fingerprint: typeof input.fingerprint === "string" ? input.fingerprint : undefined,
+        context: input.context && typeof input.context === "object" ? input.context : undefined,
+        created_at: typeof input.created_at === "string" ? input.created_at : undefined,
+    };
+}
+function shouldPrompt(record) {
+    if (record.severity === "error")
+        return record.occurrence_count >= 3;
+    if (record.severity === "warning")
+        return record.occurrence_count >= 5 || record.category === "fallback";
+    return false;
+}
+function buildFingerprint(event) {
+    return `${event.source}:${event.category}:${normalizeDiagnosticMessage(event.message).toLowerCase()}`;
+}
+function isSeverity(value) {
+    return value === "debug" || value === "info" || value === "warning" || value === "error";
+}
+function isCategory(value) {
+    return (value === "network" ||
+        value === "fallback" ||
+        value === "persistence" ||
+        value === "config" ||
+        value === "extension_timeout" ||
+        value === "schema" ||
+        value === "unknown");
+}
+function maxSeverity(a, b) {
+    const rank = { debug: 0, info: 1, warning: 2, error: 3 };
+    return rank[b] > rank[a] ? b : a;
+}

package/dist/extensions/defaults/diagnostics/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * [WHO]: diagnosticsExtension - diagnostic:event listener, /report-issue command, silent auto-upload on agent_end
+ * [FROM]: Depends on core/extensions/types, @pencil-agent/tui, ./diagnostic-buffer, ./reporter, ./types
+ * [TO]: Auto-loaded by builtin-extensions.ts as a default extension before diagnostic producers
+ * [HERE]: extensions/defaults/diagnostics/index.ts - extension-owned diagnostic buffer; background failures auto-upload silently at agent_end, /report-issue stays for explicit user-initiated bundles
+ */
+import type { ExtensionAPI } from "../../../core/extensions/types.js";
+export default function diagnosticsExtension(api: ExtensionAPI): Promise<void>;