@fastagent-sh/fastagent 0.24.4 → 0.25.0

package/dist/cli/commands/login.js

@@ -1,32 +1,35 @@
-/**
- * `fastagent login [provider]`: authenticate a model provider into the project-level auth file
- * (`<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 { existsSync } from "node:fs";
-import { join } from "node:path";
-import { enterAgentEnv } from "../../env.js";
-import { GLOBAL_AUTH_PATH, resolveAuthPath } from "../../engines/pi/auth.js";
-import { agentModels } from "../../engines/pi/agent-models.js";
+import { enterAgentEnv, dotEnvPath } from "../../env.js";
+import { GLOBAL_AUTH_PATH, resolveAuthPath, } from "../../harnesses/models/credentials.js";
+import { modelEnvironment } from "../../harnesses/models/environment.js";
 import { DEPLOY_HOSTS } from "../../deploy/hosts.js";
-import { findAgentDir, globalHome, placementDeadEnd, resolvePlacement } from "../../paths.js";
-import { LoginCancelled, loginFlow } from "../../engines/pi/login.js";
-import { environmentAuthSource } from "../../engines/pi/models.js";
-import { loginOnBox } from "../box-login.js";
-import { failStartup, failUsage, placementOrExit } from "../fail.js";
+import { findAgentDir, globalHome, selectAgentEnvironment } from "../../paths.js";
+import { LoginCancelled, LoginRefused, PI_DEFAULT_MODELS, chooseLogin, loginFlow, loginOptionsOver, loginOver, loginStatusText, } from "../../harnesses/models/login.js";
+import { environmentAuth, keyVariables, loginProviders } from "../../harnesses/models/models.js";
+import { definitionProviders, loadConfig, modelSpecFor } from "../../harnesses/pi-durable/open.js";
+import { loginOnBox, ticketLoginIO } from "../box-login.js";
+import { deploymentLoginCommand } from "../../deploy/box-shell.js";
+import { agentDirOrExit, failStartup, failUsage, optionalAgentDirOrExit } from "../fail.js";
+import { printReport, refusedCheck, checkTicket, runTicket, startTicket, ticketExitCode, ticketReport, } from "../ticket.js";
 import { stdioLoginIO } from "../login-relay.js";
 import { isInteractive, terminalLoginIO } from "../shared.js";
 import { HOSTS } from "./deploy.js";
+/** The command that reads a sign-in's ticket, as every such ticket records it. */
+const LOGIN_CHECK = "fastagent login --check";
+/** Without a terminal, how long a sign-in stays open for the person to finish it. */
+const UNATTENDED_TIMEOUT_SECONDS = 600;
 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.
