@the-open-engine/zeroshot 5.4.0

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

@@ -0,0 +1,311 @@
+import { getProviderAdapter } from './adapters';
+import { isRecord } from './json';
+import type {
+  BuildProviderCommandOptions,
+  CliFeatureOverrides,
+  CommandSpec,
+  LevelOverrides,
+  ModelLevel,
+  ModelSpec,
+  ProviderAdapter,
+  ProviderCliFeatures,
+  ProviderId,
+  ReasoningEffort,
+} from './types';
+
+type UnknownFunction = (...args: readonly unknown[]) => unknown;
+
+interface CommandParts {
+  readonly command: string;
+  readonly args: readonly string[];
+}
+
+interface RuntimeProviderSettings {
+  readonly defaultLevel?: ModelLevel;
+  readonly levelOverrides: LevelOverrides;
+}
+
+export interface SingleAgentProviderCommandInput {
+  readonly provider?: string | null;
+  readonly context: string;
+  readonly options?: BuildProviderCommandOptions;
+}
+
+export interface PreparedSingleAgentProviderCommand {
+  readonly adapter: ProviderAdapter;
+  readonly commandSpec: CommandSpec;
+  readonly options: BuildProviderCommandOptions;
+  readonly cliFeatures: CliFeatureOverrides;
+}
+
+type MutableModelSpec = {
+  level?: ModelLevel;
+  model?: string | null;
+  reasoningEffort?: ReasoningEffort;
+};
+
+const MODEL_LEVELS: readonly ModelLevel[] = ['level1', 'level2', 'level3'];
+const REASONING_EFFORTS: readonly ReasoningEffort[] = ['low', 'medium', 'high', 'xhigh'];
+
+const settingsModule: unknown = require('../../lib/settings');
+const providerDetectionModule: unknown = require('../../lib/provider-detection');
+const claudeAuthModule: unknown = require('../../lib/settings/claude-auth');
+
+const loadSettingsFn = moduleFunction(settingsModule, 'loadSettings');
+const getClaudeCommandFn = moduleFunction(settingsModule, 'getClaudeCommand');
+const getHelpOutputFn = moduleFunction(providerDetectionModule, 'getHelpOutput');
+const resolveClaudeAuthFn = moduleFunction(claudeAuthModule, 'resolveClaudeAuth');
+
+export function prepareSingleAgentProviderCommand(
+  input: SingleAgentProviderCommandInput
+): PreparedSingleAgentProviderCommand {
+  const settings = loadRuntimeSettings();
+  const adapter = adapterForRuntimeInput(input.provider, settings);
+  const providerSettings = runtimeProviderSettings(settings, adapter.id);
+  const baseOptions = input.options ?? {};
+  const cliFeatures = baseOptions.cliFeatures ?? detectRuntimeProviderCliFeatures(adapter.id);
+  const authEnv = baseOptions.authEnv ?? resolveRuntimeAuthEnv(adapter.id, settings);
+  const options = buildRuntimeOptions(baseOptions, adapter, providerSettings, cliFeatures, authEnv);
+  return {
+    adapter,
+    options,
+    cliFeatures,
+    commandSpec: adapter.buildCommand(input.context, options),
+  };
+}
+
+export function detectRuntimeProviderCliFeatures(provider: string): ProviderCliFeatures {
+  const adapter = getProviderAdapter(provider);
+  const helpCommand = runtimeHelpCommand(adapter.id);
+  const helpText = stringResult(getHelpOutputFn(helpCommand.command, helpCommand.args));
+  return adapter.detectCliFeatures(helpText);
+}
+
+function buildRuntimeOptions(
+  baseOptions: BuildProviderCommandOptions,
+  adapter: ProviderAdapter,
+  providerSettings: RuntimeProviderSettings,
+  cliFeatures: CliFeatureOverrides,
+  authEnv: Readonly<Record<string, string>>
+): BuildProviderCommandOptions {
+  const resolved = {
+    ...baseOptions,
+    modelSpec: resolveRuntimeModelSpec(adapter, baseOptions.modelSpec, providerSettings),
+    cliFeatures,
+  };
+  if (!shouldIncludeAuthEnv(baseOptions, authEnv)) return resolved;
+  return { ...resolved, authEnv };
+}
+
+function shouldIncludeAuthEnv(
+  baseOptions: BuildProviderCommandOptions,
+  authEnv: Readonly<Record<string, string>>
+): boolean {
+  return baseOptions.authEnv !== undefined || Object.keys(authEnv).length > 0;
+}
+
+function resolveRuntimeModelSpec(
+  adapter: ProviderAdapter,
+  explicit: ModelSpec | undefined,
+  providerSettings: RuntimeProviderSettings
+): ModelSpec {
+  if (explicit?.model !== undefined) {
+    adapter.validateModelId(explicit.model);
+    return explicit;
+  }
+
+  const level = explicit?.level ?? providerSettings.defaultLevel ?? adapter.defaultLevel;
+  const resolved = adapter.resolveModelSpec(level, providerSettings.levelOverrides);
+  const modelSpec = modelSpecFromResolved(resolved);
+  if (explicit?.reasoningEffort === undefined) return modelSpec;
+  return { ...modelSpec, reasoningEffort: explicit.reasoningEffort };
+}
+
+function modelSpecFromResolved(resolved: {
+  readonly level: ModelLevel;
+  readonly model: string | null;
+  readonly reasoningEffort: ReasoningEffort | undefined;
+}): ModelSpec {
+  const result: MutableModelSpec = {
+    level: resolved.level,
+    model: resolved.model,
+  };
+  if (resolved.reasoningEffort !== undefined) result.reasoningEffort = resolved.reasoningEffort;
+  return result;
+}
+
+function resolveRuntimeAuthEnv(
+  provider: ProviderId,
+  settings: Record<string, unknown>
+): Readonly<Record<string, string>> {
+  if (provider !== 'claude') return {};
+  return stringRecordFromUnknown(resolveClaudeAuthFn(settings), 'resolveClaudeAuth');
+}
+
+function adapterForRuntimeInput(
+  provider: string | null | undefined,
+  settings: Record<string, unknown>
+): ProviderAdapter {
+  const configured = provider ?? optionalString(settings.defaultProvider, 'settings.defaultProvider');
+  return getProviderAdapter(configured ?? 'claude');
+}
+
+function runtimeProviderSettings(
+  settings: Record<string, unknown>,
+  provider: ProviderId
+): RuntimeProviderSettings {
+  const allSettings = optionalRecord(settings.providerSettings, 'settings.providerSettings');
+  const providerValue = allSettings?.[provider];
+  if (providerValue === undefined) return { levelOverrides: {} };
+  const providerSettings = requiredRecord(providerValue, `settings.providerSettings.${provider}`);
+  const defaultLevel = optionalModelLevel(
+    providerSettings.defaultLevel,
+    `settings.providerSettings.${provider}.defaultLevel`
+  );
+  const levelOverrides = levelOverridesFromUnknown(
+    providerSettings.levelOverrides,
+    `settings.providerSettings.${provider}.levelOverrides`
+  );
+  if (defaultLevel === undefined) return { levelOverrides };
+  return { defaultLevel, levelOverrides };
+}
+
+function runtimeHelpCommand(provider: ProviderId): CommandParts {
+  if (provider === 'claude') return getClaudeRuntimeCommand();
+  if (provider === 'codex') return { command: 'codex', args: ['exec'] };
+  if (provider === 'opencode') return { command: 'opencode', args: ['run'] };
+  return { command: 'gemini', args: [] };
+}
+
+function getClaudeRuntimeCommand(): CommandParts {
+  return commandPartsFromUnknown(getClaudeCommandFn(), 'getClaudeCommand');
+}
+
+function loadRuntimeSettings(): Record<string, unknown> {
+  const settings = loadSettingsFn();
+  return requiredRecord(settings, 'loadSettings');
+}
+
+function moduleFunction(moduleValue: unknown, field: string): UnknownFunction {
+  const record = requiredRecord(moduleValue, 'module');
+  const value = record[field];
+  if (isUnknownFunction(value)) return value;
+  throw new Error(`Expected ${field} to be a function.`);
+}
+
+function isUnknownFunction(value: unknown): value is UnknownFunction {
+  return typeof value === 'function';
+}
+
+function commandPartsFromUnknown(value: unknown, field: string): CommandParts {
+  const record = requiredRecord(value, field);
+  return {
+    command: requiredStringValue(record.command, `${field}.command`),
+    args: stringArray(record.args, `${field}.args`),
+  };
+}
+
+function levelOverridesFromUnknown(value: unknown, field: string): LevelOverrides {
+  if (value === undefined) return {};
+  const record = requiredRecord(value, field);
+  const result: Partial<Record<ModelLevel, ModelSpec>> = {};
+  for (const level of MODEL_LEVELS) {
+    if (record[level] !== undefined) result[level] = modelSpecFromUnknown(record[level], field);
+  }
+  return result;
+}
+
+function modelSpecFromUnknown(value: unknown, field: string): ModelSpec {
+  const record = requiredRecord(value, field);
+  const result: MutableModelSpec = {};
+  addModelLevel(result, record.level, `${field}.level`);
+  addModel(result, record.model, `${field}.model`);
+  addReasoningEffort(result, record.reasoningEffort, `${field}.reasoningEffort`);
+  return result;
+}
+
+function addModelLevel(result: MutableModelSpec, value: unknown, field: string): void {
+  const level = optionalModelLevel(value, field);
+  if (level !== undefined) result.level = level;
+}
+
+function addModel(result: MutableModelSpec, value: unknown, field: string): void {
+  if (value === undefined) return;
+  if (value === null || typeof value === 'string') {
+    result.model = value;
+    return;
+  }
+  throw new Error(`${field} must be a string or null.`);
+}
+
+function addReasoningEffort(result: MutableModelSpec, value: unknown, field: string): void {
+  const effort = optionalReasoningEffort(value, field);
+  if (effort !== undefined) result.reasoningEffort = effort;
+}
+
+function optionalModelLevel(value: unknown, field: string): ModelLevel | undefined {
+  if (value === undefined) return undefined;
+  if (value === 'level1' || value === 'level2' || value === 'level3') return value;
+  throw new Error(`${field} must be one of: ${MODEL_LEVELS.join(', ')}.`);
+}
+
+function optionalReasoningEffort(value: unknown, field: string): ReasoningEffort | undefined {
+  if (value === undefined) return undefined;
+  if (value === 'low' || value === 'medium' || value === 'high' || value === 'xhigh') {
+    return value;
+  }
+  throw new Error(`${field} must be one of: ${REASONING_EFFORTS.join(', ')}.`);
+}
+
+function optionalString(value: unknown, field: string): string | undefined {
+  if (value === undefined || value === null) return undefined;
+  if (typeof value === 'string') return value;
+  throw new Error(`${field} must be a string.`);
+}
+
+function requiredStringValue(value: unknown, field: string): string {
+  if (typeof value === 'string' && value.length > 0) return value;
+  throw new Error(`${field} must be a non-empty string.`);
+}
+
+function optionalRecord(
+  value: unknown,
+  field: string
+): Readonly<Record<string, unknown>> | undefined {
+  if (value === undefined || value === null) return undefined;
+  return requiredRecord(value, field);
+}
+
+function requiredRecord(value: unknown, field: string): Record<string, unknown> {
+  if (isRecord(value)) return value;
+  throw new Error(`${field} must be an object.`);
+}
+
+function stringRecordFromUnknown(
+  value: unknown,
+  field: string
+): Readonly<Record<string, string>> {
+  if (value === undefined || value === null) return {};
+  const record = requiredRecord(value, field);
+  const result: Record<string, string> = {};
+  for (const [key, item] of Object.entries(record)) {
+    if (typeof item !== 'string') throw new Error(`${field}.${key} must be a string.`);
+    result[key] = item;
+  }
+  return result;
+}
+
+function stringArray(value: unknown, field: string): readonly string[] {
+  if (!Array.isArray(value)) throw new Error(`${field} must be an array.`);
+  const result: string[] = [];
+  for (const item of value) {
+    if (typeof item !== 'string') throw new Error(`${field} entries must be strings.`);
+    result.push(item);
+  }
+  return result;
+}
+
+function stringResult(value: unknown): string {
+  if (typeof value === 'string') return value;
+  throw new Error('Provider help output must be a string.');
+}

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

