@fastagent-sh/fastagent 0.13.0 → 0.15.0

package/dist/session-remote.js

@@ -0,0 +1,336 @@
+import { SSE_HEARTBEAT_MS } from "./channels/http.js";
+import { abortFirstIterator } from "./collect.js";
+/** Dead-connection watchdog for SSE reads: the server heartbeats every SSE_HEARTBEAT_MS, so a
+ *  PENDING READ seeing no bytes (of ANY kind — comments included) for this many missed beats
+ *  means the connection is a black hole. The stream is aborted and surfaced as an error, so a
+ *  consumer's failure budget ticks instead of hanging forever. Quiet-but-alive streams (a long
+ *  tool call) keep heartbeating and never trip this. */
+const SSE_IDLE_LIMIT_MS = 3 * SSE_HEARTBEAT_MS;
+function idleWatchdog(abort) {
+    let armedAt;
+    let stale = false;
+    const timer = setInterval(() => {
+        if (armedAt !== undefined && Date.now() - armedAt > SSE_IDLE_LIMIT_MS) {
+            stale = true;
+            abort.abort();
+        }
+    }, SSE_HEARTBEAT_MS);
+    return {
+        arm: () => {
+            armedAt ??= Date.now();
+        },
+        disarm: () => {
+            armedAt = undefined;
+        },
+        stale: () => stale,
+        stop: () => clearInterval(timer),
+    };
+}
+/** A control request the server answered with a non-2xx status. Carries the STRUCTURED status so a
+ *  consumer distinguishing auth failure (401 — stale token, unrecoverable) from transient transport
+ *  trouble branches on `status`, never on message prose. */
+export class ControlRequestError extends Error {
+    status;
+    constructor(status, body) {
+        super(`control request failed: ${status} ${body}`);
+        this.status = status;
+    }
+}
+/**
+ * Connect and return a remote `SessionControl`. Async because `capabilities()` is synchronous in
+ * the contract: the static declaration is fetched ONCE here and served from memory — which also
+ * makes a wrong URL/token fail at connect time, not on first use.
+ */
+export async function connectSessionControl(options) {
+    const { url, token, fetchFn = fetch } = options;
+    const base = url.replace(/\/$/, "");
+    const headers = { authorization: `Bearer ${token}` };
+    // Non-streaming requests carry a TIMEOUT: attach's whole reliability model counts failed rounds
+    // against a budget ("unreachable for ~Ns"), which a black-hole endpoint (firewall drop, half-dead
+    // tunnel) would silently defeat — a hung state()/entries() ticks nothing. The SSE stream stays
+    // timeout-free (quiet is normal there; heartbeats cover proxy idling).
+    const REQUEST_TIMEOUT_MS = 10_000;
+    // The PAYLOAD-bearing calls get a longer budget than the black-hole detector's 10s — in both
+    // directions: dispatch may UPLOAD up to the 1 MiB body cap (base64 images in steer/follow_up),
+    // and entries may DOWNLOAD a long session's full record (a cursor-less first backfill) — a slow
+    // link legitimately needs longer, and cutting a healthy transfer would be indistinguishable from
+    // a dead endpoint. capabilities/state stay on the short detector: they are small by contract.
+    const PAYLOAD_TIMEOUT_MS = 60_000;
+    const get = async (path, timeoutMs = REQUEST_TIMEOUT_MS) => {
+        const res = await fetchFn(`${base}${path}`, { headers, signal: AbortSignal.timeout(timeoutMs) });
+        if (!res.ok)
+            throw new ControlRequestError(res.status, await res.text());
+        return (await res.json());
+    };
+    const capabilities = await get("/control/capabilities");
+    return {
+        capabilities: () => capabilities,
+        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) {
+            const res = await fetchFn(`${base}/control/dispatch`, {
+                method: "POST",
+                headers: { ...headers, "content-type": "application/json" },
+                body: JSON.stringify({ session, command }),
+                signal: AbortSignal.timeout(PAYLOAD_TIMEOUT_MS),
+            });
+            if (!res.ok)
+                throw new ControlRequestError(res.status, await res.text());
+            return (await res.json());
+        },
+        events(session) {
+            // Each ITERATION opens its own connection (gen/abort created inside asyncIterator), matching
+            // the local hub's "every iteration is a fresh subscription" — a shared single-use generator
+            // would make the second for-await silently empty, breaking local/remote isomorphism.
+            // The abort controller lives OUTSIDE the generator: a consumer's `return()`/`break` while the
+            // generator is suspended on a quiet SSE read must abort the fetch FIRST — an async generator's
+            // own finally only runs after the pending await settles, which a silent stream never does.
+            const openStream = (abort) => (async function* iterate() {
+                // Armed BEFORE the fetch: the connect phase (headers never arriving from a black-holed
+                // endpoint) is otherwise a window no timeout covers — the same watchdog terminates it,
+                // with headers-arrival counting as the first sign of life.
+                const watchdog = idleWatchdog(abort);
+                watchdog.arm(); // the connect await is a pending read
+                try {
+                    const res = await fetchFn(`${base}/control/events?session=${encodeURIComponent(session)}`, {
+                        headers,
+                        signal: abort.signal,
+                    });
+                    watchdog.disarm(); // headers arrived
+                    if (!res.ok) {
+                        // The error body is a pending read too — a half-dead tunnel serving 4xx headers then
+                        // black-holing the body must not hang the round outside every budget. Re-armed: the
+                        // watchdog aborts the read and the round fails with the dead-connection diagnosis.
+                        watchdog.arm();
+                        throw new ControlRequestError(res.status, await res.text());
+                    }
+                    if (!res.body)
+                        throw new Error("control events: response has no body");
+                    let nextSeq = 0;
+                    for await (const data of sseData(res.body, watchdog)) {
+                        // Parse discipline, same as the other two wire planes (dispatch parses, invoke
+                        // classifies drift): a non-JSON or non-envelope payload is PROTOCOL MISMATCH —
+                        // thrown, so a consumer's failure budget applies — never misdiagnosed as an
+                        // in-transit gap whose remedy (reconnect) can never fix it.
+                        let wire;
+                        try {
+                            // The ONE envelope type (control.ts's WireEvent) — an inline shape would let the
+                            // envelope drift server-side while this cast silently kept the old fields.
+                            wire = JSON.parse(data);
+                        }
+                        catch (parseError) {
+                            throw new Error(`control events: non-JSON data on the stream (${String(parseError)}) — protocol mismatch?`);
+                        }
+                        if (typeof wire.seq !== "number" || typeof wire.event !== "object" || wire.event === null) {
+                            throw new Error("control events: malformed envelope — the endpoint does not speak this protocol version");
+                        }
+                        // Envelope checks — consumed HERE. (epoch is not compared: it cannot change within
+                        // one connection — see the header note.) A gap THROWS like a protocol mismatch: the
+                        // consumer's failure path (budget, its own io) owns the diagnostic — a library-level
+                        // log would bypass consumer output discipline, and a silent clean end would be
+                        // indistinguishable from the server closing normally.
+                        if (wire.seq !== nextSeq) {
+                            throw new Error(`control events: sequence gap (expected ${nextSeq}, got ${wire.seq}) — events were lost in transit; resync via entries()`);
+                        }
+                        nextSeq = wire.seq + 1;
+                        yield wire.event;
+                    }
+                }
+                catch (error) {
+                    if (abort.signal.aborted) {
+                        if (watchdog.stale()) {
+                            throw new Error(`control events: no bytes for ${SSE_IDLE_LIMIT_MS / 1000}s (heartbeats absent) — dead connection; resync via entries()`);
+                        }
+                        return; // the consumer walked away — clean end, not an error
+                    }
+                    throw error;
+                }
+                finally {
+                    watchdog.stop();
+                }
+            })();
+            return {
+                [Symbol.asyncIterator]() {
+                    const abort = new AbortController();
+                    // Abort-first cancellation (see abortFirstIterator): aborting the connection unblocks a
+                    // generator suspended on a quiet stream read.
+                    return abortFirstIterator(openStream(abort), () => abort.abort());
+                },
+            };
+        },
+    };
+}
+/**
+ * The remote DATA plane: an `Agent` whose `invoke` drives `POST /control/invoke` on a serving
+ * process — paired with {@link connectSessionControl}, a client holds a full remote fastagent
+ * instance through the same two contracts local code uses. A REAL Agent, failure discipline
+ * included: SPEC MUST 2 forbids iteration throws, so every failure — transport (401/refused/
+ * dropped mid-stream), protocol, and the images precheck — becomes a terminal `failed` event
+ * (`retryable` from the HTTP status where one exists; network trouble is retryable). Breaking out
+ * of iteration disconnects the request, which cancels the run (SPEC cancellation semantics travel
+ * the wire). The invoke wire is text-only for now: a prompt with images fails visibly instead of
+ * silently dropping them (steer/follow_up on the control plane carry full Prompts).
+ */
+export function connectAgent(options) {
+    const { url, token, fetchFn = fetch } = options;
+    const base = url.replace(/\/$/, "");
+    const toFailed = (error) => {
+        if (error instanceof ControlRequestError) {
+            return { type: "failed", details: error.message, retryable: error.status === 429 || error.status >= 500 };
+        }
+        return { type: "failed", details: String(error), retryable: true }; // network-class: worth re-sending
+    };
+    // COMPILE-TIME drift guard (dispatch-wire parity): the invoke body carries exactly text (and
+    // rejects images visibly) — a new Prompt field must break THIS line and force a decision
+    // (carry it or reject it), never vanish on the wire while the client believes it was sent.
+    const _invokeDriftGuard = {};
+    void _invokeDriftGuard;
+    // Same guard for Scope: the body carries session only — a new Scope field must force a decision.
+    const _scopeDriftGuard = {};
+    void _scopeDriftGuard;
+    return {
+        invoke(scope, prompt) {
+            const abort = new AbortController();
+            const openStream = () => (async function* iterate() {
+                if (prompt.images && prompt.images.length > 0) {
+                    yield {
+                        type: "failed",
+                        details: "remote invoke does not carry images yet — send text, or invoke in-process",
+                        retryable: false,
+                    };
+                    return;
+                }
+                // Exactly-one-terminal discipline across the wire: a drop AFTER the server's terminal
+                // must not append a second one (catch included), and a stream that ends WITHOUT one
+                // (server died mid-run) must be closed with a failed — never a terminal-less end.
+                let terminalSeen = false;
+                // Armed BEFORE the fetch — the run's driver must not hang on a black-holed connect
+                // either (the connect await is a pending read; headers arriving disarm it).
+                const watchdog = idleWatchdog(abort);
+                watchdog.arm();
+                try {
+                    const res = await fetchFn(`${base}/control/invoke`, {
+                        method: "POST",
+                        headers: { authorization: `Bearer ${token}`, "content-type": "application/json" },
+                        body: JSON.stringify({ session: scope.session, text: prompt.text }),
+                        signal: abort.signal,
+                    });
+                    watchdog.disarm(); // headers arrived
+                    if (!res.ok) {
+                        watchdog.arm(); // the error body is a pending read too — see the events() twin
+                        const failure = toFailed(new ControlRequestError(res.status, await res.text()));
+                        watchdog.disarm();
+                        yield failure;
+                        return;
+                    }
+                    if (!res.body) {
+                        yield { type: "failed", details: "remote invoke: response has no body", retryable: true };
+                        return;
+                    }
+                    for await (const data of sseData(res.body, watchdog)) {
+                        let event;
+                        try {
+                            event = JSON.parse(data);
+                        }
+                        catch (parseError) {
+                            // Protocol drift (version skew, non-SSE middlebox), NOT transport trouble:
+                            // re-sending the same prompt cannot fix an unparseable stream — retryable: false.
+                            // (Guarded by terminalSeen: garbage AFTER the terminal must not add a second one.)
+                            if (!terminalSeen) {
+                                yield {
+                                    type: "failed",
+                                    details: `remote invoke: unparseable event on the stream (${String(parseError)})`,
+                                    retryable: false,
+                                };
+                            }
+                            return;
+                        }
+                        // Shape check, same discipline as the events plane: `data: null` / `data: 42` is
+                        // valid JSON but protocol drift — it must not TypeError into the catch below and be
+                        // misclassified as retryable network trouble.
+                        if (typeof event !== "object" || event === null || typeof event.type !== "string") {
+                            if (!terminalSeen) {
+                                yield {
+                                    type: "failed",
+                                    details: "remote invoke: non-event data on the stream — protocol mismatch?",
+                                    retryable: false,
+                                };
+                            }
+                            return;
+                        }
+                        if (event.type === "completed" || event.type === "failed")
+                            terminalSeen = true;
+                        yield event;
+                    }
+                    if (!terminalSeen) {
+                        yield { type: "failed", details: "remote invoke: stream ended without a terminal", retryable: true };
+                    }
+                }
+                catch (error) {
+                    if (abort.signal.aborted) {
+                        if (watchdog.stale() && !terminalSeen) {
+                            yield {
+                                type: "failed",
+                                details: `remote invoke: no bytes for ${SSE_IDLE_LIMIT_MS / 1000}s (heartbeats absent) — dead connection`,
+                                retryable: true,
+                            };
+                        }
+                        return; // the consumer walked away — cancellation, not an error
+                    }
+                    if (!terminalSeen)
+                        yield toFailed(error);
+                }
+                finally {
+                    watchdog.stop();
+                }
+            })();
+            // ONE stream per invoke, like a local async generator (which is its own iterator): a second
+            // iteration must never re-POST — that would silently start a second run with the same prompt.
+            // Abort-first cancellation (see abortFirstIterator): disconnect = cancel the run, even
+            // while suspended on a quiet read.
+            const iterator = abortFirstIterator(openStream(), () => abort.abort());
+            return {
+                [Symbol.asyncIterator]() {
+                    return iterator;
+                },
+            };
+        },
+    };
+}
+/** Minimal SSE reader: yields each `data:` payload; ignores comments (heartbeats) and other
+ *  fields. The explicit reader loop (not for-await) exists for the watchdog: armed strictly
+ *  around each pending read, so only "we are listening and nothing arrives" counts as idle — a
+ *  consumer pausing at a yield leaves the watch disarmed (see {@link ReadWatch}). */
+async function* sseData(body, watch) {
+    const decoder = new TextDecoder();
+    let buffer = "";
+    const reader = body.getReader();
+    try {
+        for (;;) {
+            watch?.arm(); // a read is pending — the idle clock may run
+            const { done, value } = await reader.read();
+            watch?.disarm(); // bytes (ANY bytes — heartbeats included) or a clean end arrived
+            if (done)
+                return;
+            // SSE permits CRLF line endings (proxies/other servers may produce them); normalize AFTER
+            // appending so a \r\n split across chunks still collapses once its second half arrives.
+            buffer = (buffer + decoder.decode(value, { stream: true })).replace(/\r\n/g, "\n");
+            let sep = buffer.indexOf("\n\n");
+            while (sep !== -1) {
+                const block = buffer.slice(0, sep);
+                buffer = buffer.slice(sep + 2);
+                const data = block
+                    .split("\n")
+                    .filter((line) => line.startsWith("data:"))
+                    .map((line) => line.slice(5).trimStart())
+                    .join("\n");
+                if (data !== "")
+                    yield data;
+                sep = buffer.indexOf("\n\n");
+            }
+        }
+    }
+    finally {
+        reader.releaseLock();
+    }
+}

