@fastagent-sh/fastagent 0.24.4 → 0.25.0

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

@@ -1,430 +0,0 @@
-/** Session persistence for the `AgentSession` L0. */
-import { existsSync, mkdirSync, readdirSync, renameSync, rmSync, writeFileSync } from "node:fs";
-import { basename, dirname, join, resolve } from "node:path";
-import { contentText } from "@earendil-works/pi-ai";
-import { SessionManager } from "@earendil-works/pi-coding-agent";
-import { log } from "../../log.js";
-import { LEAF_ANCHOR, isConversationMessage, publishedLeaf, stampProvenance } from "./session-markers.js";
-import { activePath } from "./session-settings.js";
-import { copyBranchForInheritance, copyBranchInto, inheritanceCut, } from "./session-inheritance.js";
-/** A Caller's session id, as a name pi will accept. */
-export function piSessionId(sessionId) {
-    const hex = (c) => {
-        const code = c.charCodeAt(0);
-        return code < 0x100
-            ? `_${code.toString(16).toUpperCase().padStart(2, "0")}`
-            : `_u${code.toString(16).toUpperCase().padStart(4, "0")}`;
-    };
-    const body = sessionId.replace(/[^A-Za-z0-9.-]/g, hex).replace(/[.-]$/, hex);
-    return `s${body}`;
-}
-/**
- * {@link piSessionId} backwards — what `list()` needs, because a session id belongs to the CALLER and a record name is
- * storage detail.
- */
-export function callerSessionId(recordId) {
-    if (!recordId.startsWith("s"))
-        return undefined;
-    let out = "";
-    for (let i = 1; i < recordId.length; i++) {
-        const c = recordId[i];
-        if (c !== "_") {
-            out += c;
-            continue;
-        }
-        const wide = recordId[i + 1] === "u";
-        const start = i + (wide ? 2 : 1);
-        const width = wide ? 4 : 2;
-        const hex = recordId.slice(start, start + width);
-        if (hex.length !== width || !/^[0-9A-F]+$/.test(hex))
-            return undefined;
-        out += String.fromCharCode(Number.parseInt(hex, 16));
-        i = start + width - 1;
-    }
-    return out;
-}
-/** Disk-backed store under `dir`: restart the process, conversations continue. */
-export function piSessionRecordStore(options) {
-    const cwd = options.cwd ?? process.cwd();
-    // Resolved against the workspace this store serves, not against wherever the process happens to have been started.
-    const root = resolve(cwd, options.dir);
-    const own = join(root, OWN_RECORDS_DIR);
-    /** Where a forked record is finished before it becomes discoverable. */
-    const staging = join(own, ".staging");
-    /** An empty record under `id`, ON DISK (see {@link materialize}) and not yet discoverable. */
-    const stage = (id) => {
-        mkdirSync(staging, { recursive: true });
-        return materialize(SessionManager.create(cwd, staging, { id }), staging);
-    };
-    /** Fill a staged record and move it in — or leave nothing behind. */
-    const fillStaged = (id, fill) => {
-        const staged = stage(id);
-        // WHERE the record is, so cleanup deletes the file that exists rather than the path it used to have.
-        let published;
-        try {
-            fill(staged);
-            // Publishing is a mkdir + rename, and both can fail (EACCES, a store root on another filesystem).
-            published = publishStaged(staged);
-            return SessionManager.open(published, own);
-        }
-        catch (error) {
-            rmSync(published ?? staged.getSessionFile() ?? "", { force: true });
-            throw error;
-        }
-    };
-    /**
-     * Move a finished record into the store: one same-filesystem rename, so a reader sees the whole thing or nothing at
-     * all.
-     */
-    const publishStaged = (staged) => {
-        const file = staged.getSessionFile();
-        if (!file)
-            throw new Error(`staged record ${staged.getSessionId()} has no file to publish`);
-        mkdirSync(own, { recursive: true });
-        const target = join(own, basename(file));
-        renameSync(file, target);
-        return target;
-    };
-    /** Fork the named parent into `id`, or answer undefined so the caller starts empty. */
-    const inheritInto = async (sessionId, inherit) => {
-        const found = locate(inherit.parentSession);
-        if (!found) {
-            log.warn(`[fastagent] session "${sessionId}" names parent "${inherit.parentSession}", which has no record — starting empty`);
-            return undefined;
-        }
-        try {
-            const parent = SessionManager.open(found.path, found.dir);
-            const cut = inheritanceCut(parent, inherit.branchHints);
-            if (!cut)
-                return undefined;
-            return fillStaged(piSessionId(sessionId), (staged) => copyBranchForInheritance(parent, staged, cut.at));
-        }
-        catch (error) {
-            // Unattributed on purpose: this spans reading the parent AND writing the child.
-            log.warn(`[fastagent] could not inherit from "${inherit.parentSession}" into "${sessionId}" (${String(error)}) — starting empty`);
-            return undefined;
-        }
-    };
-    /**
-     * The unreadable records the last listing reported, so a polled endpoint states the condition once rather than once
-     * a second.
-     */
-    let lastUnreadable = "";
-    /**
-     * WHERE a session's record is — the one lookup every caller shares, so a fix to it (this store's own directory
-     * rather than pi's cwd-filtered listing) cannot reach three of the four.
-     */
-    const locate = (sessionId) => {
-        const path = recordPathIn(own, sessionId);
-        return path ? { path, dir: own } : undefined;
-    };
-    /** Open an existing record, or undefined. */
-    const openExisting = async (sessionId) => {
-        const found = locate(sessionId);
-        return found ? SessionManager.open(found.path, found.dir) : undefined;
-    };
-    return {
-        async openOrCreate(sessionId, inherit) {
-            const found = locate(sessionId);
-            if (found)
-                return SessionManager.open(found.path, found.dir);
-            mkdirSync(own, { recursive: true });
-            // Inheritance is a CREATE-path decision: an existing session above ignores it entirely, which is what makes it
-            // one-time by construction.
-            if (inherit) {
-                const inherited = await inheritInto(sessionId, inherit);
-                if (inherited)
-                    return inherited;
-            }
-            // The CALLER's id in every message above; pi's spelling only where pi names the file.
-            return materialize(SessionManager.create(cwd, own, { id: piSessionId(sessionId) }), own);
-        },
-        openIfExists: openExisting,
-        applyProperties: (sessionId, writes) => applyProperties(() => openExisting(sessionId), writes),
-        async list() {
-            const files = recordFiles(own);
-            const rows = [];
-            const unreadable = [];
-            for (const file of files) {
-                // A name this store did not write cannot be decoded back to a Caller id, and a row nobody can dial is worse
-                // than a row that is missing.
-                const session = callerSessionId(file.id);
-                if (!session)
-                    continue;
-                try {
-                    rows.push(summarize(session, SessionManager.open(file.path, own)));
-                }
-                catch (error) {
-                    // ONE unreadable record must not take the listing down — the other conversations are fine, and a GUI that
-                    // shows nothing is worse than one missing a row.
-                    unreadable.push(`${basename(file.path)} (${String(error)})`);
-                }
-                // A TURN for everything else.
-                await new Promise((resolve) => setImmediate(resolve));
-            }
-            // NEWEST ACTIVITY first.
-            rows.sort((a, b) => b.updatedAt - a.updatedAt);
-            // Said when the SET changes, not on every poll: this endpoint is polled once a second or so, and an unreadable
-            // record stays unreadable until someone acts on it.
-            const reported = unreadable.join("; ");
-            if (reported !== lastUnreadable) {
-                lastUnreadable = reported;
-                if (unreadable.length > 0) {
-                    log.warn(`[fastagent] ${unreadable.length} of ${files.length} session records in ${own} could not be read and are missing from this listing: ${reported}`);
-                }
-            }
-            return rows;
-        },
-        async fork(from, at, into, provenance) {
-            const parent = await openExisting(from);
-            if (!parent)
-                throw new Error(`session "${from}" has no record`);
-            // The port promises a NEW record, so the guarantee belongs here rather than in the one caller that happens to
-            // check.
-            if (await openExisting(into))
-                throw new Error(`session "${into}" already exists`);
-            fillStaged(piSessionId(into), (staged) => {
-                // METADATA FIRST, history last. pi has one leaf pointer and every append advances it, so whatever is written
-                // last becomes the fork's `leafEntryId`.
-                const name = parent.getSessionName();
-                // The name travels: a fork of "Deploy notes" that lists as untitled is a row a user cannot place.
-                if (name)
-                    staged.appendSessionInfo(name);
-                stampProvenance(staged, provenance);
-                copyBranchInto(parent, staged, at);
-            });
-        },
-        async delete(sessionId) {
-            const found = locate(sessionId);
-            if (!found)
-                return false;
-            // A record that cannot be deleted must not report success — the caller turns the throw into a coded failure,
-            // and the session is still there for the next attempt.
-            rmSync(found.path);
-            return true;
-        },
-    };
-}
-/** The property write, for both backends: the ONE place that knows how pi records a property. */
-async function applyProperties(open, writes) {
-    const record = await open();
-    if (!record)
-        return undefined;
-    const landed = [];
-    let moved = false;
-    let failure;
-    try {
-        if (writes.leafEntryId !== undefined) {
-            // A move to where the head ALREADY is asks for nothing: a client retry, or a UI firing on every selection, must
-            // not grow the session.
-            if (publishedLeaf(record) !== writes.leafEntryId) {
-                record.branch(writes.leafEntryId);
-                moved = true;
-            }
-            landed.push("leafEntryId");
-        }
-        if (writes.model) {
-            record.appendModelChange(writes.model.provider, writes.model.id);
-            landed.push("model");
-        }
-        if (writes.thinkingLevel !== undefined) {
-            record.appendThinkingLevelChange(writes.thinkingLevel);
-            landed.push("thinkingLevel");
-        }
-        if (writes.name !== undefined) {
-            record.appendSessionInfo(writes.name);
-            landed.push("name");
-        }
-    }
-    catch (error) {
-        // Held, not rethrown: what already landed still has to be reported, and the report is the only way a caller
-        // learns the record moved.
-        failure = error;
-    }
-    // THE ANCHOR, outside the try so a failed property write cannot skip it.
-    if (moved && record.getLeafId() === writes.leafEntryId) {
-        try {
-            record.appendCustomEntry(LEAF_ANCHOR, {});
-        }
-        catch (error) {
-            // The move is runtime-only and will not survive the next open, so it did NOT land: saying it did is the one
-            // thing a partial report cannot afford.
-            landed.splice(landed.indexOf("leafEntryId"), 1);
-            failure ??= error;
-        }
-    }
-    // READ BACK, never echo: pi rewrites a name (newlines collapse, ends trim), and the settings a path resolves to can
-    // change under a moved leaf.
-    const name = record.getSessionName();
-    // The PUBLISHED head, not pi's: the anchor above is ours, and a client must be told the position it asked for — the
-    // one it can find in `entries()`.
-    const leafEntryId = publishedLeaf(record);
-    let path;
-    try {
-        path = activePath(record);
-    }
-    catch (error) {
-        // An unreadable chain is the caller's decision (design §7), not a silent short path.
-        log.warn(`[fastagent] session ${record.getSessionId()}: written, active path unreadable: ${String(error)}`);
-    }
-    return {
-        landed,
-        ...(failure !== undefined ? { failure } : {}),
-        ...(name ? { name } : {}),
-        ...(leafEntryId ? { leafEntryId } : {}),
-        ...(path ? { path } : {}),
-    };
-}
-/**
- * The record files in a directory, newest first — pi names them `<ISO timestamp>_<id>.jsonl`, so the name sorts by
- * time and carries the id without opening anything.
- */
-/** WHERE a session's record file is, WITHOUT opening it. */
-function recordPathIn(own, sessionId) {
-    return recordFiles(own).find((f) => f.id === piSessionId(sessionId))?.path;
-}
-function recordFiles(dir) {
-    let names;
-    try {
-        names = readdirSync(dir);
-    }
-    catch (error) {
-        if (error.code !== "ENOENT")
-            throw error;
-        return [];
-    }
-    // UNORDERED.
-    return names
-        .filter((name) => name.endsWith(RECORD_SUFFIX))
-        .flatMap((name) => {
-        // The FIRST underscore: the timestamp holds none, and an encoded id may hold several (`piSessionId` escapes
-        // with `_`).
-        const cut = name.indexOf("_");
-        return cut < 0 ? [] : [{ path: join(dir, name), id: name.slice(cut + 1, -RECORD_SUFFIX.length) }];
-    });
-}
-/** One record as a conversation-list row. */
-function summarize(session, record) {
-    const entries = record.getEntries();
-    const createdAt = Date.parse(record.getHeader()?.timestamp ?? "") || 0;
-    // `|| 0` on both: an unparseable timestamp is NaN, and NaN in `updatedAt` serializes to `null` — which the contract
-    // types as a number and a client sorts by.
-    const lastAt = Date.parse(entries.at(-1)?.timestamp ?? "") || 0;
-    // A list row counts turns in the conversation, not the engine's system bookkeeping (`isConversationMessage`).
-    const messages = entries.filter(isConversationMessage);
-    const name = record.getSessionName();
-    const preview = firstUserText(messages);
-    return {
-        session,
-        ...(name ? { name } : {}),
-        createdAt,
-        updatedAt: Math.max(lastAt, createdAt),
-        messageCount: messages.length,
-        ...(preview ? { preview } : {}),
-    };
-}
-/**
- * The first user message with text in it, truncated by CODE POINT (a cut through a surrogate pair would put a lone
- * half in the row, which renders as U+FFFD).
- */
-function firstUserText(messages) {
-    for (const entry of messages) {
-        const message = entry.message;
-        if (message?.role !== "user")
-            continue;
-        // The engine's own reading of message text, on a SPACE: this is a one-line preview, where adjacent
-        // blocks running together would read as one word.
-        const text = contentText(message.content, " ");
-        // Cut to UTF-16 units FIRST: a pasted megabyte would otherwise become a million-element array on the way to
-        // keeping 200 of them.
-        if (text.trim())
-            return [...text.slice(0, PREVIEW_CHARS * 2)].slice(0, PREVIEW_CHARS).join("");
-    }
-    return undefined;
-}
-/** What pi names a record file. */
-const RECORD_SUFFIX = ".jsonl";
-/** How much of the first message a list row carries. */
-const PREVIEW_CHARS = 200;
-/** Where the records live, under the sessions directory the store is pointed at. */
-const OWN_RECORDS_DIR = "agent-session";
-/** Make a NEW record exist on disk before anyone can act on it. */
-function materialize(session, dir) {
-    const file = session.getSessionFile();
-    if (!file || existsSync(file))
-        return session; // in-memory, or already on disk
-    const header = session.getHeader();
-    if (!header)
-        return session;
-    mkdirSync(dirname(file), { recursive: true });
-    writeFileSync(file, `${JSON.stringify(header)}\n`, { flag: "wx" });
-    return SessionManager.open(file, dir);
-}
-/** In-process store: continuity lives and dies with the instance. */
-export function piInMemorySessionRecordStore(options = {}) {
-    const cwd = options.cwd ?? process.cwd();
-    const live = new Map();
-    return {
-        async openOrCreate(sessionId, inherit) {
-            // Keyed by the CALLER's id: the encoding exists to satisfy pi's filename rule, and in memory there are no
-            // filenames.
-            const existing = live.get(sessionId);
-            if (existing)
-                return existing;
-            const fresh = () => SessionManager.inMemory(cwd, { id: piSessionId(sessionId) });
-            // Same semantics as the durable store, different mechanism: with no file to fork, the parent's path is copied
-            // entry by entry.
-            const parent = inherit ? live.get(inherit.parentSession) : undefined;
-            if (inherit && !parent) {
-                log.warn(`[fastagent] session "${sessionId}" names parent "${inherit.parentSession}", which has no record — starting empty`);
-            }
-            let created;
-            if (inherit && parent) {
-                try {
-                    const staged = fresh();
-                    const cut = inheritanceCut(parent, inherit.branchHints);
-                    if (cut)
-                        copyBranchForInheritance(parent, staged, cut.at);
-                    created = staged;
-                }
-                catch (error) {
-                    log.warn(`[fastagent] could not inherit from "${inherit.parentSession}" into "${sessionId}" (${String(error)}) — starting empty`);
-                    created = fresh(); // the partially-copied one is discarded, never registered
-                }
-            }
-            else {
-                created = fresh();
-            }
-            live.set(sessionId, created);
-            return created;
-        },
-        async openIfExists(sessionId) {
-            return live.get(sessionId);
-        },
-        applyProperties: (sessionId, writes) => applyProperties(async () => live.get(sessionId), writes),
-        async list() {
-            // The SAME row builder the disk store uses, ordered the same way.
-            return [...live].map(([session, record]) => summarize(session, record)).sort((a, b) => b.updatedAt - a.updatedAt);
-        },
-        async fork(from, at, into, provenance) {
-            const parent = live.get(from);
-            if (!parent)
-                throw new Error(`session "${from}" has no record`);
-            // The port's promise, not the caller's: registering over a live session would replace its history outright.
-            if (live.has(into))
-                throw new Error(`session "${into}" already exists`);
-            // Entry-by-entry, like the in-memory inheritance path: there is no file to fork.
-            const staged = SessionManager.inMemory(cwd, { id: piSessionId(into) });
-            // METADATA FIRST, history last — the same order the disk store writes in, and for the same reason.
-            const name = parent.getSessionName();
-            if (name)
-                staged.appendSessionInfo(name);
-            stampProvenance(staged, provenance);
-            copyBranchInto(parent, staged, at);
-            live.set(into, staged);
-        },
-        async delete(sessionId) {
-            return live.delete(sessionId);
-        },
-    };
-}

