@fastagent-sh/fastagent 0.12.0

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

@@ -0,0 +1,51 @@
+/**
+ * `fastagent login`: authenticate a MODEL PROVIDER into the resolved auth file (project-level
+ * `<dir>/.fastagent/auth.json` by default, or `--auth-path`/`FASTAGENT_AUTH_PATH`) via the same
+ * {@link fastagentCredentialStore} the runtime uses (one writer, one lock/corruption semantics).
+ *
+ * Flow (pi-ai's unified `ProviderAuth` API): pick a method (OAuth or API key), then a provider that
+ * offers it, then run `provider.auth.{oauth|apiKey}.login(callbacks)` and persist with `store.modify`
+ * (which refuses to clobber a corrupt file). The terminal IO and providers are injected, so the
+ * routing is testable without real stdin or a real auth round-trip.
+ */
+import type { CredentialStore, Provider } from "@earendil-works/pi-ai";
+/** One picker option: a stable `value`, a human `label`, and an optional `hint` (e.g. configured status). */
+export interface IoOption {
+    value: string;
+    label: string;
+    hint?: string;
+}
+/**
+ * Terminal interaction, injectable for tests (no real stdin/stdout or browser). The CLI implements it
+ * with `@clack/prompts` (a searchable list for many options, a hidden prompt for keys).
+ */
+export interface LoginIO {
+    /** Single-choice picker. Returns the chosen `value`, or undefined on cancel. */
+    select(message: string, options: IoOption[]): Promise<string | undefined>;
+    /** Free-text or hidden input. Returns the entered string, or undefined on cancel/abort. */
+    prompt(message: string, opts?: {
+        hidden?: boolean;
+        signal?: AbortSignal;
+    }): Promise<string | undefined>;
+    /** Print an informational line (auth URL, device code, progress). */
+    note(message: string): void;
+    /** Best-effort open a URL in the browser (printed regardless). */
+    openUrl(url: string): void;
+}
+export type LoginMethod = "oauth" | "api_key";
+export interface LoginResult {
+    provider: string;
+    method: LoginMethod;
+}
+/**
+ * Resolve method + provider (asking only what is not given), run the login flow, and persist. A no-op
+ * `modify` up front runs the refuse-corrupt check BEFORE the flow, so a known-bad file fails fast.
+ */
+export declare function loginFlow(io: LoginIO, options?: {
+    provider?: string;
+    method?: LoginMethod;
+    authPath?: string;
+    store?: CredentialStore;
+    providers?: Provider[];
+    signal?: AbortSignal;
+}): Promise<LoginResult>;

package/dist/engines/pi/login.js

