@fastagent-sh/fastagent 0.22.1 → 0.24.0

package/dist/deploy/secrets.js

@@ -30,7 +30,7 @@ const DEPLOY_OWNED = new Set([
 ]);
 /** Is `name` one the deployment sets itself (see {@link DEPLOY_OWNED}), including the chunked carriers? */
 function isDeployOwned(name) {
-    return DEPLOY_OWNED.has(name) || /^FASTAGENT_(AUTH_SEED|ENV)(_\d+)?$/.test(name);
+    return DEPLOY_OWNED.has(name) || /^FASTAGENT_ENV(_\d+)?$/.test(name);
 }
 /** The value-file variables that travel: everything with a value that the deployment does not set itself. */
 function carriedValues(values) {
@@ -59,36 +59,25 @@ export function deploymentSecrets(modelAuth, declared, values, valueFile) {
     return secrets;
 }
 /**
- * Assemble the VALUES a `--run` deploy sets on the host: every variable the value file carries, plus the local
- * credential. Never minted here.
+ * Assemble the VALUES a `--run` deploy sets on the host: every variable the value file carries. Never minted here.
  *
  * `values` is the selected value file, read as data — **the environment running `deploy` is not a source**. A
  * deployment must be reproducible from what it carries, and a variable that happens to be exported on the builder is
  * written down nowhere. CI supplies values by writing the file before running the command.
+ *
+ * No credentials file travels: a model that does not authenticate through a variable (or its own definition) logs in
+ * on the deployment itself (`fastagent login --deployment`), so the box is the only holder of its grant.
  */
 export function assembleSecrets(input) {
     const secrets = carriedValues(input.values);
     const missingSecrets = [];
-    let needsModelCredential = false;
-    if (isEnvKey(input.modelAuth)) {
-        if (!secrets[input.modelAuth])
-            missingSecrets.push(input.modelAuth); // `.env` remediation fits
-    }
-    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.
-    }
-    else {
-        needsModelCredential = true; // no env key, no auth.json — `fastagent login` remediation
-    }
+    if (isEnvKey(input.modelAuth) && !secrets[input.modelAuth])
+        missingSecrets.push(input.modelAuth);
     for (const { name } of dedupeSecrets(input.declared ?? [])) {
         if (!secrets[name] && !missingSecrets.includes(name))
             missingSecrets.push(name);
     }
-    return { secrets, missingSecrets, needsModelCredential };
+    return { secrets, missingSecrets };
 }
 /**
  * The ONE refusal for declared names the deployed environment does not supply a value for — every host reaches it
@@ -101,10 +90,6 @@ export function missingValuesGate(missing, valueFile) {
     return (`no value for: ${missing.join(", ")} — the deployed environment is declared by ${valueFile}, and this deploy ` +
         `reads only that file (exporting the variable here does not reach the deployment). Add them there and re-run`);
 }
-/** The bytes to seed to the auth file, or undefined to leave it alone. */
-export function authSeedBytes(seed, fileExists) {
-    return !seed || fileExists ? undefined : Buffer.from(seed, "base64");
-}
 /**
  * Collect a (possibly CHUNKED) carrier from the environment: `<name>` plus numbered continuations (`_2`, `_3`, …)
  * concatenated in order. A host whose env values have a length cap splits a long value this way.
@@ -122,10 +107,6 @@ function collectChunked(env, name) {
     }
     return value;
 }
-/** `FASTAGENT_AUTH_SEED` (+ `_2`, …): the base64 auth.json a deploy carries. */
-export function collectAuthSeed(env) {
-    return collectChunked(env, "FASTAGENT_AUTH_SEED");
-}
 /**
  * `FASTAGENT_ENV` (+ `_2`, …): the carried variables as ONE base64 JSON object, for a host whose deployment artifact
  * must not depend on which names the value file holds (AgentCore's template is committed and gated on drift). The

package/dist/dev-supervisor.js

@@ -5,7 +5,7 @@
 import { spawn } from "node:child_process";
 import { relative, sep } from "node:path";
 import { watch as watchTree } from "chokidar";
-import { AGENT_CONFIG_FILE, AGENT_MODELS_FILE, resolveStateRoot, isUnderDir } from "./paths.js";
+import { AGENT_CONFIG_FILE, AGENT_MODEL_CATALOG_FILE, AGENT_MODELS_FILE, resolveStateRoot, isUnderDir, } from "./paths.js";
 import { dotEnvPath } from "./env.js";
 import { log } from "./log.js";
 import { openExternalUrl } from "./open-url.js";
@@ -14,7 +14,7 @@ import { announceWebhooks, startCloudflareTunnel } from "./tunnel.js";
 /** What the dev watcher restarts on (agent-dir-relative): the process-bound code inputs only. */
 /** The agent-dir directories loaded ONCE per worker: a restart is their only re-read. */
 const CODE_INPUT_DIRS = ["tools", "channels", "routines", "extensions"];
