@modelprofile.com/flexharness 10.0.0 → 10.2.0

package/ts_chat_harness/functions.mapping.ts

@@ -0,0 +1,267 @@
+import type * as plugins from './plugins.js';
+import type {
+  IFlexAttachmentMessagePart,
+  IFlexMessage,
+  IFlexModelIdentity,
+  IFlexPermissionRequest,
+  IFlexProjectStateResult,
+  IFlexSession,
+  IFlexToolMessagePart,
+  IFlexUsage,
+  TFlexToolPartStatus,
+} from '../ts/interfaces.js';
+
+/** When a streamed part started and ended, as the events that carried it stated. */
+export interface IFlexPartTiming {
+  startedAt?: number;
+  endedAt?: number;
+}
+
+export type TFlexPartTimings = ReadonlyMap<string, IFlexPartTiming>;
+
+/** The transcript row of one part of an assistant message. */
+export const flexPartRowId = (messageId: string, partId: string): string => `${messageId}:${partId}`;
+
+export const flexPartTimingKey = flexPartRowId;
+
+const epoch = (timestamp: string | undefined): number | undefined => {
+  if (timestamp === undefined) return undefined;
+  const value = Date.parse(timestamp);
+  return Number.isFinite(value) ? value : undefined;
+};
+
+export const flexModelLabel = (model: IFlexModelIdentity): string => `${model.provider}/${model.model}`;
+
+export const flexUsageToHarness = (usage: IFlexUsage): plugins.IHarnessUsage => ({
+  inputTokens: usage.inputTokens,
+  outputTokens: usage.outputTokens,
+  totalTokens: usage.totalTokens,
+  cacheReadTokens: usage.cacheReadTokens,
+  cacheWriteTokens: usage.cacheWriteTokens,
+});
+
+const toolStatuses: Record<TFlexToolPartStatus, plugins.THarnessToolStatus> = {
+  running: 'running',
+  completed: 'completed',
+  failed: 'error',
+  cancelled: 'stopped',
+};
+
+export function flexToolPartToHarness(
+  part: IFlexToolMessagePart,
+  timing?: IFlexPartTiming,
+): plugins.IHarnessToolCall {
+  return {
+    id: part.toolCallId,
+    name: part.toolName,
+    status: toolStatuses[part.status],
+    input: part.input,
+    ...(part.output === undefined ? {} : { output: part.output }),
+    ...(part.status === 'failed' ? { isError: true } : {}),
+    ...(part.error === undefined ? {} : { errorText: part.error }),
+    ...(part.childSessionId === undefined ? {} : { childSessionId: part.childSessionId }),
+    ...(part.model === undefined ? {} : { model: flexModelLabel(part.model) }),
+    ...(timing?.startedAt === undefined ? {} : { startedAt: timing.startedAt }),
+    ...(timing?.endedAt === undefined ? {} : { finishedAt: timing.endedAt }),
+  };
+}
+
+/**
+ * The public projection keeps no attachment payload. An attachment the components can show needs
+ * its name, media type and size; one whose source did not state all three, such as a remote URL
+ * of unknown size, has no row.
+ */
+export function flexAttachmentToHarness(
+  part: IFlexAttachmentMessagePart,
+): plugins.IHarnessAttachment | undefined {
+  if (part.name === undefined || part.mediaType === undefined || part.sizeBytes === undefined) {
+    return undefined;
+  }
+  return {
+    id: part.partId,
+    name: part.name,
+    mediaType: part.mediaType,
+    size: part.sizeBytes,
+    kind: part.attachmentType === 'image' ? 'image' : 'binary',
+  };
+}
+
+function attachmentsOf(message: IFlexMessage): plugins.IHarnessAttachment[] {
+  return message.parts.flatMap((part) => {
+    if (part.type !== 'attachment') return [];
+    const attachment = flexAttachmentToHarness(part);
+    return attachment ? [attachment] : [];
+  });
+}
+
+/**
+ * The transcript rows of one message. A user message is one row. An assistant message has one
+ * row per part, in part order: a text row, a reasoning row, or a tool row, so every streamed
+ * delta addresses exactly one row. The run's usage and error attach to its last text or reasoning
+ * row, or to a row of their own when the message has none.
+ */
+export function flexMessageToHarnessRows(
+  message: IFlexMessage,
+  messageIndex: number,
+  timings: TFlexPartTimings = new Map(),
+): plugins.IHarnessMessage[] {
+  const createdAt = epoch(message.createdAt) ?? 0;
+  const completedAt = epoch(message.completedAt);
+  const identity = {
+    ...(message.model === undefined ? {} : { model: flexModelLabel(message.model) }),
+    ...(message.model?.variant === undefined ? {} : { effort: message.model.variant }),
+  };
+  if (message.role === 'user') {
+    const attachments = attachmentsOf(message);
+    return [{
+      id: message.messageId,
+      role: 'user',
+      text: message.parts.flatMap((part) => part.type === 'text' ? [part.text] : []).join('\n\n'),
+      createdAt,
+      order: { messageIndex, partIndex: 0 },
+      ...(attachments.length === 0 ? {} : { attachments }),
+    }];
+  }
+
+  const streaming = message.status === 'streaming';
+  const rows: plugins.IHarnessMessage[] = [];
+  let terminalRow: plugins.IHarnessMessage | undefined;
+  message.parts.forEach((part, partIndex) => {
+    const timing = timings.get(flexPartTimingKey(message.messageId, part.partId));
+    const base = {
+      id: flexPartRowId(message.messageId, part.partId),
+      createdAt: timing?.startedAt ?? createdAt,
+      order: { messageIndex, partIndex },
+      ...identity,
+    };
+    switch (part.type) {
+      case 'text': {
+        const row: plugins.IHarnessMessage = {
+          ...base,
+          role: 'assistant',
+          text: part.text,
+          ...(streaming && partIndex === message.parts.length - 1 ? { streaming: true } : {}),
+        };
+        rows.push(row);
+        terminalRow = row;
+        break;
+      }
+      case 'reasoning': {
+        const startedAt = timing?.startedAt ?? createdAt;
+        const endedAt = part.status === 'running'
+          ? undefined
+          : timing?.endedAt ?? completedAt ?? startedAt;
+        const row: plugins.IHarnessMessage = {
+          ...base,
+          role: 'assistant',
+          text: '',
+          reasoning: [{
+            id: part.partId,
+            text: part.text,
+            startedAt,
+            ...(endedAt === undefined ? {} : { endedAt }),
+          }],
+        };
+        rows.push(row);
+        terminalRow = row;
+        break;
+      }
+      case 'tool':
+        rows.push({ ...base, role: 'tool', text: '', toolCall: flexToolPartToHarness(part, timing) });
+        break;
+      case 'attachment': {
+        const attachment = flexAttachmentToHarness(part);
+        if (attachment) rows.push({ ...base, role: 'assistant', text: '', attachments: [attachment] });
+        break;
+      }
+    }
+  });
+
+  const terminal = {
+    ...(message.usage === undefined ? {} : { usage: flexUsageToHarness(message.usage) }),
+    ...(message.error === undefined ? {} : { error: message.error }),
+  };
+  if (Object.keys(terminal).length > 0) {
+    if (terminalRow) {
+      Object.assign(terminalRow, terminal);
+    } else {
+      rows.push({
+        id: message.messageId,
+        role: 'assistant',
+        text: '',
+        createdAt: completedAt ?? createdAt,
+        order: { messageIndex, partIndex: message.parts.length },
+        ...identity,
+        ...terminal,
+      });
+    }
+  }
+  return rows;
+}
+
+export function flexPermissionToHarness(
+  request: IFlexPermissionRequest,
+): plugins.IHarnessPermissionRequest {
+  const metadata = request.metadata;
+  return {
+    id: request.permissionId,
+    sessionId: request.sessionId,
+    ...(epoch(request.createdAt) === undefined ? {} : { createdAt: epoch(request.createdAt) }),
+    title: request.description,
+    type: request.kind,
+    ...(metadata !== null && typeof metadata === 'object' && !Array.isArray(metadata)
+      ? { metadata: { ...metadata } }
+      : {}),
+  };
+}
+
+export function flexSessionToHarnessStatus(session: IFlexSession): plugins.IHarnessStatus {
+  switch (session.activity.status) {
+    case 'running':
+    case 'scheduled':
+    case 'waiting_permission':
+      return { type: 'busy' };
+    case 'failed':
+      return {
+        type: 'error',
+        ...(session.activity.error === undefined ? {} : { message: session.activity.error }),
+      };
+    default:
+      return { type: 'idle' };
+  }
+}
+
+const sessionCardStates: Record<IFlexSession['activity']['status'], plugins.THarnessSessionCardState> = {
+  idle: 'normal',
+  scheduled: 'working',
+  running: 'working',
+  waiting_permission: 'attention',
+  failed: 'error',
+  cancelled: 'normal',
+};
+
+/** A session-list row. `title` falls back to the session id, which is what the session is named by. */
+export function flexSessionToHarnessMeta(session: IFlexSession): plugins.IHarnessSessionMeta {
+  return {
+    id: session.sessionId,
+    title: session.title ?? session.sessionId,
+    ...(epoch(session.createdAt) === undefined ? {} : { createdAt: epoch(session.createdAt) }),
+    ...(epoch(session.updatedAt) === undefined ? {} : { updatedAt: epoch(session.updatedAt) }),
+    state: sessionCardStates[session.activity.status],
+  };
+}
+
+export function flexProjectToHarnessTodos(project: IFlexProjectStateResult): plugins.IHarnessTodoItem[] {
+  return project.state.tasks.map((task) => ({
+    id: task.id,
+    content: task.content,
+    status: task.status,
+  }));
+}
+
+export function flexProjectToHarnessScratchpad(
+  sessionId: string,
+  project: IFlexProjectStateResult,
+): plugins.IHarnessScratchpad {
+  return { id: sessionId, text: project.state.scratchpad, revision: project.revision };
+}

