@fastagent-sh/fastagent 0.24.4 → 0.25.0

package/dist/loader.js

@@ -1,116 +0,0 @@
-var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
-    if (typeof path === "string" && /^\.\.?\//.test(path)) {
-        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
-            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
-        });
-    }
-    return path;
-};
-import { readdir } from "node:fs/promises";
-import { basename, extname, join } from "node:path";
-import { pathToFileURL } from "node:url";
-import { log } from "./log.js";
-const MODULE_EXTS = new Set([".ts", ".js", ".mjs"]);
-/** Whether `name` is an importable agent module (a discovery candidate, not a type declaration). */
-function isModuleFile(name) {
-    return MODULE_EXTS.has(extname(name)) && !name.endsWith(".d.ts");
-}
-/** The name a module is known by: its basename without the extension. */
-function moduleName(fileName) {
-    return basename(fileName, extname(fileName));
-}
-/**
- * WHAT A CODE-INPUT DIRECTORY DECLARES — the single answer to "which files here are modules", without importing any of
- * them. Internal: the loading functions below are its only consumers.
- */
-async function moduleInventory(subDir) {
-    let dirents;
-    try {
-        dirents = await readdir(subDir, { withFileTypes: true });
-    }
-    catch (error) {
-        const code = error.code;
-        if (code === "ENOENT" || code === "not_found")
-            return [];
-        throw new Error(`cannot read ${subDir}: ${error.message}`);
-    }
-    const sub = basename(subDir);
-    const entries = [];
-    // Sorted by the NAME a consumer sees, so none of them re-sorts and none can disagree about order.
-    const byName = (a, b) => moduleName(a.name).localeCompare(moduleName(b.name)) || a.name.localeCompare(b.name);
-    for (const dirent of dirents.sort(byName)) {
-        if (!isModuleFile(dirent.name))
-            continue;
-        const label = `${sub}/${dirent.name}`;
-        if (dirent.isFile()) {
-            entries.push({ name: moduleName(dirent.name), label, file: join(subDir, dirent.name) });
-        }
-        else if (dirent.isSymbolicLink()) {
-            log.warn(`[fastagent] ${label} is a symlink — code inputs must be real files inside the agent dir — not loaded`);
-        }
-        else if (dirent.isDirectory()) {
-            log.warn(`[fastagent] ${label} is a directory, not a file — not loaded`);
-        }
-        else {
-            log.warn(`[fastagent] ${label} is not a regular file — not loaded`);
-        }
-    }
-    return entries;
-}
-/** A module the loader skipped, said once, the same way for tools, channels and routines. */
-export function reportModuleLoadFailures(failures) {
-    for (const f of failures)
-        log.warn(`[fastagent] ${f.label} failed to load, skipping it — ${f.message}`);
-}
-/**
- * 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 function refuseBrokenDeclarations(failures) {
-    if (failures.length === 0)
-        return;
-    reportModuleLoadFailures(failures);
-    // The reasons are repeated from the warnings above because this message is all an embedder catching the rejection
-    // has, and all a deployment running at FASTAGENT_LOG_LEVEL=error sees.
-    throw new Error(`failed to load: ${failures.map((f) => `${f.label} (${f.message})`).join("; ")} — fix it, or rename an ` +
-        `intentionally disabled file to *.disabled`);
-}
-/** Import every module the directory declares ({@link moduleInventory}). */
-export async function loadModuleDir(subDir) {
-    const entries = await moduleInventory(subDir);
-    const modules = [];
-    const failures = [];
-    for (const { name, label, file } of entries) {
-        try {
-            const mod = (await import(__rewriteRelativeImportExtension(pathToFileURL(file).href)));
-            modules.push({ name, label, file, mod });
-        }
-        catch (error) {
-            failures.push({
-                label,
-                file,
-                message: `${error.message}${moduleLoadHint(error)}`,
-            });
-        }
-    }
-    return { modules, failures };
-}
-/**
- * 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 function moduleLoadHint(error) {
-    if (error.code === "ERR_MODULE_NOT_FOUND" || /Cannot find (package|module)/.test(error.message)) {
-        return "\n  (a dependency is not installed — run `npm install` in the agent dir)";
-    }
-    if (/import statement outside a module|Unexpected token 'export'|ERR_REQUIRE_ESM/.test(error.message)) {
-        return '\n  (the agent dir must be ESM — set "type": "module" in package.json)';
-    }
-    return "";
-}

package/dist/node.d.ts

@@ -1,3 +0,0 @@
-/** Binding a Fetch handler to a Node HTTP server. */
-export { nodeListener, serveNode } from "./channels/serve.ts";
-export { mountAgentService, type AgentService, type HttpSurface, type MountableAgent, type MountAgentServiceOptions, } from "./service.ts";

