@fastagent-sh/fastagent 0.21.1 → 0.22.0

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

@@ -1,22 +1,11 @@
-/**
- * AgentCore log discovery + tailing. The container's stdout/stderr lives in a per-endpoint CloudWatch
- * log group, while the forwarder Lambda has a separate group. This operator surface resolves the
- * stack's RuntimeArn, discovers the endpoint group by prefix, and tails it.
- *
- * NO STREAM FILTER, deliberately: AgentCore names its streams `YYYY/MM/DD/[runtime-logs]<session-id>`
- * (the Lambda `2024/01/01/[$LATEST]abc` convention), so `[runtime-logs]` is an INFIX after the UTC date
- * path, not a prefix. `--log-stream-name-prefix` is a literal prefix match, and the AWS CLI has no
- * substring filter (`--log-stream-names` takes exact names, which `--follow` could never extend to the
- * new session streams). Passing the marker as a prefix therefore matches zero streams and `aws logs
- * tail` prints nothing and exits 0 — a silent empty tail. Do not add it back.
- */
+/** AgentCore log discovery + tailing. */
 import type { CliRunner } from "../runner.ts";
 export type AgentcoreLogSource = "runtime" | "forwarder";
 export interface AgentcoreLogsPlan {
     /** Deployment base name — stack `fastagent-<name>`, forwarder `fastagent-<name>-forwarder`. */
     name: string;
     source: AgentcoreLogSource;
-    /** AWS CLI relative/ISO-8601 window (`10m`, `2h`, ...). Defaults to the CLI's own 10 minutes. */
+    /** AWS CLI relative/ISO-8601 window (`10m`, `2h`, ...). */
     since?: string;
     follow: boolean;
 }
@@ -27,9 +16,4 @@ export type AgentcoreLogsOutcome = {
     ok: false;
     gate: string;
 };
-/**
- * Find and tail one AgentCore log source. Discovery is dynamic rather than spelling `-DEFAULT`:
- * endpoint naming belongs to AWS, and an edited stack may use a different endpoint. The whole group
- * is tailed — see the file header for why a stream filter cannot narrow it and must not be added.
- */
 export declare function tailAgentcoreLogs(plan: AgentcoreLogsPlan, aws: CliRunner, announce?: (message: string) => void): Promise<AgentcoreLogsOutcome>;

package/dist/deploy/agentcore/logs.js

@@ -1,4 +1,6 @@
-import { parseStackOutputs } from "./run.js";
+import { awsCli, awsJson, parseLogGroupNames } from "./aws-cli.js";
+import { agentcoreStackName, forwarderLogGroup, runtimeLogGroupPrefix } from "./plan.js";
+import { pickStackOutputs } from "./run.js";
 /** Runtime id from `arn:...:runtime/<id>` — the id prefixes AgentCore's per-endpoint log group. */
 function runtimeIdFromArn(arn) {
     const marker = ":runtime/";
@@ -6,33 +8,21 @@ function runtimeIdFromArn(arn) {
     const id = at === -1 ? "" : arn.slice(at + marker.length);
     return id && !id.includes("/") ? id : undefined;
 }
-function parseLogGroupNames(stdout) {
-    try {
-        const parsed = JSON.parse(stdout);
-        return Array.isArray(parsed) && parsed.every((v) => typeof v === "string") ? parsed : undefined;
-    }
-    catch {
-        return undefined;
-    }
-}
-/**
- * Find and tail one AgentCore log source. Discovery is dynamic rather than spelling `-DEFAULT`:
- * endpoint naming belongs to AWS, and an edited stack may use a different endpoint. The whole group
- * is tailed — see the file header for why a stream filter cannot narrow it and must not be added.
- */
 export async function tailAgentcoreLogs(plan, aws, announce = () => { }) {
-    const stack = `fastagent-${plan.name}`;
-    const outputsResult = await aws(["cloudformation", "describe-stacks", "--stack-name", stack, "--query", "Stacks[0].Outputs", "--output", "json"], { capture: true });
-    if (outputsResult.code === 127) {
-        return { ok: false, gate: "aws CLI not found — install AWS CLI v2: https://docs.aws.amazon.com/cli/" };
+    const cli = awsCli(aws);
+    const stack = agentcoreStackName(plan.name);
+    // THROUGH THE ADJUDICATOR, like every other read of an AWS result in this directory: an exit code alone cannot
+    // separate "deploy it first" from `AccessDeniedException`.
+    const outputsRead = await cli.read(["cloudformation", "describe-stacks", "--stack-name", stack, "--query", "Stacks[0].Outputs", "--output", "json"], awsJson(pickStackOutputs));
+    if ("absent" in outputsRead) {
+        return { ok: false, gate: `no AgentCore stack ${stack} in this account/region — deploy it first` };
     }
-    if (outputsResult.code !== 0) {
-        return {
-            ok: false,
-            gate: `could not read AgentCore stack ${stack} — deploy it first, or fix the AWS account/region shown above`,
-        };
+    if ("unreadable" in outputsRead) {
+        if (outputsRead.code === 127)
+            return { ok: false, gate: outputsRead.unreadable };
+        return { ok: false, gate: `could not read AgentCore stack ${stack}: ${outputsRead.unreadable}` };
     }
-    const outputs = parseStackOutputs(outputsResult.stdout);
+    const outputs = outputsRead.ok;
     let prefix;
     let exact;
     if (plan.source === "runtime") {
@@ -44,17 +34,14 @@ export async function tailAgentcoreLogs(plan, aws, announce = () => { }) {
                 gate: `stack ${stack} has no valid RuntimeArn output — regenerate/deploy the AgentCore stack`,
             };
         }
-        prefix = `/aws/bedrock-agentcore/runtimes/${runtimeId}-`;
+        prefix = runtimeLogGroupPrefix(runtimeId);
     }
     else {
-        // `ForwarderUrl` is the stack's INGRESS URL, NOT proof that a forwarder Lambda exists: plan.ts
-        // keeps needsForwarder and needsFunctionUrl as two variables on purpose (a schedules-only topology
-        // may keep the forwarder and drop the public URL). So DISCOVERY decides existence below, and the
-        // URL output only picks which not-found sentence is true.
-        exact = `/aws/lambda/fastagent-${plan.name}-forwarder`;
+        // `ForwarderUrl` is the stack's INGRESS URL, NOT proof that a forwarder Lambda exists.
+        exact = forwarderLogGroup(plan.name);
         prefix = exact;
     }
-    const groupsResult = await aws([
+    const groupsRead = await cli.read([
         "logs",
         "describe-log-groups",
         "--log-group-name-prefix",
@@ -63,33 +50,22 @@ export async function tailAgentcoreLogs(plan, aws, announce = () => { }) {
         "logGroups[].logGroupName",
         "--output",
         "json",
-    ], { capture: true });
-    if (groupsResult.code !== 0) {
-        return { ok: false, gate: "could not discover the CloudWatch log group — see the AWS error above" };
-    }
-    const groups = parseLogGroupNames(groupsResult.stdout);
-    if (!groups) {
-        return { ok: false, gate: "AWS returned an invalid CloudWatch log-group response" };
+    ], parseLogGroupNames);
+    if ("unreadable" in groupsRead) {
+        // QUOTED, not "see the error above": the read captures both streams, so there is nothing above.
+        return { ok: false, gate: `could not discover the CloudWatch log group: ${groupsRead.unreadable}` };
     }
+    const groups = "ok" in groupsRead ? groupsRead.ok : [];
     const matches = groups.filter((group) => (exact ? group === exact : group.startsWith(prefix))).sort();
     if (matches.length === 0) {
-        // Absent group = never used, EXCEPT when the stack has no forwarder at all — an invoke-only
-        // deployment would otherwise be told to deliver a webhook it can never receive. Both facts agree
-        // there (no ingress URL output either), so the message can name the topology instead of a trigger.
-        if (plan.source === "forwarder" && !outputs.ForwarderUrl) {
-            return {
-                ok: false,
-                gate: `stack ${stack} has neither a forwarder log group nor an ingress URL — this looks like an invoke-only deployment, which has Runtime logs only`,
-            };
-        }
-        const trigger = plan.source === "runtime" ? "invoke the Runtime once" : "deliver one webhook or schedule fire";
+        // Absent group = never used.
+        const trigger = plan.source === "runtime" ? "invoke the Runtime once" : "deliver one webhook or routine run";
         return {
             ok: false,
             gate: `no ${plan.source} log group exists yet — ${trigger}, then retry (AWS creates it on first use)`,
         };
     }
-    // A generated stack has one Runtime endpoint. If an operator's edited stack has several, choosing
-    // one silently would show a valid but potentially WRONG agent log — list them and make the choice explicit.
+    // A generated stack has one Runtime endpoint.
     if (matches.length > 1) {
         return {
             ok: false,

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

@@ -1,6 +1,7 @@
 import type { DeclaredChannel } from "../../channels/discover.ts";
 import { type Artifact, type ContainerInput } from "../container.ts";
-/** The one schedule fact the plan needs (from loadSchedules) — name + cron + tz. */
+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;
@@ -11,15 +12,24 @@ export interface AgentcorePlanInput extends ContainerInput {
     name: string;
     /** What satisfies model auth locally: an env-var name, an OAuth/stored label, or undefined. */
     modelAuth: string | undefined;
-    /** Every declared channel and its ingress — the source of the secret list, the webhook steps, and
-     *  whether the forwarder is needed at all (ANY webhook channel requires it, customs included). */
+    /**
+     * Every declared channel and its ingress — the source of the webhook steps, and whether the
+     * forwarder is needed at all (ANY webhook channel requires it, customs included).
+     */
     channels: readonly DeclaredChannel[];
-    /** Extra secret env-var names (fastagent.config deploy.secrets). */
-    extraSecrets?: string[];
+    /**
+     * The runbook's variable list (`deploymentSecrets`): what must have a value, then everything else the value file
+     * carries.
+     */
+    secrets?: readonly DeploymentSecret[];
     /** 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;
+    /**
+     * 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
+     * {@link DEFAULT_IDLE_TIMEOUT_SECONDS}.
+     */
+    idleTimeoutSeconds?: number;
 }
 export interface AgentcorePlan {
     /** template + forwarder + Dockerfile/.dockerignore — written by the CLI (kept unless --force). */
@@ -34,79 +44,55 @@ export interface AgentcorePlan {
     /** What the stack contains — the ONE reading the template, the runbook and the `--run` driver share. */
     topology: AgentcoreTopology;
 }
-/**
- * Which resources the definition puts in the stack. Read in one place because it was computed in
- * three — the template, the plan and the CLI — and the third disagreed with the first about a
- * schedule EventBridge cannot express (counted by the CLI, not by the template), which is a
- * `cloudformation deploy` rejecting parameters the template never declared.
- */
+/** Which resources the definition puts in the stack. */
 export interface AgentcoreTopology {
     /** A webhook channel: the forwarder relays public Function URL traffic to it. */
     webhooks: boolean;
-    /** The forwarder Lambda exists — for webhooks, for EventBridge cron rules, or for wake alarms —
-     *  with its Function URL: every forwarder needs it as the authenticated refresh channel for the
-     *  state snapshot's presigned URLs, since a turn can outlive the Lambda credentials that signed
-     *  them. A schedule-only URL rejects every non-reserved path before invoking AgentCore. */
-    forwarder: boolean;
-    /** The forwarder mirrors the agent's wake-ups into one-shot EventBridge schedules. */
-    wakeAlarms: boolean;
 }
-/** 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";
+/** The platform's managed SessionStorage mount (AgentCore requires exactly `/mnt/<one-level>`). */
+export declare const MOUNT = "/mnt/data";
+/** Beside the state root on the one mount, as every volume-backed host does. */
+export declare const SECRETS_DIR = "/mnt/data/.secrets";
 /**
- * FASTAGENT_SECRETS_DIR — the seeded-then-ROTATED auth.json, deliberately INSIDE the state root
- * rather than beside it.
- *
- * Every other host mounts a real volume and puts the two machinery dirs side by side (`/data/.state`
- * + `/data/.secrets`), because there the persistence boundary is the MOUNT POINT: anything under it
- * survives. AgentCore has no volume. Its persistence boundary is `packStateRoot(stateRoot)` — the one
- * directory tree the S3 snapshot copies out and back (channels/agentcore-state.ts) — while {@link MOUNT}
- * itself is wiped on every runtime version update, i.e. on every deploy.
- *
- * So the sibling layout would put credentials INSIDE the mount but OUTSIDE the snapshot: nothing
- * copies them out, the platform wipes them, and the next microVM re-seeds the deploy-time copy. With
- * single-use OAuth refresh tokens that is a slow-motion outage — the box works until the seeded token
- * is rotated away, then loses model access with only a redeploy to restore it.
- *
- * Nesting is what makes agentcore-state.ts's stated contract ("restores VERBATIM — including
- * auth.json") reachable at all; `packStateRoot` walks the whole tree, so no snapshot code knows about
- * this. Tests assert the containment, not just the two names — the sibling spelling looks tidier and
- * reintroduces the outage silently.
+ * How long an idle session keeps its microVM when the config names no other value. Below AWS's own default (900) on
+ * purpose: memory bills for the whole idle tail, so the cheap posture is the default and a longer one is a choice.
  */
-export declare const SECRETS_DIR = "/mnt/state/.secrets";
-/**
- * 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 + time_of_last_update while
- * work is in flight (the FIELD is what the platform's idle measurement actually reads — agentcore.ts),
- * 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 DEFAULT_IDLE_TIMEOUT_SECONDS = 180;
+/** One session's compute lifetime — AWS's own default. Both lifecycle fields cap at 1209600 (14 d). */
 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;
+/**
+ * Where the forwarder puts the one-shot schedule for a wake-up. The id inside the name is minted in the
+ * 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;
+/** Account-suffixed artifact bucket for S3's global namespace. */
+export declare function deploymentBucketName(name: string, account: string): string;
+/**
+ * AgentCore env values max 2048 chars — a real OAuth auth.json's base64 exceeds it, so each carrier is CHUNKED across
+ * `<NAME>` + `_2`… (collectChunked reassembles at boot): FASTAGENT_AUTH_SEED for the credential, FASTAGENT_ENV for the
+ * value file's variables.
+ */
+export declare const CARRIER_CHUNK_SIZE = 2000;
+export declare const CARRIER_MAX_CHUNKS = 4;
+/** The template's two chunked carriers: CloudFormation parameter prefix → container env-var name. */
+export declare const CARRIERS: readonly [{
+    readonly param: "FastagentAuthSeed";
+    readonly env: "FASTAGENT_AUTH_SEED";
+    readonly what: "base64 auth.json";
+}, {
+    readonly param: "FastagentEnv";
+    readonly env: "FASTAGENT_ENV";
+    readonly what: "base64 JSON of the value file's variables";
+}];
+/** Chunk `i` (0-based) of a carrier: its parameter and env-var names. */
+export declare function carrierChunk(carrier: (typeof CARRIERS)[number], i: number): {
+    param: string;
+    env: string;
+};
 /** 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. */
+/** The generated template's first-line marker. */
 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;
@@ -114,51 +100,45 @@ export declare function isGeneratedAgentcoreTemplate(content: string): boolean;
 export declare function agentcoreName(workspaceBasename: string): string;
 /** 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.
+ * The two names every part of this host derives from the deployment name, and the reason they are functions:
+ * a deploy CREATES them and a destroy LOOKS FOR them, so a drift between the two spellings is silent in the
+ * worst direction. `describe-repositories` on a mis-spelled repo answers `RepositoryNotFoundException`, which
+ * is "already gone" — the teardown would report nothing left to delete while the repository kept billing.
+ */
+export declare function agentcoreStackName(name: string): string;
+export declare function agentcoreRepoName(name: string): string;
+/**
+ * Where a RUNTIME's logs land, by the identifier the caller happens to hold: `fastagent logs` knows the runtime id
+ * from the stack's `RuntimeArn`, `destroy` knows only the {@link toRuntimeName} the template deployed — and AgentCore
+ * names the id `<AgentRuntimeName>-<suffix>`, so the same prefix serves both. MEASURED (ap-southeast-1, 2026-09-22):
+ * a deploy of `destroy-probe-yehg` produced `/aws/bedrock-agentcore/runtimes/destroy_probe_yehg-6oR1zq7pBZ-DEFAULT`.
+ *
+ * ONE OWNER because of what the callers do with it: `logs` picks a group to tail, `destroy` DELETES everything the
+ * prefix matches. The trailing `-` is what keeps `probe-` off `probe2-…`, and a second hand-spelled copy of this
+ * string is a copy that can lose it.
  */
+export declare function runtimeLogGroupPrefix(runtimeOrName: string): string;
+/**
+ * Where the forwarder's logs land. Lambda creates this group itself, from the function name, so three parties have
+ * to agree on a string none of them can check against the others: the template that names the function, the runbook
+ * 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). */
+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. A real file, not a template
- * literal: it is linted, and it needs no interpolation — the one value it once took from here
- * (`MAX_WEBHOOK_BODY_BYTES`) rides in as a Lambda environment variable. Zero-dependency: the
- * Lambda Node runtime bundles AWS SDK v3. CommonJS ON PURPOSE: the package's entry lands as
- * `index.js` ({@link zipSingleFile}), where ESM `import` is a syntax error. 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).
- *
- * It ships as an S3 object rather than inline `ZipFile`, so there is no 4096-byte ceiling on it — a
- * constraint this comment asserted for long after the template stopped inlining, which is the kind
- * of stale rule that stops the next person making a correct change.
+ * 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. 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).
- */
+/** 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;