@modelprofile.com/flexharness 3.6.0 → 3.7.0

package/ts/utils.json.ts

@@ -1,8 +1,13 @@
 import { FlexHarnessStoreFormatError, FlexHarnessValidationError } from './errors.js';
+import {
+  FLEX_REVERSION_MAXIMUM_LIMITS,
+  FLEX_REVERSION_REFERENCE_MAX_BYTES,
+} from './interfaces.js';
 import type {
   IFlexJsonLimits,
   IFlexPermissionSnapshot,
-  IFlexProjectionSnapshot,
+  IFlexProjectionSnapshotV1,
+  IFlexProjectionSnapshotV2,
   IFlexScopeSnapshot,
   TFlexAgentModelMessage,
   TJsonValue,
@@ -390,8 +395,8 @@ function requireString(value: unknown, path: string): string {
   return value;
 }
 
-function requireOptionalString(value: unknown, path: string): void {
-  if (value !== undefined) requireString(value, path);
+function requireOptionalString(value: unknown, path: string): string | undefined {
+  return value === undefined ? undefined : requireString(value, path);
 }
 
 function requireNonNegativeNumber(value: unknown, path: string): void {
@@ -873,15 +878,12 @@ export function assertFlexScopeSnapshot(value: unknown): asserts value is IFlexS
   }
 }
 
-export function assertFlexProjectionSnapshot(
-  value: unknown,
-): asserts value is IFlexProjectionSnapshot {
-  const snapshot = validateSnapshotHeader(value, [
-    'schemaVersion',
-    'revision',
-    'messages',
-    'stagedTerminals',
-  ]);
+interface IValidatedProjectionBody {
+  messages: IValidatedMessageIdentity[];
+  stagedUsers: IValidatedMessageIdentity[];
+}
+
+function validateProjectionBody(snapshot: Record<string, unknown>): IValidatedProjectionBody {
   const visibleMessages = validateMessages(snapshot.messages, '$snapshot.messages');
   let projectionSessionId = visibleMessages[0]?.sessionId;
   if (visibleMessages.some((message) => message.sessionId !== projectionSessionId)) {
@@ -892,6 +894,7 @@ export function assertFlexProjectionSnapshot(
   }
   const runIds = new Set<string>();
   const stagedMessageIds = new Set<string>();
+  const stagedUsers: IValidatedMessageIdentity[] = [];
   for (let index = 0; index < snapshot.stagedTerminals.length; index++) {
     const path = `$snapshot.stagedTerminals[${index}]`;
     const terminal = requireRecord(snapshot.stagedTerminals[index], path);
@@ -928,6 +931,10 @@ export function assertFlexProjectionSnapshot(
     if (assistant.status !== terminal.status) {
       throw new FlexHarnessStoreFormatError(`${path}.status does not match its assistant message.`);
     }
+    if (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) {
       throw new FlexHarnessStoreFormatError(`${path} belongs to another session.`);
@@ -945,6 +952,271 @@ export function assertFlexProjectionSnapshot(
     requireOptionalString(terminal.finishReason, `${path}.finishReason`);
     if (terminal.steps !== undefined) requireNonNegativeInteger(terminal.steps, `${path}.steps`);
   }
+  return { messages: visibleMessages, stagedUsers };
+}
+
+export function assertFlexProjectionSnapshotV1(
+  value: unknown,
+): asserts value is IFlexProjectionSnapshotV1 {
+  const snapshot = validateSnapshotHeader(value, [
+    'schemaVersion',
+    'revision',
+    'messages',
+    'stagedTerminals',
+  ]);
+  validateProjectionBody(snapshot);
+}
+
+export function assertFlexProjectionSnapshotV2(
+  value: unknown,
+): asserts value is IFlexProjectionSnapshotV2 {
+  assertJsonSerializable(value, '$snapshot');
+  const snapshot = requireRecord(value, '$snapshot');
+  requireOnlyKeys(snapshot, [
+    'schemaVersion',
+    'revision',
+    'messages',
+    'stagedTerminals',
+    'reversionSegments',
+    'revertCursor',
+    'excludedRunIds',
+    'pendingReversion',
+    'pendingReversionReleases',
+  ], '$snapshot');
+  if (snapshot.schemaVersion !== 2) {
+    throw new FlexHarnessStoreFormatError('Projection snapshot schemaVersion must be 2.');
+  }
+  requireNonNegativeInteger(snapshot.revision, 'Snapshot revision');
+  const projectionBody = validateProjectionBody(snapshot);
+  const segments = Array.isArray(snapshot.reversionSegments)
+    ? snapshot.reversionSegments
+    : (() => { throw new FlexHarnessStoreFormatError('Snapshot reversionSegments must be an array.'); })();
+  if (segments.length > FLEX_REVERSION_MAXIMUM_LIMITS.maxSegments) {
+    throw new FlexHarnessStoreFormatError('Snapshot reversionSegments exceeds its hard limit.');
+  }
+  const segmentRunIds = new Set<string>();
+  const segmentCaptureIds = new Set<string>();
+  const segmentEventIds = new Set<string>();
+  const capturingWorkspaceSegments = new Map<string, string>();
+  for (let index = 0; index < segments.length; index++) {
+    const path = `$snapshot.reversionSegments[${index}]`;
+    const segment = requireRecord(segments[index], path);
+    requireOnlyKeys(segment, [
+      'runId',
+      'userMessageId',
+      'status',
+      'contextAvailable',
+      'eventIds',
+      'workspaceCaptured',
+      'captureId',
+      'workspaceReference',
+    ], path);
+    const runId = requireString(segment.runId, `${path}.runId`);
+    const userMessageId = requireString(segment.userMessageId, `${path}.userMessageId`);
+    if (segmentRunIds.has(runId)) {
+      throw new FlexHarnessStoreFormatError(`Snapshot contains duplicate reversion run "${runId}".`);
+    }
+    segmentRunIds.add(runId);
+    if (!['capturing', 'completed', 'failed', 'cancelled'].includes(String(segment.status))) {
+      throw new FlexHarnessStoreFormatError(`${path}.status is invalid.`);
+    }
+    if (typeof segment.contextAvailable !== 'boolean') {
+      throw new FlexHarnessStoreFormatError(`${path}.contextAvailable must be a boolean.`);
+    }
+    const eventIds = requireStringArray(segment.eventIds, `${path}.eventIds`);
+    if (eventIds.some((id) => !id) || new Set(eventIds).size !== eventIds.length) {
+      throw new FlexHarnessStoreFormatError(`${path}.eventIds is invalid.`);
+    }
+    for (const eventId of eventIds) {
+      if (segmentEventIds.has(eventId)) {
+        throw new FlexHarnessStoreFormatError(`Snapshot reuses reversion event "${eventId}".`);
+      }
+      segmentEventIds.add(eventId);
+    }
+    if (typeof segment.workspaceCaptured !== 'boolean') {
+      throw new FlexHarnessStoreFormatError(`${path}.workspaceCaptured must be a boolean.`);
+    }
+    const captureId = requireOptionalString(segment.captureId, `${path}.captureId`);
+    if (segment.workspaceCaptured && captureId === undefined) {
+      throw new FlexHarnessStoreFormatError(`${path} is capture-backed without a capture ID.`);
+    }
+    if (captureId !== undefined) {
+      if (segmentCaptureIds.has(captureId)) {
+        throw new FlexHarnessStoreFormatError(`Snapshot contains duplicate capture "${captureId}".`);
+      }
+      segmentCaptureIds.add(captureId);
+      if (segment.status === 'capturing') capturingWorkspaceSegments.set(runId, captureId);
+    }
+    if (!segment.workspaceCaptured && (captureId !== undefined || segment.workspaceReference !== undefined)) {
+      throw new FlexHarnessStoreFormatError(`${path} is transcript-only but contains workspace capture data.`);
+    }
+    if (
+      segment.workspaceCaptured
+      && segment.status !== 'capturing'
+      && segment.workspaceReference === undefined
+    ) {
+      throw new FlexHarnessStoreFormatError(`${path} is terminal but has no workspace reference.`);
+    }
+    if (segment.status === 'capturing' && segment.workspaceReference !== undefined) {
+      throw new FlexHarnessStoreFormatError(`${path} is capturing but already has a workspace reference.`);
+    }
+    if (segment.workspaceReference !== undefined) {
+      if (captureId === undefined) {
+        throw new FlexHarnessStoreFormatError(`${path} has a workspace reference without a capture ID.`);
+      }
+      if (Buffer.byteLength(JSON.stringify(segment.workspaceReference)) > FLEX_REVERSION_REFERENCE_MAX_BYTES) {
+        throw new FlexHarnessStoreFormatError(`${path}.workspaceReference exceeds its byte limit.`);
+      }
+    }
+    const correlatedUsers = new Set([...projectionBody.messages, ...projectionBody.stagedUsers]
+      .filter((message) =>
+        message.role === 'user' && message.runId === runId && 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.`);
+    }
+  }
+  requireNonNegativeInteger(snapshot.revertCursor, '$snapshot.revertCursor');
+  const candidateCount = segments.filter((segment) => {
+    const record = segment as Record<string, unknown>;
+    return record.status === 'completed';
+  }).length;
+  if (candidateCount > FLEX_REVERSION_MAXIMUM_LIMITS.maxCompletedTurns) {
+    throw new FlexHarnessStoreFormatError('Snapshot completed reversion turns exceed their hard limit.');
+  }
+  if (Number(snapshot.revertCursor) > candidateCount) {
+    throw new FlexHarnessStoreFormatError('Snapshot revertCursor exceeds its candidate count.');
+  }
+  const excludedRunIds = requireStringArray(snapshot.excludedRunIds, '$snapshot.excludedRunIds');
+  if (
+    excludedRunIds.some((id) => !id)
+    || new Set(excludedRunIds).size !== excludedRunIds.length
+  ) throw new FlexHarnessStoreFormatError('Snapshot excludedRunIds is invalid.');
+  if (excludedRunIds.length > FLEX_REVERSION_MAXIMUM_LIMITS.maxExcludedRunIds) {
+    throw new FlexHarnessStoreFormatError('Snapshot excludedRunIds exceeds its hard limit.');
+  }
+  if (snapshot.pendingReversion !== undefined) {
+    const pending = requireRecord(snapshot.pendingReversion, '$snapshot.pendingReversion');
+    if (pending.kind === 'capture') {
+      requireOnlyKeys(pending, ['kind', 'runId', 'captureId', 'state'], '$snapshot.pendingReversion');
+      const pendingRunId = requireString(pending.runId, '$snapshot.pendingReversion.runId');
+      const pendingCaptureId = requireString(pending.captureId, '$snapshot.pendingReversion.captureId');
+      if (!['preparing', 'prepared', 'finalizing'].includes(String(pending.state))) {
+        throw new FlexHarnessStoreFormatError('Snapshot pending capture state is invalid.');
+      }
+      const matches = segments.filter((segment) => {
+        const record = segment as Record<string, unknown>;
+        return record.runId === pendingRunId
+          && record.captureId === pendingCaptureId
+          && record.workspaceCaptured === true
+          && record.status === 'capturing';
+      });
+      if (matches.length !== 1) {
+        throw new FlexHarnessStoreFormatError('Snapshot pending capture does not match exactly one segment.');
+      }
+      capturingWorkspaceSegments.delete(pendingRunId);
+    } else if (pending.kind === 'apply') {
+      requireOnlyKeys(pending, [
+        'kind',
+        'operationId',
+        'direction',
+        'fromCursor',
+        'toCursor',
+        'segmentRunIds',
+        'appliedRunIds',
+      ], '$snapshot.pendingReversion');
+      requireString(pending.operationId, '$snapshot.pendingReversion.operationId');
+      if (!['undo', 'redo'].includes(String(pending.direction))) {
+        throw new FlexHarnessStoreFormatError('Snapshot pending apply direction is invalid.');
+      }
+      requireNonNegativeInteger(pending.fromCursor, '$snapshot.pendingReversion.fromCursor');
+      requireNonNegativeInteger(pending.toCursor, '$snapshot.pendingReversion.toCursor');
+      const pendingRuns = requireStringArray(
+        pending.segmentRunIds,
+        '$snapshot.pendingReversion.segmentRunIds',
+      );
+      const appliedRuns = requireStringArray(
+        pending.appliedRunIds,
+        '$snapshot.pendingReversion.appliedRunIds',
+      );
+      if (new Set(pendingRuns).size !== pendingRuns.length || new Set(appliedRuns).size !== appliedRuns.length) {
+        throw new FlexHarnessStoreFormatError('Snapshot pending apply run IDs are invalid.');
+      }
+      if (appliedRuns.some((runId) => !pendingRuns.includes(runId))) {
+        throw new FlexHarnessStoreFormatError('Snapshot pending apply progress is invalid.');
+      }
+      const fromCursor = Number(pending.fromCursor);
+      const toCursor = Number(pending.toCursor);
+      const direction = pending.direction as 'undo' | 'redo';
+      if (fromCursor !== Number(snapshot.revertCursor) || toCursor !== fromCursor + (direction === 'undo' ? -1 : 1)) {
+        throw new FlexHarnessStoreFormatError('Snapshot pending apply cursor movement is invalid.');
+      }
+      const completed = segments.filter((segment) =>
+        (segment as Record<string, unknown>).status === 'completed');
+      const target = direction === 'undo' ? completed[fromCursor - 1] : completed[fromCursor];
+      if (!target) throw new FlexHarnessStoreFormatError('Snapshot pending apply has no target candidate.');
+      const targetRunId = (target as Record<string, unknown>).runId;
+      const targetIndex = segments.findIndex((segment) =>
+        (segment as Record<string, unknown>).runId === targetRunId);
+      const start = target === completed[0] ? 0 : targetIndex;
+      const next = completed[direction === 'undo' ? fromCursor : fromCursor + 1];
+      const end = next
+        ? segments.findIndex((segment) =>
+            (segment as Record<string, unknown>).runId === (next as Record<string, unknown>).runId)
+        : segments.length;
+      const exactRuns = segments.slice(start, end).map((segment) =>
+        String((segment as Record<string, unknown>).runId));
+      if (JSON.stringify(pendingRuns) !== JSON.stringify(exactRuns)) {
+        throw new FlexHarnessStoreFormatError('Snapshot pending apply segment unit is invalid.');
+      }
+      const applyOrder = direction === 'undo' ? [...exactRuns].reverse() : exactRuns;
+      if (JSON.stringify(appliedRuns) !== JSON.stringify(applyOrder.slice(0, appliedRuns.length))) {
+        throw new FlexHarnessStoreFormatError('Snapshot pending apply progress is out of order.');
+      }
+    } else {
+      throw new FlexHarnessStoreFormatError('Snapshot pendingReversion kind is invalid.');
+    }
+  }
+  if (capturingWorkspaceSegments.size > 0) {
+    throw new FlexHarnessStoreFormatError(
+      'Snapshot contains a capture-backed capturing segment without exact pending ownership.',
+    );
+  }
+  if (!Array.isArray(snapshot.pendingReversionReleases)) {
+    throw new FlexHarnessStoreFormatError('Snapshot pendingReversionReleases must be an array.');
+  }
+  if (
+    snapshot.pendingReversionReleases.length
+    > FLEX_REVERSION_MAXIMUM_LIMITS.maxPendingReversionReleases
+  ) {
+    throw new FlexHarnessStoreFormatError('Snapshot pending reversion releases exceed their hard limit.');
+  }
+  const releaseCaptureIds = new Set<string>();
+  for (let index = 0; index < snapshot.pendingReversionReleases.length; index++) {
+    const path = `$snapshot.pendingReversionReleases[${index}]`;
+    const release = requireRecord(snapshot.pendingReversionReleases[index], path);
+    requireOnlyKeys(release, ['runId', 'captureId', 'reference'], path);
+    requireString(release.runId, `${path}.runId`);
+    const captureId = requireString(release.captureId, `${path}.captureId`);
+    if (releaseCaptureIds.has(captureId)) {
+      throw new FlexHarnessStoreFormatError(`Snapshot contains duplicate release capture "${captureId}".`);
+    }
+    releaseCaptureIds.add(captureId);
+    if (!Object.prototype.hasOwnProperty.call(release, 'reference')) {
+      throw new FlexHarnessStoreFormatError(`${path}.reference is required.`);
+    }
+    if (Buffer.byteLength(JSON.stringify(release.reference)) > FLEX_REVERSION_REFERENCE_MAX_BYTES) {
+      throw new FlexHarnessStoreFormatError(`${path}.reference exceeds its byte limit.`);
+    }
+  }
+}
+
+export function assertFlexProjectionSnapshot(
+  value: unknown,
+): asserts value is IFlexProjectionSnapshotV1 | IFlexProjectionSnapshotV2 {
+  const record = requireRecord(value, '$snapshot');
+  if (record.schemaVersion === 1) assertFlexProjectionSnapshotV1(value);
+  else assertFlexProjectionSnapshotV2(value);
 }
 
 export function assertFlexPermissionSnapshot(

package/ts/utils.slashcommands.ts

@@ -0,0 +1,178 @@
+import { FlexHarnessValidationError } from './errors.js';
+import type {
+  IFlexParsedSlashCommand,
+  TFlexSlashCommandParseResult,
+} from './interfaces.js';
+
+export const FLEX_SLASH_COMMAND_MAX_INPUT_BYTES = 768 * 1024;
+
+const slashCommandNamePattern = /^[a-z][a-z0-9-]{0,63}$/u;
+const slashCommandPattern = /^\/([a-z][a-z0-9-]{0,63})(?:$|(\s+)([\s\S]*))$/u;
+const slashCommandArgumentsPattern = /(?:\[Image\s+\d+\]|"[^"]*"|'[^']*'|[^\s"']+)/gi;
+const slashCommandQuoteTrimPattern = /^["']|["']$/g;
+const slashCommandPlaceholderPattern = /\$(\d+)/g;
+const slashCommandAllPlaceholderPattern = /\$ARGUMENTS|\$(\d+)/g;
+
+export const FLEX_SLASH_COMMAND_INITIALIZE_TEMPLATE = `Create or update \`AGENTS.md\` for this repository.
+
+The goal is a compact instruction file that helps future OpenCode sessions avoid mistakes and ramp up quickly. Every line should answer: "Would an agent likely miss this without help?" If not, leave it out.
+
+User-provided focus or constraints (honor these):
+$ARGUMENTS
+
+## How to investigate
+
+Read the highest-value sources first:
+- \`README*\`, root manifests, workspace config, lockfiles
+- build, test, lint, formatter, typecheck, and codegen config
+- CI workflows and pre-commit / task runner config
+- existing instruction files (\`AGENTS.md\`, \`CLAUDE.md\`, \`.cursor/rules/\`, \`.cursorrules\`, \`.github/copilot-instructions.md\`)
+- repo-local OpenCode config such as \`opencode.json\`
+
+If architecture is still unclear after reading config and docs, inspect a small number of representative code files to find the real entrypoints, package boundaries, and execution flow. Prefer reading the files that explain how the system is wired together over random leaf files.
+
+Prefer executable sources of truth over prose. If docs conflict with config or scripts, trust the executable source and only keep what you can verify.
+
+## What to extract
+
+Look for the highest-signal facts for an agent working in this repo:
+- exact developer commands, especially non-obvious ones
+- how to run a single test, a single package, or a focused verification step
+- required command order when it matters, such as \`lint -> typecheck -> test\`
+- monorepo or multi-package boundaries, ownership of major directories, and the real app/library entrypoints
+- framework or toolchain quirks: generated code, migrations, codegen, build artifacts, special env loading, dev servers, infra deploy flow
+- repo-specific style or workflow conventions that differ from defaults
+- testing quirks: fixtures, integration test prerequisites, snapshot workflows, required services, flaky or expensive suites
+- important constraints from existing instruction files worth preserving
+
+Good \`AGENTS.md\` content is usually hard-earned context that took reading multiple files to infer.
+
+## Questions
+
+Only ask the user questions if the repo cannot answer something important. Use the \`question\` tool for one short batch at most.
+
+Good questions:
+- undocumented team conventions
+- branch / PR / release expectations
+- missing setup or test prerequisites that are known but not written down
+
+Do not ask about anything the repo already makes clear.
+
+## Writing rules
+
+Include only high-signal, repo-specific guidance such as:
+- exact commands and shortcuts the agent would otherwise guess wrong
+- architecture notes that are not obvious from filenames
+- conventions that differ from language or framework defaults
+- setup requirements, environment quirks, and operational gotchas
+- references to existing instruction sources that matter
+
+Exclude:
+- generic software advice
+- long tutorials or exhaustive file trees
+- obvious language conventions
+- speculative claims or anything you could not verify
+- content better stored in another file referenced via \`opencode.json\` \`instructions\`
+
+When in doubt, omit.
+
+Prefer short sections and bullets. If the repo is simple, keep the file simple. If the repo is large, summarize the few structural facts that actually change how an agent should work.
+
+If \`AGENTS.md\` already exists in the active workspace, improve it in place rather than rewriting blindly. Preserve verified useful guidance, delete fluff or stale claims, and reconcile it with the current codebase.
+`;
+
+export function isValidSlashCommandName(name: string): boolean {
+  return slashCommandNamePattern.test(name);
+}
+
+function tokenizeSlashCommandArguments(rawArguments: string): string[] {
+  const tokens = rawArguments.match(slashCommandArgumentsPattern) ?? [];
+  return tokens.map((token) => token.replace(slashCommandQuoteTrimPattern, ''));
+}
+
+export function parseSlashCommand(input: string): TFlexSlashCommandParseResult {
+  if (typeof input !== 'string') {
+    throw new FlexHarnessValidationError('Slash command input must be a string.');
+  }
+  if (!input.startsWith('/')) return Object.freeze({ type: 'not-command' });
+  if (Buffer.byteLength(input, 'utf8') > FLEX_SLASH_COMMAND_MAX_INPUT_BYTES) {
+    return Object.freeze({
+      type: 'malformed',
+      reason: `Slash command input exceeds ${FLEX_SLASH_COMMAND_MAX_INPUT_BYTES} UTF-8 bytes.`,
+    });
+  }
+  const match = slashCommandPattern.exec(input);
+  if (!match) {
+    return Object.freeze({
+      type: 'malformed',
+      reason: 'Slash command syntax is invalid.',
+    });
+  }
+  const arguments_ = tokenizeSlashCommandArguments(match[3] ?? '');
+  Object.freeze(arguments_);
+  return Object.freeze({
+    type: 'parsed',
+    input,
+    name: match[1],
+    rawArguments: match[3] ?? '',
+    arguments: arguments_,
+  } satisfies IFlexParsedSlashCommand);
+}
+
+export function slashCommandTemplateHints(template: string): string[] {
+  const hints = [...new Set(template.match(/\$\d+/g) ?? [])].sort();
+  if (template.includes('$ARGUMENTS')) hints.push('$ARGUMENTS');
+  return hints;
+}
+
+export function expandSlashCommandTemplate(
+  template: string,
+  rawArguments: string,
+  arguments_: readonly string[],
+): string {
+  const placeholders = template.match(slashCommandPlaceholderPattern) ?? [];
+  let highestPosition = 0;
+  for (const placeholder of placeholders) {
+    highestPosition = Math.max(highestPosition, Number(placeholder.slice(1)));
+  }
+  const segments: string[] = [];
+  let lastIndex = 0;
+  let expandedBytes = 0;
+  for (const match of template.matchAll(slashCommandAllPlaceholderPattern)) {
+    const literal = template.slice(lastIndex, match.index);
+    let replacement: string;
+    if (match[0] === '$ARGUMENTS') {
+      replacement = rawArguments;
+    } else {
+      const position = Number(match[1]);
+      const argumentIndex = position - 1;
+      replacement = argumentIndex < 0 || argumentIndex >= arguments_.length
+        ? ''
+        : position === highestPosition
+          ? arguments_.slice(argumentIndex).join(' ')
+          : arguments_[argumentIndex];
+    }
+    expandedBytes += Buffer.byteLength(literal, 'utf8') + Buffer.byteLength(replacement, 'utf8');
+    if (expandedBytes > FLEX_SLASH_COMMAND_MAX_INPUT_BYTES) {
+      throw new FlexHarnessValidationError('Expanded slash command prompt exceeds the input limit.');
+    }
+    segments.push(literal, replacement);
+    lastIndex = match.index + match[0].length;
+  }
+  segments.push(template.slice(lastIndex));
+  expandedBytes += Buffer.byteLength(segments.at(-1)!, 'utf8');
+  if (expandedBytes > FLEX_SLASH_COMMAND_MAX_INPUT_BYTES) {
+    throw new FlexHarnessValidationError('Expanded slash command prompt exceeds the input limit.');
+  }
+  let expanded = segments.join('');
+  if (placeholders.length === 0 && !template.includes('$ARGUMENTS') && rawArguments.trim()) {
+    if (
+      expandedBytes + Buffer.byteLength(rawArguments, 'utf8') + 2
+      > FLEX_SLASH_COMMAND_MAX_INPUT_BYTES
+    ) {
+      throw new FlexHarnessValidationError('Expanded slash command prompt exceeds the input limit.');
+    }
+    expanded += `\n\n${rawArguments}`;
+  }
+  return expanded;
+}

package/ts_migration/v3_legacyflexharness.ts

@@ -4,10 +4,11 @@ import type {
   IFlexHarnessStores,
   IFlexMessage,
   IFlexPermissionSnapshot,
-  IFlexProjectionSnapshot,
+  IFlexProjectionSnapshotCurrent,
   IFlexScopeSnapshot,
   IFlexSession,
   TFlexAgentModelMessage,
+  TFlexProjectionSnapshot,
   TJsonValue,
 } from '../ts/interfaces.js';
 import {
@@ -44,7 +45,7 @@ interface ILegacyRun {
 
 interface ILegacySessionMigrationPlan {
   sessionId: string;
-  projectionSnapshot: IFlexProjectionSnapshot;
+  projectionSnapshot: IFlexProjectionSnapshotCurrent;
   permissionSnapshot: IFlexPermissionSnapshot;
   agentEvents: plugins.TAgentEvent[];
 }
@@ -56,7 +57,7 @@ interface ILegacyMigrationPlan {
 
 interface IInspectedSessionDestination {
   plan: ILegacySessionMigrationPlan;
-  projection: IFlexProjectionSnapshot | undefined;
+  projection: TFlexProjectionSnapshot | undefined;
   permission: IFlexPermissionSnapshot | undefined;
   eventStore: plugins.IAgentEventStoreV2;
   eventSnapshot: plugins.IAgentEventSnapshotV2 | undefined;
@@ -403,11 +404,15 @@ function createMigrationPlan(
       sessions: [stored.session],
       tombstones: [],
     };
-    const projectionSnapshot: IFlexProjectionSnapshot = {
-      schemaVersion: 1,
+    const projectionSnapshot: IFlexProjectionSnapshotCurrent = {
+      schemaVersion: 2,
       revision: 1,
       messages: stored.messages,
       stagedTerminals: [],
+      reversionSegments: [],
+      revertCursor: 0,
+      excludedRunIds: [],
+      pendingReversionReleases: [],
     };
     const permissionSnapshot: IFlexPermissionSnapshot = {
       schemaVersion: 1,