@modelprofile.com/flexharness 1.0.0

package/ts/classes.stores.ts

@@ -0,0 +1,195 @@
+import * as plugins from './plugins.js';
+import {
+  FlexHarnessStoreConflictError,
+  FlexHarnessStoreFormatError,
+  FlexHarnessValidationError,
+} from './errors.js';
+import type { IFlexHarnessSnapshot, IFlexHarnessStore } from './interfaces.js';
+import { assertFlexHarnessSnapshot, cloneSerializable } from './utils.json.js';
+
+function validateSave(
+  snapshot: IFlexHarnessSnapshot,
+  expectedRevision: number,
+): IFlexHarnessSnapshot {
+  assertFlexHarnessSnapshot(snapshot);
+  if (!Number.isSafeInteger(expectedRevision) || expectedRevision < 0) {
+    throw new FlexHarnessValidationError('expectedRevision must be a non-negative integer.');
+  }
+  if (snapshot.revision !== expectedRevision + 1) {
+    throw new FlexHarnessStoreFormatError(
+      `Snapshot revision ${snapshot.revision} must equal expected revision ${expectedRevision} plus one.`,
+    );
+  }
+  return cloneSerializable(snapshot);
+}
+
+export class InMemoryFlexHarnessStore implements IFlexHarnessStore {
+  private readonly snapshots = new Map<string, IFlexHarnessSnapshot>();
+
+  public async load(storageKey: string): Promise<IFlexHarnessSnapshot | undefined> {
+    const snapshot = this.snapshots.get(storageKey);
+    return snapshot ? cloneSerializable(snapshot) : undefined;
+  }
+
+  public async save(
+    storageKey: string,
+    snapshot: IFlexHarnessSnapshot,
+    expectedRevision: number,
+  ): Promise<void> {
+    const validated = validateSave(snapshot, expectedRevision);
+    const actualRevision = this.snapshots.get(storageKey)?.revision ?? 0;
+    if (actualRevision !== expectedRevision) {
+      throw new FlexHarnessStoreConflictError(storageKey, expectedRevision, actualRevision);
+    }
+    this.snapshots.set(storageKey, validated);
+  }
+}
+
+export interface IJsonFileFlexHarnessStoreOptions {
+  directory: string;
+}
+
+/**
+ * Atomic and CAS-safe across instances in this process. It intentionally does not
+ * claim cross-process safety because no operating-system lock is held.
+ */
+export class JsonFileFlexHarnessStore implements IFlexHarnessStore {
+  private static readonly fileQueues = new Map<string, Promise<void>>();
+  private readonly directory: string;
+
+  constructor(options: IJsonFileFlexHarnessStoreOptions) {
+    if (!options.directory) {
+      throw new FlexHarnessValidationError('JsonFileFlexHarnessStore requires a directory.');
+    }
+    this.directory = plugins.path.resolve(options.directory);
+  }
+
+  public async load(storageKey: string): Promise<IFlexHarnessSnapshot | undefined> {
+    const filePath = this.filePath(storageKey);
+    return JsonFileFlexHarnessStore.inFileQueue(filePath, async () => {
+      await this.preparePath(filePath);
+      return this.readSnapshot(filePath);
+    });
+  }
+
+  public async save(
+    storageKey: string,
+    snapshot: IFlexHarnessSnapshot,
+    expectedRevision: number,
+  ): Promise<void> {
+    const validated = validateSave(snapshot, expectedRevision);
+    const filePath = this.filePath(storageKey);
+    await JsonFileFlexHarnessStore.inFileQueue(filePath, async () => {
+      await this.preparePath(filePath);
+      const current = await this.readSnapshot(filePath);
+      const actualRevision = current?.revision ?? 0;
+      if (actualRevision !== expectedRevision) {
+        throw new FlexHarnessStoreConflictError(storageKey, expectedRevision, actualRevision);
+      }
+      await this.writeSnapshot(filePath, validated);
+    });
+  }
+
+  private static inFileQueue<T>(filePath: string, operation: () => Promise<T>): Promise<T> {
+    const previous = JsonFileFlexHarnessStore.fileQueues.get(filePath) ?? Promise.resolve();
+    const result = previous.catch(() => undefined).then(operation);
+    const barrier = result.then(
+      () => undefined,
+      () => undefined,
+    );
+    JsonFileFlexHarnessStore.fileQueues.set(filePath, barrier);
+    void barrier.then(() => {
+      if (JsonFileFlexHarnessStore.fileQueues.get(filePath) === barrier) {
+        JsonFileFlexHarnessStore.fileQueues.delete(filePath);
+      }
+    });
+    return result;
+  }
+
+  private filePath(storageKey: string): string {
+    const digest = plugins.crypto.createHash('sha256').update(storageKey).digest('hex');
+    return plugins.path.join(this.directory, `${digest}.json`);
+  }
+
+  private async preparePath(filePath: string): Promise<void> {
+    await plugins.fs.mkdir(this.directory, { recursive: true, mode: 0o700 });
+    await plugins.fs.chmod(this.directory, 0o700);
+    await this.cleanupTemps(filePath);
+  }
+
+  private async cleanupTemps(filePath: string): Promise<void> {
+    const prefix = `${plugins.path.basename(filePath)}.`;
+    const entries = await plugins.fs.readdir(this.directory, { withFileTypes: true });
+    await Promise.all(
+      entries
+        .filter((entry) => entry.isFile() && entry.name.startsWith(prefix) && entry.name.endsWith('.tmp'))
+        .map(async (entry) => {
+          try {
+            await plugins.fs.unlink(plugins.path.join(this.directory, entry.name));
+          } catch (error) {
+            if ((error as NodeJS.ErrnoException).code !== 'ENOENT') {
+              throw error;
+            }
+          }
+        }),
+    );
+  }
+
+  private async readSnapshot(filePath: string): Promise<IFlexHarnessSnapshot | undefined> {
+    let serialized: string;
+    try {
+      await plugins.fs.chmod(filePath, 0o600);
+      serialized = await plugins.fs.readFile(filePath, 'utf8');
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code === 'ENOENT') {
+        return undefined;
+      }
+      throw error;
+    }
+
+    let parsed: unknown;
+    try {
+      parsed = JSON.parse(serialized);
+    } catch (error) {
+      throw new FlexHarnessStoreFormatError(`Malformed JSON snapshot at ${filePath}.`, {
+        cause: error,
+      });
+    }
+    try {
+      assertFlexHarnessSnapshot(parsed);
+    } catch (error) {
+      if (error instanceof FlexHarnessStoreFormatError) {
+        throw new FlexHarnessStoreFormatError(`Invalid snapshot at ${filePath}: ${error.message}`, {
+          cause: error,
+        });
+      }
+      throw error;
+    }
+    return cloneSerializable(parsed);
+  }
+
+  private async writeSnapshot(
+    filePath: string,
+    snapshot: IFlexHarnessSnapshot,
+  ): Promise<void> {
+    const tempPath = `${filePath}.${process.pid}.${plugins.crypto.randomUUID()}.tmp`;
+    let fileHandle: plugins.fs.FileHandle | undefined;
+    try {
+      fileHandle = await plugins.fs.open(tempPath, 'wx', 0o600);
+      await fileHandle.writeFile(`${JSON.stringify(snapshot, null, 2)}\n`, 'utf8');
+      await fileHandle.sync();
+      await fileHandle.close();
+      fileHandle = undefined;
+      await plugins.fs.chmod(tempPath, 0o600);
+      await plugins.fs.rename(tempPath, filePath);
+      await plugins.fs.chmod(filePath, 0o600);
+    } finally {
+      await fileHandle?.close().catch(() => undefined);
+      await plugins.fs.unlink(tempPath).catch((error: NodeJS.ErrnoException) => {
+        if (error.code !== 'ENOENT') {
+          throw error;
+        }
+      });
+    }
+  }
+}

