@kodelyth/codex 2026.5.40 → 2026.5.42

package/src/app-server/models.ts

@@ -0,0 +1,172 @@
+import type { resolveCodexAppServerAuthProfileIdForAgent } from "./auth-bridge.js";
+import type { CodexAppServerClient } from "./client.js";
+import type { CodexAppServerStartOptions } from "./config.js";
+import { readCodexModelListResponse } from "./protocol-validators.js";
+import type { CodexModel, CodexReasoningEffortOption } from "./protocol.js";
+
+export type CodexAppServerModel = {
+  id: string;
+  model: string;
+  displayName?: string;
+  description?: string;
+  hidden?: boolean;
+  isDefault?: boolean;
+  inputModalities: string[];
+  supportedReasoningEfforts: string[];
+  defaultReasoningEffort?: string;
+};
+
+export type CodexAppServerModelListResult = {
+  models: CodexAppServerModel[];
+  nextCursor?: string;
+  truncated?: boolean;
+};
+
+export type CodexAppServerListModelsOptions = {
+  limit?: number;
+  cursor?: string;
+  includeHidden?: boolean;
+  timeoutMs?: number;
+  startOptions?: CodexAppServerStartOptions;
+  authProfileId?: string;
+  agentDir?: string;
+  config?: Parameters<typeof resolveCodexAppServerAuthProfileIdForAgent>[0]["config"];
+  sharedClient?: boolean;
+};
+
+export async function listCodexAppServerModels(
+  options: CodexAppServerListModelsOptions = {},
+): Promise<CodexAppServerModelListResult> {
+  return await withCodexAppServerModelClient(options, async ({ client, timeoutMs }) =>
+    requestModelListPage(client, { ...options, timeoutMs }),
+  );
+}
+
+export async function listAllCodexAppServerModels(
+  options: CodexAppServerListModelsOptions & { maxPages?: number } = {},
+): Promise<CodexAppServerModelListResult> {
+  const maxPages = normalizeMaxPages(options.maxPages);
+  return await withCodexAppServerModelClient(options, async ({ client, timeoutMs }) => {
+    const models: CodexAppServerModel[] = [];
+    let cursor = options.cursor;
+    let nextCursor: string | undefined;
+    for (let page = 0; page < maxPages; page += 1) {
+      const result = await requestModelListPage(client, {
+        ...options,
+        timeoutMs,
+        cursor,
+      });
+      models.push(...result.models);
+      nextCursor = result.nextCursor;
+      if (!nextCursor) {
+        return { models };
+      }
+      cursor = nextCursor;
+    }
+    return { models, nextCursor, truncated: true };
+  });
+}
+
+async function withCodexAppServerModelClient<T>(
+  options: CodexAppServerListModelsOptions,
+  run: (params: { client: CodexAppServerClient; timeoutMs: number }) => Promise<T>,
+): Promise<T> {
+  const timeoutMs = options.timeoutMs ?? 2500;
+  const useSharedClient = options.sharedClient !== false;
+  const { createIsolatedCodexAppServerClient, getSharedCodexAppServerClient } =
+    await import("./shared-client.js");
+  const client = useSharedClient
+    ? await getSharedCodexAppServerClient({
+        startOptions: options.startOptions,
+        timeoutMs,
+        authProfileId: options.authProfileId,
+        agentDir: options.agentDir,
+        config: options.config,
+      })
+    : await createIsolatedCodexAppServerClient({
+        startOptions: options.startOptions,
+        timeoutMs,
+        authProfileId: options.authProfileId,
+        agentDir: options.agentDir,
+        config: options.config,
+      });
+  try {
+    return await run({ client, timeoutMs });
+  } finally {
+    if (!useSharedClient) {
+      client.close();
+    }
+  }
+}
+
+async function requestModelListPage(
+  client: CodexAppServerClient,
+  options: CodexAppServerListModelsOptions & { timeoutMs: number },
+): Promise<CodexAppServerModelListResult> {
+  const response = await client.request(
+    "model/list",
+    {
+      limit: options.limit ?? null,
+      cursor: options.cursor ?? null,
+      includeHidden: options.includeHidden ?? null,
+    },
+    { timeoutMs: options.timeoutMs },
+  );
+  return readModelListResult(response);
+}
+
+export function readModelListResult(value: unknown): CodexAppServerModelListResult {
+  const response = readCodexModelListResponse(value);
+  if (!response) {
+    return { models: [] };
+  }
+  const models = response.data
+    .map((entry) => readCodexModel(entry))
+    .filter((entry): entry is CodexAppServerModel => entry !== undefined);
+  const nextCursor = response.nextCursor ?? undefined;
+  return { models, ...(nextCursor ? { nextCursor } : {}) };
+}
+
+function readCodexModel(value: CodexModel): CodexAppServerModel | undefined {
+  const id = readNonEmptyString(value.id);
+  const model = readNonEmptyString(value.model) ?? id;
+  if (!id || !model) {
+    return undefined;
+  }
+  return {
+    id,
+    model,
+    ...(readNonEmptyString(value.displayName)
+      ? { displayName: readNonEmptyString(value.displayName) }
+      : {}),
+    ...(readNonEmptyString(value.description)
+      ? { description: readNonEmptyString(value.description) }
+      : {}),
+    hidden: value.hidden,
+    isDefault: value.isDefault,
+    inputModalities: value.inputModalities,
+    supportedReasoningEfforts: readReasoningEfforts(value.supportedReasoningEfforts),
+    ...(readNonEmptyString(value.defaultReasoningEffort)
+      ? { defaultReasoningEffort: readNonEmptyString(value.defaultReasoningEffort) }
+      : {}),
+  };
+}
+
+function readReasoningEfforts(value: CodexReasoningEffortOption[]): string[] {
+  const efforts = value
+    .map((entry) => readNonEmptyString(entry.reasoningEffort))
+    .filter((entry): entry is string => entry !== undefined);
+  return [...new Set(efforts)];
+}
+
+function readNonEmptyString(value: unknown): string | undefined {
+  if (typeof value !== "string") {
+    return undefined;
+  }
+  const trimmed = value.trim();
+  return trimmed || undefined;
+}
+
+function normalizeMaxPages(value: unknown): number {
+  return typeof value === "number" && Number.isFinite(value) && value > 0 ? Math.floor(value) : 20;
+}

