@molecule/api-ai-tools 1.0.0

package/dist/types.d.ts

@@ -0,0 +1,134 @@
+/**
+ * Core types for the shared AI agent tool system.
+ *
+ * @module
+ */
+/**
+ * Abstraction over the execution environment.
+ * Implemented by SandboxBackend (Docker) and LocalBackend (host filesystem).
+ */
+export interface ExecutionBackend {
+    /** The root directory for all operations (e.g. '/workspace' or '/Users/.../project'). */
+    readonly projectRoot: string;
+    /** Read a file's content as UTF-8 string. */
+    readFile(path: string): Promise<string>;
+    /** Write content to a file. Creates parent directories as needed. */
+    writeFile(path: string, content: string): Promise<void>;
+    /** Delete a file. */
+    deleteFile(path: string): Promise<void>;
+    /** List entries in a directory. */
+    readDir(path: string): Promise<Array<{
+        name: string;
+        type: 'file' | 'directory';
+    }>>;
+    /**
+     * Run a shell command. Returns stdout, stderr, and exit code.
+     * Backends implement this safely (sandbox.exec for Docker, execFile for local).
+     */
+    run(command: string, opts?: {
+        cwd?: string;
+        timeout?: number;
+    }): Promise<{
+        stdout: string;
+        stderr: string;
+        exitCode: number;
+    }>;
+}
+/**
+ * Configuration for building the tool set.
+ * Allows consumers to customize security, callbacks, and tool selection.
+ */
+export interface ToolBuildConfig {
+    /** Which tools to include. Defaults to all. */
+    include?: string[];
+    /** Which tools to exclude. Applied after include. */
+    exclude?: string[];
+    /** Whether to validate paths stay within projectRoot. Default: true. */
+    pathGuards?: boolean;
+    /** Whether to check symlinks resolve within projectRoot. Default: false (sandbox-only). */
+    symlinkGuards?: boolean;
+    /** Whether to redact secrets in file reads and command output. Default: true. */
+    redactSecrets?: boolean;
+    /** Whether to block dangerous shell commands (env dumps, /proc access). Default: false. */
+    blockDangerousCommands?: boolean;
+    /**
+     * Consumer-specific command guard for `exec_command`, checked BEFORE execution (after
+     * the built-in dangerous-command check). Return an error string to block the command —
+     * it is returned to the model verbatim, so make it actionable (say what to do instead) —
+     * or `null`/`undefined` to allow it. Keeps environment-specific rules (e.g. an IDE
+     * sandbox forbidding installs that would break its preinstalled library) out of this
+     * shared package.
+     *
+     * @param command - The shell command the model asked to run.
+     * @param cwd - The resolved working directory it would run in.
+     * @returns An error string to block, or null/undefined to allow.
+     */
+    blockCommand?: (command: string, cwd: string) => string | null | undefined;
+    /**
+     * Timeout (ms) for a single `exec_command` run. `exec_command` legitimately
+     * runs LONG — `npm install`, a production build, a test suite — so the default
+     * is generous (2 min); the old 30 s hardcap killed those spuriously. A consumer
+     * that wraps tool calls in its own outer timeout should set this to match (or
+     * slightly exceed) that budget so its own timeout is the effective bound and
+     * produces the nicer "tool timed out" message. Quick commands are unaffected —
+     * this is only the ceiling before a wedged command is killed.
+     */
+    execTimeoutMs?: number;
+    /**
+     * Directory names `search_files` and `find_files` skip (VS Code
+     * `search.exclude` semantics). Defaults to `DEFAULT_SEARCH_EXCLUDED_DIRS`
+     * (node_modules, VCS dirs, build output). Pass the consumer's per-project
+     * setting so every search surface shares ONE synchronized set.
+     */
+    searchExcludedDirs?: string[];
+    /** Post-write hook (e.g. auto-format via Prettier/ESLint). Called after every write_file/edit_file. */
+    onAfterWrite?: (path: string) => Promise<void>;
+    /** Diff tracking callback. Called before writes with old/new content. */
+    onFileDiff?: (event: FileDiffEvent) => void;
+    /** Structural change callback. Called on create_directory, delete_file, rename_file. */
+    onFileChange?: (event: FileChangeEvent) => void;
+}
+/**
+ * Payload emitted when a tracked file changes contents.
+ */
+export interface FileDiffEvent {
+    path: string;
+    oldContent: string | null;
+    newContent: string;
+}
+/**
+ * Payload emitted when a file is created, modified, or deleted structurally.
+ */
+export interface FileChangeEvent {
+    type: 'created' | 'modified' | 'deleted';
+    path: string;
+}
+/** Metadata for a discovered skill (used in PromptContext). */
+export interface SkillEntry {
+    /** Skill name. */
+    name: string;
+    /** Short description. */
+    description: string;
+    /** Relative path to the SKILL.md file. */
+    path: string;
+}
+/**
+ * Context for building a composable system prompt.
+ */
+export interface PromptContext {
+    /** Agent identity (e.g. 'Synthase', 'Polish Agent'). */
+    agentName: string;
+    /** Project root path. */
+    projectRoot: string;
+    /** Names of available tools (for the tool listing section). */
+    tools: string[];
+    /** Project-specific rules (AGENTS.md or CLAUDE.md content). */
+    projectDocs?: string;
+    /** Additional skill/reference content to inject. */
+    skills?: string[];
+    /** Discovered skills to list in the prompt (use load_skill to read on demand). */
+    discoveredSkills?: SkillEntry[];
+    /** Custom sections to append to the prompt. */
+    customSections?: string[];
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

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

package/dist/types.js

@@ -0,0 +1,6 @@
+/**
+ * Core types for the shared AI agent tool system.
+ *
+ * @module
+ */
+export {};

package/dist/utilities.d.ts

@@ -0,0 +1,150 @@
+/**
+ * Shared utilities for AI agent tools.
+ * Extracted from molecule-dev/api/src/ai/tools.ts for reuse.
+ *
+ * @module
+ */
+/**
+ * Shell-safe quoting using single quotes. Unlike JSON.stringify (double quotes),
+ * single-quoted strings prevent command substitution ($(), backticks) and variable expansion.
+ *
+ * @param s - Raw string to wrap for POSIX shell single-quoted context.
+ * @returns A single-quoted shell literal representing `s`.
+ */
+export declare function shellQuote(s: string): string;
+/**
+ * Strip C0 control chars (except tab, newline, CR) that break PostgreSQL JSONB
+ * and can cause rendering issues.
+ *
+ * @param s - Arbitrary text that may contain disallowed control characters.
+ * @returns A copy of `s` with unsafe control characters removed.
+ */
+export declare const stripControlChars: (s: string) => string;
+/**
+ * Redact values of common secret/credential patterns in text output.
+ *
+ * @param s - Log or command output that may contain `.env`-style secrets.
+ * @returns A redacted copy safe to surface to end users or models.
+ */
+export declare function redactSecrets(s: string): string;
+/**
+ * Check if a command is blocked for security reasons. Returns error message or null if allowed.
+ *
+ * @param command - Shell command string proposed for execution.
+ * @returns A human-readable block reason, or `null` when the command is allowed.
+ */
+export declare function checkBlockedCommand(command: string): string | null;
+/**
+ * Normalize a path to be absolute within the project root.
+ * Empty string and '/' both resolve to projectRoot.
+ * Rejects paths that escape via traversal or absolute paths outside root.
+ *
+ * @param path - Relative or absolute path inside the workspace.
+ * @param projectRoot - Absolute filesystem root for the active project.
+ * @returns A normalized absolute path confined to `projectRoot`.
+ */
+export declare function resolvePath(path: string, projectRoot: string): string;
+/**
+ * Validate that a glob/include pattern is safe (no shell metacharacters that could
+ * inject). Allows alphanumeric, `* ? . _ - /` and the bracket/paren glob chars `[] ()`.
+ *
+ * The brackets/parens matter for real frameworks: Next.js App Router names route
+ * directories `[id]`, `[...slug]`, `(group)`, `[[...optional]]`, so without them the
+ * executor cannot `find_files`/`search_files` its own routes on any Next.js project — a
+ * hard block observed on live imports. They are injection-safe here because every caller
+ * passes the pattern through `shellQuote` before it reaches `find -name`/`grep --include`,
+ * where inside single quotes `[]()` are literal (a subshell `(...)` only starts UNquoted);
+ * to the glob engine `[abc]` is a normal character class. The genuinely dangerous
+ * metacharacters (`; | & $ \` > < \n` space) remain disallowed.
+ *
+ * @param pattern - User-supplied glob fragment for search/list operations.
+ * @returns `true` when the pattern contains only allowed characters.
+ */
+export declare function isValidGlob(pattern: string): boolean;
+/**
+ * Validate a file tool's `path` argument is a non-empty string. A weak model
+ * sometimes omits it or passes a non-string, which would otherwise crash
+ * `resolvePath` (`path.replace` on undefined) with the cryptic, unactionable
+ * "Cannot read properties of undefined (reading 'replace')" — wasting executor
+ * turns. Returns an actionable message, or null when the path is usable.
+ *
+ * @param path - The raw `path` argument from the tool input.
+ * @param tool - The tool name, for the error message (e.g. 'read_file').
+ * @returns An actionable error string, or null when `path` is a non-empty string.
+ */
+export declare function pathArgError(path: unknown, tool: string): string | null;
+/**
+ * Detect a "read/edit targeted a directory, not a file" failure from a backend
+ * error message (local fs `EISDIR` or the sandbox's `cat: X: Is a directory`),
+ * and return an actionable message steering the model to `list_files`. Returns
+ * null when the error is not a directory error.
+ *
+ * @param message - The backend error message.
+ * @param path - The resolved path that was targeted.
+ * @returns An actionable directory-error string, or null.
+ */
+export declare function directoryReadHint(message: string, path: string): string | null;
+/** Max file size for read_file (5MB). */
+export declare const MAX_READ_SIZE: number;
+/** Max content size for write_file (10MB). */
+export declare const MAX_WRITE_SIZE: number;
+/** Max command output size (100KB per stream). */
+export declare const MAX_OUTPUT_SIZE: number;
+/** Max search results. */
+export declare const MAX_SEARCH_RESULTS = 50;
+/** Max find results. */
+export declare const MAX_FIND_RESULTS = 100;
+/**
+ * Default directory names `search_files`/`find_files` skip — VS Code's
+ * `search.exclude` + `files.exclude` defaults (node_modules, bower_components,
+ * VCS dirs) plus the platform's vendored/build dirs. Overridable per consumer
+ * via `ToolBuildConfig.searchExcludedDirs` (a per-project, user-editable
+ * setting in molecule.dev — keep the APP-SIDE copy in
+ * `@molecule/app-ide-react`'s search types in sync with this list).
+ */
+export declare const DEFAULT_SEARCH_EXCLUDED_DIRS: readonly ["node_modules", "bower_components", ".git", ".svn", ".hg", "CVS", "dist", ".next", ".vite", "molecule"];
+/**
+ * Truncate a string to a max length with a truncation notice.
+ *
+ * @param s - Arbitrary text to bound in size.
+ * @param maxLength - Maximum number of characters to retain before truncating.
+ * @returns Either the original string or a shortened copy with a trailing notice.
+ */
+export declare function truncate(s: string, maxLength: number): string;
+/**
+ * Truncate keeping BOTH the head and the tail, eliding the middle — for command
+ * output (build / test / migration / install logs). Plain head truncation
+ * ({@link truncate}) drops the TAIL, which is exactly where a failing command puts
+ * the reason: the `npm ERR!` line, the test-failure summary (`1 failed, 240
+ * passed`), the migration stack trace. When that is cut, the executor sees only
+ * passing progress and can't tell WHY the command failed — a self-inflicted error
+ * then survives every fix round. The head still shows what ran and the first
+ * errors; the split is weighted toward the tail since the summary lives there.
+ * No-op when `s` already fits.
+ *
+ * @param s - Arbitrary text (typically stdout/stderr) to bound in size.
+ * @param maxLength - Maximum characters to retain (excluding the elision notice).
+ * @returns The original string, or head + an elision notice + tail.
+ */
+export declare function truncateMiddle(s: string, maxLength: number): string;
+/**
+ * Attempt a whitespace-tolerant replacement when an exact `old_string` match
+ * failed. Finds a contiguous run of lines in `content` whose per-line
+ * whitespace-normalized form (runs of whitespace collapsed to one space, then
+ * trimmed) equals the normalized `oldString` lines, and replaces that run with
+ * `newString` verbatim. Applies ONLY when exactly one such run exists —
+ * uniqueness keeps it safe; an ambiguous (or zero) match is refused (returns
+ * null) so the caller falls back to its existing error path.
+ *
+ * This rescues the most common edit_file failure: a (weak) executor reproduces
+ * the target text correctly but with different indentation or trailing
+ * whitespace, which would otherwise bounce it into a re-read/retry loop — the
+ * single biggest source of wasted edit turns.
+ *
+ * @param content - Current file content.
+ * @param oldString - The search text (an exact match has already failed).
+ * @param newString - The replacement text, applied verbatim.
+ * @returns The new content if a unique fuzzy run matched, else null.
+ */
+export declare function whitespaceTolerantReplace(content: string, oldString: string, newString: string): string | null;
+//# sourceMappingURL=utilities.d.ts.map

package/dist/utilities.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"utilities.d.ts","sourceRoot":"","sources":["../src/utilities.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAS5C;AAED;;;;;;GAMG;AACH,eAAO,MAAM,iBAAiB,GAAI,GAAG,MAAM,KAAG,MAEE,CAAA;AAyDhD;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAK/C;AAaD;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAgBlE;AAID;;;;;;;;GAQG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,MAAM,CAQrE;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAEpD;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAIvE;AAED;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAI9E;AAID,yCAAyC;AACzC,eAAO,MAAM,aAAa,QAAkB,CAAA;AAC5C,8CAA8C;AAC9C,eAAO,MAAM,cAAc,QAAmB,CAAA;AAC9C,kDAAkD;AAClD,eAAO,MAAM,eAAe,QAAa,CAAA;AACzC,0BAA0B;AAC1B,eAAO,MAAM,kBAAkB,KAAK,CAAA;AACpC,wBAAwB;AACxB,eAAO,MAAM,gBAAgB,MAAM,CAAA;AAEnC;;;;;;;GAOG;AACH,eAAO,MAAM,4BAA4B,mHAW/B,CAAA;AAEV;;;;;;GAMG;AACH,wBAAgB,QAAQ,CAAC,CAAC,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAG7D;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,cAAc,CAAC,CAAC,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAmBnE;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,yBAAyB,CACvC,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM,GAChB,MAAM,GAAG,IAAI,CAyBf"}

package/dist/utilities.js

@@ -0,0 +1,311 @@
+/**
+ * Shared utilities for AI agent tools.
+ * Extracted from molecule-dev/api/src/ai/tools.ts for reuse.
+ *
+ * @module
+ */
+import { posix } from 'path';
+/**
+ * Shell-safe quoting using single quotes. Unlike JSON.stringify (double quotes),
+ * single-quoted strings prevent command substitution ($(), backticks) and variable expansion.
+ *
+ * @param s - Raw string to wrap for POSIX shell single-quoted context.
+ * @returns A single-quoted shell literal representing `s`.
+ */
+export function shellQuote(s) {
+    // Defensive: a tool handler passing a missing arg (undefined) would otherwise throw
+    // the cryptic "Cannot read properties of undefined (reading 'replace')". Fail with a
+    // clear message so the surrounding handler's catch reports something actionable.
+    if (typeof s !== 'string')
+        throw new Error(`shellQuote expected a string, received ${s === undefined ? 'undefined' : typeof s}`);
+    return "'" + s.replace(/'/g, "'\\''") + "'";
+}
+/**
+ * Strip C0 control chars (except tab, newline, CR) that break PostgreSQL JSONB
+ * and can cause rendering issues.
+ *
+ * @param s - Arbitrary text that may contain disallowed control characters.
+ * @returns A copy of `s` with unsafe control characters removed.
+ */
+export const stripControlChars = (s) => 
+// eslint-disable-next-line no-control-regex -- strip C0 controls except tab/LF/CR
+s.replace(/[\x00-\x08\x0B\x0C\x0E-\x1F]/g, '');
+// ── Secret redaction ──────────────────────────────────────────────────────────
+/** Keywords that indicate a secret/credential when part of an env var name. */
+// Keep aligned with the vault's secret classifier (isSecretKey): a key the vault
+// encrypts must also be masked here, or a decrypted secret read from a project's
+// .env egresses UNMASKED into stored AI transcripts (a store with different
+// access controls than the vault). PWD (DB_PWD/MYSQL_PWD), APIKEY (no underscore,
+// e.g. MAILGUN_APIKEY), and SERVICE_ACCOUNT were the gaps; `_KEY` already covers
+// OPENAI_KEY / *_ROLE_KEY.
+const SECRET_KEYWORDS = 'SECRET|PASSWORD|PASSWD|PWD|TOKEN|API_KEY|APIKEY|PRIVATE_KEY|DATABASE_URL|REDIS_URL|AUTH|CREDENTIAL|ACCESS_KEY|SIGNING_KEY|ENCRYPTION_KEY|CONNECTION_STRING|SERVICE_ACCOUNT|DSN|SMTP_PASS|_KEY';
+const SECRET_KEY_PATTERN = new RegExp(`^(.*(?:${SECRET_KEYWORDS})[A-Z0-9_]*)=(.+)$`, 'gim');
+/** Catch JSON-formatted env dumps like { KEY: 'value' } from node/python. */
+const SECRET_JSON_DQ = new RegExp(`(['"]?(?:\\w*(?:${SECRET_KEYWORDS})\\w*)['"]?\\s*[:=]\\s*)"(?:[^"\\\\]|\\\\.)*"`, 'gi');
+const SECRET_JSON_SQ = new RegExp(`(['"]?(?:\\w*(?:${SECRET_KEYWORDS})\\w*)['"]?\\s*[:=]\\s*)'(?:[^'\\\\]|\\\\.)*'`, 'gi');
+/**
+ * Exact VALUES that are UI vocabulary, never credentials — kept verbatim even when they
+ * sit next to a keyword-looking name. Frontend auth code is full of these: a JSX ternary
+ * `autoComplete={mode === "signup" ? "new-password" : "current-password"}` parses to the
+ * JSON patterns as name `…password"` : value `"current-password"` and was redacted to
+ * `"[REDACTED]"` — corrupting what the model reads back from its own auth files (and any
+ * edit_file old_string built from that read can never match).
+ */
+const NON_SECRET_VALUES = new Set([
+    'current-password',
+    'new-password',
+    'one-time-code',
+    'webauthn',
+    'password',
+    'username',
+]);
+/**
+ * Replacer for the JSON-style keyword patterns: masks the quoted value unless it is a
+ * known non-secret UI token ({@link NON_SECRET_VALUES}).
+ *
+ * @param quote - The quote character the value uses (`"` or `'`).
+ * @returns A String.replace replacer preserving allowlisted values.
+ */
+const jsonValueReplacer = (quote) => (match, prefix) => {
+    const value = match.slice(prefix.length);
+    const inner = value.slice(1, -1);
+    if (NON_SECRET_VALUES.has(inner.toLowerCase()))
+        return match;
+    return `${prefix}${quote}[REDACTED]${quote}`;
+};
+/**
+ * Redact values of common secret/credential patterns in text output.
+ *
+ * @param s - Log or command output that may contain `.env`-style secrets.
+ * @returns A redacted copy safe to surface to end users or models.
+ */
+export function redactSecrets(s) {
+    return s
+        .replace(SECRET_KEY_PATTERN, '$1=[REDACTED]')
+        .replace(SECRET_JSON_DQ, jsonValueReplacer('"'))
+        .replace(SECRET_JSON_SQ, jsonValueReplacer("'"));
+}
+// ── Command blocking ──────────────────────────────────────────────────────────
+/** Commands that dump environment variables — blocked to prevent secret leakage. */
+const BLOCKED_COMMANDS = /(?:^|[;&|`]\s*|(?:sh|bash|zsh|dash)\s+-c\s+['"]?\s*)(?:\/usr\/bin\/)?(?:\benv\b|\bprintenv\b|\bexport\s*$|\bset\s*$|\bdeclare\s+-x|cat\s+\/etc\/environment|cat\s+\/root\/\.bashrc|cat\s+\/proc\/\d+\/environ|cat\s+\/proc\/self\/environ|strings\s+\/proc|xargs[^;&|\n]*\/proc\/[^;&|\n]*environ|less\s+\/proc|head\s+\/proc|tail\s+\/proc|xxd\s+\/proc|od\s+\/proc|base64\s+\/proc|dd\s[^\n]*\/proc|sed\s[^\n]*\/proc\/[^\n]*environ|awk\s[^\n]*\/proc\/[^\n]*environ|cp\s[^\n]*\/proc\/[^\n]*environ)/i;
+/** Block shell redirects from /proc environ. */
+const BLOCKED_PROC_REDIRECT = /(?:<\s*\/proc\/(?:\d+|self)\/environ)/i;
+/** Interpreter-based env dumping (python, node, ruby, perl). */
+const BLOCKED_INTERPRETER_ENV = /(?:python[23]?|node|ruby|perl)\s+(?:-e|-c)\s+[^\n]*(?:os\.environ|process\.env|ENV\[|%ENV|ENVIRON)/i;
+/**
+ * Check if a command is blocked for security reasons. Returns error message or null if allowed.
+ *
+ * @param command - Shell command string proposed for execution.
+ * @returns A human-readable block reason, or `null` when the command is allowed.
+ */
+export function checkBlockedCommand(command) {
+    // These blocks fire when the executor tries to DUMP the environment (usually to discover
+    // what managed services are configured). Don't just refuse — redirect: the values are
+    // already in the process environment, so it never needs to print them.
+    const envDumpSteer = ' You do NOT need to dump it: the managed service values (DATABASE_URL, etc.) are already ' +
+        'in the process environment — read them IN CODE via process.env / your config loader, or ' +
+        "check the project's provisioned env file to see WHICH services exist. Printing them only " +
+        'leaks secrets into the transcript.';
+    if (BLOCKED_COMMANDS.test(command))
+        return `Command blocked: dumping environment variables is not allowed.${envDumpSteer}`;
+    if (BLOCKED_PROC_REDIRECT.test(command))
+        return 'Command blocked: /proc/environ access is not allowed.' + envDumpSteer;
+    if (BLOCKED_INTERPRETER_ENV.test(command))
+        return `Command blocked: dumping the environment from an interpreter is not allowed.${envDumpSteer}`;
+    return null;
+}
+// ── Path resolution ───────────────────────────────────────────────────────────
+/**
+ * Normalize a path to be absolute within the project root.
+ * Empty string and '/' both resolve to projectRoot.
+ * Rejects paths that escape via traversal or absolute paths outside root.
+ *
+ * @param path - Relative or absolute path inside the workspace.
+ * @param projectRoot - Absolute filesystem root for the active project.
+ * @returns A normalized absolute path confined to `projectRoot`.
+ */
+export function resolvePath(path, projectRoot) {
+    if (path === '' || path === '/')
+        return projectRoot;
+    const clean = path.replace(/\0/g, '');
+    const resolved = clean.startsWith('/')
+        ? posix.normalize(clean)
+        : posix.normalize(`${projectRoot}/${clean}`);
+    if (resolved !== projectRoot && !resolved.startsWith(projectRoot + '/'))
+        return projectRoot;
+    return resolved;
+}
+/**
+ * Validate that a glob/include pattern is safe (no shell metacharacters that could
+ * inject). Allows alphanumeric, `* ? . _ - /` and the bracket/paren glob chars `[] ()`.
+ *
+ * The brackets/parens matter for real frameworks: Next.js App Router names route
+ * directories `[id]`, `[...slug]`, `(group)`, `[[...optional]]`, so without them the
+ * executor cannot `find_files`/`search_files` its own routes on any Next.js project — a
+ * hard block observed on live imports. They are injection-safe here because every caller
+ * passes the pattern through `shellQuote` before it reaches `find -name`/`grep --include`,
+ * where inside single quotes `[]()` are literal (a subshell `(...)` only starts UNquoted);
+ * to the glob engine `[abc]` is a normal character class. The genuinely dangerous
+ * metacharacters (`; | & $ \` > < \n` space) remain disallowed.
+ *
+ * @param pattern - User-supplied glob fragment for search/list operations.
+ * @returns `true` when the pattern contains only allowed characters.
+ */
+export function isValidGlob(pattern) {
+    return /^[A-Za-z0-9*?._/()[\]-]+$/.test(pattern);
+}
+/**
+ * Validate a file tool's `path` argument is a non-empty string. A weak model
+ * sometimes omits it or passes a non-string, which would otherwise crash
+ * `resolvePath` (`path.replace` on undefined) with the cryptic, unactionable
+ * "Cannot read properties of undefined (reading 'replace')" — wasting executor
+ * turns. Returns an actionable message, or null when the path is usable.
+ *
+ * @param path - The raw `path` argument from the tool input.
+ * @param tool - The tool name, for the error message (e.g. 'read_file').
+ * @returns An actionable error string, or null when `path` is a non-empty string.
+ */
+export function pathArgError(path, tool) {
+    if (typeof path !== 'string' || path.trim() === '')
+        return `${tool} requires a non-empty "path" argument (a file path relative to the project root, e.g. "api/src/handlers/index.ts").`;
+    return null;
+}
+/**
+ * Detect a "read/edit targeted a directory, not a file" failure from a backend
+ * error message (local fs `EISDIR` or the sandbox's `cat: X: Is a directory`),
+ * and return an actionable message steering the model to `list_files`. Returns
+ * null when the error is not a directory error.
+ *
+ * @param message - The backend error message.
+ * @param path - The resolved path that was targeted.
+ * @returns An actionable directory-error string, or null.
+ */
+export function directoryReadHint(message, path) {
+    if (/EISDIR|is a directory/i.test(message))
+        return `${path} is a directory, not a file. Use list_files to see its contents, then read_file a specific file inside it.`;
+    return null;
+}
+// ── Output truncation ─────────────────────────────────────────────────────────
+/** Max file size for read_file (5MB). */
+export const MAX_READ_SIZE = 5 * 1024 * 1024;
+/** Max content size for write_file (10MB). */
+export const MAX_WRITE_SIZE = 10 * 1024 * 1024;
+/** Max command output size (100KB per stream). */
+export const MAX_OUTPUT_SIZE = 100 * 1024;
+/** Max search results. */
+export const MAX_SEARCH_RESULTS = 50;
+/** Max find results. */
+export const MAX_FIND_RESULTS = 100;
+/**
+ * Default directory names `search_files`/`find_files` skip — VS Code's
+ * `search.exclude` + `files.exclude` defaults (node_modules, bower_components,
+ * VCS dirs) plus the platform's vendored/build dirs. Overridable per consumer
+ * via `ToolBuildConfig.searchExcludedDirs` (a per-project, user-editable
+ * setting in molecule.dev — keep the APP-SIDE copy in
+ * `@molecule/app-ide-react`'s search types in sync with this list).
+ */
+export const DEFAULT_SEARCH_EXCLUDED_DIRS = [
+    'node_modules',
+    'bower_components',
+    '.git',
+    '.svn',
+    '.hg',
+    'CVS',
+    'dist',
+    '.next',
+    '.vite',
+    'molecule',
+];
+/**
+ * Truncate a string to a max length with a truncation notice.
+ *
+ * @param s - Arbitrary text to bound in size.
+ * @param maxLength - Maximum number of characters to retain before truncating.
+ * @returns Either the original string or a shortened copy with a trailing notice.
+ */
+export function truncate(s, maxLength) {
+    if (s.length <= maxLength)
+        return s;
+    return s.substring(0, maxLength) + '\n\n... (truncated)';
+}
+/**
+ * Truncate keeping BOTH the head and the tail, eliding the middle — for command
+ * output (build / test / migration / install logs). Plain head truncation
+ * ({@link truncate}) drops the TAIL, which is exactly where a failing command puts
+ * the reason: the `npm ERR!` line, the test-failure summary (`1 failed, 240
+ * passed`), the migration stack trace. When that is cut, the executor sees only
+ * passing progress and can't tell WHY the command failed — a self-inflicted error
+ * then survives every fix round. The head still shows what ran and the first
+ * errors; the split is weighted toward the tail since the summary lives there.
+ * No-op when `s` already fits.
+ *
+ * @param s - Arbitrary text (typically stdout/stderr) to bound in size.
+ * @param maxLength - Maximum characters to retain (excluding the elision notice).
+ * @returns The original string, or head + an elision notice + tail.
+ */
+export function truncateMiddle(s, maxLength) {
+    if (s.length <= maxLength)
+        return s;
+    // Reserve room for the elision notice so head + notice + tail stays WITHIN
+    // maxLength — the cap is a real token budget the caller relies on (a head-only
+    // truncate that overshoots by its suffix length breaks that contract). 140 =
+    // the fixed notice text (~124) + up to ~12 digits for the omitted count.
+    const noticeReserve = 140;
+    // Cap too small to fit the notice + any head/tail → plain head slice (still
+    // within maxLength; the middle-preserving form only helps at real sizes).
+    if (maxLength <= noticeReserve)
+        return s.slice(0, maxLength);
+    const budget = maxLength - noticeReserve;
+    const headLen = Math.floor(budget * 0.4);
+    const tailLen = budget - headLen;
+    const omitted = s.length - headLen - tailLen;
+    return (s.slice(0, headLen) +
+        `\n\n... [middle truncated — ${omitted} chars omitted; the head AND the tail are shown, a failing command's error is usually near the end] ...\n\n` +
+        s.slice(s.length - tailLen));
+}
+/**
+ * Attempt a whitespace-tolerant replacement when an exact `old_string` match
+ * failed. Finds a contiguous run of lines in `content` whose per-line
+ * whitespace-normalized form (runs of whitespace collapsed to one space, then
+ * trimmed) equals the normalized `oldString` lines, and replaces that run with
+ * `newString` verbatim. Applies ONLY when exactly one such run exists —
+ * uniqueness keeps it safe; an ambiguous (or zero) match is refused (returns
+ * null) so the caller falls back to its existing error path.
+ *
+ * This rescues the most common edit_file failure: a (weak) executor reproduces
+ * the target text correctly but with different indentation or trailing
+ * whitespace, which would otherwise bounce it into a re-read/retry loop — the
+ * single biggest source of wasted edit turns.
+ *
+ * @param content - Current file content.
+ * @param oldString - The search text (an exact match has already failed).
+ * @param newString - The replacement text, applied verbatim.
+ * @returns The new content if a unique fuzzy run matched, else null.
+ */
+export function whitespaceTolerantReplace(content, oldString, newString) {
+    const norm = (s) => s.replace(/\s+/g, ' ').trim();
+    const fileLines = content.split('\n');
+    const normOld = oldString.split('\n').map(norm);
+    // Refuse a degenerate all-blank search block (would match any blank run).
+    if (normOld.length === 0 || normOld.every((l) => l === ''))
+        return null;
+    const matches = [];
+    for (let i = 0; i + normOld.length <= fileLines.length; i++) {
+        let ok = true;
+        for (let j = 0; j < normOld.length; j++) {
+            if (norm(fileLines[i + j]) !== normOld[j]) {
+                ok = false;
+                break;
+            }
+        }
+        if (ok) {
+            matches.push(i);
+            if (matches.length > 1)
+                return null; // ambiguous — refuse
+        }
+    }
+    if (matches.length !== 1)
+        return null;
+    const start = matches[0];
+    return [...fileLines.slice(0, start), newString, ...fileLines.slice(start + normOld.length)].join('\n');
+}

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@molecule/api-ai-tools",
+  "version": "1.0.0",
+  "description": "Shared AI agent tools with backend abstraction for sandbox and local execution",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "keywords": [
+    "molecule",
+    "ai",
+    "tools",
+    "agent"
+  ],
+  "license": "Apache-2.0",
+  "peerDependencies": {
+    "@molecule/api-ai": "^1.0.0"
+  },
+  "devDependencies": {
+    "@molecule/api-ai": "1.0.0",
+    "@types/node": "26.1.2",
+    "typescript": "6.0.3",
+    "vitest": "4.1.10"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/molecule-dev/molecule.git",
+    "directory": "packages/api/core/ai-tools"
+  },
+  "homepage": "https://github.com/molecule-dev/molecule/tree/main/packages/api/core/ai-tools",
+  "bugs": "https://github.com/molecule-dev/molecule/issues",
+  "publishConfig": {
+    "access": "public"
+  }
+}