Sessions

// From shared/src/schemas.ts
type Session = {
  // Identity
  id: string                     // Unique session ID (e.g., 'ses_abc123')
  namespace: string              // Namespace for multi-user isolation
  seq: number                    // Database sequence number
  
  // Timestamps
  createdAt: number              // Unix timestamp (ms)
  updatedAt: number              // Last update timestamp
  activeAt: number               // Last activity timestamp
  thinkingAt: number             // Last thinking state change
  
  // Status
  active: boolean                // Is session currently running?
  thinking: boolean              // Is agent currently processing?
  
  // State (versioned)
  metadata: Metadata | null      // Session metadata
  metadataVersion: number        // Metadata version for optimistic concurrency
  agentState: AgentState | null  // Agent state (permissions, control)
  agentStateVersion: number      // Agent state version
  
  // Features
  todos?: TodoItem[]             // Extracted todo items
  permissionMode?: PermissionMode // Current permission mode
  modelMode?: ModelMode          // Current model mode
}

// From shared/src/schemas.ts
type Metadata = {
  // Required
  path: string                   // Working directory
  host: string                   // Hostname
  
  // Optional
  version?: string               // CLI version
  name?: string                  // Custom session name
  os?: string                    // Operating system (e.g., 'darwin', 'linux')
  
  // Summary
  summary?: {
    text: string                 // AI-generated summary
    updatedAt: number            // Summary timestamp
  }
  
  // Agent IDs
  machineId?: string             // Machine ID for remote spawn
  claudeSessionId?: string       // Claude session ID
  codexSessionId?: string        // Codex session ID
  geminiSessionId?: string       // Gemini session ID
  opencodeSessionId?: string     // OpenCode session ID
  cursorSessionId?: string       // Cursor session ID
  
  // Capabilities
  tools?: string[]               // Available tools
  slashCommands?: string[]       // Available slash commands
  
  // Paths
  homeDir?: string               // User home directory
  happyHomeDir?: string          // HAPI home directory (~/.hapi)
  happyLibDir?: string           // HAPI library directory
  happyToolsDir?: string         // HAPI tools directory
  
  // Runner context
  startedFromRunner?: boolean    // Started by runner daemon?
  hostPid?: number               // Host process ID
  startedBy?: 'runner' | 'terminal'
  
  // Lifecycle
  lifecycleState?: string        // Current lifecycle state
  lifecycleStateSince?: number   // State timestamp
  archivedBy?: string            // Who archived it
  archiveReason?: string         // Why archived
  
  // Agent
  flavor?: string | null         // Agent flavor (see Agents page)
  
  // Git worktree
  worktree?: {
    basePath: string             // Base repository path
    branch: string               // Branch name
    name: string                 // Worktree name
    worktreePath?: string        // Full worktree path
    createdAt?: number           // Creation timestamp
  }
}

// From shared/src/schemas.ts
type AgentState = {
  controlledByUser?: boolean     // User has paused agent for manual control
  requests?: Record<string, AgentStateRequest>
  completedRequests?: Record<string, AgentStateCompletedRequest>
}

type AgentStateRequest = {
  tool: string                   // Tool name (e.g., 'edit_file', 'run_command')
  arguments: unknown             // Tool-specific arguments
  createdAt?: number             // Request timestamp
}

{
  "req_123": {
    "tool": "edit_file",
    "arguments": {
      "path": "src/auth.ts",
      "content": "..."
    },
    "createdAt": 1709735200000
  },
  "req_124": {
    "tool": "run_command",
    "arguments": {
      "command": "npm test"
    },
    "createdAt": 1709735210000
  }
}

type AgentStateCompletedRequest = {
  tool: string
  arguments: unknown
  createdAt?: number
  completedAt?: number           // Completion timestamp
  status: 'canceled' | 'denied' | 'approved'
  reason?: string                // User-provided reason for denial
  mode?: string                  // Permission mode at time of request
  decision?: 'approved' | 'approved_for_session' | 'denied' | 'abort'
  allowTools?: string[]          // Tools approved for rest of session
  
  // User answers (for AskUserQuestion / request_user_input)
  answers?: Record<string, string[]> | Record<string, { answers: string[] }>
}

