@gaunt-sloth/core 2.0.0-alpha.6 → 2.0.0-alpha.8

package/dist/core/shell/ShellCommandFailedError.d.ts

@@ -0,0 +1,54 @@
+/**
+ * @module core/shell/ShellCommandFailedError
+ *
+ * The typed error a `run_*` shell/dev tool throws when a command did NOT exit cleanly
+ * (non-zero exit code, or killed for exceeding the timeout). It carries the FULL model-facing
+ * body so a softening middleware can hand the model the exact observation it saw before — the
+ * only change being that the tool result's status flips to `'error'` (→ `isError` → the ✗ glyph).
+ *
+ * Canonical home is **core** so BOTH agents can recognise a shell failure without violating the
+ * `agent → core` dependency direction:
+ *  - the deep agent (`code` mode, `@gaunt-sloth/agent` `GthDeepShellExitSoftening`) and
+ *  - the lean agent (`exec` / `ask --write`, core `GthLangChainAgent` `GthLeanShellExitSoftening`).
+ *
+ * The throw site (`GthDevToolkit.executeCommand`) lives in the `agent` package and re-exports this
+ * class, so its `throw new ShellCommandFailedError(...)` is one and the same type both agents catch.
+ */
+/**
+ * A `run_*` command that did NOT exit cleanly (non-zero exit code, or was killed for exceeding the
+ * timeout). Carries the FULL model-facing body text ({@link output}) so a softening middleware can
+ * hand the model the exact same observation it saw before — the only change is the tool result's
+ * status flips to `'error'`, which drives the ✗ (`isError`) glyph.
+ *
+ * `executeCommand` previously `resolve()`d on a non-zero exit, so the LangChain `ToolMessage` stayed
+ * `status: 'success'` and every failure rendered a ✓. Throwing this typed error instead lets each
+ * agent's softening middleware convert it into an error `ToolMessage`. A clean exit (`code === 0`)
+ * still `resolve()`s; a spawn-level `child.on('error')` still rejects with a plain `Error`.
+ */
+export declare class ShellCommandFailedError extends Error {
+    /** The full model-facing body (command echo + `<COMMAND_OUTPUT>` + the failure/timeout tail). */
+    readonly output: string;
+    /** The process exit code; `null` when the command was killed (timeout) and never exited cleanly. */
+    readonly exitCode: number | null;
+    /** The exact command string that was executed. */
+    readonly command: string;
+    /** The run_* tool name that invoked the command (e.g. `run_tests`, `run_shell_command`). */
+    readonly toolName: string;
+    constructor(params: {
+        output: string;
+        exitCode: number | null;
+        command: string;
+        toolName: string;
+    });
+}
+/**
+ * Recognise a {@link ShellCommandFailedError} for the softening middleware in either agent.
+ *
+ * Prefers a plain `instanceof` (both agents share this one core module, so the class identity is
+ * the same), but falls back to a STRUCTURAL check keyed on `name === 'ShellCommandFailedError'`
+ * plus the carried fields. The structural arm is deliberate defence against a dual-package /
+ * realm-boundary hazard: if the error ever crossed a module boundary that broke `instanceof`, we
+ * would otherwise silently rethrow a real shell failure and regress the ✗ signal. Every field the
+ * softener reads (`output`) is asserted so a narrowed value is safe to use.
+ */
+export declare function isShellCommandFailedError(e: unknown): e is ShellCommandFailedError;

package/dist/core/shell/ShellCommandFailedError.js

