@the-open-engine/zeroshot 6.17.0 → 6.18.0

package/src/cluster/json-source.ts

@@ -0,0 +1,71 @@
+import { ClusterRequestError } from './errors.js';
+import { MAX_FRAME_BYTES } from './generated/protocol.js';
+
+export const MAX_REQUEST_BYTES = MAX_FRAME_BYTES;
+
+export function decodeBoundedJson(bytes: Uint8Array): unknown {
+  if (bytes.length > MAX_REQUEST_BYTES) {
+    throw new ClusterRequestError(
+      `request payload of ${bytes.length} bytes exceeds the ${MAX_REQUEST_BYTES} byte limit`,
+      'OVERSIZED_JSON',
+    );
+  }
+  let text: string;
+  try {
+    text = new TextDecoder('utf-8', { fatal: true }).decode(bytes);
+  } catch {
+    throw new ClusterRequestError('request payload is not valid UTF-8', 'INVALID_UTF8');
+  }
+  try {
+    return JSON.parse(text) as unknown;
+  } catch {
+    throw new ClusterRequestError('request payload is not valid JSON', 'MALFORMED_JSON');
+  }
+}
+
+// Callers resolve `--graph`/`--input` specifiers ('-' vs. a file path) to a byte
+// source themselves; opening the filesystem stream stays outside src/cluster so this
+// module keeps no host-specific dependency (not even the `NodeJS` ambient namespace,
+// which isn't resolvable from a consumer's declaration-only install) beyond the
+// standard async-iterable protocol every Node Readable already implements — mirrors
+// how WebSocketLike is injected instead of importing 'ws' directly, see socket.ts.
+export async function readBoundedSource(
+  source: AsyncIterable<Uint8Array | string>,
+): Promise<Uint8Array> {
+  const encoder = new TextEncoder();
+  const chunks: Uint8Array[] = [];
+  let total = 0;
+  for await (const chunk of source) {
+    const bytes = typeof chunk === 'string' ? encoder.encode(chunk) : new Uint8Array(chunk);
+    total += bytes.length;
+    if (total > MAX_REQUEST_BYTES) {
+      throw new ClusterRequestError(
+        `request payload exceeds the ${MAX_REQUEST_BYTES} byte limit`,
+        'OVERSIZED_JSON',
+      );
+    }
+    chunks.push(bytes);
+  }
+  const assembled = new Uint8Array(total);
+  let offset = 0;
+  for (const bytes of chunks) {
+    assembled.set(bytes, offset);
+    offset += bytes.length;
+  }
+  return assembled;
+}
+
+export function assertDistinctRequestSources(
+  graph: string,
+  input: string | undefined,
+): asserts input is string {
+  if (input === undefined) {
+    throw new ClusterRequestError('--input is required for every hosted run', 'MISSING_INPUT');
+  }
+  if (graph === '-' && input === '-') {
+    throw new ClusterRequestError(
+      'graph and input cannot both read from stdin',
+      'AMBIGUOUS_STDIN_SOURCE',
+    );
+  }
+}

package/src/cluster/payload-value.ts

