@pencil-agent/nano-pencil 1.14.2 → 1.14.4

package/dist/core/telemetry/ext-events.js

@@ -0,0 +1,189 @@
+/**
+ * [WHO]: Provides ExtensionTelemetrySink interface, CommandEventInput, classifyArgsSignature(), createExtensionTelemetrySink() factory (insforge-backed or noop)
+ * [FROM]: Depends on ./insforge-base (InsforgeHttpClient), ./batching-dispatcher (BatchingDispatcher), ./credentials (loadInsforgeCredentials), ./build-meta (loadBuildMeta), ./types (DiagnosticHandler)
+ * [TO]: Consumed by core/extensions/runner.ts (writes one row per /command invocation); future P2/P3 commits add LLM-call + hook-event sinks alongside this one
+ * [HERE]: core/telemetry/ext-events.ts - P1 writer for ext_command_events table; one row per extension command invocation, batched + fire-and-forget, no-op when no insforge credentials configured
+ */
+import { BatchingDispatcher } from "./batching-dispatcher.js";
+import { loadBuildMeta } from "./build-meta.js";
+import { loadInsforgeCredentials } from "./credentials.js";
+import { InsforgeHttpClient } from "./insforge-base.js";
+const BUILD_META = loadBuildMeta();
+const TELEMETRY_SOURCE = "ext.telemetry";
+const EXT_COMMAND_EVENTS_TABLE = "ext_command_events";
+const EXT_LLM_CALLS_TABLE = "ext_llm_calls";
+const EXT_HOOK_EVENTS_TABLE = "ext_hook_events";
+/**
+ * Sample rates per hook name. Tool-related hooks fire many times per turn
+ * (one pair per tool call), so we record only 10% to avoid drowning the
+ * table; the sample_rate column lets dashboards extrapolate counts with
+ * `count(*) * (1.0 / avg(sample_rate))`. Everything else is rare enough
+ * to record in full.
+ */
+export const HOOK_SAMPLE_RATES = Object.freeze({
+    tool_call: 0.1,
+    tool_result: 0.1,
+    tool_execution_start: 0.1,
+    tool_execution_end: 0.1,
+});
+class NoopExtensionTelemetrySink {
+    writeCommandEvent() {
+        // no-op
+    }
+    writeLlmCallEvent() {
+        // no-op
+    }
+    writeHookEvent() {
+        // no-op
+    }
+    async close() {
+        // no-op
+    }
+}
+class InsforgeExtensionTelemetrySink {
+    http;
+    dispatcher;
+    constructor(opts) {
+        this.http = new InsforgeHttpClient({
+            endpoint: opts.endpoint,
+            apiKey: opts.apiKey,
+            anonKey: opts.anonKey,
+            apiKeyHeader: opts.apiKeyHeader,
+            extraHeaders: opts.extraHeaders,
+            allowSelfSigned: opts.allowSelfSigned,
+            source: TELEMETRY_SOURCE,
+            onDiagnostic: opts.onDiagnostic,
+        });
+        this.dispatcher = new BatchingDispatcher({
+            handler: (event) => this.postEvent(event),
+            intervalMs: opts.batchIntervalMs ?? 2000,
+            source: TELEMETRY_SOURCE,
+            onDiagnostic: opts.onDiagnostic,
+        });
+    }
+    writeCommandEvent(input) {
+        this.dispatcher.enqueue({ type: "command", payload: input });
+    }
+    writeLlmCallEvent(input) {
+        this.dispatcher.enqueue({ type: "llm_call", payload: input });
+    }
+    writeHookEvent(input) {
+        this.dispatcher.enqueue({ type: "hook", payload: input });
+    }
+    async close() {
+        await this.dispatcher.close();
+    }
+    async postEvent(event) {
+        if (event.type === "command") {
+            await this.postCommandEvent(event.payload);
+        }
+        else if (event.type === "llm_call") {
+            await this.postLlmCallEvent(event.payload);
+        }
+        else {
+            await this.postHookEvent(event.payload);
+        }
+    }
+    async postCommandEvent(input) {
+        const row = {
+            run_id: input.runId ?? null,
+            session_id: input.sessionId ?? null,
+            extension_name: input.extensionName,
+            command_name: input.commandName,
+            args_signature: input.argsSignature,
+            args_length: input.argsLength,
+            outcome: input.outcome,
+            error_code: input.errorCode ?? null,
+            duration_ms: input.durationMs,
+            details: input.details ?? null,
+            pencil_version: BUILD_META.version,
+            commit_hash: BUILD_META.commitHash ?? null,
+            variant: input.variant ?? null,
+            started_at: input.startedAt.toISOString(),
+            ended_at: input.endedAt.toISOString(),
+        };
+        await this.http.postJson(`${this.http.base}/api/database/records/${EXT_COMMAND_EVENTS_TABLE}`, [row]);
+    }
+    async postLlmCallEvent(input) {
+        const row = {
+            run_id: input.runId ?? null,
+            session_id: input.sessionId ?? null,
+            command_event_id: input.commandEventId ?? null,
+            extension_name: input.extensionName,
+            caller_context: input.callerContext,
+            is_user_initiated: input.isUserInitiated,
+            model_id: input.modelId ?? null,
+            tokens_in: input.tokensIn ?? null,
+            tokens_out: input.tokensOut ?? null,
+            cost_total: input.costTotal ?? null,
+            duration_ms: input.durationMs,
+            ok: input.ok,
+            error_code: input.errorCode ?? null,
+            pencil_version: BUILD_META.version,
+            commit_hash: BUILD_META.commitHash ?? null,
+            variant: input.variant ?? null,
+            started_at: input.startedAt.toISOString(),
+            ended_at: input.endedAt.toISOString(),
+        };
+        await this.http.postJson(`${this.http.base}/api/database/records/${EXT_LLM_CALLS_TABLE}`, [row]);
+    }
+    async postHookEvent(input) {
+        const row = {
+            run_id: input.runId ?? null,
+            session_id: input.sessionId ?? null,
+            extension_name: input.extensionName,
+            hook_name: input.hookName,
+            duration_ms: input.durationMs,
+            ok: input.ok,
+            error_code: input.errorCode ?? null,
+            sample_rate: input.sampleRate,
+            pencil_version: BUILD_META.version,
+            variant: input.variant ?? null,
+            recorded_at: input.recordedAt.toISOString(),
+        };
+        await this.http.postJson(`${this.http.base}/api/database/records/${EXT_HOOK_EVENTS_TABLE}`, [row]);
+    }
+}
+/**
+ * Build a telemetry sink. Returns a noop sink — silently dropping every event —
+ * when insforge credentials are missing or disabled. Callers can therefore wire
+ * the sink unconditionally; users without credentials pay zero cost.
+ */
+export function createExtensionTelemetrySink(options) {
+    const creds = loadInsforgeCredentials(options.workspaceRoot, TELEMETRY_SOURCE, options.onDiagnostic);
+    const endpoint = creds?.endpoint ?? creds?.insforge_url;
+    if (!endpoint || !creds?.api_key || creds.enabled === false) {
+        return new NoopExtensionTelemetrySink();
+    }
+    return new InsforgeExtensionTelemetrySink({
+        endpoint,
+        apiKey: creds.api_key,
+        anonKey: creds.anon_key,
+        apiKeyHeader: creds.api_key_header,
+        extraHeaders: creds.headers,
+        allowSelfSigned: creds.allow_self_signed,
+        batchIntervalMs: options.batchIntervalMs,
+        onDiagnostic: options.onDiagnostic,
+    });
+}
+/**
+ * Classify arg text into a small bounded set of signatures so dashboards can
+ * group invocations without ingesting user-supplied text. Privacy posture:
+ *
+ * - "no-args"     — empty or whitespace-only args
+ * - "--<flag>"    — args start with a `--flag` token; we record the flag name only
+ *                   (enum-like, low cardinality, no PII)
+ * - "with-args"   — any other non-empty args; original text is never recorded
+ *
+ * Anything else interesting (length, etc.) lives on its own typed column so we
+ * never need free-form arg storage.
+ */
+export function classifyArgsSignature(args) {
+    const trimmed = args.trim();
+    if (!trimmed)
+        return "no-args";
+    const flagMatch = trimmed.match(/^(--[a-z0-9-]+)/i);
+    if (flagMatch)
+        return flagMatch[1].toLowerCase();
+    return "with-args";
+}

