@huynle/hub 0.7.3 → 0.8.0

package/packages/protocol/src/concierge.ts

@@ -0,0 +1,366 @@
+// Concierge (C1) shared types: one hub-managed agent per user that watches their sessions, answers status
+// questions and acts under a grant (contract: docs/plans/2026-11-01-concierge-contracts.md).
+
+export const CONCIERGE_ROLE = "concierge"
+export const CONCIERGE_PARTY = "app:concierge"
+/** OpenCode agent the plugin registers for the Concierge session (CON-04). */
+export const CONCIERGE_AGENT = "concierge"
+/**
+ * The only tools a Concierge session is offered (CON-04): an exact allow-list, enforced by the agent's rules and by
+ * the per-turn strip. No subagent/task, execute (Code Mode), web, shell, edit, MCP or plugin tools.
+ */
+export const CONCIERGE_TOOLS = ["hub", "read", "glob", "grep", "question"] as const
+/** Spoke feature for the per-turn session context push (CON-04). */
+export const SESSION_CONTEXT_FEATURE = "sessionContext"
+
+export type ConciergeState = "disabled" | "starting" | "running" | "waiting_machine" | "backoff" | "failed" | "stopping"
+
+export interface ConciergeStatus {
+  readonly state: ConciergeState
+  /** At most 200 characters, written by the hub, never model text. */
+  readonly reason?: string
+  /** The current session (running or starting). */
+  readonly sessionID?: string
+  /** Current and previous Concierge sessions (at most 20), hidden from session lists. */
+  readonly hiddenSessionIDs: readonly string[]
+  readonly launchID?: string
+  readonly machineID?: string
+  /** The @@concierge holder generation. */
+  readonly generation: number
+  readonly since: number
+  /** When the next relaunch is attempted (backoff). */
+  readonly nextAttemptAt?: number
+}
+
+/** Grant verbs the Concierge may hold in C1 (no launch, no roles). */
+export type ConciergeGrantVerb = "approve" | "deny" | "answer" | "prompt" | "stop"
+
+/** What Settings edits; it becomes a real grant whose holder is @@concierge. */
+export interface ConciergeGrantSpec {
+  readonly allow: readonly ConciergeGrantVerb[]
+  /** 1–20 canonical project directories. */
+  readonly projects: readonly string[]
+  readonly permissions: { readonly allow: readonly string[]; readonly never: readonly string[] }
+  readonly allowAlways: boolean
+  /** "1h".."30d", default "30d". */
+  readonly expires: string
+  /** 1–1000, default 60. */
+  readonly maxActionsPerHour: number
+}
+
+/** HH:MM in an IANA time zone. */
+export interface ConciergeQuietHours {
+  readonly start: string
+  readonly end: string
+  readonly timeZone: string
+}
+
+/** HH:MM in the settings' time zone. */
+export interface ConciergeDigest {
+  readonly at: string
+  readonly days?: readonly (0 | 1 | 2 | 3 | 4 | 5 | 6)[]
+}
+
+export interface ConciergeSettings {
+  readonly enabled: boolean
+  /** "hosted" is reserved for C2. */
+  readonly where: "machine"
+  /** Required to enable. */
+  readonly machineID?: string
+  /** Absolute git repo on that machine under its node roots; a checkout, never a branch switch. */
+  readonly directory?: string
+  /** provider/model; absent means the machine default. */
+  readonly model?: string
+  /** Absent means no grant: the Concierge reads and notifies only. */
+  readonly grant?: ConciergeGrantSpec
+  /** Hub-managed, read-only to clients. */
+  readonly grantID?: string
+  readonly connectors: { readonly brain: boolean }
+  /** IANA, default from the device that enabled it. */
+  readonly timeZone: string
+  readonly quietHours?: ConciergeQuietHours
+  /** Default true: priority events still wake it during quiet hours. */
+  readonly quietAllowsUrgent: boolean
+  /** At most 4. */
+  readonly digests: readonly ConciergeDigest[]
+  readonly revision: number
+  readonly updatedAt?: number
+}
+
+export const CONCIERGE_LIMITS = {
+  hiddenHistory: 20,
+  notesBytes: 32_768,
+  digests: 4,
+  relaunchBackoffMs: [15_000, 60_000, 300_000, 900_000, 1_800_000],
+  relaunchesPerHour: 6,
+  healthyAfterMs: 600_000,
+} as const
+
+// ---- Session context (CON-04, spoke feature "sessionContext") ----
+
+/** The keys of the parts a session context carries, appended to the session's system prompt in this order. */
+export const SESSION_CONTEXT_KEYS = ["instructions", "board", "notes"] as const
+export type SessionContextKey = (typeof SESSION_CONTEXT_KEYS)[number]
+
+export const SESSION_CONTEXT_LIMITS = { partChars: 40_000, denyGlobs: 50, globChars: 100, allowTools: 50 } as const
+
+/**
+ * Hub → spoke: a session's per-turn context (feature "sessionContext"). The whole set replaces the previous one;
+ * `clear` drops it (no parts, tools or lock then). The spoke keeps it in memory per session and answers the
+ * revision now effective; an older revision than the effective one is refused ("stale"). `tools.allow`: the exact
+ * tool names the session keeps on every turn (every other tool, including unknown future ones, is removed: fail
+ * closed). `tools.deny`: globs of tool names removed as well. `lockAgent`: conversation mode keeps the session's
+ * agent and model and adds no orchestrator parts.
+ */
+export interface SessionContextRequest {
+  readonly op: "sessionContext"
+  readonly sessionID: string
+  readonly revision: number
+  readonly parts: readonly { readonly key: SessionContextKey; readonly text: string }[]
+  readonly tools?: { readonly allow?: readonly string[]; readonly deny?: readonly string[] }
+  readonly lockAgent?: boolean
+  readonly clear?: true
+}
+
+export interface SessionContextResult {
+  readonly revision: number
+}
+
+const isRecord = (v: unknown): v is Record<string, unknown> => typeof v === "object" && v !== null && !Array.isArray(v)
+const TOOL_GLOB = /^[A-Za-z0-9_.*-]+$/
+const TOOL_NAME = /^[A-Za-z0-9_.-]+$/
+const REQUEST_FIELDS = new Set(["op", "sessionID", "revision", "parts", "tools", "lockAgent", "clear"])
+
+/** Why `v` is not an acceptable sessionContext request, or undefined. Exactly the known fields. */
+export function sessionContextProblem(v: unknown): string | undefined {
+  if (!isRecord(v) || v.op !== "sessionContext") return "op must be sessionContext"
+  for (const key of Object.keys(v)) if (!REQUEST_FIELDS.has(key)) return `unknown field ${key.slice(0, 40)}`
+  if (typeof v.sessionID !== "string" || !v.sessionID || v.sessionID.length > 200) return "sessionID is required"
+  if (!Number.isSafeInteger(v.revision) || (v.revision as number) < 0) return "revision is a whole number ≥ 0"
+  if (!Array.isArray(v.parts) || v.parts.length > SESSION_CONTEXT_KEYS.length) return "parts lists at most one part per key"
+  const seen = new Set<string>()
+  for (const part of v.parts) {
+    if (!isRecord(part) || Object.keys(part).some((k) => k !== "key" && k !== "text")) return "a part is {key, text}"
+    if (!(SESSION_CONTEXT_KEYS as readonly unknown[]).includes(part.key)) return `part key is ${SESSION_CONTEXT_KEYS.join(", ")}`
+    if (seen.has(part.key as string)) return "one part per key"
+    seen.add(part.key as string)
+    if (typeof part.text !== "string" || part.text.length > SESSION_CONTEXT_LIMITS.partChars) return `part text is at most ${SESSION_CONTEXT_LIMITS.partChars} characters`
+  }
+  if (v.tools !== undefined) {
+    if (!isRecord(v.tools) || Object.keys(v.tools).some((k) => k !== "deny" && k !== "allow")) return "tools is {allow?, deny?}"
+    const { deny, allow } = v.tools
+    if (deny !== undefined) {
+      if (!Array.isArray(deny) || deny.length > SESSION_CONTEXT_LIMITS.denyGlobs) return `tools.deny lists at most ${SESSION_CONTEXT_LIMITS.denyGlobs} globs`
+      for (const glob of deny) if (typeof glob !== "string" || glob.length > SESSION_CONTEXT_LIMITS.globChars || !TOOL_GLOB.test(glob)) return "tools.deny holds tool name globs"
+    }
+    if (allow !== undefined) {
+      if (!Array.isArray(allow) || allow.length > SESSION_CONTEXT_LIMITS.allowTools) return `tools.allow lists at most ${SESSION_CONTEXT_LIMITS.allowTools} tool names`
+      for (const name of allow) if (typeof name !== "string" || name.length > SESSION_CONTEXT_LIMITS.globChars || !TOOL_NAME.test(name)) return "tools.allow holds exact tool names (no globs)"
+    }
+    if (deny === undefined && allow === undefined) return "tools is {allow?, deny?}"
+  }
+  if (v.lockAgent !== undefined && typeof v.lockAgent !== "boolean") return "lockAgent is true or false"
+  if (v.clear !== undefined) {
+    if (v.clear !== true) return "clear is true when present"
+    if (v.parts.length || v.tools !== undefined || v.lockAgent !== undefined) return "clear carries no parts, tools or lockAgent"
+  }
+  return undefined
+}
+
+/** Whether tool `name` matches a deny glob (`*` matches any run of characters). */
+export function toolDenied(name: string, deny: readonly string[]): boolean {
+  return deny.some((glob) => (glob.includes("*") ? new RegExp(`^${glob.replace(/[.+?^${}()|[\]\\-]/g, "\\$&").replace(/\*/g, ".*")}$`).test(name) : glob === name))
+}
+
+// ---- Watchlist (CON-01) ----
+
+/** What the Concierge watches: auto-active sessions, pins, explicit sessions, projects and label filters, minus mutes. */
+export interface WatchlistConfig {
+  /** Default true: sessions working, blocked, in error, with an open blocker or Decision, or active lately. */
+  readonly autoActive: boolean
+  /** 1–24, default 8 (bounded by the 24 h journal). */
+  readonly activeWithinHours: number
+  /** Default true: the console's viewPrefs.pinnedSessions and pinnedWorkspaces. */
+  readonly usePins: boolean
+  /** Explicit ses_… IDs (at most 200): Concierge-only pins, never the console's. */
+  readonly sessions: readonly string[]
+  /** Canonical absolute project directories (at most 50). */
+  readonly projects: readonly string[]
+  /** At most 20 filters; one matches a session when all its pairs equal its launch's labels. */
+  readonly labels: readonly Readonly<Record<string, string>>[]
+  /** ses_… IDs (at most 500); beats every include. */
+  readonly muted: readonly string[]
+  /** Canonical absolute project directories (at most 50); beats every include. */
+  readonly mutedProjects: readonly string[]
+  readonly revision: number
+}
+
+export type WatchReason = "active" | "pinned" | "pinned_project" | "explicit" | "project" | "label"
+
+export interface WatchlistEntry {
+  readonly sessionID: string
+  readonly reasons: readonly WatchReason[]
+  readonly lastActiveAt?: number
+}
+
+/** GET /api/agent/concierge/watchlist. */
+export interface WatchlistView {
+  readonly config: WatchlistConfig
+  readonly entries: readonly WatchlistEntry[]
+  readonly truncated: boolean
+}
+
+export const WATCHLIST_LIMITS = { entries: 200, sessions: 200, projects: 50, labels: 20, muted: 500 } as const
+
+export const WATCHLIST_DEFAULTS = { autoActive: true, activeWithinHours: 8, usePins: true } as const
+
+// ---- Session intent (CON-02) ----
+
+/** Who set a session's intent, highest precedence first: user > launch > self > prompt > title. */
+export type IntentSource = "user" | "launch" | "self" | "prompt" | "title"
+
+/** What a session is for: untrusted text (sanitised, one line), never interpreted as instructions. */
+export interface SessionIntent {
+  readonly sessionID: string
+  /** Sanitised, one line, 1–280 characters (INTENT_MAX). */
+  readonly text: string
+  readonly source: IntentSource
+  /** 0 before the hub stored anything for the session (a title fallback). */
+  readonly revision: number
+  readonly updatedAt: number
+  /** Party key of the writer (user, app:…, ses_…); absent for derived intents. */
+  readonly by?: string
+}
+
+export const INTENT_MAX = 280
+
+// ---- Situation board (CON-03) ----
+
+/** A board section, as on the workspace board: ok, omitted (scope), unsupported (not wired) or failed (its source). */
+export type ConciergeBoardSection<T> =
+  | { readonly status: "ok"; readonly items: readonly T[]; readonly truncated: boolean }
+  | { readonly status: "omitted"; readonly reason: "scope"; readonly scope: string }
+  | { readonly status: "unsupported"; readonly feature: string }
+  | { readonly status: "failed" }
+
+export type ConciergeBoardState = "idle" | "working" | "blocked" | "error" | "offline"
+
+export type ConciergeResultOutcome = "turn_done" | "error" | "launch_failed" | "launch_needs_user" | "launch_idle"
+
+/**
+ * (CON-13) A pending blocker the Concierge may act on, by ID (at most CONCIERGE_BOARD_PENDING_MAX per session): a
+ * permission with its action (an enum-like label, "other" otherwise) and `inGrant`, which the hub computes with the
+ * acting engine's own check (would approve once succeed under the @@concierge grant): the model never decides it;
+ * `auto` (CON-13 decision): inGrant and not the tap risk tier, the only ones the Concierge approves itself. A
+ * form with its ID (concierge_form reads its fields). Never summaries, commands or paths.
+ */
+export type ConciergeBoardBlocker =
+  | { readonly kind: "permission"; readonly id: string; readonly action: string; readonly inGrant: boolean; readonly auto: boolean }
+  | { readonly kind: "form"; readonly id: string }
+
+export const CONCIERGE_BOARD_PENDING_MAX = 6
+
+/** One watched root session: IDs, enums, counts and times; `intent`, `title`, `machine`, `project` are untrusted. */
+export interface ConciergeBoardSession {
+  readonly sessionID: string
+  /** The @name slug (with "@"). */
+  readonly name?: string
+  /** Project label (lowercased slug, as the directory has it). */
+  readonly project?: string
+  /** Machine name (sanitised label). */
+  readonly machine?: string
+  readonly state: ConciergeBoardState
+  /** When the current state began, as far as the hub knows (activity, last result, or lastSeen when offline). */
+  readonly since?: number
+  /** reported: false when this hub's catalog does not report the session now (never "none"). */
+  readonly blockers: { readonly reported: false } | { readonly reported: true; readonly count: number; readonly kinds: readonly string[]; readonly pending?: readonly ConciergeBoardBlocker[] }
+  /** Open Decision IDs about this tree (at most 8). */
+  readonly decisions: readonly string[]
+  /** The stored intent (at most 280 characters), untrusted. */
+  readonly intent?: { readonly text: string; readonly source: IntentSource }
+  /** The non-placeholder title (at most 80 characters), untrusted; only when there is no intent. */
+  readonly title?: string
+  readonly lastResult?: { readonly at: number; readonly outcome: ConciergeResultOutcome }
+  readonly reasons: readonly WatchReason[]
+}
+
+export interface ConciergeBoardDecision {
+  readonly id: string
+  /** Party label (sanitised; "@@concierge" for the Concierge's own sessions). */
+  readonly from: string
+  /** Session IDs it concerns. */
+  readonly about: readonly string[]
+  readonly urgency: "low" | "normal" | "high"
+  readonly tier: "confirm" | "tap"
+  readonly at: number
+  readonly deadline?: number
+  /** Under discussion by voice (CON-06). */
+  readonly armed?: true
+}
+
+export interface ConciergeBoardMachine {
+  readonly id: string
+  readonly name: string
+  readonly online: boolean
+}
+
+export interface ConciergeBoard {
+  /** Monotonic per user; changes only when the content (everything but `at`) changes. */
+  readonly revision: number
+  readonly at: number
+  /** At most CONCIERGE_BOARD_LIMITS.sessions, in watchlist order. */
+  readonly sessions: ConciergeBoardSection<ConciergeBoardSession>
+  /** Open, at most CONCIERGE_BOARD_LIMITS.decisions, newest first. */
+  readonly decisions: ConciergeBoardSection<ConciergeBoardDecision>
+  readonly machines: ConciergeBoardSection<ConciergeBoardMachine>
+  readonly counts: { readonly watched: number; readonly working: number; readonly blocked: number; readonly error: number; readonly openDecisions: number }
+}
+
+/** GET /api/agent/concierge/board. */
+export interface ConciergeBoardView {
+  readonly board: ConciergeBoard
+  /** renderBoard(board): the text the Concierge gets, at most CONCIERGE_BOARD_LIMITS.renderedChars. */
+  readonly rendered: string
+}
+
+export const CONCIERGE_BOARD_LIMITS = { sessions: 40, decisions: 20, renderedChars: 12_000, titleChars: 80, decisionsPerSession: 8, machines: 50 } as const
+
+
+// ---- Event-driven turns (CON-05) ----
+
+// ---- Approval tiers (CON-06) ----
+
+/** The verbs a Concierge proposal covers (POST /api/agent/concierge/proposals). */
+export type ConciergeProposalVerb = "stop" | "deny" | "prompt" | "answer"
+
+/** POST /api/agent/concierge/proposals (the current Concierge's act token only) → 201 {decision}. */
+export interface ConciergeProposalBody {
+  readonly verb: ConciergeProposalVerb
+  /** @name, @@role, ses_… (resolved for the user). */
+  readonly session: string
+  /** stop/deny: none; prompt: {text}; answer: {answer} | {cancel: true}. */
+  readonly input?: { readonly text?: string; readonly answer?: Readonly<Record<string, string | number | boolean | readonly string[]>>; readonly cancel?: true }
+  /** The Concierge's reason (≤ whyChars): the recommendation's with `recommend`, else shown after the question. */
+  readonly why?: string
+  /** (CON-09a) The Concierge recommends Do it. Absent/false: no recommendation (the user only asked it to propose). */
+  readonly recommend?: boolean
+  /** deny only. */
+  readonly requestID?: string
+  /** answer only. */
+  readonly formID?: string
+}
+
+/** The hub's tier per proposed verb (never the Concierge's): free text only by a tap. */
+export const CONCIERGE_PROPOSAL_TIERS = { stop: "confirm", deny: "confirm", prompt: "tap", answer: "tap" } as const satisfies Record<ConciergeProposalVerb, "confirm" | "tap">
+
+/** POST/GET /api/agent/concierge/arm → {armed: ConciergeArmed | null}; SSE {type: "concierge", armed}. */
+export interface ConciergeArmed {
+  readonly decisionID: string
+  readonly at: number
+  readonly expiresAt: number
+}
+
+/** How the user answered a Decision (POST /api/decisions/:id/answer `via`; absent = tap). */
+export type DecisionAnswerVia = "tap" | "voice" | "text"
+
+export const CONCIERGE_TIER_LIMITS = { proposalsOpen: 10, proposalsPerHour: 30, armedTtlMs: 120_000, promptChars: 8_000, answerJsonChars: 4_000, whyChars: 1_000 } as const

package/packages/protocol/src/contracts.ts

@@ -0,0 +1,104 @@
+// Shared vocabulary of the workspaces/artifacts/teams contracts (HWA-02, docs/plans/2026-10-30-hub-workspaces-
+// artifacts-contracts.md). Pure: IDs, slugs, bounded text and the expected-revision / idempotency rules every new
+// record follows. Domain modules (hub-workspace.ts, profiles.ts, artifacts.ts, teams.ts, graph.ts) build on it.
+import { UNSAFE_CHARS } from "./wire.ts"
+
+/** Record-schema version of every new record; readers reject other versions rather than guess. */
+export const CONTRACT_VERSION = 1
+
+/** ID prefixes of the new records. An ID is `<prefix>_<16–32 base32/alnum chars>`, minted by the hub. */
+export const ID_PREFIXES = {
+  workspace: "ws",
+  binding: "wsb",
+  member: "wsm",
+  assignment: "asg",
+  supervision: "sup",
+  checkpoint: "chk",
+  sideChat: "chat",
+  profile: "prof",
+  artifact: "art",
+  revision: "rev",
+  blob: "blob",
+  aiJob: "job",
+  team: "team",
+  staffing: "stf",
+  intake: "itk",
+} as const
+export type IdKind = keyof typeof ID_PREFIXES
+
+const ID_BODY = /^[A-Za-z0-9]{16,32}$/
+
+/** True when `v` is a well-formed ID of that kind. */
+export function isContractID(kind: IdKind, v: unknown): v is string {
+  if (typeof v !== "string") return false
+  const prefix = `${ID_PREFIXES[kind]}_`
+  return v.startsWith(prefix) && ID_BODY.test(v.slice(prefix.length))
+}
+
+/** Slugs (team names, role names, profile names): the @name syntax, lowercase letters, digits, dashes, 2–40. */
+export const SLUG = /^[a-z0-9-]{2,40}$/
+export const isSlug = (v: unknown): v is string => typeof v === "string" && SLUG.test(v)
+
+/** One-line labels (titles, role labels): 1–120 characters, no control or format characters. */
+export const LABEL_MAX = 120
+export const isLabel = (v: unknown, max = LABEL_MAX): v is string =>
+  typeof v === "string" && v.trim().length > 0 && v.length <= max && !UNSAFE_CHARS.test(v)
+
+/** Free-form descriptions/instructions: up to `max` characters (newlines allowed, other controls not). */
+export const DESCRIPTION_MAX = 4_000
+const UNSAFE_MULTILINE = /[\u0000-\u0009\u000b-\u001f\u007f\u2028\u2029\u200b-\u200f\u202a-\u202e\u2066-\u2069]/
+export const isText = (v: unknown, max = DESCRIPTION_MAX): v is string => typeof v === "string" && v.length <= max && !UNSAFE_MULTILINE.test(v)
+
+/** Tags and metadata (teams, artifacts, workspaces): bounded, filterable, never secrets. */
+export const TAGS_MAX = 32
+export const METADATA_MAX_KEYS = 32
+export const METADATA_VALUE_MAX = 200
+export function tagsProblem(v: unknown): string | undefined {
+  if (v === undefined) return undefined
+  if (!Array.isArray(v) || v.length > TAGS_MAX) return `tags must be a list of at most ${TAGS_MAX}`
+  if (!v.every(isSlug)) return "each tag must be 2–40 lowercase letters, digits or dashes"
+  if (new Set(v).size !== v.length) return "tags must be unique"
+  return undefined
+}
+export function metadataProblem(v: unknown): string | undefined {
+  if (v === undefined) return undefined
+  if (typeof v !== "object" || v === null || Array.isArray(v)) return "metadata must be an object"
+  const entries = Object.entries(v)
+  if (entries.length > METADATA_MAX_KEYS) return `metadata has more than ${METADATA_MAX_KEYS} keys`
+  for (const [key, value] of entries) {
+    if (!isSlug(key)) return `metadata key ${JSON.stringify(String(key).slice(0, 50))} must be a slug`
+    if (!isLabel(value, METADATA_VALUE_MAX)) return `metadata.${key} must be 1–${METADATA_VALUE_MAX} characters of text`
+  }
+  return undefined
+}
+
+/**
+ * Optimistic concurrency for every mutable record: each record carries `revision` (1 on create, +1 per change).
+ * A mutation names `expectedRevision`; a mismatch is answered 409 `conflict` with `extra.currentRevision`.
+ * Creates take `expectedRevision: 0` implicitly. Revisions are never reused, even after delete.
+ */
+export interface Revisioned {
+  readonly revision: number
+}
+export const isExpectedRevision = (v: unknown): v is number => typeof v === "number" && Number.isSafeInteger(v) && v >= 0
+
+/**
+ * Idempotency: creating mutations (workspace, artifact, revision, AI job, intake, staffing launch) accept an
+ * `Idempotency-Key` header (1–200 of [A-Za-z0-9_.:-]); the same key + same body within IDEMPOTENCY_TTL_MS returns
+ * the original result, a different body under the same key is 409 `conflict`. Keys are per user and per route.
+ */
+export const IDEMPOTENCY_KEY = /^[A-Za-z0-9_.:-]{1,200}$/
+export const IDEMPOTENCY_TTL_MS = 24 * 60 * 60_000
+
+/** Record lifecycle shared by workspaces, teams, profiles and artifacts: archive is reversible, delete is not. */
+export const RECORD_STATES = ["active", "archived"] as const
+export type RecordState = (typeof RECORD_STATES)[number]
+
+/** Bounded list reads: `limit` 1–LIST_LIMIT_MAX (default LIST_LIMIT_DEFAULT) and an opaque `cursor`. */
+export const LIST_LIMIT_DEFAULT = 50
+export const LIST_LIMIT_MAX = 200
+export interface Page<T> {
+  readonly items: readonly T[]
+  /** Absent on the last page. */
+  readonly cursor?: string
+}

