@fastagent-sh/fastagent 0.24.3 → 0.25.0

package/dist/engines/pi/config.js

@@ -1,199 +0,0 @@
-var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
-    if (typeof path === "string" && /^\.\.?\//.test(path)) {
-        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
-            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
-        });
-    }
-    return path;
-};
-/**
- * The config subsystem: schema (defineConfig), loading (loadConfig), and value interpretation (resolveModel,
- * resolveModelSpec).
- */
-import { existsSync, statSync } from "node:fs";
-import { join } from "node:path";
-import { pathToFileURL } from "node:url";
-import { THINKING_LEVELS } from "./session-settings.js";
-import { readSecretDeclaration } from "../../declared-secrets.js";
-import { assertCorsOrigins } from "../../channels/serve.js";
-import { moduleLoadHint } from "../../loader.js";
-import { AGENT_CONFIG_FILE } from "../../paths.js";
-/** Identity function for typing and IDE completion (vite/next-style). */
-export function defineConfig(config) {
-    return config;
-}
-export function isValidPort(n) {
-    return Number.isInteger(n) && n >= 0 && n <= 65535;
-}
-/** Validate an optional `string[]` config field where each entry must match `shape`. */
-function validateStringList(value, key, shape, desc, path) {
-    if (value === undefined)
-        return;
-    if (!Array.isArray(value))
-        throw new Error(`${path}: "${key}" must be an array of strings`);
-    for (const [i, v] of value.entries()) {
-        if (typeof v !== "string" || !shape.test(v)) {
-            throw new Error(`${path}: "${key}[${i}]" must be ${desc}`);
-        }
-    }
-}
-/** Refuse a key `level` does not have, naming the keys it does (the ONE list both the check and the message read). */
-function refuseUnknownKeys(level, valid, prefix, path) {
-    for (const key of Object.keys(level)) {
-        if (!valid.includes(key)) {
-            throw new Error(`${path}: unknown key "${prefix}${key}" (valid keys: ${valid.join(", ")})`);
-        }
-    }
-}
-/** Load `<dir>/fastagent.config.ts`. */
-export async function loadConfig(dir) {
-    const path = join(dir, AGENT_CONFIG_FILE);
-    if (!existsSync(path))
-        return { config: {} };
-    let mod;
-    try {
-        // Cache-bust on file change: ESM `import()` caches by URL, so a config REWRITTEN in this process (the first-run
-        // picker's write-back) would otherwise read back stale. An INTEGER stamp (mtimeNs), because `mtimeMs` carries a
-        // fraction and a loader that decides how to transform a module by looking at the last dot in the URL reads
-        // `…config.ts?v=1789701227227.251` as extension `251` and parses the file as JavaScript — which the scaffold's
-        // `import type` + `satisfies` (what makes an editor complete these keys) does not survive.
-        const url = pathToFileURL(path);
-        url.searchParams.set("v", String(statSync(path, { bigint: true }).mtimeNs));
-        mod = (await import(__rewriteRelativeImportExtension(url.href)));
-    }
-    catch (error) {
-        throw new Error(`${path}: ${error.message}${moduleLoadHint(error)}`);
-    }
-    const config = mod.default;
-    if (!config || typeof config !== "object") {
-        throw new Error(`${path}: must default-export defineConfig({...})`);
-    }
-    const c = config;
-    // Unknown keys throw. This is NOT redundant with `defineConfig`'s types: Node strips types without checking them,
-    // so `modle:` reaches here whatever the editor said, and silently degrading to defaults is the failure it would
-    // otherwise cause.
-    refuseUnknownKeys(c, ["model", "thinkingLevel", "tools", "http", "deploy", "sessionControl"], "", path);
-    if (c.model !== undefined && typeof c.model !== "string") {
-        throw new Error(`${path}: "model" must be a "provider/modelId" string`);
-    }
-    if (c.sessionControl !== undefined && typeof c.sessionControl !== "boolean") {
-        throw new Error(`${path}: "sessionControl" must be a boolean`);
-    }
-    if (c.thinkingLevel !== undefined && !THINKING_LEVELS.has(c.thinkingLevel)) {
-        throw new Error(`${path}: "thinkingLevel" must be one of ${[...THINKING_LEVELS].join(", ")}`);
-    }
-    if (c.tools !== undefined && !Array.isArray(c.tools)) {
-        throw new Error(`${path}: "tools" must be an array of AgentTool`);
-    }
-    if (c.tools !== undefined) {
-        for (const [i, tool] of c.tools.entries()) {
-            if (!tool || typeof tool !== "object") {
-                throw new Error(`${path}: "tools[${i}]" must be an AgentTool object`);
-            }
-            const candidate = tool;
-            if (typeof candidate.name !== "string" || typeof candidate.execute !== "function") {
-                throw new Error(`${path}: "tools[${i}]" must have string "name" and function "execute"`);
-            }
-            // The declaration's SHAPE, checked with the same read the code-input loaders use. Here rather
-            // than at tool resolution because this is the author's own config file: a wrong shape in it is
-            // a config error like any other (it stops the command with one line naming the entry), while a
-            // wrong shape in `tools/x.ts` is that one file's load failure and the agent serves without it.
-            const declaration = readSecretDeclaration(candidate, `${path}: "tools[${i}]"`);
-            if (declaration.error !== undefined)
-                throw new Error(declaration.error);
-        }
-    }
-    if (c.http !== undefined && (typeof c.http !== "object" || c.http === null)) {
-        throw new Error(`${path}: "http" must be an object`);
-    }
-    refuseUnknownKeys(c.http ?? {}, ["port", "cors", "invoke", "run"], "http.", path);
-    if (c.http?.invoke !== undefined && typeof c.http.invoke !== "boolean") {
-        throw new Error(`${path}: "http.invoke" must be a boolean`);
-    }
-    if (c.http?.run !== undefined && typeof c.http.run !== "boolean") {
-        throw new Error(`${path}: "http.run" must be a boolean`);
-    }
-    if (c.http?.cors !== undefined)
-        assertCorsOrigins(c.http.cors, `${path}: "http.cors"`);
-    if (c.http?.port !== undefined && (typeof c.http.port !== "number" || !isValidPort(c.http.port))) {
-        throw new Error(`${path}: "http.port" must be an integer 0-65535`);
-    }
-    if (c.deploy !== undefined && (typeof c.deploy !== "object" || c.deploy === null)) {
-        throw new Error(`${path}: "deploy" must be an object`);
-    }
-    refuseUnknownKeys(c.deploy ?? {}, ["apt", "agentcore"], "deploy.", path);
-    if (c.deploy?.agentcore !== undefined && (typeof c.deploy.agentcore !== "object" || c.deploy.agentcore === null)) {
-        throw new Error(`${path}: "deploy.agentcore" must be an object`);
-    }
-    refuseUnknownKeys(c.deploy?.agentcore ?? {}, ["idleTimeoutSeconds"], "deploy.agentcore.", path);
-    // AWS's own bounds for idleRuntimeSessionTimeout: a value outside them is rejected by CloudFormation minutes into
-    // `deploy agentcore --run`, after the image build.
-    const idle = c.deploy?.agentcore?.idleTimeoutSeconds;
-    if (idle !== undefined && (!Number.isInteger(idle) || idle < 60 || idle > 1209600)) {
-        throw new Error(`${path}: "deploy.agentcore.idleTimeoutSeconds" must be an integer 60-1209600 (seconds)`);
-    }
-    // apt entries are Debian package names.
-    validateStringList(c.deploy?.apt, "deploy.apt", /^[a-z0-9][a-z0-9.+-]*$/, "a Debian package name", path);
-    return { config: c, path };
-}
-/** The provider prefix of a "provider/modelId" spec. */
-export function providerOf(spec) {
-    const slash = spec.indexOf("/");
-    return slash > 0 ? spec.slice(0, slash) : spec;
-}
-/** Resolve "provider/modelId" → a pi Model from `models`, so auth resolves from the same collection. */
-export function resolveModel(models, spec) {
-    const slash = spec.indexOf("/");
-    if (slash < 1 || slash === spec.length - 1) {
-        throw new Error(`model must be "provider/modelId" (e.g. "openai-codex/gpt-5.5"), got "${spec}"`);
-    }
-    const provider = spec.slice(0, slash);
-    const modelId = spec.slice(slash + 1);
-    const model = models.getModel(provider, modelId);
-    if (!model) {
-        throw new Error(`unknown model "${spec}" (provider "${provider}" / id "${modelId}" not in registry); run \`fastagent models\` to list ` +
-            "available specs, or `fastagent models --refresh` in the agent to fetch models newer than the installed pi");
-    }
-    return model;
-}
-/** All registered "provider/modelId" specs in `models`, sorted — the list behind `fastagent models`. */
-export function listModels(models) {
-    const specs = [];
-    for (const provider of models.getProviders()) {
-        for (const model of provider.getModels())
-            specs.push(`${provider.id}/${model.id}`);
-    }
-    return specs.sort();
-}
-/** Rewrite the `model` in a config file's SOURCE TEXT to `spec`, for the first-run picker's write-back. */
-export function rewriteConfigModel(src, spec) {
-    const line = `  model: ${JSON.stringify(spec)},`;
-    const commented = /^[ \t]*\/\/[ \t]*model:.*$/m;
-    const active = /^[ \t]*model:[ \t]*["'].*$/m;
-    if (commented.test(src))
-        return src.replace(commented, line);
-    if (active.test(src))
-        return src.replace(active, line);
-    // No model line at all — the natural state after "picked once, then hand-deleted the line to reset".
-    const opener = /^export default[ \t]*\{[ \t]*$/m;
-    if (opener.test(src))
-        return src.replace(opener, (open) => `${open}\n${line}`);
-    return null;
-}
-/**
- * Model selection precedence: CLI flag > FASTAGENT_MODEL env > config default. An EMPTY `FASTAGENT_MODEL` is
- * "unset", not "no model": `export FASTAGENT_MODEL=` in a shell or CI job, and an `environment:`/`env` entry that
- * interpolates a missing variable, both arrive as `""` — and a set-but-empty value that shadowed `config.model`
- * would refuse to start an agent whose config names a model.
- */
-export function resolveModelSpec(flag, config, env = process.env) {
-    return flag ?? (env.FASTAGENT_MODEL || config.model);
-}
-/**
- * The refusal of a process that runs the agent here (the CLI's dev/start/invoke/routine run, and chat) when no
- * default model resolves. The agent itself opens without one; such a process would fail every new conversation, so it
- * stops at startup instead.
- */
-export function missingDefaultModel() {
-    return new Error(`missing model: set --model, "model" in fastagent.config.ts, or FASTAGENT_MODEL (e.g. "openai-codex/gpt-5.5")`);
-}

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

@@ -1,170 +0,0 @@
-import type { ExecutionEnv, Skill, ThinkingLevel } from "@earendil-works/pi-agent-core";
-import { type ModelRuntime } from "@earendil-works/pi-coding-agent";
-import type { CredentialStore, Provider } from "@earendil-works/pi-ai";
-import type { Agent } from "../../agent.ts";
-import { type FastagentConfig } from "./config.ts";
-import { type LoadedDefinition } from "./definition.ts";
-import type { ModuleLoadFailure } from "../../loader.ts";
-import { type ToolCollision, type MountedTool } from "./tool.ts";
-import { type DeclaredSecret } from "../../declared-secrets.ts";
-import { type PiAgentSessionFactory } from "./invoke-session.ts";
-import { type PiAgentSessionFactoryOptions } from "./agent-session-factory.ts";
-import { type AnyModel } from "./models.ts";
-import { type AgentModels } from "./agent-models.ts";
-import { type PiSessionRecordStore } from "./session-store.ts";
-import { type Lease, type SessionObserver } from "./turn-kit.ts";
-/**
- * Every pi coding tool, in canonical order, rooted at the workspace it operates in. pi ships two overlapping groupings
- * and neither is the whole set.
- */
-export declare const CODING_TOOL_NAMES: readonly ["read", "grep", "find", "ls", "bash", "edit", "write"];
-export declare function piAllCodingTools(cwd: string): MountedTool[];
-/** How the model reaches a mounted tool it is not given up front. */
-export type ToolReach = "tool_search" | "codemode" | "hidden" | "inactive" | "unreachable";
-/** A mounted authored tool outside the default-active surface, and its way in. */
-export interface IndirectTool {
-    name: string;
-    reach: ToolReach;
-}
-/**
- * The full directory-agent tool set: all pi coding tools + `config.tools` + discovered `tools/` (deduped, existing
- * win), plus the authored names and collisions to report.
- */
-export declare function resolveAgentTools(config: FastagentConfig, agentDir: string, cwd: string): Promise<{
-    tools: MountedTool[];
-    toolNames: string[];
-    /** Mounted authored tools the model is not given up front, with how each is reached. */
-    indirectTools: IndirectTool[];
-    toolCollisions: ToolCollision[];
-    toolFailures: ModuleLoadFailure[];
-    /** Env vars the MOUNTED tools declared they need, BY TOOL NAME — a discovered tool shadowed by a
-     *  coding tool or `config.tools` never executes, so its declaration is dropped here rather than
-     *  gating a start. Per tool because a caller that runs exactly ONE of them (`fastagent tool`) must
-     *  not be stopped by a sibling's credential; the serving paths flatten it (they mount all of
-     *  them). DATA: `info` reports it and the deploy pre-flight carries it, while the serving opener
-     *  asserts it (open.ts) — this function must stay reportable. */
-    toolSecrets: Map<string, DeclaredSecret[]>;
-}>;
-/**
- * FastAgent's own prompt sections (docs/design/agent-model.md §2): what pi's prompt cannot know. Each is a named
- * section pi renders after its own, so it holds whoever wrote the rest of the prompt.
- */
-export declare function fastagentPromptSections(options: {
-    tools: readonly MountedTool[];
-    /** The {@link BUILTIN_EXTENSIONS} this machine leaves enabled (`Machine.builtinExtensions`). */
-    builtinExtensions: readonly string[];
-}): Record<string, string>;
-/** The assembly, as a value: what every rung builds and what the agent runs on. */
-export interface PiAssembly {
-    lease: Lease;
-    sessionFactory: PiAgentSessionFactory;
-    /** Extension-aware catalog for startup reporting and control-plane validation; never bound to a session. */
-    modelRuntime: () => Promise<ModelRuntime>;
-    /** A fresh runtime for every session, before loading its extensions. */
-    createModelRuntime: () => Promise<ModelRuntime>;
-    /**
-     * The registry and the default model, resolved on first use (a credential read is async). No model when the
-     * assembly has no default: each session then runs on the model it records (agent-session-factory.ts).
-     */
-    engine: () => Promise<{
-        modelRuntime: ModelRuntime;
-        model?: AnyModel;
-    }>;
-    /** The configured reasoning effort — the other half of the pair a session without overrides runs on. */
-    thinkingLevel: ThinkingLevel;
-    /** The tools every session mounts. */
-    tools: MountedTool[];
-    /** Pi built-ins the mounted tools leave out, denied in every session so discovery cannot bring them back. */
-    excludedToolNames: readonly string[];
-    /** The prompt and skills a session runs on, read when a session is bound. */
-    readDefinition: PiAgentSessionFactoryOptions["readDefinition"];
-    /** The extension entry points every session loads, discovered once with the assembly. */
-    extensionPaths: readonly string[];
-}
-/** The agent an assembly runs as: the L0 over its lease and session factory. */
-export declare function agentOf(assembly: PiAssembly, observer?: SessionObserver): Agent;
-/** L1 options. */
-export interface CreatePiAgentOptions {
-    /** Model spec "provider/modelId" (e.g. "openai-codex/gpt-5.5"), resolved against {@link models}. */
-    model: string;
-    /** Reasoning effort (pi's scale). */
-    thinkingLevel?: ThinkingLevel;
-    /**
-     * The system prompt itself — no engine base and no wrapping (unlike the directory path, where pi builds its default
-     * prompt, or SYSTEM.md replaces it, and AGENTS.md, APPEND_SYSTEM.md and FastAgent's sections are added).
-     */
-    instructions?: string | (() => string);
-    /** The tool set to mount: authored tools or pi's cwd-bound coding tools, both AgentTool. */
-    tools?: MountedTool[];
-    skills?: Skill[];
-    /**
-     * Extra providers registered on top of the built-ins — your own gateway / self-hosted endpoint / test fake —
-     * selected by the `model` spec's provider id.
-     */
-    providers?: Provider[];
-    /** Credentials file for stored OAuth/API-key auth (default `GLOBAL_AUTH_PATH`). */
-    authPath?: string;
-    /** The caller's own credential store, in place of any file ({@link CredentialSourceOptions}). */
-    credentialStore?: CredentialStore;
-    sessions?: PiSessionRecordStore;
-    /** Supplies the working directory at L1 (default: process.cwd()), which loads no definition. */
-    env?: ExecutionEnv;
-    /** Single-writer lease. */
-    lease?: Lease;
-    /** Observation-plane tap (session control): every rich session event of every run. */
-    observer?: SessionObserver;
-}
-/** L1: assemble from typed parts. */
-export declare function createPiAgent(options: CreatePiAgentOptions): Agent;
-/** L2 options. */
-export interface CreatePiAgentFromDefinitionOptions {
-    /**
-     * The default model spec "provider/modelId", resolved against {@link models}. Optional: without it, a session runs
-     * on the model it records, and one that records none fails its invoke with `missing_model`.
-     */
-    model?: string;
-    /** Reasoning effort (pi's scale). */
-    thinkingLevel?: ThinkingLevel;
-    /**
-     * Replaces pi's default prompt, as `SYSTEM.md` does, and outranks it. Required when `tools` replaces the coding
-     * tools and the directory has no `SYSTEM.md`: pi's default would claim tools the agent does not have.
-     */
-    base?: string;
-    tools?: MountedTool[];
-    /**
-     * The agent's working directory: where the coding tools operate AND whose ancestors are walked for ② project context
-     * (AGENTS.md).
-     */
-    cwd?: string;
-    /** Extra providers registered on top of the built-ins (your own gateway / self-hosted endpoint). */
-    providers?: Provider[];
-    /**
-     * Credentials file. Unset reads the directory's own layers (`resolveAuthLayers`); a named file is an instruction and
-     * gets no second layer.
-     */
-    authPath?: string;
-    /** The caller's own credential store, in place of any file ({@link CredentialSourceOptions}). */
-    credentialStore?: CredentialStore;
-    sessions?: PiSessionRecordStore;
-    /** Filesystem/process environment; see {@link CreatePiAgentOptions.env}. */
-    env?: ExecutionEnv;
-    lease?: Lease;
-    /** Observation-plane tap; see {@link CreatePiAgentOptions.observer}. */
-    observer?: SessionObserver;
-}
-/**
- * L2, as the value: load the directory (base + AGENTS.md + skills + env) and assemble. `models` is the directory's
- * model environment when the caller already built it (the opener, whose report must describe what runs); otherwise it
- * is built here from the credential options.
- */
-export declare function assemblePiFromDefinition(dir: string, options: Omit<CreatePiAgentFromDefinitionOptions, "observer"> & {
-    models?: AgentModels;
-}): Promise<{
-    assembly: PiAssembly;
-    definition: LoadedDefinition;
-}>;
-/** L2: "point at a directory → agent": {@link assemblePiFromDefinition} under the L0. */
-export declare function createPiAgentFromDefinition(dir: string, options: CreatePiAgentFromDefinitionOptions): Promise<{
-    agent: Agent;
-    definition: LoadedDefinition;
-}>;