@jmoyers/harness 0.1.11 → 0.1.20

package/packages/harness-ui/src/surface.ts

@@ -0,0 +1,252 @@
+import { measureDisplayWidth } from './text-layout.ts';
+
+export type UiColor =
+  | { kind: 'default' }
+  | { kind: 'indexed'; index: number }
+  | { kind: 'rgb'; r: number; g: number; b: number };
+
+export interface UiStyle {
+  readonly fg: UiColor;
+  readonly bg: UiColor;
+  readonly bold: boolean;
+  readonly dim?: boolean;
+  readonly italic?: boolean;
+  readonly underline?: boolean;
+  readonly inverse?: boolean;
+}
+
+export interface UiCell {
+  glyph: string;
+  continued: boolean;
+  style: UiStyle;
+}
+
+const DEFAULT_COLOR: UiColor = {
+  kind: 'default',
+};
+
+export const DEFAULT_UI_STYLE: UiStyle = {
+  fg: DEFAULT_COLOR,
+  bg: DEFAULT_COLOR,
+  bold: false,
+};
+
+function cloneColor(color: UiColor): UiColor {
+  if (color.kind === 'default') {
+    return DEFAULT_COLOR;
+  }
+  if (color.kind === 'indexed') {
+    return {
+      kind: 'indexed',
+      index: color.index,
+    };
+  }
+  return {
+    kind: 'rgb',
+    r: color.r,
+    g: color.g,
+    b: color.b,
+  };
+}
+
+function cloneStyle(style: UiStyle): UiStyle {
+  return {
+    fg: cloneColor(style.fg),
+    bg: cloneColor(style.bg),
+    bold: style.bold,
+    ...(style.dim === true ? { dim: true } : {}),
+    ...(style.italic === true ? { italic: true } : {}),
+    ...(style.underline === true ? { underline: true } : {}),
+    ...(style.inverse === true ? { inverse: true } : {}),
+  };
+}
+
+function styleFlag(value: boolean | undefined): boolean {
+  return value === true;
+}
+
+function styleEqual(left: UiStyle, right: UiStyle): boolean {
+  if (left.bold !== right.bold) {
+    return false;
+  }
+  if (styleFlag(left.dim) !== styleFlag(right.dim)) {
+    return false;
+  }
+  if (styleFlag(left.italic) !== styleFlag(right.italic)) {
+    return false;
+  }
+  if (styleFlag(left.underline) !== styleFlag(right.underline)) {
+    return false;
+  }
+  if (styleFlag(left.inverse) !== styleFlag(right.inverse)) {
+    return false;
+  }
+  if (left.fg.kind !== right.fg.kind || left.bg.kind !== right.bg.kind) {
+    return false;
+  }
+
+  if (left.fg.kind === 'indexed') {
+    if (left.fg.index !== (right.fg as Extract<UiColor, { kind: 'indexed' }>).index) {
+      return false;
+    }
+  } else if (left.fg.kind === 'rgb') {
+    const typedRight = right.fg as Extract<UiColor, { kind: 'rgb' }>;
+    if (left.fg.r !== typedRight.r || left.fg.g !== typedRight.g || left.fg.b !== typedRight.b) {
+      return false;
+    }
+  }
+
+  if (left.bg.kind === 'indexed') {
+    if (left.bg.index !== (right.bg as Extract<UiColor, { kind: 'indexed' }>).index) {
+      return false;
+    }
+  } else if (left.bg.kind === 'rgb') {
+    const typedRight = right.bg as Extract<UiColor, { kind: 'rgb' }>;
+    if (left.bg.r !== typedRight.r || left.bg.g !== typedRight.g || left.bg.b !== typedRight.b) {
+      return false;
+    }
+  }
+
+  return true;
+}
+
+function colorSgrCodes(color: UiColor, target: 'fg' | 'bg'): readonly string[] {
+  const prefix = target === 'fg' ? '38' : '48';
+  if (color.kind === 'default') {
+    return [target === 'fg' ? '39' : '49'];
+  }
+  if (color.kind === 'indexed') {
+    return [prefix, '5', String(color.index)];
+  }
+  return [prefix, '2', String(color.r), String(color.g), String(color.b)];
+}
+
+function styleToSgr(style: UiStyle): string {
+  const codes: string[] = ['0'];
+  if (style.bold) {
+    codes.push('1');
+  }
+  if (styleFlag(style.dim)) {
+    codes.push('2');
+  }
+  if (styleFlag(style.italic)) {
+    codes.push('3');
+  }
+  if (styleFlag(style.underline)) {
+    codes.push('4');
+  }
+  if (styleFlag(style.inverse)) {
+    codes.push('7');
+  }
+  codes.push(...colorSgrCodes(style.fg, 'fg'));
+  codes.push(...colorSgrCodes(style.bg, 'bg'));
+  return `\u001b[${codes.join(';')}m`;
+}
+
+export class SurfaceBuffer {
+  public readonly cols: number;
+  public readonly rows: number;
+  public readonly baseStyle: UiStyle;
+  public readonly cells: UiCell[];
+
+  constructor(cols: number, rows: number, baseStyle: UiStyle = DEFAULT_UI_STYLE) {
+    this.cols = Math.max(1, cols);
+    this.rows = Math.max(1, rows);
+    this.baseStyle = cloneStyle(baseStyle);
+    this.cells = Array.from({ length: this.cols * this.rows }, () => ({
+      glyph: ' ',
+      continued: false,
+      style: cloneStyle(this.baseStyle),
+    }));
+  }
+
+  private cellOffset(col: number, row: number): number {
+    return row * this.cols + col;
+  }
+
+  public fillRow(row: number, style: UiStyle): void {
+    if (row < 0 || row >= this.rows) {
+      return;
+    }
+    const typedStyle = cloneStyle(style);
+    for (let col = 0; col < this.cols; col += 1) {
+      const cell = this.cells[this.cellOffset(col, row)]!;
+      cell.glyph = ' ';
+      cell.continued = false;
+      cell.style = typedStyle;
+    }
+  }
+
+  public drawText(
+    colStart: number,
+    row: number,
+    text: string,
+    style: UiStyle = this.baseStyle,
+  ): void {
+    if (row < 0 || row >= this.rows || colStart >= this.cols) {
+      return;
+    }
+
+    let col = Math.max(0, colStart);
+    let lastGlyphCol: number | null = null;
+    const typedStyle = cloneStyle(style);
+    for (const glyph of text) {
+      const width = Math.max(0, measureDisplayWidth(glyph));
+      if (width === 0) {
+        if (lastGlyphCol !== null) {
+          const cell = this.cells[this.cellOffset(lastGlyphCol, row)]!;
+          cell.glyph += glyph;
+        }
+        continue;
+      }
+      if (col >= this.cols) {
+        break;
+      }
+
+      if (width === 1) {
+        const cell = this.cells[this.cellOffset(col, row)]!;
+        cell.glyph = glyph;
+        cell.continued = false;
+        cell.style = typedStyle;
+        lastGlyphCol = col;
+        col += 1;
+        continue;
+      }
+
+      if (col + width > this.cols) {
+        break;
+      }
+      const first = this.cells[this.cellOffset(col, row)]!;
+      first.glyph = glyph;
+      first.continued = false;
+      first.style = typedStyle;
+      for (let offset = 1; offset < width && col + offset < this.cols; offset += 1) {
+        const cell = this.cells[this.cellOffset(col + offset, row)]!;
+        cell.glyph = '';
+        cell.continued = true;
+        cell.style = typedStyle;
+      }
+      lastGlyphCol = col;
+      col += width;
+    }
+  }
+
+  public renderAnsiRows(): readonly string[] {
+    const rows: string[] = [];
+    for (let row = 0; row < this.rows; row += 1) {
+      let output = '';
+      let lastStyle: UiStyle | null = null;
+      for (let col = 0; col < this.cols; col += 1) {
+        const cell = this.cells[this.cellOffset(col, row)]!;
+        if (lastStyle === null || !styleEqual(lastStyle, cell.style)) {
+          output += styleToSgr(cell.style);
+          lastStyle = cell.style;
+        }
+        output += cell.continued ? '' : cell.glyph.length > 0 ? cell.glyph : ' ';
+      }
+      output += '\u001b[0m';
+      rows.push(output);
+    }
+    return rows;
+  }
+}

