@pencil-agent/nano-pencil 1.14.2 → 1.14.4

package/dist/core/slash-commands.js

@@ -1,40 +1,89 @@
 export const BUILTIN_SLASH_COMMANDS = [
-    { name: "settings", descriptionKey: "slash.settings" },
-    { name: "model", descriptionKey: "slash.model" },
-    { name: "agent-loop", descriptionKey: "slash.agent-loop" },
-    { name: "scoped-models", descriptionKey: "slash.scoped-models" },
-    { name: "apikey", descriptionKey: "slash.apikey" },
-    { name: "mcp", descriptionKey: "slash.mcp" },
-    { name: "soul", descriptionKey: "slash.soul" },
-    { name: "persona", descriptionKey: "slash.persona" },
-    { name: "memory", descriptionKey: "slash.memory" },
-    { name: "dream", descriptionKey: "slash.dream" },
-    { name: "export", descriptionKey: "slash.export" },
-    { name: "share", descriptionKey: "slash.share" },
-    { name: "copy", descriptionKey: "slash.copy" },
-    { name: "name", descriptionKey: "slash.name" },
-    { name: "session", descriptionKey: "slash.session" },
-    { name: "status", descriptionKey: "slash.status" },
-    { name: "usage", descriptionKey: "slash.usage" },
-    { name: "changelog", descriptionKey: "slash.changelog" },
-    { name: "hotkeys", descriptionKey: "slash.hotkeys" },
-    { name: "fork", descriptionKey: "slash.fork" },
-    { name: "tree", descriptionKey: "slash.tree" },
-    { name: "login", descriptionKey: "slash.login" },
-    { name: "logout", descriptionKey: "slash.logout" },
-    { name: "new", descriptionKey: "slash.new" },
-    { name: "update", descriptionKey: "slash.update" },
-    { name: "reinstall", descriptionKey: "slash.reinstall" },
-    { name: "compact", descriptionKey: "slash.compact" },
-    { name: "resume", descriptionKey: "slash.resume" },
-    { name: "reload", descriptionKey: "slash.reload" },
-    { name: "link-world", descriptionKey: "slash.link-world" },
-    { name: "language", descriptionKey: "slash.language" },
-    { name: "quit", descriptionKey: "slash.quit" },
+    { name: "settings", descriptionKey: "slash.settings", category: "core" },
+    { name: "model", descriptionKey: "slash.model", category: "model" },
+    { name: "thinking", descriptionKey: "slash.thinking", category: "model" },
+    { name: "agent-loop", descriptionKey: "slash.agent-loop", category: "model" },
+    { name: "scoped-models", descriptionKey: "slash.scoped-models", category: "model" },
+    { name: "apikey", descriptionKey: "slash.apikey", category: "model" },
+    { name: "mcp", descriptionKey: "slash.mcp", category: "tools" },
+    { name: "soul", descriptionKey: "slash.soul", category: "memory" },
+    { name: "persona", descriptionKey: "slash.persona", category: "core" },
+    { name: "memory", descriptionKey: "slash.memory", category: "memory" },
+    { name: "dream", descriptionKey: "slash.dream", category: "memory", implementation: "extension" },
+    { name: "export", descriptionKey: "slash.export", category: "tools" },
+    { name: "share", descriptionKey: "slash.share", category: "tools" },
+    { name: "copy", descriptionKey: "slash.copy", category: "core" },
+    { name: "name", descriptionKey: "slash.name", category: "session" },
+    { name: "session", descriptionKey: "slash.session", category: "session" },
+    { name: "status", descriptionKey: "slash.status", category: "core" },
+    { name: "usage", descriptionKey: "slash.usage", category: "core" },
+    { name: "changelog", descriptionKey: "slash.changelog", category: "core" },
+    { name: "hotkeys", descriptionKey: "slash.hotkeys", category: "core" },
+    { name: "resources", descriptionKey: "slash.resources", category: "core" },
+    { name: "fork", descriptionKey: "slash.fork", category: "session" },
+    { name: "tree", descriptionKey: "slash.tree", category: "session" },
+    { name: "login", descriptionKey: "slash.login", category: "model" },
+    { name: "logout", descriptionKey: "slash.logout", category: "model" },
+    { name: "new", descriptionKey: "slash.new", category: "session" },
+    { name: "update", descriptionKey: "slash.update", category: "admin" },
+    { name: "reinstall", descriptionKey: "slash.reinstall", category: "admin" },
+    { name: "compact", descriptionKey: "slash.compact", category: "session" },
+    { name: "resume", descriptionKey: "slash.resume", category: "session" },
+    { name: "reload", descriptionKey: "slash.reload", category: "admin" },
+    { name: "link-world", descriptionKey: "slash.link-world", category: "tools", implementation: "extension" },
+    { name: "language", descriptionKey: "slash.language", category: "core" },
+    { name: "quit", descriptionKey: "slash.quit", category: "core" },
 ];
