@modelprofile.com/flexharness 10.17.0 → 10.18.0

package/ts_chat_harness/classes.chatclient.ts

@@ -0,0 +1,343 @@
+import type * as plugins from './plugins.js';
+import type { TJsonValue } from '@modelprofile.com/flexharness';
+import type {
+  IFlexHarnessChatHistoryState,
+  IFlexHarnessChatSessionsPush,
+  IFlexHarnessChatSteerOutcome,
+  IFlexHarnessChatToolRequest,
+  IFlexHarnessChatUpdate,
+  TFlexHarnessChatMethod,
+  TFlexHarnessChatRequest,
+  TFlexHarnessChatResponse,
+} from './interfaces.chat.js';
+
+/** Where a `FlexHarnessChatClient` hands the hub's pushes. */
+export interface IFlexHarnessChatPushHandlers {
+  update(push: IFlexHarnessChatUpdate): void;
+  sessions(push: IFlexHarnessChatSessionsPush): void;
+  /** Runs a tool of a turn; settles at once when the signal aborts. */
+  tool(request: IFlexHarnessChatToolRequest, abortSignal: AbortSignal | undefined): Promise<TJsonValue>;
+}
+
+/** The tab's connection to the hub. It names the tab in every request it carries. */
+export interface IFlexHarnessChatClientTransport {
+  request<TMethod extends TFlexHarnessChatMethod>(
+    method: TMethod,
+    request: TFlexHarnessChatRequest<TMethod>,
+  ): Promise<TFlexHarnessChatResponse<TMethod>>;
+  /** Routes the hub's pushes to the handlers until the returned function is called. */
+  listen(handlers: IFlexHarnessChatPushHandlers): () => void;
+  /** Calls back whenever the connection was lost and is restored, until the returned function is called. */
+  onReconnect(callback: () => void): () => void;
+}
+
+/** What the chat view learns; every member is optional. */
+export interface IFlexHarnessChatClientListener {
+  /** the tab (re)attached; its conversations, newest first */
+  attached?(sessions: plugins.IHarnessSessionMeta[]): void;
+  sessions?(sessions: plugins.IHarnessSessionMeta[]): void;
+  /** the rows of the open conversation, in order; deltas mutate these objects */
+  rows?(rows: plugins.IHarnessMessage[]): void;
+  delta?(delta: plugins.THarnessStreamDelta): void;
+  status?(status: plugins.IHarnessStatus): void;
+  usage?(usage: plugins.IHarnessUsage): void;
+  permissions?(permissions: plugins.IHarnessPermissionRequest[]): void;
+  history?(history: IFlexHarnessChatHistoryState): void;
+  steer?(outcome: IFlexHarnessChatSteerOutcome): void;
+  /** the open conversation could not be followed again and was closed; the message says why */
+  closed?(message: string): void;
+  /** attaching again after a reconnect failed; the message says why */
+  error?(message: string): void;
+}
+
+/** Runs one tool of a turn in this tab and answers with what the model reads. */
+export type TFlexHarnessChatToolExecutor = (
+  input: TJsonValue,
+  context: { toolCallId: string; abortSignal?: AbortSignal },
+) => Promise<TJsonValue>;
+
+export interface IFlexHarnessChatClientOptions {
+  transport: IFlexHarnessChatClientTransport;
+}
+
+interface IOpenConversation {
+  sessionId: string;
+  subscriptionId: string;
+  /** the seq of the next update */
+  nextSeq: number;
+  rows: Map<string, plugins.IHarnessMessage>;
+  order: string[];
+}
+
+const errorText = (errorArg: unknown, fallbackArg: string): string =>
+  (errorArg instanceof Error && errorArg.message) || fallbackArg;
+
+/** 128 random bits as hex; `getRandomValues` works on plain http too, unlike `randomUUID`. */
+const randomId = (): string =>
+  Array.from(globalThis.crypto.getRandomValues(new Uint8Array(16)), (byte) => byte.toString(16).padStart(2, '0')).join('');
+
+/**
+ * A tab's side of a `FlexHarnessChatHub`: attaches the tab, follows one conversation through
+ * numbered updates and opens it again after a gap or a reconnect, sends what the composer emits,
+ * and runs the tools of the tab's turns, one after another. `dispose()` releases the transport.
+ */
+export class FlexHarnessChatClient {
+  private readonly transport: IFlexHarnessChatClientTransport;
+  private readonly tools = new Map<string, TFlexHarnessChatToolExecutor>();
+  private readonly stopListening: () => void;
+  private readonly stopWatchingReconnects: () => void;
+  private listener: IFlexHarnessChatClientListener | null = null;
+  private sessionsById = new Map<string, plugins.IHarnessSessionMeta>();
+  private open: IOpenConversation | null = null;
+  /** counts opens and closes, so a failed reopen closes only what nothing replaced meanwhile */
+  private openEpoch = 0;
+  /** tools run one after another, so a tool never races the one the model called before it */
+  private toolQueue: Promise<unknown> = Promise.resolve();
+  private disposed = false;
+
+  constructor(optionsArg: IFlexHarnessChatClientOptions) {
+    this.transport = optionsArg.transport;
+    this.stopListening = this.transport.listen({
+      update: (pushArg) => this.applyUpdate(pushArg),
+      sessions: (pushArg) => this.applySessions(pushArg),
+      tool: (requestArg, abortSignalArg) => this.runTool(requestArg, abortSignalArg),
+    });
+    this.stopWatchingReconnects = this.transport.onReconnect(() => {
+      void this.attach().catch((error) =>
+        this.listener?.error?.(errorText(error, 'The conversation could not be reattached after a reconnect.')),
+      );
+    });
+  }
+
+  public setListener(listenerArg: IFlexHarnessChatClientListener | null): void {
+    this.listener = listenerArg;
+  }
+
+  /** Runs the named tool when a turn of this tab calls it, until the returned function is called. */
+  public registerTool(nameArg: string, executorArg: TFlexHarnessChatToolExecutor): () => void {
+    this.tools.set(nameArg, executorArg);
+    return () => {
+      if (this.tools.get(nameArg) === executorArg) this.tools.delete(nameArg);
+    };
+  }
+
+  /** The conversation the tab follows, if any. */
+  public get sessionId(): string | null {
+    return this.open?.sessionId ?? null;
+  }
+
+  /** Attaches the tab, and follows its open conversation again. */
+  public async attach(): Promise<plugins.IHarnessSessionMeta[]> {
+    const result = await this.transport.request('flexHarnessChatAttach', {});
+    this.sessionsById = new Map(result.sessions.map((session) => [session.id, session]));
+    // attaching ends the hub's subscription of this tab
+    const reopen = this.open?.sessionId;
+    this.open = null;
+    this.listener?.attached?.(result.sessions);
+    if (reopen && this.sessionsById.has(reopen)) await this.reopen(reopen);
+    else if (reopen) this.clear();
+    return result.sessions;
+  }
+
+  /** Follows a conversation; its transcript arrives as updates. */
+  public async openSession(sessionIdArg: string): Promise<TFlexHarnessChatResponse<'flexHarnessChatOpen'>> {
+    this.openEpoch++;
+    const open: IOpenConversation = {
+      sessionId: sessionIdArg,
+      subscriptionId: randomId(),
+      nextSeq: 1,
+      rows: new Map(),
+      order: [],
+    };
+    // registered before the request: updates can overtake its answer
+    this.open = open;
+    try {
+      return await this.transport.request('flexHarnessChatOpen', {
+        sessionId: sessionIdArg,
+        subscriptionId: open.subscriptionId,
+      });
+    } catch (error) {
+      if (this.open === open) this.open = null;
+      throw error;
+    }
+  }
+
+  /** Stops following the open conversation; the next message starts a new one. */
+  public async newConversation(): Promise<void> {
+    const open = this.open;
+    this.clear();
+    if (open) await this.transport.request('flexHarnessChatClose', { subscriptionId: open.subscriptionId });
+  }
+
+  /** Sends a message to the open conversation, or starts a new one with it. */
+  public async send(
+    detailArg: plugins.IHarnessComposerSendDetail,
+    contextArg: TJsonValue,
+  ): Promise<TFlexHarnessChatResponse<'flexHarnessChatSend'>> {
+    const sessionId = this.open?.sessionId;
+    const result = await this.transport.request('flexHarnessChatSend', {
+      ...(sessionId ? { sessionId } : {}),
+      send: { delivery: detailArg.delivery, text: detailArg.text, attachments: detailArg.attachments },
+      context: contextArg,
+    });
+    if (result.sessionId !== this.open?.sessionId) await this.openSession(result.sessionId);
+    return result;
+  }
+
+  public async abort(): Promise<void> {
+    const sessionId = this.open?.sessionId;
+    if (sessionId) await this.transport.request('flexHarnessChatAbort', { sessionId });
+  }
+
+  /** Answers a permission card of the open conversation (`harness-permission-response`). */
+  public async respondToPermission(detailArg: plugins.IHarnessPermissionResponseDetail): Promise<void> {
+    // the card reports a remembered approval as `remember`, which FlexHarness calls `always`
+    await this.transport.request('flexHarnessChatPermission', {
+      sessionId: this.requireOpenSessionId(),
+      permissionId: detailArg.requestId,
+      decision: detailArg.response === 'reject' ? 'reject' : detailArg.remember ? 'always' : 'once',
+    });
+  }
+
+  /** Undoes the open conversation's last turn; the conversation is shown again from a reset. */
+  public async undo(): Promise<string> {
+    return (await this.transport.request('flexHarnessChatHistory', {
+      sessionId: this.requireOpenSessionId(),
+      direction: 'undo',
+    })).runId;
+  }
+
+  public async redo(): Promise<string> {
+    return (await this.transport.request('flexHarnessChatHistory', {
+      sessionId: this.requireOpenSessionId(),
+      direction: 'redo',
+    })).runId;
+  }
+
+  public async renameSession(sessionIdArg: string, titleArg: string): Promise<void> {
+    const result = await this.transport.request('flexHarnessChatSessionUpdate', { sessionId: sessionIdArg, title: titleArg });
+    this.sessionsById.set(result.session.id, result.session);
+    this.listener?.sessions?.(this.sessionList());
+  }
+
+  public async deleteSession(sessionIdArg: string): Promise<void> {
+    await this.transport.request('flexHarnessChatSessionDelete', { sessionId: sessionIdArg });
+    this.sessionsById.delete(sessionIdArg);
+    this.listener?.sessions?.(this.sessionList());
+    if (this.open?.sessionId === sessionIdArg) this.clear();
+  }
+
+  /** Stops taking pushes and reconnects; the tab's tools are no longer run. */
+  public dispose(): void {
+    if (this.disposed) return;
+    this.disposed = true;
+    this.stopListening();
+    this.stopWatchingReconnects();
+    this.tools.clear();
+    this.listener = null;
+    this.open = null;
+  }
+
+  private requireOpenSessionId(): string {
+    const sessionId = this.open?.sessionId;
+    if (!sessionId) throw new Error('No conversation is open.');
+    return sessionId;
+  }
+
+  private sessionList(): plugins.IHarnessSessionMeta[] {
+    return [...this.sessionsById.values()].sort((left, right) => (right.updatedAt ?? 0) - (left.updatedAt ?? 0));
+  }
+
+  private clear(): void {
+    this.openEpoch++;
+    this.open = null;
+    this.listener?.rows?.([]);
+    this.listener?.permissions?.([]);
+    this.listener?.status?.({ type: 'idle' });
+    this.listener?.usage?.({});
+  }
+
+  /** Follows the conversation again; when that fails, closes it and says why. */
+  private async reopen(sessionIdArg: string): Promise<void> {
+    const reopening = this.openSession(sessionIdArg);
+    const epoch = this.openEpoch;
+    try {
+      await reopening;
+    } catch (error) {
+      // another conversation was opened or a new one started meanwhile: that one stays
+      if (this.openEpoch !== epoch) return;
+      this.clear();
+      this.listener?.closed?.(errorText(error, 'The conversation could not be opened again.'));
+    }
+  }
+
+  private applySessions(pushArg: IFlexHarnessChatSessionsPush): void {
+    for (const id of pushArg.deletedIds) this.sessionsById.delete(id);
+    for (const session of pushArg.upserts) this.sessionsById.set(session.id, session);
+    this.listener?.sessions?.(this.sessionList());
+  }
+
+  private applyUpdate(updateArg: IFlexHarnessChatUpdate): void {
+    const open = this.open;
+    if (!open || updateArg.subscriptionId !== open.subscriptionId) return;
+    if (updateArg.seq !== open.nextSeq) {
+      // an update was lost: read the conversation again
+      void this.reopen(open.sessionId);
+      return;
+    }
+    open.nextSeq++;
+    if (updateArg.reset) open.rows.clear();
+    if (updateArg.rows) {
+      for (const row of updateArg.rows.upserts) open.rows.set(row.id, row);
+      open.order = updateArg.rows.order;
+      const kept = new Set(open.order);
+      for (const id of [...open.rows.keys()]) {
+        if (!kept.has(id)) open.rows.delete(id);
+      }
+      this.listener?.rows?.(open.order.flatMap((id) => open.rows.get(id) ?? []));
+    }
+    for (const delta of updateArg.deltas ?? []) this.listener?.delta?.(delta);
+    if (updateArg.status) this.listener?.status?.(updateArg.status);
+    if (updateArg.usage) this.listener?.usage?.(updateArg.usage);
+    if (updateArg.permissions) this.listener?.permissions?.(updateArg.permissions);
+    if (updateArg.history) this.listener?.history?.(updateArg.history);
+    for (const steer of updateArg.steers ?? []) this.listener?.steer?.(steer);
+  }
+
+  private runTool(requestArg: IFlexHarnessChatToolRequest, abortSignalArg: AbortSignal | undefined): Promise<TJsonValue> {
+    const run = this.toolQueue.then(() => {
+      abortSignalArg?.throwIfAborted();
+      const executor = this.tools.get(requestArg.name);
+      if (!executor) throw new Error(`This tab does not run the tool "${requestArg.name}".`);
+      return untilAborted(
+        executor(requestArg.input, {
+          toolCallId: requestArg.toolCallId,
+          ...(abortSignalArg ? { abortSignal: abortSignalArg } : {}),
+        }),
+        abortSignalArg,
+      );
+    });
+    this.toolQueue = run.catch(() => undefined);
+    return run;
+  }
+}
+
+/** The work's result, or a rejection as soon as the signal aborts; the work itself may run on. */
+const untilAborted = <T>(workArg: Promise<T>, signalArg: AbortSignal | undefined): Promise<T> => {
+  if (!signalArg) return workArg;
+  if (signalArg.aborted) return Promise.reject(signalArg.reason ?? new Error('The tool call was cancelled.'));
+  return new Promise<T>((resolve, reject) => {
+    const onAbort = () => reject(signalArg.reason ?? new Error('The tool call was cancelled.'));
+    signalArg.addEventListener('abort', onAbort, { once: true });
+    workArg.then(
+      (value) => {
+        signalArg.removeEventListener('abort', onAbort);
+        resolve(value);
+      },
+      (error) => {
+        signalArg.removeEventListener('abort', onAbort);
+        reject(error);
+      },
+    );
+  });
+};