package/ts/errors.ts

@@ -0,0 +1,125 @@
+import type { IFlexErrorInfo } from './interfaces.js';
+
+export class FlexHarnessError extends Error {
+  public readonly code: string;
+
+  constructor(code: string, message: string, options?: ErrorOptions) {
+    super(message, options);
+    this.name = 'FlexHarnessError';
+    this.code = code;
+  }
+}
+
+export class FlexHarnessValidationError extends FlexHarnessError {
+  constructor(message: string, options?: ErrorOptions) {
+    super('FLEX_VALIDATION', message, options);
+    this.name = 'FlexHarnessValidationError';
+  }
+}
+
+export class FlexHarnessClosedError extends FlexHarnessError {
+  constructor() {
+    super('FLEX_CLOSED', 'FlexHarness is disposed.');
+    this.name = 'FlexHarnessClosedError';
+  }
+}
+
+export class FlexHarnessNotFoundError extends FlexHarnessError {
+  constructor(resource: string, id: string) {
+    super('FLEX_NOT_FOUND', `${resource} "${id}" was not found.`);
+    this.name = 'FlexHarnessNotFoundError';
+  }
+}
+
+export class FlexHarnessSessionBusyError extends FlexHarnessError {
+  constructor(sessionId: string, reason = 'already has an active run') {
+    super('FLEX_SESSION_BUSY', `Session "${sessionId}" ${reason}.`);
+    this.name = 'FlexHarnessSessionBusyError';
+  }
+}
+
+export class FlexHarnessAbortError extends FlexHarnessError {
+  constructor(message = 'The run was aborted.', options?: ErrorOptions) {
+    super('FLEX_ABORTED', message, options);
+    this.name = 'FlexHarnessAbortError';
+  }
+}
+
+export class FlexHarnessCallbackOverflowError extends FlexHarnessError {
+  constructor(message: string) {
+    super('FLEX_CALLBACK_OVERFLOW', message);
+    this.name = 'FlexHarnessCallbackOverflowError';
+  }
+}
+
+export class FlexHarnessPermissionRejectedError extends FlexHarnessError {
+  constructor(permissionId: string, options?: ErrorOptions) {
+    super('FLEX_PERMISSION_REJECTED', `Permission "${permissionId}" was rejected.`, options);
+    this.name = 'FlexHarnessPermissionRejectedError';
+  }
+}
+
+export class FlexHarnessPermissionStateError extends FlexHarnessError {
+  constructor(message: string) {
+    super('FLEX_PERMISSION_STATE', message);
+    this.name = 'FlexHarnessPermissionStateError';
+  }
+}
+
+export class FlexHarnessStoreConflictError extends FlexHarnessError {
+  public readonly storageKey: string;
+  public readonly expectedRevision: number;
+  public readonly actualRevision: number;
+
+  constructor(storageKey: string, expectedRevision: number, actualRevision: number) {
+    super(
+      'FLEX_STORE_CONFLICT',
+      `Snapshot conflict for storage key "${storageKey}": expected revision ${expectedRevision}, found ${actualRevision}.`,
+    );
+    this.name = 'FlexHarnessStoreConflictError';
+    this.storageKey = storageKey;
+    this.expectedRevision = expectedRevision;
+    this.actualRevision = actualRevision;
+  }
+}
+
+export class FlexHarnessStoreFormatError extends FlexHarnessError {
+  constructor(message: string, options?: ErrorOptions) {
+    super('FLEX_STORE_FORMAT', message, options);
+    this.name = 'FlexHarnessStoreFormatError';
+  }
+}
+
+export class FlexHarnessRunError extends AggregateError {
+  public readonly code = 'FLEX_RUN_FAILED';
+
+  constructor(errors: unknown[]) {
+    super(errors, 'Multiple FlexHarness run or cleanup operations failed.');
+    this.name = 'FlexHarnessRunError';
+  }
+}
+
+export function errorToInfo(error: unknown): IFlexErrorInfo {
+  if (error instanceof FlexHarnessError) {
+    return {
+      name: error.name,
+      message: error.message,
+      code: error.code,
+    };
+  }
+  if (error instanceof Error) {
+    return {
+      name: error.name,
+      message: error.message,
+      ...('code' in error && typeof error.code === 'string' ? { code: error.code } : {}),
+    };
+  }
+  return {
+    name: 'Error',
+    message: String(error),
+  };
+}
+
+export function errorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}

