@fastagent-sh/fastagent 0.15.0 → 0.16.0

package/dist/cli/serve.js

@@ -4,6 +4,9 @@
  */
 import { chmodSync, mkdirSync, renameSync, rmSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
+import { createStateSync } from "../channels/agentcore-state.js";
+import { agentcoreRoutes, UnknownScheduleError } from "../channels/agentcore.js";
+import { activeWork } from "../channels/busy.js";
 import { controlRoutes } from "../channels/control.js";
 import { INVOKE_EXAMPLE_BODY, createInvokeHandler } from "../channels/http.js";
 import { text } from "../channels/respond.js";
@@ -13,15 +16,15 @@ import { parseRouteKey, router, serveNode } from "../host/node.js";
 import { log } from "../log.js";
 import { openExternalUrl } from "../open-url.js";
 import { loadSchedules } from "../schedule/discover.js";
-import { createScheduler } from "../schedule/scheduler.js";
+import { createScheduler, fireScheduleOnce } from "../schedule/scheduler.js";
 import { announceWebhooks, startCloudflareTunnel } from "../tunnel.js";
 import { failStartup } from "./fail.js";
 /**
  * The surface this deployment serves: default `GET /health` plus discovered channels, or the default
  * POST `/invoke` only when neither a route nor a long-connection channel was declared.
  */
-export async function routesFor(workspaceDir, agent, stateRoot, control) {
-    const { routes, longConnections, routeChannels, collisions, failures } = await loadChannels(workspaceDir, {
+export async function routesFor(agentDir, agent, stateRoot, control, options = {}) {
+    const { routes, longConnections, routeChannels, collisions, failures } = await loadChannels(agentDir, {
         agent,
         stateRoot,
         control,
@@ -34,7 +37,7 @@ export async function routesFor(workspaceDir, agent, stateRoot, control) {
         throw new Error(`channel setup is invalid (${failures.length} load failure(s), ${collisions.length} route collision(s)) — ` +
             `fix it, or rename an intentionally disabled file to *.disabled`);
     }
-    const builtinInvoke = Object.keys(routes).length === 0 && longConnections.length === 0;
+    const builtinInvoke = options.builtinInvoke !== false && Object.keys(routes).length === 0 && longConnections.length === 0;
     const channels = builtinInvoke ? { "POST /invoke": createInvokeHandler(agent) } : routes;
     const healthCovered = Object.keys(channels).some((key) => {
         const entry = parseRouteKey(key);
@@ -53,7 +56,7 @@ export async function routesFor(workspaceDir, agent, stateRoot, control) {
     };
 }
 /**
- * Mount the session control plane (`/control/*`) when the workspace enabled it
+ * Mount the session control plane (`/control/*`) when the agent enabled it
  * (`config.sessionControl`): merge the bearer-authenticated routes and return an announcer that
  * writes `<stateRoot>/control.json` — `{ url, token }`, 0600 — once the port is known. The file is
  * the LOCAL discovery channel (`fastagent attach`, a local desktop app); filesystem permissions are
@@ -132,6 +135,46 @@ export function mountSessionControl(routes, control, stateRoot, options = {}) {
         },
     };
 }
+/**
+ * Mount the AgentCore Runtime adapter (`POST /invocations` + `GET /ping`) over the serving routes —
+ * the deployed container's ONLY reachable surface (channels/agentcore.ts). Wired by `start` when
+ * `FASTAGENT_AGENTCORE=1` (set by the generated deploy artifacts, never by hand). A channel colliding
+ * on either path fails startup, same disposition as the control-plane mount: the adapter's paths are
+ * the platform's contract, so a channel shadowing them would silently unserve the whole deployment.
+ */
+export function mountAgentcore(routes, options) {
+    const { agent, stateRoot, schedules, onStateReady } = options;
+    const mounted = agentcoreRoutes({
+        routes,
+        agent,
+        stateRoot,
+        isBusy: () => activeWork() > 0,
+        // Cross-deploy durability: AgentCore wipes the state mount on every runtime version update, so
+        // the state root is restored from (and pushed to) an S3 snapshot through presigned URLs the
+        // forwarder mints per envelope. Always wired on this path — the platform gives no other way to
+        // keep an agent's memory across a deploy.
+        stateSync: createStateSync({ stateRoot }),
+        // What separates a forwarder envelope from any IAM principal's InvokeAgentRuntime call. Absent =
+        // no forwarder in this topology, so only the public `invoke` kind is servable.
+        ingressSecret: process.env.FASTAGENT_INGRESS_SECRET,
+        onStateReady,
+        fire: schedules.length === 0
+            ? undefined
+            : (name, slot) => {
+                const schedule = schedules.find((s) => s.name === name);
+                if (!schedule)
+                    throw new UnknownScheduleError(name);
+                return fireScheduleOnce({ agent, stateRoot, schedule, slot });
+            },
+    });
+    const mountedPaths = new Set(Object.keys(mounted).map((key) => parseRouteKey(key).path));
+    const collisions = Object.keys(routes).filter((key) => mountedPaths.has(parseRouteKey(key).path));
+    if (collisions.length > 0) {
+        throw new Error(`channel route(s) ${collisions.map((key) => `"${key}"`).join(", ")} collide with the AgentCore adapter ` +
+            `(/invocations, /ping) — rename the channel route`);
+    }
+    return { ...routes, ...mounted };
+}
 /**
  * Bind HTTP, open long-connection channels, and report ready only when both forms are usable. Each
  * adapter owns reconnects; a terminal close rejects `closed` and fails the process visibly. Abort is
@@ -217,32 +260,36 @@ export function serve(surface, port, onListening) {
     });
 }
 /** Start a Cloudflare tunnel for route channels only. */
-export function maybeTunnel(workspaceDir, routeChannels, boundPort, tunnel, stateRoot) {
+export function maybeTunnel(agentDir, routeChannels, boundPort, tunnel, stateRoot) {
     if (!tunnel || process.env.FASTAGENT_DEV_WORKER === "1")
         return;
     void startCloudflareTunnel(boundPort).then((instance) => {
         if (!instance)
             return;
-        void announceWebhooks(workspaceDir, instance.url, { openUrl: openExternalUrl, routeChannels, stateRoot });
+        void announceWebhooks(agentDir, instance.url, { openUrl: openExternalUrl, routeChannels, stateRoot });
         const cleanup = () => instance.close();
         process.once("SIGINT", cleanup);
         process.once("SIGTERM", cleanup);
     });
 }
 /**
- * Load and start the workspace's `schedules/` — a time-trigger firing the agent on each cron. Starts iff
- * there are static schedules OR `selfSchedule` is on. Best-effort stop on process signals.
+ * Load and start the agent's `schedules/` — a time-trigger firing the agent on each cron. Starts iff
+ * there are static schedules OR `selfSchedule` is on. Best-effort stop on process signals. Returns the
+ * loaded schedules so a serving surface that needs them (the AgentCore adapter's fire binding) shares
+ * ONE load instead of re-discovering. `externalClock` (AgentCore) arms no resident cron timers.
  */
-export async function startSchedules(workspaceDir, agent, stateRoot, selfSchedule) {
-    const { schedules, failures } = await loadSchedules(workspaceDir).catch(failStartup);
+export async function startSchedules(agentDir, agent, stateRoot, selfSchedule, options = {}) {
+    const { schedules, failures } = await loadSchedules(agentDir).catch(failStartup);
     reportModuleLoadFailures(failures);
     if (schedules.length === 0 && !selfSchedule)
-        return;
-    const scheduler = createScheduler({ agent, stateRoot, schedules });
+        return schedules;
+    const scheduler = createScheduler({ agent, stateRoot, schedules, externalClock: options.externalClock });
     scheduler.start();
-    if (schedules.length > 0)
-        log.info(`[fastagent] schedules: ${schedules.map((s) => s.name).join(", ")}`);
+    if (schedules.length > 0) {
+        log.info(`[fastagent] schedules: ${schedules.map((s) => s.name).join(", ")}${options.externalClock ? " (external clock — no resident cron timers)" : ""}`);
+    }
     const stop = () => scheduler.stop();
     process.once("SIGINT", stop);
     process.once("SIGTERM", stop);
+    return schedules;
 }

package/dist/cli/shared.d.ts

@@ -1,4 +1,16 @@
 import { type LoginIO, type LoginMethod, type LoginResult } from "../engines/pi/login.ts";
+/**
+ * The padded label writer for the STARTUP report (`dev`/`start`, stderr via the log level). Hand-spaced
+ * labels drift out of alignment the moment a longer one appears — which is exactly what happened when
+ * `workspace:` joined `config:`/`model:`/`state:`. `info` keeps its own writer on purpose: its report is
+ * stdout DATA (pipeable, its own label set, its own width), not a log line — the shared thing is the
+ * policy (pad, never hand-space), not a constant.
+ */
+export declare function reportLine(label: string, value: string): void;
+/** The workspace hint under the `agent:`/`workspace:` pair, when there is one ({@link workspaceHint}):
+ *  you pointed at the agent, and the project around it is probably what you meant. A hint, so it renders
+ *  as one and is silent otherwise — `dev` and `start` both print the pair, so both ask for it. */
+export declare function reportWorkspaceHint(hint: string | undefined): void;
 /** Both stdin and stdout are a terminal — the precondition for an interactive prompt. */
 export declare function isInteractive(): boolean;
 /**
@@ -19,9 +31,10 @@ export declare function reportAuth(modelSpec: string, authPath: string): Promise
  * already set; on a non-TTY (CI, a piped stdin), with `--no-input`, on cancel, or on a failed login
  * it stays quiet and lets the caller raise its own clear error (`missing model`, or deploy's
  * model-travel gate). The pick is exported to FASTAGENT_MODEL so a spawned `dev` worker inherits it,
- * and best-effort written back to the config so the next run is quiet.
+ * and best-effort written back to the config so the next run is quiet. `agentDir` is the resolved
+ * AGENT DIR (resolvePlacement().agentDir) — config and auth both live there.
  */
-export declare function resolveFirstRunModel(workspaceDir: string, options?: {
+export declare function resolveFirstRunModel(agentDir: string, options?: {
     model?: string;
     authPath?: string;
     input?: boolean;

package/dist/cli/shared.js

@@ -8,14 +8,30 @@ import { relative } from "node:path";
 import { autocomplete, isCancel, log as clackLog, password, select, text as clackText } from "@clack/prompts";
 import { buildModelPickerOptions } from "./models-view.js";
 import { fastagentCredentialStore } from "../engines/pi/auth.js";
-import { isValidPort, listModels, loadConfig, providerOf, resolveAuthPath, resolveModel, resolveModelSpec, resolveStateRoot, rewriteConfigModel, } from "../engines/pi/config.js";
-import { ensureStateRootSelfIgnored, isUnderDir } from "../engines/pi/definition.js";
+import { isValidPort, listModels, loadConfig, providerOf, resolveAuthPath, resolveModel, resolveModelSpec, rewriteConfigModel, } from "../engines/pi/config.js";
 import { LoginCancelled, loginFlow } from "../engines/pi/login.js";
 import { createPiModels, probeApiKey, probeAuthSource, providerAuthStatuses } from "../engines/pi/models.js";
 import { formatAuthReport } from "./auth-view.js";
 import { log } from "../log.js";
 import { openExternalUrl } from "../open-url.js";
 import { failStartup, failUsage } from "./fail.js";
+/**
+ * The padded label writer for the STARTUP report (`dev`/`start`, stderr via the log level). Hand-spaced
+ * labels drift out of alignment the moment a longer one appears — which is exactly what happened when
+ * `workspace:` joined `config:`/`model:`/`state:`. `info` keeps its own writer on purpose: its report is
+ * stdout DATA (pipeable, its own label set, its own width), not a log line — the shared thing is the
+ * policy (pad, never hand-space), not a constant.
+ */
+export function reportLine(label, value) {
+    log.info(`[fastagent] ${`${label}:`.padEnd(11)}${value}`);
+}
+/** The workspace hint under the `agent:`/`workspace:` pair, when there is one ({@link workspaceHint}):
+ *  you pointed at the agent, and the project around it is probably what you meant. A hint, so it renders
+ *  as one and is silent otherwise — `dev` and `start` both print the pair, so both ask for it. */
+export function reportWorkspaceHint(hint) {
+    if (hint)
+        reportLine("hint", hint);
+}
 /** Both stdin and stdout are a terminal — the precondition for an interactive prompt. */
 export function isInteractive() {
     return Boolean(process.stdin.isTTY && process.stdout.isTTY);
@@ -65,23 +81,24 @@ export async function reportAuth(modelSpec, authPath) {
  * already set; on a non-TTY (CI, a piped stdin), with `--no-input`, on cancel, or on a failed login
  * it stays quiet and lets the caller raise its own clear error (`missing model`, or deploy's
  * model-travel gate). The pick is exported to FASTAGENT_MODEL so a spawned `dev` worker inherits it,
- * and best-effort written back to the config so the next run is quiet.
+ * and best-effort written back to the config so the next run is quiet. `agentDir` is the resolved
+ * AGENT DIR (resolvePlacement().agentDir) — config and auth both live there.
  */
-export async function resolveFirstRunModel(workspaceDir, options = {}) {
-    const { config, path: configPath } = await loadConfig(workspaceDir).catch(failStartup);
+export async function resolveFirstRunModel(agentDir, options = {}) {
+    const { config, path: configPath } = await loadConfig(agentDir).catch(failStartup);
     if (resolveModelSpec(options.model, config))
         return; // already set (flag > FASTAGENT_MODEL > config)
     if (options.input === false)
         return; // --no-input: never prompt (clig) — the opener raises the clear error
     if (!isInteractive())
         return; // CI/deploy: the opener throws the actionable missing-model error
-    const authPath = resolveAuthPath(workspaceDir, options.authPath);
+    const authPath = resolveAuthPath(agentDir, options.authPath);
     const models = createPiModels({ authPath });
-    const chosen = await pickWithCredentials(workspaceDir, models, authPath);
+    const chosen = await pickWithCredentials(models, authPath);
     if (chosen === undefined)
         return; // cancelled (or auth probe failed): the caller raises its clear missing-model error
     process.env.FASTAGENT_MODEL = chosen; // this process + any spawned dev worker inherits it
-    await persistModelChoice(workspaceDir, configPath, chosen);
+    await persistModelChoice(agentDir, configPath, chosen);
 }
 /**
  * The credential-aware pick: full catalog annotated per provider, then the post-pick auth policy —
@@ -89,7 +106,7 @@ export async function resolveFirstRunModel(workspaceDir, options = {}) {
  * independent of credentials), or the inline login for the rest. Returns the chosen spec, or
  * undefined when the pick should be discarded (picker cancel, login cancel, a failed auth probe).
  */
-async function pickWithCredentials(workspaceDir, models, authPath) {
+async function pickWithCredentials(models, authPath) {
     let statuses;
     try {
         statuses = await providerAuthStatuses(models);
@@ -124,11 +141,6 @@ async function pickWithCredentials(workspaceDir, models, authPath) {
         }
         return chosen;
     }
-    // Inline login. Same leak guard as `login`: self-ignore the state root BEFORE a credential
-    // can land in-tree, so the secret is never untracked-but-committable.
-    const stateRoot = resolveStateRoot(workspaceDir);
-    if (isUnderDir(authPath, stateRoot))
-        await ensureStateRootSelfIgnored(workspaceDir, stateRoot);
     try {
         // Verified against the CHOSEN model — the exact request the agent is about to make; a rejected
         // key re-prompts inside the loop, so reaching here means a usable (or at worst unverifiable) key.
@@ -224,10 +236,10 @@ function terminalLoginIO() {
 /**
  * Best-effort persist the picked model so the next run does not prompt. Rewrites the commented
  * `model:` placeholder the scaffold writes / an existing `model:` line, or re-inserts the line into a
- * scaffold-shaped config (the hand-deleted-to-reset case); anything else (zero-config, a hand-shaped
- * config) is left untouched with a printed hint. Never throws — persistence is a convenience.
+ * scaffold-shaped config (the hand-deleted-to-reset case); anything else (a hand-shaped config) is
+ * left untouched with a printed hint. Never throws — persistence is a convenience.
  */
-async function persistModelChoice(workspaceDir, configPath, spec) {
+async function persistModelChoice(agentDir, configPath, spec) {
     const hint = () => console.error(
     // No "using it for this run" promise: deploy's model-travel gate rightly ignores the un-persisted pick.
     `[fastagent] picked ${spec} — set \`model: ${JSON.stringify(spec)}\` in your config to persist`);
@@ -238,7 +250,7 @@ async function persistModelChoice(workspaceDir, configPath, spec) {
         if (!replaced)
             return hint();
         await writeFile(configPath, replaced);
-        console.error(`[fastagent] saved model ${JSON.stringify(spec)} to ${relative(workspaceDir, configPath)}`);
+        console.error(`[fastagent] saved model ${JSON.stringify(spec)} to ${relative(agentDir, configPath)}`);
     }
     catch {
         hint();

package/dist/deploy/agentcore/plan.d.ts

@@ -0,0 +1,117 @@
+import type { ChannelKind } from "../../scaffold/add-channel.ts";
+import { type Artifact, type ContainerInput } from "../container.ts";
+/** The one schedule fact the plan needs (from loadSchedules) — name + cron + tz. */
+export interface ScheduleFact {
+    name: string;
+    cron: string;
+    tz?: string;
+}
+export interface AgentcorePlanInput extends ContainerInput {
+    /** Base name (dir basename) — shapes the runtime name, stack name, ECR repo, session id. */
+    name: string;
+    /** What satisfies model auth locally: an env-var name, an OAuth/stored label, or undefined. */
+    modelAuth: string | undefined;
+    /** Known first-party channels — each contributes its secret metadata + webhook step. */
+    channels: ChannelKind[];
+    /** ALL route-channel basenames (customs included) — any of them requires the forwarder. */
+    routeChannels: string[];
+    /** Extra secret env-var names (fastagent.config deploy.secrets). */
+    extraSecrets?: string[];
+    /** Static schedules — each becomes an EventBridge Scheduler rule targeting the forwarder. */
+    schedules: ScheduleFact[];
+    /** Wake tool enabled — DEGRADED here (fires only while a session happens to be awake); warned. */
+    selfSchedule: boolean;
+}
+export interface AgentcorePlan {
+    /** template + forwarder + Dockerfile/.dockerignore — written by the CLI (kept unless --force). */
+    artifacts: Artifact[];
+    /** The ordered, values-resolved deploy runbook — printed to stdout. */
+    runbook: string[];
+    /** Cron expressions EventBridge cannot express — surfaced as runbook warnings, not silent drops. */
+    untranslatableSchedules: {
+        name: string;
+        reason: string;
+    }[];
+}
+/** SessionStorage mount = FASTAGENT_STATE_DIR (AgentCore requires exactly `/mnt/<one-level>`). It is
+ *  a fast LOCAL disk only: the platform wipes it on every runtime version update (= every deploy).
+ *  Durability across deploys comes from the S3 snapshot (channels/agentcore-state.ts). */
+export declare const MOUNT = "/mnt/state";
+/**
+ * How long an idle session keeps its microVM. Memory is billed per second across the WHOLE session
+ * — idle included, at the peak level reached — so this tail is the standing cost of every burst of
+ * activity, while CPU stops billing the moment the agent stops working. 3 minutes rather than the
+ * platform's 15: the tail shrinks 5×, and the cost is a cold start (image + Node + snapshot restore)
+ * for anyone who returns after a longer gap. `/ping` reports HealthyBusy while work is in flight, so
+ * this timer only ever starts once the agent has genuinely settled — a long turn is never cut short.
+ * AWS accepts 60–28800.
+ */
+export declare const IDLE_TIMEOUT_SECONDS = 180;
+/** The platform ceiling on one session's compute (8 h). The session ID outlives it: the next invoke
+ *  simply gets fresh compute with the same storage. */
+export declare const MAX_LIFETIME_SECONDS = 28800;
+/** The state snapshot's object key in the deployment bucket (one object; see agentcore-state.ts). */
+export declare const STATE_KEY = "state/snapshot.json.gz";
+/** The forwarder artifact. Named `index.js` because it IS the Lambda deployment package's entry:
+ *  zipping it as-is produces a valid package (`Handler: index.handler`), with nothing to rename. */
+export declare const FORWARDER_FILE = "lambda/index.js";
+/** The deployment bucket: forwarder code + the state snapshot. Account-suffixed for S3's GLOBAL
+ *  namespace, and created OUTSIDE the stack (like the ECR repo) so a `delete-stack` cannot take the
+ *  agent's memory with it. Bucket names cap at 63 chars; `name` is already gated to 40. */
+export declare function stateBucketName(name: string, account: string): string;
+/** AgentCore env values max 2048 chars — a real OAuth auth.json's base64 exceeds it, so the seed is
+ *  CHUNKED across FASTAGENT_AUTH_SEED + _2… (collectAuthSeed reassembles at boot). 2000 keeps margin. */
+export declare const AUTH_SEED_CHUNK_SIZE = 2000;
+export declare const AUTH_SEED_MAX_CHUNKS = 4;
+/** The generated template's filename (namespaced under the kit in the agentDir layout). */
+export declare const TEMPLATE_FILE = "agentcore.template.yaml";
+/** The generated template's first-line marker — the ONE source for both the generator and the
+ *  "did fastagent generate this?" check (deploy's drift gate), so they cannot drift apart. */
+export declare const GENERATED_TEMPLATE_MARKER = "# Generated by `fastagent deploy agentcore`";
+/** Whether an on-disk template is fastagent-generated (vs hand-written — kept, never gated). */
+export declare function isGeneratedAgentcoreTemplate(content: string): boolean;
+/** Runtime name (`[a-zA-Z][a-zA-Z0-9_]{0,47}`) from a dir basename. */
+export declare function toRuntimeName(basename: string): string;
+/** The ONE fixed ingress session id (webhooks + schedule fires) — ≥ 33 chars (the API minimum),
+ *  deterministic (the Lambda holds it in env), padded so any name clears the floor. */
+export declare function ingressSessionId(name: string): string;
+/** CFN parameter logical id for a secret env-var name: TELEGRAM_BOT_TOKEN → TelegramBotToken
+ *  (parameter names must be alphanumeric). Deterministic — run.ts builds the same mapping. */
+export declare function cfnParamName(envName: string): string;
+/**
+ * Translate a 5-field cron into EventBridge Scheduler's `cron(m h dom mon dow *)`, or say why it
+ * can't be. The two dialects disagree exactly where silent translation would misfire:
+ *  - EventBridge numbers day-of-week 1–7 (1 = Sunday); standard cron uses 0–6 (0/7 = Sunday) —
+ *    numeric dow values and range endpoints are remapped ({@link mapDowField}); steps and names
+ *    pass through; a range that wraps under renumbering is refused.
+ *  - EventBridge requires `?` in dom or dow: a `*` on either side becomes `?`; BOTH restricted is
+ *    standard cron's OR semantics, which EventBridge cannot express — refused, never approximated.
+ *  - A 6-field (seconds) expression and L/# day-of-week forms are refused for the same reason.
+ */
+export declare function toEventBridgeCron(cron: string): {
+    expression: string;
+} | {
+    error: string;
+};
+/**
+ * The forwarder Lambda source — the ONLY string both the template's inline ZipFile and the readable
+ * `lambda/forwarder.js` artifact are generated from (one source, no drift). Zero-dependency: the
+ * Lambda Node runtime bundles AWS SDK v3. CommonJS ON PURPOSE: CloudFormation inline code always
+ * lands as `index.js`, where ESM `import` is a syntax error (found by the first real deploy). Two
+ * event shapes: a Function URL webhook (reconstructed verbatim into a `webhook` envelope; the
+ * channel's REAL response rides back inside the transport reply and is re-emitted byte-exact —
+ * Feishu's URL-verification challenge depends on it), and an EventBridge Scheduler fire
+ * (`{ scheduleFire }`, slot = the scheduled instant — the container's idempotency key). MUST stay
+ * under CloudFormation's 4096-byte inline-code cap.
+ */
+export declare function forwarderSource(): string;
+/**
+ * The EventBridge physical name for a schedule. A schedule's local name is an arbitrary MODULE FILE
+ * NAME (`schedules/晨报.ts`, `schedules/deploy check.ts`), while AWS requires `[0-9A-Za-z-_.]+` within
+ * 64 chars — and the `fa-<agent>-` prefix already eats up to 44 of them. So: sanitize, bound the
+ * readable part, and end with a hash of the ORIGINAL name, which keeps distinct schedules distinct
+ * where sanitizing or truncation would have merged them (one rule silently firing for two).
+ */
+export declare function scheduleResourceName(agent: string, schedule: string): string;
+/** Compute the AgentCore deploy plan from the resolved definition. */
+export declare function planAgentcoreDeploy(input: AgentcorePlanInput): AgentcorePlan;