@modelprofile.com/flexharness 4.0.2 → 4.1.1

package/ts/classes.flexharness.ts

@@ -20,8 +20,6 @@ import {
 import {
   FLEX_PROJECT_MANAGEMENT_LIMITS,
   FLEX_REVERSION_MAX_AFFECTED_WORKSPACES,
-  FLEX_REVERSION_DEFAULT_LIMITS,
-  FLEX_REVERSION_MAXIMUM_LIMITS,
   FLEX_REVERSION_REASON_CODE_MAX_BYTES,
   FLEX_REVERSION_REFERENCE_MAX_BYTES,
   FLEX_REVERSION_WORKSPACE_ID_MAX_BYTES,
@@ -31,7 +29,6 @@ import type {
   IFlexAgentContextInvocation,
   IFlexAgentSessionPolicy,
   IFlexAffectedWorkspace,
-  IFlexAttachmentMessagePart,
   IFlexBackgroundExecution,
   IFlexCallbackLimits,
   IFlexCreateProjectTaskInput,
@@ -83,7 +80,6 @@ import type {
   IFlexSlashCommandDescriptor,
   IFlexSlashCommandExecutionOptions,
   IFlexSlashCommandHandlerRegistration,
-  IFlexSlashCommandTemplateRegistration,
   IFlexSubagentDefinition,
   IFlexTerminalProjection,
   IFlexToolHandle,
@@ -93,12 +89,10 @@ import type {
   IFlexUndoSessionResult,
   IFlexUpdateSessionOptions,
   IFlexUpdateProjectTaskInput,
-  IFlexUsage,
   IJsonObject,
-  TFlexAgentRunResult,
+  TFlexAgentToolCallUpdateEvent,
   TFlexAgentToolCallFinishEvent,
   TFlexAgentToolSet,
-  TFlexAttachmentSource,
   TFlexExternalErrorProjector,
   TFlexExternalErrorSource,
   TFlexHarnessEvent,
@@ -108,10 +102,8 @@ import type {
   TFlexProjectTaskPriority,
   TFlexProjectTaskStatus,
   TFlexPrompt,
-  TFlexPromptPart,
   TFlexPromptQueueStatus,
   TFlexSlashCommandExecutionResult,
-  TFlexSlashCommandRegistration,
   TFlexPendingReversion,
   TFlexProjectionSnapshot,
   TFlexReversionPolicy,
@@ -138,14 +130,58 @@ import {
   normalizeFlexPrompt,
   type INormalizedFlexPrompt,
 } from './utils.prompt.js';
+import {
+  maxSubagentNameBytes,
+  normalizeAgentSessionPolicy,
+  normalizeBuiltInTools,
+  normalizeSlashCommands,
+  normalizeSubagents,
+  requireHarnessStores,
+  resolveBoundedPositiveInteger,
+  resolveCallbackLimits,
+  resolvePromptQueueLimits,
+  resolveReversionLimits,
+  type INormalizedBuiltInTools,
+  type INormalizedProjectManagementTools,
+  type TRegisteredSlashCommand,
+} from './utils.harnessoptions.js';
 import {
   FLEX_SLASH_COMMAND_INITIALIZE_TEMPLATE,
-  FLEX_SLASH_COMMAND_MAX_INPUT_BYTES,
   expandSlashCommandTemplate,
-  isValidSlashCommandName,
+  isReservedSlashCommandName,
   parseSlashCommand,
   slashCommandTemplateHints,
 } from './utils.slashcommands.js';
+import {
+  createBoundedTransferMessage,
+  describeAttachment,
+  jsonBytes,
+  maxMessagePageCursorBytes,
+  maxMessagePageSize,
+  maxTransferIdentifierBytes,
+  maxTransferMetadataBytes,
+  maxTransferPageBytes,
+  maxTransferTextBytes,
+  normalizeModelIdentity,
+  normalizeResolvedModel,
+  normalizeRunResult,
+  publicSnapshot,
+  requireTransferIdentifier,
+  truncateUtf8,
+  type IRunResultProjection,
+} from './utils.transfer.js';
+import { wrapToolSet } from './utils.tooloutput.js';
+import {
+  validateCreateProjectTaskInput,
+  validateIdentifier,
+  validateProjectTaskId,
+  validateProjectedErrorInfo,
+  validatePromptOptions,
+  validateSlashCommandExecutionOptions,
+  validateUpdateProjectTaskInput,
+  validateUpdateSessionOptions,
+  validateUtf8String,
+} from './utils.validation.js';
 
 type TCanonicalOutcome = 'accepted' | 'rejected' | 'interrupted';
 type TRunPhase =
@@ -347,10 +383,6 @@ interface IScopeAdmissionState {
   retiring: boolean;
 }
 
-type TRegisteredSlashCommand<TScope> =
-  | Readonly<IFlexSlashCommandTemplateRegistration>
-  | Readonly<IFlexSlashCommandHandlerRegistration<TScope>>;
-
 interface IActiveSlashCommandExecution {
   kind: 'handler' | 'operation' | 'prompt-admission';
   storageKey: string;
@@ -379,13 +411,6 @@ interface ISlashCommandActivityOwner {
   sessionId: string;
 }
 
-interface IRunResultProjection {
-  text: string;
-  steps: number;
-  finishReason: string;
-  usage: IFlexUsage;
-}
-
 interface IResolverOutcome<TValue> {
   source: 'model' | 'tools' | 'abort';
   success: boolean;
@@ -400,10 +425,6 @@ interface IFlexMessageCursor {
   anchorMessageId: string;
 }
 
-interface IExecutableToolRecord extends Record<string, unknown> {
-  execute?: (input: unknown, options: unknown) => unknown;
-}
-
 interface IFlexSubagentTaskInput {
   description: string;
   prompt: string;
@@ -416,17 +437,6 @@ interface IFlexSubagentAcquisition {
   created: boolean;
 }
 
-interface INormalizedProjectManagementTools {
-  readonly task: boolean;
-  readonly goal: boolean;
-  readonly scratchpad: boolean;
-}
-
-interface INormalizedBuiltInTools {
-  readonly renameSession: boolean;
-  readonly projectManagement?: INormalizedProjectManagementTools;
-}
-
 type TProjectTaskToolInput =
   | { action: 'list' }
   | {
@@ -461,35 +471,8 @@ type TEventDetails = Record<string, unknown> & {
   type: TFlexHarnessEvent['type'];
 };
 
-const DEFAULT_CALLBACK_LIMITS: Required<IFlexCallbackLimits> = {
-  maxEvents: 10_000,
-  maxOutputBytes: 1024 * 1024,
-  maxParts: 2_000,
-};
-const DEFAULT_PROMPT_QUEUE_LIMITS: Required<IFlexPromptQueueLimits> = {
-  maxOutstandingPromptsPerSession: 16,
-  maxOutstandingBytesPerSession: 64 * 1024 * 1024,
-  maxPendingAdmissions: 64,
-  maxPendingAdmissionBytes: 128 * 1024 * 1024,
-  maxTerminalEntriesPerSession: 64,
-};
-const maxMessagePageSize = 50;
-const maxMessagePageCursorBytes = 4096;
-const maxTransferIdentifierBytes = 512;
-const maxTransferMetadataBytes = 2048;
-const maxTransferTextBytes = 96 * 1024;
-const maxTransferMessageBytes = 480 * 1024;
-const maxTransferPageBytes = 512 * 1024;
-const maxProjectedErrorNameBytes = 128;
-const maxProjectedErrorMessageBytes = 2048;
-const maxProjectedErrorCodeBytes = 128;
 const maxScheduleDebounceMs = 24 * 60 * 60 * 1000;
 const maxBackgroundExecutions = 100;
-const maxSubagentDefinitions = 32;
-const maxSubagentNameBytes = 128;
-const maxSubagentDescriptionBytes = 2048;
-const maxSubagentModelHintBytes = 512;
-const maxSubagentSystemBytes = 64 * 1024;
 const maxSubagentTaskDescriptionBytes = 256;
 const maxSubagentPromptBytes = 64 * 1024;
 const maxSubagentTaskIdBytes = 512;
@@ -501,15 +484,11 @@ const maximumMaxSubagentCallsPerRun = 128;
 const maxResourceToolProviders = 128;
 const maxResourceIdBytes = 512;
 const maxResourceToolNameBytes = 512;
-const maxSlashCommandRegistrations = 128;
-const maxSlashCommandDescriptionBytes = 2048;
-const maxSlashCommandTemplateBytes = FLEX_SLASH_COMMAND_MAX_INPUT_BYTES;
 const maxProjectManagementTombstoneConflicts = 8;
 const resourceToolStemLength = 16;
 const repairCancellationMessage = 'The process stopped before this run completed.';
 const scopeRetirementMessage = 'The scope is being retired.';
 const slashCommandSessionUnavailableReason = 'Session must be idle with no queued prompts.';
-const reservedSlashCommandNames = new Set(['compact', 'undo', 'redo', 'init']);
 const externalErrorFallback: IFlexErrorInfo = Object.freeze({
   name: 'FlexHarnessExternalError',
   message: 'The model operation failed.',
@@ -553,97 +532,6 @@ function requireSessionGeneration(
   };
 }
 
-function isAsyncIterable(value: unknown): value is AsyncIterable<unknown> {
-  return Boolean(
-    value
-    && typeof value === 'object'
-    && typeof (value as { [Symbol.asyncIterator]?: unknown })[Symbol.asyncIterator] === 'function',
-  );
-}
-
-async function* normalizeAsyncIterable(
-  iterable: AsyncIterable<unknown>,
-  limits: Required<NonNullable<IFlexHarnessOptions<unknown>['toolOutputLimits']>>,
-  projectError: (error: unknown) => Error,
-): AsyncGenerator<unknown> {
-  try {
-    for await (const value of iterable) yield normalizeJsonValue(value, limits);
-  } catch (error) {
-    throw projectError(error);
-  }
-}
-
-function wrapToolSet(
-  tools: TFlexAgentToolSet,
-  limits: Required<NonNullable<IFlexHarnessOptions<unknown>['toolOutputLimits']>>,
-  projectError: (error: unknown) => Error,
-): TFlexAgentToolSet {
-  const wrapped: Record<string, unknown> = {};
-  for (const [name, tool] of Object.entries(tools)) {
-    const toolRecord = tool as unknown as IExecutableToolRecord;
-    if (typeof toolRecord.execute !== 'function') {
-      wrapped[name] = tool;
-      continue;
-    }
-    const execute = toolRecord.execute;
-    wrapped[name] = {
-      ...toolRecord,
-      execute(input: unknown, options: unknown): unknown {
-        let output: unknown;
-        try {
-          output = execute.call(tool, input, options);
-          if (isAsyncIterable(output)) {
-            return normalizeAsyncIterable(output, limits, projectError);
-          }
-        } catch (error) {
-          throw projectError(error);
-        }
-        return Promise.resolve(output).then(
-          (value) => {
-            try {
-              return normalizeJsonValue(value, limits);
-            } catch (error) {
-              throw projectError(error);
-            }
-          },
-          (error: unknown) => {
-            throw projectError(error);
-          },
-        );
-      },
-    };
-  }
-  return wrapped as TFlexAgentToolSet;
-}
-
-function publicSnapshot<TValue>(value: TValue): TValue {
-  return deepFreeze(cloneSerializable(value));
-}
-
-function jsonBytes(value: unknown): number {
-  return Buffer.byteLength(JSON.stringify(value), 'utf8');
-}
-
-function truncateUtf8(value: string, maxBytes: number): string {
-  if (Buffer.byteLength(value, 'utf8') <= maxBytes) return value;
-  const suffix = ' [truncated]';
-  const suffixBytes = Buffer.byteLength(suffix, 'utf8');
-  let truncated = Buffer.from(value, 'utf8')
-    .subarray(0, Math.max(0, maxBytes - suffixBytes))
-    .toString('utf8')
-    .replace(/\uFFFD$/u, '');
-  while (Buffer.byteLength(`${truncated}${suffix}`, 'utf8') > maxBytes) {
-    truncated = truncated.slice(0, -1);
-  }
-  return `${truncated}${suffix}`;
-}
-
-function validateIdentifier(value: string, name: string): void {
-  if (typeof value !== 'string' || value.length === 0) {
-    throw new FlexHarnessValidationError(`${name} must be a non-empty string.`);
-  }
-}
-
 function sha256Hex(value: string): string {
   return plugins.crypto.createHash('sha256').update(value, 'utf8').digest('hex');
 }
@@ -678,346 +566,6 @@ export function createFlexResourceToolName(namespace: string, toolName: string):
   return `${namespace}__${stem}__${sha256Hex(toolName).slice(0, 12)}`;
 }
 
-function validateUtf8String(
-  value: unknown,
-  name: string,
-  maxBytes: number,
-  nonEmpty = false,
-): asserts value is string {
-  if (
-    typeof value !== 'string'
-    || (nonEmpty && !value.trim())
-    || Buffer.byteLength(value, 'utf8') > maxBytes
-  ) {
-    throw new FlexHarnessValidationError(
-      `${name} must be ${nonEmpty ? 'a non-empty ' : 'a '}string of at most ${maxBytes} UTF-8 bytes.`,
-    );
-  }
-}
-
-function normalizeSubagents(
-  definitions: IFlexSubagentDefinition[] | undefined,
-): ReadonlyMap<string, Readonly<IFlexSubagentDefinition>> {
-  if (definitions === undefined) return new Map();
-  if (!Array.isArray(definitions) || definitions.length > maxSubagentDefinitions) {
-    throw new FlexHarnessValidationError(
-      `subagents must be an array with at most ${maxSubagentDefinitions} definitions.`,
-    );
-  }
-  const normalized = new Map<string, Readonly<IFlexSubagentDefinition>>();
-  for (let index = 0; index < definitions.length; index++) {
-    const definition = definitions[index];
-    if (
-      !definition
-      || typeof definition !== 'object'
-      || Array.isArray(definition)
-      || ![Object.prototype, null].includes(Object.getPrototypeOf(definition))
-    ) {
-      throw new FlexHarnessValidationError(`subagents[${index}] must be a plain object.`);
-    }
-    const unsupported = Object.keys(definition).find(
-      (key) => !['name', 'description', 'modelHint', 'system', 'maxSteps'].includes(key),
-    );
-    if (unsupported) {
-      throw new FlexHarnessValidationError(`subagents[${index}] does not support "${unsupported}".`);
-    }
-    validateUtf8String(definition.name, `subagents[${index}].name`, maxSubagentNameBytes, true);
-    validateUtf8String(
-      definition.description,
-      `subagents[${index}].description`,
-      maxSubagentDescriptionBytes,
-    );
-    if (definition.modelHint !== undefined) {
-      validateUtf8String(
-        definition.modelHint,
-        `subagents[${index}].modelHint`,
-        maxSubagentModelHintBytes,
-      );
-    }
-    if (definition.system !== undefined) {
-      validateUtf8String(
-        definition.system,
-        `subagents[${index}].system`,
-        maxSubagentSystemBytes,
-      );
-    }
-    if (
-      definition.maxSteps !== undefined
-      && (!Number.isSafeInteger(definition.maxSteps) || definition.maxSteps < 1)
-    ) {
-      throw new FlexHarnessValidationError(`subagents[${index}].maxSteps must be a positive integer.`);
-    }
-    if (normalized.has(definition.name)) {
-      throw new FlexHarnessValidationError(`Duplicate subagent definition "${definition.name}".`);
-    }
-    normalized.set(definition.name, Object.freeze({
-      name: definition.name,
-      description: definition.description,
-      ...(definition.modelHint === undefined ? {} : { modelHint: definition.modelHint }),
-      ...(definition.system === undefined ? {} : { system: definition.system }),
-      ...(definition.maxSteps === undefined ? {} : { maxSteps: definition.maxSteps }),
-    }));
-  }
-  return Object.freeze(normalized);
-}
-
-function normalizeBuiltInTools(
-  options: IFlexHarnessOptions<unknown>['builtInTools'],
-): INormalizedBuiltInTools {
-  if (options === undefined) return Object.freeze({ renameSession: false });
-  if (
-    !options
-    || typeof options !== 'object'
-    || Array.isArray(options)
-    || ![Object.prototype, null].includes(Object.getPrototypeOf(options))
-  ) {
-    throw new FlexHarnessValidationError('builtInTools must be a plain object.');
-  }
-  const unsupported = Object.keys(options)
-    .find((key) => !['renameSession', 'projectManagement'].includes(key));
-  if (unsupported) throw new FlexHarnessValidationError(`builtInTools does not support "${unsupported}".`);
-  if (options.renameSession !== undefined && typeof options.renameSession !== 'boolean') {
-    throw new FlexHarnessValidationError('builtInTools.renameSession must be a boolean.');
-  }
-  const projectManagement = options.projectManagement;
-  if (projectManagement === undefined) {
-    return Object.freeze({ renameSession: options.renameSession ?? false });
-  }
-  if (
-    !projectManagement
-    || typeof projectManagement !== 'object'
-    || Array.isArray(projectManagement)
-    || ![Object.prototype, null].includes(Object.getPrototypeOf(projectManagement))
-  ) {
-    throw new FlexHarnessValidationError('builtInTools.projectManagement must be a plain object.');
-  }
-  const unsupportedProjectOption = Object.keys(projectManagement)
-    .find((key) => !['task', 'goal', 'scratchpad'].includes(key));
-  if (unsupportedProjectOption) {
-    throw new FlexHarnessValidationError(
-      `builtInTools.projectManagement does not support "${unsupportedProjectOption}".`,
-    );
-  }
-  for (const key of ['task', 'goal', 'scratchpad'] as const) {
-    if (projectManagement[key] !== undefined && typeof projectManagement[key] !== 'boolean') {
-      throw new FlexHarnessValidationError(`builtInTools.projectManagement.${key} must be a boolean.`);
-    }
-  }
-  return Object.freeze({
-    renameSession: options.renameSession ?? false,
-    projectManagement: Object.freeze({
-      task: projectManagement.task ?? true,
-      goal: projectManagement.goal ?? true,
-      scratchpad: projectManagement.scratchpad ?? true,
-    }),
-  });
-}
-
-function normalizeSlashCommands<TScope>(
-  registrations: readonly TFlexSlashCommandRegistration<TScope>[] | undefined,
-): ReadonlyMap<string, TRegisteredSlashCommand<TScope>> {
-  if (registrations === undefined) return new Map();
-  if (!Array.isArray(registrations) || registrations.length > maxSlashCommandRegistrations) {
-    throw new FlexHarnessValidationError(
-      `slashCommands must be an array with at most ${maxSlashCommandRegistrations} registrations.`,
-    );
-  }
-  const normalized = new Map<string, TRegisteredSlashCommand<TScope>>();
-  for (let index = 0; index < registrations.length; index++) {
-    const registration = registrations[index];
-    if (
-      !registration
-      || typeof registration !== 'object'
-      || Array.isArray(registration)
-      || ![Object.prototype, null].includes(Object.getPrototypeOf(registration))
-    ) {
-      throw new FlexHarnessValidationError(`slashCommands[${index}] must be a plain object.`);
-    }
-    const keys = Object.keys(registration);
-    const hasTemplate = Object.prototype.hasOwnProperty.call(registration, 'template');
-    const hasHandler = Object.prototype.hasOwnProperty.call(registration, 'handler');
-    const supported = hasTemplate
-      ? ['name', 'description', 'template']
-      : ['name', 'description', 'handler'];
-    const unsupported = keys.find((key) => !supported.includes(key));
-    if (unsupported || hasTemplate === hasHandler) {
-      throw new FlexHarnessValidationError(
-        `slashCommands[${index}] must define exactly one of template or handler.`,
-      );
-    }
-    if (typeof registration.name !== 'string' || !isValidSlashCommandName(registration.name)) {
-      throw new FlexHarnessValidationError(`slashCommands[${index}].name is invalid.`);
-    }
-    if (reservedSlashCommandNames.has(registration.name)) {
-      throw new FlexHarnessValidationError(
-        `Slash command "${registration.name}" is reserved.`,
-      );
-    }
-    if (normalized.has(registration.name)) {
-      throw new FlexHarnessValidationError(`Duplicate slash command "${registration.name}".`);
-    }
-    if (registration.description !== undefined) {
-      validateUtf8String(
-        registration.description,
-        `slashCommands[${index}].description`,
-        maxSlashCommandDescriptionBytes,
-        true,
-      );
-    }
-    if (hasTemplate) {
-      const template = registration.template;
-      validateUtf8String(
-        template,
-        `slashCommands[${index}].template`,
-        maxSlashCommandTemplateBytes,
-        true,
-      );
-      normalized.set(registration.name, Object.freeze({
-        name: registration.name,
-        ...(registration.description === undefined
-          ? {}
-          : { description: registration.description }),
-        template,
-      }));
-    } else {
-      const handler = registration.handler;
-      if (typeof handler !== 'function') {
-        throw new FlexHarnessValidationError(`slashCommands[${index}].handler must be a function.`);
-      }
-      normalized.set(registration.name, Object.freeze({
-        name: registration.name,
-        ...(registration.description === undefined
-          ? {}
-          : { description: registration.description }),
-        handler,
-      }));
-    }
-  }
-  return Object.freeze(normalized);
-}
-
-function resolveBoundedPositiveInteger(
-  value: number | undefined,
-  name: string,
-  defaultValue: number,
-  maximum: number,
-): number {
-  const resolved = value ?? defaultValue;
-  if (!Number.isSafeInteger(resolved) || resolved < 1 || resolved > maximum) {
-    throw new FlexHarnessValidationError(`${name} must be an integer from 1 through ${maximum}.`);
-  }
-  return resolved;
-}
-
-function requireTransferIdentifier(value: string, field: string): void {
-  if (Buffer.byteLength(value, 'utf8') > maxTransferIdentifierBytes) {
-    throw new FlexHarnessValidationError(`${field} exceeds the transfer limit.`);
-  }
-}
-
-function validateProjectedErrorInfo(value: unknown): IFlexErrorInfo {
-  if (
-    !value
-    || typeof value !== 'object'
-    || Array.isArray(value)
-    || ![Object.prototype, null].includes(Object.getPrototypeOf(value))
-  ) {
-    throw new FlexHarnessValidationError('External error projection is invalid.');
-  }
-  const descriptors = Object.getOwnPropertyDescriptors(value);
-  const unsupportedKey = Reflect.ownKeys(descriptors).find(
-    (key) => typeof key !== 'string' || !['name', 'message', 'code'].includes(key),
-  );
-  const name = descriptors.name?.value;
-  const message = descriptors.message?.value;
-  const code = descriptors.code?.value;
-  if (
-    unsupportedKey
-    || descriptors.name?.get !== undefined
-    || descriptors.name?.set !== undefined
-    || descriptors.message?.get !== undefined
-    || descriptors.message?.set !== undefined
-    || descriptors.code?.get !== undefined
-    || descriptors.code?.set !== undefined
-    || typeof name !== 'string'
-    || !name
-    || Buffer.byteLength(name, 'utf8') > maxProjectedErrorNameBytes
-    || typeof message !== 'string'
-    || !message
-    || Buffer.byteLength(message, 'utf8') > maxProjectedErrorMessageBytes
-    || (code !== undefined
-      && (typeof code !== 'string'
-        || !code
-        || Buffer.byteLength(code, 'utf8') > maxProjectedErrorCodeBytes))
-  ) {
-    throw new FlexHarnessValidationError('External error projection is invalid.');
-  }
-  return Object.freeze({ name, message, ...(code === undefined ? {} : { code }) });
-}
-
-function normalizeModelIdentity(identity: IFlexModelIdentity): IFlexModelIdentity {
-  const normalized: IFlexModelIdentity = {
-    provider: identity.provider,
-    model: identity.model,
-    ...(identity.displayName === undefined ? {} : { displayName: identity.displayName }),
-    ...(identity.variant === undefined ? {} : { variant: identity.variant }),
-  };
-  validateIdentifier(normalized.provider, 'model identity provider');
-  validateIdentifier(normalized.model, 'model identity model');
-  if (normalized.displayName !== undefined) {
-    validateIdentifier(normalized.displayName, 'model identity displayName');
-  }
-  if (normalized.variant !== undefined) validateIdentifier(normalized.variant, 'model identity variant');
-  if (
-    Buffer.byteLength(normalized.provider, 'utf8') > maxTransferIdentifierBytes
-    || Buffer.byteLength(normalized.model, 'utf8') > maxTransferIdentifierBytes
-    || (normalized.displayName !== undefined
-      && Buffer.byteLength(normalized.displayName, 'utf8') > maxTransferMetadataBytes)
-    || (normalized.variant !== undefined && Buffer.byteLength(normalized.variant, 'utf8') > 128)
-  ) {
-    throw new FlexHarnessValidationError('Model identity exceeds its transfer limit.');
-  }
-  return normalized;
-}
-
-function normalizeResolvedModel(resolvedModel: IFlexResolvedModel): IFlexResolvedModel {
-  return {
-    model: resolvedModel.model,
-    identity: normalizeModelIdentity(resolvedModel.identity),
-    ...(resolvedModel.system === undefined ? {} : { system: resolvedModel.system }),
-    ...(resolvedModel.providerOptions === undefined
-      ? {}
-      : { providerOptions: resolvedModel.providerOptions }),
-    ...(resolvedModel.cache === undefined ? {} : { cache: resolvedModel.cache }),
-    ...(resolvedModel.maxSteps === undefined ? {} : { maxSteps: resolvedModel.maxSteps }),
-  };
-}
-
-function normalizeRunResult(result: TFlexAgentRunResult): IRunResultProjection {
-  const normalized: IRunResultProjection = {
-    text: result.text,
-    steps: result.steps,
-    finishReason: result.finishReason,
-    usage: {
-      inputTokens: result.usage.inputTokens,
-      outputTokens: result.usage.outputTokens,
-      totalTokens: result.usage.totalTokens,
-      cacheReadTokens: result.usage.cacheReadTokens,
-      cacheWriteTokens: result.usage.cacheWriteTokens,
-    },
-  };
-  if (
-    typeof normalized.text !== 'string'
-    || typeof normalized.finishReason !== 'string'
-    || !Number.isSafeInteger(normalized.steps)
-    || normalized.steps < 0
-    || Object.values(normalized.usage).some((value) => !Number.isFinite(value) || value < 0)
-  ) {
-    throw new FlexHarnessValidationError('Agent generation result is invalid.');
-  }
-  return normalized;
-}
-
 function combineErrors(errors: unknown[]): unknown {
   if (errors.length === 1) return errors[0];
   const combined = new FlexHarnessRunError(errors);
@@ -1047,321 +595,6 @@ function containsStoreCommitUncertainty(error: unknown, seen = new Set<unknown>(
   }
 }
 
-function base64Size(data: string): number | undefined {
-  const compact = data.replace(/\s/g, '');
-  if (!/^[A-Za-z0-9+/]*={0,2}$/.test(compact) || compact.length % 4 === 1) return undefined;
-  return Buffer.from(compact, 'base64').byteLength;
-}
-
-function describeAttachment(
-  part: Exclude<TFlexPromptPart, { type: 'text' }>,
-): Omit<IFlexAttachmentMessagePart, 'partId' | 'type' | 'attachmentType'> {
-  let source: TFlexAttachmentSource = 'inline-base64';
-  let sizeBytes: number | undefined;
-  let inferredMediaType: string | undefined;
-  if (/^data:/i.test(part.data)) {
-    source = 'data-url';
-    const commaIndex = part.data.indexOf(',');
-    if (commaIndex >= 0) {
-      const metadata = part.data.slice(5, commaIndex);
-      const payload = part.data.slice(commaIndex + 1);
-      const metadataParts = metadata.split(';');
-      if (metadataParts[0]?.includes('/')) inferredMediaType = metadataParts[0];
-      if (metadataParts.some((entry) => entry.toLowerCase() === 'base64')) {
-        sizeBytes = base64Size(payload);
-      } else {
-        try {
-          sizeBytes = Buffer.byteLength(decodeURIComponent(payload));
-        } catch {
-          // Malformed URL encoding leaves size unknown without exposing the payload.
-        }
-      }
-    }
-  } else {
-    try {
-      const url = new URL(part.data);
-      if (url.protocol === 'http:' || url.protocol === 'https:') source = 'remote-url';
-      else sizeBytes = base64Size(part.data);
-    } catch {
-      sizeBytes = base64Size(part.data);
-    }
-  }
-  return {
-    source,
-    ...(sizeBytes === undefined ? {} : { sizeBytes }),
-    ...(part.mediaType ?? inferredMediaType
-      ? { mediaType: part.mediaType ?? inferredMediaType }
-      : {}),
-    ...(part.name ? { name: part.name } : {}),
-  };
-}
-
-function createBoundedTransferMessage(message: IFlexMessage): IFlexMessage {
-  const projected = cloneSerializable(message);
-  requireTransferIdentifier(projected.messageId, 'messageId');
-  requireTransferIdentifier(projected.sessionId, 'sessionId');
-  requireTransferIdentifier(projected.runId, 'runId');
-  projected.createdAt = truncateUtf8(projected.createdAt, 128);
-  if (projected.completedAt !== undefined) projected.completedAt = truncateUtf8(projected.completedAt, 128);
-  if (projected.error !== undefined) projected.error = truncateUtf8(projected.error, maxTransferMetadataBytes);
-  if (projected.model) {
-    projected.model.provider = truncateUtf8(projected.model.provider, maxTransferIdentifierBytes);
-    projected.model.model = truncateUtf8(projected.model.model, maxTransferIdentifierBytes);
-    if (projected.model.displayName !== undefined) {
-      projected.model.displayName = truncateUtf8(projected.model.displayName, maxTransferMetadataBytes);
-    }
-    if (projected.model.variant !== undefined) projected.model.variant = truncateUtf8(projected.model.variant, 128);
-  }
-  for (const part of projected.parts) {
-    requireTransferIdentifier(part.partId, 'partId');
-    if (part.type === 'text' || part.type === 'reasoning') {
-      part.text = truncateUtf8(part.text, maxTransferTextBytes);
-    } else if (part.type === 'tool') {
-      part.toolCallId = truncateUtf8(part.toolCallId, maxTransferIdentifierBytes);
-      part.toolName = truncateUtf8(part.toolName, maxTransferIdentifierBytes);
-      if (part.error !== undefined) part.error = truncateUtf8(part.error, maxTransferMetadataBytes);
-    } else {
-      if (part.mediaType !== undefined) part.mediaType = truncateUtf8(part.mediaType, maxTransferIdentifierBytes);
-      if (part.name !== undefined) part.name = truncateUtf8(part.name, maxTransferMetadataBytes);
-    }
-  }
-  if (jsonBytes(projected) > maxTransferMessageBytes) {
-    projected.parts = [{
-      partId: 'transfer-elided',
-      type: 'text',
-      text: '[elided: message exceeds the transfer budget]',
-    }];
-  }
-  if (jsonBytes(projected) > maxTransferMessageBytes) {
-    throw new FlexHarnessValidationError('Stored message metadata exceeds the transfer limit.');
-  }
-  return projected;
-}
-
-function validateUpdateSessionOptions(options: IFlexUpdateSessionOptions): void {
-  if (!options || typeof options !== 'object' || Array.isArray(options)) {
-    throw new FlexHarnessValidationError('updateSession options must be a plain object.');
-  }
-  const keys = Object.keys(options);
-  if (keys.length === 0) throw new FlexHarnessValidationError('updateSession requires title or archived.');
-  const unsupportedKey = keys.find((key) => key !== 'title' && key !== 'archived');
-  if (unsupportedKey) throw new FlexHarnessValidationError(`updateSession does not support "${unsupportedKey}".`);
-  if (Object.prototype.hasOwnProperty.call(options, 'title') && options.title !== null) {
-    validateUtf8String(
-      options.title,
-      'title',
-      FLEX_PROJECT_MANAGEMENT_LIMITS.maxTitleBytes,
-      true,
-    );
-  }
-  if (Object.prototype.hasOwnProperty.call(options, 'archived') && typeof options.archived !== 'boolean') {
-    throw new FlexHarnessValidationError('archived must be a boolean.');
-  }
-}
-
-function validateProjectTaskStatus(value: unknown): asserts value is TFlexProjectTaskStatus {
-  if (!['pending', 'in_progress', 'completed', 'cancelled'].includes(String(value))) {
-    throw new FlexHarnessValidationError('Project task status is invalid.');
-  }
-}
-
-function validateProjectTaskPriority(value: unknown): asserts value is TFlexProjectTaskPriority {
-  if (!['high', 'medium', 'low'].includes(String(value))) {
-    throw new FlexHarnessValidationError('Project task priority is invalid.');
-  }
-}
-
-function validateProjectTaskId(value: unknown): asserts value is string {
-  validateUtf8String(
-    value,
-    'project task id',
-    FLEX_PROJECT_MANAGEMENT_LIMITS.maxTaskIdBytes,
-    true,
-  );
-}
-
-function validateProjectTaskContent(value: unknown): asserts value is string {
-  validateUtf8String(
-    value,
-    'project task content',
-    FLEX_PROJECT_MANAGEMENT_LIMITS.maxTaskContentBytes,
-    true,
-  );
-}
-
-function validateCreateProjectTaskInput(input: IFlexCreateProjectTaskInput): void {
-  if (!input || typeof input !== 'object' || Array.isArray(input)) {
-    throw new FlexHarnessValidationError('Project task create input must be a plain object.');
-  }
-  const unsupported = Object.keys(input)
-    .find((key) => !['id', 'content', 'status', 'priority'].includes(key));
-  if (unsupported) {
-    throw new FlexHarnessValidationError(`Project task create input does not support "${unsupported}".`);
-  }
-  validateProjectTaskId(input.id);
-  validateProjectTaskContent(input.content);
-  if (input.status !== undefined) validateProjectTaskStatus(input.status);
-  if (input.priority !== undefined) validateProjectTaskPriority(input.priority);
-}
-
-function validateUpdateProjectTaskInput(input: IFlexUpdateProjectTaskInput): void {
-  if (!input || typeof input !== 'object' || Array.isArray(input)) {
-    throw new FlexHarnessValidationError('Project task update input must be a plain object.');
-  }
-  const keys = Object.keys(input);
-  const unsupported = keys.find((key) => !['id', 'content', 'status', 'priority'].includes(key));
-  if (unsupported) {
-    throw new FlexHarnessValidationError(`Project task update input does not support "${unsupported}".`);
-  }
-  if (!keys.some((key) => key !== 'id')) {
-    throw new FlexHarnessValidationError('Project task update requires a changed field.');
-  }
-  validateProjectTaskId(input.id);
-  if (input.content !== undefined) validateProjectTaskContent(input.content);
-  if (input.status !== undefined) validateProjectTaskStatus(input.status);
-  if (input.priority !== undefined) validateProjectTaskPriority(input.priority);
-}
-
-function validatePromptOptions(options: IFlexPromptOptions, scheduled: boolean): void {
-  if (!options || typeof options !== 'object' || Array.isArray(options)) {
-    throw new FlexHarnessValidationError('Prompt options must be a plain object.');
-  }
-  const supported = scheduled
-    ? ['modelHint', 'system', 'maxSteps', 'debounceMs']
-    : ['modelHint', 'system', 'maxSteps'];
-  const unsupported = Object.keys(options).find((key) => !supported.includes(key));
-  if (unsupported) throw new FlexHarnessValidationError(`Prompt options do not support "${unsupported}".`);
-  if (options.modelHint !== undefined) validateIdentifier(options.modelHint, 'modelHint');
-  if (options.system !== undefined) validateIdentifier(options.system, 'system');
-  if (options.maxSteps !== undefined && (!Number.isSafeInteger(options.maxSteps) || options.maxSteps < 1)) {
-    throw new FlexHarnessValidationError('maxSteps must be a positive integer.');
-  }
-}
-
-function validateSlashCommandExecutionOptions(
-  options: IFlexSlashCommandExecutionOptions,
-): IFlexPromptOptions {
-  if (!options || typeof options !== 'object' || Array.isArray(options)) {
-    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));
-  if (unsupported) {
-    throw new FlexHarnessValidationError(
-      `Slash command execution options do not support "${unsupported}".`,
-    );
-  }
-  if (options.signal !== undefined && !(options.signal instanceof AbortSignal)) {
-    throw new FlexHarnessValidationError('Slash command signal must be an AbortSignal.');
-  }
-  const promptOptions: IFlexPromptOptions = {
-    ...(options.modelHint === undefined ? {} : { modelHint: options.modelHint }),
-    ...(options.system === undefined ? {} : { system: options.system }),
-    ...(options.maxSteps === undefined ? {} : { maxSteps: options.maxSteps }),
-  };
-  validatePromptOptions(promptOptions, false);
-  return promptOptions;
-}
-
-function resolveCallbackLimits(limits: IFlexCallbackLimits = {}): Required<IFlexCallbackLimits> {
-  const resolved = {
-    maxEvents: limits.maxEvents ?? DEFAULT_CALLBACK_LIMITS.maxEvents,
-    maxOutputBytes: limits.maxOutputBytes ?? DEFAULT_CALLBACK_LIMITS.maxOutputBytes,
-    maxParts: limits.maxParts ?? DEFAULT_CALLBACK_LIMITS.maxParts,
-  };
-  for (const [name, value] of Object.entries(resolved)) {
-    if (!Number.isSafeInteger(value) || value < 1) {
-      throw new FlexHarnessValidationError(`callbackLimits.${name} must be a positive integer.`);
-    }
-  }
-  return resolved;
-}
-
-function resolvePromptQueueLimits(
-  limits: IFlexPromptQueueLimits = {},
-): Required<IFlexPromptQueueLimits> {
-  const resolved = {
-    maxOutstandingPromptsPerSession: limits.maxOutstandingPromptsPerSession
-      ?? DEFAULT_PROMPT_QUEUE_LIMITS.maxOutstandingPromptsPerSession,
-    maxOutstandingBytesPerSession: limits.maxOutstandingBytesPerSession
-      ?? DEFAULT_PROMPT_QUEUE_LIMITS.maxOutstandingBytesPerSession,
-    maxPendingAdmissions: limits.maxPendingAdmissions
-      ?? DEFAULT_PROMPT_QUEUE_LIMITS.maxPendingAdmissions,
-    maxPendingAdmissionBytes: limits.maxPendingAdmissionBytes
-      ?? DEFAULT_PROMPT_QUEUE_LIMITS.maxPendingAdmissionBytes,
-    maxTerminalEntriesPerSession: limits.maxTerminalEntriesPerSession
-      ?? DEFAULT_PROMPT_QUEUE_LIMITS.maxTerminalEntriesPerSession,
-  };
-  for (const [name, value] of Object.entries(resolved)) {
-    if (!Number.isSafeInteger(value) || value < 1) {
-      throw new FlexHarnessValidationError(`promptQueueLimits.${name} must be a positive integer.`);
-    }
-  }
-  return resolved;
-}
-
-function resolveReversionLimits(
-  limits: IFlexReversionLimits = {},
-): Required<IFlexReversionLimits> {
-  const resolved = {
-    maxCompletedTurns: limits.maxCompletedTurns ?? FLEX_REVERSION_DEFAULT_LIMITS.maxCompletedTurns,
-    maxSegments: limits.maxSegments ?? FLEX_REVERSION_DEFAULT_LIMITS.maxSegments,
-    maxExcludedRunIds: limits.maxExcludedRunIds ?? FLEX_REVERSION_DEFAULT_LIMITS.maxExcludedRunIds,
-    maxPendingReversionReleases: limits.maxPendingReversionReleases
-      ?? FLEX_REVERSION_DEFAULT_LIMITS.maxPendingReversionReleases,
-  };
-  for (const [name, value] of Object.entries(resolved)) {
-    const maximum = FLEX_REVERSION_MAXIMUM_LIMITS[name as keyof IFlexReversionLimits];
-    if (!Number.isSafeInteger(value) || value < 1 || value > maximum) {
-      throw new FlexHarnessValidationError(
-        `reversionLimits.${name} must be an integer from 1 through ${maximum}.`,
-      );
-    }
-  }
-  return resolved;
-}
-
-function normalizeAgentSessionPolicy<TScope>(
-  policy: IFlexAgentSessionPolicy<TScope> = {},
-): IFlexAgentSessionPolicy<TScope> {
-  return {
-    ...(policy.contextBuilder === undefined ? {} : { contextBuilder: policy.contextBuilder }),
-    ...(policy.contextCompactor === undefined ? {} : { contextCompactor: policy.contextCompactor }),
-    ...(policy.eventRetention === undefined ? {} : { eventRetention: policy.eventRetention }),
-    ...(policy.changeListenerTimeoutMs === undefined
-      ? {}
-      : { changeListenerTimeoutMs: policy.changeListenerTimeoutMs }),
-    ...(policy.maxPendingSessionChanges === undefined
-      ? {}
-      : { maxPendingSessionChanges: policy.maxPendingSessionChanges }),
-    ...(policy.generationLeaseCleanupTimeoutMs === undefined
-      ? {}
-      : { generationLeaseCleanupTimeoutMs: policy.generationLeaseCleanupTimeoutMs }),
-    ...(policy.maxArchivedTransactionTombstones === undefined
-      ? {}
-      : { maxArchivedTransactionTombstones: policy.maxArchivedTransactionTombstones }),
-    ...(policy.maxContextOverflowRetries === undefined
-      ? {}
-      : { maxContextOverflowRetries: policy.maxContextOverflowRetries }),
-  };
-}
-
-function requireHarnessStores(stores: IFlexHarnessStores): IFlexHarnessStores {
-  const projectManagement = stores?.projectManagement;
-  if (
-    !projectManagement
-    || typeof projectManagement.load !== 'function'
-    || typeof projectManagement.save !== 'function'
-    || typeof projectManagement.tombstoneSession !== 'function'
-    || typeof projectManagement.purgeNamespace !== 'function'
-  ) {
-    throw new FlexHarnessValidationError(
-      'stores.projectManagement requires load/save/tombstoneSession/purgeNamespace methods.',
-    );
-  }
-  return stores;
-}
-
 export class FlexHarness<TScope = unknown> {
   private readonly scopeResolver: IFlexHarnessOptions<TScope>['scopeResolver'];
   private readonly modelResolver: IFlexHarnessOptions<TScope>['modelResolver'];
@@ -2253,7 +1486,7 @@ export class FlexHarness<TScope = unknown> {
     const parsed = parseSlashCommand(untouchedInput);
     if (parsed.type !== 'parsed') return parsed;
     const registration = this.slashCommands.get(parsed.name);
-    if (!reservedSlashCommandNames.has(parsed.name) && !registration) {
+    if (!isReservedSlashCommandName(parsed.name) && !registration) {
       return Object.freeze({
         type: 'unknown',
         input: parsed.input,
@@ -5667,6 +4900,7 @@ export class FlexHarness<TScope = unknown> {
         part.status = status === 'completed' ? 'completed' : 'cancelled';
       } else if (part.type === 'tool' && part.status === 'running') {
         part.status = status === 'cancelled' ? 'cancelled' : 'failed';
+        delete part.output;
         part.error = status === 'cancelled'
           ? 'Tool execution was cancelled.'
           : 'Tool execution ended without a terminal event.';
@@ -6928,6 +6162,7 @@ export class FlexHarness<TScope = unknown> {
         part.output = output!;
       } else {
         part.status = 'failed';
+        delete part.output;
         part.error = projectedError!.message;
       }
       this.emitPartEvent(run, 'part.completed', part);
@@ -6936,6 +6171,31 @@ export class FlexHarness<TScope = unknown> {
     }
   }
 
+  private onToolUpdate(
+    state: IStorageState,
+    sessionId: string,
+    event: TFlexAgentToolCallUpdateEvent,
+  ): void {
+    let run = this.callbackRun(state, sessionId);
+    if (!run) return;
+    if (!run.toolPartIds.has(event.toolCallId)) {
+      this.onToolStart(state, sessionId, event);
+      run = this.callbackRun(state, sessionId);
+      if (!run) return;
+    }
+    const partId = run.toolPartIds.get(event.toolCallId);
+    const part = run.callbackParts.find((entry) => entry.partId === partId && entry.type === 'tool');
+    if (!part || part.type !== 'tool' || part.status !== 'running') return;
+    try {
+      const output = normalizeJsonValue(event.output, this.toolOutputLimits);
+      if (!this.reserveCallbackCapacity(run, 1, jsonBytes(output), 0)) return;
+      part.output = output;
+      this.emitPartEvent(run, 'part.updated', part);
+    } catch (error) {
+      this.failCallback(run, this.projectExternalError(run, error, 'toolCallback'));
+    }
+  }
+
   private callbackRun(state: IStorageState, sessionId: string): IActiveRun | undefined {
     const run = state.activeRuns.get(sessionId);
     return !run || run.callbacksClosed || run.callbackError ? undefined : run;
@@ -8100,6 +7360,7 @@ export class FlexHarness<TScope = unknown> {
         onReasoningDelta: (id, delta) => this.onReasoningDelta(state, sessionId, id, delta),
         onReasoningEnd: (id, text) => this.onReasoningEnd(state, sessionId, id, text),
         onToolCallStart: (event) => this.onToolStart(state, sessionId, event),
+        onToolCallUpdate: (event) => this.onToolUpdate(state, sessionId, event),
         onToolCallFinish: (event) => this.onToolFinish(state, sessionId, event),
       };
       stored.agentSession = await this.withCompactorContext(