package/ts_chat_harness/index.ts

@@ -0,0 +1,33 @@
+export {
+  FlexHarnessTranscript,
+  type IFlexHarnessEventDelivery,
+  type IFlexHarnessTranscriptChange,
+  type IFlexHarnessTranscriptOptions,
+  type IFlexHarnessTranscriptSnapshot,
+  type IFlexHarnessTranscriptView,
+} from './classes.transcript.js';
+export {
+  flexAttachmentToHarness,
+  flexMessageToHarnessRows,
+  flexModelLabel,
+  flexPartRowId,
+  flexPermissionToHarness,
+  flexProjectToHarnessScratchpad,
+  flexProjectToHarnessTodos,
+  flexSessionToHarnessMeta,
+  flexSessionToHarnessStatus,
+  flexToolPartToHarness,
+  flexUsageToHarness,
+  type IFlexPartTiming,
+  type TFlexPartTimings,
+} from './functions.mapping.js';
+export {
+  flexHarnessAbortIntent,
+  flexHarnessPermissionIntent,
+  flexHarnessSendIntent,
+  runFlexHarnessChatIntent,
+  type IFlexHarnessChatTarget,
+  type IFlexHarnessSendIntentOptions,
+  type TFlexHarnessChatHost,
+  type TFlexHarnessChatIntent,
+} from './functions.intents.js';

