@fastagent-sh/fastagent 0.28.0 → 0.30.0

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

package/dist/cli/commands/start.js

@@ -1,21 +1,14 @@
-var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
-    if (typeof path === "string" && /^\.\.?\//.test(path)) {
-        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
-            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
-        });
-    }
-    return path;
-};
 /** Production serving. */
 import { join, resolve } from "node:path";
-import { pathToFileURL } from "node:url";
-import { createRequire } from "node:module";
 import { readFile } from "node:fs/promises";
-import { applyCarriedEnv } from "../../deploy/secrets.js";
-import { applyReleaseEnv, installAgentDependencies, parseDeploymentRelease, prepareDeployment, } from "../../deploy/workspace.js";
-import { selectAgentEnvironment, resolveSecretsDir, isAgentcoreRuntime, isUnderDir, exists } from "../../paths.js";
+import { applyRuntimeSecrets } from "../../deploy/agentcore/runtime-secrets.js";
+import { applyReleaseEnv, parseDeploymentRelease, prepareDeployment } from "../../deploy/workspace.js";
+import { selectAgentEnvironment, resolveSecretsDir, isAgentcoreRuntime, isDeployedWorkspace, isUnderDir, INSTANCE_ROOT_ENV, } from "../../paths.js";
 import { log, setLogLevel } from "../../log.js";
+import { loadProjectBuild } from "../../harnesses/pi-durable/built.js";
+import { namedInstanceConfig } from "../../harnesses/pi-durable/config.js";
 import { openServing } from "../../harnesses/pi-durable/serve.js";
+import { instanceInputs } from "../instance.js";
 import { DEFAULT_HTTP_PORT, serveAgent } from "../../service.js";
 import { mountAgentcoreService, deferAgentcoreService } from "../../channels/agentcore-service.js";
 import { failStartup } from "../fail.js";
