@gaunt-sloth/core 2.0.0-alpha.3 → 2.0.0-alpha.30

package/README.md

@@ -1,34 +1,66 @@
 # @gaunt-sloth/core
 
-Core utilities and types for Gaunt Sloth.
+The foundation layer of Gaunt Sloth: the configuration system (`GthConfig`, config discovery and
+loading, the JSON schema), the LLM provider factory (anthropic, deepseek, google-genai, groq,
+huggingface, ollama, openai, openrouter, vertexai, xai, fake), the lean LangChain agent runtime
+(`GthAgentRunner`), session history, and the shared utility modules (`consoleUtils`,
+`systemUtils`, `fileUtils`, `llmUtils`, …).
 
-## Contents
+**When to depend on this package** — you are embedding a piece of Gaunt Sloth (or building your
+own front-end on its infrastructure) and need its config resolution and provider wiring without
+the CLI. Every other `@gaunt-sloth/*` package builds on it. If you just want to use Gaunt Sloth
+from the terminal, install the [`gaunt-sloth`](https://www.npmjs.com/package/gaunt-sloth) app
+instead.
 
-- 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
+## Installation
 
-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`) pulls them in.
+AI vendor packages are optional peer dependencies — install the provider(s) your configuration
+uses alongside core:
 
-## Dependencies
-
-No other `@gaunt-sloth/*` packages.
+```bash
+npm install @gaunt-sloth/core @langchain/anthropic
+```
 
-## Exports
+## Embedding: resolve config into a live model
 
-All modules are exported via the `./` export map pattern (`./*.js`), e.g.:
+I want my script to honour the user's `.gsloth.config.*` (provider, model, API keys) instead of
+hard-coding a vendor SDK. With a `.gsloth.config.json` such as
+`{ "llm": { "type": "anthropic", "model": "claude-sonnet-4-5" } }` in the working directory:
 
 ```js
-import { GthAgentRunner } from '@gaunt-sloth/core/agentRunner.js';
-import { display } from '@gaunt-sloth/core/utils/consoleUtils.js';
+import { initConfig } from '@gaunt-sloth/core';
+
+const config = await initConfig({}); // discovers .gsloth.config.* up-tree from cwd
+// config.llm is a live LangChain chat model built from that config
+const response = await config.llm.invoke('Say hello');
+console.log(response.text);
 ```
 
+When the configured provider has no API key anywhere — not in `llm.apiKey`, not in
+`llm.apiKeyEnvironmentVariable`, not in any variable that provider accepts — `initConfig` rejects
+with a `MissingProviderKeyError` carrying `provider` and `envVars`, so a caller running several
+configs can report which one lacked a secret and carry on with the rest. Use
+`isMissingProviderKeyError(error)` to recognise it.
+
+All config keys (providers, prompts, tools, per-command settings) are documented in
+[the configuration guide](https://github.com/pukeko-robotics/gaunt-sloth/blob/main/docs/configuration/index.md).
+
+## Exports
+
+- `@gaunt-sloth/core` (the root export) is the public API: config
+  (`initConfig`, `GthConfig`, defaults), constants, core types, the lean agent factory, model
+  discovery, and session history.
+- `@gaunt-sloth/core/<path>.js` deep paths (e.g. `@gaunt-sloth/core/config.js`,
+  `@gaunt-sloth/core/utils/consoleUtils.js`) mirror the internal `dist/` layout 1:1 and are a
+  deliberate part of the contract — the other `@gaunt-sloth/*` packages and downstream consumers
+  import them directly. They are supported at your own risk: internal files can move between
+  alpha/minor versions without a deprecation cycle. Prefer the root export where it suffices.
+
+This package ships no binaries.
+
 ## Related packages
 
-- [`@gaunt-sloth/core`](../core) — Core utilities, config, and agent infrastructure (this package)
-- [`@gaunt-sloth/agent`](../agent) — Agent runtime: built-in tools, filesystem toolkit, middleware registry, API server, AG-UI, MCP, and A2A integration
-- [`@gaunt-sloth/review`](../review) — Review and Q&A modules with standalone CLI
-- [`gaunt-sloth`](../app) — Main CLI application
+- [`@gaunt-sloth/agent`](https://www.npmjs.com/package/@gaunt-sloth/agent) — Agent runtime: built-in tools, filesystem toolkit, middleware registry, API server, AG-UI, MCP, and A2A integration ([source](https://github.com/pukeko-robotics/gaunt-sloth/tree/main/packages/agent))
+- [`@gaunt-sloth/review`](https://www.npmjs.com/package/@gaunt-sloth/review) — Review engine with content/requirement sources (GitHub, Jira, file, text) and standalone CLI ([source](https://github.com/pukeko-robotics/gaunt-sloth/tree/main/packages/review))
+- [`@gaunt-sloth/batch`](https://www.npmjs.com/package/@gaunt-sloth/batch) — Batch / eval / workflow runtime ([source](https://github.com/pukeko-robotics/gaunt-sloth/tree/main/packages/batch))
+- [`gaunt-sloth`](https://www.npmjs.com/package/gaunt-sloth) — Main CLI application ([source](https://github.com/pukeko-robotics/gaunt-sloth/tree/main/packages/app))

package/dist/config/colour.d.ts

@@ -0,0 +1,38 @@
+/**
+ * CFG-30 — the single place that decides whether Gaunt Sloth emits ANSI colour.
+ *
+ * Everything this decision depends on arrives as an argument: no `process.env`, no `stdout`, no
+ * config merge. That keeps the ladder unit-testable rung by rung without touching process globals,
+ * and keeps the one mutation site ({@link setUseColour}, called from `mergeConfig`) unchanged.
+ */
+/** Everything the colour decision depends on. See {@link resolveUseColour}. */
+export interface UseColourInput {
+    /**
+     * Raw `FORCE_COLOR` environment value; `undefined` when the variable is not set at all.
+     * The empty string is a SET value (`FORCE_COLOR=` on the command line) and means colour on.
+     */
+    forceColor?: string;
+    /** Raw `NO_COLOR` environment value; `undefined` when the variable is not set at all. */
+    noColor?: string;
+    /**
+     * `useColour` as the user actually wrote it — read from the RAW config, BEFORE `DEFAULT_CONFIG`
+     * is merged in. `undefined` means the user set nothing, which is what rung 3 tests for; after the
+     * default merge an explicit `true` is indistinguishable from the default `true`, so this value
+     * must be captured pre-merge or the rung collapses.
+     */
+    explicitUseColour?: boolean;
+    /** Whether stdout is a terminal. Rung 4's auto-detection; stdout, not stdin. */
+    stdoutIsTTY: boolean;
+}
+/**
+ * Resolve the effective colour setting from the four-rung precedence ladder, highest wins:
+ *
+ *   1. `FORCE_COLOR` is set — `"0"` or `"false"` turn colour OFF, ANY other value (including the
+ *      empty string) turns it ON. This rung outranks everything below it, `NO_COLOR` included.
+ *   2. `NO_COLOR` is set and non-empty — colour OFF (the no-color.org convention: the variable's
+ *      presence is the signal, its value is not, but an empty value does not count as set).
+ *   3. `useColour` was set explicitly in config — use it verbatim.
+ *   4. Otherwise auto-detect — colour ON when stdout is a terminal, OFF when it is piped or
+ *      redirected, so captured output stays clean without any configuration.
+ */
+export declare function resolveUseColour(input: UseColourInput): boolean;

package/dist/config/colour.js

@@ -0,0 +1,36 @@
+/**
+ * CFG-30 — the single place that decides whether Gaunt Sloth emits ANSI colour.
+ *
+ * Everything this decision depends on arrives as an argument: no `process.env`, no `stdout`, no
+ * config merge. That keeps the ladder unit-testable rung by rung without touching process globals,
+ * and keeps the one mutation site ({@link setUseColour}, called from `mergeConfig`) unchanged.
+ */
+/**
+ * Resolve the effective colour setting from the four-rung precedence ladder, highest wins:
+ *
+ *   1. `FORCE_COLOR` is set — `"0"` or `"false"` turn colour OFF, ANY other value (including the
+ *      empty string) turns it ON. This rung outranks everything below it, `NO_COLOR` included.
+ *   2. `NO_COLOR` is set and non-empty — colour OFF (the no-color.org convention: the variable's
+ *      presence is the signal, its value is not, but an empty value does not count as set).
+ *   3. `useColour` was set explicitly in config — use it verbatim.
+ *   4. Otherwise auto-detect — colour ON when stdout is a terminal, OFF when it is piped or
+ *      redirected, so captured output stays clean without any configuration.
+ */
+export function resolveUseColour(input) {
+    // Rung 1 — FORCE_COLOR, the deliberate "I know what I am doing" override. Checked first so a
+    // user can force colour through a NO_COLOR inherited from their shell profile or a CI image.
+    if (input.forceColor !== undefined) {
+        return !(input.forceColor === '0' || input.forceColor === 'false');
+    }
+    // Rung 2 — NO_COLOR (no-color.org), honoured by chalk, ripgrep, fd and delta.
+    if (input.noColor !== undefined && input.noColor !== '') {
+        return false;
+    }
+    // Rung 3 — the user's own config. Only reachable with an explicit value, never the default.
+    if (input.explicitUseColour !== undefined) {
+        return input.explicitUseColour;
+    }
+    // Rung 4 — auto-detect.
+    return input.stdoutIsTTY;
+}
+//# sourceMappingURL=colour.js.map

package/dist/config/colour.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"colour.js","sourceRoot":"","sources":["../../src/config/colour.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAsBH;;;;;;;;;;GAUG;AACH,MAAM,UAAU,gBAAgB,CAAC,KAAqB;IACpD,6FAA6F;IAC7F,6FAA6F;IAC7F,IAAI,KAAK,CAAC,UAAU,KAAK,SAAS,EAAE,CAAC;QACnC,OAAO,CAAC,CAAC,KAAK,CAAC,UAAU,KAAK,GAAG,IAAI,KAAK,CAAC,UAAU,KAAK,OAAO,CAAC,CAAC;IACrE,CAAC;IAED,8EAA8E;IAC9E,IAAI,KAAK,CAAC,OAAO,KAAK,SAAS,IAAI,KAAK,CAAC,OAAO,KAAK,EAAE,EAAE,CAAC;QACxD,OAAO,KAAK,CAAC;IACf,CAAC;IAED,4FAA4F;IAC5F,IAAI,KAAK,CAAC,iBAAiB,KAAK,SAAS,EAAE,CAAC;QAC1C,OAAO,KAAK,CAAC,iBAAiB,CAAC;IACjC,CAAC;IAED,wBAAwB;IACxB,OAAO,KAAK,CAAC,WAAW,CAAC;AAC3B,CAAC"}

package/dist/config/defaults.d.ts

@@ -0,0 +1,84 @@
+/**
+ * @packageDocumentation
+ * Default Gaunt Sloth configuration ({@link DEFAULT_CONFIG}). Extracted verbatim from
+ * the former `config.ts` god-file; values are unchanged.
+ */
+import { StatusLevel } from '#src/core/types.js';
+/**
+ * Default config
+ */
+export declare const DEFAULT_CONFIG: {
+    readonly contentSource: 'file';
+    readonly requirementSource: 'file';
+    /**
+     * Whether to include the current date in the project review instructions or not.
+     */
+    readonly includeCurrentDateAfterGuidelines: false;
+    readonly filesystem: 'none';
+    readonly builtInTools: string[];
+    readonly debugLog: false;
+    readonly consoleLevel: StatusLevel.INFO;
+    /**
+     * Default source for both requirements and content is GitHub.
+     * It needs GitHub CLI (gh).
+     *
+     * `github` content source uses `gh pr diff NN` internally. {@link src/sources/ghPrDiffSource.ts!}
+     *
+     *
+     * `github` requirement source uses `gh issue view NN` internally
+     */
+    readonly commands: {
+        readonly pr: {
+            readonly contentSource: 'github';
+            readonly requirementSource: '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 exec: {
+            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: false;
+    readonly writeBinaryOutputsToFile: true;
+    readonly useColour: true;
+    readonly useMouse: true;
+    readonly streamSessionInferenceLog: true;
+    readonly canInterruptInferenceWithEsc: true;
+    readonly aiignore: {
+        readonly enabled: true;
+        readonly patterns: undefined;
+    };
+};

package/dist/config/defaults.js

@@ -0,0 +1,99 @@
+/**
+ * @packageDocumentation
+ * Default Gaunt Sloth configuration ({@link DEFAULT_CONFIG}). Extracted verbatim from
+ * the former `config.ts` god-file; values are unchanged.
+ */
+import { StatusLevel } from '#src/core/types.js';
+/**
+ * Default config
+ */
+export const DEFAULT_CONFIG = {
+    contentSource: 'file',
+    requirementSource: 'file',
+    // GS2-43: prompt segments (backstory/guidelines/system/chat/code/exec/review) are configured
+    // via the optional `prompts` object and DEFAULTED AT THE READ SITE (`readPromptSegment` falls
+    // back to each segment's default-named file), so `prompts` is intentionally absent here.
+    /**
+     * Whether to include the current date in the project review instructions or not.
+     */
+    includeCurrentDateAfterGuidelines: false,
+    filesystem: 'none',
+    // Enabled built-in tools. `gth_checklist` (the lean agent's planning/todo tool) and `gth_grep`
+    // (the permission-light content-search tool, GS2-51) are on by default across commands; a user
+    // `builtInTools` setting replaces this set entirely. Both are named to coexist with the deep
+    // backend's own `write_todos`/`grep` built-ins. Cast keeps it a mutable `string[]` under the
+    // surrounding `as const`.
+    builtInTools: ['gth_checklist', 'gth_grep'],
+    debugLog: false,
+    consoleLevel: StatusLevel.INFO, // Default to INFO level, not debug
+    /**
+     * Default source for both requirements and content is GitHub.
+     * It needs GitHub CLI (gh).
+     *
+     * `github` content source uses `gh pr diff NN` internally. {@link src/sources/ghPrDiffSource.ts!}
+     *
+     *
+     * `github` requirement source uses `gh issue view NN` internally
+     */
+    commands: {
+        pr: {
+            contentSource: 'github',
+            requirementSource: 'github',
+            rating: {
+                enabled: true,
+                passThreshold: 6,
+                minRating: 0,
+                maxRating: 10,
+                errorOnReviewFail: true,
+            },
+        },
+        review: {
+            rating: {
+                enabled: true,
+                passThreshold: 6,
+                minRating: 0,
+                maxRating: 10,
+                errorOnReviewFail: true,
+            },
+        },
+        ask: {
+            filesystem: 'read',
+        },
+        chat: {
+            filesystem: 'read',
+        },
+        code: {
+            filesystem: 'all',
+        },
+        exec: {
+            filesystem: 'all',
+        },
+        api: {
+            filesystem: 'read',
+            port: 3000,
+            cors: {
+                allowOrigin: 'http://localhost:3000',
+                allowMethods: 'POST, GET, OPTIONS',
+                allowHeaders: 'Content-Type, Accept',
+            },
+        },
+    },
+    streamOutput: true,
+    writeOutputToFile: false,
+    writeBinaryOutputsToFile: true,
+    useColour: true,
+    useMouse: true,
+    streamSessionInferenceLog: true,
+    canInterruptInferenceWithEsc: true,
+    aiignore: {
+        enabled: true,
+        patterns: undefined,
+    },
+};
+/**
+ * Needed DEFAULT_CONFIG to be plain const to be picked up by typedoc,
+ * this cast here is just for typecheck.
+ */
+// eslint-disable-next-line @typescript-eslint/no-unused-expressions
+DEFAULT_CONFIG;
+//# sourceMappingURL=defaults.js.map

package/dist/config/defaults.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"defaults.js","sourceRoot":"","sources":["../../src/config/defaults.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAGjD;;GAEG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG;IAC5B,aAAa,EAAE,MAAM;IACrB,iBAAiB,EAAE,MAAM;IACzB,6FAA6F;IAC7F,8FAA8F;IAC9F,yFAAyF;IACzF;;OAEG;IACH,iCAAiC,EAAE,KAAK;IACxC,UAAU,EAAE,MAAM;IAClB,+FAA+F;IAC/F,+FAA+F;IAC/F,6FAA6F;IAC7F,6FAA6F;IAC7F,0BAA0B;IAC1B,YAAY,EAAE,CAAC,eAAe,EAAE,UAAU,CAAa;IACvD,QAAQ,EAAE,KAAK;IACf,YAAY,EAAE,WAAW,CAAC,IAAI,EAAE,mCAAmC;IACnE;;;;;;;;OAQG;IACH,QAAQ,EAAE;QACR,EAAE,EAAE;YACF,aAAa,EAAE,QAAQ;YACvB,iBAAiB,EAAE,QAAQ;YAC3B,MAAM,EAAE;gBACN,OAAO,EAAE,IAAI;gBACb,aAAa,EAAE,CAAC;gBAChB,SAAS,EAAE,CAAC;gBACZ,SAAS,EAAE,EAAE;gBACb,iBAAiB,EAAE,IAAI;aACxB;SACF;QACD,MAAM,EAAE;YACN,MAAM,EAAE;gBACN,OAAO,EAAE,IAAI;gBACb,aAAa,EAAE,CAAC;gBAChB,SAAS,EAAE,CAAC;gBACZ,SAAS,EAAE,EAAE;gBACb,iBAAiB,EAAE,IAAI;aACxB;SACF;QACD,GAAG,EAAE;YACH,UAAU,EAAE,MAAM;SACnB;QACD,IAAI,EAAE;YACJ,UAAU,EAAE,MAAM;SACnB;QACD,IAAI,EAAE;YACJ,UAAU,EAAE,KAAK;SAClB;QACD,IAAI,EAAE;YACJ,UAAU,EAAE,KAAK;SAClB;QACD,GAAG,EAAE;YACH,UAAU,EAAE,MAAM;YAClB,IAAI,EAAE,IAAI;YACV,IAAI,EAAE;gBACJ,WAAW,EAAE,uBAAuB;gBACpC,YAAY,EAAE,oBAAoB;gBAClC,YAAY,EAAE,sBAAsB;aACrC;SACF;KACF;IACD,YAAY,EAAE,IAAI;IAClB,iBAAiB,EAAE,KAAK;IACxB,wBAAwB,EAAE,IAAI;IAC9B,SAAS,EAAE,IAAI;IACf,QAAQ,EAAE,IAAI;IACd,yBAAyB,EAAE,IAAI;IAC/B,4BAA4B,EAAE,IAAI;IAClC,QAAQ,EAAE;QACR,OAAO,EAAE,IAAI;QACb,QAAQ,EAAE,SAAS;KACpB;CACO,CAAC;AAEX;;;GAGG;AACH,oEAAoE;AACpE,cAA2B,CAAC"}

package/dist/config/filesystem-tools.d.ts

@@ -0,0 +1,41 @@
+/**
+ * @packageDocumentation
+ * The single interpretation of the `filesystem` config value: **which filesystem tools it
+ * registers**.
+ *
+ * `filesystem` is a union — `'all'`, `'read'`, `'none'`, or a `string[]` of tool names — so any
+ * two-value check ("is it `read` or `none`?") is wrong by construction. The toolkit filter in
+ * `@gaunt-sloth/agent` (`filterFilesystemTools`) and the system-prompt notes in this package both
+ * need the answer, and they must never derive it separately: a prompt that names a tool the filter
+ * did not register tells the model to call something that does not exist. {@link
+ * isFilesystemToolRegistered} is that one derivation; both call it.
+ */
+import { type BuiltInToolAccess } from '#src/config/tool-descriptions.js';
+/** The `filesystem` config union: an allow-list of tool names, or one of the three modes. */
+export type FilesystemToolsConfig = string[] | 'all' | 'read' | 'none';
+/**
+ * The filesystem tool that creates a file from supplied content.
+ *
+ * Exported as a constant because prompt text names it literally: the note telling the model how to
+ * write a commit message interpolates this, so the name the model is told and the name the
+ * registration check asks about cannot drift apart.
+ */
+export declare const WRITE_FILE_TOOL_NAME = "write_file";
+/**
+ * Whether a filesystem tool is registered under the given `filesystem` config.
+ *
+ * `access` is the tool's own read/write class — the runtime `gthFileSystemType` the toolkit stamps
+ * on each tool, or {@link BUILT_IN_TOOL_ACCESS} for a caller that has only a name. A tool with no
+ * class is never covered by `'read'`; it can still be named explicitly in the array form.
+ *
+ * The array form is an allow-list of tool NAMES which may also carry the `'read'` and `'all'`
+ * keywords, so `['read', 'write_file']` means "every read tool, plus write_file". A value that is
+ * neither a known mode nor an array leaves the toolset unrestricted, matching the filter's own
+ * fallback, so an absent or malformed value never silently strips the model's tools.
+ */
+export declare function isFilesystemToolRegistered(filesystemConfig: FilesystemToolsConfig | undefined, toolName: string | undefined, access: BuiltInToolAccess | undefined): boolean;
+/**
+ * Whether {@link WRITE_FILE_TOOL_NAME} is registered under the given `filesystem` config — the
+ * question the commit-message guidance asks before it names the tool.
+ */
+export declare function isWriteFileToolRegistered(filesystemConfig: FilesystemToolsConfig | undefined): boolean;

package/dist/config/filesystem-tools.js

@@ -0,0 +1,56 @@
+/**
+ * @packageDocumentation
+ * The single interpretation of the `filesystem` config value: **which filesystem tools it
+ * registers**.
+ *
+ * `filesystem` is a union — `'all'`, `'read'`, `'none'`, or a `string[]` of tool names — so any
+ * two-value check ("is it `read` or `none`?") is wrong by construction. The toolkit filter in
+ * `@gaunt-sloth/agent` (`filterFilesystemTools`) and the system-prompt notes in this package both
+ * need the answer, and they must never derive it separately: a prompt that names a tool the filter
+ * did not register tells the model to call something that does not exist. {@link
+ * isFilesystemToolRegistered} is that one derivation; both call it.
+ */
+import { BUILT_IN_TOOL_ACCESS } from '#src/config/tool-descriptions.js';
+/**
+ * The filesystem tool that creates a file from supplied content.
+ *
+ * Exported as a constant because prompt text names it literally: the note telling the model how to
+ * write a commit message interpolates this, so the name the model is told and the name the
+ * registration check asks about cannot drift apart.
+ */
+export const WRITE_FILE_TOOL_NAME = 'write_file';
+/**
+ * Whether a filesystem tool is registered under the given `filesystem` config.
+ *
+ * `access` is the tool's own read/write class — the runtime `gthFileSystemType` the toolkit stamps
+ * on each tool, or {@link BUILT_IN_TOOL_ACCESS} for a caller that has only a name. A tool with no
+ * class is never covered by `'read'`; it can still be named explicitly in the array form.
+ *
+ * The array form is an allow-list of tool NAMES which may also carry the `'read'` and `'all'`
+ * keywords, so `['read', 'write_file']` means "every read tool, plus write_file". A value that is
+ * neither a known mode nor an array leaves the toolset unrestricted, matching the filter's own
+ * fallback, so an absent or malformed value never silently strips the model's tools.
+ */
+export function isFilesystemToolRegistered(filesystemConfig, toolName, access) {
+    if (filesystemConfig === 'none')
+        return false;
+    if (filesystemConfig === 'all')
+        return true;
+    if (filesystemConfig === 'read')
+        return access === 'read';
+    if (!Array.isArray(filesystemConfig))
+        return true;
+    if (filesystemConfig.includes('all'))
+        return true;
+    if (filesystemConfig.includes('read') && access === 'read')
+        return true;
+    return filesystemConfig.some((name) => name !== 'read' && name !== 'all' && name === toolName && !!toolName);
+}
+/**
+ * Whether {@link WRITE_FILE_TOOL_NAME} is registered under the given `filesystem` config — the
+ * question the commit-message guidance asks before it names the tool.
+ */
+export function isWriteFileToolRegistered(filesystemConfig) {
+    return isFilesystemToolRegistered(filesystemConfig, WRITE_FILE_TOOL_NAME, BUILT_IN_TOOL_ACCESS[WRITE_FILE_TOOL_NAME]);
+}
+//# sourceMappingURL=filesystem-tools.js.map

package/dist/config/filesystem-tools.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"filesystem-tools.js","sourceRoot":"","sources":["../../src/config/filesystem-tools.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,oBAAoB,EAA0B,MAAM,kCAAkC,CAAC;AAKhG;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG,YAAY,CAAC;AAEjD;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,0BAA0B,CACxC,gBAAmD,EACnD,QAA4B,EAC5B,MAAqC;IAErC,IAAI,gBAAgB,KAAK,MAAM;QAAE,OAAO,KAAK,CAAC;IAC9C,IAAI,gBAAgB,KAAK,KAAK;QAAE,OAAO,IAAI,CAAC;IAC5C,IAAI,gBAAgB,KAAK,MAAM;QAAE,OAAO,MAAM,KAAK,MAAM,CAAC;IAC1D,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,gBAAgB,CAAC;QAAE,OAAO,IAAI,CAAC;IAClD,IAAI,gBAAgB,CAAC,QAAQ,CAAC,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IAClD,IAAI,gBAAgB,CAAC,QAAQ,CAAC,MAAM,CAAC,IAAI,MAAM,KAAK,MAAM;QAAE,OAAO,IAAI,CAAC;IACxE,OAAO,gBAAgB,CAAC,IAAI,CAC1B,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,KAAK,MAAM,IAAI,IAAI,KAAK,KAAK,IAAI,IAAI,KAAK,QAAQ,IAAI,CAAC,CAAC,QAAQ,CAC/E,CAAC;AACJ,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,yBAAyB,CACvC,gBAAmD;IAEnD,OAAO,0BAA0B,CAC/B,gBAAgB,EAChB,oBAAoB,EACpB,oBAAoB,CAAC,oBAAoB,CAAC,CAC3C,CAAC;AACJ,CAAC"}

package/dist/config/jsonc.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Parse a JSONC string (JSON + comments + trailing commas) into a value.
+ *
+ * On success returns the parsed value. On a structural error (anything `JSON.parse`
+ * would also reject, e.g. a missing brace or a dangling property) it throws a `SyntaxError`
+ * whose message names the first problem and its 0-based character offset, so the loader's
+ * existing "Failed to read config …" diagnostics stay actionable.
+ *
+ * @param text The file contents.
+ * @param sourceLabel Optional human-readable source name, included in the error message.
+ */
+export declare function parseJsonc(text: string, sourceLabel?: string): unknown;

package/dist/config/jsonc.js

@@ -0,0 +1,41 @@
+/**
+ * @packageDocumentation
+ * JSONC (JSON-with-comments) parsing for on-disk `.gsloth.config.json` files.
+ *
+ * The loader historically `JSON.parse`d config files, which rejects the two things
+ * hand-edited config files most want: `//` / `/* … *​/` comments and trailing commas.
+ * This wraps Microsoft's zero-dependency `jsonc-parser` so a plain `.json` config may
+ * carry both, while a genuinely malformed file still fails with a clear, located error
+ * (rather than silently returning `undefined`).
+ *
+ * `jsonc-parser` is used over a hand-rolled comment-stripper because stripping comments
+ * with a regex mishandles `//` / `/*` sequences that appear *inside* string values and
+ * escaped quotes; the tokenizer here respects string boundaries correctly. It has no
+ * transitive dependencies and is the same parser VS Code uses for its settings files.
+ */
+import { parse as parseJsoncTree, printParseErrorCode } from 'jsonc-parser';
+/**
+ * Parse a JSONC string (JSON + comments + trailing commas) into a value.
+ *
+ * On success returns the parsed value. On a structural error (anything `JSON.parse`
+ * would also reject, e.g. a missing brace or a dangling property) it throws a `SyntaxError`
+ * whose message names the first problem and its 0-based character offset, so the loader's
+ * existing "Failed to read config …" diagnostics stay actionable.
+ *
+ * @param text The file contents.
+ * @param sourceLabel Optional human-readable source name, included in the error message.
+ */
+export function parseJsonc(text, sourceLabel) {
+    const errors = [];
+    const value = parseJsoncTree(text, errors, {
+        allowTrailingComma: true,
+        disallowComments: false,
+    });
+    if (errors.length > 0) {
+        const first = errors[0];
+        const where = sourceLabel ? ` in ${sourceLabel}` : '';
+        throw new SyntaxError(`Invalid JSON/JSONC${where}: ${printParseErrorCode(first.error)} at offset ${first.offset}.`);
+    }
+    return value;
+}
+//# sourceMappingURL=jsonc.js.map

package/dist/config/jsonc.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"jsonc.js","sourceRoot":"","sources":["../../src/config/jsonc.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,OAAO,EAAE,KAAK,IAAI,cAAc,EAAmB,mBAAmB,EAAE,MAAM,cAAc,CAAC;AAE7F;;;;;;;;;;GAUG;AACH,MAAM,UAAU,UAAU,CAAC,IAAY,EAAE,WAAoB;IAC3D,MAAM,MAAM,GAAiB,EAAE,CAAC;IAChC,MAAM,KAAK,GAAG,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE;QACzC,kBAAkB,EAAE,IAAI;QACxB,gBAAgB,EAAE,KAAK;KACxB,CAAC,CAAC;IACH,IAAI,MAAM,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACtB,MAAM,KAAK,GAAG,MAAM,CAAC,CAAC,CAAC,CAAC;QACxB,MAAM,KAAK,GAAG,WAAW,CAAC,CAAC,CAAC,OAAO,WAAW,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACtD,MAAM,IAAI,WAAW,CACnB,qBAAqB,KAAK,KAAK,mBAAmB,CAAC,KAAK,CAAC,KAAK,CAAC,cAAc,KAAK,CAAC,MAAM,GAAG,CAC7F,CAAC;IACJ,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC"}