@the-open-engine/zeroshot 6.11.0 → 6.13.0

package/lib/cluster/subscriptions.mjs

@@ -0,0 +1,264 @@
+var _a;
+import { ClusterProtocolError, ClusterStateError } from './errors.mjs';
+import { isRecord } from './frames.mjs';
+import { assertDefinition } from './validators.mjs';
+class SubscriptionStream {
+    connection;
+    registration;
+    parse;
+    #done = false;
+    constructor(connection, registration, parse) {
+        this.connection = connection;
+        this.registration = registration;
+        this.parse = parse;
+    }
+    get subscriptionId() { return this.registration.id; }
+    get retainedCount() { return this.registration.queue.retainedCount; }
+    [Symbol.asyncIterator]() { return this; }
+    async next() {
+        if (this.#done)
+            return { done: true, value: undefined };
+        const queued = await this.registration.queue.recv();
+        if (queued.done) {
+            if (this.registration.overflowed) {
+                this.registration.overflowed = false;
+                this.#done = true;
+                return { done: false, value: { type: 'closed', reason: 'SLOW_CONSUMER' } };
+            }
+            this.#done = true;
+            return { done: true, value: undefined };
+        }
+        try {
+            const value = this.parse(queued.value);
+            if (value.type === 'closed')
+                this.#finishWithoutCancel();
+            return { done: false, value };
+        }
+        catch (cause) {
+            await this.#terminate(true);
+            throw cause;
+        }
+    }
+    async return() {
+        await this.#terminate(true);
+        return { done: true, value: undefined };
+    }
+    async throw(error) {
+        await this.#terminate(true);
+        throw error;
+    }
+    cancel() { return this.#terminate(true); }
+    async #terminate(sendCancel) {
+        if (this.#done)
+            return;
+        this.#done = true;
+        this.connection.unregisterSubscription(this.registration.id, this.registration);
+        this.registration.queue.closeAndDiscard();
+        if (sendCancel) {
+            try {
+                await this.connection.cancelSubscription(this.registration);
+            }
+            catch (error) {
+                this.connection.recordDiagnostic(error);
+            }
+        }
+    }
+    #finishWithoutCancel() {
+        if (this.#done)
+            return;
+        this.#done = true;
+        this.connection.unregisterSubscription(this.registration.id, this.registration);
+        this.registration.queue.closeAndDiscard();
+    }
+}
+function parseCursorlessClosed(params, definition) {
+    assertDefinition(definition, params);
+    return { type: 'closed', reason: params.reason };
+}
+function parseWatchClosed(params) {
+    assertDefinition('SubscriptionClosedNotification', params);
+    const cursor = params.lastDeliveredCursor;
+    return {
+        type: 'closed',
+        reason: params.reason,
+        ...(cursor === undefined ? {} : { lastDeliveredCursor: cursor }),
+    };
+}
+function subscriptionParser(field, eventDefinition, closedDefinition) {
+    return (frame) => {
+        if (!isRecord(frame.params)) {
+            throw new ClusterProtocolError('notification params are missing', 'INVALID_SUBSCRIPTION_EVENT');
+        }
+        if (frame.method === 'subscription/closed') {
+            return parseCursorlessClosed(frame.params, closedDefinition);
+        }
+        if (frame.method !== 'event') {
+            throw new ClusterProtocolError('malformed subscription event', 'INVALID_SUBSCRIPTION_EVENT');
+        }
+        assertDefinition(eventDefinition, frame.params);
+        return { type: 'event', event: frame.params[field] };
+    };
+}
+export class LogsSubscriptionStream extends SubscriptionStream {
+    constructor(connection, registration) {
+        super(connection, registration, subscriptionParser('record', 'LogEventNotification', 'LogsClosedNotification'));
+    }
+}
+export class AgentAttachSubscriptionStream extends SubscriptionStream {
+    constructor(connection, registration) {
+        super(connection, registration, subscriptionParser('event', 'AgentAttachEventNotification', 'AgentAttachClosedNotification'));
+    }
+}
+export class WatchSubscriptionStream {
+    #connection;
+    #registration;
+    #lastSeenRunId;
+    #lastSeenCursor;
+    #lastDelivered;
+    #runId;
+    #done = false;
+    #reconnectConsumed = false;
+    #readBarrier = Promise.resolve();
+    constructor(init) {
+        this.#connection = init.connection;
+        this.#registration = init.registration;
+        this.#lastSeenRunId = init.lastSeenRunId;
+        this.#lastSeenCursor = init.lastSeenCursor;
+        this.#lastDelivered = init.params.fromCursor;
+        this.#runId = init.result.runId ?? init.params.runId;
+    }
+    get subscriptionId() { return this.#registration.id; }
+    get retainedCount() { return this.#registration.queue.retainedCount; }
+    get lastDeliveredCursor() { return this.#lastDelivered; }
+    [Symbol.asyncIterator]() { return this; }
+    next() {
+        const read = this.#readBarrier.then(() => this.#nextLogical());
+        this.#readBarrier = read.then(() => undefined, () => undefined);
+        return read;
+    }
+    async #nextLogical() {
+        while (!this.#done) {
+            const queued = await this.#registration.queue.recv();
+            if (queued.done)
+                return this.#finishQueue();
+            const item = await this.#decode(queued.value);
+            if (item)
+                return { done: false, value: item };
+        }
+        return { done: true, value: undefined };
+    }
+    #finishQueue() {
+        this.#done = true;
+        if (!this.#registration.overflowed)
+            return { done: true, value: undefined };
+        this.#registration.overflowed = false;
+        const cursor = this.#lastDelivered;
+        return {
+            done: false,
+            value: { type: 'closed', reason: 'SLOW_CONSUMER', ...(cursor === undefined ? {} : { lastDeliveredCursor: cursor }) },
+        };
+    }
+    async #decode(frame) {
+        if (!isRecord(frame.params))
+            return this.#invalid('notification params are missing');
+        if (frame.method === 'subscription/closed') {
+            const closed = parseWatchClosed(frame.params);
+            if (closed.lastDeliveredCursor !== undefined)
+                this.#lastDelivered = closed.lastDeliveredCursor;
+            this.#finishWithoutCancel();
+            return closed;
+        }
+        if (frame.method !== 'event')
+            return this.#invalid('malformed watch event');
+        try {
+            assertDefinition('EventNotification', frame.params);
+        }
+        catch {
+            return this.#invalid('malformed watch event');
+        }
+        const { runId, cursor, event } = frame.params;
+        if (this.#lastSeenRunId === runId && this.#lastSeenCursor === cursor)
+            return undefined;
+        this.#lastSeenRunId = runId;
+        this.#lastSeenCursor = cursor;
+        this.#runId = runId;
+        this.#lastDelivered = cursor;
+        return { type: 'event', runId, cursor, event };
+    }
+    async return() {
+        await this.#terminate(true);
+        return { done: true, value: undefined };
+    }
+    async throw(error) {
+        await this.#terminate(true);
+        throw error;
+    }
+    cancel() { return this.#terminate(true); }
+    reconnect(freshConnection) {
+        if (this.#reconnectConsumed) {
+            throw new ClusterStateError('watch stream reconnect is one-shot', 'RECONNECT_CONSUMED');
+        }
+        this.#reconnectConsumed = true;
+        return this.#reconnectOn(freshConnection);
+    }
+    async #reconnectOn(freshConnection) {
+        await this.#terminate(true);
+        try {
+            const runId = this.#runId;
+            const fromCursor = this.#lastDelivered;
+            const params = {
+                ...(runId === undefined ? {} : { runId }),
+                ...(fromCursor === undefined ? {} : { fromCursor }),
+            };
+            const established = await freshConnection.openSubscription('watch', params);
+            return {
+                result: established.result,
+                stream: new _a({
+                    connection: freshConnection,
+                    registration: established.registration,
+                    result: established.result,
+                    params,
+                    ...(this.#lastSeenRunId === undefined ? {} : { lastSeenRunId: this.#lastSeenRunId }),
+                    ...(this.#lastSeenCursor === undefined ? {} : { lastSeenCursor: this.#lastSeenCursor }),
+                }),
+            };
+        }
+        catch (error) {
+            await freshConnection.close();
+            throw error;
+        }
+    }
+    async #terminate(sendCancel) {
+        if (this.#done)
+            return;
+        this.#done = true;
+        this.#connection.unregisterSubscription(this.#registration.id, this.#registration);
+        this.#registration.queue.closeAndDiscard();
+        if (sendCancel) {
+            try {
+                await this.#connection.cancelSubscription(this.#registration);
+            }
+            catch (error) {
+                this.#connection.recordDiagnostic(error);
+            }
+        }
+    }
+    #finishWithoutCancel() {
+        if (this.#done)
+            return;
+        this.#done = true;
+        this.#connection.unregisterSubscription(this.#registration.id, this.#registration);
+        this.#registration.queue.closeAndDiscard();
+    }
+    async #invalid(message) {
+        await this.#terminate(true);
+        throw new ClusterProtocolError(message, 'INVALID_SUBSCRIPTION_EVENT');
+    }
+}
+_a = WatchSubscriptionStream;
+Object.defineProperty(SubscriptionStream.prototype, Symbol.asyncDispose, {
+    configurable: true, value: SubscriptionStream.prototype.cancel,
+});
+Object.defineProperty(WatchSubscriptionStream.prototype, Symbol.asyncDispose, {
+    configurable: true, value: WatchSubscriptionStream.prototype.cancel,
+});

package/lib/cluster/validators.cjs

@@ -0,0 +1,46 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.assertDefinition = assertDefinition;
+exports.assertMethodResult = assertMethodResult;
+const _2020_js_1 = require("ajv/dist/2020.js");
+const protocol_js_1 = require("./generated/protocol.cjs");
+const protocol_schema_js_1 = require("./generated/protocol-schema.cjs");
+const errors_js_1 = require("./errors.cjs");
+const ajv = new _2020_js_1.default({
+    allErrors: true,
+    strict: false,
+    validateFormats: false,
+});
+ajv.addSchema(protocol_schema_js_1.CLUSTER_PROTOCOL_SCHEMA, 'openengine-cluster-v1');
+const validators = new Map();
+function validatorFor(definition) {
+    const cached = validators.get(definition);
+    if (cached)
+        return cached;
+    const validator = ajv.compile({
+        $ref: `openengine-cluster-v1#/$defs/${definition}`,
+    });
+    validators.set(definition, validator);
+    return validator;
+}
+function assertDefinition(definition, value) {
+    const validate = validatorFor(definition);
+    if (validate(value))
+        return;
+    const details = (validate.errors ?? []).map((error) => `${error.instancePath || '/'} ${error.message ?? 'is invalid'}`).join('; ');
+    throw new errors_js_1.ClusterProtocolError(`${definition} validation failed: ${details}`, 'INVALID_RESPONSE');
+}
+function assertMethodResult(method, value) {
+    try {
+        assertDefinition(protocol_js_1.METHOD_RESULT_DEFINITIONS[method], value);
+    }
+    catch (error) {
+        const receivedVersion = method === 'initialize' && value !== null && typeof value === 'object'
+            ? value.protocolVersion
+            : undefined;
+        if (typeof receivedVersion === 'string' && receivedVersion !== protocol_js_1.PROTOCOL_VERSION) {
+            throw new errors_js_1.ClusterProtocolError(`unsupported protocol version ${receivedVersion}`, 'UNSUPPORTED_PROTOCOL_VERSION');
+        }
+        throw error;
+    }
+}

package/lib/cluster/validators.d.ts

@@ -0,0 +1,3 @@
+import type { ClusterMethod } from './generated/protocol.js';
+export declare function assertDefinition(definition: string, value: unknown): void;
+export declare function assertMethodResult(method: ClusterMethod, value: unknown): void;

package/lib/cluster/validators.mjs

@@ -0,0 +1,42 @@
+import Ajv2020 from 'ajv/dist/2020.js';
+import { METHOD_RESULT_DEFINITIONS, PROTOCOL_VERSION, } from './generated/protocol.mjs';
+import { CLUSTER_PROTOCOL_SCHEMA } from './generated/protocol-schema.mjs';
+import { ClusterProtocolError } from './errors.mjs';
+const ajv = new Ajv2020({
+    allErrors: true,
+    strict: false,
+    validateFormats: false,
+});
+ajv.addSchema(CLUSTER_PROTOCOL_SCHEMA, 'openengine-cluster-v1');
+const validators = new Map();
+function validatorFor(definition) {
+    const cached = validators.get(definition);
+    if (cached)
+        return cached;
+    const validator = ajv.compile({
+        $ref: `openengine-cluster-v1#/$defs/${definition}`,
+    });
+    validators.set(definition, validator);
+    return validator;
+}
+export function assertDefinition(definition, value) {
+    const validate = validatorFor(definition);
+    if (validate(value))
+        return;
+    const details = (validate.errors ?? []).map((error) => `${error.instancePath || '/'} ${error.message ?? 'is invalid'}`).join('; ');
+    throw new ClusterProtocolError(`${definition} validation failed: ${details}`, 'INVALID_RESPONSE');
+}
+export function assertMethodResult(method, value) {
+    try {
+        assertDefinition(METHOD_RESULT_DEFINITIONS[method], value);
+    }
+    catch (error) {
+        const receivedVersion = method === 'initialize' && value !== null && typeof value === 'object'
+            ? value.protocolVersion
+            : undefined;
+        if (typeof receivedVersion === 'string' && receivedVersion !== PROTOCOL_VERSION) {
+            throw new ClusterProtocolError(`unsupported protocol version ${receivedVersion}`, 'UNSUPPORTED_PROTOCOL_VERSION');
+        }
+        throw error;
+    }
+}

package/lib/settings.js

@@ -6,6 +6,8 @@
 const fs = require('fs');
 const path = require('path');
 const os = require('os');
+const crypto = require('crypto');
+const lockfile = require('proper-lockfile');
 const { validateMountConfig, validateEnvPassthrough } = require('./docker-config');
 const {
   VALID_PROVIDERS,
@@ -13,6 +15,18 @@ const {
   normalizeProviderSettings,
 } = require('./provider-names');
 
+const SETTINGS_LOCK_STALE_MS = 5000;
+const SETTINGS_LOCK_TIMEOUT_MS = 500;
+const SETTINGS_LOCK_RETRY_MS = 20;
+const SETTINGS_LOCK_SLEEP = new Int32Array(new SharedArrayBuffer(4));
+
+class SettingsValidationError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = 'SettingsValidationError';
+  }
+}
+
 // Lazy-loaded to avoid circular dependency (issue-providers → settings → issue-providers)
 let _issueProviderFns = null;
 function getIssueProviderFns() {
@@ -115,10 +129,11 @@ const DEFAULT_SETTINGS_BASE = {
   defaultDelivery: 'none', // 'none' | 'pr' | 'ship' - folded into resolveEffectiveRunPlan same as defaultDocker
   strictSchema: true, // true = reliable json output (default), false = live streaming (may crash - see bold-meadow-11)
   logLevel: 'normal',
-  // Auto-update settings
+  // Automatic update notification cache
   autoCheckUpdates: true, // Check npm registry for newer versions
-  lastUpdateCheckAt: null, // Unix timestamp of last check (null = never checked)
-  lastSeenVersion: null, // Don't re-prompt for same version
+  lastUpdateCheckAt: null, // Unix timestamp of last automatic attempt (null = never checked)
+  lastSeenVersion: null, // Compatibility key containing the cached valid npm-latest version
+  lastUpdateCheckClaim: null, // Opaque ownership token for an in-flight automatic refresh
   // Claude command - customize how to invoke Claude CLI (default: 'claude')
   // Example: 'ccr code' for claude-code-router integration
   claudeCommand: 'claude',
@@ -260,48 +275,204 @@ function normalizeLoadedSettings(parsed) {
   if (parsed.providerSettings) {
     normalized.providerSettings = normalizeProviderSettings(parsed.providerSettings);
   }
+  if (
+    normalized.autoCheckUpdates === false ||
+    typeof normalized.lastUpdateCheckClaim !== 'string' ||
+    normalized.lastUpdateCheckClaim.trim().length === 0
+  ) {
+    normalized.lastUpdateCheckClaim = null;
+  }
   return normalized;
 }
 
+function resolvedDefaultSettings() {
+  return {
+    ...DEFAULT_SETTINGS,
+    providerSettings: mergeProviderSettings(getProviderDefaults()),
+  };
+}
+
+function mergeLoadedSettings(parsed) {
+  const normalized = normalizeLoadedSettings(parsed);
+  const merged = { ...resolvedDefaultSettings(), ...normalized };
+  merged.defaultProvider =
+    normalizeProviderName(merged.defaultProvider) || DEFAULT_SETTINGS.defaultProvider;
+  merged.providerSettings = mergeProviderSettings(getProviderDefaults(), normalized.providerSettings);
+  if (
+    merged.autoCheckUpdates === false ||
+    typeof merged.lastUpdateCheckClaim !== 'string' ||
+    merged.lastUpdateCheckClaim.trim().length === 0
+  ) {
+    merged.lastUpdateCheckClaim = null;
+  }
+  return applyLegacyModelBounds(merged);
+}
+
 /**
  * Load settings from disk, merging with defaults
  */
-function loadSettings() {
+function loadSettings(options = {}) {
   const settingsFile = getSettingsFile();
   if (!fs.existsSync(settingsFile)) {
-    // Return a copy with resolved providerSettings
+    return resolvedDefaultSettings();
+  }
+  try {
+    return mergeLoadedSettings(JSON.parse(fs.readFileSync(settingsFile, 'utf8')));
+  } catch {
+    if (!options.silent) console.error('Warning: Could not load settings, using defaults');
+    return resolvedDefaultSettings();
+  }
+}
+
+function readSettingsForMutation(settingsFile) {
+  if (!fs.existsSync(settingsFile)) {
     return {
-      ...DEFAULT_SETTINGS,
-      providerSettings: getProviderDefaults(),
+      settings: resolvedDefaultSettings(),
+      requiresClaimInvalidation: false,
+      requiresRecovery: false,
     };
   }
+  let parsed;
   try {
-    const data = fs.readFileSync(settingsFile, 'utf8');
-    const parsed = normalizeLoadedSettings(JSON.parse(data));
-    const merged = { ...DEFAULT_SETTINGS, ...parsed };
-    merged.defaultProvider =
-      normalizeProviderName(merged.defaultProvider) || DEFAULT_SETTINGS.defaultProvider;
-    merged.providerSettings = mergeProviderSettings(getProviderDefaults(), parsed.providerSettings);
-    return applyLegacyModelBounds(merged);
-  } catch {
-    console.error('Warning: Could not load settings, using defaults');
+    parsed = JSON.parse(fs.readFileSync(settingsFile, 'utf8'));
+  } catch (error) {
+    if (!(error instanceof SyntaxError)) throw error;
     return {
-      ...DEFAULT_SETTINGS,
-      providerSettings: getProviderDefaults(),
+      settings: resolvedDefaultSettings(),
+      requiresClaimInvalidation: false,
+      requiresRecovery: true,
     };
   }
+  if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+    return {
+      settings: resolvedDefaultSettings(),
+      requiresClaimInvalidation: false,
+      requiresRecovery: true,
+    };
+  }
+
+
+  const updatesDisabled = parsed.autoCheckUpdates === false || parsed.updatePolicy === 'off';
+  return {
+    settings: mergeLoadedSettings(parsed),
+    requiresClaimInvalidation: updatesDisabled && parsed.lastUpdateCheckClaim !== null,
+    requiresRecovery: false,
+  };
+}
+
+function getAtomicSettingsMode(settingsFile) {
+  try {
+    return fs.statSync(settingsFile).mode & 0o600;
+  } catch (error) {
+    if (error.code === 'ENOENT') return 0o600;
+    throw error;
+  }
+}
+
+function atomicWriteSettings(settingsFile, settings) {
+  const dir = path.dirname(settingsFile);
+  const temporaryFile = path.join(
+    dir,
+    `.${path.basename(settingsFile)}.${process.pid}.${crypto.randomUUID()}.tmp`
+  );
+
+  let operationError;
+  try {
+    fs.writeFileSync(temporaryFile, JSON.stringify(settings, null, 2), {
+      encoding: 'utf8',
+      flag: 'wx',
+      mode: getAtomicSettingsMode(settingsFile),
+    });
+    fs.renameSync(temporaryFile, settingsFile);
+  } catch (error) {
+    operationError = error;
+  }
+
+  try {
+    fs.unlinkSync(temporaryFile);
+  } catch (error) {
+    if (error.code !== 'ENOENT' && !operationError) operationError = error;
+  }
+  if (operationError) throw operationError;
+}
+
+function acquireSettingsLock(settingsFile, lockfilePath, timeoutMs) {
+  const deadline = Date.now() + timeoutMs;
+  while (true) {
+    try {
+      return lockfile.lockSync(settingsFile, {
+        lockfilePath,
+        realpath: false,
+        stale: SETTINGS_LOCK_STALE_MS,
+      });
+    } catch (error) {
+      if (error.code !== 'ELOCKED' || Date.now() >= deadline) throw error;
+      Atomics.wait(SETTINGS_LOCK_SLEEP, 0, 0, SETTINGS_LOCK_RETRY_MS);
+    }
+  }
 }
 
 /**
- * Save settings to disk
+ * Atomically mutate global settings under the process-shared settings lock.
+ * The mutator receives only the freshly re-read, normalized state.
+ *
+ * @param {(settings: object) => any} mutator
+ * @param {object} [options]
+ * @returns {any} the mutator's return value
  */
-function saveSettings(settings) {
+function mutateSettings(mutator, options = {}) {
+  if (typeof mutator !== 'function') {
+    throw new TypeError('Global settings mutation requires a callback');
+  }
+
   const settingsFile = getSettingsFile();
   const dir = path.dirname(settingsFile);
-  if (!fs.existsSync(dir)) {
+  const lockfilePath = `${settingsFile}.lock`;
+  let release;
+  let result;
+  let mutationError;
+
+  try {
     fs.mkdirSync(dir, { recursive: true });
+    release = acquireSettingsLock(
+      settingsFile,
+      lockfilePath,
+      options.lockTimeoutMs ?? SETTINGS_LOCK_TIMEOUT_MS
+    );
+
+    const { settings, requiresClaimInvalidation, requiresRecovery } =
+      readSettingsForMutation(settingsFile);
+    const before = JSON.stringify(settings);
+    result = mutator(settings);
+    if (result && typeof result.then === 'function') {
+      throw new TypeError('Global settings mutations must be synchronous');
+    }
+    if (settings.autoCheckUpdates === false || settings.updatePolicy === 'off') {
+      settings.lastUpdateCheckClaim = null;
+    }
+    if (requiresRecovery || requiresClaimInvalidation || JSON.stringify(settings) !== before) {
+      atomicWriteSettings(settingsFile, settings);
+    }
+  } catch (error) {
+    mutationError =
+      error instanceof SettingsValidationError
+        ? error
+        : new Error(`Unable to persist global settings: ${error.message}`, { cause: error });
+  } finally {
+    if (release) {
+      try {
+        release();
+      } catch (error) {
+        if (!mutationError) {
+          mutationError = new Error(`Unable to release global settings lock: ${error.message}`, {
+            cause: error,
+          });
+        }
+      }
+    }
   }
-  fs.writeFileSync(settingsFile, JSON.stringify(settings, null, 2), 'utf8');
+  if (mutationError) throw mutationError;
+  return result;
 }
 
 /**
@@ -537,9 +708,10 @@ function getClaudeCommand() {
 
 module.exports = {
   loadSettings,
-  saveSettings,
+  mutateSettings,
   validateSetting,
   coerceValue,
+  SettingsValidationError,
   DEFAULT_SETTINGS,
   getSettingsFile,
   settingsFileExists,