+export function getExtensionBackedBuiltinCommandNames() {
+    return new Set(BUILTIN_SLASH_COMMANDS.filter((command) => command.implementation === "extension").map((command) => command.name));
+}
+export function inferSlashCommandCategory(name, source) {
+    if (source === "prompt")
+        return "workflow";
+    if (source === "skill")
+        return "tools";
+    if (name === "dream" || name === "memory" || name.startsWith("mem-"))
+        return "memory";
+    if (name === "team" || name.startsWith("team:") || name === "subagent" || name.startsWith("subagent:"))
+        return "agents";
+    if (name === "grub" ||
+        name === "loop" ||
+        name === "plan" ||
+        name.startsWith("plan:") ||
+        name === "recap" ||
+        name === "btw" ||
+        name === "interview" ||
+        name === "grill-me" ||
+        name === "simplify") {
+        return "workflow";
+    }
+    if (name === "browser" || name === "figma" || name === "link-world" || name === "export")
+        return "tools";
+    if (name === "debug" ||
+        name === "set-locale" ||
+        name === "report-issue" ||
+        name === "tokensave" ||
+        name === "security" ||
+        name.startsWith("security-") ||
+        name.startsWith("sal:")) {
+        return "admin";
+    }
+    return "tools";
+}
+export function getSlashCommandCategoryLabel(category, t) {
+    return t(`slash.categories.${category}`);
+}
+export function formatSlashCommandDescription(description, category, t) {
+    if (!description || !category)
+        return description;
+    const label = getSlashCommandCategoryLabel(category, t);
+    return label && !label.startsWith("slash.") ? `${label} · ${description}` : description;
+}
 export function getLocalizedCommands(t) {
     return BUILTIN_SLASH_COMMANDS.map((cmd) => ({
         name: cmd.name,
         description: t(cmd.descriptionKey),
+        category: cmd.category,
+        categoryLabel: getSlashCommandCategoryLabel(cmd.category, t),
     }));
 }

package/dist/core/telemetry/batching-dispatcher.d.ts

@@ -0,0 +1,41 @@
+/**
+ * [WHO]: Provides BatchingDispatcher<T> — generic event-buffering with deferred-flush timer, reentrancy protection, and close-time drain
+ * [FROM]: Depends on ./types for DiagnosticHandler; sink-agnostic — no HTTP, no insforge, no SAL semantics
+ * [TO]: Consumed by extensions/defaults/sal/eval/insforge-sink.ts via composition; future ext-telemetry sink reuses the same machinery
+ * [HERE]: core/telemetry/batching-dispatcher.ts - factored out of SAL's eval sink: SAL's scheduleFlush/doFlush/flush/close logic was inherently generic, now reusable
+ */
+import type { DiagnosticHandler } from "./types.js";
+export interface BatchingDispatcherOptions<T> {
+    /** Per-event work. Errors are caught and reported via onDiagnostic. */
+    handler: (event: T) => Promise<void>;
+    /** Flush timer interval in ms. Default 2000ms. */
+    intervalMs?: number;
+    /** Diagnostic source used in fingerprints. e.g. "sal.eval". */
+    source: string;
+    onDiagnostic?: DiagnosticHandler;
+}
+/**
+ * Generic buffer-then-drain dispatcher. Consumers call enqueue() to add work;
+ * a debounced flush timer drains the queue serially through the handler.
+ * close() drains synchronously (best-effort) before letting the process exit.
+ *
+ * Reentrancy: doFlush() loops over splice()'d batches so events arriving while
+ * a flush is in flight are picked up by the same flush cycle.
+ */
+export declare class BatchingDispatcher<T> {
+    private pending;
+    private flushTimer;
+    private flushInFlight;
+    private closed;
+    private handler;
+    private intervalMs;
+    private source;
+    private onDiagnostic?;
+    constructor(options: BatchingDispatcherOptions<T>);
+    enqueue(event: T): void;
+    flush(): Promise<void>;
+    close(): Promise<void>;
+    private scheduleFlush;
+    private doFlush;
+    private reportFlushFailure;
+}

