@openclaw/codex 2026.5.2-beta.2 → 2026.5.3-beta.1

package/src/manifest.test.ts

@@ -1,20 +0,0 @@
-import fs from "node:fs";
-import { describe, expect, it } from "vitest";
-import { MANAGED_CODEX_APP_SERVER_PACKAGE_VERSION } from "./app-server/version.js";
-
-type CodexPackageManifest = {
-  dependencies?: Record<string, string>;
-};
-
-describe("codex package manifest", () => {
-  it("keeps runtime dependencies in the package manifest", () => {
-    const packageJson = JSON.parse(
-      fs.readFileSync(new URL("../package.json", import.meta.url), "utf8"),
-    ) as CodexPackageManifest;
-
-    expect(packageJson.dependencies?.["@mariozechner/pi-coding-agent"]).toBeDefined();
-    expect(packageJson.dependencies?.["@openai/codex"]).toBe(
-      MANAGED_CODEX_APP_SERVER_PACKAGE_VERSION,
-    );
-  });
-});

package/src/migration/apply.ts

@@ -1,43 +0,0 @@
-import path from "node:path";
-import { summarizeMigrationItems } from "openclaw/plugin-sdk/migration";
-import {
-  archiveMigrationItem,
-  copyMigrationFileItem,
-  writeMigrationReport,
-} from "openclaw/plugin-sdk/migration-runtime";
-import type {
-  MigrationApplyResult,
-  MigrationItem,
-  MigrationPlan,
-  MigrationProviderContext,
-} from "openclaw/plugin-sdk/plugin-entry";
-import { buildCodexMigrationPlan } from "./plan.js";
-
-export async function applyCodexMigrationPlan(params: {
-  ctx: MigrationProviderContext;
-  plan?: MigrationPlan;
-}): Promise<MigrationApplyResult> {
-  const plan = params.plan ?? (await buildCodexMigrationPlan(params.ctx));
-  const reportDir = params.ctx.reportDir ?? path.join(params.ctx.stateDir, "migration", "codex");
-  const items: MigrationItem[] = [];
-  for (const item of plan.items) {
-    if (item.status !== "planned") {
-      items.push(item);
-      continue;
-    }
-    if (item.action === "archive") {
-      items.push(await archiveMigrationItem(item, reportDir));
-    } else {
-      items.push(await copyMigrationFileItem(item, reportDir, { overwrite: params.ctx.overwrite }));
-    }
-  }
-  const result: MigrationApplyResult = {
-    ...plan,
-    items,
-    summary: summarizeMigrationItems(items),
-    backupPath: params.ctx.backupPath,
-    reportDir,
-  };
-  await writeMigrationReport(result, { title: "Codex Migration Report" });
-  return result;
-}

package/src/migration/helpers.ts

@@ -1,60 +0,0 @@
-import fs from "node:fs/promises";
-import os from "node:os";
-import path from "node:path";
-
-export async function exists(filePath: string): Promise<boolean> {
-  try {
-    await fs.access(filePath);
-    return true;
-  } catch {
-    return false;
-  }
-}
-
-export async function isDirectory(filePath: string | undefined): Promise<boolean> {
-  if (!filePath) {
-    return false;
-  }
-  try {
-    return (await fs.stat(filePath)).isDirectory();
-  } catch {
-    return false;
-  }
-}
-
-export function resolveUserHomeDir(): string {
-  return process.env.HOME?.trim() || os.homedir();
-}
-
-export function resolveHomePath(value: string): string {
-  if (value === "~") {
-    return resolveUserHomeDir();
-  }
-  if (value.startsWith("~/")) {
-    return path.join(resolveUserHomeDir(), value.slice(2));
-  }
-  return path.resolve(value);
-}
-
-export function sanitizeName(value: string): string {
-  return value
-    .trim()
-    .toLowerCase()
-    .replaceAll(/[^a-z0-9._-]+/gu, "-")
-    .replaceAll(/^-+|-+$/gu, "")
-    .slice(0, 64);
-}
-
-export async function readJsonObject(
-  filePath: string | undefined,
-): Promise<Record<string, unknown>> {
-  if (!filePath) {
-    return {};
-  }
-  try {
-    const parsed = JSON.parse(await fs.readFile(filePath, "utf8"));
-    return parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : {};
-  } catch {
-    return {};
-  }
-}

