@zenera/engine 0.0.0-stage → 1.1.39

package/dist/projects.d.ts

@@ -0,0 +1,91 @@
+import { type ProjectConfig, type SandboxMount } from '@zenera/neo';
+/** Whether a directory is a project: whether the loader has something to read. */
+export declare function isProjectDir(dir: string): boolean;
+/** A project resolved on disk. */
+export interface Project {
+    dir: string;
+    /** what it is called: the registry's name, or the directory's own */
+    name: string;
+}
+/**
+ * The trees a run mounts besides the workspace itself.
+ *
+ * One array, handed to the file tools and to the container both, because the
+ * two have to agree on the name: a path `run_command` prints has to be a path
+ * `read_file` takes. Everything here is read-only — material an agent consults
+ * and does not edit — and the paths are resolved, because the podman machine on
+ * macOS shares the real path or nothing.
+ */
+export declare function projectMounts(root: string, config: ProjectConfig, memoryAt?: string): SandboxMount[];
+/** Walks up from `start` looking for a project configuration. */
+export declare function findUp(start: string): Promise<Project | undefined>;
+export declare function openDir(dir: string): Promise<Project>;
+/**
+ * A name from the registry, or a path. A value that looks like either is tried
+ * as both, path first, because a directory that exists is unambiguous evidence
+ * and a stale registry entry is not.
+ */
+export declare function open(nameOrDir: string): Promise<Project>;
+/**
+ * `open` where a miss is an answer rather than an error. It exists for the one
+ * place a word might be a project name and might be something else entirely —
+ * `zen run <project>` against `zen run <prompt>` — and the difference decides
+ * how the rest of the line is read.
+ */
+export declare function find(nameOrDir: string): Promise<Project | undefined>;
+/** The project a bare command means: the one you are standing in. */
+export declare function current(cwd?: string): Promise<Project | undefined>;
+export interface RegistryEntry {
+    name: string;
+    path: string;
+    addedAt: string;
+}
+export declare class Registry {
+    #private;
+    private constructor();
+    static open(): Promise<Registry>;
+    get entries(): readonly RegistryEntry[];
+    find(name: string): RegistryEntry | undefined;
+    findPath(dir: string): RegistryEntry | undefined;
+    /** Idempotent: re-registering the same directory refreshes it in place. */
+    add(name: string, dir: string): RegistryEntry;
+    remove(name: string): boolean;
+    /** Drops entries whose directory is gone. Returns what it dropped. */
+    prune(): RegistryEntry[];
+    save(): void;
+}
+export interface ProjectSummary {
+    name: string;
+    path: string;
+    /** false when the directory has gone away since it was registered */
+    present: boolean;
+    sessions: number;
+    runs: number;
+    lastRunAt?: string;
+    /** a session currently held by a live process */
+    busy: boolean;
+}
+export declare function summarize(entry: RegistryEntry): Promise<ProjectSummary>;
+export declare const sessionsDir: (projectDir: string) => string;
+/** Session ids, oldest first. Only well-formed stamps count as sessions. */
+export declare function sessionIds(projectDir: string): string[];
+export declare function runIds(sessionDir: string): string[];
+/**
+ * When this project was last worked in, as a stamp, or `undefined` for one
+ * that never has been. Session and run ids are stamps in the same format, so
+ * the newest of either compares directly — and reading directory NAMES is what
+ * keeps this cheap enough to ask of every registered project before drawing a
+ * chooser.
+ */
+export declare function lastUsedAt(projectDir: string): string | undefined;
+/**
+ * What a tree occupies, in allocated blocks rather than in bytes, because a
+ * sparse file costs what it was given and not what it claims. Symlinks are
+ * counted and never followed: a link out of the tree is not part of it, and
+ * one that points back in would otherwise be counted twice — or forever.
+ */
+export declare function dirSize(dir: string): number;
+/** True when a session's lock names a process that is still alive. */
+export declare function isBusy(sessionDir: string): boolean;
+export declare function projectName(dir: string): string;
+//# sourceMappingURL=projects.d.ts.map

