Skip to content

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

Python
10.5 KB
Raw Blame
// Experimental isolate-native host. Pass a statically imported WebAssembly.Module.
import type { SpanObserver, TraceSpan } from "./otel.ts";
export interface WorkerTool {
  name: string;
  description: string;
  parameters: Record<string, unknown>;
  /** Must reject malformed/untrusted inputs before execute is called. */
  validate(input: unknown): boolean;
  execute(input: unknown, context: { signal: AbortSignal }): string | Promise<string>;
}
export interface WorkerAgentOptions {
  model: string;
  instructions?: string;
  maxSteps?: number;
  tools?: readonly WorkerTool[];
  /** Full chat-completions URL; HTTPS except explicitly opted-in loopback tests. */
  endpoint: string;
  token?: string;
  fetch?: typeof fetch;
  allowLoopbackHttp?: boolean;
  /** Optional content-free lifecycle observer; never awaited by execution. */
  observe?: SpanObserver;
}
export interface WorkerResult { text: string; modelCalls: number; toolCalls: number }
export interface WorkerAgent {
  prompt(text: string, options?: { signal?: AbortSignal }): Promise<WorkerResult>;
  cancel(): void;
}
type Core = {
  memory: WebAssembly.Memory;
  graff_worker_in_ptr(): number;
  graff_worker_in_cap(): number;
  graff_worker_out_ptr(): number;
  graff_worker_out_len(): number;
  graff_worker_create(len: number): number;
  graff_worker_prompt(len: number): number;
  graff_worker_cancel(): void;
};
type HostCall = (kind: number, ptr: number, len: number, reply: number, cap: number) => Promise<number>;
type Jspi = {
  Suspending: new (fn: HostCall) => NonNullable<Parameters<typeof WebAssembly.instantiate>[1]>[string][string];
  promising(fn: Core["graff_worker_prompt"]): (len: number) => Promise<number>;
};
const encoder = new TextEncoder();
const decoder = new TextDecoder("utf-8", { fatal: true, ignoreBOM: false });
const LIMIT = 1024 * 1024;
const object = (v: unknown): v is Record<string, unknown> => v !== null && typeof v === "object" && !Array.isArray(v);
const aborted = () => new DOMException("Agent cancelled", "AbortError");
function abortable<T>(work: Promise<T>, signal: AbortSignal): Promise<T> {
  return new Promise((resolve, reject) => {
    const abort = () => reject(aborted());
    signal.addEventListener("abort", abort, { once: true });
    if (signal.aborted) abort();
    work.then(resolve, reject).finally(() => signal.removeEventListener("abort", abort));
  });
}
async function responseBytes(response: Response, signal: AbortSignal): Promise<Uint8Array> {
  if (!response.body) throw new Error("Model response has no body");
  const reader = response.body.getReader();
  const chunks: Uint8Array[] = [];
  let length = 0;
  try {
    while (true) {
      const part = await abortable(reader.read(), signal);
      if (part.done) break;
      length += part.value.byteLength;
      if (length > LIMIT) throw new Error("Model response exceeds 1 MiB");
      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;
}

/** No native process, filesystem, dynamic compilation, or credential enters Wasm. */
export async function createWorkerAgent(module: WebAssembly.Module, options: WorkerAgentOptions): Promise<WorkerAgent> {
  const jspi = WebAssembly as unknown as Jspi;
  if (typeof jspi.Suspending !== "function" || typeof jspi.promising !== "function") {
    throw new Error("Worker runtime requires WebAssembly JSPI");
  }
  const endpoint = new URL(options.endpoint);
  const loopback = ["localhost", "127.0.0.1", "[::1]"].includes(endpoint.hostname);
  if (endpoint.username || endpoint.password || endpoint.hash ||
      (endpoint.protocol !== "https:" && !(options.allowLoopbackHttp && loopback && endpoint.protocol === "http:"))) {
    throw new Error("Use an explicit HTTPS model endpoint (loopback HTTP requires opt-in)");
  }
  if (!options.model || (options.maxSteps !== undefined &&
      (!Number.isInteger(options.maxSteps) || options.maxSteps < 1 || options.maxSteps > 64))) {
    throw new Error("Model and maxSteps (1..64) are required to be valid");
  }
  const tools = new Map<string, WorkerTool>();
  for (const tool of options.tools ?? []) {
    if (!/^[a-zA-Z0-9_-]{1,64}$/.test(tool.name) || tools.has(tool.name) ||
        typeof tool.validate !== "function" || typeof tool.execute !== "function") throw new Error("Invalid or duplicate tool");
    tools.set(tool.name, tool);
  }
  let core: Core;
  let active: AbortController | undefined;
  let busy = false;
  const host: HostCall = async (kind, ptr, len, reply, cap) => {
    try {
      const signal = active?.signal;
      if (!signal || signal.aborted || len > LIMIT || cap > LIMIT) return -1;
      const raw = decoder.decode(new Uint8Array(core.memory.buffer, ptr, len));
      const request: unknown = JSON.parse(raw);
      let bytes: Uint8Array;
      if (kind === 1) {
        if (!object(request) || request.stream !== false) return -1;
        const headers = new Headers({ "content-type": "application/json" });
        if (options.token) headers.set("authorization", `Bearer ${options.token}`);
        const response = await abortable((options.fetch ?? fetch)(endpoint.href, {
          method: "POST", headers, body: raw, signal, redirect: "manual",
        }), signal);
        if (!response.ok) { void response.body?.cancel().catch(() => {}); return -1; }
        bytes = await responseBytes(response, signal);
      } else if (kind === 2) {
        let result = { text: "Unknown or malformed tool call", is_error: true };
        const tool = object(request) && typeof request.name === "string" ? tools.get(request.name) : undefined;
        if (tool && object(request) && typeof request.id === "string") {
          try {
            if (tool.validate(request.input)) {
              const text = await abortable(Promise.resolve().then(() => {
                if (signal.aborted) throw aborted();
                return tool.execute(request.input, { signal });
              }), signal);
              result = typeof text === "string" ? { text, is_error: false } : { text: "Tool must return text", is_error: true };
            }
          } catch { result = { text: "Tool execution failed", is_error: true }; }
        }
        bytes = encoder.encode(JSON.stringify(result));
        if (bytes.length > LIMIT || bytes.length > cap) {
          bytes = encoder.encode(JSON.stringify({ text: "Tool response exceeds limit", is_error: true }));
        }
      } else return -1;
      if (signal.aborted || bytes.length > cap || bytes.length > LIMIT) return -1;
      // Awaited work may grow Wasm memory: always reacquire the current buffer.
      new Uint8Array(core.memory.buffer, reply, bytes.length).set(bytes);
      return bytes.length;
    } catch { return -1; }
  };
  const instance = await WebAssembly.instantiate(module, { env: { graff_host_call: new jspi.Suspending(host) } });
  core = instance.exports as unknown as Core;
  if (!(core.memory instanceof WebAssembly.Memory) || ["graff_worker_in_ptr", "graff_worker_in_cap",
      "graff_worker_out_ptr", "graff_worker_out_len", "graff_worker_create", "graff_worker_prompt",
      "graff_worker_cancel"].some(name => typeof instance.exports[name] !== "function")) {
    throw new Error("Missing experimental worker ABI exports");
  }
  const write = (text: string) => {
    const bytes = encoder.encode(text);
    if (bytes.length > core.graff_worker_in_cap()) throw new Error("Agent input exceeds Wasm input capacity");
    new Uint8Array(core.memory.buffer, core.graff_worker_in_ptr(), bytes.length).set(bytes);
    return bytes.length;
  };
  const output = (status: number): unknown => {
    const length = core.graff_worker_out_len();
    if (length > LIMIT) throw new Error("Agent output exceeds limit");
    const result: unknown = JSON.parse(decoder.decode(new Uint8Array(core.memory.buffer, core.graff_worker_out_ptr(), length)));
    if (status !== 0 || (object(result) && "error" in result)) throw new Error("Worker engine failed");
    return result;
  };
  const status = core.graff_worker_create(write(JSON.stringify({
    model: options.model, instructions: options.instructions, maxSteps: options.maxSteps ?? 16,
    tools: [...tools.values()].map(tool => ({ type: "function", function: {
      name: tool.name, description: tool.description, parameters: tool.parameters,
    } })),
  })));
  if (status !== 0) throw new Error("Worker engine configuration failed");
  const prompt = jspi.promising(core.graff_worker_prompt);
  const cancel = () => { if (active && !active.signal.aborted) { active.abort(); core.graff_worker_cancel(); } };
  return {
    cancel,
    async prompt(text, { signal } = {}) {
      if (busy) throw new Error("Agent prompt is already running");
      if (signal?.aborted) throw aborted();
      busy = true;
      active = new AbortController();
      signal?.addEventListener("abort", cancel, { once: true });
      let span: TraceSpan | undefined;
      try {
        if (options.observe) {
          try {
            const hex = (bytes: number) => Array.from(crypto.getRandomValues(new Uint8Array(bytes)),
              value => value.toString(16).padStart(2, "0")).join("");
            span = { traceId: hex(16), spanId: hex(8), name: "graff.turn",
              startTimeUnixNano: (BigInt(Date.now()) * 1_000_000n).toString(), endTimeUnixNano: "0",
              status: { code: 2 } };
          } catch { /* Observability cannot prevent a turn. */ }
        }
        const code = await prompt(write(text));
        if (active.signal.aborted) throw aborted();
        const result = output(code);
        if (!object(result) || typeof result.text !== "string" || !Number.isInteger(result.modelCalls) ||
            !Number.isInteger(result.toolCalls)) throw new Error("Malformed engine output");
        if (span) {
          span.status = { code: 1 };
          span.attributes = { "graff.api_calls": result.modelCalls as number };
        }
        return result as unknown as WorkerResult;
      } finally {
        signal?.removeEventListener("abort", cancel);
        active = undefined;
        busy = false;
        if (span) {
          try {
            const end = BigInt(Date.now()) * 1_000_000n;
            span.endTimeUnixNano = (end < BigInt(span.startTimeUnixNano) ? BigInt(span.startTimeUnixNano) : end).toString();
            // Consume rejected observers without awaiting slow or stuck observers.
            void Promise.resolve(options.observe?.(span)).catch(() => {});
          } catch { /* No errors or execution content enter telemetry. */ }
        }
      }
    },
  };
}