codex-overleaf-link 2.2.1 → 2.3.0

package/extension/src/shared/pageRpcContract.js

@@ -0,0 +1,136 @@
+(function (root, factory) {
+  var api = factory();
+  if (typeof module === 'object' && module.exports) module.exports = api;
+  if (root) root.CodexOverleafPageRpcContract = api;
+})(typeof window !== 'undefined' ? window : (typeof globalThis !== 'undefined' ? globalThis : this), function () {
+  'use strict';
+
+  var REVISION = '2026-07-26-page-rpc-contract-v13';
+  var METHODS = freezeCatalog({
+    initializeCapability: entry('bridge.initialize', 'control', 'none', 'default', false, 'none'),
+    probe: entry('bridge.probe', 'read', 'none', 'default', false, 'safe'),
+    cancelActiveWrite: entry('write.cancel', 'control', 'none', 'default', false, 'idempotent'),
+    getProjectSnapshot: entry('snapshot.read', 'read', 'none', 'snapshot', true, 'safe'),
+    getProjectFileList: entry('snapshot.list', 'read', 'none', 'file_list', true, 'safe'),
+    invalidateProjectSnapshot: entry('snapshot.invalidate', 'cache', 'none', 'default', false, 'idempotent'),
+    createCheckpoint: entry('checkpoint.create', 'page_state', 'none', 'default', false, 'no_retry'),
+    ensureReviewing: entry('reviewing.enable', 'page_state', 'optional', 'default', true, 'idempotent'),
+    ensureEditing: entry('reviewing.disable', 'page_state', 'optional', 'default', true, 'idempotent'),
+    applyOperations: entry('document.write', 'document', 'required', 'writeback', true, 'no_retry'),
+    jumpToPosition: entry('editor.navigate', 'navigation', 'required', 'default', false, 'idempotent'),
+    rejectTrackedChanges: entry('tracked_changes.reject', 'document', 'required', 'lifecycle', true, 'no_retry'),
+    acceptTrackedChanges: entry('tracked_changes.accept', 'document', 'required', 'lifecycle', true, 'no_retry'),
+    triggerCompile: entry('compile.trigger', 'page_state', 'required', 'compile', false, 'no_retry'),
+    getCompileLog: entry('compile.log', 'read', 'required', 'compile', true, 'safe'),
+    getCompileState: entry('compile.state', 'read', 'none', 'default', false, 'safe'),
+    waitForSaveState: entry('save.wait', 'read', 'none', 'default', true, 'safe'),
+    startOtObserver: entry('ot.start', 'observer', 'none', 'default', false, 'idempotent'),
+    stopOtObserver: entry('ot.stop', 'observer', 'none', 'default', false, 'idempotent'),
+    getOtStatus: entry('ot.status', 'read', 'none', 'default', false, 'safe'),
+    drainOtEvents: entry('ot.drain', 'observer', 'none', 'default', false, 'no_retry')
+  });
+
+  function entry(capability, mutation, projectIdentity, timeoutClass, cancellable, retryClass) {
+    return {
+      capability: capability,
+      mutation: mutation,
+      projectIdentity: projectIdentity,
+      timeoutClass: timeoutClass,
+      cancellation: cancellable ? 'content_abort' : 'none',
+      retryClass: retryClass,
+      failureClass: mutation === 'document' ? 'write' : mutation
+    };
+  }
+
+  function getMethod(name) {
+    return typeof name === 'string' && METHODS[name] ? METHODS[name] : null;
+  }
+
+  function listMethods() {
+    return Object.keys(METHODS);
+  }
+
+  function isCancellable(name) {
+    return getMethod(name)?.cancellation === 'content_abort';
+  }
+
+  function requiresProjectIdentity(name) {
+    return getMethod(name)?.projectIdentity === 'required';
+  }
+
+  function resolveTimeoutMs(name, overrides) {
+    overrides = overrides || {};
+    var timeoutClass = getMethod(name)?.timeoutClass || 'default';
+    var defaults = {
+      default: 8000,
+      snapshot: 70000,
+      file_list: 35000,
+      compile: 75000,
+      lifecycle: 120000,
+      writeback: 30000
+    };
+    var candidate = Number(overrides[timeoutClass]);
+    return Number.isFinite(candidate) && candidate > 0 ? candidate : defaults[timeoutClass];
+  }
+
+  function resolveDispatchPolicy(name, overrides) {
+    var method = getMethod(name);
+    return Object.freeze({
+      timeoutMs: resolveTimeoutMs(name, overrides),
+      cancellation: method ? method.cancellation : 'none',
+      retryClass: method ? method.retryClass : 'none',
+      automaticAttempts: 1
+    });
+  }
+
+  function capabilityReport() {
+    var report = {};
+    listMethods().forEach(function (name) {
+      var method = METHODS[name];
+      report[name] = {
+        capability: method.capability,
+        mutation: method.mutation,
+        projectIdentity: method.projectIdentity,
+        retryClass: method.retryClass,
+        timeoutClass: method.timeoutClass,
+        cancellation: method.cancellation
+      };
+    });
+    return report;
+  }
+
+  function withCapabilityReport(capabilities) {
+    return Object.assign({}, capabilities || {}, { pageRpc: capabilityReport() });
+  }
+
+  function normalizeFailure(method, error) {
+    var contract = getMethod(method);
+    var message = error && error.message ? error.message : String(error || 'Page bridge request failed');
+    return {
+      ok: false,
+      code: 'page_bridge_dispatch_failed',
+      error: message,
+      rpcMethod: typeof method === 'string' ? method : '',
+      failureClass: contract ? contract.failureClass : 'unknown'
+    };
+  }
+
+  function freezeCatalog(catalog) {
+    Object.keys(catalog).forEach(function (name) { Object.freeze(catalog[name]); });
+    return Object.freeze(catalog);
+  }
+
+  return Object.freeze({
+    METHODS: METHODS,
+    REVISION: REVISION,
+    capabilityReport: capabilityReport,
+    getMethod: getMethod,
+    isCancellable: isCancellable,
+    listMethods: listMethods,
+    normalizeFailure: normalizeFailure,
+    requiresProjectIdentity: requiresProjectIdentity,
+    resolveDispatchPolicy: resolveDispatchPolicy,
+    resolveTimeoutMs: resolveTimeoutMs,
+    withCapabilityReport: withCapabilityReport
+  });
+});

