@fastagent-sh/fastagent 0.16.0 → 0.16.2

package/README.md

@@ -196,7 +196,7 @@ FastAgent is pre-1.0. The stable design center is the Agent Handler contract in
 The neutral contract leaves room for capabilities that are not complete product features yet:
 
 - **Durable execution**: Telegram, Slack, and Feishu/Lark accepted turns replay at least once today; general durability and exactly-once execution remain future backend work.
-- **Sandboxed execution** — `ExecutionEnv` is an assembly seam, but the pi coding tools and project-context loader are still local; a complete sandbox adapter is future work.
+- **Sandboxed execution** — `ExecutionEnv` governs the default coding tools, but ② project context and author-written `tools/` still reach the local process; a complete sandbox adapter is future work.
 - **Observability export** — leveled logs and per-turn traces exist today; an OpenTelemetry exporter does not.
 - **More harness bindings and channels** — pi is the built-in harness; another harness can implement the Agent contract, and community channels can use the channel kit.
 - **More deploy targets** — local Docker, Fly, Railway, and AWS Bedrock AgentCore ship today; the generated container is the portable path for other hosts.

package/dist/bind.d.ts

@@ -0,0 +1,34 @@
+/** A bindable host: an IP literal (v4/v6, brackets optional) or "localhost". No other DNS name — a
+ *  bind address must be an address of THIS machine, and resolving one is not this module's job. */
+export declare function isBindAddress(host: string): boolean;
+/**
+ * The ADDRESS form of an accepted bind value: `localhost` becomes `127.0.0.1`, everything else is
+ * already an address. Applied where a value ENTERS (the flag, `http.host`), so nothing downstream ever
+ * holds a name — not deferring the resolution but removing it, which is the module's whole point.
+ *
+ * Two things go wrong otherwise, and both are silent. `server.listen` hands the name to `dns.lookup`,
+ * which picks ONE of 127.0.0.1/::1 by rules we do not control — so what got bound is unknown here. And
+ * `clientHost` would then write that NAME into control.json and the copyable curl, where a consumer
+ * resolves it again, possibly to the other one.
+ */
+export declare function bindAddress(host: string): string;
+/**
+ * How far a bind address reaches: `wildcard` (unset or all-interfaces) reaches every interface and
+ * answers on loopback too; `loopback` is this machine only; `specific` is one interface, reachable
+ * only as itself. Loopback covers the whole reserved range (127/8, ::1) — a `127.0.0.2` bind is no
+ * more LAN-reachable than `127.0.0.1`.
+ */
+export declare function classifyBind(host: string | undefined): "wildcard" | "loopback" | "specific";
+/**
+ * Does a serve bound to `host` answer a dial of the NAME `localhost`? Only the addresses that name
+ * resolves to (127.0.0.1 / ::1) and a wildcard bind do — `127.0.0.2` is loopback yet unreachable that
+ * way. cloudflared dials by name, so `--tunnel` needs this question, not `classifyBind`'s reach.
+ */
+export declare function answersLocalhost(host: string | undefined): boolean;
+/** How to NAME a bind in a message: the wildcard is every interface, so calling it one address would
+ *  understate it; anything else is dialable as itself. THE renderer — the ready lines, the
+ *  already-in-use refusal and the generic bind failure all read a bind through this one, so a reader
+ *  never sees the same bind described two ways. */
+export declare function bindLabel(host: string | undefined, port: number): string;
+/** The address a local client should dial for a serve bound to `host` (control.json, the ready log). */
+export declare function clientHost(host: string | undefined): string;

package/dist/bind.js