@@ -0,0 +1,125 @@
+import { builtinProviders } from "@earendil-works/pi-ai/providers/all";
+import { GLOBAL_AUTH_PATH, fastagentCredentialStore } from "./auth.js";
+/** Combine present abort signals into one (no-op when none/one). */
+function anySignal(...signals) {
+    const present = signals.filter((s) => s !== undefined);
+    return present.length === 0 ? undefined : present.length === 1 ? present[0] : AbortSignal.any(present);
+}
+/**
+ * Map pi-ai's `AuthLoginCallbacks` onto the injected {@link LoginIO}. `doneSignal` fires when the flow
+ * resolves, cancelling a prompt the provider left pending (a manual-code paste racing a callback
+ * server it just won) so the one-shot CLI exits instead of hanging on stdin.
+ */
+function authCallbacks(io, userSignal, doneSignal) {
+    return {
+        signal: userSignal,
+        prompt: async (p) => {
+            if (p.type === "select") {
+                const v = await io.select(p.message, p.options.map((o) => ({ value: o.id, label: o.label, hint: o.description })));
+                if (v === undefined)
+                    throw new Error("cancelled");
+                return v;
+            }
+            const signal = anySignal(p.signal, userSignal, doneSignal);
+            const v = await io.prompt(p.message, { hidden: p.type === "secret", signal });
+            if (v === undefined)
+                throw new Error("cancelled");
+            return v;
+        },
+        notify: (e) => {
+            if (e.type === "auth_url") {
+                io.note(`Open this URL to authorize:\n  ${e.url}`);
+                if (e.instructions)
+                    io.note(e.instructions);
+                io.openUrl(e.url);
+            }
+            else if (e.type === "device_code") {
+                io.note(`Go to ${e.verificationUri} and enter the code:  ${e.userCode}`);
+                io.openUrl(e.verificationUri);
+            }
+            else {
+                io.note(e.message);
+            }
+        },
+    };
+}
+/** Providers offering the given method as an INTERACTIVE login (so `login` can actually run it). */
+function candidatesFor(providers, method) {
+    return providers.filter((p) => (method === "oauth" ? p.auth.oauth : p.auth.apiKey?.login));
+}
+async function selectMethod(io) {
+    const v = await io.select("Authentication method", [
+        { value: "oauth", label: "Use a subscription (OAuth)" },
+        { value: "api_key", label: "Use an API key" },
+    ]);
+    if (v !== "oauth" && v !== "api_key")
+        throw new Error("no authentication method selected");
+    return v;
+}
+/** Given a provider arg, pick the method it supports (asking only when it offers both). */
+async function methodForProvider(io, p) {
+    const hasOauth = !!p.auth.oauth;
+    const hasKeyLogin = !!p.auth.apiKey?.login;
+    if (hasOauth && hasKeyLogin)
+        return selectMethod(io);
+    if (hasOauth)
+        return "oauth";
+    if (hasKeyLogin)
+        return "api_key";
+    throw new Error(`provider "${p.id}" has no interactive login — set its API key via the provider's env var`);
+}
+/** List providers for the method with their configured status, and let the user pick one. */
+async function selectProvider(io, providers, method, store) {
+    const candidates = candidatesFor(providers, method);
+    if (candidates.length === 0)
+        throw new Error(`no provider supports ${method} login`);
+    const options = await Promise.all(candidates.map(async (p) => {
+        const cred = await store.read(p.id);
+        const auth = method === "oauth" ? p.auth.oauth : p.auth.apiKey;
+        return { value: p.id, label: auth?.name ?? p.name, hint: cred ? `configured (${cred.type})` : undefined };
+    }));
+    const id = await io.select("Select a provider", options);
+    if (!id)
+        throw new Error("no provider selected");
+    return id;
+}
+/**
+ * Resolve method + provider (asking only what is not given), run the login flow, and persist. A no-op
+ * `modify` up front runs the refuse-corrupt check BEFORE the flow, so a known-bad file fails fast.
+ */
+export async function loginFlow(io, options = {}) {
+    const store = options.store ?? fastagentCredentialStore(options.authPath ?? GLOBAL_AUTH_PATH);
+    const providers = options.providers ?? builtinProviders();
+    let method;
+    let providerId;
+    if (options.provider) {
+        providerId = options.provider;
+        const p = providers.find((x) => x.id === providerId);
+        if (!p)
+            throw new Error(`unknown provider "${providerId}"`);
+        method = options.method ?? (await methodForProvider(io, p));
+    }
+    else {
+        method = options.method ?? (await selectMethod(io));
+        providerId = await selectProvider(io, providers, method, store);
+    }
+    // Preflight: a no-op modify runs the refuse-corrupt / writability check BEFORE the flow.
+    await store.modify(providerId, async () => undefined);
+    const provider = providers.find((p) => p.id === providerId);
+    if (!provider)
+        throw new Error(`unknown provider "${providerId}"`);
+    const auth = method === "oauth" ? provider.auth.oauth : provider.auth.apiKey;
+    if (!auth?.login)
+        throw new Error(`provider "${providerId}" has no ${method} login`);
+    // `done` cancels any prompt left pending when login resolves (manual-code race backstop).
+    const done = new AbortController();
+    let credential;
+    try {
+        credential = await auth.login(authCallbacks(io, options.signal, done.signal));
+    }
+    finally {
+        done.abort();
+    }
+    await store.modify(providerId, async () => credential);
+    return { provider: providerId, method };
+}

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

