@fastagent-sh/fastagent 0.21.0 → 0.22.0

package/dist/engines/pi/models.js

@@ -1,108 +1,226 @@
 /**
- * The pi `Models` collection — the single hub that owns BOTH model resolution (provider/modelId
- * lookup) AND auth (per-request credential resolution). fastagent builds one per opener and threads
- * it into the engine alongside the selected `model`; the two must come from the same collection so
- * the model's provider auth is in scope.
+ * The pi `Models` collection — the single hub that owns BOTH model resolution (provider/modelId lookup) AND auth
+ * (per-request credential resolution). fastagent builds one per opener and threads it into the engine alongside the
+ * selected `model`; the two must come from the same collection so the model's provider auth is in scope.
  */
+import { createHash } from "node:crypto";
+import { existsSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+import { homedir } from "node:os";
 import { join } from "node:path";
-import { defaultProviderAuthContext } from "@earendil-works/pi-ai";
-import { builtinModels } from "@earendil-works/pi-ai/providers/all";
+import { InMemoryCredentialStore, defaultProviderAuthContext, } from "@earendil-works/pi-ai";
+import { builtinModels, builtinProviders } from "@earendil-works/pi-ai/providers/all";
 import { ModelRuntime } from "@earendil-works/pi-coding-agent";
 import { fastagentCredentialStore } from "./auth.js";
 import { providerOf } from "./config.js";
-import { interactiveLoginKind } from "./login.js";
-import { AGENT_MODELS_FILE, resolveStateRoot } from "../../paths.js";
-/**
- * A `Models` with every built-in pi provider, wired to fastagent's auth: stored credentials from the
- * {@link CreatePiModelsOptions.authPath} file (via {@link fastagentCredentialStore}; the global
- * `~/.fastagent/.secrets/auth.json` unless the opener passes a project-level path), then ambient env vars. A
- * stored credential owns the provider; env is consulted only when nothing is stored (resolution order
- * is upstream-owned).
- */
+import { AGENT_MODELS_FILE, GLOBAL_HOME_DIR, resolveOverridePath, resolveStateRoot } from "../../paths.js";
+import { writeFileAtomic } from "../../atomic-write.js";
+/** A `Models` with every built-in pi provider, wired to fastagent's auth. */
 export function createPiModels(options = {}) {
-    const models = builtinModels({
-        credentials: fastagentCredentialStore(options.authPath, { warn: options.warn }),
-        authContext: defaultProviderAuthContext(),
-    });
-    for (const provider of options.providers ?? [])
+    return piModelsOver(fastagentCredentialStore(options.authPath, { warn: options.warn }), options.providers);
+}
+/** The built-ins plus `providers` (a same id replaces a built-in), over any credential store. */
+export function piModelsOver(credentials, providers = []) {
+    const models = builtinModels({ credentials, authContext: defaultProviderAuthContext() });
+    for (const provider of providers)
         models.setProvider(provider);
     return models;
 }
+/** The serving default for reasoning effort, pinned to what pi's TUI defaults to (its own DEFAULT_THINKING_LEVEL). */
+export const DEFAULT_THINKING_LEVEL = "medium";
 /**
- * The serving default for reasoning effort, pinned to what pi's TUI defaults to (its own
- * DEFAULT_THINKING_LEVEL) — NOT inherited from the engine, whose fallback is "off": an author vibes
- * at "medium" in pi and must get "medium" when served (fidelity), and pinning the value here means
- * an upstream default change in either place cannot silently alter deployments. Models that do not
- * support a level are clamped by pi per model.
+ * The MACHINE's custom-endpoint file, in the same schema as an agent's own: endpoints a person set up for this machine
+ * (a local Ollama, a company gateway), which every agent here inherits the way it inherits the machine's skills.
+ * `FASTAGENT_MODELS_PATH` moves it. It never ships: a deployed agent has only its definition's file.
  */
-export const DEFAULT_THINKING_LEVEL = "medium";
+export function machineModelsPath(env = process.env) {
+    return resolveOverridePath(env.FASTAGENT_MODELS_PATH) ?? join(homedir(), GLOBAL_HOME_DIR, AGENT_MODELS_FILE);
+}
+/** A custom-endpoint file's providers by id, or undefined when there is no file. Strict JSON: see {@link modelLayers}. */
+async function readProviders(path) {
+    let raw;
+    try {
+        raw = await readFile(path, "utf8");
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return undefined;
+        throw new Error(`could not read ${path}: ${error.message}`);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw.replace(/^\uFEFF/, ""));
+    }
+    catch (error) {
+        throw new Error(`${path} is not valid JSON: ${error.message}`);
+    }
+    const providers = parsed?.providers;
+    if (typeof providers !== "object" || providers === null || Array.isArray(providers)) {
+        throw new Error(`${path} must hold { "providers": { ... } }`);
+    }
+    return providers;
+}
 /**
- * The `ModelRuntime`-shaped sibling of {@link createPiModels} — the SAME hub semantics (built-in
- * providers + fastagent's credential store at `authPath`) in the type pi's session services require
- * (`createAgentSessionServices({ modelRuntime })`). Built-ins PLUS the agent's own
- * {@link AGENT_MODELS_FILE} when `agentDir` is given (a dir-less caller gets built-ins only), and no
- * availability network, so the model surface equals serving's.
+ * The two custom-endpoint layers of an agent, read ONCE for every reader: the file pi loads and the report of where a
+ * provider came from both come from this, so what runs and what `info`/`deploy` say cannot disagree. Undefined when
+ * the machine has no file: then the agent's own file goes to pi untouched.
  *
- * `ModelRuntime` also takes `Provider` INSTANCES via `registerNativeProvider` (pi 0.83); the
- * declarative file is what this rung wires because it is data that travels with the definition.
+ * Read here rather than by pi, because pi loads exactly one path and its comment stripping is not reachable: while a
+ * machine file exists, both files must be plain JSON.
+ */
+async function modelLayers(agentDir) {
+    const machinePath = machineModelsPath();
+    const machine = await readProviders(machinePath);
+    if (!machine)
+        return undefined;
+    return { machinePath, machine, own: (await readProviders(join(agentDir, AGENT_MODELS_FILE))) ?? {} };
+}
+/**
+ * The models.json pi loads for an agent: its own file, layered over the machine's. The agent's file wins a provider id
+ * outright, as a definition's skill wins a name: an agent that pins an endpoint keeps it.
+ *
+ * The merge is a SNAPSHOT named by its content, in fastagent's own home: not in the agent (so `info` writes nothing
+ * there), and not in a shared temp dir, which the OS clears while a long-running process still re-reads it (pi
+ * reloads `modelsPath` on every refresh). Content addressing is what lets every process share the directory: a
+ * snapshot is never rewritten, so no process can change what another's refresh reads. The price is that a running
+ * process keeps the snapshot it started with; an edit to either file takes effect on the next start.
+ *
+ * ponytail: snapshots are never pruned (one per distinct content, a few KB each) because a running process may still
+ * read an old one; delete the directory while no fastagent process runs if it ever matters.
+ */
+async function modelsFileFor(agentDir) {
+    const definition = join(agentDir, AGENT_MODELS_FILE);
+    const layers = await modelLayers(agentDir);
+    if (!layers)
+        return { path: definition };
+    const content = JSON.stringify({ providers: { ...layers.machine, ...layers.own } }, null, 2);
+    const hash = createHash("sha256").update(content).digest("hex").slice(0, 32);
+    const path = join(homedir(), GLOBAL_HOME_DIR, ".cache", "models", `${hash}.json`);
+    // 0600: it may carry literal keys. Several processes may create the same snapshot at once.
+    if (!existsSync(path))
+        writeFileAtomic(path, content, 0o600, true);
+    return { path, merged: { machine: layers.machinePath, definition } };
+}
+/**
+ * Where an agent's custom endpoints come from, for a report: the machine file, the providers the agent inherits from
+ * it, and the ones its own file overrides. Undefined when the machine has no file.
  */
