eve 0.83.2 → 0.84.0

package/dist/src/client/open-stream.d.ts

@@ -1,5 +1,5 @@
-import type { MessageStreamEvent } from "#protocol/message.js";
-import type { MessageStreamVersion } from "#protocol/message-version.js";
+import type { SessionStreamEvent } from "#protocol/session-event.js";
+import type { StoredLine } from "#protocol/session-events/envelope.js";
 import type { ClientRedirectPolicy, StreamReconnectPolicy } from "#client/types.js";
 interface RetryPolicy {
     readonly baseDelayMs: number;
@@ -7,19 +7,29 @@ interface RetryPolicy {
     readonly maxDelayMs: number;
 }
 interface ResolvedStreamReconnectPolicy {
+    /** False when the caller owns cursor recovery: one connection, then stop. */
+    readonly reconnect: boolean;
     readonly retryableErrorStatuses: ReadonlySet<number>;
-    readonly streamIdleReconnectPolicy: RetryPolicy;
     readonly streamOpenReconnectPolicy: RetryPolicy;
 }
+/** Backoff between reconnects after a transport failure. Following readers retry forever. */
+export declare const RECONNECT_BACKOFF: {
+    readonly baseDelayMs: 250;
+    readonly maxDelayMs: 5000;
+};
+export declare const DEFAULT_STREAM_RECONNECT_POLICY: ResolvedStreamReconnectPolicy;
+export declare function isRetryableStreamError(error: unknown, statuses?: ReadonlySet<number>): boolean;
 /**
  * Internal configuration for following a durable event stream.
  */
 interface FollowStreamInput {
+    /** Validates reader provenance before consuming any stream data. */
+    readonly onOpen?: (headers: Headers) => void;
+    /** Committed source progress, including lines that materialize no recognized events. */
+    readonly onPosition?: (position: number) => void;
     /** Called once after consuming the durable tail captured when the connection opens. */
     readonly onCaughtUp?: () => void;
-    readonly host: string;
-    /** Keep following empty streams unless the caller configures an idle retry limit. */
-    readonly keepAlive?: boolean;
+    readonly baseUrl: string;
     readonly resolveReconnectPolicy?: () => StreamReconnectPolicy | undefined;
     readonly streamReconnectPolicy?: StreamReconnectPolicy;
     /** @internal Test override for reconnecting an open stream that stops producing bytes. */
@@ -28,7 +38,9 @@ interface FollowStreamInput {
     readonly redirect?: ClientRedirectPolicy;
     /** eve stream route path, such as a session stream or a parent-origin subagent stream. */
     readonly path: string;
+    readonly searchParams?: Readonly<Record<string, string>>;
     readonly signal?: AbortSignal;
+    /** The position of the first line to read. Negative values count back from the tail. */
     readonly startIndex: number;
     /** Follow the live stream after the durable tail (default). `false` bounds the read at the tail. */
     readonly follow?: boolean;
@@ -37,28 +49,43 @@ interface FollowStreamInput {
 interface OpenStreamInput extends FollowStreamInput {
     readonly requestTailIndex?: boolean;
 }
+/** One stored line and its position. A line this version can't read has `line: undefined`. */
+export interface FollowedLine {
+    readonly line: StoredLine | undefined;
+    readonly position: number;
+}
 /**
- * Follows one durable event stream route from an absolute cursor,
- * transparently reconnecting whenever the transport ends.
+ * Follows one durable stream route from a position, reconnecting as the transport ends.
  *
- * Transport endings reconnect from the advanced cursor. Progress resets the
- * idle budget; repeated empty streams eventually stop the follow. A
- * `session.completed` or `session.failed` event ends the follow, since a
- * session records nothing after it; callers own turn-boundary handling.
- * Negative tail-relative cursors use one connection because they cannot be
- * advanced safely.
+ * A reader counts positions from its cursor, one per stored line, and jumps forward at each
+ * position marker. `stream.ended` stops the follow; a lease end reconnects at once; anything
+ * else is a transport failure, retried with capped backoff. Readers that follow retry forever,
+ * and decide to stop from what they read. A tail-relative cursor becomes a position on the first
+ * connection, from the tail the server reports.
  *
- * With `follow: false`, the first connection fixes the bound: the iterator
- * yields events until the cursor passes that tail, reconnecting as needed,
- * then returns instead of following.
+ * With `follow: false`, the first connection fixes the bound: the iterator yields lines until
+ * the cursor passes that tail, reconnecting as needed, then returns instead of following.
+ */
+export declare function followStreamLines(input: FollowStreamInput): AsyncGenerator<FollowedLine>;
+/** One v26 event read from a line, with the position to resume from once it's handled. */
+export interface FollowedEvent {
+    readonly event: SessionStreamEvent;
+    /**
+     * The cursor after this event: past its line once the line's last event is handled, at the
+     * line before then, so a resume re-reads the rest of the line.
+     */
+    readonly cursor: number;
+}
+/**
+ * Follows a stream route's v26 events: the records each line carries, rebuilt as v26 readers
+ * expect them. Kept while v26 event types ride inside lines.
  */
-export declare function followStreamIterable(input: FollowStreamInput): AsyncGenerator<MessageStreamEvent>;
+export declare function followStreamIterable(input: FollowStreamInput): AsyncGenerator<FollowedEvent>;
 /** An opened connection: the response body plus the tail index from the response header, if any. */
 interface OpenedStream {
+    readonly headers: Headers;
     readonly body: ReadableStream<Uint8Array>;
     close(): void;
-    readonly controlVersion: "1" | undefined;
-    readonly streamVersion: MessageStreamVersion;
     readonly tailIndex: number | undefined;
 }
 /**

package/dist/src/client/open-stream.js

@@ -1 +1 @@
-import{ClientError,ClientSessionStrandedError,createClientError}from"#client/client-error.js";import{EVE_STREAM_CONTROL_VERSION,EVE_STREAM_CONTROL_VERSION_QUERY,EVE_STREAM_TAIL_INDEX_HEADER}from"#protocol/message.js";import{createClientUrl}from"#client/url.js";import{throwIfAborted}from"#client/abort-signal.js";import{isStreamDisconnectError,readNdjsonStream}from"#client/ndjson.js";import{readMessageStreamVersion}from"#client/stream-version.js";const DEFAULT_STREAM_RECONNECT_POLICY={retryableErrorStatuses:new Set([404,409,425,500,502,503,504]),streamIdleReconnectPolicy:{baseDelayMs:250,maxAttempts:5,maxDelayMs:4e3},streamOpenReconnectPolicy:{baseDelayMs:250,maxAttempts:12,maxDelayMs:5e3}},NO_STREAM_RECONNECT_POLICY={...DEFAULT_STREAM_RECONNECT_POLICY,streamIdleReconnectPolicy:{...DEFAULT_STREAM_RECONNECT_POLICY.streamIdleReconnectPolicy,maxAttempts:0},streamOpenReconnectPolicy:{...DEFAULT_STREAM_RECONNECT_POLICY.streamOpenReconnectPolicy,maxAttempts:1}};function resolveRetryPolicy(e,t){return{...t,...e}}function resolveStreamReconnectPolicy(e,t=!1){if(e&&`reconnect`in e&&e.reconnect===!1)return NO_STREAM_RECONNECT_POLICY;let n=e;return{retryableErrorStatuses:n?.retryableErrorStatuses?new Set(n.retryableErrorStatuses):DEFAULT_STREAM_RECONNECT_POLICY.retryableErrorStatuses,streamIdleReconnectPolicy:resolveRetryPolicy(n?.streamIdleReconnectPolicy,{...DEFAULT_STREAM_RECONNECT_POLICY.streamIdleReconnectPolicy,maxAttempts:t?1/0:DEFAULT_STREAM_RECONNECT_POLICY.streamIdleReconnectPolicy.maxAttempts}),streamOpenReconnectPolicy:resolveRetryPolicy(n?.streamOpenReconnectPolicy,DEFAULT_STREAM_RECONNECT_POLICY.streamOpenReconnectPolicy)}}async function*followStreamIterable(e){if(e.follow===!1&&e.startIndex<0)throw Error(`stream({ follow: false }) requires a nonnegative startIndex; a tail-relative cursor cannot be bounded.`);let resolvePolicy=()=>resolveStreamReconnectPolicy(e.resolveReconnectPolicy===void 0?e.streamReconnectPolicy:e.resolveReconnectPolicy(),e.keepAlive),t=resolvePolicy(),n=t.streamIdleReconnectPolicy,r=e.startIndex,i=n.baseDelayMs,a=0,o=!0,s,c=!1;for(;;){t=resolvePolicy(),n=t.streamIdleReconnectPolicy;let l;try{l=await openStreamBody({...e,retryPolicy:t,startIndex:r,requestTailIndex:(e.follow===!1||e.onCaughtUp!==void 0)&&s===void 0})}catch(t){if(e.signal?.aborted)return;throw t}if((e.follow===!1||e.onCaughtUp!==void 0)&&s===void 0&&(s=l.tailIndex,s===void 0))throw l.close(),Error(`stream({ follow: false }) requires the server to report the ${EVE_STREAM_TAIL_INDEX_HEADER} header. The agent may be running an older eve version.`);if(!c&&s!==void 0&&r>s&&(c=!0,e.onCaughtUp?.()),e.follow===!1&&s!==void 0&&r>s){l.close();return}let u=!1,d=!1;try{for await(let t of readNdjsonStream(l.body,{signal:e.signal,controlVersion:l.controlVersion,idleTimeoutMs:e.streamReadIdleTimeoutMs??15e3,onLeaseEnded:()=>{d=!0},streamVersion:l.streamVersion}))if(r+=1,u=!0,i=n.baseDelayMs,a=0,yield t,!c&&s!==void 0&&r>s&&(c=!0,e.onCaughtUp?.()),t.type===`session.failed`||t.type===`session.completed`||e.follow===!1&&s!==void 0&&r>s)return}catch(e){if(!isStreamDisconnectError(e))throw e}finally{l.close()}if(n=resolvePolicy().streamIdleReconnectPolicy,e.signal?.aborted||e.startIndex<0||n.maxAttempts===0)return;if(!d){if(!u&&!o&&(a+=1)>=n.maxAttempts||(o=!1,await sleep(i,e.signal),e.signal?.aborted))return;i=Math.min(i*2,n.maxDelayMs)}}}async function openStreamBody(e){let t=e.retryPolicy??resolveStreamReconnectPolicy(e.streamReconnectPolicy,e.keepAlive),n=t.streamOpenReconnectPolicy,r,i,a,o=n.baseDelayMs,s=e.startIndex>=0&&t.streamIdleReconnectPolicy.maxAttempts>0?EVE_STREAM_CONTROL_VERSION:void 0,c={};s!==void 0&&(c[EVE_STREAM_CONTROL_VERSION_QUERY]=s),e.startIndex!==0&&(c.startIndex=String(e.startIndex)),e.requestTailIndex===!0&&(c.includeTailIndex=`1`),e.follow===!1&&(c.follow=`false`);for(let l=0;l<n.maxAttempts;l+=1){throwIfAborted(e.signal);let u=createClientUrl(e.host,e.path,Object.keys(c).length>0?c:void 0),d=await e.resolveHeaders();throwIfAborted(e.signal);let f=new AbortController,p=e.signal?AbortSignal.any([e.signal,f.signal]):f.signal,m;try{m=await fetch(u,{cache:`no-store`,headers:d,redirect:e.redirect,signal:p})}catch(t){if(e.signal?.aborted||!isStreamDisconnectError(t)||l===n.maxAttempts-1)throw t;await sleep(o,e.signal),o=Math.min(o*2,n.maxDelayMs);continue}if(m.ok){if(!m.body)throw new ClientError(m.status,`Response body is null.`,m.headers);let e=!1;return{body:m.body,close:()=>{e||(e=!0,m.body?.cancel().catch(()=>{}),f.abort())},controlVersion:s,streamVersion:readMessageStreamVersion(m.headers),tailIndex:parseTailIndexHeader(m.headers)}}r=m.status,i=await m.text(),a=m.headers;let h=createClientError(m.status,i,m.headers);if(h instanceof ClientSessionStrandedError||!t.retryableErrorStatuses.has(m.status))throw h;l<n.maxAttempts-1&&(await sleep(o,e.signal),o=Math.min(o*2,n.maxDelayMs))}throw new ClientError(r??0,i??`Failed to open message stream.`,a)}function parseTailIndexHeader(e){let t=e.get(EVE_STREAM_TAIL_INDEX_HEADER);if(t===null||!/^-?\d+$/.test(t))return;let n=Number(t);return Number.isSafeInteger(n)?n:void 0}async function sleep(e,t){t?.aborted||await new Promise(n=>{let onAbort=()=>{clearTimeout(r),n()},r=setTimeout(()=>{t?.removeEventListener(`abort`,onAbort),n()},e);t?.addEventListener(`abort`,onAbort,{once:!0})})}export{followStreamIterable,openStreamBody,sleep};
+import{SessionNotActiveError}from"#channel/session-not-active-error.js";import{ClientError,ClientSessionStrandedError,createClientError}from"#client/client-error.js";import{createEventReader}from"#protocol/session-lines.js";import{EVE_STREAM_TAIL_INDEX_HEADER}from"#protocol/session-http.js";import{createClientUrl}from"#client/url.js";import{throwIfAborted}from"#client/abort-signal.js";import{isV26Line}from"#protocol/v26-lines.js";import{isStreamDisconnectError,readNdjsonStream}from"#client/ndjson.js";import{readMessageStreamVersion}from"#client/stream-version.js";const RECONNECT_BACKOFF={baseDelayMs:250,maxDelayMs:5e3},DEFAULT_STREAM_RECONNECT_POLICY={reconnect:!0,retryableErrorStatuses:new Set([404,409,425,500,502,503,504]),streamOpenReconnectPolicy:{baseDelayMs:250,maxAttempts:12,maxDelayMs:5e3}},NO_STREAM_RECONNECT_POLICY={...DEFAULT_STREAM_RECONNECT_POLICY,reconnect:!1,streamOpenReconnectPolicy:{...DEFAULT_STREAM_RECONNECT_POLICY.streamOpenReconnectPolicy,maxAttempts:1}};function isRetryableStreamError(e,t=DEFAULT_STREAM_RECONNECT_POLICY.retryableErrorStatuses){return e instanceof ClientSessionStrandedError?!1:SessionNotActiveError.is(e)?t.has(409):e instanceof ClientError?e.code!==`session_version_unsupported`&&t.has(e.status):isStreamDisconnectError(e)}function resolveRetryPolicy(e,t){return{...t,...e}}function resolveStreamReconnectPolicy(e){if(e&&`reconnect`in e&&e.reconnect===!1)return NO_STREAM_RECONNECT_POLICY;let t=e;return{reconnect:!0,retryableErrorStatuses:t?.retryableErrorStatuses?new Set(t.retryableErrorStatuses):DEFAULT_STREAM_RECONNECT_POLICY.retryableErrorStatuses,streamOpenReconnectPolicy:resolveRetryPolicy(t?.streamOpenReconnectPolicy,DEFAULT_STREAM_RECONNECT_POLICY.streamOpenReconnectPolicy)}}async function*followStreamLines(e){let resolvePolicy=()=>resolveStreamReconnectPolicy(e.resolveReconnectPolicy===void 0?e.streamReconnectPolicy:e.resolveReconnectPolicy()),t=e.follow===!1||e.onCaughtUp!==void 0,n=e.startIndex,r=RECONNECT_BACKOFF.baseDelayMs,i=0,a,o=!1,passedTail=()=>a!==void 0&&n>a,noteProgress=()=>(!o&&passedTail()&&(o=!0,e.onCaughtUp?.()),e.follow===!1&&passedTail());for(;;){let o=resolvePolicy(),s;try{s=await openStreamBody({...e,retryPolicy:o,startIndex:n,requestTailIndex:(t||n<0)&&a===void 0})}catch(t){if(e.signal?.aborted)return;throw t}if((t||n<0)&&a===void 0){if(a=s.tailIndex,a===void 0)throw s.close(),Error(`This read requires the server to report the ${EVE_STREAM_TAIL_INDEX_HEADER} header. The agent may be running an older eve version.`);n<0&&(n=Math.max(0,a+1+n))}try{e.onOpen?.(s.headers)}catch(e){throw s.close(),e}if(noteProgress()){s.close();return}let c=!1,l=!1;try{for await(let t of readNdjsonStream(s.body,{signal:e.signal,idleTimeoutMs:e.streamReadIdleTimeoutMs??3e4}))switch(t.kind){case`transport`:switch(t.record.$eve){case`position`:if(t.record.next>n&&(n=t.record.next),e.onPosition?.(n),noteProgress())return;break;case`stream.lease-ended`:l=!0;break;case`stream.ended`:c=!0}continue;case`unknown-transport`:continue;case`commit`:case`progress`:case`invalid`:{if(t.kind===`invalid`&&isV26Line(t.value))throw new ClientError(409,JSON.stringify({code:`session_version_unsupported`,error:`This session was started by an earlier eve version. Start a new session.`}));let a=n;if(n+=1,i=0,r=RECONNECT_BACKOFF.baseDelayMs,yield{line:t.kind===`invalid`?void 0:t.line,position:a},e.onPosition?.(n),noteProgress())return}}}catch(e){if(!isStreamDisconnectError(e))throw e}finally{s.close()}if(c||e.signal?.aborted||!resolvePolicy().reconnect)return;if(!l){if(i+=1,e.follow===!1&&i>=o.streamOpenReconnectPolicy.maxAttempts)throw Error(`The session stream kept disconnecting before the read reached its tail.`);if(await sleep(r,e.signal),e.signal?.aborted)return;r=Math.min(r*2,RECONNECT_BACKOFF.maxDelayMs)}}}async function*followStreamIterable(e){let t=createEventReader();for await(let{line:n,position:r}of followStreamLines(e)){if(n===void 0)continue;let e=t.read(n,r);for(let[t,n]of e.entries())yield{cursor:t===e.length-1?r+1:r,event:n}}}async function openStreamBody(e){let t=e.retryPolicy??resolveStreamReconnectPolicy(e.streamReconnectPolicy),n=t.streamOpenReconnectPolicy,r,i,a,o=n.baseDelayMs,s={...e.searchParams};e.startIndex!==0&&(s.startIndex=String(e.startIndex)),e.requestTailIndex===!0&&(s.includeTailIndex=`1`),e.follow===!1&&(s.follow=`false`);for(let c=0;c<n.maxAttempts;c+=1){throwIfAborted(e.signal);let l=createClientUrl(e.baseUrl,e.path,Object.keys(s).length>0?s:void 0),u=await e.resolveHeaders();throwIfAborted(e.signal);let d=new AbortController,f=e.signal?AbortSignal.any([e.signal,d.signal]):d.signal,p;try{p=await fetch(l,{cache:`no-store`,headers:u,redirect:e.redirect,signal:f})}catch(t){if(e.signal?.aborted||!isStreamDisconnectError(t)||c===n.maxAttempts-1)throw t;await sleep(o,e.signal),o=Math.min(o*2,n.maxDelayMs);continue}if(p.ok){if(!p.body)throw new ClientError(p.status,`Response body is null.`,p.headers);try{readMessageStreamVersion(p.headers)}catch(e){throw p.body.cancel().catch(()=>{}),d.abort(),e}let e=!1;return{headers:p.headers,body:p.body,close:()=>{e||(e=!0,p.body?.cancel().catch(()=>{}),d.abort())},tailIndex:parseTailIndexHeader(p.headers)}}r=p.status,i=await p.text(),a=p.headers;let m=createClientError(p.status,i,p.headers);if(!isRetryableStreamError(m,t.retryableErrorStatuses))throw m;c<n.maxAttempts-1&&(await sleep(o,e.signal),o=Math.min(o*2,n.maxDelayMs))}throw new ClientError(r??0,i??`Failed to open message stream.`,a)}function parseTailIndexHeader(e){let t=e.get(EVE_STREAM_TAIL_INDEX_HEADER);if(t===null||!/^-?\d+$/.test(t))return;let n=Number(t);return Number.isSafeInteger(n)?n:void 0}async function sleep(e,t){t?.aborted||await new Promise(n=>{let onAbort=()=>{clearTimeout(r),n()},r=setTimeout(()=>{t?.removeEventListener(`abort`,onAbort),n()},e);t?.addEventListener(`abort`,onAbort,{once:!0})})}export{DEFAULT_STREAM_RECONNECT_POLICY,RECONNECT_BACKOFF,followStreamIterable,followStreamLines,isRetryableStreamError,openStreamBody,sleep};

package/dist/src/client/optimistic-message-submissions.d.ts

@@ -1,24 +1,15 @@
-import type { EveAgentEventLog } from "#client/eve-agent-projection.js";
-import type { MessageStreamEvent } from "#protocol/message.js";
+import type { LocalSubmission } from "#client/conversation.js";
 import type { SendTurnPayload } from "#client/types.js";
-interface ReconciledSubmissions {
-    readonly alreadyProjected: boolean;
-    readonly event: Extract<MessageStreamEvent, {
-        readonly type: "message.received";
-    }>;
-    readonly ids: readonly string[];
-}
-/** Owns optimistic message projection and server-delivery reconciliation. */
+import type { SessionView } from "#protocol/session-projection/tables.js";
+/** Local message echoes until their deliveries arrive, including failed sends. */
 export declare class OptimisticMessageSubmissions {
     #private;
-    constructor(projections: readonly EveAgentEventLog[], optimistic: boolean);
+    constructor(show: (submissions: readonly LocalSubmission[]) => void, optimistic: boolean);
     reset(): void;
-    submit(input: SendTurnPayload, eventStartIndex: number, turnId?: string): string | undefined;
-    /** Re-echoes a submission whose payload `prepareSend` replaced, keeping its place in the stream. */
-    resubmit(submissionId: string | undefined, input: SendTurnPayload): string | undefined;
-    apply(event: MessageStreamEvent): ReconciledSubmissions | undefined;
-    correlate(submissionId: string | undefined, deliveryId: string | undefined, events: readonly MessageStreamEvent[]): ReconciledSubmissions | undefined;
-    fail(error: Error, submissionId?: string): void;
-    failAll(error: Error): void;
+    submit(input: SendTurnPayload, turnId?: string): string | undefined;
+    resubmit(id: string | undefined, input: SendTurnPayload): string | undefined;
+    correlate(id: string | undefined, deliveryId: string): void;
+    reconcile(view: SessionView): void;
+    fail(error: Error, id: string | undefined): void;
+    get awaitingReceipt(): boolean;
 }
-export {};

package/dist/src/client/optimistic-message-submissions.js

@@ -1 +1 @@
-import{createSubmissionId,summarizeUserContent}from"#client/eve-agent-store-helpers.js";var OptimisticMessageSubmissions=class{#e;#t;#n=[];constructor(e,t){this.#t=e,this.#e=t}reset(){this.#n=[]}submit(e,t,n){if(e.message===void 0)return;let r={createdAt:Date.now(),eventStartIndex:t,id:createSubmissionId(),message:summarizeUserContent(e.message),turnId:n,requiresDeliveryId:!0};if(this.#n=[...this.#n,r],this.#e)for(let e of this.#t)e.append({data:{createdAt:r.createdAt,message:r.message,submissionId:r.id,turnId:n},type:`client.message.submitted`});return r.id}resubmit(e,t){let n=this.#n.find(t=>t.id===e),r=t.message===void 0?void 0:summarizeUserContent(t.message);return n?.message===r?e:(n!==void 0&&this.#a([n.id]),this.submit(t,n?.eventStartIndex??0,n?.turnId))}apply(e){if(e.type!==`message.received`){for(let t of this.#t)t.append(e);return}let t=this.#r(e);if(t.length===0){for(let t of this.#t)t.append(e);return}return this.#i(t,e,!1)}correlate(e,t,n){if(e===void 0)return;this.#n=this.#n.map(n=>n.id===e?{...n,deliveryId:t,requiresDeliveryId:t!==void 0}:n);let r=this.#n.find(t=>t.id===e);if(r!==void 0)for(let t of n.slice(r.eventStartIndex)){if(t.type!==`message.received`)continue;let n=this.#r(t);if(n.some(t=>t.id===e))return this.#i(n,t,!0)}}fail(e,t){let n=t===void 0?this.#n[0]:this.#n.find(e=>e.id===t);if(n!==void 0){this.#n=this.#n.filter(e=>e.id!==n.id);for(let t of this.#t)t.replace(e=>e.type===`client.message.submitted`&&e.data.submissionId===n.id,{data:{createdAt:n.createdAt,error:{message:e.message},message:n.message,submissionId:n.id,turnId:n.turnId},type:`client.message.failed`})}}failAll(e){for(let t of this.#n)this.fail(e,t.id)}#r(e){return this.#n.filter(t=>t.deliveryId===void 0?!t.requiresDeliveryId:e.meta.deliveryIds?.includes(t.deliveryId)===!0)}#i(e,t,n){let r=e.map(e=>e.id);if(this.#a(r),!n)for(let e of this.#t)e.append(t);return{alreadyProjected:n,event:t,ids:r}}#a(e){let t=new Set(e);this.#n=this.#n.filter(e=>!t.has(e.id));for(let e of this.#t)e.remove(e=>e.type===`client.message.submitted`&&t.has(e.data.submissionId))}};export{OptimisticMessageSubmissions};
+import{summarizeMessage}from"#client/session-store-helpers.js";var OptimisticMessageSubmissions=class{#e;#t;#n=new Map;constructor(e,t){this.#t=e,this.#e=t}reset(){this.#n.clear(),this.#r()}submit(e,t){if(e.message===void 0)return;let n=crypto.randomUUID();return this.#n.set(n,{id:n,message:summarizeMessage(e.message),turnId:t}),this.#r(),n}resubmit(e,t){if(e===void 0)return this.submit(t);let n=this.#n.get(e);return t.message===void 0?this.#n.delete(e):this.#n.set(e,{...n,id:e,message:summarizeMessage(t.message)}),this.#r(),t.message===void 0?void 0:e}correlate(e,t){if(e===void 0)return;let n=this.#n.get(e);n!==void 0&&this.#n.set(e,{...n,deliveryId:t})}reconcile(e){for(let[t,n]of this.#n){let r=n.deliveryId===void 0?void 0:e.deliveries[n.deliveryId];n.turnId===void 0&&r?.turnId!==void 0&&this.#n.set(t,{...n,turnId:r.turnId}),r?.consumedAt===void 0?(r?.status===`settled`||e.session.status===`ended`)&&n.error===void 0&&this.fail(Error(r?.reason??`The message was not consumed.`),t):this.#n.delete(t)}this.#r()}fail(e,t){if(t===void 0)return;let n=this.#n.get(t);n!==void 0&&(this.#n.set(t,{...n,error:{message:e.message}}),this.#r())}get awaitingReceipt(){return[...this.#n.values()].some(e=>e.deliveryId===void 0&&e.error===void 0)}#r(){this.#t([...this.#n.values()].filter(e=>this.#e||e.error!==void 0))}};export{OptimisticMessageSubmissions};

package/dist/src/client/session-controls.d.ts

@@ -1,37 +1,34 @@
 import { type PrewarmSessionResult } from "#protocol/prewarm-session.js";
-import type { CancelSessionResult, ClearResult, ClientRedirectPolicy, CompactResult, ResetResult } from "#client/types.js";
-interface SessionControlContext {
-    readonly host: string;
-    readonly redirect?: ClientRedirectPolicy;
-    resolveHeaders(): Promise<Headers>;
-}
+import type { ClientRedirectPolicy } from "#client/types.js";
+import { type DeliveryReceipt } from "#protocol/delivery.js";
+import { createEveSessionCancelRoutePath, createEveSessionClearRoutePath, createEveSessionCompactRoutePath, createEveSessionResetRoutePath } from "#protocol/routes.js";
+declare const paths: {
+    cancel: typeof createEveSessionCancelRoutePath;
+    clear: typeof createEveSessionClearRoutePath;
+    compact: typeof createEveSessionCompactRoutePath;
+    reset: typeof createEveSessionResetRoutePath;
+};
 export declare function prewarmClientSession(input: {
-    readonly context: SessionControlContext;
+    readonly context: {
+        readonly baseUrl: string;
+        readonly redirect?: ClientRedirectPolicy;
+        resolveHeaders(): Promise<Headers>;
+    };
     readonly sessionId: string;
     readonly signal?: AbortSignal;
 }): Promise<PrewarmSessionResult>;
-export declare function cancelClientSession(input: {
-    readonly context: SessionControlContext;
-    readonly options?: {
-        readonly signal?: AbortSignal;
-        readonly turnId?: string;
+export declare function sendClientControl(input: {
+    readonly context: {
+        readonly baseUrl: string;
+        readonly redirect?: ClientRedirectPolicy;
+        resolveHeaders(): Promise<Headers>;
     };
+    readonly kind: keyof typeof paths;
     readonly sessionId: string;
-}): Promise<CancelSessionResult>;
-export declare function clearClientSession(input: {
-    readonly context: SessionControlContext;
-    readonly sessionId: string;
-}): Promise<ClearResult>;
-export declare function compactClientSession(input: {
-    readonly context: SessionControlContext;
-    readonly sessionId: string;
-}): Promise<CompactResult>;
-export declare function resetClientSession(input: {
-    readonly context: SessionControlContext;
     readonly options?: {
-        readonly reason?: string;
         readonly signal?: AbortSignal;
+        readonly turnId?: string | null;
+        readonly reason?: string;
     };
-    readonly sessionId: string;
-}): Promise<ResetResult>;
+}): Promise<DeliveryReceipt>;
 export {};

package/dist/src/client/session-controls.js

@@ -1 +1 @@
-import{createEveSessionCancelRoutePath,createEveSessionClearRoutePath,createEveSessionCompactRoutePath,createEveSessionResetRoutePath,createEveSessionRoutePath}from"#protocol/routes.js";import{createClientError}from"#client/client-error.js";import{createClientUrl}from"#client/url.js";import{PrewarmResponseSchema}from"#protocol/prewarm-session.js";import{CancelTurnResponseSchema}from"#protocol/cancel-turn.js";import{ClearResponseSchema}from"#protocol/clear-session.js";import{CompactResponseSchema}from"#protocol/compact-session.js";import{ResetResponseSchema}from"#protocol/reset-session.js";async function prewarmClientSession(e){let{payload:t}=await postJson({context:e.context,operation:`Prewarm`,path:createEveSessionRoutePath(e.sessionId),signal:e.signal}),n=PrewarmResponseSchema.safeParse(t);if(!n.success)throw Error(`Prewarm route returned an invalid response.`);return{status:n.data.status}}async function cancelClientSession(e){let{signal:t,...n}=e.options??{},{payload:r,response:i}=await postJson({body:n,context:e.context,operation:`Cancel`,path:createEveSessionCancelRoutePath(e.sessionId),signal:t}),a=CancelTurnResponseSchema.safeParse(r);if(!a.success||a.data.status===`accepted`&&a.data.sessionId!==e.sessionId)throw Error(`Cancel route returned an invalid response (${i.status}).`);return a.data.status===`accepted`?{sessionId:a.data.sessionId,status:`accepted`}:{status:`no_active_turn`}}async function clearClientSession(e){let{payload:t}=await postJson({context:e.context,operation:`Clear`,path:createEveSessionClearRoutePath(e.sessionId)}),n=ClearResponseSchema.safeParse(t);if(!n.success||n.data.status===`accepted`&&n.data.sessionId!==e.sessionId)throw Error(`Clear route returned an invalid response.`);return n.data.status===`accepted`?{sessionId:n.data.sessionId,status:`accepted`}:{status:`no_active_session`}}async function compactClientSession(e){let{payload:t}=await postJson({context:e.context,operation:`Compact`,path:createEveSessionCompactRoutePath(e.sessionId)}),n=CompactResponseSchema.safeParse(t);if(!n.success||n.data.status===`accepted`&&n.data.sessionId!==e.sessionId)throw Error(`Compact route returned an invalid response.`);return n.data.status===`accepted`?{sessionId:n.data.sessionId,status:`accepted`}:{status:`no_active_session`}}async function resetClientSession(e){let{signal:t,...n}=e.options??{},{payload:r}=await postJson({body:n,context:e.context,operation:`Reset`,path:createEveSessionResetRoutePath(e.sessionId),signal:t}),i=ResetResponseSchema.safeParse(r);if(!i.success||i.data.status===`reset`&&i.data.previousSessionId!==e.sessionId)throw Error(`Reset route returned an invalid response.`);return i.data.status===`reset`?{previousSessionId:i.data.previousSessionId,status:`reset`}:{status:`no_active_session`}}async function postJson(e){let t=await e.context.resolveHeaders();t.set(`content-type`,`application/json`);let n=await fetch(createClientUrl(e.context.host,e.path),withRedirectPolicy({body:e.body===void 0?void 0:JSON.stringify(e.body),headers:t,method:`POST`,signal:e.signal},e.context.redirect)),r=await n.text();if(!n.ok)throw createClientError(n.status,r,n.headers);try{return{payload:JSON.parse(r),response:n}}catch{throw Error(`${e.operation} route returned invalid JSON (${n.status}).`)}}function withRedirectPolicy(e,t){return t===void 0?e:{...e,redirect:t}}export{cancelClientSession,clearClientSession,compactClientSession,prewarmClientSession,resetClientSession};
+import{createEveSessionCancelRoutePath,createEveSessionClearRoutePath,createEveSessionCompactRoutePath,createEveSessionResetRoutePath,createEveSessionRoutePath}from"#protocol/routes.js";import{createClientError}from"#client/client-error.js";import{createClientUrl}from"#client/url.js";import{PrewarmResponseSchema}from"#protocol/prewarm-session.js";import{DeliveryResponseSchema}from"#protocol/delivery.js";const paths={cancel:createEveSessionCancelRoutePath,clear:createEveSessionClearRoutePath,compact:createEveSessionCompactRoutePath,reset:createEveSessionResetRoutePath};async function prewarmClientSession(e){let t=await fetch(createClientUrl(e.context.baseUrl,createEveSessionRoutePath(e.sessionId)),{headers:await e.context.resolveHeaders(),method:`POST`,signal:e.signal,redirect:e.context.redirect}),n=await t.text();if(!t.ok)throw createClientError(t.status,n,t.headers);let r;try{r=JSON.parse(n)}catch{throw Error(`Prewarm route returned invalid JSON (${t.status}).`)}let i=PrewarmResponseSchema.safeParse(r);if(!i.success)throw Error(`Prewarm route returned an invalid response.`);return{status:i.data.status}}async function sendClientControl(e){let{signal:t,turnId:n,reason:r}=e.options??{},i=e.kind===`cancel`?{turnId:n}:e.kind===`reset`?{reason:r}:{},a=await e.context.resolveHeaders();a.set(`content-type`,`application/json`);let o=await fetch(createClientUrl(e.context.baseUrl,paths[e.kind](e.sessionId)),{body:JSON.stringify(i),headers:a,method:`POST`,signal:t,redirect:e.context.redirect}),s=await o.text();if(!o.ok)throw createClientError(o.status,s,o.headers);let c;try{c=JSON.parse(s)}catch{throw Error(`${e.kind} route returned invalid JSON (${o.status}).`)}let l=DeliveryResponseSchema.safeParse(c);if(!l.success||l.data.sessionId!==e.sessionId)throw Error(`${e.kind} route returned an invalid delivery receipt.`);return{sessionId:l.data.sessionId,deliveryId:l.data.deliveryId}}export{prewarmClientSession,sendClientControl};

package/dist/src/client/session-event-stream.d.ts

@@ -1,30 +1,19 @@
+import type { SessionStreamEvent } from "#protocol/session-event.js";
 import { type ClientSession } from "#client/session.js";
-import type { MessageStreamEvent } from "#protocol/message.js";
-import type { StreamOptions } from "#client/types.js";
+import type { SessionStreamOptions } from "#client/types.js";
 export interface SessionEventStreamOptions {
     readonly startIndex?: number;
-    readonly catchUp?: boolean;
     readonly headers?: Readonly<Record<string, string>>;
-    readonly streamReconnectPolicy?: StreamOptions["streamReconnectPolicy"];
-    readonly onEvent: (event: MessageStreamEvent) => void;
+    readonly streamReconnectPolicy?: SessionStreamOptions["streamReconnectPolicy"];
+    readonly onEvent: (event: SessionStreamEvent, historical: boolean) => void;
     readonly onError: (error: unknown) => void;
 }
-/** One transport, with short-lived readers for catch-up and turn completion. */
+/** One continuously folded UI transport, independent of explicit Delivery reads. */
 export declare class SessionEventStream {
     #private;
     readonly caughtUp: Promise<void>;
     constructor(session: ClientSession, options: SessionEventStreamOptions);
-    subscribe(signal?: AbortSignal): SessionEventReader;
     get ended(): boolean;
     setOptions(options: Pick<SessionEventStreamOptions, "headers" | "streamReconnectPolicy">): void;
     close(): void;
 }
-export declare class SessionEventReader implements AsyncIterable<MessageStreamEvent>, Disposable {
-    #private;
-    constructor(unsubscribe: () => void, signal?: AbortSignal);
-    push(event: MessageStreamEvent): void;
-    end(error?: unknown): void;
-    [Symbol.dispose](): void;
-    discard(): void;
-    [Symbol.asyncIterator](): AsyncGenerator<MessageStreamEvent>;
-}

package/dist/src/client/session-event-stream.js

@@ -1 +1 @@
-import{followClientSession}from"#client/session.js";var SessionEventStream=class{#e=new AbortController;#t=new Set;#n=Promise.withResolvers();caughtUp=this.#n.promise;#r=!1;#i;#a;#o;constructor(e,t){this.setOptions(t),this.caughtUp.catch(()=>{}),t.catchUp||this.#n.resolve(),(async()=>{try{for await(let n of followClientSession(e,{signal:this.#e.signal,resolveHeaders:()=>this.#a,resolveReconnectPolicy:()=>this.#o,startIndex:t.startIndex,onCaughtUp:t.catchUp?()=>this.#n.resolve():void 0})){if(this.#e.signal.aborted)return;t.onEvent(n);for(let e of this.#t)e.push(n);if(n.type===`session.completed`||n.type===`session.failed`)break}this.#n.resolve(),this.#s()}catch(e){this.#n.reject(e),this.#s(e),this.#e.signal.aborted||t.onError(e)}})()}subscribe(e){let t=new SessionEventReader(()=>this.#t.delete(t),e);return this.#r?t.end(this.#i):this.#t.add(t),t}get ended(){return this.#r}setOptions(e){`headers`in e&&(this.#a=e.headers),`streamReconnectPolicy`in e&&(this.#o=e.streamReconnectPolicy)}close(){let e=new DOMException(`Session stream was detached.`,`AbortError`);this.#e.abort(e),this.#n.reject(e),this.#s(e)}#s(e){if(!this.#r){this.#r=!0,this.#i=e;for(let t of this.#t)t.end(e)}}},SessionEventReader=class{#e=[];#t=Promise.withResolvers();#n=!1;#r;#i;constructor(e,t){let abort=()=>this.end(t?.reason);t?.addEventListener(`abort`,abort,{once:!0}),this.#i=()=>{t?.removeEventListener(`abort`,abort),e()},t?.aborted&&abort()}push(e){this.#n||(this.#e.push(e),this.#t.resolve())}end(e){this.#n||(this.#n=!0,this.#r=e,this.#t.resolve())}[Symbol.dispose](){this.end(),this.#e=[],this.#i()}discard(){this.#e=[]}async*[Symbol.asyncIterator](){for(;;){for(;this.#e.length>0;)yield this.#e.shift();if(this.#n){if(this.#r!==void 0)throw this.#r;return}this.#t=Promise.withResolvers(),await this.#t.promise}}};export{SessionEventReader,SessionEventStream};
+import{followClientSession}from"#client/session.js";var SessionEventStream=class{#e=new AbortController;#t=Promise.withResolvers();caughtUp=this.#t.promise;#n=!1;#r;#i;constructor(e,t){this.setOptions(t),this.caughtUp.catch(()=>{}),(async()=>{let n=!0;try{for await(let r of followClientSession(e,{signal:this.#e.signal,resolveHeaders:()=>this.#r,resolveReconnectPolicy:()=>this.#i,startIndex:t.startIndex,onCaughtUp:()=>{n=!1,this.#t.resolve()}})){if(this.#e.signal.aborted)return;if(t.onEvent(r,n),r.type===`session.ended`)break}this.#t.resolve()}catch(e){this.#n=!0,this.#t.reject(e),this.#e.signal.aborted||t.onError(e)}finally{this.#n=!0}})()}get ended(){return this.#n}setOptions(e){`headers`in e&&(this.#r=e.headers),`streamReconnectPolicy`in e&&(this.#i=e.streamReconnectPolicy)}close(){this.#n=!0;let e=new DOMException(`Session stream was detached.`,`AbortError`);this.#e.abort(e),this.#t.reject(e)}};export{SessionEventStream};

package/dist/src/client/session-store-helpers.d.ts

@@ -0,0 +1,8 @@
+import type { ConversationState } from "#client/conversation-state.js";
+import type { SendTurnPayload } from "#client/types.js";
+import type { MessageContent } from "#shared/message-content.js";
+/** A server ignores answers to requests it already settled, so the store never sends them. */
+export declare function assertAnswerable(input: SendTurnPayload, conversation: ConversationState): void;
+export declare function assertExclusiveTurnInput(input: SendTurnPayload): void;
+export declare function summarizeMessage(message: MessageContent): string;
+export declare function isAbortError(error: unknown): boolean;

package/dist/src/client/session-store-helpers.js

@@ -0,0 +1,2 @@
+import{interaction}from"#protocol/session-projection/public-view.js";function assertAnswerable(e,t){for(let{interactionId:n}of e.answers??[]){let e=interaction(t.view,n)?.status;if(e!==void 0&&e!==`open`)throw Error(`Input request ${n} was already answered.`)}}function assertExclusiveTurnInput(e){if(e.message!==void 0==(e.answers!==void 0))throw Error(`A turn requires exactly one of message or answers.`)}function summarizeMessage(e){return typeof e==`string`?e:e.flatMap(e=>e.type===`text`?[e.text]:e.type===`file`?[e.filename?`[file: ${e.filename}]`:`[file]`]:[]).join(`
+`)}function isAbortError(e){return e instanceof Error&&e.name===`AbortError`}export{assertAnswerable,assertExclusiveTurnInput,isAbortError,summarizeMessage};

package/dist/src/client/session-store-state.d.ts

@@ -0,0 +1,80 @@
+import type { SessionStreamEvent } from "#protocol/session-event.js";
+import type { Client } from "#client/client.js";
+import type { SessionView } from "#protocol/session-projection/session-view.js";
+import type { ConversationState, FollowAgents } from "#client/conversation-state.js";
+import type { ClientSession } from "#client/session.js";
+import type { ClientAuth, ClientSessionState, HeadersValue, SendTurnPayload } from "#client/types.js";
+/**
+ * Outstanding work the store has observed or still owes: `"resuming"` during catch-up, `"busy"`
+ * while a command, answer, or followed receipt is pending or the observed view is not idle, and
+ * otherwise `"idle"`. A turn waiting only on a person is open while the store is idle; read
+ * `activeTurn(view)` for turn openness. Errors live in `error`.
+ */
+export type SessionStoreStatus = "idle" | "busy" | "resuming";
+/**
+ * Prepares one outbound turn immediately before the client sends it, for
+ * example to attach fresh one-turn page state through `clientContext`.
+ */
+export type PrepareSend = (input: SendTurnPayload) => SendTurnPayload | Promise<SendTurnPayload>;
+export interface SessionStoreSnapshot extends ConversationState {
+    /** Immutable lifecycle observations as of this complete commit. */
+    readonly view: SessionView;
+    /** The latest session creation, stream, resume, or turn failure. */
+    readonly error: Error | undefined;
+    readonly events: readonly SessionStreamEvent[];
+    /** Fixed identity and next covered source line, including lines that emitted no events. */
+    readonly session: ClientSessionState | undefined;
+    readonly status: SessionStoreStatus;
+}
+/**
+ * Hooks invoked during session creation and turn processing. The observation callbacks
+ * do not alter execution; `prepareSend` may replace the outbound turn payload.
+ */
+export interface SessionStoreCallbacks {
+    /** Reports live failures and transport errors; recorded historical failures only update `error`. */
+    readonly onError?: (error: Error) => void;
+    /** Observes newly read events, including catch-up events. */
+    readonly onEvent?: (event: SessionStreamEvent) => void;
+    /** Fires once per live settled turn after its complete commit, never for catch-up (even for a local receipt). */
+    readonly onFinish?: (snapshot: SessionStoreSnapshot) => void;
+    readonly onSessionChange?: (session: ClientSessionState | undefined) => void;
+    readonly prepareSend?: PrepareSend;
+}
+/**
+ * Configuration for constructing an eve frontend session store. Pass connection
+ * options or a configured `Client` for store-owned sessions, or an existing
+ * `ClientSession`. Saved events must be an ordered prefix of the same session stream.
+ */
+export interface SessionStoreInit {
+    readonly prewarm?: boolean;
+    /** Configured client for store-owned sessions; replaces `baseUrl`, `auth`, and `headers`. */
+    readonly client?: Client;
+    readonly auth?: ClientAuth;
+    readonly headers?: HeadersValue;
+    readonly baseUrl?: string;
+    /**
+     * Ordered prefix of this session's stream. Preserve reader metadata, including `meta.next`
+     * when source lines emitted no events. Partial commits replay from their first source line.
+     */
+    readonly initialEvents?: readonly SessionStreamEvent[];
+    /** Positions the session handle; it does not extend the source coverage of `initialEvents`. */
+    readonly initialSession?: ClientSessionState;
+    readonly optimistic?: boolean;
+    /**
+     * Recursively observe recorded child sessions, including workflow-created children, while
+     * mounted or programmatically streaming. A predicate selects relationships at each known depth;
+     * `true` is equivalent to `() => true`. Returning false also excludes that child's descendants.
+     * Observation is bounded to depth 8, 128 admitted children, and 8 simultaneous descendant reads.
+     * Call results and root callbacks never wait for descendant catch-up. Off by default.
+     */
+    readonly followAgents?: FollowAgents;
+    /**
+     * Keep following while this predicate accepts the last committed view. Local POSTs, unsettled
+     * receipts, and resume catch-up keep the stream open regardless. Evaluated only at complete
+     * line boundaries; a closed stream reopens on any command, resume, or follow, from the
+     * store's committed position. If it closes during machine work, the snapshot remains busy
+     * until reopened. Defaults to always following, including between turns.
+     */
+    readonly followWhile?: (view: SessionView) => boolean;
+    readonly session?: ClientSession;
+}

package/dist/src/client/session-store-state.js

@@ -0,0 +1 @@
+export{};

package/dist/src/client/session-store.d.ts

@@ -0,0 +1,48 @@
+import type { SessionStoreCallbacks, SessionStoreInit, SessionStoreSnapshot } from "#client/session-store-state.js";
+import { type Delivery } from "#client/delivery.js";
+import type { DeliveryReceipt } from "#protocol/delivery.js";
+import type { SendTurnPayload } from "#client/types.js";
+export type { SessionStoreCallbacks, SessionStoreInit, SessionStoreSnapshot, SessionStoreStatus, PrepareSend, } from "#client/session-store-state.js";
+declare const detachStore: unique symbol;
+declare const attachStore: unique symbol;
+/** An observable durable session. Commands resolve on acceptance; only its stream changes its lifecycle. */
+export declare class SessionStore {
+    #private;
+    constructor(init: SessionStoreInit);
+    get snapshot(): SessionStoreSnapshot;
+    /** Activates observation outside a framework. Release the scope to stop reads, not execution. */
+    observe(): () => void;
+    setCallbacks(callbacks: SessionStoreCallbacks): void;
+    subscribe(callback: () => void): () => void;
+    /**
+     * Creates an idle session, sharing creation with sends already in flight, or
+     * prepares an existing session's idle owner without a model turn.
+     */
+    prewarm(): Promise<void>;
+    /** Accepts a message or answers. Observe the stream for its durable result. */
+    send<TOutput = unknown>(input: SendTurnPayload<TOutput>): Promise<Delivery<TOutput>>;
+    /**
+     * Follow an accepted delivery in this session until it settles or the session ends.
+     * The receipt may come from another store. Repeating it is safe and retries a closed stream.
+     * Pass only a receipt returned by `send`, `respond`, `clear`, `compact`, or `reset`: a receipt
+     * may arrive before its delivery is admitted, so an id the stream never admits keeps the store
+     * busy and its stream open until the session ends or `newSession()`.
+     * Catch-up updates recorded failures without replaying live completion callbacks.
+     * Normal session stream authorization still applies.
+     */
+    follow(receipt: DeliveryReceipt): void;
+    /** Replays through the durable tail; subsequent following obeys `followWhile`. */
+    resume(): Promise<void>;
+    /** Cancels the current turn, waiting for a pending submission's turn when necessary. */
+    cancel(): Promise<Delivery>;
+    compact(): Promise<Delivery>;
+    clear(): Promise<Delivery>;
+    reset(): Promise<Delivery>;
+    [attachStore](): void;
+    [detachStore](): void;
+    newSession(): void;
+}
+/** @internal Detaches local transport without cancelling durable server work. */
+export declare function detachSessionStore(store: SessionStore): void;
+/** @internal Starts mount-scoped session work after the framework commits. */
+export declare function attachSessionStore(store: SessionStore): void;

package/dist/src/client/session-store.js

@@ -0,0 +1 @@
+import{activeTurn,failure,idle}from"#protocol/session-projection/selectors.js";import{SessionNotActiveError}from"#channel/session-not-active-error.js";import{StreamDelivery}from"#client/delivery.js";import{toError}from"#shared/errors.js";import{assertAnswerable,assertExclusiveTurnInput,isAbortError}from"#client/session-store-helpers.js";import{throwIfAborted}from"#client/abort-signal.js";import{Client}from"#client/client.js";import{OptimisticMessageSubmissions}from"#client/optimistic-message-submissions.js";import{ConversationClient}from"#client/conversation-client.js";import{waitWithSignal}from"#shared/wait-with-signal.js";const detachStore=Symbol(`detachSessionStore`),attachStore=Symbol(`attachSessionStore`);var SessionStore=class{#e;#t;#n;#r;#i;#a=new Set;#o=new Set;#s;#c;#l=new Set;#u=new Set;#d=!1;#f=!1;#p=0;#m=!1;#h={};#g=new AbortController;#_;#v;#y;#b;#x;#S;#C;#w;#T=!1;#E=0;#D=0;#O=new Set;#k=[];constructor(e){this.#t=e.prewarm??!1,this.#n=e.followAgents??!1,this.#r=e.followWhile??(()=>!0),this.#i=e.session!==void 0,this.#e=this.#i?void 0:e.client??new Client({auth:e.auth,headers:e.headers,baseUrl:e.baseUrl??``}),this.#s=new ConversationClient(()=>this.#Z()),this.#S=(e.initialEvents??[]).filter(e=>this.#s.hydrate(e)),this.#c=new OptimisticMessageSubmissions(e=>this.#s.showSubmissions(e),e.optimistic??!0),this.#b=e.session??(e.initialSession===void 0?void 0:this.#e?.sessions.attach(e.initialSession.sessionId,{streamIndex:e.initialSession.streamIndex})),this.#x=this.#q(),this.#C=this.#X()}get snapshot(){return this.#C}observe(){this.#p+=1,this.#M();let e=!1;return()=>{e||(e=!0,--this.#p,!this.#f&&this.#p===0&&this.#N())}}setCallbacks(e){this.#h=e}subscribe(e){return this.#a.add(e),()=>void this.#a.delete(e)}async prewarm(){if(this.#b!==void 0)return await this.#L(this.#b);let e=this.#g;try{await this.#I()}catch(t){throw e===this.#g&&!isAbortError(t)&&this.#l.size===0&&this.#J(t),t}e===this.#g&&this.#r(this.#s.conversation.view)&&this.#z()}async send(e){if(this.#y!==void 0)throw Error(`eve session is resuming.`);assertExclusiveTurnInput(e),assertAnswerable(e,this.#s.conversation);let t=this.#g,n=e.signal?AbortSignal.any([t.signal,e.signal]):t.signal,r=Promise.withResolvers();this.#l.add(r.promise),this.#x=void 0;let i=this.#c.submit(e,e.turnPolicy===`steer`?activeTurn(this.#s.view)?.turnId:void 0),a=this.#s.projectAnswers(e.answers);this.#Z();let o=!1;try{let s=this.#h.prepareSend===void 0?e:await waitWithSignal(Promise.resolve(this.#h.prepareSend(e)),n);throwIfAborted(n),assertExclusiveTurnInput(s),s!==e&&(i=this.#c.resubmit(i,s),a=this.#s.replaceAnswers(a,s),this.#Z()),o=!0,this.#E+=1;let c=await this.#R({...s,signal:n});throwIfAborted(n);let l=c.deliveryId;if(l===void 0)throw Error(`The server did not identify the accepted delivery.`);return a?.accept(l),a=void 0,t===this.#g&&(i!==void 0&&(this.#s.confirmSubmission(i,l),this.#c.correlate(i,l)),this.#H(l)),r.resolve(l),new StreamDelivery({sessionId:c.sessionId,deliveryId:l,createStream:e=>c.stream(e)})}catch(e){throw t===this.#g&&(a?.(),this.#c.fail(toError(e),i),isAbortError(e)||this.#J(e)),e}finally{r.resolve(void 0),t===this.#g&&(this.#l.delete(r.promise),o&&--this.#E,this.#Z(),this.#G())}}follow(e){if(this.#b===void 0)throw Error(`An eve session is required before following.`);if(e.sessionId!==this.#b.id)throw Error(`The delivery belongs to a different eve session.`);let t=this.#s.view,n=t.deliveries[e.deliveryId];t.session.status!==`ended`&&n?.status!==`settled`&&(this.#x=void 0,this.#H(e.deliveryId),this.#u.has(e.deliveryId)&&this.#z(),this.#Z())}resume(){if(this.#y!==void 0)return this.#y;if(this.#b===void 0)return Promise.reject(Error(`An eve session is required before resuming.`));if(this.#l.size>0)return Promise.reject(Error(`eve session has pending submissions.`));let e=this.#g;this.#x=void 0;let t=this.#z({startIndex:this.#s.view.position}).caughtUp.then(()=>{e===this.#g&&(this.#x??=this.#q())}).finally(()=>{e===this.#g&&(this.#y=void 0,this.#Z(),this.#G())});return this.#y=t,this.#Z(!0),t}async cancel(){let e=this.#g,t=activeTurn(this.#s.view)?.turnId??await this.#A(e.signal);return throwIfAborted(e.signal),this.#j(e=>e.cancel({turnId:t??null}))}async#A(e){let t=new Set(this.#u.keys()),n=[...this.#l],r=n.length,i=Promise.withResolvers(),check=()=>{let e=this.#s.view;if(e.session.status===`ended`)return i.resolve(void 0);for(let n of t){let r=e.deliveries[n],a=r?.turnId===void 0?void 0:e.turns[r.turnId];if(a?.status===`running`)return i.resolve(a.turnId);(r?.status===`settled`||a?.status===`settled`)&&t.delete(n)}r===0&&t.size===0?i.resolve(void 0):this.#x!==void 0&&i.reject(this.#x)};this.#o.add(check);for(let e of n)e.then(e=>{--r,e!==void 0&&t.add(e),check()});try{return check(),await waitWithSignal(i.promise,e)}finally{this.#o.delete(check)}}compact(){return this.#j(e=>e.compact())}clear(){return this.#j(e=>e.clear())}reset(){return this.#j(e=>e.reset())}async#j(e){let t=this.#b;if(t===void 0)throw new SessionNotActiveError;let n=this.#g;this.#E+=1,this.#z(),this.#Z();try{let r=await e(t);return throwIfAborted(n.signal),this.#H(r.deliveryId),r}finally{n===this.#g&&(--this.#E,this.#Z(),this.#G())}}[attachStore](){this.#f=!0,this.#M()}#M(){if(this.#d)return;this.#d=!0,this.#B();let e=this.#m&&this.#r(this.#s.conversation.view);this.#m=!1,this.#b!==void 0&&(this.#W||e)&&this.#z(),this.#t&&this.#b===void 0&&this.prewarm().catch(()=>{})}[detachStore](){this.#f=!1,this.#p===0&&this.#N()}#N(){this.#d=!1,this.#m=this.#s.streaming,this.#P()}newSession(){this.#P(),this.#i||(this.#b=void 0),this.#u.clear(),this.#O.clear(),this.#S=[],this.#s.reset(),this.#c.reset(),this.#x=void 0,this.#d&&this.#B(),this.#h.onSessionChange?.(this.#Y),this.#Z(),this.#t&&this.#d&&this.prewarm().catch(()=>{})}#P(){this.#s.stop(),this.#g.abort(),this.#g=new AbortController,this.#_=void 0,this.#y=void 0,this.#l.clear(),this.#E=0,this.#D=0,this.#F()}#F(){this.#s.closeStream();let e=this.#S.length;for(;e>0&&this.#S[e-1].meta.endOfLine===!1;)--e;e<this.#S.length&&(this.#S=this.#S.slice(0,e)),this.#k=[],this.#T=!1}#I(e){if(this.#_!==void 0)return this.#_;let t=this.#e;if(t===void 0)return Promise.reject(Error(`This store cannot create a session.`));let n=this.#g,r=e?.signal??n.signal,i=(async()=>{let i,a;return e?.message===void 0?{session:i}=await t.sessions.create({signal:r}):{session:i,delivery:a}=await t.sessions.create({...e,message:e.message,signal:r}),throwIfAborted(n.signal),this.#b=i,this.#x=void 0,this.#h.onSessionChange?.(this.#Y),this.#B(),this.#Z(),a})();this.#_=i;let clear=()=>{this.#_===i&&(this.#_=void 0)};return i.then(clear,clear),i}#L(e){let t=this.#g;if(this.#v?.lifetime===t)return this.#v.promise;let n=e.prewarm({signal:t.signal}).then(()=>void 0),r={lifetime:t,promise:n};this.#v=r;let clear=()=>{this.#v===r&&(this.#v=void 0)};return n.then(clear,clear),n}async#R(e){if(this.#_!==void 0&&await waitWithSignal(this.#_.catch(()=>void 0),e.signal),throwIfAborted(e.signal),this.#b===void 0){if(e.message===void 0)throw Error(`Cannot answer before the session starts.`);let t=await this.#I(e);if(this.#z(e),t===void 0)throw Error(`The session was created without accepting a message.`);return t}return this.#z(e),e.answers===void 0?await this.#b.send(e.message,e):await this.#b.respond(e.answers,e)}#z(e={}){if(this.#b===void 0)throw Error(`A session is required before opening its stream.`);this.#B();let t=this.#g;return this.#s.stream(this.#b,{startIndex:this.#s.view.position,...e,onEvent:(e,n)=>{t===this.#g&&this.#V(e,n)},onError:e=>{t===this.#g&&(this.#F(),this.#J(e))}})}#B(){this.#n&&this.#b&&this.#s.follow(this.#b,this.#n)}#V(e,t){let n=this.#g;if(this.#T=e.meta.endOfLine===!1,!this.#s.observe(e,{notify:!1})||(this.#S=[...this.#S,e],this.#h.onEvent?.(e),n!==this.#g)||(e.type===`turn.started`&&!t&&(this.#x=void 0),(e.type===`turn.settled`||e.type===`session.ended`)&&this.#k.push({event:e,historical:t}),this.#T))return;let r=this.#s.view,i=new Set([...this.#u].map(e=>r.deliveries[e]?.turnId).filter(e=>e!==void 0));this.#U();for(let e of this.#k.splice(0)){if(e.event.type===`turn.settled`)e.historical?i.has(e.event.data.turnId)&&this.#l.size===0&&(this.#x??=this.#q(e.event.data.turnId)):this.#K(e.event.data.turnId);else if(e.event.data.outcome===`failed`){let t=Object.assign(Error(e.event.data.error?.message??`The session failed.`),{name:e.event.data.error?.code??`SESSION_FAILED`});e.historical?this.#l.size===0&&(this.#x??=t):this.#J(t)}if(n!==this.#g)return}for(let e of this.#o)e();this.#h.onSessionChange?.(this.#Y),n===this.#g&&(this.#Z(),n===this.#g&&(this.#s.reconcileFollowing(),n===this.#g&&this.#G()))}#H(e){this.#u.add(e),this.#U();let t=this.#s.view,n=t.deliveries[e]?.turnId;n!==void 0&&t.turns[n]?.status===`settled`&&(this.#x??=this.#q(n)),t.session.status===`ended`&&(this.#x??=this.#q())}#U(){let e=this.#s.view;e.session.status===`ended`&&this.#u.clear(),this.#c.reconcile(e);for(let t of this.#u)e.deliveries[t]?.status===`settled`&&this.#u.delete(t)}get#W(){return this.#y!==void 0||this.#E>0||this.#l.size>0||this.#u.size>0}#G(){this.#T||this.#W||this.#r(this.#s.conversation.view)||this.#s.closeStream()}#K(e){if(this.#O.has(e)||this.#s.view.turns[e]?.status!==`settled`)return;this.#O.add(e),this.#D+=1;let t=failure(this.#s.view,e);t!==void 0&&this.#J(Object.assign(Error(t.message),{name:t.code}))}#q(e=this.#s.view.session.latestTurnId){let t=this.#s.view,n=failure(t,e);return n===void 0?void 0:Object.assign(Error(n.message),{name:n.code})}#J(e){let t=this.#x!==void 0;this.#x=toError(e);for(let e of this.#o)e();t||this.#h.onError?.(this.#x),this.#Z()}get#Y(){if(this.#b===void 0)return this.#w=void 0;let e=this.#b.id,t=this.#s.view.position;return(this.#w?.sessionId!==e||this.#w.streamIndex!==t)&&(this.#w={sessionId:e,streamIndex:t}),this.#w}#X(){this.#s.holdUnconfirmedMessages(this.#E>0&&this.#c.awaitingReceipt);let e=this.#s.conversation,{view:t}=e;return{...e,view:t,error:this.#x,events:this.#S,session:this.#Y,status:this.#y===void 0?this.#W||!idle(this.#s.view)?`busy`:`idle`:`resuming`}}#Z(e=!1){if(this.#y!==void 0&&!e)return;if(this.#T){if(this.#x===void 0&&!this.#W)return;this.#C={...this.#C,error:this.#x,status:this.#y===void 0?this.#W?`busy`:this.#C.status:`resuming`};for(let e of this.#a)e();return}this.#C=this.#X();let t=this.#D,n=this.#g;this.#D=0;for(let e of this.#a)e();for(let e=0;e<t&&n===this.#g;e+=1)this.#h.onFinish?.(this.#C)}};function detachSessionStore(e){e[detachStore]()}function attachSessionStore(e){e[attachStore]()}export{SessionStore,attachSessionStore,detachSessionStore};

package/dist/src/client/session-utils.d.ts

@@ -1,51 +1,55 @@
-import type { AuthorizationRequiredStreamEvent, TurnFailureStreamEvent, UnstampedMessageStreamEvent } from "#protocol/message.js";
-import type { InputRequest } from "#shared/input.js";
-/** A connection authorization challenge that remains unresolved at a turn boundary. */
-interface PendingAuthorization {
-    readonly authorization?: AuthorizationRequiredStreamEvent["data"]["authorization"];
-    readonly description: string;
-    readonly name: string;
-    readonly attemptId?: string;
-    readonly webhookUrl?: string;
-}
-/** Canonical projection of the lifecycle state represented by one turn's events. */
+import type { SessionEvent } from "#protocol/session-event.js";
+import { type RequestStatus } from "#protocol/session-projection/request-status.js";
+import type { DeliveryOutcome } from "#protocol/session-events/families/delivery.js";
+import type { ErrorInfo } from "#protocol/session-events/envelope.js";
+import { type Interaction } from "#protocol/session-projection/reader.js";
+/** What one response's events say, for a reader that wants the outcome. */
 interface TurnEventSummary {
-    readonly boundary: UnstampedMessageStreamEvent | undefined;
-    readonly failure: TurnFailureStreamEvent | undefined;
-    readonly inputRequests: readonly InputRequest[];
+    readonly boundary: SessionEvent | undefined;
+    readonly failure: ErrorInfo | undefined;
+    /** What the response leaves open for people: answers it asks for, and sign-ins. */
+    readonly interactions: readonly Interaction[];
+    /** The reply's text, from the parts `turn.settled.reply` lists. */
     readonly message: string | undefined;
-    readonly pendingAuthorizations: readonly PendingAuthorization[];
-    readonly status: "completed" | "failed" | "waiting";
+    /** The value of the latest `result` part, whatever its phase. */
+    readonly result: unknown;
+    readonly status: RequestStatus | "working";
+    readonly outcome: DeliveryOutcome | undefined;
+    readonly sessionEnded: boolean;
 }
-/** Reduces one turn's protocol events into their client-facing lifecycle state. */
-export declare function summarizeTurnEvents(events: readonly UnstampedMessageStreamEvent[]): TurnEventSummary;
-/** Collects one segment of an event stream through its current-turn boundary. */
-export declare function collectTurnEvents(stream: AsyncIterable<UnstampedMessageStreamEvent>): Promise<readonly UnstampedMessageStreamEvent[]>;
 /**
- * Returns true when a read of a session's events ends at `event`: at a current-turn boundary, or
- * at a `turn.waiting` on `"input"` (or while a request read in the segment is unanswered). The
- * turn stays open there until a person acts; a `turn.waiting` on `"tasks"` is informational and
- * reading goes on to the turn's real end.
- * A reader that follows sign-in callbacks reads past a sign-in's `turn.waiting` or
- * `session.waiting` while its callback is outstanding, because the callback resumes the same turn.
+ * Reduces one response's events into their outcome. It reads the events themselves, not tables
+ * folded from them: a response that joins a running turn starts after that turn's
+ * `turn.started`, so a fold would never see the turn its `turn.settled` ends.
+ */
+export declare function summarizeTurnEvents(events: readonly SessionEvent[], deliveryId?: string): TurnEventSummary;
+/** Incremental response summary; progress events are folded, not retained. */
+export declare function turnSummary(deliveryId?: string): {
+    observe(event: SessionEvent): void;
+    result(): TurnEventSummary;
+};
+/** The failure an event reports: a turn's, a run's, or the session's. */
+export declare function failureOf(event: SessionEvent): ErrorInfo | undefined;
+/** Collects one response's events, through its end. */
+export declare function collectTurnEvents(stream: AsyncIterable<SessionEvent>, deliveryId?: string): Promise<readonly SessionEvent[]>;
+/**
+ * True when a read that follows no delivery ends at `event`: the turn settled, the session
+ * ended, or the turn paused on a person, who must act before it goes on.
+ */
+export declare function endsTurn(event: SessionEvent): boolean;
+/**
+ * One response's events, from where a reader started, and the requests and sign-ins they leave
+ * open. A response to a delivery ends when that delivery settles, however it settles, or when
+ * the session ends first; a read that follows no delivery ends with the turn ({@link endsTurn}).
  */
-export declare function endsTurnSegment(event: UnstampedMessageStreamEvent, open: {
-    readonly callbacks: boolean;
-    readonly requests: boolean;
-}): boolean;
-/** The requests and sign-ins one segment of a session's events leaves open. */
-export declare class TurnSegment {
+export declare class ResponseSegment {
     #private;
     constructor(options?: {
-        readonly followCallbacks?: boolean;
+        readonly deliveryId?: string;
     });
-    get inputRequests(): readonly InputRequest[];
-    get pendingAuthorizations(): readonly PendingAuthorization[];
-    /** Records `event` and returns true when it ends the segment. */
-    observe(event: UnstampedMessageStreamEvent): boolean;
+    get interactions(): readonly Interaction[];
+    get boundary(): SessionEvent | undefined;
+    /** Records `event`; an ending fact ends the response after the rest of its commit. */
+    observe(event: SessionEvent): boolean;
 }
-export declare function authorizationKey(data: {
-    readonly name: string;
-    readonly attemptId?: string;
-}): string;
 export {};