@gaunt-sloth/core 2.0.0-alpha.2 → 2.0.0-alpha.21

package/dist/core/types.d.ts

@@ -1,4 +1,5 @@
 import type { GthConfig } from '#src/config.js';
+import type { ShellSafetyVerdict } from '#src/core/shell/judge.js';
 import type { BaseMessage } from '@langchain/core/messages';
 import type { RunnableConfig } from '@langchain/core/runnables';
 import type { StructuredToolInterface } from '@langchain/core/tools';
@@ -21,6 +22,23 @@ export declare enum StatusLevel {
     STREAM = 6
 }
 export type GthCommand = 'ask' | 'pr' | 'review' | 'chat' | 'code' | 'api' | 'exec';
+/**
+ * GS2-16 — per-run analytics harvested from a finished agent turn, threaded into the opt-in
+ * history recorder ({@link recordSessionSafe}) so `gth insights` reports real numbers instead of
+ * zeros. All fields are best-effort: token counts are only present when the provider actually
+ * reported `usage_metadata` (otherwise omitted so the recorder stores NULL and the insights
+ * formatter suppresses the misleading `0`), and `tools` lists the names of tools invoked during
+ * the run (deduplicated, order-insensitive). There is no `costUsd` — cost requires a reliable
+ * price table this project does not carry, so it is deliberately never invented here.
+ */
+export interface GthRunStats {
+    /** Total prompt/input tokens across the run's LLM calls, when the provider reported usage. */
+    tokensInput?: number;
+    /** Total completion/output tokens across the run's LLM calls, when the provider reported usage. */
+    tokensOutput?: number;
+    /** Names of tools invoked during the run (deduplicated); empty when no tools were used. */
+    tools: string[];
+}
 /**
  * Typed events emitted by the agent's {@link GthAgentInterface#streamWithEvents} path.
  * This is the renderer contract shared by every consumer of an agent run — the AG-UI
@@ -48,10 +66,45 @@ export type AgentStreamEvent = {
 } | {
     type: 'tool_end';
     id: string;
+} | {
+    /**
+     * TUI-C17 — one live output chunk from an EXECUTING tool (a custom/dev toolkit child
+     * process's stdout/stderr, or its "Executing …" announcement), surfaced through the managed
+     * event stream instead of raw `process.stdout` so a renderer (the Ink TUI) can fold it into
+     * its view-model. Emitted by the tool-output channel merge
+     * (see `core/toolOutputChannel.js#mergeToolOutputIntoEvents`), NOT by `processEventStream`
+     * itself — consumers that don't opt into the merge (e.g. the AG-UI SSE encoder) never see it
+     * and the toolkits keep writing to stdout for them (today's headless behaviour).
+     */
+    type: 'tool_output';
+    /**
+     * The tool call this chunk belongs to (LangChain's `ToolRunnableConfig.toolCall.id`,
+     * threaded through the toolkits), so a renderer can nest output under the exact call —
+     * TUI-C30 consumes this for per-call output previews. Optional only defensively: absent
+     * when the executing framework did not supply a tool call, in which case consumers should
+     * fall back to `name` attribution.
+     */
+    id?: string;
+    /** The gth tool name (e.g. `run_shell_command`, a custom tool's name). Always known. */
+    name: string;
+    /** One verbatim streamed chunk of the child's stdout/stderr (or the notice text). */
+    chunk: string;
+    /**
+     * True when this chunk is the "🔧 Executing …" announcement rather than child output, so
+     * a richer renderer (TUI-C30) can style or strip it when previewing raw output lines.
+     */
+    isNotice?: boolean;
 } | {
     type: 'tool_result';
     id: string;
     content: string;
+    /**
+     * True when the underlying `ToolMessage.status` is `'error'` (LangChain's real
+     * tool-result error signal). Absent/undefined means success — consumers must not
+     * sniff the result text to infer failure. Optional for backward compatibility with
+     * producers that predate the field.
+     */
+    isError?: boolean;
 };
 /**
  * The minimal structural surface of a compiled LangGraph agent that the shared agent
@@ -66,7 +119,61 @@ export interface GthCompiledGraph {
         messages: BaseMessage[];
     }>;
     stream(input: any, config?: any): Promise<IterableReadableStream<any>>;
+    /**
+     * Read the checkpointed graph state for a thread. Present on LangGraph compiled graphs
+     * (both `createAgent` and `createDeepAgent`); used to detect a graph suspended on a
+     * human-in-the-loop `interrupt()` (its pending {@link PendingToolInterrupt} lives in
+     * `state.tasks[].interrupts[].value`). Optional because the structural surface predates it.
+     */
+    getState?(config: RunnableConfig): Promise<any>;
+}
+/**
+ * A single tool call a human-in-the-loop interrupt is waiting on, surfaced from the
+ * suspended graph state so a consumer (the interactive session) can render an approve/reject
+ * prompt. Mirrors LangChain's HITL `ActionRequest` (tool name + the args it would run with).
+ */
+export interface PendingToolInterrupt {
+    name: string;
+    args: Record<string, unknown>;
+    /**
+     * EXT-10 — when the LLM-as-judge safety gate escalated this `run_shell_command` to the human
+     * (rather than auto-approving it), the judge's verdict is attached here so the approval surface
+     * can show a "safety judge flagged: <reason>" notice. Absent when the judge is disabled (the
+     * default) or when the command reached the human without going through the judge.
+     */
+    safetyVerdict?: ShellSafetyVerdict;
 }
