@gaunt-sloth/core 0.0.1

package/.gsloth.backstory.md

@@ -0,0 +1,17 @@
+Your name is Gaunt Sloth, a programmer with comprehensive expertise across programming languages. Maintain a
+professional, direct communication style. Begin responses with substance, not pleasantries or self-promotion.
+
+Your priority is code correctness and bug prevention over social niceties, though you remain courteous in all
+interactions. Focus on technical accuracy and practical solutions.
+
+Use visual indicators when providing feedback:
+
+- ✅ for correct implementations (and approvals)
+- ⚠️ for potential issues or areas needing attention
+- ❌ for errors or problematic approaches (and rejections)
+
+You may enhance communication with relevant emojis throughout your responses to improve clarity and readability,
+but do not include foolish smiley faces.
+
+Never include decorative emojis within code snippets — only use them in code when they're part of the actual
+logic, string literals, or were present in the original code being discussed.

package/.gsloth.chat.md

@@ -0,0 +1,11 @@
+# Chat Mode Instructions
+
+You are a helpful AI assistant engaged in a conversational chat session. Your role is to:
+
+- Provide informative, accurate, and helpful responses to user queries
+- Maintain context throughout the conversation
+- Be conversational and friendly while remaining professional
+- Ask clarifying questions when needed to better understand the user's intent
+- Provide examples and explanations when appropriate
+
+Remember that this is an interactive chat session, so keep your responses concise and engaging. Focus on being helpful while maintaining a natural conversational flow.

package/.gsloth.code.md

@@ -0,0 +1,27 @@
+# Code Mode Instructions
+
+You are an AI coding assistant with full file system access within the user's project. Your role is to:
+
+- Help write, modify, and debug code
+- Understand and work with the existing codebase
+- Follow project conventions and best practices
+- Create, read, update, and delete files as needed to complete coding tasks
+- Run commands and scripts to test and validate changes
+- Provide clear explanations of the changes you make
+
+You have access to the entire project directory and can:
+- Navigate the file system
+- Read and analyze existing code
+- Make modifications to implement features or fix bugs
+- Create new files and directories as needed
+- Execute commands to run tests, build the project or run static analysis (lint)
+
+Focus on writing clean, maintainable code that follows the project's established patterns and conventions. Always test your changes when possible and explain what you're doing and why.
+
+## Running tests
+
+- When working on functionality always prefer running a single test, over the entire suite;
+- Abstain from running tests in circles, run the test once, if it fails — inspect the output carefully and try to fix it;
+- Run full tests suite as a penultimate step, when everything is fixed, but before running the lint;
+- Run lint only as a final step when everything else is fixed;
+- If nothing seems to work, ask for user's assistance;

package/.gsloth.guidelines.md

@@ -0,0 +1 @@
+

package/.gsloth.review.md

@@ -0,0 +1,15 @@
+If requirements were provided, first check that the implemented code implements these requirements.
+Document that you checked the code to implement requirements.
+Reject the change if it appears to implement something else instead of required change.
+
+Provide specific feedback on any areas of concern or suggestions for improvement.
+Please categorize your feedback (e.g., "Bug," "Suggestion," "Nitpick").
+
+Important! In the end, conclude if you would recommend approving this PR or not.
+Use ✅⚠️❌ symbols to highlight your feedback appropriately.
+
+Finish with a short 1-2 sentence summary that captures the overall state of the review.
+
+Thank you for your thorough review!
+
+Important! You are likely to be dealing with git diff below, please don't confuse removed and added lines.

package/.gsloth.system.md

@@ -0,0 +1,10 @@
+# Filesystem Context
+
+When the user mentions directories and files without specifying an exact location, this is likely referring to files in the current working directory (`.`).
+
+For example:
+- "Read the config file" likely means a configuration file in the current directory
+- "Check the tests" likely refers to test files in the current project
+- "Look at the source code" typically means source files in the current directory structure
+
+Always consider the current working directory as the default context for file operations unless the user specifies an absolute path or different location.

package/README.md

