@modelprofile.com/flexharness 18.0.0 → 18.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (80) hide show
  1. package/dist_ts/00_commitinfo_data.js +1 -1
  2. package/dist_ts/classes.flexharness.cachewarm.js +3 -3
  3. package/dist_ts/classes.flexharness.callbacks.d.ts +37 -0
  4. package/dist_ts/classes.flexharness.callbacks.js +129 -2
  5. package/dist_ts/classes.flexharness.compaction.js +2 -2
  6. package/dist_ts/classes.flexharness.configurations.js +4 -4
  7. package/dist_ts/classes.flexharness.core.d.ts +96 -5
  8. package/dist_ts/classes.flexharness.core.js +848 -301
  9. package/dist_ts/classes.flexharness.d.ts +10 -1
  10. package/dist_ts/classes.flexharness.deletion.d.ts +13 -0
  11. package/dist_ts/classes.flexharness.deletion.js +122 -40
  12. package/dist_ts/classes.flexharness.imports.js +26 -21
  13. package/dist_ts/classes.flexharness.js +16 -1
  14. package/dist_ts/classes.flexharness.lifecycle.js +9 -3
  15. package/dist_ts/classes.flexharness.projects.js +2 -2
  16. package/dist_ts/classes.flexharness.prompts.js +14 -8
  17. package/dist_ts/classes.flexharness.reversions.js +3 -3
  18. package/dist_ts/classes.flexharness.runs.js +18 -2
  19. package/dist_ts/classes.flexharness.sessions.d.ts +8 -1
  20. package/dist_ts/classes.flexharness.sessions.js +40 -14
  21. package/dist_ts/classes.flexharness.slashcommands.js +3 -3
  22. package/dist_ts/classes.flexharness.subagents.js +37 -16
  23. package/dist_ts/classes.flexharness.tooldispatch.js +3 -3
  24. package/dist_ts/classes.scoperecovery.d.ts +36 -0
  25. package/dist_ts/classes.scoperecovery.js +228 -0
  26. package/dist_ts/classes.stores.d.ts +14 -1
  27. package/dist_ts/classes.stores.js +150 -17
  28. package/dist_ts/classes.timeslicer.d.ts +21 -0
  29. package/dist_ts/classes.timeslicer.js +31 -0
  30. package/dist_ts/index.d.ts +1 -0
  31. package/dist_ts/index.js +2 -1
  32. package/dist_ts/interfaces.d.ts +120 -0
  33. package/dist_ts/interfaces.flexharness.d.ts +56 -1
  34. package/dist_ts/interfaces.js +1 -1
  35. package/dist_ts/plugins.d.ts +2 -2
  36. package/dist_ts/plugins.js +3 -3
  37. package/dist_ts/utils.harnessoptions.d.ts +2 -0
  38. package/dist_ts/utils.harnessoptions.js +16 -11
  39. package/dist_ts/utils.json.d.ts +6 -0
  40. package/dist_ts/utils.json.js +75 -20
  41. package/dist_ts/utils.scopesnapshot.d.ts +14 -0
  42. package/dist_ts/utils.scopesnapshot.js +58 -0
  43. package/dist_ts_stores_nosqldb/classes.nosqldbstores.d.ts +3 -2
  44. package/dist_ts_stores_nosqldb/classes.nosqldbstores.js +33 -2
  45. package/dist_ts_stores_nosqldb/classes.recordstore.d.ts +10 -1
  46. package/dist_ts_stores_nosqldb/classes.recordstore.js +75 -7
  47. package/package.json +3 -3
  48. package/readme.md +46 -3
  49. package/ts/00_commitinfo_data.ts +1 -1
  50. package/ts/classes.flexharness.cachewarm.ts +2 -2
  51. package/ts/classes.flexharness.callbacks.ts +142 -1
  52. package/ts/classes.flexharness.compaction.ts +1 -1
  53. package/ts/classes.flexharness.configurations.ts +3 -3
  54. package/ts/classes.flexharness.core.ts +902 -328
  55. package/ts/classes.flexharness.deletion.ts +161 -52
  56. package/ts/classes.flexharness.imports.ts +26 -21
  57. package/ts/classes.flexharness.lifecycle.ts +8 -2
  58. package/ts/classes.flexharness.projects.ts +1 -1
  59. package/ts/classes.flexharness.prompts.ts +11 -7
  60. package/ts/classes.flexharness.reversions.ts +2 -2
  61. package/ts/classes.flexharness.runs.ts +16 -1
  62. package/ts/classes.flexharness.sessions.ts +43 -13
  63. package/ts/classes.flexharness.slashcommands.ts +2 -2
  64. package/ts/classes.flexharness.subagents.ts +40 -15
  65. package/ts/classes.flexharness.tooldispatch.ts +2 -2
  66. package/ts/classes.flexharness.ts +22 -0
  67. package/ts/classes.scoperecovery.ts +290 -0
  68. package/ts/classes.stores.ts +150 -16
  69. package/ts/classes.timeslicer.ts +32 -0
  70. package/ts/index.ts +2 -0
  71. package/ts/interfaces.flexharness.ts +60 -0
  72. package/ts/interfaces.ts +129 -0
  73. package/ts/plugins.ts +2 -0
  74. package/ts/readme.md +46 -3
  75. package/ts/utils.harnessoptions.ts +18 -12
  76. package/ts/utils.json.ts +70 -18
  77. package/ts/utils.scopesnapshot.ts +75 -0
  78. package/ts_stores_nosqldb/classes.nosqldbstores.ts +52 -2
  79. package/ts_stores_nosqldb/classes.recordstore.ts +78 -8
  80. package/ts_stores_nosqldb/readme.md +10 -0
