Skip to content

graff — a fast agentic coding harness in Zig: multi-provider, MCP, workflows, DGM evolution loop, TS/Python SDKs

Python
12.5 KB
Raw Blame
// Fetch-only access to existing Codegraff Fleet sandboxes; no local processes.
export interface SandboxExecResult { exitCode: number; result: string }
export interface SandboxRequestOptions { signal?: AbortSignal }
export interface SandboxExecOptions extends SandboxRequestOptions { timeoutSeconds?: number; cwd?: string }
export interface CodegraffSandboxAttachOptions {
  /** A cg_sk_ key, sent only in the gateway Authorization header. */
  token: string;
  /** May bridge requests locally; this client still constructs only gateway HTTPS URLs. */
  fetch?: typeof fetch;
}
export interface CodegraffSandboxOptions extends CodegraffSandboxAttachOptions, SandboxRequestOptions {
  autoStopMinutes?: number;
}
export interface CodegraffSandbox {
  readonly id: string;
  /** Aborting stops HTTP waiting, not the remote command. Destroy the VM to stop it. */
  exec(command: string, options?: SandboxExecOptions): Promise<SandboxExecResult>;
  upload(path: string, text: string, options?: SandboxRequestOptions): Promise<void>;
  /** Downloads UTF-8 text; binary files are rejected. */
  download(path: string, options?: SandboxRequestOptions): Promise<string>;
  /** Independent of create/operation signals. Call in finally to end billing. */
  destroy(): Promise<void>;
}
export type SandboxErrorCode = "invalid_argument" | "http" | "network" | "invalid_response" |
  "response_too_large" | "output_too_large" | "file_too_large" | "aborted" | "timeout" | "destroyed";
/** Deliberately excludes request data, response bodies, URLs, IDs, and error causes. */
export class SandboxError extends Error {
  readonly name = "SandboxError";
  constructor(
    readonly code: SandboxErrorCode,
    readonly status?: number,
    /** An attach failure exposed an ID, but its best-effort DELETE failed. */
    readonly cleanupFailed = false,
  ) {
    super(`Sandbox error: ${code}${status === undefined ? "" : ` (${status})`}`);
  }
}
const ORIGIN = "https://gateway.codegraff.com";
const COMMAND_LIMIT = 8 * 1024;
const FILE_LIMIT = 64 * 1024;
const OUTPUT_LIMIT = 64 * 1024;
const RESPONSE_LIMIT = 128 * 1024;
const REQUEST_MS = 45_000;
const CREATE_MS = 90_000;
const CLEANUP_MS = 5_000;
const encoder = new TextEncoder();
const object = (value: unknown): value is Record<string, unknown> =>
  value !== null && typeof value === "object" && !Array.isArray(value);
const validId = (value: unknown): value is string =>
  typeof value === "string" && /^[a-zA-Z0-9_-]{1,256}$/.test(value);
