@fastagent-sh/fastagent 0.13.0 → 0.15.0

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

@@ -4,8 +4,10 @@
  * it into the harness alongside the selected `model`; the two must come from the same collection so
  * the model's provider auth is in scope.
  */
-import { type Models, type Provider } from "@earendil-works/pi-ai";
+import { type Api, 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";
 export interface CreatePiModelsOptions extends FastagentAuthOptions {
     /** Credentials file path. Defaults to the global `~/.fastagent/auth.json`; the directory opener passes
      *  the project-level `<dir>/.fastagent/auth.json`. */
@@ -22,16 +24,41 @@ export interface CreatePiModelsOptions extends FastagentAuthOptions {
  */
 export declare function createPiModels(options?: CreatePiModelsOptions): Models;
 /**
- * The "provider/modelId" specs whose provider currently has USABLE credentials (a stored login or an
- * env key) — the menu for the first-run model picker (`fastagent dev`/`start`/`invoke` with no model
- * set). Auth is provider-scoped, so probe once per provider (any of its models) rather than per model.
- * A provider that resolves no auth (unconfigured) or rejects it (configured-but-expired) is omitted:
- * the picker offers only models that would actually run now; `fastagent login` fixes the rest. Sorted.
- *
- * pi deliberately has no "best/tier" ranking on Model, so this does not auto-pick — it narrows the menu
- * to what the user can use and lets them choose (mirroring pi-coding-agent's select-then-persist).
+ * 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 })`). Builtins only (`modelsPath: null` — pi's
+ * machine-global models.json is definition-foreign) and no availability network, so the model
+ * surface equals serving's. No `providers` option: `ModelRuntime` registers providers by config
+ * record, not `Provider` instance — accepting the option and dropping it would be a silent no-op;
+ * add the mapping when a consumer actually needs it.
  */
-export declare function configuredModelSpecs(models: Models): Promise<string[]>;
+export declare function createPiModelRuntime(options?: FastagentAuthOptions & {
+    authPath?: string;
+}): Promise<ModelRuntime>;
+/** 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. */
+export type ProviderAuthStatus = {
+    state: "ready";
+    source?: string;
+} | {
+    state: "unconfigured";
+    login: InteractiveLoginKind;
+} | {
+    state: "broken";
+    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).
+ */
+export declare function providerAuthStatuses(models: Models): Promise<Map<string, ProviderAuthStatus>>;
 /**
  * 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),
@@ -39,3 +66,22 @@ export declare function configuredModelSpecs(models: Models): Promise<string[]>;
  * undefined when unconfigured. Reporting-only; never throws.
  */
 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>;

package/dist/engines/pi/models.js

@@ -6,8 +6,9 @@
  */
 import { defaultProviderAuthContext } from "@earendil-works/pi-ai";
 import { builtinModels } from "@earendil-works/pi-ai/providers/all";
-import { log } from "../../log.js";
+import { ModelRuntime } from "@earendil-works/pi-coding-agent";
 import { fastagentCredentialStore } from "./auth.js";
+import { interactiveLoginKind } from "./login.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
@@ -25,38 +26,44 @@ export function createPiModels(options = {}) {
     return models;
 }
 /**
- * The "provider/modelId" specs whose provider currently has USABLE credentials (a stored login or an
- * env key) — the menu for the first-run model picker (`fastagent dev`/`start`/`invoke` with no model
- * set). Auth is provider-scoped, so probe once per provider (any of its models) rather than per model.
- * A provider that resolves no auth (unconfigured) or rejects it (configured-but-expired) is omitted:
- * the picker offers only models that would actually run now; `fastagent login` fixes the rest. Sorted.
- *
- * pi deliberately has no "best/tier" ranking on Model, so this does not auto-pick — it narrows the menu
- * to what the user can use and lets them choose (mirroring pi-coding-agent's select-then-persist).
+ * 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 })`). Builtins only (`modelsPath: null` — pi's
+ * machine-global models.json is definition-foreign) and no availability network, so the model
+ * surface equals serving's. No `providers` option: `ModelRuntime` registers providers by config
+ * record, not `Provider` instance — accepting the option and dropping it would be a silent no-op;
+ * add the mapping when a consumer actually needs it.
  */
-export async function configuredModelSpecs(models) {
-    const specs = [];
+export function createPiModelRuntime(options = {}) {
+    return ModelRuntime.create({
+        credentials: fastagentCredentialStore(options.authPath, { warn: options.warn }),
+        modelsPath: null,
+        allowModelNetwork: false,
+    });
+}
+/**
+ * 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).
+ */
+export async function providerAuthStatuses(models) {
+    const statuses = new Map();
     for (const provider of models.getProviders()) {
         const [probe] = provider.getModels();
         if (!probe)
             continue;
-        let usable;
+        const login = interactiveLoginKind(provider);
         try {
-            usable = (await models.getAuth(probe)) !== undefined;
+            const auth = await models.getAuth(probe);
+            statuses.set(provider.id, auth ? { state: "ready", source: auth.source } : { state: "unconfigured", login });
         }
         catch (error) {
-            // Configured-but-broken (expired token, a refresh network failure, a corrupt store): omit it
-            // from the menu, but SAY so — a silent disappearance is the same fail-visibly gap the caller
-            // guards against for the top-level enumeration. `undefined` (plainly unconfigured) stays quiet.
-            log.warn(`[fastagent] skipping provider "${provider.id}": auth check failed (${error.message})`);
-            continue;
+            statuses.set(provider.id, { state: "broken", message: error.message, login });
         }
-        if (!usable)
-            continue;
-        for (const model of provider.getModels())
-            specs.push(`${provider.id}/${model.id}`);
     }
-    return specs.sort();
+    return statuses;
 }
 /**
  * Which source currently satisfies auth for `spec` — a startup diagnostic. Returns the upstream
@@ -74,3 +81,34 @@ 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) {
+    let status;
+    let reply;
+    try {
+        reply = await models.complete(model, { messages: [{ role: "user", content: "ping", timestamp: Date.now() }] }, {
+            maxTokens: 16,
+            timeoutMs: 15_000,
+            maxRetries: 0,
+            onResponse: (r) => {
+                status = r.status;
+            },
+        });
+    }
+    catch (error) {
+        // Thrown = before/around the request (auth resolution, transport setup) — not a provider verdict.
+        return { state: "unknown", message: error.message };
+    }
+    if (reply.stopReason !== "error" && reply.stopReason !== "aborted")
+        return { state: "ok" };
+    const message = reply.errorMessage ?? `stopReason "${reply.stopReason}"`;
+    const unauthorized = status === 401 || (status === undefined && /(^|\D)401(\D|$)/.test(message));
+    return { state: unauthorized ? "rejected" : "unknown", message };
+}

package/dist/engines/pi/search-tools.d.ts

@@ -0,0 +1,10 @@
+import type { AgentTool } from "@earendil-works/pi-agent-core";
+/** Mount the built-in loader iff any mounted tool is deferred and the author didn't define their own. */
+export declare function withSearchTool(tools: AgentTool[]): AgentTool[];
+/** Build the `search_tools` loader. Keyword search over the inactive tools' name+description.
+ *
+ * `executionMode: "sequential"` — pi turns any batch containing a sequential tool serial. Required for
+ * correct load-point attribution everywhere an OUTER active-set diff exists: pi wraps SDK customTools
+ * (the chat path) in a before/after diff, and two parallel loader calls would both snapshot the
+ * pre-activation set and get stamped with the same activation. Custom loader authors must set it too. */
+export declare function makeSearchToolsTool(): AgentTool;

package/dist/engines/pi/search-tools.js

@@ -0,0 +1,138 @@
+/**
+ * The built-in `search_tools` loader — the discovery surface for deferred tools (defineTool
+ * `deferred: true`). A deferred tool's schema is not in the request and the model cannot see it; this
+ * loader is how it finds and activates one. Mounted automatically (withSearchTool) only when a
+ * deferred tool exists; a workspace tool named `search_tools` wins — the author owns the concept then
+ * (same rule as the wake pair).
+ */
+import { z } from "zod";
+import { log } from "../../log.js";
+import { defineTool, isDeferredTool, stripDeferredMarker } from "./tool.js";
+/** Mount the built-in loader iff any mounted tool is deferred and the author didn't define their own. */
+export function withSearchTool(tools) {
+    if (!tools.some(isDeferredTool))
+        return tools;
+    const authored = tools.find((t) => t.name === "search_tools");
+    if (!authored)
+        return [...tools, makeSearchToolsTool()];
+    let fixed = authored;
+    if (isDeferredTool(fixed)) {
+        // A deferred LOADER is a contradiction — it is the only entry point to the deferred tools, so
+        // nothing could ever activate it (or, through it, them): every deferred tool would be silently
+        // unreachable. Ignore the marker and keep the loader active (fail visibly, keep the capability).
+        log.warn("[fastagent] search_tools is marked deferred — ignoring the marker: the loader must stay active, or no deferred tool could ever be activated");
+        fixed = stripDeferredMarker(fixed);
+    }
+    if (fixed.executionMode !== "sequential") {
+        // A non-sequential loader silently revives the parallel double-attribution (pi's diff around SDK
+        // tools in chat) — enforce the mode rather than hope the author read the docs; warn so they know.
+        log.warn('[fastagent] search_tools lacks executionMode: "sequential" — forcing it: parallel loader calls would misattribute activations');
+        fixed = { ...fixed, executionMode: "sequential" };
+    }
+    return fixed === authored ? tools : tools.map((t) => (t === authored ? fixed : t));
+}
+/** Activation cap per search: activation is additive, session-persisted, and has NO deactivate path —
+ *  without a cap, one broad token ("get", "file") would permanently activate half the catalog and
+ *  silently spend the entire deferral benefit for the rest of the conversation. Over the cap nothing
+ *  activates; the model gets the candidates and narrows the query. */
+const MAX_ACTIVATIONS_PER_SEARCH = 5;
+/** Miss-path listing cap — same rationale as the activation cap: a typo query must not pour the whole
+ *  catalog (the thing deferral keeps OUT of the context) back in as a tool result. */
+const MAX_MISS_LISTING = 10;
+/** Build the `search_tools` loader. Keyword search over the inactive tools' name+description.
+ *
+ * `executionMode: "sequential"` — pi turns any batch containing a sequential tool serial. Required for
+ * correct load-point attribution everywhere an OUTER active-set diff exists: pi wraps SDK customTools
+ * (the chat path) in a before/after diff, and two parallel loader calls would both snapshot the
+ * pre-activation set and get stamped with the same activation. Custom loader authors must set it too. */
+export function makeSearchToolsTool() {
+    return defineTool({
+        name: "search_tools",
+        executionMode: "sequential",
+        description: 
+        // First line short on purpose: the base prompt's tools list truncates at the first newline, and
+        // the discovery guidance below would otherwise flood it (and duplicate its deferred note).
+        "Discover and activate additional tools.\n" +
+            "Part of this agent's toolset is inactive until needed: search by keywords (e.g. what you are " +
+            "trying to do), and matching inactive tools are activated and become callable from that point on " +
+            "(if too many match, you get the candidates back — narrow the query, or query an exact tool " +
+            "name). ALWAYS search here before concluding a capability is missing.",
+        input: z.object({
+            query: z.string().min(1).describe("keywords describing the capability you need (e.g. 'weather forecast')"),
+        }),
+        async execute(input, ctx) {
+            if (!ctx.tools)
+                return "tool activation is unavailable outside a conversation turn.";
+            // Search the WHOLE registered catalog: the loader is the only discovery surface, and in a long
+            // conversation the model does not remember what it activated — a "No tools matched" answer for
+            // an ALREADY-ACTIVE tool would push it toward the exact wrong conclusion (capability missing).
+            // ponytail: naive keyword match (any query token as a case-insensitive substring of
+            // name+description) with a hard per-search activation cap above — the two named ceilings are
+            // relevance and irreversibility; swap in scoring/embeddings if catalogs outgrow this.
+            const tokens = input.query
+                .toLowerCase()
+                .split(/[^a-z0-9]+/)
+                .filter(Boolean);
+            // AND semantics: EVERY token must hit — "adding a word narrows" must actually hold, or the
+            // over-cap "narrow the query" instruction sends the model in circles (OR would widen with each
+            // word, and a shared prefix like "fetch" could make a whole tool family permanently over-cap).
+            const matchesQuery = (t) => {
+                const haystack = `${t.name} ${t.description}`.toLowerCase();
+                return tokens.every((token) => haystack.includes(token));
+            };
+            const describe = (t) => `${t.name} — ${t.description.split("\n")[0]}`;
+            const active = new Set(ctx.tools.active());
+            const registered = ctx.tools.registered();
+            // A query with no searchable tokens (all punctuation/symbols) must not match: `every` over an
+            // empty token list is vacuously true, and a noise query would otherwise activate the catalog.
+            if (tokens.length === 0)
+                return `"${input.query}" contains no searchable keywords — describe the capability you need.`;
+            // Exact-name shortcut: the guaranteed escape hatch from the cap — a query that IS an INACTIVE
+            // registered tool's name addresses that one tool, no keyword scoring in the way. An exact match
+            // on an ACTIVE tool falls through to keyword matching: it must not swallow the discovery of
+            // other, still-inactive keyword matches.
+            const exact = registered.find((t) => t.name.toLowerCase() === input.query.trim().toLowerCase());
+            const activeMatches = registered.filter((t) => active.has(t.name) && (t === exact || matchesQuery(t)));
+            const inactiveMatches = exact && !active.has(exact.name) ? [exact] : registered.filter((t) => !active.has(t.name) && matchesQuery(t));
+            // Same listing cap as every other branch — a wide token can match most of the ACTIVE set too
+            // (in chat that includes pi's default tools), and no answer may pour a catalog into the context.
+            const listedActive = activeMatches.slice(0, MAX_MISS_LISTING);
+            const moreActive = activeMatches.length - listedActive.length;
+            const activeNote = activeMatches.length > 0
+                ? `Already active (call directly): ${listedActive.map(describe).join("; ")}${moreActive > 0 ? ` … and ${moreActive} more` : ""}.`
+                : "";
+            if (inactiveMatches.length === 0) {
+                if (activeNote)
+                    return activeNote;
+                const inactive = registered.filter((t) => !active.has(t.name));
+                if (inactive.length === 0)
+                    return "All tools are already active — nothing to discover.";
+                // Cap the miss listing like the activation cap — both guard the same semantic (don't pour the
+                // catalog back into the context the deferral exists to protect).
+                const listed = inactive.slice(0, MAX_MISS_LISTING);
+                const more = inactive.length - listed.length;
+                return `No tools matched "${input.query}". Inactive tools: ${listed.map(describe).join("; ")}${more > 0 ? ` … and ${more} more — search with different keywords.` : ""}`;
+            }
+            if (inactiveMatches.length > MAX_ACTIVATIONS_PER_SEARCH) {
+                // Same listing cap as the miss path — an over-cap answer must not pour the catalog into the
+                // context either. Names alone suffice: the exact-name escape only needs a name to query.
+                const listed = inactiveMatches.slice(0, MAX_MISS_LISTING);
+                const more = inactiveMatches.length - listed.length;
+                return `${inactiveMatches.length} inactive tools matched "${input.query}" — too many to activate at once (activation is permanent for this conversation). Narrow the query (or query an exact name). Matches: ${listed
+                    .map((t) => t.name)
+                    .join(", ")}${more > 0 ? ` … and ${more} more` : ""}.${activeNote ? ` ${activeNote}` : ""}`;
+            }
+            const activated = await ctx.tools.activate(inactiveMatches.map((t) => t.name));
+            // Report what actually happened, not what was attempted: a parallel sibling call may have
+            // activated the same matches first, leaving nothing new here — an empty "Activated:" would lie.
+            if (activated.length === 0) {
+                return `Matched ${inactiveMatches.map((t) => t.name).join(", ")} — already active (possibly activated by a concurrent call). Call them directly.${activeNote ? ` ${activeNote}` : ""}`;
+            }
+            const raced = inactiveMatches.filter((t) => !activated.includes(t.name));
+            return `Activated: ${inactiveMatches
+                .filter((t) => activated.includes(t.name))
+                .map(describe)
+                .join("; ")}.${raced.length > 0 ? ` Already active: ${raced.map((t) => t.name).join(", ")}.` : ""}${activeNote ? ` ${activeNote}` : ""} These tools are callable now.`;
+        },
+    });
+}

package/dist/engines/pi/session-builder.d.ts

@@ -0,0 +1,16 @@
+import { type AgentSessionRuntime, SessionManager } from "@earendil-works/pi-coding-agent";
+export interface BuildSessionRuntimeOptions {
+    /** Model spec override (the CLI --model flag). Precedence: this > FASTAGENT_MODEL > config.model. */
+    model?: string;
+    /** Credentials file override (the CLI --auth-path flag). Precedence: this > FASTAGENT_AUTH_PATH >
+     *  the workspace default `<stateRoot>/auth.json`. */
+    authPath?: string;
+}
+/**
+ * Build pi's interactive runtime driven by fastagent's assembled agent (model, prompt, tools,
+ * skills, and auth resolved exactly as the serving opener does). Split from the TUI launcher so the
+ * assembly — the fidelity-critical part — is inspectable and reusable without launching a TUI.
+ */
+export declare function buildWorkspaceSessionRuntime(dir: string, options?: BuildSessionRuntimeOptions, 
+/** Session backend. Defaults to pi's project-scoped store; tests inject SessionManager.inMemory(). */
+sessionManager?: SessionManager): Promise<AgentSessionRuntime>;