@molecule/api-ai-tools 1.16.7 → 1.17.0

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-11-06T02:27:22.476Z
+Generated: 2026-11-06T13:53:38.704Z
 -->
 
 # @molecule/api-ai-tools
@@ -51,7 +51,7 @@ for await (const event of requireProvider().chat({ system, tools, messages, stre
 ## Installation
 
 ```bash
-npm install @molecule/api-ai-tools @molecule/api-ai
+npm install @molecule/api-ai-tools @molecule/api-ai typescript
 ```
 
 ## API
@@ -80,6 +80,36 @@ interface ForegroundBrowserProbe extends BrowserProbeLeak {
 }
 ```
 
+#### `CommandPlanStep`
+
+One sequential command, with boundaries emitted by its launcher around execution.
+
+```typescript
+interface CommandPlanStep {
+  /** Launcher's stable step identity. */
+  id: string
+  /** The logical command actually executed, including launch rewrites. */
+  command: string
+  /** Printed on its own line immediately before this step runs. */
+  startMarker: string
+  /** Printed on its own line after this step settles. */
+  endMarker: string
+}
+```
+
+#### `CommandPlan`
+
+A wrapper's ordered commands; metadata describes execution, never proof or completion.
+
+```typescript
+interface CommandPlan {
+  /** Per-launch boundary identity, preventing ordinary suite output from matching a boundary. */
+  id: string
+  /** Steps execute in this order. */
+  steps: CommandPlanStep[]
+}
+```
+
 #### `CommandSegment`
 
 One statement or pipeline stage of a shell command: what it runs, and with what.
@@ -374,6 +404,111 @@ interface RunnerOutputFilter {
 }
 ```
 
+#### `FeedbackSource`
+
+A source file already read by the caller. Paths are absolute.
+
+```typescript
+interface FeedbackSource {
+  path: string
+  content: string
+}
+```
+
+#### `FeedbackSpec`
+
+One supplied or scaffolded spec, with its normal, locally targeted runner command.
+
+```typescript
+interface FeedbackSpec extends FeedbackSource {
+  command: string
+  cwd: string
+}
+```
+
+#### `FeedbackProject`
+
+The inputs the host already knows; no suite discovery or vendor selection in the scheduler.
+
+```typescript
+interface FeedbackProject {
+  /** Base for relative source-change paths, already resolved by the host. */
+  root?: string
+  sources: FeedbackSource[]
+  specs: FeedbackSpec[]
+}
+```
+
+#### `PlaywrightFeedbackFailure`
+
+A native failure, never a static prediction or a completed-suite proof.
+
+```typescript
+interface PlaywrightFeedbackFailure {
+  spec: string
+  line: number
+  error: string
+  /** The native runner's locator or assertion, verbatim apart from redaction. */
+  locator: string
+  /** Playwright's own failure-time accessibility snapshot, when recorded. */
+  rendered?: string
+  /** Route render dependencies affected by this write, or the triggering source paths. */
+  sourceFiles: string[]
+}
+```
+
+#### `PlaywrightFeedbackResult`
+
+A diagnosis of one spec file at one source revision. A pass is not whole-suite proof.
+
+```typescript
+interface PlaywrightFeedbackResult {
+  spec: string
+  revision: number
+  durationMs: number
+  status: 'passed' | 'failed' | 'unavailable'
+  failures: PlaywrightFeedbackFailure[]
+  /** Native counts for this one diagnostic selection, never whole-suite proof. */
+  nativeStats?: PlaywrightReportStats
+  reason?: string
+}
+```
+
+#### `PlaywrightFeedbackOptions`
+
+Host operations for the same scheduler in a CLI process or a remote sandbox.
+
+```typescript
+interface PlaywrightFeedbackOptions {
+  load: () => Promise<FeedbackProject>
+  run: (
+    spec: FeedbackSpec,
+    sources: string[],
+    revision: number,
+    emit: (result: PlaywrightFeedbackResult) => void,
+  ) => Promise<PlaywrightFeedbackResult>
+  /** Only current native failures are delivered. Passing apps receive no note. */
+  onFailures?: (result: PlaywrightFeedbackResult) => void
+  /** Operational state is separate from defect feedback. */
+  onResult?: (result: PlaywrightFeedbackResult) => void
+  debounceMs?: number
+}
+```
+
+#### `PlaywrightFeedback`
+
+A nonblocking source-change subscription.
+
+```typescript
+interface PlaywrightFeedback {
+  changed: (paths: readonly string[]) => void
+  takeFailures: () => PlaywrightFeedbackResult[]
+  /** Wait only in tests or shutdown; file writes and deploys must never await this. */
+  settled: () => Promise<void>
+  close: () => Promise<void>
+}
+```
+
 #### `PlaywrightReportAttachment`
 
 One artifact the runner saved for one test, as the report records it.
@@ -1798,6 +1933,94 @@ function browserProbeOverBudgetAdvice(probe: ForegroundBrowserProbe): string
 
 **Returns:** The sentence the cut result carries.
 
+#### `createCommandPlan(steps)`
+
+Give already-prepared logical commands unique log boundaries.
+
+```typescript
+function createCommandPlan(steps: { id: string; command: string }[]): CommandPlan
+```
+
+- `steps` — Commands in execution order.
+
+**Returns:** Metadata for the wrapper and the launcher that executes its steps.
+
+#### `commandWithPlan(command, plan)`
+
+Preserve a wrapper's typed logical plan in its durable shell script, including across restarts.
+Shell comments keep this independent of the wrapper's executable, arguments and payload format.
+
+```typescript
+function commandWithPlan(command: string, plan: CommandPlan): string
+```
+
+- `command` — Executed wrapper.
+- `plan` — Commands the launcher will actually execute and delimit.
+
+**Returns:** A shell command with a passive metadata header.
+
+#### `commandPlan(command)`
+
+Read the shared descriptor, never a launcher's private wrapper format.
+
+```typescript
+function commandPlan(command: string): CommandPlan | null
+```
+
+- `command` — Command or recovered task script.
+
+**Returns:** A valid logical plan, or null for an ordinary command.
+
+#### `logicalCommandText(command)`
+
+Commands a wrapper will run, for static classification; live diagnostics use commandStepView.
+
+```typescript
+function logicalCommandText(command: string): string
+```
+
+- `command` — Executed command.
+
+**Returns:** Logical commands in order, or the direct command unchanged.
+
+#### `commandStepView(command, output)`
+
+Select only the step that owns the latest log boundary. Completed steps cannot supply a live
+failure, target, retry policy, file selection or rerun. Before the first boundary and between
+steps the live command is unknown; no diagnostic is permitted.
+
+```typescript
+function commandStepView(
+  command: string,
+  output: string,
+): {
+  command: string
+  output: string
+  complete: boolean
+  /** Unique execution step, including when adjacent steps run identical commands. */
+  stepKey?: string
+}
+```
+
+- `command` — Wrapper or direct command.
+- `output` — Whole log, or the boundary-preserving bounded read.
+
+**Returns:** Active command and its output, plus whether the entire step's output is available.
+
+#### `commandPlanLogRead(plan, limit)`
+
+AWK program for a bounded read that retains the active boundary even after a long step and
+discards prior steps. A truncated step cannot establish a universal failure across its history.
+
+```typescript
+function commandPlanLogRead(plan: CommandPlan, limit: number): string
+```
+
+- `plan` — Logical plan whose boundaries the launcher emits.
+- `limit` — Maximum output characters retained for diagnosis.
+
+**Returns:** An AWK program; callers shell-quote it like every other argument.
+
 #### `durationSeconds(word)`
 
 The seconds a duration word stands for.
@@ -2432,6 +2655,96 @@ function pipelineExitCodeNote(command: string, exitCode: number, output: string)
 
 **Returns:** One sentence naming the stage the code came from, or null.
 
+#### `selectFeedbackSpecs(project, changed)`
+
+Prioritize spec files potentially affected by writes. Every file still runs: a click or
+a helper can navigate somewhere a literal-goto index cannot see. This index never excludes work.
+
+```typescript
+function selectFeedbackSpecs(
+  project: FeedbackProject,
+  changed: readonly string[],
+): Array<{ spec: FeedbackSpec; sourceFiles: string[] }>
+```
+
+- `project` — Caller-supplied source and runner inventory.
+- `changed` — Absolute source paths changed since the previous diagnosis.
+
+**Returns:** Spec files to run, with their rendering-source context.
+
+#### `isPlaywrightFeedbackSource(path)`
+
+Whether a source change can alter markup, copy, styling or local runner configuration.
+
+```typescript
+function isPlaywrightFeedbackSource(path: string): boolean
+```
+
+- `path` — The path reported by the host's file-change subscription.
+
+**Returns:** True for app source and data formats; never a correctness judgment.
+
+#### `createPlaywrightFeedback(options)`
+
+Subscribe to writes without making them wait for browser work.
+
+```typescript
+function createPlaywrightFeedback(options: PlaywrightFeedbackOptions): PlaywrightFeedback
+```
+
+- `options` — Source loader, native runner and delivery callbacks.
+
+**Returns:** A source-change subscription; settle/close are for tests and shutdown only.
+
+#### `readFeedbackSources(backend, sourceRoots, suiteFiles)`
+
+Read explicit source roots and supplied helper/spec paths in one backend round trip.
+The standard filesystem and TypeScript parser own traversal/syntax; this is transport batching.
+
+```typescript
+function readFeedbackSources(
+  backend: ExecutionBackend,
+  sourceRoots: readonly string[],
+  suiteFiles: readonly string[],
+): Promise<FeedbackSource[]>
+```
+
+- `backend` — Local or sandbox execution backend.
+- `sourceRoots` — App source directories, absolute.
+- `suiteFiles` — Supplied spec/helper paths, absolute.
+
+**Returns:** Existing, bounded text sources. Missing/unsupported files are ignored.
+
+#### `runPlaywrightFeedback(backend, spec, sourceFiles, revision, options)`
+
+Run ONE spec's native command. Callers supply the correctly configured local command and
+append these runner flags at composition time (rather than modifying shell text here).
+Native failures are diagnosis, never proof that a complete supplied suite passed.
+
+```typescript
+function runPlaywrightFeedback(
+  backend: ExecutionBackend,
+  spec: FeedbackSpec,
+  sourceFiles: string[],
+  revision: number,
+  options: {
+    command: (flags: string[]) => string
+    scratchRoot?: string
+    timeoutMs?: number
+    emit?: (result: PlaywrightFeedbackResult) => void
+    pollMs?: number
+  },
+): Promise<PlaywrightFeedbackResult>
+```
+
+- `backend` — Existing execution backend.
+- `spec` — The supplied spec and its normal per-file command.
+- `sourceFiles` — Triggering component files, known to the write/index.
+- `revision` — Source revision the scheduler will validate before delivery.
+- `options` — Output location, command composition and a bounded backend budget.
+
+**Returns:** The actual native outcome and actionable failures only.
+
 #### `reportCarriesIdentities(status)`
 
 The report statuses for which the report's own per-test identities and attachments may be used.
@@ -4456,7 +4769,7 @@ function failureBlocks(s: string): string[]
 
 **Returns:** Each block, in order (empty when there are none).
 
-#### `runningOutputSliceCommand(log, own)`
+#### `runningOutputSliceCommand(log, own, command)`
 
 The shell command whose stdout is the interesting part of a log that is still being written:
 the failure lines so far (capped at {@link RUNNING_FAILURE_LINES}), then the end of the log.
@@ -4473,6 +4786,7 @@ function runningOutputSliceCommand(log: string, own?: string): string
 
 - `log` — The task log path.
 - `own` — A file the command redirects its own output to, if any.
+- `command` — Executed command, whose logical plan supplies live step boundaries if present.
 
 **Returns:** The shell command, safe to hand to the execution backend as-is.
 
@@ -4488,7 +4802,7 @@ a duration — three bodies do not fit, and the repeat is invisible. This read i
 anyone; it is parsed.
 
 ```typescript
-function runningCauseCommand(log: string, own?: string): string
+function runningCauseCommand(log: string, own?: string, command?: string): string
 ```
 
 - `log` — The task log path.
@@ -5546,6 +5860,14 @@ Bytes of a running log a repeating-cause look reads back.
 const REPEATING_CAUSE_TAIL_BYTES: 40000
 ```
 
+#### `COMMAND_PLAN_LOG_CHARS`
+
+Whole-step history retained for wrapped plans; ordinary diagnostic logs fit inside this bound.
+
+```typescript
+const COMMAND_PLAN_LOG_CHARS: 4000000
+```
+
 #### `RUNNING_LOG_READ_BYTES`
 
 Bytes of a running log a diagnostic note reads back: one {@link REPEATING_CAUSE_TAIL_BYTES} window.
@@ -5677,7 +5999,21 @@ Peer dependencies:
 ### Runtime Dependencies
 
 - `@molecule/api-ai`
-
+- `typescript`
+
+- **Background Playwright feedback:** `createPlaywrightFeedback({ load, run, onFailures })`
+  coalesces `changed(paths)` events without delaying writes. Use `readFeedbackSources`
+  to batch source reads over either backend and `runPlaywrightFeedback` to run each
+  supplied spec through its native command. Its incremental reporter supplies exact
+  locator failures and the failure-time page snapshot. Healthy runs emit no note;
+  no suite schedules no runner. `settled()`/`close()` are for tests and shutdown,
+  never a deployment barrier. Diagnoses are not whole-suite completion proof.
+- **Opaque command plans:** prepare each logical step with `streamingBackgroundCommand`,
+  call `createCommandPlan`, and attach it to the executed wrapper with `commandWithPlan`.
+  The launcher prints each step's `startMarker` and `endMarker` on their own lines around
+  execution. `commandStepView` reads the active step for diagnostics; `logicalCommandText`
+  exposes the planned commands for static classification. Preserve the descriptor when
+  wrapping again. The metadata is advisory and never establishes a completed test result.
 - **`yieldOnFirstFailureFor`** can yield one still-running deployed task's concrete diagnostic; callers opt out after a prior wait result or unknown history.
 - **`wait_for_task` state probes report current progress without guessing log growth.**
   A call shorter than one normal two-second poll omits both growth and no-growth

package/dist/backends/local.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"local.d.ts","sourceRoot":"","sources":["../../src/backends/local.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAMH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAA;AAEnD;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,WAAW,EAAE,MAAM,GAAG,gBAAgB,CAsDxE"}
+{"version":3,"file":"local.d.ts","sourceRoot":"","sources":["../../src/backends/local.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAMH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAA;AAEnD;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,WAAW,EAAE,MAAM,GAAG,gBAAgB,CA6FxE"}

package/dist/backends/local.js

@@ -4,7 +4,7 @@
  *
  * @module
  */
-import { execFile } from 'child_process';
+import { spawn } from 'child_process';
 import { mkdir, readdir, readFile, unlink, writeFile } from 'fs/promises';
 import { dirname } from 'path';
 /**
@@ -38,23 +38,69 @@ export function createLocalBackend(projectRoot) {
         },
         run(command, opts) {
             return new Promise((resolve) => {
-                // Use shell: true for command strings (grep pipelines, find, etc.)
-                // Input is sanitized via shellQuote at the tool level
-                execFile('sh', ['-c', command], {
+                // A native runner owns children. execFile's timeout killed only sh,
+                // leaving the runner/browser alive. Use the OS process group, with a
+                // graceful signal followed by a bounded forceful cleanup of that group.
+                const grouped = process.platform !== 'win32';
+                const child = spawn('sh', ['-c', command], {
                     cwd: opts?.cwd || projectRoot,
-                    timeout: opts?.timeout || 30000,
-                    maxBuffer: 10 * 1024 * 1024,
-                    encoding: 'utf8',
-                }, (error, stdout, stderr) => {
-                    if (error && 'code' in error && typeof error.code === 'number') {
-                        resolve({ stdout: stdout || '', stderr: stderr || '', exitCode: error.code });
+                    detached: grouped,
+                    stdio: ['ignore', 'pipe', 'pipe'],
+                });
+                let stdout = '', stderr = '', closed = false, code = 1;
+                let stopped;
+                let force;
+                const finish = () => {
+                    if (closed && !force)
+                        resolve({ stdout, stderr, exitCode: stopped === 'timeout' ? 124 : stopped ? 1 : code });
+                };
+                const signal = (value) => {
+                    try {
+                        if (grouped && child.pid)
+                            process.kill(-child.pid, value);
+                        else
+                            child.kill(value);
                     }
-                    else if (error) {
-                        resolve({ stdout: stdout || '', stderr: stderr || error.message, exitCode: 1 });
+                    catch (_error) {
+                        /* the owned group already exited */
                     }
-                    else {
-                        resolve({ stdout: stdout || '', stderr: stderr || '', exitCode: 0 });
+                };
+                const stop = (why) => {
+                    if (stopped)
+                        return;
+                    stopped = why;
+                    signal('SIGTERM');
+                    force = setTimeout(() => {
+                        signal('SIGKILL');
+                        force = undefined;
+                        finish();
+                    }, 1000);
+                };
+                const timeout = Math.min(opts?.timeout || 30_000, opts?.budgetMs || Infinity);
+                const deadline = setTimeout(() => stop('timeout'), timeout);
+                const collect = (text, channel) => {
+                    if (stopped)
+                        return;
+                    if (stdout.length + stderr.length + text.length > 10 * 1024 * 1024) {
+                        stderr += '\nCommand exceeded the 10 MB output limit.';
+                        stop('output');
+                        return;
                     }
+                    if (channel === 'stdout')
+                        stdout += text;
+                    else
+                        stderr += text;
+                };
+                child.stdout.setEncoding('utf8').on('data', (text) => collect(text, 'stdout'));
+                child.stderr.setEncoding('utf8').on('data', (text) => collect(text, 'stderr'));
+                child.on('error', (error) => {
+                    stderr += error.message;
+                });
+                child.on('close', (exitCode) => {
+                    closed = true;
+                    code = exitCode ?? 1;
+                    clearTimeout(deadline);
+                    finish();
                 });
             });
         },

package/dist/command-plan.d.ts

@@ -0,0 +1,71 @@
+/** One sequential command, with boundaries emitted by its launcher around execution. */
+export interface CommandPlanStep {
+    /** Launcher's stable step identity. */
+    id: string;
+    /** The logical command actually executed, including launch rewrites. */
+    command: string;
+    /** Printed on its own line immediately before this step runs. */
+    startMarker: string;
+    /** Printed on its own line after this step settles. */
+    endMarker: string;
+}
+/** A wrapper's ordered commands; metadata describes execution, never proof or completion. */
+export interface CommandPlan {
+    /** Per-launch boundary identity, preventing ordinary suite output from matching a boundary. */
+    id: string;
+    /** Steps execute in this order. */
+    steps: CommandPlanStep[];
+}
+/**
+ * Give already-prepared logical commands unique log boundaries.
+ * @param steps - Commands in execution order.
+ * @returns Metadata for the wrapper and the launcher that executes its steps.
+ */
+export declare function createCommandPlan(steps: {
+    id: string;
+    command: string;
+}[]): CommandPlan;
+/**
+ * Preserve a wrapper's typed logical plan in its durable shell script, including across restarts.
+ * Shell comments keep this independent of the wrapper's executable, arguments and payload format.
+ * @param command - Executed wrapper.
+ * @param plan - Commands the launcher will actually execute and delimit.
+ * @returns A shell command with a passive metadata header.
+ */
+export declare function commandWithPlan(command: string, plan: CommandPlan): string;
+/**
+ * Read the shared descriptor, never a launcher's private wrapper format.
+ * @param command - Command or recovered task script.
+ * @returns A valid logical plan, or null for an ordinary command.
+ */
+export declare function commandPlan(command: string): CommandPlan | null;
+/**
+ * Commands a wrapper will run, for static classification; live diagnostics use commandStepView.
+ * @param command - Executed command.
+ * @returns Logical commands in order, or the direct command unchanged.
+ */
+export declare function logicalCommandText(command: string): string;
+/**
+ * Select only the step that owns the latest log boundary. Completed steps cannot supply a live
+ * failure, target, retry policy, file selection or rerun. Before the first boundary and between
+ * steps the live command is unknown; no diagnostic is permitted.
+ * @param command - Wrapper or direct command.
+ * @param output - Whole log, or the boundary-preserving bounded read.
+ * @returns Active command and its output, plus whether the entire step's output is available.
+ */
+export declare function commandStepView(command: string, output: string): {
+    command: string;
+    output: string;
+    complete: boolean;
+    /** Unique execution step, including when adjacent steps run identical commands. */
+    stepKey?: string;
+};
+/**
+ * AWK program for a bounded read that retains the active boundary even after a long step and
+ * discards prior steps. A truncated step cannot establish a universal failure across its history.
+ * @param plan - Logical plan whose boundaries the launcher emits.
+ * @param limit - Maximum output characters retained for diagnosis.
+ * @returns An AWK program; callers shell-quote it like every other argument.
+ */
+export declare function commandPlanLogRead(plan: CommandPlan, limit: number): string;
+//# sourceMappingURL=command-plan.d.ts.map

package/dist/command-plan.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"command-plan.d.ts","sourceRoot":"","sources":["../src/command-plan.ts"],"names":[],"mappings":"AAIA,wFAAwF;AACxF,MAAM,WAAW,eAAe;IAC9B,uCAAuC;IACvC,EAAE,EAAE,MAAM,CAAA;IACV,wEAAwE;IACxE,OAAO,EAAE,MAAM,CAAA;IACf,iEAAiE;IACjE,WAAW,EAAE,MAAM,CAAA;IACnB,uDAAuD;IACvD,SAAS,EAAE,MAAM,CAAA;CAClB;AAED,6FAA6F;AAC7F,MAAM,WAAW,WAAW;IAC1B,+FAA+F;IAC/F,EAAE,EAAE,MAAM,CAAA;IACV,mCAAmC;IACnC,KAAK,EAAE,eAAe,EAAE,CAAA;CACzB;AAKD;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,EAAE,GAAG,WAAW,CAUvF;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,WAAW,GAAG,MAAM,CAE1E;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,WAAW,GAAG,IAAI,CA4B/D;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAM1D;AAED;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAC7B,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,MAAM,GACb;IACD,OAAO,EAAE,MAAM,CAAA;IACf,MAAM,EAAE,MAAM,CAAA;IACd,QAAQ,EAAE,OAAO,CAAA;IACjB,mFAAmF;IACnF,OAAO,CAAC,EAAE,MAAM,CAAA;CACjB,CAsBA;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,WAAW,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAQ3E"}