@fastagent-sh/fastagent 0.20.0 → 0.21.0

package/dist/cli/shared.d.ts

@@ -1,7 +1,19 @@
 import { type LoginIO, type LoginMethod, type LoginResult } from "../engines/pi/login.ts";
 import type { LoadedDefinition } from "../engines/pi/definition.ts";
-import type { ModuleLoadFailure } from "../loader.ts";
+import { type ModuleLoadFailure } from "../loader.ts";
 import type { ToolCollision } from "../engines/pi/tool.ts";
+import { type ResolvedPlacement } from "../paths.ts";
+/**
+ * How every command that runs the model enters its agent directory, in the one order that works:
+ * placement decides whose `.env` to read; `.env` may carry the proxy and the provider keys the
+ * picker's auth probe needs; the picker runs last. Six commands wrote these steps out by hand, and
+ * one carried the order as a comment. The result is the placement every later step reads.
+ */
+export declare function enterAgentCommand(dirArg: string, opts: {
+    model?: string;
+    authPath?: string;
+    input?: boolean;
+}): Promise<ResolvedPlacement>;
 /** What the startup report reads off an opened directory — a structural subset of the opener's return,
  *  spelled out so this module does not depend on that function's whole shape. */
 export interface ReportableAssembly {
@@ -60,23 +72,6 @@ export declare function parseBind(value: string | undefined): string | undefined
  *  Probes through the AGENT's model surface (`agentDir` carries its models.json), so a custom endpoint is
  *  reported like any built-in rather than as an unknown provider. */
 export declare function reportAuth(agentDir: string, modelSpec: string, authPath: string): Promise<void>;
-/**
- * First-run model resolution for every assembly command (dev/start/invoke/fire/chat/deploy): ONE
- * funnel, no dead ends. When no model is set (flag/env/config) and we're on a TTY, show the FULL
- * catalog annotated per provider — ready (with the credential source, so which account pays is
- * visible at the decision point) or login-required — and, when the choice needs auth, run the login
- * flow INLINE instead of exiting with "run `fastagent login` and come back". A no-op when a model is
- * 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. `agentDir` is the resolved
- * AGENT DIR (resolvePlacement().agentDir) — config and auth both live there.
- */
-export declare function resolveFirstRunModel(agentDir: string, options?: {
-    model?: string;
-    authPath?: string;
-    input?: boolean;
-}): Promise<void>;
 /**
  * Interactive login with the api_key quick-fail probe closed into a LOOP: a definitively rejected key
  * (HTTP 401) deletes the bad credential and RE-PROMPTS immediately — the user's hands are on the

package/dist/cli/shared.js

@@ -4,7 +4,7 @@
  * module-scoped flag access (`values.*`) became parameters.
  */
 import { readFile, writeFile } from "node:fs/promises";
-import { relative } from "node:path";
+import { relative, resolve } 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";
@@ -13,12 +13,28 @@ import { LoginCancelled, loginFlow } from "../engines/pi/login.js";
 import { createPiModelRuntime, createPiModels, probeApiKey, probeAuthSource, providerAuthStatuses, } from "../engines/pi/models.js";
 import { formatAuthReport } from "./auth-view.js";
 import { CODING_TOOL_NAMES } from "../engines/pi/create.js";
+import { reportModuleLoadFailures } from "../loader.js";
 import { reportFindingsIfChanged, reportToolCollisions } from "../engines/pi/report.js";
 import { workspaceHint } from "../paths.js";
-import { log, reportModuleLoadFailures } from "../log.js";
+import { log } from "../log.js";
+import { loadDotEnv } from "../env.js";
 import { openExternalUrl } from "../open-url.js";
+import { installProxyFetch } from "../proxy.js";
 import { bindAddress, isBindAddress } from "../bind.js";
-import { failStartup, failUsage } from "./fail.js";
+import { failStartup, failUsage, placementOrExit } from "./fail.js";
+/**
+ * How every command that runs the model enters its agent directory, in the one order that works:
+ * placement decides whose `.env` to read; `.env` may carry the proxy and the provider keys the
+ * picker's auth probe needs; the picker runs last. Six commands wrote these steps out by hand, and
+ * one carried the order as a comment. The result is the placement every later step reads.
+ */
+export async function enterAgentCommand(dirArg, opts) {
+    const placement = placementOrExit(resolve(dirArg));
+    loadDotEnv(placement.agentDir);
+    installProxyFetch();
+    await resolveFirstRunModel(placement.agentDir, opts);
+    return placement;
+}
 /**
  * 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
@@ -148,7 +164,7 @@ export async function reportAuth(agentDir, modelSpec, authPath) {
  * 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(agentDir, options = {}) {
+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)

package/dist/deploy/agentcore/forwarder.js

@@ -0,0 +1,250 @@
+// 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`.)
+// 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). With selfSchedule, 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.
+// CommonJS on purpose: the deployment package's entry lands as index.js, where ESM import is invalid.
+"use strict";
+const crypto = require("node:crypto");
+const { BedrockAgentCoreClient, InvokeAgentRuntimeCommand } = require("@aws-sdk/client-bedrock-agentcore");
+const client = new BedrockAgentCoreClient({});
+let ownUrl; // self-resolved once per cold start; rides on every envelope for the wake-alarm callback
+
+// Presigned S3 URLs for the container's state snapshot. AgentCore wipes the /mnt/state mount on
+// every runtime version update (= every deploy), so the durable copy lives in S3 — but the
+// container is given NO AWS credentials by the platform, so the only reachable form is a URL that
+// carries its own authorization. SigV4 query signing, node:crypto only (no SDK, nothing to install).
+const enc = (s) => encodeURIComponent(s).replace(/[!'()*]/g, (c) => `%${c.charCodeAt(0).toString(16).toUpperCase()}`);
+const hmac = (key, data) => crypto.createHmac("sha256", key).update(data).digest();
+
+// Every shared-secret gate on this public URL goes through here. Constant-time, and an unset
+// expected secret NEVER matches — otherwise a topology that did not configure one would accept a
+// request that sent none. Non-string input is coerced to "" first: Buffer.from(8) allocates eight
+// bytes rather than throwing, which would compare a number against a secret by length alone.
+const secretEq = (given, expected) => {
+  const a = Buffer.from(typeof given === "string" ? given : ""),
+    b = Buffer.from(expected || "");
+  return b.length > 0 && a.length === b.length && crypto.timingSafeEqual(a, b);
+};
+
+function presign(method, seconds) {
+  const bucket = process.env.STATE_BUCKET,
+    key = process.env.STATE_KEY,
+    region = process.env.AWS_REGION;
+  const host = `${bucket}.s3.${region}.amazonaws.com`;
+  const stamp = new Date().toISOString().replace(/[-:]/g, "").replace(/\.\d+/, "");
+  const scope = `${stamp.slice(0, 8)}/${region}/s3/aws4_request`;
+  const pairs = [
+    ["X-Amz-Algorithm", "AWS4-HMAC-SHA256"],
+    ["X-Amz-Credential", `${process.env.AWS_ACCESS_KEY_ID}/${scope}`],
+    ["X-Amz-Date", stamp],
+    ["X-Amz-Expires", String(seconds)],
+    ["X-Amz-SignedHeaders", "host"],
+  ];
+  if (process.env.AWS_SESSION_TOKEN) pairs.push(["X-Amz-Security-Token", process.env.AWS_SESSION_TOKEN]);
+  // The canonical query must be byte-identical to the one on the wire — build it ONCE, reuse below.
+  const query = pairs
+    .map(([k, v]) => [enc(k), enc(v)])
+    .sort((a, b) => (a[0] < b[0] ? -1 : 1))
+    .map((p) => p.join("="))
+    .join("&");
+  const path = `/${key.split("/").map(enc).join("/")}`;
+  const canonical = [method, path, query, `host:${host}\n`, "host", "UNSIGNED-PAYLOAD"].join("\n");
+  const sts = ["AWS4-HMAC-SHA256", stamp, scope, crypto.createHash("sha256").update(canonical).digest("hex")].join(
+    "\n",
+  );
+  let k = hmac(`AWS4${process.env.AWS_SECRET_ACCESS_KEY}`, stamp.slice(0, 8));
+  for (const part of [region, "s3", "aws4_request"]) k = hmac(k, part);
+  return `https://${host}${path}?${query}&X-Amz-Signature=${hmac(k, sts).toString("hex")}`;
+}
+
+async function invoke(envelope) {
+  if ((process.env.WAKE_SECRET || process.env.STATE_REFRESH_SECRET) && !ownUrl) {
+    const { LambdaClient, GetFunctionUrlConfigCommand } = require("@aws-sdk/client-lambda");
+    ownUrl = (
+      await new LambdaClient({}).send(
+        new GetFunctionUrlConfigCommand({ FunctionName: process.env.AWS_LAMBDA_FUNCTION_NAME }),
+      )
+    ).FunctionUrl;
+  }
+  if (ownUrl) envelope.wake = { url: ownUrl };
+  // Authenticates this envelope as coming from the forwarder (see the template's FastagentIngressSecret).
+  envelope.auth = process.env.INGRESS_SECRET;
+  // Keep each capability short-lived. Function-URL deployments also carry an authenticated refresh
+  // endpoint, so a background turn settling hours after its webhook never depends on the temporary
+  // Lambda credentials that signed the original pair still being alive.
+  if (process.env.STATE_BUCKET)
+    envelope.state = {
+      getUrl: presign("GET", 3600),
+      putUrl: presign("PUT", 3600),
+      ...(ownUrl && process.env.STATE_REFRESH_SECRET
+        ? {
+            refresh: {
+              url: `${ownUrl.replace(/\/$/, "")}/__fastagent/state-urls`,
+              auth: process.env.STATE_REFRESH_SECRET,
+            },
+          }
+        : {}),
+    };
+  const res = await client.send(
+    new InvokeAgentRuntimeCommand({
+      agentRuntimeArn: process.env.RUNTIME_ARN,
+      runtimeSessionId: process.env.INGRESS_SESSION_ID,
+      contentType: "application/json",
+      accept: "application/json",
+      payload: new TextEncoder().encode(JSON.stringify(envelope)),
+    }),
+  );
+  const body = Buffer.from(await res.response.transformToByteArray());
+  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
+// self-deletes (lazy cleanup by design).
+async function syncAlarms(alarms, ctx) {
+  const { SchedulerClient, CreateScheduleCommand, UpdateScheduleCommand } = require("@aws-sdk/client-scheduler");
+  const sch = new SchedulerClient({});
+  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.
+  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);
+    if (names.has(name)) {
+      failed += 1;
+      console.log(`alarm name collision ${name}: ${names.get(name)} vs ${a.id}`);
+      continue;
+    }
+    names.set(name, a.id);
+    const p = {
+      Name: name,
+      ScheduleExpression: `at(${a.at.slice(0, 19)})`,
+      ScheduleExpressionTimezone: "UTC",
+      FlexibleTimeWindow: { Mode: "OFF" },
+      ActionAfterCompletion: "DELETE",
+      Target: { Arn: ctx.invokedFunctionArn, RoleArn: process.env.WAKE_ROLE_ARN, Input: '{"wakePoke":true}' },
+    };
+    try {
+      await sch.send(new CreateScheduleCommand(p));
+    } catch (e) {
+      try {
+        if (e.name !== "ConflictException") throw e;
+        await sch.send(new UpdateScheduleCommand(p));
+      } catch (u) {
+        failed += 1;
+        console.log(`alarm ${p.Name}: ${u}`);
+      }
+    }
+  }
+  return failed;
+}
+
+exports.handler = async (event, ctx) => {
+  // EventBridge wake-up poke: the invocation itself wakes the container; its pump does the rest.
+  if (event?.wakePoke) {
+    const r = await invoke({ kind: "wake-poke" });
+    console.log(`wake-poke: ${r.status}`);
+    return { status: r.status };
+  }
+  // EventBridge Scheduler fire — throw on failure so the miss lands in CloudWatch, never silently.
+  if (event?.scheduleFire) {
+    const { name, slot } = event.scheduleFire;
+    const r = await invoke({ kind: "schedule-fire", name, slot });
+    const out = r.body.toString();
+    console.log(`schedule-fire ${name} (${slot}): ${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;
+  if (!http) throw new Error("unrecognized event shape");
+  // Refresh the snapshot capabilities with THIS Lambda invocation's current temporary credentials.
+  // The container may settle long after the webhook Lambda (and its credentials) expired.
+  if (event.rawPath === "/__fastagent/state-urls") {
+    const req = JSON.parse(event.isBase64Encoded ? Buffer.from(event.body, "base64").toString() : event.body || "{}");
+    if (!secretEq(req.auth, process.env.STATE_REFRESH_SECRET)) return { statusCode: 403, body: "forbidden\n" };
+    return {
+      statusCode: 200,
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({ getUrl: presign("GET", 3600), putUrl: presign("PUT", 3600) }),
+    };
+  }
+  // The container's wake-alarm callback (reserved path, shared secret) — handled HERE, never forwarded.
+  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);
+    // Partial failure IS failure: the container retries the whole (idempotent) set until every
+    // pending wake really has its alarm.
+    if (failed > 0) return { statusCode: 500, body: `${failed} alarm(s) failed\n` };
+    return { statusCode: 200, body: "ok\n" };
+  }
+  // The deploy driver's probe (reserved path, ingress secret): wake the runtime through the SAME
+  // trusted envelope pipeline (state URLs included — a direct InvokeAgentRuntime call could not mint
+  // them, and would make the runtime construct against a pre-restore mount) and pass its structured
+  // transport-200 verdict back VERBATIM. The ordinary webhook path below folds a non-200 transport
+  // into an opaque 502, which would strip exactly the diagnostics the probe exists to carry — and it
+  // sits BEFORE the WEBHOOKS_ENABLED gate so schedule-only topologies (whose URLs refuse ordinary
+  // public traffic) are probeable too.
+  if (event.rawPath === "/__fastagent/probe") {
+    const req = JSON.parse(event.isBase64Encoded ? Buffer.from(event.body, "base64").toString() : event.body || "{}");
+    if (!secretEq(req.auth, process.env.INGRESS_SECRET)) return { statusCode: 403, body: "forbidden\n" };
+    const r = await invoke({ kind: "probe" });
+    if (r.status !== 200) {
+      console.log(`probe transport error ${r.status}: ${r.body}`);
+      return { statusCode: 502, body: "upstream error\n" };
+    }
+    return { statusCode: 200, headers: { "content-type": "application/json" }, body: r.body.toString() };
+  }
+  // Enforce the advertised ORIGINAL-body ceiling before base64 adds another 4/3 inside the runtime
+  // envelope. This also leaves deterministic room for headers/query/JSON under Lambda's 6 MB cap.
+  const webhookBytes =
+    event.body === undefined
+      ? 0
+      : event.isBase64Encoded
+        ? Buffer.byteLength(event.body, "base64")
+        : Buffer.byteLength(event.body);
+  // The ceiling rides in as an env var (the template's MAX_WEBHOOK_BODY_BYTES), so a stack whose
+  // template predates it would compare against NaN — every comparison false, the limit silently gone.
+  const maxWebhookBytes = Number(process.env.MAX_WEBHOOK_BODY_BYTES);
+  if (!(maxWebhookBytes > 0))
+    throw new Error("MAX_WEBHOOK_BODY_BYTES is missing or invalid — redeploy to regenerate the stack template");
+  if (webhookBytes > maxWebhookBytes) return { statusCode: 413, body: "payload too large\n" };
+  // A schedule-only deployment has a Function URL solely for the authenticated refresh callback.
+  // Reject arbitrary public traffic BEFORE it can wake AgentCore (cost/DoS) or reach an inner route.
+  if (process.env.WEBHOOKS_ENABLED !== "1") return { statusCode: 404, body: "not found\n" };
+  // Function URL webhook — forward the original request verbatim (signature material included).
+  const r = await invoke({
+    kind: "webhook",
+    method: http.method,
+    path: event.rawPath || "/",
+    query: event.rawQueryString || undefined,
+    headers: event.headers || {},
+    bodyB64:
+      event.body === undefined
+        ? undefined
+        : event.isBase64Encoded
+          ? event.body
+          : Buffer.from(event.body).toString("base64"),
+  });
+  if (r.status !== 200) {
+    console.log(`transport error ${r.status}: ${r.body}`);
+    return { statusCode: 502, body: "upstream error\n" };
+  }
+  const reply = JSON.parse(r.body.toString()); // { status, headers, bodyB64 } from the adapter
+  for (const k of Object.keys(reply.headers)) {
+    if (/^(content-length|transfer-encoding|connection)$/i.test(k)) delete reply.headers[k];
+  }
+  return { statusCode: reply.status, headers: reply.headers, body: reply.bodyB64, isBase64Encoded: true };
+};

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

@@ -31,6 +31,25 @@ export interface AgentcorePlan {
         name: string;
         reason: string;
     }[];
+    /** 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.
+ */
+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).
@@ -117,8 +136,10 @@ export declare function toEventBridgeCron(cron: string): {
     error: string;
 };
 /**
- * The forwarder Lambda source — the ONLY string both the deployment package and the readable
- * `lambda/forwarder.js` artifact are generated from (one source, no drift). Zero-dependency: the
+ * 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