-    if (!agentDir && placementDeadEnd(cwd))
-        placementOrExit(cwd);
+    if (opts.check !== undefined)
+        return runCheck(opts.check, opts);
+    if (opts.code !== undefined)
+        failUsage("--code hands an address to a sign-in: pass --check <ticket> too");
+    const method = opts.method === undefined ? undefined : methodOf(opts.method);
+    const givenTimeout = opts.timeout === undefined ? undefined : secondsOf(opts.timeout);
+    // "Outside an agent" must mean exactly that: inside one is refused (findAgentDir), never a global login.
+    const agentDir = optionalAgentDirOrExit(process.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 ?? globalHome();
@@ -41,86 +44,425 @@ export async function runLogin(provider, opts) {
     // exactly where the operator said, or a second `login` for a provider they already have globally would silently
     // rewrite the global credential instead of creating the project-level override they asked for.
     const authPath = opts.global ? GLOBAL_AUTH_PATH : resolveAuthPath(loginDir);
+    const ownAgent = opts.global ? undefined : agentDir;
+    // The definition's providers too: a gateway's key is verified against the gateway, not a built-in's endpoint. Not for
+    // `-g`: the global file serves every agent on this machine, so no one agent's providers decide what it holds.
+    const providersOf = () => (ownAgent ? definitionProviders(ownAgent) : Promise.resolve([]));
+    if (opts.ticket !== undefined) {
+        // The process `startTicket` started: it takes the ticket before loading the definition, then signs in.
+        await runTicket(opts.ticket, async (step) => {
+            const providers = await providersOf();
+            const interaction = signInInteraction(step, provider);
+            await loginOver({ provider: provider, method: "oauth", authPath, interaction }, { providers });
+            const model = ownAgent ? await defaultModelHint(ownAgent, provider) : undefined;
+            const name = loginProviders(providers).find((p) => p.id === provider)?.name ?? provider;
+            return { provider, path: authPath, ...(model === undefined ? {} : { model, name }) };
+        });
+        process.exit(0);
+    }
+    const providers = await providersOf().catch(failStartup);
     // Announce when the FALLBACK is what decided the target: outside an agent with no explicit path, the credential
     // 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) — ` +
+        console.error(`[fastagent] no agent here (no fastagent.config.ts) — ` +
             `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.`);
+            `credential of its own for (no entry in its .secrets/auth.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).
-    if (opts.input === false || !isInteractive()) {
-        failStartup(new Error(`login is interactive (it shows a menu and opens a browser) — run it in a terminal, not a pipe/CI`));
+    // What the agent reads, its file over the global one, is what authenticates each provider for it now.
+    const statusFrom = ownAgent
+        ? (await modelEnvironment(ownAgent, {}, providers)).credentials
+        : authPath;
+    if (opts.input === false || opts.json === true || !isInteractive()) {
+        const offered = await loginOptionsOver(statusFrom, providers);
+        return requestLogin(offered, { provider, method }, opts, {
+            authPath,
+            providers,
+            valueFile: ownAgent === undefined ? undefined : dotEnvPath(ownAgent),
+            heldIn: async (id) => (typeof statusFrom === "string" ? statusFrom : statusFrom.layerOf(id)),
+            timeoutSeconds: givenTimeout ?? UNATTENDED_TIMEOUT_SECONDS,
+        });
     }
+    const timeout = givenTimeout === undefined ? undefined : AbortSignal.timeout(givenTimeout * 1000);
     // An entered API key is verified with one minimal request (login.ts); a rejected one is asked for again.
-    // Inside an agent, the key is checked on that agent's registry: its models.json may point a provider at a gateway.
-    // Not with `-g`: the global file serves every agent on the machine, so no one agent's routing may judge its key.
     const result = await loginFlow(terminalLoginIO(), {
         authPath,
+        providers,
+        statusFrom: typeof statusFrom === "string" ? undefined : statusFrom,
         ...(provider ? { provider } : {}),
-        ...(agentDir && !opts.global ? { agentDir } : {}),
+        ...(method ? { method } : {}),
+        ...(timeout ? { signal: timeout } : {}),
     }).catch((error) => {
+        if (timeout?.aborted)
+            failStartup(new Error(`login timed out after ${givenTimeout}s (--timeout)`));
         if (error instanceof LoginCancelled) {
             // A decision, not a failure — neutral wording; non-zero exit because no credential was stored.
             console.error(`[fastagent] login cancelled`);
             process.exit(1);
         }
+        if (error instanceof LoginRefused)
+            failUsage(error.message);
         failStartup(error);
     });
-    console.error(`[fastagent] logged in to ${result.provider} (${result.method}) — saved to ${authPath}`);
+    const name = loginProviders(providers).find((p) => p.id === result.provider)?.name ?? result.provider;
+    console.error(result.method === "oauth"
+        ? `[fastagent] logged in to ${name} — saved to ${authPath}`
+        : `[fastagent] saved the API key for ${name} to ${authPath}`);
+    const model = ownAgent ? await defaultModelHint(ownAgent, result.provider) : undefined;
+    if (model !== undefined)
+        console.error(`[fastagent] ${modelHint(model, name)}`);
     // 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;
+    const shadowedBy = authPath === GLOBAL_AUTH_PATH ? (await environmentAuth(result.provider, shellEnv))?.source : 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
 }
+const modelHint = (model, name) => `this agent has no model: \`model: "${model}"\` in fastagent.config.ts uses ${name}'s default`;
+/** `--method`'s words, pi's: an account (OAuth) or an API key. */
+function methodOf(value) {
+    if (value === "account")
+        return "oauth";
+    if (value === "api-key")
+        return "api_key";
+    return failUsage(`--method must be account or api-key, not "${value}"`);
+}
+const methodWord = (method) => (method === "oauth" ? "account" : "api-key");
+function secondsOf(value) {
+    const seconds = Number(value);
+    if (!Number.isInteger(seconds) || seconds <= 0)
+        failUsage(`--timeout must be a whole number of seconds, not "${value}"`);
+    return seconds;
+}
+/**
+ * pi's default model for `provider`, when the agent in `agentDir` has no model of its own: what pi starts on after a
+ * sign-in. Printed, never written: the model belongs in the author's own config.
+ */
+async function defaultModelHint(agentDir, provider) {
+    const config = await loadConfig(agentDir).catch(failStartup);
+    if (modelSpecFor(config, undefined) !== undefined)
+        return undefined;
+    const modelId = PI_DEFAULT_MODELS[provider];
+    return modelId === undefined ? undefined : `${provider}/${modelId}`;
+}
 /**
- * `--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.
+ * Login with no one at a terminal to ask, as Netlify's `login --request` and Dosu's tickets have it: a choice not
+ * given is named with a command for each way (`need_choice`, exit 2); an account sign-in starts in a process of its
+ * own and returns its address with a ticket (`need_user_action`, exit 0); an API key is the person's to set where the
+ * agent reads it, never handed through the agent (`need_user_action` naming the variables).
+ */
+async function requestLogin(offered, given, opts, target) {
+    const global = opts.global ? " -g" : "";
+    let choice;
+    try {
+        choice = await chooseLogin(offered, given, undefined);
+    }
+    catch (error) {
+        if (!(error instanceof LoginRefused))
+            throw error;
+        return choiceNotGiven(error, opts, { flags: global, statuses: true });
+    }
+    if (choice.method === "api_key")
+        return keyNeeded(choice, opts, target);
+    const ticket = await startTicket({
+        // One subject per provider, here or on a deployment: they hold the same callback port on this machine.
+        subject: `login:${choice.provider}`,
+        fields: { provider: choice.provider, method: "account" },
+        action: `sign in to ${choice.name}`,
+        check: LOGIN_CHECK,
+        restart: `fastagent login ${choice.provider} --method account${global}`,
+        timeoutSeconds: target.timeoutSeconds,
+        waitsFirst: true,
+        whenRunning: "replace",
+        command: {
+            file: process.execPath,
+            args: [
+                ...process.execArgv,
+                process.argv[1],
+                "login",
+                choice.provider,
+                "--method",
+                "account",
+                ...(opts.global ? ["-g"] : []),
+            ],
+            cwd: process.cwd(),
+        },
+    });
+    // No browser is opened: the agent hands the address to its person, who may be on another machine.
+    reportTicket(ticket, opts, "started");
+    process.exit(ticketExitCode(ticket));
+}
+/**
+ * An API key with no terminal to type it in: the variables the person sets themselves where the agent reads them, and
+ * how to tell it worked. With no agent's value file to name (`-g`, or no agent here), the person signs in at a terminal
+ * of their own, which keeps the key in the global file `auth check -g` reads: the agent's environment was fixed when it
+ * started, so a variable set now would never reach it.
+ */
+async function keyNeeded(choice, opts, target) {
+    const base = { provider: choice.provider, method: "api-key" };
+    if (choice.status?.type === "api_key") {
+        printReport(opts.json, { status: "ready", ...base, source: choice.status.source }, [
+            `ready: ${choice.name} is authenticated by ${choice.status.source}`,
+        ]);
+        return;
+    }
+    const check = `fastagent auth check --provider ${choice.provider}${target.valueFile === undefined ? " -g" : ""}`;
+    if (target.valueFile === undefined) {
+        const terminal = `fastagent login ${choice.provider} --method api-key -g`;
+        printReport(opts.json, {
+            status: "need_user_action",
+            ...base,
+            terminal_command: terminal,
+            check_command: `${check} --json`,
+            agent_next_steps: "Ask the user to run terminal_command in a terminal of their own: it asks for the key there, not in this " +
+                "conversation, and keeps it in the global credentials file. Once they say they have, run check_command.",
+        }, [`need_user_action: run in a terminal of your own: ${terminal}`, `then run: ${check}`]);
+        return;
+    }
+    // A stored account sign-in outranks any key in the environment: it goes first, or the key set now is never used.
+    const outranking = choice.status?.source === "OAuth" ? await target.heldIn(choice.provider) : undefined;
+    const logout = outranking === undefined
+        ? undefined
+        : `fastagent logout ${choice.provider}${outranking === GLOBAL_AUTH_PATH ? " -g" : ""}`;
+    const { variables, what } = await keyToSet(choice, target.providers);
+    const first = logout === undefined
+        ? ""
+        : `${choice.name} is signed in with an account in ${outranking}, which outranks a key in the environment: ` +
+            "run logout_command first (with the user's agreement: it removes that sign-in). Then ";
+    printReport(opts.json, {
+        status: "need_user_action",
+        ...base,
+        variables,
+        value_file: target.valueFile,
+        ...(logout === undefined ? {} : { logout_command: logout }),
+        check_command: `${check} --json`,
+        agent_next_steps: `${first}${first ? "ask" : "Ask"} the user to set ${what} in ${target.valueFile} themselves, not in this ` +
+            "conversation. Once they say they have, run check_command.",
+    }, [
+        ...(logout === undefined ? [] : [`first, to replace the account sign-in in ${outranking}: ${logout}`]),
+        `need_user_action: set ${what} in ${target.valueFile}`,
+        `then run: ${check}`,
+    ]);
+}
+/**
+ * A sign-in not chosen with no one to ask (exit 2): with `--json`, the choices and the command for each, `flags`
+ * added to it. `statuses`: what authenticates each provider here is worth showing (it is not, for a deployment).
+ */
+function choiceNotGiven(error, opts, how) {
+    if (opts.json) {
+        const choices = error.choices.map((o) => ({
+            provider: o.provider,
+            name: o.name,
+            method: methodWord(o.method),
+            label: o.label,
+            ...(how.statuses ? { status: loginStatusText(o) } : {}),
+            command: `fastagent login ${o.provider} --method ${methodWord(o.method)}${how.flags} --json`,
+        }));
+        printReport(true, {
+            status: "need_choice",
+            message: error.message,
+            choices,
+            agent_next_steps: "Ask the user which of these to sign in with, then run that choice's command.",
+        }, []);
+    }
+    return failUsage(error.message);
+}
+/** The variables `choice`'s key is read from, and how to tell the person to set it. */
+async function keyToSet(choice, providers) {
+    const provider = loginProviders(providers).find((p) => p.id === choice.provider);
+    const variables = provider ? await keyVariables(provider) : [];
+    const what = variables.length === 0
+        ? `its key as ${choice.name}'s own documentation says`
+        : variables.length === 1
+            ? `${variables[0]}=<their ${choice.name} key>`
+            : `the variables ${choice.name} reads its key from (${variables.join(", ")})`;
+    return { variables, what };
+}
+/** `login --check <ticket> [--code <address>]`. */
+async function runCheck(id, opts) {
+    const refused = refusedCheck(id, LOGIN_CHECK);
+    if (refused !== undefined)
+        failUsage(refused);
+    // There: refusedCheck read it, and a ticket is pruned only a day after it ends.
+    const ticket = (await checkTicket(id, opts.code));
+    reportTicket(ticket, opts, "checked");
+    process.exit(ticketExitCode(ticket));
+}
+/** A sign-in's ticket for whoever started or checked it: the shared report, and what a finished sign-in adds. */
+function reportTicket(ticket, opts, when) {
+    const deployment = ticket.fields?.deployment;
+    const { json, text } = ticketReport(ticket, when, (result) => {
+        if (deployment !== undefined) {
+            return { fields: {}, text: [`signed in on the ${deployment} deployment`], next: "Signed in on the deployment." };
+        }
+        const hint = typeof result.model === "string" ? modelHint(result.model, String(result.name)) : undefined;
+        return {
+            fields: { path: result.path, ...(result.model ? { model: result.model } : {}) },
+            text: [`saved to ${String(result.path)}`, ...(hint === undefined ? [] : [hint])],
+            next: hint === undefined ? "Signed in." : `Signed in. Tell the user: ${hint}.`,
+        };
+    });
+    printReport(opts.json, json, text);
+}
+/**
+ * pi-ai's account sign-in, run by a ticket's process with no one to answer it. A choice takes its first option, pi's
+ * default (the browser sign-in); a text question is left blank, the one pi-ai's account sign-ins ask being Copilot's
+ * optional Enterprise domain (a required one fails in the provider's own flow, which the ticket reports); a secret it
+ * cannot take; the code or address a browser ends on comes from `login --check --code`, unless the provider's callback
+ * brings it first. Not public: a test seam.
+ */
+export function signInInteraction(step, provider) {
+    return {
+        signal: step.signal,
+        prompt: async (prompt) => {
+            if (prompt.type === "select")
+                return prompt.options[0].id;
+            if (prompt.type === "text")
+                return "";
+            if (prompt.type === "secret") {
+                throw new Error(`the sign-in asks "${prompt.message}", which only a terminal can answer: run \`fastagent login ${provider}\` ` +
+                    "in one");
+            }
+            return step.address(prompt.signal ? AbortSignal.any([prompt.signal, step.signal]) : step.signal);
+        },
+        notify: (event) => {
+            if (event.type === "auth_url") {
+                step.waits({
+                    url: event.url,
+                    takesAddress: true,
+                    ...(event.instructions ? { instructions: event.instructions } : {}),
+                });
+            }
+            else if (event.type === "device_code") {
+                step.waits({ url: event.verificationUri, code: event.userCode });
+            }
+            console.error(`[fastagent] ${event.type}: ${"message" in event ? event.message : ""}`);
+        },
+    };
+}
+/**
+ * `--deployment <host>`: always named. The agent directory cannot answer which host it means: a Railway deploy leaves
+ * no file of its own there, and a directory can hold several hosts' files, so a guess could log a different box in
+ * than the one that asked. Every command fastagent prints names it (`deploymentLoginCommand`, `deployedHost`).
  */
 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];
+    // A ticket is read on its own: with --deployment, this would start another sign-in and replace the one it names.
+    if (opts.check !== undefined || opts.code !== undefined) {
+        failUsage("--check reads a sign-in's ticket by itself: run `fastagent login --check <ticket>`, without --deployment");
+    }
+    const agentDir = agentDirOrExit(process.cwd());
+    selectAgentEnvironment("production");
+    enterAgentEnv(agentDir);
+    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>`);
+    }
+    const host = opts.deployment;
+    const method = opts.method === undefined ? undefined : methodOf(opts.method);
+    if (opts.ticket !== undefined) {
+        // The process `startTicket` started: it holds the box's shell while the person signs in.
+        const retry = deploymentLoginCommand(host, provider);
+        await runTicket(opts.ticket, async (step) => {
+            const io = ticketLoginIO(step, retry);
+            const failed = await loginOnBox({
+                host,
+                shell: await HOSTS[host].shell(agentDir),
+                provider: provider,
+                method: "oauth",
+                input: true,
+                io,
+            });
+            if (failed)
+                throw new Error(io.refusal() ?? failed);
+            return { provider, deployment: host };
+        });
+        process.exit(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`));
+    if (opts.input === false || opts.json === true || !isInteractive()) {
+        const timeout = opts.timeout === undefined ? UNATTENDED_TIMEOUT_SECONDS : secondsOf(opts.timeout);
+        return requestDeploymentLogin(agentDir, host, { provider, method }, opts, timeout);
     }
     const failed = await loginOnBox({
         host,
-        shell: await HOSTS[host].shell(placement).catch(failStartup),
-        placement,
+        shell: await HOSTS[host].shell(agentDir).catch(failStartup),
         ...(provider ? { provider } : {}),
-        input,
+        ...(method ? { method } : {}),
+        input: true,
     });
     if (failed)
         failStartup(new Error(failed));
     process.exit(0);
 }