package/dist/core/telemetry/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * [WHO]: Re-exports the telemetry layer's public surface — types, credential loader, InsforgeHttpClient, BatchingDispatcher
+ * [FROM]: Depends on ./types, ./credentials, ./insforge-base, ./batching-dispatcher
+ * [TO]: Consumed by extensions/defaults/sal/* and (future) extensions/<ext>/telemetry sinks via `import { ... } from "../../../core/telemetry/index.js"`
+ * [HERE]: core/telemetry/index.ts - barrel for the telemetry module; the only entry point external callers should import from
+ */
+export type { DiagnosticHandler, InsforgeHttpResult, PostJsonOptions, TelemetryDiagnostic } from "./types.js";
+export { type InsforgeCredentialsBase, loadInsforgeCredentials } from "./credentials.js";
+export { type InsforgeHttpClientOptions, InsforgeHttpClient, parsePostgrestErrorCode, safeHost, } from "./insforge-base.js";
+export { type BatchingDispatcherOptions, BatchingDispatcher } from "./batching-dispatcher.js";
+export { type BuildMeta, loadBuildMeta } from "./build-meta.js";
+export { type CommandEventInput, type CommandOutcome, type CreateExtensionTelemetrySinkOptions, type ExtensionTelemetrySink, type HookEventInput, type LlmCallEventInput, classifyArgsSignature, createExtensionTelemetrySink, HOOK_SAMPLE_RATES, } from "./ext-events.js";
+export { type ExtCallerContext, getExtCallerContext, runWithExtCallerContext } from "./caller-context.js";

