@the-open-engine/zeroshot 5.4.0

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

@@ -0,0 +1,167 @@
+import { getProviderAdapter } from './adapters';
+import { getString, isRecord, parseJson } from './json';
+import { mergeRedactions } from './redaction';
+import { requestOptions } from './contract-options';
+import { prepareSingleAgentProviderCommand } from './single-agent-runtime';
+import type { BuildProviderCommandOptions, CommandSpec, ProviderAdapter } from './types';
+export {
+  contractError,
+  ContractRequestError,
+  optionalNumber,
+  optionalString,
+  requiredString,
+} from './contract-errors';
+export {
+  collectCommandSpecEnv,
+  commandRedactions,
+  envRedactions,
+  mergeEnvForRedaction,
+  providerCredentialEnv,
+  stringRecord,
+} from './contract-env';
+import { contractError, optionalString, requiredString } from './contract-errors';
+import { envRedactions, stringRecord } from './contract-env';
+
+export interface RequestData {
+  readonly raw: Record<string, unknown>;
+  readonly command: string | null;
+  readonly provider: string | null;
+  readonly env: Readonly<Record<string, string>>;
+}
+
+export function adapterForProvider(provider: string | null): ProviderAdapter {
+  if (provider === null || provider.length === 0) {
+    throw contractError({
+      code: 'missing-field',
+      message: 'provider is required.',
+      exitCode: 2,
+      field: 'provider',
+    });
+  }
+  try {
+    return getProviderAdapter(provider);
+  } catch {
+    throw contractError({
+      code: 'unknown-provider',
+      message: `Unknown provider: ${provider}.`,
+      exitCode: 4,
+      field: 'provider',
+    });
+  }
+}
+
+function mergeCommandSpec(
+  commandSpec: CommandSpec,
+  env: Readonly<Record<string, string>>
+): CommandSpec {
+  const mergedEnv = { ...commandSpec.env, ...env };
+  return {
+    ...commandSpec,
+    env: mergedEnv,
+    redactions: mergeRedactions(commandSpec.redactions, envRedactions(mergedEnv)),
+  };
+}
+
+function buildOptions(request: RequestData): BuildProviderCommandOptions {
+  const options = requestOptions(request.raw.options);
+  const cwd = optionalString(request.raw, 'cwd');
+  if (cwd === undefined || options.cwd !== undefined) return options;
+  return { ...options, cwd };
+}
+
+export function buildCommandSpec(request: RequestData): {
+  readonly adapter: ProviderAdapter;
+  readonly commandSpec: CommandSpec;
+  readonly options: BuildProviderCommandOptions;
+} {
+  const adapter = adapterForProvider(request.provider);
+  const context = requiredString(request.raw, 'context');
+  const options = buildOptions(request);
+  const prepared = prepareSingleAgentProviderCommand({
+    provider: adapter.id,
+    context,
+    options,
+  });
+  return {
+    adapter: prepared.adapter,
+    options: prepared.options,
+    commandSpec: mergeCommandSpec(prepared.commandSpec, request.env),
+  };
+}
+
+export function schemaMode(options: BuildProviderCommandOptions): string {
+  if (!options.jsonSchema) return 'none';
+  return options.strictSchema === false ? 'prompt' : 'strict';
+}
+
+export function validateRequest(input: string, schemaVersion: 1): RequestData {
+  const parsed = parseRequestObject(input);
+  assertSchemaVersion(parsed, schemaVersion);
+  const command = requiredCommand(parsed);
+  return {
+    raw: parsed,
+    command,
+    provider: getString(parsed, 'provider'),
+    env: requestEnv(parsed),
+  };
+}
+
+const KNOWN_COMMANDS: readonly string[] = [
+  'probe',
+  'build-command',
+  'parse-output',
+  'classify-error',
+  'invoke',
+];
+
+function parseRequestObject(input: string): Record<string, unknown> {
+  let parsed: unknown;
+  try {
+    parsed = parseJson(input);
+  } catch {
+    throw contractError({
+      code: 'malformed-json',
+      message: 'Request body must be valid JSON.',
+      exitCode: 2,
+    });
+  }
+  if (isRecord(parsed)) return parsed;
+  throw contractError({
+    code: 'invalid-request',
+    message: 'Request body must be a JSON object.',
+    exitCode: 2,
+  });
+}
+
+function assertSchemaVersion(parsed: Record<string, unknown>, schemaVersion: 1): void {
+  if (parsed.schemaVersion === schemaVersion) return;
+  throw contractError({
+    code: 'unsupported-schema-version',
+    message: 'schemaVersion must be 1.',
+    exitCode: 2,
+    field: 'schemaVersion',
+  });
+}
+
+function requiredCommand(parsed: Record<string, unknown>): string {
+  const command = getString(parsed, 'command');
+  if (command === null) {
+    throw contractError({
+      code: 'missing-field',
+      message: 'command is required.',
+      exitCode: 2,
+      field: 'command',
+    });
+  }
+  if (KNOWN_COMMANDS.includes(command)) return command;
+  throw contractError({
+    code: 'unknown-command',
+    message: `Unknown command: ${command}.`,
+    exitCode: 3,
+    field: 'command',
+  });
+}
+
+function requestEnv(parsed: Record<string, unknown>): Readonly<Record<string, string>> {
+  return stringRecord(parsed.env, 'env');
+}

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