package/ts_chat_harness/plugins.ts

@@ -0,0 +1,18 @@
+// @design.estate scope: the harness components' plain-data contract, types only
+export type {
+  IHarnessAttachment,
+  IHarnessComposerSendDetail,
+  IHarnessMessage,
+  IHarnessPermissionRequest,
+  IHarnessPermissionResponseDetail,
+  IHarnessQuestionRequest,
+  IHarnessScratchpad,
+  IHarnessSessionMeta,
+  IHarnessStatus,
+  IHarnessTodoItem,
+  IHarnessToolCall,
+  IHarnessUsage,
+  THarnessSessionCardState,
+  THarnessStreamDelta,
+  THarnessToolStatus,
+} from '@design.estate/dees-catalog';

package/ts_chat_harness/readme.md

@@ -0,0 +1,117 @@
+A FlexHarness session as the inputs of the `@design.estate/dees-catalog` harness components (`dees-harness-chat` and its parts), and their events as FlexHarness calls.
+
+```sh
+pnpm add @modelprofile.com/flexharness @design.estate/dees-catalog
+```
+
+The subpath imports only types from `@design.estate/dees-catalog` and no runtime code at all, so it runs in the browser beside the components as well as on the server beside the harness.
+
+```typescript
+import type { TFlexHarnessEvent } from '@modelprofile.com/flexharness';
+import {
+  FlexHarnessTranscript,
+  flexHarnessAbortIntent,
+  flexHarnessPermissionIntent,
+  flexHarnessSendIntent,
+} from '@modelprofile.com/flexharness/chat/harness';
+
+const target = { scopeId, sessionId };
+const transcript = new FlexHarnessTranscript(target);
+let precedingSequence: number | undefined;
+// Events that arrive while the session is being read wait here.
+let buffered: TFlexHarnessEvent[] | undefined;
+
+function apply(event: TFlexHarnessEvent): void {
+  const change = transcript.applyEvent(event, { precedingSequence });
+  precedingSequence = event.sequence;
+  if (change.reload) return void reloadSession();
+  const view = transcript.view();
+  if (change.messages) chat.messages = view.messages;
+  else for (const delta of change.deltas) chat.applyDelta(delta);
+  if (change.permissions) chat.permissions = view.permissions;
+  if (change.status) chat.status = view.status;
+  if (change.usage) chat.usage = view.usage;
+}
+
+async function reloadSession(): Promise<void> {
+  buffered = [];
+  const view = await harness.getSessionView(scopeId, sessionId);
+  transcript.load({
+    messages: view.messages,
+    permissions: view.pendingPermissions,
+    session: view.session,
+    sequence: view.sequence,
+  });
+  precedingSequence = undefined;
+  Object.assign(chat, transcript.view());
+  const pending = buffered;
+  buffered = undefined;
+  // Buffered events the view already includes change nothing.
+  for (const event of pending) {
+    if (buffered) break; // a reported gap started another reload
+    apply(event);
+  }
+}
+
+// Subscribe before the first read, so no event is lost.
+harness.subscribe((event) => (buffered ? buffered.push(event) : apply(event)));
+await reloadSession();
+
+chat.addEventListener('harness-send', (event) =>
+  send(flexHarnessSendIntent(target, event.detail, { activeQueueId: transcript.activeQueueId })));
+chat.addEventListener('harness-permission-response', (event) =>
+  send(flexHarnessPermissionIntent(target, event.detail)));
+chat.addEventListener('harness-abort', () => send(flexHarnessAbortIntent(target)));
+```
+
+## Transcript
+
+`FlexHarnessTranscript` follows one session. `load()` takes its authoritative state from `getSessionView()` and, with project management, `getProjectState()`. `applyEvent()` takes every harness event, ignores those of other sessions, and returns what changed.
+
+The host forwards every event of the harness instance, of every session, in order, and passes the `sequence` of the event it received before as `precedingSequence` (`undefined` for the first event after `load()`). Event sequences are global to the instance, so only this proves that no event of the session was lost: an event that does not directly follow its predecessor asks for a reload. After a gap or a reconnect, the host calls `load()` and starts again with `precedingSequence: undefined`. `getSessionView()` states the `sequence` of the last event its state includes; passed to `load()`, it lets the transcript skip the events the state already holds and prove that the first event after it follows. A snapshot from `getMessages()`, `listPendingPermissions()` and `getSession()` carries no sequence, so the first event after such a `load()` is taken unchecked. `view()` returns a copy of the component inputs: `messages`, `permissions`, `questions`, `status`, `usage`, `todos` and `scratchpad`. The transcript keeps its own objects, so the deltas the components apply to theirs never apply twice.
+
+- A user message is one row. An assistant message has one row per part, in part order: a text row, a reasoning row, or a tool row, so every streamed delta addresses exactly one row. The run's usage and error attach to its last text or reasoning row. Rows carry `order` from the message and part positions.
+- `change.deltas` stream text, reasoning, tool updates and part ends into the rows the components already hold. When `change.messages` is true, rows were added or replaced: assign `view().messages` instead.
+- `change.reload` means the transcript can no longer follow incrementally: events were lost, the history moved (`session.history.changed` after undo, redo or a branch), or a delta does not continue the text the transcript holds, which the delta's UTF-8 byte counters prove. Read the session again and call `load()`.
+- Permission rows stay in the transcript once answered, showing the decision. A request its run leaves unanswered, because the run was stopped or failed, is removed when the run finishes.
+- FlexHarness emits no event for project state. After a run, or after a project tool's row completes, read `getProjectState()` and pass it to `applyProjectState()` for the task list and the scratchpad.
+- `questions` is always empty: FlexHarness has no question requests.
+- Messages the session has not taken in yet (a queued prompt, a steer) carry no text in FlexHarness events. The host that sent them shows them as pending rows.
+- An attachment row needs a name, a media type and a size. The public projection keeps no payload and states these only when the prompt did, so an attachment without all three, such as a remote URL of unknown size, has no row.
+
+`flexMessageToHarnessRows()`, `flexPermissionToHarness()`, `flexSessionToHarnessMeta()` for `dees-harness-session-list`, and the other `flex*ToHarness` functions are the mappings the transcript uses, for hosts that keep their own state.
+
+## Intents
+
+The intent functions map component events to plain `TFlexHarnessChatIntent` values a host carries to the server that owns the harness. There, `runFlexHarnessChatIntent(harness, intent)` makes the call and returns the admission of a queued prompt, whose `completion` the caller owns, as with `enqueuePrompt()`.
+
+Intents are untrusted client input: a client can name any `scopeId` and `sessionId`. Before calling `runFlexHarnessChatIntent`, the server authenticates the caller and checks, or replaces, the intent's target with a session the caller may act on. The harness itself checks only that a permission belongs to the session the intent names, not who is asking.
+
+- `harness-send`: text and attachments become prompt parts. A text attachment is sent as a UTF-8 file part; a truncated attachment, or one without a payload, throws. A message sent while idle, queued behind the running turn, or delivered as `next-turn` becomes `enqueuePrompt`. A steer joins the running turn, `transcript.activeQueueId`, through `steerPrompt`, and answers on that turn's model; with no running turn, or when its turn ended before the harness took it, it is the next turn's input and is queued with the prompt options. A steer id comes from `crypto.randomUUID()`, which browsers offer only in secure contexts (HTTPS or localhost). The composer's `model` becomes the prompt's `modelHint`; a host that offers accounts or reasoning efforts passes its own `modelHint`.
+- `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.
+
+## Issue Reporting and Security
+
+Report issues and security concerns through [community.foss.global](https://community.foss.global).
+
+## License and Legal Information
+
+This repository contains open-source code licensed under the MIT License. A copy of the license can be found in the repository license file.
+
+**Please note:** The MIT License does not grant permission to use the trade names, trademarks, service marks, or product names of the project, except as required for reasonable and customary use in describing the origin of the work and reproducing the content of the NOTICE file.
+
+### Trademarks
+
+This project is owned and maintained by Task Venture Capital GmbH. The names and logos associated with Task Venture Capital GmbH and any related products or services are trademarks of Task Venture Capital GmbH or third parties, and are not included within the scope of the MIT license granted herein.
+
+Use of these trademarks must comply with Task Venture Capital GmbH's Trademark Guidelines or the guidelines of the respective third-party owners, and any usage must be approved in writing. Third-party trademarks used herein are the property of their respective owners and used only in a descriptive manner, e.g. for an implementation of an API or similar.
+
+### Company Information
+
+Task Venture Capital GmbH<br>
+Registered at District Court Bremen HRB 35230 HB, Germany
+
+For any legal inquiries or further information, please contact us via email at hello@task.vc.
+
+By using this repository, you acknowledge that you have read this section, agree to comply with its terms, and understand that the licensing of the code does not imply endorsement by Task Venture Capital GmbH of any derivative works.