{
  "req_123": {
    "tool": "edit_file",
    "arguments": { "path": "src/auth.ts" },
    "createdAt": 1709735200000,
    "completedAt": 1709735205000,
    "status": "approved",
    "decision": "approved"
  },
  "req_124": {
    "tool": "run_command",
    "arguments": { "command": "npm test" },
    "createdAt": 1709735210000,
    "completedAt": 1709735215000,
    "status": "denied",
    "reason": "Too risky, run locally first",
    "decision": "denied"
  }
}

# REST API
POST /api/sessions/:id/abort

# Result
# - CLI terminates agent process
# - Session becomes inactive
# - active = false
# - Hub broadcasts session-updated event

# REST API
POST /api/sessions/:id/switch

# Result
# - CLI switches to remote mode
# - Terminal shows "Remote mode - waiting for input"
# - Web can now send messages

# REST API
POST /api/sessions/:id/resume

# Requirements
# - Original machine must be online
# - Machine must have runner daemon running
# - Session must be inactive

# Result
# - Runner spawns new CLI process with session ID
# - Session becomes active again
# - Agent continues from last state

# REST API
POST /api/sessions/:id/archive

# Result
# - metadata.lifecycleState = 'archived'
# - metadata.archivedBy = user ID
# - metadata.archiveReason = reason string
# - Session hidden from default views

# REST API
DELETE /api/sessions/:id

# Requirements
# - Session must be inactive

# Result
# - Session and all messages deleted from SQLite
# - Cache entry removed
# - Hub broadcasts session-removed event

// From shared/src/modes.ts
type PermissionMode =
  | 'default'            // Ask for permission (default)
  | 'acceptEdits'        // Auto-approve edits (Claude)
  | 'bypassPermissions'  // Approve everything (Claude YOLO)
  | 'plan'               // Plan mode (Claude/Cursor)
  | 'ask'                // Ask mode (Cursor)
  | 'read-only'          // No file changes (Codex/Gemini)
  | 'safe-yolo'          // Auto-approve safe operations (Codex/Gemini)
  | 'yolo'               // Approve everything (all agents)

POST /api/sessions/:id/permission-mode
Content-Type: application/json

{
  "mode": "acceptEdits"
}

// From shared/src/modes.ts
type ModelMode = 'default' | 'sonnet' | 'opus'

POST /api/sessions/:id/model
Content-Type: application/json

{
  "model": "opus"
}

// CLI creates or resumes session by tag
const session = await api.getOrCreateSession({
  tag: '/home/user/my-project',
  metadata: { ... },
  state: null
})

// Hub returns existing session if tag matches
// Otherwise, creates a new session

// From shared/src/schemas.ts
type TodoItem = {
  id: string                     // Unique todo ID
  content: string                // Todo text
  status: 'pending' | 'in_progress' | 'completed'
  priority: 'high' | 'medium' | 'low'
}

[
  {
    "id": "todo_1",
    "content": "Refactor authentication module",
    "status": "in_progress",
    "priority": "high"
  },
  {
    "id": "todo_2",
    "content": "Add error handling",
    "status": "pending",
    "priority": "medium"
  },
  {
    "id": "todo_3",
    "content": "Write unit tests",
    "status": "completed",
    "priority": "low"
  }
]

// Each session belongs to a namespace
type Session = {
  namespace: string  // e.g., 'default', 'team-a', 'user-123'
  // ...
}

// Hub filters sessions by namespace
function getSessionsByNamespace(namespace: string): Session[] {
  return sessions.filter(s => s.namespace === namespace)
}

# CLI and web both append namespace to token
CLI_API_TOKEN=secret:my-namespace

# Hub extracts namespace from token and assigns to session