@modelprofile.com/flexharness 10.24.0 → 10.24.1

package/ts/interfaces.flexharness.ts

@@ -0,0 +1,517 @@
+import type * as plugins from './plugins.js';
+import type { FlexHarnessAbortError } from './errors.js';
+import type { FlexToolCatalog } from './classes.toolcatalog.js';
+import type { FlexCodeSandbox } from './classes.codesandbox.js';
+import type {
+  IFlexAgentContextInvocation,
+  IFlexAffectedWorkspace,
+  IFlexDelegatedRunAdmissionContext,
+  IFlexDelegatedRunAdmissionLease,
+  IFlexExecutionContextHandle,
+  IFlexImportedRun,
+  IFlexMessage,
+  IFlexPermissionRequest,
+  IFlexPromptAdmission,
+  IFlexPromptQueueEntry,
+  IFlexPromptOptions,
+  IFlexPromptResult,
+  IFlexReversionSegment,
+  IFlexPendingReversionRelease,
+  IFlexResolvedModel,
+  IFlexResolvedSessionConfiguration,
+  IFlexSession,
+  IFlexSessionMetricsState,
+  IFlexSessionTombstone,
+  IFlexSubagentDefinition,
+  IFlexTerminalProjection,
+  IFlexToolHandle,
+  IFlexToolProviderContext,
+  IFlexUsage,
+  TFlexHarnessEvent,
+  TFlexMessagePart,
+  TFlexProjectTaskPriority,
+  TFlexProjectTaskStatus,
+  TFlexPromptQueueStatus,
+  TFlexPendingReversion,
+  TFlexProjectionSnapshot,
+  TFlexSessionReversionGroupKind,
+  TFlexTurnReversionFinalizedOutcome,
+} from './interfaces.js';
+import type { INormalizedFlexPrompt } from './utils.prompt.js';
+import type { TRegisteredSlashCommand } from './utils.harnessoptions.js';
+import type { INormalizedSessionImportOptions } from './utils.sessionimport.js';
+import type { ISessionMetricsOperation } from './utils.sessionmetrics.js';
+
+export type TCanonicalOutcome = 'accepted' | 'rejected' | 'interrupted';
+export type TRunPhase =
+  | 'admitting'
+  | 'scheduled'
+  | 'running'
+  | 'closing'
+  | 'finalizing'
+  | 'promoting';
+
+/** The invocation a compaction runs under; a manual compaction also carries its requested model hint. */
+export interface ICompactorInvocation<TScope> extends IFlexAgentContextInvocation<TScope> {
+  readonly modelHint?: string;
+}
+
+export interface IStoredSessionState {
+  storageKey: string;
+  compactorContext?: IFlexAgentContextInvocation<unknown>;
+  session: IFlexSession;
+  messages: IFlexMessage[];
+  stagedTerminals: IFlexTerminalProjection[];
+  reversionSegments: IFlexReversionSegment[];
+  revertCursor: number;
+  excludedRunIds: string[];
+  pendingReversion?: TFlexPendingReversion;
+  pendingReversionReleases: IFlexPendingReversionRelease[];
+  projectionSchemaVersion: 1 | 2 | 3;
+  projectionBaseline?: TFlexProjectionSnapshot;
+  projectionReconciliationRequired: boolean;
+  projectionRevision: number;
+  projectionQueue: Promise<void>;
+  metrics: IFlexSessionMetricsState;
+  metricsCompaction?: ISessionMetricsOperation;
+  /** Retained independently of the error-neutral projectionQueue. */
+  metricsFailure?: unknown;
+  rememberedPermissionKeys: Set<string>;
+  permissionRevision: number;
+  permissionQueue: Promise<void>;
+  eventStore: plugins.IAgentEventStoreV2;
+  agentSession: plugins.IAgentSession;
+  agentSessionAbortCompleted: boolean;
+  agentSessionCloseCompleted: boolean;
+  agentEventStoreReleased: boolean;
+  executionContextHandle?: IFlexExecutionContextHandle;
+  executionContextCloseCompleted: boolean;
+  jobStoreReleased: boolean;
+  jobs?: NonNullable<plugins.IToolExecutionContext['jobs']>;
+  compactorLifecycleController: AbortController;
+  promptQueue: IQueuedPrompt[];
+  outstandingPromptsById: Map<string, IQueuedPrompt>;
+  terminalPromptQueueEntries: Map<string, IFlexPromptQueueEntry>;
+  outstandingPromptBytes: number;
+  promptQueueDrain?: Promise<void>;
+}
+
+export interface IRetainedSessionCleanup {
+  stored: IStoredSessionState;
+  domainsCompleted: boolean;
+}
+
+export interface IReversionGroup {
+  target: IFlexReversionSegment;
+  segments: IFlexReversionSegment[];
+  kind: TFlexSessionReversionGroupKind;
+  affectedWorkspaces: IFlexAffectedWorkspace[];
+  affectedWorkspacesTruncated: boolean;
+}
+
+export type TNormalizedCaptureInspection =
+  | { status: 'missing' | 'prepared' | 'unknown' }
+  | { status: 'finalized'; outcome: TFlexTurnReversionFinalizedOutcome };
+
+export interface IDetachedCleanup {
+  cleanup: () => Promise<void> | void;
+  projectError: (error: unknown) => Error;
+  completion?: Promise<void>;
+  error?: Error;
+}
+
+export interface IOrphanedProviderRelease {
+  providerName: 'agentEvents' | 'jobs';
+  storageKey: string;
+  sessionId: string;
+  release: () => Promise<void>;
+}
+
+export interface IOrphanedTombstoneCleanup {
+  storageKey: string;
+  sessionId: string;
+  completion: Promise<void>;
+}
+
+export interface IOrphanedTombstoneOwner<TScope> {
+  state: IStorageState;
+  rootSessionId: string;
+  scopeId: string;
+  scope: TScope;
+}
+
+export interface IOrphanedExecutionContextOwner {
+  storageKey: string;
+  sessionId: string;
+}
+
+/** A staged session import: its runs stay in memory until the import is committed. */
+export interface IStagedSessionImport {
+  importId: string;
+  scopeId: string;
+  state: IStorageState;
+  scope: unknown;
+  sessionId: string;
+  options: INormalizedSessionImportOptions;
+  identity: string;
+  runs: IFlexImportedRun[];
+  runIds: Set<string>;
+  messageIds: Set<string>;
+  messageCount: number;
+  bytes: number;
+  phase: 'staging' | 'committing';
+  /** Discards the import when it stays idle; cleared once the import commits or is released. */
+  idleTimer?: ReturnType<typeof setTimeout>;
+}
+
+export interface IStorageState {
+  storageKey: string;
+  compactorLifecycleController: AbortController;
+  scopeIdHint: string;
+  scopeContext: { scopeId: string; scope: unknown };
+  revision: number;
+  sessions: Map<string, IStoredSessionState>;
+  retainedSessionCleanups: Map<string, IRetainedSessionCleanup>;
+  sessionDeletions: Map<string, Promise<void>>;
+  initializingSessions: Set<string>;
+  sessionInitializations: Map<string, Promise<void>>;
+  /** Staged session imports by session id; their ids are also in `initializingSessions`. */
+  sessionImports: Map<string, IStagedSessionImport>;
+  tombstones: Map<string, IFlexSessionTombstone>;
+  tombstoneCleanups: Map<string, Promise<void>>;
+  activeRuns: Map<string, IActiveRun>;
+  delegatedRunAdmissionOwners: Set<IDelegatedRunAdmissionOwner>;
+  pendingPermissions: Map<string, IPendingPermission>;
+  /**
+   * Per session, the open sections that change what a session view shows and emit the events
+   * describing it. A view waits until none is open, so it never shows a change without its event.
+   */
+  publications: Map<string, Set<Promise<void>>>;
+  scopeQueue: Promise<void>;
+  lifecycle: 'active' | 'retiring' | 'fenced' | 'retired';
+  fenceInProgress: boolean;
+  fenceAdditionalErrors: unknown[];
+  detachedCleanups: Set<IDetachedCleanup>;
+}
+
+export interface IActiveRun {
+  state: IStorageState;
+  stored: IStoredSessionState;
+  originCompactorContext: IFlexAgentContextInvocation<unknown>;
+  deferredCompactorContext?: IFlexAgentContextInvocation<unknown>;
+  scopeId: string;
+  scope: unknown;
+  sessionId: string;
+  queueId: string;
+  runId: string;
+  userMessageId: string;
+  assistantMessageId: string;
+  controller: AbortController;
+  transaction?: plugins.IAgentGenerationHandle;
+  scheduleKey?: string;
+  debounceMs?: number;
+  ownerCancellation?: FlexHarnessAbortError;
+  internalFailure?: unknown;
+  callbackError?: unknown;
+  callbackEventCount: number;
+  callbackOutputBytes: number;
+  callbackParts: TFlexMessagePart[];
+  partTextUtf8Bytes: Map<string, number>;
+  callbacksClosed: boolean;
+  /** Set once the run emitted its `run.finished` event. */
+  finishedEventEmitted: boolean;
+  /** The usage the provider reported for the run's model calls so far. */
+  usage: IFlexUsage;
+  metricsOperation?: ISessionMetricsOperation;
+  reasoningPartIds: Map<string, string>;
+  toolPartIds: Map<string, string>;
+  trustedToolExecutionErrors: Map<string, Error>;
+  /**
+   * The confirmations of read-only calls started while the model still streamed, by tool call ID:
+   * their permission requests wait for them.
+   */
+  unconfirmedToolCalls: Map<string, Promise<void>>;
+  /**
+   * The read-only calls of the turn by real name and canonical params, with the call that answers
+   * them. A call that is not read-only clears them when it runs.
+   */
+  readCalls: Map<string, IRunReadCall>;
+  /** Calls an identical earlier read answered: the call's ID to the earlier call's. */
+  deduplicatedToolCalls: Map<string, string>;
+  subagentCallCount: number;
+  subagentSessionIds: Set<string>;
+  backgroundSubagents: Set<Promise<void>>;
+  cacheDispatch?: plugins.ISmartAiCacheDispatch;
+  pendingPermissionIds: Set<string>;
+  phase: TRunPhase;
+  reservedUserMessage?: IFlexMessage;
+  reservedAssistantMessage?: IFlexMessage;
+  modelResolution?: IFlexResolvedModel;
+  /** The tool-provider context of the run, passed to catalog methods. */
+  toolProviderContext?: Readonly<IFlexToolProviderContext<unknown>>;
+  /** The catalog methods the run offers through search_tools, describe_tools and execute. */
+  toolCatalog?: FlexToolCatalog<unknown>;
+  /** The sandbox `run_code` programs run in, loaded when the catalog has code mode. */
+  codeSandbox?: FlexCodeSandbox;
+  /** The tool handle's classifier of read-only calls. */
+  isReadOnlyHostCall?: IFlexToolHandle['isReadOnlyToolCall'];
+  subagents: ReadonlyMap<string, Readonly<IFlexSubagentDefinition>>;
+  allowedTools?: readonly string[];
+  agentAllowedTools?: readonly string[];
+  permissionPolicy?: IFlexResolvedSessionConfiguration<unknown>['permissionPolicy'];
+  delegatedRunAdmissionOwner?: IDelegatedRunAdmissionOwner;
+  delegatedRunAdmissionClose?: Promise<void>;
+  completion: Promise<IFlexPromptResult>;
+  steering: IRunSteering;
+  /** Stops the run's generation for its owner, so what the model produced stays in context. */
+  stop: AbortController;
+}
+
+/** The validated params of a `results.get` call. */
+export interface IResultRead {
+  handle: string;
+  page?: number;
+  path?: string;
+}
+
+/** A read-only call of a turn and its output, which identical reads after it share. */
+export interface IRunReadCall {
+  readonly toolCallId: string;
+  /** The call's output; `notShared` when it streams its output, which only its own call reads. */
+  readonly output: Promise<unknown>;
+}
+
+/** The steers of a run: the input its generation takes in, and the prompts it accepted for it. */
+export interface IRunSteering {
+  readonly input: plugins.AgentPendingInputQueue;
+  /** The session whose outstanding prompt bytes hold the bytes of the steers not taken in yet. */
+  readonly stored: IStoredSessionState;
+  /** Every steer the run accepted, in arrival order, by steer id. */
+  readonly accepted: Map<string, { prompt: INormalizedFlexPrompt; byteSize: number }>;
+  /** Accepted steers the generation recorded durably as user messages of the run. */
+  readonly applied: Set<string>;
+  /** Whether the run stays in the model context of later turns, once that is established. */
+  keptInContext?: boolean;
+  /** What became of the run's steers, fixed when the run ends. */
+  outcome?: IRunSteeringOutcome;
+}
+
+export interface IRunSteeringOutcome {
+  /** Whether the run's prompt, the steers it took in and what its model produced stay in context. */
+  readonly keptInContext: boolean;
+  /** Accepted steers the model context of later turns does not hold, in arrival order. */
+  readonly unappliedSteerIds: readonly string[];
+}
+
+export interface IDelegatedRunAdmissionSeed {
+  readonly state: IStorageState;
+  readonly childStored: IStoredSessionState;
+  readonly parentRun: IActiveRun;
+  readonly parentStored: IStoredSessionState;
+  readonly scopeId: string;
+  readonly scope: unknown;
+  readonly storageKey: string;
+  readonly sessionId: string;
+  readonly sessionGenerationId: string;
+  readonly sessionGenerationSequence: number;
+  readonly originParentRunId: string;
+  readonly originParentToolCallId: string;
+  readonly parentSessionId: string;
+  readonly parentSessionGenerationId: string;
+  readonly parentSessionGenerationSequence: number;
+  readonly parentQueueId: string;
+  readonly parentRunId: string;
+  readonly parentToolCallId: string;
+  readonly configurationRef?: string;
+  readonly agent: string;
+  readonly depth: number;
+}
+
+export type TDelegatedRunAdmissionOwnerStatus =
+  | 'acquiring'
+  | 'acquired'
+  | 'close-requested'
+  | 'retrying'
+  | 'closed';
+
+export interface IDelegatedRunAdmissionOwner {
+  readonly storageState: IStorageState;
+  readonly run: IActiveRun;
+  readonly context: Readonly<IFlexDelegatedRunAdmissionContext<unknown>>;
+  status: TDelegatedRunAdmissionOwnerStatus;
+  acquisitionSettled: boolean;
+  acquisitionDetached: boolean;
+  acquisitionCompletion?: Promise<void>;
+  acquisitionError?: Error;
+  lease?: IFlexDelegatedRunAdmissionLease;
+  closeAttempt?: Promise<void>;
+  closeAttemptSequence: number;
+  closeFailure?: { sequence: number; error: Error };
+}
+
+export interface IQueuedPrompt {
+  state: IStorageState;
+  stored: IStoredSessionState;
+  scopeId: string;
+  scope: unknown;
+  sessionId: string;
+  queueId: string;
+  queueSequence: number;
+  status: Exclude<TFlexPromptQueueStatus, 'completed' | 'failed' | 'cancelled'>;
+  queuedAt: string;
+  runId?: string;
+  scheduleKey?: string;
+  debounceMs?: number;
+  startedAt?: string;
+  prompt?: INormalizedFlexPrompt;
+  options?: IFlexPromptOptions;
+  delegationSeed?: IDelegatedRunAdmissionSeed;
+  byteSize: number;
+  /** The steering of the run the prompt started, once it started one. */
+  steering?: IRunSteering;
+  completion: Promise<IFlexPromptResult>;
+  resolveCompletion: (result: IFlexPromptResult) => void;
+  rejectCompletion: (error: unknown) => void;
+  started: Promise<IFlexPromptAdmission>;
+  resolveStarted: (admission: IFlexPromptAdmission) => void;
+  rejectStarted: (error: unknown) => void;
+}
+
+export interface IPendingPromptAdmission {
+  controller: AbortController;
+  settled: Promise<void>;
+  resolveSettled: () => void;
+}
+
+export interface IPendingPermission {
+  request: IFlexPermissionRequest;
+  run: IActiveRun;
+  resolve: () => void;
+  reject: (error: unknown) => void;
+  settled: boolean;
+  responding: boolean;
+  abortReason?: unknown;
+  responseQueue: Promise<void>;
+  abortListener: () => void;
+}
+
+export interface IScopeAdmissionState {
+  generation: number;
+  inFlightResolvers: number;
+  retiring: boolean;
+}
+
+export interface IActiveSlashCommandExecution {
+  kind: 'handler' | 'operation' | 'prompt-admission';
+  storageKey: string;
+  sessionId: string;
+  controller: AbortController;
+  completion: Promise<unknown>;
+}
+
+export interface IActiveSlashCommandListing {
+  storageKey: string;
+  sessionId: string;
+  controller: AbortController;
+  completion: Promise<unknown>;
+}
+
+export interface IResolvedSessionConfiguration<TScope> {
+  subagents: ReadonlyMap<string, Readonly<IFlexSubagentDefinition>>;
+  slashCommands: ReadonlyMap<string, TRegisteredSlashCommand<TScope>>;
+  allowedTools?: readonly string[];
+  permissionPolicy?: IFlexResolvedSessionConfiguration<TScope>['permissionPolicy'];
+}
+
+export interface ISessionConfigurationOwner<TScope> {
+  storageKey: string;
+  sessionId: string;
+  controller: AbortController;
+  completion: Promise<IResolvedSessionConfiguration<TScope>>;
+  settled: boolean;
+  waiters: number;
+}
+
+export interface ISlashCommandInvocationOwner {
+  scopeId: string;
+  storageKey: string;
+  sessionId: string;
+  sessionKey: string;
+}
+
+export interface ISlashCommandActivityOwner {
+  scopeId: string;
+  storageKey: string;
+  sessionId: string;
+}
+
+export interface IResolverOutcome<TValue> {
+  source: 'model' | 'tools' | 'abort';
+  success: boolean;
+  value?: TValue;
+  error?: unknown;
+}
+
+export interface IFlexMessageCursor {
+  version: 1;
+  namespace: string;
+  sessionId: string;
+  anchorMessageId: string;
+}
+
+export interface IFlexSubagentTaskInput {
+  description: string;
+  prompt: string;
+  subagentType: string;
+  taskId?: string;
+  foreground?: boolean;
+}
+
+export interface IFlexSubagentAcquisition {
+  stored: IStoredSessionState;
+  created: boolean;
+}
+
+export interface ISessionDeletionPlan {
+  matched: boolean;
+  deletion?: Promise<void>;
+}
+
+export interface IReservedSessionDeletion {
+  deletedSessions: IFlexSession[];
+  descendantRoots: string[];
+}
+
+export type TProjectTaskToolInput =
+  | { action: 'list' }
+  | {
+      action: 'create';
+      id?: string;
+      content: string;
+      status?: TFlexProjectTaskStatus;
+      priority?: TFlexProjectTaskPriority;
+    }
+  | {
+      action: 'update';
+      id: string;
+      content?: string;
+      status?: TFlexProjectTaskStatus;
+      priority?: TFlexProjectTaskPriority;
+    }
+  | { action: 'delete'; id: string }
+  | { action: 'clear' };
+
+export type TProjectGoalToolInput =
+  | { action: 'get' }
+  | { action: 'set'; goal: string }
+  | { action: 'clear' };
+
+export type TProjectScratchpadToolInput =
+  | { action: 'get' }
+  | { action: 'set'; content: string }
+  | { action: 'append'; content: string }
+  | { action: 'clear' };
+
+export type TEventDetails = Record<string, unknown> & {
+  type: TFlexHarnessEvent['type'];
+};

