fix: expose selected container Codex skills to Skiller

Author: skulidropek

docs/integrations/skiller.md

@@ -46,6 +46,8 @@ docker-git serves Skiller's built renderer from the submodule and proxies `/api/
 
 For project terminals, docker-git scopes Skiller to the active project container filesystem. The API inspects the selected project container mounts, maps `/home/<sshUser>` and the project `targetDir` to the controller-visible Docker volume path, launches Skiller with `HOME` set to that mapped home directory, and registers the mapped project directory in Skiller. This makes global skill operations target the selected container home and project skill operations target the selected container project directory. If the controller cannot access the Docker volume path, the endpoint fails instead of opening Skiller against the wrong filesystem.
 
+For Codex, Skiller resolves `~/.codex/skills` against the selected container home volume. For example, `/home/dev/.codex/skills` inside the selected container is exposed to the controller as the mapped Docker volume path and is the only Codex global skill tree used for that session. docker-git does not fall back to the controller's own `~/.codex/skills`.
+
 When the API process has no `$DISPLAY`, the launcher uses `xvfb-run` if it is available so Skiller can still start in a headless controller environment.
 
 ## PR #238 Proof
@@ -54,6 +56,7 @@ The latest Playwright proof screenshots are checked in under `docs/screenshots/i
 
 - `pr238-proof-27-terminal-skiller-same-session.png` shows the attached terminal with the `Skiller` button.
 - `pr238-proof-28-skiller-session-scoped-ui.png` shows the real Skiller UI opened from that button.
+- `pr238-proof-29-skiller-codex-container-skill.png` shows a Codex skill discovered from the selected container's `/home/dev/.codex/skills` tree.
 
 ## Updating the Pin
 

docs/screenshots/issue-237/proof/pr238-proof-29-skiller-codex-container-skill.png

@@ -7,9 +7,11 @@ export type DockerContainerMount = {
 }
 
 export type SkillerContainerScope = {
+  readonly containerCodexSkillsPath: string
   readonly containerHomePath: string
   readonly containerName: string
   readonly containerProjectPath: string
+  readonly hostCodexSkillsPath: string
   readonly hostHomePath: string
   readonly hostProjectPath: string
   readonly projectId: string
@@ -41,6 +43,9 @@ export const normalizeContainerPath = (path: string): string => {
   return posix.normalize(absolute)
 }
 
+export const containerCodexSkillsPath = (containerHomePath: string): string =>
+  posix.join(normalizeContainerPath(containerHomePath), ".codex", "skills")
+
 const isPathInside = (basePath: string, targetPath: string): boolean =>
   targetPath === basePath || targetPath.startsWith(`${basePath}/`)
 
@@ -82,6 +87,7 @@ export const sameSkillerScope = (
   }
   return left.projectKey === right.projectKey &&
     left.containerName === right.containerName &&
+    left.hostCodexSkillsPath === right.hostCodexSkillsPath &&
     left.hostHomePath === right.hostHomePath &&
     left.hostProjectPath === right.hostProjectPath
 }

packages/api/src/services/skiller-core.ts

@@ -17,6 +17,7 @@ import * as Stream from "effect/Stream"
 
 import { ApiConflictError, ApiInternalError, ApiNotFoundError } from "../api/errors.js"
 import {
+  containerCodexSkillsPath,
   parseDockerMountLines,
   remapContainerPathToMountedHost,
   sameSkillerScope,
@@ -203,13 +204,20 @@ const resolveSkillerScope = (
   Effect.gen(function*(_) {
     const mounts = yield* _(inspectContainerMounts(project.containerName))
     const containerHome = containerHomePath(project.sshUser)
+    const containerCodexSkills = containerCodexSkillsPath(containerHome)
     const hostHomePath = remapContainerPathToMountedHost(mounts, containerHome)
+    const hostCodexSkillsPath = remapContainerPathToMountedHost(mounts, containerCodexSkills)
     const hostProjectPath = remapContainerPathToMountedHost(mounts, project.targetDir)
     if (hostHomePath === null) {
       return yield* _(Effect.fail(new ApiConflictError({
         message: `Skiller cannot find a writable Docker mount for ${containerHome} in ${project.containerName}.`
       })))
     }
+    if (hostCodexSkillsPath === null) {
+      return yield* _(Effect.fail(new ApiConflictError({
+        message: `Skiller cannot find a writable Docker mount for ${containerCodexSkills} in ${project.containerName}.`
+      })))
+    }
     if (hostProjectPath === null) {
       return yield* _(Effect.fail(new ApiConflictError({
         message: `Skiller cannot find a writable Docker mount for ${project.targetDir} in ${project.containerName}.`
@@ -218,9 +226,11 @@ const resolveSkillerScope = (
     yield* _(requireAccessibleDirectory(hostHomePath, "home volume"))
     yield* _(requireAccessibleDirectory(hostProjectPath, "project directory"))
     return {
+      containerCodexSkillsPath: containerCodexSkills,
       containerHomePath: containerHome,
       containerName: project.containerName,
       containerProjectPath: project.targetDir,
+      hostCodexSkillsPath,
       hostHomePath,
       hostProjectPath,
       projectId: project.projectDir,
@@ -318,6 +328,24 @@ const chownIfExists = (path: string, user: SkillerProcessUser): void => {
   }
 }
 
+const prepareSkillerScopeHome = (scope: SkillerContainerScope | null): SkillerProcessUser | null => {
+  const processUser = scopedProcessUser(scope)
+  if (scope === null || processUser === null) {
+    return null
+  }
+  ensureOwnedDirectory(join(scope.hostHomePath, ".agents"), processUser)
+  ensureOwnedDirectory(join(scope.hostHomePath, ".agents", "skills"), processUser)
+  ensureOwnedDirectory(join(scope.hostHomePath, ".codex"), processUser)
+  ensureOwnedDirectory(scope.hostCodexSkillsPath, processUser)
+  ensureOwnedDirectory(join(scope.hostHomePath, ".config"), processUser)
+  ensureOwnedDirectory(join(scope.hostHomePath, ".cache"), processUser)
+  ensureOwnedDirectory(join(scope.hostHomePath, ".local", "share"), processUser)
+  ensureOwnedDirectory(join(scope.hostHomePath, ".skiller"), processUser)
+  chownIfExists(join(scope.hostHomePath, ".codex", "config.toml"), processUser)
+  chownIfExists(join(scope.hostHomePath, ".skiller", "config.toml"), processUser)
+  return processUser
+}
+
 const skillerLaunchCommand = (
   user: SkillerProcessUser | null
 ): readonly [string, ReadonlyArray<string>] =>
@@ -377,16 +405,7 @@ const launchSkillerProcess = (
   scope: SkillerContainerScope | null
 ): SkillerLaunch => {
   mkdirSync(dirname(launchLogPath), { recursive: true })
-  const processUser = scopedProcessUser(scope)
-  if (scope !== null && processUser !== null) {
-    ensureOwnedDirectory(join(scope.hostHomePath, ".agents"), processUser)
-    ensureOwnedDirectory(join(scope.hostHomePath, ".agents", "skills"), processUser)
-    ensureOwnedDirectory(join(scope.hostHomePath, ".config"), processUser)
-    ensureOwnedDirectory(join(scope.hostHomePath, ".cache"), processUser)
-    ensureOwnedDirectory(join(scope.hostHomePath, ".local", "share"), processUser)
-    ensureOwnedDirectory(join(scope.hostHomePath, ".skiller"), processUser)
-    chownIfExists(join(scope.hostHomePath, ".skiller", "config.toml"), processUser)
-  }
+  const processUser = prepareSkillerScopeHome(scope)
   const logFd = openSync(launchLogPath, "a")
   try {
     const [command, args] = skillerLaunchCommand(processUser)
@@ -442,6 +461,15 @@ export const openSkiller = (
     rememberSessionScope(sessionId, scope)
     if (currentProcess !== null && isRunning(currentProcess.process)) {
       if (sameSkillerScope(currentProcess.scope, scope)) {
+        yield* _(Effect.try({
+          catch: (cause) => new ApiInternalError({
+            message: "Failed to prepare selected container home for Skiller.",
+            cause
+          }),
+          try: () => {
+            prepareSkillerScopeHome(scope)
+          }
+        }))
         yield* _(waitForSkillerReady(currentProcess.trpcPort))
         yield* _(registerSkillerProject(currentProcess.trpcPort, scope))
         return toLaunch(currentProcess, true, sessionId)

packages/api/src/services/skiller.ts

@@ -1,6 +1,7 @@
 import { describe, expect, it } from "@effect/vitest"
 
 import {
+  containerCodexSkillsPath,
   parseDockerMountLines,
   remapContainerPathToMountedHost,
   sameSkillerScope
@@ -17,6 +18,9 @@ describe("skiller container filesystem mapping", () => {
     expect(remapContainerPathToMountedHost(mounts, "/home/dev/app")).toBe(
       "/var/lib/docker/volumes/project-home/_data/app"
     )
+    expect(remapContainerPathToMountedHost(mounts, containerCodexSkillsPath("/home/dev"))).toBe(
+      "/var/lib/docker/volumes/project-home/_data/.codex/skills"
+    )
     expect(remapContainerPathToMountedHost(mounts, "/home/dev/.docker-git/.cache/bun")).toBe(
       "/var/lib/docker/volumes/project-cache/_data/bun"
     )
@@ -25,9 +29,11 @@ describe("skiller container filesystem mapping", () => {
 
   it("treats identical Skiller scopes as reusable and different scopes as isolated", () => {
     const scope = {
+      containerCodexSkillsPath: "/home/dev/.codex/skills",
       containerHomePath: "/home/dev",
       containerName: "dg-project",
       containerProjectPath: "/home/dev/app",
+      hostCodexSkillsPath: "/var/lib/docker/volumes/project-home/_data/.codex/skills",
       hostHomePath: "/var/lib/docker/volumes/project-home/_data",
       hostProjectPath: "/var/lib/docker/volumes/project-home/_data/app",
       projectId: "/home/dev/.docker-git/project",
@@ -37,6 +43,10 @@ describe("skiller container filesystem mapping", () => {
 
     expect(sameSkillerScope(scope, scope)).toBe(true)
     expect(sameSkillerScope(scope, { ...scope, projectKey: "def456" })).toBe(false)
+    expect(sameSkillerScope(scope, {
+      ...scope,
+      hostCodexSkillsPath: "/var/lib/docker/volumes/other-home/_data/.codex/skills"
+    })).toBe(false)
     expect(sameSkillerScope(scope, null)).toBe(false)
     expect(sameSkillerScope(null, null)).toBe(true)
   })

packages/api/tests/skiller-core.test.ts

@@ -1,9 +1,11 @@
 import * as Schema from "@effect/schema/Schema"
 
 export const SkillerScopeResponseSchema = Schema.Struct({
+  containerCodexSkillsPath: Schema.String,
   containerHomePath: Schema.String,
   containerName: Schema.String,
   containerProjectPath: Schema.String,
+  hostCodexSkillsPath: Schema.String,
   hostHomePath: Schema.String,
   hostProjectPath: Schema.String,
   projectId: Schema.String,

packages/app/src/web/api-skiller-schema.ts

@@ -9,9 +9,11 @@ const openSkillerMock = vi.hoisted(() => vi.fn())
 const openUrlMock = vi.hoisted(() => vi.fn())
 
 const proofScope = {
+  containerCodexSkillsPath: "/home/dev/.codex/skills",
   containerHomePath: "/home/dev",
   containerName: "dg-project",
   containerProjectPath: "/home/dev/app",
+  hostCodexSkillsPath: "/var/lib/docker/volumes/dg-project-home/_data/.codex/skills",
   hostHomePath: "/var/lib/docker/volumes/dg-project-home/_data",
   hostProjectPath: "/var/lib/docker/volumes/dg-project-home/_data/app",
   projectId: "/home/dev/.docker-git/project",
@@ -23,9 +25,11 @@ const skillerLaunch = (
   overrides: {
     readonly alreadyRunning?: boolean
     readonly scope?: null | {
+      readonly containerCodexSkillsPath: string
       readonly containerHomePath: string
       readonly containerName: string
       readonly containerProjectPath: string
+      readonly hostCodexSkillsPath: string
       readonly hostHomePath: string
       readonly hostProjectPath: string
       readonly projectId: string