@the-open-engine/zeroshot 5.4.0

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

@@ -0,0 +1,66 @@
+export class ContractRequestError extends Error {
+  readonly code: string;
+  readonly exitCode: number;
+  readonly field?: string;
+
+  constructor(input: { code: string; message: string; exitCode: number; field?: string }) {
+    super(input.message);
+    this.name = 'ContractRequestError';
+    this.code = input.code;
+    this.exitCode = input.exitCode;
+    if (input.field !== undefined) this.field = input.field;
+  }
+}
+
+export function contractError(input: {
+  readonly code: string;
+  readonly message: string;
+  readonly exitCode: number;
+  readonly field?: string;
+}): ContractRequestError {
+  return new ContractRequestError(input);
+}
+
+export function invalidField(field: string, message: string): never {
+  throw contractError({
+    code: 'invalid-field',
+    message,
+    exitCode: 2,
+    field,
+  });
+}
+
+export function requiredString(record: Record<string, unknown>, field: string): string {
+  const value = record[field];
+  if (typeof value === 'string' && value.length > 0) return value;
+  throw contractError({
+    code: 'missing-field',
+    message: `${field} is required.`,
+    exitCode: 2,
+    field,
+  });
+}
+
+export function optionalString(record: Record<string, unknown>, field: string): string | undefined {
+  const value = record[field];
+  if (value === undefined) return undefined;
+  if (typeof value === 'string') return value;
+  throw contractError({
+    code: 'invalid-field',
+    message: `${field} must be a string.`,
+    exitCode: 2,
+    field,
+  });
+}
+
+export function optionalNumber(record: Record<string, unknown>, field: string): number | undefined {
+  const value = record[field];
+  if (value === undefined) return undefined;
+  if (typeof value === 'number' && Number.isFinite(value)) return value;
+  throw contractError({
+    code: 'invalid-field',
+    message: `${field} must be a finite number.`,
+    exitCode: 2,
+    field,
+  });
+}

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