@@ -0,0 +1,41 @@
+/**
+ * The pi `Models` collection — the single hub that owns BOTH model resolution (provider/modelId
+ * lookup) AND auth (per-request credential resolution). fastagent builds one per opener and threads
+ * it into the harness alongside the selected `model`; the two must come from the same collection so
+ * the model's provider auth is in scope.
+ */
+import { type Models, type Provider } from "@earendil-works/pi-ai";
+import { type FastagentAuthOptions } from "./auth.ts";
+export interface CreatePiModelsOptions extends FastagentAuthOptions {
+    /** Credentials file path. Defaults to the global `~/.fastagent/auth.json`; the directory opener passes
+     *  the project-level `<dir>/.fastagent/auth.json`. */
+    authPath?: string;
+    /** Extra providers registered on top of the built-ins (same id overrides a built-in). */
+    providers?: Provider[];
+}
+/**
+ * A `Models` with every built-in pi provider, wired to fastagent's auth: stored credentials from the
+ * {@link CreatePiModelsOptions.authPath} file (via {@link fastagentCredentialStore}; the global
+ * `~/.fastagent/auth.json` unless the opener passes a project-level path), then ambient env vars. A
+ * stored credential owns the provider; env is consulted only when nothing is stored (resolution order
+ * is upstream-owned).
+ */
+export declare function createPiModels(options?: CreatePiModelsOptions): Models;
+/**
+ * The "provider/modelId" specs whose provider currently has USABLE credentials (a stored login or an
+ * env key) — the menu for the first-run model picker (`fastagent dev`/`start`/`invoke` with no model
+ * set). Auth is provider-scoped, so probe once per provider (any of its models) rather than per model.
+ * A provider that resolves no auth (unconfigured) or rejects it (configured-but-expired) is omitted:
+ * the picker offers only models that would actually run now; `fastagent login` fixes the rest. Sorted.
+ *
+ * pi deliberately has no "best/tier" ranking on Model, so this does not auto-pick — it narrows the menu
+ * to what the user can use and lets them choose (mirroring pi-coding-agent's select-then-persist).
+ */
+export declare function configuredModelSpecs(models: Models): Promise<string[]>;
+/**
+ * Which source currently satisfies auth for `spec` — a startup diagnostic. Returns the upstream
+ * `AuthResult.source` label: `"OAuth"` for a stored OAuth credential (e.g. a logged-in openai-codex),
+ * `"stored credential"` for a stored API key, an env-var name like `"ANTHROPIC_API_KEY"` for env, or
+ * undefined when unconfigured. Reporting-only; never throws.
+ */
+export declare function probeAuthSource(models: Models, spec: string): Promise<string | undefined>;

package/dist/engines/pi/models.js

