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.

15.5 KB
Raw Blame

C-3 Loop control

The loop in core/agent_core/agent/. Semantics are the ones the bare-loop spike and Pi passed in the control matrix (evaluation §1).

1. Surface

class Agent:
    def __init__(self, *, models: ModelRouter, tools: Sequence[Tool], hooks: Sequence[Hooks],
                 store: TranscriptStore, jobs: JobHost,
                 context: ContextConfig | None = None) -> None: ...   # C-9; excludes hooks in v1 (§3)

    def run(self, input: Input, *, turn_id: str) -> AsyncIterator[AgentEvent]: ...   # one Avibe Turn
    def resume(self, input: Input, *, turn_id: str, turn_inputs: Iterable[int] | None = None) -> AsyncIterator[AgentEvent]: ...
    def steer(self, input: Input) -> bool: ...       # False: not accepted, the adapter keeps ownership
    def follow_up(self, input: Input) -> bool: ...
    def abort(self, reason: str) -> None: ...
    def set_tools(self, tools: Sequence[Tool]) -> None: ...
    def snapshot(self) -> Snapshot: ...
    def side_turn_fits(self, turn: SideTurn, route: ModelSelection) -> bool: ...      # C-10 fork.md §7, §15
    async def side_turn(self, turn: SideTurn, route: ModelSelection) -> SideTurnResult: ...

Input pairs a UserMessage with its messages.id row. ModelRouter returns the ModelEndpoint and ModelCapabilities for the next call (C-2, C-6 via the adapter); TranscriptStore is C-5; JobHost is C-7. The loop wraps the given JobHost (Agent.jobs) to track foreground jobs for abort; tools are constructed with that wrapper.

A transcript-only resume uses the same loop and cleanup path as run, but skips input consumption. It may be used only after the previous run has closed; the adapter supplies an existing input to before_run for hook setup but does not write a second input row. A fresh Agent passes the source Turn's committed input sequence numbers through turn_inputs; an Agent continuing its own run preserves its in-memory Turn-input set when the argument is omitted. Retry eligibility and retry budgets are adapter policy, not loop policy.

A provider-caused AgentError preserves retryable, continuable, and retry_after_s; other errors default to false/false/None. Vibey continues only a source error explicitly marked continuable, with no committed final and no Stop. It permits at most five additional runs on the same Agent, with exponential backoff bounded by the loop's delay settings and Retry-After as a floor. One elapsed window (the loop policy's max_elapsed_s, at most 120 seconds) starts at the first eligible failed run and includes all subsequent recovery work, waits, and runs; it is not restarted by resume. A delay that does not fit denies another continuation. Expiry prevents new continuations without interrupting a run already doing useful work. Stop wakes backoff immediately and settles the Turn as stopped without another provider request or a failure notice.

commit input → loop:
    projection → before_model hooks (without a ContextConfig) or budget and the C-9 stage (with one; C-9 §10)
        → provider stream (events out) → admission of the response
    if the response has tool calls:
        commit it as `assistant`
        for each group of calls, in call order (below):
            before_tool for each call of the group, in call order
            start the calls the gates let run, in call order; they run at the same time
            for each call of the group, in call order: its result → after_tool → commit tool result
        drain steers (commit each) → continue loop
    else, holding the queue lock:
        if a steer or follow-up is pending: commit the response as `assistant`, commit the pending inputs,
            release the lock → continue loop
        else: commit the response as final (`result`, or `error` when it failed) and close the queues, release the lock → end

