@fastagent-sh/fastagent 0.21.0 → 0.22.0

package/dist/engines/pi/machine.js

@@ -0,0 +1,106 @@
+/**
+ * THE MACHINE an agent runs on, as fastagent inherits it: the skills and prompt templates this box provides — found
+ * by pi's own Agent Skills discovery, installed pi packages included — and pi's engine settings.
+ *
+ * An agent inherits its machine the way it already inherits the `PATH`: `bash` runs whatever is installed, and a
+ * skill in `~/.pi/agent/skills` is available the same way. Deploying ships the project scope — the workspace — and
+ * nothing here is compared against a deployment, the same way nobody is told their local `ffmpeg` is not in the image.
+ *
+ * READ ONCE per process, like the environment it is. The definition is what stays live (`dev` re-reads it per turn,
+ * because it is what an author edits); a skill installed after boot arrives on the next start.
+ */
+import { DefaultPackageManager, DefaultResourceLoader, SettingsManager, getAgentDir, } from "@earendil-works/pi-coding-agent";
+import { log } from "../../log.js";
+/** Keyed by the two places it reads: the workspace (project scope) and pi's own directory (user scope). */
+const reads = new Map();
+/** This process's one read of the machine, shared by the run plane and `commands()` so the two cannot disagree. */
+export function readMachine(workspace) {
+    // pi's own answer for where its user-level resources live — asked, not spelled, since `PI_CODING_AGENT_DIR` moves it.
+    const agentDir = getAgentDir();
+    const key = `${workspace}\u0000${agentDir}`;
+    const cached = reads.get(key);
+    if (cached)
+        return cached;
+    const reading = read(workspace, agentDir);
+    reads.set(key, reading);
+    return reading;
+}
+async function read(workspace, agentDir) {
+    const files = SettingsManager.create(workspace, agentDir);
+    // pi reads an unparseable or locked settings file as `{}` and keeps the error for whoever asks. Nobody did, so a
+    // trailing comma in `~/.pi/agent/settings.json` — or pi's own TUI holding the lock at that moment — left this whole
+    // process on pi's defaults, silently: the read happens once.
+    for (const { scope, path, error } of files.drainErrors()) {
+        log.warn(`[fastagent] pi ${scope} settings${path ? ` (${path})` : ""} could not be read, so pi's defaults apply: ${error.message}`);
+    }
+    // INSTALLED PACKAGES, NEVER AN INSTALL. pi's loader resolves `packages` itself and installs a missing one
+    // (`npm install`, `git clone`), throwing out of `reload()` when that fails — measured. So fastagent resolves them
+    // here, telling pi to skip what is absent, and hands the loader a packageless copy of the settings so its own
+    // resolve has nothing to do.
+    const manager = new DefaultPackageManager({ cwd: workspace, agentDir, settingsManager: files });
+    const packages = await manager.resolve(async () => "skip");
+    // A package skipped is said, once: its skills would otherwise just not be there. Asked of the configured list, not
+    // of `onMissing` — pi never calls that under `PI_OFFLINE`, so the warning would vanish exactly when offline.
+    for (const { source } of manager.listConfiguredPackages().filter((configured) => !configured.installedPath)) {
+        log.warn(`[fastagent] pi package ${source} is not installed, so its skills and prompts are not loaded`);
+    }
+    const settings = {
+        global: withoutPackages(files.getGlobalSettings()),
+        project: withoutPackages(files.getProjectSettings()),
+    };
+    const loader = new DefaultResourceLoader({
+        cwd: workspace,
+        agentDir,
+        settingsManager: scopedSettings(settings),
+        additionalSkillPaths: fromPackages(packages.skills),
+        additionalPromptTemplatePaths: fromPackages(packages.prompts),
+        // The machine's extensions are its owner's setup, not this agent's (agent-session-factory.ts loads only the
+        // definition's own); context files are fastagent's own (segment ②).
+        noExtensions: true,
+        noContextFiles: true,
+    });
+    await loader.reload();
+    const { skills, diagnostics: skillDiagnostics } = loader.getSkills();
+    const { prompts, diagnostics: promptDiagnostics } = loader.getPrompts();
+    // Said once — this is the process's only read. A `SKILL.md` with no description, or a prompt template whose
+    // frontmatter does not parse, is otherwise simply absent.
+    for (const [kind, diagnostics] of [
+        ["skill", skillDiagnostics],
+        ["prompt template", promptDiagnostics],
+    ]) {
+        for (const diagnostic of diagnostics) {
+            log.warn(`[fastagent] ${kind} ${diagnostic.type}: ${diagnostic.message}${diagnostic.path ? ` (${diagnostic.path})` : ""}`);
+        }
+    }
+    return { skills, prompts, settingsManager: () => scopedSettings(settings) };
+}
+/** A package's enabled resources; the loader discovers the top-level ones itself. */
+function fromPackages(resources) {
+    return resources.filter((r) => r.enabled && r.metadata.origin === "package").map((r) => r.path);
+}
+function withoutPackages({ packages: _, ...rest }) {
+    return rest;
+}
+/**
+ * A SettingsManager over the boot snapshot. TWO scopes, not `SettingsManager.inMemory`'s one: pi deep-merges the
+ * project file over the global one (a project `retry.enabled` keeps the global `retry.maxRetries`), and flattening
+ * them first would change that. A write stays in memory — a served turn never edits the operator's files.
+ */
+function scopedSettings(snapshot) {
+    const stored = {
+        global: JSON.stringify(snapshot.global),
+        project: JSON.stringify(snapshot.project),
+    };
+    return SettingsManager.fromStorage({
+        withLock(scope, fn) {
+            const next = fn(stored[scope]);
+            if (next !== undefined)
+                stored[scope] = next;
+        },
+    });
+}
+/** The definition's names win: vendoring a skill into `skills/` is how an author overrides the machine's. */
+export function withMachine(own, lent) {
+    const names = new Set(own.map((item) => item.name));
+    return [...own, ...lent.filter((item) => !names.has(item.name))];
+}

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