package/src/migration/plan.ts

@@ -1,148 +0,0 @@
-import path from "node:path";
-import {
-  createMigrationItem,
-  createMigrationManualItem,
-  MIGRATION_REASON_TARGET_EXISTS,
-  summarizeMigrationItems,
-} from "openclaw/plugin-sdk/migration";
-import type {
-  MigrationItem,
-  MigrationPlan,
-  MigrationProviderContext,
-} from "openclaw/plugin-sdk/plugin-entry";
-import { exists, sanitizeName } from "./helpers.js";
-import { discoverCodexSource, hasCodexSource, type CodexSkillSource } from "./source.js";
-import { resolveCodexMigrationTargets } from "./targets.js";
-
-function uniqueSkillName(skill: CodexSkillSource, counts: Map<string, number>): string {
-  const base = sanitizeName(skill.name) || "codex-skill";
-  if ((counts.get(base) ?? 0) <= 1) {
-    return base;
-  }
-  const parent = sanitizeName(path.basename(path.dirname(skill.source)));
-  return sanitizeName(["codex", parent, base].filter(Boolean).join("-")) || base;
-}
-
-async function buildSkillItems(params: {
-  skills: CodexSkillSource[];
-  workspaceDir: string;
-  overwrite?: boolean;
-}): Promise<MigrationItem[]> {
-  const baseCounts = new Map<string, number>();
-  for (const skill of params.skills) {
-    const base = sanitizeName(skill.name) || "codex-skill";
-    baseCounts.set(base, (baseCounts.get(base) ?? 0) + 1);
-  }
-  const resolvedCounts = new Map<string, number>();
-  const planned = params.skills.map((skill) => {
-    const name = uniqueSkillName(skill, baseCounts);
-    resolvedCounts.set(name, (resolvedCounts.get(name) ?? 0) + 1);
-    return { skill, name, target: path.join(params.workspaceDir, "skills", name) };
-  });
-  const items: MigrationItem[] = [];
-  for (const item of planned) {
-    const collides = (resolvedCounts.get(item.name) ?? 0) > 1;
-    const targetExists = await exists(item.target);
-    items.push(
-      createMigrationItem({
-        id: `skill:${item.name}`,
-        kind: "skill",
-        action: "copy",
-        source: item.skill.source,
-        target: item.target,
-        status: collides ? "conflict" : targetExists && !params.overwrite ? "conflict" : "planned",
-        reason: collides
-          ? `multiple Codex skills normalize to "${item.name}"`
-          : targetExists && !params.overwrite
-            ? MIGRATION_REASON_TARGET_EXISTS
-            : undefined,
-        message: `Copy ${item.skill.sourceLabel} into this OpenClaw agent workspace.`,
-        details: {
-          skillName: item.name,
-          sourceLabel: item.skill.sourceLabel,
-        },
-      }),
-    );
-  }
-  return items;
-}
-
-export async function buildCodexMigrationPlan(
-  ctx: MigrationProviderContext,
-): Promise<MigrationPlan> {
-  const source = await discoverCodexSource(ctx.source);
-  if (!hasCodexSource(source)) {
-    throw new Error(
-      `Codex state was not found at ${source.root}. Pass --from <path> if it lives elsewhere.`,
-    );
-  }
-  const targets = resolveCodexMigrationTargets(ctx);
-  const items: MigrationItem[] = [];
-  items.push(
-    ...(await buildSkillItems({
-      skills: source.skills,
-      workspaceDir: targets.workspaceDir,
-      overwrite: ctx.overwrite,
-    })),
-  );
-  for (const [index, plugin] of source.plugins.entries()) {
-    items.push(
-      createMigrationManualItem({
-        id: `plugin:${sanitizeName(plugin.name) || sanitizeName(path.basename(plugin.source))}:${index + 1}`,
-        source: plugin.source,
-        message: `Codex native plugin "${plugin.name}" was found but not activated automatically.`,
-        recommendation:
-          "Review the plugin bundle first, then install trusted compatible plugins with openclaw plugins install <path>.",
-      }),
-    );
-  }
-  for (const archivePath of source.archivePaths) {
-    items.push(
-      createMigrationItem({
-        id: archivePath.id,
-        kind: "archive",
-        action: "archive",
-        source: archivePath.path,
-        message:
-          archivePath.message ??
-          "Archived in the migration report for manual review; not imported into live config.",
-        details: { archiveRelativePath: archivePath.relativePath },
-      }),
-    );
-  }
-  const warnings = [
-    ...(items.some((item) => item.status === "conflict")
-      ? [
-          "Conflicts were found. Re-run with --overwrite to replace conflicting skill targets after item-level backups.",
-        ]
-      : []),
-    ...(source.plugins.length > 0
-      ? [
-          "Codex native plugins are reported for manual review only. OpenClaw does not auto-activate plugin bundles, hooks, MCP servers, or apps from another Codex home.",
-        ]
-      : []),
-    ...(source.archivePaths.length > 0
-      ? [
-          "Codex config and hook files are archive-only. They are preserved in the migration report, not loaded into OpenClaw automatically.",
-        ]
-      : []),
-  ];
-  return {
-    providerId: "codex",
-    source: source.root,
-    target: targets.workspaceDir,
-    summary: summarizeMigrationItems(items),
-    items,
-    warnings,
-    nextSteps: [
-      "Run openclaw doctor after applying the migration.",
-      "Review skipped Codex plugin/config/hook items before installing or recreating them in OpenClaw.",
-    ],
-    metadata: {
-      agentDir: targets.agentDir,
-      codexHome: source.codexHome,
-      codexSkillsDir: source.codexSkillsDir,
-      personalAgentsSkillsDir: source.personalAgentsSkillsDir,
-    },
-  };
-}

