ai-task-board-bridge 0.9.0

package/README.md

@@ -0,0 +1,253 @@
+# AI Task Board Bridge
+
+`ai-task-board-bridge` is the device-level Codex companion for AI Task
+Board. One long-running Bridge process represents one device/AI Connection. It
+starts the local `codex app-server` over stdio, discovers non-archived top-level
+Codex threads, maps each thread to a Board Session, receives reserved work, and
+streams supported progress back to the Board.
+
+The Bridge uses the Board REST API and authenticated SSE directly. The Board
+MCP server is optional and is not required for Bridge operation.
+
+## Interactive Linux setup
+
+Node.js 18 or newer and a compatible, logged-in `codex` CLI are required. Run
+the Bridge as the same OS user that owns the local Codex data and workspaces:
+
+```bash
+npx --yes ai-task-board-bridge@0.9.0 setup
+```
+
+The setup wizard asks for the Board URL, hidden Connection Token, working
+directory, Codex home and executable, custom-provider credential environment
+variables, thread limits, permission/approval modes, and the Web configuration
+gate. It then installs and starts
+`ai-task-board-bridge.service` in the effective user's systemd user
+manager. Running with no command also enters setup in a TTY when either required
+Board setting is missing.
+
+The generated unit has no `User=` directive: a systemd user manager already
+runs as its owning UID. Setup explicitly binds that user's `HOME` and
+`CODEX_HOME`, captures an absolute Codex executable, stores secrets in a `0600`
+EnvironmentFile, and copies the current package to the user's XDG data directory
+so the service does not depend on an ephemeral npx cache. Do not use `sudo npx`
+unless a root-owned service and root's Codex configuration are actually desired.
+Each Linux user can install an independent unit with the same name; use separate
+Board Connections unless only one of them should acquire the runtime lease.
+Provider variables referenced by `env_key` or `env_http_headers` in
+`config.toml` are detected by name and confirmed with hidden input; setup does
+not copy the user's entire shell environment.
+
+New interactive installs default to `safe` permissions and `decline` approvals.
+The wizard requires an explicit selection before installing, and rerunning it
+updates the configuration and restarts the service. Upgrades disable the legacy
+`ai-task-board-codex-bridge.service` before starting
+`ai-task-board-bridge.service`, with rollback if the new service fails to start.
+
+## Foreground and automation mode
+
+The original environment-variable interface remains available and does not
+install a service:
+
+```bash
+AI_TASK_BOARD_URL='https://board.example.com' \
+AI_TASK_BOARD_CONNECTION_TOKEN='atb_REPLACE_ME' \
+CODEX_WORKING_DIRECTORY='/path/to/a/safe/start-directory' \
+npx --yes ai-task-board-bridge@0.9.0 run
+```
+
+> **High-risk foreground defaults:** when these values are omitted, the Bridge uses
+> `CODEX_BRIDGE_PERMISSION_MODE=danger-full-access` (no sandbox) together with
+> `CODEX_BRIDGE_APPROVAL_MODE=accept` (automatic device-side approval). Use
+> this combination only when the workspace, Codex configuration, and Connection
+> users are trusted. Set `CODEX_BRIDGE_PERMISSION_MODE=safe` explicitly when
+> writes and network access must be constrained.
+
+`CODEX_THREAD_ID` is optional. By default, `CODEX_THREAD_SCOPE=cwd` manages only
+top-level threads whose recorded cwd exactly equals a locally allowlisted directory,
+up to 50 recent matches. Set `CODEX_THREAD_SCOPE=all` only as an explicit,
+high-risk opt-in to cross-project discovery. `CODEX_THREAD_ID` overrides the
+scope with one exact existing-thread compatibility filter:
+
+```bash
+CODEX_THREAD_ID='REPLACE_WITH_LOCAL_THREAD_ID' \
+npx --yes ai-task-board-bridge@0.9.0
+```
+
+Bridge 0.7 and later can manage several exact working directories in one process:
+
+```bash
+CODEX_WORKING_DIRECTORIES='[{"key":"main","name":"Main App","path":"/srv/main"},{"key":"docs","name":"Docs","path":"/srv/docs"}]' \
+CODEX_THREAD_SCOPE='cwd' \
+npx --yes ai-task-board-bridge@0.9.0
+```
+
+The JSON array accepts 1 to 100 unique `{key,name?,path}` entries. Its first
+entry is the App Server startup and local fallback directory. The Board stores
+and returns only a selected key in Web create commands; the Bridge resolves that
+key against the currently effective list.
+
+`CODEX_MAX_THREADS` controls the device-wide inventory limit (default `50`,
+range `1..500` across all configured directories).
+`CODEX_MAX_CONCURRENT_TURNS` remains a compatibility startup value (default
+`2`) before Web configuration is applied; once enabled, the Web value directly
+controls device-wide turn concurrency from `1..32`. Session names do not upload
+the local thread title or first prompt by default; they use the cwd basename plus
+a short thread ID. Set
+`CODEX_BRIDGE_INCLUDE_THREAD_TITLES=true` only after explicitly accepting that
+metadata disclosure. Inventory still uploads each thread ID, absolute working
+directory, and model label to the Board Workspace.
+
+## Optional Web configuration
+
+Web configuration is disabled locally by default. Enable it on the device with
+`CODEX_BRIDGE_WEB_CONFIG=true`; the Bridge then checks `/api/ai/config` every
+10 seconds and applies safe runtime changes without restarting systemd. The
+interval can be set with `AI_TASK_BOARD_CONFIG_POLL_INTERVAL_MS` from `1000` to
+`600000` milliseconds.
+
+The Web console may enable or pause this Bridge, hide or show thread titles,
+enable bounded history sync, lower the thread and history limits, set device-wide
+turn concurrency directly,
+and—only after a separate local opt-in—replace the effective working-directory
+list. `enabled=false` stops all Session
+workers, releases their work, and uploads an authoritative empty inventory,
+while keeping the device Bridge process alive so it can be re-enabled. A
+concurrency reduction lets active turns finish and only delays new turns.
+
+The device environment remains the immutable security boundary:
+
+- Web `max_threads` is clamped to the local `CODEX_MAX_THREADS` maximum.
+- Web `max_concurrent_turns` directly sets device-wide concurrency in the
+  supported `1..32` range; it is not clamped by a separate local maximum.
+- Web title upload is denied unless
+  `CODEX_BRIDGE_ALLOW_REMOTE_THREAD_TITLES=true` or the device already opted in
+  with `CODEX_BRIDGE_INCLUDE_THREAD_TITLES=true`.
+- Web history sync is denied unless the device explicitly sets
+  `CODEX_BRIDGE_ALLOW_HISTORY_SYNC=true`. The requested recent-turn count is
+  clamped to `CODEX_BRIDGE_MAX_HISTORY_TURNS` (default `50`, maximum `200`).
+- Web working-directory configuration is denied unless the device explicitly
+  sets `CODEX_BRIDGE_ALLOW_REMOTE_WORKING_DIRECTORIES=true`. A remote list must
+  contain 1 to 100 unique entries with absolute paths that already exist and are
+  directories. Missing, null, or locally denied remote values retain the
+  immutable `CODEX_WORKING_DIRECTORIES` / `CODEX_WORKING_DIRECTORY` startup list.
+- The Board cannot change the URL/token, Codex executable, thread scope/fixed
+  thread, permission mode, approval mode, or the immutable local fallback list.
+
+The Bridge reports its effective settings, local constraints, applied version,
+and any clamp/gate warning back to the Board. It also holds a renewable runtime
+lease so a second Bridge using the same Connection waits instead of overwriting
+status or starting duplicate workers. With Web configuration disabled, these
+reports continue as lease heartbeats so a new Web console can explain the local
+gate, but the Bridge ignores returned desired settings. A missing config
+endpoint is tolerated in that mode. When Web configuration is explicitly
+enabled, a 404 is fatal so a deployment cannot appear remotely managed when it
+is not. Graceful shutdown releases the runtime lease; after an unclean exit it
+expires within 30 seconds.
+A replacement process waits without starting workers while that old lease is
+still valid. Lease renewal runs independently from inventory/config application,
+at least every 10 seconds, and a local safety deadline stops workers before a
+lease can expire during a prolonged Board outage. The deprecated-Board 404
+fallback cannot provide this single-runtime fence.
+
+## Web Thread management
+
+Bridge 0.5 lets a Workspace owner create, rename, and delete Codex Threads from
+the Web Console. The Board stores each request as a leased command; only the
+Bridge process holding that connection's runtime lease may execute it. New
+Threads use the effective directory selected in the hierarchy. Thread-create
+commands still carry only its stable key, never an absolute path. Rename and delete commands only
+target Threads already present in the Bridge's managed inventory. Fixed
+`CODEX_THREAD_ID` mode rejects create and delete commands.
+
+A delete request is accepted only when the Thread has no active or reserved
+work. It immediately hides and fences the Board Session, then calls the Codex
+App Server's hard-delete method. Compatible older App Server builds that lack
+hard delete fall back to archive. Board audit/history rows are retained.
+
+## Optional bounded history sync
+
+History upload is off by default and requires both
+`CODEX_BRIDGE_ALLOW_HISTORY_SYNC=true` on the device and `sync_history=true` in
+Web configuration. Bridge 0.5 scans at most the configured number of recent
+completed turns for ordinary CLI/VS Code threads in a separate, cancellable,
+bounded background loop. Runtime-lease renewal, inventory, and live turns do
+not wait for this scan.
+
+The user's `userMessage` and the final `agentMessage` are imported. A turn
+carrying a non-empty persisted `clientUserMessageId` is skipped because it came
+from Board live execution.
+Images, local-image/skill paths, raw `reasoning.content`, commands and their
+output, diffs, MCP arguments/results, and every other tool item are discarded
+locally while persisted items are read in pages. The Bridge scans at most 10,000
+raw items in one turn and retains at most 500 whitelisted activities across one
+snapshot. A turn that would cross either hard safety boundary is not partially
+imported; the snapshot stops with `partial` and a `local-safety-cap` marker.
+That marker reports local truncation and is not a resumable App Server cursor.
+Text passes through the Bridge redactor and a UTF-safe 50,000-character limit
+before upload. Stable thread/turn/item references make any rescan idempotent. An
+unchanged `thread.updatedAt` plus turn-limit signature is scanned only once per
+Bridge process; a changed thread, changed limit, or process restart can enqueue
+another idempotent scan. Batches contain at most 100 items and 512 KiB. Other
+scan/import failures use bounded backoff, update only the per-Session history
+status, and do not stop the main Bridge.
+
+Imported history is append-only on the Board, and historical user prompts are
+visible to members who can access the Workspace. Turning history sync off or
+lowering the recent-turn limit stops later imports but does not delete content
+that was already uploaded. Remove that data through the Board's applicable
+Workspace/data deletion flow when required.
+
+The Bridge forwards only agent-message deltas and completed replies. Stream
+chunks are batched for roughly 500 ms or 8 KiB. Reasoning summaries, command
+output, tool/file/plan events, and usage are not uploaded.
+`CODEX_BRIDGE_PERMISSION_MODE=danger-full-access` is the default execution
+profile. It explicitly keeps `on-request` / user-reviewed approval handling but
+runs without a sandbox, so writes and network access are unrestricted within
+the OS user's own permissions. It does not grant root or bypass operating-system
+access controls. This default is intended to keep trusted tasks from stalling on
+sandbox limits, but it is high risk.
+
+Set `CODEX_BRIDGE_PERMISSION_MODE=safe` explicitly to use `workspace-write`,
+limit writable roots to the thread's absolute cwd, exclude implicit tmp roots,
+and disable network access. This primarily constrains writes and network; it
+does not prevent reading files already readable by the same UID. The `inherit`
+mode sends no permission or approval overrides and uses the thread/local Codex
+configuration as-is. It may inherit full access, broader writable roots, or a
+stricter policy, so treat it as high risk when the local configuration is not
+known.
+
+Separately, supported server-initiated approval requests correlated with the
+active turn are automatically accepted on the device by the default
+`CODEX_BRIDGE_APPROVAL_MODE=accept`, without per-request Web confirmation.
+Uncorrelated requests are still denied, blocking `requestUserInput` continues
+through the Web Console, and MCP elicitation remains denied. Approval mode does
+not configure the sandbox. Use `decline` to deny approval requests or
+`accept-session` to extend supported approvals to the session. Automatic
+approval is high risk and is not a Web confirmation flow.
+
+There is currently no reliable running-turn steer, Web-triggered interrupt, or
+Web approval flow. Messages sent while a thread is busy queue as later Tasks.
+Execution is at-least-once, so irreversible actions still need their own
+idempotency or explicit human confirmation.
+
+Version 0.6 forwards blocking Codex `requestUserInput` prompts to the Web
+Console as structured controls. The App Server request, turn, task claim, and
+heartbeats remain active while the Bridge polls; submitting the Web answer
+resolves that same request instead of creating a later turn. Answer values are
+kept out of public messages, and secret inputs are cleared when the claim ends.
+
+Keep the Connection Token in a secret store or protected environment file. Do
+not pass it as a command-line argument. The Bridge removes that token from the
+App Server child environment, but processes under the same OS UID are not a
+strong token-isolation boundary. Use a separate UID and/or a token proxy when
+strong isolation is required. Board schema and `/api/ai/sessions/sync` must be
+upgraded before starting 0.8; there is no 404 fallback to the old registration
+API. On Linux, use `setup` for a pinned local runtime and systemd user service.
+On other platforms, pin version `0.9.0` in launchd or another process manager.
+Run only one Bridge for the same device/Connection, and
+do not let another TUI, IDE, or automation writer submit turns to a managed
+thread at the same time.
+
+Use `npx --yes ai-task-board-bridge@0.9.0 --help` for the complete
+environment-variable list.

