feat(acp): support additional workspace directories (#52524)

This commit is contained in:
Shoubhit Dash
2026-10-01 23:47:00 +05:30
committed by GitHub
Unverified
parent 507e117466
commit 7bb3fbf095
8 changed files with 392 additions and 12 deletions
+83
View File
@@ -0,0 +1,83 @@
import { isAbsolute, join, resolve } from "node:path"
import { isDeepStrictEqual } from "node:util"
import type { OpenCodeClient, PermissionRule, SessionInfo, SessionMetadata } from "@opencode/client/promise"
import { FSUtil } from "@opencode/util/fs-util"
import { Effect, Option, Schema } from "effect"
import { ACPError } from "./error"
import { ACPPromise } from "./promise"
const key = "opencode.acp.additionalDirectories"
const decodeStored = Schema.decodeUnknownOption(Schema.Array(Schema.String))
/**
* Normalizes additional workspace roots without following symlinks, keeping the spelling tools will see, and
* drops duplicates and roots that resolve to cwd. Glob characters are rejected because permission resources
* would treat them as wildcards. The ACP SDK has already dropped entries that are not strings and replaced a
* value that is not an array with `[]`.
*/
export const parse = Effect.fnUntraced(function* (cwd: string, directories: readonly string[] = []) {
const invalid = directories.find((directory) => !isAbsolute(directory) || /[*?]/.test(directory))
if (invalid !== undefined) return yield* new ACPError.InvalidAdditionalDirectoryError({ directory: invalid })
const root = FSUtil.resolve(cwd)
return [...new Set(directories.map((directory) => resolve(FSUtil.windowsPath(directory))))].filter(
(directory) => FSUtil.resolve(directory) !== root,
)
})
/** Session create fields that grant these directories. */
export function grant(directories: readonly string[]) {
if (directories.length === 0) return {}
return { permissions: rules(directories), metadata: { [key]: [...directories] } }
}
/** The additional directories ACP last activated for the session, in request order. */
export function list(session: Pick<SessionInfo, "metadata">) {
return [...Option.getOrElse(decodeStored(session.metadata?.[key]), () => [])]
}
/**
* Replaces the rules granted for the previously activated directories with grants for these directories.
* Grants persist on the server session, so they also apply when it is used from other clients, and child
* sessions copy them when they are created; a child created earlier keeps roots its parent later dropped.
* Session rules are evaluated after agent and config rules, so a grant overrides config `external_directory`
* rules inside the root, while read, edit, and shell rules still apply.
*/
export const activate = Effect.fnUntraced(function* (
client: OpenCodeClient,
session: SessionInfo,
directories: readonly string[],
) {
const previous = list(session)
const owned = rules(previous)
const current = session.permissions ?? []
// ACP rules lead so the session's other rules keep precedence for the same paths.
const permissions = [
...rules(directories),
...current.filter((rule) => !owned.some((item) => isDeepStrictEqual(item, rule))),
]
const metadata: SessionMetadata = {
...Object.fromEntries(Object.entries(session.metadata ?? {}).filter(([name]) => name !== key)),
...(directories.length > 0 ? { [key]: [...directories] } : {}),
}
const permissionsChanged = !isDeepStrictEqual(permissions, current)
const metadataChanged = !isDeepStrictEqual(previous, directories)
if (!permissionsChanged && !metadataChanged) return
yield* ACPPromise.promise(() =>
client.session.update({
sessionID: session.id,
...(permissionsChanged ? { permissions } : {}),
...(metadataChanged ? { metadata } : {}),
}),
)
})
// Tools compare the written path without following symlinks, so both spellings of a root are granted.
function rules(directories: readonly string[]): PermissionRule[] {
return [...new Set(directories.flatMap((directory) => [directory, FSUtil.resolve(directory)]))].map((directory) => ({
action: "external_directory",
resource: join(directory, "*"),
effect: "allow",
}))
}
export * as ACPDirectories from "./directories"
+11
View File
@@ -28,6 +28,11 @@ export class InvalidModeError extends Schema.TaggedError<InvalidModeError>()("AC
mode: Schema.String,
}) {}
export class InvalidAdditionalDirectoryError extends Schema.TaggedError<InvalidAdditionalDirectoryError>()(
"ACPInvalidAdditionalDirectoryError",
{ directory: Schema.String },
) {}
export class AuthRequiredError extends Schema.TaggedError<AuthRequiredError>()("ACPAuthRequiredError", {}) {}
export class UnknownAuthMethodError extends Schema.TaggedError<UnknownAuthMethodError>()("ACPUnknownAuthMethodError", {
@@ -57,6 +62,7 @@ const Errors = Schema.Union([
InvalidModelError,
InvalidEffortError,
InvalidModeError,
InvalidAdditionalDirectoryError,
AuthRequiredError,
UnknownAuthMethodError,
InvalidRequestError,
@@ -88,6 +94,11 @@ export function toRequestError(error: Error): RequestError {
return RequestError.invalidParams({ effort: error.effort }, `effort not found: ${error.effort}`)
case "ACPInvalidModeError":
return RequestError.invalidParams({ mode: error.mode }, `mode not found: ${error.mode}`)
case "ACPInvalidAdditionalDirectoryError":
return RequestError.invalidParams(
{ additionalDirectory: error.directory },
`additional directory must be an absolute path without glob characters: ${error.directory}`,
)
case "ACPAuthRequiredError":
return RequestError.authRequired({}, "provider authentication required")
case "ACPUnknownAuthMethodError":
+24 -8
View File
@@ -41,6 +41,7 @@ import { OPENCODE_VERSION } from "../version"
import type { ACPCatalog, Catalog } from "./catalog"
import { configOptions, currentModel, DEFAULT_VARIANT_VALUE, parseModelSelection } from "./config-option"
import type { ACPConnection } from "./connection"
import { ACPDirectories } from "./directories"
import { ACPError } from "./error"
import { ACPPromise } from "./promise"
import type { ACPSessions, Attached } from "./sessions"
@@ -171,7 +172,7 @@ export function make(input: {
loadSession: true,
mcpCapabilities: { http: true, sse: false },
promptCapabilities: { embeddedContext: true, image: true },
sessionCapabilities: { close: {}, delete: {}, fork: {}, list: {}, resume: {} },
sessionCapabilities: { additionalDirectories: {}, close: {}, delete: {}, fork: {}, list: {}, resume: {} },
_meta: { [ACPTranslate.ChildSessionUpdatesCapability]: true },
},
authMethods: [authMethod],
@@ -184,17 +185,23 @@ export function make(input: {
return {}
}),
newSession: Effect.fnUntraced(function* (params) {
const directories = yield* ACPDirectories.parse(params.cwd, params.additionalDirectories)
// Load before creating so a catalog failure leaves no session behind. Agent and model stay unset
// so the server resolves its defaults after plugins activate.
yield* input.catalog.get(params.cwd)
const created = yield* ACPPromise.promise(() =>
input.client.session.create({ location: { directory: params.cwd } }),
input.client.session.create({
location: { directory: params.cwd },
...ACPDirectories.grant(directories),
}),
)
const attached = yield* input.sessions.attach(created, params.cwd, params.mcpServers)
return { sessionId: attached.id, configOptions: yield* currentOptions(attached) }
}),
loadSession: Effect.fnUntraced(function* (params) {
const directories = yield* ACPDirectories.parse(params.cwd, params.additionalDirectories)
const session = yield* getSession(params.sessionId, params.cwd)
yield* ACPDirectories.activate(input.client, session, directories)
const attached = yield* input.sessions.attach(session, session.location.directory, params.mcpServers)
return yield* replay(attached).pipe(
Effect.andThen(currentOptions(attached)),
@@ -212,12 +219,16 @@ export function make(input: {
}),
)
return {
sessions: page.data.map((session) => ({
sessionId: session.id,
cwd: session.location.directory,
title: withTimestampedFallback(session),
updatedAt: new Date(session.time.updated).toISOString(),
})),
sessions: page.data.map((session) => {
const additionalDirectories = ACPDirectories.list(session)
return {
sessionId: session.id,
cwd: session.location.directory,
...(additionalDirectories.length > 0 ? { additionalDirectories } : {}),
title: withTimestampedFallback(session),
updatedAt: new Date(session.time.updated).toISOString(),
}
}),
...(page.cursor.next ? { nextCursor: page.cursor.next } : {}),
}
}),
@@ -233,7 +244,9 @@ export function make(input: {
return {}
}),
resumeSession: Effect.fnUntraced(function* (params) {
const directories = yield* ACPDirectories.parse(params.cwd, params.additionalDirectories)
const session = yield* getSession(params.sessionId, params.cwd)
yield* ACPDirectories.activate(input.client, session, directories)
const attached = yield* input.sessions.attach(session, session.location.directory, params.mcpServers ?? [])
return { configOptions: yield* currentOptions(attached) }
}),
@@ -243,7 +256,10 @@ export function make(input: {
return {}
}),
forkSession: Effect.fnUntraced(function* (params) {
const directories = yield* ACPDirectories.parse(params.cwd, params.additionalDirectories)
const forked = yield* ACPPromise.promise(() => input.client.session.fork({ sessionID: params.sessionId }))
// Forks copy the source session's rules, so the request list replaces any inherited grants.
yield* ACPDirectories.activate(input.client, forked, directories)
const attached = yield* input.sessions.attach(forked, forked.location.directory, params.mcpServers ?? [])
return yield* currentOptions(attached).pipe(
Effect.map((configOptions) => ({ sessionId: attached.id, configOptions })),
@@ -0,0 +1,58 @@
import type { NewSessionResponse, PromptResponse } from "@agentclientprotocol/sdk"
import { describe, expect, test } from "bun:test"
import fs from "node:fs/promises"
import path from "node:path"
import { createAcpFixture, expectOk, initialize } from "./subprocess"
// The first completion reads the file outside cwd; the follow-up completion ends the turn.
function readingModel(file: () => string) {
return (request: unknown) => {
if (JSON.stringify(request).includes('"role":"tool"')) return "done"
return new Response(toolCall(file()), { headers: { "content-type": "text/event-stream" } })
}
}
function toolCall(file: string) {
const call = { index: 0, id: "call_read", type: "function", function: { name: "read", arguments: "" } }
const chunks = [
{ choices: [{ delta: { role: "assistant", tool_calls: [call] }, finish_reason: null }], usage: null },
{
choices: [{ delta: { tool_calls: [{ index: 0, function: { arguments: JSON.stringify({ path: file }) } }] } }],
usage: null,
},
{ choices: [{ delta: {}, finish_reason: "tool_calls" }], usage: null },
{ choices: [], usage: { prompt_tokens: 10, completion_tokens: 1, total_tokens: 11 } },
]
return `${chunks.map((chunk) => `data: ${JSON.stringify(chunk)}\n\n`).join("")}data: [DONE]\n\n`
}
describe("acp additional directories subprocess", () => {
test("tools read files in an additional directory without an external directory ask", async () => {
const target = { file: "" }
await using fixture = await createAcpFixture({ respond: readingModel(() => target.file) })
// Keep the unresolved tmpdir spelling, which differs from the real path on macOS.
const shared = path.join(fixture.root, "shared")
target.file = path.join(shared, "notes.txt")
await fs.mkdir(shared)
await Bun.write(target.file, "shared root content\n")
const acp = fixture.spawn()
await initialize(acp)
const session = expectOk(
await acp.request<NewSessionResponse>("session/new", {
cwd: fixture.home,
additionalDirectories: [shared],
mcpServers: [],
}),
)
const result = expectOk(
await acp.request<PromptResponse>("session/prompt", {
sessionId: session.sessionId,
prompt: [{ type: "text", text: "read the shared notes" }],
}),
)
expect(result.stopReason).toBe("end_turn")
expect(JSON.stringify(fixture.llm.requests.at(-1))).toContain("shared root content")
}, 60_000)
})
@@ -0,0 +1,182 @@
import { describe, expect, test } from "bun:test"
import fs from "node:fs/promises"
import path from "node:path"
import type { PermissionRule } from "@opencode/client/promise"
import { tmpdir } from "../fixture/tmpdir"
import { makeSession, rpcError, startWire, type Wire } from "./wire-fixture"
const key = "opencode.acp.additionalDirectories"
const grant = (directory: string): PermissionRule => ({
action: "external_directory",
resource: path.join(directory, "*"),
effect: "allow",
})
const sharedLib = path.resolve("/shared/lib")
const productDocs = path.resolve("/product-docs")
const old = path.resolve("/old")
const userGrant: PermissionRule = { action: "external_directory", resource: "/x/**", effect: "allow" }
const other: PermissionRule[] = [
{ action: "read", resource: "*.secret", effect: "deny" },
{ action: "external_directory", resource: "/shared/lib/private/*", effect: "deny" },
]
const updates = (acp: Wire) =>
acp.server.requests.filter((request) => request.method === "PATCH" && request.path.startsWith("/api/session/"))
describe("acp additional directories over the wire", () => {
test("session/new grants normalized unique directories other than cwd and lists them", async () => {
await using acp = await startWire()
await acp.initialize()
const created = await acp.request("session/new", {
cwd: "/workspace",
additionalDirectories: ["/shared/lib/", "/workspace", "/docs/../product-docs", "/shared/lib", "/workspace/"],
mcpServers: [],
})
expect(acp.server.sessions.get(created.sessionId)).toMatchObject({
permissions: [grant(sharedLib), grant(productDocs)],
metadata: { [key]: [sharedLib, productDocs] },
})
expect((await acp.request("session/list", { cwd: "/workspace" })).sessions).toEqual([
expect.objectContaining({
sessionId: created.sessionId,
additionalDirectories: [sharedLib, productDocs],
}),
])
})
test("grants both the written and real spelling of a symlinked root and drops links to cwd", async () => {
await using tmp = await tmpdir()
const root = await fs.realpath(tmp.path)
const cwd = path.join(root, "workspace")
const shared = path.join(root, "shared")
await Promise.all([fs.mkdir(cwd), fs.mkdir(shared)])
await Promise.all([
fs.symlink(shared, path.join(root, "shared-link")),
fs.symlink(cwd, path.join(root, "workspace-link")),
])
await using acp = await startWire()
await acp.initialize()
const created = await acp.request("session/new", {
cwd,
additionalDirectories: [path.join(root, "workspace-link"), path.join(root, "shared-link")],
mcpServers: [],
})
expect(acp.server.sessions.get(created.sessionId)).toMatchObject({
permissions: [grant(path.join(root, "shared-link")), grant(shared)],
metadata: { [key]: [path.join(root, "shared-link")] },
})
expect((await acp.request("session/list", { cwd })).sessions[0]?.additionalDirectories).toEqual([
path.join(root, "shared-link"),
])
})
test.each(["shared/lib", "", "/shared/*", "/shared/lib?"])(
"rejects %p before creating a session",
async (directory) => {
await using acp = await startWire()
await acp.initialize()
expect(
await rpcError(
acp.request("session/new", {
cwd: "/workspace",
additionalDirectories: ["/shared/ok", directory],
mcpServers: [],
}),
),
).toMatchObject({ code: -32602, data: { additionalDirectory: directory } })
expect(acp.server.sessions.size).toBe(0)
},
)
test("load and resume replace ACP grants and keep other session rules and metadata", async () => {
await using acp = await startWire()
acp.server.sessions.set("ses_saved", {
...makeSession("ses_saved"),
metadata: { host: "tui", [key]: [old] },
permissions: [grant(old), userGrant, ...other],
})
await acp.initialize()
await acp.request("session/load", {
cwd: "/workspace",
sessionId: "ses_saved",
additionalDirectories: ["/shared/lib", "/product-docs"],
mcpServers: [],
})
expect(acp.server.sessions.get("ses_saved")).toMatchObject({
metadata: { host: "tui", [key]: [sharedLib, productDocs] },
permissions: [grant(sharedLib), grant(productDocs), userGrant, ...other],
})
await acp.request("session/resume", {
cwd: "/workspace",
sessionId: "ses_saved",
additionalDirectories: ["/shared/lib", "/product-docs"],
})
expect(updates(acp)).toHaveLength(1)
await acp.request("session/resume", { cwd: "/workspace", sessionId: "ses_saved" })
expect(acp.server.sessions.get("ses_saved")?.metadata).toEqual({ host: "tui" })
expect(acp.server.sessions.get("ses_saved")?.permissions).toEqual([userGrant, ...other])
expect((await acp.request("session/list", { cwd: "/workspace" })).sessions[0]).not.toHaveProperty(
"additionalDirectories",
)
})
test("forks replace inherited grants with the requested list", async () => {
await using acp = await startWire()
acp.server.sessions.set("ses_source", {
...makeSession("ses_source"),
metadata: { [key]: [old] },
permissions: [grant(old), ...other],
})
await acp.initialize()
const plain = await acp.request("session/fork", { cwd: "/workspace", sessionId: "ses_source" })
const granted = await acp.request("session/fork", {
cwd: "/workspace",
sessionId: "ses_source",
additionalDirectories: ["/shared/lib"],
})
expect(acp.server.sessions.get(plain.sessionId)).toMatchObject({ metadata: {}, permissions: other })
expect(acp.server.sessions.get(granted.sessionId)).toMatchObject({
metadata: { [key]: [sharedLib] },
permissions: [grant(sharedLib), ...other],
})
expect(acp.server.sessions.get("ses_source")?.permissions).toEqual([grant(old), ...other])
})
test("leaves sessions alone without additional directories", async () => {
await using acp = await startWire()
acp.server.sessions.set("ses_saved", {
...makeSession("ses_saved"),
metadata: { host: "tui" },
permissions: [userGrant, ...other],
})
await acp.initialize()
const created = await acp.request("session/new", { cwd: "/workspace", mcpServers: [] })
await acp.request("session/load", { cwd: "/workspace", sessionId: "ses_saved", mcpServers: [] })
await acp.request("session/resume", { cwd: "/workspace", sessionId: "ses_saved", additionalDirectories: [] })
const create = acp.server.requests.find((request) => request.method === "POST" && request.path === "/api/session")
expect(create?.body).toEqual({ location: { directory: "/workspace" } })
expect(acp.server.sessions.get(created.sessionId)?.permissions).toBeUndefined()
expect(updates(acp)).toEqual([])
expect(
(await acp.request("session/list", { cwd: "/workspace" })).sessions.map(
(session) => session.additionalDirectories,
),
).toEqual([undefined, undefined])
})
})
+1 -1
View File
@@ -26,7 +26,7 @@ describe("acp session lifecycle over the wire", () => {
loadSession: true,
mcpCapabilities: { http: true, sse: false },
promptCapabilities: { embeddedContext: true, image: true },
sessionCapabilities: { close: {}, delete: {}, fork: {}, list: {}, resume: {} },
sessionCapabilities: { additionalDirectories: {}, close: {}, delete: {}, fork: {}, list: {}, resume: {} },
_meta: { "opencode/child-session-updates": true },
},
agentInfo: { name: "OpenCode" },
+24 -2
View File
@@ -61,7 +61,16 @@ const SyntheticBody = Schema.Struct({
delivery: Delivery,
resume: Schema.optional(Schema.Boolean),
})
const CreateBody = Schema.Struct({ location: Schema.Struct({ directory: Schema.String }) })
const Permissions = Schema.Array(
Schema.Struct({ action: Schema.String, resource: Schema.String, effect: Schema.Literals(["allow", "deny", "ask"]) }),
)
const Metadata = Schema.Record(Schema.String, Schema.MutableJson)
const CreateBody = Schema.Struct({
location: Schema.Struct({ directory: Schema.String }),
permissions: Schema.optional(Permissions),
metadata: Schema.optional(Metadata),
})
const UpdateBody = Schema.Struct({ permissions: Schema.optional(Permissions), metadata: Schema.optional(Metadata) })
const ModelBody = Schema.Struct({
model: Schema.Struct({ providerID: Schema.String, id: Schema.String, variant: Schema.optional(Schema.String) }),
})
@@ -712,7 +721,13 @@ function startServer(options: WireOptions, changed: () => void) {
return Response.json(page(sessions, query, 100))
}),
POST: body(CreateBody, (_req, input) =>
Response.json({ data: createSession(makeSession("", { cwd: input.location.directory })) }),
Response.json({
data: createSession({
...makeSession("", { cwd: input.location.directory }),
...(input.permissions ? { permissions: [...input.permissions] } : {}),
...(input.metadata ? { metadata: input.metadata } : {}),
}),
}),
),
},
"/api/session/:sessionID": {
@@ -727,6 +742,13 @@ function startServer(options: WireOptions, changed: () => void) {
if (invalid) return invalid
return fake.sessions.delete(req.params.sessionID) ? noContent() : notFound(req.params.sessionID)
}),
PATCH: body(UpdateBody, (req, input) => {
const session = fake.sessions.get(req.params.sessionID)
if (!session) return notFound(req.params.sessionID)
if (input.permissions) session.permissions = [...input.permissions]
if (input.metadata) session.metadata = input.metadata
return noContent()
}),
},
"/api/session/:sessionID/fork": {
POST: route((req) => {
+9 -1
View File
@@ -1,4 +1,4 @@
import { describe, expect } from "bun:test"
import { describe, expect, test } from "bun:test"
import { Cause, Deferred, Effect, Fiber, Layer } from "effect"
import { Agent } from "@opencode/core/agent"
import { Database } from "@opencode/core/database/database"
@@ -148,6 +148,14 @@ describe("Permission", () => {
}),
)
test("matches Windows rule resources against slash-normalized file access resources", () => {
const rules: Permission.Ruleset = [
{ action: "external_directory", resource: "C:\\Users\\x\\proj\\*", effect: "allow" },
]
expect(Permission.evaluate("external_directory", "C:/Users/x/proj/src/*", rules).effect).toBe("allow")
expect(Permission.evaluate("external_directory", "C:/Users/x/other/*", rules).effect).toBe("ask")
})
it.effect("allows managed output reads without granting external directory access", () =>
Effect.gen(function* () {
yield* setup([