Co-VibeDocs

Engineering

Session Context Exchange#

A developer's agent publishes its current working context so a teammate's agent can pick up related work without re-discovering decisions. Contexts live in the session_contexts table (see data-model.md) and flow through covibe_session operations.

What a context is#

Structured metadata only:

  • title and a plain-text summary (what I'm doing plus key decisions)
  • files_touched (repo-relative paths), next_actions, blockers, task_ids
  • repo / branch and an optional owning session_id

Never prompts, transcripts, diffs, or file contents. This matches Co-Vibe's privacy stance everywhere else: coordination metadata, not surveillance.

Operations#

  • covibe_session operation: "publish_context" — upserts the caller's context. Publishing again for the same repo/branch supersedes the previous active context (superseded_by). Writes a session.context_published work event and a usage event.
  • covibe_session operation: "get_context" — with developer (handle or id) returns that teammate's active contexts; without it, lists every active context in the workspace. Revoked, superseded, and expired contexts are never returned.
  • covibe_session operation: "revoke_context" — owner withdraws a context immediately. Writes session.context_revoked. Only the owner can revoke.

Every call writes a usage event (covibe_session.publish_context, .get_context, .revoke_context).

TTL#

A context expires 24 hours after publishing by default. ttl_hours (1-168) overrides per publish. Expired rows stop appearing in reads but stay stored for audit.

Privacy rules#

  • Reads pass through the same private-developer redaction as /api/state and covibe_team operation: "state": a developer with visibility = 'private' never appears in another peer's context list, team state, or dashboard.
  • Asking for a private developer by handle returns the same error as asking for a developer who does not exist, so context reads leak no membership signal. Developers always see their own contexts; revocation is immediate.
  • The table is workspace-scoped with the same PostgreSQL row-level-security policy as sibling tables.

Surfacing#

  • covibe_team operation: "state" includes published_contexts (developer, title, summary, repo/branch, timestamps) plus a next-action hint to fetch details with get_context.
  • /api/state returns sessionContexts, rendered read-only in the console's Coordination tab as the "Published contexts" panel (src/features/console/views/redesign/coordination-contexts.tsx): each row shows the title, owner, relative publish time, a repo · branch tag, and counts for files touched / next actions / blockers, with the summary, next actions, blockers, and file list behind an expand toggle.
  • covibe_coordination operation: "handoff" attaches the giving developer's active context reference (id, title, summary) to the handoff payload and response when one exists, preferring a context published for the claim's repo.

Agent workflow#

  1. Publish at meaningful milestones and at session end: after landing a decision, finishing a slice of work, or pausing with known next actions. Include blockers so a teammate's agent does not repeat dead ends.
  2. Before starting work related to a teammate's area, call get_context (directly, or after seeing published_contexts in team state or a handoff context reference) and read the summary, next actions, and blockers first.
  3. Re-publish rather than edit — the newest publish for the same repo/branch replaces the old one. Revoke when the context is wrong or obsolete.
View as .md