@fastagent-sh/fastagent 0.24.3 → 0.25.0

package/dist/engines/pi/tool.js

@@ -1,118 +0,0 @@
-/** Tool authoring: `defineTool` (the authoring surface) and `loadTools` (filesystem discovery). */
-import { join } from "node:path";
-import { assertInsideAgentDir } from "../../paths.js";
-import { z } from "zod";
-import { loadModuleDir } from "../../loader.js";
-import { readSecretDeclaration, secretValues } from "../../declared-secrets.js";
-import { turnContext } from "./tool-context.js";
-/**
- * Ask the provider to constrain sampling to the tool's schema, the posture pi's own built-ins take. `"prefer"`
- * rather than `"require"`: a schema pi cannot express strictly, one using a keyword the provider's strict mode rejects
- * (Anthropic: numeric bounds, which every `z.number().int()` carries), or a provider without strict mode silently
- * falls back to an ordinary function tool instead of failing the turn.
- *
- * Nothing here has to undo pi's strict rewrite. To express "optional" strictly, pi marks every property required and
- * unions the optional ones with `null`, so a constrained model emits `null` where it would have omitted the key — and
- * pi-ai's `validateToolArguments` drops those nulls (`normalizeOptionalNulls`) before `execute` is called. It drops
- * one only where the author's OWN schema rejects null, so any nullable property keeps its `null`, and a
- * `.nullable().optional()` property can no longer distinguish "absent" from "null" — the one place this changes
- * what an author's `execute` receives.
- */
-const CONSTRAINED_SAMPLING = { type: "json_schema", strict: "prefer" };
-/** Wrap a plain return value into pi's tool-result shape; pass a full result through unchanged. */
-function wrapResult(value, output) {
-    if (value && typeof value === "object" && Array.isArray(value.content)) {
-        return value;
-    }
-    const structuredContent = output ? output.parse(value) : undefined;
-    const text = typeof value === "string" ? value : JSON.stringify(value ?? null);
-    return { content: [{ type: "text", text }], details: value, ...(output ? { structuredContent } : {}) };
-}
-// `S` defaults to the EMPTY tuple, not `readonly string[]`: a tool that declares nothing then gets
-// `ctx.secrets` with no keys, so `ctx.secrets.X_API_KEY` fails to compile instead of type-checking as
-// a `string` that is `undefined` at run time. "A typo is a compile error" has to hold for the tool
-// that forgot to declare, which is the one making the mistake.
-export function defineTool(options) {
-    const { $schema: _drop, ...parameters } = z.toJSONSchema(options.input);
-    const tool = {
-        name: options.name ?? "",
-        label: options.name ?? "",
-        description: options.description,
-        parameters,
-        constrainedSampling: CONSTRAINED_SAMPLING,
-        ...(options.exposure ? { exposure: options.exposure } : {}),
-        ...(options.defaultActive !== undefined ? { defaultActive: options.defaultActive } : {}),
-        ...(options.annotations ? { annotations: options.annotations } : {}),
-        ...(options.namespace ? { namespace: options.namespace } : {}),
-        ...(options.output ? { outputSchema: z.toJSONSchema(options.output) } : {}),
-        ...(options.executionMode ? { executionMode: options.executionMode } : {}),
-        ...(options.secrets?.length ? { secrets: options.secrets } : {}),
-        async execute(_toolCallId, rawParams, signal, onUpdate, context) {
-            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 },
-                    isError: true,
-                };
-            }
-            const store = turnContext.getStore();
-            return wrapResult(await options.execute(parsed.data, {
-                cwd: store?.cwd ?? process.cwd(),
-                signal,
-                sessionManager: store?.sessionManager,
-                tools: store?.tools,
-                // Per CALL, not per turn: pi binds `executeTool` to this call's id, the parent of what it runs.
-                executeTool: context?.executeTool,
-                onUpdate: onUpdate && ((partial) => onUpdate(wrapResult(partial))),
-                secrets: secretValues(options.secrets),
-            }), options.output);
-        },
-    };
-    return tool;
-}
-/** Discover code tools in `<dir>/tools/`: each `*.ts|.js|.mjs` default-exports a tool, named from its filename. */
-export async function loadTools(dir) {
-    // The same containment guard channels/routines/skills get.
-    await assertInsideAgentDir(dir, "tools");
-    const { modules, failures } = await loadModuleDir(join(dir, "tools"));
-    const byName = new Map();
-    const collisions = [];
-    const secrets = new Map();
-    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;
-        }
-        const declaration = readSecretDeclaration(tool, label);
-        if (declaration.error !== undefined) {
-            failures.push({ label, file, message: declaration.error });
-            continue;
-        }
-        if (byName.has(name)) {
-            collisions.push({ name, source: label });
-            continue;
-        }
-        byName.set(name, { ...tool, name });
-        secrets.set(name, declaration.secrets);
-    }
-    return { tools: [...byName.values()], secrets, collisions, failures };
-}
-/** Merge resolved tools (pi coding tools + `config.tools`) with discovered `tools/`, deduped by name. */
-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 };
-}

