@the-open-engine/zeroshot 5.4.0

package/src/agent-cli-provider/process-runner.ts

@@ -0,0 +1,145 @@
+import { spawn } from 'node:child_process';
+import { omitProcessControlEnv, omitUnsafeProviderEnv } from './env-safety';
+import type { CommandSpec } from './types';
+
+const DEFAULT_TIMEOUT_KILL_GRACE_MS = 100;
+const PROVIDER_STDIO: ['ignore', 'pipe', 'pipe'] = ['ignore', 'pipe', 'pipe'];
+
+export interface ProcessRunnerOptions {
+  readonly timeoutMs?: number;
+  readonly timeoutKillGraceMs?: number;
+}
+
+export interface ProcessResult {
+  readonly stdout: string;
+  readonly stderr: string;
+  readonly exitCode: number | null;
+  readonly signal: string | null;
+  readonly durationMs: number;
+  readonly timedOut?: boolean;
+  readonly timeoutMs?: number;
+}
+
+export type ProcessRunner = (
+  commandSpec: CommandSpec,
+  options?: ProcessRunnerOptions
+) => Promise<ProcessResult>;
+
+interface TimeoutState {
+  timedOut: boolean;
+  timeout?: NodeJS.Timeout;
+  timeoutKill?: NodeJS.Timeout;
+}
+
+function clearTimeoutState(state: TimeoutState): void {
+  if (state.timeout !== undefined) clearTimeout(state.timeout);
+  if (state.timeoutKill !== undefined) clearTimeout(state.timeoutKill);
+}
+
+function armTimeout(
+  child: ReturnType<typeof spawn>,
+  options: ProcessRunnerOptions,
+  state: TimeoutState,
+  isSettled: () => boolean
+): void {
+  if (options.timeoutMs === undefined) return;
+  state.timeout = setTimeout(() => {
+    state.timedOut = true;
+    child.kill('SIGTERM');
+    state.timeoutKill = setTimeout(() => {
+      if (!isSettled()) child.kill('SIGKILL');
+    }, options.timeoutKillGraceMs ?? DEFAULT_TIMEOUT_KILL_GRACE_MS);
+  }, options.timeoutMs);
+}
+
+function processResult(input: {
+  readonly stdout: readonly Buffer[];
+  readonly stderr: readonly Buffer[];
+  readonly exitCode: number | null;
+  readonly signal: string | null;
+  readonly startedAt: number;
+  readonly state: TimeoutState;
+  readonly timeoutMs?: number;
+}): ProcessResult {
+  return {
+    stdout: Buffer.concat(input.stdout).toString('utf8'),
+    stderr: Buffer.concat(input.stderr).toString('utf8'),
+    exitCode: input.exitCode,
+    signal: input.signal,
+    durationMs: Date.now() - input.startedAt,
+    timedOut: input.state.timedOut,
+    ...(input.state.timedOut && input.timeoutMs !== undefined
+      ? { timeoutMs: input.timeoutMs }
+      : {}),
+  };
+}
+
+function spawnOptions(commandSpec: CommandSpec): {
+  readonly shell: false;
+  readonly env: NodeJS.ProcessEnv;
+  readonly stdio: ['ignore', 'pipe', 'pipe'];
+  cwd?: string;
+} {
+  const options: {
+    readonly shell: false;
+    readonly env: NodeJS.ProcessEnv;
+    readonly stdio: ['ignore', 'pipe', 'pipe'];
+    cwd?: string;
+  } = {
+    shell: false,
+    env: { ...omitProcessControlEnv(process.env), ...omitUnsafeProviderEnv(commandSpec.env) },
+    stdio: PROVIDER_STDIO,
+  };
+  if (commandSpec.cwd !== undefined) options.cwd = commandSpec.cwd;
+  return options;
+}
+
+function attachOutputCollectors(
+  child: ReturnType<typeof spawn>,
+  stdout: Buffer[],
+  stderr: Buffer[]
+): void {
+  child.stdout?.on('data', (chunk: Buffer) => stdout.push(chunk));
+  child.stderr?.on('data', (chunk: Buffer) => stderr.push(chunk));
+}
+
+export function spawnProcessRunner(): ProcessRunner {
+  return (commandSpec, options = {}) =>
+    new Promise<ProcessResult>((resolve, reject) => {
+      const startedAt = Date.now();
+      const stdout: Buffer[] = [];
+      const stderr: Buffer[] = [];
+      const child = spawn(commandSpec.binary, [...commandSpec.args], spawnOptions(commandSpec));
+      const timeoutState: TimeoutState = { timedOut: false };
+      let settled = false;
+
+      function settle(): boolean {
+        if (settled) return false;
+        settled = true;
+        clearTimeoutState(timeoutState);
+        return true;
+      }
+
+      attachOutputCollectors(child, stdout, stderr);
+      child.once('error', (error) => {
+        if (settle()) reject(error);
+      });
+      child.once('close', (exitCode, signal) => {
+        if (settle()) {
+          resolve(
+            processResult({
+              stdout,
+              stderr,
+              exitCode,
+              signal,
+              startedAt,
+              state: timeoutState,
+              ...(options.timeoutMs !== undefined ? { timeoutMs: options.timeoutMs } : {}),
+            })
+          );
+        }
+      });
+
+      armTimeout(child, options, timeoutState, () => settled);
+    });
+}

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