+/**
+ * Persistence scope for an `approve` decision (EXT-9 Tier-2 allow-list ergonomics):
+ * - `once`    — run this single invocation only; remember nothing (the default).
+ * - `session` — remember the command's classified prefix for the life of this runner
+ *   instance, so flag-variants of the same operation auto-approve without re-prompting.
+ * - `always`  — additionally persist the prefix to the project allow-list
+ *   (`.gsloth/.gsloth-settings/shell-allowlist.json`) so it survives across runs.
+ */
+export type ToolApprovalScope = 'once' | 'session' | 'always';
+/**
+ * A consumer-supplied decision on a {@link PendingToolInterrupt}: approve runs the tool,
+ * reject feeds the model a tool-rejected message (with the optional reason).
+ *
+ * `approve` carries an optional {@link ToolApprovalScope}; when absent it means `once`
+ * (backward compatible — a bare `{ type: 'approve' }` still type-checks and behaves as
+ * a single-shot approval that persists nothing).
+ */
+export type ToolApprovalDecision = {
+    type: 'approve';
+    scope?: ToolApprovalScope;
+} | {
+    type: 'reject';
+    message?: string;
+};
+/**
+ * Callback the {@link GthAgentRunner} invokes when a run suspends on a tool-approval
+ * interrupt, once per pending tool call. Returns the human's decision. When no handler is
+ * wired (e.g. a non-interactive run), the runner defaults to reject so a run can never
+ * silently hang or auto-approve.
+ */
+export type ToolApprovalCallback = (pending: PendingToolInterrupt) => Promise<ToolApprovalDecision> | ToolApprovalDecision;
 export interface GthAgentInterface {
     init(command: GthCommand | undefined, configIn: GthConfig, checkpointSaver?: BaseCheckpointSaver | undefined): Promise<void>;
     invoke(messages: Message[], runConfig: RunnableConfig): Promise<string>;
@@ -80,6 +187,31 @@ export interface GthAgentInterface {
     streamWithEvents(messages: Message[], runConfig: RunnableConfig, signal?: AbortSignal): AsyncGenerator<AgentStreamEvent>;
     /** Resume a graph suspended via `interrupt()` with the supplied value. */
     streamWithEventsResume(resumeValue: unknown, runConfig: RunnableConfig, queuedMessages?: BaseMessage[], signal?: AbortSignal): AsyncGenerator<AgentStreamEvent>;
+    /**
+     * Resume a graph suspended on a human-in-the-loop `interrupt()` and stream the continuation
+     * as text (the string counterpart to {@link streamWithEventsResume}, for the readline path).
+     * Optional: only implemented by agents that support tool-approval interrupts.
+     */
+    streamResume?(resumeValue: unknown, runConfig: RunnableConfig): Promise<IterableReadableStream<string>>;
+    /**
+     * Inspect the checkpointed state for the thread and return any tool calls currently pending
+     * human approval (empty when the run completed normally). Optional: only implemented by
+     * agents whose graph exposes `getState`. Used by {@link GthAgentRunner} to drive the
+     * approve/reject confirmation loop.
+     */
+    getPendingToolInterrupts?(runConfig: RunnableConfig): Promise<PendingToolInterrupt[]>;
+    /**
+     * GS2-16 — reset the per-run analytics accumulator so the NEXT turn's token/tool totals start
+     * from zero. Called by {@link GthAgentRunner} at each turn boundary (the runner is reused across
+     * turns in interactive sessions). Optional: agents that don't collect stats simply omit it.
+     */
+    resetRunStats?(): void;
+    /**
+     * GS2-16 — the analytics harvested from the run(s) since the last {@link resetRunStats}. Used by
+     * the runner to thread token/tool data into the opt-in history recorder. Optional; when absent
+     * the runner records no analytics for that turn. Reading must never throw.
+     */
+    getRunStats?(): GthRunStats;
     cleanup?(): Promise<void>;
 }
 /**
@@ -93,9 +225,50 @@ export type ToolsResolver = (config: GthConfig, command?: GthCommand) => Promise
 export type ToolsCleanup = () => Promise<void>;
 export type MiddlewareResolver = (middleware: any[] | undefined, config: GthConfig) => Promise<any[]>;
 export type MiddlewareCleanup = () => Promise<void>;
+/**
+ * EXT-32 — one connected MCP server's discovery `instructions` string (from its MCP `initialize`
+ * handshake), paired with the server name it came from. Captured once during tool resolution and
+ * reused: injected (fenced + per-server-labelled) into the composed system prompt, and available
+ * for [[TUI-C20]]'s MCP debug tab to render the same captured text. Only servers that actually
+ * supplied non-empty instructions appear here.
+ */
+export interface McpServerInstruction {
+    /** The configured MCP server name (the key under `config.mcpServers`). */
+    server: string;
+    /** The server-provided instructions text (trimmed, non-empty). */
+    instructions: string;
+}
+/**
+ * A per-server MCP connection failure captured during the most recent {@link ToolsResolver} call.
+ * Recorded when a configured MCP server can't be reached (connection/handshake/auth error), so the
+ * failure — otherwise a transient `displayWarning` that scrolls away the moment the Ink TUI takes
+ * over the screen — can be re-surfaced persistently in the chrome AND named in the /debug MCP tab
+ * (which renders per configured server and would otherwise show only a bare "no tools" line, with
+ * no hint that the server never connected). Mirrors {@link McpServerInstruction}.
+ */
+export interface McpConnectionFailure {
+    /** The configured MCP server name (the key under `config.mcpServers`). */
+    server: string;
+    /** A concise, human-readable reason (the underlying connection error's message). */
+    reason: string;
+}
 export interface AgentResolvers {
     resolveTools?: ToolsResolver;
     cleanupTools?: ToolsCleanup;
     resolveMiddleware?: MiddlewareResolver;
     cleanupMiddleware?: MiddlewareCleanup;
+    /**
+     * EXT-32 — the per-server MCP discovery instructions captured during the most recent
+     * {@link ToolsResolver} call (empty when no MCP servers are configured or none supplied
+     * instructions). Optional: resolvers without MCP support simply omit it, and the prompt
+     * composition treats an absent accessor as "no instructions" (no MCP section is emitted).
+     */
+    getMcpServerInstructions?(): McpServerInstruction[];
+    /**
+     * The per-server MCP connection failures captured during the most recent {@link ToolsResolver}
+     * call (empty when every configured server connected, or none is configured). Optional: resolvers
+     * without MCP support omit it, and callers treat an absent accessor as "no failures". Read by the
+     * TUI to surface a persistent notice and to annotate the /debug MCP tab.
+     */
+    getMcpConnectionFailures?(): McpConnectionFailure[];
 }

package/dist/core/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/core/types.ts"],"names":[],"mappings":"AAWA;;;;GAIG;AACH,MAAM,CAAN,IAAY,WAQX;AARD,WAAY,WAAW;IACrB,+CAAS,CAAA;IACT,6CAAQ,CAAA;IACR,mDAAW,CAAA;IACX,mDAAW,CAAA;IACX,mDAAW,CAAA;IACX,+CAAS,CAAA;IACT,iDAAU,CAAA;AACZ,CAAC,EARW,WAAW,KAAX,WAAW,QAQtB"}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/core/types.ts"],"names":[],"mappings":"AAYA;;;;GAIG;AACH,MAAM,CAAN,IAAY,WAQX;AARD,WAAY,WAAW;IACrB,+CAAS,CAAA;IACT,6CAAQ,CAAA;IACR,mDAAW,CAAA;IACX,mDAAW,CAAA;IACX,mDAAW,CAAA;IACX,+CAAS,CAAA;IACT,iDAAU,CAAA;AACZ,CAAC,EARW,WAAW,KAAX,WAAW,QAQtB"}

