@fastagent-sh/fastagent 0.22.1 → 0.24.0

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

@@ -5,22 +5,47 @@
 import { mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { basename, join } from "node:path";
-import { FORWARDER_FILE, TEMPLATE_FILE, agentcoreName, forwarderLogGroup, ingressSessionId, isGeneratedAgentcoreTemplate, planAgentcoreDeploy, } from "../../../deploy/agentcore/plan.js";
-import { deployAgentcoreRun } from "../../../deploy/agentcore/run.js";
-import { spawnRunner } from "../../../deploy/runner.js";
+import { FORWARDER_FILE, TEMPLATE_FILE, agentcoreName, agentcoreStackName, forwarderLogGroup, ingressSessionId, isGeneratedAgentcoreTemplate, planAgentcoreDeploy, } from "../../../deploy/agentcore/plan.js";
+import { deployAgentcoreRun, pickStackOutputs } from "../../../deploy/agentcore/run.js";
+import { awsCli, awsJson } from "../../../deploy/agentcore/aws-cli.js";
+import { agentcoreShell } from "../../../deploy/agentcore/shell.js";
+import { awsRunner, spawnRunner } from "../../../deploy/runner.js";
 import { SECRET_FILE_MODE, exists } from "../../../paths.js";
 import { loadRoutines } from "../../../schedule/discover.js";
+import { assembleSecrets } from "../../../deploy/secrets.js";
 import { failStartup } from "../../fail.js";
-import { carryCredentials, gateOnModelCredential, registrarsFor } from "./shared.js";
+import { isInteractive } from "../../shared.js";
+import { boxLoginStep, registrarsFor } from "./shared.js";
 /** A copy/paste-safe POSIX shell argument for the command hints deploy prints. */
 function shellArg(value) {
     return /^[A-Za-z0-9_./:@%+=,-]+$/.test(value) ? value : `'${value.replaceAll("'", `'"'"'`)}'`;
 }
 export const agentcoreHost = {
     isOurs: (path, content) => path.endsWith(TEMPLATE_FILE) && isGeneratedAgentcoreTemplate(content),
+    artifact: TEMPLATE_FILE,
+    async shell({ workspace }) {
+        const name = agentcoreName(basename(workspace));
+        const stack = agentcoreStackName(name);
+        const aws = awsRunner(workspace);
+        const read = await awsCli(aws).read(["cloudformation", "describe-stacks", "--stack-name", stack, "--query", "Stacks[0].Outputs", "--output", "json"], awsJson(pickStackOutputs));
+        if ("absent" in read)
+            throw new Error(`no AgentCore stack ${stack} in this account/region — deploy it first`);
+        if ("unreadable" in read)
+            throw new Error(`could not read AgentCore stack ${stack}: ${read.unreadable}`);
+        const runtimeArn = read.ok.RuntimeArn;
+        if (!runtimeArn)
+            throw new Error(`stack ${stack} has no RuntimeArn output — redeploy it`);
+        return agentcoreShell(runtimeArn, ingressSessionId(name), aws);
+    },
     async deploy(ctx) {
         const { opts, agentDir, workspace, config, channels, longConnectionChannels, pre, write } = ctx;
-        const { modelAuth, modelKeyInDefinition, authPath, container, declaredSecrets, values, valueFile } = pre;
+        const { modelAuth, boxLogin, container, declaredSecrets, values, valueFile } = pre;
+        if (boxLogin) {
+            console.error(`[fastagent] note: AgentCore resets the runtime's storage on every deploy AND after 14 idle days, and the ` +
+                `${boxLogin} login with it: every deploy of this agent ends with a login on the runtime, and after an idle ` +
+                `reset every turn fails until \`fastagent login ${boxLogin} --deployment agentcore\` (the runtime's log says ` +
+                `so). For an agent that must keep answering unattended, set ${boxLogin}'s API key in ${valueFile}.`);
+        }
         // Long-connection channels are STRUCTURALLY unsupported: the connection is the ingress, and a reclaimed session
         // has nothing to wake it.
         if (longConnectionChannels.length > 0) {
@@ -54,7 +79,7 @@ export const agentcoreHost = {
         }
         const plan = planAgentcoreDeploy({
             name: acName,
-            modelAuth,
+            boxLogin,
             channels,
             secrets: pre.secrets,
             // ONLY THE ONES WITH A CRON become rules. A routine without one is reached by NAME, through this host's
@@ -98,8 +123,8 @@ export const agentcoreHost = {
                 agentPrefix: container.agentPrefix,
                 name: acName,
                 modelAuth,
-                modelKeyInDefinition,
-                authPath,
+                boxLogin,
+                input: opts.input !== false && isInteractive(),
                 channels,
                 declaredSecrets,
                 values,
@@ -114,12 +139,23 @@ export const agentcoreHost = {
 /** `deploy agentcore --run`: drive aws + docker to completion. */
 async function runDeployAgentcore(params) {
     const { agentDir, workspace, agentPrefix, name, channels, topology } = params;
-    const { secrets, missingSecrets, needsModelCredential } = await carryCredentials(params);
+    // Decided before the first side effect: the deploy resets the runtime's storage and the login with it, so with nobody
+    // to log it in again it would end at "not logged in" AFTER replacing a runtime that was serving, with the webhooks
+    // a previous deploy registered still pointing at it.
+    if (params.boxLogin && !params.input) {
+        failStartup(new Error(`deploy stopped: every AgentCore deploy wipes the runtime's ${params.boxLogin} login, and without a terminal ` +
+            `nobody can log it in again — run this deploy in a terminal, or set ${params.boxLogin}'s API key in ` +
+            `${params.valueFile}`));
+    }
+    const { secrets, missingSecrets } = assembleSecrets({
+        modelAuth: params.modelAuth,
+        declared: params.declaredSecrets,
+        values: params.values,
+    });
     // The wake-alarm shared secret (container ↔ forwarder).
     secrets.FASTAGENT_WAKE_SECRET = crypto.randomUUID();
     // The forwarder→runtime ingress secret: what makes an envelope the forwarder's rather than any IAM principal's.
     secrets.FASTAGENT_INGRESS_SECRET = crypto.randomUUID();
-    gateOnModelCredential(needsModelCredential);
     // The params temp dir holds the ONE file carrying secret values (file:// parameter-overrides — never argv);
     // 0700/0600 and removed after the run, success or gate.
     const paramsDir = await mkdtemp(join(tmpdir(), "fastagent-agentcore-"));
@@ -138,7 +174,8 @@ async function runDeployAgentcore(params) {
             valueFile: params.valueFile,
             channels,
             topology,
-        }, spawnRunner("aws", workspace), spawnRunner("docker", workspace), (m) => console.error(`[fastagent] ${m}`), async (content) => {
+            ...boxLoginStep("agentcore", params, (runtimeArn) => agentcoreShell(runtimeArn, ingressSessionId(name), awsRunner(workspace))),
+        }, awsRunner(workspace), spawnRunner("docker", workspace), (m) => console.error(`[fastagent] ${m}`), async (content) => {
             const path = join(paramsDir, "params.json");
             await writeFile(path, content, { mode: SECRET_FILE_MODE });
             return path;

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,12 +2,13 @@
 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";
-import { reportFindingsIfChanged, reportToolCollisions } from "../../engines/pi/report.js";
+import { describeIndirectTools, reportFindingsIfChanged, reportToolCollisions } from "../../engines/pi/report.js";
 import { allSecrets, describeSecrets, missingSecrets } from "../../declared-secrets.js";
 import { log } from "../../log.js";
 import { reportModuleLoadFailures } from "../../loader.js";
@@ -31,7 +32,7 @@ export async function runInfo(dirArg, opts) {
     const tools = await resolveAgentTools(config, agentDir, workspace)
         .then((r) => ({
         names: r.toolNames,
-        deferred: r.deferredToolNames,
+        indirect: r.indirectTools,
         collisions: r.toolCollisions,
         failures: r.toolFailures,
         secrets: allSecrets(r.toolSecrets),
@@ -39,7 +40,7 @@ export async function runInfo(dirArg, opts) {
     }))
         .catch((e) => ({
         names: [],
-        deferred: [],
+        indirect: [],
         collisions: [],
         failures: [],
         secrets: [],
@@ -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, {}, { cwd: workspace });
+    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)
@@ -104,7 +107,7 @@ export async function runInfo(dirArg, opts) {
             persona: definition.persona !== undefined,
             skills: skills.map((skill) => ({ name: skill.name, description: skill.description })),
             tools: tools.names,
-            deferredTools: tools.deferred,
+            indirectTools: tools.indirect,
             toolError: tools.error ?? null,
             channels,
             routines,
@@ -142,8 +145,8 @@ export async function runInfo(dirArg, opts) {
     line("persona", definition.persona ? "persona.md" : "(none)");
     line("skills", skills.map((skill) => skill.name).join(", ") || "(none)");
     line("tools", tools.error ? "(could not load — see warning below)" : tools.names.join(", ") || "(none)");
-    if (tools.deferred.length > 0)
-        line("deferred", `${tools.deferred.join(", ")} (activated via search_tools)`);
+    if (tools.indirect.length > 0)
+        line("indirect", describeIndirectTools(tools.indirect));
     line("channels", channels.join(", ") || "(none)");
     line("routines", routines.map((r) => `${r.name} (${r.cron === null ? "on demand" : `next ${r.next ?? "never"}`})`).join(", ") ||
         "(none)");

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>;