@molecule/api-ai-tools 1.0.0 → 1.0.1

package/README.md

@@ -0,0 +1,649 @@
+<!--
+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-04T01:47:38.726Z
+-->
+
+# @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
+
+#### `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.
+
+```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.
+
+#### `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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@molecule/api-ai-tools",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "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"