package/src/app-server/native-hook-relay.test.ts

@@ -0,0 +1,271 @@
+import type { NativeHookRelayRegistrationHandle } from "klaw/plugin-sdk/agent-harness-runtime";
+import { describe, expect, it } from "vitest";
+import {
+  buildCodexNativeHookRelayConfig,
+  buildCodexNativeHookRelayDisabledConfig,
+} from "./native-hook-relay.js";
+
+describe("Codex native hook relay config", () => {
+  it("builds deterministic Codex config overrides with command hooks", () => {
+    const config = buildCodexNativeHookRelayConfig({
+      relay: createRelay(),
+      hookTimeoutSec: 7,
+    });
+
+    expect(config).toEqual({
+      "features.hooks": true,
+      "hooks.PreToolUse": [
+        {
+          hooks: [
+            {
+              type: "command",
+              command: "klaw hooks relay --provider codex --relay-id relay-1 --event pre_tool_use",
+              timeout: 7,
+              async: false,
+              statusMessage: "Klaw native hook relay",
+            },
+          ],
+        },
+      ],
+      "hooks.PostToolUse": [
+        {
+          hooks: [
+            {
+              type: "command",
+              command: "klaw hooks relay --provider codex --relay-id relay-1 --event post_tool_use",
+              timeout: 7,
+              async: false,
+              statusMessage: "Klaw native hook relay",
+            },
+          ],
+        },
+      ],
+      "hooks.PermissionRequest": [
+        {
+          hooks: [
+            {
+              type: "command",
+              command:
+                "klaw hooks relay --provider codex --relay-id relay-1 --event permission_request",
+              timeout: 7,
+              async: false,
+              statusMessage: "Klaw native hook relay",
+            },
+          ],
+        },
+      ],
+      "hooks.Stop": [
+        {
+          hooks: [
+            {
+              type: "command",
+              command:
+                "klaw hooks relay --provider codex --relay-id relay-1 --event before_agent_finalize",
+              timeout: 7,
+              async: false,
+              statusMessage: "Klaw native hook relay",
+            },
+          ],
+        },
+      ],
+      "hooks.state": {
+        "/<session-flags>/config.toml:pre_tool_use:0:0": {
+          enabled: true,
+          trusted_hash: expect.stringMatching(/^sha256:[a-f0-9]{64}$/),
+        },
+        "<session-flags>/config.toml:pre_tool_use:0:0": {
+          enabled: true,
+          trusted_hash: expect.stringMatching(/^sha256:[a-f0-9]{64}$/),
+        },
+        "/<session-flags>/config.toml:post_tool_use:0:0": {
+          enabled: true,
+          trusted_hash: expect.stringMatching(/^sha256:[a-f0-9]{64}$/),
+        },
+        "<session-flags>/config.toml:post_tool_use:0:0": {
+          enabled: true,
+          trusted_hash: expect.stringMatching(/^sha256:[a-f0-9]{64}$/),
+        },
+        "/<session-flags>/config.toml:permission_request:0:0": {
+          enabled: true,
+          trusted_hash: expect.stringMatching(/^sha256:[a-f0-9]{64}$/),
+        },
+        "<session-flags>/config.toml:permission_request:0:0": {
+          enabled: true,
+          trusted_hash: expect.stringMatching(/^sha256:[a-f0-9]{64}$/),
+        },
+        "/<session-flags>/config.toml:stop:0:0": {
+          enabled: true,
+          trusted_hash: expect.stringMatching(/^sha256:[a-f0-9]{64}$/),
+        },
+        "<session-flags>/config.toml:stop:0:0": {
+          enabled: true,
+          trusted_hash: expect.stringMatching(/^sha256:[a-f0-9]{64}$/),
+        },
+      },
+    });
+    expect(JSON.stringify(config)).not.toContain("timeoutSec");
+    expect(JSON.stringify(config)).not.toContain('"matcher":null');
+    expect(config).not.toHaveProperty("hooks.SessionStart");
+    expect(config).not.toHaveProperty("hooks.UserPromptSubmit");
+  });
+
+  it("includes only requested hook events", () => {
+    expect(
+      buildCodexNativeHookRelayConfig({
+        relay: createRelay(),
+        events: ["permission_request"],
+      }),
+    ).toEqual({
+      "features.hooks": true,
+      "hooks.PermissionRequest": [
+        {
+          hooks: [
+            {
+              type: "command",
+              command:
+                "klaw hooks relay --provider codex --relay-id relay-1 --event permission_request",
+              timeout: 5,
+              async: false,
+              statusMessage: "Klaw native hook relay",
+            },
+          ],
+        },
+      ],
+      "hooks.state": {
+        "/<session-flags>/config.toml:permission_request:0:0": {
+          enabled: true,
+          trusted_hash: expect.stringMatching(/^sha256:[a-f0-9]{64}$/),
+        },
+        "<session-flags>/config.toml:permission_request:0:0": {
+          enabled: true,
+          trusted_hash: expect.stringMatching(/^sha256:[a-f0-9]{64}$/),
+        },
+      },
+    });
+  });
+
+  it("clears requested hook events when the relay reports no local work", () => {
+    expect(
+      buildCodexNativeHookRelayConfig({
+        relay: createRelay({ inactiveEvents: ["post_tool_use", "before_agent_finalize"] }),
+        events: ["pre_tool_use", "post_tool_use", "before_agent_finalize"],
+      }),
+    ).toEqual({
+      "features.hooks": true,
+      "hooks.PreToolUse": [
+        {
+          hooks: [
+            {
+              type: "command",
+              command: "klaw hooks relay --provider codex --relay-id relay-1 --event pre_tool_use",
+              timeout: 5,
+              async: false,
+              statusMessage: "Klaw native hook relay",
+            },
+          ],
+        },
+      ],
+      "hooks.PostToolUse": [],
+      "hooks.Stop": [],
+      "hooks.state": {
+        "/<session-flags>/config.toml:pre_tool_use:0:0": {
+          enabled: true,
+          trusted_hash: expect.stringMatching(/^sha256:[a-f0-9]{64}$/),
+        },
+        "<session-flags>/config.toml:pre_tool_use:0:0": {
+          enabled: true,
+          trusted_hash: expect.stringMatching(/^sha256:[a-f0-9]{64}$/),
+        },
+      },
+    });
+  });
+
+  it("clears omitted hook events when requested", () => {
+    expect(
+      buildCodexNativeHookRelayConfig({
+        relay: createRelay(),
+        events: ["permission_request"],
+        clearOmittedEvents: true,
+      }),
+    ).toEqual({
+      "features.hooks": true,
+      "hooks.PreToolUse": [],
+      "hooks.PostToolUse": [],
+      "hooks.PermissionRequest": [
+        {
+          hooks: [
+            {
+              type: "command",
+              command:
+                "klaw hooks relay --provider codex --relay-id relay-1 --event permission_request",
+              timeout: 5,
+              async: false,
+              statusMessage: "Klaw native hook relay",
+            },
+          ],
+        },
+      ],
+      "hooks.Stop": [],
+      "hooks.state": {
+        "/<session-flags>/config.toml:pre_tool_use:0:0": { enabled: false },
+        "<session-flags>/config.toml:pre_tool_use:0:0": { enabled: false },
+        "/<session-flags>/config.toml:post_tool_use:0:0": { enabled: false },
+        "<session-flags>/config.toml:post_tool_use:0:0": { enabled: false },
+        "/<session-flags>/config.toml:permission_request:0:0": {
+          enabled: true,
+          trusted_hash: expect.stringMatching(/^sha256:[a-f0-9]{64}$/),
+        },
+        "<session-flags>/config.toml:permission_request:0:0": {
+          enabled: true,
+          trusted_hash: expect.stringMatching(/^sha256:[a-f0-9]{64}$/),
+        },
+        "/<session-flags>/config.toml:stop:0:0": { enabled: false },
+        "<session-flags>/config.toml:stop:0:0": { enabled: false },
+      },
+    });
+  });
+
+  it("omits matchers so Codex MCP tool names reach the relay with a stable trust hash", () => {
+    const config = buildCodexNativeHookRelayConfig({
+      relay: createRelay(),
+      events: ["pre_tool_use", "post_tool_use"],
+    });
+
+    expect((config["hooks.PreToolUse"] as Array<{ matcher?: unknown }>)[0]).not.toHaveProperty(
+      "matcher",
+    );
+    expect((config["hooks.PostToolUse"] as Array<{ matcher?: unknown }>)[0]).not.toHaveProperty(
+      "matcher",
+    );
+  });
+
+  it("builds deterministic clearing config when the relay is disabled", () => {
+    expect(buildCodexNativeHookRelayDisabledConfig()).toEqual({
+      "features.hooks": false,
+      "hooks.PreToolUse": [],
+      "hooks.PostToolUse": [],
+      "hooks.PermissionRequest": [],
+      "hooks.Stop": [],
+    });
+  });
+});
+
+function createRelay(options?: {
+  inactiveEvents?: readonly NativeHookRelayRegistrationHandle["allowedEvents"][number][];
+}): NativeHookRelayRegistrationHandle {
+  const inactiveEvents = new Set(options?.inactiveEvents ?? []);
+  return {
+    relayId: "relay-1",
+    provider: "codex",
+    sessionId: "session-1",
+    sessionKey: "agent:main:session-1",
+    runId: "run-1",
+    allowedEvents: ["pre_tool_use", "post_tool_use", "permission_request", "before_agent_finalize"],
+    expiresAtMs: Date.now() + 1000,
+    shouldRelayEvent: (event) => !inactiveEvents.has(event),
+    commandForEvent: (event) =>
+      `klaw hooks relay --provider codex --relay-id relay-1 --event ${event}`,
+    renew: () => undefined,
+    unregister: () => undefined,
+  };
+}

