@fastagent-sh/fastagent 0.24.4 → 0.26.0

package/dist/harnesses/pi-durable/stream.d.ts

@@ -0,0 +1,20 @@
+/**
+ * `messages.stream` (SPEC.md §6.2): send a message and deliver it as it is written, over the Agent's own reads.
+ * The session is watched before the message is sent, so nothing it writes afterwards is missed; a send whose key the
+ * session has seen delivers that message from wherever it is.
+ */
+import { type Entry, type Message, type MessageStreamEvent, type Page, type SendRequest, type SessionEvent } from "../../agent-api.ts";
+export interface StreamSource {
+    events(sessionId: string, after?: string): AsyncIterable<SessionEvent>;
+    /** A send, and whether its key had already been sent: the message is then delivered from where it is. */
+    admit(request: SendRequest): Promise<{
+        message: Message;
+        replayed: boolean;
+    }>;
+    get(sessionId: string, messageId: string): Promise<Message>;
+    entry(sessionId: string, entryId: string): Promise<Entry>;
+    entries(sessionId: string, options: {
+        after: string;
+    }): Promise<Page<Entry>>;
+}
+export declare function messageStream(source: StreamSource, request: SendRequest, signal: AbortSignal | undefined): AsyncIterable<MessageStreamEvent>;

package/dist/harnesses/pi-durable/stream.js

