feat: @agor/types package + BackendAdapter + TauriAdapter + ElectrobunAdapter

- packages/types/: shared type definitions (agent, project, btmsg, bttask,
  health, settings, protocol, backend interface)
- BackendAdapter: capability-flagged interface, compile-time selected
- TauriAdapter: wraps Tauri invoke/listen
- ElectrobunAdapter: wraps Electrobun RPC
- src/lib/backend/backend.ts: adapter singleton + setBackendForTesting()
- pnpm-workspace.yaml: workspace setup

packages/types/agent.ts

@@ -0,0 +1,119 @@
+// Agent types — shared between Tauri and Electrobun frontends
+
+// ── Provider ─────────────────────────────────────────────────────────────────
+
+export type ProviderId = 'claude' | 'codex' | 'ollama' | 'aider';
+
+/** What a provider can do — UI gates features on these flags */
+export interface ProviderCapabilities {
+  hasProfiles: boolean;
+  hasSkills: boolean;
+  hasModelSelection: boolean;
+  hasSandbox: boolean;
+  supportsSubagents: boolean;
+  supportsCost: boolean;
+  supportsResume: boolean;
+}
+
+/** Static metadata about a provider */
+export interface ProviderMeta {
+  id: ProviderId;
+  name: string;
+  description: string;
+  capabilities: ProviderCapabilities;
+  /** Name of the sidecar runner file (e.g. 'claude-runner.mjs') */
+  sidecarRunner: string;
+  /** Default model identifier, if applicable */
+  defaultModel?: string;
+  /** Available model presets for dropdown selection */
+  models?: { id: string; label: string }[];
+}
+
+/** Per-provider configuration (stored in settings) */
+export interface ProviderSettings {
+  enabled: boolean;
+  defaultModel?: string;
+  /** Provider-specific config blob */
+  config: Record<string, unknown>;
+}
+
+// ── Agent status ─────────────────────────────────────────────────────────────
+
+export type AgentStatus = 'idle' | 'starting' | 'running' | 'done' | 'error';
+
+// ── Agent message (internal display format) ──────────────────────────────────
+
+export type MsgRole = 'user' | 'assistant' | 'tool-call' | 'tool-result' | 'thinking' | 'system';
+
+export interface AgentMessage {
+  id: string;
+  role: MsgRole;
+  content: string;
+  toolName?: string;
+  toolInput?: string;
+  toolPath?: string;
+  timestamp: number;
+}
+
+// ── Agent message (wire format from sidecar) ─────────────────────────────────
+
+export type AgentMessageType =
+  | 'init'
+  | 'text'
+  | 'thinking'
+  | 'tool_call'
+  | 'tool_result'
+  | 'status'
+  | 'compaction'
+  | 'cost'
+  | 'error'
+  | 'unknown';
+
+export interface AgentWireMessage {
+  id: string;
+  type: AgentMessageType;
+  parentId?: string;
+  content: unknown;
+  timestamp: number;
+}
+
+// ── Agent session state ──────────────────────────────────────────────────────
+
+export interface AgentSession {
+  id: string;
+  sdkSessionId?: string;
+  status: AgentStatus;
+  model?: string;
+  prompt: string;
+  messages: AgentMessage[];
+  costUsd: number;
+  inputTokens: number;
+  outputTokens: number;
+  numTurns: number;
+  durationMs: number;
+  error?: string;
+  // Agent Teams: parent/child hierarchy
+  parentSessionId?: string;
+  parentToolUseId?: string;
+  childSessionIds: string[];
+}
+
+// ── Agent start options (backend-agnostic) ───────────────────────────────────
+
+export interface AgentStartOptions {
+  provider?: ProviderId;
+  sessionId: string;
+  prompt: string;
+  cwd?: string;
+  model?: string;
+  systemPrompt?: string;
+  maxTurns?: number;
+  maxBudgetUsd?: number;
+  permissionMode?: string;
+  settingSources?: string[];
+  claudeConfigDir?: string;
+  additionalDirectories?: string[];
+  worktreeName?: string;
+  providerConfig?: Record<string, unknown>;
+  extraEnv?: Record<string, string>;
+}

packages/types/backend.ts

@@ -0,0 +1,84 @@
+// BackendAdapter — abstraction layer for Tauri and Electrobun backends
+
+import type { AgentStartOptions, AgentMessage, AgentStatus } from './agent.ts';
+import type { FileEntry, FileContent, PtyCreateOptions } from './protocol.ts';
+import type { SettingsMap } from './settings.ts';
+import type { GroupsFile } from './project.ts';
+
+// ── Backend capabilities ─────────────────────────────────────────────────────
+
+export interface BackendCapabilities {
+  /** Can multiplex multiple PTY sessions (Tauri: yes, Electrobun: via daemon) */
+  readonly supportsPtyMultiplexing: boolean;
+  /** Web Worker plugin sandbox available */
+  readonly supportsPluginSandbox: boolean;
+  /** Native OS menu bar integration */
+  readonly supportsNativeMenus: boolean;
+  /** OS keychain for secrets (libsecret on Linux) */
+  readonly supportsOsKeychain: boolean;
+  /** Native file open/save dialogs */
+  readonly supportsFileDialogs: boolean;
+  /** In-app auto-updater (Tauri updater / GitHub Releases) */
+  readonly supportsAutoUpdater: boolean;
+  /** Desktop notifications (notify-rust / OS notification daemon) */
+  readonly supportsDesktopNotifications: boolean;
+  /** OpenTelemetry tracing export */
+  readonly supportsTelemetry: boolean;
+}
+
+// ── Unsubscribe function ─────────────────────────────────────────────────────
+
+/** Call to remove an event listener */
+export type UnsubscribeFn = () => void;
+
+// ── Backend adapter interface ────────────────────────────────────────────────
+
+export interface BackendAdapter {
+  readonly capabilities: BackendCapabilities;
+
+  // ── Lifecycle ────────────────────────────────────────────────────────────
+
+  /** Initialize the backend (connect to IPC, register listeners, etc.) */
+  init(): Promise<void>;
+
+  /** Tear down the backend (disconnect, clean up listeners) */
+  destroy(): Promise<void>;
+
+  // ── Settings ─────────────────────────────────────────────────────────────
+
+  getSetting(key: string): Promise<string | null>;
+  setSetting(key: string, value: string): Promise<void>;
+  getAllSettings(): Promise<SettingsMap>;
+
+  // ── Groups ───────────────────────────────────────────────────────────────
+
+  loadGroups(): Promise<GroupsFile>;
+  saveGroups(groups: GroupsFile): Promise<void>;
+
+  // ── Agent ────────────────────────────────────────────────────────────────
+
+  startAgent(options: AgentStartOptions): Promise<{ ok: boolean; error?: string }>;
+  stopAgent(sessionId: string): Promise<{ ok: boolean; error?: string }>;
+  sendPrompt(sessionId: string, prompt: string): Promise<{ ok: boolean; error?: string }>;
+
+  // ── PTY ──────────────────────────────────────────────────────────────────
+
+  createPty(options: PtyCreateOptions): Promise<string>;
+  writePty(sessionId: string, data: string): Promise<void>;
+  resizePty(sessionId: string, cols: number, rows: number): Promise<void>;
+  closePty(sessionId: string): Promise<void>;
+
+  // ── Files ────────────────────────────────────────────────────────────────
+
+  listDirectory(path: string): Promise<FileEntry[]>;
+  readFile(path: string): Promise<FileContent>;
+  writeFile(path: string, content: string): Promise<void>;
+
+  // ── Events (backend -> frontend) ─────────────────────────────────────────
+
+  onAgentMessage(callback: (sessionId: string, messages: AgentMessage[]) => void): UnsubscribeFn;
+  onAgentStatus(callback: (sessionId: string, status: AgentStatus, error?: string) => void): UnsubscribeFn;
+  onAgentCost(callback: (sessionId: string, costUsd: number, inputTokens: number, outputTokens: number) => void): UnsubscribeFn;
+  onPtyOutput(callback: (sessionId: string, data: string) => void): UnsubscribeFn;
+  onPtyClosed(callback: (sessionId: string, exitCode: number | null) => void): UnsubscribeFn;
+}

packages/types/btmsg.ts

