@molecule/api-ai-tools 1.5.8 → 1.5.10

package/README.md

@@ -3,7 +3,7 @@ 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-10-15T23:00:29.499Z
+Generated: 2026-10-16T00:26:34.364Z
 -->
 
 # @molecule/api-ai-tools
@@ -58,6 +58,62 @@ npm install @molecule/api-ai-tools @molecule/api-ai
 
 ### Interfaces
 
+#### `NormalizableSchema`
+
+The JSON-Schema-ish shape every tool in this package declares.
+
+```typescript
+interface NormalizableSchema {
+  name: string
+  parameters?: {
+    type?: string
+    properties?: Record<string, { type?: string; description?: string }>
+    required?: string[]
+  }
+}
+```
+
+#### `NormalizedInput`
+
+The result of normalizing one tool call's input.
+
+```typescript
+interface NormalizedInput {
+  /** The input to hand the handler, with aliases moved onto the declared names. */
+  input: Record<string, unknown>
+  /** Declared-required parameters still absent after aliasing. */
+  missing: string[]
+  /** `alias→declared` pairs that were moved, for logging. */
+  aliased: string[]
+}
+```
+
+#### `GuardOptions`
+
+Options shared by {@link guardToolExecute} and {@link guardAITool}.
+
+```typescript
+interface GuardOptions {
+  /**
+   * Redactor applied to a THROWN error's message before it is returned to the
+   * model. Defaults to this package's `redactSecrets`.
+   */
+  redactError?: (message: string) => string
+}
+```
+
+#### `ToolSchema`
+
+JSON-schema-backed definition for a single agent tool.
+
+```typescript
+interface ToolSchema {
+  name: string
+  description: string
+  parameters: JSONSchema
+}
+```
+
 #### `ExecutionBackend`
 
 Abstraction over the execution environment.
