@the-open-engine/zeroshot 6.16.0 → 6.18.0

package/src/agent-cli-provider/adapters/opencode.ts

@@ -1,4 +1,8 @@
 import { contractError } from '../contract-errors';
+import { randomUUID } from 'node:crypto';
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
 import { UnsupportedProviderCapabilityError } from '../errors';
 import { appendJsonSchemaPrompt } from '../schema';
 import {
@@ -15,7 +19,7 @@ import {
   type ErrorClassification,
   type OpencodeCliFeatures,
   type OutputEvent,
-  type ProviderAdapter,
+  type StructuredOutputRecoveryAdapter,
   type WarningMetadata,
 } from '../types';
 import {
@@ -49,7 +53,9 @@ function detectCliFeatures(
     supportsCwd: unknown ? false : /--cwd\b/.test(help),
     supportsAutoApprove: false,
     supportsResume: !unknown && /--session\b/.test(help) && /--continue\b/.test(help),
+    supportsAgent: !unknown && /--agent\b/.test(help),
     supportsWebSearch: isCliVersionAtLeast(versionText, '1.0.137'),
+    supportsRecoveryIsolation: isCliVersionAtLeast(versionText, '1.17.20'),
     unknown,
   };
 }
@@ -162,6 +168,82 @@ function buildCommand(context: string, options: BuildProviderCommandOptions = {}
   });
 }
 
