@the-open-engine/zeroshot 5.4.0

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

@@ -0,0 +1,286 @@
+import { appendJsonSchemaPrompt } from '../schema';
+import {
+  getNumber,
+  getOptionalString,
+  getRecord,
+  getString,
+  isRecord,
+  tryParseJson,
+} from '../json';
+import {
+  type BuildProviderCommandOptions,
+  type CommandSpec,
+  type ErrorClassification,
+  type LevelModelSpec,
+  type LevelOverrides,
+  type ModelCatalogEntry,
+  type ModelLevel,
+  type OpencodeCliFeatures,
+  type OutputEvent,
+  type ProviderAdapter,
+  type ResolvedModelSpec,
+  type WarningMetadata,
+} from '../types';
+import {
+  classifyBaseProviderError,
+  commandSpec,
+  createParserState,
+  optionFeatures,
+  resolveModelSpecWithConfig,
+  unsupportedSessionControlWarnings,
+  validateModelIdFromCatalog,
+  warning,
+} from './common';
+
+const MODEL_CATALOG: Readonly<Record<string, ModelCatalogEntry>> = {
+  'opencode/big-pickle': { rank: 1 },
+  'opencode/glm-4.7-free': { rank: 1 },
+  'opencode/gpt-5-nano': { rank: 1 },
+  'opencode/grok-code': { rank: 1 },
+  'opencode/minimax-m2.1-free': { rank: 1 },
+  'google/gemini-1.5-flash': { rank: 1 },
+  'google/gemini-1.5-flash-8b': { rank: 1 },
+  'google/gemini-1.5-pro': { rank: 1 },
+  'google/gemini-2.0-flash': { rank: 1 },
+  'google/gemini-2.0-flash-lite': { rank: 1 },
+  'google/gemini-2.5-flash': { rank: 1 },
+  'google/gemini-2.5-flash-image': { rank: 1 },
+  'google/gemini-2.5-flash-image-preview': { rank: 1 },
+  'google/gemini-2.5-flash-lite': { rank: 1 },
+  'google/gemini-2.5-flash-lite-preview-06-17': { rank: 1 },
+  'google/gemini-2.5-flash-lite-preview-09-2025': { rank: 1 },
+  'google/gemini-2.5-flash-preview-04-17': { rank: 1 },
+  'google/gemini-2.5-flash-preview-05-20': { rank: 1 },
+  'google/gemini-2.5-flash-preview-09-2025': { rank: 1 },
+  'google/gemini-2.5-flash-preview-tts': { rank: 1 },
+  'google/gemini-2.5-pro': { rank: 1 },
+  'google/gemini-2.5-pro-preview-05-06': { rank: 1 },
+  'google/gemini-2.5-pro-preview-06-05': { rank: 1 },
+  'google/gemini-2.5-pro-preview-tts': { rank: 1 },
+  'google/gemini-3-flash-preview': { rank: 1 },
+  'google/gemini-3-pro-preview': { rank: 1 },
+  'google/gemini-embedding-001': { rank: 1 },
+  'google/gemini-flash-latest': { rank: 1 },
+  'google/gemini-flash-lite-latest': { rank: 1 },
+  'google/gemini-live-2.5-flash': { rank: 1 },
+  'google/gemini-live-2.5-flash-preview-native-audio': { rank: 1 },
+  'openai/gpt-5.1-codex-max': { rank: 1 },
+  'openai/gpt-5.1-codex-mini': { rank: 1 },
+  'openai/gpt-5.2': { rank: 1 },
+  'openai/gpt-5.2-codex': { rank: 1 },
+};
+
+const LEVEL_MAPPING: Readonly<Record<ModelLevel, LevelModelSpec>> = {
+  level1: { rank: 1, model: null, reasoningEffort: 'low' },
+  level2: { rank: 2, model: null, reasoningEffort: 'medium' },
+  level3: { rank: 3, model: null, reasoningEffort: 'high' },
+};
+
+function detectCliFeatures(helpText?: string | null): OpencodeCliFeatures {
+  const help = helpText ?? '';
+  const unknown = !help;
+  return {
+    provider: 'opencode',
+    supportsJson: unknown ? true : /--format\b/.test(help),
+    supportsModel: unknown ? true : /--model\b/.test(help),
+    supportsVariant: unknown ? true : /--variant\b/.test(help),
+    supportsCwd: unknown ? false : /--cwd\b/.test(help),
+    supportsAutoApprove: false,
+    unknown,
+  };
+}
+
+function addOpencodeOptionalArgs(args: string[], options: BuildProviderCommandOptions): void {
+  const features = optionFeatures(options);
+  if (
+    (options.outputFormat === 'stream-json' || options.outputFormat === 'json') &&
+    features.supportsJson
+  ) {
+    args.push('--format', 'json');
+  }
+
+  if (options.modelSpec?.model) {
+    args.push('--model', options.modelSpec.model);
+  }
+
+  if (options.modelSpec?.reasoningEffort && features.supportsVariant) {
+    args.push('--variant', options.modelSpec.reasoningEffort);
+  }
+
+  if (options.cwd && features.supportsCwd) {
+    args.push('--cwd', options.cwd);
+  }
+}
+
+function collectOpencodeWarnings(options: BuildProviderCommandOptions): WarningMetadata[] {
+  const features = optionFeatures(options);
+  const warnings: WarningMetadata[] = unsupportedSessionControlWarnings('opencode', options);
+  if (options.modelSpec?.reasoningEffort && features.supportsVariant === false) {
+    warnings.push(
+      warning(
+        'opencode',
+        'opencode-variant',
+        'Opencode CLI does not support --variant; skipping reasoningEffort.'
+      )
+    );
+  }
+  return warnings;
+}
+
+function buildCommand(context: string, options: BuildProviderCommandOptions = {}): CommandSpec {
+  const finalContext = options.jsonSchema
+    ? appendJsonSchemaPrompt(context, options.jsonSchema)
+    : context;
+  const args: string[] = ['run'];
+  addOpencodeOptionalArgs(args, options);
+
+  args.push(finalContext);
+
+  return commandSpec({
+    binary: 'opencode',
+    args,
+    env: {},
+    ...(options.cwd === undefined ? {} : { cwd: options.cwd }),
+    warnings: collectOpencodeWarnings(options),
+  });
+}
+
+function parseToolPart(part: Record<string, unknown>): OutputEvent | null {
+  const state = getRecord(part, 'state') ?? {};
+  const status = getString(state, 'status');
+  if (status === 'pending' || status === 'running') {
+    return {
+      type: 'tool_call',
+      toolName: getOptionalString(part, 'tool'),
+      toolId: getOptionalString(part, 'callID'),
+      input: state.input ?? {},
+    };
+  }
+
+  if (status === 'completed') {
+    return {
+      type: 'tool_result',
+      toolId: getOptionalString(part, 'callID'),
+      content: state.output || '',
+      isError: false,
+    };
+  }
+
+  if (status === 'error') {
+    return {
+      type: 'tool_result',
+      toolId: getOptionalString(part, 'callID'),
+      content: state.error || '',
+      isError: true,
+    };
+  }
+
+  return null;
+}
+
+function parseStepFinish(part: Record<string, unknown>): OutputEvent {
+  const tokens = getRecord(part, 'tokens') ?? {};
+  return {
+    type: 'result',
+    success: true,
+    inputTokens: getNumber(tokens, 'input') ?? 0,
+    outputTokens: getNumber(tokens, 'output') ?? 0,
+  };
+}
+
+function parsePart(part: unknown): OutputEvent | null {
+  if (!isRecord(part)) return null;
+  if (getString(part, 'type') === 'text') {
+    const text = getString(part, 'text');
+    if (text) return { type: 'text', text };
+  }
+
+  if (getString(part, 'type') === 'reasoning') {
+    const text = getString(part, 'text');
+    if (text) return { type: 'thinking', text };
+  }
+
+  if (getString(part, 'type') === 'tool') {
+    return parseToolPart(part);
+  }
+
+  if (getString(part, 'type') === 'step-finish') {
+    return parseStepFinish(part);
+  }
+
+  return null;
+}
+
+function parseErrorEvent(event: Record<string, unknown>): OutputEvent {
+  const error = getRecord(event, 'error') ?? {};
+  const data = getRecord(error, 'data');
+  return {
+    type: 'result',
+    success: false,
+    error:
+      (data ? getString(data, 'message') : null) ??
+      getString(error, 'message') ??
+      getString(error, 'name') ??
+      'Unknown error',
+  };
+}
+
+function parseEvent(line: string): OutputEvent | null {
+  const event = tryParseJson(line);
+  if (!isRecord(event)) return null;
+
+  const type = getString(event, 'type');
+  if (type === 'error') return parseErrorEvent(event);
+  if (type === 'text' || type === 'step_start' || type === 'step_finish') {
+    return parsePart(event.part ?? event);
+  }
+  if (type === 'message.part.updated') {
+    const properties = getRecord(event, 'properties');
+    return parsePart(properties?.part);
+  }
+  return null;
+}
+
+function resolveModelSpec(level: ModelLevel, overrides?: LevelOverrides): ResolvedModelSpec {
+  return resolveModelSpecWithConfig({
+    mapping: LEVEL_MAPPING,
+    defaultLevel: 'level2',
+    level,
+    overrides,
+    validateModelId,
+  });
+}
+
+function validateModelId(modelId: string | null | undefined): string | null | undefined {
+  return validateModelIdFromCatalog('opencode', MODEL_CATALOG, modelId);
+}
+
+function classifyError(error: unknown): ErrorClassification {
+  return classifyBaseProviderError(error, [], []);
+}
+
+export const opencodeAdapter: ProviderAdapter = {
+  id: 'opencode',
+  displayName: 'Opencode',
+  binary: 'opencode',
+  adapterVersion: '1',
+  credentialEnvKeys: [
+    'OPENCODE_API_KEY',
+    'OPENAI_API_KEY',
+    'ANTHROPIC_API_KEY',
+    'GEMINI_API_KEY',
+    'GOOGLE_API_KEY',
+  ],
+  modelCatalog: MODEL_CATALOG,
+  levelMapping: LEVEL_MAPPING,
+  defaultLevel: 'level2',
+  defaultMaxLevel: 'level3',
+  defaultMinLevel: 'level1',
+  detectCliFeatures,
+  buildCommand,
+  parseEvent,
+  createParserState: () => createParserState('opencode'),
+  resolveModelSpec,
+  validateModelId,
+  classifyError,
+};

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

