@fastagent-sh/fastagent 0.24.4 → 0.26.0

package/dist/engines/pi/create.js

@@ -1,343 +0,0 @@
-/**
- * Agent assembly (configuration-time): the engine assets (tools, prompt) plus the reusable ladder that puts a pi agent
- * together.
- */
-import { toUSVString } from "node:util";
-import { NodeExecutionEnv } from "@earendil-works/pi-agent-core/node";
-import { createCodingTools, createPowerShellTool, createReadOnlyTools, } from "@earendil-works/pi-coding-agent";
-import { resolveModel } from "./config.js";
-import { isAgentcoreRuntime, isDeployedWorkspace } from "../../paths.js";
-import { loadAgentDefinition } from "./definition.js";
-import { reportFindingsIfChanged } from "./report.js";
-import { log } from "../../log.js";
-import { BUILTIN_EXTENSIONS, DISCOVERY, readMachine } from "./machine.js";
-import { loadTools, mergeDiscoveredTools } from "./tool.js";
-import { readSecretDeclaration } from "../../declared-secrets.js";
-import { createPiAgentFromSession } from "./invoke-session.js";
-import { piAgentSessionFactory } from "./agent-session-factory.js";
-import { DEFAULT_THINKING_LEVEL } from "./models.js";
-import { agentModels } from "./agent-models.js";
-import { piInMemorySessionRecordStore } from "./session-store.js";
-import { inProcessLease } from "./turn-kit.js";
-// ── §1 tools ─────────────────────────────────────────────────────────────────
-//
-// A directory agent gets every pi coding tool.
-/**
- * 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 const CODING_TOOL_NAMES = ["read", "grep", "find", "ls", "bash", "edit", "write"];
-export function piAllCodingTools(cwd) {
-    const mutating = createCodingTools(cwd, {
-        bash: {
-            spawnHook(context) {
-                const { env } = context;
-                const id = env.PI_SESSION_ID;
-                delete env.PI_SESSION_ID_ENCODING;
-                // OS environment strings cannot preserve NUL or unpaired UTF-16 surrogates.
-                if (id !== undefined && (id.includes("\u0000") || toUSVString(id) !== id)) {
-                    env.PI_SESSION_ID = JSON.stringify(id);
-                    env.PI_SESSION_ID_ENCODING = "json";
-                }
-                return context;
-            },
-        },
-    }).filter((tool) => tool.name !== "read");
-    return [...createReadOnlyTools(cwd), ...mutating];
-}
-/** Every tool an `AgentSession` registers on its own, whether or not a directory agent mounts it. */
-function piRegisteredToolNames(cwd) {
-    return [
-        ...createReadOnlyTools(cwd).map((tool) => tool.name),
-        ...createCodingTools(cwd).map((tool) => tool.name),
-        createPowerShellTool(cwd).name,
-    ];
-}
-/** Built-ins omitted by an explicit lower-level tool list. */
-function omittedBuiltinNames(mounted, cwd) {
-    const mountedNames = new Set(mounted.map((tool) => tool.name));
-    return [...new Set(piRegisteredToolNames(cwd))].filter((name) => !mountedNames.has(name));
-}
-function isDefaultActiveTool(tool) {
-    return ((!tool.exposure || tool.exposure === "direct" || tool.exposure === "model-only") && tool.defaultActive !== false);
-}
-/** The built-in extension a `codemode`/`deferred` tool is reached through ({@link DISCOVERY}). */
-function wayIn(tool) {
-    return tool.exposure === "codemode" || tool.exposure === "deferred" ? DISCOVERY[tool.exposure].extension : undefined;
-}
-/** Whether this machine leaves the tool's way in enabled (a tool that needs none always has one). */
-function hasWayIn(tool, builtinExtensions) {
-    const extension = wayIn(tool);
-    return extension === undefined || builtinExtensions.includes(extension);
-}
-function indirectReach(tool, builtinExtensions) {
-    if (isDefaultActiveTool(tool))
-        return undefined;
-    if (!hasWayIn(tool, builtinExtensions))
-        return "unreachable";
-    if (tool.exposure === "deferred")
-        return "tool_search";
-    if (tool.exposure === "codemode")
-        return "codemode";
-    if (tool.exposure === "hidden")
-        return "hidden";
-    // `defaultActive: false`: only an authored loader (`ToolContext.tools.activate`) brings it in.
-    return "inactive";
-}
-/**
- * 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 async function resolveAgentTools(config, agentDir, cwd) {
-    // Discovered `tools/` come from `agentDir` (the agent's own surface); the coding tools are rooted at `cwd`, the
-    // WORKSPACE.
-    const discovered = await loadTools(agentDir);
-    const configured = piAllCodingTools(cwd);
-    const configuredNames = new Set(configured.map((tool) => tool.name));
-    const configuredCollisions = [];
-    // The config.tools that actually MOUNT — collected here rather than re-derived from `config.tools`
-    // afterwards, so a tool dropped for sharing a coding tool's name cannot contribute a declaration
-    // (its body never runs, and gating a start on its secret would refuse to serve for nothing).
-    const mountedConfigTools = [];
-    for (const tool of config.tools ?? []) {
-        if (configuredNames.has(tool.name)) {
-            configuredCollisions.push({ name: tool.name, source: "config.tools" });
-            continue;
-        }
-        configuredNames.add(tool.name);
-        configured.push(tool);
-        mountedConfigTools.push(tool);
-    }
-    const merged = mergeDiscoveredTools(configured, discovered.tools);
-    const tools = merged.tools;
-    const toolCollisions = [...discovered.collisions, ...configuredCollisions, ...merged.collisions];
-    // `toolNames` is the AUTHOR's active-by-default surface (config.tools + tools/).
-    // The discovered tools that were DROPPED (a coding tool or config.tools already owns the name):
-    // asking the mounted set instead would read the winner's name as proof the loser is mounted.
-    const shadowed = new Set(merged.collisions.map((c) => c.name));
-    const { builtinExtensions } = await readMachine(cwd);
-    const defaultNames = new Set(CODING_TOOL_NAMES);
-    const toolNames = tools.filter((t) => !defaultNames.has(t.name) && isDefaultActiveTool(t)).map((t) => t.name);
-    return {
-        tools,
-        toolNames,
-        indirectTools: tools.flatMap((t) => {
-            const reach = defaultNames.has(t.name) ? undefined : indirectReach(t, builtinExtensions);
-            return reach ? [{ name: t.name, reach }] : [];
-        }),
-        toolCollisions,
-        toolFailures: discovered.failures,
-        // Mounted only, and config.tools are FastagentTools too, so a programmatic tool declares the
-        // same way a file does.
-        toolSecrets: new Map([
-            ...[...discovered.secrets].filter(([name]) => !shadowed.has(name)),
-            // A programmatic tool declares the same way a file does. The source names the ENTRY, not just
-            // the list: `source` has to point at something the author can find, and "config.tools" alone
-            // locates nothing when the list has several tools. The shape was already refused by config
-            // validation (config.ts), so a throw here means a FastagentConfig assembled in code bypassed
-            // it — still the caller's own object, so it fails loudly rather than being isolated.
-            ...mountedConfigTools.map((tool) => {
-                const declaration = readSecretDeclaration(tool, `config.tools "${tool.name}"`);
-                if (declaration.error !== undefined)
-                    throw new Error(declaration.error);
-                return [tool.name, declaration.secrets];
-            }),
-        ]),
-    };
-}
-// pi builds the prompt (its default, or SYSTEM.md in its place); FastAgent adds its own named sections after it.
-/** The tools pi's default prompt says the agent has ("reading files, executing commands, editing code"). */
-const CODING_IDENTITY_TOOLS = ["read", "bash", "edit", "write"];
-/**
- * Refuse a prompt that would claim tools the agent does not have: pi's default says the agent reads files, runs
- * commands and edits code, which an embedder that replaced the coding tools made false. A prompt of the agent's own
- * (`base`, or `SYSTEM.md`) describes it instead. Checked at assembly and on every turn, since `SYSTEM.md` is re-read
- * per turn and an agent may delete it.
- */
-function refuseDefaultPromptOverReplacedTools(tools, hasOwnPrompt) {
-    if (hasOwnPrompt)
-        return;
-    const mounted = new Set(tools.map((tool) => tool.name));
-    const missing = CODING_IDENTITY_TOOLS.filter((name) => !mounted.has(name));
-    if (missing.length === 0)
-        return;
-    throw new Error(`the coding tools were replaced (${missing.join(", ")} not mounted), so pi's default prompt, which says the agent ` +
-        `reads files, runs commands and edits code, does not describe this agent: pass \`base\` or write SYSTEM.md`);
-}
-/**
- * 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 function fastagentPromptSections(options) {
-    const sections = {};
-    const mountedNames = new Set(options.tools.map((tool) => tool.name));
-    // Only `deferred` tools are tool_search's to load (the session activates it for them); `codemode` ones are listed
-    // in codemode's own description, and an inactive direct tool is reached only through an authored activation.
-    // A disabled tool-search leaves them no way in, and naming tool_search would invite calls to a tool that is not there.
-    const deferredCount = options.tools.filter((tool) => tool.exposure === "deferred" && hasWayIn(tool, options.builtinExtensions)).length;
-    if (deferredCount > 0) {
-        sections.deferred_tools = `${deferredCount} additional tool(s) are registered but not loaded — use tool_search to find and load them before concluding a capability is missing.`;
-    }
-    // What takes effect when, and the agent's own path to a new capability, are the same on every host; only how long
-    // the storage lives differs, below. The skill it writes lives in the definition directory, which the next
-    // deployment replaces (or, on AgentCore, erases with everything else) — so the sentence says so, and where a skill
-    // that should outlast it has to go. A skill outside the definition would survive, but it is machine state, read
-    // once per process (machine.ts), so it would not be live.
-    const runtimeChanges = ` Markdown definition files are read each turn; changes to tools, channels or configuration take effect when the service restarts. To give yourself a new capability now, write a skill — a SKILL.md in your definition's skills/ directory, with any script it needs run through bash. It lasts until the next deployment replaces that directory, so a capability that should outlast it belongs in the author's release: propose it to them.${
-    // Named only when mounted (a serve; not a one-shot invoke), like the deferred tools above: naming a tool the model
-    // does not have invites calls to it.
-    mountedNames.has("wake") ? " To schedule your own follow-up work, use the wake tool." : ""}`;
-    // How long the storage lives is the HOST's answer, not a deployment-wide one: AgentCore's managed mount is reset by
-    // every deploy, so telling that agent to keep work "outside the definition" would name a location its next deploy
-    // erases.
-    if (isDeployedWorkspace()) {
-        sections.self_change = isAgentcoreRuntime()
-            ? `Your workspace survives restarts, including uncommitted work; /tmp does not. Every deployment of a new version resets this host's storage entirely, so anything that must outlive a deployment belongs in an external system (a git remote, an issue tracker, a database).${runtimeChanges}`
-            : `Your workspace survives restarts and deployments, including uncommitted work; /tmp does not. A new deployment replaces your definition directory with the author's release, so keep ongoing project work outside it.${runtimeChanges}`;
-    }
-    return sections;
-}
-/** Shared low-level wiring: resolve the model spec against the collection, default the K ports, build the parts. */
-function assemblePi(opts) {
-    const cwd = opts.cwd ?? opts.env?.cwd ?? process.cwd();
-    // Materialized here (not defaulted inside the L0) so the value carries the SAME lease instance the agent runs under
-    // — boundary mutations must contend on it.
-    const lease = opts.lease ?? inProcessLease();
-    const sessions = opts.sessions ?? piInMemorySessionRecordStore({ cwd });
-    const createModelRuntime = opts.models;
-    let registry;
-    const modelRuntime = () => {
-        registry ??= opts.catalog();
-        return registry;
-    };
-    let engine;
-    const resolveEngine = () => {
-        const spec = opts.model;
-        engine ??= modelRuntime().then((runtime) => ({
-            modelRuntime: runtime,
-            ...(spec ? { model: resolveModel(runtime, spec) } : {}),
-        }));
-        return engine;
-    };
-    // Deny omitted coding names so discovery cannot reintroduce tools a lower-level caller excluded.
-    const excludedToolNames = omittedBuiltinNames(opts.tools ?? [], cwd);
-    const sessionFactory = piAgentSessionFactory({
-        sessions,
-        engine: async () => ({ modelRuntime: await createModelRuntime() }),
-        ...(opts.model ? { modelSpec: opts.model } : {}),
-        thinkingLevel: opts.thinkingLevel,
-        tools: opts.tools,
-        readDefinition: opts.readDefinition,
-        cwd,
-        ...(opts.extensionPaths ? { extensionPaths: opts.extensionPaths } : {}),
-        excludedToolNames,
-    });
-    return {
-        lease,
-        sessionFactory,
-        modelRuntime,
-        createModelRuntime,
-        engine: resolveEngine,
-        thinkingLevel: opts.thinkingLevel ?? DEFAULT_THINKING_LEVEL,
-        tools: opts.tools ?? [],
-        excludedToolNames,
-        readDefinition: opts.readDefinition,
-        extensionPaths: opts.extensionPaths ?? [],
-    };
-}
-/** The agent an assembly runs as: the L0 over its lease and session factory. */
-export function agentOf(assembly, observer) {
-    return createPiAgentFromSession({ lease: assembly.lease, observer, sessionFactory: assembly.sessionFactory });
-}
-/** L1: assemble from typed parts. */
-export function createPiAgent(options) {
-    const { instructions, skills = [] } = options;
-    const models = agentModels(undefined, options, { providers: options.providers });
-    return agentOf(assemblePi({
-        model: options.model,
-        thinkingLevel: options.thinkingLevel,
-        models: models.createRuntime,
-        catalog: models.runtime,
-        // No instructions is an empty prompt, not pi's default: this path takes the prompt whole.
-        readDefinition: () => ({
-            systemPrompt: (typeof instructions === "function" ? instructions() : instructions) || " ",
-            skills,
-        }),
-        tools: options.tools,
-        sessions: options.sessions,
-        env: options.env,
-        lease: options.lease,
-    }), options.observer);
-}
-/**
- * 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 async function assemblePiFromDefinition(dir, options) {
-    // `dir` = the agent-definition dir; `cwd` (default = dir) is the run root where tools operate and whose ancestors are
-    // walked for project context.
-    const cwd = options.cwd ?? dir;
-    const env = options.env ?? new NodeExecutionEnv({ cwd });
-    // Boot-time load: fail-visibly at startup on a broken directory, and give callers the snapshot to report
-    // (skills/diagnostics/collisions).
-    const definition = await loadAgentDefinition(dir, { cwd, env });
-    const tools = options.tools ?? piAllCodingTools(cwd);
-    // Boot findings go through the SAME memoized reporter every later reader uses (report.ts, keyed by the resolved
-    // dir).
-    reportFindingsIfChanged(definition.dir, definition);
-    // pi treats an empty prompt as none and builds its default, so a blank `base` would look like a prompt of the
-    // caller's own while being nothing.
-    if (options.base !== undefined && options.base.trim() === "") {
-        throw new Error("`base` is empty: pass the prompt the agent should use, or leave `base` out for pi's default");
-    }
-    refuseDefaultPromptOverReplacedTools(tools, options.base !== undefined || definition.systemPrompt !== undefined);
-    const { providers } = options;
-    const models = options.models ?? agentModels(dir, options, { cwd, env, ...(providers ? { providers } : {}) });
-    // Built at boot, so a malformed models.json fails the assembly rather than its first turn. The directory's own
-    // models.json is what a turn resolves against, layered over the machine's (models.ts).
-    await models.runtime();
-    const { builtinExtensions } = await readMachine(cwd);
-    const unreachable = tools.filter((tool) => !hasWayIn(tool, builtinExtensions));
-    // Said once per assembly: the model cannot call these at all, while the tools themselves loaded fine.
-    for (const tool of unreachable) {
-        log.warn(`[fastagent] tool "${tool.name}" (exposure: ${tool.exposure}) cannot be reached: pi's settings disable ` +
-            `builtin:${wayIn(tool)}, its only way in`);
-    }
-    const assembly = assemblePi({
-        model: options.model,
-        thinkingLevel: options.thinkingLevel,
-        models: models.createRuntime,
-        catalog: models.runtime,
-        // The directory is the agent, LIVE: re-read the definition on every invoke, so AGENTS.md/skills edits (the
-        // author's, or the agent's own self-modification) take effect on the next turn with no process restart — restarts
-        // are reserved for code (tools/channels/config, module cache).
-        readDefinition: async () => {
-            const def = await loadAgentDefinition(dir, { cwd, env });
-            reportFindingsIfChanged(def.dir, def);
-            const systemPrompt = options.base ?? def.systemPrompt?.content;
-            refuseDefaultPromptOverReplacedTools(tools, systemPrompt !== undefined);
-            return {
-                ...(systemPrompt !== undefined ? { systemPrompt } : {}),
-                ...(def.appendSystemPrompt ? { appendSystemPrompt: def.appendSystemPrompt.content } : {}),
-                contextFiles: def.contextFiles,
-                sections: fastagentPromptSections({ tools, builtinExtensions }),
-                skills: def.skills,
-                prompts: def.prompts,
-            };
-        },
-        tools,
-        sessions: options.sessions,
-        // The catalog's own discovery: the models it registered and the extensions sessions load are one list.
-        extensionPaths: [...(await models.extensionPaths())],
-        cwd,
-        env,
-        lease: options.lease,
-    });
-    return { assembly, definition };
-}
-/** L2: "point at a directory → agent": {@link assemblePiFromDefinition} under the L0. */
-export async function createPiAgentFromDefinition(dir, options) {
-    const { assembly, definition } = await assemblePiFromDefinition(dir, options);
-    return { agent: agentOf(assembly, options.observer), definition };
-}

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

