@fastagent-sh/fastagent 0.24.4 → 0.26.0

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

@@ -1,83 +0,0 @@
-/**
- * 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

@@ -1,120 +0,0 @@
-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

@@ -1,121 +0,0 @@
-import { type Machine } from "./machine.ts";
-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 AnyModel } from "./models.ts";
-import type { DefinitionPrompt } from "./definition.ts";
-/** What one binding reads from the definition: the prompt pieces, skills and prompt templates pi is handed. */
-export interface PiSessionDefinition {
-    /** Replaces pi's default prompt when set (`SYSTEM.md`, L2's `base`, L1's `instructions`); absent → pi's default. */
-    systemPrompt?: string;
-    /** Added after the prompt, whichever it is (`APPEND_SYSTEM.md`). */
-    appendSystemPrompt?: string;
-    /** Project instructions (AGENTS.md); pi renders them as its project context. */
-    contextFiles?: Array<{
-        path: string;
-        content: string;
-    }>;
-    /** FastAgent's own named prompt sections: pi renders them after its own, whoever wrote the rest. */
-    sections?: Record<string, string>;
-    skills: Skill[];
-    /** The definition's own prompt templates; the machine's are added behind them. */
-    prompts?: DefinitionPrompt[];
-}
-export interface PiAgentSessionFactoryOptions {
-    /** Where conversations live. */
-    sessions: PiSessionRecordStore;
-    /** A fresh model runtime per binding: extension routers and provider registrations belong to this session. */
-    engine: () => Promise<{
-        modelRuntime: ModelRuntime;
-    }>;
-    /**
-     * The default model, resolved after extensions register their models. Optional: a session that records a model
-     * runs on it, and one that records none is refused with {@link MissingModel} when there is no default either.
-     */
-    modelSpec?: string;
-    thinkingLevel?: ThinkingLevel;
-    tools?: MountedTool[];
-    /** Read once per binding; prompt and skills come from the same definition read. */
-    readDefinition: () => PiSessionDefinition | Promise<PiSessionDefinition>;
-    /** The agent's working directory — what fastagent-defined tools see as `cwd`. */
-    cwd: string;
-    /** The definition's own extension entry points, loaded fresh for every bound session. */
-    extensionPaths?: string[];
-    /** Built-ins omitted by an explicit lower-level tool list. */
-    excludedToolNames?: readonly string[];
-}
-export interface BindPiSessionOptions {
-    services: AgentSessionServices;
-    sessionManager: SessionManager;
-    /** Chat only: pi's runtime hands the resumed/new session its start event. */
-    sessionStartEvent?: Parameters<typeof createAgentSessionFromServices>[0]["sessionStartEvent"];
-    model: AnyModel;
-    thinkingLevel: ThinkingLevel | undefined;
-    tools: MountedTool[];
-    /** The agent's working directory — what fastagent-defined tools see as `cwd`. */
-    cwd: string;
-    /** Built-ins omitted by an explicit lower-level tool list. */
-    excludedToolNames?: readonly string[];
-    /** The CALLER's session id — what a tool asking which conversation it is in hears. */
-    sessionId?: string;
-}
-/**
- * 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>;
-/** 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. */
-export declare function definitionResourceLoaderOptions(source: {
-    definition: PiSessionDefinition;
-    /** {@link readMachine} for this workspace — resolved by the caller, because this function is synchronous. */
-    machine: Machine;
-    extensionPaths?: readonly string[];
-}): DefinitionLoaderOptions;
-/** Tell a waiting {@link startCompaction} that pi admitted the compaction on this record. */
-export declare function admitCompaction(record: SessionManager): void;
-/** What pi decided before its model call: go ahead, nothing to do, or a failure of its own (in `refused`). */
-export type CompactAdmission = "admitted" | "nothing_to_compact" | {
-    refused: unknown;
-};
-/**
- * Start pi's manual compaction on a bound session. `onAdmitted` runs INSIDE pi's admission event, so everything it
- * publishes precedes anything pi does next (the model call, its retries). `admission` settles before the model call.
- * pi's own pre-admission failures come back as `refused` rather than a rejection: the caller answers them to its
- * Caller as a result. `done` is the compaction itself.
- */
-export declare function startCompaction(session: AgentSession, instructions: string | undefined, onAdmitted: () => void): {
-    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 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).
- */
-export declare function servedExtensionCommands(options: {
-    cwd: string;
-    modelRuntime: ModelRuntime;
-    extensionPaths: readonly string[];
-}): Promise<ResolvedCommand[]>;
-/**
- * Open-or-create the record, then bind a fresh session to it — on a fresh resource loader.
- *
- * ONE LOADER PER SESSION, because pi's extension runtime belongs to its loader: a loader shared across concurrent
- * turns would let one conversation's extension act on another's session. It also makes the definition live with no
- * bookkeeping: every bind reads the prompt and skills this invoke read. The machine's half is the process's one read
- * (machine.ts). Extension CODE is imported once per process, so an edit to `extensions/` needs a restart, which is
- * what `dev` does on one.
- */
-export declare function piAgentSessionFactory(options: PiAgentSessionFactoryOptions): PiAgentSessionFactory;
-export {};