@@ -25,13 +18,6 @@ import { enterAgentCommand, parseBind, parsePort, reportAssembly } from "../shar
 export async function runStart(dirArg, opts) {
     const portFlag = parsePort(opts.port, "--port", "flag");
     const bindFlag = parseBind(opts.bind);
-    // A host that carries the value file as ONE encoded variable (AgentCore): expanded before anything reads the env.
-    try {
-        applyCarriedEnv();
-    }
-    catch (error) {
-        failStartup(error);
-    }
     setLogLevel("info");
     selectAgentEnvironment("production");
     unmarkDevServe();
@@ -39,9 +25,9 @@ export async function runStart(dirArg, opts) {
         // The generated Runtime resource sets PORT; 8080 is the platform's contract when nothing does.
         const port = portFlag ?? parsePort(process.env.PORT, "PORT env", "env") ?? 8080;
         const deferred = deferAgentcoreService({
-            prepare: () => prepareStartWorkspace(dirArg),
-            assemble: async (prepared) => {
-                const service = await openPreparedWorkspace(prepared, opts);
+            prepare: () => prepareAgentcoreWorkspace(dirArg),
+            assemble: async (dir) => {
+                const service = await openPreparedStartService(dir, opts);
                 await service.ready;
                 return service;
             },
@@ -53,28 +39,31 @@ export async function runStart(dirArg, opts) {
         });
         return;
     }
-    // Deployed storage refusals (no mount, a held lease, a missing `flock`, a failed install) are the operator's only
+    // Deployed storage refusals (no mount, a held lease, a missing `flock`, another agent's storage) are the operator's only
     // clue in a crash-looping container.
     const service = await openStartService(dirArg, opts).catch(failStartup);
     const tunnel = opts.tunnel ?? false;
     // An unset bind stays the wildcard: this is the container posture, and a published port needs it.
     assertTunnelBindable(bindFlag, tunnel);
-    serveService(service, { port: portFlag ?? parsePort(process.env.PORT, "PORT env", "env") ?? service.port, host: bindFlag }, { tunnel, agentDir: service.agentDir, stateRoot: service.stateRoot, config: service.config });
+    serveService(service, { port: portFlag ?? parsePort(process.env.PORT, "PORT env", "env") ?? service.port, host: bindFlag }, { tunnel, agentDir: service.agentDir, config: service.config });
 }
 /**
- * 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 async function prepareStartWorkspace(dirArg) {
     const manifestPath = process.env.FASTAGENT_RELEASE_FILE;
     if (!manifestPath)
-        return { dir: dirArg };
-    const storage = process.env.FASTAGENT_STORAGE_DIR;
+        return dirArg;
+    const storage = process.env[INSTANCE_ROOT_ENV];
     if (!storage)
-        throw new Error("FASTAGENT_STORAGE_DIR is required for a deployment");
+        throw new Error(`${INSTANCE_ROOT_ENV} is required for a deployment`);
     const root = resolve(storage);
     const manifest = parseDeploymentRelease(await readFile(manifestPath, "utf8"));
-    const dir = await prepareDeployment(resolve(dirArg), root, manifest);
-    // Defaults, not overrides: an operator who pointed either dir somewhere else meant it, and silently relocating
+    await prepareDeployment(root, manifest);
+    process.env[INSTANCE_ROOT_ENV] = root;
+    // Defaults, not overrides: an operator who pointed a directory somewhere else meant it, and silently relocating
     // their state is the one failure they could not diagnose from the logs.
     process.env.FASTAGENT_STATE_DIR ||= join(root, ".state");
     process.env.FASTAGENT_SECRETS_DIR ||= join(root, ".secrets");
@@ -85,40 +74,31 @@ export async function prepareStartWorkspace(dirArg) {
     // `enterAgentEnv` reads the agent's `.env`, which is what makes either source outrank a value edited on the
     // box (applyReleaseEnv's own tests pin the precedence).
     applyReleaseEnv(manifest);
-    process.chdir(dir);
-    return { dir, deployed: { root } };
+    return dirArg;
 }
 /**
- * Stage two — RUN the prepared agent directory: install its dependencies, then open through its own FastAgent install.
+ * 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.
  */
-async function openPreparedWorkspace(prepared, opts) {
-    let open = openPreparedStartService;
-    if (prepared.deployed) {
-        const { root } = prepared.deployed;
-        const agentDir = prepared.dir;
-        if (await exists(join(agentDir, "package.json"))) {
-            await installAgentDependencies(root, agentDir);
-            // Tools and their session context must share the agent's runtime module instance.
-            const entry = createRequire(join(agentDir, "package.json")).resolve("@fastagent-sh/fastagent");
-            const local = (await import(__rewriteRelativeImportExtension(new URL("./cli/commands/start.js", pathToFileURL(entry)).href)));
-            // A version-skewed dependency resolves and imports fine, then fails as "open is not a function" with nothing
-            // naming the two versions.
-            if (typeof local.openPreparedStartService !== "function") {
-                throw new Error(`${entry} does not export openPreparedStartService — align the agent's @fastagent-sh/fastagent version with the deploy CLI`);
-            }
-            open = local.openPreparedStartService;
-        }
-    }
-    return open(prepared.dir, opts);
+export async function prepareAgentcoreWorkspace(dirArg) {
+    await applyRuntimeSecrets();
+    return prepareStartWorkspace(dirArg);
 }
 export async function openStartService(dirArg, opts) {
-    return openPreparedWorkspace(await prepareStartWorkspace(dirArg), opts);
+    return openPreparedStartService(await prepareStartWorkspace(dirArg), opts);
 }
-/** Internal entry loaded from the agent's installed package after storage initialization. */
+/** Stage two: open the built definition in `dirArg` and serve it. */
 export async function openPreparedStartService(dirArg, opts) {
-    const { agentDir, modelSpec } = await enterAgentCommand(dirArg, opts);
-    const opened = await openServing(agentDir, {
+    // The build, never the source (agent-artifact.md §8): refused when there is none or the project has moved on.
+    let built;
+    // A start never reads the development `fastagent.json`: its instance configuration is the one `--config` names.
+    const loadBuilt = (dir) => (built ??= loadProjectBuild(dir, { checkSources: !isDeployedWorkspace() }).then((definition) => ({ definition })));
+    const { agentDir, modelSpec } = await enterAgentCommand(dirArg, opts, undefined, loadBuilt);
+    const config = await namedInstanceConfig();
+    const opened = await openServing((await loadBuilt(agentDir)).definition, {
         model: modelSpec,
+        ...instanceInputs(agentDir),
+        ...(config === undefined ? {} : { config }),
         // AgentCore's session storage refuses SQLite's own locks; the deployment's lease makes the dotfile lock safe.
         storage: { instance: isAgentcoreRuntime() ? "leased-dotfile" : "posix" },
     });
@@ -130,9 +110,15 @@ export async function openPreparedStartService(dirArg, opts) {
     if (isUnderDir(resolveSecretsDir(agentDir), agentDir)) {
         log.info("[fastagent] note: credentials live under the definition; use FASTAGENT_SECRETS_DIR on persistent storage for deployment.");
     }
-    const { config } = opened.definition;
+    const { config: effective } = opened;
     const service = await (isAgentcoreRuntime()
         ? mountAgentcoreService(opened)
-        : serveAgent(opened, cliMountOptions(config)));
-    return { ...service, agent: opened.agent, stateRoot, port: config.http?.port ?? DEFAULT_HTTP_PORT, config };
+        : serveAgent(opened, cliMountOptions(effective)));
+    return {
+        ...service,
+        agent: opened.agent,
+        stateRoot,
+        port: effective.http?.port ?? DEFAULT_HTTP_PORT,
+        config: effective,
+    };
 }

package/dist/cli/content-view.d.ts

@@ -1,9 +1,7 @@
 /** How the CLI writes an agent's content. */
-import type { BoundContent } from "../content/declare.ts";
-import { type ResolvedContent } from "../content/resolve.ts";
+import type { ResolvedContent } from "../content/resolve.ts";
 /**
- * The report lines for an agent's content — `works on`, one per entry, then a `notice` line for each
- * thing its resolution has to say, then one for each directory this machine binds that is not here — shared by the
- * startup report, `info` and `content list`, so the three say the same thing.
+ * The report lines for an agent's content — `works on`, one per entry, then a `notice` line for each thing its
+ * resolution has to say — shared by the startup report, `info` and `content list`, so the three say the same thing.
  */
-export declare function contentLines(content: readonly ResolvedContent[], absent?: readonly BoundContent[]): [label: string, value: string][];
+export declare function contentLines(content: readonly ResolvedContent[]): [label: string, value: string][];

package/dist/cli/content-view.js

@@ -1,24 +1,18 @@
-import { LOCAL_CONTEXT_FILE } from "../paths.js";
-import { absentNotice } from "../content/resolve.js";
 /** What a content entry is, in the words the reports use. */
 function contentKind(c) {
     if (c.kind !== "github")
-        return `this machine only, bound in ${LOCAL_CONTEXT_FILE}`;
-    const github = `github ${c.repo}${c.ref ? `@${c.ref}` : ""}`;
-    return c.clone ? `${github}, a clone brought up to date at each start` : `${github}, your checkout bound here`;
+        return "a directory of this machine";
+    return `github ${c.repo}${c.ref ? `@${c.ref}` : ""}, a clone brought up to date at each start`;
 }
 /**
- * The report lines for an agent's content — `works on`, one per entry, then a `notice` line for each
- * thing its resolution has to say, then one for each directory this machine binds that is not here — shared by the
- * startup report, `info` and `content list`, so the three say the same thing.
+ * The report lines for an agent's content — `works on`, one per entry, then a `notice` line for each thing its
+ * resolution has to say — shared by the startup report, `info` and `content list`, so the three say the same thing.
  */
-export function contentLines(content, absent = []) {
+export function contentLines(content) {
     const lines = content.flatMap((c) => [
         ["works on", `${c.name.padEnd(width(content))}  ${c.location} (${contentKind(c)})`],
         ...c.notices.map((notice) => ["notice", `${c.name}: ${notice}`]),
     ]);
-    for (const binding of absent)
-        lines.push(["notice", absentNotice(binding)]);
     return lines.length === 0 ? [["content", "(none)"]] : lines;
 }
 function width(content) {

package/dist/cli/first-run-channels.d.ts

@@ -0,0 +1,3 @@
+export declare function setUpMissingChannels(agentDir: string, opts?: {
+    input?: boolean;
+}): Promise<void>;

package/dist/cli/first-run-channels.js

@@ -0,0 +1,63 @@
+/**
+ * A channel the development instance has no credentials for yet is set up the first time `dev` runs (channel-setup.md
+ * §2), the way the first run picks a model: in the parent process, at a terminal, once per project. Without a terminal
+ * nothing is asked and nothing waits: the command that does it for a coding agent is named.
+ */
+import { resolveConfig } from "../harnesses/pi-durable/config.js";
+import { codeSecrets } from "../harnesses/pi-durable/definition.js";
+import { chosenIngress } from "../harnesses/pi-durable/definition.js";
+import { loadDevProject } from "../harnesses/pi-durable/open.js";
+import { missingSecrets } from "../declared-secrets.js";
+import { dotEnvPath, loadEnvValues } from "../value-file.js";
+import { isSetupKind, setUpChannel, setupNames } from "./channel-setup.js";
+import { failStartup, failUsage } from "./fail.js";
+import { isInteractive } from "./shared.js";
+/** The first-party channels the agent mounts whose credentials this process's environment lacks, and the configuration. */
+async function lackingChannels(agentDir) {
+    const project = await loadDevProject(agentDir).catch(failStartup);
+    const config = resolveConfig(project.definition, project.instance);
+    const missing = missingSecrets(codeSecrets(project.definition, config), process.env);
+    const kinds = project.definition.registry.channels.flatMap(({ file, name }) => {
+        if (!isSetupKind(name))
+            return [];
+        // Only what the channel's own setup supplies: a channel file of the same name that reads other variables is its
+        // author's to fill.
+        const supplied = setupNames(name, chosenIngress(config, name, true));
+        return missing.some((secret) => secret.declaredIn === file && supplied.includes(secret.name)) ? [name] : [];
+    });
+    return { kinds, config };
+}
+export async function setUpMissingChannels(agentDir, opts = {}) {
+    const { kinds, config } = await lackingChannels(agentDir);
+    if (kinds.length === 0)
+        return;
+    if (opts.input === false || !isInteractive()) {
+        const lacking = kinds
+            .map((kind) => `${kind} has no credentials in ${dotEnvPath(agentDir)}: run \`fastagent channels setup ${kind} --json\``)
+            .join("; ");
+        failUsage(`${lacking} (it hands the person's part to its user), or run \`fastagent dev\` in a terminal, which asks`);
+    }
+    const file = dotEnvPath(agentDir);
+    for (const kind of kinds) {
+        console.error(`[fastagent] ${kind} has no credentials in ${file} yet: setting it up (\`fastagent channels setup ${kind}\`)`);
+        const outcome = await setUpChannel({
+            kind,
+            agentDir,
+            file,
+            way: chosenIngress(config, kind, true),
+            dev: true,
+            rerun: `fastagent channels setup ${kind}`,
+            ...(config.http?.publicUrl === undefined ? {} : { publicUrl: config.http.publicUrl }),
+        }).catch((error) => failStartup(new Error(`${kind} setup did not finish (${error.message}): \`dev\` needs it while src/channels/${kind}.ts ` +
+            `exists. Run \`fastagent channels setup ${kind}\` when ready, or remove the file`, { cause: error })));
+        // What setup wrote is this process's now, and the dev worker's: a value it replaced would otherwise keep the old one.
+        const values = loadEnvValues(file);
+        for (const name of outcome.written)
+            process.env[name] = values.get(name);
+        if (outcome.after.length > 0) {
+            console.error("  next steps:");
+            for (const line of outcome.after)
+                console.error(`    ${line}`);
+        }
+    }
+}

package/dist/cli/instance.d.ts

@@ -0,0 +1,41 @@
+import type { ContentScope } from "../authoring.ts";
+import type { OpenServingOptions } from "../harnesses/pi-durable/serve.ts";
+import { type RunsAs } from "../serving-command.ts";
+import type { FlagSpec } from "./kernel.ts";
+/** The flags that place an instance, as the commander adapter hands them over. */
+export interface InstanceFlags {
+    name?: string;
+    root?: string;
+    state?: string;
+    workdir?: string;
+    config?: string;
+    envFile?: string;
+}
+/** The flags of a command that opens, or reads the state of, an instance. */
+export declare const INSTANCE_FLAGS: readonly FlagSpec[];
+/** The flags of a command that reads or edits what an instance works on: where it keeps its clones, and its file. */
+export declare const CONTENT_FLAGS: readonly FlagSpec[];
+/** `--config`: the instance configuration, a fastagent.json, for a command that opens the agent. */
+export declare const CONFIG_FLAG: FlagSpec;
+export declare function instanceFlags(flags: Record<string, unknown>): InstanceFlags;
+/** `--env-file`: the file the agent's values are read from, for a command that opens the agent or reads them. */
+export declare const ENV_FILE_FLAG: FlagSpec;
+/**
+ * `--env-file`, settled before the agent's values are entered: absolute, and a file that exists. Without the flag the
+ * command's default file is used again, whatever an earlier command in this process chose.
+ */
+export declare function enterEnvFile(given: string | undefined): void;
+/**
+ * Enter the agent's directory as a command runs it: the value file, whose values become this process's environment
+ * and so the instance's secrets, then where the instance is.
+ */
+export declare function enterInstance(agentDir: string, flags?: InstanceFlags): void;
+/** Where a content command reads and edits an agent's content, as its flags and variables say. */
+export declare function enterContentScope(agentDir: string, flags?: InstanceFlags): ContentScope;
+/** Who runs this process's instance, as its own variables say: the one place the CLI reads them for an open. */
+export declare function runsAsIn(env: NodeJS.ProcessEnv): RunsAs;
+/**
+ * What `openServing` is given for the agent in `agentDir`, as the flags and variables entered above say: where the
+ * instance is, and its secrets, which for a command are its environment once the value file is entered.
+ */
+export declare function instanceInputs(agentDir: string): Pick<OpenServingOptions, "projectDir" | "workdir" | "stateRoot" | "secrets" | "env" | "ownEnv" | "runsAs" | "name">;

package/dist/cli/instance.js

@@ -0,0 +1,155 @@
+/**
+ * Where a command's instance is (agent-artifact.md §4.1): the flags that place it, over the environment variables that
+ * name the same inputs, settled once at the command's entry into absolute paths in this process's environment. A
+ * `dev` worker inherits them, and every reader after (`resolveStateRoot`, `resolveWorkdir`, the instance configuration)
+ * reads one answer.
+ */
+import { existsSync, mkdirSync, statSync } from "node:fs";
+import { baseEnv } from "../child-env.js";
+import { definedValues } from "../declared-secrets.js";
+import { enterAgentEnv } from "../env.js";
+import { INSTANCE_CONFIG_ENV, INSTANCE_ROOT_ENV, INSTANCE_STATE_ENV, INSTANCE_WORKDIR_ENV, isAgentcoreRuntime, isDeployedWorkspace, resolveOverridePath, resolveStateRoot, resolveWorkdir, } from "../paths.js";
+import { INSTANCE_NAME_ENV, checkInstanceName, enteredInstanceName } from "../instance-name.js";
+import { servedByDev } from "../serving-command.js";
+import { useValueFile } from "../value-file.js";
+import { failUsage } from "./fail.js";
+const INSTANCE_LOCATION = [
+    ["root", "--root", INSTANCE_ROOT_ENV],
+    ["state", "--state", INSTANCE_STATE_ENV],
+    ["workdir", "--workdir", INSTANCE_WORKDIR_ENV],
+    ["config", "--config", INSTANCE_CONFIG_ENV],
+];
+const NAME_FLAG = {
+    flags: "--name <name>",
+    description: `the instance's name, one path segment (${INSTANCE_NAME_ENV}; default: the program's name)`,
+};
+const ROOT_FLAG = {
+    flags: "--root <dir>",
+    description: `the instance root: its working directory, with its state in <dir>/.state (${INSTANCE_ROOT_ENV})`,
+};
+const STATE_FLAG = {
+    flags: "--state <dir>",
+    description: `the instance's state, apart from the root (${INSTANCE_STATE_ENV})`,
+};
+const WORKDIR_FLAG = {
+    flags: "--workdir <dir>",
+    description: `the agent's working directory, apart from the root (${INSTANCE_WORKDIR_ENV})`,
+};
+/** The flags of a command that opens, or reads the state of, an instance. */
+export const INSTANCE_FLAGS = [NAME_FLAG, ROOT_FLAG, STATE_FLAG, WORKDIR_FLAG];
+/** The flags of a command that reads or edits what an instance works on: where it keeps its clones, and its file. */
+export const CONTENT_FLAGS = [
+    ROOT_FLAG,
+    WORKDIR_FLAG,
+    {
+        flags: "--config <file>",
+        description: `the instance configuration to read and edit, a fastagent.json (${INSTANCE_CONFIG_ENV}; default: the project's)`,
+    },
+];
+/** `--config`: the instance configuration, a fastagent.json, for a command that opens the agent. */
+export const CONFIG_FLAG = {
+    flags: "--config <file>",
+    description: `the instance configuration, a fastagent.json (${INSTANCE_CONFIG_ENV}; dev reads the one at the project root)`,
+};
+export function instanceFlags(flags) {
+    const picked = {};
+    for (const key of [...INSTANCE_LOCATION.map(([name]) => name), "name", "envFile"]) {
+        if (typeof flags[key] === "string")
+            picked[key] = flags[key];
+    }
+    return picked;
+}
+function makeDirectory(path, source) {
+    try {
+        mkdirSync(path, { recursive: true });
+    }
+    catch (error) {
+        failUsage(`${source} ${path} cannot be used as a directory: ${error.message}`);
+    }
+}
+/** `--env-file`: the file the agent's values are read from, for a command that opens the agent or reads them. */
+export const ENV_FILE_FLAG = {
+    flags: "--env-file <file>",
+    description: "the file the agent's secrets are read from, over the default (.secrets/.env); it must exist",
+};
+/**
+ * `--env-file`, settled before the agent's values are entered: absolute, and a file that exists. Without the flag the
+ * command's default file is used again, whatever an earlier command in this process chose.
+ */
+export function enterEnvFile(given) {
+    if (given === undefined) {
+        useValueFile(undefined);
+        return;
+    }
+    if (given.trim() === "")
+        failUsage("--env-file needs a path");
+    const path = resolveOverridePath(given);
+    if (!existsSync(path) || !statSync(path).isFile())
+        failUsage(`--env-file ${path} is not a file`);
+    useValueFile(path);
+}
+/**
+ * Enter the agent's directory as a command runs it: the value file, whose values become this process's environment
+ * and so the instance's secrets, then where the instance is.
+ */
+export function enterInstance(agentDir, flags = {}) {
+    enterEnvFile(flags.envFile);
+    enterAgentEnv(agentDir);
+    enterInstanceLocation(flags);
+}
+/** Where a content command reads and edits an agent's content, as its flags and variables say. */
+export function enterContentScope(agentDir, flags = {}) {
+    enterInstanceLocation(flags);
+    const config = process.env[INSTANCE_CONFIG_ENV];
+    return { workdir: resolveWorkdir(agentDir), ...(config === undefined ? {} : { config }) };
+}
+/**
+ * Settle the instance's location: a flag beats its environment variable, a relative path is resolved against the
+ * directory the command was started in (here, once), and the directories named are made. Refuses a flag with no path.
+ */
+function enterInstanceLocation(flags = {}) {
+    for (const [key, flag, variable] of INSTANCE_LOCATION) {
+        const given = flags[key];
+        if (given !== undefined && given.trim() === "")
+            failUsage(`${flag} needs a path`);
+        const path = resolveOverridePath(given ?? process.env[variable]);
+        if (path === undefined)
+            continue;
+        process.env[variable] = path;
+        if (key === "root" || key === "workdir")
+            makeDirectory(path, given === undefined ? variable : flag);
+    }
+    const name = flags.name ?? enteredInstanceName();
+    if (name === undefined)
+        return;
+    try {
+        checkInstanceName(name);
+    }
+    catch (error) {
+        failUsage(`${flags.name === undefined ? INSTANCE_NAME_ENV : "--name"}: ${error.message}`);
+    }
+    process.env[INSTANCE_NAME_ENV] = name;
+}
+/** Who runs this process's instance, as its own variables say: the one place the CLI reads them for an open. */
+export function runsAsIn(env) {
+    return { dev: servedByDev(env), deployed: isDeployedWorkspace(env), agentcore: isAgentcoreRuntime(env) };
+}
+/**
+ * What `openServing` is given for the agent in `agentDir`, as the flags and variables entered above say: where the
+ * instance is, and its secrets, which for a command are its environment once the value file is entered.
+ */
+export function instanceInputs(agentDir) {
+    const workdir = resolveWorkdir(agentDir);
+    // A default one is the project's own `.fastagent/<environment>/`, which nothing has made yet.
+    makeDirectory(workdir, "the working directory");
+    return {
+        projectDir: agentDir,
+        ...(enteredInstanceName() === undefined ? {} : { name: enteredInstanceName() }),
+        workdir,
+        stateRoot: resolveStateRoot(agentDir),
+        secrets: definedValues(process.env),
+        env: baseEnv(process.env),
+        ownEnv: process.env,
+        runsAs: runsAsIn(process.env),
+    };
+}

package/dist/cli/invoke-stream.d.ts

@@ -2,8 +2,11 @@
 import { type Message, type MessageStreamEvent } from "../agent-api.ts";
 /** A command that sends a message exits 0 only when it completed. */
 export declare const exitCodeOf: (message: Pick<Message, "status">) => number;
-/** The answer as text on `out`, what the tools did and why it failed on `err`. */
-export declare function runInvokeStream(events: AsyncIterable<MessageStreamEvent>, out: (text: string) => void, err: (line: string) => void): Promise<number>;
+/**
+ * The answer as text on `out`, what the tools did and why it failed on `err`. `authHint` is what to do when the failure
+ * is a model with no credential, which depends on where the agent runs.
+ */
+export declare function runInvokeStream(events: AsyncIterable<MessageStreamEvent>, out: (text: string) => void, err: (line: string) => void, authHint?: string): Promise<number>;
 /**
  * The answer as JSON lines, for a program to read: the message's events as `messages.stream` delivers them, its
  * `message` first, through its `done`. A message that ends no other way ends with the line that says why: `rejected`

package/dist/cli/invoke-stream.js

@@ -31,8 +31,11 @@ async function readMessage(events, read, refused) {
     }
     return undefined;
 }
-/** The answer as text on `out`, what the tools did and why it failed on `err`. */
-export async function runInvokeStream(events, out, err) {
+/**
+ * The answer as text on `out`, what the tools did and why it failed on `err`. `authHint` is what to do when the failure
+ * is a model with no credential, which depends on where the agent runs.
+ */
+export async function runInvokeStream(events, out, err, authHint) {
     const toolName = new Map(); // a tool result carries the id; its name came with tool_started
     const textOf = answerText();
     const exit = await readMessage(events, (event) => {
@@ -65,6 +68,8 @@ export async function runInvokeStream(events, out, err) {
                 const failed = failure(event.message);
                 if (failed !== undefined)
                     err(`[fastagent] failed: ${failed}`);
+                if (authHint !== undefined && event.message.error?.code === "auth_required")
+                    err(`[fastagent] next: ${authHint}`);
                 return exitCodeOf(event.message);
             }
             default: