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
import type { TFunction } from 'i18next';
import type { TranslationKey } from '@/i18n/types';
// Shared types + pure helpers for the Agents · 运行图 (run graph).
//
// The wire shape is the frozen contract in
// `docs/plans/agents-run-graph-contract.md` §3 (GET /api/agents-graph). The
// only addition over that doc is the per-node `runs` array: the detail panel's
// "RUNS · 本会话" timeline needs the recent run rows, and the graph service is
// the one place that already has agent_runs open — embedding them avoids an
// N+1 fetch from the client. It is additive (no frozen field changes) and only
// the graph frontend consumes it.
//
// Everything here is transport/React-agnostic so the layout + forest builders
// stay unit-testable without a canvas.
// ── Wire types (frozen contract §3) ────────────────────────────────────────
// Live nodes carry a running-agents state; non-live nodes carry the latest run
// outcome. `live` on the node distinguishes the two families.
export type AgentGraphLiveStatus = 'active' | 'idle' | 'orphan';
export type AgentGraphTerminalStatus = 'queued' | 'succeeded' | 'failed' | 'canceled';
export type AgentGraphStatus = AgentGraphLiveStatus | AgentGraphTerminalStatus;
export type AgentGraphVisibility = 'foreground' | 'background';
// One recent run for a session (contract amendment A1; drives the detail-panel
// timeline). Elapsed is derived client-side from started/completed.
export type AgentGraphRunRow = {
id: string;
status: string;
run_type: string | null;
created_at: string | null;
started_at: string | null;
completed_at: string | null;
};
export type AgentGraphNode = {
session_id: string;
title: string | null;
agent_name: string | null;
agent_display_name?: string | null;
agent_backend: string | null;
model: string | null;
reasoning_effort: string | null;
status: AgentGraphStatus;
live: boolean;
// Absent until the M1 visibility column ships; absent ⇒ treat as foreground
// AND hide the 移到前台/隐藏 actions (the PATCH would 400 otherwise).
visibility?: AgentGraphVisibility;
scope_id: string | null;
project_id: string | null;
scope_label: string | null;
platform: string | null;
workdir: string | null;
openable_in_chat: boolean;
created_at: string;
last_active_at: string | null;
elapsed_seconds: number | null;
run_counts: { total: number; running: number };
runs?: AgentGraphRunRow[];
};
export type AgentGraphTriggerNode = {
definition_id: string;
// 'scheduled' | 'watch' in practice; kept open for forward definitions.
definition_type: string;
name: string | null;
schedule_label: string | null;
enabled: boolean;
};
export type AgentGraphEdgeKind = 'spawn' | 'callback' | 'trigger';
export type AgentGraphCallbackStatus = 'pending' | 'sent' | 'failed' | 'skipped';
export type AgentGraphEdge = {
kind: AgentGraphEdgeKind;
// session_id, or `def:<definition_id>` for a trigger source.
from: string;
to: string;
run_count?: number;
last_run_id?: string | null;
last_at?: string | null;
// callback edges only.
status?: AgentGraphCallbackStatus | null;
};
export type AgentGraphCounts = {
active: number;
idle: number;
queued: number;
ended: number;
background: number;
foreground: number;
[key: string]: number;
};
export type AgentGraphResult = {
ok: boolean;
generated_at: string;
window: string;
counts: AgentGraphCounts;
nodes: AgentGraphNode[];
trigger_nodes: AgentGraphTriggerNode[];
edges: AgentGraphEdge[];
truncated: boolean;
};
// ── Query params ────────────────────────────────────────────────────────────
export type GraphWindow = '1h' | '6h' | '24h' | '7d';
export const GRAPH_WINDOWS: GraphWindow[] = ['1h', '6h', '24h', '7d'];
// `all` = every project, `standalone` = the NULL-scope (独立) bucket, else a
// concrete project_id. Mirrors the contract's `project` query param.
export type GraphProjectFilter = string; // 'all' | 'standalone' | <project_id>
export type AgentGraphParams = {
window?: GraphWindow;
project?: GraphProjectFilter;
includeEnded?: boolean;
includeBackground?: boolean;
};
// ── Presentation helpers ─────────────────────────────────────────────────────
// The trigger def id encoded on a trigger edge's `from`.
export const TRIGGER_PREFIX = 'def:';
export function triggerRefId(definitionId: string): string {
return `${TRIGGER_PREFIX}${definitionId}`;
}
export function isTriggerRef(ref: string): boolean {
return ref.startsWith(TRIGGER_PREFIX);
}
export function definitionIdFromRef(ref: string): string {
return ref.startsWith(TRIGGER_PREFIX) ? ref.slice(TRIGGER_PREFIX.length) : ref;
}
// A11: disabled trigger chips are hidden by default. A chip only ever appears
// because its definition fired in-window (A10), so this is a pure *display*
// filter over the edge-derived set — the payload is unchanged and the legend
// "show disabled" switch reveals them again. Enabled triggers and every
// spawn/callback edge always pass through; only trigger edges sourced from a
// hidden definition are dropped, so lineage between sessions is never touched.
// Inputs are returned by reference when nothing is filtered, so downstream
// memoized layout stays stable across unrelated refreshes.
export function filterDisabledTriggers(
triggerNodes: AgentGraphTriggerNode[],
edges: AgentGraphEdge[],
showDisabled: boolean,
): { triggerNodes: AgentGraphTriggerNode[]; edges: AgentGraphEdge[] } {
if (showDisabled) return { triggerNodes, edges };
const hiddenRefs = new Set<string>();
const keptTriggers: AgentGraphTriggerNode[] = [];
for (const tr of triggerNodes) {
if (tr.enabled) keptTriggers.push(tr);
else hiddenRefs.add(triggerRefId(tr.definition_id));
}
if (hiddenRefs.size === 0) return { triggerNodes, edges };
return {
triggerNodes: keptTriggers,
edges: edges.filter((e) => !(e.kind === 'trigger' && hiddenRefs.has(e.from))),
};
}
// Sessions a trigger definition fired within the current payload, newest first
// and de-duplicated. Derived from its trigger edges (`from === def:<id>`); drives
// the trigger detail panel's "triggered sessions" list, each row selecting that
// graph node. Callers map the ids through the node set to drop any not rendered.
export function triggerFiredSessionIds(definitionId: string, edges: AgentGraphEdge[]): string[] {
const ref = triggerRefId(definitionId);
const lastAtBySession = new Map<string, string | null | undefined>();
for (const e of edges) {
if (e.kind !== 'trigger' || e.from !== ref) continue;
if (!lastAtBySession.has(e.to) || laterAt(e.last_at, lastAtBySession.get(e.to)) > 0) {
lastAtBySession.set(e.to, e.last_at);
}
}
return [...lastAtBySession.entries()].sort((a, b) => laterAt(b[1], a[1])).map(([id]) => id);
}
// Per-status presentation, in one place (matches the spec frame anu5U). The
// dot/border tone maps to design tokens; `dim` fades ended sessions.
export type StatusTone = 'mint' | 'gold' | 'cyan' | 'muted' | 'destructive';
export type StatusMeta = {
tone: StatusTone;
dotClass: string;
labelKey: TranslationKey;
dim: boolean;
// Which glyph the node header shows: a colored dot, a check, or a cross.
glyph: 'dot' | 'check' | 'cross';
};
const STATUS_META: Record<AgentGraphStatus, StatusMeta> = {
active: { tone: 'mint', dotClass: 'bg-mint', labelKey: 'agents.graph.status.active', dim: false, glyph: 'dot' },
queued: { tone: 'gold', dotClass: 'bg-gold', labelKey: 'agents.graph.status.queued', dim: false, glyph: 'dot' },
idle: { tone: 'muted', dotClass: 'bg-muted', labelKey: 'agents.graph.status.idle', dim: false, glyph: 'dot' },
orphan: { tone: 'gold', dotClass: 'bg-amber-500', labelKey: 'agents.graph.status.orphan', dim: false, glyph: 'dot' },
succeeded: { tone: 'muted', dotClass: 'bg-muted', labelKey: 'agents.graph.status.succeeded', dim: true, glyph: 'check' },
failed: { tone: 'destructive', dotClass: 'bg-destructive', labelKey: 'agents.graph.status.failed', dim: true, glyph: 'cross' },
canceled: { tone: 'muted', dotClass: 'bg-muted', labelKey: 'agents.graph.status.canceled', dim: true, glyph: 'cross' },
};
export function statusMeta(status: AgentGraphStatus): StatusMeta {
return STATUS_META[status] ?? STATUS_META.idle;
}
// A background session is dimmed/eye-off; absent visibility ⇒ foreground.
export function isBackground(node: Pick<AgentGraphNode, 'visibility'>): boolean {
return node.visibility === 'background';
}
// Human-friendly duration: 12 → "12s", 185 → "3m", 3700 → "1h", 259200 → "3d".
// One formatter for every duration the workbench prints, so the graph, the run
// rows and the Harness rows read consistently.
//
// The day unit exists because a Harness watch is not a run: a ``forever`` watch
// waits until something happens, which is routinely days, and "waiting 168h" is
// a number the reader has to divide before it means anything. Runs inherit it
// for free — a three-day run reads the same way.
//
// ``t`` is required rather than optional because the unit is user-visible text:
// an optional translator would leave a path that silently prints English into a
// Chinese UI, which is how "等待 3h" shipped in the first place.
export function formatElapsed(seconds: number | null | undefined, t: TFunction): string {
if (seconds == null) return '—';
const s = Math.max(0, seconds);
if (s < 60) return `${Math.round(s)}${t('common.duration.seconds')}`;
if (s < 3600) return `${Math.floor(s / 60)}${t('common.duration.minutes')}`;
if (s < 86_400) return `${Math.floor(s / 3600)}${t('common.duration.hours')}`;
return `${Math.floor(s / 86_400)}${t('common.duration.days')}`;
}
// Elapsed seconds for a run row: completed − started, or now − started while
// still open. Derived client-side since A1 carries timestamps, not a duration.
export function runElapsedSeconds(
run: Pick<AgentGraphRunRow, 'started_at' | 'completed_at'>,
now: number = Date.now(),
): number | null {
if (!run.started_at) return null;
const start = Date.parse(run.started_at);
if (Number.isNaN(start)) return null;
const end = run.completed_at ? Date.parse(run.completed_at) : now;
return Math.max(0, (end - start) / 1000);
}
// Fallback label when a node has no title: display name + short session suffix.
export function nodeDisplayTitle(
node: Pick<AgentGraphNode, 'title' | 'agent_name' | 'agent_display_name' | 'session_id'>,
): string {
if (node.title && node.title.trim()) return node.title;
const suffix = node.session_id.length > 6 ? node.session_id.slice(-6) : node.session_id;
const agentLabel = node.agent_display_name?.trim() || node.agent_name;
return agentLabel ? `${agentLabel} · ${suffix}` : suffix;
}
// Desktop run-graph fill height (design.pen KfgtJ — canvas fills its container):
// the canvas (and the detail panel beside it) grow to consume the viewport below
// the graph area's top, minus a small bottom gap, floored at a usable minimum so
// a short window can't crush them — below the floor the page scrolls instead.
// Pure so it's unit-testable; the DOM read (window.innerHeight and the graph's
// getBoundingClientRect().top) lives in the component and feeds this. Resizing
// only changes this number — never the dagre layout, which is keyed on the graph
// data alone — so the viewport reflows without a re-layout (mirrors the M3 hover
// principle: size changes touch the viewport, not the node positions).
export function computeFillHeight(
viewportHeight: number,
topOffset: number,
bottomGap: number,
minHeight: number,
): number {
return Math.max(minHeight, Math.round(viewportHeight - topOffset - bottomGap));
}
// ── Lineage derivation (facts panel) ─────────────────────────────────────────
export type NodeLineage = {
// 启动方: caller session that spawned this one (latest spawn edge in).
spawnedBy: string | null;
// 汇报到: callback target + status (callback edge out).
callbackTo: string | null;
callbackStatus: AgentGraphCallbackStatus | null;
// 触发: originating task/watch definition (trigger edge in).
trigger: AgentGraphTriggerNode | null;
};
// Pick the most recent of two ISO timestamps (null sorts oldest).
function laterAt(a: string | null | undefined, b: string | null | undefined): number {
return (a ? Date.parse(a) : 0) - (b ? Date.parse(b) : 0);
}
export function deriveLineage(
sessionId: string,
edges: AgentGraphEdge[],
triggersById: Map<string, AgentGraphTriggerNode>,
): NodeLineage {
let spawnedBy: AgentGraphEdge | null = null;
let callback: AgentGraphEdge | null = null;
let trigger: AgentGraphEdge | null = null;
for (const edge of edges) {
if (edge.kind === 'spawn' && edge.to === sessionId) {
if (!spawnedBy || laterAt(edge.last_at, spawnedBy.last_at) > 0) spawnedBy = edge;
} else if (edge.kind === 'callback' && edge.from === sessionId) {
if (!callback || laterAt(edge.last_at, callback.last_at) > 0) callback = edge;
} else if (edge.kind === 'trigger' && edge.to === sessionId) {
if (!trigger || laterAt(edge.last_at, trigger.last_at) > 0) trigger = edge;
}
}
return {
spawnedBy: spawnedBy ? spawnedBy.from : null,
callbackTo: callback ? callback.to : null,
callbackStatus: callback ? (callback.status ?? 'pending') : null,
trigger: trigger ? triggersById.get(definitionIdFromRef(trigger.from)) ?? null : null,
};
}
// ── Forest builder (mobile grouped list) ─────────────────────────────────────
// One row of the mobile tree list: a node plus its indentation depth and the
// trigger (if any) that spawned its lineage root.
export type ForestRow = {
node: AgentGraphNode;
depth: number;
trigger: AgentGraphTriggerNode | null;
};
// Ranking: live sessions first, then most-recently-active. Deterministic tie
// break on session_id so the list never reshuffles between refreshes.
function nodeOrder(a: AgentGraphNode, b: AgentGraphNode): number {
if (a.live !== b.live) return a.live ? -1 : 1;
const at = laterAt(b.last_active_at ?? b.created_at, a.last_active_at ?? a.created_at);
if (at !== 0) return at;
return a.session_id.localeCompare(b.session_id);
}
// Flatten the spawn forest into indented rows. A node's parent is the latest
// spawn caller that is also present in the node set; nodes with no such parent
// are roots. Cycles and diamonds are guarded by a visited set (each node is
// emitted once, under its latest parent). Triggered roots carry their trigger
// chip so the mobile row can show the Task/Watch source.
export function buildGraphForest(
nodes: AgentGraphNode[],
edges: AgentGraphEdge[],
triggerNodes: AgentGraphTriggerNode[] = [],
): ForestRow[] {
const byId = new Map(nodes.map((n) => [n.session_id, n]));
const triggersById = new Map(triggerNodes.map((tr) => [tr.definition_id, tr]));
// Resolve each node's spawn parent (latest incoming spawn edge whose source
// is a real node) and its trigger source.
const parentOf = new Map<string, string>();
const parentEdgeAt = new Map<string, string | null | undefined>();
const triggerOf = new Map<string, AgentGraphTriggerNode>();
const triggerAtOf = new Map<string, string | null | undefined>();
const childrenOf = new Map<string, string[]>();
for (const edge of edges) {
if (edge.kind === 'spawn' && byId.has(edge.from) && byId.has(edge.to) && edge.from !== edge.to) {
const prev = parentOf.get(edge.to);
if (!prev || laterAt(edge.last_at, parentEdgeAt.get(edge.to)) > 0) {
parentOf.set(edge.to, edge.from);
parentEdgeAt.set(edge.to, edge.last_at);
}
} else if (edge.kind === 'trigger' && byId.has(edge.to)) {
const tr = triggersById.get(definitionIdFromRef(edge.from));
// A session reused by multiple tasks/watches gets one trigger edge per
// definition; keep the latest by last_at so the mobile chip matches the
// detail panel's lineage (which also picks the newest trigger).
if (tr && (!triggerOf.has(edge.to) || laterAt(edge.last_at, triggerAtOf.get(edge.to)) > 0)) {
triggerOf.set(edge.to, tr);
triggerAtOf.set(edge.to, edge.last_at);
}
}
}
for (const [child, parent] of parentOf) {
if (!childrenOf.has(parent)) childrenOf.set(parent, []);
childrenOf.get(parent)!.push(child);
}
const roots = nodes.filter((n) => !parentOf.has(n.session_id)).sort(nodeOrder);
const rows: ForestRow[] = [];
const visited = new Set<string>();
const walk = (node: AgentGraphNode, depth: number, rootTrigger: AgentGraphTriggerNode | null) => {
if (visited.has(node.session_id)) return;
visited.add(node.session_id);
const trigger = triggerOf.get(node.session_id) ?? (depth === 0 ? rootTrigger : null);
rows.push({ node, depth, trigger });
const kids = (childrenOf.get(node.session_id) ?? [])
.map((id) => byId.get(id))
.filter((n): n is AgentGraphNode => !!n)
.sort(nodeOrder);
for (const kid of kids) walk(kid, depth + 1, null);
};
for (const root of roots) walk(root, 0, triggerOf.get(root.session_id) ?? null);
// Any node left unvisited (a cycle with no external root) is surfaced flat so
// it never silently disappears from the list.
for (const node of nodes) if (!visited.has(node.session_id)) rows.push({ node, depth: 0, trigger: null });
return rows;
}