package/dist/core/telemetry/batching-dispatcher.js

@@ -0,0 +1,89 @@
+/**
+ * Generic buffer-then-drain dispatcher. Consumers call enqueue() to add work;
+ * a debounced flush timer drains the queue serially through the handler.
+ * close() drains synchronously (best-effort) before letting the process exit.
+ *
+ * Reentrancy: doFlush() loops over splice()'d batches so events arriving while
+ * a flush is in flight are picked up by the same flush cycle.
+ */
+export class BatchingDispatcher {
+    pending = [];
+    flushTimer;
+    flushInFlight;
+    closed = false;
+    handler;
+    intervalMs;
+    source;
+    onDiagnostic;
+    constructor(options) {
+        this.handler = options.handler;
+        this.intervalMs = options.intervalMs ?? 2000;
+        this.source = options.source;
+        this.onDiagnostic = options.onDiagnostic;
+    }
+    enqueue(event) {
+        if (this.closed)
+            return;
+        this.pending.push(event);
+        this.scheduleFlush();
+    }
+    async flush() {
+        if (this.flushInFlight) {
+            await this.flushInFlight.catch(() => { });
+            return;
+        }
+        this.flushInFlight = this.doFlush();
+        try {
+            await this.flushInFlight;
+        }
+        catch (err) {
+            this.reportFlushFailure(err, "flush");
+        }
+        finally {
+            this.flushInFlight = undefined;
+        }
+    }
+    async close() {
+        this.closed = true;
+        await this.flush().catch((err) => {
+            this.reportFlushFailure(err, "close-flush");
+        });
+    }
+    scheduleFlush() {
+        if (this.flushTimer)
+            return;
+        this.flushTimer = setTimeout(() => {
+            this.flushTimer = undefined;
+            void this.flush().catch(() => { });
+        }, this.intervalMs);
+    }
+    async doFlush() {
+        if (this.flushTimer) {
+            clearTimeout(this.flushTimer);
+            this.flushTimer = undefined;
+        }
+        while (true) {
+            const toFlush = this.pending.splice(0);
+            if (toFlush.length === 0)
+                break;
+            for (const event of toFlush) {
+                try {
+                    await this.handler(event);
+                }
+                catch (err) {
+                    this.reportFlushFailure(err, "handler");
+                }
+            }
+        }
+    }
+    reportFlushFailure(err, fingerprintSuffix) {
+        this.onDiagnostic?.({
+            source: this.source,
+            severity: "error",
+            category: "persistence",
+            message: "Telemetry flush failed.",
+            detail: err instanceof Error ? { error: err.message } : err,
+            fingerprint: `${this.source}:persistence:${fingerprintSuffix}`,
+        });
+    }
+}

package/dist/core/telemetry/build-meta.d.ts

@@ -0,0 +1,12 @@
+export interface BuildMeta {
+    version: string;
+    commitHash?: string;
+    branch?: string;
+}
+/**
+ * Walk up from this module's location looking for either a generated
+ * `build-meta.json` (production / dist) or the project's `package.json` (dev /
+ * tsx). Location-independent: works regardless of which directory the caller
+ * lives in. Always returns a result — fallback is `{ version: "dev" }`.
+ */
+export declare function loadBuildMeta(): BuildMeta;

package/dist/core/telemetry/build-meta.js

