@fastagent-sh/fastagent 0.29.0 → 0.30.0

package/dist/cli/commands/login.js

@@ -1,3 +1,11 @@
+/**
+ * `fastagent login [provider]`: sign in to a model provider, into the project-level auth file
+ * (`<agentDir>/.secrets/auth.json`) by default, or `FASTAGENT_AUTH_PATH`. In a terminal it asks, as pi's `/login`
+ * does; otherwise (a script, a coding agent: no terminal, `--no-input` or `--json`) nothing is asked and nothing
+ * waits: what it needs is named, and a person's step is handed back with a ticket to check (ticket.ts).
+ * `--deployment` runs the same login on this agent's deployed box instead (box-login.ts); `--stdio` is the box's half.
+ */
+import { definedValues } from "../../declared-secrets.js";
 import { enterAgentEnv } from "../../env.js";
 import { dotEnvPath } from "../../value-file.js";
 import { GLOBAL_AUTH_PATH, resolveAuthPath, } from "../../harnesses/models/credentials.js";
@@ -7,7 +15,8 @@ import { findAgentDir, globalHome, selectAgentEnvironment } from "../../paths.js
 import { SignInCancelled } from "../../sign-in-api.js";
 import { 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 { resolveConfig } from "../../harnesses/pi-durable/config.js";
+import { definitionProviders, loadDevProject, 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";
@@ -49,7 +58,7 @@ export async function runLogin(provider, opts) {
     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([]));
+    const providersOf = () => (ownAgent ? definitionProviders(ownAgent, process.env) : 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) => {
@@ -73,7 +82,8 @@ export async function runLogin(provider, opts) {
     }
     // 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
+        ? (await modelEnvironment(ownAgent, {}, providers, { environment: definedValues(process.env) }))
+            .credentials
         : authPath;
     if (opts.input === false || opts.json === true || !isInteractive()) {
         const offered = await loginOptionsOver(statusFrom, providers);
@@ -122,7 +132,7 @@ export async function runLogin(provider, opts) {
     }
     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`;
+const modelHint = (model, name) => `this agent has no model: \`defaults: { 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")
@@ -143,7 +153,9 @@ function secondsOf(value) {
  * 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);
+    const config = await loadDevProject(agentDir)
+        .then(({ definition, instance }) => resolveConfig(definition, instance))
+        .catch(failStartup);
     if (modelSpecFor(config, undefined) !== undefined)
         return undefined;
     const modelId = PI_DEFAULT_MODELS[provider];
@@ -406,7 +418,7 @@ async function runDeploymentLogin(provider, opts) {
  * 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 providers = await definitionProviders(agentDir, process.env).catch(failStartup);
     const offered = await loginOptionsOver(resolveAuthPath(agentDir), providers);
     let choice;
     try {
@@ -487,13 +499,13 @@ async function stdioLogin(io, provider, opts) {
         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).
+    // proxy they name. AgentCore's command shell hands down none of the runtime's, so a proxy the runtime has
+    // in its values does not reach the login (docs/deploy.md).
     enterAgentEnv(agentDir);
     // 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 providers = await definitionProviders(agentDir, process.env);
+    const models = await modelEnvironment(agentDir, {}, providers, { environment: definedValues(process.env) });
     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

package/dist/cli/commands/logout.js

@@ -15,7 +15,7 @@ export async function runLogout(provider, opts) {
     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 known = loginProviders(agentDir ? await definitionProviders(agentDir, process.env).catch(failStartup) : []);
     const stored = (await store.list())
         .map(({ providerId, type }) => ({
         id: providerId,

package/dist/cli/commands/mcp.js

@@ -3,7 +3,8 @@ import { confirm, isCancel } from "@clack/prompts";
 import { inspectMcp, mcpContext, writeMcpBinding, httpServer } from "../../mcp/host.js";
 import { signInMcp } from "../../mcp/sign-in.js";
 import { holdingInstance } from "../../harnesses/pi-durable/serve.js";
-import { resolveMcpServers } from "../../mcp/config.js";
+import { declareMcp, mcpInstance, resolveMcpServers } from "../../mcp/config.js";
+import { devInstanceConfig, namedInstanceConfig } from "../../harnesses/pi-durable/config.js";
 import { McpError } from "../../mcp-api.js";
 import { selectAgentEnvironment } from "../../paths.js";
 import { enterAgentEnv } from "../../env.js";
@@ -37,8 +38,12 @@ export async function runMcp(action, server, dir, options) {
         return failUsage("--env must be dev or production");
     selectAgentEnvironment(environment);
     enterAgentEnv(target);
+    // The servers the instance of this environment opens: the program's, and what its configuration adds. `dev` reads the
+    // one `--config` names or else the project's; `start` never reads the project's.
+    const instance = await (environment === "production" ? namedInstanceConfig() : devInstanceConfig(target)).catch(failStartup);
+    const config = instance?.label;
     if (action === "list") {
-        const servers = await inspectMcp(target).catch(failStartup);
+        const servers = await inspectMcp(target, config === undefined ? {} : { config }).catch(failStartup);
         if (options.json)
             console.log(JSON.stringify(servers));
         else
@@ -47,7 +52,7 @@ export async function runMcp(action, server, dir, options) {
         return;
     }
     if (!server)
-        return failUsage(`mcp ${action} needs a server name from .mcp.json`);
+        return failUsage(`mcp ${action} needs a server name from the program's context.json or the instance's fastagent.json`);
     const context = mcpContext(target);
     if (action === "disconnect") {
         await holdingInstance(context.stateRoot, () => writeMcpBinding(context.stateRoot, server, undefined)).catch(failStartup);
@@ -55,11 +60,13 @@ export async function runMcp(action, server, dir, options) {
             status: "done",
             server,
             grant_revoked: false,
-            agent_next_steps: "The instance binding was removed. The stored grant was not revoked; reauthorize or update .mcp.json before reopening.",
-        }, ["Binding removed; the stored grant was not revoked. Reauthorize or update .mcp.json before reopening."]);
+            agent_next_steps: "The instance binding was removed. The stored grant was not revoked; reauthorize or update the server's declaration before reopening.",
+        }, [
+            "Binding removed; the stored grant was not revoked. Reauthorize or update the server's declaration before reopening.",
+        ]);
         return;
     }
-    httpServer(resolveMcpServers(target, context.environment, server), server);
+    httpServer(resolveMcpServers(declareMcp(target, mcpInstance(config)), context.environment, server, target, {}), server);
     const seconds = options.timeout === undefined ? 900 : Number(options.timeout);
     if (!Number.isInteger(seconds) || seconds <= 0)
         return failUsage("--timeout must be a positive whole number of seconds");
@@ -73,6 +80,7 @@ export async function runMcp(action, server, dir, options) {
     const run = async (step) => {
         const grant = await signInMcp({
             agentDir: target,
+            ...(config === undefined ? {} : { config }),
             server,
             store: context.auth.store,
             scopes,

package/dist/cli/commands/models.js

@@ -3,6 +3,7 @@
  * published catalogs, and the providers its definition declares), or, outside an agent, the built-ins; `[search]`
  * filters by substring. `--refresh` asks the network for the lists even when the kept ones are fresh.
  */
+import { definedValues } from "../../declared-secrets.js";
 import { InMemoryCredentialStore } from "@earendil-works/pi-ai";
 import { modelEnvironment } from "../../harnesses/models/environment.js";
 import { listModels, providerOf } from "../../harnesses/models/models.js";
@@ -18,13 +19,13 @@ export async function runModels(search, opts = {}) {
     let providers = [];
     if (agentDir) {
         enterAgentEnv(agentDir); // a provider in code may read its secrets when it is built
-        providers = await definitionProviders(agentDir).catch(failStartup);
+        providers = await definitionProviders(agentDir, process.env).catch(failStartup);
     }
     else {
         installProxyFetch();
     }
     // Outside an agent, no credentials file is read: the built-ins' lists need none.
-    const environment = await modelEnvironment(agentDir, agentDir ? {} : { credentialStore: new InMemoryCredentialStore() }, providers, { force: opts.refresh === true });
+    const environment = await modelEnvironment(agentDir, agentDir ? {} : { credentialStore: new InMemoryCredentialStore() }, providers, { force: opts.refresh === true, environment: definedValues(process.env) });
     const { lines, error } = formatModelsCommand(listModels(environment.models), search);
     if (opts.json) {
         const models = lines.map((spec) => {

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

@@ -1,9 +1,10 @@
+import { type InstanceFlags } from "../instance.ts";
 /**
  * Text mode answers "when does each run next, and did the last run work?" from the newest claim alone, so an old file
  * in the retained window cannot fail it; `--json` adds each schedule's whole retained fire history (the claims under
  * `schedule/claims/<name>/`). What a run SAID is in its session, once it has fired.
  */
-export declare function runSchedulesList(dirArg: string, json: boolean): Promise<void>;
+export declare function runSchedulesList(dirArg: string, json: boolean, instance?: InstanceFlags): Promise<void>;
 /**
  * Fire the schedule `name` now, as its clock would: in its session, with its claim and its outcome recorded. It opens
  * the instance's storage, so a serve of it refuses this, and the other way round. The answer goes to stdout; exit 0
@@ -12,10 +13,11 @@ export declare function runSchedulesList(dirArg: string, json: boolean): Promise
 export declare function runScheduleNow(name: string, dirArg: string, opts: {
     model?: string;
     input?: boolean;
+    instance?: InstanceFlags;
 }): Promise<void>;
 /**
  * Cancel the pending wake-up `id`, whatever session set it: the one way out of a wake-up set where nobody can message
  * the agent (a schedule's own session). It holds the instance's storage while it writes, so it is refused while a serve
  * of the instance runs, whose poll writes the same store.
  */
-export declare function runUnwake(id: string, dirArg: string): Promise<void>;
+export declare function runUnwake(id: string, dirArg: string, instance?: InstanceFlags): Promise<void>;

package/dist/cli/commands/schedules.js

@@ -8,8 +8,7 @@
 import { resolve } from "node:path";
 import * as Effect from "effect/Effect";
 import { AgentError, hasEnded } from "../../agent-api.js";
-import { enterAgentEnv } from "../../env.js";
-import { buildDefinitionShape, prepareDefinition } from "../../harnesses/pi-durable/open.js";
+import { buildDefinitionShape, loadDevProject, loadSourceDefinition } from "../../harnesses/pi-durable/open.js";
 import { holdingInstance, openServing } from "../../harnesses/pi-durable/serve.js";
 import { resolveStateRoot } from "../../paths.js";
 import { nextRun } from "../../schedule/cron.js";
@@ -18,18 +17,19 @@ import { latestFire, readFires } from "../../schedule/state.js";
 import { listWakeups, removeAnyWakeup } from "../../schedule/wakeups.js";
 import { agentDirOrExit, failStartup, failUsage } from "../fail.js";
 import { exitCodeOf } from "../invoke-stream.js";
+import { enterInstance, instanceInputs } from "../instance.js";
 import { enterAgentCommand, reportAuth } from "../shared.js";
 /**
  * Text mode answers "when does each run next, and did the last run work?" from the newest claim alone, so an old file
  * in the retained window cannot fail it; `--json` adds each schedule's whole retained fire history (the claims under
  * `schedule/claims/<name>/`). What a run SAID is in its session, once it has fired.
  */
-export async function runSchedulesList(dirArg, json) {
+export async function runSchedulesList(dirArg, json, instance) {
     const target = agentDirOrExit(resolve(dirArg));
-    enterAgentEnv(target); // FASTAGENT_STATE_DIR may live in .env — read the SAME state root the scheduler wrote
+    enterInstance(target, instance); // FASTAGENT_STATE_DIR may live in .env — read the SAME state root the scheduler wrote
     const stateRoot = resolveStateRoot(target);
     // Its shape only: listing what will fire needs none of the values the code reads.
-    const { schedules } = await prepareDefinition(target)
+    const { schedules } = await loadSourceDefinition(target)
         .then((definition) => buildDefinitionShape(definition, process.env))
         .catch(failStartup);
     const sessions = scheduleSessions(stateRoot);
@@ -83,7 +83,7 @@ export async function runScheduleNow(name, dirArg, opts) {
     // The name before the model, from the definition's shape: a script told its schedule does not exist need not set up
     // a model first.
     const { agentDir, modelSpec } = await enterAgentCommand(dirArg, opts, async (target) => {
-        const declared = await prepareDefinition(target)
+        const declared = await loadSourceDefinition(target)
             .then((definition) => buildDefinitionShape(definition, process.env).schedules.map((s) => s.name))
             .catch(failStartup);
         if (!declared.includes(name)) {
@@ -91,10 +91,14 @@ export async function runScheduleNow(name, dirArg, opts) {
         }
     });
     // Refused while the instance holds work a stopped serve left: this process would run it, and cut it off at its exit.
-    const { agent, models, schedules, stateRoot } = await openServing(agentDir, {
+    const { agent, models, schedules, stateRoot } = await loadDevProject(agentDir)
+        .then(({ definition, instance }) => openServing(definition, {
         model: modelSpec,
+        ...instanceInputs(agentDir),
         unfinished: "refuse",
-    }).catch(failStartup);
+        ...(instance === undefined ? {} : { config: instance }),
+    }))
+        .catch(failStartup);
     const schedule = schedules.find((s) => s.name === name);
     if (schedule === undefined) {
         // Checked above: only an edit of src/schedules/ while this ran gets here.
@@ -131,9 +135,9 @@ export async function runScheduleNow(name, dirArg, opts) {
  * the agent (a schedule's own session). It holds the instance's storage while it writes, so it is refused while a serve
  * of the instance runs, whose poll writes the same store.
  */
-export async function runUnwake(id, dirArg) {
+export async function runUnwake(id, dirArg, instance) {
     const target = agentDirOrExit(resolve(dirArg));
-    enterAgentEnv(target);
+    enterInstance(target, instance);
     const stateRoot = resolveStateRoot(target);
     const removed = await holdingInstance(stateRoot, () => removeAnyWakeup(stateRoot, id)).catch(failStartup);
     if (removed === undefined) {

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

@@ -0,0 +1,14 @@
+/** The targets that keep a deployment's values in a store of their own. */
+export type SecretsHost = "docker" | "fly" | "railway" | "agentcore";
+export interface SecretsOptions {
+    /** `--config <file>`: the instance configuration the deployment delivers; its channels decide which names it reads. */
+    config?: string;
+    /** `--env-file <file>` (push): where the values come from. */
+    envFile?: string;
+    /** `--from-env` (push): the environment this command runs in. */
+    fromEnv?: boolean;
+    /** `--generate` (set): a random value, printed once. */
+    generate?: boolean;
+    json?: boolean;
+}
+export declare function runSecrets(action: "list" | "set" | "push", host: SecretsHost, name: string | undefined, dirArg: string, opts: SecretsOptions): Promise<void>;

package/dist/cli/commands/secrets.js

@@ -0,0 +1,213 @@
+/**
+ * `fastagent secrets list|set|push <host>`: a deployment's values on the target that keeps them (agent-artifact.md
+ * §6.2). `deploy` checks names and never carries a file; these are how the values get there. A value is never an
+ * argument: it is typed without echo, read from standard input, taken from a value file, or from the environment of a
+ * command that injected it (`op run -- fastagent secrets push fly --from-env`).
+ */
+import { randomBytes } from "node:crypto";
+import { basename, resolve } from "node:path";
+import { isCancel, password } from "@clack/prompts";
+import { isEnvName } from "../../declared-secrets.js";
+import { agentcoreName, agentcoreSecretName } from "../../deploy/agentcore/plan.js";
+import { agentcoreSecretStore } from "../../deploy/agentcore/store.js";
+import { deploymentApi } from "../../deploy/api.js";
+import { fileStore } from "../../deploy/file-store.js";
+import { toFlyAppName, parseFlyAppName } from "../../deploy/fly/plan.js";
+import { flyStore } from "../../deploy/fly/store.js";
+import { toRailwayName } from "../../deploy/railway/plan.js";
+import { railwayStore } from "../../deploy/railway/store.js";
+import { preflightDeploy } from "../../deploy/preflight.js";
+import { awsRunner, spawnRunner } from "../../deploy/runner.js";
+import { declaredNames, hostSignedOutGate, secretNeeds } from "../../deploy/secrets.js";
+import { readInstanceConfigFile, resolveConfig } from "../../harnesses/pi-durable/config.js";
+import { loadSourceDefinition } from "../../harnesses/pi-durable/open.js";
+import { API_KEY_VARIABLE } from "../../http/server.js";
+import { readTextIfExists, selectAgentEnvironment } from "../../paths.js";
+import { unmarkDevServe } from "../../serving-command.js";
+import { dotEnvPath, loadEnvValues } from "../../value-file.js";
+import { agentDirOrExit, failStartup, failUsage } from "../fail.js";
+import { printReport } from "../ticket.js";
+import { join } from "node:path";
+const LABELS = {
+    docker: "Docker",
+    fly: "Fly",
+    railway: "Railway",
+    agentcore: "AWS Secrets Manager",
+};
+/** The store of `host` for the agent in `agentDir`, its CLI signed in. */
+async function openStore(host, agentDir) {
+    const log = (message) => console.error(`[fastagent] ${message}`);
+    if (host === "docker")
+        return fileStore(agentDir, dotEnvPath(agentDir));
+    if (host === "agentcore")
+        return agentcoreSecretStore(awsRunner(agentDir), agentcoreSecretName(agentcoreName(basename(agentDir))), log);
+    if (host === "fly") {
+        const fly = spawnRunner("fly", agentDir, { stdoutToStderr: true });
+        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"));
+        }
+        if ((await fly(["auth", "whoami"], { capture: true })).code !== 0) {
+            failStartup(new Error(hostSignedOutGate("Fly", "fly auth login", "FLY_API_TOKEN", "fly auth login")));
+        }
+        const toml = await readTextIfExists(join(agentDir, "fly.toml"));
+        const app = (toml && parseFlyAppName(toml)) ?? toFlyAppName(basename(agentDir));
+        return flyStore(fly, app, log, { stage: false });
+    }
+    const railway = spawnRunner("railway", agentDir, { stdoutToStderr: true });
+    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"));
+    }
+    if ((await railway(["whoami"], { capture: true })).code !== 0) {
+        failStartup(new Error(hostSignedOutGate("Railway", "railway login", "RAILWAY_API_TOKEN (an account token)", "railway login")));
+    }
+    return railwayStore(railway, toRailwayName(basename(agentDir)), log, { redeploy: true });
+}
+/** What the definition declares for the deployment, and the production value file it reads. */
+async function declared(agentDir, configFile, host) {
+    const instance = configFile === undefined ? undefined : await readInstanceConfigFile(resolve(configFile));
+    const definition = await loadSourceDefinition(agentDir);
+    const config = resolveConfig(definition, instance);
+    const api = deploymentApi({ config, hostServes: host !== "agentcore" });
+    const facts = await preflightDeploy({
+        agentDir,
+        config,
+        ...(instance === undefined
+            ? {}
+            : { delivered: { source: instance, text: `${JSON.stringify(instance.values, null, 2)}\n` } }),
+        run: false,
+        force: false,
+        noResidentProcess: false,
+        storageResets: false,
+        servesApi: api.served,
+    });
+    if (!facts.ok)
+        throw new Error(facts.gate);
+    return {
+        needs: secretNeeds(facts.modelAuth, facts.declaredSecrets, facts.modelKey),
+        names: declaredNames(facts.modelAuth, facts.declaredSecrets, facts.modelKey),
+        modelKeys: facts.modelKey.variables,
+        // The key of the Agent API: on the hosts that serve it.
+        apiNames: api.served ? [API_KEY_VARIABLE] : [],
+    };
+}
+async function readStdin() {
+    const chunks = [];
+    for await (const chunk of process.stdin)
+        chunks.push(Buffer.from(chunk));
+    return Buffer.concat(chunks).toString("utf8");
+}
+/** The value for `name`: random with `--generate`, else typed without echo at a terminal, else the whole standard input. */
+async function valueFor(name, generate) {
+    if (generate)
+        return { value: randomBytes(32).toString("base64url"), minted: true };
+    if (process.stdin.isTTY) {
+        const typed = await password({ message: name });
+        if (isCancel(typed))
+            throw new Error("cancelled");
+        return { value: String(typed), minted: false };
+    }
+    return { value: (await readStdin()).replace(/\r?\n$/, ""), minted: false };
+}
+export async function runSecrets(action, host, name, dirArg, opts) {
+    if (action === "set" && !isEnvName(name))
+        failUsage(`${name} is not an environment variable name`);
+    if (action === "push" && opts.fromEnv && opts.envFile !== undefined) {
+        failUsage("--env-file and --from-env are two sources: pass one");
+    }
+    const agentDir = agentDirOrExit(resolve(dirArg));
+    // The deployment's own, never the development instance's: its channels receive the way the box will choose.
+    selectAgentEnvironment("production");
+    unmarkDevServe();
+    try {
+        const store = await openStore(host, agentDir);
+        if (action === "list")
+            return await list(store, host, agentDir, opts);
+        if (action === "set")
+            return await set(store, host, name, opts, agentDir);
+        return await push(store, host, agentDir, opts);
+    }
+    catch (error) {
+        failStartup(error);
+    }
+}
+/** When a written value reaches what is running: a Docker container reads its file at start, an AgentCore session its secret. */
+function noteWhenItTakesEffect(host) {
+    if (host === "docker") {
+        console.error("[fastagent] note: a running container reads it after `docker compose up -d`, or the next `deploy docker --run`");
+    }
+    if (host === "agentcore") {
+        console.error("[fastagent] note: the runtime reads the secret when a session starts: a session already running keeps its values " +
+            "until it ends (its idle timeout) or the next deploy");
+    }
+}
+async function list(store, host, agentDir, opts) {
+    const label = LABELS[host];
+    const { needs, names, modelKeys } = await declared(agentDir, opts.config, host);
+    // A target with no app yet holds nothing: every name is missing, which is an answer and not a failure.
+    const present = await store.exists();
+    if (!present)
+        console.error(`[fastagent] ${label} has no app for this agent yet: the first set, push or \`deploy --run\` makes it`);
+    const have = present ? await store.names() : new Set();
+    const required = new Set(needs.map((need) => need.name));
+    const rows = names.map((name) => ({
+        name,
+        set: have.has(name),
+        required: required.has(name),
+        hint: needs.find((need) => need.name === name)?.hint ??
+            (modelKeys.includes(name) ? "your model provider key, or a login on the box" : undefined),
+    }));
+    printReport(opts.json, { host: label, exists: present, secrets: rows }, rows.map(({ name, set, required: must, hint }) => `${set ? "set    " : "missing"}  ${name}  (${must ? (hint ?? "required") : `optional${hint === undefined ? "" : `: ${hint}`}`})`));
+}
+async function set(store, host, name, opts, agentDir) {
+    const label = LABELS[host];
+    const { names, apiNames } = await declared(agentDir, opts.config, host);
+    if (!names.includes(name) && !apiNames.includes(name)) {
+        console.error(`[fastagent] warn: ${name} is not declared by the definition, so nothing reads it on ${label}`);
+    }
+    const { value, minted } = await valueFor(name, opts.generate);
+    if (value.trim() === "")
+        throw new Error(`${name} would be empty`);
+    await store.ensure();
+    await store.write({ [name]: value });
+    console.error(`[fastagent] set ${name} on ${label}`);
+    noteWhenItTakesEffect(host);
+    // The one time a value is shown: it was made here and nobody holds it yet.
+    if (minted)
+        console.log(value);
+}
+async function push(store, host, agentDir, opts) {
+    const label = LABELS[host];
+    const { names, apiNames } = await declared(agentDir, opts.config, host);
+    const known = new Set([...names, ...apiNames]);
+    let source;
+    let where;
+    if (opts.fromEnv) {
+        source = new Map(Object.entries(process.env).flatMap(([n, v]) => (v === undefined ? [] : [[n, v]])));
+        where = "the environment";
+    }
+    else {
+        if (host === "docker" && opts.envFile === undefined) {
+            throw new Error(`${dotEnvPath(agentDir)} is Docker's own store, so there is nothing to push from it: pass --env-file <file> or --from-env`);
+        }
+        const file = opts.envFile === undefined ? dotEnvPath(agentDir) : resolve(opts.envFile);
+        source = loadEnvValues(file);
+        where = file;
+        if (source.size === 0 && opts.envFile === undefined) {
+            throw new Error(`${file} holds no values: pass --env-file <file>, or --from-env for the environment`);
+        }
+    }
+    const toWrite = {};
+    for (const [n, v] of source)
+        if (known.has(n) && v.trim() !== "")
+            toWrite[n] = v;
+    const skipped = opts.fromEnv ? [] : [...source.keys()].filter((n) => !known.has(n));
+    if (skipped.length > 0) {
+        console.error(`[fastagent] not pushed, since the definition does not declare them: ${skipped.join(", ")}`);
+    }
+    if (Object.keys(toWrite).length === 0)
+        throw new Error(`${where} holds a value for none of the names the definition declares`);
+    await store.ensure();
+    await store.write(toWrite);
+    console.error(`[fastagent] pushed ${Object.keys(toWrite).length} value(s) from ${where} to ${label}: ${Object.keys(toWrite).join(", ")}`);
+    noteWhenItTakesEffect(host);
+}

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

@@ -1,5 +1,6 @@
 import type { Agent } from "../../agent-api.ts";
-import type { AgentConfig } from "../../harnesses/pi-durable/define.ts";
+import type { EffectiveConfig } from "../../harnesses/pi-durable/config.ts";
+import { type InstanceFlags } from "../instance.ts";
 import { type ServedAgent } from "../../service.ts";
 export interface StartOptions {
     port?: string;
@@ -7,29 +8,28 @@ export interface StartOptions {
     model?: string;
     tunnel?: boolean;
     input?: boolean;
+    instance?: InstanceFlags;
 }
 /** What `start` opened and serves: the agent too, for a deployment's own check of what it runs. */
 type StartedService = ServedAgent & {
     agent: Agent;
     stateRoot: string;
     port: number;
-    config: AgentConfig;
+    config: EffectiveConfig;
 };
 export declare function runStart(dirArg: string, opts: StartOptions): Promise<void>;
-/** What the storage stage hands the opening stage. */
-export interface PreparedWorkspace {
-    /** The agent directory to open — the storage's deployed definition when a release manifest selected one. */
-    dir: string;
-    /** The storage root, set when this process took a deployment's storage. */
-    deployed?: {
-        root: string;
-    };
-}
 /**
- * Stage one — TAKE the storage: verify it is mounted, apply the release, and point the machinery at the volume.
+ * Stage one — TAKE the storage, on a deployed box (a release manifest names it): it is mounted, held by this process,
+ * and this agent's; it becomes the instance's root, and the machinery points at it. The program stays where the image
+ * built it, `dirArg`. Returns that directory. Elsewhere, nothing is taken.
+ */
+export declare function prepareStartWorkspace(dirArg: string): Promise<string>;
+/**
+ * AgentCore's stage one: the deployment's values first, on the first invocation, so a failed read is that invocation's
+ * failure and the next asks again; then the storage.
  */
-export declare function prepareStartWorkspace(dirArg: string): Promise<PreparedWorkspace>;
+export declare function prepareAgentcoreWorkspace(dirArg: string): Promise<string>;
 export declare function openStartService(dirArg: string, opts: StartOptions): Promise<StartedService>;
-/** Internal entry loaded from the agent's installed package after storage initialization. */
+/** Stage two: open the built definition in `dirArg` and serve it. */
 export declare function openPreparedStartService(dirArg: string, opts: StartOptions): Promise<StartedService>;
 export {};