Distillation

Date: Sep 9, 2026

• 🔴 (13:40) The pnpm physical dependency directory /home/byk/Code/opencode-lore-v2/node_modules/.pnpm/@opencode+plugin@0.0.0-beta-19378_@opentelemetry+api-logs@0.214.0_@opentelemetry+resour_adca8235564d91579da6ab6087184da7/node_modules/@opencode contains 6 packages: ai/, client/, plugin/, protocol/, schema/, and util/.
• 🔴 (13:40) The nested physical package /home/byk/Code/opencode-lore-v2/node_modules/.pnpm/@opencode+plugin@0.0.0-beta-19378_@opentelemetry+api-logs@0.214.0_@opentelemetry+resour_adca8235564d91579da6ab6087184da7/node_modules/@opencode/schema contains dist/ and package.json.
• 🔴 (13:41) The nested physical declaration /home/byk/Code/opencode-lore-v2/node_modules/.pnpm/@opencode+plugin@0.0.0-beta-19378_@opentelemetry+api-logs@0.214.0_@opentelemetry+resour_adca8235564d91579da6ab6087184da7/node_modules/@opencode/schema/dist/location.d.ts exists. It exports namespace Location; Ref has branded directory: AbsolutePath and optional branded workspaceID: Workspace.ID; Info has directory, optional workspaceID, and project containing branded id: Project.ID, directory: AbsolutePath, and canonical: AbsolutePath; response<S extends Schema.Top>(data: S) returns a struct with location: Info and data: S.
• 🔴 (13:41) /home/byk/Code/opencode/packages/core/src/plugin/ contains these 10 directly listed TypeScript files: models-dev.ts, internal.ts, variant.ts, skill.ts, provider.ts, promise.ts, host.ts, command.ts, agent.ts, and layer-map.example.ts; provider-specific files under this area inspect model/provider npm package names.
• 🔴 (13:41) /home/byk/Code/opencode/packages/core/src/config/plugin/external.ts defines external-plugin discovery and loading: document entries resolve string/object plugin references relative to the configuration document; directory entries glob {plugin,plugins}/*.{ts,js} with absolute: true, include: "file", dot: true, and symlink: true; discovered files are sorted; absolute paths become pathToFileURL(ref.package).href, package references use (yield* npm.add(ref.package)).entrypoint; modules are dynamically imported and decoded as a default Effect plugin (id + effect) or Promise plugin (id + setup); Promise plugins are converted with PluginPromise.fromPromise(value); options default to {}; individual load failures are suppressed with Effect.ignoreCause.
• 🔴 (13:42) /home/byk/Code/opencode-v2-pilot/packages/core/src/config/plugin/ includes 20 listed files: worktree.ts, websearch.ts, tool-output.ts, source.ts, snapshot.ts, skill.ts, skill-file.ts, shell.ts, reference.ts, provider.ts, policy.ts, mcp.ts, location-watcher.ts, instruction.ts, image.ts, formatter.ts, entry-observer.ts, compaction.ts, command.ts, and agent.ts.
• 🔴 (13:42) /home/byk/Code/opencode-v2-pilot/packages/core/src/plugin/ includes top-level files warming.ts, variant.ts, update.ts, supervisor.ts, source-directory.ts, skill.ts, service.ts, sdk.ts, provider.ts, promise.ts, plan.ts, optimize.ts, module.ts, models-dev.ts, mcp-codemode-exclusion.ts, internal.ts, instance.ts, host.ts, hooks.ts, command.ts, and agent.ts; VCS implementations vcs/hg.ts and vcs/git.ts; web-search implementations websearch/tavily.ts, parallel.ts, mcp.ts, index.ts, firecrawl.ts, and exa.ts; and provider implementations zenmux.ts, xai.ts, vllm.ts, vercel.ts, venice.ts, snowflake-cortex.ts, sdk-factory.ts, sap-ai-core.ts, perplexity.ts, openrouter.ts, opencode.ts, openai.ts, openai-compatible.ts, ollama.ts, nvidia.ts, modal.ts, mistral.ts, lmstudio.ts, llmgateway.ts, kilo.ts, google-vertex.ts, gitlab.ts, github-copilot.ts, gateway.ts, factory.ts, dynamic.ts, digitalocean.ts, configured.ts, cohere.ts, cloudflare-workers-ai.ts, cloudflare-ai-gateway.ts, cerebras.ts, azure.ts, anthropic.ts, amazon-bedrock.ts, and alibaba.ts.
• 🔴 (13:42) The plugin module loader in /home/byk/Code/opencode-v2-pilot/packages/core/src/plugin/module.ts treats local plugins as directories: “local plugins always arrive here as directories.” It resolves an entrypoint and returns LoadError with message Plugin entrypoint not found: ${operation.target} when none is found; loading uses Host.load(entrypoint), and Promise-plugin setup exports are adapted through PluginPromise.fromPromise.
• 🔴 (13:42) /home/byk/Code/opencode-v2-pilot/packages/plugin/src/host.ts defines Target with directory and optional name, and Entrypoints with optional server, tui, and rpc. Host.resolve(target) checks server subpaths in order ["server", ""], TUI ["tui"], and RPC ["rpc"]; named targets resolve package subpaths, while unnamed targets resolve filesystem paths relative to target.directory, with the empty subpath mapped to index.
• 🔴 (13:42) Host.resolve() ignores resolution errors only for ENOENT, ENOTDIR, MODULE_NOT_FOUND, ERR_MODULE_NOT_FOUND, ERR_PACKAGE_PATH_NOT_EXPORTED, and ERR_UNSUPPORTED_DIR_IMPORT; other errors are rethrown. Host.load(entrypoint) calls importModule(entrypoint), while resolution uses resolveModule(specifier, target.directory) from @opencode/util/runtime-import.
• 🔴 (13:42) The plugin package has two API versions, Effect and Promise. In the Effect version, every domain must extend the corresponding Effect API client interface from @opencode/client/effect/api; functions already present on that client interface must not be redefined, and plugin domains add only plugin-context-specific functions.
• 🔴 (13:42) Repository dependency direction is Schema → Core and Protocol, then Core and Protocol → Server. Client runtime code may depend on Schema and Protocol but never Core or Server; sdk composes Client, Core, and Server.
• 🔴 (13:42) After changing the public Protocol or Server HttpApi, run bun run generate from packages/client; generated client files must not be edited directly.
• 🔴 (13:42) Current implementation changes belong in packages/core, packages/cli, packages/server, packages/protocol, packages/schema, and related generated client surfaces when required.
• 🔴 (13:42) The repository does not use Changesets; do not add .changeset files, and follow the existing release workflow.
• 🔴 (13:42) The repository’s default branch is v2. New branches and worktrees default to v2, or origin/v2 when local v2 is unavailable; pull requests default to target v2 unless explicitly instructed otherwise. Local main may not exist, so diffs should use v2 or origin/v2.
• 🔴 (13:42) Always run bun typecheck from package directories such as packages/core; never run tsc directly.
• 🔴 (13:42) Never alias imports: do not use forms such as import { foo as bar } from "..." or resolve as pathResolve. Only when two imported type names genuinely collide and no other option exists may an aliased type import such as import type { Plugin as PluginDefinition } from "..." be used as a last resort.
• 🔴 (13:42) Never use type-position import("...") references such as Schema.declare<import("@opencode/plugin/effect/plugin").Plugin["effect"]>; use a normal type import instead.
• 🔴 (13:42) Never use star imports such as import * as Foo from "..." or import type * as Foo from "...". When namespace-style access is needed, import the module’s own exported namespace by name, e.g. import { Project } from "@opencode/core/project" and then use Project.ID.
• 🔴 (13:42) Prefer dynamic imports for heavy modules used only on selected paths, especially startup-sensitive entrypoints. Destructure bindings near the top of the narrowest scope that needs them; avoid inline chains such as await import("./module").then((mod) => mod.value()) and (await import("./module")).value(); keep branch-specific imports inside their branch to preserve lazy loading.
• 🔴 (13:42) Theme tokens must be chosen by semantic role rather than current color. Do not use raw theme.hue values or repurpose unrelated tokens; text.feedback and background.feedback are only for error, warning, success, or informational status feedback; form controls, ordinals, and selection markers use formfield states; actions use action states. If no suitable token exists, extend theme schema, defaults, resolution, and types, and verify built-in light/dark defaults plus custom-theme fallback when changing the public token surface.
• 🔴 (13:42) Keep helpers close to supported code when useful, avoid abstracting simple expressions into many single-use helpers, and extract only concepts with meaningful names such as requireConfig or readMetadata. Helpers should return Effect only when they perform effectful work; synchronous parsing, validation, and option construction remain synchronous.
• 🔴 (13:42) Prefer Effect schema helpers such as Schema.UnknownFromJsonString and Schema.decodeUnknownOption over manually wrapping JSON.parse in Effect.try for untrusted JSON. Comments should explain non-obvious constraints or surprising behavior rather than obvious assignments/control flow.
• 🔴 (13:42) SessionRunner, model resolution, tool registry, permissions, and filesystem state must remain Location-scoped. Omitted Location.workspaceID means implicit-local placement; explicit workspace identity is reserved for future placement semantics.
• 🔴 (13:42) Session terminology convention: one “step” is one logical LLM call, and its durable record covers only the model-visible span. Do not say “provider turn,” and do not use bare “turn” for one call; “turn” is reserved for the future assistant-turn unit spanning all steps from prompt promotion until the session would go idle.
• 🔴 (13:42) Search across /home/byk/Code/opencode-v2-pilot found session request hooks in both /packages/plugin/src/promise/session.ts and /packages/plugin/src/effect/session.ts, with "model.request" and "http.request" declarations; core request processing is concentrated in /packages/core/src/session/model-request.ts, which triggers "session", "model.request" before dispatch and exposes outbound exchanges through "session", "http.request"/response hooks.
• 🔴 (13:42) Tests covering session model/HTTP hooks and related behavior include /home/byk/Code/opencode-v2-pilot/packages/core/test/session-model-request-hooks.test.ts, session-model-request.test.ts, session-native-compaction.test.ts, session-runner.test.ts, session-title.test.ts, session-compaction.test.ts, config/compaction.test.ts, plugin/provider-openai.test.ts, plugin/provider-github-copilot.test.ts, and plugin/provider-azure.test.ts.