@modelprofile.com/flexharness 10.24.0 → 11.0.0

package/ts_chat_harness_server/classes.chathub.ts

@@ -1,4 +1,5 @@
 import * as plugins from './plugins.js';
+import { FlexHarnessChatScopeDirectory, flexHarnessChatSessionMeta } from './classes.scopedirectory.js';
 import { FlexHarnessChatSessionLists } from './classes.sessionlists.js';
 import { FlexHarnessChatSubscription } from './classes.chatsubscription.js';
 import { FlexHarnessChatTurnGate } from './classes.turngate.js';
@@ -16,6 +17,8 @@ import {
 } from './functions.validation.js';
 import type {
   IFlexHarnessChatCaller,
+  IFlexHarnessChatConversation,
+  IFlexHarnessChatDirectory,
   IFlexHarnessChatHubOptions,
   IFlexHarnessChatLimits,
   IFlexHarnessChatPeers,
@@ -42,12 +45,6 @@ export const defaultFlexHarnessChatLimits: Readonly<IFlexHarnessChatLimits> = Ob
   sweepIntervalMs: 5 * 60 * 1000,
 });
 
-/** A conversation as a session list shows it; an imported one says so. */
-export const flexHarnessChatSessionMeta = (sessionArg: plugins.IFlexSession): plugins.IHarnessSessionMeta => ({
-  ...plugins.flexSessionToHarnessMeta(sessionArg),
-  ...(sessionArg.origin?.kind === 'import' ? { statusLabel: 'Imported' } : {}),
-});
-
 /**
  * Serves `dees-harness-chat` conversations of one FlexHarness to browser tabs, over any transport:
  * a tab attaches, follows one conversation through numbered updates, sends messages that start or
@@ -56,8 +53,10 @@ export const flexHarnessChatSessionMeta = (sessionArg: plugins.IFlexSession): pl
  * tab that started the turn.
  *
  * The host authenticates every request and names its caller: the tab and the scope it may reach. A
- * session of another scope reads as not found. `stop()` stops the turns the hub started, its
- * subscriptions and its timers; the harness stays the host's.
+ * session of another scope reads as not found. A host whose conversations run in scopes of their
+ * own gives the hub a directory: it says which conversations a tab reaches, and where they run.
+ * `stop()` stops the turns the hub started, its subscriptions and its timers; the harness stays the
+ * host's.
  */
 export class FlexHarnessChatHub<TContext> {
   private readonly limits: Readonly<IFlexHarnessChatLimits>;
@@ -65,6 +64,9 @@ export class FlexHarnessChatHub<TContext> {
   private readonly peers: IFlexHarnessChatPeers;
   private readonly readContext: (valueArg: plugins.TJsonValue) => TContext;
   private readonly titleOf: (sendArg: plugins.IHarnessComposerSendDetail) => string;
+  private readonly directory: IFlexHarnessChatDirectory;
+  /** without a directory of the host's, the harness's session events change the lists */
+  private readonly listsFromHarness: boolean;
   private readonly gate: FlexHarnessChatTurnGate<TContext>;
   private readonly sessionLists: FlexHarnessChatSessionLists;
   private readonly subscriptions = new Map<string, FlexHarnessChatSubscription>();
@@ -82,8 +84,10 @@ export class FlexHarnessChatHub<TContext> {
     this.peers = optionsArg.peers;
     this.readContext = optionsArg.readContext;
     this.titleOf = optionsArg.titleOf ?? titleFromMessage;
+    this.directory = optionsArg.directory ?? new FlexHarnessChatScopeDirectory(this.harness);
+    this.listsFromHarness = !optionsArg.directory;
     this.gate = new FlexHarnessChatTurnGate<TContext>(this.harness, this.limits);
-    this.sessionLists = new FlexHarnessChatSessionLists(this.peers, flexHarnessChatSessionMeta);
+    this.sessionLists = new FlexHarnessChatSessionLists(this.peers);
     this.unsubscribe = this.harness.subscribe((eventArg) => this.takeEvent(eventArg));
     this.sweepTimer = setInterval(() => void this.forgetClosedTabs(), this.limits.sweepIntervalMs);
     this.sweepTimer.unref?.();
@@ -96,13 +100,7 @@ export class FlexHarnessChatHub<TContext> {
     this.assertRunning();
     this.closeSubscriptionsOf(callerArg);
     this.sessionLists.attach(callerArg);
-    const sessions = await this.call(() => this.harness.listSessions(callerArg.scopeId));
-    return {
-      sessions: sessions
-        .filter((session) => !session.parentSessionId)
-        .sort((left, right) => right.updatedAt.localeCompare(left.updatedAt))
-        .map(flexHarnessChatSessionMeta),
-    };
+    return { sessions: await this.call(() => this.directory.list(callerArg)) };
   }
 
   public open(
@@ -118,15 +116,15 @@ export class FlexHarnessChatHub<TContext> {
   ): Promise<TResponse<'flexHarnessChatOpen'>> {
     this.assertRunning();
     const subscriptionId = readRandomId(requestArg?.subscriptionId);
-    const session = await this.requireSession(callerArg, requestArg.sessionId);
+    const conversation = await this.requireConversation(callerArg, requestArg.sessionId);
     this.assertRunning();
     if (this.subscriptions.has(subscriptionId)) throw new FlexHarnessChatRequestError(BAD_REQUEST_MESSAGE);
     this.closeSubscriptionsOf(callerArg);
     const subscription = new FlexHarnessChatSubscription({
       id: subscriptionId,
-      tabId: callerArg.tabId,
-      scopeId: callerArg.scopeId,
-      sessionId: session.sessionId,
+      tab: { tabId: callerArg.tabId, scopeId: callerArg.scopeId },
+      scopeId: conversation.scopeId,
+      sessionId: conversation.sessionId,
       harness: this.harness,
       peers: this.peers,
       limits: this.limits,
@@ -141,7 +139,7 @@ export class FlexHarnessChatHub<TContext> {
       this.closeSubscription(subscription);
       throw this.toRequestError(error);
     }
-    return { session: flexHarnessChatSessionMeta(session), readOnly: session.origin?.kind === 'import' };
+    return { session: conversation.meta, readOnly: conversation.readOnly };
   }
 
   public async close(
@@ -149,7 +147,7 @@ export class FlexHarnessChatHub<TContext> {
     requestArg: TRequest<'flexHarnessChatClose'>,
   ): Promise<TResponse<'flexHarnessChatClose'>> {
     const subscription = this.subscriptions.get(requestArg?.subscriptionId);
-    if (subscription && isSameTab(subscription, callerArg)) this.closeSubscription(subscription);
+    if (subscription && isSameTab(subscription.tab, callerArg)) this.closeSubscription(subscription);
     return {};
   }
 
@@ -170,24 +168,23 @@ export class FlexHarnessChatHub<TContext> {
     this.assertRunning();
     const send = readSendDetail(requestArg?.send, this.limits);
     const context = this.readSendContext(requestArg.context);
-    let sessionId: string;
+    let conversation: IFlexHarnessChatConversation;
     let created = false;
     if (requestArg.sessionId === undefined) {
-      sessionId = (await this.call(() => this.harness.createSession(callerArg.scopeId, { title: this.titleOf(send) }))).sessionId;
+      conversation = await this.call(() => this.directory.create(callerArg, { title: this.titleOf(send) }));
       created = true;
     } else {
-      const session = await this.requireSession(callerArg, requestArg.sessionId);
-      if (session.origin?.kind === 'import') throw new FlexHarnessChatRequestError(READ_ONLY_MESSAGE);
-      sessionId = session.sessionId;
+      conversation = await this.requireConversation(callerArg, requestArg.sessionId);
+      if (conversation.readOnly) throw new FlexHarnessChatRequestError(READ_ONLY_MESSAGE);
     }
     try {
       // the hub may have stopped while the conversation was read or created
       this.assertRunning();
-      return await this.gate.admit(callerArg, sessionId, send, context, deadlineArg);
+      return await this.gate.admit(callerArg, conversation, send, context, deadlineArg);
     } catch (error) {
       // a conversation created for this message that never got it is not kept
       if (created && !(error instanceof plugins.FlexHarnessClosedError)) {
-        await this.harness.deleteSession(callerArg.scopeId, sessionId).catch(() => undefined);
+        await this.directory.delete(callerArg, conversation).catch(() => undefined);
       }
       throw this.toRequestError(error);
     }
@@ -197,8 +194,8 @@ export class FlexHarnessChatHub<TContext> {
     callerArg: IFlexHarnessChatCaller,
     requestArg: TRequest<'flexHarnessChatAbort'>,
   ): Promise<TResponse<'flexHarnessChatAbort'>> {
-    const session = await this.requireSession(callerArg, requestArg?.sessionId);
-    await this.call(() => this.harness.abort(callerArg.scopeId, session.sessionId));
+    const conversation = await this.requireConversation(callerArg, requestArg?.sessionId);
+    await this.call(() => this.harness.abort(conversation.scopeId, conversation.sessionId));
     return {};
   }
 
@@ -206,13 +203,13 @@ export class FlexHarnessChatHub<TContext> {
     callerArg: IFlexHarnessChatCaller,
     requestArg: TRequest<'flexHarnessChatPermission'>,
   ): Promise<TResponse<'flexHarnessChatPermission'>> {
-    const session = await this.requireSession(callerArg, requestArg?.sessionId);
+    const conversation = await this.requireConversation(callerArg, requestArg?.sessionId);
     if (typeof requestArg.permissionId !== 'string' || !DECISIONS.includes(requestArg.decision)) {
       throw new FlexHarnessChatRequestError(BAD_REQUEST_MESSAGE);
     }
     await this.call(() => this.harness.respondToPermission(
-      callerArg.scopeId,
-      session.sessionId,
+      conversation.scopeId,
+      conversation.sessionId,
       requestArg.permissionId,
       requestArg.decision,
     ));
@@ -223,13 +220,13 @@ export class FlexHarnessChatHub<TContext> {
     callerArg: IFlexHarnessChatCaller,
     requestArg: TRequest<'flexHarnessChatHistory'>,
   ): Promise<TResponse<'flexHarnessChatHistory'>> {
-    const session = await this.requireSession(callerArg, requestArg?.sessionId);
+    const conversation = await this.requireConversation(callerArg, requestArg?.sessionId);
     if (requestArg.direction === 'undo') {
-      const result = await this.call(() => this.harness.undoSession(callerArg.scopeId, session.sessionId));
+      const result = await this.call(() => this.harness.undoSession(conversation.scopeId, conversation.sessionId));
       return { runId: result.revertedRunId };
     }
     if (requestArg.direction === 'redo') {
-      const result = await this.call(() => this.harness.redoSession(callerArg.scopeId, session.sessionId));
+      const result = await this.call(() => this.harness.redoSession(conversation.scopeId, conversation.sessionId));
       return { runId: result.restoredRunId };
     }
     throw new FlexHarnessChatRequestError(BAD_REQUEST_MESSAGE);
@@ -240,23 +237,25 @@ export class FlexHarnessChatHub<TContext> {
     requestArg: TRequest<'flexHarnessChatSessionUpdate'>,
   ): Promise<TResponse<'flexHarnessChatSessionUpdate'>> {
     const title = readTitle(requestArg?.title, this.limits);
-    const session = await this.requireSession(callerArg, requestArg.sessionId);
-    const updated = await this.call(() => this.harness.updateSession(callerArg.scopeId, session.sessionId, { title }));
-    return { session: flexHarnessChatSessionMeta(updated) };
+    const conversation = await this.requireConversation(callerArg, requestArg.sessionId);
+    return { session: await this.call(() => this.directory.rename(callerArg, conversation, title)) };
   }
 
   public async deleteSession(
     callerArg: IFlexHarnessChatCaller,
     requestArg: TRequest<'flexHarnessChatSessionDelete'>,
   ): Promise<TResponse<'flexHarnessChatSessionDelete'>> {
-    const session = await this.requireSession(callerArg, requestArg?.sessionId);
-    await this.call(() => this.harness.deleteSession(callerArg.scopeId, session.sessionId));
+    const conversation = await this.requireConversation(callerArg, requestArg?.sessionId);
+    await this.call(() => this.directory.delete(callerArg, conversation));
     return {};
   }
 
   // ---------------- turns ----------------
 
-  /** The running turn of a conversation; the host's model resolver and tool provider read it. */
+  /**
+   * The running turn of a conversation, by the harness scope it runs in; the host's model resolver
+   * and tool provider read it.
+   */
   public turnOf(scopeIdArg: string, sessionIdArg: string): IFlexHarnessChatTurn<TContext> | undefined {
     return this.gate.turnOf(scopeIdArg, sessionIdArg);
   }
@@ -270,7 +269,7 @@ export class FlexHarnessChatHub<TContext> {
     requestArg: plugins.IFlexHarnessChatToolRequest,
     optionsArg: { timeoutMs?: number; abortSignal?: AbortSignal } = {},
   ): Promise<plugins.TJsonValue> {
-    const peer = await this.peers.find({ tabId: turnArg.tabId, scopeId: turnArg.scopeId });
+    const peer = await this.peers.find(turnArg.tab);
     if (!peer) throw new FlexHarnessChatTabUnavailableError();
     try {
       return await peer.runTool(requestArg, {
@@ -285,6 +284,15 @@ export class FlexHarnessChatHub<TContext> {
 
   // ---------------- tabs and lifecycle ----------------
 
+  /**
+   * Tells the tabs of a scope that conversations of their list changed. A host with a directory of
+   * its own calls it for every change; without one, the harness's session events do.
+   */
+  public publishSessions(scopeIdArg: string, changesArg: Partial<plugins.IFlexHarnessChatSessionsPush>): void {
+    if (this.stopped) return;
+    this.sessionLists.publish(scopeIdArg, changesArg);
+  }
+
   /** Forgets a tab that is gone: its conversation list and the conversation it followed. */
   public forgetTab(tabArg: IFlexHarnessChatCaller): void {
     this.closeSubscriptionsOf(tabArg);
@@ -317,16 +325,20 @@ export class FlexHarnessChatHub<TContext> {
     this.lastSequence = eventArg.sequence;
     this.gate.takeEvent(eventArg);
     for (const subscription of this.subscriptions.values()) subscription.takeEvent(eventArg, preceding);
+    if (!this.listsFromHarness) return;
     if (eventArg.type === 'session.created' || eventArg.type === 'session.updated' || eventArg.type === 'session.deleted') {
-      if (!eventArg.session.parentSessionId) this.sessionLists.publish(eventArg);
+      if (eventArg.session.parentSessionId) return;
+      this.sessionLists.publish(eventArg.scopeId, eventArg.type === 'session.deleted'
+        ? { deletedIds: [eventArg.sessionId] }
+        : { upserts: [flexHarnessChatSessionMeta(eventArg.session)] });
     }
   }
 
   /** Forgets the tabs that are gone and run no turn; runs every `sweepIntervalMs` on its own. */
   private async forgetClosedTabs(): Promise<void> {
     const tabs = new Map<string, IFlexHarnessChatCaller>();
-    for (const tab of [...this.sessionLists.tabs, ...this.subscriptions.values()]) {
-      tabs.set(tabKey(tab), { tabId: tab.tabId, scopeId: tab.scopeId });
+    for (const tab of [...this.sessionLists.tabs, ...[...this.subscriptions.values()].map((subscription) => subscription.tab)]) {
+      tabs.set(tabKey(tab), tab);
     }
     for (const tab of tabs.values()) {
       if (this.stopped) return;
@@ -338,7 +350,7 @@ export class FlexHarnessChatHub<TContext> {
 
   private closeSubscriptionsOf(tabArg: IFlexHarnessChatCaller): void {
     for (const subscription of [...this.subscriptions.values()]) {
-      if (isSameTab(subscription, tabArg)) this.closeSubscription(subscription);
+      if (isSameTab(subscription.tab, tabArg)) this.closeSubscription(subscription);
     }
   }
 
@@ -366,20 +378,15 @@ export class FlexHarnessChatHub<TContext> {
     }
   }
 
-  /** A root session of the caller's scope; another scope's session id reads as not found. */
-  private async requireSession(callerArg: IFlexHarnessChatCaller, sessionIdArg: unknown): Promise<plugins.IFlexSession> {
+  /** A conversation the caller reaches; one it does not reach reads as not found. */
+  private async requireConversation(
+    callerArg: IFlexHarnessChatCaller,
+    sessionIdArg: unknown,
+  ): Promise<IFlexHarnessChatConversation> {
     const sessionId = readSessionId(sessionIdArg, NOT_FOUND_MESSAGE);
-    let session: plugins.IFlexSession;
-    try {
-      session = await this.harness.getSession(callerArg.scopeId, sessionId);
-    } catch (error) {
-      if (error instanceof plugins.FlexHarnessNotFoundError || error instanceof plugins.FlexHarnessValidationError) {
-        throw new FlexHarnessChatRequestError(NOT_FOUND_MESSAGE);
-      }
-      throw this.toRequestError(error);
-    }
-    if (session.parentSessionId) throw new FlexHarnessChatRequestError(NOT_FOUND_MESSAGE);
-    return session;
+    const conversation = await this.call(() => this.directory.find(callerArg, sessionId));
+    if (!conversation) throw new FlexHarnessChatRequestError(NOT_FOUND_MESSAGE);
+    return conversation;
   }
 
   private async call<T>(fnArg: () => Promise<T>): Promise<T> {

package/ts_chat_harness_server/classes.chatsubscription.ts

@@ -1,5 +1,5 @@
 import * as plugins from './plugins.js';
-import type { IFlexHarnessChatLimits, IFlexHarnessChatPeers } from './interfaces.js';
+import type { IFlexHarnessChatCaller, IFlexHarnessChatLimits, IFlexHarnessChatPeers } from './interfaces.js';
 
 type TUpdate = plugins.IFlexHarnessChatUpdate;
 
@@ -44,7 +44,9 @@ export type TFlexHarnessChatSubscriptionHarness = Pick<
 
 export interface IFlexHarnessChatSubscriptionOptions {
   id: string;
-  tabId: string;
+  /** the tab that follows the conversation */
+  tab: IFlexHarnessChatCaller;
+  /** the harness scope of the conversation */
   scopeId: string;
   sessionId: string;
   harness: TFlexHarnessChatSubscriptionHarness;
@@ -61,7 +63,7 @@ export interface IFlexHarnessChatSubscriptionOptions {
  */
 export class FlexHarnessChatSubscription {
   public readonly id: string;
-  public readonly tabId: string;
+  public readonly tab: IFlexHarnessChatCaller;
   public readonly scopeId: string;
   public readonly sessionId: string;
 
@@ -82,7 +84,7 @@ export class FlexHarnessChatSubscription {
 
   constructor(optionsArg: IFlexHarnessChatSubscriptionOptions) {
     this.id = optionsArg.id;
-    this.tabId = optionsArg.tabId;
+    this.tab = optionsArg.tab;
     this.scopeId = optionsArg.scopeId;
     this.sessionId = optionsArg.sessionId;
     this.harness = optionsArg.harness;
@@ -181,7 +183,7 @@ export class FlexHarnessChatSubscription {
     let inFlight: TUpdate | null = null;
     try {
       while (!this.closed && this.state === 'live' && hasPending(this.pending)) {
-        const peer = await this.peers.find({ tabId: this.tabId, scopeId: this.scopeId });
+        const peer = await this.peers.find(this.tab);
         if (!peer) {
           this.closeSelf();
           return;

package/ts_chat_harness_server/classes.scopedirectory.ts

@@ -0,0 +1,67 @@
+import * as plugins from './plugins.js';
+import type {
+  IFlexHarnessChatCaller,
+  IFlexHarnessChatConversation,
+  IFlexHarnessChatDirectory,
+  TFlexHarnessChatHubHarness,
+} from './interfaces.js';
+
+/** A conversation as a session list shows it; an imported one says so. */
+export const flexHarnessChatSessionMeta = (sessionArg: plugins.IFlexSession): plugins.IHarnessSessionMeta => ({
+  ...plugins.flexSessionToHarnessMeta(sessionArg),
+  ...(sessionArg.origin?.kind === 'import' ? { statusLabel: 'Imported' } : {}),
+});
+
+const conversationOf = (sessionArg: plugins.IFlexSession): IFlexHarnessChatConversation => ({
+  scopeId: sessionArg.scopeId,
+  sessionId: sessionArg.sessionId,
+  meta: flexHarnessChatSessionMeta(sessionArg),
+  readOnly: sessionArg.origin?.kind === 'import',
+});
+
+/** The directory a hub has without one of the host's: a tab's conversations are the root sessions of its scope. */
+export class FlexHarnessChatScopeDirectory implements IFlexHarnessChatDirectory {
+  private readonly harness: TFlexHarnessChatHubHarness;
+
+  constructor(harnessArg: TFlexHarnessChatHubHarness) {
+    this.harness = harnessArg;
+  }
+
+  public async list(tabArg: IFlexHarnessChatCaller): Promise<plugins.IHarnessSessionMeta[]> {
+    const sessions = await this.harness.listSessions(tabArg.scopeId);
+    return sessions
+      .filter((session) => !session.parentSessionId)
+      .sort((left, right) => right.updatedAt.localeCompare(left.updatedAt))
+      .map(flexHarnessChatSessionMeta);
+  }
+
+  /** A root session of the tab's scope; another scope's session id reads as not found. */
+  public async find(tabArg: IFlexHarnessChatCaller, sessionIdArg: string): Promise<IFlexHarnessChatConversation | null> {
+    let session: plugins.IFlexSession;
+    try {
+      session = await this.harness.getSession(tabArg.scopeId, sessionIdArg);
+    } catch (error) {
+      if (error instanceof plugins.FlexHarnessNotFoundError || error instanceof plugins.FlexHarnessValidationError) return null;
+      throw error;
+    }
+    return session.parentSessionId ? null : conversationOf(session);
+  }
+
+  public async create(tabArg: IFlexHarnessChatCaller, initArg: { title: string }): Promise<IFlexHarnessChatConversation> {
+    return conversationOf(await this.harness.createSession(tabArg.scopeId, { title: initArg.title }));
+  }
+
+  public async rename(
+    _tabArg: IFlexHarnessChatCaller,
+    conversationArg: IFlexHarnessChatConversation,
+    titleArg: string,
+  ): Promise<plugins.IHarnessSessionMeta> {
+    return flexHarnessChatSessionMeta(
+      await this.harness.updateSession(conversationArg.scopeId, conversationArg.sessionId, { title: titleArg }),
+    );
+  }
+
+  public async delete(_tabArg: IFlexHarnessChatCaller, conversationArg: IFlexHarnessChatConversation): Promise<void> {
+    await this.harness.deleteSession(conversationArg.scopeId, conversationArg.sessionId);
+  }
+}

package/ts_chat_harness_server/classes.sessionlists.ts

@@ -2,11 +2,6 @@ import type * as plugins from './plugins.js';
 import { tabKey } from './functions.validation.js';
 import type { IFlexHarnessChatCaller, IFlexHarnessChatPeers } from './interfaces.js';
 
-type TSessionEvent =
-  | plugins.IFlexSessionCreatedEvent
-  | plugins.IFlexSessionUpdatedEvent
-  | plugins.IFlexSessionDeletedEvent;
-
 /** A tab and the changes of its conversation list it has not received yet. */
 interface IAttachedTab {
   tab: IFlexHarnessChatCaller;
@@ -22,15 +17,10 @@ interface IAttachedTab {
  */
 export class FlexHarnessChatSessionLists {
   private readonly peers: IFlexHarnessChatPeers;
-  private readonly toSessionMeta: (sessionArg: plugins.IFlexSession) => plugins.IHarnessSessionMeta;
   private readonly attached = new Map<string, IAttachedTab>();
 
-  constructor(
-    peersArg: IFlexHarnessChatPeers,
-    toSessionMetaArg: (sessionArg: plugins.IFlexSession) => plugins.IHarnessSessionMeta,
-  ) {
+  constructor(peersArg: IFlexHarnessChatPeers) {
     this.peers = peersArg;
-    this.toSessionMeta = toSessionMetaArg;
   }
 
   public get tabs(): IFlexHarnessChatCaller[] {
@@ -54,15 +44,17 @@ export class FlexHarnessChatSessionLists {
     this.attached.clear();
   }
 
-  public publish(eventArg: TSessionEvent): void {
+  /** Changes of the lists of the tabs of a scope; a deletion and an upsert of one id: the upsert wins. */
+  public publish(scopeIdArg: string, changesArg: Partial<plugins.IFlexHarnessChatSessionsPush>): void {
     for (const [key, entry] of this.attached) {
-      if (entry.tab.scopeId !== eventArg.scopeId) continue;
-      if (eventArg.type === 'session.deleted') {
-        entry.upserts.delete(eventArg.sessionId);
-        entry.deletedIds.add(eventArg.sessionId);
-      } else {
-        entry.deletedIds.delete(eventArg.sessionId);
-        entry.upserts.set(eventArg.sessionId, this.toSessionMeta(eventArg.session));
+      if (entry.tab.scopeId !== scopeIdArg) continue;
+      for (const sessionId of changesArg.deletedIds ?? []) {
+        entry.upserts.delete(sessionId);
+        entry.deletedIds.add(sessionId);
+      }
+      for (const session of changesArg.upserts ?? []) {
+        entry.deletedIds.delete(session.id);
+        entry.upserts.set(session.id, session);
       }
       void this.pump(key, entry);
     }

package/ts_chat_harness_server/classes.turngate.ts

@@ -1,6 +1,6 @@
 import * as plugins from './plugins.js';
 import { FlexHarnessChatRequestError } from './errors.js';
-import { STOPPED_MESSAGE } from './functions.validation.js';
+import { STOPPED_MESSAGE, isSameTab } from './functions.validation.js';
 import type { IFlexHarnessChatCaller, IFlexHarnessChatLimits, IFlexHarnessChatTurn } from './interfaces.js';
 
 const STILL_FINISHING_MESSAGE =
@@ -12,6 +12,12 @@ export type TFlexHarnessChatGateHarness = Pick<
   'enqueuePrompt' | 'steerPrompt' | 'getPromptQueueEntry' | 'cancelPrompt'
 >;
 
+/** A conversation as the gate reaches it: the harness scope it runs in, and its session. */
+interface ITarget {
+  scopeId: string;
+  sessionId: string;
+}
+
 /** A turn as the gate tracks it, from its admission until its run ended. */
 interface ITurnBinding<TContext> extends IFlexHarnessChatTurn<TContext> {
   /** set once the harness queued the prompt */
@@ -62,14 +68,14 @@ export class FlexHarnessChatTurnGate<TContext> {
   public turnOf(scopeIdArg: string, sessionIdArg: string): IFlexHarnessChatTurn<TContext> | undefined {
     const binding = this.bindings.get(bindingKey(scopeIdArg, sessionIdArg));
     return binding
-      ? { scopeId: binding.scopeId, sessionId: binding.sessionId, tabId: binding.tabId, context: binding.context }
+      ? { scopeId: binding.scopeId, sessionId: binding.sessionId, tab: binding.tab, context: binding.context }
       : undefined;
   }
 
   /** Whether a turn the tab started still runs. */
   public hasTurnOf(tabArg: IFlexHarnessChatCaller): boolean {
     for (const binding of this.bindings.values()) {
-      if (binding.tabId === tabArg.tabId && binding.scopeId === tabArg.scopeId) return true;
+      if (isSameTab(binding.tab, tabArg)) return true;
     }
     return false;
   }
@@ -81,17 +87,18 @@ export class FlexHarnessChatTurnGate<TContext> {
     if (binding && binding.queueId === eventArg.queueId) binding.markRunning();
   }
 
-  /** Admits a message under the conversation's lock; every wait ends at the deadline. */
+  /** Admits a message of the caller's tab under the conversation's lock; every wait ends at the deadline. */
   public admit(
     callerArg: IFlexHarnessChatCaller,
-    sessionIdArg: string,
+    targetArg: ITarget,
     sendArg: plugins.IHarnessComposerSendDetail,
     contextArg: TContext,
     deadlineArg: number,
   ): Promise<plugins.TFlexHarnessChatResponse<'flexHarnessChatSend'>> {
     if (this.stopped) return Promise.reject(new FlexHarnessChatRequestError(STOPPED_MESSAGE));
-    const admission = this.withLock(bindingKey(callerArg.scopeId, sessionIdArg), () =>
-      this.admitLocked(callerArg, sessionIdArg, sendArg, contextArg, deadlineArg),
+    const target = { scopeId: targetArg.scopeId, sessionId: targetArg.sessionId };
+    const admission = this.withLock(bindingKey(target.scopeId, target.sessionId), () =>
+      this.admitLocked(callerArg, target, sendArg, contextArg, deadlineArg),
     );
     const settled = admission.then(() => undefined, () => undefined);
     this.admissions.add(settled);
@@ -144,7 +151,7 @@ export class FlexHarnessChatTurnGate<TContext> {
 
   private async admitLocked(
     callerArg: IFlexHarnessChatCaller,
-    sessionIdArg: string,
+    target: ITarget,
     sendArg: plugins.IHarnessComposerSendDetail,
     contextArg: TContext,
     deadlineArg: number,
@@ -153,7 +160,6 @@ export class FlexHarnessChatTurnGate<TContext> {
       if (!(await settlesBefore(promiseArg, deadlineArg))) throw new FlexHarnessChatRequestError(STILL_FINISHING_MESSAGE);
     };
     this.assertOpen();
-    const target = { scopeId: callerArg.scopeId, sessionId: sessionIdArg };
     const binding = this.bindings.get(bindingKey(target.scopeId, target.sessionId));
     if (binding?.queueId) {
       for (let attempt = 0; attempt < 2; attempt++) {
@@ -165,7 +171,7 @@ export class FlexHarnessChatTurnGate<TContext> {
             steerId: intent.steerId,
             prompt: intent.prompt,
           });
-          return { sessionId: sessionIdArg, steerId: intent.steerId };
+          return { sessionId: target.sessionId, steerId: intent.steerId };
         } catch (error) {
           if (!(error instanceof plugins.FlexHarnessSteerRejectedError) || error.reason !== 'not-running') throw error;
         }
@@ -181,24 +187,25 @@ export class FlexHarnessChatTurnGate<TContext> {
       await waitFor(binding.settled);
     }
     this.assertOpen();
-    return this.startTurn(callerArg, sessionIdArg, sendArg, contextArg);
+    return this.startTurn(callerArg, target, sendArg, contextArg);
   }
 
   private async startTurn(
     callerArg: IFlexHarnessChatCaller,
-    sessionIdArg: string,
+    target: ITarget,
     sendArg: plugins.IHarnessComposerSendDetail,
     contextArg: TContext,
   ): Promise<plugins.TFlexHarnessChatResponse<'flexHarnessChatSend'>> {
-    const key = bindingKey(callerArg.scopeId, sessionIdArg);
-    const intent = intentOf({ scopeId: callerArg.scopeId, sessionId: sessionIdArg }, { ...sendArg, delivery: 'turn' });
+    const { scopeId, sessionId } = target;
+    const key = bindingKey(scopeId, sessionId);
+    const intent = intentOf(target, { ...sendArg, delivery: 'turn' });
     if (intent.type !== 'enqueuePrompt') throw new Error('A new turn must be queued.');
     let markSettled!: () => void;
     let markRunning!: () => void;
     const binding: ITurnBinding<TContext> = {
-      scopeId: callerArg.scopeId,
-      sessionId: sessionIdArg,
-      tabId: callerArg.tabId,
+      scopeId,
+      sessionId,
+      tab: { tabId: callerArg.tabId, scopeId: callerArg.scopeId },
       context: contextArg,
       running: new Promise<void>((resolve) => (markRunning = resolve)),
       markRunning: () => markRunning(),
@@ -214,7 +221,7 @@ export class FlexHarnessChatTurnGate<TContext> {
     this.bindings.set(key, binding);
     let queued: plugins.IFlexPromptQueueAdmission;
     try {
-      queued = await this.harness.enqueuePrompt(callerArg.scopeId, sessionIdArg, intent.prompt);
+      queued = await this.harness.enqueuePrompt(scopeId, sessionId, intent.prompt);
     } catch (error) {
       end();
       throw error;
@@ -224,12 +231,12 @@ export class FlexHarnessChatTurnGate<TContext> {
     void queued.completion.then(() => undefined, () => undefined).finally(end);
     if (this.stopped) {
       // the gate stopped while the prompt was being queued: the turn never runs on
-      this.cancel(callerArg.scopeId, sessionIdArg, queued.queueId);
+      this.cancel(scopeId, sessionId, queued.queueId);
       throw new FlexHarnessChatRequestError(STOPPED_MESSAGE);
     }
-    binding.timer = setTimeout(() => this.cancel(callerArg.scopeId, sessionIdArg, queued.queueId), this.limits.turnTimeoutMs);
+    binding.timer = setTimeout(() => this.cancel(scopeId, sessionId, queued.queueId), this.limits.turnTimeoutMs);
     binding.timer.unref?.();
-    return { sessionId: sessionIdArg, queueId: queued.queueId };
+    return { sessionId, queueId: queued.queueId };
   }
 }
 

package/ts_chat_harness_server/index.ts

@@ -1,8 +1,5 @@
-export {
-  FlexHarnessChatHub,
-  defaultFlexHarnessChatLimits,
-  flexHarnessChatSessionMeta,
-} from './classes.chathub.js';
+export { FlexHarnessChatHub, defaultFlexHarnessChatLimits } from './classes.chathub.js';
+export { flexHarnessChatSessionMeta } from './classes.scopedirectory.js';
 export { FlexHarnessChatRequestError, FlexHarnessChatTabUnavailableError } from './errors.js';
 export {
   createFlexHarnessChatErrorProjector,
@@ -10,6 +7,8 @@ export {
 } from './functions.errorprojector.js';
 export type {
   IFlexHarnessChatCaller,
+  IFlexHarnessChatConversation,
+  IFlexHarnessChatDirectory,
   IFlexHarnessChatHubOptions,
   IFlexHarnessChatLimits,
   IFlexHarnessChatPeer,