<!--
hoody-agent Subskill (sdk)
Auto-generated by Hoody Skills Generator
Generated: 2026-05-06T20:20:32.328Z
Model: mimo-v2.5-pro + fixer:mimo-v2.5-pro
Mode: sdk


Tokens: 41794

DO NOT EDIT MANUALLY - Changes will be overwritten on next generation
-->

# hoody-agent Subskill

## Overview

### What This Service Does

hoody-agent is the AI agent orchestration and task execution service within the Hoody platform. It provides a comprehensive API for managing AI-powered coding sessions, orchestrating complex multi-step workflows, managing workspace configurations, and coordinating background tasks across multiple AI providers and models.

**Core Capabilities:**
- **Session Management** — Create, manage, and interact with AI coding sessions that maintain full conversation history, file diffs, and task state
- **Orchestration Engine** — Multi-phase task orchestration with TODO management, executor dispatch, budget controls, and verification loops
- **Memory System** — Persistent memory blocks, journal entries, and change history for agent context retention
- **MCP Integration** — Model Context Protocol server management for extending agent capabilities
- **MITM Rules** — Man-in-the-middle request interception, transformation, and logging for tool calls
- **Branch Management** — Git worktree-based branch isolation for parallel development workflows
- **Provider Management** — Multi-provider AI model configuration with OAuth authentication flows

### When to Use This Service

| Scenario | Use hoody-agent |
|----------|----------------|
| Start an AI coding session | `client.agent.sessions.create()` |
| Send a prompt to an agent | `client.agent.sessions.prompt()` |
| Manage multi-step project tasks | `client.agent.orchestration.*` |
| Search workspace files | `client.agent.files.*` |
| Configure AI providers | `client.agent.providers.*` |
| Manage persistent agent memory | `client.agent.memory.*` |
| Run background CLI agents | `client.agent.workspaceSession.sessionsCliAgentStart()` |
| Review session quality (RSI) | `client.agent.rsi.rsiReviewStart()` |

### Authentication Model

hoody-agent uses token-based or credential-based authentication via the Hoody SDK:

```
import { HoodyClient } from '@hoody-ai/hoody-sdk'

// Token-based authentication (preferred for production)
const client = new HoodyClient({
  baseURL: 'https://api.hoody.icu',
  token: process.env.HOODY_TOKEN
})

// Credential-based authentication (interactive flows)
const client = await HoodyClient.authenticate(
  'https://api.hoody.icu',
  { username: 'user', password: 'pass' }
)
```

All workspace-scoped endpoints require a valid `workspaceID` parameter. The authenticated user must have access to the specified workspace.

### How It Fits Into Hoody Philosophy

hoody-agent embodies the Hoody principle of **agent-first development**. Rather than treating AI as an add-on, the entire service is designed around the agent lifecycle:

1. **Workspaces** isolate projects and their configurations
2. **Sessions** provide stateful conversation contexts with full history
3. **Orchestration** enables complex multi-phase task decomposition
4. **Memory** ensures agents retain context across sessions
5. **MITM rules** give fine-grained control over agent tool usage
6. **Branches** enable parallel agent workstreams without conflicts

The service automatically handles container routing via the Hoody Proxy pattern:
```
https://{projectId}-{containerId}-{serviceName}-{serviceId}.{node}.containers.hoody.icu
```

---

## Core Resource Workflows

### 1. Health Checks

Verify service availability before performing operations.

```
// Basic health check — no authentication required
const health = await client.agent.health.healthCheck()
console.log(health.status) // "ok"
```

**Response structure:**
```
{
  "status": "ok",
  "version": "1.0.0",
  "uptime": 86400,
  "timestamp": "2025-01-15T10:30:00Z",
  "services": {
    "database": "ok",
    "cache": "ok",
    "queue": "ok"
  },
  "metrics": {
    "activeSessions": 42,
    "pendingJobs": 7
  }
}
```

---

### 2. Workspace Management

Workspaces are the top-level organizational unit. Each workspace maps to a project and can be bound to a container for execution.

#### List All Workspaces

```
const workspaces = await client.agent.workspace.workspacesList(1, 20)
console.log(workspaces.items.length)
console.log(workspaces.total)
```

#### Create a Workspace

```
const workspace = await client.agent.workspace.workspacesCreate({
  name: 'my-project',
  icon: '🚀'
})
console.log(workspace.id) // Use this as workspaceID for all subsequent calls
```

#### Get Workspace Details

```
const details = await client.agent.workspace.workspacesGet({ workspaceID: 'ws_abc123' })
console.log(details.name)
console.log(details.container)
```

#### Update Workspace Properties

```
const updated = await client.agent.workspace.workspacesUpdate('ws_abc123', {
  name: 'renamed-project',
  icon: '⚡'
})
```

#### Delete a Workspace

```
await client.agent.workspace.workspacesDelete({ workspaceID: 'ws_abc123' })
```

#### Container Binding

Bind a container to a workspace for agent execution:

```
// Bind container
await client.agent.workspace.bind('ws_abc123', {
  containerId: 'cnt_xyz789',
  projectId: 'proj_def456',
  node: 'us-east-1'
})

// Unbind container
await client.agent.workspace.unbind({ workspaceID: 'ws_abc123' })
```

**Verification pattern — confirm workspace is ready:**

```
async function ensureWorkspaceReady(client: HoodyClient, workspaceID: string) {
  const ws = await client.agent.workspace.workspacesGet(workspaceID)
  if (!ws.container) {
    throw new Error(`Workspace ${workspaceID} has no container bound`)
  }
  return ws
}
```

---

### 3. Session Lifecycle

Sessions are stateful conversation contexts within a workspace. Each session maintains message history, file changes, and task state.

#### Create a Session

Sessions require permission rules that control what the agent can do:

```
const session = await client.agent.sessions.create('ws_abc123', {
  permission: [
    {
      permission: 'allow',
      pattern: 'file:read:*',
      action: 'approve'
    },
    {
      permission: 'allow',
      pattern: 'file:write:src/**',
      action: 'approve'
    },
    {
      permission: 'deny',
      pattern: 'file:write:.env*',
      action: 'reject'
    }
  ]
})
console.log(session.id) // sessionID for subsequent operations
```

#### List Sessions

```
// Paginated list, newest first
const sessions = await client.agent.sessions.list('ws_abc123', 1, 50)

// Search sessions by title/content
const results = await client.agent.sessions.list('ws_abc123', 1, 20, false, 'refactor auth')

// List only root sessions (not forks)
const roots = await client.agent.sessions.list('ws_abc123', 1, 20, true)
```

#### Get Session Statuses

```
const statuses = await client.agent.sessions.getStatuses({ workspaceID: 'ws_abc123' })
// Returns map of sessionID → { status: 'active' | 'idle' | 'completed' }
```

#### Get Session Details