+function buildStructuredOutputRecoveryCommand(
+  context: string,
+  options: BuildProviderCommandOptions = {}
+): CommandSpec {
+  const features = optionFeatures(options);
+  if (features.supportsAgent !== true || features.supportsRecoveryIsolation !== true) {
+    throw new UnsupportedProviderCapabilityError(
+      'opencode',
+      'structuredOutputRecovery',
+      'OpenCode structured-output recovery requires CLI evidence for --agent and isolation controls available in OpenCode >= 1.17.20. Upgrade OpenCode before retrying.'
+    );
+  }
+  const agentName = `zeroshot-output-reformatter-${randomUUID()}`;
+  const profile = {
+    description: 'Convert supplied text to schema-valid JSON without external actions',
+    mode: 'primary',
+    permission: { '*': 'deny' },
+    tools: { '*': false },
+  };
+  const recoveryOptions = { ...options };
+  delete recoveryOptions.resumeSessionId;
+  delete recoveryOptions.continueSession;
+  const isolatedConfigHome = fs.mkdtempSync(path.join(os.tmpdir(), 'zeroshot-opencode-config-'));
+
+  try {
+    const spec = buildCommand(context, {
+      ...recoveryOptions,
+      agentName,
+      autoApprove: false,
+      webSearch: false,
+    });
+    const restrictedConfig = {
+      default_agent: agentName,
+      permission: { '*': 'deny' },
+      tools: { '*': false },
+      agent: { [agentName]: profile },
+      mode: { [agentName]: profile },
+      mcp: {},
+      instructions: [],
+      plugin: [],
+      command: {},
+    };
+    return {
+      ...spec,
+      env: {
+        ...spec.env,
+        ZEROSHOT_OPENCODE_AGENT: agentName,
+        XDG_CONFIG_HOME: isolatedConfigHome,
+        OPENCODE_DB: ':memory:',
+        OPENCODE_CONFIG: '',
+        OPENCODE_CONFIG_DIR: isolatedConfigHome,
+        OPENCODE_CONFIG_CONTENT: JSON.stringify(restrictedConfig),
+        OPENCODE_PERMISSION: JSON.stringify({ '*': 'deny' }),
+        OPENCODE_DISABLE_PROJECT_CONFIG: '1',
+        OPENCODE_PURE: '1',
+        OPENCODE_DISABLE_DEFAULT_PLUGINS: '1',
+        OPENCODE_DISABLE_EXTERNAL_SKILLS: '1',
+        OPENCODE_DISABLE_CLAUDE_CODE: '1',
+      },
+      cleanup: [...(spec.cleanup || []), isolatedConfigHome],
+      cleanupMetadata: [
+        ...(spec.cleanupMetadata || []),
+        {
+          kind: 'temp-directory',
+          provider: 'opencode',
+          path: isolatedConfigHome,
+          reason: 'isolated-config',
+        },
+      ],
+    };
+  } catch (error) {
+    fs.rmSync(isolatedConfigHome, { recursive: true, force: true });
+    throw error;
+  }
+}
+
 function parseToolPart(part: Record<string, unknown>): OutputEvent | null {
   const state = getRecord(part, 'state') ?? {};
   const status = getString(state, 'status');
@@ -262,7 +344,7 @@ function classifyError(error: unknown): ErrorClassification {
   return classifyBaseProviderError(error, [], []);
 }
 
-export const opencodeAdapter: ProviderAdapter = {
+export const opencodeAdapter: StructuredOutputRecoveryAdapter = {
   id: 'opencode',
   displayName: 'Opencode',
   binary: 'opencode',
@@ -281,6 +363,7 @@ export const opencodeAdapter: ProviderAdapter = {
   defaultMinLevel: 'level1',
   detectCliFeatures,
   buildCommand,
+  buildStructuredOutputRecoveryCommand,
   extractSessionId,
   parseEvent,
   createParserState: () => createParserState('opencode'),

package/src/agent-cli-provider/contract-options.ts

@@ -24,6 +24,9 @@ const CLI_FEATURE_FIELDS = [
   'supportsModel',
   'supportsEffort',
   'supportsSettings',
+  'supportsTools',
+  'supportsStrictMcpConfig',
+  'supportsNoSessionPersistence',
   'supportsJson',
   'supportsOutputSchema',
   'supportsDir',
@@ -31,13 +34,26 @@ const CLI_FEATURE_FIELDS = [
   'supportsConfigOverride',
   'supportsSkipGitRepoCheck',
   'supportsVariant',
+  'supportsSandbox',
+  'supportsEphemeral',
+  'supportsIgnoreUserConfig',
+  'supportsIgnoreRules',
+  'supportsStrictConfig',
   'supportsJsonMode',
+  'supportsAdminPolicy',
   'supportsNoSession',
+  'supportsAgent',
+  'supportsRecoveryIsolation',
   'supportsNoExtensions',
   'supportsNoSkills',
   'supportsNoPromptTemplates',
   'supportsNoContextFiles',
   'supportsNoApprove',
+  'supportsModeJson',
+  'supportsPrint',
+  'supportsThinking',
+  'supportsNoRules',
+  'supportsNoTitle',
   'supportsJsonOutput',
   'supportsAllowAll',
   'supportsNoAskUser',
@@ -224,6 +240,11 @@ function normalizeBuildOptions(value: Record<string, unknown>): BuildProviderCom
     'strictSchema',
     optionalBooleanValue(value.strictSchema, 'options.strictSchema')
   );
+  addDefined(
+    result,
+    'structuredOutputRecovery',
+    optionalBooleanValue(value.structuredOutputRecovery, 'options.structuredOutputRecovery')
+  );
   addDefined(
     result,
     'gateway',

package/src/agent-cli-provider/index.ts

@@ -53,6 +53,7 @@ export {
   providerRegistry,
   resolveProviderCommand,
   supportsProviderCapability,
+  supportsProviderOutputReformatting,
 } from './provider-registry';
 
 export type {
@@ -78,6 +79,7 @@ export type {
   ModelCatalogEntry,
   ModelLevel,
   ModelSpec,
+  OmpCliFeatures,
   OpencodeCliFeatures,
   OutputEvent,
   OutputFormat,
@@ -92,6 +94,9 @@ export type {
   ProviderCliFeatures,
   ProviderId,
   ProviderRegistryEntry,
+  StructuredOutputRecoveryAdapter,
+  StructuredOutputProviderRegistryEntry,
+  UnstructuredOutputProviderRegistryEntry,
   RedactionMetadata,
   ReasoningEffort,
   ResolvedGatewayBuildOptions,

package/src/agent-cli-provider/provider-registry.ts

@@ -5,9 +5,10 @@ import { copilotAdapter } from './adapters/copilot';
 import { gatewayAdapter, gatewaySettingsDefaults, validateGatewaySettings } from './adapters/gateway';
 import { geminiAdapter } from './adapters/gemini';
 import { opencodeAdapter } from './adapters/opencode';
+import { ompAdapter } from './adapters/omp';
 import { piAdapter } from './adapters/pi';
 import { resolveClaudeCommand } from './claude-command';
-import type { ModelLevel, ProviderAdapter } from './types';
+import type { ModelLevel, ProviderAdapter, StructuredOutputRecoveryAdapter } from './types';
 
 export type ProviderCapabilityState = boolean | 'experimental';
 
@@ -68,7 +69,7 @@ export interface ProviderDockerMetadata {
   readonly install?: string;
 }
 
-export interface ProviderRegistryEntry {
+interface ProviderRegistryEntryBase {
   readonly id: string;
   readonly aliases: readonly string[];
   readonly displayName: string;
@@ -83,7 +84,6 @@ export interface ProviderRegistryEntry {
   readonly settingsDefaults?: Readonly<Record<string, unknown>>;
   readonly settingsValidator?: (settings: Record<string, unknown>) => string | null;
   readonly availabilityProbe?: 'command' | 'help-or-version';
-  readonly capabilities: ProviderCapabilities;
   readonly docs: ProviderDocsMetadata;
   readonly docker: ProviderDockerMetadata;
   readonly defaultLevels: Readonly<{
@@ -91,9 +91,26 @@ export interface ProviderRegistryEntry {
     readonly default: ModelLevel;
     readonly max: ModelLevel;
   }>;
+}
+
+export interface StructuredOutputProviderRegistryEntry extends ProviderRegistryEntryBase {
+  readonly capabilities: Omit<ProviderCapabilities, 'jsonSchema'> & {
+    readonly jsonSchema: true | 'experimental';
+  };
+  readonly adapter: StructuredOutputRecoveryAdapter;
+}
+
+export interface UnstructuredOutputProviderRegistryEntry extends ProviderRegistryEntryBase {
+  readonly capabilities: Omit<ProviderCapabilities, 'jsonSchema'> & {
+    readonly jsonSchema: false;
+  };
   readonly adapter: ProviderAdapter;
 }
 
+export type ProviderRegistryEntry =
+  | StructuredOutputProviderRegistryEntry
+  | UnstructuredOutputProviderRegistryEntry;
+
 const STANDARD_CAPABILITIES: Readonly<
   Pick<
     ProviderCapabilities,
@@ -400,6 +417,44 @@ export const providerRegistry = [
     },
     adapter: piAdapter,
   },
+  {
+    id: 'omp',
+    aliases: [],
+    displayName: 'OMP',
+    binary: 'omp',
+    command: { kind: 'fixed', command: 'omp', args: [] },
+    invoke: SPAWN_INVOKE,
+    installInstructions: 'npm install -g --ignore-scripts @oh-my-pi/pi-coding-agent',
+    authInstructions: 'omp\n/login',
+    credentialPaths: ['~/.omp'],
+    credentialEnvKeys: ompAdapter.credentialEnvKeys,
+    settingsFields: [],
+    availabilityProbe: 'help-or-version',
+    capabilities: {
+      ...STANDARD_CAPABILITIES,
+      mcpServers: false,
+      jsonSchema: false,
+      reasoningEffort: true,
+    },
+    docs: {
+      label: 'OMP',
+      setupHeading: 'OMP Setup',
+    },
+    docker: {
+      mount: {
+        host: '~/.omp',
+        container: '$HOME/.omp',
+        readonly: true,
+      },
+      envPassthrough: [],
+    },
+    defaultLevels: {
+      min: ompAdapter.defaultMinLevel,
+      default: ompAdapter.defaultLevel,
+      max: ompAdapter.defaultMaxLevel,
+    },
+    adapter: ompAdapter,
+  },
   {
     id: 'kiro',
     aliases: [],
@@ -551,3 +606,7 @@ export function supportsProviderCapability(
 ): boolean {
   return getProviderRegistryEntry(name).capabilities[capability] === true;
 }
+
+export function supportsProviderOutputReformatting(name: string): boolean {
+  return getProviderRegistryEntry(name).capabilities.jsonSchema !== false;
+}

package/src/agent-cli-provider/single-agent-runtime.ts

@@ -6,6 +6,7 @@ import {
   getProviderRegistryEntry,
   resolveProviderCommand,
   supportsProviderCapability,
+  supportsProviderOutputReformatting,
 } from './provider-registry';
 import type {
   BuildProviderCommandOptions,
@@ -16,6 +17,7 @@ import type {
   ModelLevel,
   ModelSpec,
   ProviderAdapter,
+  StructuredOutputRecoveryAdapter,
   ProviderCliFeatures,
   ProviderId,
   ResolvedGatewayBuildOptions,
@@ -106,7 +108,9 @@ export function prepareSingleAgentProviderCommand(
     adapter.id,
     baseOptions.cwd ?? process.cwd()
   );
-  const requestedWebSearch = baseOptions.webSearch ?? providerSettings.webSearch;
+  const requestedWebSearch = baseOptions.structuredOutputRecovery
+    ? recoveryWebSearchOption(adapter)
+    : (baseOptions.webSearch ?? providerSettings.webSearch);
   assertWebSearchDeclared(adapter.id, requestedWebSearch);
   const cliFeatures = resolveRuntimeCliFeatures(
     adapter.id,
@@ -125,10 +129,37 @@ export function prepareSingleAgentProviderCommand(
     configuration: {
       webSearch: webSearchAttestation(options),
     },
-    commandSpec: adapter.buildCommand(input.context, options),
+    commandSpec: buildRuntimeCommand(adapter, input.context, options),
   };
 }
 
+function buildRuntimeCommand(
+  adapter: ProviderAdapter,
+  context: string,
+  options: BuildProviderCommandOptions
+): CommandSpec {
+  if (options.structuredOutputRecovery !== true) {
+    return adapter.buildCommand(context, options);
+  }
+  if (!supportsProviderOutputReformatting(adapter.id)) {
+    throw new UnsupportedProviderCapabilityError(
+      adapter.id,
+      'structuredOutputRecovery',
+      `Provider ${adapter.id} does not advertise structured-output recovery.`
+    );
+  }
+  const recoveryAdapter = adapter as ProviderAdapter &
+    Partial<StructuredOutputRecoveryAdapter>;
+  if (typeof recoveryAdapter.buildStructuredOutputRecoveryCommand !== 'function') {
+    throw new UnsupportedProviderCapabilityError(
+      adapter.id,
+      'structuredOutputRecovery',
+      `Provider ${adapter.id} advertises structured output without a recovery adapter. Upgrade Zeroshot before retrying.`
+    );
+  }
+  return recoveryAdapter.buildStructuredOutputRecoveryCommand(context, options);
+}
+
 export function detectRuntimeProviderCliFeatures(provider: string): ProviderCliFeatures {
   return probeRuntimeProviderCli(provider).capabilities;
 }
@@ -262,15 +293,26 @@ function buildRuntimeOptions(
     providerSettings,
     modelSpec
   );
-  const webSearch = baseOptions.webSearch ?? providerSettings.webSearch;
+  const webSearch = baseOptions.structuredOutputRecovery
+    ? recoveryWebSearchOption(adapter)
+    : (baseOptions.webSearch ?? providerSettings.webSearch);
   assertWebSearchDeclared(adapter.id, webSearch);
-  const resolved = {
+  const baseResolved = {
     ...baseOptions,
     modelSpec,
     ...(gateway === undefined ? {} : { gateway }),
     ...(webSearch === undefined ? {} : { webSearch }),
     cliFeatures: runtime.cliFeatures,
   };
+  const resolved = { ...baseResolved };
+  if (baseOptions.structuredOutputRecovery) {
+    delete resolved.resumeSessionId;
+    delete resolved.continueSession;
+    delete resolved.mcpConfig;
+    resolved.autoApprove = false;
+    if (recoveryWebSearchOption(adapter) === undefined) delete resolved.webSearch;
+    else resolved.webSearch = false;
+  }
   if (baseOptions.jsonSchema && !supportsProviderCapability(adapter.id, 'jsonSchema')) {
     if (!shouldIncludeAuthEnv(baseOptions, runtime.authEnv)) {
       return { ...resolved, strictSchema: false };
@@ -281,6 +323,10 @@ function buildRuntimeOptions(
   return { ...resolved, authEnv: runtime.authEnv };
 }
 
+function recoveryWebSearchOption(adapter: ProviderAdapter): false | undefined {
+  return getProviderRegistryEntry(adapter.id).capabilities.webSearch === false ? undefined : false;
+}
+
 function resolveRuntimeGatewayOptions(
   provider: ProviderId,
   baseOptions: BuildProviderCommandOptions,

package/src/agent-cli-provider/types.ts

@@ -9,6 +9,8 @@ import type {
   ProviderDocsMetadata,
   ProviderInvokeSpec,
   ProviderRegistryEntry,
+  StructuredOutputProviderRegistryEntry,
+  UnstructuredOutputProviderRegistryEntry,
 } from './provider-registry';
 
 export type ProviderId = (typeof providerIds)[number];
@@ -27,8 +29,9 @@ export type {
   ProviderDocsMetadata,
   ProviderInvokeSpec,
   ProviderRegistryEntry,
+  StructuredOutputProviderRegistryEntry,
+  UnstructuredOutputProviderRegistryEntry,
 };
-
 export interface AgentCliProviderHelperMetadata {
   readonly packageName: '@the-open-engine/zeroshot';
   readonly buildOutputDir: 'lib/agent-cli-provider';
@@ -105,6 +108,9 @@ export interface ClaudeCliFeatures extends BaseCliFeatures {
   readonly supportsSettings: boolean;
   readonly supportsMcpConfig: boolean;
   readonly supportsResume: boolean;
+  readonly supportsTools: boolean;
+  readonly supportsStrictMcpConfig: boolean;
+  readonly supportsNoSessionPersistence: boolean;
 }
 
 export interface CodexCliFeatures extends BaseCliFeatures {
@@ -118,6 +124,11 @@ export interface CodexCliFeatures extends BaseCliFeatures {
   readonly supportsSkipGitRepoCheck: boolean;
   readonly supportsResume: boolean;
   readonly supportsWebSearch: boolean;
+  readonly supportsSandbox: boolean;
+  readonly supportsEphemeral: boolean;
+  readonly supportsIgnoreUserConfig: boolean;
+  readonly supportsIgnoreRules: boolean;
+  readonly supportsStrictConfig: boolean;
 }
 
 export interface GeminiCliFeatures extends BaseCliFeatures {
@@ -126,6 +137,7 @@ export interface GeminiCliFeatures extends BaseCliFeatures {
   readonly supportsAutoApprove: boolean;
   readonly supportsCwd: boolean;
   readonly supportsModel: boolean;
+  readonly supportsAdminPolicy: boolean;
 }
 
 export interface OpencodeCliFeatures extends BaseCliFeatures {
@@ -138,6 +150,8 @@ export interface OpencodeCliFeatures extends BaseCliFeatures {
   readonly supportsAutoApprove: false;
   readonly supportsResume: boolean;
   readonly supportsWebSearch: boolean;
+  readonly supportsAgent: boolean;
+  readonly supportsRecoveryIsolation: boolean;
 }
 
 export interface PiCliFeatures extends BaseCliFeatures {
@@ -152,6 +166,20 @@ export interface PiCliFeatures extends BaseCliFeatures {
   readonly supportsNoApprove: boolean;
 }
 
+export interface OmpCliFeatures extends BaseCliFeatures {
+  readonly provider: 'omp';
+  readonly supportsModeJson: boolean;
+  readonly supportsPrint: boolean;
+  readonly supportsCwd: boolean;
+  readonly supportsAutoApprove: boolean;
+  readonly supportsModel: boolean;
+  readonly supportsThinking: boolean;
+  readonly supportsNoExtensions: boolean;
+  readonly supportsNoSkills: boolean;
+  readonly supportsNoRules: boolean;
+  readonly supportsNoTitle: boolean;
+}
+
 export interface CopilotCliFeatures extends BaseCliFeatures {
   readonly provider: 'copilot';
   readonly supportsJsonOutput: boolean;
@@ -188,6 +216,7 @@ export type ProviderCliFeatures =
   | GeminiCliFeatures
   | OpencodeCliFeatures
   | PiCliFeatures
+  | OmpCliFeatures
   | CopilotCliFeatures
   | GatewayCliFeatures
   | AcpCliFeatures;
@@ -200,6 +229,9 @@ export interface CliFeatureOverrides {
   readonly supportsIncludePartials?: boolean;
   readonly supportsVerbose?: boolean;
   readonly supportsModel?: boolean;
+  readonly supportsTools?: boolean;
+  readonly supportsStrictMcpConfig?: boolean;
+  readonly supportsNoSessionPersistence?: boolean;
   readonly supportsEffort?: boolean;
   readonly supportsSettings?: boolean;
   readonly supportsJson?: boolean;
@@ -208,14 +240,27 @@ export interface CliFeatureOverrides {
   readonly supportsCwd?: boolean;
   readonly supportsConfigOverride?: boolean;
   readonly supportsSkipGitRepoCheck?: boolean;
+  readonly supportsSandbox?: boolean;
+  readonly supportsEphemeral?: boolean;
+  readonly supportsIgnoreUserConfig?: boolean;
+  readonly supportsIgnoreRules?: boolean;
+  readonly supportsStrictConfig?: boolean;
   readonly supportsVariant?: boolean;
+  readonly supportsAdminPolicy?: boolean;
   readonly supportsJsonMode?: boolean;
   readonly supportsNoSession?: boolean;
   readonly supportsNoExtensions?: boolean;
   readonly supportsNoSkills?: boolean;
   readonly supportsNoPromptTemplates?: boolean;
+  readonly supportsAgent?: boolean;
+  readonly supportsRecoveryIsolation?: boolean;
   readonly supportsNoContextFiles?: boolean;
   readonly supportsNoApprove?: boolean;
+  readonly supportsModeJson?: boolean;
+  readonly supportsPrint?: boolean;
+  readonly supportsThinking?: boolean;
+  readonly supportsNoRules?: boolean;
+  readonly supportsNoTitle?: boolean;
   readonly supportsJsonOutput?: boolean;
   readonly supportsAllowAll?: boolean;
   readonly supportsNoAskUser?: boolean;
@@ -242,7 +287,7 @@ export interface CleanupMetadata {
   readonly kind: 'temp-file' | 'temp-directory';
   readonly provider: ProviderId;
   readonly path: string;
-  readonly reason: 'output-schema' | 'settings-overlay';
+  readonly reason: 'output-schema' | 'settings-overlay' | 'admin-policy' | 'isolated-config';
 }
 
 export interface WarningMetadata {
@@ -292,6 +337,8 @@ export interface BuildProviderCommandOptions {
   // one variadic `--mcp-config` followed by file paths; adapters such as Copilot accept repeated
   // flags with inline JSON so configs survive container path translation.
   readonly mcpConfig?: readonly string[];
+  /** Internal profile for provider-neutral structured-output correction turns. */
+  readonly structuredOutputRecovery?: boolean;
 }
 
 export interface TextEvent {
@@ -395,6 +442,13 @@ export interface ProviderAdapter {
   classifyError(error: unknown): ErrorClassification;
 }
 
+export interface StructuredOutputRecoveryAdapter extends ProviderAdapter {
+  buildStructuredOutputRecoveryCommand(
+    context: string,
+    options?: BuildProviderCommandOptions
+  ): CommandSpec;
+}
+
 export class InvalidProviderModelError extends Error {
   readonly permanent = true;
 

package/src/agent-wrapper.js

@@ -586,8 +586,8 @@ class AgentWrapper {
    * Falls back to reformatting if extraction fails
    * @private
    */
-  _parseResultOutput(output) {
-    return parseResultOutput(this, output);
+  _parseResultOutput(output, options = {}) {
+    return parseResultOutput(this, output, options);
   }
 
   /**

package/src/cluster/errors.ts

@@ -13,6 +13,7 @@ export class ClusterInternalError extends ClusterError {}
 export class ClusterProtocolError extends ClusterError {}
 export class ClusterTransportError extends ClusterError {}
 export class ClusterTimeoutError extends ClusterError {}
+export class ClusterRequestError extends ClusterError {}
 
 export function requestAbortError(method: string): DOMException {
   return new DOMException(

package/src/cluster/index.ts

@@ -5,11 +5,15 @@ export {
   ClusterError,
   ClusterInternalError,
   ClusterProtocolError,
+  ClusterRequestError,
   ClusterRpcError,
   ClusterStateError,
   ClusterTimeoutError,
   ClusterTransportError,
 } from './errors.js';
+export { assertGraphProfile, assertGraphProfileSupported, assertGraphSpec } from './validators.js';
+export * from './payload-value.js';
+export * from './json-source.js';
 export { CONNECTION_TRANSITIONS, PROTOCOL_DIAGNOSTIC_CAPACITY, Connection } from './connection.js';
 export type {
   CallOptions,

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',
+    );
+  }
+}