@tangle-network/sdk-provider-codex 0.0.0-stage → 0.4.1

package/LICENSE

@@ -0,0 +1,11 @@
+Copyright (c) 2025 Tangle Network
+
+All rights reserved.
+
+This software and associated documentation files (the "Software") are proprietary
+and confidential. No part of this Software may be reproduced, distributed, or
+transmitted in any form or by any means, including photocopying, recording, or
+other electronic or mechanical methods, without the prior written permission of
+Tangle Network.
+
+For licensing inquiries, contact: hello@tangle.tools

package/dist/index.d.mts

@@ -0,0 +1,274 @@
+import { AgentExecutionInput, AgentExecutionResult, BackendCapabilities, CliAuthFile, InteractionResponse, McpConfig, SdkHostServices, StreamEvent } from "@tangle-network/agent-interface";
+import * as _$_tangle_network_sdk_cli_runner0 from "@tangle-network/sdk-cli-runner";
+import { RpcBridge, StreamParserConfig } from "@tangle-network/sdk-cli-runner";
+import { CliExecArgs, CliProviderAdapterBase, CliProviderConfig, CliProviderOptions, CliTurnProcess, CliTurnSpawn, ExecutionState, HarnessId, PreparedAttachment, WorkspacePlanApplication } from "@tangle-network/sdk-provider-cli-base";
+
+//#region src/app-server-protocol.d.ts
+type NativeMcp = {
+  enabled?: boolean;
+  url?: string;
+  command?: string;
+  args?: string[];
+  env?: Record<string, string>;
+  env_vars?: string[];
+  http_headers?: Record<string, string>;
+  env_http_headers?: Record<string, string>;
+  [key: string]: unknown;
+};
+//#endregion
+//#region src/types.d.ts
+/** Codex accepts an explicit OpenAI API key or CLI-managed ChatGPT OAuth. */
+type CodexAuthMode = "api-key" | "oauth";
+interface CodexConfig extends CliProviderConfig {
+  /**
+   * Authentication mode.
+   * - "api-key": Use apiKey or OPENAI_API_KEY env var
+   * - "oauth": Use CLI-managed OAuth (for ChatGPT Plus/Pro subscriptions)
+   * Default: "api-key" if apiKey is provided, otherwise "oauth"
+   */
+  authMode?: CodexAuthMode;
+  /**
+   * Sandbox mode when bypassPermissions is false.
+   * Options: "read-only", "workspace-write", "danger-full-access"
+   */
+  sandboxMode?: "read-only" | "workspace-write" | "danger-full-access";
+  /**
+   * Opt in to the interactive permission path: instead of the one-way
+   * `codex exec --json` run (which cannot route approvals), drive
+   * `codex app-server` (JSON-RPC) so each command-execution / file-change
+   * approval is escalated through the unified interaction broker. When unset
+   * (the default) the adapter behaves exactly as before. Requires a non-bypass
+   * sandbox + an escalating approval policy for codex to actually ask.
+   */
+  interactivePermissions?: boolean;
+  /**
+   * Approval policy sent to `codex app-server` when `interactivePermissions`
+   * is on. Interactive turns need an escalating value (codex never asks under
+   * "never" or a bypass sandbox); "never" is the question-only posture, where
+   * approvals are deliberately bypassed but `request_user_input` questions still
+   * fire. Default: "on-request" (interactive) / "never" (question-only).
+   */
+  approvalPolicy?: "untrusted" | "on-failure" | "on-request" | "never";
+}
+/**
+ * Codex CLI event types based on --json output format.
+ * These match the JSONL output from `codex exec --json`.
+ */
+/**
+ * Session started event.
+ */
+interface CodexSessionStartedEvent {
+  type: "session_started";
+  session_id: string;
+}
+/**
+ * Thread started event — the modern `codex exec --json` wire's session
+ * announcement. `thread_id` is the handle `codex exec resume <id>` takes.
+ */
+interface CodexThreadStartedEvent {
+  type: "thread.started";
+  thread_id: string;
+}
+/**
+ * Message event wrapper.
+ */
+interface CodexMessageEvent {
+  type: "message";
+  role: "user" | "assistant" | "system";
+  message: CodexMessage;
+}
+/**
+ * Codex message content.
+ */
+interface CodexMessage {
+  content?: CodexContentBlock[];
+  status?: string;
+}
+/**
+ * Content block types.
+ */
+type CodexContentBlock = CodexTextContent | CodexToolUseContent | CodexToolResultContent | CodexThinkingContent;
+interface CodexTextContent {
+  type: "text";
+  text: string;
+}
+interface CodexToolUseContent {
+  type: "tool_use";
+  id: string;
+  name: string;
+  input: unknown;
+}
+interface CodexToolResultContent {
+  type: "tool_result";
+  tool_use_id: string;
+  content: unknown;
+  is_error?: boolean;
+}
+interface CodexThinkingContent {
+  type: "thinking";
+  thinking: string;
+}
+/**
+ * Task started event.
+ */
+interface CodexTaskStartedEvent {
+  type: "task_started";
+  task_id: string;
+  task_type?: string;
+}
+/**
+ * Error event.
+ */
+interface CodexErrorEvent {
+  type: "error";
+  message: string;
+  code?: string;
+}
+/**
+ * One file touched by an exec-path `file_change` item. The exec `--json`
+ * stream carries only `path` + `kind` ("add" | "update" | "delete") — no
+ * diff, unlike the app-server's FileUpdateChange. Fields are optional so a
+ * malformed change degrades to "no file signal" instead of a crash.
+ */
+interface CodexFileChange {
+  path?: string;
+  kind?: string;
+}
+/**
+ * Raw item completion event emitted by newer Codex CLI builds.
+ * We care about assistant message completions because they may contain
+ * the final full text even when incremental message events were absent,
+ * and `file_change` completions because they are the exec path's only
+ * signal that the agent wrote files (surfaced as file parts).
+ */
+interface CodexItemCompletedEvent {
+  type: "item.completed";
+  item: {
+    id?: string;
+    type?: string;
+    text?: string;
+    status?: string;
+    changes?: CodexFileChange[]; /** command_execution */
+    command?: string;
+    aggregated_output?: string;
+    exit_code?: number | null; /** mcp_tool_call */
+    server?: string;
+    tool?: string;
+    arguments?: unknown;
+    result?: unknown;
+    error?: unknown; /** web_search */
+    query?: string;
+  };
+}
+/** A tool item the agent began; its `item.completed` follows. */
+interface CodexItemStartedEvent {
+  type: "item.started";
+  item: CodexItemCompletedEvent["item"];
+}
+/** The turn's end, with the tokens it used (`codex exec --json`). */
+interface CodexTurnCompletedEvent {
+  type: "turn.completed";
+  usage?: Record<string, unknown>;
+}
+/**
+ * Union of all Codex CLI events.
+ */
+type CodexEvent = CodexSessionStartedEvent | CodexThreadStartedEvent | CodexMessageEvent | CodexTaskStartedEvent | CodexErrorEvent | CodexItemCompletedEvent | CodexItemStartedEvent | CodexTurnCompletedEvent;
+//#endregion
+//#region src/codex-connection-config.d.ts
+declare function normalizeExplicitCodexModel(model: string): string;
+declare function resolveCodexApiKeyBaseUrl(config: Pick<CodexConfig, "apiKey" | "baseUrl">): string;
+declare function resolveCodexConnection(config: CodexConfig, explicitModel?: string): {
+  baseUrl?: string;
+  model?: string;
+};
+//#endregion
+//#region src/codex-native-launch.d.ts
+declare abstract class CodexNativeLaunchAdapter extends CliProviderAdapterBase<CodexConfig, CodexEvent> {
+  protected readonly inheritProcessEnv = false;
+  protected nativeAttachmentKinds(): ReadonlyArray<"image" | "file">;
+  protected nativeConfigArgs(config: CodexConfig, connection: ReturnType<typeof resolveCodexConnection>, prompts: {
+    systemPrompt?: string;
+    appendSystemPrompt?: string;
+  }, flags: readonly string[]): string[];
+  protected buildExecArgs(params: {
+    message: string;
+    config: CodexConfig;
+    model?: string;
+    sessionId?: string;
+    workspaceRoot: string;
+    systemPrompt?: string;
+    appendSystemPrompt?: string;
+    attachments?: PreparedAttachment[];
+  }): CliExecArgs;
+  protected buildExecEnv(config: CodexConfig): Record<string, string | undefined>;
+  protected buildAppServerEnv(profilePlan: WorkspacePlanApplication | undefined, workspaceRoot: string): Record<string, string | undefined>;
+  getManagedAuthFiles(): CliAuthFile[];
+}
+//#endregion
+//#region src/codex-secret-profile.d.ts
+declare abstract class CodexSecretProfileAdapter extends CodexNativeLaunchAdapter {
+  protected readonly supportsSecretProfileRevisions = true;
+  private readonly mcpOwner;
+  private binary?;
+  constructor(options?: CliProviderOptions<CodexConfig>);
+  private refuse;
+  protected getCliPath(): string;
+  protected secretProfileVerificationScope(): string;
+  protected verifyPreparedSecretProfileRevision(input: AgentExecutionInput, plan: WorkspacePlanApplication): Promise<void>;
+  private readNativeConfig;
+  private readNativeControls;
+  protected nativeArgs(input: AgentExecutionInput, plan: WorkspacePlanApplication | undefined, mcp?: Record<string, unknown>): string[];
+  protected prepareSecretCodexTurn(input: AgentExecutionInput, plan: WorkspacePlanApplication, sessionId: string): Promise<{
+    cwd: string;
+    env: Record<string, string | undefined>;
+    args: string[];
+    release: (() => void | Promise<void>) | undefined;
+    validate: (bridge: RpcBridge, extra: Record<string, unknown>) => Promise<Record<string, NativeMcp>>;
+  }>;
+  shutdown(): Promise<void>;
+}
+//#endregion
+//#region src/codex-app-server-adapter.d.ts
+declare abstract class CodexAppServerAdapter extends CodexSecretProfileAdapter {
+  private readonly permissions;
+  getCapabilities(): BackendCapabilities;
+  respondToInteraction(response: InteractionResponse): Promise<void>;
+  execute(input: AgentExecutionInput, services: SdkHostServices, onEvent?: (event: StreamEvent) => void): Promise<AgentExecutionResult>;
+  private executeViaAppServer;
+  /** Capture session binding, profile/prompt and native callbacks before acquiring resources.
+   * Field construction stays one preparation record; launch/run/cleanup have separate owners. */
+  private prepareAppServerTurn;
+  private launchAppServerTurn;
+  private spawnAppServer;
+  private runAppServerTurn;
+  private closeAppServerTurn;
+  private bindPlanMcp;
+}
+//#endregion
+//#region src/adapter.d.ts
+/** Codex provider adapter. */
+declare class CodexProviderAdapter extends CodexAppServerAdapter {
+  readonly provider = "codex";
+  protected readonly profileHarness: HarnessId;
+  protected readonly defaultCliPath = "codex";
+  /** Start the process the box's first turn will adopt: `codex exec` launched as an ordinary new-session managed turn. */
+  prewarmProcess(workspaceRootOrUndefined: string | undefined, launch: {
+    systemPrompt: string;
+  }): Promise<{
+    ready: Promise<boolean>;
+  }>;
+  /** A new session takes the spare in its HOME when its own launch is the spare's: the same. */
+  protected spawnExecutionProcess(request: CliTurnSpawn<CodexConfig, CodexEvent>): CliTurnProcess | Promise<CliTurnProcess>;
+  protected createEventParser(state: ExecutionState, onEvent?: (event: StreamEvent) => void): StreamParserConfig<CodexEvent>;
+  protected buildMcpAddArgs(name: string, config: McpConfig): string[];
+  protected buildMcpListArgs(): string[] | null;
+  protected formatStdinMessage(message: string): string;
+  private mapEventToStreamEvents;
+}
+//#endregion
+//#region src/held-spare.d.ts
+declare const codexHeldSpares: _$_tangle_network_sdk_cli_runner0.HeldSpareRegistry<CodexEvent, object>;
+//#endregion
+export { type CodexAuthMode, type CodexConfig, type CodexContentBlock, type CodexErrorEvent, type CodexEvent, type CodexMessage, type CodexMessageEvent, CodexProviderAdapter, type CodexSessionStartedEvent, type CodexTaskStartedEvent, type CodexTextContent, type CodexThinkingContent, type CodexToolResultContent, type CodexToolUseContent, codexHeldSpares, normalizeExplicitCodexModel, resolveCodexApiKeyBaseUrl };
+//# sourceMappingURL=index.d.mts.map