import { type SandboxBackend } from '../agent/folder.js'; import { type LaunchSpec } from '../agent/launch.js'; import { type NpmPackageSpec } from '../agent/packages.js'; import { type SbxSpec } from '../sbx/compose.js'; import { type TreeFile } from '../setup/install.js'; import { type WhichFn } from '../util/which.js'; export interface RunFlags { readonly dir: string; /** `--offline` → full network block. Overrides the folder network posture and forces the sandbox on (unless --no-sandbox). */ readonly offline?: boolean; /** `--allow-host` (repeatable) → network host allowlist. Overrides the folder allowlist and forces the sandbox on (unless --no-sandbox). */ readonly allowHost?: readonly string[]; /** Explicit CLI choice: `--no-sandbox` → true, `--sandbox` → false. Absent = defer to the folder. */ readonly noSandbox?: boolean; /** `--sandbox-backend` → explicit backend choice; implies the sandbox is on (still beaten by `--no-sandbox`). */ readonly sandboxBackend?: SandboxBackend; readonly dryRun?: boolean; readonly passthrough?: readonly string[]; /** `--verbose` → show nono's full sandbox capabilities banner instead of the one-line status. */ readonly verbose?: boolean; /** * A `schedule/.md` slug to run headless instead of starting an * interactive session. The named schedule's `cwd` replaces the run's * effective working directory (see `RunPlan.cwd`), and its body is appended * to the launch passthrough as `--print --name --no-approve -- * `, after any user `--` passthrough so it always terminates the * argv. Set only by `cradle schedule run` — and therefore by the OS timers, * whose composed argv is exactly that command (see `schedule/launchd.ts` * and `schedule/systemd.ts`). There is deliberately no `--schedule` flag on * `cradle run`: two spellings of one action is one too many. */ readonly schedule?: string; } interface RunDeps { readonly cwd?: string; readonly home?: string; readonly which?: WhichFn; /** Whether stdout is a TTY (`cli.ts` passes `process.stdout.isTTY`) — rides the sbx exec argv as `-t`; default false. */ readonly tty?: boolean; /** Host terminal discovery environment; defaults to the inherited process environment. */ readonly env?: Readonly>; readonly platform?: NodeJS.Platform; } /** * The agent's settings.json `packages` resolved into a per-agent npm install * plan. `npmDir` is a private npm project under the agent's state dir — never * the folder itself, so the install stays out of the portable, committable * agent folder. */ export interface PackagesPlan { readonly npmDir: string; /** `emitPackagesManifest` output — the package.json cradle writes into `npmDir`. */ readonly manifest: string; readonly specs: readonly NpmPackageSpec[]; /** * `[...(settings.npmCommand ?? ['npm']), 'install', '--ignore-scripts']`. * This install runs on the host, unsandboxed, before the sandbox spawns — * `--ignore-scripts` stops a folder-declared package's postinstall from * running arbitrary host code (`npmCommand` is validated upstream to a * single-element allowlist of `npm`/`pnpm`/`yarn`/`bun`, all of which accept * this flag). */ readonly installCommand: readonly string[]; } /** * The sbx backend's materialization plan: the setup argvs `materializeRun` * runs before the final `sbx exec` (composed there, wrapping the pi argv). * `spec.piVersion` is null at plan time — the provision argv is recomposed at * materialize with the host pi version (see `MaterializeDeps.readPiVersion`) * so the guest install pins to it; the plan-time argv is the unpinned preview * dry-run prints, the same precedent as package `-e` entries, which also * resolve at materialize. */ export interface SbxRunPlan { readonly spec: SbxSpec; /** Resolved host pi path — the version-pin source for guest provisioning; never spawned in-guest. */ readonly hostPiBin: string; readonly createArgv: readonly string[]; readonly policyArgvs: ReadonlyArray; readonly provisionArgv: readonly string[]; } export interface RunPlan { /** Generated extensions, relative to `extensionsDir`. */ readonly files: readonly TreeFile[]; /** * Authoritative — the single derivation site for where generated extensions * and sessions live. `materializeRun` re-asserts these onto `launch` * before composing the final argv, so overriding either here (as tests do) * changes the composed argv accordingly instead of silently disagreeing * with whatever `launch` had baked in at `planRun` time. */ readonly extensionsDir: string; readonly sessionsDir: string; readonly warnings: readonly string[]; /** The generated per-agent nono profile to write before spawning; `null` unless the resolved backend is `'nono'`. */ readonly profile: { readonly path: string; readonly content: string; } | null; /** The sbx setup plan (see `SbxRunPlan`); `null` unless the resolved backend is `'sbx'`. */ readonly sbx: SbxRunPlan | null; /** Settings.json `packages` resolved into an install plan; `null` when the folder declares none. */ readonly packages: PackagesPlan | null; /** The single argv source: `composeArgv(plan.launch)` — package-entry-free until `materializeRun` recomposes it with resolved package entries. */ readonly launch: LaunchSpec; /** * The effective working directory: the terminal cwd, a named alias's cwd, * or `flags.schedule`'s `Schedule.cwd` (highest precedence). Callers spawn here — `cli.ts` * passes it to `runForeground` — since a scheduled run's launchd/systemd * invocation carries no shell `cd` of its own. */ readonly cwd: string; readonly dryRun: boolean; } /** * Resolve the ref (bare alias name or path — see `../agent/aliases.js`), load * the agent folder, and compose the launch. Returns a plan; the caller * decides whether to print it (`--dry-run`) or materialize + spawn it. * * `--dry-run` only previews, so it deliberately skips the bin checks — you can * compose a command before nono/sbx/pi are installed. */ export declare function planRun(flags: RunFlags, deps?: RunDeps): Promise; export interface SbxRunResult { readonly exitCode: number; readonly stderr: string; } export interface MaterializeDeps { /** Runs a package install (e.g. `npm install`) in `cwd`; `cli.ts` always passes `runInstall` from `util/proc.js`. */ readonly install?: (command: readonly string[], cwd: string) => Promise; /** Runs one sbx setup command (create/policy/provision), capturing stderr; `cli.ts` passes `runCapture` from `util/proc.js`. */ readonly run?: (argv: readonly string[]) => Promise; /** Reads the host pi version (`cli.ts` passes its `--version` reader) to pin the guest install; absent → unpinned provisioning. */ readonly readPiVersion?: (piBin: string) => Promise; } /** * Write the generated extensions (replacing stale ones), ensure the sessions * dir, and — per backend — (re)write the generated per-agent nono profile * that `nono run --profile` points at, or run the sbx setup sequence * (create/policy/provision) and wrap the final argv in `sbx exec`. When the * folder declares `packages`, also (re)install the per-agent npm project and * resolve each package's pi extension entries, returning the final argv with * those entries appended as `-e` flags plus any resolution warnings; * otherwise the plan's argv is already final. */ export declare function materializeRun(plan: RunPlan, deps?: MaterializeDeps): Promise<{ argv: string[]; warnings: string[]; }>; export {};