@uchibeke/gallivant 0.0.0-stage → 0.2.1

package/lib/network_diagnostics.mjs

@@ -0,0 +1,64 @@
+import { execFile } from "node:child_process";
+import { request } from "node:https";
+
+// Explicit operator input only. Never probe destinations copied from task text,
+// error messages or repository settings, and never send credentials or redirects.
+export function diagnosticOrigin(value) {
+  let url;
+  try { url = new URL(value); } catch { throw new Error("Network diagnosis requires an HTTPS origin, for example https://api.anthropic.com"); }
+  if (url.protocol !== "https:" || url.username || url.password || url.search || url.hash || url.pathname !== "/") {
+    throw new Error("Use an HTTPS origin without credentials, a path, query parameters or fragment.");
+  }
+  return url;
+}
+
+const errorCode = error => /^[A-Z][A-Z0-9_]{1,63}$/.test(error?.code || "") ? error.code : "NETWORK_ERROR";
+
+export function systemDns(hostname, timeoutMs = 5000) {
+  // dns.lookup uses the OS resolver, matching normal application lookups. Run
+  // it in a bounded child because getaddrinfo cannot be cancelled on every OS.
+  const source = 'import { lookup } from "node:dns"; lookup(process.argv[1], { all: true }, (e, a) => console.log(JSON.stringify(e ? { ok: false, code: e.code } : { ok: true, families: [...new Set(a.map(x => x.family))] })));';
+  return new Promise(resolve => {
+    execFile(process.execPath, ["--input-type=module", "-e", source, hostname], { timeout: timeoutMs, killSignal: "SIGKILL", maxBuffer: 4096, encoding: "utf8" }, (error, stdout) => {
+      if (error) return resolve({ ok: false, code: error.killed ? "DNS_TIMEOUT" : errorCode(error) });
+      try { resolve(JSON.parse(stdout)); } catch { resolve({ ok: false, code: "DNS_RESULT_INVALID" }); }
+    });
+  });
+}
+
+export function httpsReachable(url, timeoutMs = 5000) {
+  return new Promise(resolve => {
+    let timer;
+    const req = request(url, { method: "HEAD", agent: false, rejectUnauthorized: true, headers: { "user-agent": "gallivant-network-diagnostic" } }, response => {
+      // Any HTTP response proves DNS/TCP/TLS connectivity, not model access.
+      response.resume();
+      clearTimeout(timer);
+      resolve({ ok: true, status: response.statusCode });
+      req.destroy();
+    });
+    req.on("error", error => { clearTimeout(timer); resolve({ ok: false, code: errorCode(error) }); });
+    timer = setTimeout(() => req.destroy(Object.assign(new Error("deadline"), { code: "HTTPS_TIMEOUT" })), timeoutMs);
+    req.end();
+  });
+}
+
+export async function diagnoseNetwork(value, { dns = systemDns, https = httpsReachable, clock = Date, env = process.env } = {}) {
+  const url = diagnosticOrigin(value);
+  const samples = [];
+  for (let i = 0; i < 3; i++) {
+    const started = clock.now();
+    const [dnsResult, httpsResult] = await Promise.all([dns(url.hostname.replace(/^\[|\]$/g, "")), https(url)]);
+    samples.push({ dns: dnsResult, https: httpsResult, elapsed_ms: clock.now() - started });
+  }
+  return { origin: url.origin, ok: samples.every(s => s.dns.ok && s.https.ok), samples,
+    proxyEnvironmentPresent: ["HTTPS_PROXY", "HTTP_PROXY", "ALL_PROXY", "https_proxy", "http_proxy", "all_proxy"].some(k => Boolean(env[k])),
+    scope: "Direct OS DNS and credential-free HTTPS only; no proxy forwarding, model request, authentication check or system configuration change." };
+}
+
+export function renderNetworkDiagnostics(result) {
+  return [`Network diagnostic: ${result.origin}`, ...result.samples.map((s, i) =>
+    `${i + 1}. DNS ${s.dns.ok ? "resolved" : s.dns.code}; HTTPS ${s.https.ok ? `reachable (HTTP ${s.https.status})` : s.https.code}; ${s.elapsed_ms}ms`),
+  result.scope,
+  ...(result.proxyEnvironmentPresent ? ["Proxy environment detected. This direct test does not qualify the harness's proxy route."] : []),
+  result.ok ? "All samples passed. This does not rule out an intermittent failure or prove model access." : "Connectivity failed in at least one sample. Preserve this output and compare on another approved network; see docs/network-recovery.md."].join("\n");
+}

package/lib/network_recovery.mjs

