@fastagent-sh/fastagent 0.21.0 → 0.22.0

package/dist/session-remote.d.ts

@@ -1,58 +1,47 @@
-/**
- * The remote `SessionControl` — the client half of the HTTP + SSE transport
- * (docs/design/session-control.md §13). Engine- and server-neutral: speaks only the wire protocol
- * `createControlPlane` serves (HTTP JSON + SSE with the {sessionId, epoch, seq, event} envelope) and
- * re-exposes the SAME `SessionControl` interface, so local and remote consumers are isomorphic —
- * client code does not change when the agent moves out of process.
- *
- * Envelope consumption is internal: a seq gap (loss in transit on this connection) — and any
- * mid-stream transport failure, a server restart included (its connections drop) — THROWS from
- * the events iterator, so the consumer's failure handling and budget own it; only the consumer's
- * own detach reads as a clean end. Recovery is the standard reconnect steps (`entries({ since })`
- * → `state()` → resubscribe), exactly as after any disconnect. The envelope's `epoch` is
- * informational for consumers that correlate ACROSS connections — within one connection it cannot
- * change, so this client does not compare it. Nothing here retries silently: a broken stream is
- * visible as a thrown iteration error, a failed request as a rejected promise.
- */
+/** The remote `SessionControl` — the client half of the HTTP + SSE transport (docs/design/session-control.md §13). */
 import type { Agent } from "./agent.ts";
 import { type SessionControl } from "./session.ts";
-/** 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. */
+/** A control request the server answered with a non-2xx status. */
 export declare class ControlRequestError extends Error {
     readonly status: number;
-    /** The plane's own error code, when the reply carried one (`sessions()` is the only read that
-     *  does today — design §13). Absent for a plain-text rejection (401) or a proxy's page: a caller
-     *  distinguishing "this deployment cannot list sessions" from "the endpoint is unreachable" reads
-     *  THIS, not the status. */
+    /**
+     * The plane's own error code, when the reply carried one (`sessions()` is the only read that does today — design
+     * §13).
+     */
     readonly code?: string;
-    constructor(status: number, body: string, code?: string);
+    /**
+     * Whether re-sending is worth it, as the plane itself answered — the same question `SessionResult.retryable`
+     * answers for a write, carried here because a throwing read has no result to put it in. Absent when the reply
+     * declared no opinion; a caller then has only the status.
+     */
+    readonly retryable?: boolean;
+    constructor(status: number, body: string, declared?: {
+        code?: string;
+        retryable?: boolean;
+    });
 }
-/** Connection parameters shared by BOTH remote planes (`connectSessionControl` and
- *  `connectAgent`) — plane-neutral on purpose: one endpoint, one token, two contracts. */
+/**
+ * Connection parameters shared by BOTH remote planes (`connectSessionControl` and `connectAgent`) — plane-neutral on
+ * purpose: one endpoint, two contracts.
+ */
 export interface RemoteEndpointOptions {
-    /** Base URL of the serving process (e.g. `http://127.0.0.1:8787`); `/control/*` is appended. */
+    /**
+     * Base URL of the serving process (e.g. `http://127.0.0.1:8787`). fastagent serves it unauthenticated — point this
+     * at whatever fronts it (a gateway, an SSH tunnel, a private network address), not at a public port.
+     */
     url: string;
-    /** The shared bearer secret (`<stateRoot>/control.json` on the serving machine). */
-    token: string;
-    /** Injectable for tests. Defaults to global fetch. */
+    /**
+     * The transport seam. fastagent authenticates nothing, so whatever fronts the serve is what a caller has to
+     * satisfy: wrap `fetch` here to add a gateway credential, refresh it, sign the request, or pin a client
+     * certificate — a static header cannot express the refresh an IdP proxy needs. Tests inject a fake through the
+     * same seam.
+     */
     fetchFn?: typeof fetch;
 }
-/**
- * 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 declare function connectSessionControl(options: RemoteEndpointOptions): Promise<SessionControl>;
 /**
- * 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).
+ * The remote DATA plane: an `Agent` whose `invoke` drives `POST /invoke` on a serving process. A real Agent,
+ * failure discipline included — SPEC MUST 2 forbids iteration throws, so transport, protocol and precheck failures
+ * all become `failed` events.
  */
 export declare function connectAgent(options: RemoteEndpointOptions): Agent;