toolroll 0.9.104 → 0.9.105

package/dist/agent-fence.d.ts

@@ -1,479 +0,0 @@
-import type { LoopbackMode } from "./egress.js";
-import type { ExecutionProfile } from "./scope.js";
-import { type SrtTerms } from "./sandbox-runtime.js";
-import { type ProtectedStorage } from "./protected-storage.js";
-/** How a launch was fenced, as recorded on the run and said on the task. */
-export type FenceMethod = "codex-profile" | "macos-sandbox" | "linux-bubblewrap" | "claude-rules" | "none";
-/** Only the plane's recorded repository may supply an own-Git exemption. */
-export type WorktreeBinding = {
-    main: string;
-    gitdir: string;
-};
-export declare class CheckoutBindingError extends Error {
-}
-export declare const HARDENED_GIT_ARGS: readonly ["--no-optional-locks", "-c", "core.fsmonitor=false", "-c", "core.hooksPath=/dev/null"];
-export declare function checkoutGitEnv(base?: Readonly<NodeJS.ProcessEnv>): Record<string, string>;
-export declare function trustedWorktreeBinding(repository: string, worktree: string, poolRoots?: readonly (string | null)[]): WorktreeBinding;
-/**
- * Every path an agent must not reach: the Toolroll state folder
- * beside the database (all of it, except the folder that holds this run's
- * own worktree), the database itself with its journal files, and
- * `~/.toolroll` or an older `~/.standing-orders` (provider keys and project tool secrets). When the
- * database sits anywhere else (a shared folder), only the database and
- * secret-looking entries there are fenced.
- */
-export declare function agentFence(options: {
-    databaseFile: string | null;
-    worktree: string | null;
-    home?: string;
-    extra?: readonly string[];
-    boundary?: TaskBoundary | null;
-    binding?: WorktreeBinding | null;
-    runFolders?: RunFolders;
-    /** Protected storage as this launch resolved it (protected-storage.ts); resolved here when not given. */
-    protectedStorage?: readonly string[];
-}): string[];
-/** The task's boundary: `shell` joins the OS fence; `fileTools` only Claude's file-tool deny rules; `readOnly` and
- * `lookup` are other tasks' git metadata and checkout roots (see FenceGrants). */
-export type TaskBoundary = {
-    protectedShell?: string[];
-    shell: string[];
-    fileTools: string[];
-    readOnly: string[];
-    lookup: string[];
-    /** Every home configuration name the launch may not reach, by name, whether or not it exists now (macOS: Seatbelt
-     * denies a path that isn't there yet, so a build can't create it, or later replace it with a link). */
-    homeNames?: string[];
-};
-/**
- * Everything outside a task's own folders that a build could otherwise
- * reach: the home configuration above, the other repositories beside its
- * project (and other tasks' worktrees beside its own), and the project's
- * primary checkout — all but its `.git`, which the worktree's git needs.
- * The task's worktree, the files Toolroll makes for the run (in the
- * system temp folder) and everything else stay as they are.
- */
-export declare function taskBoundary(options: {
-    worktree: string;
-    provider: string;
-    home?: string;
-    binding?: WorktreeBinding | null;
-    policy?: FencePolicy;
-    storage?: ProtectedStorage;
-}): TaskBoundary;
-/** Where launches keep their private folders: `root` (the system temp folder) and, on a Mac, `also` the short shared one
- * a check's launch folder is made in (/private/tmp, so its unix sockets fit); `own` is this launch's. */
-export type RunFolders = {
-    root: string;
-    own: string | null;
-    also?: string[];
-};
-/** The prefixes of every launch's private folders: its tools' config and a Codex build's own home (and a check's). */
-export declare const RUN_FOLDER_PREFIXES: readonly ["so-tools-", "so-codex-", "so-net-", "so-cmd-"];
-export declare function runFolders(own: string | null, root?: string): RunFolders;
-/** Where a check's launch folder is made on a Mac: a short shared folder, so its TMPDIR leaves room for a unix socket
- * path (about 104 bytes). */
-export declare const CHECK_LAUNCH_ROOT_MACOS = "/private/tmp";
-/** The folder a check's launch folder is made in: on a Mac the short one, elsewhere the system temp folder. */
-export declare const checkLaunchRoot: () => string;
-/** Every root launch folders are made under (the system temp folder, and on a Mac the short shared one). */
-export declare const runRoots: (folders: RunFolders) => string[];
-/**
- * What a fence gives back beside its denied paths. `readOnly` is read, never written (other tasks' git metadata, the
- * primary checkout under v2); `readable` is read inside a denied folder (the shared dependencies this checkout links);
- * `lookup` is kept for Codex (looked up, never listed); `runFolders` names this launch's own private folder and where
- * the others are; `pool` denies the plane's checkout pools around this build's own checkout (CheckoutPool).
- */
-export type FenceGrants = {
-    readOnly: string[];
-    readable: string[];
-    lookup: string[];
-    runFolders?: RunFolders;
-    pool?: CheckoutPool;
-    network?: NetworkFence;
-    writes?: WriteAllowlist;
-    /** Which `readable` entries are one exact file: read with no listing of its folder, so a sibling stays denied. */
-    exactFiles?: string[];
-    /** Policy v1: the home configuration names denied by name, present or not (TaskBoundary.homeNames). */
-    homeNames?: string[];
-    /** macOS: the project's sealed mach services beyond the runtime's baseline (its `allowMachLookup`). */
-    machLookup?: string[];
-    /** macOS: the keychain's services (securityd), denied to every launch without it (sandbox-runtime.ts
-     * SEATBELT_NO_KEYCHAIN). Only fenceFor gives it, to a build's agent. Never a check's (one with sign-ins gets those in
-     * its environment, invoke.ts keychainSignIns), never a tool server's (serverGrantsOf). */
-    keychain?: true;
-    /** macOS: a project check's launch, or a flow script zone's with approved browser use, whose Chromium may start
-     * (sandbox-runtime.ts SEATBELT_CHROMIUM). Only fenceFor sets it: always for kind "check", for kind "flow" only when
-     * its caller proved the approval (flow-browser.ts). */
-    browser?: true;
-    /** A `sign-ins` check's exact sign-in files, read again inside the home denies (check-access.ts, signInGrants). */
-    signIns?: SignInGrants;
-    /** Never written, wherever the launch writes (homeWriteDenies): what runs for the operator next or signs them in. */
-    writeDenies?: string[];
-    /** Protected storage (protected-storage.ts): denied to read and write by every backend, and no grant equal to or
-     * inside one survives (a sandbox that lets the more specific path win can't reopen it). */
-    protectedStorage?: string[];
-};
-export { isWritesMode, WRITES_DEFAULT, type WritesMode } from "./writes-mode.js";
-/**
- * The only places a `workspace` build writes: `subpaths`, each a folder (or file) writable whole, and `prefixes`, a file
- * with the temporary names it is atomically replaced through, or a folder named by a pattern (a regex on macOS;
- * elsewhere the path alone, when it exists). Everything else is read-only to the build; its fence's denies and read-only grants still hold inside these.
- */
-export type WriteAllowlist = {
-    subpaths: string[];
-    prefixes: WritePrefix[];
-};
-/** A file or folder named by `path` followed by what `suffix` (a regular expression, anchored at its end) allows. */
-export type WritePrefix = {
-    path: string;
-    suffix: string;
-};
-/** Claude's transcript folder for a working folder: its path with every character but a letter or digit made `-`
- * (Claude Code's own naming; a name over 200 characters gets a suffix, so it is granted by prefix). */
-export declare function claudeProjectFolder(home: string, cwd: string): {
-    path: string;
-    byPrefix: boolean;
-};
-/**
- * A folder a write grant may name: made when absent, then only as the real folder it is — never a link, nor reached
- * through one (its real path is its parent's real path and its own name). A build can rewrite what it may write, so a
- * folder it was given could otherwise come back as a link to anywhere and be granted, followed, on its next launch.
- * Null when it isn't such a folder: nothing is granted, and the write it was for fails.
- */
-export declare function grantFolder(path: string, create?: boolean): string | null;
-/**
- * What a `workspace` build writes and what it loses (arc 2): its checkout, its checkout's Git data (less the shared
- * repository's config, hooks and info, which Git runs or reads as commands), its own launch folder (its temp is there),
- * its project's cache folder, the terminal devices, and only the provider state its CLI must write (measured: Claude's
- * transcript folder for this checkout; Gemini's history, temp and project list; an ACP agent's own folders). The
- * folders named here are made first, so the provider never has to make them where it can't. `deny` is what this
- * provider must not even read (Claude's live sessions' keys).
- */
-export declare function writeAllowlist(options: {
-    provider: string;
-    home: string;
-    worktree: string;
-    binding: WorktreeBinding | null;
-    launchFolder: string | null;
-    cache: string | null;
-}): {
-    writes: WriteAllowlist;
-    readOnly: string[];
-    deny: string[];
-};
-/** Where a project's builds keep their package caches: one folder per project (one trust domain), never used by the
- * plane's own tools, below the user's cache folder. */
-export declare function buildCacheFolder(repo: string, home?: string, platform?: NodeJS.Platform, env?: Readonly<Record<string, string | undefined>>): string;
-/** The environment that points a build's package managers at its project's cache folder, not the user's own. */
-export declare function buildCacheEnv(folder: string): Record<string, string>;
-/**
- * A launch's network confinement (egress.ts). `open`: the network as it always was. `allowlist`: nothing leaves the
- * machine but through the run's own proxy (`proxyPort`, which admits only this run's `token`); the run's tool broker
- * (`brokerPorts`, at most one) rides the sandbox runtime's second relay; this machine's other local services are
- * reachable only under `loopback: "any"`; unix sockets only under `socketRoots` (macOS).
- */
-export type NetworkFence = {
-    mode: "open";
-} | {
-    mode: "allowlist";
-    proxyPort: number;
-    brokerPorts: number[];
-    loopback: LoopbackMode;
-    socketRoots: string[];
-    token?: string;
-};
-export declare const NO_GRANTS: FenceGrants;
-/**
- * The plane's checkout pools, denied whole: every project's worktrees, and any made there after launch. `agentFence`
- * drops a path at or above the checkout, so the deny lives here and each sandbox gives back, right after it, only
- * `own` (this build's checkout, read and written) and `lookup` (the folders between, looked up, never listed).
- */
-export type CheckoutPool = {
-    deny: string[];
-    own: string | null;
-    lookup: string[];
-    gitPaths?: string[];
-    /** Policy v2 (owner Q-C): other tasks' checkouts are read, never written (agents can work together); v1 denies both. */
-    readable?: true;
-    /** Folders inside the pool that stay denied whole whatever the policy (flows' scratch folders hold their inputs and
-     * outputs), this launch's own folder given back. */
-    sealed?: string[];
-};
-/**
- * The pool deny for one launch. `roots` come from the plane's own records (the pool beside the database, and the one
- * the recorded checkout was made in), never from the checkout. A root that holds this checkout's own Git data (the
- * binding's gitdir or the repository's .git) is never denied whole: it is split around that data instead, entry by
- * entry, so it is denied as far as it can be (fail closed by denying more, never by refusing). A root inside the
- * checkout, the home folder, a folder above it or / is left alone: the first is the build's own work, the others the
- * whole machine.
- */
-export declare function checkoutPool(options: {
-    roots: readonly (string | null)[];
-    worktree: string | null;
-    binding?: WorktreeBinding | null;
-    home?: string;
-}, list?: (path: string) => string[]): CheckoutPool;
-/** The grants for one build: its task boundary's git rules, the shared dependencies its checkout links, and the
- * checkout pools (`poolRoots`, from the plane's records) denied around its own checkout. */
-export declare function fenceGrants(options: {
-    databaseFile: string | null;
-    worktree: string | null;
-    boundary?: TaskBoundary | null;
-    runFolders?: RunFolders;
-    linked?: {
-        repo: string;
-        setupDigest: string | null;
-    } | null;
-    poolRoots?: readonly (string | null)[];
-    binding?: WorktreeBinding | null;
-    home?: string;
-}): FenceGrants;
-/**
- * Git settings every fenced build runs with (GIT_CONFIG_COUNT, after any the
- * caller already set): `git gc` never expires a reflog, so it never rewrites
- * another task's reflog, which the fence would refuse mid-collection.
- */
-export declare function fencedGitEnv(base?: Readonly<Record<string, string | undefined>>): Record<string, string>;
-/**
- * Codex's own sandbox, fenced. Auto: the `:workspace` profile Codex's
- * `--sandbox workspace-write` already gives (workspace and temp writes, no
- * network). Full access: the same profile widened to write anywhere with
- * network on, instead of no sandbox at all. Either way the fenced paths are
- * denied, which in Codex outranks any write or read grant. The checkout pools
- * are never `flattened` (which leaves what is made after launch readable): see
- * `codexPool`, which denies them around the build's own checkout, written back.
- */
-export declare function codexFenceArgv(fence: readonly string[], fullAccess: boolean, grants?: FenceGrants): string[];
-/**
- * The same permission profile as codexFenceArgv, as the config overrides a Codex app-server thread takes
- * (`thread/start` and `thread/resume` `config`; checked against codex-cli 0.156: the thread reports
- * `activePermissionProfile` standing-orders, and its commands are refused the denied paths). Approval policy is the
- * caller's own (an interactive session asks).
- */
-export declare function codexFenceConfig(fence: readonly string[], fullAccess: boolean, grants?: FenceGrants): Record<string, unknown>;
-/**
- * Codex cannot deny an ancestor and still traverse it to the own checkout. Deny existing
- * siblings individually, from the trusted pool roots and a fresh listing, never through
- * flattened or name patterns. A project added after launch is covered on the next launch;
- * Seatbelt and bubblewrap retain the stronger whole-pool rule for later-created projects.
- */
-export declare function codexPool(pool: CheckoutPool, list?: (path: string) => string[]): {
-    read: string[];
-    deny: string[];
-    write: string[];
-};
-/** Secret-looking names denied by pattern inside a folder `flattened` makes read-only, so one written there after
- * launch is denied too (the database and its journals, tokens, login and other text files). */
-export declare const SPLIT_SECRET_PATTERNS: readonly ["orders.db*", "*token*", "up-login*", "*.txt", "*secret*", "*password*", "*credential*", "*.pem", "*.key"];
-/**
- * A fence as plain denied and read-only paths, for a sandbox that can't
- * grant inside a denied folder (Codex: a deny outranks any grant): a denied
- * folder holding something readable becomes read-only, with each of its
- * entries not on the way to what is readable denied instead. Fails closed: a
- * folder that can't be listed stays denied whole and its grant is dropped.
- * Residual: an entry made after launch in a read-only folder is denied only
- * when its name matches SPLIT_SECRET_PATTERNS; any other new entry there is
- * readable (never writable) until the next launch. The macOS fence has no
- * such gap: it denies the folder and grants back only the readable path.
- */
-export declare function flattened(fence: readonly string[], grants?: FenceGrants, list?: (path: string) => string[]): {
-    deny: string[];
-    readOnly: string[];
-};
-/** Claude's own file tools refuse the fenced paths in every mode (its shell is fenced by the macOS sandbox), and
- * never edit a read-only one. */
-export declare function claudeFenceSettings(fence: readonly string[], readOnly?: readonly string[]): string;
-/**
- * Whether this machine can run an agent inside the macOS fence (checked once). Not from inside another
- * sandbox: a Toolroll a fenced process starts (the end-to-end journeys a flow's check zone runs) can't nest
- * its fence, and would otherwise fail every launch. Its agents stay inside the outer fence, which every
- * child inherits, and are recorded with the fence they actually got. Any other probe failure keeps the
- * fence on, so a launch fails loudly rather than running unfenced.
- */
-export declare function macosFenceAvailable(platform?: NodeJS.Platform, probe?: () => {
-    status: number | null;
-    stderr: string;
-}): boolean;
-export declare function linuxFenceAvailable(platform?: NodeJS.Platform, probe?: () => boolean): boolean;
-/** Thrown when no sandbox can be made for a launch: the spawn road refuses it. */
-export declare class LinuxFenceUnavailable extends Error {
-}
-/**
- * The runtime's config for a launch (sandbox-runtime.ts SrtTerms), from its fence: every fenced path denied to read and
- * write (with the exact paths read again inside them), the pools' other checkouts write-denied (and, under v1, read-
- * denied) around the build's own, the flows' scratch folders sealed, the launch's writes (its allowlist, or anywhere
- * outside the denies), its mach services and its network.
- */
-export declare function srtTermsOf(fence: readonly string[], grants?: FenceGrants): SrtTerms;
-/** The spawn that runs `file args` from `cwd` inside the sandbox runtime's sandbox (sandbox-runtime.ts srtSpawn), and the
- * environment it needs beside the caller's. */
-export declare function sandboxedSpawn(file: string, args: readonly string[], fence: readonly string[], grants?: FenceGrants, cwd?: string, temp?: string): {
-    file: string;
-    args: string[];
-    env: Record<string, string>;
-};
-/**
- * What each agent's fence gives it, by permission mode: the one table "What an agent can reach" in
- * docs/guide/security.md shows (fenceSummaryMarkdown; a test holds them equal).
- */
-export declare const FENCE_SUMMARY: readonly {
-    agent: string;
-    auto: string;
-    full: string;
-}[];
-/** FENCE_SUMMARY as the security guide's markdown table. */
-export declare function fenceSummaryMarkdown(): string;
-/** What a `sign-ins` check reads and writes beyond its fence (check-access.ts): its exact sign-in files, its own Claude
- * transcript folder (macOS) and Codex's session and log folders. */
-export type SignInGrants = {
-    read: string[];
-    transcripts: string[];
-    writes: string[];
-    /** macOS services the sign-ins need: certificate checking (trustd), without which gh (Go) can't verify GitHub's TLS
-     * and calls its own token invalid. Measured with gh 2.x on macOS 26. */
-    mach: string[];
-};
-/**
- * A `sign-ins` check's grants (sandbox parity C10, srt-style): each sign-in file by its name, read by the check itself
- * through its sandbox. Nothing privileged reads or copies one: the sandbox resolves the name in its own view, so a link
- * planted there into Toolroll's state leads to a denied path (Seatbelt checks the resolved file; bubblewrap resolves
- * inside its mount namespace, where the state is masked). On a Mac, the checkout's own Claude transcript folder (made
- * when absent, only as the real folder it is), whose session files alone are written; and Codex's session and log
- * folders (when ~/.codex is there), never its config.
- */
-export declare function signInGrants(home: string, checkout: string, platform?: NodeJS.Platform): SignInGrants;
-/** Whether a sign-in file is itself, now: every folder from the (real) home folder down a real folder, the file a
- * regular file with one name (never a link, never a hard link to something else). Checked when granted and again right
- * before the launch (invoke.ts); the sandbox resolves the name a third time. */
-export declare function signInIsItself(base: string, path: string): boolean;
-/**
- * Which fence policy a launch runs under (docs/plans/sandbox-parity.md §1.5). v1: the fence as approvals sealed before
- * 0.9.70 knew it (the home configuration, the repositories beside the project and its primary checkout denied to read).
- * v2: those reads open, as in Anthropic's sandbox runtime, less what the project's sealed `readDeny` names. A widening,
- * so only a scope sealed at v2 runs under it; every narrowing applies to both.
- */
-export type FencePolicy = 1 | 2;
-export declare const FENCE_POLICY_CURRENT: FencePolicy;
-/** Who a launch is (docs/plans/sandbox-parity.md §3): a build's agent, its setup and check commands, a saved result's
- * checks, a flow's setup, script or trigger, or a tool server. Each gets its fence from `fenceFor`, and only from it. */
-export type FenceKind = "build" | "command" | "check" | "flow" | "tool-server";
-/**
- * What `fenceFor` needs. The boundary and the trusted binding are required, as values or an explicit null (a launch
- * with no checkout), so no caller forgets one; every path comes from Toolroll's own records, never from the checkout.
- */
-export type FenceContext = {
-    /** This launch's storage check, awaited before the fence is made (protected-storage.ts prepareProtectedStorage). Every
-     * launch road passes it (an architecture test holds them to it); without one the check runs right here, which only a
-     * test does. */
-    storage?: ProtectedStorage;
-    /** One exact file read back inside the fence (a build's code map), or null. */
-    exactFile?: string | null;
-    databaseFile: string | null;
-    worktree: string | null;
-    boundary: TaskBoundary | null;
-    binding: WorktreeBinding | null;
-    runFolders: RunFolders;
-    /** The checkout pools, from the plane's records (CheckoutPool). */
-    poolRoots: readonly (string | null)[];
-    home?: string;
-    /** Denied beside the fence (a provider's live session keys, say). */
-    extra?: readonly string[];
-    /** The shared dependencies this checkout links, as the plane recorded them. */
-    linked?: {
-        repo: string;
-        setupDigest: string | null;
-    } | null;
-    /** A workspace launch's write allowlist and what it adds read-only (writeAllowlist); absent: writes anywhere its
-     * fence allows. */
-    writes?: {
-        writes: WriteAllowlist;
-        readOnly: string[];
-    } | null;
-    /** The launch's network, when it has one of its own (a flow's: decided by its caller, never left unsaid). */
-    network?: NetworkFence;
-    /** What it may not read beside the fence, as absolute paths (project-sandbox.ts readDenyPath): denied whole. */
-    readDeny?: readonly string[];
-    /** macOS services it may also reach (project-sandbox.ts). */
-    machLookup?: readonly string[];
-    /** The fence policy it runs under: v2 reads other tasks' checkouts (never writes them). */
-    policy?: FencePolicy;
-    /** The agent the launch runs, whose own sign-in files stay its to write (PROVIDER_HOME). */
-    provider?: string;
-    /** Scratch folders (a flow's) that stay denied whole inside the pool, whatever the policy. */
-    scratchRoots?: readonly string[];
-    /** A flow's script zone whose browser use a person approved, proved at launch (flow-browser.ts browserStanding):
-     * Chromium's one service, as a check gets it. Read for kind "flow" only; every other kind ignores it. */
-    browser?: true;
-};
-/** A launch's sealed sandbox terms (builder.ts launchSandboxOf): its policy version, read denies and mach services. A
- * launch with none sealed is v1 with none of them. */
-export type LaunchSandbox = {
-    policy: FencePolicy;
-    readDeny: readonly string[];
-    machLookup: readonly string[];
-};
-export declare const LEGACY_SANDBOX: LaunchSandbox;
-/** A build's sandbox terms, exactly as its approval sealed them: an approval from before 0.9.70 is policy v1 (the home
- * configuration denied) with nothing listed. */
-export declare function launchSandboxOf(profile: ExecutionProfile): LaunchSandbox;
-/** A launch's whole fence: its denied paths, what it gives back, and that it runs inside the OS fence or not at all.
- * Spread into RunOptions as is. */
-export type LaunchFence = {
-    kind: FenceKind;
-    fence: string[];
-    fenceGrants: FenceGrants;
-    confinement: "required";
-};
-/** The one place a launch's fence is made (docs/plans/sandbox-parity.md C1): its denies, its grants, and
- * `confinement: "required"`, so the spawn road refuses it where no OS fence applies rather than running it bare. */
-export declare function fenceFor(kind: FenceKind, ctx: FenceContext): LaunchFence;
-/** The flows' scratch folders inside the checkout pools (`flow-checks` beside the checkouts) and any a caller names,
- * each denied by name whether or not it is there yet, and where it is a link, where it leads too. */
-export declare function sealedScratch(poolRoots: readonly (string | null)[], named: readonly string[]): string[];
-/**
- * Toolroll's own install as no launch may write it: this package's folder (its compiled code, the sandbox launch
- * helper among it), the sandbox runtime's package wherever it was installed, and the Node running them with the
- * folder it lives in (its npm and global packages beside it), as the real folders they are. Never a folder that holds
- * the launch's own checkout or its repository (a build of Toolroll's own source, run from it: that repository's other
- * files are the primary checkout's, write-denied already), the home folder or one above it, and nothing the user
- * doesn't own (root's folders are out of a build's reach already).
- */
-export declare function toolrollInstall(worktree: string | null, home: string, repository?: string | null): string[];
-/** Names that run code or reconfigure tools for whoever opens the project next: the sandbox runtime's DANGEROUS_FILES
- * (@anthropic-ai/sandbox-runtime sandbox-utils), and the names its mandatory denies can't hold when they are made
- * after a launch starts (`.envrc`, package-manager and Claude settings). */
-export declare const PROTECTED_FILES: readonly string[];
-/** Folders protected whole, wherever they are (the runtime's dangerous directories, with Git's hooks). */
-export declare const PROTECTED_DIRS: readonly string[];
-/**
- * The handoff's backstop (builder.ts commit): the changed paths (relative, from Git) that are protected names at any
- * depth, in any case. The sandbox runtime denies these when a launch starts; one made after it started (a new nested
- * folder's `.envrc`, say) gets through the sandbox, and a result that holds it is refused.
- */
-export declare function protectedChanges(changed: readonly string[]): string[];
-/**
- * The handoff's backstop for links (builder.ts commit): a staged symbolic link (Git mode 120000) whose path is a
- * protected name or a folder on the way to one (`pkg/.claude`, `.vscode`, `lib/.git`), at any depth, in any case. A
- * link there would lead whoever opens the project to settings, hooks or commands kept anywhere.
- */
-export declare function protectedLinks(links: readonly string[]): string[];
-/** The home folder's own persistence points beyond the protected names (login items, systemd user units and autostart,
- * Git's, gh's, pip's and fish's configuration, the shells' other startup files, SSH and GnuPG, and the folders on a
- * login PATH). Under `.config/` each also stands under $XDG_CONFIG_HOME. */
-export declare const HOME_PERSISTENCE: readonly string[];
-/**
- * What no launch writes, whatever its writes, as static write denies for the sandbox runtime (whose own protected names
- * are anchored at the launch's folder only) and Codex's profile: the home folder's protected names (shell profiles, Git
- * and tool configuration), its persistence points and sign-ins (but the launch's own agent's exact sign-in files), and
- * the bound repository's own Git config, hooks and submodules (a linked worktree reaches them through its `.git`
- * file). Each by its name and by where it leads now (a linked ~/.config or LaunchAgents is denied at both ends). On
- * Linux only those there at launch: the runtime holds an absent name with a stand-in nothing can read for the launch's
- * length, and the person's own git and shells then fail on their ~/.gitconfig and ~/.bashrc (measured). Under a write
- * allowlist an absent one is out of reach anyway; under `anywhere` it can be made (an accepted limit).
- */
-export declare function homeWriteDenies(home: string, binding: WorktreeBinding | null, provider: string | null, platform?: NodeJS.Platform, env?: Readonly<Record<string, string | undefined>>): string[];
-/** A tool server's grants from its build's: never the agent's network or write allowlist (a server keeps its own state
- * where it always has), and never the build's own checkout or launch folder read back (nothing a build wrote loads in a
- * process that holds a tool's secrets). */
-export declare function serverGrantsOf(grants: FenceGrants): FenceGrants;