package/extension/src/shared/runExecutionSnapshot.js

@@ -0,0 +1,177 @@
+(function initCodexOverleafRunExecutionSnapshot(root, factory) {
+  if (typeof module === 'object' && module.exports) {
+    module.exports = factory(require('./providerProfiles'), require('./runExecutionSnapshotCodec'));
+  } else {
+    root.CodexOverleafModuleRegistry.define('RunExecutionSnapshot', [
+      'ProviderProfiles',
+      'RunExecutionSnapshotCodec'
+    ], factory);
+  }
+})(typeof window !== 'undefined' ? window : globalThis, function runExecutionSnapshotFactory(ProviderProfiles, Codec) {
+  'use strict';
+
+  function create(input = {}) {
+    const providerId = Codec.normalizeText(input.providerId) || 'builtin';
+    return Codec.normalizeSnapshot(input, {
+      source: input.source || 'submitted',
+      requireProviderRevision: providerId !== 'builtin'
+    });
+  }
+
+  function capture(input = {}, options = {}) {
+    return Codec.normalizeSnapshot(input, options);
+  }
+
+  function captureRawQueueTuple(rawQueueItem = {}, fallbackInput = {}) {
+    const rawPayload = rawQueueItem?.payload && typeof rawQueueItem.payload === 'object'
+      ? rawQueueItem.payload
+      : rawQueueItem;
+    const persisted = rawQueueItem?.executionSnapshot || rawPayload?.executionSnapshot;
+    if (persisted && typeof persisted === 'object') {
+      return Codec.normalizeSnapshot(persisted, { source: persisted.source || 'submitted' });
+    }
+    const raw = rawPayload && typeof rawPayload === 'object' ? rawPayload : {};
+    const fallback = fallbackInput && typeof fallbackInput === 'object' ? fallbackInput : {};
+    const captured = {};
+    let inferred = false;
+    for (const field of Codec.TUPLE_FIELDS) {
+      if (Codec.hasOwn(raw, field)) captured[field] = Codec.cloneValue(raw[field]);
+      else {
+        captured[field] = Codec.cloneValue(fallback[field]);
+        inferred = true;
+      }
+    }
+    const providerId = Codec.normalizeText(captured.providerId) || 'builtin';
+    if (providerId !== 'builtin' && !Codec.normalizeRevision(captured.providerRevision)
+      && (!Codec.hasOwn(raw, 'providerRevision') || captured.providerRevision === '' || captured.providerRevision == null)) {
+      captured.providerRevision = fallback.providerRevision;
+      inferred = true;
+    }
+    return Codec.normalizeSnapshot(captured, {
+      source: inferred ? 'legacy-inferred' : 'legacy-captured'
+    });
+  }
+
+  function resolveForExecution(value = {}, options = {}) {
+    const persisted = value.executionSnapshot || value;
+    const snapshot = Codec.normalizeSnapshot(persisted, { source: persisted.source || 'submitted' });
+    if (snapshot.providerId === 'builtin') return Codec.normalizeSnapshot(snapshot, { source: snapshot.source });
+    const catalog = options.catalog || {};
+    const provider = ProviderProfiles?.getProviderById
+      ? ProviderProfiles.getProviderById(catalog, snapshot.providerId)
+      : (catalog.providers || []).find(item => item?.id === snapshot.providerId);
+    if (!provider) throw Codec.snapshotError('provider_not_found', 'The selected provider no longer exists.');
+    const currentRevision = Codec.normalizeRevision(provider.revision);
+    if (!currentRevision) throw Codec.snapshotError('provider_revision_conflict', 'The selected provider has no usable revision.');
+    if (!snapshot.providerRevision) {
+      if (snapshot.source !== 'legacy-inferred') {
+        throw Codec.snapshotError('provider_revision_conflict', 'The selected provider revision was not captured for this run.');
+      }
+      return Codec.normalizeSnapshot({ ...snapshot, providerRevision: currentRevision }, {
+        source: 'legacy-inferred',
+        requireProviderRevision: true
+      });
+    }
+    if (snapshot.providerRevision !== currentRevision) {
+      throw Codec.snapshotError('provider_revision_conflict', 'The selected provider changed after this run was submitted.');
+    }
+    return Codec.normalizeSnapshot(snapshot, { source: snapshot.source, requireProviderRevision: true });
+  }
+
+  function snapshotOf(value = {}) {
+    const persisted = value.executionSnapshot || value;
+    return Codec.normalizeSnapshot(persisted, { source: persisted.source || 'submitted' });
+  }
+
+  function cloneSnapshot(value = {}) {
+    const snapshot = snapshotOf(value);
+    return { ...snapshot, focusFiles: [...snapshot.focusFiles] };
+  }
+
+  function toLegacyQueueTuple(value = {}) {
+    const snapshot = snapshotOf(value);
+    return {
+      mode: snapshot.mode,
+      providerId: snapshot.providerId,
+      providerRevision: snapshot.providerRevision,
+      model: snapshot.model,
+      reasoningEffort: snapshot.reasoningEffort,
+      speedTier: snapshot.speedTier,
+      autoRecompile: snapshot.autoRecompile,
+      requireReviewing: snapshot.requireReviewing,
+      focusFiles: [...snapshot.focusFiles]
+    };
+  }
+
+  function toQueuePayload(value = {}) {
+    const snapshot = snapshotOf(value);
+    return { executionSnapshot: cloneSnapshot(snapshot), ...toLegacyQueueTuple(snapshot) };
+  }
+
+  function toRunCompatibilityTuple(value = {}) {
+    const snapshot = snapshotOf(value);
+    return {
+      ...toLegacyQueueTuple(snapshot),
+      providerRevision: snapshot.providerId === 'builtin' ? 0 : Number(snapshot.providerRevision),
+      executionSnapshot: cloneSnapshot(snapshot)
+    };
+  }
+
+  function projectForDisplay(value = {}) {
+    const snapshot = snapshotOf(value);
+    return {
+      providerId: snapshot.providerId,
+      model: snapshot.model,
+      reasoningEffort: snapshot.reasoningEffort,
+      speedTier: snapshot.speedTier,
+      mode: snapshot.mode,
+      focusFiles: [...snapshot.focusFiles]
+    };
+  }
+
+  function equalsExecutionConfig(left = {}, right = {}) {
+    const leftTuple = toLegacyQueueTuple(left);
+    const rightTuple = toLegacyQueueTuple(right);
+    return Codec.TUPLE_FIELDS.every(field =>
+      JSON.stringify(leftTuple[field]) === JSON.stringify(rightTuple[field])
+    );
+  }
+
+  function applyToState(state = {}, value = {}) {
+    const snapshot = snapshotOf(value);
+    return {
+      ...state,
+      ...toLegacyQueueTuple(snapshot),
+      providerRevision: snapshot.providerId === 'builtin' ? 0 : Number(snapshot.providerRevision)
+    };
+  }
+
+  function toProviderSelection(value = {}) {
+    const snapshot = snapshotOf(value);
+    return {
+      providerId: snapshot.providerId,
+      providerRevision: snapshot.providerId === 'builtin' ? 0 : Number(snapshot.providerRevision)
+    };
+  }
+
+  return {
+    SCHEMA_VERSION: Codec.SCHEMA_VERSION,
+    TUPLE_FIELDS: Codec.TUPLE_FIELDS,
+    applyToState,
+    capture,
+    captureRawQueueTuple,
+    cloneSnapshot,
+    create,
+    equalsExecutionConfig,
+    fromQueuePayload: captureRawQueueTuple,
+    normalizeRevision: Codec.normalizeRevision,
+    normalizeSnapshot: Codec.normalizeSnapshot,
+    projectForDisplay,
+    resolveForExecution,
+    toLegacyQueueTuple,
+    toProviderSelection,
+    toQueuePayload,
+    toRunCompatibilityTuple,
+    validate: Codec.validate
+  };
+});