```
const session = await client.agent.sessions.get({ workspaceID: 'ws_abc123', sessionID: 'sess_001' })
console.log(session.title)
console.log(session.time)
```

#### Update Session Properties

```
const updated = await client.agent.sessions.update('ws_abc123', 'sess_001', {
  title: 'Auth Refactor Session',
  permission: [
    {
      permission: 'allow',
      pattern: 'shell:*',
      action: 'approve'
    }
  ]
})
```

#### Delete a Session

```
// Irreversible — deletes all associated data
await client.agent.sessions.delete({ workspaceID: 'ws_abc123', sessionID: 'sess_001' })
```

#### Session Lifecycle Operations

```
// Abort in-progress AI processing
await client.agent.sessions.abort({ workspaceID: 'ws_abc123', sessionID: 'sess_001' })

// Fork session at a specific message point
const forked = await client.agent.sessions.fork('ws_abc123', 'sess_001', {
  messageID: 'msg_050'
})

// Revert to a specific message (undo subsequent changes)
await client.agent.sessions.revert('ws_abc123', 'sess_001', {
  messageID: 'msg_030'
})

// Restore all reverted messages
await client.agent.sessions.unrevert({ workspaceID: 'ws_abc123', sessionID: 'sess_001' })

// Get child sessions (forks)
const children = await client.agent.sessions.getChildren({ workspaceID: 'ws_abc123', sessionID: 'sess_001' })
```

#### Session Summary and Diff

```
// Lightweight summary — no AI call triggered
const summary = await client.agent.sessions.getSummary({ workspaceID: 'ws_abc123', sessionID: 'sess_001' })
console.log(summary.title)
console.log(summary.tokenTotals)

// Get file changes from the session
const diff = await client.agent.sessions.getDiff({ workspaceID: 'ws_abc123', sessionID: 'sess_001' })

// Get session todo list
const todo = await client.agent.sessions.getTodo({ workspaceID: 'ws_abc123', sessionID: 'sess_001' })
```

#### Export Session

```
await client.agent.sessions.export({ workspaceID: 'ws_abc123', sessionID: 'sess_001' })
```

#### Initialize Workspace Config

```
// Trigger AI-based workspace analysis to generate AGENTS.md
await client.agent.sessions.init('ws_abc123', 'sess_001', {
  providerID: 'openai',
  modelID: 'gpt-4o',
  messageID: 'msg_init'
})
```

#### Session Tags

```
// Update MITM tags on a session
const tagged = await client.agent.sessions.updateTags('ws_abc123', 'sess_001', {
  add: ['production', 'critical'],
  remove: ['experimental']
})
```

---

### 4. Session Communication

#### Send a Message (Streaming)

The primary way to interact with an agent. Returns an SSE stream of the AI response:

```
const response = await client.agent.sessions.prompt('ws_abc123', 'sess_001', {
  model: {
    providerID: 'openai',
    modelID: 'gpt-4o'
  },
  parts: [
    {
      type: 'text',
      text: 'Refactor the authentication module to use JWT tokens',
      time: { start: Date.now() }
    }
  ]
})
```

#### Send a Message with File Context

```
const response = await client.agent.sessions.prompt('ws_abc123', 'sess_001', {
  model: {
    providerID: 'anthropic',
    modelID: 'claude-sonnet-4-20250514'
  },
  parts: [
    {
      type: 'text',
      text: 'Review this file for security issues',
      time: { start: Date.now() }
    },
    {
      type: 'source',
      source: {
        type: 'file',
        path: 'src/auth/login.ts',
        range: {
          start: { line: 1, character: 0 },
          end: { line: 50, character: 0 }
        }
      }
    }
  ]
})
```

#### Send Async Message

```
// Returns immediately, processes in background
await client.agent.sessions.promptAsync('ws_abc123', 'sess_001', {
  model: {
    providerID: 'openai',
    modelID: 'gpt-4o'
  },
  parts: [
    {
      type: 'text',
      text: 'Generate comprehensive tests for the user service',
      time: { start: Date.now() }
    }
  ]
})
```

#### Send a Command

```
await client.agent.sessions.command('ws_abc123', 'sess_001', {
  command: 'format',
  arguments: '--check src/',
  parts: [
    {
      type: 'text',
      mime: 'text/plain',
      url: 'file:///src/index.ts',
      source: {
        text: {
          value: 'const x = 1',
          start: 0,
          end: 11
        },
        type: 'file',
        path: 'src/index.ts',
        range: {
          start: { line: 1, character: 0 },
          end: { line: 1, character: 11 }
        },
        name: 'index.ts',
        kind: 1,
        clientName: 'hoody-agent',
        uri: 'file:///src/index.ts'
      }
    }
  ]
})
```

#### Execute Shell Command

```
const result = await client.agent.sessions.shell('ws_abc123', 'sess_001', {
  agent: 'default',
  model: {
    providerID: 'openai',
    modelID: 'gpt-4o'
  },
  command: 'npm test -- --coverage'
})
```

#### Summarize Session

```
await client.agent.sessions.summarize('ws_abc123', 'sess_001', {
  providerID: 'openai',
  modelID: 'gpt-4o-mini'
})
```

#### List Messages

```
// Chronological order (oldest first), cursor-based pagination
const messages = await client.agent.sessions.listMessages(
  'ws_abc123', 'sess_001', 50, 'assistant'
)

// Incremental fetch using cursor
const next = await client.agent.sessions.listMessages(
  'ws_abc123', 'sess_001', 50, undefined, 'msg_cursor_abc'
)
```

#### Get Specific Message

```
const message = await client.agent.sessions.getMessage(
  'ws_abc123', 'sess_001', 'msg_042'
)
```

#### Update Message

```
await client.agent.sessions.updateMessage(
  'ws_abc123', 'sess_001', 'msg_042', {
    model: { providerID: 'anthropic', modelID: 'claude-sonnet-4-20250514' }
  }
)
```

#### Update/Delete Message Parts

```
// Update a specific part
await client.agent.sessions.updatePart(
  'ws_abc123', 'sess_001', 'msg_042', 'part_001', {
    type: 'text',
    text: 'Updated content'
  }
)

// Delete a specific part
await client.agent.sessions.deletePart(
  'ws_abc123', 'sess_001', 'msg_042', 'part_001'
)
```


---


### 6. Session Background Jobs

Manage background jobs (RSI, self-tuning, CLI agent, bash, webfetch):

#### List Jobs

```
// All jobs
const jobs = await client.agent.workspaceSession.sessionsJobsList(
  'all', 'ws_abc123', 'sess_001'
)

// Active only
const active = await client.agent.workspaceSession.sessionsJobsList(
  'active', 'ws_abc123', 'sess_001'
)
```

#### Get Job Details

```
const job = await client.agent.workspaceSession.sessionsJobsGet(
  'ws_abc123', 'sess_001', 'job_001'
)
```

#### Get Full Job Output

```
const output = await client.agent.workspaceSession.sessionsJobsGetOutput(
  'ws_abc123', 'sess_001', 'job_001'
)
```

#### Cancel a Job

```
await client.agent.workspaceSession.sessionsJobsCancel(
  'ws_abc123', 'sess_001', 'job_001'
)
```

#### Inject Job Results into Session

```
await client.agent.workspaceSession.sessionsJobsInject(
  'ws_abc123', 'sess_001', {
    jobIds: ['job_001', 'job_002']
  }
)
```

---

### 7. CLI Agent Runs

Run external CLI agents (gemini, codex, claude) against the session workspace:

```
// Start a CLI agent run
await client.agent.workspaceSession.sessionsCliAgentStart(
  'ws_abc123', 'sess_001', {
    agent: 'claude',
    prompt: 'Analyze the codebase and suggest improvements'
  }
)

// Stream progress via SSE
const stream = await client.agent.workspaceSession.sessionsCliAgentStream(
  'ws_abc123', 'sess_001', 'job_cli_001'
)
```

---

### 8. RSI (Reviewer-Selected Improvement)

Fan out review passes where configured reviewer models analyze session transcripts:

```
// Start RSI review
await client.agent.rsi.rsiReviewStart('ws_abc123', 'sess_001', {
  reviewers: ['gpt-4o', 'claude-sonnet-4-20250514']
})

// Stream review progress
const stream = await client.agent.rsi.rsiStream(
  'ws_abc123', 'sess_001', 'job_rsi_001'
)
```

---

### 9. Self-Tuning

Run verification-based self-improvement loops:

```
// Single-iteration tune
await client.agent.selfTuning.selfTuningTuneStart('ws_abc123', 'sess_001', {
  verifier: 'test-runner'
})

// Best-of-N amplify (n must be odd, max 11)
await client.agent.selfTuning.selfTuningAmplifyStart('ws_abc123', 'sess_001', {
  n: 5,
  verifier: 'test-runner'
})

// Stream progress
const stream = await client.agent.selfTuning.selfTuningStream(
  'ws_abc123', 'sess_001', 'job_tune_001'
)
```

---

### 10. Orchestration — TODO Management

The Master TODO is the central task list for orchestrated workflows:

#### Read Full TODO State

```
const todo = await client.agent.orchestration.todoRead({ workspaceID: 'ws_abc123' })
```

#### Append TODO Entries

```
const entry = await client.agent.orchestration.todoAppend('ws_abc123', {
  entries: [
    {
      title: 'Implement user authentication',
      description: 'Add JWT-based auth with refresh tokens',
      priority: 1,
      budget_rounds: 10
    },
    {
      title: 'Add rate limiting',
      description: 'Implement sliding window rate limiter',
      priority: 2,
      budget_rounds: 5
    }
  ]
})
```

#### Get TODO Events

```
const events = await client.agent.orchestration.todoGetEvents(1, 50, 'ws_abc123')
```

#### Manage Individual Entries

```
// Get entry details
const entry = await client.agent.orchestration.todoGetEntry({ workspaceID: 'ws_abc123', entryID: 'entry_001' })

// Update status
await client.agent.orchestration.todoSetStatus('ws_abc123', 'entry_001', {
  status: 'in_progress'
})

// Set rounds budget
await client.agent.orchestration.todoSetRounds('ws_abc123', 'entry_001', {
  budget_rounds: 15
})

// Update priority
await client.agent.orchestration.todoSetPriority('ws_abc123', 'entry_001', {
  priority: 1
})

// Delete entry
await client.agent.orchestration.todoDeleteEntry({ workspaceID: 'ws_abc123', entryID: 'entry_001' })
```

#### Entry Spec Management

```
// Read spec
const spec = await client.agent.orchestration.todoReadSpec({ workspaceID: 'ws_abc123', entryID: 'entry_001' })

// Update spec
await client.agent.orchestration.todoUpdateSpec('ws_abc123', 'entry_001', {
  acceptance: ['All tests pass', 'Code coverage > 80%'],
  constraints: ['No breaking changes to public API']
})

// Freeze spec (prevents further modifications)
await client.agent.orchestration.todoFreezeSpec({ workspaceID: 'ws_abc123', entryID: 'entry_001' })
```

---

### 11. Orchestration — Executor

The executor dispatches TODO entries to worker sessions:

#### Executor Control

```
// Get executor status
const status = await client.agent.orchestration.executorGetStatus({ workspaceID: 'ws_abc123' })

// Start dispatch loop
await client.agent.orchestration.executorStart({ workspaceID: 'ws_abc123' })

// Pause dispatching
await client.agent.orchestration.executorPause({ workspaceID: 'ws_abc123' })

// Resume dispatching
await client.agent.orchestration.executorResume({ workspaceID: 'ws_abc123' })

// Stop all workers and pause
await client.agent.orchestration.executorStopAll({ workspaceID: 'ws_abc123' })

// Force dispatch cycle with diagnostics
await client.agent.orchestration.executorForceDispatch({ workspaceID: 'ws_abc123' })
```

#### Worker Management

```
// List active workers
const workers = await client.agent.orchestration.executorGetWorkers({ workspaceID: 'ws_abc123' })

// Stop a specific worker
await client.agent.orchestration.executorStopWorker({ workspaceID: 'ws_abc123', sessionID: 'sess_worker_001' })

// Re-verify an entry (skip worker, use last session)
await client.agent.orchestration.executorReverifyEntry({ workspaceID: 'ws_abc123', entryID: 'entry_001' })

// Get file locks per entry
const locks = await client.agent.orchestration.executorGetLocks({ workspaceID: 'ws_abc123' })
```

---

### 12. Orchestration — Phases

Phases group related TODO entries into sequential execution units:

```
// List all phases
const phases = await client.agent.orchestration.phasesList({ workspaceID: 'ws_abc123' })

// Create phases
const phase = await client.agent.orchestration.phasesCreate('ws_abc123', {
  name: 'Authentication',
  description: 'Implement auth system',
  budget_rounds: 20
})

// Get phase details
const detail = await client.agent.orchestration.phasesGet({ workspaceID: 'ws_abc123', phaseID: 'phase_001' })

// Delete phase (entries are unphased, not deleted)
await client.agent.orchestration.phasesDelete({ workspaceID: 'ws_abc123', phaseID: 'phase_001' })

// Update phase status
await client.agent.orchestration.phasesUpdateStatus('ws_abc123', 'phase_001', {
  status: 'completed'
})

// Add entry to phase
await client.agent.orchestration.phasesAddEntry('ws_abc123', 'phase_001', {
  entryID: 'entry_003'
})

// Update rounds budget
await client.agent.orchestration.phasesUpdateRounds('ws_abc123', 'phase_001', {
  budget_rounds: 30
})

// Trigger verification
await client.agent.orchestration.phasesVerify({ workspaceID: 'ws_abc123', phaseID: 'phase_001' })

// Get phase summary
const summary = await client.agent.orchestration.phasesGetSummary({ workspaceID: 'ws_abc123', phaseID: 'phase_001' })

// Trigger review
await client.agent.orchestration.phasesReview({ workspaceID: 'ws_abc123', phaseID: 'phase_001' })
```

