@uchibeke/gallivant 0.0.0-stage → 0.2.1

package/lib/openai_agents_http.mjs

@@ -0,0 +1,87 @@
+// Direct documented Agents REST transport. No SDK loop or inference fallback.
+import { executionError, EXECUTION_LIMITS } from "./execution_io.mjs";
+export const AGENTS_API_VERSION = "agents=v1";
+export const AGENTS_LIMITS = Object.freeze({ responseBytes: 1_048_576, pageSize: 100, pages: 20, streamBytes: 65_536, streamEvents: 100, uploadBytes: 5 * 1024 * 1024, inputBytes: 3 * 1024 * 1024 });
+function retryDelay(value, now) {
+  const header = value?.trim() ?? "";
+  // HTTP accepts delta-seconds and three HTTP-date formats. Do not let
+  // Date.parse interpret malformed numeric values as calendar dates.
+  const date = /^(?:[A-Za-z]{3}, \d{2} [A-Za-z]{3} \d{4} \d{2}:\d{2}:\d{2} GMT|[A-Za-z]+, \d{2}-[A-Za-z]{3}-\d{2} \d{2}:\d{2}:\d{2} GMT|[A-Za-z]{3} [A-Za-z]{3} [ \d]\d \d{2}:\d{2}:\d{2} \d{4})$/;
+  const delay = /^\d+$/.test(header) ? Math.min(EXECUTION_LIMITS.maxBackoffMs, Number(header) * 1000) : date.test(header) ? Date.parse(header.endsWith(" GMT") ? header : `${header} GMT`) - now : 0;
+  return Number.isFinite(delay) ? Math.min(EXECUTION_LIMITS.maxBackoffMs, Math.max(0, delay)) : 0;
+}
+export function agentsHttp({ credential, organization, project, fetcher = fetch, clock = Date }) {
+  const headers = async () => {
+    const key = await credential();
+    if (!key) throw executionError("AGENTS_AUTH", "provide an application OPENAI_API_KEY with api.agents.read/write and api.responses.write; API billing is separate from ChatGPT subscriptions");
+    return { Authorization: `Bearer ${key}`, "OpenAI-Beta": AGENTS_API_VERSION, ...(organization ? { "OpenAI-Organization": organization } : {}), ...(project ? { "OpenAI-Project": project } : {}) };
+  };
+  async function response(path, { signal, method = "GET", body, key, accept } = {}) {
+    if (!/^\/(?:agents|models)\//.test(path) && path !== "/agents/sessions") throw executionError("AGENTS_PATH", "unsupported Agents endpoint");
+    if (body && Buffer.byteLength(JSON.stringify(body)) > AGENTS_LIMITS.inputBytes) throw executionError("AGENTS_SIZE", "input exceeds the bounded request; supply smaller portable sources");
+    const result = await fetcher(`https://api.openai.com/v1${path}`, { method, signal, redirect: "error", headers: { ...await headers(), ...(body ? { "Content-Type": "application/json" } : {}), ...(key ? { "Idempotency-Key": key } : {}), ...(accept ? { Accept: accept } : {}) }, ...(body ? { body: JSON.stringify(body) } : {}) });
+    if (!result.ok) {
+      await result.body?.cancel(); // Never put provider error bodies/credentials in public errors.
+      const error = executionError(result.status === 401 || result.status === 403 ? "AGENTS_AUTH" : result.status === 429 ? "AGENTS_THROTTLED" : "AGENTS_HTTP", `Agents API HTTP ${result.status}; request ${result.headers.get("x-request-id") || "unknown"}; check scoped access, billing or resource configuration`);
+      error.retryAfterMs = retryDelay(result.headers.get("retry-after"), clock.now());
+      throw error;
+    }
+    return result;
+  }
+  async function bytes(result, max = AGENTS_LIMITS.responseBytes) {
+    if (Number(result.headers.get("content-length") || 0) > max) { await result.body?.cancel(); throw executionError("AGENTS_SIZE", "provider response exceeds the bounded limit"); }
+    const reader = result.body?.getReader();
+    if (!reader) return Buffer.alloc(0);
+    const chunks = []; let size = 0;
+    try {
+      for (;;) { const { value, done } = await reader.read(); if (done) break; size += value.length; if (size > max) throw executionError("AGENTS_SIZE", "provider response exceeds the bounded limit"); chunks.push(value); }
+      return Buffer.concat(chunks);
+    } finally { await reader.cancel(); reader.releaseLock(); }
+  }
+  const request = async (path, options) => {
+    const value = await bytes(await response(path, options));
+    if (!value.length) return null;
+    try { return JSON.parse(value.toString("utf8")); } catch { throw executionError("AGENTS_PROTOCOL", "invalid provider JSON"); }
+  };
+  // Connect first, buffer while the caller retrieves authoritative state. Each
+  // bounded operation closes its stream; periodic coordinator polling recovers it.
+  async function subscribe(sessionId, signal) {
+    const controller = new AbortController();
+    const abort = () => controller.abort(); signal?.addEventListener("abort", abort, { once: true });
+    if (signal?.aborted) controller.abort();
+    let reader;
+    try { reader = (await response(`/agents/sessions/${encodeURIComponent(sessionId)}/events?stream=true`, { signal: controller.signal, accept: "text/event-stream" })).body.getReader(); }
+    catch (error) { signal?.removeEventListener("abort", abort); throw error; }
+    const events = []; let gap = false, pending = "", total = 0;
+    const decoder = new TextDecoder();
+    const pumping = (async () => {
+      try {
+        for (;;) {
+          const { done, value } = await reader.read(); if (done) { gap = true; break; }
+          total += value.length;
+          if (total > AGENTS_LIMITS.streamBytes) { gap = true; break; }
+          pending = (pending + decoder.decode(value, { stream: true })).replace(/\r\n/g, "\n");
+          let end;
+          while ((end = pending.indexOf("\n\n")) >= 0) {
+            const block = pending.slice(0, end); pending = pending.slice(end + 2);
+            const data = block.split("\n").filter(line => line.startsWith("data:")).map(line => line.slice(5).trimStart()).join("\n");
+            if (!data || data === "[DONE]") continue;
+            try { const event = JSON.parse(data); if (events.length < AGENTS_LIMITS.streamEvents) events.push(event); else gap = true; }
+            catch { gap = true; }
+          }
+          if (events.length >= AGENTS_LIMITS.streamEvents) { gap = true; break; }
+        }
+      } catch { gap = true; }
+    })();
+    return { events, get gap() { return gap; }, async close() { controller.abort(); await reader.cancel().catch(() => {}); await pumping; reader.releaseLock(); signal?.removeEventListener("abort", abort); } };
+  }
+  async function page(path, signal, after = null) {
+    const separator = path.includes("?") ? "&" : "?";
+    const value = await request(`${path}${separator}limit=${AGENTS_LIMITS.pageSize}&order=asc${after ? `&after=${encodeURIComponent(after)}` : ""}`, { signal });
+    if (!Array.isArray(value?.data) || value.data.length > AGENTS_LIMITS.pageSize || typeof value.has_more !== "boolean") throw executionError("AGENTS_PROTOCOL", "invalid provider page");
+    const next = value.has_more ? value.last_id || value.data.at(-1)?.id : null;
+    if (value.has_more && (!next || next === after || typeof next !== "string" || next.length > 512)) throw executionError("AGENTS_PROTOCOL", "provider pagination does not advance");
+    return { data: value.data, next };
+  }
+  return { request, subscribe, page, download: async (path, signal) => bytes(await response(path, { signal })) };
+}

package/lib/openai_agents_input.mjs

@@ -0,0 +1,15 @@
+// Same source/authority boundary for first launch, resume and review corrections.
+import { prepareAgentsSources } from "./openai_agents_sources.mjs";
+import { executionError } from "./execution_io.mjs";
+import { taskProviderAllowance } from "./task_allowance.mjs";
+export async function agentsInput(ctx, id, entry, input, contextPaths) {
+  if (contextPaths?.length) throw executionError("EXECUTION_POLICY", "hosted backend cannot enforce configured read-only private context_paths");
+  const config = ctx.config.harness[entry.harness];
+  if (!config) throw executionError("AGENTS_CONFIG", "selected managed API account is not configured");
+  const overlays = [];
+  if (entry.prd) overlays.push({ path: entry.prd, text: ctx.readPrd(id) });
+  for (const path of entry.sources || []) overlays.push({ path, text: ctx.readSource(id, path) });
+  const source = await prepareAgentsSources({ worktree: entry.worktree, inputHead: input.inputHead, repo: entry.repo, branch: entry.branch, base: entry.base, overlays });
+  return { ...input, repo: entry.repo, branch: entry.branch, base: entry.base, allowance: taskProviderAllowance(config.allowance, entry.task), mandatoryPolicy: config.mandatory_policy || [], model: config.model, environment: config.environment,
+    sources: { data: source.bytes.toString("base64"), hash: source.hash, hashes: source.hashes, modes: source.modes, inputHead: source.inputHead, repo: source.repo, branch: source.branch } };
+}

package/lib/openai_agents_sources.mjs

@@ -0,0 +1,112 @@
+import { createHash } from "node:crypto";
+import { gzipSync } from "node:zlib";
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+const sourceExec = promisify(execFile);
+import { readRepositoryText, assertRepositoryTargets } from "./repository_files.mjs";
+import { parseTaskSources } from "./task_contract.mjs";
+import { executionError } from "./execution_io.mjs";
+import { AGENTS_LIMITS } from "./openai_agents_http.mjs";
+export const contentHash = value => value === null ? null : createHash("sha256").update(value).digest("hex");
+export function portablePath(path) {
+  const parsed = parseTaskSources([path]);
+  if (parsed.problems.length || parsed.paths[0] !== path || path.split("/").some(p => !p || p === ".") || /[\x00-\x1f\x7f]/.test(path)) throw executionError("AGENTS_SOURCE", "unsafe or private portable source/result path");
+  return path;
+}
+// Only approved brief/source overlays may differ from HEAD. An explicit resume
+// must never describe preserved local edits while dispatching stale Git blobs.
+export async function assertAgentsCheckout({ worktree, overlays = [], signal }, exec = sourceExec) {
+  const allowed = new Set(overlays.map(item => portablePath(typeof item === "string" ? item : item.path)));
+  const { stdout } = await exec("git", ["status", "--porcelain=v1", "-z", "--untracked-files=all"], { cwd: worktree, env: { ...process.env, GIT_OPTIONAL_LOCKS: "0" }, signal, encoding: "utf8", maxBuffer: 10 * 1024 * 1024, timeout: 20_000 });
+  for (const entry of stdout.split("\0").filter(Boolean)) {
+    if (entry.length < 4 || entry[2] !== " " || /[RCU]/.test(entry.slice(0, 2)) || !allowed.has(entry.slice(3))) {
+      throw executionError("AGENTS_DIRTY_SOURCE", "hosted execution requires unfinished repository edits to be committed before resume; preserve the index/worktree, commit the intended changes on the owned branch, then resume the existing session; only approved brief/source overlays may remain uncommitted");
+    }
+  }
+}
+// Immutable Git blobs, plus the foundation's explicitly snapshotted brief and
+// carried sources. Never upload the checkout's environment or Git history.
+export async function prepareAgentsSources({ worktree, inputHead, repo, branch, base, overlays = [], signal }, exec = sourceExec) {
+  if (!/^(?:[a-f0-9]{40}|[a-f0-9]{64})$/.test(inputHead || "") || !/^[\w.-]+\/[\w.-]+$/.test(repo || "") || typeof branch !== "string" || branch === base) throw executionError("AGENTS_SOURCE", "exact source head and owned repository/branch/base are required");
+  const options = { cwd: worktree, signal, encoding: "utf8", maxBuffer: 10 * 1024 * 1024, timeout: 20_000 };
+  const { stdout: head } = await exec("git", ["rev-parse", "HEAD"], options);
+  if (head.trim() !== inputHead) throw executionError("AGENTS_SOURCE", "source head changed during preparation");
+  await assertAgentsCheckout({ worktree, overlays, signal }, exec);
+  const { stdout: listing } = await exec("git", ["ls-tree", "-r", "-z", inputHead], options);
+  const files = new Map(); let size = 0;
+  const treeEntry = new RegExp(`^(100644|100755) blob ([a-f0-9]{${inputHead.length}})\\t(.+)$`, "s");
+  for (const entry of listing.split("\0").filter(Boolean)) {
+    const match = entry.match(treeEntry);
+    if (!match) throw executionError("AGENTS_SOURCE", "portable source includes a symlink, submodule or unsupported mode");
+    const [, mode, blob, rawPath] = match, path = portablePath(rawPath);
+    const { stdout: data } = await exec("git", ["cat-file", "blob", blob], { ...options, encoding: "buffer" });
+    size += data.length;
+    if (size > 10 * 1024 * 1024) throw executionError("AGENTS_SIZE", "portable source exceeds the 10 MiB expanded limit");
+    files.set(path, { path, mode: Number.parseInt(mode.slice(-3), 8), data: data.toString("base64"), hash: contentHash(data) });
+  }
+  for (const item of overlays) {
+    const path = portablePath(item.path);
+    if (typeof item.text !== "string" || readRepositoryText(worktree, path) !== item.text) throw executionError("AGENTS_SOURCE", "portable brief/source differs from its saved snapshot");
+    const bytes = Buffer.from(item.text); size += bytes.length;
+    if (size > 10 * 1024 * 1024) throw executionError("AGENTS_SIZE", "portable source exceeds the expanded limit");
+    files.set(path, { path, mode: files.get(path)?.mode ?? 0o644, data: bytes.toString("base64"), hash: contentHash(bytes) });
+  }
+  assertRepositoryTargets([...files.keys()], [...files.keys()]);
+  await assertAgentsCheckout({ worktree, overlays, signal }, exec);
+  if ((await exec("git", ["rev-parse", "HEAD"], options)).stdout.trim() !== inputHead) throw executionError("AGENTS_SOURCE", "source head changed during preparation");
+  // Carried files can be uncommitted on the coordinator's fresh checkout. Include
+  // them in delivery even when the agent leaves their approved bytes unchanged,
+  // so the single PR writer commits them with the implementation. Later receipt
+  // repairs use the same verified files without manufacturing a code change.
+  const manifest = { version: 1, inputHead, repo, branch, base, deliveryPaths: overlays.map(item => item.path), files: [...files.values()] };
+  const bytes = gzipSync(Buffer.from(JSON.stringify(manifest)));
+  if (bytes.length > AGENTS_LIMITS.uploadBytes || bytes.length * 4 / 3 > AGENTS_LIMITS.inputBytes - 65_536) throw executionError("AGENTS_SIZE", "portable snapshot exceeds inline request limits; reduce explicitly selected context");
+  return { bytes, hash: contentHash(bytes), inputHead, repo, branch, base, hashes: Object.fromEntries(manifest.files.map(f => [f.path, f.hash])), modes: Object.fromEntries(manifest.files.map(f => [f.path, f.mode])) };
+}
+
+// Shipped into the sandbox. Outputs contain text changes and test records only;
+// GitHub credentials and API keys stay with the coordinator's existing PR writer.
+export const AGENTS_WORKSPACE_HELPER = String.raw`import base64,gzip,hashlib,json,pathlib,shutil,subprocess,sys
+root=pathlib.Path('/workspace/repo')
+def safe(path):
+    p=pathlib.PurePosixPath(path)
+    if p.is_absolute() or not p.parts or any(x in ('..','.git') for x in p.parts): raise ValueError('unsafe path')
+    target=root.joinpath(*p.parts)
+    if any(x.is_symlink() for x in (target,*target.parents) if x==root or root in x.parents): raise ValueError('output symlink')
+    return target
+def sha(data): return hashlib.sha256(data).hexdigest()
+def restore(source, expected):
+    raw=pathlib.Path(source).read_bytes()
+    if sha(raw)!=expected: raise ValueError('snapshot hash mismatch')
+    m=json.loads(gzip.decompress(raw))
+    if root.exists(): shutil.rmtree(root)
+    root.mkdir()
+    for f in m['files']:
+        p=safe(f['path']); data=base64.b64decode(f['data'],validate=True)
+        if sha(data)!=f['hash']: raise ValueError('source hash mismatch')
+        p.parent.mkdir(parents=True,exist_ok=True); p.write_bytes(data); p.chmod(f['mode'])
+    subprocess.run(['git','init','-b',m['branch']],cwd=root,check=True,stdout=subprocess.DEVNULL)
+    subprocess.run(['git','add','--all'],cwd=root,check=True)
+    subprocess.run(['git','-c','user.name=Workspace','-c','user.email=workspace@localhost','commit','-qm','Input snapshot'],cwd=root,check=True)
+    pathlib.Path('/workspace/baseline.json').write_text(json.dumps(m))
+def publish(prfile, testsfile):
+    m=json.loads(pathlib.Path('/workspace/baseline.json').read_text()); before={f['path']:f for f in m['files']}; files=[]
+    paths=set(before)
+    selected=subprocess.run(['git','ls-files','--cached','--others','--exclude-standard','-z'],cwd=root,check=True,stdout=subprocess.PIPE).stdout.decode('utf-8')
+    paths.update(x for x in selected.split('\x00') if x)
+    for name in sorted(paths):
+        p=safe(name); previous=before.get(name)
+        if p.exists() and (p.stat().st_mode&0o777 != (previous['mode'] if previous else 0o644) or p.stat().st_size>max(1000000,len(base64.b64decode(previous['data'])) if previous else 0)): raise ValueError('unsupported output mode/size')
+        data=p.read_bytes() if p.exists() else None
+        after=sha(data) if data is not None else None
+        if after==(previous['hash'] if previous else None) and name not in m.get('deliveryPaths',[]): continue
+        if data is not None and b'\x00' in data: raise ValueError('unsupported output content')
+        files.append({'path':name,'beforeHash':previous['hash'] if previous else None,'afterHash':after,'text':data.decode('utf-8') if data is not None else None})
+    result={'version':1,'inputHead':m['inputHead'],'repo':m['repo'],'branch':m['branch'],'files':files,'pr':json.loads(pathlib.Path(prfile).read_text()),'tests':json.loads(pathlib.Path(testsfile).read_text())}
+    raw=json.dumps(result).encode()
+    if len(files)>100 or len(raw)>1000000: raise ValueError('bounded result exceeded')
+    out=pathlib.Path('/workspace/outputs'); out.mkdir(exist_ok=True); (out/'result.json').write_bytes(raw)
+if sys.argv[1]=='restore': restore(sys.argv[2],sys.argv[3])
+elif sys.argv[1]=='publish': publish(sys.argv[2],sys.argv[3])
+else: raise ValueError('unknown operation')
+`;