package/ts/utils.flexharness.ts

@@ -0,0 +1,121 @@
+import * as plugins from './plugins.js';
+import {
+  FlexHarnessAbortError,
+  FlexHarnessRunError,
+  FlexHarnessValidationError,
+} from './errors.js';
+import type {
+  IFlexErrorInfo,
+  IFlexMessage,
+  IFlexSession,
+  IFlexSessionActivity,
+  IFlexSessionGeneration,
+  IFlexSessionTombstone,
+} from './interfaces.js';
+import { validateUtf8String } from './utils.validation.js';
+
+/** Runs `operation` after the operations queued before it under `key`, whatever their outcome. */
+export function queueOperation<TResult>(
+  queues: Map<string, Promise<void>>,
+  key: string,
+  operation: () => Promise<TResult>,
+): Promise<TResult> {
+  const previous = queues.get(key) ?? Promise.resolve();
+  const result = previous.then(operation);
+  const barrier = result.then(() => undefined, () => undefined);
+  queues.set(key, barrier);
+  void barrier.then(() => {
+    if (queues.get(key) === barrier) queues.delete(key);
+  });
+  return result;
+}
+
+export const maxResourceIdBytes = 512;
+export const maxResourceToolNameBytes = 512;
+export const resourceToolStemLength = 16;
+export const scopeRetirementMessage = 'The scope is being retired.';
+export const slashCommandSessionUnavailableReason = 'Session must be idle with no queued prompts.';
+
+export const externalErrorFallback: IFlexErrorInfo = Object.freeze({
+  name: 'FlexHarnessExternalError',
+  message: 'The model operation failed.',
+  code: 'FLEX_EXTERNAL_ERROR',
+});
+
+export function createSessionGenerationId(): string {
+  return `generation_${plugins.crypto.randomUUID()}`;
+}
+
+export function requireSessionGeneration(
+  session: Pick<
+    IFlexSession | IFlexSessionTombstone,
+    'sessionGenerationId' | 'sessionGenerationSequence'
+  >,
+): IFlexSessionGeneration {
+  if (
+    !session.sessionGenerationId
+    || !Number.isSafeInteger(session.sessionGenerationSequence)
+    || Number(session.sessionGenerationSequence) < 1
+  ) {
+    throw new FlexHarnessValidationError('Session generation metadata is missing.');
+  }
+  return {
+    sessionGenerationId: session.sessionGenerationId,
+    sessionGenerationSequence: session.sessionGenerationSequence as number,
+  };
+}
+
+export function sha256Hex(value: string): string {
+  return plugins.crypto.createHash('sha256').update(value, 'utf8').digest('hex');
+}
+
+export function createFlexResourceIdentityDigest(
+  resourceId: string,
+  attachmentRevision: number,
+): string {
+  validateUtf8String(resourceId, 'resourceId', maxResourceIdBytes, true);
+  if (!Number.isSafeInteger(attachmentRevision) || attachmentRevision < 0) {
+    throw new FlexHarnessValidationError('attachmentRevision must be a non-negative safe integer.');
+  }
+  return sha256Hex(JSON.stringify([resourceId, attachmentRevision]));
+}
+
+export function createFlexResourceToolNamespace(
+  resourceId: string,
+  attachmentRevision: number,
+): string {
+  const digest = createFlexResourceIdentityDigest(resourceId, attachmentRevision);
+  return `resource_${digest.slice(0, 16)}`;
+}
+
+export function createFlexResourceToolName(namespace: string, toolName: string): string {
+  if (!/^resource_[a-f0-9]{16}$/u.test(namespace)) {
+    throw new FlexHarnessValidationError('Resource tool namespace is invalid.');
+  }
+  validateUtf8String(toolName, 'resource tool name', maxResourceToolNameBytes, true);
+  const stem = toolName
+    .replace(/[^A-Za-z0-9_-]/gu, '_')
+    .slice(0, resourceToolStemLength) || 'tool';
+  return `${namespace}__${stem}__${sha256Hex(toolName).slice(0, 12)}`;
+}
+
+export function combineErrors(errors: unknown[]): unknown {
+  if (errors.length === 1) return errors[0];
+  const combined = new FlexHarnessRunError(errors);
+  Object.freeze(combined.errors);
+  return Object.freeze(combined);
+}
+
+/** The error and model limit a finished run leaves on its session activity. */
+export function terminalActivityError(message: IFlexMessage): Pick<IFlexSessionActivity, 'error' | 'limit'> {
+  return {
+    ...(message.error ? { error: message.error } : {}),
+    ...(message.limit ? { limit: message.limit } : {}),
+  };
+}
+
+export function isAbortError(error: unknown): boolean {
+  return error instanceof FlexHarnessAbortError
+    || (error instanceof DOMException && error.name === 'AbortError')
+    || (error instanceof Error && error.name === 'AbortError');
+}