@modelprofile.com/flexharness 3.3.0 → 3.4.0

package/dist_ts/interfaces.d.ts

@@ -323,9 +323,18 @@ export interface IFlexExecutionContextHandle {
 export interface IFlexExecutionContextProvider<TScope> {
     provideExecutionContext(context: IFlexExecutionContextProviderContext<TScope>): Promise<IFlexExecutionContextHandle | undefined> | IFlexExecutionContextHandle | undefined;
 }
-export interface IFlexAgentSessionPolicy {
+export interface IFlexAgentContextInvocation<TScope = unknown> {
+    readonly scopeId: string;
+    readonly scope: TScope;
+    readonly storageKey: string;
+    readonly sessionId: string;
+}
+export interface IFlexAgentContextCompactionOptions<TScope = unknown> extends plugins.IAgentContextCompactionOptions, IFlexAgentContextInvocation<TScope> {
+}
+export type TFlexAgentContextCompactor<TScope = unknown> = (messages: Parameters<plugins.TAgentContextCompactor>[0], events: Parameters<plugins.TAgentContextCompactor>[1], options: IFlexAgentContextCompactionOptions<TScope>) => ReturnType<plugins.TAgentContextCompactor>;
+export interface IFlexAgentSessionPolicy<TScope = unknown> {
     contextBuilder?: plugins.TAgentContextBuilder;
-    contextCompactor?: plugins.TAgentContextCompactor;
+    contextCompactor?: TFlexAgentContextCompactor<TScope>;
     eventRetention?: TFlexAgentSessionOptions['eventRetention'];
     changeListenerTimeoutMs?: number;
     maxPendingSessionChanges?: number;
@@ -339,7 +348,7 @@ export interface IFlexHarnessOptions<TScope> {
     toolProvider?: IFlexToolProvider<TScope>;
     executionContextProvider?: IFlexExecutionContextProvider<TScope>;
     stores?: IFlexHarnessStores;
-    agentSessionPolicy?: IFlexAgentSessionPolicy;
+    agentSessionPolicy?: IFlexAgentSessionPolicy<TScope>;
     toolOutputLimits?: IFlexJsonLimits;
     callbackLimits?: IFlexCallbackLimits;
     promptQueueLimits?: IFlexPromptQueueLimits;

package/dist_ts/plugins.d.ts

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

package/dist_ts/plugins.js

@@ -1,9 +1,10 @@
 // node native scope
+import { AsyncLocalStorage } from 'node:async_hooks';
 import * as crypto from 'node:crypto';
 import * as fs from 'node:fs/promises';
 import * as path from 'node:path';
-export { crypto, fs, path };
+export { AsyncLocalStorage, crypto, fs, path };
 // @push.rocks scope
 import { AgentEventStoreConflictError, AgentSession, buildModelMessages, ToolJobStoreConflictError, createAgentEvent, getAgentGenerationTransactions, modelMessagesToAgentEvents, validateAgentEventArchiveV2, validateAgentEventSnapshotV2, } from '@push.rocks/smartagent';
 export { AgentEventStoreConflictError, AgentSession, buildModelMessages, ToolJobStoreConflictError, createAgentEvent, getAgentGenerationTransactions, modelMessagesToAgentEvents, validateAgentEventArchiveV2, validateAgentEventSnapshotV2, };
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoicGx1Z2lucy5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uL3RzL3BsdWdpbnMudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBQUEsb0JBQW9CO0FBQ3BCLE9BQU8sS0FBSyxNQUFNLE1BQU0sYUFBYSxDQUFDO0FBQ3RDLE9BQU8sS0FBSyxFQUFFLE1BQU0sa0JBQWtCLENBQUM7QUFDdkMsT0FBTyxLQUFLLElBQUksTUFBTSxXQUFXLENBQUM7QUFFbEMsT0FBTyxFQUFFLE1BQU0sRUFBRSxFQUFFLEVBQUUsSUFBSSxFQUFFLENBQUM7QUFFNUIsb0JBQW9CO0FBQ3BCLE9BQU8sRUFDTCw0QkFBNEIsRUFDNUIsWUFBWSxFQUNaLGtCQUFrQixFQUNsQix5QkFBeUIsRUFDekIsZ0JBQWdCLEVBQ2hCLDhCQUE4QixFQUM5QiwwQkFBMEIsRUFDMUIsMkJBQTJCLEVBQzNCLDRCQUE0QixHQUM3QixNQUFNLHdCQUF3QixDQUFDO0FBRWhDLE9BQU8sRUFDTCw0QkFBNEIsRUFDNUIsWUFBWSxFQUNaLGtCQUFrQixFQUNsQix5QkFBeUIsRUFDekIsZ0JBQWdCLEVBQ2hCLDhCQUE4QixFQUM5QiwwQkFBMEIsRUFDMUIsMkJBQTJCLEVBQzNCLDRCQUE0QixHQUM3QixDQUFDIn0=
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoicGx1Z2lucy5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uL3RzL3BsdWdpbnMudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBQUEsb0JBQW9CO0FBQ3BCLE9BQU8sRUFBRSxpQkFBaUIsRUFBRSxNQUFNLGtCQUFrQixDQUFDO0FBQ3JELE9BQU8sS0FBSyxNQUFNLE1BQU0sYUFBYSxDQUFDO0FBQ3RDLE9BQU8sS0FBSyxFQUFFLE1BQU0sa0JBQWtCLENBQUM7QUFDdkMsT0FBTyxLQUFLLElBQUksTUFBTSxXQUFXLENBQUM7QUFFbEMsT0FBTyxFQUFFLGlCQUFpQixFQUFFLE1BQU0sRUFBRSxFQUFFLEVBQUUsSUFBSSxFQUFFLENBQUM7QUFFL0Msb0JBQW9CO0FBQ3BCLE9BQU8sRUFDTCw0QkFBNEIsRUFDNUIsWUFBWSxFQUNaLGtCQUFrQixFQUNsQix5QkFBeUIsRUFDekIsZ0JBQWdCLEVBQ2hCLDhCQUE4QixFQUM5QiwwQkFBMEIsRUFDMUIsMkJBQTJCLEVBQzNCLDRCQUE0QixHQUM3QixNQUFNLHdCQUF3QixDQUFDO0FBRWhDLE9BQU8sRUFDTCw0QkFBNEIsRUFDNUIsWUFBWSxFQUNaLGtCQUFrQixFQUNsQix5QkFBeUIsRUFDekIsZ0JBQWdCLEVBQ2hCLDhCQUE4QixFQUM5QiwwQkFBMEIsRUFDMUIsMkJBQTJCLEVBQzNCLDRCQUE0QixHQUM3QixDQUFDIn0=

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@modelprofile.com/flexharness",
-  "version": "3.3.0",
+  "version": "3.4.0",
   "private": false,
   "description": "Provider-neutral model-session runtime with durable history, permissions, typed events, and pluggable local or remote tool execution.",
   "main": "dist_ts/index.js",

package/readme.hints.md

@@ -22,6 +22,7 @@ Implementation findings for flexharness.
 - Permission callbacks wait for the current save tail and then revalidate their run before reading remembered grants, so neither uncommitted grants nor captured callbacks can authorize later work.
 - Detached tool-provider settlement remains tracked after prompt finalization. Failed late handle closure stays owned by its storage state and is retried by a later retirement or disposal call.
 - Scope retirement fences older resolver calls and late state admissions, drains the complete resolved storage namespace, and evicts only the exact cached state promise. It never deletes the durable snapshot. Applications must close admission across every resolver alias before retirement because aliases are unknowable before resolution.
+- Context compaction runs under immutable async invocation context rather than storage-state scope hints. This keeps `scopeId`, `scope`, `storageKey`, and `sessionId` exact for manual, retention, and context-overflow compaction even when aliases share one cached namespace. Autonomous job callbacks use their immutable session-owner context because no later public invocation owns them.
 - Detached tool-provider cleanup and retained session cleanup are owned by the exact loaded storage state. Failed drains retain that ownership and the cached state for retry. Scope retirement cannot await or consume another namespace's cleanup, while full disposal settles all storage drains and orphaned initialization cleanup before aggregating failures.
 - JSON provider release hooks evict non-destructive session wrapper caches after AgentSession and execution-context ownership ends. Failed partial-initialization releases remain storage-scoped orphan ownership and are retried by retirement or disposal.
 - `JsonFileFlexHarnessStores.dispose()` is the explicit final drain for file handles whose close failed on the last store operation; failed disposal retains the handle for another call.

package/readme.md

@@ -280,7 +280,7 @@ Model resolver, tool provider, AgentSession, tool execution, tool callback, tool
 
 Transactional tool calls persist an execution intent before the tool side effect starts. After an interrupted process, `listUncertainToolExecutions()` exposes intents whose outcome cannot be proven. A controller must inspect the external system and call `reconcileToolExecution()` with `executed`, `not-executed`, or `abandoned-unknown` before allowing dependent work to continue. Reconciliation output is normalized using the same tool-output limits.
 
-`agentSessionPolicy` forwards bounded SmartAgent session controls for context building, compaction, event retention, change-listener pressure, lease cleanup, archived transaction tombstones, and context-overflow retries. With a configured `contextCompactor`, `compactSession()` writes a canonical compaction event. `archiveSessionEvents()` moves events covered by that compaction into the configured Agent event archive store and returns public archive metadata.
+`agentSessionPolicy` forwards bounded SmartAgent session controls for context building, compaction, event retention, change-listener pressure, lease cleanup, archived transaction tombstones, and context-overflow retries. A configured `contextCompactor` receives the projected model messages, only the filtered model-visible covered events, SmartAgent's existing `reason` and `abortSignal`, and the exact resolved `scopeId`, `scope`, `storageKey`, and `sessionId` for the invocation causing compaction. The invocation context remains isolated when aliases share one storage key, so integrations can resolve the correct model without global mutable state. If no events are eligible for compaction, `compactSession()` returns without calling the compactor or writing a compaction event; otherwise it writes the canonical event. `archiveSessionEvents()` moves events covered by that compaction into the configured Agent event archive store and returns public archive metadata.
 
 `executionContextProvider` can construct a SmartAgent execution context for each session. FlexHarness supplies the resolved scope, storage key, and the session's private job store. The public background APIs expose only execution ID, type, state, exit code, and timestamps; command payloads, stdout, and stderr remain private. The provider's optional `close()` is owned by session deletion, scope retirement, and harness disposal.
 
@@ -316,7 +316,7 @@ const unsubscribe = harness.subscribe((event) => {
 unsubscribe();
 ```
 
-Events are discriminated, sequenced, deeply immutable snapshots. Listener exceptions are isolated from runs and other listeners. Every accepted queue entry emits `prompt.queued` and exactly one `prompt.finished`. Durable promotion additionally emits `prompt.started`, and actual model preparation emits `prompt.running`; cancellation or failure can omit either intermediate event. Existing durable run/message terminal events precede `prompt.finished`. Every `part.started`, `part.delta`, and `part.completed` event carries zero-based `messageIndex` and `partIndex` coordinates from the session's authoritative message and part sequences. Events contain public IDs and snapshots only; they do not expose prompt payloads, the resolved scope object, storage key, model object, or provider options.
+Events are discriminated, sequenced, deeply immutable snapshots. Listener exceptions are isolated from runs and other listeners. Every accepted queue entry emits `prompt.queued` and exactly one `prompt.finished`. Durable promotion additionally emits `prompt.started`, and actual model preparation emits `prompt.running`; cancellation or failure can omit either intermediate event. Existing durable run/message terminal events precede `prompt.finished`. Every callback-backed streamed text part emits exactly one `part.completed` event before the corresponding `run.finished` event. Every `part.started`, `part.delta`, and `part.completed` event carries zero-based `messageIndex` and `partIndex` coordinates from the session's authoritative message and part sequences. Events contain public IDs and snapshots only; they do not expose prompt payloads, the resolved scope object, storage key, model object, or provider options.
 
 ## Stores
 

package/ts/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@modelprofile.com/flexharness',
-  version: '3.3.0',
+  version: '3.4.0',
   description: 'Provider-neutral model-session runtime with durable history, permissions, typed events, and pluggable local or remote tool execution.'
 }