@fastagent-sh/fastagent 0.24.3 → 0.25.0

package/dist/channels/feishu/context-buffer.d.ts

@@ -1,35 +0,0 @@
-/** Feishu/Lark's half of the shared context buffer (mechanics + consume protocol: ../kit/context-buffer.ts). */
-import { type ContextBuffer } from "../kit/context-buffer.ts";
-import type { NormalizedFeishuMessage } from "./model.ts";
-export interface FeishuBufferedResource {
-    messageId: string;
-    key: string;
-    name?: string;
-}
-export interface FeishuBufferEntry {
-    sender: string;
-    body: string;
-    messageId: string;
-    replyTo?: string;
-    files?: FeishuBufferedResource[];
-    images?: FeishuBufferedResource[];
-}
-/** A background resource carried into a later turn, with attribution for its prompt manifest. */
-export interface FeishuBufferedRef extends FeishuBufferedResource {
-    from: string;
-}
-/** The place a message belongs to: the main chat, or a thread within it. */
-export declare function feishuBufferPlaceKey(conversation: Pick<NormalizedFeishuMessage["conversation"], "chatId" | "threadId">): string;
-/** One-line, bounded background text. */
-export declare function feishuBufferText(text: string): string;
-/** Select the most recent background resources, excluding resources already primary on this turn. */
-export declare function collectFeishuBufferedAttachments(consumed: FeishuBufferEntry[], primary: {
-    files: FeishuBufferedResource[];
-    images: FeishuBufferedResource[];
-}): {
-    files: FeishuBufferedRef[];
-    images: FeishuBufferedRef[];
-    skipped: number;
-};
-export type FeishuContextBuffer = ContextBuffer<FeishuBufferEntry>;
-export declare function createFeishuContextBuffer(path: string, label: string): FeishuContextBuffer;

package/dist/channels/feishu/context-buffer.js

@@ -1,65 +0,0 @@
-/** Feishu/Lark's half of the shared context buffer (mechanics + consume protocol: ../kit/context-buffer.ts). */
-import { capBufferedRefs, BUFFER_LINE_MAX_CHARS, createContextBuffer as createGenericContextBuffer, } from "../kit/context-buffer.js";
-import { truncateCodePointPrefix } from "../kit/text.js";
-function bufferLine(entry) {
-    const meta = [`msg ${entry.messageId}`, entry.replyTo ? `reply to msg ${entry.replyTo}` : undefined]
-        .filter(Boolean)
-        .join(", ");
-    return `${entry.sender} (${meta}): ${entry.body}`;
-}
-/** The place a message belongs to: the main chat, or a thread within it. */
-export function feishuBufferPlaceKey(conversation) {
-    return conversation.threadId ? `${conversation.chatId}:thread:${conversation.threadId}` : conversation.chatId;
-}
-/** One-line, bounded background text. */
-export function feishuBufferText(text) {
-    return truncateCodePointPrefix(text.replace(/\s+/g, " ").trim(), BUFFER_LINE_MAX_CHARS);
-}
-function resourceIdentity(resource) {
-    return `${resource.messageId}\u0000${resource.key}`;
-}
-/** Select the most recent background resources, excluding resources already primary on this turn. */
-export function collectFeishuBufferedAttachments(consumed, primary) {
-    const refs = (pick, primaryRefs) => {
-        const excluded = new Set(primaryRefs.map(resourceIdentity));
-        const seen = new Set();
-        const out = [];
-        for (const entry of consumed) {
-            for (const resource of pick(entry) ?? []) {
-                const identity = resourceIdentity(resource);
-                if (excluded.has(identity) || seen.has(identity))
-                    continue;
-                seen.add(identity);
-                out.push({ ...resource, from: entry.sender });
-            }
-        }
-        return out;
-    };
-    const files = capBufferedRefs(refs((entry) => entry.files, primary.files));
-    const images = capBufferedRefs(refs((entry) => entry.images, primary.images));
-    return { files: files.kept, images: images.kept, skipped: files.skipped + images.skipped };
-}
-function isResource(value) {
-    const resource = value;
-    return (typeof resource?.messageId === "string" &&
-        typeof resource.key === "string" &&
-        (resource.name === undefined || typeof resource.name === "string"));
-}
-function isEntry(value) {
-    const entry = value;
-    const resources = (candidate) => candidate === undefined || (Array.isArray(candidate) && candidate.every(isResource));
-    return (typeof entry?.sender === "string" &&
-        typeof entry.body === "string" &&
-        typeof entry.messageId === "string" &&
-        (entry.replyTo === undefined || typeof entry.replyTo === "string") &&
-        resources(entry.files) &&
-        resources(entry.images));
-}
-export function createFeishuContextBuffer(path, label) {
-    return createGenericContextBuffer({
-        path,
-        label,
-        isEntry,
-        line: bufferLine,
-    });
-}