@@ -0,0 +1,67 @@
+// btmsg types — agent messaging system
+
+import type { AgentId, GroupId } from './ids.ts';
+
+export interface BtmsgAgent {
+  id: AgentId;
+  name: string;
+  role: string;
+  groupId: GroupId;
+  tier: number;
+  model: string | null;
+  status: string;
+  unreadCount: number;
+}
+
+export interface BtmsgMessage {
+  id: string;
+  fromAgent: AgentId;
+  toAgent: AgentId;
+  content: string;
+  read: boolean;
+  replyTo: string | null;
+  createdAt: string;
+  senderName?: string;
+  senderRole?: string;
+}
+
+export interface BtmsgChannel {
+  id: string;
+  name: string;
+  groupId: GroupId;
+  createdBy: AgentId;
+  memberCount: number;
+  createdAt: string;
+}
+
+export interface BtmsgChannelMessage {
+  id: string;
+  channelId: string;
+  fromAgent: AgentId;
+  content: string;
+  createdAt: string;
+  senderName: string;
+  senderRole: string;
+}
+
+export interface AgentHeartbeat {
+  agentId: AgentId;
+  timestamp: number;
+}
+
+export interface DeadLetterEntry {
+  id: number;
+  fromAgent: string;
+  toAgent: string;
+  content: string;
+  error: string;
+  createdAt: string;
+}
+
+export interface AuditEntry {
+  id: number;
+  agentId: string;
+  eventType: string;
+  detail: string;
+  createdAt: string;
+}

packages/types/bttask.ts

@@ -0,0 +1,30 @@
+// bttask types — task board system
+
+import type { AgentId, GroupId } from './ids.ts';
+
+export type TaskStatus = 'todo' | 'progress' | 'review' | 'done' | 'blocked';
+export type TaskPriority = 'low' | 'medium' | 'high' | 'critical';
+
+export interface Task {
+  id: string;
+  title: string;
+  description: string;
+  status: TaskStatus;
+  priority: TaskPriority;
+  assignedTo: AgentId | null;
+  createdBy: AgentId;
+  groupId: GroupId;
+  parentTaskId: string | null;
+  sortOrder: number;
+  createdAt: string;
+  updatedAt: string;
+  version: number;
+}
+
+export interface TaskComment {
+  id: string;
+  taskId: string;
+  agentId: AgentId;
+  content: string;
+  createdAt: string;
+}

packages/types/health.ts

@@ -0,0 +1,33 @@
+// Health tracking types
+
+import type { ProjectId, SessionId } from './ids.ts';
+
+export type ActivityState = 'inactive' | 'running' | 'idle' | 'stalled';
+
+export interface ProjectHealth {
+  projectId: ProjectId;
+  sessionId: SessionId | null;
+  /** Current activity state */
+  activityState: ActivityState;
+  /** Name of currently running tool (if any) */
+  activeTool: string | null;
+  /** Duration in ms since last activity (0 if running a tool) */
+  idleDurationMs: number;
+  /** Burn rate in USD per hour (0 if no data) */
+  burnRatePerHour: number;
+  /** Context pressure as fraction 0..1 (null if unknown) */
+  contextPressure: number | null;
+  /** Number of file conflicts (2+ agents writing same file) */
+  fileConflictCount: number;
+  /** Number of external write conflicts */
+  externalConflictCount: number;
+  /** Attention urgency score (higher = more urgent, 0 = no attention needed) */
+  attentionScore: number;
+  /** Human-readable attention reason */
+  attentionReason: string | null;
+}
+
+export interface AttentionItem extends ProjectHealth {
+  projectName: string;
+  projectIcon: string;
+}

packages/types/ids.ts

@@ -0,0 +1,34 @@
+// Branded types for domain identifiers — prevents accidental swapping of IDs across domains.
+// These are compile-time only; at runtime they are plain strings.
+
+/** Unique identifier for an agent session */
+export type SessionId = string & { readonly __brand: 'SessionId' };
+
+/** Unique identifier for a project */
+export type ProjectId = string & { readonly __brand: 'ProjectId' };
+
+/** Unique identifier for a project group */
+export type GroupId = string & { readonly __brand: 'GroupId' };
+
+/** Unique identifier for an agent in the btmsg/bttask system */
+export type AgentId = string & { readonly __brand: 'AgentId' };
+
+/** Create a SessionId from a raw string */
+export function SessionId(value: string): SessionId {
+  return value as SessionId;
+}
+
+/** Create a ProjectId from a raw string */
+export function ProjectId(value: string): ProjectId {
+  return value as ProjectId;
+}
+
+/** Create a GroupId from a raw string */
+export function GroupId(value: string): GroupId {
+  return value as GroupId;
+}
+
+/** Create an AgentId from a raw string */
+export function AgentId(value: string): AgentId {
+  return value as AgentId;
+}

