@fastagent-sh/fastagent 0.22.1 → 0.24.0

package/dist/deploy/fly/run.d.ts

@@ -1,10 +1,11 @@
 /** `fastagent deploy fly --run` — drive flyctl to completion. */
+import type { BoxLoginStep } from "../box-shell.ts";
 import { type PublicHealthProbe, type Registrars } from "../channel-ingress.ts";
 import type { DeclaredChannel } from "../../channels/discover.ts";
-import type { CliRunner } from "../runner.ts";
+import { type CliRunner } from "../runner.ts";
 export interface FlyRunPlan {
     appName: string;
-    /** `KEY=value` secrets to set on Fly: the value file's variables + `FASTAGENT_AUTH_SEED` for a file credential. */
+    /** `KEY=value` secrets to set on Fly: the value file's variables. */
     secrets: Record<string, string>;
     /** Declared names the value file supplies no value for — the run gates on these before any side effect. */
     missingSecrets: string[];
@@ -19,6 +20,11 @@ export interface FlyRunPlan {
      * resolve it relative to the config's own directory).
      */
     dockerfile: string;
+    /**
+     * Log the box in (`fastagent login --deployment`) once it is up and before any webhook is pointed at it: a channel pointed at
+     * a box with no model credential answers every message with a failure. Resolves a gate line, or undefined.
+     */
+    boxLogin?: BoxLoginStep;
 }
 /** Done, or a gate the operator must clear before re-running (printed + non-zero exit by the CLI). */
 export type FlyRunOutcome = {

package/dist/deploy/fly/run.js

@@ -1,5 +1,5 @@
-/** `fastagent deploy fly --run` — drive flyctl to completion. */
-import { publicHealthGate, registerWebhooks } from "../channel-ingress.js";
+import { loginGate, publicHealthGate, registerWebhooks, } from "../channel-ingress.js";
+import { readOutput } from "../runner.js";
 import { missingValuesGate } from "../secrets.js";
 /**
  * The `Type` values that put an app on `https://<app>.fly.dev`, BY FAMILY — one entry per allocate command, because
@@ -28,27 +28,6 @@ export function listHasName(stdout, name) {
         throw new Error(`expected a JSON array, got ${typeof entries}`);
     return entries.some((o) => o.Name === name);
 }
-/**
- * A read-only `fly … list --json`, reduced to the question the next step asks of it — or the gate for a list we cannot
- * act on.
- */
-async function readList(fly, args, read) {
-    // The command as RUN, not a restatement of it.
-    const cmd = `fly ${args.join(" ")}`;
-    const result = await fly(args, { capture: true });
-    if (result.code !== 0)
-        return { gate: `\`${cmd}\` failed — see the flyctl output above; fix and re-run` };
-    try {
-        return { value: read(result.stdout) };
-    }
-    catch (error) {
-        // The one place a parse failure is allowed to stop being an exception.
-        return {
-            gate: `\`${cmd}\` was unreadable (${error instanceof Error ? error.message : String(error)}) — ` +
-                `run it yourself and check the flyctl version; fix and re-run`,
-        };
-    }
-}
 export async function deployFlyRun(plan, fly, log, registrars, healthProbe) {
     const gate = (g) => ({ ok: false, gate: g });
     // 1.
@@ -60,7 +39,7 @@ export async function deployFlyRun(plan, fly, log, registrars, healthProbe) {
     if (missingValues)
         return gate(missingValues);
     // 3.
-    const appExists = await readList(fly, ["apps", "list", "--json"], (out) => listHasName(out, plan.appName));
+    const appExists = await readOutput(fly, "fly", ["apps", "list", "--json"], (out) => listHasName(out, plan.appName));
     if ("gate" in appExists)
         return gate(appExists.gate);
     if (appExists.value) {
@@ -77,7 +56,7 @@ export async function deployFlyRun(plan, fly, log, registrars, healthProbe) {
     // which machine (guest size + image) must fit on the host the volume is pinned to. Pre-creating one here placed it
     // blind, and a host with disk but no compute failed the deploy with `insufficient resources … with existing volume`.
     // 5.
-    const addresses = await readList(fly, ["ips", "list", "-a", plan.appName, "--json"], ingressAddresses);
+    const addresses = await readOutput(fly, "fly", ["ips", "list", "-a", plan.appName, "--json"], ingressAddresses);
     if ("gate" in addresses)
         return gate(addresses.gate);
     // Check-then-act PER FAMILY: an app that already holds one must still be given the other, or the gate between the
@@ -131,9 +110,20 @@ export async function deployFlyRun(plan, fly, log, registrars, healthProbe) {
         inspectHint: `the app itself deployed — inspect \`fly logs -a ${plan.appName}\`, then re-run once it answers ` +
             `(a re-run repeats the remote build)`,
         probe: healthProbe,
+        ...(plan.boxLogin ? { login: plan.boxLogin.command } : {}),
     });
     if (healthGate)
         return gate(healthGate);
+    const notLoggedIn = await plan.boxLogin?.run();
+    if (notLoggedIn) {
+        return gate(loginGate({
+            notLoggedIn,
+            channels: plan.channels,
+            log,
+            baseUrl,
+            afterLogin: "re-run `fastagent deploy fly --run` (it keeps the login)",
+        }));
+    }
     // 9.
     const registrationGateMsg = await registerWebhooks({
         baseUrl,

package/dist/deploy/preflight.d.ts

@@ -26,20 +26,22 @@ interface DeployFacts {
     values: ReadonlyMap<string, string>;
     /** That file, workspace-relative — the name every "set it here" message must use. */
     valueFile: string;
-    /** What satisfies model auth locally — an env-var name, an OAuth/stored label, or undefined. */
+    /**
+     * The variable the value file carries the model's key in (the provider's own, or a models.json `"$NAME"`), or
+     * undefined when no key travels that way ({@link credentialRoute}).
+     */
     modelAuth: string | undefined;
     /**
-     * The definition itself carries the model key (a models.json literal `apiKey`, or a `!command` run on the host), so
-     * there is nothing for `--run` to carry AND nothing to gate: `fastagent login` cannot serve a custom provider, so
-     * gating on it would strand a correctly configured agent.
+     * The provider the deployment must log in to itself (`fastagent login --deployment`): the model's credential does
+     * not travel, because it is neither a variable in the value file nor carried by the definition (a models.json
+     * literal `apiKey` or `!command`). Nothing from this machine's credentials file is ever copied, so a login on the
+     * box is its only holder.
      */
-    modelKeyInDefinition: boolean;
+    boxLogin: string | undefined;
     /** Every tool/routine/channel declaration — the names the value file must supply, by declaring file. */
     declaredSecrets: DeclaredSecret[];
     /** The runbook's variable list: the declared names, then everything else the value file carries. */
     secrets: DeploymentSecret[];
-    /** The project-level auth file `--run` reads to carry the credential (probed with the same path). */
-    authPath: string;
     /** Container facts shared by the plan and the generated Dockerfile — ONE source, so they can't drift. */
     container: ContainerInput;
     port: number;

package/dist/deploy/preflight.js

@@ -6,13 +6,16 @@ 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, resolveAuthPath } from "../engines/pi/config.js";
-import { AGENT_MODELS_FILE, exists } from "../paths.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 { agentModels } from "../engines/pi/agent-models.js";
 import { allSecrets } from "../declared-secrets.js";
-import { createPiModelRuntime, literalKeyProviders, isBuiltinProvider, machineModels, modelCredentialCarry, probeAuthSource, } from "../engines/pi/models.js";
+import { createPiModelRuntime, definitionKeyOf, environmentAuthSource, literalKeyProviders, isBuiltinProvider, machineModels, globalCatalogPath, inGlobalCatalog, interactiveLoginKind, loginProviders, } from "../engines/pi/models.js";
 import { CHANNEL_KINDS } from "../scaffold/add-channel.js";
 import { detectRuntime, readPackageJson } from "../runtime.js";
 import { fastagentVersion } from "../version.js";
@@ -147,21 +150,38 @@ async function gatherFacts(input, report) {
                 : ""));
     }
     await checkMachineModels(agentDir, modelSpec, report);
-    // Probe auth from the SAME project-level file the opener/login use, on the registry the DEPLOYED agent has: the
-    // machine's models.json does not ship, so an entry there (a gateway over a built-in provider, a key) must not decide
-    // how the credential reaches the host.
+    // 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);
-    const models = await createPiModelRuntime({ agentDir, auth: { path: authPath }, machineLayer: false });
-    let modelAuth = modelSpec ? await probeAuthSource(models, modelSpec) : undefined;
-    let modelKeyInDefinition = false;
-    // probeAuthSource answers "is it authenticated here", which is not the deploy question ("how does the credential
-    // REACH the host").
-    if (modelSpec && !isEnvKey(modelAuth)) {
-        const carry = modelCredentialCarry(models, modelSpec);
-        if (carry.envVar)
-            modelAuth = carry.envVar;
-        else
-            modelKeyInDefinition = carry.inDefinition;
+    // 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}`);
+    }
+    const route = modelSpec && !fromExtension ? await credentialRoute(agentDir, modelSpec, values) : {};
+    const modelAuth = route.envVar;
+    const boxLogin = route.boxLogin;
+    if (boxLogin !== undefined) {
+        if (!hasLogin(boxLogin)) {
+            report.issue(`no credential for ${modelSpec} reaches the deployment, and "${boxLogin}" has no login to run there — set ` +
+                `its API key in ${valueFile}`);
+        }
+        else {
+            report.note(`${modelSpec}: no credential ships with this deploy (this machine's logins and shell stay here) — once the ` +
+                `box is up, \`--run\` asks it: it keeps what it already authenticates ${boxLogin} with, else logs in ` +
+                `(\`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
@@ -254,14 +274,52 @@ async function gatherFacts(input, report) {
         values,
         valueFile,
         modelAuth,
-        modelKeyInDefinition,
-        authPath,
+        boxLogin,
         container,
         port,
         declaredSecrets,
         secrets: deploymentSecrets(modelAuth, declaredSecrets, values, valueFile),
     };
 }
+/**
+ * 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
+ *    already authenticate the provider.
+ */
+async function credentialRoute(agentDir, spec, values) {
+    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 } : {};
+    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);
+    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
@@ -285,6 +343,20 @@ async function checkMachineModels(agentDir, modelSpec, report) {
         report.issue(issue);
     }
 }
+/**
+ * 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
  * looks safe and is not: the manifest is always written, but only the generated Dockerfile sets
@@ -341,7 +413,7 @@ valueFile) {
     const source = fromEnv ? valueFile : "fastagent.config";
     // BOTH sources are checked, at the one point that reads them: a `provider`-less spec resolves to nothing on the
     // box, so letting `config.model` through would ship exactly the crash-loop this resolution exists to prevent —
-    // `probeAuthSource` reports "unconfigured" for it here and the failure only appears after deployment.
+    // the auth probe reports "unconfigured" for it here and the failure only appears after deployment.
     const spec = fromEnv || config.model;
     if (spec && !isModelSpec(spec))
         return { source, invalid: spec };

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

@@ -1,12 +1,15 @@
 /** `fastagent deploy railway` — the Railway deploy PLAN, computed from the resolved definition. */
 import type { DeclaredChannel } from "../../channels/discover.ts";
 import { type Artifact, type ContainerInput } from "../container.ts";
-import { type DeploymentSecret } from "../secrets.ts";
+import type { DeploymentSecret } from "../secrets.ts";
 export interface RailwayPlanInput extends ContainerInput {
     /** The service name to create (`railway add --service`). */
     serviceName: string;
-    /** What satisfies model auth locally: an env-var name, an OAuth/stored label, or undefined. */
-    modelAuth: string | undefined;
+    /**
+     * The provider the deployment logs in to itself (`fastagent login --deployment`): its credential is not a variable
+     * the plan carries.
+     */
+    boxLogin?: string;
     /**
      * Every declared channel and its ingress — the source of the secret list, the webhook steps, and whether App
      * Sleeping must stay off for an outbound connection.

package/dist/deploy/railway/plan.js

@@ -1,7 +1,7 @@
 import { webhookRunbook } from "../channel-ingress.js";
 import { containerArtifacts } from "../container.js";
+import { deploymentLoginCommand } from "../box-shell.js";
 import { CRON_CAN_BE_EXTERNAL, WAKEUPS_WHEN_ASLEEP, residencyFor } from "../residency.js";
-import { isEnvKey } from "../secrets.js";
 /** State root = the volume mount path, kept in lockstep. */
 const MOUNT = "/data";
 /** The `RAILWAY_DOCKERFILE_PATH` value for an agent under `prefix`. */
@@ -33,7 +33,7 @@ function railwayJson(prefix) {
 }
 /** Compute the Railway deploy plan from the resolved definition. */
 export function planRailwayDeploy(input) {
-    const { serviceName, modelAuth, channels } = input;
+    const { serviceName, channels } = input;
     // railway.json is namespaced under the agent dir too (the workspace may carry its own railway.toml/json for the
     // product).
     const configPath = `${input.agentPrefix}railway.json`;
@@ -60,7 +60,7 @@ export function planRailwayDeploy(input) {
         `# the later commands resolve it without --service (--run passes --service to stay non-interactive).`,
         `railway add --service ${serviceName}`,
         ``,
-        `# Persistent volume at ${MOUNT} — .state (sessions, channel state) + .secrets (seeded auth).`,
+        `# Persistent volume at ${MOUNT} — .state (sessions, channel state) + .secrets (the box's own login).`,
         `railway volume add --mount-path ${MOUNT}`,
         ``,
         `# Variables — set BEFORE the first deploy so the box boots with them. Railway injects PORT itself.`,
@@ -71,14 +71,12 @@ export function planRailwayDeploy(input) {
     if (secrets.length > 0) {
         runbook.push(`# Secrets:`, `#   ${secrets.map((s) => `${s.name}: ${s.hint}`).join("\n#   ")}`, `railway variables set ${secrets.map((s) => `${s.name}=<value>`).join(" ")}`);
     }
-    // Model-auth guidance: an env key becomes a variable above.
-    if (!isEnvKey(modelAuth)) {
-        runbook.push(modelAuth === undefined
-            ? `# Model auth: none found at the local auth path — a global \`fastagent login\` isn't read here; set FASTAGENT_AUTH_PATH (e.g. ~/.fastagent/.secrets/auth.json), or \`--run\` carries it automatically.`
-            : `# Model auth: your local auth is "${modelAuth}" — the plan can't read its value to set as a variable.`, `#   Set your provider API key as a variable (railway variables set KEY=...), OR place auth.json on the ${MOUNT} volume.`);
-    }
     runbook.push(``, `# OPTIONAL — the build already uses the agent's Dockerfile via RAILWAY_DOCKERFILE_PATH (set above),`, `# and Railway's default restart policy equals what ${configPath} declares (ON_FAILURE).`, `# Pointing the service at ${configPath} (Service → Settings → Config-as-code — dashboard-only) adds`, `# the /health healthcheck gate: a boot-crashing deploy is marked FAILED instead of going live dead.`, `# (Zero-downtime switching doesn't apply either way — the ${MOUNT} volume allows one active deployment.)`);
     runbook.push(``, `# Before a new definition release, run \`fastagent deploy railway\` to refresh the release manifest.`, `# Upload this workspace and build on Railway (no local Docker needed):`, `railway up`);
+    // The credential is created on the box, never carried: the box is then the only holder of its grant.
+    if (input.boxLogin) {
+        runbook.push(``, `# Model auth: once it is up, the deployment logs in to ${input.boxLogin} itself (from this workspace):`, `${deploymentLoginCommand("railway", input.boxLogin)}`);
+    }
     runbook.push(``, `# The volume keeps /data/base (including uncommitted work), .state and .secrets across restarts and deploys.`, `# Each generated release replaces only /data/base/${input.agentPrefix}; other workspace files are initialized once.`, input.shipsGit
         ? `# Railway uploads may strip .git. Clone inside the persistent workspace when collaboration needs history.`
         : `# To use Git for collaboration, add deploy: { apt: ["git"] }. Storage durability does not require Git.`);

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

@@ -1,7 +1,8 @@
 /** `fastagent deploy railway --run` — drive the Railway CLI to completion. */
+import type { BoxLoginStep } from "../box-shell.ts";
 import { type PublicHealthProbe, type Registrars } from "../channel-ingress.ts";
 import type { DeclaredChannel } from "../../channels/discover.ts";
-import type { CliRunner } from "../runner.ts";
+import { type CliRunner } from "../runner.ts";
 export interface RailwayRunPlan {
     /** Names both the project (`railway init --name`) and the service (`railway add --service`). */
     name: string;
@@ -10,10 +11,7 @@ export interface RailwayRunPlan {
      * in lockstep).
      */
     mountPath: string;
-    /**
-     * `KEY=value` secrets set one-per-`variable set --stdin`: the value file's variables + `FASTAGENT_AUTH_SEED` for a
-     * file credential.
-     */
+    /** `KEY=value` secrets set one-per-`variable set --stdin`: the value file's variables. */
     secrets: Record<string, string>;
     /** Declared names the value file supplies no value for — the run gates on these before any side effect. */
     missingSecrets: string[];
@@ -25,6 +23,11 @@ export interface RailwayRunPlan {
     intoLinked: boolean;
     /** `RAILWAY_DOCKERFILE_PATH` value (`/fastagent/Dockerfile`). */
     dockerfilePath: string;
+    /**
+     * Log the box in (`fastagent login --deployment`) once it is up and before any webhook is pointed at it: a channel pointed at
+     * a box with no model credential answers every message with a failure. Resolves a gate line, or undefined.
+     */
+    boxLogin?: BoxLoginStep;
 }
 /**
  * Done (with the live URL), or a gate the operator must clear before re-running (printed + non-zero exit by the CLI).
@@ -49,7 +52,8 @@ export declare function parseDomainUrl(stdout: string): string | undefined;
  * The status of the volume `railway volume list --json` shows mounted at `mountPath` ON `service`, or undefined when
  * that service has none there. The list is the whole PROJECT's: another service's volume, or one a deleted service
  * left behind (`serviceName: null` — deleting a service keeps its volume), sits at the same path and is not this
- * one. Read from any object carrying `mountPath` and `serviceName`, so a wrapper key moving does not matter.
+ * one. Read from any object carrying `mountPath` and `serviceName`, so a wrapper key moving does not matter. Output
+ * that is not JSON throws: read as "no volume", it would add a second one.
  */
 export declare function volumeOn(stdout: string, service: string, mountPath: string): string | undefined;
 export declare function deployRailwayRun(plan: RailwayRunPlan, railway: CliRunner, log: (msg: string) => void, registrars: Registrars, healthProbe?: PublicHealthProbe, sleep?: (ms: number) => Promise<void>): Promise<RailwayRunOutcome>;

package/dist/deploy/railway/run.js

@@ -1,5 +1,5 @@
-/** `fastagent deploy railway --run` — drive the Railway CLI to completion. */
-import { publicHealthGate, registerWebhooks } from "../channel-ingress.js";
+import { loginGate, publicHealthGate, registerWebhooks, } from "../channel-ingress.js";
+import { readOutput } from "../runner.js";
 import { missingValuesGate } from "../secrets.js";
 /** Whether `railway status --json` shows a linked project: non-empty stdout. */
 export function isLinked(stdout) {
@@ -49,7 +49,8 @@ export function parseDomainUrl(stdout) {
  * The status of the volume `railway volume list --json` shows mounted at `mountPath` ON `service`, or undefined when
  * that service has none there. The list is the whole PROJECT's: another service's volume, or one a deleted service
  * left behind (`serviceName: null` — deleting a service keeps its volume), sits at the same path and is not this
- * one. Read from any object carrying `mountPath` and `serviceName`, so a wrapper key moving does not matter.
+ * one. Read from any object carrying `mountPath` and `serviceName`, so a wrapper key moving does not matter. Output
+ * that is not JSON throws: read as "no volume", it would add a second one.
  */
 export function volumeOn(stdout, service, mountPath) {
     const walk = (v) => {
@@ -62,12 +63,7 @@ export function volumeOn(stdout, service, mountPath) {
             return typeof o.status === "string" ? o.status : "";
         return walk(Object.values(o));
     };
-    try {
-        return walk(JSON.parse(stdout));
-    }
-    catch {
-        return undefined;
-    }
+    return walk(JSON.parse(stdout));
 }
 /**
  * How long `--run` waits for a new volume to reach its service before deploying. Railway's `volume add` returns
@@ -113,7 +109,10 @@ export async function deployRailwayRun(plan, railway, log, registrars, healthPro
         // Create + link the service (init makes only a project); it precedes the volume, which has no --service flag and
         // rides the linked service.
         log(`creating service ${plan.name}…`);
-        if ((await railway(["add", "--service", plan.name])).code !== 0) {
+        // `--variables` with one of the machinery variables set just below: in a terminal, a bare `railway add` stops at
+        // "Enter a variable <esc to skip>" (5.62.1) and waits for a key nobody was told to press.
+        const addArgs = ["add", "--service", plan.name, "--variables", `FASTAGENT_STATE_DIR=${plan.mountPath}/.state`];
+        if ((await railway(addArgs)).code !== 0) {
             // Precise recovery, not "fix and re-run": init already created + linked the project, so a plain re-run hits the
             // linked-gate, and --into-linked SKIPS `add` and then fails at the volume (no service to ride).
             return gate(`\`railway add --service\` failed — \`railway init\` already created the project (this directory is now ` +
@@ -141,8 +140,11 @@ export async function deployRailwayRun(plan, railway, log, registrars, healthPro
         }
     }
     // 3c.
-    const volumeStatus = async () => volumeOn((await railway(["volume", "list", "--json"], { capture: true })).stdout, plan.name, plan.mountPath);
-    if ((await volumeStatus()) !== undefined) {
+    const volumeStatus = () => readOutput(railway, "railway", ["volume", "list", "--json"], (out) => volumeOn(out, plan.name, plan.mountPath));
+    const existing = await volumeStatus();
+    if ("gate" in existing)
+        return gate(existing.gate);
+    if (existing.value !== undefined) {
         log(`volume at ${plan.mountPath} exists on ${plan.name} — skipping`);
     }
     else {
@@ -154,7 +156,10 @@ export async function deployRailwayRun(plan, railway, log, registrars, healthPro
         // never seed a workspace onto a disk that vanishes on restart).
         let status;
         for (let waited = 0;; waited += VOLUME_POLL_MS) {
-            status = await volumeStatus();
+            const read = await volumeStatus();
+            if ("gate" in read)
+                return gate(read.gate);
+            status = read.value;
             if (status === "Ready" || waited >= VOLUME_ATTACH_TIMEOUT_MS)
                 break;
             await sleep(VOLUME_POLL_MS);
@@ -183,9 +188,20 @@ export async function deployRailwayRun(plan, railway, log, registrars, healthPro
         log,
         inspectHint: "the service itself deployed — inspect `railway logs`, then re-run once it answers",
         probe: healthProbe,
+        ...(plan.boxLogin ? { login: plan.boxLogin.command } : {}),
     });
     if (healthGate)
         return gate(healthGate);
+    const notLoggedIn = await plan.boxLogin?.run();
+    if (notLoggedIn) {
+        return gate(loginGate({
+            notLoggedIn,
+            channels: plan.channels,
+            log,
+            baseUrl: url,
+            afterLogin: "re-run `fastagent deploy railway --run --into-linked` (it keeps the login)",
+        }));
+    }
     // 7.
     const registrationGateMsg = await registerWebhooks({
         baseUrl: url,

package/dist/deploy/runner.d.ts

@@ -18,9 +18,25 @@ export type CliRunner = (args: string[], opts?: {
     input?: string;
     env?: NodeJS.ProcessEnv;
 }) => Promise<RunResult>;
+/**
+ * A read-only host-CLI query (`… list --json`), reduced to the question the next step asks of it — or the gate for an
+ * answer we cannot act on. A failed command and unreadable output both stop the run: read as "nothing there", either
+ * one would send the next step to create what already exists.
+ */
+export declare function readOutput<T>(run: CliRunner, bin: string, args: string[], read: (stdout: string) => T): Promise<{
+    value: T;
+} | {
+    gate: string;
+}>;
 /**
  * Production {@link CliRunner}: spawn `bin` in `cwd` (the workspace, so a build/upload context is the agent). stderr
  * is always inherited to the terminal.
  */
 export declare function spawnRunner(bin: string, cwd: string): CliRunner;
+/**
+ * The AWS CLI, as every command here runs it: with its pager off. Given a terminal, AWS CLI v2 pipes any output it
+ * prints through `less`, so `deploy agentcore --run` stopped at `(END)` after `ecr create-repository` until someone
+ * pressed `q`. ONE runner rather than a `--no-cli-pager` at each call: a call site that forgets is how that hang ships.
+ */
+export declare function awsRunner(cwd: string): CliRunner;
 export {};

package/dist/deploy/runner.js

@@ -1,6 +1,28 @@
 /** The host-CLI dispatcher seam, shared by every `deploy <host> --run` driver (fly/run.ts, railway/run.ts). */
 import { spawn } from "node:child_process";
 import { log } from "../log.js";
+/**
+ * A read-only host-CLI query (`… list --json`), reduced to the question the next step asks of it — or the gate for an
+ * answer we cannot act on. A failed command and unreadable output both stop the run: read as "nothing there", either
+ * one would send the next step to create what already exists.
+ */
+export async function readOutput(run, bin, args, read) {
+    // The command as RUN, not a restatement of it.
+    const cmd = `${bin} ${args.join(" ")}`;
+    const result = await run(args, { capture: true });
+    if (result.code !== 0)
+        return { gate: `\`${cmd}\` failed — see the ${bin} output above; fix and re-run` };
+    try {
+        return { value: read(result.stdout) };
+    }
+    catch (error) {
+        // The one place a parse failure is allowed to stop being an exception.
+        return {
+            gate: `\`${cmd}\` was unreadable (${error instanceof Error ? error.message : String(error)}) — ` +
+                `run it yourself and check the ${bin} CLI version; fix and re-run`,
+        };
+    }
+}
 /**
  * Production {@link CliRunner}: spawn `bin` in `cwd` (the workspace, so a build/upload context is the agent). stderr
  * is always inherited to the terminal.
@@ -39,3 +61,12 @@ export function spawnRunner(bin, cwd) {
         child.on("error", () => res({ code: 127, stdout: "", stderr: opts?.captureStderr ? "" : undefined })); // ENOENT
     });
 }
+/**
+ * The AWS CLI, as every command here runs it: with its pager off. Given a terminal, AWS CLI v2 pipes any output it
+ * prints through `less`, so `deploy agentcore --run` stopped at `(END)` after `ecr create-repository` until someone
+ * pressed `q`. ONE runner rather than a `--no-cli-pager` at each call: a call site that forgets is how that hang ships.
+ */
+export function awsRunner(cwd) {
+    const aws = spawnRunner("aws", cwd);
+    return (args, opts) => aws(args, { ...opts, env: { ...opts?.env, AWS_PAGER: "" } });
+}

package/dist/deploy/secrets.d.ts

@@ -19,21 +19,17 @@ export interface DeploymentSecret {
  */
 export declare function deploymentSecrets(modelAuth: string | undefined, declared: readonly DeclaredSecret[], values: ReadonlyMap<string, string>, valueFile: string): DeploymentSecret[];
 /**
- * Assemble the VALUES a `--run` deploy sets on the host: every variable the value file carries, plus the local
- * credential. Never minted here.
+ * Assemble the VALUES a `--run` deploy sets on the host: every variable the value file carries. Never minted here.
  *
  * `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.
+ *
+ * No credentials file travels: a model that does not authenticate through a variable (or its own definition) logs in
+ * on the deployment itself (`fastagent login --deployment`), so the box is the only holder of its grant.
  */
 export declare function assembleSecrets(input: {
     modelAuth: string | undefined;
-    /**
-     * The definition carries the model key itself (a models.json literal `apiKey` / `!command`): there is no value to
-     * carry and no gate to raise.
-     */
-    modelKeyInDefinition?: boolean;
-    authFile: Buffer | undefined;
     /** Every name the definition declared it needs — what must have a value. */
     declared?: readonly DeclaredSecret[];
     /** The selected value file's contents (`loadEnvValues`). The ONLY source of operator-supplied values. */
@@ -41,7 +37,6 @@ export declare function assembleSecrets(input: {
 }): {
     secrets: Record<string, string>;
     missingSecrets: string[];
-    needsModelCredential: boolean;
 };
 /**
  * The ONE refusal for declared names the deployed environment does not supply a value for — every host reaches it
@@ -49,10 +44,6 @@ export declare function assembleSecrets(input: {
  * name missing from it is missing from the deployment, whatever platform receives it.
  */
 export declare function missingValuesGate(missing: readonly string[], valueFile: string): string | undefined;
-/** The bytes to seed to the auth file, or undefined to leave it alone. */
-export declare function authSeedBytes(seed: string | undefined, fileExists: boolean): Buffer | undefined;
-/** `FASTAGENT_AUTH_SEED` (+ `_2`, …): the base64 auth.json a deploy carries. */
-export declare function collectAuthSeed(env: NodeJS.ProcessEnv): string | undefined;
 /**
  * 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.