ag-ai 0.1.0

package/runtime/bridge.mjs

@@ -0,0 +1,1093 @@
+/* eslint-disable no-await-in-loop, no-console */
+/* eslint-disable import/extensions -- Native Node ESM requires file extensions. */
+
+import { randomUUID } from 'node:crypto';
+import { mkdir, readFile, realpath, rm, lstat, writeFile, rename } from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { createOpenCodeExecutor, DEFAULT_OPENCODE_URL } from './executor/opencode.mjs';
+import { createImageAdapter } from './image/adapter.mjs';
+import { normalizeGenerationRequest } from './protocol.mjs';
+import { createLocalRunner, startGenerationServer } from './server.mjs';
+import { GenerationStore } from './store.mjs';
+import { AnalyticaEvents } from './telemetry.mjs';
+
+// Generic placeholder: the queue endpoint must be supplied through AG_AI_QUEUE_URL.
+const DEFAULT_QUEUE_URL = 'https://queue.invalid/api/ai/runner';
+const DEFAULT_TOKEN_FILE = '/var/run/secrets/ag-ai-runner/token';
+const DEFAULT_WORKSPACE = '/workspace';
+const DEFAULT_MAIN_WORKSPACE = '/data/workspace';
+const DEFAULT_GENERATED_IMAGES = '/generated-images';
+const DEFAULT_MAIN_GENERATED_IMAGES = '/data/ag-ai/generated_images';
+const DEFAULT_GENERATION_PORT = 4501;
+const DEFAULT_GENERATION_STORE = '/generation-jobs';
+const DEFAULT_GENERATION_TOKEN_FILE = '/var/run/secrets/ag-ai-generation/token';
+const DEFAULT_ANALYTICA_TOKEN_FILE = '/var/run/secrets/ag-ai-analytica/token';
+const DEFAULT_IMAGE_PROVIDER = 'openai';
+const HEARTBEAT_INTERVAL_MS = 10_000;
+const LEASE_HEARTBEAT_INTERVAL_MS = 5_000;
+const HEALTH_INTERVAL_MS = 30_000;
+const CLAIM_INTERVAL_MS = 5_000;
+const REQUEST_TIMEOUT_MS = 15_000;
+const TURN_TIMEOUT_MS = 30 * 60 * 1000;
+const SHUTDOWN_TIMEOUT_MS = 10_000;
+const MAX_HTTP_JSON_BYTES = 2 * 1024 * 1024;
+const MAX_HTTP_INPUT_BYTES = 64 * 1024 * 1024;
+const MAX_HTTP_ERROR_BYTES = 16 * 1024;
+const MAX_OUTPUT_IMAGE_BYTES = 25 * 1024 * 1024;
+const MAX_OUTPUT_IMAGE_TOTAL_BYTES = 40 * 1024 * 1024;
+const MAX_OUTPUT_IMAGES = 4;
+const MAX_OUTPUT_TEXT_BYTES = 2 * 1024 * 1024;
+const MAX_ID_LENGTH = 160;
+const SAFE_ID = /^[A-Za-z0-9][A-Za-z0-9._~-]{0,159}$/;
+const BASE64 = /^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/;
+const PNG_SIGNATURE = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
+
+class UncertainRequestError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = 'UncertainRequestError';
+  }
+}
+
+class RunnerHttpError extends Error {
+  constructor(status, message) {
+    super(`runner HTTP ${status}: ${message}`);
+    this.name = 'RunnerHttpError';
+    this.status = status;
+  }
+}
+
+class JobError extends Error {
+  constructor(message, outcome = 'failed') {
+    super(message);
+    this.name = 'JobError';
+    this.outcome = outcome;
+  }
+}
+
+const asObject = (value) => (value && typeof value === 'object' ? value : null);
+
+const boundedString = (value, maxLength, name) => {
+  if (typeof value !== 'string' || value.length > maxLength) {
+    throw new JobError(`${name} is missing or too long`);
+  }
+
+  return value;
+};
+
+const boundedId = (value, name) => {
+  if (
+    typeof value !== 'string' ||
+    value.length === 0 ||
+    value.length > MAX_ID_LENGTH ||
+    !SAFE_ID.test(value)
+  ) {
+    throw new JobError(`${name} is not a safe identifier`);
+  }
+
+  return value;
+};
+
+const boundedInteger = (value, name, min, max) => {
+  if (!Number.isInteger(value) || value < min || value > max) {
+    throw new JobError(`${name} is outside its allowed range`);
+  }
+
+  return value;
+};
+
+const delay = (milliseconds) => new Promise((resolve) => setTimeout(resolve, milliseconds));
+
+const errorMessage = (error) => {
+  if (error instanceof Error) {
+    return error.message.slice(0, 500);
+  }
+
+  return String(error).slice(0, 500);
+};
+
+const redact = (value, secrets = []) => {
+  let message = errorMessage(value);
+  for (const secret of secrets) {
+    if (secret) {
+      message = message.split(secret).join('[redacted]');
+    }
+  }
+
+  return message.replace(/(bearer\s+)[^\s]+/gi, '$1[redacted]');
+};
+
+const parseJson = (bytes, label) => {
+  try {
+    return JSON.parse(bytes.toString('utf8'));
+  } catch {
+    throw new Error(`${label} was not valid JSON`);
+  }
+};
+
+const readResponseBytes = async (response, maximum) => {
+  const contentLength = Number(response.headers.get('content-length'));
+  if (Number.isFinite(contentLength) && contentLength > maximum) {
+    throw new Error(`response exceeds ${maximum} bytes`);
+  }
+
+  if (!response.body) {
+    return Buffer.alloc(0);
+  }
+
+  const reader = response.body.getReader();
+  const chunks = [];
+  let total = 0;
+  try {
+    for (;;) {
+      const { done, value } = await reader.read();
+      if (done) {
+        break;
+      }
+
+      const chunk = Buffer.from(value);
+      total += chunk.length;
+      if (total > maximum) {
+        await reader.cancel();
+        throw new Error(`response exceeds ${maximum} bytes`);
+      }
+
+      chunks.push(chunk);
+    }
+  } finally {
+    reader.releaseLock();
+  }
+
+  return Buffer.concat(chunks, total);
+};
+
+const timeoutSignal = (milliseconds) => {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), milliseconds);
+  return { signal: controller.signal, cancel: () => clearTimeout(timer) };
+};
+
+const normalizeBaseUrl = (value) => {
+  let url;
+  try {
+    url = new URL(value);
+  } catch {
+    throw new Error('AG_AI_QUEUE_URL must be an absolute URL');
+  }
+
+  if (url.protocol !== 'https:') {
+    throw new Error('AG_AI_QUEUE_URL must be an absolute https URL');
+  }
+  if (url.username || url.password || url.search || url.hash) {
+    throw new Error('AG_AI_QUEUE_URL must not contain credentials, query, or fragment');
+  }
+
+  return url;
+};
+
+const urlFor = (baseUrl, suffix) => {
+  const base = baseUrl.href.endsWith('/') ? baseUrl.href : `${baseUrl.href}/`;
+  return new URL(suffix.replace(/^\/+/, ''), base);
+};
+
+const responseErrorMessage = (body) => {
+  const text = body.toString('utf8').replace(/\s+/g, ' ').trim();
+  return text.slice(0, 500) || 'request failed';
+};
+
+const runnerRequestRoute = (suffix) => {
+  const pathName = String(suffix)
+    .split('?', 1)[0]
+    .replace(/^\/+|\/+$/g, '');
+  if (pathName === 'heartbeat' || pathName === 'claim') return pathName;
+  const match = /^jobs\/[^/]+\/(input|heartbeat|upload|complete|fail)$/.exec(pathName);
+  if (!match) return 'unknown';
+  return match[1] === 'heartbeat' ? 'lease-heartbeat' : match[1];
+};
+
+const JOB_ROUTES = new Set(['input', 'upload', 'complete', 'fail']);
+
+const emitRunnerHttpEvent = (analytics, route, ...segments) => {
+  if (!JOB_ROUTES.has(route)) return;
+  void analytics.emit('runner-http', route, ...segments);
+};
+
+class RunnerClient {
+  constructor({ baseUrl, token, runnerId, analytics, fetchImpl = globalThis.fetch }) {
+    this.baseUrl = normalizeBaseUrl(baseUrl);
+    this.token = boundedString(token, 4096, 'runner token');
+    if (this.token.length === 0) {
+      throw new Error('runner token is empty');
+    }
+
+    this.runnerId = boundedString(runnerId, MAX_ID_LENGTH, 'runner id');
+    if (this.runnerId.length === 0) {
+      throw new Error('runner id is empty');
+    }
+    if (typeof fetchImpl !== 'function') {
+      throw new Error('runner fetch implementation is required');
+    }
+    this.analytics = analytics;
+    this.fetchImpl = fetchImpl;
+  }
+
+  async request(
+    method,
+    suffix,
+    {
+      body,
+      leaseToken,
+      timeoutMs = REQUEST_TIMEOUT_MS,
+      responseLimit = MAX_HTTP_JSON_BYTES,
+      uncertainOnNetwork = false,
+    } = {},
+  ) {
+    const timeout = timeoutSignal(timeoutMs);
+    const route = runnerRequestRoute(suffix);
+    const verb = method.toLowerCase();
+    let responseObserved = false;
+    emitRunnerHttpEvent(this.analytics, route, verb, 'requested');
+    const headers = {
+      accept: 'application/json',
+      authorization: `Bearer ${this.token}`,
+    };
+    if (body !== undefined) {
+      headers['content-type'] = 'application/json';
+    }
+    if (leaseToken) {
+      headers['x-ai-lease-token'] = leaseToken;
+    }
+
+    const fetchOptions = {
+      method,
+      headers,
+      signal: timeout.signal,
+      redirect: 'error',
+    };
+    if (body !== undefined) {
+      fetchOptions.body = JSON.stringify(body);
+    }
+    try {
+      const response = await this.fetchImpl(urlFor(this.baseUrl, suffix), fetchOptions);
+      responseObserved = true;
+      emitRunnerHttpEvent(this.analytics, route, verb, 'responded', response.status);
+      const responseBody = await readResponseBytes(
+        response,
+        response.ok ? responseLimit : MAX_HTTP_ERROR_BYTES,
+      );
+      if (!response.ok) {
+        throw new RunnerHttpError(
+          response.status,
+          redact(responseErrorMessage(responseBody), [this.token, leaseToken]),
+        );
+      }
+
+      if (responseBody.length === 0) {
+        return {};
+      }
+
+      return parseJson(responseBody, 'runner response');
+    } catch (error) {
+      if (!responseObserved) emitRunnerHttpEvent(this.analytics, route, verb, 'failed');
+      if (error instanceof RunnerHttpError) {
+        throw error;
+      }
+      const message = redact(error, [this.token, leaseToken]);
+      throw uncertainOnNetwork ? new UncertainRequestError(message) : new Error(message);
+    } finally {
+      timeout.cancel();
+    }
+  }
+
+  async requestBytes(suffix, bytes, { name, contentType, leaseToken } = {}) {
+    const timeout = timeoutSignal(REQUEST_TIMEOUT_MS);
+    const route = runnerRequestRoute(suffix);
+    let responseObserved = false;
+    emitRunnerHttpEvent(this.analytics, route, 'post', 'requested');
+    const headers = {
+      accept: 'application/json',
+      authorization: `Bearer ${this.token}`,
+      'content-type': contentType,
+      'x-ai-result-name': name,
+      'x-ai-lease-token': leaseToken,
+    };
+
+    try {
+      const response = await this.fetchImpl(urlFor(this.baseUrl, suffix), {
+        method: 'POST',
+        headers,
+        body: bytes,
+        signal: timeout.signal,
+        redirect: 'error',
+      });
+      responseObserved = true;
+      emitRunnerHttpEvent(this.analytics, route, 'post', 'responded', response.status);
+      const responseBody = await readResponseBytes(
+        response,
+        response.ok ? MAX_HTTP_JSON_BYTES : MAX_HTTP_ERROR_BYTES,
+      );
+      if (!response.ok) {
+        throw new RunnerHttpError(
+          response.status,
+          redact(responseErrorMessage(responseBody), [this.token, leaseToken]),
+        );
+      }
+
+      return parseJson(responseBody, 'runner upload response');
+    } catch (error) {
+      if (!responseObserved) emitRunnerHttpEvent(this.analytics, route, 'post', 'failed');
+      if (error instanceof RunnerHttpError) {
+        throw error;
+      }
+      throw new UncertainRequestError(redact(error, [this.token, leaseToken]));
+    } finally {
+      timeout.cancel();
+    }
+  }
+
+  heartbeat(activeJobs, providerReady, modelReady) {
+    return this.request('POST', 'heartbeat', {
+      body: {
+        runnerId: this.runnerId,
+        authenticatedChatgpt: providerReady,
+        modelReady,
+        activeJobs,
+      },
+    });
+  }
+
+  claim() {
+    return this.request('POST', 'claim', {
+      body: { runnerId: this.runnerId },
+      uncertainOnNetwork: true,
+    });
+  }
+
+  input(jobId, leaseToken) {
+    return this.request('GET', `jobs/${encodeURIComponent(jobId)}/input`, {
+      leaseToken,
+      responseLimit: MAX_HTTP_INPUT_BYTES,
+    });
+  }
+
+  leaseHeartbeat(jobId, leaseToken) {
+    return this.request('POST', `jobs/${encodeURIComponent(jobId)}/heartbeat`, {
+      leaseToken,
+      body: {},
+    });
+  }
+
+  upload(jobId, leaseToken, bytes, name, contentType) {
+    return this.requestBytes(`jobs/${encodeURIComponent(jobId)}/upload`, bytes, {
+      leaseToken,
+      name,
+      contentType,
+    });
+  }
+
+  complete(jobId, leaseToken, payload) {
+    return this.request('POST', `jobs/${encodeURIComponent(jobId)}/complete`, {
+      leaseToken,
+      body: payload,
+    });
+  }
+
+  fail(jobId, leaseToken, error, outcome) {
+    return this.request('POST', `jobs/${encodeURIComponent(jobId)}/fail`, {
+      leaseToken,
+      body: {
+        error: error.slice(0, 10_000),
+        outcome,
+      },
+    });
+  }
+}
+
+const validateJobEnvelope = (value) => {
+  const job = asObject(value);
+  if (!job) {
+    throw new Error('runner claim response did not contain a job object');
+  }
+
+  const id = boundedId(job.id, 'job id');
+  const runId = boundedId(job.runId, 'job runId');
+  const leaseToken = boundedString(job.leaseToken, 4096, 'lease token');
+  if (!leaseToken) {
+    throw new Error('runner claim response contained an empty lease token');
+  }
+
+  const leaseExpiresAt = boundedInteger(
+    job.leaseExpiresAt,
+    'leaseExpiresAt',
+    0,
+    Number.MAX_SAFE_INTEGER,
+  );
+  const model = job.model === undefined ? undefined : boundedString(job.model, 160, 'job model');
+  const reasoningEffort =
+    job.reasoningEffort === undefined
+      ? undefined
+      : boundedString(job.reasoningEffort, 64, 'job reasoning effort');
+  if (model === '' || reasoningEffort === '') {
+    throw new JobError('claimed job model metadata is empty');
+  }
+  return {
+    id,
+    runId,
+    leaseToken,
+    leaseExpiresAt,
+    ...(model === undefined ? {} : { model }),
+    ...(reasoningEffort === undefined ? {} : { reasoningEffort }),
+  };
+};
+
+const safeRoot = async (root, name) => {
+  await mkdir(root, { recursive: true, mode: 0o700 });
+  const resolved = await realpath(root);
+  if (resolved !== path.resolve(root)) {
+    throw new JobError(`${name} resolves unexpectedly`);
+  }
+  return resolved;
+};
+
+const safeChildDirectory = async (root, childName, label) => {
+  boundedId(childName, label);
+  const child = path.join(root, childName);
+  const relative = path.relative(root, child);
+  if (!relative || relative.startsWith('..') || path.isAbsolute(relative)) {
+    throw new JobError(`${label} escaped its workspace`);
+  }
+
+  await mkdir(child, { recursive: true, mode: 0o700 });
+  const resolved = await realpath(child);
+  if (resolved !== child || !(resolved === root || resolved.startsWith(`${root}${path.sep}`))) {
+    throw new JobError(`${label} resolved outside its workspace`);
+  }
+
+  const childStat = await lstat(child);
+  if (!childStat.isDirectory()) {
+    throw new JobError(`${label} is not a directory`);
+  }
+
+  return child;
+};
+
+const removeJobDirectory = async (workspaceRoot, jobDirectory) => {
+  if (!jobDirectory) return;
+  const resolvedRoot = await safeRoot(workspaceRoot, 'workspace root');
+  const resolvedDirectory = await realpath(jobDirectory).catch(() => undefined);
+  if (
+    !resolvedDirectory ||
+    resolvedDirectory === resolvedRoot ||
+    !resolvedDirectory.startsWith(`${resolvedRoot}${path.sep}`)
+  ) {
+    return;
+  }
+  const directoryStat = await lstat(jobDirectory).catch(() => undefined);
+  if (!directoryStat?.isDirectory()) {
+    return;
+  }
+  await rm(jobDirectory, { recursive: true, force: true });
+};
+
+const createCancellation = () => {
+  const controller = new AbortController();
+  let settled = false;
+  let reason;
+  let resolvePromise;
+  const listeners = new Set();
+  const promise = new Promise((resolve) => {
+    resolvePromise = resolve;
+  });
+  return {
+    promise,
+    signal: controller.signal,
+    get cancelled() {
+      return settled;
+    },
+    get reason() {
+      return reason;
+    },
+    onCancel(listener) {
+      if (settled) {
+        return Promise.resolve(listener(reason));
+      }
+      listeners.add(listener);
+      return () => listeners.delete(listener);
+    },
+    cancel(why) {
+      if (!settled) {
+        settled = true;
+        reason = why;
+        resolvePromise(reason);
+        controller.abort();
+        for (const listener of listeners) {
+          Promise.resolve(listener(reason)).catch(() => undefined);
+        }
+        listeners.clear();
+      }
+    },
+  };
+};
+
+const resultText = (result) => {
+  if (!Array.isArray(result?.output)) return '';
+  return result.output
+    .filter((part) => asObject(part)?.type === 'text' && typeof part.text === 'string')
+    .map((part) => part.text)
+    .join('');
+};
+
+const decodeOutputImage = (part) => {
+  const value = asObject(part);
+  if (value?.type !== 'image' || value.mimeType !== 'image/png' || typeof value.data !== 'string') {
+    throw new JobError('model returned an unsupported image output');
+  }
+  if (!BASE64.test(value.data)) {
+    throw new JobError('model returned non-canonical image base64 data');
+  }
+  const bytes = Buffer.from(value.data, 'base64');
+  if (bytes.length === 0 || bytes.length > MAX_OUTPUT_IMAGE_BYTES) {
+    throw new JobError('generated image is outside its size limit');
+  }
+  if (bytes.toString('base64') !== value.data) {
+    throw new JobError('model returned non-canonical image base64 data');
+  }
+  if (
+    bytes.length < PNG_SIGNATURE.length ||
+    !bytes.subarray(0, PNG_SIGNATURE.length).equals(PNG_SIGNATURE)
+  ) {
+    throw new JobError('generated image output is not a PNG');
+  }
+  return bytes;
+};
+
+const parseStructuredOutput = (text, outputSchema) => {
+  if (!outputSchema) {
+    return undefined;
+  }
+
+  try {
+    return JSON.parse(text);
+  } catch {
+    throw new JobError('model did not return valid structured output');
+  }
+};
+
+const safeErrorOutcome = (error) =>
+  error instanceof JobError
+    ? error.outcome
+    : error instanceof UncertainRequestError
+      ? 'unknown'
+      : 'failed';
+
+const cancellationOutcome = (reason) =>
+  reason === 'lease lost' ||
+  reason === 'lease expired' ||
+  reason === 'SIGTERM' ||
+  reason === 'SIGINT' ||
+  reason === 'shutdown'
+    ? 'unknown'
+    : 'cancelled';
+
+const processJob = async (runner, job, config, state, source, analytics) => {
+  const cancellation = createCancellation();
+  state.cancellation = cancellation;
+  void analytics.emit('job', source, 'claimed');
+  let jobDirectory;
+  let leaseLost = false;
+  let leaseExpiresAt = job.leaseExpiresAt;
+  let leaseHeartbeatInFlight = false;
+  const leaseTimer = setInterval(() => {
+    if (leaseHeartbeatInFlight) {
+      return;
+    }
+    if (Date.now() >= leaseExpiresAt) {
+      leaseLost = true;
+      cancellation.cancel('lease expired');
+      return;
+    }
+    leaseHeartbeatInFlight = true;
+    runner
+      .leaseHeartbeat(job.id, job.leaseToken)
+      .then((response) => {
+        if (Number.isInteger(response?.leaseExpiresAt)) {
+          leaseExpiresAt = response.leaseExpiresAt;
+        }
+        if (leaseExpiresAt <= Date.now()) {
+          leaseLost = true;
+          cancellation.cancel('lease expired');
+        }
+        if (response?.cancelRequested === true) {
+          cancellation.cancel('cancel requested');
+        }
+      })
+      .catch((error) => {
+        if (error instanceof RunnerHttpError && error.status === 409) {
+          leaseLost = true;
+          cancellation.cancel('lease lost');
+        } else {
+          console.error(`[runner] lease heartbeat failed: ${redact(error, [job.leaseToken])}`);
+          if (Date.now() >= leaseExpiresAt) {
+            leaseLost = true;
+            cancellation.cancel('lease expired');
+          }
+        }
+      })
+      .finally(() => {
+        leaseHeartbeatInFlight = false;
+      });
+  }, LEASE_HEARTBEAT_INTERVAL_MS);
+
+  let turnTimer;
+  try {
+    if (job.leaseExpiresAt <= Date.now()) {
+      throw new JobError('claimed job lease has already expired', 'unknown');
+    }
+    const inputEnvelope = await runner.input(job.id, job.leaseToken);
+    void analytics.emit('job', source, 'input-loaded');
+    const models = state.health.models ?? [];
+    const normalizedInput = normalizeGenerationRequest(inputEnvelope, models);
+    void analytics.emit('job', source, 'input-validated');
+
+    const jobDirectoryName = `runner-${job.id}`;
+    jobDirectory = await safeChildDirectory(config.workspace, jobDirectoryName, 'job directory');
+    const mainJobDirectory = path.join(config.mainWorkspace, jobDirectoryName);
+    const mainRoot = path.resolve(config.mainWorkspace);
+    const mainResolved = path.resolve(mainJobDirectory);
+    const mainRelative = path.relative(mainRoot, mainResolved);
+    if (!mainRelative || mainRelative.startsWith('..') || path.isAbsolute(mainRelative)) {
+      throw new JobError('main job directory escaped workspace');
+    }
+    void analytics.emit('job', source, 'workspace-ready');
+    if (cancellation.cancelled) {
+      throw new JobError(
+        `AI job cancelled: ${cancellation.reason}`,
+        cancellationOutcome(cancellation.reason),
+      );
+    }
+
+    turnTimer = setTimeout(() => cancellation.cancel('turn timeout'), TURN_TIMEOUT_MS);
+    void analytics.emit('job', source, 'turn-started');
+    const result = await state.executor.execute(normalizedInput, {
+      signal: cancellation.signal,
+      directory: mainJobDirectory,
+    });
+    void analytics.emit('job', source, 'turn-completed');
+    // oxlint-disable-next-line typescript/no-unnecessary-condition -- leaseLost is set by the lease timer.
+    if (leaseLost) {
+      throw new JobError('job lease was lost while the model turn was running', 'unknown');
+    }
+
+    const wantsText = normalizedInput.output.includes('text');
+    const wantsImage = normalizedInput.output.includes('image');
+    const text = wantsText ? resultText(result) : '';
+    if (Buffer.byteLength(text) > MAX_OUTPUT_TEXT_BYTES) {
+      throw new JobError('model output exceeded its text size limit');
+    }
+    if (wantsText && normalizedInput.outputSchema !== undefined) {
+      parseStructuredOutput(text, normalizedInput.outputSchema);
+    }
+
+    const imageParts = Array.isArray(result.output)
+      ? result.output.filter((part) => asObject(part)?.type === 'image')
+      : [];
+    if (!wantsImage && imageParts.length > 0) {
+      throw new JobError('model returned an unrequested image output');
+    }
+    if (wantsImage && imageParts.length === 0) {
+      throw new JobError('model completed without an image output');
+    }
+    if (imageParts.length > MAX_OUTPUT_IMAGES) {
+      throw new JobError('model returned too many image outputs');
+    }
+    const imageBytes = [];
+    let totalImageBytes = 0;
+    for (const part of imageParts) {
+      const bytes = decodeOutputImage(part);
+      totalImageBytes += bytes.length;
+      if (totalImageBytes > MAX_OUTPUT_IMAGE_TOTAL_BYTES) {
+        throw new JobError('generated images exceed their aggregate size limit');
+      }
+      imageBytes.push(bytes);
+    }
+    void analytics.emit('job', source, 'output-validated');
+
+    const output = [];
+    if (wantsText) {
+      output.push({ type: 'text', text });
+    }
+    if (wantsImage) {
+      for (const [index] of imageBytes.entries()) {
+        output.push({ type: 'image', mimeType: 'image/png', name: `image-${index}.png` });
+      }
+    }
+    const responseBytes = Buffer.from(
+      JSON.stringify({
+        output,
+        model: normalizedInput.model,
+        generatedAt: Number.isInteger(result.generatedAt) ? result.generatedAt : Date.now(),
+        ...(result.usage === undefined ? {} : { usage: result.usage }),
+      }),
+    );
+    const uploadedResponse = await runner.upload(
+      job.id,
+      job.leaseToken,
+      responseBytes,
+      'response.json',
+      'application/json',
+    );
+    const responseKey = boundedString(uploadedResponse?.key, 2048, 'uploaded response key');
+    void analytics.emit('job', source, 'response-uploaded');
+    const imageKeys = [];
+    for (const [index, bytes] of imageBytes.entries()) {
+      const uploaded = await runner.upload(
+        job.id,
+        job.leaseToken,
+        bytes,
+        `image-${index}.png`,
+        'image/png',
+      );
+      imageKeys.push(boundedString(uploaded?.key, 1024, 'uploaded image key'));
+    }
+    void analytics.emit('job', source, 'images-uploaded');
+    await runner.complete(job.id, job.leaseToken, {
+      responseKey,
+      imageKeys,
+    });
+    void analytics.emit('job', source, 'completed');
+  } catch (error) {
+    const outcome = cancellation.cancelled
+      ? cancellationOutcome(cancellation.reason)
+      : safeErrorOutcome(error);
+    void analytics.emit('job', source, 'failed', outcome);
+    const diagnostic = redact(error, [job.leaseToken]);
+    try {
+      await runner.fail(job.id, job.leaseToken, diagnostic, outcome);
+      void analytics.emit('job', source, 'failure-recorded', outcome);
+    } catch (failError) {
+      if (!(failError instanceof RunnerHttpError && failError.status === 409)) {
+        console.error(
+          `[runner] failed to report job ${job.id}: ${redact(failError, [job.leaseToken])}`,
+        );
+      }
+      void analytics.emit('job', source, 'failure-report-failed', outcome);
+    }
+    throw error;
+  } finally {
+    clearInterval(leaseTimer);
+    clearTimeout(turnTimer);
+    state.cancellation = undefined;
+    await removeJobDirectory(config.workspace, jobDirectory).catch((error) => {
+      console.error(`[runner] failed to remove job workspace: ${redact(error)}`);
+    });
+    void analytics.emit('job', source, 'cleanup-completed');
+  }
+};
+
+const readTokenFile = async (fileName, label) => {
+  const token = (await readFile(fileName, 'utf8')).trim();
+  if (!token) {
+    throw new Error(`${label} token file is empty`);
+  }
+  return token;
+};
+
+const readOptionalToken = async (fileName) => {
+  try {
+    const token = (await readFile(fileName, 'utf8')).trim();
+    return token || undefined;
+  } catch (error) {
+    if (error?.code === 'ENOENT') return undefined;
+    console.error(`[runner] optional token could not be read: ${redact(error)}`);
+    return undefined;
+  }
+};
+
+const readConfig = async (env = process.env) => {
+  const token = await readTokenFile(env.AG_AI_RUNNER_TOKEN_FILE ?? DEFAULT_TOKEN_FILE, 'runner');
+  const analyticaToken = await readTokenFile(
+    env.AG_AI_ANALYTICA_TOKEN_FILE ?? DEFAULT_ANALYTICA_TOKEN_FILE,
+    'Analytica',
+  );
+
+  const config = {
+    queueUrl: env.AG_AI_QUEUE_URL ?? DEFAULT_QUEUE_URL,
+    opencodeUrl: env.AG_AI_OPENCODE_URL ?? DEFAULT_OPENCODE_URL,
+    opencodeUsername: env.AG_AI_OPENCODE_USERNAME,
+    opencodePasswordFile: env.AG_AI_OPENCODE_PASSWORD_FILE,
+    opencodeProvider: env.AG_AI_OPENCODE_PROVIDER,
+    imageProvider: env.AG_AI_IMAGE_PROVIDER ?? DEFAULT_IMAGE_PROVIDER,
+    imageApiKeyFile: env.AG_AI_IMAGE_API_KEY_FILE,
+    runnerId: env.AG_AI_RUNNER_ID ?? `ag-ai-${os.hostname()}-${randomUUID()}`,
+    workspace: path.resolve(env.AG_AI_WORKSPACE ?? DEFAULT_WORKSPACE),
+    mainWorkspace: path.resolve(env.AG_AI_MAIN_WORKSPACE ?? DEFAULT_MAIN_WORKSPACE),
+    generatedImages: path.resolve(env.AG_AI_GENERATED_IMAGES ?? DEFAULT_GENERATED_IMAGES),
+    mainGeneratedImages: path.resolve(
+      env.AG_AI_MAIN_GENERATED_IMAGES ?? DEFAULT_MAIN_GENERATED_IMAGES,
+    ),
+    generationHost: env.AG_AI_GENERATION_HOST,
+    generationPeerPrefix: env.AG_AI_GENERATION_PEER_PREFIX,
+    generationPort: env.AG_AI_GENERATION_PORT ?? DEFAULT_GENERATION_PORT,
+    generationStore: path.resolve(env.AG_AI_GENERATION_STORE ?? DEFAULT_GENERATION_STORE),
+    generationTokenFile: env.AG_AI_GENERATION_TOKEN_FILE ?? DEFAULT_GENERATION_TOKEN_FILE,
+    analyticaToken,
+    token,
+  };
+  normalizeBaseUrl(config.queueUrl);
+  return config;
+};
+
+const main = async () => {
+  // emptyDir survives a sidecar restart. Never inherit another process's ready signal.
+  await rm('/tmp/runner-health.json', { force: true });
+  const config = await readConfig();
+  const analytics = new AnalyticaEvents({ token: config.analyticaToken, source: config.runnerId });
+  void analytics.emit('pod', 'started');
+  await safeRoot(config.workspace, 'workspace root');
+  await safeRoot(config.generatedImages, 'generated-image root');
+
+  const imageApiKey = await readOptionalToken(config.imageApiKeyFile);
+  let imageAdapter;
+  if (imageApiKey) {
+    try {
+      imageAdapter = createImageAdapter({ provider: config.imageProvider, apiKey: imageApiKey });
+    } catch (error) {
+      console.error(`[runner] image adapter disabled: ${redact(error)}`);
+    }
+  }
+  const executor = await createOpenCodeExecutor({
+    baseUrl: config.opencodeUrl,
+    username: config.opencodeUsername,
+    passwordFile: config.opencodePasswordFile,
+    providerID: config.opencodeProvider,
+    imageAdapter,
+  });
+
+  const runner = new RunnerClient({
+    baseUrl: config.queueUrl,
+    token: config.token,
+    runnerId: config.runnerId,
+    analytics,
+  });
+  const state = {
+    job: undefined,
+    cancellation: undefined,
+    stopping: false,
+    executor,
+    health: { serverReady: false, modelReady: false, models: [] },
+    healthPromise: undefined,
+  };
+
+  const generationToken = await readOptionalToken(config.generationTokenFile);
+  const generationStore = generationToken ? new GenerationStore(config.generationStore) : undefined;
+  // The LAN listener binds only where the host supplies a private bind address.
+  const generationServer =
+    generationToken && config.generationHost
+      ? await startGenerationServer({
+          host: config.generationHost,
+          port: config.generationPort,
+          token: String(generationToken),
+          store: generationStore,
+          allowedPeerPrefix: config.generationPeerPrefix,
+          getModels: () => state.health.models,
+          isReady: () => state.health.serverReady && state.health.modelReady,
+          analytics,
+        })
+      : undefined;
+  if (generationServer) {
+    const address = generationServer.address();
+    console.log(`[runner] LAN generation listener ready on ${address.address}:${address.port}`);
+  } else {
+    console.log(
+      '[runner] LAN generation listener disabled (generation token or bind host is absent)',
+    );
+  }
+
+  const refreshHealth = async () => {
+    // oxlint-disable-next-line typescript/no-unnecessary-condition -- the promise is set across async calls.
+    if (state.healthPromise) {
+      return state.healthPromise;
+    }
+    state.healthPromise = (async () => {
+      try {
+        await executor.health();
+        const models = await executor.listModels();
+        state.health = { serverReady: true, modelReady: models.length > 0, models };
+      } catch (error) {
+        state.health = { serverReady: false, modelReady: false, models: [] };
+        console.error(`[runner] OpenCode health check failed: ${redact(error)}`);
+      }
+      return state.health;
+    })().finally(() => {
+      state.healthPromise = undefined;
+    });
+    return state.healthPromise;
+  };
+
+  let heartbeatPromise;
+  const sendHeartbeat = async () => {
+    if (heartbeatPromise) {
+      return heartbeatPromise;
+    }
+    heartbeatPromise = runner
+      // oxlint-disable-next-line typescript/no-unnecessary-condition -- state.job is assigned in the claim loop.
+      .heartbeat(state.job ? 1 : 0, state.health.serverReady, state.health.modelReady)
+      .then(() => true)
+      .catch((error) => {
+        console.error(`[runner] runner heartbeat failed: ${redact(error, [config.token])}`);
+        return false;
+      })
+      .then(async (workerReachable) => {
+        // Probe data is private to this sidecar and contains no credentials.
+        const backendReady = state.health.serverReady && state.health.modelReady;
+        const lanReady = generationServer !== undefined && backendReady;
+        await writeFile(
+          '/tmp/runner-health.tmp',
+          JSON.stringify({
+            checkedAt: Date.now(),
+            ready: !state.stopping && (lanReady || (workerReachable && backendReady)),
+          }),
+          { mode: 0o600 },
+        );
+        await rename('/tmp/runner-health.tmp', '/tmp/runner-health.json');
+      })
+      .catch(() => console.error('[runner] could not update local health probe'))
+      .finally(() => {
+        heartbeatPromise = undefined;
+      });
+    return heartbeatPromise;
+  };
+
+  let shutdownPromise;
+  const stop = async (reason) => {
+    if (shutdownPromise) {
+      return shutdownPromise;
+    }
+    shutdownPromise = (async () => {
+      state.stopping = true;
+      void analytics.emit('pod', 'stopping');
+      state.cancellation?.cancel(reason);
+      // oxlint-disable-next-line typescript/no-unnecessary-condition -- state.job is assigned in the claim loop.
+      await Promise.race([state.job ?? Promise.resolve(), delay(SHUTDOWN_TIMEOUT_MS)]);
+      await generationServer?.close();
+      await generationStore?.close();
+      await analytics.flush();
+    })();
+    return shutdownPromise;
+  };
+  process.once('SIGTERM', () => void stop('SIGTERM'));
+  process.once('SIGINT', () => void stop('SIGINT'));
+
+  const heartbeatTimer = setInterval(() => void sendHeartbeat(), HEARTBEAT_INTERVAL_MS);
+  const healthTimer = setInterval(() => void refreshHealth(), HEALTH_INTERVAL_MS);
+  const claimLocal = async () => {
+    if (!generationStore) return undefined;
+    try {
+      const record = await generationStore.claimNext();
+      // oxlint-disable-next-line typescript/no-unnecessary-condition -- claimNext returns a record or undefined.
+      return record
+        ? {
+            source: 'local',
+            runner: createLocalRunner({ store: generationStore, record }),
+            job: undefined,
+          }
+        : undefined;
+    } catch (error) {
+      console.error(`[runner] local generation claim failed: ${redact(error)}`);
+      return undefined;
+    }
+  };
+  const claimCloud = async () => {
+    let claimResponse;
+    try {
+      claimResponse = await runner.claim();
+    } catch (error) {
+      console.error(`[runner] claim failed: ${redact(error, [config.token])}`);
+      if (error instanceof UncertainRequestError) return { uncertain: true };
+      return undefined;
+    }
+    if (!claimResponse?.job) return undefined;
+    try {
+      return { source: 'cloud', runner, job: validateJobEnvelope(claimResponse.job) };
+    } catch (error) {
+      console.error(`[runner] invalid claimed job: ${redact(error, [config.token])}`);
+      return { uncertain: true };
+    }
+  };
+  let preferLocal = false;
+  try {
+    await refreshHealth();
+    await sendHeartbeat();
+    while (!state.stopping) {
+      if (!state.health.serverReady || !state.health.modelReady) {
+        await refreshHealth();
+        await delay(CLAIM_INTERVAL_MS);
+        continue;
+      }
+      // oxlint-disable-next-line typescript/no-unnecessary-condition -- state.job is assigned in the claim loop.
+      if (state.job) {
+        await delay(250);
+        continue;
+      }
+
+      const first = preferLocal ? await claimLocal() : await claimCloud();
+      if (first?.uncertain) {
+        await delay(CLAIM_INTERVAL_MS);
+        continue;
+      }
+      const selection = first ?? (preferLocal ? await claimCloud() : await claimLocal());
+      if (selection?.uncertain) {
+        await delay(CLAIM_INTERVAL_MS);
+        continue;
+      }
+      if (!selection) {
+        await delay(CLAIM_INTERVAL_MS);
+        continue;
+      }
+      const activeRunner = selection.runner;
+      const job = selection.job ?? activeRunner.job;
+      preferLocal = selection.source === 'cloud';
+      const jobPromise = processJob(activeRunner, job, config, state, selection.source, analytics)
+        .catch((error) => {
+          console.error(`[runner] job ${job.id} ended: ${redact(error, [job.leaseToken])}`);
+        })
+        .finally(() => {
+          state.job = undefined;
+        });
+      state.job = jobPromise;
+      await jobPromise;
+    }
+  } finally {
+    clearInterval(heartbeatTimer);
+    clearInterval(healthTimer);
+    await stop('shutdown');
+  }
+};
+
+export {
+  JobError,
+  RunnerClient,
+  RunnerHttpError,
+  UncertainRequestError,
+  createCancellation,
+  emitRunnerHttpEvent,
+  normalizeBaseUrl,
+  processJob,
+  readConfig,
+  safeErrorOutcome,
+  validateJobEnvelope,
+};
+
+if (
+  process.argv[1] &&
+  (await realpath(process.argv[1]).catch(() => '')) ===
+    (await realpath(fileURLToPath(import.meta.url)))
+) {
+  main().catch((error) => {
+    console.error(`[runner] fatal: ${redact(error)}`);
+    process.exitCode = 1;
+  });
+}