#### Phase Memory

```
// Get memory notes for a phase
const notes = await client.agent.orchestration.phasesListMemory({ workspaceID: 'ws_abc123', phaseID: 'phase_001' })

// Add a note
await client.agent.orchestration.phasesAddMemory('ws_abc123', 'phase_001', {
  note: 'Decided to use bcrypt for password hashing'
})

// Clear phase memory
await client.agent.orchestration.phasesClearMemory({ workspaceID: 'ws_abc123', phaseID: 'phase_001' })

// Get memory for all phases
const allMemory = await client.agent.orchestration.phasesGetAllMemory({ workspaceID: 'ws_abc123' })
```

---

### 13. Orchestration — Budget

Control spending across orchestrated tasks:

```
// Get budget status with per-entry breakdown
const budget = await client.agent.orchestration.budgetGetStatus({ workspaceID: 'ws_abc123' })

// Update global budget
await client.agent.orchestration.budgetUpdateGlobal('ws_abc123', {
  max_spend: 50.00
})

// Edit entry budget
await client.agent.orchestration.budgetEdit('ws_abc123', 'entry_001', {
  budget: 5.00
})

// Toggle budget lock on entry
await client.agent.orchestration.budgetLock({ workspaceID: 'ws_abc123', entryID: 'entry_001' })
```

---

### 14. Orchestration — Questions

Handle interactive prompts from orchestrated agents:

```
// List all pending questions
const questions = await client.agent.orchestration.questionsList({ workspaceID: 'ws_abc123' })

// Get question details
const detail = await client.agent.orchestration.questionsGetDetail(
  'ws_abc123', 'q_001'
)

// Answer a question
await client.agent.orchestration.questionsAnswer('ws_abc123', 'q_001', {
  answer: 'Use PostgreSQL for the database'
})
```

---

### 15. Orchestration — Orchestrator Sessions

Manage the top-level planning session and per-phase sessions:

```
// Get orchestrator session info
const session = await client.agent.orchestration.orchestratorGetSession({ workspaceID: 'ws_abc123' })

// Create or resume orchestrator session
await client.agent.orchestration.orchestratorCreateSession({ workspaceID: 'ws_abc123' })

// Send prompt to orchestrator (with @todo mention resolution)
await client.agent.orchestration.orchestratorSendPrompt('ws_abc123', {
  prompt: 'Plan the implementation of the notification system'
})

// List all orchestrator sessions
const sessions = await client.agent.orchestration.orchestratorListSessions({ workspaceID: 'ws_abc123' })

// Get phase orchestrator session
const phaseSession = await client.agent.orchestration.orchestratorGetPhaseSession(
  'ws_abc123', 'phase_001'
)

// Send prompt to phase orchestrator
await client.agent.orchestration.orchestratorPromptPhase(
  'ws_abc123', 'phase_001', {
    prompt: 'Focus on the OAuth integration first'
  }
)
```

---

### 16. Orchestration — Configuration, Logging, and Events

```
// Get orchestration config
const config = await client.agent.orchestration.getConfig({ workspaceID: 'ws_abc123' })

// Update orchestration config
await client.agent.orchestration.updateConfig('ws_abc123', {
  max_concurrent_workers: 3,
  auto_verify: true
})

// Read tool call log
const log = await client.agent.orchestration.getLog({ workspaceID: 'ws_abc123' })

// Stream tool call log (SSE)
const logStream = await client.agent.orchestration.streamLog({ workspaceID: 'ws_abc123' })

// Stream all orchestration events (supports reconnection)
const events = await client.agent.orchestration.streamEvents({ workspaceID: 'ws_abc123' })

// Get SSE connection count
const connections = await client.agent.orchestration.getEventsConnections({ workspaceID: 'ws_abc123' })

// Get debug dump
const dump = await client.agent.orchestration.getDebugDump({ workspaceID: 'ws_abc123' })

// Purge all orchestration data
await client.agent.orchestration.purge({ workspaceID: 'ws_abc123' })
```

---

### 17. Orchestration — Import and Vault

```
// Start a repo import
await client.agent.orchestration.startImport('ws_abc123', {
  repo: 'https://github.com/org/project',
  branch: 'main'
})

// Get import status
const importStatus = await client.agent.orchestration.getImportStatus(
  'ws_abc123', 'import_job_001'
)

// Discover Master TODOs in Vault
const vaultTodos = await client.agent.orchestration.vaultDiscover({ workspaceID: 'ws_abc123' })

// Import TODO from Vault
await client.agent.orchestration.vaultImport('ws_abc123', {
  todoId: 'vault_todo_001'
})

// Sync local TODO to Vault
await client.agent.orchestration.vaultSync({ workspaceID: 'ws_abc123' })
```

---

### 18. File Operations

Search and read files within a workspace:

```
// Search for text patterns (ripgrep)
const matches = await client.agent.files.search({ pattern: 'TODO|FIXME', workspaceID: 'ws_abc123' })

// Find files by name
const files = await client.agent.files.findByName('*.ts', 'ws_abc123', 'src', 'file', 20)

// Find symbols (LSP)
const symbols = await client.agent.files.findSymbols({ query: 'UserService', workspaceID: 'ws_abc123' })

// List files in directory
const listing = await client.agent.files.list({ path: 'src/auth', workspaceID: 'ws_abc123' })

// Read file content
const content = await client.agent.files.readContent({ path: 'src/auth/login.ts', workspaceID: 'ws_abc123' })

// Get git status of all files
const status = await client.agent.files.getStatus({ workspaceID: 'ws_abc123' })
```

---

### 19. Configuration Management

#### Workspace Configuration

```
// Get current config
const config = await client.agent.config.get({ workspaceID: 'ws_abc123' })

// Update config
await client.agent.config.update('ws_abc123', {
  defaultProvider: 'openai',
  defaultModel: 'gpt-4o'
})

// Get tool overrides
const overrides = await client.agent.config.getToolOverrides({ workspaceID: 'ws_abc123' })
```

#### Provider Configuration

```
// List configured providers and default models
const providers = await client.agent.providers.listConfigs({ workspaceID: 'ws_abc123' })
```

#### Reviewer Configuration

```
// List RSI reviewers
const reviewers = await client.agent.reviewers.configListReviewers({ workspaceID: 'ws_abc123' })
```

#### Verifier Configuration

```
// List self-tuning verifiers
const verifiers = await client.agent.verifiers.configListVerifiers({ workspaceID: 'ws_abc123' })
```

#### CLI Agent Configuration

```
// List CLI agents
const cliAgents = await client.agent.cliAgents.configListCliAgents({ workspaceID: 'ws_abc123' })
```

#### Permission Configuration