@@ -0,0 +1,221 @@
+/**
+ * `messages.stream` (SPEC.md §6.2): send a message and deliver it as it is written, over the Agent's own reads.
+ * The session is watched before the message is sent, so nothing it writes afterwards is missed; a send whose key the
+ * session has seen delivers that message from wherever it is.
+ */
+import { AgentError, agentError, errorData, hasEnded, } from "../../agent-api.js";
+const messageOf = (entry) => entry.kind === "user" ? entry.data.messageId : undefined;
+/**
+ * The next of `events`, a read that failed as the `stream_error` it is once the message has been delivered: a session
+ * watched again cannot reject the stream then, or a Caller would take a message already recorded for one refused.
+ */
+const nextOf = (events) => events.next().catch((error) => ({ done: false, value: failedRead(error) }));
+const failedRead = (error) => ({
+    type: "stream_error",
+    error: errorData(error instanceof AgentError
+        ? error
+        : agentError("internal", error instanceof Error ? error.message : String(error))),
+});
+export function messageStream(source, request, signal) {
+    const { sessionId } = request;
+    let active;
+    const leave = () => {
+        const current = active;
+        active = undefined;
+        void current?.return?.();
+    };
+    const follow = (after) => {
+        leave();
+        active = source.events(sessionId, after)[Symbol.asyncIterator]();
+        return active;
+    };
+    /** From the message's `user` entry, which arrives live, through its `done`. */
+    async function* live(watching, id) {
+        let opened = false;
+        for (let next = await watching.next(); !next.done; next = await watching.next()) {
+            const event = next.value;
+            if (event.type === "stream_error")
+                return yield event;
+            // A queued message withdrawn by a cancel ends without ever being taken.
+            if (event.type === "done" && event.message.id === id)
+                return yield event;
+            if (!opened && event.type === "entry" && messageOf(event.entry) === id)
+                opened = true;
+            if (opened)
+                yield event;
+        }
+    }
+    /**
+     * A running message sent again, whose `user` entry was written before: its entries so far, then live. What the
+     * session replays is held until the message is read again, since one that ended meanwhile may have been followed by
+     * the next message's entries.
+     */
+    async function* running(message) {
+        let opening;
+        try {
+            opening = await source.entry(sessionId, message.entryId);
+        }
+        catch (error) {
+            return yield failedRead(error);
+        }
+        const after = follow(message.entryId);
+        const held = [];
+        for (let next = await nextOf(after); !next.done; next = await nextOf(after)) {
+            const event = next.value;
+            if (event.type === "stream_error")
+                return yield event;
+            if (event.type !== "state") {
+                held.push(event);
+                continue;
+            }
+            let now;
+            try {
+                now = await source.get(sessionId, message.id);
+            }
+            catch (error) {
+                return yield failedRead(error);
+            }
+            if (hasEnded(now)) {
+                leave();
+                return yield* ended(now, opening, held);
+            }
+            yield { type: "entry", entry: opening };
+            yield* held;
+            yield event;
+            for (let next = await nextOf(after); !next.done; next = await nextOf(after)) {
+                const event = next.value;
+                yield event;
+                if (event.type === "stream_error")
+                    return;
+                if (event.type === "done" && event.message.id === message.id)
+                    return;
+            }
+            return;
+        }
+    }
+    /** An ended message: its entries through its answer, then its `done`. */
+    async function* ended(done, opening, held) {
+        const { entryId, answer } = done;
+        if (entryId === undefined)
+            return yield { type: "done", message: done };
+        try {
+            yield { type: "entry", entry: opening ?? (await source.entry(sessionId, entryId)) };
+        }
+        catch (error) {
+            return yield failedRead(error);
+        }
+        if (answer === undefined)
+            return yield { type: "done", message: done };
+        const through = held?.findIndex((event) => event.type === "entry" && event.entry.id === answer.entryId) ?? -1;
+        if (held !== undefined && through !== -1) {
+            yield* held.slice(0, through + 1).filter((event) => event.type === "entry");
+            return yield { type: "done", message: done };
+        }
+        let cursor = entryId;
+        for (;;) {
+            let page;
+            try {
+                page = await source.entries(sessionId, { after: cursor });
+            }
+            catch (error) {
+                return yield failedRead(error);
+            }
+            for (const entry of page.data) {
+                yield { type: "entry", entry };
+                if (entry.id === answer.entryId)
+                    return yield { type: "done", message: done };
+            }
+            if (page.next === undefined) {
+                return yield failedRead(agentError("internal", `the answer ${answer.entryId} of message ${done.id} is not in its session`));
+            }
+            cursor = page.next;
+        }
+    }
+    async function* events() {
+        try {
+            const watching = follow();
+            const snapshot = await watching.next();
+            if (snapshot.done || snapshot.value.type !== "state") {
+                if (!snapshot.done && snapshot.value.type === "stream_error")
+                    throw new AgentError(snapshot.value.error);
+                throw agentError("internal", "the session's events did not begin with its state");
+            }
+            const { message, replayed } = await source.admit(request);
+            yield { type: "message", message };
+            if (hasEnded(message)) {
+                leave();
+                yield* ended(message);
+            }
+            else if (replayed && message.status === "running" && message.entryId !== undefined) {
+                yield* running({ ...message, entryId: message.entryId });
+            }
+            else
+                yield* live(watching, message.id);
+        }
+        finally {
+            leave();
+        }
+    }
+    return { [Symbol.asyncIterator]: () => leavableIterator(events(), leave, signal) };
+}
+/**
+ * A stream the Caller can leave at any point. An async generator suspended on an await parks inside it, and
+ * `gen.return()` queues behind the pending `next()` (async-generator semantics), so leaving first ends what it awaits
+ * (`leave`), then returns the generator. Leaving also silences it: a generator on its way out can still reach a
+ * `yield`, which must not hand an event to a Caller that left. A `signal` leaves the same way, and the read pending
+ * then, and any after it, rejects with the signal's reason.
+ */
+function leavableIterator(gen, leave, signal) {
+    let left = false;
+    const teardown = async () => {
+        left = true;
+        leave();
+        await gen.return(undefined).catch(() => { });
+    };
+    const released = () => {
+        throw signal?.reason;
+    };
+    let onAbort;
+    const aborted = signal === undefined
+        ? undefined
+        : new Promise((_, reject) => {
+            onAbort = () => {
+                void teardown();
+                reject(signal.reason);
+            };
+            if (signal.aborted)
+                onAbort();
+            else
+                signal.addEventListener("abort", onAbort, { once: true });
+        });
+    aborted?.catch(() => { });
+    const stopListening = () => {
+        if (onAbort !== undefined)
+            signal?.removeEventListener("abort", onAbort);
+    };
+    return {
+        async next() {
+            if (signal?.aborted)
+                released();
+            const result = await (aborted === undefined ? gen.next() : Promise.race([gen.next(), aborted]));
+            if (left) {
+                if (signal?.aborted)
+                    released();
+                return { done: true, value: undefined };
+            }
+            if (result.done)
+                stopListening();
+            return result;
+        },
+        async return() {
+            stopListening();
+            await teardown();
+            return { done: true, value: undefined };
+        },
+        async throw(error) {
+            stopListening();
+            await teardown();
+            throw error;
+        },
+    };
+}

