@fastagent-sh/fastagent 0.24.3 → 0.25.0

package/dist/deploy/preflight.js

@@ -6,27 +6,82 @@ import { readFile } from "node:fs/promises";
 import { randomUUID } from "node:crypto";
 import { basename, join, relative } from "node:path";
 import { isModelSpec, isReleaseAgentName } from "./workspace.js";
-import { providerOf } from "../engines/pi/config.js";
-import { resolveAuthPath } from "../engines/pi/auth.js";
 import { InMemoryCredentialStore } from "@earendil-works/pi-ai";
-import { AGENT_MODEL_CATALOG_FILE, AGENT_MODELS_FILE, exists } from "../paths.js";
-import { inspectChannels } from "../channels/discover.js";
-import { loadRoutines } from "../schedule/discover.js";
-import { resolveAgentTools } from "../engines/pi/create.js";
-import { loadAgentDefinition } from "../engines/pi/definition.js";
-import { agentModels } from "../engines/pi/agent-models.js";
-import { allSecrets } from "../declared-secrets.js";
-import { createPiModelRuntime, definitionKeyOf, environmentAuthSource, literalKeyProviders, isBuiltinProvider, machineModels, globalCatalogPath, inGlobalCatalog, interactiveLoginKind, loginProviders, } from "../engines/pi/models.js";
+import { resolveAuthPath } from "../harnesses/models/credentials.js";
+import { environmentAuth, interactiveLoginKind, loginProviders, modelsOver, providerOf, } from "../harnesses/models/models.js";
+import { modelEnvironment } from "../harnesses/models/environment.js";
+import { buildDefinitionShape, definitionSecrets, prepareDefinition, } from "../harnesses/pi-durable/open.js";
+import { LOCAL_CONTEXT_FILE, exists } from "../paths.js";
+import { channelIngress } from "../channels/discover.js";
+import { loadContent, loadEnvironment } from "../content/file.js";
 import { CHANNEL_KINDS } from "../scaffold/add-channel.js";
-import { detectRuntime, readPackageJson } from "../runtime.js";
+import { RUNTIME_FLOOR, belowFloor, detectRuntime, listsFastagent, readPackageJson } from "../runtime.js";
 import { fastagentVersion } from "../version.js";
 import { isGeneratedDockerfile } from "./container.js";
 import { buildContextPaths, checkKeptIgnoreFiles } from "./build-context.js";
-import { CRON_CAN_BE_EXTERNAL, residencyFor } from "./residency.js";
 import { dotEnvPath, loadEnvValues } from "../env.js";
 import { deploymentSecrets, isEnvKey } from "./secrets.js";