package/dist/node.js

@@ -1,4 +0,0 @@
-/** Binding a Fetch handler to a Node HTTP server. */
-export { nodeListener, serveNode } from "./channels/serve.js";
-// The assembly: a MountableAgent becomes a mounted service.
-export { mountAgentService, } from "./service.js";

package/dist/observe.d.ts

@@ -1,6 +0,0 @@
-/**
- * The turn trace: wrap an Agent to tee each turn's loop — prompt, reasoning, tool calls (name + args) with results,
- * reply, terminal — to the log at DEBUG level.
- */
-import type { Agent } from "./agent.ts";
-export declare function logAgentLoop(agent: Agent, sink?: (line: string) => void): Agent;

package/dist/observe.js

@@ -1,47 +0,0 @@
-import { log } from "./log.js";
-const PREVIEW = 200;
-/** One line, whitespace-collapsed, truncated — a log stays scannable. */
-function oneLine(s) {
-    const t = s.replace(/\s+/g, " ").trim();
-    return t.length > PREVIEW ? `${t.slice(0, PREVIEW - 1)}…` : t;
-}
-const preview = (v) => oneLine(typeof v === "string" ? v : JSON.stringify(v));
-export function logAgentLoop(agent, sink = (line) => log.debug(line)) {
-    return {
-        async *invoke(scope, prompt) {
-            const s = scope.session;
-            sink(`[agent] ▶ turn session=${s} ← ${oneLine(prompt.text)}`);
-            const toolName = new Map(); // tool_ended carries no name — remember it from tool_started
-            let thinking = "";
-            let reply = "";
-            for await (const e of agent.invoke(scope, prompt)) {
-                if (e.type === "text") {
-                    reply += e.delta;
-                }
-                else if (e.type === "thinking") {
-                    thinking += e.delta;
-                }
-                else if (e.type === "tool_started") {
-                    toolName.set(e.id, e.name);
-                    sink(`[agent]   tool → ${e.name}(${preview(e.args)})`);
-                }
-                else if (e.type === "tool_ended") {
-                    sink(`[agent]   tool ${e.isError ? "✗" : "✓"} ${toolName.get(e.id) ?? e.id} → ${preview(e.content)}`);
-                }
-                else if (e.type === "retrying") {
-                    sink(`[agent]   retrying (${e.attempt}/${e.maxAttempts} in ${e.delayMs}ms): ${oneLine(e.reason)}`);
-                }
-                else if (e.type === "completed") {
-                    if (thinking.trim() !== "")
-                        sink(`[agent]   thinking: ${oneLine(thinking)}`);
-                    sink(`[agent]   reply: ${oneLine(reply) || "(empty)"}`);
-                    sink(`[agent] ■ completed session=${s}`);
-                }
-                else if (e.type === "failed") {
-                    sink(`[agent] ■ failed session=${s}: ${e.details} (retryable=${e.retryable})`);
-                }
-                yield e;
-            }
-        },
-    };
-}

package/dist/pi.d.ts