package/dist/history/historyFormat.d.ts

@@ -0,0 +1,28 @@
+/**
+ * @packageDocumentation
+ * GS2-7 (B20) — pure, presentation-only formatters for the history surfaces.
+ *
+ * Shared by the `gth history` / `gth insights` CLI commands AND the `/history` `/search`
+ * `/insights` TUI slash commands so both render identically and both are unit-testable without a
+ * DB or a terminal. Every function is a pure `data -> string[]` transform (one display line per
+ * element); no I/O, no colour codes.
+ */
+import type { ConversationSummary, HistoryInsights, SessionRecord, SessionSearchResult } from '#src/history/historyStore.js';
+/**
+ * Render FTS search hits: a header line per hit plus its snippet (or a prompt preview when the
+ * snippet is empty). Returns a friendly single line when there are none.
+ */
+export declare function formatSearchResults(results: SessionSearchResult[]): string[];
+/**
+ * GS2-19 — render a conversation-grained listing: one header + last-turn preview per conversation.
+ * The header carries the count / timespan / last message that make the conversation the top-level
+ * unit (`gth history list`), replacing the old flat per-turn list.
+ */
+export declare function formatConversationList(conversations: ConversationSummary[]): string[];
+/**
+ * GS2-19 — render one conversation's full thread (all turns in order) for `gth history show <id>`.
+ * Each turn shows its prompt and response preview so a search hit can be expanded into context.
+ */
+export declare function formatConversationThread(turns: SessionRecord[]): string[];
+/** Render the analytics summary: totals, top tools, per-command breakdown. */
+export declare function formatInsightsSummary(insights: HistoryInsights): string[];