@@ -0,0 +1,27 @@
+# @gaunt-sloth/core
+
+Core utilities and types for Gaunt Sloth.
+
+## Contents
+
+- Configuration system (`GthConfig`, `RawGthConfig`, config loading and post-processing)
+- Agent infrastructure: `GthLangChainAgent`, `GthAgentRunner`
+- LLM provider wrappers: anthropic, deepseek, google-genai, groq, openai, openrouter, vertexai, xai, fake
+- Utility modules: `consoleUtils`, `debugUtils`, `fileUtils`, `llmUtils`, `systemUtils`, `stringUtils`, `aiignoreUtils`, `binaryOutputUtils`, `vertexaiUtils`, `globalConfigUtils`, `ProgressIndicator`
+- State and artifact storage: `artifactStore`
+- Shared constants and types
+
+AI vendor packages are not direct dependencies. Each vendor package is an optional peer dependency, resolved at runtime by whichever consumer (e.g. `gaunt-sloth-assistant`) pulls them in.
+
+## Dependencies
+
+No other `@gaunt-sloth/*` packages.
+
+## Exports
+
+All modules are exported via the `./` export map pattern (`./*.js`), e.g.:
+
+```js
+import { GthAgentRunner } from '@gaunt-sloth/core/agentRunner.js';
+import { display } from '@gaunt-sloth/core/utils/consoleUtils.js';
+```

package/dist/config.d.ts

