@modelprofile.com/flexharness 15.0.0 → 16.0.1

package/ts/interfaces.ts

@@ -547,6 +547,7 @@ export type TFlexSlashCommandRegistration<TScope> =
   | IFlexSlashCommandTemplateRegistration
   | IFlexSlashCommandHandlerRegistration<TScope>;
 
+/** `promptId` names template and `/init` admissions; results that admit no prompt ignore it. */
 export interface IFlexSlashCommandExecutionOptions extends IFlexPromptOptions {
   signal?: AbortSignal;
 }
@@ -600,6 +601,8 @@ export interface IFlexPromptQueueEntry {
   /** The prompt's `promptId`, when it named one. */
   promptId?: string;
   scheduleKey?: string;
+  /** This entry answers existing context without adding a prompt message. */
+  continuation?: true;
   /** The entry is a cache-warm prompt; see {@link IFlexMessage.cacheWarm}. */
   cacheWarm?: true;
   startedAt?: string;
@@ -608,8 +611,9 @@ export interface IFlexPromptQueueEntry {
   /**
    * On a finished entry: whether its prompt, the steers its run took in and what its model
    * produced stay in the model context of later turns. True for a completed run and a run
-   * stopped after its model produced output; false for a failed run, a run stopped before any
-   * model output and a prompt that never ran. Send the prompt again to have it answered.
+   * stopped or failed after its model produced output; false for an unsuccessful run without
+   * model output and a prompt that never ran. For a continuation, this describes only the new
+   * run's history; it does not change the retention of the existing input.
    */
   keptInContext?: boolean;
   /**
@@ -620,10 +624,10 @@ export interface IFlexPromptQueueEntry {
   unappliedSteerIds?: string[];
 }
 
-export interface IFlexPromptResult {
+/** The result of answering existing context, without adding a prompt message. */
+export interface IFlexContinuePromptResult {
   runId: string;
   sessionId: string;
-  userMessage: IFlexMessage;
   /** The run's last assistant message; a steered run completed earlier ones as it took steers in. */
   assistantMessage: IFlexMessage;
   model: IFlexModelIdentity;
@@ -634,6 +638,10 @@ export interface IFlexPromptResult {
   unappliedSteerIds: string[];
 }
 
+export interface IFlexPromptResult extends IFlexContinuePromptResult {
+  userMessage: IFlexMessage;
+}
+
 /** A message for the running run of a session, taken in at the run's next step boundary. */
 export interface IFlexSteerInput {
   /** Caller-chosen identity, unique among the steers of the run. */
@@ -647,12 +655,13 @@ export interface IFlexSteerAdmission {
   runId: string;
 }
 
-export interface IFlexPromptQueueAdmission {
+export interface IFlexPromptQueueAdmission<TResult extends IFlexContinuePromptResult = IFlexPromptResult> {
   queueId: string;
-  completion: Promise<IFlexPromptResult>;
+  completion: Promise<TResult>;
 }
 
-export interface IFlexPromptAdmission extends IFlexPromptQueueAdmission {
+export interface IFlexPromptAdmission<TResult extends IFlexContinuePromptResult = IFlexPromptResult>
+  extends IFlexPromptQueueAdmission<TResult> {
   runId: string;
 }
 
@@ -673,6 +682,13 @@ export interface IFlexEnqueuePromptOptions extends IFlexPromptOptions {
   steers?: readonly IFlexSteerInput[];
 }
 
+/** Options for continuation through the same FIFO, optionally with scheduled execution. */
+export interface IFlexContinuePromptOptions extends Omit<IFlexEnqueuePromptOptions, 'promptId'> {
+  scheduleKey?: string;
+  /** Requires scheduleKey; defaults to 50 ms when scheduled. */
+  debounceMs?: number;
+}
+
 export interface IFlexScheduledPromptAdmission extends IFlexPromptAdmission {
   scheduleKey: string;
 }
@@ -1260,7 +1276,8 @@ export interface IFlexScopeSnapshot {
 export interface IFlexTerminalProjection {
   runId: string;
   status: 'completed' | 'failed' | 'cancelled';
-  userMessage: IFlexMessage;
+  /** Absent for a continuation, which creates no prompt message. */
+  userMessage?: IFlexMessage;
   assistantMessage: IFlexMessage;
   model?: IFlexModelIdentity;
   /** The usage the provider reported for the run's model calls, whatever the status. */
@@ -1288,7 +1305,8 @@ export interface IFlexAffectedWorkspace {
 
 interface IFlexReversionSegmentV2 {
   runId: string;
-  userMessageId: string;
+  /** Absent for an assistant-only continuation segment. */
+  userMessageId?: string;
   status: TFlexReversionSegmentStatus;
   contextAvailable: boolean;
   eventIds: string[];

package/ts/plugins.ts

@@ -159,6 +159,7 @@ export type {
   IAgentRetryEvent,
   IAgentRunResult,
   IAgentSession,
+  IAgentContinuationSession,
   IAgentSessionOptions,
   IAgentToolCallUpdateEvent,
   IAgentToolExecutionOptions,

package/ts/readme.md

@@ -498,7 +498,7 @@ Sending requires the exact active parent run, its currently delegated direct chi
 
 Before creating or resuming a child, FlexHarness requests permission on the parent run with `kind: 'subagent.start'`, the parent `toolCallId`, and separately bounded harness-owned agent/task metadata. Its metadata includes `childSessionId`, the exact ID reserved for this call: FlexHarness derives it deterministically when `taskId` is omitted and copies the supplied candidate when `taskId` is present. A resume also retains that candidate as `taskId`. This block is not truncated by `toolOutputLimits`. The reserved ID binds permission handling before child creation but does not prove that the child exists or is owned: applications must treat the later delegated admission context as authoritative. The controller answers through the normal permission APIs. This request has no `rememberKey`, so `always` is invalid; controllers use `once` or `reject`.
 
-Each new invocation creates a durable child `IFlexSession` with immutable `parentSessionId`, origin `parentRunId`, origin `parentToolCallId`, `agent`, and `depth`. New public roots persist `depth: 0`; legacy schema-1 roots may omit it. These fields are harness-owned; public `createSession()` accepts `sessionId`, `sessionGenerationId`, `configurationRef`, and `title`. A child inherits its parent's `configurationRef` and cannot resume under a different reference. Child sessions reject direct `prompt()`, `startPrompt()`, `enqueuePrompt()`, and `schedulePrompt()` calls and run only through the `delegate` tool. The model and tool resolver contexts receive optional immutable `parentSessionId` and `agent` values so integrations can apply agent-specific model and tool policy. Child prompts use the definition's `modelHint`, `system`, and `maxSteps`.
+Each new invocation creates a durable child `IFlexSession` with immutable `parentSessionId`, origin `parentRunId`, origin `parentToolCallId`, `agent`, and `depth`. New public roots persist `depth: 0`; legacy schema-1 roots may omit it. These fields are harness-owned; public `createSession()` accepts `sessionId`, `sessionGenerationId`, `configurationRef`, and `title`. A child inherits its parent's `configurationRef` and cannot resume under a different reference. Child sessions reject direct `continuePrompt()`, `prompt()`, `startPrompt()`, `enqueuePrompt()`, and `schedulePrompt()` calls and run only through the `delegate` tool. The model and tool resolver contexts receive optional immutable `parentSessionId` and `agent` values so integrations can apply agent-specific model and tool policy. Child prompts use the definition's `modelHint`, `system`, and `maxSteps`.
 
 The parent tool part receives `childSessionId` as soon as the child is acquired, so a host can offer an authorized live transcript. A foreground call also adds the resolved child model to its part and returns bounded JSON:
 
@@ -717,6 +717,55 @@ The reservation save is the admission point. A save failure produces no start ev
 
 `abort()` returns `true` only while cancellation is still accepted. Terminal persistence is the run's commit point; once it starts, `abort()` returns `false` and the already-fixed terminal outcome completes while the session remains busy.
 
+### Continuing Without New Input
+
+Use `continuePrompt()` after a failed or stopped run whose input remains in context
+(`keptInContext: true`), when the conversation still needs an answer:
+
+```typescript
+const continuation = await harness.continuePrompt(scopeId, sessionId, {
+  modelHint: 'available-model',
+});
+console.log(continuation.queueId);
+const result = await continuation.completion;
+console.log(result.assistantMessage.parts);
+```
+
+The signature is `continuePrompt(scopeId: string, sessionId: string,
+options?: IFlexContinuePromptOptions): Promise<IFlexPromptQueueAdmission<IFlexContinuePromptResult>>`.
+It accepts `modelHint`, `system`, `maxSteps` and initial `steers`, plus optional
+`scheduleKey` and `debounceMs` for the same scheduling behavior as `schedulePrompt()`.
+`debounceMs` requires a schedule key and defaults to 50 ms when scheduled. There is
+no `prompt` or `promptId`: continuation creates a new run and an assistant message
+without appending or modifying a user message. Its result has the prompt result's
+fields except `userMessage`. Explicit steers still become user messages normally.
+
+Admission returns `{ queueId, completion }` once queued, like `enqueuePrompt()`.
+The entry and its `prompt.*` events carry `continuation: true`. Inspect its `runId`
+after `prompt.started`, or read it through `getPromptQueueEntry()`. Use the same
+`cancelPrompt()`, `cancelScheduledPrompt()`, `abort()` and `steerPrompt()` methods.
+Queue bounds and FIFO order, permissions, resource cleanup, compaction, usage
+accounting and provider limits follow the ordinary run path.
+
+At the front of the FIFO, the harness validates the visible transcript and model
+context with undone and excluded runs filtered out, before committing an undone
+branch or reserving a generation or audit message. A refusal preserves redo history.
+Empty context, an already answered turn, and an unsuccessful input that did not stay
+in context refuse with `FlexHarnessValidationError` through `completion`. A retained
+failure whose model context ends in partial assistant text with no tool call is also
+refused; `keptInContext: true` alone does not guarantee it can be continued. An earlier
+queued answer can therefore invalidate a waiting continuation. Cancellation before
+execution leaves the retained input available for another continuation. Continuing never replays
+previous tool calls; unknown external effects still require reconciliation.
+
+Existing projections and Agent event stores remain readable without migration.
+Assistant-only runs require two optional fields in the existing schema-3 projection:
+a staged terminal omits `userMessage`, and its reversion segment omits
+`userMessageId`. Requiring either would invent a user message. Generation claims
+use existing events without a new `user-message` event. Older strict projection
+readers cannot open a session containing these continuation records; do not mix
+versions or downgrade those sessions.
+
 ### Steering a Running Turn
 
 `steerPrompt()` hands a message to the running run of a prompt instead of queueing it behind that run:
@@ -823,7 +872,7 @@ Two horizons bound undo. Retention pruning removes the oldest complete visible u
 
 Session metadata archival through `updateSession(..., { archived: true })` only sets `archivedAt`. It does not archive Agent events, retire captures, or remove undo history.
 
-`executeSlashCommand()` is the authoritative parser and lookup boundary. Its result distinguishes `not-command`, `malformed`, `unknown`, completed `operation`, bounded `handler-result`, and `prompt-admission`. A prompt admission contains the normal `{ queueId, runId, completion }`; await `admission.completion` for the model result. Unknown commands are never admitted as literal prompts. Known unavailable commands and invalid arguments throw typed FlexHarness errors. Options accept `modelHint`, `system`, `maxSteps`, and `signal`; commands do not accept attachments. `/compact` takes `modelHint` and `signal` only and refuses `system` and `maxSteps` with `FlexHarnessValidationError`. Aborting a template or `init` execution cancels its exact queued or started prompt without affecting another queue entry.
+`executeSlashCommand()` is the authoritative parser and lookup boundary. Its result distinguishes `not-command`, `malformed`, `unknown`, completed `operation`, bounded `handler-result`, and `prompt-admission`. A prompt admission contains the normal `{ queueId, runId, completion }`; await `admission.completion` for the model result. Unknown commands are never admitted as literal prompts. Known unavailable commands and invalid arguments throw typed FlexHarness errors. Options accept `promptId`, `modelHint`, `system`, `maxSteps`, and `signal`; commands do not accept attachments. For templates and `/init`, `promptId` follows the normal prompt contract: a non-empty string of at most 512 UTF-8 bytes, recorded on the queue entry and native user message (including exact transcript reads after restart or with `includeUndone`), with duplicate outstanding ids refused by `FlexHarnessDuplicatePromptError`. Results that admit no prompt (`operation`, `handler-result`, `unknown`, `not-command`, `malformed`) ignore `promptId` without recording or reserving it. `/compact` uses `modelHint` and `signal` and refuses `system` and `maxSteps` with `FlexHarnessValidationError`. Aborting a template or `init` execution cancels its exact queued or started prompt without affecting another queue entry.
 
 Templates replace every `$ARGUMENTS` with untouched raw argument text. `$1` through the highest referenced positional placeholder use tokenized arguments, with the highest position receiving all remaining tokens joined by spaces. Missing positions become empty. A template with no placeholders appends non-empty raw arguments after a blank line. `/init` uses the OpenCode 1.18.15 `AGENTS.md` initialization prompt with provider-neutral active-workspace wording.
 
@@ -1010,7 +1059,7 @@ if (started.status === 'started') {
 
 **Read-only.** An imported session never runs, and nothing writes model context for it: it has no Agent events and no tool jobs. Every operation that would change its history or model context throws `FlexHarnessImportedSessionError` (code `FLEX_SESSION_READ_ONLY`):
 
-- `prompt`, `startPrompt`, `enqueuePrompt` and `schedulePrompt`;
+- `prompt`, `startPrompt`, `enqueuePrompt`, `schedulePrompt` and `continuePrompt`;
 - `executeSlashCommand` and `compactSession`;
 - `undoSession` and `redoSession`;
 - `pushRuntimeEvent`, `reconcileToolExecution` and `archiveSessionEvents`;

package/ts/utils.json.ts

@@ -762,6 +762,7 @@ interface IValidatedMessageIdentity {
   runId: string;
   role: 'user' | 'assistant';
   status: 'streaming' | 'completed' | 'failed' | 'cancelled';
+  steerId?: string;
 }
 
 interface IValidatedSessionIdentity {
@@ -932,6 +933,7 @@ function validateMessage(value: unknown, path: string): IValidatedMessageIdentit
     runId,
     role: message.role,
     status: message.status as IValidatedMessageIdentity['status'],
+    ...(message.steerId === undefined ? {} : { steerId: message.steerId as string }),
   };
 }
 
@@ -1226,7 +1228,7 @@ export function assertFlexScopeSnapshot(value: unknown): asserts value is IFlexS
 
 interface IValidatedProjectionBody {
   messages: IValidatedMessageIdentity[];
-  stagedUsers: IValidatedMessageIdentity[];
+  stagedMessages: IValidatedMessageIdentity[];
 }
 
 function validateProjectionBody(snapshot: Record<string, unknown>): IValidatedProjectionBody {
@@ -1240,7 +1242,7 @@ function validateProjectionBody(snapshot: Record<string, unknown>): IValidatedPr
   }
   const runIds = new Set<string>();
   const stagedMessageIds = new Set<string>();
-  const stagedUsers: IValidatedMessageIdentity[] = [];
+  const stagedMessages: IValidatedMessageIdentity[] = [];
   for (let index = 0; index < snapshot.stagedTerminals.length; index++) {
     const path = `$snapshot.stagedTerminals[${index}]`;
     const terminal = requireRecord(snapshot.stagedTerminals[index], path);
@@ -1266,26 +1268,33 @@ function validateProjectionBody(snapshot: Record<string, unknown>): IValidatedPr
     if (!['completed', 'failed', 'cancelled'].includes(String(terminal.status))) {
       throw new FlexHarnessStoreFormatError(`${path}.status is invalid.`);
     }
-    const user = validateMessage(terminal.userMessage, `${path}.userMessage`);
+    const user = terminal.userMessage === undefined
+      ? undefined
+      : validateMessage(terminal.userMessage, `${path}.userMessage`);
     const assistant = validateMessage(terminal.assistantMessage, `${path}.assistantMessage`);
-    if (user.role !== 'user' || assistant.role !== 'assistant') {
+    if ((user && user.role !== 'user') || assistant.role !== 'assistant') {
       throw new FlexHarnessStoreFormatError(`${path} has invalid terminal message roles.`);
     }
-    if (user.runId !== runId || assistant.runId !== runId || user.sessionId !== assistant.sessionId) {
+    if ((user && (user.runId !== runId || user.sessionId !== assistant.sessionId)) || assistant.runId !== runId) {
       throw new FlexHarnessStoreFormatError(`${path} has uncorrelated terminal messages.`);
     }
     if (assistant.status !== terminal.status) {
       throw new FlexHarnessStoreFormatError(`${path}.status does not match its assistant message.`);
     }
-    if (user.status !== terminal.status) {
+    if (!user && visibleMessages.some((message) =>
+      message.runId === runId && message.role === 'user' && message.steerId === undefined)) {
+      throw new FlexHarnessStoreFormatError(`${path} omits its projected prompt message.`);
+    }
+    if (user && user.status !== terminal.status) {
       throw new FlexHarnessStoreFormatError(`${path}.status does not match its user message.`);
     }
-    stagedUsers.push(user);
-    projectionSessionId ??= user.sessionId;
-    if (user.sessionId !== projectionSessionId) {
+    if (user) stagedMessages.push(user);
+    stagedMessages.push(assistant);
+    projectionSessionId ??= assistant.sessionId;
+    if (assistant.sessionId !== projectionSessionId) {
       throw new FlexHarnessStoreFormatError(`${path} belongs to another session.`);
     }
-    for (const messageId of [user.messageId, assistant.messageId]) {
+    for (const messageId of [...(user ? [user.messageId] : []), assistant.messageId]) {
       if (stagedMessageIds.has(messageId)) {
         throw new FlexHarnessStoreFormatError(
           `Snapshot staged terminals contain duplicate message "${messageId}".`,
@@ -1298,7 +1307,7 @@ function validateProjectionBody(snapshot: Record<string, unknown>): IValidatedPr
     requireOptionalString(terminal.finishReason, `${path}.finishReason`);
     if (terminal.steps !== undefined) requireNonNegativeInteger(terminal.steps, `${path}.steps`);
   }
-  return { messages: visibleMessages, stagedUsers };
+  return { messages: visibleMessages, stagedMessages };
 }
 
 export function assertFlexProjectionSnapshotV1(
@@ -1358,7 +1367,7 @@ export function assertFlexProjectionSnapshotV2(
       'workspaceReference',
     ], path);
     const runId = requireString(segment.runId, `${path}.runId`);
-    const userMessageId = requireString(segment.userMessageId, `${path}.userMessageId`);
+    const userMessageId = requireOptionalString(segment.userMessageId, `${path}.userMessageId`);
     if (segmentRunIds.has(runId)) {
       throw new FlexHarnessStoreFormatError(`Snapshot contains duplicate reversion run "${runId}".`);
     }
@@ -1414,12 +1423,19 @@ export function assertFlexProjectionSnapshotV2(
         throw new FlexHarnessStoreFormatError(`${path}.workspaceReference exceeds its byte limit.`);
       }
     }
-    const correlatedUsers = new Set([...projectionBody.messages, ...projectionBody.stagedUsers]
+    const projectedMessages = [...projectionBody.messages, ...projectionBody.stagedMessages];
+    if (userMessageId === undefined && projectedMessages.some((message) =>
+      message.runId === runId && message.role === 'user' && message.steerId === undefined)) {
+      throw new FlexHarnessStoreFormatError(`${path} omits its projected prompt identity.`);
+    }
+    const correlatedMessages = new Set(projectedMessages
       .filter((message) =>
-        message.role === 'user' && message.runId === runId && message.messageId === userMessageId)
+        message.runId === runId && (userMessageId === undefined
+          ? message.role === 'assistant'
+          : message.role === 'user' && message.messageId === userMessageId))
       .map((message) => `${message.runId}:${message.messageId}`));
-    if (correlatedUsers.size !== 1) {
-      throw new FlexHarnessStoreFormatError(`${path} does not match exactly one projected user message.`);
+    if (userMessageId === undefined ? correlatedMessages.size === 0 : correlatedMessages.size !== 1) {
+      throw new FlexHarnessStoreFormatError(`${path} does not match its projected turn messages.`);
     }
   }
   requireNonNegativeInteger(snapshot.revertCursor, '$snapshot.revertCursor');
@@ -1843,7 +1859,7 @@ export function assertFlexProjectionSnapshotV3(
       const segment = entry as Record<string, unknown>;
       return {
         runId: segment.runId,
-        userMessageId: segment.userMessageId,
+        ...(segment.userMessageId === undefined ? {} : { userMessageId: segment.userMessageId }),
         status: segment.status,
         contextAvailable: segment.contextAvailable,
         eventIds: segment.eventIds,
@@ -1901,7 +1917,7 @@ function assertProjectionSession(
   }
   for (const terminal of snapshot.stagedTerminals) {
     if (
-      terminal.userMessage.sessionId !== sessionId
+      (terminal.userMessage !== undefined && terminal.userMessage.sessionId !== sessionId)
       || terminal.assistantMessage.sessionId !== sessionId
     ) {
       throw new FlexHarnessStoreFormatError(

package/ts/utils.validation.ts

@@ -376,7 +376,7 @@ export function validateSlashCommandExecutionOptions(
     throw new FlexHarnessValidationError('Slash command execution options must be a plain object.');
   }
   const unsupported = Object.keys(options)
-    .find((key) => !['modelHint', 'system', 'maxSteps', 'signal'].includes(key));
+    .find((key) => !['promptId', 'modelHint', 'system', 'maxSteps', 'signal'].includes(key));
   if (unsupported) {
     throw new FlexHarnessValidationError(
       `Slash command execution options do not support "${unsupported}".`,
@@ -386,6 +386,7 @@ export function validateSlashCommandExecutionOptions(
     throw new FlexHarnessValidationError('Slash command signal must be an AbortSignal.');
   }
   const promptOptions: IFlexPromptOptions = {
+    ...(options.promptId === undefined ? {} : { promptId: options.promptId }),
     ...(options.modelHint === undefined ? {} : { modelHint: options.modelHint }),
     ...(options.system === undefined ? {} : { system: options.system }),
     ...(options.maxSteps === undefined ? {} : { maxSteps: options.maxSteps }),