@makaio/adapter-codex-app-server 1.0.0-dev-1779051654000 → 1.0.0-dev-1781368205459

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026-present Makaio GmbH
+Copyright (c) Makaio GmbH
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/dist/adapter.d.ts

@@ -0,0 +1,51 @@
+import { AIAdapter, type AIAdapterConfig } from '@makaio/framework/adapters';
+import { CodexAppServerAgent } from './agent.js';
+import { CodexAppServerConnector } from './connector.js';
+import { type CodexAppServerBus } from './namespaces/index.js';
+import { CodexAppServerAdapterName } from './constants.js';
+export { CodexAppServerAdapterName };
+/**
+ * Codex App-Server Adapter - Domain-level adapter using the three-layer architecture.
+ *
+ * Architecture:
+ * ```
+ * CodexAppServerAdapter extends AIAdapter
+ *     -> creates via agentFactory()
+ * CodexAppServerAgent extends AIAgent
+ *     -> receives connector via connectorFactory()
+ * CodexAppServerConnector extends AIAgentConnector
+ * ```
+ *
+ * Responsibilities:
+ * - Handle adapter.startAgent RPC (inherited from AIAdapter)
+ * - Provide agent and connector factories for instance creation
+ * - Emit adapter.initialized and adapter.session.created events
+ * - Manage agent lifecycle (tracking, disposal)
+ * @example
+ * ```typescript
+ * // Using the class directly
+ * const adapter = new CodexAppServerAdapter();
+ * await adapter.init();
+ *
+ * // Using the convenience factory
+ * const adapter = await createCodexAppServerAdapter();
+ * ```
+ */
+export declare class CodexAppServerAdapter extends AIAdapter<CodexAppServerBus, CodexAppServerConnector, CodexAppServerAgent> {
+    constructor(config?: Partial<AIAdapterConfig>);
+}
+/**
+ * Factory function to create and initialize a Codex App-Server adapter.
+ *
+ * Convenience wrapper that creates the adapter and calls init() for you.
+ * @param config - Optional adapter configuration
+ * @returns Initialized CodexAppServerAdapter instance
+ * @example
+ * ```typescript
+ * const adapter = await createCodexAppServerAdapter();
+ *
+ * // Adapter is ready to handle requests via bus
+ * // e.g., MakaioBus.request(AdapterSubjects.startAgent, { adapterId: adapter.adapterId, ... })
+ * ```
+ */
+export declare function createCodexAppServerAdapter(config?: Partial<AIAdapterConfig>): Promise<CodexAppServerAdapter>;

package/dist/agent.d.ts

