Healthcode

Healthcode (healthcode-v0) is the Ollie Health agent-authoring model. It powers health code — the natural-language interface in the health CLI that turns a builder’s prompt into a sequence of concrete health commands you can run to scaffold, configure, and deploy a Health Loop.

This page documents what Healthcode is, what it does, what it will not do, and the wire contract between the CLI and the hosted model.

What Healthcode is

A planner. You describe what you want to build; Healthcode produces:

1. An assistant message — a short markdown reply (≤ ~6 lines) explaining what it would do and why.
2. A tool plan — an ordered list of concrete health CLI commands you should run to make progress. Every command starts with health and uses only documented subcommands.

$ health code --hosted --prompt "build a care navigation whatsapp agent that calls FACIAL_SCAN then routes BP through HEALTH_CALCULATOR"
 
Healthcode session
model: healthcode-v0
intent: build_agent
target: local_terminal
 
assistant:
I'll scaffold a WhatsApp-channel agent, add a route plan that names FACIAL_SCAN
and HEALTH_CALCULATOR, then save a route fixture for the BP triage flow.
 
tool_plan:
- [scaffold] health init care-nav --channel whatsapp -- scaffold the workspace
- [route]    health route --task agent --prompt "care nav with facial scan then BP triage" --save --name care-nav -- save the routing plan
- [tools]    health tools list -- confirm FACIAL_SCAN + HEALTH_CALCULATOR are bindable
- [build]    health agent build -- validate the manifest
- [verify]   health verify -- preflight before sync

What Healthcode will not do

• Clinical advice. Healthcode is developer infrastructure. If a prompt asks for diagnoses, treatment recommendations, prescribing, or benefit verification, the local safety gate marks the turn clinical_blocked and Healthcode returns an empty tool plan with a redirect message. The hosted endpoint is never engaged for blocked prompts — that is a deliberate boundary, not a fallback.
• Raw shell. Every command in the tool plan must start with health and uses only documented subcommands. Shell metacharacters (;, &, |, backticks, $, <, >, newlines) cause the step to be marked blocked server-side.
• PHI in the request body. The CLI redacts PHI client-side before posting to /cli/code/sessions. The raw bearer token is never in the request body, only in the Authorization header.

Architecture

Healthcode is a brand, not a single upstream model. The brand healthcode-v0 is stable across upstream swaps:

health (CLI)
   │  POST /cli/code/sessions
   │  Authorization: Bearer <token>
   │  X-Ollie-Company: <slug>
   │  body: { redacted_prompt, intent, route_context, safety_checks, ... }
   ▼
Loops worker (apps/worker)
   │  cliBearerAuth() — system-key or future cli:run token
   │  composeCodeSession() — safety gate + sanitizer
   │  callHealthcode() — through Cloudflare AI Gateway
   ▼
Cloudflare AI Gateway
   │  https://gateway.ai.cloudflare.com/v1/{account}/{gateway}/openrouter
   │  Caching, observability, latency metrics
   ▼
OpenRouter
   │  Default upstream: openrouter/auto (free auto-router)
   │  Future: a fine-tuned Healthcode model on CF Workers AI
   ▼
Free model (Qwen3 Coder, Kimi K2.6, DeepSeek V4, ...) returns JSON matching
the Healthcode response schema. Tool plan sanitization runs server-side
before the response is returned to the CLI.

CLI usage

One-shot

health code --prompt "build a care navigation agent loop"

Runs locally only. Uses the offline planner for intent classification and safety gating; no network call. Useful for safety checks and CI.

Hosted

health code --hosted --prompt "build a care navigation agent loop"

Requires health login to have stored a token. The CLI sends the redacted prompt to /cli/code/sessions and overlays Healthcode’s assistant_message and tool_plan on top of the local plan.

REPL

health code

Launches the Healthcode REPL — a ratatui-driven chat surface that classifies each turn, renders the tool plan in a sidebar, and audits to ~/.ollie/health/logs/audit.jsonl. Ctrl+H toggles offline/hosted mode. Esc or Ctrl+C exits.

Execute a saved step

health code --exec --session-id <uuid> --step 1

Runs a single step of a saved code session through a strict safety gate: only commands starting with health , no shell metacharacters, allow-listed subcommands only. Stdin closed, results written to .health/code/runs/run-<uuid>.json.

Wire contract

Request

POST /cli/code/sessions

{
  "session_id": "uuid",
  "turn_id": "uuid",
  "redacted_prompt": "build a care navigation agent loop",
  "intent": "build_agent",
  "route_context": { "hosted": true, "...": "..." },
  "safety_checks": ["developer-infrastructure-only"],
  "workspace_manifest": null
}

Headers:

• Authorization: Bearer <token> — required.
• X-Ollie-Company: <slug> — surfaced on the server context for attribution.
• X-Ollie-CLI-Version: <version> — surfaced on /cli/account.
• Idempotency-Key: <sha256-of-request> — set by the CLI.

Response

{
  "model": "healthcode-v0",
  "assistant_message": "I'll scaffold a WhatsApp agent and add a route plan...",
  "tool_plan": [
    {
      "kind": "scaffold",
      "command": "health init care-nav --channel whatsapp",
      "purpose": "scaffold the workspace",
      "requires_auth": false,
      "blocked_reason": null
    }
  ],
  "execution_target": "local_terminal",
  "audit_id": "cli-code-<uuid>",
  "metadata": {
    "egress": "cloudflare_ai_gateway",
    "upstream_provider": "openrouter",
    "upstream_model": "openrouter/auto",
    "classified_intent": "build_agent"
  }
}

Safety gate short-circuit

If the CLI’s local classifier sets intent: "clinical_blocked", the worker skips the upstream call and returns:

{
  "model": "healthcode-v0",
  "assistant_message": "This prompt was locally classified as a clinical-advice request. Healthcode will not produce a plan. Reframe as a builder/operator task (e.g. data sourcing, eval design, deployment).",
  "tool_plan": [],
  "execution_target": "local_terminal",
  "audit_id": "cli-code-<uuid>",
  "metadata": { "upstream": "skipped", "blocked": "clinical_advice" }
}

Model roadmap

Each stage swaps only the upstream. The CLI surface, the system prompt, and the JSON response schema do not move — that is the contract.

Operator notes

• Cost: free tier today. Cloudflare AI Gateway adds ~10–50ms proxy latency. Cache hits on identical prompts are free and instant.
• Observability: every Healthcode call shows up in the CF AI Gateway dashboard. The CLI also writes a local audit row to ~/.ollie/health/logs/audit.jsonl.
• PHI posture: Healthcode never sees raw PHI. The CLI’s local redactor runs first; the worker rejects empty redacted_prompt. The metadata returned contains no patient context, only routing info (provider, upstream_model, egress).
• Token scope: today the bearer token gates the endpoint via the WORKER_SYSTEM_API_KEY bypass. Per-company cli:run scoped tokens land with the device-link login flow.