package/dist/harnesses/pi-durable/text.d.ts

@@ -0,0 +1,30 @@
+import { type PromptSection } from "@earendil-works/pi-durable";
+import type { ResolvedContent } from "../../content/resolve.ts";
+import type { AgentCommand } from "./agent.ts";
+export interface Skill {
+    name: string;
+    description: string;
+    /** Absolute: what the model's `read` opens. */
+    filePath: string;
+    baseDir: string;
+    /** Offered only through `/skill:<name>`, never listed to the model. */
+    disableModelInvocation: boolean;
+}
+/** The agent's skills: `skills/<name>/SKILL.md`. One that breaks the specification is reported and skipped. */
+export declare function readSkills(agentDir: string): Skill[];
+/** Arguments as a shell splits them: by whitespace, with `"…"` or `'…'` keeping one argument together. */
+export declare function parseArguments(text: string): string[];
+/**
+ * A template's text with its arguments, in pi's format: `$1`… positional, `$@` and `$ARGUMENTS` all of them,
+ * `${N:-default}` a positional one or its default, `${@:N}` and `${@:N:L}` a slice from the Nth.
+ */
+export declare function expandTemplate(body: string, args: readonly string[]): string;
+/** What a Caller may offer as `/<name>`: the prompt templates, then `skill:<name>` for each skill. */
+export declare function readCommands(agentDir: string): AgentCommand[];
+/**
+ * The prompt the definition contributes: `SYSTEM.md` as written, `AGENTS.md` as project context, the skills, where it
+ * works, and, deployed, what of a change it makes to itself lasts. `wake`: the agent has the wake tool.
+ */
+export declare function definitionSections(agentDir: string, content: readonly ResolvedContent[], options: {
+    wake: boolean;
+}): PromptSection[];

package/dist/harnesses/pi-durable/text.js