package/src/migration/provider.test.ts

@@ -1,219 +0,0 @@
-import fs from "node:fs/promises";
-import os from "node:os";
-import path from "node:path";
-import type { MigrationProviderContext } from "openclaw/plugin-sdk/plugin-entry";
-import { afterEach, describe, expect, it, vi } from "vitest";
-import { buildCodexMigrationProvider } from "./provider.js";
-
-const tempRoots = new Set<string>();
-
-const logger = {
-  info() {},
-  warn() {},
-  error() {},
-  debug() {},
-};
-
-async function makeTempRoot(): Promise<string> {
-  const root = await fs.mkdtemp(path.join(os.tmpdir(), "openclaw-migrate-codex-"));
-  tempRoots.add(root);
-  return root;
-}
-
-async function writeFile(filePath: string, content = ""): Promise<void> {
-  await fs.mkdir(path.dirname(filePath), { recursive: true });
-  await fs.writeFile(filePath, content, "utf8");
-}
-
-function makeContext(params: {
-  source: string;
-  stateDir: string;
-  workspaceDir: string;
-  overwrite?: boolean;
-  reportDir?: string;
-}): MigrationProviderContext {
-  return {
-    config: {
-      agents: {
-        defaults: {
-          workspace: params.workspaceDir,
-        },
-      },
-    } as MigrationProviderContext["config"],
-    source: params.source,
-    stateDir: params.stateDir,
-    overwrite: params.overwrite,
-    reportDir: params.reportDir,
-    logger,
-  };
-}
-
-async function createCodexFixture(): Promise<{
-  root: string;
-  homeDir: string;
-  codexHome: string;
-  stateDir: string;
-  workspaceDir: string;
-}> {
-  const root = await makeTempRoot();
-  const homeDir = path.join(root, "home");
-  const codexHome = path.join(root, ".codex");
-  const stateDir = path.join(root, "state");
-  const workspaceDir = path.join(root, "workspace");
-  vi.stubEnv("HOME", homeDir);
-  await writeFile(path.join(codexHome, "skills", "tweet-helper", "SKILL.md"), "# Tweet helper\n");
-  await writeFile(path.join(codexHome, "skills", ".system", "system-skill", "SKILL.md"));
-  await writeFile(path.join(homeDir, ".agents", "skills", "personal-style", "SKILL.md"));
-  await writeFile(
-    path.join(
-      codexHome,
-      "plugins",
-      "cache",
-      "openai-primary-runtime",
-      "documents",
-      "1.0.0",
-      ".codex-plugin",
-      "plugin.json",
-    ),
-    JSON.stringify({ name: "documents" }),
-  );
-  await writeFile(path.join(codexHome, "config.toml"), 'model = "gpt-5.5"\n');
-  await writeFile(path.join(codexHome, "hooks", "hooks.json"), "{}\n");
-  return { root, homeDir, codexHome, stateDir, workspaceDir };
-}
-
-afterEach(async () => {
-  vi.unstubAllEnvs();
-  for (const root of tempRoots) {
-    await fs.rm(root, { recursive: true, force: true });
-  }
-  tempRoots.clear();
-});
-
-describe("buildCodexMigrationProvider", () => {
-  it("plans Codex skills while keeping plugins and native config explicit", async () => {
-    const fixture = await createCodexFixture();
-    const provider = buildCodexMigrationProvider();
-
-    const plan = await provider.plan(
-      makeContext({
-        source: fixture.codexHome,
-        stateDir: fixture.stateDir,
-        workspaceDir: fixture.workspaceDir,
-      }),
-    );
-
-    expect(plan.providerId).toBe("codex");
-    expect(plan.source).toBe(fixture.codexHome);
-    expect(plan.items).toEqual(
-      expect.arrayContaining([
-        expect.objectContaining({
-          id: "skill:tweet-helper",
-          kind: "skill",
-          action: "copy",
-          status: "planned",
-          target: path.join(fixture.workspaceDir, "skills", "tweet-helper"),
-        }),
-        expect.objectContaining({
-          id: "skill:personal-style",
-          kind: "skill",
-          action: "copy",
-          status: "planned",
-          target: path.join(fixture.workspaceDir, "skills", "personal-style"),
-        }),
-        expect.objectContaining({
-          id: "plugin:documents:1",
-          kind: "manual",
-          action: "manual",
-          status: "skipped",
-        }),
-        expect.objectContaining({
-          id: "archive:config.toml",
-          kind: "archive",
-          action: "archive",
-          status: "planned",
-        }),
-        expect.objectContaining({
-          id: "archive:hooks/hooks.json",
-          kind: "archive",
-          action: "archive",
-          status: "planned",
-        }),
-      ]),
-    );
-    expect(plan.items).not.toEqual(
-      expect.arrayContaining([expect.objectContaining({ id: "skill:system-skill" })]),
-    );
-    expect(plan.warnings).toEqual(
-      expect.arrayContaining([
-        expect.stringContaining("Codex native plugins are reported for manual review only"),
-      ]),
-    );
-  });
-
-  it("copies planned skills and archives native config during apply", async () => {
-    const fixture = await createCodexFixture();
-    const reportDir = path.join(fixture.root, "report");
-    const provider = buildCodexMigrationProvider();
-
-    const result = await provider.apply(
-      makeContext({
-        source: fixture.codexHome,
-        stateDir: fixture.stateDir,
-        workspaceDir: fixture.workspaceDir,
-        reportDir,
-      }),
-    );
-
-    await expect(
-      fs.access(path.join(fixture.workspaceDir, "skills", "tweet-helper", "SKILL.md")),
-    ).resolves.toBeUndefined();
-    await expect(
-      fs.access(path.join(fixture.workspaceDir, "skills", "personal-style", "SKILL.md")),
-    ).resolves.toBeUndefined();
-    await expect(
-      fs.access(path.join(reportDir, "archive", "config.toml")),
-    ).resolves.toBeUndefined();
-    expect(result.items).toEqual(
-      expect.arrayContaining([
-        expect.objectContaining({ id: "plugin:documents:1", status: "skipped" }),
-        expect.objectContaining({ id: "skill:tweet-helper", status: "migrated" }),
-        expect.objectContaining({ id: "archive:config.toml", status: "migrated" }),
-      ]),
-    );
-    await expect(fs.access(path.join(reportDir, "report.json"))).resolves.toBeUndefined();
-  });
-
-  it("reports existing skill targets as conflicts unless overwrite is set", async () => {
-    const fixture = await createCodexFixture();
-    await writeFile(path.join(fixture.workspaceDir, "skills", "tweet-helper", "SKILL.md"));
-    const provider = buildCodexMigrationProvider();
-
-    const plan = await provider.plan(
-      makeContext({
-        source: fixture.codexHome,
-        stateDir: fixture.stateDir,
-        workspaceDir: fixture.workspaceDir,
-      }),
-    );
-    const overwritePlan = await provider.plan(
-      makeContext({
-        source: fixture.codexHome,
-        stateDir: fixture.stateDir,
-        workspaceDir: fixture.workspaceDir,
-        overwrite: true,
-      }),
-    );
-
-    expect(plan.items).toEqual(
-      expect.arrayContaining([
-        expect.objectContaining({ id: "skill:tweet-helper", status: "conflict" }),
-      ]),
-    );
-    expect(overwritePlan.items).toEqual(
-      expect.arrayContaining([
-        expect.objectContaining({ id: "skill:tweet-helper", status: "planned" }),
-      ]),
-    );
-  });
-});

