Implement per-session listSkills configuration via additionalRoots meta parameter

Author: egor-baranov

src/CodexAcpClient.ts

@@ -14,6 +14,7 @@ import type {
 import type {JsonValue} from "./app-server/serde_json/JsonValue";
 import {ModelId} from "./ModelId";
 import {AgentMode} from "./AgentMode";
+import {CodexAdditionalRootsProvider} from "./CodexAdditionalRootsProvider";
 import path from "node:path";
 import {logger} from "./Logger";
 import type {
@@ -38,13 +39,15 @@ import type {AuthenticationLogoutResponse, AuthenticationStatusResponse} from ".
 export class CodexAcpClient {
 
     private readonly codexClient: CodexAppServerClient;
+    private readonly additionalRootsProvider: CodexAdditionalRootsProvider;
     private readonly config: JsonObject;
     private readonly modelProvider: string | null;
     private gatewayConfig: GatewayConfig | null;
 
 
     constructor(codexClient: CodexAppServerClient, codexConfig?: JsonObject, modelProvider?: string) {
         this.codexClient = codexClient;
+        this.additionalRootsProvider = new CodexAdditionalRootsProvider(codexClient);
         this.config = codexConfig ?? {};
         this.modelProvider = modelProvider ?? null;
         this.gatewayConfig = null;
@@ -179,6 +182,8 @@ export class CodexAcpClient {
     }
 
     async resumeSession(request: acp.ResumeSessionRequest): Promise<SessionMetadata> {
+        await this.additionalRootsProvider.refreshSkills(request);
+
         const response = await this.codexClient.threadResume({
             approvalPolicy: null,
             sandbox: null,
@@ -228,6 +233,8 @@ export class CodexAcpClient {
     }
 
     async newSession(request: acp.NewSessionRequest): Promise<SessionMetadata> {
+        await this.additionalRootsProvider.refreshSkills(request);
+
         const response = await this.codexClient.threadStart({
             config: this.createSessionConfig(request.cwd, request.mcpServers),
             modelProvider: this.getModelProvider(),
@@ -334,6 +341,8 @@ export class CodexAcpClient {
     ): Promise<TurnCompletedNotification> {
         const input = buildPromptItems(request.prompt);
         const effort = modelId.effort as ReasoningEffort | null; //TODO remove unsafe conversion
+
+        await this.additionalRootsProvider.refreshSkills(request);
         await this.codexClient.turnStart({
             outputSchema: null,
             threadId: request.sessionId,

src/CodexAdditionalRootsProvider.ts

@@ -0,0 +1,42 @@
+import type {CodexAppServerClient} from "./CodexAppServerClient";
+
+export class CodexAdditionalRootsProvider {
+    constructor(private readonly codexClient: CodexAppServerClient) {}
+
+    async refreshSkills(request: { _meta?: Record<string, unknown> | null, cwd?: string }): Promise<void> {
+        const additionalRoots = this.readAdditionalRoots(request._meta);
+        const cwd = this.nonEmpty(request.cwd) ?? this.nonEmpty(request._meta?.["cwd"]);
+        if (!cwd) {
+            return;
+        }
+
+        await this.codexClient.listSkills({
+            cwds: [cwd],
+            forceReload: true,
+            perCwdExtraUserRoots: [{
+                cwd: cwd,
+                extraUserRoots: additionalRoots
+            }]
+        });
+    }
+
+    private readAdditionalRoots(meta: Record<string, unknown> | null | undefined): string[] {
+        const rawRoots = meta?.["additionalRoots"];
+        if (!Array.isArray(rawRoots)) {
+            return [];
+        }
+
+        return Array.from(new Set(rawRoots
+            .filter((value): value is string => typeof value === "string")
+            .map(value => value.trim())
+            .filter(value => value.length > 0)));
+    }
+
+    private nonEmpty(value: unknown): string | null {
+        if (typeof value !== "string") {
+            return null;
+        }
+        const trimmed = value.trim();
+        return trimmed.length > 0 ? trimmed : null;
+    }
+}

src/__tests__/CodexACPAgent/CodexAcpClient.test.ts

@@ -105,6 +105,96 @@ describe('ACP server test', { timeout: 40_000 }, () => {
         expect(newSessionResponse.sessionId).toBeDefined()
     })
 
+    it('prefetches session additional skill roots before thread start', async () => {
+        const mockFixture = createCodexMockTestFixture();
+        const codexAcpClient = mockFixture.getCodexAcpClient();
+        const codexAppServerClient = mockFixture.getCodexAppServerClient();
+
+        const listSkillsSpy = vi.spyOn(codexAppServerClient, "listSkills").mockResolvedValue({ data: [] });
+        const threadStartSpy = vi.spyOn(codexAppServerClient, "threadStart").mockResolvedValue({
+            thread: { id: "thread-id" } as any,
+            model: "gpt-5",
+            modelProvider: "openai",
+            cwd: "/workspace",
+            approvalPolicy: "on-request",
+            sandbox: "workspace-write",
+            reasoningEffort: "medium",
+        } as any);
+        vi.spyOn(codexAppServerClient, "listModels").mockResolvedValue({
+            data: [{
+                id: "gpt-5",
+                model: "gpt-5",
+                upgrade: null,
+                displayName: "gpt-5",
+                description: "test model",
+                supportedReasoningEfforts: [{ reasoningEffort: "medium", description: "balanced" }],
+                defaultReasoningEffort: "medium",
+                inputModalities: ["text"],
+                supportsPersonality: false,
+                isDefault: true
+            }],
+            nextCursor: null
+        });
+
+        await codexAcpClient.newSession({
+            cwd: "/workspace",
+            mcpServers: [],
+            _meta: {
+                additionalRoots: ["/skills/one", " /skills/two ", 7]
+            }
+        });
+
+        expect(listSkillsSpy).toHaveBeenCalledWith({
+            cwds: ["/workspace"],
+            forceReload: true,
+            perCwdExtraUserRoots: [{
+                cwd: "/workspace",
+                extraUserRoots: ["/skills/one", "/skills/two"]
+            }]
+        });
+        expect(listSkillsSpy.mock.invocationCallOrder[0]!).toBeLessThan(threadStartSpy.mock.invocationCallOrder[0]!);
+    });
+
+    it('prefetches session additional skill roots before turn start', async () => {
+        const mockFixture = createCodexMockTestFixture();
+        const codexAcpAgent = mockFixture.getCodexAcpAgent();
+        const codexAppServerClient = mockFixture.getCodexAppServerClient();
+
+        const listSkillsSpy = vi.spyOn(codexAppServerClient, "listSkills").mockResolvedValue({ data: [] });
+        const turnStartSpy = vi.spyOn(codexAppServerClient, "turnStart").mockResolvedValue({
+            turn: { id: "turn-id", items: [], status: "inProgress", error: null }
+        } as any);
+        vi.spyOn(codexAppServerClient, "awaitTurnCompleted").mockResolvedValue({
+            threadId: "session-id",
+            turn: { id: "turn-id", items: [], status: "completed", error: null }
+        } as any);
+
+        vi.spyOn(codexAcpAgent, "getSessionState").mockReturnValue(createTestSessionState({
+            sessionId: "session-id",
+            cwd: "/workspace"
+        }));
+
+        const promptRequest: acp.PromptRequest = {
+            sessionId: "session-id",
+            prompt: [{ type: "text", text: "Hello" }],
+            _meta: {
+                additionalRoots: ["/skills/one", " /skills/two ", 7],
+                cwd: "/workspace"
+            }
+        };
+        await codexAcpAgent.prompt(promptRequest);
+
+        expect(listSkillsSpy).toHaveBeenCalledWith({
+            cwds: ["/workspace"],
+            forceReload: true,
+            perCwdExtraUserRoots: [{
+                cwd: "/workspace",
+                extraUserRoots: ["/skills/one", "/skills/two"]
+            }]
+        });
+        expect(listSkillsSpy.mock.invocationCallOrder[0]!).toBeLessThan(turnStartSpy.mock.invocationCallOrder[0]!);
+    });
+
     function loadNotifications(){
         //TODO collect logs form dev run and then load them from file to speedup
         const serverNotifications: ServerNotification[] = [