@modelprofile.com/flexharness 10.0.0 → 10.1.0

package/ts_chat_harness/classes.transcript.ts

@@ -0,0 +1,365 @@
+import type * as plugins from './plugins.js';
+import type {
+  IFlexMessage,
+  IFlexPermissionRequest,
+  IFlexProjectStateResult,
+  IFlexSession,
+  TFlexHarnessEvent,
+  TFlexMessagePart,
+} from '../ts/interfaces.js';
+import {
+  flexMessageToHarnessRows,
+  flexPartRowId,
+  flexPartTimingKey,
+  flexPermissionToHarness,
+  flexProjectToHarnessScratchpad,
+  flexProjectToHarnessTodos,
+  flexSessionToHarnessStatus,
+  flexToolPartToHarness,
+  flexUsageToHarness,
+  type IFlexPartTiming,
+} from './functions.mapping.js';
+
+export interface IFlexHarnessTranscriptOptions {
+  scopeId: string;
+  sessionId: string;
+}
+
+/** What `load()` reads: the session's authoritative state, as the harness APIs return it. */
+export interface IFlexHarnessTranscriptSnapshot {
+  /** `getMessages()` of the session. */
+  messages: readonly IFlexMessage[];
+  /** `listPendingPermissions()` of the session. */
+  permissions?: readonly IFlexPermissionRequest[];
+  /** `getSession()`; states whether a run is active or failed. */
+  session?: IFlexSession;
+  /** `getProjectState()`, when project management is enabled. */
+  project?: IFlexProjectStateResult;
+}
+
+/** The inputs of `dees-harness-chat`, as plain data the transcript does not share. */
+export interface IFlexHarnessTranscriptView {
+  messages: plugins.IHarnessMessage[];
+  permissions: plugins.IHarnessPermissionRequest[];
+  /** FlexHarness asks no questions; always empty. */
+  questions: plugins.IHarnessQuestionRequest[];
+  status: plugins.IHarnessStatus;
+  usage: plugins.IHarnessUsage;
+  todos: plugins.IHarnessTodoItem[];
+  scratchpad?: plugins.IHarnessScratchpad;
+}
+
+/** Where an event stands in its harness instance's event stream, as the host received it. */
+export interface IFlexHarnessEventDelivery {
+  /**
+   * The `sequence` of the event of the same harness instance the host received just before this
+   * one, of any session; `undefined` for the first event after `load()`. The host forwards every
+   * event of the instance in order, and calls `load()` after a gap or a reconnect.
+   */
+  precedingSequence: number | undefined;
+}
+
+/**
+ * What one event changed. Apply `deltas` with `applyDelta()` in order; when `messages` is true,
+ * assign `transcript.view().messages` instead, which already holds the deltas. `reload` means
+ * the transcript can no longer follow the session incrementally: read the session again and
+ * pass it to `load()`.
+ */
+export interface IFlexHarnessTranscriptChange {
+  messages: boolean;
+  deltas: plugins.THarnessStreamDelta[];
+  permissions: boolean;
+  status: boolean;
+  usage: boolean;
+  reload: boolean;
+}
+
+const utf8 = new TextEncoder();
+
+/** UTF-8 bytes `delta` adds to `text`, counted the way FlexHarness counts them. */
+function appendedUtf8Bytes(text: string, delta: string): number {
+  const trailing = text.charCodeAt(text.length - 1);
+  const leading = delta.charCodeAt(0);
+  const joinsSurrogatePair = trailing >= 0xd800 && trailing <= 0xdbff
+    && leading >= 0xdc00 && leading <= 0xdfff;
+  return utf8.encode(delta).length - (joinsSurrogatePair ? 2 : 0);
+}
+
+function sumUsage(
+  total: plugins.IHarnessUsage,
+  usage: plugins.IHarnessUsage,
+): plugins.IHarnessUsage {
+  const sum = (key: keyof plugins.IHarnessUsage) => (total[key] ?? 0) + (usage[key] ?? 0);
+  return {
+    inputTokens: sum('inputTokens'),
+    outputTokens: sum('outputTokens'),
+    totalTokens: sum('totalTokens'),
+    cacheReadTokens: sum('cacheReadTokens'),
+    cacheWriteTokens: sum('cacheWriteTokens'),
+  };
+}
+
+const noChange = (): IFlexHarnessTranscriptChange => ({
+  messages: false,
+  deltas: [],
+  permissions: false,
+  status: false,
+  usage: false,
+  reload: false,
+});
+
+/**
+ * Follows one FlexHarness session and keeps the `dees-harness-chat` inputs for it. It is a pure
+ * reducer over the session's public messages and events: it imports no runtime code, so it runs
+ * in the browser beside the components as well as on the server beside the harness.
+ */
+export class FlexHarnessTranscript {
+  public readonly scopeId: string;
+  public readonly sessionId: string;
+  private flexMessages: IFlexMessage[] = [];
+  private readonly timings = new Map<string, IFlexPartTiming>();
+  private readonly partBytes = new Map<string, number>();
+  private readonly permissionRows = new Map<string, plugins.IHarnessPermissionRequest>();
+  private status: plugins.IHarnessStatus = { type: 'idle' };
+  private usage: plugins.IHarnessUsage = {};
+  private todos: plugins.IHarnessTodoItem[] = [];
+  private scratchpad?: plugins.IHarnessScratchpad;
+  private runningQueueId?: string;
+
+  constructor(options: IFlexHarnessTranscriptOptions) {
+    this.scopeId = options.scopeId;
+    this.sessionId = options.sessionId;
+  }
+
+  /** The queue entry whose run is running; a steer joins it. */
+  public get activeQueueId(): string | undefined {
+    return this.runningQueueId;
+  }
+
+  /** Replaces everything with the session's authoritative state. */
+  public load(snapshot: IFlexHarnessTranscriptSnapshot): void {
+    this.flexMessages = [];
+    this.todos = [];
+    this.scratchpad = undefined;
+    this.runningQueueId = undefined;
+    this.timings.clear();
+    this.partBytes.clear();
+    for (const message of snapshot.messages) this.upsertMessage(message);
+    this.permissionRows.clear();
+    for (const request of snapshot.permissions ?? []) {
+      this.permissionRows.set(request.permissionId, flexPermissionToHarness(request));
+    }
+    this.status = snapshot.session ? flexSessionToHarnessStatus(snapshot.session) : { type: 'idle' };
+    this.usage = this.flexMessages.reduce<plugins.IHarnessUsage>(
+      (total, message) => message.usage ? sumUsage(total, flexUsageToHarness(message.usage)) : total,
+      {},
+    );
+    if (snapshot.project) this.applyProjectState(snapshot.project);
+  }
+
+  /** Takes in the session's task list and scratchpad after `getProjectState()`. */
+  public applyProjectState(project: IFlexProjectStateResult): void {
+    this.todos = flexProjectToHarnessTodos(project);
+    this.scratchpad = flexProjectToHarnessScratchpad(this.sessionId, project);
+  }
+
+  /** A copy of the component inputs; the transcript keeps its own objects. */
+  public view(): IFlexHarnessTranscriptView {
+    return structuredClone({
+      messages: this.flexMessages.flatMap((message, index) =>
+        flexMessageToHarnessRows(message, index, this.timings)),
+      permissions: [...this.permissionRows.values()],
+      questions: [],
+      status: this.status,
+      usage: this.usage,
+      todos: this.todos,
+      ...(this.scratchpad === undefined ? {} : { scratchpad: this.scratchpad }),
+    });
+  }
+
+  /**
+   * Takes one event of the harness instance. An event that does not directly follow
+   * `delivery.precedingSequence` means events were lost, possibly of this session, so the change
+   * asks for a reload.
+   */
+  public applyEvent(
+    event: TFlexHarnessEvent,
+    delivery: IFlexHarnessEventDelivery,
+  ): IFlexHarnessTranscriptChange {
+    const change = noChange();
+    if (
+      delivery.precedingSequence !== undefined
+      && event.sequence !== delivery.precedingSequence + 1
+    ) {
+      change.reload = true;
+      return change;
+    }
+    if (event.scopeId !== this.scopeId || event.sessionId !== this.sessionId) return change;
+    const timestamp = Date.parse(event.timestamp);
+    switch (event.type) {
+      case 'session.created':
+      case 'session.updated':
+        this.setStatus(change, flexSessionToHarnessStatus(event.session));
+        break;
+      case 'session.deleted':
+        this.load({ messages: [] });
+        change.messages = change.permissions = change.status = change.usage = true;
+        break;
+      case 'run.started':
+        this.setStatus(change, { type: 'busy' });
+        break;
+      case 'message.created':
+      case 'message.updated':
+        this.upsertMessage(event.message);
+        change.messages = true;
+        break;
+      case 'part.started':
+        this.timings.set(flexPartTimingKey(event.messageId, event.partId), { startedAt: timestamp });
+        this.applyPartSnapshot(change, event.messageId, event.partIndex, event.part);
+        break;
+      case 'part.updated':
+        this.applyPartSnapshot(change, event.messageId, event.partIndex, event.part);
+        break;
+      case 'part.completed': {
+        const key = flexPartTimingKey(event.messageId, event.partId);
+        this.timings.set(key, { ...this.timings.get(key), endedAt: timestamp });
+        this.applyPartSnapshot(change, event.messageId, event.partIndex, event.part);
+        break;
+      }
+      case 'part.delta':
+        this.applyPartDelta(change, event);
+        break;
+      case 'permission.requested':
+        this.permissionRows.set(event.request.permissionId, flexPermissionToHarness(event.request));
+        change.permissions = true;
+        break;
+      case 'permission.resolved': {
+        const row = this.permissionRows.get(event.request.permissionId);
+        if (!row) break;
+        row.response = event.decision;
+        row.respondedAt = timestamp;
+        change.permissions = true;
+        break;
+      }
+      case 'run.finished':
+        this.upsertMessage(event.message);
+        change.messages = true;
+        if (event.message.usage) {
+          this.usage = sumUsage(this.usage, flexUsageToHarness(event.message.usage));
+          change.usage = true;
+        }
+        this.setStatus(change, event.status === 'failed'
+          ? { type: 'error', ...(event.error ? { message: event.error.message } : {}) }
+          : { type: 'idle' });
+        break;
+      case 'prompt.started':
+      case 'prompt.running':
+        this.runningQueueId = event.queueId;
+        break;
+      case 'prompt.finished':
+        if (this.runningQueueId === event.queueId) this.runningQueueId = undefined;
+        break;
+      case 'session.history.changed':
+        change.reload = true;
+        break;
+      default:
+        break;
+    }
+    return change;
+  }
+
+  private setStatus(change: IFlexHarnessTranscriptChange, status: plugins.IHarnessStatus): void {
+    if (status.type === this.status.type && status.message === this.status.message) return;
+    this.status = status;
+    change.status = true;
+  }
+
+  private upsertMessage(message: IFlexMessage): void {
+    const index = this.flexMessages.findIndex((entry) => entry.messageId === message.messageId);
+    const copy = structuredClone(message);
+    if (index === -1) this.flexMessages.push(copy);
+    else this.flexMessages[index] = copy;
+    for (const part of copy.parts) {
+      if (part.type === 'text' || part.type === 'reasoning') {
+        this.partBytes.set(flexPartTimingKey(copy.messageId, part.partId), utf8.encode(part.text).length);
+      }
+    }
+  }
+
+  private applyPartSnapshot(
+    change: IFlexHarnessTranscriptChange,
+    messageId: string,
+    partIndex: number,
+    part: TFlexMessagePart,
+  ): void {
+    const message = this.flexMessages.find((entry) => entry.messageId === messageId);
+    if (!message || partIndex > message.parts.length) {
+      change.reload = true;
+      return;
+    }
+    const previous = message.parts[partIndex];
+    message.parts[partIndex] = structuredClone(part);
+    const key = flexPartTimingKey(messageId, part.partId);
+    if (part.type === 'text' || part.type === 'reasoning') {
+      this.partBytes.set(key, utf8.encode(part.text).length);
+    }
+    const rowId = flexPartRowId(messageId, part.partId);
+    if (previous?.partId !== part.partId || previous.type !== part.type) {
+      change.messages = true;
+      return;
+    }
+    if (part.type === 'tool') {
+      change.deltas.push({
+        type: 'tool-update',
+        messageId: rowId,
+        tool: flexToolPartToHarness(part, this.timings.get(key)),
+      });
+    } else if (part.type === 'text' && previous.type === 'text') {
+      if (previous.text !== part.text) change.messages = true;
+      else if (message.status !== 'streaming' || partIndex !== message.parts.length - 1) {
+        change.deltas.push({ type: 'message-end', messageId: rowId });
+      }
+    } else if (part.type === 'reasoning' && previous.type === 'reasoning') {
+      if (previous.text !== part.text) change.messages = true;
+      else if (part.status !== 'running') {
+        change.deltas.push({
+          type: 'reasoning-end',
+          messageId: rowId,
+          partId: part.partId,
+          endedAt: this.timings.get(key)?.endedAt,
+        });
+      }
+    } else {
+      change.messages = true;
+    }
+  }
+
+  private applyPartDelta(
+    change: IFlexHarnessTranscriptChange,
+    event: Extract<TFlexHarnessEvent, { type: 'part.delta' }>,
+  ): void {
+    const message = this.flexMessages.find((entry) => entry.messageId === event.messageId);
+    const part = message?.parts[event.partIndex];
+    const key = flexPartTimingKey(event.messageId, event.partId);
+    if (
+      !part
+      || part.partId !== event.partId
+      || part.type !== event.partType
+      || this.partBytes.get(key) !== event.baseTextUtf8Bytes
+    ) {
+      change.reload = true;
+      return;
+    }
+    const bytes = event.baseTextUtf8Bytes + appendedUtf8Bytes(part.text, event.delta);
+    if (bytes !== event.textUtf8Bytes) {
+      change.reload = true;
+      return;
+    }
+    part.text += event.delta;
+    this.partBytes.set(key, bytes);
+    const rowId = flexPartRowId(event.messageId, event.partId);
+    change.deltas.push(event.partType === 'text'
+      ? { type: 'text', messageId: rowId, delta: event.delta }
+      : { type: 'reasoning', messageId: rowId, partId: event.partId, delta: event.delta });
+  }
+}