package/src/migration/provider.ts

@@ -1,28 +0,0 @@
-import type { MigrationPlan, MigrationProviderPlugin } from "openclaw/plugin-sdk/plugin-entry";
-import { applyCodexMigrationPlan } from "./apply.js";
-import { buildCodexMigrationPlan } from "./plan.js";
-import { discoverCodexSource, hasCodexSource } from "./source.js";
-
-export function buildCodexMigrationProvider(): MigrationProviderPlugin {
-  return {
-    id: "codex",
-    label: "Codex",
-    description:
-      "Inventory and promote Codex CLI skills while keeping Codex native plugins and hooks explicit.",
-    async detect(ctx) {
-      const source = await discoverCodexSource(ctx.source);
-      const found = hasCodexSource(source);
-      return {
-        found,
-        source: source.root,
-        label: "Codex",
-        confidence: found ? source.confidence : "low",
-        message: found ? "Codex state found." : "Codex state not found.",
-      };
-    },
-    plan: buildCodexMigrationPlan,
-    async apply(ctx, plan?: MigrationPlan) {
-      return await applyCodexMigrationPlan({ ctx, plan });
-    },
-  };
-}

package/src/migration/source.ts

@@ -1,176 +0,0 @@
-import type { Dirent } from "node:fs";
-import fs from "node:fs/promises";
-import path from "node:path";
-import {
-  exists,
-  isDirectory,
-  readJsonObject,
-  resolveHomePath,
-  resolveUserHomeDir,
-} from "./helpers.js";
-
-const SKILL_FILENAME = "SKILL.md";
-const MAX_SCAN_DEPTH = 6;
-const MAX_DISCOVERED_DIRS = 2000;
-
-export type CodexSkillSource = {
-  name: string;
-  source: string;
-  sourceLabel: string;
-};
-
-type CodexPluginSource = {
-  name: string;
-  source: string;
-  manifestPath: string;
-};
-
-type CodexArchiveSource = {
-  id: string;
-  path: string;
-  relativePath: string;
-  message?: string;
-};
-
-type CodexSource = {
-  root: string;
-  confidence: "low" | "medium" | "high";
-  codexHome: string;
-  codexSkillsDir?: string;
-  personalAgentsSkillsDir?: string;
-  configPath?: string;
-  hooksPath?: string;
-  skills: CodexSkillSource[];
-  plugins: CodexPluginSource[];
-  archivePaths: CodexArchiveSource[];
-};
-
-function defaultCodexHome(): string {
-  return resolveHomePath(process.env.CODEX_HOME?.trim() || "~/.codex");
-}
-
-function personalAgentsSkillsDir(): string {
-  return path.join(resolveUserHomeDir(), ".agents", "skills");
-}
-
-async function safeReadDir(dir: string): Promise<Dirent[]> {
-  return await fs.readdir(dir, { withFileTypes: true }).catch(() => []);
-}
-
-async function discoverSkillDirs(params: {
-  root: string | undefined;
-  sourceLabel: string;
-  excludeSystem?: boolean;
-}): Promise<CodexSkillSource[]> {
-  if (!params.root || !(await isDirectory(params.root))) {
-    return [];
-  }
-  const discovered: CodexSkillSource[] = [];
-  async function visit(dir: string, depth: number): Promise<void> {
-    if (discovered.length >= MAX_DISCOVERED_DIRS || depth > MAX_SCAN_DEPTH) {
-      return;
-    }
-    const name = path.basename(dir);
-    if (params.excludeSystem && depth === 1 && name === ".system") {
-      return;
-    }
-    if (await exists(path.join(dir, SKILL_FILENAME))) {
-      discovered.push({ name, source: dir, sourceLabel: params.sourceLabel });
-      return;
-    }
-    for (const entry of await safeReadDir(dir)) {
-      if (!entry.isDirectory()) {
-        continue;
-      }
-      await visit(path.join(dir, entry.name), depth + 1);
-    }
-  }
-  await visit(params.root, 0);
-  return discovered;
-}
-
-async function discoverPluginDirs(codexHome: string): Promise<CodexPluginSource[]> {
-  const root = path.join(codexHome, "plugins", "cache");
-  if (!(await isDirectory(root))) {
-    return [];
-  }
-  const discovered = new Map<string, CodexPluginSource>();
-  async function visit(dir: string, depth: number): Promise<void> {
-    if (discovered.size >= MAX_DISCOVERED_DIRS || depth > MAX_SCAN_DEPTH) {
-      return;
-    }
-    const manifestPath = path.join(dir, ".codex-plugin", "plugin.json");
-    if (await exists(manifestPath)) {
-      const manifest = await readJsonObject(manifestPath);
-      const manifestName = typeof manifest.name === "string" ? manifest.name.trim() : "";
-      const name = manifestName || path.basename(dir);
-      discovered.set(dir, { name, source: dir, manifestPath });
-      return;
-    }
-    for (const entry of await safeReadDir(dir)) {
-      if (!entry.isDirectory()) {
-        continue;
-      }
-      await visit(path.join(dir, entry.name), depth + 1);
-    }
-  }
-  await visit(root, 0);
-  return [...discovered.values()].toSorted((a, b) => a.source.localeCompare(b.source));
-}
-
-export async function discoverCodexSource(input?: string): Promise<CodexSource> {
-  const codexHome = resolveHomePath(input?.trim() || defaultCodexHome());
-  const codexSkillsDir = path.join(codexHome, "skills");
-  const agentsSkillsDir = personalAgentsSkillsDir();
-  const configPath = path.join(codexHome, "config.toml");
-  const hooksPath = path.join(codexHome, "hooks", "hooks.json");
-  const codexSkills = await discoverSkillDirs({
-    root: codexSkillsDir,
-    sourceLabel: "Codex CLI skill",
-    excludeSystem: true,
-  });
-  const personalAgentSkills = await discoverSkillDirs({
-    root: agentsSkillsDir,
-    sourceLabel: "personal AgentSkill",
-  });
-  const plugins = await discoverPluginDirs(codexHome);
-  const archivePaths: CodexArchiveSource[] = [];
-  if (await exists(configPath)) {
-    archivePaths.push({
-      id: "archive:config.toml",
-      path: configPath,
-      relativePath: "config.toml",
-      message: "Codex config is archived for manual review; it is not activated automatically.",
-    });
-  }
-  if (await exists(hooksPath)) {
-    archivePaths.push({
-      id: "archive:hooks/hooks.json",
-      path: hooksPath,
-      relativePath: "hooks/hooks.json",
-      message:
-        "Codex native hooks are archived for manual review because they can execute commands.",
-    });
-  }
-  const skills = [...codexSkills, ...personalAgentSkills].toSorted((a, b) =>
-    a.source.localeCompare(b.source),
-  );
-  const high = Boolean(codexSkills.length || plugins.length || archivePaths.length);
-  const medium = personalAgentSkills.length > 0;
-  return {
-    root: codexHome,
-    confidence: high ? "high" : medium ? "medium" : "low",
-    codexHome,
-    ...((await isDirectory(codexSkillsDir)) ? { codexSkillsDir } : {}),
-    ...((await isDirectory(agentsSkillsDir)) ? { personalAgentsSkillsDir: agentsSkillsDir } : {}),
-    ...((await exists(configPath)) ? { configPath } : {}),
-    ...((await exists(hooksPath)) ? { hooksPath } : {}),
-    skills,
-    plugins,
-    archivePaths,
-  };
-}
-
-export function hasCodexSource(source: CodexSource): boolean {
-  return source.confidence !== "low";
-}