package/packages/protocol/src/graph.ts

@@ -0,0 +1,70 @@
+// Interaction graph projection for the Watchtower (HWA-02 contract; API HWA-31, 3D page HWA-32, 2D/teams
+// HWA-38/39). Decisions 5e4l4u8v (page), 50slcj1x (3d-force-graph + force-graph).
+//
+// GET /api/agent/graph?since=&until=&machine=&harness=&team=&tag=&project=&limit= returns a bounded snapshot over
+// the existing registry, message store, Decisions and canonical events. It carries counts and IDs, never message
+// text: edge detail is read through the existing authorized message reads. Quiet machines and sessions are
+// included. Live updates arrive as compact `graph.invalidated` hints; the client re-fetches.
+//
+// History is bounded by message retention (200 per party; 10,000 / 20 MiB per user): `retention.truncated`
+// tells the UI to disclose that older interactions were evicted.
+
+export const GRAPH_LIMITS = {
+  nodes: 2_000,
+  edges: 5_000,
+  /** Longest window a snapshot may cover. */
+  windowMs: 7 * 24 * 60 * 60_000,
+  defaultWindowMs: 24 * 60 * 60_000,
+} as const
+
+export type GraphNodeKind = "hub" | "machine" | "session" | "user" | "team"
+
+export interface GraphNode {
+  readonly id: string
+  readonly kind: GraphNodeKind
+  /** Display label: an @name, machine name or team title. Never a prompt or message. */
+  readonly label: string
+  readonly machineID?: string
+  /**
+   * The harness kind: the reporting process's, else (offline) the last one the hub saw for the session, else its
+   * launch's, else its machine's when the user's processes there all run one harness (RF-02). Absent: unknown.
+   */
+  readonly harness?: string
+  /** Native ancestry (parentID); distinct from supervision. */
+  readonly parentID?: string
+  readonly supervisorID?: string
+  readonly teamIDs?: readonly string[]
+  readonly status?: "idle" | "working" | "blocked" | "error" | "offline" | "ended"
+  readonly tags?: readonly string[]
+  readonly project?: string
+  /** (CON-04) The user's Concierge session (current or previous): hidden from session lists, shown here. */
+  readonly concierge?: true
+}
+
+export interface GraphEdge {
+  readonly id: string
+  readonly from: string
+  readonly to: string
+  readonly kind: "msg" | "ask" | "reply" | "decision" | "launch" | "policy"
+  readonly count: number
+  readonly lastAt: number
+  /** For kind "policy": a permitted team path that may have no traffic (policy-vs-actual overlay). */
+  readonly teamID?: string
+  readonly denied?: number
+}
+
+export interface GraphSnapshot {
+  readonly v: 1
+  readonly at: number
+  readonly window: { readonly since: number; readonly until: number }
+  readonly nodes: readonly GraphNode[]
+  readonly edges: readonly GraphEdge[]
+  readonly retention: { readonly truncated: boolean; readonly oldestAt?: number }
+  /** True when limits cut the snapshot (narrow the filters). */
+  readonly capped: boolean
+}
+
+/** Budget for the lazily loaded Watchtower chunk (three + 3d-force-graph + force-graph), gzip bytes. */
+export const WATCHTOWER_CHUNK_BUDGET = 700 * 1024
+/** @deprecated The page was renamed Watchtower; kept for API stability. Use WATCHTOWER_CHUNK_BUDGET. */
+export const BIRDS_EYE_CHUNK_BUDGET = WATCHTOWER_CHUNK_BUDGET