@modelprofile.com/flexharness 10.11.0 → 10.13.0

package/ts/utils.schemadeclarations.ts

@@ -0,0 +1,322 @@
+/**
+ * Renders JSON Schema as TypeScript declarations for the tool catalog. The output depends only on
+ * the schema, so the same schema always renders to the same bytes.
+ */
+
+export type TJsonSchemaNode = boolean | { [key: string]: unknown };
+
+export interface ISchemaDeclarationContext {
+  /** The named type a `$ref` denotes, or undefined to inline the referenced schema. */
+  namedType(ref: string): string | undefined;
+  /** The schema a local `$ref` points to. */
+  resolve(ref: string): TJsonSchemaNode | undefined;
+}
+
+export interface IRenderedDeclaration {
+  text: string;
+  /** Named types the text refers to, sorted. */
+  types: string[];
+}
+
+const identifierPattern = /^[A-Za-z_$][A-Za-z0-9_$]*$/;
+const maxRenderDepth = 32;
+const maxInlineObjectCharacters = 100;
+const maxSafeInteger = Number.MAX_SAFE_INTEGER;
+
+export const isSchemaRecord = (value: unknown): value is { [key: string]: unknown } =>
+  typeof value === 'object' && value !== null && !Array.isArray(value);
+
+export const isIdentifier = (value: string): boolean => identifierPattern.test(value);
+
+const literal = (value: unknown): string => {
+  if (typeof value === 'string') return JSON.stringify(value);
+  if (typeof value === 'number' && Number.isFinite(value)) return String(value);
+  if (typeof value === 'boolean' || value === null) return String(value);
+  return 'unknown';
+};
+
+/**
+ * Reports whether `character` occurs outside brackets, braces, parentheses, string literals and
+ * comments.
+ */
+const hasTopLevel = (text: string, character: string): boolean => {
+  let depth = 0;
+  let quote: string | undefined;
+  for (let index = 0; index < text.length; index++) {
+    const current = text[index];
+    if (quote) {
+      if (current === '\\') index++;
+      else if (current === quote) quote = undefined;
+      continue;
+    }
+    if (current === '/' && text[index + 1] === '*') {
+      const end = text.indexOf('*/', index + 2);
+      if (end === -1) return false;
+      index = end + 1;
+      continue;
+    }
+    if (current === '"' || current === "'") quote = current;
+    else if (current === '{' || current === '[' || current === '(' || current === '<') depth++;
+    else if (current === '}' || current === ']' || current === ')' || current === '>') depth--;
+    else if (depth === 0 && current === character) return true;
+  }
+  return false;
+};
+
+const union = (parts: string[]): string => {
+  const unique = [...new Set(parts)];
+  if (unique.includes('unknown')) return 'unknown';
+  const withoutNever = unique.length > 1 ? unique.filter((part) => part !== 'never') : unique;
+  return withoutNever.join(' | ');
+};
+
+const intersection = (parts: string[]): string => {
+  const unique = [...new Set(parts)].filter((part) => part !== 'unknown');
+  if (unique.length === 0) return 'unknown';
+  return unique.map((part) => hasTopLevel(part, '|') ? `(${part})` : part).join(' & ');
+};
+
+const arrayOf = (element: string): string =>
+  hasTopLevel(element, '|') || hasTopLevel(element, '&') ? `(${element})[]` : `${element}[]`;
+
+const propertyKey = (name: string): string => isIdentifier(name) ? name : JSON.stringify(name);
+
+/** A JSDoc block at `indent`; a short single line stays on one line. */
+export const docBlock = (text: string, indent: string): string => {
+  const lines = text.replace(/\*\//g, '*\\/').split('\n').map((line) => line.trimEnd());
+  if (lines.length === 1 && indent.length + lines[0].length <= 100) return `${indent}/** ${lines[0]} */\n`;
+  return `${indent}/**\n${lines.map((line) => line ? `${indent} * ${line}` : `${indent} *`).join('\n')}\n${indent} */\n`;
+};
+
+export const countOf = (count: number, unit: string): string => `${count} ${unit}${count === 1 ? '' : 's'}`;
+
+/** Constraints a TypeScript type cannot state, in a short readable form. */
+const constraintsOf = (schema: { [key: string]: unknown }): string[] => {
+  const constraints: string[] = [];
+  const types = Array.isArray(schema.type) ? schema.type : [schema.type];
+  if (types.includes('integer')) constraints.push('integer');
+  if (typeof schema.format === 'string') constraints.push(`format ${schema.format}`);
+  const bound = (value: unknown): value is number =>
+    typeof value === 'number' && Number.isFinite(value) && Math.abs(value) !== maxSafeInteger;
+  if (bound(schema.exclusiveMinimum)) constraints.push(`> ${schema.exclusiveMinimum}`);
+  else if (bound(schema.minimum)) constraints.push(`${schema.exclusiveMinimum === true ? '>' : '>='} ${schema.minimum}`);
+  if (bound(schema.exclusiveMaximum)) constraints.push(`< ${schema.exclusiveMaximum}`);
+  else if (bound(schema.maximum)) constraints.push(`${schema.exclusiveMaximum === true ? '<' : '<='} ${schema.maximum}`);
+  if (bound(schema.multipleOf)) constraints.push(`multiple of ${schema.multipleOf}`);
+  const range = (min: unknown, max: unknown, unit: string): void => {
+    const hasMin = bound(min) && min > 0;
+    const hasMax = bound(max);
+    if (hasMin && hasMax) constraints.push(min === max ? countOf(min, unit) : `${min}-${countOf(max, unit)}`);
+    else if (hasMin) constraints.push(`at least ${countOf(min, unit)}`);
+    else if (hasMax) constraints.push(`at most ${countOf(max, unit)}`);
+  };
+  range(schema.minLength, schema.maxLength, 'character');
+  range(schema.minItems, schema.maxItems, 'item');
+  if (schema.uniqueItems === true) constraints.push('unique items');
+  if (typeof schema.pattern === 'string') constraints.push(`pattern /${schema.pattern}/`);
+  if (schema.default !== undefined) {
+    const value = JSON.stringify(schema.default);
+    if (value !== undefined && value.length <= 60) constraints.push(`default ${value}`);
+  }
+  if (schema.deprecated === true) constraints.push('deprecated');
+  return constraints;
+};
+
+/** The documentation of a property: its description and the constraints its type cannot state. */
+export const schemaDoc = (schema: TJsonSchemaNode, description?: string): string | undefined => {
+  if (!isSchemaRecord(schema)) return description?.trim() || undefined;
+  const text = (description ?? (typeof schema.description === 'string' ? schema.description : '')).trim();
+  const constraints = constraintsOf(schema);
+  if (constraints.length === 0) return text || undefined;
+  return text ? `${text} (${constraints.join(', ')})` : constraints.join(', ');
+};
+
+export class SchemaDeclarationWriter {
+  private readonly used = new Set<string>();
+  private readonly inlining = new Set<string>();
+
+  constructor(private readonly context: ISchemaDeclarationContext) {}
+
+  public get usedTypes(): string[] {
+    return [...this.used].sort();
+  }
+
+  /** The TypeScript type of `schema`, with continuation lines indented relative to `indent`. */
+  public type(schema: TJsonSchemaNode, indent = '', depth = 0, omitMemberDocs = false): string {
+    if (depth > maxRenderDepth) return 'unknown';
+    if (schema === true) return 'unknown';
+    if (schema === false) return 'never';
+    if (!isSchemaRecord(schema)) return 'unknown';
+    const base = this.baseType(schema, indent, depth, omitMemberDocs);
+    return schema.nullable === true ? union([base, 'null']) : base;
+  }
+
+  /** The members of an object schema; undefined when the schema is not a plain object type. */
+  public objectMembers(
+    schema: TJsonSchemaNode,
+  ): Array<{ name: string; doc?: string }> | undefined {
+    if (!isSchemaRecord(schema) || !this.isPlainObject(schema)) return undefined;
+    const properties = isSchemaRecord(schema.properties) ? schema.properties : {};
+    return Object.entries(properties).map(([name, property]) => {
+      const doc = schemaDoc(property as TJsonSchemaNode);
+      return { name, ...(doc === undefined ? {} : { doc }) };
+    });
+  }
+
+  /** Whether an object schema requires none of its properties. */
+  public hasNoRequiredProperties(schema: TJsonSchemaNode): boolean {
+    return isSchemaRecord(schema)
+      && this.isPlainObject(schema)
+      && !(Array.isArray(schema.required) && schema.required.length > 0);
+  }
+
+  /** `interface Name { … }` for a plain object schema, otherwise `type Name = …;`. */
+  public namedDeclaration(name: string, schema: TJsonSchemaNode, description?: string): string {
+    const doc = isSchemaRecord(schema)
+      ? (description ?? (typeof schema.description === 'string' ? schema.description : undefined))?.trim()
+      : description?.trim();
+    const prefix = doc ? docBlock(doc, '') : '';
+    if (isSchemaRecord(schema) && this.isPlainObject(schema) && schema.nullable !== true) {
+      return `${prefix}interface ${name} ${this.objectType(schema, '', 0, false)}`;
+    }
+    return `${prefix}type ${name} = ${this.type(schema, '', 0)};`;
+  }
+
+  private isPlainObject(schema: { [key: string]: unknown }): boolean {
+    if (schema.$ref !== undefined || 'const' in schema || schema.enum !== undefined) return false;
+    if (schema.anyOf !== undefined || schema.oneOf !== undefined || schema.allOf !== undefined) return false;
+    if (schema.type === 'object') return true;
+    return schema.type === undefined && isSchemaRecord(schema.properties);
+  }
+
+  private baseType(
+    schema: { [key: string]: unknown },
+    indent: string,
+    depth: number,
+    omitMemberDocs: boolean,
+  ): string {
+    if (typeof schema.$ref === 'string') return this.reference(schema.$ref, indent, depth);
+    if ('const' in schema) return literal(schema.const);
+    if (Array.isArray(schema.enum)) return schema.enum.length ? union(schema.enum.map(literal)) : 'never';
+    const alternatives = Array.isArray(schema.anyOf) ? schema.anyOf : Array.isArray(schema.oneOf) ? schema.oneOf : undefined;
+    if (alternatives?.length) {
+      return union(alternatives.map((alternative) => this.type(alternative as TJsonSchemaNode, indent, depth + 1)));
+    }
+    if (Array.isArray(schema.allOf) && schema.allOf.length) {
+      const own = { ...schema };
+      delete own.allOf;
+      const hasOwnShape = own.type !== undefined || own.properties !== undefined;
+      return intersection([
+        ...schema.allOf.map((part) => this.type(part as TJsonSchemaNode, indent, depth + 1)),
+        ...(hasOwnShape ? [this.type(own, indent, depth + 1)] : []),
+      ]);
+    }
+    const types = Array.isArray(schema.type)
+      ? schema.type.filter((type): type is string => typeof type === 'string')
+      : typeof schema.type === 'string'
+        ? [schema.type]
+        : this.inferredTypes(schema);
+    if (types.length === 0) return 'unknown';
+    return union(types.map((type) => {
+      switch (type) {
+        case 'string': return 'string';
+        case 'number':
+        case 'integer': return 'number';
+        case 'boolean': return 'boolean';
+        case 'null': return 'null';
+        case 'array': return this.arrayType(schema, indent, depth);
+        case 'object': return this.objectType(schema, indent, depth, omitMemberDocs);
+        default: return 'unknown';
+      }
+    }));
+  }
+
+  private inferredTypes(schema: { [key: string]: unknown }): string[] {
+    if (
+      schema.properties !== undefined
+      || schema.additionalProperties !== undefined
+      || schema.patternProperties !== undefined
+      || schema.required !== undefined
+    ) return ['object'];
+    if (schema.items !== undefined || schema.prefixItems !== undefined) return ['array'];
+    return [];
+  }
+
+  private reference(ref: string, indent: string, depth: number): string {
+    const name = this.context.namedType(ref);
+    if (name) {
+      this.used.add(name);
+      return name;
+    }
+    const target = this.context.resolve(ref);
+    if (target === undefined || this.inlining.has(ref)) return 'unknown';
+    this.inlining.add(ref);
+    try {
+      return this.type(target, indent, depth + 1);
+    } finally {
+      this.inlining.delete(ref);
+    }
+  }
+
+  private arrayType(schema: { [key: string]: unknown }, indent: string, depth: number): string {
+    const tuple = Array.isArray(schema.prefixItems)
+      ? schema.prefixItems
+      : Array.isArray(schema.items) ? schema.items : undefined;
+    if (tuple) {
+      const rest = Array.isArray(schema.prefixItems) ? schema.items : schema.additionalItems;
+      const members = tuple.map((item) => this.type(item as TJsonSchemaNode, indent, depth + 1));
+      if (rest !== undefined && rest !== false) {
+        members.push(`...${arrayOf(this.type(rest as TJsonSchemaNode, indent, depth + 1))}`);
+      }
+      return `[${members.join(', ')}]`;
+    }
+    if (schema.items === undefined) return 'unknown[]';
+    return arrayOf(this.type(schema.items as TJsonSchemaNode, indent, depth + 1));
+  }
+
+  private objectType(
+    schema: { [key: string]: unknown },
+    indent: string,
+    depth: number,
+    omitMemberDocs: boolean,
+  ): string {
+    const memberIndent = `${indent}  `;
+    const properties = isSchemaRecord(schema.properties) ? schema.properties : {};
+    const required = new Set(Array.isArray(schema.required)
+      ? schema.required.filter((name): name is string => typeof name === 'string')
+      : []);
+    const members: Array<{ doc?: string; text: string }> = [];
+    for (const [name, property] of Object.entries(properties)) {
+      const type = this.type(property as TJsonSchemaNode, memberIndent, depth + 1);
+      const doc = omitMemberDocs ? undefined : schemaDoc(property as TJsonSchemaNode);
+      members.push({
+        ...(doc === undefined ? {} : { doc }),
+        text: `${propertyKey(name)}${required.has(name) ? '' : '?'}: ${type}`,
+      });
+    }
+    const indexTypes: string[] = [];
+    if (isSchemaRecord(schema.patternProperties)) {
+      for (const property of Object.values(schema.patternProperties)) {
+        indexTypes.push(this.type(property as TJsonSchemaNode, memberIndent, depth + 1));
+      }
+    }
+    if (isSchemaRecord(schema.additionalProperties)) {
+      indexTypes.push(this.type(schema.additionalProperties, memberIndent, depth + 1));
+    } else if (schema.additionalProperties === true && members.length > 0) {
+      indexTypes.push('unknown');
+    }
+    if (indexTypes.length) members.push({ text: `[key: string]: ${union(indexTypes)}` });
+    if (members.length === 0) return schema.additionalProperties === false ? '{}' : 'Record<string, unknown>';
+    if (members.every((member) => member.doc === undefined && !member.text.includes('\n'))) {
+      const inline = `{ ${members.map((member) => member.text).join('; ')} }`;
+      if (inline.length <= maxInlineObjectCharacters) return inline;
+    }
+    const lines = members.map((member) =>
+      `${member.doc === undefined ? '' : docBlock(member.doc, memberIndent)}${memberIndent}${member.text};`);
+    return `{\n${lines.join('\n')}\n${indent}}`;
+  }
+}
+
+/** Indents every non-empty line of `text`. */
+export const indentLines = (text: string, indent: string): string =>
+  text.split('\n').map((line) => line ? `${indent}${line}` : line).join('\n');

package/ts/utils.sessionmetrics.ts

@@ -0,0 +1,104 @@
+import type {
+  IFlexSessionMetrics,
+  IFlexSessionMetricsState,
+  TFlexModelCallUsage,
+} from './interfaces.js';
+
+/** Fixed-size accumulator. One owner per generation / actual compactor invocation. */
+export interface ISessionMetricsOperation {
+  id: string;
+  source: 'generation' | 'compaction';
+  reportedTokens: number;
+  reportedTokensExact: boolean;
+  complete: boolean;
+  sawCall: boolean;
+  lastObservedInputTokens?: number;
+  lastObservedInputTokensAt?: string;
+}
+
+export const createSessionMetricsState = (complete: boolean): IFlexSessionMetricsState => ({
+  reportedLifetimeUsedTokens: 0,
+  reportedLifetimeUsedTokensExact: true,
+  lifetimeUsageComplete: complete,
+});
+
+export const createSessionMetricsOperation = (
+  id: string,
+  source: ISessionMetricsOperation['source'],
+): ISessionMetricsOperation => ({
+  id, source, reportedTokens: 0, reportedTokensExact: true, complete: true, sawCall: false,
+});
+
+const isTokenCount = (value: unknown): value is number =>
+  typeof value === 'number' && Number.isSafeInteger(value) && value >= 0;
+
+/** Saturation is a safe lower bound, never a rounded purported exact total. */
+const addTokens = (left: number, right: number): { tokens: number; exact: boolean } =>
+  right > Number.MAX_SAFE_INTEGER - left
+    ? { tokens: Number.MAX_SAFE_INTEGER, exact: false }
+    : { tokens: left + right, exact: true };
+
+export function observeSessionMetricsCall(
+  operation: ISessionMetricsOperation,
+  call: TFlexModelCallUsage,
+): void {
+  operation.sawCall = true;
+  if (call.status === 'unreported') {
+    operation.complete = false;
+    return;
+  }
+  const { usage } = call;
+  if (call.usageComplete === false) operation.complete = false;
+  if (!Object.values(usage).every(isTokenCount)
+    || !isTokenCount(usage.totalTokens)
+    || usage.inputTokens > Number.MAX_SAFE_INTEGER - usage.outputTokens
+    || usage.totalTokens !== usage.inputTokens + usage.outputTokens) {
+    operation.complete = false;
+    operation.reportedTokensExact = false;
+    return;
+  }
+  const sum = addTokens(operation.reportedTokens, usage.totalTokens);
+  operation.reportedTokens = sum.tokens;
+  operation.reportedTokensExact &&= sum.exact;
+  if (operation.source === 'generation' && call.usageComplete !== false) {
+    operation.lastObservedInputTokens = usage.inputTokens;
+    operation.lastObservedInputTokensAt = new Date().toISOString();
+  }
+}
+
+export function settleSessionMetricsOperation(
+  metrics: IFlexSessionMetricsState,
+  operation: ISessionMetricsOperation,
+): void {
+  const key = operation.source === 'generation' ? 'pendingGenerationId' : 'pendingCompactionId';
+  if (metrics[key] !== operation.id) throw new Error('Session metrics operation ownership changed.');
+  const sum = addTokens(metrics.reportedLifetimeUsedTokens, operation.reportedTokens);
+  metrics.reportedLifetimeUsedTokens = sum.tokens;
+  metrics.reportedLifetimeUsedTokensExact &&= sum.exact && operation.reportedTokensExact;
+  metrics.lifetimeUsageComplete &&= operation.complete
+    && metrics.reportedLifetimeUsedTokensExact
+    // An arbitrary compactor may make uninstrumented calls. No report is not proof of zero spend.
+    && (operation.source === 'generation' || operation.sawCall);
+  if (operation.lastObservedInputTokens !== undefined) {
+    metrics.lastObservedInputTokens = operation.lastObservedInputTokens;
+    metrics.lastObservedInputTokensAt = operation.lastObservedInputTokensAt;
+  }
+  delete metrics[key];
+}
+
+export function sessionMetricsView(metrics: IFlexSessionMetricsState): IFlexSessionMetrics {
+  const inFlight = metrics.pendingGenerationId !== undefined || metrics.pendingCompactionId !== undefined;
+  const lifetimeUsageComplete = metrics.lifetimeUsageComplete && !inFlight;
+  return {
+    reportedLifetimeUsedTokens: metrics.reportedLifetimeUsedTokens,
+    reportedLifetimeUsedTokensExact: metrics.reportedLifetimeUsedTokensExact,
+    lifetimeUsageComplete,
+    inFlight,
+    ...(lifetimeUsageComplete ? { lifetimeUsedTokens: metrics.reportedLifetimeUsedTokens } : {}),
+    ...(metrics.lastObservedInputTokens === undefined ? {} : {
+      lastObservedInputTokens: metrics.lastObservedInputTokens,
+      lastObservedInputTokensAt: metrics.lastObservedInputTokensAt,
+      lastObservedInputTokensFreshness: 'historical' as const,
+    }),
+  };
+}

package/ts_chat_harness/readme.md

@@ -4,7 +4,7 @@ A FlexHarness session as the inputs of the `@design.estate/dees-catalog` harness
 pnpm add @modelprofile.com/flexharness @design.estate/dees-catalog
 ```
 
-The optional peer range is `^17.0.0 || ^19.5.0 || ^20.0.0`; the package builds and is tested against 20.
+The optional peer range is `^17.0.0 || ^19.5.0 || ^20.0.0 || ^21.0.0`; the package builds and is tested against 21.
 
 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.