@modelprofile.com/flexharness 16.3.0 → 17.0.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.core.d.ts +6 -0
- package/dist_ts/classes.flexharness.core.js +28 -15
- package/dist_ts/classes.flexharness.d.ts +6 -1
- package/dist_ts/classes.flexharness.js +8 -1
- package/dist_ts/classes.flexharness.projects.d.ts +10 -0
- package/dist_ts/classes.flexharness.projects.js +48 -21
- package/dist_ts/classes.flexharness.prompts.js +5 -3
- package/dist_ts/classes.flexharness.runs.js +6 -3
- package/dist_ts/classes.flexharness.sessions.d.ts +8 -1
- package/dist_ts/classes.flexharness.sessions.js +30 -20
- package/dist_ts/index.d.ts +1 -1
- package/dist_ts/index.js +2 -2
- package/dist_ts/interfaces.d.ts +42 -0
- package/dist_ts/interfaces.flexharness.d.ts +8 -0
- package/dist_ts/interfaces.js +1 -1
- package/dist_ts/utils.json.d.ts +21 -1
- package/dist_ts/utils.json.js +432 -191
- package/dist_ts/utils.projectionchange.d.ts +12 -2
- package/dist_ts/utils.projectionchange.js +41 -22
- package/dist_ts/utils.transfer.d.ts +15 -1
- package/dist_ts/utils.transfer.js +55 -7
- package/dist_ts/utils.validation.d.ts +3 -1
- package/dist_ts/utils.validation.js +19 -1
- package/package.json +3 -3
- package/readme.md +32 -4
- package/ts/00_commitinfo_data.ts +1 -1
- package/ts/classes.flexharness.core.ts +29 -20
- package/ts/classes.flexharness.projects.ts +57 -29
- package/ts/classes.flexharness.prompts.ts +4 -2
- package/ts/classes.flexharness.runs.ts +5 -2
- package/ts/classes.flexharness.sessions.ts +49 -19
- package/ts/classes.flexharness.ts +13 -0
- package/ts/index.ts +1 -0
- package/ts/interfaces.flexharness.ts +5 -0
- package/ts/interfaces.ts +59 -0
- package/ts/readme.md +32 -4
- package/ts/utils.json.ts +521 -198
- package/ts/utils.projectionchange.ts +62 -26
- package/ts/utils.transfer.ts +68 -6
- package/ts/utils.validation.ts +19 -0
package/ts/readme.md
CHANGED
|
@@ -427,7 +427,7 @@ The tools use strict action-discriminated inputs:
|
|
|
427
427
|
- `rename_session`: sets the active session title and returns the authoritative session.
|
|
428
428
|
- `keep_cache_warm` (`cacheWarm: true`, root sessions only): keeps the session's prompt cache warm; see [Keeping the Prompt Cache Warm](#keeping-the-prompt-cache-warm).
|
|
429
429
|
|
|
430
|
-
Every project
|
|
430
|
+
Every project API returns the authoritative revision and state; task mutations also return the affected task, and clear returns the removed tasks. The model tools return the authoritative revision with only the field they read or the item they changed, so their results do not grow with the rest of the state: `task` returns `{ revision, tasks }` for `list` and for `clear` (the removed tasks) and `{ revision, task }` for `create`, `update` and `delete`; `goal` returns `{ revision, goal }`, `null` when none is set; `scratchpad` returns `{ revision, scratchpad }` for `get` and `{ revision, scratchpadBytes }`, the scratchpad's size in UTF-8 bytes, for `set`, `append` and `clear`. No tool returns the whole state, so a tool never shows fields of tools the host did not enable; reads that return the same revision are one consistent view. Reads never save. A set, clear, append, update, idempotent create, or empty task clear that makes no state change returns the current revision without writing. Mutations load once, apply once, validate the complete next snapshot, and issue one compare-and-swap save at `revision + 1`. FlexHarness never retries or merges an external conflict.
|
|
431
431
|
|
|
432
432
|
Tool task creation accepts an optional `id`. When omitted, FlexHarness requires the stable AgentSession `toolCallId` and derives `task_` plus the SHA-256 of `JSON.stringify(['flexharness-project-task-v1', storageKey, sessionId, runId, toolCallId])`. Repeating an explicit or deterministic ID with identical content, status, and priority is idempotent; different creation data conflicts. Application callers must supply an explicit `id` to `createProjectTask()` because no tool-call identity exists at that boundary.
|
|
433
433
|
|
|
@@ -627,7 +627,7 @@ Attachment payloads are never copied into public audit messages or events. Publi
|
|
|
627
627
|
}
|
|
628
628
|
```
|
|
629
629
|
|
|
630
|
-
The original string remains only in canonical private Agent events, so a later model turn can receive the attachment again. Successful turns stay in future context. Failed, stopped, rejected and restart-interrupted generations also retain their prompt, applied steers and recorded partial model/tool output once execution started and produced output. Their model-visible outcome marker truthfully says rejected, interrupted or stopped by owner, never successful. An unsuccessful generation with no model/tool output stays out of future context; its `run.finished` event and finished queue entry carry `keptInContext: false`. An unresolved tool call is closed in model context with an error result saying its effect is unknown: this does not assert that the action failed, succeeded or was rolled back. Restoring history never automatically reruns the generation or replays tools; inspect `listUncertainToolExecutions()` and reconcile external effects before treating them as known. Resolver, cleanup and persistence failures still reject completion; retention depends on durable canonical output and outcome, not the failure label.
|
|
630
|
+
The original string remains only in canonical private Agent events, so a later model turn can receive the attachment again. Successful turns stay in future context, except cache-warm turns (see [Keeping the Prompt Cache Warm](#keeping-the-prompt-cache-warm)). Failed, stopped, rejected and restart-interrupted generations also retain their prompt, applied steers and recorded partial model/tool output once execution started and produced output. Their model-visible outcome marker truthfully says rejected, interrupted or stopped by owner, never successful. An unsuccessful generation with no model/tool output stays out of future context; its `run.finished` event and finished queue entry carry `keptInContext: false`. An unresolved tool call is closed in model context with an error result saying its effect is unknown: this does not assert that the action failed, succeeded or was rolled back. Restoring history never automatically reruns the generation or replays tools; inspect `listUncertainToolExecutions()` and reconcile external effects before treating them as known. Resolver, cleanup and persistence failures still reject completion; retention depends on durable canonical output and outcome, not the failure label.
|
|
631
631
|
|
|
632
632
|
The main session methods are:
|
|
633
633
|
|
|
@@ -637,6 +637,7 @@ await harness.createSession(scopeId, { sessionId, sessionGenerationId, title });
|
|
|
637
637
|
await harness.getSession(scopeId, sessionId);
|
|
638
638
|
await harness.getMessages(scopeId, sessionId);
|
|
639
639
|
await harness.listMessagePage(scopeId, sessionId, { limit: 50, before: cursor });
|
|
640
|
+
await harness.listMessageMetadataPage(scopeId, sessionId, { limit: 50, includeUndone: true });
|
|
640
641
|
await harness.getMessage(scopeId, sessionId, messageId);
|
|
641
642
|
await harness.listSlashCommands(scopeId, sessionId);
|
|
642
643
|
const command = await harness.executeSlashCommand(scopeId, sessionId, '/init focus on tests');
|
|
@@ -717,6 +718,8 @@ The reservation save is the admission point. A save failure produces no start ev
|
|
|
717
718
|
|
|
718
719
|
`listMessagePage()` returns the newest contiguous page in chronological order. `limit` must be an integer from 1 through 50 and defaults to 50. `nextCursor` is opaque, limited to 4096 UTF-8 bytes, bound to the resolved storage namespace and session, and remains stable when newer messages are appended. Mismatched and stale cursors fail validation. Each page carries `startIndex`, the zero-based index of its first message in the session's visible history (for an empty page, the index the page ends at), so a consumer can order and page by absolute position. Appending messages leaves every index unchanged; a branch after an undo reuses the positions of the history it replaces, so a consumer re-reads its pages after `session.history.changed`. `getMessage()` performs an exact lookup. `getMessages()`, `listMessagePage()`, `getMessage()` and `getSessionView()` take `includeUndone: true` to also return the messages of undone turns, which a redo can bring back: they follow the visible messages in their place, each marked `undone: true`, and page indexes count them. `undone` is set only by such a read and never stored. Messages a committed branch removed are gone and no read returns them. Transfer identifiers are limited to 512 bytes, text and reasoning parts to 96 KiB, complete messages to 480 KiB, and complete page envelopes to 512 KiB. A page may therefore contain fewer messages than requested. Oversized text is truncated and an otherwise oversized parts collection is replaced with an explicit elision marker; metadata that still cannot fit fails validation. Canonical private Agent events are unchanged.
|
|
719
720
|
|
|
721
|
+
`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.
|
|
722
|
+
|
|
720
723
|
`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 and active 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.
|
|
721
724
|
|
|
722
725
|
`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.
|
|
@@ -794,6 +797,31 @@ A prompt can bring further user messages into its run: `startPrompt()`, `enqueue
|
|
|
794
797
|
|
|
795
798
|
A prompt can name itself with `promptId` in its options (`startPrompt()`, `enqueuePrompt()`, `prompt()` and `schedulePrompt()`): a non-empty string of at most 512 UTF-8 bytes, validated like a `steerId`. It is on the prompt's queue entry and its queue events, and on the user message that heads its run, also after a restart, so a caller that is unsure whether a prompt was taken in finds out from the transcript. A prompt whose `promptId` an outstanding prompt of the same session, queued or running, already holds is refused with `FlexHarnessDuplicatePromptError`; once that prompt finished, the id is free again. Other sessions' prompts do not count.
|
|
796
799
|
|
|
800
|
+
### Pinned Context
|
|
801
|
+
|
|
802
|
+
Text the model must always see in its current form, such as a host's working notes, belongs in `pinnedContext` of the resolved model, not in `system`. The system prompt and the tool definitions open every request, so any change there makes the provider write the whole cached prefix again; a pinned context changes nothing in front of the history:
|
|
803
|
+
|
|
804
|
+
```typescript
|
|
805
|
+
async resolveModel(context): Promise<IFlexResolvedModel> {
|
|
806
|
+
const notes = await notesStore.read(context.sessionId);
|
|
807
|
+
return {
|
|
808
|
+
...configuredModel,
|
|
809
|
+
system: stableInstructions,
|
|
810
|
+
pinnedContext: { id: 'notes', revision: notes.revision, text: notes.text },
|
|
811
|
+
};
|
|
812
|
+
}
|
|
813
|
+
```
|
|
814
|
+
|
|
815
|
+
FlexHarness keeps the current revision of each pinned id in the model-visible context exactly once after the latest compaction. When a run starts and the model-visible context does not show this revision as the id's latest (it shows an earlier one, or none), the run appends a pinned context message, which the model sees right before the run's prompt:
|
|
816
|
+
|
|
817
|
+
```text
|
|
818
|
+
[Pinned context "notes", revision 7. This is its current text; it replaces every earlier revision of "notes".]
|
|
819
|
+
|
|
820
|
+
<the text>
|
|
821
|
+
```
|
|
822
|
+
|
|
823
|
+
Earlier revisions stay where they are in the history, so everything in front of the new message is byte for byte the previous request. A compaction ends its summary with the latest revision of each pinned id it covered, unless the run it compacts for brought that id itself. FlexHarness keeps no record beside the conversation: the revision it compares with is read from the model-visible messages, so a run that leaves the context (undone, or failed before its model produced anything) takes its pinned context message along and the next run appends it again, and a restarted harness reads it back from `stores.agentEvents`. A changed text needs a new revision, a non-negative safe integer: FlexHarness compares revisions, never texts. The message is model context only, never a message of `getMessages()`. An invalid `pinnedContext` (an empty id, a revision that is not a non-negative safe integer, a text that is not a string, any other member) fails the run as the model resolver's failure. `pinnedContextMessageContent()` of `@modelprofile.com/flexharness-agent` renders the message.
|
|
824
|
+
|
|
797
825
|
### Keeping the Prompt Cache Warm
|
|
798
826
|
|
|
799
827
|
A provider's prompt cache expires when nothing reads it for its TTL, and the next turn then writes the whole prefix again. `keepCacheWarm()` keeps a root session's cache warm until a deadline:
|
|
@@ -814,7 +842,7 @@ Each call replaces the deadline with `durationMs` from now, capped at `cacheWarm
|
|
|
814
842
|
| `openai-in-memory` | 5 min | OpenAI's API, an earlier model with `in_memory` or no retention; or the ChatGPT backend of ChatGPT accounts, which takes no retention and documents none. In-memory entries last 5 to 10 minutes of inactivity |
|
|
815
843
|
| `configured` | `cache.warmDurationMs` | any |
|
|
816
844
|
|
|
817
|
-
With no basis (another provider or endpoint, or a custom transport that may change the request) the TTL is 5 minutes. No OpenAI retention promises a hit beyond about 30 minutes, so none makes warming unnecessary; extended retention only spaces warm turns further apart. Source: OpenAI's [prompt caching guide](https://developers.openai.com/api/docs/guides/prompt-caching), read 2026-10-11. A prompt, a steer or a running turn resets the wait, and no warm prompt is sent while a turn runs, a prompt is queued, an undo's redo history is open, a reversion is pending or a slash command runs. The warm prompt is the fixed text `FLEX_CACHE_WARM_PROMPT`, starting with `[cache-warm]`, which asks for the single word `ok`. Its turn uses the model and system of the session's last turn and offers the same tools, so it reads the cached prefix, but it refuses every tool call, takes at most two steps, caps each model call at `cacheWarm.maxOutputTokens` (default 1024) and takes no steer: `steerPrompt()` refuses one with reason `not-running`. Keeping a session warm costs a cache read of its prefix and a few new tokens per warm turn
|
|
845
|
+
With no basis (another provider or endpoint, or a custom transport that may change the request) the TTL is 5 minutes. No OpenAI retention promises a hit beyond about 30 minutes, so none makes warming unnecessary; extended retention only spaces warm turns further apart. Source: OpenAI's [prompt caching guide](https://developers.openai.com/api/docs/guides/prompt-caching), read 2026-10-11. A prompt, a steer or a running turn resets the wait, and no warm prompt is sent while a turn runs, a prompt is queued, an undo's redo history is open, a reversion is pending or a slash command runs. The warm prompt is the fixed text `FLEX_CACHE_WARM_PROMPT`, starting with `[cache-warm]`, which asks for the single word `ok`. Its turn uses the model and system of the session's last turn and offers the same tools, so it reads the cached prefix, but it refuses every tool call, takes at most two steps, caps each model call at `cacheWarm.maxOutputTokens` (default 1024) and takes no steer: `steerPrompt()` refuses one with reason `not-running`. Keeping a session warm costs a cache read of its prefix and a few new tokens per warm turn. A warm exchange leaves the model context with its outcome: no later model call sees its prompt or its answer, so the next real turn continues the context the warm turn read and shares the prefix it kept cached. The warm turn keeps its single outcome, its usage, its `model.usage` and `cache.warm.*` events and its marked transcript messages; its prompt reports `keptInContext: false`, as do its run's `run.finished` and finished queue entry.
|
|
818
846
|
|
|
819
847
|
Warm turns are marked so hosts can leave them out of what they show and of what they count as work: both messages, the session `activity`, the prompt queue entry, `run.started`, `run.finished` and `model.usage` carry `cacheWarm: true`. A warm turn changes neither the session's `updatedAt` nor its `preview`, and adds no undo step. Three events report the keeper: `cache.warm.changed` (`source` `host` or `agent`, `warmUntil` absent once stopped), `cache.warm.completed` with the warm turn's `usage`, whose `cacheReadTokens` and `cacheWriteTokens` are the provider's own counts and show whether it hit the cache (OpenAI's `input_tokens_details.cached_tokens` and `cache_write_tokens`, Anthropic's `cache_read_input_tokens` and `cache_creation_input_tokens`), its `idleForMs` since the session's previous model call and its `basis`, and `cache.warm.stopped` with `reason` `deadline`, `cleared`, `failed` (the warm turn failed; `error` set) or `unavailable` (the session or its scope went away).
|
|
820
848
|
|
|
@@ -1263,7 +1291,7 @@ Current FlexHarness persistence is separated by trust and lifecycle domain throu
|
|
|
1263
1291
|
|
|
1264
1292
|
A custom store validates what it loads and saves with the validators the built-in stores apply. Each throws `FlexHarnessStoreFormatError` for a malformed or wrong-schema snapshot: `assertFlexScopeSnapshot()`, `assertFlexProjectionSnapshot(value, sessionId)`, which also requires every message and staged terminal to belong to `sessionId`, `assertFlexPermissionSnapshot()`, `assertFlexProjectManagementRecord()` and `assertFlexToolJobSnapshot()`. Agent event snapshots and archives have `validateAgentEventSnapshot()` and `validateAgentEventArchive()` in `@modelprofile.com/flexharness-agent`.
|
|
1265
1293
|
|
|
1266
|
-
Projections and Agent event histories are saved as changes, so a save costs what changed rather than the whole session. `IFlexProjectionStore.save(storageKey, sessionId, change, expectedRevision)` receives an `IFlexProjectionChange`: the schema-3 projection with `messages` and `reversionSegments` given as `IFlexListChange`s `{ start, end, items }`, each of which keeps the stored entries from `start` up to `end` and appends `items`. A list change with `start` and `end` at 0 replaces the list whole; FlexHarness sends whole lists when it cannot know which entries the store holds: for a projection it loaded in an older schema and after a save with an uncertain outcome. The Agent event store of each session receives an `IAgentEventChange` of removed, replaced and appended events, as the `@modelprofile.com/flexharness-agent` readme describes. A store that keeps snapshots checks a change's form with `assertFlexProjectionChange()` or `assertAgentEventChange()`, applies it with `applyFlexProjectionChange()` or `applyAgentEventChange()`, and validates the result as above; `createWholeProjectionChange(snapshot)` makes the change that stores a projection whole. FlexHarness freezes every message and reversion segment it saved and replaces an entry instead of editing it, which is how it tells the entries the store already holds. `/stores/testing` exports `createFlexStoreContractTests(backend)`, the cases every built-in store passes, for a custom store to run with any test runner; its readme shows how.
|
|
1294
|
+
Projections and Agent event histories are saved as changes, so a save costs what changed rather than the whole session. `IFlexProjectionStore.save(storageKey, sessionId, change, expectedRevision)` receives an `IFlexProjectionChange`: the schema-3 projection with `messages` and `reversionSegments` given as `IFlexListChange`s `{ start, end, items }`, each of which keeps the stored entries from `start` up to `end` and appends `items`. A list change with `start` and `end` at 0 replaces the list whole; FlexHarness sends whole lists when it cannot know which entries the store holds: for a projection it loaded in an older schema and after a save with an uncertain outcome. The Agent event store of each session receives an `IAgentEventChange` of removed, replaced and appended events, as the `@modelprofile.com/flexharness-agent` readme describes. A store that keeps snapshots checks a change's form with `assertFlexProjectionChange()` or `assertAgentEventChange()`, applies it with `applyFlexProjectionChange()` or `applyAgentEventChange()`, and validates the result as above; `createWholeProjectionChange(snapshot)` makes the change that stores a projection whole. `createChangedProjectionSnapshot(stored, change, sessionId)` applies a projection change and validates the result in one step that costs what the change carries rather than the whole session: it validates the change's own entries and other fields in full and reads the stored entries the change keeps only for their identities (message, run, event and capture IDs, roles and statuses), which relate every entry to the others. For a `stored` that `assertFlexProjectionSnapshot(stored, sessionId)` accepted or the function returned, it throws exactly when `assertFlexProjectionSnapshot(applyFlexProjectionChange(stored, change), sessionId)` throws and otherwise returns that snapshot, provided the stored entries were not modified after their validation. The in-memory and JSON-file stores save through it. FlexHarness freezes every message and reversion segment it saved and replaces an entry instead of editing it, which is how it tells the entries the store already holds. `/stores/testing` exports `createFlexStoreContractTests(backend)`, the cases every built-in store passes, for a custom store to run with any test runner; its readme shows how.
|
|
1267
1295
|
|
|
1268
1296
|
Custom Agent event and job providers may implement `releaseSession(storageKey, sessionId)` to release session-bound wrappers, handles, or caches without deleting durable data. FlexHarness calls these hooks only after the corresponding AgentSession or execution context has released runtime ownership. A failed release remains owned for a later retirement or disposal retry. `deleteSession()` and `deleteSessionGenerationCohort()` are the separate destructive operations for durable session data.
|
|
1269
1297
|
|