package/dist/history/historyFormat.js

@@ -0,0 +1,127 @@
+/** Collapse whitespace and clip to `max` chars with an ellipsis, for one-line previews. */
+function oneLine(text, max = 80) {
+    const s = (text ?? '').replace(/\s+/g, ' ').trim();
+    return s.length > max ? s.slice(0, max - 1) + '…' : s;
+}
+/** A compact `#id  <ts>  [command] model  (conversation #cid)` header line for one turn. */
+function headerLine(r) {
+    const parts = [`#${r.id}`, r.ts];
+    if (r.command)
+        parts.push(`[${r.command}]`);
+    if (r.model)
+        parts.push(r.model);
+    // GS2-19: a search hit resolves to the conversation it belongs to, so the reader can pull up the
+    // whole thread (`gth history show <cid>`). Older rows migrated from GS2-7 always have one now.
+    if (r.conversationId != null)
+        parts.push(`(conversation #${r.conversationId})`);
+    return parts.join('  ');
+}
+/**
+ * Render FTS search hits: a header line per hit plus its snippet (or a prompt preview when the
+ * snippet is empty). Returns a friendly single line when there are none.
+ */
+export function formatSearchResults(results) {
+    if (results.length === 0)
+        return ['No matching sessions found.'];
+    const lines = [];
+    for (const r of results) {
+        lines.push(headerLine(r));
+        const detail = r.snippet && r.snippet.trim().length > 0 ? r.snippet : r.prompt;
+        const preview = oneLine(detail, 100);
+        if (preview)
+            lines.push(`    ${preview}`);
+    }
+    return lines;
+}
+/**
+ * GS2-19 — render a conversation-grained listing: one header + last-turn preview per conversation.
+ * The header carries the count / timespan / last message that make the conversation the top-level
+ * unit (`gth history list`), replacing the old flat per-turn list.
+ */
+export function formatConversationList(conversations) {
+    if (conversations.length === 0) {
+        return [
+            'No conversations recorded yet. Enable history with `history.enabled: true` in your config.',
+        ];
+    }
+    const lines = [];
+    for (const c of conversations) {
+        const parts = [`#${c.id}`];
+        // Timespan across the conversation's turns; a 1-turn (or not-yet-started) conversation collapses
+        // to a single instant, so show one timestamp rather than an `a → a` range.
+        if (c.firstTs && c.lastTs && c.firstTs !== c.lastTs) {
+            parts.push(`${c.firstTs} → ${c.lastTs}`);
+        }
+        else {
+            parts.push(c.lastTs ?? c.firstTs ?? c.startedTs);
+        }
+        if (c.command)
+            parts.push(`[${c.command}]`);
+        if (c.model)
+            parts.push(c.model);
+        parts.push(`(${c.turnCount} ${c.turnCount === 1 ? 'turn' : 'turns'})`);
+        lines.push(parts.join('  '));
+        const preview = oneLine(c.lastPrompt, 100);
+        if (preview)
+            lines.push(`    ${preview}`);
+    }
+    return lines;
+}
+/**
+ * GS2-19 — render one conversation's full thread (all turns in order) for `gth history show <id>`.
+ * Each turn shows its prompt and response preview so a search hit can be expanded into context.
+ */
+export function formatConversationThread(turns) {
+    if (turns.length === 0)
+        return ['No turns found for that conversation.'];
+    const lines = [];
+    turns.forEach((t, i) => {
+        const header = t.ts ? `Turn ${i + 1}  ${t.ts}` : `Turn ${i + 1}`;
+        lines.push(header);
+        const prompt = oneLine(t.prompt, 200);
+        if (prompt)
+            lines.push(`  > ${prompt}`);
+        const response = oneLine(t.response, 200);
+        if (response)
+            lines.push(`    ${response}`);
+    });
+    return lines;
+}
+/** Render the analytics summary: totals, top tools, per-command breakdown. */
+export function formatInsightsSummary(insights) {
+    if (insights.sessionCount === 0) {
+        return [
+            'No sessions recorded yet. Enable history with `history.enabled: true` in your config.',
+        ];
+    }
+    const lines = [];
+    lines.push(`Sessions: ${insights.sessionCount}`);
+    if (insights.firstTs && insights.lastTs) {
+        lines.push(`Span: ${insights.firstTs} → ${insights.lastTs}`);
+    }
+    // GS2-16: only surface the token/cost/top-tool lines when there is real data behind them.
+    // Older records (and providers that report no usage) leave these zero/empty; printing
+    // `Tokens: 0` / `$0.0000` / `(none recorded)` reads as "the run used nothing", which is
+    // misleading, so omit the line entirely instead. Sessions / Span / By-command always show.
+    if (insights.totalTokens > 0) {
+        lines.push(`Tokens: ${insights.totalTokens} total ` +
+            `(${insights.totalTokensInput} in / ${insights.totalTokensOutput} out)`);
+    }
+    // Cost is only ever recorded when a reliable price was available (the recorder never invents
+    // one), so a positive total is the signal that a cost line is meaningful.
+    if (insights.totalCostUsd > 0) {
+        lines.push(`Estimated cost: $${insights.totalCostUsd.toFixed(4)}`);
+    }
+    if (insights.perCommand.length > 0) {
+        lines.push('By command:');
+        for (const c of insights.perCommand)
+            lines.push(`  ${c.command}: ${c.count}`);
+    }
+    if (insights.topTools.length > 0) {
+        lines.push('Top tools:');
+        for (const t of insights.topTools)
+            lines.push(`  ${t.tool}: ${t.count}`);
+    }
+    return lines;
+}
+//# sourceMappingURL=historyFormat.js.map

