catui-agent 1.0.0-beta.0

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

@@ -0,0 +1,53 @@
+/**
+ * [WHO]: slashCommands - Chinese translations for slash command descriptions
+ * [FROM]: No external dependencies
+ * [TO]: Consumed by core/platform/i18n/index.ts
+ * [HERE]: core/platform/i18n/slash-commands.zh.ts - Chinese slash command translations
+ */
+export declare const slashCommands: {
+    categories: {
+        core: string;
+        model: string;
+        memory: string;
+        session: string;
+        workflow: string;
+        agents: string;
+        tools: string;
+        admin: string;
+    };
+    settings: string;
+    model: string;
+    thinking: string;
+    "agent-loop": string;
+    "scoped-models": string;
+    apikey: string;
+    mcp: string;
+    soul: string;
+    persona: string;
+    memory: string;
+    dream: string;
+    browser: string;
+    export: string;
+    share: string;
+    copy: string;
+    name: string;
+    session: string;
+    status: string;
+    usage: string;
+    changelog: string;
+    hotkeys: string;
+    resources: string;
+    fork: string;
+    tree: string;
+    login: string;
+    logout: string;
+    new: string;
+    update: string;
+    reinstall: string;
+    compact: string;
+    resume: string;
+    reload: string;
+    "link-world": string;
+    quit: string;
+    language: string;
+};

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

@@ -0,0 +1 @@
+const e={categories:{core:"\u6838\u5FC3",model:"\u6A21\u578B",memory:"\u8BB0\u5FC6",session:"\u4F1A\u8BDD",workflow:"\u5DE5\u4F5C\u6D41",agents:"Agent",tools:"\u5DE5\u5177",admin:"\u7BA1\u7406"},settings:"\u6253\u5F00\u8BBE\u7F6E\u83DC\u5355",model:"\u9009\u62E9\u6A21\u578B\uFF08\u6253\u5F00\u9009\u62E9\u5668\u754C\u9762\uFF09",thinking:"\u9009\u62E9\u5F53\u524D\u6A21\u578B\u7684\u63A8\u7406\u6DF1\u5EA6","agent-loop":"\u9009\u62E9 agent \u63A8\u8FDB\u4EFB\u52A1\u7684\u65B9\u5F0F","scoped-models":"\u9009\u62E9\u5FEB\u901F\u5207\u6362\u91CC\u51FA\u73B0\u7684\u6A21\u578B",apikey:"\u66F4\u65B0\u5F53\u524D\u63D0\u4F9B\u5546\u7684 API \u5BC6\u94A5",mcp:"\u7BA1\u7406 MCP \u670D\u52A1\u5668\uFF08\u5217\u51FA\u3001\u542F\u7528\u3001\u7981\u7528\uFF09",soul:"\u663E\u793A AI \u4EBA\u683C\u548C\u7EDF\u8BA1\uFF08\u7075\u9B42\uFF09",persona:"\u5207\u6362 AI \u4EBA\u683C/\u4E2A\u6027\u5305",memory:"\u663E\u793A\u9879\u76EE\u8BB0\u5FC6\u548C\u77E5\u8BC6\uFF08\u7EB3\u7C73\u8BB0\u5FC6\uFF09",dream:"\u5237\u65B0\u957F\u671F\u9879\u76EE\u8BB0\u5FC6\uFF08\u7EB3\u7C73\u8BB0\u5FC6\uFF09",browser:"\u542F\u7528\u6216\u68C0\u67E5\u6D4F\u89C8\u5668\u81EA\u52A8\u5316\u5DE5\u5177",export:"\u5C06\u4F1A\u8BDD\u5BFC\u51FA\u4E3A HTML \u6587\u4EF6",share:"\u5C06\u4F1A\u8BDD\u5206\u4EAB\u4E3A\u4FDD\u5BC6\u7684 GitHub gist",copy:"\u590D\u5236\u4E0A\u4E00\u6761 AI \u6D88\u606F\u5230\u526A\u8D34\u677F",name:"\u8BBE\u7F6E\u4F1A\u8BDD\u663E\u793A\u540D\u79F0",session:"\u663E\u793A\u4F1A\u8BDD\u4FE1\u606F\u548C\u7EDF\u8BA1",status:"\u663E\u793A\u4EE3\u7406\u72B6\u6001\u5361\u7247\uFF08\u6A21\u578B\u3001\u76EE\u5F55\u3001\u4F1A\u8BDD\u3001\u7528\u91CF\uFF09",usage:"\u663E\u793A token \u4F7F\u7528\u91CF\u548C\u8D39\u7528\u7EDF\u8BA1",changelog:"\u663E\u793A\u66F4\u65B0\u65E5\u5FD7\u6761\u76EE",hotkeys:"\u663E\u793A\u6240\u6709\u952E\u76D8\u5FEB\u6377\u952E",resources:"\u663E\u793A\u5DF2\u52A0\u8F7D\u7684\u6269\u5C55\u3001\u63D0\u793A\u3001\u6280\u80FD\u548C\u4E3B\u9898",fork:"\u4ECE\u4E0A\u4E00\u6761\u6D88\u606F\u521B\u5EFA\u65B0\u5206\u652F",tree:"\u5BFC\u822A\u4F1A\u8BDD\u6811\uFF08\u5207\u6362\u5206\u652F\uFF09",login:"\u901A\u8FC7 OAuth \u63D0\u4F9B\u5546\u767B\u5F55",logout:"\u4ECE OAuth \u63D0\u4F9B\u5546\u767B\u51FA",new:"\u5F00\u59CB\u65B0\u4F1A\u8BDD",update:"\u68C0\u67E5 Catui \u66F4\u65B0",reinstall:"\u5F3A\u5236\u91CD\u65B0\u5B89\u88C5 Catui\uFF08\u5E72\u51C0\u5B89\u88C5\uFF09",compact:"\u624B\u52A8\u538B\u7F29\u4F1A\u8BDD\u4E0A\u4E0B\u6587",resume:"\u6062\u590D\u5176\u4ED6\u4F1A\u8BDD",reload:"\u91CD\u65B0\u52A0\u8F7D\u6269\u5C55\u3001\u6280\u80FD\u3001\u63D0\u793A\u548C\u4E3B\u9898","link-world":"\u8BBE\u7F6E\u8054\u7F51\u8BBF\u95EE\u5DE5\u5177",quit:"\u9000\u51FA Catui",language:"\u5207\u6362\u8BED\u8A00\uFF08English/\u4E2D\u6587\uFF09"};export{e as slashCommands};