package/dist/engines/pi/turn-kit.d.ts

@@ -1,83 +0,0 @@
-import { type AssistantMessage, type ImageContent, type ToolResultMessage } from "@earendil-works/pi-ai";
-import { type AgentEvent, type Prompt } from "../../agent.ts";
-import type { AnswerOutcome, PromptDisposition, SessionEvent } from "../../session.ts";
-export type Release = () => void;
-export interface Lease {
-    /** Try to acquire exclusive write access for the session (fail-fast). */
-    tryAcquire(session: string): Release | null;
-}
-export declare function inProcessLease(): Lease;
-/** Classify `retryable`: structured status/code first, message prose only as the last-resort ceiling. */
-export declare function classifyRetryable(details: string, signal: {
-    status?: number;
-    code?: unknown;
-}): boolean;
-/**
- * How an answer ended, read off the stopReason pi records on the message. The ONE reading: `message_finished`,
- * the `assistant` entry `entries()` publishes, and the invoke terminal all derive from it, so the live outcome and
- * the recorded one cannot disagree.
- */
-export declare function answerOutcome(message: AssistantMessage): AnswerOutcome | undefined;
-/**
- * An answer's recorded thinking: its published thinking blocks, in order, joined with nothing between them, exactly as
- * their live deltas add up (the stream marks no block boundary, and the answer's `text` is joined the same way).
- * Undefined when it has none.
- */
-export declare function answerThinking(message: AssistantMessage): string | undefined;
-/** Whether a live thinking delta is streamed: the block it extends is one {@link answerThinking} will publish. */
-export declare function streamsThinkingDelta(event: {
-    contentIndex: number;
-    partial: AssistantMessage;
-}): boolean;
-/**
- * Whether a finished tool call asked to end its run (pi's `terminate`: returned by the tool, or set by a `tool_call`
- * hook that blocks it; pi 0.99.2's `tool_result` hook cannot set it). After a batch whose EVERY result asks it, pi
- * makes no further model call for that batch, so unless a queued steer or follow-up continues the run, it completes on
- * `tool` entries with no answer after them: the same shape a process killed after its tools leaves. A call made from
- * inside another tool (`parentToolCallId`, a codemode script) is not in the batch and does not count.
- * The ONE reading: the live `tool_finished` and the flag {@link markEndsRun} records both come from it.
- */
-export declare function asksToEndRun(event: {
-    result?: unknown;
-    parentToolCallId?: string;
-}): boolean;
-/**
- * The tool result message as pi then records it, carrying the request: pi's `createToolResultMessage` drops
- * `terminate` (as of pi 0.99.2), so without this nothing in the record says the run ended on purpose.
- */
-export declare function markEndsRun(message: ToolResultMessage): ToolResultMessage;
-/** Whether a recorded tool result carries {@link markEndsRun}'s flag. */
-export declare function endsRun(message: ToolResultMessage): boolean;
-/**
- * Terminal mapping, decided by the resolved message's outcome: pi's `prompt()` RESOLVES a message with stopReason
- * "error"/"aborted" rather than throwing, so relying on catch alone would miss that whole failure class and violate
- * SPEC MUST 1. A truncated final answer still completes the run.
- */
-export declare function toTerminal(message: AssistantMessage): AgentEvent;
-export declare function errorToTerminal(error: unknown): Extract<AgentEvent, {
-    type: "failed";
-}>;
-/**
- * Map prompt images to pi ImageContent. `prompt()` normalizes its images itself, with the bound model's resize
- * profile (`inputLimits.images.resize`) and format conversion, so a `"prompt"` delivery hands them over as-is.
- * `steer`/`followUp` do not, so a `"queued"` delivery resizes here with pi's default profile: the model is not known
- * yet when a queued message is prepared. pi's resizer is lazy-imported so the no-image path never loads its module
- * graph.
- */
-export declare function toPiPromptOptions(prompt: Prompt, delivery: "prompt" | "queued"): Promise<{
-    images?: ImageContent[];
-} | undefined>;
-/** Live modulation handles for one active run — what the control plane's `dispatch` routes to. */
-export interface RunControls {
-    steer(prompt: Prompt): Promise<PromptDisposition>;
-    followUp(prompt: Prompt): Promise<PromptDisposition>;
-    abort(): Promise<void>;
-}
-/** The DATA-plane observation seam: every rich event of every run, pushed as it happens. */
-export type SessionObserver = (session: string, event: SessionEvent, run?: RunControls) => void;
-/**
- * The SPEC projection of ONE run's rich stream. Stateful only for `tool_progress`, the one event that is a status
- * rather than a fact: an outer call's status line is sent when it changes, and a call that call makes, at any depth,
- * is its status. Nested calls are otherwise the observation plane's alone.
- */
-export declare function agentEventProjection(): (se: SessionEvent) => AgentEvent | null;