packages/types/index.ts

@@ -0,0 +1,11 @@
+// @agor/types — shared type definitions for Tauri and Electrobun frontends
+
+export * from './ids.ts';
+export * from './agent.ts';
+export * from './project.ts';
+export * from './settings.ts';
+export * from './btmsg.ts';
+export * from './bttask.ts';
+export * from './health.ts';
+export * from './protocol.ts';
+export * from './backend.ts';

packages/types/package.json

@@ -0,0 +1,13 @@
+{
+  "name": "@agor/types",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "main": "index.ts",
+  "types": "index.ts",
+  "exports": {
+    ".": "./index.ts",
+    "./*": "./*.ts"
+  },
+  "files": ["*.ts"]
+}

packages/types/project.ts

@@ -0,0 +1,88 @@
+// Project and Group configuration types
+
+import type { ProviderId } from './agent.ts';
+import type { ProjectId, GroupId, AgentId } from './ids.ts';
+
+// ── Anchor budget ────────────────────────────────────────────────────────────
+
+export type AnchorBudgetScale = 'small' | 'medium' | 'large' | 'full';
+
+// ── Wake strategy ────────────────────────────────────────────────────────────
+
+export type WakeStrategy = 'persistent' | 'on-demand' | 'smart';
+
+// ── Agent roles ──────────────────────────────────────────────────────────────
+
+export type GroupAgentRole = 'manager' | 'architect' | 'tester' | 'reviewer';
+
+// ── Project configuration ────────────────────────────────────────────────────
+
+export interface ProjectConfig {
+  id: ProjectId;
+  name: string;
+  identifier: string;
+  description: string;
+  icon: string;
+  cwd: string;
+  profile: string;
+  enabled: boolean;
+  /** Agent provider for this project (defaults to 'claude') */
+  provider?: ProviderId;
+  /** Model override. Falls back to provider default. */
+  model?: string;
+  /** When true, agents for this project use git worktrees for isolation */
+  useWorktrees?: boolean;
+  /** When true, sidecar process is sandboxed via Landlock */
+  sandboxEnabled?: boolean;
+  /** Shell execution mode for AI agents */
+  autonomousMode?: 'restricted' | 'autonomous';
+  /** Anchor token budget scale (defaults to 'medium' = 6K tokens) */
+  anchorBudgetScale?: AnchorBudgetScale;
+  /** Stall detection threshold in minutes (defaults to 15) */
+  stallThresholdMin?: number;
+  /** True for Tier 1 management agents rendered as project boxes */
+  isAgent?: boolean;
+  /** Agent role (manager/architect/tester/reviewer) -- only when isAgent */
+  agentRole?: GroupAgentRole;
+  /** System prompt injected at session start -- only when isAgent */
+  systemPrompt?: string;
+}
+
+// ── Group-level agent configuration ──────────────────────────────────────────
+
+export interface GroupAgentConfig {
+  id: AgentId;
+  name: string;
+  role: GroupAgentRole;
+  provider?: ProviderId;
+  model?: string;
+  cwd?: string;
+  systemPrompt?: string;
+  enabled: boolean;
+  /** Auto-wake interval in minutes (Manager only, default 3) */
+  wakeIntervalMin?: number;
+  /** Wake strategy */
+  wakeStrategy?: WakeStrategy;
+  /** Wake threshold 0..1 for smart strategy (default 0.5) */
+  wakeThreshold?: number;
+  /** Shell execution mode */
+  autonomousMode?: 'restricted' | 'autonomous';
+}
+
+// ── Group configuration ──────────────────────────────────────────────────────
+
+export interface GroupConfig {
+  id: GroupId;
+  name: string;
+  projects: ProjectConfig[];
+  /** Group-level orchestration agents (Tier 1) */
+  agents?: GroupAgentConfig[];
+}
+
+// ── Groups file (persisted to disk) ──────────────────────────────────────────
+
+export interface GroupsFile {
+  version: number;
+  groups: GroupConfig[];
+  activeGroupId: GroupId;
+}

packages/types/protocol.ts