package/dist/engines/pi/tool-context.d.ts

@@ -1,45 +0,0 @@
-/** Per-turn capabilities shared by every FastAgent-defined tool. */
-import { AsyncLocalStorage } from "node:async_hooks";
-import type { SessionEntry as PiSessionEntry, AgentSession } from "@earendil-works/pi-coding-agent";
-/** FastAgent's read-only port over the current conversation manager. */
-export interface ReadonlySessionManager {
-    getSessionId(): string;
-    getHeader(): Promise<{
-        id: string;
-        timestamp: string;
-    }>;
-    getBranch(): Promise<PiSessionEntry[]>;
-}
-/** pi's AgentSession as the port above — the SAME adapter for both of its consumers. */
-export declare function agentSessionManager(session: AgentSession, sessionId: string): ReadonlySessionManager;
-/**
- * The turn's tool-activation bridge — narrow closures over the CURRENT session (bound per turn), so a loader tool can
- * activate deferred tools mid-turn without tool.ts importing the engine. pi anchors the addition in the transcript
- * (a system message carrying `toolsAdded`, written after the batch of tool results the activating call belongs to),
- * so providers with native deferred loading keep their
- * prompt-cache prefix. The same transcript declarations restore the loadout on the next binding.
- */
-export interface ToolActivation {
-    /** Names of the currently ACTIVE tools. */
-    active(): string[];
-    /** Every registered tool (active or not). */
-    registered(): Array<{
-        name: string;
-        description: string;
-    }>;
-    /**
-     * ADDITIVE activation. Returns ONLY the names this call actually added — a name a batch sibling activated first
-     * is not in it. That return value is the caller's truth for both what to report and what to charge an activation
-     * cap: the call is atomic, but an `active()` -> await -> `activate()` sequence around it is not.
-     */
-    activate(names: string[]): string[];
-}
-/** The activation bridge over a live pi session — the ONE implementation, for both consumers. */
-export declare function sessionToolActivation(session: AgentSession): ToolActivation;
-export interface TurnContext {
-    /** Working directory for this execution. */
-    cwd?: string;
-    sessionManager?: ReadonlySessionManager;
-    tools?: ToolActivation;
-}
-export declare const turnContext: AsyncLocalStorage<TurnContext>;

