@molecule/api-ai-tools

Auto-generated, AI-first package reference for the 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 AITools (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

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

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).

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.

interface FileChangeEvent {
  type: 'created' | 'modified' | 'deleted'
  path: string
}

FileDiffEvent

Payload emitted when a tracked file changes contents.

interface FileDiffEvent {
  path: string
  oldContent: string | null
  newContent: string
}

PromptContext

Context for building a composable system prompt.

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).

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.

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.

interface ToolSchema {
  name: string
  description: string
  parameters: JSONSchema
}

Types

DiscoveredSkill (deprecated)

Re-export SkillEntry as DiscoveredSkill for backwards compatibility.

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)

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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).

const DEFAULT_SEARCH_EXCLUDED_DIRS: readonly [
  'node_modules',
  'bower_components',
  '.git',
  '.svn',
  '.hg',
  'CVS',
  'dist',
  '.next',
  '.vite',
  'molecule',
]

MAX_FIND_RESULTS

Max find results.

const MAX_FIND_RESULTS: 100

MAX_OUTPUT_SIZE

Max command output size (100KB per stream).

const MAX_OUTPUT_SIZE: number

MAX_READ_SIZE

Max file size for read_file (5MB).

const MAX_READ_SIZE: number

MAX_SEARCH_RESULTS

Max search results.

const MAX_SEARCH_RESULTS: 50

MAX_WRITE_SIZE

Max content size for write_file (10MB).

const MAX_WRITE_SIZE: number

TOOL_SCHEMAS

Canonical tool schemas shared by the agent runtime and documentation.

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.