@@ -0,0 +1,76 @@
+/**
+ * The pi `Models` collection — the single hub that owns BOTH model resolution (provider/modelId
+ * lookup) AND auth (per-request credential resolution). fastagent builds one per opener and threads
+ * it into the harness alongside the selected `model`; the two must come from the same collection so
+ * the model's provider auth is in scope.
+ */
+import { defaultProviderAuthContext } from "@earendil-works/pi-ai";
+import { builtinModels } from "@earendil-works/pi-ai/providers/all";
+import { log } from "../../log.js";
+import { fastagentCredentialStore } from "./auth.js";
+/**
+ * A `Models` with every built-in pi provider, wired to fastagent's auth: stored credentials from the
+ * {@link CreatePiModelsOptions.authPath} file (via {@link fastagentCredentialStore}; the global
+ * `~/.fastagent/auth.json` unless the opener passes a project-level path), then ambient env vars. A
+ * stored credential owns the provider; env is consulted only when nothing is stored (resolution order
+ * is upstream-owned).
+ */
+export function createPiModels(options = {}) {
+    const models = builtinModels({
+        credentials: fastagentCredentialStore(options.authPath, { warn: options.warn }),
+        authContext: defaultProviderAuthContext(),
+    });
+    for (const provider of options.providers ?? [])
+        models.setProvider(provider);
+    return models;
+}
+/**
+ * The "provider/modelId" specs whose provider currently has USABLE credentials (a stored login or an
+ * env key) — the menu for the first-run model picker (`fastagent dev`/`start`/`invoke` with no model
+ * set). Auth is provider-scoped, so probe once per provider (any of its models) rather than per model.
+ * A provider that resolves no auth (unconfigured) or rejects it (configured-but-expired) is omitted:
+ * the picker offers only models that would actually run now; `fastagent login` fixes the rest. Sorted.
+ *
+ * pi deliberately has no "best/tier" ranking on Model, so this does not auto-pick — it narrows the menu
+ * to what the user can use and lets them choose (mirroring pi-coding-agent's select-then-persist).
+ */
+export async function configuredModelSpecs(models) {
+    const specs = [];
+    for (const provider of models.getProviders()) {
+        const [probe] = provider.getModels();
+        if (!probe)
+            continue;
+        let usable;
+        try {
+            usable = (await models.getAuth(probe)) !== undefined;
+        }
+        catch (error) {
+            // Configured-but-broken (expired token, a refresh network failure, a corrupt store): omit it
+            // from the menu, but SAY so — a silent disappearance is the same fail-visibly gap the caller
+            // guards against for the top-level enumeration. `undefined` (plainly unconfigured) stays quiet.
+            log.warn(`[fastagent] skipping provider "${provider.id}": auth check failed (${error.message})`);
+            continue;
+        }
+        if (!usable)
+            continue;
+        for (const model of provider.getModels())
+            specs.push(`${provider.id}/${model.id}`);
+    }
+    return specs.sort();
+}
+/**
+ * Which source currently satisfies auth for `spec` — a startup diagnostic. Returns the upstream
+ * `AuthResult.source` label: `"OAuth"` for a stored OAuth credential (e.g. a logged-in openai-codex),
+ * `"stored credential"` for a stored API key, an env-var name like `"ANTHROPIC_API_KEY"` for env, or
+ * undefined when unconfigured. Reporting-only; never throws.
+ */
+export async function probeAuthSource(models, spec) {
+    const slash = spec.indexOf("/");
+    if (slash < 1)
+        return undefined;
+    const model = models.getModel(spec.slice(0, slash), spec.slice(slash + 1));
+    if (!model)
+        return undefined;
+    const auth = await models.getAuth(model).catch(() => undefined);
+    return auth?.source;
+}

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

@@ -0,0 +1,13 @@
+/**
+ * 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. One copy so the wording can't drift.
+ */
+import type { SkillDiagnostic } from "@earendil-works/pi-agent-core";
+import type { SkillCollision } from "./definition.ts";
+import type { ModuleLoadFailure } from "../../loader.ts";
+import type { ToolCollision } from "./tool.ts";
+export declare function reportDefinitionWarnings(collisions: SkillCollision[], diagnostics: SkillDiagnostic[]): void;
+export declare function reportToolCollisions(collisions: ToolCollision[]): void;
+/** Report per-file module failures. The caller decides whether they are degradations (tools/schedules)
+ *  or fatal (declared channels on the serving path). */
+export declare function reportModuleLoadFailures(failures: ModuleLoadFailure[]): void;

package/dist/engines/pi/report.js

