@fastagent-sh/fastagent 0.24.4 → 0.26.0

package/dist/engines/pi/report.js

@@ -1,59 +0,0 @@
-/**
- * Render assembly warnings to stderr — the one place both the CLI runners and the `chat` runtime show the non-fatal
- * definition/tool findings the loaders return as data.
- */
-import { relative } from "node:path";
-import { log } from "../../log.js";
-/** Stable identity of a definition's non-fatal findings — the dedup key below. */
-function findingsSignature(def) {
-    const collisions = def.collisions.map((c) => `c:${c.name}:${c.winnerPath}:${c.loserPath}`);
-    const diagnostics = def.diagnostics.map((d) => `d:${d.code}:${d.path}`);
-    const shadowed = (def.shadowed ?? []).map((s) => `s:${s.what}:${s.winnerPath}:${s.loserPath}`);
-    const ignored = (def.ignored ?? []).map((i) => `i:${i.path}`);
-    return [...collisions, ...diagnostics, ...shadowed, ...ignored].sort().join("\n");
-}
-/** The last reported finding set PER DEFINITION DIR. */
-const lastFindings = new Map();
-/** THE door for definition findings: warns only when this dir's set CHANGED since the last report. */
-export function reportFindingsIfChanged(dir, def) {
-    const sig = findingsSignature(def);
-    if (lastFindings.get(dir) === sig)
-        return;
-    lastFindings.set(dir, sig);
-    reportDefinitionWarnings(def);
-}
-export function reportDefinitionWarnings(def) {
-    for (const c of def.collisions) {
-        log.warn(`[fastagent] skill "${c.name}" collision — using ${c.winnerPath}, ignoring ${c.loserPath}`);
-    }
-    for (const s of def.shadowed ?? []) {
-        log.warn(`[fastagent] ${s.what} is in two places — using ${s.winnerPath}, ignoring ${s.loserPath}`);
-    }
-    for (const i of def.ignored ?? []) {
-        log.warn(`[fastagent] ${i.path} is ${i.reason}`);
-    }
-    for (const d of def.diagnostics) {
-        log.warn(`[fastagent] ${d.code}: ${d.message} (${d.path})`);
-    }
-}
-/** What the agent's system prompt is made of, as a report line: pi's default or `SYSTEM.md`, plus an addendum. */
-export function describePrompt(def) {
-    const base = def.systemPrompt ? relative(def.dir, def.systemPrompt.path) : "pi's default";
-    return def.appendSystemPrompt ? `${base} + ${relative(def.dir, def.appendSystemPrompt.path)}` : base;
-}
-const REACH = {
-    tool_search: "loaded via tool_search",
-    codemode: "codemode scripts only",
-    hidden: "hidden",
-    inactive: "inactive until an authored loader activates it",
-    unreachable: "unreachable: pi's settings disable the built-in extension it needs",
-};
-/** The report line for the mounted tools the model is not given up front: each name with its way in. */
-export function describeIndirectTools(tools) {
-    return tools.map((tool) => `${tool.name} (${REACH[tool.reach]})`).join(", ");
-}
-export function reportToolCollisions(collisions) {
-    for (const c of collisions) {
-        log.warn(`[fastagent] tool "${c.name}" (${c.source}) dropped — a default/config tool already uses that name`);
-    }
-}

package/dist/engines/pi/retry-event.d.ts

@@ -1,6 +0,0 @@
-import type { AgentSessionEvent } from "@earendil-works/pi-coding-agent";
-import type { RetryScheduledEvent } from "../../session.ts";
-/** Manual compaction retries are session-scoped; retries inside an invoke carry its runId. */
-export declare function toRetryScheduledEvent(event: Extract<AgentSessionEvent, {
-    type: "auto_retry_start" | "summarization_retry_scheduled";
-}>, runId?: string): RetryScheduledEvent;

package/dist/engines/pi/retry-event.js

@@ -1,15 +0,0 @@
-/** Manual compaction retries are session-scoped; retries inside an invoke carry its runId. */
-export function toRetryScheduledEvent(event, runId) {
-    return {
-        type: "retry_scheduled",
-        timestamp: Date.now(),
-        ...(runId === undefined ? {} : { runId }),
-        data: {
-            operation: event.type === "auto_retry_start" ? "assistant" : "compaction",
-            attempt: event.attempt,
-            maxAttempts: event.maxAttempts,
-            delayMs: event.delayMs,
-            error: event.errorMessage,
-        },
-    };
-}

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

