@gaunt-sloth/core 2.0.0-alpha.10 → 2.0.0-alpha.11

package/dist/config/types.d.ts

@@ -442,7 +442,7 @@ export interface LLMConfig extends Record<string, unknown> {
     configuration: Record<string, unknown>;
     apiKeyEnvironmentVariable?: string;
 }
-export declare const availableDefaultConfigs: readonly ["vertexai", "anthropic", "groq", "deepseek", "openai", "google-genai", "xai", "openrouter", "ollama"];
+export declare const availableDefaultConfigs: readonly ["vertexai", "anthropic", "groq", "deepseek", "openai", "google-genai", "xai", "openrouter", "huggingface", "ollama"];
 export type ConfigType = (typeof availableDefaultConfigs)[number];
 export interface CommandLineConfigOverrides {
     /**

package/dist/config/types.js

@@ -7,6 +7,7 @@ export const availableDefaultConfigs = [
     'google-genai',
     'xai',
     'openrouter',
+    'huggingface',
     'ollama',
 ];
 //# sourceMappingURL=types.js.map

package/dist/config/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/config/types.ts"],"names":[],"mappings":"AA2cA,MAAM,CAAC,MAAM,uBAAuB,GAAG;IACrC,UAAU;IACV,WAAW;IACX,MAAM;IACN,UAAU;IACV,QAAQ;IACR,cAAc;IACd,KAAK;IACL,YAAY;IACZ,QAAQ;CACA,CAAC"}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/config/types.ts"],"names":[],"mappings":"AA2cA,MAAM,CAAC,MAAM,uBAAuB,GAAG;IACrC,UAAU;IACV,WAAW;IACX,MAAM;IACN,UAAU;IACV,QAAQ;IACR,cAAc;IACd,KAAK;IACL,YAAY;IACZ,aAAa;IACb,QAAQ;CACA,CAAC"}

package/dist/constants.d.ts

@@ -36,3 +36,11 @@ export declare const CONFIG_SCHEMA_POINTER = "https://gauntsloth.app/schema/v2/g
  * Lives under `.gsloth/.gsloth-settings/` like other project settings.
  */
 export declare const SHELL_ALLOWLIST_FILE = "shell-allowlist.json";
+/**
+ * The `additionalToolNamePrefix` handed to `MultiServerMCPClient` so every MCP tool name is
+ * namespaced. Combined with `prefixToolNameWithServerName`, the adapter emits tool names shaped
+ * `${MCP_TOOL_NAME_PREFIX}__<serverName>__<toolName>` (the `__` separator is the mcp-adapters
+ * convention). Single-sourced here so the resolver that sets the prefix (EXT-32) and any consumer
+ * that groups tools back by server (the [[TUI-C20]] MCP debug tab) can never silently drift apart.
+ */
+export declare const MCP_TOOL_NAME_PREFIX = "mcp";

package/dist/constants.js

@@ -36,4 +36,12 @@ export const CONFIG_SCHEMA_POINTER = 'https://gauntsloth.app/schema/v2/gsloth-co
  * Lives under `.gsloth/.gsloth-settings/` like other project settings.
  */
 export const SHELL_ALLOWLIST_FILE = 'shell-allowlist.json';
+/**
+ * The `additionalToolNamePrefix` handed to `MultiServerMCPClient` so every MCP tool name is
+ * namespaced. Combined with `prefixToolNameWithServerName`, the adapter emits tool names shaped
+ * `${MCP_TOOL_NAME_PREFIX}__<serverName>__<toolName>` (the `__` separator is the mcp-adapters
+ * convention). Single-sourced here so the resolver that sets the prefix (EXT-32) and any consumer
+ * that groups tools back by server (the [[TUI-C20]] MCP debug tab) can never silently drift apart.
+ */
+export const MCP_TOOL_NAME_PREFIX = 'mcp';
 //# sourceMappingURL=constants.js.map

package/dist/constants.js.map

@@ -1 +1 @@
-{"version":3,"file":"constants.js","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,UAAU,GAAG,SAAS,CAAC;AACpC,MAAM,CAAC,MAAM,mBAAmB,GAAG,kBAAkB,CAAC;AACtD,MAAM,CAAC,MAAM,WAAW,GAAG,cAAc,CAAC;AAC1C,MAAM,CAAC,MAAM,sBAAsB,GAAG,mBAAmB,CAAC;AAC1D,MAAM,CAAC,MAAM,wBAAwB,GAAG,qBAAqB,CAAC;AAC9D,MAAM,CAAC,MAAM,uBAAuB,GAAG,oBAAoB,CAAC;AAC5D,MAAM,CAAC,MAAM,sBAAsB,GAAG,mBAAmB,CAAC;AAC1D,MAAM,CAAC,MAAM,gBAAgB,GAAG,sBAAsB,CAAC;AACvD,MAAM,CAAC,MAAM,kBAAkB,GAAG,uBAAuB,CAAC;AAC1D,MAAM,CAAC,MAAM,2BAA2B,GAAG,mBAAmB,CAAC;AAC/D,MAAM,CAAC,MAAM,oBAAoB,GAAG,mBAAmB,CAAC;AACxD,MAAM,CAAC,MAAM,kBAAkB,GAAG,iBAAiB,CAAC;AACpD,MAAM,CAAC,MAAM,kBAAkB,GAAG,iBAAiB,CAAC;AACpD,MAAM,CAAC,MAAM,kBAAkB,GAAG,iBAAiB,CAAC;AACpD,MAAM,CAAC,MAAM,aAAa,GAAG,WAAW,CAAC;AACzC;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG,4DAA4D,CAAC;AAClG;;;GAGG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG,sBAAsB,CAAC"}
+{"version":3,"file":"constants.js","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,UAAU,GAAG,SAAS,CAAC;AACpC,MAAM,CAAC,MAAM,mBAAmB,GAAG,kBAAkB,CAAC;AACtD,MAAM,CAAC,MAAM,WAAW,GAAG,cAAc,CAAC;AAC1C,MAAM,CAAC,MAAM,sBAAsB,GAAG,mBAAmB,CAAC;AAC1D,MAAM,CAAC,MAAM,wBAAwB,GAAG,qBAAqB,CAAC;AAC9D,MAAM,CAAC,MAAM,uBAAuB,GAAG,oBAAoB,CAAC;AAC5D,MAAM,CAAC,MAAM,sBAAsB,GAAG,mBAAmB,CAAC;AAC1D,MAAM,CAAC,MAAM,gBAAgB,GAAG,sBAAsB,CAAC;AACvD,MAAM,CAAC,MAAM,kBAAkB,GAAG,uBAAuB,CAAC;AAC1D,MAAM,CAAC,MAAM,2BAA2B,GAAG,mBAAmB,CAAC;AAC/D,MAAM,CAAC,MAAM,oBAAoB,GAAG,mBAAmB,CAAC;AACxD,MAAM,CAAC,MAAM,kBAAkB,GAAG,iBAAiB,CAAC;AACpD,MAAM,CAAC,MAAM,kBAAkB,GAAG,iBAAiB,CAAC;AACpD,MAAM,CAAC,MAAM,kBAAkB,GAAG,iBAAiB,CAAC;AACpD,MAAM,CAAC,MAAM,aAAa,GAAG,WAAW,CAAC;AACzC;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG,4DAA4D,CAAC;AAClG;;;GAGG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG,sBAAsB,CAAC;AAE3D;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG,KAAK,CAAC"}

package/dist/core/GthLangChainAgent.js

@@ -3,6 +3,7 @@ import { GthAbstractAgent } from '#src/core/GthAbstractAgent.js';
 import { debugLog, debugLogObject } from '#src/utils/debugUtils.js';
 import { buildSystemMessages, formatToolCalls, readChatPrompt, readCodePrompt, readExecPrompt, } from '#src/utils/llmUtils.js';
 import { getCurrentWorkDir } from '#src/utils/systemUtils.js';
+import { appendOsShellNote, appendCwdNote, appendMcpServerInstructionsNote, } from '#src/utils/systemPromptNotes.js';
 import { isShellCommandFailedError } from '#src/core/shell/ShellCommandFailedError.js';
 import { extractDebugRequestExtras } from '#src/core/debugCapture.js';
 import { AIMessage, ToolMessage } from '@langchain/core/messages';
@@ -176,7 +177,30 @@ export class GthLangChainAgent extends GthAbstractAgent {
                 ? readExecPrompt(this.config)
                 : readChatPrompt(this.config);
         const systemMessages = buildSystemMessages(this.config, modePrompt);
-        const systemPrompt = typeof systemMessages[0]?.content === 'string' ? systemMessages[0].content : undefined;
+        const baseSystemPrompt = typeof systemMessages[0]?.content === 'string' ? systemMessages[0].content : undefined;
+        // GS2-27: in `code` mode append the SHARED code-mode notes the deep backend has always carried
+        // — the real-cwd / path-model note (EXT-13) and the OS + shell-dialect note (EXT-26). Both are
+        // backend-agnostic (the lean backend also exposes `run_shell_command` and runs on the real-fs
+        // cwd), so composing them here closes the deep-only drift that left a lean code session with no
+        // cwd value and no shell-dialect guidance (e.g. on Windows). The deepagents virtual-fs-namespace
+        // notes stay deep-only (lean never runs virtualMode). Same order the deep backend's real-path
+        // branch uses: cwd note first, OS/shell note last. `getCurrentWorkDir()` is already read above
+        // for the status line, so the value is free.
+        const codeNotesPrompt = this.command === 'code'
+            ? appendOsShellNote(appendCwdNote(baseSystemPrompt, getCurrentWorkDir()))
+            : baseSystemPrompt;
+        // EXT-32: inject each connected MCP server's discovery `instructions` (captured during tool
+        // resolution) into the prompt — fenced + per-server-labelled as untrusted server-provided
+        // context. Mode-independent: MCP tools load in every mode, so their usage guidance applies in
+        // every mode (not just `code`). Empty/absent capture (or a resolver without the accessor) adds
+        // nothing. Composed through this shared path so it reaches the lean AND deep backends alike.
+        // When tools are disabled, resolveTools is skipped entirely (no MCP contact), so a REUSED
+        // resolver could still hold a prior run's capture — gate on toolsDisabled so no stale
+        // instructions leak into a tools-disabled session.
+        const mcpInstructions = toolsDisabled
+            ? []
+            : (this.resolvers?.getMcpServerInstructions?.() ?? []);
+        const systemPrompt = appendMcpServerInstructionsNote(codeNotesPrompt, mcpInstructions);
         // Create agent with configured middleware. Only pass systemPrompt when non-empty so we never
         // hand createAgent an empty system message.
         this.agent = createAgent({

package/dist/core/GthLangChainAgent.js.map

@@ -1 +1 @@
-{"version":3,"file":"GthLangChainAgent.js","sourceRoot":"","sources":["../../src/core/GthLangChainAgent.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"GthLangChainAgent.js","sourceRoot":"","sources":["../../src/core/GthLangChainAgent.ts"],"names":[],"mappings":"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"}

package/dist/core/types.d.ts

@@ -197,9 +197,29 @@ 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;
+}
 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[];
 }

package/dist/history/historyFormat.d.ts

@@ -7,13 +7,22 @@
  * 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 { HistoryInsights, SessionSearchResult } from '#src/history/historyStore.js';
+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[];
-/** Render a recent-sessions listing: one header + prompt-preview pair per session. */
-export declare function formatHistoryList(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

@@ -3,13 +3,17 @@ 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` header line for one session. */
+/** 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('  ');
 }
 /**
@@ -29,22 +33,60 @@ export function formatSearchResults(results) {
     }
     return lines;
 }
-/** Render a recent-sessions listing: one header + prompt-preview pair per session. */
-export function formatHistoryList(results) {
-    if (results.length === 0) {
+/**
+ * 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 sessions recorded yet. Enable history with `history.enabled: true` in your config.',
+            'No conversations recorded yet. Enable history with `history.enabled: true` in your config.',
         ];
     }
     const lines = [];
-    for (const r of results) {
-        lines.push(headerLine(r));
-        const preview = oneLine(r.prompt, 100);
+    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) {

package/dist/history/historyFormat.js.map

@@ -1 +1 @@
-{"version":3,"file":"historyFormat.js","sourceRoot":"","sources":["../../src/history/historyFormat.ts"],"names":[],"mappings":"AAWA,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,0EAA0E;AAC1E,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,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,sFAAsF;AACtF,MAAM,UAAU,iBAAiB,CAAC,OAA8B;IAC9D,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACzB,OAAO;YACL,uFAAuF;SACxF,CAAC;IACJ,CAAC;IACD,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,OAAO,GAAG,OAAO,CAAC,CAAC,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;QACvC,IAAI,OAAO;YAAE,KAAK,CAAC,IAAI,CAAC,OAAO,OAAO,EAAE,CAAC,CAAC;IAC5C,CAAC;IACD,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"}
+{"version":3,"file":"historyFormat.js","sourceRoot":"","sources":["../../src/history/historyFormat.ts"],"names":[],"mappings":"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"}

package/dist/history/historyStore.d.ts

@@ -2,6 +2,13 @@
 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. */
@@ -32,6 +39,41 @@ export interface SessionSearchResult extends SessionRecord {
     /** 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;
@@ -85,6 +127,25 @@ export declare class HistoryStore {
      */
     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
@@ -99,6 +160,22 @@ export declare class HistoryStore {
     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:

package/dist/history/historyStore.js

@@ -73,7 +73,20 @@ export class HistoryStore {
         }
     }
     initSchema() {
+        // GS2-19: the `sessions` table is turn-grained (its rows are prompt→response turns, despite the
+        // name). A `conversations` table groups the turns of one interactive session; each turn carries
+        // a `conversation_id`. `conversation_id` is a plain INTEGER join key, not an enforced FK — SQLite
+        // leaves `foreign_keys` off by default and `ALTER TABLE ADD COLUMN` can't add a REFERENCES clause,
+        // so declaring one here would only make the fresh schema drift from the migrated one. The column
+        // definition is kept byte-identical between this fresh path and {@link migrate}'s ALTER.
         this.db.exec(`
+      CREATE TABLE IF NOT EXISTS conversations (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        started_ts TEXT NOT NULL,
+        project TEXT,
+        command TEXT,
+        model TEXT
+      );
       CREATE TABLE IF NOT EXISTS sessions (
         id INTEGER PRIMARY KEY AUTOINCREMENT,
         ts TEXT NOT NULL,
@@ -86,12 +99,77 @@ export class HistoryStore {
         tokens_output INTEGER,
         cost_usd REAL,
         tools TEXT,
-        duration_ms INTEGER
+        duration_ms INTEGER,
+        conversation_id INTEGER
       );
       CREATE VIRTUAL TABLE IF NOT EXISTS sessions_fts USING fts5(
         prompt, response, command, project
       );
     `);
+        this.migrate();
+    }
+    /**
+     * 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.
+     */
+    migrate() {
+        try {
+            const cols = this.db.prepare(`PRAGMA table_info(sessions)`).all();
+            const hasConversationId = cols.some((c) => c.name === 'conversation_id');
+            if (!hasConversationId) {
+                this.db.exec(`ALTER TABLE sessions ADD COLUMN conversation_id INTEGER`);
+            }
+            const orphans = this.db
+                .prepare(`SELECT id, ts, project, command, model
+             FROM sessions
+            WHERE conversation_id IS NULL
+            ORDER BY id`)
+                .all();
+            if (orphans.length === 0)
+                return;
+            this.db.exec('BEGIN');
+            try {
+                const insertConversation = this.db.prepare(`INSERT INTO conversations (started_ts, project, command, model) VALUES (?, ?, ?, ?)`);
+                const stampTurn = this.db.prepare(`UPDATE sessions SET conversation_id = ? WHERE id = ?`);
+                for (const row of orphans) {
+                    const info = insertConversation.run(row.ts != null ? String(row.ts) : new Date().toISOString(), row.project != null ? String(row.project) : null, row.command != null ? String(row.command) : null, row.model != null ? String(row.model) : null);
+                    stampTurn.run(Number(info.lastInsertRowid), Number(row.id));
+                }
+                this.db.exec('COMMIT');
+            }
+            catch (e) {
+                this.db.exec('ROLLBACK');
+                throw e;
+            }
+        }
+        catch {
+            /* fail-soft: a migration failure must not break opening the store or a run */
+        }
+    }
+    /**
+     * 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 = {}) {
+        try {
+            const ts = meta.ts ?? new Date().toISOString();
+            const info = this.db
+                .prepare(`INSERT INTO conversations (started_ts, project, command, model) VALUES (?, ?, ?, ?)`)
+                .run(ts, meta.project ?? null, meta.command ?? null, meta.model ?? null);
+            return Number(info.lastInsertRowid);
+        }
+        catch {
+            return null;
+        }
     }
     /**
      * Persist one session and its full-text index entry. Returns the new row id, or `null` on any
@@ -104,11 +182,21 @@ export class HistoryStore {
             const tools = rec.tools && rec.tools.length > 0 ? JSON.stringify(rec.tools) : null;
             this.db.exec('BEGIN');
             try {
+                // GS2-19: every turn belongs to a conversation. When the caller opened one up-front
+                // (interactive sessions), stamp it; otherwise open a fresh 1-turn conversation for this row
+                // (single-shot runs / bare record() calls) so the turn is never left ungrouped.
+                let conversationId = rec.conversationId ?? null;
+                if (conversationId == null) {
+                    const cinfo = this.db
+                        .prepare(`INSERT INTO conversations (started_ts, project, command, model) VALUES (?, ?, ?, ?)`)
+                        .run(ts, rec.project ?? null, rec.command ?? null, rec.model ?? null);
+                    conversationId = Number(cinfo.lastInsertRowid);
+                }
                 const insert = this.db.prepare(`INSERT INTO sessions
              (ts, project, command, model, prompt, response,
-              tokens_input, tokens_output, cost_usd, tools, duration_ms)
-           VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`);
-                const info = insert.run(ts, rec.project ?? null, rec.command ?? null, rec.model ?? null, rec.prompt ?? null, rec.response ?? null, rec.tokensInput ?? null, rec.tokensOutput ?? null, rec.costUsd ?? null, tools, rec.durationMs ?? null);
+              tokens_input, tokens_output, cost_usd, tools, duration_ms, conversation_id)
+           VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`);
+                const info = insert.run(ts, rec.project ?? null, rec.command ?? null, rec.model ?? null, rec.prompt ?? null, rec.response ?? null, rec.tokensInput ?? null, rec.tokensOutput ?? null, rec.costUsd ?? null, tools, rec.durationMs ?? null, conversationId);
                 const id = Number(info.lastInsertRowid);
                 this.db
                     .prepare(`INSERT INTO sessions_fts (rowid, prompt, response, command, project)
@@ -141,6 +229,7 @@ export class HistoryStore {
                   s.model AS model, s.prompt AS prompt, s.response AS response,
                   s.tokens_input AS tokens_input, s.tokens_output AS tokens_output,
                   s.cost_usd AS cost_usd, s.tools AS tools, s.duration_ms AS duration_ms,
+                  s.conversation_id AS conversation_id,
                   snippet(sessions_fts, 0, '[', ']', '…', 12) AS snippet
              FROM sessions_fts f
              JOIN sessions s ON s.id = f.rowid
@@ -164,7 +253,7 @@ export class HistoryStore {
         try {
             const rows = this.db
                 .prepare(`SELECT id, ts, project, command, model, prompt, response,
-                  tokens_input, tokens_output, cost_usd, tools, duration_ms
+                  tokens_input, tokens_output, cost_usd, tools, duration_ms, conversation_id
              FROM sessions
             ORDER BY id DESC
             LIMIT ?`)
@@ -180,6 +269,70 @@ export class HistoryStore {
             return [];
         }
     }
+    /**
+     * 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 = 20) {
+        try {
+            const rows = this.db
+                .prepare(`SELECT c.id AS id, c.started_ts AS started_ts, c.project AS project,
+                  c.command AS command, c.model AS model,
+                  COUNT(s.id) AS turn_count, MIN(s.ts) AS first_ts, MAX(s.ts) AS last_ts
+             FROM conversations c
+             LEFT JOIN sessions s ON s.conversation_id = c.id
+            GROUP BY c.id
+           HAVING COUNT(s.id) > 0
+            ORDER BY c.id DESC
+            LIMIT ?`)
+                .all(limit);
+            const lastTurn = this.db.prepare(`SELECT prompt, response FROM sessions
+          WHERE conversation_id = ? ORDER BY id DESC LIMIT 1`);
+            return rows.map((r) => {
+                const last = lastTurn.get(Number(r.id));
+                return {
+                    id: Number(r.id),
+                    startedTs: String(r.started_ts),
+                    project: r.project != null ? String(r.project) : undefined,
+                    command: r.command != null ? String(r.command) : undefined,
+                    model: r.model != null ? String(r.model) : undefined,
+                    turnCount: Number(r.turn_count ?? 0),
+                    firstTs: r.first_ts != null ? String(r.first_ts) : undefined,
+                    lastTs: r.last_ts != null ? String(r.last_ts) : undefined,
+                    lastPrompt: last?.prompt != null ? String(last.prompt) : undefined,
+                    lastResponse: last?.response != null ? String(last.response) : undefined,
+                };
+            });
+        }
+        catch {
+            return [];
+        }
+    }
+    /**
+     * 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) {
+        try {
+            const rows = this.db
+                .prepare(`SELECT id, ts, project, command, model, prompt, response,
+                  tokens_input, tokens_output, cost_usd, tools, duration_ms, conversation_id
+             FROM sessions
+            WHERE conversation_id = ?
+            ORDER BY id ASC`)
+                .all(conversationId);
+            return rows.map((r) => rowToRecord(r));
+        }
+        catch {
+            return [];
+        }
+    }
     /**
      * 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:
@@ -281,6 +434,7 @@ function rowToRecord(r) {
         }
     }
     return {
+        conversationId: r.conversation_id != null ? Number(r.conversation_id) : undefined,
         ts: r.ts != null ? String(r.ts) : undefined,
         project: r.project != null ? String(r.project) : undefined,
         command: r.command != null ? String(r.command) : undefined,