Repository navigation
Description
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:
- ✨ feature: llmrouter free-tier gateway waterfall + capacity pause for turn.Runner #18465
pkg/turn/llmrouter, with the capacity pause, offered-tools capability set andDigestCompactor; - 🐛 fix: toolapprove classifies hive-tool/v1 names so AgentMode gates apply #18467
toolapproveclasses forhive-tool/v1; - ✨ feature: hivetool read-only hive-tool/v1 executor with evidence gate #18477
pkg/hivetoolread executor and evidence gate.
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-mediatedmodes (§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-mediatedand 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:
- Stateless OpenAI-compatible APIs with free tiers (Groq, OpenRouter
:free, Gemini via AI Studio, Cloudflare Workers AI, Cerebras trial). - Vendor cloud agent sessions (Claude Managed Agents, Claude Code routines, GitHub Copilot cloud agent).
- Always-on chat/MCP agents (OpenAI dots via an MCP Events bridge or a Matrix bridge).
- Contributor relays (the existing
contributor-relayWebSocket,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.JournaledExecutorwith a key fromturn.DeriveIdempotencyKey. Per RFC [v5] RFC: re-entrant conversation-as-state agent turn model (durable, handoff-able agents) #4002 §"Ordered operations", a model-suppliedcall_idis 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, thentask.complete. Hive executes every tool exactly as intool-hostedmode. 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.Runnerkeeps 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
Ledgerinterface so a stateless host can keep them in its store. - Exhaustion is not failure: the client returns an error matching new
turn.ErrInferenceCapacity, andRunner.Stepparks the session aspausedwithout consuming a turn (today any LLM error marks the sessionfailed). - 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-IDandGET /api/messages/{id}/responsesrecover 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, soCancelFacts{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, elsem.replaceedit-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/syncinstead, 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
shaprecondition (409 on mismatch) per state file.PATCH /git/refs force=falseonly 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)
- Family C core:
pkg/turn/llmrouterand theErrInferenceCapacitypause (companion PR); hive-toolToolExecutorover the GitHub API reusing pushbroker/AuthorizePROpen;tool-hostedmode. - Coordinator pass + Store with the D1 and state-branch drivers; summarising compactor; governor turn budget.
- Family B: promote
claude-managed-agentstotool-hosted; addcopilot-cloudandclaude-routinesundergithub-mediated(after the token-identity question is settled). - Family A: dots-bridge adapter, then the Matrix adapter.
- Family E: Hive MCP server (agent-driven mode first, then sampling as a Family C provider).
Open questions
- Is
github-mediatedacceptable at all given the vendor writes as a user identity (Routines, Copilot)? Or should those engines stayreport-onlyuntil a Hive-owned identity is possible? - Should
tool-hostedcap atISSUES_AND_PRSpermanently, keeping merge out of non-CLI paths entirely? - Should the hive-tool
ToolExecutorlive inpkg/turnor in a newpkg/hivetoolshared by extwork adapters (Managed Agents custom tools, dots MCP)? - 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.
- 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.Persisterhas 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:
- Cerebras is now a trial, not 1M tokens/day.
- Codex Cloud has no task API (Codex Cloud: per-task model and reasoning effort, and scheduled tasks in a cloud environment openai/codex#47660 asks for something else).
- Copilot does not support installation tokens.
- Routines and Copilot have no cancel; Routines has no status API.
- Managed Agents
limitedis a networking setting (defaultunrestricted) andself_hostedis an environment type. EnsureClosingIssueLinkcites ✨ Link non-default-branch fix PRs to their issues so the issue list shows the PR icon #11888.- [ci-maintainer] GitHub App installation lacks 'workflows: write' permission — agents cannot open PRs touching .github/workflows #4677 is the
workflows: writeApp permission, not a pushbroker rule. - Routing is a map in
manager_routing.go, and tmux I/O lives interminal.go. - The relay holds a persistent outbound WebSocket and does not poll.
- Upstash's limit is monthly.
git/refsis not a compare-and-swap.- The free-LLM list moved, and its mirror is stale.
Activity
hanthor commentedon Nov 16, 2026
First library slice (Family C, default-off and unwired): #18465
pkg/turn/llmrouterwith the 429 waterfall, plus theErrInferenceCapacity→pausedhandling inturn.Runner.♻️ llmrouter: converge on Model Gateways; fixes from live Workers AI …
hanthor commentedon Nov 16, 2026
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:crux/inference.ResolveGatewayAuth, so key env/file and watsonx IAM minting match the gateway path.config.LiteLLMChatCompletionsURL, the rule the translator and Test Connection share.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:
prices: {input: 0, output: 0}, so spend reads $0 and not "unknown". That needsturn.LLMResponseto carry usage.:freemodels can come fromcrux/openrouter.CachedPublicModels(zero pricing) instead of an external list.Open question for the gateway owners: the shared URL rule appends
/v1/chat/completionsunless 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 #18441Measured, not inferred:
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-formedtool_calls. This closes the RFC's "unconfirmed" row.issue.read, llama-4-scout replied in prose with no tool call. Withissue_readit called the tool. Strict OpenAI servers reject dotted names outright. The router now maps names to a wire-safe form and back.content: nullon an assistant tool-call message makes gpt-oss-120b on Workers AI return 400. The router now sends"".!at roughly 4k tokens of context. The router now treats that as malformed and fails over (it fired once in a later run).toolapprovedoesn'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.[task__complete(summary=…)]as prose, and the Runner marked the sessioncompletedwith no result. Requirement: a tool-hosted session ends only ontask.complete/task.abort, and max-turns or a prose answer must not count as completed. A fencedhive-tooltext fallback parser is worth having even for native-tool models.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.git grepover v6 it found the right files in 7 turns. Requirement:repo.search_codemust be backed by a Hive-owned index (pkg/codeindexor a maintained clone), not GitHub search.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 rebasewhere 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.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.✨ turn: offered tools are the capability set; router maps history nam…
✨ hivetool: read-only hive-tool/v1 executor with evidence gate (#18464)
✨ turn: DigestCompactor pins the task and digests dropped tool calls (#…
hanthor commentedon Nov 16, 2026
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:
pkg/turn:llmrouterbuilds on Model Gateways;ErrInferenceCapacity→paused;WithToolChoice;DigestCompactor.toolapproveclasses forhive-tool/v1. Live: reads now auto-approve, and ADVISORY writes are denied at L5/L6.pkg/hivetoolread executor (stacked on 🐛 fix: toolapprove classifies hive-tool/v1 names so AgentMode gates apply #18467):pkg/codeindexsearch adapter;ParseFenced;New measurements
tool_choice: "required"is honoured by llama-4-scout and glm-4.7-flash. gpt-oss-120b ignores it and still reportsfinish_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.task.complete, gpt-oss calledrepo.search_codeandrepo.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.task.completewas refused; it then calledtask.abort("relevant code not found") for 204 neurons. glm-4.7-flash's citation, from a search hit, verified.task.complete, grounded, lists what it couldn't verifyglm-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.
task.complete, so a turn budget plus a forced finish is the policy that delivers results, and the compactor is a cost saving.DigestCompactornever produces one.Still blocked on discussion (not started, by design)
Write tools (
repo.patch_files,pr.createthrough pushbroker andAuthorizePROpen), thetool-hostedandgithub-mediatedadmission modes, the coordinator pass andStore, and Families A, B and E. These are the RFC's open questions.🔒 toolapprove: classify hive-tool/v1 names so mode gates apply (#18464)…
✨ hive-lite: report-only free-tier triage CLI + workflow (RFC hivecom…
✨ hivetool: tool-hosted write side — repo.patch_files and draft pr.cr…
hanthor commentedon Nov 16, 2026
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 aworkflow_dispatchworkflow on a free hosted runner:GatewayConfigentries;pkg/codeindex;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.repo.patch_files, draftpr.create) behind executor-side guards: push-capable mode, pushbroker protected paths, exact-once search/replace, a whole-file-rewrite guard, an optional pre-commitVerifier, closing-keyword neutralisation, and a Hive-written verification record in the PR body.Live results
tool-hostedneeding executor-side guards and verification, not just approval.(total + perPage - 1) / perPagelanded and a draft PR followed in 4 turns (resumed session). No issue was closed.<tool_call>…).llmrouternow 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.pkg/codeindexhits 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
tool-hostedcapped at drafts.Storecontent: 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.
hanthor commentedon Nov 16, 2026
Housekeeping: the
pkg/hivetoolPR 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 targetsv6directly and also carries #18467's single commit, which its tests need. Merging #18467 first shrinks #18477's diff topkg/hivetool.✨ feature: llmrouter free-tier gateway waterfall + capacity pause for…
✨ feature: hivetool read-only hive-tool/v1 executor with evidence gate (
✨ extwork: tool-hosted and github-mediated admission postures
✨ hive-lite: CAS state store, resumable checkpoints, persisted ledger
hanthor commentedon Nov 16, 2026
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.gotool-hostedandgithub-mediatedare now validAdmission.Authority.Modevalues. Each mode has aPosture:tool-hostedISSUES_AND_PRSgithub-mediatedADVISORY"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(). OtherwiseOffer/Dispatchrefuse it withErrPostureUndeclaredbefore 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.ValidModeaccepting 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 atISSUES_AND_PRSpermanently.VetMediatedPRis the outside-contributor bar forgithub-mediatedoutput. 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-hostedadmission. It is refused underreport-onlyorgithub-mediatedrather than silently downgraded.§7 Store:
pkg/coordstateplus resumable sessionsStoreis a compare-and-swap key/value interface (Getreturns a version;Putsucceeds only at the expected version). There are two drivers:hive-lite-statebranch, with no shared history with the code.Live run: 4 processes, 1 session (private sandbox repo, Workers AI free tier,
-state github)daily_cap: 3paused); checkpoint and ledger writtentask.completewas cut off mid-string, then every request failed with HTTP 400 (bug below)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 thesummaryvalue begins. The fix:{"invalid_arguments": "<raw>"};finish_reasonislengthand a tool call's arguments are invalid;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
Family E's agent-driven mode is next in the fork. It reuses
hivetool.Executoras the MCP tool surface, withtool-hostedadmission.✨ hive-mcp: Family E agent-driven MCP server
hanthor commentedon Nov 16, 2026
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-mcpin 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 byhivetool.Executorunder atool-hostedadmission.Shape
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.hive_next_taskreturns only the issue number and title.hive_accept_taskdelivers the ioscan-screened brief;hive_decline_taskskips the offer.hivetool.Definitions(mode)with MCP-safe names (repo.read_file→repo_read_file). The evidence gate applies exactly as in Family C: an ungroundedtask_completeis refused.coordstate.Storeunder 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.Live runs (private sandbox repo, real Claude Code as the client)
claude -p(haiku) restricted to the hive MCP toolstask_completewith 4/4 citations verified: 9 turns, 15 s, $0.006 of the client's inference, $0 of Hive'sRun 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.
ContentsStorenow 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
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-testsrun on the branch,pkg/hivemcp(90.3%),pkg/hivelite(92.7%) andpkg/extwork(97.5%, with the posture tests) pass. #18511 (router fix) is green upstream.hanthor commentedon Nov 16, 2026
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(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.INSERT … ON CONFLICT DO NOTHING.UPDATE … WHERE key = ? AND version = ?.ErrConflict.hive-liteandhive-mcpnow take-state d1:<account>/<database>alongsidegithub/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:
The same two-client Family E run on D1 had both clients claim different issues and complete, for $0.007 combined.
Proposed §7 wording:
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
initializerequest Claude Code 2.1.319 sends to an MCP server:rootsandelicitation(formandurl). There is nosampling.2025-11-25.hive-mcpanswers2025-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:
pr_createor a label change, which is the human-in-the-loop step §3a wanted sampling's approval for.Tests:
pkg/coordstate(D1 driver plusOpen) passes in the fork'sv2-testsrun on the branch. #18511 is fully green upstream, after a re-run of two contributor-image builds that failed on a GitHub Actions cacheBlobNotFound.clubanderson commentedon Nov 17, 2026
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.
hanthor commentedon Nov 17, 2026
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
github-mediatedmode. It's dropped from the RFC, and the posture, the PR vetting and their tests are being removed from the tuna-os fork.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-hostedstays capped atISSUES_AND_PRSpermanently, with a test that no path can raise it.trains_on_inputsflag, and those providers are skipped for private repos unless an operator explicitly opts in.Plan on v6
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.ADVISORY, offering read tools only and no write tool definitions.I'll update the RFC body to this scope and open the phase 1 PR against v6 as default-off.
✨ Shadow advisory engine over Model Gateways (default off) (#18651)