@gaunt-sloth/core 2.0.0-alpha.9 → 2.0.0-beta.0

package/dist/core/debugCapture.d.ts

@@ -0,0 +1,74 @@
+import type { BaseMessage } from '@langchain/core/messages';
+/**
+ * The non-message parts of a `wrapModelCall` request that also shape a turn: the tool
+ * definitions, the system prompt, and the model params. Captured alongside the message
+ * history so the `/debug` panel can show the full picture of what was sent to the model.
+ *
+ * SECURITY: these are assembled from an explicit allowlist at the capture site
+ * (see {@link extractDebugRequestExtras}); the raw model instance (which can carry an
+ * `apiKey`) is never passed through here.
+ */
+export interface DebugRequestExtras {
+    /** The composed system prompt string sent to the model for this call. */
+    systemPrompt?: string;
+    /** The tool definitions made available for this call (name + description + JSON schema). */
+    tools?: DebugToolDef[];
+    /** Scalar model params (model id, temperature, …) — a key-free allowlist. */
+    modelParams?: Record<string, unknown>;
+    /** The tool-choice configuration for this call, if any. */
+    toolChoice?: unknown;
+}
+/** A single tool's debug-renderable definition. */
+export interface DebugToolDef {
+    name: string;
+    description?: string;
+    /** The tool's JSON-schema parameters, when resolvable. */
+    schema?: unknown;
+}
+/**
+ * GS2-56 — the always-on snapshot of the LAST model request, kept on
+ * {@link import('#src/core/GthAbstractAgent.js').GthAbstractAgent} independent of any
+ * {@link DebugCapture} sink. It is the SAME data the sink reports (the as-sent, post-summarization
+ * `request.messages` plus the {@link DebugRequestExtras}), captured unconditionally at each model
+ * call so `/debug-dump` can render the full model input even when the TUI `/debug` panel was never
+ * opened and on non-TUI surfaces. Reuses {@link DebugRequestExtras} rather than forking a parallel
+ * capture shape; `WriteDebugDumpInput.modelRequest` is this same type, so the caller threads
+ * `agent.lastModelRequest` straight through with no reshaping.
+ */
+export interface LastModelRequest {
+    /** The request extras (system prompt, tool defs with schema, model params, tool-choice). */
+    extras?: DebugRequestExtras;
+    /** The exact messages sent to the model for the last call (post-summarization / middleware). */
+    messages?: BaseMessage[];
+}
+/**
+ * Debug-capture sink for the TUI's `/debug` panel.
+ *
+ * A {@link DebugCapture} is an OPT-IN callback the TUI sets on a live agent after `init`
+ * (on the shared {@link import('#src/core/GthAbstractAgent.js').GthAbstractAgent} base, so
+ * every backend supports it). When present, the agent's `wrapModelCall`
+ * middleware reports, per model call:
+ *
+ * - `request` — `request.messages: BaseMessage[]`, the real history sent to the model at
+ *   call time (post-summarization / post-middleware), plus the {@link DebugRequestExtras}
+ *   (tools, system prompt, model params) that also shape the turn. This is exactly what the
+ *   model saw.
+ * - `response` — the resolved `AIMessage` returned by the handler, captured as a whole
+ *   (resolved message, not per-chunk frames; keeps the streaming core untouched).
+ *
+ * The sink is read lazily inside the middleware (per call), so when no TUI debug panel is
+ * attached the middleware is a transparent pass-through and the normal path pays nothing.
+ */
+export interface DebugCapture {
+    /** The full message history sent to the model for this call, plus the request extras. */
+    onRequest?(messages: BaseMessage[], extras?: DebugRequestExtras): void;
+    /** The resolved model response for this call (an `AIMessage`). */
+    onResponse?(response: unknown): void;
+}
+/**
+ * Assemble the non-message request parts ({@link DebugRequestExtras}) for the `/debug`
+ * panel from a `wrapModelCall` request, defensively and key-free. Never throws (the caller
+ * already guards, but a debug sink must never break a run) and never dumps the raw model.
+ * Lives in core, beside the capture type itself, so every backend feeds the panel the same shape.
+ */
+export declare function extractDebugRequestExtras(request: unknown): DebugRequestExtras | undefined;

package/dist/core/debugCapture.js

