engineering-behavior-observatory 0.2.1

package/dist/src/codex.d.ts

@@ -0,0 +1,187 @@
+import type { AskForApproval } from "../contracts/codex-app-server-0.153.4/types/AskForApproval.js";
+import type { SandboxMode } from "../contracts/codex-app-server-0.153.4/types/SandboxMode.js";
+import type { TokenUsageBreakdown } from "../contracts/codex-app-server-0.153.4/types/TokenUsageBreakdown.js";
+import { type ProtocolObservation, type ProtocolProcessResult } from "./process-protocol.js";
+import { type AdapterCoverageReport, type NormalizedDataset } from "./normalization-integrity.js";
+import { type HarnessAdapter, type NormalizationResult, type QualifiedNativeCapture } from "./uniform-events.js";
+export declare const CODEX_APP_SERVER_VERSION = "0.153.4";
+export declare const CODEX_ADAPTER_VERSION = "0.1.0";
+export declare const CODEX_HARNESS = "codex-app-server";
+export declare const CODEX_DEFAULT_SHUTDOWN_GRACE_MS = 2000;
+export type CodexReasoningEffort = "none" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max" | "ultra";
+export type CodexApprovalPolicy = Extract<AskForApproval, string>;
+export type CodexSandbox = SandboxMode;
+export type CodexTelemetrySignal = "logs" | "traces" | "metrics";
+export type CodexAppServerConfiguration = {
+    executable: string;
+    version: typeof CODEX_APP_SERVER_VERSION;
+    provider: "openai";
+    model: string;
+    effort: CodexReasoningEffort;
+    approvalPolicy: CodexApprovalPolicy;
+    sandbox: CodexSandbox;
+    /** Test-only executable prefix; production uses the pinned executable directly. */
+    executableArgs?: readonly string[];
+    telemetry?: {
+        signals: readonly CodexTelemetrySignal[];
+    };
+};
+export type CodexOtlpRecord = {
+    signal: CodexTelemetrySignal;
+    receivedAt: string;
+    contentType?: string;
+    payload?: unknown;
+    raw?: string;
+    parseError?: string;
+};
+export type CodexTelemetryEvidence = {
+    schemaVersion: "ebo.codex-telemetry/v1";
+    attemptId: string;
+    runtime: {
+        executable: string;
+        version: string;
+        adapterVersion: string;
+        userConfiguration: "isolated";
+        localLoginReference: "available" | "unavailable";
+    };
+    effectiveConfiguration: {
+        model: string;
+        provider: "openai";
+        effort: CodexReasoningEffort;
+        approvalPolicy: CodexApprovalPolicy;
+        sandbox: CodexSandbox;
+        workspace: string;
+        environmentKeys: readonly string[];
+        threadStart?: Record<string, unknown>;
+    };
+    telemetry: {
+        receipt: {
+            status: "received" | "missing" | "not-checked";
+            signals: Record<CodexTelemetrySignal, {
+                status: "received" | "missing" | "disabled";
+                count: number;
+            }>;
+        };
+        records: readonly CodexOtlpRecord[];
+        receiverErrors: readonly string[];
+    };
+    usage: {
+        updates: ReadonlyArray<{
+            sequence: number;
+            threadId: string;
+            turnId: string;
+            total: Partial<TokenUsageBreakdown>;
+            last: Partial<TokenUsageBreakdown>;
+            modelContextWindow?: number;
+        }>;
+        final?: {
+            total: Partial<TokenUsageBreakdown>;
+            last: Partial<TokenUsageBreakdown>;
+            modelContextWindow?: number;
+        };
+    };
+};
+export type CodexCaptureGap = {
+    kind: string;
+    detail: string;
+};
+export type CodexAppServerCaptureRequest = {
+    runId: string;
+    attemptId: string;
+    workspacePath: string;
+    prompt: string;
+    configuration: CodexAppServerConfiguration;
+    evidencePath: string;
+    stderrPath?: string;
+    signal?: AbortSignal;
+    shutdownGraceMs?: number;
+    maxLineBytes?: number;
+    maxInMemoryObservations?: number;
+    now?: () => string;
+    registerShutdown?: (shutdown: () => Promise<void>) => void;
+};
+export type CodexAppServerCapture = QualifiedNativeCapture<ProtocolObservation> & {
+    threadId?: string;
+    turnId?: string;
+    terminalStatus?: "completed" | "interrupted" | "failed";
+    terminal?: Record<string, unknown>;
+    history?: Record<string, unknown>;
+    process: ProtocolProcessResult;
+    gaps: readonly CodexCaptureGap[];
+    telemetry: CodexTelemetryEvidence;
+};
+export declare const CODEX_APP_SERVER_CAPABILITIES: {
+    readonly adapterId: "ebo-codex-app-server-v0.153.4";
+    readonly schemaVersion: "ebo.adapter-capability-profile/v1";
+    readonly harness: "codex-app-server";
+    readonly nativeTypes: readonly ["item/completed", "turn/completed", "turn/plan/updated", "thread/compacted", "thread/tokenUsage/updated", "model/rerouted", "hook/completed", "server-request"];
+    readonly families: {
+        readonly message: {
+            readonly status: "partial";
+            readonly detail: "Completed user and agent message items are projected.";
+        };
+        readonly "model-request": {
+            readonly status: "unsupported";
+            readonly detail: "Inference requests are not inferred from turns or model changes.";
+        };
+        readonly tool: {
+            readonly status: "partial";
+            readonly detail: "Only completed native tool items are projected; deltas stay native.";
+        };
+        readonly context: {
+            readonly status: "partial";
+            readonly detail: "Plans and compaction are projected when emitted.";
+        };
+        readonly permission: {
+            readonly status: "partial";
+            readonly detail: "Server requests and unattended decisions stay native; request events are projected.";
+        };
+        readonly delegation: {
+            readonly status: "partial";
+            readonly detail: "Completed exposed collaboration items are projected when present.";
+        };
+        readonly artifact: {
+            readonly status: "partial";
+            readonly detail: "Completed file-change items are projected.";
+        };
+        readonly validation: {
+            readonly status: "unsupported";
+            readonly detail: "Verifier evidence is packaged outside the Codex native normalizer.";
+        };
+        readonly runtime: {
+            readonly status: "partial";
+            readonly detail: "Usage, reroutes, and completed hooks are projected when emitted.";
+        };
+        readonly outcome: {
+            readonly status: "available";
+            readonly detail: "Matching turn/completed is authoritative for turn outcome.";
+        };
+    };
+    readonly evidence: {
+        readonly nativeOrder: {
+            readonly status: "available";
+            readonly detail: "The retained receive/write sequence is one stdio ordering domain.";
+        };
+        readonly nativeTime: {
+            readonly status: "partial";
+            readonly detail: "Item lifecycle timestamps are native; other records retain observation time separately.";
+        };
+        readonly parentage: {
+            readonly status: "partial";
+            readonly detail: "Thread and turn scopes are retained; item relations remain source-specific.";
+        };
+        readonly content: {
+            readonly status: "partial";
+            readonly detail: "Mapped content references retained native payloads without copying bodies.";
+        };
+    };
+};
+export declare function createCodexHarnessAdapter(): HarnessAdapter<CodexAppServerCaptureRequest, ProtocolObservation>;
+/** Drive one owned Codex app-server thread and finish only on its matching turn/completed notification. */
+export declare function captureCodexAppServer(request: CodexAppServerCaptureRequest): Promise<CodexAppServerCapture>;
+export declare function normalizeCodexCapture(capture: QualifiedNativeCapture<ProtocolObservation>): Promise<NormalizationResult>;
+export declare function describeAndValidateCodexDataset(capture: QualifiedNativeCapture<ProtocolObservation>, runtimeVersion?: string): Promise<{
+    dataset: NormalizedDataset;
+    coverage: AdapterCoverageReport;
+}>;
+export declare function writeProtocolLine(stream: NodeJS.WritableStream, message: unknown): Promise<void>;