@@ -0,0 +1,42 @@
+// Only terminal local harness errors qualify. Unknown remote acceptance is owned
+// by the execution transport and must never be turned into a second submission.
+export const NETWORK_RETRY_DELAYS = Object.freeze([60_000, 300_000, 900_000]);
+export const NETWORK_RECOVERY_WINDOW = 60 * 60_000;
+const CODES = /\b(ENOTFOUND|EAI_AGAIN|ECONNRESET|ECONNREFUSED|ETIMEDOUT)\b/;
+
+export function networkFailure(outcome) {
+  if (outcome?.ok !== false || outcome.finished !== true || outcome.denials?.length) return null;
+  const text = outcome.error;
+  if (typeof text !== "string" || text.length > 512 || /auth|credential|permission|denied|policy|quota|budget|rate.limit|\b(?:401|403|429)\b/i.test(text)) return null;
+  // Do not classify arbitrary assistant prose, successful output, tool logs, or
+  // a generic "no result" as a retry instruction.
+  if (!/^(?:API Error:|Error:|(?:getaddrinfo|connect|read)\s|ENOTFOUND\b|EAI_AGAIN\b|ECONNRESET\b|ECONNREFUSED\b|ETIMEDOUT\b)/.test(text)) return null;
+  return text.match(CODES)?.[1] ?? null;
+}
+
+export function needsAgentResume(entry) {
+  return Boolean(entry.network_retry) || entry.reason === "harness-error" ||
+    Boolean(entry.last?.exit && networkFailure({ ok: false, finished: true, error: entry.last.error }));
+}
+
+// Embedders must keep waking a pending recovery even though the stored review
+// state is needs-human. Actual blocked/exhausted stops still require an operator.
+export const networkRecoveryPending = entry => Boolean(entry?.network_retry && entry.reason === "provider-network" &&
+  !entry.dispatch_stopped && entry.state !== "done" && !["running", "blocked", "exhausted"].includes(entry.network_retry.phase));
+
+export function validNetworkRetry(retry) {
+  return retry && Number.isInteger(retry.attempts) && retry.attempts >= 0 && retry.attempts <= NETWORK_RETRY_DELAYS.length &&
+    Number.isFinite(Date.parse(retry.first_at)) && typeof retry.run === "string" && retry.run.length > 0 &&
+    /^(ENOTFOUND|EAI_AGAIN|ECONNRESET|ECONNREFUSED|ETIMEDOUT)$/.test(retry.code) &&
+    ["reconciling", "waiting", "launching", "running", "blocked", "exhausted"].includes(retry.phase) &&
+    (retry.phase !== "waiting" || retry.attempts < NETWORK_RETRY_DELAYS.length && Number.isFinite(Date.parse(retry.next_at)));
+}
+
+export function networkRecoveryDetail(retry) {
+  const count = `${retry.attempts}/${NETWORK_RETRY_DELAYS.length}`;
+  if (retry.phase === "reconciling") return `checking published progress after ${retry.code}; no retry authorized`;
+  if (retry.phase === "waiting") return `waiting for API connectivity (${retry.code}); ${count} retries used; next ${retry.next_at}`;
+  if (retry.phase === "running") return `same-session network recovery ${count} after ${retry.code}`;
+  if (retry.phase === "launching") return `network recovery launch unconfirmed (${retry.code}); inspect the existing run before resuming`;
+  return `network recovery stopped (${retry.code}); ${count} retries used; inspect gallivant why before resuming`;
+}

package/lib/notify.mjs

@@ -0,0 +1,58 @@
+// Notifications through ntfy: two transition messages and a throttled error class. Nothing else, ever.
+// Bodies never carry diff or comment text; the PR URL is the only link.
+import { join } from "node:path";
+import { readJson, writeJsonAtomic } from "./fs.mjs";
+import { hours } from "./time.mjs";
+
+const ERROR_THROTTLE = hours(6);
+
+import { shortRepo } from "./state.mjs";
+
+/** Message shapes, kept as data so tests and docs can read them. */
+export const messages = {
+  ready: ({ entry, max, checks, reviewerNote }) => ({
+    title: `${shortRepo(entry.repo)}#${entry.pr} ready for a human`,
+    body: `Round ${entry.iteration}/${max}. Reviewer: ${reviewerNote}. Checks green (${checks}).`,
+    priority: "default", tags: "white_check_mark", click: entry.url,
+  }),
+  needs: ({ entry, max, handle }) => ({
+    title: `${shortRepo(entry.repo)}#${entry.pr ?? "?"} needs you: ${entry.reason}`,
+    body: `Stopped in round ${entry.iteration}/${max}. gallivant why ${handle}`,
+    priority: "high", tags: "warning", click: entry.url,
+  }),
+  error: ({ cls, fix }) => ({ title: `gallivant: ${cls}`, body: fix, priority: "high", tags: "rotating_light" }),
+};
+
+export function makeNotifier({ config, fetch = globalThis.fetch, clock = Date, log }) {
+  const throttleFile = join(config.home, "notify-throttle.json");
+  const target = config.notify?.ntfy || null;
+
+  async function send(msg) {
+    if (!target) { log?.info(`notify (no target): ${msg.title}`); return false; }
+    const headers = { Title: msg.title, Priority: msg.priority, Tags: msg.tags };
+    if (msg.click) headers.Click = msg.click;
+    if (config.notify.email) headers.Email = config.notify.email;
+    try {
+      const res = await fetch(target, { method: "POST", headers, body: msg.body });
+      if (!res.ok) throw new Error(`ntfy ${res.status}`);
+      return true;
+    } catch (e) {
+      log?.error(`notify failed: ${e.message} (${msg.title})`);
+      return false;
+    }
+  }
+
+  return {
+    ready: ctx => send(messages.ready(ctx)),
+    needs: ctx => send(messages.needs(ctx)),
+    /** At most one message per error class per six hours. Always logged. */
+    async error(cls, fix) {
+      log?.error(`${cls}: ${fix}`);
+      const t = readJson(throttleFile, {});
+      if (t[cls] && clock.now() - t[cls] < ERROR_THROTTLE) return false;
+      writeJsonAtomic(throttleFile, { ...t, [cls]: clock.now() });
+      return send(messages.error({ cls, fix }));
+    },
+    test: () => send({ title: "gallivant: test", body: "Notifications work.", priority: "low", tags: "wave" }),
+  };
+}

package/lib/openai_agents.mjs

