@fastagent-sh/fastagent 0.16.1 → 0.16.2

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/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,6 +77,8 @@ 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;
     }

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,16 @@ 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[];
 /**
  * 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

@@ -423,6 +423,32 @@ 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));
+}
 /**
  * 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 +516,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/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/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 selects only [runtime-logs], so application stdout/stderr is not mixed " +
+        "with OTEL/spans in the same AWS log group; the forwarder source shows 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,30 @@
+/**
+ * AgentCore log discovery + tailing. AWS puts the container's stdout/stderr and its OTEL telemetry
+ * in the same 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 ONLY `[runtime-logs]` for the runtime source — the same application lines shown locally,
+ * without mixing in spans/otel-rt-logs.
+ */
+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,115 @@
+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 with the ` +
+                `same stream filter this command applies: aws logs tail <group> --log-stream-name-prefix '[runtime-logs]' ` +
+                `(quote the prefix — [...] is a shell glob)`,
+        };
+    }
+    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.source === "runtime")
+        tailArgs.push("--log-stream-name-prefix", "[runtime-logs]");
+    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,6 +37,27 @@ 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
@@ -70,6 +91,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),

package/dist/deploy/agentcore/plan.js

@@ -29,12 +29,34 @@
  */
 import { createHash } from "node:crypto";
 import { MAX_WEBHOOK_BODY_BYTES } from "../../channels/agentcore-limits.js";
+import { SECRETS_DIRNAME } from "../../paths.js";
 import { containerArtifacts } from "../container.js";
 import { deploymentSecrets, isEnvKey } from "../secrets.js";
 /** 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 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 const SECRETS_DIR = `${MOUNT}/${SECRETS_DIRNAME}`;
 /**
  * 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
@@ -72,6 +94,13 @@ export const GENERATED_TEMPLATE_MARKER = "# Generated by `fastagent deploy agent
 export function isGeneratedAgentcoreTemplate(content) {
     return content.startsWith(GENERATED_TEMPLATE_MARKER);
 }
