Helix — Grounded Execution Recovery

Gemini turns scattered delivery evidence into a grounded diagnosis and a safe, auditable recovery action.

Comment

Inspiration

Engineering work now moves between people, coding agents, issue trackers, pull requests, reviews, and release systems. A task can look complete in one surface while still lacking ownership, review, release proof, or a link to the customer need that started it. Teams waste time reconstructing what happened, while model-written status summaries can sound certain without proving anything.

What it does

Helix gives every issue a seven-stage Execution Record: origin, plan, responsibility, execution, evidence, decision, and release.

When work stalls, Recover execution asks Gemini 3.5 Flash-Lite to call one server-owned, read-only tool. That tool returns a tenant-scoped, minimized snapshot and an allowlist of valid delivery gaps. Gemini selects up to three gap IDs; Helix validates those IDs deterministically, stores a durable Agent Run Receipt, and prepares a recovery follow-up. A person approves the consequential write, and Helix applies it idempotently.

The result is one evidence-backed answer to three questions: what is blocked, what proves it, and what should happen next.

How we built it

  • React 19 web UI and Hono/Node API
  • PostgreSQL with Drizzle for product data and durable receipts
  • Google GenAI SDK (@google/genai)
  • Gemini 3.5 Flash-Lite function calling plus structured output
  • Cloud Run container packaging and Cloud SQL integration
  • Better Auth with optional Google OAuth and workspace-bound sessions
  • Vitest and Playwright coverage

The model is deliberately constrained. It can call only helix_get_execution_record, which performs authorized issue reads and returns server-derived gap IDs. A deterministic boundary rejects unknown, duplicate, empty, or over-limit selections before anything is persisted. The model never chooses a tenant, queries arbitrary data, invents proof, or performs the final write.

Challenges we ran into

Our first paid Gemini proof call exposed a real API-contract failure: forced function calling and JSON response MIME type cannot be combined in the same model turn. We reproduced it with a regression test, separated the required tool-call turn from the structured-response turn, disabled tools for the follow-up, and reran the real Gemini path successfully.

We also kept release evidence honest: local build, paid model proof, cloud deployment, public repository, and Devpost status are tracked as separate states rather than collapsed into “done.”

Accomplishments that we're proud of

  • A real Gemini tool call grounded in a tenant-scoped Execution Record
  • Durable success and failure receipts that survive refresh
  • Human approval separated from model judgment
  • Idempotent recovery application
  • Visible fail-closed behavior instead of mock fallback
  • A sanitized public repository with reproducible setup, Apache-2.0 licensing, tests, and an architecture artifact

What we learned

Agentic reliability is less about giving a model more power and more about designing the evidence and authorization boundaries around it. Gemini is strongest here as a constrained diagnostic reasoner: the application owns identity, retrieval, validation, persistence, and writes.

What's next for Helix

The current boundary is an issue-scoped, single-workspace demo. Next steps are background recovery triggers, richer cross-system evidence connectors, and production-grade multi-tenant authorization—without weakening the receipt and human-approval model.

Known limitations

  • Recovery is user-triggered rather than scheduled in the background.
  • Gemini diagnoses and drafts recovery, but a human approves the consequential write.
  • Google OAuth support is implemented but a live OAuth round trip is not part of this submission claim.
  • Broader Helix surfaces remain preview-grade; this entry claims the Execution Record and grounded recovery loop.

Built With

Share this project:

Updates

Submission history