@kodelyth/codex 2026.5.40 → 2026.5.42

package/src/app-server/plugin-approval-roundtrip.ts

@@ -0,0 +1,122 @@
+import {
+  callGatewayTool,
+  type EmbeddedRunAttemptParams,
+} from "klaw/plugin-sdk/agent-harness-runtime";
+
+const DEFAULT_CODEX_APPROVAL_TIMEOUT_MS = 120_000;
+const MAX_PLUGIN_APPROVAL_TITLE_LENGTH = 80;
+const MAX_PLUGIN_APPROVAL_DESCRIPTION_LENGTH = 256;
+
+type ExecApprovalDecision = "allow-once" | "allow-always" | "deny";
+
+export type AppServerApprovalOutcome =
+  | "approved-once"
+  | "approved-session"
+  | "denied"
+  | "unavailable"
+  | "cancelled";
+
+type ApprovalRequestResult = {
+  id?: string;
+  decision?: ExecApprovalDecision | null;
+};
+
+type ApprovalWaitResult = {
+  id?: string;
+  decision?: ExecApprovalDecision | null;
+};
+
+export async function requestPluginApproval(params: {
+  paramsForRun: EmbeddedRunAttemptParams;
+  title: string;
+  description: string;
+  severity: "info" | "warning";
+  toolName: string;
+  toolCallId?: string;
+}): Promise<ApprovalRequestResult | undefined> {
+  const timeoutMs = DEFAULT_CODEX_APPROVAL_TIMEOUT_MS;
+  return callGatewayTool(
+    "plugin.approval.request",
+    { timeoutMs: timeoutMs + 10_000 },
+    {
+      pluginId: "klaw-codex-app-server",
+      title: truncateForGateway(params.title, MAX_PLUGIN_APPROVAL_TITLE_LENGTH),
+      description: truncateForGateway(params.description, MAX_PLUGIN_APPROVAL_DESCRIPTION_LENGTH),
+      severity: params.severity,
+      toolName: params.toolName,
+      toolCallId: params.toolCallId,
+      agentId: params.paramsForRun.agentId,
+      sessionKey: params.paramsForRun.sessionKey,
+      turnSourceChannel: params.paramsForRun.messageChannel ?? params.paramsForRun.messageProvider,
+      turnSourceTo: params.paramsForRun.currentChannelId,
+      turnSourceAccountId: params.paramsForRun.agentAccountId,
+      turnSourceThreadId: params.paramsForRun.currentThreadTs,
+      timeoutMs,
+      twoPhase: true,
+    },
+    { expectFinal: false },
+  ) as Promise<ApprovalRequestResult | undefined>;
+}
+
+export function approvalRequestExplicitlyUnavailable(result: unknown): boolean {
+  if (result === null || result === undefined || typeof result !== "object") {
+    return false;
+  }
+  let descriptor: PropertyDescriptor | undefined;
+  try {
+    descriptor = Object.getOwnPropertyDescriptor(result, "decision");
+  } catch {
+    return false;
+  }
+  return descriptor !== undefined && "value" in descriptor && descriptor.value === null;
+}
+
+export async function waitForPluginApprovalDecision(params: {
+  approvalId: string;
+  signal?: AbortSignal;
+}): Promise<ExecApprovalDecision | null | undefined> {
+  const timeoutMs = DEFAULT_CODEX_APPROVAL_TIMEOUT_MS;
+  const waitPromise: Promise<ApprovalWaitResult | undefined> = callGatewayTool(
+    "plugin.approval.waitDecision",
+    { timeoutMs: timeoutMs + 10_000 },
+    { id: params.approvalId },
+  );
+  if (!params.signal) {
+    return (await waitPromise)?.decision;
+  }
+  let onAbort: (() => void) | undefined;
+  const abortPromise = new Promise<never>((_, reject) => {
+    if (params.signal!.aborted) {
+      reject(params.signal!.reason);
+      return;
+    }
+    onAbort = () => reject(params.signal!.reason);
+    params.signal!.addEventListener("abort", onAbort, { once: true });
+  });
+  try {
+    return (await Promise.race([waitPromise, abortPromise]))?.decision;
+  } finally {
+    if (onAbort) {
+      params.signal.removeEventListener("abort", onAbort);
+    }
+  }
+}
+
+export function mapExecDecisionToOutcome(
+  decision: ExecApprovalDecision | null | undefined,
+): AppServerApprovalOutcome {
+  if (decision === "allow-once") {
+    return "approved-once";
+  }
+  if (decision === "allow-always") {
+    return "approved-session";
+  }
+  if (decision === null || decision === undefined) {
+    return "unavailable";
+  }
+  return "denied";
+}
+
+function truncateForGateway(value: string, maxLength: number): string {
+  return value.length <= maxLength ? value : `${value.slice(0, Math.max(0, maxLength - 3))}...`;
+}