@@ -0,0 +1,74 @@
+/**
+ * The ONE reading of a bind address, shared by everything that parses, binds, warns about, or ships
+ * one (the CLI flag, `http.host` validation, the Node host, the deploy pre-flight). Engine- and
+ * host-neutral on purpose: a bind address is a plain value, and two parsers of it would disagree.
+ */
+import { isIP } from "node:net";
+/** Lowercase, unbracketed, IPv4-mapped IPv6 reduced to its IPv4 form — the form the checks below read.
+ *  Brackets come off only as a PAIR: a half-bracketed `[::1` must stay invalid, not become an address. */
+function normalize(host) {
+    return host
+        .toLowerCase()
+        .replace(/^\[(.+)]$/, "$1")
+        .replace(/^::ffff:/, "");
+}
+/** A bindable host: an IP literal (v4/v6, brackets optional) or "localhost". No other DNS name — a
+ *  bind address must be an address of THIS machine, and resolving one is not this module's job. */
+export function isBindAddress(host) {
+    const h = normalize(host);
+    return h === "localhost" || isIP(h) !== 0;
+}
+/**
+ * The ADDRESS form of an accepted bind value: `localhost` becomes `127.0.0.1`, everything else is
+ * already an address. Applied where a value ENTERS (the flag, `http.host`), so nothing downstream ever
+ * holds a name — not deferring the resolution but removing it, which is the module's whole point.
+ *
+ * Two things go wrong otherwise, and both are silent. `server.listen` hands the name to `dns.lookup`,
+ * which picks ONE of 127.0.0.1/::1 by rules we do not control — so what got bound is unknown here. And
+ * `clientHost` would then write that NAME into control.json and the copyable curl, where a consumer
+ * resolves it again, possibly to the other one.
+ */
+export function bindAddress(host) {
+    return normalize(host) === "localhost" ? "127.0.0.1" : host;
+}
+/**
+ * How far a bind address reaches: `wildcard` (unset or all-interfaces) reaches every interface and
+ * answers on loopback too; `loopback` is this machine only; `specific` is one interface, reachable
+ * only as itself. Loopback covers the whole reserved range (127/8, ::1) — a `127.0.0.2` bind is no
+ * more LAN-reachable than `127.0.0.1`.
+ */
+export function classifyBind(host) {
+    if (host === undefined)
+        return "wildcard";
+    const h = normalize(host);
+    if (h === "0.0.0.0" || h === "::" || h === "::0")
+        return "wildcard";
+    if (h === "localhost" || h === "::1" || /^127\.\d+\.\d+\.\d+$/.test(h))
+        return "loopback";
+    return "specific";
+}
+/**
+ * Does a serve bound to `host` answer a dial of the NAME `localhost`? Only the addresses that name
+ * resolves to (127.0.0.1 / ::1) and a wildcard bind do — `127.0.0.2` is loopback yet unreachable that
+ * way. cloudflared dials by name, so `--tunnel` needs this question, not `classifyBind`'s reach.
+ */
+export function answersLocalhost(host) {
+    if (classifyBind(host) === "wildcard")
+        return true;
+    const h = normalize(host);
+    return h === "localhost" || h === "127.0.0.1" || h === "::1";
+}
+/** How to NAME a bind in a message: the wildcard is every interface, so calling it one address would
+ *  understate it; anything else is dialable as itself. THE renderer — the ready lines, the
+ *  already-in-use refusal and the generic bind failure all read a bind through this one, so a reader
+ *  never sees the same bind described two ways. */
+export function bindLabel(host, port) {
+    return classifyBind(host) === "wildcard" ? `port ${port}` : `${clientHost(host)}:${port}`;
+}
+/** The address a local client should dial for a serve bound to `host` (control.json, the ready log). */
+export function clientHost(host) {
+    if (classifyBind(host) === "wildcard")
+        return "127.0.0.1";
+    // biome-ignore lint/style/noNonNullAssertion: only a wildcard bind leaves host undefined
+    return host.includes(":") && !host.startsWith("[") ? `[${host}]` : host;
+}

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). */
@@ -126,17 +133,25 @@ export function createStateSync(options) {
     let looping = false;
     const runRestore = async (urls) => {
         const res = await doFetch(urls.getUrl, { method: "GET" });
-        // ONLY a proven 404 is "first deploy". The signer holds s3:GetObject on exactly this key, so a
-        // missing object answers NoSuchKey/404; a 403 means an expired or malformed signature, or a
-        // revoked permission — i.e. the snapshot may well exist. Reading 403 as "absent" would serve an
-        // empty agent and then overwrite the real snapshot with that emptiness.
+        // ONLY a proven 404 is "first deploy". A missing key answers 404 only because the generated
+        // template grants the signer s3:ListBucket on the snapshot prefix — without it S3 folds "absent"
+        // into 403 (anti-enumeration). A 403 therefore means an expired or malformed signature, a
+        // revoked permission, or a template from before that grant — i.e. the snapshot may well exist.
+        // Reading 403 as "absent" would serve an empty agent and then overwrite the real snapshot with
+        // that emptiness.
         if (res.status === 404) {
             log.info("[agentcore] no state snapshot yet — starting from an empty state root (first deploy)");
             restored = true;
             return;
         }
-        if (!res.ok)
-            throw new Error(`state snapshot GET failed: ${res.status}`);
+        if (!res.ok) {
+            const hint = res.status === 403
+                ? " (an expired presigned URL, a revoked permission, or a template generated before the " +
+                    "ForwarderRole granted s3:ListBucket — S3 answers 403 even for a MISSING first-deploy " +
+                    "snapshot without it; regenerate with `fastagent deploy agentcore --force` and redeploy)"
+                : "";
+            throw new Error(`state snapshot GET failed: ${res.status}${hint}`);
+        }
         const written = await unpackIntoStateRoot(stateRoot, Buffer.from(await res.arrayBuffer()));
         log.info(`[agentcore] restored ${written} state file(s) from the snapshot`);
         restored = true;

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.d.ts

@@ -13,3 +13,16 @@ export interface DeployOptions {
     input?: boolean;
 }
 export declare function runDeploy(host: DeployHost, dirArg: string, opts: DeployOptions): Promise<void>;
+/**
+ * Write the plan's artifacts under `target`, honouring the ownership rule: a file we did not generate is
+ * never touched, ours is kept unless `--force`. Exported for its own test — this is a four-branch state
+ * machine over (exists, ours, force) that used to be proven by spawning the CLI eight times, which is
+ * command LOGIC re-run through a subprocess (see vitest.config.ts) and the suite's slowest test.
+ */
+export declare function writeArtifacts(target: string, artifacts: {
+    path: string;
+    content: string;
+}[], options: {
+    force: boolean;
+    alwaysWrite?: string[];
+}): Promise<void>;

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).
@@ -413,7 +414,13 @@ function isOurArtifact(path, content) {
         return isGeneratedAgentcoreTemplate(content);
     return false;
 }
-async function writeArtifacts(target, artifacts, options) {
+/**
+ * Write the plan's artifacts under `target`, honouring the ownership rule: a file we did not generate is
+ * never touched, ours is kept unless `--force`. Exported for its own test — this is a four-branch state
+ * machine over (exists, ours, force) that used to be proven by spawning the CLI eight times, which is
+ * command LOGIC re-run through a subprocess (see vitest.config.ts) and the suite's slowest test.
+ */
+export async function writeArtifacts(target, artifacts, options) {
     for (const a of artifacts) {
         const abs = join(target, a.path);
         // Pure build output, not operator-owned configuration. It must track the generated template/runbook.
@@ -599,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.d.ts

@@ -1,5 +1,6 @@
 export interface DevOptions {
     port?: string;
+    bind?: string;
     model?: string;
     authPath?: string;
     /** false ⇔ `--no-watch`. */

package/dist/cli/commands/dev.js

@@ -12,9 +12,10 @@ import { setLogLevel } from "../../log.js";
 import { logAgentLoop } from "../../observe.js";
 import { installProxyFetch } from "../../proxy.js";
 import { workspaceHint } from "../../paths.js";
+import { bindAddress } from "../../bind.js";
 import { failStartup, placementOrExit } from "../fail.js";
-import { maybeTunnel, mountSessionControl, routesFor, serve, startSchedules } from "../serve.js";
-import { parsePort, reportAuth, reportLine, resolveFirstRunModel, reportWorkspaceHint } from "../shared.js";
+import { assertTunnelBindable, maybeTunnel, mountSessionControl, routesFor, serve, startSchedules } from "../serve.js";
+import { parseBind, parsePort, reportAuth, reportLine, resolveFirstRunModel, reportWorkspaceHint } from "../shared.js";
 export async function runDev(dirArg, opts) {
     const dir = resolve(dirArg);
     const placement = placementOrExit(dir);
@@ -33,12 +34,16 @@ export async function runDev(dirArg, opts) {
         await serveOnce(dir, opts);
         return;
     }
-    parsePort(opts.port, "--port", "flag"); // flag-shape check before spawning
+    parsePort(opts.port, "--port", "flag"); // flag-shape checks before spawning
+    // The --bind/--tunnel conflict is decidable from flags alone: refuse it HERE, before a worker and a
+    // tunnel exist. The worker repeats the check because `http.host` can supply the address instead.
+    assertTunnelBindable(parseBind(opts.bind), opts.tunnel ?? false, "flag");
     await runDevSupervisor(placement, { tunnel: opts.tunnel ?? false });
 }
 /** Assemble the agent and serve it once (the dev worker; also the --no-watch path). */
 async function serveOnce(dir, opts) {
     const portFlag = parsePort(opts.port, "--port", "flag");
+    const bindFlag = parseBind(opts.bind);
     loadDotEnv(placementOrExit(dir).agentDir);
     installProxyFetch();
     const a = await createPiAgentFromDir(dir, {
@@ -57,12 +62,18 @@ async function serveOnce(dir, opts) {
     // out in start (level info), keeping end-user content out of production logs. Wired in both postures.
     const traced = logAgentLoop(a.agent);
     const routed = await routesFor(a.agentDir, traced, a.stateRoot, a.sessionControl).catch(failStartup);
+    // `http.host` enters here the way the flag enters `parseBind` — through `bindAddress`, so a
+    // configured `localhost` is an ADDRESS by the time anything binds, renders or dials it.
+    const configured = a.config.http?.host;
+    const host = bindFlag ?? (configured === undefined ? undefined : bindAddress(configured));
+    assertTunnelBindable(host, opts.tunnel ?? false, bindFlag ? "flag" : "config");
     const withControl = mountSessionControl(routed.routes, a.sessionControl, a.stateRoot, {
         tunnel: opts.tunnel ?? false,
         agent: traced, // the remote data plane (POST /control/invoke) drives the SAME traced agent
+        host,
     });
     await startSchedules(a.agentDir, traced, a.stateRoot, a.config.selfSchedule ?? false);
-    serve({ ...routed, routes: withControl.routes }, portFlag ?? a.config.http?.port ?? 8787, (p) => {
+    serve({ ...routed, routes: withControl.routes }, { port: portFlag ?? a.config.http?.port ?? 8787, host }, (p) => {
         withControl.announce(p);
         maybeTunnel(a.agentDir, routed.routeChannels, p, opts.tunnel ?? false, a.stateRoot);
     });

package/dist/cli/commands/info.js

@@ -24,7 +24,7 @@ export async function runInfo(dirArg, opts) {
     // tool), is isolated the same way everywhere (G2): info, dev, AND start report it and keep going with
     // the tools that loaded. The `error`/`.catch` below only fires for a whole-load fault (an unreadable
     // tools/ dir), not a single bad file.
-    const tools = await resolveAgentTools(config, agentDir, workspace)
+    const tools = await resolveAgentTools(config, agentDir)
         .then((r) => ({
         names: r.toolNames,
         deferred: r.deferredToolNames,

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.d.ts

@@ -1,5 +1,6 @@
 export interface StartOptions {
     port?: string;
+    bind?: string;
     model?: string;
     sessionsDir?: string;
     authPath?: string;

package/dist/cli/commands/start.js

@@ -17,14 +17,16 @@ import { setWakeupsSink } from "../../schedule/wakeups.js";
 import { logAgentLoop } from "../../observe.js";
 import { installProxyFetch } from "../../proxy.js";
 import { exists } from "../../paths.js";
+import { bindAddress } from "../../bind.js";
 import { failStartup, placementOrExit } from "../fail.js";
-import { maybeTunnel, mountAgentcore, mountSessionControl, routesFor, serve, startSchedules } from "../serve.js";
-import { parsePort, reportAuth, reportLine, resolveFirstRunModel, reportWorkspaceHint } from "../shared.js";
+import { assertTunnelBindable, maybeTunnel, mountAgentcore, mountSessionControl, routesFor, serve, startSchedules, } from "../serve.js";
+import { parseBind, parsePort, reportAuth, reportLine, resolveFirstRunModel, reportWorkspaceHint } from "../shared.js";
 export async function runStart(dirArg, opts) {
     const dir = resolve(dirArg);
     // Flag validation first: a bad --port is a USAGE error (exit 2), and reporting it must not depend on
     // the directory being an agent (which is a runtime/environment failure, exit 1).
     const portFlag = parsePort(opts.port, "--port", "flag");
+    const bindFlag = parseBind(opts.bind);
     const placement = placementOrExit(dir);
     setLogLevel("info"); // production posture: info+, the debug turn trace (and its end-user content) gated out
     loadDotEnv(placement.agentDir);
@@ -88,9 +90,15 @@ export async function runStart(dirArg, opts) {
     // Same debug turn trace as dev; gated out here by the info level (see dev.ts serveOnce).
     const traced = logAgentLoop(agent);
     const routed = await routesFor(agentDir, traced, stateRoot, sessionControl, { builtinInvoke: !agentcore }).catch(failStartup);
+    // `http.host` enters here the way the flag enters `parseBind` — through `bindAddress`, so a
+    // configured `localhost` is an ADDRESS by the time anything binds, renders or dials it.
+    const configured = config.http?.host;
+    const host = bindFlag ?? (configured === undefined ? undefined : bindAddress(configured));
+    assertTunnelBindable(host, opts.tunnel ?? false, bindFlag ? "flag" : "config");
     const withControl = mountSessionControl(routed.routes, sessionControl, stateRoot, {
         tunnel: opts.tunnel ?? false,
         agent: traced,
+        host,
     });
     // AgentCore + selfSchedule: register the wake-ALARM sink BEFORE the scheduler starts — the boot
     // wake pump may advance a recurring entry (a store save) and that save must already re-arm its
@@ -126,7 +134,7 @@ export async function runStart(dirArg, opts) {
         }
         log.info(`[fastagent] agentcore: serving POST /invocations + GET /ping (FASTAGENT_AGENTCORE=1)`);
     }
-    serve({ ...routed, routes }, portFlag ?? parsePort(process.env.PORT, "PORT env", "env") ?? config.http?.port ?? 8787, (p) => {
+    serve({ ...routed, routes }, { port: portFlag ?? parsePort(process.env.PORT, "PORT env", "env") ?? config.http?.port ?? 8787, host }, (p) => {
         withControl.announce(p);
         maybeTunnel(agentDir, routed.routeChannels, p, opts.tunnel ?? false, stateRoot);
     });

package/dist/cli/commands/tool.js

@@ -1,5 +1,6 @@
 /** `fastagent tool <name> '<json>' [dir]`: run one tool's body directly with JSON args — no model. */
 import { resolve } from "node:path";
+import { NodeExecutionEnv } from "@earendil-works/pi-agent-core/node";
 import { loadDotEnv } from "../../env.js";
 import { loadConfig } from "../../engines/pi/config.js";
 import { resolveAgentTools } from "../../engines/pi/create.js";
@@ -16,7 +17,7 @@ export async function runTool(name, argsJson, dirArg) {
     // The same tool set dev/start mount (defaults + config.tools + discovered, deduped), so the runner
     // exercises exactly what gets served — a shadowed tool is surfaced, not silently run. Resolve the
     // placement like the openers, so `fastagent tool` finds the SAME tools/ as dev/start.
-    const { tools, toolCollisions, toolFailures } = await resolveAgentTools(config, agentDir, workspace).catch(failStartup);
+    const { tools, toolCollisions, toolFailures } = await resolveAgentTools(config, agentDir).catch(failStartup);
     for (const c of toolCollisions) {
         console.error(`[fastagent] warn: tool "${c.name}" (${c.source}) is shadowed by a default/config tool — not mounted`);
     }
@@ -25,7 +26,14 @@ export async function runTool(name, argsJson, dirArg) {
     if (!tool) {
         failStartup(new Error(`unknown tool "${name}". available: ${tools.map((t) => t.name).join(", ") || "(none)"}`));
     }
-    const result = await turnContext.run({ cwd: workspace }, () => tool.execute(`cli-${name}`, args)).catch(failStartup);
+    // Two contexts, because the two tool families read different ones and this command must serve both
+    // exactly as serving does: fastagent's own tools take cwd/session/activation from `turnContext`
+    // (AsyncLocalStorage), and pi's default coding tools take the ExecutionEnv from the harness's TOOL
+    // context — which no harness supplies here, so this stands in for it, rooted at the same workspace.
+    const env = new NodeExecutionEnv({ cwd: workspace });
+    const result = await turnContext
+        .run({ cwd: workspace }, () => tool.execute(`cli-${name}`, args, undefined, undefined, { env }))
+        .catch(failStartup);
     const out = result?.details !== undefined
         ? result.details
         : (result?.content ?? []).map((c) => ("text" in c ? c.text : "")).join("");

package/dist/cli/program.js

@@ -27,6 +27,10 @@ const NO_INPUT = {
     description: "never prompt (CI/scripts) — missing information becomes an error instead of a question",
 };
 const PORT = { flags: "--port <n>", description: "HTTP port" };
+const BIND = {
+    flags: "--bind <addr>",
+    description: "bind address (default: all interfaces; 127.0.0.1 keeps it off the LAN)",
+};
 const TUNNEL = {
     flags: "--tunnel",
     description: "expose a public HTTPS URL via a Cloudflare quick tunnel (needs cloudflared) and auto-register " +
@@ -85,6 +89,7 @@ const dev = {
     args: [DIR_ARG],
     flags: [
         PORT,
+        BIND,
         MODEL,
         AUTH_PATH,
         { flags: "--no-watch", description: "serve once, no file-watching" },
@@ -97,6 +102,7 @@ const dev = {
     ],
     run: async (args, f) => (await import("./commands/dev.js")).runDev(args[0], {
         port: f.port,
+        bind: f.bind,
         model: f.model,
         authPath: f.authPath,
         watch: f.watch !== false,
@@ -218,6 +224,7 @@ const start = {
     args: [DIR_ARG],
     flags: [
         PORT,
+        BIND,
         MODEL,
         { flags: "--sessions-dir <dir>", description: "sessions directory override" },
         AUTH_PATH,
@@ -230,6 +237,7 @@ const start = {
     ],
     notes: "Precedence chains:\n" +
         "  port:     --port > PORT env > fastagent.config.ts http.port > 8787\n" +
+        "  bind:     --bind > fastagent.config.ts http.host > all interfaces\n" +
         "  state:    FASTAGENT_STATE_DIR > <agent dir>/.state — mutable machine state\n" +
         "            (sessions, channel state, schedule state); point it at a mounted\n" +
         "            volume so a redeploy that replaces the directory never wipes it\n" +
@@ -240,6 +248,7 @@ const start = {
         "            share one credential across projects)",
     run: async (args, f) => (await import("./commands/start.js")).runStart(args[0], {
         port: f.port,
+        bind: f.bind,
         model: f.model,
         sessionsDir: f.sessionsDir,
         authPath: f.authPath,
@@ -444,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)",
@@ -477,6 +511,7 @@ export const specs = [
     start,
     add,
     deploy,
+    logs,
     login,
 ];
 /**