@fastagent-sh/fastagent 0.14.0 → 0.16.0

package/dist/engines/pi/models.js

@@ -6,12 +6,13 @@
  */
 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
- * `~/.fastagent/auth.json` unless the opener passes a project-level path), then ambient env vars. A
+ * `~/.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).
  */
@@ -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/open.d.ts

@@ -0,0 +1,114 @@
+import type { AgentTool } from "@earendil-works/pi-agent-core";
+import type { Agent } from "../../agent.ts";
+import { type FastagentConfig } from "./config.ts";
+import type { SessionControl } from "../../session.ts";
+import type { SessionObserver } from "./invoke.ts";
+import type { PiSessionReader, PiSessionStore } from "./sessions.ts";
+import type { ModuleLoadFailure } from "../../loader.ts";
+import type { LoadedDefinition } from "./definition.ts";
+import type { ToolCollision } from "./tool.ts";
+export interface CreatePiAgentFromDirOptions {
+    /** Model spec override (e.g. the CLI --model flag). Precedence: this > FASTAGENT_MODEL > config.model. */
+    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.
+     */
+    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.
+     */
+    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.
+     */
+    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. */
+    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: since Phase 2a an observer
+     *  receives each run's live modulation handles (see `SessionObserver`) — for read-only consumers
+     *  use the hub's `events()` stream instead. */
+    observer?: SessionObserver;
+}
+/**
+ * The agent assembly FRONT HALF — everything that is independent of how pi consumes the
+ * definition (transient harness for serving vs resident AgentSession for chat / session control):
+ * 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.)
+ */
+export interface AgentAssembly {
+    config: FastagentConfig;
+    configPath?: string;
+    /** The resolved "provider/modelId" spec in use. */
+    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. */
+    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 full mounted tool surface (config.tools + discovered tools/, search_tools applied). */
+    tools: AgentTool[];
+    toolNames: string[];
+    deferredToolNames: string[];
+    toolCollisions: ToolCollision[];
+    toolFailures: ModuleLoadFailure[];
+}
+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.
+ */
+export declare function createPiAgentFromDir(dir: string, options?: CreatePiAgentFromDirOptions): Promise<{
+    agent: Agent;
+    definition: LoadedDefinition;
+    config: FastagentConfig;
+    configPath?: string;
+    /** The resolved "provider/modelId" spec actually in use. */
+    modelSpec: string;
+    /** Absolute agent dir in use — channels/tools/persona come from here. */
+    agentDir: string;
+    /** Absolute workspace in use — the agent's cwd: ALWAYS the directory that was pointed at. */
+    workspace: string;
+    /** Absolute state root in use (FASTAGENT_STATE_DIR > <agentDir>/.state) — the ChannelContext's stateRoot. */
+    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 — also a {@link PiSessionReader}. */
+    sessions: PiSessionStore & PiSessionReader;
+    /** The observation plane over this agent's sessions; present iff `options.sessionControl`. */
+    sessionControl?: SessionControl;
+    /** 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. */
+    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[];
+}>;

package/dist/engines/pi/open.js

@@ -0,0 +1,127 @@
+/**
+ * Open a definition directory into an agent — the single agent opener BOTH `fastagent dev` and
+ * `fastagent start` drive.
+ *
+ * A thin command-posture composition over L2 `createPiAgentFromDefinition`: open the directory →
+ * resolve model (flag > env > config) and tools (append-after-defaults) → pick session storage →
+ * call L2. dev and start share the SAME assembly here (what you iterate is what you serve); they
+ * differ only at the CLI — dev watches and uses the in-tree sessions default, start runs without
+ * watch and can point sessions at a mounted volume.
+ */
+import { mkdir } from "node:fs/promises";
+import { defaultSessionsDir, loadConfig, resolveAuthPath, resolveModelSpec, } from "./config.js";
+import { resolveStateRoot, resolvePlacement } from "../../paths.js";
+import { createPiAgentFromDefinition, resolveAgentTools } from "./create.js";
+import { createPiSessionControl } from "./session-control.js";
+import { withWakeTool } from "./wake-tool.js";
+import { jsonlSessionStore } from "./sessions.js";
+export async function resolveAgentAssembly(dir, options = {}) {
+    // Placement is structural (resolvePlacement): the AGENT DIR carries definition + config + machinery;
+    // its parent — the WORKSPACE — is what the agent works on: its cwd and the start of the ②-context
+    // walk (that is where it reads the project's AGENTS.md from).
+    const { agentDir, workspace } = resolvePlacement(dir);
+    const { config, path: configPath } = await loadConfig(agentDir);
+    const modelSpec = resolveModelSpec(options.model, config);
+    if (!modelSpec) {
+        throw new Error(`missing model: set --model, "model" in fastagent.config.ts, or FASTAGENT_MODEL (e.g. "openai-codex/gpt-5.5")`);
+    }
+    const { tools, toolNames, deferredToolNames, toolCollisions, toolFailures } = await resolveAgentTools(config, agentDir, workspace);
+    // The state root: sessions/channel state/schedule state derive from it (FASTAGENT_STATE_DIR moves it
+    // in one knob — a container points it at its volume); the finer overrides below still win.
+    const stateRoot = resolveStateRoot(agentDir);
+    // The credentials file: project-level by default (under `<agentDir>/.secrets`); only resolved here, never
+    // created (a missing file reads as not-configured — `fastagent login` creates it).
+    const authPath = resolveAuthPath(agentDir, options.authPath);
+    return {
+        config,
+        configPath,
+        modelSpec,
+        agentDir,
+        workspace,
+        stateRoot,
+        authPath,
+        tools,
+        toolNames,
+        deferredToolNames,
+        toolCollisions,
+        toolFailures,
+    };
+}
+/**
+ * "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.
+ */
+export async function createPiAgentFromDir(dir, options = {}) {
+    const { config, configPath, modelSpec, agentDir, workspace, stateRoot, authPath, tools, toolNames, deferredToolNames, toolCollisions, toolFailures, } = await resolveAgentAssembly(dir, options);
+    // Mount the built-in `wake` tool only when BOTH: this is a long-running serve (the poller honors it) AND
+    // the author opted into self-scheduling (config.selfSchedule). The agent's own `wake` wins if defined.
+    const mountedTools = withWakeTool(tools, stateRoot, !!options.serving && !!config.selfSchedule);
+    const sessionsDir = options.sessionsDir ?? defaultSessionsDir(stateRoot);
+    await mkdir(sessionsDir, { recursive: true });
+    const sessions = jsonlSessionStore({ dir: sessionsDir, cwd: workspace });
+    // The hub is wired HERE because the store is created here: chicken-and-egg otherwise (the hub
+    // needs the store; the agent needs the hub's observer). Boundary parts (models/factory/lease)
+    // only exist after the assembly below — the hub takes them as a lazy thunk, filled by the
+    // assembly's onAssembly callback (assembly completes before this function returns, so every
+    // dispatch sees them). An extra caller observer composes after the hub's (TRUSTED seam).
+    let boundaryParts;
+    const caller = options.observer;
+    const wantControl = options.sessionControl ?? (config.sessionControl === true && options.serving === true);
+    const hub = wantControl
+        ? createPiSessionControl({
+            sessions,
+            boundary: () => boundaryParts,
+            // The caller tap's boundary-event half: state_changed/compaction_* originate in the hub
+            // and never cross the data plane's observer seam — without this, an audit tap wired here
+            // would miss exactly the mutations it most needs to see (set_model).
+            tap: caller ? (session, event) => caller(session, event) : undefined,
+        })
+        : undefined;
+    const observer = hub
+        ? caller
+            ? (session, event, run) => {
+                hub.observer(session, event, run);
+                caller(session, event, run);
+            }
+            : hub.observer
+        : caller;
+    const { agent, definition } = await createPiAgentFromDefinition(agentDir, {
+        model: modelSpec,
+        thinkingLevel: config.thinkingLevel,
+        cwd: workspace,
+        tools: mountedTools,
+        authPath,
+        // Skills are definition-only (the agent is its directory), so dev mirrors deployment exactly.
+        sessions,
+        observer,
+        onAssembly: hub
+            ? (parts) => {
+                boundaryParts = {
+                    lease: parts.lease,
+                    models: parts.models,
+                    harnessFactory: parts.harnessFactory,
+                };
+            }
+            : undefined,
+    });
+    return {
+        agent,
+        definition,
+        sessions,
+        sessionControl: hub?.control,
+        agentDir,
+        workspace,
+        config,
+        configPath,
+        modelSpec,
+        stateRoot,
+        sessionsDir,
+        authPath,
+        toolNames,
+        deferredToolNames,
+        toolCollisions,
+        toolFailures,
+    };
+}

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 agent's default `<agentDir>/.secrets/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 buildAgentSessionRuntime(dir: string, options?: BuildSessionRuntimeOptions, 
+/** Session backend. Defaults to pi's project-scoped store; tests inject SessionManager.inMemory(). */
+sessionManager?: SessionManager): Promise<AgentSessionRuntime>;