From 6a7cedcbf1823eeb1c8dfc4baf5a7951854f578b Mon Sep 17 00:00:00 2001 From: Aiden Cline <63023139+rekram1-node@users.noreply.github.com> Date: Tue, 13 Oct 2026 20:28:24 -0500 Subject: [PATCH] feat(plugin): let plugins assert permissions (#54930) --- packages/core/src/plugin/host.ts | 10 ++ packages/core/test/fixture/policy.ts | 1 + packages/core/test/plugin/host.ts | 1 + .../test/plugin/permission-assert.test.ts | 91 +++++++++++++++++++ packages/plugin/src/effect/permission.ts | 9 ++ packages/plugin/src/permission.ts | 14 +++ packages/plugin/src/promise/adapter.ts | 3 + packages/plugin/src/promise/permission.ts | 8 ++ 8 files changed, 137 insertions(+) create mode 100644 packages/core/test/plugin/permission-assert.test.ts create mode 100644 packages/plugin/src/permission.ts diff --git a/packages/core/src/plugin/host.ts b/packages/core/src/plugin/host.ts index 7477c16ff52..8d40da4aa8b 100644 --- a/packages/core/src/plugin/host.ts +++ b/packages/core/src/plugin/host.ts @@ -434,6 +434,16 @@ export const make = Effect.fn("PluginHost.make")(function* ( : Effect.fail(new Error(`Permission request not found: ${input.requestID}`)), ), ), + // Plain rejections stay defects, as for built-in tools, so they end the step. + assert: (input) => + permission.assert(input).pipe( + Effect.catchTags({ + "Permission.BlockedError": (error) => Effect.fail(new Tool.Error({ message: error.message, error })), + "Permission.CorrectedError": (error) => Effect.fail(new Tool.Error({ message: error.feedback, error })), + "Session.NotFoundError": (error) => + Effect.fail(new Tool.Error({ message: `Session not found: ${error.sessionID}`, error })), + }), + ), }, plugin: { list: () => response(plugin.list()), diff --git a/packages/core/test/fixture/policy.ts b/packages/core/test/fixture/policy.ts index 1d4f19459b4..6ac6c259e2f 100644 --- a/packages/core/test/fixture/policy.ts +++ b/packages/core/test/fixture/policy.ts @@ -41,6 +41,7 @@ export const registerIntegrationPolicy = Effect.fn(function* (input: { list: () => Effect.die("unused permission.list"), get: () => Effect.die("unused permission.get"), reply: () => Effect.die("unused permission.reply"), + assert: () => Effect.die("unused permission.assert"), }, }), ) diff --git a/packages/core/test/plugin/host.ts b/packages/core/test/plugin/host.ts index 00838dcaf15..94c92fd0b05 100644 --- a/packages/core/test/plugin/host.ts +++ b/packages/core/test/plugin/host.ts @@ -112,6 +112,7 @@ export function host(overrides: Overrides = {}): Plugin.Context { list: () => Effect.die("unused permission.list"), get: () => Effect.die("unused permission.get"), reply: () => Effect.die("unused permission.reply"), + assert: () => Effect.die("unused permission.assert"), }, plugin: overrides.plugin ?? { list: () => Effect.die("unused plugin.list"), diff --git a/packages/core/test/plugin/permission-assert.test.ts b/packages/core/test/plugin/permission-assert.test.ts new file mode 100644 index 00000000000..ef4490e63f9 --- /dev/null +++ b/packages/core/test/plugin/permission-assert.test.ts @@ -0,0 +1,91 @@ +import { expect } from "bun:test" +import { Permission } from "@opencode/core/permission" +import { Plugin } from "@opencode/core/plugin" +import { PluginHost } from "@opencode/core/plugin/host" +import { PluginPromise } from "@opencode/core/plugin/promise" +import { Tool } from "@opencode/core/tool" +import type { PermissionDomain } from "@opencode/plugin/promise/permission" +import { Session } from "@opencode/schema/session" +import { Cause, Effect, Exit, Layer, Option } from "effect" +import { testEffect } from "../lib/effect" +import { makePluginTestLayer } from "./fixture" + +const asserted: Permission.AssertInput[] = [] + +// Answers by action so each test can pick the outcome the real service would produce. +const permission = Layer.succeed( + Permission.Service, + Permission.Service.of({ + close: Effect.void, + ask: (input) => Effect.succeed({ id: input.id ?? Permission.ID.create(), effect: "ask" }), + assert: (input) => { + asserted.push(input) + if (input.action === "blocked") + return Effect.fail(new Permission.BlockedError({ rules: [], permission: "blocked", resources: ["*"] })) + if (input.action === "corrected") return Effect.fail(new Permission.CorrectedError({ feedback: "Use staging" })) + if (input.action === "declined") return Effect.die(new Permission.DeclinedError()) + return Effect.void + }, + reply: () => Effect.void, + get: () => Effect.succeed(undefined), + forSession: () => Effect.succeed([]), + list: () => Effect.succeed([]), + }), +) + +const it = testEffect(makePluginTestLayer(permission)) +const sessionID = Session.ID.make("ses_plugin_permission") + +it.live("Effect plugins assert permissions and receive outcomes as tool errors", () => + Effect.gen(function* () { + const host = yield* PluginHost.make(yield* Plugin.Service) + const assert = (action: string) => + host.permission.assert({ sessionID, action, resources: ["prod"], save: ["*"] }).pipe(Effect.exit) + + asserted.length = 0 + expect(Exit.isSuccess(yield* assert("deploy"))).toBe(true) + expect(asserted).toEqual([{ sessionID, action: "deploy", resources: ["prod"], save: ["*"] }]) + + const blocked = Option.getOrUndefined(Exit.findErrorOption(yield* assert("blocked"))) + expect(blocked).toBeInstanceOf(Tool.Error) + expect(blocked).toMatchObject({ message: "Permission denied: blocked" }) + expect(blocked?.error).toBeInstanceOf(Permission.BlockedError) + + const corrected = Option.getOrUndefined(Exit.findErrorOption(yield* assert("corrected"))) + expect(corrected).toMatchObject({ message: "Use staging" }) + expect(corrected?.error).toBeInstanceOf(Permission.CorrectedError) + + const declined = yield* assert("declined") + expect( + Exit.isFailure(declined) && + declined.cause.reasons.some( + (reason) => Cause.isDieReason(reason) && reason.defect instanceof Permission.DeclinedError, + ), + ).toBe(true) + }), +) + +it.live("Promise plugins assert permissions with plain input", () => + Effect.gen(function* () { + let assertPermission: PermissionDomain["assert"] = () => Promise.reject(new Error("Plugin did not start")) + yield* PluginPromise.fromPromise({ + id: "promise-permission", + async setup(context) { + assertPermission = context.permission.assert + }, + }).effect(yield* PluginHost.make(yield* Plugin.Service)) + const assert = (action: string) => + Effect.promise(() => + assertPermission({ sessionID: "ses_plugin_permission", action, resources: ["prod"] }).then( + () => undefined, + (error: unknown) => error, + ), + ) + + asserted.length = 0 + expect(yield* assert("deploy")).toBeUndefined() + expect(asserted).toEqual([{ sessionID, action: "deploy", resources: ["prod"] }]) + expect(yield* assert("corrected")).toMatchObject({ _tag: "Tool.Error", message: "Use staging" }) + expect(yield* assert("declined")).toBeInstanceOf(Permission.DeclinedError) + }), +) diff --git a/packages/plugin/src/effect/permission.ts b/packages/plugin/src/effect/permission.ts index e97fbf3ebe5..23aba2da117 100644 --- a/packages/plugin/src/effect/permission.ts +++ b/packages/plugin/src/effect/permission.ts @@ -2,6 +2,9 @@ import type { PermissionApi } from "@opencode/client/effect/api" import type { Agent } from "@opencode/schema/agent" import type { Permission } from "@opencode/schema/permission" import type { Session } from "@opencode/schema/session" +import type { Tool } from "@opencode/schema/tool" +import type { Effect } from "effect" +import type { AssertInput } from "../permission.js" import type { Hooks } from "./registration.js" export interface PermissionEvaluation { @@ -21,4 +24,10 @@ export interface PermissionHooks { export type PermissionDomain = Pick, "list" | "get" | "reply"> & { readonly hook: Hooks + /** + * Evaluates the session's permission rules and, when approval is required, prompts the user and + * waits for the reply. Succeeds when allowed. A deny rule or a rejection with feedback fails with a + * `Tool.Error` carrying the reason; a plain rejection ends the current step. + */ + readonly assert: (input: AssertInput) => Effect.Effect } diff --git a/packages/plugin/src/permission.ts b/packages/plugin/src/permission.ts new file mode 100644 index 00000000000..73c854f0754 --- /dev/null +++ b/packages/plugin/src/permission.ts @@ -0,0 +1,14 @@ +import { Agent } from "@opencode/schema/agent" +import { Permission } from "@opencode/schema/permission" +import { Schema } from "effect" + +export const AssertInput = Schema.Struct({ + sessionID: Permission.Request.fields.sessionID, + agent: Agent.ID.pipe(Schema.optional), + action: Permission.Request.fields.action, + resources: Permission.Request.fields.resources, + save: Permission.Request.fields.save, + metadata: Permission.Request.fields.metadata, + source: Permission.Request.fields.source, +}) +export interface AssertInput extends Schema.Schema.Type {} diff --git a/packages/plugin/src/promise/adapter.ts b/packages/plugin/src/promise/adapter.ts index b66bccb378f..aacf3889367 100644 --- a/packages/plugin/src/promise/adapter.ts +++ b/packages/plugin/src/promise/adapter.ts @@ -6,6 +6,7 @@ import type { Scope } from "effect" import { HttpApiEndpoint, HttpApiSchema } from "effect/http-api" import { define } from "../effect/plugin.js" import type { ToolFailures, ToolHooks } from "../effect/tool.js" +import { AssertInput } from "../permission.js" import type { Plugin } from "./plugin.js" import type { Info } from "./tool.js" import type { RpcDomain, RpcHandlers } from "./rpc.js" @@ -450,6 +451,8 @@ export function fromPromise(plugin: Plugin) { list: adaptApiMethod(PermissionEndpoints["session.permission.list"], host.permission.list), get: adaptApiMethod(PermissionEndpoints["session.permission.get"], host.permission.get), reply: adaptApiMethod(PermissionEndpoints["session.permission.reply"], host.permission.reply), + assert: (input) => + run(Schema.decodeUnknownEffect(AssertInput)(input).pipe(Effect.flatMap(host.permission.assert))), }, plugin: { list: adaptApiMethod(PluginEndpoints["plugin.list"], host.plugin.list), diff --git a/packages/plugin/src/promise/permission.ts b/packages/plugin/src/promise/permission.ts index 1729cac29b5..f7eff1a5eb9 100644 --- a/packages/plugin/src/promise/permission.ts +++ b/packages/plugin/src/promise/permission.ts @@ -2,6 +2,7 @@ import type { PermissionApi } from "@opencode/client/promise/api" import type { Agent } from "@opencode/schema/agent" import type { Permission } from "@opencode/schema/permission" import type { Session } from "@opencode/schema/session" +import type { AssertInput } from "../permission.js" import type { Hooks } from "./registration.js" export interface PermissionEvaluation { @@ -21,4 +22,11 @@ export interface PermissionHooks { export type PermissionDomain = Pick & { readonly hook: Hooks + /** + * Evaluates the session's permission rules and, when approval is required, prompts the user and + * waits for the reply. Resolves when allowed. A deny rule or a rejection with feedback rejects with + * a `Tool.Error` carrying the reason. A plain rejection rejects with an error that ends the current + * step; rethrow it rather than returning it as tool output. + */ + readonly assert: (input: typeof AssertInput.Encoded) => Promise }