package/dist/core/platform/i18n/themes.d.ts

@@ -0,0 +1,11 @@
+/**
+ * [WHO]: themes - English translations for theme names
+ * [FROM]: No external dependencies
+ * [TO]: Consumed by core/platform/i18n/index.ts
+ * [HERE]: core/platform/i18n/themes.ts - English theme translations
+ */
+export declare const themes: {
+    dark: string;
+    light: string;
+    warm: string;
+};

package/dist/core/platform/i18n/themes.js

@@ -0,0 +1 @@
+const r={dark:"Dark",light:"Light",warm:"Warm (Eye-friendly)"};export{r as themes};

package/dist/core/platform/i18n/themes.zh.d.ts

@@ -0,0 +1,11 @@
+/**
+ * [WHO]: themes - Chinese translations for theme names
+ * [FROM]: No external dependencies
+ * [TO]: Consumed by core/platform/i18n/index.ts
+ * [HERE]: core/platform/i18n/themes.zh.ts - Chinese theme translations
+ */
+export declare const themes: {
+    dark: string;
+    light: string;
+    warm: string;
+};

package/dist/core/platform/i18n/themes.zh.js

@@ -0,0 +1 @@
+const t={dark:"\u6DF1\u8272",light:"\u6D45\u8272",warm:"\u6696\u8272\uFF08\u62A4\u773C\uFF09"};export{t as themes};

package/dist/core/platform/keybindings.d.ts