package/ts/index.ts

@@ -0,0 +1,5 @@
+export * from './classes.flexharness.js';
+export * from './classes.stores.js';
+export * from './errors.js';
+export * from './interfaces.js';
+export { normalizeJsonValue } from './utils.json.js';

package/ts/interfaces.ts

@@ -0,0 +1,369 @@
+import type * as plugins from './plugins.js';
+
+export type TJsonPrimitive = string | number | boolean | null;
+
+export interface IJsonObject {
+  [key: string]: TJsonValue;
+}
+
+export type TJsonValue = TJsonPrimitive | IJsonObject | TJsonValue[];
+
+export type TFlexAgentRunOptions = plugins.IAgentRunOptions;
+export type TFlexAgentRunResult = plugins.IAgentRunResult;
+export type TFlexAgentRunner = (options: TFlexAgentRunOptions) => Promise<TFlexAgentRunResult>;
+export type TFlexAgentModel = TFlexAgentRunOptions['model'];
+export type TFlexAgentPrompt = TFlexAgentRunOptions['prompt'];
+export type TFlexAgentModelMessage = NonNullable<TFlexAgentRunOptions['messages']>[number];
+export type TFlexAgentToolSet = NonNullable<TFlexAgentRunOptions['tools']>;
+export type TFlexAgentProviderOptions = TFlexAgentRunOptions['providerOptions'];
+export type TFlexAgentCacheSetting = TFlexAgentRunOptions['cache'];
+export type TFlexAgentToolCallFinishEvent = Parameters<
+  NonNullable<TFlexAgentRunOptions['onToolCallFinish']>
+>[0];
+
+export interface IFlexTextPromptPart {
+  type: 'text';
+  text: string;
+}
+
+export interface IFlexImagePromptPart {
+  type: 'image';
+  data: string;
+  mediaType?: string;
+  name?: string;
+}
+
+export interface IFlexFilePromptPart {
+  type: 'file';
+  data: string;
+  mediaType: string;
+  name?: string;
+}
+
+export type TFlexPromptPart = IFlexTextPromptPart | IFlexImagePromptPart | IFlexFilePromptPart;
+export type TFlexPrompt = string | TFlexPromptPart[];
+
+export interface IFlexUsage {
+  inputTokens: number;
+  outputTokens: number;
+  totalTokens: number;
+  cacheReadTokens: number;
+  cacheWriteTokens: number;
+}
+
+export interface IFlexModelIdentity {
+  provider: string;
+  model: string;
+  displayName?: string;
+}
+
+export type TFlexActivityStatus =
+  | 'idle'
+  | 'running'
+  | 'waiting_permission'
+  | 'failed'
+  | 'cancelled';
+export type TFlexMessageStatus = 'streaming' | 'completed' | 'failed' | 'cancelled';
+export type TFlexToolPartStatus = 'running' | 'completed' | 'failed' | 'cancelled';
+export type TFlexAttachmentSource = 'inline-base64' | 'data-url' | 'remote-url';
+
+export interface IFlexTextMessagePart {
+  partId: string;
+  type: 'text';
+  text: string;
+}
+
+export interface IFlexReasoningMessagePart {
+  partId: string;
+  type: 'reasoning';
+  text: string;
+  status: 'running' | 'completed' | 'cancelled';
+}
+
+export interface IFlexToolMessagePart {
+  partId: string;
+  type: 'tool';
+  toolCallId: string;
+  toolName: string;
+  status: TFlexToolPartStatus;
+  input: TJsonValue;
+  output?: TJsonValue;
+  error?: string;
+}
+
+export interface IFlexAttachmentMessagePart {
+  partId: string;
+  type: 'attachment';
+  attachmentType: 'image' | 'file';
+  source: TFlexAttachmentSource;
+  sizeBytes?: number;
+  mediaType?: string;
+  name?: string;
+}
+
+export type TFlexMessagePart =
+  | IFlexTextMessagePart
+  | IFlexReasoningMessagePart
+  | IFlexToolMessagePart
+  | IFlexAttachmentMessagePart;
+
+export interface IFlexMessage {
+  messageId: string;
+  sessionId: string;
+  runId: string;
+  role: 'user' | 'assistant';
+  status: TFlexMessageStatus;
+  createdAt: string;
+  completedAt?: string;
+  parts: TFlexMessagePart[];
+  model?: IFlexModelIdentity;
+  usage?: IFlexUsage;
+  error?: string;
+}
+
+export interface IFlexSessionActivity {
+  runId?: string;
+  status: TFlexActivityStatus;
+  startedAt?: string;
+  completedAt?: string;
+  error?: string;
+}
+
+export interface IFlexSession {
+  scopeId: string;
+  sessionId: string;
+  title?: string;
+  createdAt: string;
+  updatedAt: string;
+  archivedAt?: string;
+  status: TFlexActivityStatus;
+  activity: IFlexSessionActivity;
+}
+
+export interface IFlexCreateSessionOptions {
+  sessionId?: string;
+  title?: string;
+}
+
+export interface IFlexUpdateSessionOptions {
+  title?: string | null;
+  archived?: boolean;
+}
+
+export interface IFlexPromptOptions {
+  modelHint?: string;
+  system?: string;
+  maxSteps?: number;
+}
+
+export interface IFlexPromptResult {
+  runId: string;
+  sessionId: string;
+  userMessage: IFlexMessage;
+  assistantMessage: IFlexMessage;
+  model: IFlexModelIdentity;
+  usage: IFlexUsage;
+  finishReason: string;
+  steps: number;
+}
+
+export interface IFlexResolvedScope<TScope> {
+  storageKey: string;
+  scope: TScope;
+}
+
+export interface IFlexScopeResolver<TScope> {
+  resolveScope(scopeId: string): Promise<IFlexResolvedScope<TScope>> | IFlexResolvedScope<TScope>;
+}
+
+export interface IFlexModelResolverContext<TScope> {
+  scopeId: string;
+  scope: TScope;
+  sessionId: string;
+  runId: string;
+  modelHint?: string;
+  signal: AbortSignal;
+}
+
+export interface IFlexResolvedModel {
+  model: TFlexAgentModel;
+  identity: IFlexModelIdentity;
+  system?: string;
+  providerOptions?: TFlexAgentProviderOptions;
+  cache?: TFlexAgentCacheSetting;
+  maxSteps?: number;
+}
+
+export interface IFlexModelResolver<TScope> {
+  resolveModel(
+    context: IFlexModelResolverContext<TScope>,
+  ): Promise<IFlexResolvedModel> | IFlexResolvedModel;
+}
+
+export interface IFlexPermissionRequestInput {
+  kind: string;
+  description: string;
+  toolCallId?: string;
+  rememberKey?: string;
+  metadata?: TJsonValue;
+}
+
+export interface IFlexPermissionRequest extends IFlexPermissionRequestInput {
+  permissionId: string;
+  scopeId: string;
+  sessionId: string;
+  runId: string;
+  createdAt: string;
+}
+
+export type TFlexPermissionDecision = 'once' | 'always' | 'reject';
+
+export interface IFlexToolProviderContext<TScope> {
+  scopeId: string;
+  scope: TScope;
+  sessionId: string;
+  runId: string;
+  signal: AbortSignal;
+  requestPermission(request: IFlexPermissionRequestInput): Promise<void>;
+}
+
+export interface IFlexToolHandle {
+  tools: TFlexAgentToolSet;
+  close?(): Promise<void> | void;
+}
+
+export interface IFlexToolProvider<TScope> {
+  provideTools(
+    context: IFlexToolProviderContext<TScope>,
+  ): Promise<IFlexToolHandle | undefined> | IFlexToolHandle | undefined;
+}
+
+export interface IFlexStoredSessionSnapshot {
+  session: IFlexSession;
+  messages: IFlexMessage[];
+  modelHistory: TJsonValue[];
+  rememberedPermissionKeys: string[];
+}
+
+export interface IFlexHarnessSnapshot {
+  schemaVersion: 1;
+  revision: number;
+  sessions: IFlexStoredSessionSnapshot[];
+}
+
+export interface IFlexHarnessStore {
+  load(storageKey: string): Promise<IFlexHarnessSnapshot | undefined>;
+  save(
+    storageKey: string,
+    snapshot: IFlexHarnessSnapshot,
+    expectedRevision: number,
+  ): Promise<void>;
+}
+
+export interface IFlexJsonLimits {
+  maxDepth?: number;
+  maxBytes?: number;
+}
+
+export interface IFlexCallbackLimits {
+  maxEvents?: number;
+  maxOutputBytes?: number;
+  maxParts?: number;
+}
+
+export interface IFlexHarnessOptions<TScope> {
+  scopeResolver: IFlexScopeResolver<TScope>;
+  modelResolver: IFlexModelResolver<TScope>;
+  toolProvider?: IFlexToolProvider<TScope>;
+  store?: IFlexHarnessStore;
+  runner?: TFlexAgentRunner;
+  toolOutputLimits?: IFlexJsonLimits;
+  callbackLimits?: IFlexCallbackLimits;
+}
+
+export interface IFlexEventBase {
+  readonly eventId: string;
+  readonly sequence: number;
+  readonly timestamp: string;
+  readonly scopeId: string;
+  readonly sessionId: string;
+}
+
+export interface IFlexSessionCreatedEvent extends IFlexEventBase {
+  readonly type: 'session.created';
+  readonly session: IFlexSession;
+}
+
+export interface IFlexSessionUpdatedEvent extends IFlexEventBase {
+  readonly type: 'session.updated';
+  readonly session: IFlexSession;
+}
+
+export interface IFlexSessionDeletedEvent extends IFlexEventBase {
+  readonly type: 'session.deleted';
+  readonly session: IFlexSession;
+}
+
+export interface IFlexRunStartedEvent extends IFlexEventBase {
+  readonly type: 'run.started';
+  readonly runId: string;
+  readonly messageId: string;
+  readonly session: IFlexSession;
+}
+
+export interface IFlexMessageChangedEvent extends IFlexEventBase {
+  readonly type: 'message.created' | 'message.updated';
+  readonly runId: string;
+  readonly messageId: string;
+  readonly message: IFlexMessage;
+}
+
+export interface IFlexPartChangedEvent extends IFlexEventBase {
+  readonly type: 'part.started' | 'part.delta' | 'part.completed';
+  readonly runId: string;
+  readonly messageId: string;
+  readonly partId: string;
+  readonly part: TFlexMessagePart;
+  readonly delta?: string;
+}
+
+export interface IFlexPermissionRequestedEvent extends IFlexEventBase {
+  readonly type: 'permission.requested';
+  readonly runId: string;
+  readonly request: IFlexPermissionRequest;
+}
+
+export interface IFlexPermissionResolvedEvent extends IFlexEventBase {
+  readonly type: 'permission.resolved';
+  readonly runId: string;
+  readonly request: IFlexPermissionRequest;
+  readonly decision: TFlexPermissionDecision;
+}
+
+export interface IFlexRunFinishedEvent extends IFlexEventBase {
+  readonly type: 'run.finished';
+  readonly runId: string;
+  readonly messageId: string;
+  readonly status: 'completed' | 'failed' | 'cancelled';
+  readonly message: IFlexMessage;
+  readonly error?: IFlexErrorInfo;
+}
+
+export interface IFlexErrorInfo {
+  name: string;
+  message: string;
+  code?: string;
+}
+
+export type TFlexHarnessEvent =
+  | IFlexSessionCreatedEvent
+  | IFlexSessionUpdatedEvent
+  | IFlexSessionDeletedEvent
+  | IFlexRunStartedEvent
+  | IFlexMessageChangedEvent
+  | IFlexPartChangedEvent
+  | IFlexPermissionRequestedEvent
+  | IFlexPermissionResolvedEvent
+  | IFlexRunFinishedEvent;
+
+export type TFlexHarnessEventListener = (event: TFlexHarnessEvent) => void;

package/ts/plugins.ts

@@ -0,0 +1,15 @@
+// node native scope
+import * as crypto from 'node:crypto';
+import * as fs from 'node:fs/promises';
+import * as path from 'node:path';
+
+export { crypto, fs, path };
+
+// @push.rocks scope
+import { runAgent } from '@push.rocks/smartagent';
+
+export { runAgent };
+export type {
+  IAgentRunOptions,
+  IAgentRunResult,
+} from '@push.rocks/smartagent';