package/packages/harness-ui/src/text-layout.ts

@@ -0,0 +1,210 @@
+function isCombiningMark(codePoint: number): boolean {
+  if (codePoint < 0x0300) return false;
+  if (codePoint <= 0x036f) return true; // Combining Diacritical Marks
+  if (codePoint < 0x0483) return false;
+  if (codePoint <= 0x0489) return true; // Cyrillic combining marks
+  if (codePoint < 0x0591) return false;
+  if (codePoint <= 0x05bd) return true; // Hebrew combining marks
+  if (codePoint === 0x05bf) return true;
+  if (codePoint === 0x05c1 || codePoint === 0x05c2) return true;
+  if (codePoint === 0x05c4 || codePoint === 0x05c5) return true;
+  if (codePoint === 0x05c7) return true;
+  if (codePoint < 0x0610) return false;
+  if (codePoint <= 0x061a) return true; // Arabic combining marks
+  if (codePoint < 0x064b) return false;
+  if (codePoint <= 0x065f) return true; // Arabic combining marks (extended)
+  if (codePoint === 0x0670) return true;
+  if (codePoint < 0x06d6) return false;
+  if (codePoint <= 0x06dc) return true;
+  if (codePoint < 0x06df) return false;
+  if (codePoint <= 0x06e4) return true;
+  if (codePoint === 0x06e7 || codePoint === 0x06e8) return true;
+  if (codePoint === 0x06ea || codePoint === 0x06eb || codePoint === 0x06ec || codePoint === 0x06ed)
+    return true;
+  if (codePoint < 0x0730) return false;
+  if (codePoint <= 0x074a) return true; // Syriac combining marks
+  if (codePoint < 0x0900) return false;
+  if (codePoint <= 0x0903) return true; // Devanagari
+  if (codePoint < 0x093a) return false;
+  if (codePoint <= 0x094f) return true;
+  if (codePoint < 0x0951) return false;
+  if (codePoint <= 0x0957) return true;
+  if (codePoint < 0x0e31) return false;
+  if (codePoint === 0x0e31) return true; // Thai
+  if (codePoint >= 0x0e34 && codePoint <= 0x0e3a) return true;
+  if (codePoint >= 0x0e47 && codePoint <= 0x0e4e) return true;
+  if (codePoint < 0x1ab0) return false;
+  if (codePoint <= 0x1aff) return true; // Combining Diacritical Marks Extended
+  if (codePoint < 0x1dc0) return false;
+  if (codePoint <= 0x1dff) return true; // Combining Diacritical Marks Supplement
+  if (codePoint < 0x20d0) return false;
+  if (codePoint <= 0x20ff) return true; // Combining Diacritical Marks for Symbols
+  if (codePoint < 0xfe00) return false;
+  if (codePoint <= 0xfe0f) return true; // Variation Selectors
+  if (codePoint < 0xfe20) return false;
+  if (codePoint <= 0xfe2f) return true; // Combining Half Marks
+  if (codePoint < 0xe0100) return false;
+  if (codePoint <= 0xe01ef) return true; // Variation Selectors Supplement
+  return false;
+}
+
+const WIDE_RANGES: ReadonlyArray<readonly [number, number]> = [
+  [0x1100, 0x115f],
+  [0x2329, 0x232a],
+  [0x2e80, 0xa4cf],
+  [0xac00, 0xd7a3],
+  [0xf900, 0xfaff],
+  [0xfe10, 0xfe19],
+  [0xfe30, 0xfe6f],
+  [0xff00, 0xff60],
+  [0xffe0, 0xffe6],
+  [0x1f300, 0x1faff],
+];
+
+function isWideCodePoint(codePoint: number): boolean {
+  for (const [start, end] of WIDE_RANGES) {
+    if (codePoint >= start && codePoint <= end) {
+      return true;
+    }
+  }
+  return false;
+}
+
+export function measureDisplayWidth(text: string): number {
+  let width = 0;
+  for (const char of text) {
+    const codePoint = char.codePointAt(0)!;
+    if (codePoint < 0x20 || (codePoint >= 0x7f && codePoint < 0xa0)) {
+      continue;
+    }
+    if (isCombiningMark(codePoint)) {
+      continue;
+    }
+    width += isWideCodePoint(codePoint) ? 2 : 1;
+  }
+  return width;
+}
+
+export function wrapTextForColumns(text: string, cols: number): string[] {
+  if (cols <= 0) {
+    return [''];
+  }
+
+  const lines: string[] = [];
+  let current = '';
+  let currentWidth = 0;
+  for (const char of text) {
+    if (char === '\n') {
+      lines.push(current);
+      current = '';
+      currentWidth = 0;
+      continue;
+    }
+    const charWidth = Math.max(1, measureDisplayWidth(char));
+    if (currentWidth + charWidth > cols) {
+      lines.push(current);
+      current = '';
+      currentWidth = 0;
+    }
+    current += char;
+    currentWidth += charWidth;
+  }
+  lines.push(current);
+  return lines;
+}
+
+export interface WrappingInputBuffer {
+  readonly text: string;
+  readonly cursor: number;
+}
+
+export interface RenderWrappingInputLinesOptions {
+  readonly buffer: WrappingInputBuffer;
+  readonly width: number;
+  readonly cursorVisible?: boolean;
+  readonly cursorToken?: string;
+  readonly linePrefix?: string;
+}
+
+function normalizedCursor(buffer: WrappingInputBuffer): number {
+  if (!Number.isFinite(buffer.cursor)) {
+    return buffer.text.length;
+  }
+  return Math.max(0, Math.min(buffer.text.length, Math.floor(buffer.cursor)));
+}
+
+function consumedGlyphsText(consumed: ReadonlyArray<{ glyph: string; width: number }>): string {
+  let output = '';
+  for (const entry of consumed) {
+    output += entry.glyph;
+  }
+  return output;
+}
+
+export class TextLayoutEngine {
+  public constructor() {}
+
+  public measure(text: string): number {
+    return measureDisplayWidth(text);
+  }
+
+  public wrap(text: string, cols: number): readonly string[] {
+    return wrapTextForColumns(text, cols);
+  }
+
+  public truncate(text: string, width: number): string {
+    const safeWidth = Math.max(0, Math.floor(width));
+    if (safeWidth === 0 || text.length === 0) {
+      return '';
+    }
+
+    const consumed: Array<{ glyph: string; width: number }> = [];
+    let consumedWidth = 0;
+    let truncated = false;
+    for (const glyph of text) {
+      const glyphWidth = Math.max(1, this.measure(glyph));
+      if (consumedWidth + glyphWidth > safeWidth) {
+        truncated = true;
+        break;
+      }
+      consumed.push({ glyph, width: glyphWidth });
+      consumedWidth += glyphWidth;
+    }
+
+    if (!truncated) {
+      return consumedGlyphsText(consumed);
+    }
+    if (safeWidth === 1) {
+      return '…';
+    }
+    while (consumed.length > 0 && consumedWidth + 1 > safeWidth) {
+      const removed = consumed.pop()!;
+      consumedWidth -= removed.width;
+    }
+    return `${consumedGlyphsText(consumed)}…`;
+  }
+}
+
+export class WrappingInputRenderer {
+  constructor(private readonly layout: TextLayoutEngine = new TextLayoutEngine()) {}
+
+  public renderLines(options: RenderWrappingInputLinesOptions): readonly string[] {
+    const cursor = normalizedCursor(options.buffer);
+    const cursorToken = options.cursorToken ?? '█';
+    const linePrefix = options.linePrefix ?? '';
+    const cursorVisible = options.cursorVisible ?? true;
+    const textWithCursor = !cursorVisible
+      ? options.buffer.text
+      : cursor >= options.buffer.text.length
+        ? `${options.buffer.text}${cursorToken}`
+        : options.buffer.text.slice(0, cursor) +
+          cursorToken +
+          options.buffer.text.slice(cursor + 1);
+    const logicalLines = textWithCursor.split('\n');
+    const wrapped: string[] = [];
+    for (const line of logicalLines) {
+      wrapped.push(...this.layout.wrap(`${linePrefix}${line}`, options.width));
+    }
+    return wrapped.length === 0 ? [''] : wrapped;
+  }
+}

