@fastagent-sh/fastagent 0.24.3 → 0.25.0

package/dist/cli/serve.d.ts

@@ -1,81 +1,31 @@
-import type { Agent } from "../agent.ts";
-import type { ChannelHandler } from "../channel.ts";
-import { type AgentService, type MountableAgent, type MountAgentServiceOptions } from "../service.ts";
+import type { ServedAgent, ServeOptions, Service } from "../service.ts";
+import type { AgentConfig } from "../harnesses/pi-durable/define.ts";
 /** Refuse `--tunnel` with a `--bind` that cloudflared cannot reach. */
 export declare function assertTunnelBindable(host: string | undefined, tunnel: boolean): void;
 /**
- * Apply the flags that override what the definition said, for THIS run only.
- *
- * ONE place, because `dev` and `start` both do it and a mapping two call sites must each remember is one a third
- * will not.
- *
- * `--no-invoke` outranks `http.invoke`: a config value travels into a deployed image, so "do not publish a turn
- * endpoint on this tunnel" has to be sayable without editing the definition.
- *
- * It takes `POST /run` WITH it, including over a definition that said `http.run: true`. Both routes start a
- * turn for an anonymous caller, and the flag's whole reason for existing is the case where the definition cannot be
- * edited — `dev --tunnel --no-invoke` leaving the other one published at the tunnel URL would be the flag failing at
- * exactly the job it was added for.
+ * What the CLI adds to the assembly: its shutdown grace, exit on a connection that drops, and the API's keys, none
+ * when the definition turns the API off, whatever key the environment holds (a host's from an earlier deploy).
  */
-export declare function withRunOverrides<T extends MountableAgent>(opened: T, run: {
-    invoke?: boolean;
-}): T;
-/** What the CLI adds to the assembly: its shutdown grace, and exit on a connection that drops. */
-export declare function cliMountOptions(wrapAgent: (agent: Agent) => Agent): MountAgentServiceOptions;
+export declare function cliMountOptions(config: AgentConfig): ServeOptions;
 /**
- * Bind, report, announce the control plane, open the tunnel, and close in order on a signal — the tail dev's worker
- * and start share once the service is assembled.
+ * Bind, report, warn about reach, open the tunnel, and close in order on a signal — the tail dev's worker and start
+ * share once the service is assembled.
  */
