@fastagent-sh/fastagent 0.24.4 → 0.26.0

package/dist/dev-supervisor.d.ts

@@ -1,7 +1,16 @@
-import { type ResolvedPlacement } from "./paths.ts";
 /** 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;
+/**
+ * In the dev worker: on the supervisor's `restart`, wait until no turn runs (`activeWork`, which every leased session
+ * counts), then `stop`. Bounded by `limitMs`, after which it stops anyway and says it cut work off: a chat that
+ * keeps the worker busy must not hold an edit back forever. A second `restart` while waiting is the same restart.
+ */
+export declare function listenForRestart(stop: () => void, options?: {
+    busy?: () => number;
+    limitMs?: number;
+    pollMs?: number;
+}): (message: unknown) => void;
 /** 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?: {
+export declare function runDevSupervisor(agentDir: string, options?: {
     tunnel?: boolean;
 }): Promise<void>;

package/dist/dev-supervisor.js

@@ -5,16 +5,16 @@
 import { spawn } from "node:child_process";
 import { relative, sep } from "node:path";
 import { watch as watchTree } from "chokidar";
-import { AGENT_CONFIG_FILE, AGENT_MODEL_CATALOG_FILE, AGENT_MODELS_FILE, resolveStateRoot, isUnderDir, } from "./paths.js";
-import { dotEnvPath } from "./env.js";
+import { AGENT_CONFIG_FILE, CONTEXT_FILE, LOCAL_CONTEXT_FILE, resolveStateRoot, isUnderDir } from "./paths.js";
+import { dotEnvPath } from "./value-file.js";
 import { log } from "./log.js";
 import { openExternalUrl } from "./open-url.js";
 import { declaredChannels } from "./channels/discover.js";
+import { activeWork } from "./channels/busy.js";
 import { announceWebhooks, startCloudflareTunnel } from "./tunnel.js";
-/** What the dev watcher restarts on (agent-dir-relative): the process-bound code inputs only. */
-/** The agent-dir directories loaded ONCE per worker: a restart is their only re-read. */
-const CODE_INPUT_DIRS = ["tools", "channels", "routines", "extensions"];
-const WATCHED_HINT = `${CODE_INPUT_DIRS.map((dir) => `${dir}/`).join(", ")}, package.json, fastagent.config.ts, models.json, models-store.json, .secrets/.env`;
+/** The agent's code (its tools, extensions, channels and schedules), loaded ONCE per worker: a restart is its only re-read. */
+const CODE_DIR = "src";
+const WATCHED_HINT = `${CODE_DIR}/, package.json, fastagent.config.ts, context.json, context.local.json, .secrets/.env`;
 /** chokidar `ignored` matcher for the narrow watch scope (true = ignore), rooted at the AGENT DIR. */
 export function devWatchIgnored(root, envFile) {
     // The `.env` is allow-listed by its RESOLVED path, not by the `.secrets` name.
@@ -23,21 +23,14 @@ export function devWatchIgnored(root, envFile) {
         if (path === root)
             return false; // the root itself must not be pruned
         const rel = relative(root, path);
-        // Code inputs at the agent dir root: config, package.json, and the dirs loaded once per worker (a restart is
+        // Code inputs at the agent dir root: config, package.json, and the code loaded once per worker (a restart is
         // their only re-read).
-        if (rel === AGENT_CONFIG_FILE)
+        if (rel === AGENT_CONFIG_FILE || rel === CONTEXT_FILE || rel === LOCAL_CONTEXT_FILE)
             return false;
         if (rel === "package.json")
             return false;
-        // models.json is read ONCE per worker (agentModels' snapshot, which every session's runtime is built from), so an
-        // edit needs a restart like any other code input.
-        if (rel === AGENT_MODELS_FILE)
-            return false;
-        // So is the model catalog: a `models --refresh` during `dev` restarts the worker onto the new models.
-        if (rel === AGENT_MODEL_CATALOG_FILE)
-            return false;
         const segments = rel.split(sep);
-        if (CODE_INPUT_DIRS.includes(segments[0]))
+        if (segments[0] === CODE_DIR)
             return false;
         // The `.env` restarts too (credentials are process-bound).
         if (segments.length <= envRel.length && segments.every((seg, i) => seg === envRel[i]))
@@ -45,9 +38,37 @@ export function devWatchIgnored(root, envFile) {
         return true;
     };
 }
+/** How long a dev worker waits for its running turns before it restarts anyway. */
+const DEV_RESTART_WAIT_MS = 10 * 60_000;
+/**
+ * In the dev worker: on the supervisor's `restart`, wait until no turn runs (`activeWork`, which every leased session
+ * counts), then `stop`. Bounded by `limitMs`, after which it stops anyway and says it cut work off: a chat that
+ * keeps the worker busy must not hold an edit back forever. A second `restart` while waiting is the same restart.
+ */
+export function listenForRestart(stop, options = {}) {
+    const { busy = activeWork, limitMs = DEV_RESTART_WAIT_MS, pollMs = 100 } = options;
+    let restarting = false;
+    return (message) => {
+        if (message?.type !== "restart" || restarting)
+            return;
+        restarting = true;
+        void (async () => {
+            // `busy` counts pieces of work (a channel turn is counted queued and again leased), not turns, so no number.
+            if (busy() > 0)
+                log.info("[fastagent] restarting once the turns running now finish");
+            const deadline = Date.now() + limitMs;
+            while (busy() > 0 && Date.now() < deadline)
+                await new Promise((resolve) => setTimeout(resolve, pollMs));
+            if (busy() > 0) {
+                log.warn(`[fastagent] restarting with work still running after ${limitMs / 60_000} minutes: it is cut off`);
+            }
+            stop();
+        })();
+    };
+}
 /** Spawn the dev worker and restart it on agent-dir edits; supervise its lifecycle until the process exits. */
-export async function runDevSupervisor(placement, options = {}) {
-    // The placement arrives RESOLVED from the command (which already routed its refusal through failStartup).
+export async function runDevSupervisor(agentDir, options = {}) {
+    // The agent directory arrives RESOLVED from the command (which already routed its refusal through failStartup).
     let worker;
     let reloadPending = false;
     let everServed = false; // has any worker successfully bound (sent `ready`) yet?
@@ -72,9 +93,9 @@ export async function runDevSupervisor(placement, options = {}) {
                 void startCloudflareTunnel(m.port).then((t) => {
                     if (t) {
                         tunnel = t;
-                        void announceWebhooks(placement.agentDir, t.url, declaredChannels(m.routeChannels ?? []), {
+                        void announceWebhooks(agentDir, t.url, declaredChannels(m.routeChannels ?? []), {
                             openUrl: openExternalUrl,
-                            stateRoot: resolveStateRoot(placement.agentDir),
+                            stateRoot: resolveStateRoot(agentDir),
                         });
                     }
                 });
@@ -90,7 +111,7 @@ export async function runDevSupervisor(placement, options = {}) {
             }
             else if (!everServed) {
                 // Failed BEFORE ever serving — a non-editable startup failure (bad flag, EADDRINUSE, broken initial
-                // workspace) that saving cannot fix.
+                // definition) that saving cannot fix.
                 process.exit(code ?? 1);
             }
             else {
@@ -103,26 +124,30 @@ export async function runDevSupervisor(placement, options = {}) {
         log.info(`[fastagent] change detected — restarting…`);
         if (worker) {
             reloadPending = true;
-            worker.kill("SIGTERM"); // the exit handler respawns once the port is released
+            // The worker stops once its running turns finish (listenForRestart); the exit handler respawns it then. A turn
+            // that wrote the very file that changed is not cut off by its own edit. A worker whose channel is already
+            // closed is exiting: its exit handler respawns it, and `send` would throw ERR_IPC_CHANNEL_CLOSED.
+            if (worker.connected)
+                worker.send({ type: "restart" });
         }
         else {
             spawnWorker(); // worker was down (broken edit) — retry now
         }
     };
     // chokidar gives reliable cross-platform recursion + structural ignore that native fs.watch cannot.
-    const watcher = watchTree(placement.agentDir, {
+    const watcher = watchTree(agentDir, {
         ignoreInitial: true, // the startup scan is not a change
-        ignored: devWatchIgnored(placement.agentDir, dotEnvPath(placement.agentDir)),
+        ignored: devWatchIgnored(agentDir, dotEnvPath(agentDir)),
     });
     watcher.on("all", () => {
         clearTimeout(timer);
         timer = setTimeout(triggerReload, 200);
     });
     watcher.on("error", (error) => log.warn(`[fastagent] file watching error (${error.message}); some edits may need a manual restart`));
-    log.info(`[fastagent] watching ${WATCHED_HINT} — code edits restart the dev worker (--no-watch to disable); AGENTS.md/SYSTEM.md/APPEND_SYSTEM.md/skills/prompts edits go live next turn without a restart`);
+    log.info(`[fastagent] watching ${WATCHED_HINT} — code edits restart the dev worker (--no-watch to disable); SYSTEM.md, AGENTS.md, skills/ and prompts/ go live without a restart`);
     // FASTAGENT_SECRETS_DIR can move the `.env` OUT of the agent dir entirely.
-    if (!isUnderDir(dotEnvPath(placement.agentDir), placement.agentDir)) {
-        log.warn(`[fastagent] .env lives outside the agent dir (FASTAGENT_SECRETS_DIR → ${dotEnvPath(placement.agentDir)}) — it is NOT watched; restart dev after editing it`);
+    if (!isUnderDir(dotEnvPath(agentDir), agentDir)) {
+        log.warn(`[fastagent] .env lives outside the agent dir (FASTAGENT_SECRETS_DIR → ${dotEnvPath(agentDir)}) — it is NOT watched; restart dev after editing it`);
     }
     const shutdown = () => {
         worker?.kill("SIGTERM");

package/dist/effect-port.d.ts

@@ -1,8 +1,8 @@
 /**
  * The ONE crossing between this codebase's Promise-shaped ports and Effect execution.
  *
- * The ports are everywhere and none of them are ours to change: the SPEC fixes `Agent.invoke` as an
- * AsyncIterable and `SessionControl` as Promises, pi's SDK is Promise-based, every platform client
+ * The ports are everywhere and none of them are ours to change: the Agent API fixes its streams as
+ * AsyncIterables and its other operations as Promises, pi's SDK is Promise-based, every platform client
  * is `fetch`, and so is the filesystem. Two properties have to hold at each crossing:
  *
  *  1. INTERRUPTION MUST JOIN. A Promise exposes no abort hook, so cancelling the fiber that awaits
@@ -12,11 +12,11 @@
  *     pending promise to settle before releasing, and abort first when the port gives us a door.
  *     {@link port} is the explicit opt-out, for work a caller may walk away from — so a call site
  *     holding a lease, a session or any other resource must not reach for it.
- *  2. THE CAUSE SURVIVES. Retry classification (`turn-kit.classifyRetryable`), the channels'
+ *  2. THE CAUSE SURVIVES. Retry classification (`messages.ts` `thrownFailure`), the channels'
  *     platform error types and every operator-facing message read the ORIGINAL error, so the
  *     wrapper carries it verbatim and {@link portError} is how a caller gets it back.
  *
- * The channel kit, the pi engine, the AgentCore runtime and the scheduler all cross through here, so each rule is
+ * The channel kit, the pi harness, the AgentCore runtime and the scheduler all cross through here, so each rule is
  * written once.
  *
  * What is NOT here is a policy: whether a failure rejects a request, is logged, or ends a turn stays

package/dist/effect-port.js

@@ -1,8 +1,8 @@
 /**
  * The ONE crossing between this codebase's Promise-shaped ports and Effect execution.
  *
- * The ports are everywhere and none of them are ours to change: the SPEC fixes `Agent.invoke` as an
- * AsyncIterable and `SessionControl` as Promises, pi's SDK is Promise-based, every platform client
+ * The ports are everywhere and none of them are ours to change: the Agent API fixes its streams as
+ * AsyncIterables and its other operations as Promises, pi's SDK is Promise-based, every platform client
  * is `fetch`, and so is the filesystem. Two properties have to hold at each crossing:
  *
  *  1. INTERRUPTION MUST JOIN. A Promise exposes no abort hook, so cancelling the fiber that awaits
@@ -12,11 +12,11 @@
  *     pending promise to settle before releasing, and abort first when the port gives us a door.
  *     {@link port} is the explicit opt-out, for work a caller may walk away from — so a call site
  *     holding a lease, a session or any other resource must not reach for it.
- *  2. THE CAUSE SURVIVES. Retry classification (`turn-kit.classifyRetryable`), the channels'
+ *  2. THE CAUSE SURVIVES. Retry classification (`messages.ts` `thrownFailure`), the channels'
  *     platform error types and every operator-facing message read the ORIGINAL error, so the
  *     wrapper carries it verbatim and {@link portError} is how a caller gets it back.
  *
- * The channel kit, the pi engine, the AgentCore runtime and the scheduler all cross through here, so each rule is
+ * The channel kit, the pi harness, the AgentCore runtime and the scheduler all cross through here, so each rule is
  * written once.
  *
  * What is NOT here is a policy: whether a failure rejects a request, is logged, or ends a turn stays

package/dist/env.d.ts

@@ -4,19 +4,6 @@
  * occurrence wins ({@link parseEnvContent}).
  */
 export declare function applyEnvValues(values: ReadonlyMap<string, string>): void;
-/** Parse .env content into key → value (the dialect above; last occurrence of a key wins). */
-export declare function parseEnvContent(content: string): Map<string, string>;
-/**
- * READ a value file without entering it: the values as data, never `process.env`. This is how code reasons about an
- * environment OTHER than its own — `deploy` resolves configuration in the environment being deployed, which this
- * file declares, and merging it into the running process would put the two environments in one bag. A missing file
- * is no values, which is normal.
- */
-export declare function loadEnvValues(file: string): Map<string, string>;
-/** The agent's `.env` file: `<resolved secrets dir>/.env`. */
-export declare function dotEnvPath(agentDir: string, env?: NodeJS.ProcessEnv): string;
-/** The committable template: `<agentDir>/.secrets/.env.example`. */
-export declare function envExamplePath(agentDir: string): string;
 /**
  * ENTER an agent directory's runtime environment: its `.env` becomes `process.env`, and this process's outbound fetch
  * follows whatever proxy that (or the ambient environment) declares.

package/dist/env.js

@@ -2,7 +2,7 @@ import { readFileSync, existsSync } from "node:fs";
 import { join } from "node:path";
 import { log } from "./log.js";
 import { installProxyFetch } from "./proxy.js";
-import { SECRETS_DIRNAME, resolveSecretsDir } from "./paths.js";
+import { dotEnvPath, loadEnvValues, parseEnvContent } from "./value-file.js";
 /**
  * Write parsed values into `process.env`, matching Node's `--env-file` / `process.loadEnvFile` precedence on BOTH
  * axes (verified against Node in test/env.test.ts): a real env var wins over the file, and within the file the last
@@ -13,49 +13,6 @@ export function applyEnvValues(values) {
         if (!(key in process.env))
             process.env[key] = value;
 }
-/** Parse .env content into key → value (the dialect above; last occurrence of a key wins). */
-export function parseEnvContent(content) {
-    const parsed = new Map();
-    for (const raw of content.split("\n")) {
-        const line = raw.trim();
-        if (!line || line.startsWith("#"))
-            continue;
-        const eq = line.indexOf("=");
-        if (eq < 1)
-            continue; // no `=`, or an empty key
-        const key = line.slice(0, eq).trim();
-        let value = line.slice(eq + 1).trim();
-        const quote = value[0];
-        if ((quote === '"' || quote === "'") && value.at(-1) === quote)
-            value = value.slice(1, -1);
-        parsed.set(key, value); // in-file: last occurrence wins (Map overwrite)
-    }
-    return parsed;
-}
-/**
- * READ a value file without entering it: the values as data, never `process.env`. This is how code reasons about an
- * environment OTHER than its own — `deploy` resolves configuration in the environment being deployed, which this
- * file declares, and merging it into the running process would put the two environments in one bag. A missing file
- * is no values, which is normal.
- */
-export function loadEnvValues(file) {
-    try {
-        return parseEnvContent(readFileSync(file, "utf8"));
-    }
-    catch (error) {
-        if (error.code === "ENOENT")
-            return new Map();
-        throw error;
-    }
-}
-/** The agent's `.env` file: `<resolved secrets dir>/.env`. */
-export function dotEnvPath(agentDir, env = process.env) {
-    return join(resolveSecretsDir(agentDir, env), ".env");
-}
-/** The committable template: `<agentDir>/.secrets/.env.example`. */
-export function envExamplePath(agentDir) {
-    return join(agentDir, SECRETS_DIRNAME, ".env.example");
-}
 /**
  * ENTER an agent directory's runtime environment: its `.env` becomes `process.env`, and this process's outbound fetch
  * follows whatever proxy that (or the ambient environment) declares.

package/dist/environment/apt.d.ts

@@ -0,0 +1,4 @@
+/** The packages of `names` this machine does not have, or undefined when it cannot tell (not Debian, or no dpkg). */
+export declare function missingAptPackages(names: readonly string[], debian?: boolean): string[] | undefined;
+/** What to tell whoever runs the agent here, with the command that installs them. */
+export declare function aptAdvice(missing: readonly string[]): string;

package/dist/environment/apt.js

@@ -0,0 +1,32 @@
+/**
+ * The apt packages an environment declares, on THIS machine: the image installs them, and a machine that runs the agent
+ * locally supplies its own. Only Debian and Ubuntu can be asked (dpkg); elsewhere nothing is said, and FastAgent never
+ * runs apt itself.
+ */
+import { spawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
+/** The packages of `names` this machine does not have, or undefined when it cannot tell (not Debian, or no dpkg). */
+export function missingAptPackages(names, debian = existsSync("/etc/debian_version")) {
+    if (!debian)
+        return undefined;
+    if (names.length === 0)
+        return [];
+    // dpkg-query exits 1 when a name is unknown to it; the names it does know are still printed.
+    // biome-ignore lint/suspicious/noTemplateCurlyInString: dpkg-query's own format, not a template
+    const result = spawnSync("dpkg-query", ["-W", "-f=${Package} ${db:Status-Status}\n", ...names], { encoding: "utf8" });
+    // A Debian-based image without dpkg cannot tell, which is what undefined says; anything else is a failure.
+    if (result.error?.code === "ENOENT")
+        return undefined;
+    if (result.error)
+        throw new Error(`dpkg-query could not run: ${result.error.message}`);
+    const installed = new Set(result.stdout
+        .split("\n")
+        .filter((line) => line.endsWith(" installed"))
+        .map((line) => line.split(" ")[0]));
+    return names.filter((name) => !installed.has(name));
+}
+/** What to tell whoever runs the agent here, with the command that installs them. */
+export function aptAdvice(missing) {
+    return (`the image installs apt packages this machine does not have: ${missing.join(", ")} — ` +
+        `\`sudo apt-get install -y ${missing.join(" ")}\``);
+}

package/dist/environment/declare.d.ts

@@ -0,0 +1,59 @@
+/**
+ * WHAT AN AGENT'S ENVIRONMENT IS: the `environment` of `context.json`, read and refused in ONE place, and the backends a
+ * package may install from. FastAgent's own format, with mise underneath: `packages` (mise's tool names, each with a
+ * version), `aptPackages` (Debian packages the image installs) and `variables` (the environment variables its commands
+ * read, by name: their values come from the environment, as a tool's secrets do). Pure: installing it is mise.ts's.
+ * docs/design/agent-service.md §4 is the rule.
+ */
+import { type DeclaredSecret } from "../declared-secrets.ts";
+/** An agent's environment, as declared. */
+export interface DeclaredEnvironment {
+    /** Package → version: `"latest"`, a prefix (`"2"`) or an exact version. */
+    packages: Record<string, string>;
+    /** Debian packages the image installs. */
+    aptPackages: string[];
+    /** Environment variable name → what it is for. Every one is required; its value comes from the environment. */
+    variables: Record<string, DeclaredVariable>;
+}
+/** One declared environment variable, as `context.json` holds it. */
+interface DeclaredVariable {
+    /** What it is for, said where the variable is reported: runbooks, `info`, `fastagent env list`. */
+    description: string;
+}
+/** Read the `environment` of `context.json` (undefined is none). Every refusal names what it refuses. */
+export declare function declareEnvironment(raw: unknown): DeclaredEnvironment | undefined;
+/** The variables `environment` declares, as the declarations every serving path and `deploy` require. */
+export declare function declaredVariables(environment: DeclaredEnvironment | undefined): DeclaredSecret[];
+/** The backend a package is written with (`npm:prettier` is npm), or undefined for a registry name, which mise resolves. */
+export declare function writtenBackend(name: string): string | undefined;
+/**
+ * Why the registry name `name`, which mise resolves to `backend` (`cargo:tokei`), is refused; undefined when that
+ * backend is allowed.
+ */
+export declare function resolvedBackendRefusal(name: string, backend: string): string | undefined;
+/** PyPI packages whose runtime the environment does not declare, and what to declare. */
+export interface MissingRuntime {
+    packages: string[];
+    missing: string[];
+}
+/**
+ * The PyPI packages, written `pypi:` or resolved to it (`backends`, by package), when the environment does not declare
+ * both `python` and `uv`: mise takes them from the machine and never adds them, so such a package installs on an
+ * author's machine that has them and fails in the image.
+ */
+export declare function missingPythonRuntime(packages: Record<string, string>, backends: ReadonlyMap<string, string>): MissingRuntime | undefined;
+/** What to tell whoever declared them, with the command that declares the rest. */
+export declare function runtimeAdvice({ packages, missing }: MissingRuntime): string;
+/** Whether `packages` declares `tool` under any backend or owner: `aqua:astral-sh/uv` is `uv`. */
+export declare function declaresTool(packages: Record<string, string>, tool: string): boolean;
+/**
+ * One argument of `fastagent env add`: `gh`, `gh@2`, `npm:@scope/tool@1`, or `apt:chromium` for an apt package. The
+ * version is what follows the last `@` after the backend, `latest` without one.
+ */
+export declare function parsePackageArgument(arg: string): {
+    apt: string;
+} | {
+    name: string;
+    version: string;
+};
+export {};

package/dist/environment/declare.js

@@ -0,0 +1,210 @@
+/**
+ * WHAT AN AGENT'S ENVIRONMENT IS: the `environment` of `context.json`, read and refused in ONE place, and the backends a
+ * package may install from. FastAgent's own format, with mise underneath: `packages` (mise's tool names, each with a
+ * version), `aptPackages` (Debian packages the image installs) and `variables` (the environment variables its commands
+ * read, by name: their values come from the environment, as a tool's secrets do). Pure: installing it is mise.ts's.
+ * docs/design/agent-service.md §4 is the rule.
+ */
+import { isEnvName } from "../declared-secrets.js";
+import { isDeployOwned } from "../deploy/secrets.js";
+import { CONTEXT_FILE } from "../paths.js";
+const ENVIRONMENT_KEYS = ["packages", "aptPackages", "variables"];
+/** The backends a package may be written with: a release, a conda-forge build, an npm or a PyPI package. */
+const WRITTEN_BACKENDS = ["aqua", "github", "gitlab", "conda", "npm", "pypi"];
+/** The backends a registry name may resolve to: the written ones, more release hosts, and mise's own runtimes. */
+const RESOLVED_BACKENDS = new Set([...WRITTEN_BACKENDS, "forgejo", "http", "packslip", "core"]);
+/** The backends left out, each with its reason; any other is refused until it is classified. */
+const LEFT_OUT = {
+    go: "builds from source: a whole Go toolchain in the image for one binary",
+    cargo: "builds from source: a whole Rust toolchain in the image for one binary",
+    spm: "builds from source with Swift",
+    gem: "compiles native extensions against Ruby",
+    spinel: "compiles Ruby into a binary",
+    asdf: "runs a plugin's shell scripts at install, and has no Windows",
+    vfox: "runs a plugin's code at install and whenever the environment is entered, and the plugin is not pinned",
+    dotnet: "needs the .NET SDK, which the environment does not declare yet",
+    ubi: "is deprecated in mise",
+};
+const ALTERNATIVE = "write the project's release with github:<owner>/<repo>, or install it in your own Dockerfile";
+/** A registry name: what `mise registry` lists. */
+const REGISTRY_NAME = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+/** What follows a written backend: a package or `owner/repo`, an npm scope included, without mise's `[options]`. */
+const BACKEND_NAME = /^@?[A-Za-z0-9][A-Za-z0-9._/-]*$/;
+/** A Debian package name (Debian Policy §5.6.1). */
+const APT_NAME = /^[a-z0-9][a-z0-9+.-]+$/;
+/** Read the `environment` of `context.json` (undefined is none). Every refusal names what it refuses. */
+export function declareEnvironment(raw) {
+    if (raw === undefined)
+        return undefined;
+    if (!raw || typeof raw !== "object" || Array.isArray(raw))
+        throw new Error(`"environment" must be an object`);
+    const environment = raw;
+    for (const key of Object.keys(environment)) {
+        if (!ENVIRONMENT_KEYS.includes(key)) {
+            throw new Error(`environment: unknown key "${key}" (valid keys: ${ENVIRONMENT_KEYS.join(", ")})`);
+        }
+    }
+    return {
+        packages: declarePackages(environment.packages),
+        aptPackages: declareAptPackages(environment.aptPackages),
+        variables: declareVariables(environment.variables),
+    };
+}
+function declareVariables(raw) {
+    if (raw === undefined)
+        return {};
+    if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+        throw new Error(`environment: "variables" must be an object of variables by name`);
+    }
+    for (const [name, variable] of Object.entries(raw)) {
+        const at = `environment: variable ${JSON.stringify(name)}`;
+        if (!isEnvName(name))
+            throw new Error(`${at} is not an environment variable name`);
+        if (isDeployOwned(name)) {
+            throw new Error(`${at} is set by the deployment itself, so it cannot be declared: a value file's copy never travels`);
+        }
+        if (!variable || typeof variable !== "object" || Array.isArray(variable)) {
+            throw new Error(`${at} must be { "description": "what it is for" }: its value goes in the stage's value file ` +
+                `(.secrets/.env, .secrets/production/.env) or the host, never in context.json`);
+        }
+        for (const key of Object.keys(variable)) {
+            if (key !== "description")
+                throw new Error(`${at}: unknown key "${key}" (valid keys: description)`);
+        }
+        const description = variable.description;
+        if (typeof description !== "string" || description.trim() === "") {
+            throw new Error(`${at}: "description" must be a non-empty sentence saying what it is for`);
+        }
+        // Written verbatim into each host's runbook, as a comment: a line break would end the comment and start a command.
+        // biome-ignore lint/suspicious/noControlCharactersInRegex: the control characters are what is refused
+        if (/[\u0000-\u001f\u007f]/.test(description)) {
+            throw new Error(`${at}: "description" must be one line of text, without control characters`);
+        }
+    }
+    return Object.fromEntries(Object.entries(raw).map(([name, { description }]) => [name, { description }]));
+}
+/** The variables `environment` declares, as the declarations every serving path and `deploy` require. */
+export function declaredVariables(environment) {
+    return Object.entries(environment?.variables ?? {}).map(([name, { description }]) => ({
+        name,
+        source: CONTEXT_FILE,
+        description,
+    }));
+}
+function declarePackages(raw) {
+    if (raw === undefined)
+        return {};
+    if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+        throw new Error(`environment: "packages" must be an object of versions by package`);
+    }
+    for (const [name, version] of Object.entries(raw)) {
+        const refused = packageNameError(name);
+        if (refused)
+            throw new Error(`environment: package "${name}" ${refused}`);
+        if (typeof version !== "string")
+            throw new Error(`environment: package "${name}": the version must be a string`);
+        const badVersion = versionError(version);
+        if (badVersion)
+            throw new Error(`environment: package "${name}": ${badVersion}`);
+    }
+    return { ...raw };
+}
+function declareAptPackages(raw) {
+    if (raw === undefined)
+        return [];
+    if (!Array.isArray(raw))
+        throw new Error(`environment: "aptPackages" must be an array of Debian package names`);
+    const seen = new Set();
+    for (const name of raw) {
+        if (typeof name !== "string" || !APT_NAME.test(name)) {
+            throw new Error(`environment: apt package ${JSON.stringify(name)} is not a Debian package name`);
+        }
+        if (seen.has(name))
+            throw new Error(`environment: apt package "${name}" is listed twice`);
+        seen.add(name);
+    }
+    return [...raw];
+}
+/** Why `name` cannot name a package, as the rest of a sentence that starts with it; undefined when it can. */
+function packageNameError(name) {
+    if (name.includes("["))
+        return "has mise's [options], which the format does not hold";
+    const colon = name.indexOf(":");
+    if (colon === -1)
+        return REGISTRY_NAME.test(name) ? undefined : "is not a name from mise's registry";
+    const backend = name.slice(0, colon);
+    if (backend === "http") {
+        return "is written with http:, whose package needs a URL a version cannot hold — a registry name that installs from a URL carries its own";
+    }
+    if (!WRITTEN_BACKENDS.includes(backend)) {
+        return `installs with ${backend}:, which ${refusalReason(backend)}`;
+    }
+    return BACKEND_NAME.test(name.slice(colon + 1)) ? undefined : `does not name a package after "${backend}:"`;
+}
+/** Why `version` is not one, or undefined. */
+function versionError(version) {
+    if (version === "" || /\s/.test(version))
+        return "the version must be non-empty, without spaces";
+    // ref:, path:, prefix:, sub-…: build from source, read this machine, or say what a version already says.
+    if (version.includes(":") || version === "system") {
+        return `version "${version}" — a version is "latest", a prefix ("2") or an exact version ("2.1.0")`;
+    }
+    return undefined;
+}
+/** Why FastAgent does not install from `backend`, as a clause after "which", with what to do instead. */
+function refusalReason(backend) {
+    const reason = LEFT_OUT[backend] ??
+        `FastAgent does not install from (a package is a registry name, or written with ` +
+            `${WRITTEN_BACKENDS.map((b) => `${b}:`).join(", ")})`;
+    return `${reason} — ${ALTERNATIVE}`;
+}
+/** The backend a package is written with (`npm:prettier` is npm), or undefined for a registry name, which mise resolves. */
+export function writtenBackend(name) {
+    const colon = name.indexOf(":");
+    return colon === -1 ? undefined : name.slice(0, colon);
+}
+/**
+ * Why the registry name `name`, which mise resolves to `backend` (`cargo:tokei`), is refused; undefined when that
+ * backend is allowed.
+ */
+export function resolvedBackendRefusal(name, backend) {
+    const kind = backend.split(":")[0] ?? backend;
+    if (RESOLVED_BACKENDS.has(kind))
+        return undefined;
+    return `package "${name}" resolves to ${backend}, which ${refusalReason(kind)}`;
+}
+/**
+ * The PyPI packages, written `pypi:` or resolved to it (`backends`, by package), when the environment does not declare
+ * both `python` and `uv`: mise takes them from the machine and never adds them, so such a package installs on an
+ * author's machine that has them and fails in the image.
+ */
+export function missingPythonRuntime(packages, backends) {
+    const pypi = Object.keys(packages).filter((name) => backends.get(name) === "pypi");
+    const missing = ["python", "uv"].filter((tool) => !declaresTool(packages, tool));
+    return pypi.length > 0 && missing.length > 0 ? { packages: pypi, missing } : undefined;
+}
+/** What to tell whoever declared them, with the command that declares the rest. */
+export function runtimeAdvice({ packages, missing }) {
+    return (`${packages.join(", ")} ${packages.length === 1 ? "installs" : "install"} with ${missing.join(" and ")}, which ` +
+        `the environment does not declare: mise then uses this machine's, and the image has none — run ` +
+        `\`fastagent env add ${missing.join(" ")}\``);
+}
+/** Whether `packages` declares `tool` under any backend or owner: `aqua:astral-sh/uv` is `uv`. */
+export function declaresTool(packages, tool) {
+    return Object.keys(packages).some((name) => name
+        .slice(name.indexOf(":") + 1)
+        .split("/")
+        .at(-1) === tool);
+}
+/**
+ * One argument of `fastagent env add`: `gh`, `gh@2`, `npm:@scope/tool@1`, or `apt:chromium` for an apt package. The
+ * version is what follows the last `@` after the backend, `latest` without one.
+ */
+export function parsePackageArgument(arg) {
+    if (arg.startsWith("apt:"))
+        return { apt: arg.slice("apt:".length) };
+    const at = arg.lastIndexOf("@");
+    if (at > arg.indexOf(":") + 1)
+        return { name: arg.slice(0, at), version: arg.slice(at + 1) };
+    return { name: arg, version: "latest" };
+}