@gaunt-sloth/core 0.1.7 → 2.0.0-alpha.0

package/dist/core/types.d.ts

@@ -20,13 +20,75 @@ export declare enum StatusLevel {
     ERROR = 5,
     STREAM = 6
 }
-export type GthCommand = 'ask' | 'pr' | 'review' | 'chat' | 'code' | 'api';
+export type GthCommand = 'ask' | 'pr' | 'review' | 'chat' | 'code' | 'api' | 'exec';
+/**
+ * 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
+ * SSE encoder, the (future) TUI, and any embedder — so it is intentionally agnostic of
+ * how the underlying graph was built (lean `createAgent` or `createDeepAgent`).
+ */
+export type AgentStreamEvent = {
+    type: 'text';
+    delta: string;
+} | {
+    type: 'reasoning_start';
+} | {
+    type: 'reasoning_delta';
+    delta: string;
+} | {
+    type: 'reasoning_end';
+} | {
+    type: 'tool_start';
+    id: string;
+    name: string;
+} | {
+    type: 'tool_args';
+    id: string;
+    delta: string;
+} | {
+    type: 'tool_end';
+    id: string;
+} | {
+    type: 'tool_result';
+    id: string;
+    content: string;
+};
+/**
+ * The minimal structural surface of a compiled LangGraph agent that the shared agent
+ * plumbing in {@link GthAbstractAgent} drives. Both `createAgent` (lean) and
+ * `createDeepAgent` return graphs that satisfy this, so the base class can stream/invoke
+ * either without knowing which builder produced it. Inputs are intentionally loose
+ * (`any`) so concrete builder return types assign without casts; the base re-applies
+ * precise typing at the point of use via `AIMessage`/`AIMessageChunk` guards.
+ */
+export interface GthCompiledGraph {
+    invoke(input: any, config?: RunnableConfig): Promise<{
+        messages: BaseMessage[];
+    }>;
+    stream(input: any, config?: any): Promise<IterableReadableStream<any>>;
+}
 export interface GthAgentInterface {
     init(command: GthCommand | undefined, configIn: GthConfig, checkpointSaver?: BaseCheckpointSaver | undefined): Promise<void>;
     invoke(messages: Message[], runConfig: RunnableConfig): Promise<string>;
     stream(messages: Message[], runConfig: RunnableConfig): Promise<IterableReadableStream<string>>;
+    /**
+     * Stream the run as typed {@link AgentStreamEvent}s. If a client tool triggers
+     * `interrupt()` the underlying graph suspends; this generator ends cleanly so the
+     * transport can finish the run with the tool call hanging. Resume via
+     * {@link streamWithEventsResume} on the same `thread_id`.
+     */
+    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>;
     cleanup?(): Promise<void>;
 }
+/**
+ * Factory that produces a {@link GthAgentInterface} implementation. Injected into
+ * {@link GthAgentRunner} so embedders can swap the lean `GthLangChainAgent` (default,
+ * in core) for a deep `GthDeepAgent` (in `@gaunt-sloth/agent`) without core ever
+ * importing deepagents.
+ */
+export type GthAgentFactory = (statusUpdate: StatusUpdateCallback, resolvers?: AgentResolvers) => GthAgentInterface;
 export type ToolsResolver = (config: GthConfig, command?: GthCommand) => Promise<StructuredToolInterface[]>;
 export type ToolsCleanup = () => Promise<void>;
 export type MiddlewareResolver = (middleware: any[] | undefined, config: GthConfig) => Promise<any[]>;

package/dist/index.d.ts

@@ -1,3 +1,4 @@
 export * from '#src/constants.js';
 export * from '#src/core/types.js';
 export * from '#src/config.js';
+export * from '#src/providers/modelDiscovery.js';

package/dist/index.js

@@ -1,4 +1,5 @@
 export * from '#src/constants.js';
 export * from '#src/core/types.js';
 export * from '#src/config.js';
