@gakr-gakr/codex 0.1.0

package/src/app-server/timeout.ts

@@ -0,0 +1,9 @@
+import { withTimeout as withSharedTimeout } from "autobot/plugin-sdk/security-runtime";
+
+export async function withTimeout<T>(
+  promise: Promise<T>,
+  timeoutMs: number,
+  timeoutMessage: string,
+): Promise<T> {
+  return await withSharedTimeout(promise, timeoutMs, { message: timeoutMessage });
+}

package/src/app-server/tool-progress-normalization.ts

@@ -0,0 +1,77 @@
+import {
+  inferToolMetaFromArgs,
+  type EmbeddedRunAttemptParams,
+  type ToolProgressDetailMode,
+} from "autobot/plugin-sdk/agent-harness-runtime";
+import { redactSensitiveFieldValue, redactToolPayloadText } from "autobot/plugin-sdk/logging-core";
+import {
+  isJsonObject,
+  type CodexDynamicToolCallParams,
+  type CodexDynamicToolCallResponse,
+  type JsonValue,
+} from "./protocol.js";
+
+export function resolveCodexToolProgressDetailMode(
+  value: EmbeddedRunAttemptParams["toolProgressDetail"],
+): ToolProgressDetailMode {
+  return value === "raw" ? "raw" : "explain";
+}
+
+export function sanitizeCodexAgentEventValue(
+  value: unknown,
+  seen = new WeakSet<object>(),
+): unknown {
+  if (typeof value === "string") {
+    return redactToolPayloadText(value);
+  }
+  if (Array.isArray(value)) {
+    if (seen.has(value)) {
+      return "[Circular]";
+    }
+    seen.add(value);
+    return value.map((entry) => sanitizeCodexAgentEventValue(entry, seen));
+  }
+  if (value && typeof value === "object") {
+    if (seen.has(value)) {
+      return "[Circular]";
+    }
+    seen.add(value);
+    const out: Record<string, unknown> = {};
+    for (const [key, child] of Object.entries(value as Record<string, unknown>)) {
+      out[key] =
+        typeof child === "string"
+          ? redactSensitiveFieldValue(key, child)
+          : sanitizeCodexAgentEventValue(child, seen);
+    }
+    return out;
+  }
+  return value;
+}
+
+export function sanitizeCodexAgentEventRecord(
+  value: Record<string, unknown>,
+): Record<string, unknown> {
+  return sanitizeCodexAgentEventValue(value) as Record<string, unknown>;
+}
+
+export function sanitizeCodexToolArguments(
+  value: JsonValue | undefined,
+): Record<string, unknown> | undefined {
+  if (!isJsonObject(value)) {
+    return undefined;
+  }
+  return sanitizeCodexAgentEventRecord(value);
+}
+
+export function sanitizeCodexToolResponse(
+  response: CodexDynamicToolCallResponse,
+): Record<string, unknown> {
+  return sanitizeCodexAgentEventRecord(response as unknown as Record<string, unknown>);
+}
+
+export function inferCodexDynamicToolMeta(
+  call: Pick<CodexDynamicToolCallParams, "tool" | "arguments">,
+  detailMode: ToolProgressDetailMode,
+): string | undefined {
+  return inferToolMetaFromArgs(call.tool, call.arguments, { detailMode });
+}

package/src/app-server/trajectory.ts

@@ -0,0 +1,368 @@
+import nodeFs from "node:fs";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { resolveUserPath } from "autobot/plugin-sdk/agent-harness-runtime";
+import type {
+  EmbeddedRunAttemptParams,
+  EmbeddedRunAttemptResult,
+} from "autobot/plugin-sdk/agent-harness-runtime";
+import {
+  appendRegularFile,
+  resolveRegularFileAppendFlags,
+} from "autobot/plugin-sdk/security-runtime";
+import { resolveCodexLocalRuntimeAttribution } from "./local-runtime-attribution.js";
+
+export type CodexTrajectoryRecorder = {
+  filePath: string;
+  recordEvent: (type: string, data?: Record<string, unknown>) => void;
+  flush: () => Promise<void>;
+};
+
+type CodexTrajectoryInit = {
+  attempt: EmbeddedRunAttemptParams;
+  cwd: string;
+  developerInstructions?: string;
+  prompt?: string;
+  tools?: Array<{ name?: string; description?: string; inputSchema?: unknown }>;
+  env?: NodeJS.ProcessEnv;
+};
+
+const SENSITIVE_FIELD_RE = /(?:authorization|cookie|credential|key|password|passwd|secret|token)/iu;
+const PRIVATE_PAYLOAD_FIELD_RE = /(?:image|screenshot|attachment|fileData|dataUri)/iu;
+const AUTHORIZATION_VALUE_RE = /\b(Bearer|Basic)\s+[A-Za-z0-9+/._~=-]{8,}/giu;
+const JWT_VALUE_RE = /\beyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\b/gu;
+const COOKIE_PAIR_RE = /\b([A-Za-z][A-Za-z0-9_.-]{1,64})=([A-Za-z0-9+/._~%=-]{16,})(?=;|\s|$)/gu;
+const TRAJECTORY_RUNTIME_FILE_MAX_BYTES = 50 * 1024 * 1024;
+const TRAJECTORY_RUNTIME_EVENT_MAX_BYTES = 256 * 1024;
+
+type CodexTrajectoryOpenFlagConstants = Pick<
+  typeof nodeFs.constants,
+  "O_APPEND" | "O_CREAT" | "O_TRUNC" | "O_WRONLY"
+> &
+  Partial<Pick<typeof nodeFs.constants, "O_NOFOLLOW">>;
+
+export function resolveCodexTrajectoryAppendFlags(
+  constants: CodexTrajectoryOpenFlagConstants = nodeFs.constants,
+): number {
+  return resolveRegularFileAppendFlags(constants);
+}
+
+export function resolveCodexTrajectoryPointerFlags(
+  constants: CodexTrajectoryOpenFlagConstants = nodeFs.constants,
+): number {
+  const noFollow = constants.O_NOFOLLOW;
+  return (
+    constants.O_CREAT |
+    constants.O_TRUNC |
+    constants.O_WRONLY |
+    (typeof noFollow === "number" ? noFollow : 0)
+  );
+}
+
+async function safeAppendTrajectoryFile(filePath: string, line: string): Promise<void> {
+  await appendRegularFile({
+    filePath,
+    content: line,
+    maxFileBytes: TRAJECTORY_RUNTIME_FILE_MAX_BYTES,
+    rejectSymlinkParents: true,
+  });
+}
+
+function boundedTrajectoryLine(event: Record<string, unknown>): string | undefined {
+  const line = JSON.stringify(event);
+  const bytes = Buffer.byteLength(line, "utf8");
+  if (bytes <= TRAJECTORY_RUNTIME_EVENT_MAX_BYTES) {
+    return `${line}\n`;
+  }
+  const truncated = JSON.stringify({
+    ...event,
+    data: {
+      truncated: true,
+      originalBytes: bytes,
+      limitBytes: TRAJECTORY_RUNTIME_EVENT_MAX_BYTES,
+      reason: "trajectory-event-size-limit",
+    },
+  });
+  if (Buffer.byteLength(truncated, "utf8") <= TRAJECTORY_RUNTIME_EVENT_MAX_BYTES) {
+    return `${truncated}\n`;
+  }
+  return undefined;
+}
+
+function resolveTrajectoryPointerFilePath(sessionFile: string): string {
+  return sessionFile.endsWith(".jsonl")
+    ? `${sessionFile.slice(0, -".jsonl".length)}.trajectory-path.json`
+    : `${sessionFile}.trajectory-path.json`;
+}
+
+function writeTrajectoryPointerBestEffort(params: {
+  filePath: string;
+  sessionFile: string;
+  sessionId: string;
+}): void {
+  const pointerPath = resolveTrajectoryPointerFilePath(params.sessionFile);
+  try {
+    const pointerDir = path.resolve(path.dirname(pointerPath));
+    if (nodeFs.lstatSync(pointerDir).isSymbolicLink()) {
+      return;
+    }
+    try {
+      if (nodeFs.lstatSync(pointerPath).isSymbolicLink()) {
+        return;
+      }
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== "ENOENT") {
+        return;
+      }
+    }
+    const fd = nodeFs.openSync(pointerPath, resolveCodexTrajectoryPointerFlags(), 0o600);
+    try {
+      nodeFs.writeFileSync(
+        fd,
+        `${JSON.stringify(
+          {
+            traceSchema: "autobot-trajectory-pointer",
+            schemaVersion: 1,
+            sessionId: params.sessionId,
+            runtimeFile: params.filePath,
+          },
+          null,
+          2,
+        )}\n`,
+        "utf8",
+      );
+      nodeFs.fchmodSync(fd, 0o600);
+    } finally {
+      nodeFs.closeSync(fd);
+    }
+  } catch {
+    // Pointer files are best-effort; the runtime sidecar itself is authoritative.
+  }
+}
+
+export function createCodexTrajectoryRecorder(
+  params: CodexTrajectoryInit,
+): CodexTrajectoryRecorder | null {
+  const env = params.env ?? process.env;
+  const enabled = parseTrajectoryEnabled(env);
+  if (!enabled) {
+    return null;
+  }
+
+  const filePath = resolveTrajectoryFilePath({
+    env,
+    sessionFile: params.attempt.sessionFile,
+    sessionId: params.attempt.sessionId,
+  });
+  const ready = fs
+    .mkdir(path.dirname(filePath), { recursive: true, mode: 0o700 })
+    .catch(() => undefined);
+  writeTrajectoryPointerBestEffort({
+    filePath,
+    sessionFile: params.attempt.sessionFile,
+    sessionId: params.attempt.sessionId,
+  });
+  let queue = Promise.resolve();
+  let seq = 0;
+  const attribution = resolveCodexLocalRuntimeAttribution(params.attempt);
+
+  return {
+    filePath,
+    recordEvent: (type, data) => {
+      const event = {
+        traceSchema: "autobot-trajectory",
+        schemaVersion: 1,
+        traceId: params.attempt.sessionId,
+        source: "runtime",
+        type,
+        ts: new Date().toISOString(),
+        seq: (seq += 1),
+        sourceSeq: seq,
+        sessionId: params.attempt.sessionId,
+        sessionKey: params.attempt.sessionKey,
+        runId: params.attempt.runId,
+        workspaceDir: params.cwd,
+        provider: attribution.provider,
+        modelId: params.attempt.modelId,
+        modelApi: attribution.api,
+        data: data ? sanitizeValue(data) : undefined,
+      };
+      const line = boundedTrajectoryLine(event);
+      if (!line) {
+        return;
+      }
+      queue = queue
+        .then(() => ready)
+        .then(() => safeAppendTrajectoryFile(filePath, line))
+        .catch(() => undefined);
+    },
+    flush: async () => {
+      await queue;
+    },
+  };
+}
+
+export function recordCodexTrajectoryContext(
+  recorder: CodexTrajectoryRecorder | null,
+  params: CodexTrajectoryInit,
+): void {
+  if (!recorder) {
+    return;
+  }
+  recorder.recordEvent("context.compiled", {
+    systemPrompt: params.developerInstructions,
+    prompt: params.prompt ?? params.attempt.prompt,
+    imagesCount: params.attempt.images?.length ?? 0,
+    tools: toTrajectoryToolDefinitions(params.tools),
+  });
+}
+
+export function recordCodexTrajectoryCompletion(
+  recorder: CodexTrajectoryRecorder | null,
+  params: {
+    attempt: EmbeddedRunAttemptParams;
+    result: EmbeddedRunAttemptResult;
+    threadId: string;
+    turnId: string;
+    timedOut: boolean;
+    yieldDetected?: boolean;
+  },
+): void {
+  if (!recorder) {
+    return;
+  }
+  recorder.recordEvent("model.completed", {
+    threadId: params.threadId,
+    turnId: params.turnId,
+    timedOut: params.timedOut,
+    yieldDetected: params.yieldDetected ?? false,
+    aborted: params.result.aborted,
+    promptError: normalizeCodexTrajectoryError(params.result.promptError),
+    usage: params.result.attemptUsage,
+    assistantTexts: params.result.assistantTexts,
+    messagesSnapshot: params.result.messagesSnapshot,
+  });
+}
+
+function parseTrajectoryEnabled(env: NodeJS.ProcessEnv): boolean {
+  const value = env.AUTOBOT_TRAJECTORY?.trim().toLowerCase();
+  if (value === "1" || value === "true" || value === "yes" || value === "on") {
+    return true;
+  }
+  if (value === "0" || value === "false" || value === "no" || value === "off") {
+    return false;
+  }
+  return true;
+}
+
+function resolveTrajectoryFilePath(params: {
+  env: NodeJS.ProcessEnv;
+  sessionFile: string;
+  sessionId: string;
+}): string {
+  const dirOverride = params.env.AUTOBOT_TRAJECTORY_DIR?.trim();
+  if (dirOverride) {
+    return resolveContainedPath(
+      resolveUserPath(dirOverride),
+      `${safeTrajectorySessionFileName(params.sessionId)}.jsonl`,
+    );
+  }
+  return params.sessionFile.endsWith(".jsonl")
+    ? `${params.sessionFile.slice(0, -".jsonl".length)}.trajectory.jsonl`
+    : `${params.sessionFile}.trajectory.jsonl`;
+}
+
+function safeTrajectorySessionFileName(sessionId: string): string {
+  const safe = sessionId.replaceAll(/[^A-Za-z0-9_-]/g, "_").slice(0, 120);
+  return /[A-Za-z0-9]/u.test(safe) ? safe : "session";
+}
+
+function resolveContainedPath(baseDir: string, fileName: string): string {
+  const resolvedBase = path.resolve(baseDir);
+  const resolvedFile = path.resolve(resolvedBase, fileName);
+  const relative = path.relative(resolvedBase, resolvedFile);
+  if (!relative || relative.startsWith("..") || path.isAbsolute(relative)) {
+    throw new Error("Trajectory file path escaped its configured directory");
+  }
+  return resolvedFile;
+}
+
+function toTrajectoryToolDefinitions(
+  tools: Array<{ name?: string; description?: string; inputSchema?: unknown }> | undefined,
+): Array<{ name: string; description?: string; parameters?: unknown }> | undefined {
+  if (!tools || tools.length === 0) {
+    return undefined;
+  }
+  return tools
+    .flatMap((tool) => {
+      const name = tool.name?.trim();
+      if (!name) {
+        return [];
+      }
+      return [
+        {
+          name,
+          description: tool.description,
+          parameters: sanitizeValue(tool.inputSchema),
+        },
+      ];
+    })
+    .toSorted((left, right) => left.name.localeCompare(right.name));
+}
+
+function sanitizeValue(value: unknown, depth = 0, key = ""): unknown {
+  if (value == null || typeof value === "boolean" || typeof value === "number") {
+    return value;
+  }
+  if (typeof value === "string") {
+    if (SENSITIVE_FIELD_RE.test(key)) {
+      return "<redacted>";
+    }
+    if (value.startsWith("data:") && value.length > 256) {
+      return `<redacted data-uri ${value.slice(0, value.indexOf(",")).length} chars>`;
+    }
+    if (PRIVATE_PAYLOAD_FIELD_RE.test(key) && value.length > 256) {
+      return "<redacted payload>";
+    }
+    const redacted = redactSensitiveString(value);
+    return redacted.length > 20_000 ? `${redacted.slice(0, 20_000)}…` : redacted;
+  }
+  if (depth >= 6) {
+    return "<truncated>";
+  }
+  if (Array.isArray(value)) {
+    return value.slice(0, 100).map((entry) => sanitizeValue(entry, depth + 1, key));
+  }
+  if (typeof value === "object") {
+    const next: Record<string, unknown> = {};
+    for (const [key, child] of Object.entries(value).slice(0, 100)) {
+      next[key] = sanitizeValue(child, depth + 1, key);
+    }
+    return next;
+  }
+  return JSON.stringify(value);
+}
+
+function redactSensitiveString(value: string): string {
+  return value
+    .replace(AUTHORIZATION_VALUE_RE, "$1 <redacted>")
+    .replace(JWT_VALUE_RE, "<redacted-jwt>")
+    .replace(COOKIE_PAIR_RE, "$1=<redacted>");
+}
+
+export function normalizeCodexTrajectoryError(value: unknown): string | null {
+  if (!value) {
+    return null;
+  }
+  if (value instanceof Error) {
+    return value.message;
+  }
+  if (typeof value === "string") {
+    return value;
+  }
+  try {
+    return JSON.stringify(value);
+  } catch {
+    return "Unknown error";
+  }
+}