package/dist/channels/feishu/scaffold/channel.websocket.ts

@@ -1,31 +0,0 @@
-import { feishuWebSocketChannel } from "@fastagent-sh/fastagent/feishu";
-import { defineChannel } from "@fastagent-sh/fastagent";
-
-// Feishu WebSocket long connection: the process connects OUT to the platform, so no public URL,
-// Verification Token, Encrypt Key, or --tunnel is needed. In Events & Callbacks choose long
-// connection, subscribe im.message.receive_v1, then publish the app version. Keep one process
-// running in production: scale-to-zero/App Sleeping would disconnect ingress.
-export default defineChannel({
-  // The env vars this channel needs. fastagent carries them to a deployed box and refuses to serve
-  // while one is unset — a bare process.env read gets neither guarantee.
-  secrets: ["FEISHU_APP_ID", "FEISHU_APP_SECRET"],
-  channel: (secrets) =>
-    feishuWebSocketChannel({
-      appId: secrets.FEISHU_APP_ID,
-      appSecret: secrets.FEISHU_APP_SECRET,
-      // No session modes: a chat is one session and a thread is another, and where the answer goes follows
-      // from that (docs/design/participant-model.md).
-      // Dev/personal bot: surface raw errors to the chat so you (and your AI agent) can act on them. The
-      // chat is customer-facing by default — for a public bot, drop this or return a neutral string;
-      // full details always go to the server log regardless.
-      onError: (failed) => `⚠️ ${failed.details}`,
-      // The channel owns transport + format (markdown card) + attachments (image→vision, file→disk) +
-      // the live streaming preview. `route` (POLICY) is OPTIONAL — omitted, it uses defaultFeishuRoute:
-      // p2p chats always answer; groups answer on @this-bot, plus bare messages in a thread where the
-      // Agent takes part and exactly ONE human does. Other human group/thread discussion buffers until
-      // that place's next answered turn; @other-only messages buffer rather than triggering the Agent.
-      // Override to customise explicit routing, reusing the export:
-      //   route: (e) => defaultFeishuRoute(e, { botOpenId: "ou_xxx" }) && { session: `user:${e.sender?.sender_id?.open_id}` },
-      //   route: (e) => defaultFeishuRoute(e, { botOpenId: "ou_xxx" }) && { text: `${feishuEnvelope(e)}\n[extra]` },
-    }),
-});

package/dist/channels/http.d.ts

@@ -1,23 +0,0 @@
-/**
- * HTTP/SSE channel: fan one invoke stream out to Server-Sent Events. The web stream primitives supply cancellation
- * natively (consumer disconnect → `cancel()` → `iterator.return()` → invoke cancellation, SPEC MUST 3), backpressure,
- * and the body cap.
- */
-import type { Agent } from "../agent.ts";
-/**
- * Request body cap (1 MiB) — shared by every Prompt-bearing wire surface (the control plane's dispatch imports it), so
- * the two caps cannot drift apart.
- */
-export declare const MAX_BODY_BYTES: number;
-/**
- * A valid example request body for the invoke handler — lives HERE, next to the shape check it must satisfy, so the
- * CLI's "try it" hint can't drift from the protocol.
- */
-export declare const INVOKE_EXAMPLE_BODY = "{\"session\":\"dev\",\"text\":\"hello\"}";
-/**
- * Fetch-shaped invoke handler.
- *
- * No CORS here: who may call this from a browser is decided once, before dispatch, in `channels/serve.ts`'s router
- * — which is also the only layer that can answer the `OPTIONS` preflight, since this route registers only `POST`.
- */
-export declare function createInvokeHandler(agent: Agent): (req: Request) => Promise<Response>;

