@modelprofile.com/flexharness 12.5.0 → 13.1.0

package/ts/classes.flexharness.runs.ts

@@ -3,6 +3,7 @@ import {
   FlexHarnessAbortError,
   FlexHarnessExternalError,
   FlexHarnessNotFoundError,
+  FlexHarnessPermissionRejectedError,
   FlexHarnessRunError,
   FlexHarnessStepLimitError,
   FlexHarnessValidationError,
@@ -53,6 +54,7 @@ import {
   externalErrorFallback,
   requireSessionGeneration,
   combineErrors,
+  delegatedCancellation,
   terminalActivityError,
 } from './utils.flexharness.js';
 import type { FlexHarnessCore } from './classes.flexharness.core.js';
@@ -664,9 +666,8 @@ export class FlexHarnessRuns<TScope> {
     if (!active || active.runId !== runId || active.phase === 'finalizing' || active.phase === 'promoting') {
       return false;
     }
-    const cancellation = reason instanceof FlexHarnessAbortError
-      ? reason
-      : this.core.trustInternalError(new FlexHarnessAbortError('The parent run was aborted.'));
+    const cancellation = delegatedCancellation(reason)
+      ?? this.core.trustInternalError(new FlexHarnessAbortError('The parent run was aborted.'));
     this.cancelRun(active, cancellation);
     return true;
   }
@@ -914,9 +915,15 @@ export class FlexHarnessRuns<TScope> {
       assistantMessage.usage = cloneSerializable(run.usage);
       const message = truncateUtf8(error?.message ?? externalErrorFallback.message, maxTransferMetadataBytes);
       const limit = error instanceof FlexHarnessExternalError ? error.limit : undefined;
-      for (const failedMessage of [userMessage, assistantMessage]) {
+      const rejectedPermissionId = error instanceof FlexHarnessPermissionRejectedError
+        ? error.permissionId
+        : undefined;
+      // A failed turn fails its prompt too. A stopped turn is no fault of its prompt, so the prompt
+      // stays an ordinary user message and only the answer it stopped carries the stop.
+      for (const failedMessage of status === 'cancelled' ? [assistantMessage] : [userMessage, assistantMessage]) {
         failedMessage.error = message;
         if (limit) failedMessage.limit = cloneSerializable(limit);
+        if (rejectedPermissionId) failedMessage.rejectedPermissionId = rejectedPermissionId;
       }
     }
     return {

package/ts/classes.flexharness.subagents.ts

@@ -41,6 +41,7 @@ import {
   requireSessionGeneration,
   sha256Hex,
   combineErrors,
+  delegatedCancellation,
 } from './utils.flexharness.js';
 import type { FlexHarnessCore } from './classes.flexharness.core.js';
 
@@ -379,9 +380,8 @@ export class FlexHarnessSubagents<TScope> {
     let queued: Awaited<ReturnType<typeof this.core.prompts.enqueuePromptInternal>> | undefined;
     let admission: IFlexPromptAdmission | undefined;
     const abortChild = () => {
-      const reason = run.controller.signal.reason instanceof FlexHarnessAbortError
-        ? run.controller.signal.reason
-        : this.core.trustInternalError(new FlexHarnessAbortError('The parent run was aborted.'));
+      const reason = delegatedCancellation(run.controller.signal.reason)
+        ?? this.core.trustInternalError(new FlexHarnessAbortError('The parent run was aborted.'));
       const ownedChild = child ?? run.state.sessions.get(reservedSessionId);
       if (
         ownedChild

package/ts/classes.toolcatalog.ts

@@ -396,6 +396,31 @@ const typeIdentifierOf = (name: string): string => {
   return reservedWords.has(identifier) ? `${identifier}_` : identifier;
 };
 
+/**
+ * The identifier each of a catalog's type names is declared under. A name that is an identifier
+ * keeps it; the others are mapped in code-point order, so a catalog always declares the same
+ * identifiers.
+ */
+const typeIdentifiersOf = (typeNames: Iterable<string>): Map<string, string> => {
+  const typeIdentifiers = new Map<string, string>();
+  const taken = new Set<string>();
+  const names = [...new Set(typeNames)].sort(compareCodePoints);
+  for (const name of names) {
+    if (typeIdentifierOf(name) !== name) continue;
+    typeIdentifiers.set(name, name);
+    taken.add(name);
+  }
+  for (const name of names) {
+    if (typeIdentifiers.has(name)) continue;
+    const base = typeIdentifierOf(name);
+    let identifier = base;
+    for (let suffix = 2; taken.has(identifier); suffix++) identifier = `${base}_${suffix}`;
+    typeIdentifiers.set(name, identifier);
+    taken.add(identifier);
+  }
+  return typeIdentifiers;
+};
+
 const textListOf = (
   value: unknown,
   label: string,
@@ -603,24 +628,7 @@ class FlexToolCatalogCore {
       }
       namedTypes.set(entry.name, entry);
     }
-    // A name that is an identifier keeps it; the others are mapped in code-point order, so a
-    // catalog always declares the same identifiers.
-    const typeIdentifiers = new Map<string, string>();
-    const taken = new Set<string>();
-    const names = [...namedTypes.keys()].sort(compareCodePoints);
-    for (const name of names) {
-      if (typeIdentifierOf(name) !== name) continue;
-      typeIdentifiers.set(name, name);
-      taken.add(name);
-    }
-    for (const name of names) {
-      if (typeIdentifiers.has(name)) continue;
-      const base = typeIdentifierOf(name);
-      let identifier = base;
-      for (let suffix = 2; taken.has(identifier); suffix++) identifier = `${base}_${suffix}`;
-      typeIdentifiers.set(name, identifier);
-      taken.add(identifier);
-    }
+    const typeIdentifiers = typeIdentifiersOf(namedTypes.keys());
     /** Catalog types by the name their `$ref`s use. */
     const catalogTypes = new Map<string, ITypeEntry>();
     for (const [name, entry] of namedTypes) {
@@ -949,11 +957,7 @@ class FlexToolCatalogCore {
 
   /** The catalog types a declaration's code names; its comments and string literals name none. */
   private scanTypes(text: string, self?: string): string[] {
-    const found = new Set<string>();
-    for (const match of codeOf(text).matchAll(identifierScanPattern)) {
-      if (match[0] !== self && this.types.has(match[0])) found.add(match[0]);
-    }
-    return [...found].sort(compareCodePoints);
+    return identifiersIn(text).filter((name) => name !== self && this.types.has(name));
   }
 
   /** The named types a method's parameters and result use. */
@@ -1059,6 +1063,26 @@ export class FlexToolCatalog<TScope = unknown> {
     return typeIdentifierOf(name);
   }
 
+  /**
+   * The identifier each type name of a catalog of exactly these types is declared under: a name that
+   * is an identifier keeps it, and each other takes `identifierOf()`'s, in code-point order with
+   * `_2`, `_3` … appended where that is taken (`a_b` and `a-b` are declared as `a_b` and `a_b_2`).
+   * As a name's identifier depends on the other names, a host that hands a catalog only some of its
+   * types keeps the ones that took the lower identifiers along.
+   */
+  public static identifiersOf(names: Iterable<string>): Map<string, string> {
+    return typeIdentifiersOf(names);
+  }
+
+  /**
+   * The identifiers a declaration's code names, sorted; its comments and the contents of its string
+   * literals name none. The catalog takes the named types a declaration uses from these, so a host
+   * that hands a catalog only some of its types finds the ones a declaration needs the same way.
+   */
+  public static identifiersIn(declaration: string): string[] {
+    return identifiersIn(declaration);
+  }
+
   /**
    * Prepares `catalog`. Preparing the same object again returns the cached preparation, so a host
    * that returns one catalog object for every run pays for it once.
@@ -1824,6 +1848,10 @@ const codeOf = (text: string): string => {
   return code;
 };
 
+/** The identifiers a declaration's code names, sorted; its comments and string literals name none. */
+const identifiersIn = (text: string): string[] =>
+  [...new Set(codeOf(text).match(identifierScanPattern))].sort(compareCodePoints);
+
 /** The index of the bracket that closes the one at `open`, or -1. */
 const closingBracket = (code: string, open: number): number => {
   const pairs: Record<string, string> = { '(': ')', '<': '>', '{': '}', '[': ']' };

package/ts/errors.ts

@@ -112,8 +112,9 @@ export class FlexHarnessQueueFullError extends FlexHarnessError {
 }
 
 export class FlexHarnessAbortError extends FlexHarnessError {
-  constructor(message = 'The run was aborted.', options?: ErrorOptions) {
-    super('FLEX_ABORTED', message, options);
+  /** `code` names a more specific stop for a subclass, such as a rejected permission. */
+  constructor(message = 'The run was aborted.', options?: ErrorOptions, code = 'FLEX_ABORTED') {
+    super(code, message, options);
     this.name = 'FlexHarnessAbortError';
   }
 }
@@ -143,10 +144,17 @@ export class FlexHarnessExternalError extends FlexHarnessError {
   }
 }
 
-export class FlexHarnessPermissionRejectedError extends FlexHarnessError {
+/**
+ * A permission was rejected, by a `reject` response or by the session's permission policy. The
+ * rejection is a decision, not a fault: it stops the run like an owner's cancellation.
+ */
+export class FlexHarnessPermissionRejectedError extends FlexHarnessAbortError {
+  public readonly permissionId: string;
+
   constructor(permissionId: string, options?: ErrorOptions) {
-    super('FLEX_PERMISSION_REJECTED', `Permission "${permissionId}" was rejected.`, options);
+    super(`Permission "${permissionId}" was rejected.`, options, 'FLEX_PERMISSION_REJECTED');
     this.name = 'FlexHarnessPermissionRejectedError';
+    this.permissionId = permissionId;
   }
 }
 
@@ -247,6 +255,7 @@ export function errorToInfo(error: unknown): IFlexErrorInfo {
       message: error.message,
       code: error.code,
       ...(error instanceof FlexHarnessExternalError && error.limit ? { limit: error.limit } : {}),
+      ...(error instanceof FlexHarnessPermissionRejectedError ? { permissionId: error.permissionId } : {}),
     };
   }
   if (error instanceof Error) {

package/ts/interfaces.flexharness.ts

@@ -35,6 +35,7 @@ import type {
   TFlexPromptQueueStatus,
   TFlexPendingReversion,
   TFlexProjectionSnapshot,
+  TFlexSessionReversionBarrierCause,
   TFlexSessionReversionGroupKind,
   TFlexTurnReversionFinalizedOutcome,
 } from './interfaces.js';
@@ -114,6 +115,8 @@ export interface IReversionGroup {
   kind: TFlexSessionReversionGroupKind;
   affectedWorkspaces: IFlexAffectedWorkspace[];
   affectedWorkspacesTruncated: boolean;
+  barrierCauses: TFlexSessionReversionBarrierCause[];
+  reasonCodes: string[];
 }
 
 export type TNormalizedCaptureInspection =

package/ts/interfaces.ts

@@ -174,6 +174,8 @@ export interface IFlexToolMessagePart {
    * did not run; its output is the earlier call's.
    */
   deduplicatedFrom?: string;
+  /** For a failed call whose permission was rejected: the rejected request's `permissionId`. */
+  rejectedPermissionId?: string;
   model?: IFlexModelIdentity;
   /** ISO time the tool call began. Absent on parts recorded before part times existed. */
   startedAt?: string;
@@ -216,6 +218,8 @@ export interface IFlexMessage {
   error?: string;
   /** The model limit that failed this run, next to its error. */
   limit?: TFlexModelLimit;
+  /** The permission whose rejection stopped this run, next to its error. */
+  rejectedPermissionId?: string;
   /** On a user message that steered its running run: the caller's steer identity. */
   steerId?: string;
 }
@@ -228,6 +232,8 @@ export interface IFlexSessionActivity {
   error?: string;
   /** The model limit that failed the last run, next to its error. */
   limit?: TFlexModelLimit;
+  /** The permission whose rejection stopped the last run, next to its error. */
+  rejectedPermissionId?: string;
 }
 
 export interface IFlexSession {
@@ -238,6 +244,13 @@ export interface IFlexSession {
   /** Opaque immutable configuration revision bound to this exact session generation. */
   configurationRef?: string;
   title?: string;
+  /**
+   * The session's first prompt as one line, bounded like a title (`maxTitleBytes`), so a session
+   * nobody titled can still be named. The harness sets it when the first run with prompt text is
+   * admitted, and for a session stored before previews existed at its next run; it never changes
+   * afterwards and is never set by a caller. Absent until then.
+   */
+  preview?: string;
   createdAt: string;
   updatedAt: string;
   archivedAt?: string;
@@ -1696,12 +1709,30 @@ export type TFlexReversionPolicy = 'transcript-optional' | 'workspace-required';
 
 export type TFlexSessionReversionGroupKind = 'candidate' | 'barrier' | 'no-change';
 
+/**
+ * Why a group is a barrier: `pending` while a capture runs or its outcome is not final,
+ * `nonrevertible` for a workspace outcome that cannot be reverted, `transcript-only` for legacy
+ * transcript history without a workspace capture.
+ */
+export type TFlexSessionReversionBarrierCause = 'pending' | 'nonrevertible' | 'transcript-only';
+
+/** The barrier causes in the order a group lists them. */
+export const FLEX_SESSION_REVERSION_BARRIER_CAUSES: readonly TFlexSessionReversionBarrierCause[] = [
+  'pending',
+  'nonrevertible',
+  'transcript-only',
+];
+
 export interface IFlexSessionReversionGroup {
   readonly runId: string;
   readonly kind: TFlexSessionReversionGroupKind;
   readonly visibility: 'visible' | 'hidden';
   readonly affectedWorkspaces: readonly IFlexAffectedWorkspace[];
   readonly affectedWorkspacesTruncated: boolean;
+  /** Each cause of a barrier once, in the order of the type; empty for every other kind. */
+  readonly barrierCauses: readonly TFlexSessionReversionBarrierCause[];
+  /** The distinct reason codes of the group's nonrevertible segments, in segment order. */
+  readonly reasonCodes: readonly string[];
 }
 
 export interface IFlexSessionReversionInfo {
@@ -2128,6 +2159,8 @@ export interface IFlexErrorInfo {
   code?: string;
   /** Set when a model usage or rate limit caused the error. */
   limit?: TFlexModelLimit;
+  /** Set when a rejected permission stopped the run: the rejected request's `permissionId`. */
+  permissionId?: string;
 }
 
 export type TFlexHarnessEvent =

package/ts/readme.md

@@ -693,7 +693,7 @@ await harness.dispose();
 
 Only one run may be active in a session. Additional prompts enter a bounded FIFO owned by FlexHarness, while different sessions can run concurrently. `enqueuePrompt()` resolves with `{ queueId, completion }` after the immutable prompt and options have been accepted into that runtime queue and `prompt.queued` has been emitted. `startPrompt()` keeps its durable-admission behavior: it waits for its FIFO turn and resolves with `{ queueId, runId, completion }` only after the canonical generation claim, run ID, and initial public audit messages have been durably reserved and the corresponding start events have been emitted. `prompt()` preserves the simpler behavior by awaiting completion internally.
 
-Queue entries expose `queued`, `starting`, `scheduled`, `running`, `completed`, `failed`, and `cancelled` status through `getPromptQueueEntry()` and `listPromptQueueEntries()`. The list is ordered by process-local `queueSequence`. `getPromptQueueEntry()` throws `FlexHarnessNotFoundError` for an unknown or evicted ID. `cancelPrompt()` cancels one exact queue ID: a waiting entry leaves the FIFO and releases capacity immediately but remains queryable as `cancelled` until terminal retention evicts it; a promoted entry uses the canonical run cancellation path. Cancelling a terminal entry returns `false`, while an unknown ID throws. `abort()` remains scoped to the currently active run.
+Queue entries expose `queued`, `starting`, `scheduled`, `running`, `completed`, `failed`, and `cancelled` status through `getPromptQueueEntry()` and `listPromptQueueEntries()`. The list is ordered by process-local `queueSequence`. `getPromptQueueEntry()` throws `FlexHarnessNotFoundError` for an unknown or evicted ID. `cancelPrompt()` cancels one exact queue ID: a waiting entry leaves the FIFO and releases capacity immediately but remains queryable as `cancelled` until terminal retention evicts it; a promoted entry uses the canonical run cancellation path and is stopped with the same `FlexHarnessAbortError` ("The run was aborted.") as `abort()`; only a waiting entry is rejected with "The queued prompt was cancelled.". A cancelled run, whether stopped or found interrupted on reload, puts its `error` on the assistant message only; its user message is `cancelled` without an `error`, while a failed run marks both messages. Cancelling a terminal entry returns `false`, while an unknown ID throws. `abort()` remains scoped to the currently active run.
 
 The displayed queue limits are the defaults. Outstanding count and byte limits apply per session and include every non-terminal queued or active prompt until it settles. Pending-admission limits apply to the complete harness while scope aliases are unresolved. Terminal retention applies per session. Exceeding an admission limit throws `FlexHarnessQueueFullError`.
 
@@ -705,7 +705,7 @@ The reservation save is the admission point. A save failure produces no start ev
 
 `listMessagePage()` returns the newest contiguous page in chronological order. `limit` must be an integer from 1 through 50 and defaults to 50. `nextCursor` is opaque, limited to 4096 UTF-8 bytes, bound to the resolved storage namespace and session, and remains stable when newer messages are appended. Mismatched and stale cursors fail validation. Each page carries `startIndex`, the zero-based index of its first message in the session's visible history (for an empty page, the index the page ends at), so a consumer can order and page by absolute position. Appending messages leaves every index unchanged; a branch after an undo reuses the positions of the history it replaces, so a consumer re-reads its pages after `session.history.changed`. `getMessage()` performs an exact lookup. Transfer identifiers are limited to 512 bytes, text and reasoning parts to 96 KiB, complete messages to 480 KiB, and complete page envelopes to 512 KiB. A page may therefore contain fewer messages than requested. Oversized text is truncated and an otherwise oversized parts collection is replaced with an explicit elision marker; metadata that still cannot fit fails validation. Canonical private Agent events are unchanged.
 
-`updateSession()` supports title replacement, explicit title clearing with `null`, and archive state through `archived`. Title-only updates remain available while prompts are queued or running, while permission is pending, and after archival. Requests containing `archived` are rejected while the session has any outstanding prompt or pending permission; a mixed title-and-archive request is rejected atomically without changing the title. Archived sessions expose `archivedAt`. Deleting a session cascades through its complete descendant subtree. One durable root-keyed tombstone group hides every newly affected live session, and the delete also joins any already-separate descendant cleanup groups without rewriting their roots. FlexHarness then cancels queued and active subtree work, emits terminal queue events, waits for admitted initialization, and purges runtime queue status while cleaning runtime and persisted domains child-first. The requested root tombstone is removed last after every domain confirms cleanup; project-management cleanup confirmation is a retained durable project tombstone rather than physical removal. An imported session can hold no project-management state, so its deletion writes no project tombstone. A successful live `deleteSession()` call emits `session.deleted` for each session it newly tombstoned; retries of an existing tombstone and automatic load, retirement, or disposal cleanup emit no deletion events. Direct deletion of a descendant cascades only through that descendant's subtree. Cleanup authority follows the resolved storage namespace, so scope aliases share the same groups. A partial failure retains durable ownership for retry by a later `deleteSession()`, namespace load, `retireScope()`, or `dispose()` call.
+`updateSession()` supports title replacement, explicit title clearing with `null`, and archive state through `archived`. Title-only updates remain available while prompts are queued or running, while permission is pending, and after archival. Requests containing `archived` are rejected while the session has any outstanding prompt or pending permission; a mixed title-and-archive request is rejected atomically without changing the title. Archived sessions expose `archivedAt`. Every session exposes `preview` once a run with prompt text was admitted: its first prompt as one line (whitespace runs collapsed, cut at a character boundary to `maxTitleBytes`), with no model call, so a host can name a session nobody titled (`title || preview`). It is set once, a session stored before previews existed takes it from its first prompt at its next run, and no caller sets or clears it. Deleting a session cascades through its complete descendant subtree. One durable root-keyed tombstone group hides every newly affected live session, and the delete also joins any already-separate descendant cleanup groups without rewriting their roots. FlexHarness then cancels queued and active subtree work, emits terminal queue events, waits for admitted initialization, and purges runtime queue status while cleaning runtime and persisted domains child-first. The requested root tombstone is removed last after every domain confirms cleanup; project-management cleanup confirmation is a retained durable project tombstone rather than physical removal. An imported session can hold no project-management state, so its deletion writes no project tombstone. A successful live `deleteSession()` call emits `session.deleted` for each session it newly tombstoned; retries of an existing tombstone and automatic load, retirement, or disposal cleanup emit no deletion events. Direct deletion of a descendant cascades only through that descendant's subtree. Cleanup authority follows the resolved storage namespace, so scope aliases share the same groups. A partial failure retains durable ownership for retry by a later `deleteSession()`, namespace load, `retireScope()`, or `dispose()` call.
 
 `deleteSessionGenerationCohort()` is the generation-fenced destructive form for controllers. Its `root` and every `authorizedCohort` entry use the exact `{ sessionId, sessionGenerationId, sessionGenerationSequence }` shape. The cohort contains unique entries in strictly ascending `sessionId` order and is limited by `FLEX_SESSION_GENERATION_COHORT_MAX_ENTRIES` (2048). FlexHarness atomically validates the matching root, its complete live subtree, and every retained descendant tombstone group before reserving deletion. A missing or different root generation returns `{ matched: false }` without touching a newer generation; a missing or mismatched cascade entry throws before new tombstoning or cleanup. Extra valid entries do not expand the cascade. A matched partial cleanup remains retryable with the same authority and resolves to `{ matched: true }` when cleanup completes. The existing `deleteSession()` method remains available for callers that intentionally own the complete reusable-ID namespace.
 
@@ -872,11 +872,13 @@ for (const group of info.groups) {
     group.visibility,
     group.affectedWorkspaces,
     group.affectedWorkspacesTruncated,
+    group.barrierCauses,
+    group.reasonCodes,
   );
 }
 ```
 
-The immutable result exposes `undoAvailable`, `redoAvailable`, and groups classified as `candidate`, `barrier`, or `no-change`. Group metadata contains at most 64 unique affected workspaces; `affectedWorkspacesTruncated` is `true` when additional unique descriptors were omitted. It never includes capture IDs or provider references.
+The immutable result exposes `undoAvailable`, `redoAvailable`, and groups classified as `candidate`, `barrier`, or `no-change`. Group metadata contains at most 64 unique affected workspaces; `affectedWorkspacesTruncated` is `true` when additional unique descriptors were omitted. `barrierCauses` states why a barrier blocks traversal, each cause once in this order: `pending` while a capture runs or its outcome is not final, `nonrevertible` for a workspace outcome that cannot be reverted, `transcript-only` for legacy transcript history without a workspace capture; it is empty for candidate and no-change groups (`FLEX_SESSION_REVERSION_BARRIER_CAUSES` lists the order). `reasonCodes` lists the distinct `reasonCode`s of the group's nonrevertible segments in segment order, so an application can say why a turn is not revertible even when its provider named no affected workspace. It never includes capture IDs or provider references.
 
 `workspaceSnapshots` is application-owned. Every context contains `scopeId`, `scope`, `storageKey`, `sessionId`, the required canonical `sessionGenerationId` and `sessionGenerationSequence`, `runId`, deterministic `captureId`, and an `AbortSignal`. Apply contexts additionally contain the normalized `reference`, per-segment `operationId`, and `direction`; release contexts contain the reference. Deleted-session recovery retains the same generation from the durable tombstone, so providers can reject callbacks from an older same-ID generation.
 
@@ -923,7 +925,7 @@ Resolved model identity contains provider and model IDs plus optional display na
 
 Public audit history is safe to send to controllers: attachment parts contain source and size metadata, never inline base64, data URLs, or remote URL payloads. Canonical private Agent events retain those values solely for subsequent model turns.
 
-Sessions expose `idle`, `scheduled`, `running`, `waiting_permission`, `failed`, and `cancelled` status. Persisted non-terminal activity is repaired from canonical Agent generation outcomes after process restart; incomplete messages and parts normalize to `cancelled` unless an accepted hidden terminal stage can be promoted.
+Sessions expose `idle`, `scheduled`, `running`, `waiting_permission`, `failed`, and `cancelled` status. A run stopped by `abort()`, `cancelPrompt()` or a rejected permission leaves its session `cancelled`; only a run that failed leaves it `failed`. Persisted non-terminal activity is repaired from canonical Agent generation outcomes after process restart; incomplete messages and parts normalize to `cancelled` unless an accepted hidden terminal stage can be promoted.
 
 ## Conversation Import
 
@@ -1023,6 +1025,8 @@ Pending requests are runtime-only and queryable with `listPendingPermissions()`.
 
 `always` is invalid when the request has no `rememberKey`. Remembered decisions are persisted before the waiting tool resolves. If persistence fails, the key is rolled back and the request remains pending so the response can be retried. Concurrent response attempts are serialized and exactly one successful response settles a request.
 
+`reject` stops the run as a decision, not as a failure. The waiting tool call fails with `FlexHarnessPermissionRejectedError`, a `FlexHarnessAbortError` with code `FLEX_PERMISSION_REJECTED` and the rejected `permissionId`, and the run ends the way `abort()` or `cancelPrompt()` ends it; the model is not asked to recover. The run's completion rejects with that error. `run.finished` and the finished queue entry have status `cancelled` and an `error` whose `permissionId` names the rejected request. The run's terminal user and assistant messages are `cancelled`; the assistant message carries `rejectedPermissionId` next to its `error`, and so does the session's `activity`; the session's status is `cancelled`, as after a stop. The refused tool part fails with the rejection as its error and carries the same `rejectedPermissionId`. Other permissions still pending in the run are rejected with it, and runs it delegated stop with "The parent run was aborted.". As with a stop, a run rejected after its model produced output stays in future context, where the refused call's result says the permission was rejected. A permission policy `deny` ends the run the same way.
+
 ## Tool Output Safety
 
 FlexHarness wraps every provided tool `execute` method before AgentSession receives it. Direct outputs and every `AsyncIterable` yield are converted into bounded JSON-safe values. Circular references, functions, symbols, bigint values, dates, URLs, and binary values receive deterministic descriptions or records. Returned error objects and unreadable getter values receive fixed descriptions without their original messages. Thrown errors and iterator failures remain failures but are converted to the safe external-error projection before AgentSession observes them.

package/ts/utils.flexharness.ts

@@ -1,6 +1,7 @@
 import * as plugins from './plugins.js';
 import {
   FlexHarnessAbortError,
+  FlexHarnessPermissionRejectedError,
   FlexHarnessRunError,
   FlexHarnessValidationError,
 } from './errors.js';
@@ -106,14 +107,27 @@ export function combineErrors(errors: unknown[]): unknown {
   return Object.freeze(combined);
 }
 
-/** The error and model limit a finished run leaves on its session activity. */
-export function terminalActivityError(message: IFlexMessage): Pick<IFlexSessionActivity, 'error' | 'limit'> {
+/** The error, model limit and rejected permission a finished run leaves on its session activity. */
+export function terminalActivityError(
+  message: IFlexMessage,
+): Pick<IFlexSessionActivity, 'error' | 'limit' | 'rejectedPermissionId'> {
   return {
     ...(message.error ? { error: message.error } : {}),
     ...(message.limit ? { limit: message.limit } : {}),
+    ...(message.rejectedPermissionId ? { rejectedPermissionId: message.rejectedPermissionId } : {}),
   };
 }
 
+/**
+ * The parent run's cancellation when the runs it delegated share it: a stop stops them alike, but a
+ * permission the parent rejected is the parent's own.
+ */
+export function delegatedCancellation(reason: unknown): FlexHarnessAbortError | undefined {
+  return reason instanceof FlexHarnessAbortError && !(reason instanceof FlexHarnessPermissionRejectedError)
+    ? reason
+    : undefined;
+}
+
 export function isAbortError(error: unknown): boolean {
   return error instanceof FlexHarnessAbortError
     || (error instanceof DOMException && error.name === 'AbortError')

package/ts/utils.json.ts

@@ -533,6 +533,7 @@ function validateSession(value: unknown, path: string): IValidatedSessionIdentit
       'sessionGenerationSequence',
       'configurationRef',
       'title',
+      'preview',
       'createdAt',
       'updatedAt',
       'archivedAt',
@@ -555,6 +556,7 @@ function validateSession(value: unknown, path: string): IValidatedSessionIdentit
     throw new FlexHarnessStoreFormatError(`${path}.configurationRef is invalid.`);
   }
   requireOptionalString(session.title, `${path}.title`);
+  requireOptionalString(session.preview, `${path}.preview`);
   requireString(session.createdAt, `${path}.createdAt`);
   requireString(session.updatedAt, `${path}.updatedAt`);
   requireOptionalString(session.archivedAt, `${path}.archivedAt`);
@@ -562,7 +564,11 @@ function validateSession(value: unknown, path: string): IValidatedSessionIdentit
     throw new FlexHarnessStoreFormatError(`${path}.status is invalid.`);
   }
   const activity = requireRecord(session.activity, `${path}.activity`);
-  requireOnlyKeys(activity, ['runId', 'status', 'startedAt', 'completedAt', 'error', 'limit'], `${path}.activity`);
+  requireOnlyKeys(
+    activity,
+    ['runId', 'status', 'startedAt', 'completedAt', 'error', 'limit', 'rejectedPermissionId'],
+    `${path}.activity`,
+  );
   if (!activityStatuses.includes(activity.status as (typeof activityStatuses)[number])) {
     throw new FlexHarnessStoreFormatError(`${path}.activity.status is invalid.`);
   }
@@ -571,6 +577,7 @@ function validateSession(value: unknown, path: string): IValidatedSessionIdentit
   requireOptionalString(activity.completedAt, `${path}.activity.completedAt`);
   requireOptionalString(activity.error, `${path}.activity.error`);
   requireOptionalModelLimit(activity.limit, `${path}.activity.limit`);
+  requireOptionalString(activity.rejectedPermissionId, `${path}.activity.rejectedPermissionId`);
   const relationship = [
     session.parentSessionId,
     session.parentRunId,
@@ -767,6 +774,7 @@ function validateMessage(value: unknown, path: string): IValidatedMessageIdentit
       'usage',
       'error',
       'limit',
+      'rejectedPermissionId',
       'steerId',
     ],
     path,
@@ -784,6 +792,7 @@ function validateMessage(value: unknown, path: string): IValidatedMessageIdentit
   requireOptionalString(message.completedAt, `${path}.completedAt`);
   requireOptionalString(message.error, `${path}.error`);
   requireOptionalModelLimit(message.limit, `${path}.limit`);
+  requireOptionalString(message.rejectedPermissionId, `${path}.rejectedPermissionId`);
   if (message.steerId !== undefined) {
     requireString(message.steerId, `${path}.steerId`);
     if (message.role !== 'user') {
@@ -834,6 +843,7 @@ function validateMessage(value: unknown, path: string): IValidatedMessageIdentit
           'childSessionId',
           'parentToolCallId',
           'deduplicatedFrom',
+          'rejectedPermissionId',
           'model',
           'startedAt',
           'completedAt',
@@ -852,6 +862,7 @@ function validateMessage(value: unknown, path: string): IValidatedMessageIdentit
       requireOptionalString(part.childSessionId, `${partPath}.childSessionId`);
       requireOptionalString(part.parentToolCallId, `${partPath}.parentToolCallId`);
       requireOptionalString(part.deduplicatedFrom, `${partPath}.deduplicatedFrom`);
+      requireOptionalString(part.rejectedPermissionId, `${partPath}.rejectedPermissionId`);
       if (part.model !== undefined) validateModel(part.model, `${partPath}.model`);
       requireOptionalString(part.startedAt, `${partPath}.startedAt`);
       requireOptionalString(part.completedAt, `${partPath}.completedAt`);

package/ts/utils.sessionpreview.ts

@@ -0,0 +1,32 @@
+import { FLEX_PROJECT_MANAGEMENT_LIMITS, type IFlexMessage } from './interfaces.js';
+
+/**
+ * What a session is about before anyone titles it: the text of its first prompt that has any, as
+ * one line (every run of whitespace becomes one space), cut to the title bound at a character
+ * boundary. Undefined while no prompt carries text.
+ */
+export function sessionPreview(messagesArg: readonly IFlexMessage[]): string | undefined {
+  for (const message of messagesArg) {
+    if (message.role !== 'user') continue;
+    const text = message.parts
+      .map((part) => (part.type === 'text' ? part.text : ''))
+      .join(' ')
+      .replace(/\s+/gu, ' ')
+      .trim();
+    if (text) return utf8Prefix(text, FLEX_PROJECT_MANAGEMENT_LIMITS.maxTitleBytes);
+  }
+  return undefined;
+}
+
+/** The longest prefix of whole characters within `maxBytesArg` UTF-8 bytes. */
+function utf8Prefix(valueArg: string, maxBytesArg: number): string {
+  if (Buffer.byteLength(valueArg, 'utf8') <= maxBytesArg) return valueArg;
+  let bytes = 0;
+  let end = 0;
+  for (const character of valueArg) {
+    bytes += Buffer.byteLength(character, 'utf8');
+    if (bytes > maxBytesArg) break;
+    end += character.length;
+  }
+  return valueArg.slice(0, end).trimEnd();
+}

package/ts_typedrequest/catalog.ts

@@ -6,6 +6,7 @@ import type {
   IFlexTypedRequestSurface,
 } from './interfaces.js';
 import { normalizeOmissionPaths, withoutRequestPaths, withRequestPaths } from './omissions.js';
+import { typesReachedBy } from './references.js';
 
 /**
  * A typed request the router refused: the `text` and `data` of its error, as a client of the API
@@ -31,7 +32,9 @@ export class FlexTypedRequestError extends Error {
  * `router.routeAndAddResponse()` in process, its request what `params` makes of the model's
  * parameters with the omitted properties its request has as `request` fills them, and its result
  * what `response` makes of the answer. A refusal rejects with `FlexTypedRequestError`. A method
- * `readOnly` marks is declared read-only, including when `onCall` decides its calls.
+ * `readOnly` marks is declared read-only, including when `onCall` decides its calls. The catalog's
+ * types are the surface's types the included methods reach: one only methods left out use is
+ * neither declared nor described.
  */
 export function catalogFromTypedRequests<TScope = unknown>(
   surface: IFlexTypedRequestSurface,
@@ -108,8 +111,9 @@ export function catalogFromTypedRequests<TScope = unknown>(
       ? await options.response(method, answer.response as Record<string, unknown>, context)
       : answer.response;
   };
+  const included = surface.methods.filter((method) => include(method));
   return {
-    methods: surface.methods.filter((method) => include(method)).map((method): IFlexCatalogMethod<TScope> => ({
+    methods: included.map((method): IFlexCatalogMethod<TScope> => ({
       method: method.path,
       summary: method.summary,
       ...(method.description ? { description: method.description } : {}),
@@ -123,7 +127,7 @@ export function catalogFromTypedRequests<TScope = unknown>(
         ? { onCall: (params: Record<string, unknown>, context: IFlexCatalogRunContext<TScope>) => options.onCall!(method, params, context) }
         : {}),
     })),
-    types: surface.types,
+    types: typesReachedBy(included, surface.types),
     ...(options.vocabulary ? { vocabulary: options.vocabulary } : {}),
     ...(options.onProposals ? { onProposals: options.onProposals } : {}),
   };

package/ts_typedrequest/describe.ts

@@ -7,14 +7,11 @@ import type {
   TFlexTypedRequestSchema,
 } from './interfaces.js';
 import { normalizeOmissionPaths } from './omissions.js';
+import { definitionsPrefix, isRecord, referencedType, referencesIn } from './references.js';
 
 const componentsPrefix = '#/components/schemas/';
-const definitionsPrefix = '#/$defs/';
 const maxSummaryCharacters = 120;
 
-const isRecord = (value: unknown): value is Record<string, unknown> =>
-  typeof value === 'object' && value !== null && !Array.isArray(value);
-
 /** A schema whose references name `#/$defs/<type>` instead of the OpenAPI components. */
 const withDefinitionRefs = (value: unknown): unknown => {
   if (Array.isArray(value)) return value.map(withDefinitionRefs);
@@ -27,12 +24,6 @@ const withDefinitionRefs = (value: unknown): unknown => {
   ]));
 };
 
-/** The type a `#/$defs/<type>` reference names. */
-const referencedType = (schema: TFlexTypedRequestSchema): string | undefined =>
-  typeof schema.$ref === 'string' && schema.$ref.startsWith(definitionsPrefix)
-    ? schema.$ref.slice(definitionsPrefix.length)
-    : undefined;
-
 /**
  * A request schema without the omitted properties: an object loses them, and a reference to a
  * named type that holds one becomes the type's own schema without them.
@@ -167,18 +158,6 @@ const requiresNothing = (
     || schema.allOf.every((member) => !isRecord(member) || requiresNothing(member, types));
 };
 
-/** The named types a schema refers to. */
-const referencesIn = (value: unknown, found: Set<string>): Set<string> => {
-  if (Array.isArray(value)) {
-    for (const entry of value) referencesIn(entry, found);
-  } else if (isRecord(value)) {
-    const target = referencedType(value);
-    if (target !== undefined) found.add(target);
-    for (const child of Object.values(value)) referencesIn(child, found);
-  }
-  return found;
-};
-
 /** The first sentence of a contract's JSDoc, its tags left out, within the summary's length. */
 const summaryOf = (documentation: string | undefined, method: string): string => {
   const prose = (documentation ?? '').split(/\n(?=@)/)[0].replace(/\s+/g, ' ').trim();

package/ts_typedrequest/interfaces.ts

@@ -125,7 +125,10 @@ export interface IFlexTypedRequestCatalogOptions<TScope = unknown> {
     method: IFlexTypedRequestMethod,
     context: IFlexCatalogRunContext<TScope>,
   ): Record<string, unknown> | PromiseLike<Record<string, unknown>>;
-  /** The methods the model may use. Default: every method that is not deprecated. */
+  /**
+   * The methods the model may use. Default: every method that is not deprecated. The catalog keeps
+   * only the named types these methods reach.
+   */
   include?(method: IFlexTypedRequestMethod): boolean;
   /**
    * The methods that only read: a call has no effect but its result. Such a method is declared

package/ts_typedrequest/readme.md

@@ -41,7 +41,7 @@ The surface is plain JSON, so a build step can write it next to the server and t
 - `request` fills the omitted properties. A call takes from what it returns only the omitted properties its method's request has, so one answer serves every method (`{ identity, csrfToken }`), and a method whose request has none is routed without asking it. A value the model passes for any omitted property never reaches the router.
 - Method-specific fills copy only the selected leaves, retaining public siblings. Array wildcards fill existing elements at corresponding indexes without adding or removing elements. An absent object parent can be created for a supplied leaf; an explicit null or scalar parent is refused. Input objects are not mutated. A surface with additional paths requires `request`; a serialized global-only surface without `omittedPaths` remains valid.
 - A refusal rejects with `FlexTypedRequestError`: the typed method, the error's `text` and `data`, as a client of the API would receive them. A handler's own failure arrives as the router's internal error. A host's `externalErrorProjector` decides what of it the model sees.
-- `include` picks the methods the model may use, by default every method that is not deprecated; `aliases` gives methods other names by typed method; `vocabulary`, `onCall` and `onProposals` are the catalog's own (`onCall` receives the typed method first).
+- `include` picks the methods the model may use, by default every method that is not deprecated, and the catalog's types are the surface's types those methods reach, through their schemas' `$ref`s and the names their declarations' code uses: a type only methods left out use is neither declared nor described, unless it holds a lower identifier of a kept type's name, which keeps that type's identifier as the whole surface declares it (`a_b` stays for `a-b`, declared `a_b_2`; `FlexToolCatalog.identifiersOf()`). `aliases` gives methods other names by typed method; `vocabulary`, `onCall` and `onProposals` are the catalog's own (`onCall` receives the typed method first).
 - `readOnly` marks the methods that only read, including their policy hook. A marked method is declared `readOnly` and its `onCall` still decides every validated call, so reads run concurrently, may start while the model still streams, and a turn answers identical ones once after each call's hook allows it; every other method's calls, gated by `onCall` or not, run in the order the model made them. A policy that proposes changes must return `run` for the reads it allows, rather than relying on reads skipping the hook. Mark nothing that asks for permission.
 - `params` makes the request a call routes of the model's validated parameters, such as the parameters with the short names the model was shown for records turned back into their IDs; by default the parameters themselves. It runs when the call runs, after `onCall` decided it where the method has one, so `onCall` and a proposal see the model's parameters. The omitted properties are dropped from what it returns as from the model's, and only `request` fills them. A throw refuses the call with its error, and so does a result that is no object.
 - The same validation, policy, stripping and filling apply to `execute` and every call inside `run_code`. Private inputs are rejected before `onCall`; a proposed change does not run `params`, `request` or the router. Omissions cover inputs only: use `response` to remove secrets from answers before they reach the model.