@themoltnet/sandbox-gondolin 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,364 @@
+import { MemoryProvider } from '@earendil-works/gondolin';
+import { VirtualFileHandle } from '@earendil-works/gondolin';
+import { VM } from '@earendil-works/gondolin';
+
+export declare function abortableResource<T>(opts: AbortableResourceOptions<T>): Promise<T>;
+
+declare interface AbortableResourceOptions<T> {
+    promise: PromiseLike<T>;
+    signal: AbortSignal | undefined;
+    label: string;
+    cleanup: (resource: T) => Promise<void> | void;
+    onCleanupError?: (err: unknown) => void;
+}
+
+/**
+ * Apply agent env vars to the host process, mirroring `moltnet start`.
+ * Resolves relative paths (e.g. GIT_CONFIG_GLOBAL) against the repo root.
+ */
+export declare function activateAgentEnv(agentEnv: Record<string, string | undefined>, repoRoot: string): void;
+
+export declare function assertGuestEnvironmentBoundary(options: {
+    guestCredentialMode: GuestCredentialMode;
+    forwardEnv?: readonly string[];
+    sandboxEnv?: Readonly<Record<string, string>>;
+}): void;
+
+/** @deprecated Prefer assertGuestEnvironmentBoundary for mode-aware checks. */
+export declare function assertHostAuthenticatedGuestEnvironment(options: {
+    forwardEnv?: readonly string[];
+    sandboxEnv?: Readonly<Record<string, string>>;
+}): void;
+
+export declare class AutoParentMemoryProvider extends MemoryProvider {
+    private ensureParentDir;
+    mkdir(pathname: string, options?: object): Promise<void | string>;
+    mkdirSync(pathname: string, options?: object): void | string;
+    open(pathname: string, flags: string, mode?: number): Promise<VirtualFileHandle>;
+    openSync(pathname: string, flags: string, mode?: number): VirtualFileHandle;
+}
+
+export declare function delay(ms: number, signal: AbortSignal | undefined, label: string): Promise<void>;
+
+/**
+ * Ensure a cached snapshot exists, building one if needed.
+ * Returns the absolute path to the qcow2 checkpoint file.
+ */
+export declare function ensureSnapshot(options?: EnsureSnapshotOptions): Promise<string>;
+
+export declare interface EnsureSnapshotOptions {
+    config?: SnapshotConfig;
+    onProgress?: (message: string) => void;
+    /** Max number of old snapshots to keep (default 1). */
+    maxCached?: number;
+}
+
+/**
+ * Resolve the main worktree root (where .moltnet/ lives — it's untracked,
+ * only exists in the main worktree, not in git worktrees).
+ */
+export declare function findMainWorktree(startPath?: string): string;
+
+/** Commands guaranteed by the base Gondolin snapshot. */
+export declare const GONDOLIN_BASE_EXECUTABLES: readonly string[];
+
+/**
+ * Memory-backed VFS mount used by the daemon to inject task context
+ * (#943 slice 1.5). This is a separate top-level mount because Gondolin
+ * mounts can't nest. The agent's Gondolin-bound Read tool accepts paths
+ * under this prefix (see toGuestPath in tool-operations.ts).
+ *
+ * Why MemoryProvider rather than a path under the workspace mount:
+ *   - Injected task context is ephemeral by intent: per-task-attempt input
+ *     scoped to the VM lifetime. MemoryProvider models that exactly —
+ *     in-memory, per-VM-instance, zero host artefacts, automatic
+ *     cleanup on VM close.
+ *   - Writing under the workspace mount fails in worktrees because we symlink
+ *     `.moltnet/` to the main repo (so credentials are reachable from
+ *     worktrees), and Gondolin's RealFSProvider correctly refuses to
+ *     create paths whose ancestors' realpath escapes the mount root.
+ *     That refusal is a deliberate sandbox-escape protection, not a
+ *     bug. See diary semantic entry cd27d9d3-efdc-4aec-ac0d-5fd8ce258d1f
+ *     and episodic 7affbfeb-18a2-4963-aeac-c177eb2afa2d for the full
+ *     investigation and the alternatives we rejected.
+ */
+export declare const GUEST_TASK_CONTEXT_MOUNT = "/moltnet-task-context";
+
+/** @deprecated Use GUEST_TASK_CONTEXT_MOUNT. */
+export declare const GUEST_TASK_SKILLS_MOUNT = "/moltnet-task-context";
+
+export declare type GuestCredentialMode = 'guest-config' | 'host-authenticated';
+
+export declare class GuestEnvironmentBoundaryError extends Error {
+    readonly refusedNames: readonly string[];
+    constructor(refusedNames: readonly string[]);
+}
+
+/**
+ * Check containment for already-resolved lexical or real paths.
+ *
+ * Callers that accept untrusted paths must resolve/realpath at their I/O
+ * boundary first; keeping the platform-specific relative-path rule here avoids
+ * subtly different `..` and absolute-path handling across runtime cleanup,
+ * session sync, and artifact staging.
+ */
+export declare function isResolvedPathInsideRoot(path: string, root: string): boolean;
+
+export declare function loadCredentials(agentDir: string, mode?: GuestCredentialMode, onDiagnostic?: (diagnostic: VmDiagnostic) => void, providerAuth?: ProviderAuthSource): VmCredentials;
+
+export declare interface ManagedVm {
+    vm: VM;
+    credentials: VmCredentials;
+    mountPath: string;
+    guestWorkspace: string;
+    agentDir: string;
+}
+
+export declare interface ProviderAuthSource {
+    /** Read the auth blob from the host, or return null when absent. */
+    load(): string | null;
+    /** Absolute guest path to write the blob to (mode 0600). */
+    guestPath: string;
+}
+
+export declare function resolveVfsShadowConfig(config: SandboxConfig | undefined): {
+    mode: 'none';
+    patterns: [];
+} | {
+    mode: 'deny' | 'tmpfs';
+    patterns: string[];
+};
+
+export declare function resolveVmAgentDir(config: {
+    agentName: string;
+    agentRootDir?: string;
+}): string;
+
+export declare interface ResumeCommand {
+    /** Shell command, same semantics as the string form. */
+    run: string;
+    /** Optional generic runtime predicate for whether this step should run. */
+    when?: ResumeCommandWhen;
+    /** Additional attempts on non-zero exit. Default 0. */
+    retries?: number;
+    /** Linear backoff between attempts in ms. Delay before attempt N+1 is
+     *  `(N + 1) * retryBackoffMs` (so 2s, 4s, … with the default). */
+    retryBackoffMs?: number;
+}
+
+/** Structured form of a resume command with optional retry policy. */
+export declare interface ResumeCommandWhen {
+    /**
+     * Effective workspace mode(s) that should run this command.
+     * Evaluated by the runtime from the mounted workspace shape rather than
+     * from task type semantics.
+     */
+    workspaceMode?: ('shared_mount' | 'dedicated_worktree' | 'scratch_mount')[];
+}
+
+/**
+ * Resume a VM from a checkpoint, inject credentials, configure egress +
+ * TLS. Returns the managed VM handle.
+ */
+export declare function resumeVm(config: VmConfig): Promise<ManagedVm>;
+
+/**
+ * Rewrite host-absolute paths inside an agent gitconfig to VM-local
+ * equivalents before injecting it into the guest.
+ *
+ * Two rewrites:
+ *   - `signingKey = <host path>`  → `<vmSshDir>/id_ed25519`
+ *   - `... credential-helper --credentials <host moltnet.json>`
+ *                                 → `<vmAgentDir>/moltnet.json`
+ *
+ * The credential-helper line is generated host-side by `moltnet github setup`
+ * with a host-absolute `--credentials` path; inside the guest that path is
+ * invalid, so it must point at the VM-side moltnet.json. The `insteadOf`
+ * rewrite rule and every other line are workspace-independent and pass through
+ * unchanged. A gitconfig without a credential helper is rewritten only for
+ * `signingKey`.
+ *
+ * This is the single source of truth for git push auth in the guest: the
+ * injected gitconfig carries the tokenless mint-on-demand helper, so the VM
+ * no longer hand-rolls a credential-helper script or runs an imperative
+ * `git config --global ... insteadOf` against the guest $HOME.
+ */
+export declare function rewriteGitconfigPaths(gitconfig: string, vmSshDir: string, vmAgentDir: string): string;
+
+/**
+ * Rewrite host-absolute paths inside moltnet.json to VM-local equivalents.
+ *
+ * Fields rewritten:
+ *   ssh.private_key_path  → <vmSshDir>/<basename of original>
+ *   ssh.public_key_path   → <vmSshDir>/<basename of original>
+ *   git.config_path       → <vmAgentDir>/gitconfig
+ *   github.private_key_path → <vmAgentDir>/<pemFilename>  (if present)
+ *
+ * All other fields are passed through unchanged.
+ * Throws if moltnetJson is not valid JSON — callers must not inject a broken
+ * moltnet.json into the guest.
+ */
+export declare function rewriteMoltnetJsonPaths(moltnetJson: string, vmAgentDir: string, vmSshDir: string, githubAppPemFilename: string | null): string;
+
+export declare interface SandboxConfig {
+    /**
+     * Operator-owned snapshot build settings. Runtime profiles must never
+     * populate this field.
+     */
+    snapshot?: {
+        /** Shell commands to run after the base setup. */
+        setupCommands?: string[];
+        /** Additional hosts to allow network access during build. */
+        allowedHosts?: string[];
+        /** Overlay disk size (default '3G'). */
+        overlaySize?: string;
+    };
+    /** Runtime network egress policy. Separate from snapshot build access. */
+    network?: {
+        /** Additional host patterns allowed while the VM is running.
+         * Internal and private address resolution remains blocked. */
+        allowedHosts?: string[];
+        /** Host patterns explicitly allowed to resolve to internal/private IPs. */
+        allowedInternalHosts?: string[];
+    };
+    /** Operator-owned shell commands to run every VM resume, after platform setup
+     *  (TLS, DNS, git safe.directory, tmpfs node_modules) and before
+     *  the agent session starts. Use for per-session bootstrap that
+     *  doesn't belong baked into the snapshot.
+     *
+     *  Not included in the snapshot cache key — changes here apply on
+     *  every resume without triggering a snapshot rebuild. Each command
+     *  runs in a fresh shell with `set -eu` and `set -o pipefail`; a
+     *  non-zero exit (including from any segment of a pipeline) aborts
+     *  resume with the failing command's stderr/stdout tail.
+     *
+     *  Each entry is either a raw string (no retries) or an object
+     *  `{ run, when?, retries?, retryBackoffMs? }`. `when` gates the
+     *  command on generic runtime properties such as effective
+     *  `workspaceMode`; this keeps sandbox policy decoupled from task
+     *  types. `retries` is the number of ADDITIONAL attempts after the
+     *  first failure (default 0 = no retry). Use for steps that hit the
+     *  network and may legitimately race DHCP/registry availability on a
+     *  fresh resume (e.g. `pnpm install`). The wrapped command must be
+     *  idempotent. */
+    resumeCommands?: (string | ResumeCommand)[];
+    /** VFS shadow settings — hide host paths from the guest. */
+    vfs?: {
+        /** Paths (relative to workspace root) to shadow from the host mount. */
+        shadow?: string[];
+        /** What to do with writes to shadowed paths: 'deny' or 'tmpfs' (default 'tmpfs'). */
+        shadowMode?: 'deny' | 'tmpfs';
+    };
+    /** Environment variable overrides for the guest VM (applied on top of defaults). */
+    env?: Record<string, string>;
+    /** Host-side escape hatch policy. Applies only to `moltnet_host_exec`. */
+    hostExec?: {
+        /**
+         * `true` auto-approves every allowed executable. An array auto-approves
+         * only commands matching one of the executable/argument rules.
+         */
+        autoApprove?: boolean | {
+            executable: string;
+            argsPrefix?: string[];
+            argsContains?: string[];
+            argsExcludes?: string[];
+        }[];
+    };
+    /** VM resource allocation. */
+    resources?: {
+        /** Memory size in qemu syntax (default '1G'). */
+        memory?: string;
+        /** CPU count (default 2). */
+        cpus?: number;
+    };
+}
+
+export declare function shouldRunResumeCommand(entry: string | ResumeCommand, ctx: {
+    workspaceMode: 'shared_mount' | 'dedicated_worktree' | 'scratch_mount';
+}): boolean;
+
+export declare function shouldShadowNodeModulesPath(pathname: string): boolean;
+
+/** Extract snapshot-specific config for backwards compat with ensureSnapshot. */
+export declare type SnapshotConfig = NonNullable<SandboxConfig['snapshot']>;
+
+export declare function throwIfAborted(signal: AbortSignal | undefined, label: string): void;
+
+export declare interface VmConfig {
+    /** Absolute path to the qcow2 checkpoint. */
+    checkpointPath: string;
+    /** MoltNet agent name (used to resolve credentials). */
+    agentName: string;
+    /**
+     * Trust boundary for guest credentials. `guest-config` injects the complete
+     * legacy agent directory. `host-authenticated` never reads or injects it and
+     * relies exclusively on the supplied host-side Agent for MoltNet operations.
+     */
+    guestCredentialMode?: GuestCredentialMode;
+    /**
+     * Host root that owns `.moltnet/<agentName>/`.
+     *
+     * Defaults to the main git worktree for backwards compatibility. Daemon
+     * callers pass the sandbox root so non-git scratch/shared tasks can boot.
+     */
+    agentRootDir?: string;
+    /** Host directory to mount into the VM. */
+    mountPath: string;
+    /** Effective workspace shape selected by the caller. */
+    workspaceMode?: 'shared_mount' | 'dedicated_worktree' | 'scratch_mount';
+    /** Additional hosts to allow in egress policy. */
+    extraAllowedHosts?: string[];
+    /** Full sandbox config (vfs shadows, env overrides). */
+    sandboxConfig?: SandboxConfig;
+    /**
+     * Host environment variable names to copy into the VM process.
+     *
+     * Runtime profiles use this for provider API keys: `requiredEnv` proves the
+     * daemon host has the secret, and this allowlist forwards only those names
+     * into the guest without storing secret values in the profile.
+     */
+    forwardEnv?: string[];
+    /** Structured credential-boundary diagnostics for daemon loggers. */
+    onDiagnostic?: (diagnostic: VmDiagnostic) => void;
+    /** Abort resume/setup work, closing any live VM owned by resumeVm. */
+    signal?: AbortSignal;
+    /**
+     * Coding-agent provider authentication to place in the guest (for example
+     * Pi's `auth.json`). The sandbox knows nothing about the provider: the
+     * runtime above it supplies the loader and the guest path. When omitted,
+     * nothing is written and the guest relies on forwarded env providers.
+     */
+    providerAuth?: ProviderAuthSource;
+}
+
+export declare interface VmCredentials {
+    /** Empty in host-authenticated mode; retained as strings for API stability. */
+    moltnetJson: string;
+    /** Empty in host-authenticated mode; retained as strings for API stability. */
+    agentEnvRaw: string;
+    /**
+     * Provider auth blob supplied by `VmConfig.providerAuth`, or null when the
+     * runtime supplied none or the host file is absent — the guest then relies
+     * on env-var providers (`ANTHROPIC_API_KEY`, etc.) carried via `agentEnv`
+     * and the forwarded host environment instead. CI uses this path.
+     */
+    providerAuthJson: string | null;
+    agentEnv: Record<string, string | undefined>;
+    gitconfig: string | null;
+    sshPrivateKey: string | null;
+    sshPublicKey: string | null;
+    allowedSigners: string | null;
+    /** Raw PEM content of the GitHub App private key, or null if not configured. */
+    githubAppPem: string | null;
+    /** VM-local filename for the GitHub App PEM (basename of host path), or null. */
+    githubAppPemFilename: string | null;
+}
+
+export declare interface VmDiagnostic {
+    event: 'vm.credentials.mode' | 'vm.credentials.github_key_missing';
+    level: 'info' | 'warning';
+    message: string;
+    credentialMode: GuestCredentialMode;
+}
+
+export { }