openclaw/extensions/codex/test-api.ts

/**
 * Test-only helpers for producing Codex app-server prompt snapshots and dynamic
 * tool specs without starting a live app-server.
 */
import {
  isSubagentSessionKey,
  type AnyAgentTool,
  type EmbeddedRunAttemptParamsV2 as EmbeddedRunAttemptParams,
} from "openclaw/plugin-sdk/agent-harness-runtime";
import type { PluginRuntime } from "openclaw/plugin-sdk/plugin-runtime";
import {
  type CodexAppServerRuntimeOptions,
  resolveCodexAppServerRuntimeOptions,
  type CodexPluginConfig,
} from "./src/app-server/config.js";
import { filterCodexDynamicTools } from "./src/app-server/dynamic-tool-profile.js";
import { createCodexDynamicToolBridge } from "./src/app-server/dynamic-tools.js";
import {
  flattenCodexDynamicToolFunctions,
  type CodexDynamicToolSpec,
  type JsonObject,
} from "./src/app-server/protocol.js";
import {
  buildDeveloperInstructions,
  buildThreadResumeParams,
  buildThreadStartParams,
  buildTurnStartParams,
} from "./src/app-server/thread-lifecycle.js";
import { buildCodexParentLocalInstructions } from "./src/app-server/turn-params.js";

export { CODEX_APP_SERVER_VERSION } from "./src/app-server/version.js";

/** Keeps host integration tests on the plugin's test boundary without exposing runtime internals. */
export async function createCodexSessionInitializationFixtureForTest(params: {
  runtime: PluginRuntime;
  workspaceDir: string;
}) {
  // Snapshot scripts also load this barrel outside Vitest; load its test fixture only on demand.
  const { createCodexSessionInitializationFixture } =
    await import("./src/app-server/session-initialization.test-support.js");
  return await createCodexSessionInitializationFixture(params);
}

type CodexHarnessPromptSnapshot = {
  developerInstructions: string;
  parentLocalInstructions: string | null;
  threadStartParams: ReturnType<typeof buildThreadStartParams>;
  threadResumeParams: ReturnType<typeof buildThreadResumeParams>;
  turnStartParams: ReturnType<typeof buildTurnStartParams>;
};

/** Resolves deterministic app-server options for prompt snapshot tests. */
export function resolveCodexPromptSnapshotAppServerOptions(
  pluginConfig?: unknown,
): CodexAppServerRuntimeOptions {
  return resolveCodexAppServerRuntimeOptions({
    pluginConfig,
    env: {},
    requirementsToml: null,
  });
}

/** Builds thread/resume/turn prompt payload snapshots for a Codex harness attempt. */
export function buildCodexHarnessPromptSnapshot(params: {
  attempt: EmbeddedRunAttemptParams;
  cwd: string;
  threadId: string;
  dynamicTools: CodexDynamicToolSpec[];
  appServer: CodexAppServerRuntimeOptions;
  config?: JsonObject;
  promptText?: string;
  developerInstructionAdditions?: string;
  turnScopedDeveloperInstructions?: string;
}): CodexHarnessPromptSnapshot {
  const developerInstructions = joinPresentSections(
    buildDeveloperInstructions(params.attempt, {
      dynamicTools: params.dynamicTools,
    }),
    params.developerInstructionAdditions,
  );
  return {
    developerInstructions,
    parentLocalInstructions: buildCodexParentLocalInstructions(params.attempt, {
      turnScopedDeveloperInstructions: params.turnScopedDeveloperInstructions,
    }),
    threadStartParams: buildThreadStartParams(params.attempt, {
      cwd: params.cwd,
      dynamicTools: params.dynamicTools,
      appServer: params.appServer,
      developerInstructions,
      config: params.config,
    }),
    threadResumeParams: buildThreadResumeParams(params.attempt, {
      threadId: params.threadId,
      appServer: params.appServer,
      developerInstructions,
      config: params.config,
    }),
    turnStartParams: buildTurnStartParams(params.attempt, {
      threadId: params.threadId,
      cwd: params.cwd,
      appServer: params.appServer,
      promptText: params.promptText,
      turnScopedDeveloperInstructions: params.turnScopedDeveloperInstructions,
      parentLocalEgress: true,
      messageToolAvailable: flattenCodexDynamicToolFunctions(params.dynamicTools).some(
        (tool) => tool.name === "message",
      ),
      requireExplicitMessageTarget:
        params.attempt.requireExplicitMessageTarget ??
        isSubagentSessionKey(params.attempt.sessionKey),
      sessionStatusAvailable: flattenCodexDynamicToolFunctions(params.dynamicTools).some(
        (tool) => tool.name === "session_status",
      ),
    }),
  };
}

function joinPresentSections(...sections: Array<string | undefined>): string {
  return sections.filter((section): section is string => Boolean(section?.trim())).join("\n\n");
}

/** Converts harness tools into Codex dynamic-tool specs for prompt snapshot tests. */
export function createCodexDynamicToolSpecsForPromptSnapshot(params: {
  tools: AnyAgentTool[];
  pluginConfig?: Pick<CodexPluginConfig, "codexDynamicToolsLoading" | "codexDynamicToolsExclude">;
  directToolNames?: Iterable<string>;
}): CodexDynamicToolSpec[] {
  const filteredTools = filterCodexDynamicTools(params.tools, params.pluginConfig ?? {});
  return createCodexDynamicToolBridge({
    tools: filteredTools,
    signal: new AbortController().signal,
    loading: params.pluginConfig?.codexDynamicToolsLoading ?? "searchable",
    directToolNames: params.directToolNames,
  }).specs;
}
export { createCanonicalForkFixture as createCanonicalForkFixtureForTest } from "./src/app-server/canonical-fork.test-support.js";