Harness: support provider-native process/filesystem semantics and preinstalled adapter payloads

[drepkovsky]

Harness: support provider-native process/filesystem semantics and preinstalled adapter payloads

Description

Harness currently assumes that a sandbox session has POSIX shell and path semantics during bootstrap and adapter startup. Core and adapter code uses command strings such as pwd and mkdir -p, composes guest paths with path.posix, and installs adapter bridge dependencies through package-manager commands.

That default is reasonable for existing POSIX sandboxes, but it prevents two broader Harness use cases:

1. Native non-POSIX sandbox providers. A provider backed by the native Windows filesystem and child_process.spawn() cannot faithfully implement POSIX commands or accept POSIX-composed guest paths.
2. Preinstalled adapter payloads. A signed desktop runtime, offline worker, or prebuilt managed image may already contain an exact adapter bridge and its dependencies, but adapters cannot currently select that payload and skip package-manager bootstrap/network access.

This is not specific to one provider adapter. Both the published Codex and Claude Code Harness adapters currently use an adapter-owned bridge bootstrap, package installation, shell command strings, and POSIX directory setup. Codex and Claude are useful reproductions, not the desired abstraction boundary.

Relevant published areas include:

• @ai-sdk/harness sandbox bootstrap, work-directory discovery, skill installation, bridge readiness and replay paths;
• @ai-sdk/provider-utils experimental sandbox session process/filesystem contract;
• @ai-sdk/harness-codex and @ai-sdk/harness-claude-code bridge bootstrap and startup.

Desired outcome

A Harness sandbox provider should be able to own its guest process, filesystem, home-directory and path semantics without emulating a POSIX shell. An adapter should be able to use an immutable, consumer-supplied preinstalled payload and omit package installation when that mode is selected.

The exact public API is intentionally left open for maintainer design. A solution should provide these capabilities without requiring one particular method shape:

• direct executable-plus-argv launch, preserving paths and arguments containing spaces;
• provider-owned guest path composition, home discovery and recursive directory creation;
• an immutable adapter payload identity distinct from machine-specific installation paths;
• an opt-in preinstalled mode that performs no package-manager install or bootstrap network request;
• unchanged default behavior for existing adapters and sandbox providers.

The preinstalled identity may participate in cache and lifecycle decisions, but host credentials, arbitrary executable locations and local profile paths should not become portable Harness state.

Reproduction

Implement a Harness network sandbox provider over the native Windows filesystem and child_process.spawn() without Git Bash or WSL, then create either a Codex or Claude Code Harness session.

Bootstrap and startup encounter a combination of POSIX-only commands/path composition and adapter-owned package installation before a turn can run. Wrapping the outer worker in Electron, Tauri or a packaged Node process does not change those nested assumptions.

Suggested acceptance coverage

• a native Windows provider with paths containing spaces and no POSIX shell;
• a POSIX provider retaining the existing default bootstrap behavior;
• preinstalled adapter startup with no ambient package manager and no bootstrap network access;
• skills/tool setup, bridge readiness and replay using provider-owned paths;
• create, turn, detach, stop, resume/replay and destroy lifecycle coverage;
• relocation of the same immutable payload does not change its content identity;
• public documentation for any new experimental sandbox or adapter capability.

Codex and Claude Code are appropriate initial consumer proofs. The reusable capability should live at the narrowest boundary justified by the repository's compatibility and abstraction rules rather than introducing Codex-specific sandbox primitives.

Versions inspected

• @ai-sdk/harness: 1.0.64
• @ai-sdk/harness-codex: 1.0.66
• @ai-sdk/harness-claude-code: current source on 2026-08-08

Code of Conduct

I agree to follow this project's Code of Conduct.

[ai-sdk-factory]

Identify issue type

Identified as Feature
Confidence: High

Rationale

This is an API and platform-support enhancement for preinstalled runtimes and native Windows sandbox sessions. It proposes new capabilities rather than identifying a failure of explicitly promised existing behavior.

Evidence

• Requests new SandboxSession capabilities for argv-based spawning, recursive directory creation, and provider-owned path resolution.
• Proposes a new preinstalledBridge option to bypass pnpm installation and bootstrap network access.
• The requested shell-free native Windows and packaged-sidecar workflow is presented as a new backward-compatible extension, not a documented behavior regression.

[ai-sdk-factory]

Feature Analysis

Feature is not available.

Feature Description