package/dist/channels/http.js

@@ -1,57 +0,0 @@
-import { readBodyCapped, refuseNonJsonBody } from "./body.js";
-import { text } from "./respond.js";
-import { sseResponse } from "./sse.js";
-/**
- * Request body cap (1 MiB) — shared by every Prompt-bearing wire surface (the control plane's dispatch imports it), so
- * the two caps cannot drift apart.
- */
-export const MAX_BODY_BYTES = 1 << 20;
-/**
- * A valid example request body for the invoke handler — lives HERE, next to the shape check it must satisfy, so the
- * CLI's "try it" hint can't drift from the protocol.
- */
-export const INVOKE_EXAMPLE_BODY = '{"session":"dev","text":"hello"}';
-/**
- * Fetch-shaped invoke handler.
- *
- * No CORS here: who may call this from a browser is decided once, before dispatch, in `channels/serve.ts`'s router
- * — which is also the only layer that can answer the `OPTIONS` preflight, since this route registers only `POST`.
- */
-export function createInvokeHandler(agent) {
-    return async (req) => {
-        if (req.method !== "POST")
-            return text("POST only\n", 405);
-        // Also applied by the host router over every unguarded route — kept HERE too because this handler is a
-        // PUBLIC standalone artifact (docs/overview.md mounts it as a Next.js route), and a handler you can mount
-        // anywhere has to be safe anywhere. The router's copy is what stops a route added later from forgetting.
-        const wrongType = refuseNonJsonBody(req);
-        if (wrongType)
-            return wrongType;
-        const body = await readBodyCapped(req, MAX_BODY_BYTES);
-        if ("tooLarge" in body)
-            return text("body too large\n", 413);
-        let payload;
-        try {
-            payload = JSON.parse(body.text);
-        }
-        catch {
-            return text("invalid json\n", 400);
-        }
-        const { session, text: promptText, parentSession, branchHints, } = (payload ?? {});
-        if (typeof session !== "string" || typeof promptText !== "string") {
-            return text('need { "session": string, "text": string }\n', 400);
-        }
-        // INVOKE_EXAMPLE_BODY must keep satisfying this request shape.
-        if (parentSession !== undefined && typeof parentSession !== "string") {
-            return text('"parentSession" must be a string\n', 400);
-        }
-        if (branchHints !== undefined && !(Array.isArray(branchHints) && branchHints.every((h) => typeof h === "string"))) {
-            return text('"branchHints" must be an array of strings\n', 400);
-        }
-        return sseResponse(agent.invoke({
-            session,
-            ...(parentSession !== undefined ? { parentSession } : {}),
-            ...(branchHints !== undefined ? { branchHints } : {}),
-        }, { text: promptText }));
-    };
-}

package/dist/channels/lark/scaffold/channel.websocket.ts