@@ -0,0 +1,282 @@
+import { isRecord } from './json';
+import type { RedactionMetadata } from './types';
+
+const SECRET_KEY_PATTERN = /TOKEN|KEY|SECRET|PASSWORD/i;
+const REDACTED_PREFIX = '[REDACTED:';
+const SECRET_VALUE_PATTERNS: readonly RegExp[] = [
+  /\b(?:sk|rk|pk)-[A-Za-z0-9][A-Za-z0-9._-]{5,}\b/g,
+  /\bgithub_pat_[A-Za-z0-9_]{20,}\b/g,
+  /\bgh[pousr]_[A-Za-z0-9]{20,}\b/g,
+  /\bxox[baprs]?-[A-Za-z0-9-]{10,}\b/g,
+  /\bAIza[A-Za-z0-9_-]{20,}\b/g,
+];
+const UNTRUSTED_OUTPUT_PATHS = new Set([
+  'error.message',
+  'evidence.message',
+  'evidence.code',
+  'result.evidence.message',
+  'result.evidence.code',
+  'result.evidence.stdout',
+  'result.evidence.stderr',
+]);
+
+interface RedactionTarget {
+  readonly kind: RedactionMetadata['kind'];
+  readonly key: string;
+  readonly source?: string;
+  readonly scope: 'env-or-untrusted' | 'global' | 'untrusted';
+  readonly value: string;
+}
+
+export interface RedactionResult {
+  readonly value: unknown;
+  readonly redactions: readonly RedactionMetadata[];
+}
+
+function metadataFor(target: RedactionTarget): RedactionMetadata {
+  if (target.source === undefined) return { kind: target.kind, key: target.key };
+  return { kind: target.kind, key: target.key, source: target.source };
+}
+
+function metadataKey(metadata: RedactionMetadata): string {
+  return `${metadata.kind}:${metadata.key}:${metadata.source ?? ''}`;
+}
+
+function dedupeMetadata(metadata: readonly RedactionMetadata[]): readonly RedactionMetadata[] {
+  const seen = new Set<string>();
+  const result: RedactionMetadata[] = [];
+  for (const item of metadata) {
+    const key = metadataKey(item);
+    if (seen.has(key)) continue;
+    seen.add(key);
+    result.push(item);
+  }
+  return result;
+}
+
+function targetsFromEnv(env: Readonly<Record<string, string>>): readonly RedactionTarget[] {
+  return Object.entries(env)
+    .filter(([, value]) => value.length > 0)
+    .map(([key, value]) => ({ kind: 'env', key, scope: 'env-or-untrusted', value }));
+}
+
+function shouldRedactSecretKey(key: string): boolean {
+  return SECRET_KEY_PATTERN.test(key);
+}
+
+function isRedactionMetadataRecord(value: unknown): boolean {
+  if (!isRecord(value)) return false;
+  const keys = Object.keys(value);
+  if (!keys.every((key) => key === 'kind' || key === 'key' || key === 'source')) return false;
+  if (value.kind !== 'env' && value.kind !== 'secret-key' && value.kind !== 'secret-value') {
+    return false;
+  }
+  if (typeof value.key !== 'string') return false;
+  return value.source === undefined || typeof value.source === 'string';
+}
+
+function isRedactionMetadataPath(path: string): boolean {
+  return /(^|\.)redactions\[\d+\]$/.test(path);
+}
+
+function shouldPreserveRedactionMetadataRecord(value: unknown, path: string): boolean {
+  return isRedactionMetadataRecord(value) && isRedactionMetadataPath(path);
+}
+
+function isCredentialPresenceRecord(value: unknown): boolean {
+  if (!isRecord(value)) return false;
+  const keys = Object.keys(value);
+  return (
+    keys.length === 2 &&
+    typeof value.key === 'string' &&
+    typeof value.present === 'boolean' &&
+    keys.every((key) => key === 'key' || key === 'present')
+  );
+}
+
+function isProbeCredentialPresencePath(path: string): boolean {
+  return /^result\.credentials\[\d+\]$/.test(path);
+}
+
+function shouldPreserveCredentialPresenceRecord(value: unknown, path: string): boolean {
+  return isCredentialPresenceRecord(value) && isProbeCredentialPresencePath(path);
+}
+
+function collectSecretKeyTargets(value: unknown, path = ''): readonly RedactionTarget[] {
+  if (Array.isArray(value)) {
+    return value.flatMap((item, index) => collectSecretKeyTargets(item, `${path}[${index}]`));
+  }
+  if (!isRecord(value)) return [];
+  if (shouldPreserveRedactionMetadataRecord(value, path)) return [];
+  if (shouldPreserveCredentialPresenceRecord(value, path)) return [];
+
+  const targets: RedactionTarget[] = [];
+  for (const [key, item] of Object.entries(value)) {
+    const keyPath = path ? `${path}.${key}` : key;
+    if (typeof item === 'string' && item.length > 0 && shouldRedactSecretKey(key)) {
+      targets.push({ kind: 'secret-key', key: keyPath, scope: 'untrusted', value: item });
+    }
+    targets.push(...collectSecretKeyTargets(item, keyPath));
+  }
+  return targets;
+}
+
+function collectSecretValueTargets(value: unknown, path = ''): readonly RedactionTarget[] {
+  if (typeof value === 'string') {
+    return SECRET_VALUE_PATTERNS.flatMap((pattern) =>
+      collectSecretValuePatternTargets(value, path, pattern)
+    );
+  }
+  if (Array.isArray(value)) {
+    return value.flatMap((item, index) => collectSecretValueTargets(item, `${path}[${index}]`));
+  }
+  if (!isRecord(value)) return [];
+  if (shouldPreserveRedactionMetadataRecord(value, path)) return [];
+  if (shouldPreserveCredentialPresenceRecord(value, path)) return [];
+
+  return Object.entries(value).flatMap(([key, item]) => {
+    const keyPath = path ? `${path}.${key}` : key;
+    return collectSecretValueTargets(item, keyPath);
+  });
+}
+
+function collectSecretValuePatternTargets(
+  value: string,
+  path: string,
+  pattern: RegExp
+): readonly RedactionTarget[] {
+  const targets: RedactionTarget[] = [];
+  pattern.lastIndex = 0;
+  let match = pattern.exec(value);
+  while (match !== null) {
+    const secret = match[0];
+    if (secret) {
+      targets.push({
+        kind: 'secret-value',
+        key: path || 'value',
+        scope: 'global',
+        value: secret,
+      });
+    }
+    match = pattern.exec(value);
+  }
+  return targets;
+}
+
+function applyTargets(input: string, targets: readonly RedactionTarget[]): string {
+  let output = input;
+  for (const target of targets) {
+    if (!target.value) continue;
+    output = output.split(target.value).join(`${REDACTED_PREFIX}${target.key}]`);
+  }
+  return output;
+}
+
+function envTargetPathKey(target: RedactionTarget): string {
+  return target.key.split(':', 1)[0] ?? target.key;
+}
+
+function isEnvValuePath(path: string, target: RedactionTarget): boolean {
+  const key = envTargetPathKey(target);
+  return path === `env.${key}` || path.endsWith(`.env.${key}`);
+}
+
+function isUntrustedOutputPath(path: string): boolean {
+  if (path.length === 0 || path === 'value') return true;
+  return (
+    UNTRUSTED_OUTPUT_PATHS.has(path) ||
+    path.startsWith('result.events') ||
+    path.startsWith('result.diagnostics')
+  );
+}
+
+function shouldApplyTargetAtPath(target: RedactionTarget, path: string): boolean {
+  if (target.scope === 'global') return true;
+  if (target.scope === 'untrusted') return isUntrustedOutputPath(path);
+  return isEnvValuePath(path, target) || isUntrustedOutputPath(path);
+}
+
+function applyTargetsAtPath(
+  input: string,
+  targets: readonly RedactionTarget[],
+  path: string
+): string {
+  return applyTargets(
+    input,
+    targets.filter((target) => shouldApplyTargetAtPath(target, path))
+  );
+}
+
+function redactValue(value: unknown, targets: readonly RedactionTarget[], path = ''): unknown {
+  if (typeof value === 'string') return applyTargetsAtPath(value, targets, path);
+  if (Array.isArray(value)) {
+    return value.map((item, index) => redactValue(item, targets, `${path}[${index}]`));
+  }
+  if (!isRecord(value)) return value;
+  if (shouldPreserveRecord(value, path)) return value;
+  return redactRecord(value, targets, path);
+}
+
+function shouldPreserveRecord(value: Record<string, unknown>, path: string): boolean {
+  return (
+    shouldPreserveRedactionMetadataRecord(value, path) ||
+    shouldPreserveCredentialPresenceRecord(value, path)
+  );
+}
+
+function redactRecord(
+  value: Record<string, unknown>,
+  targets: readonly RedactionTarget[],
+  path: string
+): Record<string, unknown> {
+  const redacted: Record<string, unknown> = {};
+  for (const [key, item] of Object.entries(value)) {
+    const keyPath = path ? `${path}.${key}` : key;
+    redacted[key] = redactRecordItem(key, item, targets, keyPath);
+  }
+  return redacted;
+}
+
+function redactRecordItem(
+  key: string,
+  item: unknown,
+  targets: readonly RedactionTarget[],
+  path: string
+): unknown {
+  if (typeof item === 'string' && item.length > 0 && shouldRedactSecretKey(key)) {
+    return `${REDACTED_PREFIX}${key}]`;
+  }
+  return redactValue(item, targets, path);
+}
+
+export function redactString(
+  value: string,
+  env: Readonly<Record<string, string>> = {}
+): RedactionResult {
+  const targets = targetsFromEnv(env);
+  return {
+    value: applyTargetsAtPath(value, targets, 'value'),
+    redactions: dedupeMetadata(targets.map(metadataFor)),
+  };
+}
+
+export function redactObject(
+  value: unknown,
+  env: Readonly<Record<string, string>> = {}
+): RedactionResult {
+  const targets = [
+    ...targetsFromEnv(env),
+    ...collectSecretKeyTargets(value),
+    ...collectSecretValueTargets(value),
+  ];
+  return {
+    value: redactValue(value, targets),
+    redactions: dedupeMetadata(targets.map(metadataFor)),
+  };
+}
+
+export function mergeRedactions(
+  ...metadataGroups: readonly (readonly RedactionMetadata[] | undefined)[]
+): readonly RedactionMetadata[] {
+  return dedupeMetadata(metadataGroups.flatMap((metadata) => metadata ?? []));
+}

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

