Skip to content

Commit 21b52c2

Browse files
feat(core): make runtime composition inspectable (#24)
* feat(core): report runtime invariant results per owner RuntimeInvariant.run returned void, so a passing check was silent and a failing one lost the owner. It now runs every registered check, records one typed result per owner, and still dies afterwards so a broken invariant fails boot loudly. * feat(core): expose runtime composition through RuntimeInspection The Cordis host holding the active profile was a local const inside PluginInternal's layer, and serviceInventory was computed at import and read by nobody. PluginProfile now holds the host's read-only snapshot reader while apply/clear stay with the owning boot, and RuntimeInspection reports profile, service topology, and invariant results as identifiers only. * feat(opencode): add debug runtime command Prints the composition the current location booted: active profile and ordered plugin IDs, effective service topology, and the boot invariant report. --json prints the raw payload. * test(opencode): pin debug runtime in the CLI help snapshot
1 parent be73f63 commit 21b52c2

12 files changed

Lines changed: 334 additions & 7 deletions

File tree

‎.changeset/runtime-inspection.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
---
2+
"opencode": patch
3+
---
4+
5+
Add `redcode debug runtime`, which prints the composition the current location actually booted: the active Cordis profile and its ordered plugin IDs, the effective service topology derived from the compiled layer graph, and the runtime invariant report from boot readiness. Runtime invariants now return a typed result per owner instead of passing silently, and a failing owner is named while still failing boot. The payload carries identifiers only — no config values, credentials, paths, or environment.

‎packages/core/src/invariant.ts‎

Lines changed: 34 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,18 +1,31 @@
11
export * as RuntimeInvariant from "./invariant"
22

3-
import { Context, Effect, Layer, Scope } from "effect"
3+
import { Cause, Context, Effect, Exit, Layer, Scope } from "effect"
44
import { makeLocationNode } from "./effect/app-node"
55

66
export interface Registration {
77
readonly dispose: Effect.Effect<void>
88
}
99

10+
export interface Result {
11+
readonly owner: string
12+
readonly ok: boolean
13+
readonly error?: string
14+
}
15+
1016
export interface Interface {
1117
readonly register: (
1218
owner: string,
1319
check: () => Effect.Effect<void>,
1420
) => Effect.Effect<Registration, never, Scope.Scope>
15-
readonly run: Effect.Effect<void>
21+
/**
22+
* Runs every registered check and reports one result per owner. Every check runs even
23+
* when an earlier one fails, so the report names all failing owners, and the run still
24+
* dies afterwards: a broken invariant must fail boot loudly, never degrade to a warning.
25+
*/
26+
readonly run: Effect.Effect<readonly Result[]>
27+
/** Results of the most recent `run`, empty until the first run. */
28+
readonly results: Effect.Effect<readonly Result[]>
1629
readonly list: Effect.Effect<readonly string[]>
1730
}
1831

@@ -22,6 +35,7 @@ export const layer = Layer.effect(
2235
Service,
2336
Effect.gen(function* () {
2437
const checks = new Map<string, () => Effect.Effect<void>>()
38+
let results: readonly Result[] = []
2539
return Service.of({
2640
register: Effect.fn("RuntimeInvariant.register")(function* (owner, check) {
2741
if (checks.has(owner)) return yield* Effect.die(`Runtime invariant already registered for ${owner}`)
@@ -35,7 +49,24 @@ export const layer = Layer.effect(
3549
yield* Effect.addFinalizer(() => dispose)
3650
return { dispose }
3751
}),
38-
run: Effect.forEach(checks, ([, check]) => check(), { discard: true }),
52+
run: Effect.gen(function* () {
53+
results = yield* Effect.forEach(Array.from(checks), ([owner, check]) =>
54+
check().pipe(
55+
Effect.exit,
56+
Effect.map(
57+
(exit): Result =>
58+
Exit.isSuccess(exit) ? { owner, ok: true } : { owner, ok: false, error: Cause.pretty(exit.cause) },
59+
),
60+
),
61+
)
62+
const failed = results.filter((result) => !result.ok)
63+
if (failed.length > 0)
64+
return yield* Effect.die(
65+
`Runtime invariants failed: ${failed.map((result) => `${result.owner}: ${result.error}`).join("; ")}`,
66+
)
67+
return results
68+
}),
69+
results: Effect.sync(() => results),
3970
list: Effect.sync(() => Array.from(checks.keys())),
4071
})
4172
}),

‎packages/core/src/location-services.ts‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -20,12 +20,14 @@ import { LocationServiceMap } from "./location-service-map"
2020
import { PermissionV2 } from "./permission"
2121
import { PluginV2 } from "./plugin"
2222
import { PluginInternal } from "./plugin/internal"
23+
import { PluginProfile } from "./plugin/profile"
2324
import { Policy } from "./policy"
2425
import { ProjectCopy } from "./project/copy"
2526
import { Pty } from "./pty"
2627
import { QuestionV2 } from "./question"
2728
import { Reference } from "./reference"
2829
import { ReferenceGuidance } from "./reference/guidance"
30+
import { RuntimeInspection } from "./runtime-inspection"
2931
import * as SessionRunnerLLM from "./session/runner/llm"
3032
import { SessionRunnerModel } from "./session/runner/model"
3133
import { SessionTodo } from "./session/todo"
@@ -41,6 +43,10 @@ import { ToolOutputStore } from "./tool-output-store"
4143

4244
export { LocationServiceMap } from "./location-service-map"
4345

46+
// The inspection node reports the very graph it belongs to, so it reads the derived
47+
// inventory lazily instead of taking it as a value the group cannot produce yet.
48+
export const runtimeInspectionNode = RuntimeInspection.makeNode(() => serviceInventory)
49+
4450
export const locationServices = LayerNode.group([
4551
Location.node,
4652
Policy.node,
@@ -53,7 +59,9 @@ export const locationServices = LayerNode.group([
5359
AISDK.node,
5460
RuntimeInvariant.node,
5561
PluginV2.node,
62+
PluginProfile.node,
5663
PluginInternal.node,
64+
runtimeInspectionNode,
5765
ProjectCopy.node,
5866
ProjectCopy.refreshNode,
5967
FileSystemSearch.node,

‎packages/core/src/plugin/internal.ts‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -34,6 +34,7 @@ import { ProviderPlugins } from "./provider"
3434
import { SkillPlugin } from "./skill"
3535
import { VariantPlugin } from "./variant"
3636
import { CordisPluginHost } from "./cordis"
37+
import { PluginProfile } from "./profile"
3738

3839
export type Requirements =
3940
| AgentV2.Service
@@ -83,6 +84,7 @@ const layer = Layer.effectDiscard(
8384
const skill = yield* SkillV2.Service
8485
const reference = yield* Reference.Service
8586
const invariants = yield* RuntimeInvariant.Service
87+
const profile = yield* PluginProfile.Service
8688
const cordis = yield* CordisPluginHost.make(plugin)
8789
const entries = builtIns().map((input) => {
8890
return {
@@ -111,6 +113,11 @@ const layer = Layer.effectDiscard(
111113
}
112114
})
113115

116+
// Share only the host's reader: this boot keeps ownership of `apply`/`clear`, while
117+
// RuntimeInspection reads the active profile. The invariant report `run` returns is
118+
// recorded by the registry and read back through `RuntimeInvariant.results`; a failing
119+
// check still dies here and fails the location boot.
120+
yield* profile.attach(cordis.snapshot)
114121
yield* cordis
115122
.apply({ name: "internal", entries })
116123
.pipe(Effect.andThen(invariants.run), Effect.withSpan("PluginInternal.boot"))
@@ -135,6 +142,7 @@ function builtIns() {
135142
}
136143

137144
export const locationLayer = layer.pipe(
145+
Layer.provideMerge(PluginProfile.layer),
138146
Layer.provideMerge(Config.locationLayer),
139147
Layer.provideMerge(FetchHttpClient.layer),
140148
)
@@ -160,5 +168,6 @@ export const node = makeLocationNode({
160168
SkillV2.node,
161169
Reference.node,
162170
RuntimeInvariant.node,
171+
PluginProfile.node,
163172
],
164173
})
Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
export * as PluginProfile from "./profile"
2+
3+
import { Context, Effect, Layer } from "effect"
4+
import { makeLocationNode } from "../effect/app-node"
5+
import { CordisPluginHost } from "./cordis"
6+
7+
export interface Interface {
8+
/** Read-only view of the active Cordis profile. Empty until its owner attaches a host. */
9+
readonly snapshot: Effect.Effect<CordisPluginHost.ProfileSnapshot>
10+
/**
11+
* Publishes the reader of the host that owns the active profile. Only the reader is shared:
12+
* `apply` and `clear` stay with the owning boot, so this service reports composition without
13+
* becoming the general service locator ADR 0001 forbids.
14+
*/
15+
readonly attach: (source: Effect.Effect<CordisPluginHost.ProfileSnapshot>) => Effect.Effect<void>
16+
}
17+
18+
export class Service extends Context.Service<Service, Interface>()("@opencode/v2/PluginProfile") {}
19+
20+
export const layer = Layer.sync(Service, () => {
21+
let source: Effect.Effect<CordisPluginHost.ProfileSnapshot> | undefined
22+
return Service.of({
23+
snapshot: Effect.suspend(() => source ?? Effect.succeed({ entries: [] })),
24+
attach: (input) =>
25+
Effect.sync(() => {
26+
source = input
27+
}),
28+
})
29+
})
30+
31+
export const node = makeLocationNode({ service: Service, layer, deps: [] })
Lines changed: 57 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,57 @@
1+
export * as RuntimeInspection from "./runtime-inspection"
2+
3+
import { Context, Effect, Layer } from "effect"
4+
import { makeLocationNode } from "./effect/app-node"
5+
import { LayerNode } from "./effect/layer-node"
6+
import { RuntimeInvariant } from "./invariant"
7+
import { PluginProfile } from "./plugin/profile"
8+
9+
export interface Profile {
10+
readonly name?: string
11+
readonly plugins: readonly string[]
12+
}
13+
14+
export interface Payload {
15+
readonly profile: Profile
16+
readonly services: readonly LayerNode.InspectionEntry[]
17+
readonly invariants: readonly RuntimeInvariant.Result[]
18+
}
19+
20+
export interface Interface {
21+
readonly inspect: Effect.Effect<Payload>
22+
}
23+
24+
export class Service extends Context.Service<Service, Interface>()("@opencode/v2/RuntimeInspection") {}
25+
26+
/**
27+
* Read-only view of the composition a Location actually booted: the active Cordis profile,
28+
* the effective service topology, and the invariant report from boot readiness.
29+
*
30+
* `services` is supplied by the module that owns the Location graph so this module never
31+
* imports that graph back. Every field is an identifier — plugin IDs, service names, tags,
32+
* dependency names, invariant owners. Config values, credentials, paths, and environment
33+
* never enter the payload, so it stays safe to print.
34+
*/
35+
export function makeNode(services: () => readonly LayerNode.InspectionEntry[]) {
36+
return makeLocationNode({
37+
service: Service,
38+
layer: Layer.effect(
39+
Service,
40+
Effect.gen(function* () {
41+
const profile = yield* PluginProfile.Service
42+
const invariants = yield* RuntimeInvariant.Service
43+
return Service.of({
44+
inspect: Effect.gen(function* () {
45+
const snapshot = yield* profile.snapshot
46+
return {
47+
profile: { name: snapshot.name, plugins: snapshot.entries },
48+
services: services(),
49+
invariants: yield* invariants.results,
50+
}
51+
}),
52+
})
53+
}),
54+
),
55+
deps: [PluginProfile.node, RuntimeInvariant.node],
56+
})
57+
}

‎packages/core/test/invariant.test.ts‎

Lines changed: 31 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
import { describe, expect } from "bun:test"
2-
import { Effect } from "effect"
2+
import { Cause, Effect, Exit } from "effect"
33
import { RuntimeInvariant } from "@opencode-ai/core/invariant"
44
import { testEffect } from "./lib/effect"
55

@@ -15,14 +15,42 @@ describe("RuntimeInvariant", () => {
1515
Effect.gen(function* () {
1616
yield* invariants.register("@opencode-ai/core/example", () => Effect.sync(() => runs++))
1717
expect(yield* invariants.list).toEqual(["@opencode-ai/core/example"])
18-
yield* invariants.run
18+
expect(yield* invariants.run).toEqual([{ owner: "@opencode-ai/core/example", ok: true }])
1919
expect(runs).toBe(1)
2020
}),
2121
)
2222

2323
expect(yield* invariants.list).toEqual([])
24-
yield* invariants.run
24+
expect(yield* invariants.run).toEqual([])
2525
expect(runs).toBe(1)
2626
}),
2727
)
28+
29+
it.effect("reports a failing owner by name and still fails the run", () =>
30+
Effect.scoped(
31+
Effect.gen(function* () {
32+
const invariants = yield* RuntimeInvariant.Service
33+
yield* invariants.register("@opencode-ai/core/healthy", () => Effect.void)
34+
yield* invariants.register("@opencode-ai/core/broken", () =>
35+
Effect.sync(() => {
36+
throw new Error("plugin inventory drifted")
37+
}),
38+
)
39+
40+
const exit = yield* Effect.exit(invariants.run)
41+
if (Exit.isSuccess(exit)) throw new Error("expected the broken invariant to fail the run")
42+
expect(Cause.pretty(exit.cause)).toContain("@opencode-ai/core/broken")
43+
expect(Cause.pretty(exit.cause)).not.toContain("@opencode-ai/core/healthy")
44+
45+
const results = yield* invariants.results
46+
expect(results.find((result) => result.owner === "@opencode-ai/core/healthy")).toEqual({
47+
owner: "@opencode-ai/core/healthy",
48+
ok: true,
49+
})
50+
const broken = results.find((result) => result.owner === "@opencode-ai/core/broken")
51+
expect(broken?.ok).toBe(false)
52+
expect(broken?.error).toContain("plugin inventory drifted")
53+
}),
54+
),
55+
)
2856
})

‎packages/core/test/location-layer.test.ts‎

Lines changed: 48 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,7 @@ import { Location } from "@opencode-ai/core/location"
1313
import { PluginV2 } from "@opencode-ai/core/plugin"
1414
import { PluginInternal } from "@opencode-ai/core/plugin/internal"
1515
import { RuntimeInvariant } from "@opencode-ai/core/invariant"
16+
import { RuntimeInspection } from "@opencode-ai/core/runtime-inspection"
1617
import { ModelV2 } from "@opencode-ai/core/model"
1718
import { ProjectV2 } from "@opencode-ai/core/project"
1819
import { ProviderV2 } from "@opencode-ai/core/provider"
@@ -237,7 +238,53 @@ describe("LocationServiceMap", () => {
237238
const invariants = yield* RuntimeInvariant.Service
238239

239240
expect(yield* plugins.list()).toEqual(PluginInternal.builtInIDs())
240-
yield* invariants.run
241+
expect(yield* invariants.run).toContainEqual({ owner: "@opencode-ai/core/plugin", ok: true })
242+
}).pipe(
243+
Effect.scoped,
244+
Effect.provide(LocationServiceMap.Service.get(Location.Ref.make({ directory: AbsolutePath.make(dir.path) }))),
245+
),
246+
),
247+
),
248+
)
249+
250+
it.live("reports the booted composition without leaking configuration", () =>
251+
Effect.acquireRelease(
252+
Effect.promise(() => tmpdir()),
253+
(dir) => Effect.promise(() => dir[Symbol.asyncDispose]()),
254+
).pipe(
255+
Effect.flatMap((dir) =>
256+
Effect.gen(function* () {
257+
yield* Effect.promise(() =>
258+
fs.writeFile(
259+
path.join(dir.path, "opencode.json"),
260+
JSON.stringify({ username: "runtime-inspection-secret-value" }),
261+
),
262+
)
263+
const inspection = yield* RuntimeInspection.Service
264+
const payload = yield* inspection.inspect
265+
266+
expect(payload.profile.name).toBe("internal")
267+
expect(payload.profile.plugins).toEqual(PluginInternal.builtInIDs())
268+
expect(payload.services.map((entry) => entry.name)).toEqual(
269+
expect.arrayContaining([
270+
"@opencode/Location",
271+
"@opencode/v2/Plugin",
272+
"@opencode/v2/PluginProfile",
273+
"@opencode/v2/RuntimeInspection",
274+
"@opencode/v2/RuntimeInvariant",
275+
"@opencode/v2/ToolRegistry",
276+
"plugin-internal",
277+
]),
278+
)
279+
expect(
280+
payload.services.find((entry) => entry.name === "@opencode/v2/RuntimeInspection")?.dependencies,
281+
).toEqual(["@opencode/v2/PluginProfile", "@opencode/v2/RuntimeInvariant"])
282+
expect(payload.invariants).toContainEqual({ owner: "@opencode-ai/core/plugin", ok: true })
283+
284+
// The payload is identifiers only: no config value, credential, path, or
285+
// environment may cross this boundary.
286+
expect(JSON.stringify(payload)).not.toContain("runtime-inspection-secret-value")
287+
expect(JSON.stringify(payload)).not.toContain(dir.path)
241288
}).pipe(
242289
Effect.scoped,
243290
Effect.provide(LocationServiceMap.Service.get(Location.Ref.make({ directory: AbsolutePath.make(dir.path) }))),

‎packages/opencode/src/cli/cmd/debug/index.ts‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,7 @@ import { ScrapCommand } from "./scrap"
1313
import { SkillCommand } from "./skill"
1414
import { SnapshotCommand } from "./snapshot"
1515
import { AgentCommand } from "./agent"
16+
import { RuntimeCommand } from "./runtime"
1617
import { StartupCommand } from "./startup"
1718
import { V2Command } from "./v2"
1819

@@ -29,6 +30,7 @@ export const DebugCommand = cmd({
2930
.command(SkillCommand)
3031
.command(SnapshotCommand)
3132
.command(StartupCommand)
33+
.command(RuntimeCommand)
3234
.command(AgentCommand)
3335
.command(V2Command)
3436
.command(InfoCommand)

0 commit comments

Comments
 (0)