package/src/app-server/plugin-inventory.test.ts

@@ -0,0 +1,355 @@
+import { describe, expect, it } from "vitest";
+import { CodexAppInventoryCache } from "./app-inventory-cache.js";
+import { CODEX_PLUGINS_MARKETPLACE_NAME } from "./config.js";
+import { findOpenAiCuratedPluginSummary, readCodexPluginInventory } from "./plugin-inventory.js";
+import type { v2 } from "./protocol.js";
+
+describe("Codex plugin inventory", () => {
+  it("returns enabled migrated curated plugins with stable owned app ids", async () => {
+    const appCache = new CodexAppInventoryCache();
+    await appCache.refreshNow({
+      key: "runtime",
+      nowMs: 0,
+      request: async () => ({
+        data: [appInfo("google-calendar-app", true)],
+        nextCursor: null,
+      }),
+    });
+    const calls: string[] = [];
+    const inventory = await readCodexPluginInventory({
+      pluginConfig: {
+        codexPlugins: {
+          enabled: true,
+          plugins: {
+            "google-calendar": {
+              marketplaceName: CODEX_PLUGINS_MARKETPLACE_NAME,
+              pluginName: "google-calendar",
+            },
+            slack: {
+              enabled: false,
+              marketplaceName: CODEX_PLUGINS_MARKETPLACE_NAME,
+              pluginName: "slack",
+            },
+          },
+        },
+      },
+      appCache,
+      appCacheKey: "runtime",
+      nowMs: 1,
+      request: async (method, params) => {
+        calls.push(method);
+        if (method === "plugin/list") {
+          return pluginList([
+            pluginSummary("google-calendar", { installed: true, enabled: true }),
+            pluginSummary("slack", { installed: true, enabled: true }),
+          ]);
+        }
+        if (method === "plugin/read") {
+          expect(params).toEqual({
+            marketplacePath: "/marketplaces/openai-curated",
+            pluginName: "google-calendar",
+          });
+          return pluginDetail("google-calendar", [appSummary("google-calendar-app")]);
+        }
+        throw new Error(`unexpected request ${method}`);
+      },
+    });
+
+    expect(inventory.records).toHaveLength(1);
+    const record = inventory.records[0];
+    expect(record?.policy.pluginName).toBe("google-calendar");
+    expect(record?.summary.installed).toBe(true);
+    expect(record?.summary.enabled).toBe(true);
+    expect(record?.appOwnership).toBe("proven");
+    expect(record?.ownedAppIds).toStrictEqual(["google-calendar-app"]);
+    expect(record?.apps).toStrictEqual([
+      {
+        id: "google-calendar-app",
+        name: "google-calendar-app",
+        accessible: true,
+        enabled: true,
+        needsAuth: false,
+      },
+    ]);
+    expect(calls).toEqual(["plugin/list", "plugin/read"]);
+  });
+
+  it("matches namespaced curated plugin ids by normalized path segment", async () => {
+    const appCache = new CodexAppInventoryCache();
+    await appCache.refreshNow({
+      key: "runtime",
+      nowMs: 0,
+      request: async () => ({
+        data: [appInfo("github-app", true)],
+        nextCursor: null,
+      }),
+    });
+
+    const listed = pluginList([
+      pluginSummary("openai-curated/github", {
+        name: "GitHub",
+        installed: true,
+        enabled: true,
+      }),
+    ]);
+    expect(findOpenAiCuratedPluginSummary(listed, "github")?.summary.id).toBe(
+      "openai-curated/github",
+    );
+
+    const inventory = await readCodexPluginInventory({
+      pluginConfig: {
+        codexPlugins: {
+          enabled: true,
+          plugins: {
+            github: {
+              marketplaceName: CODEX_PLUGINS_MARKETPLACE_NAME,
+              pluginName: "github",
+            },
+          },
+        },
+      },
+      appCache,
+      appCacheKey: "runtime",
+      nowMs: 1,
+      request: async (method, params) => {
+        if (method === "plugin/list") {
+          return listed;
+        }
+        if (method === "plugin/read") {
+          expect(params).toEqual({
+            marketplacePath: "/marketplaces/openai-curated",
+            pluginName: "github",
+          });
+          return pluginDetail("github", [appSummary("github-app")]);
+        }
+        throw new Error(`unexpected request ${method}`);
+      },
+    });
+
+    expect(inventory.records).toHaveLength(1);
+    const record = inventory.records[0];
+    expect(record?.policy.pluginName).toBe("github");
+    expect(record?.summary.id).toBe("openai-curated/github");
+    expect(record?.summary.installed).toBe(true);
+    expect(record?.summary.enabled).toBe(true);
+    expect(record?.appOwnership).toBe("proven");
+    expect(record?.ownedAppIds).toStrictEqual(["github-app"]);
+    expect(inventory.diagnostics.map((diagnostic) => diagnostic.code)).not.toContain(
+      "plugin_missing",
+    );
+  });
+
+  it("fails closed when plugin detail apps are absent from app inventory", async () => {
+    const appCache = new CodexAppInventoryCache();
+    await appCache.refreshNow({
+      key: "runtime",
+      nowMs: 0,
+      request: async () => ({
+        data: [],
+        nextCursor: null,
+      }),
+    });
+    const inventory = await readCodexPluginInventory({
+      pluginConfig: {
+        codexPlugins: {
+          enabled: true,
+          plugins: {
+            "google-calendar": {
+              marketplaceName: CODEX_PLUGINS_MARKETPLACE_NAME,
+              pluginName: "google-calendar",
+            },
+          },
+        },
+      },
+      appCache,
+      appCacheKey: "runtime",
+      nowMs: 1,
+      request: async (method) => {
+        if (method === "plugin/list") {
+          return pluginList([pluginSummary("google-calendar", { installed: true, enabled: true })]);
+        }
+        if (method === "plugin/read") {
+          return pluginDetail("google-calendar", [appSummary("google-calendar-app")]);
+        }
+        throw new Error(`unexpected request ${method}`);
+      },
+    });
+
+    const record = inventory.records[0];
+    expect(record?.appOwnership).toBe("proven");
+    expect(record?.authRequired).toBe(true);
+    expect(record?.ownedAppIds).toStrictEqual(["google-calendar-app"]);
+    expect(record?.apps).toStrictEqual([
+      {
+        id: "google-calendar-app",
+        name: "google-calendar-app",
+        accessible: false,
+        enabled: false,
+        needsAuth: true,
+      },
+    ]);
+  });
+
+  it("marks display-name-only app matches ambiguous instead of exposing app ids", async () => {
+    const appCache = new CodexAppInventoryCache();
+    await appCache.refreshNow({
+      key: "runtime",
+      nowMs: 0,
+      request: async () => ({
+        data: [
+          {
+            ...appInfo("calendar-app", true),
+            pluginDisplayNames: ["Google Calendar"],
+          },
+        ],
+        nextCursor: null,
+      }),
+    });
+
+    const inventory = await readCodexPluginInventory({
+      pluginConfig: {
+        codexPlugins: {
+          enabled: true,
+          plugins: {
+            "google-calendar": {
+              marketplaceName: CODEX_PLUGINS_MARKETPLACE_NAME,
+              pluginName: "google-calendar",
+            },
+          },
+        },
+      },
+      appCache,
+      appCacheKey: "runtime",
+      nowMs: 1,
+      readPluginDetails: false,
+      request: async (method) => {
+        if (method === "plugin/list") {
+          return pluginList([
+            pluginSummary("google-calendar", {
+              name: "Google Calendar",
+              installed: true,
+              enabled: true,
+            }),
+          ]);
+        }
+        throw new Error(`unexpected request ${method}`);
+      },
+    });
+
+    expect(inventory.records[0]?.appOwnership).toBe("ambiguous");
+    expect(inventory.records[0]?.ownedAppIds).toStrictEqual([]);
+    expect(inventory.diagnostics.map((diagnostic) => diagnostic.code)).toStrictEqual([
+      "app_ownership_ambiguous",
+    ]);
+  });
+
+  it("fails closed when the app inventory cache is missing", async () => {
+    const appCache = new CodexAppInventoryCache();
+    const inventory = await readCodexPluginInventory({
+      pluginConfig: {
+        codexPlugins: {
+          enabled: true,
+          plugins: {
+            "google-calendar": {
+              marketplaceName: CODEX_PLUGINS_MARKETPLACE_NAME,
+              pluginName: "google-calendar",
+            },
+          },
+        },
+      },
+      appCache,
+      appCacheKey: "runtime",
+      request: async (method) => {
+        if (method === "app/list") {
+          return { data: [], nextCursor: null };
+        }
+        if (method === "plugin/list") {
+          return pluginList([pluginSummary("google-calendar", { installed: true, enabled: true })]);
+        }
+        if (method === "plugin/read") {
+          return pluginDetail("google-calendar", [appSummary("google-calendar-app")]);
+        }
+        throw new Error(`unexpected request ${method}`);
+      },
+    });
+
+    expect(inventory.appInventory?.state).toBe("missing");
+    expect(inventory.records[0]?.ownedAppIds).toEqual(["google-calendar-app"]);
+    expect(inventory.records[0]?.apps).toStrictEqual([]);
+    expect(inventory.diagnostics.map((diagnostic) => diagnostic.code)).toStrictEqual([
+      "app_inventory_missing",
+    ]);
+  });
+});
+
+function pluginList(plugins: v2.PluginSummary[]): v2.PluginListResponse {
+  return {
+    marketplaces: [
+      {
+        name: CODEX_PLUGINS_MARKETPLACE_NAME,
+        path: "/marketplaces/openai-curated",
+        interface: null,
+        plugins,
+      },
+    ],
+    marketplaceLoadErrors: [],
+    featuredPluginIds: [],
+  };
+}
+
+function pluginSummary(id: string, overrides: Partial<v2.PluginSummary> = {}): v2.PluginSummary {
+  return {
+    id,
+    name: id,
+    source: { type: "remote" },
+    installed: false,
+    enabled: false,
+    installPolicy: "AVAILABLE",
+    authPolicy: "ON_USE",
+    availability: "AVAILABLE",
+    interface: null,
+    ...overrides,
+  };
+}
+
+function pluginDetail(pluginName: string, apps: v2.AppSummary[]): v2.PluginReadResponse {
+  return {
+    plugin: {
+      marketplaceName: CODEX_PLUGINS_MARKETPLACE_NAME,
+      marketplacePath: "/marketplaces/openai-curated",
+      summary: pluginSummary(pluginName, { installed: true, enabled: true }),
+      description: null,
+      skills: [],
+      apps,
+      mcpServers: [],
+    },
+  };
+}
+
+function appSummary(id: string): v2.AppSummary {
+  return {
+    id,
+    name: id,
+    description: null,
+    installUrl: null,
+    needsAuth: false,
+  };
+}
+
+function appInfo(id: string, accessible: boolean): v2.AppInfo {
+  return {
+    id,
+    name: id,
+    description: null,
+    logoUrl: null,
+    logoUrlDark: null,
+    distributionChannel: null,
+    branding: null,
+    appMetadata: null,
+    labels: null,
+    installUrl: null,
+    isAccessible: accessible,
+    isEnabled: true,
+    pluginDisplayNames: [],
+  };
+}