@@ -1,31 +0,0 @@
-import { larkWebSocketChannel } from "@fastagent-sh/fastagent/lark";
-import { defineChannel } from "@fastagent-sh/fastagent";
-
-// Lark WebSocket long connection: the process connects OUT to the platform, so no public URL,
-// Verification Token, Encrypt Key, or --tunnel is needed. In Events & Callbacks choose long
-// connection, subscribe im.message.receive_v1, then publish the app version. Keep one process
-// running in production: scale-to-zero/App Sleeping would disconnect ingress.
-export default defineChannel({
-  // The env vars this channel needs. fastagent carries them to a deployed box and refuses to serve
-  // while one is unset — a bare process.env read gets neither guarantee.
-  secrets: ["LARK_APP_ID", "LARK_APP_SECRET"],
-  channel: (secrets) =>
-    larkWebSocketChannel({
-      appId: secrets.LARK_APP_ID,
-      appSecret: secrets.LARK_APP_SECRET,
-      // No session modes: a chat is one session and a thread is another, and where the answer goes follows
-      // from that (docs/design/participant-model.md).
-      // Dev/personal bot: surface raw errors to the chat so you (and your AI agent) can act on them. The
-      // chat is customer-facing by default — for a public bot, drop this or return a neutral string;
-      // full details always go to the server log regardless.
-      onError: (failed) => `⚠️ ${failed.details}`,
-      // The channel owns transport + format (markdown card) + attachments (image→vision, file→disk) +
-      // the live streaming preview. `route` (POLICY) is OPTIONAL — omitted, it uses defaultLarkRoute:
-      // p2p chats always answer; groups answer on @this-bot, plus bare messages in a thread where the
-      // Agent takes part and exactly ONE human does. Other human group/thread discussion buffers until
-      // that place's next answered turn; @other-only messages buffer rather than triggering the Agent.
-      // Override to customise explicit routing, reusing the export:
-      //   route: (e) => defaultLarkRoute(e, { botOpenId: "ou_xxx" }) && { session: `user:${e.sender?.sender_id?.open_id}` },
-      //   route: (e) => defaultLarkRoute(e, { botOpenId: "ou_xxx" }) && { text: `${larkEnvelope(e)}\n[extra]` },
-    }),
-});

package/dist/channels/slack/context-buffer.d.ts

@@ -1,23 +0,0 @@
-/**
- * Slack's half of the shared context buffer (mechanics + consume protocol: ../kit/context-buffer.ts): the entry shape,
- * its fold-line rendering, and buffered-file selection.
- */
-import { type ContextBuffer } from "../kit/context-buffer.ts";
-export interface SlackBufferEntry {
-    sender: string;
-    body: string;
-    messageId: string;
-    replyTo?: string;
-    fileIds?: string[];
-}
-export interface SlackBufferedFileRef {
-    id: string;
-    from: string;
-    messageId: string;
-}
-export declare function collectSlackBufferedFiles(consumed: SlackBufferEntry[], primaryIds: Set<string>): {
-    files: SlackBufferedFileRef[];
-    skipped: number;
-};
-export type SlackContextBuffer = ContextBuffer<SlackBufferEntry>;
-export declare function createSlackContextBuffer(path: string, label: string): SlackContextBuffer;

package/dist/channels/slack/context-buffer.js

@@ -1,37 +0,0 @@
-/**
- * Slack's half of the shared context buffer (mechanics + consume protocol: ../kit/context-buffer.ts): the entry shape,
- * its fold-line rendering, and buffered-file selection.
- */
-import { capBufferedRefs, createContextBuffer as createGenericContextBuffer, } from "../kit/context-buffer.js";
-function bufferLine(entry) {
-    const meta = [`msg ${entry.messageId}`, entry.replyTo ? `thread root ${entry.replyTo}` : undefined]
-        .filter(Boolean)
-        .join(", ");
-    return `${entry.sender} (${meta}): ${entry.body}`;
-}
-export function collectSlackBufferedFiles(consumed, primaryIds) {
-    const seen = new Set();
-    const files = [];
-    for (const entry of consumed) {
-        for (const id of entry.fileIds ?? []) {
-            if (primaryIds.has(id) || seen.has(id))
-                continue;
-            seen.add(id);
-            files.push({ id, from: entry.sender, messageId: entry.messageId });
-        }
-    }
-    const capped = capBufferedRefs(files);
-    return { files: capped.kept, skipped: capped.skipped };
-}
-function isEntry(value) {
-    const entry = value;
-    return (typeof entry?.sender === "string" &&
-        typeof entry.body === "string" &&
-        typeof entry.messageId === "string" &&
-        (entry.replyTo === undefined || typeof entry.replyTo === "string") &&
-        (entry.fileIds === undefined ||
-            (Array.isArray(entry.fileIds) && entry.fileIds.every((id) => typeof id === "string"))));
-}
-export function createSlackContextBuffer(path, label) {
-    return createGenericContextBuffer({ path, label, isEntry, line: bufferLine });
-}

package/dist/channels/sse.d.ts