package/ts_chat_harness/classes.chatrequesterror.ts

@@ -0,0 +1,7 @@
+/** A chat request the hub refuses; its message is written for the person in the tab. */
+export class FlexHarnessChatRequestError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'FlexHarnessChatRequestError';
+  }
+}

package/ts_chat_harness/classes.transcript.ts

@@ -6,7 +6,7 @@ import type {
   IFlexSession,
   TFlexHarnessEvent,
   TFlexMessagePart,
-} from '../ts/interfaces.js';
+} from '@modelprofile.com/flexharness';
 import {
   flexMessageToHarnessRows,
   flexPartRowId,

package/ts_chat_harness/functions.intents.ts

@@ -1,11 +1,11 @@
 import type * as plugins from './plugins.js';
-import type { FlexHarness } from '../ts/classes.flexharness.js';
 import type {
+  FlexHarness,
   IFlexPromptOptions,
   IFlexPromptQueueAdmission,
   TFlexPermissionDecision,
   TFlexPromptPart,
-} from '../ts/interfaces.js';
+} from '@modelprofile.com/flexharness';
 
 /** The session a chat view shows. */
 export interface IFlexHarnessChatTarget {

package/ts_chat_harness/functions.mapping.ts

@@ -9,7 +9,7 @@ import type {
   IFlexToolMessagePart,
   IFlexUsage,
   TFlexToolPartStatus,
-} from '../ts/interfaces.js';
+} from '@modelprofile.com/flexharness';
 
 /** When a streamed part started and ended, as the events that carried it stated. */
 export interface IFlexPartTiming {

package/ts_chat_harness/index.ts

@@ -31,3 +31,23 @@ export {
   type TFlexHarnessChatHost,
   type TFlexHarnessChatIntent,
 } from './functions.intents.js';
+export { FlexHarnessChatRequestError } from './classes.chatrequesterror.js';
+export {
+  FlexHarnessChatClient,
+  type IFlexHarnessChatClientListener,
+  type IFlexHarnessChatClientOptions,
+  type IFlexHarnessChatClientTransport,
+  type IFlexHarnessChatPushHandlers,
+  type TFlexHarnessChatToolExecutor,
+} from './classes.chatclient.js';
+export type {
+  IFlexHarnessChatHistoryState,
+  IFlexHarnessChatMethods,
+  IFlexHarnessChatSessionsPush,
+  IFlexHarnessChatSteerOutcome,
+  IFlexHarnessChatToolRequest,
+  IFlexHarnessChatUpdate,
+  TFlexHarnessChatMethod,
+  TFlexHarnessChatRequest,
+  TFlexHarnessChatResponse,
+} from './interfaces.chat.js';

package/ts_chat_harness/interfaces.chat.ts

@@ -0,0 +1,108 @@
+import type * as plugins from './plugins.js';
+import type { TFlexPermissionDecision, TJsonValue } from '@modelprofile.com/flexharness';
+
+// The contract between a `FlexHarnessChatHub` on the server and a `FlexHarnessChatClient` in a
+// browser tab, as plain data any transport can carry. Requests go from the tab to the hub; pushes
+// go from the hub to the tab. The transport names the tab; requests carry no caller identity.
+
+/** What became of a steer: the running turn read it, or it ended without reading it. */
+export interface IFlexHarnessChatSteerOutcome {
+  steerId: string;
+  outcome: 'applied' | 'unapplied';
+}
+
+/** Whether the conversation's last turn can be undone, or an undone one redone. */
+export interface IFlexHarnessChatHistoryState {
+  undoAvailable: boolean;
+  redoAvailable: boolean;
+}
+
+/**
+ * Push: what changed in the conversation a tab follows. Apply in `seq` order, the parts in the order
+ * listed here: `rows`, then `deltas`, then the rest. A tab that sees a gap in `seq` opens the
+ * conversation again, which starts with a `reset`.
+ */
+export interface IFlexHarnessChatUpdate {
+  subscriptionId: string;
+  /** 1 for the first update of a subscription, one more for every later one */
+  seq: number;
+  /** forget every row: `rows` lists them all */
+  reset?: true;
+  /** the rows that are new or changed since the last update, and the order of all of them */
+  rows?: { upserts: plugins.IHarnessMessage[]; order: string[] };
+  /** streamed text and tool progress, for `dees-harness-chat.applyDelta()` */
+  deltas?: plugins.THarnessStreamDelta[];
+  status?: plugins.IHarnessStatus;
+  usage?: plugins.IHarnessUsage;
+  /** every pending permission request of the conversation */
+  permissions?: plugins.IHarnessPermissionRequest[];
+  history?: IFlexHarnessChatHistoryState;
+  steers?: IFlexHarnessChatSteerOutcome[];
+}
+
+/** Push: conversations of the tab's list that were added, changed or deleted. */
+export interface IFlexHarnessChatSessionsPush {
+  upserts: plugins.IHarnessSessionMeta[];
+  deletedIds: string[];
+}
+
+/** Push: run one tool of a turn in the tab that started the turn; the answer is the tool's output. */
+export interface IFlexHarnessChatToolRequest {
+  toolCallId: string;
+  name: string;
+  input: TJsonValue;
+}
+
+/** The requests a tab makes, by method name. */
+export interface IFlexHarnessChatMethods {
+  /** Attach the tab: lists its conversations, newest first. A tab attaches after every reconnect. */
+  flexHarnessChatAttach: {
+    request: Record<string, never>;
+    response: { sessions: plugins.IHarnessSessionMeta[] };
+  };
+  /**
+   * Follow a conversation. Its state arrives as updates under `subscriptionId`, chosen by the tab
+   * (16 random bytes, hex), starting with a `reset`. A tab follows one conversation at a time.
+   */
+  flexHarnessChatOpen: {
+    request: { sessionId: string; subscriptionId: string };
+    response: { session: plugins.IHarnessSessionMeta; readOnly: boolean };
+  };
+  flexHarnessChatClose: {
+    request: { subscriptionId: string };
+    response: Record<string, never>;
+  };
+  /**
+   * Send a message; without `sessionId` it starts a conversation. While a turn runs, the message
+   * steers it. The answer comes once the message is admitted.
+   */
+  flexHarnessChatSend: {
+    request: { sessionId?: string; send: plugins.IHarnessComposerSendDetail; context: TJsonValue };
+    response: { sessionId: string; queueId?: string; steerId?: string };
+  };
+  flexHarnessChatAbort: {
+    request: { sessionId: string };
+    response: Record<string, never>;
+  };
+  flexHarnessChatPermission: {
+    request: { sessionId: string; permissionId: string; decision: TFlexPermissionDecision };
+    response: Record<string, never>;
+  };
+  /** Undo the conversation's last turn or redo the last undone one, files included when captured. */
+  flexHarnessChatHistory: {
+    request: { sessionId: string; direction: 'undo' | 'redo' };
+    response: { runId: string };
+  };
+  flexHarnessChatSessionUpdate: {
+    request: { sessionId: string; title: string };
+    response: { session: plugins.IHarnessSessionMeta };
+  };
+  flexHarnessChatSessionDelete: {
+    request: { sessionId: string };
+    response: Record<string, never>;
+  };
+}
+
+export type TFlexHarnessChatMethod = keyof IFlexHarnessChatMethods;
+export type TFlexHarnessChatRequest<TMethod extends TFlexHarnessChatMethod> = IFlexHarnessChatMethods[TMethod]['request'];
+export type TFlexHarnessChatResponse<TMethod extends TFlexHarnessChatMethod> = IFlexHarnessChatMethods[TMethod]['response'];

package/ts_chat_harness/readme.md

@@ -93,6 +93,30 @@ Intents are untrusted client input: a client can name any `scopeId` and `session
 - `harness-permission-response`: `reject` rejects; an approval with `remember` is `always`, otherwise `once`. A request with `requiresExplicitResponse` refuses `always`.
 - `harness-abort`: `abort()` of the session.
 
+## Chat client
+
+`FlexHarnessChatClient` is a tab's side of a `FlexHarnessChatHub` (`/chat/harness/server`), over any `IFlexHarnessChatClientTransport`; `/chat/harness/typedsocket` provides one. The wire contract is `IFlexHarnessChatMethods` (requests by method name), `IFlexHarnessChatUpdate`, `IFlexHarnessChatSessionsPush` and `IFlexHarnessChatToolRequest`, plain data any transport can carry.
+
+```typescript
+const client = new FlexHarnessChatClient({ transport });
+client.setListener({
+  attached: (sessions) => (sessionList.sessions = sessions),
+  sessions: (sessions) => (sessionList.sessions = sessions),
+  rows: (rows) => (chat.messages = rows),
+  delta: (delta) => chat.applyDelta(delta),
+  status: (status) => (chat.status = status),
+  usage: (usage) => (chat.usage = usage),
+  permissions: (permissions) => (chat.permissions = permissions),
+});
+client.registerTool('snapshot', async (input, { abortSignal }) => takeSnapshot(input, abortSignal));
+await client.attach();
+chat.addEventListener('harness-send', (event) => client.send(event.detail, currentContext()));
+chat.addEventListener('harness-permission-response', (event) => client.respondToPermission(event.detail));
+chat.addEventListener('harness-abort', () => client.abort());
+```
+
+The client follows one conversation. Updates apply in `seq` order; a gap opens the conversation again from a reset, and a restored connection attaches again and reopens it. `send()` without an open conversation starts one and follows it. A message sent while a turn runs steers it, so the chat offers `busyDeliveryModes: ['steer']`. Tools of the tab's turns run one after another, so a tool never races the one the model called before it; a cancelled call settles at once. `undo()` and `redo()` move the open conversation's history, files included when the host captures them. `dispose()` stops listening to the transport and running tools.
+
 ## Issue Reporting and Security
 
 Report issues and security concerns through [community.foss.global](https://community.foss.global).