@@ -0,0 +1,56 @@
+import { dispatchRequest } from './contract-actions';
+import {
+  fallbackErrorEnvelope,
+  requestEnvelopeData,
+  requestErrorFromUnknown,
+} from './contract-fallback';
+import { finalizeEnvelope, providerExecutableSchemaVersion } from './contract-envelope';
+import { validateRequest } from './contract-support';
+import { spawnProcessRunner, type ProcessRunner } from './process-runner';
+import type { ContractEnvelope } from './contract-envelope';
+
+export {
+  providerExecutableSchemaVersion,
+  type ContractEnvelope,
+  type ContractErrorEnvelope,
+  type ContractErrorObject,
+  type ContractEvidence,
+  type ContractSuccessEnvelope,
+} from './contract-envelope';
+
+export type ProviderExecutableCommand =
+  | 'probe'
+  | 'build-command'
+  | 'parse-output'
+  | 'classify-error'
+  | 'invoke';
+
+export interface ProviderExecutableResponse {
+  readonly envelope: ContractEnvelope;
+  readonly exitCode: number;
+}
+
+export interface ProviderExecutableOptions {
+  readonly runner?: ProcessRunner;
+}
+
+export async function runProviderExecutable(
+  input: string,
+  options: ProviderExecutableOptions = {}
+): Promise<ProviderExecutableResponse> {
+  const fallback = requestEnvelopeData(input);
+  try {
+    const request = validateRequest(input, providerExecutableSchemaVersion);
+    const envelope = await dispatchRequest(request, options.runner ?? spawnProcessRunner());
+    return {
+      envelope: finalizeEnvelope(envelope, request.env),
+      exitCode: 0,
+    };
+  } catch (error) {
+    const requestError = requestErrorFromUnknown(error);
+    return {
+      envelope: finalizeEnvelope(fallbackErrorEnvelope(fallback, requestError), fallback.env),
+      exitCode: requestError.exitCode,
+    };
+  }
+}

package/src/agent-cli-provider/env-safety.ts