function fail(code: SandboxErrorCode): never { throw new SandboxError(code); }
function integer(value: number, minimum: number, maximum: number): number {
  if (!Number.isInteger(value) || value < minimum || value > maximum) fail("invalid_argument");
  return value;
}
function textBytes(value: string, limit: number, code: SandboxErrorCode): Uint8Array {
  // Check code units first so an oversized input is not copied just to reject it.
  if (typeof value !== "string" || value.length > limit) fail(code);
  const bytes = encoder.encode(value);
  if (bytes.length > limit) fail(code);
  return bytes;
}
function validPath(path: string): void {
  textBytes(path, 4096, "invalid_argument");
  if (!path || /[\x00-\x1f\x7f]/.test(path)) fail("invalid_argument");
}
function base64(bytes: Uint8Array): string {
  let binary = "";
  for (let i = 0; i < bytes.length; i += 8192) {
    binary += String.fromCharCode(...bytes.subarray(i, i + 8192));
  }
  return btoa(binary);
}
function fromBase64(value: unknown): string {
  if (typeof value !== "string") fail("invalid_response");
  if (value.length > 4 * Math.ceil(FILE_LIMIT / 3)) fail("file_too_large");
  if (!/^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/.test(value)) {
    fail("invalid_response");
  }
  let binary: string;
  try { binary = atob(value); } catch { return fail("invalid_response"); }
  if (binary.length > FILE_LIMIT) fail("file_too_large");
  const bytes = new Uint8Array(binary.length);
  for (let i = 0; i < binary.length; i++) bytes[i] = binary.charCodeAt(i);
  try { return new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(bytes); }
  catch { return fail("invalid_response"); }
}
function abortable<T>(work: Promise<T>, signal: AbortSignal, reason: () => SandboxError): Promise<T> {
  return new Promise((resolve, reject) => {
    const abort = () => { signal.removeEventListener("abort", abort); reject(reason()); };
    signal.addEventListener("abort", abort, { once: true });
    if (signal.aborted) abort();
    work.then(
      value => { signal.removeEventListener("abort", abort); resolve(value); },
      () => { signal.removeEventListener("abort", abort); reject(signal.aborted ? reason() : new SandboxError("network")); },
    );
  });
}
async function responseBytes(response: Response, signal: AbortSignal, reason: () => SandboxError): Promise<Uint8Array> {
  if (!response.body) return new Uint8Array(0);
  const reader = response.body.getReader();
  const chunks: Uint8Array[] = [];
  let length = 0;
  try {
    while (true) {
      const part = await abortable(reader.read(), signal, reason);
      if (part.done) break;
      length += part.value.byteLength;
      if (length > RESPONSE_LIMIT) fail("response_too_large");
      chunks.push(part.value);
    }
  } catch (error) {
    void reader.cancel().catch(() => {});
    throw error;
  } finally {
    reader.releaseLock();
  }
  const bytes = new Uint8Array(length);
  let offset = 0;
  for (const chunk of chunks) { bytes.set(chunk, offset); offset += chunk.length; }
  return bytes;
}
interface Reply { status: number; ok: boolean; payload: unknown; empty: boolean }
const endpoint = (id: string) => `/${encodeURIComponent(id)}`;
const check = (reply: Reply) => { if (!reply.ok) throw new SandboxError("http", reply.status); };
function transport(options: CodegraffSandboxAttachOptions) {
  if (!options || typeof options.token !== "string" || options.token.length > 4096 ||
      !/^cg_sk_[A-Za-z0-9_-]+$/.test(options.token) ||
      (options.fetch !== undefined && typeof options.fetch !== "function")) fail("invalid_argument");
  const token = options.token;
  const fetcher = options.fetch ?? globalThis.fetch;
  async function request(
    method: "POST" | "DELETE", path: string, body?: Record<string, unknown>,
    signal?: AbortSignal, milliseconds = REQUEST_MS,
  ): Promise<Reply> {
    if (signal?.aborted) fail("aborted");
    const controller = new AbortController();
    let timedOut = false;
    const reason = () => new SandboxError(timedOut ? "timeout" : "aborted");
    const abort = () => controller.abort();
    signal?.addEventListener("abort", abort, { once: true });
    if (signal?.aborted) abort();
    const timer = setTimeout(() => { timedOut = true; controller.abort(); }, milliseconds);
    try {
      if (controller.signal.aborted) throw reason();
      const headers = new Headers({ authorization: `Bearer ${token}` });
      if (body !== undefined) headers.set("content-type", "application/json");
      // Workers supports manual redirects, not the browser's error mode.
      // Non-2xx replies fail below; bearer credentials never follow redirects.
      const init = {
        method, headers, body: body === undefined ? undefined : JSON.stringify(body),
        signal: controller.signal, redirect: "manual" as const,
      };
      const pending = fetcher(`${ORIGIN}/v1/sandboxes${path}`, init);
      // An injected fetch may ignore abort. Stop waiting anyway and discard late bodies.
      void pending.then(response => {
        if (controller.signal.aborted) void response.body?.cancel().catch(() => {});
      }, () => {});
      const response = await abortable(pending, controller.signal, reason);
      const bytes = await responseBytes(response, controller.signal, reason);
      if (controller.signal.aborted) throw reason();
      let payload: unknown;
      try { payload = JSON.parse(new TextDecoder("utf-8", { fatal: true, ignoreBOM: false }).decode(bytes)); }
      catch { payload = undefined; }
      return { status: response.status, ok: response.ok, payload, empty: bytes.length === 0 };
    } catch (error) {
      if (controller.signal.aborted) throw reason();
      if (error instanceof SandboxError) throw error;
      throw new SandboxError("network");
    } finally {
      clearTimeout(timer);
      signal?.removeEventListener("abort", abort);
    }
  }
  async function remove(id: string, milliseconds = REQUEST_MS): Promise<void> {
    const reply = await request("DELETE", endpoint(id), undefined, undefined, milliseconds);
    if (reply.status !== 404) check(reply);
  }
  return { request, remove };
}
/**
 * Uses only the fixed public HTTPS gateway, with redirects disabled and no retries.
 * The create signal applies only to creation; later calls have their own signals.
 * Requests wait at most 45s (creation 90s, independent cleanup 5s). An exec may
 * keep running after that HTTP deadline; always destroy in a caller-owned finally.
 * Commands: 8 KiB UTF-8; files/output: 64 KiB; streamed response bodies: 128 KiB.
 */
export async function createCodegraffSandbox(options: CodegraffSandboxOptions): Promise<CodegraffSandbox> {
  const api = transport(options);
  const autoStopMinutes = integer(options.autoStopMinutes ?? 5, 1, 30);
  const created = await api.request("POST", "", { provider: "fleet", autoStopMinutes }, options.signal, CREATE_MS);
  const payload = created.payload;
  const id = object(payload) && validId(payload.id) ? payload.id : undefined;
  const attachedId = object(payload) && object(payload.error) && validId(payload.error.sandboxId)
    ? payload.error.sandboxId : undefined;
  const createError = !created.ok ? new SandboxError("http", created.status)
    : !id || (object(payload) && "error" in payload) ? new SandboxError("invalid_response")
    : options.signal?.aborted ? new SandboxError("aborted") : undefined;
  if (createError) {
    // Fleet may allocate successfully and then fail attachment. Never leave that ID
    // billed just because the caller aborted: this DELETE has its own deadline.
    const cleanupId = attachedId ?? id;
    let cleanupFailed = false;
    if (cleanupId) {
      try { await api.remove(cleanupId, CLEANUP_MS); } catch { cleanupFailed = true; }
    }
    throw new SandboxError(createError.code, createError.status, cleanupFailed);
  }
  // The successful create branch above guarantees a validated, path-safe ID.
  return sandboxClient(id as string, api);
}
/** Reattach without HTTP or allocation, e.g. to destroy a stored ID from an alarm. */
export function attachCodegraffSandbox(id: string, options: CodegraffSandboxAttachOptions): CodegraffSandbox {
  if (!validId(id)) fail("invalid_argument");
  return sandboxClient(id, transport(options));
}
function sandboxClient(sandboxId: string, { request, remove }: ReturnType<typeof transport>): CodegraffSandbox {
  let destroyed = false;
  let destroying: Promise<void> | undefined;
  const live = () => { if (destroyed || destroying) fail("destroyed"); };
  return {
    id: sandboxId,
    async exec(command, { signal, timeoutSeconds = 30, cwd = "/tmp" } = {}) {
      live();
      validPath(cwd);
      textBytes(command, COMMAND_LIMIT, "invalid_argument");
      if (!command.trim()) fail("invalid_argument");
      integer(timeoutSeconds, 1, 60);
      const reply = await request("POST", `${endpoint(sandboxId)}/exec`, {
        command, cwd, timeoutSeconds,
      }, signal);
      check(reply);
      const result = reply.payload;
      if (!object(result) || typeof result.exitCode !== "number" || !Number.isSafeInteger(result.exitCode) ||
          typeof result.result !== "string") fail("invalid_response");
      textBytes(result.result, OUTPUT_LIMIT, "output_too_large");
      return { exitCode: result.exitCode, result: result.result };
    },
    async upload(path, text, { signal } = {}) {
      live();
      validPath(path);
      const bytes = textBytes(text, FILE_LIMIT, "file_too_large");
      const reply = await request("POST", `${endpoint(sandboxId)}/upload`, {
        path, contentBase64: base64(bytes),
      }, signal);
      check(reply);
      if (!reply.empty && (!object(reply.payload) || "error" in reply.payload)) fail("invalid_response");
    },
    async download(path, { signal } = {}) {
      live();
      validPath(path);
      const reply = await request("POST", `${endpoint(sandboxId)}/download`, { path }, signal);
      check(reply);
      if (!object(reply.payload)) fail("invalid_response");
      return fromBase64(reply.payload.contentBase64);
    },
    async destroy() {
      if (destroyed) return;
      if (destroying) return destroying;
      destroying = remove(sandboxId).then(() => { destroyed = true; });
      try { await destroying; } finally { destroying = undefined; }
    },
  };
}