@@ -0,0 +1,100 @@
+/**
+ * Scalar model-param fields worth surfacing in the `/debug` panel. Deliberately an
+ * allowlist (NOT a whole-object dump) so no credential field (`apiKey`, `accessToken`, …)
+ * can ever leak into the rendered debug view.
+ *
+ * `streaming` is intentionally NOT here: it is the model instance's static flag, which is
+ * usually `false` even when the turn streams — the GthAgentRunner decides streaming by calling
+ * `.stream()` vs `.invoke()`, not by this property — so surfacing it just misleads.
+ */
+const DEBUG_MODEL_PARAM_KEYS = [
+    'model',
+    'modelName',
+    'modelId',
+    'deploymentName',
+    'temperature',
+    'topP',
+    'topK',
+    'maxTokens',
+    'maxOutputTokens',
+    'maxReasoningTokens',
+    'reasoningEffort',
+    'thinkingBudget',
+    'stop',
+    'provider',
+];
+/** Pull the key-free scalar model params from the (provider-specific) model instance. */
+function extractModelParams(model) {
+    if (!model || typeof model !== 'object')
+        return undefined;
+    const src = model;
+    const out = {};
+    for (const key of DEBUG_MODEL_PARAM_KEYS) {
+        const value = src[key];
+        if (value === undefined || value === null)
+            continue;
+        // Only scalars / scalar arrays — never nested objects that could carry credentials.
+        if (typeof value === 'object' && !Array.isArray(value))
+            continue;
+        out[key] = value;
+    }
+    // `model` / `modelName` / `modelId` are langchain aliases for the same value; collapse the
+    // duplicates so the panel shows the model id once instead of two identical lines.
+    if (typeof out.model !== 'string' && typeof out.modelName === 'string') {
+        out.model = out.modelName;
+    }
+    if (out.modelName === out.model)
+        delete out.modelName;
+    if (out.modelId === out.model)
+        delete out.modelId;
+    return Object.keys(out).length > 0 ? out : undefined;
+}
+/** Best-effort tool definition (name + description + schema) for the debug view. */
+function extractToolDefs(tools) {
+    if (!Array.isArray(tools) || tools.length === 0)
+        return undefined;
+    const defs = [];
+    for (const tool of tools) {
+        if (!tool || typeof tool !== 'object')
+            continue;
+        const t = tool;
+        const name = typeof t.name === 'string' ? t.name : undefined;
+        if (!name)
+            continue;
+        const description = typeof t.description === 'string' ? t.description : undefined;
+        // LangChain StructuredTools expose a Zod/JSON `schema`; some carry it on `lc_kwargs`.
+        const schema = t.schema ?? undefined;
+        defs.push({ name, description, schema });
+    }
+    return defs.length > 0 ? defs : undefined;
+}
+/**
+ * Assemble the non-message request parts ({@link DebugRequestExtras}) for the `/debug`
+ * panel from a `wrapModelCall` request, defensively and key-free. Never throws (the caller
+ * already guards, but a debug sink must never break a run) and never dumps the raw model.
+ * Lives in core, beside the capture type itself, so every backend feeds the panel the same shape.
+ */
+export function extractDebugRequestExtras(request) {
+    if (!request || typeof request !== 'object')
+        return undefined;
+    const req = request;
+    const systemMessage = req.systemMessage;
+    const systemPrompt = typeof req.systemPrompt === 'string' && req.systemPrompt
+        ? req.systemPrompt
+        : typeof systemMessage?.content === 'string'
+            ? systemMessage.content
+            : undefined;
+    const extras = {
+        systemPrompt,
+        tools: extractToolDefs(req.tools),
+        modelParams: extractModelParams(req.model),
+        toolChoice: req.toolChoice,
+    };
+    // Return undefined when nothing useful was captured so the renderer can show a clear empty state.
+    const hasAny = extras.systemPrompt !== undefined ||
+        extras.tools !== undefined ||
+        extras.modelParams !== undefined ||
+        extras.toolChoice !== undefined;
+    return hasAny ? extras : undefined;
+}
+//# sourceMappingURL=debugCapture.js.map

package/dist/core/debugCapture.js.map

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

package/dist/core/gthLeanAgentFactory.d.ts