@@ -0,0 +1,82 @@
+const EXECUTABLE_RESOLUTION_ENV_KEYS = new Set(['path', 'pathext']);
+const PROCESS_CONTROL_ENV_KEYS = new Set([
+  '_java_options',
+  'bash_env',
+  'bun_options',
+  'bun_preload',
+  'classpath',
+  'env',
+  'java_tool_options',
+  'jdk_java_options',
+  'ld_library_path',
+  'ld_preload',
+  'lua_cpath',
+  'lua_init',
+  'lua_path',
+  'node_options',
+  'node_path',
+  'npm_config_node_options',
+  'perl5lib',
+  'perl5opt',
+  'pythonhome',
+  'pythonpath',
+  'pythonstartup',
+  'rubylib',
+  'rubyopt',
+  'zshenv',
+]);
+const PROCESS_CONTROL_ENV_PREFIXES = ['dyld_', 'ld_', 'node_'];
+
+type EnvRecord = Readonly<Record<string, string | undefined>>;
+
+export function isExecutableResolutionEnvKey(key: string): boolean {
+  return EXECUTABLE_RESOLUTION_ENV_KEYS.has(key.toLowerCase());
+}
+
+export function isProcessControlEnvKey(key: string): boolean {
+  const normalized = key.toLowerCase();
+  if (PROCESS_CONTROL_ENV_KEYS.has(normalized)) return true;
+  return PROCESS_CONTROL_ENV_PREFIXES.some((prefix) => normalized.startsWith(prefix));
+}
+
+export function isUnsafeProviderEnvKey(key: string): boolean {
+  return isExecutableResolutionEnvKey(key) || isProcessControlEnvKey(key);
+}
+
+export function findExecutableResolutionEnvKey(env: EnvRecord): string | null {
+  for (const key of Object.keys(env)) {
+    if (isExecutableResolutionEnvKey(key)) return key;
+  }
+  return null;
+}
+
+export function findUnsafeProviderEnvKey(env: EnvRecord): string | null {
+  for (const key of Object.keys(env)) {
+    if (isUnsafeProviderEnvKey(key)) return key;
+  }
+  return null;
+}
+
+function omitEnvKeys(
+  env: EnvRecord,
+  isUnsafe: (key: string) => boolean
+): Readonly<Record<string, string>> {
+  const result: Record<string, string> = {};
+  for (const [key, value] of Object.entries(env)) {
+    if (value === undefined || isUnsafe(key)) continue;
+    result[key] = value;
+  }
+  return result;
+}
+
+export function omitExecutableResolutionEnv(env: EnvRecord): Readonly<Record<string, string>> {
+  return omitEnvKeys(env, isExecutableResolutionEnvKey);
+}
+
+export function omitProcessControlEnv(env: EnvRecord): Readonly<Record<string, string>> {
+  return omitEnvKeys(env, isProcessControlEnvKey);
+}
+
+export function omitUnsafeProviderEnv(env: EnvRecord): Readonly<Record<string, string>> {
+  return omitEnvKeys(env, isUnsafeProviderEnvKey);
+}

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

