@anvia/client 1.6.0 → 1.8.0

package/README.md

@@ -75,6 +75,26 @@ These committed progress events are separate from token-delta chat streams.
 
 See the [durable HTTP guide](../../docs/packages/durable.md#http-server-and-client).
 
+### Chat UI transport
+
+The optional `@anvia/client/durable-chat` entrypoint exports `createDurableChatTransport`, which
+adapts a durable endpoint to the `ClientTransport` contract used by `useChat` from `@anvia/react`
+and the `@anvia/react-ui` primitives. Create one transport per chat session; the agent, session and
+request identity live there, not in an individual message request.
+
+```ts
+const transport = createDurableChatTransport({ client, agentId, sessionId });
+const chat = useChat({ transport });
+```
+
+The adapter submits the last user message with `enqueue: true` by default, maps durable journal
+events to `anvia.client.v3` frames, routes interaction responses to the run that produced them, and
+uses the durable run id and sequence as `{ streamId, after }` for resume. Aborting the subscription
+detaches only; use `transport.controller.cancel()`, `retry()`, `resolveTool()` or
+`reattach(runId, after)` for explicit run control. A busy session is reported as
+`DurableBusyError` with the run to reattach to. Client history is discarded in favour of the
+durable transcript, so `regenerate()` and `reset()` are approximate; thread lists are not covered.
+
 `DurableClient` also exposes `submitGraph`, `listGraphs`, `graphSnapshot`, `streamGraph`, and
 `cancelGraph`. Graph snapshots contain renderable nodes/edges and explicit waiting reasons.
 Use each node's `runId` with the existing response/retry/reconciliation methods. Graph streams

package/dist/durable-chat.d.ts

@@ -0,0 +1,53 @@
+import { DurableClient } from "./durable.js";
+import { f as ClientStreamCursor, g as ClientStreamRequest, v as ClientTransport } from "./types-Bt4tUcST.js";
+import { ToolResultOutput } from "@anvia/core/completion";
+/**
+ * Thrown when a submission is rejected because the session already has unfinished work (HTTP 409).
+ * `runId` is that run when it could be read back from the session; `undefined` when the lookup
+ * failed. Reattach to `runId` instead of submitting again. Aborting a stream never raises this.
+ */
+export declare class DurableBusyError extends Error {
+  readonly runId: string | undefined;
+  readonly code: "session_busy";
+  constructor(runId: string | undefined, message?: string);
+}
+/** Methods the adapter needs. A structural subset of `DurableClient`, so tests can fake it. */
+export type DurableChatClient = Pick<DurableClient, "submit" | "stream" | "snapshot" | "respond" | "resolveTool" | "retry" | "cancel" | "listRuns"> & Partial<Pick<DurableClient, "resolveMemoryWrite">>;
+/**
+ * Run controls that `useChat` does not expose. `stop()` only aborts the subscription; cancellation
+ * is always this explicit `cancel()`.
+ */
+export type DurableChatController = {
+  /** Run last submitted or reattached. Undefined before the first successful send. */
+  readonly activeRunId: string | undefined;
+  /** Point later interaction responses and `send({ resume })` at an existing run. */
+  reattach(runId: string, after?: number): void;
+  cancel(runId?: string): Promise<void>;
+  retry(runId?: string): Promise<void>;
+  resolveTool(operationId: string, output: ToolResultOutput, runId?: string): Promise<void>;
+  /** Settle a blocked recorded memory write: `applied` says the store holds it, `discarded` drops it. */
+  resolveMemoryWrite(operationKey: string, resolution: "applied" | "discarded", runId?: string): Promise<void>;
+};
+export type CreateDurableChatTransportOptions = {
+  client: DurableChatClient;
+  agentId: string;
+  sessionId: string;
+  /** Defaults to a UUID per submission. Return a stable id to deduplicate one prompt. */
+  requestId?: () => string;
+  /** Queue behind unfinished session work instead of failing. Defaults to true. */
+  enqueue?: boolean;
+};
+export type DurableChatTransport = ClientTransport<ClientStreamRequest> & {
+  readonly controller: DurableChatController;
+};
+/**
+ * Transport `useChat` can pass to talk to `@anvia/durable`.
+ *
+ * Only the last user message of a `messages` request is submitted; durable keeps the transcript,
+ * so the rest of the client history is discarded. An `interaction_response` is delivered to the
+ * remembered run and then the stream resumes from the last applied sequence. Abort detaches the
+ * SSE subscription and does not cancel the run.
+ */
+export declare function createDurableChatTransport(options: CreateDurableChatTransportOptions): DurableChatTransport;
+export type { ClientStreamCursor };
+//# sourceMappingURL=durable-chat.d.ts.map

package/dist/durable-chat.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"durable-chat.d.ts","names":[],"sources":["../src/durable-chat.ts"],"mappings":";;;;;;;;qBA2Ba,yBAAyB;WAIzB;WAHF;EAGE,YAAA,2BACT;;;YAiBQ,oBAAoB,KAC9B,iHAIA,QAAQ,KAAK;;;;;YAMH;;WAED;;EAET,SAAS,eAAe;EACxB,OAAO,iBAAiB;EACxB,MAAM,iBAAiB;EACvB,YAAY,qBAAqB,QAAQ,kBAAkB,iBAAiB;;EAE5E,mBACE,sBACA,qCACA,iBACC;;YAGO;EACV,QAAQ;EACR;EACA;;EAEA;;EAEA;;YAGU,uBAAuB,gBAAgB;WACxC,YAAY;;;;;;;;;;wBAkBP,2BACd,SAAS,oCACR"}