@@ -0,0 +1,84 @@
+import type { PayloadType } from './generated/protocol.js';
+import { ClusterRequestError } from './errors.js';
+
+export type InputValidationIssue = {
+  readonly path: string;
+  readonly code: 'TYPE_MISMATCH' | 'MISSING_REQUIRED_FIELD' | 'UNKNOWN_FIELD' | 'UNKNOWN_ENUM_LABEL';
+};
+
+type InternalIssue = InputValidationIssue & { readonly expectedKind: string };
+
+function isJsonInteger(value: unknown): boolean {
+  return typeof value === 'number' && Number.isFinite(value) && Number.isInteger(value);
+}
+
+function evaluate(type: PayloadType, value: unknown, path: string): InternalIssue | null {
+  switch (type.kind) {
+    case 'null':
+      return value === null ? null : { path, code: 'TYPE_MISMATCH', expectedKind: 'null' };
+    case 'boolean':
+      return typeof value === 'boolean' ? null : { path, code: 'TYPE_MISMATCH', expectedKind: 'boolean' };
+    case 'integer':
+      return isJsonInteger(value) ? null : { path, code: 'TYPE_MISMATCH', expectedKind: 'integer' };
+    case 'number':
+      return typeof value === 'number' && Number.isFinite(value)
+        ? null
+        : { path, code: 'TYPE_MISMATCH', expectedKind: 'number' };
+    case 'string':
+      return typeof value === 'string' ? null : { path, code: 'TYPE_MISMATCH', expectedKind: 'string' };
+    case 'enum':
+      if (typeof value !== 'string') return { path, code: 'TYPE_MISMATCH', expectedKind: 'enum' };
+      return type.values.includes(value)
+        ? null
+        : { path, code: 'UNKNOWN_ENUM_LABEL', expectedKind: 'enum' };
+    case 'array': {
+      if (!Array.isArray(value)) return { path, code: 'TYPE_MISMATCH', expectedKind: 'array' };
+      for (let index = 0; index < value.length; index += 1) {
+        const issue = evaluate(type.items, value[index], `${path}/${index}`);
+        if (issue) return issue;
+      }
+      return null;
+    }
+    case 'record': {
+      if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+        return { path, code: 'TYPE_MISMATCH', expectedKind: 'record' };
+      }
+      const record = value as Readonly<Record<string, unknown>>;
+      const fieldNames = Object.keys(type.fields).sort();
+      for (const name of fieldNames) {
+        const field = type.fields[name];
+        if (!field) continue;
+        const fieldPath = `${path}/${name}`;
+        if (Object.prototype.hasOwnProperty.call(record, name)) {
+          const issue = evaluate(field.type, record[name], fieldPath);
+          if (issue) return issue;
+        } else if (field.required) {
+          return { path: fieldPath, code: 'MISSING_REQUIRED_FIELD', expectedKind: field.type.kind };
+        }
+      }
+      const declared = new Set(fieldNames);
+      const unknownField = Object.keys(record).sort().find((name) => !declared.has(name));
+      return unknownField
+        ? { path: `${path}/${unknownField}`, code: 'UNKNOWN_FIELD', expectedKind: 'record' }
+        : null;
+    }
+  }
+}
+
+export function firstInputValidationIssue(
+  type: PayloadType,
+  value: unknown,
+  path = '',
+): InputValidationIssue | null {
+  const issue = evaluate(type, value, path);
+  return issue ? { path: issue.path, code: issue.code } : null;
+}
+
+export function assertInputValue(type: PayloadType, value: unknown): void {
+  const issue = evaluate(type, value, '');
+  if (!issue) return;
+  throw new ClusterRequestError(
+    `input value at '${issue.path || '/'}' failed validation: ${issue.code}, expected ${issue.expectedKind}`,
+    'INVALID_INPUT',
+  );
+}

package/src/cluster/validators.ts

@@ -4,9 +4,9 @@ import {
   METHOD_RESULT_DEFINITIONS,
   PROTOCOL_VERSION,
 } from './generated/protocol.js';
-import type { ClusterMethod } from './generated/protocol.js';
+import type { ClusterMethod, GraphProfile, GraphSpec, ServerCapabilities } from './generated/protocol.js';
 import { CLUSTER_PROTOCOL_SCHEMA } from './generated/protocol-schema.js';
-import { ClusterProtocolError } from './errors.js';
+import { ClusterProtocolError, ClusterRequestError } from './errors.js';
 
 const ajv = new Ajv2020({
   allErrors: true,
@@ -54,3 +54,32 @@ export function assertMethodResult(method: ClusterMethod, value: unknown): void
     throw error;
   }
 }
+
+function assertRequestDefinition(definition: string, value: unknown, code: string): void {
+  const validate = validatorFor(definition);
+  if (validate(value)) return;
+  const details = (validate.errors ?? []).map((error) =>
+    `${error.instancePath || '/'} ${error.message ?? 'is invalid'}`
+  ).join('; ');
+  throw new ClusterRequestError(`${definition} validation failed: ${details}`, code);
+}
+
+export function assertGraphSpec(value: unknown): asserts value is GraphSpec {
+  assertRequestDefinition('GraphSpec', value, 'INVALID_GRAPH');
+}
+
+export function assertGraphProfile(value: unknown): asserts value is GraphProfile {
+  assertRequestDefinition('GraphProfile', value, 'INVALID_GRAPH_PROFILE');
+}
+
+export function assertGraphProfileSupported(
+  profile: GraphProfile,
+  capabilities: ServerCapabilities,
+): void {
+  if (!capabilities.graphProfiles?.includes(profile)) {
+    throw new ClusterRequestError(
+      `graph profile ${profile} is not among the server's advertised graphProfiles`,
+      'UNSUPPORTED_GRAPH_PROFILE',
+    );
+  }
+}

