AGENTS.md

1- To regenerate the legacy JavaScript SDK, run `./packages/sdk/js/script/build.ts`.
2- After changing the public Protocol or Server `HttpApi`, run `bun run generate` from `packages/client`. Do not edit `src/generated` or `src/generated-effect` directly.
3- Keep runtime dependencies directed from Schema to Core and Protocol, then from Core and Protocol to Server. Client runtime code may depend on Schema and Protocol but never Core or Server; `sdk-next` composes Client, Core, and Server.
4- The default branch in this repo is `dev`.
5- Local `main` ref may not exist; use `dev` or `origin/dev` for diffs.
6 
7## Branch Names
8 
9Use a short branch name of at most three words, separated by hyphens. Do not use slashes or type prefixes such as `feat/` or `fix/`.
10 
11Examples: `session-recovery`, `fix-scroll-state`, `regenerate-sdk`.
12 
13## Commits and PR Titles
14 
15Use conventional commit-style messages and PR titles: `type(scope): summary`.
16 
17Valid types are `feat`, `fix`, `docs`, `chore`, `refactor`, and `test`. Scopes are optional; use the affected package or area when helpful, e.g. `core`, `opencode`, `tui`, `app`, `desktop`, `sdk`, or `plugin`.
18 
19Examples: `fix(tui): simplify thinking toggle styling`, `docs: update contributing guide`, `chore(sdk): regenerate types`.
20 
21## Style Guide
22 
23### General Principles
24 
25- Keep things in one function unless composable or reusable
26- Do not extract single-use helpers preemptively. Inline the logic at the call site unless the helper is reused, hides a genuinely complex boundary, or has a clear independent name that improves the caller.
27- Avoid `try`/`catch` where possible
28- Avoid using the `any` type
29- Use Bun APIs when possible, like `Bun.file()`
30- Rely on type inference when possible; avoid explicit type annotations or interfaces unless necessary for exports or clarity
31- Prefer functional array methods (flatMap, filter, map) over for loops; use type guards on filter to maintain type inference downstream
32- In `src/config`, follow the existing self-export pattern at the top of the file (for example `export * as ConfigAgent from "./agent"`) when adding a new config module.
33- In Effect generators, bind services to named variables before calling methods. Do not use nested service yields such as `yield* (yield* Foo.Service).bar()`.
34 
35Reduce total variable count by inlining when a value is only used once.
36 
37```ts
38// Good
39const journal = await Bun.file(path.join(dir, "journal.json")).json()
40 
41// Bad
42const journalPath = path.join(dir, "journal.json")
43const journal = await Bun.file(journalPath).json()
44```
45 
46### Destructuring
47 
48Avoid unnecessary destructuring. Use dot notation to preserve context.
49 
50```ts
51// Good
52obj.a
53obj.b
54 
55// Bad
56const { a, b } = obj
57```
58 
59### Imports
60 
61- Never alias imports. Do not use `import { foo as bar } from "..."` or renamed imports like `resolve as pathResolve`.
62- Never use star imports. Do not use `import * as Foo from "..."` or `import type * as Foo from "..."`.
63- If a namespace-style value is needed, import the module's own exported namespace by name, for example `import { Project } from "@opencode-ai/core/project"`, then reference `Project.ID`.
64- Prefer dynamic imports for heavy modules that are only needed in selected code paths, especially in startup-sensitive entrypoints. Destructure dynamic import bindings near the top of the narrowest scope that needs them so they read like normal imports. Avoid inline chains such as `await import("./module").then((mod) => mod.value())` or `(await import("./module")).value()`. Keep branch-specific imports inside the branch that needs them to preserve lazy loading.
65 
66### Variables
67 
68Prefer `const` over `let`. Use ternaries or early returns instead of reassignment.
69 
70```ts
71// Good
72const foo = condition ? 1 : 2
73 
74// Bad
75let foo
76if (condition) foo = 1
77else foo = 2
78```
79 
80### Control Flow
81 
82Avoid `else` statements. Prefer early returns.
83 
84```ts
85// Good
86function foo() {
87  if (condition) return 1
88  return 2
89}
90 
91// Bad
92function foo() {
93  if (condition) return 1
94  else return 2
95}
96```
97 
98### Complex Logic
99 
100When a function has several validation branches or supporting details, make the main function read as the happy path and move supporting details into small helpers below it.
101 
102```ts
103// Good
104export function loadThing(input: unknown) {
105  const config = requireConfig(input)
106  const metadata = readMetadata(input)
107  return createThing({ config, metadata })
108}
109 
110function requireConfig(input: unknown) {
111  ...
112}
113```
114 
115- Keep helpers close to the code they support, below the main export when that improves readability.
116- Do not over-abstract simple expressions into many single-use helpers; extract only when it names a real concept like `requireConfig` or `readMetadata`.
117- Do not return `Effect` from helpers unless they actually perform effectful work. Synchronous parsing, validation, and option building should stay synchronous.
118- Prefer Effect schema helpers such as `Schema.UnknownFromJsonString` and `Schema.decodeUnknownOption` over manual `JSON.parse` wrapped in `Effect.try` when parsing untrusted JSON strings.
119- Add comments for non-obvious constraints and surprising behavior, not for obvious assignments or control flow.
120 
121### Schema Definitions (Drizzle)
122 
123Use snake_case for field names so column names don't need to be redefined as strings.
124 
125```ts
126// Good
127const table = sqliteTable("session", {
128  id: text().primaryKey(),
129  project_id: text().notNull(),
130  created_at: integer().notNull(),
131})
132 
133// Bad
134const table = sqliteTable("session", {
135  id: text("id").primaryKey(),
136  projectID: text("project_id").notNull(),
137  createdAt: integer("created_at").notNull(),
138})
139```
140 
141## Testing
142 
143- Avoid mocks as much as possible, you shouldn't be using globalThis.\* at all unless it's the only option.
144- Test actual implementation, do not duplicate logic into tests
145- Tests cannot run from repo root (guard: `do-not-run-tests-from-root`); run from package dirs like `packages/opencode`.
146 
147## Type Checking
148 
149- Always run `bun typecheck` from package directories (e.g., `packages/opencode`), never `tsc` directly.
150 
151## V2 Session Core
152 
153- Keep durable prompt admission separate from model execution. `SessionV2.prompt(...)` admits one durable `session_input` row before scheduling advisory `SessionExecution.wake(sessionID)` unless `resume: false` requests admit-only behavior. The serialized runner promotes admitted inputs into visible user messages at safe boundaries.
154- Reusing a Session ID adopts the existing Session. Reusing a prompt message ID reconciles an exact retry only when Session, prompt, and delivery mode match; conflicting reuse fails. Historical projected prompts lazily synthesize promoted inbox records during exact retry.
155- Keep `SessionExecution` process-global and Session-ID based. Its local implementation owns the process-local Session coordinator and discovers placement through `SessionStore` plus `LocationServiceMap.get(session.location)` only when a drain starts; no layer should take a Session ID. V2 interruption targets the active process-local ownership chain for that Session; idle or missing interruption is a no-op.
156- Keep `SessionRunner`, model resolution, tool registry, permissions, and filesystem Location-scoped. Omitted `Location.workspaceID` means implicit-local placement; explicit workspace identity remains reserved for future placement semantics.
157- Preserve one explicit `llm.stream(request)` call per provider turn and reload projected history before durable continuation. Do not bridge through legacy `SessionPrompt.loop(...)` or delegate orchestration to an in-memory tool loop.
158- Keep local Session drains process-local until clustering is implemented. `SessionRunCoordinator` joins explicit same-Session resumes, coalesces prompt wakeups, and allows different Sessions to run concurrently. Advisory wakes drain eligible durable inbox rows only; post-crash continuation recovery requires a separate explicit design before it may retry provider work. A drain has no durable identity or transcript boundary.
159- Keep delivery vocabulary explicit. Prompts steer by default and promote at the next safe provider-turn boundary while the current drain requires continuation. An explicit `queue` input remains pending until the Session would otherwise become idle; promote one queued input at that boundary, then reevaluate continuation before promoting another. Promoting any new user input resets the selected agent's provider-turn allowance; a batch of steers resets it once.
160- Keep EventV2 replay owner claims separate from clustered Session execution ownership.
161- Keep the System Context algebra, registry, and built-ins in `src/system-context`; keep Context Source producers with their observed domains, and keep Session History selection plus Context Epoch persistence Session-owned.
162