@@ -1,9 +0,0 @@
-/** `createAgentService` — the product as one call, with pi supplying the engine. */
-import { type AgentService, type MountAgentServiceOptions } from "../../service.ts";
-import type { CredentialSourceOptions } from "./auth.ts";
-export interface CreateAgentServiceOptions extends MountAgentServiceOptions, CredentialSourceOptions {
-    model?: string;
-    sessionsDir?: string;
-}
-/** Open an agent directory as a live service: one handler, mounted wherever you serve. */
-export declare function createAgentService(dir: string, options?: CreateAgentServiceOptions): Promise<AgentService>;

package/dist/engines/pi/service.js

@@ -1,14 +0,0 @@
-/** `createAgentService` — the product as one call, with pi supplying the engine. */
-import { mountAgentService } from "../../service.js";
-import { createPiAgentFromDir } from "./open.js";
-/** Open an agent directory as a live service: one handler, mounted wherever you serve. */
-export async function createAgentService(dir, options = {}) {
-    const opened = await createPiAgentFromDir(dir, {
-        ...(options.model !== undefined ? { model: options.model } : {}),
-        ...(options.authPath !== undefined ? { authPath: options.authPath } : {}),
-        ...(options.credentialStore !== undefined ? { credentialStore: options.credentialStore } : {}),
-        ...(options.sessionsDir !== undefined ? { sessionsDir: options.sessionsDir } : {}),
-        serving: true, // a mounted service is long-running: the scheduler poller runs
-    });
-    return mountAgentService(opened, options);
-}

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

@@ -1,13 +0,0 @@
-import { type AgentSessionRuntime, SessionManager } from "@earendil-works/pi-coding-agent";
-export interface BuildSessionRuntimeOptions {
-    /** Model spec override (the CLI --model flag). */
-    model?: string;
-    /** Credentials file override (the SDK `authPath` option; the CLI has only `FASTAGENT_AUTH_PATH`). */
-    authPath?: string;
-}
-/**
- * Build pi's interactive runtime over the SAME assembly `dev`/`start` serve ({@link assembleFront}): model
- * registry, prompt, tools, skills, reasoning effort and credentials all come from it, so what differs is only the
- * session's shape (one resident runtime rather than one session per invoke).
- */
-export declare function buildAgentSessionRuntime(dir: string, options?: BuildSessionRuntimeOptions, sessionManager?: SessionManager): Promise<AgentSessionRuntime>;

package/dist/engines/pi/session-builder.js

