@molecule/api-ai-tools 1.16.6 → 1.16.8

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-05T22:20:21.693Z
+Generated: 2026-11-06T03:40:01.617Z
 -->
 
 # @molecule/api-ai-tools
@@ -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.
@@ -1188,6 +1218,30 @@ interface ExecutionBackend {
   /** Write content to a file. Creates parent directories as needed. */
   writeFile(path: string, content: string): Promise<void>
 
+  /**
+   * Optional single-call path check and bounded text read for write/edit tools.
+   * `realPath` must be resolved before reading; never read outside `symlinkRoot`.
+   * Null `content` means missing; omit it for a native read (large/unreadable text).
+   * Returned text must match readFile's decoding and honor any host file-method wrappers.
+   * Implementations must use this backend's `run` so host command wrappers still apply.
+   */
+  readFileForUpdate?(
+    path: string,
+    symlinkRoot?: string,
+  ): Promise<{ realPath: string; content?: string | null }>
+
+  /**
+   * Optional write followed by the supplied parse command in one transport call.
+   * Null means unsupported BEFORE a successful write; the caller uses writeFile/run.
+   * Never retry a transport error after a write may have landed. After-write and
+   * file-change hooks use the ordinary path so their ordering before parsing stays intact.
+   */
+  writeFileAndCheck?(
+    path: string,
+    content: string,
+    command: string,
+  ): Promise<{ stdout: string; stderr: string; exitCode: number } | null>
+
   /** Delete a file. */
   deleteFile(path: string): Promise<void>
 
@@ -1710,8 +1764,8 @@ function createLocalBackend(projectRoot: string): ExecutionBackend
 
 #### `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.
+Create an ExecutionBackend that delegates to an isolated sandbox instance.
+The sandbox.exec method runs inside the provider's isolated environment.
 
 ```typescript
 function createSandboxBackend(sandbox: SandboxLike, projectRoot?: string): ExecutionBackend
@@ -1774,6 +1828,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.
@@ -4432,7 +4574,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.
@@ -4449,6 +4591,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.
 
@@ -4464,7 +4607,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.
@@ -5522,6 +5665,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.
@@ -5654,6 +5805,12 @@ Peer dependencies:
 
 - `@molecule/api-ai`
 
+- **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
@@ -5723,6 +5880,11 @@ Peer dependencies:
   to the model, and execute `catalog.loader` like any other tool. Loading only
   exposes schemas, never grants permission or runs a tool. Persist its loaded
   names with `onLoad` to keep them available across turns and compaction.
+- **Sandbox writes batch transport work.** The optional backend operations
+  `readFileForUpdate` and `writeFileAndCheck` combine path safety with the old-text
+  read, then the write with its parse check. Diff tracking and redaction checks
+  stay in the tools. Format and change hooks retain their ordering before parsing;
+  large files and backends without these operations use the native file APIs.
 - **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

package/dist/backends/sandbox-file-operations.d.ts

@@ -0,0 +1,11 @@
+/** Bounded file/command batching for sandbox transports; native file APIs remain the fallback. */
+import type { ExecutionBackend } from '../types.js';
+/**
+ * Batch sandbox filesystem work through the backend's current command wrapper.
+ * Keeping `this.run` preserves a host's environment and module-resolution prelude.
+ *
+ * @param native - Original file delegates; host overrides must not be bypassed.
+ * @returns Optional backend operations that retain native fallbacks for large files.
+ */
+export declare function sandboxFileOperations(native: Pick<ExecutionBackend, 'readFile' | 'writeFile'>): Pick<ExecutionBackend, 'readFileForUpdate' | 'writeFileAndCheck'>;
+//# sourceMappingURL=sandbox-file-operations.d.ts.map

package/dist/backends/sandbox-file-operations.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sandbox-file-operations.d.ts","sourceRoot":"","sources":["../../src/backends/sandbox-file-operations.ts"],"names":[],"mappings":"AAAA,kGAAkG;AAElG,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAA;AAenD;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,IAAI,CAAC,gBAAgB,EAAE,UAAU,GAAG,WAAW,CAAC,GACvD,IAAI,CAAC,gBAAgB,EAAE,mBAAmB,GAAG,mBAAmB,CAAC,CA2FnE"}

package/dist/backends/sandbox-file-operations.js

@@ -0,0 +1,100 @@
+/** Bounded file/command batching for sandbox transports; native file APIs remain the fallback. */
+import { shellQuote } from '../utilities.js';
+// envd may truncate command output; Docker also caps a shell argument at 128 KiB.
+// Keep both envelopes small, and accept a read only after its complete JSON arrives.
+const MAX_ENVELOPE = 24_000;
+const WRITE_MARK = 'MOL_FILE_WRITTEN\n';
+const NO_WRITE_MARK = 'MOL_FILE_NOT_WRITTEN\n';
+// Native text APIs may strip an initial UTF-8 BOM (Response.text), whereas
+// command envelopes preserve it. Keep that provider-specific decoding on the native path.
+const READ_SCRIPT = `const fs=require('fs'),cp=require('child_process');const p=process.argv[1],root=process.argv[2];let realPath='';if(root){const r=cp.spawnSync('readlink',['-f',p],{encoding:'utf8'});realPath=(r.status===0?r.stdout:p).trim()}let out={realPath};if(!root||!realPath||realPath===root||realPath.startsWith(root==='/'?'/':root+'/')){try{if(fs.statSync(p).size<=24000){const content=fs.readFileSync(p,'utf8');if(content.charCodeAt(0)!==65279&&Buffer.byteLength(JSON.stringify({realPath,content}))<=24000)out={realPath,content}}}catch(e){if(e.code==='ENOENT'||e.code==='ENOTDIR')out.content=null;/* other errors use the native API */}}process.stdout.write(JSON.stringify(out))`;
+const WRITE_SCRIPT = `const fs=require('fs'),cp=require('child_process'),path=require('path');const r=JSON.parse(Buffer.from(process.argv[1],'base64').toString('utf8'));try{fs.mkdirSync(path.dirname(r.path),{recursive:true});fs.writeFileSync(r.path,r.content,'utf8')}catch(e){process.stdout.write('MOL_FILE_NOT_WRITTEN\\n');process.exit(1)}process.stdout.write('MOL_FILE_WRITTEN\\n');const c=cp.spawnSync('sh',['-c',r.command],{cwd:path.dirname(r.path),encoding:'utf8',timeout:15000,maxBuffer:10*1024*1024});process.stdout.write(JSON.stringify({stdout:c.stdout||'',stderr:c.stderr||'',exitCode:c.status??1}))`;
+/**
+ * Batch sandbox filesystem work through the backend's current command wrapper.
+ * Keeping `this.run` preserves a host's environment and module-resolution prelude.
+ *
+ * @param native - Original file delegates; host overrides must not be bypassed.
+ * @returns Optional backend operations that retain native fallbacks for large files.
+ */
+export function sandboxFileOperations(native) {
+    let supported = false;
+    const { readFile, writeFile } = native;
+    return {
+        async readFileForUpdate(path, symlinkRoot) {
+            const q = shellQuote(path);
+            // The native API may resolve relative paths against a different base than exec.
+            if (!path.startsWith('/') || this.readFile !== readFile) {
+                if (!symlinkRoot)
+                    return { realPath: '' };
+                const checked = await this.run(`readlink -f ${q} 2>/dev/null || echo ${q}`, {
+                    timeout: 5000,
+                });
+                return { realPath: checked.stdout.trim() };
+            }
+            const result = await this.run(`node -e ${shellQuote(READ_SCRIPT)} ${q} ${shellQuote(symlinkRoot ?? '')}`, {
+                timeout: 5000,
+            });
+            try {
+                const body = JSON.parse(result.stdout);
+                if (body &&
+                    typeof body === 'object' &&
+                    'realPath' in body &&
+                    typeof body.realPath === 'string') {
+                    supported = true;
+                    if ('content' in body && (typeof body.content === 'string' || body.content === null))
+                        return { realPath: body.realPath, content: body.content };
+                    return { realPath: body.realPath };
+                }
+            }
+            catch (_error) {
+                // Missing Node or truncated/malformed stdout cannot supply file contents.
+            }
+            supported = false;
+            if (!symlinkRoot)
+                return { realPath: '' };
+            // Native path verification still decides safety when batching is unavailable.
+            const checked = await this.run(`readlink -f ${q} 2>/dev/null || echo ${q}`, { timeout: 5000 });
+            return { realPath: checked.stdout.trim() };
+        },
+        async writeFileAndCheck(path, content, command) {
+            if (!path.startsWith('/') || !supported || this.writeFile !== writeFile)
+                return null;
+            const request = Buffer.from(JSON.stringify({ path, content, command })).toString('base64');
+            if (request.length > MAX_ENVELOPE)
+                return null;
+            const result = await this.run(`node -e ${shellQuote(WRITE_SCRIPT)} ${shellQuote(request)}`, {
+                // The target's parent may be created by this very write. The child parse
+                // command enters it only after mkdir/write have succeeded.
+                cwd: this.projectRoot,
+                timeout: 20_000,
+            });
+            if (!result.stdout.startsWith(WRITE_MARK)) {
+                // No successful write acknowledged (e.g. no Node or a filesystem error).
+                // The native API retains its provider-specific error and directory behavior.
+                if (result.stdout.startsWith(NO_WRITE_MARK) ||
+                    (result.exitCode === 127 && /node.*not found/.test(result.stderr)))
+                    return null;
+                throw new Error('Sandbox file write returned no completion acknowledgement; not retrying an uncertain write');
+            }
+            try {
+                const check = JSON.parse(result.stdout.slice(WRITE_MARK.length));
+                if (typeof check.stdout === 'string' &&
+                    typeof check.stderr === 'string' &&
+                    typeof check.exitCode === 'number')
+                    return check;
+            }
+            catch (_error) {
+                // The write succeeded, but its check output was truncated. Recheck only;
+                // never replay an acknowledged write or a failed transport.
+            }
+            return this.run(command, {
+                cwd: path.slice(0, path.lastIndexOf('/')) || '/',
+                timeout: 15_000,
+            }).catch((_error) => {
+                // Like the ordinary post-write check, an unavailable parser adds no syntax note.
+                // The write was acknowledged above, so only the best-effort check failed here.
+                return { stdout: '', stderr: '', exitCode: 0 };
+            });
+        },
+    };
+}

package/dist/backends/sandbox.d.ts

@@ -14,12 +14,12 @@ interface SandboxLike {
         name: string;
         type: 'file' | 'directory';
     }>>;
-    /** Sandbox command execution — already sandboxed within Docker. */
+    /** Sandbox command execution — already isolated by the provider. */
     [key: string]: any;
 }
 /**
- * Create an ExecutionBackend that delegates to a Docker sandbox instance.
- * The sandbox.exec method is inherently safe — it runs inside an isolated Docker container.
+ * Create an ExecutionBackend that delegates to an isolated sandbox instance.
+ * The sandbox.exec method runs inside the provider's isolated environment.
  *
  * @param sandbox - A running Sandbox instance from `@molecule/api-code-sandbox`
  * @param projectRoot - Root directory inside the sandbox (default: '/workspace')

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

@@ -1 +1 @@
-{"version":3,"file":"sandbox.d.ts","sourceRoot":"","sources":["../../src/backends/sandbox.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAA;AAGnD,sFAAsF;AACtF,UAAU,WAAW;IACnB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAA;IACvC,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IACvD,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IACvC,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,GAAG,WAAW,CAAA;KAAE,CAAC,CAAC,CAAA;IACnF,mEAAmE;IAEnE,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,CAAA;CACnB;AAED;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,WAAW,EACpB,WAAW,SAAe,GACzB,gBAAgB,CAmDlB"}
+{"version":3,"file":"sandbox.d.ts","sourceRoot":"","sources":["../../src/backends/sandbox.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAA;AAInD,sFAAsF;AACtF,UAAU,WAAW;IACnB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAA;IACvC,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IACvD,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IACvC,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,GAAG,WAAW,CAAA;KAAE,CAAC,CAAC,CAAA;IACnF,oEAAoE;IAEpE,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,CAAA;CACnB;AAED;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,WAAW,EACpB,WAAW,SAAe,GACzB,gBAAgB,CAuDlB"}

package/dist/backends/sandbox.js

@@ -5,16 +5,17 @@
  * @module
  */
 import { shellQuote } from '../utilities.js';
+import { sandboxFileOperations } from './sandbox-file-operations.js';
 /**
- * Create an ExecutionBackend that delegates to a Docker sandbox instance.
- * The sandbox.exec method is inherently safe — it runs inside an isolated Docker container.
+ * Create an ExecutionBackend that delegates to an isolated sandbox instance.
+ * The sandbox.exec method runs inside the provider's isolated environment.
  *
  * @param sandbox - A running Sandbox instance from `@molecule/api-code-sandbox`
  * @param projectRoot - Root directory inside the sandbox (default: '/workspace')
  * @returns A backend that proxies all filesystem calls into the sandbox.
  */
 export function createSandboxBackend(sandbox, projectRoot = '/workspace') {
-    return {
+    const backend = {
         projectRoot,
         readFile(path) {
             return sandbox.readFile(path);
@@ -54,9 +55,10 @@ export function createSandboxBackend(sandbox, projectRoot = '/workspace') {
             const fullCommand = budgetSeconds
                 ? `o=$(mktemp); e=$(mktemp); timeout -k 5 ${budgetSeconds} bash -c ${shellQuote(anchored)} > "$o" 2> "$e" < /dev/null; c=$?; cat "$o"; cat "$e" >&2; rm -f "$o" "$e"; exit $c`
                 : anchored;
-            // sandbox.exec is the Sandbox interface method — runs inside Docker, inherently sandboxed
+            // sandbox.exec is the Sandbox interface method — runs inside the provider's isolated environment
             const result = await sandbox.exec(fullCommand, { timeout: opts?.timeout });
             return { stdout: result.stdout, stderr: result.stderr, exitCode: result.exitCode };
         },
     };
+    return Object.assign(backend, typeof sandbox.exec === 'function' ? sandboxFileOperations(backend) : {});
 }

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"}

package/dist/command-plan.js

@@ -0,0 +1,116 @@
+/** Logical commands and ordered log boundaries for launchers that execute opaque wrappers. */
+import { randomUUID } from 'node:crypto';
+import { gunzipSync, gzipSync } from 'node:zlib';
+const HEADER = '# mol-command-plan-v1 ';
+const TRUNCATED = '__MOL_COMMAND_LOG_TRUNCATED__';
+/**
+ * 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 function createCommandPlan(steps) {
+    const id = randomUUID();
+    return {
+        id,
+        steps: steps.map((step, index) => ({
+            ...step,
+            startMarker: `__MOL_COMMAND_STEP_${id}_${index}_START__`,
+            endMarker: `__MOL_COMMAND_STEP_${id}_${index}_END__`,
+        })),
+    };
+}
+/**
+ * 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 function commandWithPlan(command, plan) {
+    return `${HEADER}${gzipSync(JSON.stringify(plan)).toString('base64')}\n${command}`;
+}
+/**
+ * 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 function commandPlan(command) {
+    const header = command.split('\n').find((line) => line.startsWith(HEADER));
+    if (!header || header.length > 1024 * 1024)
+        return null;
+    try {
+        const plan = JSON.parse(gunzipSync(Buffer.from(header.slice(HEADER.length), 'base64'), {
+            maxOutputLength: 1024 * 1024,
+        }).toString('utf8'));
+        if (!plan ||
+            !/^[a-f0-9-]{36}$/.test(plan.id) ||
+            !Array.isArray(plan.steps) ||
+            plan.steps.length === 0 ||
+            !plan.steps.every((step, index) => typeof step?.id === 'string' &&
+                typeof step.command === 'string' &&
+                step.startMarker === `__MOL_COMMAND_STEP_${plan.id}_${index}_START__` &&
+                step.endMarker === `__MOL_COMMAND_STEP_${plan.id}_${index}_END__`))
+            return null;
+        return plan;
+    }
+    catch (_error) {
+        // Metadata is advisory. An absent or malformed descriptor supplies no logical commands.
+        return 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 function logicalCommandText(command) {
+    return (commandPlan(command)
+        ?.steps.map((step) => step.command)
+        .join(';\n') ?? command);
+}
+/**
+ * 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 function commandStepView(command, output) {
+    const plan = commandPlan(command);
+    if (!plan)
+        return { command, output, complete: true };
+    let at = -1;
+    let selected;
+    let offset = 0;
+    for (const line of output.split('\n')) {
+        for (const step of plan.steps) {
+            if (line === step.startMarker || line === step.endMarker) {
+                at = offset + line.length + 1;
+                selected = line === step.startMarker ? step : undefined;
+            }
+        }
+        offset += line.length + 1;
+    }
+    const text = selected && at >= 0 ? output.slice(at) : '';
+    return {
+        stepKey: selected?.startMarker,
+        command: selected?.command ?? '',
+        output: text.replace(`${TRUNCATED}\n`, ''),
+        complete: !text.startsWith(TRUNCATED),
+    };
+}
+/**
+ * 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 function commandPlanLogRead(plan, limit) {
+    const markers = plan.steps.flatMap((step) => [step.startMarker, step.endMarker]);
+    return (`BEGIN { ${markers.map((marker) => `marks["${marker}"]=1`).join('; ')} }\n` +
+        '$0 in marks { marker=$0; text=""; cut=0; next }\n' +
+        `{ text=text $0 "\\n"; if(length(text)>${limit}) { text=substr(text,length(text)-${limit}+1); cut=1 } }\n` +
+        `END { if(marker!="") { print marker; if(cut) print "${TRUNCATED}"; printf "%s",text } }`);
+}

package/dist/index.d.ts

@@ -12,6 +12,12 @@
  * (identity, tool listing, project docs, discovered skills).
  *
  * @remarks
+ * - **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
@@ -81,6 +87,11 @@
  *   to the model, and execute `catalog.loader` like any other tool. Loading only
  *   exposes schemas, never grants permission or runs a tool. Persist its loaded
  *   names with `onLoad` to keep them available across turns and compaction.
+ * - **Sandbox writes batch transport work.** The optional backend operations
+ *   `readFileForUpdate` and `writeFileAndCheck` combine path safety with the old-text
+ *   read, then the write with its parse check. Diff tracking and redaction checks
+ *   stay in the tools. Format and change hooks retain their ordering before parsing;
+ *   large files and backends without these operations use the native file APIs.
  * - **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
@@ -144,6 +155,7 @@ export * from './backends/local.js';
 export * from './backends/sandbox.js';
 export * from './browser-guard.js';
 export * from './browser-probe.js';
+export * from './command-plan.js';
 export * from './command-position.js';
 export * from './cut-run.js';
 export * from './failure-kind.js';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6IG;AAEH,cAAc,qBAAqB,CAAA;AACnC,cAAc,uBAAuB,CAAA;AACrC,cAAc,oBAAoB,CAAA;AAClC,cAAc,oBAAoB,CAAA;AAClC,cAAc,uBAAuB,CAAA;AACrC,cAAc,cAAc,CAAA;AAC5B,cAAc,mBAAmB,CAAA;AACjC,cAAc,oBAAoB,CAAA;AAClC,cAAc,uBAAuB,CAAA;AACrC,cAAc,gBAAgB,CAAA;AAC9B,cAAc,kBAAkB,CAAA;AAChC,cAAc,oBAAoB,CAAA;AAClC,cAAc,yBAAyB,CAAA;AACvC,cAAc,wBAAwB,CAAA;AACtC,cAAc,cAAc,CAAA;AAC5B,cAAc,qBAAqB,CAAA;AACnC,cAAc,iBAAiB,CAAA;AAC/B,cAAc,oBAAoB,CAAA;AAClC,cAAc,oBAAoB,CAAA;AAClC,cAAc,mBAAmB,CAAA;AACjC,cAAc,YAAY,CAAA;AAC1B,cAAc,sBAAsB,CAAA;AACpC,cAAc,YAAY,CAAA;AAC1B,cAAc,gBAAgB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwJG;AAEH,cAAc,qBAAqB,CAAA;AACnC,cAAc,uBAAuB,CAAA;AACrC,cAAc,oBAAoB,CAAA;AAClC,cAAc,oBAAoB,CAAA;AAClC,cAAc,mBAAmB,CAAA;AACjC,cAAc,uBAAuB,CAAA;AACrC,cAAc,cAAc,CAAA;AAC5B,cAAc,mBAAmB,CAAA;AACjC,cAAc,oBAAoB,CAAA;AAClC,cAAc,uBAAuB,CAAA;AACrC,cAAc,gBAAgB,CAAA;AAC9B,cAAc,kBAAkB,CAAA;AAChC,cAAc,oBAAoB,CAAA;AAClC,cAAc,yBAAyB,CAAA;AACvC,cAAc,wBAAwB,CAAA;AACtC,cAAc,cAAc,CAAA;AAC5B,cAAc,qBAAqB,CAAA;AACnC,cAAc,iBAAiB,CAAA;AAC/B,cAAc,oBAAoB,CAAA;AAClC,cAAc,oBAAoB,CAAA;AAClC,cAAc,mBAAmB,CAAA;AACjC,cAAc,YAAY,CAAA;AAC1B,cAAc,sBAAsB,CAAA;AACpC,cAAc,YAAY,CAAA;AAC1B,cAAc,gBAAgB,CAAA"}