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.
Contract: Agents Graph API + Session Visibility (FROZEN 2026-07-23)
Frozen interface contract for the two parallel lanes of
agents-run-graph-and-session-visibility.md. Deviations require
orchestrator sign-off first — do not negotiate field changes lane-to-lane.
Amendments (orchestrator-approved):
- A1 (2026-07-23, PR #956): graph node gains
runs[](recent runs for the detail-panel timeline, newest first, capped at 10 — avoids an N+1 fetch). Additive. - A2 (2026-07-23, PR #956): top-level
live_unreachable: boolean—truewhen the controller/running-agents service is unreachable and the payload degrades to DB-only (client shows a degraded banner, mirroring the running list'sunreachablepattern). Additive. - A3 (2026-07-23, PR #956 review r1): session-less orphan processes are
NOT synthesized as graph nodes (nodes stay =
agent_sessionsrows; orphans have no session, no lineage, no chat). Capability restored via a client-side orphan strip above the canvas (and a section in the mobile list): rows sourced from the existingGET /api/running-agentspayload (session_id == null), each with backend/pid/elapsed and the existing Kill flow (POST /api/running-agents/end, 2-step confirm). Graph payload unchanged. Session-anchored orphans keep rendering asstatus:orphannodes. - A4 (2026-07-23, PR #956 review r1): callback edges are emitted only
when
callback_statusis non-null (a recorded outcome/progress state). Sync-delegated runs that merely record a callback route (null status, nothing will be delivered) do not produce an edge. Supersedes the earlier "null → pending" mapping. - A5 (2026-07-23, PR #956 review r1):
include_ended=0means non-terminal sessions — live (active|idle|orphan) plusqueued— not "live only". Queued work is upcoming and must be visible in the active view; the counts object keepsqueuedpopulated accordingly. - A6 (2026-07-23, cross-lane): visibility reconcile event contract:
backend (M1, PR #957) emits the existing
session.activitySSE event with the session's currentvisibilityon every PATCH/CLI visibility or scope change. Frontend consumption is M2's (PR #956): the Inbox context removes a session card when an event carriesvisibility='background'(and refetches/re-adds on'foreground'); absentvisibilityfield ⇒ no-op (defensive pre-M1). M1 does not touchui/**for this; the gap is recorded in #957's inventory as assigned to #956. - A8 (2026-07-23, owner regression feedback): callback edges are no longer rendered on the canvas (visual clutter). The payload keeps emitting them unchanged; the node detail panel ("REPORTS TO · callback status") becomes the only callback surface. Client-side rendering change only.
- A9 (2026-07-23, owner regression feedback): chat trigger-message
provenance: agent-callback ("自动触发") messages render the SOURCE session's
title prefix and click through to
/chat/<source_session_id>; task/watch trigger messages click through to the corresponding Harness filter view (reuse the backgroundActivity deep-link helpers). Read-side message enrichment only if the payload lacks source ids. - A10 (2026-07-23, owner feedback — graph blew up with every Harness
definition):
trigger_nodesare edge-derived: emit a chip ONLY for definitions that have ≥1triggeredge in the returned payload (i.e. they actually triggered a session within the window/filters). Enabled-but-idle and disabled definitions with no in-window runs never appear. A disabled definition that DID fire in-window keeps its chip (it explains lineage) — client renders it dimmed with a disabled marker using the existingenabledfield. - A11 (2026-07-26, owner feedback): trigger chips get an in-graph
detail panel (same interaction as session nodes) instead of navigating to
Harness on click: name, type (task schedule/next-run · watch command/runtime
state), enabled state, carrying session (click selects that node), recent
trigger runs (deep-links), in-place actions (enable/disable toggle; watch
pause/resume) via the EXISTING harness API client methods — no new backend.
Amended 2026-07-26 (PR #1018 review): task run-now is DEFERRED — no HTTP
endpoint exposes the
vibe task runpath yet and this batch is UI-only (owner-approved deferral, tracked in the PR's Deferred ledger as a candidate backend micro-batch). The panel ships without a run-now control until that endpoint exists. "Open in Harness" becomes a secondary link in the panel. Additionally, chips withenabled=falseare hidden by default (together with their trigger edges); a "show disabled" switch in the canvas LEGEND reveals them (dimmed + disabled marker per A10). Client-side only; payload unchanged. - A12 (2026-07-30, callback ownership correction): only child Runs with
source_kind='callback'are callback deliveries. An agent-authored child remains an independent spawn even when it targets the parent Run's callback Session; parent/target coincidence never erases that lineage. This is read-only classification: historical rows are never reset or replayed. - A7 (2026-07-23, PR #956 review): graph endpoint path renamed
/api/agents/graph→/api/agents-graph. Rationale:/api/agents/…is the agent-resource namespace and agent names are user-creatable slugs — an agent literally namedgraphwould shadow the route. Endpoint and its sole consumer live in the same PR; no migration cost. Reserving the wordgraphin the agent-name domain was rejected.
1. Visibility enum (M1 owns, M2 consumes)
agent_sessions.visibility∈"foreground" | "background". No other values. Absent/legacy rows read as"foreground"after backfill.- Standalone session:
agent_sessions.scope_id IS NULL.
2. Session update (M1 owns)
PATCH /api/sessions/<session_id> accepts (in addition to existing fields):
{ "visibility": "background" }
{ "scope_id": "avibe::project::proj_272e944ca452" }
{ "scope_id": null }
visibilityandscope_idare independent; either may appear alone.- Response: the standard session payload, now always including
visibilityand (nullable)scope_id,project_id. - Errors:
400invalid value;404unknown session. Changingscope_idnever mutates the session's storedworkdir.
CLI equivalent: vibe session update [--session-id <id>] [--visible|--hidden] [--scope-id <scopes.id>|none].
3. Graph endpoint (M2 owns; shape frozen for both)
GET /api/agents-graph?window=24h&project=<project_id|all|standalone>&include_ended=1&include_background=1
(path per amendment A7)
window:1h|6h|24h|7d(default24h); bounds history lookback (agent_runs.created_at >= now - window, plus all currently-live sessions regardless of window).include_ended=0⇒ non-terminal sessions: live (active|idle|orphan) plusqueued(amendment A5).include_background=0⇒ foreground nodes only (edges to hidden nodes are dropped with them).
Response:
{
"ok": true,
"generated_at": "2026-07-23T02:00:00Z",
"window": "24h",
"live_unreachable": false,
"counts": { "active": 3, "idle": 1, "queued": 1, "ended": 4,
"background": 5, "foreground": 3 },
"nodes": [
{
"session_id": "ses7y3jff7b6r",
"title": "Vaults M2 · 总控分派",
"agent_name": "pm",
"agent_backend": "claude",
"model": "claude-fable-5",
"reasoning_effort": "max",
"status": "active",
"live": true,
"visibility": "foreground",
"scope_id": "avibe::project::proj_272e944ca452",
"project_id": "proj_272e944ca452",
"scope_label": "vibe-remote",
"platform": "avibe",
"workdir": "/Users/cyh/vibe-remote-project",
"openable_in_chat": true,
"created_at": "2026-07-21T10:10:22Z",
"last_active_at": "2026-07-23T01:58:00Z",
"elapsed_seconds": 4320,
"run_counts": { "total": 6, "running": 1 },
"runs": [
{ "id": "run_9f2kc1", "status": "running", "run_type": "agent_run",
"created_at": "...", "started_at": "...", "completed_at": null }
]
}
],
"trigger_nodes": [
{
"definition_id": "def_abc123",
"definition_type": "scheduled",
"name": "每日选题灵感",
"schedule_label": "cron 10:17",
"enabled": true
}
],
"edges": [
{ "kind": "spawn", "from": "ses_caller", "to": "ses_child",
"run_count": 2, "last_run_id": "run_x", "last_at": "..." },
{ "kind": "callback", "from": "ses_child", "to": "ses_caller",
"status": "pending", "last_run_id": "run_x" },
{ "kind": "trigger", "from": "def:def_abc123", "to": "ses_child",
"run_count": 5, "last_at": "..." }
],
"truncated": false
}
Semantics:
- Node
status∈active|idle|orphan(live, from running-agents service) orqueued|succeeded|failed|canceled(latest run outcome for non-live).livedistinguishes the two families. titlemay be null → client falls back toagent_name + session_idsuffix.scope_label/project_id/scope_id/platformnull ⇒ standalone (独立).- Edge node references: sessions by
session_id; trigger chips bydef:<definition_id>. spawnedges: aggregated per (caller session → callee session) from runs withsource_kind='agent'andsource_actorset. Callback deliveries usesource_kind='callback'and never enter spawn aggregation.callbackedges: emitted whencallback_session_idis set andcallback_statusis non-null (amendment A4 — sync runs that only record a return route draw nothing). Target may equal the spawn caller; the client decides rendering.status∈pending|sent|failed|skipped.triggeredges: runs withrun_type in ('scheduled','watch')grouped bydefinition_id.- Cap: server may truncate to the most recent 300 nodes; set
truncated: truewhen it does.
4. Graph payload consumers
- Desktop: React Flow canvas (Agents → 运行 tab).
- Mobile: grouped list rendering of the same payload (tree indentation by spawn edges).
- The running list's
endaction continues to use the existingPOST /api/running-agents/end— the graph detail panel calls it unchanged.