@@ -0,0 +1,373 @@
+import { validateAgentsConfig } from "./openai_agents_config.mjs";
+// Managed Codex session transport under the shared execution/coordinator contract.
+import { join } from "node:path";
+import { readFileSync } from "node:fs";
+import { agentsHttp, AGENTS_LIMITS } from "./openai_agents_http.mjs";
+import { contentHash, portablePath, AGENTS_WORKSPACE_HELPER } from "./openai_agents_sources.mjs";
+import { readJson, writeJsonAtomic, ensureDir } from "./fs.mjs";
+import { executionError, collectionValidationError, dispatchNotSentError, redact, validProviderTestRecords, accessProbeFailure } from "./execution_io.mjs";
+import { assertRepositoryTargets } from "./repository_files.mjs";
+import { requireVerificationSandbox } from "./execution_result.mjs";
+import { agentsPreparation, intakeAgent, intakeSettings, assertIntakeInput, assertIntakeSession, assertIntakeItems, intakeText } from "./preparation_agents.mjs";
+const id = value => { if (typeof value !== "string" || !/^[A-Za-z0-9_-]{1,256}$/.test(value)) throw executionError("AGENTS_ID", "invalid provider identity"); return value; };
+const sessionPath = session => `/agents/sessions/${id(session)}`;
+const stateFor = status => ({ queued: "queued", in_progress: "running", waiting: "waiting-for-input", completed: "succeeded", failed: "failed", cancelled: "cancelled" })[status];
+export { validateAgentsConfig } from "./openai_agents_config.mjs";
+export const agentsCredential = config => () => config.api_key_file ? readFileSync(config.api_key_file, "utf8").trim() : process.env.OPENAI_API_KEY;
+export async function checkAgentsAccess(config, { signal, http = null } = {}) {
+  try {
+    signal ||= AbortSignal.timeout(10_000);
+    validateAgentsConfig(config);
+    signal.throwIfAborted();
+    const api = http || agentsHttp({ credential: agentsCredential(config), organization: config.organization, project: config.project });
+    const model = await api.request(`/models/${encodeURIComponent(config.model)}`, { signal });
+    signal.throwIfAborted();
+    if (model?.id !== config.model) throw executionError("AGENTS_MODEL", "account cannot retrieve the exact selected model");
+    await api.page("/agents/sessions", signal);
+    signal.throwIfAborted();
+    if (config.environment_template_id) await api.request(`/agents/environments/templates/${id(config.environment_template_id)}`, { signal });
+    signal.throwIfAborted();
+    return { ok: true, detail: "Agents read access and selected model visible; inference and hosted setup remain unverified until dispatch", effective: { account: config.account, organization: config.organization, project: config.project, model: config.model, environment: config.environment, container_size: config.container_size, network: config.network, allowance: config.allowance, cost: { source: "API tokens plus hosted compute", hardCap: false }, apiVersion: "agents=v1" } };
+  } catch (error) { return accessProbeFailure(error,signal,"AGENTS_ACCESS"); }
+}
+
+export function makeAgentsTransport({ root, taskId, account, config, http = null, clock = Date }) {
+  const api = http || agentsHttp({ credential: agentsCredential(config), organization: config.organization, project: config.project, clock });
+  const file = join(root, "agents.json");
+  const read = () => {
+    const s = readJson(file, { version: 1, taskId, account, organization: config.organization, project: config.project, operations: {}, sessions: {} });
+    if (s.version !== 1 || s.taskId !== taskId || s.account !== account || s.organization !== config.organization || s.project !== config.project) throw executionError("EXECUTION_OWNERSHIP", "Agents task/account/project state differs; restore its original configuration");
+    return s;
+  };
+  const save = s => { ensureDir(root); writeJsonAtomic(file, s); };
+  const owned = (s, req) => {
+    const op = Object.values(s.operations).find(op => op.runId === req.providerJobId);
+    if (!op || op.sessionId !== req.sessionId || op.turnId !== req.turnId || op.runId !== req.providerJobId) throw executionError("EXECUTION_OWNERSHIP", "Agents operation does not own this session/root turn");
+    return op;
+  };
+  const assertSession = (session, op) => {
+    if (session?.id !== op.sessionId || session.metadata?.task_id !== taskId || session.metadata?.account !== account || session.agent?.model !== config.model) throw executionError("EXECUTION_OWNERSHIP", "retrieved session/model/environment does not identify the owned task/account");
+    if (op.kind === "intake") {
+      if (op.settings !== intakeSettings(config)) throw executionError("TASK_PREPARATION_BOUNDARY", "intake configuration changed; restore the original account/model settings for recovery");
+      assertIntakeSession(session, config);
+      op.effective = { account, organization: config.organization, project: config.project, model: session.agent.model, environment: { type: "none" }, preparation: agentsPreparation, allowance: config.allowance, hardSpendCap: false };
+      return;
+    }
+    if (session.environment?.id !== op.environmentId) throw executionError("EXECUTION_OWNERSHIP", "retrieved environment does not identify the owned task");
+    const env = session.environment;
+    if (env.type !== "openai_hosted" || env.container_size !== config.container_size || env.network?.access !== config.network.access || (config.network.access === "restricted" && (env.network.allowed_domains || []).some(domain => !config.network.allowed_domains.includes(domain)))) throw executionError("EXECUTION_POLICY", "effective hosted environment cannot confirm the selected container/network requirements");
+    op.effective = { account, organization: config.organization, project: config.project, model: session.agent.model, environment: { id: env.id, type: env.type, container_size: env.container_size, network: env.network, packages: env.packages ?? null }, allowance: config.allowance, hardSpendCap: false };
+  };
+  const turn = async (op, signal) => {
+    const value = await api.request(`${sessionPath(op.sessionId)}/turns/${id(op.turnId)}`, { signal });
+    if (value?.id !== op.turnId || value.session_id !== op.sessionId || value.subagent_id != null || !stateFor(value.status)) throw executionError("AGENTS_PROTOCOL", "authoritative root turn does not match ownership");
+    return value;
+  };
+  async function allPages(path, signal) {
+    const results = []; let cursor = null, size = 0;
+    for (let n = 0; n < AGENTS_LIMITS.pages; n++) {
+      const page = await api.page(path, signal, cursor); size += Buffer.byteLength(JSON.stringify(page.data));
+      if (size > AGENTS_LIMITS.responseBytes) throw executionError("AGENTS_SIZE", "saved provider history exceeds bounded recovery; preserve state and narrow the task");
+      results.push(...page.data); if (!page.next) return results; cursor = page.next;
+    }
+    throw executionError("AGENTS_SIZE", "provider pagination exceeds bounded recovery; no truncated result accepted");
+  }
+  const acknowledge = op => ({ providerJobId: op.runId, sessionId: op.sessionId, turnId: op.turnId, environment: op.environmentId, model: config.model, effective: op.effective });
+  async function resolveTurn(s, op, signal) {
+    // No arbitrary latest-turn adoption: only one new root after the saved
+    // pre-send turn set, in this single-writer session, can resolve acceptance.
+    const turns = await allPages(`${sessionPath(op.sessionId)}/turns`, signal);
+    const candidates = turns.filter(t => t.subagent_id == null && !(op.previousTurns || []).includes(t.id));
+    if (candidates.length !== 1) return null;
+    op.turnId = id(candidates[0].id); op.acceptance = "accepted"; save(s); return acknowledge(op);
+  }
+  async function dispatch(req, continuing = false) {
+    const s = read(); let op = s.operations[req.idempotencyKey];
+    if (op) { validateAgentsConfig(config); if (op.turnId) return acknowledge(op); throw executionError("EXECUTION_UNKNOWN", "Agents acceptance unknown; reconcile the saved dispatch before retrying"); }
+    const source = req.sources, intake = req.kind === "intake";
+    let snapshotPath, previous;
+    try {
+      validateAgentsConfig(config);
+      if (intake) {
+        assertIntakeInput(req, config, true);
+        if (continuing) throw executionError("TASK_PREPARATION_BOUNDARY", "each intake attempt requires a new tool-free session");
+      } else if (!source || contentHash(Buffer.from(source.data || "", "base64")) !== source.hash || source.inputHead !== req.inputHead || source.repo !== req.repo || source.branch !== req.branch) throw executionError("AGENTS_SOURCE", "dispatch requires a verified portable snapshot for its exact input head");
+      snapshotPath = `/workspace/input-${id(req.runId)}.json.gz`;
+      if (continuing) {
+        previous = Object.values(s.operations).find(old => old.sessionId === req.sessionId && old.turnId);
+        if (!previous) throw executionError("EXECUTION_CONTINUATION", "no owned Agents session to continue");
+      }
+      if (!intake) await requireVerificationSandbox({ signal: req.signal });
+    } catch (error) { throw dispatchNotSentError(error); }
+    const helperPath = "/workspace/transport.py";
+    const restore = intake ? null : `python3 ${helperPath} restore ${snapshotPath} ${source.hash}`;
+    op = { runId: req.runId, key: req.idempotencyKey, kind: intake ? "intake" : "implementation", ...(intake ? { settings: intakeSettings(config) } : {}), inputHead: req.inputHead ?? null, repo: req.repo, branch: req.branch, sourceHash: source?.hash, hashes: source?.hashes, modes: source?.modes, acceptance: "unknown", createdAt: clock.now(), sessionId: req.sessionId || null, environmentId: null, turnId: null, previousTurns: [] };
+    s.operations[req.idempotencyKey] = op; save(s);
+    if (continuing) {
+      op.environmentId = previous.environmentId;
+      const session = await api.request(sessionPath(op.sessionId), { signal: req.signal }); assertSession(session, op);
+      const environment = await api.request(`/agents/environments/${id(op.environmentId)}`, { signal: req.signal });
+      if (session.status === "failed" || environment.status !== "connected") throw executionError("AGENTS_ENVIRONMENT", "session failed or filesystem expired; retain published artifacts, repair setup and explicitly authorize a replacement session");
+      op.previousTurns = (await allPages(`${sessionPath(op.sessionId)}/turns`, req.signal)).filter(t => t.subagent_id == null).map(t => t.id);
+      if (!["completed", "failed"].includes((await turn(previous, req.signal)).status)) throw executionError("BUSY", "owned root turn has not settled");
+      save(s);
+      await api.request(`/agents/environments/${id(op.environmentId)}/files`, { method: "POST", signal: req.signal, body: { type: "inline", path: snapshotPath, data: source.data } });
+    } else {
+      // Conversation-only sessions require initial input (live API, 2026-10-08).
+      // Persist its intent first; recovery adopts the exact initial root and
+      // never sends that text again. Coding sessions still stage sources first.
+      if (intake) { op.sendIntent = true; save(s); }
+      const session = await api.request("/agents/sessions", { method: "POST", signal: req.signal, ...(intake ? { key: op.key } : {}), body: {
+        agent: intake ? intakeAgent(config) : { model: config.model, ...(config.reasoning ? { reasoning: config.reasoning } : {}), ...(config.service_tier ? { service_tier: config.service_tier } : {}), multi_agent: { enabled: false }, instructions: "Work only in /workspace/repo. Publish requested files and real test records. The application owns GitHub publication; never request or infer credentials.", tools: [{ type: "function", name: "ask_operator", description: "Ask a concise question requiring an operator answer", parameters: { type: "object", properties: { question: { type: "string" } }, required: ["question"], additionalProperties: false } }] },
+        environment: intake ? { type: "none" } : { type: "openai_hosted", container_size: config.container_size, network: config.network, ...(config.packages ? { packages: config.packages } : {}), ...(config.environment_template_id ? { environment_template_id: config.environment_template_id } : {}), files: [{ type: "inline", path: snapshotPath, data: source.data }, { type: "inline", path: helperPath, data: Buffer.from(AGENTS_WORKSPACE_HELPER).toString("base64") }], setup_commands: [{ command: restore }] },
+        metadata: { task_id: taskId, account, dispatch_key: req.idempotencyKey },
+        ...(intake ? { input: [{ role: "user", content: [{ type: "input_text", text: req.prompt }] }] } : {}),
+      } });
+      op.sessionId = id(session.id); op.environmentId = intake ? "none" : id(session.environment?.id); s.sessions[op.sessionId] = { environmentId: op.environmentId }; save(s); assertSession(session, op); save(s);
+    }
+    if (intake) {
+      const stream = await api.subscribe(op.sessionId, req.signal);
+      try {
+        const ack = await resolveTurn(s, op, req.signal);
+        if (!ack) throw executionError("EXECUTION_UNKNOWN", "initial intake turn unresolved; recover by saved metadata without resending");
+        return ack;
+      } finally { await stream.close(); }
+    }
+    return send(s, op, req, continuing ? restore : null);
+  }
+  async function send(s, op, req, restore = null) {
+    const stream = await api.subscribe(op.sessionId, req.signal);
+    try {
+      op.sendIntent = true; save(s);
+      const delivery = op.kind === "intake" ? req.prompt : `${restore ? `Before continuing, reconcile to the current coordinator source by running ${restore}. This replaces the previous round filesystem with the verified current branch input.\n` : ""}Work in /workspace/repo. Input revision: ${op.inputHead}.\n${req.prompt}\n\nDelivery: do not push or create a PR from this environment. Write /workspace/pr.json with neutral title and complete receipt body, and /workspace/tests.json with each actual command, exit, output and inputHead. Run python3 /workspace/transport.py publish /workspace/pr.json /workspace/tests.json. Finish only after /workspace/outputs/result.json exists. Preserve the supplied input head; the coordinator verifies, commits and publishes the files.`;
+      await api.request(`${sessionPath(op.sessionId)}/events`, { method: "POST", signal: req.signal, key: op.key, body: { events: [{ type: "agent.session.input.message", input: [{ role: "user", content: [{ type: "input_text", text: delivery }] }] }] } });
+      op.sendAcknowledged = true; save(s);
+      const ack = await resolveTurn(s, op, req.signal);
+      if (!ack) throw executionError("EXECUTION_UNKNOWN", "input accepted but root identity unresolved; reconcile saved turns without resending");
+      return ack;
+    } finally { await stream.close(); }
+  }
+  async function lookup(req) {
+    const s = read(), op = s.operations[req.intent.idempotencyKey];
+    if (!op || op.recoveryBlocked) return null;
+    let stream;
+    const unresolved = () => {
+      op.lookupFailures = (op.lookupFailures || 0) + 1;
+      if (op.lookupFailures >= 3) op.recoveryBlocked = "three launch reconciliation failures; inspect the recorded dispatch key and repair access before explicitly resetting recovery; input was not resent";
+      save(s); return null;
+    };
+    try {
+      if (!op.sessionId) {
+        const sessions = await allPages("/agents/sessions", req.signal);
+        const matches = sessions.filter(x => x.metadata?.dispatch_key === op.key && x.metadata?.task_id === taskId && x.metadata?.account === account);
+        if (matches.length !== 1) return unresolved();
+        op.sessionId = id(matches[0].id); op.environmentId = op.kind === "intake" ? "none" : id(matches[0].environment?.id); save(s);
+      }
+      stream = await api.subscribe(op.sessionId, req.signal);
+      const session = await api.request(sessionPath(op.sessionId), { signal: req.signal }); assertSession(session, op);
+      if (session.status === "failed" || !op.sendIntent) {
+        op.sessionFailed = session.status === "failed";
+        op.recoveryBlocked = op.sessionFailed ? "session failed before launch acknowledgement; recover saved outputs and repair setup; no automatic reconnect or replacement" : "session creation recovered before any input send; inspect the saved session and explicitly authorize recovery; no implementation was launched";
+        save(s); return null;
+      }
+      if (!op.turnId && !await resolveTurn(s, op, req.signal)) return unresolved();
+    } catch (error) { op.recoveryErrorCode=error.code || null; unresolved(); throw error; }
+    finally { await stream?.close(); }
+    return inspect({ ...req, ...acknowledge(op) });
+  }
+  async function inspect(req) {
+    const s = read(), op = owned(s, req); let stream = null;
+    if (op.recoveryBlocked) throw executionError("AGENTS_RECOVERY_REQUIRED", op.recoveryBlocked);
+    // Failed sessions are not reconnected again, even after a process restart.
+    try {
+      if (!op.sessionFailed) stream = await api.subscribe(op.sessionId, req.signal);
+      const session = await api.request(sessionPath(op.sessionId), { signal: req.signal }); assertSession(session, op);
+      const rootTurn = await turn(op, req.signal);
+      const events = [], checkpoint = op.items || {}, items = await api.page(`${sessionPath(op.sessionId)}/items?turn_id=${id(op.turnId)}`, req.signal, op.itemCursor || null);
+      if (op.kind === "intake") assertIntakeItems(items.data, op);
+      for (const item of items.data) {
+        if (!item.id || item.turn_id !== op.turnId || item.subagent_id != null) throw executionError("AGENTS_PROTOCOL", "saved item does not identify the owned root turn");
+        const digest = contentHash(JSON.stringify(item));
+        if (checkpoint[item.id] !== digest) events.push({ eventId: `item:${item.id}:${digest}`, type: "output-replace", data: redact({ itemId: item.id, content: item.content, status: item.status }), timestamp: clock.now() });
+        checkpoint[item.id] = digest;
+      }
+      op.items = checkpoint; op.itemCursor = items.next;
+      op.itemPages = (op.itemPages || 0) + 1;
+      if (items.next && op.itemPages >= AGENTS_LIMITS.pages) throw executionError("AGENTS_SIZE", "saved item pagination exceeds bounded recovery");
+      if (!items.next) { op.items = {}; op.itemCursor = null; op.itemPages = 0; } // rescan authoritative current items after each cycle
+      if (session.status === "failed") op.sessionFailed = true;
+      const actions = (session.required_actions || []).filter(action => action.turn_id === op.turnId);
+      op.requiredActions = actions;
+      if (actions.length) events.push({ eventId: `actions:${contentHash(JSON.stringify(actions))}`, type: "required-action", data: redact(actions), timestamp: clock.now() });
+      op.finalItems ||= {};
+      for (const item of items.data) if (["completed", "done"].includes(item.status)) op.finalItems[item.id] = true;
+      const finalItems = new Set(Object.keys(op.finalItems));
+      op.parts ||= {};
+      for (const event of stream?.events || []) {
+        if (event.session_id !== op.sessionId || event.turn_id !== op.turnId || event.subagent_id != null || !event.event_id || finalItems.has(event.item_id)) continue;
+        const part = `${event.item_id}:${event.output_index}:${event.content_index}`;
+        if (!["agent.session.turn.output_text.delta", "agent.session.turn.output_text.done"].includes(event.type) || op.parts[part]?.done) continue;
+        const text = event.type.endsWith(".done") ? event.text : (op.parts[part]?.text || "") + (event.delta || "");
+        if (typeof text !== "string" || Buffer.byteLength(text) > 16_384 || Object.keys(op.parts).length > 100) continue;
+        op.parts[part] = { text: redact(text), done: event.type.endsWith(".done") };
+        events.push({ eventId: event.event_id, type: "output-replace", data: { itemId: event.item_id, outputIndex: event.output_index, contentIndex: event.content_index, ...op.parts[part] }, timestamp: clock.now() });
+      }
+      const environment = op.kind === "intake" ? { id: "none", status: "connected" } : await api.request(`/agents/environments/${id(op.environmentId)}`, { signal: req.signal });
+      if (environment.id !== op.environmentId) throw executionError("EXECUTION_OWNERSHIP", "environment identity differs");
+      op.environmentState = environment.status; op.usage = rootTurn.usage ?? null; op.rootStatus = rootTurn.status; op.error = redact(rootTurn.error || session.error || null); save(s);
+      // Completed artifacts remain recoverable after filesystem expiry. Failure
+      // settles only the authoritative owned root; session idle is irrelevant.
+      let state = stateFor(rootTurn.status);
+      if (!["succeeded", "failed", "cancelled"].includes(state)) {
+        if (op.sessionFailed || ["failed", "expired", "deleted"].includes(environment.status)) {
+          op.recoveryBlocked = "session/environment unavailable; saved files remain recoverable, filesystem continuity is unverified; no automatic replacement session"; save(s);
+          throw executionError("AGENTS_ENVIRONMENT", op.recoveryBlocked);
+        }
+        if (environment.status !== "connected") state = "provisioning";
+      }
+      if (events.length > 100 || Buffer.byteLength(JSON.stringify(events)) > 60_000) throw executionError("AGENTS_SIZE", "normalized event page exceeds journal limits");
+      if (items.next && ["succeeded", "failed"].includes(state)) state = "running";
+      op.recoveryFailures = 0; save(s);
+      return { ...acknowledge(op), state, observedAt: clock.now(), completedAt: !["succeeded", "failed", "cancelled"].includes(state) || rootTurn.completed_at == null ? null : rootTurn.completed_at * 1000, events, cursor: op.itemCursor || `snapshot:${contentHash(JSON.stringify(checkpoint))}`, gap: "saved items restore final output; intermediate deltas between bounded subscriptions may be unavailable", costUsd: null, usage: op.usage, environmentState: op.environmentState };
+    } catch (error) {
+      op.recoveryErrorCode=error.code || null;
+      op.recoveryFailures = (op.recoveryFailures || 0) + 1;
+      if (op.recoveryFailures >= 3) op.recoveryBlocked ||= "three reconciliation failures; repair access/configuration, then explicitly reset recovery without resending input";
+      save(s); throw error;
+    } finally { await stream?.close(); }
+  }
+  async function collect(req) {
+    const s = read(), op = owned(s, req);
+    if (op.kind === "intake") assertSession(await api.request(sessionPath(op.sessionId), { signal: req.signal }), op);
+    if (op.collectionRejection) throw collectionValidationError("saved immutable artifact was rejected; explicitly resume the same session for correction");
+    const rootTurn = await turn(op, req.signal);
+    if (!["completed", "failed"].includes(rootTurn.status)) throw executionError("EXECUTION_RESULT", "owned root has not completed");
+    if (rootTurn.status === "failed") return { ...acknowledge(op), inputHead: op.inputHead, completedAt: rootTurn.completed_at == null ? null : rootTurn.completed_at * 1000, outcome: { finished: true, ok: false, cost: null, denials: [], error: redact(rootTurn.error || "root turn failed") }, usage: rootTurn.usage ?? null };
+    if (op.kind === "intake") {
+      const items = await allPages(`${sessionPath(op.sessionId)}/items?turn_id=${id(op.turnId)}`, req.signal);
+      return { ...acknowledge(op), inputHead: op.inputHead, completedAt: rootTurn.completed_at == null ? null : rootTurn.completed_at * 1000,
+        outcome: { finished: true, ok: true, lastMessage: intakeText(items, op), cost: null, denials: [] }, usage: rootTurn.usage ?? null };
+    }
+    const artifacts = await allPages(`${sessionPath(op.sessionId)}/artifacts`, req.signal);
+    const candidates = artifacts.filter(a => a.turn_id === op.turnId && a.path === "/workspace/outputs/result.json");
+    if (candidates.length !== 1 || candidates[0].session_id !== op.sessionId || candidates[0].environment_id !== op.environmentId || !Number.isInteger(candidates[0].size_bytes) || candidates[0].size_bytes > AGENTS_LIMITS.responseBytes) throw executionError("EXECUTION_RESULT", "one bounded completed-turn result artifact is required");
+    const bytes = await api.download(`${sessionPath(op.sessionId)}/artifacts/${id(candidates[0].id)}/content`, req.signal);
+    if (bytes.length !== candidates[0].size_bytes) throw executionError("EXECUTION_RESULT", "artifact download size differs from immutable metadata");
+    let result;
+    try {
+      try { result = JSON.parse(bytes.toString("utf8")); } catch { throw collectionValidationError("invalid artifact JSON"); }
+      if (!result || result.version !== 1 || result.inputHead !== op.inputHead || result.repo !== op.repo || result.branch !== op.branch || !Array.isArray(result.files) || !result.files.length || result.files.length > 100 || !validProviderTestRecords(result.tests, op.inputHead)) throw collectionValidationError("artifact source identity/files/test records are incomplete");
+      const paths = [];
+      for (const f of result.files) {
+        if (!f || f.text !== null && (typeof f.text !== "string" || f.text.includes("\0"))) throw collectionValidationError("artifact must contain regular UTF-8 text files");
+        try { paths.push(portablePath(f.path)); } catch { throw collectionValidationError("unsafe or private artifact path"); }
+        if (f.beforeHash !== (op.hashes[f.path] ?? null) || f.afterHash !== contentHash(f.text)) throw collectionValidationError("artifact hash/base mismatch");
+      }
+      try { assertRepositoryTargets(paths, Object.keys(op.hashes)); } catch { throw collectionValidationError("artifact aliases a repository path"); }
+    } catch (error) {
+      if (error.collectionValidation !== true) throw error;
+      // Preserve rejected bytes privately for inspection, never as publication
+      // input or public diagnostics. This refusal also fences retries if the
+      // coordinator crashes before it can save its application checkpoint.
+      const artifact = { id: candidates[0].id, hash: contentHash(bytes), size: bytes.length };
+      const cache = `${id(op.runId)}-rejected-artifact.json`;
+      writeJsonAtomic(join(root, cache), { version: 1, taskId, providerJobId: op.runId, sessionId: op.sessionId,
+        turnId: op.turnId, inputHead: op.inputHead, artifact, contentBase64: bytes.toString("base64") });
+      op.collectionRejection = { artifact, cache }; save(s);
+      throw error;
+    }
+    const saved = { ...result, ...acknowledge(op), inputHead: op.inputHead, completedAt: rootTurn.completed_at == null ? null : rootTurn.completed_at * 1000, outcome: { finished: true, ok: true, cost: null, denials: [] }, usage: rootTurn.usage ?? null, artifact: { id: candidates[0].id, hash: contentHash(bytes), turnId: op.turnId } };
+    // The boundary also saves result.json before settlement; this download cache
+    // independently protects outputs before any explicit session deletion.
+    writeJsonAtomic(join(root, `${id(op.runId)}-artifacts.json`), saved); op.savedArtifacts = true; save(s); return saved;
+  }
+  async function cancel(req) {
+    const s = read(), op = owned(s, req), session = await api.request(sessionPath(op.sessionId), { signal: req.signal }); assertSession(session, op);
+    const rootTurn = await turn(op, req.signal);
+    if (rootTurn.status === "cancelled") return { confirmed: true };
+    if (["completed", "failed"].includes(rootTurn.status)) return { confirmed: false };
+    const active = (await allPages(`${sessionPath(op.sessionId)}/turns`, req.signal)).filter(t => t.subagent_id == null && !["completed", "failed", "cancelled"].includes(t.status));
+    if (active.length !== 1 || active[0].id !== op.turnId) throw executionError("EXECUTION_CONTROL", "session cancellation cannot target a different active root turn");
+    await api.request(`${sessionPath(op.sessionId)}/events`, { method: "POST", key: req.idempotencyKey, signal: req.signal, body: { events: [{ type: "agent.session.input.cancel" }] } });
+    return { confirmed: (await turn(op, req.signal)).status === "cancelled" };
+  }
+  async function respond(req, recovering = false) {
+    const s = read(), op = owned(s, req);
+    if (req.authorized !== true || typeof req.answer !== "string" || Buffer.byteLength(req.answer) > 16_384 || typeof req.idempotencyKey !== "string" || !req.idempotencyKey || req.idempotencyKey.length > 256) throw executionError("EXECUTION_ACTION", "an authorized bounded answer and stable identity are required");
+    const key = contentHash(req.idempotencyKey), signature = contentHash(JSON.stringify([op.turnId, req.callId, req.answer]));
+    const prior = op.answers?.[key];
+    if (prior && prior.signature !== signature) throw executionError("EXECUTION_CONFLICT", "answer identity owns different input");
+    if (prior?.accepted) return { accepted: true };
+    const stream = await api.subscribe(op.sessionId, req.signal);
+    try {
+      const session = await api.request(sessionPath(op.sessionId), { signal: req.signal }); assertSession(session, op);
+      const rootTurn = await turn(op, req.signal);
+      const actions = (session.required_actions || []).filter(a => a.turn_id === op.turnId && a.call_id === req.callId);
+      if (actions.length > 1 || actions.some(a => a.type !== "function_call" || a.name !== "ask_operator")) throw executionError("EXECUTION_ACTION", "only the current ask_operator call can receive an answer");
+      if (!actions.length) {
+        if (!recovering) throw executionError("EXECUTION_ACTION", "the current ask_operator turn/call is not pending");
+        const items = await allPages(`${sessionPath(op.sessionId)}/turns/${id(op.turnId)}/items`, req.signal);
+        if (items.some(item => !item.id || item.turn_id !== op.turnId || item.subagent_id != null)) throw executionError("AGENTS_PROTOCOL", "answer recovery items do not identify the owned root turn");
+        const calls = items.filter(item => item.type === "function_call" && item.call_id === req.callId);
+        const outputs = items.filter(item => item.type === "function_call_output" && item.call_id === req.callId);
+        if (calls.length !== 1 || calls[0].name !== "ask_operator" || outputs.length !== 1 || outputs[0].status !== "completed" || outputs[0].error != null) throw executionError("EXECUTION_UNKNOWN", "answer is no longer pending and saved items cannot confirm acceptance; inspect the owned turn; no input was sent");
+        if (outputs[0].output !== req.answer) throw executionError("EXECUTION_CONFLICT", "saved call output differs from the authorized answer; no input was sent");
+      } else {
+        if (session.status === "failed" || !["in_progress", "waiting"].includes(rootTurn.status)) throw executionError("EXECUTION_ACTION", "the owned root cannot receive another answer");
+        op.answers = { ...op.answers, [key]: { signature, accepted: false } }; save(s);
+        await api.request(`${sessionPath(op.sessionId)}/events`, { method: "POST", signal: req.signal, key: req.idempotencyKey,
+          body: { events: [{ type: "agent.session.input.tool_result", turn_id: op.turnId, call_id: req.callId, success: true, output: req.answer }] } });
+      }
+      // Preserve the acknowledgement before stream cleanup or a coordinator
+      // checkpoint fails, so retry never needs another input send.
+      op.answers = { ...op.answers, [key]: { signature, accepted: true } }; save(s);
+      return { accepted: true };
+    } finally { await stream.close(); }
+  }
+  return {
+    prepare: async req => {
+      if (req.contextPaths?.length) throw executionError("EXECUTION_POLICY", "hosted backend cannot enforce private read-only context");
+      validateAgentsConfig(config);
+      if (req.kind === "intake") assertIntakeInput(req, config);
+      const verificationSandbox = req.kind === "intake" ? null : await requireVerificationSandbox({ signal: req.signal });
+      const result = await checkAgentsAccess(config, { signal: req.signal, http: api });
+      if (!result.ok) throw executionError(result.detail, result.fix);
+      if (req.kind === "intake") return { boundary: agentsPreparation.boundary, environment: "none", model: config.model, settings: intakeSettings(config) };
+      const state = read(); state.capabilities = { ...result.effective, verificationSandbox }; save(state); return state.capabilities;
+    },
+    submit: req => dispatch(req), continue: req => dispatch(req, true), lookup, inspect, collect, cancel,
+    respond: req => respond(req), recoverResponse: req => respond(req, true),
+    resetRecovery: async req => {
+      const s = read(), intent=req.intent, op=intent && s.operations[intent.idempotencyKey];
+      if (!op || op.runId!==intent.runId || (req.providerJobId && req.providerJobId!==op.runId) || (req.sessionId && req.sessionId!==op.sessionId) || (req.turnId && req.turnId!==op.turnId)) throw executionError("EXECUTION_OWNERSHIP", "recovery requires the exact saved dispatch intent and any recorded session/root identity");
+      if (op.sessionFailed || ["failed", "expired", "deleted"].includes(op.environmentState)) throw executionError("AGENTS_ENVIRONMENT", "failed/expired sessions require saved artifact recovery and explicit replacement authorization");
+      if (req.authorized !== true || typeof req.operationId!=="string" || !/^[a-f0-9]{64}$/.test(req.operationId)) throw executionError("EXECUTION_CONTROL", "explicit bounded recovery authorization is required");
+      // A replay cannot replenish a circuit which failed again after this reset.
+      if (op.recoveryResets?.includes(req.operationId)) return {reset:false};
+      const retryBlocks=["three launch reconciliation failures; inspect the recorded dispatch key and repair access before explicitly resetting recovery; input was not resent","three reconciliation failures; repair access/configuration, then explicitly reset recovery without resending input"];
+      if ((op.recoveryBlocked && !retryBlocks.includes(op.recoveryBlocked)) || ["AGENTS_PROTOCOL","AGENTS_ID","EXECUTION_OWNERSHIP","EXECUTION_POLICY","TASK_PREPARATION_BOUNDARY"].includes(op.recoveryErrorCode)) throw executionError(op.recoveryErrorCode || "AGENTS_RECOVERY_REQUIRED", "saved ownership, policy or terminal refusal requires repair; observation retry does not override it");
+      if ((op.recoveryResets?.length || 0)>=32) throw executionError("AGENTS_RECOVERY_REQUIRED", "recovery receipt capacity reached; preserve the recorded operation for inspection");
+      // Recheck read access to the owned work, not readiness to start new work:
+      // recovering saved results must not require model-catalog/inference access.
+      // Failed/late checks cannot consume a receipt or clear the retry fence.
+      if (op.recoveryErrorCode === "AGENTS_AUTH") {
+        const signal = req.signal || AbortSignal.timeout(10_000);
+        signal.throwIfAborted();
+        if (op.sessionId) {
+          const session = await api.request(sessionPath(op.sessionId), { signal });
+          signal.throwIfAborted(); assertSession(session, op);
+          if (op.turnId) await turn(op, signal);
+        } else await api.page("/agents/sessions", signal);
+        signal.throwIfAborted();
+      }
+      req.signal?.throwIfAborted();
+      op.recoveryResets=[...(op.recoveryResets || []),req.operationId];
+      op.recoveryBlocked = null; op.recoveryErrorCode = null; op.recoveryFailures = 0; op.lookupFailures = 0; save(s);return {reset:true};
+    },
+    deleteSession: async req => {
+      const s = read(), op = owned(s, req);
+      if (!op.savedArtifacts || !["completed", "failed", "cancelled"].includes((await turn(op, req.signal)).status)) throw executionError("EXECUTION_CONTROL", "save published artifacts and settle the root before session deletion");
+      await api.request(sessionPath(op.sessionId), { method: "DELETE", signal: req.signal });
+    },
+  };
+}

