@fastagent-sh/fastagent 0.14.0 → 0.16.0

package/dist/cli/shared.js

@@ -1,17 +1,37 @@
 /**
  * Helpers shared across command modules: interactivity gates, port parsing, the startup auth report,
- * and first-run model resolution. Bodies moved verbatim from cli.ts; the module-scoped flag access
- * (`values.*`) became parameters.
+ * first-run model resolution, and the login terminal IO. Bodies moved verbatim from cli.ts; the
+ * module-scoped flag access (`values.*`) became parameters.
  */
 import { readFile, writeFile } from "node:fs/promises";
 import { relative } from "node:path";
-import { autocomplete, isCancel, select } from "@clack/prompts";
+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, loadConfig, resolveAuthPath, resolveModelSpec, rewriteConfigModel, } from "../engines/pi/config.js";
-import { configuredModelSpecs, createPiModels, probeAuthSource } from "../engines/pi/models.js";
-import { formatAuthReport } from "../cli-auth.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);
@@ -38,7 +58,7 @@ export function parsePort(value, source, from) {
 }
 /** Report which source provides the model's credentials, surfacing a remediation hint at startup. Non-blocking. */
 export async function reportAuth(modelSpec, authPath) {
-    const provider = modelSpec.slice(0, modelSpec.indexOf("/"));
+    const provider = providerOf(modelSpec);
     const source = await probeAuthSource(createPiModels({ authPath }), modelSpec);
     // Only when nothing satisfies auth do we read the store (refresh-FREE) to tell "nothing stored" from
     // "stored but unusable" — see formatAuthReport for why. store.read warns on a corrupt file itself.
@@ -53,54 +73,176 @@ export async function reportAuth(modelSpec, authPath) {
         log.warn(`[fastagent] ${report.warn}`);
 }
 /**
- * First-run model resolution for the serving commands. When no model is set (flag/env/config), and
- * we're on a TTY, pick one from the providers the user is logged into and persist the choice. A no-op
- * when a model is already set; on a non-TTY (CI/deploy), or with `--no-input`, or with nothing
- * configured it stays silent and lets the opener raise its clear "missing model" error. 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.
+ * 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 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);
-    let specs;
+    const authPath = resolveAuthPath(agentDir, options.authPath);
+    const models = createPiModels({ 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(agentDir, configPath, chosen);
+}
+/**
+ * The credential-aware pick: full catalog annotated per provider, then the post-pick auth policy —
+ * remedy warnings for providers no login flow can fix (the choice is KEPT: model validity is
+ * 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(models, authPath) {
+    let statuses;
     try {
-        specs = await configuredModelSpecs(createPiModels({ authPath }));
+        statuses = await providerAuthStatuses(models);
     }
     catch (error) {
-        // Enumerating providers/auth threw — a system fault (a corrupt auth store, a throwing provider),
-        // NOT "not logged in". Surface it instead of masking it as the login hint; the opener then still
-        // raises the clear missing-model error.
-        log.warn(`[fastagent] could not list configured models: ${error.message}`);
-        return;
-    }
-    if (specs.length === 0) {
-        log.warn(`[fastagent] no model set and no authenticated provider — run \`fastagent login\`, then \`fastagent dev\``);
-        return;
+        // Per-provider auth throws are captured as `broken` INSIDE providerAuthStatuses; reaching here
+        // means the enumeration itself failed (getProviders / a provider with no probe-able surface) — a
+        // system fault. Surface it; the opener then still raises the clear missing-model error.
+        log.warn(`[fastagent] could not probe provider auth: ${error.message}`);
+        return undefined;
     }
-    const r = await (specs.length > 7 ? autocomplete : select)({
+    const r = await autocomplete({
         message: "Choose a model for this agent",
-        options: specs.map((s) => ({ value: s, label: s })),
+        options: buildModelPickerOptions(listModels(models), statuses),
     });
     if (isCancel(r))
-        return; // cancelled: let the opener report the missing model
+        return undefined; // cancelled: the caller raises its clear missing-model error
     const chosen = r;
-    process.env.FASTAGENT_MODEL = chosen; // this process + any spawned dev worker inherits it
-    await persistModelChoice(workspaceDir, configPath, chosen);
+    const provider = providerOf(chosen);
+    const status = statuses.get(provider);
+    if (status?.state === "ready")
+        return chosen; // usable now — nothing to fix
+    if (status && status.login === "none") {
+        // No login flow exists for this provider — KEEP the choice and name the remedy. The remedy depends
+        // on WHY it is not ready: a BROKEN stored credential still owns the provider (env is consulted
+        // only when nothing is stored — createPiModels), so "set the env var" would not help there.
+        if (status.state === "broken") {
+            log.warn(`[fastagent] stored auth for "${provider}" is unusable: ${status.message} — fix or remove it in ${authPath}; invokes fail until then`);
+        }
+        else {
+            log.warn(`[fastagent] "${provider}" has no interactive login — set its API key env var; invokes fail until then`);
+        }
+        return chosen;
+    }
+    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.
+        await loginWithKeyCheck(provider, authPath, chosen);
+        console.error(`[fastagent] logged in to ${provider} — saved to ${authPath}`);
+    }
+    catch (error) {
+        if (error instanceof LoginCancelled)
+            return undefined; // user backed out — discard the choice, like a picker cancel
+        // A FAILED login keeps the choice: the pick persists, the startup auth report names the remedy,
+        // and a later `fastagent login` fixes auth without re-picking the model.
+        log.warn(`[fastagent] login for "${provider}" failed: ${error.message} — model saved; run \`fastagent login\` to fix auth`);
+    }
+    return chosen;
+}
+/**
+ * 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
+ * keyboard NOW; parking the failure for a later `fastagent login` would waste that. The loop exits on
+ * a verified/unverifiable key (kept), an OAuth login (completing the flow already proved the
+ * credential), or cancel (LoginCancelled propagates to the caller's cancel policy). Used by both the
+ * `login` command and the first-run picker's inline login.
+ */
+export async function loginWithKeyCheck(provider, authPath, spec, 
+// Test seams: this loop DESTROYS credential state on `rejected`, so its policy (rejected → delete →
+// re-ask ONLY the key) is pinned by a test through fake flow/verify; production callers omit both.
+seams = {}) {
+    const flow = seams.flow ?? loginFlow;
+    const verify = seams.verify ?? verifyApiKeyLogin;
+    const io = terminalLoginIO();
+    let method;
+    for (;;) {
+        const result = await flow(io, { provider, authPath, method });
+        if (result.method !== "api_key")
+            return result;
+        const verdict = await verify(result.provider, authPath, spec);
+        if (verdict !== "rejected")
+            return result;
+        // Retry re-asks ONLY the key: the provider/method choices weren't the mistake, the keystrokes were.
+        provider = result.provider;
+        method = "api_key";
+    }
+}
+/**
+ * Quick-fail check after an api_key login (OAuth needs none — completing the flow already proved the
+ * credential): probe the stored key with one minimal request against `spec`, or the provider's first
+ * model. Policy over {@link probeApiKey}'s verdict: `rejected` (definitive HTTP 401) DELETES the
+ * just-stored credential — a mistyped key must not persist as plausible state — and the caller
+ * ({@link loginWithKeyCheck}) re-prompts; `unknown` (network, quota, permissions) keeps it and prints
+ * the provider's message: the key may still be right, and wrongly destroying a good credential costs
+ * more than keeping a doubtful one.
+ */
+async function verifyApiKeyLogin(provider, authPath, spec) {
+    const models = createPiModels({ authPath });
+    const model = spec ? resolveModel(models, spec) : models.getProvider(provider)?.getModels()[0];
+    if (!model) {
+        console.error(`[fastagent] cannot verify the key: provider "${provider}" lists no models — kept as stored`);
+        return "unknown";
+    }
+    const label = `${model.provider}/${model.id}`;
+    console.error(`[fastagent] verifying the key with ${label}…`);
+    const probe = await probeApiKey(models, model);
+    if (probe.state === "ok") {
+        console.error(`[fastagent] key verified — ${label} responded`);
+    }
+    else if (probe.state === "rejected") {
+        await fastagentCredentialStore(authPath).delete(provider);
+        console.error(`[fastagent] ${provider} rejected the API key (HTTP 401): ${probe.message} — enter it again (or cancel)`);
+    }
+    else {
+        console.error(`[fastagent] could not verify the key with ${label}: ${probe.message} — kept; invokes surface the provider's error`);
+    }
+    return probe.state;
+}
+/** Login terminal IO via @clack/prompts: a searchable list once long, a hidden prompt for keys. Shared
+ *  by the `login` command and the first-run picker's inline login. */
+function terminalLoginIO() {
+    return {
+        async select(message, options) {
+            const r = await (options.length > 7 ? autocomplete : select)({ message, options });
+            return isCancel(r) ? undefined : r;
+        },
+        async prompt(message, opts) {
+            const r = opts?.hidden
+                ? await password({ message, signal: opts.signal })
+                : await clackText({ message, signal: opts?.signal });
+            return isCancel(r) ? undefined : r;
+        },
+        note: (message) => clackLog.info(message),
+        openUrl: openExternalUrl,
+    };
 }
 /**
- * Best-effort persist the picked model so the next run does not prompt. Only rewrites the commented
- * `model:` placeholder the scaffold writes (or an existing `model:` line); anything else (zero-config,
- * a hand-shaped config) is left untouched with a printed hint. Never throws — persistence is a convenience.
+ * 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 (a hand-shaped config) is
+ * left untouched with a printed hint. Never throws — persistence is a convenience.
  */
-async function persistModelChoice(workspaceDir, configPath, spec) {
-    const hint = () => console.error(`[fastagent] using ${spec} for this run; set \`model: ${JSON.stringify(spec)}\` in your config to persist`);
+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`);
     if (!configPath)
         return hint();
     try {
@@ -108,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/collect.d.ts

@@ -1,9 +1,20 @@
 /**
- * Buffered consumption helper (caller-side, SPEC §7): reduce an AgentEvent stream to a final value,
- * encoding the terminal discipline (failed → throw, missing terminal → error). Streaming consumers
- * for-await themselves.
+ * Caller-side stream helpers: `collect` (buffered consumption, SPEC §7) reduces an AgentEvent
+ * stream to a final value, encoding the terminal discipline (failed → throw, missing terminal →
+ * error) — streaming consumers for-await themselves. `abortFirstIterator` is the shared
+ * cancellation protocol for generator-backed streams.
  */
 import type { AgentEvent, Json } from "./agent.ts";
+/**
+ * The abort-first cancellation protocol, ONCE: an async generator suspended on a quiet await (a
+ * tool mid-execution, a silent SSE read) parks inside that await, and `gen.return()`/`gen.throw()`
+ * queue behind the pending `next()` FOREVER (async-generator semantics) — a consumer's cancel
+ * would deadlock. The wrapper's `return()` first runs `cancel` (abort the underlying work, which
+ * settles the suspension), then delegates to `gen.return`, swallowing its rejection (the
+ * generator's own catch/finally already surfaced the outcome). `throw()` tears down identically
+ * and rethrows the caller's error deterministically instead of poking a completed generator.
+ */
+export declare function abortFirstIterator<T>(gen: AsyncGenerator<T>, cancel: () => void): AsyncIterator<T>;
 /** Exception form of a failed event (thrown by collect). Carries the failed event's fields verbatim, so
  *  a buffered consumer can branch on `code` (SPEC §8 failure subdivision) just like a streaming one. */
 export declare class AgentFailure extends Error {

package/dist/collect.js

@@ -1,3 +1,27 @@
+/**
+ * The abort-first cancellation protocol, ONCE: an async generator suspended on a quiet await (a
+ * tool mid-execution, a silent SSE read) parks inside that await, and `gen.return()`/`gen.throw()`
+ * queue behind the pending `next()` FOREVER (async-generator semantics) — a consumer's cancel
+ * would deadlock. The wrapper's `return()` first runs `cancel` (abort the underlying work, which
+ * settles the suspension), then delegates to `gen.return`, swallowing its rejection (the
+ * generator's own catch/finally already surfaced the outcome). `throw()` tears down identically
+ * and rethrows the caller's error deterministically instead of poking a completed generator.
+ */
+export function abortFirstIterator(gen, cancel) {
+    return {
+        next: () => gen.next(),
+        async return(value) {
+            cancel();
+            await gen.return(value).catch(() => { });
+            return { done: true, value: undefined };
+        },
+        async throw(error) {
+            cancel();
+            await gen.return(undefined).catch(() => { });
+            throw error;
+        },
+    };
+}
 /** Exception form of a failed event (thrown by collect). Carries the failed event's fields verbatim, so
  *  a buffered consumer can branch on `code` (SPEC §8 failure subdivision) just like a streaming one. */
 export class AgentFailure extends Error {

package/dist/core.d.ts

@@ -2,9 +2,11 @@ export type { Agent, AgentEvent, ImageRef, Json, Prompt, Scope } from "./agent.t
 export { collect, AgentFailure, type CollectResult } from "./collect.ts";
 export type { ModuleLoadFailure } from "./loader.ts";
 export { createInvokeHandler, nodeListener } from "./channels/http.ts";
+export { controlRoutes, type ControlRoutesOptions, type WireEvent } from "./channels/control.ts";
+export { ControlRequestError, connectAgent, connectSessionControl, type RemoteEndpointOptions, } from "./session-remote.ts";
 export { readBodyCapped } from "./channels/body.ts";
 export { text, textHeaders } from "./channels/respond.ts";
-export { type ChannelContext, type ChannelHandler, type ChannelModule, type Routes, router, serveNode, } from "./host/node.ts";
+export { type ChannelContext, type ChannelHandler, type ChannelModule, type LongConnection, type LongConnectionChannelModule, type Routes, router, serveNode, } from "./host/node.ts";
 export { defineSchedule, type LoadedSchedule, type Schedule } from "./schedule/schedule.ts";
 export { discoverScheduleFiles, loadSchedules } from "./schedule/discover.ts";
 export { createScheduler, scheduleSession, type Scheduler, type SchedulerOptions } from "./schedule/scheduler.ts";

package/dist/core.js

@@ -1,5 +1,7 @@
 export { collect, AgentFailure } from "./collect.js";
 export { createInvokeHandler, nodeListener } from "./channels/http.js";
+export { controlRoutes } from "./channels/control.js";
+export { ControlRequestError, connectAgent, connectSessionControl, } from "./session-remote.js";
 export { readBodyCapped } from "./channels/body.js";
 export { text, textHeaders } from "./channels/respond.js";
 export { router, serveNode, } from "./host/node.js";

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;