@@ -0,0 +1,533 @@
+import { StatusLevel } from '#src/core/types.js';
+import type { BaseChatModel } from '@langchain/core/language_models/chat_models';
+import type { BaseToolkit, StructuredToolInterface } from '@langchain/core/tools';
+/**
+ * This is a processed Gaunt Sloth config ready to be passed down into components.
+ *
+ * Default values can be found in {@link DEFAULT_CONFIG}
+ */
+export interface GthConfig {
+    llm: BaseChatModel;
+    /**
+     * Binary format support configuration.
+     * Disabled by default unless explicitly configured.
+     */
+    binaryFormats?: false | BinaryFormatConfig[];
+    /**
+     * Content Provider. Provider used to fetch content (usually diff) for `review` or `pr` command.
+     *
+     * {@link DEFAULT_CONFIG#contentProvider}
+     */
+    /**
+     * Content source type. Preferred name for contentProvider.
+     */
+    contentSource: string;
+    /**
+     * Requirement source type. Preferred name for requirementsProvider.
+     */
+    requirementSource: string;
+    /**
+     * @deprecated Use contentSource instead
+     */
+    contentProvider: string;
+    /**
+     * @deprecated Use requirementSource instead
+     */
+    requirementsProvider: string;
+    /**
+     * Path to project-specific guidelines.
+     * The default is `.gsloth.guidelines.md`; this config may be used to point Gaunt Sloth to a different file,
+     * for example, to AGENTS.md
+     */
+    projectGuidelines: string;
+    /**
+     * Separate identity profile.
+     * May include separate identity, guidelines and command protocol,
+     * making gsloth behave as an agent different from default profile behaviour.
+     * for example, `devops` profile to detect changes such as properties and environment variables.
+     * Custom config can still win over this one.
+     * This setting requires .gsloth/.gsloth-settings directory to exist.
+     */
+    identityProfile?: string;
+    /**
+     * Whether to include the current date in the project review instructions or not.
+     */
+    includeCurrentDateAfterGuidelines: boolean;
+    /**
+     * Organisation name, locale and timezone.
+     * Only used with {@link includeCurrentDateAfterGuidelines}.
+     * timeZone and locale should be in format supported by Intl.DateTimeFormat
+     */
+    organization?: {
+        name?: string;
+        locale?: string;
+        timezone?: string;
+    };
+    projectReviewInstructions: string;
+    /**
+     * If true, only use user-provided system prompts. Do not fall back to the
+     * bundled `.gsloth.*.md` prompt files shipped with the installation.
+     * This applies to all `.gsloth.*.md` files (backstory, system, chat, code, guidelines, review).
+     */
+    noDefaultPrompts?: boolean;
+    filesystem: string[] | 'all' | 'read' | 'none';
+    builtInTools?: string[];
+    tools?: StructuredToolInterface[] | BaseToolkit[] | ServerTool[];
+    /**
+     * Middleware configuration for LangChain v1.
+     * Middleware provides hooks to intercept and control agent execution at critical points.
+     *
+     * Middleware can be:
+     * - Predefined middleware (string or config object) - works in both JSON and JS configs
+     * - Custom middleware objects - only available in JS configs
+     *
+     * Example (JSON config):
+     * ```json
+     * {
+     *   "middleware": [
+     *     "summarization",
+     *     { "name": "anthropic-prompt-caching", "ttl": "5m" }
+     *   ]
+     * }
+     * ```
+     *
+     * Example (JS config):
+     * ```js
+     * {
+     *   middleware: [
+     *     "summarization",
+     *     { beforeModel: (state) => { /* custom logic *\/ return state; } }
+     *   ]
+     * }
+     * ```
+     *
+     * Available predefined middleware:
+     * - `anthropic-prompt-caching`: Reduces API costs by caching prompts (Anthropic only)
+     * - `summarization`: Condenses conversation history when approaching token limits
+     */
+    middleware?: unknown[];
+    /**
+     * Stream output. Some models do not support streaming. Set value to `false` for them.
+     *
+     * {@link DEFAULT_CONFIG#streamOutput}
+     */
+    streamOutput: boolean;
+    /**
+     * Should the output be written to md file.
+     * (e.g. gth_2025-07-26_22-59-06_REVIEW.md).
+     * Can be set to false with `-wn` or `-w0`
+     * Can be set to a specific filename or path by passing a string:
+     * - Bare filenames (e.g. `"review.md"`) are placed in `.gsloth/` when it exists, otherwise project root
+     * - Paths with separators (e.g. `"./review.md"` or `"reviews/last.md"`) are always relative to project root
+     * Please note the string does not accept absolute path, but allows to exit project with `..` if necessary.
+     */
+    writeOutputToFile: boolean | string;
+    /**
+     * Whether binary model outputs should be written to files instead of printed inline.
+     * When enabled, supported binary content blocks are materialized as `gth_*.<ext>` files.
+     */
+    writeBinaryOutputsToFile: boolean;
+    /**
+     * Use colour in output
+     */
+    useColour: boolean;
+    /**
+     * Stream session log instead of writing it when inference streaming is complete.
+     * (only works when {@link streamOutput} is true)
+     */
+    streamSessionInferenceLog: boolean;
+    /**
+     * Allow inference to be interrupted with esc. Only has an effect in TTY mode.
+     */
+    canInterruptInferenceWithEsc: boolean;
+    /**
+     * Log messages and events to gaunt-sloth.log,
+     * use llm.verbose or `gth --verbose` as more intrusive option, setting verbose to LangChain / LangGraph
+     */
+    debugLog?: boolean;
+    /**
+     * Console logging level. Only messages at or above this level will be displayed.
+     * Valid values: 'debug', 'info', 'display', 'success', 'warning', 'error', 'stream'
+     * Default: 'info' (not debug)
+     */
+    consoleLevel?: StatusLevel;
+    customTools?: CustomToolsConfig;
+    requirementSourceConfig?: Record<string, unknown>;
+    contentSourceConfig?: Record<string, unknown>;
+    /** @deprecated Use requirementSourceConfig instead */
+    requirementsProviderConfig?: Record<string, unknown>;
+    /** @deprecated Use contentSourceConfig instead */
+    contentProviderConfig?: Record<string, unknown>;
+    /**
+     * MCP (Model Context Protocol) server connections.
+     * Allows connecting to external MCP servers including those requiring OAuth.
+     * @see {@link https://modelcontextprotocol.io/}
+     */
+    mcpServers?: Record<string, unknown>;
+    /**
+     * A2A (Agent-to-Agent) protocol agents configuration.
+     * Enables delegation of tasks to external AI agents.
+     * Each agent becomes available as a tool named `a2a_agent_<agentId>`.
+     * @experimental This feature is experimental and may change.
+     * @see {@link https://a2a-protocol.org/}
+     */
+    a2aAgents?: Record<string, unknown>;
+    builtInToolsConfig?: BuiltInToolsConfig;
+    aiignore?: {
+        enabled?: boolean;
+        patterns?: string[];
+    };
+    commands?: {
+        pr?: {
+            contentSource?: string;
+            requirementSource?: string;
+            /** @deprecated Use contentSource instead */
+            contentProvider?: string;
+            /** @deprecated Use requirementSource instead */
+            requirementsProvider?: string;
+            filesystem?: string[] | 'all' | 'read' | 'none';
+            builtInTools?: string[];
+            customTools?: CustomToolsConfig | false;
+            logWorkForReviewInSeconds?: number;
+            rating?: RatingConfig;
+            binaryFormats?: false | BinaryFormatConfig[];
+        };
+        review?: {
+            contentSource?: string;
+            requirementSource?: string;
+            /** @deprecated Use requirementSource instead */
+            requirementsProvider?: string;
+            /** @deprecated Use contentSource instead */
+            contentProvider?: string;
+            filesystem?: string[] | 'all' | 'read' | 'none';
+            builtInTools?: string[];
+            customTools?: CustomToolsConfig | false;
+            rating?: RatingConfig;
+            binaryFormats?: false | BinaryFormatConfig[];
+        };
+        ask?: {
+            filesystem?: string[] | 'all' | 'read' | 'none';
+            builtInTools?: string[];
+            customTools?: CustomToolsConfig | false;
+            binaryFormats?: false | BinaryFormatConfig[];
+        };
+        chat?: {
+            filesystem?: string[] | 'all' | 'read' | 'none';
+            builtInTools?: string[];
+            customTools?: CustomToolsConfig | false;
+            binaryFormats?: false | BinaryFormatConfig[];
+        };
+        code?: {
+            filesystem?: string[] | 'all' | 'read' | 'none';
+            builtInTools?: string[];
+            customTools?: CustomToolsConfig | false;
+            devTools?: GthDevToolsConfig;
+            binaryFormats?: false | BinaryFormatConfig[];
+        };
+        api?: {
+            filesystem?: string[] | 'all' | 'read' | 'none';
+            builtInTools?: string[];
+            port?: number;
+            cors?: {
+                allowOrigin?: string;
+                allowMethods?: string;
+                allowHeaders?: string;
+            };
+        };
+    };
+    modelDisplayName?: string;
+}
+/**
+ * Server tools such as Anthropic Web Search.
+ * These tools are meant to be magic objects like
+ * `{"type": "web_search_20250305", "name": "web_search", "max_uses": 10}`,
+ * AI Provider does the rest of the magic on their side.
+ */
+export interface ServerTool extends Record<string, unknown> {
+    type: string;
+    name?: string;
+}
+/**
+ * Raw, unprocessed Gaunt Sloth config.
+ */
+export type ConsoleLevelInput = StatusLevel | keyof typeof StatusLevel | Lowercase<keyof typeof StatusLevel>;
+export interface RawGthConfig extends Omit<GthConfig, 'llm' | 'consoleLevel'> {
+    llm: LLMConfig;
+    consoleLevel?: ConsoleLevelInput;
+}
+export type BinaryFormatType = 'image' | 'file' | 'audio' | 'video' | 'binary';
+export interface BinaryFormatConfig {
+    /**
+     * The type/category of binary format.
+     */
+    type: BinaryFormatType;
+    /**
+     * List of allowed extensions for this type (without leading dot).
+     */
+    extensions: string[];
+    /**
+     * Maximum file size in bytes. Defaults to 10MB when omitted.
+     */
+    maxSize?: number;
+    /**
+     * Optional MIME type overrides for extensions not in the default mapping.
+     */
+    mimeTypes?: Record<string, string>;
+}
+export type CustomToolsConfig = Record<string, CustomCommandConfig>;
+export type BuiltInToolsConfig = Record<string, unknown>;
+/**
+ * Configuration for review rating feature.
+ * Allows configuring automated review scoring with pass/fail thresholds.
+ */
+export interface RatingConfig {
+    /**
+     * Enable or disable review rating.
+     * @default true
+     */
+    enabled?: boolean;
+    /**
+     * Minimum score (0-10) required to pass the review.
+     * @default 6
+     */
+    passThreshold?: number;
+    /**
+     * Highest allowed value on the rating scale.
+     * @default 10
+     */
+    maxRating?: number;
+    /**
+     * Lowest allowed value on the rating scale.
+     * @default 0
+     */
+    minRating?: number;
+    /**
+     * Exit with error code 1 when review fails (below threshold).
+     * When false, exits normally (code 0) regardless of rating.
+     * @default true
+     */
+    errorOnReviewFail?: boolean;
+}
+/**
+ * Validation checks that can be skipped for custom command parameters.
+ * Use with the `allow` property to bypass specific security checks.
+ *
+ * - `absolute-paths`: Allow absolute paths (e.g. `/dev/ttyUSB0`)
+ * - `directory-traversal`: Allow `..` in paths
+ * - `shell-injection`: Allow shell metacharacters (`|`, `&`, `;`, etc.)
+ * - `null-bytes`: Allow null bytes in values
+ */
+export type ValidationCheck = 'absolute-paths' | 'directory-traversal' | 'shell-injection' | 'null-bytes';
+/**
+ * Configuration for a custom command parameter.
+ * Parameters allow the model to provide dynamic values to commands.
+ */
+export interface CustomCommandParameter {
+    /**
+     * Description of the parameter shown to the model.
+     */
+    description: string;
+    /**
+     * Optional list of validation checks to skip for this parameter's value.
+     * Use when this parameter legitimately requires values that would normally be blocked.
+     * For example, `["absolute-paths"]` allows values like `/dev/ttyUSB0` for this parameter.
+     *
+     * Available checks: `absolute-paths`, `directory-traversal`, `shell-injection`, `null-bytes`
+     */
+    allow?: ValidationCheck[];
+}
+/**
+ * Configuration for a custom command.
+ * Custom commands can be executed with or without parameters.
+ */
+export interface CustomCommandConfig {
+    /**
+     * The shell command to execute.
+     * Can include placeholders like ${paramName} that will be replaced with parameter values.
+     * If no placeholder is present and parameters are provided, they are appended to the command.
+     */
+    command: string;
+    /**
+     * Description of what this command does, shown to the model.
+     */
+    description: string;
+    /**
+     * Optional parameters that the model can provide when calling this command.
+     * Each parameter has a name (the key) and a description.
+     * Parameters are validated for security (no shell injection, directory traversal, etc.).
+     */
+    parameters?: Record<string, CustomCommandParameter>;
+    /**
+     * Optional timeout in seconds.
+     * When set, the command will be killed if it exceeds this duration.
+     * When omitted, no timeout is applied.
+     */
+    timeout?: number;
+}
+/**
+ * Config for {@link GthDevToolkit}.
+ * Tools are not applied when config is not provided.
+ * Only available in `code` mode.
+ */
+export interface GthDevToolsConfig {
+    /**
+     * Optional shell command to run tests.
+     * Not applied when config is not provided.
+     */
+    run_tests?: string;
+    /**
+     * Optional shell command to run static analysis (lint).
+     * Not applied when config is not provided.
+     */
+    run_lint?: string;
+    /**
+     * Optional shell command to run the build.
+     * Not applied when config is not provided.
+     */
+    run_build?: string;
+    /**
+     * Optional shell command to run a single test file.
+     * Supports command interpolation with the `${testPath}` placeholder.
+     * Example: "npm test -- ${testPath}" or "jest ${testPath}"
+     * Example: "npm test" - the test will simply be appended
+     * Not applied when config is not provided.
+     */
+    run_single_test?: string;
+}
+export interface LLMConfig extends Record<string, unknown> {
+    type: string;
+    model: string;
+    configuration: Record<string, unknown>;
+    apiKeyEnvironmentVariable?: string;
+}
+export declare const availableDefaultConfigs: readonly ["vertexai", "anthropic", "groq", "deepseek", "openai", "google-genai", "xai", "openrouter"];
+export type ConfigType = (typeof availableDefaultConfigs)[number];
+export interface CommandLineConfigOverrides {
+    /**
+     * Custom config path
+     */
+    customConfigPath?: string;
+    /**
+     * Set LangChain/LangGraph to verbose mode,
+     * causing LangChain/LangGraph to log many details to the console.
+     * debugLog from config.ts may be a less intrusive option.
+     */
+    verbose?: boolean;
+    /**
+     * Should the output be written to md file.
+     * (e.g. gth_2025-07-26_22-59-06_REVIEW.md).
+     * Can be set to false with `-wn` or `-w0`
+     * Can be set to a specific filename or path by passing a string:
+     * - Bare filenames (e.g. `"review.md"`) are placed in `.gsloth/` when it exists, otherwise project root
+     * - Paths with separators (e.g. `"./review.md"` or `"reviews/last.md"`) are always relative to project root
+     * Please note the string does not accept absolute path, but allows to exit project with `..` if necessary.
+     */
+    writeOutputToFile?: boolean | string;
+    /**
+     * Separate identity profile.
+     * May include separate identity, guidelines and command protocol,
+     * making gsloth behave as an agent different from default profile behaviour.
+     * for example, `devops` profile to detect changes such as properties and environment variables.
+     * Custom config can still win over this one.
+     * This setting requires .gsloth/.gsloth-settings directory to exist.
+     * Important to note that the profile directory substitutes the entire config directory,
+     * in the case if some prompt files are missing - a file from the installation directory will be used.
+     */
+    identityProfile?: string;
+}
+/**
+ * Default config
+ */
+export declare const DEFAULT_CONFIG: {
+    readonly contentSource: "file";
+    readonly requirementSource: "file";
+    readonly contentProvider: "file";
+    readonly requirementsProvider: "file";
+    /**
+     * Path to project-specific guidelines.
+     * The default is `.gsloth.guidelines.md`; this config may be used to point Gaunt Sloth to a different file,
+     * for example, to AGENTS.md
+     */
+    readonly projectGuidelines: ".gsloth.guidelines.md";
+    /**
+     * Whether to include the current date in the project review instructions or not.
+     */
+    readonly includeCurrentDateAfterGuidelines: false;
+    readonly projectReviewInstructions: ".gsloth.review.md";
+    readonly filesystem: "none";
+    readonly debugLog: false;
+    readonly consoleLevel: StatusLevel.INFO;
+    /**
+     * Default provider for both requirements and content is GitHub.
+     * It needs GitHub CLI (gh).
+     *
+     * `github` content provider uses `gh pr diff NN` internally. {@link src/providers/ghPrDiffProvider.ts!}
+     *
+     *
+     * `github` requirements provider `gh issue view NN` internally
+     */
+    readonly commands: {
+        readonly pr: {
+            readonly contentSource: "github";
+            readonly requirementSource: "github";
+            readonly contentProvider: "github";
+            readonly requirementsProvider: "github";
+            readonly rating: {
+                readonly enabled: true;
+                readonly passThreshold: 6;
+                readonly minRating: 0;
+                readonly maxRating: 10;
+                readonly errorOnReviewFail: true;
+            };
+        };
+        readonly review: {
+            readonly rating: {
+                readonly enabled: true;
+                readonly passThreshold: 6;
+                readonly minRating: 0;
+                readonly maxRating: 10;
+                readonly errorOnReviewFail: true;
+            };
+        };
+        readonly ask: {
+            readonly filesystem: "read";
+        };
+        readonly chat: {
+            readonly filesystem: "read";
+        };
+        readonly code: {
+            readonly filesystem: "all";
+        };
+        readonly api: {
+            readonly filesystem: "read";
+            readonly port: 3000;
+            readonly cors: {
+                readonly allowOrigin: "http://localhost:3000";
+                readonly allowMethods: "POST, GET, OPTIONS";
+                readonly allowHeaders: "Content-Type, Accept";
+            };
+        };
+    };
+    readonly streamOutput: true;
+    readonly writeOutputToFile: true;
+    readonly writeBinaryOutputsToFile: true;
+    readonly useColour: true;
+    readonly streamSessionInferenceLog: true;
+    readonly canInterruptInferenceWithEsc: true;
+    readonly aiignore: {
+        readonly enabled: true;
+        readonly patterns: undefined;
+    };
+};
+/**
+ * Initialize configuration by loading from available config files
+ * @returns The loaded GthConfig
+ */
+export declare function initConfig(commandLineConfigOverrides: CommandLineConfigOverrides): Promise<GthConfig>;
+/**
+ * Process JSON LLM config by creating the appropriate LLM instance
+ * @param jsonConfig - The parsed JSON config
+ * @param commandLineConfigOverrides - command line config overrides
+ * @returns Promise<GthConfig>
+ */
+export declare function tryJsonConfig(jsonConfig: RawGthConfig, commandLineConfigOverrides: CommandLineConfigOverrides): Promise<GthConfig>;