@fastagent-sh/fastagent 0.24.4 → 0.25.0

package/dist/deploy/agentcore/destroy.js

@@ -1,5 +1,5 @@
 import { awsCli, awsJson, parseLogGroupNames } from "./aws-cli.js";
-import { agentcoreRepoName, agentcoreStackName, deploymentBucketName, forwarderLogGroup, runtimeLogGroupPrefix, toRuntimeName, wakeAlarmPrefix, } from "./plan.js";
+import { agentcoreRepoName, agentcoreStackName, deploymentBucketName, forwarderLogGroup, runtimeLogGroupPrefix, recurringSchedulePrefix, toRuntimeName, wakeAlarmPrefix, } from "./plan.js";
 /** S3 deletes at most 1000 keys per call. */
 const DELETE_BATCH = 1000;
 /**
@@ -59,18 +59,33 @@ export async function destroyAgentcoreDeployment(plan, runner, announce = () =>
     // the wrong profile has to be able to see that from the line above the failure.
     announce(`account ${account}, region ${region}`);
     // ---- What is out there. Each read gets its own policy for "AWS could not answer". ----
-    // The alarm ids are minted inside the container, so the PREFIX is all we can ask for. Unreadable is a gate
-    // here: an alarm nobody deleted keeps firing at a Lambda that is about to stop existing.
-    const prefix = wakeAlarmPrefix(plan.name);
-    const listed = await aws.read(["scheduler", "list-schedules", "--name-prefix", prefix, "--output", "json"], parseScheduleNames);
-    if ("unreadable" in listed)
-        return gate(`could not list wake alarms under ${prefix}: ${listed.unreadable}`);
-    // THE FULL SHAPE, not just the prefix. The forwarder mints every alarm as prefix + sha256(wakeId)[:16]
-    // (plan.ts / forwarder.js), and a prefix alone is ambiguous between sibling agents: a workspace literally
+    // The schedule names are minted inside the container, so the PREFIXES are all we can ask for. Unreadable is a gate
+    // here: a schedule nobody deleted keeps firing at a Lambda that is about to stop existing.
+    const minted = [
+        { what: "wake alarm", prefix: wakeAlarmPrefix(plan.name) },
+        { what: "schedule", prefix: recurringSchedulePrefix(plan.name) },
+    ];
+    // THE FULL SHAPE, not just the prefix. The forwarder mints every name as prefix + sha256(id)[:16]
+    // (plan.ts / forwarder.js), and a prefix alone is ambiguous between sibling agents: an agent directory literally
     // named `<name>-wk-abc` produces `fa-<name>-wk-abc-wk-<hash>`, which starts with THIS deployment's prefix.
-    // Deleting it would take a live deployment's pending wake-ups, and a wake-up is not re-created.
-    const isMintedAlarm = (alarm) => alarm.startsWith(prefix) && /^[0-9a-f]{16}$/.test(alarm.slice(prefix.length));
-    const alarms = ("ok" in listed ? listed.ok : []).filter(isMintedAlarm);
+    // Deleting it would take a live deployment's pending wake-ups or schedules.
+    const listMinted = async (prefix) => {
+        const listed = await aws.read(["scheduler", "list-schedules", "--name-prefix", prefix, "--output", "json"], parseScheduleNames);
+        if ("unreadable" in listed)
+            return listed;
+        const names = "ok" in listed ? listed.ok : [];
+        return {
+            ok: names.filter((name) => name.startsWith(prefix) && /^[0-9a-f]{16}$/.test(name.slice(prefix.length))),
+        };
+    };
+    const held = [];
+    for (const kind of minted) {
+        const listed = await listMinted(kind.prefix);
+        if ("unreadable" in listed) {
+            return gate(`could not list ${kind.what}s under ${kind.prefix}: ${listed.unreadable}`);
+        }
+        held.push({ ...kind, names: listed.ok });
+    }
     // A GATE for these three, because they decide whether the REPORT is true. `delete-stack` answers 0 for a
     // stack that does not exist, so "deleted: stack X" for a stack nobody deployed — or "nothing left to delete"
     // over a runtime that is still billing — is the false signal this repo refuses.
@@ -148,8 +163,10 @@ export async function destroyAgentcoreDeployment(plan, runner, announce = () =>
     const listedGroups = [...named(forwarderRead).filter((name) => name === forwarderGroup), ...named(runtimeRead)];
     const logGroups = "unreadable" in forwarderRead ? [forwarderGroup, ...listedGroups] : listedGroups;
     const found = [];
-    if (alarms.length > 0)
-        found.push(`${alarms.length} wake alarm(s) under ${prefix}`);
+    for (const kind of held) {
+        if (kind.names.length > 0)
+            found.push(`${kind.names.length} ${kind.what}(s) under ${kind.prefix}`);
+    }
     if (stackExists)
         found.push(`stack ${stack}`);
     if (bucketExists)
@@ -185,13 +202,14 @@ export async function destroyAgentcoreDeployment(plan, runner, announce = () =>
         return false;
     };
     const swept = new Set();
-    const sweepAlarms = async (names) => {
-        for (const alarm of names.filter((name) => !swept.has(name))) {
-            swept.add(alarm);
-            await attempt(`wake alarm ${alarm}`, ["scheduler", "delete-schedule", "--name", alarm]);
+    const sweep = async (what, names) => {
+        for (const name of names.filter((name) => !swept.has(name))) {
+            swept.add(name);
+            await attempt(`${what} ${name}`, ["scheduler", "delete-schedule", "--name", name]);
         }
     };
-    await sweepAlarms(alarms);
+    for (const kind of held)
+        await sweep(kind.what, kind.names);
     if (stackExists) {
         announce(`deleting stack ${stack} (this waits for CloudFormation)…`);
         const asked = await aws.write(["cloudformation", "delete-stack", "--stack-name", stack]);
@@ -211,15 +229,15 @@ export async function destroyAgentcoreDeployment(plan, runner, announce = () =>
                 `from are untouched, so a retry has what it needs.`, { found, removed, kept });
         }
         removed.push(`stack ${stack}`);
-        // AGAIN, NOW. The container served the whole deletion and holds `scheduler:CreateSchedule`, so a wake-up
-        // taken in those minutes minted an alarm after the first sweep read the list — an alarm whose target is the
-        // Lambda we just deleted, retrying into nothing for weeks.
-        const after = await aws.read(["scheduler", "list-schedules", "--name-prefix", prefix, "--output", "json"], parseScheduleNames);
-        if ("unreadable" in after) {
-            failures.push(`re-listing wake alarms under ${prefix}: ${after.unreadable}`);
-        }
-        else {
-            await sweepAlarms(("ok" in after ? after.ok : []).filter(isMintedAlarm));
+        // AGAIN, NOW. The container served the whole deletion and could create schedules, so a wake-up taken or a
+        // schedule written in those minutes minted one after the first sweep read the list — one whose target is the
+        // Lambda we just deleted, retrying into nothing.
+        for (const kind of minted) {
+            const after = await listMinted(kind.prefix);
+            if ("unreadable" in after)
+                failures.push(`re-listing ${kind.what}s under ${kind.prefix}: ${after.unreadable}`);
+            else
+                await sweep(kind.what, after.ok);
         }
     }
     if (bucketExists && foreign.length === 0)

package/dist/deploy/agentcore/forwarder.js

@@ -1,15 +1,16 @@
 // Generated by `fastagent deploy agentcore` — the deployment's only ingress.
 // (Inside fastagent this file IS the source; the sentence below applies to the copy it is emitted as,
-// the workspace's `lambda/index.js`.)
+// the agent directory's `lambda/index.js`.)
 // REGENERATED ON EVERY DEPLOY; edits here are overwritten and never deployed. `--run` builds the
 // Lambda package from fastagent's own copy of this source, so this file is the readable MIRROR of
 // what runs (and what the manual runbook zips) — not an input you can change.
 // Webhooks (Function URL) and EventBridge Scheduler fires are forwarded as envelopes to the
 // AgentCore Runtime over SigV4 InvokeAgentRuntime, all on ONE fixed ingress session (fastagent
 // channel state is single-writer; one session = at most one microVM). This
-// Lambda also OWNS the wake alarms: the container POSTs its pending wake-ups to /__fastagent/
-// wake-alarm (shared secret) and each becomes a self-deleting one-shot EventBridge schedule that
-// pokes this Lambda — which wakes the container, whose wake pump fires the due entry.
+// Lambda also OWNS the alarms: the container POSTs its schedules and pending wake-ups to
+// /__fastagent/wake-alarm (shared secret). Each schedule becomes a RECURRING EventBridge cron schedule
+// that delivers each instant's fire on EventBridge's own clock; each wake-up becomes a self-deleting
+// one-shot that pokes the container, whose wake pump fires the due entry.
 // CommonJS on purpose: the deployment package's entry lands as index.js, where ESM import is invalid.
 "use strict";
 const crypto = require("node:crypto");
@@ -52,22 +53,24 @@ async function invoke(envelope) {
   return { status: res.statusCode ?? 200, body };
 }
 
-// Mirror the container's pending wake-ups into one-shot schedules: at(fireAt), poke me, delete
-// after firing. Upsert (create → conflict → update). The container pre-filters DUE alarms (it is
-// awake handling those), so every failure here is REAL — counted and propagated: a swallowed error
-// would leave a pending wake with no alarm, exactly the reliability hole this mechanism closes.
-// Cancelled wakes are NOT deleted here: their poke fires, finds nothing due, and the schedule
+/** The EventBridge name for one alarm id: prefix + a stable hash of the WHOLE id. */
+const mintedName = (prefix, id) => prefix + crypto.createHash("sha256").update(id).digest("hex").slice(0, 16);
+
+// Mirror the container's pending wake-ups into one-shot schedules: at(fireAt), poke me, delete after firing. Upsert
+// (create → conflict → update): an id names one instant, so the update is the same alarm mirrored again, never a
+// spent one moved. The container pre-filters DUE alarms (it is awake handling those), so every failure here is REAL —
+// counted and propagated: a swallowed error would leave a pending wake with no alarm, exactly the reliability hole
+// this mechanism closes. Cancelled wakes are NOT deleted here: their poke fires, finds nothing due, and the schedule
 // self-deletes (lazy cleanup by design).