@@ -0,0 +1,121 @@
+import { getProviderAdapter } from './adapters';
+import { envRedactions, mergeEnvForRedaction } from './contract-env';
+import { ContractRequestError, contractError } from './contract-errors';
+import {
+  errorEnvelope,
+  type ContractErrorObject,
+  type ContractEnvelope,
+} from './contract-envelope';
+import { getString, isRecord, parseJson, unknownToMessage } from './json';
+import { mergeRedactions, redactString } from './redaction';
+import type { ProviderAdapter } from './types';
+import type { RequestData } from './contract-support';
+
+export function requestEnvelopeData(input: string): RequestData {
+  try {
+    const parsed = parseJson(input);
+    if (isRecord(parsed)) {
+      return {
+        raw: parsed,
+        command: getString(parsed, 'command'),
+        provider: getString(parsed, 'provider'),
+        env: fallbackRedactionEnv(parsed),
+      };
+    }
+  } catch {
+    return { raw: {}, command: null, provider: null, env: {} };
+  }
+  return { raw: {}, command: null, provider: null, env: {} };
+}
+
+function fallbackStringRecord(value: unknown): Readonly<Record<string, string>> {
+  if (!isRecord(value)) return {};
+  const result: Record<string, string> = {};
+  for (const [key, item] of Object.entries(value)) {
+    if (typeof item === 'string') result[key] = item;
+  }
+  return result;
+}
+
+function fallbackRedactionEnv(value: Record<string, unknown>): Readonly<Record<string, string>> {
+  const options = isRecord(value.options) ? value.options : {};
+  return mergeEnvForRedaction(
+    { source: 'request', env: fallbackStringRecord(value.env) },
+    { source: 'options.authEnv', env: fallbackStringRecord(options.authEnv) }
+  );
+}
+
+function redactFallbackField(input: {
+  readonly value: string | null;
+  readonly env: Readonly<Record<string, string>>;
+  readonly untrusted: boolean;
+}): {
+  readonly value: string | null;
+  readonly redactions: ReturnType<typeof redactString>['redactions'];
+} {
+  if (input.value === null || !input.untrusted) return { value: input.value, redactions: [] };
+  const result = redactString(input.value, input.env);
+  if (typeof result.value !== 'string') {
+    throw new Error('Redacted provider contract field lost its string shape.');
+  }
+  return { value: result.value, redactions: result.redactions };
+}
+
+function errorObject(requestError: ContractRequestError): ContractErrorObject {
+  if (requestError.field === undefined) {
+    return {
+      code: requestError.code,
+      message: requestError.message,
+    };
+  }
+  return {
+    code: requestError.code,
+    message: requestError.message,
+    field: requestError.field,
+  };
+}
+
+export function requestErrorFromUnknown(error: unknown): ContractRequestError {
+  if (error instanceof ContractRequestError) return error;
+  return contractError({
+    code: 'internal-error',
+    message: unknownToMessage(error),
+    exitCode: 5,
+  });
+}
+
+export function fallbackErrorEnvelope(
+  fallback: RequestData,
+  requestError: ContractRequestError
+): ContractEnvelope {
+  const adapter = fallback.provider === null ? null : providerAdapterOrNull(fallback.provider);
+  const command = redactFallbackField({
+    value: fallback.command,
+    env: fallback.env,
+    untrusted: requestError.field === 'command',
+  });
+  const provider = redactFallbackField({
+    value: fallback.provider,
+    env: fallback.env,
+    untrusted: requestError.field === 'provider',
+  });
+  return errorEnvelope({
+    command: command.value,
+    provider: provider.value,
+    adapterVersion: adapter?.adapterVersion ?? null,
+    redactions: mergeRedactions(
+      envRedactions(fallback.env),
+      command.redactions,
+      provider.redactions
+    ),
+    error: errorObject(requestError),
+  });
+}
+
+function providerAdapterOrNull(provider: string): ProviderAdapter | null {
+  try {
+    return getProviderAdapter(provider);
+  } catch {
+    return null;
+  }
+}

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

