@fastagent-sh/fastagent 0.16.1 → 0.17.0

package/dist/channels/agentcore-state.js

@@ -41,6 +41,13 @@ const PUT_TIMEOUT_MS = 60_000;
  * file from the builder machine, but the box's own copy is the one that has been REFRESHED, and this
  * snapshot is its volume: the same rule every other host states ("a credential already refreshed on
  * the volume is never overwritten"). The seed is bootstrap for a snapshot that has none.
+ *
+ * That sentence is only true because the generated template points FASTAGENT_SECRETS_DIR INSIDE the
+ * state root (deploy/agentcore/plan.ts `SECRETS_DIR`) — nothing here special-cases credentials, the
+ * walk below simply reaches them. Moving the secrets dir back out (e.g. to the sibling layout the
+ * volume-backed hosts use) silently un-does it: the file stops being copied, the platform wipes it
+ * with the microVM, and a single-use OAuth refresh token dies with it. `restores VERBATIM` is a
+ * statement about where that directory is, not a property this module can enforce on its own.
  */
 const EXCLUDED = new Set(["control.json"]);
 /** Every regular file under `root`, as root-relative POSIX paths (stable across platforms). */

package/dist/channels/agentcore.js

@@ -19,7 +19,8 @@
  *  - `{ kind: "invoke", session, text }` — the programmatic data plane; streams the invoke back as
  *    SSE (AgentCore's streaming response form), reusing the HTTP channel's handler wholesale.
  *
- * `/ping` reports `HealthyBusy` while process-wide background work is in flight (busy.ts) — webhook
+ * `/ping` reports `HealthyBusy` (+ `time_of_last_update`, required — see the handler) while
+ * process-wide background work is in flight (busy.ts) — webhook
  * channels ACK fast and run turns fire-and-forget, and AgentCore ends an idle session, so without
  * this signal a long turn would be killed mid-flight right after its ACK. `Healthy` when idle lets
  * the platform reclaim the microVM (that idle-to-zero IS the point of this deployment).
@@ -242,12 +243,30 @@ export function agentcoreRoutes(options) {
             stateSync.save();
         return response;
     };
+    // The Runtime ping contract: Healthy = reclaimable, HealthyBusy = keep the session alive
+    // (background turns in flight). `time_of_last_update` is REQUIRED for the keep-alive to work,
+    // despite the contract documenting it as optional ("If you omit the field, the platform tracks
+    // status changes on its own"): measured on a live Runtime (us-east-1, 2026-08-04), the platform's
+    // idle measurement reads ONLY this field — with it omitted, a session polling every ~2s and
+    // receiving HealthyBusy 200s was still reclaimed at exactly IdleRuntimeSessionTimeout after the
+    // last InvokeAgentRuntime, mid-turn, 2s after the last HealthyBusy answer; with the field present
+    // the same turn survived 3.5× the idle timeout with zero invocations and completed. The value
+    // updates ONLY on a real status change: a timestamp advancing on every ping declares a perpetual
+    // status change, so the idle timeout never fires and dead-idle sessions live to MaxLifetime
+    // (quota exhaustion — the failure mode the contract's warning describes).
+    let lastStatus = "Healthy";
+    let lastTransition = Math.floor(Date.now() / 1000);
     return {
         "POST /invocations": invocations,
-        // The Runtime ping contract: Healthy = reclaimable, HealthyBusy = keep the session alive
-        // (background turns in flight). No time_of_last_update — the platform tracks status changes
-        // itself, and a timestamp advancing every ping would defeat the idle timeout (their docs warn).
-        "GET /ping": () => json({ status: isBusy() ? "HealthyBusy" : "Healthy" }, 200),
+        "GET /ping": () => {
+            const status = isBusy() ? "HealthyBusy" : "Healthy";
+            if (status !== lastStatus) {
+                lastTransition = Math.floor(Date.now() / 1000);
+                log.debug(`[agentcore] ping status: ${lastStatus} → ${status}`);
+                lastStatus = status;
+            }
+            return json({ status, time_of_last_update: lastTransition }, 200);
+        },
     };
 }
 /** Thrown by the mount-site `fire` binding when the envelope names a schedule this workspace does

package/dist/channels/control.d.ts

@@ -22,7 +22,7 @@ export interface ControlRoutesOptions {
     agent?: Agent;
 }
 /**
- * Mount the control plane: `GET /control/capabilities|state|entries|events` + `POST
+ * Mount the control plane: `GET /control/capabilities|commands|state|entries|events` + `POST
  * /control/dispatch`, all bearer-authenticated. `events` streams SSE (`data: <WireEvent>` lines).
  */
 export declare function controlRoutes(control: SessionControl, options: ControlRoutesOptions): Routes;

package/dist/channels/control.js

@@ -25,6 +25,7 @@ function parseWireCommand(raw) {
         compact: true,
         set_model: true,
         set_thinking: true,
+        navigate: true,
     };
     void _commandDriftGuard;
     if (typeof raw !== "object" || raw === null)
@@ -76,12 +77,14 @@ function parseWireCommand(raw) {
             return typeof c.model === "string" ? { type: "set_model", model: c.model } : undefined;
         case "set_thinking":
             return typeof c.level === "string" ? { type: "set_thinking", level: c.level } : undefined;
+        case "navigate":
+            return typeof c.targetId === "string" ? { type: "navigate", targetId: c.targetId } : undefined;
         default:
             return undefined;
     }
 }
 /**
- * Mount the control plane: `GET /control/capabilities|state|entries|events` + `POST
+ * Mount the control plane: `GET /control/capabilities|commands|state|entries|events` + `POST
  * /control/dispatch`, all bearer-authenticated. `events` streams SSE (`data: <WireEvent>` lines).
  */
 export function controlRoutes(control, options) {
@@ -108,6 +111,7 @@ export function controlRoutes(control, options) {
     return {
         ...(invokeHandler ? { "POST /control/invoke": guard((req) => invokeHandler(req)) } : {}),
         "GET /control/capabilities": guard(() => json(control.capabilities())),
+        "GET /control/commands": guard(async () => json(await control.commands())),
         "GET /control/state": guard(async (_req, url) => {
             const session = sessionParam(url);
             if (!session)

package/dist/cli/commands/attach.d.ts

@@ -1,4 +1,4 @@
-import type { SessionControl } from "../../session.ts";
+import type { SessionControl, SessionEntry } from "../../session.ts";
 export interface AttachOptions {
     /** Override the control endpoint (skip control.json discovery) — for a remote serve. */
     url?: string;
@@ -62,6 +62,34 @@ export interface AttachIo {
     write: (chunk: string) => void;
     warn: (line: string) => void;
 }
+/**
+ * The backfill slice REDUCED TO THE ACTIVE PATH — a session is a tree (a `navigate`, or a
+ * compaction, leaves sibling branches behind), and printing the slice raw renders the abandoned
+ * branch interleaved with the live one as if it were one conversation. Reachability is computed
+ * backwards from the leaf; an entry whose parent lies BEFORE the slice is path-connected by
+ * construction (its ancestors were rendered in an earlier round), so only what the walk cannot
+ * reach is dropped. An engine that reports NO leaf says nothing about branches, so its slice stands
+ * whole — the one case where "unknown" must not read as "off-path".
+ */
+export declare function activePathSlice(entries: SessionEntry[], leafEntryId: string | undefined): SessionEntry[];
+/**
+ * Answer a RESERVED-SLASH line (anything starting with `/` that is not `/abort`). Two intents share
+ * the prefix — a mistyped control command and an attempt to invoke a name — and they are answered
+ * differently:
+ *
+ * - a mistyped slash gets the certain half NOW (a leading `/` is reserved here, whatever the token
+ *   turns out to be), because waiting on a remote read that can be slow or fail would leave the
+ *   input unanswered; it deliberately does not pre-judge the token as unknown — the read may be
+ *   about to prove it names a real skill;
+ * - `/commands` prints nothing first: its whole answer IS the read, and a placeholder is noise;
+ * - the enumeration answers `/commands` ONLY — dumping every skill at a mistyped `/aboort` answers
+ *   an intent the typo did not express.
+ *
+ * Names print BARE: this composer cannot expand `/name` (the data plane takes prompts as text), so
+ * printing them with a slash would invite the user straight back into this branch. Returns the
+ * promise for the remote half, so a caller (or a test) can await the second line.
+ */
+export declare function answerSlashInput(trimmed: string, control: Pick<SessionControl, "commands">, println: (line: string) => void): Promise<void>;
 /**
  * ONE attach round: subscribe → backfill (render the durable record since `cursor`) → drain live
  * until the stream drops. Returns the advanced cursor. Subscribing first + the server's eager

package/dist/cli/commands/attach.js

@@ -185,7 +185,7 @@ export async function runAttach(sessionArg, dirArg, opts) {
         // invoke) — give the human a corrective signal.
         log.warn(`[fastagent] no durable record for "${sessionArg}" yet — a new session, or a typo?`);
     }
-    log.info(`[fastagent] type to steer the active run; /abort to stop it; Ctrl+C to detach`);
+    log.info(`[fastagent] type to steer the active run; /abort to stop it; /commands to list what this agent defines; Ctrl+C to detach`);
     // stdin → the two planes: a line steers the ACTIVE run; with no run to join (no_active_run) it
     // falls back to STARTING one over the remote data plane (`POST /control/invoke`) — try-steer-
     // then-prompt avoids a state() pre-check race. Acceptance is not outcome: rejections print and
@@ -222,7 +222,7 @@ export async function runAttach(sessionArg, dirArg, opts) {
         // `/` is a reserved command prefix: a typo'd /aboort silently steering the model (injecting a
         // prompt when the user meant to STOP the run) is the dangerous direction of the ambiguity.
         if (trimmed.startsWith("/") && trimmed !== "/abort") {
-            console.log(`[unknown command ${trimmed} — /abort stops the run; a leading / is reserved]`);
+            void answerSlashInput(trimmed, control, (l) => console.log(l));
             return;
         }
         const command = trimmed === "/abort" ? { type: "abort" } : { type: "steer", prompt: { text: trimmed } };
@@ -423,6 +423,76 @@ const isAuthError = (error) => error instanceof ControlRequestError && error.sta
 /** `failStartup` borrowed for its print-one-line-and-exit behavior — attach can fail long after
  *  startup (a serve restart hours in), so the local name must not imply "startup only". */
 const exitWith = failStartup;
+/**
+ * The backfill slice REDUCED TO THE ACTIVE PATH — a session is a tree (a `navigate`, or a
+ * compaction, leaves sibling branches behind), and printing the slice raw renders the abandoned
+ * branch interleaved with the live one as if it were one conversation. Reachability is computed
+ * backwards from the leaf; an entry whose parent lies BEFORE the slice is path-connected by
+ * construction (its ancestors were rendered in an earlier round), so only what the walk cannot
+ * reach is dropped. An engine that reports NO leaf says nothing about branches, so its slice stands
+ * whole — the one case where "unknown" must not read as "off-path".
+ */
+export function activePathSlice(entries, leafEntryId) {
+    if (leafEntryId === undefined)
+        return entries;
+    const byId = new Map(entries.map((e) => [e.id, e]));
+    // An append always moves the leaf, so a leaf BEHIND the slice means every entry in it was
+    // appended and then abandoned — a navigate backwards with no new turn since. Nothing here is on
+    // the active path.
+    if (!byId.has(leafEntryId))
+        return [];
+    const onPath = new Set();
+    for (let cur = byId.get(leafEntryId); cur; cur = cur.parentId ? byId.get(cur.parentId) : undefined) {
+        if (onPath.has(cur.id))
+            break;
+        onPath.add(cur.id);
+    }
+    return entries.filter((e) => onPath.has(e.id));
+}
+/**
+ * Answer a RESERVED-SLASH line (anything starting with `/` that is not `/abort`). Two intents share
+ * the prefix — a mistyped control command and an attempt to invoke a name — and they are answered
+ * differently:
+ *
+ * - a mistyped slash gets the certain half NOW (a leading `/` is reserved here, whatever the token
+ *   turns out to be), because waiting on a remote read that can be slow or fail would leave the
+ *   input unanswered; it deliberately does not pre-judge the token as unknown — the read may be
+ *   about to prove it names a real skill;
+ * - `/commands` prints nothing first: its whole answer IS the read, and a placeholder is noise;
+ * - the enumeration answers `/commands` ONLY — dumping every skill at a mistyped `/aboort` answers
+ *   an intent the typo did not express.
+ *
+ * Names print BARE: this composer cannot expand `/name` (the data plane takes prompts as text), so
+ * printing them with a slash would invite the user straight back into this branch. Returns the
+ * promise for the remote half, so a caller (or a test) can await the second line.
+ */
+export async function answerSlashInput(trimmed, control, println) {
+    // The first WORD is the token: slash input naturally carries arguments (`/triage my inbox`), and
+    // taking the whole line would answer "names nothing" for a name the user did give.
+    const word = trimmed.slice(1).split(/\s+/)[0] ?? "";
+    const listing = word === "commands";
+    if (!listing)
+        println("[a leading / is reserved — /abort stops the run, /commands lists what this agent defines]");
+    let commands;
+    try {
+        commands = await control.commands();
+    }
+    catch (error) {
+        println(`[command list unavailable: ${error}]`);
+        return;
+    }
+    if (listing) {
+        // `description` is what makes a listing usable — a bare name tells the author nothing they did
+        // not already know from the directory.
+        const listed = commands.map((c) => (c.description ? `${c.name} — ${c.description}` : c.name));
+        println(listed.length ? `[this agent defines: ${listed.join("; ")}]` : "[this agent defines no names]");
+        return;
+    }
+    const hit = commands.find((c) => c.name === word);
+    println(hit
+        ? `[${hit.name} is a ${hit.source}${hit.description ? ` — ${hit.description}` : ""}; name it in a normal message, without the /]`
+        : `[/${word} names nothing this agent defines]`);
+}
 /**
  * ONE attach round: subscribe → backfill (render the durable record since `cursor`) → drain live
  * until the stream drops. Returns the advanced cursor. Subscribing first + the server's eager
@@ -490,9 +560,11 @@ settleMs = 300) {
         // append-position cursor (design §7), and a leaf that sits before later appends (abandoned
         // branches) would make every reconnect permanently replay the same tail.
         next = backfill.entries.at(-1)?.id ?? cursor;
-        if (backfill.entries.length > 0) {
+        // Cursor advancement is APPEND ORDER over the whole slice; RENDERING is the active path only.
+        const replay = activePathSlice(backfill.entries, backfill.leafEntryId);
+        if (replay.length > 0) {
             io.println("[replaying the record since the last sync (may overlap what you saw live)]");
-            for (const entry of backfill.entries) {
+            for (const entry of replay) {
                 let line;
                 try {
                     line = renderEntry(entry);

package/dist/cli/commands/deploy.js

@@ -15,7 +15,7 @@ import { registerFeishuWebhook } from "../../channels/feishu/register-webhook.js
 import { readSlackBotAuthEnv } from "../../channels/slack/bot-auth.js";
 import { registerSlackWebhook } from "../../channels/slack/register-webhook.js";
 import { registerTelegramWebhook } from "../../channels/telegram/register-webhook.js";
-import { FORWARDER_FILE, TEMPLATE_FILE, isGeneratedAgentcoreTemplate, planAgentcoreDeploy, } from "../../deploy/agentcore/plan.js";
+import { FORWARDER_FILE, TEMPLATE_FILE, agentcoreName, isGeneratedAgentcoreTemplate, planAgentcoreDeploy, } from "../../deploy/agentcore/plan.js";
 import { deployAgentcoreRun } from "../../deploy/agentcore/run.js";
 import { isGeneratedDockerfile, isGeneratedDockerignore } from "../../deploy/container.js";
 import { composeHasTunnelService, dockerWebhookPaths, isGeneratedCompose, planDockerDeploy, toDockerProjectName, } from "../../deploy/docker/plan.js";
@@ -37,6 +37,10 @@ import { exists } from "../../paths.js";
 import { announceWebhooks } from "../../tunnel.js";
 import { failStartup, failUsage, placementOrExit } from "../fail.js";
 import { resolveFirstRunModel } from "../shared.js";
+/** A copy/paste-safe POSIX shell argument for the command hints deploy prints. */
+function shellArg(value) {
+    return /^[A-Za-z0-9_./:@%+=,-]+$/.test(value) ? value : `'${value.replaceAll("'", `'"'"'`)}'`;
+}
 export async function runDeploy(host, dirArg, opts) {
     // ONE deploy semantic: bake the WORKSPACE (WYSIWYG). Artifacts land under the agent dir
     // (`fastagent/`) plus the one workspace-root `.dockerignore` the packers require; host CLIs run
@@ -212,10 +216,7 @@ export async function runDeploy(host, dirArg, opts) {
         if (loaded.failures.length > 0) {
             failStartup(new Error(`deploy stopped: cannot load schedules: ${loaded.failures.map((x) => `${x.label}: ${x.message}`).join("; ")}`));
         }
-        const acName = basename(workspace)
-            .toLowerCase()
-            .replace(/[^a-z0-9-]+/g, "-")
-            .replace(/^-+|-+$/g, "") || "agent";
+        const acName = agentcoreName(basename(workspace));
         // Every derived AWS name embeds acName; the tightest ceiling is the Lambda function name
         // (`fastagent-<name>-forwarder` ≤ 64 chars). Gate the base instead of silently truncating —
         // truncation would break the redeploy identity (a renamed stack starts blank state).
@@ -605,6 +606,11 @@ async function runDeployAgentcore(params) {
         console.error(`[fastagent] deployed → ${outcome.runtimeArn}`);
         if (outcome.url)
             console.error(`[fastagent] webhook ingress → ${outcome.url}`);
+        const logsDir = shellArg(workspace);
+        console.error(`[fastagent] runtime logs → fastagent logs agentcore ${logsDir} --follow`);
+        if (params.needsForwarder) {
+            console.error(`[fastagent] forwarder logs → fastagent logs agentcore ${logsDir} --source forwarder --follow`);
+        }
         console.error(`[fastagent] invoke: aws bedrock-agentcore invoke-agent-runtime --agent-runtime-arn ${outcome.runtimeArn} \\\n` +
             `  --runtime-session-id "my-conversation-000000000000000000" \\\n` +
             `  --payload '{"kind":"invoke","session":"cli","text":"hello"}' --cli-binary-format raw-in-base64-out /dev/stdout`);

package/dist/cli/commands/dev.js

@@ -6,7 +6,7 @@
 import { resolve } from "node:path";
 import { runDevSupervisor } from "../../dev-supervisor.js";
 import { loadDotEnv } from "../../env.js";
-import { reportDefinitionWarnings, reportModuleLoadFailures, reportToolCollisions } from "../../engines/pi/report.js";
+import { reportFindingsIfChanged, reportModuleLoadFailures, reportToolCollisions } from "../../engines/pi/report.js";
 import { createPiAgentFromDir } from "../../engines/pi/open.js";
 import { setLogLevel } from "../../log.js";
 import { logAgentLoop } from "../../observe.js";
@@ -91,5 +91,5 @@ function reportAgentsSkillsTools(a) {
     }
     reportToolCollisions(a.toolCollisions);
     reportModuleLoadFailures(a.toolFailures);
-    reportDefinitionWarnings(a.definition.collisions, a.definition.diagnostics);
+    reportFindingsIfChanged(a.definition.dir, a.definition);
 }

package/dist/cli/commands/info.js

@@ -6,7 +6,7 @@ import { defaultSessionsDir, loadConfig, resolveAuthPath, resolveModelSpec, reso
 import { resolveStateRoot, workspaceHint } from "../../paths.js";
 import { resolveAgentTools } from "../../engines/pi/create.js";
 import { loadAgentDefinition } from "../../engines/pi/definition.js";
-import { reportDefinitionWarnings, reportModuleLoadFailures, reportToolCollisions } from "../../engines/pi/report.js";
+import { reportFindingsIfChanged, reportModuleLoadFailures, reportToolCollisions } from "../../engines/pi/report.js";
 import { log } from "../../log.js";
 import { nextRun } from "../../schedule/cron.js";
 import { loadSchedules } from "../../schedule/discover.js";
@@ -111,5 +111,5 @@ export async function runInfo(dirArg, opts) {
     reportModuleLoadFailures(sched.failures);
     if (tools.error)
         log.warn(`[fastagent] ${tools.error}`);
-    reportDefinitionWarnings(definition.collisions, definition.diagnostics);
+    reportFindingsIfChanged(definition.dir, definition);
 }

package/dist/cli/commands/logs.d.ts

@@ -0,0 +1,6 @@
+export interface AgentcoreLogsOptions {
+    source?: string;
+    since?: string;
+    follow?: boolean;
+}
+export declare function runLogs(host: string, dirArg: string, opts: AgentcoreLogsOptions): Promise<void>;

package/dist/cli/commands/logs.js

@@ -0,0 +1,27 @@
+/** `fastagent logs agentcore [dir]`: discover and tail the deployed AgentCore CloudWatch logs. */
+import { basename, resolve } from "node:path";
+import { agentcoreName } from "../../deploy/agentcore/plan.js";
+import { tailAgentcoreLogs } from "../../deploy/agentcore/logs.js";
+import { spawnRunner } from "../../deploy/runner.js";
+import { loadDotEnv } from "../../env.js";
+import { failStartup, failUsage, placementOrExit } from "../fail.js";
+export async function runLogs(host, dirArg, opts) {
+    // The host argument is DISPATCHED here, as in runDeploy — the parser's `choices` happens to have a
+    // single member today, and a future second host must land on its own reader, not silently on this one.
+    if (host !== "agentcore")
+        failUsage(`logs: unsupported host "${host}" — only agentcore has remote logs`);
+    const placement = placementOrExit(resolve(dirArg));
+    loadDotEnv(placement.agentDir); // AWS_PROFILE/region/proxy may be definition-local, as on deploy
+    const source = opts.source ?? "runtime";
+    if (source !== "runtime" && source !== "forwarder") {
+        failUsage(`logs: --source must be "runtime" or "forwarder"`);
+    }
+    const outcome = await tailAgentcoreLogs({
+        name: agentcoreName(basename(placement.workspace)),
+        source: source,
+        since: opts.since,
+        follow: opts.follow === true,
+    }, spawnRunner("aws", placement.workspace), (message) => console.error(`[fastagent] logs: ${message}`));
+    if (!outcome.ok)
+        failStartup(new Error(`logs stopped: ${outcome.gate}`));
+}

package/dist/cli/commands/start.js

@@ -9,7 +9,7 @@ import { loadDotEnv } from "../../env.js";
 import { resolveAuthPath, resolveSessionsDirOverride } from "../../engines/pi/config.js";
 import { resolveSecretsDir, workspaceHint } from "../../paths.js";
 import { isUnderDir } from "../../engines/pi/definition.js";
-import { reportDefinitionWarnings, reportModuleLoadFailures, reportToolCollisions } from "../../engines/pi/report.js";
+import { reportFindingsIfChanged, reportModuleLoadFailures, reportToolCollisions } from "../../engines/pi/report.js";
 import { createPiAgentFromDir } from "../../engines/pi/open.js";
 import { log, setLogLevel } from "../../log.js";
 import { createWakeAlarmSink, reconcileWakeAlarms } from "../../schedule/wake-alarm.js";
@@ -80,7 +80,7 @@ export async function runStart(dirArg, opts) {
         log.info(`[fastagent] note: secrets (.env, rotated auth.json) live under the definition dir; point ` +
             `FASTAGENT_SECRETS_DIR at a persistent volume so a redeploy that replaces the dir does not wipe them.`);
     }
-    reportDefinitionWarnings(definition.collisions, definition.diagnostics);
+    reportFindingsIfChanged(definition.dir, definition);
     // AgentCore Runtime posture (FASTAGENT_AGENTCORE=1, set by the generated deploy artifacts): the
     // adapter (POST /invocations + GET /ping) is the container's only reachable surface, and cron
     // slots arrive from the external clock through it — so no resident cron timers. In particular,

package/dist/cli/program.js

@@ -453,6 +453,31 @@ const schedule = {
         },
     ],
 };
+const logs = {
+    name: "logs",
+    summary: "find and tail a deployed host's application logs",
+    description: "Find the CloudWatch log group for the AgentCore stack derived from dir, then run aws logs tail. " +
+        "The default Runtime source shows the agent process's own stdout/stderr; the forwarder source shows " +
+        "the Lambda ingress transport logs.",
+    args: [{ name: "<host>", description: "deployed host", choices: ["agentcore"] }, DIR_ARG],
+    flags: [
+        { flags: "--source <source>", description: "agentcore log source: runtime (default) or forwarder" },
+        { flags: "--since <duration>", description: "history window accepted by AWS CLI (for example 30m or 2h)" },
+        { flags: "--follow", description: "keep polling for new log events until interrupted" },
+    ],
+    examples: [
+        { cmd: "fastagent logs agentcore --follow", note: "the agent process" },
+        { cmd: "fastagent logs agentcore --source forwarder --follow", note: "Lambda ingress" },
+    ],
+    notes: "Read-only. Run it against the same workspace passed to deploy so it derives the same CloudFormation " +
+        "stack name. It never changes FASTAGENT_LOG_LEVEL: AgentCore keeps start's production default, and " +
+        "setting that environment knob to debug exposes the existing detailed turn trace when needed.",
+    run: async (args, f) => (await import("./commands/logs.js")).runLogs(args[0], args[1], {
+        source: f.source,
+        since: f.since,
+        follow: f.follow === true,
+    }),
+};
 const login = {
     name: "login",
     summary: "authenticate a model provider (subscription/OAuth or API key)",
@@ -486,6 +511,7 @@ export const specs = [
     start,
     add,
     deploy,
+    logs,
     login,
 ];
 /**

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

@@ -0,0 +1,35 @@
+/**
+ * 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.
+ */
+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. */
+    since?: string;
+    follow: boolean;
+}
+export type AgentcoreLogsOutcome = {
+    ok: true;
+    logGroup: string;
+} | {
+    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. Runtime tailing
+ * filters the log STREAM prefix so OTEL/spans in the same group never pollute the application log.
+ */
+export declare function tailAgentcoreLogs(plan: AgentcoreLogsPlan, aws: CliRunner, announce?: (message: string) => void): Promise<AgentcoreLogsOutcome>;

package/dist/deploy/agentcore/logs.js

@@ -0,0 +1,112 @@
+import { parseStackOutputs } from "./run.js";
+/** Runtime id from `arn:...:runtime/<id>` — the id prefixes AgentCore's per-endpoint log group. */
+function runtimeIdFromArn(arn) {
+    const marker = ":runtime/";
+    const at = arn.lastIndexOf(marker);
+    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. Runtime tailing
+ * filters the log STREAM prefix so OTEL/spans in the same group never pollute the application log.
+ */
+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/" };
+    }
+    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`,
+        };
+    }
+    const outputs = parseStackOutputs(outputsResult.stdout);
+    let prefix;
+    let exact;
+    if (plan.source === "runtime") {
+        const runtimeArn = outputs.RuntimeArn;
+        const runtimeId = runtimeArn && runtimeIdFromArn(runtimeArn);
+        if (!runtimeId) {
+            return {
+                ok: false,
+                gate: `stack ${stack} has no valid RuntimeArn output — regenerate/deploy the AgentCore stack`,
+            };
+        }
+        prefix = `/aws/bedrock-agentcore/runtimes/${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`;
+        prefix = exact;
+    }
+    const groupsResult = await aws([
+        "logs",
+        "describe-log-groups",
+        "--log-group-name-prefix",
+        prefix,
+        "--query",
+        "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" };
+    }
+    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";
+        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.
+    if (matches.length > 1) {
+        return {
+            ok: false,
+            gate: `several Runtime log groups match this stack: ${matches.join(", ")} — tail the intended one directly: ` +
+                `aws logs tail <group> --format short --follow`,
+        };
+    }
+    const logGroup = matches[0];
+    announce(`${plan.source} → ${logGroup}`);
+    const tailArgs = ["logs", "tail", logGroup, "--format", "short"];
+    if (plan.since)
+        tailArgs.push("--since", plan.since);
+    if (plan.follow)
+        tailArgs.push("--follow");
+    const tailed = await aws(tailArgs);
+    if (tailed.code !== 0) {
+        return { ok: false, gate: `aws logs tail failed for ${logGroup} — see the AWS error above` };
+    }
+    return { ok: true, logGroup };
+}

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

@@ -37,13 +37,35 @@ export interface AgentcorePlan {
  *  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";
+/**
+ * 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.
+ */
+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 while work is in flight, so
- * this timer only ever starts once the agent has genuinely settled — a long turn is never cut short.
+ * 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;
@@ -70,6 +92,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;
 /** 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),