@@ -1,9 +1,9 @@
1
1
  import * as plugins from './plugins.js';
2
2
  import { FlexHarnessAbortError } from './errors.js';
3
- import type { IFlexAgentSessionPolicy, IFlexCallbackLimits, IFlexHarnessOptions, IFlexHarnessStores, IFlexMessage, IFlexPartSnapshotEvent, IFlexPromptQueueLimits, IFlexProjectionSnapshotCurrent, IFlexReversionLimits, IFlexResolvedScope, IFlexResultLimits, IFlexSession, IFlexSessionImportLimits, IFlexSubagentDefinition, IFlexToolCatalogOptions, IJsonObject, TFlexExternalErrorSource, TFlexHarnessEventListener, TFlexMessagePart, TFlexProjectionSnapshot, TFlexReversionPolicy } from './interfaces.js';
3
+ import type { IFlexAgentSessionPolicy, IFlexCacheWarmClock, IFlexCallbackLimits, IFlexHarnessOptions, IFlexHarnessStores, IFlexMessage, IFlexPartSnapshotEvent, IFlexPromptQueueLimits, IFlexProjectionSnapshotCurrent, IFlexReversionLimits, IFlexResolvedScope, IFlexResultLimits, IFlexSession, IFlexSessionImportLimits, IFlexSubagentDefinition, IFlexToolCatalogOptions, IJsonObject, TFlexExternalErrorSource, TFlexHarnessEventListener, TFlexMessagePart, TFlexProjectionSnapshot, TFlexReversionPolicy } from './interfaces.js';
4
4
  import { FlexCodeSandbox } from './classes.codesandbox.js';
5
5
  import { type INormalizedBuiltInTools, type INormalizedCacheWarmOptions, type TRegisteredSlashCommand } from './utils.harnessoptions.js';
6
- import type { TCanonicalOutcome, IStoredSessionState, IStorageState, IActiveRun, IScopeAdmissionState, IFlexMessageCursor, TEventDetails } from './interfaces.flexharness.js';
6
+ import type { TCanonicalOutcome, IStoredSessionState, IStorageState, IActiveRun, IScopeAdmissionState, IFlexMessageCursor, IScopeLoadPass, TEventDetails, TProjectionSaved } from './interfaces.flexharness.js';
7
7
  import { FlexHarnessResults } from './classes.flexharness.results.js';