@@ -0,0 +1,104 @@
+import { unlink } from 'node:fs/promises';
+import { commandRedactions } from './contract-env';
+import { successEnvelope, type ContractEnvelope } from './contract-envelope';
+import { buildCommandSpec, optionalNumber, schemaMode, type RequestData } from './contract-support';
+import { providerFailureClassification } from './invoke-evidence';
+import { parseOutputEvents } from './contract-parse';
+import { unknownToMessage } from './json';
+import type { CommandSpec } from './types';
+import type { ProcessResult, ProcessRunner, ProcessRunnerOptions } from './process-runner';
+
+interface CleanupResult {
+  readonly path: string;
+  readonly removed: boolean;
+  readonly error?: string;
+}
+
+async function cleanupFiles(commandSpec: CommandSpec): Promise<readonly CleanupResult[]> {
+  const cleanup = commandSpec.cleanup ?? [];
+  const results: CleanupResult[] = [];
+  for (const file of cleanup) {
+    try {
+      await unlink(file);
+      results.push({ path: file, removed: true });
+    } catch (error) {
+      results.push({ path: file, removed: false, error: unknownToMessage(error) });
+    }
+  }
+  return results;
+}
+
+async function runAndCleanup(
+  commandSpec: CommandSpec,
+  runner: ProcessRunner,
+  runnerOptions: ProcessRunnerOptions
+): Promise<{ readonly result: ProcessResult; readonly cleanup: readonly CleanupResult[] }> {
+  let result: ProcessResult | null = null;
+  let runnerError: unknown;
+  try {
+    result = await runner(commandSpec, runnerOptions);
+  } catch (error) {
+    runnerError = error;
+  }
+
+  const cleanup = await cleanupFiles(commandSpec);
+  if (runnerError !== undefined) throw runnerError;
+  if (result === null) throw new Error('Provider runner did not produce a result.');
+  return { result, cleanup };
+}
+
+export async function runInvoke(
+  request: RequestData,
+  runner: ProcessRunner
+): Promise<ContractEnvelope> {
+  const { adapter, commandSpec, options } = buildCommandSpec(request);
+  const timeoutMs = optionalNumber(request.raw, 'timeoutMs');
+  const runnerOptions = timeoutMs === undefined ? {} : { timeoutMs };
+  const { result, cleanup } = await runAndCleanup(commandSpec, runner, runnerOptions);
+  const parsed = parseOutputEvents(adapter, {
+    chunk: [result.stdout, result.stderr].join('\n'),
+    sources: [
+      { name: 'stdout', value: result.stdout },
+      { name: 'stderr', value: result.stderr },
+    ],
+  });
+  const classification = providerFailureClassification(adapter, result);
+  return successEnvelope({
+    command: request.command ?? 'invoke',
+    adapter,
+    warnings: commandSpec.warnings,
+    redactions: commandRedactions(commandSpec),
+    evidence: invokeEvidence(result, timeoutMs),
+    result: {
+      commandSpec,
+      outputFormat: options.outputFormat ?? null,
+      schemaMode: schemaMode(options),
+      evidence: {
+        stdout: result.stdout,
+        stderr: result.stderr,
+      },
+      events: parsed.events,
+      diagnostics: parsed.diagnostics,
+      exitCode: result.exitCode,
+      signal: result.signal,
+      durationMs: result.durationMs,
+      timedOut: result.timedOut ?? false,
+      timeoutMs: result.timeoutMs ?? timeoutMs ?? null,
+      cleanup,
+      classification,
+    },
+  });
+}
+
+function invokeEvidence(
+  result: ProcessResult,
+  timeoutMs: number | undefined
+): Record<string, unknown> {
+  return {
+    exitCode: result.exitCode,
+    signal: result.signal,
+    durationMs: result.durationMs,
+    timedOut: result.timedOut ?? false,
+    timeoutMs: result.timeoutMs ?? timeoutMs ?? null,
+  };
+}

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