package/ts_chat_harness/functions.intents.ts

@@ -0,0 +1,169 @@
+import type * as plugins from './plugins.js';
+import type { FlexHarness } from '../ts/classes.flexharness.js';
+import type {
+  IFlexPromptOptions,
+  IFlexPromptQueueAdmission,
+  TFlexPermissionDecision,
+  TFlexPromptPart,
+} from '../ts/interfaces.js';
+
+/** The session a chat view shows. */
+export interface IFlexHarnessChatTarget {
+  scopeId: string;
+  sessionId: string;
+}
+
+/**
+ * One call a chat view asks the harness to make, as plain data a host can carry from the browser
+ * to the server that owns the harness.
+ */
+export type TFlexHarnessChatIntent =
+  | (IFlexHarnessChatTarget & {
+      type: 'enqueuePrompt';
+      prompt: TFlexPromptPart[];
+      options: IFlexPromptOptions;
+    })
+  | (IFlexHarnessChatTarget & {
+      type: 'steerPrompt';
+      queueId: string;
+      steerId: string;
+      prompt: TFlexPromptPart[];
+      options: IFlexPromptOptions;
+    })
+  | (IFlexHarnessChatTarget & {
+      type: 'respondToPermission';
+      permissionId: string;
+      decision: TFlexPermissionDecision;
+    })
+  | (IFlexHarnessChatTarget & { type: 'abort' });
+
+export interface IFlexHarnessSendIntentOptions {
+  /** The running queue entry, `FlexHarnessTranscript.activeQueueId`; a steer joins it. */
+  activeQueueId?: string;
+  /**
+   * The model hint the prompt carries. Defaults to the composer's `model`. A host that offers
+   * accounts or reasoning efforts encodes them in its own hint scheme here.
+   */
+  modelHint?: string;
+}
+
+function base64Utf8(text: string): string {
+  const bytes = new TextEncoder().encode(text);
+  let binary = '';
+  for (let offset = 0; offset < bytes.length; offset += 0x8000) {
+    binary += String.fromCharCode(...bytes.subarray(offset, offset + 0x8000));
+  }
+  return btoa(binary);
+}
+
+function attachmentToPromptPart(attachment: plugins.IHarnessAttachment): TFlexPromptPart {
+  if (attachment.truncated) {
+    throw new Error(`Attachment "${attachment.name}" is truncated and cannot be sent.`);
+  }
+  const described = { mediaType: attachment.mediaType, name: attachment.name };
+  if (attachment.kind === 'text' && attachment.text !== undefined) {
+    return { type: 'file', data: base64Utf8(attachment.text), ...described };
+  }
+  if (attachment.dataBase64 === undefined) {
+    throw new Error(`Attachment "${attachment.name}" carries no payload.`);
+  }
+  return attachment.kind === 'image'
+    ? { type: 'image', data: attachment.dataBase64, ...described }
+    : { type: 'file', data: attachment.dataBase64, ...described };
+}
+
+/**
+ * Maps `harness-send`. A message sent while idle, or queued behind the running turn, becomes a
+ * queued prompt. A steer joins the running turn; with no running turn it is the next turn's
+ * input, so it is queued as well. A steer keeps the prompt options for that case only: it answers
+ * on the running turn's model. A steer id comes from `crypto.randomUUID()`, which browsers offer
+ * in secure contexts only (HTTPS or localhost).
+ */
+export function flexHarnessSendIntent(
+  target: IFlexHarnessChatTarget,
+  detail: plugins.IHarnessComposerSendDetail,
+  options: IFlexHarnessSendIntentOptions = {},
+): TFlexHarnessChatIntent {
+  const prompt: TFlexPromptPart[] = [
+    ...(detail.text.length > 0 ? [{ type: 'text' as const, text: detail.text }] : []),
+    ...detail.attachments.map(attachmentToPromptPart),
+  ];
+  const modelHint = options.modelHint ?? detail.model;
+  const promptOptions: IFlexPromptOptions = modelHint === undefined ? {} : { modelHint };
+  if (detail.delivery === 'steer' && options.activeQueueId !== undefined) {
+    return {
+      ...target,
+      type: 'steerPrompt',
+      queueId: options.activeQueueId,
+      steerId: globalThis.crypto.randomUUID(),
+      prompt,
+      options: promptOptions,
+    };
+  }
+  return { ...target, type: 'enqueuePrompt', prompt, options: promptOptions };
+}
+
+/**
+ * Maps `harness-permission-response`. The card reports a remembered approval as `remember`,
+ * which FlexHarness calls `always`.
+ */
+export function flexHarnessPermissionIntent(
+  target: IFlexHarnessChatTarget,
+  detail: plugins.IHarnessPermissionResponseDetail,
+): TFlexHarnessChatIntent {
+  const decision: TFlexPermissionDecision = detail.response === 'reject'
+    ? 'reject'
+    : detail.remember ? 'always' : 'once';
+  return { ...target, type: 'respondToPermission', permissionId: detail.requestId, decision };
+}
+
+/** Maps `harness-abort`. */
+export function flexHarnessAbortIntent(target: IFlexHarnessChatTarget): TFlexHarnessChatIntent {
+  return { ...target, type: 'abort' };
+}
+
+/** The harness calls `runFlexHarnessChatIntent` makes. */
+export type TFlexHarnessChatHost = Pick<
+  FlexHarness<unknown>,
+  'enqueuePrompt' | 'steerPrompt' | 'respondToPermission' | 'abort'
+>;
+
+const steerNotRunningCode = 'FLEX_STEER_NOT_RUNNING';
+
+/**
+ * Makes the call an intent names, on the server that owns the harness, once the harness admitted
+ * it. A queued prompt returns its admission: its `completion` settles when the run ends, and the
+ * caller owns it, as with `enqueuePrompt()`. A steer whose turn ended before the harness took it
+ * is the next turn's input, so it is queued instead and returns that admission.
+ */
+export async function runFlexHarnessChatIntent(
+  harness: TFlexHarnessChatHost,
+  intent: TFlexHarnessChatIntent,
+): Promise<IFlexPromptQueueAdmission | undefined> {
+  switch (intent.type) {
+    case 'enqueuePrompt':
+      return harness.enqueuePrompt(intent.scopeId, intent.sessionId, intent.prompt, intent.options);
+    case 'steerPrompt':
+      try {
+        await harness.steerPrompt(intent.scopeId, intent.sessionId, intent.queueId, {
+          steerId: intent.steerId,
+          prompt: intent.prompt,
+        });
+        return undefined;
+      } catch (error) {
+        if ((error as { code?: unknown }).code !== steerNotRunningCode) throw error;
+        return harness.enqueuePrompt(intent.scopeId, intent.sessionId, intent.prompt, intent.options);
+      }
+    case 'respondToPermission':
+      await harness.respondToPermission(
+        intent.scopeId,
+        intent.sessionId,
+        intent.permissionId,
+        intent.decision,
+      );
+      return undefined;
+    case 'abort':
+      await harness.abort(intent.scopeId, intent.sessionId);
+      return undefined;
+  }
+}