@modelprofile.com/flexharness 10.24.0 → 10.24.1

package/dist_ts/classes.flexharness.core.d.ts

@@ -0,0 +1,143 @@
+import * as plugins from './plugins.js';
+import { FlexHarnessAbortError } from './errors.js';
+import type { IFlexAgentSessionPolicy, IFlexCallbackLimits, IFlexHarnessOptions, IFlexHarnessStores, IFlexMessage, IFlexPartSnapshotEvent, IFlexPromptQueueLimits, IFlexProjectionSnapshotCurrent, IFlexReversionLimits, IFlexResolvedScope, IFlexSession, IFlexSessionImportLimits, IFlexSubagentDefinition, IFlexToolCatalogOptions, IJsonObject, TFlexExternalErrorSource, TFlexHarnessEventListener, TFlexMessagePart, TFlexProjectionSnapshot, TFlexReversionPolicy } from './interfaces.js';
+import { type INormalizedBuiltInTools, type TRegisteredSlashCommand } from './utils.harnessoptions.js';
+import type { TCanonicalOutcome, IStoredSessionState, IStorageState, IActiveRun, IScopeAdmissionState, IFlexMessageCursor, TEventDetails } from './interfaces.flexharness.js';
+import { FlexHarnessResults } from './classes.flexharness.results.js';
+import { FlexHarnessToolDispatch } from './classes.flexharness.tooldispatch.js';
+import { FlexHarnessToolProviders } from './classes.flexharness.providers.js';
+import { FlexHarnessCompaction } from './classes.flexharness.compaction.js';
+import { FlexHarnessSessionConfigurations } from './classes.flexharness.configurations.js';
+import { FlexHarnessPermissions } from './classes.flexharness.permissions.js';
+import { FlexHarnessRunCallbacks } from './classes.flexharness.callbacks.js';
+import { FlexHarnessDelegatedRunAdmission } from './classes.flexharness.admission.js';
+import { FlexHarnessProjectManagement } from './classes.flexharness.projects.js';
+import { FlexHarnessSessionImports } from './classes.flexharness.imports.js';
+import { FlexHarnessSlashCommands } from './classes.flexharness.slashcommands.js';
+import { FlexHarnessSubagents } from './classes.flexharness.subagents.js';
+import { FlexHarnessPromptQueue } from './classes.flexharness.prompts.js';
+import { FlexHarnessReversions } from './classes.flexharness.reversions.js';
+import { FlexHarnessSessionDeletion } from './classes.flexharness.deletion.js';
+import { FlexHarnessLifecycle } from './classes.flexharness.lifecycle.js';
+import { FlexHarnessRuns } from './classes.flexharness.runs.js';
+import { FlexHarnessSessions } from './classes.flexharness.sessions.js';
+/**
+ * The engine behind {@link FlexHarness}: its options, scope state, events and error projection, and
+ * the services that implement its API.
+ */
+export declare class FlexHarnessCore<TScope> {
+    readonly scopeResolver: IFlexHarnessOptions<TScope>['scopeResolver'];
+    readonly modelResolver: IFlexHarnessOptions<TScope>['modelResolver'];
+    readonly sessionConfigurationResolver: IFlexHarnessOptions<TScope>['sessionConfigurationResolver'];
+    readonly toolProvider: IFlexHarnessOptions<TScope>['toolProvider'];
+    readonly resourceToolProviderResolver: IFlexHarnessOptions<TScope>['resourceToolProviderResolver'];
+    private readonly executionContextProvider;
+    readonly delegatedRunAdmissionProvider: IFlexHarnessOptions<TScope>['delegatedRunAdmissionProvider'];
+    readonly stores: IFlexHarnessStores;
+    readonly agentSessionPolicy: IFlexAgentSessionPolicy<TScope>;
+    readonly toolOutputLimits: Required<NonNullable<IFlexHarnessOptions<TScope>['toolOutputLimits']>>;
+    readonly callbackLimits: Required<IFlexCallbackLimits>;
+    readonly promptQueueLimits: Required<IFlexPromptQueueLimits>;
+    readonly reversionLimits: Required<IFlexReversionLimits>;
+    readonly sessionImportLimits: Required<IFlexSessionImportLimits>;
+    readonly reversionMaintenanceTimeoutMs: number;
+    readonly turnReversionProvider: IFlexHarnessOptions<TScope>['turnReversionProvider'];
+    readonly reversionPolicy: TFlexReversionPolicy;
+    private readonly externalErrorProjector?;
+    readonly subagents: ReadonlyMap<string, Readonly<IFlexSubagentDefinition>>;
+    readonly builtInTools: INormalizedBuiltInTools;
+    readonly toolCatalogOptions: Readonly<IFlexToolCatalogOptions>;
+    readonly slashCommands: ReadonlyMap<string, TRegisteredSlashCommand<TScope>>;
+    readonly maxSubagentDepth: number;
+    readonly maxSubagentCallsPerRun: number;
+    readonly stateLoads: Map<string, Promise<IStorageState>>;
+    readonly scopeAdmissions: Map<string, IScopeAdmissionState>;
+    readonly listeners: Set<TFlexHarnessEventListener>;
+    readonly trustedInternalErrors: WeakSet<object>;
+    sequence: number;
+    closed: boolean;
+    readonly results: FlexHarnessResults<TScope>;
+    readonly toolDispatch: FlexHarnessToolDispatch<TScope>;
+    readonly providers: FlexHarnessToolProviders<TScope>;
+    readonly compaction: FlexHarnessCompaction<TScope>;
+    readonly configurations: FlexHarnessSessionConfigurations<TScope>;
+    readonly permissions: FlexHarnessPermissions<TScope>;
+    readonly callbacks: FlexHarnessRunCallbacks<TScope>;
+    readonly admission: FlexHarnessDelegatedRunAdmission<TScope>;
+    readonly projects: FlexHarnessProjectManagement<TScope>;
+    readonly imports: FlexHarnessSessionImports<TScope>;
+    readonly commands: FlexHarnessSlashCommands<TScope>;
+    readonly subagentTasks: FlexHarnessSubagents<TScope>;
+    readonly prompts: FlexHarnessPromptQueue<TScope>;
+    readonly reversions: FlexHarnessReversions<TScope>;
+    readonly deletion: FlexHarnessSessionDeletion<TScope>;
+    readonly lifecycle: FlexHarnessLifecycle<TScope>;
+    readonly runs: FlexHarnessRuns<TScope>;
+    readonly sessions: FlexHarnessSessions<TScope>;
+    constructor(options: IFlexHarnessOptions<TScope>);
+    /**
+     * Opens a section that changes what a view of the session shows and emits the events that
+     * describe the change. Closing is idempotent; close it once the events are emitted or the
+     * change is rolled back.
+     */
+    openPublication(state: IStorageState, sessionId: string): () => void;
+    subscribe(listener: TFlexHarnessEventListener): () => void;
+    projectExternalError(run: IActiveRun, error: unknown, source: TFlexExternalErrorSource): Error;
+    projectOperationError(error: unknown, source: TFlexExternalErrorSource, scopeId: string, sessionId: string, runId: string): Error;
+    trustInternalError<TError extends Error>(error: TError): TError;
+    canonicalOutcomes(events: readonly plugins.TAgentEvent[]): Map<string, TCanonicalOutcome>;
+    durableCanonicalOutcomes(stored: IStoredSessionState): Promise<Map<string, TCanonicalOutcome>>;
+    private loadState;
+    createUninitializedStoredSession(session: IFlexSession, storageKey: string, compactorLifecycleController?: AbortController): IStoredSessionState;
+    loadSessionRuntime(state: IStorageState, metadata: IFlexSession, scopeId: string, scope: TScope, compactorLifecycleController?: AbortController, newSession?: boolean): Promise<IStoredSessionState>;
+    private repairLoadedSession;
+    private repairTerminal;
+    withScopeMutationOwnership<TValue>(state: IStorageState, operation: () => TValue | Promise<TValue>): Promise<TValue>;
+    mutateScope<TValue>(state: IStorageState, mutation: () => TValue, allowDuringDrain?: boolean): Promise<TValue>;
+    mutateScopeOwned<TValue>(state: IStorageState, mutation: () => TValue): Promise<TValue>;
+    mutateProjection<TValue>(state: IStorageState, stored: IStoredSessionState, mutation: () => TValue, _allowDuringDrain?: boolean): Promise<TValue>;
+    private createScopeSnapshot;
+    private createProjectionSnapshot;
+    upgradeProjectionSnapshot(projection: TFlexProjectionSnapshot): IFlexProjectionSnapshotCurrent;
+    reconcileProjectionFromStore(stored: IStoredSessionState): Promise<void>;
+    sessionsAreDependencyRelated(state: IStorageState, leftSessionId: string, rightSessionId: string): boolean;
+    isSessionAncestor(state: IStorageState, ancestorSessionId: string, descendantSessionId: string): boolean;
+    sessionAncestryDepth(state: IStorageState, sessionId: string): number;
+    private sessionParentSessionId;
+    private sessionMetadata;
+    appendUnexpectedErrors(target: unknown[], error: unknown): void;
+    resolveState(scopeId: string): Promise<{
+        scope: IFlexResolvedScope<TScope>;
+        state: IStorageState;
+    }>;
+    getScopeAdmission(scopeId: string): IScopeAdmissionState;
+    pruneScopeAdmission(scopeId: string, admission: IScopeAdmissionState): void;
+    createScopeRetirementError(): FlexHarnessAbortError;
+    assertStateAcceptingWork(state: IStorageState): void;
+    requireSession(state: IStorageState, sessionId: string): IStoredSessionState;
+    visibleMessages(stored: IStoredSessionState): IFlexMessage[];
+    requireMutableSession(state: IStorageState, sessionId: string): IStoredSessionState;
+    /** Refuses an operation that would change an imported session's history or model context. */
+    assertSessionWritable(stored: IStoredSessionState): void;
+    /** An imported session never ran here, so it has no hidden stage and no reversion state. */
+    private assertImportedSessionState;
+    requireMessage(stored: IStoredSessionState, messageId: string): IFlexMessage;
+    isTombstoned(run: IActiveRun): boolean;
+    emitPartEvent(run: IActiveRun, type: IFlexPartSnapshotEvent['type'], part: TFlexMessagePart): void;
+    emitPartDeltaEvent(run: IActiveRun, part: Extract<TFlexMessagePart, {
+        type: 'text' | 'reasoning';
+    }>, delta: string, accounting: {
+        baseTextUtf8Bytes: number;
+        textUtf8Bytes: number;
+    }): void;
+    private partEventCoordinates;
+    emitEvent(scopeId: string, sourceSession: IFlexSession, details: TEventDetails): void;
+    validateRuntimeEvent(event: unknown): asserts event is IJsonObject & {
+        type: string;
+    };
+    boundedIdentifier(value: string, name: string): string;
+    messageCursorNamespace(storageKey: string): string;
+    createMessageCursor(namespace: string, sessionId: string, anchorMessageId: string): string;
+    parseMessageCursor(cursor: string): IFlexMessageCursor;
+    assertOpen(): void;
+}