@bbigbang/agent-node 0.1.0

package/dist/native-worker/native-worker.mjs

@@ -0,0 +1,475 @@
+import { existsSync, mkdirSync, readFileSync, realpathSync, statSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+
+/**
+ * Native mission worker script.
+ *
+ * Receives feature context via environment variables (`NATIVE_WORKER_CONTEXT`)
+ * or a JSON file (`NATIVE_WORKER_CONTEXT_FILE`), calls an OpenAI-compatible
+ * LLM API directly with built-in `fetch`, performs workspace file operations,
+ * and writes a structured JSON output file for the runner to consume.
+ *
+ * Hardening features:
+ *  - Output schema versioning (`schemaVersion`)
+ *  - Retryable vs terminal error classification
+ *  - Structured workspace file operation capture (`fileOperations`)
+ *  - Explicit model/provider/env visibility in output and logs
+ */
+
+const SCHEMA_VERSION = '1.0.0';
+const STDOUT_LIMIT = 8_000;
+const STDERR_LIMIT = 8_000;
+
+// Environment variables that influence worker behavior. Values are surfaced in
+// output.runtimeConfig.env so the exact runtime configuration is auditable;
+// secrets are redacted to avoid leaking credentials.
+const VISIBLE_ENV_VARS = [
+  'OPENAI_API_BASE',
+  'NATIVE_WORKER_TIMEOUT_MS',
+  'NATIVE_WORKER_GRACE_PERIOD_MS',
+];
+
+function main() {
+  run()
+    .then(({ exitCode }) => {
+      process.exit(exitCode);
+    })
+    .catch((error) => {
+      console.error('[native-worker] unhandled error:', error);
+      process.exit(1);
+    });
+}
+
+async function run() {
+  let rawContext;
+  try {
+    rawContext = readContext();
+  } catch (error) {
+    console.error('[native-worker]', error);
+    return { exitCode: 1 };
+  }
+
+  let context;
+  try {
+    context = JSON.parse(rawContext);
+    validateContext(context);
+    context.featureId = sanitizeFeatureId(context.featureId);
+  } catch (error) {
+    console.error('[native-worker]', error);
+    return { exitCode: 1 };
+  }
+
+  let workspaceRoot;
+  let missionDir;
+  try {
+    workspaceRoot = resolveSafePath(context.workspaceRoot, null);
+    missionDir = resolveSafePath(context.missionDir, workspaceRoot);
+  } catch (error) {
+    const message = String(error?.message ?? error);
+    console.error('[native-worker]', message);
+    return { exitCode: 1 };
+  }
+
+  const fileOps = new FileOperationTracker(workspaceRoot);
+  const contextFile = process.env.NATIVE_WORKER_CONTEXT_FILE;
+  if (contextFile && !process.env.NATIVE_WORKER_CONTEXT) {
+    fileOps.record(contextFile, 'read');
+  }
+
+  const runtimeConfig = buildRuntimeConfig(context);
+  logRuntimeConfig(runtimeConfig);
+
+  const stdoutLines = [
+    `Native worker started for ${context.featureId}`,
+    `Schema version: ${SCHEMA_VERSION}`,
+    `Model: ${runtimeConfig.model}`,
+    `Provider base URL: ${runtimeConfig.providerBaseUrl}`,
+    `Timeout: ${runtimeConfig.workerTimeoutMs}ms`,
+    `Grace period: ${runtimeConfig.workerGracePeriodMs}ms`,
+  ];
+  const stderrLines = [];
+
+  let llmResult;
+  try {
+    llmResult = await callLlm(context, runtimeConfig);
+  } catch (error) {
+    const classification = classifyLlmError(error);
+    const message = String(error?.message ?? error);
+    stderrLines.push(message);
+    writeFailure(context, missionDir, fileOps, runtimeConfig, stdoutLines.join('\n'), stderrLines.join('\n'), message, classification);
+    return { exitCode: 1 };
+  }
+
+  // Workspace file operation: write a durable marker inside the workspace root.
+  const markerRelative = path.join('.bigbang', 'native-worker-runs', context.featureId, 'marker.md');
+  const markerPath = path.join(workspaceRoot, markerRelative);
+  try {
+    ensureInsideWorkspace(markerPath, workspaceRoot);
+    fileOps.record(path.dirname(markerPath), 'mkdir');
+    mkdirSync(path.dirname(markerPath), { recursive: true });
+    const existedBefore = existsSync(markerPath);
+    const content = buildMarkerContent(context, llmResult, runtimeConfig);
+    fileOps.record(markerPath, existedBefore ? 'modify' : 'create', { size: Buffer.byteLength(content, 'utf8') });
+    writeFileSync(markerPath, content, 'utf8');
+  } catch (error) {
+    const classification = classifyWorkspaceError(error);
+    const message = String(error?.message ?? error);
+    stderrLines.push(message);
+    writeFailure(context, missionDir, fileOps, runtimeConfig, stdoutLines.join('\n'), stderrLines.join('\n'), message, classification);
+    return { exitCode: 1 };
+  }
+
+  const implementedFiles = [markerPath];
+
+  // Workspace file operation: touch a small run receipt in the mission dir so
+  // that "touched" operations appear in fileOperations as well.
+  const receiptPath = path.join(missionDir, 'native-output', `${context.featureId}-receipt.txt`);
+  try {
+    ensureInsideWorkspace(receiptPath, workspaceRoot);
+    fileOps.record(receiptPath, 'touch');
+    writeFileSync(receiptPath, `${context.featureId} ${Date.now()}\n`, 'utf8');
+  } catch (error) {
+    // Receipt is non-critical; log but do not fail the feature.
+    stderrLines.push(String(error?.message ?? error));
+  }
+
+  const handoff = {
+    salientSummary: `Native worker completed feature ${context.featureId}.`,
+    verification: {
+      markerPath,
+      markerRelative,
+      llmUsed: llmResult.used,
+      model: llmResult.model,
+    },
+    discoveredIssues: [],
+  };
+
+  if (llmResult.used && typeof llmResult.response === 'string' && llmResult.response.length > 0) {
+    handoff.llmResponsePreview = llmResult.response.slice(0, 2_000);
+  }
+
+  writeOutput(context, missionDir, {
+    schemaVersion: SCHEMA_VERSION,
+    featureId: context.featureId,
+    status: 'completed',
+    implementedFiles,
+    fileOperations: fileOps.toArray(),
+    runtimeConfig,
+    handoff,
+    stdout: truncateLines(stdoutLines.join('\n'), STDOUT_LIMIT),
+    stderr: truncateLines(stderrLines.join('\n'), STDERR_LIMIT),
+    exitCode: 0,
+  });
+
+  return { exitCode: 0 };
+}
+
+function readContext() {
+  const envRaw = process.env.NATIVE_WORKER_CONTEXT;
+  if (envRaw) {
+    return envRaw;
+  }
+
+  const contextFile = process.env.NATIVE_WORKER_CONTEXT_FILE;
+  if (contextFile) {
+    return readFileSync(contextFile, 'utf8');
+  }
+
+  throw new Error('NATIVE_WORKER_CONTEXT or NATIVE_WORKER_CONTEXT_FILE is required.');
+}
+
+function validateContext(context) {
+  if (!context || typeof context !== 'object') {
+    throw new Error('Feature context must be an object.');
+  }
+  const requiredStringFields = ['featureId', 'featureDescription', 'milestone', 'workspaceRoot', 'missionDir'];
+  for (const field of requiredStringFields) {
+    const value = context[field];
+    if (typeof value !== 'string' || value.trim() === '') {
+      throw new Error(`Feature context is missing required field: ${field}`);
+    }
+  }
+}
+
+const SAFE_FEATURE_ID_RE = /^[a-zA-Z0-9_-]+$/;
+
+function sanitizeFeatureId(featureId) {
+  const trimmed = featureId.trim();
+  if (!SAFE_FEATURE_ID_RE.test(trimmed)) {
+    throw new Error(`featureId contains unsafe characters: ${featureId}`);
+  }
+  return trimmed;
+}
+
+function resolveSafePath(value, base) {
+  const resolved = path.resolve(value);
+  if (!existsSync(resolved)) {
+    throw new Error(`Path does not exist: ${value}`);
+  }
+  const real = realpathSync(resolved);
+  if (base) {
+    const realBase = realpathSync(base);
+    const relative = path.relative(realBase, real);
+    if (relative.startsWith('..') || path.isAbsolute(relative)) {
+      throw new Error(`Path escapes allowed workspace: ${value}`);
+    }
+  }
+  return real;
+}
+
+function ensureInsideWorkspace(targetPath, workspaceRoot) {
+  const realBase = realpathSync(workspaceRoot);
+  const resolved = path.resolve(targetPath);
+  let ancestor = resolved;
+  while (!existsSync(ancestor)) {
+    const parent = path.dirname(ancestor);
+    if (parent === ancestor) break;
+    ancestor = parent;
+  }
+  const realAncestor = realpathSync(ancestor);
+  const relative = path.relative(realBase, realAncestor);
+  if (relative.startsWith('..') || path.isAbsolute(relative)) {
+    throw new Error(`Target path escapes workspace: ${targetPath}`);
+  }
+}
+
+function resolveProviderBaseUrl() {
+  const baseUrl = process.env.OPENAI_API_BASE?.replace(/\/$/, '') ?? 'https://api.openai.com/v1';
+  // Redact any embedded credentials from the logged URL.
+  try {
+    const url = new URL(baseUrl);
+    url.username = '';
+    url.password = '';
+    return url.toString().replace(/\/$/, '');
+  } catch {
+    return baseUrl;
+  }
+}
+
+function buildRuntimeConfig(context) {
+  const model = context.workerModel ?? context.orchestratorModel ?? 'gpt-4o-mini';
+  const providerBaseUrl = resolveProviderBaseUrl();
+  return {
+    model,
+    modelMode: context.modelMode ?? 'platform_default',
+    orchestratorModel: context.orchestratorModel ?? null,
+    workerModel: context.workerModel ?? null,
+    validatorModel: context.validatorModel ?? null,
+    providerBaseUrl,
+    apiKeyConfigured: Boolean(process.env.OPENAI_API_KEY),
+    workerTimeoutMs: Number(process.env.NATIVE_WORKER_TIMEOUT_MS ?? 300_000),
+    workerGracePeriodMs: Number(process.env.NATIVE_WORKER_GRACE_PERIOD_MS ?? 5_000),
+    platform: process.platform,
+    nodeVersion: process.version,
+    env: buildVisibleEnv(),
+  };
+}
+
+function buildVisibleEnv() {
+  const env = {};
+  for (const key of VISIBLE_ENV_VARS) {
+    const value = process.env[key];
+    if (value !== undefined) {
+      env[key] = key.toLowerCase().includes('key') ? '[redacted]' : value;
+    }
+  }
+  return env;
+}
+
+function logRuntimeConfig(runtimeConfig) {
+  console.log('[native-worker] runtime config:', JSON.stringify({
+    ...runtimeConfig,
+    apiKeyConfigured: runtimeConfig.apiKeyConfigured ? 'yes' : 'no',
+  }));
+}
+
+async function callLlm(context, runtimeConfig) {
+  const apiKey = process.env.OPENAI_API_KEY;
+  if (!apiKey) {
+    const error = new Error('OPENAI_API_KEY is not configured in the worker environment.');
+    error.code = 'ENOKEY';
+    throw error;
+  }
+
+  const model = runtimeConfig.model;
+  const baseUrl = runtimeConfig.providerBaseUrl;
+
+  let response;
+  try {
+    response = await fetch(`${baseUrl}/chat/completions`, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        Authorization: `Bearer ${apiKey}`,
+      },
+      body: JSON.stringify({
+        model,
+        messages: [
+          { role: 'system', content: 'You are a helpful software engineering assistant.' },
+          { role: 'user', content: context.prompt },
+        ],
+      }),
+    });
+  } catch (error) {
+    // Network-level failures (timeout, DNS, connection reset) are retryable.
+    throw Object.assign(new Error(`LLM network error: ${String(error?.message ?? error)}`), { llmErrorKind: 'network' });
+  }
+
+  if (!response.ok) {
+    const status = response.status;
+    const statusText = response.statusText;
+    let bodyText = '';
+    try {
+      bodyText = await response.text();
+    } catch {
+      // Ignore body read failures.
+    }
+    const error = new Error(`LLM request failed: ${status} ${statusText}${bodyText ? ` - ${bodyText.slice(0, 500)}` : ''}`);
+    error.status = status;
+    error.llmErrorKind = 'http';
+    throw error;
+  }
+
+  const data = await response.json();
+  const choices = Array.isArray(data.choices) ? data.choices : [];
+  const first = choices[0];
+  const message = first?.message ?? {};
+  const content = typeof message.content === 'string' ? message.content : '';
+
+  if (choices.length === 0 && data.error) {
+    const upstreamError = new Error(`LLM upstream error: ${JSON.stringify(data.error).slice(0, 500)}`);
+    upstreamError.llmErrorKind = 'upstream';
+    throw upstreamError;
+  }
+
+  return { used: true, model, response: content };
+}
+
+function classifyLlmError(error) {
+  if (error?.code === 'ENOKEY') {
+    return { kind: 'terminal', category: 'auth_failure' };
+  }
+
+  const status = typeof error?.status === 'number' ? error.status : undefined;
+  const message = String(error?.message ?? error ?? '').toLowerCase();
+  const kind = error?.llmErrorKind;
+
+  if (status === 401) {
+    return { kind: 'terminal', category: 'auth_failure' };
+  }
+  if (status === 403) {
+    return { kind: 'terminal', category: 'permission_denied' };
+  }
+  if (status === 429) {
+    return { kind: 'retryable', category: 'rate_limit' };
+  }
+  if (status === 400 || status === 404) {
+    return { kind: 'terminal', category: 'invalid_model' };
+  }
+  if (kind === 'network' || message.includes('timeout') || message.includes('abort') || message.includes('econnreset') || message.includes('etimedout')) {
+    return { kind: 'retryable', category: 'network_timeout' };
+  }
+  if (status >= 500 || kind === 'upstream') {
+    return { kind: 'retryable', category: 'llm_error' };
+  }
+  return { kind: 'retryable', category: 'llm_error' };
+}
+
+function classifyWorkspaceError(error) {
+  const code = error?.code;
+  const message = String(error?.message ?? error ?? '').toLowerCase();
+  if (code === 'EACCES' || code === 'EPERM' || message.includes('permission denied')) {
+    return { kind: 'terminal', category: 'permission_denied' };
+  }
+  if (code === 'EEXIST' || code === 'ENOTDIR' || message.includes('not a directory') || message.includes('file already exists')) {
+    return { kind: 'terminal', category: 'workspace_error' };
+  }
+  if (code === 'ENOSPC' || message.includes('no space')) {
+    return { kind: 'terminal', category: 'workspace_error' };
+  }
+  if (message.includes('escapes workspace')) {
+    return { kind: 'terminal', category: 'permission_denied' };
+  }
+  return { kind: 'retryable', category: 'workspace_error' };
+}
+
+class FileOperationTracker {
+  constructor(workspaceRoot) {
+    this.workspaceRoot = workspaceRoot;
+    this.operations = [];
+  }
+
+  record(absolutePath, operation, extra = {}) {
+    const relativePath = path.relative(this.workspaceRoot, absolutePath) || '.';
+    this.operations.push({
+      path: absolutePath,
+      relativePath,
+      operation,
+      ...extra,
+      timestamp: Date.now(),
+    });
+  }
+
+  toArray() {
+    return this.operations;
+  }
+}
+
+function outputPath(context, missionDir) {
+  return path.join(missionDir, 'native-output', `${context.featureId}.json`);
+}
+
+function writeOutput(context, missionDir, output) {
+  const outPath = outputPath(context, missionDir);
+  mkdirSync(path.dirname(outPath), { recursive: true });
+  writeFileSync(outPath, `${JSON.stringify(output, null, 2)}\n`, 'utf8');
+}
+
+function writeFailure(context, missionDir, fileOps, runtimeConfig, stdout, stderr, error, classification) {
+  try {
+    writeOutput(context, missionDir, {
+      schemaVersion: SCHEMA_VERSION,
+      featureId: context.featureId,
+      status: 'failed',
+      implementedFiles: [],
+      fileOperations: fileOps.toArray(),
+      runtimeConfig,
+      errorClassification: classification,
+      handoff: {
+        salientSummary: 'Native worker failed.',
+        discoveredIssues: [error],
+      },
+      stdout: truncateLines(stdout, STDOUT_LIMIT),
+      stderr: truncateLines(stderr, STDERR_LIMIT),
+      exitCode: 1,
+    });
+  } catch (writeError) {
+    console.error('[native-worker] failed to write failure output:', writeError);
+  }
+}
+
+function buildMarkerContent(context, llmResult, runtimeConfig) {
+  const lines = [
+    '# Native worker run',
+    '',
+    `Feature: ${context.featureId}`,
+    `Milestone: ${context.milestone}`,
+    `Description: ${context.featureDescription}`,
+  ];
+  if (context.title) {
+    lines.push(`Title: ${context.title}`);
+  }
+  if (llmResult.used) {
+    lines.push(`Model: ${llmResult.model}`);
+  }
+  lines.push(`Provider base URL: ${runtimeConfig.providerBaseUrl}`);
+  lines.push('', `Generated at: ${new Date().toISOString()}`);
+  return lines.join('\n') + '\n';
+}
+
+function truncateLines(value, limit) {
+  if (value.length <= limit) return value;
+  return `${value.slice(0, limit)}\n[truncated]`;
+}
+
+main();