```
// Get workspace permission overrides (not merged with global)
const perms = await client.agent.permissions.getOverrides({ workspaceID: 'ws_abc123' })
```

---

### 20. Permissions Management

Handle permission requests from AI assistants:

```
// List all pending permission requests
const requests = await client.agent.permissions.list({ workspaceID: 'ws_abc123' })

// Approve a permission request
await client.agent.permissions.reply('req_001', 'ws_abc123', {
  approved: true,
  reason: 'Required for test execution'
})

// Deny a permission request
await client.agent.permissions.reply('req_002', 'ws_abc123', {
  approved: false,
  reason: 'Access to production database not allowed'
})
```

---

### 21. Provider and OAuth Management

```
// List all available providers
const providers = await client.agent.providers.list({ workspaceID: 'ws_abc123' })

// Get authentication methods
const authMethods = await client.agent.providers.getAuthMethods({ workspaceID: 'ws_abc123' })

// Initiate OAuth authorization
const auth = await client.agent.providers.authorizeOAuth('github', 'ws_abc123', {
  redirectUri: 'https://app.hoody.icu/callback'
})
console.log(auth.url) // Redirect user to this URL

// Handle OAuth callback
await client.agent.providers.callbackOAuth('github', 'ws_abc123', {
  code: 'auth_code_from_callback',
  state: 'state_from_authorize'
})
```

---

### 22. Memory System

#### Memory Blocks

Persistent key-value storage for agent context:

```
// List all memory blocks
const blocks = await client.agent.memory.listBlocks({ workspaceID: 'ws_abc123' })

// List only workspace-scoped blocks
const wsBlocks = await client.agent.memory.listBlocks({ workspaceID: 'ws_abc123' }) // filtered via scope param

// Get a specific block
const block = await client.agent.memory.getBlock({ workspaceID: 'ws_abc123', label: 'project-context' })

// Create or overwrite a block
await client.agent.memory.setBlock('ws_abc123', 'project-context', {
  content: 'This project uses TypeScript with Express.js. Database is PostgreSQL.'
})

// Surgically replace content within a block
await client.agent.memory.replaceBlock('ws_abc123', 'project-context', {
  old: 'Express.js',
  new: 'Fastify'
})

// Delete a block
await client.agent.memory.deleteBlock({ workspaceID: 'ws_abc123', label: 'project-context' })
```

#### Journal Entries

```
// List journal entries
const entries = await client.agent.memory.listJournalEntries({ workspaceID: 'ws_abc123' })

// Create a journal entry
await client.agent.memory.createJournalEntry('ws_abc123', {
  content: 'Migrated auth from sessions to JWT tokens',
  tags: ['auth', 'migration']
})

// Count entries
const count = await client.agent.memory.countJournalEntries({ workspaceID: 'ws_abc123' })

// Get specific entry
const entry = await client.agent.memory.getJournalEntry({ workspaceID: 'ws_abc123', id: 'journal_001' })

// Delete entry
await client.agent.memory.deleteJournalEntry({ workspaceID: 'ws_abc123', id: 'journal_001' })

// Search entries
const results = await client.agent.memory.searchJournalEntries('ws_abc123', {
  query: 'authentication',
  tags: ['auth']
})
```

#### Memory History

```
// List history events
const history = await client.agent.memory.listHistory({ workspaceID: 'ws_abc123' })

// Get specific history event
const event = await client.agent.memory.getHistoryEvent({ workspaceID: 'ws_abc123', id: 'hist_001' })

// Get memory config
const memConfig = await client.agent.memory.getConfig({ workspaceID: 'ws_abc123' })
```

---

### 23. MCP (Model Context Protocol)

Manage MCP servers that extend agent capabilities:

```
// Get status of all MCP servers
const status = await client.agent.mcp.getStatus({ workspaceID: 'ws_abc123' })

// Add a new MCP server
await client.agent.mcp.addServer('ws_abc123', {
  name: 'filesystem',
  command: 'npx',
  args: ['-y', '@modelcontextprotocol/server-filesystem', '/path/to/dir']
})

// Connect an MCP server
await client.agent.mcp.connect({ name: 'filesystem', workspaceID: 'ws_abc123' })

// Disconnect an MCP server
await client.agent.mcp.disconnect({ name: 'filesystem', workspaceID: 'ws_abc123' })
```

#### MCP OAuth Flows

```
// Start OAuth flow
await client.agent.mcp.startOAuth({ workspaceID: 'ws_abc123', name: 'github-mcp' })

// Complete OAuth with callback code
await client.agent.mcp.completeOAuth('ws_abc123', 'github-mcp', {
  code: 'oauth_code',
  state: 'oauth_state'
})

// Authenticate (opens browser, waits for callback)
await client.agent.mcp.authenticateOAuth({ workspaceID: 'ws_abc123', name: 'github-mcp' })

// Remove OAuth credentials
await client.agent.mcp.removeOAuth({ workspaceID: 'ws_abc123', name: 'github-mcp' })
```

---

### 24. Skills Management

```
// Browse marketplace skills
const marketplace = await client.agent.skills.listMarketplace({ workspaceID: 'ws_abc123' })

// Get a skill by name
const skill = await client.agent.skills.get({ workspaceID: 'ws_abc123', name: 'code-review' })

// Create or update a skill
await client.agent.skills.upsert('ws_abc123', 'code-review', {
  description: 'Performs thorough code reviews',
  content: 'Review the code for...',
  scope: 'workspace'
})

// Partially update a skill
await client.agent.skills.update('ws_abc123', 'code-review', {
  description: 'Updated code review skill'
})

// Delete a skill
await client.agent.skills.delete({ workspaceID: 'ws_abc123', name: 'code-review' })

// Toggle built-in skill
await client.agent.skills.toggleBuiltin('ws_abc123', 'web-search', {
  enabled: true
})

// Discover available exec skills
const execSkills = await client.agent.skills.discover()
```

---

### 25. Tools

```
// List all available tools with source and enabled status
const tools = await client.agent.tools.list({ workspaceID: 'ws_abc123' })
```

---

### 26. Project Management

```
// Get current project
const project = await client.agent.project.getCurrent({ workspaceID: 'ws_abc123' })

// Update project properties
await client.agent.project.update('proj_001', 'ws_abc123', {
  name: 'My Project',
  icon: '📦'
})
```

---

### 27. Questions (Session-Level)

Handle questions from AI assistants at the session level:

```
// List all pending questions across sessions
const questions = await client.agent.questions.list({ workspaceID: 'ws_abc123' })

// Reply to a question
await client.agent.questions.reply('req_001', 'ws_abc123', {
  answer: 'Use the v2 API endpoint'
})

// Reject a question
await client.agent.questions.reject({ requestID: 'req_002', workspaceID: 'ws_abc123' })

// Consult another AI model about a question
const advice = await client.agent.questions.consult('req_003', 'ws_abc123', {
  model: 'gpt-4o'
})
```