-const WATCHED_HINT = `${CODE_INPUT_DIRS.map((dir) => `${dir}/`).join(", ")}, package.json, fastagent.config.ts, models.json, .secrets/.env`;
+const WATCHED_HINT = `${CODE_INPUT_DIRS.map((dir) => `${dir}/`).join(", ")}, package.json, fastagent.config.ts, models.json, models-store.json, .secrets/.env`;
 /** chokidar `ignored` matcher for the narrow watch scope (true = ignore), rooted at the AGENT DIR. */
 export function devWatchIgnored(root, envFile) {
     // The `.env` is allow-listed by its RESOLVED path, not by the `.secrets` name.
@@ -29,10 +29,13 @@ 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.
+        // models.json is read ONCE per worker (agentModels' snapshot, which every session's runtime is built from), so an
+        // edit needs a restart like any other code input.
         if (rel === AGENT_MODELS_FILE)
             return false;
+        // So is the model catalog: a `models --refresh` during `dev` restarts the worker onto the new models.
+        if (rel === AGENT_MODEL_CATALOG_FILE)
+            return false;
         const segments = rel.split(sep);
         if (CODE_INPUT_DIRS.includes(segments[0]))
             return false;

package/dist/engines/pi/agent-models.d.ts

@@ -0,0 +1,83 @@
+/**
+ * An agent's MODEL ENVIRONMENT as one value: the credential store its turns authenticate through, the registry they
+ * resolve models against, and what authenticates a provider there. Every reader builds it through {@link agentModels}
+ * — the opener and L2, the startup report and a deployed box's `login --if-missing`, `info`, the first-run picker,
+ * login, the model list — so none of them can read other credential layers or another registry than the runtime
+ * does. Each used to compose these parts itself, and two of those copies drifted from the rule (#636, #660).
+ */
+import type { ExecutionEnv } from "@earendil-works/pi-agent-core";
+import type { Credential, CredentialStore, Models, Provider } from "@earendil-works/pi-ai";
+import { ModelRuntime } from "@earendil-works/pi-coding-agent";
+import { type AuthLayers, type CredentialSourceOptions, type FastagentAuthOptions } from "./auth.ts";
+/** What authenticates one provider for an agent ({@link AgentModels.authStatus}). */
+interface AuthStatus {
+    /** What satisfies it now (`OAuth`, `stored credential`, an env variable's name), after a due refresh. */
+    source?: string;
+    /** Why resolving it failed (a corrupt entry, a refresh the provider refused), when it did. */
+    error?: string;
+    /** The file that holds the stored credential, or the one a login would write; absent over a caller's store. */
+    path?: string;
+    /** The kind of credential the store holds for it, usable or not. */
+    stored?: Credential["type"];
+    /**
+     * An env variable that also authenticates it but goes unused, because pi lets a stored credential own its provider
+     * — a key added to a deployment's value file after the box was logged in, typically.
+     */
+    shadowed?: string;
+}
+export interface AgentModels {
+    /** The credentials files behind {@link credentials}; absent when the caller supplied its own store. */
+    auth?: AuthLayers;
+    credentials: CredentialStore;
+    /**
+     * The registry: pi's built-ins, plus (with a directory) the agent's `models.json` and model catalog over the
+     * machine's, plus `providers` and extension model declarations. An unbound catalog, built on first use and shared
+     * after; session bindings use createRuntime and their own extension instances.
+     */
+    runtime(): Promise<ModelRuntime>;
+    /** A session-local registry, before its extensions are loaded. Credentials remain shared. */
+    createRuntime(): Promise<ModelRuntime>;
+    /**
+     * What authenticates `provider` here, resolved exactly as a turn resolves it: the ONE answer the startup report and a
+     * deployed box's `login --if-missing` both give. `modelId` picks the model to probe with; the provider's first one
+     * otherwise (auth is provider-scoped).
+     */
+    authStatus(provider: string, modelId?: string): Promise<AuthStatus>;
+    /**
+     * The definition's extension entry points, discovered once: what this catalog registers models from and what every
+     * session of the assembly built over it loads. Empty without a directory.
+     */
+    extensionPaths(): Promise<readonly string[]>;
+}
+export interface AgentModelsOptions {
+    /** Workspace for extension model registration; defaults to agentDir for standalone definitions. */
+    cwd?: string;
+    /** Where `extensions/` is listed from; Node's filesystem by default. */
+    env?: ExecutionEnv;
+    /** Extra providers registered on top of the built-ins (a same id replaces one). */
+    providers?: readonly Provider[];
+    /**
+     * Layer the machine's models.json and model catalog under the agent's (default). Off for the registry a DEPLOYED
+     * agent has, since neither ships.
+     */
+    machineLayer?: boolean;
+}
+/**
+ * The model environment of the agent in `agentDir` (or, without one, of a caller with no directory: pi's built-ins
+ * over the named or global credentials file). A supplied `credentialStore` is used as given; otherwise the files:
+ * the directory's own layers ({@link resolveAuthLayers}), or the named file or the global one.
+ */
+export declare function agentModels(agentDir: string | undefined, source?: {
+    authPath?: string;
+    credentialStore?: undefined;
+} & FastagentAuthOptions, options?: AgentModelsOptions): AgentModels & {
+    auth: AuthLayers;
+};
+export declare function agentModels(agentDir: string | undefined, source?: CredentialSourceOptions & FastagentAuthOptions, options?: AgentModelsOptions): AgentModels;
+export interface CreatePiModelsOptions extends FastagentAuthOptions, CredentialSourceOptions {
+    /** Extra providers registered on top of the built-ins (same id overrides a built-in). */
+    providers?: Provider[];
+}
+/** A `Models` with every built-in pi provider, wired to fastagent's auth. */
+export declare function createPiModels(options?: CreatePiModelsOptions): Models;
+export {};

package/dist/engines/pi/agent-models.js

@@ -0,0 +1,120 @@
+import { ModelRuntime } from "@earendil-works/pi-coding-agent";
+import { definitionServices } from "./agent-session-factory.js";
+import { loadExtensionPaths } from "./definition.js";
+import { GLOBAL_AUTH_PATH, assertOneCredentialSource, fastagentCredentialStore, resolveAuthLayers, } from "./auth.js";
+import { createPiModelRuntime, environmentAuthSource, modelRuntimeFiles, piModelsOver, probeAuthSource, } from "./models.js";
+export function agentModels(agentDir, source = {}, options = {}) {
+    assertOneCredentialSource(source);
+    const { providers, machineLayer } = options;
+    const files = source.credentialStore
+        ? undefined
+        : agentDir
+            ? resolveAuthLayers(agentDir, source.authPath)
+            : { path: source.authPath ?? GLOBAL_AUTH_PATH };
+    // The model files, read once for every runtime this agent builds: a session's and the control plane's.
+    let modelFiles;
+    const readModelFiles = () => (modelFiles ??= modelRuntimeFiles({
+        ...(agentDir ? { agentDir } : {}),
+        ...(machineLayer !== undefined ? { machineLayer } : {}),
+    }));
+    const store = files
+        ? agentCredentialStore(files, readModelFiles, { providers, warn: source.warn })
+        : undefined;
+    const credentials = source.credentialStore ?? store;
+    const createRuntime = async () => createPiModelRuntime({
+        credentials,
+        files: await readModelFiles(),
+        ...(agentDir ? { agentDir } : {}),
+        ...(providers ? { providers } : {}),
+        ...(machineLayer !== undefined ? { machineLayer } : {}),
+    });
+    const cwd = options.cwd ?? agentDir;
+    let discovered;
+    const extensionPaths = () => (discovered ??= agentDir
+        ? loadExtensionPaths(agentDir, { ...(cwd ? { cwd } : {}), ...(options.env ? { env: options.env } : {}) })
+        : Promise.resolve([]));
+    let registry;
+    const runtime = () => {
+        registry ??= createRuntime().then(async (models) => {
+            if (agentDir) {
+                await definitionServices({
+                    cwd: cwd ?? agentDir,
+                    modelRuntime: models,
+                    definition: { skills: [] },
+                    extensionPaths: await extensionPaths(),
+                });
+            }
+            return models;
+        });
+        return registry;
+    };
+    return {
+        ...(files ? { auth: files } : {}),
+        credentials,
+        runtime,
+        createRuntime,
+        extensionPaths,
+        async authStatus(provider, modelId) {
+            const models = await runtime();
+            const id = modelId ?? models.getProvider(provider)?.getModels()[0]?.id;
+            let resolved = {};
+            if (id !== undefined) {
+                try {
+                    const found = await probeAuthSource(models, `${provider}/${id}`);
+                    if (found !== undefined)
+                        resolved = { source: found };
+                }
+                catch (error) {
+                    // The first line: pi folds the request's stack into the message of a failed refresh.
+                    resolved = { error: String(error.message).split("\n")[0] };
+                }
+            }
+            // `read` never refreshes: this is the kind on file, whatever became of it.
+            const stored = (await credentials.read(provider))?.type;
+            const fromEnvironment = stored === undefined ? undefined : await environmentAuthSource(provider, process.env);
+            const shadowed = resolved.source !== undefined && fromEnvironment !== resolved.source ? fromEnvironment : undefined;
+            return {
+                ...(store ? { path: await store.layerOf(provider) } : {}),
+                ...resolved,
+                ...(stored !== undefined ? { stored } : {}),
+                ...(shadowed !== undefined ? { shadowed } : {}),
+            };
+        },
+    };
+}
+/** A `Models` with every built-in pi provider, wired to fastagent's auth. */
+export function createPiModels(options = {}) {
+    return piModelsOver(agentModels(undefined, options).credentials, options.providers);
+}
+/**
+ * The credential store an agent reads through: its own file, then the user-global one for a provider the PROJECT
+ * authenticates no other way (its own auth file, a models.json key, or the environment). "No other way" is answered
+ * by pi's own resolution over a registry that has no global layer, built the first time a provider is looked up
+ * there. A deployment never has the global file, so a global login that outranked, say, an `ANTHROPIC_API_KEY` in
+ * `.secrets/.env` would run one credential here and a different one deployed.
+ */
+function agentCredentialStore(auth, modelFiles, options) {
+    const { warn, providers = [] } = options;
+    const fallback = auth.fallback;
+    if (fallback === undefined)
+        return fastagentCredentialStore(auth.path, { warn });
+    let project;
+    const projectRuntime = () => {
+        project ??= (async () => {
+            const runtime = await ModelRuntime.create({
+                credentials: fastagentCredentialStore(auth.path, { warn }),
+                ...(await (await modelFiles()).create()),
+                refreshOnCreate: false,
+            });
+            for (const provider of providers)
+                runtime.registerNativeProvider(provider);
+            return runtime;
+        })();
+        return project;
+    };
+    return fastagentCredentialStore(auth.path, {
+        warn,
+        fallbackPath: fallback,
+        projectAuthenticates: async (providerId) => (await (await projectRuntime()).checkAuth(providerId)) !== undefined,
+    });
+}

package/dist/engines/pi/agent-session-factory.d.ts

@@ -3,7 +3,7 @@ import type { Skill, ThinkingLevel } from "@earendil-works/pi-agent-core";
 import { type AgentSession, type AgentSessionServices, type CompactionResult, type CreateAgentSessionServicesOptions, type ModelRuntime, type ResolvedCommand, SessionManager, createAgentSessionFromServices } from "@earendil-works/pi-coding-agent";
 import type { PiAgentSessionFactory } from "./invoke-session.ts";
 import type { PiSessionRecordStore } from "./session-store.ts";
-import { type MountedTool } from "./tool.ts";
+import type { MountedTool } from "./tool.ts";
 import { type AnyModel } from "./models.ts";
 interface PiSessionDefinition {
     systemPrompt?: string;
@@ -12,11 +12,12 @@ interface PiSessionDefinition {
 export interface PiAgentSessionFactoryOptions {
     /** Where conversations live. */
     sessions: PiSessionRecordStore;
-    /** The model to run and the hub that authenticates it, resolved on FIRST USE and kept. */
+    /** A fresh model runtime per binding: extension routers and provider registrations belong to this session. */
     engine: () => Promise<{
         modelRuntime: ModelRuntime;
-        model: AnyModel;
     }>;
+    /** Resolved after extensions register their models. */
+    modelSpec: string;
     thinkingLevel?: ThinkingLevel;
     tools?: MountedTool[];
     /** Read once per binding; prompt and skills come from the same definition read. */
@@ -42,19 +43,11 @@ export interface BindPiSessionOptions {
     excludedToolNames?: readonly string[];
     /** The CALLER's session id — what a tool asking which conversation it is in hears. */
     sessionId?: string;
-    /** Record each discovered activation on the session, so the next bind restores it. */
-    recordActivations: boolean;
 }
 /**
- * Bind ONE pi session to a record: the definition's tools as pi definitions over one turn context, pi's own tool
- * copies kept off, and deferral applied.
+ * Bind ONE pi session to a record: authored tools replace same-name built-ins; Pi owns exposure and discovery.
  */
 export declare function bindPiSession(options: BindPiSessionOptions): ReturnType<typeof createAgentSessionFromServices>;
-/**
- * Announce extensions pi failed to load. pi collects them into `LoadExtensionsResult.errors` and carries on with the
- * rest.
- */
-export declare function reportExtensionErrors(services: AgentSessionServices): void;
 /** What pi is allowed to discover, minus the parts each assembly fills in itself. */
 type DefinitionLoaderOptions = NonNullable<CreateAgentSessionServicesOptions["resourceLoaderOptions"]>;
 /** The resource posture a fastagent definition asks pi for — ONE definition of it, for both assemblies. */
@@ -81,9 +74,16 @@ export declare function startCompaction(session: AgentSession, instructions: str
     admission: Promise<CompactAdmission>;
     done: Promise<CompactionResult>;
 };
+/** A fresh loader and Pi's native model registration, over a session-local runtime. */
+export declare function definitionServices(options: {
+    cwd: string;
+    modelRuntime: ModelRuntime;
+    definition: PiSessionDefinition;
+    extensionPaths: readonly string[];
+}): Promise<AgentSessionServices>;
 /**
  * The `/name` commands a served session dispatches, named the way pi resolves them (a name two extensions share gets
- * a `:N` suffix). Loaded through the same {@link servingServices} a turn binds, so the menu and the dispatch cannot
+ * a `:N` suffix). Loaded through the same {@link definitionServices} a turn binds, so the menu and the dispatch cannot
  * disagree. Loading runs the extensions' factories; no session opens, so `session_start` does not fire, and the
  * instances are never bound (any action they call throws).
  */