@fastagent-sh/fastagent 0.16.2 → 0.17.1

package/dist/cli/serve.js

@@ -151,9 +151,9 @@ export function mountSessionControl(routes, control, stateRoot, options = {}) {
  * the platform's contract, so a channel shadowing them would silently unserve the whole deployment.
  */
 export function mountAgentcore(routes, options) {
-    const { agent, stateRoot, schedules, onStateReady } = options;
+    const { agent, stateRoot, schedules, onStateReady, lazyChannels } = options;
     const mounted = agentcoreRoutes({
-        routes,
+        routes: lazyChannels ?? routes,
         agent,
         stateRoot,
         isBusy: () => activeWork() > 0,

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

@@ -1,9 +1,14 @@
 /**
- * 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.
+ * 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";

package/dist/deploy/agentcore/logs.js

@@ -93,9 +93,8 @@ export async function tailAgentcoreLogs(plan, aws, announce = () => { }) {
     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)`,
+            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];
@@ -103,8 +102,6 @@ export async function tailAgentcoreLogs(plan, aws, announce = () => { }) {
     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);

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

@@ -63,8 +63,9 @@ export declare const SECRETS_DIR = "/mnt/state/.secrets";
  * — 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;

package/dist/deploy/agentcore/plan.js

@@ -62,8 +62,9 @@ export const SECRETS_DIR = `${MOUNT}/${SECRETS_DIRNAME}`;
  * — 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 const IDLE_TIMEOUT_SECONDS = 180;
@@ -395,6 +396,23 @@ exports.handler = async (event, ctx) => {
     if (failed > 0) return { statusCode: 500, body: \`\${failed} alarm(s) failed\\n\` };
     return { statusCode: 200, body: "ok\\n" };
   }
+  // The deploy driver's probe (reserved path, ingress secret): wake the runtime through the SAME
+  // trusted envelope pipeline (state URLs included — a direct InvokeAgentRuntime call could not mint
+  // them, and would make the runtime construct against a pre-restore mount) and pass its structured
+  // transport-200 verdict back VERBATIM. The ordinary webhook path below folds a non-200 transport
+  // into an opaque 502, which would strip exactly the diagnostics the probe exists to carry — and it
+  // sits BEFORE the WEBHOOKS_ENABLED gate so schedule-only topologies (whose URLs refuse ordinary
+  // public traffic) are probeable too.
+  if (event.rawPath === "/__fastagent/probe") {
+    const req = JSON.parse(event.isBase64Encoded ? Buffer.from(event.body, "base64").toString() : event.body || "{}");
+    if (!process.env.INGRESS_SECRET || req.auth !== process.env.INGRESS_SECRET) return { statusCode: 403, body: "forbidden\\n" };
+    const r = await invoke({ kind: "probe" });
+    if (r.status !== 200) {
+      console.log(\`probe transport error \${r.status}: \${r.body}\`);
+      return { statusCode: 502, body: "upstream error\\n" };
+    }
+    return { statusCode: 200, headers: { "content-type": "application/json" }, body: r.body.toString() };
+  }
   // Enforce the advertised ORIGINAL-body ceiling before base64 adds another 4/3 inside the runtime
   // envelope. This also leaves deterministic room for headers/query/JSON under Lambda's 6 MB cap.
   const webhookBytes = event.body === undefined ? 0
@@ -562,7 +580,7 @@ function template(input, translated) {
         `      # forces a NAT gateway for model/channel egress (~$33/mo) — deliberately not the default.`,
         `      FilesystemConfigurations:`,
         `        - SessionStorage: { MountPath: ${MOUNT} }`,
-        `      # Idle ${IDLE_TIMEOUT_SECONDS}s (the ping's HealthyBusy keeps BUSY sessions alive regardless), max compute`,
+        `      # Idle ${IDLE_TIMEOUT_SECONDS}s (the ping's HealthyBusy + time_of_last_update keeps BUSY sessions alive), max compute`,
         `      # lifetime ${MAX_LIFETIME_SECONDS}s — the platform ceiling; the session id stays valid, so the next invoke`,
         `      # just gets fresh compute with the same storage. Memory bills per second for the whole`,
         `      # session INCLUDING the idle tail, so a shorter tail is the main cost lever here.`,
@@ -712,7 +730,7 @@ 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"`, ``, `# 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
+        : [`#    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 resolves the per-endpoint log group from the stack's RuntimeArn:`, `fastagent logs agentcore --follow`, ...(needsForwarder
         ? [
             `# The ingress transport is a separate Lambda and therefore a separate log source:`,
             `fastagent logs agentcore --source forwarder --follow`,
@@ -732,7 +750,7 @@ export function planAgentcoreDeploy(input) {
         post.push(`# Register the Telegram webhook (default route POST /telegram; secret_token MUST equal TELEGRAM_SECRET_TOKEN):`, `curl "https://api.telegram.org/bot<TELEGRAM_BOT_TOKEN>/setWebhook" \\`, `  -d url=<ForwarderUrl>/telegram -d secret_token=<TELEGRAM_SECRET_TOKEN>`);
     }
     if (channels.includes("github")) {
-        post.push(`# Set the GitHub webhook (repo Settings → Webhooks): Payload URL = <ForwarderUrl>/webhook,`, `#   content type application/json, secret = GITHUB_WEBHOOK_SECRET.`, `# NOTE: github turns are fire-and-forget with no replay — a compute reclaimed mid-review drops it`, `#   (the ping's HealthyBusy holds the session while turns run, but the 8 h compute ceiling is hard).`);
+        post.push(`# Set the GitHub webhook (repo Settings → Webhooks): Payload URL = <ForwarderUrl>/webhook,`, `#   content type application/json, secret = GITHUB_WEBHOOK_SECRET.`, `# NOTE: github turns are fire-and-forget with no replay — a compute reclaimed mid-review drops it`, `#   (the ping's HealthyBusy + time_of_last_update holds the session while turns run, but the 8 h compute ceiling is hard).`);
     }
     if (channels.includes("slack")) {
         post.push(`# Set Slack Event Subscriptions → Request URL = <ForwarderUrl>/slack (scopes per channels/slack.ts).`);

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

@@ -70,4 +70,10 @@ export declare function parseCheckpointReply(stdout: string): CheckpointReply |
  * post-deploy webhook steps from the builder machine against the forwarder's Function URL. Every
  * gate is fail-visible; `writeSecretFile` is the caller's 0600-temp-file seam (see the header).
  */
-export declare function deployAgentcoreRun(plan: AgentcoreRunPlan, aws: CliRunner, docker: CliRunner, log: (msg: string) => void, writeSecretFile: (content: string) => Promise<string>, writeForwarderZip: (bytes: Uint8Array) => Promise<string>, registerTelegram: (baseUrl: string) => Promise<RegistrationOutcome>, registerFeishu?: (baseUrl: string, kind: "feishu" | "lark") => Promise<RegistrationOutcome>, registerSlack?: (baseUrl: string) => Promise<RegistrationOutcome>): Promise<AgentcoreRunOutcome>;
+export declare function deployAgentcoreRun(plan: AgentcoreRunPlan, aws: CliRunner, docker: CliRunner, log: (msg: string) => void, writeSecretFile: (content: string) => Promise<string>, writeForwarderZip: (bytes: Uint8Array) => Promise<string>, registerTelegram: (baseUrl: string) => Promise<RegistrationOutcome>, registerFeishu?: (baseUrl: string, kind: "feishu" | "lark") => Promise<RegistrationOutcome>, registerSlack?: (baseUrl: string) => Promise<RegistrationOutcome>, 
+/** Injected in tests; the probe itself stays inside the run so no deploy can skip it. */
+probe?: {
+    fetchImpl?: typeof fetch;
+    timeoutMs?: number;
+    intervalMs?: number;
+}): Promise<AgentcoreRunOutcome>;

package/dist/deploy/agentcore/run.js

@@ -3,6 +3,66 @@ import { createHash } from "node:crypto";
 import { Buffer } from "node:buffer";
 import { AUTH_SEED_CHUNK_SIZE, AUTH_SEED_MAX_CHUNKS, cfnParamName, forwarderSource, ingressSessionId, stateBucketName, } from "./plan.js";
 import { zipSingleFile } from "./zip.js";
+/** How long the post-deploy probe waits for the fresh session (image pull + microVM boot + snapshot
+ *  restore + channel construction) before gating with the last answer. */
+const PROBE_TIMEOUT_MS = 120_000;
+const PROBE_INTERVAL_MS = 3_000;
+/**
+ * Drive the forwarder's reserved `/__fastagent/probe` path until it answers, and read the runtime's
+ * STRUCTURED verdict. The path answers on every forwarder topology (a schedule-only URL refuses
+ * ordinary public traffic, so a plain `GET /health` would 404 there), and the verdict rides a
+ * transport-200 JSON body `{ ok, error? }` — the ordinary webhook relay folds a non-200 transport
+ * into an opaque 502, which would strip the very diagnostics this probe exists to carry.
+ *
+ * Outcome policy: `ok:true` verifies the deploy; `ok:false` gates IMMEDIATELY with the runtime's own
+ * error text (construction rejections are cached per session, so polling cannot change the answer);
+ * anything else (unroutable URL, forwarder 4xx/5xx, malformed body) is retried to the deadline —
+ * that budget's job is absorbing cold-start provisioning — and then gates with the last answer seen.
+ */
+async function probeRuntime(probeUrl, auth, fetchImpl, timeoutMs = PROBE_TIMEOUT_MS, intervalMs = PROBE_INTERVAL_MS) {
+    const deadline = Date.now() + timeoutMs;
+    let last;
+    for (;;) {
+        try {
+            const res = await fetchImpl(probeUrl, {
+                method: "POST",
+                headers: { "content-type": "application/json" },
+                body: JSON.stringify({ auth }),
+                signal: AbortSignal.timeout(65_000),
+            });
+            const bodyText = await res.text();
+            if (res.status === 200) {
+                let verdict;
+                try {
+                    verdict = JSON.parse(bodyText);
+                }
+                catch {
+                    /* malformed — fall through to retry with it as the last answer */
+                }
+                if (verdict?.ok === true)
+                    return { ok: true };
+                if (verdict?.ok === false) {
+                    const error = typeof verdict.error === "string" ? verdict.error : "unknown error";
+                    return { ok: false, gate: `the deployed runtime failed its probe: ${error} — fix and re-run` };
+                }
+            }
+            const firstLine = bodyText.trim().split("\n")[0] ?? "";
+            last = `${res.status}${firstLine ? ` ${firstLine}` : ""}`;
+        }
+        catch {
+            /* not routable yet (Function URL DNS, cold start) — keep polling until the deadline */
+        }
+        if (Date.now() >= deadline) {
+            return {
+                ok: false,
+                gate: last
+                    ? `the forwarder probe never verified the deployment (last answer: ${last}) — check the runtime logs and re-run`
+                    : "the forwarder URL never answered the probe — check the Function URL / runtime logs and re-run",
+            };
+        }
+        await new Promise((r) => setTimeout(r, intervalMs));
+    }
+}
 /** Stack outputs (`describe-stacks --query "Stacks[0].Outputs"`) → { OutputKey: OutputValue }. */
 export function parseStackOutputs(stdout) {
     try {
@@ -63,7 +123,9 @@ export function parseCheckpointReply(stdout) {
  * post-deploy webhook steps from the builder machine against the forwarder's Function URL. Every
  * gate is fail-visible; `writeSecretFile` is the caller's 0600-temp-file seam (see the header).
  */
-export async function deployAgentcoreRun(plan, aws, docker, log, writeSecretFile, writeForwarderZip, registerTelegram, registerFeishu, registerSlack) {
+export async function deployAgentcoreRun(plan, aws, docker, log, writeSecretFile, writeForwarderZip, registerTelegram, registerFeishu, registerSlack, 
+/** Injected in tests; the probe itself stays inside the run so no deploy can skip it. */
+probe = {}) {
     const gate = (g) => ({ ok: false, gate: g });
     const stack = `fastagent-${plan.name}`;
     const repo = `fastagent/${plan.name}`;
@@ -359,19 +421,42 @@ export async function deployAgentcoreRun(plan, aws, docker, log, writeSecretFile
                 log("note: no ingress session to stop (first deploy, or already reclaimed)");
             }
             else {
-                log(`warn: could not stop the ingress session — an ACTIVE session may keep serving the PREVIOUS ` +
-                    `image until reclaimed (idle timeout / 8 h ceiling). Stop it manually: aws ${stopCommand.join(" ")}`);
+                // A GATE, not a warning: the probe below reaches the SAME fixed session id, so a session
+                // still running the previous image would answer it and the deploy would claim to have
+                // verified a serving path it never touched. Unable to guarantee the session is fresh =
+                // unable to verify = stop.
                 const firstLine = stderr.trim().split("\n")[0];
-                if (firstLine)
-                    log(`warn: ${firstLine}`);
+                return gate(`could not stop the ingress session — it may still be serving the PREVIOUS image, so the ` +
+                    `deploy cannot verify the new one${firstLine ? ` (${firstLine})` : ""}. ` +
+                    `Stop it manually (aws ${stopCommand.join(" ")}) and re-run`);
             }
         }
     }
+    // 8c. Every forwarder topology MUST carry the ForwarderUrl output — schedule-only and
+    //     selfSchedule-only deployments included, since the probe below is their only construction
+    //     check (there is no boot-time failStartup on this host). A missing output means an edited
+    //     template; skipping the probe silently would let such a deploy report success unverified.
+    //     Only a pure-invoke deployment (no forwarder) legitimately has no URL and nothing to probe.
+    //     `channels.length` is belt-and-braces: the planner derives needsForwarder FROM the channel
+    //     list, but this gate must not silently trust that invariant across callers.
+    if ((plan.needsForwarder || plan.channels.length > 0) && !url) {
+        return gate("this deployment needs the forwarder but the stack has no ForwarderUrl output — regenerate the " +
+            "template with --force");
+    }
+    // 8d. Warm + verify the NEW serving path end to end, BEFORE registration: the probe wakes a fresh
+    //     session on the new image through the forwarder's reserved path, which restores the state
+    //     snapshot and constructs the channels — construction is deferred to exactly that moment
+    //     (channels/agentcore.ts), so this is where a bad credential, a broken channels/ module, or an
+    //     unrestorable snapshot surfaces AT DEPLOY TIME with the runtime's own error text.
+    if (url) {
+        log("probing the deployed runtime (state restore + channel construction)…");
+        const verdict = await probeRuntime(`${url}/__fastagent/probe`, plan.secrets.FASTAGENT_INGRESS_SECRET ?? "", probe.fetchImpl ?? fetch, probe.timeoutMs, probe.intervalMs);
+        if (!verdict.ok)
+            return gate(verdict.gate);
+        log("runtime verified (state restored, channels constructed)");
+    }
     // 9. Post-deploy webhook registration — same registrar seam as every host, pointed at the
     //    forwarder's Function URL. Gate policy is the shared registration-gate kernel.
-    if (plan.channels.length > 0 && !url) {
-        return gate("channels are declared but the stack has no ForwarderUrl output — regenerate the template with --force");
-    }
     const reg = registrationGate(log, "re-run to retry registration (steps already done are skipped)");
     if (url) {
         if (plan.channels.includes("telegram")) {

package/dist/deploy/preflight.js

@@ -195,12 +195,17 @@ export async function preflightDeploy(input) {
         const rel = relative(workspace, p);
         return rel === "" || rel.startsWith("..") || isAbsolute(rel) ? undefined : rel.split(sep).join("/");
     };
-    // The secrets DIR is the unit, not the two filenames we happen to know: an atomic-write temp beside
-    // auth.json, a second key file, an editor backup of `.env` — all of it must stay out of the image, and
-    // `resolveSecretsDir` says as much ("everything fastagent manages that must never leave the machine").
-    // The auth path adds an entry only when an override puts it OUTSIDE that dir. An external secrets dir
-    // (the deployed posture: a mounted volume) is outside the context — nothing to check, nothing to
-    // exclude.
+    // The secrets DIR is the unit of RESPONSIBILITY, but never the unit of the leak QUESTION below: the
+    // generated ignore excludes the dir's CONTENTS (`**/.secrets/**`) so its two value-free tracked
+    // scaffolds can be re-included, and a directory-level question reads that correct file as "not
+    // excluded" — the generator's own default output gated its own deploy (field-hit: a fresh
+    // kit-layout workspace without --force; --force skips checking our own file, which is why the
+    // combination stayed invisible). What leaks is a FILE, so files are what the gate asks about — see
+    // secretDirFiles below, which enumerates what is actually inside (an atomic-write temp beside
+    // auth.json, a second key file, an editor backup of `.env`: the dir-as-unit worry, covered per
+    // file). The auth path adds an entry only when an override puts it OUTSIDE that dir. An external
+    // secrets dir (the deployed posture: a mounted volume) is outside the context — nothing to check,
+    // nothing to exclude.
     const secretsRel = inContext(resolveSecretsDir(agentDir));
     const authRel = inContext(authPath);
     const authElsewhere = authRel !== undefined && (secretsRel === undefined || !authRel.startsWith(`${secretsRel}/`));
@@ -246,7 +251,29 @@ export async function preflightDeploy(input) {
             .map((n) => join(relDir, n).split(sep).join("/"));
     };
     const envFiles = (await Promise.all([...new Set(["", agentPrefix])].map(dotEnvFiles))).flat();
-    const leakCandidates = [...(await present(secretPaths)), ...envFiles];
+    // Everything ACTUALLY inside the secrets dir, minus the two tracked scaffolds the image ships on
+    // purpose (they carry no values; the generated ignore re-includes them by name). Existence is the
+    // enumeration itself — readdir lists exactly what could be baked — and a hand-written ignore that
+    // misses the dir now gates NAMING the leaking file, a better diagnostic than pointing at a
+    // directory. Recurses: a subdirectory inside .secrets is unusual but its files leak all the same.
+    const secretDirFiles = async (dirRel) => {
+        const entries = await readdir(join(workspace, dirRel), { withFileTypes: true }).catch(() => []);
+        const files = [];
+        for (const entry of entries) {
+            if (entry.name === ".gitignore" || entry.name === ".env.example")
+                continue;
+            if (entry.isDirectory())
+                files.push(...(await secretDirFiles(`${dirRel}/${entry.name}`)));
+            else
+                files.push(`${dirRel}/${entry.name}`);
+        }
+        return files;
+    };
+    const leakCandidates = [
+        ...(secretsRel ? await secretDirFiles(secretsRel) : []),
+        ...(await present(authElsewhere && authRel !== undefined ? [authRel] : [])),
+        ...envFiles,
+    ];
     // Same existence rule: a node_modules that is not there cannot be uploaded.
     const depDirs = await present([...new Set([`${agentPrefix}node_modules`, "node_modules"])]);
     const machineryPaths = [...secretPaths, ...(stateRel ? [stateRel] : [])];

package/dist/engines/pi/create.js

@@ -19,7 +19,7 @@ import { resolveSecretsDir } from "../../paths.js";
 import { loadAgentDefinition } from "./definition.js";
 import { DEFAULT_THINKING_LEVEL, piHarnessFactory } from "./harness.js";
 import { createPiModels } from "./models.js";
-import { reportDefinitionWarnings } from "./report.js";
+import { reportFindingsIfChanged } from "./report.js";
 import { inMemorySessionStore } from "./sessions.js";
 import { isDeferredTool, loadTools, mergeDiscoveredTools, } from "./tool.js";
 import { withSearchTool } from "./search-tools.js";
@@ -221,12 +221,6 @@ export function createPiAgent(options) {
         observer: options.observer,
     });
 }
-/** Stable identity of a definition's non-fatal findings, for change-detection in `live` (dedup only). */
-function findingsSignature(def) {
-    const collisions = def.collisions.map((c) => `c:${c.name}:${c.winnerPath}:${c.loserPath}`);
-    const diagnostics = def.diagnostics.map((d) => `d:${d.code}:${d.path}`);
-    return [...collisions, ...diagnostics].sort().join("\n");
-}
 /**
  * L2: "point at a directory → agent": load + assemble (base + AGENTS.md + skills + env) + L1 in one
  * call. Returns the definition so callers can surface diagnostics/collisions.
@@ -239,10 +233,11 @@ export async function createPiAgentFromDefinition(dir, options) {
     // Boot-time load: fail-visibly at startup on a broken directory, and give callers the snapshot to
     // report (skills/diagnostics/collisions). Serving does NOT close over it — see `live` below.
     const definition = await loadAgentDefinition(dir, { cwd: env.cwd, env });
-    // Findings the caller already reported at boot; `live` re-reports only when the set CHANGES — a
-    // runtime-written bad skill surfaces the moment it appears, while a static finding does not spam
-    // every turn's log. A log-dedup memo, not session state (stateless invoke holds).
-    let reportedFindings = findingsSignature(definition);
+    // Boot findings go through the SAME memoized reporter every later reader uses (report.ts, keyed by
+    // the resolved dir): announced once here, and re-announced by a turn or by the control plane's
+    // command list only when the set CHANGES — a runtime-written bad skill surfaces the moment it
+    // appears, a static one does not spam. Log dedup, not session state (stateless invoke holds).
+    reportFindingsIfChanged(definition.dir, definition);
     // Deferred tools need their loader on every rung (idempotent — the workspace opener already applied
     // it; a caller's own search_tools wins).
     const tools = withSearchTool(options.tools ?? piDefaultTools());
@@ -265,11 +260,7 @@ export async function createPiAgentFromDefinition(dir, options) {
         // next good edit heals both.
         live: async () => {
             const def = await loadAgentDefinition(dir, { cwd: env.cwd, env });
-            const sig = findingsSignature(def);
-            if (sig !== reportedFindings) {
-                reportedFindings = sig;
-                reportDefinitionWarnings(def.collisions, def.diagnostics);
-            }
+            reportFindingsIfChanged(def.dir, def);
             return {
                 systemPrompt: assembleSystemPrompt({
                     // Segment ①: an authored persona (persona.md, def.persona) overrides the engine identity,

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

@@ -41,6 +41,21 @@ export interface LoadAgentDefinitionOptions {
 }
 /** Read an agent definition. persona.md/skills come from `agentDir`; ② context = pi's loadProjectContextFiles({ cwd, agentDir }). */
 export declare function loadAgentDefinition(agentDir: string, options?: LoadAgentDefinitionOptions): Promise<LoadedDefinition>;
+/**
+ * The definition's skills ALONE, resolved the same way `loadAgentDefinition` resolves them (same
+ * loader, same containment guard, same first-wins collision rule) — for readers that need only the
+ * names and must not pay the full load's ② context walk (every AGENTS.md from cwd to root) for them.
+ * The control plane's `commands()` is that reader, called when a composer opens its completion list.
+ */
+export declare function loadAgentSkills(agentDir: string, options?: {
+    cwd?: string;
+    env?: ExecutionEnv;
+}): Promise<{
+    skills: Skill[];
+    diagnostics: SkillDiagnostic[];
+    collisions: SkillCollision[];
+    dir: string;
+}>;
 /**
  * Whether `targetPath` lives inside `baseDir` (same path counts). Used to ask "did an override move
  * this OUT of the agent?" — the startup report's redeploy notes, `add`'s printed `.env` label, and the

package/dist/engines/pi/definition.js

@@ -42,6 +42,11 @@ export async function loadAgentDefinition(agentDir, options = {}) {
         throw new Error(`cannot read ${personaPath}: ${personaRead.error.message}`);
     }
     const persona = personaRead.ok ? personaRead.value : undefined;
+    const { skills, diagnostics, collisions } = await readSkills(e, root);
+    return { contextFiles, persona, skills, diagnostics, collisions, dir: root };
+}
+/** The skills half, shared by the full load and {@link loadAgentSkills}. `root` is already resolved. */
+async function readSkills(e, root) {
     // Skills come ONLY from the definition's own skills/ (no external/global mount), so the same
     // definition loads the same skills on every machine — and, like tools/channels/schedules, a symlink
     // that escapes the agent dir is refused rather than followed (the fourth of four surfaces).
@@ -58,7 +63,23 @@ export async function loadAgentDefinition(agentDir, options = {}) {
             byName.set(skill.name, skill);
         }
     }
-    return { contextFiles, persona, skills: [...byName.values()], diagnostics, collisions, dir: root };
+    return { skills: [...byName.values()], diagnostics, collisions };
+}
+/**
+ * The definition's skills ALONE, resolved the same way `loadAgentDefinition` resolves them (same
+ * loader, same containment guard, same first-wins collision rule) — for readers that need only the
+ * names and must not pay the full load's ② context walk (every AGENTS.md from cwd to root) for them.
+ * The control plane's `commands()` is that reader, called when a composer opens its completion list.
+ */
+export async function loadAgentSkills(agentDir, options = {}) {
+    const cwd = options.cwd ?? agentDir;
+    const e = options.env ?? new NodeExecutionEnv({ cwd });
+    const rootResult = await e.absolutePath(agentDir);
+    if (!rootResult.ok)
+        throw new Error(`cannot resolve agent dir "${agentDir}": ${rootResult.error.message}`);
+    // `dir` is the RESOLVED root, like {@link LoadedDefinition.dir}: readers key per-definition state
+    // (the findings memo) on it, and "./agent" vs an absolute path must not become two definitions.
+    return { ...(await readSkills(e, rootResult.value)), dir: rootResult.value };
 }
 /**
  * Whether `targetPath` lives inside `baseDir` (same path counts). Used to ask "did an override move

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

@@ -4,7 +4,7 @@ import type { SessionControl } from "../../session.ts";
 import type { SessionObserver } from "./invoke.ts";
 import type { PiSessionReader, PiSessionStore } from "./sessions.ts";
 import type { ModuleLoadFailure } from "../../loader.ts";
-import type { LoadedDefinition } from "./definition.ts";
+import { type LoadedDefinition } from "./definition.ts";
 import type { ToolCollision } from "./tool.ts";
 import type { MountedTool } from "./tool.ts";
 export interface CreatePiAgentFromDirOptions {

package/dist/engines/pi/open.js

@@ -14,6 +14,8 @@ import { resolveStateRoot, resolvePlacement } from "../../paths.js";
 import { createPiAgentFromDefinition, resolveAgentTools } from "./create.js";
 import { createPiSessionControl } from "./session-control.js";
 import { withWakeTool } from "./wake-tool.js";
+import { loadAgentSkills } from "./definition.js";
+import { reportFindingsIfChanged } from "./report.js";
 import { jsonlSessionStore } from "./sessions.js";
 export async function resolveAgentAssembly(dir, options = {}) {
     // Placement is structural (resolvePlacement): the AGENT DIR carries definition + config + machinery;
@@ -73,6 +75,23 @@ export async function createPiAgentFromDir(dir, options = {}) {
         ? createPiSessionControl({
             sessions,
             boundary: () => boundaryParts,
+            // Skills ARE the names a client offers — the resolved set, after collisions were decided
+            // first-wins, which a client cannot reconstruct from the directory. Read LIVE (the directory
+            // is the agent: a skill added while serving is in play on the next turn, so it must be
+            // listable now) and SKILLS-ONLY: this is called when a composer opens its completion list,
+            // and the full load's ② context walk buys nothing here.
+            commands: async () => {
+                const loaded = await loadAgentSkills(agentDir, { cwd: workspace });
+                // A skill whose frontmatter broke simply is not in `skills` — it would disappear from the
+                // author's composer with no signal anywhere. The memo is SHARED with the turn path (keyed
+                // by dir), so a finding is warned when it appears, not once per reader that notices it.
+                reportFindingsIfChanged(loaded.dir, loaded);
+                return loaded.skills.map((skill) => ({
+                    name: skill.name,
+                    description: skill.description,
+                    source: "skill",
+                }));
+            },
             // The caller tap's boundary-event half: state_changed/compaction_* originate in the hub
             // and never cross the data plane's observer seam — without this, an audit tap wired here
             // would miss exactly the mutations it most needs to see (set_model).

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

@@ -6,8 +6,24 @@ import type { SkillDiagnostic } from "@earendil-works/pi-agent-core";
 import type { SkillCollision } from "./definition.ts";
 import type { ModuleLoadFailure } from "../../loader.ts";
 import type { ToolCollision } from "./tool.ts";
+type Findings = {
+    collisions: SkillCollision[];
+    diagnostics: SkillDiagnostic[];
+};
+/**
+ * THE door for definition findings: warns only when this dir's set CHANGED since the last report.
+ * Every reader calls it — boot, the per-turn live read, the control plane's command list — so a
+ * finding is announced when it appears and never repeated. There is deliberately no "record without
+ * printing" variant: a memo entry that trusts some other caller to have printed would silently
+ * swallow findings for a caller that does not.
+ *
+ * `dir` must be the RESOLVED definition root (`LoadedDefinition.dir`), or two spellings of one path
+ * become two memos and warn twice.
+ */
+export declare function reportFindingsIfChanged(dir: string, def: Findings): void;
 export declare function reportDefinitionWarnings(collisions: SkillCollision[], diagnostics: SkillDiagnostic[]): void;
 export declare function reportToolCollisions(collisions: ToolCollision[]): void;
 /** Report per-file module failures. The caller decides whether they are degradations (tools/schedules)
  *  or fatal (declared channels on the serving path). */
 export declare function reportModuleLoadFailures(failures: ModuleLoadFailure[]): void;
+export {};

package/dist/engines/pi/report.js

@@ -1,4 +1,34 @@
 import { log } from "../../log.js";
+/** Stable identity of a definition's non-fatal findings — the dedup key below. */
+function findingsSignature(def) {
+    const collisions = def.collisions.map((c) => `c:${c.name}:${c.winnerPath}:${c.loserPath}`);
+    const diagnostics = def.diagnostics.map((d) => `d:${d.code}:${d.path}`);
+    return [...collisions, ...diagnostics].sort().join("\n");
+}
+/**
+ * The last reported finding set PER DEFINITION DIR. One memo for every reader of a definition (the
+ * per-turn live read, the control plane's command list), because the thing being deduped is the
+ * FINDING, not the reader: a newly broken skill deserves one warning, not one per code path that
+ * noticed it, and a static one deserves none at all.
+ */
+const lastFindings = new Map();
+/**
+ * THE door for definition findings: warns only when this dir's set CHANGED since the last report.
+ * Every reader calls it — boot, the per-turn live read, the control plane's command list — so a
+ * finding is announced when it appears and never repeated. There is deliberately no "record without
+ * printing" variant: a memo entry that trusts some other caller to have printed would silently
+ * swallow findings for a caller that does not.
+ *
+ * `dir` must be the RESOLVED definition root (`LoadedDefinition.dir`), or two spellings of one path
+ * become two memos and warn twice.
+ */
+export function reportFindingsIfChanged(dir, def) {
+    const sig = findingsSignature(def);
+    if (lastFindings.get(dir) === sig)
+        return;
+    lastFindings.set(dir, sig);
+    reportDefinitionWarnings(def.collisions, def.diagnostics);
+}
 export function reportDefinitionWarnings(collisions, diagnostics) {
     for (const c of collisions) {
         log.warn(`[fastagent] skill "${c.name}" collision — using ${c.winnerPath}, ignoring ${c.loserPath}`);

package/dist/engines/pi/session-builder.js

@@ -37,7 +37,7 @@ import { canonicalPath, loadAgentDefinition } from "./definition.js";
 import { createPiModelRuntime, probeAuthSource } from "./models.js";
 import { log } from "../../log.js";
 import { additiveActivation, turnContext } from "./tool-context.js";
-import { reportDefinitionWarnings, reportModuleLoadFailures, reportToolCollisions } from "./report.js";
+import { reportFindingsIfChanged, reportModuleLoadFailures, reportToolCollisions } from "./report.js";
 import { resolveAgentAssembly } from "./open.js";
 /** Adapt coding-agent's resident SessionManager to FastAgent's shared tool-runtime manager port. */
 function toolChatSessionManager(session) {
@@ -119,7 +119,7 @@ sessionManager) {
         const model = resolveModel(modelRuntime, modelSpec);
         const env = new NodeExecutionEnv({ cwd });
         const definition = await loadAgentDefinition(agentDir, { cwd, env });
-        reportDefinitionWarnings(definition.collisions, definition.diagnostics);
+        reportFindingsIfChanged(definition.dir, definition);
         const defaultNames = piDefaultTools().map((t) => t.name);
         const customTools = tools.filter((t) => !defaultNames.includes(t.name));
         // Adapt fastagent's AgentTool to pi's ToolDefinition (`parameters` is plain JSON-Schema; pi accepts

package/dist/engines/pi/session-control.d.ts

@@ -1,6 +1,6 @@
 import type { ThinkingLevel } from "@earendil-works/pi-agent-core";
 import type { Models } from "@earendil-works/pi-ai";
-import { type SessionControl, type SessionEvent } from "../../session.ts";
+import { type AgentCommand, type SessionControl, type SessionEvent } from "../../session.ts";
 import type { Lease, SessionObserver } from "./invoke.ts";
 import { type AnyModel, type PiHarnessFactory } from "./harness.ts";
 import { type PiSessionReader } from "./sessions.ts";
@@ -39,6 +39,16 @@ export interface CreatePiSessionControlOptions {
      *  (assembly completes before any dispatch can arrive). Absent / undefined → boundary commands
      *  are gated off in `capabilities()` and rejected `unsupported_capability`. */
     boundary?: () => PiBoundaryWiring | undefined;
+    /** The definition's names, as a LAZY thunk for the same reason {@link boundary} is one (the hub
+     *  exists before the assembly that can read a definition) — and async because the definition is
+     *  live: this must re-read it, not close over a boot snapshot, or `commands()` would advertise a
+     *  list the next turn no longer runs.
+     *
+     *  OPTIONAL because absence is a TRUE answer for the assembly that omits it: a hub over an L1
+     *  agent (`createPiAgent({ model, instructions, tools })`) has no definition and therefore no
+     *  names, and `[]` says exactly that. Wire it whenever the agent came from a DIRECTORY — there
+     *  `[]` would be a lie; the directory constructor (`createPiAgentFromDir`) always does. */
+    commands?: () => Promise<AgentCommand[]>;
     /** Tap for the events the HUB ITSELF generates (boundary mutations: `state_changed`,
      *  `compaction_*`) — those never pass through the data plane's observer seam, so a consumer
      *  composing a full-vocabulary tap wires the run events via the observer AND this. Called after

package/dist/engines/pi/session-control.js

@@ -200,6 +200,9 @@ export function createPiSessionControl(options) {
         fanOut(session, event);
     };
     const control = {
+        async commands() {
+            return (await options.commands?.()) ?? [];
+        },
         capabilities: () => {
             const b = boundary?.();
             return {