@@ -1,25 +0,0 @@
-export { createPiAgent, createPiAgentFromDefinition, type CreatePiAgentFromDefinitionOptions, type CreatePiAgentOptions, } from "./engines/pi/create.ts";
-export { defineTool, type DefineToolOptions, type FastagentTool, type MountedTool, type ToolCollision, type ToolContext, } from "./engines/pi/tool.ts";
-export type { ReadonlySessionManager, ToolActivation } from "./engines/pi/tool-context.ts";
-export { z } from "zod";
-export type { AgentTool, ExecutionEnv, Skill, SkillDiagnostic } from "@earendil-works/pi-agent-core";
-/** A conversation record, as the tool runtime and the control plane hold it. */
-export type { SessionManager, SessionEntry as PiSessionEntry } from "@earendil-works/pi-coding-agent";
-export { availableModelsFromDir, createPiAgentFromDir, type CreatePiAgentFromDirOptions, refreshMachineModelCatalog, refreshModelCatalog, } from "./engines/pi/open.ts";
-export type { DefinitionDiagnostic, DefinitionFile, DefinitionPrompt, DefinitionShadow, LoadedDefinition, SkillCollision, } from "./engines/pi/definition.ts";
-export { defineConfig, listModels, resolveModel, type FastagentConfig, } from "./engines/pi/config.ts";
-export type { SessionObserver } from "./engines/pi/turn-kit.ts";
-export { inProcessLease, type Lease, type Release } from "./engines/pi/turn-kit.ts";
-export { createPiSessionControl, type CreatePiSessionControlOptions, } from "./engines/pi/session-control.ts";
-export { piInMemorySessionRecordStore, piSessionRecordStore, type PiSessionRecordStore, } from "./engines/pi/session-store.ts";
-export type { SessionInheritance } from "./engines/pi/session-inheritance.ts";
-export { GLOBAL_AUTH_PATH, fastagentCredentialStore, type FastagentAuthOptions } from "./engines/pi/auth.ts";
-export { createPiModels, type CreatePiModelsOptions } from "./engines/pi/agent-models.ts";
-export { probeAuthSource } from "./engines/pi/models.ts";
-export { login, loginOptions, LoginCancelled, type LoginMethod, type LoginOption, type LoginRequest, type LoginResult, } from "./engines/pi/login.ts";
-/** pi-ai's sign-in types, and the `CredentialStore` a caller supplies as `credentialStore` (with what it holds). */
-export type { AuthEvent, AuthInteraction, AuthPrompt, Credential, CredentialStore } from "@earendil-works/pi-ai";
-export type { Models } from "@earendil-works/pi-ai";
-export type { Provider, ProviderAuth } from "@earendil-works/pi-ai";
-export type { Model } from "@earendil-works/pi-ai";
-export { createAgentService, type CreateAgentServiceOptions } from "./engines/pi/service.ts";

package/dist/pi.js

@@ -1,15 +0,0 @@
-// The pi reference implementation: assembly, agent discovery, tools, config, models, auth, and state ports.
-export { createPiAgent, createPiAgentFromDefinition, } from "./engines/pi/create.js";
-export { defineTool, } from "./engines/pi/tool.js";
-export { z } from "zod";
-export { availableModelsFromDir, createPiAgentFromDir, refreshMachineModelCatalog, refreshModelCatalog, } from "./engines/pi/open.js";
-export { defineConfig, listModels, resolveModel, } from "./engines/pi/config.js";
-export { inProcessLease } from "./engines/pi/turn-kit.js";
-export { createPiSessionControl, } from "./engines/pi/session-control.js";
-export { piInMemorySessionRecordStore, piSessionRecordStore, } from "./engines/pi/session-store.js";
-export { GLOBAL_AUTH_PATH, fastagentCredentialStore } from "./engines/pi/auth.js";
-export { createPiModels } from "./engines/pi/agent-models.js";
-export { probeAuthSource } from "./engines/pi/models.js";
-export { login, loginOptions, LoginCancelled, } from "./engines/pi/login.js";
-// The product's one-call assembly: a directory becomes a live service.
-export { createAgentService } from "./engines/pi/service.js";

package/dist/scaffold/templates/APPEND_SYSTEM.md

@@ -1,12 +0,0 @@
-# Standing instructions
-
-These instructions are added to your system prompt on every turn. This file, `APPEND_SYSTEM.md`, is re-read every turn along with the rest of your definition (`skills/` — capabilities you load when a task calls for them; `prompts/` — prompt templates; `tools/` — code tools your author added, in the same directory as this file). An edit to any of them takes effect on your next message, no restart.
-
-Your definition is this directory: `APPEND_SYSTEM.md`, `skills/`, `tools/`, and the config beside them. Your WORKSPACE is the directory you were started in — the project you work on. It may be this same directory, or the one containing it; `fastagent info` prints both. Use only the tools actually listed in your system prompt. If the workspace has an `AGENTS.md`, it is project context — follow it without assuming a file tool is available.
-
-When your mounted tools allow it, you can improve yourself. When a task reveals something durable — a repeatable process, a standing preference, a hard-won fact — write it into your definition instead of losing it:
-
-- A repeatable process or capability → a new skill beside this file: `skills/<name>/SKILL.md`. Read `skills/writing-great-skills/SKILL.md` first; it is the guide to authoring skills well.
-- A standing instruction or fact → edit this file.
-
-Keep both lean: include only what changes your behavior, and delete what no longer earns its place.