Finality is decided before the response row is inserted, so a final (result or error) row is always the run's last response. A final response with stop_reason=length is incomplete, even when it contains partial text: commit it as error, preserve usable content, and end with an error of kind length. A no-answer length stop is not an empty_response; the upstream already supplied the cause. Ordinary empty or reasoning-only stop responses still fail as empty_response, unless the run's calls generated images (a completed image_generate result): a final that ends normally then replies with them, delivered under their heading (vibey-hosted-tools.md §7.3). A refusal, safety or length stop stays a failure, its images still delivered. The loop decides whether a response replies once (has_reply), from the tool results as they committed (a settlement another writer won counts as it committed), and passes the decision to append_response as replied, with the images a final delivers as images. The row's type and display at commit carry both, so the committed final is the complete terminal reply even if delivery never runs; live settlement takes the same values. This does not add a model call, increase an output limit, or replay a task. Non-final responses with pending steer/follow-up keep continuing normally; a tool-free one that replies and did not stop at its output limit is a completed reply that the pending input superseded, which the loop passes to append_response as superseded, so it commits as result, a reply like a final, in the same transaction (released versions committed it as output). A truncated one stays narration, as it would fail as a final. Truncated tool calls keep the existing bounded reissue path without executing their partial arguments. A strict malformed final tool-argument error is different: the adapter preserves every call with safe {} arguments and marks only malformed identities; the loop commits the assistant row, records an explicit error result for each malformed call, executes valid siblings once, and permits Vibey's bounded transcript-only continuation. It never guesses or persists the malformed bytes.

A final response with stop_reason refusal or safety and no text is still committed as the final response, typed error (transcript.md §1); its commit-time display text is the localized explanation. (That it is written in the same transaction so that re-delivery after a crash shows it is moot: Avibe delivers committed rows through the shared emit path and nothing re-delivers them, recovery.md §Delivery.) The run also ends with an error event of that kind. Refusal text from the provider is kept as the reply. A steer that arrives after the queues closed is refused by the running Turn, and Avibe's delivery falls back to the P3 queue, which starts the next run.

The calls of one response. Each tool says whether its calls may run concurrently (Tool.concurrent, C-7 tools.md); a tool that does not is exclusive. The loop walks the calls in call order: a maximal run of consecutive concurrent calls is one group, whose calls run at the same time, and every exclusive call is a group of its own. Groups run one after another. So an exclusive call starts only after every call before it has finished, and no call after it starts until it has finished: a reader-writer lock taken in call order, as Codex's tools/parallel.rs does. Whenever an edit or write is involved, the observable result equals running the calls one by one; concurrency only ever applies between neighbouring read and bash calls. A call to a tool that is not available runs nothing and never splits a group.

  • tool_started is emitted when a call starts. Results commit in call order: a call that finishes early waits for the calls before it, and tool_finished follows the commits.
  • One call failing, by an exception (which becomes its error result) or by an error result, never cancels another call.
  • No call outlives its batch: every call is awaited or cancelled before the run moves on or ends.
  • There is no cap on how many calls run at once, as in Pi and Codex.
  • Calls that run nothing keep one-at-a-time order: those of a response that stopped at its output limit, and those an after_model skip_tools or end settles.
  • A side turn (C-10 fork.md §7) runs its calls one at a time, in call order, and never through groups: the room each call gets depends on the results before it.

Pi differs (packages/agent/src/agent-loop.ts at 7fbbd5f): it runs every call of a response at the same time unless a tool in it declares executionMode: "sequential", and its edit and write serialize only per file path (withFileMutationQueue), which bash bypasses. Avibe makes mutations exclusive instead, so a command never races an edit and never sees a batch of edits half applied. file_mutation_lock (tools/paths.py) still serializes edit and write across Sessions and forks in the same process.

3. Hooks

Hooks run in registration order. The first deny or end wins; rewrites compose in order.

Hook Receives May return
before_run input message, run context system prompt and tool set for this run
before_model the ModelRequest about to be sent a replacement request (transient rewrite of messages, system, tools, model, max tokens), or end
after_model the committed assistant message skip_tools (commit error results [skipped by policy] for its calls), or end
before_tool the tool call deny(reason) (error result with the reason), alter_args(args), or end
after_tool call and result alter_result(result) before commit, or end
after_run outcome nothing

A before_model rewrite changes only that request and is not persisted by design: a rewritten request is not reconstructible from the rows, and A10 is stated for requests without a transient rewrite. Anything that must survive a restart, or that context management must see, goes through C-5 rows (context_edit, context_compaction). end finishes the run after the current step commits.

The tool hooks follow the groups of §2:

  • before_tool runs for each call, in call order, before that call starts. A group's gates all run before the group starts, so no gate sees a result from its own group. deny and alter_args affect only their call. An end settles its call and every later call [skipped by policy]; the calls before it in its group still run.
  • after_tool runs for each call, in call order, when its result is available, before its commit. An end settles every call that has not started [skipped by policy]. The later calls of its group have already started: they finish, pass after_tool, and commit their real results, because their effects happened and the committed result is the truthful record.