package/src/orchestrator.js

@@ -270,6 +270,7 @@ class Orchestrator {
 
     // Track if orchestrator is closed (prevents _saveClusters race conditions during cleanup)
     this.closed = false;
+    this._conductorWatchdogs = new Set();
 
     // Track if clusters are loaded (for lazy loading pattern)
     this._clustersLoaded = options.skipLoad === true;
@@ -1654,6 +1655,28 @@ class Orchestrator {
     const timeoutMs = 30000;
     let watchdogTimer = null;
     let completedAt = null;
+    const watchdog = {
+      clear: () => {
+        if (!watchdogTimer) {
+          return;
+        }
+        clearTimeout(watchdogTimer);
+        watchdogTimer = null;
+        this._conductorWatchdogs.delete(watchdog);
+        const elapsed = completedAt ? Date.now() - completedAt : 0;
+        this._log(
+          `✅ CLUSTER_OPERATIONS received (${elapsed}ms after conductor completed) - watchdog cleared`
+        );
+      },
+      dispose: () => {
+        if (watchdogTimer) {
+          clearTimeout(watchdogTimer);
+          watchdogTimer = null;
+        }
+        this._conductorWatchdogs.delete(watchdog);
+      },
+    };
+    this._conductorWatchdogs.add(watchdog);
 
     this._subscribeToClusterTopic(messageBus, clusterId, 'AGENT_LIFECYCLE', (message) => {
       const event = message.content?.data?.event;
@@ -1666,6 +1689,11 @@ class Orchestrator {
         );
 
         watchdogTimer = setTimeout(() => {
+          watchdogTimer = null;
+          this._conductorWatchdogs.delete(watchdog);
+          if (this.closed || messageBus._closed) {
+            return;
+          }
           const clusterOps = messageBus.query({
             cluster_id: clusterId,
             topic: 'CLUSTER_OPERATIONS',
@@ -1700,19 +1728,7 @@ class Orchestrator {
       }
     });
 
-    return {
-      clear: () => {
-        if (!watchdogTimer) {
-          return;
-        }
-        clearTimeout(watchdogTimer);
-        watchdogTimer = null;
-        const elapsed = completedAt ? Date.now() - completedAt : 0;
-        this._log(
-          `✅ CLUSTER_OPERATIONS received (${elapsed}ms after conductor completed) - watchdog cleared`
-        );
-      },
-    };
+    return watchdog;
   }
 
   _registerClusterOperationsHandler(
@@ -2414,6 +2430,10 @@ class Orchestrator {
       return;
     }
     this.closed = true;
+    for (const watchdog of this._conductorWatchdogs) {
+      watchdog.dispose();
+    }
+    this._conductorWatchdogs.clear();
 
     for (const cluster of this.clusters.values()) {
       if (typeof cluster.snapshotter?.stop === 'function') {

package/task-lib/attachable-watcher.js

@@ -111,6 +111,7 @@ const providerSessionCapture = createProviderSessionCapture({
   requestedSessionId: persistedTask?.requestedResumeSessionId || null,
   initialSessionId: persistedTask?.sessionId || null,
   initialSessionIdConflict: persistedTask?.sessionIdConflict === true,
+  disabled: config.structuredOutputRecovery === true,
 });
 let outputBuffer = '';
 

package/task-lib/command-spec-cleanup.js

@@ -14,6 +14,10 @@ const CLEANUP_METADATA_KEYS = ['kind', 'path', 'provider', 'reason'];
 const SCHEMA_DIRECTORY_PATTERN = /^zeroshot-schema-[A-Za-z0-9_-]+$/u;
 const SCHEMA_FILE_PATTERN =
   /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}\.json$/u;
+const POLICY_DIRECTORY_PATTERN = /^zeroshot-gemini-policy-[A-Za-z0-9_-]+$/u;
+const POLICY_FILE_PATTERN =
+  /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}\.toml$/u;
+const OPENCODE_CONFIG_DIRECTORY_PATTERN = /^zeroshot-opencode-config-[A-Za-z0-9_-]+$/u;
 
 function assertClosedCleanupMetadata(cleanupPath, metadata) {
   if (!metadata || typeof metadata !== 'object' || Array.isArray(metadata)) {
@@ -59,6 +63,37 @@ function createCleanupPlan(commandSpec) {
 }
 
 function assertOwnedTempDirectory(cleanupPath, metadata) {
+  const isOpenCodeConfig =
+    metadata.provider === 'opencode' && metadata.reason === 'isolated-config';
+  if (isOpenCodeConfig) {
+    const canonical =
+      isAbsolute(cleanupPath) &&
+      resolve(cleanupPath) === cleanupPath &&
+      dirname(cleanupPath) === resolve(tmpdir()) &&
+      OPENCODE_CONFIG_DIRECTORY_PATTERN.test(basename(cleanupPath));
+    if (!canonical) {
+      throw new Error(`Refusing unowned temporary directory cleanup: ${cleanupPath}`);
+    }
+    let stat;
+    try {
+      stat = lstatSync(cleanupPath);
+    } catch (error) {
+      if (error?.code === 'ENOENT') return true;
+      throw error;
+    }
+    const tempRoot = realpathSync(tmpdir());
+    const realDirectory = realpathSync(cleanupPath);
+    if (
+      stat.isSymbolicLink() ||
+      !stat.isDirectory() ||
+      dirname(realDirectory) !== tempRoot ||
+      basename(realDirectory) !== basename(cleanupPath)
+    ) {
+      throw new Error(`Refusing unowned temporary directory cleanup: ${cleanupPath}`);
+    }
+    return false;
+  }
+
   if (
     metadata.provider !== 'claude' ||
     metadata.reason !== 'settings-overlay' ||
@@ -79,22 +114,33 @@ function assertOwnedTempDirectory(cleanupPath, metadata) {
 }
 
 function assertCanonicalSchemaPath(cleanupPath, metadata) {
+  const isCodexSchema =
+    metadata.kind === 'temp-file' &&
+    metadata.provider === 'codex' &&
+    metadata.reason === 'output-schema';
+  const isGeminiPolicy =
+    metadata.kind === 'temp-file' &&
+    metadata.provider === 'gemini' &&
+    metadata.reason === 'admin-policy';
   if (
-    metadata.kind !== 'temp-file' ||
-    metadata.provider !== 'codex' ||
-    metadata.reason !== 'output-schema' ||
+    (!isCodexSchema && !isGeminiPolicy) ||
     !isAbsolute(cleanupPath) ||
     resolve(cleanupPath) !== cleanupPath
   ) {
-    throw new Error(`Refusing unowned output-schema cleanup: ${cleanupPath}`);
+    throw new Error(
+      `Refusing unowned ${isGeminiPolicy ? 'admin-policy' : 'output-schema'} cleanup: ${cleanupPath}`
+    );
   }
-  const schemaDirectory = dirname(cleanupPath);
-  if (
-    dirname(schemaDirectory) !== resolve(tmpdir()) ||
-    !SCHEMA_DIRECTORY_PATTERN.test(basename(schemaDirectory)) ||
-    !SCHEMA_FILE_PATTERN.test(basename(cleanupPath))
-  ) {
-    throw new Error(`Refusing non-canonical output-schema cleanup: ${cleanupPath}`);
+  const ownedDirectory = dirname(cleanupPath);
+  const matchesOwnedName = isCodexSchema
+    ? SCHEMA_DIRECTORY_PATTERN.test(basename(ownedDirectory)) &&
+      SCHEMA_FILE_PATTERN.test(basename(cleanupPath))
+    : POLICY_DIRECTORY_PATTERN.test(basename(ownedDirectory)) &&
+      POLICY_FILE_PATTERN.test(basename(cleanupPath));
+  if (dirname(ownedDirectory) !== resolve(tmpdir()) || !matchesOwnedName) {
+    throw new Error(
+      `Refusing non-canonical ${isGeminiPolicy ? 'admin-policy' : 'output-schema'} cleanup: ${cleanupPath}`
+    );
   }
 }
 

package/task-lib/commands/run.js

@@ -40,6 +40,7 @@ export async function runTask(prompt, options = {}) {
     jsonSchema,
     mcpConfig: options.mcpConfig,
     silentJsonOutput,
+    structuredOutputRecovery: options.structuredOutputRecovery === true,
   });
 
   console.log(chalk.green(`\n✓ Task spawned: ${chalk.cyan(task.id)}`));

package/task-lib/provider-session-capture.js

@@ -71,7 +71,15 @@ export function createProviderSessionCapture({
   requestedSessionId = null,
   initialSessionId = null,
   initialSessionIdConflict = false,
+  disabled = false,
 }) {
+  if (disabled) {
+    return {
+      captureLine() {},
+      getCompletionError: () => null,
+      getCompletionUpdate: () => ({ resumeIdentityVerified: false }),
+    };
+  }
   let currentSessionId = initialSessionId;
   let sessionIdConflict = initialSessionIdConflict;
   let persistenceError = null;

package/task-lib/runner.js

@@ -116,19 +116,21 @@ function resolveJsonSchema(options, outputFormat) {
 }
 
 function buildProviderOptions(options, runtime, modelSelection) {
+  const structuredOutputRecovery = options.structuredOutputRecovery === true;
   return {
     outputFormat: runtime.outputFormat,
     jsonSchema: runtime.jsonSchema,
     cwd: runtime.cwd,
-    autoApprove: true,
+    autoApprove: !structuredOutputRecovery,
     ...(modelSelection === undefined ? {} : { modelSpec: modelSelection.modelSpec }),
-    ...mcpConfigOption(options),
+    ...(structuredOutputRecovery ? {} : mcpConfigOption(options)),
     ...claudeSettingsFileOption(),
-    ...(options.resume ? { resumeSessionId: options.resume } : {}),
+    ...(!structuredOutputRecovery && options.resume ? { resumeSessionId: options.resume } : {}),
     ...(process.env.ZEROSHOT_OPENCODE_AGENT?.trim()
       ? { agentName: process.env.ZEROSHOT_OPENCODE_AGENT.trim() }
       : {}),
-    ...(options.continue ? { continueSession: true } : {}),
+    ...(!structuredOutputRecovery && options.continue ? { continueSession: true } : {}),
+    ...(structuredOutputRecovery ? { structuredOutputRecovery: true } : {}),
   };
 }
 
@@ -218,10 +220,10 @@ export function buildTaskRecord({
     // accepted that session identity.
     sessionId: null,
     sessionIdConflict: false,
-    requestedResumeSessionId: options.resume || null,
+    requestedResumeSessionId: options.structuredOutputRecovery ? null : options.resume || null,
     // Resumed tasks start fail-closed. Only the watcher terminal transaction
     // may prove that the requested identity completed without conflict.
-    resumeIdentityVerified: !options.resume,
+    resumeIdentityVerified: options.structuredOutputRecovery || !options.resume,
     logFile,
     createdAt: new Date().toISOString(),
     updatedAt: new Date().toISOString(),
@@ -253,6 +255,7 @@ function buildWatcherConfig(outputFormat, jsonSchema, options, providerName, com
     outputFormat,
     jsonSchema,
     silentJsonOutput: options.silentJsonOutput || false,
+    structuredOutputRecovery: options.structuredOutputRecovery === true,
     provider: providerName,
     command: commandSpec.binary,
     env: commandSpec.env || {},

package/task-lib/watcher.js

@@ -64,6 +64,7 @@ const providerSessionCapture = createProviderSessionCapture({
   requestedSessionId: storedTask?.requestedResumeSessionId || null,
   initialSessionId: storedTask?.sessionId || null,
   initialSessionIdConflict: storedTask?.sessionIdConflict === true,
+  disabled: config.structuredOutputRecovery === true,
 });
 
 let crashStarted = false;