package/lib/openai_agents_config.mjs

@@ -0,0 +1,14 @@
+import { executionError } from "./execution_io.mjs";
+export function validateAgentsConfig(config) {
+  if (!config || typeof config.account !== "string" || !config.account.trim() || config.account.length > 128 || typeof config.model !== "string" || !/^[\w.-]{1,128}$/.test(config.model)) throw executionError("AGENTS_CONFIG", "openai-agents requires explicit account and model; no model default/fallback is supplied");
+  if (!/^[A-Za-z0-9_-]{1,128}$/.test(config.organization || "") || !/^[A-Za-z0-9_-]{1,128}$/.test(config.project || "")) throw executionError("AGENTS_CONFIG", "configure explicit organization and project to isolate API account ownership");
+  if (config.environment !== "openai_hosted" || !["small", "medium", "large"].includes(config.container_size)) throw executionError("AGENTS_CONFIG", "select openai_hosted and an explicit container_size");
+  if (config.environment_template_id && !/^[A-Za-z0-9_-]{1,64}$/.test(config.environment_template_id)) throw executionError("AGENTS_CONFIG", "invalid selected environment template");
+  if (config.packages && (typeof config.packages !== "object" || Array.isArray(config.packages) || Object.keys(config.packages).some(key => !["system", "python", "npm"].includes(key)) || Object.values(config.packages).some(values => !Array.isArray(values) || values.length > 50 || values.some(value => typeof value !== "string" || !/^[A-Za-z0-9@][A-Za-z0-9@._/=+:-]{0,127}$/.test(value))))) throw executionError("AGENTS_CONFIG", "packages must contain bounded explicit system/python/npm package lists");
+  if (!config.network || !["disabled", "restricted"].includes(config.network.access)) throw executionError("AGENTS_CONFIG", "select disabled or restricted sandbox network access");
+  if (config.network.access === "restricted" && (!Array.isArray(config.network.allowed_domains) || !config.network.allowed_domains.length || config.network.allowed_domains.length > 100 || config.network.allowed_domains.some(domain => typeof domain !== "string" || !/^(?:[a-z0-9](?:[a-z0-9-]*[a-z0-9])?\.)+[a-z]{2,}$/i.test(domain)))) throw executionError("AGENTS_CONFIG", "restricted network requires 1–100 exact domain names");
+  if (!Number.isFinite(config.allowance?.remainingUsd) || !Number.isFinite(config.allowance?.reservedUsd) || config.allowance.reservedUsd <= 0 || config.allowance.remainingUsd < config.allowance.reservedUsd) throw executionError("EXECUTION_ALLOWANCE", "configure a positive task reservation and remaining API allowance");
+  for (const policy of config.mandatory_policy || []) throw executionError("EXECUTION_POLICY", `hosted backend cannot enforce mandatory policy ${policy}; retain a capable local backend`);
+  if (config.context_paths?.length) throw executionError("EXECUTION_POLICY", "hosted backend cannot grant read-only private context paths");
+  return config;
+}