@@ -0,0 +1,148 @@
+/**
+ * Codex App-Server Agent - Event routing layer.
+ *
+ * Wires connector events to global agent.* subjects.
+ * Auto-enriches payloads with AgentContext via emitGlobal().
+ *
+ * Responsibilities:
+ * 1. Wire connector's scoped bus events to global agent.* subjects
+ * 2. Auto-enrich payloads with AgentContext
+ * 3. Track usage metrics
+ * 4. Route tool approval to global bus
+ * 5. Emit normalized client.session.* observed-semantics events
+ * 6. Emit client.runtime.observe (best-effort) when a thread starts with a confirmed adapter session ID
+ *
+ * Event Flow:
+ * - CodexAppServerConnector emits to adapter:codex-app-server:* subjects
+ * - CodexAppServerAgent routes to semantic subjects via wireConnectorEvents()
+ * - CodexAppServerAgent subscribes to semantic subjects and emits to global bus (agent.*)
+ * - Downstream consumers subscribe to normalized agent.* subjects
+ * @packageDocumentation
+ */
+import { AIAgent } from '@makaio/framework/adapters';
+import { CodexAppServerConnector } from './connector.js';
+import { type CodexAppServerBus } from './namespaces/index.js';
+/**
+ * Codex App-Server Agent - Middle layer between AIAdapter and CodexAppServerConnector.
+ *
+ * Responsibilities:
+ * 1. Wire connector's scoped bus events to global agent.* subjects
+ * 2. Auto-enrich payloads with AgentContext via emitGlobal()
+ * 3. Emit normalized client.session.* observed-semantics events (best-effort)
+ * 4. Emit client.runtime.observe (best-effort) when a thread starts with a confirmed adapter session ID
+ *
+ * Event Flow:
+ * - CodexAppServerConnector emits to adapter:codex-app-server:* subjects
+ * - CodexAppServerAgent routes to semantic subjects via wireConnectorEvents()
+ * - CodexAppServerAgent subscribes to semantic subjects and emits to global bus (agent.*)
+ * - Downstream consumers subscribe to normalized agent.* subjects
+ */
+export declare class CodexAppServerAgent extends AIAgent<CodexAppServerBus, CodexAppServerConnector> {
+    /** Cache of tool call arguments indexed by callId for content blocks */
+    private toolCallCache;
+    /** Accumulated tool output indexed by callId during streaming */
+    private toolOutputCache;
+    /** Track toolCallId to blockIndex for correlation between step.started and step.finished */
+    private toolBlockIndexMap;
+    /**
+     * Guard: client.session.* global bus observations are wired once per agent
+     * lifetime (not per connector swap). Connector-level wiring uses
+     * addConnectorWiringCleanup(); these stable global subscriptions use
+     * addBusHandlerCleanup() and must not accumulate across swaps.
+     */
+    private clientSessionObservationsWired;
+    protected wireEvents(connector: CodexAppServerConnector): void;
+    /**
+     * Wire connector's bus events to global agent.* subjects.
+     *
+     * Maps CodexAppServerSubjects.* to AgentSubjects.*
+     *
+     * Note: Turn lifecycle events (turn.started, turn.completed) are NOT wired here
+     * because the base AIAgent's message-lifecycle-tracker already handles emitting
+     * these global events when messages are acknowledged and turns complete.
+     * @param connector - The CodexAppServerConnector to wire events from
+     */
+    private wireConnectorEvents;
+    /**
+     * Build the shared base payload for all `client.session.*` observed-semantics
+     * events by forwarding this agent's current identity fields to the shared
+     * {@link buildClientSessionBase} helper.
+     *
+     * Captures the adapter session ID best-effort: if the connector has not yet
+     * confirmed a session ID (e.g., very early in initialization), the field is
+     * omitted rather than blocking emission.
+     * @returns Base payload with clientId, source, observedAt, and optional session IDs
+     */
+    private getClientSessionBase;
+    /**
+     * Wire stable global bus subscriptions for client.session.turn.* events.
+     *
+     * Uses addBusHandlerCleanup() so these subscriptions survive connector swaps.
+     * Guarded by clientSessionObservationsWired so they are registered exactly once
+     * per agent lifetime regardless of how many connector swaps occur.
+     *
+     * Subscribes to:
+     * - AgentSubjects.turn.started → client.session.turn.started
+     * - AgentSubjects.turn.completed → client.session.turn.completed
+     * - AgentSubjects.user_message.sent → client.session.userPrompt.submitted
+     */
+    private wireClientSessionTurnObservations;
+    /**
+     * Wire thread lifecycle events.
+     * @param connector - The CodexAppServerConnector to wire events from
+     */
+    private wireThreadLifecycleEvents;
+    /**
+     * Wire assistant message events.
+     *
+     * Note: Turn lifecycle events (agent.turn.started, agent.turn.completed) are emitted by
+     * MessageLifecycleTracker in ai-adapters-core based on message handle states,
+     * not by adapter-specific events.
+     * @param connector - The CodexAppServerConnector to wire events from
+     */
+    private wireMessageEvents;
+    /**
+     * Wire tool-related events.
+     * @param connector - The CodexAppServerConnector to wire events from
+     */
+    private wireToolEvents;
+    /**
+     * Wire command execution events (bash tool).
+     * @param connector - The CodexAppServerConnector to wire events from
+     */
+    private wireCommandExecutionEvents;
+    private handleExecCommandBegin;
+    /**
+     * Wire file change events (patch tool).
+     * @param connector - The CodexAppServerConnector to wire events from
+     */
+    private wireFileChangeEvents;
+    /**
+     * Wire dynamic tool call events (experimental API).
+     *
+     * Handles registry tools declared in `dynamicTools` at `thread/start`.
+     * The execution happens in the `item/tool/call` server request handler; these
+     * events carry the cached result into the agent's step lifecycle.
+     * @param connector - The CodexAppServerConnector to wire events from
+     */
+    private wireDynamicToolCallEvents;
+    /**
+     * Wire usage tracking events.
+     * The base AIAgent.trackUsage() handles dual emission to both
+     * AgentSubjects.usage and adapter session usage subjects.
+     * @param connector - The CodexAppServerConnector to wire events from
+     */
+    private wireUsageTracking;
+    /**
+     * Wire tool approval RPC from connector's scoped bus to global AgentSubjects.toolApprove.
+     *
+     * Uses centralized tool-handling helper for consistent approval flow.
+     * Note: adapterSessionId may be undefined at wire time — the lazy callback resolves it
+     * at request time via connector.getAdapterSessionId() to avoid the race condition.
+     * sessionId is always set for agents running within a session; asserted here as the
+     * Zod schema on AgentSubjects.toolApprove enforces it at runtime.
+     * @param connector - The CodexAppServerConnector to wire RPC from
+     */
+    private wireToolApprovalRpc;
+    private emitToolStepFinished;
+}

