@fastagent-sh/fastagent 0.18.0 → 0.20.0

package/dist/session.d.ts

@@ -1,63 +1,193 @@
 /**
  * Session control plane — the engine-neutral serving extension beside Agent Handler
- * (docs/design/session-control.md). Pure types, zero dependencies; importing any engine
- * implementation here is forbidden, exactly like agent.ts.
+ * (docs/design/session-control.md). Zero dependencies, no engine import, exactly like agent.ts.
  *
- * The plane model: `invoke` is the only data plane (no run exists without an invoke); `dispatch`
- * modulates the run an invoke drives; `state`/`entries`/`events` observe, strictly read-only.
+ * `invoke` remains the only data plane: no run exists without one. Everything here observes a run,
+ * modulates it, or manages the records it leaves behind — and the shape follows which of those a
+ * call is, not the transport that carries it. A session's PROPERTIES (name, model, thinking level,
+ * where its leaf points) are updated; things that HAPPEN to a run (steer, abort, compact) are
+ * actions; the set of sessions is a collection. One verb over all three would make a client spell
+ * the session id on every call and read "delete" as something dispatched INTO a session that is
+ * about to stop existing.
  */
 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
+    /** The names this agent exposes — what a composer's `/` completion LISTS. A listing, not an
+     *  invocation 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>;
+    sessions: SessionCollection;
+}
+/** The deployment's sessions, as a collection. */
+export interface SessionCollection {
+    /** Every session this DEPLOYMENT holds — what a GUI shows as its conversation list, and the only
+     *  call that is not about ONE session. Deployment-level on purpose: a multi-tenant facade in front
+     *  of one deployment MUST NOT expose it, because it answers for every user at once. Such a facade
+     *  does not need it either — `Scope.session` is the Caller's own string, so it already holds the
+     *  mapping this would return (design §5).
+     *
+     *  The one read that MAY reject: `[]` is a complete answer for a deployment with no sessions, so
+     *  it would be a lie for a store that cannot be enumerated. Every other read stays TOTAL — their
+     *  absent fields are answers a control-less deployment gives too. */
+    list(): Promise<SessionSummary[]>;
+    /**
+     * Copy `from`'s history up to entry `at` into a session called `into` — the growth verb beside
+     * {@link SessionUpdate.leafEntryId}'s walk, and the two together are what make a session tree
+     * usable. Cloning is this with the source's own `leafEntryId`.
+     *
+     * IDEMPOTENT: `into` is the CALLER's id (the plane never invents one), so repeating a fork that
+     * already landed is `ok: true` and writes nothing — a client that retries a request whose response
+     * it never saw does not get a second record. `into` naming a session that exists but came from
+     * somewhere else rejects `invalid_command`: same id, different history is what the id would then
+     * be lying about.
+     *
+     * Answers a result, not the new session: the caller minted `into` and can {@link get} it.
+     */
+    fork(options: {
+        from: string;
+        at: string;
+        into: string;
+    }): Promise<SessionResult>;
+    /** Bind an id. A PURE BINDING — an id plus the transport it travels on: no state, no lifecycle,
+     *  nothing to dispose, and it does not check that the session exists (the calls on it answer that,
+     *  each in its own vocabulary). Two handles for one id are interchangeable. */
+    get(session: string): Session;
+}
+/**
+ * Can this id be ADDRESSED by a client? A session id is an opaque Caller string, and the data plane
+ * takes any of it — but a control plane carries the id as a URL path segment, and three strings are
+ * not path segments: the empty one, `.` and `..`. URL normalisation eats them before any router
+ * sees them (`encodeURIComponent` does not help; the spec normalises `%2E` too), so a request for
+ * `.` arrives as a request for the collection and answers about something else entirely.
+ *
+ * The rule lives HERE, in the contract, because both sides enforce it and they must not drift: a
+ * transport rejects such an id rather than sending a request that will silently address its
+ * neighbour, and an implementation refuses to MINT one (a fork target nothing could open) — while a
+ * session a channel already created under one keeps running, and keeps appearing in `list()`, since
+ * hiding it would be the silent half of the same problem.
+ */
+export declare function isAddressableSession(session: string): boolean;
+/**
+ * One session, bound. Every call here is about THIS session, so the id is spelled once.
+ *
+ * The split inside it is the one the contract is built on: {@link update} sets PROPERTIES (durable,
+ * last-wins, applied by the next turn), while the action methods do things TO A RUN (admitted or
+ * rejected now, outcome later on the event stream). {@link SessionResult} says which of the two a
+ * given answer is.
+ */
+export interface Session {
+    readonly id: string;
+    state(): 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
      *  the client's job via `parentId` chains from `leafEntryId`. An unknown cursor falls back to a
      *  full backfill (correct, merely larger). */
-    entries(session: string, options?: {
+    entries(options?: {
         since?: string;
     }): Promise<SessionEntries>;
-    events(session: string): AsyncIterable<SessionEvent>;
-    dispatch(session: string, command: SessionCommand): Promise<SessionResult>;
+    events(): AsyncIterable<SessionEvent>;
+    /** Set durable session properties. Last-wins, applied by every later turn; an empty patch is a
+     *  no-op that still answers `ok: true`. Fields outside {@link SessionCapabilities.updatable}
+     *  reject `unsupported_capability`; invalid values reject `invalid_command`. Takes the same lease
+     *  as a run (`session_busy` while one is in flight).
+     *
+     *  VALIDATION is all-or-nothing: a rejected patch leaves nothing behind, which is what makes
+     *  `ok: false` safe to retry. The WRITES need not be one operation — an engine may record each
+     *  property separately — so a failure BETWEEN them answers {@link PARTIAL_UPDATE_CODE}, naming
+     *  what landed, after an event reporting the record as it now is. */
+    update(patch: SessionUpdate): Promise<SessionResult>;
+    /** Join the active run: delivered after the current turn's tool calls, before the next model
+     *  call. Not polyfillable — its delivery point is an engine primitive. */
+    steer(prompt: Prompt): Promise<SessionResult>;
+    /** Queue for the active run, FIFO, delivered when it is otherwise idle. */
+    followUp(prompt: Prompt): Promise<SessionResult>;
+    /** Stop the active run — its queues, its retry delay, its cancellable tool work — or an in-flight
+     *  {@link compact}, which is the same kind of thing: a model call a client must be able to stop. */
+    abort(): Promise<SessionResult>;
+    /** Summarize the history at a session boundary. ACCEPT-FAST: a full model call, so `ok: true`
+     *  means admitted and the outcome travels as `compaction_finished{summary|error|aborted}`. */
+    compact(options?: {
+        instructions?: string;
+    }): Promise<SessionResult>;
+    /** Destroy the record. The plane's only IRREVERSIBLE call, guarded by the same bearer token as
+     *  everything else — the only key the framework owns (design §14). Live {@link events} streams for
+     *  this session END; a later {@link state} answers for a session that no longer exists. */
+    delete(): Promise<SessionResult>;
 }
+/** The durable properties {@link Session.update} sets. Every field is optional and last-wins; which
+ *  ones a deployment accepts is {@link SessionCapabilities.updatable}. */
+export interface SessionUpdate {
+    /** The display name `list()` reports — a label, not an identity: the id stays the Caller's. */
+    name?: string;
+    /** A FastAgent model spec, constrained to {@link SessionCapabilities.allowedModels}. Never a
+     *  provider credential. */
+    model?: string;
+    /** A string because supported levels are MODEL-dependent — the set for this session's current
+     *  model is {@link SessionState.availableThinkingLevels}. */
+    thinkingLevel?: string;
+    /** Move the session's active leaf: the write verb for the tree `entries()` publishes, and how
+     *  sibling branches come to exist (the next turn hangs off it). Every entry `entries()` publishes
+     *  is a legal target; anything else rejects `invalid_command`. A move to where the leaf already is
+     *  writes nothing. There is no move to the ROOT — "start from nothing" is a new session, not an
+     *  emptied one. */
+    leafEntryId?: string;
+}
+/** What {@link Session.update} can be asked to set. */
+export type SessionUpdateField = keyof SessionUpdate;
+/** Every field name, as a value — what an implementation checks a patch against, and what a
+ *  transport rejects an unknown key by. The `satisfies` anchor keeps it exhaustive: a field added to
+ *  {@link SessionUpdate} must be added here too, or this stops compiling. */
+export declare const UPDATE_FIELDS: readonly ["name", "model", "thinkingLevel", "leafEntryId"];
+/**
+ * The wire form of the run actions — what a transport carries for {@link Session.steer} and its
+ * siblings. Clients use the METHODS; this exists so a transport has one body shape to parse, and so
+ * an implementation can answer an unknown `type` as `invalid_command` rather than crashing.
+ */
+export type SessionAction = {
+    type: "steer";
+    prompt: Prompt;
+} | {
+    type: "follow_up";
+    prompt: Prompt;
+} | {
+    type: "abort";
+} | {
+    type: "compact";
+    instructions?: string;
+};
 /**
- * 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
+ * STATIC support declaration — sessionless, so nothing here may depend on a session. Two kinds of
+ * flag, and the difference decides what a client does with them:
+ * - GATES (`steering`, `followUp`, `compaction`, `fork`, `delete`, `updatable`): a client MUST gate
+ *   its controls on these; calling past one rejects 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.
+ * - OBSERVATION QUALITY (`toolProgress`, `usage`): whether those events/state fields appear at all —
+ *   nothing to call, 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}.
+ * `allowedModels` may live here because the registry is a deployment fact; thinking LEVELS depend on
+ * the model a session is currently running, so they live on
+ * {@link SessionState.availableThinkingLevels} — a static list could only answer for one model.
  *
- * `state`/`entries`/`events` are mandatory (the reconnect contract) and deliberately absent here.
+ * `state`/`entries`/`events` and `sessions.list()` are mandatory (the reconnect contract and the
+ * conversation list) and deliberately absent here.
  */
 export interface SessionCapabilities {
     steering: boolean;
     followUp: boolean;
-    manualCompaction: boolean;
-    modelSelection: false | {
-        allowedModels: 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;
+    compaction: boolean;
+    fork: boolean;
+    delete: boolean;
+    /** Which {@link SessionUpdate} fields this deployment accepts. A patch naming anything else
+     *  rejects `unsupported_capability` — a LIST rather than a flag per field, so a client reads the
+     *  same names it writes. */
+    updatable: SessionUpdateField[];
+    /** The specs `update({ model })` accepts — present iff `model` is updatable. */
+    allowedModels?: string[];
     toolProgress: boolean;
     usage: boolean;
 }
@@ -73,26 +203,28 @@ export interface AgentCommand {
     description?: string;
     source: string;
 }
-/** Stable `SessionResult.error.code` for a command the implementation does not support. */
+/** Stable `SessionResult.error.code` for a call, or an update field, the implementation does not
+ *  support — the answer to calling past a {@link SessionCapabilities} gate. */
 export declare const UNSUPPORTED_CAPABILITY_CODE = "unsupported_capability";
-/** Stable `SessionResult.error.code` for a run-modulating command (`steer`/`follow_up`/`abort`)
- *  dispatched while the session has no active run — and, for `abort`, no in-flight manual
- *  compaction either (`abort` is also the door out of a `compacting` state; the outcome then
- *  travels as `compaction_finished{aborted}`). `retryable: false` — re-dispatching as-is fails
- *  again; re-dispatch only after `state()` shows an active run. */
+/** Stable `SessionResult.error.code` for a run action
+ *  (`steer`/`follow_up`/`abort`) called while the session has no active run — and, for `abort`, no
+ *  in-flight compaction either (`abort` is also the door out of a `compacting` state; the outcome
+ *  then travels as `compaction_finished{aborted}`). `retryable: false` — the same call fails again;
+ *  call it after `state()` shows an active run. */
 export declare const NO_ACTIVE_RUN_CODE = "no_active_run";
-/** Stable `SessionResult.error.code` for a command whose PAYLOAD is invalid for this runtime — an
- *  unknown model spec, an unsupported thinking level. Permanent for that payload; a different value
- *  may succeed. Rejected before acceptance. */
+/** Stable `SessionResult.error.code` for a PAYLOAD that is invalid for this runtime — an unknown
+ *  model spec, an unsupported thinking level, an entry id that is not a position, a fork onto an id
+ *  another history already holds. Permanent for that payload; a different value may succeed.
+ *  Rejected before acceptance. */
 export declare const INVALID_COMMAND_CODE = "invalid_command";
-/** Stable `SessionResult.error.code` for a boundary mutation on a session that does not exist.
- *  Sessions are created by the DATA plane (`invoke`), never by the control plane — a mutation on an
- *  unknown id (a typo, a not-yet-started conversation) must not mint a ghost record. Rejected
- *  before acceptance; retry after the session's first turn exists. */
+/** Stable `SessionResult.error.code` for a write against a session that does not exist. Sessions are
+ *  created by the DATA plane (`invoke`) or copied by `fork`, never minted by an update — a write on
+ *  an unknown id (a typo, a not-yet-started conversation) must not create a ghost record. Rejected
+ *  before acceptance; retry once the session's first turn exists. */
 export declare const NO_SUCH_SESSION_CODE = "no_such_session";
-/** Stable `SessionResult.error.code` for a boundary mutation rejected BEFORE acceptance with
- *  nothing durable landed — a failed override append, or compact's admission failing (the harness
- *  build, the local preparation). Acceptance sits where the work becomes asynchronous and
+/** Stable `SessionResult.error.code` for a write rejected BEFORE acceptance with nothing durable
+ *  landed — a failed property append, a fork whose copy could not be written, or compact's admission
+ *  failing (binding the session, the local preparation). Acceptance sits where the work becomes asynchronous and
  *  expensive: the model call — compact is accept-fast (holding the dispatch open for a full model
  *  call would make acceptance = outcome), and post-acceptance outcomes travel as
  *  `compaction_finished{summary|error|aborted}` events. `retryable: true` throughout: the same
@@ -101,52 +233,35 @@ export declare const NO_SUCH_SESSION_CODE = "no_such_session";
 export declare const BOUNDARY_COMMAND_FAILED_CODE = "boundary_command_failed";
 /** Stable `SessionResult.error.code` for `compact` on a session with no compactable history yet —
  *  a no-op, not a failure, rejected before acceptance. The {@link NO_ACTIVE_RUN_CODE} pattern:
- *  `retryable: false` (as-is retry fails now), re-dispatch once the session has grown. */
+ *  `retryable: false` (as-is retry fails now), call it again once the session has grown. */
 export declare const NOTHING_TO_COMPACT_CODE = "nothing_to_compact";
-/** Stable `SessionResult.error.code` for a run command that reached an active run but could not
- *  take effect because the run raced to settlement (or the engine refused it). Distinct from
- *  {@link NO_ACTIVE_RUN_CODE}: the run existed — and TRANSIENT: the session's next run can be
- *  dispatched to. Still pre-acceptance — nothing was queued — and `retryable: false`: the same
- *  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}.) */
+/** Stable `SessionResult.error.code` for a run action that reached an active run but could not take
+ *  effect because the run raced to settlement (or the engine refused it). Distinct from
+ *  {@link NO_ACTIVE_RUN_CODE}: the run existed — and TRANSIENT: the session's next run can be acted
+ *  on. Still pre-acceptance — nothing was queued — and `retryable: false`: the same call 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";
-/** Seven commands; deliberately NO `prompt` — starting work is the data plane's definition. */
-export type SessionCommand = {
-    type: "steer";
-    prompt: Prompt;
-} | {
-    type: "follow_up";
-    prompt: Prompt;
-} | {
-    type: "abort";
-} | {
-    type: "compact";
-    instructions?: string;
-} | {
-    type: "set_model";
-    model: string;
-} | {
-    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;
-};
+/** What {@link SessionCollection.list} rejects with — the only read that can (see it for why). Not a
+ *  `SessionResult`: it REJECTS, and a transport carries this code in the error body of a non-2xx
+ *  (design §13). `retryable: true` — the condition is the store's availability, not the request. */
+export declare const SESSIONS_UNAVAILABLE_CODE = "sessions_unavailable";
+/** Stable `SessionResult.error.code` for a multi-field {@link Session.update} that wrote some of its
+ *  fields and then failed. It exists because {@link BOUNDARY_COMMAND_FAILED_CODE} promises the
+ *  opposite — nothing durable landed — and an implementation cannot keep that promise across
+ *  properties an engine records as separate journal entries. `retryable: false`: re-sending the same
+ *  patch would re-apply what already landed, so a client reads `state()` (or the `state_changed`
+ *  this emits first, which reports the record as it now is) and decides what is left to ask for. */
+export declare const PARTIAL_UPDATE_CODE = "partial_update";
 /**
  * Acceptance is not outcome: `ok: true` means admitted or applied, never that the run ultimately
  * succeeded (outcomes are `run_settled` events / the invoke terminal). `ok: false` is guaranteed to
  * mean rejection BEFORE acceptance — nothing was queued or applied. ONE exception to "nothing took
  * effect": a rejected `abort` may still have attributed a concurrently-settling run as `aborted`
  * (the intent was live while the run resolved — see the guarantee boundary in the pi
- * implementation); the settlement is the truth. `error.retryable` means "re-dispatching the SAME
- * command as-is may succeed"; a `false` with a state-dependent code (e.g.
- * {@link NO_ACTIVE_RUN_CODE}) invites a re-dispatch only after `state()` shows the condition
- * changed.
+ * implementation); the settlement is the truth. `error.retryable` means "the SAME call as-is may
+ * succeed"; a `false` with a state-dependent code (e.g. {@link NO_ACTIVE_RUN_CODE}) invites another
+ * call only after `state()` shows the condition changed.
  */
 export type SessionResult = {
     ok: true;
@@ -159,7 +274,22 @@ export type SessionResult = {
         retryable: boolean;
     };
 };
+/** One session in {@link SessionControl.sessions} — a conversation-list row, not a session's
+ *  contents. `session` is the CALLER's id (the string a channel minted), never a storage name. */
+export interface SessionSummary {
+    session: string;
+    /** Set by `update({ name })`; absent until then — a client showing a list falls back to `preview`. */
+    name?: string;
+    createdAt: number;
+    updatedAt: number;
+    messageCount: number;
+    /** First user message, truncated — enough for a list row, not a transcript. */
+    preview?: string;
+}
 export interface SessionState {
+    /** Set by `update({ name })`, so a client that opens a session directly gets the same label the list
+     *  showed. */
+    name?: string;
     /** `compacting` refers to Phase 2 MANUAL compaction at a session boundary. Automatic overflow
      *  compaction happens inside a run's activity window and reports as `running`. */
     status: "idle" | "running" | "compacting";
@@ -169,7 +299,7 @@ export interface SessionState {
      *  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`. */
+    /** What `update({ thinkingLevel })` accepts for THIS session — re-read after a model change. */
     availableThinkingLevels?: string[];
     pending: {
         steering: number;
@@ -263,11 +393,15 @@ export type QueueChangedEvent = SessionEvent<"queue_changed", {
 }> & {
     runId: string;
 };
-/** A boundary mutation changed durable session state (L2; no runId — boundary mutations happen
- *  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. */
+/** An {@link Session.update} changed durable session state (L2; no runId — a property is set between
+ *  runs). Carries what LANDED, read back from the record: a patch that set two fields reports both,
+ *  and one that failed partway reports only what applied.
+ *
+ *  `leafEntryId` reports 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", {
+    name?: string;
     model?: string;
     thinkingLevel?: string;
     leafEntryId?: string;
@@ -289,7 +423,9 @@ export type CompactionFinishedEvent = SessionEvent<"compaction_finished", {
  *  the next event (message_*, `run_settled`, `compaction_finished`) is the closure, and the
  *  engine's `retry_finished` carries no outcome to forward. */
 export type RetryScheduledEvent = SessionEvent<"retry_scheduled", {
-    operation: "compaction" | "branch_summary";
+    /** "assistant" is an engine that retries the ANSWER request itself (pi's AgentSession does;
+     *  pi's own session does; a summarization call is the other two). */
+    operation: "assistant" | "compaction" | "branch_summary";
     attempt: number;
     maxAttempts: number;
     delayMs: number;

package/dist/session.js

@@ -1,23 +1,50 @@
-/** Stable `SessionResult.error.code` for a command the implementation does not support. */
+/**
+ * Can this id be ADDRESSED by a client? A session id is an opaque Caller string, and the data plane
+ * takes any of it — but a control plane carries the id as a URL path segment, and three strings are
+ * not path segments: the empty one, `.` and `..`. URL normalisation eats them before any router
+ * sees them (`encodeURIComponent` does not help; the spec normalises `%2E` too), so a request for
+ * `.` arrives as a request for the collection and answers about something else entirely.
+ *
+ * The rule lives HERE, in the contract, because both sides enforce it and they must not drift: a
+ * transport rejects such an id rather than sending a request that will silently address its
+ * neighbour, and an implementation refuses to MINT one (a fork target nothing could open) — while a
+ * session a channel already created under one keeps running, and keeps appearing in `list()`, since
+ * hiding it would be the silent half of the same problem.
+ */
+export function isAddressableSession(session) {
+    return session !== "" && session !== "." && session !== "..";
+}
+/** Every field name, as a value — what an implementation checks a patch against, and what a
+ *  transport rejects an unknown key by. The `satisfies` anchor keeps it exhaustive: a field added to
+ *  {@link SessionUpdate} must be added here too, or this stops compiling. */
+export const UPDATE_FIELDS = [
+    "name",
+    "model",
+    "thinkingLevel",
+    "leafEntryId",
+];
+/** Stable `SessionResult.error.code` for a call, or an update field, the implementation does not
+ *  support — the answer to calling past a {@link SessionCapabilities} gate. */
 export const UNSUPPORTED_CAPABILITY_CODE = "unsupported_capability";
-/** Stable `SessionResult.error.code` for a run-modulating command (`steer`/`follow_up`/`abort`)
- *  dispatched while the session has no active run — and, for `abort`, no in-flight manual
- *  compaction either (`abort` is also the door out of a `compacting` state; the outcome then
- *  travels as `compaction_finished{aborted}`). `retryable: false` — re-dispatching as-is fails
- *  again; re-dispatch only after `state()` shows an active run. */
+/** Stable `SessionResult.error.code` for a run action
+ *  (`steer`/`follow_up`/`abort`) called while the session has no active run — and, for `abort`, no
+ *  in-flight compaction either (`abort` is also the door out of a `compacting` state; the outcome
+ *  then travels as `compaction_finished{aborted}`). `retryable: false` — the same call fails again;
+ *  call it after `state()` shows an active run. */
 export const NO_ACTIVE_RUN_CODE = "no_active_run";
-/** Stable `SessionResult.error.code` for a command whose PAYLOAD is invalid for this runtime — an
- *  unknown model spec, an unsupported thinking level. Permanent for that payload; a different value
- *  may succeed. Rejected before acceptance. */
+/** Stable `SessionResult.error.code` for a PAYLOAD that is invalid for this runtime — an unknown
+ *  model spec, an unsupported thinking level, an entry id that is not a position, a fork onto an id
+ *  another history already holds. Permanent for that payload; a different value may succeed.
+ *  Rejected before acceptance. */
 export const INVALID_COMMAND_CODE = "invalid_command";
-/** Stable `SessionResult.error.code` for a boundary mutation on a session that does not exist.
- *  Sessions are created by the DATA plane (`invoke`), never by the control plane — a mutation on an
- *  unknown id (a typo, a not-yet-started conversation) must not mint a ghost record. Rejected
- *  before acceptance; retry after the session's first turn exists. */
+/** Stable `SessionResult.error.code` for a write against a session that does not exist. Sessions are
+ *  created by the DATA plane (`invoke`) or copied by `fork`, never minted by an update — a write on
+ *  an unknown id (a typo, a not-yet-started conversation) must not create a ghost record. Rejected
+ *  before acceptance; retry once the session's first turn exists. */
 export const NO_SUCH_SESSION_CODE = "no_such_session";
-/** Stable `SessionResult.error.code` for a boundary mutation rejected BEFORE acceptance with
- *  nothing durable landed — a failed override append, or compact's admission failing (the harness
- *  build, the local preparation). Acceptance sits where the work becomes asynchronous and
+/** Stable `SessionResult.error.code` for a write rejected BEFORE acceptance with nothing durable
+ *  landed — a failed property append, a fork whose copy could not be written, or compact's admission
+ *  failing (binding the session, the local preparation). Acceptance sits where the work becomes asynchronous and
  *  expensive: the model call — compact is accept-fast (holding the dispatch open for a full model
  *  call would make acceptance = outcome), and post-acceptance outcomes travel as
  *  `compaction_finished{summary|error|aborted}` events. `retryable: true` throughout: the same
@@ -26,12 +53,23 @@ export const NO_SUCH_SESSION_CODE = "no_such_session";
 export const BOUNDARY_COMMAND_FAILED_CODE = "boundary_command_failed";
 /** Stable `SessionResult.error.code` for `compact` on a session with no compactable history yet —
  *  a no-op, not a failure, rejected before acceptance. The {@link NO_ACTIVE_RUN_CODE} pattern:
- *  `retryable: false` (as-is retry fails now), re-dispatch once the session has grown. */
+ *  `retryable: false` (as-is retry fails now), call it again once the session has grown. */
 export const NOTHING_TO_COMPACT_CODE = "nothing_to_compact";
-/** Stable `SessionResult.error.code` for a run command that reached an active run but could not
- *  take effect because the run raced to settlement (or the engine refused it). Distinct from
- *  {@link NO_ACTIVE_RUN_CODE}: the run existed — and TRANSIENT: the session's next run can be
- *  dispatched to. Still pre-acceptance — nothing was queued — and `retryable: false`: the same
- *  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}.) */
+/** Stable `SessionResult.error.code` for a run action that reached an active run but could not take
+ *  effect because the run raced to settlement (or the engine refused it). Distinct from
+ *  {@link NO_ACTIVE_RUN_CODE}: the run existed — and TRANSIENT: the session's next run can be acted
+ *  on. Still pre-acceptance — nothing was queued — and `retryable: false`: the same call fails
+ *  again. (A run registered without modulation controls is a capability problem, not a run problem,
+ *  and rejects with {@link UNSUPPORTED_CAPABILITY_CODE}.) */
 export const RUN_COMMAND_FAILED_CODE = "run_command_failed";
+/** What {@link SessionCollection.list} rejects with — the only read that can (see it for why). Not a
+ *  `SessionResult`: it REJECTS, and a transport carries this code in the error body of a non-2xx
+ *  (design §13). `retryable: true` — the condition is the store's availability, not the request. */
+export const SESSIONS_UNAVAILABLE_CODE = "sessions_unavailable";
+/** Stable `SessionResult.error.code` for a multi-field {@link Session.update} that wrote some of its
+ *  fields and then failed. It exists because {@link BOUNDARY_COMMAND_FAILED_CODE} promises the
+ *  opposite — nothing durable landed — and an implementation cannot keep that promise across
+ *  properties an engine records as separate journal entries. `retryable: false`: re-sending the same
+ *  patch would re-apply what already landed, so a client reads `state()` (or the `state_changed`
+ *  this emits first, which reports the record as it now is) and decides what is left to ask for. */
+export const PARTIAL_UPDATE_CODE = "partial_update";

package/dist/telegram.d.ts

@@ -1,2 +1,2 @@
 /** `@fastagent-sh/fastagent/telegram` — the Telegram bot channel subpath export, kept off the root surface. */
-export { telegramChannel, defaultTelegramRoute, telegramEnvelope, type TelegramChannelOptions, type TelegramUpdate, type TelegramMessage, type TelegramRoute, type TelegramFailure, } from "./channels/telegram/telegram.ts";
+export { telegramChannel, defaultTelegramRoute, telegramEnvelope, telegramStop, type TelegramChannelOptions, type TelegramUpdate, type TelegramMessage, type TelegramRoute, type TelegramFailure, } from "./channels/telegram/telegram.ts";

package/dist/telegram.js

@@ -1,2 +1,2 @@
 /** `@fastagent-sh/fastagent/telegram` — the Telegram bot channel subpath export, kept off the root surface. */
-export { telegramChannel, defaultTelegramRoute, telegramEnvelope, } from "./channels/telegram/telegram.js";
+export { telegramChannel, defaultTelegramRoute, telegramEnvelope, telegramStop, } from "./channels/telegram/telegram.js";

package/dist/tunnel.d.ts

@@ -7,6 +7,8 @@
  * Process orchestration, not assembly — lives outside the engine, beside dev-supervisor.ts.
  */
 import { type ChildProcess } from "node:child_process";
+import type { RegistrationOutcome } from "./channels/registration.ts";
+import type { DeclaredChannel } from "./channels/discover.ts";
 export interface Tunnel {
     url: string;
     close(): void;
@@ -28,10 +30,23 @@ export declare function startCloudflareTunnel(port: number, spawnFn?: SpawnCloud
  * Print the public URL and wire up first-party webhook channels found under `dir` (the agent
  * ROOT): Telegram and Feishu/Lark use runtime credentials; onboarded Slack uses its owner-local config
  * token; GitHub and a manually scaffolded Slack app receive explicit console URLs.
+ *
+ * Returns what each registrar ANSWERED, because two kinds of caller need different things from a
+ * failure. `dev`/`start` are long-running: a webhook that did not register is a logged problem, not
+ * a reason to stop serving, and they void this. `deploy … --run` is a command that exits, and an
+ * exit 0 there tells its caller the deployment is reachable — so it feeds these through
+ * `registrationGate`, exactly as the fly/railway/agentcore runners feed their own registrar calls
+ * (docker used to be the one host that could not, because this returned nothing).
  */
-export declare function announceWebhooks(dir: string, baseUrl: string, opts?: {
+export declare function announceWebhooks(dir: string, baseUrl: string, 
+/** Every declared channel with its ingress. Not a pre-filtered list: this used to accept "the route
+ *  channels" and default to every basename in `channels/`, which pointed a webhook at a
+ *  long-connection channel whenever a caller forgot to filter. {@link pointChannelsAt} filters. */
+channels: readonly DeclaredChannel[], opts?: {
     openUrl?: (url: string) => void;
-    routeChannels?: string[];
     stateRoot?: string;
-}): Promise<void>;
+}): Promise<{
+    kind: string;
+    outcome: RegistrationOutcome;
+}[]>;
 export {};