import { type NpmPackageSpec } from './packages.js'; export type ThinkingLevel = 'off' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh' | 'max'; export interface AgentSettings { readonly defaultProvider?: string; readonly defaultModel?: string; readonly defaultThinkingLevel?: ThinkingLevel; /** Parsed `npm:` package sources from settings.json's `packages` key — see `./packages.js`. */ readonly packages?: readonly NpmPackageSpec[]; /** * Installer argv from settings.json's `npmCommand`; `["npm"]` when absent. * Always exactly one of `npm`/`pnpm`/`yarn`/`bun` — see `readNpmCommand`. */ readonly npmCommand?: readonly string[]; } export interface AgentSandboxGrants { readonly read: readonly string[]; readonly write: readonly string[]; readonly allow: readonly string[]; /** Individual Unix socket paths the process may connect to, without bind access. */ readonly unixSocket: readonly string[]; /** Direct-child Unix socket paths the process may connect to and bind. */ readonly unixSocketDirBind: readonly string[]; } /** * The agent's declared network posture — a curated subset of nono's profile * `network` block, using nono's CANONICAL key names (not the `proxy_allow` / * `port_allow` legacy aliases). Folded verbatim into the generated per-agent * profile by `nono/profiles.ts`, where nono is the enforcement authority: * `allow_domain` presence flips nono to default-deny proxy filtering, and nono * fails closed (refuses to run) on an unenforceable platform or a bad key — * cradle never has to synthesize a fallback. Absent entirely ⇒ nono default * (open network), preserving the old `net: "allow"` behavior. */ export interface AgentNetwork { /** Deny all outbound (replaces the old `net: "block"`). */ readonly block?: boolean; /** Named nono network-policy profile (host `network-policy.json`); opaque pass-through. */ readonly networkProfile?: string; /** Outbound host allowlist — hostnames/IPs. Presence ⇒ nono default-denies unlisted hosts. */ readonly allowDomain?: readonly string[]; /** localhost TCP ports the child may connect+bind (local IPC / dev servers). */ readonly openPort?: readonly number[]; /** TCP ports the child may listen on. */ readonly listenPort?: readonly number[]; } export type AgentSandboxPosture = 'unconfigured' | 'enabled' | 'disabled'; /** * The sandbox enforcement backend a folder can declare a posture for: `nono` * (Seatbelt/bubblewrap, `sandbox/nono.json`) or `sbx` (Docker Sandboxes * microVM, `sandbox/sbx.json`). Backend resolution — which one actually runs * — is a `commands/run.ts` concern; this module only reads each file's * declared posture. */ export type SandboxBackend = 'nono' | 'sbx'; export interface AgentSandbox { /** * The declaring file's sandbox posture. `'unconfigured'` when the folder * has no `sandbox/nono.json` (for the `sandbox` field) or no * `sandbox/sbx.json` (for the `sbx` field); otherwise mirrors the file's * `sandbox` key (absent ⇒ `'enabled'`). */ readonly posture: AgentSandboxPosture; readonly network?: AgentNetwork; readonly filesystem: AgentSandboxGrants; /** * Raw macOS Seatbelt s-expression rules from `sandbox/nono.json`'s * `unsafe_macos_seatbelt_rules`, merged verbatim after the base profile's * rules (see nono/profiles.ts). The escape hatch a browser agent uses to let * Chrome register its crashpad Mach service and open IOKit — capabilities the * default profile denies. Named "unsafe" because each rule widens the OS * sandbox; nono's startup banner does not list seatbelt rules, so review a * folder's `sandbox/nono.json` or the generated profile to audit them. */ readonly unsafeMacosSeatbeltRules: readonly string[]; } export interface AgentFolder { readonly dir: string; /** * Abs path of SYSTEM.md — REPLACES pi's default system prompt via * `--system-prompt`; `null` when the folder has no SYSTEM.md. `loadAgentFolder` * guarantees at least one of `systemFilePath`/`appendSystemFilePath` is non-null. */ readonly systemFilePath: string | null; /** Abs path of APPEND_SYSTEM.md — appended to pi's system prompt via `--append-system-prompt`; `null` when absent. */ readonly appendSystemFilePath: string | null; readonly settings: AgentSettings; /** Serialized `providers` object from models.json, `null` when absent. */ readonly providersJson: string | null; readonly skillsDir: string | null; /** `schedule/` dir, `null` when absent. Parsing is lazy — see `./schedules.js`'s `loadSchedules`. */ readonly scheduleDir: string | null; /** pi-native extensions (top-level `extensions/*.ts` plus each subdir's `index.ts`), absolute paths. */ readonly extensionFiles: readonly string[]; /** `sandbox/nono.json`'s declared posture — the Seatbelt/bubblewrap backend. */ readonly sandbox: AgentSandbox; /** * `sandbox/sbx.json`'s declared posture — the Docker Sandboxes microVM * backend. A restricted subset of nono's schema: no Unix-socket grants, no * named network-profile pass-through, no Seatbelt escape hatch — the VM * boundary has no equivalent for them, so those keys are warned-and-dropped * rather than silently accepted. See `readSbxSandbox`. */ readonly sbx: AgentSandbox; readonly warnings: readonly string[]; } export declare function loadAgentFolder(dir: string): Promise;