@modelprofile.com/flexharness 3.6.0 → 3.8.0

package/ts/classes.stores.ts

@@ -10,11 +10,12 @@ import type {
   IFlexHarnessStores,
   IFlexPermissionSnapshot,
   IFlexPermissionStore,
-  IFlexProjectionSnapshot,
+  IFlexProjectionSnapshotV3,
   IFlexProjectionStore,
   IFlexScopeSnapshot,
   IFlexScopeStore,
   IFlexToolJobStoreProvider,
+  TFlexProjectionSnapshot,
 } from './interfaces.js';
 import {
   assertFlexPermissionSnapshot,
@@ -24,7 +25,7 @@ import {
   cloneSerializable,
 } from './utils.json.js';
 
-type TSnapshot = IFlexScopeSnapshot | IFlexProjectionSnapshot | IFlexPermissionSnapshot;
+type TSnapshot = IFlexScopeSnapshot | TFlexProjectionSnapshot | IFlexPermissionSnapshot;
 type TSnapshotValidator<TSnapshotValue extends TSnapshot> = (
   value: unknown,
 ) => asserts value is TSnapshotValue;
@@ -62,7 +63,7 @@ function providerKey(storageKey: string, sessionId: string): string {
   return JSON.stringify([storageKey, sessionId]);
 }
 
-function assertProjectionSession(snapshot: IFlexProjectionSnapshot, sessionId: string): void {
+function assertProjectionSession(snapshot: TFlexProjectionSnapshot, sessionId: string): void {
   for (const message of snapshot.messages) {
     if (message.sessionId !== sessionId) {
       throw new FlexHarnessStoreFormatError(
@@ -350,12 +351,12 @@ class InMemoryScopeStore implements IFlexScopeStore {
 }
 
 class InMemoryProjectionStore implements IFlexProjectionStore {
-  private readonly snapshots = new Map<string, IFlexProjectionSnapshot>();
+  private readonly snapshots = new Map<string, TFlexProjectionSnapshot>();
 
   public async load(
     storageKey: string,
     sessionId: string,
-  ): Promise<IFlexProjectionSnapshot | undefined> {
+  ): Promise<TFlexProjectionSnapshot | undefined> {
     const key = providerKey(storageKey, sessionId);
     const snapshot = this.snapshots.get(key);
     return snapshot ? cloneSerializable(snapshot) : undefined;
@@ -364,7 +365,7 @@ class InMemoryProjectionStore implements IFlexProjectionStore {
   public async save(
     storageKey: string,
     sessionId: string,
-    snapshot: IFlexProjectionSnapshot,
+    snapshot: IFlexProjectionSnapshotV3,
     expectedRevision: number,
   ): Promise<void> {
     const key = providerKey(storageKey, sessionId);
@@ -972,7 +973,7 @@ class JsonProjectionStore implements IFlexProjectionStore {
   public async load(
     storageKey: string,
     sessionId: string,
-  ): Promise<IFlexProjectionSnapshot | undefined> {
+  ): Promise<TFlexProjectionSnapshot | undefined> {
     const filePath = this.root.sessionPath('projections', storageKey, sessionId);
     return JsonFileRoot.inQueue(filePath, async () => {
       const snapshot = await this.root.read(filePath, (value) => {
@@ -987,7 +988,7 @@ class JsonProjectionStore implements IFlexProjectionStore {
   public async save(
     storageKey: string,
     sessionId: string,
-    snapshot: IFlexProjectionSnapshot,
+    snapshot: IFlexProjectionSnapshotV3,
     expectedRevision: number,
   ): Promise<void> {
     const validated = validateSnapshotSave(snapshot, expectedRevision, assertFlexProjectionSnapshot);

package/ts/errors.ts

@@ -38,6 +38,31 @@ export class FlexHarnessSessionBusyError extends FlexHarnessError {
   }
 }
 
+export class FlexHarnessSlashCommandUnavailableError extends FlexHarnessError {
+  public readonly commandName: string;
+  public readonly unavailableReason: string;
+
+  constructor(commandName: string, unavailableReason: string) {
+    super(
+      'FLEX_SLASH_COMMAND_UNAVAILABLE',
+      `Slash command "/${commandName}" is unavailable: ${unavailableReason}`,
+    );
+    this.name = 'FlexHarnessSlashCommandUnavailableError';
+    this.commandName = commandName;
+    this.unavailableReason = unavailableReason;
+  }
+}
+
+export class FlexHarnessSlashCommandReentryError extends FlexHarnessError {
+  constructor(sessionId: string) {
+    super(
+      'FLEX_SLASH_COMMAND_REENTRY',
+      `Session "${sessionId}" cannot reenter slash command execution.`,
+    );
+    this.name = 'FlexHarnessSlashCommandReentryError';
+  }
+}
+
 export class FlexHarnessQueueFullError extends FlexHarnessError {
   constructor(message: string) {
     super('FLEX_QUEUE_FULL', message);

package/ts/index.ts

@@ -3,3 +3,7 @@ export * from './classes.stores.js';
 export * from './errors.js';
 export * from './interfaces.js';
 export { normalizeJsonValue } from './utils.json.js';
+export {
+  FLEX_SLASH_COMMAND_MAX_INPUT_BYTES,
+  parseSlashCommand,
+} from './utils.slashcommands.js';

package/ts/interfaces.ts

@@ -164,6 +164,109 @@ export interface IFlexPromptOptions {
   maxSteps?: number;
 }
 
+export interface IFlexSlashCommandInvocation {
+  input: string;
+  name: string;
+  rawArguments: string;
+  arguments: string[];
+}
+
+export interface IFlexSlashCommandNotCommandResult {
+  type: 'not-command';
+}
+
+export interface IFlexSlashCommandMalformedResult {
+  type: 'malformed';
+  reason: string;
+}
+
+export interface IFlexParsedSlashCommand extends IFlexSlashCommandInvocation {
+  type: 'parsed';
+}
+
+export type TFlexSlashCommandParseResult =
+  | IFlexSlashCommandNotCommandResult
+  | IFlexSlashCommandMalformedResult
+  | IFlexParsedSlashCommand;
+
+export type TFlexSlashCommandKind = 'builtin' | 'template' | 'handler';
+export type TFlexSlashCommandWorkspaceReversion = 'supported' | 'unsupported' | 'not-applicable';
+
+export interface IFlexSlashCommandDescriptor {
+  name: string;
+  description: string;
+  kind: TFlexSlashCommandKind;
+  hints: string[];
+  available: boolean;
+  unavailableReason?: string;
+  workspaceReversion: TFlexSlashCommandWorkspaceReversion;
+}
+
+export interface IFlexSlashCommandHandlerContext<TScope> {
+  readonly scopeId: string;
+  readonly scope: TScope;
+  readonly storageKey: string;
+  readonly sessionId: string;
+  readonly rawArguments: string;
+  readonly arguments: readonly string[];
+  readonly signal: AbortSignal;
+}
+
+export type TFlexSlashCommandHandler<TScope> = (
+  context: IFlexSlashCommandHandlerContext<TScope>,
+) => TJsonValue | void | Promise<TJsonValue | void>;
+
+export interface IFlexSlashCommandTemplateRegistration {
+  name: string;
+  description?: string;
+  template: string;
+  handler?: never;
+}
+
+export interface IFlexSlashCommandHandlerRegistration<TScope> {
+  name: string;
+  description?: string;
+  handler: TFlexSlashCommandHandler<TScope>;
+  template?: never;
+}
+
+export type TFlexSlashCommandRegistration<TScope> =
+  | IFlexSlashCommandTemplateRegistration
+  | IFlexSlashCommandHandlerRegistration<TScope>;
+
+export interface IFlexSlashCommandExecutionOptions extends IFlexPromptOptions {
+  signal?: AbortSignal;
+}
+
+export interface IFlexSlashCommandUnknownResult extends IFlexSlashCommandInvocation {
+  type: 'unknown';
+}
+
+export interface IFlexSlashCommandOperationResult {
+  type: 'operation';
+  name: string;
+}
+
+export interface IFlexSlashCommandHandlerResult {
+  type: 'handler-result';
+  name: string;
+  result: TJsonValue;
+}
+
+export interface IFlexSlashCommandPromptAdmissionResult {
+  type: 'prompt-admission';
+  name: string;
+  admission: IFlexPromptAdmission;
+}
+
+export type TFlexSlashCommandExecutionResult =
+  | IFlexSlashCommandNotCommandResult
+  | IFlexSlashCommandMalformedResult
+  | IFlexSlashCommandUnknownResult
+  | IFlexSlashCommandOperationResult
+  | IFlexSlashCommandHandlerResult
+  | IFlexSlashCommandPromptAdmissionResult;
+
 export type TFlexPromptQueueStatus =
   | 'queued'
   | 'starting'
@@ -349,13 +452,112 @@ export interface IFlexTerminalProjection {
   steps?: number;
 }
 
-export interface IFlexProjectionSnapshot {
+export interface IFlexProjectionSnapshotV1 {
   schemaVersion: 1;
   revision: number;
   messages: IFlexMessage[];
   stagedTerminals: IFlexTerminalProjection[];
 }
 
+export type TFlexReversionSegmentStatus = 'capturing' | 'completed' | 'failed' | 'cancelled';
+export type TFlexReversionProtocolVersion = 1 | 2;
+export type TFlexReversionProvenance = 'transcript' | 'workspace';
+export type TFlexReversionDisposition = 'pending' | 'revertible' | 'no-change' | 'nonrevertible';
+
+export interface IFlexAffectedWorkspace {
+  readonly id: string;
+  readonly label: string;
+}
+
+interface IFlexReversionSegmentV2 {
+  runId: string;
+  userMessageId: string;
+  status: TFlexReversionSegmentStatus;
+  contextAvailable: boolean;
+  eventIds: string[];
+  workspaceCaptured: boolean;
+  captureId?: string;
+  workspaceReference?: TJsonValue;
+}
+
+export interface IFlexReversionSegment extends IFlexReversionSegmentV2 {
+  protocolVersion: TFlexReversionProtocolVersion;
+  provenance: TFlexReversionProvenance;
+  disposition?: TFlexReversionDisposition;
+  affectedWorkspaces?: IFlexAffectedWorkspace[];
+  reasonCode?: string;
+}
+
+interface IFlexPendingCaptureReversionV2 {
+  kind: 'capture';
+  runId: string;
+  captureId: string;
+  state: 'preparing' | 'prepared' | 'finalizing';
+}
+
+export interface IFlexPendingCaptureReversion extends IFlexPendingCaptureReversionV2 {
+  protocolVersion: TFlexReversionProtocolVersion;
+}
+
+export interface IFlexPendingApplyReversion {
+  kind: 'apply';
+  operationId: string;
+  direction: 'undo' | 'redo';
+  fromCursor: number;
+  toCursor: number;
+  segmentRunIds: string[];
+  appliedRunIds: string[];
+}
+
+type TFlexPendingReversionV2 =
+  | IFlexPendingCaptureReversionV2
+  | IFlexPendingApplyReversion;
+
+export type TFlexPendingReversion =
+  | IFlexPendingCaptureReversion
+  | IFlexPendingApplyReversion;
+
+interface IFlexPendingReversionReleaseV2 {
+  runId: string;
+  captureId: string;
+  reference: TJsonValue;
+}
+
+export interface IFlexPendingReversionRelease extends IFlexPendingReversionReleaseV2 {
+  protocolVersion: TFlexReversionProtocolVersion;
+}
+
+export interface IFlexProjectionSnapshotV2 {
+  schemaVersion: 2;
+  revision: number;
+  messages: IFlexMessage[];
+  stagedTerminals: IFlexTerminalProjection[];
+  reversionSegments: IFlexReversionSegmentV2[];
+  revertCursor: number;
+  excludedRunIds: string[];
+  pendingReversion?: TFlexPendingReversionV2;
+  pendingReversionReleases: IFlexPendingReversionReleaseV2[];
+}
+
+export interface IFlexProjectionSnapshotV3 {
+  schemaVersion: 3;
+  revision: number;
+  messages: IFlexMessage[];
+  stagedTerminals: IFlexTerminalProjection[];
+  reversionSegments: IFlexReversionSegment[];
+  revertCursor: number;
+  excludedRunIds: string[];
+  pendingReversion?: TFlexPendingReversion;
+  pendingReversionReleases: IFlexPendingReversionRelease[];
+}
+
+export type IFlexProjectionSnapshot =
+  | IFlexProjectionSnapshotV1
+  | IFlexProjectionSnapshotV2
+  | IFlexProjectionSnapshotV3;
+export type TFlexProjectionSnapshot = IFlexProjectionSnapshot;
+export type IFlexProjectionSnapshotCurrent = IFlexProjectionSnapshotV3;
+
 export interface IFlexPermissionSnapshot {
   schemaVersion: 1;
   revision: number;
@@ -372,11 +574,11 @@ export interface IFlexScopeStore {
 }
 
 export interface IFlexProjectionStore {
-  load(storageKey: string, sessionId: string): Promise<IFlexProjectionSnapshot | undefined>;
+  load(storageKey: string, sessionId: string): Promise<TFlexProjectionSnapshot | undefined>;
   save(
     storageKey: string,
     sessionId: string,
-    snapshot: IFlexProjectionSnapshot,
+    snapshot: IFlexProjectionSnapshotCurrent,
     expectedRevision: number,
   ): Promise<void>;
   deleteSession(storageKey: string, sessionId: string): Promise<void>;
@@ -438,6 +640,164 @@ export interface IFlexPromptQueueLimits {
   maxTerminalEntriesPerSession?: number;
 }
 
+export interface IFlexReversionLimits {
+  maxCompletedTurns?: number;
+  maxSegments?: number;
+  maxExcludedRunIds?: number;
+  maxPendingReversionReleases?: number;
+}
+
+export const FLEX_REVERSION_DEFAULT_LIMITS = Object.freeze({
+  maxCompletedTurns: 100,
+  maxSegments: 300,
+  maxExcludedRunIds: 1000,
+  maxPendingReversionReleases: 1000,
+});
+
+export const FLEX_REVERSION_MAXIMUM_LIMITS = Object.freeze({
+  maxCompletedTurns: 1000,
+  maxSegments: 3000,
+  maxExcludedRunIds: 10_000,
+  maxPendingReversionReleases: 10_000,
+});
+
+export const FLEX_REVERSION_REFERENCE_MAX_BYTES = 256 * 1024;
+export const FLEX_REVERSION_MAX_AFFECTED_WORKSPACES = 64;
+export const FLEX_REVERSION_WORKSPACE_ID_MAX_BYTES = 512;
+export const FLEX_REVERSION_WORKSPACE_LABEL_MAX_BYTES = 2048;
+export const FLEX_REVERSION_REASON_CODE_MAX_BYTES = 128;
+
+export interface IFlexTurnReversionBaseContext<TScope> {
+  readonly scopeId: string;
+  readonly scope: TScope;
+  readonly storageKey: string;
+  readonly sessionId: string;
+  readonly runId: string;
+  readonly captureId: string;
+  readonly signal: AbortSignal;
+}
+
+export interface IFlexTurnReversionCaptureInspection {
+  status: 'missing' | 'prepared' | 'finalized' | 'unknown';
+  reference?: TJsonValue;
+}
+
+export interface IFlexTurnReversionApplyContext<TScope>
+  extends IFlexTurnReversionBaseContext<TScope> {
+  readonly reference: TJsonValue;
+  readonly operationId: string;
+  readonly direction: 'undo' | 'redo';
+}
+
+export interface IFlexTurnReversionApplyInspection {
+  status: 'not-applied' | 'applied' | 'unknown';
+}
+
+export interface IFlexTurnReversionReleaseContext<TScope>
+  extends IFlexTurnReversionBaseContext<TScope> {
+  readonly reference: TJsonValue;
+}
+
+export interface IFlexTurnReversionProvider<TScope> {
+  prepare(
+    context: IFlexTurnReversionBaseContext<TScope>,
+  ): Promise<void> | void;
+  inspectCapture(
+    context: IFlexTurnReversionBaseContext<TScope>,
+  ): Promise<IFlexTurnReversionCaptureInspection> | IFlexTurnReversionCaptureInspection;
+  finalize(
+    context: IFlexTurnReversionBaseContext<TScope>,
+  ): Promise<TJsonValue> | TJsonValue;
+  apply(
+    context: IFlexTurnReversionApplyContext<TScope>,
+  ): Promise<void> | void;
+  inspectApply(
+    context: IFlexTurnReversionApplyContext<TScope>,
+  ): Promise<IFlexTurnReversionApplyInspection> | IFlexTurnReversionApplyInspection;
+  release(
+    context: IFlexTurnReversionReleaseContext<TScope>,
+  ): Promise<void> | void;
+}
+
+export interface IFlexTurnReversionRevertibleOutcome {
+  readonly disposition: 'revertible';
+  readonly reference: TJsonValue;
+  readonly affectedWorkspaces: readonly IFlexAffectedWorkspace[];
+}
+
+export interface IFlexTurnReversionNoChangeOutcome {
+  readonly disposition: 'no-change';
+  readonly reference: TJsonValue;
+  readonly affectedWorkspaces?: readonly [];
+}
+
+export interface IFlexTurnReversionNonrevertibleOutcome {
+  readonly disposition: 'nonrevertible';
+  readonly reference: TJsonValue;
+  readonly reasonCode: string;
+  readonly affectedWorkspaces?: readonly IFlexAffectedWorkspace[];
+}
+
+export type TFlexTurnReversionFinalizedOutcome =
+  | IFlexTurnReversionRevertibleOutcome
+  | IFlexTurnReversionNoChangeOutcome
+  | IFlexTurnReversionNonrevertibleOutcome;
+
+export type TFlexTurnReversionCaptureInspectionV2 =
+  | { readonly status: 'missing' | 'prepared' | 'unknown' }
+  | {
+      readonly status: 'finalized';
+      readonly outcome: TFlexTurnReversionFinalizedOutcome;
+    };
+
+export interface IFlexTurnReversionProviderV2<TScope> {
+  readonly protocolVersion: 2;
+  prepare(
+    context: IFlexTurnReversionBaseContext<TScope>,
+  ): Promise<void> | void;
+  inspectCapture(
+    context: IFlexTurnReversionBaseContext<TScope>,
+  ): Promise<TFlexTurnReversionCaptureInspectionV2> | TFlexTurnReversionCaptureInspectionV2;
+  finalize(
+    context: IFlexTurnReversionBaseContext<TScope>,
+  ): Promise<TFlexTurnReversionFinalizedOutcome> | TFlexTurnReversionFinalizedOutcome;
+  apply(
+    context: IFlexTurnReversionApplyContext<TScope>,
+  ): Promise<void> | void;
+  inspectApply(
+    context: IFlexTurnReversionApplyContext<TScope>,
+  ): Promise<IFlexTurnReversionApplyInspection> | IFlexTurnReversionApplyInspection;
+  release(
+    context: IFlexTurnReversionReleaseContext<TScope>,
+  ): Promise<void> | void;
+}
+
+export type TFlexReversionPolicy = 'transcript-optional' | 'workspace-required';
+
+export type TFlexSessionReversionGroupKind = 'candidate' | 'barrier' | 'no-change';
+
+export interface IFlexSessionReversionGroup {
+  readonly runId: string;
+  readonly kind: TFlexSessionReversionGroupKind;
+  readonly visibility: 'visible' | 'hidden';
+  readonly affectedWorkspaces: readonly IFlexAffectedWorkspace[];
+  readonly affectedWorkspacesTruncated: boolean;
+}
+
+export interface IFlexSessionReversionInfo {
+  readonly undoAvailable: boolean;
+  readonly redoAvailable: boolean;
+  readonly groups: readonly IFlexSessionReversionGroup[];
+}
+
+export interface IFlexUndoSessionResult {
+  revertedRunId: string;
+}
+
+export interface IFlexRedoSessionResult {
+  restoredRunId: string;
+}
+
 export type TFlexExternalErrorSource =
   | 'modelResolver'
   | 'toolProvider'
@@ -445,7 +805,9 @@ export type TFlexExternalErrorSource =
   | 'toolCallback'
   | 'toolCleanup'
   | 'agentSession'
-  | 'persistence';
+  | 'persistence'
+  | 'slashCommand'
+  | 'turnReversion';
 
 export interface IFlexExternalErrorContext {
   source: TFlexExternalErrorSource;
@@ -524,8 +886,12 @@ export interface IFlexHarnessOptions<TScope> {
   toolOutputLimits?: IFlexJsonLimits;
   callbackLimits?: IFlexCallbackLimits;
   promptQueueLimits?: IFlexPromptQueueLimits;
+  reversionLimits?: IFlexReversionLimits;
+  turnReversionProvider?: IFlexTurnReversionProvider<TScope> | IFlexTurnReversionProviderV2<TScope>;
+  reversionPolicy?: TFlexReversionPolicy;
   externalErrorProjector?: TFlexExternalErrorProjector;
   subagents?: IFlexSubagentDefinition[];
+  slashCommands?: readonly TFlexSlashCommandRegistration<TScope>[];
   maxSubagentDepth?: number;
   maxSubagentCallsPerRun?: number;
 }
@@ -645,6 +1011,12 @@ export interface IFlexPromptQueueEvent extends IFlexEventBase {
   readonly entry: IFlexPromptQueueEntry;
 }
 
+export interface IFlexSessionHistoryChangedEvent extends IFlexEventBase {
+  readonly type: 'session.history.changed';
+  readonly direction: 'undo' | 'redo' | 'branch';
+  readonly runId?: string;
+}
+
 export interface IFlexErrorInfo {
   name: string;
   message: string;
@@ -661,6 +1033,7 @@ export type TFlexHarnessEvent =
   | IFlexPermissionRequestedEvent
   | IFlexPermissionResolvedEvent
   | IFlexRunFinishedEvent
-  | IFlexPromptQueueEvent;
+  | IFlexPromptQueueEvent
+  | IFlexSessionHistoryChangedEvent;
 
 export type TFlexHarnessEventListener = (event: TFlexHarnessEvent) => void;

package/ts/plugins.ts

@@ -13,6 +13,7 @@ import {
   buildModelMessages,
   ToolJobStoreConflictError,
   createAgentEvent,
+  filterModelVisibleAgentEvents,
   getAgentGenerationTransactions,
   modelMessagesToAgentEvents,
   tool,
@@ -27,6 +28,7 @@ export {
   buildModelMessages,
   ToolJobStoreConflictError,
   createAgentEvent,
+  filterModelVisibleAgentEvents,
   getAgentGenerationTransactions,
   modelMessagesToAgentEvents,
   tool,