package/extension/src/shared/runExecutionSnapshotCodec.js

@@ -0,0 +1,168 @@
+(function initCodexOverleafRunExecutionSnapshotCodec(root, factory) {
+  if (typeof module === 'object' && module.exports) {
+    module.exports = factory();
+  } else {
+    root.CodexOverleafRunExecutionSnapshotCodec = factory();
+  }
+})(typeof window !== 'undefined' ? window : globalThis, function runExecutionSnapshotCodecFactory() {
+  'use strict';
+
+  const SCHEMA_VERSION = 1;
+  const VALID_MODES = new Set(['ask', 'confirm', 'auto']);
+  const VALID_SOURCES = new Set(['submitted', 'legacy-captured', 'legacy-inferred']);
+  const TUPLE_FIELDS = Object.freeze([
+    'mode', 'providerId', 'providerRevision', 'model', 'reasoningEffort',
+    'speedTier', 'autoRecompile', 'requireReviewing', 'focusFiles'
+  ]);
+  const SECRET_FIELD_PATTERN = /(?:api.?key|authorization|password|secret|access.?token|refresh.?token)/i;
+
+  function normalizeSnapshot(value = {}, options = {}) {
+    const input = value && typeof value === 'object' ? value : {};
+    assertNoSecretFields(input);
+    const providerId = normalizeText(input.providerId) || 'builtin';
+    const revision = normalizeRevisionResult(input.providerRevision);
+    if (!revision.ok) throw snapshotError('provider_revision_conflict', revision.error);
+    const snapshot = {
+      schemaVersion: SCHEMA_VERSION,
+      mode: VALID_MODES.has(input.mode) ? input.mode : 'ask',
+      providerId,
+      providerRevision: providerId === 'builtin' ? '' : revision.value,
+      model: normalizeText(input.model).slice(0, 160),
+      reasoningEffort: normalizeText(input.reasoningEffort).slice(0, 32),
+      speedTier: input.speedTier === 'fast' ? 'fast' : 'standard',
+      autoRecompile: input.autoRecompile !== false,
+      requireReviewing: input.requireReviewing !== false,
+      focusFiles: normalizePaths(input.focusFiles),
+      capturedAt: normalizeTimestamp(input.capturedAt),
+      source: VALID_SOURCES.has(options.source || input.source)
+        ? (options.source || input.source)
+        : 'submitted'
+    };
+    const result = validate(snapshot, options);
+    if (!result.ok) throw snapshotError(result.errors[0].code, result.errors[0].message);
+    snapshot.focusFiles = Object.freeze([...snapshot.focusFiles]);
+    return Object.freeze(snapshot);
+  }
+
+  function validate(value = {}, options = {}) {
+    const errors = [];
+    if (!value || typeof value !== 'object' || Array.isArray(value)) {
+      return fail('invalid_execution_snapshot', 'Execution snapshot must be an object.');
+    }
+    if (value.schemaVersion !== undefined && Number(value.schemaVersion) !== SCHEMA_VERSION) {
+      errors.push(errorItem('invalid_execution_snapshot', `Unsupported execution snapshot schema version: ${value.schemaVersion}`));
+    }
+    if (!VALID_MODES.has(value.mode)) {
+      errors.push(errorItem('invalid_execution_snapshot', 'Execution snapshot mode is invalid.'));
+    }
+    const providerId = normalizeText(value.providerId);
+    if (!providerId) errors.push(errorItem('invalid_execution_snapshot', 'Execution snapshot provider is missing.'));
+    const revision = normalizeRevisionResult(value.providerRevision);
+    if (!revision.ok) {
+      errors.push(errorItem('provider_revision_conflict', revision.error));
+    } else if (providerId === 'builtin' && revision.value) {
+      errors.push(errorItem('provider_revision_conflict', 'Built-in Codex cannot carry a provider revision.'));
+    } else if (providerId !== 'builtin' && options.requireProviderRevision === true && !revision.value) {
+      errors.push(errorItem('provider_revision_conflict', 'The selected provider revision was not available when the run was submitted.'));
+    }
+    if (!Array.isArray(value.focusFiles) || value.focusFiles.length > 100) {
+      errors.push(errorItem('invalid_execution_snapshot', 'Execution snapshot focus files are invalid.'));
+    }
+    try {
+      assertNoSecretFields(value);
+    } catch (error) {
+      errors.push(errorItem(error.code, error.message));
+    }
+    return { ok: errors.length === 0, errors };
+  }
+
+  function normalizeRevision(value) {
+    const result = normalizeRevisionResult(value);
+    return result.ok ? result.value : '';
+  }
+
+  function normalizeRevisionResult(value) {
+    if (value === undefined || value === null || value === '') return { ok: true, value: '' };
+    const text = typeof value === 'string' ? value.trim() : String(value);
+    if (!text) return { ok: true, value: '' };
+    const number = Number(text);
+    return Number.isSafeInteger(number) && number >= 0
+      ? { ok: true, value: String(number) }
+      : { ok: false, value: '', error: 'Provider revision must be a finite non-negative integer.' };
+  }
+
+  function normalizePaths(value) {
+    const seen = new Set();
+    const result = [];
+    for (const raw of Array.isArray(value) ? value : []) {
+      const path = normalizeProjectPath(raw);
+      if (!path || seen.has(path)) continue;
+      seen.add(path);
+      result.push(path);
+      if (result.length >= 100) break;
+    }
+    return result;
+  }
+
+  function normalizeProjectPath(value) {
+    const result = [];
+    for (const segment of String(value || '').replace(/\0/g, '').replace(/\\/g, '/').replace(/^\/+/, '').split('/')) {
+      if (!segment || segment === '.') continue;
+      if (segment === '..') return '';
+      result.push(segment);
+    }
+    return result.join('/').trim();
+  }
+
+  function normalizeTimestamp(value) {
+    if (typeof value === 'string' && value) return value;
+    if (Number.isFinite(Number(value)) && Number(value) > 0) return new Date(Number(value)).toISOString();
+    return new Date().toISOString();
+  }
+
+  function assertNoSecretFields(value) {
+    for (const key of Object.keys(value && typeof value === 'object' ? value : {})) {
+      if (SECRET_FIELD_PATTERN.test(key)) {
+        throw snapshotError('invalid_execution_snapshot', `Execution snapshot cannot contain secret field "${key}".`);
+      }
+    }
+  }
+
+  function cloneValue(value) {
+    return value === undefined ? undefined : JSON.parse(JSON.stringify(value));
+  }
+
+  function normalizeText(value) {
+    return typeof value === 'string' ? value.trim() : '';
+  }
+
+  function hasOwn(value, key) {
+    return Object.prototype.hasOwnProperty.call(value, key);
+  }
+
+  function snapshotError(code, message) {
+    const error = new Error(message);
+    error.code = code;
+    return error;
+  }
+
+  function errorItem(code, message) {
+    return { code, message };
+  }
+
+  function fail(code, message) {
+    return { ok: false, errors: [errorItem(code, message)] };
+  }
+
+  return {
+    SCHEMA_VERSION,
+    TUPLE_FIELDS,
+    cloneValue,
+    hasOwn,
+    normalizeRevision,
+    normalizeSnapshot,
+    normalizeText,
+    snapshotError,
+    validate
+  };
+});