@@ -0,0 +1,61 @@
+/**
+ * [WHO]: AppKeybinding, KeybindingsManager, KeybindingsConfig
+ * [FROM]: Depends on tui, node:fs, node:path, config
+ * [TO]: Consumed by main.ts, cli/session-picker.ts, modes/interactive/interactive-mode.ts, modes/interactive/components/session-selector.ts, modes/interactive/components/custom-editor.ts, modes/interactive/components/extension-editor.ts, modes/interactive/components/keybinding-hints.ts
+ * [HERE]: core/platform/keybindings.ts - application-level keybindings management
+ */
+import { type EditorAction, type KeyId } from "@catui/tui";
+import { type AgentDirContext } from "../agent-dir/agent-dir-context.js";
+/**
+ * Application-level actions (coding agent specific).
+ */
+export type AppAction = "interrupt" | "showResources" | "clear" | "exit" | "suspend" | "cycleThinkingLevel" | "cycleModelForward" | "cycleModelBackward" | "selectModel" | "selectProviderThenModel" | "expandTools" | "toggleThinking" | "toggleSessionNamedFilter" | "externalEditor" | "followUp" | "dequeue" | "pasteImage" | "newSession" | "tree" | "fork" | "resume";
+/**
+ * All configurable actions.
+ */
+export type KeyAction = AppAction | EditorAction;
+/**
+ * Full keybindings configuration (app + editor actions).
+ */
+export type KeybindingsConfig = {
+    [K in KeyAction]?: KeyId | KeyId[];
+};
+/**
+ * Default application keybindings.
+ */
+export declare const DEFAULT_APP_KEYBINDINGS: Record<AppAction, KeyId | KeyId[]>;
+/**
+ * All default keybindings (app + editor).
+ */
+export declare const DEFAULT_KEYBINDINGS: Required<KeybindingsConfig>;
+/**
+ * Manages all keybindings (app + editor).
+ */
+export declare class KeybindingsManager {
+    private config;
+    private appActionToKeys;
+    private constructor();
+    /**
+     * Create from config file and set up editor keybindings.
+     */
+    static create(ctx?: AgentDirContext): KeybindingsManager;
+    /**
+     * Create in-memory.
+     */
+    static inMemory(config?: KeybindingsConfig): KeybindingsManager;
+    private static loadFromFile;
+    private buildMaps;
+    /**
+     * Check if input matches an app action.
+     */
+    matches(data: string, action: AppAction): boolean;
+    /**
+     * Get keys bound to an app action.
+     */
+    getKeys(action: AppAction): KeyId[];
+    /**
+     * Get the full effective config.
+     */
+    getEffectiveConfig(): Required<KeybindingsConfig>;
+}
+export type { EditorAction, KeyId };

package/dist/core/platform/keybindings.js

@@ -0,0 +1 @@
+var d=Object.defineProperty;var c=(n,e)=>d(n,"name",{value:e,configurable:!0});import{DEFAULT_EDITOR_KEYBINDINGS as u,EditorKeybindingsManager as y,matchesKey as g,setEditorKeybindings as h}from"@catui/tui";import{existsSync as A,readFileSync as T}from"fs";import{join as m}from"path";import{defaultAgentDirContext as k}from"../agent-dir/agent-dir-context.js";const a={interrupt:"escape",showResources:"ctrl+h",clear:"ctrl+c",exit:"ctrl+d",suspend:"ctrl+z",cycleThinkingLevel:"shift+tab",cycleModelForward:"ctrl+p",cycleModelBackward:"shift+ctrl+p",selectModel:"ctrl+l",selectProviderThenModel:"ctrl+shift+l",expandTools:"ctrl+o",toggleThinking:"ctrl+t",toggleSessionNamedFilter:"ctrl+n",externalEditor:"ctrl+g",followUp:"alt+enter",dequeue:"alt+up",pasteImage:"ctrl+v",newSession:[],tree:[],fork:[],resume:[]},w={...u,...a},x=["interrupt","showResources","clear","exit","suspend","cycleThinkingLevel","cycleModelForward","cycleModelBackward","selectModel","selectProviderThenModel","expandTools","toggleThinking","toggleSessionNamedFilter","externalEditor","followUp","dequeue","pasteImage","newSession","tree","fork","resume"];function f(n){return x.includes(n)}c(f,"isAppAction");class r{static{c(this,"KeybindingsManager")}config;appActionToKeys;constructor(e){this.config=e,this.appActionToKeys=new Map,this.buildMaps()}static create(e=k()){const t=m(e.path,"keybindings.json"),o=r.loadFromFile(t),s=new r(o),l={};for(const[i,p]of Object.entries(o))(!f(i)||i==="expandTools")&&(l[i]=p);return h(new y(l)),s}static inMemory(e={}){return new r(e)}static loadFromFile(e){if(!A(e))return{};try{return JSON.parse(T(e,"utf-8"))}catch{return{}}}buildMaps(){this.appActionToKeys.clear();for(const[e,t]of Object.entries(a)){const o=Array.isArray(t)?t:[t];this.appActionToKeys.set(e,[...o])}for(const[e,t]of Object.entries(this.config)){if(t===void 0||!f(e))continue;const o=Array.isArray(t)?t:[t];this.appActionToKeys.set(e,o)}}matches(e,t){const o=this.appActionToKeys.get(t);if(!o)return!1;for(const s of o)if(g(e,s))return!0;return!1}getKeys(e){return this.appActionToKeys.get(e)??[]}getEffectiveConfig(){const e={...w};for(const[t,o]of Object.entries(this.config))o!==void 0&&(e[t]=o);return e}}export{a as DEFAULT_APP_KEYBINDINGS,w as DEFAULT_KEYBINDINGS,r as KeybindingsManager};