@@ -1,4 +0,0 @@
-/** Shared SSE response lifecycle for invoke and session observation. */
-/** The remote client's idle watchdog allows three missed heartbeats. */
-export declare const SSE_HEARTBEAT_MS = 30000;
-export declare function sseResponse<T>(events: AsyncIterable<T>, project?: (event: T) => unknown): Response;

package/dist/channels/sse.js

@@ -1,66 +0,0 @@
-/** Shared SSE response lifecycle for invoke and session observation. */
-/** The remote client's idle watchdog allows three missed heartbeats. */
-export const SSE_HEARTBEAT_MS = 30_000;
-const encoder = new TextEncoder();
-const heartbeat = encoder.encode(": ping\n\n");
-export function sseResponse(events, project = (event) => event) {
-    const iterator = events[Symbol.asyncIterator]();
-    // Subscribe before headers; synchronous startup errors belong to the HTTP error boundary.
-    let pending = Promise.resolve(iterator.next());
-    // pull() surfaces asynchronous failures. Observe rejection even if the caller cancels before that pull.
-    pending.catch(() => { });
-    let closed = false;
-    let timer;
-    const stop = () => {
-        closed = true;
-        clearInterval(timer);
-    };
-    const cancel = async () => {
-        if (closed)
-            return;
-        stop();
-        await iterator.return?.();
-    };
-    const stream = new ReadableStream({
-        start(controller) {
-            timer = setInterval(() => controller.enqueue(heartbeat), SSE_HEARTBEAT_MS);
-        },
-        async pull(controller) {
-            try {
-                const next = await (pending ?? iterator.next());
-                pending = undefined;
-                // Cancellation can settle a pending next(); its value no longer has a reader.
-                if (closed)
-                    return;
-                if (next.done) {
-                    stop();
-                    controller.close();
-                }
-                else {
-                    controller.enqueue(encoder.encode(`data: ${JSON.stringify(project(next.value))}\n\n`));
-                }
-            }
-            catch (error) {
-                if (closed)
-                    return;
-                // Errored streams never call cancel(), so iterator and timer cleanup belongs here too.
-                try {
-                    await cancel();
-                }
-                catch (cleanupError) {
-                    controller.error(new AggregateError([error, cleanupError], "SSE source and cleanup failed", { cause: error }));
-                    return;
-                }
-                controller.error(error);
-            }
-        },
-        cancel,
-    });
-    return new Response(stream, {
-        headers: {
-            "content-type": "text/event-stream",
-            "cache-control": "no-cache",
-            connection: "keep-alive",
-        },
-    });
-}

package/dist/cli/commands/chat.d.ts

@@ -1,3 +0,0 @@
-export declare function runChat(dirArg: string, opts: {
-    model?: string;
-}): Promise<void>;

package/dist/cli/commands/chat.js

@@ -1,14 +0,0 @@
-/** `fastagent chat [dir]`: open the SAME assembled agent in pi's interactive TUI. */
-import { failStartup } from "../fail.js";
-import { enterAgentCommand } from "../shared.js";
-export async function runChat(dirArg, opts) {
-    // Chat authenticates through fastagent's credential store like every other command (the shared session builder
-    // injects it — see engines/pi/session-builder.ts), so the first-run picker and its inline login apply here too.
-    const placement = await enterAgentCommand(dirArg, opts);
-    // Run the chat process AT the workspace: pi resolves a session's cwd as `header.cwd ?? process.cwd()`, so aligning
-    // process.cwd() with the workspace keeps a cwd-less session on it.
-    process.chdir(placement.workspace);
-    // Lazy-import: chat pulls pi's interactive TUI module graph; headless start/dev never need it.
-    const { runPiChat } = await import("../../engines/pi/chat.js");
-    await runPiChat(placement.agentDir, { model: placement.modelSpec }).catch(failStartup);
-}

package/dist/cli/commands/routine-run.d.ts

@@ -1,6 +0,0 @@
-export interface RoutineRunOptions {
-    model?: string;
-    /** false ⇔ `--no-input`. */
-    input?: boolean;
-}
-export declare function runRoutine(name: string, dirArg: string, opts: RoutineRunOptions): Promise<void>;

