OXYGENHUB

Spec: the AI assistants design, §13.4 d4792b4a4629

Assistants at site, organisation and repository level with a merged
prompt, encrypted tokens, review requests recorded via the assistant,
and drafted proposal descriptions. refs #97
Author
Andy McCall @andymccall <[email protected]>
When
· 2026-10-04 15:16 UTC
Signature
✔ signed by Andy McCall
Hash
d4792b4a4629fc1804abf928bb72230e33665f87688f9a5b8c885bd3e2c19f75
Depends on
5ea4872f23e8 93be9ce4653e
Depended on by
155cab142b63 d1727c573f30 7d2eb590051f e71846aa07b9
In bookmarks
api-unknown-fields cancel-landed-runs clear-waiting close-proposal-140 diffusion-pin-bookmark draft-ready image-check job-waits main oh-comment-body-file proposal-list-fast run-one-job wiki-says-so
In tags
v0.4.1 v0.4.2 v0.5.0 v0.5.1 v0.5.2 v0.6.0 v0.6.1 v0.7.0 v0.8.0 v0.9.0 v0.9.1 v0.9.11 v0.9.15 v0.9.16 v0.9.19 v0.9.2 v0.9.20 v0.9.21 v0.9.22 v0.9.23 v0.9.24 v0.9.3 v0.9.4 v0.9.5 v0.9.6 v0.9.7 v0.9.8 v0.9.9
Edits
1 atom, 0 tree operations, 1 file

Browse the tree at this change

hide whitespace changes
modified docs/spec.md +11 −0
… 
533 unchanged lines
534 534 
- *Costs.* One microVM per open workspace: 2 vCPU and 4 GB by default, from the runner's capacity like any job, so open workspaces compete with pipeline jobs; a runner label `workspace` keeps them on runners meant for it. Idle stop at 30 minutes keeps the fleet small.
535 535 
- *Open questions.* Whether the Oxygen VCS extension should talk to the microVM's `oxy` (simplest; works offline in the VM) or to the hub's API (no `oxy` in the VM, but a second code path for every operation): the first. Whether a stopped workspace's overlay should be kept for a day so an unpushed edit is not lost: probably yes, as a tarball artifact of the job, restored on reopen. Whether to allow terminals: yes, it is the point.
536 536 

    

  
    

      
      537
      +
      
### 13.4 AI assistants (planned, design 2026-10-04)

    

  
    

      
      538
      +
      

    

  
    

      
      539
      +
      
An **assistant** is a chat-completion endpoint the hub may ask to review a proposal or draft its description (oxygenhub#97). Assistants are configured at three levels and combined downwards:

    

  
    

      
      540
      +
      

    

  
    

      
      541
      +
      
- **Where.** Administration (site), an organisation's settings, a repository's settings each hold a list of assistants: name (`Claude`, `Antigravity`, `ChatGPT`, `DeepSeek`, …), endpoint URL, API shape (`chat-completions` or `anthropic-messages`), model, extra headers, the token, and an *enabled* switch. Each level also holds a **prompt**. A repository sees the assistants of its organisation and of the site beside its own; an assistant disabled at an outer level is off for everything inside it, whatever an inner level says. The effective prompt for a call is the site's, then the organisation's, then the repository's, each under a heading, so a project adds to what the site says rather than replacing it, and each settings page shows the prompt it inherits above its own.

    

  
    

      
      542
      +
      
- **Secrets.** Tokens are kept encrypted at rest (ChaCha20-Poly1305 with a key in the data directory's `keys/`, beside the cookie key), shown masked, and never returned by the API.

    

  
    

      
      543
      +
      
- **Request review.** The proposal page's Reviewers menu lists the enabled assistants beside people. Asking one queues a worker task: the hub builds the context (the proposal's title and description, the diff of each changed file, trimmed to a size budget, the effective prompt), calls the endpoint, and records the answer as a review of verdict `comment` whose author is the person who asked and whose **via** is the assistant, shown as "andymccall via Claude" with an `agent` badge, exactly as agent-signed changes are shown (§6). An assistant never approves: approvals count only people. The event and the audit log record who asked which assistant; the proposal's author is told as for any review.

    

  
    

      
      544
      +
      
- **Draft the description.** On a new or open proposal, "Draft with …" asks an assistant for a description from the changes and puts it in the editor for the requester to edit before saving; nothing is saved by the assistant itself.

    

  
    

      
      545
      +
      
- **Limits and failure.** One request per assistant per proposal at a time, a per-repository rate limit, a 60-second call timeout, and a context budget (characters) per assistant; a failed call leaves an event ("Claude did not answer: …") and no review.

    

  
    

      
      546
      +
      
- **API.** `/repos/{o}/{n}/proposals/{n}/review-requests {"assistant": NAME}` and the settings endpoints mirror the pages. Hub actions by an assistant are attributed "ASSISTANT via WHO" everywhere, so a project can require that a human has approved regardless of what an assistant said.

    

  
    

      
      547
      +
      

    

  
    

      537
      548
       
      
## 14. Git interoperability

    

  
    

      538
      549
       
      

    

  
    

      539
      550
       
      
A repository may enable a **Git mirror**: on every landing on selected bookmarks the hub runs `oxy git export` into `<data>/mirrors/<owner>/<name>.git` and serves it read-only over Git's smart HTTP protocol at `/{owner}/{name}.git` (implemented with the `git` binary's `http-backend` behind the hub's authorization, since reimplementing pack negotiation is not the product). This lets GitHub Actions runners, IDEs and tooling that only speak Git read hosted Oxygen repositories. Pushing to a mirror is refused with a message pointing at `oxy`.

    

  
    

      
      
      …
      
144 unchanged lines