@@ -0,0 +1,21 @@
+import { log } from "../../log.js";
+export function reportDefinitionWarnings(collisions, diagnostics) {
+    for (const c of collisions) {
+        log.warn(`[fastagent] skill "${c.name}" collision — using ${c.winnerPath}, ignoring ${c.loserPath}`);
+    }
+    for (const d of diagnostics) {
+        log.warn(`[fastagent] ${d.code}: ${d.message} (${d.path})`);
+    }
+}
+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`);
+    }
+}
+/** Report per-file module failures. The caller decides whether they are degradations (tools/schedules)
+ *  or fatal (declared channels on the serving path). */
+export function reportModuleLoadFailures(failures) {
+    for (const f of failures) {
+        log.warn(`[fastagent] ${f.label} failed to load, skipping it — ${f.message}`);
+    }
+}

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

@@ -0,0 +1,15 @@
+import type { Session } from "@earendil-works/pi-agent-core";
+/** What fastagent needs from a session backend: open-or-create by opaque id. */
+export interface PiSessionStore {
+    openOrCreate(sessionId: string): Promise<Session>;
+}
+/** In-process store (pi InMemorySessionRepo). Continuity lives and dies with the instance. */
+export declare function inMemorySessionStore(): PiSessionStore;
+/**
+ * Disk-backed store (pi JsonlSessionRepo under `dir`): restart the process, conversations continue.
+ * `cwd` is recorded in session metadata; defaults to process.cwd().
+ */
+export declare function jsonlSessionStore(options: {
+    dir: string;
+    cwd?: string;
+}): PiSessionStore;

package/dist/engines/pi/sessions.js

@@ -0,0 +1,130 @@
+/**
+ * Session persistence — the K-axis port and its first two backends.
+ *
+ * PiSessionStore is the consumer-owned port: open-or-create by opaque session id, nothing more.
+ * pi's full SessionRepo surface (list/open/create/delete/fork) stays behind the adapters. The `Pi`
+ * prefix is honest — `openOrCreate` returns pi's `Session`, so this is pi-coupled, not a neutral
+ * persistence contract.
+ *
+ * Continuity = same backing store + same session id: in-memory continuity dies with the instance;
+ * jsonl survives process restarts (disk is the truth).
+ */
+import { InMemorySessionRepo } from "@earendil-works/pi-agent-core";
+import { JsonlSessionRepo, NodeExecutionEnv } from "@earendil-works/pi-agent-core/node";
+import { log } from "../../log.js";
+/**
+ * Crash-safety reconciliation, run on every OPEN of an existing session.
+ *
+ * A turn that dies mid tool-execution leaves an assistant `tool_use` with no matching result (pi
+ * persists the assistant message before the tool runs). The next turn would then hand the provider an
+ * `assistant(tool_use) -> user` sequence that Anthropic/OpenAI reject — the session is poisoned. We
+ * append an honest "interrupted" error result for each dangling call, restoring a valid transcript.
+ * Tool side-effect idempotency stays the tool's responsibility (SPEC §6); this only restores
+ * transcript validity, not exactly-once execution.
+ *
+ * Pairing is TURN-LOCAL: a tool_use is paired only by a toolResult that immediately follows it (up to
+ * the next non-toolResult). tool-call ids are not unique across turns (a local model may restart ids
+ * each response), so matching against the whole transcript could falsely settle a leaf call against an
+ * earlier turn's identical id. Append-only logs can only repair a gap AT THE LEAF (last assistant
+ * followed by nothing but its own results); an earlier gap is surfaced via log.warn rather than
+ * "fixed" with an orphaned result that appending cannot place.
+ *
+ * The synthetic result splits its audiences: `content` (read by the model, may reach the end user)
+ * stays neutral — it must NOT say "aborted" (pi's word for a user cancellation) or leak infra detail;
+ * `details` carries the operational marker for developers and is never sent to the provider.
+ */
+async function reconcileInterruptedToolCalls(session) {
+    const { messages } = await session.buildContext();
+    let leafIdx = -1;
+    for (let i = messages.length - 1; i >= 0; i--) {
+        if (messages[i]?.role === "assistant") {
+            leafIdx = i;
+            break;
+        }
+    }
+    if (leafIdx === -1)
+        return; // no assistant turn yet
+    const leafReparable = messages.slice(leafIdx + 1).every((m) => m.role === "toolResult");
+    const toRepair = [];
+    const orphaned = [];
+    messages.forEach((m, idx) => {
+        if (m.role !== "assistant")
+            return;
+        const paired = new Set();
+        for (let j = idx + 1; j < messages.length; j++) {
+            const next = messages[j];
+            if (next?.role !== "toolResult")
+                break;
+            paired.add(next.toolCallId);
+        }
+        for (const block of m.content) {
+            if (block.type !== "toolCall" || paired.has(block.id))
+                continue;
+            if (idx === leafIdx && leafReparable)
+                toRepair.push({ id: block.id, name: block.name });
+            else
+                orphaned.push(block.id);
+        }
+    });
+    if (orphaned.length > 0) {
+        log.warn(`[fastagent] unmatched tool_use is not at the session leaf; leaving it unreconciled ` +
+            `(an append-only log cannot repair a mid-history gap): toolCallIds=${orphaned.join(",")}`);
+    }
+    for (const { id, name } of toRepair) {
+        const result = {
+            role: "toolResult",
+            toolCallId: id,
+            toolName: name,
+            content: [
+                {
+                    type: "text",
+                    text: "This tool call did not complete and its result is unavailable. Re-run it if the result is still needed.",
+                },
+            ],
+            details: { fastagent: "interrupted-tool-call" },
+            isError: true,
+            timestamp: Date.now(),
+        };
+        await session.appendMessage(result);
+    }
+}
+/** In-process store (pi InMemorySessionRepo). Continuity lives and dies with the instance. */
+export function inMemorySessionStore() {
+    const repo = new InMemorySessionRepo();
+    return {
+        async openOrCreate(sessionId) {
+            const existing = (await repo.list()).find((m) => m.id === sessionId);
+            if (!existing)
+                return repo.create({ id: sessionId });
+            const session = await repo.open(existing);
+            await reconcileInterruptedToolCalls(session);
+            return session;
+        },
+    };
+}
+/**
+ * Disk-backed store (pi JsonlSessionRepo under `dir`): restart the process, conversations continue.
+ * `cwd` is recorded in session metadata; defaults to process.cwd().
+ */
+export function jsonlSessionStore(options) {
+    const cwd = options.cwd ?? process.cwd();
+    const repo = new JsonlSessionRepo({ fs: new NodeExecutionEnv({ cwd }), sessionsRoot: options.dir });
+    return {
+        async openOrCreate(sessionId) {
+            // Caller-provided ids land in jsonl FILENAMES — encode anything unsafe before it reaches disk.
+            const id = encodeSessionId(sessionId);
+            // Scope the lookup to this store's cwd: two stores sharing a sessionsRoot must not open each
+            // other's sessions (pi groups sessions by project dir).
+            const existing = (await repo.list({ cwd })).find((m) => m.id === id);
+            if (!existing)
+                return repo.create({ id, cwd });
+            const session = await repo.open(existing);
+            await reconcileInterruptedToolCalls(session);
+            return session;
+        },
+    };
+}
+/** Injective filename-safe encoding: [A-Za-z0-9._-] verbatim, the rest %-escaped. */
+function encodeSessionId(id) {
+    return id.replace(/[^A-Za-z0-9._-]/g, (c) => `%${c.charCodeAt(0).toString(16).toUpperCase().padStart(2, "0")}`);
+}

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

@@ -0,0 +1,17 @@
+/**
+ * The per-turn context a tool's `execute` can read (beyond its abort signal): the SESSION the current
+ * turn runs in. A `defineTool` tool is built ONCE and reused across sessions, so the session can't be a
+ * closure — it rides an AsyncLocalStorage set around the harness turn (invoke.ts) and read inside
+ * `execute` (tool.ts). Undefined outside a turn (e.g. `fastagent tool`, which runs a tool with no
+ * session). This is what lets a tool know which conversation it is in — the mechanism the agent's
+ * self-scheduling `wake` tool needs to fire a later turn back into the SAME session.
+ *
+ * Only `session` lives here (a per-turn runtime value). Deploy-time ambients a tool closes over at
+ * build time (e.g. a stateRoot) do NOT belong here — pass them via the tool's own closure.
+ */
+import { AsyncLocalStorage } from "node:async_hooks";
+export interface TurnContext {
+    /** The session id of the current turn. */
+    session: string;
+}
+export declare const turnContext: AsyncLocalStorage<TurnContext>;

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

@@ -0,0 +1,13 @@
+/**
+ * The per-turn context a tool's `execute` can read (beyond its abort signal): the SESSION the current
+ * turn runs in. A `defineTool` tool is built ONCE and reused across sessions, so the session can't be a
+ * closure — it rides an AsyncLocalStorage set around the harness turn (invoke.ts) and read inside
+ * `execute` (tool.ts). Undefined outside a turn (e.g. `fastagent tool`, which runs a tool with no
+ * session). This is what lets a tool know which conversation it is in — the mechanism the agent's
+ * self-scheduling `wake` tool needs to fire a later turn back into the SAME session.
+ *
+ * Only `session` lives here (a per-turn runtime value). Deploy-time ambients a tool closes over at
+ * build time (e.g. a stateRoot) do NOT belong here — pass them via the tool's own closure.
+ */
+import { AsyncLocalStorage } from "node:async_hooks";
+export const turnContext = new AsyncLocalStorage();

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

@@ -0,0 +1,45 @@
+import type { AgentTool } from "@earendil-works/pi-agent-core";
+import { z } from "zod";
+import { type ModuleLoadFailure } from "../../loader.ts";
+export interface ToolContext {
+    /** Abort signal for the current turn — honor it to cancel in-flight work on cancellation. */
+    signal?: AbortSignal;
+    /** The session id of the current turn — which conversation this tool is running in. A general tool
+     *  capability: partition per-conversation data, tag logs, scope state. Undefined outside a turn (a bare
+     *  `fastagent tool` run, or any call with no session). (The built-in `wake` tool is one consumer — it
+     *  fires a later turn back into this same session.) */
+    session?: string;
+}
+export interface DefineToolOptions<I extends z.ZodType> {
+    /** Explicit name. Usually omitted — a `tools/<name>.ts` tool is named from its filename. */
+    name?: string;
+    description: string;
+    input: I;
+    execute: (input: z.infer<I>, ctx: ToolContext) => unknown | Promise<unknown>;
+}
+export declare function defineTool<I extends z.ZodType>(options: DefineToolOptions<I>): AgentTool;
+/** A discarded same-name tool (within `tools/`, or against an existing tool). Surfaced, never silent. */
+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. A file broken for ANY reason — a failed import (from {@link loadModuleDir}) or not being a
+ * tool (no `execute`) — is ISOLATED into `failures` (skipped + reported, not thrown) so one broken file
+ * can't crash `start`; the agent serves the tools that loaded. A repo turned into an agent often has a
+ * `tools/` dir of its OWN scripts, which is exactly this case.
+ */
+export declare function loadTools(dir: string): Promise<{
+    tools: AgentTool[];
+    collisions: ToolCollision[];
+    failures: ModuleLoadFailure[];
+}>;
+/**
+ * Merge resolved tools (pi defaults + `config.tools`) with discovered `tools/`, deduped by name.
+ * Existing tools win; dropped discovered tools surface as collisions.
+ */
+export declare function mergeDiscoveredTools(existing: AgentTool[], discovered: AgentTool[]): {
+    tools: AgentTool[];
+    collisions: ToolCollision[];
+};

package/dist/engines/pi/tool.js

@@ -0,0 +1,85 @@
+/**
+ * Tool authoring: `defineTool` (the authoring surface) and `loadTools` (filesystem discovery).
+ * Drop a file in `tools/`, default-export `defineTool({...})`, and it is discovered, named from
+ * the filename, validated, and injected.
+ *
+ *   // tools/lookup-order.ts            → tool "lookup-order"
+ *   export default defineTool({
+ *     description: "Look up an order by id.",
+ *     input: z.object({ orderId: z.string() }),
+ *     async execute({ orderId }) { return await db.find(orderId); },
+ *   });
+ */
+import { join } from "node:path";
+import { z } from "zod";
+import { loadModuleDir } from "../../loader.js";
+import { turnContext } from "./tool-context.js";
+/** Wrap a plain return value into pi's tool-result shape; pass a full result through unchanged. */
+function wrapResult(value) {
+    if (value && typeof value === "object" && Array.isArray(value.content)) {
+        return value;
+    }
+    const text = typeof value === "string" ? value : JSON.stringify(value ?? null);
+    return { content: [{ type: "text", text }], details: value };
+}
+export function defineTool(options) {
+    const { $schema: _drop, ...parameters } = z.toJSONSchema(options.input);
+    const tool = {
+        name: options.name ?? "",
+        description: options.description,
+        parameters,
+        async execute(_toolCallId, rawParams, signal) {
+            const parsed = options.input.safeParse(rawParams);
+            if (!parsed.success) {
+                // Validation failure is reported TO THE MODEL (it can correct and retry), not thrown.
+                const detail = parsed.error.issues.map((i) => `${i.path.join(".") || "(root)"}: ${i.message}`).join("; ");
+                return { content: [{ type: "text", text: `Invalid arguments: ${detail}` }], details: { error: detail } };
+            }
+            return wrapResult(await options.execute(parsed.data, { signal, session: turnContext.getStore()?.session }));
+        },
+    };
+    return tool;
+}
+/**
+ * Discover code tools in `<dir>/tools/`: each `*.ts|.js|.mjs` default-exports a tool, named from its
+ * filename. A file broken for ANY reason — a failed import (from {@link loadModuleDir}) or not being a
+ * tool (no `execute`) — is ISOLATED into `failures` (skipped + reported, not thrown) so one broken file
+ * can't crash `start`; the agent serves the tools that loaded. A repo turned into an agent often has a
+ * `tools/` dir of its OWN scripts, which is exactly this case.
+ */
+export async function loadTools(dir) {
+    const { modules, failures } = await loadModuleDir(join(dir, "tools"));
+    const byName = new Map();
+    const collisions = [];
+    for (const { name, label, file, mod } of modules) {
+        const tool = mod.default;
+        if (!tool || typeof tool.execute !== "function") {
+            failures.push({ label, file, message: `${label} must default-export defineTool({...})` });
+            continue;
+        }
+        if (byName.has(name)) {
+            collisions.push({ name, source: label });
+            continue;
+        }
+        byName.set(name, { ...tool, name });
+    }
+    return { tools: [...byName.values()], collisions, failures };
+}
+/**
+ * Merge resolved tools (pi defaults + `config.tools`) with discovered `tools/`, deduped by name.
+ * Existing tools win; dropped discovered tools surface as collisions.
+ */
+export function mergeDiscoveredTools(existing, discovered) {
+    const names = new Set(existing.map((t) => t.name));
+    const tools = [...existing];
+    const collisions = [];
+    for (const tool of discovered) {
+        if (names.has(tool.name)) {
+            collisions.push({ name: tool.name, source: `tools/${tool.name}` });
+            continue;
+        }
+        names.add(tool.name);
+        tools.push(tool);
+    }
+    return { tools, collisions };
+}