+/**
+ * `login --deployment <host>` with no one at a terminal. The sign-in is chosen here, from the definition the box
+ * serves; what this machine holds says nothing of the box, so no status is shown. An account sign-in runs on the box
+ * through a ticket whose process holds the box's shell (box-login.ts `ticketLoginIO`). An API key reaches a box only
+ * as a variable its deploy carries, so the person sets it in the production value file and the agent deploys again.
+ */
+async function requestDeploymentLogin(agentDir, host, given, opts, timeoutSeconds) {
+    const providers = await definitionProviders(agentDir).catch(failStartup);
+    const offered = await loginOptionsOver(resolveAuthPath(agentDir), providers);
+    let choice;
+    try {
+        choice = await chooseLogin(offered, given, undefined);
+    }
+    catch (error) {
+        if (!(error instanceof LoginRefused))
+            throw error;
+        return choiceNotGiven(error, opts, { flags: ` --deployment ${host}`, statuses: false });
+    }
+    if (choice.method === "api_key") {
+        const valueFile = dotEnvPath(agentDir);
+        const { variables, what } = await keyToSet(choice, providers);
+        const deploy = `fastagent deploy ${host} --run`;
+        printReport(opts.json, {
+            status: "need_user_action",
+            provider: choice.provider,
+            method: "api-key",
+            deployment: host,
+            variables,
+            value_file: valueFile,
+            check_command: deploy,
+            agent_next_steps: `Ask the user to set ${what} in ${valueFile} themselves, not in this conversation. A key reaches the ` +
+                `${host} deployment with its next deploy: once they say they have, run check_command.`,
+        }, [
+            `need_user_action: set ${what} in ${valueFile}`,
+            `then run: ${deploy}   # the key reaches the deployment with its deploy`,
+        ]);
+        process.exit(0);
+    }
+    const ticket = await startTicket({
+        subject: `login:${choice.provider}`,
+        fields: { provider: choice.provider, method: "account", deployment: host },
+        action: `sign in to ${choice.name} for the ${host} deployment`,
+        check: LOGIN_CHECK,
+        restart: `fastagent login ${choice.provider} --method account --deployment ${host}`,
+        timeoutSeconds,
+        // Reaching the box comes first, and can take a while (a host's shell, an idle runtime woken).
+        waitsFirst: false,
+        whenRunning: "replace",
+        command: {
+            file: process.execPath,
+            args: [
+                ...process.execArgv,
+                process.argv[1],
+                "login",
+                choice.provider,
+                "--method",
+                "account",
+                "--deployment",
+                host,
+            ],
+            cwd: process.cwd(),
+        },
+    });
+    reportTicket(ticket, opts, "started");
+    process.exit(ticketExitCode(ticket));
+}
 /**
  * `--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
@@ -146,10 +488,11 @@ async function stdioLogin(io, provider, opts) {
     // 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, {}, { cwd: resolvePlacement(agentDir).workspace });
-    const { auth } = models;
+    // The model environment the serving Agent reads (openServing), its definition's providers included, so "logged in"
+    // means what the server will use, and a provider only the definition declares can be signed in to.
+    const providers = await definitionProviders(agentDir);
+    const models = await modelEnvironment(agentDir, {}, providers);
+    const auth = models.auth;
     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
@@ -169,6 +512,12 @@ async function stdioLogin(io, provider, opts) {
     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 });
+    const method = opts.method === undefined ? undefined : methodOf(opts.method);
+    const result = await loginFlow(io, {
+        authPath: auth.path,
+        providers,
+        ...(provider ? { provider } : {}),
+        ...(method ? { method } : {}),
+    });
     return { ok: true, provider: result.provider, method: result.method, path: auth.path };
 }

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

@@ -0,0 +1,4 @@
+export declare function runLogout(provider: string | undefined, opts: {
+    global?: boolean;
+    input?: boolean;
+}): Promise<void>;

package/dist/cli/commands/logout.js

@@ -0,0 +1,53 @@
+/**
+ * `fastagent logout [provider]`: remove the credential `login` stored for a provider, as pi's `/logout` does, from the
+ * file `login` writes (the agent's, or with `-g` or outside an agent the global one). Environment variables and the
+ * grant at the provider are left as they are.
+ */
+import { enterAgentEnv } from "../../env.js";
+import { GLOBAL_AUTH_PATH, fastagentCredentialStore, resolveAuthPath } from "../../harnesses/models/credentials.js";
+import { loginProviders } from "../../harnesses/models/models.js";
+import { definitionProviders } from "../../harnesses/pi-durable/open.js";
+import { globalHome } from "../../paths.js";
+import { failStartup, failUsage, optionalAgentDirOrExit } from "../fail.js";
+import { isInteractive, terminalLoginIO } from "../shared.js";
+export async function runLogout(provider, opts) {
+    const agentDir = opts.global ? undefined : optionalAgentDirOrExit(process.cwd());
+    enterAgentEnv(agentDir ?? globalHome());
+    const authPath = opts.global ? GLOBAL_AUTH_PATH : resolveAuthPath(agentDir ?? globalHome());
+    const store = fastagentCredentialStore(authPath);
+    const known = loginProviders(agentDir ? await definitionProviders(agentDir).catch(failStartup) : []);
+    const stored = (await store.list())
+        .map(({ providerId, type }) => ({
+        id: providerId,
+        type,
+        name: known.find((p) => p.id === providerId)?.name ?? providerId,
+    }))
+        .sort((a, b) => a.name.localeCompare(b.name));
+    const held = stored.length === 0 ? "it holds none" : `it holds ${stored.map(({ id }) => id).join(", ")}`;
+    let chosen;
+    if (provider !== undefined) {
+        const named = provider.trim().toLowerCase();
+        chosen = stored.find(({ id, name }) => id.toLowerCase() === named || name.toLowerCase() === named);
+        if (chosen === undefined)
+            failStartup(new Error(`no credential for "${provider}" is stored in ${authPath}: ${held}`));
+    }
+    else if (stored.length === 0) {
+        console.error(`[fastagent] no credential is stored in ${authPath}; environment variables are not login's to remove`);
+        return;
+    }
+    else if (opts.input === false || !isInteractive()) {
+        failUsage(`name the provider to log out of: ${held} (${authPath})`);
+    }
+    else {
+        const value = await terminalLoginIO().select("Select provider to logout:", stored.map(({ id, name, type }) => ({ value: id, label: name, hint: type === "oauth" ? "account" : "API key" })));
+        chosen = stored.find(({ id }) => id === value);
+        if (chosen === undefined) {
+            console.error("[fastagent] logout cancelled");
+            process.exit(1);
+        }
+    }
+    await store.delete(chosen.id);
+    console.error(chosen.type === "oauth"
+        ? `[fastagent] logged out of ${chosen.name} — removed from ${authPath}`
+        : `[fastagent] removed the stored API key for ${chosen.name} from ${authPath}; environment variables are unchanged`);
+}

