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 Run Callback Session
Status: proposal.
Background
vibe agent run lets one Agent queue async work that continues in the
background by default. The missing piece is a first-class way for the completed
run to return its full result to the Session that initiated or is waiting for
that work.
This is especially important for Agent-to-Agent delegation:
caller Session -> async Agent Run -> target Session/scope
|
v
full result callback
|
v
caller Session continues
Terminology:
- Target Session: the Session where the async run executes.
- Caller Session: the Session that should receive the completed run result.
- Callback: a follow-up Agent message created from the completed run result and delivered to the Caller Session.
Avoid "parent Session" / "parent Agent" in user-facing naming because that can confuse run lineage with message delivery.
Product Semantics
Add a callback option to direct Agent Runs:
vibe agent run \
--session-id <target-session-id> \
--callback-session-id <caller-session-id> \
--message "Run this delegated task."
Rules:
--callback-session-idnames the Caller Session.- The async run still executes in its own Target Session or target scope exactly as it does today.
- When the async run reaches a terminal state, Avibe sends the full execution result as a new message to the Caller Session.
- Callback delivery is independent from ordinary output delivery. If the target run also posts to its IM scope, the callback still happens.
- Callback sends all terminal outcomes for v1: success, failure, cancellation, and terminal errors. Do not add filtering flags yet.
- The callback message enters the Caller Session as P1: it steers the active Turn when possible, starts when idle, and falls back to P3 after a definitive steer refusal. It never interrupts the active Turn.
- The callback message should trigger the Caller Session Agent as a normal follow-up message. It is not just passive transcript decoration.
Message Content
The callback message should contain only the completed run's final result text, not a status notification or process transcript.
Priority:
- Use
agent_runs.result_textwhen present. - If the run failed and has no
result_text, construct a failure result fromerror,stderr, and stdout when useful for diagnosing a failed run. - If the run was canceled and has no
result_text, construct a cancellation result. - If there is truly no result content, skip sending an empty callback but persist the callback state as skipped.
Do not include wrapper metadata such as run id, status, agent name, target session, system messages, tool calls, or intermediate assistant updates in the callback body.
CLI/API Shape
CLI
Add to vibe agent run:
--callback-session-id <session-id>
Validation:
vibe agent runis async by default, so--callback-session-idworks without an explicit async flag.- The callback session id must resolve to an active
agent_sessionsrow. - Archived sessions are invalid.
- Callback to the same Session is allowed but should be documented as a loop risk for automation authors.
--callback-session-idis orthogonal to target Session selection and scope placement.
The accept payload is one run object, and the callback route lives on it:
{
"run": {
"callback_session_id": "ses..."
}
}
callback_notice appears only when the route is not what the caller's flags
imply: a run on the caller's own Session, which gets no callback because the
result already lands there.
Internal/API Payload
Carry callback_session_id through the same run-spec path as session_id and
scope placement, so CLI, future UI/API creation, and persisted run history do
not drift.
Data Model
Add persisted callback fields to agent_runs.
Minimum v1 columns:
callback_session_id text nullcallback_status text nullcallback_error text nullcallback_run_id text nullcallback_completed_at text null
Suggested callback statuses:
pending: callback requested but not attempted.sent: callback run/message was queued successfully.skipped: no callback was sent because no callback was requested or there was no content to send.failed: callback dispatch failed.
Why explicit columns instead of only metadata_json:
- callback state is user-visible run state;
- it needs to be queryable in
vibe runs show/list; - retries/debugging should not depend on parsing opaque metadata.
Also update:
- SQLAlchemy model definition.
- Alembic migration.
- lightweight local migration path in
storage/migrations.py. - import/export or state-backfill paths that enumerate
agent_runscolumns.
Execution Design
Callback should happen in the Harness execution layer after the target run is
terminal and after result_text has been recorded.
High-level flow:
vibe agent run ... --callback-session-id ses_callingenqueues anagent_runrow withcallback_session_id=ses_callingandcallback_status=pending.- The scheduler/request drain executes the target run as today.
- Terminal output is recorded on the target
agent_runsrow. - The Harness layer builds callback message content from the terminal run row.
- The Harness layer enqueues a new callback Agent Run into the Caller Session using the same scheduled/watch Agent turn path.
- The original run persists the callback update as
sent,skipped, orfailed, includingcallback_run_idwhen a follow-up run is created.
Important boundary:
- Do not implement callback in the CLI process. Default-async runs return immediately, and callback must survive CLI exit and service restart.
Turn/Queue Semantics
For Workbench/Avibe Sessions:
- callback enters
SessionTurnManager.submit_scheduled(...); - if the Caller Session is busy, callback is queued;
- if idle, callback starts a normal scheduled-source turn;
- callback must not interrupt the active turn.
For IM-backed Sessions:
- callback uses the existing scheduled-message path and delivery context for that Session.
This mirrors watch follow-up behavior and keeps callback behavior consistent with existing Harness semantics.
Failure Handling
The target run can succeed while callback fails. These are separate outcomes.
Run status remains the target execution result:
- target succeeded + callback failed => run status
succeeded,callback_status=failed. - target failed + callback sent => run status
failed, callback still recordssent.
Retries:
- v1 can be manual:
vibe runs show <run-id>exposes callback failure details. - A later
vibe runs callback <run-id>orvibe runs retry-callback <run-id>can be added if needed.
Tests
Focused test coverage:
- CLI parser accepts
--callback-session-idfor default-async direct Agent Runs. - CLI payload and persisted row include
callback_session_id. - unresolved/archived callback Session is rejected.
- completed successful run dispatches full
result_textinto Caller Session. - failed run without
result_textdispatches constructed failure content. - target IM delivery and callback both happen when both are configured.
- busy Workbench Caller Session queues callback instead of interrupting.
- callback failure does not overwrite target run status.
vibe runs showincludes callback state.
Documentation
Update:
- CLI docs for
vibe agent run. - Chinese CLI docs.
skills/use-avibe/SKILL.mdif command guidance mentions async Agent Runs.
Docs should use "Caller Session" / "调用方 Session" consistently.
Non-Goals For v1
- No
--callback-on success|failure|alwaysfilter. - No result summarization/compression.
- No callback retry command unless implementation reveals the need.
- No special "parent run" behavior.
- No automatic loop prevention beyond normal session serialization.
Implementation Sequence
- Add schema/model/store support for callback fields.
- Extend
TaskExecutionRequestandenqueue_agent_run(...)to carrycallback_session_id. - Add CLI flag, validation, and JSON output.
- Add callback message builder from terminal run rows.
- Dispatch callback through the scheduled/watch-style Session path.
- Expose callback state in
vibe runs show/list. - Add focused unit tests.
- Update CLI docs and Avibe skill docs.