@fastagent-sh/fastagent 0.21.1 → 0.22.0

package/dist/deploy/secrets.js

@@ -1,150 +1,164 @@
 /**
- * The secret set a deployed agent needs, computed from the definition — host-neutral. Required values
- * gate every target; optional channel values travel only when configured. Only the SET command differs
- * (`fly secrets import` vs `railway variables set`). The runbooks list both classes; `--run` reads local values.
+ * The environment a deployed agent runs with — host-neutral.
  *
- * Both DIRECTIONS of the credential carry live here: the deploy-time assembly below, and the boot-time
- * seed read at the bottom. They were split across a host driver (`fly/run.ts`), which left `start`
- * — a serving path that deploys nothing, on Fly or anywhere — importing from it to boot a container.
+ * The value file (`.secrets/.env`) IS the deployed environment: every variable in it travels, on every host. What the
+ * definition declares (`defineTool`/`defineChannel`/`defineRoutine({ secrets })`, plus the model's env key) only says
+ * which of those must have a value, so a missing one stops a deploy before its first side effect instead of a boot.
  */
-import { CONTROL_TOKEN_ENV } from "../channels/control.js";
-import { CHANNEL_KINDS, channelSetup } from "../scaffold/add-channel.js";
-/** The declared channels this tool has setup metadata for. A custom channel carries its own secrets;
- *  nothing here can name them, and guessing would print a runbook line no one can act on. */
-function firstPartyChannels(channels) {
-    return channels.flatMap((channel) => CHANNEL_KINDS.includes(channel.name)
-        ? [{ kind: channel.name, ingress: channel.ingress }]
-        : []);
+import { dedupeSecrets } from "../declared-secrets.js";
+/** Is this local auth source an env-var API key (→ becomes a deploy secret) vs OAuth / stored / none? */
+export function isEnvKey(source) {
+    return source !== undefined && /^[A-Z][A-Z0-9_]*$/.test(source);
 }
 /**
- * Is this local auth source an env-var API key (→ becomes a deploy secret) vs OAuth / stored / none?
- * Positive match on the UPPER_SNAKE env-var naming shape, NOT a negative exclude of today's sentinel
- * labels: a new non-env `AuthResult.source` (e.g. `keychain`) then degrades to guidance, never a fake
- * `keychain=<value>` secret — the two modules don't couple through an exhaustive string list.
+ * Names a deployment sets on the box itself. The value file's copy of one describes THIS machine (a local state path,
+ * a port) or rides another carrier (the model rides the release manifest), so it never travels.
  */
-export function isEnvKey(source) {
-    return source !== undefined && /^[A-Z][A-Z0-9_]*$/.test(source);
+const DEPLOY_OWNED = new Set([
+    "PORT",
+    "FASTAGENT_AGENT",
+    "FASTAGENT_MODEL",
+    "FASTAGENT_STATE_DIR",
+    "FASTAGENT_SECRETS_DIR",
+    "FASTAGENT_AUTH_PATH",
+    "FASTAGENT_RELEASE_FILE",
+    "FASTAGENT_STORAGE_DIR",
+    "FASTAGENT_AGENTCORE",
+    "FASTAGENT_INGRESS_SECRET",
+    "FASTAGENT_WAKE_SECRET",
+    "FASTAGENT_DEV_WORKER",
+]);
+/** Is `name` one the deployment sets itself (see {@link DEPLOY_OWNED}), including the chunked carriers? */
+function isDeployOwned(name) {
+    return DEPLOY_OWNED.has(name) || /^FASTAGENT_(AUTH_SEED|ENV)(_\d+)?$/.test(name);
+}
+/** The value-file variables that travel: everything with a value that the deployment does not set itself. */
+function carriedValues(values) {
+    const carried = {};
+    for (const [name, value] of values)
+        if (value && !isDeployOwned(name))
+            carried[name] = value;
+    return carried;
 }
 /**
- * Secret NAMES + hints for a runbook: the model key (when local auth is an env key), discovered channel
- * secrets, and config extras. Channel metadata keeps optional values visible without presenting them as
- * deployment prerequisites. An OAuth/stored login has no env key here — it carries as
- * `FASTAGENT_AUTH_SEED` on the `--run` path (see each host's run module), not as a named runbook secret.
+ * What a runbook lists: the names that must have a value (the model's env key, every declaration — hinted by the file
+ * that declared it) and then every other variable the value file carries.
  */
-export function deploymentSecrets(modelAuth, channels, extraSecrets = []) {
+export function deploymentSecrets(modelAuth, declared, values, valueFile) {
     const secrets = [];
+    const add = (name, hint) => {
+        if (!secrets.some((s) => s.name === name))
+            secrets.push({ name, hint });
+    };
     if (isEnvKey(modelAuth))
-        secrets.push({ name: modelAuth, hint: "your model provider key", required: true });
-    for (const { kind, ingress } of firstPartyChannels(channels)) {
-        for (const e of channelSetup(kind, ingress === "long-connection" ? "websocket" : "webhook").env) {
-            secrets.push({ name: e.name, hint: e.hint, required: e.required });
-        }
-    }
-    // Dedup: a name already covered by the model key / a channel secret must not appear twice in the runbook.
-    for (const name of extraSecrets) {
-        if (!secrets.some((s) => s.name === name)) {
-            const control = name === CONTROL_TOKEN_ENV;
-            secrets.push({
-                name,
-                hint: control
-                    ? "the /control/* bearer token — mint one (uuidgen) and give the same value to callers"
-                    : "declared in fastagent.config deploy.secrets",
-                // OPTIONAL, unlike every other extra: unset, the box mints a per-boot token and still serves,
-                // and every host with a shell can read it back out of control.json. Gating would stop deploys
-                // that work today to enforce a convenience — the pre-flight warning is where that argument
-                // belongs.
-                required: !control,
-            });
-        }
-    }
+        add(modelAuth, "your model provider key");
+    for (const { name, source } of dedupeSecrets(declared))
+        add(name, `required by ${source}`);
+    for (const name of Object.keys(carriedValues(values)))
+        add(name, `from ${valueFile}`);
     return secrets;
 }
 /**
- * Assemble the secret VALUES a `--run` deploy sets on the host, from the local credential + channels —
- * pure, host-neutral (Fly sets them via `fly secrets import`, Railway via `railway variables set`), so
- * the security-sensitive key wiring is testable once. The model credential travels one of two ways: an
- * env-key auth as its own secret (value from `env`), OR an OAuth/stored login (no plaintext key) as
- * `FASTAGENT_AUTH_SEED` (base64 auth.json) which `start` materializes on first boot. `needsModelCredential`
- * (neither present) is a DISTINCT signal: its remediation is `fastagent login`, not the `.env` one that
- * `missingSecrets` (real secret NAMES with no value) carries.
+ * Assemble the VALUES a `--run` deploy sets on the host: every variable the value file carries, plus the local
+ * credential. Never minted here.
  *
- * Channel secrets come from the local env only — NEVER minted. A random mint would be wrong for a
- * human-shared secret (github's webhook secret must match the value the operator enters in the repo,
- * which a silent mint never surfaces) and would rotate every run (breaking idempotency). An absent
- * required value enters `missingSecrets`; an absent optional value is simply omitted.
+ * `values` is the selected value file, read as data — **the environment running `deploy` is not a source**. A
+ * deployment must be reproducible from what it carries, and a variable that happens to be exported on the builder is
+ * written down nowhere. CI supplies values by writing the file before running the command.
  */
 export function assembleSecrets(input) {
-    const secrets = {};
+    const secrets = carriedValues(input.values);
     const missingSecrets = [];
     let needsModelCredential = false;
     if (isEnvKey(input.modelAuth)) {
-        const v = input.env[input.modelAuth];
-        if (v)
-            secrets[input.modelAuth] = v;
-        else
-            missingSecrets.push(input.modelAuth); // an env-key name with no value — `.env` remediation fits
+        if (!secrets[input.modelAuth])
+            missingSecrets.push(input.modelAuth); // `.env` remediation fits
     }
     else if (input.authFile) {
         secrets.FASTAGENT_AUTH_SEED = input.authFile.toString("base64");
     }
     else if (input.modelKeyInDefinition) {
-        // The definition authenticates itself (models.json literal key, or a command run on the host), so it
-        // travels in the image with everything else. Gating here would be the worst kind of wrong: both
-        // remedies we print are impossible for such an agent — `fastagent login` has no flow for a custom
-        // provider, and there is no provider env key to set.
+        // The definition authenticates itself (models.json literal key, or a command run on the host), so it travels in
+        // the image with everything else.
     }
     else {
         needsModelCredential = true; // no env key, no auth.json — `fastagent login` remediation
     }
-    for (const { kind, ingress } of firstPartyChannels(input.channels)) {
-        for (const e of channelSetup(kind, ingress === "long-connection" ? "websocket" : "webhook").env) {
-            const v = input.env[e.name];
-            if (v)
-                secrets[e.name] = v; // optional channel values travel when configured
-            else if (e.required) {
-                missingSecrets.push(e.name); // operator-provided (in .env); a human-shared secret can't be minted
-            }
-        }
-    }
-    for (const name of input.extraSecrets ?? []) {
-        if (name in secrets || missingSecrets.includes(name))
-            continue; // already covered by model/channel — no dup
-        const v = input.env[name];
-        if (v)
-            secrets[name] = v;
-        // The control token is CARRIED, never gated — see {@link deploymentSecrets}: unset, the box mints
-        // one and serves; every other extra is declared as needed, so its absence is a stop.
-        else if (name !== CONTROL_TOKEN_ENV)
+    for (const { name } of dedupeSecrets(input.declared ?? [])) {
+        if (!secrets[name] && !missingSecrets.includes(name))
             missingSecrets.push(name);
     }
     return { secrets, missingSecrets, needsModelCredential };
 }
 /**
- * The bytes to seed to the auth file, or undefined to leave it alone — the pure core of `start`'s
- * FASTAGENT_AUTH_SEED materialization (the read side of {@link assembleSecrets}'s carry). ABSENT-ONLY
- * by design: a present file (a refreshed volume copy) is never overwritten by the stale seed, so a box
- * that ran its own OAuth refresh is not rolled back.
+ * The ONE refusal for declared names the deployed environment does not supply a value for — every host reaches it
+ * before its first side effect. Host-neutral because the reason is: the value file IS the deployed environment, so a
+ * name missing from it is missing from the deployment, whatever platform receives it.
  */
+export function missingValuesGate(missing, valueFile) {
+    if (missing.length === 0)
+        return undefined;
+    return (`no value for: ${missing.join(", ")} — the deployed environment is declared by ${valueFile}, and this deploy ` +
+        `reads only that file (exporting the variable here does not reach the deployment). Add them there and re-run`);
+}
+/** The bytes to seed to the auth file, or undefined to leave it alone. */
 export function authSeedBytes(seed, fileExists) {
     return !seed || fileExists ? undefined : Buffer.from(seed, "base64");
 }
 /**
- * Collect the (possibly CHUNKED) auth seed from the environment: `FASTAGENT_AUTH_SEED` plus numbered
- * continuations (`_2`, `_3`, …) concatenated in order. Hosts whose env values carry a small max
- * length (AgentCore: 2048 chars — a real OAuth auth.json's base64 exceeds it) split the seed across
- * them at deploy time; single-var hosts (Fly/Railway) never set a continuation and are unchanged.
- * Collection stops at the first absent/empty continuation — the writer fills them contiguously.
+ * Collect a (possibly CHUNKED) carrier from the environment: `<name>` plus numbered continuations (`_2`, `_3`, …)
+ * concatenated in order. A host whose env values have a length cap splits a long value this way.
  */
-export function collectAuthSeed(env) {
-    const first = env.FASTAGENT_AUTH_SEED;
+function collectChunked(env, name) {
+    const first = env[name];
     if (!first)
         return undefined;
-    let seed = first;
+    let value = first;
     for (let i = 2;; i++) {
-        const part = env[`FASTAGENT_AUTH_SEED_${i}`];
+        const part = env[`${name}_${i}`];
         if (!part)
             break;
-        seed += part;
+        value += part;
     }
-    return seed;
+    return value;
+}
+/** `FASTAGENT_AUTH_SEED` (+ `_2`, …): the base64 auth.json a deploy carries. */
+export function collectAuthSeed(env) {
+    return collectChunked(env, "FASTAGENT_AUTH_SEED");
+}
+/**
+ * `FASTAGENT_ENV` (+ `_2`, …): the carried variables as ONE base64 JSON object, for a host whose deployment artifact
+ * must not depend on which names the value file holds (AgentCore's template is committed and gated on drift). The
+ * inverse of {@link encodeCarriedEnv}.
+ */
+function collectCarriedEnv(env) {
+    const encoded = collectChunked(env, "FASTAGENT_ENV");
+    if (encoded === undefined)
+        return undefined;
+    const parsed = JSON.parse(Buffer.from(encoded, "base64").toString("utf8"));
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+        throw new Error("FASTAGENT_ENV is not an object of variables — redeploy to regenerate it");
+    }
+    const carried = {};
+    for (const [name, value] of Object.entries(parsed)) {
+        if (typeof value !== "string")
+            throw new Error(`FASTAGENT_ENV: ${name} is not a string — redeploy to regenerate it`);
+        carried[name] = value;
+    }
+    return carried;
+}
+/**
+ * Expand `FASTAGENT_ENV` into the process environment — what `start` does first on a host that carries the value file
+ * that way. The platform's own variables still win, as they do over a value file anywhere.
+ */
+export function applyCarriedEnv(env = process.env) {
+    const carried = collectCarriedEnv(env);
+    if (carried)
+        for (const [name, value] of Object.entries(carried))
+            if (!(name in env))
+                env[name] = value;
+}
+/** The carried variables as the base64 JSON {@link collectCarriedEnv} reads back; empty when nothing travels. */
+export function encodeCarriedEnv(carried) {
+    return Object.keys(carried).length === 0 ? "" : Buffer.from(JSON.stringify(carried), "utf8").toString("base64");
 }

package/dist/deploy/workspace.d.ts

@@ -0,0 +1,50 @@
+export declare const RELEASE_FILE = "fastagent.release.json";
+export interface DeploymentRelease {
+    version: 1;
+    id: string;
+    agent: string;
+    /**
+     * The model this release resolved, when the deployed environment's value file named it (`config.model` needs
+     * nothing here — the config ships in the image too). NON-CREDENTIAL configuration only: the manifest travels
+     * inside the image, which is readable by anyone who can pull it, and it is rebuilt on every deploy — both are the
+     * opposite of what a credential needs (see docs/design/configuration.md §8).
+     */
+    model?: string;
+}
+/** The manifest names a directory the container joins onto the workspace root, so the spelling is
+ *  constrained. `deploy` asks BEFORE generating artifacts — a name `init` accepts but this rejects
+ *  is the author's directory name, not a corrupt manifest. */
+export declare function isReleaseAgentName(name: string): boolean;
+export declare function parseDeploymentRelease(raw: string): DeploymentRelease;
+/**
+ * Project a release's own declarations into the environment it was resolved FOR — the receiving half of the model
+ * chain, run by `prepareStartWorkspace` BEFORE the workspace's `.env` is read (so either source outranks a value
+ * edited on the box).
+ *
+ * `||=`: a variable the platform already holds still wins, because the deployment declares only the half of this
+ * environment it can. The log names whichever source actually won — the remedies differ, and a redeploy does
+ * nothing at all to a platform-set variable.
+ */
+export declare function applyReleaseEnv(release: DeploymentRelease, env?: NodeJS.ProcessEnv): void;
+/** A `provider/modelId` spec. The id itself may carry `/` and `~` (`baseten/zai-org/GLM-5.3`, openrouter aliases);
+ *  resolution only ever splits on the first slash. */
+export declare function isModelSpec(value: string): boolean;
+/** Call while holding the workspace lease. No deployment replaces existing work outside the definition. */
+export declare function applyDeploymentRelease(source: string, root: string, release: DeploymentRelease): Promise<string>;
+/** An unmounted directory must never look like a new disk. */
+export declare function assertStorageMounted(root: string, paths?: string[]): Promise<void>;
+/** `waitSeconds` covers a restart overlapping the old process's exit; a test that wants the refusal
+ *  passes a short one rather than waiting out the deployment default. */
+export declare function leaseDeployment(metadata: string, waitSeconds?: number): Promise<() => Promise<void>>;
+/**
+ * Prepare the deployed workspace and return its path.
+ *
+ * The lease is NOT returned: it stays held for the process lifetime, because channel activation can
+ * start background writers that `close()` does not drain. The kernel drops it when the process exits.
+ */
+export declare function prepareDeployment(source: string, root: string, release: DeploymentRelease): Promise<string>;
+/**
+ * Install the deployed agent's dependencies into the storage when it has no installed CLI yet (a fresh volume), or
+ * when an earlier install died part-way — its `installing` marker is still there, so the next boot redoes it.
+ */
+export declare function installAgentDependencies(root: string, agentDir: string): Promise<void>;

package/dist/deploy/workspace.js

@@ -0,0 +1,197 @@
+/** Deployment-owned initialization; the workspace itself belongs to the running agent. */
+import { cp, lstat, mkdir, readFile, rename, rm } from "node:fs/promises";
+import { join, resolve } from "node:path";
+import { spawn } from "node:child_process";
+import { closeSync, openSync } from "node:fs";
+import { once } from "node:events";
+import { writeFileAtomic } from "../atomic-write.js";
+import { log } from "../log.js";
+import { exists } from "../paths.js";
+import { detectRuntime, readPackageJson } from "../runtime.js";
+export const RELEASE_FILE = "fastagent.release.json";
+/** The deployment's own bookkeeping on the storage: the lease, the release journal, the install marker. */
+const deploymentMeta = (root) => join(root, ".deployment");
+/** The manifest names a directory the container joins onto the workspace root, so the spelling is
+ *  constrained. `deploy` asks BEFORE generating artifacts — a name `init` accepts but this rejects
+ *  is the author's directory name, not a corrupt manifest. */
+export function isReleaseAgentName(name) {
+    return /^[a-zA-Z0-9_-]+$/.test(name);
+}
+export function parseDeploymentRelease(raw) {
+    const r = JSON.parse(raw);
+    if (r?.version !== 1 ||
+        typeof r.id !== "string" ||
+        !r.id ||
+        typeof r.agent !== "string" ||
+        !isReleaseAgentName(r.agent) ||
+        (r.model !== undefined && !isModelSpec(r.model))) {
+        throw new Error("invalid deployment release manifest");
+    }
+    return r;
+}
+/**
+ * Project a release's own declarations into the environment it was resolved FOR — the receiving half of the model
+ * chain, run by `prepareStartWorkspace` BEFORE the workspace's `.env` is read (so either source outranks a value
+ * edited on the box).
+ *
+ * `||=`: a variable the platform already holds still wins, because the deployment declares only the half of this
+ * environment it can. The log names whichever source actually won — the remedies differ, and a redeploy does
+ * nothing at all to a platform-set variable.
+ */
+export function applyReleaseEnv(release, env = process.env) {
+    const fromPlatform = env.FASTAGENT_MODEL;
+    if (release.model && !fromPlatform)
+        env.FASTAGENT_MODEL = release.model;
+    const effective = env.FASTAGENT_MODEL;
+    if (!effective)
+        return;
+    log.info(`[fastagent] model ${effective} — from ${fromPlatform
+        ? `a FASTAGENT_MODEL already set in this environment${release.model ? ", which outranks the release manifest" : ""}`
+        : "the release manifest (redeploy to change it)"}; editing FASTAGENT_MODEL in this workspace's .env does not override it`);
+}
+/** A `provider/modelId` spec. The id itself may carry `/` and `~` (`baseten/zai-org/GLM-5.3`, openrouter aliases);
+ *  resolution only ever splits on the first slash. */
+export function isModelSpec(value) {
+    return /^\S+\/\S+$/.test(value);
+}
+/** A completed staging tree is published before its journal; readers start only after recovery. */
+async function finishRelease(root, pending) {
+    const meta = deploymentMeta(root), staged = join(meta, "staged"), previous = join(meta, "previous");
+    const target = pending.initial ? join(root, "base") : join(root, "base", pending.release.agent);
+    if (await exists(staged)) {
+        if (await exists(target)) {
+            if (pending.initial || (await exists(previous)))
+                throw new Error(`deployment recovery conflict at ${target}`);
+            await rename(target, previous);
+        }
+        await rename(staged, target);
+    }
+    else if (!(await exists(target))) {
+        throw new Error(`deployment recovery has neither staged nor active content: ${target}`);
+    }
+    writeFileAtomic(join(meta, "applied.json"), JSON.stringify(pending.release));
+    await rm(previous, { recursive: true, force: true });
+    await rm(join(meta, "pending.json"));
+}
+/** Call while holding the workspace lease. No deployment replaces existing work outside the definition. */
+export async function applyDeploymentRelease(source, root, release) {
+    const meta = deploymentMeta(root), staged = join(meta, "staged"), pendingPath = join(meta, "pending.json");
+    await mkdir(meta, { recursive: true });
+    if (await exists(pendingPath)) {
+        const pending = JSON.parse(await readFile(pendingPath, "utf8"));
+        pending.release = parseDeploymentRelease(JSON.stringify(pending.release));
+        if (typeof pending.initial !== "boolean")
+            throw new Error("invalid pending deployment journal");
+        await finishRelease(root, pending);
+    }
+    const appliedPath = join(meta, "applied.json");
+    const applied = (await exists(appliedPath)) ? parseDeploymentRelease(await readFile(appliedPath, "utf8")) : undefined;
+    const workspace = join(root, "base");
+    if (applied?.agent !== undefined && applied.agent !== release.agent) {
+        throw new Error(`deployment selects ${release.agent}, but this workspace belongs to ${applied.agent}`);
+    }
+    // Logged on BOTH paths: rebuilding an image without regenerating the manifest keeps the id, and a
+    // deployment that silently kept the old definition looks identical to one that took the new one.
+    if (applied?.id === release.id) {
+        log.info(`[fastagent] release ${release.id} is already applied — keeping the workspace's definition`);
+        return workspace;
+    }
+    const initial = applied === undefined;
+    if (initial && (await exists(workspace)))
+        throw new Error(`refusing to initialize over an existing unowned workspace: ${workspace}`);
+    const definition = join(source, release.agent);
+    if (!(await exists(definition)) || !(await lstat(definition)).isDirectory())
+        throw new Error(`the release must contain its agent directory: ${definition}`);
+    log.info(initial
+        ? `[fastagent] seeding the workspace from release ${release.id}`
+        : `[fastagent] publishing release ${release.id} over base/${release.agent}`);
+    await rm(staged, { recursive: true, force: true });
+    await cp(initial ? source : join(source, release.agent), staged, { recursive: true, verbatimSymlinks: true });
+    const pending = { release, initial };
+    writeFileAtomic(pendingPath, JSON.stringify(pending));
+    await finishRelease(root, pending);
+    return workspace;
+}
+async function mountedPaths() {
+    const mounts = await readFile("/proc/self/mountinfo", "utf8");
+    return mounts
+        .split("\n")
+        .map((line) => line
+        .split(" ")[4]
+        ?.replace(/\\([0-7]{3})/g, (_, octal) => String.fromCharCode(Number.parseInt(octal, 8))))
+        .filter((path) => path !== undefined);
+}
+/** An unmounted directory must never look like a new disk. */
+export async function assertStorageMounted(root, paths) {
+    if (!(paths ?? (await mountedPaths())).includes(resolve(root)))
+        throw new Error(`persistent storage is not mounted at ${root}`);
+}
+/** `waitSeconds` covers a restart overlapping the old process's exit; a test that wants the refusal
+ *  passes a short one rather than waiting out the deployment default. */
+export async function leaseDeployment(metadata, waitSeconds = 35) {
+    // flock locks the shared open-file description. The parent's raw fd survives GC and closes at exit.
+    // Never unlink this inode: another starter may already have it open.
+    const fd = openSync(join(metadata, "lock"), "a", 0o600);
+    try {
+        const child = spawn("flock", ["--exclusive", "--wait", String(waitSeconds), "3"], {
+            stdio: ["ignore", "ignore", "pipe", fd],
+        });
+        let stderr = "";
+        child.stderr.setEncoding("utf8").on("data", (chunk) => {
+            stderr += chunk;
+        });
+        const [code, signal] = await once(child, "close");
+        if (code !== 0)
+            throw new Error(`could not acquire workspace lease at ${metadata}: flock ${signal ?? code} ${stderr.trim()}`);
+        return async () => {
+            closeSync(fd);
+        };
+    }
+    catch (error) {
+        closeSync(fd);
+        // A custom base image without util-linux fails every boot; the bare spawn error names neither
+        // the binary nor why a lease needs one.
+        if (error.code === "ENOENT")
+            throw new Error(`the deployed workspace lease needs the \`flock\` binary (util-linux): ${String(error)}`);
+        throw error;
+    }
+}
+/**
+ * Prepare the deployed workspace and return its path.
+ *
+ * The lease is NOT returned: it stays held for the process lifetime, because channel activation can
+ * start background writers that `close()` does not drain. The kernel drops it when the process exits.
+ */
+export async function prepareDeployment(source, root, release) {
+    await assertStorageMounted(root);
+    const meta = deploymentMeta(root);
+    await mkdir(meta, { recursive: true });
+    const unlock = await leaseDeployment(meta);
+    try {
+        return await applyDeploymentRelease(source, root, release);
+    }
+    catch (error) {
+        await unlock();
+        throw error;
+    }
+}
+/**
+ * Install the deployed agent's dependencies into the storage when it has no installed CLI yet (a fresh volume), or
+ * when an earlier install died part-way — its `installing` marker is still there, so the next boot redoes it.
+ */
+export async function installAgentDependencies(root, agentDir) {
+    const installing = join(deploymentMeta(root), "installing");
+    // A failed install can leave the CLI link in place before its dependencies are complete.
+    if ((await exists(installing)) || !(await exists(join(agentDir, "node_modules/.bin/fastagent")))) {
+        const { runtime, hasLockfile } = detectRuntime(agentDir, await readPackageJson(agentDir));
+        const args = runtime === "bun" ? ["install", ...(hasLockfile ? ["--frozen-lockfile"] : [])] : [hasLockfile ? "ci" : "install"];
+        writeFileAtomic(installing, "");
+        log.info(`[fastagent] installing the agent's dependencies (${runtime} ${args.join(" ")})…`);
+        // stdio inherited: a five-minute install with no output reads as a hang, and the default 1 MB capture would
+        // kill a noisy one outright.
+        const [code, signal] = (await once(spawn(runtime === "bun" ? "bun" : "npm", args, { cwd: agentDir, stdio: "inherit" }), "exit"));
+        if (code !== 0)
+            throw new Error(`dependency install failed (${signal ?? `exit ${code}`})`);
+        await rm(installing);
+    }
+}

package/dist/dev-supervisor.d.ts

@@ -1,13 +1,5 @@
 import { type ResolvedPlacement } from "./paths.ts";
-/**
- * chokidar `ignored` matcher for the narrow watch scope (true = ignore), rooted at the AGENT DIR. When
- * the agent sits INSIDE the workspace that means the surrounding tree never triggers a restart at all;
- * when the agent IS the workspace the root is that tree, and the allowlist below is what keeps the
- * author's own files out of scope. Ignoring a directory prunes the whole subtree, so everything outside it —
- * `.state/` machine state, node_modules, .git, and any file/dir the agent writes as work product —
- * costs no watchers and triggers no restarts. Helper code imported from OUTSIDE tools//channels/ is
- * out of scope by design (keep it under tools/, or restart manually) — the startup log names the set.
- */
+/** chokidar `ignored` matcher for the narrow watch scope (true = ignore), rooted at the AGENT DIR. */
 export declare function devWatchIgnored(root: string, envFile: string): (path: string) => boolean;
 /** Spawn the dev worker and restart it on agent-dir edits; supervise its lifecycle until the process exits. */
 export declare function runDevSupervisor(placement: ResolvedPlacement, options?: {