@@ -0,0 +1,292 @@
+/**
+ * The definition's text (architecture.md §3), read for each request so an edit takes effect on the next answer:
+ * `SYSTEM.md` and `AGENTS.md` as prompt sections, `skills/` as Agent Skills (agentskills.io) and `prompts/` as prompt
+ * templates. A skill is loaded as pi does it: the prompt lists each one's name, description and location, the model
+ * reads its `SKILL.md` when a task matches, and `/skill:<name>` loads it into the message.
+ */
+import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
+import { basename, join } from "node:path";
+import { section } from "@earendil-works/pi-durable";
+import { parse as parseYaml } from "yaml";
+import { log } from "../../log.js";
+import { isAgentcoreRuntime, isDeployedWorkspace } from "../../paths.js";
+const FRONTMATTER = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?/;
+const SKILL_NAME = /^[a-z0-9]+(-[a-z0-9]+)*$/;
+/** A file's YAML frontmatter and its body. A file without frontmatter is all body. */
+function frontmatter(text, file) {
+    const match = FRONTMATTER.exec(text);
+    if (match === null)
+        return { fields: {}, body: text };
+    const fields = parseYaml(match[1]);
+    if (fields !== null && (typeof fields !== "object" || Array.isArray(fields))) {
+        throw new Error(`${file}: its frontmatter is not a set of fields`);
+    }
+    return { fields: (fields ?? {}), body: text.slice(match[0].length) };
+}
+/** Each problem once per process: the text is read for every request, and a broken file should not flood the log. */
+const reported = new Set();
+function report(problem) {
+    if (reported.has(problem))
+        return;
+    reported.add(problem);
+    log.warn(`[fastagent] ${problem}; it is skipped`);
+}
+/** The directories in `dir`. An entry that cannot be read (a symlink to nothing) is reported and skipped. */
+function directories(dir) {
+    if (!existsSync(dir))
+        return [];
+    return readdirSync(dir)
+        .sort()
+        .filter((name) => {
+        if (name.startsWith("."))
+            return false;
+        try {
+            return statSync(join(dir, name)).isDirectory();
+        }
+        catch (error) {
+            report(`${join(basename(dir), name)}: ${error instanceof Error ? error.message : String(error)}`);
+            return false;
+        }
+    });
+}
+/** The agent's skills: `skills/<name>/SKILL.md`. One that breaks the specification is reported and skipped. */
+export function readSkills(agentDir) {
+    const root = join(agentDir, "skills");
+    const skills = [];
+    for (const entry of directories(root)) {
+        const baseDir = join(root, entry);
+        const filePath = join(baseDir, "SKILL.md");
+        const label = `skills/${entry}/SKILL.md`;
+        if (!existsSync(filePath))
+            continue;
+        let fields;
+        try {
+            ({ fields } = frontmatter(readFileSync(filePath, "utf8"), label));
+        }
+        catch (error) {
+            report(`${label}: ${error instanceof Error ? error.message : String(error)}`);
+            continue;
+        }
+        const name = fields.name ?? entry;
+        const { description } = fields;
+        if (typeof name !== "string" || name.length > 64 || !SKILL_NAME.test(name)) {
+            report(`${label}: "name" must be lowercase letters, digits and single hyphens, at most 64 characters`);
+            continue;
+        }
+        if (typeof description !== "string" || description.trim() === "" || description.length > 1024) {
+            report(`${label}: "description" must be a text of at most 1024 characters`);
+            continue;
+        }
+        if (skills.some((skill) => skill.name === name)) {
+            report(`${label}: another skill is named "${name}"`);
+            continue;
+        }
+        skills.push({
+            name,
+            description: description.trim(),
+            filePath,
+            baseDir,
+            disableModelInvocation: fields["disable-model-invocation"] === true,
+        });
+    }
+    return skills;
+}
+/** The agent's prompt templates: `prompts/<name>.md`, a `description` in the frontmatter and the body as the text. */
+function readTemplates(agentDir) {
+    const root = join(agentDir, "prompts");
+    if (!existsSync(root))
+        return [];
+    return readdirSync(root)
+        .sort()
+        .flatMap((entry) => {
+        if (!entry.endsWith(".md"))
+            return [];
+        const label = `prompts/${entry}`;
+        try {
+            const { fields, body } = frontmatter(readFileSync(join(root, entry), "utf8"), label);
+            const description = typeof fields.description === "string" ? fields.description : undefined;
+            return [{ name: entry.slice(0, -3), ...(description === undefined ? {} : { description }), body }];
+        }
+        catch (error) {
+            report(`${label}: ${error instanceof Error ? error.message : String(error)}`);
+            return [];
+        }
+    });
+}
+/** Arguments as a shell splits them: by whitespace, with `"…"` or `'…'` keeping one argument together. */
+export function parseArguments(text) {
+    const args = [];
+    let current = "";
+    let started = false;
+    let quote;
+    for (const char of text) {
+        if (quote !== undefined) {
+            if (char === quote)
+                quote = undefined;
+            else
+                current += char;
+        }
+        else if (char === '"' || char === "'") {
+            quote = char;
+            started = true;
+        }
+        else if (/\s/.test(char)) {
+            if (started)
+                args.push(current);
+            current = "";
+            started = false;
+        }
+        else {
+            current += char;
+            started = true;
+        }
+    }
+    if (started)
+        args.push(current);
+    return args;
+}
+/**
+ * A template's text with its arguments, in pi's format: `$1`… positional, `$@` and `$ARGUMENTS` all of them,
+ * `${N:-default}` a positional one or its default, `${@:N}` and `${@:N:L}` a slice from the Nth.
+ */
+export function expandTemplate(body, args) {
+    const all = args.join(" ");
+    return body.replace(/\$\{(\d+|@|ARGUMENTS):-([^}]*)\}|\$\{@:(\d+)(?::(\d+))?\}|\$(ARGUMENTS|@|\d+)/g, (_match, target, fallback, from, length, simple) => {
+        if (target !== undefined) {
+            const value = target === "@" || target === "ARGUMENTS" ? all : args[Number(target) - 1];
+            return value ? value : (fallback ?? "");
+        }
+        if (from !== undefined) {
+            const start = Math.max(0, Number(from) - 1);
+            return (length === undefined ? args.slice(start) : args.slice(start, start + Number(length))).join(" ");
+        }
+        return simple === "@" || simple === "ARGUMENTS" ? all : (args[Number(simple) - 1] ?? "");
+    });
+}
+/** A skill's instructions as a message carries them when `/skill:<name>` loads it, as pi does. */
+function loadedSkill(skill, args) {
+    const { body } = frontmatter(readFileSync(skill.filePath, "utf8"), skill.filePath);
+    const block = `<skill name="${skill.name}" location="${skill.filePath}">\nReferences are relative to ${skill.baseDir}.\n\n${body.trim()}\n</skill>`;
+    return args.trim() === "" ? block : `${block}\n\n${args.trim()}`;
+}
+/** What a Caller may offer as `/<name>`: the prompt templates, then `skill:<name>` for each skill. */
+export function readCommands(agentDir) {
+    return [
+        ...readTemplates(agentDir).map((template) => ({
+            name: template.name,
+            ...(template.description === undefined ? {} : { description: template.description }),
+            expand: (args) => expandTemplate(template.body, parseArguments(args)),
+        })),
+        ...readSkills(agentDir).map((skill) => ({
+            name: `skill:${skill.name}`,
+            description: skill.description,
+            expand: (args) => loadedSkill(skill, args),
+        })),
+    ];
+}
+const escapeXml = (text) => text
+    .replace(/&/g, "&amp;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;")
+    .replace(/'/g, "&apos;");
+/** The skills the model may choose, as pi lists them: a skill's instructions are loaded only when a task needs them. */
+function skillsPrompt(skills) {
+    const listed = skills.filter((skill) => !skill.disableModelInvocation);
+    if (listed.length === 0)
+        return undefined;
+    return [
+        "The following skills provide specialized instructions for specific tasks.",
+        "Use the read tool to load a skill's file when the task matches its description.",
+        "When a skill file references a relative path, resolve it against the skill directory (parent of SKILL.md / dirname of the path) and use that absolute path in tool commands.",
+        "",
+        "<available_skills>",
+        ...listed.flatMap((skill) => [
+            "  <skill>",
+            `    <name>${escapeXml(skill.name)}</name>`,
+            `    <description>${escapeXml(skill.description)}</description>`,
+            `    <location>${escapeXml(skill.filePath)}</location>`,
+            "  </skill>",
+        ]),
+        "</available_skills>",
+    ].join("\n");
+}
+const fileText = (path) => {
+    if (!existsSync(path))
+        return undefined;
+    const text = readFileSync(path, "utf8").trim();
+    return text === "" ? undefined : text;
+};
+/**
+ * The prompt the definition contributes: `SYSTEM.md` as written, `AGENTS.md` as project context, the skills, where it
+ * works, and, deployed, what of a change it makes to itself lasts. `wake`: the agent has the wake tool.
+ */
+export function definitionSections(agentDir, content, options) {
+    return [
+        section("system", () => fileText(join(agentDir, "SYSTEM.md")), { tag: false }),
+        section("project_context", () => fileText(join(agentDir, "AGENTS.md"))),
+        section("skills", () => skillsPrompt(readSkills(agentDir))),
+        section("content", () => contentSection({ agentDir, content })),
+        section("self_change", () => (isDeployedWorkspace() ? selfChangeSection(options.wake) : undefined)),
+    ];
+}
+/**
+ * What takes effect when, and the agent's own path to a new capability, are the same on every host; how long the
+ * storage lives is the host's answer: AgentCore's managed mount is reset by every deploy, so telling that agent to keep
+ * work "outside the definition" would name a location its next deploy erases. The skill it writes lives in the
+ * definition directory, which the next deployment replaces (or, on AgentCore, erases with everything else), so the
+ * sentence says so, and where a skill that should outlast it has to go.
+ */
+function selfChangeSection(wake) {
+    const deployment = isAgentcoreRuntime()
+        ? "Every deployment of a new version resets this host's storage entirely"
+        : "Each deployment replaces your directory with the author's release";
+    return (`Your directory survives restarts, including uncommitted work; /tmp does not. ${deployment}, so anything that ` +
+        `must outlive a deployment belongs in an external system (a git remote, an issue tracker, a database). ` +
+        `SYSTEM.md, AGENTS.md, skills/ and prompts/ are read for every message; changes to code in src/ (tools, ` +
+        `extensions, channels, schedules) or to configuration (fastagent.config.ts, context.json, package.json) take ` +
+        `effect when the service restarts. A tool you install yourself (apt-get, npm install -g) belongs to this machine ` +
+        `and is gone when its container is replaced. To give yourself a new capability now, write a skill — a SKILL.md in ` +
+        `your definition's skills/ directory, with any script it needs run through bash. It lasts until the next ` +
+        `deployment replaces that directory, so a capability that should outlast it belongs in the author's release: ` +
+        `propose it to them.` +
+        // Named only when it has the tool: naming a tool the model does not have invites calls to it.
+        (wake ? " To schedule your own follow-up work, use the wake tool." : ""));
+}
+/** What a content entry of this kind is, said to the agent: where it is, and whether another instance shares it. */
+function contentKind(c) {
+    if (c.kind !== "github")
+        return "a directory on this machine";
+    if (!c.clone)
+        return `a checkout of github ${c.repo} on this machine`;
+    // Brought up to date in place at each start where git can do so without touching the agent's work; what the agent
+    // changes stays, and reaches anyone else only when pushed. The declared ref is what it follows, not a claim about
+    // where it is: a clone the agent moved elsewhere is left there.
+    const clone = `a shallow clone of github ${c.repo}${c.ref ? ` (declared ${c.ref})` : ""} in your own storage`;
+    return c.readonly
+        ? `${clone}, brought up to date each time you start`
+        : `${clone}: what you change in it stays, and each time you start it is brought up to date where that touches nothing of yours; push to share a change`;
+}
+/**
+ * Where the agent is and what it works on (agent-model.md §4): its own directory is itself, and each content entry is named
+ * with its location, whether it is the agent's to change, and where a change there goes. A result written where it
+ * does not last is how knowledge gets lost, so the agent is told which is which.
+ */
+function contentSection({ agentDir, content }) {
+    const own = `Your working directory, ${agentDir}, is your own directory: it holds your definition, and files you create ` +
+        `land there unless you put them elsewhere.`;
+    if (content.length === 0)
+        return `${own} Nothing else is declared for you: you work only in your own directory.`;
+    const line = (c) => `- ${c.name}: ${c.location} (${contentKind(c)})${c.description !== undefined ? ` ${c.description}` : ""}`;
+    const worksOn = content.filter((c) => !c.readonly);
+    const knows = content.filter((c) => c.readonly);
+    return [
+        own,
+        ...(worksOn.length > 0 ? ["You work on:", ...worksOn.map(line)] : []),
+        ...(knows.length > 0 ? ["You know, and do not write:", ...knows.map(line)] : []),
+        `Run a command in one of these directories with \`cd <its location> && …\`; file tools take the location directly.` +
+            (worksOn.length > 0
+                ? " A result worth keeping belongs in a directory you work on, not in your own directory."
+                : " You write only in your own directory: the directories above are for reading."),
+    ].join("\n");
+}

package/dist/harnesses/pi-durable/wake.d.ts

@@ -0,0 +1,11 @@
+import { type Extension } from "@earendil-works/pi-durable";
+export declare const WAKE_EXTENSION = "fastagent.wake";
+export declare const WAKE_TOOLS: string[];
+/**
+ * `ticking` says whether a clock fires the wake-ups kept in `stateRoot` now; a wake-up nothing would fire is refused.
+ * Without it, one always does: `dev`, `start` and AgentCore serve whatever they open.
+ */
+export declare function wakeExtension(stateRoot: string, options?: {
+    now?: () => Date;
+    ticking?: () => boolean;
+}): Extension;

package/dist/harnesses/pi-durable/wake.js

@@ -0,0 +1,90 @@
+/**
+ * `wake` and `unwake`: the agent schedules itself back into the conversation it is in, one-shot or recurring, kept in
+ * the instance's state (schedule/wakeups.ts), which the scheduler fires. A pair over one store: a definition that
+ * defines either name gets neither.
+ */
+import { Type } from "@earendil-works/pi-ai";
+import { defineExtension, defineTool } from "@earendil-works/pi-durable";
+import { addWakeup, parseDelayMs, removeWakeup } from "../../schedule/wakeups.js";
+import { sessionIdOf } from "./ids.js";
+export const WAKE_EXTENSION = "fastagent.wake";
+export const WAKE_TOOLS = ["wake", "unwake"];
+const said = (text) => ({ output: [{ type: "text", text }] });
+const refused = (text) => ({ output: [{ type: "text", text }], isError: true });
+const NOT_A_SESSION = "wake-ups belong to a session, and this conversation is not one (a subagent's): nothing would wake it.";
+const NO_CLOCK = "nothing fires wake-ups for this agent now: the app that opened it does not serve it, so no clock runs. Do the " +
+    "work now, or say it cannot be scheduled.";
+/**
+ * `ticking` says whether a clock fires the wake-ups kept in `stateRoot` now; a wake-up nothing would fire is refused.
+ * Without it, one always does: `dev`, `start` and AgentCore serve whatever they open.
+ */
+export function wakeExtension(stateRoot, options = {}) {
+    const now = options.now ?? (() => new Date());
+    return defineExtension({
+        name: WAKE_EXTENSION,
+        tools: [
+            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 it sparingly, and `unwake` with the returned " +
+                    "id when the job is done. Exactly one of `in`/`cron`. When the time comes, a new message arrives in this " +
+                    "same conversation with `prompt` as its instruction, tagged with the wake-up's id so you can tell it from a " +
+                    "user's, and you keep the full context of this conversation. Its plain reply is delivered to no one: to " +
+                    "reach a person it must call a delivery tool (a channel's send tool), as a scheduled job does.",
+                parameters: Type.Object({
+                    in: Type.Optional(Type.Union([Type.String(), Type.Number()], {
+                        description: 'one-shot delay: a duration string with a unit ("30m" / "2h" / "1d"), or a number of seconds',
+                    })),
+                    cron: Type.Optional(Type.String({ description: 'recurring: a 5-field cron expression (e.g. "0 9 * * *")' })),
+                    tz: Type.Optional(Type.String({ description: 'IANA timezone for `cron` (default "UTC")' })),
+                    prompt: Type.String({
+                        minLength: 1,
+                        description: "the instruction for the woken message (it arrives in this same conversation)",
+                    }),
+                }),
+                execute: async (args, api, context) => {
+                    if (options.ticking?.() === false)
+                        return refused(NO_CLOCK);
+                    if ((args.in === undefined) === (args.cron === undefined)) {
+                        return refused("pass exactly one of `in` (one-shot) or `cron` (recurring).");
+                    }
+                    const session = await sessionIdOf(api, context);
+                    if (session === undefined)
+                        return refused(NOT_A_SESSION);
+                    const at = now();
+                    if (args.cron !== undefined) {
+                        const added = addWakeup(stateRoot, { session, prompt: args.prompt, cron: args.cron, tz: args.tz }, at);
+                        if (!added.ok)
+                            return refused(added.error);
+                        return said(`OK — recurring wake ${added.id} (cron "${args.cron}"${args.tz ? ` ${args.tz}` : ""}), first at ${added.fireAt}: ${args.prompt}. Use unwake({ id: "${added.id}" }) to stop it.`);
+                    }
+                    const ms = parseDelayMs(args.in);
+                    if (ms === undefined) {
+                        return refused(`couldn't parse "in" (${JSON.stringify(args.in)}): use a unit like "30m" / "2h" / "1d", or a number of seconds (a bare number as text like "120" is rejected).`);
+                    }
+                    const added = addWakeup(stateRoot, { session, prompt: args.prompt, fireAt: new Date(at.getTime() + ms) }, at);
+                    if (!added.ok)
+                        return refused(added.error);
+                    return said(`OK — I'll wake up at ${added.fireAt} (id ${added.id}) to: ${args.prompt}. Use unwake({ id: "${added.id}" }) if it becomes unnecessary.`);
+                },
+            }),
+            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.",
+                parameters: Type.Object({
+                    id: Type.String({ minLength: 1, description: "the wake-up id (returned by `wake`)" }),
+                }),
+                execute: async (args, api, context) => {
+                    const session = await sessionIdOf(api, context);
+                    if (session === undefined)
+                        return refused(NOT_A_SESSION);
+                    return removeWakeup(stateRoot, args.id, session)
+                        ? said(`OK — wake-up ${args.id} cancelled.`)
+                        : refused(`no pending wake-up ${args.id} in this conversation (already fired, or not yours).`);
+                },
+            }),
+        ],
+    });
+}