<!-- Context: core/standards | Priority: critical | Version: 1.0 | Updated: 2026-02-15 -->

# OpenCode Codebase Standards

**Complete Reference Guide**  
_Last Updated: Feb 2026_  
_Analyzed: 206+ TypeScript files across `packages/opencode/src/`_

---

## Table of Contents

1. [Function Definition Standards](#1-function-definition-standards)
2. [Class Usage Standards](#2-class-usage-standards)
3. [Array Handling Standards](#3-array-handling-standards)
4. [Variable & Destructuring Standards](#4-variable--destructuring-standards)
5. [Control Flow Standards](#5-control-flow-standards)
6. [Async & Concurrency Standards](#6-async--concurrency-standards)
7. [Race Condition Prevention](#7-race-condition-prevention)
8. [AI System Integration Standards](#8-ai-system-integration-standards)
9. [Service Architecture Standards](#9-service-architecture-standards)
10. [State Management Standards](#10-state-management-standards)
11. [Event Bus Standards](#11-event-bus-standards)
12. [Configuration Management Standards](#12-configuration-management-standards)
13. [Storage & Persistence Standards](#13-storage--persistence-standards)
14. [Error Handling Standards](#14-error-handling-standards)
15. [Type System Standards](#15-type-system-standards)
16. [Import Organization Standards](#16-import-organization-standards)
17. [Naming Conventions](#17-naming-conventions)
18. [Testing Standards](#18-testing-standards)
19. [Documentation Standards](#19-documentation-standards)
20. [Schema Definition Standards](#20-schema-definition-standards)
21. [Dependency Management Standards](#21-dependency-management-standards)
22. [Build & Development Standards](#22-build--development-standards)
23. [Performance Standards](#23-performance-standards)
24. [Security Standards](#24-security-standards)

---

## 1. Function Definition Standards

### 1.1 Naming Convention

**Rule: Prefer single-word function names**

**Compliance: 95%+**

```typescript
// ✅ GOOD - Single-word names
export const create = fn(...)
export const fork = fn(...)
export const touch = fn(...)
export const get = fn(...)
export const share = fn(...)
export async function stream(input: StreamInput) {...}
export async function work<T>(concurrency, items, fn) {...}

// ✅ ACCEPTABLE - Multi-word only when necessary
export function isDefaultTitle(title: string) {...}      // Boolean predicate
export function assertNotBusy(sessionID: string) {...}   // Assertion pattern
export async function createNext(input) {...}            // Version disambiguation
export async function resolvePromptParts(template) {...} // Complex operation needs clarity

// ❌ AVOID - Unnecessary multi-word names
function prepareJournal(dir: string) {}  // Use: journal()
function getUserData(id: string) {}      // Use: user()
function processFileContent(path) {}     // Use: process()
```

**File References:**

- `packages/opencode/src/session/index.ts` - Lines 140, 200, 206
- `packages/opencode/src/session/llm.ts` - Line 59
- `packages/opencode/src/util/queue.ts` - Lines 1-32

### 1.2 Function Definition Patterns

#### Pattern A: Zod-Validated Functions (Primary Pattern)

```typescript
// packages/opencode/src/util/fn.ts - The fn() wrapper
export function fn<T extends z.ZodType, Result>(schema: T, cb: (input: z.infer<T>) => Result) {
  const result = (input: z.infer<T>) => {
    const parsed = schema.parse(input) // Validates input
    return cb(parsed)
  }
  result.force = (input: z.infer<T>) => cb(input) // Skip validation
  result.schema = schema // Expose schema
  return result
}

// Usage Example 1: Session creation
export const create = fn(
  z
    .object({
      parentID: Identifier.schema("session").optional(),
      title: z.string().optional(),
      permission: Info.shape.permission,
    })
    .optional(),
  async (input) => {
    return createNext({
      parentID: input?.parentID,
      title: input?.title,
      permission: input?.permission ?? "allow",
    })
  },
)

// Usage Example 2: Simple validation
export const touch = fn(Identifier.schema("session"), async (sessionID) => {
  await update(sessionID, (draft) => {
    draft.time.updated = Date.now()
  })
})

// Usage Example 3: Complex object validation
export const messages = fn(
  z.object({
    sessionID: Identifier.schema("session"),
    limit: z.number().optional(),
  }),
  async (input) => {
    const result = [] as MessageV2.WithParts[]
    for await (const msg of MessageV2.stream(input.sessionID)) {
      if (input.limit && result.length >= input.limit) break
      result.push(msg)
    }
    result.reverse()
    return result
  },
)
```

**File References:**

- `packages/opencode/src/util/fn.ts` - Lines 1-12
- `packages/opencode/src/session/index.ts` - Lines 140-202

#### Pattern B: Namespace Organization (Preferred over Classes)

```typescript
// packages/opencode/src/session/index.ts
export namespace Session {
  const log = Log.create({ service: "session" })

  // Exported functions with fn() wrapper
  export const create = fn(...)
  export const fork = fn(...)
  export const touch = fn(...)
  export const messages = fn(...)

  // Async functions without wrapper
  export async function createNext(input) {...}
  export async function update(id, editor, options) {...}

  // Type definitions
  export type Info = z.infer<typeof Info>
  export const Info = z.object({...})

  // Events
  export const Event = {
    Created: BusEvent.define("session.created", z.object({info: Info})),
    Updated: BusEvent.define("session.updated", z.object({info: Info})),
  }

  // Error classes (only exception to no-class rule)
  export class BusyError extends Error {
    constructor(public readonly sessionID: string) {
      super(`Session ${sessionID} is busy`)
    }
  }
}

// Usage
await Session.create({ title: "New Session" })
await Session.touch(sessionID)
const msgs = await Session.messages({ sessionID, limit: 10 })
```

**File References:**

- `packages/opencode/src/session/index.ts` - Lines 26-518
- `packages/opencode/src/tool/tool.ts` - Lines 1-90
- `packages/opencode/src/session/processor.ts` - Lines 19-416

#### Pattern C: Inline vs. Extraction Rule

**Rule: Inline when used once, extract when composable/reusable**

```typescript
// ✅ GOOD - Inline when value used once
const journal = await Bun.file(path.join(dir, "journal.json")).json()
const [language, cfg] = await Promise.all([Provider.getLanguage(input.model), Config.get()])

// ❌ BAD - Unnecessary intermediate variable
const journalPath = path.join(dir, "journal.json")
const journalFile = Bun.file(journalPath)
const journal = await journalFile.json()

// ✅ GOOD - Extract when reusable across multiple call sites
async function resolveTools(input: Pick<StreamInput, "tools" | "agent" | "user">) {
  const disabled = PermissionNext.disabled(Object.keys(input.tools), input.agent.permission)
  for (const tool of Object.keys(input.tools)) {
    if (input.user.tools?.[tool] === false || disabled.has(tool)) {
      delete input.tools[tool]
    }
  }
  return input.tools
}

// Called from multiple locations
const tools = await resolveTools({ tools: input.tools, agent, user })

// ✅ GOOD - Extract when logic is complex and improves readability
function shouldUseCopilotResponsesApi(modelID: string): boolean {
  const match = /^gpt-(\d+)/.exec(modelID)
  if (!match) return false
  return Number(match[1]) >= 5 && !modelID.startsWith("gpt-5-mini")
}
```

**File References:**

- `packages/opencode/src/session/llm.ts` - Lines 59, 268-276
- `packages/opencode/src/provider/provider.ts` - Lines 46-56

### 1.3 Function Composition Patterns

```typescript
// ✅ GOOD - Functional composition with pipes
const filtered = agents
  .filter((a) => a.mode !== "primary")
  .filter((a) => PermissionNext.evaluate("task", a.name, caller.permission).action !== "deny")
  .map((a) => a.name)

// ✅ GOOD - Async composition with Promise.all
const [results, metadata] = await Promise.all([processItems(items), fetchMetadata(id)])

// ✅ GOOD - Higher-order functions
export function withLock<T>(filepath: string, fn: () => Promise<T>): Promise<T> {
  return Lock.write(filepath).then(async (lock) => {
    try {
      return await fn()
    } finally {
      lock[Symbol.dispose]()
    }
  })
}
```

---

## 2. Class Usage Standards

### 2.1 Avoid Classes (Except Specific Patterns)

**Finding: Only 5 classes in 206 files**

**Rule: Use namespaces + functions instead of classes**

```typescript
// ❌ AVOID - Class-based organization
class SessionManager {
  private sessions: Map<string, Session> = new Map()

  create(input: CreateInput) {
    const session = { id: generateId(), ...input }
    this.sessions.set(session.id, session)
    return session
  }

  update(id: string, data: Partial<Session>) {
    const session = this.sessions.get(id)
    if (!session) throw new Error("Not found")
    Object.assign(session, data)
    return session
  }
}

// ✅ PREFER - Namespace-based organization
export namespace Session {
  const state = Instance.state(async () => ({
    sessions: new Map<string, Info>()
  }))

  export const create = fn(
    CreateInput.schema,
    async (input) => {
      const session = { id: Identifier.ascending("session"), ...input }
      state().sessions.set(session.id, session)
      return session
    }
  )

  export const update = fn(
    z.object({ id: z.string(), data: z.record(z.unknown()) }),
    async (input) => {
      const session = state().sessions.get(input.id)
      if (!session) throw NotFoundError.create({...})
      Object.assign(session, input.data)
      return session
    }
  )
}
```

### 2.2 Allowed Class Use Cases

#### Use Case 1: Error Types

```typescript
// ✅ GOOD - Custom error classes
export class BusyError extends Error {
  constructor(public readonly sessionID: string) {
    super(`Session ${sessionID} is busy`)
  }
}

// Usage
throw new BusyError(sessionID)

// Catching
try {
  await operation()
} catch (error) {
  if (error instanceof BusyError) {
    // Handle busy state
  }
}
```

**File Reference:** `packages/opencode/src/session/index.ts:494`

#### Use Case 2: Protocol Implementations

```typescript
// ✅ GOOD - Implementing external interfaces
export class OpenAICompatibleChatLanguageModel implements LanguageModelV2 {
  readonly specificationVersion = "v2"
  readonly provider: string
  readonly modelId: string

  constructor(modelId: string, settings: ModelSettings) {
    this.modelId = modelId
    this.provider = settings.provider
  }

  async doGenerate(options: GenerateOptions): Promise<GenerateResult> {
    // Implementation required by interface
  }

  async doStream(options: StreamOptions): AsyncIterableIterator<StreamPart> {
    // Implementation required by interface
  }
}

// ✅ GOOD - OAuth protocol implementation
export class McpOAuthProvider implements OAuthClientProvider {
  async getAccessToken(): Promise<string> {
    // OAuth flow implementation
  }
}
```

**File References:**

- `packages/opencode/src/provider/sdk/*` - Lines 53, 131
- `packages/opencode/src/mcp/oauth-provider.ts:26`

#### Use Case 3: Async Iterators

```typescript
// ✅ GOOD - AsyncIterable implementation
export class AsyncQueue<T> implements AsyncIterable<T> {
  private queue: T[] = []
  private resolvers: ((value: T) => void)[] = []

  push(item: T) {
    const resolve = this.resolvers.shift()
    if (resolve) {
      resolve(item)
    } else {
      this.queue.push(item)
    }
  }

  async next(): Promise<T> {
    if (this.queue.length > 0) {
      return this.queue.shift()!
    }
    return new Promise((resolve) => {
      this.resolvers.push(resolve)
    })
  }

  async *[Symbol.asyncIterator]() {
    while (true) {
      yield await this.next()
    }
  }
}

// Usage
const queue = new AsyncQueue<Message>()
queue.push(message)

for await (const msg of queue) {
  console.log(msg)
}
```

**File Reference:** `packages/opencode/src/util/queue.ts:1-19`

#### Use Case 4: Complex Stateful Managers

```typescript
// ✅ ACCEPTABLE - When managing complex state machines
export class ACPSessionManager {
  private sessions: Map<string, ACPSession>
  private connections: Map<string, WebSocket>

  // Complex lifecycle management
  async createSession(id: string) {...}
  async handleMessage(id: string, msg: Message) {...}
  async closeSession(id: string) {...}

  // State machine logic
  private transition(from: State, to: State) {...}
}
```

**File Reference:** `packages/opencode/src/acp/session.ts:8`

---

## 3. Array Handling Standards

### 3.1 Functional Methods (85% of operations)

**Rule: Prefer map/filter/flatMap over for-loops**

```typescript
// ✅ GOOD - Functional chain with type inference
const files = messages
  .flatMap((x) => x.parts)
  .filter((x): x is Patch => x.type === "patch") // Type guard maintains inference
  .flatMap((x) => x.files)
  .map((x) => path.relative(Instance.worktree, x))

// ✅ GOOD - Parallel async operations
const results = await Promise.all(
  toolCalls.map(async (call) => {
    return executeCall(call)
  }),
)

// ✅ GOOD - Reduce for aggregation
const totalAdditions = diffs.reduce((sum, x) => sum + x.additions, 0)

// ✅ GOOD - Filter with type guards
const agents = await Agent.list().then((x) => x.filter((a): a is Agent & { mode: "secondary" } => a.mode !== "primary"))

// ✅ GOOD - Unique values
const uniqueNames = Array.from(new Set(items.map((x) => x.name)))

// ✅ GOOD - Sorting
const sorted = items.toSorted((a, b) => a.timestamp - b.timestamp)
```

**File References:**

- `packages/opencode/src/tool/batch.ts` - Lines 41, 56, 80, 170
- `packages/opencode/src/session/prompt.ts` - Lines 192-200
- `packages/opencode/src/session/summary.ts` - Lines 96-109

### 3.2 For-Loops (15%, only when necessary)

**Rule: Use for-loops only for:**

1. Algorithm complexity (DP, graph traversal)
2. Early exit requirements
3. Sequential side effects
4. Performance-critical iteration

#### Pattern 1: Algorithm Complexity

```typescript
// ✅ GOOD - Dynamic programming (LCS algorithm)
// packages/opencode/src/tool/edit.ts:175-176
function lcs(a: string[], b: string[]): number[][] {
  const dp: number[][] = Array(a.length + 1)
    .fill(0)
    .map(() => Array(b.length + 1).fill(0))

  for (let i = 1; i <= a.length; i++) {
    for (let j = 1; j <= b.length; j++) {
      if (a[i - 1] === b[j - 1]) {
        dp[i][j] = dp[i - 1][j - 1] + 1
      } else {
        dp[i][j] = Math.max(dp[i - 1][j], dp[i][j - 1])
      }
    }
  }

  return dp
}
```

#### Pattern 2: Early Exit

```typescript
// ✅ GOOD - Break on condition
// packages/opencode/src/session/revert.ts:31-40
const patches = []
for (const msg of all) {
  if (msg.info.id === revert.messageID) break
  for (const part of msg.parts) {
    if (part.type === "patch") {
      patches.push(part)
    }
  }
}

// ✅ GOOD - Find first match
for (const file of files) {
  if (await Filesystem.exists(file)) {
    return file
  }
}
```

#### Pattern 3: Sequential Side Effects

```typescript
// ✅ GOOD - Sequential mutations
for (const key of Object.keys(input.tools)) {
  if (input.user.tools?.[key] === false || disabled.has(key)) {
    delete input.tools[key]
  }
}

// ✅ GOOD - Streaming output
for (const line of lines) {
  await stream.write(line)
}
```

**File Reference:** `packages/opencode/src/tool/grep.ts:77`

#### Pattern 4: Performance Critical

```typescript
// ✅ GOOD - Low-level iteration for performance
for (let i = 0; i < buffer.length; i++) {
  result += buffer[i] * multiplier
}

// Note: Profile before optimizing - functional methods are often fast enough
```

### 3.3 Type Guards on Filter

**Rule: Use type guards to maintain type inference downstream**

```typescript
// ✅ GOOD - Type guard preserves type information
const patches = messages.flatMap((msg) => msg.parts).filter((part): part is PatchPart => part.type === "patch")
// patches is now PatchPart[], not Part[]

// ❌ BAD - Loses type information
const patches = messages.flatMap((msg) => msg.parts).filter((part) => part.type === "patch")
// patches is still Part[], requires casting later

// ✅ GOOD - Multiple type guards
const validAgents = agents
  .filter((a): a is Agent => a !== undefined)
  .filter((a): a is Agent & { mode: "secondary" } => a.mode !== "primary")
```

**File Reference:** `packages/opencode/src/tool/task.ts:24,29`

---

## 4. Variable & Destructuring Standards

### 4.1 Variable Declaration

**Rule: Prefer `const` over `let`**

```typescript
// ✅ GOOD - Immutable with ternary
const foo = condition ? 1 : 2
const result = await (isValid ? processValid() : processInvalid())

// ❌ BAD - Reassignment
let foo
if (condition) {
  foo = 1
} else {
  foo = 2
}

// ✅ GOOD - Early return instead of reassignment
function getValue(condition: boolean) {
  if (condition) return 1
  return 2
}

// ✅ ACCEPTABLE - let when mutation is necessary
let accumulator = 0
for (const item of items) {
  accumulator += item.value
}
```

**File Reference:** `AGENTS.md:56-68`

### 4.2 Destructuring

**Rule: Avoid unnecessary destructuring, preserve context with dot notation**

```typescript
// ✅ GOOD - Preserve context
function process(session: Session) {
  log.info("processing", { id: session.id, title: session.title })
  return {
    id: session.id,
    status: session.status,
    owner: session.owner
  }
}

// ❌ BAD - Loses context, harder to read
function process(session: Session) {
  const { id, title, status, owner } = session
  log.info("processing", { id, title })
  return { id, status, owner }
}

// ✅ ACCEPTABLE - Destructuring when improving readability
function renderUser({ name, email, avatar }: User) {
  return `<div>${name} (${email})</div>`
}

// ✅ ACCEPTABLE - Destructuring array returns
const [language, cfg, provider] = await Promise.all([...])
```

**File Reference:** `AGENTS.md:43-54`

### 4.3 Variable Naming

**Rule: Concise single-word names when descriptive**

```typescript
// ✅ GOOD
const session = await Session.get(id)
const user = await Auth.current()
const messages = await Session.messages({ sessionID })

// ❌ BAD - Unnecessary verbosity
const currentSession = await Session.get(id)
const currentlyAuthenticatedUser = await Auth.current()
const sessionMessagesList = await Session.messages({ sessionID })

// ✅ GOOD - Multi-word when single word is ambiguous
const sessionID = params.id
const userAgent = req.headers["user-agent"]
const maxRetries = config.retries
```

---

## 5. Control Flow Standards

### 5.1 Early Returns

**Rule: Avoid `else` statements, use early returns**

```typescript
// ✅ GOOD - Early returns
function getStatus(session: Session) {
  if (!session) return "not_found"
  if (session.busy) return "busy"
  if (session.error) return "error"
  return "ready"
}

async function process(id: string) {
  const session = await Session.get(id)
  if (!session) return { error: "Not found" }

  const result = await execute(session)
  if (!result.success) return { error: result.message }

  return { data: result.data }
}

// ❌ BAD - Else statements
function getStatus(session: Session) {
  if (!session) {
    return "not_found"
  } else {
    if (session.busy) {
      return "busy"
    } else {
      if (session.error) {
        return "error"
      } else {
        return "ready"
      }
    }
  }
}
```

**File Reference:** `AGENTS.md:70-86`

### 5.2 Guard Clauses

```typescript
// ✅ GOOD - Guard clauses at function start
async function updateSession(id: string, data: UpdateData) {
  if (!id) throw new Error("ID required")
  if (!data) throw new Error("Data required")
  if (data.title && data.title.length > 100) throw new Error("Title too long")

  // Main logic here
  const session = await Session.get(id)
  await Session.update(id, data)
  return session
}
```

### 5.3 Switch Statements

**Rule: Use exhaustive switch with default case**

```typescript
// ✅ GOOD - Exhaustive switch for stream handling
for await (const value of stream.fullStream) {
  switch (value.type) {
    case "reasoning-start":
      reasoningMap[value.id] = { id: generateId(), type: "reasoning", text: "" }
      break

    case "reasoning-delta":
      if (value.id in reasoningMap) {
        reasoningMap[value.id].text += value.text
        await Session.updatePart({ delta: value.text })
      }
      break

    case "tool-call":
      await Session.updatePart({ state: { status: "running" } })
      break

    case "tool-result":
      await Session.updatePart({ state: { status: "completed" } })
      break

    default:
      const _exhaustive: never = value
      throw new Error(`Unhandled type: ${(value as any).type}`)
  }
}
```

**File Reference:** `packages/opencode/src/session/processor.ts:53-346`

---

## 6. Async & Concurrency Standards

### 6.1 Parallel Execution (Default Pattern)

**Rule: Use `Promise.all` for independent operations**

```typescript
// ✅ GOOD - Parallel independent operations
const [language, cfg, provider, auth] = await Promise.all([
  Provider.getLanguage(input.model),
  Config.get(),
  Provider.getProvider(input.model.providerID),
  Auth.get(input.model.providerID),
])

// ✅ GOOD - Parallel array processing
const results = await Promise.all(
  items.map(async (item) => {
    return processItem(item)
  }),
)

// ❌ BAD - Sequential when independent
const language = await Provider.getLanguage(input.model)
const cfg = await Config.get() // Could run in parallel!
const provider = await Provider.getProvider(input.model.providerID)
const auth = await Auth.get(input.model.providerID)
```

**File Reference:** `packages/opencode/src/session/llm.ts:59`

### 6.2 Sequential Operations

**Rule: Chain when operations depend on previous results**

```typescript
// ✅ GOOD - Sequential dependency chain
const session = await Session.create({ title: "New" })
const message = await Session.addMessage(session.id, { content: "Hello" })
const response = await LLM.stream({ sessionID: session.id, messageID: message.id })

// ✅ GOOD - Promise chain for clarity
const result = await Session.create({ title: "New" })
  .then((session) => Session.addMessage(session.id, { content: "Hello" }))
  .then((message) => LLM.stream({ messageID: message.id }))
```

### 6.3 Error Handling in Async

**Rule: Prefer `.catch()` over try/catch when possible**

```typescript
// ✅ GOOD - Catch at call site
const result = await operation().catch((error) => {
  log.error("Operation failed", { error })
  return defaultValue
})

// ✅ GOOD - Promise.all with error handling
const results = await Promise.all(
  items.map(async (item) => {
    return processItem(item).catch((error) => {
      log.error("Item failed", { item, error })
      return null
    })
  }),
)

// ✅ ACCEPTABLE - try/catch for multiple operations
try {
  const session = await Session.create(input)
  await Session.addMessage(session.id, message)
  await EventBus.publish(Session.Event.Created, { session })
  return session
} catch (error) {
  log.error("Session creation failed", { error })
  throw error
}

// ❌ AVOID - try/catch for single operation
try {
  const result = await operation()
  return result
} catch (error) {
  log.error(error)
  throw error
}
// Better:
const result = await operation().catch((error) => {
  log.error(error)
  throw error
})
```

### 6.4 Concurrent Worker Pattern

```typescript
// ✅ GOOD - Controlled concurrency
export async function work<T>(concurrency: number, items: T[], fn: (item: T) => Promise<void>) {
  const pending = [...items]

  await Promise.all(
    Array.from({ length: concurrency }, async () => {
      while (true) {
        const item = pending.pop()
        if (item === undefined) return
        await fn(item)
      }
    }),
  )
}

// Usage
await work(3, files, async (file) => {
  await processFile(file)
})
```

**File Reference:** `packages/opencode/src/util/queue.ts:21-32`

---

## 7. Race Condition Prevention

### 7.1 Reader-Writer Lock (Storage Operations)

```typescript
// packages/opencode/src/util/lock.ts
export namespace Lock {
  const locks = new Map<
    string,
    {
      readers: number
      writer: boolean
      waitingReaders: (() => void)[]
      waitingWriters: (() => void)[]
    }
  >()

  export async function read(key: string): Promise<Disposable> {
    const lock = get(key)
    return new Promise((resolve) => {
      // Writers get priority
      if (!lock.writer && lock.waitingWriters.length === 0) {
        lock.readers++
        resolve({
          [Symbol.dispose]: () => {
            lock.readers--
            process(key)
          },
        })
      } else {
        lock.waitingReaders.push(() => {
          lock.readers++
          resolve({
            [Symbol.dispose]: () => {
              lock.readers--
              process(key)
            },
          })
        })
      }
    })
  }

  export async function write(key: string): Promise<Disposable> {
    const lock = get(key)
    return new Promise((resolve) => {
      if (!lock.writer && lock.readers === 0) {
        lock.writer = true
        resolve({
          [Symbol.dispose]: () => {
            lock.writer = false
            process(key)
          },
        })
      } else {
        lock.waitingWriters.push(() => {
          lock.writer = true
          resolve({
            [Symbol.dispose]: () => {
              lock.writer = false
              process(key)
            },
          })
        })
      }
    })
  }
}

// Usage with disposable pattern
export async function read<T>(target: string): Promise<T> {
  using _ = await Lock.read(target) // Auto-releases on scope exit
  const file = Bun.file(target)
  if (!(await file.exists())) {
    throw NotFoundError.create({ message: `File not found: ${target}` })
  }
  return file.json()
}

export async function write(target: string, data: any): Promise<void> {
  using _ = await Lock.write(target) // Auto-releases on scope exit
  const dir = path.dirname(target)
  await fs.mkdir(dir, { recursive: true })
  await Bun.write(target, JSON.stringify(data, null, 2))
}
```

**File References:**

- `packages/opencode/src/util/lock.ts` - Lines 1-99
- `packages/opencode/src/storage/storage.ts` - Lines 173, 183, 195

### 7.2 File-Level Lock (Edit Operations)

```typescript
// packages/opencode/src/file/time.ts
export async function withLock<T>(filepath: string, fn: () => Promise<T>): Promise<T> {
  const current = state()
  const currentLock = current.locks.get(filepath) ?? Promise.resolve()

  let release: () => void = () => {}
  const nextLock = new Promise<void>((resolve) => {
    release = resolve
  })

  const chained = currentLock.then(() => nextLock)
  current.locks.set(filepath, chained)

  await currentLock // Wait for previous lock

  try {
    return await fn()
  } finally {
    release()
    if (current.locks.get(filepath) === chained) {
      current.locks.delete(filepath)
    }
  }
}

// Usage: Atomic read-modify-write
await FileTime.withLock(filePath, async () => {
  const contentOld = await Bun.file(filePath).text()
  const contentNew = replace(contentOld, params.oldString, params.newString)
  await Bun.write(filePath, contentNew)
  await FileTime.touch(filePath)
})
```

**File References:**

- `packages/opencode/src/file/time.ts` - Lines 35-53
- `packages/opencode/src/tool/edit.ts` - Line 50

### 7.3 Mutex Pattern

```typescript
// ✅ GOOD - Simple mutex for critical sections
const mutexes = new Map<string, Promise<void>>()

async function withMutex<T>(key: string, fn: () => Promise<T>): Promise<T> {
  const current = mutexes.get(key) ?? Promise.resolve()

  let release: () => void
  const next = new Promise<void>((resolve) => {
    release = resolve
  })
  mutexes.set(key, next)

  await current

  try {
    return await fn()
  } finally {
    release!()
    if (mutexes.get(key) === next) {
      mutexes.delete(key)
    }
  }
}

// Usage
await withMutex(`session:${sessionID}`, async () => {
  // Critical section - only one execution at a time
  const session = await Session.get(sessionID)
  session.busy = true
  await Session.save(session)
})
```

### 7.4 Debouncing & Throttling

```typescript
// ✅ GOOD - Debounce for file watching
function debounce<T extends (...args: any[]) => any>(fn: T, delay: number): (...args: Parameters<T>) => void {
  let timer: Timer | undefined

  return (...args: Parameters<T>) => {
    if (timer) clearTimeout(timer)
    timer = setTimeout(() => {
      fn(...args)
      timer = undefined
    }, delay)
  }
}

// Usage in file watcher
const debouncedUpdate = debounce((file: string) => {
  Bus.publish(FileWatcher.Event.Updated, { file })
}, 100)

watcher.on("change", (file) => {
  debouncedUpdate(file)
})
```

---

## 8. AI System Integration Standards

### 8.1 Message Context Management

```typescript
// packages/opencode/src/session/message-v2.ts

export type Part = TextPart | FilePart | PatchPart | ToolCallPart | ToolResultPart | ReasoningPart

export interface WithParts {
  info: Info
  parts: Part[]
}

// Convert internal message format to LLM format
export function toModelMessages(input: WithParts[], model: Provider.Model): ModelMessage[] {
  return input.flatMap((msg): ModelMessage[] => {
    if (msg.info.role === "user") {
      return [
        {
          role: "user",
          content: msg.parts.map((part) => {
            if (part.type === "text") {
              return { type: "text", text: part.text }
            }
            if (part.type === "file") {
              return {
                type: "file",
                data: part.data,
                mimeType: part.mimeType,
              }
            }
            if (part.type === "patch") {
              return {
                type: "text",
                text: formatPatch(part),
              }
            }
            // ... handle other types
          }),
        },
      ]
    }

    if (msg.info.role === "assistant") {
      return [
        {
          role: "assistant",
          content: msg.parts
            .filter((p) => p.type === "text" || p.type === "reasoning")
            .map((p) => ({ type: "text", text: p.text })),
        },
      ]
    }

    // Handle tool results...
    return []
  })
}
```

**File Reference:** `packages/opencode/src/session/message-v2.ts:438-500`

### 8.2 System Prompt Construction

```typescript
// packages/opencode/src/session/llm.ts

export async function stream(input: StreamInput) {
  const system: string[] = []

  // Part 1: Base system prompt (cached)
  const header = [
    // Agent prompt OR provider prompt
    ...(input.agent.prompt ? [input.agent.prompt] : isCodex ? [] : SystemPrompt.provider(input.model)),
    // Custom prompt from request
    ...input.system,
    // Custom prompt from user config
    ...(input.user.system ? [input.user.system] : []),
  ]
    .filter(Boolean)
    .join("\n")

  system.push(header)

  // Part 2: Dynamic context (not cached)
  const dynamicContext = [
    `Working directory: ${Instance.directory}`,
    `Current date: ${new Date().toISOString()}`,
    // ... other dynamic info
  ].join("\n")

  system.push(dynamicContext)

  // Allow plugins to transform system prompt
  const original = clone(system)
  await Plugin.trigger(
    "experimental.chat.system.transform",
    {
      model: input.model,
      agent: input.agent,
    },
    { system },
  )

  // Optimize for prompt caching: maintain 2-part structure if header unchanged
  if (system.length > 2 && system[0] === header) {
    const rest = system.slice(1)
    system.length = 0
    system.push(header, rest.join("\n"))
  }

  // Convert to LLM messages
  const messages = [
    ...system.map((text) => ({ role: "system", content: text })),
    ...toModelMessages(input.messages, input.model),
  ]

  return language.doStream({
    model: input.model.id,
    messages,
    tools: await resolveTools(input),
  })
}
```

**File Reference:** `packages/opencode/src/session/llm.ts:67-97`

### 8.3 Tool Definition & Execution

```typescript
// packages/opencode/src/tool/tool.ts

export namespace Tool {
  export interface Info<Parameters = any, Metadata = any> {
    id: string
    title: string
    description: string
    parameters: z.ZodType<Parameters>
    metadata?: Metadata

    execute(args: Parameters, context: Context): Promise<ExecuteResult>
  }

  export interface Context {
    sessionID: string
    messageID: string
    agent: string
    abort: AbortSignal
    messages: () => Promise<MessageV2.WithParts[]>
    metadata: <T>(key: string, value: T) => Promise<void>
    ask: <T>(question: Question<T>) => Promise<T>
  }

  export type ExecuteResult = {
    output?: string
    title?: string
    metadata?: Record<string, unknown>
  }

  export function define<Parameters, Result>(
    id: string,
    init: {
      title: string
      description: string
      parameters: z.ZodType<Parameters>
      execute: (args: Parameters, context: Context) => Promise<ExecuteResult>
    },
  ): Info<Parameters> {
    return {
      id,
      ...init,
    }
  }
}

// Usage: Define a tool
export const ReadTool = Tool.define("read", {
  title: "Read File",
  description: "Read contents of a file from the filesystem",
  parameters: z.object({
    filePath: z.string().describe("Absolute path to file"),
    offset: z.number().optional().describe("Line number to start reading"),
    limit: z.number().optional().describe("Number of lines to read"),
  }),

  async execute(args, context) {
    await context.ask({
      type: "permission",
      message: `Read file ${args.filePath}?`,
      actions: ["allow", "deny"],
    })

    const content = await Bun.file(args.filePath).text()
    const lines = content.split("\n")

    const start = args.offset ?? 0
    const end = args.limit ? start + args.limit : lines.length
    const selected = lines.slice(start, end)

    return {
      output: selected.join("\n"),
      title: `Read ${path.basename(args.filePath)}`,
      metadata: {
        lineCount: selected.length,
        filePath: args.filePath,
      },
    }
  },
})

// Register tool
await ToolRegistry.register(ReadTool)

// Tool execution in session
const tools = await ToolRegistry.tools({ agent: input.agent })

const toolMap = tools.reduce(
  (acc, tool) => {
    acc[tool.id] = vercelAiTool({
      description: tool.description,
      parameters: zodToJsonSchema(tool.parameters),
      execute: async (args) => {
        const result = await tool.execute(args, {
          sessionID: input.sessionID,
          messageID: input.messageID,
          agent: input.agent.name,
          abort: input.abort,
          messages: () => Session.messages({ sessionID: input.sessionID }),
          metadata: async (key, value) => {
            await Session.updatePart({
              messageID: input.messageID,
              metadata: { [key]: value },
            })
          },
          ask: async (question) => {
            return new Promise((resolve) => {
              Bus.publish(Session.Event.Question, {
                sessionID: input.sessionID,
                question,
                respond: resolve,
              })
            })
          },
        })

        return result.output
      },
    })
    return acc
  },
  {} as Record<string, any>,
)
```

**File References:**

- `packages/opencode/src/tool/tool.ts` - Lines 1-90
- `packages/opencode/src/session/prompt.ts` - Lines 711-748

### 8.4 Streaming Handling

```typescript
// packages/opencode/src/session/processor.ts

export function create(input: CreateInput) {
  const reasoningMap: Record<string, ReasoningPart> = {}
  const toolcalls: Record<string, ToolCallPart> = {}

  return {
    async process() {
      const stream = await LLM.stream({
        sessionID: input.sessionID,
        messageID: input.messageID,
        model: input.model,
        messages: input.messages,
        tools: input.tools,
        abort: input.abort,
      })

      // Handle stream events
      for await (const value of stream.fullStream) {
        input.abort.throwIfAborted()

        switch (value.type) {
          case "reasoning-start":
            reasoningMap[value.id] = {
              id: Identifier.ascending("part"),
              type: "reasoning",
              text: "",
              time: { start: Date.now() },
            }
            await Session.addPart({
              messageID: input.messageID,
              part: reasoningMap[value.id],
            })
            break

          case "reasoning-delta":
            if (value.id in reasoningMap) {
              const part = reasoningMap[value.id]
              part.text += value.text
              await Session.updatePart({
                messageID: input.messageID,
                partID: part.id,
                delta: value.text,
              })
            }
            break

          case "reasoning-finish":
            if (value.id in reasoningMap) {
              const part = reasoningMap[value.id]
              part.time.end = Date.now()
              await Session.updatePart({
                messageID: input.messageID,
                partID: part.id,
                part,
              })
            }
            break

          case "text-delta":
            // Handle text streaming...
            break

          case "tool-call":
            const toolPart: ToolCallPart = {
              id: Identifier.ascending("part"),
              type: "tool-call",
              toolCallID: value.toolCallId,
              toolName: value.toolName,
              state: {
                status: "running",
                input: value.args,
                time: { start: Date.now() },
              },
            }
            toolcalls[value.toolCallId] = toolPart
            await Session.addPart({
              messageID: input.messageID,
              part: toolPart,
            })
            break

          case "tool-result":
            const match = toolcalls[value.toolCallId]
            if (match) {
              match.state = {
                status: "completed",
                output: value.result,
                time: {
                  start: match.state.time.start,
                  end: Date.now(),
                },
              }
              await Session.updatePart({
                messageID: input.messageID,
                partID: match.id,
                part: match,
              })
            }
            break

          case "error":
            await Session.updateMessage({
              messageID: input.messageID,
              error: {
                message: value.error.message,
                code: value.error.code,
              },
            })
            throw value.error

          case "finish":
            await Session.updateMessage({
              messageID: input.messageID,
              tokens: value.usage,
              time: { end: Date.now() },
            })
            break

          default:
            // Exhaustiveness check
            const _exhaustive: never = value
            throw new Error(`Unhandled stream type: ${(value as any).type}`)
        }
      }
    },
  }
}
```

**File Reference:** `packages/opencode/src/session/processor.ts:53-346`

### 8.5 Context Compaction

```typescript
// packages/opencode/src/session/compaction.ts

export async function isOverflow(input: {
  tokens: MessageV2.Assistant["tokens"]
  model: Provider.Model
}): Promise<boolean> {
  const limit = input.model.limit.context

  const total = input.tokens.input + input.tokens.output + input.tokens.cache.read + input.tokens.cache.write

  const threshold = limit * 0.75 // Trigger at 75% capacity

  return total > threshold
}

export async function compact(sessionID: string) {
  const messages = await Session.messages({ sessionID })
  const model = await Session.getModel(sessionID)

  // Find oldest non-system messages
  const candidates = messages.filter((m) => m.info.role !== "system")

  if (candidates.length <= 2) {
    // Keep at least 2 messages for context
    return
  }

  // Remove oldest message
  const toRemove = candidates[0]
  await Session.deleteMessage(toRemove.info.id)

  // Add summary if necessary
  const summary = await generateSummary(toRemove)
  await Session.addSystemMessage(sessionID, {
    content: `Previous context (summarized): ${summary}`,
  })

  log.info("compacted session", {
    sessionID,
    removedMessageID: toRemove.info.id,
    remainingMessages: messages.length - 1,
  })
}

// Check after each assistant response
await Session.onMessageComplete(async (messageID) => {
  const message = await Session.getMessage(messageID)
  const model = await Session.getModel(message.sessionID)

  if (await isOverflow({ tokens: message.tokens, model })) {
    await compact(message.sessionID)
  }
})
```

**File References:**

- `packages/opencode/src/session/compaction.ts` - Lines 30-48
- `packages/opencode/src/session/processor.ts` - Lines 282-284

---

## 9. Service Architecture Standards

### 9.1 Core Services Overview

| Service                 | Location                   | Pattern                | Responsibility              |
| ----------------------- | -------------------------- | ---------------------- | --------------------------- |
| **Session Management**  | `src/session/`             | Namespace + State      | AI conversation lifecycle   |
| **File Watching**       | `src/file/watcher.ts`      | Chokidar + Debounce    | Filesystem change detection |
| **LSP Integration**     | `src/lsp/`                 | Multi-client manager   | Language server protocol    |
| **MCP**                 | `src/mcp/`                 | Multi-transport client | Model Context Protocol      |
| **Terminal/PTY**        | `src/server/routes/pty.ts` | WebSocket-based        | Shell session management    |
| **Event Bus**           | `src/bus/`                 | Pub/sub pattern        | Cross-service communication |
| **Storage**             | `src/storage/`             | Lock-based persistence | JSON file storage           |
| **Provider Management** | `src/provider/`            | Lazy-loaded SDKs       | LLM provider abstraction    |
| **Config Management**   | `src/config/`              | Layered merge          | Multi-level configuration   |
| **Scheduler**           | `src/scheduler/`           | Interval-based         | Background job execution    |

### 9.2 Service Implementation Template

```typescript
// Service template following codebase patterns

import { Log } from "../util/log"
import { Instance } from "../project/instance"
import { BusEvent } from "../bus/event"
import z from "zod"

export namespace MyService {
  const log = Log.create({ service: "my-service" })

  // 1. Type definitions
  export type Info = z.infer<typeof Info>
  export const Info = z.object({
    id: z.string(),
    status: z.enum(["idle", "active", "error"]),
    created: z.number(),
  })

  // 2. Per-instance state
  const state = Instance.state(
    async () => {
      log.info("initializing service")

      return {
        items: new Map<string, Info>(),
        timers: new Map<string, Timer>(),
        clients: [] as Client[],
      }
    },
    async (state) => {
      log.info("disposing service")

      // Cleanup resources
      await Promise.all([
        ...state.clients.map((c) => c.close()),
        ...Array.from(state.timers.values()).map((t) => clearInterval(t)),
      ])

      state.items.clear()
    },
  )

  // 3. Event definitions
  export const Event = {
    Created: BusEvent.define(
      "my-service.created",
      z.object({
        info: Info,
      }),
    ),
    Updated: BusEvent.define(
      "my-service.updated",
      z.object({
        info: Info,
      }),
    ),
    Deleted: BusEvent.define(
      "my-service.deleted",
      z.object({
        id: z.string(),
      }),
    ),
  }

  // 4. Public API with fn() wrapper
  export const create = fn(
    z
      .object({
        id: z.string().optional(),
        data: z.record(z.unknown()).optional(),
      })
      .optional(),
    async (input) => {
      const id = input?.id ?? Identifier.ascending("my-service")

      const info: Info = {
        id,
        status: "idle",
        created: Date.now(),
      }

      state().items.set(id, info)
      await Bus.publish(Event.Created, { info })

      log.info("created", { id })
      return info
    },
  )

  export const get = fn(z.string(), async (id) => {
    const item = state().items.get(id)
    if (!item) {
      throw NotFoundError.create({ message: `Item ${id} not found` })
    }
    return item
  })

  export const list = fn(
    z
      .object({
        status: z.enum(["idle", "active", "error"]).optional(),
      })
      .optional(),
    async (input) => {
      const items = Array.from(state().items.values())

      if (input?.status) {
        return items.filter((item) => item.status === input.status)
      }

      return items
    },
  )

  // 5. Internal functions (not exported)
  async function cleanup(id: string) {
    const timer = state().timers.get(id)
    if (timer) {
      clearInterval(timer)
      state().timers.delete(id)
    }
  }
}
```

**File References:**

- `packages/opencode/src/session/index.ts` - Complete example
- `packages/opencode/src/mcp/index.ts` - Multi-client manager
- `packages/opencode/src/lsp/index.ts` - Lazy spawning

---

## 10. State Management Standards

### 10.1 Per-Instance State Isolation

**Rule: All state must be isolated per working directory**

```typescript
// packages/opencode/src/project/instance.ts

export namespace Instance {
  // Current working directory
  export let directory = process.cwd()

  // Git worktree root
  export let worktree = directory

  // Project ID
  export let id = "unknown"

  // Create state scoped to current instance
  export function state<S>(
    init: () => S | Promise<S>,
    dispose?: (state: Awaited<S>) => Promise<void>,
  ): () => Awaited<S> {
    return State.create(
      () => Instance.directory, // Key by directory
      init,
      dispose,
    )
  }
}

// packages/opencode/src/project/state.ts

const recordsByKey = new Map<string, Map<Function, Entry>>()

interface Entry {
  state: any
  dispose?: (state: any) => Promise<void>
}

export function create<S>(
  root: () => string,
  init: () => S | Promise<S>,
  dispose?: (state: Awaited<S>) => Promise<void>,
): () => Awaited<S> {
  return () => {
    const key = root()

    // Get or create entries for this key
    let entries = recordsByKey.get(key)
    if (!entries) {
      entries = new Map<Function, Entry>()
      recordsByKey.set(key, entries)
    }

    // Get or initialize state
    const exists = entries.get(init)
    if (exists) {
      return exists.state as Awaited<S>
    }

    const state = init()
    entries.set(init, { state, dispose })

    return state as Awaited<S>
  }
}

// Dispose all state for a key
export async function dispose(key: string) {
  const entries = recordsByKey.get(key)
  if (!entries) return

  await Promise.all(
    Array.from(entries.values()).map(async (entry) => {
      if (entry.dispose) {
        const state = await entry.state
        await entry.dispose(state)
      }
    }),
  )

  recordsByKey.delete(key)
}
```

**File References:**

- `packages/opencode/src/project/instance.ts` - Lines 66-68
- `packages/opencode/src/project/state.ts` - Lines 12-29

### 10.2 State Initialization Pattern

```typescript
// ✅ GOOD - Lazy initialization with disposal
const state = Instance.state(
  async () => {
    log.info("initializing LSP clients")

    const cfg = await Config.get()
    const servers: Record<string, LSPServer.Info> = {}
    const clients: LSPClient.Info[] = []

    // Initialize servers
    for (const [id, server] of Object.entries(LSPServer)) {
      if (cfg.lsp?.[id]?.enabled !== false) {
        servers[id] = server
      }
    }

    return {
      servers,
      clients,
      broken: new Set<string>(),
      spawning: new Map<string, Promise<LSPClient.Info | undefined>>(),
    }
  },
  async (state) => {
    log.info("disposing LSP clients")

    // Cleanup all clients
    await Promise.all(
      state.clients.map(async (client) => {
        try {
          await client.shutdown()
        } catch (error) {
          log.error("failed to shutdown client", { client: client.id, error })
        }
      }),
    )
  },
)

// Access state
const lspState = state()
lspState.clients.push(newClient)
```

### 10.3 Global State (Rare)

**Rule: Avoid global state, use per-instance state instead**

```typescript
// ❌ AVOID - Global mutable state
const sessions = new Map<string, Session>()

export function addSession(session: Session) {
  sessions.set(session.id, session)
}

// ✅ PREFER - Per-instance state
const state = Instance.state(async () => ({
  sessions: new Map<string, Session>(),
}))

export function addSession(session: Session) {
  state().sessions.set(session.id, session)
}

// ✅ ACCEPTABLE - Truly global state (user config, auth tokens)
export namespace Global {
  export namespace Path {
    export const home = os.homedir()
    export const config = path.join(home, ".config", "opencode")
    export const data = path.join(home, ".local", "share", "opencode")
    export const cache = path.join(home, ".cache", "opencode")
  }
}
```

---

## 11. Event Bus Standards

### 11.1 Event Definition

```typescript
// packages/opencode/src/bus/event.ts

export namespace BusEvent {
  export interface Definition<Properties extends z.ZodType = any> {
    type: string
    properties: Properties
  }

  export function define<Properties extends z.ZodType>(type: string, properties: Properties): Definition<Properties> {
    return { type, properties }
  }
}

// Usage: Define events for a service
export namespace Session {
  export const Event = {
    Created: BusEvent.define("session.created", z.object({ info: Info })),

    Updated: BusEvent.define("session.updated", z.object({ info: Info, changes: z.record(z.unknown()) })),

    Deleted: BusEvent.define("session.deleted", z.object({ id: z.string() })),

    Diff: BusEvent.define(
      "session.diff",
      z.object({
        sessionID: z.string(),
        messageID: z.string(),
        diff: z.object({
          file: z.string(),
          additions: z.number(),
          deletions: z.number(),
        }),
      }),
    ),

    Error: BusEvent.define(
      "session.error",
      z.object({
        sessionID: z.string(),
        error: z.object({
          message: z.string(),
          code: z.string().optional(),
        }),
      }),
    ),

    Question: BusEvent.define(
      "session.question",
      z.object({
        sessionID: z.string(),
        question: z.object({
          type: z.string(),
          message: z.string(),
          options: z.array(z.unknown()),
        }),
        respond: z.function(),
      }),
    ),
  }
}
```

### 11.2 Publishing Events

```typescript
// packages/opencode/src/bus/index.ts

export namespace Bus {
  const state = Instance.state(async () => ({
    subscriptions: new Map<string, Set<Handler>>(),
  }))

  type Handler = (payload: EventPayload) => void | Promise<void>

  interface EventPayload {
    type: string
    properties: any
  }

  export async function publish<Definition extends BusEvent.Definition>(
    def: Definition,
    properties: z.output<Definition["properties"]>,
  ): Promise<void> {
    const payload: EventPayload = {
      type: def.type,
      properties,
    }

    const pending: Promise<void>[] = []

    // Notify specific subscribers
    const specific = state().subscriptions.get(def.type)
    if (specific) {
      for (const handler of specific) {
        pending.push(Promise.resolve(handler(payload)))
      }
    }

    // Notify wildcard subscribers
    const wildcard = state().subscriptions.get("*")
    if (wildcard) {
      for (const handler of wildcard) {
        pending.push(Promise.resolve(handler(payload)))
      }
    }

    // Also publish to global bus (for cross-instance communication)
    GlobalBus.emit("event", {
      directory: Instance.directory,
      payload,
    })

    await Promise.all(pending)
  }
}

// Usage: Publish an event
await Bus.publish(Session.Event.Created, {
  info: {
    id: "session-123",
    title: "New Session",
    created: Date.now(),
  },
})

await Bus.publish(Session.Event.Updated, {
  info: updatedSession,
  changes: { title: "Updated Title" },
})
```

**File Reference:** `packages/opencode/src/bus/index.ts:41-64`

### 11.3 Subscribing to Events

```typescript
// packages/opencode/src/bus/index.ts

export namespace Bus {
  export function subscribe<Definition extends BusEvent.Definition>(
    def: Definition | "*",
    handler: (payload: { type: string; properties: z.output<Definition["properties"]> }) => void | Promise<void>,
  ): Disposable {
    const key = typeof def === "string" ? def : def.type

    let subs = state().subscriptions.get(key)
    if (!subs) {
      subs = new Set()
      state().subscriptions.set(key, subs)
    }

    subs.add(handler)

    return {
      [Symbol.dispose]: () => {
        subs?.delete(handler)
        if (subs?.size === 0) {
          state().subscriptions.delete(key)
        }
      },
    }
  }
}

// Usage: Subscribe to specific events
const subscription = Bus.subscribe(Session.Event.Created, async (event) => {
  log.info("session created", { id: event.properties.info.id })
  await notifyUser(`New session: ${event.properties.info.title}`)
})

// Unsubscribe
subscription[Symbol.dispose]()

// Or use disposable pattern
{
  using sub = Bus.subscribe(Session.Event.Updated, handleUpdate)

  // Automatically unsubscribes when scope exits
}

// Subscribe to all events
Bus.subscribe("*", (event) => {
  log.debug("event", { type: event.type, properties: event.properties })
})
```

### 11.4 Event-Driven Communication Pattern

```typescript
// Service A: Publish events
export namespace FileWatcher {
  export const Event = {
    Updated: BusEvent.define(
      "file.updated",
      z.object({
        file: z.string(),
        event: z.enum(["add", "change", "unlink"]),
      }),
    ),
  }

  async function watch(directory: string) {
    const watcher = chokidar.watch(directory)

    watcher.on("change", async (file) => {
      await Bus.publish(Event.Updated, {
        file,
        event: "change",
      })
    })
  }
}

// Service B: React to events
export namespace LSP {
  export async function initialize() {
    // Subscribe to file changes
    Bus.subscribe(FileWatcher.Event.Updated, async (event) => {
      if (event.properties.event === "change") {
        await notifyClientsOfChange(event.properties.file)
      }
    })
  }

  async function notifyClientsOfChange(file: string) {
    const clients = state().clients.filter((c) => c.watchesFile(file))
    await Promise.all(clients.map((c) => c.didChangeTextDocument({ uri: file })))
  }
}

// Service C: Also react to same events
export namespace Session {
  export async function initialize() {
    Bus.subscribe(FileWatcher.Event.Updated, async (event) => {
      // Invalidate cached file contents
      await invalidateFileCache(event.properties.file)
    })
  }
}
```

---

## 12. Configuration Management Standards

### 12.1 Configuration Precedence

**Order (Low → High priority):**

1. **Remote `.well-known/opencode`** - Organization defaults
2. **Global config** - `~/.config/opencode/opencode.json{,c}`
3. **Custom config** - `OPENCODE_CONFIG` env var path
4. **Project config** - `opencode.json{,c}` in project
5. **`.opencode` directories** - `.opencode/opencode.json{,c}`
6. **Inline config** - `OPENCODE_CONFIG_CONTENT` env var
7. **Managed config** - Enterprise `/etc/opencode` (highest priority)

```typescript
// packages/opencode/src/config/config.ts

export namespace Config {
  export const state = Instance.state(async () => {
    let result: Info = {}

    // 1. Remote organization config
    const auth = await Auth.all()
    for (const [key, value] of Object.entries(auth)) {
      if (value.type === "wellknown") {
        const response = await fetch(`${key}/.well-known/opencode`)
        const wellknown = await response.json()
        result = mergeConfigConcatArrays(result, wellknown.config ?? {})
      }
    }

    // 2. Global user config
    result = mergeConfigConcatArrays(result, await global())

    // 3. Custom config path
    if (Flag.OPENCODE_CONFIG) {
      result = mergeConfigConcatArrays(result, await loadFile(Flag.OPENCODE_CONFIG))
    }

    // 4. Project config (if not disabled)
    if (!Flag.OPENCODE_DISABLE_PROJECT_CONFIG) {
      for (const file of ["opencode.jsonc", "opencode.json"]) {
        const found = await Filesystem.findUp(file, Instance.directory, Instance.worktree)
        for (const resolved of found.toReversed()) {
          result = mergeConfigConcatArrays(result, await loadFile(resolved))
        }
      }
    }

    // 5. .opencode directories
    const directories = [
      Global.Path.config,
      ...(!Flag.OPENCODE_DISABLE_PROJECT_CONFIG
        ? await Array.fromAsync(
            Filesystem.up({
              targets: [".opencode"],
              start: Instance.directory,
              stop: Instance.worktree,
            }),
          )
        : []),
      // Always scan user home ~/.opencode/
      ...(await Array.fromAsync(
        Filesystem.up({
          targets: [".opencode"],
          start: Global.Path.home,
          stop: Global.Path.home,
        }),
      )),
    ]

    for (const dir of unique(directories)) {
      for (const file of ["opencode.jsonc", "opencode.json"]) {
        const configPath = path.join(dir, file)
        if (await Filesystem.exists(configPath)) {
          result = mergeConfigConcatArrays(result, await loadFile(configPath))
        }
      }
    }

    // 6. Inline config
    if (Flag.OPENCODE_CONFIG_CONTENT) {
      result = mergeConfigConcatArrays(result, await load(Flag.OPENCODE_CONFIG_CONTENT, "inline"))
    }

    // 7. Managed config (enterprise, highest priority)
    const managedPath = path.join(managedConfigDir, "opencode.json")
    if (await Filesystem.exists(managedPath)) {
      result = mergeConfigConcatArrays(result, await loadFile(managedPath))
    }

    return result
  })

  export const get = fn(z.void(), async () => state())
}
```

**File Reference:** `packages/opencode/src/config/config.ts:62-150`

### 12.2 Configuration Merge Strategy

```typescript
// packages/opencode/src/config/config.ts

function mergeConfigConcatArrays(target: Info, source: Info): Info {
  // Deep merge objects
  const merged = mergeDeep(target, source)

  // Special handling: Concatenate arrays instead of replacing
  if (target.plugin && source.plugin) {
    merged.plugin = Array.from(new Set([...target.plugin, ...source.plugin]))
  }

  if (target.instructions && source.instructions) {
    merged.instructions = Array.from(new Set([...target.instructions, ...source.instructions]))
  }

  return merged
}

// Example:
// Base config:    { plugin: ["a", "b"], model: { id: "gpt-4" } }
// Override config: { plugin: ["b", "c"], model: { temperature: 0.7 } }
// Result:         { plugin: ["a", "b", "c"], model: { id: "gpt-4", temperature: 0.7 } }
```

**File Reference:** `packages/opencode/src/config/config.ts:51-60`

### 12.3 Configuration Schema

```typescript
export namespace Config {
  export type Info = z.infer<typeof Info>
  export const Info = z.object({
    // Model configuration
    model: z
      .object({
        id: z.string().optional(),
        providerID: z.string().optional(),
        temperature: z.number().optional(),
        maxTokens: z.number().optional(),
      })
      .optional(),

    // Providers
    providers: z
      .record(
        z.object({
          apiKey: z.string().optional(),
          baseURL: z.string().optional(),
          enabled: z.boolean().optional(),
        }),
      )
      .optional(),

    // Plugins
    plugin: z.array(z.string()).optional(),

    // Instructions (system prompts)
    instructions: z.array(z.string()).optional(),

    // Agents
    agent: z
      .record(
        z.object({
          mode: z.enum(["primary", "secondary"]).optional(),
          prompt: z.string().optional(),
          permission: z.string().optional(),
        }),
      )
      .optional(),

    // LSP servers
    lsp: z
      .record(
        z.object({
          enabled: z.boolean().optional(),
          command: z.string().optional(),
          args: z.array(z.string()).optional(),
        }),
      )
      .optional(),

    // MCP servers
    mcp: z
      .record(
        z.union([
          z.object({
            command: z.string(),
            args: z.array(z.string()).optional(),
            env: z.record(z.string()).optional(),
            enabled: z.boolean().optional(),
          }),
          z.object({
            url: z.string(),
            transport: z.literal("sse"),
            enabled: z.boolean().optional(),
          }),
        ]),
      )
      .optional(),

    // Formatters
    formatter: z
      .record(
        z.object({
          command: z.string(),
          args: z.array(z.string()).optional(),
        }),
      )
      .optional(),
  })
}
```

### 12.4 Configuration File Loading

```typescript
export namespace Config {
  async function loadFile(filepath: string): Promise<Info> {
    if (!(await Filesystem.exists(filepath))) {
      return {}
    }

    const content = await Bun.file(filepath).text()
    return load(content, filepath)
  }

  async function load(content: string, source: string): Promise<Info> {
    try {
      // Parse JSONC (JSON with comments)
      const parsed = parseJsonc(content)

      // Validate against schema
      const validated = Info.parse(parsed)

      return validated
    } catch (error) {
      if (error instanceof z.ZodError) {
        log.error("config validation failed", {
          source,
          errors: error.errors,
        })
        throw new Error(`Invalid config at ${source}: ${error.errors[0].message}`)
      }

      throw error
    }
  }
}
```

---

## 13. Storage & Persistence Standards

### 13.1 Storage Operations

```typescript
// packages/opencode/src/storage/storage.ts

export namespace Storage {
  const log = Log.create({ service: "storage" })

  export const NotFoundError = NamedError.create("NotFoundError", z.object({ message: z.string() }))

  // Read with lock
  export async function read<T>(target: string): Promise<T> {
    using _ = await Lock.read(target)

    const file = Bun.file(target)
    if (!(await file.exists())) {
      throw NotFoundError.create({
        message: `File not found: ${target}`,
      })
    }

    return file.json()
  }

  // Write with lock
  export async function write(target: string, data: any): Promise<void> {
    using _ = await Lock.write(target)

    const dir = path.dirname(target)
    await fs.mkdir(dir, { recursive: true })

    await Bun.write(target, JSON.stringify(data, null, 2))
  }

  // Update (read-modify-write)
  export async function update<T>(target: string, editor: (draft: T) => void | Promise<void>): Promise<T> {
    using _ = await Lock.write(target)

    const data = await read<T>(target)
    await editor(data)
    await write(target, data)

    return data
  }

  // Delete
  export async function remove(target: string): Promise<void> {
    using _ = await Lock.write(target)

    if (await Filesystem.exists(target)) {
      await fs.rm(target, { recursive: true })
    }
  }

  // List files matching pattern
  export async function list(directory: string, pattern: string): Promise<string[]> {
    using _ = await Lock.read(directory)

    const files: string[] = []
    for await (const file of new Bun.Glob(pattern).scan({ cwd: directory })) {
      files.push(path.join(directory, file))
    }

    return files
  }
}
```

**File Reference:** `packages/opencode/src/storage/storage.ts:1-200`

### 13.2 Storage Paths

```typescript
export namespace Storage {
  export function path(...segments: string[]): string {
    return path.join(Global.Path.data, ...segments)
  }

  // Session storage
  export namespace Session {
    export function info(sessionID: string): string {
      return Storage.path("session", sessionID, "info.json")
    }

    export function messages(sessionID: string): string {
      return Storage.path("session", sessionID, "messages")
    }

    export function message(sessionID: string, messageID: string): string {
      return Storage.path("session", sessionID, "messages", `${messageID}.json`)
    }
  }

  // Project storage
  export namespace Project {
    export function info(projectID: string): string {
      return Storage.path("project", `${projectID}.json`)
    }

    export function list(): Promise<string[]> {
      return Storage.list(Storage.path("project"), "*.json")
    }
  }

  // Cache storage
  export namespace Cache {
    export function file(key: string): string {
      return Storage.path("cache", `${key}.json`)
    }
  }
}
```

### 13.3 Migration Pattern

```typescript
export namespace Storage {
  type Migration = (dir: string) => Promise<void>

  const MIGRATIONS: Migration[] = [
    // Migration 1: Rename old directories
    async (dir) => {
      const oldPath = path.join(dir, "old-structure")
      const newPath = path.join(dir, "new-structure")

      if (await Filesystem.exists(oldPath)) {
        await fs.rename(oldPath, newPath)
        log.info("migrated directory structure")
      }
    },

    // Migration 2: Transform data format
    async (dir) => {
      const files = await Storage.list(path.join(dir, "sessions"), "*.json")

      for (const file of files) {
        const data = await Storage.read<any>(file)

        // Add new field
        if (!data.version) {
          data.version = 2
          data.migrated = Date.now()
          await Storage.write(file, data)
        }
      }

      log.info("migrated session data", { count: files.length })
    },

    // Migration 3: Consolidate files
    async (dir) => {
      const oldDir = path.join(dir, "old")
      const newFile = path.join(dir, "consolidated.json")

      if (await Filesystem.exists(oldDir)) {
        const files = await Storage.list(oldDir, "*.json")
        const consolidated = await Promise.all(files.map((f) => Storage.read(f)))

        await Storage.write(newFile, consolidated)
        await fs.rm(oldDir, { recursive: true })

        log.info("consolidated files", { count: files.length })
      }
    },
  ]

  export async function migrate(): Promise<void> {
    const dataDir = Global.Path.data
    const versionFile = path.join(dataDir, ".version")

    let currentVersion = 0
    if (await Filesystem.exists(versionFile)) {
      currentVersion = Number(await Bun.file(versionFile).text())
    }

    const targetVersion = MIGRATIONS.length

    if (currentVersion >= targetVersion) {
      log.debug("storage up to date", { version: currentVersion })
      return
    }

    log.info("migrating storage", {
      from: currentVersion,
      to: targetVersion,
    })

    // Run pending migrations
    for (let i = currentVersion; i < targetVersion; i++) {
      log.info(`running migration ${i + 1}/${targetVersion}`)
      await MIGRATIONS[i](dataDir)
    }

    // Update version
    await Bun.write(versionFile, String(targetVersion))

    log.info("migration complete", { version: targetVersion })
  }
}
```

**File Reference:** `packages/opencode/src/storage/storage.ts:24-100`

---

## 14. Error Handling Standards

### 14.1 Named Errors (Preferred)

```typescript
// packages/opencode/src/util/error.ts

import { NamedError } from "@opencode-ai/util/error"
import z from "zod"

// Define typed errors
export const NotFoundError = NamedError.create(
  "NotFoundError",
  z.object({
    message: z.string(),
    resource: z.string().optional(),
    id: z.string().optional(),
  }),
)

export const ValidationError = NamedError.create(
  "ValidationError",
  z.object({
    message: z.string(),
    field: z.string().optional(),
    expected: z.string().optional(),
    received: z.string().optional(),
  }),
)

export const PermissionError = NamedError.create(
  "PermissionError",
  z.object({
    message: z.string(),
    action: z.string(),
    resource: z.string(),
  }),
)

// Usage: Throw typed error
throw NotFoundError.create({
  message: "Session not found",
  resource: "session",
  id: sessionID,
})

// Usage: Catch and check type
try {
  await operation()
} catch (error) {
  if (NotFoundError.is(error)) {
    log.warn("resource not found", {
      resource: error.data.resource,
      id: error.data.id,
    })
    return null
  }

  if (PermissionError.is(error)) {
    log.error("permission denied", {
      action: error.data.action,
      resource: error.data.resource,
    })
    throw error
  }

  // Unknown error
  log.error("unexpected error", { error })
  throw error
}
```

**File Reference:** `packages/opencode/src/storage/storage.ts:17-22`

### 14.2 Custom Error Classes (When Needed)

```typescript
// ✅ GOOD - Error with additional context
export class BusyError extends Error {
  constructor(public readonly sessionID: string) {
    super(`Session ${sessionID} is busy`)
    this.name = "BusyError"
  }
}

// Usage
throw new BusyError(sessionID)

// Catching
try {
  await process(sessionID)
} catch (error) {
  if (error instanceof BusyError) {
    log.info("session busy, retrying", { sessionID: error.sessionID })
    await retry()
  }
}
```

**File Reference:** `packages/opencode/src/session/index.ts:494`

### 14.3 Result Pattern (for Tools)

```typescript
// ✅ GOOD - Never throw in tool execution
export const ReadTool = Tool.define("read", {
  async execute(args, context) {
    try {
      const content = await Bun.file(args.filePath).text()

      return {
        output: content,
        title: `Read ${path.basename(args.filePath)}`,
      }
    } catch (error) {
      return {
        output: `Error reading file: ${error.message}`,
        title: "Read Failed",
        metadata: {
          error: true,
          message: error.message,
        },
      }
    }
  },
})

// ✅ GOOD - Result type for fallible operations
export type Result<T, E = Error> = { success: true; value: T } | { success: false; error: E }

export async function operation(): Promise<Result<Data>> {
  try {
    const data = await fetchData()
    return { success: true, value: data }
  } catch (error) {
    return { success: false, error }
  }
}

// Usage
const result = await operation()
if (result.success) {
  console.log(result.value)
} else {
  log.error("operation failed", { error: result.error })
}
```

### 14.4 Error Context

```typescript
// ✅ GOOD - Rich error context
class OperationError extends Error {
  constructor(
    message: string,
    public readonly context: {
      operation: string
      input: unknown
      timestamp: number
      sessionID?: string
    }
  ) {
    super(message)
    this.name = "OperationError"
  }
}

// Usage
try {
  await processData(input)
} catch (error) {
  throw new OperationError(
    "Failed to process data",
    {
      operation: "processData",
      input,
      timestamp: Date.now(),
      sessionID: context.sessionID
    }
  )
}

// Logging with context
catch (error) {
  if (error instanceof OperationError) {
    log.error("operation failed", {
      operation: error.context.operation,
      sessionID: error.context.sessionID,
      error: error.message
    })
  }
}
```

---

## 15. Type System Standards

### 15.1 Zod Schemas (Primary)

**Rule: Use Zod for runtime validation, derive TypeScript types from schemas**

```typescript
// ✅ GOOD - Schema-first approach
export namespace Session {
  export const Info = z.object({
    id: z.string(),
    title: z.string(),
    projectID: z.string(),
    modelID: z.string().optional(),
    permission: z.enum(["allow", "ask", "deny"]),
    time: z.object({
      created: z.number(),
      updated: z.number(),
    }),
  })

  // Derive TypeScript type from schema
  export type Info = z.infer<typeof Info>

  // Use in functions
  export const create = fn(Info.pick({ title: true, projectID: true }).partial(), async (input): Promise<Info> => {
    // Implementation
  })
}

// ❌ BAD - Type-first approach (no runtime validation)
export interface SessionInfo {
  id: string
  title: string
  projectID: string
}

export function create(input: Partial<SessionInfo>): SessionInfo {
  // No validation! Runtime errors possible
}
```

### 15.2 Type Inference

**Rule: Rely on type inference, avoid explicit annotations**

```typescript
// ✅ GOOD - Let TypeScript infer
const session = await Session.create({ title: "New" })
const messages = session.messages.filter((m) => m.role === "user")
const ids = messages.map((m) => m.id)

// ❌ BAD - Unnecessary annotations
const session: Session.Info = await Session.create({ title: "New" })
const messages: Message[] = session.messages.filter((m) => m.role === "user")
const ids: string[] = messages.map((m) => m.id)

// ✅ ACCEPTABLE - Annotation for clarity in complex scenarios
const messages: Message[] = await fetchMessages().then((msgs): Message[] => {
  return msgs.filter((m) => m.deleted !== true)
})
```

**File Reference:** `AGENTS.md:15`

### 15.3 Avoid `any`

```typescript
// ❌ BAD
function process(data: any) {
  return data.value.toString()
}

// ✅ GOOD - Use unknown and validate
function process(data: unknown) {
  if (typeof data !== "object" || data === null) {
    throw new Error("Expected object")
  }

  if (!("value" in data)) {
    throw new Error("Missing value property")
  }

  return String(data.value)
}

// ✅ BEST - Use Zod schema
const DataSchema = z.object({
  value: z.union([z.string(), z.number()]),
})

function process(data: unknown) {
  const validated = DataSchema.parse(data)
  return String(validated.value)
}
```

**File Reference:** `AGENTS.md:12`

### 15.4 Type Guards

```typescript
// ✅ GOOD - Type guards for narrowing
function isMessage(value: unknown): value is Message {
  return typeof value === "object" && value !== null && "id" in value && "role" in value && typeof value.id === "string"
}

// Usage
if (isMessage(data)) {
  console.log(data.id) // TypeScript knows data is Message
}

// ✅ GOOD - Type guards in filter
const messages = items.filter((item): item is Message => isMessage(item)).map((msg) => msg.id)

// ✅ GOOD - Discriminated unions
type Part =
  | { type: "text"; text: string }
  | { type: "file"; data: Buffer; mimeType: string }
  | { type: "patch"; files: string[]; diff: string }

function handle(part: Part) {
  switch (part.type) {
    case "text":
      console.log(part.text) // TypeScript knows: text part
      break
    case "file":
      console.log(part.mimeType) // TypeScript knows: file part
      break
    case "patch":
      console.log(part.files) // TypeScript knows: patch part
      break
    default:
      const _exhaustive: never = part
      throw new Error("Unhandled part type")
  }
}
```

---

## 16. Import Organization Standards

### 16.1 Import Order

```typescript
// 1. Zod and validation libraries
import z from "zod"

// 2. Node.js built-ins
import path from "path"
import fs from "fs/promises"
import os from "os"

// 3. External packages (alphabetical)
import { mergeDeep, sortBy, unique } from "remeda"
import chokidar from "chokidar"
import fuzzysort from "fuzzysort"

// 4. Internal packages (@opencode-ai/*)
import { NamedError } from "@opencode-ai/util/error"

// 5. Project utilities (../util/*)
import { Log } from "../util/log"
import { Lock } from "../util/lock"
import { fn } from "../util/fn"

// 6. Project services (../<service>/*)
import { Config } from "../config/config"
import { Storage } from "../storage/storage"
import { Bus } from "../bus"

// 7. Relative imports (same directory)
import { Session } from "./session"
import { MessageV2 } from "./message-v2"
```

### 16.2 Import Style

```typescript
// ✅ GOOD - Named imports
import { create, update, get } from "./session"
import { Log, type LogOptions } from "./util/log"

// ❌ AVOID - Default imports (except for external packages)
import session from "./session"

// ✅ GOOD - Namespace imports for large APIs
import * as Session from "./session"

// ✅ GOOD - Type-only imports
import type { Session } from "./session"
import { type Config, loadConfig } from "./config"
```

### 16.3 Circular Dependency Prevention

```typescript
// ❌ BAD - Circular dependency
// file-a.ts
import { funcB } from "./file-b"
export function funcA() {
  return funcB()
}

// file-b.ts
import { funcA } from "./file-a"
export function funcB() {
  return funcA()
}

// ✅ GOOD - Extract shared code
// shared.ts
export function shared() {
  return 42
}

// file-a.ts
import { shared } from "./shared"
export function funcA() {
  return shared()
}

// file-b.ts
import { shared } from "./shared"
export function funcB() {
  return shared()
}
```

---

## 17. Naming Conventions

### 17.1 Functions & Variables

```typescript
// ✅ camelCase for functions and variables
const sessionID = "abc123"
const userAgent = "opencode/1.0"
const maxRetries = 3

async function processMessage(messageID: string) {}
async function createSession() {}
```

### 17.2 Types & Interfaces

```typescript
// ✅ PascalCase for types, interfaces, and classes
type SessionInfo = {
  id: string
  title: string
}

interface Message {
  id: string
  content: string
}

class BusyError extends Error {}

namespace Session {
  export type Info = z.infer<typeof Info>
}
```

### 17.3 Constants

```typescript
// ✅ SCREAMING_SNAKE_CASE for true constants
const MAX_RETRY_ATTEMPTS = 3
const DEFAULT_TIMEOUT = 5000
const API_BASE_URL = "https://api.example.com"

// ✅ camelCase for configuration values
const maxRetries = config.retries ?? 3
const defaultModel = config.model?.id ?? "gpt-4"
```

### 17.4 Namespaces

```typescript
// ✅ PascalCase for namespaces
export namespace Session {}
export namespace Storage {}
export namespace FileWatcher {}
```

### 17.5 Files

```typescript
// ✅ kebab-case for files
// session-manager.ts
// message-processor.ts
// file-watcher.ts

// ✅ Single word when possible
// session.ts
// storage.ts
// config.ts
```

---

## 18. Testing Standards

### 18.1 Principles

1. **Avoid mocks** - Test actual implementation
2. **No logic duplication** - Don't reimplement logic in tests
3. **Use Bun test runner** - `bun test`

**File Reference:** `AGENTS.md:108-111`

### 18.2 Test Structure

```typescript
// packages/opencode/src/addons/serialize.test.ts

import { expect, test, describe } from "bun:test"
import { serialize, deserialize } from "./serialize"

describe("serialize", () => {
  test("preserves Date objects", () => {
    const input = { date: new Date("2024-01-01") }
    const serialized = serialize(input)
    const deserialized = deserialize(serialized)

    expect(deserialized.date).toBeInstanceOf(Date)
    expect(deserialized.date.toISOString()).toBe("2024-01-01T00:00:00.000Z")
  })

  test("preserves Set objects", () => {
    const input = { set: new Set([1, 2, 3]) }
    const serialized = serialize(input)
    const deserialized = deserialize(serialized)

    expect(deserialized.set).toBeInstanceOf(Set)
    expect(Array.from(deserialized.set)).toEqual([1, 2, 3])
  })

  test("handles nested structures", () => {
    const input = {
      map: new Map([["key", { date: new Date("2024-01-01") }]]),
      array: [new Set([1, 2])],
    }
    const serialized = serialize(input)
    const deserialized = deserialize(serialized)

    expect(deserialized.map).toBeInstanceOf(Map)
    expect(deserialized.map.get("key")?.date).toBeInstanceOf(Date)
    expect(deserialized.array[0]).toBeInstanceOf(Set)
  })
})
```

**File Reference:** `packages/opencode/src/addons/serialize.test.ts`

### 18.3 Test Commands

```bash
# Run all tests
bun test

# Run specific test file
bun test src/util/queue.test.ts

# Run tests matching pattern
bun test --test-name-pattern "serialize"

# Watch mode
bun test --watch

# Coverage
bun test --coverage
```

**File Reference:** `packages/opencode/AGENTS.md` - Build/Test Commands

### 18.4 Integration Tests

```typescript
import { test, expect, beforeAll, afterAll } from "bun:test"
import { Session } from "./session"
import { Storage } from "./storage"

let sessionID: string

beforeAll(async () => {
  // Setup: Create test session
  const session = await Session.create({ title: "Test Session" })
  sessionID = session.id
})

afterAll(async () => {
  // Cleanup: Delete test session
  await Session.delete(sessionID)
})

test("create and retrieve session", async () => {
  const session = await Session.get(sessionID)

  expect(session).toBeDefined()
  expect(session.id).toBe(sessionID)
  expect(session.title).toBe("Test Session")
})

test("update session", async () => {
  await Session.update(sessionID, { title: "Updated" })

  const session = await Session.get(sessionID)
  expect(session.title).toBe("Updated")
})
```

---

## 19. Documentation Standards

### 19.1 Code Comments

**Rule: Comment WHY, not WHAT**

```typescript
// ✅ GOOD - Explains why
// Cache header separately to enable 2-part prompt caching
if (system.length > 2 && system[0] === header) {
  system.length = 0
  system.push(header, rest.join("\n"))
}

// Prevent race condition: lock before checking existence
using _ = await Lock.write(filepath)
if (await Filesystem.exists(filepath)) {
  await fs.rm(filepath)
}

// ❌ BAD - States the obvious
// Push the item to the array
items.push(item)

// Set the title property
session.title = "New Title"
```

### 19.2 JSDoc (For Exported APIs)

````typescript
/**
 * Execute a function with a file lock to prevent concurrent access.
 *
 * The lock is automatically released when the function completes or throws.
 * Locks are queued and processed in order.
 *
 * @param filepath - Absolute path to the file to lock
 * @param fn - Function to execute while holding the lock
 * @returns The result of the function
 *
 * @example
 * ```typescript
 * await withLock("/path/to/file", async () => {
 *   const content = await Bun.file("/path/to/file").text()
 *   await Bun.write("/path/to/file", content + "\n")
 * })
 * ```
 */
export async function withLock<T>(filepath: string, fn: () => Promise<T>): Promise<T>
````

### 19.3 README Structure

```markdown
# Package Name

Brief description of what this package does.

## Installation

\`\`\`bash
bun install @opencode-ai/package-name
\`\`\`

## Usage

\`\`\`typescript
import { feature } from "@opencode-ai/package-name"

await feature()
\`\`\`

## API

### `function(param: Type): ReturnType`

Description of function.

**Parameters:**

- `param` - Description of parameter

**Returns:** Description of return value

**Example:**
\`\`\`typescript
const result = await function(param)
\`\`\`

## Development

\`\`\`bash
bun install
bun test
\`\`\`
```

---

## 20. Schema Definition Standards

### 20.1 Drizzle Schema (Database)

**Rule: Use snake_case for field names to match SQL conventions**

```typescript
// ✅ GOOD - snake_case fields
const sessionTable = sqliteTable("session", {
  id: text().primaryKey(),
  project_id: text().notNull(),
  created_at: integer().notNull(),
  updated_at: integer().notNull(),
})

// ❌ BAD - camelCase requires explicit column names
const sessionTable = sqliteTable("session", {
  id: text("id").primaryKey(),
  projectID: text("project_id").notNull(),
  createdAt: integer("created_at").notNull(),
  updatedAt: integer("updated_at").notNull(),
})
```

**File Reference:** `AGENTS.md:88-106`

### 20.2 Zod Schema

```typescript
// ✅ GOOD - Consistent field naming
export const SessionInfo = z.object({
  id: z.string(),
  projectID: z.string(), // camelCase for TypeScript
  title: z.string(),
  permission: z.enum(["allow", "ask", "deny"]),
  time: z.object({
    created: z.number(),
    updated: z.number(),
  }),
})

// ✅ GOOD - Schema composition
export const CreateSessionInput = SessionInfo.pick({
  title: true,
  projectID: true,
}).partial()

export const UpdateSessionInput = SessionInfo.partial().required({
  id: true,
})

// ✅ GOOD - Schema extension
export const SessionWithMessages = SessionInfo.extend({
  messages: z.array(MessageInfo),
})
```

---

## 21. Dependency Management Standards

### 21.1 Bun Runtime Preference

**Rule: Use Bun APIs when available**

```typescript
// ✅ GOOD - Bun APIs
const content = await Bun.file(filepath).text()
await Bun.write(filepath, content)
const json = await Bun.file(filepath).json()

const proc = Bun.spawn(["ls", "-la"], {
  cwd: directory,
  stdout: "pipe",
})

// ❌ AVOID - Node.js fs when Bun alternative exists
import fs from "fs/promises"
const content = await fs.readFile(filepath, "utf-8")
await fs.writeFile(filepath, content)
```

**File Reference:** `AGENTS.md:14`

### 21.2 Package Installation

```bash
# Add dependency
bun add package-name

# Add dev dependency
bun add -d package-name

# Add workspace dependency
bun add @opencode-ai/other-package
```

### 21.3 Version Management

```json
// package.json
{
  "dependencies": {
    "zod": "^3.22.4", // Allow patch and minor updates
    "remeda": "1.30.0", // Pin exact version for critical deps
    "@ai-sdk/anthropic": "^0.0.39"
  },
  "devDependencies": {
    "@types/node": "^20.10.0",
    "typescript": "^5.3.3"
  }
}
```

---

## 22. Build & Development Standards

### 22.1 Development Commands

```bash
# Install dependencies
bun install

# Run in development (TUI)
bun dev                       # Run in packages/opencode
bun dev <directory>           # Run in specific directory
bun dev .                     # Run in repo root

# Run API server
bun dev serve                 # Start on port 4096
bun dev serve --port 8080     # Custom port

# Run web UI (requires server running)
bun dev web                   # Start server + open web UI
bun run --cwd packages/app dev  # Just web UI

# Run desktop app
bun run --cwd packages/desktop tauri dev

# Type checking
bun run typecheck

# Run tests
bun test
bun test path/to/test.ts

# Build standalone executable
./packages/opencode/script/build.ts --single

# Regenerate SDK (after server changes)
./script/generate.ts
```

**File Reference:** `CONTRIBUTING.md:30-150`

### 22.2 Project Structure

```
opencode/
├── packages/
│   ├── opencode/           # Core business logic & CLI
│   │   ├── src/
│   │   │   ├── session/    # Session management
│   │   │   ├── tool/       # Tool implementations
│   │   │   ├── agent/      # Agent system
│   │   │   ├── mcp/        # Model Context Protocol
│   │   │   ├── lsp/        # Language Server Protocol
│   │   │   ├── file/       # File operations
│   │   │   ├── config/     # Configuration
│   │   │   ├── provider/   # LLM providers
│   │   │   ├── server/     # HTTP/WebSocket server
│   │   │   └── cli/cmd/tui/  # Terminal UI (SolidJS)
│   │   └── script/
│   │       └── build.ts    # Build script
│   ├── app/                # Web UI (SolidJS)
│   ├── desktop/            # Native app (Tauri)
│   ├── sdk/js/             # TypeScript SDK
│   ├── plugin/             # Plugin system
│   └── console/            # Web console
├── script/
│   ├── generate.ts         # Generate SDK
│   └── format.ts           # Format code
├── AGENTS.md               # Agent guidelines
├── CONTRIBUTING.md         # Contribution guide
└── CODEBASE_STANDARDS.md   # This document
```

### 22.3 Build Output

```bash
# Single build creates:
packages/opencode/dist/opencode-darwin-arm64/
├── bin/
│   └── opencode           # Executable
├── node_modules/          # Bundled dependencies
└── package.json

# Run built executable:
./packages/opencode/dist/opencode-darwin-arm64/bin/opencode
```

---

## 23. Performance Standards

### 23.1 Lazy Initialization

```typescript
// ✅ GOOD - Lazy state initialization
const state = Instance.state(async () => {
  // Only initialize when first accessed
  const config = await Config.get()
  return { config, clients: [] }
})

// Access only when needed
if (needsClient) {
  const client = state().clients[0]
}

// ✅ GOOD - Lazy loading of heavy dependencies
const lazyModule = lazy(async () => {
  return import("./heavy-module")
})

// Load only when needed
const module = await lazyModule()
```

### 23.2 Caching

```typescript
// ✅ GOOD - Cache expensive operations
const cache = new Map<string, Data>()

async function getData(id: string): Promise<Data> {
  const cached = cache.get(id)
  if (cached) return cached

  const data = await fetchData(id)
  cache.set(id, data)
  return data
}

// ✅ GOOD - Time-based cache invalidation
const cache = new Map<string, { data: Data; expires: number }>()

async function getData(id: string): Promise<Data> {
  const cached = cache.get(id)
  if (cached && Date.now() < cached.expires) {
    return cached.data
  }

  const data = await fetchData(id)
  cache.set(id, {
    data,
    expires: Date.now() + 60_000, // 1 minute
  })
  return data
}
```

### 23.3 Debouncing

```typescript
// ✅ GOOD - Debounce high-frequency events
function debounce<T extends (...args: any[]) => any>(fn: T, delay: number): (...args: Parameters<T>) => void {
  let timer: Timer | undefined

  return (...args: Parameters<T>) => {
    if (timer) clearTimeout(timer)
    timer = setTimeout(() => {
      fn(...args)
      timer = undefined
    }, delay)
  }
}

// Usage
const debouncedSave = debounce(async (content: string) => {
  await save(content)
}, 500)

// Only saves after 500ms of inactivity
input.on("change", (content) => {
  debouncedSave(content)
})
```

### 23.4 Streaming

```typescript
// ✅ GOOD - Stream large responses
export async function* streamMessages(sessionID: string) {
  const files = await Storage.list(Storage.path("messages", sessionID), "*.json")

  for (const file of files) {
    const message = await Storage.read<Message>(file)
    yield message
  }
}

// Usage
for await (const message of streamMessages(sessionID)) {
  process(message)
}
```

---

## 24. Security Standards

### 24.1 Input Validation

```typescript
// ✅ GOOD - Validate all external input
export const handleRequest = fn(
  z.object({
    sessionID: z.string().regex(/^session-[a-z0-9]{10}$/),
    content: z.string().max(100_000),
    metadata: z.record(z.unknown()).optional(),
  }),
  async (input) => {
    // Input is validated, safe to use
    return process(input)
  },
)

// ✅ GOOD - Validate file paths
function validatePath(filepath: string) {
  const normalized = path.normalize(filepath)
  const absolute = path.resolve(normalized)

  // Prevent directory traversal
  if (!absolute.startsWith(Instance.worktree)) {
    throw new Error("Path outside worktree")
  }

  return absolute
}
```

### 24.2 Permission Checks

```typescript
// ✅ GOOD - Check permissions before sensitive operations
async function readFile(filepath: string, context: Context) {
  // Validate path
  const safe = validatePath(filepath)

  // Check permission
  const permission = await PermissionNext.evaluate("read", safe, context.agent.permission)

  if (permission.action === "deny") {
    throw PermissionError.create({
      message: "Permission denied",
      action: "read",
      resource: safe,
    })
  }

  if (permission.action === "ask") {
    const allowed = await context.ask({
      type: "permission",
      message: `Read file ${path.basename(safe)}?`,
      actions: ["allow", "deny"],
    })

    if (!allowed) {
      throw PermissionError.create({
        message: "User denied permission",
        action: "read",
        resource: safe,
      })
    }
  }

  // Permission granted, perform operation
  return Bun.file(safe).text()
}
```

### 24.3 Secrets Management

```typescript
// ✅ GOOD - Load secrets from environment
export namespace Auth {
  export async function get(providerID: string): Promise<string | undefined> {
    const key = `OPENCODE_${providerID.toUpperCase()}_API_KEY`
    return process.env[key]
  }
}

// ❌ AVOID - Hardcoded secrets
const API_KEY = "sk-abc123..."

// ❌ AVOID - Logging secrets
log.info("api key", { key: apiKey })

// ✅ GOOD - Redact secrets in logs
log.info("api request", { key: apiKey.slice(0, 8) + "..." })
```

### 24.4 Command Injection Prevention

```typescript
// ❌ BAD - Command injection vulnerability
const output = await $`ls ${userInput}`.text()

// ✅ GOOD - Use array syntax (prevents injection)
const proc = Bun.spawn(["ls", userInput], {
  stdout: "pipe",
})
const output = await new Response(proc.stdout).text()

// ✅ GOOD - Validate input
const sanitized = userInput.replace(/[^a-zA-Z0-9_-]/g, "")
const proc = Bun.spawn(["ls", sanitized])
```

---

## Summary: Key Principles

1. **Single-word function names** unless multi-word necessary (95%+ adherence)
2. **Namespaces over classes** for code organization (only 5 classes in 206 files)
3. **Functional array methods** over for-loops (85/15 split)
4. **Parallel execution by default** via `Promise.all`
5. **Lock mechanisms** prevent race conditions (reader-writer locks, file locks)
6. **Per-instance state isolation** for multi-project support
7. **Event-driven architecture** via pub/sub bus
8. **Zod validation** for all inputs via `fn()` wrapper
9. **Disposable resources** with `using` keyword for automatic cleanup
10. **Bun runtime preference** for file I/O and process spawning
11. **Inline values once, extract when reusable**
12. **Named errors** over throw strings
13. **Avoid mocks in tests**, test actual implementation
14. **Layered config** with clear precedence (7 levels)
15. **Graceful disposal** for all stateful services
16. **Prefer `const` over `let`** - use ternaries instead of reassignment
17. **Avoid `else` statements** - use early returns
18. **Avoid destructuring** - preserve context with dot notation
19. **Type inference** - avoid explicit annotations unless necessary
20. **Avoid `any` type** - use `unknown` with validation
21. **Comment WHY, not WHAT** - explain reasoning, not obvious operations
22. **Schema-first approach** - define Zod schemas, derive TS types
23. **Reader-writer locks** for concurrent access
24. **System prompt caching** - maintain 2-part structure for efficiency
25. **Context compaction** at 75% token threshold

---

## File References Quick Index

### Core Patterns

- **Function wrapper**: `packages/opencode/src/util/fn.ts`
- **State management**: `packages/opencode/src/project/state.ts`
- **Instance isolation**: `packages/opencode/src/project/instance.ts`
- **Event bus**: `packages/opencode/src/bus/index.ts`
- **Locks**: `packages/opencode/src/util/lock.ts`
- **Async queue**: `packages/opencode/src/util/queue.ts`

### Services

- **Session**: `packages/opencode/src/session/index.ts`
- **LLM streaming**: `packages/opencode/src/session/llm.ts`
- **Processor**: `packages/opencode/src/session/processor.ts`
- **Messages**: `packages/opencode/src/session/message-v2.ts`
- **LSP**: `packages/opencode/src/lsp/index.ts`
- **MCP**: `packages/opencode/src/mcp/index.ts`
- **Storage**: `packages/opencode/src/storage/storage.ts`
- **Config**: `packages/opencode/src/config/config.ts`
- **Provider**: `packages/opencode/src/provider/provider.ts`

### Tools

- **Tool definition**: `packages/opencode/src/tool/tool.ts`
- **Edit**: `packages/opencode/src/tool/edit.ts`
- **Batch**: `packages/opencode/src/tool/batch.ts`
- **Grep**: `packages/opencode/src/tool/grep.ts`

### Documentation

- **Style guide**: `AGENTS.md`
- **Contributing**: `CONTRIBUTING.md`
- **This document**: `CODEBASE_STANDARDS.md`

---

**End of Standards Document**