package/dist/core/platform/listeners.d.ts

@@ -0,0 +1,21 @@
+/**
+ * [WHO]: Provides Listeners<T> — a typed broadcast listener set
+ * [FROM]: No dependencies
+ * [TO]: Consumed by core/runtime/agent-session.ts (session event subscribers); reusable by any
+ *       module needing add/emit/clear over a set of same-typed callbacks
+ * [HERE]: core/platform/listeners.ts - generic observer primitive (no business knowledge)
+ *
+ * Replaces the inline `private _xListeners: Fn[]` + push / indexOf-splice / clear pattern.
+ * add() returns an unsubscribe closure; emit() broadcasts to every current listener.
+ */
+export declare class Listeners<T> {
+    private _listeners;
+    /** Register a listener; returns a function that removes exactly this listener. */
+    add(listener: (value: T) => void): () => void;
+    /** Broadcast a value to all current listeners. */
+    emit(value: T): void;
+    /** Number of registered listeners. */
+    get size(): number;
+    /** Remove all listeners. */
+    clear(): void;
+}

package/dist/core/platform/listeners.js

@@ -0,0 +1 @@
+var n=Object.defineProperty;var i=(t,s)=>n(t,"name",{value:s,configurable:!0});class l{static{i(this,"Listeners")}_listeners=[];add(s){return this._listeners.push(s),()=>{const e=this._listeners.indexOf(s);e!==-1&&this._listeners.splice(e,1)}}emit(s){for(const e of this._listeners)e(s)}get size(){return this._listeners.length}clear(){this._listeners=[]}}export{l as Listeners};

package/dist/core/platform/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/builtin/sal/eval/insforge-sink.ts via composition; future ext-telemetry sink reuses the same machinery
+ * [HERE]: core/platform/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/platform/telemetry/batching-dispatcher.js

@@ -0,0 +1 @@
+var r=Object.defineProperty;var t=(i,s)=>r(i,"name",{value:s,configurable:!0});class u{static{t(this,"BatchingDispatcher")}pending=[];flushTimer;flushInFlight;closed=!1;handler;intervalMs;source;onDiagnostic;constructor(s){this.handler=s.handler,this.intervalMs=s.intervalMs??2e3,this.source=s.source,this.onDiagnostic=s.onDiagnostic}enqueue(s){this.closed||(this.pending.push(s),this.scheduleFlush())}async flush(){if(this.flushInFlight){await this.flushInFlight.catch(()=>{});return}this.flushInFlight=this.doFlush();try{await this.flushInFlight}catch(s){this.reportFlushFailure(s,"flush")}finally{this.flushInFlight=void 0}}async close(){this.closed=!0,await this.flush().catch(s=>{this.reportFlushFailure(s,"close-flush")})}scheduleFlush(){this.flushTimer||(this.flushTimer=setTimeout(()=>{this.flushTimer=void 0,this.flush().catch(()=>{})},this.intervalMs))}async doFlush(){for(this.flushTimer&&(clearTimeout(this.flushTimer),this.flushTimer=void 0);;){const s=this.pending.splice(0);if(s.length===0)break;for(const e of s)try{await this.handler(e)}catch(h){this.reportFlushFailure(h,"handler")}}}reportFlushFailure(s,e){this.onDiagnostic?.({source:this.source,severity:"error",category:"persistence",message:"Telemetry flush failed.",detail:s instanceof Error?{error:s.message}:s,fingerprint:`${this.source}:persistence:${e}`})}}export{u as BatchingDispatcher};

package/dist/core/platform/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/platform/telemetry/build-meta.js

@@ -0,0 +1 @@
+var h=Object.defineProperty;var c=(n,e)=>h(n,"name",{value:e,configurable:!0});import{existsSync as f,readFileSync as m}from"node:fs";import{dirname as p,join as d}from"node:path";import{fileURLToPath as u}from"node:url";const r={version:"dev"},v="catui-agent",l=12;function P(){try{const n=u(import.meta.url);let e=p(n);for(let i=0;i<l;i++){const o=d(e,"build-meta.json");if(f(o)){const t=JSON.parse(m(o,"utf-8"));return{version:typeof t.version=="string"?t.version:r.version,commitHash:typeof t.commitHash=="string"?t.commitHash:void 0,branch:typeof t.branch=="string"?t.branch:void 0}}const s=d(e,"package.json");if(f(s))try{const t=JSON.parse(m(s,"utf-8"));if(t?.name===v)return{version:typeof t.version=="string"?t.version:r.version}}catch{}const a=p(e);if(a===e)break;e=a}}catch{}return r}c(P,"loadBuildMeta");export{P as loadBuildMeta};

