@modelprofile.com/flexharness 2.1.0 → 3.0.1

package/ts/errors.ts

@@ -97,6 +97,26 @@ export class FlexHarnessStoreFormatError extends FlexHarnessError {
   }
 }
 
+export class FlexHarnessStoreCommitUncertainError extends FlexHarnessError {
+  public readonly path: string;
+  public readonly operation: 'write' | 'delete-file' | 'delete-directory';
+
+  constructor(
+    path: string,
+    operation: 'write' | 'delete-file' | 'delete-directory',
+    options: ErrorOptions,
+  ) {
+    super(
+      'FLEX_STORE_COMMIT_UNCERTAIN',
+      `Store ${operation} at "${path}" may have committed but could not be durably confirmed.`,
+      options,
+    );
+    this.name = 'FlexHarnessStoreCommitUncertainError';
+    this.path = path;
+    this.operation = operation;
+  }
+}
+
 export class FlexHarnessRunError extends AggregateError {
   public readonly code = 'FLEX_RUN_FAILED';
 

package/ts/interfaces.ts

@@ -8,17 +8,16 @@ export interface IJsonObject {
 
 export type TJsonValue = TJsonPrimitive | IJsonObject | TJsonValue[];
 
-export type TFlexAgentRunOptions = plugins.IAgentRunOptions;
+export type TFlexAgentSessionOptions = plugins.IAgentSessionOptions;
 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 TFlexAgentModel = NonNullable<TFlexAgentSessionOptions['model']>;
+export type TFlexAgentPrompt = Parameters<plugins.IAgentSession['beginGeneration']>[0];
+export type TFlexAgentModelMessage = ReturnType<plugins.IAgentSession['getModelMessages']>[number];
+export type TFlexAgentToolSet = NonNullable<TFlexAgentSessionOptions['tools']>;
+export type TFlexAgentProviderOptions = TFlexAgentSessionOptions['providerOptions'];
+export type TFlexAgentCacheSetting = TFlexAgentSessionOptions['cache'];
 export type TFlexAgentToolCallFinishEvent = Parameters<
-  NonNullable<TFlexAgentRunOptions['onToolCallFinish']>
+  NonNullable<TFlexAgentSessionOptions['onToolCallFinish']>
 >[0];
 
 export interface IFlexTextPromptPart {
@@ -60,6 +59,7 @@ export interface IFlexModelIdentity {
 
 export type TFlexActivityStatus =
   | 'idle'
+  | 'scheduled'
   | 'running'
   | 'waiting_permission'
   | 'failed'
@@ -173,6 +173,14 @@ export interface IFlexPromptAdmission {
   completion: Promise<IFlexPromptResult>;
 }
 
+export interface IFlexSchedulePromptOptions extends IFlexPromptOptions {
+  debounceMs?: number;
+}
+
+export interface IFlexScheduledPromptAdmission extends IFlexPromptAdmission {
+  scheduleKey: string;
+}
+
 export interface IFlexMessagePageOptions {
   limit?: number;
   before?: string;
@@ -254,26 +262,97 @@ export interface IFlexToolProvider<TScope> {
   ): Promise<IFlexToolHandle | undefined> | IFlexToolHandle | undefined;
 }
 
-export interface IFlexStoredSessionSnapshot {
-  session: IFlexSession;
+export interface IFlexSessionTombstone {
+  sessionId: string;
+  deletedAt: string;
+}
+
+export interface IFlexScopeSnapshot {
+  schemaVersion: 1;
+  revision: number;
+  sessions: IFlexSession[];
+  tombstones: IFlexSessionTombstone[];
+}
+
+export interface IFlexTerminalProjection {
+  runId: string;
+  status: 'completed' | 'failed' | 'cancelled';
+  userMessage: IFlexMessage;
+  assistantMessage: IFlexMessage;
+  model?: IFlexModelIdentity;
+  usage?: IFlexUsage;
+  finishReason?: string;
+  steps?: number;
+}
+
+export interface IFlexProjectionSnapshot {
+  schemaVersion: 1;
+  revision: number;
   messages: IFlexMessage[];
-  modelHistory: TJsonValue[];
-  rememberedPermissionKeys: string[];
+  stagedTerminals: IFlexTerminalProjection[];
 }
 
-export interface IFlexHarnessSnapshot {
+export interface IFlexPermissionSnapshot {
   schemaVersion: 1;
   revision: number;
-  sessions: IFlexStoredSessionSnapshot[];
+  rememberedPermissionKeys: string[];
+}
+
+export interface IFlexScopeStore {
+  load(storageKey: string): Promise<IFlexScopeSnapshot | undefined>;
+  save(
+    storageKey: string,
+    snapshot: IFlexScopeSnapshot,
+    expectedRevision: number,
+  ): Promise<void>;
 }
 
-export interface IFlexHarnessStore {
-  load(storageKey: string): Promise<IFlexHarnessSnapshot | undefined>;
+export interface IFlexProjectionStore {
+  load(storageKey: string, sessionId: string): Promise<IFlexProjectionSnapshot | undefined>;
   save(
     storageKey: string,
-    snapshot: IFlexHarnessSnapshot,
+    sessionId: string,
+    snapshot: IFlexProjectionSnapshot,
     expectedRevision: number,
   ): Promise<void>;
+  deleteSession(storageKey: string, sessionId: string): Promise<void>;
+}
+
+export interface IFlexPermissionStore {
+  load(storageKey: string, sessionId: string): Promise<IFlexPermissionSnapshot | undefined>;
+  save(
+    storageKey: string,
+    sessionId: string,
+    snapshot: IFlexPermissionSnapshot,
+    expectedRevision: number,
+  ): Promise<void>;
+  deleteSession(storageKey: string, sessionId: string): Promise<void>;
+}
+
+export interface IFlexAgentEventStoreProvider {
+  getStore(
+    storageKey: string,
+    sessionId: string,
+  ): Promise<plugins.IAgentEventStoreV2> | plugins.IAgentEventStoreV2;
+  releaseSession?(storageKey: string, sessionId: string): Promise<void> | void;
+  deleteSession(storageKey: string, sessionId: string): Promise<void>;
+}
+
+export interface IFlexToolJobStoreProvider {
+  getStore(
+    storageKey: string,
+    sessionId: string,
+  ): Promise<plugins.IToolJobStore> | plugins.IToolJobStore;
+  releaseSession?(storageKey: string, sessionId: string): Promise<void> | void;
+  deleteSession(storageKey: string, sessionId: string): Promise<void>;
+}
+
+export interface IFlexHarnessStores {
+  scopes: IFlexScopeStore;
+  projections: IFlexProjectionStore;
+  permissions: IFlexPermissionStore;
+  agentEvents: IFlexAgentEventStoreProvider;
+  jobs: IFlexToolJobStoreProvider;
 }
 
 export interface IFlexJsonLimits {
@@ -290,10 +369,10 @@ export interface IFlexCallbackLimits {
 export type TFlexExternalErrorSource =
   | 'modelResolver'
   | 'toolProvider'
-  | 'runner'
   | 'toolExecution'
   | 'toolCallback'
   | 'toolCleanup'
+  | 'agentSession'
   | 'persistence';
 
 export interface IFlexExternalErrorContext {
@@ -308,17 +387,84 @@ export type TFlexExternalErrorProjector = (
   context: IFlexExternalErrorContext,
 ) => IFlexErrorInfo;
 
+export interface IFlexExecutionContextProviderContext<TScope> {
+  scopeId: string;
+  scope: TScope;
+  storageKey: string;
+  sessionId: string;
+  jobStore: plugins.IToolJobStore;
+}
+
+export interface IFlexExecutionContextHandle {
+  context: plugins.IToolExecutionContext;
+  close?(): Promise<void> | void;
+}
+
+export interface IFlexExecutionContextProvider<TScope> {
+  provideExecutionContext(
+    context: IFlexExecutionContextProviderContext<TScope>,
+  ): Promise<IFlexExecutionContextHandle | undefined> | IFlexExecutionContextHandle | undefined;
+}
+
+export interface IFlexAgentSessionPolicy {
+  contextBuilder?: plugins.TAgentContextBuilder;
+  contextCompactor?: plugins.TAgentContextCompactor;
+  eventRetention?: TFlexAgentSessionOptions['eventRetention'];
+  changeListenerTimeoutMs?: number;
+  maxPendingSessionChanges?: number;
+  generationLeaseCleanupTimeoutMs?: number;
+  maxArchivedTransactionTombstones?: number;
+  maxContextOverflowRetries?: number;
+}
+
 export interface IFlexHarnessOptions<TScope> {
   scopeResolver: IFlexScopeResolver<TScope>;
   modelResolver: IFlexModelResolver<TScope>;
   toolProvider?: IFlexToolProvider<TScope>;
-  store?: IFlexHarnessStore;
-  runner?: TFlexAgentRunner;
+  executionContextProvider?: IFlexExecutionContextProvider<TScope>;
+  stores?: IFlexHarnessStores;
+  agentSessionPolicy?: IFlexAgentSessionPolicy;
   toolOutputLimits?: IFlexJsonLimits;
   callbackLimits?: IFlexCallbackLimits;
   externalErrorProjector?: TFlexExternalErrorProjector;
 }
 
+export interface IFlexUncertainToolExecution {
+  intentId: string;
+  generationId: string;
+  toolCallId: string;
+  toolName: string;
+  input: TJsonValue;
+  timestamp: string;
+}
+
+export type TFlexToolExecutionReconciliation =
+  | {
+      resolution: 'executed';
+      output: TJsonValue;
+    }
+  | {
+      resolution: 'not-executed' | 'abandoned-unknown';
+      error?: string;
+    };
+
+export interface IFlexBackgroundExecution {
+  executionId: string;
+  type: string;
+  state: 'running' | 'finished' | 'failed' | 'aborted';
+  exitCode?: number | null;
+  startedAt?: string;
+  updatedAt?: string;
+  finishedAt?: string;
+}
+
+export interface IFlexEventArchiveMetadata {
+  archiveId: string;
+  sessionId: string;
+  createdAt: string;
+  eventCount: number;
+}
+
 export interface IFlexEventBase {
   readonly eventId: string;
   readonly sequence: number;
@@ -343,7 +489,7 @@ export interface IFlexSessionDeletedEvent extends IFlexEventBase {
 }
 
 export interface IFlexRunStartedEvent extends IFlexEventBase {
-  readonly type: 'run.started';
+  readonly type: 'run.started' | 'run.scheduled';
   readonly runId: string;
   readonly messageId: string;
   readonly session: IFlexSession;

package/ts/plugins.ts

@@ -6,10 +6,53 @@ import * as path from 'node:path';
 export { crypto, fs, path };
 
 // @push.rocks scope
-import { runAgent } from '@push.rocks/smartagent';
+import {
+  AgentEventStoreConflictError,
+  AgentSession,
+  buildModelMessages,
+  ToolJobStoreConflictError,
+  createAgentEvent,
+  getAgentGenerationTransactions,
+  modelMessagesToAgentEvents,
+  validateAgentEventArchiveV2,
+  validateAgentEventSnapshotV2,
+} from '@push.rocks/smartagent';
 
-export { runAgent };
+export {
+  AgentEventStoreConflictError,
+  AgentSession,
+  buildModelMessages,
+  ToolJobStoreConflictError,
+  createAgentEvent,
+  getAgentGenerationTransactions,
+  modelMessagesToAgentEvents,
+  validateAgentEventArchiveV2,
+  validateAgentEventSnapshotV2,
+};
 export type {
-  IAgentRunOptions,
+  IAgentEventArchiveV2,
+  IAgentEventSnapshotV2,
+  IAgentEventStoreV2,
+  IAgentGenerateResult,
+  IAgentGenerationHandle,
+  IAgentGenerationLease,
   IAgentRunResult,
+  IAgentSession,
+  IAgentSessionOptions,
+  IAgentRuntimeEventPayload,
+  IGenerationBegunEvent,
+  IGenerationExecutionCompletedEvent,
+  IGenerationExecutionStartedEvent,
+  IGenerationOutcomeEvent,
+  IToolExecutionContext,
+  IToolExecutionIntentEvent,
+  IToolJobSnapshot,
+  IToolJobState,
+  IToolJobStore,
+  TAgentContextBuilder,
+  TAgentContextCompactor,
+  TAgentEvent,
+  TAgentGenerationOutcome,
+  TAgentToolCallFinishEvent,
+  TAgentToolExecutionReconciliationOptions,
 } from '@push.rocks/smartagent';