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.
Python agentagent-osaiai-agentsai-partnerchatopsclaudeclaude-codecodexdevtoolsdiscord-botlark-botllmlocal-firstlong-term-memoryopencodeslack-botvibe-codingvibeywechat
"""Read-only assembly of the Agents · 运行图 (run graph) payload.
This service is the single place that turns the persisted agent state into the
graph the Agents → 运行 tab renders. It is intentionally read-only: it opens a
SQLite connection, reads ``agent_sessions``/``agent_runs``/``scopes``/
``run_definitions``, and merges in liveness that the caller passes in from the
controller's running-agents snapshot. It never writes and never touches the
controller directly, so it stays pure w.r.t. its inputs and unit-testable with
fixture rows + a fake ``live_agents`` list.
Wire shape is the frozen contract in
``docs/plans/agents-run-graph-contract.md`` §3. The only addition over that doc
is the per-node ``runs`` array (recent runs for the detail-panel timeline);
it is additive and only the graph frontend consumes it.
Graph semantics (all from existing columns):
- **Node** = an ``agent_sessions`` row. ``status``/``live`` come from the
running-agents snapshot when the session has a live process, else from the
session's latest run outcome.
- **Spawn edge** (caller → callee): runs with ``source_kind='agent'`` and
``source_actor`` set, aggregated per (caller session, callee session).
- **Callback edge** (callee → report target): runs with ``callback_session_id``
set; status from ``callback_status``. Its delivery child has
``source_kind='callback'`` and never suppresses an agent-authored spawn.
- **Trigger edge** (definition → carrying session): runs with
``run_type in ('scheduled','watch')`` grouped by ``definition_id``.
Scope is joined LEFT (``scope_id`` is nullable): a NULL scope renders as the
``独立`` (standalone) bucket.
"""
from __future__ import annotations
import json
from datetime import datetime, timedelta, timezone
from typing import Any, Iterable, Mapping, Optional, Sequence
from sqlalchemy import and_, or_, select
from sqlalchemy.engine import Engine
from storage.agent_session_rows import session_openable_in_chat
from storage.background import _status_query_values, normalize_run_status
from storage.db import create_sqlite_engine
from storage.models import agents, agent_runs, agent_sessions, run_definitions, scope_settings, scopes
# History window → lookback seconds. ``24h`` is the default (contract §3).
WINDOW_SECONDS: dict[str, int] = {
"1h": 3600,
"6h": 21600,
"24h": 86400,
"7d": 604800,
}
DEFAULT_WINDOW = "24h"
# Server-side node cap; when exceeded we keep the most recent 300 and set
# ``truncated`` so the client can surface it (contract §3).
NODE_CAP = 300
# Recent runs embedded per node for the detail-panel timeline (contract A1:
# newest first, capped at 10).
RUNS_PER_NODE = 10
# Sort sentinel for runs whose created_at is missing/unparseable (oldest).
_EPOCH = datetime.min.replace(tzinfo=timezone.utc)
# Trigger definition types that produce a trigger chip.
_TRIGGER_RUN_TYPES = {"scheduled", "watch"}
# ── timestamp helpers ────────────────────────────────────────────────────────
# Stored ``*_at`` strings come in two ISO-8601 flavors depending on the writer
# (``…Z`` second-granularity vs ``.isoformat()`` with ``+00:00`` microseconds).
# Parse either and re-emit the canonical ``…Z`` the contract asks for.
def _parse_iso(value: Optional[str]) -> Optional[datetime]:
if not value:
return None
text = value.strip()
if not text:
return None
if text.endswith("Z"):
text = text[:-1] + "+00:00"
try:
dt = datetime.fromisoformat(text)
except ValueError:
return None
if dt.tzinfo is None:
dt = dt.replace(tzinfo=timezone.utc)
return dt.astimezone(timezone.utc)
def _iso_z(value: Any) -> Optional[str]:
"""Normalize a stored timestamp (or datetime) to ``YYYY-MM-DDTHH:MM:SSZ``."""
if isinstance(value, datetime):
dt: Optional[datetime] = value if value.tzinfo else value.replace(tzinfo=timezone.utc)
else:
dt = _parse_iso(value)
if dt is None:
return value if isinstance(value, str) and value else None
return dt.astimezone(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
# ── status resolution ────────────────────────────────────────────────────────
def _node_status(live_state: Optional[str], runs: list[dict[str, Any]]) -> tuple[str, bool]:
"""Return ``(status, live)`` for a node.
Live sessions carry the running-agents state (``active``/``idle``/
``orphan``). Otherwise the node reflects its runs: any non-terminal run
(``queued``/``running`` — including a stale ``running`` with no live process,
or an older queued/running run left behind a newer finished one on a reused
or stuck session) surfaces as ``queued`` so the Active view keeps its pending
work; else the latest run's terminal outcome; else ``idle``.
"""
if live_state in ("active", "idle", "orphan"):
return live_state, True
for run in runs:
if normalize_run_status(run["status"]) in ("queued", "running"):
return "queued", False
if runs:
return normalize_run_status(runs[0]["status"]), False
return "idle", False
def _merge_live_state(states: Iterable[str]) -> str:
"""Collapse a session's per-backend live rows into one state.
A session can appear once per backend in the snapshot; ``active`` wins over
``orphan`` over ``idle`` so the node reflects its most significant activity.
"""
rank = {"active": 0, "orphan": 1, "idle": 2}
best: Optional[str] = None
for state in states:
if best is None or rank.get(state, 3) < rank.get(best, 3):
best = state
return best or "idle"
# ── liveness index ───────────────────────────────────────────────────────────
def _index_live_agents(live_agents: Sequence[Mapping[str, Any]]) -> dict[str, dict[str, Any]]:
"""Index running-agents rows by ``session_id``.
Keeps the merged live ``state`` and the ``elapsed_seconds`` of the row whose
state *won* the merge — the header shows the winning state (e.g. ``active``),
so its elapsed must come from an ``active`` row, not from an unrelated idle
row that happened to have a larger elapsed.
"""
by_session: dict[str, dict[str, Any]] = {}
grouped: dict[str, list[Mapping[str, Any]]] = {}
for row in live_agents or ():
session_id = row.get("session_id")
if session_id:
grouped.setdefault(session_id, []).append(row)
for session_id, rows in grouped.items():
state = _merge_live_state(str(r.get("state") or "idle") for r in rows)
winning_elapsed = [
r.get("elapsed_seconds")
for r in rows
if str(r.get("state") or "idle") == state and r.get("elapsed_seconds") is not None
]
by_session[session_id] = {
"state": state,
"elapsed_seconds": max(winning_elapsed) if winning_elapsed else None,
}
return by_session
# ── scope helpers ────────────────────────────────────────────────────────────
def _scope_label(display_name: Optional[str], native_id: Optional[str]) -> Optional[str]:
if display_name and display_name.strip():
return display_name
return native_id or None
def _project_id(platform: Optional[str], scope_type: Optional[str], native_id: Optional[str]) -> Optional[str]:
# A "project" is an avibe scope of type project; its public id is the
# scope's native_id (proj_<hex>). IM scopes are not projects.
if platform == "avibe" and scope_type == "project":
return native_id
return None
# ── trigger schedule label ───────────────────────────────────────────────────
def _schedule_label(row: Mapping[str, Any]) -> Optional[str]:
if row.get("definition_type") == "scheduled":
cron = row.get("cron")
if cron:
return f"cron {cron}"
run_at = row.get("run_at")
if run_at:
return _iso_z(run_at)
return None
# ── main assembly ────────────────────────────────────────────────────────────
def build_graph(
*,
live_agents: Optional[Sequence[Mapping[str, Any]]] = None,
window: str = DEFAULT_WINDOW,
project: str = "all",
include_ended: bool = True,
include_background: bool = True,
live_unreachable: bool = False,
now: Optional[datetime] = None,
node_cap: int = NODE_CAP,
engine: Optional[Engine] = None,
) -> dict[str, Any]:
"""Assemble the run-graph payload (contract §3 + amendments A1/A2).
``live_agents`` is the controller's running-agents snapshot list (each row
has at least ``session_id`` + ``state``); the route injects it so this stays
testable. ``live_unreachable`` (A2) is set by the route when the controller
is down and ``live_agents`` is empty. ``now`` is injectable for tests.
"""
now = now or datetime.now(timezone.utc)
if now.tzinfo is None:
now = now.replace(tzinfo=timezone.utc)
window = window if window in WINDOW_SECONDS else DEFAULT_WINDOW
cutoff = now - timedelta(seconds=WINDOW_SECONDS[window])
cutoff_iso = cutoff.isoformat()
live_by_session = _index_live_agents(live_agents or ())
live_ids = set(live_by_session)
owned_engine = engine is None
engine = engine or create_sqlite_engine()
try:
with engine.connect() as conn:
# The candidate source differs by view. History (include_ended) uses
# the window scan. Active (contract A5 = live + queued) uses the live
# set plus every session with a non-terminal run, independent of the
# window and of the raw status alias — so a stuck-queued job older
# than the cutoff, or a controller-down stale ``running`` row, can't
# disappear from the active view.
if include_ended:
candidate_ids = _resolve_candidates(conn, live_ids, cutoff_iso)
else:
candidate_ids = set(live_ids) | _active_run_session_ids(conn)
if not candidate_ids:
return _empty_payload(now, window, live_unreachable)
# Bound the expensive run-history load by choosing which candidate
# SESSIONS to load runs for (cheap — no runs) before ``_load_runs``,
# after the session-level visibility filters (project, background,
# archived/disabled) so hidden rows can't consume the cap and starve
# visible ones. A busy install can have far more candidates than
# survive the response, and the graph refetches on SSE/poll.
candidate_rows = _load_sessions(conn, candidate_ids)
eligible = _prefilter_candidate_rows(
candidate_rows, project=project,
include_background=include_background, live_ids=live_ids,
)
ranked = sorted(eligible, key=lambda r: _session_sort_key(r, live_ids))
candidate_truncated = len(ranked) > node_cap
session_by_id = {r["id"]: r for r in ranked[:node_cap]}
loaded_ids = set(session_by_id)
runs_by_session = _load_runs(conn, loaded_ids)
# Pull in lineage sessions referenced by a retained run — even a
# spawn/callback older than the window (e.g. a long-lived live
# session's original delegation) — so the edge and its "who started
# it / reports to" endpoints survive. Fixed point, but track attempted
# ids in ``loaded_ids`` (monotonic): a run can point at a session id
# with no ``agent_sessions`` row (stale source_actor/callback from
# imported or repaired state) which never lands in ``session_by_id``,
# so keying the loop off that alone would spin forever.
while True:
extra = _lineage_refs(runs_by_session) - loaded_ids
if not extra:
break
loaded_ids |= extra
runs_by_session.update(_load_runs(conn, extra))
for row in _load_sessions(conn, extra):
session_by_id.setdefault(row["id"], row)
session_rows = list(session_by_id.values())
edges, trigger_ids = _build_edges(runs_by_session, loaded_ids, cutoff)
trigger_nodes = _load_trigger_nodes(conn, trigger_ids)
finally:
if owned_engine:
engine.dispose()
nodes = _build_nodes(session_rows, runs_by_session, live_by_session)
nodes = _filter_nodes(nodes, project=project, include_ended=include_ended,
include_background=include_background)
nodes, cap_truncated = _cap_nodes(nodes, node_cap)
truncated = candidate_truncated or cap_truncated
node_ids = {n["session_id"] for n in nodes}
edges = _filter_edges(edges, node_ids, {t["definition_id"] for t in trigger_nodes})
trigger_nodes = _prune_triggers(trigger_nodes, edges)
return {
"ok": True,
"generated_at": _iso_z(now),
"window": window,
"live_unreachable": live_unreachable,
"counts": _counts(nodes),
"nodes": nodes,
"trigger_nodes": trigger_nodes,
"edges": edges,
"truncated": truncated,
}
def _empty_payload(now: datetime, window: str, live_unreachable: bool) -> dict[str, Any]:
return {
"ok": True,
"generated_at": _iso_z(now),
"window": window,
"live_unreachable": live_unreachable,
"counts": _counts([]),
"nodes": [],
"trigger_nodes": [],
"edges": [],
"truncated": False,
}
def _active_run_session_ids(conn) -> set[str]:
"""Sessions with a non-terminal run — the non-live half of the active view
(contract A5). Uses the run store's own normalized status family
(``queued``/``running`` → raw ``pending``/``queued``/``processing``/
``running``) so aliases and a controller-down stale ``running`` row still
count, and is NOT window-limited so a stuck-queued job older than the
history cutoff can't disappear from the active view. Non-terminal runs are
few (in-flight work drains), so the set stays small."""
raw_statuses = _status_query_values("queued") + _status_query_values("running")
stmt = select(agent_runs.c.session_id).where(agent_runs.c.status.in_(raw_statuses)).distinct()
return {row[0] for row in conn.execute(stmt) if row[0]}
def _resolve_candidates(conn, live_ids: set[str], cutoff_iso: str) -> set[str]:
"""The set of session ids that become nodes.
Always the live sessions, plus every session with a run in the window and
the sessions those runs reference as caller (``source_actor``) or callback
target — so tree roots, report targets, and (per contract A5) queued work
render. ``_filter_nodes`` then narrows to the active (non-terminal) or full
(history) view; this stays broad so a queued-but-not-live session is a
candidate the active filter can keep.
"""
candidates: set[str] = set(live_ids)
# Window match = any recent activity, not just creation: a long run created
# before the cutoff but finished/failed/canceled inside the window must
# still surface. ``updated_at`` alone captures all of these — it is set to
# ``created_at`` on insert and bumped to the transition time (equal to
# ``completed_at`` on terminal states) on every status change, so it is a
# superset of the created/completed timestamps. Using the single column lets
# this frequently-polled scan ride the ``ix_agent_runs_updated`` index
# instead of a full table scan (the other agent_runs indexes all lead with a
# non-timestamp column and cannot serve a bare range predicate).
stmt = select(
agent_runs.c.session_id,
agent_runs.c.source_kind,
agent_runs.c.source_actor,
agent_runs.c.callback_session_id,
agent_runs.c.callback_status,
).where(agent_runs.c.updated_at >= cutoff_iso)
for row in conn.execute(stmt).mappings():
if row["session_id"]:
candidates.add(row["session_id"])
if row["source_kind"] == "agent" and row["source_actor"]:
candidates.add(row["source_actor"])
# Only a callback target that will draw an edge (A4: non-null status) —
# a bare return route must not promote an unconnected root node.
if row["callback_session_id"] and row["callback_status"]:
candidates.add(row["callback_session_id"])
return candidates
def _load_sessions(conn, candidate_ids: set[str]) -> list[dict[str, Any]]:
cols = [
agent_sessions.c.id,
agent_sessions.c.scope_id,
agent_sessions.c.agent_name,
agent_sessions.c.agent_backend,
agent_sessions.c.model,
agent_sessions.c.reasoning_effort,
agent_sessions.c.workdir,
agent_sessions.c.title,
agent_sessions.c.status,
agent_sessions.c.visibility,
agent_sessions.c.created_at,
agent_sessions.c.updated_at,
agent_sessions.c.last_active_at,
scopes.c.display_name.label("scope_display_name"),
scopes.c.native_id.label("scope_native_id"),
scopes.c.platform.label("scope_platform"),
scopes.c.scope_type.label("scope_scope_type"),
scopes.c.native_type.label("scope_native_type"),
scope_settings.c.enabled.label("scope_enabled"),
agents.c.name.label("catalog_agent_name"),
agents.c.archived_at.label("catalog_agent_archived_at"),
agents.c.metadata_json.label("catalog_agent_metadata_json"),
]
stmt = (
select(*cols)
.select_from(
agent_sessions
.outerjoin(scopes, agent_sessions.c.scope_id == scopes.c.id)
.outerjoin(scope_settings, agent_sessions.c.scope_id == scope_settings.c.scope_id)
.outerjoin(
agents,
or_(
agents.c.id == agent_sessions.c.agent_id,
and_(
agent_sessions.c.agent_id.is_(None),
agents.c.name == agent_sessions.c.agent_name,
),
),
)
)
.where(agent_sessions.c.id.in_(candidate_ids))
)
return [dict(row) for row in conn.execute(stmt).mappings()]
def _session_agent_display_name(row: Mapping[str, Any]) -> Optional[str]:
internal_name = str(row.get("agent_name") or "").strip()
catalog_name = str(row.get("catalog_agent_name") or "").strip()
if row.get("catalog_agent_archived_at"):
try:
metadata = json.loads(row.get("catalog_agent_metadata_json") or "{}")
except (TypeError, ValueError):
metadata = {}
archive = metadata.get("_avibe_archive") if isinstance(metadata, dict) else None
if isinstance(archive, dict):
original_name = str(archive.get("original_name") or "").strip()
if original_name:
return original_name
return catalog_name or internal_name or None
def _load_runs(conn, candidate_ids: set[str]) -> dict[str, list[dict[str, Any]]]:
"""Every run belonging to a candidate session, newest first, grouped by
session. Full lineage (not window-limited) so aggregates + edges are
accurate for a session once it is in scope."""
stmt = (
select(
agent_runs.c.id,
agent_runs.c.session_id,
agent_runs.c.status,
agent_runs.c.run_type,
agent_runs.c.definition_id,
agent_runs.c.source_kind,
agent_runs.c.source_actor,
agent_runs.c.parent_run_id,
agent_runs.c.callback_session_id,
agent_runs.c.callback_status,
agent_runs.c.callback_run_id,
agent_runs.c.created_at,
agent_runs.c.started_at,
agent_runs.c.completed_at,
)
.where(agent_runs.c.session_id.in_(candidate_ids))
.order_by(agent_runs.c.created_at.desc(), agent_runs.c.id.desc())
)
grouped: dict[str, list[dict[str, Any]]] = {}
for row in conn.execute(stmt).mappings():
data = dict(row)
grouped.setdefault(data["session_id"], []).append(data)
# Re-sort newest-first in Python: stored run times mix `...Z` (seconds) and
# `.isoformat()` (`+00:00`, microseconds), so SQLite's text order_by can rank
# two same-second runs wrong and leave a stale run at runs[0] — which drives
# the node status, the recent-runs timeline, and the active-view filter.
for runs in grouped.values():
runs.sort(key=lambda r: (_parse_iso(r.get("created_at")) or _EPOCH, r["id"]), reverse=True)
return grouped
def _lineage_refs(runs_by_session: dict[str, list[dict[str, Any]]]) -> set[str]:
"""Session ids referenced as a spawn caller or callback target by any run."""
refs: set[str] = set()
for runs in runs_by_session.values():
for run in runs:
if run.get("source_kind") == "agent" and run.get("source_actor"):
refs.add(run["source_actor"])
# Only follow a callback target that will actually draw an edge
# (A4: callback edges need a non-null status). A run that merely
# recorded a return route otherwise promotes an unconnected root that
# consumes cap/count with no report edge.
if run.get("callback_session_id") and run.get("callback_status"):
refs.add(run["callback_session_id"])
return refs
def _build_edges(
runs_by_session: dict[str, list[dict[str, Any]]],
candidate_ids: set[str],
cutoff: datetime,
) -> tuple[list[dict[str, Any]], set[str]]:
"""Aggregate spawn / callback / trigger edges from the candidate runs.
Trigger edges are window-scoped (contract A10): a candidate session can carry
OLD trigger runs (it stays in scope via other in-window activity or lineage),
but a definition only earns a ``trigger`` edge — and thus a chip — from a run
that fired within the window. Spawn/callback stay full-lineage so an older
delegation's endpoints survive.
"""
spawn: dict[tuple[str, str], dict[str, Any]] = {}
callback: dict[tuple[str, str], dict[str, Any]] = {}
trigger: dict[tuple[str, str], dict[str, Any]] = {}
trigger_ids: set[str] = set()
def _newer(existing: Optional[str], candidate: Optional[str]) -> bool:
# Compare parsed instants, not raw strings: stored run times mix `...Z`
# (second precision) and `.isoformat()` (microseconds/`+00:00`), which
# sort wrong lexicographically within the same second.
cand = _parse_iso(candidate)
if cand is None:
return False
prev = _parse_iso(existing)
return prev is None or prev < cand
for session_id, runs in runs_by_session.items():
for run in runs:
created = run.get("created_at")
# Callback deliveries use source_kind='callback'. Every agent child
# remains independent delegation, even when it targets the parent
# run's callback session.
if run.get("source_kind") == "agent" and run.get("source_actor"):
key = (run["source_actor"], session_id)
agg = spawn.setdefault(key, {"run_count": 0, "last_run_id": None, "last_at": None})
agg["run_count"] += 1
if agg["last_at"] is None or _newer(agg["last_at"], created):
agg["last_at"] = created
agg["last_run_id"] = run.get("id")
# callback: this session → report target
# Contract A4: only emit a callback edge once a callback_status is
# recorded. A run that merely routes a callback (sync-delegated,
# null status — nothing will be delivered) produces no edge.
if run.get("callback_session_id") and run.get("callback_status"):
key = (session_id, run["callback_session_id"])
agg = callback.setdefault(key, {"status": None, "last_run_id": None, "last_at": None})
if agg["last_at"] is None or _newer(agg["last_at"], created):
agg["last_at"] = created
agg["last_run_id"] = run.get("callback_run_id") or run.get("id")
agg["status"] = run.get("callback_status")
# trigger: definition → this session. A10: only an IN-WINDOW trigger
# run earns a chip. A candidate session can carry old trigger runs (it
# stays in scope via other in-window activity or lineage); a historical
# or since-disabled definition must not resurface just because its old
# session lingers.
run_at = _parse_iso(created)
if (
run.get("run_type") in _TRIGGER_RUN_TYPES
and run.get("definition_id")
and run_at is not None
and run_at >= cutoff
):
definition_id = run["definition_id"]
trigger_ids.add(definition_id)
key = (definition_id, session_id)
agg = trigger.setdefault(key, {"run_count": 0, "last_at": None})
agg["run_count"] += 1
if agg["last_at"] is None or _newer(agg["last_at"], created):
agg["last_at"] = created
edges: list[dict[str, Any]] = []
for (src, dst), agg in spawn.items():
edges.append({
"kind": "spawn", "from": src, "to": dst,
"run_count": agg["run_count"],
"last_run_id": agg["last_run_id"], "last_at": _iso_z(agg["last_at"]),
})
for (src, dst), agg in callback.items():
edges.append({
"kind": "callback", "from": src, "to": dst,
"status": agg["status"],
"last_run_id": agg["last_run_id"], "last_at": _iso_z(agg["last_at"]),
})
for (definition_id, dst), agg in trigger.items():
edges.append({
"kind": "trigger", "from": f"def:{definition_id}", "to": dst,
"run_count": agg["run_count"], "last_at": _iso_z(agg["last_at"]),
})
return edges, trigger_ids
def _load_trigger_nodes(conn, trigger_ids: set[str]) -> list[dict[str, Any]]:
if not trigger_ids:
return []
stmt = select(
run_definitions.c.id,
run_definitions.c.definition_type,
run_definitions.c.name,
run_definitions.c.cron,
run_definitions.c.run_at,
run_definitions.c.enabled,
).where(run_definitions.c.id.in_(trigger_ids))
nodes: list[dict[str, Any]] = []
for row in conn.execute(stmt).mappings():
data = dict(row)
nodes.append({
"definition_id": data["id"],
"definition_type": data["definition_type"],
"name": data.get("name"),
"schedule_label": _schedule_label(data),
"enabled": bool(data.get("enabled")),
})
return nodes
def _build_nodes(
session_rows: list[dict[str, Any]],
runs_by_session: dict[str, list[dict[str, Any]]],
live_by_session: dict[str, dict[str, Any]],
) -> list[dict[str, Any]]:
nodes: list[dict[str, Any]] = []
for row in session_rows:
session_id = row["id"]
runs = runs_by_session.get(session_id, [])
live = live_by_session.get(session_id)
status, is_live = _node_status(live["state"] if live else None, runs)
# Hide user-deleted chats (archived session) and sessions under an
# archived project (avibe project scope with scope_settings.enabled=0) —
# other session lists hide both, so they must not reappear as non-live
# history nodes. A live row still shows so its runtime can be ended.
is_archived_project = row.get("scope_scope_type") == "project" and row.get("scope_enabled") == 0
if (row.get("status") == "archived" or is_archived_project) and not is_live:
continue
run_count_total = len(runs)
run_count_running = sum(1 for r in runs if normalize_run_status(r["status"]) == "running")
recent = [
{
"id": r["id"],
"status": normalize_run_status(r["status"]),
"run_type": r.get("run_type"),
"created_at": _iso_z(r.get("created_at")),
"started_at": _iso_z(r.get("started_at")),
"completed_at": _iso_z(r.get("completed_at")),
}
for r in runs[:RUNS_PER_NODE]
]
# A private ``vibe agent run`` session hangs on the legacy
# ``private_agent_run`` pseudo-scope (placeholder platform, no delivery).
# Mirror the running-agents enrichment: render it as an internal run
# (no platform/scope label/project) and not openable — never label it as
# an IM channel session or offer a chat link. M1 re-parents sessions off
# this pseudo-scope, so this branch is a no-op post-migration.
is_private_run = row.get("scope_native_type") == "private_agent_run"
platform = None if is_private_run else row.get("scope_platform")
scope_label = None if is_private_run else _scope_label(
row.get("scope_display_name"), row.get("scope_native_id")
)
project_id = None if is_private_run else _project_id(
row.get("scope_platform"), row.get("scope_scope_type"), row.get("scope_native_id")
)
node: dict[str, Any] = {
"session_id": session_id,
"title": row.get("title"),
"agent_name": row.get("agent_name"),
"agent_display_name": _session_agent_display_name(row),
"agent_backend": row.get("agent_backend"),
"model": row.get("model"),
"reasoning_effort": row.get("reasoning_effort"),
"status": status,
"live": is_live,
"scope_id": row.get("scope_id"),
"project_id": project_id,
"scope_label": scope_label,
"platform": platform,
"workdir": row.get("workdir"),
"openable_in_chat": session_openable_in_chat(
session_id=session_id, scope_native_type=row.get("scope_native_type")
),
"created_at": _iso_z(row.get("created_at")),
"last_active_at": _iso_z(row.get("last_active_at")),
"elapsed_seconds": (live or {}).get("elapsed_seconds") if is_live else None,
"run_counts": {"total": run_count_total, "running": run_count_running},
"runs": recent,
# Legacy rows backfill to foreground (contract §1).
"visibility": row.get("visibility") or "foreground",
}
nodes.append(node)
return nodes
def _filter_nodes(
nodes: list[dict[str, Any]],
*,
project: str,
include_ended: bool,
include_background: bool,
) -> list[dict[str, Any]]:
result = nodes
if not include_ended:
# Active view (contract A5) = non-terminal work: live sessions plus
# queued (accepted-but-not-started) runs. Only terminal non-live nodes
# (succeeded/failed/canceled) are dropped.
result = [n for n in result if n["live"] or n["status"] == "queued"]
if project and project != "all":
if project == "standalone":
result = [n for n in result if not n["scope_id"]]
else:
target = f"avibe::project::{project}"
result = [n for n in result if n["scope_id"] == target]
# A ``system`` session is the RUNTIME's own row (today: the workspace-notifications
# sink that harness failure notices fall back to — see
# ``storage.agent_session_rows.resolve_workspace_notice_session``). It is not agent
# work, has no backend and runs no turns, so it is not a node under EITHER toggle;
# ``include_background`` is a user preference about the user's own hidden sessions and
# does not mean "show me the runtime's". Excluded EXPLICITLY rather than left to the
# ``!= 'background'`` test below, which admits by default: today the row owns no runs
# so it never even becomes a candidate, but a single run pointing at it (a repaired
# ``session_id``, an imported row, a future self-heal run) would otherwise make it a
# History-view node counted as ``foreground``. Pinned by
# ``tests/test_workspace_system_session.py``.
result = [n for n in result if n.get("visibility") != "system"]
if not include_background:
result = [n for n in result if n.get("visibility") != "background"]
return result
def _node_sort_key(node: dict[str, Any]) -> tuple[int, str]:
# Live first, then most-recently-active; deterministic tie-break on id.
activity = node.get("last_active_at") or node.get("created_at") or ""
return (0 if node["live"] else 1, _invert_iso(activity) + node["session_id"])
def _invert_iso(value: str) -> str:
# Sort ISO timestamps descending under an ascending sort by inverting bytes.
return "".join(chr(0x10FFFF - ord(c)) if ord(c) < 0x10FFFF else c for c in value)
def _session_sort_key(row: dict[str, Any], live_ids: set[str]) -> tuple[int, str]:
# Mirror _node_sort_key on a raw session row so candidates can be ranked (and
# capped) before their run histories are loaded.
activity = row.get("last_active_at") or row.get("created_at") or ""
sid = row["id"]
return (0 if sid in live_ids else 1, _invert_iso(activity) + sid)
def _prefilter_candidate_rows(
rows: list[dict[str, Any]],
*,
project: str,
include_background: bool,
live_ids: set[str],
) -> list[dict[str, Any]]:
# The session-level visibility filters that _build_nodes / _filter_nodes also
# apply, hoisted ahead of the run-load cap so hidden rows (archived chats,
# sessions under a disabled project, backgrounds, other projects) can't
# consume the cap and starve visible sessions. include_ended is deliberately
# excluded — it needs the run-derived status, so it stays a post-load filter.
def _hidden(r: dict[str, Any]) -> bool:
# Mirror _build_nodes: archived chat or archived (disabled) project,
# unless the session is live.
if r["id"] in live_ids:
return False
archived_project = r.get("scope_scope_type") == "project" and r.get("scope_enabled") == 0
return r.get("status") == "archived" or archived_project
result = [r for r in rows if not _hidden(r)]
# Mirror _filter_nodes' unconditional ``system`` exclusion here too, so a runtime row
# cannot consume the run-load cap on its way to being dropped.
result = [r for r in result if (r.get("visibility") or "foreground") != "system"]
if not include_background:
result = [r for r in result if (r.get("visibility") or "foreground") != "background"]
if project and project != "all":
if project == "standalone":
result = [r for r in result if not r.get("scope_id")]
else:
target = f"avibe::project::{project}"
result = [r for r in result if r.get("scope_id") == target]
return list(result)
def _cap_nodes(nodes: list[dict[str, Any]], node_cap: int) -> tuple[list[dict[str, Any]], bool]:
ordered = sorted(nodes, key=_node_sort_key)
if len(ordered) > node_cap:
return ordered[:node_cap], True
return ordered, False
def _filter_edges(
edges: list[dict[str, Any]],
node_ids: set[str],
trigger_ids: set[str],
) -> list[dict[str, Any]]:
kept: list[dict[str, Any]] = []
for edge in edges:
if edge["kind"] == "trigger":
definition_id = edge["from"][len("def:"):]
if definition_id in trigger_ids and edge["to"] in node_ids:
kept.append(edge)
else:
if edge["from"] in node_ids and edge["to"] in node_ids:
kept.append(edge)
return kept
def _prune_triggers(
trigger_nodes: list[dict[str, Any]],
edges: list[dict[str, Any]],
) -> list[dict[str, Any]]:
referenced = {e["from"][len("def:"):] for e in edges if e["kind"] == "trigger"}
return [t for t in trigger_nodes if t["definition_id"] in referenced]
def _counts(nodes: list[dict[str, Any]]) -> dict[str, int]:
counts = {
"active": 0, "idle": 0, "orphan": 0, "queued": 0,
"succeeded": 0, "failed": 0, "canceled": 0,
"live": 0, "ended": 0, "background": 0, "foreground": 0, "total": len(nodes),
}
for node in nodes:
status = node["status"]
if status in counts:
counts[status] += 1
if node["live"]:
counts["live"] += 1
else:
counts["ended"] += 1
if node.get("visibility") == "background":
counts["background"] += 1
else:
counts["foreground"] += 1
return counts