@fastagent-sh/fastagent 0.16.1 → 0.17.0

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
@@ -21,12 +29,17 @@ export interface SessionControl {
     dispatch(session: string, command: SessionCommand): Promise<SessionResult>;
 }
 /**
- * Static support declaration, two kinds of flag:
- * - COMMAND GATES (`steering`, `followUp`, `manualCompaction`, `modelSelection`, `thinkingLevel`):
+ * STATIC support declaration — sessionless, so nothing here may depend on a session. Two kinds of flag:
+ * - COMMAND GATES (`steering`, `followUp`, `manualCompaction`, `modelSelection`, `thinkingLevel`,
+ *   `navigate`):
  *   clients MUST gate dispatch on them; an unsupported command is rejected before acceptance with
  *   {@link UNSUPPORTED_CAPABILITY_CODE}.
  * - OBSERVATION-QUALITY flags (`toolProgress`, `usage`): whether those events/state fields appear
  *   at all — nothing to dispatch, nothing to reject.
+ *
+ * `modelSelection` may carry a list because the registry is a deployment fact; thinking levels
+ * depend on the session's current model, so they live on {@link SessionState.availableThinkingLevels}.
+ *
  * `state`/`entries`/`events` are mandatory (the reconnect contract) and deliberately absent here.
  */
 export interface SessionCapabilities {
@@ -36,12 +49,30 @@ export interface SessionCapabilities {
     modelSelection: false | {
         allowedModels: string[];
     };
-    thinkingLevel: false | {
-        allowedLevels: string[];
-    };
+    /** Whether `set_thinking` is servable at all. WHICH levels is per-session — see
+     *  {@link SessionState.availableThinkingLevels}. */
+    thinkingLevel: boolean;
+    /** Whether `navigate` is servable at all — `false` both when the engine's sessions are linear and
+     *  when this deployment has no write path for them; either way the tree the contract publishes
+     *  (`SessionEntry.parentId` + `SessionEntries.leafEntryId`) is read-only here. Named after its COMMAND, unlike the older gates (`manualCompaction` gates
+     *  `compact`, `thinkingLevel` gates `set_thinking`): those already force a client to translate,
+     *  and a gate keyed by the command literal is the only naming a derived map could ever produce. */
+    navigate: boolean;
     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`)
@@ -79,7 +110,7 @@ export declare const NOTHING_TO_COMPACT_CODE = "nothing_to_compact";
  *  command as-is fails again. (A run registered without modulation controls is a capability
  *  problem, not a run problem, and rejects with {@link UNSUPPORTED_CAPABILITY_CODE}.) */
 export declare const RUN_COMMAND_FAILED_CODE = "run_command_failed";
-/** Six commands; deliberately NO `prompt` — starting work is the data plane's definition. */
+/** Seven commands; deliberately NO `prompt` — starting work is the data plane's definition. */
 export type SessionCommand = {
     type: "steer";
     prompt: Prompt;
@@ -97,6 +128,14 @@ export type SessionCommand = {
 } | {
     type: "set_thinking";
     level: string;
+}
+/** Move the session's active leaf to `targetId`, an existing entry — the write verb for the tree
+ *  `entries()` already publishes (and how sibling branches come to exist: the next turn hangs off
+ *  the new leaf). Every entry `entries()` publishes is a legal target; a `targetId` that is not
+ *  one rejects `invalid_command`. A boundary mutation otherwise: same lease as a run. */
+ | {
+    type: "navigate";
+    targetId: string;
 };
 /**
  * Acceptance is not outcome: `ok: true` means admitted or applied, never that the run ultimately
@@ -125,10 +164,13 @@ export interface SessionState {
      *  compaction happens inside a run's activity window and reports as `running`. */
     status: "idle" | "running" | "compacting";
     activeRunId?: string;
-    /** The session's durable overrides (set_model / set_thinking), read from the record — so a
-     *  reconnecting client sees them without scanning entries. Absent = the assembly default. */
+    /** What this session will RUN with, not what was recorded: overrides resolved against the
+     *  deployment (a model the registry lost falls back to the configured one; a level the current
+     *  model cannot do is clamped). Absent where the implementation exposes no model control. */
     model?: string;
     thinkingLevel?: string;
+    /** What `set_thinking` accepts for THIS session — re-read after a `set_model`. */
+    availableThinkingLevels?: string[];
     pending: {
         steering: number;
         followUp: number;
@@ -222,10 +264,13 @@ export type QueueChangedEvent = SessionEvent<"queue_changed", {
     runId: string;
 };
 /** A boundary mutation changed durable session state (L2; no runId — boundary mutations happen
- *  between runs). */
+ *  between runs). `leafEntryId` reports a `navigate` — a deliberate move of the branch head, which
+ *  a second attached client would otherwise have no signal for. It is NOT a general leaf feed:
+ *  every turn advances the leaf too, and that is read from `entries()`/`state()` after the run. */
 export type StateChangedEvent = SessionEvent<"state_changed", {
     model?: string;
     thinkingLevel?: string;
+    leafEntryId?: string;
 }>;
 /** Manual compaction bounds (L2): every `compaction_started` is closed by exactly one
  *  `compaction_finished` — `summary` on success, `error` on failure, `aborted: true` on a

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fastagent-sh/fastagent",
-  "version": "0.16.1",
+  "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",