codex-workflow-v2 2.0.0-beta.1 → 2.0.0-beta.11

package/plugins/codex-workflow-gateway/scripts/chat-registry.mjs

@@ -0,0 +1,376 @@
+#!/usr/bin/env node
+import {
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  renameSync,
+  rmSync,
+  statSync,
+  writeFileSync,
+} from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import process from 'node:process';
+import { randomUUID } from 'node:crypto';
+
+const TYPES = new Set(['coordinator', 'task', 'step-review', 'final-review', 'corrective-audit', 'plan-audit']);
+const LOCK_STALE_MS = 30_000;
+const LOCK_WAIT_MS = 2_000;
+
+export function allocateChat(options) {
+  validateProjectId(options.projectId);
+  if (!TYPES.has(options.type)) throw new Error(`Unsupported chat type: ${options.type}`);
+  return withRegistryLock(options.projectId, options.registryHome, (file) => {
+    const registry = readRegistry(file, options.projectId);
+    const sequence = registry.nextSequence;
+    const reservationId = randomUUID();
+    const candidates = buildTitleCandidates({ ...options, sequence });
+    const entry = {
+      sequence,
+      reservationId,
+      type: options.type,
+      milestoneOrdinal: requiredOrdinal(options.milestoneOrdinal, 'M'),
+      taskOrdinal: optionalOrdinal(options.taskOrdinal, 'T'),
+      stepOrdinal: optionalOrdinal(options.stepOrdinal, 'S'),
+      entityId: requiredText(options.entityId, 'entityId'),
+      semanticTitle: requiredText(options.semanticTitle, 'semanticTitle'),
+      attempt: positiveInteger(options.attempt ?? 1, 'attempt'),
+      candidates,
+      candidateIndex: 0,
+      requestedTitle: candidates[0],
+      observedTitle: null,
+      titleVerified: false,
+      threadId: null,
+      hostId: null,
+      status: 'reserved',
+      createdAt: new Date().toISOString(),
+      updatedAt: new Date().toISOString(),
+    };
+    registry.nextSequence += 1;
+    registry.entries.push(entry);
+    writeRegistry(file, registry);
+    return publicEntry(entry);
+  });
+}
+
+export function readbackChat(options) {
+  validateProjectId(options.projectId);
+  return withRegistryLock(options.projectId, options.registryHome, (file) => {
+    const registry = readRegistry(file, options.projectId);
+    const entry = requireEntry(registry, options.reservationId);
+    const observedTitle = requiredText(options.observedTitle, 'observedTitle');
+    entry.observedTitle = observedTitle;
+    entry.updatedAt = new Date().toISOString();
+    if (observedTitle === entry.candidates[entry.candidateIndex]) {
+      entry.titleVerified = true;
+      entry.status = entry.threadId ? 'bound' : 'verified';
+      writeRegistry(file, registry);
+      return { accepted: true, renameRequired: false, ...publicEntry(entry) };
+    }
+    entry.titleVerified = false;
+    if (entry.candidateIndex + 1 >= entry.candidates.length) {
+      entry.status = 'blocked';
+      writeRegistry(file, registry);
+      return {
+        accepted: false,
+        renameRequired: false,
+        blocker: 'No deterministic title candidate survived exact app readback.',
+        ...publicEntry(entry),
+      };
+    }
+    entry.candidateIndex += 1;
+    entry.requestedTitle = entry.candidates[entry.candidateIndex];
+    entry.status = 'rename-required';
+    writeRegistry(file, registry);
+    return { accepted: false, renameRequired: true, renameTitle: entry.requestedTitle, ...publicEntry(entry) };
+  });
+}
+
+export function bindChat(options) {
+  validateProjectId(options.projectId);
+  return withRegistryLock(options.projectId, options.registryHome, (file) => {
+    const registry = readRegistry(file, options.projectId);
+    const entry = requireEntry(registry, options.reservationId);
+    if (!entry.titleVerified) throw new Error('Chat title must pass exact readback before binding.');
+    entry.threadId = requiredText(options.threadId, 'threadId');
+    entry.hostId = requiredText(options.hostId, 'hostId');
+    entry.status = 'bound';
+    entry.updatedAt = new Date().toISOString();
+    writeRegistry(file, registry);
+    return publicEntry(entry);
+  });
+}
+
+export function retitleChat(options) {
+  validateProjectId(options.projectId);
+  return withRegistryLock(options.projectId, options.registryHome, (file) => {
+    const registry = readRegistry(file, options.projectId);
+    const entry = requireEntry(registry, options.reservationId);
+    entry.entityId = requiredText(options.entityId, 'entityId');
+    entry.semanticTitle = requiredText(options.semanticTitle, 'semanticTitle');
+    entry.candidates = buildTitleCandidates({
+      sequence: entry.sequence,
+      type: entry.type,
+      milestoneOrdinal: entry.milestoneOrdinal,
+      taskOrdinal: entry.taskOrdinal,
+      stepOrdinal: entry.stepOrdinal,
+      entityId: entry.entityId,
+      semanticTitle: entry.semanticTitle,
+      attempt: entry.attempt,
+    });
+    entry.candidateIndex = 0;
+    entry.requestedTitle = entry.candidates[0];
+    entry.observedTitle = null;
+    entry.titleVerified = false;
+    entry.status = 'rename-required';
+    entry.updatedAt = new Date().toISOString();
+    writeRegistry(file, registry);
+    return { renameRequired: true, renameTitle: entry.requestedTitle, ...publicEntry(entry) };
+  });
+}
+
+export function abandonChat(options) {
+  validateProjectId(options.projectId);
+  return withRegistryLock(options.projectId, options.registryHome, (file) => {
+    const registry = readRegistry(file, options.projectId);
+    const entry = requireEntry(registry, options.reservationId);
+    entry.status = 'abandoned';
+    entry.updatedAt = new Date().toISOString();
+    writeRegistry(file, registry);
+    return publicEntry(entry);
+  });
+}
+
+export function showRegistry(options) {
+  validateProjectId(options.projectId);
+  const file = registryFile(options.projectId, options.registryHome);
+  return readRegistry(file, options.projectId);
+}
+
+export function buildTitleCandidates(options) {
+  const prefix = `#${String(positiveInteger(options.sequence, 'sequence')).padStart(3, '0')}`;
+  const milestone = requiredOrdinal(options.milestoneOrdinal, 'M');
+  const task = optionalOrdinal(options.taskOrdinal, 'T');
+  const step = optionalOrdinal(options.stepOrdinal, 'S');
+  const entityId = requiredText(options.entityId, 'entityId');
+  const semantic = compactWhitespace(requiredText(options.semanticTitle, 'semanticTitle'));
+  const attempt = positiveInteger(options.attempt ?? 1, 'attempt');
+  validateTypeBindings(options.type, task, step, entityId);
+  const scope = options.type === 'coordinator'
+    ? milestone
+    : options.type === 'step-review' || options.type === 'corrective-audit'
+      ? [milestone, task, step].filter(Boolean).join('/')
+      : [milestone, task].filter(Boolean).join('/');
+  const role = {
+    coordinator: 'Coord',
+    task: 'Task',
+    'step-review': `Step Review A${attempt}`,
+    'final-review': `Final Review A${attempt}`,
+    'corrective-audit': `Corrective A${attempt}`,
+    'plan-audit': `Plan Audit A${attempt}`,
+  }[options.type];
+  if (!role) throw new Error(`Unsupported chat type: ${options.type}`);
+  return unique([
+    `${prefix} · ${scope} · ${role} · ${semantic} · ${entityId}`,
+    `${prefix} · ${scope} · ${role} · ${entityId}`,
+    `${prefix}·${scope}·${shortRole(options.type, attempt)}·${entityId}`,
+  ]);
+}
+
+function shortRole(type, attempt) {
+  return {
+    coordinator: 'C',
+    task: 'T',
+    'step-review': `SR${attempt}`,
+    'final-review': `FR${attempt}`,
+    'corrective-audit': `CA${attempt}`,
+    'plan-audit': `PA${attempt}`,
+  }[type];
+}
+
+function withRegistryLock(projectId, registryHome, operation) {
+  const file = registryFile(projectId, registryHome);
+  mkdirSync(path.dirname(file), { recursive: true });
+  const lock = `${file}.lock`;
+  const started = Date.now();
+  while (true) {
+    try {
+      mkdirSync(lock);
+      writeFileSync(path.join(lock, 'owner.json'), `${JSON.stringify({ pid: process.pid, acquiredAt: new Date().toISOString() })}\n`);
+      break;
+    } catch (error) {
+      if (error?.code !== 'EEXIST') throw error;
+      if (lockIsStale(lock)) {
+        rmSync(lock, { recursive: true, force: true });
+        continue;
+      }
+      if (Date.now() - started >= LOCK_WAIT_MS) throw new Error(`Chat registry is locked for project ${projectId}.`);
+      Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 20);
+    }
+  }
+  try {
+    return operation(file);
+  } finally {
+    rmSync(lock, { recursive: true, force: true });
+  }
+}
+
+function lockIsStale(lock) {
+  try {
+    return Date.now() - statSync(lock).mtimeMs > LOCK_STALE_MS;
+  } catch {
+    return false;
+  }
+}
+
+function registryFile(projectId, registryHome) {
+  const root = registryHome
+    ? path.resolve(registryHome)
+    : process.env.CODEX_WORKFLOW_CHAT_REGISTRY_HOME
+      ? path.resolve(process.env.CODEX_WORKFLOW_CHAT_REGISTRY_HOME)
+      : path.join(os.homedir(), '.codex', 'workflow-chat-registry', 'v1');
+  return path.join(root, 'projects', projectId, 'registry.json');
+}
+
+function readRegistry(file, projectId) {
+  if (!existsSync(file)) return { schemaVersion: 1, projectId, nextSequence: 1, entries: [] };
+  const value = JSON.parse(readFileSync(file, 'utf8'));
+  if (value.schemaVersion !== 1 || value.projectId !== projectId
+    || !Number.isSafeInteger(value.nextSequence) || value.nextSequence < 1) {
+    throw new Error('Chat registry failed schema or project binding validation.');
+  }
+  if (!Array.isArray(value.entries)) throw new Error('Chat registry entries must be an array.');
+  const sequences = value.entries.map((entry) => entry?.sequence);
+  const reservations = value.entries.map((entry) => entry?.reservationId);
+  if (sequences.some((sequence) => !Number.isSafeInteger(sequence) || sequence < 1 || sequence >= value.nextSequence)
+    || new Set(sequences).size !== sequences.length
+    || reservations.some((reservation) => typeof reservation !== 'string' || !reservation)
+    || new Set(reservations).size !== reservations.length) {
+    throw new Error('Chat registry monotonic sequence or reservation integrity failed.');
+  }
+  return value;
+}
+
+function writeRegistry(file, registry) {
+  const temporary = `${file}.${process.pid}.${randomUUID()}.tmp`;
+  writeFileSync(temporary, `${JSON.stringify(registry, null, 2)}\n`, { flag: 'wx' });
+  renameSync(temporary, file);
+}
+
+function requireEntry(registry, reservationId) {
+  const entry = registry.entries.find((candidate) => candidate.reservationId === reservationId);
+  if (!entry) throw new Error(`Unknown chat reservation: ${reservationId}`);
+  return entry;
+}
+
+function publicEntry(entry) {
+  return {
+    sequence: entry.sequence,
+    ordinal: `#${String(entry.sequence).padStart(3, '0')}`,
+    reservationId: entry.reservationId,
+    type: entry.type,
+    requestedTitle: entry.requestedTitle,
+    observedTitle: entry.observedTitle,
+    titleVerified: entry.titleVerified,
+    threadId: entry.threadId,
+    hostId: entry.hostId,
+    status: entry.status,
+  };
+}
+
+function validateProjectId(projectId) {
+  if (!/^[a-f0-9]{24}$/.test(projectId ?? '')) throw new Error('projectId must be a 24-character lowercase hex value.');
+}
+
+function validateTypeBindings(type, taskOrdinal, stepOrdinal, entityId) {
+  if (!TYPES.has(type)) throw new Error(`Unsupported chat type: ${type}`);
+  if (type !== 'coordinator' && !taskOrdinal) throw new Error(`${type} requires a Task membership ordinal.`);
+  if ((type === 'step-review' || type === 'corrective-audit') && !stepOrdinal) {
+    throw new Error(`${type} requires a Step membership ordinal.`);
+  }
+  const validEntity = type === 'coordinator'
+    ? entityId === 'DISCOVERY' || /^MS-[0-9A-HJKMNP-TV-Z]{26}$/.test(entityId)
+    : /^TASK-[0-9A-HJKMNP-TV-Z]{26}$/.test(entityId);
+  if (!validEntity) throw new Error(`${type} requires its full authoritative entity ID.`);
+}
+
+function requiredOrdinal(value, prefix) {
+  const text = requiredText(value, `${prefix} ordinal`).toUpperCase();
+  if (!new RegExp(`^${prefix}\\d{2,}$`).test(text)) throw new Error(`${prefix} ordinal must use ${prefix}<NN>.`);
+  return text;
+}
+
+function optionalOrdinal(value, prefix) {
+  return value === undefined || value === null || value === '' ? null : requiredOrdinal(value, prefix);
+}
+
+function requiredText(value, name) {
+  if (typeof value !== 'string' || !value.trim()) throw new Error(`${name} is required.`);
+  return value.trim();
+}
+
+function positiveInteger(value, name) {
+  const number = Number(value);
+  if (!Number.isSafeInteger(number) || number < 1) throw new Error(`${name} must be a positive integer.`);
+  return number;
+}
+
+function compactWhitespace(value) {
+  return value.replace(/\s+/g, ' ').trim();
+}
+
+function unique(values) {
+  return [...new Set(values)];
+}
+
+function option(args, name) {
+  const index = args.indexOf(`--${name}`);
+  return index >= 0 ? args[index + 1] : undefined;
+}
+
+function cli() {
+  const [action, ...args] = process.argv.slice(2);
+  const common = {
+    projectId: option(args, 'project-id'),
+    registryHome: option(args, 'registry-home'),
+  };
+  if (action === 'allocate') return allocateChat({
+    ...common,
+    type: option(args, 'type'),
+    milestoneOrdinal: option(args, 'milestone'),
+    taskOrdinal: option(args, 'task'),
+    stepOrdinal: option(args, 'step'),
+    entityId: option(args, 'entity-id'),
+    semanticTitle: option(args, 'semantic-title'),
+    attempt: option(args, 'attempt') ?? 1,
+  });
+  if (action === 'readback') return readbackChat({
+    ...common,
+    reservationId: option(args, 'reservation-id'),
+    observedTitle: option(args, 'observed-title'),
+  });
+  if (action === 'bind') return bindChat({
+    ...common,
+    reservationId: option(args, 'reservation-id'),
+    threadId: option(args, 'thread-id'),
+    hostId: option(args, 'host-id'),
+  });
+  if (action === 'retitle') return retitleChat({
+    ...common,
+    reservationId: option(args, 'reservation-id'),
+    entityId: option(args, 'entity-id'),
+    semanticTitle: option(args, 'semantic-title'),
+  });
+  if (action === 'abandon') return abandonChat({ ...common, reservationId: option(args, 'reservation-id') });
+  if (action === 'show') return showRegistry(common);
+  throw new Error('Use allocate, retitle, readback, bind, abandon, or show.');
+}
+
+if (process.argv[1] && path.resolve(process.argv[1]) === path.resolve(new URL(import.meta.url).pathname)) {
+  try {
+    process.stdout.write(`${JSON.stringify(cli())}\n`);
+  } catch (error) {
+    process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+    process.exitCode = 1;
+  }
+}