+export async function machineModels(agentDir) {
+    const layers = await modelLayers(agentDir);
+    if (!layers)
+        return undefined;
+    const ids = Object.keys(layers.machine).sort();
+    return {
+        path: layers.machinePath,
+        inherited: ids.filter((id) => !(id in layers.own)),
+        overridden: ids.filter((id) => id in layers.own),
+    };
+}
+/** Whether pi ships this provider id itself, so an agent resolves it without any models.json entry. */
+export function isBuiltinProvider(providerId) {
+    return builtinProviders().some((provider) => provider.id === providerId);
+}
+/** The `ModelRuntime`-shaped sibling of {@link createPiModels}. */
 export async function createPiModelRuntime(options = {}) {
     const { agentDir } = options;
+    const models = !agentDir
+        ? undefined
+        : options.machineLayer === false
+            ? { path: join(agentDir, AGENT_MODELS_FILE) }
+            : await modelsFileFor(agentDir);
     const runtime = await ModelRuntime.create({
-        credentials: fastagentCredentialStore(options.authPath, { warn: options.warn }),
-        modelsPath: agentDir ? join(agentDir, AGENT_MODELS_FILE) : null,
-        // MUST be set whenever modelsPath is: pi defaults this to `<dirname(modelsPath)>/models-store.json`,
-        // which would write a generated cache INTO the author's agent dir — and `deploy` bakes the whole
-        // tree, so it would travel into the image as stale state. Machinery belongs under the state root.
+        credentials: options.credentials ??
+            fastagentCredentialStore(options.auth?.path, { warn: options.warn, fallbackPath: options.auth?.fallback }),
+        modelsPath: models?.path ?? null,
+        // MUST be set whenever modelsPath is: pi defaults this to `<dirname(modelsPath)>/models-store.json`, which would
+        // write a generated cache INTO the author's agent dir.
         ...(agentDir
             ? { modelsStorePath: join(options.stateRoot ?? resolveStateRoot(agentDir), "models-store.json") }
             : {}),
         allowModelNetwork: false,
     });
-    // A malformed models.json does NOT throw upstream — `create` resolves with the built-ins and parks the
-    // reason in getError(). Left unread, a typo'd endpoint would silently degrade to "provider not in
-    // registry" at model-resolution time, i.e. the silent fallback this codebase forbids. The upstream
-    // message already names both the reason and the file, so it is surfaced verbatim.
+    // A malformed models.json does NOT throw upstream — `create` resolves with the built-ins and parks the reason in
+    // getError().
     const error = runtime.getError();
-    if (error)
-        throw new Error(error);
+    if (error) {
+        const origin = models?.merged
+            ? `\n\nThat file merges ${models.merged.machine} with ${models.merged.definition} (the agent's own wins a provider id).`
+            : "";
+        throw new Error(`${error}${origin}`);
+    }
     for (const provider of options.providers ?? [])
         runtime.registerNativeProvider(provider);
     return runtime;
 }
