Distillation

Date: Sep 9, 2026

• 🔴 (10:29) /home/byk/Code/opencode/packages/plugin/src/v2/effect/README.md states V2 plugin setup registers hooks imperatively and does not return a hook object; plugin configuration is available as ctx.options.
• 🔴 (10:29) V2 Effect plugin registrations are owned by the plugin scope: closing the scope removes them automatically, and dispose can remove a registration early.
• 🔴 (10:29) Transform hooks rebuild their stateful domain when registered or disposed. Each rebuild starts from fresh domain state and runs every active transform in registration order.
• 🔴 (10:29) Available V2 Effect transform hooks are ctx.agent.transform, ctx.catalog.transform, ctx.command.transform, ctx.integration.transform, ctx.reference.transform, and ctx.skill.transform.
• 🔴 (10:29) V2 runtime hooks intercept live operations instead of rebuilding state. ctx.aisdk.sdk may dynamically import an AI SDK package and assign event.sdk; ctx.aisdk.language may assign event.language. Hooks execute sequentially in registration order, and later hooks observe earlier mutations.
• 🔴 (10:29) Reload is domain-wide rather than registration-specific. ctx.catalog.reload() reruns every active catalog transform and publishes the rebuilt catalog. Available operations are ctx.agent.reload(), ctx.catalog.reload(), ctx.command.reload(), ctx.integration.reload(), ctx.reference.reload(), and ctx.skill.reload().
• 🔴 (10:29) /home/byk/Code/opencode-lore/packages/opencode/src/internal.ts intentionally keeps helpers outside the plugin entry module ./index.ts. OpenCode’s legacy loader treats every exported function as a plugin instance and invokes it; exporting applyLoreProviderConfig from the entry module caused its undefined return value to enter the hooks array and crash dispatch with undefined is not an object (evaluating 'A.event').
• 🔴 (10:29) isLoopbackUrl(value) in /home/byk/Code/opencode-lore/packages/opencode/src/internal.ts recognizes localhost, localhost., ::1, and IPv4 addresses matching /^127(?:\.\d{1,3}){3}$/; malformed URLs return false.
• 🔴 (10:29) gatewayAccessHeadersForRemote(gatewayBase, env = process.env) strips trailing slashes from LORE_REMOTE_URL and gatewayBase, and returns { [GATEWAY_AUTH_HEADER]: LORE_GATEWAY_AUTH_TOKEN } only when the normalized URLs match and the token exists; otherwise it returns {}.
• 🔴 (10:29) shouldForwardUpstreamExtraHeader(name) rejects case-insensitive headers beginning with x-lore- and the exact names x-api-key, x-goog-api-key, and authorization; provider and Lore credentials are applied by the gateway, never this hop.
• 🔴 (10:29) probeLoopback(url, signal) uses node:http or node:https according to the parsed protocol, sends GET with the supplied AbortSignal, drains the response via response.resume(), and considers only HTTP status codes from 200 through 299 successful.
• 🔴 (10:29) applyLoreProviderConfig(cfg, gatewayBase) pins every configured OpenCode provider’s options.baseURL to ${gatewayBase}/v1; it returns immediately when gatewayBase is empty and deep-merges each provider so existing keys, custom headers, model overrides, and other options are preserved.
• 🔴 (10:29) OpenCode’s resolveSDK() always passes options.baseURL to the @ai-sdk factory. Therefore @ai-sdk’s loadOptionalSetting() does not consult an environment variable unless the factory receives an undefined baseURL.
• 🔴 (10:29) Without provider pinning, OpenCode can derive the Anthropic base URL from OPENAI_BASE_URL by stripping /v1, causing requests to reach http://host/messages; the Lore gateway routes only /v1/messages, and its fetch interceptor skips 127.0.0.1 to avoid loops, so the bare /messages request returns 404.
• 🔴 (10:29) Other @ai-sdk providers—including Google, Mistral, Groq, Cohere, xAI, Perplexity, Together AI, Vercel, Alibaba, DeepInfra, Gateway, OpenRouter, and Cerebras—have no baseURL environment variable, making iteration over cfg.provider the universal configuration mechanism.
• 🔴 (10:29) applyLoreProviderConfig forces headerTimeout: false for provider IDs "openai" and "openai-codex" because Lore context preparation can exceed OpenCode Codex’s 10-second header deadline; OpenCode installs its default before this hook runs, so Lore overrides rather than preserves it, while the gateway owns the foreground request deadline.
• 🔴 (10:29) If no openai provider exists, applyLoreProviderConfig creates pinned.openai = { options: { baseURL: baseUrl, headerTimeout: false } }; it finishes with cfg.provider = { ...existingProvider, ...pinned }.
• 🔴 (10:29) applyLoreProviderConfig is exported for direct unit testing so merge logic can be verified without launching a gateway; the surrounding LorePlugin skips gateway startup when NODE_ENV=test.
• 🔴 (10:29) probeGateway(baseURL, timeoutMs = 1500) checks ${baseURL}/health, uses probeLoopback for loopback URLs and fetch(...).ok otherwise, aborts after 1500 ms by default, returns false on every caught failure, and always clears its timeout.
• 🔴 (10:29) surfaceGatewayUnavailable(client, message) calls log.error(message) for the file and Sentry sinks. In embedded/TUI mode, log.silenceStderr() makes stderr invisible to users, so the function uses an OpenCode showToast request as the user-visible, TUI-safe notification channel.
• 🔴 (10:29) The showToast path never writes a raw byte to the terminal; it posts to the OpenCode server over HTTP and renders inside the TUI render loop, avoiding the screen corruption caused by the replaced process.stderr.write.
• 🔴 (10:29) surfaceGatewayUnavailable is fire-and-forget and must swallow every failure: a missing or headless TUI, or an older server lacking /tui/show-toast, must not convert a degraded-but-running session into a crash.
• 🔴 (10:29) A repository search found 22 references involving V2 Effect hook types. Hooks is defined in /home/byk/Code/opencode/packages/plugin/src/v2/effect/registration.ts; it is used by SkillHooks in skill.ts, ReferenceHooks in reference.ts, IntegrationHooks in integration.ts, CommandHooks in command.ts, CatalogHooks in catalog.ts, AISDKHooks in aisdk.ts, and AgentHooks in agent.ts. context.ts imports AgentHooks, AISDKHooks, CatalogHooks, CommandHooks, IntegrationHooks, ReferenceHooks, and SkillHooks.
• 🔴 (10:29) /home/byk/Code/opencode/packages/plugin/src/v2/effect/aisdk.ts defines AISDKHooks = Hooks<{ sdk: ...; language: ... }> and imports LanguageModelV3 from @ai-sdk/provider, ModelV2Info from @opencode-ai/sdk/v2/types, and Hooks from ./registration.js.
• 🔴 (10:29) The AISDKHooks.sdk event has readonly model: ModelV2Info, readonly package: string, readonly options: Record<string, any>, and mutable optional sdk?: any.
• 🔴 (10:29) The AISDKHooks.language event has readonly model: ModelV2Info, readonly sdk: any, readonly options: Record<string, any>, and mutable optional language?: LanguageModelV3.