@fastagent-sh/fastagent 0.17.1 → 0.18.0

package/dist/cli/commands/deploy.js

@@ -76,7 +76,7 @@ export async function runDeploy(host, dirArg, opts) {
         failStartup(new Error(`deploy stopped: ${pre.gate}`));
     for (const m of pre.messages)
         console.error(`[fastagent] ${m.level}: ${m.text}`);
-    const { channels, routeChannels, longConnectionChannels, hasTimeTriggers, modelAuth, authPath, container, port, extraSecrets, } = pre;
+    const { channels, routeChannels, longConnectionChannels, hasTimeTriggers, modelAuth, modelKeyInDefinition, authPath, container, port, extraSecrets, } = pre;
     const hasDeclaredChannels = routeChannels.length + longConnectionChannels.length > 0;
     // Docker: one app service + loopback port + state volume. `--tunnel` shapes the generated topology
     // with an optional Quick Tunnel service; `--run` alone decides whether Docker receives side effects.
@@ -126,6 +126,7 @@ export async function runDeploy(host, dirArg, opts) {
                 port,
                 requireTunnel: requestedTunnel,
                 modelAuth,
+                modelKeyInDefinition,
                 authPath,
                 channels,
                 longConnectionChannels,
@@ -176,6 +177,7 @@ export async function runDeploy(host, dirArg, opts) {
                 workspace,
                 name: serviceName,
                 modelAuth,
+                modelKeyInDefinition,
                 authPath,
                 channels,
                 longConnectionChannels,
@@ -278,6 +280,7 @@ export async function runDeploy(host, dirArg, opts) {
                 agentPrefix: container.agentPrefix,
                 name: acName,
                 modelAuth,
+                modelKeyInDefinition,
                 authPath,
                 channels,
                 extraSecrets,
@@ -371,6 +374,7 @@ export async function runDeploy(host, dirArg, opts) {
             agentPrefix: container.agentPrefix,
             appName,
             modelAuth,
+            modelKeyInDefinition,
             authPath,
             channels,
             longConnectionChannels,
@@ -468,9 +472,10 @@ function deployEnvironment(agentDir, channels) {
  * when present, yields an ephemeral URL that reuses the same webhook announcer as `dev --tunnel`.
  */
 async function runDeployDocker(params) {
-    const { agentDir, workspace, composeFile, port, requireTunnel, modelAuth, authPath, channels, longConnectionChannels, extraSecrets, } = params;
+    const { agentDir, workspace, composeFile, port, requireTunnel, modelAuth, modelKeyInDefinition, authPath, channels, longConnectionChannels, extraSecrets, } = params;
     const { secrets, missingSecrets, needsModelCredential } = assembleSecrets({
         modelAuth,
+        modelKeyInDefinition,
         authFile: (await exists(authPath)) ? await readFile(authPath) : undefined,
         channels,
         longConnectionChannels,
@@ -511,7 +516,7 @@ async function runDeployDocker(params) {
  * behind the shared {@link spawnRunner} seam (spawned `fly`, cwd = the workspace so the build context is the whole workspace).
  */
 async function runDeployFly(params) {
-    const { agentDir, workspace, agentPrefix, appName, modelAuth, authPath, channels, longConnectionChannels, flyTomlPath, extraSecrets, } = params;
+    const { agentDir, workspace, agentPrefix, appName, modelAuth, modelKeyInDefinition, authPath, channels, longConnectionChannels, flyTomlPath, extraSecrets, } = params;
     const fly = spawnRunner("fly", workspace);
     // Fail fast if flyctl is absent (spawn ENOENT → 127), with the install link — not a confusing auth gate.
     if ((await fly(["version"], { capture: true })).code === 127) {
@@ -520,6 +525,7 @@ async function runDeployFly(params) {
     const region = parseFlyRegion(await readFile(flyTomlPath, "utf8")) ?? "iad";
     const { secrets, missingSecrets, needsModelCredential } = assembleSecrets({
         modelAuth,
+        modelKeyInDefinition,
         authFile: (await exists(authPath)) ? await readFile(authPath) : undefined,
         channels,
         longConnectionChannels,
@@ -553,9 +559,10 @@ async function runDeployFly(params) {
  * file (secret values off argv) is created here — 0600, removed after the run either way.
  */
 async function runDeployAgentcore(params) {
-    const { agentDir, workspace, agentPrefix, name, modelAuth, authPath, channels, extraSecrets, selfSchedule } = params;
+    const { agentDir, workspace, agentPrefix, name, modelAuth, modelKeyInDefinition, authPath, channels, extraSecrets, selfSchedule, } = params;
     const { secrets, missingSecrets, needsModelCredential } = assembleSecrets({
         modelAuth,
+        modelKeyInDefinition,
         authFile: (await exists(authPath)) ? await readFile(authPath) : undefined,
         channels,
         extraSecrets,
@@ -627,7 +634,7 @@ async function runDeployAgentcore(params) {
  * webhook) lives in {@link deployRailwayRun}; see there for why Railway differs from Fly.
  */
 async function runDeployRailway(params) {
-    const { agentDir, workspace, name, modelAuth, authPath, channels, longConnectionChannels, extraSecrets, intoLinked, dockerfilePath, } = params;
+    const { agentDir, workspace, name, modelAuth, modelKeyInDefinition, authPath, channels, longConnectionChannels, extraSecrets, intoLinked, dockerfilePath, } = params;
     const railway = spawnRunner("railway", workspace);
     // Fail fast if the railway CLI is absent (spawn ENOENT → 127), with the install link.
     if ((await railway(["--version"], { capture: true })).code === 127) {
@@ -635,6 +642,7 @@ async function runDeployRailway(params) {
     }
     const { secrets, missingSecrets, needsModelCredential } = assembleSecrets({
         modelAuth,
+        modelKeyInDefinition,
         authFile: (await exists(authPath)) ? await readFile(authPath) : undefined,
         channels,
         longConnectionChannels,

package/dist/cli/commands/dev.js

@@ -56,7 +56,7 @@ async function serveOnce(dir, opts) {
     reportWorkspaceHint(workspaceHint(a));
     reportLine("config", a.configPath ?? "(none)");
     reportLine("model", `${a.modelSpec}${a.config.thinkingLevel ? ` (thinking: ${a.config.thinkingLevel})` : ""}`);
-    await reportAuth(a.modelSpec, a.authPath);
+    await reportAuth(a.agentDir, a.modelSpec, a.authPath);
     reportAgentsSkillsTools(a);
     // Trace each turn's agent loop (tool calls + reply) to the log at debug level — shown in dev, gated
     // out in start (level info), keeping end-user content out of production logs. Wired in both postures.

package/dist/cli/commands/fire.js

@@ -37,7 +37,7 @@ export async function runFire(name, dirArg, opts) {
         authPath: opts.authPath, // flag > FASTAGENT_AUTH_PATH > default — resolved by the opener (one owner)
     }).catch(failStartup);
     console.error(`[fastagent] fire: ${name} (${modelSpec})`);
-    await reportAuth(modelSpec, authPath);
+    await reportAuth(placement.agentDir, modelSpec, authPath);
     const exitCode = await runInvokeStream(agent.invoke({ session: scheduleSession(name) }, { text: schedule.prompt }), (text) => process.stdout.write(text), (line) => console.error(line));
     process.stdout.write("\n");
     process.exit(exitCode);

package/dist/cli/commands/info.js

@@ -2,7 +2,8 @@
 import { resolve } from "node:path";
 import { loadDotEnv } from "../../env.js";
 import { discoverChannelFiles } from "../../engines/pi/channel.js";
-import { defaultSessionsDir, loadConfig, resolveAuthPath, resolveModelSpec, resolveSessionsDirOverride, } from "../../engines/pi/config.js";
+import { defaultSessionsDir, loadConfig, resolveAuthPath, resolveModel, resolveModelSpec, resolveSessionsDirOverride, } from "../../engines/pi/config.js";
+import { createPiModelRuntime } from "../../engines/pi/models.js";
 import { resolveStateRoot, workspaceHint } from "../../paths.js";
 import { resolveAgentTools } from "../../engines/pi/create.js";
 import { loadAgentDefinition } from "../../engines/pi/definition.js";
@@ -55,12 +56,27 @@ export async function runInfo(dirArg, opts) {
     const stateRoot = resolveStateRoot(agentDir);
     const sessionsDir = resolveSessionsDirOverride(opts.sessionsDir) ?? defaultSessionsDir(stateRoot);
     const authPath = resolveAuthPath(agentDir, opts.authPath); // flag > FASTAGENT_AUTH_PATH > default — the one owner
+    // RESOLVE the spec, do not just echo it: a spec is only real once its provider/model exist in the
+    // agent's own surface (built-ins + its models.json), which is exactly what a custom endpoint changes.
+    // Reporting a healthy-looking spec that `dev`/`start` then reject is the failure this pre-empts.
+    // Reported as DATA rather than thrown — a broken agent is what `info` is for — and read-only: the
+    // runtime reads models.json without creating anything (its catalog cache is written on refresh, and
+    // there is none here).
+    const modelError = modelSpec
+        ? await createPiModelRuntime({ agentDir, authPath })
+            .then((models) => {
+            resolveModel(models, modelSpec);
+            return undefined;
+        })
+            .catch((error) => error.message)
+        : undefined;
     if (opts.json) {
         console.log(JSON.stringify({
             agentDir,
             workspace,
             configPath: configPath ?? null,
             model: modelSpec ?? null,
+            modelError: modelError ?? null,
             thinkingLevel: config.thinkingLevel ?? null,
             context: definition.contextFiles.map((f) => f.path),
             persona: definition.persona !== undefined,
@@ -85,6 +101,8 @@ export async function runInfo(dirArg, opts) {
     // One padded label writer: hand-spaced labels drifted out of alignment the moment a longer one
     // (agent/workspace/selfSchedule) joined the report.
     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", agentDir);
     line("workspace", workspace);
     const hint = workspaceHint({ agentDir, workspace });
@@ -92,6 +110,8 @@ export async function runInfo(dirArg, opts) {
         line("hint", hint);
     line("config", configPath ?? "(none)");
     line("model", modelSpec ?? "(not set — pass --model, set FASTAGENT_MODEL, or config.model)");
+    if (modelError)
+        cont(`⚠ does not resolve: ${modelError}`);
     if (config.thinkingLevel)
         line("thinking", config.thinkingLevel);
     line("context", definition.contextFiles.map((f) => f.path).join(", ") || "(none)");

package/dist/cli/commands/invoke.js

@@ -20,7 +20,7 @@ export async function runInvoke(message, dirArg, opts) {
     // BOTH directories, like dev/start: from the workspace, `placement.workspace` alone equals the dir you
     // typed, so it cannot tell you which agent actually ran.
     console.error(`[fastagent] invoke: ${placement.agentDir} (workspace ${placement.workspace}, ${modelSpec})`);
-    await reportAuth(modelSpec, authPath);
+    await reportAuth(placement.agentDir, modelSpec, authPath);
     // Fresh session per invoke (one-shot, no resume). runInvokeStream maps events→IO: reply→stdout,
     // tool/failure→stderr, exit 1 iff the turn failed (so CI can gate on it).
     const exitCode = await runInvokeStream(agent.invoke({ session: randomUUID() }, { text: message }), (text) => process.stdout.write(text), (line) => console.error(line));

package/dist/cli/commands/start.js

@@ -49,7 +49,7 @@ export async function runStart(dirArg, opts) {
     reportLine("workspace", workspace);
     reportWorkspaceHint(workspaceHint({ agentDir, workspace }));
     reportLine("model", `${modelSpec}${config.thinkingLevel ? ` (thinking: ${config.thinkingLevel})` : ""}`);
-    await reportAuth(modelSpec, authPath);
+    await reportAuth(agentDir, modelSpec, authPath);
     reportLine("context", definition.contextFiles.map((f) => f.path).join(", ") || "(none)");
     if (definition.persona)
         reportLine("persona", "persona.md");

package/dist/cli/shared.d.ts

@@ -26,8 +26,10 @@ export declare function parsePort(value: string | undefined, source: string, fro
  * a node bind failure, or worse, as a "the interface you bound" diagnostic downstream.
  */
 export declare function parseBind(value: string | undefined): string | undefined;
-/** Report which source provides the model's credentials, surfacing a remediation hint at startup. Non-blocking. */
-export declare function reportAuth(modelSpec: string, authPath: string): Promise<void>;
+/** Report which source provides the model's credentials, surfacing a remediation hint at startup. Non-blocking.
+ *  Probes through the AGENT's model surface (`agentDir` carries its models.json), so a custom endpoint is
+ *  reported like any built-in rather than as an unknown provider. */
+export declare function reportAuth(agentDir: string, modelSpec: string, authPath: string): Promise<void>;
 /**
  * First-run model resolution for every assembly command (dev/start/invoke/fire/chat/deploy): ONE
  * funnel, no dead ends. When no model is set (flag/env/config) and we're on a TTY, show the FULL

package/dist/cli/shared.js

@@ -10,7 +10,7 @@ import { buildModelPickerOptions } from "./models-view.js";
 import { fastagentCredentialStore } from "../engines/pi/auth.js";
 import { isValidPort, listModels, loadConfig, providerOf, resolveAuthPath, resolveModel, resolveModelSpec, rewriteConfigModel, } from "../engines/pi/config.js";
 import { LoginCancelled, loginFlow } from "../engines/pi/login.js";
-import { createPiModels, probeApiKey, probeAuthSource, providerAuthStatuses } from "../engines/pi/models.js";
+import { createPiModelRuntime, createPiModels, probeApiKey, probeAuthSource, providerAuthStatuses, } from "../engines/pi/models.js";
 import { formatAuthReport } from "./auth-view.js";
 import { log } from "../log.js";
 import { openExternalUrl } from "../open-url.js";
@@ -70,10 +70,13 @@ export function parseBind(value) {
         failUsage(`invalid --bind "${value}": must be an IP address or "localhost"`);
     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. Non-blocking. */
-export async function reportAuth(modelSpec, authPath) {
+/** Report which source provides the model's credentials, surfacing a remediation hint at startup. Non-blocking.
+ *  Probes through the AGENT's model surface (`agentDir` carries its models.json), so a custom endpoint is
+ *  reported like any built-in rather than as an unknown provider. */
+export async function reportAuth(agentDir, modelSpec, authPath) {
     const provider = providerOf(modelSpec);
-    const source = await probeAuthSource(createPiModels({ authPath }), modelSpec);
+    const models = await createPiModelRuntime({ agentDir, authPath }).catch(failStartup);
+    const source = await probeAuthSource(models, modelSpec);
     // Only when nothing satisfies auth do we read the store (refresh-FREE) to tell "nothing stored" from
     // "stored but unusable" — see formatAuthReport for why. store.read warns on a corrupt file itself.
     const stored = source === undefined
@@ -107,7 +110,9 @@ export async function resolveFirstRunModel(agentDir, options = {}) {
     if (!isInteractive())
         return; // CI/deploy: the opener throws the actionable missing-model error
     const authPath = resolveAuthPath(agentDir, options.authPath);
-    const models = createPiModels({ authPath });
+    // 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 createPiModelRuntime({ agentDir, authPath }).catch(failStartup);
     const chosen = await pickWithCredentials(models, authPath);
     if (chosen === undefined)
         return; // cancelled (or auth probe failed): the caller raises its clear missing-model error
@@ -208,6 +213,8 @@ seams = {}) {
  * more than keeping a doubtful one.
  */
 async function verifyApiKeyLogin(provider, authPath, spec) {
+    // Built-ins only: `login` itself offers built-in providers (login.ts), and a models.json endpoint
+    // authenticates from its own `apiKey` (env/command), so there is no stored credential to verify here.
     const models = createPiModels({ authPath });
     const model = spec ? resolveModel(models, spec) : models.getProvider(provider)?.getModels()[0];
     if (!model) {

package/dist/collect.d.ts

@@ -1,8 +1,13 @@
 /**
- * Caller-side stream helpers: `collect` (buffered consumption, SPEC §7) reduces an AgentEvent
- * stream to a final value, encoding the terminal discipline (failed → throw, missing terminal →
- * error) — streaming consumers for-await themselves. `abortFirstIterator` is the shared
- * cancellation protocol for generator-backed streams.
+ * Stream helpers around the SPEC's two stream disciplines.
+ *
+ * Caller side: `collect` (buffered consumption, SPEC §7) reduces an AgentEvent stream to a final
+ * value, encoding the terminal discipline (failed → throw, missing terminal → error) — streaming
+ * consumers for-await themselves.
+ *
+ * Agent side: the cancellation protocol (SPEC MUST 3), in two halves that only work together —
+ * `abortFirstIterator` delivers the consumer's knock, `cancellableStream` is what an engine wraps
+ * its turn in to receive it.
  */
 import type { AgentEvent, Json } from "./agent.ts";
 /**
@@ -13,8 +18,29 @@ import type { AgentEvent, Json } from "./agent.ts";
  * settles the suspension), then delegates to `gen.return`, swallowing its rejection (the
  * generator's own catch/finally already surfaced the outcome). `throw()` tears down identically
  * and rethrows the caller's error deterministically instead of poking a completed generator.
+ *
+ * Cancellation also SILENCES the stream, and that belongs here rather than in each producer: a
+ * generator parked in an await can still reach a `yield` on its way out (an error path that
+ * yields a terminal, say), and that yield satisfies the pending `next()` — handing a terminal
+ * event to a consumer that already walked away, which SPEC MUST 3 forbids. Deciding it once, at
+ * the protocol boundary, is what keeps every producer from having to re-ask "is anyone still
+ * listening?" before each yield.
  */
 export declare function abortFirstIterator<T>(gen: AsyncGenerator<T>, cancel: () => void): AsyncIterator<T>;
+/** What a turn generator gets so a consumer walking away can stop it. */
+export interface CancelHooks {
+    /** Publish the door: how to abort the engine work, once there is engine work to abort. */
+    onCancelReady: (cancel: () => void) => void;
+    /** The latch, for the window where the door is armed but the engine is still idle — knocking then
+     *  does nothing, so a turn must read this before committing to work no one is waiting for. */
+    wasCancelled: () => boolean;
+}
+/**
+ * Wrap a turn generator in the cancellation protocol: cancelling the returned stream latches the
+ * intent AND knocks on whatever door the generator published, in that order (the latch must be set
+ * before the knock, or a turn checking it mid-flight could miss the cancel it just received).
+ */
+export declare function cancellableStream<T>(start: (hooks: CancelHooks) => AsyncGenerator<T>): AsyncIterable<T>;
 /** Exception form of a failed event (thrown by collect). Carries the failed event's fields verbatim, so
  *  a buffered consumer can branch on `code` (SPEC §8 failure subdivision) just like a streaming one. */
 export declare class AgentFailure extends Error {

package/dist/collect.js

@@ -6,22 +6,55 @@
  * settles the suspension), then delegates to `gen.return`, swallowing its rejection (the
  * generator's own catch/finally already surfaced the outcome). `throw()` tears down identically
  * and rethrows the caller's error deterministically instead of poking a completed generator.
+ *
+ * Cancellation also SILENCES the stream, and that belongs here rather than in each producer: a
+ * generator parked in an await can still reach a `yield` on its way out (an error path that
+ * yields a terminal, say), and that yield satisfies the pending `next()` — handing a terminal
+ * event to a consumer that already walked away, which SPEC MUST 3 forbids. Deciding it once, at
+ * the protocol boundary, is what keeps every producer from having to re-ask "is anyone still
+ * listening?" before each yield.
  */
 export function abortFirstIterator(gen, cancel) {
+    let cancelled = false;
+    const teardown = async () => {
+        cancelled = true;
+        cancel();
+        await gen.return(undefined).catch(() => { });
+    };
     return {
-        next: () => gen.next(),
-        async return(value) {
-            cancel();
-            await gen.return(value).catch(() => { });
+        async next() {
+            const result = await gen.next();
+            return cancelled ? { done: true, value: undefined } : result;
+        },
+        async return() {
+            await teardown();
             return { done: true, value: undefined };
         },
         async throw(error) {
-            cancel();
-            await gen.return(undefined).catch(() => { });
+            await teardown();
             throw error;
         },
     };
 }
+/**
+ * Wrap a turn generator in the cancellation protocol: cancelling the returned stream latches the
+ * intent AND knocks on whatever door the generator published, in that order (the latch must be set
+ * before the knock, or a turn checking it mid-flight could miss the cancel it just received).
+ */
+export function cancellableStream(start) {
+    let door;
+    let cancelled = false;
+    const iterator = abortFirstIterator(start({
+        onCancelReady: (cancel) => {
+            door = cancel;
+        },
+        wasCancelled: () => cancelled,
+    }), () => {
+        cancelled = true;
+        door?.();
+    });
+    return { [Symbol.asyncIterator]: () => iterator };
+}
 /** Exception form of a failed event (thrown by collect). Carries the failed event's fields verbatim, so
  *  a buffered consumer can branch on `code` (SPEC §8 failure subdivision) just like a streaming one. */
 export class AgentFailure extends Error {

package/dist/deploy/preflight.d.ts

@@ -19,9 +19,15 @@ interface DeployFacts {
      *  has no external wake-up, so the deployment must keep one machine running: the fly plan forces
      *  `min_machines_running=1`, the railway runbook forbids App Sleeping. */
     hasTimeTriggers: boolean;
-    /** What satisfies model auth locally ({@link probeAuthSource}) — an env-var name, an OAuth/stored label,
-     *  or undefined. Drives the runbook's secret guidance and `--run`'s credential carry. */
+    /** What satisfies model auth locally — an env-var name, an OAuth/stored label, or undefined. Drives the
+     *  runbook's secret guidance and `--run`'s credential carry. For a models.json endpoint keyed from the
+     *  environment this is the VARIABLE NAME (see {@link modelCredentialCarry}), not the display label, so
+     *  the value carries like any provider key. */
     modelAuth: string | undefined;
+    /** The definition itself carries the model key (a models.json literal `apiKey`, or a `!command` run on
+     *  the host), so there is nothing for `--run` to carry AND nothing to gate: `fastagent login` cannot
+     *  serve a custom provider, so gating on it would strand a correctly configured agent. */
+    modelKeyInDefinition: boolean;
     /** The project-level auth file `--run` reads to carry the credential (probed with the same path). */
     authPath: string;
     /** Container facts shared by the plan and the generated Dockerfile — ONE source, so they can't drift. */

package/dist/deploy/preflight.js

@@ -17,12 +17,13 @@ import { resolveAuthPath } from "../engines/pi/config.js";
 import { resolveSecretsDir, resolveStateRoot } from "../paths.js";
 import { inspectChannels } from "../engines/pi/channel.js";
 import { discoverScheduleFiles } from "../schedule/discover.js";
-import { createPiModels, probeAuthSource } from "../engines/pi/models.js";
+import { createPiModelRuntime, modelCredentialCarry, probeAuthSource } from "../engines/pi/models.js";
 import { CHANNEL_KINDS } from "../scaffold/add-channel.js";
 import { exists } from "../paths.js";
 import { detectRuntime, readPackageJson } from "../runtime.js";
 import { fastagentVersion } from "../version.js";
 import { isGeneratedDockerfile, isGeneratedDockerignore } from "./container.js";
+import { isEnvKey } from "./secrets.js";
 /**
  * "Would docker's packer drop this path?" — built from a `.dockerignore`'s text via the `ignore`
  * matcher (the same library the workspace ignore files use), so `!` negation and last-match-wins are
@@ -126,9 +127,25 @@ export async function preflightDeploy(input) {
         });
     }
     // Probe auth from the SAME project-level file the opener/login use — not the global default, which would
-    // miss a `fastagent login` credential and falsely report "none configured".
+    // miss a `fastagent login` credential and falsely report "none configured". Through the AGENT's model
+    // surface too (its models.json travels into the image), so a custom endpoint is not read as an unknown
+    // provider — this probe feeds the gate that decides whether `--run` may proceed.
     const authPath = resolveAuthPath(agentDir, authPathFlag);
-    const modelAuth = modelSpec ? await probeAuthSource(createPiModels({ authPath }), modelSpec) : undefined;
+    const models = await createPiModelRuntime({ agentDir, authPath });
+    let modelAuth = modelSpec ? await probeAuthSource(models, modelSpec) : undefined;
+    let modelKeyInDefinition = false;
+    // probeAuthSource answers "is it authenticated here", which is not the deploy question ("how does the
+    // credential REACH the host"). It reports every models.json endpoint as "configured API key" — not an
+    // env-var name — so without this the gate below sees no credential and stops the deploy with two
+    // remedies that are both wrong for such an agent: `fastagent login` cannot serve a custom provider,
+    // and the key is already in the environment.
+    if (modelSpec && !isEnvKey(modelAuth)) {
+        const carry = modelCredentialCarry(models, modelSpec);
+        if (carry.envVar)
+            modelAuth = carry.envVar;
+        else
+            modelKeyInDefinition = carry.inDefinition;
+    }
     // Container facts (shared by every host) + the warnings that follow. The facts describe the AGENT —
     // its package.json/runtime/lockfile drive the image's install step — never the workspace's (the bake
     // ships the whole tree, but the workspace's own manifest belongs to its own deploy).
@@ -410,6 +427,7 @@ export async function preflightDeploy(input) {
         longConnectionChannels,
         hasTimeTriggers,
         modelAuth,
+        modelKeyInDefinition,
         authPath,
         container,
         port,

package/dist/deploy/secrets.d.ts

@@ -38,6 +38,9 @@ export declare function deploymentSecrets(modelAuth: string | undefined, channel
  */
 export declare function assembleSecrets(input: {
     modelAuth: string | undefined;
+    /** The definition carries the model key itself (a models.json literal `apiKey` / `!command`): there is
+     *  no value to carry and no gate to raise — see {@link modelCredentialCarry}. */
+    modelKeyInDefinition?: boolean;
     authFile: Buffer | undefined;
     channels: ChannelKind[];
     longConnectionChannels?: string[];

package/dist/deploy/secrets.js

@@ -65,6 +65,12 @@ export function assembleSecrets(input) {
     else if (input.authFile) {
         secrets.FASTAGENT_AUTH_SEED = input.authFile.toString("base64");
     }
+    else if (input.modelKeyInDefinition) {
+        // The definition authenticates itself (models.json literal key, or a command run on the host), so it
+        // travels in the image with everything else. Gating here would be the worst kind of wrong: both
+        // remedies we print are impossible for such an agent — `fastagent login` has no flow for a custom
+        // provider, and there is no provider env key to set.
+    }
     else {
         needsModelCredential = true; // no env key, no auth.json — `fastagent login` remediation
     }

package/dist/dev-supervisor.js

@@ -13,7 +13,7 @@
 import { spawn } from "node:child_process";
 import { relative, sep } from "node:path";
 import { watch as watchTree } from "chokidar";
-import { AGENT_CONFIG_NAMES, resolveStateRoot } from "./paths.js";
+import { AGENT_CONFIG_NAMES, AGENT_MODELS_FILE, resolveStateRoot } from "./paths.js";
 import { isUnderDir } from "./engines/pi/definition.js";
 import { dotEnvPath } from "./env.js";
 import { log } from "./log.js";
@@ -21,7 +21,7 @@ import { installProxyFetch } from "./proxy.js";
 import { openExternalUrl } from "./open-url.js";
 import { announceWebhooks, startCloudflareTunnel } from "./tunnel.js";
 /** What the dev watcher restarts on (agent-dir-relative): the process-bound code inputs only. */
-const WATCHED_HINT = "tools/, channels/, schedules/, package.json, fastagent.config.*, .secrets/.env";
+const WATCHED_HINT = "tools/, channels/, schedules/, package.json, fastagent.config.*, models.json, .secrets/.env";
 /**
  * chokidar `ignored` matcher for the narrow watch scope (true = ignore), rooted at the AGENT DIR. When
  * the agent sits INSIDE the workspace that means the surrounding tree never triggers a restart at all;
@@ -49,6 +49,12 @@ export function devWatchIgnored(root, envFile) {
             return false;
         if (rel === "package.json")
             return false;
+        // models.json is read ONCE per worker (the model hub is built during assembly), so an edit needs a
+        // restart like any other code input. It is also the one input whose breakage KILLS the worker — a
+        // malformed file fails assembly — so leaving it unwatched would strand the author: the fix that
+        // repairs it would not be the edit that restarts.
+        if (rel === AGENT_MODELS_FILE)
+            return false;
         const segments = rel.split(sep);
         if (segments[0] === "tools" || segments[0] === "channels" || segments[0] === "schedules")
             return false;

package/dist/engines/pi/create.d.ts

@@ -7,7 +7,8 @@ import { type AnyModel, piHarnessFactory } from "./harness.ts";
 import { type PiSessionStore } from "./sessions.ts";
 import type { ModuleLoadFailure } from "../../loader.ts";
 import { type ToolCollision, type MountedTool } from "./tool.ts";
-import { type Lease, type SessionObserver } from "./invoke.ts";
+import { type SessionObserver } from "./invoke.ts";
+import { type Lease } from "./turn-kit.ts";
 /** pi's core default toolset (read/bash/edit/write). Rooted at the ExecutionEnv's cwd, supplied per
  *  turn as the harness tool context — hence no argument here. */
 export declare function piDefaultTools(): MountedTool[];

package/dist/engines/pi/create.js

@@ -18,12 +18,13 @@ import { defaultAuthPath, resolveModel } from "./config.js";
 import { resolveSecretsDir } from "../../paths.js";
 import { loadAgentDefinition } from "./definition.js";
 import { DEFAULT_THINKING_LEVEL, piHarnessFactory } from "./harness.js";
-import { createPiModels } from "./models.js";
+import { createPiModelRuntime, createPiModels } from "./models.js";
 import { reportFindingsIfChanged } from "./report.js";
 import { inMemorySessionStore } from "./sessions.js";
 import { isDeferredTool, loadTools, mergeDiscoveredTools, } from "./tool.js";
 import { withSearchTool } from "./search-tools.js";
-import { createPiAgentFromHarness, inProcessLease } from "./invoke.js";
+import { createPiAgentFromHarness } from "./invoke.js";
+import { inProcessLease } from "./turn-kit.js";
 // ── §1 tools ─────────────────────────────────────────────────────────────────
 //
 // The full pi toolset is the default for fidelity: authors vibe in local pi with it, so serving with
@@ -164,7 +165,7 @@ export function assembleSystemPrompt(options) {
  * directory) and route through here.
  */
 function buildPiAgent(opts) {
-    const models = createPiModels({ providers: opts.providers, authPath: opts.authPath });
+    const models = opts.models ?? createPiModels({ providers: opts.providers, authPath: opts.authPath });
     const env = opts.env ?? new NodeExecutionEnv({ cwd: process.cwd() });
     // Materialized here (not defaulted inside createPiAgentFromHarness) so the exposed parts carry
     // the SAME lease instance the agent runs under — boundary mutations must contend on it.
@@ -241,13 +242,17 @@ export async function createPiAgentFromDefinition(dir, options) {
     // Deferred tools need their loader on every rung (idempotent — the workspace opener already applied
     // it; a caller's own search_tools wins).
     const tools = withSearchTool(options.tools ?? piDefaultTools());
+    // Dir-aware default: the same secrets-dir-derived file the opener uses for this dir (the opener
+    // passes an explicit authPath, so this only affects direct L2 callers).
+    const authPath = options.authPath ?? defaultAuthPath(resolveSecretsDir(dir));
     const agent = buildPiAgent({
         model: options.model,
         thinkingLevel: options.thinkingLevel,
-        providers: options.providers,
-        // Dir-aware default: the same secrets-dir-derived file the opener uses for this dir (the opener
-        // passes an explicit authPath, so this only affects direct L2 callers).
-        authPath: options.authPath ?? defaultAuthPath(resolveSecretsDir(dir)),
+        // THE directory rung's model surface: built-ins + the agent's own models.json (custom endpoints,
+        // which are definition data and travel with the artifact) + any injected Provider instance. This
+        // is what makes `dev`/`start`/`invoke` and an embedded L2 caller resolve the same specs.
+        models: await createPiModelRuntime({ agentDir: dir, authPath, providers: options.providers }),
+        authPath,
         // The directory is the agent, LIVE: re-read the definition on every invoke, so AGENTS.md/skills
         // edits (the author's, or the agent's own self-modification) take effect on the next turn with
         // no process restart — restarts are reserved for code (tools/channels/config, module cache).

package/dist/engines/pi/harness.d.ts

@@ -9,7 +9,7 @@
 import { AgentHarness } from "@earendil-works/pi-agent-core";
 import type { ExecutionEnv, ExecutionToolContext, Skill, ThinkingLevel } from "@earendil-works/pi-agent-core";
 import type { Model, Models } from "@earendil-works/pi-ai";
-import { type PiSessionStore } from "./sessions.ts";
+import { type PiSessionStore, type SessionInheritance } from "./sessions.ts";
 import { type MountedTool } from "./tool.ts";
 import { type OverrideEntryLike } from "./session-settings.ts";
 /**
@@ -38,7 +38,9 @@ export type AnyModel = Model<any>;
  *  pi's env-backed default tools read (pi 0.83). Custom tools are context-FREE and stay assignable — a
  *  four-parameter `execute` satisfies the five-parameter one, so `defineTool` is untouched by this. */
 type PiHarness = AgentHarness<ExecutionToolContext>;
-export type PiHarnessFactory = (session: string) => PiHarness | Promise<PiHarness>;
+export type PiHarnessFactory = (session: string, 
+/** Where a NEW session starts from (sessions.ts) — an existing session ignores it. */
+inherit?: SessionInheritance) => PiHarness | Promise<PiHarness>;
 export interface PiHarnessFactoryOptions {
     /** Session persistence. Continuity = same backing store + same session id. */
     sessions: PiSessionStore;
@@ -107,6 +109,7 @@ export declare function resolveHarnessOverrides(entries: OverrideEntryLike[], mo
     thinkingLevel: ThinkingLevel;
 };
 export declare function resolveHarnessActiveToolNames(recorded: string[] | null, tools: MountedTool[], sessionId: string): string[] | undefined;
-/** Open-or-create the session per invoke: existing → open (history via buildContext); missing → create. */
+/** Open-or-create the session per invoke: existing → open (history via buildContext); missing →
+ *  create, seeded from `inherit` when the scope names a parent. */
 export declare function piHarnessFactory(options: PiHarnessFactoryOptions): PiHarnessFactory;
 export {};

package/dist/engines/pi/harness.js

@@ -114,10 +114,11 @@ export function resolveHarnessActiveToolNames(recorded, tools, sessionId) {
     }
     return [...new Set([...initial, ...known])];
 }
-/** Open-or-create the session per invoke: existing → open (history via buildContext); missing → create. */
+/** Open-or-create the session per invoke: existing → open (history via buildContext); missing →
+ *  create, seeded from `inherit` when the scope names a parent. */
 export function piHarnessFactory(options) {
-    return async (sessionId) => {
-        const session = await options.sessions.openOrCreate(sessionId);
+    return async (sessionId, inherit) => {
+        const session = await options.sessions.openOrCreate(sessionId, inherit);
         // One extra entry walk per invoke to collect the activation deltas — negligible against the model
         // call, same trade as L2's per-invoke definition re-read. The walk is over the ACTIVE PATH, not
         // the flat journal: `navigate` moves the leaf, so the tree can hold an abandoned branch whose