graff — a fast agentic coding harness in Zig: multi-provider, MCP, workflows, DGM evolution loop, TS/Python SDKs
Python
#!/usr/bin/env python3
"""Generate the TypeScript and Python SDKs from `harness --schema`.
Single source of truth: the harness emits its own interface (providers,
models, tools, and the --json event protocol). This script turns that JSON
into typed clients in sdk/ts/ and sdk/py/. Run in CI on every release so the
SDKs never drift from the binary — never hand-edit the generated files.
Usage:
harness --schema | python3 sdk/generate.py
python3 sdk/generate.py --schema path/to/schema.json
python3 sdk/generate.py --harness ./zig-out/bin/harness # runs it for you
"""
import json
import os
import subprocess
import sys
import tempfile
from event_templates import STDIO_EVENTS, REMOTE_EVENTS
HERE = os.path.dirname(os.path.abspath(__file__))
def load_schema(argv):
if "--schema" in argv:
with open(argv[argv.index("--schema") + 1]) as f:
return json.load(f)
if "--harness" in argv:
binary = argv[argv.index("--harness") + 1]
# Deterministic by construction (#370): dynamic model catalogs cached
# under $HOME (~/.codegraff gateway/kimi lists) must never leak into
# the committed MODELS list, so the harness runs with a scrubbed HOME.
with tempfile.TemporaryDirectory(prefix="sdk-schema-home-") as home:
env = {**os.environ, "HOME": home, "USERPROFILE": home}
out = subprocess.run([binary, "--schema"], capture_output=True, text=True, check=True, env=env)
return json.loads(out.stdout)
if sys.stdin.isatty():
sys.exit("no schema: pipe `harness --schema` in, or pass --schema FILE / --harness BIN")
return json.load(sys.stdin)
def write(path, content):
os.makedirs(os.path.dirname(path), exist_ok=True)
with open(path, "w") as f:
f.write(content)
print(f" wrote {os.path.relpath(path, HERE)} ({len(content)} bytes)")
def gen_ts(schema):
models = sorted({m["name"] for m in schema["models"]})
tools = [t["name"] for t in schema["tools"]]
providers = [p["id"] for p in schema["providers"]]
version = schema.get("version", "0")
model_union = " | ".join(f'"{m}"' for m in models)
if schema.get("dynamic_model_providers"):
model_union += " | (string & {})"
tool_union = " | ".join(f'"{t}"' for t in tools)
provider_union = " | ".join(f'"{p}"' for p in providers)
header = "// AUTO-GENERATED by sdk/generate.py from `harness --schema`. Do not edit.\n"
return header + f'''
import {{ spawn, type ChildProcessByStdio }} from "node:child_process";
import {{ createHash, randomBytes }} from "node:crypto";
import {{ accessSync, constants, existsSync, readFileSync, writeFileSync }} from "node:fs";
import {{ createRequire }} from "node:module";
import {{ homedir }} from "node:os";
import {{ delimiter, dirname, join }} from "node:path";
import {{ createInterface }} from "node:readline";
import type {{ Readable, Writable }} from "node:stream";
export const HARNESS_VERSION = "{version}";
export type ModelName = {model_union};
export type ToolName = {tool_union};
export type ProviderId = {provider_union};
/** Events streamed by `harness --json` (one JSON object per stdout line), each
* discriminated by `type` — the analogue of codegraff's AgentEvent stream.
* `seq` is a monotonic, gap-free, 1-based per-session id: it is what lets a
* supervisor say exactly where it stopped reading, and it CONTINUES across a
* `--resume` rather than restarting (#330).
* Forward compatibility: a newer (edge) harness binary may stream event
* types not in this union; the runtime yields them as-is and every loop in
* this client only terminates on `turn`/`error`, so unknown events are safe
* to ignore in consumer code too. */
{STDIO_EVENTS}
/** Fingerprint of a system prompt as used in `.graff/trajectories` —
* the aggregate DGM-style archive — and by `Harness.score()`:
* first 8 bytes of SHA-256, hex (16 chars). */
export function promptFingerprint(text: string): string {{
return createHash("sha256").update(text).digest("hex").slice(0, 16);
}}
// ── Options ──────────────────────────────────────────────────────────────
export interface HarnessOptions {{
/** Path to the CLI binary. Defaults to the matching optional
* `@codegraff/graff-*` package, then `graff` on PATH. */
binary?: string;
/** Working directory for the agent. Defaults to the parent process cwd. */
cwd?: string;
env?: NodeJS.ProcessEnv;
/** Pin the startup model or provider, e.g. "gpt-5.5", "claude-opus-4-8", "codex". */
model?: ModelName | ProviderId | string;
/** Skip every bash/tool/MCP permission prompt (passes --yolo). */
yolo?: boolean;
/** Replace the built-in system prompt (the cwd project-instructions file is still appended). */
systemPrompt?: string;
/** Append extra text to the end of the system prompt. */
appendSystemPrompt?: string;
/** Hard per-turn root tool-call budget. */
maxToolCalls?: number;
/** Invocation-wide provider-call ceiling shared by all agent work. */
maxModelCalls?: number;
/** Reject duplicate root tool name+normalized-input calls per turn. */
dedupeToolCalls?: boolean;
/** Start automatic compaction at this percent of the context window (10-95; default 80). */
compactAt?: number;
/** Extra raw flags. `--json` is always added. */
args?: string[];
}}
/** Native image input for a user turn. URLs stay URLs on every provider;
* base64 is converted to that provider's image-content shape by Graff. */
export type ImageInput =
| {{ type: "image_url"; url: string }}
| {{ type: "image_base64"; mediaType: string; data: string }};
export interface ChatOptions {{
/** User prompt for this turn. */
prompt: string;
/** Native vision parts (max 16); never flattened into prompt text. */
images?: ImageInput[];
/** Run this turn in isolated, read-only review mode. */
review?: boolean;
/** Abort the turn mid-flight: on abort the SDK writes {{"type":"cancel"}}
* out-of-band (the REPL's Esc path); the stream still runs to the
* cancelled turn's terminal event — an `error` event ("turn cancelled"). */
signal?: AbortSignal;
}}
export interface AnswerOptions {{
text?: string;
cancelled?: boolean;
callId?: string;
}}
/** Reasoning effort levels for setEffort; `none` requires a supported model route. */
export type EffortLevel = "none" | "low" | "medium" | "high" | "xhigh" | "max" | "ultra";
/** Structured result of one turn: the final assistant text plus the usage
* the harness reported on the terminal `turn` event. */
export interface AskResult {{
/** Final assistant text. */
text: string;
/** Server-reported context size at turn end. */
contextTokens: number;
/** Known turn cost in USD; check usageComplete before treating it as a total. */
costUsd: number;
inputTokens: number;
uncachedInputTokens: number;
cacheReadTokens: number;
outputTokens: number;
/** Provider API calls made this turn. */
apiCalls: number;
/** Calls served under a subscription (unmetered) login. */
subscriptionCalls: number;
/** Calls with no pricing data. */
unpricedCalls: number;
/** False when the turn finished incomplete (interrupted/stalled). */
complete?: boolean;
metadataComplete?: boolean;
/** False means token/cost values are known subtotals only; absent on older servers. */
usageComplete?: boolean;
missingUsageCalls?: number;
unreportedFailedAttempts?: number;
}}
export interface RunAgentOptions extends HarnessOptions {{
/** User prompt to send to the agent. */
prompt: string;
/** Native vision parts (max 16); never flattened into prompt text. */
images?: ImageInput[];
}}
function spawnArgs(o: HarnessOptions): string[] {{
const a = ["--json"];
if (o.yolo) a.push("--yolo");
if (o.model) a.push("--model", o.model);
if (o.maxToolCalls !== undefined) a.push("--max-tool-calls", String(o.maxToolCalls));
if (o.maxModelCalls !== undefined) a.push("--max-model-calls", String(o.maxModelCalls));
if (o.dedupeToolCalls) a.push("--dedupe-tool-calls");
if (o.compactAt !== undefined) a.push("--compact-at", String(o.compactAt));
if (o.systemPrompt) a.push("--system-prompt", o.systemPrompt);
if (o.appendSystemPrompt) a.push("--append-system-prompt", o.appendSystemPrompt);
if (o.args) a.push(...o.args);
return a;
}}
/** Anonymous per-install id for SDK telemetry — its own id file, distinct
* from the harness CLI's install id, so SDK users aren't conflated with
* direct CLI users. Only ever leaves the machine when the harness has an
* OTLP endpoint configured (OTEL_EXPORTER_OTLP_ENDPOINT); opt out entirely
* with GRAFF_NO_TELEMETRY=1 or by passing --no-telemetry in `args`. */
function sdkInstallId(): string {{
const p = join(homedir(), ".simple-harness-sdk-id");
try {{
const v = readFileSync(p, "utf8").trim();
if (/^[0-9a-f]{{32}}$/.test(v)) return v;
}} catch {{}}
const id = randomBytes(16).toString("hex");
try {{ writeFileSync(p, id + "\\n"); }} catch {{}}
return id;
}}
const PLATFORM_PACKAGES: Readonly<Record<string, string>> = {{
"darwin-arm64": "@codegraff/graff-darwin-arm64",
"darwin-x64": "@codegraff/graff-darwin-x64",
"linux-arm64": "@codegraff/graff-linux-arm64",
"linux-x64": "@codegraff/graff-linux-x64",
"win32-arm64": "@codegraff/graff-win32-arm64",
"win32-x64": "@codegraff/graff-win32-x64",
}};
/** Resolve the binary bundled by npm. `createRequire` anchors lookup beside
* this installed SDK, so hoisted and nested optional dependencies both work. */
function packagedBinary(): {{ path?: string; packageName?: string }} {{
const packageName = PLATFORM_PACKAGES[`${{process.platform}}-${{process.arch}}`];
if (!packageName) return {{}};
const require = createRequire(import.meta.url);
let manifest: string;
try {{ manifest = require.resolve(`${{packageName}}/package.json`); }} catch {{
return {{ packageName }};
}}
let protocol: unknown;
try {{ protocol = JSON.parse(readFileSync(manifest, "utf8")).graffProtocol; }} catch {{}}
if (protocol !== HARNESS_VERSION) {{
throw new Error(`${{packageName}} uses graff protocol ${{String(protocol ?? "unknown")}}, but @codegraff/sdk requires ${{HARNESS_VERSION}}. Reinstall @codegraff/sdk without disabling optional dependencies.`);
}}
const binary = process.platform === "win32" ? "graff.exe" : "graff";
const path = join(dirname(manifest), "bin", binary);
return existsSync(path) ? {{ path, packageName }} : {{ packageName }};
}}
/** Prefer the version-pinned npm binary, then a caller-supplied PATH. Return
* an absolute path so probing and spawning cannot disagree. */
function defaultBinary(env: NodeJS.ProcessEnv): string {{
const packaged = packagedBinary();
if (packaged.path) return packaged.path;
const binary = process.platform === "win32" ? "graff.exe" : "graff";
for (const dir of (env.PATH ?? env.Path ?? env.path ?? "").split(delimiter)) {{
if (!dir) continue;
const path = join(dir, binary);
try {{
accessSync(path, process.platform === "win32" ? constants.F_OK : constants.X_OK);
return path;
}} catch {{}}
}}
const install = packaged.packageName
? `Reinstall @codegraff/sdk so npm can install ${{packaged.packageName}}, or install graff on PATH.`
: "Install graff on PATH or pass Harness.init({{ binary: ... }}).";
throw new Error(`No graff binary is available for ${{process.platform}}-${{process.arch}}. ${{install}}`);
}}
const TELEMETRY_DEFAULT = "https://harness-telemetry.rachpradhan.workers.dev";
/** Best-effort OTLP ERROR log for failures the harness process cannot report
* itself (it may be dead or never have started): spawn failures, mid-turn
* exits. Same pipeline and opt-out as harness telemetry — skipped when
* GRAFF_NO_TELEMETRY is set; endpoint from OTEL_EXPORTER_OTLP_ENDPOINT /
* GRAFF_OTEL_ENDPOINT, else the default collector. Fire-and-forget. */
function reportError(kind: string, detail: string): void {{
if (process.env.GRAFF_NO_TELEMETRY) return;
const base = (process.env.OTEL_EXPORTER_OTLP_ENDPOINT || process.env.GRAFF_OTEL_ENDPOINT || TELEMETRY_DEFAULT).replace(/\\/+$/, "");
const url = base.endsWith("/v1/logs") ? base : base + "/v1/logs";
const payload = JSON.stringify({{ resourceLogs: [{{
resource: {{ attributes: [
{{ key: "service.name", value: {{ stringValue: "simple-harness" }} }},
{{ key: "client.name", value: {{ stringValue: process.env.HARNESS_CLIENT ?? "sdk-ts" }} }},
{{ key: "sdk.install.id", value: {{ stringValue: sdkInstallId() }} }},
] }},
scopeLogs: [{{ scope: {{ name: "simple-harness-sdk" }}, logRecords: [{{
timeUnixNano: String(Date.now() * 1e6),
severityText: "ERROR",
body: {{ stringValue: "error" }},
attributes: [
{{ key: "kind", value: {{ stringValue: kind }} }},
{{ key: "detail", value: {{ stringValue: detail.slice(0, 512) }} }},
],
}}] }}],
}}] }});
try {{
fetch(url, {{
method: "POST",
// default runtime UAs can be bot-blocked by Cloudflare in front of
// the collector (403) — identify explicitly.
headers: {{ "content-type": "application/json", "user-agent": "simple-harness-sdk-ts" }},
body: payload,
signal: AbortSignal.timeout(3000),
}}).catch(() => {{}});
}} catch {{ /* fetch unavailable: drop */ }}
}}
/** Prompt-free SDK fleet signal. Local is the fail-closed default; SDKs have
* no interactive artifact-review UI, so prompt_text is never admitted. */
export function fleetSignal(kind: string, attrs: Record<string, string | number> = {{}}): void {{
if (process.env.GRAFF_NO_TELEMETRY) return;
const privacy = process.env.GRAFF_LEARNING_PRIVACY ?? "local";
if (!(["aggregate", "templates", "examples"] as string[]).includes(privacy)) return;
const admitted = {{ ...attrs }};
delete admitted.prompt_text;
let base = process.env.OTEL_EXPORTER_OTLP_ENDPOINT || process.env.GRAFF_OTEL_ENDPOINT || TELEMETRY_DEFAULT;
while (base.endsWith("/")) base = base.slice(0, -1);
const url = base.endsWith("/v1/logs") ? base : base + "/v1/logs";
const attributes: Array<Record<string, unknown>> = [
{{ key: "kind", value: {{ stringValue: kind }} }},
];
for (const [k, v] of Object.entries(admitted)) {{
attributes.push({{ key: k, value: typeof v === "number" ? {{ doubleValue: v }} : {{ stringValue: String(v) }} }});
}}
const payload = JSON.stringify({{ resourceLogs: [{{
resource: {{ attributes: [
{{ key: "service.name", value: {{ stringValue: "simple-harness" }} }},
{{ key: "client.name", value: {{ stringValue: process.env.HARNESS_CLIENT ?? "sdk-ts" }} }},
{{ key: "sdk.install.id", value: {{ stringValue: sdkInstallId() }} }},
] }},
scopeLogs: [{{ scope: {{ name: "simple-harness-sdk" }}, logRecords: [{{
timeUnixNano: String(Date.now() * 1e6),
body: {{ stringValue: "fleet" }},
attributes,
}}] }}],
}}] }});
try {{
fetch(url, {{
method: "POST",
headers: {{ "content-type": "application/json", "user-agent": "simple-harness-sdk-ts" }},
body: payload,
signal: AbortSignal.timeout(3000),
}}).catch(() => {{}});
}} catch {{ /* fetch unavailable: drop */ }}
}}
/** Spawn env: tag the harness child as SDK-driven for telemetry attribution
* (explicit caller values win). The id file is only read/created when
* telemetry is actually live — same gating as the harness CLI's own id. */
function sdkEnv(base?: NodeJS.ProcessEnv): NodeJS.ProcessEnv {{
const env = {{ ...(base ?? process.env) }};
env.HARNESS_CLIENT ??= "sdk-ts";
const live = !env.GRAFF_NO_TELEMETRY &&
(env.OTEL_EXPORTER_OTLP_ENDPOINT || env.GRAFF_OTEL_ENDPOINT);
if (live && !env.HARNESS_SDK_INSTALL_ID) env.HARNESS_SDK_INSTALL_ID = sdkInstallId();
return env;
}}
// ── Harness (parallel to codegraff's `Graff`) ──────────────────────────────
/** A live `harness --json` agent. Multi-turn: each `chat()` / `session().send()`
* continues the same conversation (the process retains history). */
export class Harness {{
// stdin/stdout piped, stderr inherited (tool progress straight to the
// user's terminal) — hence the ByStdio<Writable, Readable, null> shape.
private proc: ChildProcessByStdio<Writable, Readable, null>;
private queue: ((e: Event | null) => void)[] = [];
private buffer: Event[] = [];
/** Tail of the operation chain (see acquireOp). Always resolves. */
private opTail: Promise<void> = Promise.resolve();
private closed = false;
private closePromise?: Promise<void>;
constructor(opts: HarnessOptions = {{}}) {{
const env = sdkEnv(opts.env);
this.proc = spawn(opts.binary ?? defaultBinary(env), spawnArgs(opts), {{
cwd: opts.cwd,
env,
stdio: ["pipe", "pipe", "inherit"],
}});
const rl = createInterface({{ input: this.proc.stdout }});
rl.on("line", (line) => {{
if (!line.trim()) return;
let ev: Event;
try {{ ev = JSON.parse(line) as Event; }} catch {{ return; }}
const w = this.queue.shift();
if (w) w(ev); else this.buffer.push(ev);
}});
this.proc.on("close", () => {{ for (const w of this.queue) w(null); this.queue = []; }});
// Spawn failures (ENOENT etc.) never emit "close"; report and release
// any waiters so callers get the mid-turn-death error instead of a hang.
this.proc.on("error", (e) => {{
reportError("spawn", String(e));
for (const w of this.queue) w(null);
this.queue = [];
}});
// cancel()/answer() are lock-free, so their writes can race process
// death: swallow stdin stream errors instead of crashing the host.
this.proc.stdin.on("error", () => {{}});
}}
/** Start a long-lived agent (codegraff parity for `Graff.init`). */
static init(opts: HarnessOptions = {{}}): Harness {{ return new Harness(opts); }}
private next(): Promise<Event | null> {{
if (this.buffer.length) return Promise.resolve(this.buffer.shift()!);
return new Promise((resolve) => this.queue.push(resolve));
}}
/** Operation chain: turns (chat) and acked controls (setSystemPrompt,
* setModel, setEffort, compact, score) run one at a time, so a control
* can never steal a chat's terminal event off the shared event queue.
* The tail always RESOLVES — an operation's error goes only to its own
* caller and can never poison the queue behind it. answer() and cancel()
* bypass the chain on purpose: the harness reads both out-of-band. */
private acquireOp(): Promise<() => void> {{
if (this.closed) return Promise.reject(new Error("harness is closed"));
let release!: () => void;
const gate = new Promise<void>((resolve) => {{ release = resolve; }});
const acquired = this.opTail.then(() => release);
this.opTail = this.opTail.then(() => gate);
return acquired;
}}
/** Run `op` holding the operation lock (see acquireOp). */
private async runOp<T>(op: () => Promise<T>): Promise<T> {{
const release = await this.acquireOp();
try {{
return await op();
}} finally {{
release();
}}
}}
/** Run one turn; async-iterate events up to and including `turn`/`error`.
* Holds the operation lock until the terminal event, so a control issued
* mid-turn (setSystemPrompt, setModel, …) queues BEHIND the turn instead
* of stealing its events off the shared queue. Pass `signal` to cancel
* the turn (see ChatOptions.signal / cancel()). */
async *chat(input: string | ChatOptions): AsyncGenerator<Event> {{
const prompt = typeof input === "string" ? input : input.prompt;
const type = typeof input === "string" || !input.review ? "user" : "review";
const images = typeof input === "string" ? undefined : input.images?.map((image) =>
image.type === "image_base64"
? {{ type: image.type, media_type: image.mediaType, data: image.data }}
: image);
const signal = typeof input === "string" ? undefined : input.signal;
// Already aborted: send nothing — a cancel written before the turn's
// first line would be cleared again when the turn starts.
signal?.throwIfAborted();
const release = await this.acquireOp();
let aborted = false;
const onAbort = () => {{ if (aborted) return; aborted = true; this.cancel(); }};
try {{
this.proc.stdin.write(JSON.stringify({{ type, text: prompt, ...(images?.length ? {{ images }} : {{}}) }}) + "\\n");
if (signal) {{
signal.addEventListener("abort", onAbort, {{ once: true }});
if (signal.aborted) onAbort(); // aborted between the entry check and here
}}
while (true) {{
const ev = await this.next();
if (ev === null) {{
// Process closed without a terminal event: died mid-turn. Reported
// to telemetry and thrown instead of silently ending the stream.
reportError("died", `harness exited mid-turn (code=${{this.proc.exitCode}})`);
throw new Error(`harness exited mid-turn (code=${{this.proc.exitCode}})`);
}}
yield ev;
if (ev.type === "turn" || ev.type === "error") return;
}}
}} finally {{
if (signal) signal.removeEventListener("abort", onAbort);
release();
}}
}}
/** Run a turn and return its final text plus the usage the harness
* reported on the terminal `turn` event (tokens, cost, call breakdown).
* Rejects on an `error` event — including a cancelled turn. */
async askResult(input: string | ChatOptions): Promise<AskResult> {{
let result: AskResult | null = null;
for await (const ev of this.chat(input)) {{
if (ev.type === "turn") {{
result = {{
text: ev.text,
contextTokens: ev.context_tokens,
costUsd: ev.cost_usd,
inputTokens: ev.input_tokens,
uncachedInputTokens: ev.uncached_input_tokens,
cacheReadTokens: ev.cache_read_tokens,
outputTokens: ev.output_tokens,
apiCalls: ev.api_calls,
subscriptionCalls: ev.subscription_calls,
unpricedCalls: ev.unpriced_calls,
complete: ev.complete,
metadataComplete: ev.metadata_complete,
usageComplete: ev.usage_complete,
missingUsageCalls: ev.missing_usage_calls,
unreportedFailedAttempts: ev.unreported_failed_attempts,
}};
}}
if (ev.type === "error") throw new Error(ev.message);
}}
if (!result) throw new Error("turn ended without a terminal event");
return result;
}}
/** Run a turn and return just the final assistant text. */
async ask(input: string | ChatOptions): Promise<string> {{
return (await this.askResult(input)).text;
}}
/** Run one isolated, read-only review turn and return its final report. */
review(input: string | ChatOptions): Promise<string> {{
const options = typeof input === "string" ? {{ prompt: input }} : input;
return this.ask({{ ...options, review: true }});
}}
/** Answer an in-flight ask_user event. Call this while consuming chat()
* when you receive {{ type: "ask_user", call_id, ... }}. */
answer(input: string | AnswerOptions): void {{
const payload = typeof input === "string"
? {{ type: "answer", text: input, cancelled: false }}
: {{ type: "answer", text: input.text ?? "", cancelled: input.cancelled ?? false, call_id: input.callId }};
this.proc.stdin.write(JSON.stringify(payload) + "\\n");
}}
/** Replace (or with append=true, extend) the system prompt for subsequent
* turns. Call between turns; resolves on the harness's ack.
*
* KV-cache warning (Manus context-engineering lessons): the system prompt
* heads the cached prefix, so ANY mutation — append included — invalidates
* the cache for the whole conversation; the next turn re-reads everything
* at full input price. Prefer the spawn-time `systemPrompt` /
* `appendSystemPrompt` options; mutate only at task boundaries, never
* back-and-forth inside a loop. */
async setSystemPrompt(text: string, append = false): Promise<void> {{
return this.runOp(async () => {{
this.proc.stdin.write(JSON.stringify({{ type: "set_system_prompt", text, append }}) + "\\n");
// Edge-version durability: a newer harness may emit event types this
// client predates — skip them while waiting for the ack (the chat loop
// already tolerates unknowns the same way) instead of throwing.
while (true) {{
const ev = await this.next();
if (ev === null) {{ reportError("died", "harness closed before acking set_system_prompt"); throw new Error("harness closed"); }}
if (ev.type === "error") throw new Error(ev.message);
if (ev.type === "system_prompt") return;
}}
}});
}}
/** Tack extra instructions onto the current system prompt. */
appendSystemPrompt(text: string): Promise<void> {{ return this.setSystemPrompt(text, true); }}
/** Cancel the in-flight turn — the SDK analogue of the REPL's Esc. Writes
* {{"type":"cancel"}} straight to stdin, which the harness inbox reads
* OUT-OF-BAND (ahead of any queued request), so this deliberately does
* NOT join the operation queue: a cancel queued behind the turn it means
* to stop would fire too late. Lock-free like answer(). The active
* chat() stream still runs to the cancelled turn's terminal event. */
cancel(): void {{
this.proc.stdin.write(JSON.stringify({{ type: "cancel" }}) + "\\n");
}}
/** Switch provider/model mid-session — the provider-qualified form of the
* protocol's set_model control. Call between turns; resolves on the
* `model` ack, rejects on the harness's `error` event (unknown model,
* missing key/login, …). Serialized with chat() and the other controls. */
setModel(provider: ProviderId | string, model: ModelName | string): Promise<void> {{
return this.runOp(async () => {{
this.proc.stdin.write(JSON.stringify({{ type: "set_model", provider, model }}) + "\\n");
while (true) {{
const ev = await this.next();
if (ev === null) {{ reportError("died", "harness closed before acking set_model"); throw new Error("harness closed"); }}
if (ev.type === "error") throw new Error(ev.message);
if (ev.type === "model") return;
}}
}});
}}
/** Set the reasoning effort for later turns (protocol set_effort).
* Resolves on the `effort` ack; serialized like the other controls. */
setEffort(level: EffortLevel): Promise<void> {{
return this.runOp(async () => {{
this.proc.stdin.write(JSON.stringify({{ type: "set_effort", level }}) + "\\n");
while (true) {{
const ev = await this.next();
if (ev === null) {{ reportError("died", "harness closed before acking set_effort"); throw new Error("harness closed"); }}
if (ev.type === "error") throw new Error(ev.message);
if (ev.type === "effort") return;
}}
}});
}}
/** Compact the conversation history now (protocol compact). Resolves on
* the `compact` ack; rejects when compaction fails — the harness leaves
* history unchanged in that case. Serialized like the other controls. */
compact(): Promise<void> {{
return this.runOp(async () => {{
this.proc.stdin.write(JSON.stringify({{ type: "compact" }}) + "\\n");
while (true) {{
const ev = await this.next();
if (ev === null) {{ reportError("died", "harness closed before acking compact"); throw new Error("harness closed"); }}
if (ev.type === "error") throw new Error(ev.message);
if (ev.type === "compact") return;
}}
}});
}}
/** Record an evaluation score for an agent/prompt variant in the
* aggregate `.graff/trajectories` archive — the DGM evaluation
* phase writing back. `promptOrSha` is either the full system-prompt
* text (fingerprinted for you) or an existing 16-hex fingerprint.
* Pass `parent` (text or sha) when the variant was mutated from another
* prompt: that genome-lineage edge is what DGM parent selection counts
* children with. Pass `niche` (reviewer/researcher/implementer/skeptic, or
* a custom agent) to file the score into that MAP-Elites cell so the fleet
* can promote a champion for the role; full text produces only a prompt-free
* fingerprint proposal until the SDK has review UI. Scale: the wire scale is
* [0, 1]. Pass scale "unit" to assert `value` is already in [0, 1]
* (anything else is rejected), or "percent" to always send value/100
* (accepts [0, 100] — a percent-scale 0.5 means 0.005, not 0.5). Without
* `scale` the harness heuristic applies: [0, 1] passes as-is, values in
* (1, 100] are treated as percentages and normalized to /100, and values
* outside [0, 100] are rejected. Call between turns; resolves on the
* harness's ack. */
async score(promptOrSha: string, value: number, notes = "", parent?: string, niche?: string, scale?: "unit" | "percent"): Promise<void> {{
const sha = /^[0-9a-f]{{16}}$/.test(promptOrSha) ? promptOrSha : promptFingerprint(promptOrSha);
const parent_sha = parent === undefined ? undefined
: /^[0-9a-f]{{16}}$/.test(parent) ? parent : promptFingerprint(parent);
// The SDK emitter strips prompt_text until it has an interactive review UI.
if (niche && !/^[0-9a-f]{{16}}$/.test(promptOrSha)) fleetSignal("propose", {{ niche, prompt_sha: sha, parent_sha: parent_sha ?? "", prompt_text: promptOrSha }});
return this.runOp(async () => {{
this.proc.stdin.write(JSON.stringify({{ type: "score", prompt_sha: sha, score: value, notes, parent_sha, niche, scale }}) + "\\n");
// Same edge-version tolerance as setSystemPrompt: skip unknown events
// while waiting for the ack.
while (true) {{
const ev = await this.next();
if (ev === null) {{ reportError("died", "harness closed before acking score"); throw new Error("harness closed"); }}
if (ev.type === "error") throw new Error(ev.message);
if (ev.type === "score") {{ fleetSignal("submit", {{ prompt_sha: sha, parent_sha: parent_sha ?? "", niche: niche ?? "" }}); return; }}
}}
}});
}}
/** Pull the fleet's live champion personas (GET /v1/elites). Local mode
* returns before contacting the telemetry collector. */
async pullElites(providerClass: string, evalSetHash?: string): Promise<Array<Record<string, unknown>>> {{
if (!(["aggregate", "templates", "examples"] as string[]).includes(process.env.GRAFF_LEARNING_PRIVACY ?? "local")) return [];
let base = process.env.OTEL_EXPORTER_OTLP_ENDPOINT || process.env.GRAFF_OTEL_ENDPOINT || TELEMETRY_DEFAULT;
while (base.endsWith("/")) base = base.slice(0, -1);
if (base.endsWith("/v1/logs")) base = base.slice(0, -"/v1/logs".length);
let q = "provider_class=" + encodeURIComponent(providerClass);
if (evalSetHash) q += "&eval_set_hash=" + encodeURIComponent(evalSetHash);
let elites: Array<Record<string, unknown>> = [];
try {{
const res = await fetch(base + "/v1/elites?" + q, {{ signal: AbortSignal.timeout(5000) }});
const j = (await res.json()) as {{ elites?: Array<Record<string, unknown>> }};
elites = j?.elites ?? [];
}} catch {{ /* collector unreachable: no elites */ }}
fleetSignal("elite_pull", {{ provider_class: providerClass, eval_set_hash: evalSetHash ?? "", n_elites: elites.length }});
return elites;
}}
/** A multi-turn session view over this agent (codegraff parity). */
session(): HarnessSession {{ return new HarnessSession(this); }}
/** The harness schema version this client was generated from. */
version(): string {{ return HARNESS_VERSION; }}
/** Cancel active work, close stdin, and await the child's clean exit so its
* telemetry and trajectory flushes are durable. Idempotent; force-kills
* only after the graceful deadline. */
close(): Promise<void> {{
if (this.closePromise) return this.closePromise;
this.cancel();
this.closed = true;
this.proc.stdin.end();
this.closePromise = new Promise((resolve) => {{
if (this.proc.exitCode !== null) return resolve();
const timer = setTimeout(() => this.proc.kill(), 15000);
timer.unref?.();
const finish = () => {{ clearTimeout(timer); resolve(); }};
this.proc.once("close", finish);
this.proc.once("error", finish);
}});
return this.closePromise;
}}
/** Alias for close(). */
dispose(): Promise<void> {{ return this.close(); }}
}}
// ── HarnessSession (parallel to codegraff's `GraffSession`) ────────────────
export class HarnessSession {{
private agent: Harness;
/** Wrap an existing agent, or spawn a fresh one. */
constructor(agent: Harness = new Harness()) {{ this.agent = agent; }}
/** Send a user turn; async-iterate its events. */
send(input: string | ChatOptions): AsyncGenerator<Event> {{ return this.agent.chat(input); }}
ask(input: string | ChatOptions): Promise<string> {{ return this.agent.ask(input); }}
askResult(input: string | ChatOptions): Promise<AskResult> {{ return this.agent.askResult(input); }}
review(input: string | ChatOptions): Promise<string> {{ return this.agent.review(input); }}
answer(input: string | AnswerOptions): void {{ return this.agent.answer(input); }}
cancel(): void {{ this.agent.cancel(); }}
setSystemPrompt(text: string, append = false): Promise<void> {{ return this.agent.setSystemPrompt(text, append); }}
setModel(provider: ProviderId | string, model: ModelName | string): Promise<void> {{ return this.agent.setModel(provider, model); }}
setEffort(level: EffortLevel): Promise<void> {{ return this.agent.setEffort(level); }}
compact(): Promise<void> {{ return this.agent.compact(); }}
close(): Promise<void> {{ return this.agent.close(); }}
dispose(): Promise<void> {{ return this.agent.dispose(); }}
}}
// ── Top-level one-shot (parallel to codegraff's `runAgent`) ────────────────
/** Spawn an agent, run a single turn, stream its events, then close. */
export async function* runAgent(opts: RunAgentOptions): AsyncGenerator<Event> {{
const h = new Harness(opts);
try {{
yield* h.chat({{ prompt: opts.prompt, images: opts.images }});
}} finally {{
await h.close();
}}
}}
export const MODELS: ModelName[] = [{", ".join(f'"{m}"' for m in models)}];
export const TOOLS: ToolName[] = [{", ".join(f'"{t}"' for t in tools)}];
'''
def gen_ts_remote(schema):
"""Edge-safe remote client: drives a `harness serve` bridge over fetch +
Web Streams only — zero node: imports, so it runs on Cloudflare Workers,
Deno, Bun, browsers, and Node >= 18 alike. Self-contained on purpose
(its own copy of the generated types): no cross-file imports keeps both
entry points independently consumable."""
models = sorted({m["name"] for m in schema["models"]})
tools = [t["name"] for t in schema["tools"]]
providers = [p["id"] for p in schema["providers"]]
version = schema.get("version", "0")
model_union = " | ".join(f'"{m}"' for m in models)
if schema.get("dynamic_model_providers"):
model_union += " | (string & {})"
tool_union = " | ".join(f'"{t}"' for t in tools)
provider_union = " | ".join(f'"{p}"' for p in providers)
header = "// AUTO-GENERATED by sdk/generate.py from `harness --schema`. Do not edit.\n"
return header + f'''
// Edge-safe remote transport for a `harness serve` bridge: fetch + Web
// Streams only (no node: imports), so it runs on Cloudflare Workers, Deno,
// Bun, browsers, and Node >= 18. The server side is `harness serve`
// (see the "serve" key of `harness --schema`): each session is a real
// `harness --json` child over there, and one POST = one protocol request,
// streamed back as NDJSON until that request's terminal event.
export const HARNESS_VERSION = "{version}";
export type ModelName = {model_union};
export type ToolName = {tool_union};
export type ProviderId = {provider_union};
/** Events streamed by the bridge (same `--json` contract as the stdio SDK).
* `seq` is a monotonic, gap-free, 1-based per-session id the bridge forwards
* unchanged from the child and persists; reconnect with `?from=seq+1` to pick
* the stream back up exactly where you stopped (#330).
* Forward compatibility: a newer (edge) harness may stream event types not
* in this union; every loop here only terminates on its request's terminal
* event, so unknown events pass through and are safe to ignore. */
{REMOTE_EVENTS}
/** Async (WebCrypto) variant of the trajectory-archive prompt fingerprint:
* first 8 bytes of SHA-256, hex (16 chars). */
export async function promptFingerprint(text: string): Promise<string> {{
const d = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(text));
return [...new Uint8Array(d).slice(0, 8)].map((b) => b.toString(16).padStart(2, "0")).join("");
}}
export interface RemoteOptions {{
/** Base URL of the `harness serve` bridge, e.g. "http://127.0.0.1:8787". */
url: string;
/** Bearer token (the bridge's --token / HARNESS_SERVE_TOKEN). */
token?: string;
/** Pin the session's model or provider (overrides the serve default). */
model?: ModelName | ProviderId | string;
/** Skip every permission prompt server-side (passes --yolo to the child).
* Usually what you want: the bridge has no terminal to ask on. */
yolo?: boolean;
/** Replace the built-in system prompt. */
systemPrompt?: string;
/** Append extra text to the system prompt. */
appendSystemPrompt?: string;
/** Hard per-turn root tool-call budget for the child session. */
maxToolCalls?: number;
/** Invocation-wide provider-call ceiling shared by all agent work. */
maxModelCalls?: number;
/** Reject duplicate root tool name+normalized-input calls per turn. */
dedupeToolCalls?: boolean;
/** Attach to an existing LIVE session on this bridge without creating one.
* Skips the create call entirely — use `session` to create-or-resume. */
sessionId?: string;
/** Name a DURABLE session (1-64 chars of [A-Za-z0-9._-]). The bridge runs
* the child as `graff --json --resume <session>` in its workspace, so the
* conversation is autosaved after every turn. Passing the same name to a
* REPLACEMENT bridge picks the run up from the last persisted turn, with
* the event sequence continuing rather than restarting (#330). Omitted:
* the bridge mints a fresh 16-hex name, which is still durable. */
session?: string;
}}
/** What the bridge reports when a session is created or resumed. */
export interface SessionInfo {{
/** The durable session id — also the graff session name on the server. */
session_id: string;
/** A session file already existed: this run continues an earlier one. */
resumed: boolean;
/** Highest seq on the persisted event tape. Reconnect from `last_seq + 1`. */
last_seq: number;
}}
/** Native image input for a user turn. URLs stay URLs on every provider;
* base64 is converted to that provider's image-content shape by Graff. */
export type ImageInput =
| {{ type: "image_url"; url: string }}
| {{ type: "image_base64"; mediaType: string; data: string }};
export interface ChatOptions {{
prompt: string;
/** Native vision parts (max 16); never flattened into prompt text. */
images?: ImageInput[];
review?: boolean;
/** Replay persisted events with seq >= from before this turn's live ones. */
from?: number;
/** Abort the turn mid-flight: on abort the SDK POSTs {{"type":"cancel"}}
* (the bridge answers it ahead of the session's busy lock); the stream
* still runs to the cancelled turn's terminal event — an `error` event
* ("turn cancelled"). */
signal?: AbortSignal;
}}
export interface AnswerOptions {{
text?: string;
cancelled?: boolean;
callId?: string;
}}
/** Reasoning effort levels for setEffort; `none` requires a supported model route. */
export type EffortLevel = "none" | "low" | "medium" | "high" | "xhigh" | "max" | "ultra";
/** Structured result of one turn: the final assistant text plus the usage
* the harness reported on the terminal `turn` event. */
export interface AskResult {{
/** Final assistant text. */
text: string;
/** Server-reported context size at turn end. */
contextTokens: number;
/** Known turn cost in USD; check usageComplete before treating it as a total. */
costUsd: number;
inputTokens: number;
uncachedInputTokens: number;
cacheReadTokens: number;
outputTokens: number;
/** Provider API calls made this turn. */
apiCalls: number;
/** Calls served under a subscription (unmetered) login. */
subscriptionCalls: number;
/** Calls with no pricing data. */
unpricedCalls: number;
/** False when the turn finished incomplete (interrupted/stalled). */
complete?: boolean;
metadataComplete?: boolean;
/** False means token/cost values are known subtotals only; absent on older servers. */
usageComplete?: boolean;
missingUsageCalls?: number;
unreportedFailedAttempts?: number;
}}
export interface RunAgentRemoteOptions extends RemoteOptions {{
prompt: string;
/** Native vision parts (max 16); never flattened into prompt text. */
images?: ImageInput[];
}}
/** Parse a streaming NDJSON response body into events. */
async function* ndjson(res: Response): AsyncGenerator<Event> {{
const body = res.body;
if (!body) throw new Error("bridge response had no body");
const reader = body.getReader();
const dec = new TextDecoder();
let buf = "";
try {{
while (true) {{
const {{ done, value }} = await reader.read();
if (done) break;
buf += dec.decode(value, {{ stream: true }});
let i: number;
while ((i = buf.indexOf("\\n")) >= 0) {{
const line = buf.slice(0, i).trim();
buf = buf.slice(i + 1);
if (line) {{ try {{ yield JSON.parse(line) as Event; }} catch {{ /* skip noise */ }} }}
}}
}}
const tail = buf.trim();
if (tail) {{ try {{ yield JSON.parse(tail) as Event; }} catch {{ /* skip noise */ }} }}
}} finally {{
// Release the body however the consumer left — terminal event, break,
// or throw — so the connection drains back to keep-alive and the
// server-side stream never dangles.
await reader.cancel().catch(() => {{}});
}}
}}
const HEX16 = /^[0-9a-f]{{16}}$/;
/** A session on a remote `harness serve` bridge — the fetch-transport
* analogue of the stdio `Harness` class, same method surface.
*
* Resumability (#330): every event carries a monotonic `seq`, tracked here as
* `lastSeq`. If a stream dies mid-turn, call `reconnect(h.lastSeq + 1)` — the
* bridge kept draining the child into a persisted log the whole time, so you
* get the events you missed and then the live tail. If the whole BRIDGE died,
* point a new `RemoteHarness` at the replacement with the same `session` name
* and the run continues from the last persisted turn. */
export class RemoteHarness {{
private base: string;
private token?: string;
/** Tail of the operation chain (see acquireOp). Always resolves. */
private opTail: Promise<void> = Promise.resolve();
private closed = false;
/** Resolves to the session id (creation is lazy-started in the constructor). */
readonly sessionId: Promise<string>;
/** Resolves to the bridge's create/resume report; null when attaching by
* `sessionId` (no create call was made). */
readonly info: Promise<SessionInfo | null>;
/** Highest `seq` this client has seen. `reconnect(lastSeq + 1)` resumes
* exactly where it stopped; 0 before the first event. */
lastSeq = 0;
constructor(opts: RemoteOptions) {{
this.base = opts.url.replace(/\\/+$/, "");
this.token = opts.token;
if (opts.sessionId) {{
this.sessionId = Promise.resolve(opts.sessionId);
this.info = Promise.resolve(null);
}} else {{
const created = this.create(opts);
// Observe BOTH derived promises up front: a caller that only ever
// awaits one of info/sessionId must not trip an unhandled rejection on
// the other when creation fails — awaiting either still rejects with
// the original cause.
created.catch(() => {{}});
this.info = created;
const sid = created.then((d) => d.session_id);
sid.catch(() => {{}});
this.sessionId = sid;
}}
}}
/** Create a session (codegraff parity for `Graff.init`, remote edition). */
static init(opts: RemoteOptions): RemoteHarness {{ return new RemoteHarness(opts); }}
private headers(): Record<string, string> {{
const h: Record<string, string> = {{ "content-type": "application/json" }};
if (this.token) h.authorization = `Bearer ${{this.token}}`;
return h;
}}
private async req(method: string, path: string, body?: unknown): Promise<Response> {{
const res = await fetch(this.base + path, {{
method,
headers: this.headers(),
body: body === undefined ? undefined : JSON.stringify(body),
}});
if (!res.ok) {{
const detail = await res.text().catch(() => "");
throw new Error(`bridge ${{method}} ${{path}} → ${{res.status}}: ${{detail.slice(0, 256)}}`);
}}
return res;
}}
private async create(opts: RemoteOptions): Promise<SessionInfo> {{
const body: Record<string, unknown> = {{}};
if (opts.session) body.session = opts.session;
if (opts.model) body.model = opts.model;
if (opts.yolo !== undefined) body.yolo = opts.yolo;
if (opts.systemPrompt) body.system_prompt = opts.systemPrompt;
if (opts.appendSystemPrompt) body.append_system_prompt = opts.appendSystemPrompt;
if (opts.maxToolCalls !== undefined) body.maxToolCalls = opts.maxToolCalls;
if (opts.maxModelCalls !== undefined) body.maxModelCalls = opts.maxModelCalls;
if (opts.dedupeToolCalls !== undefined) body.dedupeToolCalls = opts.dedupeToolCalls;
const res = await this.req("POST", "/v1/sessions", body);
const data = (await res.json()) as SessionInfo;
this.lastSeq = data.last_seq ?? 0;
return data;
}}
/** Track the sequence as events go by, so a reconnect needs no bookkeeping
* from the caller. */
private note(ev: Event): Event {{
if (typeof ev.seq === "number" && ev.seq > this.lastSeq) this.lastSeq = ev.seq;
return ev;
}}
/** Operation chain, the client-side mirror of the bridge's
* one-non-answer-request-in-flight rule: turns and acked controls run one
* at a time. The tail always RESOLVES, so one operation's failure cannot
* poison the queue behind it. answer(), cancel(), and reconnect() bypass
* it — the bridge handles all three without taking the protocol lock. */
private acquireOp(): Promise<() => void> {{
let release!: () => void;
const gate = new Promise<void>((resolve) => {{ release = resolve; }});
const acquired = this.opTail.then(() => release);
this.opTail = this.opTail.then(() => gate);
return acquired;
}}
/** Run `op` holding the operation lock (see acquireOp). */
private async runOp<T>(op: () => Promise<T>): Promise<T> {{
const release = await this.acquireOp();
try {{
return await op();
}} finally {{
release();
}}
}}
/** Send one protocol request; stream its events. */
private async *send(payload: Record<string, unknown>, from?: number): AsyncGenerator<Event> {{
const id = await this.sessionId;
const q = from === undefined ? "" : `?from=${{from}}`;
const res = await this.req("POST", `/v1/sessions/${{id}}${{q}}`, payload);
for await (const ev of ndjson(res)) yield this.note(ev);
}}
/** Run one turn; async-iterate events up to and including `turn`/`error`.
* Holds the operation slot until the terminal event (the bridge itself
* allows one non-answer request in flight per session). Pass `signal` to
* cancel the turn (see ChatOptions.signal / cancel()). */
async *chat(input: string | ChatOptions): AsyncGenerator<Event> {{
const prompt = typeof input === "string" ? input : input.prompt;
const type = typeof input === "string" || !input.review ? "user" : "review";
const images = typeof input === "string" ? undefined : input.images?.map((image) =>
image.type === "image_base64"
? {{ type: image.type, media_type: image.mediaType, data: image.data }}
: image);
const from = typeof input === "string" ? undefined : input.from;
const signal = typeof input === "string" ? undefined : input.signal;
signal?.throwIfAborted();
const release = await this.acquireOp();
let aborted = false;
const onAbort = () => {{ if (aborted) return; aborted = true; void this.cancel(); }};
try {{
// Wait until the bridge has accepted the turn and returned stream headers
// before arming cancel. Otherwise an immediately-aborted signal can POST
// cancel first, receive 409, and leave the following turn running.
const id = await this.sessionId;
const q = from === undefined ? "" : `?from=${{from}}`;
const res = await this.req("POST", `/v1/sessions/${{id}}${{q}}`, {{ type, text: prompt, ...(images?.length ? {{ images }} : {{}}) }});
if (signal) {{
signal.addEventListener("abort", onAbort, {{ once: true }});
if (signal.aborted) onAbort();
}}
let terminal = false;
for await (const raw of ndjson(res)) {{
const ev = this.note(raw);
yield ev;
if (ev.type === "turn" || ev.type === "error") {{ terminal = true; break; }}
}}
if (!terminal) throw new Error("bridge stream ended mid-turn (session process died?)");
}} finally {{
if (signal) signal.removeEventListener("abort", onAbort);
release();
}}
}}
/** Re-attach to a session after losing the stream: replay persisted events
* with `seq >= from` (default: everything after what this client already
* saw), then follow live until the in-flight request's terminal event.
* Sends nothing to the model, so it is safe to call while a turn is
* running — including from a different process than the one that started
* it. Also the way to read a completed turn you never received. */
async *reconnect(from = this.lastSeq + 1): AsyncGenerator<Event> {{
const id = await this.sessionId;
const res = await this.req("GET", `/v1/sessions/${{id}}/events?from=${{from}}`);
for await (const ev of ndjson(res)) yield this.note(ev);
}}
/** Run a turn and return its final text plus the usage the harness
* reported on the terminal `turn` event (tokens, cost, call breakdown).
* Rejects on an `error` event — including a cancelled turn. */
async askResult(input: string | ChatOptions): Promise<AskResult> {{
let result: AskResult | null = null;
for await (const ev of this.chat(input)) {{
if (ev.type === "turn") {{
result = {{
text: ev.text,
contextTokens: ev.context_tokens,
costUsd: ev.cost_usd,
inputTokens: ev.input_tokens,
uncachedInputTokens: ev.uncached_input_tokens,
cacheReadTokens: ev.cache_read_tokens,
outputTokens: ev.output_tokens,
apiCalls: ev.api_calls,
subscriptionCalls: ev.subscription_calls,
unpricedCalls: ev.unpriced_calls,
complete: ev.complete,
metadataComplete: ev.metadata_complete,
usageComplete: ev.usage_complete,
missingUsageCalls: ev.missing_usage_calls,
unreportedFailedAttempts: ev.unreported_failed_attempts,
}};
}}
if (ev.type === "error") throw new Error(ev.message);
}}
if (!result) throw new Error("turn ended without a terminal event");
return result;
}}
/** Run a turn and return just the final assistant text. */
async ask(input: string | ChatOptions): Promise<string> {{
return (await this.askResult(input)).text;
}}
/** Run one isolated, read-only review turn and return its final report. */
review(input: string | ChatOptions): Promise<string> {{
const options = typeof input === "string" ? {{ prompt: input }} : input;
return this.ask({{ ...options, review: true }});
}}
/** Answer an in-flight ask_user event. The original chat() stream continues
* and will later yield the ask_user tool_result plus the final turn. */
async answer(input: string | AnswerOptions): Promise<void> {{
const payload = typeof input === "string"
? {{ type: "answer", text: input, cancelled: false }}
: {{ type: "answer", text: input.text ?? "", cancelled: input.cancelled ?? false, call_id: input.callId }};
const res = await this.req("POST", `/v1/sessions/${{await this.sessionId}}`, payload);
await res.text();
}}
/** Cancel the in-flight turn (REPL Esc equivalent): POSTs
* {{"type":"cancel"}} to the bridge, which answers it AHEAD of the
* session's busy lock and forwards it down the child's out-of-band cancel
* path — so it bypasses the client operation queue too. Best-effort: the
* bridge 409s when no request is in flight, which is not an error here. */
async cancel(): Promise<void> {{
const id = await this.sessionId.catch(() => null);
if (id === null) return; // no live session: nothing to cancel
const res = await this.req("POST", `/v1/sessions/${{id}}`, {{ type: "cancel" }}).catch(() => null);
if (res) await res.text().catch(() => {{}});
}}
/** Switch provider/model mid-session — the provider-qualified form of the
* protocol's set_model control. Resolves on the `model` ack, rejects on
* the `error` event; serialized with chat() and the other controls. */
setModel(provider: ProviderId | string, model: ModelName | string): Promise<void> {{
return this.runOp(async () => {{
for await (const ev of this.send({{ type: "set_model", provider, model }})) {{
if (ev.type === "error") throw new Error(ev.message);
if (ev.type === "model") return;
}}
throw new Error("bridge stream ended before acking set_model");
}});
}}
/** Set the reasoning effort for later turns (protocol set_effort).
* Resolves on the `effort` ack; serialized like the other controls. */
setEffort(level: EffortLevel): Promise<void> {{
return this.runOp(async () => {{
for await (const ev of this.send({{ type: "set_effort", level }})) {{
if (ev.type === "error") throw new Error(ev.message);
if (ev.type === "effort") return;
}}
throw new Error("bridge stream ended before acking set_effort");
}});
}}
/** Compact the conversation history now (protocol compact). Resolves on
* the `compact` ack; rejects when compaction fails (history is left
* unchanged in that case). Serialized like the other controls. */
compact(): Promise<void> {{
return this.runOp(async () => {{
for await (const ev of this.send({{ type: "compact" }})) {{
if (ev.type === "error") throw new Error(ev.message);
if (ev.type === "compact") return;
}}
throw new Error("bridge stream ended before acking compact");
}});
}}
/** Replace (or with append=true, extend) the system prompt for later turns.
* Same KV-cache warning as the stdio SDK: any mutation invalidates the
* cached prefix for the whole conversation — prefer the creation-time
* options; mutate only at task boundaries. */
async setSystemPrompt(text: string, append = false): Promise<void> {{
return this.runOp(async () => {{
for await (const ev of this.send({{ type: "set_system_prompt", text, append }})) {{
if (ev.type === "error") throw new Error(ev.message);
if (ev.type === "system_prompt") return;
}}
throw new Error("bridge stream ended before acking set_system_prompt");
}});
}}
appendSystemPrompt(text: string): Promise<void> {{ return this.setSystemPrompt(text, true); }}
/** Record an evaluation score in the server-side trajectory archive —
* same semantics as the stdio SDK's `score()`, including the optional
* `scale` ("unit" | "percent") override of the harness's
* value-normalization heuristic. */
async score(promptOrSha: string, value: number, notes = "", parent?: string, niche?: string, scale?: "unit" | "percent"): Promise<void> {{
const sha = HEX16.test(promptOrSha) ? promptOrSha : await promptFingerprint(promptOrSha);
const parent_sha = parent === undefined ? undefined
: HEX16.test(parent) ? parent : await promptFingerprint(parent);
// `niche` files the score into a MAP-Elites cell so the fleet can promote a
// champion for the role; the remote harness reads it from the request and
// tags its own score/submit. (Genome capture rides the harness process,
// which holds the persona text the remote bridge only references by sha.)
return this.runOp(async () => {{
for await (const ev of this.send({{ type: "score", prompt_sha: sha, score: value, notes, parent_sha, niche, scale }})) {{
if (ev.type === "error") throw new Error(ev.message);
if (ev.type === "score") return;
}}
throw new Error("bridge stream ended before acking score");
}});
}}
/** The harness schema version this client was generated from. */
version(): string {{ return HARNESS_VERSION; }}
/** Close the remote session (graceful: the bridge EOFs the child's stdin
* so it flushes telemetry/trajectory on the way out). Idempotent and
* never throws — safe even when session creation failed. */
async close(): Promise<void> {{
if (this.closed) return;
this.closed = true;
const id = await this.sessionId.catch(() => null);
if (id === null) return; // creation failed or no session: nothing to close
const res = await this.req("DELETE", `/v1/sessions/${{id}}`).catch(() => null);
if (res) await res.text().catch(() => {{}});
}}
/** Alias for close(). */
dispose(): Promise<void> {{ return this.close(); }}
}}
/** Create a remote session, run a single turn, stream its events, close. */
export async function* runAgentRemote(opts: RunAgentRemoteOptions): AsyncGenerator<Event> {{
const h = new RemoteHarness(opts);
try {{
yield* h.chat({{ prompt: opts.prompt, images: opts.images }});
}} finally {{
await h.close();
}}
}}
export const MODELS: ModelName[] = [{", ".join(f'"{m}"' for m in models)}];
export const TOOLS: ToolName[] = [{", ".join(f'"{t}"' for t in tools)}];
'''
def gen_py(schema):
models = sorted({m["name"] for m in schema["models"]})
tools = [t["name"] for t in schema["tools"]]
providers = [p["id"] for p in schema["providers"]]
header = '"""AUTO-GENERATED by sdk/generate.py from `harness --schema`. Do not edit."""\n'
return header + f'''from __future__ import annotations
import hashlib
import hmac
import json
import os
import re
import secrets
import subprocess
import threading
import time
import urllib.error
import urllib.request
from typing import Iterator, List, Literal, Optional, TypedDict, Union
MODELS = {json.dumps(models)}
TOOLS = {json.dumps(tools)}
PROVIDERS = {json.dumps(providers)}
class ImageUrlInput(TypedDict):
type: Literal["image_url"]
url: str
class ImageBase64Input(TypedDict):
type: Literal["image_base64"]
media_type: str
data: str
ImageInput = Union[ImageUrlInput, ImageBase64Input]
def _sdk_install_id() -> str:
"""Anonymous per-install id for SDK telemetry — its own id file, distinct
from the harness CLI's install id, so SDK users are counted separately.
Only ever leaves the machine when the harness has an OTLP endpoint
configured (OTEL_EXPORTER_OTLP_ENDPOINT); opt out entirely with
GRAFF_NO_TELEMETRY=1 or by passing --no-telemetry in `args`."""
path = os.path.join(os.path.expanduser("~"), ".simple-harness-sdk-id")
try:
with open(path) as f:
v = f.read().strip()
if len(v) == 32 and all(c in "0123456789abcdef" for c in v):
return v
except OSError:
pass
v = secrets.token_hex(16)
try:
with open(path, "w") as f:
f.write(v + "\\n")
except OSError:
pass
return v
def _default_binary() -> str:
"""The CLI is `graff` (renamed from `harness`); prefer it when on PATH,
fall back to the old name so pre-rename installs keep working."""
import shutil
return "graff" if shutil.which("graff") else "harness"
_TELEMETRY_DEFAULT = "https://harness-telemetry.rachpradhan.workers.dev"
def _report_error(kind: str, detail: str) -> None:
"""Best-effort OTLP ERROR log for failures the harness process cannot
report itself (it may be dead or never have started): spawn failures,
mid-turn exits, protocol breaks. Same pipeline and opt-out as harness
telemetry — skipped when GRAFF_NO_TELEMETRY is set; endpoint from
OTEL_EXPORTER_OTLP_ENDPOINT / GRAFF_OTEL_ENDPOINT, else the default
collector. Fire-and-forget on a daemon thread; never raises."""
if os.environ.get("GRAFF_NO_TELEMETRY"):
return
base = (os.environ.get("OTEL_EXPORTER_OTLP_ENDPOINT")
or os.environ.get("GRAFF_OTEL_ENDPOINT")
or _TELEMETRY_DEFAULT).rstrip("/")
url = base if base.endswith("/v1/logs") else base + "/v1/logs"
payload = json.dumps({{"resourceLogs": [{{
"resource": {{"attributes": [
{{"key": "service.name", "value": {{"stringValue": "simple-harness"}}}},
{{"key": "client.name", "value": {{"stringValue": os.environ.get("HARNESS_CLIENT", "sdk-py")}}}},
{{"key": "sdk.install.id", "value": {{"stringValue": _sdk_install_id()}}}},
]}},
"scopeLogs": [{{"scope": {{"name": "simple-harness-sdk"}}, "logRecords": [{{
"timeUnixNano": str(int(time.time() * 1e9)),
"severityText": "ERROR",
"body": {{"stringValue": "error"}},
"attributes": [
{{"key": "kind", "value": {{"stringValue": kind}}}},
{{"key": "detail", "value": {{"stringValue": detail[:512]}}}},
],
}}]}}],
}}]}}).encode()
def post():
try:
req = urllib.request.Request(
url, data=payload, headers={{
"Content-Type": "application/json",
# urllib's default Python-urllib/x.y UA is bot-blocked by
# Cloudflare in front of the collector (403) — identify.
"User-Agent": "simple-harness-sdk-py",
}})
urllib.request.urlopen(req, timeout=3).read()
except Exception:
pass
threading.Thread(target=post, daemon=True).start()
def _fleet_signal(kind: str, attrs: Optional[dict] = None) -> None:
"""Prompt-free SDK fleet signal; local is the fail-closed default."""
if os.environ.get("GRAFF_NO_TELEMETRY"):
return
privacy = os.environ.get("GRAFF_LEARNING_PRIVACY", "local")
if privacy not in ("aggregate", "templates", "examples"):
return
attrs = {{k: v for k, v in (attrs or {{}}).items() if k != "prompt_text"}}
base = (os.environ.get("OTEL_EXPORTER_OTLP_ENDPOINT")
or os.environ.get("GRAFF_OTEL_ENDPOINT")
or _TELEMETRY_DEFAULT).rstrip("/")
url = base if base.endswith("/v1/logs") else base + "/v1/logs"
al = [{{"key": "kind", "value": {{"stringValue": kind}}}}]
for k, v in attrs.items():
val = {{"doubleValue": v}} if isinstance(v, (int, float)) else {{"stringValue": str(v)}}
al.append({{"key": k, "value": val}})
payload = json.dumps({{"resourceLogs": [{{
"resource": {{"attributes": [
{{"key": "service.name", "value": {{"stringValue": "simple-harness"}}}},
{{"key": "client.name", "value": {{"stringValue": os.environ.get("HARNESS_CLIENT", "sdk-py")}}}},
{{"key": "sdk.install.id", "value": {{"stringValue": _sdk_install_id()}}}},
]}},
"scopeLogs": [{{"scope": {{"name": "simple-harness-sdk"}}, "logRecords": [{{
"timeUnixNano": str(int(time.time() * 1e9)),
"body": {{"stringValue": "fleet"}},
"attributes": al,
}}]}}],
}}]}}).encode()
def post():
try:
req = urllib.request.Request(
url, data=payload, headers={{
"Content-Type": "application/json",
"User-Agent": "simple-harness-sdk-py",
}})
urllib.request.urlopen(req, timeout=3).read()
except Exception:
pass
threading.Thread(target=post, daemon=True).start()
def prompt_fingerprint(text: str) -> str:
"""Fingerprint of a system prompt as used in `.graff/trajectories` —
the aggregate DGM-style archive — and by `Harness.score()`:
first 8 bytes of SHA-256, hex (16 chars)."""
return hashlib.sha256(text.encode()).hexdigest()[:16]
def score_signature(key: bytes, prompt_sha: str, parent_sha: str, score: float,
run_id: str, judge_id: str = "", artifact_sha: str = "",
eval_set_hash: str = "", niche: str = "",
provider_class: str = "") -> str:
"""Recompute a score record's HMAC the way the harness signs it (Step 0,
fitness-channel integrity). The canonical v2 message is version-tagged and
newline-joined with the score fixed to 6 decimals — byte-identical to the
Zig signer (src/scoring.zig scoreSigMessage). v2 folds `niche` and
`provider_class` into the signed envelope so a score for one MAP-Elites
cell cannot be replayed into another. `score` is on the canonical [0, 1]
scale. `key` is the raw bytes of the GRAFF_SCORE_KEY_FILE file."""
msg = "v2\\n{{}}\\n{{}}\\n{{:.6f}}\\n{{}}\\n{{}}\\n{{}}\\n{{}}\\n{{}}\\n{{}}".format(
prompt_sha, parent_sha, score, run_id, judge_id, artifact_sha,
eval_set_hash, niche, provider_class)
return hmac.new(key, msg.encode(), hashlib.sha256).hexdigest()
def verify_score(key: bytes, rec: dict) -> bool:
"""True iff a kind:"score" trajectory/D1 record carries a valid signature
for `key`. Use this in an evolution driver's archive loader to reject
forged fitness rows (an attacker without the key cannot produce a matching
sig). Verifies the v2 envelope first, then falls back to legacy v1 rows
(signed before niche/provider_class entered the envelope — transition
window only). Records with no sig fail closed when a key is set."""
sig = rec.get("sig") or ""
if not sig:
return False
# Run-scoped JSONL reserves top-level `run_id` for invocation identity.
# Score provenance therefore uses `score_run_id`; legacy/D1 records still
# carry the signed value as `run_id`.
signed_run_id = rec.get("score_run_id", rec.get("run_id", ""))
want = score_signature(
key, rec.get("prompt_sha", ""), rec.get("parent_sha", "") or "",
float(rec.get("score", "nan")), signed_run_id,
rec.get("judge_id", ""), rec.get("artifact_sha", ""),
rec.get("eval_set_hash", ""),
# D1 returns NULL (None) for an empty niche/provider_class — "{{}}"
# would format it as the literal "None" and poison the message.
rec.get("niche", "") or "",
rec.get("provider_class", "") or "")
if hmac.compare_digest(sig, want):
return True
legacy = "v1\\n{{}}\\n{{}}\\n{{:.6f}}\\n{{}}\\n{{}}\\n{{}}\\n{{}}".format(
rec.get("prompt_sha", ""), rec.get("parent_sha", "") or "",
float(rec.get("score", "nan")), signed_run_id,
rec.get("judge_id", ""), rec.get("artifact_sha", ""),
rec.get("eval_set_hash", ""))
return hmac.compare_digest(
sig, hmac.new(key, legacy.encode(), hashlib.sha256).hexdigest())
class Harness:
"""Drives a `harness --json` subprocess. One turn = send text, stream events.
Events are plain dicts with a "type" field: "text", "tool_call",
"ask_user", "tool_result", "turn", or "error" (see the harness
--schema protocol).
"""
def __init__(self, binary: Optional[str] = None, args: Optional[list] = None,
cwd: Optional[str] = None, env: Optional[dict] = None,
model: Optional[str] = None, yolo: bool = False,
system_prompt: Optional[str] = None,
append_system_prompt: Optional[str] = None,
max_tool_calls: Optional[int] = None,
dedupe_tool_calls: bool = False,
max_model_calls: Optional[int] = None,
compact_at: Optional[int] = None):
binary = binary or _default_binary()
argv = [binary, "--json"]
if yolo:
argv.append("--yolo")
if model:
argv += ["--model", model]
if max_tool_calls is not None:
argv += ["--max-tool-calls", str(max_tool_calls)]
if max_model_calls is not None:
argv += ["--max-model-calls", str(max_model_calls)]
if dedupe_tool_calls:
argv.append("--dedupe-tool-calls")
if compact_at is not None:
argv += ["--compact-at", str(compact_at)]
if system_prompt:
argv += ["--system-prompt", system_prompt]
if append_system_prompt:
argv += ["--append-system-prompt", append_system_prompt]
argv += list(args or [])
# Tag the harness child as SDK-driven for telemetry attribution
# (explicit caller values win). The id file is only read/created when
# telemetry is actually live — same gating as the harness CLI's own id.
run_env = dict(env if env is not None else os.environ)
run_env.setdefault("HARNESS_CLIENT", "sdk-py")
live = not run_env.get("GRAFF_NO_TELEMETRY") and (
run_env.get("OTEL_EXPORTER_OTLP_ENDPOINT") or run_env.get("GRAFF_OTEL_ENDPOINT"))
if live and "HARNESS_SDK_INSTALL_ID" not in run_env:
run_env["HARNESS_SDK_INSTALL_ID"] = _sdk_install_id()
try:
self.proc = subprocess.Popen(
argv, stdin=subprocess.PIPE, stdout=subprocess.PIPE,
text=True, bufsize=1, cwd=cwd, env=run_env,
)
except OSError as e:
_report_error("spawn", f"{{binary}}: {{e}}")
raise
def chat(self, text: str, review: bool = False,
images: Optional[List[ImageInput]] = None) -> Iterator[dict]:
"""Send a user turn; yield events until (and including) the 'turn'
event. Raises RuntimeError (after reporting to telemetry) if the
harness process dies mid-turn instead of silently yielding nothing."""
assert self.proc.stdin and self.proc.stdout
try:
payload = {{"type": "review" if review else "user", "text": text}}
if images:
payload["images"] = images
self.proc.stdin.write(json.dumps(payload) + "\\n")
self.proc.stdin.flush()
except OSError as e:
_report_error("died", f"harness pipe closed on send: {{e}}")
raise
for line in self.proc.stdout:
line = line.strip()
if not line:
continue
try:
ev = json.loads(line)
except json.JSONDecodeError:
continue
yield ev
if ev.get("type") in ("turn", "error"):
return
# stdout EOF without a terminal event: the harness died mid-turn.
rc = self.proc.poll()
_report_error("died", f"harness exited mid-turn (rc={{rc}})")
raise RuntimeError(f"harness exited mid-turn (rc={{rc}})")
def ask(self, text: str, images: Optional[List[ImageInput]] = None) -> str:
"""Run a turn and return just the final assistant text."""
final = ""
for ev in self.chat(text, images=images):
if ev.get("type") == "turn":
final = ev["text"]
elif ev.get("type") == "error":
raise RuntimeError(ev["message"])
return final
def review(self, text: str, images: Optional[List[ImageInput]] = None) -> str:
"""Run one isolated, read-only review turn and return its report."""
final = ""
for ev in self.chat(text, review=True, images=images):
if ev.get("type") == "turn":
final = ev["text"]
elif ev.get("type") == "error":
raise RuntimeError(ev["message"])
return final
def answer(self, text: str = "", cancelled: bool = False,
call_id: Optional[str] = None) -> None:
"""Answer an in-flight ask_user event while chat() is being consumed."""
assert self.proc.stdin
req = {{"type": "answer", "text": text, "cancelled": cancelled}}
if call_id:
req["call_id"] = call_id
self.proc.stdin.write(json.dumps(req) + "\\n")
self.proc.stdin.flush()
def set_system_prompt(self, text: str, append: bool = False) -> None:
"""Replace (or with append=True, extend) the system prompt for later
turns. Call between turns; blocks until the harness acks.
KV-cache warning (Manus context-engineering lessons): the system
prompt heads the cached prefix, so ANY mutation — append included —
invalidates the cache for the whole conversation; the next turn
re-reads everything at full input price. Prefer the spawn-time
system_prompt/append_system_prompt arguments; mutate only at task
boundaries, never back-and-forth inside a loop."""
assert self.proc.stdin and self.proc.stdout
self.proc.stdin.write(json.dumps(
{{"type": "set_system_prompt", "text": text, "append": append}}) + "\\n")
self.proc.stdin.flush()
for line in self.proc.stdout:
line = line.strip()
if not line:
continue
try:
ev = json.loads(line)
except json.JSONDecodeError:
continue
if ev.get("type") == "error":
raise RuntimeError(ev["message"])
if ev.get("type") == "system_prompt":
return
_report_error("died", f"harness closed before acking set_system_prompt (rc={{self.proc.poll()}})")
raise RuntimeError("harness closed before acking set_system_prompt")
def append_system_prompt(self, text: str) -> None:
"""Tack extra instructions onto the current system prompt."""
self.set_system_prompt(text, append=True)
def score(self, prompt_or_sha: str, value: float, notes: str = "",
parent: Optional[str] = None, judge_id: str = "",
artifact_sha: str = "", eval_set_hash: str = "",
niche: str = "", scale: str = "") -> None:
"""Record an evaluation score for an agent/prompt variant in the
aggregate trajectory archive (`.graff/trajectories`) — the DGM evaluation
phase writing back. `prompt_or_sha` is either the full system-prompt
text (fingerprinted for you) or an existing 16-hex fingerprint.
Pass `parent` (text or sha) when the variant was mutated from
another prompt: that genome-lineage edge is what DGM parent
selection counts children with.
Provenance (signed when GRAFF_SCORE_KEY_FILE is set): `judge_id`
names the evaluator, `artifact_sha` the thing it judged, and
`eval_set_hash` the held-out eval used — all folded into the record's
HMAC so a forged fitness row is detectable (see `verify_score`).
`niche` (reviewer/researcher/implementer/skeptic, or a custom agent)
files the score into that MAP-Elites cell so the fleet can promote a
champion for the role; full text produces only a prompt-free fingerprint
proposal until the SDK has an interactive review UI.
Scale: the canonical wire scale is [0, 1]. Pass scale="unit" to
assert `value` is already in [0, 1] (anything else is rejected), or
scale="percent" to always send value/100 (accepts [0, 100] — note a
percent-scale 0.5 means 0.005, not 0.5). Without `scale` the harness
heuristic applies: [0, 1] passes as-is, values in (1, 100] are
treated as percentages and normalized to /100, and values outside
[0, 100] are rejected. Call between turns; blocks until the harness
acks."""
assert self.proc.stdin and self.proc.stdout
sha = prompt_or_sha if re.fullmatch(r"[0-9a-f]{{16}}", prompt_or_sha) \\
else prompt_fingerprint(prompt_or_sha)
req = {{"type": "score", "prompt_sha": sha, "score": value, "notes": notes}}
if parent is not None:
req["parent_sha"] = parent if re.fullmatch(r"[0-9a-f]{{16}}", parent) \\
else prompt_fingerprint(parent)
if judge_id:
req["judge_id"] = judge_id
if artifact_sha:
req["artifact_sha"] = artifact_sha
if eval_set_hash:
req["eval_set_hash"] = eval_set_hash
if niche:
req["niche"] = niche
if scale:
req["scale"] = scale
# The SDK emitter strips prompt_text until it has an interactive review UI.
if niche and not re.fullmatch(r"[0-9a-f]{{16}}", prompt_or_sha):
_fleet_signal("propose", {{"niche": niche, "prompt_sha": sha,
"parent_sha": req.get("parent_sha", ""),
"prompt_text": prompt_or_sha}})
self.proc.stdin.write(json.dumps(req) + "\\n")
self.proc.stdin.flush()
for line in self.proc.stdout:
line = line.strip()
if not line:
continue
try:
ev = json.loads(line)
except json.JSONDecodeError:
continue
if ev.get("type") == "error":
raise RuntimeError(ev["message"])
if ev.get("type") == "score":
_fleet_signal("submit", {{"prompt_sha": sha, "eval_set_hash": eval_set_hash, "niche": niche}})
return
_report_error("died", f"harness closed before acking score (rc={{self.proc.poll()}})")
raise RuntimeError("harness closed before acking score")
def pull_elites(self, provider_class: str, eval_set_hash: str = "") -> list:
"""Pull fleet champions; local mode returns without network access."""
if os.environ.get("GRAFF_LEARNING_PRIVACY", "local") not in ("aggregate", "templates", "examples"):
return []
base = (os.environ.get("OTEL_EXPORTER_OTLP_ENDPOINT")
or os.environ.get("GRAFF_OTEL_ENDPOINT")
or _TELEMETRY_DEFAULT).rstrip("/")
if base.endswith("/v1/logs"):
base = base[: -len("/v1/logs")]
q = "provider_class=" + provider_class
if eval_set_hash:
q += "&eval_set_hash=" + eval_set_hash
elites: list = []
try:
req = urllib.request.Request(
base + "/v1/elites?" + q,
headers={{"User-Agent": "simple-harness-sdk-py"}})
body = urllib.request.urlopen(req, timeout=5).read()
elites = (json.loads(body) or {{}}).get("elites", []) or []
except Exception:
pass
_fleet_signal("elite_pull", {{"provider_class": provider_class,
"eval_set_hash": eval_set_hash,
"n_elites": len(elites)}})
return elites
def close(self):
"""Close stdin and give the harness a moment to exit cleanly — it
flushes telemetry and trajectory records on the way out; killing it
immediately would race (and lose) that flush."""
if self.proc.stdin:
self.proc.stdin.close()
try:
self.proc.wait(timeout=15)
except subprocess.TimeoutExpired:
self.proc.terminate()
def __enter__(self):
return self
def __exit__(self, *exc):
self.close()
class RemoteHarness:
"""Drives a session on a remote `harness serve` bridge over HTTP — the
network-transport analogue of `Harness`, same method surface. The server
side runs `harness serve` (see the "serve" key of `harness --schema`);
each session is a real `harness --json` child over there, and one POST =
one protocol request, streamed back as NDJSON until its terminal event.
Stdlib-only (urllib): usable anywhere Python runs, no local binary
needed. Pass yolo=True in most cases — the bridge has no terminal to
show permission prompts on.
#330: sessions are durable. Pass `session="<name>"` and the bridge runs
`graff --json --resume <name>`, so a REPLACEMENT bridge given the same
name continues the run. Every event carries a monotonic `seq`; after a
dropped stream, `reconnect()` replays exactly what was missed."""
def __init__(self, url: str, token: Optional[str] = None,
model: Optional[str] = None, yolo: bool = False,
system_prompt: Optional[str] = None,
append_system_prompt: Optional[str] = None,
max_tool_calls: Optional[int] = None,
dedupe_tool_calls: bool = False,
session_id: Optional[str] = None,
max_model_calls: Optional[int] = None,
session: Optional[str] = None):
self.base = url.rstrip("/")
self.token = token
# #330: highest event seq seen. reconnect() picks up from last_seq + 1.
self.last_seq = 0
self.info = None
if session_id is not None:
self.session_id = session_id
return
opts = {{}}
# A durable session name: the bridge runs the child as
# `graff --json --resume <session>`, so a REPLACEMENT bridge given the
# same name continues the run from its last persisted turn.
if session:
opts["session"] = session
if model:
opts["model"] = model
if yolo:
opts["yolo"] = True
if system_prompt:
opts["system_prompt"] = system_prompt
if append_system_prompt:
opts["append_system_prompt"] = append_system_prompt
if max_tool_calls is not None:
opts["maxToolCalls"] = max_tool_calls
if max_model_calls is not None:
opts["maxModelCalls"] = max_model_calls
if dedupe_tool_calls:
opts["dedupeToolCalls"] = True
resp = self._request("POST", "/v1/sessions", opts)
self.info = json.loads(resp.read())
self.session_id = self.info["session_id"]
self.last_seq = int(self.info.get("last_seq") or 0)
def _request(self, method: str, path: str, body=None):
headers = {{"Content-Type": "application/json",
"User-Agent": "simple-harness-sdk-py"}}
if self.token:
headers["Authorization"] = "Bearer " + self.token
data = None if body is None else json.dumps(body).encode()
req = urllib.request.Request(self.base + path, data=data,
headers=headers, method=method)
try:
return urllib.request.urlopen(req)
except urllib.error.HTTPError as e:
detail = e.read().decode(errors="replace")[:256]
raise RuntimeError(f"bridge {{method}} {{path}} → {{e.code}}: {{detail}}") from None
def _stream(self, resp) -> Iterator[dict]:
for line in resp:
line = line.strip()
if not line:
continue
try:
ev = json.loads(line)
except json.JSONDecodeError:
continue
seq = ev.get("seq")
if isinstance(seq, int) and seq > self.last_seq:
self.last_seq = seq
yield ev
def _send(self, payload: dict, from_seq: Optional[int] = None) -> Iterator[dict]:
"""POST one protocol request; yield its streamed NDJSON events.
from_seq replays persisted events with seq >= from_seq first."""
query = "" if from_seq is None else f"?from={{from_seq}}"
resp = self._request("POST", f"/v1/sessions/{{self.session_id}}{{query}}", payload)
return self._stream(resp)
def reconnect(self, from_seq: Optional[int] = None) -> Iterator[dict]:
"""Re-attach after losing the stream: replay persisted events with
seq >= from_seq (default: everything after what this client saw), then
follow live until the in-flight request's terminal event. Sends nothing
to the model, so it is safe while a turn is running — including from a
different process than the one that started it."""
start = self.last_seq + 1 if from_seq is None else from_seq
resp = self._request("GET", f"/v1/sessions/{{self.session_id}}/events?from={{start}}")
return self._stream(resp)
def chat(self, text: str, review: bool = False,
from_seq: Optional[int] = None,
images: Optional[List[ImageInput]] = None) -> Iterator[dict]:
"""Send a user turn; yield events until (and including) the 'turn'
event. Raises RuntimeError if the stream ends without one (the
session process died server-side)."""
terminal = False
payload = {{"type": "review" if review else "user", "text": text}}
if images:
payload["images"] = images
for ev in self._send(payload, from_seq):
yield ev
if ev.get("type") in ("turn", "error"):
terminal = True
return
if not terminal:
raise RuntimeError("bridge stream ended mid-turn (session process died?)")
def ask(self, text: str, images: Optional[List[ImageInput]] = None) -> str:
"""Run a turn and return just the final assistant text."""
final = ""
for ev in self.chat(text, images=images):
if ev.get("type") == "turn":
final = ev["text"]
elif ev.get("type") == "error":
raise RuntimeError(ev["message"])
return final
def review(self, text: str, images: Optional[List[ImageInput]] = None) -> str:
"""Run one isolated, read-only review turn and return its report."""
final = ""
for ev in self.chat(text, review=True, images=images):
if ev.get("type") == "turn":
final = ev["text"]
elif ev.get("type") == "error":
raise RuntimeError(ev["message"])
return final
def answer(self, text: str = "", cancelled: bool = False,
call_id: Optional[str] = None) -> None:
"""Answer an in-flight ask_user event. The original chat stream
continues and later yields the ask_user tool_result plus final turn."""
req = {{"type": "answer", "text": text, "cancelled": cancelled}}
if call_id:
req["call_id"] = call_id
self._request("POST", f"/v1/sessions/{{self.session_id}}", req).read()
def set_system_prompt(self, text: str, append: bool = False) -> None:
"""Replace (or with append=True, extend) the system prompt for later
turns. Same KV-cache warning as `Harness.set_system_prompt`: prefer
the creation-time arguments; mutate only at task boundaries."""
for ev in self._send({{"type": "set_system_prompt", "text": text, "append": append}}):
if ev.get("type") == "error":
raise RuntimeError(ev["message"])
if ev.get("type") == "system_prompt":
return
raise RuntimeError("bridge stream ended before acking set_system_prompt")
def append_system_prompt(self, text: str) -> None:
"""Tack extra instructions onto the current system prompt."""
self.set_system_prompt(text, append=True)
def score(self, prompt_or_sha: str, value: float, notes: str = "",
parent: Optional[str] = None, judge_id: str = "",
artifact_sha: str = "", eval_set_hash: str = "",
niche: str = "", scale: str = "") -> None:
"""Record an evaluation score in the server-side trajectory archive —
same semantics (and provenance fields) as `Harness.score`, including
prompt-free MAP-Elites lineage and the optional `scale`
("unit" | "percent") override of the harness's value-normalization
heuristic."""
sha = prompt_or_sha if re.fullmatch(r"[0-9a-f]{{16}}", prompt_or_sha) \\
else prompt_fingerprint(prompt_or_sha)
req = {{"type": "score", "prompt_sha": sha, "score": value, "notes": notes}}
if parent is not None:
req["parent_sha"] = parent if re.fullmatch(r"[0-9a-f]{{16}}", parent) \\
else prompt_fingerprint(parent)
if judge_id:
req["judge_id"] = judge_id
if artifact_sha:
req["artifact_sha"] = artifact_sha
if eval_set_hash:
req["eval_set_hash"] = eval_set_hash
if niche:
req["niche"] = niche
if scale:
req["scale"] = scale
# The SDK emitter strips prompt_text until it has an interactive review UI.
if niche and not re.fullmatch(r"[0-9a-f]{{16}}", prompt_or_sha):
_fleet_signal("propose", {{"niche": niche, "prompt_sha": sha,
"parent_sha": req.get("parent_sha", ""),
"prompt_text": prompt_or_sha}})
for ev in self._send(req):
if ev.get("type") == "error":
raise RuntimeError(ev["message"])
if ev.get("type") == "score":
return
raise RuntimeError("bridge stream ended before acking score")
def close(self):
"""Close the remote session (graceful: the bridge EOFs the child's
stdin so it flushes telemetry/trajectory on the way out)."""
try:
self._request("DELETE", f"/v1/sessions/{{self.session_id}}").read()
except (RuntimeError, OSError):
pass
def __enter__(self):
return self
def __exit__(self, *exc):
self.close()
'''
def main():
schema = load_schema(sys.argv[1:])
print(f"generating SDKs from schema: {schema.get('harness')} v{schema.get('version')} "
f"({len(schema['models'])} models, {len(schema['tools'])} tools)")
write(os.path.join(HERE, "ts", "harness.ts"), gen_ts(schema))
write(os.path.join(HERE, "ts", "remote.ts"), gen_ts_remote(schema))
write(os.path.join(HERE, "py", "harness_sdk.py"), gen_py(schema))
write(os.path.join(HERE, "..", "examples", "edge-worker", "src", "remote.ts"), gen_ts_remote(schema))
print("done.")
if __name__ == "__main__":
main()