@@ -0,0 +1,150 @@
+import { classifyProviderError } from './adapters';
+import { envRedactions, commandRedactions } from './contract-env';
+import { contractError } from './contract-errors';
+import {
+  providerExecutableSchemaVersion,
+  successEnvelope,
+  type ContractEnvelope,
+  type ContractEvidence,
+} from './contract-envelope';
+import { runInvoke } from './contract-invoke';
+import { runParseOutput } from './contract-parse';
+import {
+  adapterForProvider,
+  buildCommandSpec,
+  schemaMode,
+  type RequestData,
+} from './contract-support';
+import { detectRuntimeProviderCliFeatures } from './single-agent-runtime';
+import { getNumber, getRecord, getString, isRecord, unknownToMessage } from './json';
+import type { ErrorClassification } from './types';
+import type { ProcessRunner } from './process-runner';
+
+function runBuildCommand(request: RequestData): ContractEnvelope {
+  const { adapter, commandSpec, options } = buildCommandSpec(request);
+  return successEnvelope({
+    command: request.command ?? 'build-command',
+    adapter,
+    warnings: commandSpec.warnings,
+    redactions: commandRedactions(commandSpec),
+    evidence: {
+      outputFormat: options.outputFormat ?? null,
+      schemaMode: schemaMode(options),
+    },
+    result: {
+      commandSpec,
+      outputFormat: options.outputFormat ?? null,
+      schemaMode: schemaMode(options),
+    },
+  });
+}
+
+function runProbe(request: RequestData): ContractEnvelope {
+  const adapter = adapterForProvider(request.provider);
+  const helpText = typeof request.raw.helpText === 'string' ? request.raw.helpText : null;
+  const capabilities =
+    helpText === null ? detectRuntimeProviderCliFeatures(adapter.id) : adapter.detectCliFeatures(helpText);
+  return successEnvelope({
+    command: request.command ?? 'probe',
+    adapter,
+    redactions: envRedactions(request.env),
+    result: {
+      provider: {
+        id: adapter.id,
+        displayName: adapter.displayName,
+        binary: adapter.binary,
+      },
+      contractVersion: providerExecutableSchemaVersion,
+      adapterVersion: adapter.adapterVersion,
+      capabilities,
+      credentials: adapter.credentialEnvKeys.map((key) => ({
+        key,
+        present: Boolean(request.env[key] ?? process.env[key]),
+      })),
+    },
+  });
+}
+
+function statusFromError(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 categoryForClassification(classification: ErrorClassification, error: unknown): string {
+  const status = statusFromError(error);
+  if (status === 401 || status === 403) return 'auth';
+  if (status === 429) return 'rate-limit';
+  const message = unknownToMessage(error);
+  if (/auth|api[_ -]?key|unauthorized|forbidden|permission/i.test(message)) return 'auth';
+  if (/rate|429|quota|resource_exhausted/i.test(message)) return 'rate-limit';
+  if (/schema|json|parse|format/i.test(message)) return 'schema';
+  return classification.retryable ? 'retryable' : 'permanent';
+}
+
+function errorEvidence(error: unknown): ContractEvidence {
+  const evidence: Record<string, unknown> = {
+    message: unknownToMessage(error),
+  };
+  if (isRecord(error)) {
+    const status = statusFromError(error);
+    const code = getString(error, 'code');
+    if (status !== null) evidence.status = status;
+    if (code !== null) evidence.code = code;
+  }
+  return evidence;
+}
+
+function runClassifyError(request: RequestData): ContractEnvelope {
+  const adapter = adapterForProvider(request.provider);
+  const error = request.raw.error;
+  if (error === undefined) {
+    throw contractError({
+      code: 'missing-field',
+      message: 'error is required.',
+      exitCode: 2,
+      field: 'error',
+    });
+  }
+  const classification = classifyProviderError(adapter.id, error);
+  return successEnvelope({
+    command: request.command ?? 'classify-error',
+    adapter,
+    redactions: envRedactions(request.env),
+    evidence: errorEvidence(error),
+    result: {
+      classification,
+      category: categoryForClassification(classification, error),
+      evidence: errorEvidence(error),
+    },
+  });
+}
+
+export function dispatchRequest(
+  request: RequestData,
+  runner: ProcessRunner
+): ContractEnvelope | Promise<ContractEnvelope> {
+  switch (request.command) {
+    case 'probe':
+      return runProbe(request);
+    case 'build-command':
+      return runBuildCommand(request);
+    case 'parse-output':
+      return runParseOutput(request);
+    case 'classify-error':
+      return runClassifyError(request);
+    case 'invoke':
+      return runInvoke(request, runner);
+    default:
+      throw contractError({
+        code: 'unknown-command',
+        message: `Unknown command: ${request.command ?? ''}.`,
+        exitCode: 3,
+        field: 'command',
+      });
+  }
+}

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

@@ -0,0 +1,111 @@
+import { getProviderAdapter } from './adapters';
+import { findUnsafeProviderEnvKey } from './env-safety';
+import { isRecord } from './json';
+import { mergeRedactions } from './redaction';
+import { contractError } from './contract-errors';
+import type { CommandSpec, ProviderAdapter, RedactionMetadata } from './types';
+
+export function stringRecord(value: unknown, field: string): Readonly<Record<string, string>> {
+  if (value === undefined) return {};
+  if (!isRecord(value)) {
+    throw contractError({
+      code: 'invalid-field',
+      message: `${field} must be an object with string values.`,
+      exitCode: 2,
+      field,
+    });
+  }
+
+  const result: Record<string, string> = {};
+  for (const [key, item] of Object.entries(value)) {
+    if (typeof item !== 'string') {
+      throw contractError({
+        code: 'invalid-field',
+        message: `${field}.${key} must be a string.`,
+        exitCode: 2,
+        field: `${field}.${key}`,
+      });
+    }
+    result[key] = item;
+  }
+  assertNoUnsafeProviderEnv(result, field);
+  return result;
+}
+
+function assertNoUnsafeProviderEnv(env: Readonly<Record<string, string>>, field: string): void {
+  const key = findUnsafeProviderEnvKey(env);
+  if (key === null) return;
+  throw contractError({
+    code: 'forbidden-field',
+    message: `${field}.${key} is not accepted by provider executable requests; provider adapters own executable resolution and process-control environment.`,
+    exitCode: 2,
+    field: `${field}.${key}`,
+  });
+}
+
+export function envRedactions(env: Readonly<Record<string, string>>): readonly RedactionMetadata[] {
+  return Object.keys(env).map((key) => ({ kind: 'env', key }));
+}
+
+export function commandRedactions(commandSpec: CommandSpec): readonly RedactionMetadata[] {
+  return mergeRedactions(commandSpec.redactions, envRedactions(commandSpec.env));
+}
+
+export function providerCredentialEnv(provider: string | null): Readonly<Record<string, string>> {
+  if (provider === null) return {};
+  let adapter: ProviderAdapter;
+  try {
+    adapter = getProviderAdapter(provider);
+  } catch {
+    return {};
+  }
+  const result: Record<string, string> = {};
+  for (const key of adapter.credentialEnvKeys) {
+    const value = process.env[key];
+    if (typeof value === 'string' && value.length > 0) result[key] = value;
+  }
+  return result;
+}
+
+export function mergeEnvForRedaction(
+  ...inputs: readonly {
+    readonly source: string;
+    readonly env: Readonly<Record<string, string>>;
+  }[]
+): Readonly<Record<string, string>> {
+  const result: Record<string, string> = {};
+  for (const input of inputs) {
+    for (const [key, value] of Object.entries(input.env)) {
+      if (value.length === 0) continue;
+      if (result[key] === undefined || result[key] === value) {
+        result[key] = value;
+        continue;
+      }
+      result[`${key}:${input.source}`] = value;
+    }
+  }
+  return result;
+}
+
+export function collectCommandSpecEnv(value: unknown): Readonly<Record<string, string>> {
+  const result: Record<string, string> = {};
+  collectCommandSpecEnvInto(value, result);
+  return result;
+}
+
+function collectCommandSpecEnvInto(value: unknown, result: Record<string, string>): void {
+  if (Array.isArray(value)) {
+    for (const item of value) collectCommandSpecEnvInto(item, result);
+    return;
+  }
+  if (!isRecord(value)) return;
+
+  const commandSpec = value.commandSpec;
+  if (isRecord(commandSpec) && isRecord(commandSpec.env)) {
+    for (const [key, item] of Object.entries(commandSpec.env)) {
+      if (typeof item === 'string' && item.length > 0) result[key] = item;
+    }
+  }
+
+  for (const item of Object.values(value)) collectCommandSpecEnvInto(item, result);
+}

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

@@ -0,0 +1,110 @@
+import { collectCommandSpecEnv, mergeEnvForRedaction, providerCredentialEnv } from './contract-env';
+import { isRecord } from './json';
+import { mergeRedactions, redactObject } from './redaction';
+import type { ProviderAdapter, RedactionMetadata, WarningMetadata } from './types';
+
+export const providerExecutableSchemaVersion = 1 as const;
+
+export interface ContractErrorObject {
+  readonly code: string;
+  readonly message: string;
+  readonly field?: string;
+  readonly classification?: unknown;
+}
+
+export interface ContractEvidence {
+  readonly [key: string]: unknown;
+}
+
+interface ContractEnvelopeBase {
+  readonly schemaVersion: 1;
+  readonly command: string | null;
+  readonly provider: string | null;
+  readonly adapterVersion: string | null;
+  readonly warnings: readonly WarningMetadata[];
+  readonly redactions: readonly RedactionMetadata[];
+  readonly evidence: ContractEvidence;
+}
+
+export interface ContractSuccessEnvelope<Result = unknown> extends ContractEnvelopeBase {
+  readonly ok: true;
+  readonly result: Result;
+}
+
+export interface ContractErrorEnvelope extends ContractEnvelopeBase {
+  readonly ok: false;
+  readonly error: ContractErrorObject;
+}
+
+export type ContractEnvelope<Result = unknown> =
+  | ContractSuccessEnvelope<Result>
+  | ContractErrorEnvelope;
+
+export function finalizeEnvelope(
+  envelope: ContractEnvelope,
+  env: Readonly<Record<string, string>>
+): ContractEnvelope {
+  const redacted = redactObject(
+    envelope,
+    mergeEnvForRedaction(
+      { source: 'commandSpec', env: collectCommandSpecEnv(envelope) },
+      { source: 'process', env: providerCredentialEnv(envelope.provider) },
+      { source: 'request', env }
+    )
+  );
+  if (!isContractEnvelope(redacted.value)) {
+    throw new Error('Redacted provider contract envelope lost its JSON shape.');
+  }
+  return {
+    ...redacted.value,
+    redactions: mergeRedactions(envelope.redactions, redacted.redactions),
+  };
+}
+
+function isContractEnvelope(value: unknown): value is ContractEnvelope {
+  if (!isRecord(value)) return false;
+  return value.schemaVersion === providerExecutableSchemaVersion && typeof value.ok === 'boolean';
+}
+
+export function successEnvelope<Result>(input: {
+  readonly command: string;
+  readonly adapter: ProviderAdapter;
+  readonly result: Result;
+  readonly warnings?: readonly WarningMetadata[];
+  readonly redactions?: readonly RedactionMetadata[];
+  readonly evidence?: ContractEvidence;
+}): ContractSuccessEnvelope<Result> {
+  return {
+    schemaVersion: providerExecutableSchemaVersion,
+    ok: true,
+    command: input.command,
+    provider: input.adapter.id,
+    adapterVersion: input.adapter.adapterVersion,
+    warnings: input.warnings ?? [],
+    redactions: input.redactions ?? [],
+    evidence: input.evidence ?? {},
+    result: input.result,
+  };
+}
+
+export function errorEnvelope(input: {
+  readonly command: string | null;
+  readonly provider: string | null;
+  readonly adapterVersion?: string | null;
+  readonly error: ContractErrorObject;
+  readonly warnings?: readonly WarningMetadata[];
+  readonly redactions?: readonly RedactionMetadata[];
+  readonly evidence?: ContractEvidence;
+}): ContractErrorEnvelope {
+  return {
+    schemaVersion: providerExecutableSchemaVersion,
+    ok: false,
+    command: input.command,
+    provider: input.provider,
+    adapterVersion: input.adapterVersion ?? null,
+    warnings: input.warnings ?? [],
+    redactions: input.redactions ?? [],
+    evidence: input.evidence ?? {},
+    error: input.error,
+  };
+}