package/dist/engines/pi/tool-context.js

@@ -1,31 +0,0 @@
-/** Per-turn capabilities shared by every FastAgent-defined tool. */
-import { AsyncLocalStorage } from "node:async_hooks";
-/** pi's AgentSession as the port above — the SAME adapter for both of its consumers. */
-export function agentSessionManager(session, sessionId) {
-    return {
-        getSessionId: () => sessionId,
-        async getHeader() {
-            const header = session.sessionManager.getHeader();
-            if (!header)
-                throw new Error("session has no metadata header");
-            return { id: sessionId, timestamp: header.timestamp };
-        },
-        async getBranch() {
-            return session.sessionManager.getBranch();
-        },
-    };
-}
-/** The activation bridge over a live pi session — the ONE implementation, for both consumers. */
-export function sessionToolActivation(session) {
-    return {
-        active: () => session.getActiveToolNames(),
-        registered: () => session.getAllTools().map((t) => ({ name: t.name, description: t.description ?? "" })),
-        activate(names) {
-            const current = session.getActiveToolNames();
-            session.setActiveToolsByName([...current, ...names]);
-            const before = new Set(current);
-            return session.getActiveToolNames().filter((name) => !before.has(name));
-        },
-    };
-}
-export const turnContext = new AsyncLocalStorage();

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