-async function syncAlarms(alarms, ctx) {
-  const { SchedulerClient, CreateScheduleCommand, UpdateScheduleCommand } = require("@aws-sdk/client-scheduler");
-  const sch = new SchedulerClient({});
+async function syncAlarms(sch, alarms, ctx) {
+  const { CreateScheduleCommand, UpdateScheduleCommand } = require("@aws-sdk/client-scheduler");
   let failed = 0;
-  // Alarm name = a stable hash of the WHOLE wake id. A prefix of the id would collide (two wakes
-  // sharing 8 hex chars), and a collision is INDISTINGUISHABLE from the legitimate re-arm below:
-  // the second wake would "update" the first's alarm and silently steal its fire time.
+  // Alarm name = a stable hash of the WHOLE alarm id. A prefix of the id would collide (two alarms
+  // sharing 8 hex chars), and a collision is INDISTINGUISHABLE from the legitimate re-mirror below:
+  // the second alarm would "update" the first and silently steal its fire time.
   const names = new Map();
   for (const a of alarms) {
-    const name = process.env.WAKE_PREFIX + crypto.createHash("sha256").update(a.id).digest("hex").slice(0, 16);
+    const name = mintedName(process.env.WAKE_PREFIX, a.id);
     if (names.has(name)) {
       failed += 1;
       console.log(`alarm name collision ${name}: ${names.get(name)} vs ${a.id}`);
@@ -80,6 +83,7 @@ async function syncAlarms(alarms, ctx) {
       ScheduleExpressionTimezone: "UTC",
       FlexibleTimeWindow: { Mode: "OFF" },
       ActionAfterCompletion: "DELETE",
+      // It only wakes the container, whose pump fires what is due.
       Target: { Arn: ctx.invokedFunctionArn, RoleArn: process.env.WAKE_ROLE_ARN, Input: '{"wakePoke":true}' },
     };
     try {
@@ -97,12 +101,86 @@ async function syncAlarms(alarms, ctx) {
   return failed;
 }
 
+// Make the recurring schedules exactly the container's set: create what is missing, update what differs, delete what
+// it no longer has. Declarative, so a delete that failed is retried by the next sync, and the update is skipped when
+// nothing changed (every sync carries the whole set, and a sync follows every wake-up too). Only names this Lambda
+// mints are deleted: a prefix alone also matches a sibling agent named `<name>-sc-…`.
+async function syncSchedules(sch, schedules, ctx) {
+  const {
+    CreateScheduleCommand,
+    UpdateScheduleCommand,
+    GetScheduleCommand,
+    DeleteScheduleCommand,
+    ListSchedulesCommand,
+  } = require("@aws-sdk/client-scheduler");
+  const prefix = process.env.SCHEDULE_PREFIX;
+  const held = new Set();
+  let NextToken;
+  do {
+    const page = await sch.send(new ListSchedulesCommand({ NamePrefix: prefix, NextToken }));
+    for (const s of page.Schedules || []) {
+      if (s.Name.startsWith(prefix) && /^[0-9a-f]{16}$/.test(s.Name.slice(prefix.length))) held.add(s.Name);
+    }
+    NextToken = page.NextToken;
+  } while (NextToken);
+  let failed = 0;
+  const wanted = new Set();
+  for (const s of schedules) {
+    const p = {
+      Name: mintedName(prefix, s.name),
+      ScheduleExpression: s.expression,
+      ScheduleExpressionTimezone: s.tz,
+      FlexibleTimeWindow: { Mode: "OFF" },
+      State: "ENABLED",
+      // <aws.scheduler.scheduled-time> is the clock's NAME for this occurrence: EventBridge repeats it byte-identical
+      // on every redelivery, which is what makes the container's claim work.
+      Target: {
+        Arn: ctx.invokedFunctionArn,
+        RoleArn: process.env.WAKE_ROLE_ARN,
+        Input: JSON.stringify({ scheduleFire: { name: s.name, occurrence: "<aws.scheduler.scheduled-time>" } }),
+      },
+    };
+    wanted.add(p.Name);
+    try {
+      if (!held.has(p.Name)) {
+        await sch.send(new CreateScheduleCommand(p));
+        continue;
+      }
+      const now = await sch.send(new GetScheduleCommand({ Name: p.Name }));
+      // Every field this Lambda sets. RoleArn too: the role's name is CloudFormation's, so a stack recreated over a
+      // schedule left behind gives it a new one, and a schedule still naming the old role never fires again.
+      const same =
+        now.ScheduleExpression === p.ScheduleExpression &&
+        now.ScheduleExpressionTimezone === p.ScheduleExpressionTimezone &&
+        now.State === p.State &&
+        now.Target?.Input === p.Target.Input &&
+        now.Target?.Arn === p.Target.Arn &&
+        now.Target?.RoleArn === p.Target.RoleArn;
+      if (!same) await sch.send(new UpdateScheduleCommand(p));
+    } catch (e) {
+      failed += 1;
+      console.log(`schedule ${s.name} (${p.Name}): ${e}`);
+    }
+  }
+  for (const name of held) {
+    if (wanted.has(name)) continue;
+    try {
+      await sch.send(new DeleteScheduleCommand({ Name: name }));
+    } catch (e) {
+      if (e.name === "ResourceNotFoundException") continue;
+      failed += 1;
+      console.log(`schedule ${name} (delete): ${e}`);
+    }
+  }
+  return failed;
+}
+
 /**
  * Invoke the container, and leave ONE line under `label` whichever way it ends — including the way that never came
  * back at all.
  *
  * Lambda already logs an unhandled throw, so the failure is not invisible; what it is not is ATTRIBUTABLE. An
- * operator (or a probe) filtering this log group for `routine-fire <name>` sees nothing and concludes the clock
+ * operator (or a probe) filtering this log group for `schedule-fire <name>` sees nothing and concludes the clock
  * never fired, when what actually happened is that the clock fired and the call died. Those need different fixes
  * and looked identical from outside — that mistake cost a real debugging session.
  */
@@ -125,11 +203,11 @@ exports.handler = async (event, ctx) => {
   // EventBridge Scheduler fire — throw on failure so the miss lands in CloudWatch, never silently.
   if (event?.scheduleFire) {
     const { name, occurrence } = event.scheduleFire;
-    const label = `routine-fire ${name} (${occurrence})`;
-    const r = await invokeLogged(label, { kind: "routine-fire", name, occurrence });
+    const label = `schedule-fire ${name} (${occurrence})`;
+    const r = await invokeLogged(label, { kind: "schedule-fire", name, occurrence });
     const out = r.body.toString();
     console.log(`${label}: ${r.status} ${out}`);
-    if (r.status >= 400) throw new Error(`routine-fire ${name} failed: ${r.status} ${out}`);
+    if (r.status >= 400) throw new Error(`schedule-fire ${name} failed: ${r.status} ${out}`);
     return { status: r.status };
   }
   const http = event?.requestContext?.http;
@@ -138,9 +216,14 @@ exports.handler = async (event, ctx) => {
   if (event.rawPath === "/__fastagent/wake-alarm") {
     const req = JSON.parse(event.isBase64Encoded ? Buffer.from(event.body, "base64").toString() : event.body || "{}");
     if (!secretEq(req.secret, process.env.WAKE_SECRET)) return { statusCode: 403, body: "forbidden\n" };
-    const failed = await syncAlarms(req.alarms || [], ctx);
+    const { SchedulerClient } = require("@aws-sdk/client-scheduler");
+    const sch = new SchedulerClient({});
+    // A sync request names the WHOLE schedule set; one without it is not a sync, and deleting every schedule on it
+    // would be the wrong answer.
+    if (!Array.isArray(req.schedules)) return { statusCode: 400, body: "schedules: expected the whole set\n" };
+    const failed = (await syncAlarms(sch, req.alarms || [], ctx)) + (await syncSchedules(sch, req.schedules, ctx));
     // Partial failure IS failure: the container retries the whole (idempotent) set until every
-    // pending wake really has its alarm.
+    // schedule and pending wake really has its EventBridge schedule.
     if (failed > 0) return { statusCode: 500, body: `${failed} alarm(s) failed\n` };
     return { statusCode: 200, body: "ok\n" };
   }

package/dist/deploy/agentcore/logs.js

@@ -59,7 +59,7 @@ export async function tailAgentcoreLogs(plan, aws, announce = () => { }) {
     const matches = groups.filter((group) => (exact ? group === exact : group.startsWith(prefix))).sort();
     if (matches.length === 0) {
         // Absent group = never used.
-        const trigger = plan.source === "runtime" ? "invoke the Runtime once" : "deliver one webhook or routine run";
+        const trigger = plan.source === "runtime" ? "invoke the Runtime once" : "deliver one webhook or schedule fire";
         return {
             ok: false,
             gate: `no ${plan.source} log group exists yet — ${trigger}, then retry (AWS creates it on first use)`,

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

@@ -1,12 +1,6 @@
 import type { DeclaredChannel } from "../../channels/discover.ts";
 import { type Artifact, type ContainerInput } from "../container.ts";
 import type { DeploymentSecret } from "../secrets.ts";
-/** The one schedule fact the plan needs (from loadRoutines) — 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;
@@ -20,8 +14,6 @@ export interface AgentcorePlanInput extends ContainerInput {
      * carries.
      */
     secrets?: readonly DeploymentSecret[];
-    /** Static schedules — each becomes an EventBridge Scheduler rule targeting the forwarder. */
-    schedules: ScheduleFact[];
     /**
      * How long an idle session keeps its microVM (config `deploy.agentcore.idleTimeoutSeconds`). The workload decides:
      * a chat agent talked to in bursts wants a longer tail than a schedule-only one. Defaults to
@@ -40,11 +32,6 @@ export interface AgentcorePlan {
     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;
-    }[];
     /** What the stack contains — the ONE reading the template, the runbook and the `--run` driver share. */
     topology: AgentcoreTopology;
 }
@@ -70,6 +57,11 @@ export declare const FORWARDER_FILE = "lambda/index.js";
  * container, so this prefix is the only handle anything outside has on the alarms a deployment has pending.
  */
 export declare function wakeAlarmPrefix(name: string): string;
+/**
+ * Where the forwarder puts the recurring schedule for each `schedules/` file. Set at runtime by the container (the
+ * set follows edits), so like the wake alarms it is no stack resource, and this prefix is the handle on them.
+ */
+export declare function recurringSchedulePrefix(name: string): string;
 /** Account-suffixed artifact bucket for S3's global namespace. */
 export declare function deploymentBucketName(name: string, account: string): string;
 /**
@@ -95,8 +87,8 @@ export declare const TEMPLATE_FILE = "agentcore.template.yaml";
 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;
-/** Deployment base name from the workspace basename — the ONE mapping used to find its stack later. */
-export declare function agentcoreName(workspaceBasename: string): string;
+/** Deployment base name from the agent directory's name — the ONE mapping used to find its stack later. */
+export declare function agentcoreName(agentDirName: string): string;
 /** Runtime name (`[a-zA-Z][a-zA-Z0-9_]{0,47}`) from a dir basename. */
 export declare function toRuntimeName(basename: string): string;
 /**
@@ -124,20 +116,14 @@ export declare function runtimeLogGroupPrefix(runtimeOrName: string): string;
  * and `--run` summary that tell an operator to set its retention, and `fastagent logs --source forwarder`.
  */
 export declare function forwarderLogGroup(name: string): string;
-/** The ONE fixed ingress session id (webhooks + routine fires). */
+/** The `invoke-agent-runtime` payload IAM may send: a probe, answered `{"ok":true}` once the definition opened. */
+export declare const PROBE_PAYLOAD: string;
+/** The ONE fixed ingress session id (webhooks + schedule fires). */
 export declare function ingressSessionId(name: string): string;
-/** Translate a 5-field cron into EventBridge Scheduler's `cron(m h dom mon dow *)`, or say why it can't be. */
-export declare function toEventBridgeCron(cron: string): {
-    expression: string;
-} | {
-    error: string;
-};
 /**
  * The forwarder Lambda source — `forwarder.js` beside this file, the ONE text both the deployment package and the
  * readable `lambda/index.js` artifact are generated from.
  */
 export declare function forwarderSource(): string;
-/** The EventBridge physical name for a schedule. */
-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;