package/dist/history/historyFormat.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"historyFormat.js","sourceRoot":"","sources":["../../src/history/historyFormat.ts"],"names":[],"mappings":"AAgBA,2FAA2F;AAC3F,SAAS,OAAO,CAAC,IAAwB,EAAE,GAAG,GAAG,EAAE;IACjD,MAAM,CAAC,GAAG,CAAC,IAAI,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC;IACnD,OAAO,CAAC,CAAC,MAAM,GAAG,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,GAAG,CAAC,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;AACxD,CAAC;AAED,4FAA4F;AAC5F,SAAS,UAAU,CAAC,CAAsB;IACxC,MAAM,KAAK,GAAG,CAAC,IAAI,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,CAAC;IACjC,IAAI,CAAC,CAAC,OAAO;QAAE,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,OAAO,GAAG,CAAC,CAAC;IAC5C,IAAI,CAAC,CAAC,KAAK;QAAE,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC;IACjC,iGAAiG;IACjG,+FAA+F;IAC/F,IAAI,CAAC,CAAC,cAAc,IAAI,IAAI;QAAE,KAAK,CAAC,IAAI,CAAC,kBAAkB,CAAC,CAAC,cAAc,GAAG,CAAC,CAAC;IAChF,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC1B,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,mBAAmB,CAAC,OAA8B;IAChE,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,CAAC,6BAA6B,CAAC,CAAC;IACjE,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,KAAK,MAAM,CAAC,IAAI,OAAO,EAAE,CAAC;QACxB,KAAK,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC;QAC1B,MAAM,MAAM,GAAG,CAAC,CAAC,OAAO,IAAI,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC;QAC/E,MAAM,OAAO,GAAG,OAAO,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;QACrC,IAAI,OAAO;YAAE,KAAK,CAAC,IAAI,CAAC,OAAO,OAAO,EAAE,CAAC,CAAC;IAC5C,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,sBAAsB,CAAC,aAAoC;IACzE,IAAI,aAAa,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC/B,OAAO;YACL,4FAA4F;SAC7F,CAAC;IACJ,CAAC;IACD,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,KAAK,MAAM,CAAC,IAAI,aAAa,EAAE,CAAC;QAC9B,MAAM,KAAK,GAAG,CAAC,IAAI,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;QAC3B,iGAAiG;QACjG,2EAA2E;QAC3E,IAAI,CAAC,CAAC,OAAO,IAAI,CAAC,CAAC,MAAM,IAAI,CAAC,CAAC,OAAO,KAAK,CAAC,CAAC,MAAM,EAAE,CAAC;YACpD,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,OAAO,MAAM,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC;QAC3C,CAAC;aAAM,CAAC;YACN,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,IAAI,CAAC,CAAC,OAAO,IAAI,CAAC,CAAC,SAAS,CAAC,CAAC;QACnD,CAAC;QACD,IAAI,CAAC,CAAC,OAAO;YAAE,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,OAAO,GAAG,CAAC,CAAC;QAC5C,IAAI,CAAC,CAAC,KAAK;YAAE,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC;QACjC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,SAAS,IAAI,CAAC,CAAC,SAAS,KAAK,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,OAAO,GAAG,CAAC,CAAC;QACvE,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC;QAC7B,MAAM,OAAO,GAAG,OAAO,CAAC,CAAC,CAAC,UAAU,EAAE,GAAG,CAAC,CAAC;QAC3C,IAAI,OAAO;YAAE,KAAK,CAAC,IAAI,CAAC,OAAO,OAAO,EAAE,CAAC,CAAC;IAC5C,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,wBAAwB,CAAC,KAAsB;IAC7D,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,CAAC,uCAAuC,CAAC,CAAC;IACzE,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE;QACrB,MAAM,MAAM,GAAG,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC;QACjE,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;QACnB,MAAM,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;QACtC,IAAI,MAAM;YAAE,KAAK,CAAC,IAAI,CAAC,OAAO,MAAM,EAAE,CAAC,CAAC;QACxC,MAAM,QAAQ,GAAG,OAAO,CAAC,CAAC,CAAC,QAAQ,EAAE,GAAG,CAAC,CAAC;QAC1C,IAAI,QAAQ;YAAE,KAAK,CAAC,IAAI,CAAC,OAAO,QAAQ,EAAE,CAAC,CAAC;IAC9C,CAAC,CAAC,CAAC;IACH,OAAO,KAAK,CAAC;AACf,CAAC;AAED,8EAA8E;AAC9E,MAAM,UAAU,qBAAqB,CAAC,QAAyB;IAC7D,IAAI,QAAQ,CAAC,YAAY,KAAK,CAAC,EAAE,CAAC;QAChC,OAAO;YACL,uFAAuF;SACxF,CAAC;IACJ,CAAC;IACD,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,KAAK,CAAC,IAAI,CAAC,aAAa,QAAQ,CAAC,YAAY,EAAE,CAAC,CAAC;IACjD,IAAI,QAAQ,CAAC,OAAO,IAAI,QAAQ,CAAC,MAAM,EAAE,CAAC;QACxC,KAAK,CAAC,IAAI,CAAC,SAAS,QAAQ,CAAC,OAAO,MAAM,QAAQ,CAAC,MAAM,EAAE,CAAC,CAAC;IAC/D,CAAC;IACD,0FAA0F;IAC1F,sFAAsF;IACtF,wFAAwF;IACxF,2FAA2F;IAC3F,IAAI,QAAQ,CAAC,WAAW,GAAG,CAAC,EAAE,CAAC;QAC7B,KAAK,CAAC,IAAI,CACR,WAAW,QAAQ,CAAC,WAAW,SAAS;YACtC,IAAI,QAAQ,CAAC,gBAAgB,SAAS,QAAQ,CAAC,iBAAiB,OAAO,CAC1E,CAAC;IACJ,CAAC;IACD,6FAA6F;IAC7F,0EAA0E;IAC1E,IAAI,QAAQ,CAAC,YAAY,GAAG,CAAC,EAAE,CAAC;QAC9B,KAAK,CAAC,IAAI,CAAC,oBAAoB,QAAQ,CAAC,YAAY,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;IACrE,CAAC;IAED,IAAI,QAAQ,CAAC,UAAU,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACnC,KAAK,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC;QAC1B,KAAK,MAAM,CAAC,IAAI,QAAQ,CAAC,UAAU;YAAE,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,OAAO,KAAK,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC;IAChF,CAAC;IACD,IAAI,QAAQ,CAAC,QAAQ,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACjC,KAAK,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC;QACzB,KAAK,MAAM,CAAC,IAAI,QAAQ,CAAC,QAAQ;YAAE,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,IAAI,KAAK,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC;IAC3E,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC"}

