@roll-agent/relay-client 0.2.1 → 0.3.0

package/README.md

@@ -103,3 +103,7 @@ error.
 `@roll-agent/relay-client/testing` exports `createRelayClientForTesting()` and the minimal WebSocket
 and scheduler interfaces. Inject a deterministic transport without adding Node APIs to production
 Browser code.
+
+### Context recovery and Wire 1.3
+
+`RelayThreadView.contextRecovery` carries the latest bounded recovery gate state from snapshots and `context.recovery.changed` events. It is `null` for older peers. The default session advertisement remains `["1.2", "1.1"]` for existing Relay services with strict version allowlists. After upgrading the Relay service and Companion together, pass `relayProtocolVersions: ["1.3", "1.2", "1.1"]` to `createRelayClient`. Companion's bridge accepts `protocolVersion: "1.3"`; the Core host session factory accepts `relayProtocolVersion: "1.3"`. The deployed Relay service must support 1.3 ticket negotiation and routing before enabling either option.

package/dist/client.d.ts

@@ -1,17 +1,17 @@
-import { relayRequestMethodSchemasV12, type RelayInteractionRequestV11, type RelayRequestParamsForVersion, type RelayRequestResultForVersion } from "@roll-agent/relay-protocol";
+import { relayRequestMethodSchemasV13, type RelayInteractionRequestV11, type RelayRequestParamsForVersion, type RelayRequestResultForVersion } from "@roll-agent/relay-protocol";
 import { z } from "zod/v4";
 import { type RelayClientErrorDetails, type RelayConnectionState, type RelayThreadView } from "./schemas.ts";
 import { type RelayClientRuntimeDependencies } from "./transport.ts";
-type ThreadListWireInput = z.input<(typeof relayRequestMethodSchemasV12)["thread.list"]["params"]>;
-type ThreadCreateWireInput = z.input<(typeof relayRequestMethodSchemasV12)["thread.create"]["params"]>;
-type ThreadListWireResult = RelayRequestResultForVersion<"1.2", "thread.list">;
-type ThreadOpenWireResult = RelayRequestResultForVersion<"1.2", "thread.open">;
-type ThreadSnapshotWireResult = RelayRequestResultForVersion<"1.2", "thread.snapshot">;
-type TurnStartWireResult = RelayRequestResultForVersion<"1.2", "turn.start">;
-type TurnCancelWireResult = RelayRequestResultForVersion<"1.2", "turn.cancel">;
-type InteractionCandidateWireResult = RelayRequestResultForVersion<"1.2", "interaction.candidate">;
-export type RelayOperationResult = RelayRequestResultForVersion<"1.2", "operation.result.get">;
-export type RelayThreadCapabilities = RelayRequestResultForVersion<"1.2", "thread.capabilities">;
+type ThreadListWireInput = z.input<(typeof relayRequestMethodSchemasV13)["thread.list"]["params"]>;
+type ThreadCreateWireInput = z.input<(typeof relayRequestMethodSchemasV13)["thread.create"]["params"]>;
+type ThreadListWireResult = RelayRequestResultForVersion<"1.3", "thread.list">;
+type ThreadOpenWireResult = RelayRequestResultForVersion<"1.3", "thread.open"> | RelayRequestResultForVersion<"1.2", "thread.open">;
+type ThreadSnapshotWireResult = RelayRequestResultForVersion<"1.3", "thread.snapshot"> | RelayRequestResultForVersion<"1.2", "thread.snapshot">;
+type TurnStartWireResult = RelayRequestResultForVersion<"1.3", "turn.start">;
+type TurnCancelWireResult = RelayRequestResultForVersion<"1.3", "turn.cancel">;
+type InteractionCandidateWireResult = RelayRequestResultForVersion<"1.3", "interaction.candidate">;
+export type RelayOperationResult = RelayRequestResultForVersion<"1.3", "operation.result.get">;
+export type RelayThreadCapabilities = RelayRequestResultForVersion<"1.3", "thread.capabilities">;
 export type RelayThreadId = ThreadOpenWireResult["thread"]["id"];
 export type RelayTurnId = RelayRequestParamsForVersion<"1.2", "turn.cancel">["turnId"];
 export type RelayInteractionId = RelayInteractionRequestV11["interactionId"];