@@ -0,0 +1,122 @@
+import { getNumber, getRecord, getString, isRecord, unknownToMessage } from './json';
+import type { ErrorClassification } from './types';
+
+const BASE_RETRYABLE_PATTERNS: readonly RegExp[] = [
+  /rate.?limit/i,
+  /\b429\b/i,
+  /too many requests/i,
+  /overloaded/i,
+  /temporar(?:y|ily)/i,
+  /unavailable/i,
+  /try again/i,
+  /timeout/i,
+  /timed out/i,
+  /deadline exceeded/i,
+  /connection (?:reset|refused)/i,
+  /\b(econnreset|econnrefused|etimedout|eai_again)\b/i,
+  /network/i,
+];
+
+const BASE_PERMANENT_PATTERNS: readonly RegExp[] = [
+  /invalid[_ -]?api[_ -]?key/i,
+  /api[_ -]?key.*invalid/i,
+  /unauthorized/i,
+  /forbidden/i,
+  /authentication/i,
+  /permission denied/i,
+  /invalid argument/i,
+  /unknown option/i,
+  /\busage:\b/i,
+  /command not found/i,
+  /not recognized as an internal or external command/i,
+  /model not found/i,
+  /context length exceeded/i,
+  /insufficient quota/i,
+];
+
+function getStatus(error: unknown): number | null {
+  if (!isRecord(error)) return null;
+  const directStatus = getNumber(error, 'status') ?? getNumber(error, 'statusCode');
+  if (directStatus !== null) return directStatus;
+
+  const response = getRecord(error, 'response');
+  if (response === null) return null;
+  return getNumber(response, 'status') ?? getNumber(response, 'statusCode');
+}
+
+function getCode(error: unknown): string | null {
+  if (!isRecord(error)) return null;
+  return getString(error, 'code');
+}
+
+function firstMatchedPattern(patterns: readonly RegExp[], message: string): RegExp | null {
+  for (const pattern of patterns) {
+    if (pattern.test(message)) return pattern;
+  }
+  return null;
+}
+
+export function baseRetryableErrorPatterns(): readonly RegExp[] {
+  return BASE_RETRYABLE_PATTERNS;
+}
+
+export function basePermanentErrorPatterns(): readonly RegExp[] {
+  return BASE_PERMANENT_PATTERNS;
+}
+
+export function classifyErrorWithPatterns(
+  error: unknown,
+  retryablePatterns: readonly RegExp[],
+  permanentPatterns: readonly RegExp[]
+): ErrorClassification {
+  const statusClassification = classifyStatus(getStatus(error));
+  if (statusClassification !== null) return statusClassification;
+
+  const codeClassification = classifyCode(getCode(error));
+  if (codeClassification !== null) return codeClassification;
+
+  const message = unknownToMessage(error).trim();
+  if (!message) return { retryable: true, kind: 'unknown-retryable' };
+  return classifyMessage(message, retryablePatterns, permanentPatterns);
+}
+
+function classifyStatus(status: number | null): ErrorClassification | null {
+  if (typeof status !== 'number') return null;
+  if (status === 429 || status >= 500) return { retryable: true, kind: 'status-retryable' };
+  if (status >= 400 && status < 500) return { retryable: false, kind: 'status-permanent' };
+  return null;
+}
+
+function classifyCode(code: string | null): ErrorClassification | null {
+  if (typeof code !== 'string') return null;
+  if (/\b(econnreset|econnrefused|etimedout|eai_again)\b/i.test(code)) {
+    return { retryable: true, kind: 'code-retryable', matchedPattern: 'network-code' };
+  }
+  return null;
+}
+
+function classifyMessage(
+  message: string,
+  retryablePatterns: readonly RegExp[],
+  permanentPatterns: readonly RegExp[]
+): ErrorClassification {
+  const permanent = firstMatchedPattern(permanentPatterns, message);
+  if (permanent !== null) {
+    return {
+      retryable: false,
+      kind: 'permanent-pattern',
+      matchedPattern: permanent.source,
+    };
+  }
+
+  const retryable = firstMatchedPattern(retryablePatterns, message);
+  if (retryable !== null) {
+    return {
+      retryable: true,
+      kind: 'retryable-pattern',
+      matchedPattern: retryable.source,
+    };
+  }
+
+  return { retryable: true, kind: 'unknown-retryable' };
+}

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

@@ -0,0 +1,24 @@
+#!/usr/bin/env node
+import { runProviderExecutable } from './contract';
+import { spawnProcessRunner } from './process-runner';
+import { stringifyJson, unknownToMessage } from './json';
+
+async function readStdin(): Promise<string> {
+  const chunks: Buffer[] = [];
+  for await (const chunk of process.stdin) {
+    chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(String(chunk)));
+  }
+  return Buffer.concat(chunks).toString('utf8');
+}
+
+async function main(): Promise<void> {
+  const input = await readStdin();
+  const response = await runProviderExecutable(input, { runner: spawnProcessRunner() });
+  process.stdout.write(`${stringifyJson(response.envelope)}\n`);
+  process.exitCode = response.exitCode;
+}
+
+main().catch((error: unknown) => {
+  process.stderr.write(`${unknownToMessage(error)}\n`);
+  process.exitCode = 5;
+});

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

