Two files, one repository
anomalyco/opencode ships 1 format across 16 indexed files. The question worth asking is whether the second one says anything the first does not.
| Dimension | Shared | Only in A | Only in B | Overlap |
|---|---|---|---|---|
| Sections | 0 | 13 | 1 | 0% |
| Commands | 0 | 3 | 0 | 0% |
| Section tags | 2 | 5 | 1 | 25% |
What each file covers
Sections
0 shared · 13 only in A · 1 only in B- − Branch Names
- − Commits and PR Titles
- − Style Guide
- − General Principles
- − Destructuring
- − Imports
- − Variables
- − Control Flow
- − Complex Logic
- − Schema Definitions (Drizzle)
- − Testing
- − Type Checking
- − V2 Session Core
- + Server Test Guide
Commands
0 shared · 3 only in A · 0 only in B- − bun run generate
- − bun typecheck
- − tsc
Section tags
2 shared · 5 only in A · 1 only in B- − lint-format
- − types
- − git-pr
- − database
- − do-not
- + api
- test
- code-style
Line diff
anomalyco/opencode · AGENTS.md
@@ −1 @@
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
anomalyco/opencode · packages/opencode/test/server/AGENTS.md
@@ +1 @@
1# Server Test Guide
2
3Use these patterns for server and HttpApi middleware tests in this directory.
4
5- Prefer focused middleware tests with tiny fake routes over full API route trees when testing routing, context, proxying, or middleware policy.
6- Use `testEffect(...)` with `NodeHttpServer.layerTest` for the primary in-test server and make relative `HttpClient` requests against it.
7- Use tiny `HttpApiBuilder` probe groups that declare the typed middleware under test and expose context such as `WorkspaceRouteContext`, `InstanceRef`, or `WorkspaceRef`.
8- Declare middleware in the same order as production when testing interactions, for example `InstanceContextMiddleware` followed by `WorkspaceRoutingMiddleware`.
9- For secondary upstream servers, build Effect `NodeHttpServer.layer(...)` into the current test scope with `Layer.build(...)` so the listener stays alive until the test scope exits.
10- Avoid `Bun.serve` when testing Effect HTTP middleware. Keep the test in the Effect HTTP stack unless the production path being tested is Bun-specific.
11- For WebSocket paths, use `Socket.makeWebSocket(...)` from the test client and assert protocol forwarding or frame relay when relevant.
12- Use scoped test layers for flags, database reset, and other global mutable state. Restore flags and reset state in finalizers.
13- Use `tmpdirScoped({ git: true })` plus `Project.use.fromDirectory(dir)` for project-backed requests.
14- If a test needs persisted state without matching runtime state, keep direct database setup inside a narrowly named helper that explains that state.
15- Add comments for non-obvious test topology, especially tests involving both the local test server and a fake upstream server.
16
@@ −1 +1 @@
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.
1+# Server Test Guide
62
7−## Branch Names
3+Use these patterns for server and HttpApi middleware tests in this directory.
84
9−Use 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−
11−Examples: `session-recovery`, `fix-scroll-state`, `regenerate-sdk`.
12−
13−## Commits and PR Titles
14−
15−Use conventional commit-style messages and PR titles: `type(scope): summary`.
16−
17−Valid 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−
19−Examples: `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−
35−Reduce total variable count by inlining when a value is only used once.
36−
37−```ts
38−// Good
39−const journal = await Bun.file(path.join(dir, "journal.json")).json()
40−
41−// Bad
42−const journalPath = path.join(dir, "journal.json")
43−const journal = await Bun.file(journalPath).json()
44−```
45−
46−### Destructuring
47−
48−Avoid unnecessary destructuring. Use dot notation to preserve context.
49−
50−```ts
51−// Good
52−obj.a
53−obj.b
54−
55−// Bad
56−const { 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−
68−Prefer `const` over `let`. Use ternaries or early returns instead of reassignment.
69−
70−```ts
71−// Good
72−const foo = condition ? 1 : 2
73−
74−// Bad
75−let foo
76−if (condition) foo = 1
77−else foo = 2
78−```
79−
80−### Control Flow
81−
82−Avoid `else` statements. Prefer early returns.
83−
84−```ts
85−// Good
86−function foo() {
87− if (condition) return 1
88− return 2
89−}
90−
91−// Bad
92−function foo() {
93− if (condition) return 1
94− else return 2
95−}
96−```
97−
98−### Complex Logic
99−
100−When 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
104−export function loadThing(input: unknown) {
105− const config = requireConfig(input)
106− const metadata = readMetadata(input)
107− return createThing({ config, metadata })
108−}
109−
110−function 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−
123−Use snake_case for field names so column names don't need to be redefined as strings.
124−
125−```ts
126−// Good
127−const table = sqliteTable("session", {
128− id: text().primaryKey(),
129− project_id: text().notNull(),
130− created_at: integer().notNull(),
131−})
132−
133−// Bad
134−const 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.
5+- Prefer focused middleware tests with tiny fake routes over full API route trees when testing routing, context, proxying, or middleware policy.
6+- Use `testEffect(...)` with `NodeHttpServer.layerTest` for the primary in-test server and make relative `HttpClient` requests against it.
7+- Use tiny `HttpApiBuilder` probe groups that declare the typed middleware under test and expose context such as `WorkspaceRouteContext`, `InstanceRef`, or `WorkspaceRef`.
8+- Declare middleware in the same order as production when testing interactions, for example `InstanceContextMiddleware` followed by `WorkspaceRoutingMiddleware`.
9+- For secondary upstream servers, build Effect `NodeHttpServer.layer(...)` into the current test scope with `Layer.build(...)` so the listener stays alive until the test scope exits.
10+- Avoid `Bun.serve` when testing Effect HTTP middleware. Keep the test in the Effect HTTP stack unless the production path being tested is Bun-specific.
11+- For WebSocket paths, use `Socket.makeWebSocket(...)` from the test client and assert protocol forwarding or frame relay when relevant.
12+- Use scoped test layers for flags, database reset, and other global mutable state. Restore flags and reset state in finalizers.
13+- Use `tmpdirScoped({ git: true })` plus `Project.use.fromDirectory(dir)` for project-backed requests.
14+- If a test needs persisted state without matching runtime state, keep direct database setup inside a narrowly named helper that explains that state.
15+- Add comments for non-obvious test topology, especially tests involving both the local test server and a fake upstream server.
16216