@@ -0,0 +1,57 @@
+/**
+ * [WHO]: Provides BuildMeta interface + loadBuildMeta() — single-source build-stamp loader (version + commit + branch)
+ * [FROM]: Depends on node:fs (existsSync, readFileSync), node:path (dirname, join), node:url (fileURLToPath)
+ * [TO]: Consumed by extensions/defaults/sal/index.ts and core/telemetry/ext-events.ts; both want the same version stamp on every emitted row
+ * [HERE]: core/telemetry/build-meta.ts - extracted from SAL's inline loadBuildMeta(); location-independent walker so callers in core/, extensions/, or scripts/ all resolve the same way
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+const FALLBACK = { version: "dev" };
+const PKG_NAME = "@pencil-agent/nano-pencil";
+const MAX_WALK_DEPTH = 12;
+/**
+ * Walk up from this module's location looking for either a generated
+ * `build-meta.json` (production / dist) or the project's `package.json` (dev /
+ * tsx). Location-independent: works regardless of which directory the caller
+ * lives in. Always returns a result — fallback is `{ version: "dev" }`.
+ */
+export function loadBuildMeta() {
+    try {
+        const thisFile = fileURLToPath(import.meta.url);
+        let dir = dirname(thisFile);
+        for (let i = 0; i < MAX_WALK_DEPTH; i++) {
+            const distMetaPath = join(dir, "build-meta.json");
+            if (existsSync(distMetaPath)) {
+                const parsed = JSON.parse(readFileSync(distMetaPath, "utf-8"));
+                return {
+                    version: typeof parsed.version === "string" ? parsed.version : FALLBACK.version,
+                    commitHash: typeof parsed.commitHash === "string" ? parsed.commitHash : undefined,
+                    branch: typeof parsed.branch === "string" ? parsed.branch : undefined,
+                };
+            }
+            const pkgPath = join(dir, "package.json");
+            if (existsSync(pkgPath)) {
+                try {
+                    const parsed = JSON.parse(readFileSync(pkgPath, "utf-8"));
+                    if (parsed?.name === PKG_NAME) {
+                        return {
+                            version: typeof parsed.version === "string" ? parsed.version : FALLBACK.version,
+                        };
+                    }
+                }
+                catch {
+                    // fall through and keep walking
+                }
+            }
+            const parent = dirname(dir);
+            if (parent === dir)
+                break;
+            dir = parent;
+        }
+    }
+    catch {
+        // non-fatal — fall through to fallback
+    }
+    return FALLBACK;
+}

package/dist/core/telemetry/caller-context.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Per-async-frame metadata identifying which extension triggered the current
+ * execution path and whether that path was initiated by a user action (slash
+ * command) or by a hook auto-firing. Read by the LLM-call telemetry wrapper
+ * so each ext_llm_calls row can answer "who burned these tokens, and was the
+ * user aware?".
+ */
+export interface ExtCallerContext {
+    extensionName: string;
+    /**
+     * Short scope label, e.g. "command:/recap --smart" or "hook:before_agent_start".
+     * Format is consumer-readable; bounded length (≤128 chars).
+     */
+    callerContext: string;
+    /**
+     * True when the path was initiated by the user typing a slash command;
+     * false when the path was initiated by an extension hook auto-firing.
+     * This is the field SQL dashboards group on to catch idle-thinking-class
+     * bugs (hooks silently calling LLMs the user never asked for).
+     */
+    isUserInitiated: boolean;
+    sessionId?: string | null;
+    runId?: string | null;
+    variant?: string | null;
+}
+/**
+ * Run `fn` with `ctx` accessible to any descendant async frame via
+ * getExtCallerContext(). The context is automatically cleared when the
+ * returned promise settles.
+ */
+export declare function runWithExtCallerContext<T>(ctx: ExtCallerContext, fn: () => Promise<T> | T): Promise<T>;
+export declare function getExtCallerContext(): ExtCallerContext | undefined;

package/dist/core/telemetry/caller-context.js

@@ -0,0 +1,19 @@
+/**
+ * [WHO]: Provides ExtCallerContext interface, runWithExtCallerContext(), getExtCallerContext() — AsyncLocalStorage-backed caller-attribution bus
+ * [FROM]: Depends on node:async_hooks (AsyncLocalStorage); no other internal deps to stay loadable from anywhere in the runtime
+ * [TO]: runWithExtCallerContext is pushed by core/extensions/runner.ts at every command/hook dispatch boundary; getExtCallerContext is read by core/runtime/extension-core-bindings.ts when writing ext_llm_calls rows
+ * [HERE]: core/telemetry/caller-context.ts - the only mechanism distinguishing "extension command path (user-initiated)" from "extension hook path (auto-fired)" when an LLM call eventually happens; if this bus is empty, the telemetry layer marks the call as is_user_initiated=false / extension_name="unknown"
+ */
+import { AsyncLocalStorage } from "node:async_hooks";
+const storage = new AsyncLocalStorage();
+/**
+ * Run `fn` with `ctx` accessible to any descendant async frame via
+ * getExtCallerContext(). The context is automatically cleared when the
+ * returned promise settles.
+ */
+export function runWithExtCallerContext(ctx, fn) {
+    return Promise.resolve(storage.run(ctx, fn));
+}
+export function getExtCallerContext() {
+    return storage.getStore();
+}

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