In v1 an Agent with a C-9 ContextConfig takes no user hooks: passing both is a configuration error, because C-9 owns the request and the checkpoint turn's tools. Hooks with context management are a post-v1 design item (context.md §10, plan §10).

4. Steer, follow-up, abort

  • steer(m) queues m. It enters the context after the current tool batch and before the next model call, or, when the current response has no tool calls, it starts another model call in the same run. A steer never interrupts a running tool. Avibe P1 deliveries map to steer.
  • follow_up(m) enters only when the run would otherwise end. It exists for hooks and the future tension system; Avibe's P3 queue starts a new run after the Turn settles instead.
  • abort(reason) cancels the provider stream and every running tool call of the batch: each foreground job's process tree is killed (Pi's behavior). Jobs already handed to Watch are not affected. The run ends with run_ended{reason: "aborted"}; what was committed stays committed, and T2 (recovery.md) gives each call left open exactly one result.
  • A tool result with terminate: true ends the run after the batch commits.

5. Tools per call

set_tools and a before_model rewrite take effect at the next model call. A call to a tool that is not in the set sent with that request gets the error result Tool <name> is not available.

6. Agent events (C-4)

run() yields agent-event.schema.json events, keyed by turn_id. The adapter maps them onto existing Avibe concepts; no new UI nouns.

Event Avibe effect
run_started none; the Turn was opened by its delivery
text_delta, thinking_delta dropped: no backend shows live partial text, and none will (owner decision, 2026-10-08), so progress comes from the committed narration and tool lines, as for the other backends
message_committed the committed messages row is delivered: assistant as activity, a superseded result (a reply pending input took the final word from) as a reply that does not end the Turn, the final result as the reply that ends it; a Turn whose final is silent settles with its last reply (reply-and-turn-end.md)
tool_started agent_events tool_call trace row; IM progress line
tool_progress dropped: no backend shows live tool output, and none will (owner decision, 2026-10-08), so a running tool shows its tool_started line, as for the other backends
tool_finished the committed tool_result row; a handed-over job names its Watch
steer_applied the steer delivery is accepted into the running Turn
compaction_started, compaction_finished, compaction_failed none: compaction is invisible (C-9 context.md §10); a finished one lowers the session's token snapshot
context_exhausted the run's stop message, from the error's kind (C-9 context.md §8 d): context_exhausted, the conversation has grown too long to continue reliably, start a new session with /new; tool_output_too_large, the latest tool output does not fit even shortened, ask for a smaller part or use a larger model; input_too_large, the message does not fit, send a shorter one or use a larger model; step_too_large, the latest step (its tool-call arguments or text) is too large, ask for smaller steps or use a larger model. The parts are diagnostic
run_ended MessageOutput settles the Turn; cause is the error that decided the outcome, from which the adapter takes the failure's kind, text, and Model Hub attribution (a diagnostic is never the cause). A completed run whose foreground job cannot be released ends error, and that cleanup error is its cause
error notify / error row; the text shown is the adapter's localized copy for the event's kind (vibe/i18n), and message is diagnostic detail, never display copy; origin (source or local, set where the loop raises the error) decides whether Model Hub records the failure against the route (C-9 context.md §9). A kind is one of NAMED_ERROR_KINDS (agent/events.py: C-2's ErrorKind, a failed StopReason, and the loop's own LoopErrorKind), each with copy of its own, or the class name of an exception the loop did not expect, which reads as an internal error. The adapter logs every failed run once (session, Turn, kind, origin, the hop that served the last response, and the redacted message) and records the kind, never the message, on the failure notice row

7. Snapshot and fork

snapshot() returns (session_id, context_seq, state), where state is the JSON object hooks keep; it is the state of the after_run outcome, not a fork API. A hook that sets state causes an agent_state row at the next commit point (C-5), so a fork whose point is at or after that row restores it. Fork is C-10 (fork.md): the fork point, the side turn (side_turn, above), and the fork Session, whose context resolves through C-5.