@@ -1,99 +0,0 @@
-import type { AgentTool } from "@earendil-works/pi-agent-core";
-import type { ExtensionToolContext, ToolAnnotations, ToolDefinition, ToolExposure, ToolNamespace } from "@earendil-works/pi-coding-agent";
-import { z } from "zod";
-import { type ModuleLoadFailure } from "../../loader.ts";
-import { type DeclaredSecret } from "../../declared-secrets.ts";
-import { type ReadonlySessionManager, type ToolActivation } from "./tool-context.ts";
-export interface ToolContext {
-    /** Working directory for this execution. */
-    cwd: string;
-    /** Abort signal for the current turn — honor it to cancel in-flight work on cancellation. */
-    signal?: AbortSignal;
-    sessionManager?: ReadonlySessionManager;
-    /**
-     * Tool activation for the current turn; Pi records changes in the transcript.
-     */
-    tools?: ToolActivation;
-    /**
-     * Run another mounted tool through pi's own pipeline: argument validation, the definition's `tool_call` and
-     * `tool_result` hooks, cancellation (this call's signal by default). It reaches the active `direct` tools and every
-     * `codemode` or `deferred` one. A tool failure comes back as `isError: true`, never as a rejection. The nested call
-     * is observed with `parentToolCallId` and does not enter the transcript. Undefined without a session
-     * (`fastagent tool`).
-     */
-    executeTool?: ExtensionToolContext["executeTool"];
-    /**
-     * Report progress while this call runs: a snapshot of everything so far (each call replaces the last), wrapped the
-     * way a return value is. Its last line is the call's status (`tool_progress` on the invoke stream); session-control
-     * observers receive the whole snapshot. Undefined when the caller takes no progress (`fastagent tool`).
-     */
-    onUpdate?: (partial: unknown) => void;
-    /** THE values of {@link DefineToolOptions.secrets}, keyed by the names this tool declared — read
-     *  from the process environment per call, so a value rotated THERE takes effect without a restart
-     *  (one rotated in `.secrets/.env` does not: that file is loaded once at startup). This is how a
-     *  tool gets a credential: reaching into `process.env` instead leaves the name undeclared, which
-     *  means nothing carries it to a deployed box and nothing checks it before the call fails. */
-    secrets: Record<string, string>;
-}
-export interface DefineToolOptions<I extends z.ZodType, S extends readonly string[] = readonly []> {
-    name?: string;
-    description: string;
-    input: I;
-    /** Pi's native visibility: direct (default), model-only, codemode, deferred, or hidden. */
-    exposure?: ToolExposure;
-    /** Direct tools start active unless false; settings may still select them. */
-    defaultActive?: boolean;
-    /**
-     * MCP-style hints about what the tool does (`readOnlyHint`, `destructiveHint`, `idempotentHint`, `openWorldHint`).
-     * Pi does not enforce them; a permission extension reads them from `pi.getAllTools()` to decide which calls to
-     * confirm, and treats a tool without them as possibly destructive.
-     */
-    annotations?: ToolAnnotations;
-    /** Groups the tool with related ones (`{ name, description? }`): codemode lists a namespace under one heading. */
-    namespace?: ToolNamespace;
-    /** Structured output schema for programmatic callers such as codemode. */
-    output?: z.ZodType;
-    /** pi's per-tool execution mode: "sequential" makes pi run any batch containing this tool serially. */
-    executionMode?: "sequential" | "parallel";
-    /**
-     * Env vars this tool needs (`secrets: ["X_API_KEY"]`). Their values arrive as `ctx.secrets.X_API_KEY`,
-     * typed from this list. Declaring buys the two guarantees a bare `process.env` read cannot have:
-     * `deploy` carries the value to the host without it being listed anywhere else, and `dev`/`start`
-     * REFUSE TO START while it is unset, naming this file — instead of the tool failing on its first
-     * real call (see src/declared-secrets.ts).
-     */
-    secrets?: S;
-    execute: (input: z.infer<I>, ctx: Omit<ToolContext, "secrets"> & {
-        secrets: Record<S[number], string>;
-    }) => unknown | Promise<unknown>;
-}
-/** AgentTool with Pi's optional per-call context; absent for sessionless CLI execution. */
-export type MountedTool = Omit<AgentTool, "execute"> & Pick<ToolDefinition, "exposure" | "defaultActive" | "annotations" | "namespace"> & {
-    execute(...args: [...Parameters<AgentTool["execute"]>, context?: ExtensionToolContext]): ReturnType<AgentTool["execute"]>;
-};
-/** A Pi tool with fastagent's declared secrets. */
-export type FastagentTool = MountedTool & {
-    /** {@link DefineToolOptions.secrets} — read back by `readSecretDeclaration`; pi ignores it. */
-    secrets?: readonly string[];
-};
-export declare function defineTool<I extends z.ZodType, const S extends readonly string[] = readonly []>(options: DefineToolOptions<I, S>): FastagentTool;
-/** A discarded same-name tool (within `tools/`, or against an existing tool). */
-export interface ToolCollision {
-    name: string;
-    source: string;
-}
-/** Discover code tools in `<dir>/tools/`: each `*.ts|.js|.mjs` default-exports a tool, named from its filename. */
-export declare function loadTools(dir: string): Promise<{
-    tools: AgentTool[];
-    /** What each loaded tool declared it needs, BY TOOL NAME and attributed to the file. Per tool
-     *  because whether a declaration counts depends on whether that tool ends up MOUNTED — a name
-     *  shadowed by a coding tool never runs ({@link resolveAgentTools} makes that call). */
-    secrets: Map<string, DeclaredSecret[]>;
-    collisions: ToolCollision[];
-    failures: ModuleLoadFailure[];
-}>;
-/** Merge resolved tools (pi coding tools + `config.tools`) with discovered `tools/`, deduped by name. */
-export declare function mergeDiscoveredTools(existing: MountedTool[], discovered: AgentTool[]): {
-    tools: MountedTool[];
-    collisions: ToolCollision[];
-};