package/dist/cli/commands/routine-run.js

@@ -1,46 +0,0 @@
-/**
- * `fastagent routine run <name> [dir]`: run ONE routine's turn immediately — the authoring loop for routines (like
- * `invoke` is for a prompt). Cron or not: a routine that declares none has no other local entry.
- */
-import { join } from "node:path";
-import { displayPath } from "../../paths.js";
-import { reportModuleLoadFailures } from "../../loader.js";
-import { createPiAgentFromDir } from "../../engines/pi/open.js";
-import { runInvokeStream } from "../invoke-stream.js";
-import { loadRoutines } from "../../schedule/discover.js";
-import { routineSession } from "../../schedule/routine.js";
-import { failStartup, gateSecretsOrExit } from "../fail.js";
-import { enterAgentDirectory, reportAuth, requireDefaultModel } from "../shared.js";
-export async function runRoutine(name, dirArg, opts) {
-    const placement = await enterAgentDirectory(dirArg, opts);
-    // Routines are agent surface — discovered where dev/start/`routine list` do (the agent dir), so this command
-    // sees the same set the clock serves.
-    const { routines, secrets, failures } = await loadRoutines(placement.agentDir).catch(failStartup);
-    // Reported BEFORE the name is looked up: a routine file that failed to import is missing from
-    // `routines`, so "unknown routine" is the case where the author most needs to hear about it.
-    reportModuleLoadFailures(failures);
-    const routine = routines.find((r) => r.name === name);
-    if (!routine) {
-        // Name the discovery path: a schedule misplaced in the workspace (outside the agent dir) should read as "wrong
-        // place", not "broken file".
-        failStartup(new Error(`unknown routine "${name}" (looked in ${displayPath(process.cwd(), join(placement.agentDir, "routines")) ?? "routines"}). ` +
-            `available: ${routines.map((r) => r.name).join(", ") || "(none)"}`));
-    }
-    // This RUNS the routine, so it takes the serving path's guarantee: a prompt built from an
-    // unset declared value is the degraded turn this feature exists to prevent (`Post the digest to `
-    // — sent and executed), and the loader resolved it into a string before anything could notice.
-    // THIS schedule only (`owner`): running one routine must not fail because a SIBLING ROUTINE needs a
-    // credential this machine has no reason to hold. The agent assembled below is a different question
-    // and gates every mounted tool — a run's turn can call any of them — so this command is not free of a
-    // tool's declaration, only of another routine's. The failures go to the gate too, even though they
-    // were printed above: its guarantee must not depend on this call site remembering (a repeated line
-    // on the refusal path is the cheaper failure).
-    gateSecretsOrExit({ declared: secrets, failures, owner: name });
-    const { modelSpec } = requireDefaultModel(placement);
-    const { agent, models } = await createPiAgentFromDir(placement.agentDir, { model: modelSpec }).catch(failStartup);
-    console.error(`[fastagent] routine run: ${name} (${modelSpec})`);
-    await reportAuth(models, modelSpec);
-    const exitCode = await runInvokeStream(agent.invoke({ session: routineSession(name) }, { text: routine.prompt }), (text) => process.stdout.write(text), (line) => console.error(line));
-    process.stdout.write("\n");
-    process.exit(exitCode);
-}

package/dist/cli/commands/routine.d.ts