package/dist/engines/pi/turn-kit.js

@@ -1,275 +0,0 @@
-/** The turn mechanism's ENGINE-agnostic half: the parts that describe a turn rather than pi. */
-import { stripVTControlCharacters } from "node:util";
-import { contentText, } from "@earendil-works/pi-ai";
-import { ABORTED_CODE } from "../../agent.js";
-import { log } from "../../log.js";
-export function inProcessLease() {
-    const busy = new Set();
-    return {
-        tryAcquire(session) {
-            if (busy.has(session))
-                return null;
-            busy.add(session);
-            let released = false;
-            return () => {
-                if (released)
-                    return;
-                released = true;
-                busy.delete(session);
-            };
-        },
-    };
-}
-/** Clearly-transient network error codes (Node/undici), decisive on their own. */
-const RETRYABLE_CODES = new Set([
-    "ECONNRESET",
-    "ETIMEDOUT",
-    "ENETUNREACH",
-    "ENETDOWN",
-    "EAI_AGAIN",
-    "EPIPE",
-    "UND_ERR_CONNECT_TIMEOUT",
-    "UND_ERR_SOCKET",
-]);
-/** 429 (rate limit) and 5xx (server) are worth retrying; other statuses are decisive NON-retryable. */
-const statusIsRetryable = (status) => status === 429 || (status >= 500 && status < 600);
-/** Last-resort prose match, used only when no structured status/code is available. */
-const RETRYABLE_MESSAGE = /\b(429|5\d\d|timeout|timed out|rate.?limit|overloaded|ECONNRESET|ETIMEDOUT|ENETUNREACH|EAI_AGAIN|socket hang up)\b/i;
-/** A structured status/code decision, or `null` when the signal is absent/undecisive → fall to prose. */
-function retryableFromSignal(signal) {
-    if (typeof signal.status === "number")
-        return statusIsRetryable(signal.status);
-    const { code } = signal;
-    if (typeof code === "number")
-        return statusIsRetryable(code);
-    if (typeof code === "string") {
-        if (RETRYABLE_CODES.has(code))
-            return true;
-        if (/^\d{3}$/.test(code))
-            return statusIsRetryable(Number(code)); // a status carried as a string
-    }
-    return null; // no code, or an unknown one — not decisive on its own
-}
-/** Classify `retryable`: structured status/code first, message prose only as the last-resort ceiling. */
-export function classifyRetryable(details, signal) {
-    return retryableFromSignal(signal) ?? RETRYABLE_MESSAGE.test(details);
-}
-/** Pull a structured status/code off a thrown error (HTTP status or a network code, incl. its cause). */
-function errorSignal(error) {
-    if (!error || typeof error !== "object")
-        return {};
-    const e = error;
-    const status = typeof e.status === "number" ? e.status : typeof e.statusCode === "number" ? e.statusCode : undefined;
-    const causeCode = e.cause && typeof e.cause === "object" ? e.cause.code : undefined;
-    return { status, code: e.code ?? causeCode };
-}
-/** Pull the structured error `code` pi records on a failed message's diagnostics. */
-function messageSignal(message) {
-    const diagnostics = message.diagnostics ?? [];
-    for (let i = diagnostics.length - 1; i >= 0; i--) {
-        const code = diagnostics[i]?.error?.code;
-        if (code !== undefined)
-            return { code };
-    }
-    return {};
-}
-/**
- * How an answer ended, read off the stopReason pi records on the message. The ONE reading: `message_finished`,
- * the `assistant` entry `entries()` publishes, and the invoke terminal all derive from it, so the live outcome and
- * the recorded one cannot disagree.
- */
-export function answerOutcome(message) {
-    const error = message.errorMessage ? { error: { message: message.errorMessage } } : {};
-    switch (message.stopReason) {
-        case "error":
-            return { status: "failed", ...error };
-        case "aborted":
-            return { status: "aborted", ...error };
-        case "length":
-            return { status: "truncated" };
-        default:
-            return undefined;
-    }
-}
-/**
- * Whether a thinking block is PUBLISHED: readable reasoning. A redacted one holds a provider's opaque payload and a
- * placeholder (pi writes "[Reasoning redacted]" for it), not reasoning anyone can read, so it is neither streamed nor
- * read back. The ONE rule: the live `message_delta { channel: "thinking" }` ({@link streamsThinkingDelta}) and the
- * `assistant` entry's `thinking` ({@link answerThinking}) both apply it, so a client reads the same text either way.
- *
- * One exception, by when the flag is read: live reads it as each delta arrives, the record as the answer ended. pi's
- * Bedrock path flags a block redacted when its first encrypted chunk arrives, and its readable text and its encrypted
- * chunks are separate fields, so a block that streamed readable text BEFORE turning redacted had that text streamed
- * and is then not read back. Not separable after the fact: the record keeps one flag and one string per block, with
- * pi's placeholder appended. Whether a Bedrock model sends both in one block is unverified.
- */
-function isPublishedThinking(block) {
-    return block?.type === "thinking" && block.redacted !== true;
-}
-/**
- * An answer's recorded thinking: its published thinking blocks, in order, joined with nothing between them, exactly as
- * their live deltas add up (the stream marks no block boundary, and the answer's `text` is joined the same way).
- * Undefined when it has none.
- */
-export function answerThinking(message) {
-    const text = message.content
-        .filter(isPublishedThinking)
-        .map((block) => block.thinking)
-        .join("");
-    return text === "" ? undefined : text;
-}
-/** Whether a live thinking delta is streamed: the block it extends is one {@link answerThinking} will publish. */
-export function streamsThinkingDelta(event) {
-    return isPublishedThinking(event.partial.content[event.contentIndex]);
-}
-/**
- * Whether a finished tool call asked to end its run (pi's `terminate`: returned by the tool, or set by a `tool_call`
- * hook that blocks it; pi 0.99.2's `tool_result` hook cannot set it). After a batch whose EVERY result asks it, pi
- * makes no further model call for that batch, so unless a queued steer or follow-up continues the run, it completes on
- * `tool` entries with no answer after them: the same shape a process killed after its tools leaves. A call made from
- * inside another tool (`parentToolCallId`, a codemode script) is not in the batch and does not count.
- * The ONE reading: the live `tool_finished` and the flag {@link markEndsRun} records both come from it.
- */
-export function asksToEndRun(event) {
-    return !event.parentToolCallId && event.result?.terminate === true;
-}
-/**
- * The tool result message as pi then records it, carrying the request: pi's `createToolResultMessage` drops
- * `terminate` (as of pi 0.99.2), so without this nothing in the record says the run ended on purpose.
- */
-export function markEndsRun(message) {
-    return { ...message, terminate: true };
-}
-/** Whether a recorded tool result carries {@link markEndsRun}'s flag. */
-export function endsRun(message) {
-    return message.terminate === true;
-}
-/**
- * Terminal mapping, decided by the resolved message's outcome: pi's `prompt()` RESOLVES a message with stopReason
- * "error"/"aborted" rather than throwing, so relying on catch alone would miss that whole failure class and violate
- * SPEC MUST 1. A truncated final answer still completes the run.
- */
-export function toTerminal(message) {
-    const outcome = answerOutcome(message);
-    if (outcome?.status === "aborted") {
-        // A deliberate stop (a control-plane or consumer abort), not an error — see {@link ABORTED_CODE} for the consumer
-        // contract (design §6).
-        const details = outcome.error?.message ?? "run aborted";
-        return { type: "failed", details, retryable: false, code: ABORTED_CODE };
-    }
-    if (outcome?.status === "failed") {
-        const details = outcome.error?.message ?? "model stopped: error";
-        return { type: "failed", details, retryable: classifyRetryable(details, messageSignal(message)) };
-    }
-    return { type: "completed" };
-}
-export function errorToTerminal(error) {
-    const details = error instanceof Error ? error.message : String(error);
-    return { type: "failed", details, retryable: classifyRetryable(details, errorSignal(error)) };
-}
-/**
- * Map prompt images to pi ImageContent. `prompt()` normalizes its images itself, with the bound model's resize
- * profile (`inputLimits.images.resize`) and format conversion, so a `"prompt"` delivery hands them over as-is.
- * `steer`/`followUp` do not, so a `"queued"` delivery resizes here with pi's default profile: the model is not known
- * yet when a queued message is prepared. pi's resizer is lazy-imported so the no-image path never loads its module
- * graph.
- */
-export async function toPiPromptOptions(prompt, delivery) {
-    if (!prompt.images || prompt.images.length === 0)
-        return undefined;
-    if (delivery === "prompt") {
-        return { images: prompt.images.map((img) => ({ type: "image", data: img.data, mimeType: img.mimeType })) };
-    }
-    const { resizeImage } = await import("@earendil-works/pi-coding-agent");
-    const images = await Promise.all(prompt.images.map(async (img, i) => {
-        const resized = await resizeImage(Buffer.from(img.data, "base64"), img.mimeType);
-        if (resized)
-            return { type: "image", data: resized.data, mimeType: resized.mimeType };
-        // `null` covers an image it cannot decode or shrink under the limit AND an image backend that did not load,
-        // and does not say which. pi's own tool-result path keeps the original in that case rather than drop what the
-        // sender attached, and so does this; a provider that refuses it fails the turn with its own message.
-        log.warn(`[fastagent] queued image ${i + 1} (${img.mimeType}) could not be resized; sending it as given — ` +
-            "the provider may refuse it");
-        return { type: "image", data: img.data, mimeType: img.mimeType };
-    }));
-    return { images };
-}
-/**
- * The SPEC projection of ONE run's rich stream. Stateful only for `tool_progress`, the one event that is a status
- * rather than a fact: an outer call's status line is sent when it changes, and a call that call makes, at any depth,
- * is its status. Nested calls are otherwise the observation plane's alone.
- */
-export function agentEventProjection() {
-    /** Each nested call's outer call, the one the stream announced with `tool_started`. */
-    const outerOf = new Map();
-    /** The status line each outer call last reported. */
-    const shown = new Map();
-    const progress = (id, text) => {
-        if (text === undefined || shown.get(id) === text)
-            return null;
-        shown.set(id, text);
-        return { type: "tool_progress", id, text };
-    };
-    return (se) => {
-        switch (se.type) {
-            case "message_delta": {
-                const d = se.data;
-                return d.channel === "text" ? { type: "text", delta: d.delta } : { type: "thinking", delta: d.delta };
-            }
-            case "tool_started": {
-                const d = se.data;
-                if (!d.parentToolCallId)
-                    return { type: "tool_started", id: d.id, name: d.name, args: d.args };
-                const outer = outerOf.get(d.parentToolCallId) ?? d.parentToolCallId;
-                outerOf.set(d.id, outer);
-                return progress(outer, callLine(d.name, d.args));
-            }
-            case "tool_progress": {
-                const d = se.data;
-                // A nested call's own output is not its caller's status; the nested call starting is (above).
-                if (d.parentToolCallId || !Array.isArray(d.partialResult.content))
-                    return null;
-                return progress(d.id, lastLine(contentText(d.partialResult.content, "\n")));
-            }
-            case "tool_finished": {
-                const d = se.data;
-                if (d.parentToolCallId)
-                    return null;
-                return { type: "tool_ended", id: d.id, isError: d.isError, content: d.content };
-            }
-            case "retry_scheduled": {
-                // `operation` (compaction | branch_summary) stays session-plane vocabulary.
-                const d = se.data;
-                return {
-                    type: "retrying",
-                    attempt: d.attempt,
-                    maxAttempts: d.maxAttempts,
-                    delayMs: d.delayMs,
-                    reason: d.error,
-                };
-            }
-            default:
-                return null;
-        }
-    };
-}
-/**
- * The line a terminal shows last: control sequences removed, and a bare `\r`, a progress bar redrawing in place, ends a
- * line like `\n` does. Undefined when there is no visible text yet (a shell that has printed nothing).
- */
-function lastLine(text) {
-    const lines = stripVTControlCharacters(text).split(/\r\n|\r|\n/);
-    for (let i = lines.length - 1; i >= 0; i--) {
-        const line = lines[i]?.trim();
-        if (line)
-            return line;
-    }
-    return undefined;
-}
-/** A nested call as its caller's status: the tool and its first plain argument, on one line (`weather London`). */
-function callLine(name, args) {
-    const first = args !== null && typeof args === "object" && !Array.isArray(args)
-        ? Object.values(args).find((value) => typeof value === "string" || typeof value === "number")
-        : undefined;
-    return first === undefined ? name : `${name} ${String(first).replace(/\s+/g, " ").trim()}`.trim();
-}

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

