@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.
- package/dist_ts/00_commitinfo_data.js +1 -1
- package/dist_ts/classes.flexharness.cachewarm.js +3 -3
- package/dist_ts/classes.flexharness.callbacks.d.ts +37 -0
- package/dist_ts/classes.flexharness.callbacks.js +129 -2
- package/dist_ts/classes.flexharness.compaction.js +2 -2
- package/dist_ts/classes.flexharness.configurations.js +4 -4
- package/dist_ts/classes.flexharness.core.d.ts +96 -5
- package/dist_ts/classes.flexharness.core.js +848 -301
- package/dist_ts/classes.flexharness.d.ts +10 -1
- package/dist_ts/classes.flexharness.deletion.d.ts +13 -0
- package/dist_ts/classes.flexharness.deletion.js +122 -40
- package/dist_ts/classes.flexharness.imports.js +26 -21
- package/dist_ts/classes.flexharness.js +16 -1
- package/dist_ts/classes.flexharness.lifecycle.js +9 -3
- package/dist_ts/classes.flexharness.projects.js +2 -2
- package/dist_ts/classes.flexharness.prompts.js +14 -8
- package/dist_ts/classes.flexharness.reversions.js +3 -3
- package/dist_ts/classes.flexharness.runs.js +18 -2
- package/dist_ts/classes.flexharness.sessions.d.ts +8 -1
- package/dist_ts/classes.flexharness.sessions.js +40 -14
- package/dist_ts/classes.flexharness.slashcommands.js +3 -3
- package/dist_ts/classes.flexharness.subagents.js +37 -16
- package/dist_ts/classes.flexharness.tooldispatch.js +3 -3
- package/dist_ts/classes.scoperecovery.d.ts +36 -0
- package/dist_ts/classes.scoperecovery.js +228 -0
- package/dist_ts/classes.stores.d.ts +14 -1
- package/dist_ts/classes.stores.js +150 -17
- package/dist_ts/classes.timeslicer.d.ts +21 -0
- package/dist_ts/classes.timeslicer.js +31 -0
- package/dist_ts/index.d.ts +1 -0
- package/dist_ts/index.js +2 -1
- package/dist_ts/interfaces.d.ts +120 -0
- package/dist_ts/interfaces.flexharness.d.ts +56 -1
- package/dist_ts/interfaces.js +1 -1
- package/dist_ts/plugins.d.ts +2 -2
- package/dist_ts/plugins.js +3 -3
- package/dist_ts/utils.harnessoptions.d.ts +2 -0
- package/dist_ts/utils.harnessoptions.js +16 -11
- package/dist_ts/utils.json.d.ts +6 -0
- package/dist_ts/utils.json.js +75 -20
- package/dist_ts/utils.scopesnapshot.d.ts +14 -0
- package/dist_ts/utils.scopesnapshot.js +58 -0
- package/dist_ts_stores_nosqldb/classes.nosqldbstores.d.ts +3 -2
- package/dist_ts_stores_nosqldb/classes.nosqldbstores.js +33 -2
- package/dist_ts_stores_nosqldb/classes.recordstore.d.ts +10 -1
- package/dist_ts_stores_nosqldb/classes.recordstore.js +75 -7
- package/package.json +3 -3
- package/readme.md +46 -3
- package/ts/00_commitinfo_data.ts +1 -1
- package/ts/classes.flexharness.cachewarm.ts +2 -2
- package/ts/classes.flexharness.callbacks.ts +142 -1
- package/ts/classes.flexharness.compaction.ts +1 -1
- package/ts/classes.flexharness.configurations.ts +3 -3
- package/ts/classes.flexharness.core.ts +902 -328
- package/ts/classes.flexharness.deletion.ts +161 -52
- package/ts/classes.flexharness.imports.ts +26 -21
- package/ts/classes.flexharness.lifecycle.ts +8 -2
- package/ts/classes.flexharness.projects.ts +1 -1
- package/ts/classes.flexharness.prompts.ts +11 -7
- package/ts/classes.flexharness.reversions.ts +2 -2
- package/ts/classes.flexharness.runs.ts +16 -1
- package/ts/classes.flexharness.sessions.ts +43 -13
- package/ts/classes.flexharness.slashcommands.ts +2 -2
- package/ts/classes.flexharness.subagents.ts +40 -15
- package/ts/classes.flexharness.tooldispatch.ts +2 -2
- package/ts/classes.flexharness.ts +22 -0
- package/ts/classes.scoperecovery.ts +290 -0
- package/ts/classes.stores.ts +150 -16
- package/ts/classes.timeslicer.ts +32 -0
- package/ts/index.ts +2 -0
- package/ts/interfaces.flexharness.ts +60 -0
- package/ts/interfaces.ts +129 -0
- package/ts/plugins.ts +2 -0
- package/ts/readme.md +46 -3
- package/ts/utils.harnessoptions.ts +18 -12
- package/ts/utils.json.ts +70 -18
- package/ts/utils.scopesnapshot.ts +75 -0
- package/ts_stores_nosqldb/classes.nosqldbstores.ts +52 -2
- package/ts_stores_nosqldb/classes.recordstore.ts +78 -8
- package/ts_stores_nosqldb/readme.md +10 -0
|
@@ -2,6 +2,7 @@ import type * as plugins from './plugins.js';
|
|
|
2
2
|
import type { FlexHarnessAbortError } from './errors.js';
|
|
3
3
|
import type { FlexToolCatalog } from './classes.toolcatalog.js';
|
|
4
4
|
import type { FlexCodeSandbox } from './classes.codesandbox.js';
|
|
5
|
+
import type { FlexTimeSlicer } from './classes.timeslicer.js';
|
|
5
6
|
import type { IFlexProjectionLists } from './utils.projectionchange.js';
|
|
6
7
|
import type {
|
|
7
8
|
IFlexAgentContextInvocation,
|
|
@@ -20,6 +21,7 @@ import type {
|
|
|
20
21
|
IFlexPendingReversionRelease,
|
|
21
22
|
IFlexResolvedModel,
|
|
22
23
|
IFlexResolvedSessionConfiguration,
|
|
24
|
+
IFlexScopeLoadMetrics,
|
|
23
25
|
IFlexSession,
|
|
24
26
|
IFlexSessionMetricsState,
|
|
25
27
|
IFlexSessionTombstone,
|
|
@@ -45,6 +47,32 @@ import type { INormalizedSessionImportOptions } from './utils.sessionimport.js';
|
|
|
45
47
|
import type { ISessionMetricsOperation } from './utils.sessionmetrics.js';
|
|
46
48
|
|
|
47
49
|
export type TCanonicalOutcome = 'accepted' | 'rejected' | 'interrupted';
|
|
50
|
+
/** When a projection save started and completed, on the checkpoint clock. */
|
|
51
|
+
export type TProjectionSaved = (startedAt: number, completedAt: number) => void;
|
|
52
|
+
|
|
53
|
+
/**
|
|
54
|
+
* A run's projection checkpoints: the parts of its committed steps, saved on its streaming
|
|
55
|
+
* assistant message while the run goes on, so that a process stopping mid-run leaves them visible.
|
|
56
|
+
* A checkpoint starts no earlier than the larger of 10 s and 20 times the duration of the run's
|
|
57
|
+
* last save of that message after that save completed; one is outstanding at most.
|
|
58
|
+
*/
|
|
59
|
+
export interface IRunCheckpoint {
|
|
60
|
+
/** The parts of committed steps, by id: what a checkpoint saves, as the parts stand then. */
|
|
61
|
+
committedPartIds: Set<string>;
|
|
62
|
+
/** A step committed since the last checkpoint read the run's parts. */
|
|
63
|
+
dirty: boolean;
|
|
64
|
+
/** A checkpoint is queued in the projection FIFO or saving. */
|
|
65
|
+
outstanding: boolean;
|
|
66
|
+
/** The deadline timer on the checkpoint clock, while one is armed. */
|
|
67
|
+
timer?: unknown;
|
|
68
|
+
/** When the run's last save of its current assistant message completed, on the checkpoint clock. */
|
|
69
|
+
savedAt?: number;
|
|
70
|
+
/** How long that save took, in milliseconds of the checkpoint clock. */
|
|
71
|
+
saveMs: number;
|
|
72
|
+
/** No checkpoint starts any more: the run reached its terminal, closed or its namespace stopped. */
|
|
73
|
+
closed: boolean;
|
|
74
|
+
}
|
|
75
|
+
|
|
48
76
|
export type TRunPhase =
|
|
49
77
|
| 'admitting'
|
|
50
78
|
| 'scheduled'
|
|
@@ -53,6 +81,26 @@ export type TRunPhase =
|
|
|
53
81
|
| 'finalizing'
|
|
54
82
|
| 'promoting';
|
|
55
83
|
|
|
84
|
+
/** One scope load: the slicer that cuts its work, and what it took so far. */
|
|
85
|
+
export interface IScopeLoadPass {
|
|
86
|
+
readonly slicer: FlexTimeSlicer;
|
|
87
|
+
readonly metrics: Omit<IFlexScopeLoadMetrics, 'totalMs' | 'outcome'>;
|
|
88
|
+
}
|
|
89
|
+
|
|
90
|
+
/**
|
|
91
|
+
* A session's projection content as a repair found it: the message and reversion segment lists
|
|
92
|
+
* with their frozen entries, the other fields encoded.
|
|
93
|
+
*/
|
|
94
|
+
export interface IProjectionContent {
|
|
95
|
+
readonly messages: readonly IFlexMessage[];
|
|
96
|
+
readonly reversionSegments: readonly IFlexReversionSegment[];
|
|
97
|
+
readonly stagedTerminals: string;
|
|
98
|
+
readonly revertCursor: number;
|
|
99
|
+
readonly excludedRunIds: string;
|
|
100
|
+
readonly pendingReversion: string | undefined;
|
|
101
|
+
readonly pendingReversionReleases: string;
|
|
102
|
+
}
|
|
103
|
+
|
|
56
104
|
/** The invocation a compaction runs under; a manual compaction also carries its requested model hint. */
|
|
57
105
|
export interface ICompactorInvocation<TScope> extends IFlexAgentContextInvocation<TScope> {
|
|
58
106
|
readonly modelHint?: string;
|
|
@@ -60,6 +108,7 @@ export interface ICompactorInvocation<TScope> extends IFlexAgentContextInvocatio
|
|
|
60
108
|
|
|
61
109
|
export interface IStoredSessionState {
|
|
62
110
|
storageKey: string;
|
|
111
|
+
recovering?: boolean;
|
|
63
112
|
compactorContext?: IFlexAgentContextInvocation<unknown>;
|
|
64
113
|
session: IFlexSession;
|
|
65
114
|
messages: IFlexMessage[];
|
|
@@ -192,6 +241,13 @@ export interface IStorageState {
|
|
|
192
241
|
scopeIdHint: string;
|
|
193
242
|
scopeContext: { scopeId: string; scope: unknown };
|
|
194
243
|
revision: number;
|
|
244
|
+
/** Complete live metadata; independent of the hydrated runtime subset below. */
|
|
245
|
+
catalogue: Map<string, IFlexSession>;
|
|
246
|
+
sessionLocal: boolean;
|
|
247
|
+
qualifyingLegacy: boolean;
|
|
248
|
+
recoverySessionIds: Set<string>;
|
|
249
|
+
sessionLoads: Map<string, Promise<IStoredSessionState>>;
|
|
250
|
+
sharedRecovery?: Promise<void>;
|
|
195
251
|
sessions: Map<string, IStoredSessionState>;
|
|
196
252
|
retainedSessionCleanups: Map<string, IRetainedSessionCleanup>;
|
|
197
253
|
sessionDeletions: Map<string, Promise<void>>;
|
|
@@ -274,6 +330,8 @@ export interface IActiveRun {
|
|
|
274
330
|
stepStreamedCalls: Map<string, ReadonlySet<string>>;
|
|
275
331
|
/** The step's streamed calls the SDK could not parse or repair, with its error: they never start. */
|
|
276
332
|
stepInvalidCalls: Map<string, string>;
|
|
333
|
+
/** The run's projection checkpoints; see {@link IRunCheckpoint}. */
|
|
334
|
+
checkpoint: IRunCheckpoint;
|
|
277
335
|
textPartClosed: boolean;
|
|
278
336
|
toolPartIds: Map<string, string>;
|
|
279
337
|
trustedToolExecutionErrors: Map<string, Error>;
|
|
@@ -558,6 +616,8 @@ export interface ISessionDeletionPlan {
|
|
|
558
616
|
export interface IReservedSessionDeletion {
|
|
559
617
|
deletedSessions: IFlexSession[];
|
|
560
618
|
descendantRoots: string[];
|
|
619
|
+
/** The settlement of the deleted sessions' configuration resolutions the reservation's fence aborted. */
|
|
620
|
+
configurationSettlement?: Promise<void>;
|
|
561
621
|
}
|
|
562
622
|
|
|
563
623
|
export type TProjectTaskToolInput =
|
package/ts/interfaces.ts
CHANGED
|
@@ -1510,6 +1510,12 @@ export interface IFlexSessionGeneration {
|
|
|
1510
1510
|
sessionGenerationSequence: number;
|
|
1511
1511
|
}
|
|
1512
1512
|
|
|
1513
|
+
/** A live session of a scope as `listSessionIdentities()` names it. */
|
|
1514
|
+
export interface IFlexSessionIdentity extends IFlexSessionGeneration {
|
|
1515
|
+
sessionId: string;
|
|
1516
|
+
parentSessionId?: string;
|
|
1517
|
+
}
|
|
1518
|
+
|
|
1513
1519
|
export const FLEX_SESSION_CONFIGURATION_REF_MAX_BYTES = 1024;
|
|
1514
1520
|
|
|
1515
1521
|
export interface IFlexSessionConfigurationResolverContext<TScope> extends IFlexSessionGeneration {
|
|
@@ -1682,7 +1688,88 @@ export interface IFlexProjectScratchpadResult extends IFlexProjectStateResult {
|
|
|
1682
1688
|
scratchpad: string;
|
|
1683
1689
|
}
|
|
1684
1690
|
|
|
1691
|
+
/** Compact recovery proof stored separately from the strict schema-1 scope snapshot. */
|
|
1692
|
+
export interface IFlexScopeRecoverySnapshot {
|
|
1693
|
+
schemaVersion: 1;
|
|
1694
|
+
revision: number;
|
|
1695
|
+
catalogueRevision: number;
|
|
1696
|
+
catalogueDigest: string;
|
|
1697
|
+
recoverySessionIds: string[];
|
|
1698
|
+
}
|
|
1699
|
+
|
|
1700
|
+
/**
|
|
1701
|
+
* Additive sidecar persistence for `RecoverableFlexScopeStore`: the recovery proof and the
|
|
1702
|
+
* namespace's write provenance. A scope snapshot cannot show that nothing needs recovery: a writer
|
|
1703
|
+
* unaware of the proof (an older release, an eager harness, another tool) may write a projection's
|
|
1704
|
+
* pending capture or apply, run its workspace effect and stop before it writes the scope. The
|
|
1705
|
+
* provenance is a durable witness of the namespace's writes that the implementation keeps so that:
|
|
1706
|
+
*
|
|
1707
|
+
* - every write in every domain of the namespace (scope, proof, projections, permissions, agent
|
|
1708
|
+
* events and archives, tool jobs, results, project management, every deletion and purge) changes
|
|
1709
|
+
* it atomically with the write, by every writer that can open the namespace, releases that
|
|
1710
|
+
* predate this contract included: it is a counter or header those writers already change, never
|
|
1711
|
+
* a field only recovery-aware writers maintain;
|
|
1712
|
+
* - a write of an activated instance is recorded as known atomically with the write; every other
|
|
1713
|
+
* write is unknown;
|
|
1714
|
+
* - it is read from metadata alone, never from history bodies, and never returns to an earlier
|
|
1715
|
+
* value while the namespace holds data.
|
|
1716
|
+
*/
|
|
1717
|
+
export interface IFlexScopeRecoveryStore {
|
|
1718
|
+
/**
|
|
1719
|
+
* Synchronous and local: afterwards this instance's writes for the key are unknown. Never changes
|
|
1720
|
+
* durable state. Called on release, eager loading, disposal, retirement and stale evidence.
|
|
1721
|
+
*/
|
|
1722
|
+
deactivateWriteProvenance(storageKey: string): void;
|
|
1723
|
+
/**
|
|
1724
|
+
* True only if every write since the last {@link qualifyWriteProvenance} is known; then activates
|
|
1725
|
+
* this instance for the key. Otherwise false, deactivated. Never repairs. While activated, each
|
|
1726
|
+
* write checks in the same atomic step that the witness still shows only known writes and fails
|
|
1727
|
+
* with `FlexHarnessStoreFormatError` instead of recording itself as known when it does not.
|
|
1728
|
+
*/
|
|
1729
|
+
loadWriteProvenance(storageKey: string): Promise<boolean>;
|
|
1730
|
+
/**
|
|
1731
|
+
* Marks every write so far as known and activates. Called only at the end of an explicit complete
|
|
1732
|
+
* qualification under exclusive ownership, after the proof was published; a failure leaves the
|
|
1733
|
+
* namespace unqualified.
|
|
1734
|
+
*/
|
|
1735
|
+
qualifyWriteProvenance(storageKey: string): Promise<void>;
|
|
1736
|
+
load(storageKey: string): Promise<IFlexScopeRecoverySnapshot | undefined>;
|
|
1737
|
+
/**
|
|
1738
|
+
* Durable compare-and-swap: writes only when the stored revision equals `expectedRevision`
|
|
1739
|
+
* (`FlexHarnessStoreConflictError` otherwise); an unknown outcome is
|
|
1740
|
+
* `FlexHarnessStoreCommitUncertainError`.
|
|
1741
|
+
*/
|
|
1742
|
+
save(storageKey: string, snapshot: IFlexScopeRecoverySnapshot, expectedRevision: number): Promise<void>;
|
|
1743
|
+
}
|
|
1744
|
+
|
|
1745
|
+
/** Requires exclusive namespace ownership, like the harness itself. */
|
|
1746
|
+
export interface IFlexSessionLocalScopeStore {
|
|
1747
|
+
/** Releases local writer activation only, not a distributed namespace lock. */
|
|
1748
|
+
releaseOwnership(storageKey: string): void;
|
|
1749
|
+
/** A missing/stale proof is unqualified, never an assertion that recovery is unnecessary. */
|
|
1750
|
+
loadCatalogue(storageKey: string): Promise<{
|
|
1751
|
+
snapshot: IFlexScopeSnapshot | undefined;
|
|
1752
|
+
qualified: boolean;
|
|
1753
|
+
recoverySessionIds: string[];
|
|
1754
|
+
}>;
|
|
1755
|
+
saveCatalogue(storageKey: string, snapshot: IFlexScopeSnapshot, expectedRevision: number): Promise<void>;
|
|
1756
|
+
setRecoveryRequired(storageKey: string, sessionId: string, required: boolean): Promise<void>;
|
|
1757
|
+
/** Called only after explicit complete legacy qualification under namespace ownership. */
|
|
1758
|
+
qualifyCatalogue(storageKey: string, snapshot: IFlexScopeSnapshot, recoverySessionIds: string[]): Promise<void>;
|
|
1759
|
+
}
|
|
1760
|
+
|
|
1761
|
+
export interface IFlexPrepareScopeOptions {
|
|
1762
|
+
/** Explicitly permits the one-time complete legacy load/repair when proof is absent or stale. */
|
|
1763
|
+
qualifyLegacy?: boolean;
|
|
1764
|
+
}
|
|
1765
|
+
|
|
1766
|
+
export interface IFlexScopeCatalogue {
|
|
1767
|
+
sessions: IFlexSession[];
|
|
1768
|
+
recoverySessionIds: string[];
|
|
1769
|
+
}
|
|
1770
|
+
|
|
1685
1771
|
export interface IFlexScopeStore {
|
|
1772
|
+
sessionLocal?: IFlexSessionLocalScopeStore;
|
|
1686
1773
|
load(storageKey: string): Promise<IFlexScopeSnapshot | undefined>;
|
|
1687
1774
|
save(
|
|
1688
1775
|
storageKey: string,
|
|
@@ -2191,6 +2278,8 @@ export interface IFlexHarnessOptions<TScope> {
|
|
|
2191
2278
|
/** Lets prompts name attachments by reference; see {@link IFlexAttachmentResolver}. */
|
|
2192
2279
|
attachmentResolver?: IFlexAttachmentResolver<TScope>;
|
|
2193
2280
|
stores?: IFlexHarnessStores;
|
|
2281
|
+
/** Opt-in: requires scopes.sessionLocal; never falls back to an implicit complete load. */
|
|
2282
|
+
sessionLoading?: 'eager' | 'session-local';
|
|
2194
2283
|
agentSessionPolicy?: IFlexAgentSessionPolicy<TScope>;
|
|
2195
2284
|
toolOutputLimits?: IFlexJsonLimits;
|
|
2196
2285
|
callbackLimits?: IFlexCallbackLimits;
|
|
@@ -2216,8 +2305,48 @@ export interface IFlexHarnessOptions<TScope> {
|
|
|
2216
2305
|
maxSubagentCallsPerRun?: number;
|
|
2217
2306
|
/** Bounds and the clock of the cache keeper; see `keepCacheWarm()`. */
|
|
2218
2307
|
cacheWarm?: IFlexCacheWarmOptions;
|
|
2308
|
+
/**
|
|
2309
|
+
* The clock a running turn's projection checkpoints read and set their timers on. Defaults to
|
|
2310
|
+
* the system clock, whose timers do not keep the process alive. Tests pass a fake one; the
|
|
2311
|
+
* spacing of checkpoints is fixed, not configurable.
|
|
2312
|
+
*/
|
|
2313
|
+
projectionCheckpointClock?: IFlexCacheWarmClock;
|
|
2314
|
+
/**
|
|
2315
|
+
* Called once each scope load ends, with what it took. An exception it throws, or a promise it
|
|
2316
|
+
* rejects, is ignored.
|
|
2317
|
+
*/
|
|
2318
|
+
scopeLoadObserver?: TFlexScopeLoadObserver;
|
|
2219
2319
|
}
|
|
2220
2320
|
|
|
2321
|
+
/** How a scope load ended: loaded, failed, or stopped by disposal or the scope's retirement. */
|
|
2322
|
+
export type TFlexScopeLoadOutcome = 'loaded' | 'failed' | 'aborted';
|
|
2323
|
+
|
|
2324
|
+
/**
|
|
2325
|
+
* What one scope load took. A load reads the scope's sessions, their projections, permissions,
|
|
2326
|
+
* event logs and job stores, and repairs what a stopped process left behind; the first request of
|
|
2327
|
+
* a scope waits for it. Times are wall-clock milliseconds, which include the turns the load gives
|
|
2328
|
+
* the event loop.
|
|
2329
|
+
*/
|
|
2330
|
+
export interface IFlexScopeLoadMetrics {
|
|
2331
|
+
scopeId: string;
|
|
2332
|
+
storageKey: string;
|
|
2333
|
+
/** The live sessions the load read, up to where it ended. */
|
|
2334
|
+
sessions: number;
|
|
2335
|
+
/**
|
|
2336
|
+
* The time spent waiting for the stores: the scope snapshot, and each session's projection,
|
|
2337
|
+
* permissions, agent event store and job store. The event log itself is read in `agentSessionMs`.
|
|
2338
|
+
*/
|
|
2339
|
+
storeReadMs: number;
|
|
2340
|
+
/** The time spent creating the sessions' agent sessions: each reads and checks its event log. */
|
|
2341
|
+
agentSessionMs: number;
|
|
2342
|
+
/** The time spent repairing the sessions, their saves included. */
|
|
2343
|
+
repairMs: number;
|
|
2344
|
+
totalMs: number;
|
|
2345
|
+
outcome: TFlexScopeLoadOutcome;
|
|
2346
|
+
}
|
|
2347
|
+
|
|
2348
|
+
export type TFlexScopeLoadObserver = (metricsArg: IFlexScopeLoadMetrics) => void;
|
|
2349
|
+
|
|
2221
2350
|
export interface IFlexUncertainToolExecution {
|
|
2222
2351
|
intentId: string;
|
|
2223
2352
|
generationId: string;
|
package/ts/plugins.ts
CHANGED
|
@@ -108,6 +108,7 @@ import {
|
|
|
108
108
|
createAgentEvent,
|
|
109
109
|
filterModelVisibleAgentEvents,
|
|
110
110
|
getAgentGenerationTransactions,
|
|
111
|
+
getGenerationsInModelContext,
|
|
111
112
|
isGenerationInModelContext,
|
|
112
113
|
modelMessagesToAgentEvents,
|
|
113
114
|
resolveAgentContextCompactionPoint,
|
|
@@ -134,6 +135,7 @@ export {
|
|
|
134
135
|
createAgentEvent,
|
|
135
136
|
filterModelVisibleAgentEvents,
|
|
136
137
|
getAgentGenerationTransactions,
|
|
138
|
+
getGenerationsInModelContext,
|
|
137
139
|
isGenerationInModelContext,
|
|
138
140
|
modelMessagesToAgentEvents,
|
|
139
141
|
resolveAgentContextCompactionPoint,
|
package/ts/readme.md
CHANGED
|
@@ -639,6 +639,7 @@ The main session methods are:
|
|
|
639
639
|
|
|
640
640
|
```typescript
|
|
641
641
|
await harness.listSessions(scopeId);
|
|
642
|
+
await harness.listSessionIdentities(scopeId);
|
|
642
643
|
await harness.createSession(scopeId, { sessionId, sessionGenerationId, title });
|
|
643
644
|
await harness.getSession(scopeId, sessionId);
|
|
644
645
|
await harness.getMessages(scopeId, sessionId);
|
|
@@ -708,6 +709,10 @@ await harness.dispose();
|
|
|
708
709
|
|
|
709
710
|
`getSession()` returns the session as saved after every queued write that may change it; it does not wait for queued writes of the scope's other sessions, so a slow save of one session never holds a read of another. `listSessions()` waits for every queued write.
|
|
710
711
|
|
|
712
|
+
`listSessionIdentities(scopeId)` lists a scope's live sessions as `IFlexSessionIdentity` (`sessionId`, `sessionGenerationId`, `sessionGenerationSequence`, `parentSessionId` when set), sorted by session id. It reads complete scope metadata only, never a projection, event log or job store. Before the catalogue load settles it normalizes the stored scope snapshot just as loading does (including deterministic legacy generations and tombstone filtering); afterward it reads the complete in-memory catalogue, not the hydrated runtime subset.
|
|
713
|
+
|
|
714
|
+
The load gives the event loop a turn about every 25 ms of work, so timers, I/O and a caller's cancellation keep running beside it, and its repair takes time linear in a session's size. A request that stops waiting for the load leaves it running, and the next request of the scope joins it; `dispose()` and `retireScope()` stop it at its next turn, and the requests waiting for it fail with `FlexHarnessAbortError`. The `scopeLoadObserver` option is called once each load ends, with `IFlexScopeLoadMetrics`: `scopeId`, `storageKey`, the live `sessions` it read, `storeReadMs` (waiting for the scope snapshot and each session's projection, permissions, agent event store and job store), `agentSessionMs` (creating the sessions' agent sessions, each of which reads and checks its event log), `repairMs`, `totalMs`, all wall-clock milliseconds, and `outcome` (`'loaded'`, `'failed'`, or `'aborted'` by disposal or retirement). An exception the observer throws, or a promise it rejects, is ignored.
|
|
715
|
+
|
|
711
716
|
Only one run may be active in a session. Additional prompts enter a bounded FIFO owned by FlexHarness, while different sessions can run concurrently. `enqueuePrompt()` resolves with `{ queueId, generation, completion }` after the immutable prompt and options have been accepted into that runtime queue and `prompt.queued` has been emitted. `startPrompt()` keeps its durable-admission behavior: it waits for its FIFO turn and resolves with `{ queueId, generation, runId, completion }` only after the canonical generation claim, run ID, and initial public audit messages have been durably reserved and the corresponding start events have been emitted. `prompt()` preserves the simpler behavior by awaiting completion internally.
|
|
712
717
|
|
|
713
718
|
Every admission names the session generation that admitted it: `generation` (`IFlexPromptAdmissionGeneration`) holds `sessionGenerationId`, `sessionGenerationSequence`, `depth` (0 for a root session, also a legacy root that stored none) and `configurationRef` when the session has one, as `getSession()` reports them. None of them changes while the generation lives, and the prompt only ever runs on that generation. The harness reads it from the session in memory, so a caller that needs it for the run it started does not call `getSession()`: that read waits for the session's queued writes, which queue behind every other session's write queued before them in the scope's one write FIFO.
|
|
@@ -726,12 +731,48 @@ The reservation save is the admission point. A save failure produces no start ev
|
|
|
726
731
|
|
|
727
732
|
`listMessageMetadataPage()` pages like `listMessagePage()`, with the same options, `startIndex`, cursors (a cursor of either kind of page continues the other) and `includeUndone`, but each message carries only its identity and state (`TFlexMessageMetadata`: `messageId`, `sessionId`, `runId`, `role`, `status`, `createdAt`, `completedAt`, `steerId`, `promptId`, `keptInContext`, `undone`, `cacheWarm`), never its parts, model, usage or error. A full scan then reads the same few hundred bytes per message whatever its content, enough to prove which prompts and steers a session received and whether its runs kept them in context.
|
|
728
733
|
|
|
729
|
-
`updateSession()` supports title replacement, explicit title clearing with `null`, and archive state through `archived`. Title-only updates remain available while prompts are queued or running, while permission is pending, and after archival. Requests containing `archived` are rejected while the session has any outstanding prompt or pending permission; a mixed title-and-archive request is rejected atomically without changing the title. Archived sessions expose `archivedAt`. Every session exposes `preview` once a run with prompt text was admitted: its first prompt as one line (whitespace runs collapsed, cut at a character boundary to `maxTitleBytes`), with no model call, so a host can name a session nobody titled (`title || preview`). It is set once, a session stored before previews existed takes it from its first prompt at its next run, and no caller sets or clears it. Deleting a session cascades through its complete descendant subtree. One durable root-keyed tombstone group hides every newly affected live session, and the delete also joins any already-separate descendant cleanup groups without rewriting their roots. FlexHarness then cancels queued
|
|
734
|
+
`updateSession()` supports title replacement, explicit title clearing with `null`, and archive state through `archived`. Title-only updates remain available while prompts are queued or running, while permission is pending, and after archival. Requests containing `archived` are rejected while the session has any outstanding prompt or pending permission; a mixed title-and-archive request is rejected atomically without changing the title. Archived sessions expose `archivedAt`. Every session exposes `preview` once a run with prompt text was admitted: its first prompt as one line (whitespace runs collapsed, cut at a character boundary to `maxTitleBytes`), with no model call, so a host can name a session nobody titled (`title || preview`). It is set once, a session stored before previews existed takes it from its first prompt at its next run, and no caller sets or clears it. Deleting a session cascades through its complete descendant subtree. One durable root-keyed tombstone group hides every newly affected live session, and the delete also joins any already-separate descendant cleanup groups without rewriting their roots. FlexHarness cancels the subtree's active runs as soon as the group is applied, before its save completes, so an admission that has not reached its model call never does however slow the store; it then cancels queued subtree work, emits terminal queue events, waits for admitted initialization, and purges runtime queue status while cleaning runtime and persisted domains child-first. The requested root tombstone is removed last after every domain confirms cleanup; project-management cleanup confirmation is a retained durable project tombstone rather than physical removal. An imported session can hold no project-management state, so its deletion writes no project tombstone. A successful live `deleteSession()` call emits `session.deleted` for each session it newly tombstoned; retries of an existing tombstone and automatic load, retirement, or disposal cleanup emit no deletion events. Direct deletion of a descendant cascades only through that descendant's subtree. Cleanup authority follows the resolved storage namespace, so scope aliases share the same groups. A partial failure retains durable ownership for retry by a later `deleteSession()`, namespace load, `retireScope()`, or `dispose()` call.
|
|
730
735
|
|
|
731
736
|
`deleteSessionGenerationCohort()` is the generation-fenced destructive form for controllers. Its `root` and every `authorizedCohort` entry use the exact `{ sessionId, sessionGenerationId, sessionGenerationSequence }` shape. The cohort contains unique entries in strictly ascending `sessionId` order and is limited by `FLEX_SESSION_GENERATION_COHORT_MAX_ENTRIES` (2048). FlexHarness atomically validates the matching root, its complete live subtree, and every retained descendant tombstone group before reserving deletion. A missing or different root generation returns `{ matched: false }` without touching a newer generation; a missing or mismatched cascade entry throws before new tombstoning or cleanup. Extra valid entries do not expand the cascade. A matched partial cleanup remains retryable with the same authority and resolves to `{ matched: true }` when cleanup completes. The existing `deleteSession()` method remains available for callers that intentionally own the complete reusable-ID namespace.
|
|
732
737
|
|
|
733
738
|
`abort()` returns `true` only while cancellation is still accepted. Terminal persistence is the run's commit point; once it starts, `abort()` returns `false` and the already-fixed terminal outcome completes while the session remains busy.
|
|
734
739
|
|
|
740
|
+
### Session-local loading and startup recovery
|
|
741
|
+
|
|
742
|
+
The default `sessionLoading: 'eager'` preserves existing store behavior. Opt into `sessionLoading: 'session-local'` to load a complete metadata catalogue and hydrate only the session a request uses. Concurrent requests, including scope aliases of one storage key, join that session's hydration and repair. Creating an empty session reads none of the unrelated sessions' projections, permissions, events or jobs. `listSessions()` deliberately requests every session's repaired metadata; use `getScopeCatalogue()` or `listSessionIdentities()` for metadata-only enumeration.
|
|
743
|
+
|
|
744
|
+
```typescript
|
|
745
|
+
const harness = new FlexHarness({
|
|
746
|
+
scopeResolver,
|
|
747
|
+
modelResolver,
|
|
748
|
+
stores,
|
|
749
|
+
sessionLoading: 'session-local',
|
|
750
|
+
});
|
|
751
|
+
// Normal startup: recover indexed shared-workspace obligations and deletion tombstones.
|
|
752
|
+
await harness.prepareScope(scopeId);
|
|
753
|
+
const { sessions, recoverySessionIds } = await harness.getScopeCatalogue(scopeId);
|
|
754
|
+
```
|
|
755
|
+
|
|
756
|
+
Session-local loading requires `stores.scopes.sessionLocal`. Missing capabilities fail at construction; absent or stale qualification evidence fails before ordinary session use. There is no implicit eager fallback. On a legacy namespace, the host must exclusively own the namespace, excluding every scope alias and every old writer, and explicitly run `await harness.prepareScope(scopeId, { qualifyLegacy: true })`. This permits one complete load/repair and establishes authoritative recovery evidence. It is not a flag to put on every request. Scope retirement and disposal join owned target hydrations without hydrating cold sessions.
|
|
757
|
+
|
|
758
|
+
Shared-workspace recovery is not merely target-local: durable sidecar obligations are registered before capture preparation, application, finalization and release effects, and cleared only after canonical durable resolution. Startup gates on those obligations and tombstones, while unrelated sessions remain cold. Per-session repair still uses the canonical Agent event history and projection reconciliation.
|
|
759
|
+
|
|
760
|
+
#### Implementing `scopes.sessionLocal` on your own storage
|
|
761
|
+
|
|
762
|
+
A host that keeps Flex data in its own storage composes `new RecoverableFlexScopeStore(existingScopeStore, recoveryStore)` and implements `IFlexScopeRecoveryStore` for that storage. The scope snapshot stays exactly `{ schemaVersion, revision, sessions, tombstones }`; the proof is a separate record, `IFlexScopeRecoverySnapshot` `{ schemaVersion: 1, revision, catalogueRevision, catalogueDigest, recoverySessionIds }`, which `RecoverableFlexScopeStore` computes and the recovery store persists. A session-local load trusts a namespace only when the proof names the stored scope's revision and digest and the write provenance is current. The digest alone is never enough: a writer that does not know the proof (an older release, an eager harness, another tool) can write a projection's pending capture or apply, run its workspace effect and stop before it writes the scope, which leaves scope and proof byte for byte unchanged. The recovery store must meet this contract:
|
|
763
|
+
|
|
764
|
+
1. `save(storageKey, proof, expectedRevision)` is a durable compare-and-swap: it writes only when the stored revision equals `expectedRevision` and throws `FlexHarnessStoreConflictError` otherwise; an unknown outcome throws `FlexHarnessStoreCommitUncertainError`.
|
|
765
|
+
2. The provenance is a durable witness that every write in every domain of the namespace changes atomically with the write: scope, proof, projections, permissions, agent events and archives, tool jobs, results, project management, and every deletion or purge. Every writer that can open the namespace must change it, including releases that predate this contract, so it has to be a counter or header those writers already change, never a field only recovery-aware writers maintain. `NoSqlFlexHarnessStores` uses the namespace header's `creationCount`, which every write transaction increments since 12.1.1. Its releases 10.1.0 to 12.1.0 counted only record creations, so their projection, event and job updates change no witness: a namespace one of them may have written must be qualified explicitly before a session-local load.
|
|
766
|
+
3. A write of an activated instance is recorded as known atomically with the write (NoSQL: `recoveryWriteCount` in the same transaction); every other write is unknown. While activated, a write checks in the same atomic step that the witness still shows only known writes, and fails with `FlexHarnessStoreFormatError` instead of recording itself as known when it does not.
|
|
767
|
+
4. `loadWriteProvenance(storageKey)` reads metadata only, never history bodies, and returns `true` only if every write since the last qualification is known; it then activates the instance for that key. Otherwise it returns `false` and deactivates. It never repairs.
|
|
768
|
+
5. `deactivateWriteProvenance(storageKey)` is synchronous and local: afterwards the instance's writes are unknown. FlexHarness calls it on release, eager loading, disposal, retirement and whenever the evidence is not current.
|
|
769
|
+
6. `qualifyWriteProvenance(storageKey)` marks every write so far as known and activates. FlexHarness calls it only at the end of `prepareScope(scopeId, { qualifyLegacy: true })`, after the complete load and repair and after it published the new proof while inactive; when it fails, the namespace stays unqualified.
|
|
770
|
+
7. The witness never returns to an earlier value while the namespace holds data; an empty namespace (no scope, no proof, no records) may start over.
|
|
771
|
+
|
|
772
|
+
When the older releases of a host change no such witness, the host cannot detect their writes: it must not open the namespace with session-local loading after an older release may have written it, unless it qualifies explicitly first. Neither the provenance nor any compare-and-swap replaces the host's exclusive ownership of the namespace: no simultaneous writer, scope alias or older release.
|
|
773
|
+
|
|
774
|
+
In-memory and NoSQL stores implement the additive capability. Existing custom stores and `JsonFileFlexHarnessStores` keep their eager behavior; the JSON store creates no new recovery files and cannot opt into session-local loading without a separate capable backend.
|
|
775
|
+
|
|
735
776
|
### Continuing Without New Input
|
|
736
777
|
|
|
737
778
|
Use `continuePrompt()` after a failed or stopped run whose input remains in context
|
|
@@ -1050,7 +1091,7 @@ Resolved model identity contains provider and model IDs plus optional display na
|
|
|
1050
1091
|
|
|
1051
1092
|
Public audit history is safe to send to controllers: attachment parts contain source and size metadata, never inline base64, data URLs, or remote URL payloads. Canonical private Agent events retain those values solely for subsequent model turns.
|
|
1052
1093
|
|
|
1053
|
-
Sessions expose `idle`, `scheduled`, `running`, `waiting_permission`, `failed`, and `cancelled` status. A run stopped by `abort()`, `cancelPrompt()` or a rejected permission leaves its session `cancelled`; only a run that failed leaves it `failed`. Persisted non-terminal activity is repaired from canonical Agent generation outcomes after process restart; incomplete messages and parts normalize to `cancelled` unless an accepted hidden terminal stage can be promoted.
|
|
1094
|
+
Sessions expose `idle`, `scheduled`, `running`, `waiting_permission`, `failed`, and `cancelled` status. A run stopped by `abort()`, `cancelPrompt()` or a rejected permission leaves its session `cancelled`; only a run that failed leaves it `failed`. Persisted non-terminal activity is repaired from canonical Agent generation outcomes after process restart; incomplete messages and parts normalize to `cancelled` unless an accepted hidden terminal stage can be promoted; an interrupted turn's assistant message keeps the parts of its last checkpoint.
|
|
1054
1095
|
|
|
1055
1096
|
## Conversation Import
|
|
1056
1097
|
|
|
@@ -1158,7 +1199,9 @@ FlexHarness wraps every provided tool `execute` method before AgentSession recei
|
|
|
1158
1199
|
|
|
1159
1200
|
`toolOutputLimits` in the complete setup above bounds traversal depth and encoded bytes. The normalizer enforces its byte allowance incrementally: oversized strings are replaced before entering output, and arrays/objects stop reading entries once only truncation metadata fits.
|
|
1160
1201
|
|
|
1161
|
-
Streaming callbacks use run-local synchronous state rather than one persistence promise per source delta. Text and reasoning accumulate only in the run-local terminal projection while each source delta remains an immediate exact public event. Every distinct async-iterable tool output appears immediately as a bounded cumulative `part.updated` snapshot while the tool remains `running`, including the final yielded value before completion. Only the authoritative `part.completed` output enters the terminal projection, and failed or interrupted tools discard their transient output. `callbackLimits` bounds callback events, accumulated output bytes, and part count; overflow aborts internally with `FlexHarnessCallbackOverflowError` and the turn is recorded as failed. The calls of a `run_code` program never overflow it: they stop their program at its `callbacks` limit instead. Reservation and terminal finalization are the normal persistence
|
|
1202
|
+
Streaming callbacks use run-local synchronous state rather than one persistence promise per source delta. Text and reasoning accumulate only in the run-local terminal projection while each source delta remains an immediate exact public event. Every distinct async-iterable tool output appears immediately as a bounded cumulative `part.updated` snapshot while the tool remains `running`, including the final yielded value before completion. Only the authoritative `part.completed` output enters the terminal projection, and failed or interrupted tools discard their transient output. `callbackLimits` bounds callback events, accumulated output bytes, and part count; overflow aborts internally with `FlexHarnessCallbackOverflowError` and the turn is recorded as failed. The calls of a `run_code` program never overflow it: they stop their program at its `callbacks` limit instead. Reservation and terminal finalization are the normal persistence points, with permission state changes and the projection checkpoints of a running turn (below) as additional ones.
|
|
1203
|
+
|
|
1204
|
+
While a turn runs, its streaming assistant message is checkpointed. A checkpoint saves the parts of the model steps the turn committed (the engine saves a step's events before the step ends), each as it stands, in place of the message's parts, in one projection save in the session's projection FIFO. It starts no earlier than the larger of 10 s and 20 times the duration of the turn's last save of that message (its start, a steer split or the previous checkpoint), counted from that save's completion, so a turn shorter than that saves none. At most one is outstanding per turn; its deadline timer does not keep the process alive and fires also when no further step commits. The terminal, a steer split, the turn's close and the namespace's drain, disposal, fence or retirement end the pending one. A process that stops mid-turn therefore leaves the committed steps up to its last completed checkpoint visible, at most the current spacing plus one save behind; the next load repairs the message to `cancelled` as before, its running parts `cancelled`, and never rebuilds parts from events. The visible parts are always a prefix of the committed steps: nothing of the step in progress is saved, neither its text nor a tool call it streamed or started, although a call that started is in the model context (its call and execution intent are saved before it runs). Checkpoints emit no event. A failed checkpoint save fails the turn like its other saves, with a `persistence` error, and an uncertain one fences the namespace. `projectionCheckpointClock` (an `IFlexCacheWarmClock`) lets tests drive the timing; the spacing is fixed.
|
|
1162
1205
|
|
|
1163
1206
|
Model resolver, tool provider, delegated run admission provider, AgentSession, tool execution, tool callback, tool cleanup, and run-persistence failures cross an untrusted error boundary. By default they become a fixed immutable `FlexHarnessExternalError` before completion rejection, persistence, events, or detached-cleanup reporting. Raw external messages and aggregate members are not retained. A failed `onToolCallFinish` callback stores and accounts for only the bounded projected message; it does not otherwise reject completion, although exceeding the configured callback limits still fails the run. Scope resolution and the initial store load happen before a run exists and remain outside this boundary.
|
|
1164
1207
|
|
|
@@ -395,17 +395,32 @@ export function normalizeSlashCommands<TScope>(
|
|
|
395
395
|
return Object.freeze(normalized);
|
|
396
396
|
}
|
|
397
397
|
|
|
398
|
-
const
|
|
398
|
+
const systemClock: IFlexCacheWarmClock = Object.freeze({
|
|
399
399
|
now: () => Date.now(),
|
|
400
400
|
setTimeout: (callback: () => void, delayMs: number) => {
|
|
401
401
|
const handle = setTimeout(callback, delayMs);
|
|
402
|
-
//
|
|
402
|
+
// Neither a warm period nor a pending projection checkpoint holds the process open.
|
|
403
403
|
handle.unref?.();
|
|
404
404
|
return handle;
|
|
405
405
|
},
|
|
406
406
|
clearTimeout: (handle: unknown) => clearTimeout(handle as ReturnType<typeof setTimeout>),
|
|
407
407
|
});
|
|
408
408
|
|
|
409
|
+
/** The clock `name` gives, checked; the system clock, whose timers are unref'd, by default. */
|
|
410
|
+
export function normalizeClock(clock: IFlexCacheWarmClock | undefined, name: string): IFlexCacheWarmClock {
|
|
411
|
+
const resolved: unknown = clock ?? systemClock;
|
|
412
|
+
if (
|
|
413
|
+
!resolved
|
|
414
|
+
|| typeof resolved !== 'object'
|
|
415
|
+
|| typeof (resolved as IFlexCacheWarmClock).now !== 'function'
|
|
416
|
+
|| typeof (resolved as IFlexCacheWarmClock).setTimeout !== 'function'
|
|
417
|
+
|| typeof (resolved as IFlexCacheWarmClock).clearTimeout !== 'function'
|
|
418
|
+
) {
|
|
419
|
+
throw new FlexHarnessValidationError(`${name} must provide now, setTimeout and clearTimeout.`);
|
|
420
|
+
}
|
|
421
|
+
return resolved as IFlexCacheWarmClock;
|
|
422
|
+
}
|
|
423
|
+
|
|
409
424
|
export function normalizeCacheWarmOptions(
|
|
410
425
|
input: IFlexHarnessOptions<unknown>['cacheWarm'],
|
|
411
426
|
): INormalizedCacheWarmOptions {
|
|
@@ -416,16 +431,7 @@ export function normalizeCacheWarmOptions(
|
|
|
416
431
|
const unsupported = Object.keys(options)
|
|
417
432
|
.find((key) => !['maxDurationMs', 'maxOutputTokens', 'clock'].includes(key));
|
|
418
433
|
if (unsupported) throw new FlexHarnessValidationError(`cacheWarm does not support "${unsupported}".`);
|
|
419
|
-
const clock
|
|
420
|
-
if (
|
|
421
|
-
!clock
|
|
422
|
-
|| typeof clock !== 'object'
|
|
423
|
-
|| typeof clock.now !== 'function'
|
|
424
|
-
|| typeof clock.setTimeout !== 'function'
|
|
425
|
-
|| typeof clock.clearTimeout !== 'function'
|
|
426
|
-
) {
|
|
427
|
-
throw new FlexHarnessValidationError('cacheWarm.clock must provide now, setTimeout and clearTimeout.');
|
|
428
|
-
}
|
|
434
|
+
const clock = normalizeClock(options.clock, 'cacheWarm.clock');
|
|
429
435
|
return Object.freeze({
|
|
430
436
|
maxDurationMs: resolveBoundedPositiveInteger(
|
|
431
437
|
options.maxDurationMs,
|
package/ts/utils.json.ts
CHANGED
|
@@ -23,6 +23,7 @@ import type {
|
|
|
23
23
|
TJsonValue,
|
|
24
24
|
} from './interfaces.js';
|
|
25
25
|
import { sliceUtf16 } from './utils.text.js';
|
|
26
|
+
import type { FlexTimeSlicer } from './classes.timeslicer.js';
|
|
26
27
|
import { isValidSessionConfigurationRef } from './utils.validation.js';
|
|
27
28
|
|
|
28
29
|
const DEFAULT_MAX_DEPTH = 12;
|
|
@@ -346,22 +347,8 @@ function failJsonWalk(walk: IJsonWalk, message: string): never {
|
|
|
346
347
|
throw new FlexHarnessStoreFormatError(`${path} ${message}`);
|
|
347
348
|
}
|
|
348
349
|
|
|
349
|
-
/**
|
|
350
|
-
|
|
351
|
-
* `JSON.parse(JSON.stringify(value))` would return, built in the same pass.
|
|
352
|
-
*/
|
|
353
|
-
function walkJsonValue(walk: IJsonWalk, value: unknown): unknown {
|
|
354
|
-
if (value === null || typeof value === 'string' || typeof value === 'boolean') {
|
|
355
|
-
return value;
|
|
356
|
-
}
|
|
357
|
-
if (typeof value === 'number') {
|
|
358
|
-
if (!Number.isFinite(value)) failJsonWalk(walk, 'contains a non-finite number.');
|
|
359
|
-
// JSON writes -0 as 0.
|
|
360
|
-
return value === 0 ? 0 : value;
|
|
361
|
-
}
|
|
362
|
-
if (typeof value !== 'object') {
|
|
363
|
-
failJsonWalk(walk, `contains ${typeof value}, which is not JSON-safe.`);
|
|
364
|
-
}
|
|
350
|
+
/** Rejects an object or array that is not a JSON container where the walk stands. */
|
|
351
|
+
function assertJsonContainer(walk: IJsonWalk, value: object): void {
|
|
365
352
|
if (walk.ancestors.includes(value)) {
|
|
366
353
|
failJsonWalk(walk, 'contains a circular reference.');
|
|
367
354
|
}
|
|
@@ -371,8 +358,6 @@ function walkJsonValue(walk: IJsonWalk, value: unknown): unknown {
|
|
|
371
358
|
if (Object.getOwnPropertySymbols(value).length > 0) {
|
|
372
359
|
failJsonWalk(walk, 'contains a symbol-keyed property.');
|
|
373
360
|
}
|
|
374
|
-
walk.ancestors.push(value);
|
|
375
|
-
let copy: unknown;
|
|
376
361
|
if (Array.isArray(value)) {
|
|
377
362
|
const length = value.length;
|
|
378
363
|
// Own names list array indices in ascending order, then `length`, then any other keys, so a
|
|
@@ -392,6 +377,30 @@ function walkJsonValue(walk: IJsonWalk, value: unknown): unknown {
|
|
|
392
377
|
failJsonWalk(walk, 'is not JSON-visible.');
|
|
393
378
|
}
|
|
394
379
|
}
|
|
380
|
+
}
|
|
381
|
+
}
|
|
382
|
+
|
|
383
|
+
/**
|
|
384
|
+
* Rejects anything a JSON round trip would not preserve. With `walk.copy` it also returns the copy
|
|
385
|
+
* `JSON.parse(JSON.stringify(value))` would return, built in the same pass.
|
|
386
|
+
*/
|
|
387
|
+
function walkJsonValue(walk: IJsonWalk, value: unknown): unknown {
|
|
388
|
+
if (value === null || typeof value === 'string' || typeof value === 'boolean') {
|
|
389
|
+
return value;
|
|
390
|
+
}
|
|
391
|
+
if (typeof value === 'number') {
|
|
392
|
+
if (!Number.isFinite(value)) failJsonWalk(walk, 'contains a non-finite number.');
|
|
393
|
+
// JSON writes -0 as 0.
|
|
394
|
+
return value === 0 ? 0 : value;
|
|
395
|
+
}
|
|
396
|
+
if (typeof value !== 'object') {
|
|
397
|
+
failJsonWalk(walk, `contains ${typeof value}, which is not JSON-safe.`);
|
|
398
|
+
}
|
|
399
|
+
assertJsonContainer(walk, value);
|
|
400
|
+
walk.ancestors.push(value);
|
|
401
|
+
let copy: unknown;
|
|
402
|
+
if (Array.isArray(value)) {
|
|
403
|
+
const length = value.length;
|
|
395
404
|
const items: unknown[] | undefined = walk.copy ? [] : undefined;
|
|
396
405
|
const known = walk.knownEntries?.get(value) ?? 0;
|
|
397
406
|
for (let index = 0; index < length; index++) {
|
|
@@ -2292,6 +2301,49 @@ export function cloneSerializable<T>(value: T): T {
|
|
|
2292
2301
|
return walkJsonValue({ root: '$', segments: [], ancestors: [], copy: true }, value) as T;
|
|
2293
2302
|
}
|
|
2294
2303
|
|
|
2304
|
+
/**
|
|
2305
|
+
* `cloneSerializable(value)` in slices: the same copy and the same error for a value that is not
|
|
2306
|
+
* JSON, pausing through `slicer` between the entries of `value`. Each entry is copied whole.
|
|
2307
|
+
*/
|
|
2308
|
+
export async function cloneSerializableSliced<T>(value: T, slicer: FlexTimeSlicer): Promise<T> {
|
|
2309
|
+
const walk: IJsonWalk = { root: '$', segments: [], ancestors: [], copy: true };
|
|
2310
|
+
if (value === null || typeof value !== 'object') return walkJsonValue(walk, value) as T;
|
|
2311
|
+
assertJsonContainer(walk, value);
|
|
2312
|
+
walk.ancestors.push(value);
|
|
2313
|
+
let copy: unknown;
|
|
2314
|
+
if (Array.isArray(value)) {
|
|
2315
|
+
const items: unknown[] = [];
|
|
2316
|
+
for (let index = 0; index < value.length; index++) {
|
|
2317
|
+
walk.segments.push(index);
|
|
2318
|
+
if (!(index in value)) failJsonWalk(walk, 'is a sparse array entry.');
|
|
2319
|
+
items.push(walkJsonValue(walk, value[index]));
|
|
2320
|
+
walk.segments.pop();
|
|
2321
|
+
if (slicer.due) await slicer.pause();
|
|
2322
|
+
}
|
|
2323
|
+
copy = items;
|
|
2324
|
+
} else {
|
|
2325
|
+
const fields: Record<string, unknown> = {};
|
|
2326
|
+
for (const key of Object.getOwnPropertyNames(value)) {
|
|
2327
|
+
const descriptor = Object.getOwnPropertyDescriptor(value, key)!;
|
|
2328
|
+
walk.segments.push(key);
|
|
2329
|
+
if (!descriptor.enumerable || !('value' in descriptor)) {
|
|
2330
|
+
failJsonWalk(walk, 'is not a plain JSON property.');
|
|
2331
|
+
}
|
|
2332
|
+
const field = walkJsonValue(walk, descriptor.value);
|
|
2333
|
+
if (key in fields) {
|
|
2334
|
+
Object.defineProperty(fields, key, { value: field, enumerable: true, writable: true, configurable: true });
|
|
2335
|
+
} else {
|
|
2336
|
+
fields[key] = field;
|
|
2337
|
+
}
|
|
2338
|
+
walk.segments.pop();
|
|
2339
|
+
if (slicer.due) await slicer.pause();
|
|
2340
|
+
}
|
|
2341
|
+
copy = fields;
|
|
2342
|
+
}
|
|
2343
|
+
walk.ancestors.pop();
|
|
2344
|
+
return copy as T;
|
|
2345
|
+
}
|
|
2346
|
+
|
|
2295
2347
|
export function deepFreeze<T>(value: T): T {
|
|
2296
2348
|
if (!value || typeof value !== 'object' || Object.isFrozen(value)) {
|
|
2297
2349
|
return value;
|
|
@@ -0,0 +1,75 @@
|
|
|
1
|
+
import * as plugins from './plugins.js';
|
|
2
|
+
import type { IFlexScopeSnapshot, IFlexSession, IFlexSessionIdentity } from './interfaces.js';
|
|
3
|
+
import { cloneSerializable } from './utils.json.js';
|
|
4
|
+
import { requireSessionGeneration } from './utils.flexharness.js';
|
|
5
|
+
|
|
6
|
+
function deriveLegacySessionGenerationId(
|
|
7
|
+
storageKey: string,
|
|
8
|
+
sessionId: string,
|
|
9
|
+
createdAt: string,
|
|
10
|
+
): string {
|
|
11
|
+
const digest = plugins.crypto.createHash('sha256').update(JSON.stringify([
|
|
12
|
+
'flexharness-legacy-session-generation-v1',
|
|
13
|
+
storageKey,
|
|
14
|
+
sessionId,
|
|
15
|
+
createdAt,
|
|
16
|
+
])).digest('hex');
|
|
17
|
+
return `legacy_${digest}`;
|
|
18
|
+
}
|
|
19
|
+
|
|
20
|
+
/**
|
|
21
|
+
* The scope a store holds as the harness works with it: a copy of `stored`, or the empty scope,
|
|
22
|
+
* whose sessions and tombstones stored before session generations existed carry the generation
|
|
23
|
+
* derived for them. `changed` says whether any did; the scope load then saves the copy.
|
|
24
|
+
*/
|
|
25
|
+
export function normalizeScopeSnapshot(
|
|
26
|
+
storageKey: string,
|
|
27
|
+
stored: IFlexScopeSnapshot | undefined,
|
|
28
|
+
): { snapshot: IFlexScopeSnapshot; changed: boolean } {
|
|
29
|
+
const snapshot = cloneSerializable(stored ?? {
|
|
30
|
+
schemaVersion: 1,
|
|
31
|
+
revision: 0,
|
|
32
|
+
sessions: [],
|
|
33
|
+
tombstones: [],
|
|
34
|
+
} satisfies IFlexScopeSnapshot);
|
|
35
|
+
let changed = false;
|
|
36
|
+
const repairedGenerationSequence = snapshot.revision + 1;
|
|
37
|
+
for (const session of snapshot.sessions) {
|
|
38
|
+
if (session.sessionGenerationId !== undefined) continue;
|
|
39
|
+
session.sessionGenerationId = deriveLegacySessionGenerationId(
|
|
40
|
+
storageKey,
|
|
41
|
+
session.sessionId,
|
|
42
|
+
session.createdAt,
|
|
43
|
+
);
|
|
44
|
+
session.sessionGenerationSequence = repairedGenerationSequence;
|
|
45
|
+
changed = true;
|
|
46
|
+
}
|
|
47
|
+
for (const tombstone of snapshot.tombstones) {
|
|
48
|
+
if (tombstone.sessionGenerationId !== undefined) continue;
|
|
49
|
+
tombstone.sessionGenerationId = deriveLegacySessionGenerationId(
|
|
50
|
+
storageKey,
|
|
51
|
+
tombstone.sessionId,
|
|
52
|
+
tombstone.deletedAt,
|
|
53
|
+
);
|
|
54
|
+
tombstone.sessionGenerationSequence = repairedGenerationSequence;
|
|
55
|
+
changed = true;
|
|
56
|
+
}
|
|
57
|
+
return { snapshot, changed };
|
|
58
|
+
}
|
|
59
|
+
|
|
60
|
+
/** The sessions of a scope snapshot that no tombstone deletes, in snapshot order. */
|
|
61
|
+
export function liveScopeSessions(snapshot: IFlexScopeSnapshot): IFlexSession[] {
|
|
62
|
+
const tombstoned = new Set(snapshot.tombstones.map((tombstone) => tombstone.sessionId));
|
|
63
|
+
return snapshot.sessions.filter((session) => !tombstoned.has(session.sessionId));
|
|
64
|
+
}
|
|
65
|
+
|
|
66
|
+
/** The identities of `sessions`, sorted by session id as scope snapshots are. */
|
|
67
|
+
export function sessionIdentities(sessions: Iterable<IFlexSession>): IFlexSessionIdentity[] {
|
|
68
|
+
return [...sessions]
|
|
69
|
+
.map((session): IFlexSessionIdentity => ({
|
|
70
|
+
sessionId: session.sessionId,
|
|
71
|
+
...requireSessionGeneration(session),
|
|
72
|
+
...(session.parentSessionId === undefined ? {} : { parentSessionId: session.parentSessionId }),
|
|
73
|
+
}))
|
|
74
|
+
.sort((left, right) => left.sessionId.localeCompare(right.sessionId));
|
|
75
|
+
}
|