-import { DEFAULT_HTTP_PORT, describeAnonymousSurface, shouldServeRun } from "../service.js";
-import { CONTROL_PREFIX } from "../channels/control.js";
+import { DEFAULT_HTTP_PORT } from "../service.js";
+import { declaredVariables, declaresTool, runtimeAdvice } from "../environment/declare.js";
+import { checkPackages, MISE_PACKAGE_NAMES, miseBinary, packageSpecs } from "../environment/mise.js";
+/**
+ * What each content entry becomes on the host, one line each, so none is missing there unsaid (agent-model.md §3). A
+ * repository `context.json` declares is cloned there, as on this machine without a checkout bound. A directory only
+ * this machine binds stays here: the deployed agent works without it, which the line says and says how to change. One
+ * the agent works on is a warning, since the deployed agent lacks data it was meant to work on; one it only knows, a
+ * note.
+ */
+function checkContent({ declared, bound }, storageResets, report) {
+    for (const entry of declared) {
+        const fate = storageResets
+            ? "cloned afresh on every deployment, since the host's storage starts over; what the agent did not push is lost"
+            : "cloned on the host, and brought up to date in place at each start";
+        report.note(`${roleOf(entry)} ${entry.name}: github ${entry.repo}${entry.ref ? `@${entry.ref}` : ""}, ${fate}`);
+    }
+    for (const binding of bound) {
+        if (binding.kind !== "local")
+            continue;
+        const stays = `${roleOf(binding)} ${binding.name}: a directory of this machine (${binding.path}, bound in ` +
+            `${LOCAL_CONTEXT_FILE}), stays here, and the deployed agent works without it`;
+        if (binding.readonly) {
+            report.note(`${stays}; to ship what the agent reads there, copy it into the agent directory, which every release carries`);
+        }
+        else {
+            report.warn(`${stays}; to work on it from a host, move it to a GitHub repository and add it as github:owner/repo`);
+        }
+    }
+}
+function roleOf(entry) {
+    return entry.readonly ? "knows" : "works on";
+}
+/**
+ * What the image needs to install the packages the agent declares: the agent's own mise for linux in its package.json,
+ * so the image's install brings it, packages FastAgent installs from, and a PyPI package's runtime. A machine without
+ * the agent's mise cannot check them, which is an issue (a warning without `--run`), as a code input that cannot load
+ * is.
+ */
+async function checkEnvironment(agentDir, packages, hasPackageJson, pkg, report) {
+    if (Object.keys(packages).length === 0)
+        return;
+    const linux = MISE_PACKAGE_NAMES.filter((name) => name.includes("-linux-"));
+    const missing = linux.filter((name) => !(name in (pkg.optionalDependencies ?? {})));
+    if (!hasPackageJson || missing.length > 0) {
+        report.issue(`context.json declares packages, and the image would have no mise to install them with: the agent's ` +
+            `package.json does not list ${missing.join(", ")}. Run \`fastagent env install\` in the agent directory.`);
+        return;
+    }
+    const bin = miseBinary(agentDir);
+    if (!bin) {
+        report.issue(`the agent's mise is not installed here, so the packages context.json declares cannot be checked. Run ` +
+            `\`fastagent env install\` in ${agentDir}, then deploy again.`);
+        return;
+    }
+    const { refusals, runtime } = await checkPackages(agentDir, bin, packages);
+    for (const refusal of refusals)
+        report.issue(refusal);
+    if (runtime)
+        report.issue(runtimeAdvice(runtime));
+}
 /** The pre-flight's one early exit: thrown by a check, turned into `{ ok: false, gate }` by {@link preflightDeploy}. */
 class DeployGate {
     text;
@@ -56,7 +111,7 @@ export async function preflightDeploy(input) {
     }
 }
 async function gatherFacts(input, report) {
-    const { placement: { agentDir, workspace }, config, force, externalClock, publicUrl = true, } = input;
+    const { agentDir, config, force, noResidentProcess, storageResets = false, servesApi = false } = input;
     // The release manifest carries this name into the container, where it is joined onto the storage root — so `init`'s
     // "one path segment" is not enough here.
     if (!isReleaseAgentName(basename(agentDir))) {
@@ -64,18 +119,26 @@ async function gatherFacts(input, report) {
             `may use only letters, digits, "-" and "_"; rename it (the fastagent.config.ts inside is what ` +
             `makes it an agent, never its name)`);
     }
-    const agentPrefix = `${basename(agentDir)}/`;
-    // The definition the box will load on every start, loaded here first: a refusal in it (a leftover persona.md, a
-    // skill named with a slash) builds a perfectly good image that crash-loops on fly/railway/docker and fails every
+    const content = loadContent(agentDir);
+    checkContent(content, storageResets, report);
+    // The definition the box will load on every start, read here first: a refusal in it (a module that fails to import,
+    // two tools under one name) builds a perfectly good image that crash-loops on fly/railway/docker and fails every
     // invocation on AgentCore. This is the boundary that turns that refusal into a deploy finding, so the error is
     // carried whole into the issue rather than rethrown.
-    await loadAgentDefinition(agentDir, { cwd: workspace }).catch((error) => {
-        report.issue(`the definition does not load, so the deployed agent would not start: ${error instanceof Error ? error.message : String(error)}`);
+    const definition = await prepareDefinition(agentDir).catch((error) => {
+        report.issue(`the definition does not load, so the deployed agent would not start: ${messageOf(error)}`);
+        return undefined;
     });
     // The model this deployment will run on, and where it came from. Resolved HERE so the plan side and the run side
     // cannot disagree about it.
-    const valueFile = relative(workspace, dotEnvPath(agentDir));
+    const valueFile = relative(agentDir, dotEnvPath(agentDir));
     const values = loadEnvValues(dotEnvPath(agentDir));
+    // A host has no credential of the author's: what it clones with is GITHUB_TOKEN, which travels like every value.
+    if (content.declared.length > 0 && !values.get("GITHUB_TOKEN")) {
+        report.note(`no GITHUB_TOKEN in ${valueFile}: the host clones without a credential, which reaches public repositories ` +
+            `only, and the agent cannot push from its clones. Set one there to give it access; it travels with the ` +
+            `other values`);
+    }
     const model = resolveDeployModel(config, values, valueFile);
     if (model.invalid !== undefined) {
         // A gate rather than a warning even without `--run`: the release manifest validates the spec on the way out, so
@@ -99,32 +162,12 @@ async function gatherFacts(input, report) {
         report.note(`model ${model.spec} (source: ${model.source})`);
     }
     const modelSpec = model.spec;
-    // Time triggers (static routines or self-scheduling) need a machine kept running, and a declared schedule also
-    // decides whether `POST /run` mounts — so the load happens HERE, before the warning that has to name it.
-    // Loaded, not just listed: the same load answers "are there time triggers" AND "what did they declare they need".
-    // A file that FAILED to load still counts as a trigger — the author will fix it, and a plan that scaled to zero
-    // because a cron was broken on deploy day would sleep through it afterwards.
-    const loadedRoutines = await loadRoutines(agentDir);
-    // What the PUBLIC host URL answers with no authentication of ours, NAMED FROM WHAT WILL ACTUALLY MOUNT (through the
-    // same `shouldServeRun` the assembly uses), never from the host alone: listing an endpoint this deployment does not
-    // serve is how an operator learns to skim past every deploy warning — the same reason `publicUrl` exists.
-    const unauthenticated = describeAnonymousSurface({
-        invoke: config.http?.invoke !== false,
-        run: loadedRoutines.routines.length > 0 && shouldServeRun(config.http),
-        ...(config.sessionControl === true ? { controlPrefix: CONTROL_PREFIX } : {}),
-    });
-    if (publicUrl && unauthenticated.length > 0) {
-        report.warn(`the deployed box answers ${unauthenticated.join(" and ")} at its public URL, UNAUTHENTICATED — ` +
-            `fastagent authenticates nothing. Put a gateway, an IdP-backed proxy or a private network in front of that ` +
-            `URL (docs/design/session-control.md §14)`);
-    }
-    // Known channel kinds only — a custom channel's webhook (and, unless it declared them, its secrets) are unknown to
-    // us; note and let the author wire them.
-    const inspected = await inspectChannels(agentDir);
-    if (inspected.failures.length > 0) {
-        throw new Error(`cannot inspect channel modules: ${inspected.failures.map((failure) => `${failure.label}: ${failure.message}`).join("; ")}`);
-    }
-    const channels = inspected.channels;
+    const declaredSecrets = definition ? definitionSecrets(definition) : declaredVariables(loadEnvironment(agentDir));
+    const code = definition ? buildShapes(definition, values, report) : undefined;
+    const channels = [...(code?.channels ?? [])].map(([name, module]) => ({
+        name,
+        ingress: channelIngress(module),
+    }));
     for (const { name, ingress } of channels) {
         if (CHANNEL_KINDS.includes(name))
             continue;
@@ -134,54 +177,34 @@ async function gatherFacts(input, report) {
             : `route channel "${name}" is custom — ${secretsPart}; configure its webhook yourself`);
     }
     const longConnectionChannels = channels.filter((c) => c.ingress === "long-connection").map((c) => c.name);
-    // A ROUTINE IS NOT A CRON. `cron` is a field, so counting routine FILES answered a different question: a
-    // definition whose only routine is reached by name (`POST /run`) would pin one machine up forever and print a
-    // note about a cron instant it does not have. `deploy agentcore` already filtered the same way when it turned
-    // routines into EventBridge rules; this is the other reader of that fact, and they must agree.
-    //
-    // A FAILED file still counts, on the conservative side: it may well declare a cron, and a plan that scaled to
-    // zero because the file did not parse would hide that behind silence.
-    const hasCron = loadedRoutines.routines.some((r) => r.cron !== undefined) || loadedRoutines.failures.length > 0;
-    if (longConnectionChannels.length > 0 && !externalClock) {
+    // Counted from the registry when the code did not build: a plan that scaled to zero because a schedule failed to
+    // build on deploy day would sleep through it once it is fixed.
+    const hasCron = (code?.schedules.length ?? definition?.registry.schedules.length ?? 0) > 0;
+    if (longConnectionChannels.length > 0 && !noResidentProcess) {
         report.note(`long-connection channel present (${longConnectionChannels.join(", ")}) — a GENERATED plan keeps one machine running ` +
             `(an outbound connection cannot wake a scaled-to-zero service).`);
     }
-    // A cron has an external substitute, and an operator who is paying for an idle box should be told so — unless a
-    // long connection pins the box anyway, which residency.ts decides.
-    if (hasCron && !externalClock) {
-        const wayOut = residencyFor({ channels, hasCron })?.reason === CRON_CAN_BE_EXTERNAL;
-        report.note(`routines/ present — a GENERATED plan keeps one machine running (nothing wakes this box at a cron ` +
-            `instant).` +
-            (wayOut
-                ? ` To scale to zero instead, keep the time in a scheduler you own and let it call ` +
-                    `\`POST /run\` (an API that runs one declared unit of work by name — docs/api-reference.md#post-run).`
-                : ""));
+    if (hasCron && !noResidentProcess) {
+        report.note(`src/schedules/ present — a GENERATED plan keeps one machine running (nothing wakes this box at a cron instant).`);
     }
-    await checkMachineModels(agentDir, modelSpec, report);
-    // The registry the DEPLOYED agent has (its own models.json and model catalog, nothing of the machine's), built first
-    // so a malformed file stops the deploy with pi's own reason before anything below reads the file raw. No credential
-    // is read for that.
-    const deployed = await createPiModelRuntime({
-        agentDir,
-        credentials: new InMemoryCredentialStore(),
-        machineLayer: false,
-    });
-    if (modelSpec)
-        await checkGlobalCatalogModel(modelSpec, deployed, report);
-    const authPath = resolveAuthPath(agentDir);
-    // A model only the definition's extensions declare (a virtual model, or a provider one registers) is authenticated
-    // by that code on the box, per request: a virtual model's credential is whichever physical model it routes to.
-    // Asked of the catalog the box builds, extensions included, so deploy judges the model the box will run.
-    const fromExtension = modelSpec ? await extensionDeclared(agentDir, workspace, modelSpec, deployed) : false;
-    if (fromExtension && modelSpec) {
-        report.note(`${modelSpec} is declared by the definition's extensions, which resolve its credentials on the box — deploy ` +
-            `cannot check them. Set the keys the models it uses need in ${valueFile}`);
+    if (code !== undefined && channels.length === 0 && !hasCron && !servesApi) {
+        report.warn(`no channel in src/channels/, no schedule in src/schedules/, and no Agent API on this deployment: nothing ` +
+            `reaches it but its health check. Add a channel (\`fastagent add telegram|slack|feishu|lark\`, or your ` +
+            `own) or a schedule; an agent used only from an app is embedded in it (openAgent), not deployed`);
     }
-    const route = modelSpec && !fromExtension ? await credentialRoute(agentDir, modelSpec, values) : {};
+    const providers = code?.providers ?? [];
+    const authPath = resolveAuthPath(agentDir);
+    const route = modelSpec ? await credentialRoute(modelSpec, values, providers) : {};
     const modelAuth = route.envVar;
     const boxLogin = route.boxLogin;
+    if (modelSpec && code) {
+        await checkModelExists(agentDir, modelSpec, providers, report, {
+            credentialShips: boxLogin === undefined,
+            valueFile,
+        });
+    }
     if (boxLogin !== undefined) {
-        if (!hasLogin(boxLogin)) {
+        if (!hasLogin(boxLogin, providers)) {
             report.issue(`no credential for ${modelSpec} reaches the deployment, and "${boxLogin}" has no login to run there — set ` +
                 `its API key in ${valueFile}`);
         }
@@ -191,39 +214,36 @@ async function gatherFacts(input, report) {
                 `(\`fastagent login ${boxLogin} --deployment\`). Or set ${boxLogin}'s API key in ${valueFile}`);
         }
     }
-    // Reported, not refused. Whether a string is a credential is the AUTHOR's knowledge: pi's docs prescribe
-    // `"apiKey": "ollama"` for a keyless local server, and no static rule separates that from a leaked key. The
-    // `.dockerignore` check next to this one IS a gate because it catches a packing rule putting FastAgent's OWN
-    // `.secrets/auth.json` into the image — the framework's doing. This is the author's own committed file.
-    // Asked of EVERY provider, not just the selected model's: the file ships whole.
-    const literalKeys = await literalKeyProviders(agentDir);
-    if (literalKeys.length > 0) {
-        report.warn(`${AGENT_MODELS_FILE} carries a literal apiKey for ${literalKeys.map((id) => `"${id}"`).join(", ")} — that ` +
-            `file ships inside the image, where anyone who can pull it reads the layer. If it is a credential, use ` +
-            `"$YOUR_ENV_VAR" (deploy carries it like any provider key) or "!command" (it runs on the box and never ` +
-            `travels); a placeholder for a keyless local server is fine as it is.`);
-    }
     // Container facts (shared by every host) + the warnings that follow.
     const hasPackageJson = await exists(join(agentDir, "package.json"));
     const pkg = await readPackageJson(agentDir);
     const { runtime, bunVersion, hasLockfile } = detectRuntime(agentDir, pkg);
+    const kept = await keptDockerfile(agentDir);
+    // Only the generated image runs the pinned Bun: a hand-written Dockerfile names its own base.
+    if (kept === undefined &&
+        runtime === "bun" &&
+        bunVersion !== undefined &&
+        belowFloor(bunVersion, RUNTIME_FLOOR.bun)) {
+        report.issue(`package.json pins bun@${bunVersion}, which the image runs (oven/bun:${bunVersion}), and the agent's storage is ` +
+            `node:sqlite, which Bun ships from ${RUNTIME_FLOOR.bun}: the container would fail at start. Pin ` +
+            `bun@${RUNTIME_FLOOR.bun} or later`);
+    }
     const install = runtime === "bun" ? "bun install" : "npm install";
     const runner = runtime === "bun" ? "bun run fastagent" : "./node_modules/.bin/fastagent";
     const hasOtherLock = runtime === "node" &&
         ((await exists(join(agentDir, "pnpm-lock.yaml"))) || (await exists(join(agentDir, "yarn.lock"))));
-    // Does the baked workspace ship a `.git`?
-    const shipsGit = await exists(join(workspace, ".git"));
+    // Does the baked agent directory ship a `.git`?
+    const shipsGit = await exists(join(agentDir, ".git"));
     // After the facts: the deps sentence must match the agent's actual shape (a markdown-only agent has no package.json
     // and installs nothing — the note must not point at a file that doesn't exist).
     const deps = hasPackageJson
-        ? `only the agent's deps (${agentPrefix}package.json) are installed — the workspace's own deps are the agent's runtime concern`
+        ? `its package.json dependencies are installed in the image`
         : `the agent has no package.json, so no deps are installed (the pinned global CLI serves the directory)`;
     // What a RELEASE does — host-neutral, because how long the storage under it lives is the host's own answer and its
     // runbook gives it (a Fly volume outlives every deploy; AgentCore's mount does not).
-    report.note(`the whole directory is baked as the agent's workspace (WYSIWYG — what you see is what ships, ` +
-        `git or not, clean or not); ${deps}. The image seeds the storage once; a later release replaces ` +
-        `only ${agentPrefix} and leaves the rest of the workspace, state and credentials in place — for ` +
-        `how long, see this host's storage note below`);
+    report.note(`the agent directory is baked as the definition (WYSIWYG — what you see is what ships, git or not, clean or ` +
+        `not); ${deps}. Every release replaces the deployed definition and leaves the instance's state and ` +
+        `credentials in place — for how long, see this host's storage note below`);
     // A code agent with no lockfile builds via a non-frozen install (ranges resolve at build time) — not reproducible.
     if (hasPackageJson && !hasLockfile) {
         const lock = runtime === "bun" ? "bun.lock" : "package-lock.json";
@@ -234,17 +254,31 @@ async function gatherFacts(input, report) {
                 `Run \`${install}\` and commit the lockfile for pinned redeploys.`);
     }
     // The code-path Dockerfile runs `${runner}`.
-    if (hasPackageJson && !("@fastagent-sh/fastagent" in { ...pkg.dependencies, ...pkg.devDependencies })) {
+    if (hasPackageJson && !listsFastagent(pkg)) {
         report.warn(`package.json does not list @fastagent-sh/fastagent — the image's \`${runner}\` has no local bin to run, ` +
             `so the container fails at start. Add it to dependencies and re-run \`${install}\`.`);
     }
-    const paths = await buildContextPaths(workspace, agentDir, agentPrefix, authPath);
-    await checkKeptIgnoreFiles({ workspace, agentDir, agentPrefix, force, paths }, report);
-    // Write-back mechanics are fastagent's (the policy is the agent's prompt's).
-    const apt = shipsGit ? [...new Set(["git", ...(config.deploy?.apt ?? [])])] : config.deploy?.apt;
+    const paths = await buildContextPaths(agentDir, authPath);
+    await checkKeptIgnoreFiles({ agentDir, force, paths }, report);
+    const environment = loadEnvironment(agentDir);
+    const packages = environment?.packages ?? {};
+    await checkEnvironment(agentDir, packages, hasPackageJson, pkg, report);
+    const installsPackages = Object.keys(packages).length > 0;
+    // Write-back mechanics are fastagent's (the policy is the agent's prompt's). A repository content entry is cloned on the
+    // host, which takes git too. mise downloads over TLS, and the slim base image has no CA certificates; rustup, which
+    // mise installs rust with, downloads with curl. The agent's own apt packages join them, in one layer.
+    const needsGit = shipsGit || content.declared.length > 0;
+    const apt = [
+        ...new Set([
+            ...(needsGit ? ["git"] : []),
+            ...(installsPackages ? ["ca-certificates"] : []),
+            ...(declaresTool(packages, "rust") ? ["curl"] : []),
+            ...(environment?.aptPackages ?? []),
+        ]),
+    ];
     const container = {
         releaseId: randomUUID(),
-        agentPrefix,
+        agent: basename(agentDir),
         machineryPaths: paths.machineryPaths,
         hasPackageJson,
         runtime,
@@ -252,30 +286,13 @@ async function gatherFacts(input, report) {
         hasLockfile,
         version: await fastagentVersion(),
         apt,
+        ...(installsPackages ? { packages: packageSpecs(packages) } : {}),
         ...(model.envValue !== undefined ? { modelSpec: model.envValue } : {}),
         shipsGit,
     };
     const port = config.http?.port ?? DEFAULT_HTTP_PORT;
-    // EVERYTHING the definition declared it needs, from wherever it was declared. Read through the SAME resolver
-    // dev/start mount with, so "which tool declarations count" has one answer (config.tools declare too; a shadowed
-    // file's declaration is dropped in both places).
-    const resolvedTools = await resolveAgentTools(config, agentDir, workspace);
-    // A code input we could not READ is a code input whose declarations we cannot carry — and the box
-    // WILL read it (its deps are installed there), so its gate fires after the deploy reported success:
-    // a crash loop, which is the failure mode this whole mechanism exists to move to build time. Under
-    // `--run` that is a gate, like a channel that fails to inspect; generate-only warns, since the
-    // operator may be producing artifacts from a machine that never installed the agent's deps.
-    for (const failure of [...resolvedTools.toolFailures, ...loadedRoutines.failures]) {
-        const issue = `${failure.label} failed to load (${failure.message}) — any secrets it declares cannot be carried ` +
-            `to the host, so the deployed box would refuse to start`;
-        report.issue(issue);
-    }
-    const declaredSecrets = [
-        ...allSecrets(resolvedTools.toolSecrets),
-        ...allSecrets(loadedRoutines.secrets),
-        ...allSecrets(inspected.secrets),
-    ];
-    await checkKeptDockerfile(agentDir, config, model.envValue, valueFile, report);
+    if (kept !== undefined)
+        checkKeptDockerfile(kept, agentDir, model.envValue, valueFile, report);
     return {
         channels,
         hasCron,
@@ -289,84 +306,89 @@ async function gatherFacts(input, report) {
         secrets: deploymentSecrets(modelAuth, declaredSecrets, values, valueFile),
     };
 }
+/**
+ * The definition's code built for its SHAPE with the value file's values (`buildDefinitionShape`): a generate-only
+ * deploy runs on a machine that may hold none of them, and whether the value file supplies them is the values gate's
+ * question, asked by name. A build that fails is an issue, as a module that fails to load is.
+ */
+function buildShapes(definition, values, report) {
+    try {
+        return buildDefinitionShape(definition, Object.fromEntries(values));
+    }
+    catch (error) {
+        report.issue(`the definition does not build, so the deployed agent would not start: ${messageOf(error)}`);
+        return undefined;
+    }
+}
+function messageOf(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+/**
+ * A model no provider of the deployed agent offers fails every message there. Its lists are this machine's: what it
+ * kept and what it fetches now, a provider's own list with whatever credential this machine's environment holds. A
+ * model only a fetched list has is the box's only once the box fetches that list, which a box with nothing kept does as
+ * it opens: pi's published catalog with no credential, a provider's own list with the one this deploy carries, since a
+ * login on the box comes after the start it would refuse. Whether a model is only in a provider's own list cannot be
+ * told here: a provider in code keeps what it fetched in its own object, which every `Models` over it then lists.
+ */
+async function checkModelExists(agentDir, spec, providers, report, box) {
+    const provider = providerOf(spec);
+    const modelId = spec.slice(provider.length + 1);
+    const { models } = await modelEnvironment(agentDir, { credentialStore: new InMemoryCredentialStore() }, providers);
+    if (models.getModel(provider, modelId)) {
+        if (models.getProvider(provider)?.refreshModels !== undefined) {
+            if (box.credentialShips)
+                return;
+            report.warn(`provider "${provider}" fetches its own model list, which a box with no list kept, as on a first deploy, ` +
+                `fetches as it starts, with a credential this deploy does not carry (a login on the box comes after the ` +
+                `start): if "${spec}" is only in that list, the box refuses to start on it until ${provider}'s API key is ` +
+                `in ${box.valueFile}`);
+            return;
+        }
+        if (modelsOver(new InMemoryCredentialStore(), providers).getModel(provider, modelId))
+            return;
+        report.warn(`"${spec}" is in pi's published catalog, not in the pi-ai this FastAgent carries: a box with no catalog kept, ` +
+            `as on a first deploy, fetches it from pi.dev as it starts, and refuses to start on "${spec}" if it cannot`);
+        return;
+    }
+    report.issue(`no provider of the deployed agent offers "${spec}" — pi-ai's built-ins, pi's published catalog and the ` +
+        `providers fastagent.config.ts declares are all it has`);
+}
 /**
  * HOW THE MODEL'S CREDENTIAL REACHES THE BOX, from what the deploy ships and nothing else. The box is the one authority
  * on what it authenticates with (pi ranks a stored login above the environment, and only the box knows what it has
  * stored, which platform variables it was given, or what role it runs as), so this never asks what authenticates the
  * model on THIS machine: its stored logins and the shell running deploy do not travel. In order:
  *
- * 1. the definition's own models.json: a `"$NAME"` reference is a variable the value file must hold (the values gate
- *    asks for it by name), and a literal or `"!command"` travels in the image;
- * 2. a credential pi reads for the provider from the value file alone: its key variable (which the values gate then
- *    requires, as it does every declared name), or a keyless one such as `AWS_ACCESS_KEY_ID` — never one that needs a
- *    file, which would be this machine's;
- * 3. otherwise the box answers — `boxLogin`: after readiness, `--run` asks it, and it logs in only if it cannot
+ * 1. a credential the provider reads from the value file alone (a definition's provider included, which may resolve
+ *    its key from a secret it declared): its key variable (which the values gate then requires, as it does every
+ *    declared name), or a keyless one such as `AWS_ACCESS_KEY_ID` — never one that needs a file, which would be this
+ *    machine's;
+ * 2. otherwise the box answers — `boxLogin`: after readiness, `--run` asks it, and it logs in only if it cannot
  *    already authenticate the provider.
  */
-async function credentialRoute(agentDir, spec, values) {
+async function credentialRoute(spec, values, providers) {
     const provider = providerOf(spec);
-    const declared = await definitionKeyOf(agentDir, provider);
-    if (declared)
-        return "reference" in declared ? { envVar: declared.reference } : {};
     // No file of this machine's travels, so a source that needs one (Google ADC, an AWS profile) is the box's to find.
-    const fromValues = await environmentAuthSource(provider, Object.fromEntries(values), async () => false);
-    if (fromValues !== undefined)
-        return isEnvKey(fromValues) ? { envVar: fromValues } : {};
+    const fromValues = await environmentAuth(provider, Object.fromEntries(values), async () => false, providers);
+    if (fromValues !== undefined) {
+        return fromValues.source !== undefined && isEnvKey(fromValues.source) ? { envVar: fromValues.source } : {};
+    }
     return { boxLogin: provider };
 }
-/** Whether `spec` exists only once the definition's extensions have registered their models. */
-async function extensionDeclared(agentDir, workspace, spec, deployed) {
-    const provider = providerOf(spec);
-    const id = spec.slice(provider.length + 1);
-    if (deployed.getModel(provider, id))
-        return false;
-    const catalog = await agentModels(agentDir, { credentialStore: new InMemoryCredentialStore() }, { machineLayer: false, cwd: workspace }).runtime();
-    return catalog.getModel(provider, id) !== undefined;
-}
 /** Does `provider` offer an interactive login, i.e. can `fastagent login --deployment` authenticate it on the box? */
-function hasLogin(providerId) {
-    const provider = loginProviders().find((p) => p.id === providerId);
+function hasLogin(providerId, providers) {
+    const provider = loginProviders(providers).find((p) => p.id === providerId);
     return provider !== undefined && interactiveLoginKind(provider) !== "none";
 }
-/**
- * The machine's models.json is this box's environment, not the artifact: whatever the model takes from it is
- * absent wherever the agent is deployed. Said in so many words here; the credential probe already reads the deployed
- * registry.
- */
-async function checkMachineModels(agentDir, modelSpec, report) {
-    const machine = await machineModels(agentDir);
-    const provider = modelSpec ? providerOf(modelSpec) : undefined;
-    if (provider === undefined || !machine?.inherited.includes(provider))
-        return;
-    if (isBuiltinProvider(provider)) {
-        report.warn(`model "${modelSpec}" takes its "${provider}" entry from ${machine.path}, the machine's models.json, which ` +
-            `does not ship — the deployed agent runs pi's built-in "${provider}" without it. Declare the entry in the ` +
-            `agent's own ${AGENT_MODELS_FILE} to deploy it.`);
-    }
-    else {
-        // No built-in to fall back on: the deployed agent cannot resolve the model at all.
-        const issue = `model "${modelSpec}" exists only in ${machine.path}, the machine's models.json, which does not ship — the ` +
-            `deployed agent would fail with an unknown model. Declare "${provider}" in the agent's own ` +
-            `${AGENT_MODELS_FILE} to deploy it.`;
-        report.issue(issue);
-    }
+/** The agent's hand-written Dockerfile, which the deploy keeps; undefined when there is none, or it is the generated one. */
+async function keptDockerfile(agentDir) {
+    const path = join(agentDir, "Dockerfile");
+    const text = (await exists(path)) ? await readFile(path, "utf8") : undefined;
+    return text === undefined || isGeneratedDockerfile(text) ? undefined : text;
 }
 /**
- * The machine's model catalog is this box's environment, like its models.json: a model only it knows (newer than the
- * catalog bundled with pi) is unknown wherever the agent is deployed. The agent's own catalog ships, so the remedy is
- * one refresh in the agent.
- */
-async function checkGlobalCatalogModel(modelSpec, deployed, report) {
-    const provider = providerOf(modelSpec);
-    const id = modelSpec.slice(provider.length + 1);
-    if (deployed.getModel(provider, id) || !(await inGlobalCatalog(provider, id)))
-        return;
-    report.issue(`model "${modelSpec}" is known only from ${globalCatalogPath()}, the machine's model catalog, which does not ` +
-        "ship — the deployed agent would fail with an unknown model. Run `fastagent models --refresh` in the agent " +
-        `to record it in its own ${AGENT_MODEL_CATALOG_FILE}, which ships.`);
-}
-/**
- * What a KEPT hand-written Dockerfile drops. `deploy.apt` is the obvious one; the resolved model is the one that
+ * What a KEPT hand-written Dockerfile drops. The environment (context.json's) is the obvious one; the resolved model is the one that
  * looks safe and is not: the manifest is always written, but only the generated Dockerfile sets
  * FASTAGENT_RELEASE_FILE, and without it `prepareStartWorkspace` never reads the manifest — so a model that lives
  * ONLY in the value file would be reported here and absent on the box.
@@ -375,16 +397,15 @@ async function checkGlobalCatalogModel(modelSpec, deployed, report) {
  * hand-written Dockerfile survives `--force` and drops exactly the same things. Short-circuiting here let
  * `--run --force` ship the crash-loop this gate exists to stop.
  */
-async function checkKeptDockerfile(agentDir, config, 
+function checkKeptDockerfile(dockerfileText, agentDir, 
 /** The model the release manifest carries (set only when the value file named it). */
 modelFromValueFile, valueFile, report) {
-    const dockerfileHome = join(agentDir, "Dockerfile");
-    const dockerfileText = (await exists(dockerfileHome)) ? await readFile(dockerfileHome, "utf8") : undefined;
-    if (dockerfileText === undefined || isGeneratedDockerfile(dockerfileText))
-        return;
-    if (config.deploy?.apt?.length) {
-        report.warn(`kept your hand-written Dockerfile — deploy.apt (${config.deploy.apt.join(", ")}) is ` +
-            `NOT applied; install those packages in your Dockerfile.`);
+    // What the image installs: the packages and apt packages. Variables travel with the value file, whatever the image.
+    const environment = loadEnvironment(agentDir);
+    if (Object.keys(environment?.packages ?? {}).length > 0 || (environment?.aptPackages.length ?? 0) > 0) {
+        report.warn(`kept your hand-written Dockerfile — it installs the environment context.json declares only if it says so: ` +
+            `a generated Dockerfile shows the layers (the apt packages, then \`mise install --system\` of the packages ` +
+            `context.json declares).`);
     }
     // The INSTRUCTION is the question, not the file's authorship: `prepareStartWorkspace` returns early without
     // FASTAGENT_RELEASE_FILE, so a Dockerfile that sets it reads the manifest whoever wrote it. This gates rather

package/dist/deploy/railway/plan.d.ts

@@ -20,19 +20,21 @@ export interface RailwayPlanInput extends ContainerInput {
      * carries.
      */
     secrets?: readonly DeploymentSecret[];
-    /** `routines/` declares a cron — one of the things that forbids App Sleeping (deploy/residency.ts). */
+    /** `schedules/` declares a schedule — one of the things that forbids App Sleeping (deploy/residency.ts). */
     hasCron: boolean;
 }
 export interface RailwayPlan {
-    /** railway.json / Dockerfile / .dockerignore — written by the CLI (skipped if present unless --force). */
+    /**
+     * Dockerfile / .dockerignore — written by the CLI (skipped if present unless --force). No Railway config file: Railway
+     * builds from a root `Dockerfile` and restarts on failure by default, and the `/health` check that `railway.json`
+     * carried is the `--run` driver's own public probe now (Railway retires `railway.json`, and its replacement,
+     * `.railway/railway.ts`, would make every agent install Railway's SDK).
+     */
     artifacts: Artifact[];
     /** The ordered, values-resolved deploy runbook — printed to stdout for the coding agent to execute. */
     runbook: string[];
 }
-/** The `RAILWAY_DOCKERFILE_PATH` value for an agent under `prefix`. */
-export declare const dockerfilePathVar: (prefix: string) => string;
-/** The name this tool gives BOTH the project and the service, derived from the workspace directory. */
+/** The name this tool gives BOTH the project and the service, derived from the agent directory's name. */
 export declare function toRailwayName(basename: string): string;
-export declare function isGeneratedRailwayJson(content: string): boolean;
 /** Compute the Railway deploy plan from the resolved definition. */
 export declare function planRailwayDeploy(input: RailwayPlanInput): RailwayPlan;