@@ -0,0 +1,83 @@
+export {
+  buildProviderCommand,
+  classifyProviderError,
+  detectProviderFatalError,
+  detectProviderStreamingModeError,
+  getProviderAdapter,
+  listProviderAdapters,
+  parseProviderChunk,
+  recoverProviderStructuredOutput,
+  resolveModelSpec,
+  supportsProviderStructuredOutputRecovery,
+  NO_MESSAGES_RETURNED,
+  STREAMING_MODE_ERROR,
+  type StreamingModeError,
+  type StructuredOutputRecovery,
+} from './adapters';
+export {
+  providerExecutableSchemaVersion,
+  runProviderExecutable,
+  type ContractEnvelope,
+  type ContractErrorEnvelope,
+  type ContractErrorObject,
+  type ContractEvidence,
+  type ContractSuccessEnvelope,
+  type ProviderExecutableCommand,
+  type ProviderExecutableOptions,
+  type ProviderExecutableResponse,
+} from './contract';
+export {
+  spawnProcessRunner,
+  type ProcessResult,
+  type ProcessRunner,
+  type ProcessRunnerOptions,
+} from './process-runner';
+export {
+  detectRuntimeProviderCliFeatures,
+  prepareSingleAgentProviderCommand,
+  type PreparedSingleAgentProviderCommand,
+  type SingleAgentProviderCommandInput,
+} from './single-agent-runtime';
+
+export type {
+  AgentCliProviderHelperMetadata,
+  BuildProviderCommandOptions,
+  CleanupMetadata,
+  CliFeatureOverrides,
+  ClaudeCliFeatures,
+  CodexCliFeatures,
+  CommandSpec,
+  ErrorClassification,
+  ErrorClassificationKind,
+  GeminiCliFeatures,
+  KnownProviderName,
+  LevelModelSpec,
+  LevelOverrides,
+  ModelCatalogEntry,
+  ModelLevel,
+  ModelSpec,
+  OpencodeCliFeatures,
+  OutputEvent,
+  OutputFormat,
+  ProviderAdapter,
+  ProviderAlias,
+  ProviderCliFeatures,
+  ProviderId,
+  RedactionMetadata,
+  ResolvedModelSpec,
+  ResultEvent,
+  TextEvent,
+  ThinkingEvent,
+  ToolCallEvent,
+  ToolResultEvent,
+  WarningMetadata,
+} from './types';
+
+import type { AgentCliProviderHelperMetadata } from './types';
+
+export const agentCliProviderHelperMetadata: Readonly<AgentCliProviderHelperMetadata> = {
+  packageName: '@the-open-engine/zeroshot',
+  buildOutputDir: 'lib/agent-cli-provider',
+  contractVersion: 1,
+  adapterVersion: '1',
+};

package/src/agent-cli-provider/invoke-evidence.ts

@@ -0,0 +1,18 @@
+import { classifyProviderError } from './adapters';
+import type { ProcessResult } from './process-runner';
+import type { ErrorClassification, ProviderAdapter } from './types';
+
+export function providerFailureClassification(
+  adapter: ProviderAdapter,
+  result: ProcessResult
+): ErrorClassification | null {
+  if (result.timedOut) {
+    return classifyProviderError(adapter.id, {
+      message: `Provider timed out after ${result.timeoutMs ?? 'unknown'}ms`,
+    });
+  }
+  if (result.exitCode === 0 && result.signal === null) return null;
+  return classifyProviderError(adapter.id, {
+    message: result.stderr || result.stdout || `Provider exited with code ${result.exitCode ?? ''}`,
+  });
+}

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