package/dist/core/telemetry/index.js

@@ -0,0 +1,6 @@
+export { loadInsforgeCredentials } from "./credentials.js";
+export { InsforgeHttpClient, parsePostgrestErrorCode, safeHost, } from "./insforge-base.js";
+export { BatchingDispatcher } from "./batching-dispatcher.js";
+export { loadBuildMeta } from "./build-meta.js";
+export { classifyArgsSignature, createExtensionTelemetrySink, HOOK_SAMPLE_RATES, } from "./ext-events.js";
+export { getExtCallerContext, runWithExtCallerContext } from "./caller-context.js";

package/dist/core/telemetry/insforge-base.d.ts

@@ -0,0 +1,37 @@
+import type { DiagnosticHandler, InsforgeHttpResult, PostJsonOptions } from "./types.js";
+export interface InsforgeHttpClientOptions {
+    endpoint: string;
+    apiKey?: string;
+    anonKey?: string;
+    apiKeyHeader?: string;
+    extraHeaders?: Record<string, string>;
+    allowSelfSigned?: boolean;
+    timeoutMs?: number;
+    /** Used as diagnostic source + fingerprint scope. e.g. "sal.eval", "ext.telemetry". */
+    source: string;
+    onDiagnostic?: DiagnosticHandler;
+}
+/**
+ * Thin PostgREST HTTP client. Strictly transport: no routing, no batching, no
+ * upsert semantics — those belong to the consumer (e.g. SAL's InsForgeEvalSink).
+ *
+ * Sinks construct one of these per options.endpoint, then call postJson /
+ * patchJson with the full record URL. Diagnostics emit through
+ * options.onDiagnostic with `source:category:fingerprint` keying so multiple
+ * sinks can share an emit channel without collisions.
+ */
+export declare class InsforgeHttpClient {
+    readonly base: string;
+    private headers;
+    private allowSelfSigned;
+    private timeoutMs;
+    private source;
+    private onDiagnostic?;
+    constructor(options: InsforgeHttpClientOptions);
+    postJson(url: string, body: unknown, extra?: PostJsonOptions): Promise<InsforgeHttpResult>;
+    patchJson(url: string, body: unknown): Promise<InsforgeHttpResult>;
+    private httpJson;
+    private reportDiagnostic;
+}
+export declare function parsePostgrestErrorCode(rawBody: string): string | undefined;
+export declare function safeHost(value: string): string | undefined;