package/dist/cli/commands/logs.js

@@ -1,26 +1,28 @@
-/** `fastagent logs agentcore [dir]`: discover and tail the deployed AgentCore CloudWatch logs. */
+/** `fastagent logs agentcore [agent]`: discover and tail the deployed AgentCore CloudWatch logs. */
 import { basename, resolve } from "node:path";
 import { agentcoreName } from "../../deploy/agentcore/plan.js";
 import { tailAgentcoreLogs } from "../../deploy/agentcore/logs.js";
 import { awsRunner } from "../../deploy/runner.js";
 import { enterAgentEnv } from "../../env.js";
-import { failStartup, failUsage, placementOrExit } from "../fail.js";
+import { selectAgentEnvironment } from "../../paths.js";
+import { agentDirOrExit, failStartup, failUsage } from "../fail.js";
 export async function runLogs(host, dirArg, opts) {
     // The host argument is DISPATCHED here, as in runDeploy.
     if (host !== "agentcore")
         failUsage(`logs: unsupported host "${host}" — only agentcore has remote logs`);
-    const placement = placementOrExit(resolve(dirArg));
-    enterAgentEnv(placement.agentDir); // AWS_PROFILE/region/proxy may be definition-local, as on deploy
+    const agentDir = agentDirOrExit(resolve(dirArg));
+    selectAgentEnvironment("production");
+    enterAgentEnv(agentDir);
     const source = opts.source ?? "runtime";
     if (source !== "runtime" && source !== "forwarder") {
         failUsage(`logs: --source must be "runtime" or "forwarder"`);
     }
     const outcome = await tailAgentcoreLogs({
-        name: agentcoreName(basename(placement.workspace)),
+        name: agentcoreName(basename(agentDir)),
         source: source,
         since: opts.since,
         follow: opts.follow === true,
-    }, awsRunner(placement.workspace), (message) => console.error(`[fastagent] logs: ${message}`));
+    }, awsRunner(agentDir), (message) => console.error(`[fastagent] logs: ${message}`));
     if (!outcome.ok)
         failStartup(new Error(`logs stopped: ${outcome.gate}`));
 }