---

### 28. Web Search and Image Generation

```
// Check web search configuration
const webSearch = await client.agent.webSearch.getStatus({ workspaceID: 'ws_abc123' })

// Check image generation configuration
const imageGen = await client.agent.imageGen.getStatus({ workspaceID: 'ws_abc123' })
```

---

### 29. Experimental Features

```
// List all tool IDs (built-in + dynamic)
const toolIds = await client.agent.experimental.listToolIds({ workspaceID: 'ws_abc123' })

// List tools with JSON schema for a specific provider/model
const toolSchemas = await client.agent.experimental.listToolSchemas(
  'openai', 'gpt-4o', 'ws_abc123'
)

// Get MCP resources from connected servers
const resources = await client.agent.experimental.listMcpResources({ workspaceID: 'ws_abc123' })
```

---

### 30. Meta Information

```
// List available agents
const agents = await client.agent.meta.listAgents({ workspaceID: 'ws_abc123' })

// List available skills
const skills = await client.agent.meta.listSkills({ workspaceID: 'ws_abc123' })

// Get workspace paths
const paths = await client.agent.meta.getPaths({ workspaceID: 'ws_abc123' })

// Get VCS info (git branch, etc.)
const vcs = await client.agent.meta.getVcs({ workspaceID: 'ws_abc123' })

// List available commands
const commands = await client.agent.meta.listCommands({ workspaceID: 'ws_abc123' })

// Get LSP server status
const lsp = await client.agent.meta.getLspStatus({ workspaceID: 'ws_abc123' })

// Get formatter status
const formatter = await client.agent.meta.getFormatterStatus({ workspaceID: 'ws_abc123' })

// Subscribe to server-sent events
const events = await client.agent.meta.subscribeEvents({ workspaceID: 'ws_abc123' })

// Dispose workspace instance (release resources)
await client.agent.meta.dispose({ workspaceID: 'ws_abc123' })
```

---

### 31. Branch Management

Git worktree-based branch isolation for parallel development:

```
// List all branches
const branches = await client.agent.branches.listBranches()

// Create a new branch
const branch = await client.agent.branches.createBranch({
  name: 'feature/auth',
  base: 'main'
})

// Get branch disk usage
const usage = await client.agent.branches.getBranchDiskUsage()

// Get remote info
const remote = await client.agent.branches.getRemoteInfo()

// List remote branches and tags
const refs = await client.agent.branches.listRemoteRefs({ workspaceID: 'origin' })

// Rename branch
await client.agent.branches.renameBranch('branch_001', {
  name: 'feature/jwt-auth'
})

// Delete branch
await client.agent.branches.deleteBranch({ id: 'branch_001' })

// Reset branch to base
await client.agent.branches.resetBranch({ id: 'branch_001' })

// Retry failed branch
await client.agent.branches.retryBranch({ id: 'branch_001' })

// Get branch diff
const diff = await client.agent.branches.getBranchDiff('branch_001', 'main', undefined, 'unified')

// Merge branch
await client.agent.branches.mergeBranch('branch_001', {
  target: 'main'
})

// Get branch git status
const gitStatus = await client.agent.branches.getBranchStatus({ id: 'branch_001' })

// Push to remote
const pushResult = await client.agent.branches.pushBranch('branch_001', {
  remote: 'origin',
  force: false
})

// Pull from remote
const pullResult = await client.agent.branches.pullBranch('branch_001', {
  remote: 'origin'
})

// Get remote tracking status
const tracking = await client.agent.branches.getRemoteStatus({ id: 'branch_001' })

// Get PR/MR status
const prStatus = await client.agent.branches.getPRStatus({ id: 'branch_001' })

// Create pull/merge request
const pr = await client.agent.branches.createPR('branch_001', {
  title: 'Add JWT authentication',
  body: 'Implements JWT-based auth with refresh tokens',
  base: 'main'
})
```

---

### 32. MITM (Man-in-the-Middle) Rules

Control and intercept agent tool calls. MITM endpoints are available via direct HTTP calls to the workspace-scoped API.

**Note:** MITM endpoints are not yet exposed via the SDK client namespace. Use direct HTTP requests to these paths:

#### Snapshot and Rules

```
GET  /api/v1/workspaces/{workspaceID}/mitm/snapshot
GET  /api/v1/workspaces/{workspaceID}/mitm/rules
POST /api/v1/workspaces/{workspaceID}/mitm/rules
PUT  /api/v1/workspaces/{workspaceID}/mitm/rules/{id}
PATCH /api/v1/workspaces/{workspaceID}/mitm/rules/{id}
DELETE /api/v1/workspaces/{workspaceID}/mitm/rules/{id}
POST /api/v1/workspaces/{workspaceID}/mitm/rules/{id}/enable
POST /api/v1/workspaces/{workspaceID}/mitm/rules/{id}/transient-enable
```

#### Logging and Diagnostics

```
GET  /api/v1/workspaces/{workspaceID}/mitm/logs
GET  /api/v1/workspaces/{workspaceID}/mitm/logs/{id}
GET  /api/v1/workspaces/{workspaceID}/mitm/events
GET  /api/v1/workspaces/{workspaceID}/mitm/cooldowns
POST /api/v1/workspaces/{workspaceID}/mitm/diagnostics/dry-run
POST /api/v1/workspaces/{workspaceID}/mitm/diagnostics/match-trace
```

#### Overlay Management

```
POST /api/v1/workspaces/{workspaceID}/mitm/overlay/reset
POST /api/v1/workspaces/{workspaceID}/mitm/overlay/rebase
```

#### Tags and Validation

```
GET  /api/v1/workspaces/{workspaceID}/mitm/tags
POST /api/v1/workspaces/{workspaceID}/mitm/tags
DELETE /api/v1/workspaces/{workspaceID}/mitm/tags/{id}
PATCH /api/v1/workspaces/{workspaceID}/mitm/sessions/{sessionID}/tags
GET  /api/v1/workspaces/{workspaceID}/mitm/validation-rules
GET  /api/v1/workspaces/{workspaceID}/mitm/plugin-descriptors
POST /api/v1/workspaces/{workspaceID}/mitm/webhooks/verify
```

---

### 33. Direct Prompt API

Submit prompts outside of workspace sessions:

```
// Synchronous prompt — waits for full response
const result = await client.agent.prompt.agentPromptSync({
  prompt: 'Explain the Hoody proxy routing system',
  providerID: 'openai',
  modelID: 'gpt-4o'
})

// Streaming prompt (POST) — returns SSE stream
const stream = await client.agent.prompt.agentPrompt({
  prompt: 'Generate a TypeScript utility type',
  providerID: 'openai',
  modelID: 'gpt-4o'
})

// Query-based prompt (GET) — for simple integrations
const result = await client.agent.prompt.agentPromptGet(
  'openai', undefined, undefined, 'gpt-4o', undefined, undefined, undefined, undefined, 'true'
)
```

