@molecule/api-ai-tools 1.0.0 → 1.0.2

package/README.md

@@ -0,0 +1,696 @@
+<!--
+AUTO-GENERATED — DO NOT EDIT THIS FILE.
+Generated by `mlcl sync-docs` from the package's src/index.ts JSDoc + mlcl/registry.json.
+Edits here are overwritten on the next commit (molecule's pre-commit hook regenerates).
+To change this document, edit the module-level JSDoc in src/index.ts.
+Generated: 2026-08-13T21:34:34.535Z
+-->
+
+# @molecule/api-ai-tools
+
+> **Auto-generated, AI-first package reference** for the [molecule.dev](https://molecule.dev) ecosystem.
+> It is written to be read by coding agents as much as by people, and is generated from this
+> package's source — edit `src/index.ts` JSDoc, not this file.
+
+Shared AI agent tool set for molecule.dev — filesystem, search, and shell
+tools an LLM agent can call, with a swappable execution backend.
+
+`buildTools(backend)` returns ready-to-use `AITool`s (the `@molecule/api-ai`
+tool shape): `list_files`, `read_file`, `write_file`, `edit_file`,
+`search_files`, `find_files`, `create_directory`, `rename_file`,
+`delete_file`, `exec_command`, `save_plan`, `load_skill`. The backend decides
+WHERE they act: `createLocalBackend(projectRoot)` (host filesystem) or
+`createSandboxBackend(...)` (an isolated `@molecule/api-code-sandbox`
+container). `buildAgentPrompt(ctx)` composes a matching system prompt
+(identity, tool listing, project docs, discovered skills).
+
+## Quick Start
+
+```typescript
+import { buildAgentPrompt, buildTools, createLocalBackend } from '@molecule/api-ai-tools'
+import { requireProvider } from '@molecule/api-ai'
+
+const backend = createLocalBackend('/path/to/project')
+const tools = buildTools(backend, { include: ['read_file', 'edit_file', 'search_files'] })
+const system = buildAgentPrompt({
+  agentName: 'My Agent',
+  projectRoot: backend.projectRoot,
+  tools: tools.map((t) => t.name),
+})
+
+// Hand them to the bonded AI provider (or an @molecule/api-ai-agents run).
+for await (const event of requireProvider().chat({ system, tools, messages, stream: true })) {
+  // forward text chunks; tool calls are executed against the backend
+}
+```
+
+## Type
+
+`core`
+
+## Installation
+
+```bash
+npm install @molecule/api-ai-tools @molecule/api-ai
+```
+
+## API
+
+### Interfaces
+
+#### `ExecutionBackend`
+
+Abstraction over the execution environment.
+Implemented by SandboxBackend (Docker) and LocalBackend (host filesystem).
+
+```typescript
+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 }>
+}
+```
+
+#### `FileChangeEvent`
+
+Payload emitted when a file is created, modified, or deleted structurally.
+
+```typescript
+interface FileChangeEvent {
+  type: 'created' | 'modified' | 'deleted'
+  path: string
+}
+```
+
+#### `FileDiffEvent`
+
+Payload emitted when a tracked file changes contents.
+
+```typescript
+interface FileDiffEvent {
+  path: string
+  oldContent: string | null
+  newContent: string
+}
+```
+
+#### `PromptContext`
+
+Context for building a composable system prompt.
+
+```typescript
+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[]
+}
+```
+
+#### `SkillEntry`
+
+Metadata for a discovered skill (used in PromptContext).
+
+```typescript
+interface SkillEntry {
+  /** Skill name. */
+  name: string
+  /** Short description. */
+  description: string
+  /** Relative path to the SKILL.md file. */
+  path: string
+}
+```
+
+#### `ToolBuildConfig`
+
+Configuration for building the tool set.
+Allows consumers to customize security, callbacks, and tool selection.
+
+```typescript
+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
+}
+```
+
+#### `ToolSchema`
+
+JSON-schema-backed definition for a single agent tool.
+
+```typescript
+interface ToolSchema {
+  name: string
+  description: string
+  parameters: JSONSchema
+}
+```
+
+### Types
+
+#### `DiscoveredSkill` _(deprecated)_
+
+Re-export SkillEntry as DiscoveredSkill for backwards compatibility.
+
+```typescript
+type DiscoveredSkill = SkillEntry
+```
+
+### Functions
+
+#### `buildAgentPrompt(ctx)`
+
+Build a coding-focused system prompt from composable sections.
+
+Returns a string that includes:
+
+- Agent identity
+- Available tools listing
+- Coding best practices
+- Tool argument formatting guidance
+- Project docs (if provided)
+- Discovered skills listing (if provided)
+- Inline skills (if provided)
+- Custom sections (if provided)
+
+```typescript
+function buildAgentPrompt(ctx: PromptContext): string
+```
+
+- `ctx` — Prompt construction inputs (tools, docs, skills, etc.).
+
+**Returns:** Fully assembled system prompt text for the coding agent.
+
+#### `buildTools(backend, config)`
+
+Build a complete set of AI agent tools bound to an execution backend.
+
+```typescript
+function buildTools(backend: ExecutionBackend, config?: ToolBuildConfig): AITool[]
+```
+
+- `backend` — The execution environment (sandbox or local filesystem)
+- `config` — Optional configuration for security, callbacks, and tool selection
+
+**Returns:** Array of AITool objects ready to pass to an AI provider
+
+#### `checkBlockedCommand(command)`
+
+Check if a command is blocked for security reasons. Returns error message or null if allowed.
+
+```typescript
+function checkBlockedCommand(command: string): string | null
+```
+
+- `command` — Shell command string proposed for execution.
+
+**Returns:** A human-readable block reason, or `null` when the command is allowed.
+
+#### `createLocalBackend(projectRoot)`
+
+Create an ExecutionBackend that operates on the local filesystem.
+
+```typescript
+function createLocalBackend(projectRoot: string): ExecutionBackend
+```
+
+- `projectRoot` — Absolute path to the project root directory
+
+**Returns:** A backend wired to `fs/promises` and guarded subprocess calls.
+
+#### `createSandboxBackend(sandbox, projectRoot)`
+
+Create an ExecutionBackend that delegates to a Docker sandbox instance.
+The sandbox.exec method is inherently safe — it runs inside an isolated Docker container.
+
+```typescript
+function createSandboxBackend(sandbox: SandboxLike, projectRoot?: string): ExecutionBackend
+```
+
+- `sandbox` — A running Sandbox instance from `@molecule/api-code-sandbox`
+- `projectRoot` — Root directory inside the sandbox (default: '/workspace')
+
+**Returns:** A backend that proxies all filesystem calls into the sandbox.
+
+#### `directoryReadHint(message, path)`
+
+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.
+
+```typescript
+function directoryReadHint(message: string, path: string): string | null
+```
+
+- `message` — The backend error message.
+- `path` — The resolved path that was targeted.
+
+**Returns:** An actionable directory-error string, or null.
+
+#### `discoverSkills(backend)`
+
+Discover skills from a project directory.
+
+Scans `.agents/skills/` and `.claude/skills/` for SKILL.md files.
+Reads the YAML frontmatter of each to extract `name:` and `description:` fields.
+
+```typescript
+function discoverSkills(backend: ExecutionBackend): Promise<SkillEntry[]>
+```
+
+- `backend` — Execution backend to use for filesystem access
+
+**Returns:** Array of discovered skills with name, description, and path
+
+#### `isEnvFilePath(path)`
+
+Whether a path is an env file, for which {@link redactSecrets}' full env-dump
+treatment is appropriate rather than {@link redactSecretsInCode}. Matches
+`.env`, `.env.<suffix>`, and `<name>.env`.
+
+```typescript
+function isEnvFilePath(path: string): boolean
+```
+
+- `path` — A workspace-relative or absolute file path.
+
+**Returns:** `true` when the file is an env file.
+
+#### `isValidGlob(pattern)`
+
+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.
+
+```typescript
+function isValidGlob(pattern: string): boolean
+```
+
+- `pattern` — User-supplied glob fragment for search/list operations.
+
+**Returns:** `true` when the pattern contains only allowed characters.
+
+#### `pathArgError(path, tool)`
+
+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.
+
+```typescript
+function pathArgError(path: unknown, tool: string): string | null
+```
+
+- `path` — The raw `path` argument from the tool input.
+- `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.
+
+#### `redactSecrets(s)`
+
+Redact values of common secret/credential patterns in text output.
+
+ENV-DUMP GRADE — includes the JSON `KEY: 'value'` passes, which key off the
+NAME beside the value and therefore cannot tell a credential from ordinary
+code that happens to use a keyword-ish identifier. Use this for `.env` reads
+and command output (where an env dump is the actual threat); use
+{@link redactSecretsInCode} for source-file content.
+
+```typescript
+function redactSecrets(s: string): string
+```
+
+- `s` — Log or command output that may contain `.env`-style secrets.
+
+**Returns:** A redacted copy safe to surface to end users or models.
+
+#### `redactSecretsInCode(s)`
+
+CODE-SAFE redaction — the env-assignment pass of {@link redactSecrets} WITHOUT
+the JSON `KEY: 'value'` passes.
+
+Those passes match on the NAME next to a quoted value, so over source code they
+replace legitimate content at enormous scale: `forgotPasswordEndpoint:
+'/users/forgot-password'`, `apiKeys: 'API keys'`, and every localized "Show
+password" string all became `'[REDACTED]'`. Because the agent writes back the
+content it reads, that token then lands in the user's project — measured at
+10,952 of 27,919 flagship template files before this split.
+
+No value heuristic can fix that: a legitimate `password = 'TestPass123!'` in a
+test helper is indistinguishable from a real credential by shape. So the
+name-keyed passes simply do not run over code. Credentials in source are still
+caught by the env-assignment pass here, and consumers layer VALUE-SHAPE
+detection (vendor prefixes, PEM blocks, credentials in a URL authority) on top —
+which is what actually catches a secret sitting under an innocuous name.
+
+```typescript
+function redactSecretsInCode(s: string): string
+```
+
+- `s` — Source-file content or other code-shaped text.
+
+**Returns:** A redacted copy that preserves ordinary code verbatim.
+
+#### `resolvePath(path, projectRoot)`
+
+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.
+
+```typescript
+function resolvePath(path: string, projectRoot: string): string
+```
+
+- `path` — Relative or absolute path inside the workspace.
+- `projectRoot` — Absolute filesystem root for the active project.
+
+**Returns:** A normalized absolute path confined to `projectRoot`.
+
+#### `shellQuote(s)`
+
+Shell-safe quoting using single quotes. Unlike JSON.stringify (double quotes),
+single-quoted strings prevent command substitution ($(), backticks) and variable expansion.
+
+```typescript
+function shellQuote(s: string): string
+```
+
+- `s` — Raw string to wrap for POSIX shell single-quoted context.
+
+**Returns:** A single-quoted shell literal representing `s`.
+
+#### `stripControlChars(s)`
+
+Strip C0 control chars (except tab, newline, CR) that break PostgreSQL JSONB
+and can cause rendering issues.
+
+```typescript
+function stripControlChars(s: string): string
+```
+
+- `s` — Arbitrary text that may contain disallowed control characters.
+
+**Returns:** A copy of `s` with unsafe control characters removed.
+
+#### `truncate(s, maxLength)`
+
+Truncate a string to a max length with a truncation notice.
+
+```typescript
+function truncate(s: string, maxLength: number): string
+```
+
+- `s` — Arbitrary text to bound in size.
+- `maxLength` — Maximum number of characters to retain before truncating.
+
+**Returns:** Either the original string or a shortened copy with a trailing notice.
+
+#### `truncateMiddle(s, maxLength)`
+
+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.
+
+```typescript
+function truncateMiddle(s: string, maxLength: number): string
+```
+
+- `s` — Arbitrary text (typically stdout/stderr) to bound in size.
+- `maxLength` — Maximum characters to retain (excluding the elision notice).
+
+**Returns:** The original string, or head + an elision notice + tail.
+
+#### `whitespaceTolerantReplace(content, oldString, newString)`
+
+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.
+
+```typescript
+function whitespaceTolerantReplace(
+  content: string,
+  oldString: string,
+  newString: string,
+): string | null
+```
+
+- `content` — Current file content.
+- `oldString` — The search text (an exact match has already failed).
+- `newString` — The replacement text, applied verbatim.
+
+**Returns:** The new content if a unique fuzzy run matched, else null.
+
+### Constants
+
+#### `DEFAULT_SEARCH_EXCLUDED_DIRS`
+
+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).
+
+```typescript
+const DEFAULT_SEARCH_EXCLUDED_DIRS: readonly [
+  'node_modules',
+  'bower_components',
+  '.git',
+  '.svn',
+  '.hg',
+  'CVS',
+  'dist',
+  '.next',
+  '.vite',
+  'molecule',
+]
+```
+
+#### `MAX_FIND_RESULTS`
+
+Max find results.
+
+```typescript
+const MAX_FIND_RESULTS: 100
+```
+
+#### `MAX_OUTPUT_SIZE`
+
+Max command output size (100KB per stream).
+
+```typescript
+const MAX_OUTPUT_SIZE: number
+```
+
+#### `MAX_READ_SIZE`
+
+Max file size for read_file (5MB).
+
+```typescript
+const MAX_READ_SIZE: number
+```
+
+#### `MAX_SEARCH_RESULTS`
+
+Max search results.
+
+```typescript
+const MAX_SEARCH_RESULTS: 50
+```
+
+#### `MAX_WRITE_SIZE`
+
+Max content size for write_file (10MB).
+
+```typescript
+const MAX_WRITE_SIZE: number
+```
+
+#### `TOOL_SCHEMAS`
+
+Canonical tool schemas shared by the agent runtime and documentation.
+
+```typescript
+const TOOL_SCHEMAS: Record<string, ToolSchema>
+```
+
+## Injection Notes
+
+### Requirements
+
+Peer dependencies:
+
+- `@molecule/api-ai` ^1.0.1
+
+### Runtime Dependencies
+
+- `@molecule/api-ai`
+
+- **This package only defines the tools — it runs no model loop.** Hand them to
+  the bonded AI provider (`chat({ tools, … })`) or to an
+  `@molecule/api-ai-agents` run.
+- **Safety defaults: keep them on for model-driven use.** `pathGuards` (default
+  true) rejects paths escaping `projectRoot`; `redactSecrets` (default true)
+  masks secret-looking values in file reads and command output.
+- **`exec_command` executes REAL shell commands** on the backend. Prefer a
+  sandbox backend for untrusted/model-driven work; add environment-specific
+  rules via `blockCommand` (return an actionable error string to refuse — it is
+  shown to the model verbatim) and enable `blockDangerousCommands` (default
+  FALSE) where appropriate.
+- **Scope the tool set per agent** with `include`/`exclude` — a read-only agent
+  should not receive `write_file`/`exec_command`.
+- Outputs are size-capped (`MAX_READ_SIZE`, `MAX_OUTPUT_SIZE`, …) and searches
+  skip `DEFAULT_SEARCH_EXCLUDED_DIRS` (node_modules, VCS dirs, build output) —
+  pass `searchExcludedDirs` so every search surface shares the consumer's one
+  setting.
+
+## E2E Tests
+
+Integration checklist — drive the real UI (live preview, no mocks), adapt
+each item to this app's actual agent/chat surface and its registered tools,
+and check every box off one by one. A box you can't check is an integration
+bug to fix — not a skip:
+
+- [ ] A prompt that should trigger a registered tool makes the model INVOKE
+      it with args matching that tool's `parameters` schema (e.g. "read
+      src/index.ts" -> calls `read_file` with `{ path: 'src/index.ts' }`).
+      Confirm the tool's `execute` actually RAN — its backend side effect / log /
+      the file it touched — not that the model merely narrated calling it.
+- [ ] The tool's returned value flows back into the model and shapes the
+      final answer: the REAL result (the file's actual contents, the command's
+      real stdout/exitCode) appears in the reply, not a plausible hallucination.
+- [ ] A prompt that needs no tool is answered directly, with no spurious
+      tool call.
+- [ ] A tool whose `execute` throws or returns `{ error }` (missing file,
+      failing command, blocked path) degrades gracefully — the error is caught
+      and fed back to the model as text, the conversation continues, and nothing
+      crashes the request.
+- [ ] The model can invoke ONLY the tools handed to this run: an
+      `include`/`exclude`-scoped agent (e.g. read-only — no `write_file` /
+      `exec_command`) cannot call an excluded tool, and a tool name the model
+      invents that was never registered is refused, not executed.
+- [ ] Tool execution is server-side and authorized: `exec_command` /
+      `write_file` run only on the bonded backend under its guards (`pathGuards`,
+      `symlinkGuards`, `redactSecrets`, `blockDangerousCommands` / `blockCommand`)
+      and stay inside `projectRoot`. Feed a prompt-injected instruction (a file or
+      message telling the model to read `/etc/passwd`, escape the workspace, or run
+      a privileged command) and confirm the guard REFUSES it — a user must not be
+      able to trigger, via the model, any action they could not perform directly.

package/dist/tools.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../src/tools.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAA;AAG9C,OAAO,KAAK,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,YAAY,CAAA;AAoBnE;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,gBAAgB,EAAE,MAAM,CAAC,EAAE,eAAe,GAAG,MAAM,EAAE,CA0nBxF"}
+{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../src/tools.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAA;AAG9C,OAAO,KAAK,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,YAAY,CAAA;AAsBnE;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,gBAAgB,EAAE,MAAM,CAAC,EAAE,eAAe,GAAG,MAAM,EAAE,CAopBxF"}

package/dist/tools.js

@@ -7,7 +7,7 @@
  * @module
  */
 import { TOOL_SCHEMAS } from './schemas.js';
-import { checkBlockedCommand, DEFAULT_SEARCH_EXCLUDED_DIRS, directoryReadHint, isValidGlob, MAX_FIND_RESULTS, MAX_OUTPUT_SIZE, MAX_READ_SIZE, MAX_SEARCH_RESULTS, MAX_WRITE_SIZE, pathArgError, redactSecrets, resolvePath, shellQuote, stripControlChars, truncateMiddle, whitespaceTolerantReplace, } from './utilities.js';
+import { checkBlockedCommand, DEFAULT_SEARCH_EXCLUDED_DIRS, directoryReadHint, isEnvFilePath, isValidGlob, MAX_FIND_RESULTS, MAX_OUTPUT_SIZE, MAX_READ_SIZE, MAX_SEARCH_RESULTS, MAX_WRITE_SIZE, pathArgError, redactSecrets, redactSecretsInCode, resolvePath, shellQuote, stripControlChars, truncateMiddle, whitespaceTolerantReplace, } from './utilities.js';
 /**
  * Build a complete set of AI agent tools bound to an execution backend.
  *
@@ -71,6 +71,24 @@ export function buildTools(backend, config) {
             result = redactSecrets(result);
         return result;
     }
+    /**
+     * Sanitize FILE CONTENT for return to the model. Unlike {@link sanitizeOutput},
+     * this uses the code-safe redactor for ordinary source files — the name-keyed
+     * JSON passes destroy legitimate code, and the agent writes back what it reads,
+     * so an over-redacted read corrupts the user's project on the next write. Env
+     * files still get the full env-dump treatment, since that is where the shape
+     * those passes detect actually indicates a credential.
+     *
+     * @param s - Raw file contents.
+     * @param path - The file's path, used to decide the redaction grade.
+     * @returns Content safe to return to the model, with code preserved verbatim.
+     */
+    function sanitizeFileContent(s, path) {
+        let result = stripControlChars(s);
+        if (doRedact)
+            result = isEnvFilePath(path) ? redactSecrets(result) : redactSecretsInCode(result);
+        return result;
+    }
     // ── Diff computation ───────────────────────────────────────────
     /**
      * Compute a lightweight diff summary for telemetry and UI badges.
@@ -120,7 +138,7 @@ export function buildTools(backend, config) {
                     return {
                         error: `File too large (${Math.round(content.length / 1024)}KB). Maximum is ${MAX_READ_SIZE / 1024 / 1024}MB.`,
                     };
-                return { path, content: sanitizeOutput(content) };
+                return { path, content: sanitizeFileContent(content, path) };
             }
             catch (e) {
                 // Backends (e.g. the docker provider's `cat`) already prefix "Failed to read <path>: ";
@@ -363,7 +381,11 @@ export function buildTools(backend, config) {
             try {
                 const globArg = include ? `--include=${shellQuote(include)}` : '';
                 const result = await backend.run(`grep -rn ${globArg} ${grepExcludeArgs} --max-count=${MAX_SEARCH_RESULTS} -- ${shellQuote(pattern)} ${shellQuote(path)} 2>/dev/null || true`, { timeout: 10000 });
-                const output = sanitizeOutput(result.stdout.trim());
+                // grep emits `<file>:<line>:<content>`, so redaction runs PER MATCH on the
+                // content alone: the file prefix would otherwise hide an env assignment from
+                // the line-anchored env pattern, and knowing each match's own path is what
+                // lets a hit inside a .env get full treatment while source stays verbatim.
+                const output = stripControlChars(result.stdout.trim());
                 if (!output)
                     return { pattern, path, matches: [] };
                 const matches = output
@@ -372,8 +394,8 @@ export function buildTools(backend, config) {
                     .map((line) => {
                     const m = line.match(/^(.+?):(\d+):(.*)$/);
                     return m
-                        ? { file: m[1], line: parseInt(m[2]), content: m[3] }
-                        : { file: '', line: 0, content: line };
+                        ? { file: m[1], line: parseInt(m[2]), content: sanitizeFileContent(m[3], m[1]) }
+                        : { file: '', line: 0, content: sanitizeFileContent(line, '') };
                 });
                 return { pattern, path, matches };
             }
@@ -506,7 +528,7 @@ export function buildTools(backend, config) {
                     return { error: symlinkErr };
                 try {
                     const content = await backend.readFile(path);
-                    return { name, path, content: sanitizeOutput(content) };
+                    return { name, path, content: sanitizeFileContent(content, path) };
                 }
                 catch (_error) {
                     // File not present at the given path — fall through to the error return below
@@ -523,7 +545,11 @@ export function buildTools(backend, config) {
                     continue;
                 try {
                     const content = await backend.readFile(skillPath);
-                    return { name, path: `${dir}/${name}/SKILL.md`, content: sanitizeOutput(content) };
+                    return {
+                        name,
+                        path: `${dir}/${name}/SKILL.md`,
+                        content: sanitizeFileContent(content, skillPath),
+                    };
                 }
                 catch (_error) {
                     // Skill file not present in this directory — try the next candidate

package/dist/utilities.d.ts

@@ -23,10 +23,47 @@ export declare const stripControlChars: (s: string) => string;
 /**
  * Redact values of common secret/credential patterns in text output.
  *
+ * ENV-DUMP GRADE — includes the JSON `KEY: 'value'` passes, which key off the
+ * NAME beside the value and therefore cannot tell a credential from ordinary
+ * code that happens to use a keyword-ish identifier. Use this for `.env` reads
+ * and command output (where an env dump is the actual threat); use
+ * {@link redactSecretsInCode} for source-file content.
+ *
  * @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;
+/**
+ * CODE-SAFE redaction — the env-assignment pass of {@link redactSecrets} WITHOUT
+ * the JSON `KEY: 'value'` passes.
+ *
+ * Those passes match on the NAME next to a quoted value, so over source code they
+ * replace legitimate content at enormous scale: `forgotPasswordEndpoint:
+ * '/users/forgot-password'`, `apiKeys: 'API keys'`, and every localized "Show
+ * password" string all became `'[REDACTED]'`. Because the agent writes back the
+ * content it reads, that token then lands in the user's project — measured at
+ * 10,952 of 27,919 flagship template files before this split.
+ *
+ * No value heuristic can fix that: a legitimate `password = 'TestPass123!'` in a
+ * test helper is indistinguishable from a real credential by shape. So the
+ * name-keyed passes simply do not run over code. Credentials in source are still
+ * caught by the env-assignment pass here, and consumers layer VALUE-SHAPE
+ * detection (vendor prefixes, PEM blocks, credentials in a URL authority) on top —
+ * which is what actually catches a secret sitting under an innocuous name.
+ *
+ * @param s - Source-file content or other code-shaped text.
+ * @returns A redacted copy that preserves ordinary code verbatim.
+ */
+export declare function redactSecretsInCode(s: string): string;
+/**
+ * Whether a path is an env file, for which {@link redactSecrets}' full env-dump
+ * treatment is appropriate rather than {@link redactSecretsInCode}. Matches
+ * `.env`, `.env.<suffix>`, and `<name>.env`.
+ *
+ * @param path - A workspace-relative or absolute file path.
+ * @returns `true` when the file is an env file.
+ */
+export declare function isEnvFilePath(path: string): boolean;
 /**
  * Check if a command is blocked for security reasons. Returns error message or null if allowed.
  *

package/dist/utilities.d.ts.map

@@ -1 +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"}
+{"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;AAyFhD;;;;;;;;;;;GAWG;AACH,wBAAgB,aAAa,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAK/C;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,mBAAmB,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAErD;AAED;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAGnD;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

@@ -39,7 +39,33 @@ s.replace(/[\x00-\x08\x0B\x0C\x0E-\x1F]/g, '');
 // 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');
+/**
+ * A keyword-named `NAME=value` anywhere on a line — the ENV-DUMP grade pattern,
+ * used by {@link redactSecrets} for command output and `.env` reads. The permissive
+ * `.*` prefix is deliberate there: a leaked env var routinely arrives mid-line
+ * (`Error: DATABASE_URL=postgres://…` on stderr), and that output is shown to the
+ * model but never written back to a file, so over-matching costs nothing.
+ *
+ * The value must not open with `{` or `<`: an env value never does, but a JSX
+ * expression container or element always does. Without that guard this pattern ate
+ * `auth={authClient}` down to `auth=[REDACTED]`.
+ */
+const SECRET_KEY_PATTERN = new RegExp(`^(.*(?:${SECRET_KEYWORDS})[A-Za-z0-9_]*)=(?![{<])(.+)$`, 'gim');
+/**
+ * The same assignment anchored to a REAL env-assignment shape — line start (or
+ * `export `), a bare identifier, then `=` with no surrounding spaces. This is the
+ * CODE-SAFE form used by {@link redactSecretsInCode}.
+ *
+ * Anchoring matters because the loose form above matches any line with a keyword
+ * anywhere before an `=` and replaces the whole line tail. Over source code that
+ * destroyed ordinary lines, and since the executor writes back what it reads, the
+ * literal token landed in users' projects.
+ */
+const SECRET_ENV_ASSIGNMENT = new RegExp(
+// The leading name run allows EMPTY: a name that IS the keyword (`DATABASE_URL=`,
+// `SECRET=`) has nothing before it, and requiring a character there silently
+// un-masked exactly the plainest env vars.
+`^((?:export[ \\t]+)?[A-Za-z0-9_]*(?:${SECRET_KEYWORDS})[A-Za-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');
@@ -76,6 +102,12 @@ const jsonValueReplacer = (quote) => (match, prefix) => {
 /**
  * Redact values of common secret/credential patterns in text output.
  *
+ * ENV-DUMP GRADE — includes the JSON `KEY: 'value'` passes, which key off the
+ * NAME beside the value and therefore cannot tell a credential from ordinary
+ * code that happens to use a keyword-ish identifier. Use this for `.env` reads
+ * and command output (where an env dump is the actual threat); use
+ * {@link redactSecretsInCode} for source-file content.
+ *
  * @param s - Log or command output that may contain `.env`-style secrets.
  * @returns A redacted copy safe to surface to end users or models.
  */
@@ -85,6 +117,42 @@ export function redactSecrets(s) {
         .replace(SECRET_JSON_DQ, jsonValueReplacer('"'))
         .replace(SECRET_JSON_SQ, jsonValueReplacer("'"));
 }
+/**
+ * CODE-SAFE redaction — the env-assignment pass of {@link redactSecrets} WITHOUT
+ * the JSON `KEY: 'value'` passes.
+ *
+ * Those passes match on the NAME next to a quoted value, so over source code they
+ * replace legitimate content at enormous scale: `forgotPasswordEndpoint:
+ * '/users/forgot-password'`, `apiKeys: 'API keys'`, and every localized "Show
+ * password" string all became `'[REDACTED]'`. Because the agent writes back the
+ * content it reads, that token then lands in the user's project — measured at
+ * 10,952 of 27,919 flagship template files before this split.
+ *
+ * No value heuristic can fix that: a legitimate `password = 'TestPass123!'` in a
+ * test helper is indistinguishable from a real credential by shape. So the
+ * name-keyed passes simply do not run over code. Credentials in source are still
+ * caught by the env-assignment pass here, and consumers layer VALUE-SHAPE
+ * detection (vendor prefixes, PEM blocks, credentials in a URL authority) on top —
+ * which is what actually catches a secret sitting under an innocuous name.
+ *
+ * @param s - Source-file content or other code-shaped text.
+ * @returns A redacted copy that preserves ordinary code verbatim.
+ */
+export function redactSecretsInCode(s) {
+    return s.replace(SECRET_ENV_ASSIGNMENT, '$1=[REDACTED]');
+}
+/**
+ * Whether a path is an env file, for which {@link redactSecrets}' full env-dump
+ * treatment is appropriate rather than {@link redactSecretsInCode}. Matches
+ * `.env`, `.env.<suffix>`, and `<name>.env`.
+ *
+ * @param path - A workspace-relative or absolute file path.
+ * @returns `true` when the file is an env file.
+ */
+export function isEnvFilePath(path) {
+    const base = path.split('/').pop() ?? '';
+    return base === '.env' || base.startsWith('.env.') || base.endsWith('.env');
+}
 // ── 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;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@molecule/api-ai-tools",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "Shared AI agent tools with backend abstraction for sandbox and local execution",
   "type": "module",
   "main": "dist/index.js",
@@ -17,7 +17,8 @@
     }
   },
   "files": [
-    "dist"
+    "dist",
+    "README.md"
   ],
   "keywords": [
     "molecule",
@@ -27,10 +28,10 @@
   ],
   "license": "Apache-2.0",
   "peerDependencies": {
-    "@molecule/api-ai": "^1.0.0"
+    "@molecule/api-ai": "^1.0.1"
   },
   "devDependencies": {
-    "@molecule/api-ai": "1.0.0",
+    "@molecule/api-ai": "1.0.1",
     "@types/node": "26.1.2",
     "typescript": "6.0.3",
     "vitest": "4.1.10"