@modelprofile.com/flexharness 18.6.0 → 18.7.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.
@@ -1,5 +1,10 @@
1
1
  import * as plugins from './plugins.js';
2
- import { FlexHarnessValidationError } from './errors.js';
2
+ import {
3
+ FlexHarnessAbortError,
4
+ FlexHarnessUncertainToolCursorStaleError,
5
+ FlexHarnessUncertainToolInspectionStaleError,
6
+ FlexHarnessValidationError,
7
+ } from './errors.js';
3
8
  import {
4
9
  FLEX_CODE_MODE_TOOL_NAME,
5
10
  FLEX_RESULT_METHOD,
@@ -10,6 +15,10 @@ import {
10
15
  type IFlexCatalogSearchInput,
11
16
  type IFlexToolProviderContext,
12
17
  type IFlexUncertainToolExecution,
18
+ type IFlexUncertainToolExecutionPage,
19
+ type IFlexUncertainToolExecutionPageOptions,
20
+ type IFlexSessionGeneration,
21
+ type TFlexUncertainToolExecutionMetadata,
13
22
  type TFlexAgentToolSet,
14
23
  type TFlexToolExecutionReconciliation,
15
24
  type TJsonValue,
@@ -25,7 +34,7 @@ import {
25
34
  } from './utils.transfer.js';
26
35
  import { isAsyncIterable, settleToolOutput } from './utils.tooloutput.js';
27
36
  import { validateIdentifier } from './utils.validation.js';
28
- import type { IActiveRun, IResultRead, IRunReadCall } from './interfaces.flexharness.js';
37
+ import type { IActiveRun, IResultRead, IRunReadCall, IStoredSessionState } from './interfaces.flexharness.js';
29
38
  import type { FlexHarnessCore } from './classes.flexharness.core.js';
30
39
 
31
40
  const notShared = Symbol('not shared');
@@ -36,6 +45,95 @@ const notShared = Symbol('not shared');
36
45
  export class FlexHarnessToolDispatch<TScope> {
37
46
  constructor(private readonly core: FlexHarnessCore<TScope>) {}
38
47
 
48
+ private async inspectionSession(
49
+ scopeId: string,
50
+ sessionId: string,
51
+ generation: IFlexSessionGeneration,
52
+ signal?: AbortSignal,
53
+ ): Promise<IStoredSessionState> {
54
+ validateIdentifier(generation?.sessionGenerationId, 'sessionGenerationId');
55
+ requireTransferIdentifier(generation.sessionGenerationId, 'sessionGenerationId');
56
+ if (!Number.isSafeInteger(generation.sessionGenerationSequence) || generation.sessionGenerationSequence < 1) {
57
+ throw new FlexHarnessValidationError('sessionGenerationSequence must be a positive safe integer.');
58
+ }
59
+ const throwIfAborted = () => {
60
+ if (signal?.aborted) throw signal.reason ?? new FlexHarnessAbortError('The tool inspection was aborted.');
61
+ };
62
+ throwIfAborted();
63
+ let onAbort: (() => void) | undefined;
64
+ const aborted = signal === undefined ? undefined : new Promise<never>((_resolve, reject) => {
65
+ onAbort = () => reject(signal.reason ?? new FlexHarnessAbortError('The tool inspection was aborted.'));
66
+ signal.addEventListener('abort', onAbort, { once: true });
67
+ if (signal.aborted) onAbort();
68
+ });
69
+ try {
70
+ const stateRead = this.core.resolveState(scopeId, sessionId);
71
+ const { state } = await (aborted ? Promise.race([stateRead, aborted]) : stateRead);
72
+ throwIfAborted();
73
+ const barrier = this.core.sessionReadBarrier(state, sessionId);
74
+ await (aborted ? Promise.race([barrier, aborted]) : barrier);
75
+ throwIfAborted();
76
+ this.core.assertStateAcceptingWork(state);
77
+ const stored = this.core.requireSession(state, sessionId);
78
+ if (stored.session.sessionGenerationId !== generation.sessionGenerationId
79
+ || stored.session.sessionGenerationSequence !== generation.sessionGenerationSequence) {
80
+ throw new FlexHarnessUncertainToolInspectionStaleError(sessionId);
81
+ }
82
+ return stored;
83
+ } finally {
84
+ if (signal && onAbort) signal.removeEventListener('abort', onAbort);
85
+ }
86
+ }
87
+
88
+ private inspectionMetadata(
89
+ intent: plugins.IAgentUncertainToolExecutionMetadata,
90
+ ): TFlexUncertainToolExecutionMetadata {
91
+ return {
92
+ intentId: this.core.boundedIdentifier(intent.intentId, 'intentId'),
93
+ generationId: this.core.boundedIdentifier(intent.generationId, 'generationId'),
94
+ toolCallId: this.core.boundedIdentifier(intent.toolCallId, 'toolCallId'),
95
+ toolName: this.core.boundedIdentifier(intent.toolName, 'toolName'),
96
+ timestamp: new Date(intent.timestamp).toISOString(),
97
+ };
98
+ }
99
+
100
+ public async pageUncertainToolExecutions(
101
+ scopeId: string,
102
+ sessionId: string,
103
+ options: IFlexUncertainToolExecutionPageOptions,
104
+ signal?: AbortSignal,
105
+ ): Promise<IFlexUncertainToolExecutionPage> {
106
+ const limit = options?.limit ?? 128;
107
+ if (!Number.isSafeInteger(limit) || limit < 1 || limit > 128) {
108
+ throw new FlexHarnessValidationError('Uncertain tool page limit must be between 1 and 128.');
109
+ }
110
+ if (options?.afterIntentId !== undefined) {
111
+ validateIdentifier(options.afterIntentId, 'afterIntentId');
112
+ requireTransferIdentifier(options.afterIntentId, 'afterIntentId');
113
+ }
114
+ const stored = await this.inspectionSession(scopeId, sessionId, options, signal);
115
+ const page = stored.agentSession.pageUncertainToolExecutions(options.afterIntentId, limit);
116
+ if (!page) throw new FlexHarnessUncertainToolCursorStaleError(options.afterIntentId!);
117
+ return {
118
+ tools: page.tools.map((intent) => this.inspectionMetadata(intent)),
119
+ ...(page.nextAfterIntentId === undefined ? {} : { nextAfterIntentId: page.nextAfterIntentId }),
120
+ };
121
+ }
122
+
123
+ public async getUncertainToolExecution(
124
+ scopeId: string,
125
+ sessionId: string,
126
+ intentId: string,
127
+ generation: IFlexSessionGeneration,
128
+ signal?: AbortSignal,
129
+ ): Promise<TFlexUncertainToolExecutionMetadata | null> {
130
+ validateIdentifier(intentId, 'intentId');
131
+ requireTransferIdentifier(intentId, 'intentId');
132
+ const stored = await this.inspectionSession(scopeId, sessionId, generation, signal);
133
+ const intent = stored.agentSession.getUncertainToolExecution(intentId);
134
+ return intent ? this.inspectionMetadata(intent) : null;
135
+ }
136
+
39
137
  public async listUncertainToolExecutions(
40
138
  scopeId: string,
41
139
  sessionId: string,
@@ -44,6 +44,9 @@ import type {
44
44
  IFlexSlashCommandDescriptor,
45
45
  IFlexSlashCommandExecutionOptions,
46
46
  IFlexUncertainToolExecution,
47
+ IFlexUncertainToolExecutionPage,
48
+ IFlexUncertainToolExecutionPageOptions,
49
+ IFlexSessionGeneration,
47
50
  IFlexUndoSessionResult,
48
51
  IFlexUpdateSessionOptions,
49
52
  IFlexUpdateProjectTaskInput,
@@ -54,6 +57,7 @@ import type {
54
57
  TFlexPrompt,
55
58
  TFlexSlashCommandExecutionResult,
56
59
  TFlexToolExecutionReconciliation,
60
+ TFlexUncertainToolExecutionMetadata,
57
61
  } from './interfaces.js';
58
62
  import { FlexHarnessCore } from './classes.flexharness.core.js';
59
63
 
@@ -504,6 +508,25 @@ export class FlexHarness<TScope = unknown> {
504
508
  return this.core.toolDispatch.listUncertainToolExecutions(scopeId, sessionId);
505
509
  }
506
510
 
511
+ public pageUncertainToolExecutions(
512
+ scopeId: string,
513
+ sessionId: string,
514
+ options: IFlexUncertainToolExecutionPageOptions,
515
+ signal?: AbortSignal,
516
+ ): Promise<IFlexUncertainToolExecutionPage> {
517
+ return this.core.toolDispatch.pageUncertainToolExecutions(scopeId, sessionId, options, signal);
518
+ }
519
+
520
+ public getUncertainToolExecution(
521
+ scopeId: string,
522
+ sessionId: string,
523
+ intentId: string,
524
+ generation: IFlexSessionGeneration,
525
+ signal?: AbortSignal,
526
+ ): Promise<TFlexUncertainToolExecutionMetadata | null> {
527
+ return this.core.toolDispatch.getUncertainToolExecution(scopeId, sessionId, intentId, generation, signal);
528
+ }
529
+
507
530
  public reconcileToolExecution(
508
531
  scopeId: string,
509
532
  sessionId: string,
package/ts/errors.ts CHANGED
@@ -58,6 +58,22 @@ export class FlexHarnessUnresolvedToolExecutionsError extends FlexHarnessError {
58
58
  }
59
59
  }
60
60
 
61
+ /** The inspected session was replaced after the caller observed its generation. */
62
+ export class FlexHarnessUncertainToolInspectionStaleError extends FlexHarnessError {
63
+ constructor(sessionId: string) {
64
+ super('FLEX_UNCERTAIN_TOOL_INSPECTION_STALE', `Session "${sessionId}" changed generation during tool inspection.`);
65
+ this.name = 'FlexHarnessUncertainToolInspectionStaleError';
66
+ }
67
+ }
68
+
69
+ /** The cursor intent was resolved or removed; inspection must restart at the first page. */
70
+ export class FlexHarnessUncertainToolCursorStaleError extends FlexHarnessError {
71
+ constructor(intentId: string) {
72
+ super('FLEX_UNCERTAIN_TOOL_CURSOR_STALE', `Uncertain tool cursor "${intentId}" is stale.`);
73
+ this.name = 'FlexHarnessUncertainToolCursorStaleError';
74
+ }
75
+ }
76
+
61
77
  export type TFlexSteerRejection = 'not-running' | 'duplicate';
62
78
 
63
79
  /**
@@ -139,7 +139,7 @@ export interface IStoredSessionState {
139
139
  permissionRevision: number;
140
140
  permissionQueue: Promise<void>;
141
141
  eventStore: plugins.IAgentEventStore;
142
- agentSession: plugins.IAgentContinuationSession;
142
+ agentSession: plugins.IAgentContinuationSession & plugins.IAgentUncertainToolInspectionSession;
143
143
  agentSessionAbortCompleted: boolean;
144
144
  agentSessionCloseCompleted: boolean;
145
145
  agentEventStoreReleased: boolean;
package/ts/interfaces.ts CHANGED
@@ -2396,6 +2396,20 @@ export interface IFlexUncertainToolExecution {
2396
2396
  timestamp: string;
2397
2397
  }
2398
2398
 
2399
+ /** Bounded inspection metadata; the tool input never crosses this API. */
2400
+ export type TFlexUncertainToolExecutionMetadata = Omit<IFlexUncertainToolExecution, 'input'>;
2401
+
2402
+ export interface IFlexUncertainToolExecutionPageOptions extends IFlexSessionGeneration {
2403
+ afterIntentId?: string;
2404
+ /** Defaults to 128 and may not exceed 128. */
2405
+ limit?: number;
2406
+ }
2407
+
2408
+ export interface IFlexUncertainToolExecutionPage {
2409
+ tools: TFlexUncertainToolExecutionMetadata[];
2410
+ nextAfterIntentId?: string;
2411
+ }
2412
+
2399
2413
  export type TFlexToolExecutionReconciliation =
2400
2414
  | {
2401
2415
  resolution: 'executed';
package/ts/plugins.ts CHANGED
@@ -163,6 +163,8 @@ export type {
163
163
  IAgentRetryEvent,
164
164
  IAgentRunResult,
165
165
  IAgentSession,
166
+ IAgentUncertainToolExecutionMetadata,
167
+ IAgentUncertainToolInspectionSession,
166
168
  IAgentContinuationSession,
167
169
  IAgentSessionOptions,
168
170
  IAgentToolCallUpdateEvent,
package/ts/readme.md CHANGED
@@ -688,6 +688,11 @@ await harness.listPendingPermissions(scopeId, sessionId);
688
688
  await harness.respondToPermission(scopeId, sessionId, permissionId, 'once');
689
689
  await harness.pushRuntimeEvent(scopeId, sessionId, { type: 'workspace.changed', path: 'src/' });
690
690
  await harness.listUncertainToolExecutions(scopeId, sessionId);
691
+ const { sessionGenerationId, sessionGenerationSequence } = await harness.getSession(scopeId, sessionId);
692
+ if (!sessionGenerationId || !sessionGenerationSequence) throw new Error('Session generation is unavailable.');
693
+ const inspection = { sessionGenerationId, sessionGenerationSequence };
694
+ const firstUncertainPage = await harness.pageUncertainToolExecutions(scopeId, sessionId, inspection);
695
+ await harness.getUncertainToolExecution(scopeId, sessionId, intentId, inspection);
691
696
  await harness.reconcileToolExecution(scopeId, sessionId, intentId, {
692
697
  resolution: 'executed',
693
698
  output: { committed: true },
@@ -1217,6 +1222,8 @@ Model resolver, tool provider, delegated run admission provider, AgentSession, t
1217
1222
 
1218
1223
  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. While any such intent remains, new prompts, continuations, scheduled and cache-warm turns, and delegated child turns are refused with `FlexHarnessUnresolvedToolExecutionsError` (`FLEX_UNRESOLVED_TOOL_EXECUTIONS`). A prompt queued while the current run's tool was still executing receives one failed queue outcome if that effect remains unresolved at promotion; the caller must explicitly resend it after reconciliation. A steer may join its own running generation while that generation's tool executes, but cannot enter a run with unresolved effects from another generation. 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. After reconciliation, the model sees its authoritative result once, even if an earlier unknown-effect result closed the call in the failed run; both events remain in the audit log. Neither reconciliation nor reopening admission retries a tool or resends input automatically.
1219
1224
 
1225
+ For a bounded inspection view, call `pageUncertainToolExecutions(scopeId, sessionId, { sessionGenerationId, sessionGenerationSequence, afterIntentId?, limit? }, signal?)` or `getUncertainToolExecution(scopeId, sessionId, intentId, { sessionGenerationId, sessionGenerationSequence }, signal?)`. Take the session generation from `getSession()` and keep it fixed across pages. Pages contain only `intentId`, `generationId`, `toolCallId`, `toolName`, and ISO `timestamp`; no tool input or output is read or returned. The default and maximum page size is 128, and `nextAfterIntentId` is present only when another page exists. A changed session generation throws `FlexHarnessUncertainToolInspectionStaleError` (`FLEX_UNCERTAIN_TOOL_INSPECTION_STALE`); an `afterIntentId` that was resolved or removed throws `FlexHarnessUncertainToolCursorStaleError` (`FLEX_UNCERTAIN_TOOL_CURSOR_STALE`), so start again from the first page. Exact lookup returns `null` for an absent or resolved intent. An optional abort signal cancels only that caller's wait. The existing `listUncertainToolExecutions()` still includes tool inputs for controllers that need them.
1226
+
1220
1227
  `agentSessionPolicy` forwards bounded AgentSession 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, AgentSession'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.
1221
1228
 
1222
1229
  `executionContextProvider` can construct a AgentSession 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.