---

### 34. Live Sessions View

```
// Render HTML sessions wall (designed for iframe embedding)
const html = await client.agent.sessions.listLive()

// Alias for sessions wall
const html2 = await client.agent.sessions.listAll()
```

---

## Advanced Operations

### Full Orchestration Workflow

Complete multi-phase project execution from planning to verification:

```
async function runFullOrchestration(client: HoodyClient, workspaceID: string) {
  // 1. Create orchestrator session
  await client.agent.orchestration.orchestratorCreateSession(workspaceID)

  // 2. Define phases
  const phase1 = await client.agent.orchestration.phasesCreate(workspaceID, {
    name: 'Backend API',
    description: 'Implement REST API endpoints',
    budget_rounds: 20
  })

  const phase2 = await client.agent.orchestration.phasesCreate(workspaceID, {
    name: 'Frontend Integration',
    description: 'Connect frontend to API',
    budget_rounds: 15
  })

  // 3. Add TODO entries to phases
  await client.agent.orchestration.todoAppend(workspaceID, {
    entries: [
      {
        title: 'User CRUD endpoints',
        description: 'Create REST endpoints for user management',
        priority: 1,
        budget_rounds: 10
      },
      {
        title: 'Auth middleware',
        description: 'Implement JWT verification middleware',
        priority: 1,
        budget_rounds: 8
      }
    ]
  })

  // 4. Set global budget
  await client.agent.orchestration.budgetUpdateGlobal(workspaceID, {
    max_spend: 100.00
  })

  // 5. Start executor
  await client.agent.orchestration.executorStart(workspaceID)

  // 6. Monitor progress
  const status = await client.agent.orchestration.executorGetStatus(workspaceID)
  console.log('Executor status:', status)

  // 7. Handle questions as they arise
  const questions = await client.agent.orchestration.questionsList(workspaceID)
  for (const q of questions) {
    await client.agent.orchestration.questionsAnswer(workspaceID, q.id, {
      answer: 'Proceed with the recommended approach'
    })
  }

  // 8. Verify phases
  await client.agent.orchestration.phasesVerify(workspaceID, phase1.id)
  await client.agent.orchestration.phasesVerify(workspaceID, phase2.id)

  // 9. Sync to vault
  await client.agent.orchestration.vaultSync(workspaceID)
}
```

### Session with Background Jobs

Run multiple background tasks and inject results:

```
async function runWithBackgroundJobs(client: HoodyClient, workspaceID: string) {
  // Create session
  const session = await client.agent.sessions.create(workspaceID, {
    permission: [
      { permission: 'allow', pattern: '*', action: 'approve' }
    ]
  })

  // Start CLI agent in background
  await client.agent.workspaceSession.sessionsCliAgentStart(
    workspaceID, session.id, {
      agent: 'claude',
      prompt: 'Analyze codebase architecture'
    }
  )

  // Start RSI review in background
  await client.agent.rsi.rsiReviewStart(workspaceID, session.id, {
    reviewers: ['gpt-4o']
  })

  // Poll for job completion
  const jobs = await client.agent.workspaceSession.sessionsJobsList(
    'active', workspaceID, session.id
  )

  // Wait for jobs to complete, then inject results
  await client.agent.workspaceSession.sessionsJobsInject(
    workspaceID, session.id, {
      jobIds: jobs.map(j => j.id)
    }
  )

  // Send prompt that benefits from injected context
  await client.agent.sessions.promptAsync(workspaceID, session.id, {
    model: { providerID: 'openai', modelID: 'gpt-4o' },
    parts: [
      {
        type: 'text',
        text: 'Based on the analysis and review, create an implementation plan',
        time: { start: Date.now() }
      }
    ]
  })
}
```

### Branch-Based Parallel Development

```
async function parallelDevelopment(client: HoodyClient, workspaceID: string) {
  // Create feature branches
  const authBranch = await client.agent.branches.createBranch({
    name: 'feature/auth',
    base: 'main'
  })

  const apiBranch = await client.agent.branches.createBranch({
    name: 'feature/api',
    base: 'main'
  })

  // Create sessions for each branch
  const authSession = await client.agent.sessions.create(workspaceID, {
    permission: [{ permission: 'allow', pattern: '*', action: 'approve' }]
  })

  const apiSession = await client.agent.sessions.create(workspaceID, {
    permission: [{ permission: 'allow', pattern: '*', action: 'approve' }]
  })

  // Work on auth branch
  await client.agent.sessions.promptAsync(workspaceID, authSession.id, {
    model: { providerID: 'openai', modelID: 'gpt-4o' },
    parts: [{
      type: 'text',
      text: 'Implement JWT authentication',
      time: { start: Date.now() }
    }]
  })

  // Work on API branch simultaneously
  await client.agent.sessions.promptAsync(workspaceID, apiSession.id, {
    model: { providerID: 'openai', modelID: 'gpt-4o' },
    parts: [{
      type: 'text',
      text: 'Create REST API endpoints',
      time: { start: Date.now() }
    }]
  })

  // Check diffs
  const authDiff = await client.agent.branches.getBranchDiff(authBranch.id)
  const apiDiff = await client.agent.branches.getBranchDiff(apiBranch.id)

  // Merge when ready
  await client.agent.branches.mergeBranch(authBranch.id, { target: 'main' })
  await client.agent.branches.mergeBranch(apiBranch.id, { target: 'main' })

  // Create PR
  await client.agent.branches.createPR(authBranch.id, {
    title: 'Add JWT Authentication',
    body: 'Implements complete auth system',
    base: 'main'
  })
}
```

### Memory-Augmented Session

```
async function memoryAugmentedWorkflow(client: HoodyClient, workspaceID: string) {
  // Load existing memory context
  const context = await client.agent.memory.getBlock(workspaceID, 'project-context')
  const journal = await client.agent.memory.listJournalEntries(workspaceID)

  // Create session with context
  const session = await client.agent.sessions.create(workspaceID, {
    permission: [{ permission: 'allow', pattern: '*', action: 'approve' }]
  })

  // Send prompt referencing memory
  await client.agent.sessions.prompt(workspaceID, session.id, {
    model: { providerID: 'openai', modelID: 'gpt-4o' },
    parts: [{
      type: 'text',
      text: `Continue work based on project context: ${context.content}`,
      time: { start: Date.now() }
    }]
  })

  // Update memory with new learnings
  await client.agent.memory.setBlock(workspaceID, 'last-session-notes', {
    content: 'Completed auth module. Next: rate limiting.'
  })

  // Journal the progress
  await client.agent.memory.createJournalEntry(workspaceID, {
    content: 'Auth module completed with JWT + refresh tokens',
    tags: ['auth', 'completed']
  })
}
```

### Error Recovery Pattern

