@fastagent-sh/fastagent 0.28.0 → 0.30.0

package/dist/cli/commands/deploy.js

@@ -2,21 +2,21 @@
  * `fastagent deploy <host> [agent]`: generate host artifacts from the resolved definition and print an ordered deploy
  * runbook.
  */
-import { relative } from "node:path";
-import { cloudFor } from "../../channels/feishu/cloud.js";
-import { FEISHU_INGRESS_SETTINGS } from "../../channels/feishu/setup-mode.js";
-import { assembleSecrets, divergentSettingsGate, missingValuesGate } from "../../deploy/secrets.js";
+import { resolve } from "node:path";
 import { dotEnvPath, loadEnvValues } from "../../value-file.js";
 import { unmarkDevServe } from "../../serving-command.js";
-import { assertIndependentFeishuApps, feishuAppSecretNames, larkCredentialsNeeded, prepareFeishuApps, unpreparedFeishuApps, } from "../add-feishu.js";
+import { channelAppNames, prepareChannelApps, unpreparedChannelApps } from "./deploy/channel-apps.js";
 import { displayPath, selectAgentEnvironment } from "../../paths.js";
+import { buildProject } from "../../harnesses/pi-durable/build.js";
+import { DELIVERED_CONFIG_DIR } from "../../deploy/container.js";
+import { deliverText } from "../../deploy/delivered-text.js";
 import { preflightDeploy } from "../../deploy/preflight.js";
-import { apiReport, deploymentApi, writeApiKey } from "../../deploy/api.js";
-import { unprotectedSecretsNote } from "../../value-file.js";
-import { loadConfig } from "../../harnesses/pi-durable/open.js";
+import { apiReport, deploymentApi } from "../../deploy/api.js";
+import { API_KEY_VARIABLE, apiKeysFrom } from "../../http/server.js";
+import { readInstanceConfigFile, resolveConfig } from "../../harnesses/pi-durable/config.js";
+import { loadSourceDefinition } from "../../harnesses/pi-durable/open.js";
 import { failStartup, failUsage } from "../fail.js";
 import { enterAgentDirectory, isInteractive, shellArg } from "../shared.js";
-import { terminalPerson } from "../person.js";
 import { checkTicket, printReport, refusedCheck, runTicket, startTicket, stopTicket, ticketExitCode, ticketReport, } from "../ticket.js";
 import { agentcoreHost } from "./deploy/agentcore.js";
 import { dockerHost } from "./deploy/docker.js";