@@ -1,117 +0,0 @@
-/**
- * The shared definition-aware session builder: open a directory's assembled agent as a resident pi
- * `AgentSessionRuntime`, running the SAME agent that `dev`/`start` serve.
- */
-import { existsSync, readFileSync } from "node:fs";
-import { resolve } from "node:path";
-import { SessionManager, SettingsManager, createAgentSessionRuntime, getAgentDir, } from "@earendil-works/pi-coding-agent";
-import { bindPiSession, definitionServices } from "./agent-session-factory.js";
-import { missingDefaultModel, resolveModel } from "./config.js";
-import { canonicalPath } from "./definition.js";
-import { reportToolCollisions } from "./report.js";
-import { assembleFront, resolveAgentAssembly } from "./open.js";
-import { resolvePlacement } from "../../paths.js";
-/**
- * Build pi's interactive runtime over the SAME assembly `dev`/`start` serve ({@link assembleFront}): model
- * registry, prompt, tools, skills, reasoning effort and credentials all come from it, so what differs is only the
- * session's shape (one resident runtime rather than one session per invoke).
- */
-export async function buildAgentSessionRuntime(dir, options = {}, sessionManager) {
-    async function resolveAssembly() {
-        const front = await resolveAgentAssembly(dir, options);
-        // chat's TUI always starts a conversation, so it needs the default the served agent can do without.
-        const modelSpec = front.modelSpec;
-        if (!modelSpec)
-            throw missingDefaultModel();
-        reportToolCollisions(front.toolCollisions);
-        const { assembly } = await assembleFront(front);
-        // Read ONCE per runtime: a rebuild (/new, fork) keeps the startup snapshot, because config and tools stay in the
-        // import cache and a half-refreshed agent is worse than a stale one. Restart chat to pick up edits.
-        return { modelSpec, assembly, definition: await assembly.readDefinition() };
-    }
-    // The workspace, like serving's: where tools run and what session records are keyed to. Canonical, because pi's
-    // process.cwd() fallback is a realpath and a symlinked workspace would otherwise mismatch it.
-    const rootCwd = canonicalPath(resolvePlacement(dir).workspace);
-    // pi calls the factory again on /new, /resume, switch, and fork; the assembly is built once.
-    let assembly;
-    const assemblyFor = (cwd) => {
-        const activeCwd = canonicalPath(cwd);
-        if (activeCwd !== rootCwd) {
-            throw workspaceScopeError(activeCwd);
-        }
-        assembly ??= resolveAssembly();
-        return assembly;
-    };
-    const createRuntime = async ({ cwd, sessionManager, sessionStartEvent }) => {
-        const { modelSpec, assembly, definition } = await assemblyFor(cwd);
-        // Per session, NOT memoized with the assembly.
-        const modelRuntime = await assembly.createModelRuntime();
-        const loaded = await definitionServices({ cwd, modelRuntime, definition, extensionPaths: assembly.extensionPaths });
-        // ...while the SESSION keeps pi's own file-backed settings, so `/settings` in the TUI still saves. pi persists by
-        // re-reading the file under its lock and writing only the fields that changed, so `packages` there is untouched.
-        const services = { ...loaded, settingsManager: SettingsManager.create(cwd, loaded.agentDir) };
-        // AFTER the services, because an extension may be what defines the model.
-        const model = resolveModel(modelRuntime, modelSpec);
-        // Serving and chat restore the same native transcript declarations.
-        const result = await bindPiSession({
-            services,
-            sessionManager,
-            sessionStartEvent,
-            model,
-            // Always set, never left for pi to fill: pi resolves an ABSENT level from the machine's settings, and the effort
-            // is the definition's (`thinkingLevel` in fastagent.config.ts), like serving's.
-            thinkingLevel: assembly.thinkingLevel,
-            tools: assembly.tools,
-            excludedToolNames: assembly.excludedToolNames,
-            // A tool must see one spelling of the workspace, including when opened through a symlink.
-            cwd: rootCwd,
-        });
-        return { ...result, services, diagnostics: services.diagnostics };
-    };
-    const runtime = await createAgentSessionRuntime(createRuntime, {
-        cwd: rootCwd,
-        agentDir: getAgentDir(),
-        sessionManager: sessionManager ?? SessionManager.create(rootCwd),
-    });
-    enforceWorkspaceScopedSessionSwitches(runtime, rootCwd);
-    return runtime;
-}
-function workspaceScopeError(targetCwd) {
-    return new Error(`fastagent sessions are workspace-scoped: cannot switch to ${targetCwd}; open that workspace instead`);
-}
-function readSessionHeaderCwd(sessionPath) {
-    const resolvedPath = resolve(sessionPath);
-    if (!existsSync(resolvedPath))
-        return undefined;
-    for (const line of readFileSync(resolvedPath, "utf8").split(/\r?\n/)) {
-        if (!line.trim())
-            continue;
-        try {
-            const entry = JSON.parse(line);
-            if (entry.type === "session")
-                return typeof entry.cwd === "string" ? canonicalPath(entry.cwd) : undefined;
-        }
-        catch {
-            // Ignore malformed lines the same way pi's session loader does; no header cwd → caller pins root.
-        }
-    }
-    return undefined;
-}
-/** Keep resume/import inside the runtime's single workspace, deciding BEFORE delegating to pi. */
-function enforceWorkspaceScopedSessionSwitches(runtime, rootCwd) {
-    const rejectForeignTarget = (sessionPath, cwdOverride) => {
-        const target = cwdOverride !== undefined ? canonicalPath(cwdOverride) : readSessionHeaderCwd(sessionPath);
-        if (target !== undefined && target !== rootCwd)
-            throw workspaceScopeError(target);
-    };
-    const switchSession = runtime.switchSession.bind(runtime);
-    runtime.switchSession = async (...args) => {
-        rejectForeignTarget(args[0], args[1]?.cwdOverride);
-        return switchSession(...args);
-    };
-    const importFromJsonl = runtime.importFromJsonl.bind(runtime);
-    runtime.importFromJsonl = async (...args) => {
-        rejectForeignTarget(args[0], args[1]);
-        return importFromJsonl(...args);
-    };
-}

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