@@ -0,0 +1,114 @@
+export function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+export function parseJson(value: string): unknown {
+  const parsed: unknown = JSON.parse(value);
+  return parsed;
+}
+
+export function tryParseJson(value: string): unknown | null {
+  try {
+    return parseJson(value);
+  } catch {
+    return null;
+  }
+}
+
+export function getRecord(
+  record: Record<string, unknown>,
+  key: string
+): Record<string, unknown> | null {
+  const value = record[key];
+  return isRecord(value) ? value : null;
+}
+
+export function getArray(record: Record<string, unknown>, key: string): readonly unknown[] {
+  const value = record[key];
+  return Array.isArray(value) ? value : [];
+}
+
+export function getString(record: Record<string, unknown>, key: string): string | null {
+  const value = record[key];
+  return typeof value === 'string' ? value : null;
+}
+
+export function getOptionalString(
+  record: Record<string, unknown>,
+  key: string
+): string | null | undefined {
+  const value = record[key];
+  if (typeof value === 'string') return value;
+  if (value === null) return null;
+  return undefined;
+}
+
+export function getStringFromKeys(
+  record: Record<string, unknown>,
+  keys: readonly string[]
+): string | null {
+  for (const key of keys) {
+    const value = getString(record, key);
+    if (value !== null) return value;
+  }
+  return null;
+}
+
+export function getOrStringFromKeys(
+  record: Record<string, unknown>,
+  keys: readonly string[]
+): string | null | undefined {
+  for (const key of keys) {
+    const value = getOptionalString(record, key);
+    if (value) return value;
+  }
+
+  const lastKey = keys[keys.length - 1];
+  return lastKey === undefined ? undefined : getOptionalString(record, lastKey);
+}
+
+export function getOrStringFromKeysWithFallback(
+  record: Record<string, unknown>,
+  keys: readonly string[],
+  fallback: string | null | undefined
+): string | null | undefined {
+  for (const key of keys) {
+    const value = getOptionalString(record, key);
+    if (value) return value;
+  }
+
+  return fallback;
+}
+
+export function getNumber(record: Record<string, unknown>, key: string): number | null {
+  const value = record[key];
+  return typeof value === 'number' ? value : null;
+}
+
+export function getBoolean(record: Record<string, unknown>, key: string): boolean | null {
+  const value = record[key];
+  return typeof value === 'boolean' ? value : null;
+}
+
+export function stringifyJson(value: unknown, space?: number): string {
+  const serialized = JSON.stringify(value, null, space);
+  if (typeof serialized !== 'string') {
+    throw new Error('JSON schema must be serializable.');
+  }
+  return serialized;
+}
+
+export function stringifyContent(value: unknown): string {
+  if (typeof value === 'string') return value;
+  return stringifyJson(value);
+}
+
+export function unknownToMessage(error: unknown): string {
+  if (error instanceof Error) return error.message;
+  if (typeof error === 'string') return error;
+  if (isRecord(error)) {
+    const message = error.message;
+    if (typeof message === 'string' && message) return message;
+  }
+  return String(error);
+}

package/src/agent-cli-provider/log-prefix.ts

@@ -0,0 +1,20 @@
+export function stripTimestampPrefix(line: string): string {
+  let trimmed = line.trim().replace(/\r$/, '');
+  if (!trimmed) return '';
+
+  const timestampMatch = /^\[(\d{13})\](.*)$/.exec(trimmed);
+  const timestampRemainder = timestampMatch?.[2];
+  if (typeof timestampRemainder === 'string') {
+    trimmed = timestampRemainder.trimStart();
+  }
+
+  if (!trimmed.startsWith('{') && !trimmed.startsWith('[')) {
+    const pipeMatch = /^[^|]{1,40}\|\s*(.*)$/.exec(trimmed);
+    const afterPipe = pipeMatch?.[1]?.trimStart();
+    if (typeof afterPipe === 'string' && (afterPipe.startsWith('{') || afterPipe.startsWith('['))) {
+      return afterPipe;
+    }
+  }
+
+  return trimmed;
+}