@modelprofile.com/flexharness-agent 13.3.0 → 14.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_agent/classes.sessionengine.js +377 -177
- package/dist_ts_agent/smartagent.interfaces.d.ts +5 -3
- package/dist_ts_agent/smartagent.interfaces.js +1 -1
- package/dist_ts_agent/smartagent.transactions.d.ts +1 -6
- package/dist_ts_agent/smartagent.transactions.js +24 -20
- package/package.json +2 -2
- package/readme.md +6 -6
- package/ts_agent/classes.sessionengine.ts +431 -219
- package/ts_agent/readme.md +6 -6
- package/ts_agent/smartagent.interfaces.ts +5 -3
- package/ts_agent/smartagent.transactions.ts +24 -19
package/ts_agent/readme.md
CHANGED
|
@@ -11,7 +11,7 @@ For reporting bugs, issues, or security vulnerabilities, please visit [community
|
|
|
11
11
|
| A CLI command or background worker that investigates a task | `runAgent` runs several model/tool steps and closes its session when it finishes or fails. |
|
|
12
12
|
| A support assistant or application copilot with follow-up questions | `AgentSession` keeps the conversation, serializes generations and exposes events for your UI or application. |
|
|
13
13
|
| A job that must return an application-validated answer | `validateCompletion` can accept an answer or request a bounded correction. |
|
|
14
|
-
| A workflow that
|
|
14
|
+
| A workflow that records a reviewed draft's outcome | Transactional generations separate execution from acceptance while retaining actual unsuccessful work truthfully. |
|
|
15
15
|
| An application with its own storage, permissions or execution infrastructure | Supply tools, an event store and execution-context contracts while retaining control of those services. |
|
|
16
16
|
| A browser assistant using an application-controlled model transport | The `/runner` entrypoint provides the same task loop without Node session dependencies. |
|
|
17
17
|
|
|
@@ -253,7 +253,7 @@ Validation retries retain the conversation and accumulate usage, steps and tool-
|
|
|
253
253
|
|
|
254
254
|
## Review a generation before accepting it
|
|
255
255
|
|
|
256
|
-
A transactional generation gives the host an explicit acceptance boundary
|
|
256
|
+
A transactional generation gives the host an explicit acceptance boundary for reviewing or durably staging an answer. Acceptance records success; rejecting an answer does not erase the model/tool work that actually occurred.
|
|
257
257
|
|
|
258
258
|
```typescript
|
|
259
259
|
export async function createReviewedDraft(
|
|
@@ -278,9 +278,9 @@ export async function createReviewedDraft(
|
|
|
278
278
|
}
|
|
279
279
|
```
|
|
280
280
|
|
|
281
|
-
The `review` callback belongs to your application. While awaiting acceptance, `candidate.messages` includes the candidate, but `getModelMessages()` excludes it from ordinary future context. Acceptance includes the generation
|
|
281
|
+
The `review` callback belongs to your application. While awaiting acceptance, `candidate.messages` includes the candidate, but `getModelMessages()` excludes it from ordinary future context. Acceptance includes the generation as successful. Rejection retains actual model/tool output and its prompt and applied input in future context with a truthful rejected outcome marker. Unsuccessful generations without output remain excluded. Generation IDs identify transactions within a session; use a distinct ID for each new transaction.
|
|
282
282
|
|
|
283
|
-
`generate({ transaction, stop })` takes a second signal for the owner's stop, the way a user stops a turn. It ends the generation like `abort`, but the interrupted outcome records the stop (`stopped: true`, also accepted by `finalizeGeneration(transaction, 'interrupted', { stopped: true })` for a generation stopped after its execution completed). A stopped generation stays in future context once its model produced output: its prompt, the input it took in, the text its running model step streamed and the tool calls it issued. Each tool call without a recorded result is closed with an error result saying its effect is unknown, so the next request is well-formed for every provider. A generation stopped before any model output leaves no trace, so its prompt can be sent again without appearing twice. `isGenerationInModelContext(events, generationId)` applies the same rule to a list of events, for a caller that needs to know whether a finished generation stayed in context.
|
|
283
|
+
`generate({ transaction, stop })` takes a second signal for the owner's stop, the way a user stops a turn. It ends the generation like `abort`, but the interrupted outcome records the stop (`stopped: true`, also accepted by `finalizeGeneration(transaction, 'interrupted', { stopped: true })` for a generation stopped after its execution completed). A stopped generation stays in future context once its model produced output: its prompt, the input it took in, the text its running model step streamed and the tool calls it issued. Each tool call without a recorded result is closed with an error result saying its effect is unknown, so the next request is well-formed for every provider. A generation stopped before any model output leaves no trace, so its prompt can be sent again without appearing twice. `isGenerationInModelContext(events, generationId)` applies the same rule to a list of events, for a caller that needs to know whether a finished generation stayed in context. The same retention rule applies to aborted, failed, rejected and restart-interrupted generations once execution produced model/tool output, including recorded partial inference output. Model-visible outcome markers distinguish rejected, interrupted and stopped-by-owner work from successful completion. Synthetic unknown-effect results only close the model protocol: they are not evidence that an external effect happened or did not happen, and never trigger automatic tool replay. `stop` requires a transactional generation.
|
|
284
284
|
|
|
285
285
|
Closing a session or restoring a stored session interrupts unfinished transactions. Restoration does not automatically rerun them. Persisted transactions require an event store; without one, transactions are process-local.
|
|
286
286
|
|
|
@@ -308,7 +308,7 @@ await generation;
|
|
|
308
308
|
const unapplied = pendingInput.close(); // input the generation never took in
|
|
309
309
|
```
|
|
310
310
|
|
|
311
|
-
The generation closes the queue when it ends, whether it completed, failed or was aborted. `close()` returns the inputs it never took in, the same list on every call once the generation has ended; input that arrives during the last model step is among them, and so is input the generation drained but could not record durably. After closing, `add()` throws `AgentPendingInputRejectedError` with reason `closed`, and a reused `inputId` is refused with reason `duplicate`. The caller decides what becomes of unapplied input, for example sending it as the next turn.
|
|
311
|
+
The generation closes the queue when it ends, whether it completed, failed or was aborted. `close()` returns the inputs it never took in, the same list on every call once the generation has ended; input that arrives during the last model step is among them, and so is input the generation drained but could not record durably. After closing, `add()` throws `AgentPendingInputRejectedError` with reason `closed`, and a reused `inputId` is refused with reason `duplicate`. The caller decides what becomes of unapplied input, for example explicitly sending it as the next turn. In FlexHarness, `keptInContext` reports canonical retention, not success: applied steers in retained unsuccessful history are not `unappliedSteerIds`; input never durably applied is listed, and all accepted steers are listed when the generation is not retained. Do not automatically resend retained input or replay tool effects. FlexHarness undo/redo hides/restores grouped unsuccessful history and its outcome markers; a new branch excludes the hidden history. This changes context, not external effects without a workspace reversion provider.
|
|
312
312
|
|
|
313
313
|
## Events, storage and context
|
|
314
314
|
|
|
@@ -409,7 +409,7 @@ Tools and resource callbacks must observe their supplied abort signals. A model
|
|
|
409
409
|
|
|
410
410
|
The runtime retries a model call that failed with a rate limit (429), an overloaded provider (529) or an unavailable one (503) at most 8 times, waiting for the provider's `retry-after` delay but at least the backoff that doubles from 2 s to 30 s. A requested delay beyond 60 s, or one that would take the call's retries past 150 s in total, fails the generation: a rate limit (429) as a `ModelLimitError` of kind `rate_limit` carrying that retry time, a 503 or 529 with the provider error. A `ModelLimitError` of kind `usage_limit`, which the provider adapters raise for a spent quota, is never retried. Completed tool results are preserved during a generation's retry sequence. A ledger reuses an already observed execution for the same tool-call identity. Applications still need their own idempotency and recovery rules for external side effects.
|
|
411
411
|
|
|
412
|
-
`maxSteps`
|
|
412
|
+
`maxSteps` has **no default limit**. It is an optional positive finite safe integer limiting completed model steps per generation; `0`, negatives, fractions, `NaN`, infinity and unsafe integers are invalid. Resolution precedence is prepared generation lease → per-generation option → session setting; only when all omit the cap is execution unbounded. Owner stops, aborts, permissions, real errors, usage accounting and cleanup remain effective without a cap. Prompt-cache handling defaults to `cache: 'auto'`; use `cache: false` to disable the runtime's cache defaults, or pass an explicit cache policy (`ISmartAiCacheOptions` of `@modelprofile.com/flexharness-models`). On OpenAI a generation's `prompt_cache_key` is derived from its instructions and tool definitions, so sessions with one prefix share the provider's cache; `keyScope`, `keyBuckets` and `key` adjust it.
|
|
413
413
|
|
|
414
414
|
## Portable runner in the browser
|
|
415
415
|
|
|
@@ -268,7 +268,8 @@ export interface IAgentSessionOptions {
|
|
|
268
268
|
/**
|
|
269
269
|
* Maximum number of LLM↔tool round trips.
|
|
270
270
|
* Each step may execute multiple tools in parallel.
|
|
271
|
-
*
|
|
271
|
+
* Omitted: no step limit.
|
|
272
|
+
* Explicit caps must be positive safe integers.
|
|
272
273
|
*/
|
|
273
274
|
maxSteps?: number;
|
|
274
275
|
/** Initial canonical events. */
|
|
@@ -410,6 +411,7 @@ export interface IAgentGenerationLease {
|
|
|
410
411
|
isReadOnlyToolCall?: TAgentToolCallClassifier;
|
|
411
412
|
providerOptions?: ProviderOptions;
|
|
412
413
|
cache?: TAgentCacheSetting;
|
|
414
|
+
/** Optional positive safe integer step cap; no limit unless configured. */
|
|
413
415
|
maxSteps?: number;
|
|
414
416
|
/** Caps the output tokens of each model call of the generation; the provider's limit otherwise. */
|
|
415
417
|
maxOutputTokens?: number;
|
|
@@ -469,7 +471,7 @@ export interface IAgentGenerateOptions {
|
|
|
469
471
|
providerOptions?: ProviderOptions;
|
|
470
472
|
/** Per-generation prompt-cache override. A prepared lease takes precedence. */
|
|
471
473
|
cache?: TAgentCacheSetting;
|
|
472
|
-
/**
|
|
474
|
+
/** Optional positive safe integer cap on completed model steps; omitted means no limit. */
|
|
473
475
|
maxSteps?: number;
|
|
474
476
|
/** Cancels only this generation and its synchronous tool executions. */
|
|
475
477
|
abort?: AbortSignal;
|
|
@@ -477,7 +479,7 @@ export interface IAgentGenerateOptions {
|
|
|
477
479
|
* Stops a transactional generation the way a user stops a turn. It ends the generation like
|
|
478
480
|
* `abort`, but the interrupted outcome records the stop: the text the running model step
|
|
479
481
|
* streamed and the tool calls it issued are kept, and the generation stays in the model
|
|
480
|
-
* context once its model produced output.
|
|
482
|
+
* context once its model produced output. Aborted and failed generations with model/tool output also stay in context.
|
|
481
483
|
*/
|
|
482
484
|
stop?: AbortSignal;
|
|
483
485
|
/** Opt-in transactional claim returned by beginGeneration(). */
|
|
@@ -149,14 +149,7 @@ const isModelOutputEvent = (event: TAgentEvent): boolean =>
|
|
|
149
149
|
|| event.type === 'tool-result'
|
|
150
150
|
|| event.type === 'model-message';
|
|
151
151
|
|
|
152
|
-
/**
|
|
153
|
-
* Whether the events of a transactional generation are part of the model context. An accepted
|
|
154
|
-
* generation is, and so is the generation that is executing. A generation its owner stopped
|
|
155
|
-
* stays in the context once the model produced output in it: its prompt, the input it took in
|
|
156
|
-
* while it ran and what the model produced before the stop. One stopped before any model output
|
|
157
|
-
* left no trace in the conversation and is not shown, so its prompt can be sent again. Rejected
|
|
158
|
-
* generations, and generations interrupted by an abort, a failure or a restart, are not shown.
|
|
159
|
-
*/
|
|
152
|
+
/** Accepted and active generations, and terminal generations with actual model/tool output. */
|
|
160
153
|
const isModelVisibleTransaction = (
|
|
161
154
|
transaction: IAgentGenerationTransaction,
|
|
162
155
|
producedOutput: ReadonlySet<string>,
|
|
@@ -164,8 +157,7 @@ const isModelVisibleTransaction = (
|
|
|
164
157
|
transaction.state === 'accepted'
|
|
165
158
|
|| transaction.state === 'execution-started'
|
|
166
159
|
|| (
|
|
167
|
-
transaction.state === 'interrupted'
|
|
168
|
-
&& transaction.outcome?.stopped === true
|
|
160
|
+
(transaction.state === 'interrupted' || transaction.state === 'rejected')
|
|
169
161
|
&& transaction.executionStarted !== undefined
|
|
170
162
|
&& producedOutput.has(transaction.generationId)
|
|
171
163
|
);
|
|
@@ -179,12 +171,7 @@ const generationsWithModelOutput = (events: readonly TAgentEvent[]): Set<string>
|
|
|
179
171
|
return producedOutput;
|
|
180
172
|
};
|
|
181
173
|
|
|
182
|
-
/**
|
|
183
|
-
* Whether the transactional generation `generationId` is part of the model context of later
|
|
184
|
-
* generations, by the rule `filterModelVisibleAgentEvents` applies: it was accepted, is
|
|
185
|
-
* executing, or was stopped by its owner after its model produced output. False for a
|
|
186
|
-
* generation `events` holds no transaction of.
|
|
187
|
-
*/
|
|
174
|
+
/** Whether a generation contributes to later context, including unsuccessful work with output. */
|
|
188
175
|
export const isGenerationInModelContext = (
|
|
189
176
|
events: readonly TAgentEvent[],
|
|
190
177
|
generationId: string,
|
|
@@ -230,7 +217,7 @@ export const filterModelVisibleAgentEvents = (
|
|
|
230
217
|
}
|
|
231
218
|
}
|
|
232
219
|
const visibleEvents: TAgentEvent[] = [];
|
|
233
|
-
/** Closes each tool call
|
|
220
|
+
/** Closes each tool call an unsuccessful generation left open, right after the call. */
|
|
234
221
|
const closeOpenToolCall = (toolCallId: string, toolName: string, source: TAgentEvent): void => {
|
|
235
222
|
const key = `${source.generationId}\0${toolCallId}`;
|
|
236
223
|
if (resultedToolCalls.has(key)) return;
|
|
@@ -238,7 +225,25 @@ export const filterModelVisibleAgentEvents = (
|
|
|
238
225
|
visibleEvents.push(interruptedToolResult(toolCallId, toolName, source));
|
|
239
226
|
};
|
|
240
227
|
for (const event of events) {
|
|
241
|
-
if (isControlEvent(event))
|
|
228
|
+
if (isControlEvent(event)) {
|
|
229
|
+
if (event.type === 'generation-outcome' && event.outcome !== 'accepted') {
|
|
230
|
+
const transaction = transactions.get(event.generationId);
|
|
231
|
+
if (transaction && isModelVisibleTransaction(transaction, producedOutput)) {
|
|
232
|
+
visibleEvents.push({
|
|
233
|
+
id: `${event.id}:model-outcome`,
|
|
234
|
+
timestamp: event.timestamp,
|
|
235
|
+
generationId: event.generationId,
|
|
236
|
+
type: 'user-message',
|
|
237
|
+
content: event.outcome === 'rejected'
|
|
238
|
+
? '[Generation outcome: rejected. This turn did not complete successfully. Prior tool results describe actual work; do not assume it was undone or repeat its effects.]'
|
|
239
|
+
: event.stopped
|
|
240
|
+
? '[Generation outcome: stopped by owner. Prior tool results describe actual work; unresolved effects remain unknown.]'
|
|
241
|
+
: '[Generation outcome: interrupted, not completed successfully. Prior tool results describe actual work; unresolved effects remain unknown.]',
|
|
242
|
+
});
|
|
243
|
+
}
|
|
244
|
+
}
|
|
245
|
+
continue;
|
|
246
|
+
}
|
|
242
247
|
if (event.type === 'context-compaction' && event.archivedTransactions) {
|
|
243
248
|
visibleEvents.push({ ...event, archivedTransactions: undefined });
|
|
244
249
|
continue;
|
|
@@ -250,7 +255,7 @@ export const filterModelVisibleAgentEvents = (
|
|
|
250
255
|
const transaction = transactions.get(event.generationId);
|
|
251
256
|
if (transaction && !isModelVisibleTransaction(transaction, producedOutput)) continue;
|
|
252
257
|
visibleEvents.push(event);
|
|
253
|
-
if (transaction?.state !== 'interrupted') continue;
|
|
258
|
+
if (transaction?.state !== 'interrupted' && transaction?.state !== 'rejected') continue;
|
|
254
259
|
if (event.type === 'tool-call' && event.providerExecuted !== true) {
|
|
255
260
|
closeOpenToolCall(event.toolCallId, event.toolName, event);
|
|
256
261
|
} else if (event.type === 'assistant-message' && Array.isArray(event.content)) {
|