@@ -0,0 +1,237 @@
+export type ProviderId = 'claude' | 'codex' | 'gemini' | 'opencode';
+export type ProviderAlias = 'anthropic' | 'openai' | 'google';
+export type KnownProviderName = ProviderId | ProviderAlias;
+export type ModelLevel = 'level1' | 'level2' | 'level3';
+export type ReasoningEffort = 'low' | 'medium' | 'high' | 'xhigh';
+export type OutputFormat = 'text' | 'json' | 'stream-json';
+
+export interface AgentCliProviderHelperMetadata {
+  readonly packageName: '@the-open-engine/zeroshot';
+  readonly buildOutputDir: 'lib/agent-cli-provider';
+  readonly contractVersion: 1;
+  readonly adapterVersion: string;
+}
+
+export interface ModelCatalogEntry {
+  readonly rank: number;
+}
+
+export interface LevelModelSpec {
+  readonly rank: number;
+  readonly model: string | null;
+  readonly reasoningEffort?: ReasoningEffort;
+}
+
+export interface ModelSpec {
+  readonly level?: ModelLevel;
+  readonly model?: string | null;
+  readonly reasoningEffort?: ReasoningEffort;
+}
+
+export interface ResolvedModelSpec {
+  readonly level: ModelLevel;
+  readonly model: string | null;
+  readonly reasoningEffort: ReasoningEffort | undefined;
+}
+
+export type LevelOverrides = Readonly<Partial<Record<ModelLevel, ModelSpec>>>;
+
+export interface BaseCliFeatures {
+  readonly provider?: ProviderId;
+  readonly unknown?: boolean;
+}
+
+export interface ClaudeCliFeatures extends BaseCliFeatures {
+  readonly provider: 'claude';
+  readonly supportsOutputFormat: boolean;
+  readonly supportsStreamJson: boolean;
+  readonly supportsJsonSchema: boolean;
+  readonly supportsAutoApprove: boolean;
+  readonly supportsIncludePartials: boolean;
+  readonly supportsVerbose: boolean;
+  readonly supportsModel: boolean;
+}
+
+export interface CodexCliFeatures extends BaseCliFeatures {
+  readonly provider: 'codex';
+  readonly supportsJson: boolean;
+  readonly supportsOutputSchema: boolean;
+  readonly supportsAutoApprove: boolean;
+  readonly supportsCwd: boolean;
+  readonly supportsConfigOverride: boolean;
+  readonly supportsModel: boolean;
+  readonly supportsSkipGitRepoCheck: boolean;
+}
+
+export interface GeminiCliFeatures extends BaseCliFeatures {
+  readonly provider: 'gemini';
+  readonly supportsStreamJson: boolean;
+  readonly supportsAutoApprove: boolean;
+  readonly supportsCwd: boolean;
+  readonly supportsModel: boolean;
+}
+
+export interface OpencodeCliFeatures extends BaseCliFeatures {
+  readonly provider: 'opencode';
+  readonly supportsJson: boolean;
+  readonly supportsModel: boolean;
+  readonly supportsVariant: boolean;
+  readonly supportsCwd: boolean;
+  readonly supportsAutoApprove: false;
+}
+
+export type ProviderCliFeatures =
+  | ClaudeCliFeatures
+  | CodexCliFeatures
+  | GeminiCliFeatures
+  | OpencodeCliFeatures;
+
+export interface CliFeatureOverrides {
+  readonly supportsOutputFormat?: boolean;
+  readonly supportsStreamJson?: boolean;
+  readonly supportsJsonSchema?: boolean;
+  readonly supportsAutoApprove?: boolean;
+  readonly supportsIncludePartials?: boolean;
+  readonly supportsVerbose?: boolean;
+  readonly supportsModel?: boolean;
+  readonly supportsJson?: boolean;
+  readonly supportsOutputSchema?: boolean;
+  readonly supportsCwd?: boolean;
+  readonly supportsConfigOverride?: boolean;
+  readonly supportsSkipGitRepoCheck?: boolean;
+  readonly supportsVariant?: boolean;
+  readonly unknown?: boolean;
+}
+
+export interface CleanupMetadata {
+  readonly kind: 'temp-file';
+  readonly provider: ProviderId;
+  readonly path: string;
+  readonly reason: 'output-schema';
+}
+
+export interface WarningMetadata {
+  readonly provider: ProviderId;
+  readonly code: string;
+  readonly message: string;
+}
+
+export interface RedactionMetadata {
+  readonly kind: 'env' | 'secret-key' | 'secret-value';
+  readonly key: string;
+  readonly source?: string;
+}
+
+export interface CommandSpec {
+  readonly binary: string;
+  readonly args: readonly string[];
+  readonly env: Readonly<Record<string, string>>;
+  readonly cwd?: string;
+  readonly cleanup?: readonly string[];
+  readonly cleanupMetadata: readonly CleanupMetadata[];
+  readonly warnings: readonly WarningMetadata[];
+  readonly redactions: readonly RedactionMetadata[];
+}
+
+export interface BuildProviderCommandOptions {
+  readonly modelSpec?: ModelSpec;
+  readonly outputFormat?: OutputFormat;
+  readonly jsonSchema?: unknown;
+  readonly cwd?: string;
+  readonly autoApprove?: boolean;
+  readonly resumeSessionId?: string;
+  readonly continueSession?: boolean;
+  readonly cliFeatures?: CliFeatureOverrides;
+  readonly authEnv?: Readonly<Record<string, string>>;
+  readonly strictSchema?: boolean;
+}
+
+export interface TextEvent {
+  readonly type: 'text';
+  readonly text: string;
+}
+
+export interface ThinkingEvent {
+  readonly type: 'thinking';
+  readonly text: string;
+}
+
+export interface ToolCallEvent {
+  readonly type: 'tool_call';
+  readonly toolName: string | null | undefined;
+  readonly toolId: string | null | undefined;
+  readonly input: unknown;
+}
+
+export interface ToolResultEvent {
+  readonly type: 'tool_result';
+  readonly toolId: string | null | undefined;
+  readonly content: unknown;
+  readonly isError: unknown;
+}
+
+export interface ResultEvent {
+  readonly type: 'result';
+  readonly success: boolean;
+  readonly result?: unknown;
+  readonly error?: unknown;
+  readonly cost?: unknown;
+  readonly duration?: unknown;
+  readonly inputTokens?: number;
+  readonly outputTokens?: number;
+  readonly cacheReadInputTokens?: number;
+  readonly cacheCreationInputTokens?: number;
+  readonly modelUsage?: unknown;
+}
+
+export type OutputEvent = TextEvent | ThinkingEvent | ToolCallEvent | ToolResultEvent | ResultEvent;
+
+export type ProviderParseResult = OutputEvent | readonly OutputEvent[] | null;
+
+export interface ProviderParserState {
+  provider: ProviderId;
+  lastToolId: string | null | undefined;
+}
+
+export type ErrorClassificationKind =
+  | 'status-retryable'
+  | 'status-permanent'
+  | 'code-retryable'
+  | 'permanent-pattern'
+  | 'retryable-pattern'
+  | 'unknown-retryable';
+
+export interface ErrorClassification {
+  readonly retryable: boolean;
+  readonly kind: ErrorClassificationKind;
+  readonly matchedPattern?: string;
+}
+
+export interface ProviderAdapter {
+  readonly id: ProviderId;
+  readonly displayName: string;
+  readonly binary: string;
+  readonly adapterVersion: string;
+  readonly credentialEnvKeys: readonly string[];
+  readonly modelCatalog: Readonly<Record<string, ModelCatalogEntry>>;
+  readonly levelMapping: Readonly<Record<ModelLevel, LevelModelSpec>>;
+  readonly defaultLevel: ModelLevel;
+  readonly defaultMaxLevel: ModelLevel;
+  readonly defaultMinLevel: ModelLevel;
+  detectCliFeatures(helpText?: string | null): ProviderCliFeatures;
+  buildCommand(context: string, options?: BuildProviderCommandOptions): CommandSpec;
+  parseEvent(line: string, state: ProviderParserState): ProviderParseResult;
+  createParserState(): ProviderParserState;
+  resolveModelSpec(level: ModelLevel, overrides?: LevelOverrides): ResolvedModelSpec;
+  validateModelId(modelId: string | null | undefined): string | null | undefined;
+  classifyError(error: unknown): ErrorClassification;
+}
+
+export class InvalidProviderModelError extends Error {
+  readonly permanent = true;
+
+  constructor(message: string) {
+    super(message);
+    this.name = 'InvalidProviderModelError';
+  }
+}