package/dist/scaffold/templates/tools/fetch-url.ts

@@ -1,25 +0,0 @@
-import { defineTool, z } from "@fastagent-sh/fastagent";
-
-// A code tool: filename (fetch-url.ts) is the tool name. tools/ is auto-discovered,
-// so it needs no registration in fastagent.config. Test it without a model:
-//   fastagent tool fetch-url '{"url":"https://example.com"}'
-const MAX_TEXT = 20_000; // keep a huge page from flooding the model's context
-
-export default defineTool({
-  description: "Fetch a web page and return its readable text (HTML stripped, truncated).",
-  input: z.object({ url: z.url({ protocol: /^https?$/ }).describe("The http(s) URL to fetch") }),
-  async execute({ url }) {
-    const res = await fetch(url, { redirect: "follow", signal: AbortSignal.timeout(15_000) });
-    if (!res.ok) throw new Error(`GET ${url} failed: ${res.status} ${res.statusText}`);
-    const html = await res.text();
-    // ponytail: naive tag strip — fine for articles and docs; swap in a readability library if it falls short.
-    const entities: Record<string, string> = { amp: "&", lt: "<", gt: ">", quot: '"', "#39": "'", nbsp: " " };
-    const text = html
-      .replace(/<(script|style)\b[\s\S]*?<\/\1>/gi, " ")
-      .replace(/<[^>]+>/g, " ")
-      .replace(/&(amp|lt|gt|quot|#39|nbsp);/g, (_, e) => entities[e] ?? " ")
-      .replace(/\s+/g, " ")
-      .trim();
-    return { url: res.url, text: text.slice(0, MAX_TEXT), truncated: text.length > MAX_TEXT };
-  },
-});

package/dist/schedule/discover.d.ts

@@ -1,17 +0,0 @@
-import { type ModuleLoadFailure } from "../loader.ts";
-import { type DeclaredSecret } from "../declared-secrets.ts";
-import type { LoadedRoutine } from "./routine.ts";
-/**
- * Discover routines in `<dir>/routines/`: each file default-exports a `defineRoutine({...})`, named from its
- * filename.
- */
-export declare function loadRoutines(dir: string): Promise<{
-    routines: LoadedRoutine[];
-    /** What each loaded routine declared it needs, BY ROUTINE NAME and attributed to its file. Per
-     *  routine because a caller that runs exactly ONE of them (`fastagent routine run`) must not be stopped
-     *  by a sibling's credential, and because two routines declaring the same variable would
-     *  otherwise blame whichever file was read first. The clock flattens it (it runs all of them).
-     *  Data, not a check — only a serving path asserts it (src/declared-secrets.ts). */
-    secrets: Map<string, DeclaredSecret[]>;
-    failures: ModuleLoadFailure[];
-}>;

package/dist/schedule/discover.js

@@ -1,61 +0,0 @@
-/**
- * Routine discovery: an agent declares its named units of work by dropping files in `routines/`, mirroring
- * `tools/` and `channels/`.
- */
-import { join } from "node:path";
-import { loadModuleDir } from "../loader.js";
-import { readSecretDeclaration } from "../declared-secrets.js";
-import { assertInsideAgentDir } from "../paths.js";
-import { cronError } from "./cron.js";
-import { isSafeScheduleName } from "./state.js";
-/**
- * Discover routines in `<dir>/routines/`: each file default-exports a `defineRoutine({...})`, named from its
- * filename.
- */
-export async function loadRoutines(dir) {
-    await assertInsideAgentDir(dir, "routines");
-    const { modules, failures } = await loadModuleDir(join(dir, "routines"));
-    const byName = new Map();
-    const secrets = new Map();
-    for (const { name, label, file, mod } of modules) {
-        try {
-            const r = mod.default;
-            if (!r || typeof r.prompt !== "string") {
-                throw new Error(`${label} must default-export defineRoutine({ prompt, cron? })`);
-            }
-            const declaration = readSecretDeclaration(r, label);
-            if (declaration.error !== undefined)
-                throw new Error(declaration.error);
-            // NO CRON IS NOT AN ERROR: the routine is then reachable by name only (`POST /run`, the CLI, a scheduler
-            // that calls the route). A `tz` without one is, though — it would read as a time this routine does not have.
-            if (r.cron !== undefined && typeof r.cron !== "string")
-                throw new Error(`${label}: "cron" must be a string`);
-            if (r.cron === undefined && r.tz !== undefined) {
-                throw new Error(`${label}: "tz" means nothing without "cron" — remove it, or give this routine a cron`);
-            }
-            if (r.cron !== undefined) {
-                const err = cronError(r.cron, r.tz);
-                if (err)
-                    throw new Error(`${label}: invalid cron/tz — ${err}`);
-            }
-            // The name becomes a path segment (the fired-slot claims live under `claims/<name>/`), so anything that could
-            // leave that directory is refused here — where the author sees which file is wrong — rather than deeper.
-            if (!isSafeScheduleName(name)) {
-                throw new Error(`${label}: a routine name cannot be ".", ".." or contain a path separator`);
-            }
-            if (byName.has(name))
-                throw new Error(`${label}: duplicate routine name "${name}" — kept the first`);
-            byName.set(name, {
-                name,
-                prompt: r.prompt,
-                ...(r.cron !== undefined ? { cron: r.cron } : {}),
-                ...(r.tz !== undefined ? { tz: r.tz } : {}),
-            });
-            secrets.set(name, declaration.secrets);
-        }
-        catch (error) {
-            failures.push({ label, file, message: error.message });
-        }
-    }
-    return { routines: [...byName.values()], secrets, failures };
-}

package/dist/schedule/routine.d.ts

@@ -1,43 +0,0 @@
-/**
- * WHICH conversation a routine's turns belong to: all of them, so a routine shares one continuing conversation —
- * and without depending on engine session storage. The ONE spelling of it: the clock invokes through it,
- * `fastagent routine run` reproduces a run with it, `POST /run` reports it as where to look, and
- * `routine history` prints the command that opens it.
- */
-export declare function routineSession(name: string): string;
-/** A named unit of work the definition owns. With a `cron`, a clock fires it; without one, only its name reaches it. */
-export interface Routine {
-    /**
-     * 5-field cron expression (`minute hour day-of-month month day-of-week`), or absent.
-     *
-     * ABSENT IS A REAL CHOICE, not an omission: the routine is then reachable only by name — `POST /run`, the CLI, a
-     * platform scheduler that calls the route. A time is one way to ask for work, not what the work is.
-     */
-    cron?: string;
-    /** IANA timezone for the cron (default "UTC"). Meaningless without `cron`. */
-    tz?: string;
-    /** The turn's text = the routine's instruction. */
-    prompt: string;
-    /** Env vars this routine declared — carried by `deploy`, asserted before the clock starts. */
-    secrets?: readonly string[];
-}
-/** What an author writes. `prompt` may be built FROM the declared secrets, which is the only reason a
- *  routine file ever read the environment (a channel id, a target inbox). */
-export interface DefineRoutineOptions<S extends readonly string[]> {
-    cron?: string;
-    tz?: string;
-    prompt: string | ((secrets: Record<S[number], string>) => string);
-    /**
-     * Env vars this routine needs (`["SLACK_DIGEST_CHANNEL"]`), typed into the `prompt` builder.
-     * `deploy` carries them and the clock refuses to start while one is unset, naming this file
-     * (see src/declared-secrets.ts) — the guarantees a bare `process.env` read cannot have.
-     */
-    secrets?: S;
-}
-/** Type + completion for a routine file, and the ONE place a prompt builder is resolved (at load:
- *  what the loader stores is always a string, so every consumer sees one shape). */
-export declare function defineRoutine<const S extends readonly string[] = readonly []>(routine: DefineRoutineOptions<S>): Routine;
-/** A loaded routine: its authored fields plus the name derived from its filename (authoritative). */
-export interface LoadedRoutine extends Routine {
-    name: string;
-}

package/dist/schedule/routine.js

@@ -1,32 +0,0 @@
-/**
- * Routine authoring: `defineRoutine`.
- *
- * A ROUTINE IS THE UNIT OF WORK, and the only named one in the system: a prompt the definition owns, addressed by
- * name. `cron` is a FIELD of it, not a second concept — with one, a clock fires it; without one, it is reached by
- * name alone (`POST /run`).
- *
- * WHAT IT IS NOT: a wake-up. The agent can schedule work for itself too (the `wake` tool, schedule/wakeups.ts), and
- * conceptually that is the same idea — work to be done later. Every operational difference between them follows
- * from ONE root: a routine is written in the DEFINITION (versioned, reviewed, shipped with the image, addressable
- * by name) and a wake-up is written into the STATE by a running agent (minted id, cancellable, aimed back at the
- * conversation it came from, erased by the next release if it were a definition file). Code and data.
- *
- * A `prompt` may be a function of the file's declared `secrets` — the only reason such a file ever read the
- * environment (src/declared-secrets.ts).
- */
-import { secretValues } from "../declared-secrets.js";
-/**
- * WHICH conversation a routine's turns belong to: all of them, so a routine shares one continuing conversation —
- * and without depending on engine session storage. The ONE spelling of it: the clock invokes through it,
- * `fastagent routine run` reproduces a run with it, `POST /run` reports it as where to look, and
- * `routine history` prints the command that opens it.
- */
-export function routineSession(name) {
-    return `routine:${name}`;
-}
-/** Type + completion for a routine file, and the ONE place a prompt builder is resolved (at load:
- *  what the loader stores is always a string, so every consumer sees one shape). */
-export function defineRoutine(routine) {
-    const { prompt, ...rest } = routine;
-    return { ...rest, prompt: typeof prompt === "function" ? prompt(secretValues(routine.secrets)) : prompt };
-}

package/dist/schedule/run.d.ts

@@ -1,55 +0,0 @@
-import type { Agent } from "../agent.ts";
-import { type LoadedRoutine } from "./routine.ts";
-/**
- * The 404 for a name this deployment does not declare — drift: a caller outliving the thing it calls. The names are
- * listed so an operator can see whether it is a typo or a stale job without shelling in. The caller's name is CLIPPED
- * before it goes back out: listing this deployment's own names is deliberate, quoting an unauthenticated caller's
- * 4 KiB of body is not (`refuseNonJsonBody` states the same rule for the same table).
- */
-export declare function unknownRoutine(name: string, routines: readonly LoadedRoutine[]): Response;
-/** The reply shape both doors answer with — one for the route, one for a host that has no route (AgentCore). */
-export interface RoutineRunReply {
-    name: string;
-    /** WHERE TO LOOK: the turn's output lives in this session's journal (`fastagent routine history`, `/control/*`). */
-    session: string;
-    ran: boolean;
-    /** Present when `ran: false` — today, the previous turn still holding this routine's one session. */
-    reason?: string;
-    /** Present when the turn RAN and did not finish. */
-    failed?: string;
-    ms: number;
-}
-/**
- * Run one routine and say what happened. THE one implementation, because there are two doors and only one
- * contract: `POST /run` on any host that publishes routes, and AgentCore's IAM-gated `routine-run` envelope on the
- * host that publishes none. A second copy is how the two would come to answer differently.
- */
-export declare function runRoutineByName(agent: Agent, routine: LoadedRoutine): Promise<RoutineRunReply>;
-/**
- * Build the handler for `GET /routines` — what a caller may ask for by name.
- *
- * DISCOVERY, because the alternative was a 404. The names were already public: `POST /run` lists them when a caller
- * gets one wrong, which is deliberate (an operator has to tell a typo from a stale caller) — so the only thing this
- * adds is not having to guess wrong first. "Expose a declared prompt as an API" is half a sentence without it.
- *
- * NAMES AND SCHEDULES, NEVER PROMPTS. What a routine SAYS is the definition's content; handing it to an
- * unauthenticated caller would publish the agent's behaviour, which is the one thing keeping the prompt out of the
- * request body was for. `cron` is here because it answers "will this run on its own, or is my clock the only one?",
- * which is a caller's question, not the definition's secret.
- *
- * Mounted exactly where `POST /run` is: it describes that route, so listing names a caller cannot use would be a
- * catalogue of nothing.
- */
-export declare function createRoutineListHandler(options: {
-    routines: readonly LoadedRoutine[];
-}): ((req: Request) => Promise<Response>) | undefined;
-/**
- * Build the handler for `POST /run`, bound to what this serve loaded.
- *
- * `undefined` when the definition declares nothing runnable: a route that can only ever answer 404 is not a route,
- * and the startup report names what is actually mounted.
- */
-export declare function createRunHandler(options: {
-    agent: Agent;
-    routines: readonly LoadedRoutine[];
-}): ((req: Request) => Promise<Response>) | undefined;

package/dist/schedule/run.js

@@ -1,146 +0,0 @@
-/**
- * `POST /run` — **an API**: run a unit of work this definition declares, by name.
- *
- * NOT A TIME TRIGGER, and the difference is the whole design. Occurrence semantics — a slot, a claim, a fire
- * history, an overlap policy — exist exactly where fastagent OWNS the clock: the resident loop in `dev`/`start`,
- * and AgentCore, where `deploy` writes the EventBridge rule, injects the instant and relays it through an ingress
- * secret (channels/agentcore.ts). Both of those know which occurrence a run is for because they produced it.
- *
- * This route is the other case: somebody else's clock, CI job, button or script. It cannot be told which occurrence
- * it means, and pretending otherwise was measurably worse than admitting it. The attempt cost four rounds — an
- * instant dated ahead poisoned the claim gate permanently, one off the grid minted a claim no occurrence would ever
- * match, an old one replayed history a turn at a time, and the grid arithmetic all three needed was ~6ms of
- * synchronous CPU per request on an anonymous route. A platform cron drifting a few minutes then lost an occurrence
- * outright (Railway documents "a few minutes" of variance; measured: 3 fires, 2 turns).
- *
- * So the contract is the one an API has:
- *
- *   - the body names WHAT to run and nothing else — the prompt stays in the definition, which is the whole reason
- *     this exists beside `POST /invoke`, whose caller brings its own text and therefore its own behaviour
- *   - the reply says what happened and WHERE TO LOOK (the session the turn ran in). Retry policy is the caller's,
- *     because only the caller knows whether its work tolerates running twice
- *   - it is exactly as exposed as `POST /invoke`: unauthenticated, full tool authority, `http.invoke: false` and a
- *     gateway in front are the answers. The framework authenticates nothing (docs/design/session-control.md §14)
- *
- * AND NO IDEMPOTENCY KEY. A key would deduplicate the CALL, not the WORK: a turn that sent one message and then died
- * would answer a keyed retry with "already ran" — safety exactly where it is absent, which is the same reason a failed
- * fire is not retried (schedule/scheduler.ts). What makes a retry safe is idempotent WORK, which only the author can
- * arrange.
- *
- * NAME IN THE BODY, not the path. A declared name is a filename (`每日简报`, `my schedule` are both legal), and a
- * path segment would mean percent-encoding it — the cost the control plane pays for session ids and this route has
- * no reason to. It also keeps the shape of `POST /invoke`, whose scope rides in the body for the same reason.
- */
-import * as Effect from "effect/Effect";
-import { readBodyCapped, refuseNonJsonBody } from "../channels/body.js";
-import { text } from "../channels/respond.js";
-import { routineSession } from "./routine.js";
-import { runTurn } from "./scheduler.js";
-/** A trigger body is a name; the cap only has to admit that. */
-const MAX_RUN_BODY_BYTES = 4 * 1024;
-/**
- * How much of a caller's `name` a 404 will quote back — the ONE thing this route echoes, because telling a typo
- * from a stale caller needs the name and nothing else does. Long enough to recognise one, short enough not to be a
- * page.
- */
-const MAX_ECHOED_NAME = 64;
-/**
- * The 404 for a name this deployment does not declare — drift: a caller outliving the thing it calls. The names are
- * listed so an operator can see whether it is a typo or a stale job without shelling in. The caller's name is CLIPPED
- * before it goes back out: listing this deployment's own names is deliberate, quoting an unauthenticated caller's
- * 4 KiB of body is not (`refuseNonJsonBody` states the same rule for the same table).
- */
-export function unknownRoutine(name, routines) {
-    return text(`no declared work named "${name.slice(0, MAX_ECHOED_NAME)}" (this deployment has: ${routines
-        .map((r) => r.name)
-        .join(", ")})\n`, 404);
-}
-/** The Effect boundary, in one place: the turn runs, and its outcome is what the caller reads. */
-const runOnce = (agent, routine) => Effect.runPromise(runTurn(agent, routine.name, routineSession(routine.name), routine.prompt));
-/**
- * Run one routine and say what happened. THE one implementation, because there are two doors and only one
- * contract: `POST /run` on any host that publishes routes, and AgentCore's IAM-gated `routine-run` envelope on the
- * host that publishes none. A second copy is how the two would come to answer differently.
- */
-export async function runRoutineByName(agent, routine) {
-    const session = routineSession(routine.name);
-    const { busy, failed, ms } = await runOnce(agent, routine);
-    // BUSY IS NOT A FAILURE and it is the one "did not run" this has: a declared unit of work has ONE session, so a
-    // call arriving while the previous turn holds it is refused by that session. Reported as itself, with what the
-    // caller needs in order to decide — try later — rather than as an error it would retry blindly.
-    if (busy) {
-        return {
-            name: routine.name,
-            session,
-            ran: false,
-            reason: `the previous turn of "${routine.name}" is still running`,
-            ms,
-        };
-    }
-    return { name: routine.name, session, ran: true, ...(failed !== undefined ? { failed } : {}), ms };
-}
-/**
- * Build the handler for `GET /routines` — what a caller may ask for by name.
- *
- * DISCOVERY, because the alternative was a 404. The names were already public: `POST /run` lists them when a caller
- * gets one wrong, which is deliberate (an operator has to tell a typo from a stale caller) — so the only thing this
- * adds is not having to guess wrong first. "Expose a declared prompt as an API" is half a sentence without it.
- *
- * NAMES AND SCHEDULES, NEVER PROMPTS. What a routine SAYS is the definition's content; handing it to an
- * unauthenticated caller would publish the agent's behaviour, which is the one thing keeping the prompt out of the
- * request body was for. `cron` is here because it answers "will this run on its own, or is my clock the only one?",
- * which is a caller's question, not the definition's secret.
- *
- * Mounted exactly where `POST /run` is: it describes that route, so listing names a caller cannot use would be a
- * catalogue of nothing.
- */
-export function createRoutineListHandler(options) {
-    const { routines } = options;
-    if (routines.length === 0)
-        return undefined;
-    const body = routines.map((r) => ({
-        name: r.name,
-        ...(r.cron !== undefined ? { cron: r.cron } : {}),
-        ...(r.tz !== undefined ? { tz: r.tz } : {}),
-    }));
-    // NO METHOD CHECK. The router dispatches `GET /routines` here and nothing else, so the only thing such a check
-    // could reach is HEAD — which `channels/serve.ts` deliberately answers with the GET route, the same way
-    // `GET /health` is HEAD-probeable. Checking would break that and buy nothing.
-    return async () => Response.json(body);
-}
-/**
- * Build the handler for `POST /run`, bound to what this serve loaded.
- *
- * `undefined` when the definition declares nothing runnable: a route that can only ever answer 404 is not a route,
- * and the startup report names what is actually mounted.
- */
-export function createRunHandler(options) {
-    const { agent, routines } = options;
-    if (routines.length === 0)
-        return undefined;
-    return async (req) => {
-        if (req.method !== "POST")
-            return text("POST only\n", 405);
-        const wrongType = refuseNonJsonBody(req);
-        if (wrongType)
-            return wrongType;
-        const body = await readBodyCapped(req, MAX_RUN_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 { name } = (payload ?? {});
-        if (typeof name !== "string" || name === "") {
-            return text('need { "name": string } — e.g. {"name":"daily"}\n', 400);
-        }
-        const routine = routines.find((r) => r.name === name);
-        if (!routine)
-            return unknownRoutine(name, routines);
-        return Response.json(await runRoutineByName(agent, routine));
-    };
-}