@@ -87,39 +87,33 @@ export async function runDeploy(host, dirArg, opts) {
 async function deploy(host, dirArg, opts, step) {
     if (opts.code !== undefined)
         failUsage("--code hands a code to a deploy's ticket: pass --check <ticket> too");
-    if (opts.tunnel && host !== "docker") {
-        // A flag/host combination the parser cannot see (host is an argument) — usage class, exit 2.
-        failUsage(`deploy stopped: --tunnel is supported only by the local Docker target`);
-    }
     if (opts.json && !opts.run)
         failUsage("--json reports a deploy --run drives: pass --run too");
     selectAgentEnvironment("production");
-    const { agentDir } = await enterAgentDirectory(dirArg, opts);
-    const config = await loadConfig(agentDir).catch(failStartup);
-    // Never `dev`, whatever spawned this; and what decides a channel's shape is read here as the box will read it.
-    unmarkDevServe();
-    const shaped = divergentSettingsGate(FEISHU_INGRESS_SETTINGS, process.env, loadEnvValues(dotEnvPath(agentDir)), relative(agentDir, dotEnvPath(agentDir)));
-    if (shaped)
-        failStartup(new Error(`deploy stopped: ${shaped}`));
-    const independentApps = (values) => {
-        try {
-            assertIndependentFeishuApps(agentDir, ["feishu", "lark"], values);
-        }
-        catch (error) {
-            failStartup(error);
-        }
-    };
-    independentApps(loadEnvValues(dotEnvPath(agentDir)));
-    const api = deploymentApi({
-        config,
-        hostServes: host !== "agentcore",
-        values: loadEnvValues(dotEnvPath(agentDir)),
+    // The configuration the box runs on: the program's defaults, with the instance configuration `--config` delivers,
+    // and never the project's own `fastagent.json`, the development instance's.
+    const delivered = opts.config === undefined
+        ? undefined
+        : await readInstanceConfigFile(resolve(opts.config))
+            .then((source) => ({ source, text: `${JSON.stringify(source.values, null, 2)}\n` }))
+            .catch(failStartup);
+    const deployed = async (dir) => ({
+        definition: await loadSourceDefinition(dir),
+        ...(delivered === undefined ? {} : { instance: delivered.source }),
     });
+    const { agentDir } = await enterAgentDirectory(dirArg, opts, undefined, deployed).catch(failStartup);
+    const config = await deployed(agentDir)
+        .then(({ definition }) => resolveConfig(definition, delivered?.source))
+        .catch(failStartup);
+    // Never `dev`, whatever spawned this: a channel's way of receiving is chosen as the box will choose it.
+    unmarkDevServe();
+    const api = deploymentApi({ config, hostServes: host !== "agentcore" });
     const target = HOSTS[host];
     const preflight = async () => {
         const facts = await preflightDeploy({
             agentDir,
             config,
+            ...(delivered === undefined ? {} : { delivered }),
             run: !!opts.run,
             force: !!opts.force,
             noResidentProcess: host === "agentcore", // alarms and webhooks wake the container there — no machine to keep up
@@ -135,17 +129,10 @@ async function deploy(host, dirArg, opts, step) {
     let pre = await preflight();
     const agentArg = displayPath(process.cwd(), agentDir);
     const rerun = `fastagent deploy ${host}${agentArg === undefined ? "" : ` ${shellArg(agentArg)}`}` +
-        `${opts.tunnel ? " --tunnel" : ""}${opts.intoLinked ? " --into-linked" : ""} --run`;
-    const unprepared = opts.run ? unpreparedFeishuApps(pre.channels, pre.values) : [];
+        `${opts.intoLinked ? " --into-linked" : ""} --run`;
+    const unprepared = opts.run ? unpreparedChannelApps(pre.channels, pre.values) : [];
     if (opts.json && step === undefined) {
         // A coding agent's deploy: what this machine can refuse is refused above, at once; the rest runs in a ticket.
-        if (unprepared.some(({ kind }) => kind === "lark")) {
-            const needed = await larkCredentialsNeeded(agentDir, rerun).catch(failStartup);
-            if (needed !== undefined) {
-                printReport(true, needed.json, needed.text);
-                process.exit(0);
-            }
-        }
         const timeout = opts.timeout === undefined ? TICKET_TIMEOUT_SECONDS : Number(opts.timeout);
         if (!Number.isInteger(timeout) || timeout <= 0)
             failUsage("--timeout must be a whole number of seconds");
@@ -167,8 +154,8 @@ async function deploy(host, dirArg, opts, step) {
                     "deploy",
                     host,
                     agentDir,
-                    ...(opts.tunnel ? ["--tunnel"] : []),
                     ...(opts.force ? ["--force"] : []),
+                    ...(delivered === undefined ? [] : ["--config", delivered.source.label]),
                     ...(opts.intoLinked ? ["--into-linked"] : []),
                     "--run",
                     "--json",
@@ -182,50 +169,38 @@ async function deploy(host, dirArg, opts, step) {
     /** Everything past the pre-flight, its person's steps taken by `answerer`; the URL and what the API report says. */
     const deployWith = async (answerer) => {
         if (unprepared.length > 0) {
-            const supplied = unprepared.flatMap(({ kind, ingress }) => feishuAppSecretNames(kind, ingress));
+            const supplied = unprepared.flatMap(channelAppNames);
             const kinds = unprepared.map(({ kind }) => kind);
             const { values } = pre;
             const absent = supplied.filter((name) => !values.get(name)?.trim());
-            const { missingSecrets } = assembleSecrets({
-                modelAuth: pre.modelAuth,
-                declared: pre.declaredSecrets,
-                values: pre.values,
-            });
-            const missing = missingValuesGate(missingSecrets.filter((name) => !supplied.includes(name)), pre.valueFile);
-            if (missing)
-                failStartup(new Error(`deploy stopped: ${missing}`));
-            if (host === "docker" && !opts.tunnel && unprepared.some(({ ingress }) => ingress === "webhook")) {
+            if (host === "docker" && unprepared.some(({ way }) => way === "webhook")) {
                 failStartup(new Error(`deploy stopped: ${kinds.join(", ")} receive by webhook here, and this Docker deployment has no ` +
-                    `public URL to point the app at — re-run with --tunnel (the app is prepared then), or set up your own ` +
-                    `ingress and supply ${absent.join(", ")} from a separate production app in ${pre.valueFile}, or ` +
-                    `set ${kinds.map((kind) => `${cloudFor(kind).envPrefix}_INGRESS=websocket`).join(", ")} there`));
+                    `public URL to point the app at — set up your own ingress and supply ${absent.join(", ")} from a separate production app in ${pre.valueFile}, or ` +
+                    `set ${kinds.map((kind) => `channels.${kind}.ingress`).join(", ")} to "connection" in the configuration ` +
+                    `--config delivers`));
             }
             if (answerer.kind === "nobody") {
                 failUsage(`deploy stopped: ${pre.valueFile} has no ${absent.join(", ")}: setting up the separate production app ` +
                     `needs a person — run this deploy in a terminal; from a coding agent, run \`${rerun} --json\`, which ` +
                     `hands their part to its user`);
             }
-            const person = answerer.kind === "ticket" ? answerer.step.person : terminalPerson;
             const again = answerer.kind === "ticket" ? `${rerun} --json` : rerun;
-            await prepareFeishuApps(agentDir, unprepared, again, person).catch(failStartup);
-            pre = await preflight();
-        }
-        independentApps(pre.values);
-        if (api.served && api.generatesKey) {
-            // Past every refusal the pre-flight makes, and read again, so this deploy carries it.
-            const unprotected = await writeApiKey(agentDir).catch(failStartup);
-            if (unprotected !== undefined)
-                console.error(`[fastagent] note: ${unprotectedSecretsNote(unprotected)}`);
+            await prepareChannelApps(agentDir, unprepared, again, answerer.kind === "ticket" ? answerer.step.person : undefined).catch(failStartup);
             pre = await preflight();
         }
         for (const m of pre.messages)
             console.error(`[fastagent] ${m.level}: ${m.text}`);
+        // The box starts the build, never the source: dist/ is made here, from what the image will hold.
+        const built = await buildProject(agentDir).catch(failStartup);
+        for (const warning of built.warnings)
+            console.error(`[fastagent] warn: ${warning}`);
         const { channels } = pre;
         warnHostOnlyFlags(host, opts);
         // What follows is the host's work: a deadline meant for the person must never cut it halfway. Its own steps for
         // the person (a host sign-in, the box's login) wait again, and are bounded again.
         if (answerer.kind === "ticket")
             answerer.step.person.carriesOn();
+        let textDelivered = false;
         const reachedAt = await target.deploy({
             opts,
             answerer,
@@ -233,6 +208,7 @@ async function deploy(host, dirArg, opts, step) {
             agentDir,
             config,
             pre,
+            api,
             channels,
             webhookChannels: channels.filter((channel) => channel.ingress === "webhook"),
             // The ownership predicate is bound HERE, from the same lookup that chose the host, so no host module can pass
@@ -249,10 +225,20 @@ async function deploy(host, dirArg, opts, step) {
                         `would deploy from them. Re-run with --force to regenerate, or remove each file's generated-by ` +
                         `marker to own it yourself.`));
                 }
+                // Once, after the gate and before the first artifact lands: the directory is replaced whole, so a refused
+                // run must leave it as it was, and the build outputs the host writes next go into the fresh one.
+                if (!textDelivered) {
+                    textDelivered = true;
+                    const copied = await deliverText(agentDir, delivered?.source).catch(failStartup);
+                    if (copied > 0) {
+                        console.error(`[fastagent] delivered ${copied} path(s) of the instance's text into ${DELIVERED_CONFIG_DIR}/`);
+                    }
+                }
                 await applyArtifactPlan(plan);
             },
         });
-        const notes = apiReport(api, { valueFile: pre.valueFile, agentArg }, reachedAt);
+        const keyInFile = apiKeysFrom(loadEnvValues(dotEnvPath(agentDir)).get(API_KEY_VARIABLE)).length > 0;
+        const notes = apiReport(api, { valueFile: pre.valueFile, agentArg, keyInFile, run: !!opts.run }, reachedAt);
         for (const line of notes)
             console.error(`[fastagent] ${line}`);
         return { ...(reachedAt === undefined ? {} : { url: reachedAt }), notes };

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

@@ -1,3 +1,4 @@
+import { type InstanceFlags } from "../instance.ts";
 export interface DevOptions {
     port?: string;
     bind?: string;
@@ -7,5 +8,6 @@ export interface DevOptions {
     tunnel?: boolean;
     /** false ⇔ `--no-input`. */
     input?: boolean;
+    instance?: InstanceFlags;
 }
 export declare function runDev(dirArg: string, opts: DevOptions): Promise<void>;

package/dist/cli/commands/dev.js

@@ -6,10 +6,13 @@ import { listenForRestart, runDevSupervisor } from "../../dev-supervisor.js";
 import { setLogLevel } from "../../log.js";
 import { markDevServe } from "../../serving-command.js";
 import { selectAgentEnvironment } from "../../paths.js";
+import { loadDevProject } from "../../harnesses/pi-durable/open.js";
 import { openServing } from "../../harnesses/pi-durable/serve.js";
 import { DEFAULT_HTTP_PORT, serveAgent } from "../../service.js";
 import { failStartup } from "../fail.js";
 import { assertTunnelBindable, cliMountOptions, serveService } from "../serve.js";
+import { setUpMissingChannels } from "../first-run-channels.js";
+import { instanceInputs } from "../instance.js";
 import { enterAgentCommand, parseBind, parsePort, reportAssembly } from "../shared.js";
 /**
  * `dev` binds loopback unless `--bind` says otherwise: a dev serve carries the agent's full tool authority and lands on
@@ -26,6 +29,9 @@ export async function runDev(dirArg, opts) {
         process.on("message", listenForRestart(() => process.kill(process.pid, "SIGTERM")));
     // The model is picked ONCE, in the parent process (a TTY; watch and --no-watch both).
     const { agentDir, modelSpec } = await enterAgentCommand(dirArg, { ...opts, input: isWorker ? false : opts.input });
+    // Once, in the parent: the worker inherits what it writes, and a restart does not ask again.
+    if (!isWorker)
+        await setUpMissingChannels(agentDir, opts);
     if (isWorker || opts.watch === false) {
         await serveOnce(agentDir, modelSpec, opts);
         return;
@@ -41,9 +47,15 @@ async function serveOnce(agentDir, modelSpec, opts) {
     const host = parseBind(opts.bind) ?? DEV_BIND;
     const tunnel = opts.tunnel ?? false;
     assertTunnelBindable(host, tunnel);
-    const opened = await openServing(agentDir, { model: modelSpec }).catch(failStartup);
+    const opened = await loadDevProject(agentDir)
+        .then(({ definition, instance }) => openServing(definition, {
+        model: modelSpec,
+        ...instanceInputs(agentDir),
+        ...(instance === undefined ? {} : { config: instance }),
+    }))
+        .catch(failStartup);
     await reportAssembly(opened, modelSpec);
-    const { config } = opened.definition;
+    const { config } = opened;
     const service = await serveAgent(opened, cliMountOptions(config)).catch(failStartup);
-    serveService(service, { port: portFlag ?? config.http?.port ?? DEFAULT_HTTP_PORT, host }, { tunnel, agentDir, stateRoot: opened.stateRoot, config });
+    serveService(service, { port: portFlag ?? config.http?.port ?? DEFAULT_HTTP_PORT, host }, { tunnel, agentDir, config });
 }

package/dist/cli/commands/env.js

@@ -100,7 +100,7 @@ export async function runEnvList(opts = {}) {
     const missing = missingAptPackages(declared.aptPackages);
     if (missing && missing.length > 0)
         log.warn(`[fastagent] ${aptAdvice(missing)}`);
-    const unset = missingSecrets(variables).map(({ name }) => name);
+    const unset = missingSecrets(variables, process.env).map(({ name }) => name);
     if (unset.length > 0) {
         log.warn(`[fastagent] no value here for ${unset.join(", ")}: dev and start refuse to run until they have one — set ` +
             `them in ${dotEnvPath(agentDir)}`);

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

@@ -1,5 +1,7 @@
+import { type InstanceFlags } from "../instance.ts";
 export interface InfoOptions {
     json?: boolean;
     model?: string;
+    instance?: InstanceFlags;
 }
 export declare function runInfo(dirArg: string, opts: InfoOptions): Promise<void>;

package/dist/cli/commands/info.js

@@ -1,48 +1,67 @@
 /** `fastagent info [agent] [--json]`: print what the directory builds into, WITHOUT opening or serving the agent. */
+import { definedValues } from "../../declared-secrets.js";
 import { resolve } from "node:path";
 import { channelIngress } from "../../channels/discover.js";
 import { loadContent, loadEnvironment } from "../../content/file.js";
-import { contentAbsentHere, resolveContent } from "../../content/resolve.js";
+import { resolveContent } from "../../content/resolve.js";
 import { describeSecrets, missingSecrets } from "../../declared-secrets.js";
-import { enterAgentEnv } from "../../env.js";
+import { enteredInstanceName, instanceName } from "../../instance-name.js";
+import { enterInstance } from "../instance.js";
 import { modelEnvironment } from "../../harnesses/models/environment.js";
-import { buildDefinition, modelSpecFor, prepareDefinition, secretsManifest } from "../../harnesses/pi-durable/open.js";
-import { readCommands } from "../../harnesses/pi-durable/text.js";
-import { resolveStateRoot } from "../../paths.js";
+import { configValue, resolveConfig } from "../../harnesses/pi-durable/config.js";
+import { definitionSecrets } from "../../harnesses/pi-durable/definition.js";
+import { buildDefinition, loadDevProject, modelSpecFor } from "../../harnesses/pi-durable/open.js";
+import { openText, readCommands } from "../../harnesses/pi-durable/text.js";
+import { inspectMcp } from "../../mcp/host.js";
+import { resolveStateRoot, resolveWorkdir } from "../../paths.js";
 import { nextRun } from "../../schedule/cron.js";
 import { contentLines } from "../content-view.js";
 import { agentDirOrExit, failStartup } from "../fail.js";
 export async function runInfo(dirArg, opts) {
     const agentDir = agentDirOrExit(resolve(dirArg));
-    enterAgentEnv(agentDir); // code may read its secrets, and fetch, when it is built
-    const definition = await prepareDefinition(agentDir).catch(failStartup);
-    const { config } = definition;
+    enterInstance(agentDir, opts.instance); // code may read its secrets, and fetch, when it is built
+    const workdir = resolveWorkdir(agentDir);
+    const { definition, instance } = await loadDevProject(agentDir).catch(failStartup);
+    const config = (() => {
+        try {
+            return resolveConfig(definition, instance);
+        }
+        catch (error) {
+            return failStartup(error);
+        }
+    })();
+    const name = instanceName(definition.name, enteredInstanceName() ?? config.name);
     const modelSpec = modelSpecFor(config, opts.model);
-    const manifest = secretsManifest(definition);
-    const declared = manifest.flatMap(({ name, optional, declaredIn }) => declaredIn.map((source) => ({ name, optional, source })));
-    const unsetSecrets = missingSecrets(declared);
+    const declared = (() => {
+        try {
+            return definitionSecrets(definition, config, instance);
+        }
+        catch (error) {
+            return failStartup(error);
+        }
+    })();
+    const unsetSecrets = missingSecrets(declared, process.env);
     // Built only when every required secret has a value: building is what reads them. A module that is not what its
     // directory holds is said as the refusal `dev` and `start` would stop on.
     const code = unsetSecrets.length === 0
         ? await Promise.resolve()
-            .then(() => buildDefinition(definition))
+            .then(() => buildDefinition(definition, process.env, config))
             .catch(failStartup)
         : undefined;
     // Reported, not fatal: `info` is how an author finds out a content entry is missing, or the environment refused.
     let content = [];
-    let contentAbsent = [];
     let contentError;
     try {
-        const declaration = loadContent(agentDir);
-        content = resolveContent(agentDir, declaration);
-        contentAbsent = contentAbsentHere(declaration);
+        content = resolveContent(loadContent(agentDir, instance), { dir: agentDir, workdir });
     }
     catch (error) {
         contentError = error.message;
     }
     // Read already, by the definition's secrets: a refused environment is a definition that does not open.
     const environment = loadEnvironment(agentDir);
-    const models = await modelEnvironment(agentDir, {}, code?.providers ?? []);
+    const models = await modelEnvironment(agentDir, {}, code?.providers ?? [], {
+        environment: definedValues(process.env),
+    });
     const slash = modelSpec?.indexOf("/") ?? -1;
     const modelError = modelSpec === undefined || models.models.getModel(modelSpec.slice(0, slash), modelSpec.slice(slash + 1))
         ? undefined
@@ -57,27 +76,33 @@ export async function runInfo(dirArg, opts) {
         tz: s.tz ?? null,
         next: nextRun(s.cron, s.tz, new Date())?.toISOString() ?? null,
     }));
-    const commands = readCommands(agentDir).map(({ name, description }) => ({ name, description: description ?? null }));
+    const text = await Promise.resolve()
+        .then(() => openText(agentDir, instance))
+        .catch(failStartup);
+    const commands = readCommands(text).map(({ name, description }) => ({ name, description: description ?? null }));
     const stateRoot = resolveStateRoot(agentDir);
     const auth = models.auth;
+    const mcp = await inspectMcp(agentDir, instance === undefined ? {} : { config: instance.label }).catch(failStartup);
     if (opts.json) {
         console.log(JSON.stringify({
             agentDir,
-            name: definition.name,
+            name: name,
             content,
-            contentAbsent,
             contentError: contentError ?? null,
             environment: environment ?? null,
             model: modelSpec ?? null,
             modelError: modelError ?? null,
             thinkingLevel: config.thinkingLevel ?? null,
+            config: configReport(config, opts.model),
             tools: code?.tools.map(({ name }) => name) ?? null,
+            mcp,
             extensions: code?.extensions.map(({ name }) => name) ?? null,
             channels: code === undefined ? null : channels,
             schedules: code === undefined ? null : schedules,
             commands,
-            secrets: manifest,
+            secrets: definition.inputs.secrets,
             unsetSecrets: unsetSecrets.map(({ name }) => name),
+            workdir,
             stateRoot,
             authPath: auth?.path ?? null,
             fallbackAuthPath: auth?.fallback ?? null,
@@ -87,13 +112,13 @@ export async function runInfo(dirArg, opts) {
     const line = (label, value) => console.log(`${`${label}:`.padEnd(13)} ${value}`);
     /** A continuation under the previous line, aligned to the same column (no label, so no bare colon). */
     const cont = (value) => console.log(`${"".padEnd(13)} ${value}`);
-    line("agent", `${definition.name} — ${agentDir}`);
-    for (const [label, value] of contentLines(content, contentAbsent))
+    line("agent", `${name} — ${agentDir}`);
+    for (const [label, value] of contentLines(content))
         line(label, value);
     if (contentError)
         cont(`⚠ ${contentError}`);
     line("environment", environment ? describeEnvironment(environment) : "(none: the machine's commands)");
-    line("model", modelSpec ?? "(not set — pass --model, set FASTAGENT_MODEL, or model in fastagent.config.ts)");
+    line("model", modelSpec ?? "(not set — pass --model, set FASTAGENT_MODEL, or defaults.model in fastagent.config.ts)");
     if (modelError)
         cont(`⚠ does not resolve: ${modelError}`);
     if (config.thinkingLevel)
@@ -102,6 +127,7 @@ export async function runInfo(dirArg, opts) {
     line("tools", code ? code.tools.map(({ name }) => name).join(", ") || "(none)" : unbuilt);
     if (code && code.extensions.length > 0)
         line("extensions", code.extensions.map(({ name }) => name).join(", "));
+    line("mcp", mcp.map((server) => `${server.name} (${server.transport}, ${server.authorization})`).join(", ") || "(none)");
     line("channels", code ? channels.map((c) => `${c.name} (${c.ingress})`).join(", ") || "(none)" : unbuilt);
     line("schedules", code ? schedules.map((s) => `${s.name} (next ${s.next ?? "never"})`).join(", ") || "(none)" : unbuilt);
     line("commands", commands.map(({ name }) => `/${name}`).join(", ") || "(none)");
@@ -109,10 +135,23 @@ export async function runInfo(dirArg, opts) {
     if (unsetSecrets.length > 0) {
         cont(`⚠ dev, start and deployments refuse to boot until set: ${unsetSecrets.map((s) => s.name).join(", ")}`);
     }
+    line("workdir", workdir);
     line("state", stateRoot);
     if (auth)
         line("auth", auth.fallback === undefined ? auth.path : `${auth.path} (then ${auth.fallback})`);
 }
+/**
+ * Each value the configuration resolved, by its path, with where it is from: the program's defaults, the instance's
+ * file, and for the model the flag or variable that overrides both.
+ */
+function configReport(config, modelFlag) {
+    const report = Object.fromEntries(Object.entries(config.sources).map(([path, source]) => [path, { value: configValue(config, path), source }]));
+    const override = modelFlag !== undefined ? "--model" : process.env.FASTAGENT_MODEL ? "FASTAGENT_MODEL" : undefined;
+    const model = modelSpecFor(config, modelFlag);
+    if (override !== undefined && model !== undefined)
+        report.model = { value: model, source: override };
+    return report;
+}
 /** The packages and apt packages an environment declares, as one line. */
 function describeEnvironment(environment) {
     const packages = Object.entries(environment.packages).map(([name, version]) => `${name} ${version}`);

package/dist/cli/commands/init.js

@@ -15,7 +15,9 @@ export async function runInit(dirArg, opts) {
         .catch(failStartup);
     let installFailed = false;
     const { created, content, repository } = await initAgent(dir, {
-        content: read.map((source) => source.addition),
+        // A new agent's repositories are its program's: every instance of it reaches them, and a deploy carries them. A
+        // directory is this machine's, and goes to the instance configuration.
+        content: read.map(({ addition }) => ("github" in addition.entry ? { ...addition, program: true } : addition)),
         ...(opts.install
             ? {
                 install: async (agentDir) => {

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

@@ -1,3 +1,4 @@
+import { type InstanceFlags } from "../instance.ts";
 export interface InvokeOptions {
     model?: string;
     /** false ⇔ `--no-input`. */
@@ -8,5 +9,6 @@ export interface InvokeOptions {
     url?: string;
     /** The key `url` is called with; else the first in the agent's production values. */
     key?: string;
+    instance?: InstanceFlags;
 }
 export declare function runInvoke(message: string, dirArg: string, opts: InvokeOptions): Promise<void>;

package/dist/cli/commands/invoke.js

@@ -14,6 +14,7 @@ import { API_KEY_VARIABLE, apiKeysFrom } from "../../http/server.js";
 import { resolveStateRoot, selectAgentEnvironment } from "../../paths.js";
 import { runInvokeJson, runInvokeStream } from "../invoke-stream.js";
 import { failStartup, failUsage, optionalAgentDirOrExit } from "../fail.js";
+import { enterEnvFile, instanceInputs } from "../instance.js";
 /**
  * `invoke`'s sessions, apart from the instance's storage, so `invoke` runs beside a serve of this directory, which holds
  * that one; one `invoke` at a time holds this one.
@@ -37,11 +38,15 @@ async function sessionFor(agent, sessionId, settings, file) {
 /** A refusal as the line an operator reads: its code, then what it says. */
 const refusal = (error) => error instanceof AgentError ? new Error(`${error.code}: ${error.message}`) : error;
 /** Print the message's answer as it is written, then exit with what it ended as: 0 only for `completed`. */
-async function answer(events, json) {
+/** What to do about a model with no credential, where the answer came from. */
+const LOCAL_AUTH_HINT = "sign in with `fastagent login`, or set the provider's API key in .secrets/.env";
+const DEPLOYED_AUTH_HINT = "give the deployment a credential: `fastagent secrets set <host> <the provider's API key variable>` " +
+    "(`fastagent secrets list <host>` names it), or sign its box in with `fastagent login <provider> --deployment <host>`";
+async function answer(events, json, authHint) {
     // Both renderers exit 1 unless the message completed: CI gates on it.
     const exitCode = json
         ? await runInvokeJson(events, (line) => process.stdout.write(`${line}\n`))
-        : await runInvokeStream(events, (text) => process.stdout.write(text), (line) => console.error(line));
+        : await runInvokeStream(events, (text) => process.stdout.write(text), (line) => console.error(line), authHint);
     if (!json)
         process.stdout.write("\n");
     return exitCode;
@@ -79,6 +84,10 @@ function enterForUrl(dirArg, key, url) {
 /** `--url`: the message sent to a served agent over its Agent API, in a session there; nothing opens here. */
 async function runRemoteInvoke(message, dirArg, opts) {
     const { url } = opts;
+    const { envFile, ...placed } = opts.instance ?? {};
+    for (const flag of Object.keys(placed))
+        failUsage(`--${flag} places an instance this run opens, and --url opens none`);
+    enterEnvFile(envFile);
     let settings;
     try {
         settings = opts.model === undefined ? undefined : { model: modelRefOf(opts.model, "--model") };
@@ -90,7 +99,7 @@ async function runRemoteInvoke(message, dirArg, opts) {
     console.error(`[fastagent] invoke: ${url}`);
     const sessionId = await remoteSession(agent, opts.session, settings, url).catch((error) => failStartup(refusal(error)));
     console.error(`[fastagent] session ${sessionId} (continue it with --session ${sessionId})`);
-    process.exit(await answer(agent.messages.stream({ sessionId, content: message }), opts.json));
+    process.exit(await answer(agent.messages.stream({ sessionId, content: message }), opts.json, DEPLOYED_AUTH_HINT));
 }
 /** The served agent's session to send into: a new one, or `sessionId`, set to `--model` when one is given. */
 async function remoteSession(agent, sessionId, settings, url) {
@@ -110,28 +119,32 @@ export async function runInvoke(message, dirArg, opts) {
         return runRemoteInvoke(message, dirArg, { ...opts, url: opts.url });
     if (opts.key !== undefined)
         failUsage("--key is the key --url calls with: pass --url too");
-    const [{ openServing }, { enterAgentCommand, reportAuth }] = await Promise.all([
+    const [{ openServing }, { loadDevProject }, { enterAgentCommand, reportAuth }] = await Promise.all([
         import("../../harnesses/pi-durable/serve.js"),
+        import("../../harnesses/pi-durable/open.js"),
         import("../shared.js"),
     ]);
     const { agentDir, modelSpec } = await enterAgentCommand(dirArg, opts);
     const file = invokeStorageFile(resolveStateRoot(agentDir));
-    const { agent, models, definition } = await openServing(agentDir, {
+    const project = await loadDevProject(agentDir).catch(failStartup);
+    const { agent, models, config } = await openServing(project.definition, {
         model: modelSpec,
+        ...instanceInputs(agentDir),
+        ...(project.instance === undefined ? {} : { config: project.instance }),
         storage: { file, holders: "another `fastagent invoke` of this agent" },
         // Its messages do not outlive it: one a stopped invoke left is not run again by the next.
         unfinished: "abort",
     }).catch(failStartup);
     console.error(`[fastagent] invoke: ${agentDir} (${modelSpec})`);
     await reportAuth(models, modelSpec, agentDir);
-    const { thinkingLevel } = definition.config;
+    const { thinkingLevel } = config;
     const settings = {
         model: modelRefOf(modelSpec, "the model"),
         ...(thinkingLevel === undefined ? {} : { thinkingLevel }),
     };
     const sessionId = await sessionFor(agent, opts.session, settings, file).catch(failStartup);
     console.error(`[fastagent] session ${sessionId} (continue it with --session ${sessionId})`);
-    const exitCode = await answer(agent.messages.stream({ sessionId, content: message }), opts.json);
+    const exitCode = await answer(agent.messages.stream({ sessionId, content: message }), opts.json, LOCAL_AUTH_HINT);
     await agent.close();
     // Always exit explicitly: the undici proxy agent's keep-alive sockets would otherwise hold the event loop open
     // after a successful one-shot message.

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

@@ -1,10 +1,3 @@
-/**
- * `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 type { AuthInteraction } from "@earendil-works/pi-ai";
 import { type TicketStep } from "../ticket.ts";
 export interface LoginOptions {