@fastagent-sh/fastagent 0.22.0 → 0.23.0

package/dist/cli/commands/deploy/docker.js

@@ -2,20 +2,25 @@
 import { mkdir, writeFile } from "node:fs/promises";
 import { basename, dirname, join, relative, resolve } from "node:path";
 import { webhookPaths } from "../../../deploy/channel-ingress.js";
-import { composeHasTunnelService, isGeneratedCompose, planDockerDeploy, toDockerProjectName, } from "../../../deploy/docker/plan.js";
+import { DOCKER_COMPOSE_FILE, composeHasTunnelService, isGeneratedCompose, planDockerDeploy, toDockerProjectName, } from "../../../deploy/docker/plan.js";
 import { deployDockerRun } from "../../../deploy/docker/run.js";
 import { spawnRunner } from "../../../deploy/runner.js";
 import { openExternalUrl } from "../../../open-url.js";
 import { SECRETS_DIRNAME, SECRET_FILE_MODE, exists, readTextIfExists, resolveStateRoot, } from "../../../paths.js";
 import { dotEnvPath } from "../../../env.js";
 import { announceWebhooks } from "../../../tunnel.js";
+import { assembleSecrets } from "../../../deploy/secrets.js";
+import { processShell } from "../../../deploy/box-shell.js";
 import { failStartup } from "../../fail.js";