package/dist/core/telemetry/insforge-base.js

@@ -0,0 +1,160 @@
+/**
+ * [WHO]: Provides InsforgeHttpClient class + parsePostgrestErrorCode/safeHost helpers — generic insforge PostgREST transport
+ * [FROM]: Depends on node:http (httpRequest), node:https (request), node:url (URL); ./types for DiagnosticHandler / InsforgeHttpResult / PostJsonOptions
+ * [TO]: Consumed by extensions/defaults/sal/eval/insforge-sink.ts (SAL-specific routing); future extensions/<ext>/telemetry sinks reuse the same client
+ * [HERE]: core/telemetry/insforge-base.ts - factored out of SAL's eval/insforge-sink.ts; HTTP/transport-only, no event semantics, no batching (those live in batching-dispatcher.ts)
+ */
+import { request as httpRequest } from "node:http";
+import { request as httpsRequest } from "node:https";
+import { URL } from "node:url";
+import { isDevRuntime } from "../../utils/diagnostics.js";
+const DEFAULT_TIMEOUT_MS = 5000;
+/**
+ * Thin PostgREST HTTP client. Strictly transport: no routing, no batching, no
+ * upsert semantics — those belong to the consumer (e.g. SAL's InsForgeEvalSink).
+ *
+ * Sinks construct one of these per options.endpoint, then call postJson /
+ * patchJson with the full record URL. Diagnostics emit through
+ * options.onDiagnostic with `source:category:fingerprint` keying so multiple
+ * sinks can share an emit channel without collisions.
+ */
+export class InsforgeHttpClient {
+    base;
+    headers;
+    allowSelfSigned;
+    timeoutMs;
+    source;
+    onDiagnostic;
+    constructor(options) {
+        this.base = options.endpoint.replace(/\/+$/, "");
+        this.allowSelfSigned = options.allowSelfSigned ?? false;
+        this.timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+        this.source = options.source;
+        this.onDiagnostic = options.onDiagnostic;
+        if (this.allowSelfSigned && isDevRuntime()) {
+            console.warn(`[${this.source}] TLS certificate verification disabled (allowSelfSigned=true)`);
+        }
+        const h = {
+            "Content-Type": "application/json",
+            ...(options.extraHeaders ?? {}),
+        };
+        if (options.anonKey) {
+            h["apikey"] = options.anonKey;
+            h["Authorization"] = `Bearer ${options.anonKey}`;
+        }
+        if (options.apiKey) {
+            h[options.apiKeyHeader ?? "x-api-key"] = options.apiKey;
+            if (!options.anonKey) {
+                h["Authorization"] = `Bearer ${options.apiKey}`;
+            }
+        }
+        this.headers = h;
+    }
+    postJson(url, body, extra) {
+        const extraHeaders = {};
+        if (extra?.prefer)
+            extraHeaders["Prefer"] = extra.prefer;
+        return this.httpJson("POST", url, body, extraHeaders, extra?.quietErrorCodes);
+    }
+    patchJson(url, body) {
+        return this.httpJson("PATCH", url, body, {});
+    }
+    httpJson(method, url, body, extraHeaders, quietErrorCodes = []) {
+        return new Promise((resolve) => {
+            const payload = JSON.stringify(body);
+            let parsed;
+            try {
+                parsed = new URL(url);
+            }
+            catch {
+                this.reportDiagnostic("config", "Insforge endpoint URL is invalid.", { url }, "invalid-url");
+                resolve({ ok: false });
+                return;
+            }
+            const isHttps = parsed.protocol === "https:";
+            const requestFn = isHttps ? httpsRequest : httpRequest;
+            const port = parsed.port ? Number(parsed.port) : isHttps ? 443 : 80;
+            const req = requestFn({
+                hostname: parsed.hostname,
+                port,
+                path: parsed.pathname + parsed.search,
+                method,
+                headers: {
+                    ...this.headers,
+                    ...extraHeaders,
+                    "Content-Length": Buffer.byteLength(payload),
+                },
+                timeout: this.timeoutMs,
+                ...(isHttps && this.allowSelfSigned ? { rejectUnauthorized: false } : {}),
+            }, (res) => {
+                let rawBody = "";
+                res.setEncoding("utf-8");
+                res.on("data", (chunk) => {
+                    rawBody += chunk;
+                });
+                res.on("end", () => {
+                    const ok = res.statusCode !== undefined && res.statusCode < 300;
+                    const errorCode = parsePostgrestErrorCode(rawBody);
+                    if (!ok && !quietErrorCodes.includes(errorCode ?? "")) {
+                        this.reportDiagnostic(errorCode === "PGRST204" ? "schema" : "network", `Insforge upload failed with HTTP ${res.statusCode}.`, {
+                            method,
+                            path: parsed.pathname,
+                            statusCode: res.statusCode,
+                            body: rawBody.slice(0, 300),
+                            errorCode,
+                        }, `http-${res.statusCode ?? "unknown"}-${errorCode ?? "none"}`);
+                    }
+                    resolve({ ok, statusCode: res.statusCode, body: rawBody, errorCode });
+                });
+            });
+            req.on("error", (err) => {
+                this.reportDiagnostic("network", "Insforge upload is failing due to a network connection error.", { host: parsed.hostname, error: err.message }, "network-error");
+                if (isDevRuntime()) {
+                    console.error(`[${this.source}] network error → ${parsed.hostname}: ${err.message}`);
+                }
+                resolve({ ok: false });
+            });
+            req.on("timeout", () => {
+                this.reportDiagnostic("network", "Insforge upload timed out.", { method, path: parsed.pathname, host: parsed.hostname }, "timeout");
+                if (isDevRuntime()) {
+                    console.error(`[${this.source}] timeout ${method} ${parsed.pathname}`);
+                }
+                req.destroy();
+                resolve({ ok: false });
+            });
+            req.write(payload);
+            req.end();
+        });
+    }
+    reportDiagnostic(category, message, detail, fingerprintSuffix) {
+        this.onDiagnostic?.({
+            source: this.source,
+            severity: category === "config" ? "warning" : "error",
+            category,
+            message,
+            detail,
+            fingerprint: `${this.source}:${category}:${fingerprintSuffix}`,
+            context: {
+                adapter: "insforge",
+                endpoint_host: safeHost(this.base),
+            },
+        });
+    }
+}
+export function parsePostgrestErrorCode(rawBody) {
+    try {
+        const parsed = JSON.parse(rawBody);
+        return typeof parsed?.code === "string" ? parsed.code : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+export function safeHost(value) {
+    try {
+        return new URL(value).hostname;
+    }
+    catch {
+        return undefined;
+    }
+}

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

@@ -0,0 +1,33 @@
+/**
+ * [WHO]: Provides TelemetryDiagnostic event shape, DiagnosticHandler callback, InsforgeHttpResult, PostJsonOptions — shared types for all telemetry sinks
+ * [FROM]: No internal deps; only TypeScript-level type primitives
+ * [TO]: Consumed by core/telemetry/credentials.ts, insforge-base.ts, batching-dispatcher.ts; mirrored by sinks (SAL eval, future extension telemetry)
+ * [HERE]: core/telemetry/types.ts - foundational type surface for the telemetry layer; identical diagnostic shape to SAL's onDiagnostic so SAL can adopt without callsite churn
+ */
+/**
+ * Diagnostic event emitted by any telemetry component. The shape is intentionally
+ * identical to SAL's eval onDiagnostic signature so SAL adopts the base layer
+ * without changing any of its existing diagnostic handlers.
+ */
+export interface TelemetryDiagnostic {
+    source: string;
+    severity: "debug" | "info" | "warning" | "error";
+    category: "network" | "fallback" | "persistence" | "config" | "extension_timeout" | "schema" | "unknown";
+    message: string;
+    detail?: unknown;
+    fingerprint?: string;
+    context?: Record<string, unknown>;
+}
+export type DiagnosticHandler = (event: TelemetryDiagnostic) => void;
+export interface InsforgeHttpResult {
+    ok: boolean;
+    statusCode?: number;
+    body?: string;
+    errorCode?: string;
+}
+export interface PostJsonOptions {
+    /** PostgREST Prefer header. e.g. "resolution=merge-duplicates". */
+    prefer?: string;
+    /** Error codes (e.g. "PGRST204") to suppress from onDiagnostic. */
+    quietErrorCodes?: string[];
+}

package/dist/core/telemetry/types.js

@@ -0,0 +1,7 @@
+/**
+ * [WHO]: Provides TelemetryDiagnostic event shape, DiagnosticHandler callback, InsforgeHttpResult, PostJsonOptions — shared types for all telemetry sinks
+ * [FROM]: No internal deps; only TypeScript-level type primitives
+ * [TO]: Consumed by core/telemetry/credentials.ts, insforge-base.ts, batching-dispatcher.ts; mirrored by sinks (SAL eval, future extension telemetry)
+ * [HERE]: core/telemetry/types.ts - foundational type surface for the telemetry layer; identical diagnostic shape to SAL's onDiagnostic so SAL can adopt without callsite churn
+ */
+export {};

package/dist/extensions/defaults/browser/index.js

@@ -18,6 +18,14 @@ const HARNESS_SRC_PATH = join(__dirname, "src");
 const INTERACTION_SKILLS_PATH = join(__dirname, "interaction-skills");
 const WORKSPACE_TEMPLATE_PATH = join(__dirname, "agent-workspace");
 const DEFAULT_TIMEOUT_SECONDS = 120;
+const BROWSER_COMMAND_COMPLETIONS = [
+    { value: "install", label: "install", description: "Install Browser Harness Python dependencies" },
+    { value: "status", label: "status", description: "Run doctor diagnostics" },
+    { value: "setup", label: "setup", description: "Attach to the running browser" },
+    { value: "reload", label: "reload", description: "Restart the Browser Harness daemon" },
+    { value: "workspace", label: "workspace", description: "Show the helper workspace path" },
+    { value: "help", label: "help", description: "Show Browser Harness commands" },
+];
 const BrowserRunInputSchema = Type.Object({
     code: Type.String({
         description: "Python code to execute with Browser Harness helpers pre-imported. Use new_tab(url), wait_for_load(), page_info(), capture_screenshot(), click_at_xy(), js(), cdp(), etc.",
@@ -328,12 +336,12 @@ export default function browserExtension(api) {
         ensureBrowserWorkspace();
     });
     api.registerCommand("browser", {
-        description: "Browser Harness setup, status, reload, and workspace information",
-        getArgumentCompletions: (argumentPrefix) => {
-            const prefix = argumentPrefix.trim();
-            const values = ["install", "status", "setup", "reload", "workspace", "help"]
-                .filter((value) => value.startsWith(prefix))
-                .map((value) => ({ value, label: value }));
+        description: "Set up or inspect browser automation tools",
+        getArgumentCompletions: (argumentPrefix, context) => {
+            if (context && context.tokenIndex > 0)
+                return null;
+            const prefix = argumentPrefix.trim().toLowerCase();
+            const values = BROWSER_COMMAND_COMPLETIONS.filter((item) => item.value.startsWith(prefix));
             return values.length > 0 ? values : null;
         },
         handler: async (args, ctx) => {

package/dist/extensions/defaults/btw/index.js

@@ -14,7 +14,7 @@ Rules:
 - Do NOT use any tools
 - Do NOT say "I cannot" or explain limitations
 - If you don't know, say so briefly
-- Keep responses short (1-3 sentences unless detail is critical`;
+- Keep responses short (1-3 sentences unless detail is critical).`;
 const MAX_TURN_CHARS = 500;
 function extractText(content) {
     if (typeof content === "string")
@@ -111,7 +111,7 @@ export default async function btwExtension(api) {
     });
     // Register /btw command
     api.registerCommand("btw", {
-        description: "Ask a quick question without interrupting the current task",
+        description: "Ask a quick side question while the main task keeps its place",
         handler: (args, ctx) => handleBtwCommand(args, ctx, api),
     });
 }

package/dist/extensions/defaults/debug/index.js

@@ -5,7 +5,7 @@
  * [HERE]: extensions/defaults/debug/index.ts - system diagnostics with three-layer analysis through full agent loop
  */
 import { Box, Container, Spacer, Text } from "@pencil-agent/tui";
-import { collectSystemInfo, collectModelInfo, collectSessionInfo, collectConfigInfo, collectGitInfo, collectAgentState, sanitizeForLLM, formatDiagnosticData, } from "./collectors.js";
+import { collectSystemInfo, collectModelInfo, collectSessionInfo, collectConfigInfo, collectGitInfo, collectAgentState, collectPreferencesInfo, sanitizeForLLM, formatDiagnosticData, } from "./collectors.js";
 const DEBUG_MESSAGE_TYPE = "debug";
 const DEBUG_PROMPT_PREFIX = "[DEBUG:";
 const DEBUG_TAG = "[DEBUG]";
@@ -47,6 +47,16 @@ let pendingDiagnosticPrompt;
 function isDebugPrompt(text) {
     return text.startsWith(DEBUG_PROMPT_PREFIX);
 }
+const DEBUG_COMMAND_COMPLETIONS = [
+    { value: "env", label: "env", description: "Show terminal and system details" },
+    { value: "session", label: "session", description: "Show current conversation state" },
+    { value: "model", label: "model", description: "Show active model and provider details" },
+    { value: "preferences", label: "preferences", description: "Show saved preferences" },
+];
+const LOCALE_COMMAND_COMPLETIONS = [
+    { value: "zh", label: "zh", description: "Use Chinese for future replies" },
+    { value: "en", label: "en", description: "Use English for future replies" },
+];
 function parseDebugArgs(args) {
     const trimmed = args.trim().toLowerCase();
     if (trimmed === "env")
@@ -55,6 +65,8 @@ function parseDebugArgs(args) {
         return { subcommand: "session" };
     if (trimmed === "model")
         return { subcommand: "model" };
+    if (trimmed === "preferences")
+        return { subcommand: "preferences" };
     return { subcommand: "full", issueDescription: args.trim() || undefined };
 }
 // ============================================================================
@@ -132,6 +144,15 @@ async function handleQuickSub(subcommand, ctx, api) {
                 : `> Collection failed: ${info.error}`;
             break;
         }
+        case "preferences": {
+            const info = await collectPreferencesInfo(ctx);
+            result = info.data
+                ? `| Preferences | |\n|---|---|\n${Object.entries(info.data)
+                    .map(([k, v]) => `| ${k} | ${typeof v === "string" ? v : JSON.stringify(v)} |`)
+                    .join("\n")}`
+                : `> Collection failed: ${info.error}`;
+            break;
+        }
     }
     api.sendMessage({
         customType: DEBUG_MESSAGE_TYPE,
@@ -170,7 +191,7 @@ export default async function debugExtension(api) {
         return container;
     });
     api.on("before_agent_start", (event) => {
-        if (!isDebugPrompt(event.prompt))
+        if (!isDebugPrompt(event.prompt) || event.prompt !== pendingDiagnosticPrompt)
             return;
         return { appendSystemPrompt: DEBUG_SYSTEM_PROMPT };
     });
@@ -180,12 +201,26 @@ export default async function debugExtension(api) {
         }
     });
     api.registerCommand("debug", {
-        description: "Run system diagnostics (/debug [env|session|model|preferences|<issue>])",
+        description: "Check NanoPencil health or investigate an issue. Usage: /debug [env|session|model|preferences|<issue>]",
+        getArgumentCompletions: (argumentPrefix, context) => {
+            if (context && context.tokenIndex > 0)
+                return null;
+            const prefix = argumentPrefix.trim().toLowerCase();
+            const values = DEBUG_COMMAND_COMPLETIONS.filter((value) => value.value.startsWith(prefix));
+            return values.length > 0 ? values : null;
+        },
         handler: (args, ctx) => handleDebugCommand(args, ctx, api),
     });
     // Register /set-locale command
     api.registerCommand("set-locale", {
         description: "Set language preference (/set-locale zh|en)",
+        getArgumentCompletions: (argumentPrefix, context) => {
+            if (context && context.tokenIndex > 0)
+                return null;
+            const prefix = argumentPrefix.trim().toLowerCase();
+            const values = LOCALE_COMMAND_COMPLETIONS.filter((value) => value.value.startsWith(prefix));
+            return values.length > 0 ? values : null;
+        },
         handler: async (args, ctx) => {
             const trimmed = args.trim().toLowerCase();
             if (trimmed !== "zh" && trimmed !== "en") {

package/dist/extensions/defaults/diagnostics/index.js

@@ -10,6 +10,17 @@ import { coerceDiagnosticEvent, DiagnosticBuffer } from "./diagnostic-buffer.js"
 import { reportDiagnostics } from "./reporter.js";
 import { DIAGNOSTIC_EVENT_CHANNEL } from "./types.js";
 const MESSAGE_TYPE = "diagnostics";
+const REPORT_ISSUE_COMPLETIONS = [
+    { value: "last", label: "last", description: "Report the latest diagnostic" },
+    { value: "all", label: "all", description: "Report all diagnostics from this session" },
+];
+function getReportIssueArgumentCompletions(argumentPrefix, context) {
+    if (context && context.tokenIndex > 0)
+        return null;
+    const prefix = argumentPrefix.trim().toLowerCase();
+    const values = REPORT_ISSUE_COMPLETIONS.filter((item) => item.value.startsWith(prefix));
+    return values.length > 0 ? values.map((item) => ({ ...item })) : null;
+}
 export default async function diagnosticsExtension(api) {
     const buffer = new DiagnosticBuffer();
     api.registerMessageRenderer(MESSAGE_TYPE, (message, _options, theme) => {
@@ -49,6 +60,7 @@ export default async function diagnosticsExtension(api) {
     });
     api.registerCommand("report-issue", {
         description: "Report recent diagnostics (/report-issue [last|all|note])",
+        getArgumentCompletions: getReportIssueArgumentCompletions,
         handler: (args, ctx) => handleReportIssue(args, ctx, buffer),
     });
 }

package/dist/extensions/defaults/grub/grub-parser.d.ts

@@ -1,10 +1,24 @@
 /**
- * [WHO]: parseGrubCommand, buildGrubHelp
+ * [WHO]: parseGrubCommand, buildGrubHelp, getGrubArgumentCompletions
  * [FROM]: Depends on ./grub-types
  * [TO]: Consumed by extension entry point (./index.ts)
  * [HERE]: extensions/defaults/grub/grub-parser.ts - /grub command parser with resume/status --json/--max-iter/--max-fail flags
  */
 import type { ParsedGrubCommand } from "./grub-types.js";
 import { type GrubLocale } from "./grub-i18n.js";
+type GrubArgumentCompletionContext = {
+    commandName: string;
+    argumentText: string;
+    argumentPrefix: string;
+    tokenIndex: number;
+    previousTokens: string[];
+};
+type GrubCompletionItem = {
+    value: string;
+    label: string;
+    description: string;
+};
+export declare function getGrubArgumentCompletions(argumentPrefix: string, context?: GrubArgumentCompletionContext): GrubCompletionItem[] | null;
 export declare function parseGrubCommand(input: string): ParsedGrubCommand;
 export declare function buildGrubHelp(reason?: string, locale?: GrubLocale): string;
+export {};