@pencil-agent/nano-pencil 1.14.3 → 1.14.4

package/dist/build-meta.json

@@ -1,6 +1,6 @@
 {
-  "version": "1.14.3",
-  "commitHash": "1a4f55a",
+  "version": "1.14.4",
+  "commitHash": "092b256",
   "branch": "main",
-  "builtAt": "2026-05-27T01:43:40.032Z"
+  "builtAt": "2026-05-27T16:26:12.388Z"
 }

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

@@ -1,5 +1,5 @@
 /**
- * [WHO]: SettingsManager class, two-tier settings (global + project-local)
+ * [WHO]: SettingsManager class, two-tier settings (global + project-local), agent loop defaults
  * [FROM]: Depends on ai, node:fs, proper-lockfile, config.ts
  * [TO]: Consumed by index.ts, main.ts, core/runtime/sdk.ts, cli/config-selector.ts, extensions/defaults/team/index.ts, modes/interactive/components/model-selector.ts, modes/interactive/components/config-selector.ts, and test files
  * [HERE]: core/config/settings-manager.ts - user preferences aggregation
@@ -20,6 +20,9 @@ export interface RetrySettings {
     baseDelayMs?: number;
     maxDelayMs?: number;
 }
+export interface AgentLoopSettings {
+    maxToolResultBatchSizeChars?: number;
+}
 export interface TerminalSettings {
     showImages?: boolean;
     clearOnShrink?: boolean;
@@ -65,6 +68,7 @@ export interface Settings {
     defaultModel?: string;
     defaultThinkingLevel?: "off" | "minimal" | "low" | "medium" | "high" | "xhigh";
     agentLoopFramework?: AgentLoopFrameworkSettingInput;
+    agentLoop?: AgentLoopSettings;
     transport?: TransportSetting;
     steeringMode?: "all" | "one-at-a-time";
     followUpMode?: "all" | "one-at-a-time";
@@ -218,6 +222,9 @@ export declare class SettingsManager {
     getDefaultThinkingLevel(): "off" | "minimal" | "low" | "medium" | "high" | "xhigh" | undefined;
     setDefaultThinkingLevel(level: "off" | "minimal" | "low" | "medium" | "high" | "xhigh"): void;
     getAgentLoopFramework(): AgentLoopFrameworkSetting | undefined;
+    getAgentLoopSettings(): {
+        maxToolResultBatchSizeChars: number;
+    };
     setAgentLoopFramework(framework: AgentLoopFrameworkSettingInput | undefined): void;
     getTransport(): TransportSetting;
     setTransport(transport: TransportSetting): void;

package/dist/core/config/settings-manager.js

@@ -4,6 +4,7 @@ import lockfile from "proper-lockfile";
 import { APP_NAME, CONFIG_DIR_NAME } from "../../config.js";
 import { defaultAgentDirContext } from "../agent-dir/agent-dir-context.js";
 import { readFile, writeFile, mkdir } from "node:fs/promises";
+const DEFAULT_MAX_TOOL_RESULT_BATCH_SIZE_CHARS = 200_000;
 export function normalizeAgentLoopFrameworkSetting(value) {
     if (value === "high-intelligence")
         return "standard";
@@ -574,6 +575,14 @@ export class SettingsManager {
     getAgentLoopFramework() {
         return normalizeAgentLoopFrameworkSetting(this.settings.agentLoopFramework);
     }
+    getAgentLoopSettings() {
+        const configured = this.settings.agentLoop?.maxToolResultBatchSizeChars;
+        return {
+            maxToolResultBatchSizeChars: typeof configured === "number" && Number.isFinite(configured) && configured > 0
+                ? Math.floor(configured)
+                : DEFAULT_MAX_TOOL_RESULT_BATCH_SIZE_CHARS,
+        };
+    }
     setAgentLoopFramework(framework) {
         const normalized = normalizeAgentLoopFrameworkSetting(framework);
         if (normalized === undefined) {

package/dist/core/extensions/runner.d.ts

@@ -1,8 +1,8 @@
 /**
- * [WHO]: ExtensionRunner class, lifecycle management, event emission
- * [FROM]: Depends on agent-core, ai, tui, modes/theme, session-manager, types.ts
- * [TO]: Consumed by core/extensions/index.ts, core/extensions/wrapper.ts
- * [HERE]: core/extensions/runner.ts - extension execution and lifecycle management
+ * [WHO]: ExtensionRunner class, lifecycle management, event emission, slash-command dispatch chokepoint (invokeCommand), telemetry sink wiring (setTelemetrySink)
+ * [FROM]: Depends on agent-core, ai, tui, modes/theme, session-manager, types.ts, core/telemetry (ExtensionTelemetrySink + classifyArgsSignature for the P1 ext_command_events writer)
+ * [TO]: Consumed by core/extensions/index.ts, core/extensions/wrapper.ts, core/runtime/agent-session.ts (delegates command dispatch via invokeCommand)
+ * [HERE]: core/extensions/runner.ts - extension execution and lifecycle management; owns the single try/catch around command.handler so telemetry can wrap every invocation regardless of caller mode
  */
 import type { AgentMessage } from "@pencil-agent/agent-core";
 import type { ImageContent } from "@pencil-agent/ai";
