@pwrdrvr/agent-client 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 PwrDrvr LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/index.d.ts

@@ -0,0 +1,532 @@
+import { AgentBackendApprovalHandler, AgentBackend, Logger, NormalizedThreadEvent, AgentBackendToolCallHandler, AgentStartThreadOptions, AgentStartTurnOptions, NormalizedTokenUsage, NormalizedApprovalRequest, NormalizedToolCall, NormalizedThreadSettings, NormalizedThreadView, NormalizedMessage, ThreadStore, NormalizedApprovalDecision } from '@pwrdrvr/agent-core';
+import { JsonRpcTransport } from '@pwrdrvr/agent-transport';
+import { DynamicToolSpec, UserInput, Model, DynamicToolCallParams, ThreadItem, ThreadSettingsUpdatedNotification, ThreadTokenUsage, DynamicToolCallOutputContentItem, DynamicToolCallResponse } from '@pwrdrvr/codex-app-server-protocol/v2';
+import { z } from 'zod';
+
+type CodexThreadClientTransportFactory = (command: string) => JsonRpcTransport;
+type CodexThreadClientOptions = {
+    /** Configured command to resolve. `"codex"` (or empty) triggers discovery. */
+    command?: string;
+    /** Identity sent as `clientInfo.name` at `initialize`. Defaults to "agent-kit". */
+    clientName?: string;
+    /** Human title sent as `clientInfo.title`. Defaults to `clientName`. */
+    clientTitle?: string;
+    /** Version sent as `clientInfo.version`. Defaults to "0.0.0". */
+    clientVersion?: string;
+    /** Default `serviceName` applied at `thread/start` when the caller omits one. */
+    serviceName?: string;
+    requestTimeoutMs?: number;
+    turnTimeoutMs?: number;
+    /** Process env passed to the spawned codex. Defaults to `process.env`. */
+    env?: NodeJS.ProcessEnv;
+    /** Override the transport (tests inject an in-memory fake). When supplied,
+     *  no discovery/spawn happens. */
+    transportFactory?: CodexThreadClientTransportFactory;
+    logger?: Logger;
+};
+/**
+ * Codex-NATIVE thread/start options. **No longer the public `startThread`
+ * surface** — `CodexThreadClient` now implements the non-generic `AgentBackend`
+ * and its public `startThread` takes neutral `AgentStartThreadOptions`. This
+ * type is retained as the internal mapping target (and is still exported for
+ * hosts that want to construct the native shape directly via
+ * `startThreadNative`). The neutral→native mapping lives in `startThread`.
+ */
+type CodexStartThreadOptions = {
+    approvalPolicy?: string;
+    sandbox?: string;
+    baseInstructions?: string;
+    dynamicTools?: DynamicToolSpec[];
+    cwd?: string;
+    runtimeWorkspaceRoots?: string[];
+    serviceName?: string;
+    personality?: string;
+    /** Model id to start the thread on (ThreadStartParams.model). Omit for the
+     *  Codex default. The host drives this from its settings (per-surface default). */
+    model?: string;
+    /** Model provider id (ThreadStartParams.modelProvider) — the "provider" a host
+     *  picks when more than one is configured. Omit for the Codex default. */
+    modelProvider?: string;
+    /** Service tier (ThreadStartParams.serviceTier), when the host pins one. */
+    serviceTier?: string;
+    /** Per-thread Codex config overlay (the `-c key=value` mechanism). Used to
+     *  disable Codex prompt/tool scaffolding that belongs to coding-agent threads. */
+    config?: Record<string, unknown>;
+    /** Thread environments. **Empty array disables exec-environment access**,
+     *  dropping Codex's built-in shell / unified_exec / apply_patch tools. Dynamic
+     *  tools are added before that gate, so they survive. */
+    environments?: unknown[];
+};
+/** Codex-NATIVE turn/start options. Internal mapping target (see
+ *  `startThreadNative`'s sibling `startTurnNative`); the public `startTurn`
+ *  takes neutral `AgentStartTurnOptions`. */
+type CodexStartTurnOptions = {
+    threadId: string;
+    input: UserInput[];
+    effort?: string;
+};
+/**
+ * Handles a tool-call ServerRequest. Reconciled to the canonical
+ * `AgentBackendToolCallHandler` shape so the controller drives Codex and ACP
+ * identically: the handler receives a neutral `AgentBackendToolCall`
+ * (`{ method, params }`) and returns an `unknown` payload the client forwards
+ * back to Codex verbatim. For Codex the `params` is a `DynamicToolCallParams`
+ * (cast at the dispatch site) and the returned payload is a
+ * `DynamicToolCallResponse`.
+ */
+type CodexToolCallHandler = AgentBackendToolCallHandler;
+/** Handles an approval ServerRequest; resolves to a neutral decision. Identical
+ *  to the canonical `AgentBackendApprovalHandler`. */
+type CodexApprovalHandler = AgentBackendApprovalHandler;
+type Unsubscribe = () => void;
+type StartThreadResult = {
+    threadId: string;
+    model: string;
+    modelProvider: string;
+    serviceTier: string | null;
+};
+declare class CodexThreadClient implements AgentBackend {
+    private readonly options;
+    private readonly requestTimeoutMs;
+    private readonly turnTimeoutMs;
+    private readonly logger;
+    private readonly transportFactory;
+    private resolvedCommand;
+    private connection;
+    private initializeResponse;
+    private readonly eventListeners;
+    private toolCallHandler;
+    private approvalHandler;
+    private readonly loadedThreadIds;
+    constructor(options?: CodexThreadClientOptions);
+    /** Subscribe to the normalized event stream. Every native notification is
+     *  routed through `normalizeNotification` before listeners see it. */
+    onEvent(cb: (event: NormalizedThreadEvent) => void): Unsubscribe;
+    /** Register the dynamic-tool ServerRequest handler (one at a time). */
+    onToolCall(handler: CodexToolCallHandler): Unsubscribe;
+    /** Register the approval ServerRequest handler (one at a time). */
+    onApprovalRequest(handler: CodexApprovalHandler): Unsubscribe;
+    /**
+     * Public `AgentBackend.startThread`: accepts NEUTRAL `AgentStartThreadOptions`
+     * and maps them onto Codex-native `CodexStartThreadOptions` before delegating
+     * to `startThreadNative`. Mapping:
+     *   instructions→baseInstructions, cwd, workspaceRoots→runtimeWorkspaceRoots,
+     *   model/modelProvider, serviceTier (drop `null`), approvalPolicy, sandbox,
+     *   serviceName, config, environments, tools (cast to DynamicToolSpec[])→
+     *   dynamicTools.
+     */
+    startThread(opts?: AgentStartThreadOptions): Promise<StartThreadResult>;
+    /** Codex-native thread/start. Builds `ThreadStartParams` directly. Exposed for
+     *  hosts that want full Codex control; the neutral `startThread` delegates here. */
+    startThreadNative(opts?: CodexStartThreadOptions): Promise<StartThreadResult>;
+    resumeThread(threadId: string): Promise<void>;
+    clearThreadGitInfo(threadId: string): Promise<void>;
+    /**
+     * Public `AgentBackend.startTurn`: accepts NEUTRAL `AgentStartTurnOptions` and
+     * maps them onto Codex-native `UserInput[]`. The neutral `input.text` becomes a
+     * leading `{ type: "text" }` item; each `input.imagePaths` entry becomes a
+     * `{ type: "localImage", path }` item appended after the text. `reasoning`
+     * maps to Codex's `effort`.
+     */
+    startTurn(opts: AgentStartTurnOptions): Promise<{
+        turnId: string;
+    }>;
+    /** Codex-native turn/start. Takes pre-built `UserInput[]`. The neutral
+     *  `startTurn` delegates here after mapping text + image paths. */
+    startTurnNative(opts: CodexStartTurnOptions): Promise<{
+        turnId: string;
+    }>;
+    interruptTurn(threadId: string): Promise<void>;
+    archiveThread(threadId: string): Promise<void>;
+    close(): Promise<void>;
+    private emit;
+    private resolveCommand;
+    private initialize;
+    private getConnection;
+    private handleNotification;
+    private handleServerRequest;
+}
+
+type CodexOneShotTransportFactory = (command: string) => JsonRpcTransport;
+type CodexModelOption = {
+    id: string;
+    model: string;
+    displayName: string;
+    description: string;
+    hidden: boolean;
+    inputModalities: Model["inputModalities"];
+    defaultServiceTier: string | null;
+    isDefault: boolean;
+};
+type CodexOneShotClientOptions = {
+    command?: string;
+    /** Identity sent as `clientInfo.name`. Defaults to "agent-kit". */
+    clientName?: string;
+    clientTitle?: string;
+    clientVersion?: string;
+    /** serviceName for the worker thread. Defaults to "agent-kit". */
+    serviceName?: string;
+    /** Working dir for the persistent worker thread (keeps it out of any repo). */
+    workspaceDir?: string;
+    /** Human-readable name set on the worker thread. */
+    workerThreadName?: string;
+    /** Per-thread Codex config overlay applied to the worker thread. */
+    threadConfig?: Record<string, unknown>;
+    requestTimeoutMs?: number;
+    turnTimeoutMs?: number;
+    env?: NodeJS.ProcessEnv;
+    transportFactory?: CodexOneShotTransportFactory;
+    logger?: Logger;
+};
+type CodexOneShotRequest = {
+    /** The user-message text (the caller's prompt) for this turn. */
+    prompt: string;
+    /** Local image file paths fed as `localImage` inputs (not inlined as base64). */
+    imagePaths?: readonly string[];
+    /** JSON Schema constraining the final assistant message (`outputSchema`). */
+    outputSchema?: unknown;
+    /** Base instructions for the worker thread (set once; changing it re-creates
+     *  the worker thread). */
+    baseInstructions?: string;
+    /** Reasoning effort for the turn. Defaults to "low". */
+    effort?: string;
+    model?: string | null;
+    /** Model provider (ThreadStartParams.modelProvider) for the worker thread.
+     *  Omit for the Codex default. Part of the worker-thread cache key. */
+    modelProvider?: string | null;
+    abortSignal?: AbortSignal;
+};
+type CodexOneShotResponse = {
+    /** The raw assistant message text. Caller parses/validates against its schema. */
+    rawText: string;
+    threadId: string;
+    turnId: string;
+    userAgent: string;
+    model: string;
+    modelProvider: string;
+    serviceTier: string | null;
+    tokenUsage: NormalizedTokenUsage | null;
+};
+declare class CodexOneShotClient {
+    private readonly options;
+    private readonly requestTimeoutMs;
+    private readonly turnTimeoutMs;
+    private readonly logger;
+    private readonly transportFactory;
+    private resolvedCommand;
+    private connection;
+    private initializeResponse;
+    private pendingTurn;
+    private workerThread;
+    private queue;
+    constructor(options?: CodexOneShotClientOptions);
+    /** Run one structured-output turn. Calls are serialized — only one turn is in
+     *  flight at a time against the shared worker thread. */
+    run(request: CodexOneShotRequest): Promise<CodexOneShotResponse>;
+    private runInner;
+    listModels(input?: {
+        includeHidden?: boolean;
+    }): Promise<CodexModelOption[]>;
+    close(): Promise<void>;
+    private getWorkerThread;
+    private rollbackWorkerThread;
+    private prepareWorkspace;
+    private clearThreadGitInfo;
+    private setWorkerThreadName;
+    private resolveCommand;
+    private initialize;
+    private getConnection;
+    private waitForTurn;
+    private handleNotification;
+    private handleItemCompleted;
+    private handleRawResponseItemCompleted;
+    private handleTurnCompleted;
+    private handleThreadTokenUsageUpdated;
+    private handleServerRequest;
+}
+
+/**
+ * Generic "disable coding-agent scaffolding" config overlay. Hosts spread this
+ * into `CodexStartThreadOptions.config` (optionally merging their own keys).
+ */
+declare const DISABLE_CODING_AGENT_THREAD_CONFIG: Record<string, unknown>;
+
+declare const CODEX_NOTIFICATION_METHODS: {
+    readonly agentMessageDelta: "item/agentMessage/delta";
+    readonly reasoningDelta: "item/reasoning/delta";
+    readonly reasoningTextDelta: "item/reasoning/textDelta";
+    readonly itemStarted: "item/started";
+    readonly itemCompleted: "item/completed";
+    readonly turnStarted: "turn/started";
+    readonly turnCompleted: "turn/completed";
+    readonly tokenUsage: "thread/tokenUsage/updated";
+    readonly threadSettings: "thread/settings/updated";
+    readonly modelRerouted: "model/rerouted";
+    readonly error: "error";
+};
+/** Codex approval ServerRequest methods, normalized into `approval_request`. */
+declare const CODEX_APPROVAL_METHODS: Set<string>;
+/** The dynamic-tool ServerRequest method Codex routes tool invocations on. */
+declare const CODEX_TOOL_CALL_METHOD = "item/tool/call";
+/** Map a Codex `ThreadTokenUsage` (its `last` breakdown) to the neutral shape. */
+declare function normalizeTokenUsage(usage: ThreadTokenUsage): NormalizedTokenUsage;
+/**
+ * Build a `NormalizedToolCall` from a tool-ish `ThreadItem`. Returns `null` for
+ * non-tool items. `kind` defaults to `inferToolKind(name)` unless the item's
+ * native shape already classifies it (a command execution is always "command").
+ */
+declare function normalizeThreadItemToolCall(item: ThreadItem): NormalizedToolCall | null;
+/**
+ * Build a `NormalizedToolCall` from a `DynamicToolCallParams` (the ServerRequest
+ * the adapter must answer). `kind` defaults to `inferToolKind(name)`.
+ */
+declare function normalizeDynamicToolCall(params: DynamicToolCallParams): NormalizedToolCall;
+/** Normalize a Codex approval ServerRequest into a neutral approval request. */
+declare function normalizeApprovalRequest(method: string, params: unknown, approvalId: string): NormalizedApprovalRequest;
+declare function normalizeThreadSettings(notification: ThreadSettingsUpdatedNotification): NormalizedThreadSettings;
+/**
+ * Normalize one native Codex notification into a `NormalizedThreadEvent`.
+ * Returns `null` when the method/payload yields no neutral event (an unknown
+ * method, or an `item/*` carrying a non-streamable item).
+ *
+ * `item/started` for a tool-ish item becomes a `tool_call`; the matching
+ * `item/completed` becomes a `tool_call_update` (so the controller correlates
+ * them by id and merges via `mergeToolCall`). An `agentMessage` `item/completed`
+ * becomes a final `agent_message`.
+ */
+declare function normalizeNotification(method: string, params: unknown): NormalizedThreadEvent | null;
+
+/**
+ * Result of a tool `dispatch`. The agent only ever sees text or image content,
+ * so a structured host error is collapsed to a plain string at this boundary.
+ */
+type ToolDispatchResult = {
+    ok: true;
+    data: unknown;
+} | {
+    ok: true;
+    contentItems: DynamicToolCallOutputContentItem[];
+} | {
+    ok: false;
+    error: string;
+};
+/**
+ * One chat tool. The single audit unit: description (what the agent reads),
+ * `argsSchema` (what the agent must satisfy — validated before dispatch), and
+ * `dispatch` (the host-injected body it resolves to).
+ */
+type ToolSpec<TArgs> = {
+    /** Namespace this tool lives under; matched against `DynamicToolCallParams.namespace`. */
+    namespace: string;
+    /** snake_case agent-facing name, e.g. "library_list". */
+    name: string;
+    /** Agent-readable, terse. Shown verbatim to Codex. */
+    description: string;
+    /** zod schema for the tool arguments; also the source of `inputSchema`. */
+    argsSchema: z.ZodType<TArgs>;
+    /**
+     * Behaviour hints surfaced to the agent / approval UI. Optional per tool;
+     * omit (rather than set `undefined`) when not applicable —
+     * `exactOptionalPropertyTypes` is on.
+     */
+    annotations?: {
+        destructiveHint?: boolean;
+        readOnlyHint?: boolean;
+        idempotentHint?: boolean;
+    };
+    /**
+     * The host-injected dispatch this tool resolves to. Receives the zod-validated
+     * args (typed as `TArgs`) plus the calling thread id.
+     */
+    dispatch: (args: TArgs, ctx: {
+        threadId: string;
+    }) => Promise<ToolDispatchResult>;
+};
+/**
+ * Identity helper that preserves `TArgs` inference at each call site, so a
+ * tool's `dispatch` body is fully type-checked against its own `argsSchema`
+ * without any cast.
+ */
+declare function defineTool<TArgs>(spec: ToolSpec<TArgs>): ToolSpec<TArgs>;
+/**
+ * A `ToolSpec` with its argument type erased — the shape a heterogeneous catalog
+ * holds. `defineTool(...)`'s typed result is assignable to this, so a host writes
+ * `[defineTool(a), defineTool(b)]` and passes it straight to `buildToolCatalog` /
+ * `dispatchToolCall`. Args are validated at runtime, so the erasure is safe.
+ */
+type AnyToolSpec = ToolSpec<any>;
+/**
+ * Convert a `ToolSpec` into the protocol `DynamicToolSpec` registered with Codex
+ * at `thread/start`. The `inputSchema` is derived from the tool's zod
+ * `argsSchema` via zod v4's `z.toJSONSchema()` (JSON Schema draft 2020-12).
+ */
+declare function toDynamicToolSpec(spec: AnyToolSpec): DynamicToolSpec;
+
+/**
+ * Build the `DynamicToolSpec[]` registered with Codex at `thread/start`. Pure
+ * projection of the catalog — an empty catalog yields an empty spec list.
+ */
+declare function buildToolCatalog(catalog: ReadonlyArray<AnyToolSpec>): DynamicToolSpec[];
+/**
+ * Route an incoming `DynamicToolCallParams` to its catalog entry and run it.
+ * Always resolves — never throws — so a malformed or unknown call comes back as
+ * a `success: false` response the agent can recover from.
+ */
+declare function dispatchToolCall(params: DynamicToolCallParams, catalog: ReadonlyArray<AnyToolSpec>): Promise<DynamicToolCallResponse>;
+
+/** The backend the controller drives. Codex (`CodexThreadClient`) and ACP
+ *  (`AcpAgentClient`) both implement the non-generic `AgentBackend`; the
+ *  controller builds NEUTRAL thread/turn options, so any backend drops in
+ *  identically with no per-backend branching. Retained as an alias to
+ *  `AgentBackend` so existing hosts that name `ChatBackend` keep compiling. */
+type ChatBackend = AgentBackend;
+/** Builds the per-thread system prompt (base + host guidance). Injected as
+ *  `baseInstructions` at thread/start. Receives the frozen settings snapshot and
+ *  the thread's anchor; the controller never inspects `TSettings`. */
+type ChatSystemPromptBuilder<TSettings = unknown> = (input: {
+    settings: TSettings;
+    anchorId: string | null;
+}) => string;
+/**
+ * The neutral event union the controller broadcasts. The host maps these to its
+ * own IPC. Surface-agnostic: a library-chat host and a sizzle-chat host map the
+ * same union. Generalizes PwrSnap's six typed `events:*Chat:*` channels.
+ */
+type ChatControllerEvent = {
+    type: "thread_updated";
+    thread: NormalizedThreadView;
+} | {
+    type: "stream_delta";
+    threadId: string;
+    turnId: string;
+    messageId: string;
+    delta: string;
+} | {
+    type: "tool_call";
+    threadId: string;
+    turnId: string;
+    toolCall: NormalizedToolCall;
+} | {
+    type: "message_committed";
+    threadId: string;
+    message: NormalizedMessage;
+} | {
+    type: "turn_interrupted";
+    threadId: string;
+    turnId: string;
+} | {
+    type: "approval_requested";
+    threadId: string;
+    turnId: string;
+    approval: NormalizedApprovalRequest;
+};
+/** Re-broadcasts the controller's neutral event stream to the host's UI. */
+type ChatBroadcast = (event: ChatControllerEvent) => void;
+/** Friendly present-tense labels for tool activity chips, keyed by tool name. */
+type ToolLabelMap = Record<string, string>;
+type ChatThreadControllerDeps<TSettings = unknown> = {
+    /** The shared backend (Codex or ACP). */
+    client: ChatBackend;
+    /** Host persistence: thread index + per-turn journal + usage accounting. */
+    store: ThreadStore;
+    /** Reads the current host settings snapshot (frozen per turn). */
+    readSettings: () => Promise<TSettings>;
+    /** Re-broadcasts neutral controller events to the host UI. */
+    broadcast: ChatBroadcast;
+    /** Builds the per-thread system prompt. */
+    buildSystemPrompt: ChatSystemPromptBuilder<TSettings>;
+    /** Per-turn runtime context (L3), sent as a leading turn item framed as
+     *  system-generated — never folded into the user's message. Receives the
+     *  turn's anchor. Omit for no per-turn context. */
+    buildTurnContext?: (anchor: string) => string;
+    /** DynamicToolSpec[] registered on every thread/start. */
+    catalog?: DynamicToolSpec[];
+    /** Routes an incoming tool call to the host's tools. Defaults to a no-tools
+     *  responder when omitted. */
+    dispatchToolCall?: (params: DynamicToolCallParams) => Promise<DynamicToolCallResponse>;
+    /** Friendly chip labels for tool activity. */
+    toolLabels?: ToolLabelMap;
+    /** Default-Access policy applied to every chat thread. */
+    approvalPolicy?: string;
+    sandbox?: string;
+    /** Default serviceName for thread/start. */
+    serviceName?: string;
+    /** Per-thread Codex config overlay applied on every thread/start. */
+    threadConfig?: Record<string, unknown>;
+    /** Thread environments. `[]` disables exec-environment access. */
+    threadEnvironments?: unknown[];
+    /** Reasoning effort for turns. Defaults to "medium". */
+    effort?: string;
+    /** Default model id for thread/start (host's per-surface default). Omit for Codex default. */
+    model?: string;
+    /** Default model provider for thread/start — the "provider" a host picks when
+     *  more than one is configured. Omit for Codex default. */
+    modelProvider?: string;
+    logger?: Logger;
+    /** Injectable clock for tests. */
+    now?: () => number;
+};
+declare class ChatThreadController<TSettings = unknown> {
+    private readonly deps;
+    private readonly logger;
+    private readonly turns;
+    private readonly pendingApprovals;
+    /** Per-thread recent turn timestamps for rate limiting. */
+    private readonly turnTimestamps;
+    private readonly threadModels;
+    private wired;
+    constructor(deps: ChatThreadControllerDeps<TSettings>);
+    /** Wire the shared backend's subscription hooks ONCE. Idempotent. */
+    wire(): void;
+    private now;
+    createThread(opts?: {
+        name?: string;
+        anchorId?: string | null;
+    }): Promise<NormalizedThreadView>;
+    listThreads(opts?: {
+        includeArchived?: boolean;
+        anchorId?: string | null;
+    }): Promise<NormalizedThreadView[]>;
+    rename(threadId: string, name: string): Promise<NormalizedThreadView>;
+    archive(threadId: string, archived: boolean): Promise<NormalizedThreadView>;
+    sendMessage(input: {
+        threadId: string;
+        text: string;
+        anchorId?: string | null;
+        /** Local image file paths to attach to this turn. Forwarded neutrally as
+         *  `AgentTurnInput.imagePaths`; the backend maps to its native attachment
+         *  (Codex `localImage`, ACP `image` blocks). */
+        imagePaths?: readonly string[];
+    }): Promise<{
+        turnId: string;
+    }>;
+    getHistory(threadId: string): Promise<NormalizedMessage[]>;
+    interrupt(threadId: string): Promise<void>;
+    resolveApproval(input: {
+        threadId: string;
+        turnId: string;
+        approvalId: string;
+        decision: NormalizedApprovalDecision;
+    }): Promise<void>;
+    private onBackendEvent;
+    private onDelta;
+    private onTurnCompleted;
+    private onTokenUsage;
+    private onToolCall;
+    private onApprovalRequest;
+    private finalizeAssistant;
+    private recordUsage;
+    private commitMessage;
+    private readJournalMessages;
+    private currentAnchor;
+    private enforceRateLimit;
+    private recordTurn;
+    private broadcastThreadStatus;
+    private toView;
+    private defaultName;
+    private randomId;
+}
+/** Local-timezone `YYYY-MM-DD` stamp (NOT `toISOString()`, which is UTC). */
+declare function localDateStamp(d: Date): string;
+
+export { type AnyToolSpec, CODEX_APPROVAL_METHODS, CODEX_NOTIFICATION_METHODS, CODEX_TOOL_CALL_METHOD, type ChatBackend, type ChatBroadcast, type ChatControllerEvent, type ChatSystemPromptBuilder, ChatThreadController, type ChatThreadControllerDeps, type CodexApprovalHandler, type CodexModelOption, CodexOneShotClient, type CodexOneShotClientOptions, type CodexOneShotRequest, type CodexOneShotResponse, type CodexOneShotTransportFactory, type CodexStartThreadOptions, type CodexStartTurnOptions, CodexThreadClient, type CodexThreadClientOptions, type CodexThreadClientTransportFactory, type CodexToolCallHandler, DISABLE_CODING_AGENT_THREAD_CONFIG, type StartThreadResult, type ToolDispatchResult, type ToolLabelMap, type ToolSpec, type Unsubscribe, buildToolCatalog, defineTool, dispatchToolCall, localDateStamp, normalizeApprovalRequest, normalizeDynamicToolCall, normalizeNotification, normalizeThreadItemToolCall, normalizeThreadSettings, normalizeTokenUsage, toDynamicToolSpec };