@@ -1,74 +0,0 @@
-import { type ExecutionEnv, type PromptTemplateDiagnostic, type Skill, type SkillDiagnostic } from "@earendil-works/pi-agent-core";
-/** A same-name skill collision (the discarded side). */
-export interface SkillCollision {
-    name: string;
-    winnerPath: string;
-    loserPath: string;
-}
-/**
- * Two places in the definition holding the same thing: `SYSTEM.md` and `.pi/SYSTEM.md`, or one prompt template in
- * `prompts/` and `.pi/prompts/`. The first is used; the other is reported, because it is a file the author wrote that
- * does nothing.
- */
-export interface DefinitionShadow {
-    what: string;
-    winnerPath: string;
-    loserPath: string;
-}
-/** A file the definition holds verbatim, with where it came from. */
-export interface DefinitionFile {
-    path: string;
-    content: string;
-}
-/** A prompt template of the definition's own (`prompts/`, `.pi/prompts/`). */
-export interface DefinitionPrompt {
-    name: string;
-    description?: string;
-    content: string;
-    filePath: string;
-}
-export type DefinitionDiagnostic = SkillDiagnostic | PromptTemplateDiagnostic;
-/** Result of loading a definition directory. */
-export interface LoadedDefinition {
-    /** Project-context files (AGENTS.md), sourced via pi's `loadProjectContextFiles`; pi renders them. */
-    contextFiles: Array<{
-        path: string;
-        content: string;
-    }>;
-    /** `SYSTEM.md`, else `.pi/SYSTEM.md`: replaces pi's default prompt. Absent → pi builds its default. */
-    systemPrompt?: DefinitionFile;
-    /** `APPEND_SYSTEM.md`, else `.pi/APPEND_SYSTEM.md`: added after the prompt, whichever it is. */
-    appendSystemPrompt?: DefinitionFile;
-    skills: Skill[];
-    prompts: DefinitionPrompt[];
-    /** Non-fatal per-file problems reported by pi's skill and prompt-template loaders. */
-    diagnostics: DefinitionDiagnostic[];
-    /** Same-name skill conflicts across the definition's skill directories (first wins). */
-    collisions: SkillCollision[];
-    /** Same-name files and prompt templates across the definition's locations (first wins). */
-    shadowed: DefinitionShadow[];
-    /** Paths that exist in the definition and are deliberately not loaded, each with why. */
-    ignored: Array<{
-        path: string;
-        reason: string;
-    }>;
-    /** Absolute agent-definition directory path. */
-    dir: string;
-}
-export interface LoadAgentDefinitionOptions {
-    /** Working directory whose ancestors are walked for context files. */
-    cwd?: string;
-    env?: ExecutionEnv;
-}
-/**
- * Read an agent definition: its prompt files, skills and prompt templates from `agentDir`; the project context from
- * pi's loadProjectContextFiles({ cwd, agentDir }).
- */
-export declare function loadAgentDefinition(agentDir: string, options?: LoadAgentDefinitionOptions): Promise<LoadedDefinition>;
-/** Extension entry-point FILES under `<agentDir>/extensions/`, empty when there are none. */
-export declare function loadExtensionPaths(agentDir: string, options?: {
-    cwd?: string;
-    env?: ExecutionEnv;
-}): Promise<string[]>;
-/** Resolve to a canonical (symlink-free) absolute path so comparisons match `process.cwd()`'s realpath. */
-export declare function canonicalPath(p: string): string;