@@ -1,77 +0,0 @@
-/**
- * The pi implementation of the session control plane. `createPiSessionControl` returns the neutral
- * `SessionControl` plus the {@link SessionObserver} to plug into the invoke pipeline
- * (`createPiAgent({ observer })`).
- *
- * It holds no durable state of its own: live truth comes from the event stream (plus the
- * {@link RunControls} a `run_started` carries), durable truth from {@link PiSessionRecordStore} —
- * which is also what performs every write, so how a record takes a property is not knowledge this
- * file has. What it owns is the vocabulary: capability gating, the lease, error codes, and the
- * events its own writes emit.
- *
- * Writes take the same lease as runs. Without boundary wiring they reject before acceptance with
- * `unsupported_capability` — a client gating on `capabilities()` never sends them.
- */
-import type { ThinkingLevel } from "@earendil-works/pi-agent-core";
-import { type Models } from "@earendil-works/pi-ai";
-import { type AgentCommand, type SessionControl, type SessionEvent } from "../../session.ts";
-import { type SessionObserver, type Lease } from "./turn-kit.ts";
-import type { AnyModel } from "./models.ts";
-import type { PiAgentSessionFactory } from "./invoke-session.ts";
-import type { PiSessionRecordStore } from "./session-store.ts";
-/** Per-subscriber backlog limits: event count and UTF-8 JSON bytes. Overflow freezes the accepted
- *  prefix; the reader drains it before seeing done, then reconnects and backfills via entries(). */
-export declare const SUBSCRIBER_BUFFER_CAP = 10000;
-export declare const SUBSCRIBER_BUFFER_BYTES: number;
-/** What the plane's writes (`update` / `compact` / `fork` / `delete`) need — the SAME instances the
- *  agent assembly uses: the lease (a write must not race a run), the model registry (validation +
- *  allowedModels), and the session factory (compaction is a model call). Two writes create a record:
- *  fork's `into`, and `update()` on an id that has none (through the store's `openOrCreate`, like an
- *  invoke). Every other write needs a record that exists. */
-export interface PiBoundaryWiring {
-    lease: Lease;
-    models: Models;
-    sessionFactory: PiAgentSessionFactory;
-    /** The assembly's configured PAIR — what a session with no overrides runs on. One field because
-     *  model and thinking level are one setting: which levels exist is a property of the model, so a
-     *  wiring that could carry them apart could carry a pair no run uses. Must be what
-     *  {@link sessionFactory} was built with. No model when the agent sets no default: a session then runs on the model
-     *  it records, and `state()` of one that records none reports no model. */
-    defaults: {
-        model?: AnyModel;
-        thinkingLevel: ThinkingLevel;
-    };
-}
-export interface CreatePiSessionControlOptions {
-    /** Read-only access to the durable session records (the same root the agent writes). */
-    sessions: PiSessionRecordStore;
-    /** Boundary-mutation wiring — the assembly's own parts. Absent → boundary commands are gated off
-     *  in `capabilities()` and rejected `unsupported_capability`. */
-    boundary?: PiBoundaryWiring;
-    /** The definition's names, as an async thunk because the definition is live: this must re-read it,
-     *  not close over a boot snapshot, or `commands()` would advertise a list the next turn no longer
-     *  runs.
-     *
-     *  OPTIONAL because absence is a TRUE answer for the assembly that omits it: a hub over an L1
-     *  agent (`createPiAgent({ model, instructions, tools })`) has no definition and therefore no
-     *  names, and `[]` says exactly that. Wire it whenever the agent came from a DIRECTORY — there
-     *  `[]` would be a lie; the directory constructor (`createPiAgentFromDir`) always does. */
-    commands?: () => Promise<AgentCommand[]>;
-    /** Tap for the events the HUB ITSELF generates (boundary mutations: `state_changed`,
-     *  `compaction_*`) — those never pass through the data plane's observer seam, so a consumer
-     *  composing a full-vocabulary tap wires the run events via the observer AND this. Called after
-     *  the hub's own subscribers. */
-    tap?: (session: string, event: SessionEvent) => void;
-}
-/**
- * Build the observation hub. Wire `observer` into the SAME agent assembly that serves the sessions:
- *
- * ```ts
- * const { control, observer } = createPiSessionControl({ sessions });
- * const agent = createPiAgent({ ..., sessions, observer });
- * ```
- */
-export declare function createPiSessionControl(options: CreatePiSessionControlOptions): {
-    control: SessionControl;
-    observer: SessionObserver;
-};