@@ -0,0 +1,127 @@
+// Unified RPC protocol types — covers both Tauri commands and Electrobun RPC schema
+// These define the request/response shapes for all backend operations.
+
+import type { AgentStartOptions, AgentStatus, AgentWireMessage } from './agent.ts';
+
+// ── PTY ──────────────────────────────────────────────────────────────────────
+
+export interface PtyCreateOptions {
+  sessionId: string;
+  cols: number;
+  rows: number;
+  cwd?: string;
+  shell?: string;
+  args?: string[];
+}
+
+export interface PtyCreateResponse {
+  ok: boolean;
+  sessionId?: string;
+  error?: string;
+}
+
+// ── Files ────────────────────────────────────────────────────────────────────
+
+export interface FileEntry {
+  name: string;
+  path: string;
+  isDir: boolean;
+  size: number;
+  ext?: string;
+}
+
+export type FileContent =
+  | { type: 'Text'; content: string; lang?: string }
+  | { type: 'Binary'; message: string }
+  | { type: 'TooLarge'; size: number };
+
+// ── Settings ─────────────────────────────────────────────────────────────────
+
+export interface SettingEntry {
+  key: string;
+  value: string;
+}
+
+// ── Session persistence ──────────────────────────────────────────────────────
+
+export interface SessionRecord {
+  projectId: string;
+  sessionId: string;
+  provider: string;
+  status: string;
+  costUsd: number;
+  inputTokens: number;
+  outputTokens: number;
+  model: string;
+  error?: string;
+  createdAt: number;
+  updatedAt: number;
+}
+
+export interface SessionMessageRecord {
+  sessionId: string;
+  msgId: string;
+  role: string;
+  content: string;
+  toolName?: string;
+  toolInput?: string;
+  timestamp: number;
+  costUsd?: number;
+  inputTokens?: number;
+  outputTokens?: number;
+}
+
+// ── Agent events (backend -> frontend) ───────────────────────────────────────
+
+export interface AgentMessageEvent {
+  sessionId: string;
+  messages: AgentWireMessage[];
+}
+
+export interface AgentStatusEvent {
+  sessionId: string;
+  status: string;
+  error?: string;
+}
+
+export interface AgentCostEvent {
+  sessionId: string;
+  costUsd: number;
+  inputTokens: number;
+  outputTokens: number;
+}
+
+// ── PTY events (backend -> frontend) ─────────────────────────────────────────
+
+export interface PtyOutputEvent {
+  sessionId: string;
+  /** Base64-encoded or raw UTF-8 data depending on backend */
+  data: string;
+}
+
+export interface PtyClosedEvent {
+  sessionId: string;
+  exitCode: number | null;
+}
+
+// ── Search ───────────────────────────────────────────────────────────────────
+
+export interface SearchResult {
+  resultType: string;
+  id: string;
+  title: string;
+  snippet: string;
+  score: number;
+}
+
+// ── Remote machine ───────────────────────────────────────────────────────────
+
+export type RemoteMachineStatus = 'connecting' | 'connected' | 'disconnected' | 'error';
+
+export interface RemoteMachine {
+  machineId: string;
+  label: string;
+  url: string;
+  status: RemoteMachineStatus;
+  latencyMs: number | null;
+}

packages/types/settings.ts

@@ -0,0 +1,27 @@
+// Settings types — shared key definitions and map type
+
+/** Well-known setting keys used across the application */
+export enum SettingKey {
+  // Appearance
+  Theme = 'theme',
+  UiFontFamily = 'ui_font_family',
+  UiFontSize = 'ui_font_size',
+  TermFontFamily = 'term_font_family',
+  TermFontSize = 'term_font_size',
+
+  // Defaults
+  DefaultShell = 'default_shell',
+  DefaultCwd = 'default_cwd',
+
+  // Agent
+  PermissionMode = 'permission_mode',
+  SystemPromptTemplate = 'system_prompt_template',
+  ProviderSettings = 'provider_settings',
+
+  // Layout
+  SidebarWidth = 'sidebar_width',
+  SidebarCollapsed = 'sidebar_collapsed',
+}
+
+/** Flat key-value settings map (all values are strings) */
+export type SettingsMap = Record<string, string>;

packages/types/tsconfig.json

@@ -0,0 +1,16 @@
+{
+  "compilerOptions": {
+    "strict": true,
+    "target": "ESNext",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "isolatedModules": true,
+    "verbatimModuleSyntax": true
+  },
+  "include": ["*.ts"]
+}