@@ -0,0 +1,27 @@
+import type { DiagnosticHandler } from "./types.js";
+/**
+ * Base shape of an insforge credentials record. Sinks may extend this with
+ * their own fields (e.g. SAL adds `cleanup_stale_runs`); use the generic
+ * parameter on loadInsforgeCredentials to type those extra fields safely.
+ */
+export interface InsforgeCredentialsBase {
+    endpoint?: string;
+    /** Legacy alias for `endpoint` — both formats are produced by older configs. */
+    insforge_url?: string;
+    api_key?: string;
+    anon_key?: string;
+    api_key_header?: string;
+    headers?: Record<string, string>;
+    allow_self_signed?: boolean;
+    enabled?: boolean;
+}
+/**
+ * Walks a prioritized list of candidate paths (workspace overrides home dir) and
+ * returns the first usable credentials record. Returns null when nothing is found
+ * or all files are unparseable.
+ *
+ * `source` is folded into emitted diagnostics so SAL keeps emitting
+ * `sal.eval:...` fingerprints and a future ext-telemetry sink emits
+ * `ext.telemetry:...` without changing this loader.
+ */
+export declare function loadInsforgeCredentials<T extends InsforgeCredentialsBase = InsforgeCredentialsBase>(workspaceRoot: string, source: string, onDiagnostic?: DiagnosticHandler, extraEnvPath?: string): T | null;

package/dist/core/telemetry/credentials.js

@@ -0,0 +1,87 @@
+/**
+ * [WHO]: Provides InsforgeCredentialsBase interface + loadInsforgeCredentials() — single-source credential loader for any insforge-backed telemetry sink
+ * [FROM]: Depends on node:fs (existsSync, readFileSync), node:os (homedir), node:path (join), ./types for DiagnosticHandler
+ * [TO]: Consumed by extensions/defaults/sal/index.ts via re-export; future extension-telemetry sink reads via the same loader
+ * [HERE]: core/telemetry/credentials.ts - parses ~/.memory-experiments/credentials.json (workspace fallback ordered first), accepts both {credentials:[{id,...}]} and flat formats, returns null when no usable file found
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+const CREDENTIALS_BASENAME = ".memory-experiments";
+const CREDENTIALS_FILE = "credentials.json";
+const INSFORGE_ENTRY_ID = "insforge";
+/**
+ * Walks a prioritized list of candidate paths (workspace overrides home dir) and
+ * returns the first usable credentials record. Returns null when nothing is found
+ * or all files are unparseable.
+ *
+ * `source` is folded into emitted diagnostics so SAL keeps emitting
+ * `sal.eval:...` fingerprints and a future ext-telemetry sink emits
+ * `ext.telemetry:...` without changing this loader.
+ */
+export function loadInsforgeCredentials(workspaceRoot, source, onDiagnostic, extraEnvPath) {
+    const candidates = [
+        extraEnvPath,
+        join(workspaceRoot, CREDENTIALS_BASENAME, CREDENTIALS_FILE),
+        join(homedir(), CREDENTIALS_BASENAME, CREDENTIALS_FILE),
+    ].filter((path) => Boolean(path));
+    for (const filePath of candidates) {
+        const parsed = readFileSafely(filePath, source, onDiagnostic);
+        if (!parsed)
+            continue;
+        const record = pickInsforgeEntry(parsed);
+        if (record)
+            return record;
+    }
+    return null;
+}
+function readFileSafely(filePath, source, onDiagnostic) {
+    try {
+        if (!existsSync(filePath))
+            return null;
+        const raw = readFileSync(filePath, "utf-8");
+        const parsed = JSON.parse(raw);
+        if (!parsed || typeof parsed !== "object")
+            return null;
+        return parsed;
+    }
+    catch (err) {
+        onDiagnostic?.({
+            source,
+            severity: "warning",
+            category: "config",
+            message: "Insforge credentials file could not be read.",
+            detail: { filePath, error: err.message },
+            fingerprint: `${source}:config:credentials-read-failed`,
+        });
+        return null;
+    }
+}
+function pickInsforgeEntry(parsed) {
+    // Format 1: { credentials: [{ id: "insforge", ... }, ...] }
+    if (Array.isArray(parsed.credentials)) {
+        const entry = parsed.credentials.find((e) => e?.id === INSFORGE_ENTRY_ID && e?.enabled !== false);
+        if (entry)
+            return normalizeEntry(entry);
+        return null;
+    }
+    // Format 2: flat record at top level.
+    return normalizeEntry(parsed);
+}
+function normalizeEntry(entry) {
+    // Map camelCase aliases → snake_case canonical fields. Preserve any extra
+    // (sink-specific) keys verbatim so callers like SAL can read
+    // `cleanup_stale_runs` etc. without this loader knowing about them.
+    const normalized = {
+        ...entry,
+        endpoint: entry.endpoint ?? entry.insforge_url,
+        insforge_url: entry.insforge_url ?? entry.endpoint,
+        api_key: entry.api_key ?? entry.apiKey,
+        anon_key: entry.anon_key ?? entry.anonKey,
+        api_key_header: entry.api_key_header ?? entry.apiKeyHeader,
+        headers: entry.headers,
+        allow_self_signed: entry.allow_self_signed ?? entry.allowSelfSigned,
+        enabled: entry.enabled,
+    };
+    return normalized;
+}