+/** Deployment base name from the workspace basename — the ONE mapping used to find its stack later. */
+export function agentcoreName(workspaceBasename) {
+    return (workspaceBasename
+        .toLowerCase()
+        .replace(/[^a-z0-9-]+/g, "-")
+        .replace(/^-+|-+$/g, "") || "agent");
+}
 /** Runtime name (`[a-zA-Z][a-zA-Z0-9_]{0,47}`) from a dir basename. */
 export function toRuntimeName(basename) {
     const slug = basename.replace(/[^a-zA-Z0-9]+/g, "_").replace(/^_+|_+$/g, "");
@@ -437,6 +466,10 @@ function template(input, translated) {
         `        PORT: "8080"`, // the Runtime service contract's fixed port (config.http.port does not apply here)
         `        FASTAGENT_AGENTCORE: "1"`, // serve mounts /invocations + /ping, arms no resident cron
         `        FASTAGENT_STATE_DIR: ${MOUNT}`,
+        // Inside the state root on purpose — the snapshot is this host's only durable store, and it copies
+        // exactly one tree. See {@link SECRETS_DIR}: the sibling layout every other host uses would leave a
+        // rotated OAuth credential outside it, i.e. discarded with the microVM.
+        `        FASTAGENT_SECRETS_DIR: ${SECRETS_DIR}`,
     ];
     // The auth seed is chunked (env values max 2048 chars — see AUTH_SEED_CHUNK_SIZE): N parameters,
     // each riding its own env var; `start` reassembles them (collectAuthSeed). Empty defaults = unused.
@@ -679,7 +712,12 @@ export function planAgentcoreDeploy(input) {
         ? `# 4. Read the outputs (the runtime ARN + callback URL; it serves webhooks only when configured):`
         : `# 4. Read the outputs (the runtime ARN — this topology has NO public URL: nothing outside AWS`, ...(needsFunctionUrl
         ? []
-        : [`#    sends to it, so no Function URL is created and the agent is reachable only via SigV4).`]), `aws cloudformation describe-stacks --stack-name ${stack} --query "Stacks[0].Outputs"`);
+        : [`#    sends to it, so no Function URL is created and the agent is reachable only via SigV4).`]), `aws cloudformation describe-stacks --stack-name ${stack} --query "Stacks[0].Outputs"`, ``, `# 5. Tail the Runtime's application stdout/stderr (same fastagent messages + log level as locally).`, `#    Discovery filters to [runtime-logs], excluding OTEL/spans AWS stores in the same log group:`, `fastagent logs agentcore --follow`, ...(needsForwarder
+        ? [
+            `# The ingress transport is a separate Lambda and therefore a separate log source:`,
+            `fastagent logs agentcore --source forwarder --follow`,
+        ]
+        : []));
     // Model-auth guidance mirrors the other hosts: an env key became a parameter above; OAuth/stored
     // can't be read at plan time — `--run` carries it as FastagentAuthSeed.
     if (!isEnvKey(input.modelAuth)) {
@@ -716,6 +754,6 @@ export function planAgentcoreDeploy(input) {
     if (needsForwarder) {
         runbook.push(``, `# After a REDEPLOY, stop the ingress session so the new image serves immediately — a live session`, `# keeps its old compute (and the OLD image) until ${IDLE_TIMEOUT_SECONDS}s idle / the 8 h compute ceiling`, `# (\`--run\` does this automatically):`, `aws bedrock-agentcore stop-runtime-session --agent-runtime-arn <RuntimeArn> \\`, `  --runtime-session-id "${ingressSessionId(name)}"`);
     }
-    runbook.push(``, `# Redeploy = step 1b (new forwarder key, if its code changed) + step 2 with a NEW tag + step 3.`, `# STATE: ${MOUNT} is a LOCAL disk — AWS wipes it on every runtime version update (i.e. every`, `# deploy) and after 14 idle days. What survives is the S3 snapshot under s3://${bucketHint}/${STATE_KEY}:`, `# the container restores it on its first invocation and pushes it whenever work settles. Keep that`, `# bucket and the agent keeps its sessions, channel state and pending wake-ups across deploys;`, `# delete it and the agent starts blank. (A persistent MOUNT would need EFS + VPC mode + a NAT`, `# gateway for model/channel egress — see the template comment.)`);
+    runbook.push(``, `# Redeploy = step 1b (new forwarder key, if its code changed) + step 2 with a NEW tag + step 3.`, `# STATE: ${MOUNT} is a LOCAL disk — AWS wipes it on every runtime version update (i.e. every`, `# deploy) and after 14 idle days. What survives is the S3 snapshot under s3://${bucketHint}/${STATE_KEY}:`, `# the container restores it on its first invocation and pushes it whenever work settles. Keep that`, `# bucket and the agent keeps its sessions, channel state and pending wake-ups across deploys;`, `# delete it and the agent starts blank. (A persistent MOUNT would need EFS + VPC mode + a NAT`, `# gateway for model/channel egress — see the template comment.)`, `# CREDENTIALS RIDE THAT SNAPSHOT TOO: FASTAGENT_SECRETS_DIR is ${SECRETS_DIR}, inside the state`, `# root, so an OAuth auth.json ROTATED on the box persists (a refresh token is single-use — without`, `# this the next microVM would re-seed the deploy-time copy and eventually fail to authenticate).`, `# The bucket is therefore credential storage: it is created with public access blocked and`, `# versioning on, and deleting it costs model access until the next deploy re-seeds.`);
     return { artifacts, runbook, untranslatableSchedules: untranslatable };
 }

package/dist/deploy/container.js

@@ -128,8 +128,10 @@ CMD ["./${into("node_modules/.bin/fastagent")}", "start", "/app"]
 /** Patterns are RECURSIVE (`**​/`) on purpose — dockerignore patterns are root-anchored (unlike
  *  .gitignore), and a baked workspace can hold nested projects: a bare `node_modules` would upload
  *  their build-machine deps (macOS binaries!) and a bare `.env` would bake their secrets into the
- *  image. `.secrets`/`.state` are fastagent machinery — secrets travel through the host's secret
- *  store, state lives on the volume; neither may ever enter an image. `.cache` is generic hygiene
+ *  image. `.secrets`/`.state` are fastagent machinery — credential contents travel through the host's
+ *  secret store and state lives on the volume, so neither may enter an image. The two tracked secrets
+ *  scaffolds (`.env.example` + `.gitignore`) are the narrow exception: they carry no values and must stay
+ *  beside the shipped `.git`, or the image starts with tracked deletions. `.cache` is generic hygiene
  *  (a baked project's own build cache), not a fastagent directory.
  *  `.git` is deliberately SHIPPED: the deployed agent's write-back (pull/commit/push) needs the
  *  repo's history+remote — the WYSIWYG bake's freshness/durability loop runs through git, driven by
@@ -145,12 +147,13 @@ const dockerignore = (input) => DOCKERIGNORE_BASE +
         .join("");
 const DOCKERIGNORE_BASE = `${GENERATED_DOCKERIGNORE_MARKER}. Delete this line to take ownership (deploy then keeps your file).
 **/node_modules
-**/${SECRETS_DIRNAME}
+**/${SECRETS_DIRNAME}/**
 **/${STATE_DIRNAME}
 **/.cache
 **/.env
 **/.env.*
 !**/.env.example
+!**/${SECRETS_DIRNAME}/.gitignore
 **/*.log
 # .git is deliberately shipped: the agent can pull to freshen content and push its work back
 # (the generated image installs the git binary when this directory ships a .git; otherwise

package/dist/engines/pi/config.d.ts

@@ -1,7 +1,7 @@
 import type { ThinkingLevel } from "@earendil-works/pi-agent-core";
 import type { FastagentTool } from "./tool.ts";
 import type { Models } from "@earendil-works/pi-ai";
-import { type AnyModel } from "./harness.ts";
+import type { AnyModel } from "./harness.ts";
 export interface FastagentConfig {
     /** "provider/modelId". Precedence: CLI --model > FASTAGENT_MODEL > config. */
     model?: string;

package/dist/engines/pi/config.js

@@ -20,7 +20,7 @@ var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExte
 import { existsSync, statSync } from "node:fs";
 import { basename, join } from "node:path";
 import { pathToFileURL } from "node:url";
-import { THINKING_LEVELS } from "./harness.js";
+import { THINKING_LEVELS } from "./session-settings.js";
 import { isBindAddress } from "../../bind.js";
 import { moduleLoadHint } from "../../loader.js";
 import { AGENT_CONFIG_NAMES, resolveOverridePath, resolveSecretsDir } from "../../paths.js";

package/dist/engines/pi/create.d.ts

@@ -3,7 +3,7 @@ import type { Models, Provider } from "@earendil-works/pi-ai";
 import type { Agent } from "../../agent.ts";
 import { type FastagentConfig } from "./config.ts";
 import { type LoadedDefinition } from "./definition.ts";
-import { piHarnessFactory } from "./harness.ts";
+import { type AnyModel, piHarnessFactory } from "./harness.ts";
 import { type PiSessionStore } from "./sessions.ts";
 import type { ModuleLoadFailure } from "../../loader.ts";
 import { type ToolCollision, type MountedTool } from "./tool.ts";
@@ -64,6 +64,11 @@ type OnAssembly = (parts: {
     models: Models;
     harnessFactory: ReturnType<typeof piHarnessFactory>;
     lease: Lease;
+    /** The resolved configured pair — what a session without overrides runs on. */
+    defaults: {
+        model: AnyModel;
+        thinkingLevel: ThinkingLevel;
+    };
 }) => void;
 /** L1 options. Tier 1: model (spec) + instructions + tools. Tier 2: the injectable ports. */
 export interface CreatePiAgentOptions {

package/dist/engines/pi/create.js

@@ -17,7 +17,7 @@ import { readImageProcessor } from "./read-image.js";
 import { defaultAuthPath, resolveModel } from "./config.js";
 import { resolveSecretsDir } from "../../paths.js";
 import { loadAgentDefinition } from "./definition.js";
-import { piHarnessFactory } from "./harness.js";
+import { DEFAULT_THINKING_LEVEL, piHarnessFactory } from "./harness.js";
 import { createPiModels } from "./models.js";
 import { reportDefinitionWarnings } from "./report.js";
 import { inMemorySessionStore } from "./sessions.js";
@@ -169,18 +169,24 @@ function buildPiAgent(opts) {
     // Materialized here (not defaulted inside createPiAgentFromHarness) so the exposed parts carry
     // the SAME lease instance the agent runs under — boundary mutations must contend on it.
     const lease = opts.lease ?? inProcessLease();
+    // The assembly's configured PAIR — handed to the factory and to the control plane as ONE value, so
+    // there is no wiring in which they could disagree (which levels exist depends on the model).
+    const defaults = {
+        model: resolveModel(models, opts.model),
+        thinkingLevel: opts.thinkingLevel ?? DEFAULT_THINKING_LEVEL,
+    };
     const harnessFactory = piHarnessFactory({
         sessions: opts.sessions ?? inMemorySessionStore(),
         env,
         models,
-        model: resolveModel(models, opts.model),
+        model: defaults.model,
         thinkingLevel: opts.thinkingLevel,
         systemPrompt: opts.systemPrompt,
         tools: opts.tools,
         skills: opts.skills,
         live: opts.live,
     });
-    opts.onAssembly?.({ models, harnessFactory, lease });
+    opts.onAssembly?.({ models, harnessFactory, lease, defaults });
     return createPiAgentFromHarness({ lease, observer: opts.observer, cwd: env.cwd, harnessFactory });
 }
 /**