@@ -0,0 +1,68 @@
+/**
+ * @module core/shell/ShellCommandFailedError
+ *
+ * The typed error a `run_*` shell/dev tool throws when a command did NOT exit cleanly
+ * (non-zero exit code, or killed for exceeding the timeout). It carries the FULL model-facing
+ * body so a softening middleware can hand the model the exact observation it saw before — the
+ * only change being that the tool result's status flips to `'error'` (→ `isError` → the ✗ glyph).
+ *
+ * Canonical home is **core** so BOTH agents can recognise a shell failure without violating the
+ * `agent → core` dependency direction:
+ *  - the deep agent (`code` mode, `@gaunt-sloth/agent` `GthDeepShellExitSoftening`) and
+ *  - the lean agent (`exec` / `ask --write`, core `GthLangChainAgent` `GthLeanShellExitSoftening`).
+ *
+ * The throw site (`GthDevToolkit.executeCommand`) lives in the `agent` package and re-exports this
+ * class, so its `throw new ShellCommandFailedError(...)` is one and the same type both agents catch.
+ */
+/**
+ * A `run_*` command that did NOT exit cleanly (non-zero exit code, or was killed for exceeding the
+ * timeout). Carries the FULL model-facing body text ({@link output}) so a softening middleware can
+ * hand the model the exact same observation it saw before — the only change is the tool result's
+ * status flips to `'error'`, which drives the ✗ (`isError`) glyph.
+ *
+ * `executeCommand` previously `resolve()`d on a non-zero exit, so the LangChain `ToolMessage` stayed
+ * `status: 'success'` and every failure rendered a ✓. Throwing this typed error instead lets each
+ * agent's softening middleware convert it into an error `ToolMessage`. A clean exit (`code === 0`)
+ * still `resolve()`s; a spawn-level `child.on('error')` still rejects with a plain `Error`.
+ */
+export class ShellCommandFailedError extends Error {
+    /** The full model-facing body (command echo + `<COMMAND_OUTPUT>` + the failure/timeout tail). */
+    output;
+    /** The process exit code; `null` when the command was killed (timeout) and never exited cleanly. */
+    exitCode;
+    /** The exact command string that was executed. */
+    command;
+    /** The run_* tool name that invoked the command (e.g. `run_tests`, `run_shell_command`). */
+    toolName;
+    constructor(params) {
+        // Use the full body as the Error message so any generic logger/handler still surfaces the
+        // real command output rather than an opaque wrapper string.
+        super(params.output);
+        this.name = 'ShellCommandFailedError';
+        this.output = params.output;
+        this.exitCode = params.exitCode;
+        this.command = params.command;
+        this.toolName = params.toolName;
+    }
+}
+/**
+ * Recognise a {@link ShellCommandFailedError} for the softening middleware in either agent.
+ *
+ * Prefers a plain `instanceof` (both agents share this one core module, so the class identity is
+ * the same), but falls back to a STRUCTURAL check keyed on `name === 'ShellCommandFailedError'`
+ * plus the carried fields. The structural arm is deliberate defence against a dual-package /
+ * realm-boundary hazard: if the error ever crossed a module boundary that broke `instanceof`, we
+ * would otherwise silently rethrow a real shell failure and regress the ✗ signal. Every field the
+ * softener reads (`output`) is asserted so a narrowed value is safe to use.
+ */
+export function isShellCommandFailedError(e) {
+    if (e instanceof ShellCommandFailedError)
+        return true;
+    return (typeof e === 'object' &&
+        e !== null &&
+        e.name === 'ShellCommandFailedError' &&
+        typeof e.output === 'string' &&
+        typeof e.command === 'string' &&
+        typeof e.toolName === 'string');
+}
+//# sourceMappingURL=ShellCommandFailedError.js.map

package/dist/core/shell/ShellCommandFailedError.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ShellCommandFailedError.js","sourceRoot":"","sources":["../../../src/core/shell/ShellCommandFailedError.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH;;;;;;;;;;GAUG;AACH,MAAM,OAAO,uBAAwB,SAAQ,KAAK;IAChD,iGAAiG;IACxF,MAAM,CAAS;IACxB,oGAAoG;IAC3F,QAAQ,CAAgB;IACjC,kDAAkD;IACzC,OAAO,CAAS;IACzB,4FAA4F;IACnF,QAAQ,CAAS;IAE1B,YAAY,MAKX;QACC,0FAA0F;QAC1F,4DAA4D;QAC5D,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;QACrB,IAAI,CAAC,IAAI,GAAG,yBAAyB,CAAC;QACtC,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC;QAC5B,IAAI,CAAC,QAAQ,GAAG,MAAM,CAAC,QAAQ,CAAC;QAChC,IAAI,CAAC,OAAO,GAAG,MAAM,CAAC,OAAO,CAAC;QAC9B,IAAI,CAAC,QAAQ,GAAG,MAAM,CAAC,QAAQ,CAAC;IAClC,CAAC;CACF;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,yBAAyB,CAAC,CAAU;IAClD,IAAI,CAAC,YAAY,uBAAuB;QAAE,OAAO,IAAI,CAAC;IACtD,OAAO,CACL,OAAO,CAAC,KAAK,QAAQ;QACrB,CAAC,KAAK,IAAI;QACT,CAAwB,CAAC,IAAI,KAAK,yBAAyB;QAC5D,OAAQ,CAA0B,CAAC,MAAM,KAAK,QAAQ;QACtD,OAAQ,CAA2B,CAAC,OAAO,KAAK,QAAQ;QACxD,OAAQ,CAA4B,CAAC,QAAQ,KAAK,QAAQ,CAC3D,CAAC;AACJ,CAAC"}

package/dist/core/types.d.ts

@@ -22,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
@@ -155,6 +172,18 @@ export interface GthAgentInterface {
      * 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>;
 }
 /**

package/dist/history/historyFormat.d.ts

@@ -0,0 +1,19 @@
+/**
+ * @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 { HistoryInsights, 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[];
+/** 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,85 @@
+/** 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` header line for one session. */
+function headerLine(r) {
+    const parts = [`#${r.id}`, r.ts];
+    if (r.command)
+        parts.push(`[${r.command}]`);
+    if (r.model)
+        parts.push(r.model);
+    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;
+}
+/** Render a recent-sessions listing: one header + prompt-preview pair per session. */
+export function formatHistoryList(results) {
+    if (results.length === 0) {
+        return [
+            'No sessions 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);
+        if (preview)
+            lines.push(`    ${preview}`);
+    }
+    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":"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"}

package/dist/history/historyStore.d.ts

@@ -0,0 +1,121 @@
+/** 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 {
+    /** 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;
+}
+/** 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;
+    /**
+     * 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[];
+    /**
+     * 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;