@modelprofile.com/flexharness 3.7.0 → 4.0.0

package/ts/interfaces.ts

@@ -135,6 +135,8 @@ export interface IFlexSessionActivity {
 export interface IFlexSession {
   scopeId: string;
   sessionId: string;
+  sessionGenerationId?: string;
+  sessionGenerationSequence?: number;
   title?: string;
   createdAt: string;
   updatedAt: string;
@@ -428,6 +430,8 @@ export interface IFlexResourceToolProviderResolver<TScope> {
 
 export interface IFlexSessionTombstone {
   sessionId: string;
+  sessionGenerationId?: string;
+  sessionGenerationSequence?: number;
   deletedAt: string;
   rootSessionId?: string;
   depth?: number;
@@ -460,8 +464,16 @@ export interface IFlexProjectionSnapshotV1 {
 }
 
 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 IFlexReversionSegment {
+export interface IFlexAffectedWorkspace {
+  readonly id: string;
+  readonly label: string;
+}
+
+interface IFlexReversionSegmentV2 {
   runId: string;
   userMessageId: string;
   status: TFlexReversionSegmentStatus;
@@ -472,13 +484,25 @@ export interface IFlexReversionSegment {
   workspaceReference?: TJsonValue;
 }
 
-export interface IFlexPendingCaptureReversion {
+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;
@@ -489,21 +513,41 @@ export interface IFlexPendingApplyReversion {
   appliedRunIds: string[];
 }
 
+type TFlexPendingReversionV2 =
+  | IFlexPendingCaptureReversionV2
+  | IFlexPendingApplyReversion;
+
 export type TFlexPendingReversion =
   | IFlexPendingCaptureReversion
   | IFlexPendingApplyReversion;
 
-export interface IFlexPendingReversionRelease {
+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[];
@@ -511,9 +555,12 @@ export interface IFlexProjectionSnapshotV2 {
   pendingReversionReleases: IFlexPendingReversionRelease[];
 }
 
-export type IFlexProjectionSnapshot = IFlexProjectionSnapshotV1 | IFlexProjectionSnapshotV2;
+export type IFlexProjectionSnapshot =
+  | IFlexProjectionSnapshotV1
+  | IFlexProjectionSnapshotV2
+  | IFlexProjectionSnapshotV3;
 export type TFlexProjectionSnapshot = IFlexProjectionSnapshot;
-export type IFlexProjectionSnapshotCurrent = IFlexProjectionSnapshotV2;
+export type IFlexProjectionSnapshotCurrent = IFlexProjectionSnapshotV3;
 
 export interface IFlexPermissionSnapshot {
   schemaVersion: 1;
@@ -521,6 +568,118 @@ export interface IFlexPermissionSnapshot {
   rememberedPermissionKeys: string[];
 }
 
+export const FLEX_PROJECT_MANAGEMENT_SCHEMA_VERSION = 1 as const;
+export const FLEX_SESSION_GENERATION_ID_MAX_BYTES = 128;
+
+export const FLEX_PROJECT_MANAGEMENT_LIMITS = Object.freeze({
+  maxGoalBytes: 8 * 1024,
+  maxScratchpadBytes: 64 * 1024,
+  maxTaskContentBytes: 8 * 1024,
+  maxTaskIdBytes: 512,
+  maxTasks: 512,
+  maxTitleBytes: 2048,
+  maxSnapshotBytes: 96 * 1024,
+});
+
+export type TFlexProjectTaskStatus = 'pending' | 'in_progress' | 'completed' | 'cancelled';
+export type TFlexProjectTaskPriority = 'high' | 'medium' | 'low';
+
+export interface IFlexProjectTask {
+  id: string;
+  content: string;
+  status: TFlexProjectTaskStatus;
+  priority: TFlexProjectTaskPriority;
+  createdAt: string;
+  updatedAt: string;
+}
+
+export interface IFlexProjectManagementSnapshot {
+  schemaVersion: 1;
+  revision: number;
+  sessionGenerationId: string;
+  sessionGenerationSequence: number;
+  goal?: string;
+  scratchpad: string;
+  tasks: IFlexProjectTask[];
+}
+
+export interface IFlexProjectManagementTombstone {
+  schemaVersion: 1;
+  revision: number;
+  sessionGenerationId: string;
+  sessionGenerationSequence: number;
+  deletedAt: string;
+}
+
+export type TFlexProjectManagementRecord =
+  | IFlexProjectManagementSnapshot
+  | IFlexProjectManagementTombstone;
+
+export type TFlexProjectManagementWriteActor = 'agent' | 'application';
+
+export interface IFlexProjectManagementWriteContext {
+  actor: TFlexProjectManagementWriteActor;
+  runId?: string;
+  agent?: string;
+  toolCallId?: string;
+}
+
+export interface IFlexProjectManagementStore {
+  load(
+    storageKey: string,
+    sessionId: string,
+  ): Promise<TFlexProjectManagementRecord | undefined>;
+  save(
+    storageKey: string,
+    sessionId: string,
+    snapshot: IFlexProjectManagementSnapshot,
+    expectedRevision: number,
+    writeContext: IFlexProjectManagementWriteContext,
+  ): Promise<void>;
+  tombstoneSession(
+    storageKey: string,
+    sessionId: string,
+    tombstone: IFlexProjectManagementTombstone,
+    expectedRevision: number,
+  ): Promise<void>;
+  purgeNamespace(storageKey: string): Promise<void>;
+}
+
+export interface IFlexCreateProjectTaskInput {
+  id: string;
+  content: string;
+  status?: TFlexProjectTaskStatus;
+  priority?: TFlexProjectTaskPriority;
+}
+
+export interface IFlexUpdateProjectTaskInput {
+  id: string;
+  content?: string;
+  status?: TFlexProjectTaskStatus;
+  priority?: TFlexProjectTaskPriority;
+}
+
+export interface IFlexProjectStateResult {
+  revision: number;
+  state: IFlexProjectManagementSnapshot;
+}
+
+export interface IFlexProjectTaskResult extends IFlexProjectStateResult {
+  task: IFlexProjectTask;
+}
+
+export interface IFlexProjectTasksResult extends IFlexProjectStateResult {
+  tasks: IFlexProjectTask[];
+}
+
+export interface IFlexProjectGoalResult extends IFlexProjectStateResult {
+  goal: string | null;
+}
+
+export interface IFlexProjectScratchpadResult extends IFlexProjectStateResult {
+  scratchpad: string;
+}
+
 export interface IFlexScopeStore {
   load(storageKey: string): Promise<IFlexScopeSnapshot | undefined>;
   save(
@@ -574,6 +733,7 @@ export interface IFlexHarnessStores {
   scopes: IFlexScopeStore;
   projections: IFlexProjectionStore;
   permissions: IFlexPermissionStore;
+  projectManagement: IFlexProjectManagementStore;
   agentEvents: IFlexAgentEventStoreProvider;
   jobs: IFlexToolJobStoreProvider;
 }
@@ -619,6 +779,10 @@ export const FLEX_REVERSION_MAXIMUM_LIMITS = Object.freeze({
 });
 
 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;
@@ -672,6 +836,77 @@ export interface IFlexTurnReversionProvider<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;
 }
@@ -757,6 +992,17 @@ export interface IFlexSubagentDefinition {
   maxSteps?: number;
 }
 
+export interface IFlexProjectManagementBuiltInToolsOptions {
+  task?: boolean;
+  goal?: boolean;
+  scratchpad?: boolean;
+}
+
+export interface IFlexBuiltInToolsOptions {
+  renameSession?: boolean;
+  projectManagement?: IFlexProjectManagementBuiltInToolsOptions;
+}
+
 export interface IFlexHarnessOptions<TScope> {
   scopeResolver: IFlexScopeResolver<TScope>;
   modelResolver: IFlexModelResolver<TScope>;
@@ -769,9 +1015,11 @@ export interface IFlexHarnessOptions<TScope> {
   callbackLimits?: IFlexCallbackLimits;
   promptQueueLimits?: IFlexPromptQueueLimits;
   reversionLimits?: IFlexReversionLimits;
-  turnReversionProvider?: IFlexTurnReversionProvider<TScope>;
+  turnReversionProvider?: IFlexTurnReversionProvider<TScope> | IFlexTurnReversionProviderV2<TScope>;
+  reversionPolicy?: TFlexReversionPolicy;
   externalErrorProjector?: TFlexExternalErrorProjector;
   subagents?: IFlexSubagentDefinition[];
+  builtInTools?: IFlexBuiltInToolsOptions;
   slashCommands?: readonly TFlexSlashCommandRegistration<TScope>[];
   maxSubagentDepth?: number;
   maxSubagentCallsPerRun?: number;