package/packages/nim-core/src/contracts.ts

@@ -0,0 +1,239 @@
+import type { NimEventEnvelope } from './events.ts';
+
+export type NimProviderId = string;
+export type NimModelRef = `${string}/${string}`;
+
+export type NimToolPolicy = {
+  readonly hash: string;
+  readonly allow: readonly string[];
+  readonly deny: readonly string[];
+};
+
+export type NimProvider = {
+  readonly id: NimProviderId;
+  readonly displayName: string;
+  readonly models: readonly NimModelRef[];
+};
+
+export type NimToolDefinition = {
+  readonly name: string;
+  readonly description: string;
+};
+
+export type SessionHandle = {
+  readonly sessionId: string;
+  readonly tenantId: string;
+  readonly userId: string;
+  readonly model: NimModelRef;
+  readonly lane: string;
+  readonly soulHash?: string;
+  readonly skillsSnapshotVersion?: number;
+};
+
+export type TurnResult = {
+  readonly runId: string;
+  readonly terminalState: 'completed' | 'failed' | 'aborted';
+};
+
+export type TurnHandle = {
+  readonly runId: string;
+  readonly sessionId: string;
+  readonly idempotencyKey: string;
+  readonly done: Promise<TurnResult>;
+};
+
+export type StartSessionInput = {
+  readonly tenantId: string;
+  readonly userId: string;
+  readonly model: NimModelRef;
+  readonly lane?: string;
+};
+
+export type ResumeSessionInput = {
+  readonly tenantId: string;
+  readonly userId: string;
+  readonly sessionId: string;
+};
+
+export type ListSessionsInput = {
+  readonly tenantId: string;
+  readonly userId: string;
+};
+
+export type ListSessionsResult = {
+  readonly sessions: readonly SessionHandle[];
+};
+
+export type SwitchModelInput = {
+  readonly sessionId: string;
+  readonly model: NimModelRef;
+  readonly reason: 'manual' | 'policy' | 'fallback';
+};
+
+export type SendTurnInput = {
+  readonly sessionId: string;
+  readonly input: string;
+  readonly idempotencyKey: string;
+  readonly lane?: string;
+  readonly abortSignal?: AbortSignal;
+};
+
+export type AbortTurnInput = {
+  readonly runId: string;
+  readonly reason?: 'manual' | 'timeout' | 'policy';
+};
+
+export type CompactSessionInput = {
+  readonly sessionId: string;
+  readonly trigger: 'manual' | 'overflow' | 'policy';
+  readonly includeMemoryFlush?: boolean;
+};
+
+export type CompactionResult = {
+  readonly compacted: boolean;
+  readonly summaryEventId?: string;
+  readonly reason?: string;
+};
+
+export type SteerTurnInput = {
+  readonly sessionId: string;
+  readonly runId?: string;
+  readonly text: string;
+};
+
+export type SteerTurnResult = {
+  readonly accepted: boolean;
+  readonly reason?: 'no-active-run' | 'not-streaming' | 'compacting' | 'rate-limited';
+};
+
+export type QueueTurnInput = {
+  readonly sessionId: string;
+  readonly text: string;
+  readonly priority?: 'normal' | 'high';
+  readonly dedupeKey?: string;
+};
+
+export type QueueTurnResult = {
+  readonly queued: boolean;
+  readonly queueId?: string;
+  readonly position?: number;
+  readonly reason?: 'duplicate' | 'queue-full' | 'invalid-state';
+};
+
+export type StreamEventsInput = {
+  readonly tenantId: string;
+  readonly sessionId?: string;
+  readonly runId?: string;
+  readonly fromEventIdExclusive?: string;
+  readonly fidelity?: 'raw' | 'semantic';
+  readonly includeThoughtDeltas?: boolean;
+  readonly includeToolArgumentDeltas?: boolean;
+};
+
+export type StreamUiInput = {
+  readonly tenantId: string;
+  readonly sessionId?: string;
+  readonly runId?: string;
+  readonly mode: 'debug' | 'seamless';
+};
+
+export type ReplayEventsInput = {
+  readonly tenantId: string;
+  readonly sessionId?: string;
+  readonly runId?: string;
+  readonly fromEventIdExclusive?: string;
+  readonly toEventIdInclusive?: string;
+  readonly fidelity?: 'raw' | 'semantic';
+  readonly includeThoughtDeltas?: boolean;
+  readonly includeToolArgumentDeltas?: boolean;
+};
+
+export type ReplayEventsResult = {
+  readonly events: readonly NimEventEnvelope[];
+};
+
+export type NimTelemetrySink = {
+  readonly name: string;
+  record(event: NimEventEnvelope): void;
+};
+
+export type SoulSource = {
+  readonly name: string;
+};
+
+export type SkillSource = {
+  readonly name: string;
+};
+
+export type MemoryStore = {
+  readonly name: string;
+};
+
+export type SoulSnapshot = {
+  readonly hash: string;
+};
+
+export type SkillsSnapshot = {
+  readonly hash: string;
+  readonly version: number;
+};
+
+export type MemorySnapshot = {
+  readonly hash: string;
+};
+
+export type NimUiEvent =
+  | {
+      readonly type: 'assistant.state';
+      readonly state: 'thinking' | 'tool-calling' | 'responding' | 'idle';
+    }
+  | {
+      readonly type: 'assistant.text.delta';
+      readonly text: string;
+    }
+  | {
+      readonly type: 'assistant.text.message';
+      readonly text: string;
+    }
+  | {
+      readonly type: 'tool.activity';
+      readonly toolCallId: string;
+      readonly toolName: string;
+      readonly phase: 'start' | 'end' | 'error';
+    }
+  | {
+      readonly type: 'system.notice';
+      readonly text: string;
+    };
+
+export interface NimRuntime {
+  startSession(input: StartSessionInput): Promise<SessionHandle>;
+  resumeSession(input: ResumeSessionInput): Promise<SessionHandle>;
+  listSessions(input: ListSessionsInput): Promise<ListSessionsResult>;
+
+  registerTools(tools: readonly NimToolDefinition[]): void;
+  setToolPolicy(policy: NimToolPolicy): void;
+
+  registerProvider(provider: NimProvider): void;
+  switchModel(input: SwitchModelInput): Promise<void>;
+  registerTelemetrySink(sink: NimTelemetrySink): void;
+
+  registerSoulSource(source: SoulSource): void;
+  registerSkillSource(source: SkillSource): void;
+  registerMemoryStore(store: MemoryStore): void;
+
+  loadSoul(): Promise<SoulSnapshot>;
+  loadSkills(): Promise<SkillsSnapshot>;
+  loadMemory(): Promise<MemorySnapshot>;
+
+  sendTurn(input: SendTurnInput): Promise<TurnHandle>;
+  abortTurn(input: AbortTurnInput): Promise<void>;
+  steerTurn(input: SteerTurnInput): Promise<SteerTurnResult>;
+  queueTurn(input: QueueTurnInput): Promise<QueueTurnResult>;
+
+  compactSession(input: CompactSessionInput): Promise<CompactionResult>;
+
+  streamEvents(input: StreamEventsInput): AsyncIterable<NimEventEnvelope>;
+  streamUi(input: StreamUiInput): AsyncIterable<NimUiEvent>;
+  replayEvents(input: ReplayEventsInput): Promise<ReplayEventsResult>;
+}