+export * from '#src/providers/modelDiscovery.js';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,mBAAmB,CAAC;AAClC,cAAc,oBAAoB,CAAC;AACnC,cAAc,gBAAgB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,mBAAmB,CAAC;AAClC,cAAc,oBAAoB,CAAC;AACnC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,kCAAkC,CAAC"}

package/dist/providers/anthropic.js

@@ -12,13 +12,13 @@ export async function processJsonConfig(llmConfig) {
     return new anthropic.ChatAnthropic({
         ...llmConfig,
         apiKey: anthropicApiKey,
-        model: llmConfig.model || 'claude-sonnet-4-5',
+        model: llmConfig.model || 'claude-sonnet-4-6',
     });
 }
 const jsonContent = `{
   "llm": {
     "type": "anthropic",
-    "model": "claude-sonnet-4-5"
+    "model": "claude-sonnet-4-6"
   }
 }`;
 // noinspection JSUnusedGlobalSymbols

package/dist/providers/deepseek.js

@@ -9,13 +9,13 @@ export async function processJsonConfig(llmConfig) {
     return new deepseek.ChatDeepSeek({
         ...llmConfig,
         apiKey: deepseekApiKey,
-        model: llmConfig.model || 'deepseek-reasoner',
+        model: llmConfig.model || 'deepseek-v4-pro',
     });
 }
 const jsonContent = `{
   "llm": {
     "type": "deepseek",
-    "model": "deepseek-reasoner"
+    "model": "deepseek-v4-pro"
   }
 }`;
 export function init(configFileName) {

package/dist/providers/deepseek.js.map

@@ -1 +1 @@
-{"version":3,"file":"deepseek.js","sourceRoot":"","sources":["../../src/providers/deepseek.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,4BAA4B,CAAC;AAC5D,OAAO,EAAE,GAAG,EAAE,MAAM,2BAA2B,CAAC;AAOhD,OAAO,EAAE,gCAAgC,EAAE,MAAM,yBAAyB,CAAC;AAE3E,mEAAmE;AACnE,MAAM,CAAC,KAAK,UAAU,iBAAiB,CACrC,SAAkD;IAElD,MAAM,QAAQ,GAAG,MAAM,MAAM,CAAC,qBAAqB,CAAC,CAAC;IACrD,yEAAyE;IACzE,MAAM,cAAc,GAAG,SAAS,CAAC,MAAM,IAAI,GAAG,CAAC,gBAAgB,CAAC;IAChE,OAAO,IAAI,QAAQ,CAAC,YAAY,CAAC;QAC/B,GAAG,SAAS;QACZ,MAAM,EAAE,cAAc;QACtB,KAAK,EAAE,SAAS,CAAC,KAAK,IAAI,mBAAmB;KAC9C,CAAC,CAAC;AACL,CAAC;AAED,MAAM,WAAW,GAAG;;;;;EAKlB,CAAC;AAEH,MAAM,UAAU,IAAI,CAAC,cAAsB;IACzC,yDAAyD;IACzD,IAAI,CAAC,cAAc,CAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC;QACtC,MAAM,IAAI,KAAK,CAAC,gCAAgC,CAAC,CAAC;IACpD,CAAC;IAED,gCAAgC,CAAC,cAAc,EAAE,WAAW,CAAC,CAAC;IAC9D,cAAc,CACZ,2BAA2B,cAAc,iCAAiC;QACxE,kDAAkD,CACrD,CAAC;AACJ,CAAC"}
+{"version":3,"file":"deepseek.js","sourceRoot":"","sources":["../../src/providers/deepseek.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,4BAA4B,CAAC;AAC5D,OAAO,EAAE,GAAG,EAAE,MAAM,2BAA2B,CAAC;AAOhD,OAAO,EAAE,gCAAgC,EAAE,MAAM,yBAAyB,CAAC;AAE3E,mEAAmE;AACnE,MAAM,CAAC,KAAK,UAAU,iBAAiB,CACrC,SAAkD;IAElD,MAAM,QAAQ,GAAG,MAAM,MAAM,CAAC,qBAAqB,CAAC,CAAC;IACrD,yEAAyE;IACzE,MAAM,cAAc,GAAG,SAAS,CAAC,MAAM,IAAI,GAAG,CAAC,gBAAgB,CAAC;IAChE,OAAO,IAAI,QAAQ,CAAC,YAAY,CAAC;QAC/B,GAAG,SAAS;QACZ,MAAM,EAAE,cAAc;QACtB,KAAK,EAAE,SAAS,CAAC,KAAK,IAAI,iBAAiB;KAC5C,CAAC,CAAC;AACL,CAAC;AAED,MAAM,WAAW,GAAG;;;;;EAKlB,CAAC;AAEH,MAAM,UAAU,IAAI,CAAC,cAAsB;IACzC,yDAAyD;IACzD,IAAI,CAAC,cAAc,CAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC;QACtC,MAAM,IAAI,KAAK,CAAC,gCAAgC,CAAC,CAAC;IACpD,CAAC;IAED,gCAAgC,CAAC,cAAc,EAAE,WAAW,CAAC,CAAC;IAC9D,cAAc,CACZ,2BAA2B,cAAc,iCAAiC;QACxE,kDAAkD,CACrD,CAAC;AACJ,CAAC"}

package/dist/providers/google-genai.js

@@ -9,7 +9,7 @@ export async function processJsonConfig(llmConfig) {
     const configFields = {
         ...llmConfig,
         apiKey: googleApiKey,
-        model: llmConfig.model || 'gemini-2.5-pro',
+        model: llmConfig.model || 'gemini-3.5-flash',
         platformType: 'gai',
     };
     delete configFields.type;
@@ -19,7 +19,7 @@ export async function processJsonConfig(llmConfig) {
 const jsonContent = `{
   "llm": {
     "type": "google-genai",
-    "model": "gemini-2.5-pro"
+    "model": "gemini-3.5-flash"
   }
 }`;
 export function init(configFileName) {

package/dist/providers/google-genai.js.map

@@ -1 +1 @@
-{"version":3,"file":"google-genai.js","sourceRoot":"","sources":["../../src/providers/google-genai.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,4BAA4B,CAAC;AAC5D,OAAO,EAAE,GAAG,EAAE,MAAM,2BAA2B,CAAC;AAIhD,OAAO,EAAE,gCAAgC,EAAE,MAAM,yBAAyB,CAAC;AAE3E,uEAAuE;AACvE,MAAM,CAAC,KAAK,UAAU,iBAAiB,CACrC,SAAmF;IAEnF,MAAM,EAAE,UAAU,EAAE,GAAG,MAAM,MAAM,CAAC,wBAAwB,CAAC,CAAC;IAC9D,wEAAwE;IACxE,MAAM,YAAY,GAAG,SAAS,CAAC,MAAM,IAAI,GAAG,CAAC,cAAc,CAAC;IAC5D,MAAM,YAAY,GAAG;QACnB,GAAG,SAAS;QACZ,MAAM,EAAE,YAAY;QACpB,KAAK,EAAE,SAAS,CAAC,KAAK,IAAI,gBAAgB;QAC1C,YAAY,EAAE,KAAc;KAC7B,CAAC;IACF,OAAO,YAAY,CAAC,IAAI,CAAC;IACzB,OAAO,YAAY,CAAC,yBAAyB,CAAC;IAC9C,OAAO,IAAI,UAAU,CAAC,YAAY,CAAC,CAAC;AACtC,CAAC;AAED,MAAM,WAAW,GAAG;;;;;EAKlB,CAAC;AAEH,MAAM,UAAU,IAAI,CAAC,cAAsB;IACzC,yDAAyD;IACzD,IAAI,CAAC,cAAc,CAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC;QACtC,MAAM,IAAI,KAAK,CAAC,gCAAgC,CAAC,CAAC;IACpD,CAAC;IAED,gCAAgC,CAAC,cAAc,EAAE,WAAW,CAAC,CAAC;IAC9D,cAAc,CACZ,2BAA2B,cAAc,qCAAqC;QAC5E,gDAAgD,CACnD,CAAC;AACJ,CAAC"}
+{"version":3,"file":"google-genai.js","sourceRoot":"","sources":["../../src/providers/google-genai.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,4BAA4B,CAAC;AAC5D,OAAO,EAAE,GAAG,EAAE,MAAM,2BAA2B,CAAC;AAIhD,OAAO,EAAE,gCAAgC,EAAE,MAAM,yBAAyB,CAAC;AAE3E,uEAAuE;AACvE,MAAM,CAAC,KAAK,UAAU,iBAAiB,CACrC,SAAmF;IAEnF,MAAM,EAAE,UAAU,EAAE,GAAG,MAAM,MAAM,CAAC,wBAAwB,CAAC,CAAC;IAC9D,wEAAwE;IACxE,MAAM,YAAY,GAAG,SAAS,CAAC,MAAM,IAAI,GAAG,CAAC,cAAc,CAAC;IAC5D,MAAM,YAAY,GAAG;QACnB,GAAG,SAAS;QACZ,MAAM,EAAE,YAAY;QACpB,KAAK,EAAE,SAAS,CAAC,KAAK,IAAI,kBAAkB;QAC5C,YAAY,EAAE,KAAc;KAC7B,CAAC;IACF,OAAO,YAAY,CAAC,IAAI,CAAC;IACzB,OAAO,YAAY,CAAC,yBAAyB,CAAC;IAC9C,OAAO,IAAI,UAAU,CAAC,YAAY,CAAC,CAAC;AACtC,CAAC;AAED,MAAM,WAAW,GAAG;;;;;EAKlB,CAAC;AAEH,MAAM,UAAU,IAAI,CAAC,cAAsB;IACzC,yDAAyD;IACzD,IAAI,CAAC,cAAc,CAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC;QACtC,MAAM,IAAI,KAAK,CAAC,gCAAgC,CAAC,CAAC;IACpD,CAAC;IAED,gCAAgC,CAAC,cAAc,EAAE,WAAW,CAAC,CAAC;IAC9D,cAAc,CACZ,2BAA2B,cAAc,qCAAqC;QAC5E,gDAAgD,CACnD,CAAC;AACJ,CAAC"}

package/dist/providers/modelDiscovery.d.ts

@@ -0,0 +1,196 @@
+/**
+ * @packageDocumentation
+ * Provider / API-key detection and per-provider model listing.
+ *
+ * This is the data layer that powers the first-run configuration dialog (CFG-2),
+ * ACP model selection (CFG-5) and downstream propagation (CFG-6). It answers two
+ * questions without ever instantiating an LLM:
+ *
+ * 1. **Which providers are usable on this machine?** — by inspecting the
+ *    environment (and config) for API keys, and by probing for a local Ollama.
+ * 2. **What models does each usable provider offer?** — a live `GET /v1/models`
+ *    query for providers that expose an OpenAI-compatible (or, for Anthropic, a
+ *    native) models endpoint, falling back to a curated ⭐ "preferred" / tested
+ *    list when the live query is unavailable, errors, or is empty.
+ *
+ * Live discovery (CFG-12) is best-effort and never fatal: a bad key, an offline
+ * machine, or a malformed response simply degrades to the curated catalog so the
+ * first-run dialog always has something to show. The curated `preferredModels`
+ * therefore do double duty — the ⭐ ranking overlay over live ids **and** the
+ * offline/timeout fallback.
+ *
+ * The provider ids here are the same strings used by {@link LLMConfig.type} and
+ * the provider factory in `#src/providers/<type>.js`, so a selected
+ * `{ providerId, model }` maps directly onto a `RawGthConfig.llm`.
+ */
+import { type ConfigType } from '#src/config.js';
+/**
+ * Provider identifiers understood by model discovery. These match the provider
+ * factory module names (`#src/providers/<id>.js`) and {@link LLMConfig.type},
+ * plus `ollama` for locally-served models.
+ */
+export type ProviderId = ConfigType | 'ollama';
+/**
+ * A single model offered by a provider.
+ */
+export interface ModelInfo {
+    /** Model id as it should be written into config (`llm.model`). */
+    id: string;
+    /**
+     * Whether this is a ⭐ "preferred" / tested model. The first-run dialog
+     * should surface preferred models first / pre-selected.
+     */
+    preferred: boolean;
+}
+/**
+ * How a provider's live model catalog can be queried.
+ *
+ * - `openai`  — an OpenAI-compatible `GET /v1/models` (`{ data: [{ id }] }`).
+ *   Covers openai, openrouter, groq, deepseek, xai and ollama (local).
+ * - `anthropic` — Anthropic's native `GET /v1/models`
+ *   (`{ data: [{ type, id, display_name }] }`) with `x-api-key` auth.
+ * - `none`     — no cheap live endpoint; stay on the curated list
+ *   (google-genai, vertexai).
+ */
+export type DiscoveryKind = 'openai' | 'anthropic' | 'none';
+/**
+ * Per-provider live-discovery adapter. Bundled on the {@link ProviderDescriptor}
+ * so {@link discoverModels} can be fully data-driven.
+ */
+export interface DiscoveryConfig {
+    kind: DiscoveryKind;
+    /**
+     * The models endpoint to fetch. `host` is supplied only for ollama (the
+     * resolved daemon host); cloud providers ignore it and return a fixed URL.
+     */
+    modelsUrl?: (host?: string) => string;
+    /** Build the auth headers from the resolved API key (may be empty for ollama). */
+    authHeader?: (key: string) => Record<string, string>;
+    /**
+     * Keep only chat-capable model ids. Live endpoints return embeddings, TTS,
+     * whisper, image, guard, etc. alongside chat models; this prunes them.
+     * When omitted, all returned ids are kept.
+     */
+    filter?: (id: string) => boolean;
+}
+/**
+ * Static description of a provider: how to detect its key, how to discover its
+ * live models, and which models we recommend. Used to build
+ * {@link DetectedProvider}s.
+ */
+export interface ProviderDescriptor {
+    id: ProviderId;
+    /** Human-friendly name for dialogs. */
+    label: string;
+    /**
+     * Environment variables that, when set to a non-empty value, indicate this
+     * provider has a usable API key. Checked in order; the first match wins.
+     * Empty for providers that don't authenticate via an env var (`vertexai`,
+     * which uses gcloud ADC, and `ollama`, which is local).
+     */
+    apiKeyEnvironmentVariables: string[];
+    /**
+     * Curated ⭐ "preferred" / tested models for this provider, most-recommended
+     * first. Used as the ⭐ ranking overlay over live-discovered ids and as the
+     * fallback catalog when live discovery is unavailable.
+     */
+    preferredModels: string[];
+    /** Live-discovery adapter for this provider. */
+    discovery: DiscoveryConfig;
+    /**
+     * True when usability cannot be determined from an env var alone.
+     * `vertexai` relies on gcloud Application Default Credentials and `ollama`
+     * on a running local daemon, so both are reported as `available: false` by
+     * env inspection (ollama is then confirmed by a live probe in
+     * {@link detectProviders}).
+     */
+    requiresExternalAuth?: boolean;
+}
+/** Default Ollama host, matching the Ollama CLI/library default. */
+export declare const DEFAULT_OLLAMA_HOST = "http://127.0.0.1:11434";
+/**
+ * Provider registry. The curated `preferredModels` are the models we have
+ * tested with Gaunt Sloth's agent loop; defaults mirror the `init` templates in
+ * each `#src/providers/<id>.js` factory.
+ */
+export declare const PROVIDER_DESCRIPTORS: readonly ProviderDescriptor[];
+/**
+ * Result of detecting one provider.
+ */
+export interface DetectedProvider {
+    id: ProviderId;
+    label: string;
+    /**
+     * True when the provider looks usable on this machine: an API key env var is
+     * set, or (for ollama) a local daemon responded.
+     */
+    available: boolean;
+    /**
+     * The environment variable that supplied the key, when {@link available} via
+     * an env var. Undefined for env-less providers (vertexai, ollama).
+     */
+    apiKeyEnvironmentVariable?: string;
+    /** True when this provider authenticates outside of an env var. */
+    requiresExternalAuth: boolean;
+    /** Models offered by this provider, ⭐ preferred ones flagged. */
+    models: ModelInfo[];
+}
+/**
+ * Resolve the API key for a cloud provider by checking its env vars in order.
+ * @returns the matching env var name, or undefined when none is set.
+ */
+export declare function findApiKeyEnvVar(descriptor: ProviderDescriptor): string | undefined;
+/**
+ * Build the {@link ModelInfo} list for a provider given the descriptor and an
+ * optional set of model ids known to actually exist (e.g. from a live
+ * `/v1/models` query or the local Ollama daemon).
+ *
+ * - When `discoveredModels` is omitted, the curated `preferredModels` are
+ *   returned, all flagged ⭐ preferred.
+ * - When provided, every discovered model is listed; those that also appear in
+ *   the curated `preferredModels` are flagged ⭐ preferred.
+ */
+export declare function buildModelList(descriptor: ProviderDescriptor, discoveredModels?: string[]): ModelInfo[];
+/**
+ * Discover the models for a single provider.
+ *
+ * - `kind: 'none'` → returns the curated `buildModelList(descriptor)`.
+ * - `kind: 'openai' | 'anthropic'` → fetches the models endpoint with a short
+ *   timeout, parses `data[].id`, applies the chat-only `filter`, and overlays
+ *   the ⭐ preferred flags via `buildModelList(descriptor, liveIds)`.
+ *
+ * Best-effort: any error / non-2xx / malformed / empty payload falls back to
+ * the curated list. This function NEVER throws — a bad key must degrade to the
+ * curated catalog, not break first-run config.
+ *
+ * Cloud providers are only probed live when an API key is present; without a key
+ * the curated catalog is returned directly. Ollama (no key, local daemon) is
+ * always probed.
+ */
+export declare function discoverModels(providerId: ProviderId): Promise<ModelInfo[]>;
+/**
+ * List the models for a single provider.
+ *
+ * Live-discovers from the provider's models endpoint where possible (with a
+ * curated fallback); returns the curated set for `kind: 'none'` providers. Does
+ * not require the provider to be "available".
+ */
+export declare function listModels(providerId: ProviderId): Promise<ModelInfo[]>;
+/**
+ * Detect every known provider on this machine and list its models.
+ *
+ * - Cloud providers are `available` when one of their API-key env vars is set;
+ *   their model list is live-discovered (curated fallback) when a key is present.
+ * - `vertexai` is reported with `requiresExternalAuth: true` and
+ *   `available: false`; usability via gcloud ADC cannot be cheaply verified
+ *   here and is left to the caller / a live run.
+ * - `ollama` is `available` when the local daemon's `/v1/models` responds, and
+ *   its model list is that live inventory.
+ *
+ * @param options.includeUnavailable when true (default), every provider is
+ *   returned (so a dialog can offer "set a key" flows); when false, only
+ *   available providers are returned.
+ */
+export declare function detectProviders(options?: {
+    includeUnavailable?: boolean;
+}): Promise<DetectedProvider[]>;