package/dist/core/telemetry/ext-events.d.ts

@@ -0,0 +1,89 @@
+import type { DiagnosticHandler } from "./types.js";
+/**
+ * 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 declare const HOOK_SAMPLE_RATES: Readonly<Record<string, number>>;
+export type CommandOutcome = "ok" | "error" | "cancelled" | "no_match" | "unknown";
+export interface CommandEventInput {
+    extensionName: string;
+    commandName: string;
+    /** Whitelisted-token-only classification — see classifyArgsSignature(). Never contains original arg text. */
+    argsSignature: string;
+    argsLength: number;
+    outcome: CommandOutcome;
+    errorCode?: string | null;
+    durationMs: number;
+    details?: Record<string, unknown> | null;
+    startedAt: Date;
+    endedAt: Date;
+    runId?: string | null;
+    sessionId?: string | null;
+    variant?: string | null;
+}
+export interface HookEventInput {
+    extensionName: string;
+    hookName: string;
+    durationMs: number;
+    ok: boolean;
+    errorCode?: string | null;
+    /** Sampling probability used to decide whether to emit. Stored on each row so dashboards can extrapolate counts. */
+    sampleRate: number;
+    recordedAt: Date;
+    runId?: string | null;
+    sessionId?: string | null;
+    variant?: string | null;
+}
+export interface LlmCallEventInput {
+    extensionName: string;
+    /** Short scope label, e.g. "command:/recap --smart" or "hook:before_agent_start". */
+    callerContext: string;
+    /** True for slash-command paths; false for hook auto-fires. SQL dashboards group on this to find idle-thinking-class bugs. */
+    isUserInitiated: boolean;
+    modelId?: string | null;
+    tokensIn?: number | null;
+    tokensOut?: number | null;
+    costTotal?: number | null;
+    durationMs: number;
+    ok: boolean;
+    errorCode?: string | null;
+    startedAt: Date;
+    endedAt: Date;
+    runId?: string | null;
+    sessionId?: string | null;
+    variant?: string | null;
+    commandEventId?: number | null;
+}
+export interface ExtensionTelemetrySink {
+    writeCommandEvent(input: CommandEventInput): void;
+    writeLlmCallEvent(input: LlmCallEventInput): void;
+    writeHookEvent(input: HookEventInput): void;
+    close(): Promise<void>;
+}
+export interface CreateExtensionTelemetrySinkOptions {
+    workspaceRoot: string;
+    onDiagnostic?: DiagnosticHandler;
+    batchIntervalMs?: number;
+}
+/**
+ * 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 declare function createExtensionTelemetrySink(options: CreateExtensionTelemetrySinkOptions): ExtensionTelemetrySink;
+/**
+ * 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 declare function classifyArgsSignature(args: string): string;