@fastagent-sh/fastagent 0.16.2 → 0.17.0

package/dist/channels/agentcore.js

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

package/dist/channels/control.d.ts

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

package/dist/channels/control.js

@@ -84,7 +84,7 @@ function parseWireCommand(raw) {
     }
 }
 /**
- * Mount the control plane: `GET /control/capabilities|state|entries|events` + `POST
+ * Mount the control plane: `GET /control/capabilities|commands|state|entries|events` + `POST
  * /control/dispatch`, all bearer-authenticated. `events` streams SSE (`data: <WireEvent>` lines).
  */
 export function controlRoutes(control, options) {
@@ -111,6 +111,7 @@ export function controlRoutes(control, options) {
     return {
         ...(invokeHandler ? { "POST /control/invoke": guard((req) => invokeHandler(req)) } : {}),
         "GET /control/capabilities": guard(() => json(control.capabilities())),
+        "GET /control/commands": guard(async () => json(await control.commands())),
         "GET /control/state": guard(async (_req, url) => {
             const session = sessionParam(url);
             if (!session)

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

@@ -72,6 +72,24 @@ export interface AttachIo {
  * whole — the one case where "unknown" must not read as "off-path".
  */
 export declare function activePathSlice(entries: SessionEntry[], leafEntryId: string | undefined): SessionEntry[];
+/**
+ * Answer a RESERVED-SLASH line (anything starting with `/` that is not `/abort`). Two intents share
+ * the prefix — a mistyped control command and an attempt to invoke a name — and they are answered
+ * differently:
+ *
+ * - a mistyped slash gets the certain half NOW (a leading `/` is reserved here, whatever the token
+ *   turns out to be), because waiting on a remote read that can be slow or fail would leave the
+ *   input unanswered; it deliberately does not pre-judge the token as unknown — the read may be
+ *   about to prove it names a real skill;
+ * - `/commands` prints nothing first: its whole answer IS the read, and a placeholder is noise;
+ * - the enumeration answers `/commands` ONLY — dumping every skill at a mistyped `/aboort` answers
+ *   an intent the typo did not express.
+ *
+ * Names print BARE: this composer cannot expand `/name` (the data plane takes prompts as text), so
+ * printing them with a slash would invite the user straight back into this branch. Returns the
+ * promise for the remote half, so a caller (or a test) can await the second line.
+ */
+export declare function answerSlashInput(trimmed: string, control: Pick<SessionControl, "commands">, println: (line: string) => void): Promise<void>;
 /**
  * ONE attach round: subscribe → backfill (render the durable record since `cursor`) → drain live
  * until the stream drops. Returns the advanced cursor. Subscribing first + the server's eager

package/dist/cli/commands/attach.js

@@ -185,7 +185,7 @@ export async function runAttach(sessionArg, dirArg, opts) {
         // invoke) — give the human a corrective signal.
         log.warn(`[fastagent] no durable record for "${sessionArg}" yet — a new session, or a typo?`);
     }
-    log.info(`[fastagent] type to steer the active run; /abort to stop it; Ctrl+C to detach`);
+    log.info(`[fastagent] type to steer the active run; /abort to stop it; /commands to list what this agent defines; Ctrl+C to detach`);
     // stdin → the two planes: a line steers the ACTIVE run; with no run to join (no_active_run) it
     // falls back to STARTING one over the remote data plane (`POST /control/invoke`) — try-steer-
     // then-prompt avoids a state() pre-check race. Acceptance is not outcome: rejections print and
@@ -222,7 +222,7 @@ export async function runAttach(sessionArg, dirArg, opts) {
         // `/` is a reserved command prefix: a typo'd /aboort silently steering the model (injecting a
         // prompt when the user meant to STOP the run) is the dangerous direction of the ambiguity.
         if (trimmed.startsWith("/") && trimmed !== "/abort") {
-            console.log(`[unknown command ${trimmed} — /abort stops the run; a leading / is reserved]`);
+            void answerSlashInput(trimmed, control, (l) => console.log(l));
             return;
         }
         const command = trimmed === "/abort" ? { type: "abort" } : { type: "steer", prompt: { text: trimmed } };
@@ -449,6 +449,50 @@ export function activePathSlice(entries, leafEntryId) {
     }
     return entries.filter((e) => onPath.has(e.id));
 }
+/**
+ * Answer a RESERVED-SLASH line (anything starting with `/` that is not `/abort`). Two intents share
+ * the prefix — a mistyped control command and an attempt to invoke a name — and they are answered
+ * differently:
+ *
+ * - a mistyped slash gets the certain half NOW (a leading `/` is reserved here, whatever the token
+ *   turns out to be), because waiting on a remote read that can be slow or fail would leave the
+ *   input unanswered; it deliberately does not pre-judge the token as unknown — the read may be
+ *   about to prove it names a real skill;
+ * - `/commands` prints nothing first: its whole answer IS the read, and a placeholder is noise;
+ * - the enumeration answers `/commands` ONLY — dumping every skill at a mistyped `/aboort` answers
+ *   an intent the typo did not express.
+ *
+ * Names print BARE: this composer cannot expand `/name` (the data plane takes prompts as text), so
+ * printing them with a slash would invite the user straight back into this branch. Returns the
+ * promise for the remote half, so a caller (or a test) can await the second line.
+ */
+export async function answerSlashInput(trimmed, control, println) {
+    // The first WORD is the token: slash input naturally carries arguments (`/triage my inbox`), and
+    // taking the whole line would answer "names nothing" for a name the user did give.
+    const word = trimmed.slice(1).split(/\s+/)[0] ?? "";
+    const listing = word === "commands";
+    if (!listing)
+        println("[a leading / is reserved — /abort stops the run, /commands lists what this agent defines]");
+    let commands;
+    try {
+        commands = await control.commands();
+    }
+    catch (error) {
+        println(`[command list unavailable: ${error}]`);
+        return;
+    }
+    if (listing) {
+        // `description` is what makes a listing usable — a bare name tells the author nothing they did
+        // not already know from the directory.
+        const listed = commands.map((c) => (c.description ? `${c.name} — ${c.description}` : c.name));
+        println(listed.length ? `[this agent defines: ${listed.join("; ")}]` : "[this agent defines no names]");
+        return;
+    }
+    const hit = commands.find((c) => c.name === word);
+    println(hit
+        ? `[${hit.name} is a ${hit.source}${hit.description ? ` — ${hit.description}` : ""}; name it in a normal message, without the /]`
+        : `[/${word} names nothing this agent defines]`);
+}
 /**
  * ONE attach round: subscribe → backfill (render the durable record since `cursor`) → drain live
  * until the stream drops. Returns the advanced cursor. Subscribing first + the server's eager

package/dist/cli/commands/dev.js

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

package/dist/cli/commands/info.js

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

package/dist/cli/commands/start.js

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

package/dist/cli/program.js

@@ -457,8 +457,8 @@ 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.",
+        "The default Runtime source shows the agent process's own stdout/stderr; the forwarder source shows " +
+        "the Lambda ingress transport logs.",
     args: [{ name: "<host>", description: "deployed host", choices: ["agentcore"] }, DIR_ARG],
     flags: [
         { flags: "--source <source>", description: "agentcore log source: runtime (default) or forwarder" },

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;
@@ -562,7 +563,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 +713,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 +733,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/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 {

package/dist/session-remote.js

@@ -65,6 +65,23 @@ export async function connectSessionControl(options) {
     const capabilities = await get("/control/capabilities");
     return {
         capabilities: () => capabilities,
+        // NOT prefetched like capabilities: a live definition can grow a skill between calls, so the
+        // list is fetched per call. The endpoint is UNCACHED server-side (it re-reads the definition's
+        // skills/ per request), which is what keeps it honest about a directory that changes underneath
+        // it. A 404 is SKEW, not a fault in the definition: without this the two read identically
+        // (uncoded non-2xx), and a client would report "this agent's skills are unreadable" about a
+        // serve that simply predates the route.
+        async commands() {
+            try {
+                return await get("/control/commands");
+            }
+            catch (error) {
+                if (error instanceof ControlRequestError && error.status === 404) {
+                    throw new ControlRequestError(404, "this serve does not implement /control/commands (it predates the route)");
+                }
+                throw error;
+            }
+        },
         state: (session) => get(`/control/state?session=${encodeURIComponent(session)}`),
         entries: (session, opts) => get(`/control/entries?session=${encodeURIComponent(session)}${opts?.since !== undefined ? `&since=${encodeURIComponent(opts.since)}` : ""}`, PAYLOAD_TIMEOUT_MS),
         async dispatch(session, command) {

package/dist/session.d.ts

@@ -9,6 +9,14 @@
 import type { Json, Prompt } from "./agent.ts";
 export interface SessionControl {
     capabilities(): SessionCapabilities;
+    /** The names this agent exposes — what a composer's `/` completion LISTS. A listing, not a
+     *  dispatch surface: the data plane takes prompts as text, so what typing one means (expanding it,
+     *  sending "use the X skill", filtering a menu) is the client's business. Sessionless (the
+     *  definition is a deployment fact) but ASYNC, because a definition is allowed to be live: an
+     *  implementation that re-reads it per turn must answer from that same read, or the list and the
+     *  behavior diverge. `[]` is a complete answer, not a missing one; a definition the implementation
+     *  cannot read at all is a deployment fault and MAY reject. */
+    commands(): Promise<AgentCommand[]>;
     state(session: string): Promise<SessionState>;
     /** `since` is an APPEND-ORDER position cursor: "every record appended after the one with this
      *  id", regardless of branch structure. Reconstructing the active path in a branched session is
@@ -53,6 +61,18 @@ export interface SessionCapabilities {
     toolProgress: boolean;
     usage: boolean;
 }
+/**
+ * One name a client can offer the user. Field NAMES follow pi's RPC `get_commands` so a client
+ * porting from it maps directly; its `sourceInfo` (file provenance) is deliberately not carried, and
+ * `source` is a free-form string rather than pi's closed union — which kinds exist is an engine's
+ * business ("skill" is the only one fastagent assembles today), and an engine with none answers `[]`
+ * rather than the contract enumerating a set it cannot know.
+ */
+export interface AgentCommand {
+    name: string;
+    description?: string;
+    source: string;
+}
 /** Stable `SessionResult.error.code` for a command the implementation does not support. */
 export declare const UNSUPPORTED_CAPABILITY_CODE = "unsupported_capability";
 /** Stable `SessionResult.error.code` for a run-modulating command (`steer`/`follow_up`/`abort`)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fastagent-sh/fastagent",
-  "version": "0.16.2",
+  "version": "0.17.0",
   "description": "Vibe first. Then FastAgent: turn a local agent directory into a live service in your app, on GitHub, Telegram, Slack, or behind any channel.",
   "keywords": [
     "agent",