package/dist/session.d.ts

@@ -0,0 +1,265 @@
+/**
+ * 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.
+ *
+ * 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.
+ */
+import type { Json, Prompt } from "./agent.ts";
+export interface SessionControl {
+    capabilities(): SessionCapabilities;
+    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
+     *  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?: {
+        since?: string;
+    }): Promise<SessionEntries>;
+    events(session: string): AsyncIterable<SessionEvent>;
+    dispatch(session: string, command: SessionCommand): Promise<SessionResult>;
+}
+/**
+ * Static support declaration, two kinds of flag:
+ * - COMMAND GATES (`steering`, `followUp`, `manualCompaction`, `modelSelection`, `thinkingLevel`):
+ *   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.
+ * `state`/`entries`/`events` are mandatory (the reconnect contract) and deliberately absent here.
+ */
+export interface SessionCapabilities {
+    steering: boolean;
+    followUp: boolean;
+    manualCompaction: boolean;
+    modelSelection: false | {
+        allowedModels: string[];
+    };
+    thinkingLevel: false | {
+        allowedLevels: string[];
+    };
+    toolProgress: boolean;
+    usage: boolean;
+}
+/** 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`)
+ *  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. */
+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. */
+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. */
+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
+ *  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
+ *  command may succeed on retry (the state-dependent "nothing to compact" has its own code,
+ *  {@link NOTHING_TO_COMPACT_CODE}). */
+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. */
+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}.) */
+export declare const RUN_COMMAND_FAILED_CODE = "run_command_failed";
+/** Six 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;
+};
+/**
+ * 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.
+ */
+export type SessionResult = {
+    ok: true;
+    runId?: string;
+} | {
+    ok: false;
+    error: {
+        code: string;
+        message: string;
+        retryable: boolean;
+    };
+};
+export interface SessionState {
+    /** `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";
+    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. */
+    model?: string;
+    thinkingLevel?: string;
+    pending: {
+        steering: number;
+        followUp: number;
+    };
+    usage?: {
+        inputTokens: number;
+        outputTokens: number;
+        cacheReadTokens?: number;
+        cacheWriteTokens?: number;
+        cost?: number;
+        contextTokens?: number;
+        contextWindow?: number;
+    };
+    leafEntryId?: string;
+}
+export interface SessionEntries {
+    entries: SessionEntry[];
+    leafEntryId?: string;
+}
+/** A durable append-only session record. `kind` guarantees a minimum vocabulary of
+ *  "user" | "assistant" | "tool"; engine-specific kinds beyond it MUST be skippable. */
+export interface SessionEntry {
+    id: string;
+    parentId?: string;
+    timestamp: number;
+    kind: string;
+    data: Json;
+}
+/** Semantic-only: no sequence, no epoch, no session id — in-process the stream is lossless and
+ *  ordered, and those concerns belong to the transport envelope (design §13). Consumers MUST
+ *  forward or ignore unknown event types; the vocabulary is additive. */
+export interface SessionEvent<TType extends string = string, TData extends Json = Json> {
+    type: TType;
+    timestamp: number;
+    /** Present on run-scoped events. */
+    runId?: string;
+    data: TData;
+}
+export type RunStartedEvent = SessionEvent<"run_started", Record<never, never>> & {
+    runId: string;
+};
+export type RunSettledEvent = SessionEvent<"run_settled", {
+    status: "completed" | "failed" | "aborted";
+    error?: {
+        code?: string;
+        message: string;
+        retryable: boolean;
+    };
+}> & {
+    runId: string;
+};
+export type MessageStartedEvent = SessionEvent<"message_started", Record<never, never>> & {
+    runId: string;
+};
+export type MessageDeltaEvent = SessionEvent<"message_delta", {
+    channel: "text" | "thinking";
+    delta: string;
+}> & {
+    runId: string;
+};
+export type MessageFinishedEvent = SessionEvent<"message_finished", Record<never, never>> & {
+    runId: string;
+};
+export type ToolStartedEvent = SessionEvent<"tool_started", {
+    id: string;
+    name: string;
+    args: Json;
+}> & {
+    runId: string;
+};
+/** Replace semantics: `partialResult` is the accumulated snapshot so far, not a delta. */
+export type ToolProgressEvent = SessionEvent<"tool_progress", {
+    id: string;
+    name: string;
+    partialResult: Json;
+}> & {
+    runId: string;
+};
+export type ToolFinishedEvent = SessionEvent<"tool_finished", {
+    id: string;
+    isError: boolean;
+    content: Json;
+}> & {
+    runId: string;
+};
+/** Normalized live queue depths for the active run (L1). */
+export type QueueChangedEvent = SessionEvent<"queue_changed", {
+    steering: number;
+    followUp: number;
+}> & {
+    runId: string;
+};
+/** A boundary mutation changed durable session state (L2; no runId — boundary mutations happen
+ *  between runs). */
+export type StateChangedEvent = SessionEvent<"state_changed", {
+    model?: string;
+    thinkingLevel?: 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
+ *  deliberate stop (run/compaction symmetry with `run_settled{status: "aborted"}`: a client's own
+ *  abort is not a failure). In the failure and aborted cases nothing durable landed. Automatic
+ *  overflow compaction stays inside its run's activity window and does not emit these. */
+export type CompactionStartedEvent = SessionEvent<"compaction_started", Record<never, never>>;
+export type CompactionFinishedEvent = SessionEvent<"compaction_finished", {
+    summary?: string;
+    error?: string;
+    aborted?: boolean;
+}>;
+/** A transient provider failure scheduled a summarization retry backoff (auto-compaction /
+ *  branch summaries inside a run — `runId` present — or a manual `compact` at a boundary — no
+ *  `runId`). Explains a quiet gap that would otherwise read as a hang. Deliberately unclosed:
+ *  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";
+    attempt: number;
+    maxAttempts: number;
+    delayMs: number;
+    error: string;
+}>;
+/**
+ * The serving process failed outside a normal run outcome (fail visibly). Emitted by TRANSPORT
+ * adapters (design §13) when they lose the backend before ending a remote stream — an in-process
+ * embedding cannot produce it (a dead process has no one left to emit), so it is deliberately NOT
+ * part of {@link KnownSessionEvent}: a local L0 client would be handling a signal that cannot occur.
+ */
+export type ServingErrorEvent = SessionEvent<"serving_error", {
+    message: string;
+}>;
+/** Every event the in-process observation plane emits today: L0, L1 `queue_changed`, and the L2
+ *  events (`state_changed`, `compaction_*`, `retry_scheduled`). Remaining L2 events (turn_*) are
+ *  future vocabulary; {@link ServingErrorEvent} arrives with the transport adapter. */
+export type KnownSessionEvent = RunStartedEvent | RunSettledEvent | MessageStartedEvent | MessageDeltaEvent | MessageFinishedEvent | ToolStartedEvent | ToolProgressEvent | ToolFinishedEvent | QueueChangedEvent | StateChangedEvent | CompactionStartedEvent | CompactionFinishedEvent | RetryScheduledEvent;

package/dist/session.js

@@ -0,0 +1,37 @@
+/** Stable `SessionResult.error.code` for a command the implementation does not support. */
+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. */
+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. */
+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. */
+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
+ *  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
+ *  command may succeed on retry (the state-dependent "nothing to compact" has its own code,
+ *  {@link NOTHING_TO_COMPACT_CODE}). */
+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. */
+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}.) */
+export const RUN_COMMAND_FAILED_CODE = "run_command_failed";

package/dist/slack.d.ts

@@ -0,0 +1,2 @@
+/** `@fastagent-sh/fastagent/slack` — the first-party Slack Events API bot-channel surface. */
+export { slackChannel, defaultSlackRoute, slackEnvelope, verifySlackSignature, type SlackChannelOptions, type SlackEventEnvelope, type SlackFile, type SlackMessageEvent, type SlackRendering, type SlackRoute, type SlackFailure, } from "./channels/slack/slack.ts";

package/dist/slack.js

@@ -0,0 +1,2 @@
+/** `@fastagent-sh/fastagent/slack` — the first-party Slack Events API bot-channel surface. */
+export { slackChannel, defaultSlackRoute, slackEnvelope, verifySlackSignature, } from "./channels/slack/slack.js";