@@ -0,0 +1,173 @@
+import { isRecord } from './json';
+import { invalidField, contractError } from './contract-errors';
+import { stringRecord } from './contract-env';
+import type {
+  BuildProviderCommandOptions,
+  CliFeatureOverrides,
+  ModelLevel,
+  ModelSpec,
+  OutputFormat,
+  ReasoningEffort,
+} from './types';
+
+const OUTPUT_FORMATS: readonly OutputFormat[] = ['text', 'json', 'stream-json'];
+const MODEL_LEVELS: readonly ModelLevel[] = ['level1', 'level2', 'level3'];
+const REASONING_EFFORTS: readonly ReasoningEffort[] = ['low', 'medium', 'high', 'xhigh'];
+const CLI_FEATURE_FIELDS = [
+  'supportsOutputFormat',
+  'supportsStreamJson',
+  'supportsJsonSchema',
+  'supportsAutoApprove',
+  'supportsIncludePartials',
+  'supportsVerbose',
+  'supportsModel',
+  'supportsJson',
+  'supportsOutputSchema',
+  'supportsCwd',
+  'supportsConfigOverride',
+  'supportsSkipGitRepoCheck',
+  'supportsVariant',
+  'unknown',
+] as const;
+
+type CliFeatureField = (typeof CLI_FEATURE_FIELDS)[number];
+
+export function requestOptions(value: unknown): BuildProviderCommandOptions {
+  if (value === undefined) return {};
+  if (!isRecord(value)) {
+    throw contractError({
+      code: 'invalid-field',
+      message: 'options must be an object.',
+      exitCode: 2,
+      field: 'options',
+    });
+  }
+  rejectProviderCommandOverrides(value);
+  return normalizeBuildOptions(value);
+}
+
+function rejectProviderCommandOverrides(value: Record<string, unknown>): void {
+  for (const field of ['command', 'commandArgs']) {
+    if (!Object.prototype.hasOwnProperty.call(value, field)) continue;
+    throw contractError({
+      code: 'forbidden-field',
+      message: `options.${field} is not accepted by provider executable requests; provider adapters own executable binaries and arguments.`,
+      exitCode: 2,
+      field: `options.${field}`,
+    });
+  }
+}
+
+function optionalStringValue(value: unknown, field: string): string | undefined {
+  if (value === undefined) return undefined;
+  if (typeof value === 'string') return value;
+  invalidField(field, `${field} must be a string.`);
+}
+
+function optionalNullableStringValue(value: unknown, field: string): string | null | undefined {
+  if (value === undefined) return undefined;
+  if (value === null) return null;
+  if (typeof value === 'string') return value;
+  invalidField(field, `${field} must be a string or null.`);
+}
+
+function optionalBooleanValue(value: unknown, field: string): boolean | undefined {
+  if (value === undefined) return undefined;
+  if (typeof value === 'boolean') return value;
+  invalidField(field, `${field} must be a boolean.`);
+}
+
+function optionalEnumValue<T extends string>(
+  value: unknown,
+  field: string,
+  allowed: readonly T[]
+): T | undefined {
+  if (value === undefined) return undefined;
+  if (typeof value !== 'string') {
+    invalidField(field, `${field} must be a string.`);
+  }
+  for (const item of allowed) {
+    if (value === item) return item;
+  }
+  invalidField(field, `${field} must be one of: ${allowed.join(', ')}.`);
+}
+
+function optionalModelSpec(value: unknown): ModelSpec | undefined {
+  if (value === undefined) return undefined;
+  if (!isRecord(value)) {
+    invalidField('options.modelSpec', 'options.modelSpec must be an object.');
+  }
+
+  const level = optionalEnumValue(value.level, 'options.modelSpec.level', MODEL_LEVELS);
+  const model = optionalNullableStringValue(value.model, 'options.modelSpec.model');
+  const reasoningEffort = optionalEnumValue(
+    value.reasoningEffort,
+    'options.modelSpec.reasoningEffort',
+    REASONING_EFFORTS
+  );
+
+  return {
+    ...(level === undefined ? {} : { level }),
+    ...(model === undefined ? {} : { model }),
+    ...(reasoningEffort === undefined ? {} : { reasoningEffort }),
+  };
+}
+
+function optionalCliFeatures(value: unknown): CliFeatureOverrides | undefined {
+  if (value === undefined) return undefined;
+  if (!isRecord(value)) {
+    invalidField('options.cliFeatures', 'options.cliFeatures must be an object.');
+  }
+
+  const result: Partial<Record<CliFeatureField, boolean>> = {};
+  for (const field of CLI_FEATURE_FIELDS) {
+    const item = optionalBooleanValue(value[field], `options.cliFeatures.${field}`);
+    if (item !== undefined) result[field] = item;
+  }
+  return result;
+}
+
+function normalizeBuildOptions(value: Record<string, unknown>): BuildProviderCommandOptions {
+  const result: Record<string, unknown> = {};
+  addDefined(result, 'modelSpec', optionalModelSpec(value.modelSpec));
+  addDefined(
+    result,
+    'outputFormat',
+    optionalEnumValue(value.outputFormat, 'options.outputFormat', OUTPUT_FORMATS)
+  );
+  addPresent(result, value, 'jsonSchema');
+  addDefined(result, 'cwd', optionalStringValue(value.cwd, 'options.cwd'));
+  addDefined(result, 'autoApprove', optionalBooleanValue(value.autoApprove, 'options.autoApprove'));
+  addDefined(
+    result,
+    'resumeSessionId',
+    optionalStringValue(value.resumeSessionId, 'options.resumeSessionId')
+  );
+  addDefined(
+    result,
+    'continueSession',
+    optionalBooleanValue(value.continueSession, 'options.continueSession')
+  );
+  addDefined(result, 'cliFeatures', optionalCliFeatures(value.cliFeatures));
+  addDefined(
+    result,
+    'strictSchema',
+    optionalBooleanValue(value.strictSchema, 'options.strictSchema')
+  );
+  if (Object.prototype.hasOwnProperty.call(value, 'authEnv')) {
+    result.authEnv = stringRecord(value.authEnv, 'options.authEnv');
+  }
+  return result as BuildProviderCommandOptions;
+}
+
+function addDefined(result: Record<string, unknown>, key: string, value: unknown): void {
+  if (value !== undefined) result[key] = value;
+}
+
+function addPresent(
+  result: Record<string, unknown>,
+  input: Record<string, unknown>,
+  key: string
+): void {
+  if (Object.prototype.hasOwnProperty.call(input, key)) result[key] = input[key];
+}

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