package/src/app-server/native-hook-relay.ts

@@ -0,0 +1,150 @@
+import { createHash } from "node:crypto";
+import type {
+  NativeHookRelayEvent,
+  NativeHookRelayRegistrationHandle,
+} from "klaw/plugin-sdk/agent-harness-runtime";
+import type { JsonObject, JsonValue } from "./protocol.js";
+
+export const CODEX_NATIVE_HOOK_RELAY_EVENTS: readonly NativeHookRelayEvent[] = [
+  "pre_tool_use",
+  "post_tool_use",
+  "permission_request",
+  "before_agent_finalize",
+] as const;
+
+type CodexHookEventName = "PreToolUse" | "PostToolUse" | "PermissionRequest" | "Stop";
+
+const CODEX_HOOK_EVENT_BY_NATIVE_EVENT: Record<NativeHookRelayEvent, CodexHookEventName> = {
+  pre_tool_use: "PreToolUse",
+  post_tool_use: "PostToolUse",
+  permission_request: "PermissionRequest",
+  before_agent_finalize: "Stop",
+};
+
+const CODEX_HOOK_KEY_LABEL_BY_NATIVE_EVENT: Record<NativeHookRelayEvent, string> = {
+  pre_tool_use: "pre_tool_use",
+  post_tool_use: "post_tool_use",
+  permission_request: "permission_request",
+  before_agent_finalize: "stop",
+};
+
+const CODEX_SESSION_FLAGS_HOOK_SOURCE_PATHS = [
+  "/<session-flags>/config.toml",
+  "<session-flags>/config.toml",
+] as const;
+
+export function buildCodexNativeHookRelayConfig(params: {
+  relay: NativeHookRelayRegistrationHandle;
+  events?: readonly NativeHookRelayEvent[];
+  hookTimeoutSec?: number;
+  clearOmittedEvents?: boolean;
+}): JsonObject {
+  const events = params.events?.length ? params.events : CODEX_NATIVE_HOOK_RELAY_EVENTS;
+  const selectedEvents = new Set<NativeHookRelayEvent>(events);
+  const config: JsonObject = {
+    "features.hooks": true,
+  };
+  const hookState: JsonObject = {};
+  for (const event of CODEX_NATIVE_HOOK_RELAY_EVENTS) {
+    const codexEvent = CODEX_HOOK_EVENT_BY_NATIVE_EVENT[event];
+    const selected = selectedEvents.has(event);
+    if (!selected || !params.relay.shouldRelayEvent(event)) {
+      if (selected || params.clearOmittedEvents) {
+        config[`hooks.${codexEvent}`] = [] satisfies JsonValue;
+      }
+      if (params.clearOmittedEvents) {
+        for (const sourcePath of CODEX_SESSION_FLAGS_HOOK_SOURCE_PATHS) {
+          hookState[`${sourcePath}:${CODEX_HOOK_KEY_LABEL_BY_NATIVE_EVENT[event]}:0:0`] = {
+            enabled: false,
+          } satisfies JsonValue;
+        }
+      }
+      continue;
+    }
+    const command = params.relay.commandForEvent(event);
+    const timeout = normalizeHookTimeoutSec(params.hookTimeoutSec);
+    config[`hooks.${codexEvent}`] = [
+      {
+        hooks: [
+          {
+            type: "command",
+            command,
+            timeout,
+            async: false,
+            statusMessage: "Klaw native hook relay",
+          },
+        ],
+      },
+    ] satisfies JsonValue;
+    const state = {
+      enabled: true,
+      trusted_hash: codexCommandHookTrustedHash({
+        event,
+        command,
+        timeout,
+        statusMessage: "Klaw native hook relay",
+      }),
+    };
+    for (const sourcePath of CODEX_SESSION_FLAGS_HOOK_SOURCE_PATHS) {
+      hookState[`${sourcePath}:${CODEX_HOOK_KEY_LABEL_BY_NATIVE_EVENT[event]}:0:0`] =
+        state satisfies JsonValue;
+    }
+  }
+  config["hooks.state"] = hookState;
+  return config;
+}
+
+export function buildCodexNativeHookRelayDisabledConfig(): JsonObject {
+  return {
+    "features.hooks": false,
+    "hooks.PreToolUse": [],
+    "hooks.PostToolUse": [],
+    "hooks.PermissionRequest": [],
+    "hooks.Stop": [],
+  };
+}
+
+function normalizeHookTimeoutSec(value: number | undefined): number {
+  return typeof value === "number" && Number.isFinite(value) && value > 0 ? Math.ceil(value) : 5;
+}
+
+function codexCommandHookTrustedHash(params: {
+  event: NativeHookRelayEvent;
+  command: string;
+  timeout: number;
+  statusMessage: string;
+}): string {
+  // Keep the match-all matcher omitted rather than null. Codex app-server
+  // converts JSON null to an empty TOML string before hashing, which changes the
+  // trust identity even though both forms match all tools.
+  const identity = {
+    event_name: CODEX_HOOK_KEY_LABEL_BY_NATIVE_EVENT[params.event],
+    hooks: [
+      {
+        async: false,
+        command: params.command,
+        statusMessage: params.statusMessage,
+        timeout: params.timeout,
+        type: "command",
+      },
+    ],
+  };
+  const hash = createHash("sha256")
+    .update(JSON.stringify(sortJsonValue(identity)))
+    .digest("hex");
+  return `sha256:${hash}`;
+}
+
+function sortJsonValue(value: JsonValue): JsonValue {
+  if (!value || typeof value !== "object") {
+    return value;
+  }
+  if (Array.isArray(value)) {
+    return value.map(sortJsonValue);
+  }
+  const sorted: JsonObject = {};
+  for (const key of Object.keys(value).toSorted()) {
+    sorted[key] = sortJsonValue(value[key]);
+  }
+  return sorted;
+}