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
"""Server-side Dock state: which apps are *installed*, and which of them sit in
the workbench Dock (and in what order).
The Dock is durable *product* state — it follows the user across devices — not
per-browser UI state, so it lives in the shared ``state_meta`` KV under a single
versioned key, alongside the other cross-device workbench state. It knows two
kinds of item:
- built-in apps, keyed by their app id verbatim (``files`` / ``terminal`` /
``editor`` / ``library``). Always installed; individually dockable/undockable.
- pinned Show Pages, keyed ``show:<session_id>``. A pin IS the install record.
Future item kinds (``app:<id>`` …) slot into the same lists without a migration —
see docs/plans/dock-pinned-show-page-apps.md §7 / §7.1c.
Two layers (§7.1c):
- ``pins`` — the *installed* AI pages. Built-ins are implicitly installed.
- ``order`` — the *docked* subset: the resident tiles, in user order. It is a
SUBSET of the known ids {built-ins ∪ pins}; any known id may be absent
(undocked), built-ins included, and the empty Dock is a valid state.
The document is *reconciled on read* (dedupe pins, drop unknown/duplicate order
ids — but never force-append, so an undocked tile stays undocked) and *validated
on write* (order is a subset of the known ids, no duplicates, bounded). An absent
document seeds the default of every built-in docked; once any document exists it
is authoritative, so a stale or corrupt blob can never desync the Dock.
"""
from __future__ import annotations
import threading
from datetime import datetime, timezone
from pathlib import Path
from typing import Any
from core.chat_discovery import get_state_meta, set_state_meta
from core.show_pages import ShowPageError, ShowPageStore, validate_session_id
from storage.sessions_service import read_session_display_meta
# The single state_meta key holding the whole dock document.
DOCK_STATE_KEY = "workbench.dock.v1"
# Every Dock mutation funnels through the single local vibe process — multiple
# devices/tabs are multiple clients of ONE server — so a module lock makes each
# read-modify-write of the document atomic. Without it, two near-simultaneous
# pins both load the same doc and the later ``_save`` silently drops the other's
# pin. This matches the whole ``state_meta`` layer's single-process assumption;
# it does not (and need not here) guard against multiple OS processes.
_DOCK_MUTATION_LOCK = threading.Lock()
# Built-in resident apps, in their canonical Dock order. Mirrors the frontend
# APP_LIST ids (ui/src/apps/registry.tsx); these ids are a stable contract
# shared across the client/server boundary — keep the two in sync.
BUILTIN_DOCK_IDS: tuple[str, ...] = ("files", "terminal", "editor", "library")
# Namespace prefix for a pinned Show Page dock id.
SHOW_PREFIX = "show:"
# Defensive cap so one corrupt/hostile write can't balloon the installed set or
# the order list. ``MAX_PINNED_PAGES`` is the FIXED install budget (not a flat
# constant) so adding a built-in never shrinks it or drops an existing valid pin
# on reconcile; ``MAX_DOCK_ITEMS`` bounds the docked order (≤ built-ins ∪ pins).
# Far above any real Dock.
MAX_PINNED_PAGES = 197
MAX_DOCK_ITEMS = len(BUILTIN_DOCK_IDS) + MAX_PINNED_PAGES
class DockError(ValueError):
"""A bad Dock request (unknown page to pin, invalid order).
``code`` maps to an HTTP status at the route layer: ``*_not_found`` → 404,
everything else → 400.
"""
def __init__(self, message: str, *, code: str) -> None:
super().__init__(message)
self.code = code
def _show_id(session_id: str) -> str:
return f"{SHOW_PREFIX}{session_id}"
def _utc_now_iso() -> str:
return datetime.now(timezone.utc).isoformat()
def _coerce_doc(raw: Any) -> tuple[list[str], list[dict[str, str]]]:
"""Pull a well-typed ``(order, pins)`` out of whatever is stored, tolerating a
missing key, wrong types, or a corrupt blob (→ empty)."""
order: list[str] = []
pins: list[dict[str, str]] = []
if isinstance(raw, dict):
raw_order = raw.get("order")
if isinstance(raw_order, list):
order = [item for item in raw_order if isinstance(item, str)]
raw_pins = raw.get("pins")
if isinstance(raw_pins, list):
for entry in raw_pins:
if not isinstance(entry, dict):
continue
sid = entry.get("session_id")
if not isinstance(sid, str) or not sid:
continue
pins.append(
{
"session_id": sid,
"title_snapshot": str(entry.get("title_snapshot") or ""),
"pinned_at": str(entry.get("pinned_at") or ""),
}
)
return order, pins
def _reconcile(order: list[str], pins: list[dict[str, str]]) -> dict[str, Any]:
"""Canonicalize a dock doc under the two-layer model (§7.1c): dedupe pins by
session id; drop unknown/duplicate order ids. The order is left as the stored
SUBSET — built-ins and pins are NOT force-appended, so an undocked tile
(built-in included) stays undocked and the empty Dock survives a round-trip.
Dropping an order id whose ``show:<sid>`` has no matching pin keeps the Dock
pin-consistent (a removed pin cascades out of the order on the next read).
Pure — the same algorithm runs client-side (reconcileDock in DockContext),
so both ends agree on the canonical shape.
"""
seen_pins: set[str] = set()
deduped_pins: list[dict[str, str]] = []
for pin in pins:
sid = pin["session_id"]
if sid in seen_pins:
continue
seen_pins.add(sid)
deduped_pins.append(pin)
# Clamp on read as well as on write: a corrupt or hand-edited stored doc could
# hold more pins than the write paths admit, so bound them here too (excess
# pins beyond the fixed install budget are dropped) to keep the installed set —
# and GET /api/dock — from ballooning. Same constant the pin path guards on, so
# the two never disagree about what a read would keep.
if len(deduped_pins) > MAX_PINNED_PAGES:
deduped_pins = deduped_pins[:MAX_PINNED_PAGES]
pin_ids = [_show_id(pin["session_id"]) for pin in deduped_pins]
known = set(BUILTIN_DOCK_IDS) | set(pin_ids)
result: list[str] = []
seen: set[str] = set()
for item in order:
if item in known and item not in seen:
result.append(item)
seen.add(item)
return {"order": result, "pins": deduped_pins}
def _load(db_path: Path | None) -> dict[str, Any]:
raw = get_state_meta(DOCK_STATE_KEY, db_path=db_path)
if not isinstance(raw, dict):
# No dock document has ever been stored → seed the default: every built-in
# docked, nothing installed. Only an ABSENT document seeds; a stored doc is
# honored as-is (including an empty/partial order — built-ins are
# undockable now, so "nothing docked" is a legitimate saved state).
return {"order": list(BUILTIN_DOCK_IDS), "pins": []}
order, pins = _coerce_doc(raw)
return _reconcile(order, pins)
def _save(doc: dict[str, Any], db_path: Path | None) -> None:
set_state_meta(DOCK_STATE_KEY, doc, db_path=db_path)
def _resource_context(user_context: Any):
from storage.resource_access_service import resolve_resource_access_context
return resolve_resource_access_context(user_context)
def _filter_dock_for_access(
doc: dict[str, Any],
*,
user_context: Any,
db_path: Path | None,
) -> dict[str, Any]:
if user_context.is_instance_owner:
return doc
store = ShowPageStore(db_path)
try:
accessible_pins = []
for pin in doc["pins"]:
try:
store.require_access(pin["session_id"], user_context=user_context)
except ShowPageError:
continue
accessible_pins.append(pin)
finally:
store.close()
return _reconcile(doc["order"], accessible_pins)
def _require_show_page_management(
session_ids: set[str],
*,
user_context: Any,
db_path: Path | None,
) -> None:
# Dock pin/unpin/reorder require the Instance Owner or the Show Page
# management capability represented by its ACL.
if user_context.is_instance_owner or not session_ids:
return
store = ShowPageStore(db_path)
try:
for session_id in sorted(session_ids):
store.require_management(session_id, user_context=user_context)
finally:
store.close()
def _merge_visible_order(
current_order: list[str],
submitted_order: list[str],
visible_ids: set[str],
) -> list[str]:
"""Replace visible order slots while retaining inaccessible docked items."""
submitted = iter(submitted_order)
merged: list[str] = []
for item in current_order:
if item not in visible_ids:
merged.append(item)
continue
replacement = next(submitted, None)
if replacement is not None:
merged.append(replacement)
merged.extend(submitted)
return merged
def load_dock(*, db_path: Path | None = None, user_context: Any = None) -> dict[str, Any]:
"""Return the reconciled Dock document ``{order, pins}``."""
context = _resource_context(user_context)
return _filter_dock_for_access(_load(db_path), user_context=context, db_path=db_path)
def pin_show_page(
session_id: str,
*,
db_path: Path | None = None,
user_context: Any = None,
) -> dict[str, Any]:
"""Pin a session's Show Page to the Dock (idempotent).
Captures the session's current title as ``title_snapshot`` so the tile stays
labelled even after the session is archived. Raises ``ShowPageError`` for a
malformed id (→ 400) or ``DockError`` when the session has no Show Page
(→ 404). Never creates a page — pinning only records an existing one.
"""
session_id = validate_session_id(session_id)
context = _resource_context(user_context)
store = ShowPageStore(db_path)
try:
try:
store.require_management(session_id, user_context=context)
except ShowPageError as exc:
if exc.code == "show_page_not_found":
raise DockError("This session has no Show Page to pin.", code="show_page_not_found") from exc
raise
finally:
store.close()
# Serialize the whole read-modify-write so a concurrent pin can't lost-update.
with _DOCK_MUTATION_LOCK:
doc = _load(db_path)
if any(pin["session_id"] == session_id for pin in doc["pins"]):
return _filter_dock_for_access(
doc,
user_context=context,
db_path=db_path,
) # already pinned → idempotent no-op (keeps its place + snapshot)
# Bound the installed set to the same fixed budget reconcile clamps to, so
# a new pin can't grow ``pins`` past what a read would keep (which would
# then silently drop the just-added page).
if len(doc["pins"]) >= MAX_PINNED_PAGES:
raise DockError("The Dock is full — unpin an app before pinning another.", code="dock_full")
meta = read_session_display_meta([session_id], db_path=db_path)
title = (meta.get(session_id) or {}).get("title") or ""
doc["pins"].append(
{"session_id": session_id, "title_snapshot": title, "pinned_at": _utc_now_iso()}
)
doc["order"].append(_show_id(session_id))
doc = _reconcile(doc["order"], doc["pins"])
_save(doc, db_path)
return _filter_dock_for_access(doc, user_context=context, db_path=db_path)
def unpin_show_page(
session_id: str,
*,
db_path: Path | None = None,
user_context: Any = None,
) -> dict[str, Any]:
"""Remove a pinned Show Page from the Dock (idempotent; never 404s).
Unpin is Dock-only — it leaves the Show Page itself, its visibility, and any
open windows untouched.
"""
sid = (session_id or "").strip()
show_id = _show_id(sid)
context = _resource_context(user_context)
with _DOCK_MUTATION_LOCK:
doc = _load(db_path)
pinned = any(pin["session_id"] == sid for pin in doc["pins"])
if not pinned and show_id not in doc["order"]:
return _filter_dock_for_access(
doc,
user_context=context,
db_path=db_path,
) # nothing to remove → idempotent no-op
_require_show_page_management({sid}, user_context=context, db_path=db_path)
pins = [pin for pin in doc["pins"] if pin["session_id"] != sid]
order = [item for item in doc["order"] if item != show_id]
doc = _reconcile(order, pins)
_save(doc, db_path)
return _filter_dock_for_access(doc, user_context=context, db_path=db_path)
def set_dock_order(
order: Any,
*,
known: Any = None,
db_path: Path | None = None,
user_context: Any = None,
) -> dict[str, Any]:
"""Persist the docked subset, in order.
Under the two-layer model (§7.1c) the order is a SUBSET of the known ids
(built-ins ∪ pinned pages): every id must be known and unique, but ids may be
OMITTED — that is how a tile (built-in included) is undocked — and the empty
order (nothing docked) is valid. An id that is not a real dock item is still
rejected, so a stale client that references a pin removed by another tab
can't resurrect it.
``known`` is optimistic-concurrency guard: the full id set the client based
this order on. Because omission now means "undock", a stale tab (loaded before
another tab installed a page) would otherwise silently undock the newer pin —
its ``show:<id>`` is simply absent from the stale order, and subset validation
accepts it. So when the client declares ``known`` and it no longer equals the
server's current known set, the write is rejected as stale (the client
re-syncs and retries). When ``known`` is omitted (legacy client) we can't
tell, so subset validation alone applies. Raises ``DockError``
(``invalid_order`` / ``stale_order`` → 400).
"""
if not isinstance(order, list) or not all(isinstance(item, str) for item in order):
raise DockError("Dock order must be a list of ids.", code="invalid_order")
if len(order) > MAX_DOCK_ITEMS:
raise DockError("Dock order is too large.", code="invalid_order")
if len(order) != len(set(order)):
raise DockError("Dock order has duplicate ids.", code="invalid_order")
context = _resource_context(user_context)
has_full_runtime_access = context.is_instance_owner
with _DOCK_MUTATION_LOCK:
doc = _load(db_path)
visible_doc = _filter_dock_for_access(doc, user_context=context, db_path=db_path)
known_doc = doc if has_full_runtime_access else visible_doc
server_known = set(BUILTIN_DOCK_IDS) | {_show_id(pin["session_id"]) for pin in known_doc["pins"]}
if known is not None:
if not isinstance(known, list) or not all(isinstance(item, str) for item in known):
raise DockError("Dock known-set must be a list of ids.", code="invalid_order")
if set(known) != server_known:
raise DockError("Dock order is based on a stale view of the installed apps.", code="stale_order")
if not set(order) <= server_known:
raise DockError("Dock order has an unknown id.", code="invalid_order")
affected_sessions = {
item.removeprefix(SHOW_PREFIX)
for item in {*visible_doc["order"], *order}
if item.startswith(SHOW_PREFIX)
}
_require_show_page_management(affected_sessions, user_context=context, db_path=db_path)
merged_order = (
_merge_visible_order(doc["order"], order, server_known)
if not has_full_runtime_access
else list(order)
)
doc = {"order": merged_order, "pins": doc["pins"]}
_save(doc, db_path)
return _filter_dock_for_access(doc, user_context=context, db_path=db_path)