```
async function resilientOrchestration(client: HoodyClient, workspaceID: string) {
  try {
    await client.agent.orchestration.executorStart(workspaceID)
  } catch (error) {
    // If executor fails, check status and recover
    const status = await client.agent.orchestration.executorGetStatus(workspaceID)

    if (status.state === 'paused') {
      await client.agent.orchestration.executorResume(workspaceID)
    } else if (status.state === 'error') {
      // Stop all and restart
      await client.agent.orchestration.executorStopAll(workspaceID)
      await client.agent.orchestration.executorStart(workspaceID)
    }
  }

  // Retry failed entries
  const workers = await client.agent.orchestration.executorGetWorkers(workspaceID)
  for (const worker of workers) {
    if (worker.status === 'failed') {
      await client.agent.orchestration.executorReverifyEntry(
        workspaceID, worker.entryID
      )
    }
  }
}
```

### MCP Server Lifecycle

```
async function setupMcpServers(client: HoodyClient, workspaceID: string) {
  // Add multiple MCP servers
  await client.agent.mcp.addServer(workspaceID, {
    name: 'filesystem',
    command: 'npx',
    args: ['-y', '@modelcontextprotocol/server-filesystem', '/workspace']
  })

  await client.agent.mcp.addServer(workspaceID, {
    name: 'github',
    command: 'npx',
    args: ['-y', '@modelcontextprotocol/server-github']
  })

  // Authenticate OAuth-based server
  await client.agent.mcp.authenticateOAuth(workspaceID, 'github')

  // Connect all servers
  await client.agent.mcp.connect('filesystem', workspaceID)
  await client.agent.mcp.connect('github', workspaceID)

  // Verify connections
  const status = await client.agent.mcp.getStatus(workspaceID)
  console.log('MCP servers:', status)

  // Get available resources
  const resources = await client.agent.experimental.listMcpResources(workspaceID)
}
```

---

## Quick Reference

### Endpoint Groups Summary

| Group | SDK Namespace | Key Methods | Count |
|-------|--------------|-------------|-------|
| Health | `client.agent.health` | `healthCheck` | 1 |
| Workspaces | `client.agent.workspace` | `workspacesList`, `workspacesCreate`, `workspacesGet`, `workspacesUpdate`, `workspacesDelete`, `bind`, `unbind` | 7 |
| Sessions | `client.agent.sessions` | `list`, `create`, `get`, `update`, `delete`, `prompt`, `promptAsync`, `command`, `shell`, `abort`, `fork`, `revert`, `export`, `summarize` | 30 |
| RSI | `client.agent.rsi` | `rsiReviewStart`, `rsiStream` | 2 |
| Self-Tuning | `client.agent.selfTuning` | `selfTuningTuneStart`, `selfTuningAmplifyStart`, `selfTuningStream` | 3 |
| Workspace Session | `client.agent.workspaceSession` | `sessionsJobsList`, `sessionsJobsGet`, `sessionsCliAgentStart` | 7 |
| Orchestration | `client.agent.orchestration` | `todoRead`, `todoAppend`, `executorStart`, `phasesList`, `budgetGetStatus`, `questionsList`, `orchestratorSendPrompt` | 48 |
| Files | `client.agent.files` | `search`, `findByName`, `findSymbols`, `list`, `readContent`, `getStatus` | 6 |
| Config | `client.agent.config` | `get`, `update`, `getToolOverrides` | 3 |
| Permissions | `client.agent.permissions` | `list`, `reply`, `getOverrides` | 3 |
| Providers | `client.agent.providers` | `list`, `listConfigs`, `getAuthMethods`, `authorizeOAuth`, `callbackOAuth` | 5 |
| Reviewers | `client.agent.reviewers` | `configListReviewers` | 1 |
| Verifiers | `client.agent.verifiers` | `configListVerifiers` | 1 |
| CLI Agents | `client.agent.cliAgents` | `configListCliAgents` | 1 |
| Memory | `client.agent.memory` | `listBlocks`, `getBlock`, `setBlock`, `replaceBlock`, `deleteBlock`, `listJournalEntries`, `createJournalEntry`, `searchJournalEntries`, `listHistory`, `getConfig` | 15 |
| MCP | `client.agent.mcp` | `getStatus`, `addServer`, `connect`, `disconnect`, `startOAuth`, `completeOAuth`, `authenticateOAuth`, `removeOAuth` | 8 |
| Skills | `client.agent.skills` | `listMarketplace`, `get`, `upsert`, `update`, `delete`, `toggleBuiltin`, `discover` | 7 |
| Tools | `client.agent.tools` | `list` | 1 |
| Project | `client.agent.project` | `getCurrent`, `update` | 2 |
| Questions | `client.agent.questions` | `list`, `reply`, `reject`, `consult` | 4 |
| Web Search | `client.agent.webSearch` | `getStatus` | 1 |
| Image Gen | `client.agent.imageGen` | `getStatus` | 1 |
| Experimental | `client.agent.experimental` | `listToolIds`, `listToolSchemas`, `listMcpResources` | 3 |
| Meta | `client.agent.meta` | `listAgents`, `listSkills`, `getPaths`, `getVcs`, `listCommands`, `getLspStatus`, `getFormatterStatus`, `subscribeEvents`, `dispose` | 9 |
| Prompt | `client.agent.prompt` | `agentPromptSync`, `agentPromptGet`, `agentPrompt` | 3 |
| Branches | `client.agent.branches` | `listBranches`, `createBranch`, `getBranchDiff`, `mergeBranch`, `pushBranch`, `pullBranch`, `createPR` | 17 |
| MITM | HTTP only | Rules, logs, diagnostics, overlay, tags | 22 |

### Essential Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `workspaceID` | string | Required for all workspace-scoped endpoints |
| `sessionID` | string | Identifies a specific session |
| `messageID` | string | Identifies a specific message |
| `entryID` | string | Identifies a TODO entry |
| `phaseID` | string | Identifies an orchestration phase |
| `providerID` | string | AI provider identifier (e.g., `openai`, `anthropic`) |
| `modelID` | string | Model identifier (e.g., `gpt-4o`, `claude-sonnet-4-20250514`) |
| `page` | integer | Page number for pagination (default: 1) |
| `limit` | integer | Items per page |
| `after` | string | Cursor for cursor-based pagination |

### Typical Response Formats

**Single resource:**
```
{
  "id": "resource_001",
  "name": "example",
  "createdAt": "2025-01-15T10:30:00Z",
  "updatedAt": "2025-01-15T12:00:00Z"
}
```

**Paginated list:**
```
{
  "items": [],
  "total": 100,
  "page": 1,
  "limit": 20
}
```

**SSE stream events:**
```
event: snapshot
data: {"type":"snapshot","data":{}}

event: part.updated
data: {"type":"part.updated","data":{}}

event: message.completed
data: {"type":"message.completed","data":{}}
```

**Error response:**
```
{
  "error": {
    "code": "NOT_FOUND",
    "message": "Session not found",
    "details": {}
  }
}
```