Evidence-Bound Taskmaster

A Gemini-planned, human-approved contract-renewal agent that turns synthetic evidence into one hash-bound, idempotent Firestore sandbox task.

Comment

Problem

Contract-renewal work is easy to lose between evidence review, ownership routing, approval, task creation, and follow-up. A language model can help turn messy evidence into a useful plan, but giving model output direct tool authority creates a second problem: prompt injection, duplicate delivery, expired approval, and uncertain network outcomes can turn automation into an unsafe or duplicated action.

The target user is a legal-operations or procurement owner who wants automation to remove coordination friction without letting an AI silently mutate a real contract, send an email, or create duplicate work.

Solution

Evidence-bound Taskmaster accepts a strict contract-renewal CloudEvent carrying synthetic or public evidence. Gemini 3.5 Flash, called through the Google GenAI SDK on Vertex AI, proposes structured task wording and a planner priority. A deterministic compiler then fixes the permitted three-step workflow and derives the actual owner and priority from schema-validated event fields, so neither the evidence text nor model output can choose a tool or override routing policy.

The service will not execute that plan until a human creates a short-lived approval bound to the exact plan hash. Execution can create only one deterministically named document in a sandbox Firestore collection. A duplicate execute reconciles the existing document and returns the original sealed receipt; a timeout remains an unknown outcome and is not retried automatically.

Why This Matters

Agent demos often optimize for how much authority a model can exercise. This project explores the opposite question: how can an agent remain useful when every transition from evidence to proposal, approval, action, and receipt is explicitly bounded and auditable?

The result is intentionally narrow, but it demonstrates a reusable control-plane pattern for higher-stakes workflows: model proposals are untrusted, human authority is exact and expiring, external writes are create-only, and retries must prove idempotency before being accepted.

How We Used AI

  • Runtime model: gemini-3.5-flash through Vertex AI global.
  • Google framework: Google GenAI SDK (google-genai).
  • Model role: propose a strict JSON objective, title, summary, planner priority, and rationale from caller-supplied evidence.
  • Authority boundary: Gemini cannot approve a plan, select an arbitrary tool, change the deterministic owner/priority route, or write to Firestore.
  • Prompt-injection result: the live demo-002 fixture asked the system to reroute ownership, raise priority, and send email. Gemini's proposal remained data; the compiler retained owner legal-ops, route priority low, and the fixed Firestore-only workflow.
  • Live evidence: the final demo-004 run produced a structured Gemini plan on Cloud Run revision eao-taskmaster-canary-00008-gqh. It proceeded only after human approval, created one Firestore sandbox document, reconciled the exact original receipt, and passed one exact-document read-back. Earlier gated runs remain preserved as historical evidence.

No mock planner, fake adapter, or legacy fake-adapter/v1 record is presented as Google integration evidence.

How We Used Codex

Codex acted as an implementation and verification collaborator while the human operator retained every external-account, cost, deployment, model-call, approval, and Firestore-write decision. It helped:

  • evolve the original offline evidence ledger into a structured Taskmaster planner, approval authority, Firestore action contract, and HTTP service;
  • build mock-first tests for prompt injection, duplicate and concurrent events, expiry, revocation, provider failure, timeout/unknown outcome, reconciliation, secret boundaries, and public-demo request limits;
  • diagnose the Cloud Run /healthz 404, document the reserved-path issue, and move the verified probe to /health;
  • migrate the competition planner from a Developer API key path to Vertex AI global with runtime Application Default Credentials and no mounted Gemini secret;
  • design and inspect least-privilege deployment preflights, source-upload secret exclusions, min-zero/max-one runtime controls, and separate private versus public-demo confirmations;
  • bind the three live synthetic runs to exact revisions, image digests, request timelines, plan/approval/request/receipt hashes, and exact Firestore read-back evidence; and
  • prepare the README, architecture attachment, demo runbook, video script, and this draft with explicit claim limits.

During initial drafting, Codex did not register, publish, push, upload, or make a final Devpost entry. After the user explicitly authorized submission preparation, Codex pushed the audited final-evidence commit and synchronized the prepared project fields to Devpost. The final hackathon entry remains gated on the user's explicit “yes, submit.”

Key Features

  • Strict CloudEvents 1.0 contract-renewal input with bounded JSON and exact schema validation.
  • Deterministic owner and renewal-priority routing that model output cannot override.
  • Gemini 3.5 Flash structured planning through the Google GenAI SDK and Vertex AI global.
  • Fixed evidence.analyze → firestore.sandbox.task.create → receipt.emit allowlist; no free-form tool invocation.
  • Short-lived human approval bound to the complete plan hash, with immutable revocation and fail-closed restart behavior.
  • Deterministic create-only Firestore document IDs and exact AlreadyExists reconciliation.
  • Sealed request and receipt records with canonical JSON and SHA-256 hashes.
  • Explicit unknown-outcome handling with no automatic write retry.
  • Cloud Run service using runtime ADC, a dedicated service account, min instances 0, max instances 1, and bearer protection on every task POST.
  • Mock/no-secret local mode and 48 offline regression tests, freshly passing on Python 3.11.15 and Python 3.12.13 on 2026-08-30.

