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.
Agent loop (P1, C-9 in P3)
The change contract is C-3 plus C-5 projection from docs/plans/agent-core-contracts/,
and C-9 context management (context.md) when the Agent has a ContextConfig.
Foundation types are unchanged.
Integration
Import Agent from agent.loop, input/snapshot/hook types from agent.hooks,
ModelRouter and ModelSelection from agent.models, and the shared
ModelCapabilities from ai.provider.
The adapter supplies the Session id, working directory, explicit environment,
rebuilt system prompt, providers, transcript store, and job host.
agent = Agent(
session_id=session_id, models=router, tools=[], hooks=hooks,
store=store, jobs=job_host, cwd=cwd, env=env, system=system,
)
# Job-backed tools receive this exact wrapper, not the unwrapped host.
agent.set_tools(build_tools(jobs=agent.jobs))
async for event in agent.run(AgentInput(message_id, rendered_input), turn_id=turn_id):
await deliver(event)
# Continue from committed context without writing another input row.
async for event in agent.resume(
AgentInput(message_id, rendered_input),
turn_id=turn_id,
turn_inputs=source_turn_input_sequences,
):
await deliver(event)
# Return accepted but unconsumed inputs after an early end, abort, or error.
pending = await agent.take_pending_inputs()
resume(input, turn_id=..., turn_inputs=...) reruns the loop from the committed
transcript without consuming input; the input is only provided to before_run
for setup compatibility. A fresh Agent should pass the source Turn's committed
input sequence numbers in turn_inputs so context compaction pins only that Turn;
an Agent continuing its own run may omit it and preserves its in-memory set.
It is subject to the same one-active-run and pending-input ownership rules as
run. The adapter decides whether a failed run is safe to resume and owns any
retry budget.
(harness/context.py); in v1 such an Agent takes no user hooks (a configuration
error). Every conversation request then goes through one pipeline: projection,
budget() on that request, the C-9 stage (stop, clear, checkpoint at T, overflow
ladder), and the provider;
a stage step that changes the context rebuilds the request. Compaction is automatic
and invisible; there is no manual entry point. Without a config nothing changes and
an overflow ends the run context_exhausted. The ContextHost renders
the <earlier-record> hint and the state a checkpoint carries; the store adds
append_audit (non-context audit rows), append_payloads (one transaction per C-9
transition), append_response(request=...) (the estimate anchor), and each row's
created_at. The SQLite and adapter stores implement all of it, and
tests/test_transcript_store_contract.py runs the same tests on them and on the
in-memory store. Every response, a checkpoint turn's included, is admitted in the
model call before anything acts on it. The ordering and ownership invariants are in
context.md section 10.
steer and follow_up are async and return whether the active run accepted the
input. False means the adapter keeps the persisted input in the P3 queue.
An accepted input remains owned by the Agent until consumed or returned by
take_pending_inputs(). Early termination preserves those queues, and a new run
is refused until they are collected. A returned input belongs to the Turn that
accepted it and is never re-queued as a new P3 Turn (recovery.md T3): after a
run that ended by design (a terminating tool or a hook end), the Avibe adapter
runs again for the returned inputs within the same Turn; after a stop or an
error, it admits them into the context, and they share the Turn's outcome.
abort, set_tools, and snapshot are synchronous on the same event loop.
Only one run can use an Agent at a time. The adapter remains responsible for
excluding multiple Agent instances writing the same Session.
The router resolves endpoint and capabilities before each model attempt;
provider_for(protocol) selects transport after request hooks have run.
An explicitly tool-incapable route is refused during preflight, before hooks or
input consumption. The run yields a clear error and terminal event without a
provider request. Unknown tool support still sends tools. Unknown/false image
and reasoning support is disabled; reasoning also requires a declared effort.
The configured output budget defaults to 8,192 and is capped by the provider's
maximum (8,192 when unknown); that cap is C-9's O, the request's max_tokens.
The other C-9 limits (W is 128,000 when unknown) and the estimate come from
harness.context.budget, evaluated on each final request on the route resolved
for it.
The shared nullable source capabilities are not changed into guessed values.
Before-model rewrites affect a detached request only, including endpoint headers.
The router's cached selection is never mutated. Tools execute against the
registry captured for that request, restricted to its advertised names.
A before-run setup affects that run only; set_tools changes the configured
set as well as the next request of an active run.
Hooks subclass Hooks, override async methods, and mutate RunContext.state
with exact JSON data (string-keyed dicts, lists, JSON scalars, finite numbers).
Non-JSON Python values are hook errors, never silently coerced. Representation
comparison distinguishes booleans, integers and floats and avoids duplicate
state rows. Rewrites compose in registration order; the first Deny or
End stops that hook chain. State changes append versioned agent_state rows
at commit points. A snapshot describes committed context and committed state.
The store/adapter owns fork ancestry; the engine does not copy parent rows.
AgentError.kind is the adapter's stable error discriminator.
AgentError.message is engine/provider diagnostic detail, never display copy.
The adapter owns Session language, maps kinds to vibe/i18n messages, and tests
English/Chinese rendering at its delivery boundary. Model-facing tool result
text is separate from localized user-facing error delivery.
The stable empty_response kind means a tool-free final response had no
non-whitespace reply text (including thinking-only output); the adapter must
localize that error rather than deliver a silent success.
Invariants and evidence
- Responses are committed before
MessageCommitted, and tool results beforeToolFinished. Hook state is written before the associated context entry, so a failed state write cannot hide a committed reply. A later input-write failure still announces prior committed rows. Event sequences start at zero per Turn and increase strictly; their identity field isturn_id. - Finality is decided with input admission locked before inserting the response.
A final response closes admission; a competing late steer is refused.
A final refusal/safety stop retains the provider's text. Without a visible
reply, it still commits a final result, then emits a typed error and ends.
Other empty successful finals likewise stay committed, but emit
empty_responseand end as error. A received terminal is never retried. Empty non-final responses with queued inputs can still continue to a reply; tool calls, explicit hook end, and tool termination retain their contracts. A tool-free reply that queued input made non-final, and that did not stop at its output limit, is committedsuperseded: a completed reply, stored as aresultin the same transaction and shown as one, unlike narration beside tool calls, a stream error's partial, or a truncated reply. - A tool batch runs in groups (C-3 section 2): neighbouring calls to tools that
declare
concurrentrun at the same time, every other call runs alone, and each group starts after the one before it has committed. Each group'sbefore_toolgates run before it starts; results,after_tool, andToolFinishedfollow call order. Every call task is awaited or cancelled before the batch ends, andemitserializes events so theirseqstays in order across concurrent calls. Steers enter after the whole batch. Follow-ups enter at natural termination after steers have been consumed. A terminating tool still finishes its batch. AnExceptionfromTool.executebecomes an error result (at most 500 characters), with a logged traceback; the run continues.BaseException, includingCancelledError, retains lifecycle semantics. - Hook end commits the current step and records policy error results for
unexecuted calls.
Endis a directive, not a primary outcome in the generic hook helper. The owning request/loop stage selectsended_by_hookonly after its required state and step writes succeed; a failed required write ends in error, and abort around those writes retains the aborted outcome. Cleanup failures remain diagnostics. It makes no further model request. - One explicit
RunScopeowns operation admission and joining on Python 3.10. Lazy factories prevent aborted runs from creating callback/store work. Abort cancels pending provider/tool/hook/backoff operations and waits for their cleanup. Admitted store commits finish before ownership is released; connected consumers still receive the committed-row event, and the run ends aborted. Cleanup runs in a separately joined task outside cancelled admission. Closing the event iterator also cleans up its worker. A dependency that independently raises cancellation produces an error and a terminal aborted event; it is not mistaken for a closed iterator. - One outcome owner records the first primary cause. Stream closure, cleanup
hooks and cleanup cancellation add diagnostics without overwriting that cause.
The only exception is a foreground job that still cannot be killed, which
upgrades completed to error. A received terminal is admitted and committed
before closing its stream; close failure does not retry it or skip its tools.
Every message-bearing write passes the projector's actual invariants through
the pure
validate_message_appendhelper before persistence. This covers initial/queued input consumption, full/partial responses, post-hook tool results (including terminating tools), and durable recovery results. Invalid candidates cannot poison resume: no unsupported message is appended/consumed, no committed-row event announces it, and prior valid entries remain intact. An invalid tool/hook result ends the run with an error; its call remains open for deterministic projection and T2 settlement. Recovery rejects invalid renderer output before append, so a corrected retry can finish settlement. The projector also rechecks every call's mutable arguments using the foundation's publicrequire_json_value. Invalid JSON shapes raiseProjectionErrorwith call and row context, before admission or replay; there is no separate loop-owned JSON argument validator. - Every tool execution exit releases that
(Session, tool call)'s remaining foreground handles, including success and failure. Final cleanup sweeps all remaining Session-owned handles on every terminal path. Handed-over jobs are never touched. Failed kills remain owned, other handles are still attempted, and an explicit cleanup error prevents a silently successful run. - Transient retries have an attempt/time budget (at most 3 retries within 120
seconds; default 2), exponential backoff, and honor Retry-After. An expired
budget ends with the original error, including when delay or route resolution
crosses the deadline. Route resolution precedes request admission: expiry is
checked before route validation, projection, rehydration or hooks can run.
Whether to retry is
ProviderError.retryable, the provider boundary's decision. An attempt that did not become a response row is never context; its usage is oneModelAttemptaudit row (context.md§10, invariant 4). Without aContextConfig, overflow emits an error and ends ascontext_exhausted; with one, an overflow before anything was streamed and with no content in its partial enters the C-9 overflow ladder, which stops ascontext.md§8 (d) says. - Projection consumes store-resolved ancestry, sorts by sequence, restores hook state, applies the latest checkpoint and every context edit, and answers orphans with deterministic interrupted text. It has no job host or external settler. The caller supplies the system prompt and hook-rehydrated messages; a checkpoint's state is in its row.
- Before resume, the adapter calls
agent.recovery.settle_open_callsunder its Session writer lock. It appends a governed result for each open call: exited output, a running job handed to Watch, or synthetic interrupted text. A call without job state (includingwriteandedit) explicitly warns that it may or may not have completed and instructs the model to re-read the file before continuing. Each committed outcome is skipped on retry. Late settlement rows are projected alongside their original call; fork cuts only see included outcomes. After settlement the adapter marks the old Turn interrupted (T4); recovery never resumes the model or repeats the tool automatically.
tests/agent_core/agent/ verifies C1, transient C2, C3, C4, C5, resume C6, and
C9 against the actual requests recorded by tests/agent_core/fakes.py.
It also covers each orphan job state, retry classification, cancellation during
job ownership transitions, settlement crash/retry windows, and event consumer
closure. One lifecycle table covers pre-start/storage abort, model/tool abort,
dependency cancellation, consumer closure, tool exceptions, normal completion,
and cleanup. Separate probes cover failed kills and cancellation during commit.
A primary-outcome/cleanup table checks reasons, durable rows, event order,
commit-before-close, tools after close failure, and cleanup diagnostics.
A hook-stage/required-commit table distinguishes successful end directives
from failed state/result writes and abort before, during, or after a commit.
The admission source matrix checks provider responses/partials, tools, result
rewrites, terminating tools, initial inputs and queued steer/follow-up inputs.
Recovery separately checks invalid renderer output after a prior good commit.
Both boundaries prove a fresh Agent can continue over the same store.
Valid-then-mutated argument cases cover Done and partial responses, with a
separate loaded-ancestry check. The final-reply table covers empty, whitespace,
thinking-only and visible replies across stop/length/refusal/safety and
pending-input continuation. The primary/cleanup table includes empty_response.
These are in-memory engine checks. The store contract suite runs the same store
tests, and C-9 across a restart, on the SQLite store too; production provider and
Watch integration is a later layer.
Known by design
- No provider transport here. Checkpoint rows are projected from the text and
state fixed when they were written; a malformed
context_compactionorcontext_editrow raisesProjectionErrorand is never silently ignored. - An Agent with a
ContextConfigtakes no user hooks in v1 (Agent(...)raises a configuration error), so no hook runs in a checkpoint turn: its tool calls take the tool pipeline ofcontext.md§10, invariant 2. Its responses and results are never committed, and it emits nothing but the compaction events. - Store operations remain separate transactions under the queue lock (approved for v1 by the orchestrator). A crash between a non-final response and input consumption leaves that input queued for adapter recovery.
- Input rendering/environment deltas, delivery outbox, actual Session forking,
job-to-call lookup, Watch implementation, and output governance belong to the
adapter or tools. Recovery's renderer receives
(call, job_id, status, watch_id)and returns a governedToolResult; jobs are keyed by call instance (the owning response, in the original Session for a fork's inherited call, plus the call id). The adapter serializes recovery with active runs.JobHost.hand_overmust reuse a job's existing Watch when recovery retries an interrupted commit. - A stream error may persist its partial response as non-final evidence, but no partial tool call executes. A later projection settles missing results.
- This lane validates engine boundaries with fakes. No live service, credentials, network provider, production state, or user-facing integration is exercised.