@@ -1,9 +0,0 @@
-import { type MountedTool } from "./tool.ts";
-/**
- * Parse a delay to milliseconds: a number is SECONDS; a string MUST carry a unit — `"<n><s|m|h|d>"` ("30m", "2h",
- * "1d").
- */
-export declare function parseDelayMs(input: string | number): number | undefined;
-export declare function withWakeTool(tools: MountedTool[], stateRoot: string, enabled: boolean): MountedTool[];
-/** Build the `wake` tool bound to `stateRoot` (where wake-ups persist). */
-export declare function makeWakeTool(stateRoot: string, now?: () => Date): MountedTool;

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

@@ -1,92 +0,0 @@
-/** The built-in `wake` tool: the agent's self-scheduling surface. */
-import { z } from "zod";
-import { addWakeup, removeWakeup } from "../../schedule/wakeups.js";
-import { defineTool } from "./tool.js";
-/**
- * Parse a delay to milliseconds: a number is SECONDS; a string MUST carry a unit — `"<n><s|m|h|d>"` ("30m", "2h",
- * "1d").
- */
-export function parseDelayMs(input) {
-    if (typeof input === "number")
-        return Number.isFinite(input) && input > 0 ? input * 1000 : undefined;
-    const m = input.trim().match(/^(\d+(?:\.\d+)?)\s*(s|m|h|d)$/i); // unit REQUIRED on a string
-    if (!m)
-        return undefined;
-    const mult = { s: 1_000, m: 60_000, h: 3_600_000, d: 86_400_000 }[m[2].toLowerCase()];
-    return Number(m[1]) * mult;
-}
-export function withWakeTool(tools, stateRoot, enabled) {
-    if (!enabled)
-        return tools;
-    // wake/unwake are a PAIR over one store: if the workspace defines EITHER name, mount NEITHER built-in.
-    if (tools.some((t) => t.name === "wake" || t.name === "unwake"))
-        return tools;
-    return [...tools, makeWakeTool(stateRoot), makeUnwakeTool(stateRoot)];
-}
-/** Build the `wake` tool bound to `stateRoot` (where wake-ups persist). */
-export function makeWakeTool(stateRoot, now = () => new Date()) {
-    return defineTool({
-        name: "wake",
-        description: "Schedule yourself to wake up later and continue in THIS conversation. ONE-SHOT: pass `in` — a " +
-            'duration string with a unit ("30m", "2h", "1d") or a number of seconds — to resume a task after a ' +
-            "delay. RECURRING: pass `cron` (5-field, optional `tz`) to wake repeatedly — use sparingly, and " +
-            "`unwake` with the returned id when the job is done. Exactly one of `in`/`cron`. When the time " +
-            "comes, a new turn runs in this same session with `prompt` as its instruction (tagged with the wake-up's " +
-            "id so you can tell it from a user message) — you keep the full context of this conversation. IMPORTANT: the woken turn's plain reply is NOT delivered to anyone — " +
-            "to reach the user it must call a delivery tool (e.g. a channel's send tool), exactly as a scheduled " +
-            "job would.",
-        input: z.object({
-            in: z
-                .union([z.string(), z.number()])
-                .optional()
-                .describe('one-shot delay: a duration string with a unit ("30m" / "2h" / "1d"), or a number of seconds'),
-            cron: z.string().optional().describe('recurring: a 5-field cron expression (e.g. "0 9 * * *")'),
-            tz: z.string().optional().describe('IANA timezone for `cron` (default "UTC")'),
-            prompt: z.string().min(1).describe("the instruction for the woken turn (runs in this same conversation)"),
-        }),
-        execute(input, ctx) {
-            const session = ctx.sessionManager?.getSessionId();
-            if (!session)
-                return "wake is only available inside a conversation (there is no session to resume).";
-            if ((input.in === undefined) === (input.cron === undefined)) {
-                return "pass exactly one of `in` (one-shot) or `cron` (recurring).";
-            }
-            if (input.cron !== undefined) {
-                // addWakeup validates the cron and DERIVES the first instant itself — one computation, one truth.
-                const r = addWakeup(stateRoot, { session, prompt: input.prompt, cron: input.cron, tz: input.tz }, now());
-                if (!r.ok)
-                    return r.error; // guardrail message the model can act on
-                return `OK — recurring wake ${r.id} (cron "${input.cron}"${input.tz ? ` ${input.tz}` : ""}), first at ${r.fireAt}: ${input.prompt}. Use unwake({ id: "${r.id}" }) to stop it.`;
-            }
-            const ms = parseDelayMs(input.in);
-            if (ms === undefined) {
-                return `couldn't parse "in" (${JSON.stringify(input.in)}) — use a unit like "30m" / "2h" / "1d", or a number of seconds (a bare number as text like "120" is rejected).`;
-            }
-            const at = new Date(now().getTime() + ms);
-            const r = addWakeup(stateRoot, { session, prompt: input.prompt, fireAt: at }, now());
-            if (!r.ok)
-                return r.error; // guardrail message the model can act on
-            return `OK — I'll wake up at ${r.fireAt} (id ${r.id}) to: ${input.prompt}. Use unwake({ id: "${r.id}" }) if it becomes unnecessary.`;
-        },
-    });
-}
-/**
- * Build the `unwake` tool: cancel one of THIS conversation's pending wake-ups by id (a wake/recurring that is no
- * longer needed).
- */
-function makeUnwakeTool(stateRoot) {
-    return defineTool({
-        name: "unwake",
-        description: "Cancel one of YOUR pending wake-ups (one-shot or recurring) by the id `wake` returned. Use it when " +
-            "a scheduled follow-up is no longer needed — especially to stop a recurring wake once its job is done.",
-        input: z.object({ id: z.string().min(1).describe("the wake-up id (returned by `wake`)") }),
-        execute(input, ctx) {
-            const session = ctx.sessionManager?.getSessionId();
-            if (!session)
-                return "unwake is only available inside a conversation.";
-            return removeWakeup(stateRoot, input.id, session)
-                ? `OK — wake-up ${input.id} cancelled.`
-                : `no pending wake-up ${input.id} in this conversation (already fired, or not yours).`;
-        },
-    });
-}