package/dist/core/platform/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/platform/telemetry/caller-context.js

@@ -0,0 +1 @@
+var n=Object.defineProperty;var r=(t,e)=>n(t,"name",{value:e,configurable:!0});import{AsyncLocalStorage as l}from"node:async_hooks";const o=new l;function a(t,e){return Promise.resolve(o.run(t,e))}r(a,"runWithExtCallerContext");function c(){return o.getStore()}r(c,"getExtCallerContext");export{c as getExtCallerContext,a as runWithExtCallerContext};

package/dist/core/platform/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/platform/telemetry/credentials.js

@@ -0,0 +1 @@
+var _=Object.defineProperty;var a=(e,n)=>_(e,"name",{value:n,configurable:!0});import{existsSync as p,readFileSync as g}from"node:fs";import{homedir as m}from"node:os";import{join as d}from"node:path";const f=".memory-experiments",c="credentials.json",E="insforge";function b(e,n,r,i){const o=[i,d(e,f,c),d(m(),f,c)].filter(l=>!!l);for(const l of o){const s=S(l,n,r);if(!s)continue;const t=y(s);if(t)return t}return null}a(b,"loadInsforgeCredentials");function S(e,n,r){try{if(!p(e))return null;const i=g(e,"utf-8"),o=JSON.parse(i);return!o||typeof o!="object"?null:o}catch(i){return r?.({source:n,severity:"warning",category:"config",message:"Insforge credentials file could not be read.",detail:{filePath:e,error:i.message},fingerprint:`${n}:config:credentials-read-failed`}),null}}a(S,"readFileSafely");function y(e){if(Array.isArray(e.credentials)){const n=e.credentials.find(r=>r?.id===E&&r?.enabled!==!1);return n?u(n):null}return u(e)}a(y,"pickInsforgeEntry");function u(e){return{...e,endpoint:e.endpoint??e.insforge_url,insforge_url:e.insforge_url??e.endpoint,api_key:e.api_key??e.apiKey,anon_key:e.anon_key??e.anonKey,api_key_header:e.api_key_header??e.apiKeyHeader,headers:e.headers,allow_self_signed:e.allow_self_signed??e.allowSelfSigned,enabled:e.enabled}}a(u,"normalizeEntry");export{b as loadInsforgeCredentials};

package/dist/core/platform/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;

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