package/src/app-server/transcript-mirror.ts

@@ -0,0 +1,208 @@
+import { createHash } from "node:crypto";
+import fs from "node:fs/promises";
+import {
+  acquireSessionWriteLock,
+  appendSessionTranscriptMessage,
+  emitSessionTranscriptUpdate,
+  resolveSessionWriteLockOptions,
+  runAgentHarnessBeforeMessageWriteHook,
+  type AgentMessage,
+  type EmbeddedRunAttemptParams,
+  type SessionWriteLockAcquireTimeoutConfig,
+} from "autobot/plugin-sdk/agent-harness-runtime";
+
+type MirroredAgentMessage = Extract<AgentMessage, { role: "user" | "assistant" | "toolResult" }>;
+
+const MIRROR_IDENTITY_META_KEY = "mirrorIdentity" as const;
+
+function normalizeOptionalString(value: string | null | undefined): string | undefined {
+  const normalized = value?.trim();
+  return normalized ? normalized : undefined;
+}
+
+function buildSenderLabel(params: {
+  senderId?: string;
+  senderName?: string;
+  senderUsername?: string;
+  senderE164?: string;
+}): string | undefined {
+  const label = params.senderName ?? params.senderUsername ?? params.senderE164 ?? params.senderId;
+  if (!label) {
+    return undefined;
+  }
+  if (!params.senderId || label.includes(params.senderId)) {
+    return label;
+  }
+  return `${label} (${params.senderId})`;
+}
+
+export function buildCodexUserPromptMessage(params: EmbeddedRunAttemptParams): AgentMessage {
+  const senderId = normalizeOptionalString(params.senderId);
+  const senderName = normalizeOptionalString(params.senderName);
+  const senderUsername = normalizeOptionalString(params.senderUsername);
+  const senderE164 = normalizeOptionalString(params.senderE164);
+  const senderLabel = buildSenderLabel({ senderId, senderName, senderUsername, senderE164 });
+  const sourceChannel = normalizeOptionalString(
+    params.inputProvenance?.sourceChannel ?? params.messageChannel ?? params.messageProvider,
+  );
+  return {
+    role: "user",
+    content: params.prompt,
+    timestamp: Date.now(),
+    ...(params.inputProvenance ? { provenance: params.inputProvenance } : {}),
+    ...(sourceChannel ? { sourceChannel } : {}),
+    ...(senderId ? { senderId } : {}),
+    ...(senderName ? { senderName } : {}),
+    ...(senderUsername ? { senderUsername } : {}),
+    ...(senderE164 ? { senderE164 } : {}),
+    ...(senderLabel ? { senderLabel } : {}),
+  } as AgentMessage;
+}
+
+/**
+ * Tag a message with a stable logical identity for mirror dedupe. Callers
+ * should use a value that is invariant for the same logical message across
+ * re-emits (e.g. `${turnId}:prompt`, `${turnId}:assistant`) but distinct
+ * for genuinely-distinct messages (different turns, different kinds). When
+ * present this identity replaces the role/content fingerprint in the
+ * idempotency key, so the dedupe survives caller-scope rotation without
+ * collapsing distinct same-content turns.
+ */
+export function attachCodexMirrorIdentity<T extends AgentMessage>(message: T, identity: string): T {
+  const record = message as unknown as Record<string, unknown>;
+  const existing = record["__autobot"];
+  const baseMeta =
+    existing && typeof existing === "object" && !Array.isArray(existing)
+      ? (existing as Record<string, unknown>)
+      : {};
+  return {
+    ...record,
+    __autobot: { ...baseMeta, [MIRROR_IDENTITY_META_KEY]: identity },
+  } as unknown as T;
+}
+
+function readMirrorIdentity(message: MirroredAgentMessage): string | undefined {
+  const record = message as unknown as { __autobot?: unknown };
+  const meta = record["__autobot"];
+  if (!meta || typeof meta !== "object" || Array.isArray(meta)) {
+    return undefined;
+  }
+  const id = (meta as Record<string, unknown>)[MIRROR_IDENTITY_META_KEY];
+  return typeof id === "string" && id.length > 0 ? id : undefined;
+}
+
+// Fallback content fingerprint for callers that did not tag the message
+// with a stable mirror identity. Only role and content participate; volatile
+// metadata (timestamps, usage, etc.) is intentionally excluded so the
+// fingerprint survives snapshot reordering inside a fixed scope. Distinct
+// same-content turns are still distinguished by the caller's idempotency
+// scope when callers route through this fallback.
+function fingerprintMirrorMessageContent(message: MirroredAgentMessage): string {
+  const payload = JSON.stringify({ role: message.role, content: message.content });
+  return createHash("sha256").update(payload).digest("hex").slice(0, 16);
+}
+
+function buildMirrorDedupeIdentity(message: MirroredAgentMessage): string {
+  const explicit = readMirrorIdentity(message);
+  if (explicit) {
+    return explicit;
+  }
+  return `${message.role}:${fingerprintMirrorMessageContent(message)}`;
+}
+
+export async function mirrorCodexAppServerTranscript(params: {
+  sessionFile: string;
+  sessionKey?: string;
+  agentId?: string;
+  messages: AgentMessage[];
+  idempotencyScope?: string;
+  config?: SessionWriteLockAcquireTimeoutConfig;
+}): Promise<void> {
+  const messages = params.messages.filter(
+    (message): message is MirroredAgentMessage =>
+      message.role === "user" || message.role === "assistant" || message.role === "toolResult",
+  );
+  if (messages.length === 0) {
+    return;
+  }
+
+  const lock = await acquireSessionWriteLock({
+    sessionFile: params.sessionFile,
+    ...resolveSessionWriteLockOptions(params.config),
+  });
+  try {
+    const existingIdempotencyKeys = await readTranscriptIdempotencyKeys(params.sessionFile);
+    for (const message of messages) {
+      const dedupeIdentity = buildMirrorDedupeIdentity(message);
+      const idempotencyKey = params.idempotencyScope
+        ? `${params.idempotencyScope}:${dedupeIdentity}`
+        : undefined;
+      if (idempotencyKey && existingIdempotencyKeys.has(idempotencyKey)) {
+        continue;
+      }
+      const transcriptMessage = {
+        ...message,
+        ...(idempotencyKey ? { idempotencyKey } : {}),
+      } as AgentMessage;
+      const nextMessage = runAgentHarnessBeforeMessageWriteHook({
+        message: transcriptMessage,
+        agentId: params.agentId,
+        sessionKey: params.sessionKey,
+      });
+      if (!nextMessage) {
+        continue;
+      }
+      const messageToAppend = (
+        idempotencyKey
+          ? {
+              ...(nextMessage as unknown as Record<string, unknown>),
+              idempotencyKey,
+            }
+          : nextMessage
+      ) as AgentMessage;
+      await appendSessionTranscriptMessage({
+        transcriptPath: params.sessionFile,
+        message: messageToAppend,
+        config: params.config,
+      });
+      if (idempotencyKey) {
+        existingIdempotencyKeys.add(idempotencyKey);
+      }
+    }
+  } finally {
+    await lock.release();
+  }
+
+  if (params.sessionKey) {
+    emitSessionTranscriptUpdate({ sessionFile: params.sessionFile, sessionKey: params.sessionKey });
+  } else {
+    emitSessionTranscriptUpdate(params.sessionFile);
+  }
+}
+
+async function readTranscriptIdempotencyKeys(sessionFile: string): Promise<Set<string>> {
+  const keys = new Set<string>();
+  let raw: string;
+  try {
+    raw = await fs.readFile(sessionFile, "utf8");
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== "ENOENT") {
+      throw error;
+    }
+    return keys;
+  }
+  for (const line of raw.split(/\r?\n/)) {
+    if (!line.trim()) {
+      continue;
+    }
+    try {
+      const parsed = JSON.parse(line) as { message?: { idempotencyKey?: unknown } };
+      if (typeof parsed.message?.idempotencyKey === "string") {
+        keys.add(parsed.message.idempotencyKey);
+      }
+    } catch {
+      continue;
+    }
+  }
+  return keys;
+}