@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.
- package/dist_ts/00_commitinfo_data.js +1 -1
- package/dist_ts/classes.flexharness.core.js +1 -1
- package/dist_ts/classes.flexharness.d.ts +3 -1
- package/dist_ts/classes.flexharness.js +7 -1
- package/dist_ts/classes.flexharness.tooldispatch.d.ts +5 -1
- package/dist_ts/classes.flexharness.tooldispatch.js +74 -2
- package/dist_ts/errors.d.ts +8 -0
- package/dist_ts/errors.js +15 -1
- package/dist_ts/interfaces.d.ts +11 -0
- package/dist_ts/interfaces.flexharness.d.ts +1 -1
- package/dist_ts/plugins.d.ts +1 -1
- package/dist_ts/plugins.js +1 -1
- package/package.json +3 -3
- package/readme.md +7 -0
- package/ts/00_commitinfo_data.ts +1 -1
- package/ts/classes.flexharness.core.ts +2 -2
- package/ts/classes.flexharness.tooldispatch.ts +100 -2
- package/ts/classes.flexharness.ts +23 -0
- package/ts/errors.ts +16 -0
- package/ts/interfaces.flexharness.ts +1 -1
- package/ts/interfaces.ts +14 -0
- package/ts/plugins.ts +2 -0
- package/ts/readme.md +7 -0
|
@@ -1,5 +1,10 @@
|
|
|
1
1
|
import * as plugins from './plugins.js';
|
|
2
|
-
import {
|
|
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
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.
|