@@ -0,0 +1 @@
+var r=Object.defineProperty;var o=(a,e)=>r(a,"name",{value:e,configurable:!0});import{BatchingDispatcher as l}from"./batching-dispatcher.js";import{loadBuildMeta as i}from"./build-meta.js";import{loadInsforgeCredentials as d}from"./credentials.js";import{InsforgeHttpClient as c}from"./insforge-base.js";const n=i(),s="ext.telemetry",_="ext_command_events",m="ext_llm_calls",h="ext_hook_events",k=Object.freeze({tool_call:.1,tool_result:.1,tool_execution_start:.1,tool_execution_end:.1});class y{static{o(this,"NoopExtensionTelemetrySink")}writeCommandEvent(){}writeLlmCallEvent(){}writeHookEvent(){}async close(){}}class E{static{o(this,"InsforgeExtensionTelemetrySink")}http;dispatcher;constructor(e){this.http=new c({endpoint:e.endpoint,apiKey:e.apiKey,anonKey:e.anonKey,apiKeyHeader:e.apiKeyHeader,extraHeaders:e.extraHeaders,allowSelfSigned:e.allowSelfSigned,source:s,onDiagnostic:e.onDiagnostic}),this.dispatcher=new l({handler:o(t=>this.postEvent(t),"handler"),intervalMs:e.batchIntervalMs??2e3,source:s,onDiagnostic:e.onDiagnostic})}writeCommandEvent(e){this.dispatcher.enqueue({type:"command",payload:e})}writeLlmCallEvent(e){this.dispatcher.enqueue({type:"llm_call",payload:e})}writeHookEvent(e){this.dispatcher.enqueue({type:"hook",payload:e})}async close(){await this.dispatcher.close()}async postEvent(e){e.type==="command"?await this.postCommandEvent(e.payload):e.type==="llm_call"?await this.postLlmCallEvent(e.payload):await this.postHookEvent(e.payload)}async postCommandEvent(e){const t={run_id:e.runId??null,session_id:e.sessionId??null,extension_name:e.extensionName,command_name:e.commandName,args_signature:e.argsSignature,args_length:e.argsLength,outcome:e.outcome,error_code:e.errorCode??null,duration_ms:e.durationMs,details:e.details??null,catui_version:n.version,commit_hash:n.commitHash??null,variant:e.variant??null,started_at:e.startedAt.toISOString(),ended_at:e.endedAt.toISOString()};await this.http.postJson(`${this.http.base}/api/database/records/${_}`,[t])}async postLlmCallEvent(e){const t={run_id:e.runId??null,session_id:e.sessionId??null,command_event_id:e.commandEventId??null,extension_name:e.extensionName,caller_context:e.callerContext,is_user_initiated:e.isUserInitiated,model_id:e.modelId??null,tokens_in:e.tokensIn??null,tokens_out:e.tokensOut??null,cost_total:e.costTotal??null,duration_ms:e.durationMs,ok:e.ok,error_code:e.errorCode??null,catui_version:n.version,commit_hash:n.commitHash??null,variant:e.variant??null,started_at:e.startedAt.toISOString(),ended_at:e.endedAt.toISOString()};await this.http.postJson(`${this.http.base}/api/database/records/${m}`,[t])}async postHookEvent(e){const t={run_id:e.runId??null,session_id:e.sessionId??null,extension_name:e.extensionName,hook_name:e.hookName,duration_ms:e.durationMs,ok:e.ok,error_code:e.errorCode??null,sample_rate:e.sampleRate,catui_version:n.version,variant:e.variant??null,recorded_at:e.recordedAt.toISOString()};await this.http.postJson(`${this.http.base}/api/database/records/${h}`,[t])}}function f(a){const e=d(a.workspaceRoot,s,a.onDiagnostic),t=e?.endpoint??e?.insforge_url;return!t||!e?.api_key||e.enabled===!1?new y:new E({endpoint:t,apiKey:e.api_key,anonKey:e.anon_key,apiKeyHeader:e.api_key_header,extraHeaders:e.headers,allowSelfSigned:e.allow_self_signed,batchIntervalMs:a.batchIntervalMs,onDiagnostic:a.onDiagnostic})}o(f,"createExtensionTelemetrySink");function x(a){const e=a.trim();if(!e)return"no-args";const t=e.match(/^(--[a-z0-9-]+)/i);return t?t[1].toLowerCase():"with-args"}o(x,"classifyArgsSignature");export{k as HOOK_SAMPLE_RATES,x as classifyArgsSignature,f as createExtensionTelemetrySink};

