Orca is the place for working with a fleet of agents (e.g. Grok Bot, Claude Code). Run any coding agent with your own subscription. Available on desktop, mobile and remote runtime.
TypeScript adeagent-ideai-agentsautomationbotclaude-codecodexghosttygrok-bothermes-agentmobile-appmuseopenclawopencodeorchestrationpiruntimeterminalworktreesyc-backed
// Run off Windows: guest overlays use POSIX home paths; live Windows-to-WSL coverage belongs to the rig.
import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
import { tmpdir } from 'node:os'
import { join } from 'node:path'
import { describe, expect, it } from 'vitest'
import { PluginOverlayManager } from './plugin-overlay'
import { createInstallPluginsHandler } from './wsl-install-plugins-handler'
import { PLUGIN_SOURCE_MAX_BYTES } from './plugin-source-limit'
describe.skipIf(process.platform === 'win32')('createInstallPluginsHandler (guest side)', () => {
function freshHome(): string {
return mkdtempSync(join(tmpdir(), 'wsl-guest-home-'))
}
function withHome(run: (home: string) => void): void {
const home = freshHome()
try {
run(home)
} finally {
rmSync(home, { recursive: true, force: true })
}
}
function requireOverlayDir(dir: string | undefined): string {
if (typeof dir !== 'string') {
throw new Error('expected the handler to return an overlay dir')
}
return dir
}
it('scopes opted-in Claude mods to versioned relay storage and remembers shortcut removal', () => {
withHome((home) => {
const config = join(home, 'claude-profile')
const install = createInstallPluginsHandler(new PluginOverlayManager({ homeDir: home }), {
HOME: home,
CLAUDE_CONFIG_DIR: config,
ORCA_WSL_HOOK_INSTANCE: 'claude-test'
})
expect(install({ claudeAgentViewSource: '' }).overlayDirs.claudeAgentView).toBeUndefined()
expect(existsSync(config)).toBe(false)
const source = 'export function register() {}'
const first = install({ claudeAgentViewSource: source }).overlayDirs.claudeAgentView
if (!first) {
throw new Error('Claude mod was not installed')
}
expect(first.startsWith(join(home, '.orca-relay'))).toBe(true)
expect(readFileSync(join(first, 'hooks', 'register.js'), 'utf8')).toBe(source)
expect(existsSync(join(config, 'skills'))).toBe(false)
const second = install({ claudeAgentViewSource: `${source}\n// new version` }).overlayDirs
.claudeAgentView
expect(second).not.toBe(first)
expect(readFileSync(join(first, 'hooks', 'register.js'), 'utf8')).toBe(source)
expect(install({ claudeAgentViewSource: '' }).overlayDirs.claudeAgentView).toBeUndefined()
expect(JSON.parse(readFileSync(join(config, 'keybindings.json'), 'utf8')).bindings).toEqual(
[]
)
expect(install({ claudeAgentViewSource: source }).overlayDirs.claudeAgentView).toBe(first)
writeFileSync(join(config, 'keybindings.json'), '{"bindings": []}')
install({ claudeAgentViewSource: '' })
expect(install({ claudeAgentViewSource: source }).overlayDirs.claudeAgentView).toBeUndefined()
expect(readFileSync(join(config, 'keybindings.json'), 'utf8')).toBe('{"bindings": []}')
})
})
it('writes orca-opencode-status.js into the overlay and returns that dir', () => {
withHome((home) => {
const install = createInstallPluginsHandler(new PluginOverlayManager({ homeDir: home }), {
HOME: home,
ORCA_WSL_HOOK_INSTANCE: 'inst1'
})
const source = '// orca opencode status plugin\nexport const Plugin = () => ({})\n'
const res = install({ opencodePluginSource: source })
expect(res.installed.opencode).toBe(true)
const dir = res.overlayDirs.opencode
expect(typeof dir).toBe('string')
const pluginPath = join(requireOverlayDir(dir), 'plugins', 'orca-opencode-status.js')
expect(existsSync(pluginPath)).toBe(true)
expect(readFileSync(pluginPath, 'utf8')).toBe(source)
})
})
it('materializes the requested Pi extension in the guest home', () => {
withHome((home) => {
const install = createInstallPluginsHandler(new PluginOverlayManager({ homeDir: home }), {
HOME: home,
ORCA_WSL_HOOK_INSTANCE: 'inst-pi'
})
const source = '// @orca-managed-pi-extension\nexport default {}\n'
const res = install({ piExtensionSource: source, launchKind: 'pi' })
expect(res.overlayDirs.pi).toBe(join(home, '.pi', 'agent'))
const extension = join(home, '.pi', 'agent', 'extensions', 'orca-agent-status.ts')
expect(readFileSync(extension, 'utf8')).toContain(source)
})
})
it('writes the OpenCode 2 plugin to its separate overlay', () => {
withHome((home) => {
const install = createInstallPluginsHandler(new PluginOverlayManager({ homeDir: home }), {
HOME: home,
ORCA_WSL_HOOK_INSTANCE: 'inst-v2'
})
const source = '// opencode2\n'
const res = install({ opencode2PluginSource: source })
const dir = res.overlayDirs.opencode2
expect(res.installed.opencode2).toBe(true)
expect(typeof dir).toBe('string')
expect(
readFileSync(join(requireOverlayDir(dir), 'plugins', 'orca-opencode2-status.js'), 'utf8')
).toBe(source)
expect(res.overlayDirs.opencode).toBeUndefined()
})
})
it('reuses the overlay on repeat installs instead of rebuilding it', () => {
withHome((home) => {
const install = createInstallPluginsHandler(new PluginOverlayManager({ homeDir: home }), {
HOME: home,
ORCA_WSL_HOOK_INSTANCE: 'inst1'
})
const source = '// v1\n'
const dir = requireOverlayDir(install({ opencodePluginSource: source }).overlayDirs.opencode)
// Keep the existing config root under running agents; a wipe/rebuild would remove this canary.
const canary = join(dir, 'opencode.json')
writeFileSync(canary, '{"model":"user-set"}')
expect(install({ opencodePluginSource: source }).overlayDirs.opencode).toBe(dir)
expect(install({}).overlayDirs.opencode).toBe(dir)
expect(existsSync(canary)).toBe(true)
})
})
it('rebuilds if the resolved source dir ever changes (defensive)', () => {
withHome((home) => {
// Mutate captured env to model a newly resolvable source dir; production relay env stays fixed for its lifetime.
const userConfig = join(home, 'my-opencode')
const env: NodeJS.ProcessEnv = { HOME: home, ORCA_WSL_HOOK_INSTANCE: 'inst1' }
const install = createInstallPluginsHandler(new PluginOverlayManager({ homeDir: home }), env)
const source = '// v1\n'
install({ opencodePluginSource: source })
mkdirSync(userConfig, { recursive: true })
writeFileSync(join(userConfig, 'opencode.json'), '{"model":"late"}')
env.ORCA_OPENCODE_SOURCE_CONFIG_DIR = userConfig
const dir = requireOverlayDir(install({ opencodePluginSource: source }).overlayDirs.opencode)
expect(readFileSync(join(dir, 'opencode.json'), 'utf8')).toBe('{"model":"late"}')
})
})
it('rebuilds when the cached overlay lost its plugin file', () => {
withHome((home) => {
const install = createInstallPluginsHandler(new PluginOverlayManager({ homeDir: home }), {
HOME: home,
ORCA_WSL_HOOK_INSTANCE: 'inst1'
})
const source = '// v1\n'
const dir = requireOverlayDir(install({ opencodePluginSource: source }).overlayDirs.opencode)
// A failed rebuild can leave an empty directory; only the plugin file proves a cache hit.
rmSync(join(dir, 'plugins', 'orca-opencode-status.js'))
expect(install({ opencodePluginSource: source }).overlayDirs.opencode).toBe(dir)
expect(existsSync(join(dir, 'plugins', 'orca-opencode-status.js'))).toBe(true)
})
})
it('re-materializes when the shipped source changes', () => {
withHome((home) => {
const install = createInstallPluginsHandler(new PluginOverlayManager({ homeDir: home }), {
HOME: home,
ORCA_WSL_HOOK_INSTANCE: 'inst1'
})
install({ opencodePluginSource: '// v1\n' })
// Why: a mid-session Orca upgrade ships new plugin source; future spawns must see it.
const dir = requireOverlayDir(
install({ opencodePluginSource: '// v2\n' }).overlayDirs.opencode
)
expect(readFileSync(join(dir, 'plugins', 'orca-opencode-status.js'), 'utf8')).toBe('// v2\n')
})
})
it('rebuilds when the cached overlay disappeared from the guest', () => {
withHome((home) => {
const install = createInstallPluginsHandler(new PluginOverlayManager({ homeDir: home }), {
HOME: home,
ORCA_WSL_HOOK_INSTANCE: 'inst1'
})
const source = '// v1\n'
const dir = requireOverlayDir(install({ opencodePluginSource: source }).overlayDirs.opencode)
rmSync(dir, { recursive: true, force: true })
expect(install({ opencodePluginSource: source }).overlayDirs.opencode).toBe(dir)
expect(existsSync(join(dir, 'plugins', 'orca-opencode-status.js'))).toBe(true)
})
})
it('mirrors an explicitly-set config root so overriding the var does not drop it', () => {
withHome((home) => {
// Why: setting OPENCODE_CONFIG_DIR to the overlay removes the user's own value
// from OpenCode's config-dir list, so that one must be mirrored in.
const userConfig = join(home, 'my-opencode')
mkdirSync(userConfig, { recursive: true })
writeFileSync(join(userConfig, 'opencode.json'), '{"model":"user-set"}')
const install = createInstallPluginsHandler(new PluginOverlayManager({ homeDir: home }), {
HOME: home,
ORCA_OPENCODE_SOURCE_CONFIG_DIR: userConfig,
ORCA_WSL_HOOK_INSTANCE: 'inst1'
})
const dir = requireOverlayDir(
install({ opencodePluginSource: '// v1\n' }).overlayDirs.opencode
)
expect(readFileSync(join(dir, 'opencode.json'), 'utf8')).toBe('{"model":"user-set"}')
expect(existsSync(join(dir, 'plugins', 'orca-opencode-status.js'))).toBe(true)
})
})
it('mirrors the XDG default config root when using an overlay', () => {
withHome((home) => {
// Why: OPENCODE_CONFIG_DIR replaces the default root, so the overlay must
// carry the user's default config and Orca's plugin together.
const defaultConfig = join(home, '.config', 'opencode')
mkdirSync(defaultConfig, { recursive: true })
writeFileSync(join(defaultConfig, 'opencode.json'), '{"model":"default"}')
const install = createInstallPluginsHandler(new PluginOverlayManager({ homeDir: home }), {
HOME: home,
ORCA_WSL_HOOK_INSTANCE: 'inst1'
})
const dir = requireOverlayDir(
install({ opencodePluginSource: '// v1\n' }).overlayDirs.opencode
)
expect(existsSync(join(dir, 'opencode.json'))).toBe(true)
expect(existsSync(join(dir, 'plugins', 'orca-opencode-status.js'))).toBe(true)
})
})
it('rejects a source that exceeds the byte cap before writing anything', () => {
withHome((home) => {
const overlay = new PluginOverlayManager({ homeDir: home })
const install = createInstallPluginsHandler(overlay, {
HOME: home
})
const tooBig = 'a'.repeat(PLUGIN_SOURCE_MAX_BYTES + 1)
expect(() => install({ opencodePluginSource: tooBig })).toThrow(/byte cap/)
expect(overlay.hasOpenCodeSource()).toBe(false)
})
})
it('returns no overlay dir when no opencode source is provided', () => {
withHome((home) => {
const install = createInstallPluginsHandler(new PluginOverlayManager({ homeDir: home }), {
HOME: home
})
const res = install({})
expect(res.installed.opencode).toBe(false)
expect(res.overlayDirs.opencode).toBeUndefined()
})
})
})