package/dist/loader.d.ts

@@ -1,41 +0,0 @@
-export interface DiscoveredModule {
-    /** Basename without extension — the authoritative name for tools/channels. */
-    name: string;
-    /** "tools/foo.ts"-style label for errors and collisions. */
-    label: string;
-    file: string;
-    mod: {
-        default?: unknown;
-    };
-}
-/** An agent module that failed to load, surfaced as data so its caller can report the exact file. */
-export interface ModuleLoadFailure {
-    /** "tools/foo.ts"-style label. */
-    label: string;
-    file: string;
-    /** The failure message (an import error carries {@link moduleLoadHint}). */
-    message: string;
-}
-/** A module the loader skipped, said once, the same way for tools, channels and routines. */
-export declare function reportModuleLoadFailures(failures: readonly ModuleLoadFailure[]): void;
-/**
- * THE REFUSAL every path that is about to RUN the agent shares: an enabled file under `tools/`, `channels/` or
- * `routines/` is a declaration, so one that cannot load means the agent is missing something its author said it
- * has. Starting anyway announces a ready service over an absent capability — a schedule that never fires, a tool the
- * model simply never gets — with nothing but one warning to find it by. Every failure is reported before this
- * throws, so a boot fixes all of them at once rather than one per restart.
- *
- * Inspecting a definition (`info`, `fastagent tool`) is NOT this path: it must survive a broken file in order to
- * report it.
- */
-export declare function refuseBrokenDeclarations(failures: readonly ModuleLoadFailure[]): void;
-/** Import every module the directory declares ({@link moduleInventory}). */
-export declare function loadModuleDir(subDir: string): Promise<{
-    modules: DiscoveredModule[];
-    failures: ModuleLoadFailure[];
-}>;
-/**
- * A hint for the two common dynamic-import failures — an uninstalled dependency or a non-ESM package — and empty
- * otherwise, so an unrelated error is reported on its own.
- */
-export declare function moduleLoadHint(error: NodeJS.ErrnoException): string;