package/dist/engines/pi/definition.js

@@ -1,236 +0,0 @@
-/**
- * Definition domain: read an agent definition directory into memory — its system prompt files, its skills and prompt
- * templates (each from the agent directory's root spelling first, then pi's `.pi/` and the standard `.agents/` ones),
- * and, until contexts exist, the AGENTS.md project context. docs/design/agent-model.md §2 is the rule this follows.
- */
-import { realpathSync } from "node:fs";
-import { join, resolve } from "node:path";
-import { BACKGROUND_CONTEXT, loadPromptTemplates, loadSkills, } from "@earendil-works/pi-agent-core";
-import { NodeExecutionEnv } from "@earendil-works/pi-agent-core/node";
-import { loadProjectContextFiles } from "@earendil-works/pi-coding-agent";
-import { log } from "../../log.js";
-import { assertInsideAgentDir } from "../../paths.js";
-/** Where each resource is read from, in order: the root spelling first, then pi's, then the standard one. */
-const SYSTEM_PROMPT_FILES = ["SYSTEM.md", ".pi/SYSTEM.md"];
-const APPEND_SYSTEM_PROMPT_FILES = ["APPEND_SYSTEM.md", ".pi/APPEND_SYSTEM.md"];
-const SKILL_DIRS = ["skills", ".pi/skills", ".agents/skills"];
-const PROMPT_DIRS = ["prompts", ".pi/prompts"];
-/** The file `SYSTEM.md` and `APPEND_SYSTEM.md` replaced. Refused rather than ignored: its text would do nothing. */
-const RETIRED_PERSONA = "persona.md";
-/**
- * Read an agent definition: its prompt files, skills and prompt templates from `agentDir`; the project context from
- * pi's loadProjectContextFiles({ cwd, agentDir }).
- */
-export async function loadAgentDefinition(agentDir, options = {}) {
-    // One resolved default for the working directory (env cwd AND the context-walk start), so they can never diverge if
-    // a caller passes a relative agentDir.
-    const cwd = options.cwd ?? agentDir;
-    const e = options.env ?? new NodeExecutionEnv({ cwd });
-    const rootResult = await e.absolutePath(agentDir, BACKGROUND_CONTEXT);
-    if (!rootResult.ok) {
-        throw new Error(`cannot resolve agent dir "${agentDir}": ${rootResult.error.message}`);
-    }
-    const root = rootResult.value;
-    await refuseRetiredPersona(e, root);
-    // Project context, following pi: the agentDir's own AGENTS.md + every AGENTS.md walking cwd up to root
-    // (loadProjectContextFiles).
-    const contextFiles = loadProjectContextFiles({ cwd, agentDir: root });
-    const shadowed = [];
-    const ignored = [];
-    const systemPrompt = await readFirstFile(e, root, SYSTEM_PROMPT_FILES, "system prompt", shadowed, ignored);
-    const appendSystemPrompt = await readFirstFile(e, root, APPEND_SYSTEM_PROMPT_FILES, "appended prompt", shadowed, ignored);
-    const { skills, diagnostics: skillDiagnostics, collisions } = await readSkills(e, root);
-    const { prompts, diagnostics: promptDiagnostics } = await readPrompts(e, root, shadowed);
-    ignored.push(...(await ignoredPaths(e, root)));
-    return {
-        contextFiles,
-        ...(systemPrompt ? { systemPrompt } : {}),
-        ...(appendSystemPrompt ? { appendSystemPrompt } : {}),
-        skills,
-        prompts,
-        diagnostics: [...skillDiagnostics, ...promptDiagnostics],
-        collisions,
-        shadowed,
-        ignored,
-        dir: root,
-    };
-}
-async function exists(e, path) {
-    const info = await e.fileInfo(path, BACKGROUND_CONTEXT);
-    if (info.ok)
-        return true;
-    if (info.error.code === "not_found")
-        return false;
-    throw new Error(`cannot read ${path}: ${info.error.message}`);
-}
-async function refuseRetiredPersona(e, root) {
-    const path = join(root, RETIRED_PERSONA);
-    if (!(await exists(e, path)))
-        return;
-    throw new Error(`${path} is no longer read. Move its text to SYSTEM.md to replace pi's default prompt with an identity of the ` +
-        `agent's own, or to APPEND_SYSTEM.md to add standing instructions to pi's default prompt, which already says ` +
-        `who the agent is (pi's coding assistant) — an identity written there gives the model two`);
-}
-/**
- * The first of `names` that exists, read; every later one that also exists is shadowed by it. A blank file counts as
- * absent and is reported: pi treats an empty prompt as none, so it would change nothing while looking like a prompt
- * of the agent's own.
- */
-async function readFirstFile(e, root, names, what, shadowed, ignored) {
-    let found;
-    for (const name of names) {
-        const path = join(root, name);
-        const read = await e.readTextFile(path, BACKGROUND_CONTEXT);
-        if (!read.ok) {
-            if (read.error.code === "not_found")
-                continue;
-            throw new Error(`cannot read ${path}: ${read.error.message}`);
-        }
-        if (read.value.trim() === "") {
-            ignored.push({ path, reason: `empty, so it is not used as the ${what}` });
-            continue;
-        }
-        if (found)
-            shadowed.push({ what, winnerPath: found.path, loserPath: path });
-        else
-            found = { path, content: read.value };
-    }
-    return found;
-}
-/** `.pi/extensions/` is pi's place for project extensions; a definition's are `extensions/`, and only those load. */
-async function ignoredPaths(e, root) {
-    const path = join(root, ".pi", "extensions");
-    return (await exists(e, path)) ? [{ path, reason: "not loaded: a definition's extensions live in extensions/" }] : [];
-}
-/** Extension entry-point FILES under `<agentDir>/extensions/`, empty when there are none. */
-export async function loadExtensionPaths(agentDir, options = {}) {
-    const cwd = options.cwd ?? agentDir;
-    const e = options.env ?? new NodeExecutionEnv({ cwd });
-    const rootResult = await e.absolutePath(agentDir, BACKGROUND_CONTEXT);
-    if (!rootResult.ok)
-        throw new Error(`cannot resolve agent dir "${agentDir}": ${rootResult.error.message}`);
-    const root = rootResult.value;
-    await assertInsideAgentDir(root, "extensions");
-    const dir = join(root, "extensions");
-    const listed = await e.listDir(dir, BACKGROUND_CONTEXT);
-    if (!listed.ok) {
-        if (listed.error.code === "not_found")
-            return [];
-        throw new Error(`cannot read ${dir}: ${listed.error.message}`);
-    }
-    const paths = [];
-    for (const entry of listed.value) {
-        if (entry.kind === "symlink") {
-            // EVERY symlink here is announced, without guessing whether it meant to be an extension.
-            warnSymlinkRefused(entry.path);
-            continue;
-        }
-        if (entry.name.endsWith(".ts") || entry.name.endsWith(".js")) {
-            if (entry.kind === "file")
-                paths.push(entry.path);
-            continue;
-        }
-        if (entry.kind === "file")
-            continue; // a README, a .json — not an extension, not a problem
-        const index = await firstRealFile(e, [join(entry.path, "index.ts"), join(entry.path, "index.js")]);
-        if (index.path) {
-            paths.push(index.path);
-        }
-        else if (!index.refused) {
-            // Silent when the index WAS found and refused for being a symlink.
-            log.warn(`[fastagent] ${entry.path} is not a loadable extension: expected index.ts or index.js ` +
-                `(pi's package.json "pi" manifest form is not supported here) — it will not be loaded`);
-        }
-    }
-    return paths.sort();
-}
-/** The first candidate that is a REAL file, and whether one was found but REFUSED as a symlink. */
-async function firstRealFile(e, candidates) {
-    let refused = false;
-    for (const candidate of candidates) {
-        const info = await e.fileInfo(candidate, BACKGROUND_CONTEXT);
-        if (!info.ok) {
-            if (info.error.code === "not_found")
-                continue;
-            throw new Error(`cannot read ${candidate}: ${info.error.message}`);
-        }
-        if (info.value.kind === "file")
-            return { path: candidate, refused };
-        if (info.value.kind === "symlink") {
-            warnSymlinkRefused(candidate);
-            refused = true;
-        }
-    }
-    return { refused };
-}
-function warnSymlinkRefused(path) {
-    log.warn(`[fastagent] ${path} is a symlink and will not be loaded: an extension must be a real file inside ` +
-        `the definition so it travels with the artifact — move it in. (If it is not an extension, ` +
-        `keep it outside extensions/ to silence this.)`);
-}
-/** The skills half of {@link loadAgentDefinition}. */
-async function readSkills(e, root) {
-    // The definition's OWN skills — its half of the answer, from every place it may keep one, the root spelling first.
-    // The machine's half is machine.ts's, and `withMachine` decides a name collision in this half's favour.
-    for (const dir of SKILL_DIRS)
-        await assertInsideAgentDir(root, dir);
-    const { skills: raw, diagnostics } = await loadSkills(e, SKILL_DIRS.map((dir) => join(root, dir)), BACKGROUND_CONTEXT);
-    const byName = new Map();
-    const collisions = [];
-    for (const skill of raw) {
-        // pi only warns about a `/` in a skill name, and loads it. The slash names the context a skill comes from, so a
-        // definition's own skill spelled that way could collide with a context's and is refused here.
-        if (skill.name.includes("/")) {
-            throw new Error(`skill "${skill.name}" (${skill.filePath}): a skill's name may not contain "/", which names the context a ` +
-                `skill comes from — rename it`);
-        }
-        const existing = byName.get(skill.name);
-        if (existing) {
-            collisions.push({ name: skill.name, winnerPath: existing.filePath, loserPath: skill.filePath });
-        }
-        else {
-            byName.set(skill.name, skill);
-        }
-    }
-    return { skills: [...byName.values()], diagnostics, collisions };
-}
-/** The prompt-template half: `prompts/`, then `.pi/prompts/`, first wins. */
-async function readPrompts(e, root, shadowed) {
-    const byName = new Map();
-    const diagnostics = [];
-    for (const dir of PROMPT_DIRS) {
-        await assertInsideAgentDir(root, dir);
-        const loaded = await loadPromptTemplates(e, join(root, dir), BACKGROUND_CONTEXT);
-        diagnostics.push(...loaded.diagnostics);
-        for (const template of loaded.promptTemplates) {
-            // pi's loader names a template after its file and reads direct children only, so this is its file.
-            const filePath = join(root, dir, `${template.name}.md`);
-            const existing = byName.get(template.name);
-            if (existing) {
-                shadowed.push({
-                    what: `prompt template "${template.name}"`,
-                    winnerPath: existing.filePath,
-                    loserPath: filePath,
-                });
-                continue;
-            }
-            byName.set(template.name, {
-                name: template.name,
-                ...(template.description ? { description: template.description } : {}),
-                content: template.content,
-                filePath,
-            });
-        }
-    }
-    return { prompts: [...byName.values()], diagnostics };
-}
-/** Resolve to a canonical (symlink-free) absolute path so comparisons match `process.cwd()`'s realpath. */
-export function canonicalPath(p) {
-    const resolved = resolve(p);
-    try {
-        return realpathSync(resolved);
-    }
-    catch {
-        return resolved;
-    }
-}

package/dist/engines/pi/entry-images.d.ts

@@ -1,14 +0,0 @@
-import type { SessionManager } from "@earendil-works/pi-coding-agent";
-import type { ImageRef } from "../../agent.ts";
-import type { EntryImage } from "../../session.ts";
-type Message = {
-    role: string;
-    content?: unknown;
-};
-/** `data.images` of the entry `entryId` holding `message`, absent when it has none. */
-export declare function entryImages(entryId: string, message: Message): {
-    images?: EntryImage[];
-};
-/** The image `ref` names in `record`, or undefined when it names none there. The inverse of `entryImages`. */
-export declare function imageAt(record: SessionManager, ref: string): ImageRef | undefined;
-export {};