@fastagent-sh/fastagent 0.22.0 → 0.23.0

package/dist/deploy/preflight.js

@@ -6,13 +6,15 @@ 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 { 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 +149,30 @@ 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;
+    const route = modelSpec ? 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 +265,43 @@ 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 };
+}
+/** 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 +325,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 +395,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.

package/dist/deploy/secrets.js

@@ -30,7 +30,7 @@ const DEPLOY_OWNED = new Set([
 ]);
 /** Is `name` one the deployment sets itself (see {@link DEPLOY_OWNED}), including the chunked carriers? */
 function isDeployOwned(name) {
-    return DEPLOY_OWNED.has(name) || /^FASTAGENT_(AUTH_SEED|ENV)(_\d+)?$/.test(name);
+    return DEPLOY_OWNED.has(name) || /^FASTAGENT_ENV(_\d+)?$/.test(name);
 }
 /** The value-file variables that travel: everything with a value that the deployment does not set itself. */
 function carriedValues(values) {
@@ -59,36 +59,25 @@ export function deploymentSecrets(modelAuth, declared, values, valueFile) {
     return secrets;
 }
 /**
- * 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 function assembleSecrets(input) {
     const secrets = carriedValues(input.values);
     const missingSecrets = [];
-    let needsModelCredential = false;
-    if (isEnvKey(input.modelAuth)) {
-        if (!secrets[input.modelAuth])
-            missingSecrets.push(input.modelAuth); // `.env` remediation fits
-    }
-    else if (input.authFile) {
-        secrets.FASTAGENT_AUTH_SEED = input.authFile.toString("base64");
-    }
-    else if (input.modelKeyInDefinition) {
-        // The definition authenticates itself (models.json literal key, or a command run on the host), so it travels in
-        // the image with everything else.
-    }
-    else {
-        needsModelCredential = true; // no env key, no auth.json — `fastagent login` remediation
-    }
+    if (isEnvKey(input.modelAuth) && !secrets[input.modelAuth])
+        missingSecrets.push(input.modelAuth);
     for (const { name } of dedupeSecrets(input.declared ?? [])) {
         if (!secrets[name] && !missingSecrets.includes(name))
             missingSecrets.push(name);
     }
-    return { secrets, missingSecrets, needsModelCredential };
+    return { secrets, missingSecrets };
 }
 /**
  * The ONE refusal for declared names the deployed environment does not supply a value for — every host reaches it
@@ -101,10 +90,6 @@ export function missingValuesGate(missing, valueFile) {
     return (`no value for: ${missing.join(", ")} — the deployed environment is declared by ${valueFile}, and this deploy ` +
         `reads only that file (exporting the variable here does not reach the deployment). Add them there and re-run`);
 }
-/** The bytes to seed to the auth file, or undefined to leave it alone. */
-export function authSeedBytes(seed, fileExists) {
-    return !seed || fileExists ? undefined : Buffer.from(seed, "base64");
-}
 /**
  * Collect a (possibly CHUNKED) carrier from the environment: `<name>` plus numbered continuations (`_2`, `_3`, …)
  * concatenated in order. A host whose env values have a length cap splits a long value this way.
@@ -122,10 +107,6 @@ function collectChunked(env, name) {
     }
     return value;
 }
-/** `FASTAGENT_AUTH_SEED` (+ `_2`, …): the base64 auth.json a deploy carries. */
-export function collectAuthSeed(env) {
-    return collectChunked(env, "FASTAGENT_AUTH_SEED");
-}
 /**
  * `FASTAGENT_ENV` (+ `_2`, …): the carried variables as ONE base64 JSON object, for a host whose deployment artifact
  * must not depend on which names the value file holds (AgentCore's template is committed and gated on drift). The

package/dist/dev-supervisor.js

@@ -5,7 +5,7 @@
 import { spawn } from "node:child_process";
 import { relative, sep } from "node:path";
 import { watch as watchTree } from "chokidar";
-import { AGENT_CONFIG_FILE, AGENT_MODELS_FILE, resolveStateRoot, isUnderDir } from "./paths.js";
+import { AGENT_CONFIG_FILE, AGENT_MODEL_CATALOG_FILE, AGENT_MODELS_FILE, resolveStateRoot, isUnderDir, } from "./paths.js";
 import { dotEnvPath } from "./env.js";
 import { log } from "./log.js";
 import { openExternalUrl } from "./open-url.js";
@@ -14,7 +14,7 @@ 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, .secrets/.env`;
+const WATCHED_HINT = `${CODE_INPUT_DIRS.map((dir) => `${dir}/`).join(", ")}, package.json, fastagent.config.ts, models.json, models-store.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.
@@ -33,6 +33,9 @@ export function devWatchIgnored(root, envFile) {
         // 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]))
             return false;

package/dist/engines/pi/agent-models.d.ts

@@ -0,0 +1,70 @@
+/**
+ * An agent's MODEL ENVIRONMENT as one value: the credential store its turns authenticate through, the registry they
+ * resolve models against, and what authenticates a provider there. Every reader builds it through {@link agentModels}
+ * — the opener and L2, the startup report and a deployed box's `login --if-missing`, `info`, the first-run picker,
+ * login, the model list — so none of them can read other credential layers or another registry than the runtime
+ * does. Each used to compose these parts itself, and two of those copies drifted from the rule (#636, #660).
+ */
+import type { Credential, CredentialStore, Models, Provider } from "@earendil-works/pi-ai";
+import { ModelRuntime } from "@earendil-works/pi-coding-agent";
+import { type AuthLayers, type CredentialSourceOptions, type FastagentAuthOptions } from "./auth.ts";
+/** What authenticates one provider for an agent ({@link AgentModels.authStatus}). */
+interface AuthStatus {
+    /** What satisfies it now (`OAuth`, `stored credential`, an env variable's name), after a due refresh. */
+    source?: string;
+    /** Why resolving it failed (a corrupt entry, a refresh the provider refused), when it did. */
+    error?: string;
+    /** The file that holds the stored credential, or the one a login would write; absent over a caller's store. */
+    path?: string;
+    /** The kind of credential the store holds for it, usable or not. */
+    stored?: Credential["type"];
+    /**
+     * An env variable that also authenticates it but goes unused, because pi lets a stored credential own its provider
+     * — a key added to a deployment's value file after the box was logged in, typically.
+     */
+    shadowed?: string;
+}
+export interface AgentModels {
+    /** The credentials files behind {@link credentials}; absent when the caller supplied its own store. */
+    auth?: AuthLayers;
+    credentials: CredentialStore;
+    /**
+     * The registry: pi's built-ins, plus (with a directory) the agent's `models.json` and model catalog over the
+     * machine's, plus `providers`. Built on first use and shared after, so a malformed file fails the first reader.
+     */
+    runtime(): Promise<ModelRuntime>;
+    /**
+     * What authenticates `provider` here, resolved exactly as a turn resolves it: the ONE answer the startup report and a
+     * deployed box's `login --if-missing` both give. `modelId` picks the model to probe with; the provider's first one
+     * otherwise (auth is provider-scoped).
+     */
+    authStatus(provider: string, modelId?: string): Promise<AuthStatus>;
+}
+export interface AgentModelsOptions {
+    /** Extra providers registered on top of the built-ins (a same id replaces one). */
+    providers?: readonly Provider[];
+    /**
+     * Layer the machine's models.json and model catalog under the agent's (default). Off for the registry a DEPLOYED
+     * agent has, since neither ships.
+     */
+    machineLayer?: boolean;
+}
+/**
+ * The model environment of the agent in `agentDir` (or, without one, of a caller with no directory: pi's built-ins
+ * over the named or global credentials file). A supplied `credentialStore` is used as given; otherwise the files:
+ * the directory's own layers ({@link resolveAuthLayers}), or the named file or the global one.
+ */
+export declare function agentModels(agentDir: string | undefined, source?: {
+    authPath?: string;
+    credentialStore?: undefined;
+} & FastagentAuthOptions, options?: AgentModelsOptions): AgentModels & {
+    auth: AuthLayers;
+};
+export declare function agentModels(agentDir: string | undefined, source?: CredentialSourceOptions & FastagentAuthOptions, options?: AgentModelsOptions): AgentModels;
+export interface CreatePiModelsOptions extends FastagentAuthOptions, CredentialSourceOptions {
+    /** Extra providers registered on top of the built-ins (same id overrides a built-in). */
+    providers?: Provider[];
+}
+/** A `Models` with every built-in pi provider, wired to fastagent's auth. */
+export declare function createPiModels(options?: CreatePiModelsOptions): Models;
+export {};