package/dist/bus/index.d.ts

@@ -0,0 +1,2 @@
+export { NotificationKindSchema, NotificationUrgencySchema } from './schemas.js';
+export type { AgentCompleteNotification, ApprovalNotification, NotificationBase, NotificationEntry, NotificationUrgency, } from './schemas.js';

package/dist/bus/register.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Notification domain has no bus subjects — types are UI-local state only.
+ *
+ * This module exists to satisfy the `./register` export convention used by
+ * domain packages and to serve as a future extension point if notification
+ * bus subjects are introduced.
+ * @packageDocumentation
+ */
+export { NotificationKindSchema, NotificationUrgencySchema } from './schemas.js';
+export type { AgentCompleteNotification, ApprovalNotification, NotificationBase, NotificationEntry, NotificationUrgency, } from './schemas.js';

package/dist/bus/schemas.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Notification types and Zod schemas for the in-app notification center.
+ *
+ * Notification entries are UI-local state (not bus-transported RPCs), but
+ * schemas are provided for consistency and future validation needs.
+ * @packageDocumentation
+ */
+import type { RiskLevel } from '@makaio/framework/contracts';
+import { z } from 'zod';
+/** Zod schema for {@link NotificationUrgency}. */
+export declare const NotificationUrgencySchema: z.ZodEnum<{
+    critical: "critical";
+    high: "high";
+    low: "low";
+    normal: "normal";
+}>;
+/** Zod schema for notification kind discriminator. */
+export declare const NotificationKindSchema: z.ZodEnum<{
+    "agent-complete": "agent-complete";
+    approval: "approval";
+}>;
+/**
+ * Urgency level for a notification entry.
+ * Controls sort order and visual treatment in the notification center.
+ */
+export type NotificationUrgency = z.infer<typeof NotificationUrgencySchema>;
+/**
+ * Base shape shared by all notification entries.
+ */
+export interface NotificationBase<TKind extends string = string> {
+    /** Unique notification identifier */
+    readonly id: string;
+    /** Discriminator for the notification kind */
+    readonly kind: TKind;
+    /** Unix timestamp (ms) when the notification was created */
+    readonly createdAt: number;
+    /** How urgent the notification is (controls sort order) */
+    readonly urgency: NotificationUrgency;
+    /** Whether the user has seen/acknowledged this notification */
+    readonly isRead: boolean;
+    /** Session the notification is associated with (if any) */
+    readonly sessionId?: string;
+    /** Agent the notification is associated with (if any) */
+    readonly agentId?: string;
+    /** Human-readable label for the notification source */
+    readonly sourceLabel: string;
+}
+/**
+ * Notification for a pending tool approval request.
+ * Derived from the approval queue — not stored independently.
+ */
+export interface ApprovalNotification extends NotificationBase<'approval'> {
+    /** Discriminator: approval notification */
+    readonly kind: 'approval';
+    /** Session associated with this approval request */
+    readonly sessionId: string;
+    /** FK to the approval queue entry's requestId */
+    readonly requestId: string;
+    /** Tool call identifier */
+    readonly toolCallId: string;
+    /** Name of the tool awaiting approval */
+    readonly toolName?: string;
+    /** Risk classification for this tool call */
+    readonly riskLevel?: RiskLevel;
+}
+/**
+ * Notification for agent completion.
+ * Emitted when an `agent.complete` bus event is received with a `sessionId`.
+ */
+export interface AgentCompleteNotification extends NotificationBase<'agent-complete'> {
+    /** Discriminator: agent-complete notification */
+    readonly kind: 'agent-complete';
+    /** Summary of what the agent accomplished */
+    readonly summary?: string;
+}
+/**
+ * Discriminated union of all notification entry types.
+ * Extend this union to add new notification kinds.
+ */
+export type NotificationEntry = ApprovalNotification | AgentCompleteNotification;