@@ -11,6 +11,7 @@ import type { ResourceDiagnostic } from "../diagnostics.js";
 import type { KeybindingsConfig } from "../keybindings.js";
 import type { ModelRegistry } from "../model-registry.js";
 import type { SessionManager } from "../session/session-manager.js";
+import { type ExtensionTelemetrySink, type LlmCallEventInput } from "../telemetry/index.js";
 import type { BeforeAgentStartEvent, BeforeAgentStartEventResult, ContextEvent, Extension, ExtensionActions, ExtensionCommandContext, ExtensionCommandContextActions, ExtensionContext, ExtensionContextActions, ExtensionError, ExtensionEvent, ExtensionFlag, ExtensionRuntime, ExtensionShortcut, ExtensionUIContext, InputEvent, InputEventResult, InputSource, MessageRenderer, RegisteredCommand, RegisteredTool, ResourcesDiscoverEvent, SessionBeforeCompactResult, SessionBeforeForkResult, SessionBeforeSwitchResult, SessionBeforeTreeResult, ToolCallEvent, ToolCallEventResult, ToolResultEvent, ToolResultEventResult, UserBashEvent, UserBashEventResult } from "./types.js";
 /** Combined result from all before_agent_start handlers */
 interface BeforeAgentStartCombinedResult {
@@ -90,6 +91,7 @@ export declare class ExtensionRunner {
     private shutdownHandler;
     private shortcutDiagnostics;
     private commandDiagnostics;
+    private telemetrySink?;
     private _beforeAgentStartTimeoutMs;
     private get beforeAgentStartTimeoutMs();
     private readonly beforeAgentStartTimeoutSentinel;
@@ -127,6 +129,70 @@ export declare class ExtensionRunner {
         extensionPath: string;
     }>;
     getCommand(name: string): RegisteredCommand | undefined;
+    /**
+     * Returns the owning Extension for a given slash command name. Used by the
+     * telemetry middleware to stamp `extension_name` on each ext_command_events
+     * row. Falls back to undefined when no extension claims the command.
+     */
+    private findCommandOwner;
+    /**
+     * Derive a short, stable extension name from an Extension record. For
+     * built-ins (extensions/defaults/<name>) and most user extensions
+     * (packages/<name>) the directory basename is the right answer.
+     */
+    private deriveExtensionName;
+    /**
+     * Attach (or replace) the extension telemetry sink. The runner owns sink
+     * lifecycle from this point — invokeCommand() will fire-and-forget one
+     * `ext_command_events` row per invocation, and writeLlmCallEvent() (called
+     * from extension-core-bindings) writes one `ext_llm_calls` row per
+     * extension-initiated LLM call. Passing the noop sink (the factory's
+     * default when no insforge credentials exist) is the safe way to disable
+     * telemetry without scattering null-checks at the call sites.
+     */
+    setTelemetrySink(sink: ExtensionTelemetrySink): void;
+    /**
+     * Passthrough used by core/runtime/extension-core-bindings.ts after each
+     * extension-initiated LLM call. The runner owns the sink; the binding
+     * doesn't import it directly to keep its concerns scoped to LLM plumbing.
+     */
+    writeLlmCallEvent(input: LlmCallEventInput): void;
+    /**
+     * Wrap an extension hook handler invocation in three layers:
+     *
+     *   1. AsyncLocalStorage frame so any LLM call placed by the handler gets
+     *      attributed to this extension + hook + isUserInitiated=false in
+     *      ext_llm_calls.
+     *   2. Wall-clock timing measurement (only when the sample roll passes).
+     *   3. One fire-and-forget ext_hook_events row per sampled invocation,
+     *      capturing duration_ms + ok + error_code + sample_rate.
+     *
+     * High-frequency hooks (tool_*) are sampled at 10% so the table doesn't
+     * drown in tool-execution rows; the sample_rate column on each row lets
+     * dashboards extrapolate with `count(*) * 1/sample_rate`. Sampling decision
+     * sits inside the AsyncLocalStorage frame so even skipped-emit hooks still
+     * attribute their LLM calls.
+     */
+    private invokeHookHandler;
+    /**
+     * Single chokepoint for slash command dispatch. All modes (interactive /
+     * print / rpc / acp) funnel through agent-session._tryExecuteExtensionCommand,
+     * which calls this method. The wrapper measures wall-clock duration,
+     * captures outcome (ok / error / cancelled), and emits one telemetry row
+     * per invocation. Errors are still routed through emitError() so existing
+     * UI surfaces (toasts, logs) keep working unchanged.
+     *
+     * Returns `{ found: false }` when no extension owns the command, letting
+     * the caller fall through to built-in command handling without emitting a
+     * telemetry row for an unknown command.
+     */
+    invokeCommand(commandName: string, args: string, ctx: ExtensionCommandContext, metadata?: {
+        sessionId?: string | null;
+        runId?: string | null;
+        variant?: string | null;
+    }): Promise<{
+        found: boolean;
+    }>;
     /**
      * Request a graceful shutdown. Called by extension tools and event handlers.
      * The actual shutdown behavior is provided by the mode via bindExtensions().

package/dist/core/extensions/runner.js

@@ -1,4 +1,5 @@
 import { theme } from "../../modes/interactive/theme/theme.js";
+import { classifyArgsSignature, HOOK_SAMPLE_RATES, runWithExtCallerContext, } from "../telemetry/index.js";
 // Keybindings for these actions cannot be overridden by extensions
 const RESERVED_ACTIONS_FOR_EXTENSION_CONFLICTS = [
     "interrupt",
@@ -108,6 +109,7 @@ export class ExtensionRunner {
     shutdownHandler = () => { };
     shortcutDiagnostics = [];
     commandDiagnostics = [];
+    telemetrySink;
     _beforeAgentStartTimeoutMs = 1500;
     get beforeAgentStartTimeoutMs() { return this._beforeAgentStartTimeoutMs ?? 1500; }
     beforeAgentStartTimeoutSentinel = Symbol("before_agent_start_timeout");
@@ -378,6 +380,184 @@ export class ExtensionRunner {
         }
         return undefined;
     }
+    /**
+     * Returns the owning Extension for a given slash command name. Used by the
+     * telemetry middleware to stamp `extension_name` on each ext_command_events
+     * row. Falls back to undefined when no extension claims the command.
+     */
+    findCommandOwner(name) {
+        for (const ext of this.extensions) {
+            if (ext.commands.has(name))
+                return ext;
+        }
+        return undefined;
+    }
+    /**
+     * Derive a short, stable extension name from an Extension record. For
+     * built-ins (extensions/defaults/<name>) and most user extensions
+     * (packages/<name>) the directory basename is the right answer.
+     */
+    deriveExtensionName(ext) {
+        const path = ext.path || ext.resolvedPath || "";
+        const segments = path.replace(/\/+$/, "").split(/[\\/]/);
+        return segments[segments.length - 1] || "unknown";
+    }
+    /**
+     * Attach (or replace) the extension telemetry sink. The runner owns sink
+     * lifecycle from this point — invokeCommand() will fire-and-forget one
+     * `ext_command_events` row per invocation, and writeLlmCallEvent() (called
+     * from extension-core-bindings) writes one `ext_llm_calls` row per
+     * extension-initiated LLM call. Passing the noop sink (the factory's
+     * default when no insforge credentials exist) is the safe way to disable
+     * telemetry without scattering null-checks at the call sites.
+     */
+    setTelemetrySink(sink) {
+        this.telemetrySink = sink;
+    }
+    /**
+     * Passthrough used by core/runtime/extension-core-bindings.ts after each
+     * extension-initiated LLM call. The runner owns the sink; the binding
+     * doesn't import it directly to keep its concerns scoped to LLM plumbing.
+     */
+    writeLlmCallEvent(input) {
+        try {
+            this.telemetrySink?.writeLlmCallEvent(input);
+        }
+        catch {
+            // Telemetry must never destabilize the LLM call path.
+        }
+    }
+    /**
+     * Wrap an extension hook handler invocation in three layers:
+     *
+     *   1. AsyncLocalStorage frame so any LLM call placed by the handler gets
+     *      attributed to this extension + hook + isUserInitiated=false in
+     *      ext_llm_calls.
+     *   2. Wall-clock timing measurement (only when the sample roll passes).
+     *   3. One fire-and-forget ext_hook_events row per sampled invocation,
+     *      capturing duration_ms + ok + error_code + sample_rate.
+     *
+     * High-frequency hooks (tool_*) are sampled at 10% so the table doesn't
+     * drown in tool-execution rows; the sample_rate column on each row lets
+     * dashboards extrapolate with `count(*) * 1/sample_rate`. Sampling decision
+     * sits inside the AsyncLocalStorage frame so even skipped-emit hooks still
+     * attribute their LLM calls.
+     */
+    invokeHookHandler(ext, hookName, fn) {
+        const extensionName = this.deriveExtensionName(ext);
+        const ctx = {
+            extensionName,
+            callerContext: `hook:${hookName}`,
+            isUserInitiated: false,
+        };
+        return runWithExtCallerContext(ctx, async () => {
+            const sampleRate = HOOK_SAMPLE_RATES[hookName] ?? 1.0;
+            if (sampleRate < 1.0 && Math.random() >= sampleRate) {
+                return await fn();
+            }
+            const recordedAt = new Date();
+            const startPerf = performance.now();
+            let ok = true;
+            let errorCode = null;
+            try {
+                return await fn();
+            }
+            catch (err) {
+                ok = false;
+                errorCode = err instanceof Error ? err.constructor.name : "unknown";
+                throw err;
+            }
+            finally {
+                try {
+                    this.telemetrySink?.writeHookEvent({
+                        extensionName,
+                        hookName,
+                        durationMs: Math.round(performance.now() - startPerf),
+                        ok,
+                        errorCode,
+                        sampleRate,
+                        recordedAt,
+                    });
+                }
+                catch {
+                    // Telemetry never destabilizes hook dispatch.
+                }
+            }
+        });
+    }
+    /**
+     * Single chokepoint for slash command dispatch. All modes (interactive /
+     * print / rpc / acp) funnel through agent-session._tryExecuteExtensionCommand,
+     * which calls this method. The wrapper measures wall-clock duration,
+     * captures outcome (ok / error / cancelled), and emits one telemetry row
+     * per invocation. Errors are still routed through emitError() so existing
+     * UI surfaces (toasts, logs) keep working unchanged.
+     *
+     * Returns `{ found: false }` when no extension owns the command, letting
+     * the caller fall through to built-in command handling without emitting a
+     * telemetry row for an unknown command.
+     */
+    async invokeCommand(commandName, args, ctx, metadata) {
+        const command = this.getCommand(commandName);
+        if (!command)
+            return { found: false };
+        const ownerExt = this.findCommandOwner(commandName);
+        const extensionName = ownerExt ? this.deriveExtensionName(ownerExt) : "unknown";
+        const startedAt = new Date();
+        const startPerf = performance.now();
+        let outcome = "ok";
+        let errorCode = null;
+        let thrown;
+        const argsSig = classifyArgsSignature(args);
+        const callerCtx = {
+            extensionName,
+            callerContext: argsSig === "no-args" ? `command:/${commandName}` : `command:/${commandName} ${argsSig}`,
+            isUserInitiated: true,
+            sessionId: metadata?.sessionId ?? null,
+            runId: metadata?.runId ?? null,
+            variant: metadata?.variant ?? null,
+        };
+        try {
+            await runWithExtCallerContext(callerCtx, () => command.handler(args, ctx));
+        }
+        catch (err) {
+            outcome = "error";
+            errorCode = err instanceof Error ? err.constructor.name : "unknown";
+            thrown = err;
+            this.emitError({
+                extensionPath: `command:${commandName}`,
+                event: "command",
+                error: err instanceof Error ? err.message : String(err),
+            });
+        }
+        const durationMs = Math.round(performance.now() - startPerf);
+        const endedAt = new Date();
+        try {
+            this.telemetrySink?.writeCommandEvent({
+                extensionName,
+                commandName,
+                argsSignature: argsSig,
+                argsLength: args.length,
+                outcome,
+                errorCode,
+                durationMs,
+                startedAt,
+                endedAt,
+                sessionId: metadata?.sessionId ?? null,
+                runId: metadata?.runId ?? null,
+                variant: metadata?.variant ?? null,
+            });
+        }
+        catch {
+            // Sink emission must never bring down command dispatch.
+        }
+        // Even though we logged the error to telemetry + emitError, callers
+        // expecting the thrown error (e.g. AgentSession previously re-caught it
+        // silently) won't see it. This matches the original behaviour: the old
+        // _tryExecuteExtensionCommand swallowed the error after emitError too.
+        void thrown;
+        return { found: true };
+    }
     /**
      * Request a graceful shutdown. Called by extension tools and event handlers.
      * The actual shutdown behavior is provided by the mode via bindExtensions().
@@ -444,7 +624,7 @@ export class ExtensionRunner {
                 continue;
             for (const handler of handlers) {
                 try {
-                    const handlerResult = await handler(event, ctx);
+                    const handlerResult = await this.invokeHookHandler(ext, event.type, () => handler(event, ctx));
                     if (this.isSessionBeforeEvent(event) && handlerResult) {
                         result = handlerResult;
                         if (result.cancel) {
@@ -476,7 +656,7 @@ export class ExtensionRunner {
                 continue;
             for (const handler of handlers) {
                 try {
-                    const handlerResult = (await handler(currentEvent, ctx));
+                    const handlerResult = (await this.invokeHookHandler(ext, "tool_result", () => handler(currentEvent, ctx)));
                     if (!handlerResult)
                         continue;
                     if (handlerResult.content !== undefined) {
@@ -521,7 +701,7 @@ export class ExtensionRunner {
             if (!handlers || handlers.length === 0)
                 continue;
             for (const handler of handlers) {
-                const handlerResult = await handler(event, ctx);
+                const handlerResult = await this.invokeHookHandler(ext, "tool_call", () => handler(event, ctx));
                 if (handlerResult) {
                     result = handlerResult;
                     if (result.block) {
@@ -540,7 +720,7 @@ export class ExtensionRunner {
                 continue;
             for (const handler of handlers) {
                 try {
-                    const handlerResult = await handler(event, ctx);
+                    const handlerResult = await this.invokeHookHandler(ext, "user_bash", () => handler(event, ctx));
                     if (handlerResult) {
                         return handlerResult;
                     }
@@ -569,7 +749,7 @@ export class ExtensionRunner {
             for (const handler of handlers) {
                 try {
                     const event = { type: "context", messages: currentMessages };
-                    const handlerResult = await handler(event, ctx);
+                    const handlerResult = await this.invokeHookHandler(ext, "context", () => handler(event, ctx));
                     if (handlerResult && handlerResult.messages) {
                         currentMessages = handlerResult.messages;
                     }
@@ -605,7 +785,7 @@ export class ExtensionRunner {
                         images,
                         systemPrompt: currentSystemPrompt,
                     };
-                    const handlerResult = await this.withTimeout(handler(event, ctx), this.beforeAgentStartTimeoutMs);
+                    const handlerResult = await this.withTimeout(this.invokeHookHandler(ext, "before_agent_start", () => handler(event, ctx)), this.beforeAgentStartTimeoutMs);
                     if (handlerResult === this.beforeAgentStartTimeoutSentinel) {
                         this.reportBeforeAgentStartTimeout(ext.path);
                         continue;
@@ -663,7 +843,7 @@ export class ExtensionRunner {
             for (const handler of handlers) {
                 try {
                     const event = { type: "resources_discover", cwd, reason };
-                    const handlerResult = await handler(event, ctx);
+                    const handlerResult = await this.invokeHookHandler(ext, "resources_discover", () => handler(event, ctx));
                     const result = handlerResult;
                     if (result?.skillPaths?.length) {
                         skillPaths.push(...result.skillPaths.map((path) => ({ path, extensionPath: ext.path })));
@@ -698,7 +878,7 @@ export class ExtensionRunner {
             for (const handler of ext.handlers.get("input") ?? []) {
                 try {
                     const event = { type: "input", text: currentText, images: currentImages, source };
-                    const result = (await handler(event, ctx));
+                    const result = (await this.invokeHookHandler(ext, "input", () => handler(event, ctx)));
                     if (result?.action === "handled")
                         return result;
                     if (result?.action === "transform") {

package/dist/core/extensions/types.d.ts

@@ -685,10 +685,17 @@ export interface MessageRenderOptions {
     expanded: boolean;
 }
 export type MessageRenderer<T = unknown> = (message: CustomMessage<T>, options: MessageRenderOptions, theme: Theme) => Component | undefined;
+export interface ArgumentCompletionContext {
+    commandName: string;
+    argumentText: string;
+    argumentPrefix: string;
+    tokenIndex: number;
+    previousTokens: string[];
+}
 export interface RegisteredCommand {
     name: string;
     description?: string;
-    getArgumentCompletions?: (argumentPrefix: string) => AutocompleteItem[] | null;
+    getArgumentCompletions?: (argumentPrefix: string, context?: ArgumentCompletionContext) => AutocompleteItem[] | null;
     handler: (args: string, ctx: ExtensionCommandContext) => Promise<void>;
 }
 /** Handler function type for events */

package/dist/core/i18n/slash-commands.d.ts

@@ -17,6 +17,7 @@ export declare const slashCommands: {
     };
     settings: string;
     model: string;
+    thinking: string;
     "agent-loop": string;
     "scoped-models": string;
     apikey: string;

package/dist/core/i18n/slash-commands.js

@@ -17,6 +17,7 @@ export const slashCommands = {
     },
     settings: "Open settings menu",
     model: "Select model (opens selector UI)",
+    thinking: "Choose reasoning depth for the current model",
     "agent-loop": "Choose how the agent keeps working through a task",
     "scoped-models": "Choose which models appear in quick switching",
     apikey: "Update API key for current provider",

package/dist/core/i18n/slash-commands.zh.d.ts

@@ -17,6 +17,7 @@ export declare const slashCommands: {
     };
     settings: string;
     model: string;
+    thinking: string;
     "agent-loop": string;
     "scoped-models": string;
     apikey: string;

package/dist/core/i18n/slash-commands.zh.js

@@ -17,6 +17,7 @@ export const slashCommands = {
     },
     settings: "打开设置菜单",
     model: "选择模型（打开选择器界面）",
+    thinking: "选择当前模型的推理深度",
     "agent-loop": "选择 agent 推进任务的方式",
     "scoped-models": "选择快速切换里出现的模型",
     apikey: "更新当前提供商的 API 密钥",

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

@@ -342,6 +342,10 @@ export declare class AgentSession {
     prompt(text: string, options?: PromptOptions): Promise<void>;
     /**
      * Try to execute an extension command. Returns true if command was found and executed.
+     *
+     * Delegates to ExtensionRunner.invokeCommand() so command dispatch, error
+     * routing (emitError), and telemetry (ext_command_events) all happen in one
+     * place rather than being scattered across modes.
      */
     private _tryExecuteExtensionCommand;
     /**
@@ -516,6 +520,7 @@ export declare class AgentSession {
      * @param skipAbortedCheck If false, include aborted messages (for pre-prompt check). Default: true
      */
     private _checkCompaction;
+    private _recoverModelErrorInLoop;
     /**
      * Internal: Run auto-compaction with events.
      */