@@ -27,7 +27,7 @@ export type RelayTurnCancelResult = TurnCancelWireResult;
 export type RelayInteractionCandidateResult = InteractionCandidateWireResult;
 export interface RelaySessionProviderInput {
     readonly signal: AbortSignal;
-    readonly supportedRelayProtocolVersions: readonly ["1.2", "1.1"];
+    readonly supportedRelayProtocolVersions: readonly ("1.3" | "1.2" | "1.1")[];
 }
 export type RelaySessionProvider = (input: RelaySessionProviderInput) => Promise<unknown>;
 export interface RelayRequestOptions {
@@ -36,6 +36,8 @@ export interface RelayRequestOptions {
 }
 export interface CreateRelayClientOptions {
     readonly getSession: RelaySessionProvider;
+    /** Opt into 1.3 only after the Relay service and Companion support it. */
+    readonly relayProtocolVersions?: readonly ("1.3" | "1.2" | "1.1")[];
     readonly requestTimeoutMs?: number;
 }
 export type RelayConnectionListener = (state: RelayConnectionState) => void;

package/dist/client.js

@@ -1 +1 @@
-import{RELAY_ERROR_CODES_V11 as e,RELAY_MESSAGE_TYPES_V11 as t,RELAY_REQUEST_METHODS_V11 as s,RELAY_REQUEST_METHOD_DISPOSITIONS_V12 as n,parseRelayInteractionCandidateForRequestV11 as i,parseRelayRequestParamsForVersion as r,parseRelayRequestResultForVersion as o,relayAckSchemaV11 as a,relayMessageSchemaV12 as c,relayRequestIdSchema as l,relayRequestMethodSchemasV12 as d,relayRuntimeRequestSchemaV12 as h}from"@roll-agent/relay-protocol";import{parseRelayBrowserFirstControlFrameAny as u,relayBrowserControlMessageSchemaAny as p,relaySessionDescriptorSchema as y}from"@roll-agent/relay-protocol/control";import{z as m}from"zod/v4";import{RELAY_CLIENT_TRANSPORT_ERROR_CODES as f,getPendingInteractionRequest as g,relayClientErrorDetailsSchema as v,relayConnectionStateSchema as w,relayThreadViewSchema as R}from"./schemas.js";import{browserRelayRuntimeDependencies as S}from"./transport.js";export class RelayClientError extends Error{details;constructor(e){super(e.message),this.name="RelayClientError",this.details=v.parse(e)}}const b=3e4,I=1,q=-1,k={normal:1e3,invalidFrame:4002,sessionFatal:4008,sessionRetryable:4012},C=new Set(["completed","cancelled","failed"]);function T(e,t,s){return new RelayClientError({kind:"transport",code:e,message:t,retryable:s})}function E(e){return e instanceof RelayClientError?e:T(f.transportError,e instanceof Error?e.message:"Relay transport failed",!0)}function P(e,t){try{e(t)}catch(e){if("function"==typeof globalThis.reportError)try{globalThis.reportError(e)}catch{}}}function M(e){if("string"!=typeof e)throw T(f.protocolError,"Relay sent a non-text frame",!1);try{return JSON.parse(e)}catch{throw T(f.protocolError,"Relay sent invalid JSON",!1)}}function A(e){try{return u(e)}catch{throw T(f.protocolError,"Relay first frame must be Control 1.0 session.ready for Wire 1.1",!1)}}function B(e){const t=e.activeTurn;return void 0===t?{status:"idle"}:"cancelling"===t.status?{status:"cancelling",turnId:t.id}:{status:"running",turnId:t.id}}function O(e,t){const s=e.findIndex(e=>e.streamId===t.streamId);return-1===s?[...e,t]:e.map((e,n)=>n===s?t:e)}function x(e,t){return{status:e,interactionId:t.interactionId,threadId:t.threadId,turnId:t.turnId,method:t.method}}class RelayThreadImpl{id;#e;#t=new Set;#s;constructor(e,t){this.#e=e,this.id=t,this.#s=R.parse({status:"loading",threadId:t,snapshot:null,liveAssistantMessages:[],interactions:[],turn:{status:"idle"}})}getSnapshot(){return this.#s}subscribe(e){return this.#t.add(e),P(e,this.#s),()=>{this.#t.delete(e)}}async send(e,t){const s=await this.#e.startTurn(this.id,e,t);return this.#n({status:"running",turnId:s.turnId}),s}async cancel(e,t){const s=await this.#e.cancelTurn(this.id,e,t);return s.cancelling&&this.#n({status:"cancelling",turnId:e}),s}async respond(e,t,s){const n=this.#s.interactions.find(t=>{const s=g(t);return s?.interactionId===e}),i=void 0===n?void 0:g(n);if(void 0===i)throw T(f.connectionUnavailable,"Interaction is no longer pending in this Browser session",!1);this.#i(e,"responding");try{return await this.#e.respondToInteraction(i,t,s)}catch(t){throw this.#i(e,"pending"),t}}getResult(e,t){return this.#e.getOperationResult(this.id,e,t)}capabilities(e){return this.#e.getThreadCapabilities(this.id,e)}async refresh(e){try{const t=await this.#e.getThreadSnapshot(this.id,e);return this.applySnapshot(t),t}catch(e){throw this.applyError(E(e).details),e}}applySnapshot(e){this.#r({status:"ready",threadId:this.id,snapshot:e,liveAssistantMessages:[],interactions:this.#s.interactions,turn:B(e)})}applyError(e){this.#r({status:"error",threadId:this.id,snapshot:this.#s.snapshot,liveAssistantMessages:this.#s.liveAssistantMessages,interactions:this.#s.interactions,turn:this.#s.turn,error:e})}applyRuntimeEvent(e){const t=e.event,s=t.event,n=t.turnId;let i=this.#s.liveAssistantMessages,r=this.#s.turn;if("message.started"===s.type)i=O(i,{status:"streaming",streamId:s.streamId,text:""});else if("message.delta"===s.type){const e=i.find(e=>e.streamId===s.streamId);i=O(i,{status:"streaming",streamId:s.streamId,text:`${e?.text??""}${s.delta}`})}else"message.completed"===s.type?i=O(i,{status:"completed",streamId:s.streamId,text:s.text}):"turn.started"===s.type&&void 0!==n?r={status:"running",turnId:n}:"turn.completed"===s.type&&void 0!==n?r={status:"completed",turnId:n}:"turn.cancelled"===s.type&&void 0!==n?r={status:"cancelled",turnId:n}:"turn.failed"===s.type&&void 0!==n&&(r={status:"failed",turnId:n,stage:s.stage});this.#o({liveAssistantMessages:i,turn:r}),"turn.completed"!==s.type&&"turn.cancelled"!==s.type&&"turn.failed"!==s.type||this.refresh().catch(()=>{})}applyInteractionRequest(e){const t=this.#s.interactions.findIndex(t=>{const s=g(t);return s?.interactionId===e.interactionId}),s={status:"pending",request:e},n=-1===t?[...this.#s.interactions,s]:this.#s.interactions.map((e,n)=>n===t?s:e);this.#o({interactions:n})}applyInteractionTerminal(e){const s=x(e.type===t.interactionResolved?"resolved":"cancelled",e),n=this.#s.interactions.findIndex(t=>{const s=g(t);return s?.interactionId===e.interactionId}),i=-1===n?[...this.#s.interactions,s]:this.#s.interactions.map((e,t)=>t===n?s:e);this.#o({interactions:i})}#n(e){const t=this.#s.turn;"idle"!==t.status&&t.turnId===e.turnId&&C.has(t.status)||this.#o({turn:e})}#i(e,t){const s=this.#s.interactions.map(s=>{const n=g(s);return n?.interactionId===e?{status:t,request:n}:s});this.#o({interactions:s})}#o(e){const t={threadId:this.id,snapshot:this.#s.snapshot,liveAssistantMessages:e.liveAssistantMessages??this.#s.liveAssistantMessages,interactions:e.interactions??this.#s.interactions,turn:e.turn??this.#s.turn};this.#r(null===this.#s.snapshot?{status:"loading",...t,snapshot:null}:{status:"ready",...t,snapshot:this.#s.snapshot})}#r(e){this.#s=R.parse(e);for(const e of this.#t)P(e,this.#s)}}export class RelayClientImpl{#a;#c;#l=new Set;#d=new Map;#h=new Map;#u=new Map;#p={status:"idle"};#y;#m;#f="1.1";#g=new Map;#v;#w;#R;#S=0;#b=!1;#I=!1;#q=q;#k=!1;#C=0;#T=!1;#E;constructor(e,t){if(this.#a=e,this.#c=t,this.#E=e.requestTimeoutMs??b,!Number.isFinite(this.#E)||this.#E<=0)throw new TypeError("requestTimeoutMs must be a positive finite number")}async connect(e){if("connected"===this.#p.status)return;if(this.#b)throw T(f.closed,"Relay client is closed",!1);this.#P();const t=this.#v;return void 0!==t?t:(this.#I=!1,this.#S=0,this.#M({status:"connecting",attempt:1}),this.#A(e?.signal,e?.timeoutMs).catch(e=>{const t=E(e);throw this.#b||this.#I||this.#M({status:"closed",reason:"session"===t.details.kind?"session":"transport"}),t}))}close(){this.#b||(this.#b=!0,this.#I=!0,this.#w?.abort(),this.#P(),this.#B("client closed"),this.#O(!0),this.#M({status:"closed",reason:"client"}))}getConnectionState(){return this.#p}subscribeConnection(e){return this.#l.add(e),P(e,this.#p),()=>{this.#l.delete(e)}}async listThreads(e={},t){return this.#x(s.threadList,e,t)}async createThread(e={},t){const n=await this.#x(s.threadCreate,{...e,requestId:this.#c.createUuid()},t),i=this.#F(n.thread.id);return await i.refresh(t).catch(()=>{}),i}async openThread(e,t){const n=await this.#x(s.threadOpen,{threadId:e},t),i=this.#F(e);return i.applySnapshot(n),i}async startTurn(e,t,n){return this.#x(s.turnStart,{requestId:this.#c.createUuid(),threadId:e,turnId:this.#c.createUuid(),input:{text:t}},n)}async cancelTurn(e,t,n){return this.#x(s.turnCancel,{requestId:this.#c.createUuid(),threadId:e,turnId:t},n)}async respondToInteraction(e,t,n){const r=i(e,t);return this.#x(s.interactionCandidate,r,n)}async getThreadCapabilities(e,t){return this.#x("thread.capabilities",{threadId:e},t)}getOperationResult(e,t,s){if("1.2"!==this.#f)return Promise.reject(T(f.protocolError,"App results require Relay Wire 1.2",!1));const n=`${this.#C}:${this.#m}:${e}:${t}`;if(void 0===s){const e=this.#g.get(n);if(e)return e}const i=this.#x("operation.result.get",{threadId:e,operationId:t},s);return void 0===s&&(this.#g.set(n,i),i.finally(()=>{this.#g.get(n)===i&&this.#g.delete(n)}).catch(()=>{})),i}async getThreadSnapshot(e,t){return this.#x(s.threadSnapshot,{threadId:e,limit:100},t)}async#W(e,t){const s=t??this.#E;if(!Number.isFinite(s)||s<=0)throw new TypeError("timeoutMs must be a positive finite number");const n=new AbortController;this.#w=n;let i=!1;const r=()=>{n.abort()};e?.addEventListener("abort",r,{once:!0}),!0===e?.aborted&&n.abort();const o=this.#c.scheduler.setTimer(()=>{i=!0,n.abort()},s),a=new Promise((e,t)=>{const s=()=>{t(T(i?f.requestTimeout:f.aborted,i?"Relay session connection timed out":"Relay session request was aborted",i)),this.#y?.close(k.normal,"session attempt cancelled")};n.signal.aborted?s():n.signal.addEventListener("abort",s,{once:!0})});try{await Promise.race([this.#j(n.signal),a])}finally{this.#c.scheduler.clearTimer(o),e?.removeEventListener("abort",r),this.#w===n&&(this.#w=void 0)}}async#j(e){try{let t;try{t=await this.#a.getSession({signal:e,supportedRelayProtocolVersions:["1.2","1.1"]})}catch(t){if(e.aborted)throw T(f.aborted,"Relay session request was aborted",!1);throw E(t)}if(e.aborted)throw T(f.aborted,"Relay session request was aborted",!1);const s=y.safeParse(t);if(!s.success)throw T(f.invalidSession,"Session endpoint returned an invalid Relay session",!1);if(Date.parse(s.data.expiresAt)<=this.#c.scheduler.now())throw T(f.invalidSession,"Session endpoint returned an expired Relay session",!1);this.#B("superseded relay session");const n=this.#c.createWebSocket(s.data.connectUrl);this.#y=n,await this.#L(n)}catch(e){throw E(e)}}#L(e){return new Promise((t,s)=>{const n={ready:!1,settled:!1},i=e=>{n.settled||(n.settled=!0,s(e))};e.setHandlers({onOpen:()=>{},onMessage:s=>{if(!n.ready||this.#y===e)try{const e=M(s);if(!n.ready){const s=A(e);if(void 0!==this.#m&&this.#m!==s.workspaceId)throw T(f.protocolError,"Relay session changed the bound Workspace",!1);return this.#m=s.workspaceId,this.#f=s.relayProtocolVersion,this.#g.clear(),n.ready=!0,n.settled=!0,this.#S=0,this.#T=!0,this.#M({status:"connected",workspaceStatus:s.workspaceStatus}),this.#U(),"online"===s.workspaceStatus&&this.#z(),void t()}this.#$(e)}catch(t){const s=E(t);n.ready?this.#V(s):i(s),e.close(k.invalidFrame,"invalid relay frame")}},onClose:()=>{const t=this.#y===e;t&&(this.#y=void 0),n.ready?t&&this.#N():i(T(f.transportError,"Relay connection closed before session.ready",!0))},onError:()=>{n.ready||i(T(f.transportError,"Relay WebSocket failed before session.ready",!0))}})})}#$(e){const t=p.safeParse(e);if(t.success)return void this.#G(t.data);const s=c.safeParse(e);if(!s.success)throw T(f.protocolError,"Relay sent an invalid Control 1.0 or Wire 1.1 frame",!1);this.#H(s.data)}#G(e){if("session.ready"===e.type)throw T(f.protocolError,"session.ready may only be the first frame",!1);if("workspace.status"===e.type){this.#D(e.workspaceId);const t=this.#p,s="connected"===t.status&&"offline"===t.workspaceStatus&&"online"===e.status;return this.#M({status:"connected",workspaceStatus:e.status}),s&&(this.#T=!0,this.#J()),void("online"===e.status&&this.#z())}const t=new RelayClientError({kind:"session",code:e.code,message:`Relay session failed: ${e.code}`,retryable:e.retryable});if(e.retryable)this.#y?.close(k.sessionRetryable,"retryable relay session error");else{this.#I=!0,this.#O(!0);for(const e of this.#d.values())e.applyError(t.details);this.#M({status:"closed",reason:"session"}),this.#y?.close(k.sessionFatal,"non-retryable relay session error")}}#H(e){if(e.type!==t.runtimeResponse){if(e.type===t.runtimeGap)return this.#D(e.workspaceId),this.#Q(e.throughRelaySequence),void this.#K(e.throughRelaySequence);if(e.type!==t.runtimeEvent&&e.type!==t.interactionRequest&&e.type!==t.interactionResolved&&e.type!==t.interactionCancelled)throw T(f.protocolError,`Relay sent disallowed Browser inbound frame: ${e.type}`,!1);this.#X({relaySequence:e.relaySequence,message:e})}else this.#Y(e)}#Y(t){this.#D(t.workspaceId);const s=this.#h.get(t.requestId);if(void 0!==s){if(void 0!==t.error){const n=t.error.code===e.remoteRequestDenied?"Remote request denied":t.error.message;return void this.#Z(s,new RelayClientError({kind:"remote",code:t.error.code,message:n,retryable:t.error.retryable}))}if(void 0!==t.result)try{const e=o(this.#f,s.method,t.result);this.#Z(s,void 0,e)}catch{this.#Z(s,T(f.protocolError,`Relay returned an invalid ${s.method} result`,!1))}else this.#Z(s,T(f.protocolError,"runtime.response contains neither result nor error",!1))}}#X(e){if(this.#D(e.message.workspaceId),this.#Q(e.relaySequence),e.relaySequence<=this.#q)this.#U();else if(this.#k)this.#u.set(e.relaySequence,e);else{if(e.relaySequence!==this.#q+1)return this.#u.set(e.relaySequence,e),void this.#K(e.relaySequence-1);this.#_(e.message),this.#q=e.relaySequence,this.#U()}}#_(e){const s=e.type===t.runtimeEvent?e.event.threadId:e.threadId,n=this.#F(s);e.type===t.runtimeEvent?n.applyRuntimeEvent(e):e.type===t.interactionRequest?n.applyInteractionRequest(e):n.applyInteractionTerminal(e)}#K(e){if(e<=this.#q)return void this.#U();if(this.#k)return;this.#k=!0;const t=e,s=this.#C,n=[...this.#d.values()].map(async e=>e.refresh());Promise.all(n).then(()=>{if(this.#C===s){this.#q=t;for(const e of[...this.#u.keys()])e<=t&&this.#u.delete(e);this.#k=!1,this.#U(),this.#ee()}}).catch(()=>{this.#C===s&&(this.#k=!1,this.#y?.close(k.sessionRetryable,"snapshot recovery failed"))})}#Q(e){this.#T&&(this.#T=!1,e>this.#q||(this.#C+=1,this.#q=q,this.#u.clear(),this.#k=!1,this.#J()))}#J(){for(const e of this.#d.values())e.refresh().catch(()=>{})}#ee(){for(;!this.#k;){const e=this.#q+1,t=this.#u.get(e);if(void 0===t){const t=[...this.#u.keys()].sort((e,t)=>e-t)[0];return void(void 0!==t&&t>e&&this.#K(t-1))}this.#u.delete(e),this.#_(t.message),this.#q=e,this.#U()}}#U(){const e=this.#m,s=this.#y;if(void 0===e||1!==s?.readyState)return;const n=a.parse({type:t.runtimeAck,workspaceId:e,throughRelaySequence:this.#q});s.send(JSON.stringify(n))}#N(){this.#b||this.#I||(this.#te(),this.#se())}#se(){if(void 0!==this.#R||this.#b||this.#I)return;this.#S+=1;const e=this.#c.reconnectDelayMs(this.#S),t=new Date(this.#c.scheduler.now()+e).toISOString();this.#M({status:"reconnecting",attempt:this.#S,retryAt:t}),this.#R=this.#c.scheduler.setTimer(()=>{this.#R=void 0,this.#b||this.#I||void 0!==this.#v||"connected"===this.#p.status||this.#A().catch(e=>{if(this.#b)return;if(!E(e).details.retryable)return this.#I=!0,this.#O(!0),void this.#M({status:"closed",reason:"session"});this.#se()})},e)}#A(e,t){const s=this.#W(e,t).finally(()=>{this.#v===s&&(this.#v=void 0)});return this.#v=s,s}#B(e){const t=this.#y;void 0!==t&&(this.#y=void 0,t.close(k.normal,e))}#P(){void 0!==this.#R&&(this.#c.scheduler.clearTimer(this.#R),this.#R=void 0)}#z(){for(const e of this.#h.values())e.mutation&&this.#ne(e)}#x(e,s,i){if("connected"!==this.#p.status||"online"!==this.#p.workspaceStatus||void 0===this.#m){const e="connected"===this.#p.status&&"offline"===this.#p.workspaceStatus;return Promise.reject(T(e?f.workspaceOffline:f.connectionUnavailable,e?"The local Workspace is offline":"Relay is not connected",!0))}if(!0===i?.signal?.aborted)return Promise.reject(T(f.aborted,"Relay request was aborted",!1));const o=r("1.2",e,s),a=l.parse(this.#c.createUuid()),c=h.parse({type:t.runtimeRequest,requestId:a,workspaceId:this.#m,method:e,params:o}),d=i?.timeoutMs??this.#E;if(!Number.isFinite(d)||d<=0)return Promise.reject(new TypeError("timeoutMs must be a positive finite number"));const u="mutation"===n[e];return new Promise((t,s)=>{const n=i?.signal?()=>{const e=this.#h.get(a);if(void 0===e)return;const t=e.mutation&&e.sent;this.#Z(e,T(t?f.outcomeUnknown:f.aborted,t?"Mutation outcome is unknown after Browser cancellation":"Relay request was aborted",!1))}:void 0,r={requestId:a,method:e,frame:JSON.stringify(c),mutation:u,sent:!1,resolve:e=>{t(e)},reject:s,signal:i?.signal,abortListener:n,timeoutHandle:void 0};r.timeoutHandle=this.#c.scheduler.setTimer(()=>{const e=this.#h.get(a);if(void 0===e)return;const t=e.mutation&&e.sent;this.#Z(e,T(t?f.outcomeUnknown:f.requestTimeout,t?"Mutation outcome is unknown after Relay timeout":"Relay request timed out",!t))},d),i?.signal?.addEventListener("abort",n??(()=>{}),{once:!0}),this.#h.set(a,r),this.#ne(r)})}#ne(e){const t=this.#y;1===t?.readyState&&"connected"===this.#p.status&&"online"===this.#p.workspaceStatus&&(t.send(e.frame),e.sent=!0)}#Z(e,t,s){this.#h.delete(e.requestId)&&(void 0!==e.timeoutHandle&&this.#c.scheduler.clearTimer(e.timeoutHandle),void 0!==e.signal&&void 0!==e.abortListener&&e.signal.removeEventListener("abort",e.abortListener),void 0!==t?e.reject(t):e.resolve(s))}#te(){for(const e of[...this.#h.values()])e.mutation||this.#Z(e,T(f.transportError,"Relay disconnected before the query completed",!0))}#O(e){for(const t of[...this.#h.values()]){const s=e&&t.mutation&&t.sent;this.#Z(t,T(s?f.outcomeUnknown:f.closed,s?"Mutation outcome is unknown after Relay closed":"Relay client is closed",!1))}}#D(e){if(this.#m!==e)throw T(f.protocolError,"Relay frame does not match the bound Workspace",!1)}#F(e){const t=this.#d.get(e);if(void 0!==t)return t;const s=new RelayThreadImpl(this,e);return this.#d.set(e,s),s}#M(e){this.#p=w.parse(e);for(const e of this.#l)P(e,this.#p)}#V(e){this.#I=!0,this.#O(!0);for(const t of this.#d.values())t.applyError(e.details);this.#M({status:"closed",reason:"protocol"})}}export function createRelayClientWithRuntime(e,t){return new RelayClientImpl(e,t)}export function createRelayClient(e){return createRelayClientWithRuntime(e,S)}
+import{RELAY_ERROR_CODES_V11 as e,RELAY_MESSAGE_TYPES_V11 as t,RELAY_REQUEST_METHODS_V11 as s,RELAY_REQUEST_METHOD_DISPOSITIONS_V12 as n,parseRelayInteractionCandidateForRequestV11 as i,parseRelayRequestParamsForVersion as r,parseRelayRequestResultForVersion as o,relayAckSchemaV11 as a,relayMessageSchemaV13 as c,relayRequestIdSchema as l,relayRequestMethodSchemasV13 as d,relayRuntimeRequestSchemaV12 as h}from"@roll-agent/relay-protocol";import{parseRelayBrowserFirstControlFrameAny as u,relayBrowserControlMessageSchemaAny as p,relaySessionDescriptorSchema as y}from"@roll-agent/relay-protocol/control";import{z as m}from"zod/v4";import{RELAY_CLIENT_TRANSPORT_ERROR_CODES as f,getPendingInteractionRequest as v,relayClientErrorDetailsSchema as g,relayConnectionStateSchema as w,relayThreadViewSchema as R}from"./schemas.js";import{browserRelayRuntimeDependencies as S}from"./transport.js";export class RelayClientError extends Error{details;constructor(e){super(e.message),this.name="RelayClientError",this.details=g.parse(e)}}const b=3e4,I=1,q=-1,k={normal:1e3,invalidFrame:4002,sessionFatal:4008,sessionRetryable:4012},C=new Set(["completed","cancelled","failed"]);function T(e,t,s){return new RelayClientError({kind:"transport",code:e,message:t,retryable:s})}function E(e){return e instanceof RelayClientError?e:T(f.transportError,e instanceof Error?e.message:"Relay transport failed",!0)}function P(e,t){try{e(t)}catch(e){if("function"==typeof globalThis.reportError)try{globalThis.reportError(e)}catch{}}}function M(e){if("string"!=typeof e)throw T(f.protocolError,"Relay sent a non-text frame",!1);try{return JSON.parse(e)}catch{throw T(f.protocolError,"Relay sent invalid JSON",!1)}}function A(e){try{return u(e)}catch{throw T(f.protocolError,"Relay first frame must be Control 1.0 session.ready for Wire 1.1",!1)}}function x(e){const t=e.activeTurn;return void 0===t?{status:"idle"}:"cancelling"===t.status?{status:"cancelling",turnId:t.id}:{status:"running",turnId:t.id}}function B(e,t){const s=e.findIndex(e=>e.streamId===t.streamId);return-1===s?[...e,t]:e.map((e,n)=>n===s?t:e)}function O(e,t){return{status:e,interactionId:t.interactionId,threadId:t.threadId,turnId:t.turnId,method:t.method}}class RelayThreadImpl{id;#e;#t=new Set;#s;constructor(e,t){this.#e=e,this.id=t,this.#s=R.parse({status:"loading",threadId:t,snapshot:null,liveAssistantMessages:[],interactions:[],turn:{status:"idle"}})}getSnapshot(){return this.#s}subscribe(e){return this.#t.add(e),P(e,this.#s),()=>{this.#t.delete(e)}}async send(e,t){const s=await this.#e.startTurn(this.id,e,t);return this.#n({status:"running",turnId:s.turnId}),s}async cancel(e,t){const s=await this.#e.cancelTurn(this.id,e,t);return s.cancelling&&this.#n({status:"cancelling",turnId:e}),s}async respond(e,t,s){const n=this.#s.interactions.find(t=>{const s=v(t);return s?.interactionId===e}),i=void 0===n?void 0:v(n);if(void 0===i)throw T(f.connectionUnavailable,"Interaction is no longer pending in this Browser session",!1);this.#i(e,"responding");try{return await this.#e.respondToInteraction(i,t,s)}catch(t){throw this.#i(e,"pending"),t}}getResult(e,t){return this.#e.getOperationResult(this.id,e,t)}capabilities(e){return this.#e.getThreadCapabilities(this.id,e)}async refresh(e){try{const t=await this.#e.getThreadSnapshot(this.id,e);return this.applySnapshot(t),t}catch(e){throw this.applyError(E(e).details),e}}applySnapshot(e){this.#r({status:"ready",threadId:this.id,snapshot:e,liveAssistantMessages:[],interactions:this.#s.interactions,turn:x(e),contextRecovery:"contextRecovery"in e?e.contextRecovery:null})}applyError(e){this.#r({status:"error",threadId:this.id,snapshot:this.#s.snapshot,liveAssistantMessages:this.#s.liveAssistantMessages,interactions:this.#s.interactions,turn:this.#s.turn,contextRecovery:this.#s.contextRecovery,error:e})}applyRuntimeEvent(e){const t=e.event,s=t.event,n=t.turnId;let i=this.#s.liveAssistantMessages,r=this.#s.turn;if("message.started"===s.type)i=B(i,{status:"streaming",streamId:s.streamId,text:""});else if("message.delta"===s.type){const e=i.find(e=>e.streamId===s.streamId);i=B(i,{status:"streaming",streamId:s.streamId,text:`${e?.text??""}${s.delta}`})}else"message.completed"===s.type?i=B(i,{status:"completed",streamId:s.streamId,text:s.text}):"turn.started"===s.type&&void 0!==n?r={status:"running",turnId:n}:"turn.completed"===s.type&&void 0!==n?r={status:"completed",turnId:n}:"turn.cancelled"===s.type&&void 0!==n?r={status:"cancelled",turnId:n}:"turn.failed"===s.type&&void 0!==n&&(r={status:"failed",turnId:n,stage:s.stage});this.#o({liveAssistantMessages:i,turn:r,..."context.recovery.changed"===s.type?{contextRecovery:s.contextRecovery}:{}}),"turn.completed"!==s.type&&"turn.cancelled"!==s.type&&"turn.failed"!==s.type||this.refresh().catch(()=>{})}applyInteractionRequest(e){const t=this.#s.interactions.findIndex(t=>{const s=v(t);return s?.interactionId===e.interactionId}),s={status:"pending",request:e},n=-1===t?[...this.#s.interactions,s]:this.#s.interactions.map((e,n)=>n===t?s:e);this.#o({interactions:n})}applyInteractionTerminal(e){const s=O(e.type===t.interactionResolved?"resolved":"cancelled",e),n=this.#s.interactions.findIndex(t=>{const s=v(t);return s?.interactionId===e.interactionId}),i=-1===n?[...this.#s.interactions,s]:this.#s.interactions.map((e,t)=>t===n?s:e);this.#o({interactions:i})}#n(e){const t=this.#s.turn;"idle"!==t.status&&t.turnId===e.turnId&&C.has(t.status)||this.#o({turn:e})}#i(e,t){const s=this.#s.interactions.map(s=>{const n=v(s);return n?.interactionId===e?{status:t,request:n}:s});this.#o({interactions:s})}#o(e){const t={threadId:this.id,snapshot:this.#s.snapshot,liveAssistantMessages:e.liveAssistantMessages??this.#s.liveAssistantMessages,interactions:e.interactions??this.#s.interactions,turn:e.turn??this.#s.turn,contextRecovery:void 0===e.contextRecovery?this.#s.contextRecovery:e.contextRecovery};this.#r(null===this.#s.snapshot?{status:"loading",...t,snapshot:null}:{status:"ready",...t,snapshot:this.#s.snapshot})}#r(e){this.#s=R.parse(e);for(const e of this.#t)P(e,this.#s)}}export class RelayClientImpl{#a;#c;#l=new Set;#d=new Map;#h=new Map;#u=new Map;#p={status:"idle"};#y;#m;#f="1.1";#v=new Map;#g;#w;#R;#S=0;#b=!1;#I=!1;#q=q;#k=!1;#C=0;#T=!1;#E;constructor(e,t){if(this.#a=e,this.#c=t,this.#E=e.requestTimeoutMs??b,!Number.isFinite(this.#E)||this.#E<=0)throw new TypeError("requestTimeoutMs must be a positive finite number")}async connect(e){if("connected"===this.#p.status)return;if(this.#b)throw T(f.closed,"Relay client is closed",!1);this.#P();const t=this.#g;return void 0!==t?t:(this.#I=!1,this.#S=0,this.#M({status:"connecting",attempt:1}),this.#A(e?.signal,e?.timeoutMs).catch(e=>{const t=E(e);throw this.#b||this.#I||this.#M({status:"closed",reason:"session"===t.details.kind?"session":"transport"}),t}))}close(){this.#b||(this.#b=!0,this.#I=!0,this.#w?.abort(),this.#P(),this.#x("client closed"),this.#B(!0),this.#M({status:"closed",reason:"client"}))}getConnectionState(){return this.#p}subscribeConnection(e){return this.#l.add(e),P(e,this.#p),()=>{this.#l.delete(e)}}async listThreads(e={},t){return this.#O(s.threadList,e,t)}async createThread(e={},t){const n=await this.#O(s.threadCreate,{...e,requestId:this.#c.createUuid()},t),i=this.#F(n.thread.id);return await i.refresh(t).catch(()=>{}),i}async openThread(e,t){const n=await this.#O(s.threadOpen,{threadId:e},t),i=this.#F(e);return i.applySnapshot(n),i}async startTurn(e,t,n){return this.#O(s.turnStart,{requestId:this.#c.createUuid(),threadId:e,turnId:this.#c.createUuid(),input:{text:t}},n)}async cancelTurn(e,t,n){return this.#O(s.turnCancel,{requestId:this.#c.createUuid(),threadId:e,turnId:t},n)}async respondToInteraction(e,t,n){const r=i(e,t);return this.#O(s.interactionCandidate,r,n)}async getThreadCapabilities(e,t){return this.#O("thread.capabilities",{threadId:e},t)}getOperationResult(e,t,s){if("1.1"===this.#f)return Promise.reject(T(f.protocolError,"App results require Relay Wire 1.2",!1));const n=`${this.#C}:${this.#m}:${e}:${t}`;if(void 0===s){const e=this.#v.get(n);if(e)return e}const i=this.#O("operation.result.get",{threadId:e,operationId:t},s);return void 0===s&&(this.#v.set(n,i),i.finally(()=>{this.#v.get(n)===i&&this.#v.delete(n)}).catch(()=>{})),i}async getThreadSnapshot(e,t){return this.#O(s.threadSnapshot,{threadId:e,limit:100},t)}async#W(e,t){const s=t??this.#E;if(!Number.isFinite(s)||s<=0)throw new TypeError("timeoutMs must be a positive finite number");const n=new AbortController;this.#w=n;let i=!1;const r=()=>{n.abort()};e?.addEventListener("abort",r,{once:!0}),!0===e?.aborted&&n.abort();const o=this.#c.scheduler.setTimer(()=>{i=!0,n.abort()},s),a=new Promise((e,t)=>{const s=()=>{t(T(i?f.requestTimeout:f.aborted,i?"Relay session connection timed out":"Relay session request was aborted",i)),this.#y?.close(k.normal,"session attempt cancelled")};n.signal.aborted?s():n.signal.addEventListener("abort",s,{once:!0})});try{await Promise.race([this.#j(n.signal),a])}finally{this.#c.scheduler.clearTimer(o),e?.removeEventListener("abort",r),this.#w===n&&(this.#w=void 0)}}async#j(e){try{let t;try{t=await this.#a.getSession({signal:e,supportedRelayProtocolVersions:this.#a.relayProtocolVersions??["1.2","1.1"]})}catch(t){if(e.aborted)throw T(f.aborted,"Relay session request was aborted",!1);throw E(t)}if(e.aborted)throw T(f.aborted,"Relay session request was aborted",!1);const s=y.safeParse(t);if(!s.success)throw T(f.invalidSession,"Session endpoint returned an invalid Relay session",!1);if(Date.parse(s.data.expiresAt)<=this.#c.scheduler.now())throw T(f.invalidSession,"Session endpoint returned an expired Relay session",!1);this.#x("superseded relay session");const n=this.#c.createWebSocket(s.data.connectUrl);this.#y=n,await this.#L(n)}catch(e){throw E(e)}}#L(e){return new Promise((t,s)=>{const n={ready:!1,settled:!1},i=e=>{n.settled||(n.settled=!0,s(e))};e.setHandlers({onOpen:()=>{},onMessage:s=>{if(!n.ready||this.#y===e)try{const e=M(s);if(!n.ready){const s=A(e);if(void 0!==this.#m&&this.#m!==s.workspaceId)throw T(f.protocolError,"Relay session changed the bound Workspace",!1);return this.#m=s.workspaceId,this.#f=s.relayProtocolVersion,this.#v.clear(),n.ready=!0,n.settled=!0,this.#S=0,this.#T=!0,this.#M({status:"connected",workspaceStatus:s.workspaceStatus}),this.#U(),"online"===s.workspaceStatus&&this.#z(),void t()}this.#V(e)}catch(t){const s=E(t);n.ready?this.#$(s):i(s),e.close(k.invalidFrame,"invalid relay frame")}},onClose:()=>{const t=this.#y===e;t&&(this.#y=void 0),n.ready?t&&this.#N():i(T(f.transportError,"Relay connection closed before session.ready",!0))},onError:()=>{n.ready||i(T(f.transportError,"Relay WebSocket failed before session.ready",!0))}})})}#V(e){const t=p.safeParse(e);if(t.success)return void this.#G(t.data);const s=c.safeParse(e);if(!s.success)throw T(f.protocolError,"Relay sent an invalid Control 1.0 or Wire 1.1 frame",!1);this.#H(s.data)}#G(e){if("session.ready"===e.type)throw T(f.protocolError,"session.ready may only be the first frame",!1);if("workspace.status"===e.type){this.#D(e.workspaceId);const t=this.#p,s="connected"===t.status&&"offline"===t.workspaceStatus&&"online"===e.status;return this.#M({status:"connected",workspaceStatus:e.status}),s&&(this.#T=!0,this.#J()),void("online"===e.status&&this.#z())}const t=new RelayClientError({kind:"session",code:e.code,message:`Relay session failed: ${e.code}`,retryable:e.retryable});if(e.retryable)this.#y?.close(k.sessionRetryable,"retryable relay session error");else{this.#I=!0,this.#B(!0);for(const e of this.#d.values())e.applyError(t.details);this.#M({status:"closed",reason:"session"}),this.#y?.close(k.sessionFatal,"non-retryable relay session error")}}#H(e){if(e.type!==t.runtimeResponse){if(e.type===t.runtimeGap)return this.#D(e.workspaceId),this.#Q(e.throughRelaySequence),void this.#K(e.throughRelaySequence);if(e.type!==t.runtimeEvent&&e.type!==t.interactionRequest&&e.type!==t.interactionResolved&&e.type!==t.interactionCancelled)throw T(f.protocolError,`Relay sent disallowed Browser inbound frame: ${e.type}`,!1);this.#X({relaySequence:e.relaySequence,message:e})}else this.#Y(e)}#Y(t){this.#D(t.workspaceId);const s=this.#h.get(t.requestId);if(void 0!==s){if(void 0!==t.error){const n=t.error.code===e.remoteRequestDenied?"Remote request denied":t.error.message;return void this.#Z(s,new RelayClientError({kind:"remote",code:t.error.code,message:n,retryable:t.error.retryable}))}if(void 0!==t.result)try{const e=o(this.#f,s.method,t.result);this.#Z(s,void 0,e)}catch{this.#Z(s,T(f.protocolError,`Relay returned an invalid ${s.method} result`,!1))}else this.#Z(s,T(f.protocolError,"runtime.response contains neither result nor error",!1))}}#X(e){if(this.#D(e.message.workspaceId),this.#Q(e.relaySequence),e.relaySequence<=this.#q)this.#U();else if(this.#k)this.#u.set(e.relaySequence,e);else{if(e.relaySequence!==this.#q+1)return this.#u.set(e.relaySequence,e),void this.#K(e.relaySequence-1);this.#_(e.message),this.#q=e.relaySequence,this.#U()}}#_(e){const s=e.type===t.runtimeEvent?e.event.threadId:e.threadId,n=this.#F(s);e.type===t.runtimeEvent?n.applyRuntimeEvent(e):e.type===t.interactionRequest?n.applyInteractionRequest(e):n.applyInteractionTerminal(e)}#K(e){if(e<=this.#q)return void this.#U();if(this.#k)return;this.#k=!0;const t=e,s=this.#C,n=[...this.#d.values()].map(async e=>e.refresh());Promise.all(n).then(()=>{if(this.#C===s){this.#q=t;for(const e of[...this.#u.keys()])e<=t&&this.#u.delete(e);this.#k=!1,this.#U(),this.#ee()}}).catch(()=>{this.#C===s&&(this.#k=!1,this.#y?.close(k.sessionRetryable,"snapshot recovery failed"))})}#Q(e){this.#T&&(this.#T=!1,e>this.#q||(this.#C+=1,this.#q=q,this.#u.clear(),this.#k=!1,this.#J()))}#J(){for(const e of this.#d.values())e.refresh().catch(()=>{})}#ee(){for(;!this.#k;){const e=this.#q+1,t=this.#u.get(e);if(void 0===t){const t=[...this.#u.keys()].sort((e,t)=>e-t)[0];return void(void 0!==t&&t>e&&this.#K(t-1))}this.#u.delete(e),this.#_(t.message),this.#q=e,this.#U()}}#U(){const e=this.#m,s=this.#y;if(void 0===e||1!==s?.readyState)return;const n=a.parse({type:t.runtimeAck,workspaceId:e,throughRelaySequence:this.#q});s.send(JSON.stringify(n))}#N(){this.#b||this.#I||(this.#te(),this.#se())}#se(){if(void 0!==this.#R||this.#b||this.#I)return;this.#S+=1;const e=this.#c.reconnectDelayMs(this.#S),t=new Date(this.#c.scheduler.now()+e).toISOString();this.#M({status:"reconnecting",attempt:this.#S,retryAt:t}),this.#R=this.#c.scheduler.setTimer(()=>{this.#R=void 0,this.#b||this.#I||void 0!==this.#g||"connected"===this.#p.status||this.#A().catch(e=>{if(this.#b)return;if(!E(e).details.retryable)return this.#I=!0,this.#B(!0),void this.#M({status:"closed",reason:"session"});this.#se()})},e)}#A(e,t){const s=this.#W(e,t).finally(()=>{this.#g===s&&(this.#g=void 0)});return this.#g=s,s}#x(e){const t=this.#y;void 0!==t&&(this.#y=void 0,t.close(k.normal,e))}#P(){void 0!==this.#R&&(this.#c.scheduler.clearTimer(this.#R),this.#R=void 0)}#z(){for(const e of this.#h.values())e.mutation&&this.#ne(e)}#O(e,s,i){if("connected"!==this.#p.status||"online"!==this.#p.workspaceStatus||void 0===this.#m){const e="connected"===this.#p.status&&"offline"===this.#p.workspaceStatus;return Promise.reject(T(e?f.workspaceOffline:f.connectionUnavailable,e?"The local Workspace is offline":"Relay is not connected",!0))}if(!0===i?.signal?.aborted)return Promise.reject(T(f.aborted,"Relay request was aborted",!1));const o=r("1.2",e,s),a=l.parse(this.#c.createUuid()),c=h.parse({type:t.runtimeRequest,requestId:a,workspaceId:this.#m,method:e,params:o}),d=i?.timeoutMs??this.#E;if(!Number.isFinite(d)||d<=0)return Promise.reject(new TypeError("timeoutMs must be a positive finite number"));const u="mutation"===n[e];return new Promise((t,s)=>{const n=i?.signal?()=>{const e=this.#h.get(a);if(void 0===e)return;const t=e.mutation&&e.sent;this.#Z(e,T(t?f.outcomeUnknown:f.aborted,t?"Mutation outcome is unknown after Browser cancellation":"Relay request was aborted",!1))}:void 0,r={requestId:a,method:e,frame:JSON.stringify(c),mutation:u,sent:!1,resolve:e=>{t(e)},reject:s,signal:i?.signal,abortListener:n,timeoutHandle:void 0};r.timeoutHandle=this.#c.scheduler.setTimer(()=>{const e=this.#h.get(a);if(void 0===e)return;const t=e.mutation&&e.sent;this.#Z(e,T(t?f.outcomeUnknown:f.requestTimeout,t?"Mutation outcome is unknown after Relay timeout":"Relay request timed out",!t))},d),i?.signal?.addEventListener("abort",n??(()=>{}),{once:!0}),this.#h.set(a,r),this.#ne(r)})}#ne(e){const t=this.#y;1===t?.readyState&&"connected"===this.#p.status&&"online"===this.#p.workspaceStatus&&(t.send(e.frame),e.sent=!0)}#Z(e,t,s){this.#h.delete(e.requestId)&&(void 0!==e.timeoutHandle&&this.#c.scheduler.clearTimer(e.timeoutHandle),void 0!==e.signal&&void 0!==e.abortListener&&e.signal.removeEventListener("abort",e.abortListener),void 0!==t?e.reject(t):e.resolve(s))}#te(){for(const e of[...this.#h.values()])e.mutation||this.#Z(e,T(f.transportError,"Relay disconnected before the query completed",!0))}#B(e){for(const t of[...this.#h.values()]){const s=e&&t.mutation&&t.sent;this.#Z(t,T(s?f.outcomeUnknown:f.closed,s?"Mutation outcome is unknown after Relay closed":"Relay client is closed",!1))}}#D(e){if(this.#m!==e)throw T(f.protocolError,"Relay frame does not match the bound Workspace",!1)}#F(e){const t=this.#d.get(e);if(void 0!==t)return t;const s=new RelayThreadImpl(this,e);return this.#d.set(e,s),s}#M(e){this.#p=w.parse(e);for(const e of this.#l)P(e,this.#p)}#$(e){this.#I=!0,this.#B(!0);for(const t of this.#d.values())t.applyError(e.details);this.#M({status:"closed",reason:"protocol"})}}export function createRelayClientWithRuntime(e,t){return new RelayClientImpl(e,t)}export function createRelayClient(e){return createRelayClientWithRuntime(e,S)}

package/dist/schemas.d.ts

@@ -291,6 +291,12 @@ export declare const relayTurnStateSchema: z.ZodDiscriminatedUnion<[z.ZodReadonl
 }, z.core.$strict>>]>;
 export declare const relayThreadViewSchema: z.ZodDiscriminatedUnion<[z.ZodReadonly<z.ZodObject<{
     snapshot: z.ZodNull;
+    contextRecovery: z.ZodDefault<z.ZodNullable<z.ZodReadonly<z.ZodObject<{
+        checkpointId: z.ZodString;
+        required: z.ZodBoolean;
+        unextracted: z.ZodBoolean;
+        requiredItemCount: z.ZodNumber;
+    }, z.core.$strict>>>>;
     threadId: z.core.$ZodBranded<z.ZodString, "ThreadId">;
     liveAssistantMessages: z.ZodReadonly<z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodReadonly<z.ZodObject<{
         status: z.ZodLiteral<"streaming">;
@@ -497,7 +503,7 @@ export declare const relayThreadViewSchema: z.ZodDiscriminatedUnion<[z.ZodReadon
     }, z.core.$strict>>]>;
     status: z.ZodLiteral<"loading">;
 }, z.core.$strict>>, z.ZodReadonly<z.ZodObject<{
-    snapshot: z.ZodReadonly<z.ZodObject<{
+    snapshot: z.ZodUnion<readonly [z.ZodReadonly<z.ZodObject<{
         thread: z.ZodReadonly<z.ZodObject<{
             id: z.core.$ZodBranded<z.ZodString, "ThreadId">;
             title: z.ZodOptional<z.ZodString>;
@@ -584,7 +590,106 @@ export declare const relayThreadViewSchema: z.ZodDiscriminatedUnion<[z.ZodReadon
             }, z.core.$strict>>>;
             nextBeforeSequence: z.ZodNullable<z.ZodNumber>;
         }, z.core.$strict>>;
-    }, z.core.$strict>>;
+        contextRecovery: z.ZodNullable<z.ZodReadonly<z.ZodObject<{
+            checkpointId: z.ZodString;
+            required: z.ZodBoolean;
+            unextracted: z.ZodBoolean;
+            requiredItemCount: z.ZodNumber;
+        }, z.core.$strict>>>;
+    }, z.core.$strict>>, z.ZodReadonly<z.ZodObject<{
+        thread: z.ZodReadonly<z.ZodObject<{
+            id: z.core.$ZodBranded<z.ZodString, "ThreadId">;
+            title: z.ZodOptional<z.ZodString>;
+            model: z.ZodOptional<z.ZodString>;
+            createdAt: z.ZodString;
+            updatedAt: z.ZodString;
+            messageCount: z.ZodNumber;
+        }, z.core.$strict>>;
+        messages: z.ZodReadonly<z.ZodObject<{
+            items: z.ZodArray<z.ZodReadonly<z.ZodObject<{
+                sequence: z.ZodNumber;
+                role: z.ZodEnum<{
+                    user: "user";
+                    assistant: "assistant";
+                }>;
+                createdAt: z.ZodString;
+                parts: z.ZodArray<z.ZodReadonly<z.ZodObject<{
+                    type: z.ZodLiteral<"text">;
+                    text: z.ZodString;
+                }, z.core.$strict>>>;
+            }, z.core.$strict>>>;
+            nextBeforeSequence: z.ZodNullable<z.ZodNumber>;
+        }, z.core.$strict>>;
+        activeTurn: z.ZodOptional<z.ZodReadonly<z.ZodObject<{
+            id: z.core.$ZodBranded<z.ZodString, "TurnId">;
+            status: z.ZodEnum<{
+                running: "running";
+                cancelling: "cancelling";
+            }>;
+            startedAt: z.ZodString;
+        }, z.core.$strict>>>;
+        pendingApprovals: z.ZodArray<z.ZodReadonly<z.ZodObject<{
+            id: z.core.$ZodBranded<z.ZodString, "ApprovalId">;
+            turnId: z.core.$ZodBranded<z.ZodString, "TurnId">;
+            agentName: z.ZodString;
+            toolName: z.ZodString;
+            preview: z.ZodJSONSchema;
+            reason: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>>>;
+        transcriptCompleteness: z.ZodEnum<{
+            complete: "complete";
+            legacy_snapshot: "legacy_snapshot";
+        }>;
+        operations: z.ZodReadonly<z.ZodObject<{
+            items: z.ZodArray<z.ZodReadonly<z.ZodObject<{
+                id: z.core.$ZodBranded<z.ZodString, "OperationId">;
+                sequence: z.ZodNumber;
+                toolCallId: z.ZodString;
+                agentName: z.ZodString;
+                toolName: z.ZodString;
+                createdAt: z.ZodString;
+                outcome: z.ZodReadonly<z.ZodObject<{
+                    kind: z.ZodEnum<{
+                        success: "success";
+                        user_rejected: "user_rejected";
+                        policy_denied: "policy_denied";
+                        invalid_input: "invalid_input";
+                        cancelled: "cancelled";
+                        tool_failed: "tool_failed";
+                    }>;
+                    reason: z.ZodOptional<z.ZodString>;
+                }, z.core.$strict>>;
+                display: z.ZodJSONSchema;
+                appOutput: z.ZodOptional<z.ZodReadonly<z.ZodDiscriminatedUnion<[z.ZodReadonly<z.ZodObject<{
+                    status: z.ZodLiteral<"rejected">;
+                    reason: z.ZodEnum<{
+                        credential_field: "credential_field";
+                        credential_value: "credential_value";
+                    }>;
+                    field: z.ZodOptional<z.ZodString>;
+                }, z.core.$strict>>, z.ZodObject<{
+                    status: z.ZodLiteral<"available">;
+                    schemaId: z.ZodString;
+                    schemaVersion: z.ZodNumber;
+                }, z.core.$strict>, z.ZodObject<{
+                    status: z.ZodEnum<{
+                        not_provided: "not_provided";
+                        invalid: "invalid";
+                        too_large: "too_large";
+                        expired: "expired";
+                        denied: "denied";
+                    }>;
+                }, z.core.$strict>]>>>;
+            }, z.core.$strict>>>;
+            nextBeforeSequence: z.ZodNullable<z.ZodNumber>;
+        }, z.core.$strict>>;
+    }, z.core.$strict>>]>;
+    contextRecovery: z.ZodDefault<z.ZodNullable<z.ZodReadonly<z.ZodObject<{
+        checkpointId: z.ZodString;
+        required: z.ZodBoolean;
+        unextracted: z.ZodBoolean;
+        requiredItemCount: z.ZodNumber;
+    }, z.core.$strict>>>>;
     threadId: z.core.$ZodBranded<z.ZodString, "ThreadId">;
     liveAssistantMessages: z.ZodReadonly<z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodReadonly<z.ZodObject<{
         status: z.ZodLiteral<"streaming">;
@@ -791,7 +896,100 @@ export declare const relayThreadViewSchema: z.ZodDiscriminatedUnion<[z.ZodReadon
     }, z.core.$strict>>]>;
     status: z.ZodLiteral<"ready">;
 }, z.core.$strict>>, z.ZodReadonly<z.ZodObject<{
-    snapshot: z.ZodNullable<z.ZodReadonly<z.ZodObject<{
+    snapshot: z.ZodNullable<z.ZodUnion<readonly [z.ZodReadonly<z.ZodObject<{
+        thread: z.ZodReadonly<z.ZodObject<{
+            id: z.core.$ZodBranded<z.ZodString, "ThreadId">;
+            title: z.ZodOptional<z.ZodString>;
+            model: z.ZodOptional<z.ZodString>;
+            createdAt: z.ZodString;
+            updatedAt: z.ZodString;
+            messageCount: z.ZodNumber;
+        }, z.core.$strict>>;
+        messages: z.ZodReadonly<z.ZodObject<{
+            items: z.ZodArray<z.ZodReadonly<z.ZodObject<{
+                sequence: z.ZodNumber;
+                role: z.ZodEnum<{
+                    user: "user";
+                    assistant: "assistant";
+                }>;
+                createdAt: z.ZodString;
+                parts: z.ZodArray<z.ZodReadonly<z.ZodObject<{
+                    type: z.ZodLiteral<"text">;
+                    text: z.ZodString;
+                }, z.core.$strict>>>;
+            }, z.core.$strict>>>;
+            nextBeforeSequence: z.ZodNullable<z.ZodNumber>;
+        }, z.core.$strict>>;
+        activeTurn: z.ZodOptional<z.ZodReadonly<z.ZodObject<{
+            id: z.core.$ZodBranded<z.ZodString, "TurnId">;
+            status: z.ZodEnum<{
+                running: "running";
+                cancelling: "cancelling";
+            }>;
+            startedAt: z.ZodString;
+        }, z.core.$strict>>>;
+        pendingApprovals: z.ZodArray<z.ZodReadonly<z.ZodObject<{
+            id: z.core.$ZodBranded<z.ZodString, "ApprovalId">;
+            turnId: z.core.$ZodBranded<z.ZodString, "TurnId">;
+            agentName: z.ZodString;
+            toolName: z.ZodString;
+            preview: z.ZodJSONSchema;
+            reason: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>>>;
+        transcriptCompleteness: z.ZodEnum<{
+            complete: "complete";
+            legacy_snapshot: "legacy_snapshot";
+        }>;
+        operations: z.ZodReadonly<z.ZodObject<{
+            items: z.ZodArray<z.ZodReadonly<z.ZodObject<{
+                id: z.core.$ZodBranded<z.ZodString, "OperationId">;
+                sequence: z.ZodNumber;
+                toolCallId: z.ZodString;
+                agentName: z.ZodString;
+                toolName: z.ZodString;
+                createdAt: z.ZodString;
+                outcome: z.ZodReadonly<z.ZodObject<{
+                    kind: z.ZodEnum<{
+                        success: "success";
+                        user_rejected: "user_rejected";
+                        policy_denied: "policy_denied";
+                        invalid_input: "invalid_input";
+                        cancelled: "cancelled";
+                        tool_failed: "tool_failed";
+                    }>;
+                    reason: z.ZodOptional<z.ZodString>;
+                }, z.core.$strict>>;
+                display: z.ZodJSONSchema;
+                appOutput: z.ZodOptional<z.ZodReadonly<z.ZodDiscriminatedUnion<[z.ZodReadonly<z.ZodObject<{
+                    status: z.ZodLiteral<"rejected">;
+                    reason: z.ZodEnum<{
+                        credential_field: "credential_field";
+                        credential_value: "credential_value";
+                    }>;
+                    field: z.ZodOptional<z.ZodString>;
+                }, z.core.$strict>>, z.ZodObject<{
+                    status: z.ZodLiteral<"available">;
+                    schemaId: z.ZodString;
+                    schemaVersion: z.ZodNumber;
+                }, z.core.$strict>, z.ZodObject<{
+                    status: z.ZodEnum<{
+                        not_provided: "not_provided";
+                        invalid: "invalid";
+                        too_large: "too_large";
+                        expired: "expired";
+                        denied: "denied";
+                    }>;
+                }, z.core.$strict>]>>>;
+            }, z.core.$strict>>>;
+            nextBeforeSequence: z.ZodNullable<z.ZodNumber>;
+        }, z.core.$strict>>;
+        contextRecovery: z.ZodNullable<z.ZodReadonly<z.ZodObject<{
+            checkpointId: z.ZodString;
+            required: z.ZodBoolean;
+            unextracted: z.ZodBoolean;
+            requiredItemCount: z.ZodNumber;
+        }, z.core.$strict>>>;
+    }, z.core.$strict>>, z.ZodReadonly<z.ZodObject<{
         thread: z.ZodReadonly<z.ZodObject<{
             id: z.core.$ZodBranded<z.ZodString, "ThreadId">;
             title: z.ZodOptional<z.ZodString>;
@@ -878,7 +1076,7 @@ export declare const relayThreadViewSchema: z.ZodDiscriminatedUnion<[z.ZodReadon
             }, z.core.$strict>>>;
             nextBeforeSequence: z.ZodNullable<z.ZodNumber>;
         }, z.core.$strict>>;
-    }, z.core.$strict>>>;
+    }, z.core.$strict>>]>>;
     error: z.ZodDiscriminatedUnion<[z.ZodReadonly<z.ZodObject<{
         code: z.ZodEnum<{
             readonly aborted: "ABORTED";
@@ -912,6 +1110,12 @@ export declare const relayThreadViewSchema: z.ZodDiscriminatedUnion<[z.ZodReadon
         retryable: z.ZodBoolean;
         kind: z.ZodLiteral<"remote">;
     }, z.core.$strict>>]>;
+    contextRecovery: z.ZodDefault<z.ZodNullable<z.ZodReadonly<z.ZodObject<{
+        checkpointId: z.ZodString;
+        required: z.ZodBoolean;
+        unextracted: z.ZodBoolean;
+        requiredItemCount: z.ZodNumber;
+    }, z.core.$strict>>>>;
     threadId: z.core.$ZodBranded<z.ZodString, "ThreadId">;
     liveAssistantMessages: z.ZodReadonly<z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodReadonly<z.ZodObject<{
         status: z.ZodLiteral<"streaming">;

package/dist/schemas.js

@@ -1 +1 @@
-import{relayInteractionRequestSchemaV11 as t,relayRequestMethodSchemasV12 as e}from"@roll-agent/relay-protocol";import{relayClientErrorCodeSchema as r}from"@roll-agent/relay-protocol/control";import{z as n}from"zod/v4";const a=e["thread.open"].params.def.innerType.shape.threadId,o=e["turn.cancel"].params.def.innerType.shape.turnId,s=e["thread.snapshot"].result;export const RELAY_CONNECTION_STATUSES={idle:"idle",connecting:"connecting",connected:"connected",reconnecting:"reconnecting",closed:"closed"};export const relayConnectionStateSchema=n.discriminatedUnion("status",[n.object({status:n.literal(RELAY_CONNECTION_STATUSES.idle)}).strict().readonly(),n.object({status:n.literal(RELAY_CONNECTION_STATUSES.connecting),attempt:n.number().int().positive()}).strict().readonly(),n.object({status:n.literal(RELAY_CONNECTION_STATUSES.connected),workspaceStatus:n.enum(["online","offline"])}).strict().readonly(),n.object({status:n.literal(RELAY_CONNECTION_STATUSES.reconnecting),attempt:n.number().int().positive(),retryAt:n.string().datetime({offset:!0})}).strict().readonly(),n.object({status:n.literal(RELAY_CONNECTION_STATUSES.closed),reason:n.enum(["client","session","transport","protocol"])}).strict().readonly()]);export const RELAY_CLIENT_TRANSPORT_ERROR_CODES={aborted:"ABORTED",closed:"CLIENT_CLOSED",connectionUnavailable:"CONNECTION_UNAVAILABLE",invalidSession:"INVALID_SESSION",outcomeUnknown:"OUTCOME_UNKNOWN",protocolError:"PROTOCOL_ERROR",requestTimeout:"REQUEST_TIMEOUT",transportError:"TRANSPORT_ERROR",workspaceOffline:"WORKSPACE_OFFLINE"};export const relayClientTransportErrorCodeSchema=n.enum(RELAY_CLIENT_TRANSPORT_ERROR_CODES);const i={message:n.string(),retryable:n.boolean()};export const relayClientErrorDetailsSchema=n.discriminatedUnion("kind",[n.object({kind:n.literal("transport"),...i,code:relayClientTransportErrorCodeSchema}).strict().readonly(),n.object({kind:n.literal("session"),...i,code:r}).strict().readonly(),n.object({kind:n.literal("remote"),...i,code:n.string().min(1)}).strict().readonly()]);export const relayLiveAssistantMessageSchema=n.discriminatedUnion("status",[n.object({status:n.literal("streaming"),streamId:n.string().uuid(),text:n.string()}).strict().readonly(),n.object({status:n.literal("completed"),streamId:n.string().uuid(),text:n.string()}).strict().readonly()]);const l={interactionId:t.options[0].def.innerType.shape.interactionId,threadId:a,turnId:o,method:t.options[0].def.innerType.shape.method.or(t.options[1].def.innerType.shape.method)};export const relayInteractionStateSchema=n.discriminatedUnion("status",[n.object({status:n.literal("pending"),request:t}).strict().readonly(),n.object({status:n.literal("responding"),request:t}).strict().readonly(),n.object({status:n.literal("resolved"),...l}).strict().readonly(),n.object({status:n.literal("cancelled"),...l}).strict().readonly()]);export const relayTurnStateSchema=n.discriminatedUnion("status",[n.object({status:n.literal("idle")}).strict().readonly(),n.object({status:n.literal("running"),turnId:o}).strict().readonly(),n.object({status:n.literal("cancelling"),turnId:o}).strict().readonly(),n.object({status:n.literal("completed"),turnId:o}).strict().readonly(),n.object({status:n.literal("cancelled"),turnId:o}).strict().readonly(),n.object({status:n.literal("failed"),turnId:o,stage:n.enum(["bootstrap","plan","execute"])}).strict().readonly()]);const c={threadId:a,liveAssistantMessages:n.array(relayLiveAssistantMessageSchema).readonly(),interactions:n.array(relayInteractionStateSchema).readonly(),turn:relayTurnStateSchema};export const relayThreadViewSchema=n.discriminatedUnion("status",[n.object({status:n.literal("loading"),...c,snapshot:n.null()}).strict().readonly(),n.object({status:n.literal("ready"),...c,snapshot:s}).strict().readonly(),n.object({status:n.literal("error"),...c,snapshot:s.nullable(),error:relayClientErrorDetailsSchema}).strict().readonly()]);export function getPendingInteractionRequest(t){return"pending"===t.status||"responding"===t.status?t.request:void 0}
+import{relayInteractionRequestSchemaV11 as t,relayRequestMethodSchemasV12 as e,relayThreadSnapshotSchemaV13 as r}from"@roll-agent/relay-protocol";import{relayClientErrorCodeSchema as n}from"@roll-agent/relay-protocol/control";import{z as o}from"zod/v4";const a=e["thread.open"].params.def.innerType.shape.threadId,s=e["turn.cancel"].params.def.innerType.shape.turnId,i=o.union([r,e["thread.snapshot"].result]);export const RELAY_CONNECTION_STATUSES={idle:"idle",connecting:"connecting",connected:"connected",reconnecting:"reconnecting",closed:"closed"};export const relayConnectionStateSchema=o.discriminatedUnion("status",[o.object({status:o.literal(RELAY_CONNECTION_STATUSES.idle)}).strict().readonly(),o.object({status:o.literal(RELAY_CONNECTION_STATUSES.connecting),attempt:o.number().int().positive()}).strict().readonly(),o.object({status:o.literal(RELAY_CONNECTION_STATUSES.connected),workspaceStatus:o.enum(["online","offline"])}).strict().readonly(),o.object({status:o.literal(RELAY_CONNECTION_STATUSES.reconnecting),attempt:o.number().int().positive(),retryAt:o.string().datetime({offset:!0})}).strict().readonly(),o.object({status:o.literal(RELAY_CONNECTION_STATUSES.closed),reason:o.enum(["client","session","transport","protocol"])}).strict().readonly()]);export const RELAY_CLIENT_TRANSPORT_ERROR_CODES={aborted:"ABORTED",closed:"CLIENT_CLOSED",connectionUnavailable:"CONNECTION_UNAVAILABLE",invalidSession:"INVALID_SESSION",outcomeUnknown:"OUTCOME_UNKNOWN",protocolError:"PROTOCOL_ERROR",requestTimeout:"REQUEST_TIMEOUT",transportError:"TRANSPORT_ERROR",workspaceOffline:"WORKSPACE_OFFLINE"};export const relayClientTransportErrorCodeSchema=o.enum(RELAY_CLIENT_TRANSPORT_ERROR_CODES);const l={message:o.string(),retryable:o.boolean()};export const relayClientErrorDetailsSchema=o.discriminatedUnion("kind",[o.object({kind:o.literal("transport"),...l,code:relayClientTransportErrorCodeSchema}).strict().readonly(),o.object({kind:o.literal("session"),...l,code:n}).strict().readonly(),o.object({kind:o.literal("remote"),...l,code:o.string().min(1)}).strict().readonly()]);export const relayLiveAssistantMessageSchema=o.discriminatedUnion("status",[o.object({status:o.literal("streaming"),streamId:o.string().uuid(),text:o.string()}).strict().readonly(),o.object({status:o.literal("completed"),streamId:o.string().uuid(),text:o.string()}).strict().readonly()]);const c={interactionId:t.options[0].def.innerType.shape.interactionId,threadId:a,turnId:s,method:t.options[0].def.innerType.shape.method.or(t.options[1].def.innerType.shape.method)};export const relayInteractionStateSchema=o.discriminatedUnion("status",[o.object({status:o.literal("pending"),request:t}).strict().readonly(),o.object({status:o.literal("responding"),request:t}).strict().readonly(),o.object({status:o.literal("resolved"),...c}).strict().readonly(),o.object({status:o.literal("cancelled"),...c}).strict().readonly()]);export const relayTurnStateSchema=o.discriminatedUnion("status",[o.object({status:o.literal("idle")}).strict().readonly(),o.object({status:o.literal("running"),turnId:s}).strict().readonly(),o.object({status:o.literal("cancelling"),turnId:s}).strict().readonly(),o.object({status:o.literal("completed"),turnId:s}).strict().readonly(),o.object({status:o.literal("cancelled"),turnId:s}).strict().readonly(),o.object({status:o.literal("failed"),turnId:s,stage:o.enum(["bootstrap","plan","execute"])}).strict().readonly()]);const d={contextRecovery:r.def.innerType.shape.contextRecovery.default(null),threadId:a,liveAssistantMessages:o.array(relayLiveAssistantMessageSchema).readonly(),interactions:o.array(relayInteractionStateSchema).readonly(),turn:relayTurnStateSchema};export const relayThreadViewSchema=o.discriminatedUnion("status",[o.object({status:o.literal("loading"),...d,snapshot:o.null()}).strict().readonly(),o.object({status:o.literal("ready"),...d,snapshot:i}).strict().readonly(),o.object({status:o.literal("error"),...d,snapshot:i.nullable(),error:relayClientErrorDetailsSchema}).strict().readonly()]);export function getPendingInteractionRequest(t){return"pending"===t.status||"responding"===t.status?t.request:void 0}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@roll-agent/relay-client",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "type": "module",
   "sideEffects": false,
   "repository": {
@@ -31,7 +31,7 @@
     "node": ">=22.6.0"
   },
   "dependencies": {
-    "@roll-agent/relay-protocol": "0.4.1",
+    "@roll-agent/relay-protocol": "0.5.0",
     "zod": "3.25.76"
   },
   "devDependencies": {