Skip to content

📝 RFC: v7 - Non-CLI backends: Hive as tool host and a zero-cost CLI-less coordinator (hive-lite) #18464

Open

Description

@hanthor

Summary

Let Hive dispatch work to non-CLI backends (free-tier stateless inference APIs, vendor cloud agent sessions, chat/MCP bridges, contributor relays) while Hive stays the tool host and security gate. The goal is a zero-cost, CLI-less coordinator profile ("hive-lite"). It needs no tmux, ttyd, NET_ADMIN, local agent subprocesses or persistent /data volume, and can run on free serverless tiers.

Held RFC: a design proposal for discussion, targeted at Hive v7 (cut from v6). It is labelled hold so no hive agent picks it up for implementation until the open questions are settled. Self-contained library slices that change no default behaviour may land on v6 ahead of that, so the design can be reviewed as code. The first one is linked below. No CI requirement, review authority, protected-path rule, merge protection or default config changes. Every new path is default-off.

Status (2026-11-16). Merged on v6 as opt-in libraries with nothing wired:

Open: #18511, a router fix found live. Everything past the hold is built and run live in the tuna-os fork (tuna-os#186), as data for the open questions:

  • write tools and fix mode;
  • the tool-hosted/github-mediated modes (§2);
  • the Store (§7) with resumable checkpoints.

See the update comments.

Relationship to #17091 (v7 Hive for teams). This RFC is the execution-side counterpart of three #17091 deliverables:

  • Its pluggable entitlement provider for bring-your-own model accounts is what Family C's provider list and Family E's connected clients feed.
  • Its chat spine (Matrix et al. as transports) is the natural carrier for Family A.
  • Its identity linking is what github-mediated and MCP-connected agents need, so that a vendor writing as a user, or an MCP client, resolves to a hive principal and role.

Also related: #12815 (runtime guardrails, v7), #5698 (backend capacity and placement), #4002 (re-entrant turns).

Prior art: #2808 ("hive lite" 5-minute enrollment, closed) covered enrollment friction. This RFC covers the runtime footprint. The two compose: a hub-hosted governor (#2808 option 1) needs exactly the CLI-less dispatch described here.

Problem

The crux pane fleet assumes a privileged container. Kicks are typed into tmux (send-keys -l, src/crux/agent/terminal.go:112). Completions are scraped with capture-pane (terminal.go:31-53). Egress is redirected into the proxy via iptables (NET_ADMIN), and state lives on a /data PVC. Self-hosters therefore need Compose, Podman or Kubernetes.

Meanwhile a lot of usable inference and agent compute needs no local process at all:

  1. Stateless OpenAI-compatible APIs with free tiers (Groq, OpenRouter :free, Gemini via AI Studio, Cloudflare Workers AI, Cerebras trial).
  2. Vendor cloud agent sessions (Claude Managed Agents, Claude Code routines, GitHub Copilot cloud agent).
  3. Always-on chat/MCP agents (OpenAI dots via an MCP Events bridge or a Matrix bridge).
  4. Contributor relays (the existing contributor-relay WebSocket, src/docs/contributor-relay.md).

If Hive executes every repo-touching tool call itself, the remote side only has to think. Hive shrinks to a pass-shaped coordinator: discover/claim, stage labels, dedupe, budgets, PR/merge bookkeeping.

Existing seams this builds on (verified on v5 @ c39c0f654; pkg/turn and pkg/extwork match v6 @ b8ecb426b apart from formatting)