@@ -1,25 +0,0 @@
-/**
- * `fastagent routine history <name> [dir]`: print this routine's fired slots — when each fired, how it ended, how
- * long it took.
- *
- * The history IS the claims (`schedule/claims/<name>/`), so it is bounded by construction and carries no turn text:
- * what the run SAID is in its session (`routine:<name>`), stored once, like any other turn's, under the state
- * root's `sessions/` — which is where this command points rather than copying any of it here.
- *
- * This command does NOT try to say which turn belongs to which fire. Nothing links them: a routine's fires share
- * ONE continuing conversation, so the session id is the same for all of them, and the turn-level identifier would
- * have to cross the engine-neutral contract (no `AgentEvent` carries an entry id) or cost the shared conversation.
- * A claim's timestamp against a time-ordered journal is what an operator reads anyway — matching them HERE only
- * moves a human's judgement into a heuristic that cannot be right about a session other writers also append to.
- */
-export declare function runRoutineHistory(name: string, dirArg: string, json: boolean): void;
-/**
- * `fastagent routine list [dir]`: every declared routine, and when (or whether) a clock fires it.
- *
- * IT ALSO READS the agent's pending wake-ups. They are a different owner (the state, not the definition) but the
- * same question when an operator is asking it: "what is going to wake this agent up?". Deleting the command that
- * CANCELLED one was right — `unwake({ id })` covers it, and a serve that can receive the alarm can also be spoken
- * to — but that argument is about WRITING. Without a read, the only way to learn why an agent wakes at 3am is to
- * open `<stateRoot>/schedule/wakeups.json` by hand.
- */
-export declare function runRoutineList(dirArg: string, json: boolean): Promise<void>;

package/dist/cli/commands/routine.js

@@ -1,122 +0,0 @@
-/**
- * `fastagent routine history|list` — the routines this DEFINITION declares.
- *
- * The agent's own pending wake-ups are not here and have no command: they live in the state, not the definition,
- * and `unwake({ id })` is what cancels one (schedule/wakeups.ts says why).
- */
-import { resolve } from "node:path";
-import { enterAgentEnv } from "../../env.js";
-import { resolveSessionsDir, resolveStateRoot } from "../../paths.js";
-import { reportModuleLoadFailures } from "../../loader.js";
-import { nextRun } from "../../schedule/cron.js";
-import { loadRoutines } from "../../schedule/discover.js";
-import { routineSession } from "../../schedule/routine.js";
-import { isSafeScheduleName, readFires } from "../../schedule/state.js";
-import { listWakeups } from "../../schedule/wakeups.js";
-import { failStartup, placementOrExit } from "../fail.js";
-/**
- * `fastagent routine history <name> [dir]`: print this routine's fired slots — when each fired, how it ended, how
- * long it took.
- *
- * The history IS the claims (`schedule/claims/<name>/`), so it is bounded by construction and carries no turn text:
- * what the run SAID is in its session (`routine:<name>`), stored once, like any other turn's, under the state
- * root's `sessions/` — which is where this command points rather than copying any of it here.
- *
- * This command does NOT try to say which turn belongs to which fire. Nothing links them: a routine's fires share
- * ONE continuing conversation, so the session id is the same for all of them, and the turn-level identifier would
- * have to cross the engine-neutral contract (no `AgentEvent` carries an entry id) or cost the shared conversation.
- * A claim's timestamp against a time-ordered journal is what an operator reads anyway — matching them HERE only
- * moves a human's judgement into a heuristic that cannot be right about a session other writers also append to.
- */
-export function runRoutineHistory(name, dirArg, json) {
-    const { agentDir: target } = placementOrExit(resolve(dirArg));
-    enterAgentEnv(target); // FASTAGENT_STATE_DIR may live in .env — read the SAME state root the scheduler wrote
-    const stateRoot = resolveStateRoot(target);
-    // A name that cannot be a routine is a MISTYPED ARGUMENT, and it must not look like an empty history: exit 1 the
-    // way every other user-input refusal does, so `--json` printing nothing is never read as "the command succeeded".
-    if (!isSafeScheduleName(name)) {
-        failStartup(new Error(`"${name}" cannot be a routine name (no path separators, "." or "..")`));
-    }
-    // `readFires` throws a raw fs error on unreadable state, because its other caller is the serving boot, which must
-    // fail rather than arm a schedule it cannot read. This caller is a read-only CLI command: the same fact is an
-    // operator's to fix, so it exits the way every other refusal in this file does instead of printing a Node stack.
-    let fires;
-    try {
-        fires = readFires(stateRoot, name);
-    }
-    catch (e) {
-        failStartup(new Error(`the fired-slot claims for "${name}" are unreadable (state: ${stateRoot}): ${String(e)}`));
-    }
-    if (json) {
-        console.log(JSON.stringify(fires, null, 2));
-        return;
-    }
-    if (fires.length === 0) {
-        // No special case for "wake": it is an ordinary schedule name now (`discover.ts` stopped reserving it).
-        console.error(`no recorded fires for "${name}" (state: ${stateRoot})`);
-        return;
-    }
-    // The question is "did LAST NIGHT's run fail?", so text mode tails the most recent fires; --json above is the
-    // whole retained window.
-    const TAIL = 20;
-    const shown = fires.slice(-TAIL);
-    for (const f of shown) {
-        // An unreported fire has no duration to print, and `0ms` would be a value a fast turn really produces — the
-        // column stays empty rather than claiming the turn took no time.
-        const took = f.ms === undefined ? "" : `${f.ms}ms`;
-        console.log(`${f.firedAt}  ${(f.outcome ?? "unreported").padEnd(11)} ${took.padStart(8)}`);
-    }
-    if (fires.length > shown.length) {
-        console.error(`(the last ${shown.length} of ${fires.length} fires — --json for all)`);
-    }
-    // The other half of the answer, and where it lives: these rows say a fire happened, not what it produced. The
-    // session id comes from the ONE place that spells it and the directory from the ONE place that resolves it. The
-    // record is one level further down and under a name pi accepts (`piSessionId` escapes the `:`), so the pointer
-    // says how to recognise the file rather than claiming a path the reader can paste.
-    console.error(`(what these runs said: session ${routineSession(name)} — a JSON-lines journal under ${resolveSessionsDir(target)}, ` +
-        `in the file whose name carries "${name}")`);
-}
-/**
- * `fastagent routine list [dir]`: every declared routine, and when (or whether) a clock fires it.
- *
- * IT ALSO READS the agent's pending wake-ups. They are a different owner (the state, not the definition) but the
- * same question when an operator is asking it: "what is going to wake this agent up?". Deleting the command that
- * CANCELLED one was right — `unwake({ id })` covers it, and a serve that can receive the alarm can also be spoken
- * to — but that argument is about WRITING. Without a read, the only way to learn why an agent wakes at 3am is to
- * open `<stateRoot>/schedule/wakeups.json` by hand.
- */
-export async function runRoutineList(dirArg, json) {
-    const { agentDir: target } = placementOrExit(resolve(dirArg));
-    enterAgentEnv(target);
-    const { routines, failures } = await loadRoutines(target).catch(failStartup);
-    reportModuleLoadFailures(failures);
-    const wakeups = listWakeups(resolveStateRoot(target));
-    if (json) {
-        console.log(JSON.stringify({
-            routines: routines.map((r) => ({
-                ...r,
-                next: r.cron === undefined ? null : (nextRun(r.cron, r.tz, new Date())?.toISOString() ?? null),
-            })),
-            wakeups,
-        }, null, 2));
-        return;
-    }
-    if (routines.length === 0 && wakeups.length === 0) {
-        console.error(`nothing declared or pending — no routines/ files, no wake-ups (agent: ${target})`);
-        return;
-    }
-    for (const r of routines) {
-        // A routine with no cron is not broken and not idle: it is reached by NAME (`routine run`, `POST /run`), and
-        // saying "on demand" is the difference between that and a cron that will never fire again.
-        const when = r.cron === undefined
-            ? "on demand".padEnd(26)
-            : `${(nextRun(r.cron, r.tz, new Date())?.toISOString() ?? "(never)").padEnd(26)}cron ${r.cron}${r.tz ? ` ${r.tz}` : ""}`;
-        console.log(`${r.name.padEnd(20)} ${when}`);
-    }
-    // Labelled, because these two are NOT the same kind of thing: a routine is the author's, a wake-up is the
-    // agent's own and is cancelled with `unwake` rather than a command here.
-    for (const w of wakeups) {
-        const kind = w.cron ? `cron ${w.cron}${w.tz ? ` ${w.tz}` : ""}` : "one-shot";
-        console.log(`wake ${w.id}  ${w.fireAt}  ${kind}  session=${w.session}  ${w.prompt.slice(0, 60)}`);
-    }
-}

package/dist/cli/commands/tool.d.ts

@@ -1 +0,0 @@
-export declare function runTool(name: string, argsJson: string, dirArg: string): Promise<void>;