8
8
  import { FlexHarnessToolDispatch } from './classes.flexharness.tooldispatch.js';
9
9
  import { FlexHarnessToolProviders } from './classes.flexharness.providers.js';
@@ -39,6 +39,8 @@ export declare class FlexHarnessCore<TScope> {
39
39
  /** The URL protocols, colon included, of the attachment references prompts may carry. */
40
40
  readonly attachmentReferenceProtocols: ReadonlySet<string>;
41
41
  readonly stores: IFlexHarnessStores;
42
+ readonly sessionLoading: 'eager' | 'session-local';
43
+ private readonly legacyQualifications;
42
44
  readonly agentSessionPolicy: IFlexAgentSessionPolicy<TScope>;
43
45
  readonly toolOutputLimits: Required<NonNullable<IFlexHarnessOptions<TScope>['toolOutputLimits']>>;
44
46
  readonly callbackLimits: Required<IFlexCallbackLimits>;
@@ -50,14 +52,19 @@ export declare class FlexHarnessCore<TScope> {
50
52
  readonly turnReversionProvider: IFlexHarnessOptions<TScope>['turnReversionProvider'];
51
53
  readonly reversionPolicy: TFlexReversionPolicy;
52
54
  private readonly externalErrorProjector?;
55
+ private readonly scopeLoadObserver?;
53
56
  readonly subagents: ReadonlyMap<string, Readonly<IFlexSubagentDefinition>>;
54
57
  readonly builtInTools: INormalizedBuiltInTools;
55
58
  readonly cacheWarmOptions: INormalizedCacheWarmOptions;
59
+ /** The clock of running turns' projection checkpoints: their spacing and save timings. */
60
+ readonly checkpointClock: IFlexCacheWarmClock;
56
61
  readonly toolCatalogOptions: Readonly<IFlexToolCatalogOptions>;
57
62
  readonly slashCommands: ReadonlyMap<string, TRegisteredSlashCommand<TScope>>;
58
63
  readonly maxSubagentDepth: number;
59
64
  readonly maxSubagentCallsPerRun: number;
60
65
  readonly stateLoads: Map<string, Promise<IStorageState>>;
66
+ /** The state each settled successful load loaded. */
67
+ private readonly loadedStates;
61
68
  readonly scopeAdmissions: Map<string, IScopeAdmissionState>;
62
69
  readonly listeners: Set<TFlexHarnessEventListener>;
63
70
  readonly trustedInternalErrors: WeakSet<object>;
@@ -95,11 +102,72 @@ export declare class FlexHarnessCore<TScope> {
95
102
  projectOperationError(error: unknown, source: TFlexExternalErrorSource, scopeId: string, sessionId: string, runId: string): Error;
96
103
  trustInternalError<TError extends Error>(error: TError): TError;
97
104
  canonicalOutcomes(events: readonly plugins.TAgentEvent[]): Map<string, TCanonicalOutcome>;
105
+ /** Adds the canonical outcomes `event` records to `outcomes`. */
106
+ private rememberCanonicalOutcomes;
98
107
  durableCanonicalOutcomes(stored: IStoredSessionState): Promise<Map<string, TCanonicalOutcome>>;
108
+ /**
109
+ * Loads a scope's state for every request of the scope, and reports what the load took to the
110
+ * scope load observer. Its long steps are cut into slices of time, so the event loop keeps
111
+ * running beside it; disposal and the scope's retirement stop it at the next slice (the abort of
112
+ * `compactorLifecycleController`), a request that stops waiting for it does not.
113
+ */
99
114
  private loadState;
115
+ /** Reports a scope load to the scope load observer, which can neither delay nor fail it. */
116
+ private observeScopeLoad;
117
+ private loadStateSliced;
118
+ /** Enumerates metadata/proof only; explicit prepareScope owns startup recovery. */
119
+ getScopeCatalogue(scopeId: string): Promise<import('./interfaces.js').IFlexScopeCatalogue>;
120
+ prepareScope(scopeId: string, options?: import('./interfaces.js').IFlexPrepareScopeOptions): Promise<import('./interfaces.js').IFlexScopeCatalogue>;
121
+ hydrateSession(state: IStorageState, sessionId: string, scopeId: string, scope: TScope): Promise<IStoredSessionState>;
122
+ /** Retries ownerless shared-workspace obligations, never an active run's normal capture. */
123
+ private recoverSharedState;
124
+ hydrateAllSessions(state: IStorageState, scopeId: string, scope: TScope): Promise<void>;
125
+ private saveScopeSnapshot;
126
+ /** Registers before the projection's pending intent can reach any workspace provider. */
127
+ updateRecoveryObligation(state: IStorageState, stored: IStoredSessionState, registerOnly?: boolean): Promise<void>;
128
+ /**
129
+ * Brings a session's recovery obligation up to date after an outcome is already recorded: a
130
+ * finished prompt or run, a saved projection. Its failure never changes that outcome. The
131
+ * durable obligation stays as it was, which the next load repairs, and the namespace is fenced
132
+ * through its drain instead of throwing into the caller.
133
+ */
134
+ settleRecoveryObligation(state: IStorageState, stored: IStoredSessionState): Promise<void>;
100
135
  createUninitializedStoredSession(session: IFlexSession, storageKey: string, compactorLifecycleController?: AbortController): IStoredSessionState;
101
- loadSessionRuntime(state: IStorageState, metadata: IFlexSession, scopeId: string, scope: TScope, compactorLifecycleController?: AbortController, newSession?: boolean): Promise<IStoredSessionState>;
136
+ loadSessionRuntime(state: IStorageState, metadata: IFlexSession, scopeId: string, scope: TScope, compactorLifecycleController?: AbortController, newSession?: boolean, pass?: IScopeLoadPass): Promise<IStoredSessionState>;
137
+ /**
138
+ * Repairs what a stopped process left in a loaded session: every run gets its terminal, the
139
+ * reversion state its runs' outcomes, the session its latest turn's state. Linear in the
140
+ * session's size, in slices of `slicer`'s time; it saves the projection only if its content
141
+ * changed.
142
+ */
102
143
  private repairLoadedSession;
144
+ /**
145
+ * Gives every run of a loaded session its terminal, in one pass over its messages, and returns
146
+ * the terminal of its latest real turn. A run with an accepted completed stage takes the stage;
147
+ * a run that failed or was stopped keeps the terminal it staged or published; a run that never
148
+ * reached its terminal is repaired as failed or cancelled. Each terminal goes where
149
+ * `runs.replaceVisibleRun()` would put it.
150
+ */
151
+ private repairRunTerminals;
152
+ /**
153
+ * The messages with each run's terminal in place, built in one pass: what
154
+ * `runs.replaceVisibleRun()` gives for each terminal in turn. A run's projected terminal messages
155
+ * are replaced, its other user messages take the prompt's `keptInContext`, and a terminal
156
+ * message not projected yet goes before the run's first message (its prompt) or after its last
157
+ * (its answer); for a run without messages both go to the end.
158
+ */
159
+ private placeRunTerminals;
160
+ /**
161
+ * The projection content a repair may change, as it is before the repair. Messages and reversion
162
+ * segments are frozen and replaced, never edited, so the lists keep their entries; the other
163
+ * fields are small and kept encoded.
164
+ */
165
+ private projectionContent;
166
+ /**
167
+ * Whether the session's projection content differs from `before` as JSON. A list entry that is
168
+ * still the same object is unchanged, so only an entry replaced since is encoded, one at a time.
169
+ */
170
+ private projectionContentChanged;
103
171
  /**
104
172
  * The failed or cancelled terminal a run published, read from its projected messages. A run
105
173
  * still running has its prompt or its last assistant message streaming; it has none.
@@ -124,7 +192,19 @@ export declare class FlexHarnessCore<TScope> {
124
192
  mutateScopeOwned<TValue>(state: IStorageState, mutation: () => TValue, onlySessionId?: string): Promise<TValue>;
125
193
  /** Holds a mutation declared for one session to that session: no other session, tombstone or cleanup changed. */
126
194
  private assertOnlySessionChanged;
127
- mutateProjection<TValue>(state: IStorageState, stored: IStoredSessionState, mutation: () => TValue, _allowDuringDrain?: boolean): Promise<TValue>;
195
+ /**
196
+ * Changes `stored`'s projection in its FIFO and saves it. `onSaved` gets the checkpoint clock's
197
+ * times the save started and completed, right after it completed.
198
+ */
199
+ mutateProjection<TValue>(state: IStorageState, stored: IStoredSessionState, mutation: () => TValue, _allowDuringDrain?: boolean, onSaved?: TProjectionSaved): Promise<TValue>;
200
+ /**
201
+ * A running turn's projection checkpoint, at its turn in the projection FIFO: `prepare` decides
202
+ * there what to save and returns the mutation, or nothing, which saves nothing. Resolves whether
203
+ * it saved.
204
+ */
205
+ checkpointProjection(state: IStorageState, stored: IStoredSessionState, prepare: () => (() => void) | undefined, onSaved: TProjectionSaved): Promise<boolean>;
206
+ private enqueueProjectionOperation;
207
+ private saveProjectionMutation;
128
208
  private createScopeSnapshot;
129
209
  private createProjectionSnapshot;
130
210
  /** The change from the lists the store holds to the session's projection at `revision`. */
@@ -139,10 +219,19 @@ export declare class FlexHarnessCore<TScope> {
139
219
  private sessionParentSessionId;
140
220
  private sessionMetadata;
141
221
  appendUnexpectedErrors(target: unknown[], error: unknown): void;
142
- resolveState(scopeId: string): Promise<{
222
+ resolveState(scopeId: string, sessionId?: string): Promise<{
143
223
  scope: IFlexResolvedScope<TScope>;
144
224
  state: IStorageState;
145
225
  }>;
226
+ /** Whether `stateLoad` has settled with its loaded state. */
227
+ isStateLoaded(stateLoad: Promise<IStorageState>): boolean;
228
+ /**
229
+ * Runs `operation` for the resolved scope `scopeId` while the scope is admitted: not retiring,
230
+ * not retired since, not draining. `admitted()` tells whether that still holds.
231
+ */
232
+ withScopeAdmission<TValue>(scopeId: string, operation: (scope: IFlexResolvedScope<TScope>, admitted: () => boolean) => Promise<TValue>): Promise<TValue>;
233
+ /** The state `stateLoad` loads, once it is active and the scope still admitted. */
234
+ admittedState(scopeId: string, scope: IFlexResolvedScope<TScope>, stateLoad: Promise<IStorageState>, admitted: () => boolean): Promise<IStorageState>;
146
235
  getScopeAdmission(scopeId: string): IScopeAdmissionState;
147
236
  pruneScopeAdmission(scopeId: string, admission: IScopeAdmissionState): void;
148
237
  createScopeRetirementError(): FlexHarnessAbortError;
@@ -178,6 +267,8 @@ export declare class FlexHarnessCore<TScope> {
178
267
  * one id each; a position is searched again only after it moved (a steer, a restored or
179
268
  * reloaded projection).
180
269
  */
270
+ /** The run's remembered positions, its assistant message's checked; -1 when it is not projected. */
271
+ assistantMessagePositions(run: IActiveRun): NonNullable<IActiveRun['partEventPositions']>;
181
272
  private partEventCoordinates;
182
273
  emitEvent(scopeId: string, sourceSession: IFlexSession, details: TEventDetails): void;
183
274
  validateRuntimeEvent(event: unknown): asserts event is IJsonObject & {