package/dist/config.d.ts

@@ -0,0 +1,4 @@
+export declare const CodexAppServerConfig: {
+    getConfig: <TInput extends import("@makaio/framework/adapters/config").AdapterConfigFactoryInput<import("@makaio/framework/adapters").BaseAgentConnectorConfig<import("@makaio/framework/bus").ScopedBus<string>, object>>>(input: TInput) => Promise<Partial<Omit<import("@makaio/framework/adapters").BaseAgentConnectorConfig<import("@makaio/framework/bus").ScopedBus<string>, object>, "adapterName" | "agentId" | "bus" | "sessionId">> & Omit<TInput, "providerConfig"> & import("@makaio/framework/adapters/config").FactoryGuaranteedFields<object | undefined> extends infer T ? { [KeyType in keyof T]: T[KeyType]; } : never>;
+    getDefaults: () => Partial<Omit<import("@makaio/framework/adapters").BaseAgentConnectorConfig<import("@makaio/framework/bus").ScopedBus<string>, object>, "adapterName" | "agentId" | "bus" | "sessionId">>;
+};

package/dist/connector/approval-handlers.d.ts

@@ -0,0 +1,111 @@
+/**
+ * Approval request handlers for Codex App-Server.
+ *
+ * Handles command execution, file change, and dynamic tool call approval requests
+ * from the server. All approval handlers gate execution through the scoped bus
+ * via `requestToolApproval`, enabling a shared approval policy across adapter types.
+ * @packageDocumentation
+ */
+import type { ServerRequest } from '../protocol/generated/index.js';
+import { type CodexAppServerBus } from '../namespaces/index.js';
+import { type DynamicToolCallCacheEntry, type DynamicToolCallServerRequest, type DynamicToolCallResponse } from '../dynamic-tool-handling.js';
+/**
+ * Approval response returned to the server.
+ */
+export interface ApprovalResponse {
+    decision: 'accept' | 'decline';
+    message?: string;
+}
+/**
+ * Context needed for approval handling.
+ */
+export interface ApprovalContext {
+    agentId: string;
+    cwd: string;
+    commandExecutionByItemId: Map<string, {
+        command: string;
+        cwd: string;
+    }>;
+    /** Bound requestToolApproval from AIAgentConnector - typed loosely to avoid coupling */
+    requestToolApproval: (subject: unknown, payload: unknown) => Promise<ApprovalResponse>;
+    handleError: (error: Error, terminate: boolean) => void;
+    /**
+     * Returns the set of SDK-native tool names currently disabled by the active harness.
+     *
+     * Evaluated lazily at each approval call so that the set reflects the state
+     * resolved during {@link initializeConnection}, even though the context object
+     * is constructed before the harness query runs.
+     */
+    getDisabledNativeTools: () => ReadonlySet<string>;
+    /**
+     * Waits for `item/started` to populate `commandExecutionByItemId` for the given
+     * item. Returns the cached entry immediately if already present (fast path), or
+     * waits up to 5 seconds for the lifecycle handler to provide it. Returns
+     * `undefined` on timeout so callers can degrade gracefully.
+     * @param itemId - The item ID to wait for
+     */
+    waitForCommandInfo: (itemId: string) => Promise<{
+        command: string;
+        cwd: string;
+    } | undefined>;
+}
+/**
+ * Handle command approval request.
+ *
+ * Returns an immediate `decline` when the `bash` native tool is disabled by the
+ * active harness, bypassing the normal approval flow.
+ * Otherwise routes the JSON-RPC server request to the scoped bus via requestToolApproval.
+ * @param request - Server request for command approval
+ * @param ctx - Approval context
+ * @returns Approval response with decision and optional message
+ */
+export declare function handleCommandApprovalRequest(request: ServerRequest, ctx: ApprovalContext): Promise<ApprovalResponse>;
+/**
+ * Handle file change approval request.
+ *
+ * Returns an immediate `decline` when the `patch` native tool is disabled by the
+ * active harness, bypassing the normal approval flow.
+ * Otherwise routes the JSON-RPC server request to the scoped bus via requestToolApproval.
+ * @param request - Server request for file change approval
+ * @param ctx - Approval context
+ * @returns Approval response with decision and optional message
+ */
+export declare function handleFileChangeApprovalRequest(request: ServerRequest, ctx: ApprovalContext): Promise<ApprovalResponse>;
+/**
+ * Context needed for dynamic tool call approval and execution.
+ */
+export interface DynamicToolApprovalContext {
+    /** Bound requestToolApproval from AIAgentConnector — typed loosely to avoid coupling */
+    requestToolApproval: (subject: unknown, payload: unknown) => Promise<ApprovalResponse>;
+    /** Scoped bus emit function for emitting lifecycle events */
+    emit: CodexAppServerBus['emit'];
+    /** Session ID for bus routing */
+    sessionId?: string;
+    /** Agent ID for attribution */
+    agentId: string;
+    /** Adapter instance ID for allowedAdapters policy enforcement */
+    adapterId: string;
+    /** Adapter type name for allowedAdapters policy enforcement */
+    adapterName: string;
+    /** Session tool ledger for MCP call tracking. */
+    toolLedger?: import('@makaio/framework/adapters').ISessionToolLedger;
+    /** Current turn number for MCP call tracking. */
+    currentTurnNumber: number;
+    /** Cache for lifecycle event correlation, keyed by itemId */
+    dynamicToolCallByItemId: Map<string, DynamicToolCallCacheEntry>;
+}
+/**
+ * Handle an `item/tool/call` server request (experimental API).
+ *
+ * Requests tool approval via the scoped bus before executing. If denied, returns error
+ * content without executing. If approved, executes via bus and caches result under
+ * `itemId` for lifecycle handler correlation.
+ *
+ * Denied calls emit a synthetic `dynamic_tool_call_begin`/`end` pair so that
+ * downstream lifecycle consumers (e.g. `AgentSubjects.tool.use`) observe every
+ * tool invocation regardless of approval outcome.
+ * @param params - Parsed `item/tool/call` request parameters
+ * @param ctx - Dynamic tool approval and execution context
+ * @returns Content items to send back to codex
+ */
+export declare function handleDynamicToolCallApprovalRequest(params: DynamicToolCallServerRequest['params'], ctx: DynamicToolApprovalContext): Promise<DynamicToolCallResponse>;

package/dist/connector/client-handlers.d.ts

@@ -0,0 +1,56 @@
+import type { ProcessingState } from '@makaio/framework/adapters';
+import type { ThreadStartedNotification, TurnCompletedNotification } from '../protocol/generated/v2/index.js';
+import type { CodexAppServerBus } from '../namespaces/index.js';
+import type { JsonRpcClient } from '../utils/jsonRpcClient.js';
+import { type ApprovalContext } from './approval-handlers.js';
+import { type DynamicToolCallCacheEntry, type DynamicToolCallResponse, type DynamicToolCallServerRequest } from '../dynamic-tool-handling.js';
+import type { CodexAppServerThread } from '../thread.js';
+import type { CodexAppServerTurn } from '../turn.js';
+interface NotificationHandlerOptions {
+    client: JsonRpcClient;
+    enqueueNotification: (handler: () => Promise<void>) => void;
+    onThreadStarted: (params: ThreadStartedNotification) => Promise<void>;
+    consumeTurnNumber: () => number;
+    getCurrentTurn: () => CodexAppServerTurn | undefined;
+    emit: CodexAppServerBus['emit'];
+    commandExecutionByItemId: Map<string, {
+        command: string;
+        cwd: string;
+    }>;
+    dynamicToolCallByItemId: Map<string, DynamicToolCallCacheEntry>;
+    updateProcessingState: (state: ProcessingState) => Promise<void>;
+    appendAgentMessageDelta: (delta: string) => void;
+    onTurnCompleted: (params: TurnCompletedNotification) => Promise<void>;
+    getThread: () => CodexAppServerThread | undefined;
+    handleAsyncError: (error: unknown) => void;
+    /** Invoked after a commandExecution entry is written to commandExecutionByItemId. */
+    onCommandInfoReady: (itemId: string, info: {
+        command: string;
+        cwd: string;
+    }) => void;
+}
+interface ServerRequestHandlerOptions {
+    client: JsonRpcClient;
+    agentId: string;
+    cwd: string;
+    commandExecutionByItemId: Map<string, {
+        command: string;
+        cwd: string;
+    }>;
+    requestToolApproval: ApprovalContext['requestToolApproval'];
+    handleError: (error: unknown, terminate?: boolean) => void;
+    getDisabledNativeTools: () => ReadonlySet<string>;
+    handleDynamicToolCallRequest: (params: DynamicToolCallServerRequest['params']) => Promise<DynamicToolCallResponse>;
+    waitForCommandInfo: ApprovalContext['waitForCommandInfo'];
+}
+/**
+ * Register JSON-RPC notification handlers for the connector client instance.
+ * @param options - Callbacks and state accessors used to bridge notifications into connector state
+ */
+export declare function registerNotificationHandlers(options: NotificationHandlerOptions): void;
+/**
+ * Register the JSON-RPC server-request handler for approval and dynamic tool call flows.
+ * @param options - Callbacks and state accessors needed to answer server requests
+ */
+export declare function registerServerRequestHandler(options: ServerRequestHandlerOptions): void;
+export {};