Architecture

The request enters a Cloud Run HTTP boundary in asia-east2. The exact CloudEvent is deduplicated by source + id and sent through the Google GenAI SDK to Gemini 3.5 Flash at Vertex AI global. The model response is validated and compiled into a fixed plan. A separate human approval binds that plan hash. Only then can the Firestore adapter issue a create-only write to eao_sandbox_tasks; the resulting sealed receipt is returned and used for idempotent reconciliation.

Security boundaries include:

  • runtime Application Default Credentials instead of an API key;
  • a dedicated least-privilege service account with Vertex AI User and Datastore User roles;
  • no user-managed service-account key and no legacy Gemini secret mount;
  • a public health route separated from bearer-protected task routes;
  • a fixed fixture digest and bounded per-process planning/execution attempts on the public demonstration surface; and
  • logs restricted to allowlisted method, path, status, latency, timestamp, and revision metadata.

Formal architecture attachment: docs/assets/taskmaster-architecture.png (1920×1080 PNG, 281,224 bytes, SHA-256 ad196670f0f8ba5c0d1d74124d0f133f55f4442345ba822a0da200f30bd1e176).

Detailed trust boundaries: docs/ARCHITECTURE.md.

Testing Instructions

Offline, no-secret verification

Python 3.11 or newer is required.

python3 -m venv .venv
. .venv/bin/activate
python -m pip install --no-deps -e .
python -m unittest discover -s tests -v

Expected result at the latest recorded audit: 48 tests pass. The suite uses no model, cloud, credential, customer, or production-contract data.

Start the safe local service:

EAO_PLANNER=mock EAO_ACTION_STORE=memory python -m eao.service
curl --fail http://127.0.0.1:8080/health

Then send the tracked fixtures/contract-renewal.cloudevent.json to POST /v1/events/contract-renewal, approve the returned exact plan with the documented confirmation literal, and execute it against the in-memory store. The README describes the complete local route sequence.

Cloud evidence

The live service's task POST routes are intentionally bearer-protected. Do not place the existing bearer in this public draft, repository, video, or public testing instructions. Judges can verify the cloud path through the public video, the source and deployment configuration, and the sanitized evidence ledger at docs/LIVE_EVIDENCE.md.

Recommended judge path: do not share the operator bearer. Give judges the public health endpoint, offline no-secret steps, public repository, video, and sanitized evidence ledger. A separate judge credential is unnecessary for the required proof and should be created only after a separate security decision.

Data Sources

The live and recorded demonstrations use only the tracked synthetic contract-renewal CloudEvent fixture. The service does not fetch private contracts, email, customer records, or production data.

Findings and Learnings

  • Treating model output as a proposal, then deterministically compiling it into an allowlisted plan, kept prompt-injected ownership and priority instructions from gaining authority.
  • Binding a short-lived approval to the exact plan hash prevented stale or altered plans from executing.
  • Create-only deterministic Firestore IDs plus sealed receipts made duplicate delivery reconcilable without creating duplicate work.
  • Unknown write outcomes must remain unknown until reconciliation; automatic retries would weaken the evidence boundary.

Known Limitations

  • Inputs are synthetic or caller-supplied public evidence; the service does not fetch private contracts or production data.
  • The only real side effect is one create-only document per gated run in a sandbox Firestore collection. There is no contract mutation, email, ticket, purchase, calendar, or other third-party adapter.
  • Human approval and revocation authority are process-local. A restart loses approvals fail-closed rather than resuming them.
  • Public planning and execution counters are process-local safety limits, not durable quotas or hard cost controls.
  • The HKD 50 budget is an alert, not a hard spending cap, and billing data can lag.
  • The current service has no end-user UI; the demonstration is an HTTP workflow plus cloud/database evidence.
  • The public task surface requires a bearer. Public health alone is not a working interactive product demo.
  • Cloud Build does not independently attest the Git SHA; the evidence ledger records a clean-source gate and the resulting immutable image digest.
  • Vertex Data Access logs were not used as evidence. Provider identity is bound in the application plan record and deployment configuration.
  • demo-001, demo-002, and demo-003 are preserved historical evidence. The final video uses the distinct demo-004 run; its live proof segment is continuous and normal speed, while explanatory scenes, narration, and captions are post-produced and are not represented as an unedited full take.

Project Links

Built With

  • cloudevents
  • docker
  • gemini-3.5-flash
  • google-cloud-firestore
  • google-cloud-run
  • google-genai-sdk
  • python
  • vertex-ai
Share this project:

Updates