@@ -110,117 +166,6 @@ interface ExecutionBackend {
 }
 ```
 
-#### `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
-}
-```
-
-#### `GuardOptions`
-
-Options shared by {@link guardToolExecute} and {@link guardAITool}.
-
-```typescript
-interface GuardOptions {
-  /**
-   * Redactor applied to a THROWN error's message before it is returned to the
-   * model. Defaults to this package's `redactSecrets`.
-   */
-  redactError?: (message: string) => string
-}
-```
-
-#### `NormalizableSchema`
-
-The JSON-Schema-ish shape every tool in this package declares.
-
-```typescript
-interface NormalizableSchema {
-  name: string
-  parameters?: {
-    type?: string
-    properties?: Record<string, { type?: string; description?: string }>
-    required?: string[]
-  }
-}
-```
-
-#### `NormalizedInput`
-
-The result of normalizing one tool call's input.
-
-```typescript
-interface NormalizedInput {
-  /** The input to hand the handler, with aliases moved onto the declared names. */
-  input: Record<string, unknown>
-  /** Declared-required parameters still absent after aliasing. */
-  missing: string[]
-  /** `alias→declared` pairs that were moved, for logging. */
-  aliased: 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.
@@ -308,15 +253,70 @@ interface ToolBuildConfig {
 }
 ```
 
-#### `ToolSchema`
+#### `FileDiffEvent`
 
-JSON-schema-backed definition for a single agent tool.
+Payload emitted when a tracked file changes contents.
 
 ```typescript
-interface ToolSchema {
+interface FileDiffEvent {
+  path: string
+  oldContent: string | null
+  newContent: string
+}
+```
+
+#### `FileChangeEvent`
+
+Payload emitted when a file is created, modified, or deleted structurally.
+
+```typescript
+interface FileChangeEvent {
+  type: 'created' | 'modified' | 'deleted'
+  path: string
+}
+```
+
+#### `SkillEntry`
+
+Metadata for a discovered skill (used in PromptContext).
+
+```typescript
+interface SkillEntry {
+  /** Skill name. */
   name: string
+  /** Short description. */
   description: string
-  parameters: JSONSchema
+  /** Relative path to the SKILL.md file. */
+  path: 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[]
 }
 ```
 
@@ -338,112 +338,117 @@ A tool call the handler refuses with a message meant for the model as is —
 thrown from deep inside a handler (a path check), returned by the guard as the
 call's `error` without the generic "check your parameters" wrapping.
 
-### Functions
-
-#### `buildAgentPrompt(ctx)`
+```typescript
+class ToolInputError extends Error {}
+```
 
-Build a coding-focused system prompt from composable sections.
+### Functions
 
-Returns a string that includes:
+#### `createLocalBackend(projectRoot)`
 
-- 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)
+Create an ExecutionBackend that operates on the local filesystem.
 
 ```typescript
-function buildAgentPrompt(ctx: PromptContext): string
+function createLocalBackend(projectRoot: string): ExecutionBackend
 ```
 
-- `ctx` — Prompt construction inputs (tools, docs, skills, etc.).
+- `projectRoot` — Absolute path to the project root directory
 
-**Returns:** Fully assembled system prompt text for the coding agent.
+**Returns:** A backend wired to `fs/promises` and guarded subprocess calls.
 
-#### `buildTools(backend, config)`
+#### `createSandboxBackend(sandbox, projectRoot)`
 
-Build a complete set of AI agent tools bound to an execution backend.
+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 buildTools(backend: ExecutionBackend, config?: ToolBuildConfig): AITool[]
+function createSandboxBackend(sandbox: SandboxLike, projectRoot?: string): ExecutionBackend
 ```
 
-- `backend` — The execution environment (sandbox or local filesystem)
-- `config` — Optional configuration for security, callbacks, and tool selection
+- `sandbox` — A running Sandbox instance from `@molecule/api-code-sandbox`
+- `projectRoot` — Root directory inside the sandbox (default: '/workspace')
 
-**Returns:** Array of AITool objects ready to pass to an AI provider
+**Returns:** A backend that proxies all filesystem calls into the sandbox.
 
-#### `checkBlockedCommand(command)`
+#### `normalizeToolInput(schema, raw)`
 
-Check if a command is blocked for security reasons. Returns error message or null if allowed.
+Move known aliases onto the declared parameter names and report what is still
+missing. Unknown keys are left in place — handlers ignore them, and dropping
+them would hide a model's intent from anything reading the call log.
 
 ```typescript
-function checkBlockedCommand(command: string): string | null
+function normalizeToolInput(schema: NormalizableSchema, raw: unknown): NormalizedInput
 ```
 
-- `command` — Shell command string proposed for execution.
+- `schema` — The tool's declared schema.
+- `raw` — Whatever the model sent as the tool input.
 
-**Returns:** A human-readable block reason, or `null` when the command is allowed.
+**Returns:** The normalized input plus the missing-required and aliased lists.
 
-#### `createLocalBackend(projectRoot)`
+#### `missingParamError(schema, input, missing)`
 
-Create an ExecutionBackend that operates on the local filesystem.
+The error a tool returns when a required parameter is still absent after
+aliasing. Model-facing, so it names the right parameter, what was actually
+sent, and the shape of a correct call — everything needed to fix it in one
+turn instead of concluding the tool is broken.
 
 ```typescript
-function createLocalBackend(projectRoot: string): ExecutionBackend
+function missingParamError(
+  schema: NormalizableSchema,
+  input: Record<string, unknown>,
+  missing: string[],
+): string
 ```
 
-- `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
-```
+- `schema` — The tool's declared schema.
+- `input` — The normalized input (used to list the keys that were sent).
+- `missing` — The required parameters still absent.
 
-- `sandbox` — A running Sandbox instance from `@molecule/api-code-sandbox`
-- `projectRoot` — Root directory inside the sandbox (default: '/workspace')
+**Returns:** A single-sentence-per-clause error string.
 
-**Returns:** A backend that proxies all filesystem calls into the sandbox.
+#### `guardToolExecute(schema, impl)`
 
-#### `declaredBudgetSeconds(command, timeoutParam)`
+Wrap a tool handler so every call is normalized first and a handler that
+THROWS returns something the model can act on.
 
-The time budget a COMMAND declares for itself — a `timeout <seconds>` prefix
-anywhere in it, or the tool call's own `timeout` (ms) parameter, whichever is
-larger. Zero when it declares none.
+The guard deliberately does NOT pre-empt the handler when a required
+parameter looks absent: several handlers accept a documented older shape
+(`edit_file`'s top-level `old_string`/`new_string`) or answer a missing
+parameter with far better guidance than a generic message could (`edit_file`
+telling the model to re-read the file). It steps in only where the handler
+would otherwise crash — and when it does, a still-missing required parameter
+is the accurate diagnosis for that crash, so it is reported as one.
 
 ```typescript
-function declaredBudgetSeconds(command: string, timeoutParam: unknown): number
+function guardToolExecute(
+  schema: NormalizableSchema,
+  impl: (input: Record<string, unknown>, ...rest: never[]) => Promise<unknown>,
+  options?: GuardOptions,
+): (input: unknown, ...rest: never[]) => Promise<unknown>
 ```
 
-- `command` — The shell command.
-- `timeoutParam` — The tool call's `timeout` input, in milliseconds.
+- `schema` — The tool's declared schema.
+- `impl` — The raw handler.
 
-**Returns:** The declared budget in seconds, or 0.
+**Returns:** A handler with the same signature, guarded.
 
-#### `directoryReadHint(message, path)`
+#### `guardAITool(tool)`
 
-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.
+Apply {@link guardToolExecute} to a ready-made tool object (the
+`@molecule/api-ai` `AITool` shape: `{ name, description, parameters,
+execute }`), returning a copy whose `execute` is guarded.
+
+Use it at the point a consumer hands its full tool list to the model, so
+tools built outside this package get the same treatment as the ones built
+inside it.
 
 ```typescript
-function directoryReadHint(message: string, path: string): string | null
+function guardAITool(tool: T, options?: GuardOptions): T
 ```
 
-- `message` — The backend error message.
-- `path` — The resolved path that was targeted.
+- `tool` — The tool to guard.
 
-**Returns:** An actionable directory-error string, or null.
+**Returns:** A copy with a guarded `execute`.
 
 #### `discoverSkills(backend)`
 
@@ -460,139 +465,141 @@ function discoverSkills(backend: ExecutionBackend): Promise<SkillEntry[]>
 
 **Returns:** Array of discovered skills with name, description, and path
 
-#### `guardAITool(tool)`
+#### `buildAgentPrompt(ctx)`
 
-Apply {@link guardToolExecute} to a ready-made tool object (the
-`@molecule/api-ai` `AITool` shape: `{ name, description, parameters,
-execute }`), returning a copy whose `execute` is guarded.
+Build a coding-focused system prompt from composable sections.
 
-Use it at the point a consumer hands its full tool list to the model, so
-tools built outside this package get the same treatment as the ones built
-inside it.
+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 guardAITool(tool: T, options?: GuardOptions): T
+function buildAgentPrompt(ctx: PromptContext): string
 ```
 
-- `tool` — The tool to guard.
+- `ctx` — Prompt construction inputs (tools, docs, skills, etc.).
 
-**Returns:** A copy with a guarded `execute`.
+**Returns:** Fully assembled system prompt text for the coding agent.
 
-#### `guardToolExecute(schema, impl)`
+#### `buildTools(backend, config)`
 
-Wrap a tool handler so every call is normalized first and a handler that
-THROWS returns something the model can act on.
+Build a complete set of AI agent tools bound to an execution backend.
 
-The guard deliberately does NOT pre-empt the handler when a required
-parameter looks absent: several handlers accept a documented older shape
-(`edit_file`'s top-level `old_string`/`new_string`) or answer a missing
-parameter with far better guidance than a generic message could (`edit_file`
-telling the model to re-read the file). It steps in only where the handler
-would otherwise crash — and when it does, a still-missing required parameter
-is the accurate diagnosis for that crash, so it is reported as one.
+```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
+
+#### `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 guardToolExecute(
-  schema: NormalizableSchema,
-  impl: (input: Record<string, unknown>, ...rest: never[]) => Promise<unknown>,
-  options?: GuardOptions,
-): (input: unknown, ...rest: never[]) => Promise<unknown>
+function shellQuote(s: string): string
 ```
 
-- `schema` — The tool's declared schema.
-- `impl` — The raw handler.
+- `s` — Raw string to wrap for POSIX shell single-quoted context.
 
-**Returns:** A handler with the same signature, guarded.
+**Returns:** A single-quoted shell literal representing `s`.
 
-#### `isEnvFilePath(path)`
+#### `stripControlChars(s)`
 
-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`.
+Strip C0 control chars (except tab, newline, CR) that break PostgreSQL JSONB
+and can cause rendering issues.
 
 ```typescript
-function isEnvFilePath(path: string): boolean
+function stripControlChars(s: string): string
 ```
 
-- `path` — A workspace-relative or absolute file path.
+- `s` — Arbitrary text that may contain disallowed control characters.
 
-**Returns:** `true` when the file is an env file.
+**Returns:** A copy of `s` with unsafe control characters removed.
 
-#### `isOutsideRoot(path, projectRoot)`
+#### `redactSecrets(s)`
 
-Whether a tool path points outside the project root once normalized (an
-absolute path elsewhere, or a `..` that climbs out). {@link resolvePath}
-clamps such a path to the root; a file tool must refuse it instead of
-answering about the root — a `list_files /tmp/x` used to return the
-workspace listing as if it were `/tmp/x` (X1 runs sonnet-m17 and sol-m05,
-2026-10-14).
+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 isOutsideRoot(path: string, projectRoot: string): boolean
+function redactSecrets(s: string): string
 ```
 
-- `path` — The path the tool was given.
-- `projectRoot` — The project root.
+- `s` — Log or command output that may contain `.env`-style secrets.
 
-**Returns:** True when the path leaves the root.
+**Returns:** A redacted copy safe to surface to end users or models.
 
-#### `isValidGlob(pattern)`
+#### `redactSecretsInCode(s)`
 
-Validate that a glob/include pattern is safe (no shell metacharacters that could
-inject). Allows alphanumeric, `* ? . _ - /` and the bracket/paren glob chars `[] ()`.
+CODE-SAFE redaction — the env-assignment pass of {@link redactSecrets} WITHOUT
+the JSON `KEY: 'value'` passes.
 
-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.
+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 isValidGlob(pattern: string): boolean
+function redactSecretsInCode(s: string): string
 ```
 
-- `pattern` — User-supplied glob fragment for search/list operations.
+- `s` — Source-file content or other code-shaped text.
 
-**Returns:** `true` when the pattern contains only allowed characters.
+**Returns:** A redacted copy that preserves ordinary code verbatim.
 
-#### `missingParamError(schema, input, missing)`
+#### `isEnvFilePath(path)`
 
-The error a tool returns when a required parameter is still absent after
-aliasing. Model-facing, so it names the right parameter, what was actually
-sent, and the shape of a correct call — everything needed to fix it in one
-turn instead of concluding the tool is broken.
+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 missingParamError(
-  schema: NormalizableSchema,
-  input: Record<string, unknown>,
-  missing: string[],
-): string
+function isEnvFilePath(path: string): boolean
 ```
 
-- `schema` — The tool's declared schema.
-- `input` — The normalized input (used to list the keys that were sent).
-- `missing` — The required parameters still absent.
+- `path` — A workspace-relative or absolute file path.
 
-**Returns:** A single-sentence-per-clause error string.
+**Returns:** `true` when the file is an env file.
 
-#### `normalizeToolInput(schema, raw)`
+#### `declaredBudgetSeconds(command, timeoutParam)`
 
-Move known aliases onto the declared parameter names and report what is still
-missing. Unknown keys are left in place — handlers ignore them, and dropping
-them would hide a model's intent from anything reading the call log.
+The time budget a COMMAND declares for itself — a `timeout <seconds>` prefix
+anywhere in it, or the tool call's own `timeout` (ms) parameter, whichever is
+larger. Zero when it declares none.
 
 ```typescript
-function normalizeToolInput(schema: NormalizableSchema, raw: unknown): NormalizedInput
+function declaredBudgetSeconds(command: string, timeoutParam: unknown): number
 ```
 
-- `schema` — The tool's declared schema.
-- `raw` — Whatever the model sent as the tool input.
+- `command` — The shell command.
+- `timeoutParam` — The tool call's `timeout` input, in milliseconds.
 
-**Returns:** The normalized input plus the missing-required and aliased lists.
+**Returns:** The declared budget in seconds, or 0.
 
 #### `outputIsWithheldUntilExit(command)`
 
@@ -629,126 +636,127 @@ function outputRedirectTarget(command: string): string | null
 
 **Returns:** The target as written, or null (`/dev/null` and `&1`/`&2` are not files).
 
-#### `parseCheckCommand(path)`
+#### `streamingBackgroundCommand(command)`
 
-The shell command that parses one file and exits non-zero with the error
-when it does not parse: `node --check` for JavaScript, `JSON.parse` for
-JSON, esbuild's transform (present wherever Vite is) for TypeScript.
+Rewrite a command about to run in the background so its log grows while it
+runs. Two shapes left the log empty until exit, and an empty log is what
+`wait_for_task` reads as "stuck", so working suites were reported stuck and
+killed (X1 run flash-m15 lost 20 of its 60 minutes this way, 2026-10-15):
+
+- a trailing `| tail -N`, which holds everything back until the command ends.
+  It is dropped: `wait_for_task` already returns the end of the log.
+- `playwright test` with no `--reporter`, which runs the config's reporter —
+  often `html`, which prints nothing per test. `--reporter=line` is added
+  when the playwright run is the command's last step and nothing is piped or
+  redirected from it ( aside); the results are the same, printed as they happen.
 
 ```typescript
-function parseCheckCommand(path: string): string | null
+function streamingBackgroundCommand(command: string): { command: string; changes: string[] }
 ```
 
-- `path` — The file's absolute path.
+- `command` — The command as the executor sent it.
 
-**Returns:** The command, or null when the file type has no cheap parser.
+**Returns:** The command to run and one sentence per change made (empty when none).
 
-#### `parseCheckProblem(result)`
+#### `checkBlockedCommand(command)`
 
-What a failed parse check says to the executor, or null when the check
-passed or could not run (no parser available is not a syntax error).
+Check if a command is blocked for security reasons. Returns error message or null if allowed.
 
 ```typescript
-function parseCheckProblem(result: {
-  stdout: string
-  stderr: string
-  exitCode: number
-}): string | null
+function checkBlockedCommand(command: string): string | null
 ```
 
-- `result` — The check command's result.
+- `command` — Shell command string proposed for execution.
 
-**Returns:** The message for the tool result, or null.
+**Returns:** A human-readable block reason, or `null` when the command is allowed.
 
-#### `pathArgError(path, tool)`
+#### `resolvePath(path, projectRoot)`
 
-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.
+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 pathArgError(path: unknown, tool: string): string | null
+function resolvePath(path: string, projectRoot: string): string
 ```
 
-- `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.
+- `path` — Relative or absolute path inside the workspace.
+- `projectRoot` — Absolute filesystem root for the active project.
 
-#### `redactSecrets(s)`
+**Returns:** A normalized absolute path confined to `projectRoot`.
 
-Redact values of common secret/credential patterns in text output.
+#### `isOutsideRoot(path, projectRoot)`
 
-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.
+Whether a tool path points outside the project root once normalized (an
+absolute path elsewhere, or a `..` that climbs out). {@link resolvePath}
+clamps such a path to the root; a file tool must refuse it instead of
+answering about the root — a `list_files /tmp/x` used to return the
+workspace listing as if it were `/tmp/x` (X1 runs sonnet-m17 and sol-m05,
+2026-10-14).
 
 ```typescript
-function redactSecrets(s: string): string
+function isOutsideRoot(path: string, projectRoot: string): boolean
 ```
 
-- `s` — Log or command output that may contain `.env`-style secrets.
-
-**Returns:** A redacted copy safe to surface to end users or models.
+- `path` — The path the tool was given.
+- `projectRoot` — The project root.
 
-#### `redactSecretsInCode(s)`
+**Returns:** True when the path leaves the root.
 
-CODE-SAFE redaction — the env-assignment pass of {@link redactSecrets} WITHOUT
-the JSON `KEY: 'value'` passes.
+#### `isValidGlob(pattern)`
 
-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.
+Validate that a glob/include pattern is safe (no shell metacharacters that could
+inject). Allows alphanumeric, `* ? . _ - /` and the bracket/paren glob chars `[] ()`.
 
-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.
+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 redactSecretsInCode(s: string): string
+function isValidGlob(pattern: string): boolean
 ```
 
-- `s` — Source-file content or other code-shaped text.
+- `pattern` — User-supplied glob fragment for search/list operations.
 
-**Returns:** A redacted copy that preserves ordinary code verbatim.
+**Returns:** `true` when the pattern contains only allowed characters.
 
-#### `resolvePath(path, projectRoot)`
+#### `pathArgError(path, tool)`
 
-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.
+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 resolvePath(path: string, projectRoot: string): string
+function pathArgError(path: unknown, tool: string): string | null
 ```
 
-- `path` — Relative or absolute path inside the workspace.
-- `projectRoot` — Absolute filesystem root for the active project.
+- `path` — The raw `path` argument from the tool input.
+- `tool` — The tool name, for the error message (e.g. 'read_file').
 
-**Returns:** A normalized absolute path confined to `projectRoot`.
+**Returns:** An actionable error string, or null when `path` is a non-empty string.
 
-#### `shellQuote(s)`
+#### `directoryReadHint(message, path)`
 
-Shell-safe quoting using single quotes. Unlike JSON.stringify (double quotes),
-single-quoted strings prevent command substitution ($(), backticks) and variable expansion.
+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 shellQuote(s: string): string
+function directoryReadHint(message: string, path: string): string | null
 ```
 
-- `s` — Raw string to wrap for POSIX shell single-quoted context.
+- `message` — The backend error message.
+- `path` — The resolved path that was targeted.
 
-**Returns:** A single-quoted shell literal representing `s`.
+**Returns:** An actionable directory-error string, or null.
 
 #### `sliceLines(content, window)`
 
@@ -772,41 +780,6 @@ function sliceLines(
 
 **Returns:** The window plus its position, or null when neither was given.
 
-#### `streamingBackgroundCommand(command)`
-
-Rewrite a command about to run in the background so its log grows while it
-runs. Two shapes left the log empty until exit, and an empty log is what
-`wait_for_task` reads as "stuck", so working suites were reported stuck and
-killed (X1 run flash-m15 lost 20 of its 60 minutes this way, 2026-10-15):
-
-- a trailing `| tail -N`, which holds everything back until the command ends.
-  It is dropped: `wait_for_task` already returns the end of the log.
-- `playwright test` with no `--reporter`, which runs the config's reporter —
-  often `html`, which prints nothing per test. `--reporter=line` is added
-  when the playwright run is the command's last step and nothing is piped or
-  redirected from it ( aside); the results are the same, printed as they happen.
-
-```typescript
-function streamingBackgroundCommand(command: string): { command: string; changes: string[] }
-```
-
-- `command` — The command as the executor sent it.
-
-**Returns:** The command to run and one sentence per change made (empty when none).
-
-#### `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.
@@ -870,57 +843,61 @@ function whitespaceTolerantReplace(
 
 **Returns:** The new content if a unique fuzzy run matched, else null.
 
-### Constants
+#### `parseCheckCommand(path)`
 
-#### `DEFAULT_SEARCH_EXCLUDED_DIRS`
+The shell command that parses one file and exits non-zero with the error
+when it does not parse: `node --check` for JavaScript, `JSON.parse` for
+JSON, esbuild's transform (present wherever Vite is) for TypeScript.
 
-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
+function parseCheckCommand(path: string): string | null
+```
+
+- `path` — The file's absolute path.
+
+**Returns:** The command, or null when the file type has no cheap parser.
+
+#### `parseCheckProblem(result)`
+
+What a failed parse check says to the executor, or null when the check
+passed or could not run (no parser available is not a syntax error).
 
 ```typescript
-const DEFAULT_SEARCH_EXCLUDED_DIRS: readonly [
-  'node_modules',
-  'bower_components',
-  '.git',
-  '.svn',
-  '.hg',
-  'CVS',
-  'dist',
-  '.next',
-  '.vite',
-  'molecule',
-]
+function parseCheckProblem(result: {
+  stdout: string
+  stderr: string
+  exitCode: number
+}): string | null
 ```
 
-#### `MAX_BATCH_READ_BYTES`
+- `result` — The check command's result.
 
-Total content bytes one batched `read_file` call returns, across all files.
-The per-file {@link MAX_READ_SIZE} still applies to each one.
+**Returns:** The message for the tool result, or null.
+
+### Constants
+
+#### `TOOL_SCHEMAS`
+
+Canonical tool schemas shared by the agent runtime and documentation.
 
 ```typescript
-const MAX_BATCH_READ_BYTES: number
+const TOOL_SCHEMAS: Record<string, ToolSchema>
 ```
 
-#### `MAX_BATCH_READ_FILES`
+#### `MAX_READ_SIZE`
 
-Most files one batched `read_file` call returns. The cap exists so a survey
-of a large tree cannot swallow the turn's context in one result; the tool
-reports where it stopped so the model continues from there.
+Max file size for read_file (5MB).
 
 ```typescript
-const MAX_BATCH_READ_FILES: 25
+const MAX_READ_SIZE: number
 ```
 
-#### `MAX_FIND_RESULTS`
+#### `MAX_WRITE_SIZE`
 
-Max find results.
+Max content size for write_file (10MB).
 
 ```typescript
-const MAX_FIND_RESULTS: 100
+const MAX_WRITE_SIZE: number
 ```
 
 #### `MAX_OUTPUT_SIZE`
@@ -931,6 +908,35 @@ Max command output size (100KB per stream).
 const MAX_OUTPUT_SIZE: number
 ```
 
+#### `MAX_SEARCH_CONTEXT_LINES`
+
+Most lines of surrounding context `search_files` will return per match.
+Bounded so a broad pattern with a generous context cannot pull a whole tree
+into one reply.
+
+```typescript
+const MAX_SEARCH_CONTEXT_LINES: 40
+```
+
+#### `MAX_BATCH_READ_FILES`
+
+Most files one batched `read_file` call returns. The cap exists so a survey
+of a large tree cannot swallow the turn's context in one result; the tool
+reports where it stopped so the model continues from there.
+
+```typescript
+const MAX_BATCH_READ_FILES: 25
+```
+
+#### `MAX_BATCH_READ_BYTES`
+
+Total content bytes one batched `read_file` call returns, across all files.
+The per-file {@link MAX_READ_SIZE} still applies to each one.
+
+```typescript
+const MAX_BATCH_READ_BYTES: number
+```
+
 #### `MAX_READ_RETURN_CHARS`
 
 The most one read_file call returns for ONE file when no window was asked
@@ -948,24 +954,6 @@ needs.
 const MAX_READ_RETURN_CHARS: number
 ```
 
-#### `MAX_READ_SIZE`
-
-Max file size for read_file (5MB).
-
-```typescript
-const MAX_READ_SIZE: number
-```
-
-#### `MAX_SEARCH_CONTEXT_LINES`
-
-Most lines of surrounding context `search_files` will return per match.
-Bounded so a broad pattern with a generous context cannot pull a whole tree
-into one reply.
-
-```typescript
-const MAX_SEARCH_CONTEXT_LINES: 40
-```
-
 #### `MAX_SEARCH_RESULTS`
 
 Max search results.
@@ -974,28 +962,44 @@ Max search results.
 const MAX_SEARCH_RESULTS: 50
 ```
 
-#### `MAX_WRITE_SIZE`
+#### `MAX_FIND_RESULTS`
 
-Max content size for write_file (10MB).
+Max find results.
 
 ```typescript
-const MAX_WRITE_SIZE: number
+const MAX_FIND_RESULTS: 100
 ```
 
-#### `PARSE_CHECKABLE`
+#### `DEFAULT_SEARCH_EXCLUDED_DIRS`
 
-Files a parse check can vouch for cheaply right after a write.
+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 PARSE_CHECKABLE: RegExp
+const DEFAULT_SEARCH_EXCLUDED_DIRS: readonly [
+  'node_modules',
+  'bower_components',
+  '.git',
+  '.svn',
+  '.hg',
+  'CVS',
+  'dist',
+  '.next',
+  '.vite',
+  'molecule',
+]
 ```
 
-#### `TOOL_SCHEMAS`
+#### `PARSE_CHECKABLE`
 
-Canonical tool schemas shared by the agent runtime and documentation.
+Files a parse check can vouch for cheaply right after a write.
 
 ```typescript
-const TOOL_SCHEMAS: Record<string, ToolSchema>
+const PARSE_CHECKABLE: RegExp
 ```
 
 ## Injection Notes

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;AA8B9C,OAAO,KAAK,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,YAAY,CAAA;AAwCnE;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,gBAAgB,EAAE,MAAM,CAAC,EAAE,eAAe,GAAG,MAAM,EAAE,CA2/CxF"}
+{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../src/tools.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAA;AA8B9C,OAAO,KAAK,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,YAAY,CAAA;AAwCnE;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,gBAAgB,EAAE,MAAM,CAAC,EAAE,eAAe,GAAG,MAAM,EAAE,CAyhDxF"}

package/dist/tools.js

@@ -703,6 +703,29 @@ export function buildTools(backend, config) {
                                 error: `old_string not found in ${path}. The file's ACTUAL content near your target (copy the exact text from here):\n${snippet}`,
                             };
                         };
+                        // An import block the model rebuilt in its own order: the linter's
+                        // import sort owns that order, so name it and show the real block. X1
+                        // flash-m42 sent the same block three times in three orders.
+                        // Only when old_string is import statements and nothing else.
+                        const imported = /^(?:\s*import\b[^;]*?\bfrom\s+(['"])([^'"]+)\1;?)+\s*$/.exec(oldString)?.[2];
+                        if (imported) {
+                            const at = fileLines.findIndex((l) => l.includes(`'${imported}'`) || l.includes(`"${imported}"`));
+                            if (at >= 0) {
+                                let start = at;
+                                while (start > 0 && !/^\s*import\b/.test(fileLines[start]))
+                                    start--;
+                                const block = fileLines
+                                    .slice(start, at + 1)
+                                    .map((l, i) => `${start + i + 1}: ${l}`)
+                                    .join('\n');
+                                return {
+                                    error: `old_string not found in ${path}: it is an import block, and the linter's import ` +
+                                        `sort decides its order, so do not rebuild it. The file's import from ` +
+                                        `'${imported}' reads:\n${block}\nEdit one line of it, or add your import as a ` +
+                                        'new line and let the linter sort it.',
+                                };
+                            }
+                        }
                         const distinctiveLines = [
                             ...new Set(oldString
                                 .split('\n')
@@ -1039,8 +1062,11 @@ export function buildTools(backend, config) {
             // behind `| tail` it returns nothing (X1 flash-m29 lost a 290 s run that way).
             // A short one still comes back as a foreground result, through the grace below.
             const overCeiling = commandBudgetMs !== undefined &&
-                outputIsWithheldUntilExit(command) &&
-                (declaredSeconds > ceilingSeconds || /\bplaywright\s+test\b/.test(command));
+                ((outputIsWithheldUntilExit(command) &&
+                    (declaredSeconds > ceilingSeconds || /\bplaywright\s+test\b/.test(command))) ||
+                    // A redirected Playwright run shows nothing either (`> out.txt`), and was killed at
+                    // the ceiling with 38 tests unrun (X1 flash-m36).
+                    (/\bplaywright\s+test\b/.test(command) && outputRedirectTarget(command) !== null));
             if (input.run_in_background === true || overCeiling) {
                 const id = `mol-bg-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}`;
                 const log = `/tmp/${id}.log`;

package/dist/utilities.d.ts.map

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

package/dist/utilities.js

@@ -70,8 +70,10 @@ const SECRET_ENV_ASSIGNMENT = new RegExp(
 const SECRET_JSON_DQ = new RegExp(
 // A value ends at its closing quote OR the end of its line: cut off mid-value (`head -c`),
 // the old pattern ran on to a quote on a LATER line and swallowed the lines between (flash-m32).
-`(['"]?(?:\\w*(?:${SECRET_KEYWORDS})\\w*)['"]?\\s*[:=]\\s*)"(?:[^"\\\\\\n]|\\\\.)*(?:"|(?=\\n)|$)`, 'gi');
-const SECRET_JSON_SQ = new RegExp(`(['"]?(?:\\w*(?:${SECRET_KEYWORDS})\\w*)['"]?\\s*[:=]\\s*)'(?:[^'\\\\\\n]|\\\\.)*(?:'|(?=\\n)|$)`, 'gi');
+// The key starts at a real boundary: a package name ending in a keyword ("@molecule/app-auth": "1.2.0")
+// is not a secret, and matching from its tail masked the version (flash-m35).
+`((?<![\\w@/.-])['"]?(?:\\w*(?:${SECRET_KEYWORDS})\\w*)['"]?\\s*[:=]\\s*)"(?:[^"\\\\\\n]|\\\\.)*(?:"|(?=\\n)|$)`, 'gi');
+const SECRET_JSON_SQ = new RegExp(`((?<![\\w@/.-])['"]?(?:\\w*(?:${SECRET_KEYWORDS})\\w*)['"]?\\s*[:=]\\s*)'(?:[^'\\\\\\n]|\\\\.)*(?:'|(?=\\n)|$)`, '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
@@ -239,6 +241,13 @@ export function streamingBackgroundCommand(command) {
         changes.push(`Dropped the trailing \`${tail[0].trim()}\`: it holds all output back until the command ends, ` +
             'and wait_for_task returns the end of the log anyway.');
     }
+    // A Playwright run behind `| head -N` loses its tally, which prints last (X1
+    // flash-m32 counted ✓/✘ marks by hand); the full log comes back anyway.
+    const head = /\s*\|\s*head(?:\s+-n)?\s+-?\d+\s*$/.exec(out);
+    if (head && /\bplaywright\s+test\b/.test(out)) {
+        out = out.slice(0, head.index);
+        changes.push(`Dropped the trailing \`${head[0].trim()}\`: Playwright prints its pass/fail count last, and it would be cut.`);
+    }
     const lastStep = out.split(/&&|\|\||;/).at(-1) ?? '';
     if (/\bplaywright\s+test\b/.test(lastStep) &&
         !/--reporter\b/.test(lastStep) &&

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@molecule/api-ai-tools",
-  "version": "1.5.8",
+  "version": "1.5.10",
   "description": "Shared AI agent tools with backend abstraction for sandbox and local execution",
   "type": "module",
   "main": "dist/index.js",