Seam Where Role in this RFC
extwork.Adapter (Engine/Start/Observe/Cancel/OpenArtifact), Factory registry, build-tag wiring src/pkg/extwork/adapter.go:116-134, registry.go:18, src/cmd/hive/extwork_<engine>.go Contract for Families A, B and D. Hosted engines must not join KNOWN_BACKENDS / CLIBackends (src/docs/design/external-workflow-admission.md:432-438).
Modes off / shadow / report-only admission.go:17-21; defaulting in src/pkg/config/runs.go:93-140; write-stage refusal per adapter via the Gate interface (binding.go:87-94) Extended in §2 below.
Claude Managed Agents prototype src/pkg/extwork/managedagents/ (engine name claude-managed-agents), src/docs/backend-gap-claude-managed-agents.md Already uses self_hosted and agent.custom_tool_use → Hive executes.
Re-entrant turn model: SessionEnvelope, Runner.Step, LLMClient, ToolExecutor, Journal/JournaledExecutor src/pkg/turn/, docs/rfc-4002-reentrant-conversation-state.md Family C is an LLMClient driven by turn.Runner. The coordinator-held transcript is the envelope. No new conversation store.
Security stack proxy deny of POST /pulls and merge (src/crux/proxy/rules_deny.go:44-54); 300 req/h per-agent GitHub cap (config/agent_runtime.go:15); canary egress (HIVE-CANARY-, src/pkg/ioscan/canary.go:23); AuthorizePROpen (src/crux/agent/manager_modes.go:145); pushbroker.DefaultProtectedPaths (pushbroker.go:29-37); ioscan fail-open/closed by ACMM level (src/pkg/config/config.go:658-666); tier tokens (src/crux/agentmode, src/pkg/github/app.go:288-300); EnsureClosingIssueLink (#11888) and relay PR linking (#14763) Reused unchanged as the tool-host's execution side.

Proposal

1. Four dispatch families

Family Transport Contract Who holds GitHub write?
C: stateless LLM (build first) OpenAI-compatible /chat/completions, ordered provider waterfall turn.LLMClient + turn.Runner + a hive-tool ToolExecutor Hive only
B: vendor cloud sessions Vendor HTTP APIs extwork.Adapter Hive (Managed Agents) or the vendor (Routines, Copilot)
A: chat/MCP bridges dots-bridge HTTP/WS; Matrix bridge extwork.Adapter Hive only
D: contributor relays Existing relay WebSocket Existing contributor protocol Hive (unchanged)

2. Admission: two new modes, decided by credential custody

Mode Custody Ceiling
report-only (existing) No write credential anywhere Advisory / triage comments
tool-hosted (new) The remote side holds no GitHub credential. Every read/write is a hive-tool call executed by Hive through ioscan → toolapprove → pushbroker → AuthorizePROpen, with a tier-scoped App token Up to ISSUES_AND_PRS. Merge stays with existing merge gates.
github-mediated (new) The vendor session writes to GitHub as a user identity Hive does not mediate The output is treated as an untrusted outside-contributor PR: CI, protected-path check and an independent review before merge. Hive never grants it merge authority.

Write-stage refusal stays in each adapter's Gate. A mode only raises the ceiling an adapter may declare. It never forces one.

3. hive-tool/v1: Hive as tool host

Native function-calling schemas where the backend supports them, and fenced ```hive-tool JSON blocks for chat-only bridges. Same allowlist both ways:

issue.read, repo.list_files, repo.read_file (line ranges), repo.search_code, checks.read (ADVISORY); issue.comment, issue.label (ISSUES_ONLY); repo.patch_files (search/replace or unified diff → Git Data API on a Hive-owned branch, pushbroker rules enforced), pr.create (via AuthorizePROpen + closing-link), pr.comment (ISSUES_AND_PRS); task.complete, task.abort (terminal).

  • Idempotency: each side effect goes through turn.JournaledExecutor with a key from turn.DeriveIdempotencyKey. Per RFC [v5] RFC: re-entrant conversation-as-state agent turn model (durable, handoff-able agents) #4002 §"Ordered operations", a model-supplied call_id is traceability only and must not be the idempotency key, because replays re-mint it. (This corrects an earlier draft.)
  • Payload caps: tool output over 12k chars is truncated with a pagination cursor (dots-bridge forwards at most 16,000 chars of the latest message and 300 KiB total).
  • Inbound scanning: every reply is canary-scanned and schema-validated before execution, and the pre-kick context passes through ioscan.

3a. Hive as an MCP server (pull-mode inference, proposed Family E)

Everything above is push: Hive calls a model or a vendor. The same hive-tool/v1 surface can be published as a remote MCP server (Streamable HTTP) so that any MCP-capable agent can connect to Hive and spend its own inference on Hive work. Examples: a contributor's Claude Code or Codex CLI, a desktop chat app's custom connector, or ChatGPT/dots connectors.

  • Agent-driven mode. The client's model calls hive.next_task (an offer under the existing contributor protocol, accepted or declined before more context is delivered), then the read/patch/PR tools, then task.complete. Hive executes every tool exactly as in tool-hosted mode. The connected user's subscription or API key supplies the inference. Hive pays nothing and holds no model credential.
  • Sampling mode (Hive drives). MCP lets a server ask a connected client to run a completion (sampling/createMessage, with the client's human-in-the-loop approval). That makes a connected client one more provider in the Family C waterfall: turn.Runner keeps the envelope and Hive keeps control of the loop. Client support for sampling varies, so this is opportunistic.
  • Identity and trust. MCP's OAuth authorization maps a connection to a contributor identity and trust tier (src/docs/contributor-trust-and-roles.md), which sets the tool allowlist (ADVISORY → ISSUES_AND_PRS). This is a standards-based transport for what the contributor relay WebSocket already does, not a new trust model.
  • Hosting. Agent-driven mode is plain request/response and fits a serverless Worker. Sampling and offers need a session that can stream back to the client, so a Durable Object or sidecar.
  • Risks. A connected agent is an untrusted actor. All output gets the same ioscan, canary and schema checks. Rate limits are per identity. Sampling outputs count as untrusted model text.

4. Family C detail: the "one-turn problem"

Free APIs are stateless, so the coordinator keeps the transcript. That is already turn.SessionEnvelope. Each coordinator pass loads the envelope, calls Runner.Step, executes approved tools, persists and exits. A kick is therefore resumable across restarts and hosting moves by construction.

Required behaviours (#18465 implements the first three; the fourth's compactor is turn.DigestCompactor):

  • 429 waterfall: ordered providers. Retry-After sets a cooldown. 5xx/408/transport and 200-with-error bodies fail over. 401/403 and 404/410 (retired free model) fail over with a long cooldown. Other 4xx do not fail over, since resending a bad request only burns budget elsewhere.
  • Daily budgets are counted coordinator-side, with cooldowns behind a Ledger interface so a stateless host can keep them in its store.
  • Exhaustion is not failure: the client returns an error matching new turn.ErrInferenceCapacity, and Runner.Step parks the session as paused without consuming a turn (today any LLM error marks the session failed).
  • Later: a summarising compactor with a state digest, re-sending the primer on a model-family switch, and a fleet turn budget in the governor (the unit for Family C is turns).

5. Family B, per vendor (verified 2026-11-16)

Engine Start Observe Cancel Mode
claude-managed-agents POST /v1/sessions (beta managed-agents-2026-04-01) GET /v1/sessions/{id} + events; statuses idle/running/rescheduling/terminated user.interrupt → wait for idle → archive tool-hosted: omit authorization_token, custom tools answered with user.custom_tool_result. Set networking limited explicitly with allow_package_managers: false: the default is unrestricted, and package-manager mode opens github.com and api.github.com. Billed at $0.08/session-hour plus tokens.
claude-routines POST /v1/claude_code/routines/{id}/fire with text ≤ 65,536 chars (delivered as untrusted <routine-fire-payload>); 30 fires/h per routine, 100/h per account; research preview No status API. Correlate on claude/* branch / PR / marker via GitHub events None. Abandon and ignore github-mediated (commits as the user)
copilot-cloud Assign issue via REST agent_assignment (changelog 2025-12-03) or POST /agents/repos/{o}/{r}/tasks (public preview) GET …/tasks/{id} state: queued/in_progress/completed/failed/idle/waiting_for_user/timed_out/cancelled None. Close/abandon the PR github-mediated. Requires a user token. GitHub App installation tokens are not supported. Needs Copilot Business/Enterprise. Identity and audit implications need discussion.
codex-cloud Dropped. No public task-creation API (CLI codex cloud exec only; see openai/codex#24777). @codex PR comments only do reviews. Revisit if an API ships.

6. Family A detail

  • dots via uezo/dots-bridge (MIT, unofficial, created 2026-10-22). OpenAI-compatible Chat Completions/Responses. Idempotency-Key (≤128 chars). X-Dots-Request-ID and GET /api/messages/{id}/responses recover after a disconnect. kind=progress|final_answer|cancel. Up to 16 queued requests per WebSocket. Cancel only happens through supersession or unsubscribe; there is no client cancel endpoint, so CancelFacts{Requested:true} only. Underlying MCP Events is a draft spec with webhook-only delivery.
  • dots via beeper/chatgpt-dots (AGPL-3.0, mautrix bridgev2; approvals !dots accept|decline|accept-always). Completion is heuristic: a complete hive-tool block, else m.replace edit-idle timeout. Prefer an appservice push (PUT /_matrix/app/v1/transactions/{txnId}), which needs an HTTPS endpoint and homeserver registration. A plain bot account must long-poll /sync instead, which suits a Durable Object or sidecar, not a cron pass.
  • Out of scope: Grok over Telegram (no primary source for an official bot; use the xAI API as Family C) and Meta Muse bridges (Muse is reachable as an API, so also Family C).
  • Consumer-account bridges are opt-in, declare ToS posture and are capped to human cadence.

7. State: governance on GitHub, ephemeral state behind a store

Labels, claims and PRs stay on GitHub. Envelopes, the router ledger and adapter correlation live behind a small Store. There are three zero-cost drivers:

  • Cloudflare Workers + D1 (+ Durable Object for Matrix /sync). Free tier: 100k req/day, 10 ms CPU per invocation, 50 subrequests, 5 cron triggers. D1: 5 GB, 5M rows read and 100k written per day. Each coordinator step must be I/O-bound and small. 10 ms CPU rules out heavy diffing in-Worker.
  • GitHub Actions cron + state branch. Runs at most every 5 min, without guarantee, and public repos disable schedules after 60 days of inactivity. CAS must use the Contents API sha precondition (409 on mismatch) per state file. PATCH /git/refs force=false only rejects non-fast-forwards and is not a compare-and-swap.
  • Netlify Functions + Upstash/Neon. Scheduled functions get 30 s, sync functions 60 s. Upstash free is 500k commands per month. Neon free is 100 CU-h/month.

8. Free-tier inference facts the router must respect (verified 2026-11-16)

Provider Free terms Notes
Groq Free plan exists Docs' limit table is ambiguous (labelled Free, footnoted Developer: 30 RPM / 1K RPD / 8K TPM / 200K TPD for gpt-oss-120b and qwen3.8-27b). Confirm in console before encoding. 429 + retry-after; x-ratelimit-* headers.
OpenRouter :free 20 RPM; 50 req/day (<10 credits purchased), 1,000/day (≥10) openrouter/free router accepts tools; ToS bans multi-accounting to evade limits.
Gemini (AI Studio) Free, no billing Free-tier prompts/outputs may be used for training and human review. Never route private-repo or secret-bearing context to it. OpenAI-compat at …/v1beta/openai/. Per-model limits only shown in AI Studio.
Workers AI 10,000 neurons/day, resets 00:00 UTC Tool calling only on tagged models; tools on the OpenAI-compat endpoint unconfirmed.
Cerebras No permanent free tier. $5 trial credit, verified payment method, expires in 30 days Treat as a trial, not a waterfall tier.

Provider discovery: open-free-llm-api/awesome-freellm-apis publishes a daily status.json (22 providers / 311 free models on 2026-11-16) and is suitable for liveness. Limits must come from provider docs. The once-canonical cheahjs/free-llm-api-resources now 404s, and the jtig37 copy has not been pushed since 2024-08, so neither is usable.

9. Guardrails

  • Excluded surfaces: GitHub Models (retired 2026-07-30) and Jules (read-only 2026-11-11, shutdown 2026-12-31).
  • Data-class routing: free tiers that train on inputs are only eligible for public-repo work. An operator allowlist per provider decides this, with no default inclusion.
  • Every new adapter and mode ships default-off. Shadow mode first.

Milestones (each a separate PR / issue after discussion)

  1. Family C core: pkg/turn/llmrouter and the ErrInferenceCapacity pause (companion PR); hive-tool ToolExecutor over the GitHub API reusing pushbroker/AuthorizePROpen; tool-hosted mode.
  2. Coordinator pass + Store with the D1 and state-branch drivers; summarising compactor; governor turn budget.
  3. Family B: promote claude-managed-agents to tool-hosted; add copilot-cloud and claude-routines under github-mediated (after the token-identity question is settled).
  4. Family A: dots-bridge adapter, then the Matrix adapter.
  5. Family E: Hive MCP server (agent-driven mode first, then sampling as a Family C provider).

Open questions

  1. Is github-mediated acceptable at all given the vendor writes as a user identity (Routines, Copilot)? Or should those engines stay report-only until a Hive-owned identity is possible?
  2. Should tool-hosted cap at ISSUES_AND_PRS permanently, keeping merge out of non-CLI paths entirely?
  3. Should the hive-tool ToolExecutor live in pkg/turn or in a new pkg/hivetool shared by extwork adapters (Managed Agents custom tools, dots MCP)?
  4. Is a Hive MCP server (§3a) a better first transport for contributor compute than adding more bridges? It reuses one tool surface for Families A, D and E.
  5. Should the Store be a new package, or should we generalise extwork.AdmissionStore/turn.Persister? Fork data point: a separate compare-and-swap key/value package (pkg/coordstate) was enough. turn.Persister has no version or precondition, so it cannot detect two overlapping passes.

Verification ledger

The figures above were checked against primary sources on 2026-11-16: vendor docs, changelogs, the repos themselves and Hive source at c39c0f654. Corrections relative to the pre-RFC draft:

Activity

  1. added
    help wantedDenotes an issue that needs help from a contributor. Must meet "help wanted" guidelines.
    kind/designCreated by Hive for agent-filed issue provenance
    proposalRFC / design proposal for discussion
    on Nov 16, 2026
  2. hanthor commented on Nov 16, 2026

    @hanthor
    ContributorAuthor

    First library slice (Family C, default-off and unwired): #18465 pkg/turn/llmrouter with the 429 waterfall, plus the ErrInferenceCapacity → paused handling in turn.Runner.

  3. hanthor commented on Nov 16, 2026

    @hanthor
    ContributorAuthor

    Update: converging with the Model Gateway work, and first live Family C runs (2026-11-16)

    Convergence with the in-flight gateway work (#18449, #18463)

    Family C should not grow a parallel provider config. #18465 now builds router providers from crux/config.GatewayConfig:

    • Auth: crux/inference.ResolveGatewayAuth, so key env/file and watsonx IAM minting match the gateway path.
    • URL: config.LiteLLMChatCompletionsURL, the rule the translator and Test Connection share.
    • Health: failures feed crux/inferencehealth, so free-tier throttling appears in the existing gateway-health UI.

    The proposal is that a free-tier waterfall is just an ordered list of gateway names. Two follow-ons:

    Open question for the gateway owners: the shared URL rule appends /v1/chat/completions unless the endpoint ends in /v1. Gemini's OpenAI endpoint is …/v1beta/openai/, which would become …/v1beta/openai/v1/chat/completions. I couldn't confirm the effect without a key, because Gemini validates the key before routing. Gemini also returns error bodies as a JSON array.

    Live runs: turn.Runner + llmrouter + a read-only hive-tool executor, Workers AI free tier, issue #18441

    Measured, not inferred:

    1. Workers AI's OpenAI-compatible endpoint supports tools. 23 catalogue models are tagged for function calling, and llama-4-scout, gpt-oss-120b, glm-4.7-flash and qwen3-30b all returned well-formed tool_calls. This closes the RFC's "unconfirmed" row.
    2. Dotted tool names break silently. With issue.read, llama-4-scout replied in prose with no tool call. With issue_read it called the tool. Strict OpenAI servers reject dotted names outright. The router now maps names to a wire-safe form and back.
    3. content: null on an assistant tool-call message makes gpt-oss-120b on Workers AI return 400. The router now sends "".
    4. Degenerate 200s happen. gpt-oss-120b returned about 300 ! at roughly 4k tokens of context. The router now treats that as malformed and fails over (it fired once in a later run).
    5. toolapprove doesn't know the hive-tool names. Reads were operator-gated at L4, and writes would skip the AgentMode gate and auto-approve at L5/L6. Fixed in 🐛 fix: toolapprove classifies hive-tool/v1 names so AgentMode gates apply #18467.
    6. Weak models write the tool call as text. llama-4-scout wrote [task__complete(summary=…)] as prose, and the Runner marked the session completed with no result. Requirement: a tool-hosted session ends only on task.complete/task.abort, and max-turns or a prose answer must not count as completed. A fenced hive-tool text fallback parser is worth having even for native-tool models.
    7. A sliding-window compactor causes amnesia loops. With DefaultCompactor{2, 20}, the issue fell out of context, the model re-read it and repeated searches. Requirement: a summarising compactor that pins the task and a state digest.
    8. Tool quality matters more than model quality. GitHub's code-search API returned nothing useful for exact strings, and the model looped. With git grep over v6 it found the right files in 7 turns. Requirement: repo.search_code must be backed by a Hive-owned index (pkg/codeindex or a maintained clone), not GitHub search.
    9. A forced finish works. After 8 turns the model was offered only task.complete, and gpt-oss-120b produced a triage in 10 turns. Its file:line citations (dependency_bot_handoffs.go:149-168, dependency_bot_rebase.go:15-20) were accurate and it found the real defect: the hand-off comment still says @dependabot rebase where the code's own docs say recreate. Its conclusion ("no code change needed") was wrong. The output is a useful advisory, not something to trust unreviewed.
    10. Context re-send is the binding constraint.
    run turns prompt tokens neurons (free = 10,000/day) result
    sliding window 20, GitHub search 16 31.7k 1,069 looped, no result
    window 60, GitHub search 18 54.2k 1,801 looped
    window 60, git grep 18 170k 4,426 right files, never finished
    window 60, git grep, finish at 8 10 55.1k 1,233 triage delivered

    That is about 8 triages per day on one Workers AI account. The waterfall across providers, compaction and tool-output digests are what will scale it, which matches the working-notes estimate.

    Rough edge seen in the runs: the model also called a tool that doesn't exist (search). Unknown names correctly fail at execution.

  4. hanthor commented on Nov 16, 2026

    @hanthor
    ContributorAuthor

    Update 2: the full read-only stack, run live (2026-11-16)

    Three opt-in, unwired PRs now make up Family C's read path. They were exercised together in a local integration build with live Workers AI free-tier runs on #18441:

    New measurements

    • tool_choice: "required" is honoured by llama-4-scout and glm-4.7-flash. gpt-oss-120b ignores it and still reports finish_reason: "tool_calls" with no call. A finish phase therefore needs a coordinator policy for prose. The one I tested: prose in a finish-only turn becomes an implicit completion, flagged as such.
    • Models call tools they weren't offered. In a finish phase offering only task.complete, gpt-oss called repo.search_code and repo.read_file, and the Runner executed the read. That is now fixed in ✨ feature: llmrouter free-tier gateway waterfall + capacity pause for turn.Runner #18465.
    • The evidence gate turns a confident wrong answer into an honest abort. llama-4-scout's ungrounded task.complete was refused; it then called task.abort ("relevant code not found") for 204 neurons. glm-4.7-flash's citation, from a search hit, verified.
    • Model comparison (same task, forced finish after 8 turns):
    model turns neurons result
    glm-4.7-flash 9 513 explicit task.complete, grounded, lists what it couldn't verify
    gpt-oss-120b 10 1,476 grounded; prose finish
    llama-4-scout 2–3 74–204 ungrounded → refused → honest abort

    glm-4.7-flash is about 3× cheaper per session than gpt-oss on Workers AI, so roughly 19 grounded triages per day on one free account.

    • DigestCompactor vs a sliding window (window 12, no forced finish, n=1 each): glm used 19% fewer prompt tokens and 17% fewer neurons. There was no measurable change in repeats, since the executor's duplicate refusal already handles those. Without a finish phase no run ended with task.complete, so a turn budget plus a forced finish is the policy that delivers results, and the compactor is a cost saving.
    • Design note: pinning the task message isn't enough when the issue body arrives as a tool result, because it gets compacted away and models re-request it. The coordinator should inline the (ioscan-screened) issue body into the pinned task message, as Hive's kick prompts do today.
    • Orphaned tool messages: Workers AI accepts them. The OpenAI spec forbids them, and DigestCompactor never produces one.

    Still blocked on discussion (not started, by design)

    Write tools (repo.patch_files, pr.create through pushbroker and AuthorizePROpen), the tool-hosted and github-mediated admission modes, the coordinator pass and Store, and Families A, B and E. These are the RFC's open questions.

  5. hanthor commented on Nov 16, 2026

    @hanthor
    ContributorAuthor

    Update 3: building past the hold in the tuna-os fork (2026-11-16)

    The write side, a runnable coordinator and fix mode are now built and run live in the fork: tuna-os#186, stacked on the fork's upstream sync. Nothing here changes upstream's held status. These are data points for the open questions.

    What exists

    • cmd/hive-lite, a standalone binary plus a workflow_dispatch workflow on a free hosted runner:
      • gateways come from a YAML list of Hive GatewayConfig entries;
      • search uses pkg/codeindex;
      • it upserts one advisory comment;
      • it exits 75 when no free capacity is left.
    • pkg/hivelite, the session driver: issue body screened by ioscan and pinned in the task, a per-session canary, DigestCompactor, a turn budget with forced finish, implicit completion only through the evidence gate, and canary/ioscan output withholding.
    • Tool-hosted writes (repo.patch_files, draft pr.create) behind executor-side guards: push-capable mode, pushbroker protected paths, exact-once search/replace, a whole-file-rewrite guard, an optional pre-commit Verifier, closing-keyword neutralisation, and a Hive-written verification record in the PR body.

    Live results

    • Report mode on 🐛 scanner: stale Dependabot PRs stay stuck (App's @dependabot rebase is refused; NOTICE commit blocks rebase) #18441 (dry run): a grounded advisory in 13 turns and 68 s. glm-4.7-flash returned HTTP 500 mid-session, the router failed over to gpt-oss-120b for 8 turns, and glm served the final turn.
    • Fix mode on a private sandbox with a seeded off-by-one:
      1. Without guards, the free model diagnosed the bug correctly, then rewrote the whole file, deleted an unrelated function, and added a test its own formula fails. Its PR description read well. This is the strongest argument in this thread for tool-hosted needing executor-side guards and verification, not just approval.
      2. With guards, the verified one-line fix (total + perPage - 1) / perPage landed and a draft PR followed in 4 turns (resumed session). No issue was closed.
    • New provider failure modes:
      • Workers AI returns HTTP 400 (code 3030) when its own tool parser can't parse the model's output (<tool_call>…). llmrouter now fails over on such a 400 (pushed to ✨ feature: llmrouter free-tier gateway waterfall + capacity pause for turn.Runner #18465). Plain 400s still don't fail over.
      • gpt-oss sometimes returns 200 with neither content nor tool calls, which is already treated as malformed.
      • The free-tier OAuth token expired mid-session (401 → auth cooldown → exit 75, correct).
    • pkg/codeindex hits its 64 MB text budget on the hive repo itself, so coverage is partial. Worth raising if a hosted coordinator indexes hive.

    Design answers from this

    • Open question 2 (merge in non-CLI paths): the evidence says no. A cheap model that writes a confident, broken PR needs a draft plus verification plus human review. Keep tool-hosted capped at drafts.
    • Executor guards over prompt rules: every instruction in the primer ("use search/replace", "don't touch workflows") was broken at least once. Every executor guard held.
    • Resume needs state: a stateless coordinator resuming a session must hand the model the work branch's diff, or it redoes the work. That shows the minimal Store content: envelope, executor evidence and the branch.

    Upstream PRs updated: #18465 (model-output 400 failover, coverage) and #18472 (coverage). All tests pass on all three upstream PRs. The remaining reds are the per-package coverage gate (being fixed) and the expected stacked-PR queue check on #18472.

  6. hanthor commented on Nov 16, 2026

    @hanthor
    ContributorAuthor

    Housekeeping: the pkg/hivetool PR is now #18477 (it replaces #18472). Prow auto-closed #18472 after I stacked it on a non-release base, and it couldn't be reopened. #18477 targets v6 directly and also carries #18467's single commit, which its tests need. Merging #18467 first shrinks #18477's diff to pkg/hivetool.

  7. hanthor commented on Nov 16, 2026

    @hanthor
    ContributorAuthor

    Update 4: admission modes and the Store, built in the fork and run live (2026-11-16)

    The read-path PRs have landed on v6: #18465, #18467 and #18477. One router fix found during the live runs below is open as #18511. Everything else here is in tuna-os#186 and does not change upstream's held status.

    §2 admission modes: pkg/extwork/posture.go

    • tool-hosted and github-mediated are now valid Admission.Authority.Mode values. Each mode has a Posture:

      Mode Starts work Hive executes writes Agent-mode ceiling Output trusted
      tool-hosted yes yes ISSUES_AND_PRS yes
      github-mediated yes no ADVISORY no
    • "A mode only raises the ceiling an adapter may declare" is enforced in the binding itself. An adapter has to list the mode via PostureDeclarer.Postures(). Otherwise Offer/Dispatch refuse it with ErrPostureUndeclared before anything is offered or persisted, and record that as a gate decline. The existing adapters (omp, vibekanban, claude-managed-agents) declare nothing, so they keep refusing both modes. ValidMode accepting the new names therefore changes no existing behaviour.

    • ClampMode(mode, requested) is a cap, not a grant. No admission mode yields merge (that is tested for all five modes). This is my proposed answer to open question 2: yes, cap at ISSUES_AND_PRS permanently.

    • VetMediatedPR is the outside-contributor bar for github-mediated output. A vendor-written PR needs green required checks, no protected paths (pushbroker.DefaultProtectedPaths), and an approving review from someone who is neither the author nor a Hive identity. Passing grants nothing; the PR only becomes eligible for the ordinary merge gates. This is the concrete shape behind open question 1.

    • hive-lite fix mode now runs as a tool-hosted admission. It is refused under report-only or github-mediated rather than silently downgraded.

    §7 Store: pkg/coordstate plus resumable sessions

    • Store is a compare-and-swap key/value interface (Get returns a version; Put succeeds only at the expected version). There are two drivers:
      • memory;
      • the GitHub Contents API, where the version is the blob sha. A stale-sha PUT returns 409, and a create over an existing file returns 422. That gives the per-file CAS §7 calls for. The driver bootstraps an orphan hive-lite-state branch, with no shared history with the code.
    • The ledger merges on flush. A remote store cannot take one write per model request, so a pass loads the ledger once, works in memory and flushes once. Same-day counts add up and the later cooldown wins, under CAS with retry. Two overlapping passes therefore neither lose nor double-count spend (tested).
    • Sessions checkpoint on every exit:
      • The checkpoint holds the envelope plus executor memory: evidence spans, duplicate fingerprints, write-side head/PR state and the outcome.
      • The next run resumes an unfinished checkpoint only if it has the same admission mode and fix flag.
      • A save conflict is reported, never overwritten.
    • The canary never reaches the store. The system prompt is emptied before writing and rebuilt with a fresh canary on resume, and any echo is replaced byte-for-byte in the encoded checkpoint. The live checkpoint contained 0 occurrences.

    Live run: 4 processes, 1 session (private sandbox repo, Workers AI free tier, -state github)

    Pass Setup Result
    1 glm-4.7-flash, daily_cap: 3 3 turns, then exit 75 (paused); checkpoint and ledger written
    2 same config exit 75 immediately: the persisted ledger enforced the cap across processes
    3 fresh provider entry, gpt-oss fallback resumed at turn 3, read and searched to turn 11. gpt-oss's task.complete was cut off mid-string, then every request failed with HTTP 400 (bug below)
    4 with #18511 resumed at turn 11, completed in 1 request, 3/3 citations verified against code read in passes 1 and 3

    The state branch ended with 6 commits: one orphan init plus one per write. The ledger file showed the merged per-provider spend across all passes.

    Bug found (#18511): the executor correctly refused the truncated arguments. The router, however, resent those bytes as history, and Workers AI rejected every later request: code 3030, Unterminated string … column 14, which is where the summary value begins. The fix:

    • wrap invalid history arguments as {"invalid_arguments": "<raw>"};
    • fail over when finish_reason is length and a tool call's arguments are invalid;
    • add a per-provider max_tokens.

    Without the Store, pass 3's failure would have discarded 11 turns of grounded reading. With it, the session cost one more request.

    Still unbuilt

    • Families A (chat bridges), B (vendor sessions under the new modes) and E (MCP server).
    • The D1 and Netlify Store drivers. The interface is ready for them.

    Family E's agent-driven mode is next in the fork. It reuses hivetool.Executor as the MCP tool surface, with tool-hosted admission.

  8. hanthor commented on Nov 16, 2026

    @hanthor
    ContributorAuthor

    Update 5: Family E (Hive as an MCP server), built in the fork and run with real clients (2026-11-16)

    §3a's agent-driven mode is now a working server: pkg/hivemcp + cmd/hive-mcp in tuna-os#186. An MCP-capable agent connects to Hive and spends its own inference on Hive work. Hive holds no model credential, the client holds no GitHub credential, and every tool call is executed by hivetool.Executor under a tool-hosted admission.

    Shape

    • Transport. Streamable HTTP, POST only, one JSON-RPC request per POST, JSON responses, notifications answered 202. This is the same shape as the dashboard's existing public-knowledge MCP endpoint, so there is no new protocol code path.
    • Identity. Bearer tokens are stored as sha256 and map to a contributor principal and agent mode. The effective mode is ClampMode(tool-hosted, tier), so merge is never available, and without a configured writer there are no write tools at all. Sessions are bound to the principal that opened them: another principal gets 403, an unknown session 404.
    • Offer before context, matching the contributor protocol:
      1. hive_next_task returns only the issue number and title.
      2. hive_accept_task delivers the ioscan-screened brief; hive_decline_task skips the offer.
      3. Repo tools are refused until a task is accepted.
    • Tools are hivetool.Definitions(mode) with MCP-safe names (repo.read_file → repo_read_file). The evidence gate applies exactly as in Family C: an ungrounded task_complete is refused.
    • Stateless hosting. Sessions (executor evidence and duplicate memory) and per-issue claim leases live in a coordstate.Store under compare-and-swap, so any request can land on any instance. A lapsed claim taken by someone else ends the old holder's task before its next call executes. The durable record of the outcome belongs on GitHub (OnOutcome), consistent with §7.
    • Per-principal call budget.

    Live runs (private sandbox repo, real Claude Code as the client)

    Run Client Result
    1 claude -p (haiku) restricted to the hive MCP tools took the offer, investigated, task_complete with 4/4 citations verified: 9 turns, 15 s, $0.006 of the client's inference, $0 of Hive's
    2 two clients concurrently, two tokens, sessions on a GitHub state branch each claimed a different issue and both completed (5/5 and 4/4 verified), $0.013 combined

    Run 2 first failed for one client, which surfaced a GitHub storage fact worth recording in §7. The Contents API answers 409 when a concurrent commit to a different file moved the branch head, not only on a stale sha. The per-file CAS is real, but a 409 alone does not mean this key changed. ContentsStore now re-reads the key and retries with backoff when the key's version still matches; only a changed version is a conflict.

    Cost of that driver: one commit per write (52 commits for two short MCP sessions). That is fine for light use and the wrong backend for a busy server. D1 (or any store with real row versions) is the production driver; the interface is ready for it.

    Answer proposals for the open questions

    • Q4 (MCP server as the first transport for contributor compute): yes, based on this. It reuses the exact tool surface, gate and evidence check of Family C. It needed no bridge, scraping or completion heuristics, and any MCP client works unmodified.
    • Q3 (where the executor lives): pkg/hivetool, now shared by the Family C runner and the Family E server, as the RFC suggested.

    Family E's sampling mode (Hive drives a connected client as a Family C provider) is not built. It needs a session that streams back to the client, which this POST-only server deliberately avoids.

    Tests: in the fork's v2-tests run on the branch, pkg/hivemcp (90.3%), pkg/hivelite (92.7%) and pkg/extwork (97.5%, with the posture tests) pass. #18511 (router fix) is green upstream.

  9. hanthor commented on Nov 16, 2026

    @hanthor
    ContributorAuthor

    Update 6: a D1 store driver, measured against the GitHub branch; and what MCP clients actually support (2026-11-16)

    Everything here is in tuna-os#186.

    §7 Store: coordstate.D1Store

    • Each key is a row (key, value, version), written through the D1 HTTP query API, so it works from a hosted CI runner as well as from inside a Worker.
      • Create is INSERT … ON CONFLICT DO NOTHING.
      • Update is UPDATE … WHERE key = ? AND version = ?.
      • The changed-row count decides success or ErrConflict.
    • hive-lite and hive-mcp now take -state d1:<account>/<database> alongside github / github:owner/name@branch.

    Measured live on a free D1 database with read replication off, so compare-and-swap reads hit the primary, and compared with the Contents API driver:

    GitHub state branch D1
    CAS semantics (create-only, stale version, missing key) ✅ ✅
    get+put round trip from one host ~1.0 s ~0.86 s
    concurrent increments of one key 5 → exactly 5 (6.9 s) 20 → exactly 20 (10.7 s)
    two overlapping ledger flushes exact sum exact sum (3 + 4 = 7)
    unrelated-file contention 409 on a concurrent write to another file (retry needed) none, per-row
    history one commit per write: 52 commits for one two-client MCP run none: 4 rows, ~32 row writes for the same run

    The same two-client Family E run on D1 had both clients claim different issues and complete, for $0.007 combined.

    Proposed §7 wording:

    • The GitHub state branch is the zero-setup default for light, cron-paced coordinators.
    • D1 (or any store with row versions) is the backend for anything interactive, such as an MCP server.
    • Hot-key contention is slow on both, so one key per session or claim, never a shared counter.

    Caveat I have not verified: D1's HTTP API goes through the general Cloudflare API rate limit (from memory, 1,200 requests per 5 minutes per user). A Worker binding avoids it. Worth confirming before sizing an HTTP-API deployment.

    §3a sampling mode: Claude Code does not offer it

    I captured the initialize request Claude Code 2.1.319 sends to an MCP server:

    • Capabilities: roots and elicitation (form and url). There is no sampling.
    • Protocol 2025-11-25. hive-mcp answers 2025-06-18, and negotiation handled the mismatch.

    So "sampling mode: a connected client as a Family C provider" cannot use the most common coding-agent client today. I suggest:

    • keep sampling as opportunistic;
    • make agent-driven the Family E design;
    • note elicitation as the more useful client capability. Hive could ask the connected human to confirm before pr_create or a label change, which is the human-in-the-loop step §3a wanted sampling's approval for.

    Tests: pkg/coordstate (D1 driver plus Open) passes in the fork's v2-tests run on the branch. #18511 is fully green upstream, after a re-run of two contributor-image builds that failed on a GitHub Actions cache BlobNotFound.

  10. clubanderson commented on Nov 17, 2026

    @clubanderson
    Member

    Thanks for the measured runs, they answer more than most RFCs do. Proposal: accept with scope cuts, targeting v6, where the router, executor and tool classes already landed. Phase 1 wires them as a default-off, report-only advisory engine over existing Model Gateways, shadow first. Phase 2 is a read-only MCP server at ADVISORY. Defer the write tools, vendor sessions, chat bridges and serverless stores until phase 1 shows advisory quality over a few weeks. Decision on the open questions: vendor agents never write to GitHub (no github-mediated mode), all writes stay with the Hive App, and tool-hosted is capped permanently at ISSUES_AND_PRS. Free tiers that train on inputs stay off for private repos by default.

  11. hanthor commented on Nov 17, 2026

    @hanthor
    ContributorAuthor

    Thanks, @clubanderson. Accepted as scoped. Agent-side GitHub writes were the wrong direction; keeping all writes with the Hive App is the boundary. Here's how we'll proceed:

    Decisions adopted

    • No github-mediated mode. It's dropped from the RFC, and the posture, the PR vetting and their tests are being removed from the tuna-os fork.
    • Vendor agents never write to GitHub, and all writes stay with the Hive App. The fork's experimental write paths (hive-mcp -write, hive-lite -fix/-verify, and the Contents-API checkpoint store in the triage workflow) are being removed, not just turned off.
    • tool-hosted stays capped at ISSUES_AND_PRS permanently, with a test that no path can raise it.
    • Free tiers that train on inputs are off for private repos by default. The router gains a per-provider trains_on_inputs flag, and those providers are skipped for private repos unless an operator explicitly opts in.

    Plan on v6

    1. Phase 1: wire llmrouter, pkg/hivetool (read executor) and the toolapprove classes as a default-off, report-only advisory engine over the existing Model Gateways, shadow first. It produces advisory output alongside the normal lanes and never acts. The fix in 🐛 llmrouter: sanitise invalid history tool args, fail over on truncated calls #18511 (truncated tool args) is a prerequisite.
    2. Phase 2: a read-only MCP server at ADVISORY, offering read tools only and no write tool definitions.
    3. Deferred until phase 1 shows advisory quality over a few weeks: write tools, vendor sessions, chat bridges and serverless stores.

    I'll update the RFC body to this scope and open the phase 1 PR against v6 as default-off.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    help wantedDenotes an issue that needs help from a contributor. Must meet "help wanted" guidelines.holdkind/designCreated by Hive for agent-filed issue provenanceproposalRFC / design proposal for discussion

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions