@kodelyth/codex 2026.5.40 → 2026.5.42

package/src/app-server/image-payload-sanitizer.test.ts

@@ -0,0 +1,49 @@
+import { describe, expect, it } from "vitest";
+import {
+  invalidInlineImageText,
+  sanitizeCodexHistoryImagePayloads,
+  sanitizeInlineImageDataUrl,
+} from "./image-payload-sanitizer.js";
+
+const PNG_1X1 =
+  "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR4nGNgYAAAAAMAASsJTYQAAAAASUVORK5CYII=";
+
+describe("Codex app-server image payload sanitizer", () => {
+  it("drops malformed data URL image payloads", () => {
+    expect(sanitizeInlineImageDataUrl("data:image/jpeg;base64,not base64!")).toBeUndefined();
+  });
+
+  it("canonicalizes valid data URL images with sniffed MIME type", () => {
+    expect(sanitizeInlineImageDataUrl(`data:image/jpeg;base64,\n${PNG_1X1}`)).toBe(
+      `data:image/png;base64,${PNG_1X1}`,
+    );
+  });
+
+  it("formats the text replacement used for invalid images", () => {
+    expect(invalidInlineImageText("codex user input")).toContain("invalid inline image data");
+  });
+
+  it("scrubs invalid image blocks from mirrored history values", () => {
+    expect(
+      sanitizeCodexHistoryImagePayloads(
+        [
+          {
+            role: "toolResult",
+            content: [{ type: "image", mimeType: "image/jpeg", data: "not base64!" }],
+          },
+        ],
+        "codex mirrored history",
+      ),
+    ).toEqual([
+      {
+        role: "toolResult",
+        content: [
+          {
+            type: "text",
+            text: "[codex mirrored history] omitted image payload: invalid inline image data",
+          },
+        ],
+      },
+    ]);
+  });
+});

package/src/app-server/image-payload-sanitizer.ts

@@ -0,0 +1,167 @@
+const DATA_URL_PREFIX = "data:";
+const IMAGE_OMITTED_TEXT = "omitted image payload: invalid inline image data";
+
+function startsWithDataUrl(value: string): boolean {
+  return value.slice(0, DATA_URL_PREFIX.length).toLowerCase() === DATA_URL_PREFIX;
+}
+
+function canonicalizeBase64(base64: string): string | undefined {
+  let cleaned = "";
+  let padding = 0;
+  let sawPadding = false;
+  for (let i = 0; i < base64.length; i += 1) {
+    const code = base64.charCodeAt(i);
+    if (code <= 0x20) {
+      continue;
+    }
+    if (code === 0x3d) {
+      padding += 1;
+      if (padding > 2) {
+        return undefined;
+      }
+      sawPadding = true;
+      cleaned += "=";
+      continue;
+    }
+    const isBase64DataChar =
+      (code >= 0x41 && code <= 0x5a) ||
+      (code >= 0x61 && code <= 0x7a) ||
+      (code >= 0x30 && code <= 0x39) ||
+      code === 0x2b ||
+      code === 0x2f;
+    if (sawPadding || !isBase64DataChar) {
+      return undefined;
+    }
+    cleaned += base64[i];
+  }
+  if (!cleaned || cleaned.length % 4 !== 0) {
+    return undefined;
+  }
+  return cleaned;
+}
+
+function sniffImageMime(buffer: Buffer): string | undefined {
+  if (
+    buffer.length >= 8 &&
+    buffer[0] === 0x89 &&
+    buffer[1] === 0x50 &&
+    buffer[2] === 0x4e &&
+    buffer[3] === 0x47 &&
+    buffer[4] === 0x0d &&
+    buffer[5] === 0x0a &&
+    buffer[6] === 0x1a &&
+    buffer[7] === 0x0a
+  ) {
+    return "image/png";
+  }
+  if (buffer.length >= 3 && buffer[0] === 0xff && buffer[1] === 0xd8 && buffer[2] === 0xff) {
+    return "image/jpeg";
+  }
+  if (
+    buffer.length >= 12 &&
+    buffer.subarray(0, 4).toString("ascii") === "RIFF" &&
+    buffer.subarray(8, 12).toString("ascii") === "WEBP"
+  ) {
+    return "image/webp";
+  }
+  if (
+    buffer.length >= 6 &&
+    (buffer.subarray(0, 6).toString("ascii") === "GIF87a" ||
+      buffer.subarray(0, 6).toString("ascii") === "GIF89a")
+  ) {
+    return "image/gif";
+  }
+  return undefined;
+}
+
+export function sanitizeInlineImageDataUrl(imageUrl: string): string | undefined {
+  if (!startsWithDataUrl(imageUrl)) {
+    return imageUrl;
+  }
+  const commaIndex = imageUrl.indexOf(",");
+  if (commaIndex < 0) {
+    return undefined;
+  }
+
+  const metadata = imageUrl.slice(DATA_URL_PREFIX.length, commaIndex);
+  const payload = imageUrl.slice(commaIndex + 1);
+  const metadataParts = metadata.split(";").map((part) => part.trim());
+  const declaredMimeType = metadataParts[0]?.toLowerCase();
+  if (!declaredMimeType?.startsWith("image/")) {
+    return undefined;
+  }
+  if (!metadataParts.slice(1).some((part) => part.toLowerCase() === "base64")) {
+    return undefined;
+  }
+
+  const canonicalPayload = canonicalizeBase64(payload);
+  if (!canonicalPayload) {
+    return undefined;
+  }
+  const sniffedMimeType = sniffImageMime(Buffer.from(canonicalPayload, "base64"));
+  if (!sniffedMimeType) {
+    return undefined;
+  }
+  return `data:${sniffedMimeType};base64,${canonicalPayload}`;
+}
+
+export function invalidInlineImageText(label: string): string {
+  return `[${label}] ${IMAGE_OMITTED_TEXT}`;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return Boolean(value && typeof value === "object" && !Array.isArray(value));
+}
+
+function sanitizeImageContentRecord(
+  record: Record<string, unknown>,
+  label: string,
+): Record<string, unknown> | undefined {
+  if (record.type === "image" && typeof record.data === "string") {
+    const mimeType = typeof record.mimeType === "string" ? record.mimeType : "image/png";
+    const imageUrl = sanitizeInlineImageDataUrl(`data:${mimeType};base64,${record.data}`);
+    if (!imageUrl) {
+      return { type: "text", text: invalidInlineImageText(label) };
+    }
+    const commaIndex = imageUrl.indexOf(",");
+    const metadata = imageUrl.slice(DATA_URL_PREFIX.length, commaIndex);
+    const mime = metadata.split(";")[0] ?? mimeType;
+    return { ...record, mimeType: mime, data: imageUrl.slice(commaIndex + 1) };
+  }
+
+  if (record.type === "inputImage" && typeof record.imageUrl === "string") {
+    const imageUrl = sanitizeInlineImageDataUrl(record.imageUrl);
+    return imageUrl
+      ? { ...record, imageUrl }
+      : { type: "inputText", text: invalidInlineImageText(label) };
+  }
+
+  if (record.type === "input_image" && typeof record.image_url === "string") {
+    const imageUrl = sanitizeInlineImageDataUrl(record.image_url);
+    return imageUrl
+      ? { ...record, image_url: imageUrl }
+      : { type: "input_text", text: invalidInlineImageText(label) };
+  }
+
+  return undefined;
+}
+
+export function sanitizeCodexHistoryImagePayloads<T>(value: T, label: string): T {
+  if (Array.isArray(value)) {
+    return value.map((entry) => sanitizeCodexHistoryImagePayloads(entry, label)) as T;
+  }
+  if (!isRecord(value)) {
+    return value;
+  }
+
+  const imageRecord = sanitizeImageContentRecord(value, label);
+  if (imageRecord) {
+    return imageRecord as T;
+  }
+
+  const next: Record<string, unknown> = {};
+  for (const [key, child] of Object.entries(value)) {
+    next[key] = sanitizeCodexHistoryImagePayloads(child, label);
+  }
+  return next as T;
+}

package/src/app-server/klaw-owned-tool-runtime-contract.test.ts

@@ -0,0 +1,456 @@
+import type { AnyAgentTool } from "klaw/plugin-sdk/agent-harness";
+import { wrapToolWithBeforeToolCallHook } from "klaw/plugin-sdk/agent-harness-runtime";
+import {
+  installCodexToolResultMiddleware,
+  installKlawOwnedToolHooks,
+  mediaToolResult,
+  resetKlawOwnedToolHooks,
+  textToolResult,
+} from "klaw/plugin-sdk/agent-runtime-test-contracts";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { createCodexDynamicToolBridge } from "./dynamic-tools.js";
+
+function createContractTool(overrides: Partial<AnyAgentTool>): AnyAgentTool {
+  return {
+    name: "exec",
+    description: "Run a command.",
+    parameters: { type: "object", properties: {} },
+    execute: vi.fn(),
+    ...overrides,
+  } as unknown as AnyAgentTool;
+}
+
+function requireRecord(value: unknown, label: string): Record<string, unknown> {
+  if (typeof value !== "object" || value === null) {
+    throw new Error(`${label} was not an object`);
+  }
+  return value as Record<string, unknown>;
+}
+
+function expectRecordFields(record: Record<string, unknown>, fields: Record<string, unknown>) {
+  for (const [key, value] of Object.entries(fields)) {
+    expect(record[key]).toEqual(value);
+  }
+}
+
+function requireMockCall(mock: unknown, index: number, label: string): unknown[] {
+  const calls = (mock as { mock?: { calls?: unknown[][] } }).mock?.calls;
+  expect(Array.isArray(calls)).toBe(true);
+  if (!Array.isArray(calls)) {
+    throw new Error(`${label} did not expose mock calls`);
+  }
+  const call = calls[index];
+  if (!call) {
+    throw new Error(`missing ${label} call ${index + 1}`);
+  }
+  return call;
+}
+
+function expectHookContext(value: unknown, fields: Record<string, unknown>) {
+  expectRecordFields(requireRecord(value, "hook context"), fields);
+}
+
+function expectExecuteCall(execute: unknown, callId: string, params: Record<string, unknown>) {
+  const call = requireMockCall(execute, 0, "execute");
+  expect(call[0]).toBe(callId);
+  expect(call[1]).toEqual(params);
+  expect(call[2]).toBeInstanceOf(AbortSignal);
+  expect(call[3]).toBeUndefined();
+}
+
+function expectBeforeToolCall(
+  hooks: { beforeToolCall: unknown },
+  eventFields: Record<string, unknown>,
+  contextFields: Record<string, unknown>,
+) {
+  const call = requireMockCall(hooks.beforeToolCall, 0, "before_tool_call");
+  expectRecordFields(requireRecord(call[0], "before_tool_call event"), eventFields);
+  expectHookContext(call[1], contextFields);
+}
+
+function expectAfterToolCall(
+  hooks: { afterToolCall: unknown },
+  eventFields: Record<string, unknown>,
+  contextFields: Record<string, unknown>,
+) {
+  const call = requireMockCall(hooks.afterToolCall, 0, "after_tool_call");
+  expectRecordFields(requireRecord(call[0], "after_tool_call event"), eventFields);
+  expectHookContext(call[1], contextFields);
+}
+
+describe("Klaw-owned tool runtime contract — Codex app-server adapter", () => {
+  afterEach(() => {
+    resetKlawOwnedToolHooks();
+  });
+
+  it("wraps unwrapped dynamic tools with before/after tool hooks", async () => {
+    const adjustedParams = { mode: "safe" };
+    const mergedParams = { command: "pwd", mode: "safe" };
+    const hooks = installKlawOwnedToolHooks({ adjustedParams });
+    const execute = vi.fn(async () => textToolResult("done", { ok: true }));
+    const bridge = createCodexDynamicToolBridge({
+      tools: [createContractTool({ name: "exec", execute })],
+      signal: new AbortController().signal,
+      hookContext: {
+        agentId: "agent-1",
+        sessionId: "session-1",
+        sessionKey: "agent:agent-1:session-1",
+        runId: "run-contract",
+      },
+    });
+
+    const result = await bridge.handleToolCall({
+      threadId: "thread-1",
+      turnId: "turn-1",
+      callId: "call-contract",
+      namespace: null,
+      tool: "exec",
+      arguments: { command: "pwd" },
+    });
+
+    expect(result).toEqual({
+      success: true,
+      contentItems: [{ type: "inputText", text: "done" }],
+    });
+    expectBeforeToolCall(
+      hooks,
+      {
+        toolName: "exec",
+        toolCallId: "call-contract",
+        runId: "run-contract",
+        params: { command: "pwd" },
+      },
+      {
+        agentId: "agent-1",
+        sessionId: "session-1",
+        sessionKey: "agent:agent-1:session-1",
+        runId: "run-contract",
+        toolCallId: "call-contract",
+      },
+    );
+    expectExecuteCall(execute, "call-contract", mergedParams);
+    await vi.waitFor(() => {
+      const call = requireMockCall(hooks.afterToolCall, 0, "after_tool_call");
+      const event = requireRecord(call[0], "after_tool_call event");
+      expectRecordFields(event, {
+        toolName: "exec",
+        toolCallId: "call-contract",
+        params: mergedParams,
+      });
+      expectRecordFields(requireRecord(event.result, "after_tool_call result"), {
+        content: [{ type: "text", text: "done" }],
+        details: { ok: true },
+      });
+      expectHookContext(call[1], {
+        agentId: "agent-1",
+        sessionId: "session-1",
+        sessionKey: "agent:agent-1:session-1",
+        runId: "run-contract",
+        toolCallId: "call-contract",
+      });
+    });
+  });
+
+  it("runs tool_result middleware before after_tool_call observes the result", async () => {
+    const adjustedParams = { mode: "safe" };
+    const mergedParams = { command: "status", mode: "safe" };
+    const hooks = installKlawOwnedToolHooks({ adjustedParams });
+    const middleware = installCodexToolResultMiddleware((event) => {
+      const eventRecord = requireRecord(event, "tool_result middleware event");
+      expectRecordFields(eventRecord, {
+        toolName: "exec",
+        toolCallId: "call-middleware",
+        args: { command: "status" },
+      });
+      expectRecordFields(requireRecord(eventRecord.result, "tool_result middleware result"), {
+        content: [{ type: "text", text: "raw output" }],
+        details: { stage: "execute" },
+      });
+      return textToolResult("compacted output", { stage: "middleware" });
+    });
+    const execute = vi.fn(async () => textToolResult("raw output", { stage: "execute" }));
+    const bridge = createCodexDynamicToolBridge({
+      tools: [createContractTool({ name: "exec", execute })],
+      signal: new AbortController().signal,
+      hookContext: {
+        agentId: "agent-1",
+        sessionId: "session-1",
+        sessionKey: "agent:agent-1:session-1",
+        runId: "run-middleware",
+      },
+    });
+
+    const result = await bridge.handleToolCall({
+      threadId: "thread-1",
+      turnId: "turn-1",
+      callId: "call-middleware",
+      namespace: null,
+      tool: "exec",
+      arguments: { command: "status" },
+    });
+
+    expect(result).toEqual({
+      success: true,
+      contentItems: [{ type: "inputText", text: "compacted output" }],
+    });
+    expectExecuteCall(execute, "call-middleware", mergedParams);
+    expect(middleware.middleware).toHaveBeenCalledTimes(1);
+    await vi.waitFor(() => {
+      const call = requireMockCall(hooks.afterToolCall, 0, "after_tool_call");
+      const event = requireRecord(call[0], "after_tool_call event");
+      expectRecordFields(event, {
+        toolName: "exec",
+        toolCallId: "call-middleware",
+        params: mergedParams,
+      });
+      expectRecordFields(requireRecord(event.result, "after_tool_call result"), {
+        content: [{ type: "text", text: "compacted output" }],
+        details: { stage: "middleware" },
+      });
+      expectHookContext(call[1], {
+        runId: "run-middleware",
+        toolCallId: "call-middleware",
+      });
+    });
+  });
+
+  it("fails closed when before_tool_call blocks a dynamic tool", async () => {
+    const hooks = installKlawOwnedToolHooks({ blockReason: "blocked by policy" });
+    const execute = vi.fn(async () => textToolResult("should not run"));
+    const bridge = createCodexDynamicToolBridge({
+      tools: [createContractTool({ name: "message", execute })],
+      signal: new AbortController().signal,
+      hookContext: { runId: "run-blocked" },
+    });
+
+    const result = await bridge.handleToolCall({
+      threadId: "thread-1",
+      turnId: "turn-1",
+      callId: "call-blocked",
+      namespace: null,
+      tool: "message",
+      arguments: {
+        action: "send",
+        text: "blocked",
+        provider: "telegram",
+        to: "chat-1",
+      },
+    });
+
+    expect(result).toEqual({
+      success: false,
+      contentItems: [{ type: "inputText", text: "blocked by policy" }],
+    });
+    expect(execute).not.toHaveBeenCalled();
+    expect(bridge.telemetry.didSendViaMessagingTool).toBe(false);
+    await vi.waitFor(() => {
+      const call = requireMockCall(hooks.afterToolCall, 0, "after_tool_call");
+      const event = requireRecord(call[0], "after_tool_call event");
+      expectRecordFields(event, {
+        toolName: "message",
+        toolCallId: "call-blocked",
+        params: {
+          action: "send",
+          text: "blocked",
+          provider: "telegram",
+          to: "chat-1",
+        },
+      });
+      expectRecordFields(requireRecord(event.result, "after_tool_call result"), {
+        content: [{ type: "text", text: "blocked by policy" }],
+        details: {
+          status: "blocked",
+          deniedReason: "plugin-before-tool-call",
+          reason: "blocked by policy",
+        },
+      });
+      expectHookContext(call[1], {
+        runId: "run-blocked",
+        toolCallId: "call-blocked",
+      });
+    });
+  });
+
+  it("reports dynamic tool execution errors through after_tool_call", async () => {
+    const adjustedParams = { timeoutSec: 1 };
+    const mergedParams = { command: "false", timeoutSec: 1 };
+    const hooks = installKlawOwnedToolHooks({ adjustedParams });
+    const execute = vi.fn(async () => {
+      throw new Error("tool failed");
+    });
+    const bridge = createCodexDynamicToolBridge({
+      tools: [createContractTool({ name: "exec", execute })],
+      signal: new AbortController().signal,
+      hookContext: { runId: "run-error" },
+    });
+
+    const result = await bridge.handleToolCall({
+      threadId: "thread-1",
+      turnId: "turn-1",
+      callId: "call-error",
+      namespace: null,
+      tool: "exec",
+      arguments: { command: "false" },
+    });
+
+    expect(result).toEqual({
+      success: false,
+      contentItems: [{ type: "inputText", text: "tool failed" }],
+    });
+    expectExecuteCall(execute, "call-error", mergedParams);
+    await vi.waitFor(() => {
+      expectAfterToolCall(
+        hooks,
+        {
+          toolName: "exec",
+          toolCallId: "call-error",
+          params: mergedParams,
+          error: "tool failed",
+        },
+        {
+          runId: "run-error",
+          toolCallId: "call-error",
+        },
+      );
+    });
+  });
+
+  it("records successful Codex messaging text, media, and target telemetry", async () => {
+    const hooks = installKlawOwnedToolHooks();
+    const execute = vi.fn(async () => textToolResult("Sent."));
+    const bridge = createCodexDynamicToolBridge({
+      tools: [createContractTool({ name: "message", execute })],
+      signal: new AbortController().signal,
+      hookContext: { runId: "run-message" },
+    });
+
+    const result = await bridge.handleToolCall({
+      threadId: "thread-1",
+      turnId: "turn-1",
+      callId: "call-message",
+      namespace: null,
+      tool: "message",
+      arguments: {
+        action: "send",
+        text: "hello from Codex",
+        mediaUrl: "/tmp/codex-reply.png",
+        provider: "telegram",
+        to: "chat-1",
+        threadId: "thread-ts-1",
+      },
+    });
+
+    expect(result).toEqual({
+      success: true,
+      contentItems: [{ type: "inputText", text: "Sent." }],
+    });
+    expectRecordFields(requireRecord(bridge.telemetry, "bridge telemetry"), {
+      didSendViaMessagingTool: true,
+      messagingToolSentTexts: ["hello from Codex"],
+      messagingToolSentMediaUrls: ["/tmp/codex-reply.png"],
+    });
+    expect(bridge.telemetry.messagingToolSentTargets).toEqual([
+      {
+        tool: "message",
+        provider: "telegram",
+        to: "chat-1",
+        threadId: "thread-ts-1",
+        text: "hello from Codex",
+        mediaUrls: ["/tmp/codex-reply.png"],
+      },
+    ]);
+    await vi.waitFor(() => {
+      const call = requireMockCall(hooks.afterToolCall, 0, "after_tool_call");
+      const event = requireRecord(call[0], "after_tool_call event");
+      expectRecordFields(event, {
+        toolName: "message",
+        toolCallId: "call-message",
+      });
+      expectRecordFields(requireRecord(event.params, "after_tool_call params"), {
+        text: "hello from Codex",
+        mediaUrl: "/tmp/codex-reply.png",
+      });
+      expectHookContext(call[1], {
+        runId: "run-message",
+        toolCallId: "call-message",
+      });
+    });
+  });
+
+  it("records successful Codex media artifacts from tool results", async () => {
+    const hooks = installKlawOwnedToolHooks();
+    const execute = vi.fn(async () =>
+      mediaToolResult("Generated media reply.", "/tmp/reply.opus", true),
+    );
+    const bridge = createCodexDynamicToolBridge({
+      tools: [createContractTool({ name: "tts", execute })],
+      signal: new AbortController().signal,
+      hookContext: { runId: "run-media" },
+    });
+
+    const result = await bridge.handleToolCall({
+      threadId: "thread-1",
+      turnId: "turn-1",
+      callId: "call-media",
+      namespace: null,
+      tool: "tts",
+      arguments: { text: "hello" },
+    });
+
+    expect(result).toEqual({
+      success: true,
+      contentItems: [{ type: "inputText", text: "Generated media reply." }],
+    });
+    expect(bridge.telemetry.toolMediaUrls).toEqual(["/tmp/reply.opus"]);
+    expect(bridge.telemetry.toolAudioAsVoice).toBe(true);
+    await vi.waitFor(() => {
+      const call = requireMockCall(hooks.afterToolCall, 0, "after_tool_call");
+      const event = requireRecord(call[0], "after_tool_call event");
+      expectRecordFields(event, {
+        toolName: "tts",
+        toolCallId: "call-media",
+      });
+      const resultRecord = requireRecord(event.result, "after_tool_call result");
+      const details = requireRecord(resultRecord.details, "after_tool_call result details");
+      expectRecordFields(requireRecord(details.media, "media result details"), {
+        mediaUrl: "/tmp/reply.opus",
+        audioAsVoice: true,
+      });
+      expectHookContext(call[1], {
+        runId: "run-media",
+        toolCallId: "call-media",
+      });
+    });
+  });
+
+  it("does not double-wrap dynamic tools that already have before_tool_call", async () => {
+    const adjustedParams = { mode: "safe" };
+    const mergedParams = { command: "pwd", mode: "safe" };
+    const hooks = installKlawOwnedToolHooks({ adjustedParams });
+    const execute = vi.fn(async () => textToolResult("done"));
+    const tool = wrapToolWithBeforeToolCallHook(createContractTool({ name: "exec", execute }), {
+      runId: "run-wrapped",
+    });
+    const bridge = createCodexDynamicToolBridge({
+      tools: [tool],
+      signal: new AbortController().signal,
+      hookContext: { runId: "run-wrapped" },
+    });
+
+    const result = await bridge.handleToolCall({
+      threadId: "thread-1",
+      turnId: "turn-1",
+      callId: "call-wrapped",
+      namespace: null,
+      tool: "exec",
+      arguments: { command: "pwd" },
+    });
+
+    expect(result).toEqual({
+      success: true,
+      contentItems: [{ type: "inputText", text: "done" }],
+    });
+    expect(hooks.beforeToolCall).toHaveBeenCalledTimes(1);
+    expectExecuteCall(execute, "call-wrapped", mergedParams);
+  });
+});