package/dist/agent-onboard.d.ts

@@ -1,158 +0,0 @@
-/**
- * `toolroll onboard`: the agent that installed Toolroll becomes its lead.
- *
- * Run inside a repository, it adds that repository as a project (the same
- * registry and project row Projects → add writes), reports which agent
- * CLIs are signed in (the checks Settings → AI providers makes), installs
- * a thin operator skill for the person's own agent, prints the MCP line
- * without running it, and ends with a handoff the agent can relay.
- *
- * Adding the project and writing the skill both need --yes or one yes
- * typed at a terminal. Then it offers the starter flows (flow-starters.ts),
- * each switched on by its own yes at a terminal or by --starter; --yes alone
- * never switches one on. The project is the main checkout (never a linked
- * worktree, the home folder, or one of Toolroll's own worktrees). The skill
- * is replaced by the next onboard and deleted by `onboard --remove` only
- * while it is exactly a version Toolroll wrote; a file of the same name
- * that is not ours, or ours with the person's edits, is never touched.
- */
-import type { ProviderConnection } from "./provider-connection.js";
-import type { StarterView, SwitchedOn } from "./flow-starters.js";
-export type OnboardAgent = "claude" | "codex";
-export declare const ONBOARD_AGENTS: readonly OnboardAgent[];
-export declare const AGENT_NAMES: Record<OnboardAgent, string>;
-/** Each agent's user-level home: where its skills folder lives. A relative CODEX_HOME is under the home folder, never
- * wherever onboard happens to run. */
-export declare function agentHome(agent: OnboardAgent, home: string, env: Record<string, string | undefined>): string;
-export declare function operatorSkillPath(agent: OnboardAgent, home: string, env: Record<string, string | undefined>): string;
-/** The agents this person uses: those whose home folder exists, else Claude Code. */
-export declare function detectAgents(home: string, env: Record<string, string | undefined>): OnboardAgent[];
-/** The line that adds Toolroll as tools, for every project. Printed, never run. */
-export declare function mcpLine(agent: OnboardAgent): string;
-/** The thin skill: when to reach for Toolroll, and where the real guides are. */
-export declare function operatorSkillContent(version: string): string;
-/** A skill's fingerprint with the version it names set aside: every release writes the same words. */
-export declare function skillFingerprint(content: string): string;
-/** Every SKILL.md a release has generated at this path (skillFingerprint): the operator skill, and `skills install
- * --claude-code`'s. Kept, never replaced, when the words change: a skill an earlier release wrote is still ours. A
- * test fails until this build's own fingerprints are listed. */
-export declare const RELEASED_SKILLS: readonly string[];
-export type SkillStep = {
-    agent: OnboardAgent;
-    path: string;
-    /** create/replace/remove change the file; current and absent change nothing; not-ours and edited refuse. */
-    action: "create" | "replace" | "current" | "remove" | "absent" | "not-ours" | "edited";
-    /** Old guide copies of ours that go with it. */
-    alsoRemove: string[];
-};
-/** What install (or --remove) would do, without writing anything. */
-export declare function planOperatorSkill(agents: readonly OnboardAgent[], options: {
-    home: string;
-    env: Record<string, string | undefined>;
-    version: string;
-    remove: boolean;
-}): SkillStep[];
-/** Carry out a plan. Steps that are not ours, current, or absent change nothing. */
-export declare function applyOperatorSkill(steps: readonly SkillStep[], version: string): {
-    wrote: string[];
-    removed: string[];
-};
-/** How to sign in: the account, and the saved login file when one still works. Never the password. */
-export type HandoffLogin = {
-    account: string | null;
-    file: string | null;
-};
-export type Handoff = {
-    console: string;
-    /** How to start the console when it is not running. */
-    start: string;
-    /** null while there is no account yet. */
-    login: HandoffLogin | null;
-    phone: string;
-    next: readonly string[];
-};
-export declare const NEXT_THINGS: readonly ["queue these bugs overnight", "what needs me?", "open the result"];
-export declare function buildHandoff(input: {
-    url: string;
-    login: HandoffLogin | null;
-}): Handoff;
-export declare function handoffLines(handoff: Handoff): string[];
-/** The account name from a saved login file, never its password. */
-export declare function loginAccount(file: string): string | null;
-export type AgentReport = {
-    agent: OnboardAgent;
-    name: string;
-    state: ProviderConnection["state"];
-    words: string;
-    plan?: string;
-};
-export declare function agentReport(agent: OnboardAgent, connection: ProviderConnection): AgentReport;
-export type OnboardIo = {
-    write: (line: string) => void;
-    json: boolean;
-    yes: boolean;
-    remove: boolean;
-    /** --agent, as typed: a comma list of claude and codex. */
-    agentFlag: string | undefined;
-    url: string;
-    login: HandoffLogin | null;
-    home: string;
-    /** Where Toolroll leases its own worktrees: never a project. */
-    worktrees: string;
-    env: Record<string, string | undefined>;
-    version: string;
-    cwd: string;
-    /** A person at a terminal who can be asked y/N. */
-    interactive: boolean;
-    confirm: (question: string) => Promise<boolean>;
-    /** The repository containing cwd: its top folder, and its main checkout (the same folder unless cwd is in a linked
-     * worktree). null outside one. */
-    findRepo: (cwd: string) => Promise<{
-        top: string;
-        main: string;
-    } | null>;
-    /** Whether a repository is already a project. */
-    enrolled: (repo: string) => Promise<boolean>;
-    /** Add a repository as a project, as Projects → add does. */
-    enroll: (repo: string) => Promise<{
-        ok: true;
-        added: boolean;
-    } | {
-        ok: false;
-        message: string;
-    }>;
-    checkConnection: (agent: OnboardAgent) => Promise<ProviderConnection>;
-    /** Whether the project can open pull requests at Complete, in one line: on, the one command that turns it on, or
-     * what to fix first. Turning it on stays a person's password step. */
-    pullRequests?: (repo: string) => Promise<string>;
-    /** For a project that uses youiyoux, the one line that says its change requests become tasks; null otherwise. */
-    youiyoux?: (repo: string) => Promise<string | null>;
-    /** --starter, as typed: a comma list of starter flow ids to switch on. */
-    starterFlag?: string | undefined;
-    /** The project's starter flows, and switching one on — its trigger and zones. */
-    starters?: {
-        list: (repo: string) => Promise<StarterView[]>;
-        switchOn: (repo: string, id: string) => Promise<SwitchedOn>;
-    };
-};
-export type StarterAnswer = {
-    id: string;
-    name: string;
-    summary: string;
-    does: string[];
-    never: string;
-    state: "on" | "switched-on" | "off" | "unavailable" | "failed";
-    flow?: number;
-    said?: string;
-};
-/** Why a found repository cannot be the project, or null when it can. */
-export declare function projectRefusal(found: {
-    top: string;
-    main: string;
-}, where: {
-    cwd: string;
-    home: string;
-    worktrees: string;
-}): string | null;
-/** Returns the exit code: 0 done, 2 usage, 3 a refusal to answer. */
-export declare function runOnboard(io: OnboardIo): Promise<number>;