Skip to content

refactor(core): load Console instructions and skills from their own endpoints #62507

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
adamdotdevin merged 1 commit into from
Nov 7, 2026
Merged

refactor(core): load Console instructions and skills from their own endpoints #62507

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions packages/core/src/config.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -105,6 +105,8 @@ export const testLayer = (
emitChange: (update) => PubSub.publish(updates, update).pipe(Effect.asVoid),
integration: (integrationID, document) =>
Ref.update(integrations, (current) => {
// Like config, keeps the document it holds when handed a deep-equal one.
if (isDeepStrictEqual(current.get(integrationID), document)) return current
const next = new Map(current)
next.delete(integrationID)
return document ? next.set(integrationID, document) : next
Expand Down
83 changes: 56 additions & 27 deletions packages/core/src/plugin/provider/opencode.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,3 +1,4 @@
import { isDeepStrictEqual } from "node:util"
import { Duration, Effect, Equal, FiberHandle, Option, Schema, Scope, Semaphore, Stream } from "effect"
import type { IntegrationOAuthMethodRegistration } from "@opencode/plugin/effect/integration"
import { define } from "@opencode/plugin/effect/plugin"
Expand Down Expand Up @@ -58,21 +59,18 @@ const SsoRequired = Schema.Struct({
const InvalidGrant = Schema.Struct({ error: Schema.Literal("invalid_grant") })
// Console's 401 when the session behind the access token was revoked or expired.
const Unauthorized = Schema.Struct({ _tag: Schema.Literal("Unauthorized") })
// The workspace Library: instructions arrive whole, skills as versions whose files download separately.
const Library = Schema.Struct({
instructions: Schema.Array(Schema.Struct({ id: Schema.String, content: Schema.String })).pipe(Schema.optional),
skills: Schema.Array(Schema.Struct({ slug: Schema.String, version: Schema.String })).pipe(Schema.optional),
// The workspace's instructions arrive whole, its skills as versions whose files download separately.
const ConsoleInstructions = Schema.Struct({
instructions: Schema.Array(Schema.Struct({ id: Schema.String, content: Schema.String })),
})
// `library` decodes where it's used, so a malformed one can't fail the config and drop its policies.
const ConsoleConfig = Schema.Struct({
...ConfigIntegration.Remote.fields,
library: Schema.Unknown.pipe(Schema.optional),
const ConsoleSkills = Schema.Struct({
skills: Schema.Array(Schema.Struct({ slug: Schema.String, version: Schema.String })),
})
const SkillBundle = Schema.Struct({
slug: Schema.String,
files: Schema.Array(Schema.Struct({ path: Schema.String, content: Schema.String })),
})
type LibrarySkill = { readonly skill: Skill.Info; readonly files: Record<string, string> }
type ConsoleSkill = { readonly skill: Skill.Info; readonly files: Record<string, string> }
const signedOutMessage = "Reconnect OpenCode Console to continue"
const ssoMessage = (organization: string | undefined) =>
`Sign in with SSO again to use ${organization ?? "your OpenCode Console organization"}`
Expand Down Expand Up @@ -197,13 +195,13 @@ export const OpencodePlugin = define<
type ActiveConnection = Effect.Success<ReturnType<typeof ctx.integration.connection.active>>
let snapshot: {
// The Console's regular OpenCode config, merged as an integration config layer.
remote: typeof ConsoleConfig.Type | undefined
remote: Effect.Success<ReturnType<typeof fetchConfig>>
connection: ActiveConnection
organization: string | undefined
} = { remote: undefined, connection: undefined, organization: undefined }
let instructions: InstructionDiscovery.File[] = []
// Tagged with the account and workspace they were downloaded for, so a switch hides them right away.
let librarySkills: { owner: string; items: LibrarySkill[] } = { owner: "", items: [] }
let consoleSkills: { owner: string; items: ConsoleSkill[] } = { owner: "", items: [] }
const owner = (from: typeof snapshot) =>
`${IntegrationConnection.key(from.connection) ?? ""}:${from.organization ?? ""}`
// A newer config's skill download replaces one still in flight.
Expand Down Expand Up @@ -290,31 +288,33 @@ export const OpencodePlugin = define<
? { ...next.connection, id: Credential.ID.make(next.connection.id) }
: next.connection,
organization: next.organization,
// `make` keeps only the standard config keys, so `library` stays here.
// `make` keeps only the standard config keys, so instructions and skills stay here.
info: next.remote,
})
yield* integrate(document)
// Managed `integration.use: deny` makes config layer a policies-only copy, which withholds the Library too.
yield* syncLibrary(next, document !== undefined && (!config.integration || integrated === document))
// Managed `integration.use: deny` makes config layer a policies-only copy, which withholds instructions and
// skills too. Config keeps the document it holds when handed a deep-equal one, so compare by content.
yield* syncInstructionsAndSkills(
next,
document !== undefined && (!config.integration || isDeepStrictEqual(integrated, document)),
)
})
const syncLibrary = (next: typeof snapshot, allowed: boolean) => {
const library = allowed
? Option.getOrUndefined(Schema.decodeUnknownOption(Library)(next.remote?.library))
: undefined
instructions = (library?.instructions ?? []).map(
const syncInstructionsAndSkills = (next: typeof snapshot, allowed: boolean) => {
const remote = allowed ? next.remote : undefined
instructions = (remote?.instructions ?? []).map(
(item) =>
new InstructionDiscovery.File({ path: `OpenCode Console instruction ${item.id}`, content: item.content }),
)
if (!allowed) librarySkills = { owner: "", items: [] }
if (!allowed) consoleSkills = { owner: "", items: [] }
// Skills download in the background, so startup and config changes never wait on them. The current ones stay
// until the download replaces them.
return FiberHandle.run(
skillDownload,
loadSkills(next.connection, library?.skills ?? []).pipe(
loadSkills(next.connection, remote?.skills ?? []).pipe(
Effect.flatMap((loaded) => {
// A failed load keeps the skills already shown.
if (!loaded) return Effect.void
librarySkills = { owner: owner(next), items: loaded }
consoleSkills = { owner: owner(next), items: loaded }
return skills.reload()
}),
),
Expand Down Expand Up @@ -450,8 +450,8 @@ export const OpencodePlugin = define<
})
yield* discovery.transform((editor) => instructions.forEach((file) => editor.add(file)))
yield* skills.transform((editor) => {
if (librarySkills.owner !== owner(snapshot)) return
librarySkills.items.forEach((item) => editor.add(item.skill, item.files))
if (consoleSkills.owner !== owner(snapshot)) return
consoleSkills.items.forEach((item) => editor.add(item.skill, item.files))
})

const apply = Effect.fn("OpencodePlugin.apply")(function* (next: typeof snapshot) {
Expand Down Expand Up @@ -544,7 +544,36 @@ function fetchConfig(http: HttpClient.HttpClient, value: Credential.Key | Creden
})
}
const body = yield* HttpClientResponse.filterStatusOk(response).pipe(Effect.flatMap((ok) => ok.json))
return yield* Schema.decodeUnknownEffect(ConsoleConfig)(body)
const remote = yield* Schema.decodeUnknownEffect(ConfigIntegration.Remote)(body)
// Instructions and skills have their own endpoints. A 404 (none in the workspace) or a 403 other than SSO
// (the sign-in may not read them) counts as empty; any other error fails the load, which keeps the last lists.
const list = <A>(path: string, schema: Schema.Decoder<A>) =>
HttpClient.withScope(http)
.execute(
HttpClientRequest.get(`${ConsoleAccess.server(value)}${path}`).pipe(
HttpClientRequest.acceptJson,
HttpClientRequest.setHeaders(ConsoleAccess.headers(value)),
),
)
.pipe(
Effect.flatMap((response) =>
Effect.gen(function* () {
if (response.status === 404) return undefined
if (
response.status === 403 &&
Option.isNone(yield* HttpClientResponse.schemaBodyJson(SsoRequired)(response).pipe(Effect.option))
)
return undefined
const ok = yield* HttpClientResponse.filterStatusOk(response)

@opencodejr opencodejr Bot Nov 7, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

A failure here now fails the whole fetchConfig, so the Console config's health depends on the list endpoints:

  • At startup, with no snapshot yet, a 429 or 5xx on /api/v2/instructions or /api/v2/skills leaves remote undefined, so the org's policies aren't applied. In a quick check, config returned 200 with a tool.use deny policy and the lists returned 503: consolePolicies stayed [] until the lists recovered.
  • Later on, the same outage freezes config and policy changes at the last good version.

Could the lists fail on their own, without taking the config with them? For example, their own SharedCache entries as in the first version, or fetchConfig returning the config with "lists unavailable" so load keeps the previous lists.

return yield* HttpClientResponse.schemaBodyJson(schema)(ok).pipe(
Effect.orElseSucceed(() => undefined),
)
}),
),
)
const instructions = yield* list("/api/v2/instructions", ConsoleInstructions)
const skills = yield* list("/api/v2/skills", ConsoleSkills)
return { ...remote, instructions: instructions?.instructions ?? [], skills: skills?.skills ?? [] }
}),
),
Effect.scoped,
Expand Down Expand Up @@ -663,7 +692,7 @@ function downloadSkill(http: HttpClient.HttpClient, server: string, slug: string
if (!SkillDiscovery.isSafeSegment(slug)) return yield* Effect.fail(new Error(`unsafe skill slug: ${slug}`))
const bundle = yield* follow(
http,
HttpClientRequest.get(`${server}/api/v2/library/skills/${encodeURIComponent(slug)}`).pipe(
HttpClientRequest.get(`${server}/api/v2/skills/${encodeURIComponent(slug)}`).pipe(
HttpClientRequest.acceptJson,
HttpClientRequest.setHeaders(headers),
),
Expand All @@ -680,7 +709,7 @@ function downloadSkill(http: HttpClient.HttpClient, server: string, slug: string
files: Object.fromEntries(
bundle.files.filter((file) => file.path !== "SKILL.md").map((file) => [file.path, file.content]),
),
} satisfies LibrarySkill
} satisfies ConsoleSkill
})
}

Expand Down
96 changes: 82 additions & 14 deletions packages/core/test/plugin/provider-opencode.test.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,6 +16,7 @@ import { ConfigPolicyPlugin } from "@opencode/core/config/plugin/policy"
import { ConfigProviderPlugin } from "@opencode/core/config/plugin/provider"
import { ConfigWebSearchPlugin } from "@opencode/core/config/plugin/websearch"
import { Credential } from "@opencode/core/credential"
import { InstructionDiscovery } from "@opencode/core/instruction-discovery"
import { Integration } from "@opencode/core/integration"
import { Model } from "@opencode/core/model"
import { ModelResolver } from "@opencode/core/model-resolver"
Expand Down Expand Up @@ -358,9 +359,13 @@ describe("OpencodePlugin", () => {
label: initial.label,
}),
).toEqual(stored.value)
expect(requests).toEqual(["/auth/device/token", "/api/v2/config"])
// The refresh and the config fetch both say which OpenCode is asking.
expect(agents).toEqual(["opencode/beta/1.2.3/test", "opencode/beta/1.2.3/test"])
expect(requests).toEqual([
"/auth/device/token",
"/api/v2/config",
...(scenario.orgID === "org-missing" ? [] : ["/api/v2/instructions", "/api/v2/skills"]),
])
// The refresh and every Console fetch say which OpenCode is asking.
expect(agents).toEqual(requests.map(() => "opencode/beta/1.2.3/test"))
}).pipe(Effect.provideService(App.Metadata, App.make({ name: "test", version: "1.2.3", channel: "beta" }))),
({ server }) => Effect.promise(() => server.stop(true)),
),
Expand Down Expand Up @@ -410,6 +415,7 @@ describe("OpencodePlugin", () => {
server: Bun.serve({
port: 0,
fetch: (request) => {
if (new URL(request.url).pathname !== "/api/v2/config") return new Response(null, { status: 404 })
authorization.push(request.headers.get("authorization"))
requests.push(`${request.method} ${new URL(request.url).pathname}`)
const origin = new URL(request.url).origin
Expand Down Expand Up @@ -695,7 +701,8 @@ describe("OpencodePlugin", () => {
const state = { advertised: false, failing: false, requests: 0 }
const server = Bun.serve({
port: 0,
fetch: () => {
fetch: (request) => {
if (new URL(request.url).pathname !== "/api/v2/config") return new Response(null, { status: 404 })
state.requests++
if (state.failing) return new Response("Unavailable", { status: 502 })
return Response.json({
Expand Down Expand Up @@ -896,7 +903,8 @@ describe("OpencodePlugin", () => {
const state = { sso: false, requests: 0 }
const server = Bun.serve({
port: 0,
fetch: () => {
fetch: (request) => {
if (new URL(request.url).pathname !== "/api/v2/config") return new Response(null, { status: 404 })
state.requests++
if (state.sso)
return Response.json(
Expand Down Expand Up @@ -1191,6 +1199,7 @@ describe("OpencodePlugin", () => {
port: 0,
fetch: async (request) => {
const path = new URL(request.url).pathname
if (path === "/api/v2/instructions" || path === "/api/v2/skills") return new Response(null, { status: 404 })
const body = request.method === "POST" ? await request.json() : undefined
requests.push({
method: request.method,
Expand Down Expand Up @@ -1385,6 +1394,8 @@ describe("OpencodePlugin", () => {
)
expect(requests).toEqual([
"https://opencode.ai/console/api/v2/config",
"https://opencode.ai/console/api/v2/instructions",
"https://opencode.ai/console/api/v2/skills",
"https://opencode.ai/console/api/websearch",
])
}),
Expand Down Expand Up @@ -1525,6 +1536,7 @@ describe("OpencodePlugin", () => {
if (url.pathname === "/api/v2/config") {
return Response.json({ providers: {}, websearch: { provider: "opencode" } })
}
if (url.pathname.startsWith("/api/v2/")) return new Response(null, { status: 404 })
return Response.redirect(`${url.origin}/loop`, 302)
},
})
Expand Down Expand Up @@ -1568,10 +1580,9 @@ describe("OpencodePlugin", () => {
authorization: request.headers.get("authorization"),
orgID: request.headers.get("x-org-id"),
})
if (url.pathname === "/api/v2/config") {
return Response.json({ providers: {}, library: { skills: [{ slug: "deploy", version: "1" }] } })
}
if (url.pathname === "/api/v2/library/skills/deploy") {
if (url.pathname === "/api/v2/config") return Response.json({ providers: {} })
if (url.pathname === "/api/v2/skills") return Response.json({ skills: [{ slug: "deploy", version: "1" }] })
if (url.pathname === "/api/v2/skills/deploy") {
// Skill archives come from presigned storage on its own host, where the signature covers the encoding.
const target = new URL("/archive/deploy.json?expires=1&sig=a%20b~c", url)
target.hostname = "127.0.0.1"
Expand All @@ -1598,7 +1609,7 @@ describe("OpencodePlugin", () => {

yield* eventually(skills.list(), (list) => list.some((skill) => skill.id === Skill.ID.make("deploy")))
expect(downloads).toContainEqual({
path: "/api/v2/library/skills/deploy",
path: "/api/v2/skills/deploy",
search: "",
authorization: "Bearer secret",
orgID: "org_test",
Expand All @@ -1614,6 +1625,63 @@ describe("OpencodePlugin", () => {
),
)

it.effect("keeps Console instructions and skills through an edit or a Console error, and clears them on 404", () =>
Effect.gen(function* () {
const credentials = yield* Credential.Service
const discovery = yield* InstructionDiscovery.Service
const skills = yield* Skill.Service
const state = { instruction: "Use tabs.", lists: 200 }
const server = {
fetch: (request: Request) => {
const path = new URL(request.url).pathname
if (path === "/api/v2/config") return Response.json({ providers: {} })
if ((path === "/api/v2/instructions" || path === "/api/v2/skills") && state.lists !== 200)
return new Response(null, { status: state.lists })
if (path === "/api/v2/instructions")
return Response.json({ instructions: [{ id: "style", content: state.instruction }] })
if (path === "/api/v2/skills") return Response.json({ skills: [{ slug: "deploy", version: "1" }] })
if (path === "/api/v2/skills/deploy") return Response.json(skillBundle)
return new Response(null, { status: 404 })
},
}
const loaded = Effect.all([discovery.list(), skills.get(Skill.ID.make("deploy"))]).pipe(
Effect.map(([files, skill]) => ({
instructions: Array.isArray(files)
? files.filter((file) => file.path.startsWith("OpenCode Console")).map((file) => file.content)
: [],
skill: skill?.description,
})),
)
yield* credentials.create({
integrationID: Integration.ID.make("opencode"),
value: Credential.Key.make({ type: "key", key: "secret", metadata: { server: "https://console.test" } }),
})
yield* addPlugin().pipe(inProcess(server))
yield* drain
expect(yield* loaded).toEqual({ instructions: ["Use tabs."], skill: "Deploys the service." })

// The config is unchanged, so config keeps the Console document it already holds.
state.instruction = "Use spaces."
yield* TestClock.adjust("1 minute")
yield* drain
expect(yield* loaded).toEqual({ instructions: ["Use spaces."], skill: "Deploys the service." })

// A Console error keeps both, through the retries.
state.lists = 503
yield* TestClock.adjust("1 minute")
yield* drain
yield* TestClock.adjust("10 seconds")
yield* drain
expect(yield* loaded).toEqual({ instructions: ["Use spaces."], skill: "Deploys the service." })

// A 404 means the workspace has none.
state.lists = 404
yield* TestClock.adjust("1 minute")
yield* drain
expect(yield* loaded).toEqual({ instructions: [], skill: undefined })
}),
)

it.live("keeps credentials on a same-origin skill redirect", () =>
Effect.acquireUseRelease(
Effect.sync(() => {
Expand All @@ -1623,10 +1691,9 @@ describe("OpencodePlugin", () => {
fetch: (request) => {
const url = new URL(request.url)
downloads.push({ path: url.pathname, authorization: request.headers.get("authorization") })
if (url.pathname === "/api/v2/config") {
return Response.json({ providers: {}, library: { skills: [{ slug: "deploy", version: "1" }] } })
}
if (url.pathname === "/api/v2/library/skills/deploy")
if (url.pathname === "/api/v2/config") return Response.json({ providers: {} })
if (url.pathname === "/api/v2/skills") return Response.json({ skills: [{ slug: "deploy", version: "1" }] })
if (url.pathname === "/api/v2/skills/deploy")
return Response.redirect(`${url.origin}/assets/deploy.json`, 302)
return Response.json(skillBundle)
},
Expand Down Expand Up @@ -1668,6 +1735,7 @@ describe("OpencodePlugin", () => {
websearch: { provider: "opencode" },
})
}
if (url.pathname.startsWith("/api/v2/")) return new Response(null, { status: 404 })
return new Response(
new ReadableStream({
start(controller) {
Expand Down
Loading