Skip to content

armgit / avibe

Public Imported from GitHub
0

Make your computer a home for your AI partner. Avibe is the local-first Agent OS: Vibey, its built-in AI partner, works out of the box, and Claude Code, Codex & OpenCode run unchanged beside it — reach them from your browser, phone, or any chat app.

4.6 KB
Raw Blame

Agent core contracts

Status: draft, 2026-10-02. Shapes and semantics shared by the lanes in ../avibe-agent-core.md §7. A contract is frozen on master before the lanes that depend on it fork; after that, a change needs orchestrator approval and lands here first.

ID Contract Producer → consumer Files Frozen before
C-1 Canonical message model and cross-provider rules ai → agent, harness, adapter message.schema.json, cross-provider.md P1
C-2 Provider adapter interface and stream events ai → agent provider.md, provider-event.schema.json P1
C-3 Loop control: hooks, directives, steer, follow-up, fork agent → adapter, harness, tests loop-control.md P1
C-4 Agent event stream and its mapping to Avibe outputs agent → adapter agent-event.schema.json, loop-control.md §6 P2
C-5 Transcript rows, context_seq, projection, fork adapter ↔ harness transcript.md, transcript-rows.schema.json P2
C-6 Model Hub consumer extension Model Hub → adapter model-hub-consumer.md, hop-resolution.schema.json P1
C-7 Tools, output governance, job handle, environment block, project instructions tools → agent, adapter tools.md, job.schema.json P1
C-8 Backend registration catalog → every backend list backend-registration.md P2
C-5, C-7 Recovery invariants for jobs, tool calls, and delivery, with owners and proofs tools, loop, adapter recovery.md P1
C-9 Context management: tiers, trigger, cut, forked checkpoint, overflow ladder, guards harness → agent, adapter context.md; rows in transcript-rows.schema.json P3 (frozen 2026-10-04)
C-10 Fork: fork point, side turn, fork Session, lineage, capability, merge-back harness, agent, storage, service → C-9, adapter fork.md Phase 1 (frozen 2026-10-10)

Conventions:

  • WF-1 (2026-10-25, coordinated unreleased Model Hub v21) extends C-1 with WebFetchRecord, discriminated only by outer tool_name: web_fetch. Its one ordinary text block equals the canonical untrusted frame (≤48,000 UTF-8 surrogatepass bytes); nullable metadata, fixed budget method, diagnostics and strict consistency are specified in ../web-fetch.md §4. Search/native records are unchanged. Executor origins accept fetch_api and local_fetch, not assistant-model origins. Attempts accept local.

  • C-6 recognizes function-only fetch facts (native and replay both unsupported). WF-3 enables declaration and execution through the shared WEB_FETCH_ACTIVE switch; records, activity and usage remain readable even when the switch is false. The coordinated reader/activation release decision is in ../web-fetch.md §8. #2920's released rc4 reader preserves the full ordinary quotation when discarding unknown hosted metadata. Config and usage downgrade writes are intentionally lossy as disclosed in the owning plan.

  • JSON Schema draft-07, like ../model-hub-contracts/. Python implementations use dataclasses; the schemas describe the serialized form, which is what crosses a lane boundary or reaches disk.

  • Persisted shapes carry "version": 1. Readers accept every released version (persisted-shape rule).

    • C-1 clarification (approved 2026-10-22): Anthropic deferred hosted calls use existing v1 use-only and result-only fragments across immutable responses. Pairing/replay semantics are in cross-provider.md; released-reader round-trips cover v3.2.2 and gh-v3.2.3rc2. No wire-shape version change.
  • Field names are snake_case, except the tool parameters in C-7, which keep Pi's names (oldText, newText, replaceAll).

  • Every statement about existing code names its file and was checked against master; fields that already exist keep their meaning (a new meaning gets a new field).

  • Contracts fix shapes that cross a lane boundary and the invariants each lane must prove. Mechanisms inside one lane (launch handshakes, retry loops, chunking) are that lane's code and tests, not contract text.

  • Protocol names use Model Hub's vocabulary, extended by C-6: anthropic, openai_chat, openai_responses, google.