v0.2.14

codegraff v0.2.14

Released 2026-06-01

This release is about SDKs growing up. codegraff now ships a mouldable, Next.js-ready TypeScript SDK (@codegraff/sdk) and a new Python SDK (codegraff), both guarded by dhi-backed input validation so bad options fail fast with clear errors instead of surprising you at runtime. Alongside the SDKs, 0.2.14 introduces client trajectory upload with opt-in OTLP GenAI telemetry and RLVR reward labels, makes MCP / tool-grammar calls visible across the stream, hooks, and trajectory, hardens the orchestrator against the pending-todos doom loop, tightens compaction behavior for MCP-heavy and image-heavy contexts, and reworks the usage tracker to be privacy-respecting by default. It also folds in three upstream fixes from tailcallhq/forgecode.

Highlights

• New first-class TypeScript SDK (@codegraff/sdk) with a one-call BYOK entry point, a mouldable system prompt, a cloud Sandbox class, and Next.js-ready packaging.
• New first-class Python SDK (codegraff) sharing the same validation contract as the TypeScript SDK.
• dhi-backed input validation in both SDKs validates Graff.init and chat options before any request leaves the client.
• Client trajectory upload plus opt-in OTLP GenAI telemetry, with RLVR sparse-ORM reward labels attached to uploaded trajectories.
• MCP / tool-grammar calls are now surfaced consistently across the stream, hooks, and trajectory.
• Orchestrator reliability fixes that break the pending-todos doom loop.
• Compaction now scales to 90% of the context window (codex parity) and accounts for JSON/image tool results.
• The usage tracker no longer harvests user email, and the opt-out env var is renamed to a real opt-out: GRAFF_TRACK.
• SDK versions are now 1:1 with the CLI, bumping @codegraff/sdk from 0.2.0 to 0.2.3 with native codedb on install.

TypeScript SDK (@codegraff/sdk)

• Ships as a proper N-API package built and published through cross-platform CI, with native codedb installed on npm install.
• One-call BYOK initialization:

  Graff.init({ provider, apiKey, model, maxTokens })

  bring-your-own-key auth with thin JS wrappers over the native core.
• Mouldable system prompt so integrators can shape the agent's base instructions to fit their product.
• New Sandbox class for managing cloud sandboxes from the SDK.
• Next.js-ready packaging, with a companion Next.js example app demonstrating end-to-end usage.
• dhi-backed validation of Graff.init/chat options (see "Validation & verification").
• Versioned 1:1 with the CLI: @codegraff/sdk moves from 0.2.0 to 0.2.3.

Python SDK (codegraff)

• New Python SDK sharing the same option contract and BYOK model as the TypeScript SDK.
• dhi-backed input validation for Graff.init/chat options, pinned to dhi >= 1.3.3 (native cp314 / cp314t wheels).
• New turboAPI example: a dhi-validated, SSE-streaming server showing how to put the Python SDK behind an HTTP API.

Telemetry & RLVR

• Client trajectory upload: completed agent trajectories can be uploaded from the client.
• Opt-in OTLP GenAI telemetry: standards-aligned OpenTelemetry GenAI signals, off unless you explicitly enable them.
• RLVR sparse-ORM reward labels on uploaded trajectories, derived from the run outcome:
  • accepted → reward 1.0
  • error → reward 0.0
  • incomplete → reward null (masked, so partial/unfinished runs don't pollute the reward signal)
• This makes uploaded trajectories directly usable for Reinforcement Learning from Verifiable Rewards workflows, where only verifiably-terminal outcomes carry a dense reward and everything else is masked.
• Test coverage for all three outcome paths (accepted / incomplete / error).

MCP & tool calls

• MCP / tool-grammar calls are now surfaced across the stream, hooks, and trajectory, so tool activity that previously stayed hidden is now observable end-to-end.
• Unwrap double-encoded tool args: arguments that arrived JSON-encoded-inside-JSON are now correctly decoded before dispatch.
• MCP tools are sent non-strict, improving compatibility with MCP servers whose schemas don't satisfy strict tool-call constraints.

Orchestrator & reliability

• Break the pending-todos doom loop: the orchestrator no longer gets stuck re-running because of lingering pending todos.
  • Bounded End-hook rearms cap how many times the End hook can re-arm itself.
  • A doom-loop detector strips volatile keys before comparing state, so cosmetic churn no longer looks like genuine new work.

Compaction

• Threshold scaled to 90% of the context window for parity with codex behavior.
• JSON and image tool results are now counted toward context size, so MCP-heavy contexts actually compact instead of silently overflowing.
• Cost-only ping frames no longer shadow real token usage, fixing cases where bookkeeping frames masked the true token count used to drive compaction.

Privacy

• The usage tracker no longer harvests user email.
• The opt-out environment variable is renamed from FORGE_TRACKER to GRAFF_TRACK, and is now a real opt-out that genuinely disables tracking.

Upstream sync (tailcallhq/forgecode)

Pulled in three fixes from upstream tailcallhq/forgecode:

• #3418 — apply the Opus 4.7 API contract to Claude Opus 4.8, keeping the newer model on a known-good request/response contract.
• #3414 — add provider.json + vertex.json model entries for newly supported models.
• #3350 — replay reasoning_content for Xiaomi MiMo tool calls, so reasoning is preserved correctly across tool-call turns for that model.

Validation & verification

• Both SDKs validate inputs with dhi, a Zod-4- / Pydantic-compatible, SIMD-WASM validator. Options passed to Graff.init and chat are checked against a shared schema contract in both the TypeScript and Python SDKs, so invalid configuration is rejected at the boundary rather than deep inside a request.
• dhi is pinned to >= 1.3.3, which provides native cp314 / cp314t wheels for the Python side.
• Added regression tests covering RLVR outcome labeling for the accepted, incomplete, and error paths.

Packaging & versioning

• @codegraff/sdk bumped 0.2.0 -> 0.2.3, now versioned 1:1 with the CLI.
• Native codedb is installed on package install, so the SDK is usable without a separate build step.
• New example apps land alongside the SDKs: a Next.js example (TypeScript) and a turboAPI example (Python).

---

Install

curl -fsSL https://github.com/justrach/codegraff/releases/latest/download/install.sh | sh

Once v0.2.14 is published it becomes latest; until then pin the tag: .../releases/download/v0.2.14/install.sh.

Prebuilt binaries are attached for every supported platform:

Platform	Arch	Assets
Linux (gnu)	x86_64, aarch64	graff-*-unknown-linux-gnu, codegraff-*-unknown-linux-gnu
Linux (musl)	x86_64, aarch64	graff-*-unknown-linux-musl, codegraff-*-unknown-linux-musl
Windows	x86_64, aarch64	graff-*-pc-windows-msvc.exe, codegraff-*-pc-windows-msvc.exe
Android	aarch64	graff-aarch64-linux-android
macOS	x86_64, aarch64	graff-*-apple-darwin, codegraff-*-apple-darwin (+ .zip)

macOS binaries — signed & notarized

The macOS graff and codegraff binaries (both x86_64-apple-darwin and aarch64-apple-darwin) are:

• Signed with Developer ID Application: Rachit Pradhan (WWP9DLJ27P)
• Built with hardened runtime + secure timestamp
• Notarized by Apple — submission 34a24b8c-e5f4-454a-905d-20cace04840a, status Accepted

They launch without Gatekeeper warnings. As bare CLI tools they can't be stapled, so first launch performs a one-time online notarization check (needs network).