package/dist/core/platform/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/builtin/sal/* and (future) extensions/<ext>/telemetry sinks via `import { ... } from "../../../core/platform/telemetry/index.js"`
+ * [HERE]: core/platform/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/platform/telemetry/index.js

@@ -0,0 +1 @@
+import{loadInsforgeCredentials as t}from"./credentials.js";import{InsforgeHttpClient as a,parsePostgrestErrorCode as s,safeHost as n}from"./insforge-base.js";import{BatchingDispatcher as x}from"./batching-dispatcher.js";import{loadBuildMeta as i}from"./build-meta.js";import{classifyArgsSignature as g,createExtensionTelemetrySink as m,HOOK_SAMPLE_RATES as C}from"./ext-events.js";import{getExtCallerContext as d,runWithExtCallerContext as c}from"./caller-context.js";export{x as BatchingDispatcher,C as HOOK_SAMPLE_RATES,a as InsforgeHttpClient,g as classifyArgsSignature,m as createExtensionTelemetrySink,d as getExtCallerContext,i as loadBuildMeta,t as loadInsforgeCredentials,s as parsePostgrestErrorCode,c as runWithExtCallerContext,n as safeHost};

package/dist/core/platform/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/platform/telemetry/insforge-base.js

@@ -0,0 +1 @@
+var C=Object.defineProperty;var f=(s,e)=>C(s,"name",{value:e,configurable:!0});import{request as S}from"node:http";import{request as k}from"node:https";import{URL as g}from"node:url";const D=5e3;class K{static{f(this,"InsforgeHttpClient")}base;headers;allowSelfSigned;timeoutMs;source;onDiagnostic;constructor(e){this.base=e.endpoint.replace(/\/+$/,""),this.allowSelfSigned=e.allowSelfSigned??!1,this.timeoutMs=e.timeoutMs??D,this.source=e.source,this.onDiagnostic=e.onDiagnostic,this.allowSelfSigned&&["1","true","yes","on"].includes((process.env.CATUI_DEBUG??process.env.NANOPENCIL_DEBUG??"").toLowerCase())&&console.warn(`[${this.source}] TLS certificate verification disabled (allowSelfSigned=true)`);const t={"Content-Type":"application/json",...e.extraHeaders??{}};e.anonKey&&(t.apikey=e.anonKey,t.Authorization=`Bearer ${e.anonKey}`),e.apiKey&&(t[e.apiKeyHeader??"x-api-key"]=e.apiKey,e.anonKey||(t.Authorization=`Bearer ${e.apiKey}`)),this.headers=t}postJson(e,t,r){const i={};return r?.prefer&&(i.Prefer=r.prefer),this.httpJson("POST",e,t,i,r?.quietErrorCodes)}patchJson(e,t){return this.httpJson("PATCH",e,t,{})}httpJson(e,t,r,i,m=[]){return new Promise(d=>{const l=JSON.stringify(r);let o;try{o=new g(t)}catch{this.reportDiagnostic("config","Insforge endpoint URL is invalid.",{url:t},"invalid-url"),d({ok:!1});return}const p=o.protocol==="https:",y=p?k:S,w=o.port?Number(o.port):p?443:80,a=y({hostname:o.hostname,port:w,path:o.pathname+o.search,method:e,headers:{...this.headers,...i,"Content-Length":Buffer.byteLength(l)},timeout:this.timeoutMs,...p&&this.allowSelfSigned?{rejectUnauthorized:!1}:{}},n=>{let u="";n.setEncoding("utf-8"),n.on("data",h=>{u+=h}),n.on("end",()=>{const h=n.statusCode!==void 0&&n.statusCode<300,c=T(u);!h&&!m.includes(c??"")&&this.reportDiagnostic(c==="PGRST204"?"schema":"network",`Insforge upload failed with HTTP ${n.statusCode}.`,{method:e,path:o.pathname,statusCode:n.statusCode,body:u.slice(0,300),errorCode:c},`http-${n.statusCode??"unknown"}-${c??"none"}`),d({ok:h,statusCode:n.statusCode,body:u,errorCode:c})})});a.on("error",n=>{this.reportDiagnostic("network","Insforge upload is failing due to a network connection error.",{host:o.hostname,error:n.message},"network-error"),d({ok:!1})}),a.on("timeout",()=>{this.reportDiagnostic("network","Insforge upload timed out.",{method:e,path:o.pathname,host:o.hostname},"timeout"),a.destroy(),d({ok:!1})}),a.write(l),a.end()})}reportDiagnostic(e,t,r,i){this.onDiagnostic?.({source:this.source,severity:e==="config"?"warning":"error",category:e,message:t,detail:r,fingerprint:`${this.source}:${e}:${i}`,context:{adapter:"insforge",endpoint_host:$(this.base)}})}}function T(s){try{const e=JSON.parse(s);return typeof e?.code=="string"?e.code:void 0}catch{return}}f(T,"parsePostgrestErrorCode");function $(s){try{return new g(s).hostname}catch{return}}f($,"safeHost");export{K as InsforgeHttpClient,T as parsePostgrestErrorCode,$ as safeHost};

package/dist/core/platform/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/platform/telemetry/credentials.ts, insforge-base.ts, batching-dispatcher.ts; mirrored by sinks (SAL eval, future extension telemetry)
+ * [HERE]: core/platform/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/platform/timings.d.ts

@@ -0,0 +1,2 @@
+export declare function time(label: string): void;
+export declare function printTimings(): void;

package/dist/core/platform/timings.js

@@ -0,0 +1,3 @@
+var c=Object.defineProperty;var r=(e,o)=>c(e,"name",{value:o,configurable:!0});const s=(process.env.CATUI_TIMING??process.env.NANOPENCIL_TIMING)==="1",n=[];let t=Date.now(),i=!1;function p(e){if(!s)return;const o=Date.now();n.push({label:e,ms:o-t}),t=o}r(p,"time");function l(){if(!(!s||i||n.length===0)){i=!0,console.error(`
+--- Startup Timings ---`);for(const e of n)console.error(`  ${e.label}: ${e.ms}ms`);console.error(`  TOTAL: ${n.reduce((e,o)=>e+o.ms,0)}ms`),console.error(`------------------------
+`)}}r(l,"printTimings"),s&&process.once("exit",l);export{l as printTimings,p as time};

package/dist/core/platform/utils/logger.d.ts

@@ -0,0 +1,75 @@
+/**
+ * [WHO]: AgentLogger, createLogger(), structured logging for agent sessions
+ * [FROM]: No external dependencies
+ * [TO]: Consumed by core/runtime/agent-session.ts, core/extensions-host/runner.ts, core/tools/*
+ * [HERE]: core/platform/utils/logger.ts - structured JSON logging with session/turn/span tracing
+ */
+/** Log levels in priority order */
+export type LogLevel = "debug" | "info" | "warn" | "error";
+/** Structured log entry */
+export interface LogEntry {
+    /** Timestamp in ISO 8601 */
+    timestamp: string;
+    /** Log level */
+    level: LogLevel;
+    /** Human-readable message */
+    message: string;
+    /** Session ID for correlation */
+    sessionId?: string;
+    /** Turn index within session */
+    turnId?: number;
+    /** Tool call ID for tool execution tracing */
+    toolCallId?: string;
+    /** Component/module source */
+    component?: string;
+    /** Duration in milliseconds (for spans) */
+    durationMs?: number;
+    /** Additional structured data */
+    data?: Record<string, unknown>;
+}
+/** Logger configuration */
+export interface LoggerConfig {
+    /** Minimum log level (default: "info") */
+    level?: LogLevel;
+    /** Session ID (set once per session) */
+    sessionId?: string;
+    /** Component name prefix */
+    component?: string;
+    /** Custom output handler (default: console.error for warn/error, console.log for info/debug) */
+    handler?: (entry: LogEntry) => void;
+}
+/** Format a LogEntry as a single-line JSON string */
+export declare function formatLogEntry(entry: LogEntry): string;
+/**
+ * AgentLogger — structured logger with session/turn/span tracing.
+ *
+ * Usage:
+ * ```typescript
+ * const logger = createLogger({ sessionId: "abc123", component: "compaction" });
+ * logger.info("Compaction started", { turnId: 5 });
+ * logger.warn("Slow tool execution", { toolCallId: "call_123", durationMs: 5000 });
+ * ```
+ */
+export interface AgentLogger {
+    debug(message: string, data?: Record<string, unknown>): void;
+    info(message: string, data?: Record<string, unknown>): void;
+    warn(message: string, data?: Record<string, unknown>): void;
+    error(message: string, data?: Record<string, unknown>): void;
+    /** Create a child logger with additional context */
+    child(extra: {
+        component?: string;
+        turnId?: number;
+        toolCallId?: string;
+    }): AgentLogger;
+    /** Measure duration of an async operation */
+    measure<T>(label: string, fn: () => Promise<T>, data?: Record<string, unknown>): Promise<T>;
+}
+/**
+ * Create a new AgentLogger instance.
+ */
+export declare function createLogger(config?: LoggerConfig): AgentLogger;
+/**
+ * No-op logger that discards all output.
+ * Useful for tests or when logging is disabled.
+ */
+export declare const noopLogger: AgentLogger;