@@ -1,9 +1,9 @@
 import type { GthAgentFactory } from '#src/core/types.js';
 /**
  * The lean backend factory — a {@link GthAgentFactory} that produces a plain
- * {@link GthLangChainAgent} (no deepagents graph). This is identical to the built-in
- * default {@link GthAgentRunner} constructs when no factory is passed; exporting it lets
- * `@gaunt-sloth/agent`'s {@link resolveAgentFactory} pick lean vs deep from config without
- * duplicating the constructor call.
+ * {@link GthLangChainAgent}. This is identical to the built-in default {@link GthAgentRunner}
+ * constructs when no factory is passed; exporting it lets `@gaunt-sloth/agent`'s
+ * {@link resolveAgentFactory} hand the runner a backend without duplicating the constructor
+ * call.
  */
 export declare const gthLeanAgentFactory: GthAgentFactory;

package/dist/core/gthLeanAgentFactory.js

@@ -1,10 +1,10 @@
 import { GthLangChainAgent } from '#src/core/GthLangChainAgent.js';
 /**
  * The lean backend factory — a {@link GthAgentFactory} that produces a plain
- * {@link GthLangChainAgent} (no deepagents graph). This is identical to the built-in
- * default {@link GthAgentRunner} constructs when no factory is passed; exporting it lets
- * `@gaunt-sloth/agent`'s {@link resolveAgentFactory} pick lean vs deep from config without
- * duplicating the constructor call.
+ * {@link GthLangChainAgent}. This is identical to the built-in default {@link GthAgentRunner}
+ * constructs when no factory is passed; exporting it lets `@gaunt-sloth/agent`'s
+ * {@link resolveAgentFactory} hand the runner a backend without duplicating the constructor
+ * call.
  */
 export const gthLeanAgentFactory = (statusUpdate, resolvers) => new GthLangChainAgent(statusUpdate, resolvers);
 //# sourceMappingURL=gthLeanAgentFactory.js.map

package/dist/core/launchBanner.d.ts