package/dist/activity-sanitizer.d.ts

@@ -0,0 +1,5 @@
+/** Best-effort redaction before Harness output crosses into the shared Board. */
+export declare function redactHarnessText(value: string, limit?: number): string;
+export declare function sanitizeHarnessValue(value: unknown, depth?: number): unknown;
+export declare function boundActivityData(value: Record<string, unknown>): Record<string, unknown>;
+//# sourceMappingURL=activity-sanitizer.d.ts.map

package/dist/activity-sanitizer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"activity-sanitizer.d.ts","sourceRoot":"","sources":["../src/activity-sanitizer.ts"],"names":[],"mappings":"AAYA,iFAAiF;AACjF,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,SAAS,GAAG,MAAM,CAkBvE;AAED,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,OAAO,EAAE,KAAK,SAAI,GAAG,OAAO,CAkBvE;AAED,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC7B,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAYzB"}

package/dist/activity-sanitizer.js

@@ -0,0 +1,55 @@
+const MAX_ACTIVITY_DATA_BYTES = 240 * 1024;
+const SENSITIVE_FIELD_PATTERN = /(?:^|_)(?:api_key|authorization|credential|password|private_key|secret(?:_key)?|token)$/;
+function isSensitiveField(key) {
+    const normalized = key
+        .replace(/([a-z\d])([A-Z])/g, "$1_$2")
+        .replace(/[-\s]+/g, "_")
+        .toLowerCase();
+    return SENSITIVE_FIELD_PATTERN.test(normalized);
+}
+/** Best-effort redaction before Harness output crosses into the shared Board. */
+export function redactHarnessText(value, limit = 20_000) {
+    const redacted = value
+        .replace(/\b(?:sk[-_][A-Za-z0-9_-]{12,}|atb_[A-Za-z0-9_-]{12,})\b/g, "[REDACTED]")
+        .replace(/(authorization\s*[:=]\s*bearer\s+)(?:"[^"\r\n]*"|'[^'\r\n]*'|[^\s"']+)/gi, "$1[REDACTED]")
+        .replace(/(\b["']?(?:access[_-]?token|api[_-]?key|bearer[_-]?token|credential|password|private[_-]?key|secret(?:[_-]?key)?|token)["']?\s*[:=]\s*)(?:"[^"\r\n]*"|'[^'\r\n]*'|[^\s,;]+)/gi, "$1[REDACTED]");
+    if (redacted.length <= limit)
+        return redacted;
+    const suffix = "\n…[已截断；完整输出请作为附件上传]";
+    if (limit <= suffix.length)
+        return redacted.slice(0, limit);
+    return `${redacted.slice(0, limit - suffix.length)}${suffix}`;
+}
+export function sanitizeHarnessValue(value, depth = 0) {
+    if (depth > 6)
+        return "[截断：嵌套过深]";
+    if (typeof value === "string")
+        return redactHarnessText(value);
+    if (Array.isArray(value)) {
+        return value.slice(0, 100).map((item) => sanitizeHarnessValue(item, depth + 1));
+    }
+    if (value && typeof value === "object") {
+        const entries = Object.entries(value).slice(0, 100);
+        return Object.fromEntries(entries.map(([key, item]) => [
+            key,
+            isSensitiveField(key)
+                ? "[REDACTED]"
+                : sanitizeHarnessValue(item, depth + 1),
+        ]));
+    }
+    return value;
+}
+export function boundActivityData(value) {
+    const sanitized = sanitizeHarnessValue(value);
+    const encoded = JSON.stringify(sanitized);
+    if (new TextEncoder().encode(encoded).byteLength <= MAX_ACTIVITY_DATA_BYTES) {
+        return sanitized;
+    }
+    return {
+        truncated: true,
+        // 60k UTF-16 code units stay below the API's 256 KiB limit even if every
+        // character requires four UTF-8 bytes.
+        preview: redactHarnessText(encoded, 60_000),
+    };
+}
+//# sourceMappingURL=activity-sanitizer.js.map

package/dist/activity-sanitizer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"activity-sanitizer.js","sourceRoot":"","sources":["../src/activity-sanitizer.ts"],"names":[],"mappings":"AAAA,MAAM,uBAAuB,GAAG,GAAG,GAAG,IAAI,CAAC;AAC3C,MAAM,uBAAuB,GAC3B,yFAAyF,CAAC;AAE5F,SAAS,gBAAgB,CAAC,GAAW;IACnC,MAAM,UAAU,GAAG,GAAG;SACnB,OAAO,CAAC,mBAAmB,EAAE,OAAO,CAAC;SACrC,OAAO,CAAC,SAAS,EAAE,GAAG,CAAC;SACvB,WAAW,EAAE,CAAC;IACjB,OAAO,uBAAuB,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;AAClD,CAAC;AAED,iFAAiF;AACjF,MAAM,UAAU,iBAAiB,CAAC,KAAa,EAAE,KAAK,GAAG,MAAM;IAC7D,MAAM,QAAQ,GAAG,KAAK;SACnB,OAAO,CACN,0DAA0D,EAC1D,YAAY,CACb;SACA,OAAO,CACN,0EAA0E,EAC1E,cAAc,CACf;SACA,OAAO,CACN,+KAA+K,EAC/K,cAAc,CACf,CAAC;IACJ,IAAI,QAAQ,CAAC,MAAM,IAAI,KAAK;QAAE,OAAO,QAAQ,CAAC;IAC9C,MAAM,MAAM,GAAG,sBAAsB,CAAC;IACtC,IAAI,KAAK,IAAI,MAAM,CAAC,MAAM;QAAE,OAAO,QAAQ,CAAC,KAAK,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC;IAC5D,OAAO,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC,EAAE,KAAK,GAAG,MAAM,CAAC,MAAM,CAAC,GAAG,MAAM,EAAE,CAAC;AAChE,CAAC;AAED,MAAM,UAAU,oBAAoB,CAAC,KAAc,EAAE,KAAK,GAAG,CAAC;IAC5D,IAAI,KAAK,GAAG,CAAC;QAAE,OAAO,WAAW,CAAC;IAClC,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,iBAAiB,CAAC,KAAK,CAAC,CAAC;IAC/D,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QACzB,OAAO,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,oBAAoB,CAAC,IAAI,EAAE,KAAK,GAAG,CAAC,CAAC,CAAC,CAAC;IAClF,CAAC;IACD,IAAI,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QACvC,MAAM,OAAO,GAAG,MAAM,CAAC,OAAO,CAAC,KAAgC,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;QAC/E,OAAO,MAAM,CAAC,WAAW,CACvB,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,EAAE,IAAI,CAAC,EAAE,EAAE,CAAC;YAC3B,GAAG;YACH,gBAAgB,CAAC,GAAG,CAAC;gBACnB,CAAC,CAAC,YAAY;gBACd,CAAC,CAAC,oBAAoB,CAAC,IAAI,EAAE,KAAK,GAAG,CAAC,CAAC;SAC1C,CAAC,CACH,CAAC;IACJ,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED,MAAM,UAAU,iBAAiB,CAC/B,KAA8B;IAE9B,MAAM,SAAS,GAAG,oBAAoB,CAAC,KAAK,CAA4B,CAAC;IACzE,MAAM,OAAO,GAAG,IAAI,CAAC,SAAS,CAAC,SAAS,CAAC,CAAC;IAC1C,IAAI,IAAI,WAAW,EAAE,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,UAAU,IAAI,uBAAuB,EAAE,CAAC;QAC5E,OAAO,SAAS,CAAC;IACnB,CAAC;IACD,OAAO;QACL,SAAS,EAAE,IAAI;QACf,yEAAyE;QACzE,uCAAuC;QACvC,OAAO,EAAE,iBAAiB,CAAC,OAAO,EAAE,MAAM,CAAC;KAC5C,CAAC;AACJ,CAAC"}

package/dist/app-server-client.d.ts

@@ -0,0 +1,328 @@
+export type AppServerRequestId = string | number;
+export interface AppServerClientInfo {
+    name: string;
+    title?: string | null;
+    version: string;
+}
+export interface AppServerInitializeCapabilities {
+    experimentalApi?: boolean;
+    requestAttestation?: boolean;
+    mcpServerOpenaiFormElicitation?: boolean;
+    optOutNotificationMethods?: string[] | null;
+    extensions?: Record<string, unknown> | null;
+}
+export interface AppServerInitializeParams {
+    clientInfo: AppServerClientInfo;
+    capabilities?: AppServerInitializeCapabilities | null;
+}
+export interface AppServerInitializeResponse {
+    userAgent: string;
+    codexHome?: string;
+    platformFamily?: string;
+    platformOs?: string;
+    [key: string]: unknown;
+}
+export interface AppServerThread {
+    id: string;
+    source?: unknown;
+    /** Unix timestamp in seconds. */
+    createdAt?: number | null;
+    /** Unix timestamp in seconds; changes when a turn mutates the thread. */
+    updatedAt?: number | null;
+    [key: string]: unknown;
+}
+export type AppServerSortDirection = "asc" | "desc";
+export type AppServerTurnItemsView = "notLoaded" | "summary" | "full";
+export interface AppServerThreadItem {
+    type: string;
+    id?: string;
+    [key: string]: unknown;
+}
+export interface AppServerTurn {
+    id: string;
+    items?: AppServerThreadItem[];
+    itemsView?: AppServerTurnItemsView;
+    status?: "completed" | "interrupted" | "failed" | "inProgress" | string;
+    error?: unknown;
+    /** Unix timestamp in seconds. */
+    startedAt?: number | null;
+    /** Unix timestamp in seconds. */
+    completedAt?: number | null;
+    [key: string]: unknown;
+}
+export interface AppServerUserInput {
+    type: string;
+    [key: string]: unknown;
+}
+export interface AppServerThreadListParams {
+    cursor?: string | null;
+    limit?: number | null;
+    [key: string]: unknown;
+}
+export interface AppServerThreadListResponse {
+    data: AppServerThread[];
+    nextCursor: string | null;
+    backwardsCursor?: string | null;
+    [key: string]: unknown;
+}
+export interface AppServerModelReasoningEffort {
+    reasoningEffort: string;
+    description?: string | null;
+    [key: string]: unknown;
+}
+export interface AppServerModel {
+    id: string;
+    model: string;
+    displayName: string;
+    description?: string | null;
+    hidden?: boolean;
+    defaultReasoningEffort?: string | null;
+    supportedReasoningEfforts?: AppServerModelReasoningEffort[];
+    inputModalities?: string[];
+    supportsPersonality?: boolean;
+    isDefault?: boolean;
+    [key: string]: unknown;
+}
+export interface AppServerModelListParams {
+    cursor?: string | null;
+    limit?: number | null;
+    includeHidden?: boolean;
+    [key: string]: unknown;
+}
+export interface AppServerModelListResponse {
+    data: AppServerModel[];
+    nextCursor: string | null;
+    [key: string]: unknown;
+}
+export interface AppServerThreadReadParams {
+    threadId: string;
+    includeTurns?: boolean;
+    [key: string]: unknown;
+}
+export interface AppServerThreadReadResponse {
+    thread: AppServerThread & {
+        turns?: AppServerTurn[];
+    };
+    [key: string]: unknown;
+}
+export interface AppServerThreadTurnsListParams {
+    threadId: string;
+    cursor?: string | null;
+    limit?: number | null;
+    sortDirection?: AppServerSortDirection | null;
+    itemsView?: AppServerTurnItemsView | null;
+    [key: string]: unknown;
+}
+export interface AppServerThreadTurnsListResponse {
+    data: AppServerTurn[];
+    nextCursor: string | null;
+    backwardsCursor?: string | null;
+    [key: string]: unknown;
+}
+export interface AppServerThreadItemEntry {
+    turnId: string;
+    item: AppServerThreadItem;
+    [key: string]: unknown;
+}
+export interface AppServerThreadItemsListParams {
+    threadId: string;
+    turnId?: string | null;
+    cursor?: string | null;
+    limit?: number | null;
+    sortDirection?: AppServerSortDirection | null;
+    [key: string]: unknown;
+}
+export interface AppServerThreadItemsListResponse {
+    data: AppServerThreadItemEntry[];
+    nextCursor: string | null;
+    backwardsCursor?: string | null;
+    [key: string]: unknown;
+}
+export interface AppServerThreadStartParams {
+    model?: string | null;
+    /** Per-thread Codex config overrides, such as model_reasoning_effort. */
+    config?: Record<string, unknown> | null;
+    [key: string]: unknown;
+}
+export interface AppServerThreadStartResponse {
+    thread: AppServerThread;
+    /** Effective model selected by Codex for this resumed/started Thread. */
+    model?: string | null;
+    /** Effective reasoning effort selected by Codex. */
+    reasoningEffort?: string | null;
+    [key: string]: unknown;
+}
+export interface AppServerThreadResumeParams {
+    threadId: string;
+    model?: string | null;
+    /** Per-thread Codex config overrides, such as model_reasoning_effort. */
+    config?: Record<string, unknown> | null;
+    [key: string]: unknown;
+}
+export type AppServerThreadResumeResponse = AppServerThreadStartResponse;
+export interface AppServerThreadSetNameParams {
+    threadId: string;
+    name: string;
+}
+export type AppServerThreadSetNameResponse = Record<string, never>;
+export interface AppServerThreadDeleteParams {
+    threadId: string;
+}
+export type AppServerThreadDeleteResponse = Record<string, never>;
+export type AppServerThreadArchiveParams = AppServerThreadDeleteParams;
+export type AppServerThreadArchiveResponse = Record<string, never>;
+export interface AppServerTurnStartParams {
+    threadId: string;
+    input: AppServerUserInput[];
+    /** Per-turn model override; Codex keeps it as the Thread default afterward. */
+    model?: string | null;
+    /** Per-turn reasoning override; Codex keeps it as the Thread default afterward. */
+    effort?: string | null;
+    /** Request a provider-exposed reasoning summary for this and later turns. */
+    summary?: "auto" | "concise" | "detailed" | "none" | null;
+    [key: string]: unknown;
+}
+export interface AppServerTurnStartResponse {
+    turn: AppServerTurn;
+    [key: string]: unknown;
+}
+export interface AppServerTurnSteerParams {
+    threadId: string;
+    expectedTurnId: string;
+    input: AppServerUserInput[];
+    [key: string]: unknown;
+}
+export interface AppServerTurnSteerResponse {
+    turnId: string;
+    [key: string]: unknown;
+}
+export interface AppServerTurnInterruptParams {
+    threadId: string;
+    turnId: string;
+    [key: string]: unknown;
+}
+export type AppServerTurnInterruptResponse = Record<string, never>;
+export interface AppServerNotification<P = unknown> {
+    method: string;
+    params: P;
+}
+export interface AppServerIncomingRequest<P = unknown> {
+    id: AppServerRequestId;
+    method: string;
+    params: P;
+}
+export interface AppServerRequestOptions {
+    /** A value of zero disables the timeout for this request. */
+    timeoutMs?: number;
+    /** Cancels the local pending request without waiting for its timeout. */
+    signal?: AbortSignal;
+}
+export type AppServerNotificationListener = (notification: AppServerNotification) => void;
+export type AppServerRequestHandler = (request: AppServerIncomingRequest) => unknown | Promise<unknown>;
+export type AppServerErrorListener = (error: Error) => void;
+export type AppServerStderrListener = (text: string) => void;
+export interface CodexAppServerClientOptions {
+    /** Executable to spawn. Defaults to `codex`. */
+    binary?: string;
+    /** Complete argv for the executable. Defaults to `["app-server", "--stdio"]`. */
+    args?: readonly string[];
+    cwd?: string;
+    /** Environment entries are merged over the current process environment. */
+    env?: NodeJS.ProcessEnv;
+    /** Environment keys to remove after merging, before the child is spawned. */
+    unsetEnv?: readonly string[];
+    requestTimeoutMs?: number;
+    shutdownTimeoutMs?: number;
+    clientInfo?: AppServerClientInfo;
+    capabilities?: AppServerInitializeCapabilities | null;
+    serverRequestHandler?: AppServerRequestHandler;
+    onNotification?: AppServerNotificationListener;
+    onError?: AppServerErrorListener;
+    onStderr?: AppServerStderrListener;
+}
+export declare class AppServerRpcError extends Error {
+    readonly code: number;
+    readonly data?: unknown;
+    readonly requestId?: AppServerRequestId;
+    readonly method?: string;
+    constructor(code: number, message: string, options?: {
+        data?: unknown;
+        requestId?: AppServerRequestId;
+        method?: string;
+    });
+}
+export declare class AppServerRequestTimeoutError extends Error {
+    readonly requestId: AppServerRequestId;
+    readonly method: string;
+    readonly timeoutMs: number;
+    constructor(requestId: AppServerRequestId, method: string, timeoutMs: number);
+}
+export declare class AppServerClientClosedError extends Error {
+    constructor(message?: string);
+}
+/**
+ * A single-process client for the newline-delimited Codex App Server protocol.
+ * Constructing the client spawns the process; call `initialize()` before using
+ * thread/turn helpers, or use `CodexAppServerClient.connect()`.
+ */
+export declare class CodexAppServerClient {
+    private readonly child;
+    private readonly lines;
+    private readonly defaultRequestTimeoutMs;
+    private readonly shutdownTimeoutMs;
+    private readonly defaultInitializeParams;
+    private readonly pending;
+    private readonly notificationListeners;
+    private readonly errorListeners;
+    private readonly stderrListeners;
+    private readonly exitPromise;
+    private resolveExit;
+    private requestHandler;
+    private nextRequestId;
+    private exited;
+    private closing;
+    private closePromise;
+    private initializePromise;
+    private initializeResult;
+    constructor(options?: CodexAppServerClientOptions);
+    static connect(options?: CodexAppServerClientOptions): Promise<CodexAppServerClient>;
+    get pid(): number | undefined;
+    get isClosed(): boolean;
+    get isInitialized(): boolean;
+    get pendingRequestCount(): number;
+    onNotification(listener: AppServerNotificationListener): () => void;
+    onError(listener: AppServerErrorListener): () => void;
+    onStderr(listener: AppServerStderrListener): () => void;
+    setServerRequestHandler(handler: AppServerRequestHandler | null): void;
+    initialize(params?: AppServerInitializeParams): Promise<AppServerInitializeResponse>;
+    request<T = unknown>(method: string, params?: unknown, options?: AppServerRequestOptions): Promise<T>;
+    notify(method: string, params?: unknown): Promise<void>;
+    threadList(params?: AppServerThreadListParams, options?: AppServerRequestOptions): Promise<AppServerThreadListResponse>;
+    modelList(params?: AppServerModelListParams, options?: AppServerRequestOptions): Promise<AppServerModelListResponse>;
+    threadRead(params: AppServerThreadReadParams, options?: AppServerRequestOptions): Promise<AppServerThreadReadResponse>;
+    threadTurnsList(params: AppServerThreadTurnsListParams, options?: AppServerRequestOptions): Promise<AppServerThreadTurnsListResponse>;
+    threadItemsList(params: AppServerThreadItemsListParams, options?: AppServerRequestOptions): Promise<AppServerThreadItemsListResponse>;
+    threadStart(params?: AppServerThreadStartParams, options?: AppServerRequestOptions): Promise<AppServerThreadStartResponse>;
+    threadResume(params: AppServerThreadResumeParams, options?: AppServerRequestOptions): Promise<AppServerThreadResumeResponse>;
+    threadSetName(params: AppServerThreadSetNameParams, options?: AppServerRequestOptions): Promise<AppServerThreadSetNameResponse>;
+    threadDelete(params: AppServerThreadDeleteParams, options?: AppServerRequestOptions): Promise<AppServerThreadDeleteResponse>;
+    threadArchive(params: AppServerThreadArchiveParams, options?: AppServerRequestOptions): Promise<AppServerThreadArchiveResponse>;
+    turnStart(params: AppServerTurnStartParams, options?: AppServerRequestOptions): Promise<AppServerTurnStartResponse>;
+    turnSteer(params: AppServerTurnSteerParams, options?: AppServerRequestOptions): Promise<AppServerTurnSteerResponse>;
+    turnInterrupt(params: AppServerTurnInterruptParams, options?: AppServerRequestOptions): Promise<AppServerTurnInterruptResponse>;
+    close(): Promise<void>;
+    private initializedRequest;
+    private allocateRequestId;
+    private writeMessage;
+    private handleLine;
+    private handleResponse;
+    private parseRpcError;
+    private handleServerRequest;
+    private rejectPending;
+    private failPending;
+    private reportError;
+    private handleProcessClose;
+    private closeProcess;
+    private waitForExit;
+}
+//# sourceMappingURL=app-server-client.d.ts.map