@@ -1,93 +1,92 @@
 import type { ThinkingLevel } from "@earendil-works/pi-agent-core";
-import { type Api, type Model, type Models, type Provider } from "@earendil-works/pi-ai";
+import { type Api, type CredentialStore, type Model, type Models, type Provider } from "@earendil-works/pi-ai";
 import { ModelRuntime } from "@earendil-works/pi-coding-agent";
 import { type FastagentAuthOptions } from "./auth.ts";
-import { type InteractiveLoginKind } from "./login.ts";
-/** The DEFINITION-LOCAL custom-endpoint file, in pi's own models.json schema (see pi's docs/models.md):
- *  declare a self-hosted / gateway endpoint as `{ providers: { <id>: { baseUrl, api, apiKey, models } } }`
- *  and select it with a `<id>/<modelId>` model spec. Keys belong in the environment — `apiKey` supports
- *  `"$ENV_VAR"` interpolation and `"!command"` — with the NAME listed in `deploy.secrets` so the value
- *  travels to the host. Living in the agent dir is the whole point: it is part of the definition, so it
- *  is baked into the deployed image. pi's MACHINE-GLOBAL `~/.pi/agent/models.json` stays unread — that
- *  one is builder-machine state, and reading it would make an agent work locally and lose its model on
- *  deploy. The NAME itself lives in the neutral paths.ts — `dev`'s watcher needs the same one, and a
- *  second spelling would let the restart scope drift from what the worker loads. */
+import { type AuthLayers } from "./config.ts";
+/** The DEFINITION-LOCAL custom-endpoint file, in pi's own models.json schema (see pi's docs/models.md). */
 export interface CreatePiModelsOptions extends FastagentAuthOptions {
-    /** Credentials file path. Defaults to the global `~/.fastagent/.secrets/auth.json`; the directory opener passes
-     *  the project-level `<root>/.secrets/auth.json`. */
+    /** Credentials file (default `GLOBAL_AUTH_PATH`). A named file is an instruction: no second layer. */
     authPath?: string;
     /** 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: 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).
- */
+/** A `Models` with every built-in pi provider, wired to fastagent's auth. */
 export declare function createPiModels(options?: CreatePiModelsOptions): Models;
+/** The built-ins plus `providers` (a same id replaces a built-in), over any credential store. */
+export declare function piModelsOver(credentials: CredentialStore, providers?: readonly Provider[]): Models;
 /**
- * pi's Model with the API-shape generic erased — fastagent only passes models through to the engine,
- * so the generic carries no information. One alias keeps the `any` auditable.
+ * pi's Model with the API-shape generic erased — fastagent only passes models through to the engine, so the generic
+ * carries no information.
  */
 export type AnyModel = Model<any>;
+/** The serving default for reasoning effort, pinned to what pi's TUI defaults to (its own DEFAULT_THINKING_LEVEL). */
+export declare const DEFAULT_THINKING_LEVEL: ThinkingLevel;
 /**
- * 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 declare const DEFAULT_THINKING_LEVEL: ThinkingLevel;
+export declare function machineModelsPath(env?: NodeJS.ProcessEnv): string;
 /**
- * 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.
- *
- * `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.
+ * 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 declare function machineModels(agentDir: string): Promise<{
+    path: string;
+    inherited: string[];
+    overridden: string[];
+} | undefined>;
+/** Whether pi ships this provider id itself, so an agent resolves it without any models.json entry. */
+export declare function isBuiltinProvider(providerId: string): boolean;
+/** The `ModelRuntime`-shaped sibling of {@link createPiModels}. */
 export declare function createPiModelRuntime(options?: FastagentAuthOptions & {
-    authPath?: string;
-    /** The agent dir, whose {@link AGENT_MODELS_FILE} declares custom endpoints. Omit for built-ins only. */
+    /** The credentials files to read (default: the global file alone). */
+    auth?: AuthLayers;
+    /** The agent dir, whose {@link AGENT_MODELS_FILE} declares custom endpoints. */
     agentDir?: string;
+    /**
+     * Layer the machine's models.json under the agent's (default). Off for the registry a DEPLOYED agent has, which
+     * `deploy` must judge by: the machine's file does not ship.
+     */
+    machineLayer?: boolean;
     /** Where the dynamic model-catalog cache goes; defaults to the agent's resolved state root. */
     stateRoot?: string;
-    /** Extra providers for the ids the built-ins do not cover — the CODE-shaped sibling of models.json,
-     *  for what a file cannot express (minting a token per request, a test fake).
-     *
-     *  On an id COLLISION the file wins, not this: upstream installs a native provider as the BASE and
-     *  composes the models.json entry over it. Right way round — where a deployed agent's traffic goes
-     *  is a property of the definition, not of the program that embedded it — but it does mean a same-id
-     *  file entry silently replaces the endpoint injected here. Use a distinct id to keep both. */
+    /** Extra providers for the ids the built-ins do not cover. */
     providers?: Provider[];
+    /** A credential store to use instead of the files (login verifies an entered key from memory). */
+    credentials?: CredentialStore;
 }): Promise<ModelRuntime>;
-/**
- * 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 declare function modelCredentialCarry(runtime: ModelRuntime, spec: string): {
     envVar?: string;
     inDefinition: boolean;
 };
-/** Per-provider auth status for the first-run model picker: usable now (with the source label), not
- *  configured, or configured-but-broken (expired token, refresh failure, corrupt store — kept as DATA
- *  so the picker can show it instead of silently dropping the provider). Non-ready states carry the
- *  provider's {@link InteractiveLoginKind}, so the picker's hint predicts what picking does — an
- *  OAuth login, an API-key prompt, or (env-key-only providers) neither. */
+/**
+ * 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 declare function literalKeyProviders(agentDir: string): Promise<string[]>;
+/**
+ * What a provider can offer as an interactive login: an OAuth flow, an API-key ENTRY prompt, or nothing ("none" — the
+ * key must come from the provider's env var).
+ */
+export type InteractiveLoginKind = "oauth" | "api_key" | "none";
+export declare function interactiveLoginKind(p: Provider): InteractiveLoginKind;
+/** THE rule for "can this method be signed in to interactively": the auth to run for it, or undefined. */
+export declare function interactiveAuth(provider: Provider, method: Exclude<InteractiveLoginKind, "none">): import("@earendil-works/pi-ai").ApiKeyAuth | import("@earendil-works/pi-ai").OAuthAuth | undefined;
+/** The providers a sign-in can target: pi's built-ins plus `extra`, composed exactly as {@link createPiModels} does. */
+export declare function loginProviders(extra?: readonly Provider[]): readonly Provider[];
+/** Per-provider auth status for the first-run model picker. */
 export type ProviderAuthStatus = {
     state: "ready";
     source?: string;
@@ -99,37 +98,19 @@ export type ProviderAuthStatus = {
     message: string;
     login: InteractiveLoginKind;
 };
-/**
- * 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).
- */
+/** Probe every provider's auth once (auth is provider-scoped, so any of its models works as the probe). */
 export declare function providerAuthStatuses(models: Models): Promise<Map<string, ProviderAuthStatus>>;
+/** Which source currently satisfies auth for `spec` — a startup diagnostic. */
+export declare function probeAuthSource(models: Models, spec: string): Promise<string | undefined>;
 /**
- * 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.
+ * Verdict of {@link probeApiKey}: `rejected` is DEFINITIVE (the provider answered HTTP 401 — the key is wrong);
+ * everything else non-ok is `unknown`.
  */
-export declare function probeAuthSource(models: Models, spec: string): Promise<string | undefined>;
-/** Verdict of {@link probeApiKey}: `rejected` is DEFINITIVE (the provider answered HTTP 401 — the key
- *  is wrong); everything else non-ok is `unknown` — a 403 can be a VALID key without model permission,
- *  a 429/5xx/network failure says nothing about the key — so callers must only destroy state on
- *  `rejected`. */
 export type KeyProbe = {
     state: "ok";
 } | {
     state: "rejected" | "unknown";
     message: string;
 };
-/**
- * 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 declare function probeApiKey(models: Models, model: Model<Api>): Promise<KeyProbe>;
+/** Quick-fail probe for a just-stored API key. */
+export declare function probeApiKey(models: Models, model: Model<Api>, signal?: AbortSignal): Promise<KeyProbe>;