import type { AgentFolder, SandboxBackend } from './folder.js'; import type { TerminalIntegrations } from './terminal-integrations.js'; export interface LaunchSpec { readonly folder: AgentFolder; readonly stateDir: string; /** * Where the generated providers extension is written (see * `folder.providersJson`) and where `--session-dir` points, sourced from the * plan's own `extensionsDir`/`sessionsDir` (`commands/run.ts` — the single * derivation site; re-deriving from `stateDir` here risks silently * disagreeing with a plan whose dirs were overridden after `planRun`). */ readonly extensionsDir: string; readonly sessionsDir: string; /** * Where sandboxed runs point `MISE_CACHE_DIR` (see `composeEnv`), sourced * from the plan's `statePaths` derivation like `extensionsDir`/`sessionsDir`. */ readonly miseCacheDir: string; /** * Which sandbox backend wraps this run, or `null` for unsandboxed. `'nono'` * wraps the argv here — see `composeArgv`. `'sbx'` does NOT wrap here: its * `sbx exec` wrapper is composed at materialization in `commands/run.ts`, * so `composeArgv` returns the bare pi argv for both `'sbx'` and `null`. * For `'sbx'`, `piBin` is the literal `pi` — resolved on the guest's PATH, * since host paths (mise-shim included) are meaningless inside the * microVM. */ readonly backend: SandboxBackend | null; readonly passthrough: readonly string[]; /** Resolved path, or bare `nono` for dry-run previews. */ readonly nonoBin: string; /** * Resolved path (mise-shim fallback included, see `util/which.ts`), or bare * `pi` for dry-run previews. Used consistently whether or not the run is * nono-sandboxed — the generated profile already grants read on the mise * install tree (see `nono/cradle-pi.json`), so the absolute path resolves * inside the sandbox too; a bare `pi` only resolves on whatever PATH the * spawning process happens to have, which is exactly the gap a fresh * mise-only install falls into. See `backend` for the `'sbx'` exception. */ readonly piBin: string; /** Abs path of the generated per-agent nono profile; used only when `backend` is `'nono'`. */ readonly profilePath: string; /** * When true, nono runs without `--silent` so its capabilities banner * (effective grants + network disclosure) prints; default is silent — the * generated profile file and `--verbose` are the audit surfaces. */ readonly verbose?: boolean; /** * Abs paths of the pi extension entry files resolved from settings.json's * `packages` (see `./packages.js`), installed into `/npm` by * `commands/run.ts`. Absent/empty on the argv-only preview used for * `--dry-run` (packages resolve at install time, after the preview is * printed) and on folders that declare no packages. */ readonly packageEntries?: readonly string[]; /** Installed host terminal hooks and foreground detection hints discovered for this run. */ readonly terminalIntegrations?: TerminalIntegrations; } /** * Build the bare pi argv. `passthrough` lands last so user-passed flags win * under pi's last-wins parsing. The `-e` order is load-bearing: the generated * providers extension goes first, followed by the nono-only agent-browser * host-socket fallback, installed host terminal hooks, resolved package entries, * then the agent's own * `extensions/` files — which load with the agent's providers registered, * nono subprocess compatibility configured, and any package-provided tools * already available, since the agent's own extensions may depend on them. */ export declare function composePiArgv(spec: LaunchSpec): string[]; /** * Compose host environment overrides: private MISE_CACHE_DIR for nono, plus * HERDR_AGENT=pi when running inside a Herdr pane on any backend. * * The generated profile denies the shared `~/Library/Caches/mise` on purpose * — a poisoned `bin_paths` cache would redirect which binaries the user's * later UNSANDBOXED mise execs resolve to, invisibly and machine-globally. * Without this override, every sandboxed `mise exec` spams `mise WARN failed * to write cache file` because it can't write there. Pointing `MISE_CACHE_DIR` * at a private cache inside the already-granted state dir instead lets mise * cache writes succeed (no warnings, working cache) while the shared host * cache stays untouched; mise creates the directory itself, cradle never * pre-creates or wipes it. Unsandboxed runs produce `{}` and keep the shared * host mise cache — no override needed since there's no sandbox denial to work * around; the sbx guest has no mise at all, and its HOME override rides the * `sbx exec` argv composed in `commands/run.ts` rather than env, so the * Pi configuration still stays on argv there too. * * This deliberately overrides any user-set `MISE_CACHE_DIR` for sandboxed * runs — the profile wouldn't grant a custom location either, so honoring one * would just trade the warning spam for a silent cache-write failure. It is * one of cradle's host-only exceptions to argv-only composition (see the module * header and `ARCHITECTURE.md`'s "Why argv" section): this configures mise, * not pi, so it doesn't touch the argv-survives-sandboxing rationale that * motivates keeping pi's own configuration on argv. The failure mode if this * env var were ever stripped is benign — mise falls back to the shared cache * and the warnings return, nothing breaks. */ export declare function composeEnv(spec: LaunchSpec): Record; /** * Build the argv for `nono run … -- pi …` when `spec.backend` is `'nono'`, or * the bare pi argv otherwise (`'sbx'` or `null`) — the `'sbx'` backend's own * `sbx exec` wrapper is composed later, at materialization in * `commands/run.ts`, not here (see `LaunchSpec.backend`). * * All filesystem grants (cwd, agent dir, state dir, and the agent's own * `sandbox/nono.json` entries) AND the network posture live inside the * generated per-agent profile at `spec.profilePath` — see `nono/profiles.ts`. * The wrapper is `nono run --silent --profile ` by default (silent mode * suppresses nono's startup banner); `--verbose` omits `--silent` to show the * capabilities banner, and cradle prints `🔒 Sandbox Active` on silent runs. * No per-flag network posture — it all lives in the profile. * * Both `spec.nonoBin` and `spec.piBin` are resolved paths (mise-shim fallback * included), never bare names: cradle spawns `nonoBin` directly, and a * freshly mise-installed nono may not be on PATH yet; `piBin` is passed * through to nono as plain argv (`-- …`), and nono execs it *inside* * the sandbox, where the resolved absolute path resolves fine against the * mise install tree the base profile already grants read on (see * `nono/cradle-pi.json`) — no PATH lookup needed either side of the sandbox * boundary. nono guarantees child processes inherit the sandbox, so pi * spawning its own subprocesses is covered too. */ export declare function composeArgv(spec: LaunchSpec): string[];