package/dist/history/historyStore.d.ts

@@ -0,0 +1,198 @@
+/** Filename of the global history DB inside `~/.gsloth`. */
+export declare const HISTORY_DB_FILENAME = "history.db";
+/** A single persisted session record (all analytics fields optional; populated when available). */
+export interface SessionRecord {
+    /**
+     * GS2-19 — the parent conversation this turn belongs to. When omitted, {@link HistoryStore.record}
+     * opens a fresh single-turn conversation for the row (so a bare single-shot run = a 1-turn
+     * conversation). Interactive sessions {@link HistoryStore.openConversation | open} one conversation
+     * up-front and pass its id here on every turn, grouping the whole chat under one conversation.
+     */
+    conversationId?: number;
+    /** ISO-8601 timestamp; defaults to now when omitted. */
+    ts?: string;
+    /** Project / working directory the run happened in. */
+    project?: string;
+    /** Originating command (ask/chat/code/exec/…). */
+    command?: string;
+    /** Human-readable model/provider label. */
+    model?: string;
+    /** The user prompt / source that started the run (full-text indexed). */
+    prompt?: string;
+    /** The final assistant response text (full-text indexed). */
+    response?: string;
+    /** Prompt/input token count, when known. */
+    tokensInput?: number;
+    /** Completion/output token count, when known. */
+    tokensOutput?: number;
+    /** Estimated cost in USD, when known. */
+    costUsd?: number;
+    /** Names of tools invoked during the run, when known. */
+    tools?: string[];
+    /** Wall-clock duration of the run in milliseconds, when known. */
+    durationMs?: number;
+}
+/** A search hit: the stored record plus its id and a highlighted snippet. */
+export interface SessionSearchResult extends SessionRecord {
+    id: number;
+    ts: string;
+    /** FTS5 snippet around the match (may be empty). */
+    snippet: string;
+}
+/**
+ * GS2-19 — metadata for a conversation (a group of turns). Passed to
+ * {@link HistoryStore.openConversation} at interactive-session start.
+ */
+export interface ConversationMeta {
+    /** ISO-8601 start timestamp; defaults to now when omitted. */
+    ts?: string;
+    /** Project / working directory the conversation happened in. */
+    project?: string;
+    /** Originating command (chat/code/ask/exec/…). */
+    command?: string;
+    /** Human-readable model/provider label. */
+    model?: string;
+}
+/**
+ * GS2-19 — a conversation-grained listing row: the conversation's metadata plus the aggregate of
+ * its turns (how many, the timespan they cover, and a preview of the last one). This is the
+ * top-level unit `gth history list` shows, in place of isolated per-turn rows.
+ */
+export interface ConversationSummary {
+    id: number;
+    /** When the conversation was opened. */
+    startedTs: string;
+    project?: string;
+    command?: string;
+    model?: string;
+    /** Number of turns recorded under this conversation (0 for a conversation with no turns). */
+    turnCount: number;
+    /** Timestamp of the first / last turn, when any turns exist. */
+    firstTs?: string;
+    lastTs?: string;
+    /** Prompt / response of the most recent turn (a one-line preview source). */
+    lastPrompt?: string;
+    lastResponse?: string;
+}
+/** Aggregate analytics over the whole store (local only). */
+export interface HistoryInsights {
+    sessionCount: number;
+    totalTokensInput: number;
+    totalTokensOutput: number;
+    totalTokens: number;
+    totalCostUsd: number;
+    /** Tool-name → invocation count, most-used first. */
+    topTools: {
+        tool: string;
+        count: number;
+    }[];
+    /** Command → run count, most-used first. */
+    perCommand: {
+        command: string;
+        count: number;
+    }[];
+    firstTs?: string;
+    lastTs?: string;
+}
+/** Options for opening a store. */
+export interface OpenHistoryStoreOptions {
+    /**
+     * When false (the default for read-only callers), a missing DB file yields `null` instead of
+     * creating an empty database. Read commands pass `create: false` so `gth insights` never
+     * materialises a DB as a side effect; the recorder passes `create: true`.
+     */
+    create?: boolean;
+}
+/**
+ * Turn arbitrary user text into a safe FTS5 MATCH expression: each whitespace-separated token is
+ * wrapped as a quoted string and AND-ed together. This avoids FTS5 syntax errors from stray
+ * operators (`AND`, `*`, `:`, parentheses, unbalanced quotes) in a user's query while still
+ * matching all of their words.
+ */
+export declare function toFtsMatchQuery(query: string): string;
+/**
+ * A thin, fail-soft wrapper over a `node:sqlite` connection holding the session history.
+ *
+ * Obtain one via {@link openHistoryStore} (which returns `null` if the DB can't be opened). Every
+ * method is defensive: on any SQLite error it returns a safe empty/zero result rather than
+ * throwing, so callers on a run's hot path never have to guard.
+ */
+export declare class HistoryStore {
+    private db;
+    private constructor();
+    /**
+     * Open (and lazily initialise) the store at `dbPath`. Returns `null` on any failure — a missing
+     * file when `create` is false, an unopenable/locked/corrupt DB, or a schema-init error — so the
+     * caller can simply skip history without a try/catch.
+     */
+    static open(dbPath: string, options?: OpenHistoryStoreOptions): HistoryStore | null;
+    private initSchema;
+    /**
+     * GS2-19 — in-place, idempotent upgrade of a pre-existing GS2-7 DB (flat `sessions` rows, no
+     * grouping) to the conversation-grained model. Runs on every open (including read-only `list` /
+     * `search` opens, which open the file read-write): it adds the `conversation_id` column if an
+     * older `sessions` table lacks it, then back-fills each ungrouped turn into its own 1-turn
+     * conversation. After the first pass there are no ungrouped rows, so it is a cheap no-op.
+     *
+     * Fully fail-soft: a migration hiccup is swallowed here rather than nulling the store, so reads
+     * still work against whatever is already there and new turns just fall back to fresh 1-turn
+     * conversations. Never throws.
+     */
+    private migrate;
+    /**
+     * GS2-19 — open a new conversation and return its id (or `null` on any error). Interactive
+     * sessions call this once at start, then pass the id on every {@link record} so all the session's
+     * turns group under it. A single-shot run does not need this: {@link record} opens a 1-turn
+     * conversation itself when no `conversationId` is supplied.
+     */
+    openConversation(meta?: ConversationMeta): number | null;
+    /**
+     * Persist one session and its full-text index entry. Returns the new row id, or `null` on any
+     * error (the run continues regardless). The two inserts run in a transaction so a failure can't
+     * leave the FTS index out of sync with the base table.
+     */
+    record(rec: SessionRecord): number | null;
+    /**
+     * Full-text search over prompt/response/command/project, best match first (FTS5 `rank`). User
+     * text is sanitised via {@link toFtsMatchQuery}; an empty or all-punctuation query returns `[]`.
+     * Any SQLite error yields `[]` (fail-soft).
+     */
+    search(query: string, limit?: number): SessionSearchResult[];
+    /** Most recent sessions, newest first. Fail-soft ([] on error). */
+    listRecent(limit?: number): SessionSearchResult[];
+    /**
+     * GS2-19 — conversations newest-first, each with its turn count, timespan, and a preview of the
+     * last turn. This is the top-level unit for `gth history list` (the turn-grained {@link listRecent}
+     * remains for callers that want raw turns). Fail-soft ([] on error).
+     *
+     * Empty conversations are **excluded** (`HAVING COUNT(s.id) > 0`): a session opens its conversation
+     * at start (before any turn), so one that exits with zero turns would otherwise show as a
+     * contentless `turnCount: 0` row. The LEFT JOIN still keeps every conversation that has ≥1 turn —
+     * including back-filled 1-turn conversations, whose single turn satisfies the HAVING.
+     */
+    listConversations(limit?: number): ConversationSummary[];
+    /**
+     * GS2-19 — all turns of one conversation in chronological (insert) order, so a search hit can be
+     * expanded into the whole thread it belonged to. Fail-soft ([] on error / unknown id).
+     */
+    getConversationThread(conversationId: number): SessionRecord[];
+    /**
+     * Aggregate token/cost totals, a top-tool tally, and a per-command breakdown over the whole
+     * store. Tool tallying reads each row's JSON `tools` array in JS (robust to nulls). Fail-soft:
+     * returns a zeroed summary on any error.
+     */
+    insights(topN?: number): HistoryInsights;
+    /** Close the underlying connection (fail-soft). */
+    close(): void;
+}
+/**
+ * Resolve the on-disk path of the history DB. Honors an explicit `dbPath` (from `history.dbPath`
+ * or a `--db` flag); otherwise the global `~/.gsloth/history.db`. When `dbPath` is omitted and
+ * `ensureDir` is true, the global dir is created so the recorder can write.
+ */
+export declare function resolveHistoryDbPath(dbPath?: string, ensureDir?: boolean): string;
+/**
+ * Fail-soft open of the history store. Returns `null` (never throws) when the DB can't be opened
+ * or, for read-only callers (`create: false`, the default), when the file does not yet exist.
+ */
+export declare function openHistoryStore(dbPath: string, options?: OpenHistoryStoreOptions): HistoryStore | null;