-import { carryCredentials } from "./shared.js";
+import { isInteractive } from "../../shared.js";
+import { boxLoginStep } from "./shared.js";
 export const dockerHost = {
-    isOurs: (path, content) => path.endsWith("fastagent.compose.yml") && isGeneratedCompose(content),
+    isOurs: (path, content) => path.endsWith(DOCKER_COMPOSE_FILE) && isGeneratedCompose(content),
+    artifact: DOCKER_COMPOSE_FILE,
+    shell: async ({ agentDir, workspace }) => composeShell(`${basename(agentDir)}/${DOCKER_COMPOSE_FILE}`, workspace),
     async deploy(ctx) {
         const { opts, agentDir, workspace, channels, webhookChannels, pre, write } = ctx;
-        const { modelAuth, modelKeyInDefinition, authPath, container, port, declaredSecrets, values, valueFile } = pre;
+        const { modelAuth, boxLogin, container, port, declaredSecrets, values, valueFile } = pre;
         // The generated Compose names `<agent>/.secrets/.env` unconditionally, so it has to be there — Compose refuses
         // an `env_file` entry pointing at a missing path, and this floor predates `required: false` (Compose 2.24).
         // Creating it empty is honest: a deployment that declares nothing declares it in an empty file.
@@ -51,7 +56,7 @@ export const dockerHost = {
         const dockerPlan = (tunnel) => planDockerDeploy({
             projectName,
             port,
-            modelAuth,
+            boxLogin,
             channels,
             tunnel,
             secrets: pre.secrets,
@@ -84,8 +89,8 @@ export const dockerHost = {
                 port,
                 requireTunnel: requestedTunnel,
                 modelAuth,
-                modelKeyInDefinition,
-                authPath,
+                boxLogin,
+                input: opts.input !== false && isInteractive(),
                 channels,
                 declaredSecrets,
                 values,
@@ -100,21 +105,23 @@ export const dockerHost = {
         return;
     },
 };
-/**
- * `deploy docker --run`: carry local credentials into Compose's child environment, then reconcile the user-owned local
- * topology.
- */
+/** `deploy docker --run`: reconcile the user-owned local topology, then log the box in if it must. */
 async function runDeployDocker(params) {
     const { agentDir, workspace, composeFile, port, requireTunnel, channels } = params;
-    const { secrets, missingSecrets, needsModelCredential } = await carryCredentials(params);
+    const { secrets, missingSecrets } = assembleSecrets({
+        modelAuth: params.modelAuth,
+        declared: params.declaredSecrets,
+        values: params.values,
+    });
     const outcome = await deployDockerRun({
         composeFile,
         port,
         secrets,
         missingSecrets,
         valueFile: params.valueFile,
-        needsModelCredential,
         requireTunnel,
+        channels,
+        ...boxLoginStep("docker", params, () => composeShell(composeFile, workspace)),
         announce: (tunnelUrl) => announceWebhooks(agentDir, tunnelUrl, channels, {
             openUrl: openExternalUrl,
             stateRoot: resolveStateRoot(agentDir),
@@ -144,3 +151,7 @@ async function runDeployDocker(params) {
             `default webhook path(s): ${paths.join(", ")} (or your remapped channel routes)`);
     }
 }
+/** `docker compose exec` into the running agent service. */
+function composeShell(composeFile, workspace) {
+    return processShell("docker", (command) => ["compose", "-f", composeFile, "exec", "-T", "agent", "sh", "-c", command], workspace);
+}

package/dist/cli/commands/deploy/fly.js

@@ -5,13 +5,21 @@ import { deployFlyRun } from "../../../deploy/fly/run.js";
 import { spawnRunner } from "../../../deploy/runner.js";
 import { readTextIfExists } from "../../../paths.js";
 import { residencyFor } from "../../../deploy/residency.js";
+import { assembleSecrets } from "../../../deploy/secrets.js";
+import { processShell } from "../../../deploy/box-shell.js";
 import { failStartup } from "../../fail.js";
-import { carryCredentials, gateOnModelCredential, registrarsFor } from "./shared.js";
+import { isInteractive } from "../../shared.js";
+import { boxLoginStep, registrarsFor } from "./shared.js";
 export const flyHost = {
     isOurs: (path, content) => path.endsWith("fly.toml") && isGeneratedFlyToml(content),
+    artifact: "fly.toml",
+    async shell({ agentDir, workspace }) {
+        const flyToml = await readTextIfExists(join(agentDir, "fly.toml"));
+        return flyShell((flyToml && parseFlyAppName(flyToml)) ?? toFlyAppName(basename(workspace)), workspace);
+    },
     async deploy(ctx) {
         const { opts, agentDir, workspace, channels, pre, write } = ctx;
-        const { hasCron, modelAuth, modelKeyInDefinition, authPath, container, port, declaredSecrets, values, valueFile } = pre;
+        const { hasCron, modelAuth, boxLogin, container, port, declaredSecrets, values, valueFile } = pre;
         // Two consistent modes.
         const flyTomlPath = join(agentDir, "fly.toml");
         const flyToml = await readTextIfExists(flyTomlPath).catch(failStartup);
@@ -43,7 +51,7 @@ export const flyHost = {
         const plan = planFlyDeploy({
             appName,
             port,
-            modelAuth,
+            boxLogin,
             channels,
             secrets: pre.secrets,
             hasCron,
@@ -57,8 +65,8 @@ export const flyHost = {
                 agentPrefix: container.agentPrefix,
                 appName,
                 modelAuth,
-                modelKeyInDefinition,
-                authPath,
+                boxLogin,
+                input: opts.input !== false && isInteractive(),
                 channels,
                 declaredSecrets,
                 values,
@@ -76,8 +84,11 @@ async function runDeployFly(params) {
     if ((await fly(["version"], { capture: true })).code === 127) {
         failStartup(new Error(`flyctl not found — install it: https://fly.io/docs/flyctl/install, then re-run`));
     }
-    const { secrets, missingSecrets, needsModelCredential } = await carryCredentials(params);
-    gateOnModelCredential(needsModelCredential);
+    const { secrets, missingSecrets } = assembleSecrets({
+        modelAuth: params.modelAuth,
+        declared: params.declaredSecrets,
+        values: params.values,
+    });
     const outcome = await deployFlyRun({
         appName,
         secrets,
@@ -86,8 +97,20 @@ async function runDeployFly(params) {
         channels,
         flyConfig: `${agentPrefix}fly.toml`,
         dockerfile: `${agentPrefix}Dockerfile`,
+        ...boxLoginStep("fly", params, () => flyShell(appName, workspace)),
     }, fly, (m) => console.error(`[fastagent] ${m}`), registrarsFor(agentDir));
     if (!outcome.ok)
         failStartup(new Error(`deploy stopped: ${outcome.gate}`));
     console.error(`[fastagent] deployed → https://${appName}.fly.dev`);
 }
+/** `fly ssh console` into the app's machine, woken first: a suspended machine has no shell to open. */
+function flyShell(app, workspace) {
+    return {
+        ...processShell("fly", (command) => ["ssh", "console", "--app", app, "--quiet", "--command", `sh -c '${command}'`], workspace),
+        // `fly ssh` fails with "no started VMs" while the machine is suspended, and a request is what resumes it. The
+        // answer is not the point: a machine that stays down makes the shell fail right after, with Fly's own reason.
+        wake: async () => {
+            await fetch(`https://${app}.fly.dev/health`, { signal: AbortSignal.timeout(30_000) }).catch(() => undefined);
+        },
+    };
+}

package/dist/cli/commands/deploy/railway.js

@@ -6,17 +6,22 @@ import { basename } from "node:path";
 import { dockerfilePathVar, isGeneratedRailwayJson, planRailwayDeploy, toRailwayName, } from "../../../deploy/railway/plan.js";
 import { deployRailwayRun } from "../../../deploy/railway/run.js";
 import { spawnRunner } from "../../../deploy/runner.js";
+import { assembleSecrets } from "../../../deploy/secrets.js";
+import { processShell } from "../../../deploy/box-shell.js";
 import { failStartup } from "../../fail.js";
-import { carryCredentials, gateOnModelCredential, registrarsFor } from "./shared.js";
+import { isInteractive } from "../../shared.js";
+import { boxLoginStep, registrarsFor } from "./shared.js";
 export const railwayHost = {
     isOurs: (path, content) => path.endsWith("railway.json") && isGeneratedRailwayJson(content),
+    artifact: "railway.json",
+    shell: async ({ workspace }) => railwayShell(toRailwayName(basename(workspace)), workspace),
     async deploy(ctx) {
         const { opts, agentDir, workspace, pre, channels, write } = ctx;
-        const { hasCron, modelAuth, modelKeyInDefinition, authPath, container, declaredSecrets, values, valueFile } = pre;
+        const { hasCron, modelAuth, boxLogin, container, declaredSecrets, values, valueFile } = pre;
         const serviceName = toRailwayName(basename(workspace));
         const plan = planRailwayDeploy({
             serviceName,
-            modelAuth,
+            boxLogin,
             channels,
             secrets: pre.secrets,
             hasCron,
@@ -36,8 +41,8 @@ export const railwayHost = {
                 workspace,
                 name: serviceName,
                 modelAuth,
-                modelKeyInDefinition,
-                authPath,
+                boxLogin,
+                input: opts.input !== false && isInteractive(),
                 channels,
                 declaredSecrets,
                 values,
@@ -58,8 +63,11 @@ async function runDeployRailway(params) {
     if ((await railway(["--version"], { capture: true })).code === 127) {
         failStartup(new Error(`railway CLI not found — install it: https://docs.railway.com/guides/cli, then re-run`));
     }
-    const { secrets, missingSecrets, needsModelCredential } = await carryCredentials(params);
-    gateOnModelCredential(needsModelCredential);
+    const { secrets, missingSecrets } = assembleSecrets({
+        modelAuth: params.modelAuth,
+        declared: params.declaredSecrets,
+        values: params.values,
+    });
     const outcome = await deployRailwayRun({
         name,
         mountPath: "/data",
@@ -69,8 +77,14 @@ async function runDeployRailway(params) {
         channels,
         intoLinked,
         dockerfilePath,
+        ...boxLoginStep("railway", params, () => railwayShell(name, workspace)),
     }, railway, (m) => console.error(`[fastagent] ${m}`), registrarsFor(agentDir));
     if (!outcome.ok)
         failStartup(new Error(`deploy stopped: ${outcome.gate}`));
     console.error(`[fastagent] deployed → ${outcome.url}`);
 }
+/** `railway ssh` into the service, in the project and environment this directory is linked to. */
+function railwayShell(service, workspace) {
+    // One quoted word: the command reaches the box as ONE line its shell parses, the way OpenSSH hands it over.
+    return processShell("railway", (command) => ["ssh", "--service", service, "--", `sh -c '${command}'`], workspace);
+}

package/dist/cli/commands/deploy/shared.d.ts

@@ -2,7 +2,9 @@ import type { DeclaredChannel } from "../../../channels/discover.ts";
 import type { Registrars } from "../../../deploy/channel-ingress.ts";
 import type { DeployPreflight } from "../../../deploy/preflight.ts";
 import type { FastagentConfig } from "../../../engines/pi/config.ts";
-import type { DeclaredSecret } from "../../../declared-secrets.ts";
+import { type ResolvedPlacement } from "../../../paths.ts";
+import { type BoxLoginStep, type BoxShell } from "../../../deploy/box-shell.ts";
+import type { DeployHost } from "../../../deploy/hosts.ts";
 export interface DeployOptions {
     run?: boolean;
     tunnel?: boolean;
@@ -39,6 +41,10 @@ interface DeployContext {
 export interface HostDeploy {
     /** Did this host generate the file at `path`? */
     isOurs(path: string, content: string): boolean;
+    /** The file in the agent dir whose presence says this workspace deploys to the host. */
+    artifact: string;
+    /** The shell into this workspace's running box (`fastagent login --deployment`). */
+    shell(placement: ResolvedPlacement): Promise<BoxShell>;
     /**
      * Plan the artifacts from the pre-flight facts and what is on disk, write them, then either drive the host CLI
      * (`--run`) or print the runbook.
@@ -48,23 +54,18 @@ export interface HostDeploy {
 /** The registrars every host driver gets. */
 export declare function registrarsFor(agentDir: string): Registrars;
 /**
- * The `--run` carry, for every host: the value file's variables plus the local model credential (an env key, or the
- * whole auth.json as a `FASTAGENT_AUTH_SEED`).
+ * The login `--run` starts on the box it just deployed, before any webhook is pointed at it (a host driver's `boxLogin`): for
+ * the model's provider, keeping a credential the box already holds (a redeploy), and asking only when a person can
+ * answer. None when the model's credential travels as a variable.
  */
-export declare function carryCredentials(params: {
-    modelAuth: string | undefined;
-    modelKeyInDefinition: boolean;
-    authPath: string;
-    declaredSecrets: readonly DeclaredSecret[];
-    /** The deployed environment's declaration, from the pre-flight's single read. */
-    values: ReadonlyMap<string, string>;
-}): Promise<{
-    secrets: Record<string, string>;
-    missingSecrets: string[];
-    needsModelCredential: boolean;
-}>;
-/** Gate a `--run` that has no model credential to carry. */
-export declare function gateOnModelCredential(needsModelCredential: boolean): void;
+export declare function boxLoginStep<Args extends unknown[]>(host: DeployHost, params: ResolvedPlacement & {
+    boxLogin: string | undefined;
+    input: boolean;
+}, 
+/** The shell, from whatever the driver learns only after deploying (AgentCore's runtime ARN). */
+shell: (...args: Args) => BoxShell): {
+    boxLogin?: BoxLoginStep<Args>;
+};
 /** One artifact's verdict under the ownership rule: the bytes to write, or `undefined` to keep what is there. */
 type ArtifactStep = {
     abs: string;

package/dist/cli/commands/deploy/shared.js

@@ -1,6 +1,6 @@
 /**
- * What every host's deploy command shares: the context the dispatcher hands a host, the artifact writer with its
- * ownership rule, and the `--run` credential carry.
+ * What every host's deploy command shares: the context the dispatcher hands a host and the artifact writer with its
+ * ownership rule.
  */
 import { mkdir, readFile, writeFile } from "node:fs/promises";
 import { dirname, join } from "node:path";
@@ -10,9 +10,9 @@ import { registerSlackWebhook } from "../../../channels/slack/register-webhook.j
 import { registerTelegramWebhook } from "../../../channels/telegram/register-webhook.js";
 import { isGeneratedDockerfile, isGeneratedDockerignore } from "../../../deploy/container.js";
 import { RELEASE_FILE } from "../../../deploy/workspace.js";
-import { assembleSecrets } from "../../../deploy/secrets.js";
 import { exists, resolveStateRoot } from "../../../paths.js";
-import { failStartup } from "../../fail.js";
+import { deploymentLoginCommand } from "../../../deploy/box-shell.js";
+import { loginOnBox } from "../../box-login.js";
 /** The registrars every host driver gets. */
 export function registrarsFor(agentDir) {
     const attempts = DEPLOY_REGISTRATION_ATTEMPTS;
@@ -23,24 +23,23 @@ export function registrarsFor(agentDir) {
     };
 }
 /**
- * The `--run` carry, for every host: the value file's variables plus the local model credential (an env key, or the
- * whole auth.json as a `FASTAGENT_AUTH_SEED`).
+ * The login `--run` starts on the box it just deployed, before any webhook is pointed at it (a host driver's `boxLogin`): for
+ * the model's provider, keeping a credential the box already holds (a redeploy), and asking only when a person can
+ * answer. None when the model's credential travels as a variable.
  */
-export async function carryCredentials(params) {
-    const { modelAuth, modelKeyInDefinition, authPath, declaredSecrets, values } = params;
-    return assembleSecrets({
-        modelAuth,
-        modelKeyInDefinition,
-        authFile: (await exists(authPath)) ? await readFile(authPath) : undefined,
-        declared: declaredSecrets,
-        values,
-    });
-}
-/** Gate a `--run` that has no model credential to carry. */
-export function gateOnModelCredential(needsModelCredential) {
-    if (!needsModelCredential)
-        return;
-    failStartup(new Error(`deploy stopped: no model credential — run \`fastagent login\`, or set a provider API key in .env, then re-run`));
+export function boxLoginStep(host, params, 
+/** The shell, from whatever the driver learns only after deploying (AgentCore's runtime ARN). */
+shell) {
+    const provider = params.boxLogin;
+    if (provider === undefined)
+        return {};
+    const placement = { agentDir: params.agentDir, workspace: params.workspace };
+    return {
+        boxLogin: {
+            command: deploymentLoginCommand(host, provider),
+            run: (...args) => loginOnBox({ host, shell: shell(...args), placement, provider, ifMissing: true, input: params.input }),
+        },
+    };
 }
 /**
  * Decide what happens to each generated artifact under `target`, under ONE ownership rule — reading only, so a

package/dist/cli/commands/destroy.js

@@ -2,7 +2,7 @@
 import { basename, resolve } from "node:path";
 import { destroyAgentcoreDeployment } from "../../deploy/agentcore/destroy.js";
 import { agentcoreName } from "../../deploy/agentcore/plan.js";
-import { spawnRunner } from "../../deploy/runner.js";
+import { awsRunner } from "../../deploy/runner.js";
 import { enterAgentEnv } from "../../env.js";
 import { failStartup, failUsage, placementOrExit } from "../fail.js";
 export async function runDestroy(host, dirArg, opts) {
@@ -15,7 +15,7 @@ export async function runDestroy(host, dirArg, opts) {
     const placement = placementOrExit(resolve(dirArg));
     enterAgentEnv(placement.agentDir); // AWS_PROFILE/region/proxy may be definition-local, as on deploy
     const name = agentcoreName(basename(placement.workspace));
-    const outcome = await destroyAgentcoreDeployment({ name, run: opts.run === true }, spawnRunner("aws", placement.workspace), (message) => console.error(`[fastagent] destroy: ${message}`));
+    const outcome = await destroyAgentcoreDeployment({ name, run: opts.run === true }, awsRunner(placement.workspace), (message) => console.error(`[fastagent] destroy: ${message}`));
     if (!outcome.ok) {
         // THE WHOLE PICTURE, before the gate: a half-finished teardown is exactly when an operator needs to know
         // what is out there, what is already gone, and what the retry still has to reach.

package/dist/cli/commands/info.js

@@ -2,8 +2,9 @@
 import { resolve } from "node:path";
 import { enterAgentEnv } from "../../env.js";
 import { inspectChannels } from "../../channels/discover.js";
-import { loadConfig, providerOf, resolveAuthLayers, resolveModel, resolveModelSpec } from "../../engines/pi/config.js";
-import { createPiModelRuntime, machineModels } from "../../engines/pi/models.js";
+import { loadConfig, providerOf, resolveModel, resolveModelSpec } from "../../engines/pi/config.js";
+import { machineModels } from "../../engines/pi/models.js";
+import { agentModels } from "../../engines/pi/agent-models.js";
 import { resolveSessionsDir, resolveStateRoot } from "../../paths.js";
 import { CODING_TOOL_NAMES, resolveAgentTools } from "../../engines/pi/create.js";
 import { loadAgentDefinition } from "../../engines/pi/definition.js";
@@ -74,13 +75,15 @@ export async function runInfo(dirArg, opts) {
     const sessionsDir = resolveSessionsDir(agentDir);
     // Both layers: "what is this agent's state" is the question `info` answers, and a credential it runs on can live in
     // a file the agent dir does not contain.
-    const auth = resolveAuthLayers(agentDir);
+    const models = agentModels(agentDir);
+    const { auth } = models;
     // RESOLVE the spec, do not just echo it: a spec is only real once its provider/model exist in the agent's own
     // surface (built-ins + its models.json), which is exactly what a custom endpoint changes.
     const modelError = modelSpec
-        ? await createPiModelRuntime({ agentDir, auth })
-            .then((models) => {
-            resolveModel(models, modelSpec);
+        ? await models
+            .runtime()
+            .then((runtime) => {
+            resolveModel(runtime, modelSpec);
             return undefined;
         })
             .catch((error) => error.message)

package/dist/cli/commands/invoke.js

@@ -6,12 +6,12 @@ import { failStartup } from "../fail.js";
 import { enterAgentCommand, reportAuth } from "../shared.js";
 export async function runInvoke(message, dirArg, opts) {
     const placement = await enterAgentCommand(dirArg, opts);
-    const { agent, modelSpec, auth } = await createPiAgentFromDir(placement.agentDir, {
+    const { agent, modelSpec, models } = await createPiAgentFromDir(placement.agentDir, {
         model: opts.model,
     }).catch(failStartup);
     // BOTH directories, like dev/start: which agent ran, and what it worked on.
     console.error(`[fastagent] invoke: ${placement.agentDir} (workspace ${placement.workspace}, ${modelSpec})`);
-    await reportAuth(placement.agentDir, modelSpec, auth);
+    await reportAuth(models, modelSpec);
     // Fresh session per invoke (one-shot, no resume). runInvokeStream maps events→IO: reply→stdout,
     // tool/failure→stderr, exit 1 iff the turn failed (so CI can gate on it).
     const exitCode = await runInvokeStream(agent.invoke({ session: randomUUID() }, { text: message }), (text) => process.stdout.write(text), (line) => console.error(line));

package/dist/cli/commands/login.d.ts

@@ -1,7 +1,13 @@
 export interface LoginOptions {
-    /** `-g`: store in the user-global file every agent on this machine falls back to. */
+    /** `-g`: store in the user-global file, which an agent reads for a provider it has no other credential for. */
     global?: boolean;
     /** false ⇔ `--no-input`. */
     input?: boolean;
+    /** `--deployment [host]`: log in this workspace's deployment (`true` when no host was named). */
+    deployment?: string | boolean;
+    /** `--stdio`: the box's half of `--deployment` — the flow speaks the relay wire on stdin/stdout. */
+    stdio?: boolean;
+    /** `--if-missing` (with `--stdio`): keep a credential already stored for the provider. */
+    ifMissing?: boolean;
 }
 export declare function runLogin(provider: string | undefined, opts: LoginOptions): Promise<void>;

package/dist/cli/commands/login.js

@@ -1,17 +1,27 @@
 /**
  * `fastagent login [provider]`: authenticate a model provider into the project-level auth file
- * (`<agentDir>/.secrets/auth.json`) by default, or `FASTAGENT_AUTH_PATH`.
+ * (`<agentDir>/.secrets/auth.json`) by default, or `FASTAGENT_AUTH_PATH`. `--deployment` runs the same login on this
+ * workspace's deployed box instead (box-login.ts); `--stdio` is the box's half of that.
  */
-import { homedir } from "node:os";
+import { existsSync } from "node:fs";
 import { join } from "node:path";
 import { enterAgentEnv } from "../../env.js";
-import { resolveAuthPath } from "../../engines/pi/config.js";
-import { GLOBAL_AUTH_PATH } from "../../engines/pi/auth.js";
-import { GLOBAL_HOME_DIR, findAgentDir, placementDeadEnd } from "../../paths.js";
+import { GLOBAL_AUTH_PATH, resolveAuthPath } from "../../engines/pi/auth.js";
+import { agentModels } from "../../engines/pi/agent-models.js";
+import { DEPLOY_HOSTS } from "../../deploy/hosts.js";
+import { findAgentDir, globalHome, placementDeadEnd } from "../../paths.js";
 import { LoginCancelled, loginFlow } from "../../engines/pi/login.js";
-import { failStartup, placementOrExit } from "../fail.js";
+import { environmentAuthSource } from "../../engines/pi/models.js";
+import { loginOnBox } from "../box-login.js";
+import { failStartup, failUsage, placementOrExit } from "../fail.js";
+import { stdioLoginIO } from "../login-relay.js";
 import { isInteractive, terminalLoginIO } from "../shared.js";
+import { HOSTS } from "./deploy.js";
 export async function runLogin(provider, opts) {
+    if (opts.stdio)
+        return runStdioLogin(provider, opts);
+    if (opts.deployment !== undefined)
+        return runDeploymentLogin(provider, opts);
     const cwd = process.cwd();
     const agentDir = findAgentDir(cwd);
     // "Outside an agent" must mean exactly that.
@@ -19,9 +29,12 @@ export async function runLogin(provider, opts) {
         placementOrExit(cwd);
     // Outside any agent the target is the user-global machinery home — handed over explicitly, so the path resolvers
     // need no "is this $HOME?" special case to infer it.
-    const loginDir = agentDir ?? join(homedir(), GLOBAL_HOME_DIR);
+    const loginDir = agentDir ?? globalHome();
     // FASTAGENT_AUTH_PATH and a proxy may both be configured in the project .env, and the OAuth token exchange must go
     // through that proxy (region-locked providers).
+    // Before the agent's `.env` joins it: the shadowing check below is about what EVERY agent sees, and that is the
+    // environment the shell hands down, not one agent's value file.
+    const shellEnv = { ...process.env };
     enterAgentEnv(loginDir);
     // `-g` names the global file outright. Otherwise: FASTAGENT_AUTH_PATH > default — the one owner. The
     // store built here is deliberately UNLAYERED: reading falls back to the global file, but writing must land
@@ -32,9 +45,9 @@ export async function runLogin(provider, opts) {
     // lands somewhere no agent will read.
     if (!agentDir && !opts.global && !process.env.FASTAGENT_AUTH_PATH) {
         console.error(`[fastagent] no agent here (no fastagent.config.ts, here or one level inside) — ` +
-            `logging in GLOBALLY (${authPath}). Every agent on this machine reads this file for providers its own ` +
-            `.secrets/auth.json does not have, so this is usually what you want; \`cd\` into an agent to give that ` +
-            `one its own account instead.`);
+            `logging in GLOBALLY (${authPath}). An agent on this machine uses this file for a provider it has no ` +
+            `credential of its own for (no entry in its .secrets/auth.json, no apiKey in its models.json, no env ` +
+            `variable), so this is usually what you want; \`cd\` into an agent to give that one its own account instead.`);
     }
     // login is inherently interactive — loginFlow renders provider/method menus and opens a browser (or prompts for a
     // key).
@@ -57,5 +70,105 @@ export async function runLogin(provider, opts) {
         failStartup(error);
     });
     console.error(`[fastagent] logged in to ${result.provider} (${result.method}) — saved to ${authPath}`);
+    // The environment outranks the global file for every agent, so a global login it shadows would sit unused while
+    // agents run on, say, an API key billed per request, with only a startup line to show it.
+    const shadowedBy = authPath === GLOBAL_AUTH_PATH ? await environmentAuthSource(result.provider, shellEnv) : undefined;
+    if (shadowedBy !== undefined) {
+        console.error(`[fastagent] warning: ${result.provider} is also authenticated by ${shadowedBy} in your shell environment, which ` +
+            `agents use before the global file, so this login is not used while it is set. Unset it to use this login.`);
+    }
     process.exit(0); // the undici proxy agent's keep-alive sockets would otherwise hold the event loop open
 }
+/**
+ * `--deployment [host]`: the host is named, or the one whose generated artifact is in the agent dir. Several is a
+ * question only the operator can answer, so it is asked back rather than guessed.
+ */
+async function runDeploymentLogin(provider, opts) {
+    if (opts.global)
+        failUsage("--deployment logs the deployment in; -g names this machine's global file — pick one");
+    const placement = placementOrExit(process.cwd());
+    // The host's CLI must reach the account/region/proxy the deploy used, and those may be definition-local.
+    enterAgentEnv(placement.agentDir);
+    let host;
+    if (typeof opts.deployment === "string") {
+        if (!DEPLOY_HOSTS.includes(opts.deployment)) {
+            failUsage(`--deployment takes a host (${DEPLOY_HOSTS.join(", ")}), not "${opts.deployment}" — to name a provider too: ` +
+                `fastagent login <provider> --deployment <host>`);
+        }
+        host = opts.deployment;
+    }
+    else {
+        const found = DEPLOY_HOSTS.filter((h) => existsSync(join(placement.agentDir, HOSTS[h].artifact)));
+        if (found.length !== 1) {
+            failUsage(found.length === 0
+                ? `no deployment artifacts in ${placement.agentDir} — name the host: --deployment <${DEPLOY_HOSTS.join("|")}>`
+                : `this agent deploys to ${found.join(" and ")} — name one: --deployment <${found.join("|")}>`);
+        }
+        host = found[0];
+    }
+    const input = opts.input !== false && isInteractive();
+    if (!input) {
+        failStartup(new Error(`login is interactive (it shows a menu and opens a browser) — run it in a terminal`));
+    }
+    const failed = await loginOnBox({
+        host,
+        shell: await HOSTS[host].shell(placement).catch(failStartup),
+        placement,
+        ...(provider ? { provider } : {}),
+        input,
+    });
+    if (failed)
+        failStartup(new Error(failed));
+    process.exit(0);
+}
+/**
+ * `--stdio`: the box's half of `--deployment`. Runs where the server runs; everything it would show or ask travels as
+ * the relay wire, and it ends with exactly one result line. Never started by hand: the credential path is the one the
+ * caller exported (container.ts `boxLoginCommand`).
+ */
+async function runStdioLogin(provider, opts) {
+    const wire = stdioLoginIO(process.stdin, process.stdout);
+    const result = await stdioLogin(wire.io, provider, opts).catch((error) => error instanceof LoginCancelled
+        ? { ok: false, reason: "cancelled", message: "cancelled" }
+        : { ok: false, reason: "failed", message: error.message });
+    wire.result(result);
+    process.exitCode = result.ok ? 0 : 1;
+    // Exit once the result line is flushed: an undici keep-alive socket would otherwise hold the process open.
+    process.stdout.write("", () => process.exit());
+}
+async function stdioLogin(io, provider, opts) {
+    // `boxLoginCommand` starts this in the deployed agent directory; anywhere else there is no box to log in.
+    const agentDir = findAgentDir(process.cwd());
+    if (!agentDir)
+        throw new Error(`login --stdio: ${process.cwd()} is not an agent directory`);
+    // A deployed box has no value file to read: its variables reach this process only as the host's shell hands them
+    // down (the container's for `docker compose exec`, the platform's over fly/railway ssh), and this installs the egress
+    // proxy they name. AgentCore's command shell hands down none of the runtime's, so a proxy carried there in
+    // FASTAGENT_ENV does not reach the login (docs/deploy.md).
+    enterAgentEnv(agentDir);
+    // The model environment the serving runtime reads (createPiAgentFromDir), so "logged in" means what the server will
+    // use.
+    const models = agentModels(agentDir);
+    const { auth } = models;
+    if (opts.ifMissing && provider) {
+        // The server's own answer (`authStatus`), the one its startup report prints. Known ceiling: nothing is asked of
+        // the provider beyond a due refresh, so a revoked grant whose access token has not expired yet, or a revoked API
+        // key, reads as held and the first turn fails with the provider's error. Asking would spend a real model call on
+        // every redeploy, which the readiness checks deliberately never do.
+        const held = await models.authStatus(provider);
+        if (held.source !== undefined)
+            return { ok: true, provider, kept: held.source };
+        if (opts.input === false) {
+            const what = held.stored
+                ? `the stored ${provider} ${held.stored} credential is expired or unusable`
+                : `no ${provider} credential`;
+            const because = held.error === undefined ? "" : ` (${held.error})`;
+            return { ok: false, reason: "missing", message: `${what}${because} in ${held.path ?? auth.path}` };
+        }
+    }
+    if (opts.input === false) {
+        return { ok: false, reason: "missing", message: `no ${provider ?? "model"} credential in ${auth.path}` };
+    }
+    const result = await loginFlow(io, { authPath: auth.path, ...(provider ? { provider } : {}), agentDir });
+    return { ok: true, provider: result.provider, method: result.method, path: auth.path };
+}

package/dist/cli/commands/logs.js

@@ -2,7 +2,7 @@
 import { basename, resolve } from "node:path";
 import { agentcoreName } from "../../deploy/agentcore/plan.js";
 import { tailAgentcoreLogs } from "../../deploy/agentcore/logs.js";
-import { spawnRunner } from "../../deploy/runner.js";
+import { awsRunner } from "../../deploy/runner.js";
 import { enterAgentEnv } from "../../env.js";
 import { failStartup, failUsage, placementOrExit } from "../fail.js";
 export async function runLogs(host, dirArg, opts) {
@@ -20,7 +20,7 @@ export async function runLogs(host, dirArg, opts) {
         source: source,
         since: opts.since,
         follow: opts.follow === true,
-    }, spawnRunner("aws", placement.workspace), (message) => console.error(`[fastagent] logs: ${message}`));
+    }, awsRunner(placement.workspace), (message) => console.error(`[fastagent] logs: ${message}`));
     if (!outcome.ok)
         failStartup(new Error(`logs stopped: ${outcome.gate}`));
 }

package/dist/cli/commands/models.d.ts

@@ -1 +1,4 @@
-export declare function runModels(search: string | undefined): void;
+export declare function runModels(search: string | undefined, opts?: {
+    refresh?: boolean;
+    global?: boolean;
+}): Promise<void>;