Kernel Client and Auto

Purpose

FlashBoard exposes the general-purpose agent route as Auto. Internally it is the kernel-owned Normal Path. It is the only route that may inspect an editor snapshot, plan work, call the public atomic editor tools, inspect their results or review frames, and refine the work in later bounded rounds.

The private kernel owns the Intelligence Module behind that route. The module selects either a configured API backend for Standard mode or the Codex app-server for Logic mode. Backend choice does not create another browser or HTTP route. The only separate product workflow is Story.

The editor labels the two model choices inside Auto Fast and Logic. Fast maps to the standard DeepSeek-backed API mode; Logic maps to Codex. Raw provider names and the compatibility Very Fast/Fast/Slow model classes are not exposed as editor controls.

The internal protocol constant fast-agent-v2 and some fastV2* source and storage names remain compatibility identifiers for existing journals and D1 rows. They do not describe a second product path.

Ownership boundary

The public editor owns:

• the bounded timeline and project snapshot;
• the flat, digest-pinned atomic tool catalog;
• tool schemas, local policy, authorization, confirmation, transactions, undo, deterministic execution, and bounded result projection;
• browser/session binding and the public Cloudflare/D1 relay.

The private kernel owns:

• prompts and provider input;
• tool categories and progressive discovery;
• fast-path selection and intent-to-operation compilation;
• sequencing, retries, result inspection, visual review, and refinement;
• API-versus-Codex backend selection and provider billing callbacks.

See ADR-001 for the binding architectural rule.

Public HTTP catalog

The Cloudflare boundary exposes 14 method/path shapes. Five are the signed-in browser Normal Path, seven are private service callbacks, and two are the generic health and Seedance relays.

Browser and generic routes

Route	Authentication	Behavior
GET /api/kernel/health	Public	Relays private service readiness.
POST /api/kernel/preproduction/seedance	Signed-in user	Relays the special Seedance preproduction stage with the authenticated principal.
GET /api/kernel/normal/capabilities	Signed-in user	Advertises Standard/Logic availability and the single Normal Path execution profile.
POST /api/kernel/normal/turns	Signed-in user	Validates the bounded request, binds it to the user and page in D1, signs the private envelope, and starts or replays the turn.
GET /api/kernel/normal/turns/:turnId/events	Owning user and page binding	Relays ordered SSE events and renews the open-page lease.
POST /api/kernel/normal/turns/:turnId/operation-results	Owning user and page binding	Validates and relays one deterministic atomic-operation result.
POST /api/kernel/normal/turns/:turnId/cancel	Owning user and page binding	Marks the D1 turn terminal first, then best-effort cancels the private run.

Private service callbacks

These same-origin Cloudflare routes require the kernel service bearer plus a turn-bound assertion. They are not browser APIs.

Route	Purpose
POST /api/kernel/normal/service/turns/:turnId/rounds/:round/authorize	Atomically authorize one provider round.
POST /api/kernel/normal/service/turns/:turnId/rounds/:round/settle	Settle provider usage for one authorized round.
POST /api/kernel/normal/service/turns/:turnId/rounds/:round/authorize-replay	Reconcile a previously recorded authorization.
POST /api/kernel/normal/service/turns/:turnId/rounds/:round/settle-replay	Reconcile a previously recorded settlement.
POST /api/kernel/normal/service/turns/:turnId/complete	Complete a turn after settled work.
POST /api/kernel/normal/service/turns/:turnId/complete-replay	Reconcile an already recorded completion.
POST /api/kernel/normal/service/turns/:turnId/fail	Release reservations and fail the turn safely.

There is no public V1 compatibility route. /api/kernel/compile, /api/kernel/runs/:runId/complete, /api/kernel/hosted-agent/*, generic tool result posting, and deferred operation settlements are removed and return 404.

Auto lifecycle (internal Normal Path)

1. The signed-in browser reads GET /api/kernel/normal/capabilities.
2. It captures one revision-bound semantic snapshot and a digest-pinned flat catalog of allowed atomic tools.
3. POST /api/kernel/normal/turns creates the D1 billing/session binding and forwards a signed envelope to the private kernel.
4. The Intelligence Module selects the API backend or Codex from the requested agent mode and server policy.
5. The kernel plans the next bounded action. A private fast path may compile directly to explicit public operation-plan steps; otherwise the model can browse categories and select atomic tools.
6. The editor revalidates every operation, executes it transactionally, and posts the projected result.
7. The kernel adds results, retryable errors, and captured review grids back to the next provider round. It may inspect, correct, or refine the edit until completion or the iteration/spend bound.
8. SSE emits narration, operation requests, billing settlement, and the final terminal event. Reload resume is accepted only when the persisted request, cursor, page binding, and canonical timeline checkpoint still match.

Planning is a request mode (normal, plan, or read-only) inside Normal Path, not a separate route. plan may produce an explicit plan without committing a mutation; read-only forbids mutation locally.

Failure and security rules

• The browser cannot select a raw private provider or model ID. The editor UI sends only its Fast/Logic route choice; compatibility model-class fields are not presented as user-facing routes.
• Every mutation is checked again by the editor; a kernel assertion never bypasses local tool policy or transaction ownership.
• D1 cancellation is authoritative before origin notification.
• A stale revision, state fingerprint, cursor, catalog digest, page lease, or client/session binding fails closed.
• Provider billing authorization and settlement are idempotent per turn and round.
• Capability-specific provider tools are included only when the request carries the matching server-validated execution context. General and read-only turns cannot receive a direct-edit capability by catalog accident.
• Retryable orchestration failures keep the run open while retry budget remains; the root becomes terminal only after the bounded attempts are exhausted.
• Media bytes stay in the editor unless an explicitly bounded reference is included in the request.

Development topology

Component	Default address
Editor and bridge	http://localhost:5173
Private kernel	http://127.0.0.1:8787
Local Cloudflare/D1 relay	http://127.0.0.1:8788
Codex app-server used by Logic	ws://127.0.0.1:4500

Production uses the same-origin /api/kernel/* Cloudflare boundary and the private kernel origin configured by KERNEL_ORIGIN.