• Enable consumers to run an immutable, prepackaged Codex bridge and target-specific runtime on macOS or native Windows without bootstrap package installation, bootstrap network access, a POSIX shell, or reliance on ambient PATH, while preserving detach, stop, resume, replay, and destroy behavior.
• CodexHarnessSettings has no preinstalled-bridge option; createCodex() always returns a bootstrap recipe containing package.json, pnpm-lock.yaml, bridge.mjs, and the command pnpm install --frozen-lockfile --store-dir .pnpm-store.
• Codex startup composes paths with path.posix, creates directories through mkdir -p, and launches the bridge as a quoted node ... command string rather than a configured executable and argv array.
• Experimental_SandboxSession accepts only command: string for run and spawn and exposes neither recursive directory creation nor path composition; Harness bootstrap also executes pwd and mkdir -p, validates POSIX paths, and rejects backslashes.
• Focused Harness and Codex tests pass while explicitly asserting the current pnpm, pwd, mkdir, POSIX-path, and string-command behavior; the retained issue-18609 type probe confirms that all four proposed API capabilities are absent.
• This should remain one feature: preinstallation, provider-owned paths, shell-free filesystem setup, and argv launch are acceptance dimensions of the same self-contained sidecar workflow, and implementing any one alone would not satisfy the requested macOS-and-Windows contract.

AI SDK Fit

• The capability fits the Harness architecture because adapters already own bootstrap recipes, deterministic identities, bridge startup, and lifecycle replay, while sandbox providers own execution and filesystem behavior.
• Cross-platform path and process semantics belong in the experimental sandbox and Harness sandbox contracts rather than in Codex-specific shell quoting, preserving the provider adapter boundary and enabling third-party sandbox implementations.
• A preinstalled Codex configuration is consistent with existing reusable-template and bootstrap-identity concepts, provided its immutable payload identity participates in cache invalidation without placing executable paths or credentials in persisted Harness lifecycle state.
• The existing command-string path must remain supported for compatibility; experimental additive capabilities or explicit capability negotiation would allow shell-free providers without forcing unrelated tools to abandon shell commands.

Implications / Considerations

• The change is cross-cutting across @ai-sdk/provider-utils, the ai package re-export and reference documentation, @ai-sdk/harness bootstrap/path logic, @ai-sdk/harness-codex, sandbox provider implementations, tests, examples, and Harness documentation; it is not a model-provider change.
• Experimental_SandboxSession would need an additive executable-plus-argv process form and a recursive directory primitive, while HarnessV1NetworkSandboxSession or an equivalent provider-owned abstraction would need path joining and absolute-path validation using the guest platform's dialect.
• Harness bootstrap recipes and identity planning need a representation for immutable preinstalled artifacts that contributes to cache identity but performs no file writes or installation commands; prepareSandboxForHarness and reusable-template paths must understand the same representation.
• createCodex() needs a preinstalled bridge setting containing a stable identity, guest Node executable, and bridge entrypoint, with startup selecting this path while preserving the existing adapter-managed pnpm bootstrap by default.
• Codex startup, skill setup, marker creation, work-directory setup, and bridge-state paths must stop using path.posix and shell mkdir commands when the provider exposes native operations, and bridge launch must pass every dynamic value as a separate argument.
• The Vercel sandbox implementation can map executable and argv directly to its existing cmd/args API, but just-bash and third-party providers may require optional capability detection or an explicit unsupported-capability error because they may not execute arbitrary native binaries.
• No @ai-sdk/provider model specification or Codex bridge wire-protocol change appears necessary; the affected specifications are the experimental sandbox contract, HarnessV1 sandbox/bootstrap contracts, and their lifecycle/cache semantics.
• Because Experimental_SandboxSession is publicly re-exported from ai, adding required members could break custom structural implementations; optional capabilities, overloads, a new extended interface, or a versioned Harness sandbox contract should be considered.
• AI SDK UI messages, framework integrations, and rendering behavior should not change because this feature affects sandbox acquisition and bridge startup rather than the normalized Harness event stream.
• Regression coverage should include native Windows and macOS providers, minimal or absent PATH, paths containing spaces, no pnpm or bootstrap network activity, immutable-identity cache invalidation, create/detach/stop/resume/replay/destroy, cancellation, and unchanged default bootstrap behavior.
• Examples and documentation should show a signed desktop-sidecar provider and preinstalled Codex payload, clearly distinguish bootstrap-network independence from the model's required API traffic, and document provider capability requirements.
• Executable and entrypoint paths must be treated as trusted application configuration, validated against the provider-owned filesystem where practical, passed without shell interpolation, and excluded from portable lifecycle state along with all authentication material.
• Material uncertainties include how packaged applications expose immutable guest paths across resume, whether a provider can guarantee the same runtime payload for a stored identity, and whether 'shell-free' covers only Harness bootstrap/launch or also shells that Codex intentionally invokes as agent tools.

Relevant Documentation

• Codex
• HarnessAgent
• Harness Adapters
• Experimental_SandboxSession
• Codex SDK
• Codex TypeScript SDK Process Launcher
• Node.js Child Process
• Node.js Path