-/**
- * How a model's credential will REACH a deployed agent — the question `deploy` asks, which
- * {@link probeAuthSource} cannot answer: it flattens every models.json endpoint to the display label
- * "configured API key", so a self-hosted endpoint looks credential-less to the deploy gate even when
- * its key is sitting in an env var.
- *
- * - `envVar`: an environment variable backs it, BY NAME — the shape `deploy` already understands, so
- *   the value carries as a host secret with no extra declaration from the author.
- * - `inDefinition`: the definition itself carries it (a literal `apiKey`, or a `!command` run on the
- *   host). Nothing for `deploy` to carry — and nothing to gate on either, which is the point: the
- *   `fastagent login` remedy is meaningless for a provider login cannot serve.
- *
- * Neither set = a stored credential or nothing at all; the existing auth.json / gate paths decide.
- */
+/** How a model's credential will REACH a deployed agent. */
 export function modelCredentialCarry(runtime, spec) {
     const status = runtime.getProviderAuthStatus(providerOf(spec));
     if (!status.configured)
         return { inDefinition: false };
-    // An env-var name is only useful downstream if it IS one: `"${A}_${B}"` interpolation resolves from
-    // the environment but has no single name to carry, so it falls through to the definition-carried
-    // branch, where the author's `deploy.secrets` is the mechanism.
+    // An env-var name is only useful downstream if it IS one.
     if (status.source === "environment" && status.label && /^[A-Z][A-Z0-9_]*$/.test(status.label)) {
         return { envVar: status.label, inDefinition: false };
     }
     return { inDefinition: status.source !== "stored" };
 }
 /**
- * Probe every provider's auth once (auth is provider-scoped, so any of its models works as the probe)
- * — the status map behind the first-run model picker (`fastagent dev`/`start`/`invoke` with no model
- * set). The picker shows the FULL catalog annotated with these statuses, so "what fastagent supports"
- * and "what is authenticated on this machine" stay distinguishable; a needs-login choice triggers an
- * inline `loginFlow`. Providers with no models are omitted (nothing to pick).
+ * EVERY provider whose `models.json` entry writes its key as a LITERAL rather than a `"$NAME"` reference or a
+ * `"!cmd"`. The file ships inside the image, so a literal there is a credential in a readable layer.
+ *
+ * Read from the FILE, not from `getProviderAuthStatus`: that answers "what satisfies this provider right now" and
+ * returns `stored` first, so a provider that has both an `auth.json` entry and a literal in the file would report
+ * `stored` and the literal would go unreported. The question is what the definition DECLARES, and only the file
+ * answers it. The three-way split mirrors pi's `configuredRequestAuthStatus`, which is not exported.
+ *
+ * The caller WARNS on this; it does not refuse. Whether a given string is a credential is the author's knowledge,
+ * not the framework's — pi's own docs prescribe `"apiKey": "ollama"` for a keyless local server, and no static rule
+ * separates that from a leaked key (an endpoint's reachability is not decidable from its URL either). FastAgent
+ * gates what IT causes; what the author wrote into their own committed file, it reports.
+ */
+export async function literalKeyProviders(agentDir) {
+    const file = join(agentDir, AGENT_MODELS_FILE);
+    let raw;
+    try {
+        raw = await readFile(file, "utf8");
+    }
+    catch (error) {
+        // No custom endpoints is the normal case; anything else (unreadable, a directory) is the caller's problem.
+        if (error.code === "ENOENT")
+            return [];
+        throw error;
+    }
+    // Malformed JSON already threw out of createPiModelRuntime before this runs, so a parse failure here would be a
+    // genuine surprise and must not be swallowed.
+    const providers = JSON.parse(raw).providers ?? {};
+    return Object.entries(providers)
+        .filter(([, provider]) => isLiteralKey(provider?.apiKey))
+        .map(([id]) => id);
+}
+/**
+ * `!cmd` runs on the box; `$NAME` / `${NAME}` reads the environment; anything else is the key itself.
+ *
+ * `$$` is pi's escape for a literal `$`, so it is removed BEFORE looking for a reference — otherwise `"sk$$abc"`
+ * (which resolves to the literal `sk$abc`) would read as a reference and go unmentioned.
  */