@@ -0,0 +1,127 @@
+import { modelProviderLabel } from '#src/core/modelLabel.js';
+/**
+ * TUI-C40 — the resting face, under the name the animation layer refers to it by.
+ *
+ * Every frame below is the same five lines and the same 16-column field, so swapping one in changes
+ * nothing about the layout: the right column still starts at {@link RIGHT_COLUMN} and the
+ * truncation budgets are untouched. That invariant is what makes an animation a data change rather
+ * than a geometry change, and it is asserted per frame in the specs.
+ */
+export declare const RESTING_FACE: readonly ["  ▄█▀▀▀▀▀▀▀▀█▄", "▄▀█▄█▀▀▀▀▀▀█▄█▀▄", "█  ▀█▄▀  ▀▄█▀  █", "▀▄▀▀ ██████ ▀▀▄▀", "  ▀██████████▀"];
+/** The animations a click can play. This list is the complete set. */
+export declare const SLOTH_ANIMATIONS: readonly ['blink', 'nod', 'look-around', 'eyeroll'];
+export type SlothAnimation = (typeof SLOTH_ANIMATIONS)[number];
+/** One frame of an animation and how long it stays on screen. */
+export interface SlothAnimationStep {
+    face: readonly string[];
+    holdMs: number;
+}
+/**
+ * The four sequences, as the frames shown AFTER the resting face.
+ *
+ * Playback always settles back on {@link RESTING_FACE} once the last step's hold elapses, so no
+ * sequence lists a trailing rest — but `nod` lists rest in the MIDDLE, because nodding twice means
+ * returning to level between the two dips. None of them loops, and a click plays exactly one.
+ */
+export declare const SLOTH_ANIMATION_STEPS: Record<SlothAnimation, readonly SlothAnimationStep[]>;
+/**
+ * Pick one animation at random. `random` is injectable so a test can pin the choice — the
+ * production call passes nothing and gets `Math.random`.
+ */
+export declare function pickSlothAnimation(random?: () => number): SlothAnimation;
+/**
+ * Blank columns prepended to every art row (TUI-C36). One column of left margin, so the block does
+ * not sit flush against the edge of the terminal.
+ */
+export declare const LEFT_PAD = 1;
+/**
+ * Column at which the right-hand column begins on EVERY row — the single number the whole layout
+ * and the colour split are expressed in terms of (margin + face + gutter = 22).
+ */
+export declare const RIGHT_COLUMN: number;
+/** Column at which the version label begins on row 2 (right column + wordmark + gap = 44). */
+export declare const VERSION_COLUMN: number;
+/**
+ * Narrowest terminal that still gets the right column. The wordmark itself ends at column 40, so
+ * anything narrower than this leaves no usable room for the fields beside it; below the threshold
+ * the face prints alone (see the module docs on why wrapping is not an option).
+ */
+export declare const MIN_BANNER_COLUMNS: number;
+/** The live values the banner reports, plus the terminal geometry it has to fit inside. */
+export interface LaunchBannerInput {
+    /** Gaunt Sloth version, WITHOUT the `v` prefix (this module adds it). */
+    version?: string;
+    /** `config.modelDisplayName`. */
+    model?: string;
+    /** `config.modelProviderType`. */
+    provider?: string;
+    /** Working directory to report (`getProjectDir()`), before the home-prefix collapse. */
+    directory?: string;
+    /** The user's home dir; when `directory` sits under it the prefix collapses to `~`. */
+    homeDir?: string;
+    /** Live `stdout.columns`; `undefined` (non-TTY / tests) falls back to {@link DEFAULT_COLUMNS}. */
+    columns?: number;
+    /** Emit ANSI colour. Only {@link launchBannerText} reads this; Ink colours rows itself. */
+    colour?: boolean;
+    /**
+     * TUI-C40 — which face to draw. Defaults to {@link RESTING_FACE}, so every existing caller is
+     * unaffected and a plain launch is byte-identical to before. An animation frame differs only in
+     * these five lines: the geometry below reads the face's width from the constants, never from the
+     * strings, so a swapped frame cannot move the right column or change a truncation budget.
+     */
+    face?: readonly string[];
+}
+/**
+ * One rendered banner row, pre-split at {@link RIGHT_COLUMN} so each surface can colour the two
+ * halves independently without re-deriving the geometry.
+ */
+export interface LaunchBannerRow {
+    /**
+     * Columns 0–21: the {@link LEFT_PAD} margin and the face, right-padded to {@link RIGHT_COLUMN}
+     * when this row has right-hand content (and left unpadded when it does not, so no row ends in
+     * trailing whitespace). Rendered in magenta — the margin is blank, so painting it is a no-op.
+     * Empty on the two blank padding rows, which carry nothing at all.
+     */
+    face: string;
+    /** Columns 21+: wordmark, version, model/provider or directory. Default foreground, no colour. */
+    right: string;
+}
+/**
+ * The shared `model (provider)` spelling, re-exported so this module stays the documented home of
+ * the banner's fields. It lives in `modelLabel.ts` because the agent renders it too and must not
+ * import this module's console/filesystem graph to do so.
+ */
+export { modelProviderLabel };
+/**
+ * Assemble the banner as {@link LaunchBannerRow}s: a blank row, the five art rows each pre-split at
+ * {@link RIGHT_COLUMN}, and a blank row. Pure — every input arrives as an argument, so the geometry
+ * is testable without a terminal, a config or a process.
+ */
+export declare function launchBannerRows(input: LaunchBannerInput): LaunchBannerRow[];
+/**
+ * Render the banner as one multi-line string for the plain (readline) surface.
+ *
+ * Colour is the 16-colour `magenta` slot from {@link ANSI_COLORS} — the SAME slot the rest of the
+ * CLI uses — and never a 256-colour or 24-bit escape: the 16-colour slot picks up the violet from
+ * the user's own terminal theme, so the sloth looks native in both light and dark schemes. The
+ * right column carries no escape at all, not even dim.
+ *
+ * With `colour: false` the output contains ZERO escape sequences — not one dim wrapper, not one
+ * reset — so a monochrome session (`useColour: false`) stays genuinely clean. The caller decides;
+ * the plain surface passes `getUseColour()`, the TUI passes nothing and lets Ink's own
+ * colour-support detection make the same call.
+ */
+export declare function launchBannerText(input: LaunchBannerInput): string;
+/** The process-resolved half of {@link LaunchBannerInput} — everything but the geometry. */
+export type LaunchBannerFields = Pick<LaunchBannerInput, 'version' | 'model' | 'provider' | 'directory' | 'homeDir'>;
+/**
+ * Read the live fields off the process, so both surfaces report the same three values from the same
+ * sources instead of each picking its own. `model`/`provider` come from the caller because only it
+ * has the resolved config (`config.modelDisplayName` / `config.modelProviderType`); the rest are
+ * process-global.
+ *
+ * Fail-soft, as in `debugDump`: `getSlothVersion()` reads the installed `package.json` through the
+ * install dir that the CLI entry point sets, and THROWS when nothing set it (an embedded caller, a
+ * unit test). A missing version drops one label — it must never stop a session from starting.
+ */
+export declare function launchBannerFields(model?: string, provider?: string): LaunchBannerFields;