@@ -0,0 +1,115 @@
+import { randomUUID } from 'node:crypto';
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+
+import { parseJson, stringifyJson } from './json';
+
+type SchemaObject = Record<string, unknown> | readonly unknown[];
+
+function isSchemaObject(schema: unknown): schema is SchemaObject {
+  return typeof schema === 'object' && schema !== null;
+}
+
+function shallowCopySchemaObject(schema: SchemaObject): Record<string, unknown> {
+  const result: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(schema)) {
+    result[key] = value;
+  }
+  return result;
+}
+
+function objectKeys(schema: unknown): string[] {
+  return isSchemaObject(schema) ? Object.keys(schema) : [];
+}
+
+function enforceSchemaNode(schema: unknown): unknown {
+  if (!isSchemaObject(schema)) {
+    return schema;
+  }
+
+  const result = shallowCopySchemaObject(schema);
+  enforceObjectSchema(result);
+  enforceProperties(result);
+  enforceItems(result);
+  enforceCompositionKeywords(result);
+  enforceAdditionalProperties(result);
+  return result;
+}
+
+function enforceObjectSchema(result: Record<string, unknown>): void {
+  if (result.type === 'object') {
+    result.additionalProperties = false;
+    if (result.properties) {
+      result.required = objectKeys(result.properties);
+    }
+  }
+}
+
+function enforceProperties(result: Record<string, unknown>): void {
+  const properties = result.properties;
+  if (isSchemaObject(properties)) {
+    const strictProperties: Record<string, unknown> = {};
+    for (const [key, value] of Object.entries(properties)) {
+      strictProperties[key] = enforceSchemaNode(value);
+    }
+    result.properties = strictProperties;
+  }
+}
+
+function enforceItems(result: Record<string, unknown>): void {
+  if (result.items) {
+    result.items = enforceSchemaNode(result.items);
+  }
+}
+
+function enforceCompositionKeywords(result: Record<string, unknown>): void {
+  for (const key of ['anyOf', 'oneOf', 'allOf']) {
+    const value = result[key];
+    if (Array.isArray(value)) {
+      result[key] = value.map((item) => enforceSchemaNode(item));
+    }
+  }
+}
+
+function enforceAdditionalProperties(result: Record<string, unknown>): void {
+  const additionalProperties = result.additionalProperties;
+  if (additionalProperties && isSchemaObject(additionalProperties)) {
+    result.additionalProperties = enforceSchemaNode(additionalProperties);
+  }
+}
+
+export function enforceOpenAIStrictSchema(schema: unknown): unknown {
+  return enforceSchemaNode(schema);
+}
+
+export function schemaToPromptString(schema: unknown): string {
+  return typeof schema === 'string' ? schema : stringifyJson(schema, 2);
+}
+
+export function appendJsonSchemaPrompt(context: string, schema: unknown): string {
+  const schemaString = schemaToPromptString(schema);
+  return (
+    context +
+    `\n\n## OUTPUT FORMAT (CRITICAL - REQUIRED)
+
+You MUST respond with a JSON object that exactly matches this schema. NO markdown, NO explanation, NO code blocks. ONLY the raw JSON object.
+
+Schema:
+\`\`\`json
+${schemaString}
+\`\`\`
+
+Your response must be ONLY valid JSON. Start with { and end with }. Nothing else.`
+  );
+}
+
+export function writeStrictOutputSchemaFile(schema: unknown): string {
+  const parsedSchema = typeof schema === 'string' ? parseJson(schema) : schema;
+  const strictSchema = enforceOpenAIStrictSchema(parsedSchema);
+  const schemaText = stringifyJson(strictSchema, 2);
+  const schemaDir = fs.mkdtempSync(path.join(os.tmpdir(), 'zeroshot-schema-'));
+  const schemaFile = path.join(schemaDir, `${randomUUID()}.json`);
+  fs.writeFileSync(schemaFile, schemaText, { flag: 'wx', mode: 0o600 });
+  return schemaFile;
+}