@@ -0,0 +1,94 @@
+import { parseProviderChunk } from './adapters';
+import { envRedactions } from './contract-env';
+import { optionalString } from './contract-errors';
+import { successEnvelope, type ContractEnvelope, type ContractEvidence } from './contract-envelope';
+import { adapterForProvider, type RequestData } from './contract-support';
+import { tryParseJson, unknownToMessage } from './json';
+import type { OutputEvent, ProviderAdapter } from './types';
+
+function parseFragments(record: Record<string, unknown>): {
+  readonly chunk: string;
+  readonly sources: readonly { readonly name: string; readonly value: string }[];
+} {
+  const sources = ['stdout', 'stderr', 'jsonl']
+    .map((name) => {
+      const value = optionalString(record, name);
+      return value === undefined ? null : { name, value };
+    })
+    .filter((value): value is { readonly name: string; readonly value: string } => value !== null);
+  return {
+    chunk: sources.map((source) => source.value).join('\n'),
+    sources,
+  };
+}
+
+function collectParseDiagnostics(
+  sources: readonly { readonly name: string; readonly value: string }[]
+): readonly ContractEvidence[] {
+  const diagnostics: ContractEvidence[] = [];
+  for (const source of sources) {
+    collectSourceDiagnostics(diagnostics, source);
+  }
+  return diagnostics;
+}
+
+function collectSourceDiagnostics(
+  diagnostics: ContractEvidence[],
+  source: { readonly name: string; readonly value: string }
+): void {
+  const lines = source.value.split('\n');
+  for (let index = 0; index < lines.length; index += 1) {
+    const line = lines[index]?.trim() ?? '';
+    if (!isMalformedJsonCandidate(line)) continue;
+    diagnostics.push({
+      kind: 'parse-error',
+      source: source.name,
+      line: index + 1,
+      fragment: line,
+    });
+  }
+}
+
+function isMalformedJsonCandidate(line: string): boolean {
+  if (!line || (!line.startsWith('{') && !line.startsWith('['))) return false;
+  return tryParseJson(line) === null;
+}
+
+export function parseOutputEvents(
+  adapter: ProviderAdapter,
+  fragments: {
+    readonly chunk: string;
+    readonly sources: readonly { readonly name: string; readonly value: string }[];
+  }
+): { readonly events: readonly OutputEvent[]; readonly diagnostics: readonly ContractEvidence[] } {
+  const diagnostics = [...collectParseDiagnostics(fragments.sources)];
+  try {
+    return {
+      events: parseProviderChunk(adapter.id, fragments.chunk),
+      diagnostics,
+    };
+  } catch (error) {
+    return {
+      events: [],
+      diagnostics: [
+        ...diagnostics,
+        {
+          kind: 'parser-error',
+          message: unknownToMessage(error),
+        },
+      ],
+    };
+  }
+}
+
+export function runParseOutput(request: RequestData): ContractEnvelope {
+  const adapter = adapterForProvider(request.provider);
+  const fragments = parseFragments(request.raw);
+  const parsed = parseOutputEvents(adapter, fragments);
+  return successEnvelope({
+    command: request.command ?? 'parse-output',
+    adapter,
+    redactions: envRedactions(request.env),
+    result: parsed,
+  });
+}