@modelprofile.com/flexharness 10.24.0 → 11.0.0

package/ts_chat_harness_server/interfaces.ts

@@ -2,7 +2,8 @@ import type * as plugins from './plugins.js';
 
 /**
  * Who a request is from, as the host established it: the tab, and the scope whose conversations it
- * may reach. A tab is named by both: the same tab id in two scopes names two tabs.
+ * may reach. A tab is named by both: the same tab id in two scopes names two tabs. The scope names
+ * the tab's reach; with a directory, the conversations it reaches may run in scopes of their own.
  */
 export interface IFlexHarnessChatCaller {
   /** the browser tab, a per-page secret; pushes and tool calls of its turns go to it */
@@ -29,12 +30,42 @@ export interface IFlexHarnessChatPeers {
 
 /** The running turn of a conversation: the tab that started it and the context it was sent with. */
 export interface IFlexHarnessChatTurn<TContext> {
+  /** the harness scope of the conversation */
   readonly scopeId: string;
   readonly sessionId: string;
-  readonly tabId: string;
+  /** the tab that started the turn; its tool calls go to it */
+  readonly tab: IFlexHarnessChatCaller;
   readonly context: TContext;
 }
 
+/** A conversation a tab reaches: where its session runs, and how its list shows it. */
+export interface IFlexHarnessChatConversation {
+  /** the harness scope of the conversation's session */
+  scopeId: string;
+  sessionId: string;
+  meta: plugins.IHarnessSessionMeta;
+  /** an imported conversation can only be read */
+  readOnly: boolean;
+}
+
+/**
+ * The conversations of the tabs: which a tab lists and reaches, and how they are created, renamed
+ * and deleted. Without one, a tab's conversations are the root sessions of its scope. A host whose
+ * conversations run in scopes of their own, or that keeps records of its own, gives the hub one and
+ * tells the tabs of every change of their lists with `hub.publishSessions()`.
+ */
+export interface IFlexHarnessChatDirectory {
+  /** The conversations the tab lists, most recent first. */
+  list(tab: IFlexHarnessChatCaller): Promise<plugins.IHarnessSessionMeta[]>;
+  /** A conversation the tab reaches, or null: one it does not reach reads as not found. */
+  find(tab: IFlexHarnessChatCaller, sessionId: string): Promise<IFlexHarnessChatConversation | null>;
+  /** Creates a conversation for the tab's first message; throw `FlexHarnessChatRequestError` to refuse. */
+  create(tab: IFlexHarnessChatCaller, init: { title: string }): Promise<IFlexHarnessChatConversation>;
+  rename(tab: IFlexHarnessChatCaller, conversation: IFlexHarnessChatConversation, title: string): Promise<plugins.IHarnessSessionMeta>;
+  /** Deletes a conversation; also one created for a message that was then refused. */
+  delete(tab: IFlexHarnessChatCaller, conversation: IFlexHarnessChatConversation): Promise<void>;
+}
+
 export interface IFlexHarnessChatLimits {
   /** A turn that runs longer is stopped. Default: 10 minutes. */
   turnTimeoutMs: number;
@@ -88,5 +119,7 @@ export interface IFlexHarnessChatHubOptions<TContext> {
   readContext(value: plugins.TJsonValue): TContext;
   /** The title of a conversation a message starts. Defaults to the message's first line. */
   titleOf?(send: plugins.IHarnessComposerSendDetail): string;
+  /** Where the tabs' conversations are. Defaults to the root sessions of the tab's scope. */
+  directory?: IFlexHarnessChatDirectory;
   limits?: Partial<IFlexHarnessChatLimits>;
 }

package/ts_chat_harness_server/plugins.ts

@@ -34,9 +34,6 @@ export type {
   IFlexExternalErrorContext,
   IFlexPromptQueueAdmission,
   IFlexSession,
-  IFlexSessionCreatedEvent,
-  IFlexSessionDeletedEvent,
-  IFlexSessionUpdatedEvent,
   TFlexExternalErrorProjector,
   TFlexHarnessEvent,
   TJsonValue,

package/ts_chat_harness_server/readme.md

@@ -42,20 +42,22 @@ const harness = new FlexHarness<IAppScope>({
 hub = new FlexHarnessChatHub<IEditorContext>({ harness, peers, readContext: parseEditorContext });
 ```
 
-The host keeps its harness, models, system prompt, tools and scopes. It authenticates every request and calls the hub with the caller it established: the tab and the scope the tab may reach. A conversation of another scope reads as not found. A tab is named by its scope and its id together: the same tab id in two scopes names two tabs, and `IFlexHarnessChatPeers.find()` receives both. Tab ids are per-page secrets all the same; a page never shares its own.
+The host keeps its harness, models, system prompt, tools and scopes. It authenticates every request and calls the hub with the caller it established: the tab and the scope the tab may reach. A conversation the tab does not reach reads as not found. A tab is named by its scope and its id together: the same tab id in two scopes names two tabs, and `IFlexHarnessChatPeers.find()` receives both. Tab ids are per-page secrets all the same; a page never shares its own.
 
 ## Conversations
 
-- `attach(caller)` lists the scope's conversations, newest first, and forgets what the tab followed. A tab attaches after loading and after every reconnect; conversations created, renamed or deleted afterwards reach it as `flexHarnessChatSessions` pushes.
+- `attach(caller)` lists the tab's conversations, newest first, and forgets what the tab followed. A tab attaches after loading and after every reconnect; conversations created, renamed or deleted afterwards reach it as list pushes (`IFlexHarnessChatPeer.sessions`, an `IFlexHarnessChatSessionsPush`).
 - `open(caller, { sessionId, subscriptionId })` follows a conversation. Its state reaches the tab as numbered `IFlexHarnessChatUpdate` pushes, starting with a `reset`: changed rows, streamed deltas, status, usage, pending permissions, undo and redo availability, and what became of steers. A tab follows one conversation at a time. An update the tab does not acknowledge makes the next change a `reset`; a tab that sees a gap in `seq` opens the conversation again.
 - `send(caller, { sessionId?, send, context })` starts a conversation without `sessionId`. While a turn runs, the message steers it; one the turn no longer takes waits up to `admissionWaitMs` for the ending turn and starts the next one. `readContext` checks the context the message is sent with; the turn carries it. The composer's model, account and effort choices are not used: the host's model resolver decides from the context.
-- `abort`, `respondToPermission`, `moveHistory` (FlexHarness undo and redo), `renameSession` and `deleteSession` act on a conversation of the caller's scope. An imported conversation can be read, not continued.
+- `abort`, `respondToPermission`, `moveHistory` (FlexHarness undo and redo), `renameSession` and `deleteSession` act on a conversation the caller reaches. An imported conversation can be read, not continued.
+
+Without a directory, a tab's conversations are the root sessions of its scope, and the harness's session events update the tabs' lists. A host that runs each conversation in a scope of its own, or keeps records of its own, passes `directory`, an `IFlexHarnessChatDirectory`: it lists the conversations a tab reaches, finds one by its session id (one the tab does not reach is null, and reads as not found), creates one for a message without `sessionId`, renames and deletes. The caller's `scopeId` is then the tab's reach; each conversation names the harness scope its session runs in, and the hub subscribes, runs turns and calls `turnOf` in that scope. A conversation created for a message that then never starts, for instance because its session does not exist, is deleted again through the directory. With a directory, the harness's session events no longer reach the lists: the host calls `hub.publishSessions(reach, { upserts, deletedIds })` for every change, and the tabs of that reach get it as a list push.
 
 Refusals are `FlexHarnessChatRequestError`s with a message for the person in the tab; FlexHarness refusals keep their message. Every other error stays an internal error.
 
 ## Turns and tools in the tab
 
-FlexHarness carries no per-prompt context, so the hub binds each turn to the tab that started it and the context it was sent with: `turnOf(scopeId, sessionId)`. A turn stops after `turnTimeoutMs`. `runClientTool(turn, request, options)` sends the call to that tab and answers with its output; it fails with `FlexHarnessChatTabUnavailableError` when the tab is gone or does not answer within `toolTimeoutMs`, and passes on the cancellation of an aborted turn.
+FlexHarness carries no per-prompt context, so the hub binds each turn to the tab that started it and the context it was sent with: `turnOf(scopeId, sessionId)` with the conversation's scope returns `{ scopeId, sessionId, tab, context }`, where `tab` is the caller that sent the message. A turn stops after `turnTimeoutMs`. `runClientTool(turn, request, options)` sends the call to that tab and answers with its output; it fails with `FlexHarnessChatTabUnavailableError` when the tab is gone or does not answer within `toolTimeoutMs`, and passes on the cancellation of an aborted turn.
 
 `createFlexHarnessChatErrorProjector()` is an `externalErrorProjector` for chat conversations: the host's own projection first, then a tab that is gone, model limits, the provider's HTTP status, and a fixed message, never a provider's response text.
 

package/ts_chat_harness_typedsocket/classes.clienttransport.ts

@@ -1,15 +1,36 @@
 import * as plugins from './plugins.js';
 import type {
+  IEvent_FlexHarnessChatPending,
+  IFlexHarnessChatCallerPayload,
   IReq_FlexHarnessChat,
-  IReq_FlexHarnessChatSessions,
+  IReq_FlexHarnessChatPull,
   IReq_FlexHarnessChatTool,
-  IReq_FlexHarnessChatUpdate,
 } from './interfaces.requests.js';
 
+/**
+ * What the transport uses of the tab's TypedSocket client. A `TypedSocket` client is one; a host
+ * whose own connection object carries the client can hand that object instead.
+ */
+export interface IFlexHarnessChatTypedSocketClient {
+  createTypedRequest<T extends plugins.typedrequestInterfaces.ITypedRequest>(
+    method: T['method'],
+  ): { fire(request: T['request']): Promise<T['response']> };
+  onEvent<TEvent extends plugins.typedsocket.ITypedSocketEvent>(
+    name: TEvent['name'],
+    handler: (payload: TEvent['payload']) => void | Promise<void>,
+  ): () => void;
+  readonly eventResyncSubject: {
+    subscribe(observer: (resync: plugins.typedsocket.ITypedSocketEventResync) => void): { unsubscribe(): void };
+  };
+  readonly statusSubject: {
+    subscribe(observer: (status: plugins.typedsocket.TConnectionStatus) => void): { unsubscribe(): void };
+  };
+}
+
 export interface IFlexHarnessChatTypedSocketTransportOptions {
   /** The tab's TypedSocket client. */
-  typedsocket: plugins.typedsocket.TypedSocket;
-  /** The router the client was created with; the transport adds its push handlers to it. */
+  typedsocket: IFlexHarnessChatTypedSocketClient;
+  /** The router the client was created with; the transport adds its tool handler to it. */
   typedrouter: plugins.typedrequest.TypedRouter;
   /** The tab: 16 random bytes in hex. Defaults to a new random id for this transport's lifetime. */
   tabId?: string;
@@ -17,15 +38,24 @@ export interface IFlexHarnessChatTypedSocketTransportOptions {
   callerToken?: () => string | undefined;
 }
 
+const PENDING_EVENT: IEvent_FlexHarnessChatPending['name'] = 'flexHarnessChatPending';
+
 /** 128 random bits as hex; `getRandomValues` works on plain http too, unlike `randomUUID`. */
 const randomTabId = (): string =>
   Array.from(globalThis.crypto.getRandomValues(new Uint8Array(16)), (byte) => byte.toString(16).padStart(2, '0')).join('');
 
-/** A `FlexHarnessChatClient` transport over the tab's TypedSocket client. */
+/** A push the tab's handler failed on is reported; the server counts it as delivered all the same. */
+const reportHandlerError = (error: unknown): void => console.warn('FLEXHARNESS_CHAT_PUSH_HANDLER_ERROR', error);
+
+/**
+ * A `FlexHarnessChatClient` transport over the tab's TypedSocket client. The hub's pushes wait on
+ * the server; an event says so, and the transport pulls them, one pull at a time. It also pulls
+ * whenever TypedSocket says events may have been missed: after every (re)connect, and after a gap.
+ */
 export class FlexHarnessChatTypedSocketTransport implements plugins.IFlexHarnessChatClientTransport {
   public readonly tabId: string;
 
-  private readonly socket: plugins.typedsocket.TypedSocket;
+  private readonly socket: IFlexHarnessChatTypedSocketClient;
   private readonly router: plugins.typedrequest.TypedRouter;
   private readonly callerToken: () => string | undefined;
 
@@ -40,35 +70,69 @@ export class FlexHarnessChatTypedSocketTransport implements plugins.IFlexHarness
     methodArg: TMethod,
     requestArg: plugins.TFlexHarnessChatRequest<TMethod>,
   ): Promise<plugins.TFlexHarnessChatResponse<TMethod>> {
-    const token = this.callerToken();
     return this.socket.createTypedRequest<IReq_FlexHarnessChat<TMethod>>(methodArg).fire({
       ...requestArg,
-      caller: { tabId: this.tabId, ...(token === undefined ? {} : { token }) },
+      caller: this.caller(),
     });
   }
 
   public listen(handlersArg: plugins.IFlexHarnessChatPushHandlers): () => void {
-    const pushes = new plugins.typedrequest.TypedRouter();
-    pushes.addTypedHandler(
-      new plugins.typedrequest.TypedHandler<IReq_FlexHarnessChatUpdate>('flexHarnessChatUpdate', async (pushArg) => {
-        handlersArg.update(pushArg);
-        return {};
-      }),
-    );
-    pushes.addTypedHandler(
-      new plugins.typedrequest.TypedHandler<IReq_FlexHarnessChatSessions>('flexHarnessChatSessions', async (pushArg) => {
-        handlersArg.sessions(pushArg);
-        return {};
-      }),
-    );
-    pushes.addTypedHandler(
+    let listening = true;
+    let pulling = false;
+    let pullAgain = false;
+    // one pull at a time; a signal that comes in meanwhile makes it pull once more
+    const pull = async (): Promise<void> => {
+      if (pulling) {
+        pullAgain = true;
+        return;
+      }
+      pulling = true;
+      try {
+        do {
+          pullAgain = false;
+          let pushes: IReq_FlexHarnessChatPull['response']['pushes'];
+          try {
+            ({ pushes } = await this.socket
+              .createTypedRequest<IReq_FlexHarnessChatPull>('flexHarnessChatPull')
+              .fire({ caller: this.caller() }));
+          } catch {
+            // the pushes keep waiting for the next pull; one the server gives up on makes the hub start over
+            return;
+          }
+          for (const push of pushes) {
+            if (!listening) return;
+            // a handler that throws takes nothing from the pushes after it
+            try {
+              if ('update' in push) handlersArg.update(push.update);
+              else handlersArg.sessions(push.sessions);
+            } catch (error) {
+              reportHandlerError(error);
+            }
+          }
+        } while (pullAgain && listening);
+      } finally {
+        pulling = false;
+      }
+    };
+    const tools = new plugins.typedrequest.TypedRouter();
+    tools.addTypedHandler(
       new plugins.typedrequest.TypedHandler<IReq_FlexHarnessChatTool>('flexHarnessChatTool', async (requestArg, toolsArg) => ({
         // the server cancels the request when the turn stops or the call times out; the handler then
         // settles at once, since TypedSocket fails a connection whose handlers outlive their requests
         output: await handlersArg.tool(requestArg, toolsArg?.abortSignal),
       })),
     );
-    return this.router.addTypedRouter(pushes);
+    const removeTools = this.router.addTypedRouter(tools);
+    const removeEvent = this.socket.onEvent<IEvent_FlexHarnessChatPending>(PENDING_EVENT, () => pull());
+    const resyncs = this.socket.eventResyncSubject.subscribe((resyncArg) => {
+      if (resyncArg.names.includes(PENDING_EVENT)) void pull();
+    });
+    return () => {
+      listening = false;
+      resyncs.unsubscribe();
+      removeEvent();
+      removeTools();
+    };
   }
 
   public onReconnect(callbackArg: () => void): () => void {
@@ -84,4 +148,9 @@ export class FlexHarnessChatTypedSocketTransport implements plugins.IFlexHarness
     });
     return () => subscription.unsubscribe();
   }
+
+  private caller(): IFlexHarnessChatCallerPayload {
+    const token = this.callerToken();
+    return { tabId: this.tabId, ...(token === undefined ? {} : { token }) };
+  }
 }

package/ts_chat_harness_typedsocket/classes.serverbinding.ts

@@ -1,10 +1,11 @@
 import * as plugins from './plugins.js';
 import type {
+  IEvent_FlexHarnessChatPending,
   IFlexHarnessChatCallerPayload,
   IReq_FlexHarnessChat,
-  IReq_FlexHarnessChatSessions,
+  IReq_FlexHarnessChatPull,
   IReq_FlexHarnessChatTool,
-  IReq_FlexHarnessChatUpdate,
+  TFlexHarnessChatPush,
 } from './interfaces.requests.js';
 
 /** The hub requests the binding routes; any `FlexHarnessChatHub` serves them. */
@@ -30,7 +31,7 @@ export interface IFlexHarnessChatTypedSocketBindingOptions {
   ): Promise<IFlexHarnessChatResolvedCaller>;
   /** The server-owned connection tag that names a tab. Default: `flexHarnessChatTab`. */
   tag?: string;
-  /** How long an update or a session-list push may wait for the tab. Default: 30 seconds. */
+  /** How long an update or a session-list push may wait for the tab to pull it. Default: 30 seconds. */
   pushTimeoutMs?: number;
 }
 
@@ -44,23 +45,82 @@ const tagPayload = (tabArg: plugins.IFlexHarnessChatCaller): { scopeId: string;
   tabId: tabArg.tabId,
 });
 
+/** One key per tab and scope, as the hub names tabs. */
+const tabKeyOf = (tabArg: plugins.IFlexHarnessChatCaller): string => `${tabArg.scopeId}\n${tabArg.tabId}`;
+
+/** A push waiting for its tab, until the tab pulls it or its time is up. */
+interface IWaitingPush {
+  push: TFlexHarnessChatPush;
+  taken: () => void;
+  timer: ReturnType<typeof setTimeout>;
+}
+
+/**
+ * The pushes waiting for each tab, by tab and scope. A push resolves once the tab pulled it and
+ * fails when the tab does not pull it in time; it never reaches the tab after that.
+ */
+class TypedSocketChatMailboxes {
+  private readonly waiting = new Map<string, IWaitingPush[]>();
+
+  constructor(private readonly pushTimeoutMs: number) {}
+
+  public put(tabArg: plugins.IFlexHarnessChatCaller, pushArg: TFlexHarnessChatPush): Promise<void> {
+    const key = tabKeyOf(tabArg);
+    return new Promise<void>((resolve, reject) => {
+      const entry: IWaitingPush = {
+        push: pushArg,
+        taken: resolve,
+        timer: setTimeout(() => {
+          this.remove(key, entry);
+          reject(new Error('The tab did not pull a push in time.'));
+        }, this.pushTimeoutMs),
+      };
+      entry.timer.unref?.();
+      const mailbox = this.waiting.get(key);
+      if (mailbox) mailbox.push(entry);
+      else this.waiting.set(key, [entry]);
+    });
+  }
+
+  public take(tabArg: plugins.IFlexHarnessChatCaller): TFlexHarnessChatPush[] {
+    const key = tabKeyOf(tabArg);
+    const mailbox = this.waiting.get(key) ?? [];
+    this.waiting.delete(key);
+    for (const entry of mailbox) {
+      clearTimeout(entry.timer);
+      entry.taken();
+    }
+    return mailbox.map((entry) => entry.push);
+  }
+
+  private remove(keyArg: string, entryArg: IWaitingPush): void {
+    const mailbox = this.waiting.get(keyArg);
+    if (!mailbox) return;
+    const rest = mailbox.filter((entry) => entry !== entryArg);
+    if (rest.length) this.waiting.set(keyArg, rest);
+    else this.waiting.delete(keyArg);
+  }
+}
+
+/**
+ * One tab, reached over its current connection: a push waits in the tab's mailbox and an event
+ * tells the tab to pull it. An event the connection skips or drops is not lost: the tab pulls
+ * whenever TypedSocket tells it it may have missed events, after every (re)connect included.
+ */
 class TypedSocketChatPeer implements plugins.IFlexHarnessChatPeer {
   constructor(
     private readonly socket: plugins.typedsocket.TypedSocket,
     private readonly connection: plugins.typedsocket.ISmartServeConnectionWrapper,
-    private readonly pushTimeoutMs: number,
+    private readonly tab: plugins.IFlexHarnessChatCaller,
+    private readonly mailboxes: TypedSocketChatMailboxes,
   ) {}
 
-  public async update(pushArg: plugins.IFlexHarnessChatUpdate): Promise<void> {
-    await this.socket
-      .createTypedRequest<IReq_FlexHarnessChatUpdate>('flexHarnessChatUpdate', this.connection, { timeoutMs: this.pushTimeoutMs })
-      .fire(pushArg);
+  public update(pushArg: plugins.IFlexHarnessChatUpdate): Promise<void> {
+    return this.deliver({ update: pushArg });
   }
 
-  public async sessions(pushArg: plugins.IFlexHarnessChatSessionsPush): Promise<void> {
-    await this.socket
-      .createTypedRequest<IReq_FlexHarnessChatSessions>('flexHarnessChatSessions', this.connection, { timeoutMs: this.pushTimeoutMs })
-      .fire(pushArg);
+  public sessions(pushArg: plugins.IFlexHarnessChatSessionsPush): Promise<void> {
+    return this.deliver({ sessions: pushArg });
   }
 
   public async runTool(
@@ -72,25 +132,33 @@ class TypedSocketChatPeer implements plugins.IFlexHarnessChatPeer {
       .fire(requestArg);
     return answer.output;
   }
+
+  private async deliver(pushArg: TFlexHarnessChatPush): Promise<void> {
+    // the event goes first: a pull cannot come in between, and an event that throws leaves no push behind
+    this.socket.sendEvent<IEvent_FlexHarnessChatPending>(this.connection, 'flexHarnessChatPending', {});
+    await this.mailboxes.put(this.tab, pushArg);
+  }
 }
 
 /**
  * Serves a `FlexHarnessChatHub` over TypedSocket. Add `typedrouter` to the server's router, hand
  * the server's TypedSocket to `setTypedSocket()` once it runs, and give the hub `peers`. A tab's
- * connection carries the server-owned tag with its tab id; every request claims it again.
+ * connection carries the server-owned tag with its tab id; every request claims it again. The
+ * hub's pushes wait for the tab, which an event tells to pull them: TypedSocket events are
+ * signals, the pushes themselves travel in the answer of an authenticated request.
  */
 export class FlexHarnessChatTypedSocketBinding implements plugins.IFlexHarnessChatPeers {
   public readonly typedrouter = new plugins.typedrequest.TypedRouter();
 
   private readonly resolveCaller: IFlexHarnessChatTypedSocketBindingOptions['resolve'];
   private readonly tag: string;
-  private readonly pushTimeoutMs: number;
+  private readonly mailboxes: TypedSocketChatMailboxes;
   private socket: plugins.typedsocket.TypedSocket | null = null;
 
   constructor(optionsArg: IFlexHarnessChatTypedSocketBindingOptions) {
     this.resolveCaller = optionsArg.resolve;
     this.tag = optionsArg.tag ?? 'flexHarnessChatTab';
-    this.pushTimeoutMs = optionsArg.pushTimeoutMs ?? 30 * 1000;
+    this.mailboxes = new TypedSocketChatMailboxes(optionsArg.pushTimeoutMs ?? 30 * 1000);
     this.route<'flexHarnessChatAttach'>('flexHarnessChatAttach', (request, tools) =>
       this.serve(request.caller, tools, (hub, caller) => hub.attach(caller)));
     this.route<'flexHarnessChatOpen'>('flexHarnessChatOpen', (request, tools) =>
@@ -109,6 +177,10 @@ export class FlexHarnessChatTypedSocketBinding implements plugins.IFlexHarnessCh
       this.serve(request.caller, tools, (hub, caller) => hub.renameSession(caller, request)));
     this.route<'flexHarnessChatSessionDelete'>('flexHarnessChatSessionDelete', (request, tools) =>
       this.serve(request.caller, tools, (hub, caller) => hub.deleteSession(caller, request)));
+    this.typedrouter.addTypedHandler(
+      new plugins.typedrequest.TypedHandler<IReq_FlexHarnessChatPull>('flexHarnessChatPull', (request, tools) =>
+        this.serve(request?.caller, tools, async (_hub, caller) => ({ pushes: this.mailboxes.take(caller) }))),
+    );
   }
 
   /** The server's TypedSocket; it exists once the server runs. */
@@ -120,7 +192,7 @@ export class FlexHarnessChatTypedSocketBinding implements plugins.IFlexHarnessCh
   public async find(tabArg: plugins.IFlexHarnessChatCaller): Promise<plugins.IFlexHarnessChatPeer | null> {
     if (!this.socket) return null;
     const connection = await this.socket.findTargetConnectionByTag(this.tag, tagPayload(tabArg));
-    return connection ? new TypedSocketChatPeer(this.socket, connection, this.pushTimeoutMs) : null;
+    return connection ? new TypedSocketChatPeer(this.socket, connection, tagPayload(tabArg), this.mailboxes) : null;
   }
 
   private route<TMethod extends plugins.TFlexHarnessChatMethod>(

package/ts_chat_harness_typedsocket/index.ts

@@ -6,12 +6,14 @@ export {
 } from './classes.serverbinding.js';
 export {
   FlexHarnessChatTypedSocketTransport,
+  type IFlexHarnessChatTypedSocketClient,
   type IFlexHarnessChatTypedSocketTransportOptions,
 } from './classes.clienttransport.js';
 export type {
+  IEvent_FlexHarnessChatPending,
   IFlexHarnessChatCallerPayload,
   IReq_FlexHarnessChat,
-  IReq_FlexHarnessChatSessions,
+  IReq_FlexHarnessChatPull,
   IReq_FlexHarnessChatTool,
-  IReq_FlexHarnessChatUpdate,
+  TFlexHarnessChatPush,
 } from './interfaces.requests.js';

package/ts_chat_harness_typedsocket/interfaces.requests.ts

@@ -4,7 +4,7 @@ import type * as plugins from './plugins.js';
 export interface IFlexHarnessChatCallerPayload {
   /**
    * The tab: 16 random bytes in hex, kept for the tab's lifetime and never shared. Every request
-   * claims the connection it arrives on for the tab, so pushes and tool calls follow a reconnect.
+   * claims the connection it arrives on for the tab, so events and tool calls follow a reconnect.
    */
   tabId: string;
   token?: string;
@@ -18,18 +18,22 @@ export interface IReq_FlexHarnessChat<TMethod extends plugins.TFlexHarnessChatMe
   response: plugins.TFlexHarnessChatResponse<TMethod>;
 }
 
-/** Push: what changed in the conversation a tab follows. */
-export interface IReq_FlexHarnessChatUpdate extends plugins.typedrequestInterfaces.ITypedRequest {
-  method: 'flexHarnessChatUpdate';
-  request: plugins.IFlexHarnessChatUpdate;
-  response: Record<string, never>;
+/** One push the hub has for a tab: an update of the conversation it follows, or a change of its list. */
+export type TFlexHarnessChatPush =
+  | { update: plugins.IFlexHarnessChatUpdate }
+  | { sessions: plugins.IFlexHarnessChatSessionsPush };
+
+/** Event: the tab has pushes waiting; it takes them with `flexHarnessChatPull`. */
+export interface IEvent_FlexHarnessChatPending extends plugins.typedsocket.ITypedSocketEvent {
+  name: 'flexHarnessChatPending';
+  payload: Record<string, never>;
 }
 
-/** Push: changes of the tab's conversation list. */
-export interface IReq_FlexHarnessChatSessions extends plugins.typedrequestInterfaces.ITypedRequest {
-  method: 'flexHarnessChatSessions';
-  request: plugins.IFlexHarnessChatSessionsPush;
-  response: Record<string, never>;
+/** Takes the tab's waiting pushes, in the order the hub made them. */
+export interface IReq_FlexHarnessChatPull extends plugins.typedrequestInterfaces.ITypedRequest {
+  method: 'flexHarnessChatPull';
+  request: { caller: IFlexHarnessChatCallerPayload };
+  response: { pushes: TFlexHarnessChatPush[] };
 }
 
 /** Push: run a tool of a turn in the tab; the answer is the tool's output. */

package/ts_chat_harness_typedsocket/readme.md

@@ -4,7 +4,7 @@
 pnpm add @modelprofile.com/flexharness @api.global/typedsocket @api.global/typedrequest @api.global/typedrequest-interfaces
 ```
 
-The TypedSocket packages are optional peers: `@api.global/typedsocket` `^9.0.2` with `@api.global/typedrequest` `^9.1.0`, the major TypedSocket uses.
+The TypedSocket packages are optional peers: `@api.global/typedsocket` `^9.1.0`, which brings events, with `@api.global/typedrequest` `^9.1.0`, the major TypedSocket uses. The server and the tab both need 9.1.0 or later.
 
 ```typescript
 // server
@@ -27,9 +27,13 @@ const transport = new FlexHarnessChatTypedSocketTransport({ typedsocket, typedro
 const client = new FlexHarnessChatClient({ transport });
 ```
 
-Every request carries `caller: { tabId, token? }`. `resolve` reads it and the request's TypedSocket context and returns the hub and scope it reaches; a `FlexHarnessChatRequestError` it throws reaches the tab as a `TypedResponseError` with its message. The tab id is 16 random bytes in hex, kept for the tab's lifetime and never shared: every request claims the connection it arrives on for the tab with the server-owned tag (`flexHarnessChatTab` by default), so updates, list pushes and tool calls follow a reconnect. The tag's payload is the resolved scope and the tab id: a caller of another scope that sends the same tab id names a tab of its own and never takes over this one's connection, its updates or its tool calls. Pushes wait `pushTimeoutMs` (30 seconds) for the tab.
+Every request carries `caller: { tabId, token? }`. `resolve` reads it and the request's TypedSocket context and returns the hub and scope it reaches; a `FlexHarnessChatRequestError` it throws reaches the tab as a `TypedResponseError` with its message. The tab id is 16 random bytes in hex, kept for the tab's lifetime and never shared: every request claims the connection it arrives on for the tab with the server-owned tag (`flexHarnessChatTab` by default), so updates, list pushes and tool calls follow a reconnect. The tag's payload is the resolved scope and the tab id: a caller of another scope that sends the same tab id names a tab of its own and never takes over this one's connection, its updates or its tool calls.
 
-The transport adds its push handlers (`flexHarnessChatUpdate`, `flexHarnessChatSessions`, `flexHarnessChatTool`) to the tab's router and removes them when the client is disposed. A tool call the server cancels settles at once in the tab. A restored connection makes the client attach again.
+Updates and session-list pushes travel as a TypedSocket event and a pull. The hub's push waits in the tab's mailbox on the server, and the binding sends the tab the event `flexHarnessChatPending` (no payload). The tab answers with the request `flexHarnessChatPull`, which runs through `resolve` like every other request and returns the waiting pushes in order. A push settles when the tab pulls it; one the tab does not pull within `pushTimeoutMs` (30 seconds) fails, leaves the mailbox and never reaches the tab; a failed update makes the hub send that subscription a reset with its next change. Tool calls stay requests from the server to the tab (`flexHarnessChatTool`).
+
+The transport pulls on the event and whenever TypedSocket reports that events may have been missed: after it registers the event on a (re)connected socket, and after a sequence gap. Pulls run one at a time; a signal that arrives during a pull makes it pull once more. A pull that fails leaves the pushes waiting for the next one. A handler that throws on a push is reported with `console.warn('FLEXHARNESS_CHAT_PUSH_HANDLER_ERROR', error)`, and the pushes after it still reach the tab; the server counts the push as delivered. `listen` adds the tool handler to the tab's router and the event handler to its client, and the client's dispose removes both. A tool call the server cancels settles at once in the tab. A restored connection makes the client attach again.
+
+The transport's `typedsocket` option takes any object with the members it uses (`IFlexHarnessChatTypedSocketClient`: `createTypedRequest`, `onEvent`, `eventResyncSubject`, `statusSubject`). A `TypedSocket` client is one; a host whose own connection object carries the client can pass that object instead.
 
 ## Issue Reporting and Security