package/dist/connector/connection-manager.d.ts

@@ -0,0 +1,88 @@
+/**
+ * Connection lifecycle management for the Codex App-Server connector.
+ *
+ * Handles JSON-RPC client creation, subprocess spawning, credential resolution,
+ * the ACP `initialize` handshake, and error-path teardown. The connector holds all
+ * mutable state; this module mutates it only through the typed accessors in
+ * {@link ConnectionManagerContext}.
+ * @packageDocumentation
+ */
+import type { ProviderContext } from '@makaio/framework/contracts';
+import { type JsonRpcClient } from '../utils/jsonRpcClient.js';
+import { type StdioTransport } from '../utils/createStdioTransport.js';
+import { type SessionEnvironmentOptions } from '@makaio/framework/adapters/config';
+/**
+ * Mutable connector state and callbacks required by the connection manager.
+ *
+ * All state accessors are passed as getters/setters so the manager never holds
+ * a stale reference to the connector's internal fields.
+ */
+export interface ConnectionManagerContext {
+    /** Returns the current JSON-RPC client, or `undefined` before first connection. */
+    getJsonRpcClient: () => JsonRpcClient | undefined;
+    /** Replaces the active JSON-RPC client (or clears it by passing `undefined`). */
+    setJsonRpcClient: (client: JsonRpcClient | undefined) => void;
+    /** Returns the injected test-double client, if any. */
+    getInjectedJsonRpcClient: () => JsonRpcClient | undefined;
+    /** Returns the injected test-double transport, if any. */
+    getInjectedTransport: () => StdioTransport | undefined;
+    /** Returns the transport currently owned (and closeable) by this connector. */
+    getOwnedTransport: () => StdioTransport | undefined;
+    /** Replaces (or clears) the owned transport reference. */
+    setOwnedTransport: (transport: StdioTransport | undefined) => void;
+    /** Returns the current `isConnected` flag. */
+    getIsConnected: () => boolean;
+    /** Updates the `isConnected` flag. */
+    setIsConnected: (value: boolean) => void;
+    /** Updates the `clientHandlersRegistered` flag to `false` on reset. */
+    setClientHandlersRegistered: (value: boolean) => void;
+    /** Clears the `disabledNativeTools` set to an empty set on reset. */
+    setDisabledNativeTools: (tools: ReadonlySet<string>) => void;
+    /** Working directory passed to the subprocess on first spawn. */
+    cwd: string;
+    /** Environment variables merged into the subprocess environment. */
+    env: Record<string, string>;
+    /** Adapter type name used for harness tool policy lookup. */
+    adapterName: string;
+    /** Provider context carrying credential refs for resolution. */
+    providerContext: ProviderContext | undefined;
+    /** Optional client identifier for binary resolution (defaults to `'codex'`). */
+    clientId: string | undefined;
+    /** Optional harness ID for native-tool policy lookup. */
+    harnessId: string | undefined;
+    /** Scoped bus used for credential resolution. */
+    bus: SessionEnvironmentOptions['bus'];
+    /**
+     * Registers JSON-RPC notification and server-request handlers on the newly created client.
+     * Called immediately after the client is assigned so handlers are in place before any
+     * messages are sent.
+     */
+    registerClientHandlers: () => void;
+    /**
+     * Routes transport or protocol errors through the connector's error handling path.
+     * @param error - The error to handle
+     * @param terminate - When `true`, the connector should be torn down
+     */
+    handleError: (error: unknown, terminate: boolean) => void;
+}
+/**
+ * Tear down the active JSON-RPC client and owned transport after a connection failure.
+ *
+ * Resets connection and handler-registration flags so the next `initializeConnection`
+ * call starts fresh. If an injected test client is present it is restored (not closed)
+ * so the test can continue using the same mock instance.
+ * @param ctx - Connection manager context
+ */
+export declare function resetClient(ctx: ConnectionManagerContext): void;
+/**
+ * Ensure the connector is connected, using single-flight deduplication.
+ *
+ * Concurrent callers share the same in-flight promise so the subprocess is spawned
+ * exactly once. Resolves immediately when already connected.
+ * @param ctx - Connection manager context
+ * @param inflight - Mutable holder for the in-flight promise; updated by this function
+ * @returns Promise that resolves when the connection is established
+ */
+export declare function initializeConnection(ctx: ConnectionManagerContext, inflight: {
+    promise: Promise<void> | undefined;
+}): Promise<void>;

package/dist/connector/connector.d.ts

@@ -0,0 +1,95 @@
+import { AIAgentConnector, type AgentStartResult, type ConnectorSendMessageOptions, type ConnectorStartOptions, type MessageHandle, type MessageResult, type NormalizedMessageInput } from '@makaio/framework/adapters';
+import type { AIReasoningLevel } from '@makaio/framework/contracts';
+import type { CodexAppServerBus } from '../namespaces/index.js';
+import { type CodexAppServerConfig, type ApprovalPolicy, type SandboxMode, type ReasoningEffort } from './types.js';
+export declare class CodexAppServerConnector extends AIAgentConnector<CodexAppServerBus> {
+    /** Lazy: initialised in initializeConnection(); public methods access via getJsonRpcClient(). */
+    private jsonRpcClient?;
+    /** Injected transport for tests; null means "create from subprocess on first connect". */
+    private readonly _injectedTransport?;
+    /** Injected JSON-RPC client for tests; bypasses subprocess creation entirely. */
+    private readonly _injectedJsonRpcClient?;
+    /** Transport owned by this connector and safe to tear down after partial startup failures. */
+    private ownedTransport?;
+    private readonly messageQueue;
+    private thread?;
+    private currentTurn?;
+    private isConnected;
+    /** In-flight connection initialization promise for single-flight deduplication. */
+    private readonly initConnectionInflight;
+    /** Handlers are registered once per client instance to avoid duplicate listeners on retries. */
+    private clientHandlersRegistered;
+    private isTerminated;
+    private agentMessageContent;
+    private notificationQueue;
+    private threadStartedDeferred?;
+    private readonly _approvalPolicy?;
+    private readonly _sandboxMode?;
+    private readonly _reasoningEffort?;
+    private readonly commandExecutionByItemId;
+    private readonly dynamicToolCallByItemId;
+    /** Pending resolvers for {@link waitForCommandInfo}, keyed by itemId. */
+    private readonly commandInfoWaiters;
+    private disabledNativeTools;
+    /**
+     * Stable context object passed to connection-manager module functions.
+     * All state access is via closures over `this` so the object is never stale.
+     */
+    private readonly connCtx;
+    /**
+     * Stable context object passed to turn-flow-handlers module functions.
+     * All state access is via closures over `this` so the object is never stale.
+     */
+    private readonly turnCtx;
+    constructor(config: CodexAppServerConfig);
+    private buildConnectionContext;
+    private buildTurnFlowContext;
+    get approvalPolicy(): ApprovalPolicy | undefined;
+    get sandboxMode(): SandboxMode | undefined;
+    get reasoningEffort(): ReasoningEffort | undefined;
+    /**
+     * Resolve any pending {@link waitForCommandInfo} promise for `itemId`.
+     * Called by the `item/started` lifecycle path after populating `commandExecutionByItemId`.
+     * @param itemId - Item now available in commandExecutionByItemId
+     * @param info - Command execution metadata just written to the cache
+     */
+    private notifyCommandInfoReady;
+    /**
+     * Return `commandExecutionByItemId` entry for `itemId` immediately if present,
+     * otherwise wait up to 5 seconds for `item/started` to populate it.
+     * Returns `undefined` on timeout so callers can degrade gracefully.
+     * @param itemId - Item ID to wait for
+     * @returns Command execution metadata, or `undefined` on timeout
+     */
+    private waitForCommandInfo;
+    private resolveSystemPrompt;
+    private enqueueNotification;
+    private getJsonRpcClient;
+    private registerClientHandlers;
+    private handleDynamicToolCallRequest;
+    initialize(options?: ConnectorStartOptions): Promise<void>;
+    start(message: NormalizedMessageInput, options?: ConnectorStartOptions): Promise<AgentStartResult>;
+    sendMessage(message: NormalizedMessageInput, options?: ConnectorSendMessageOptions): Promise<MessageHandle>;
+    /**
+     * Codex supports per-turn model switching via `turn/start`.
+     * The caller updates `this.model` after this returns true.
+     * @param _newModel - The model identifier (unused — read from `this.model` at turn start)
+     * @returns Always `true`
+     */
+    changeModelInPlace(_newModel: string): Promise<boolean>;
+    /**
+     * Codex passes reasoning effort per-turn via `turn/start`; `startTurn` reads
+     * `this.currentReasoningEffort` at send time, so no SDK reconfiguration is needed.
+     * @param _newLevel - Unused — read from `this.currentReasoningEffort` at turn start
+     * @returns Always `true`
+     */
+    changeReasoningInPlace(_newLevel: AIReasoningLevel): Promise<boolean>;
+    interrupt(): Promise<void>;
+    getAdapterSessionId(): Promise<string>;
+    complete(): Promise<MessageResult | null>;
+    abort(): void;
+    close(): Promise<void>;
+    private archiveThread;
+    protected acceptsImmediate(): boolean;
+    handleError(error: unknown, terminate?: boolean): void;
+}