-export declare function serveService(service: AgentService, bind: {
+export declare function serveService(service: ServedAgent, bind: {
     port: number;
     host?: string;
 }, posture: {
     tunnel: boolean;
     agentDir: string;
     stateRoot: string;
+    config: AgentConfig;
 }): void;
 /** The "we are serving" report: the supervisor message `dev`'s watcher waits for, the addresses, and what mounted. */
-export declare function reportServing(service: AgentService, host: string | undefined, boundPort: number): void;
+export declare function reportServing(service: ServedAgent, host: string | undefined, boundPort: number, config: AgentConfig): void;
 /** The line that names WHERE the serve is — every posture reports it, including AgentCore's own surface. */
 export declare function bindLine(host: string | undefined, boundPort: number): string;
-/**
- * The startup lines for a serve of OUR surface: the bind report, and the curl the reader copies.
- *
- * `servesInvoke` is `AgentService.unverifiedRoutes`, never a guess from the route table: `http.invoke: false` leaves no
- * `/invoke` to curl, and a channel may serve that path with a protocol of its own — both would turn this line into
- * a copyable request that fails.
- */
-export declare function readyAddressLines(host: string | undefined, boundPort: number, servesInvoke: boolean): string[];
-/**
- * Say what this port exposes and how far it reaches.
- *
- * NOTHING fastagent serves is authenticated — authentication belongs to the deployment (a gateway, a private
- * network, AgentCore's IAM, an embedder's middleware). Two of the three warnings fire at a REACH the operator did
- * not get by default: a bind off this machine, and `--tunnel`'s public URL.
- *
- * The cross-origin one is UNCONDITIONAL, including on a loopback `dev`, because the grant is. `*` is the default
- * (`channels/serve.ts`), so a page the developer merely visits can drive this port from their browser and read the
- * reply, loopback bind or not. Nobody opts into a default, so the one posture the decision costs is the one that
- * has to hear about it.
- *
- * WHAT IS EXPOSED is read off `AgentService.unverifiedRoutes`, never assumed and never guessed from the route table.
- * `POST /invoke` is on most serves but not all: AgentCore answers the Runtime's `/invocations` behind IAM,
- * `http.invoke: false` withholds it, and a channel may serve that path itself — in which case the caller it is
- * open to is the platform that signs its requests, not anyone at all. A warning naming an endpoint this process
- * does not serve is how an operator learns to skim past all of them — the same reason `preflightDeploy` takes
- * `publicUrl`.
- */
-export declare function announceControl(service: Pick<AgentService, "controlPrefix" | "unverifiedRoutes" | "corsOrigins">, bind: {
-    host?: string;
-    tunnel: boolean;
-}): void;
-/** Bind HTTP and report ready — but only once the SERVICE is, which is not the same moment. */
-export declare function serve(handler: ChannelHandler, bind: {
+/** Listen, and report ready — but only once the SERVICE is, which is not the same moment — until a signal closes it. */
+export declare function serve(service: Service, bind: {
     port: number;
     host?: string;
-}, hooks?: {
-    /** Awaited before anything is reported ready — see the listening handler. */
-    ready?: Promise<void>;
-    onListening?: (boundPort: number) => void;
-    onShutdown?: () => Promise<void> | void;
-}): void;
+}, onListening?: (boundPort: number) => void): void;

package/dist/cli/serve.js

@@ -1,8 +1,7 @@
 /** What `dev` (its worker) and `start` need beyond the service itself. */
-import { INVOKE_EXAMPLE_BODY } from "../channels/http.js";
-import { answersLocalhost, bindLabel, classifyBind, clientHost } from "../bind.js";
-import { describeAnonymousSurface, } from "../service.js";
-import { serveNode } from "../channels/serve.js";
+import { answersLocalhost, bindLabel, classifyBind } from "../bind.js";
+import { API_PREFIX } from "../http/contract.js";
+import { API_KEY_VARIABLE, API_TURNED_OFF, apiKeysFrom, apiTurnedOff } from "../http/server.js";
 import { log } from "../log.js";
 import { openExternalUrl } from "../open-url.js";
 import { declaredChannels } from "../channels/discover.js";
@@ -15,54 +14,36 @@ export function assertTunnelBindable(host, tunnel) {
     failUsage(`--tunnel reaches the serve by dialing localhost, which the bind address ${host} does not answer — bind 0.0.0.0 (or 127.0.0.1), or drop --tunnel`);
 }
 /**
- * Apply the flags that override what the definition said, for THIS run only.
- *
- * ONE place, because `dev` and `start` both do it and a mapping two call sites must each remember is one a third
- * will not.
- *
- * `--no-invoke` outranks `http.invoke`: a config value travels into a deployed image, so "do not publish a turn
- * endpoint on this tunnel" has to be sayable without editing the definition.
- *
- * It takes `POST /run` WITH it, including over a definition that said `http.run: true`. Both routes start a
- * turn for an anonymous caller, and the flag's whole reason for existing is the case where the definition cannot be
- * edited — `dev --tunnel --no-invoke` leaving the other one published at the tunnel URL would be the flag failing at
- * exactly the job it was added for.
+ * What the CLI adds to the assembly: its shutdown grace, exit on a connection that drops, and the API's keys, none
+ * when the definition turns the API off, whatever key the environment holds (a host's from an earlier deploy).
  */
-export function withRunOverrides(opened, run) {
-    return run.invoke === false ? { ...opened, http: { ...opened.http, invoke: false, run: false } } : opened;
-}
-/** What the CLI adds to the assembly: its shutdown grace, and exit on a connection that drops. */
-export function cliMountOptions(wrapAgent) {
+export function cliMountOptions(config) {
     return {
-        wrapAgent,
+        apiKeys: apiTurnedOff(config) ? [] : apiKeysFrom(process.env[API_KEY_VARIABLE]),
         closeTimeoutMs: SHUTDOWN_GRACE_MS,
         onChannelClosed: (name, error) => failStartup(new Error(`${name} ${error === undefined ? "closed unexpectedly" : `failed: ${String(error)}`}`)),
     };
 }
 /**
- * Bind, report, announce the control plane, open the tunnel, and close in order on a signal — the tail dev's worker
- * and start share once the service is assembled.
+ * Bind, report, warn about reach, open the tunnel, and close in order on a signal — the tail dev's worker and start
+ * share once the service is assembled.
  */
 export function serveService(service, bind, posture) {
     const { host } = bind;
-    const { tunnel, agentDir, stateRoot } = posture;
-    serve(service.handler, bind, {
-        ready: service.ready,
-        onListening: (p) => {
-            reportServing(service, host, p);
-            announceControl(service, { host, tunnel });
-            maybeTunnel(agentDir, service.channels.routes, p, tunnel, stateRoot);
-        },
-        onShutdown: () => service.close(),
+    const { tunnel, agentDir, stateRoot, config } = posture;
+    serve(service, bind, (p) => {
+        reportServing(service, host, p, config);
+        maybeTunnel(agentDir, service.channels.routes, p, tunnel, stateRoot);
     });
 }
 /** The "we are serving" report: the supervisor message `dev`'s watcher waits for, the addresses, and what mounted. */
-export function reportServing(service, host, boundPort) {
+export function reportServing(service, host, boundPort, config) {
     process.send?.({ type: "ready", port: boundPort, routeChannels: service.channels.routes });
-    for (const line of readyAddressLines(host, boundPort, service.unverifiedRoutes.includes("POST /invoke"))) {
-        log.info(line);
-    }
+    log.info(bindLine(host, boundPort));
     log.info(`[fastagent] routes: ${Object.keys(service.routes).join(", ") || "(none)"}`);
+    log.info(service.api
+        ? `[fastagent] Agent API: ${API_PREFIX} (keys from ${API_KEY_VARIABLE})`
+        : `[fastagent] Agent API: not served — ${apiTurnedOff(config) ? API_TURNED_OFF : `set ${API_KEY_VARIABLE} to serve it under ${API_PREFIX}`}`);
     if (service.channels.longConnections.length > 0) {
         log.info(`[fastagent] long connections: ${service.channels.longConnections.join(", ")}`);
     }
@@ -72,79 +53,14 @@ export function bindLine(host, boundPort) {
     return `[fastagent] http host on ${classifyBind(host) === "wildcard" ? `:${boundPort} (all interfaces)` : bindLabel(host, boundPort)}`;
 }
 /**
- * The startup lines for a serve of OUR surface: the bind report, and the curl the reader copies.
- *
- * `servesInvoke` is `AgentService.unverifiedRoutes`, never a guess from the route table: `http.invoke: false` leaves no
- * `/invoke` to curl, and a channel may serve that path with a protocol of its own — both would turn this line into
- * a copyable request that fails.
- */
-export function readyAddressLines(host, boundPort, servesInvoke) {
-    const dial = `${clientHost(host)}:${boundPort}`;
-    return [
-        bindLine(host, boundPort),
-        ...(servesInvoke
-            ? [
-                `[fastagent] try it: curl -s ${dial}/invoke -X POST -H 'content-type: application/json' -d '${INVOKE_EXAMPLE_BODY}'`,
-            ]
-            : []),
-    ];
-}
-/**
- * Say what this port exposes and how far it reaches.
- *
- * NOTHING fastagent serves is authenticated — authentication belongs to the deployment (a gateway, a private
- * network, AgentCore's IAM, an embedder's middleware). Two of the three warnings fire at a REACH the operator did
- * not get by default: a bind off this machine, and `--tunnel`'s public URL.
- *
- * The cross-origin one is UNCONDITIONAL, including on a loopback `dev`, because the grant is. `*` is the default
- * (`channels/serve.ts`), so a page the developer merely visits can drive this port from their browser and read the
- * reply, loopback bind or not. Nobody opts into a default, so the one posture the decision costs is the one that
- * has to hear about it.
- *
- * WHAT IS EXPOSED is read off `AgentService.unverifiedRoutes`, never assumed and never guessed from the route table.
- * `POST /invoke` is on most serves but not all: AgentCore answers the Runtime's `/invocations` behind IAM,
- * `http.invoke: false` withholds it, and a channel may serve that path itself — in which case the caller it is
- * open to is the platform that signs its requests, not anyone at all. A warning naming an endpoint this process
- * does not serve is how an operator learns to skim past all of them — the same reason `preflightDeploy` takes
- * `publicUrl`.
+ * What the CLI gives a long connection to stop in, and the hard exit that follows the whole close: the server's own
+ * grace for requests in flight (500 ms, channels/serve.ts), then the channels'.
  */
-export function announceControl(service, bind) {
-    const { controlPrefix, corsOrigins } = service;
-    if (controlPrefix)
-        log.info(`[fastagent] session control on ${controlPrefix}/*`);
-    // What an unauthenticated caller of this port can do, worst first. From `unverifiedRoutes`, so a channel that serves
-    // `/invoke` itself is not described as our unauthenticated data plane — it has its own signature check.
-    const exposed = describeAnonymousSurface({
-        invoke: service.unverifiedRoutes.includes("POST /invoke"),
-        run: service.unverifiedRoutes.includes("POST /run"),
-        ...(controlPrefix ? { controlPrefix } : {}),
-    });
-    if (exposed.length === 0)
-        return; // nothing of ours answers here (the AgentCore adapter's surface)
-    const what = `${exposed.join(" and ")} ${exposed.length > 1 ? "answer" : "answers"}`;
-    if (corsOrigins === undefined || corsOrigins.includes("*")) {
-        log.warn(`[fastagent] any web page your browser visits can call this serve cross-origin and read the reply: ${what} ` +
-            "with no credential. That is the default (`*`); pin the origins you actually use with http.cors " +
-            "(docs/design/session-control.md §14)");
-    }
-    const reach = classifyBind(bind.host);
-    if (reach !== "loopback") {
-        log.warn(`[fastagent] the port binds ${reach === "wildcard" ? "all interfaces" : `${bind.host} (off this machine)`}: ` +
-            `${what} UNAUTHENTICATED to anyone who can reach it — bind loopback (--bind 127.0.0.1), ` +
-            "firewall the port, or front it with a gateway (docs/design/session-control.md §14)");
-    }
-    if (bind.tunnel) {
-        log.warn(`[fastagent] --tunnel publishes this port at a public URL with NO authentication: ${what} to anyone with ` +
-            "that URL — put real auth in front before sharing it (docs/design/session-control.md §14)");
-    }
-}
-/** What the CLI gives a service to stop in, and the hard exit that follows it. */
 const SHUTDOWN_GRACE_MS = 800;
 const FORCED_EXIT_MS = 1_500;
-/** Bind HTTP and report ready — but only once the SERVICE is, which is not the same moment. */
-export function serve(handler, bind, hooks = {}) {
+/** Listen, and report ready — but only once the SERVICE is, which is not the same moment — until a signal closes it. */
+export function serve(service, bind, onListening) {
     const { port, host } = bind;
-    const hosted = serveNode(handler, { port, host });
     let stopping = false;
     const stop = (exitCode) => {
         if (stopping)
@@ -155,33 +71,27 @@ export function serve(handler, bind, hooks = {}) {
             log.error(`[fastagent] shutdown did not finish within ${FORCED_EXIT_MS}ms; exiting`);
             process.exit(1);
         }, FORCED_EXIT_MS);
-        // Stop accepting FIRST, before anything is awaited.
-        const closingServer = hosted.close();
-        hosted.closeAllConnections();
         // A cleanup that failed is not a clean exit.
-        void Promise.allSettled([closingServer, Promise.resolve(hooks.onShutdown?.())]).then((outcomes) => {
-            let code = exitCode;
-            for (const outcome of outcomes) {
-                if (outcome.status === "rejected") {
-                    log.error(`[fastagent] shutdown failed: ${String(outcome.reason)}`);
-                    code = 1;
-                }
-            }
+        void service.close().then(() => {
+            clearTimeout(deadline);
+            process.exit(exitCode);
+        }, (error) => {
+            log.error(`[fastagent] shutdown failed: ${String(error)}`);
             clearTimeout(deadline);
-            process.exit(code);
+            process.exit(1);
         });
     };
     process.once("SIGINT", () => stop(0));
     process.once("SIGTERM", () => stop(0));
-    hosted.listening.then(async (boundPort) => {
+    service.listen(port, host).then(async (boundPort) => {
         try {
             // A bound socket is NOT a serving agent: a declared socket-mode channel still has to come up, and reporting
             // ready before it does tells the supervisor (and --tunnel, and the operator) that a surface is live while a
             // channel is dead.
-            await hooks.ready;
+            await service.ready;
             if (stopping)
                 return;
-            hooks.onListening?.(boundPort);
+            onListening?.(boundPort);
         }
         catch (error) {
             failStartup(error);

package/dist/cli/shared.d.ts

@@ -1,61 +1,32 @@
-import { type LoginIO } from "../engines/pi/login.ts";
-import { type AgentModels } from "../engines/pi/agent-models.ts";
-import { type IndirectTool } from "../engines/pi/create.ts";
-import type { LoadedDefinition } from "../engines/pi/definition.ts";
-import type { ToolCollision } from "../engines/pi/tool.ts";
-import { type ResolvedPlacement } from "../paths.ts";
+import { type LoginIO } from "../harnesses/models/login.ts";
+import { type ModelEnvironment } from "../harnesses/models/environment.ts";
+import type { OpenedServing } from "../harnesses/pi-durable/serve.ts";
+/** An agent directory a command entered, and the default model that then resolves, if any. */
+export interface EnteredAgent {
+    agentDir: string;
+    modelSpec?: string;
+}
 /**
- * How a command enters its agent directory, in the one order that works: placement, the agent's environment, then the
- * first-run model picker. Returns the default model that then resolves, if any. `deploy` uses this directly: it gates
- * a missing model itself, by what will ship.
+ * How a command enters its agent directory, in the one order that works: the directory, the agent's environment, then
+ * the first-run model picker. Returns the default model that then resolves, if any. `deploy` uses this directly: it
+ * gates a missing model itself, by what will ship. `before`: what the command checks of the directory before a model
+ * is asked for (`schedules run`: that the schedule it names exists).
  */
 export declare function enterAgentDirectory(dirArg: string, opts: {
     model?: string;
     input?: boolean;
-}): Promise<ResolvedPlacement & {
-    modelSpec?: string;
-}>;
+}, before?: (agentDir: string) => Promise<void>): Promise<EnteredAgent>;
 /**
- * How every command that RUNS the agent on this machine enters it (dev, start, invoke, routine run, chat):
+ * How every command that RUNS the agent on this machine enters it (dev, start, invoke, schedules run):
  * {@link enterAgentDirectory}, plus a default model. The agent opens without one, but a process here would then fail
- * every new conversation, so it stops at startup with {@link missingDefaultModel} instead.
+ * every new conversation, so it stops at startup instead: exit 2, the choice a terminal's picker would have asked for.
  */
 export declare function enterAgentCommand(dirArg: string, opts: {
     model?: string;
     input?: boolean;
-}): Promise<ResolvedPlacement & {
-    modelSpec: string;
-}>;
-/**
- * The startup half of {@link enterAgentCommand}, for the one command that checks something of its own in between:
- * `routine run`, whose unknown name or unset secret is the more basic fault and is reported first.
- */
-export declare function requireDefaultModel(placement: ResolvedPlacement & {
-    modelSpec?: string;
-}): ResolvedPlacement & {
-    modelSpec: string;
-};
-/** What the startup report reads off an opened directory. */
-export interface ReportableAssembly {
-    agentDir: string;
-    workspace: string;
-    modelSpec: string;
-    models: AgentModels;
-    config: {
-        thinkingLevel?: string;
-    };
-    definition: LoadedDefinition;
-    toolNames: string[];
-    indirectTools: IndirectTool[];
-    toolCollisions: ToolCollision[];
-}
-/** What `dev` and `start` say about the directory they just opened, in the order they say it. */
-export declare function reportAssembly(a: ReportableAssembly, extras?: {
-    /** Printed between `workspace:` and `model:` (`dev` names the config file here). */
-    beforeModel?: [label: string, value: string][];
-    /** Printed after the tool lines, before findings (`start` names state + sessions here). */
-    afterTools?: [label: string, value: string][];
-}): Promise<void>;
+}, before?: (agentDir: string) => Promise<void>): Promise<Required<EnteredAgent>>;
+/** What `dev` and `start` say about the agent they just opened, in the order they say it. */
+export declare function reportAssembly(opened: OpenedServing, modelSpec: string, extras?: [label: string, value: string][]): Promise<void>;
 /** Both stdin and stdout are a terminal — the precondition for an interactive prompt. */
 export declare function isInteractive(): boolean;
 /** Parse + range-check a port string (CLI flag or env). */
@@ -66,6 +37,8 @@ export declare function parsePort(value: string | undefined, source: string, fro
  */
 export declare function parseBind(value: string | undefined): string | undefined;
 /** Report which source provides the model's credentials, surfacing a remediation hint at startup. */
-export declare function reportAuth(models: AgentModels, modelSpec: string): Promise<void>;
+export declare function reportAuth(models: ModelEnvironment, modelSpec: string, agentDir: string): Promise<void>;
 /** Login terminal IO via @clack/prompts: a searchable list once long, a hidden prompt for keys. */
 export declare function terminalLoginIO(): LoginIO;
+/** A copy/paste-safe POSIX shell argument for a command the CLI prints. */
+export declare function shellArg(value: string): string;

package/dist/cli/shared.js

@@ -2,79 +2,68 @@
  * Helpers shared across command modules: interactivity gates, port parsing, the startup auth report, first-run model
  * resolution, and the login terminal IO.
  */
-import { readFile, writeFile } from "node:fs/promises";
-import { relative, resolve } from "node:path";
+import { resolve } from "node:path";
 import { autocomplete, isCancel, log as clackLog, password, select, text as clackText } from "@clack/prompts";
 import { buildModelPickerOptions } from "./models-view.js";
-import { isValidPort, listModels, loadConfig, missingDefaultModel, providerOf, resolveModelSpec, rewriteConfigModel, } from "../engines/pi/config.js";
-import { LoginCancelled, loginFlow } from "../engines/pi/login.js";
-import { readMachine, withMachine } from "../engines/pi/machine.js";
-import { providerAuthStatuses } from "../engines/pi/models.js";
-import { agentModels } from "../engines/pi/agent-models.js";
+import { LoginCancelled, loginFlow } from "../harnesses/models/login.js";
+import { modelEnvironment } from "../harnesses/models/environment.js";
+import { listModels, providerAuthStatuses, providerOf } from "../harnesses/models/models.js";
+import { definitionProviders, loadConfig, modelSpecFor } from "../harnesses/pi-durable/open.js";
 import { formatAuthReport } from "./auth-view.js";
-import { CODING_TOOL_NAMES } from "../engines/pi/create.js";
-import { describeIndirectTools, describePrompt, reportFindingsIfChanged, reportToolCollisions, } from "../engines/pi/report.js";
-import { isDeployedWorkspace } from "../paths.js";
+import { contentLines } from "./content-view.js";
+import { deployedHost, isDeployedWorkspace } from "../paths.js";
 import { log } from "../log.js";
-import { enterAgentEnv } from "../env.js";
+import { dotEnvPath, enterAgentEnv } from "../env.js";
 import { openExternalUrl } from "../open-url.js";
 import { bindAddress, isBindAddress } from "../bind.js";
-import { failStartup, failUsage, placementOrExit } from "./fail.js";
+import { agentDirOrExit, failStartup, failUsage } from "./fail.js";
 /**
- * How a command enters its agent directory, in the one order that works: placement, the agent's environment, then the
- * first-run model picker. Returns the default model that then resolves, if any. `deploy` uses this directly: it gates
- * a missing model itself, by what will ship.
+ * How a command enters its agent directory, in the one order that works: the directory, the agent's environment, then
+ * the first-run model picker. Returns the default model that then resolves, if any. `deploy` uses this directly: it
+ * gates a missing model itself, by what will ship. `before`: what the command checks of the directory before a model
+ * is asked for (`schedules run`: that the schedule it names exists).
  */
-export async function enterAgentDirectory(dirArg, opts) {
-    const placement = placementOrExit(resolve(dirArg));
-    enterAgentEnv(placement.agentDir);
-    const modelSpec = await resolveFirstRunModel(placement, opts);
-    return { ...placement, ...(modelSpec ? { modelSpec } : {}) };
+export async function enterAgentDirectory(dirArg, opts, before) {
+    const agentDir = agentDirOrExit(resolve(dirArg));
+    enterAgentEnv(agentDir);
+    await before?.(agentDir);
+    const modelSpec = await resolveFirstRunModel(agentDir, opts);
+    return { agentDir, ...(modelSpec ? { modelSpec } : {}) };
 }
 /**
- * How every command that RUNS the agent on this machine enters it (dev, start, invoke, routine run, chat):
+ * How every command that RUNS the agent on this machine enters it (dev, start, invoke, schedules run):
  * {@link enterAgentDirectory}, plus a default model. The agent opens without one, but a process here would then fail
- * every new conversation, so it stops at startup with {@link missingDefaultModel} instead.
+ * every new conversation, so it stops at startup instead: exit 2, the choice a terminal's picker would have asked for.
  */
-export async function enterAgentCommand(dirArg, opts) {
-    return requireDefaultModel(await enterAgentDirectory(dirArg, opts));
-}
-/**
- * The startup half of {@link enterAgentCommand}, for the one command that checks something of its own in between:
- * `routine run`, whose unknown name or unset secret is the more basic fault and is reported first.
- */
-export function requireDefaultModel(placement) {
-    const { modelSpec } = placement;
-    if (!modelSpec)
-        failStartup(missingDefaultModel());
-    return { ...placement, modelSpec };
+export async function enterAgentCommand(dirArg, opts, before) {
+    const entered = await enterAgentDirectory(dirArg, opts, before);
+    const { modelSpec } = entered;
+    if (!modelSpec) {
+        failUsage(`missing model: set --model, "model" in fastagent.config.ts, or FASTAGENT_MODEL (e.g. "openai/gpt-5.5"; ` +
+            "`fastagent models` lists them)");
+    }
+    return { ...entered, modelSpec };
 }
 /** The padded label writer for the STARTUP report (`dev`/`start`, stderr via the log level). */
 function reportLine(label, value) {
     log.info(`[fastagent] ${`${label}:`.padEnd(13)}${value}`);
 }
-/** What `dev` and `start` say about the directory they just opened, in the order they say it. */
-export async function reportAssembly(a, extras = {}) {
-    reportLine("agent", a.agentDir);
-    reportLine("workspace", a.workspace);
-    for (const [label, value] of extras.beforeModel ?? [])
+/** What `dev` and `start` say about the agent they just opened, in the order they say it. */
+export async function reportAssembly(opened, modelSpec, extras = []) {
+    const { definition, code, models, agentDir, stateRoot } = opened;
+    reportLine("agent", `${definition.name} — ${agentDir}`);
+    for (const [label, value] of contentLines(opened.content))
         reportLine(label, value);
-    reportLine("model", `${a.modelSpec}${a.config.thinkingLevel ? ` (thinking: ${a.config.thinkingLevel})` : ""}`);
-    await reportAuth(a.models, a.modelSpec);
-    reportLine("context", a.definition.contextFiles.map((f) => f.path).join(", ") || "(none)");
-    reportLine("prompt", describePrompt(a.definition));
-    // What this agent HAS — the definition's skills and the ones its machine lends (machine.ts).
-    const skills = withMachine(a.definition.skills, (await readMachine(a.workspace)).skills);
-    reportLine("skills", skills.map((s) => s.name).join(", ") || "(none)");
-    reportLine("codingTools", CODING_TOOL_NAMES.join(", "));
-    if (a.toolNames.length > 0)
-        reportLine("tools", a.toolNames.join(", "));
-    if (a.indirectTools.length > 0)
-        reportLine("indirect", describeIndirectTools(a.indirectTools));
-    reportToolCollisions(a.toolCollisions);
-    for (const [label, value] of extras.afterTools ?? [])
+    reportLine("model", `${modelSpec}${definition.config.thinkingLevel ? ` (thinking: ${definition.config.thinkingLevel})` : ""}`);
+    await reportAuth(models, modelSpec, agentDir);
+    const names = (list) => list.map(({ name }) => name).join(", ") || "(none)";
+    reportLine("tools", names(code.tools));
+    if (code.extensions.length > 0)
+        reportLine("extensions", names(code.extensions));
+    reportLine("commands", (await opened.agent.info()).commands.map(({ name }) => `/${name}`).join(", ") || "(none)");
+    reportLine("state", stateRoot);
+    for (const [label, value] of extras)
         reportLine(label, value);
-    reportFindingsIfChanged(a.definition.dir, a.definition);
 }
 /** Both stdin and stdout are a terminal — the precondition for an interactive prompt. */
 export function isInteractive() {
@@ -87,7 +76,7 @@ export function parsePort(value, source, from) {
     const trimmed = value.trim();
     if (trimmed === "")
         return undefined;
-    if (!/^\d+$/.test(trimmed) || !isValidPort(Number(trimmed))) {
+    if (!/^\d+$/.test(trimmed) || Number(trimmed) > 65535) {
         const message = `invalid ${source} "${value}": must be an integer 0-65535`;
         if (from === "flag")
             failUsage(message);
@@ -108,7 +97,7 @@ export function parseBind(value) {
     return bindAddress(trimmed); // a name never travels past this point — see bind.ts
 }
 /** Report which source provides the model's credentials, surfacing a remediation hint at startup. */
-export async function reportAuth(models, modelSpec) {
+export async function reportAuth(models, modelSpec, agentDir) {
     const provider = providerOf(modelSpec);
     // No files: the opener was handed a credential store, which is its caller's to describe.
     if (models.auth === undefined) {
@@ -119,36 +108,42 @@ export async function reportAuth(models, modelSpec) {
     // line cannot name a file, or a source, other than the ones the runtime uses.
     const modelId = modelSpec.slice(provider.length + 1);
     const status = await models.authStatus(provider, modelId).catch(failStartup);
-    const report = formatAuthReport({ provider, path: models.auth.path, ...status, deployed: isDeployedWorkspace() });
+    const report = formatAuthReport({
+        provider,
+        path: models.auth.path,
+        ...status,
+        ...(isDeployedWorkspace()
+            ? { deployed: { host: deployedHost() } }
+            : { local: { authPath: models.auth.path, valueFile: dotEnvPath(agentDir) } }),
+    });
     log.info(`[fastagent] ${report.line}`);
     if (report.warn)
         log.warn(`[fastagent] ${report.warn}`);
 }
 /**
- * First-run model resolution for every assembly command (dev/start/invoke/fire/chat/deploy): ONE funnel, no dead ends.
+ * The default model, for every command that runs the agent: `--model` > `FASTAGENT_MODEL` > `fastagent.config.ts`. With
+ * none and a terminal, the first-run picker chooses one for this run (and logs in to its provider when needed).
  */
-async function resolveFirstRunModel({ agentDir, workspace }, options = {}) {
-    const { config, path: configPath } = await loadConfig(agentDir).catch(failStartup);
-    const configured = resolveModelSpec(options.model, config);
+async function resolveFirstRunModel(agentDir, options = {}) {
+    const config = await loadConfig(agentDir).catch(failStartup);
+    const configured = modelSpecFor(config, options.model);
     if (configured)
-        return configured; // already set (flag > FASTAGENT_MODEL > config)
+        return configured;
     if (options.input === false)
         return undefined; // --no-input: never prompt (clig) — the caller decides what's missing
     if (!isInteractive())
         return undefined; // CI/deploy: the caller raises the actionable missing-model error
-    const environment = agentModels(agentDir, {}, { cwd: workspace });
-    // The picker lists the AGENT's surface: built-ins plus whatever its models.json declares, so a self-hosted endpoint
-    // is pickable on first run instead of being invisible until hand-set.
-    const models = await environment.runtime().catch(failStartup);
-    const chosen = await pickWithCredentials(models, environment.auth.path, agentDir);
+    const providers = await definitionProviders(agentDir).catch(failStartup);
+    const environment = await modelEnvironment(agentDir, {}, providers);
+    const chosen = await pickWithCredentials(environment.models, environment.auth?.path, providers);
     if (chosen === undefined)
         return undefined; // cancelled (or auth probe failed): the caller raises its clear error
     process.env.FASTAGENT_MODEL = chosen; // this process + any spawned dev worker inherits it
-    await persistModelChoice(agentDir, configPath, chosen);
+    console.error(`[fastagent] picked ${chosen} — set \`model: ${JSON.stringify(chosen)}\` in fastagent.config.ts to keep it`);
     return chosen;
 }
 /** The credential-aware pick: full catalog annotated per provider, then the post-pick auth policy. */
-async function pickWithCredentials(models, authPath, agentDir) {
+async function pickWithCredentials(models, authPath, providers) {
     let statuses;
     try {
         statuses = await providerAuthStatuses(models);
@@ -181,7 +176,7 @@ async function pickWithCredentials(models, authPath, agentDir) {
     }
     try {
         // Verified on this agent's registry, against the chosen model: the request the agent is about to make.
-        await loginFlow(terminalLoginIO(), { provider, authPath, agentDir, verifyWith: chosen });
+        await loginFlow(terminalLoginIO(), { provider, authPath, providers, verifyWith: chosen });
         console.error(`[fastagent] logged in to ${provider} — saved to ${authPath}`);
     }
     catch (error) {
@@ -210,23 +205,7 @@ export function terminalLoginIO() {
         openUrl: openExternalUrl,
     };
 }
-/** Best-effort persist the picked model so the next run does not prompt. */
-async function persistModelChoice(agentDir, configPath, spec) {
-    const hint = (why = "") => console.error(
-    // The pick lives in THIS process's environment only, so it serves this run and nothing that outlives it: a
-    // deployment resolves in the environment being deployed, where this machine's variables do not exist.
-    `[fastagent] picked ${spec} — set \`model: ${JSON.stringify(spec)}\` in your config to persist${why}`);
-    if (!configPath)
-        return hint();
-    try {
-        const replaced = rewriteConfigModel(await readFile(configPath, "utf8"), spec);
-        if (!replaced)
-            return hint();
-        await writeFile(configPath, replaced);
-        console.error(`[fastagent] saved model ${JSON.stringify(spec)} to ${relative(agentDir, configPath)}`);
-    }
-    catch (error) {
-        // The run goes on with the pick either way; the reason the file was not written is what the author needs to fix.
-        hint(` (could not write ${configPath}: ${error.message})`);
-    }
+/** A copy/paste-safe POSIX shell argument for a command the CLI prints. */
+export function shellArg(value) {
+    return /^[A-Za-z0-9_./:@%+=,-]+$/.test(value) ? value : `'${value.replaceAll("'", `'"'"'`)}'`;
 }