package/dist/projects.js

@@ -0,0 +1,303 @@
+import { ASSETS_MOUNT, assetsDir, FILES_DIR, MEMORY_MOUNT, memoryDir, pidAlive, skillDirs, skillMounts, SKILLS_MOUNT, } from '@zenera/neo';
+import { existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, realpathSync } from 'node:fs';
+import { basename, dirname, isAbsolute, join, resolve } from 'node:path';
+import { invalidError, usageError } from "./errors.js";
+import { paths, readJson, writeJson } from "./home.js";
+import { isStamp } from "./ids.js";
+// ---------------------------------------------------------------------------
+// Projects
+//
+// The directory is the truth, and what makes a directory a project is the one
+// file the runtime cannot do without: `agents.yaml`. There is no marker file
+// beside it — that would be a second thing to keep in sync, holding a name the
+// directory already has.
+//
+// `~/.zenera/neo/projects.json` is an index so that `zen list` and `zen open` do
+// not have to search the filesystem, and it is allowed to be wrong: every entry
+// can be rebuilt by pointing `zen` at the directory again, and an entry whose
+// path has vanished is reported, not fatal.
+// ---------------------------------------------------------------------------
+/**
+ * The loader's own names, in its own order — `packages/neo/src/project/load.ts`.
+ * Anything the library would load, `zen` finds.
+ */
+const CONFIG_NAMES = ['agents.yaml', 'agents.yml', 'agents/agents.yaml', 'agents/agents.yml'];
+/** Whether a directory is a project: whether the loader has something to read. */
+export function isProjectDir(dir) {
+    return CONFIG_NAMES.some((name) => existsSync(join(dir, name)));
+}
+/**
+ * The trees a run mounts besides the workspace itself.
+ *
+ * One array, handed to the file tools and to the container both, because the
+ * two have to agree on the name: a path `run_command` prints has to be a path
+ * `read_file` takes. Everything here is read-only — material an agent consults
+ * and does not edit — and the paths are resolved, because the podman machine on
+ * macOS shares the real path or nothing.
+ */
+export function projectMounts(root, config, memoryAt) {
+    const mounts = [];
+    const assets = assetsDir(root, config);
+    if (assets) {
+        mounts.push({ host: realpathSync(assets), at: ASSETS_MOUNT, readOnly: true });
+    }
+    // The catalog goes in whole, at fixed names, before anything is loaded: a
+    // container's mounts are decided when it is created, so a skill folder
+    // cannot be added at the moment `skill_load` asks for it.
+    for (const dir of skillMounts(skillDirs(root, config), SKILLS_MOUNT)) {
+        mounts.push({ host: realpathSync(dir.path), at: dir.at, readOnly: true });
+    }
+    const memory = memoryDir(root, config, memoryAt);
+    if (memory) {
+        // Created here because the mount is decided before the project is
+        // loaded, and podman would refuse a source that does not exist yet.
+        const files = join(memory, FILES_DIR);
+        mkdirSync(files, { recursive: true });
+        mounts.push({ host: realpathSync(files), at: MEMORY_MOUNT, readOnly: true });
+    }
+    return mounts;
+}
+// ---------------------------------------------------------------------------
+// The project directory
+// ---------------------------------------------------------------------------
+/**
+ * What a project answers to. The registry is asked first, so one registered
+ * under a name of its own keeps it; the directory's name answers for a project
+ * that was never registered — which is a working project, just not a listed one.
+ */
+async function nameOf(dir) {
+    return (await Registry.open()).findPath(dir)?.name ?? basename(dir);
+}
+// ---------------------------------------------------------------------------
+// Finding one
+// ---------------------------------------------------------------------------
+/** Walks up from `start` looking for a project configuration. */
+export async function findUp(start) {
+    let dir = resolve(start);
+    for (;;) {
+        if (isProjectDir(dir)) {
+            return { dir, name: await nameOf(dir) };
+        }
+        const parent = dirname(dir);
+        if (parent === dir) {
+            return undefined;
+        }
+        dir = parent;
+    }
+}
+export async function openDir(dir) {
+    const at = resolve(dir);
+    if (!isProjectDir(at)) {
+        throw invalidError(`${at} is not a project`, `no ${CONFIG_NAMES[0]} — run: zen init`);
+    }
+    return { dir: at, name: await nameOf(at) };
+}
+/**
+ * A name from the registry, or a path. A value that looks like either is tried
+ * as both, path first, because a directory that exists is unambiguous evidence
+ * and a stale registry entry is not.
+ */
+export async function open(nameOrDir) {
+    if (isAbsolute(nameOrDir) || nameOrDir.startsWith('.') || existsSync(nameOrDir)) {
+        return openDir(nameOrDir);
+    }
+    const entry = (await Registry.open()).find(nameOrDir);
+    if (!entry) {
+        throw usageError(`no project named "${nameOrDir}"`, 'see: zen list');
+    }
+    return openDir(entry.path);
+}
+/**
+ * `open` where a miss is an answer rather than an error. It exists for the one
+ * place a word might be a project name and might be something else entirely —
+ * `zen run <project>` against `zen run <prompt>` — and the difference decides
+ * how the rest of the line is read.
+ */
+export async function find(nameOrDir) {
+    if (isAbsolute(nameOrDir) || nameOrDir.startsWith('.') || existsSync(nameOrDir)) {
+        const dir = resolve(nameOrDir);
+        return isProjectDir(dir) ? { dir, name: await nameOf(dir) } : undefined;
+    }
+    const entry = (await Registry.open()).find(nameOrDir);
+    return entry ? openDir(entry.path) : undefined;
+}
+/** The project a bare command means: the one you are standing in. */
+export async function current(cwd = process.cwd()) {
+    return findUp(cwd);
+}
+export class Registry {
+    #file;
+    constructor(file) {
+        this.#file = file;
+    }
+    static async open() {
+        const file = await readJson(paths.projects(), {
+            version: 1,
+            projects: [],
+        });
+        return new Registry({ version: 1, projects: file.projects ?? [] });
+    }
+    get entries() {
+        return this.#file.projects;
+    }
+    find(name) {
+        return this.#file.projects.find((p) => p.name === name);
+    }
+    findPath(dir) {
+        const at = resolve(dir);
+        return this.#file.projects.find((p) => resolve(p.path) === at);
+    }
+    /** Idempotent: re-registering the same directory refreshes it in place. */
+    add(name, dir) {
+        const path = resolve(dir);
+        const existing = this.find(name);
+        if (existing && resolve(existing.path) !== path) {
+            throw usageError(`a different project is already named "${name}"`, `it lives at ${existing.path} — use --name`);
+        }
+        const byPath = this.findPath(path);
+        if (byPath) {
+            byPath.name = name;
+            return byPath;
+        }
+        const entry = { name, path, addedAt: new Date().toISOString() };
+        this.#file.projects.push(entry);
+        return entry;
+    }
+    remove(name) {
+        const at = this.#file.projects.findIndex((p) => p.name === name);
+        if (at < 0) {
+            return false;
+        }
+        this.#file.projects.splice(at, 1);
+        return true;
+    }
+    /** Drops entries whose directory is gone. Returns what it dropped. */
+    prune() {
+        const gone = this.#file.projects.filter((p) => !isProjectDir(p.path));
+        this.#file.projects = this.#file.projects.filter((p) => !gone.includes(p));
+        return gone;
+    }
+    save() {
+        writeJson(paths.projects(), this.#file, 0o600);
+    }
+}
+export async function summarize(entry) {
+    const base = {
+        name: entry.name,
+        path: entry.path,
+        present: false,
+        sessions: 0,
+        runs: 0,
+        busy: false,
+    };
+    if (!isProjectDir(entry.path)) {
+        return base;
+    }
+    const summary = { ...base, present: true };
+    for (const session of sessionIds(entry.path)) {
+        summary.sessions++;
+        const dir = join(entry.path, 'sessions', session);
+        if (isBusy(dir)) {
+            summary.busy = true;
+        }
+        const ids = runIds(dir);
+        summary.runs += ids.length;
+        const newest = ids.at(-1);
+        if (newest && (!summary.lastRunAt || newest > summary.lastRunAt)) {
+            summary.lastRunAt = newest;
+        }
+    }
+    return summary;
+}
+// ---------------------------------------------------------------------------
+// Sessions and runs
+//
+// Kept here rather than in session.ts because listing them is a read-only
+// question about a directory, and `zen list` must be able to ask it without
+// pulling in the runtime.
+// ---------------------------------------------------------------------------
+export const sessionsDir = (projectDir) => join(projectDir, 'sessions');
+/** Session ids, oldest first. Only well-formed stamps count as sessions. */
+export function sessionIds(projectDir) {
+    return stampedChildren(sessionsDir(projectDir));
+}
+export function runIds(sessionDir) {
+    return stampedChildren(join(sessionDir, 'runs'));
+}
+/**
+ * When this project was last worked in, as a stamp, or `undefined` for one
+ * that never has been. Session and run ids are stamps in the same format, so
+ * the newest of either compares directly — and reading directory NAMES is what
+ * keeps this cheap enough to ask of every registered project before drawing a
+ * chooser.
+ */
+export function lastUsedAt(projectDir) {
+    let last;
+    for (const id of sessionIds(projectDir)) {
+        const newest = runIds(join(sessionsDir(projectDir), id)).at(-1) ?? id;
+        if (!last || newest > last) {
+            last = newest;
+        }
+    }
+    return last;
+}
+function stampedChildren(dir) {
+    if (!existsSync(dir)) {
+        return [];
+    }
+    return readdirSync(dir, { withFileTypes: true })
+        .filter((e) => e.isDirectory() && isStamp(e.name))
+        .map((e) => e.name)
+        .sort();
+}
+/**
+ * What a tree occupies, in allocated blocks rather than in bytes, because a
+ * sparse file costs what it was given and not what it claims. Symlinks are
+ * counted and never followed: a link out of the tree is not part of it, and
+ * one that points back in would otherwise be counted twice — or forever.
+ */
+export function dirSize(dir) {
+    let total = 0;
+    const stack = [dir];
+    while (stack.length > 0) {
+        const at = stack.pop();
+        let entries;
+        try {
+            entries = readdirSync(at, { withFileTypes: true });
+        }
+        catch {
+            continue;
+        }
+        for (const entry of entries) {
+            const path = join(at, entry.name);
+            if (entry.isDirectory()) {
+                stack.push(path);
+                continue;
+            }
+            try {
+                total += lstatSync(path).blocks * 512;
+            }
+            catch {
+                // Gone between the listing and the stat: a live session is
+                // writing, which is normal and not worth failing a report for.
+            }
+        }
+    }
+    return total;
+}
+/** True when a session's lock names a process that is still alive. */
+export function isBusy(sessionDir) {
+    const path = join(sessionDir, '.lock');
+    try {
+        const { pid } = JSON.parse(readFileSync(path, 'utf8'));
+        return typeof pid === 'number' && pidAlive(pid);
+    }
+    catch {
+        // Absent, unreadable or malformed: nothing is holding it.
+        return false;
+    }
+}
+export function projectName(dir) {
+    return basename(resolve(dir));
+}
+//# sourceMappingURL=projects.js.map

package/dist/sandbox.d.ts

@@ -0,0 +1,66 @@
+import { SandboxPool, type AgentProject, type ProjectConfig, type SandboxMount, type SandboxSpec } from '@zenera/neo';
+import { type Logger } from './errors.ts';
+import { type ResolvedBuild } from './image.ts';
+import type { SessionPaths } from './session.ts';
+export interface SandboxSetup {
+    pool: SandboxPool;
+    /** the resolved base spec, for `zn sandbox status` and the image pre-warm */
+    spec: SandboxSpec;
+    image: string;
+    /** the Dockerfile behind `image`, when it came from one */
+    build?: ResolvedBuild;
+    /** host side of the container's `$HOME`, created only if it is ever needed */
+    home: string;
+    /** every tree bound into the container besides the workspace itself */
+    mounts: readonly SandboxMount[];
+}
+export interface SandboxInputs {
+    config: ProjectConfig;
+    session: SessionPaths;
+    workspace: string;
+    /** the project directory, which `build:` paths are relative to */
+    root: string;
+    readOnly?: boolean;
+    /**
+     * Trees to mount besides the workspace and the home — the project's assets
+     * and its skill catalog. The same array goes to the file tools, so a path
+     * a command prints is a path `read_file` accepts.
+     */
+    mounts?: readonly SandboxMount[];
+    /** `--image` */
+    image?: string;
+    /** `--no-keys`: refuse to forward credentials, whatever the config says */
+    keys?: boolean;
+    /**
+     * Names from the project's `.env`, forwarded into the container the same
+     * way a credential is — by name, so the value stays out of the argv.
+     *
+     * They travel with the keys rather than beside them: a `.env` is where an
+     * api token lives, so `--no-keys` has to withhold it too or the flag is a
+     * promise it does not keep.
+     */
+    env?: readonly string[];
+    /** `false` overrides every `persist:` in the config, the agents' included */
+    persist?: boolean;
+}
+export declare function buildSandbox(opts: SandboxInputs): SandboxSetup;
+/**
+ * Whether anything in this project can reach a shell.
+ *
+ * Read off the *resolved* tool lists rather than off the config's selectors,
+ * because `sandbox:*`, `*` and a bare name all mean the same thing by the time
+ * the loader is done, and only one of those three is greppable.
+ */
+export declare function usesSandbox(project: AgentProject): boolean;
+/**
+ * Gets the container engine ready before the first turn rather than at the
+ * first tool call, so a missing engine costs an error instead of a round trip
+ * and half a plan. Installing or starting one is a host decision with a user
+ * attached to it, so the host supplies this; the engine only calls it.
+ */
+export type Preflight = (setup: SandboxSetup, yes?: boolean) => Promise<void>;
+/** Where the container's `$HOME` lives must exist before podman mounts it. */
+export declare function prepareHome(setup: SandboxSetup): void;
+/** Best-effort teardown: losing a container must never lose a run. */
+export declare function teardown(pool: SandboxPool, logger?: Logger): Promise<void>;
+//# sourceMappingURL=sandbox.d.ts.map

package/dist/sandbox.js

@@ -0,0 +1,199 @@
+import { DEFAULT_SANDBOX_IMAGE, GATEWAY_URL_ENV, SANDBOX_GROUP, SandboxPool, } from '@zenera/neo';
+import { mkdirSync } from 'node:fs';
+import { basename, join } from 'node:path';
+import { stderrLogger } from "./errors.js";
+import { resolveBuild } from "./image.js";
+import { credentials } from "./keys.js";
+// ---------------------------------------------------------------------------
+// The sandbox, as zen wires it
+//
+// The library takes resolved values; the config states names and numbers. This
+// is the layer between the two, and it owns the two decisions the library has
+// no business making: which host variables are worth forwarding, and where the
+// container's home directory lives.
+//
+// It lives in the session directory, which is the whole point. A session is
+// already a self-contained thing — copy the directory and its conversation,
+// memory and blobs travel with it — and a `pip install --user` that vanished
+// on close would be the only part of a session that did not. So `$HOME` is a
+// bind mount into `.data/sandbox/home`, and what the agent installs for itself
+// is still there when the session is opened again. Everything *outside* the
+// mounts is throwaway, which is what keeps a stale container from becoming a
+// second, invisible configuration.
+// ---------------------------------------------------------------------------
+/** Where the persistent home lives, inside the container. */
+const HOME = '/home/agent';
+/** Where a credential *file* is mounted, inside the container. */
+const KEY_MOUNT = '/run/zenera/keys';
+/**
+ * The credentials the run is using, in the form a container takes.
+ *
+ * Two shapes, two mechanisms. A secret is forwarded by *name* — podman reads
+ * the value from its own environment, so nothing is written into an argv that
+ * `ps` will show. A service-account file has to be present as a file, so the
+ * one file is bind-mounted read-only and the variable is rewritten to where it
+ * landed; mounting the directory it came from would drag in whatever else the
+ * user keeps beside it.
+ *
+ * This is the part of the design that gives something away, and it should be
+ * said plainly: the sandbox runs code the model wrote, and a key it can read
+ * is a key it can send. `keys: false`, or `network: none`, is the answer for a
+ * project where that is not an acceptable trade.
+ */
+function forwarded() {
+    const secrets = [];
+    const env = {};
+    const mounts = [];
+    for (const cred of credentials()) {
+        if (cred.holds === 'file') {
+            const at = `${KEY_MOUNT}/${basename(cred.value)}`;
+            mounts.push({ host: cred.value, at, readOnly: true });
+            env[cred.env] = at;
+            continue;
+        }
+        secrets.push(cred.env);
+    }
+    // Not secrets, and useless without one: a service account says which
+    // project it belongs to but never which region to call, and a gateway key
+    // says nothing of where the gateway is.
+    for (const name of ['GOOGLE_CLOUD_PROJECT', 'GOOGLE_CLOUD_LOCATION', GATEWAY_URL_ENV]) {
+        const value = process.env[name];
+        if (value) {
+            env[name] = value;
+        }
+    }
+    return { secrets, env, mounts };
+}
+export function buildSandbox(opts) {
+    // An explicit --image is an answer, so there is nothing left to build.
+    const build = opts.image ? undefined : resolveBuild(opts.root, opts.config.sandbox);
+    const base = {
+        ...(opts.config.sandbox ?? {}),
+        ...((opts.image ?? build?.tag) ? { image: opts.image ?? build?.tag } : {}),
+        ...(opts.keys === false ? { keys: false } : {}),
+        ...(opts.persist === false ? { persist: false } : {}),
+    };
+    const home = join(opts.session.data, 'sandbox', 'home');
+    const mounts = [{ host: home, at: HOME }, ...(opts.mounts ?? [])];
+    const keys = base.keys === false ? undefined : forwarded();
+    if (keys) {
+        mounts.push(...keys.mounts);
+    }
+    // Skills and assets are mounted read-only, and a python script run from a
+    // read-only directory fails on writing its own `__pycache__` — a confusing
+    // error about a file nobody asked for.
+    // `ZENERA_AGENT` tells a `zen` run by `run_command` that no person is there.
+    const extra = { HOME, PYTHONDONTWRITEBYTECODE: '1', ZENERA_AGENT: '1', ...(keys?.env ?? {}) };
+    const spec = toSpec(base, extra, secretsOf(keys?.secrets, opts.env));
+    const agents = {};
+    for (const agent of opts.config.agents) {
+        if (agent.sandbox) {
+            const merged = merge(base, agent.sandbox);
+            if (opts.persist === false) {
+                merged.persist = false;
+            }
+            // An agent that opts out gets neither the variables nor the mount,
+            // but the mount is on the pool and cannot be taken back per agent —
+            // so the variable is what actually decides, and without it the file
+            // sitting there is not a credential anything will look for.
+            const own = merged.keys === false ? undefined : keys;
+            agents[agent.name] = toSpec(merged, { HOME, PYTHONDONTWRITEBYTECODE: '1', ZENERA_AGENT: '1', ...(own?.env ?? {}) }, own && secretsOf(own.secrets, opts.env));
+        }
+    }
+    const pool = new SandboxPool({
+        ...spec,
+        agents,
+        root: opts.workspace,
+        key: opts.session.id,
+        readOnly: opts.readOnly,
+        mounts,
+    });
+    return { pool, spec, image: spec.image ?? DEFAULT_SANDBOX_IMAGE, build, home, mounts };
+}
+/**
+ * An agent's overrides on the project's block. `image` and `build` answer the
+ * same question, so naming either one drops the other: a plain spread would
+ * leave an agent's `image` sitting next to the project's `build`, and the
+ * schema forbids exactly that combination when it is written down.
+ */
+function merge(base, agent) {
+    const merged = { ...base, ...agent };
+    if (agent.image !== undefined) {
+        delete merged.build;
+    }
+    if (agent.build !== undefined) {
+        delete merged.image;
+    }
+    return merged;
+}
+/**
+ * The two sources of forwarded names, as one list: the credentials the keyring
+ * selected, and whatever the project's `.env` declares. Deduped, because the
+ * same variable named twice is the same `--env` twice.
+ *
+ * `undefined` in means keys are withheld, and the file goes with them.
+ */
+function secretsOf(secrets, env) {
+    if (!secrets) {
+        return undefined;
+    }
+    return [...new Set([...secrets, ...(env ?? [])])];
+}
+/**
+ * Config names a variable; this reads it. A name that is not set on this host
+ * is simply not forwarded — an empty string in the container is a different
+ * thing from an absent one, and tools test for absence.
+ *
+ * A name that has already been answered with a value drops off the forwarded
+ * list: `--env NAME=value` and `--env NAME` are the same variable twice, and
+ * the one that carries a value is the one that was resolved on purpose. That
+ * matters for `GOOGLE_APPLICATION_CREDENTIALS`, which is rewritten here to
+ * where the key file was mounted — a `.env` naming it must not put the host's
+ * path back, since that path does not exist inside the container.
+ */
+function toSpec(config, extra, secrets) {
+    const env = { ...extra };
+    for (const name of config.env ?? []) {
+        const value = process.env[name];
+        if (value !== undefined && value !== '') {
+            env[name] = value;
+        }
+    }
+    return {
+        image: config.image,
+        cpus: config.cpus,
+        memory: config.memory,
+        network: config.network,
+        workdir: config.workdir,
+        timeout: config.timeout,
+        hardening: config.hardening,
+        user: config.user,
+        persist: config.persist,
+        env,
+        secrets: secrets?.filter((name) => !(name in env)),
+    };
+}
+/**
+ * Whether anything in this project can reach a shell.
+ *
+ * Read off the *resolved* tool lists rather than off the config's selectors,
+ * because `sandbox:*`, `*` and a bare name all mean the same thing by the time
+ * the loader is done, and only one of those three is greppable.
+ */
+export function usesSandbox(project) {
+    return project.agents.some((a) => a.tools.some((t) => t.group === SANDBOX_GROUP));
+}
+/** Where the container's `$HOME` lives must exist before podman mounts it. */
+export function prepareHome(setup) {
+    mkdirSync(setup.home, { recursive: true });
+}
+/** Best-effort teardown: losing a container must never lose a run. */
+export async function teardown(pool, logger = stderrLogger) {
+    try {
+        await pool.dispose();
+    }
+    catch (err) {
+        logger.warn(`could not clean up the sandbox: ${err instanceof Error ? err.message : String(err)}`);
+    }
+}
+//# sourceMappingURL=sandbox.js.map