+function isLiteralKey(apiKey) {
+    if (typeof apiKey !== "string" || apiKey === "" || apiKey.startsWith("!"))
+        return false;
+    return !/\$\{?[A-Za-z_]/.test(apiKey.replaceAll("$$", ""));
+}
+export function interactiveLoginKind(p) {
+    if (interactiveAuth(p, "oauth"))
+        return "oauth";
+    return interactiveAuth(p, "api_key") ? "api_key" : "none";
+}
+/** THE rule for "can this method be signed in to interactively": the auth to run for it, or undefined. */
+export function interactiveAuth(provider, method) {
+    return method === "oauth" ? provider.auth.oauth : provider.auth.apiKey?.login ? provider.auth.apiKey : undefined;
+}
+/** The providers a sign-in can target: pi's built-ins plus `extra`, composed exactly as {@link createPiModels} does. */
+export function loginProviders(extra) {
+    return piModelsOver(new InMemoryCredentialStore(), extra).getProviders();
+}
+/** Probe every provider's auth once (auth is provider-scoped, so any of its models works as the probe). */
 export async function providerAuthStatuses(models) {
     const statuses = new Map();
     for (const provider of models.getProviders()) {
@@ -120,12 +238,7 @@ export async function providerAuthStatuses(models) {
     }
     return statuses;
 }
-/**
- * Which source currently satisfies auth for `spec` — a startup diagnostic. Returns the upstream
- * `AuthResult.source` label: `"OAuth"` for a stored OAuth credential (e.g. a logged-in openai-codex),
- * `"stored credential"` for a stored API key, an env-var name like `"ANTHROPIC_API_KEY"` for env, or
- * undefined when unconfigured. Reporting-only; never throws.
- */
+/** Which source currently satisfies auth for `spec` — a startup diagnostic. */
 export async function probeAuthSource(models, spec) {
     const slash = spec.indexOf("/");
     if (slash < 1)
@@ -136,15 +249,8 @@ export async function probeAuthSource(models, spec) {
     const auth = await models.getAuth(model).catch(() => undefined);
     return auth?.source;
 }
-/**
- * Quick-fail probe for a just-stored API key: one minimal real request through the standard auth
- * resolution path (the same path invokes take), so a mistyped key surfaces at login time, not at the
- * first turn. `complete` reports provider errors as `stopReason: "error"` rather than throwing; the
- * HTTP status arrives via `onResponse` — when a provider path never calls it (SDK transports), fall
- * back to a conservative "401" match in the error text. Short timeout, no retries: feedback speed
- * over transient-failure tolerance (a transient lands on `unknown`, which keeps the key).
- */
-export async function probeApiKey(models, model) {
+/** Quick-fail probe for a just-stored API key. */
+export async function probeApiKey(models, model, signal) {
     let status;
     let reply;
     try {
@@ -152,6 +258,7 @@ export async function probeApiKey(models, model) {
             maxTokens: 16,
             timeoutMs: 15_000,
             maxRetries: 0,
+            ...(signal ? { signal } : {}),
             onResponse: (r) => {
                 status = r.status;
             },

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

@@ -1,54 +1,58 @@
 import type { Agent } from "../../agent.ts";
-import { type FastagentConfig } from "./config.ts";
-import type { SessionControl } from "../../session.ts";
+import { type AuthLayers, type FastagentConfig } from "./config.ts";
+import type { AgentCommand, SessionControl } from "../../session.ts";
 import type { SessionObserver } from "./turn-kit.ts";
-import type { ModuleLoadFailure } from "../../loader.ts";
 import { type LoadedDefinition } from "./definition.ts";
+import type { ModelRuntime } from "@earendil-works/pi-coding-agent";
+import type { FastagentAuthOptions } from "./auth.ts";
 import { type PiSessionRecordStore } from "./session-store.ts";
 import type { ToolCollision, MountedTool } from "./tool.ts";
+import type { DeclaredSecret } from "../../declared-secrets.ts";
+import type { HttpSurface } from "../../service.ts";
+/**
+ * The names a `/` composer completes: this agent's skills — the definition's, plus the ones its machine lends
+ * (machine.ts) —, the commands its `extensions/` register, and the machine's prompt templates.
+ *
+ * `source` says how a name is INVOKED, which is the one thing a client needs from it: a `skill` is sent as
+ * `/skill:<name>`, an `extension` command and a `prompt` as `/<name>` (docs/design/session-control.md §5.1.1).
+ *
+ * The definition is read live, like every turn reads it; the machine is the process's one read, the same snapshot a
+ * bound session runs on, so the menu cannot offer a name the next prompt would not expand. The same holds for
+ * extensions: `served` is what sessions load — the assembly's entry points, discovered once, and the runtime turns run
+ * on (asked only when there are extensions) — never a fresh scan of `extensions/`.
+ */
+export declare function agentCommands(agentDir: string, workspace: string, served: {
+    extensionPaths: readonly string[];
+    modelRuntime: () => Promise<ModelRuntime>;
+}): Promise<AgentCommand[]>;
 export interface CreatePiAgentFromDirOptions {
-    /** Model spec override (e.g. the CLI --model flag). Precedence: this > FASTAGENT_MODEL > config.model. */
+    /** Model spec override (e.g. the CLI --model flag). */
     model?: string;
     /**
-     * Session store directory. Default `<agentDir>/.state/sessions` (machine state). `start`
-     * overrides it (--sessions-dir / FASTAGENT_SESSIONS_DIR / a mounted volume) so production continuity
-     * survives redeploys.
+     * Where conversations are stored, for an EMBEDDER that puts them somewhere the state root does not cover. There is
+     * no env or flag spelling of it: sessions are machine state, and the one knob that moves machine state is
+     * `FASTAGENT_STATE_DIR` (see {@link resolveSessionsDir}).
      */
     sessionsDir?: string;
-    /**
-     * Credentials file override. Default `<agentDir>/.secrets/auth.json` (project-level, under the
-     * `.secrets/`). Override via --auth-path / FASTAGENT_AUTH_PATH; point it at
-     * the global `~/.fastagent/.secrets/auth.json` to share one credential across projects.
-     */
+    /** Credentials file override. */
     authPath?: string;
     /**
-     * This is a long-running SERVE (`dev`/`start`), where the scheduler poller runs — so a self-scheduled
-     * wake-up is actually honored. One-shot entries (`invoke`/`fire`) leave it off (they exit after the turn
-     * and never poll). The built-in `wake` tool mounts only when this is set AND `config.selfSchedule` is on.
+     * This is a long-running SERVE (`dev`/`start`), where the scheduler poller runs — so a self-scheduled wake-up is
+     * actually honored.
      */
     serving?: boolean;
-    /** Assemble the session control plane over this agent's session store and return it as
-     *  {@link sessionControl} — the store is created inside this opener, so the hub must be wired
-     *  here too (an external `createPiSessionControl` cannot exist before the store does).
-     *  Default: `config.sessionControl` AND {@link serving} — the config key means "serve the control
-     *  plane", so one-shot commands (invoke/fire) do not assemble an unused hub. Pass explicitly to
-     *  override either way. */
+    /**
+     * Wire the control plane's BOUNDARY (model changes, fork, delete) and publish it. A serve always gets the hub
+     * itself — stopping the running turn is a chat command, not a management endpoint — so this is the answer to
+     * "may a remote caller steer and rewrite this deployment", nothing else. Defaults to `config.sessionControl`.
+     */
     sessionControl?: boolean;
-    /** Additional raw tap with the FULL vocabulary: run events composed after the
-     *  {@link sessionControl} hub's observer, plus the hub's own boundary-mutation events
-     *  (`state_changed`/`compaction_*`) via the hub's tap. TRUSTED seam: an observer receives each
-     *  run's live modulation handles (see `SessionObserver`) — for read-only consumers
-     *  use the hub's `events()` stream instead. */
+    /** Additional raw tap with the FULL vocabulary. */
     observer?: SessionObserver;
 }
 /**
- * The agent assembly FRONT HALF — everything that is independent of how pi consumes the
- * definition (a per-invoke session for serving vs a resident one for chat):
- * placement resolution → config → model spec → the full tool surface ({@link resolveAgentTools} — the
- * ONE place it is computed) → state root → auth path. Both {@link createPiAgentFromDir} and the
- * session builder (session-builder.ts) consume this, so THESE inputs cannot drift between the two
- * consumption shapes. (Definition loading and prompt assembly stay per-consumer: serving re-reads
- * them live per invoke, the session builder snapshots at startup and lets pi append skills/env.)
+ * The agent assembly FRONT HALF — everything that is independent of how pi consumes the definition (a per-invoke
+ * session for serving vs a resident one for chat).
  */
 export interface AgentAssembly {
     config: FastagentConfig;
@@ -57,29 +61,39 @@ export interface AgentAssembly {
     modelSpec: string;
     /** Absolute agent dir — definition + config + machinery live here (resolvePlacement().agentDir). */
     agentDir: string;
-    /** Absolute workspace — the agent's cwd and the start of the ②-context walk: the agent dir's parent
-     *  when the agent sits inside it, the agent dir ITSELF when you point at the agent. */
+    /** Absolute workspace — the agent's cwd and the start of the ②-context walk. */
     workspace: string;
     /** Absolute state root (FASTAGENT_STATE_DIR > <agentDir>/.state). */
     stateRoot: string;
-    /** Absolute credentials file (--auth-path/authPath option > FASTAGENT_AUTH_PATH > <agentDir>/.secrets/auth.json). */
-    authPath: string;
+    /** The credentials files it reads ({@link resolveAuthLayers}). */
+    auth: AuthLayers;
     /** The full mounted tool surface (all coding tools + config.tools + discovered tools/, search_tools applied). */
     tools: MountedTool[];
     toolNames: string[];
     deferredToolNames: string[];
     toolCollisions: ToolCollision[];
-    toolFailures: ModuleLoadFailure[];
+    /** Env vars the mounted tools declared, by tool name — already asserted present by this function. */
+    toolSecrets: Map<string, DeclaredSecret[]>;
 }
 export declare function resolveAgentAssembly(dir: string, options?: {
     model?: string;
     authPath?: string;
 }): Promise<AgentAssembly>;
 /**
- * "Point at a directory → agent": resolve the placement (`dir` may be either end — the workspace or
- * the agent dir itself), load the config, resolve model and tools, then L2. Throws a clear error when
- * no model source is set (fail visibly at startup). Returns everything an entry point needs to report
- * what it assembled.
+ * The model specs `createPiAgentFromDir(dir, { authPath })` could run now: the agent's registry (pi's built-ins plus
+ * its `models.json`) filtered to the providers whose credentials are configured, sorted. The directory needs no model
+ * set, and the same placement and credential layers as the opener apply, so a listed spec authenticates there.
+ * Configuration is checked, not validity: no OAuth token is refreshed and no provider is called.
+ *
+ * `warn` reaches the credential store. An unreadable or corrupt credentials file otherwise reads as "nothing
+ * configured", so a client that must not show that as an empty list passes a sink that throws.
+ */
+export declare function availableModelsFromDir(dir: string, options?: FastagentAuthOptions & {
+    authPath?: string;
+}): Promise<string[]>;
+/**
+ * "Point at a directory → agent": resolve the placement (`dir` may be either end — the workspace or the agent dir
+ * itself), load the config, resolve model and tools, then L2.
  */
 export declare function createPiAgentFromDir(dir: string, options?: CreatePiAgentFromDirOptions): Promise<{
     agent: Agent;
@@ -96,21 +110,19 @@ export declare function createPiAgentFromDir(dir: string, options?: CreatePiAgen
     stateRoot: string;
     /** Absolute session store directory in use (for the startup report). */
     sessionsDir: string;
-    /** Absolute credentials file in use (for the startup report). */
-    authPath: string;
-    /** The session store in use. */
+    /** The credentials files in use — the startup report names whichever layer the credential came from. */
+    auth: AuthLayers;
     sessions: PiSessionRecordStore;
-    /** The observation plane over this agent's sessions; present iff `options.sessionControl`. */
+    /** The observation plane over this agent's sessions; present on every serve (a channel's stop command reaches the
+     *  live run through it). Its boundary is wired only when {@link publishControl}. */
     sessionControl?: SessionControl;
-    /** Whether the agent schedules its own follow-up turns — read from the config, so a caller
-     *  assembling a service does not have to reach back into it (MountableAgent). */
-    selfSchedule: boolean;
-    /** Non-default, active-by-default tool names in effect: config.tools + discovered tools/. Each name
-     *  lives in exactly one report slot — deferred names are in {@link deferredToolNames} instead. */
+    /** Whether that plane is also served as `/control/*` — `config.sessionControl`. */
+    publishControl: boolean;
+    /** What the serve publishes — `config.http`, handed to the assembly as-is (MountableAgent). */
+    http?: HttpSurface;
+    /** Non-default, active-by-default tool names in effect: config.tools + discovered tools/. */
     toolNames: string[];
     /** Tools registered but not initially active (deferred) — activated via search_tools. */
     deferredToolNames: string[];
     toolCollisions: ToolCollision[];
-    /** `tools/` files that failed to import — skipped, reported by the caller, never fatal. */
-    toolFailures: ModuleLoadFailure[];
 }>;