package/dist/core/platform/utils/logger.js

@@ -0,0 +1 @@
+var h=Object.defineProperty;var o=(r,e)=>h(r,"name",{value:e,configurable:!0});const a={debug:0,info:1,warn:2,error:3};function f(r){return JSON.stringify(r)}o(f,"formatLogEntry");function d(r){const e=f(r);r.level==="error"||r.level==="warn"?console.error(e):console.log(e)}o(d,"defaultHandler");class l{static{o(this,"LoggerImpl")}_config;_extra={};constructor(e={}){this._config={level:e.level??"info",sessionId:e.sessionId,component:e.component,handler:e.handler}}debug(e,n){this._log("debug",e,n)}info(e,n){this._log("info",e,n)}warn(e,n){this._log("warn",e,n)}error(e,n){this._log("error",e,n)}child(e){return new l({level:this._config.level,sessionId:this._config.sessionId,component:e.component??this._config.component,handler:this._config.handler})._withExtra(e)}async measure(e,n,c){const t=performance.now();try{const s=await n(),i=Math.round(performance.now()-t);return this._log("info",`${e} completed`,{...c,durationMs:i}),s}catch(s){const i=Math.round(performance.now()-t);throw this._log("error",`${e} failed`,{...c,durationMs:i,error:s instanceof Error?s.message:String(s)}),s}}_withExtra(e){return this._extra=e,this}_log(e,n,c){if(a[e]<a[this._config.level])return;const t={timestamp:new Date().toISOString(),level:e,message:n,sessionId:this._config.sessionId,component:this._config.component,...this._extra,...c??{}};for(const i of Object.keys(t))t[i]===void 0&&delete t[i];(this._config.handler??d)(t)}}function _(r){return new l(r)}o(_,"createLogger");const g={debug:o(()=>{},"debug"),info:o(()=>{},"info"),warn:o(()=>{},"warn"),error:o(()=>{},"error"),child:o(()=>g,"child"),measure:o((r,e)=>e(),"measure")};export{_ as createLogger,f as formatLogEntry,g as noopLogger};