Initial codex telegram bot source

.env.example

@@ -0,0 +1,18 @@
+TELEGRAM_BOT_TOKEN=
+
+# Use absolute host paths. The socket is mounted at the same path in the container.
+HOST_CODEX_SOCKET=/absolute/path/to/codex-telegram-bot/run/codex.sock
+HOST_CODEX_RUN_DIR=/absolute/path/to/codex-telegram-bot/run
+HOST_UPLOAD_DIR=/absolute/path/to/codex-telegram-bot/uploads
+
+# Host-side SQLite directory mounted to /data in the container.
+DB_DIR=./data
+
+# Leave empty to use Codex defaults.
+DEFAULT_MODEL=
+DEFAULT_SANDBOX=workspace-write
+POLL_TIMEOUT_SECONDS=30
+
+# Container should usually match the host user so SQLite files remain writable.
+BOT_UID=1001
+BOT_GID=1001

.gitignore

@@ -0,0 +1,30 @@
+# Local configuration and secrets
+.env
+.env.*
+!.env.example
+
+# Runtime state
+/data/
+/run/
+/uploads/
+*.db
+*.db-shm
+*.db-wal
+*.sock
+*.pid
+*.log
+
+# Build artifacts
+/bin/
+/dist/
+/build/
+/tmp/
+
+# Go/test artifacts
+*.test
+coverage.out
+
+# Editor/OS noise
+.DS_Store
+.idea/
+.vscode/

Dockerfile

@@ -0,0 +1,16 @@
+FROM golang:1.23-alpine AS build
+
+WORKDIR /src
+COPY go.mod go.sum* ./
+RUN go mod download
+
+COPY . .
+RUN CGO_ENABLED=0 go build -o /out/codex-telegram-bot ./cmd/bot
+
+FROM alpine:3.20
+
+RUN adduser -D -h /home/bot bot
+COPY --from=build /out/codex-telegram-bot /usr/local/bin/codex-telegram-bot
+
+USER bot
+ENTRYPOINT ["/usr/local/bin/codex-telegram-bot"]

PLAN.md

@@ -0,0 +1,97 @@
+# Codex Telegram Bot Hybrid Host/App-Server Plan
+
+## Summary
+
+Create `codex-telegram-bot/` as a Docker Compose managed Go Telegram bot that connects to a **host-launched Codex CLI app-server**. Codex is not containerized: it runs from the installed host `codex` binary, using the host user's `~/.codex`, sandboxing, and workspace paths. The bot runs in Docker Compose, stores state in SQLite, and communicates with Codex through a bind-mounted Unix socket.
+
+## Research
+
+Before implementation, carefully read the official docs and check against the guidelines below. Create/Update them properly if discrepancies or new findings occur. If you are not sure, ask the user for advice/instruction.
+
+- Codex App Server official docs: https://developers.openai.com/codex/app-server
+  - App-server is intended for rich clients with authentication, conversation history, approvals, and streamed agent events.
+  - Protocol is JSON-RPC 2.0 with the `jsonrpc` field omitted.
+  - Important: `unix://` transport is WebSocket over Unix socket using HTTP Upgrade, not raw newline JSON.
+  - Start flow: connect, send `initialize`, send `initialized`, then `thread/start` and `turn/start`.
+  - Generate version-matched protocol schemas with `codex app-server generate-json-schema --out ./schemas`.
+
+- Telegram Bot API official docs: https://core.telegram.org/bots/api
+  - `sendMessage` and `editMessageText` are limited to 1-4096 chars after entity parsing.
+  - Callback buttons require `answerCallbackQuery`.
+  - `getFile` downloads are limited to 20 MB via cloud Bot API.
+  - `sendDocument` supports bot-sent files up to 50 MB via cloud Bot API.
+  - Use long polling for MVP unless webhook deployment is explicitly needed.
+
+- Telegram bot feature docs: https://core.telegram.org/bots/features
+  - Validate commands server-side regardless of BotFather command scopes.
+  - Reject group/supergroup/channel updates in code even if group joining is disabled.
+  - Use inline keyboards for approve/deny/details actions.
+
+## Key requirements
+
+- Scaffold a Go bot project:
+  - `cmd/bot` for the bot process.
+  - `internal/telegram` for commands, callbacks, message rendering, and Telegram file downloads.
+  - `internal/codexapp` for app-server WebSocket-over-Unix-socket JSON-RPC.
+  - `internal/store` for SQLite state and migrations.
+  - `scripts/start-codex-app-server`, `scripts/allow-user`, `scripts/remove-user`, `scripts/list-users`, `scripts/add-workspace`, `scripts/list-workspaces`.
+
+- Docker Compose runs only the bot:
+  - Build the Go bot image locally.
+  - Mount persistent SQLite data.
+  - Bind-mount the host socket path into the bot container.
+  - Bind-mount an upload staging directory at the same absolute path visible to host Codex.
+  - Do not install or run Codex CLI inside the bot container.
+
+- Host Codex app-server:
+  - Started outside Compose with `scripts/start-codex-app-server`.
+  - Default command: `codex app-server --listen unix://$HOST_CODEX_SOCKET`.
+  - Uses host `~/.codex`, host workspaces, and host sandbox behavior.
+  - Socket defaults to an absolute path under the project, e.g. `/home/.../codex-telegram-bot/run/codex.sock`.
+
+- Telegram UX:
+  - One-to-one chats only; reject groups, supergroups, and channels.
+  - Allowlisted Telegram user IDs only.
+  - Commands: `/start`, `/help`, `/new`, `/threads`, `/resume`, `/fork`, `/archive`, `/status`, `/cancel`, `/workspaces`, `/workspace`, `/model`, `/sandbox`, `/diff`.
+  - Plain text continues the active Codex thread, creating one if needed.
+  - Send assistant messages and rendered tool/status blocks as separate Telegram messages; chunk only when a single message exceeds Telegram limits.
+  - Send long output, logs, and diffs as chunked messages.
+  - Consider using HTML to render if markdown is weak/awkward.
+  - Render Codex approval requests as inline keyboards with approve, deny, and details actions.
+
+- SQLite state:
+  - `allowed_users`, `workspaces`, `sessions`, `threads`, `pending_approvals`, `audit_log`.
+  - Workspace paths are host absolute paths used as Codex `cwd`.
+  - The bot does not need direct workspace access except for upload staging.
+
+## Test Plan
+Any interactive related test that requires user action should be done properly - ask the user to do X in telegram, then verify.
+
+- Unit tests:
+  - Allowlist enforcement and group-chat rejection.
+  - Workspace path validation.
+  - Telegram escaping, chunking, document fallback, and callback validation.
+  - WebSocket-over-Unix-socket JSON-RPC request correlation and reconnect behavior.
+  - SQLite migrations and admin scripts.
+
+- Integration tests:
+  - Use a low/mini model in codex for testing.
+  - Verify initialize, thread start, turn start, streamed output, approval, and cancellation.
+  - Verify `/start`, `/new`, `/threads`, `/resume`, `/workspace`, `/cancel`, image input, and document staging.
+  - Verify non-allowlisted users are rejected and logged.
+
+- Manual acceptance:
+  - Start host Codex app-server with `scripts/start-codex-app-server`.
+  - Run `docker compose up --build`.
+  - Add an allowlisted user and workspace with scripts.
+  - In a one-to-one Telegram chat, run `/start`, select workspace, create a thread, send a prompt, approve a Codex request, inspect output, and cancel a running turn.
+
+## Assumptions
+
+- Bot runtime is Docker Compose.
+- Codex CLI app-server is launched from the installed host binary, outside Docker.
+- The Unix socket is the only v1 connection between bot and Codex.
+- Go is used for the bot.
+- SQLite is used for state and admin-managed allowlist/workspaces.
+- Codex-in-container and `codex exec` are both out of scope for MVP.
+- This computer is resource limited. Use docker/docker compose for large tools/SDKs to avoid installing locally.

README.md

@@ -0,0 +1,49 @@
+# Codex Telegram Bot
+
+Docker Compose runs only the Go Telegram bot. Codex runs on the host through `codex app-server` and is reached through a bind-mounted Unix socket.
+
+## Setup
+
+1. Copy `.env.example` to `.env` and set `TELEGRAM_BOT_TOKEN`, `HOST_CODEX_SOCKET`, and `HOST_UPLOAD_DIR`.
+2. Start the host Codex app-server:
+
+   ```sh
+   scripts/start-codex-app-server
+   ```
+
+   The script starts Codex detached, writes `run/codex-app-server.pid`, logs to `run/codex-app-server.log`, and is idempotent if the socket is already live.
+
+3. Add at least one Telegram user and workspace:
+
+   ```sh
+   scripts/allow-user 123456789 username
+   scripts/add-workspace /absolute/path/to/workspace "Workspace name" --default
+   ```
+
+4. Build the bot binary when source changes:
+
+   ```sh
+   scripts/build-bot
+   ```
+
+5. Start or restart the bot without rebuilding:
+
+   ```sh
+   docker compose up -d
+   ```
+
+   For normal restarts, use `docker compose restart bot`. The container runs `./bin/codex-telegram-bot` mounted read-only into Alpine; Compose does not compile Go code.
+
+## Commands
+
+The bot accepts one-to-one chats from allowlisted Telegram user IDs only. It rejects group, supergroup, and channel updates in code.
+
+Supported commands: `/start`, `/help`, `/new`, `/threads`, `/resume`, `/fork`, `/archive`, `/status`, `/cancel`, `/workspaces`, `/workspace`, `/model`, `/sandbox`, `/diff`. `/model` lists available Codex models as inline buttons, then shows reasoning-effort buttons for the selected model.
+
+Plain text continues the active Codex thread and creates one if needed. Telegram images are staged under `HOST_UPLOAD_DIR` and sent as `localImage` inputs. Other uploaded documents are staged and passed to Codex as host-visible file paths.
+
+## Notes
+
+- `HOST_UPLOAD_DIR` must be the same absolute path inside the bot container and on the host so host Codex can read staged files.
+- `HOST_CODEX_SOCKET` must point to the host app-server socket. `HOST_CODEX_RUN_DIR` is mounted into the bot container at the same absolute path so socket recreation is visible without rebuilding.
+- Use long polling for the MVP; webhooks are not required.

cmd/admin/main.go

@@ -0,0 +1,172 @@
+package main
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"os"
+	"path/filepath"
+	"strconv"
+	"strings"
+
+	"codex-telegram-bot/internal/store"
+)
+
+func main() {
+	if err := run(context.Background(), os.Args[1:]); err != nil {
+		fmt.Fprintf(os.Stderr, "error: %v\n", err)
+		os.Exit(1)
+	}
+}
+
+func run(ctx context.Context, args []string) error {
+	if len(args) == 0 {
+		return usage()
+	}
+	dbPath := os.Getenv("DB_PATH")
+	if dbPath == "" {
+		dbPath = filepath.Join("data", "bot.db")
+	}
+	st, err := store.Open(ctx, dbPath)
+	if err != nil {
+		return err
+	}
+	defer st.Close()
+
+	switch args[0] {
+	case "allow-user":
+		return allowUser(ctx, st, args[1:])
+	case "remove-user":
+		return removeUser(ctx, st, args[1:])
+	case "list-users":
+		return listUsers(ctx, st)
+	case "add-workspace":
+		return addWorkspace(ctx, st, args[1:])
+	case "list-workspaces":
+		return listWorkspaces(ctx, st)
+	default:
+		return usage()
+	}
+}
+
+func usage() error {
+	return errors.New(`usage:
+  admin allow-user TELEGRAM_USER_ID [username] [notes...]
+  admin remove-user TELEGRAM_USER_ID
+  admin list-users
+  admin add-workspace ABSOLUTE_PATH [label] [--default]
+  admin list-workspaces`)
+}
+
+func allowUser(ctx context.Context, st *store.Store, args []string) error {
+	if len(args) < 1 {
+		return errors.New("allow-user requires TELEGRAM_USER_ID")
+	}
+	userID, err := strconv.ParseInt(args[0], 10, 64)
+	if err != nil {
+		return fmt.Errorf("invalid telegram user id: %w", err)
+	}
+	username := ""
+	notes := ""
+	if len(args) >= 2 {
+		username = args[1]
+	}
+	if len(args) >= 3 {
+		notes = strings.Join(args[2:], " ")
+	}
+	if err := st.AddAllowedUser(ctx, userID, username, notes); err != nil {
+		return err
+	}
+	fmt.Printf("allowed user %d\n", userID)
+	return nil
+}
+
+func removeUser(ctx context.Context, st *store.Store, args []string) error {
+	if len(args) != 1 {
+		return errors.New("remove-user requires TELEGRAM_USER_ID")
+	}
+	userID, err := strconv.ParseInt(args[0], 10, 64)
+	if err != nil {
+		return fmt.Errorf("invalid telegram user id: %w", err)
+	}
+	if err := st.RemoveAllowedUser(ctx, userID); err != nil {
+		return err
+	}
+	fmt.Printf("removed user %d\n", userID)
+	return nil
+}
+
+func listUsers(ctx context.Context, st *store.Store) error {
+	users, err := st.ListAllowedUsers(ctx)
+	if err != nil {
+		return err
+	}
+	if len(users) == 0 {
+		fmt.Println("no allowed users")
+		return nil
+	}
+	for _, user := range users {
+		if user.Username == "" && user.Notes == "" {
+			fmt.Printf("%d\n", user.TelegramUserID)
+			continue
+		}
+		fmt.Printf("%d\t%s\t%s\n", user.TelegramUserID, user.Username, user.Notes)
+	}
+	return nil
+}
+
+func addWorkspace(ctx context.Context, st *store.Store, args []string) error {
+	if len(args) < 1 {
+		return errors.New("add-workspace requires ABSOLUTE_PATH")
+	}
+	path := args[0]
+	label := ""
+	isDefault := false
+	for _, arg := range args[1:] {
+		if arg == "--default" {
+			isDefault = true
+			continue
+		}
+		if label == "" {
+			label = arg
+			continue
+		}
+		label += " " + arg
+	}
+	clean, err := store.ValidateWorkspacePath(path)
+	if err != nil {
+		return err
+	}
+	info, err := os.Stat(clean)
+	if err != nil {
+		return fmt.Errorf("workspace path is not accessible: %w", err)
+	}
+	if !info.IsDir() {
+		return errors.New("workspace path must be a directory")
+	}
+	workspace, err := st.AddWorkspace(ctx, clean, label, isDefault)
+	if err != nil {
+		return err
+	}
+	fmt.Printf("workspace %d\t%s\t%s\n", workspace.ID, workspace.Label, workspace.Path)
+	return nil
+}
+
+func listWorkspaces(ctx context.Context, st *store.Store) error {
+	workspaces, err := st.ListWorkspaces(ctx)
+	if err != nil {
+		return err
+	}
+	if len(workspaces) == 0 {
+		fmt.Println("no workspaces")
+		return nil
+	}
+	for _, workspace := range workspaces {
+		marker := ""
+		if workspace.IsDefault {
+			marker = "default"
+		}
+		fmt.Printf("%d\t%s\t%s\t%s\n", workspace.ID, marker, workspace.Label, workspace.Path)
+	}
+	return nil
+}

cmd/bot/main.go

@@ -0,0 +1,44 @@
+package main
+
+import (
+	"context"
+	"log"
+	"os"
+	"os/signal"
+	"syscall"
+
+	"codex-telegram-bot/internal/codexapp"
+	"codex-telegram-bot/internal/config"
+	"codex-telegram-bot/internal/store"
+	"codex-telegram-bot/internal/telegram"
+)
+
+func main() {
+	logger := log.New(os.Stdout, "", log.LstdFlags)
+	ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM)
+	defer stop()
+
+	cfg, err := config.Load()
+	if err != nil {
+		logger.Fatalf("config: %v", err)
+	}
+	if err := os.MkdirAll(cfg.UploadDir, 0o755); err != nil {
+		logger.Fatalf("upload dir: %v", err)
+	}
+
+	st, err := store.Open(ctx, cfg.DatabasePath)
+	if err != nil {
+		logger.Fatalf("store: %v", err)
+	}
+	defer st.Close()
+
+	tg := telegram.NewClient(cfg.TelegramToken)
+	codex := codexapp.New(cfg.CodexSocketPath, cfg.AppVersion)
+	defer codex.Close()
+
+	bot := telegram.NewBot(tg, st, codex, cfg.UploadDir, cfg.DefaultModel, cfg.DefaultSandbox, cfg.PollTimeout, logger)
+	logger.Printf("bot starting: db=%s codex_socket=%s upload_dir=%s", cfg.DatabasePath, cfg.CodexSocketPath, cfg.UploadDir)
+	if err := bot.Run(ctx); err != nil && err != context.Canceled {
+		logger.Fatalf("bot: %v", err)
+	}
+}

docker-compose.yml

@@ -0,0 +1,23 @@
+services:
+  bot:
+    image: alpine:3.20
+    restart: unless-stopped
+    user: "${BOT_UID:-1001}:${BOT_GID:-1001}"
+    entrypoint: ["/app/codex-telegram-bot"]
+    env_file:
+      - path: .env
+        required: false
+    environment:
+      TELEGRAM_BOT_TOKEN: ${TELEGRAM_BOT_TOKEN:?set TELEGRAM_BOT_TOKEN}
+      DEFAULT_MODEL: ${DEFAULT_MODEL:-}
+      DEFAULT_SANDBOX: ${DEFAULT_SANDBOX:-workspace-write}
+      POLL_TIMEOUT_SECONDS: ${POLL_TIMEOUT_SECONDS:-30}
+      DB_PATH: /data/bot.db
+      HOST_CODEX_SOCKET: ${HOST_CODEX_SOCKET:?set HOST_CODEX_SOCKET}
+      HOST_UPLOAD_DIR: ${HOST_UPLOAD_DIR:?set HOST_UPLOAD_DIR}
+      HOST_CODEX_RUN_DIR: ${HOST_CODEX_RUN_DIR:?set HOST_CODEX_RUN_DIR}
+    volumes:
+      - ./bin/codex-telegram-bot:/app/codex-telegram-bot:ro
+      - ${DB_DIR:-./data}:/data
+      - ${HOST_CODEX_RUN_DIR:?set HOST_CODEX_RUN_DIR}:${HOST_CODEX_RUN_DIR:?set HOST_CODEX_RUN_DIR}
+      - ${HOST_UPLOAD_DIR:?set HOST_UPLOAD_DIR}:${HOST_UPLOAD_DIR:?set HOST_UPLOAD_DIR}

go.mod

@@ -0,0 +1,24 @@
+module codex-telegram-bot
+
+go 1.23.2
+
+require (
+	github.com/gorilla/websocket v1.5.3
+	modernc.org/sqlite v1.33.1
+)
+
+require (
+	github.com/dustin/go-humanize v1.0.1 // indirect
+	github.com/google/uuid v1.6.0 // indirect
+	github.com/hashicorp/golang-lru/v2 v2.0.7 // indirect
+	github.com/mattn/go-isatty v0.0.20 // indirect
+	github.com/ncruces/go-strftime v0.1.9 // indirect
+	github.com/remyoudompheng/bigfft v0.0.0-20230129092748-24d4a6f8daec // indirect
+	golang.org/x/sys v0.22.0 // indirect
+	modernc.org/gc/v3 v3.0.0-20240107210532-573471604cb6 // indirect
+	modernc.org/libc v1.55.3 // indirect
+	modernc.org/mathutil v1.6.0 // indirect
+	modernc.org/memory v1.8.0 // indirect
+	modernc.org/strutil v1.2.0 // indirect
+	modernc.org/token v1.1.0 // indirect
+)

go.sum

@@ -0,0 +1,51 @@
+github.com/dustin/go-humanize v1.0.1 h1:GzkhY7T5VNhEkwH0PVJgjz+fX1rhBrR7pRT3mDkpeCY=
+github.com/dustin/go-humanize v1.0.1/go.mod h1:Mu1zIs6XwVuF/gI1OepvI0qD18qycQx+mFykh5fBlto=
+github.com/google/pprof v0.0.0-20240409012703-83162a5b38cd h1:gbpYu9NMq8jhDVbvlGkMFWCjLFlqqEZjEmObmhUy6Vo=
+github.com/google/pprof v0.0.0-20240409012703-83162a5b38cd/go.mod h1:kf6iHlnVGwgKolg33glAes7Yg/8iWP8ukqeldJSO7jw=
+github.com/google/uuid v1.6.0 h1:NIvaJDMOsjHA8n1jAhLSgzrAzy1Hgr+hNrb57e+94F0=
+github.com/google/uuid v1.6.0/go.mod h1:TIyPZe4MgqvfeYDBFedMoGGpEw/LqOeaOT+nhxU+yHo=
+github.com/gorilla/websocket v1.5.3 h1:saDtZ6Pbx/0u+bgYQ3q96pZgCzfhKXGPqt7kZ72aNNg=
+github.com/gorilla/websocket v1.5.3/go.mod h1:YR8l580nyteQvAITg2hZ9XVh4b55+EU/adAjf1fMHhE=
+github.com/hashicorp/golang-lru/v2 v2.0.7 h1:a+bsQ5rvGLjzHuww6tVxozPZFVghXaHOwFs4luLUK2k=
+github.com/hashicorp/golang-lru/v2 v2.0.7/go.mod h1:QeFd9opnmA6QUJc5vARoKUSoFhyfM2/ZepoAG6RGpeM=
+github.com/mattn/go-isatty v0.0.20 h1:xfD0iDuEKnDkl03q4limB+vH+GxLEtL/jb4xVJSWWEY=
+github.com/mattn/go-isatty v0.0.20/go.mod h1:W+V8PltTTMOvKvAeJH7IuucS94S2C6jfK/D7dTCTo3Y=
+github.com/ncruces/go-strftime v0.1.9 h1:bY0MQC28UADQmHmaF5dgpLmImcShSi2kHU9XLdhx/f4=
+github.com/ncruces/go-strftime v0.1.9/go.mod h1:Fwc5htZGVVkseilnfgOVb9mKy6w1naJmn9CehxcKcls=
+github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=
+github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
+github.com/remyoudompheng/bigfft v0.0.0-20230129092748-24d4a6f8daec h1:W09IVJc94icq4NjY3clb7Lk8O1qJ8BdBEF8z0ibU0rE=
+github.com/remyoudompheng/bigfft v0.0.0-20230129092748-24d4a6f8daec/go.mod h1:qqbHyh8v60DhA7CoWK5oRCqLrMHRGoxYCSS9EjAz6Eo=
+golang.org/x/mod v0.16.0 h1:QX4fJ0Rr5cPQCF7O9lh9Se4pmwfwskqZfq5moyldzic=
+golang.org/x/mod v0.16.0/go.mod h1:hTbmBsO62+eylJbnUtE2MGJUyE7QWk4xUqPFrRgJ+7c=
+golang.org/x/sys v0.6.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
+golang.org/x/sys v0.22.0 h1:RI27ohtqKCnwULzJLqkv897zojh5/DwS/ENaMzUOaWI=
+golang.org/x/sys v0.22.0/go.mod h1:/VUhepiaJMQUp4+oa/7Zr1D23ma6VTLIYjOOTFZPUcA=
+golang.org/x/tools v0.19.0 h1:tfGCXNR1OsFG+sVdLAitlpjAvD/I6dHDKnYrpEZUHkw=
+golang.org/x/tools v0.19.0/go.mod h1:qoJWxmGSIBmAeriMx19ogtrEPrGtDbPK634QFIcLAhc=
+modernc.org/cc/v4 v4.21.4 h1:3Be/Rdo1fpr8GrQ7IVw9OHtplU4gWbb+wNgeoBMmGLQ=
+modernc.org/cc/v4 v4.21.4/go.mod h1:HM7VJTZbUCR3rV8EYBi9wxnJ0ZBRiGE5OeGXNA0IsLQ=
+modernc.org/ccgo/v4 v4.19.2 h1:lwQZgvboKD0jBwdaeVCTouxhxAyN6iawF3STraAal8Y=
+modernc.org/ccgo/v4 v4.19.2/go.mod h1:ysS3mxiMV38XGRTTcgo0DQTeTmAO4oCmJl1nX9VFI3s=
+modernc.org/fileutil v1.3.0 h1:gQ5SIzK3H9kdfai/5x41oQiKValumqNTDXMvKo62HvE=
+modernc.org/fileutil v1.3.0/go.mod h1:XatxS8fZi3pS8/hKG2GH/ArUogfxjpEKs3Ku3aK4JyQ=
+modernc.org/gc/v2 v2.4.1 h1:9cNzOqPyMJBvrUipmynX0ZohMhcxPtMccYgGOJdOiBw=
+modernc.org/gc/v2 v2.4.1/go.mod h1:wzN5dK1AzVGoH6XOzc3YZ+ey/jPgYHLuVckd62P0GYU=
+modernc.org/gc/v3 v3.0.0-20240107210532-573471604cb6 h1:5D53IMaUuA5InSeMu9eJtlQXS2NxAhyWQvkKEgXZhHI=
+modernc.org/gc/v3 v3.0.0-20240107210532-573471604cb6/go.mod h1:Qz0X07sNOR1jWYCrJMEnbW/X55x206Q7Vt4mz6/wHp4=
+modernc.org/libc v1.55.3 h1:AzcW1mhlPNrRtjS5sS+eW2ISCgSOLLNyFzRh/V3Qj/U=
+modernc.org/libc v1.55.3/go.mod h1:qFXepLhz+JjFThQ4kzwzOjA/y/artDeg+pcYnY+Q83w=
+modernc.org/mathutil v1.6.0 h1:fRe9+AmYlaej+64JsEEhoWuAYBkOtQiMEU7n/XgfYi4=
+modernc.org/mathutil v1.6.0/go.mod h1:Ui5Q9q1TR2gFm0AQRqQUaBWFLAhQpCwNcuhBOSedWPo=
+modernc.org/memory v1.8.0 h1:IqGTL6eFMaDZZhEWwcREgeMXYwmW83LYW8cROZYkg+E=
+modernc.org/memory v1.8.0/go.mod h1:XPZ936zp5OMKGWPqbD3JShgd/ZoQ7899TUuQqxY+peU=
+modernc.org/opt v0.1.3 h1:3XOZf2yznlhC+ibLltsDGzABUGVx8J6pnFMS3E4dcq4=
+modernc.org/opt v0.1.3/go.mod h1:WdSiB5evDcignE70guQKxYUl14mgWtbClRi5wmkkTX0=
+modernc.org/sortutil v1.2.0 h1:jQiD3PfS2REGJNzNCMMaLSp/wdMNieTbKX920Cqdgqc=
+modernc.org/sortutil v1.2.0/go.mod h1:TKU2s7kJMf1AE84OoiGppNHJwvB753OYfNl2WRb++Ss=
+modernc.org/sqlite v1.33.1 h1:trb6Z3YYoeM9eDL1O8do81kP+0ejv+YzgyFo+Gwy0nM=
+modernc.org/sqlite v1.33.1/go.mod h1:pXV2xHxhzXZsgT/RtTFAPY6JJDEvOTcTdwADQCCWD4k=
+modernc.org/strutil v1.2.0 h1:agBi9dp1I+eOnxXeiZawM8F4LawKv4NzGWSaLfyeNZA=
+modernc.org/strutil v1.2.0/go.mod h1:/mdcBmfOibveCTBxUl5B5l6W+TTH1FXPLHZE6bTosX0=
+modernc.org/token v1.1.0 h1:Xl7Ap9dKaEs5kLoOQeQmPWevfnk/DM5qcLcYlA8ys6Y=
+modernc.org/token v1.1.0/go.mod h1:UGzOrNV1mAFSEB63lOFHIpNRUVMvYTc6yu1SMY/XTDM=

internal/codexapp/client.go

@@ -0,0 +1,479 @@
+package codexapp
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"net"
+	"net/http"
+	"strings"
+	"sync"
+	"sync/atomic"
+
+	"github.com/gorilla/websocket"
+)
+
+type Client struct {
+	socketPath string
+	version    string
+
+	nextID int64
+
+	mu        sync.Mutex
+	conn      *websocket.Conn
+	pending   map[int64]chan rpcResult
+	events    chan Event
+	connected bool
+}
+
+type Event struct {
+	ID            *int64
+	Method        string
+	Params        json.RawMessage
+	ServerRequest bool
+	Err           error
+}
+
+type RPCError struct {
+	Code    int             `json:"code"`
+	Message string          `json:"message"`
+	Data    json.RawMessage `json:"data,omitempty"`
+}
+
+func (e RPCError) Error() string {
+	if e.Code == 0 {
+		return e.Message
+	}
+	return fmt.Sprintf("%d: %s", e.Code, e.Message)
+}
+
+type Thread struct {
+	ID        string `json:"id"`
+	SessionID string `json:"sessionId,omitempty"`
+	Name      string `json:"name,omitempty"`
+	Preview   string `json:"preview,omitempty"`
+}
+
+type Turn struct {
+	ID     string `json:"id"`
+	Status string `json:"status"`
+}
+
+type InputItem struct {
+	Type string `json:"type"`
+	Text string `json:"text,omitempty"`
+	URL  string `json:"url,omitempty"`
+	Path string `json:"path,omitempty"`
+}
+
+type Model struct {
+	ID                        string                  `json:"id"`
+	Model                     string                  `json:"model"`
+	DisplayName               string                  `json:"displayName"`
+	Description               string                  `json:"description"`
+	IsDefault                 bool                    `json:"isDefault"`
+	DefaultReasoningEffort    string                  `json:"defaultReasoningEffort"`
+	SupportedReasoningEfforts []ReasoningEffortOption `json:"supportedReasoningEfforts"`
+}
+
+type ReasoningEffortOption struct {
+	Description     string `json:"description"`
+	ReasoningEffort string `json:"reasoningEffort"`
+}
+
+func New(socketPath, version string) *Client {
+	return &Client{
+		socketPath: socketPath,
+		version:    version,
+		pending:    make(map[int64]chan rpcResult),
+		events:     make(chan Event, 128),
+	}
+}
+
+func (c *Client) Events() <-chan Event {
+	return c.events
+}
+
+func (c *Client) EnsureConnected(ctx context.Context) error {
+	c.mu.Lock()
+	connected := c.connected && c.conn != nil
+	c.mu.Unlock()
+	if connected {
+		return nil
+	}
+	return c.Connect(ctx)
+}
+
+func (c *Client) Connect(ctx context.Context) error {
+	c.mu.Lock()
+	if c.connected && c.conn != nil {
+		c.mu.Unlock()
+		return nil
+	}
+	c.mu.Unlock()
+
+	dialer := websocket.Dialer{
+		NetDialContext: func(ctx context.Context, network, addr string) (net.Conn, error) {
+			var d net.Dialer
+			return d.DialContext(ctx, "unix", c.socketPath)
+		},
+	}
+	conn, _, err := dialer.DialContext(ctx, "ws://codex-app-server/", http.Header{})
+	if err != nil {
+		return fmt.Errorf("connect codex app-server unix socket %s: %w", c.socketPath, err)
+	}
+
+	c.mu.Lock()
+	c.conn = conn
+	c.connected = true
+	c.mu.Unlock()
+
+	go c.readLoop(conn)
+
+	if err := c.initialize(ctx); err != nil {
+		_ = c.Close()
+		return err
+	}
+	return nil
+}
+
+func (c *Client) Close() error {
+	c.mu.Lock()
+	conn := c.conn
+	c.conn = nil
+	c.connected = false
+	c.mu.Unlock()
+	if conn == nil {
+		return nil
+	}
+	return conn.Close()
+}
+
+func (c *Client) initialize(ctx context.Context) error {
+	params := map[string]any{
+		"clientInfo": map[string]any{
+			"name":    "codex_telegram_bot",
+			"title":   "Codex Telegram Bot",
+			"version": c.version,
+		},
+		"capabilities": map[string]any{
+			"experimentalApi": true,
+		},
+	}
+	var ignored json.RawMessage
+	if err := c.call(ctx, "initialize", params, &ignored); err != nil {
+		return err
+	}
+	return c.notify("initialized", nil)
+}
+
+func (c *Client) StartThread(ctx context.Context, cwd, model, sandbox string) (Thread, error) {
+	if err := c.EnsureConnected(ctx); err != nil {
+		return Thread{}, err
+	}
+	params := map[string]any{
+		"cwd":            cwd,
+		"approvalPolicy": "on-request",
+		"sandbox":        threadSandbox(sandbox),
+		"serviceName":    "codex_telegram_bot",
+	}
+	if model != "" {
+		params["model"] = model
+	}
+	var result struct {
+		Thread Thread `json:"thread"`
+	}
+	if err := c.call(ctx, "thread/start", params, &result); err != nil {
+		return Thread{}, err
+	}
+	return result.Thread, nil
+}
+
+func (c *Client) ResumeThread(ctx context.Context, threadID string) (Thread, error) {
+	if err := c.EnsureConnected(ctx); err != nil {
+		return Thread{}, err
+	}
+	var result struct {
+		Thread Thread `json:"thread"`
+	}
+	if err := c.call(ctx, "thread/resume", map[string]any{"threadId": threadID}, &result); err != nil {
+		return Thread{}, err
+	}
+	return result.Thread, nil
+}
+
+func (c *Client) ForkThread(ctx context.Context, threadID string) (Thread, error) {
+	if err := c.EnsureConnected(ctx); err != nil {
+		return Thread{}, err
+	}
+	var result struct {
+		Thread Thread `json:"thread"`
+	}
+	if err := c.call(ctx, "thread/fork", map[string]any{"threadId": threadID}, &result); err != nil {
+		return Thread{}, err
+	}
+	return result.Thread, nil
+}
+
+func (c *Client) ArchiveThread(ctx context.Context, threadID string) error {
+	if err := c.EnsureConnected(ctx); err != nil {
+		return err
+	}
+	var ignored json.RawMessage
+	return c.call(ctx, "thread/archive", map[string]any{"threadId": threadID}, &ignored)
+}
+
+func (c *Client) StartTurn(ctx context.Context, threadID, cwd, model, reasoningEffort, sandbox string, input []InputItem) (Turn, error) {
+	if err := c.EnsureConnected(ctx); err != nil {
+		return Turn{}, err
+	}
+	params := map[string]any{
+		"threadId":       threadID,
+		"input":          input,
+		"cwd":            cwd,
+		"approvalPolicy": "on-request",
+		"sandboxPolicy":  SandboxPolicy(sandbox, cwd),
+	}
+	if model != "" {
+		params["model"] = model
+	}
+	if reasoningEffort != "" {
+		params["effort"] = reasoningEffort
+	}
+	var result struct {
+		Turn Turn `json:"turn"`
+	}
+	if err := c.call(ctx, "turn/start", params, &result); err != nil {
+		return Turn{}, err
+	}
+	return result.Turn, nil
+}
+
+func (c *Client) InterruptTurn(ctx context.Context, threadID, turnID string) error {
+	if err := c.EnsureConnected(ctx); err != nil {
+		return err
+	}
+	var ignored json.RawMessage
+	return c.call(ctx, "turn/interrupt", map[string]any{
+		"threadId": threadID,
+		"turnId":   turnID,
+	}, &ignored)
+}
+
+func (c *Client) ListModels(ctx context.Context) ([]Model, error) {
+	if err := c.EnsureConnected(ctx); err != nil {
+		return nil, err
+	}
+	var result struct {
+		Data []Model `json:"data"`
+	}
+	if err := c.call(ctx, "model/list", map[string]any{"limit": 50, "includeHidden": false}, &result); err != nil {
+		return nil, err
+	}
+	return result.Data, nil
+}
+
+func (c *Client) RespondServerRequest(ctx context.Context, requestID int64, result any) error {
+	if err := c.EnsureConnected(ctx); err != nil {
+		return err
+	}
+	done := make(chan error, 1)
+	go func() {
+		done <- c.write(responseEnvelope{ID: requestID, Result: result})
+	}()
+	select {
+	case <-ctx.Done():
+		return ctx.Err()
+	case err := <-done:
+		return err
+	}
+}
+
+func (c *Client) call(ctx context.Context, method string, params any, result any) error {
+	id := atomic.AddInt64(&c.nextID, 1)
+	ch := make(chan rpcResult, 1)
+
+	c.mu.Lock()
+	if c.conn == nil {
+		c.mu.Unlock()
+		return errors.New("codex app-server is not connected")
+	}
+	c.pending[id] = ch
+	c.mu.Unlock()
+
+	if err := c.write(requestEnvelope{ID: id, Method: method, Params: params}); err != nil {
+		c.mu.Lock()
+		delete(c.pending, id)
+		c.mu.Unlock()
+		return err
+	}
+
+	select {
+	case <-ctx.Done():
+		c.mu.Lock()
+		delete(c.pending, id)
+		c.mu.Unlock()
+		return ctx.Err()
+	case rpc := <-ch:
+		if rpc.err != nil {
+			return rpc.err
+		}
+		if result == nil || len(rpc.result) == 0 {
+			return nil
+		}
+		return json.Unmarshal(rpc.result, result)
+	}
+}
+
+func (c *Client) notify(method string, params any) error {
+	return c.write(notificationEnvelope{Method: method, Params: params})
+}
+
+func (c *Client) write(message any) error {
+	c.mu.Lock()
+	defer c.mu.Unlock()
+	if c.conn == nil {
+		return errors.New("codex app-server is not connected")
+	}
+	return c.conn.WriteJSON(message)
+}
+
+func (c *Client) readLoop(conn *websocket.Conn) {
+	for {
+		var env incomingEnvelope
+		if err := conn.ReadJSON(&env); err != nil {
+			c.failConnection(conn, err)
+			return
+		}
+		if env.Method != "" && env.ID != nil {
+			c.events <- Event{
+				ID:            env.ID,
+				Method:        env.Method,
+				Params:        env.Params,
+				ServerRequest: true,
+			}
+			continue
+		}
+		if env.ID != nil {
+			c.completeCall(*env.ID, env.Result, env.Error)
+			continue
+		}
+		if env.Method != "" {
+			c.events <- Event{
+				Method: env.Method,
+				Params: env.Params,
+			}
+		}
+	}
+}
+
+func (c *Client) completeCall(id int64, result json.RawMessage, rpcErr *RPCError) {
+	c.mu.Lock()
+	ch := c.pending[id]
+	delete(c.pending, id)
+	c.mu.Unlock()
+	if ch == nil {
+		return
+	}
+	if rpcErr != nil {
+		ch <- rpcResult{err: *rpcErr}
+		return
+	}
+	ch <- rpcResult{result: result}
+}
+
+func (c *Client) failConnection(conn *websocket.Conn, err error) {
+	c.mu.Lock()
+	if c.conn == conn {
+		c.conn = nil
+		c.connected = false
+	}
+	pending := c.pending
+	c.pending = make(map[int64]chan rpcResult)
+	c.mu.Unlock()
+
+	for _, ch := range pending {
+		ch <- rpcResult{err: err}
+	}
+	c.events <- Event{Method: "connection/closed", Err: err}
+}
+
+func DecodeParams[T any](event Event) (T, error) {
+	var value T
+	if len(event.Params) == 0 {
+		return value, nil
+	}
+	err := json.Unmarshal(event.Params, &value)
+	return value, err
+}
+
+func NormalizeSandbox(value string) (string, error) {
+	switch strings.ToLower(strings.TrimSpace(value)) {
+	case "", "workspace-write", "workspacewrite":
+		return "workspace-write", nil
+	case "read-only", "readonly":
+		return "read-only", nil
+	case "danger-full-access", "dangerfullaccess":
+		return "danger-full-access", nil
+	default:
+		return "", fmt.Errorf("unsupported sandbox %q", value)
+	}
+}
+
+func SandboxPolicy(sandbox, cwd string) map[string]any {
+	normalized, err := NormalizeSandbox(sandbox)
+	if err != nil {
+		normalized = "workspace-write"
+	}
+	switch normalized {
+	case "read-only":
+		return map[string]any{"type": "readOnly"}
+	case "danger-full-access":
+		return map[string]any{"type": "dangerFullAccess"}
+	default:
+		return map[string]any{
+			"type":          "workspaceWrite",
+			"writableRoots": []string{cwd},
+			"networkAccess": false,
+		}
+	}
+}
+
+func threadSandbox(sandbox string) string {
+	normalized, err := NormalizeSandbox(sandbox)
+	if err != nil {
+		return "workspace-write"
+	}
+	return normalized
+}
+
+type requestEnvelope struct {
+	ID     int64  `json:"id"`
+	Method string `json:"method"`
+	Params any    `json:"params,omitempty"`
+}
+
+type notificationEnvelope struct {
+	Method string `json:"method"`
+	Params any    `json:"params,omitempty"`
+}
+
+type responseEnvelope struct {
+	ID     int64 `json:"id"`
+	Result any   `json:"result,omitempty"`
+	Error  any   `json:"error,omitempty"`
+}
+
+type incomingEnvelope struct {
+	ID     *int64          `json:"id,omitempty"`
+	Method string          `json:"method,omitempty"`
+	Params json.RawMessage `json:"params,omitempty"`
+	Result json.RawMessage `json:"result,omitempty"`
+	Error  *RPCError       `json:"error,omitempty"`
+}
+
+type rpcResult struct {
+	result json.RawMessage
+	err    error
+}

internal/codexapp/client_test.go

@@ -0,0 +1,155 @@
+package codexapp
+
+import (
+	"context"
+	"encoding/json"
+	"net"
+	"net/http"
+	"os"
+	"path/filepath"
+	"testing"
+	"time"
+
+	"github.com/gorilla/websocket"
+)
+
+func TestClientWebSocketUnixJSONRPC(t *testing.T) {
+	ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
+	defer cancel()
+
+	socketPath := filepath.Join(t.TempDir(), "codex.sock")
+	serverDone := make(chan error, 1)
+	ln, err := net.Listen("unix", socketPath)
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer os.Remove(socketPath)
+
+	upgrader := websocket.Upgrader{}
+	server := &http.Server{Handler: http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		conn, err := upgrader.Upgrade(w, r, nil)
+		if err != nil {
+			serverDone <- err
+			return
+		}
+		defer conn.Close()
+
+		var initialize map[string]any
+		if err := conn.ReadJSON(&initialize); err != nil {
+			serverDone <- err
+			return
+		}
+		if initialize["method"] != "initialize" {
+			serverDone <- unexpectedMessage("initialize", initialize["method"])
+			return
+		}
+		if err := conn.WriteJSON(map[string]any{"id": initialize["id"], "result": map[string]any{"userAgent": "test"}}); err != nil {
+			serverDone <- err
+			return
+		}
+
+		var initialized map[string]any
+		if err := conn.ReadJSON(&initialized); err != nil {
+			serverDone <- err
+			return
+		}
+		if initialized["method"] != "initialized" {
+			serverDone <- unexpectedMessage("initialized", initialized["method"])
+			return
+		}
+
+		if err := conn.WriteJSON(map[string]any{
+			"id":     99,
+			"method": "item/commandExecution/requestApproval",
+			"params": map[string]any{"threadId": "thr_1"},
+		}); err != nil {
+			serverDone <- err
+			return
+		}
+
+		var start map[string]any
+		if err := conn.ReadJSON(&start); err != nil {
+			serverDone <- err
+			return
+		}
+		if start["method"] != "thread/start" {
+			serverDone <- unexpectedMessage("thread/start", start["method"])
+			return
+		}
+		if err := conn.WriteJSON(map[string]any{
+			"id": start["id"],
+			"result": map[string]any{
+				"thread": map[string]any{"id": "thr_1", "preview": "test"},
+			},
+		}); err != nil {
+			serverDone <- err
+			return
+		}
+
+		var response map[string]any
+		if err := conn.ReadJSON(&response); err != nil {
+			serverDone <- err
+			return
+		}
+		if response["id"].(float64) != 99 || response["result"] != "accept" {
+			payload, _ := json.Marshal(response)
+			serverDone <- unexpectedMessage("approval response", string(payload))
+			return
+		}
+		serverDone <- nil
+	})}
+	defer server.Close()
+	go func() {
+		_ = server.Serve(ln)
+	}()
+
+	client := New(socketPath, "test")
+	if err := client.Connect(ctx); err != nil {
+		t.Fatal(err)
+	}
+	defer client.Close()
+
+	select {
+	case event := <-client.Events():
+		if !event.ServerRequest || event.ID == nil || *event.ID != 99 {
+			t.Fatalf("unexpected event: %+v", event)
+		}
+	case <-ctx.Done():
+		t.Fatal(ctx.Err())
+	}
+
+	thread, err := client.StartThread(ctx, "/tmp/project", "", "workspace-write")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if thread.ID != "thr_1" {
+		t.Fatalf("unexpected thread: %+v", thread)
+	}
+	if err := client.RespondServerRequest(ctx, 99, "accept"); err != nil {
+		t.Fatal(err)
+	}
+
+	select {
+	case err := <-serverDone:
+		if err != nil {
+			t.Fatal(err)
+		}
+	case <-ctx.Done():
+		t.Fatal(ctx.Err())
+	}
+}
+
+type errUnexpected string
+
+func (e errUnexpected) Error() string {
+	return "unexpected " + string(e)
+}
+
+func unexpectedMessage(want string, got any) error {
+	return errUnexpected("message: want " + want + ", got " + jsonString(got))
+}
+
+func jsonString(value any) string {
+	data, _ := json.Marshal(value)
+	return string(data)
+}

internal/codexapp/turn.go

@@ -0,0 +1,18 @@
+package codexapp
+
+import (
+	"context"
+	"encoding/json"
+)
+
+func (c *Client) SteerTurn(ctx context.Context, threadID, expectedTurnID string, input []InputItem) error {
+	if err := c.EnsureConnected(ctx); err != nil {
+		return err
+	}
+	var ignored json.RawMessage
+	return c.call(ctx, "turn/steer", map[string]any{
+		"threadId":       threadID,
+		"expectedTurnId": expectedTurnID,
+		"input":          input,
+	}, &ignored)
+}

internal/config/config.go

@@ -0,0 +1,61 @@
+package config
+
+import (
+	"errors"
+	"os"
+	"path/filepath"
+	"strconv"
+	"time"
+)
+
+type Config struct {
+	TelegramToken   string
+	DatabasePath    string
+	CodexSocketPath string
+	UploadDir       string
+	DefaultModel    string
+	DefaultSandbox  string
+	PollTimeout     time.Duration
+	AppVersion      string
+}
+
+func Load() (Config, error) {
+	wd, err := os.Getwd()
+	if err != nil {
+		return Config{}, err
+	}
+
+	cfg := Config{
+		TelegramToken:   os.Getenv("TELEGRAM_BOT_TOKEN"),
+		DatabasePath:    envOr("DB_PATH", filepath.Join(wd, "data", "bot.db")),
+		CodexSocketPath: envOr("HOST_CODEX_SOCKET", filepath.Join(wd, "run", "codex.sock")),
+		UploadDir:       envOr("HOST_UPLOAD_DIR", filepath.Join(wd, "uploads")),
+		DefaultModel:    os.Getenv("DEFAULT_MODEL"),
+		DefaultSandbox:  envOr("DEFAULT_SANDBOX", "workspace-write"),
+		PollTimeout:     durationSeconds("POLL_TIMEOUT_SECONDS", 30),
+		AppVersion:      envOr("APP_VERSION", "0.1.0"),
+	}
+	if cfg.TelegramToken == "" {
+		return Config{}, errors.New("TELEGRAM_BOT_TOKEN is required")
+	}
+	return cfg, nil
+}
+
+func envOr(key, fallback string) string {
+	if value := os.Getenv(key); value != "" {
+		return value
+	}
+	return fallback
+}
+
+func durationSeconds(key string, fallback int) time.Duration {
+	raw := os.Getenv(key)
+	if raw == "" {
+		return time.Duration(fallback) * time.Second
+	}
+	value, err := strconv.Atoi(raw)
+	if err != nil || value <= 0 {
+		return time.Duration(fallback) * time.Second
+	}
+	return time.Duration(value) * time.Second
+}

internal/store/migrations.go

@@ -0,0 +1,94 @@
+package store
+
+type migration struct {
+	Name string
+	SQL  string
+}
+
+var migrations = []migration{
+	{
+		Name: "initial_state",
+		SQL: `
+CREATE TABLE allowed_users (
+	telegram_user_id INTEGER PRIMARY KEY,
+	username TEXT NOT NULL DEFAULT '',
+	notes TEXT NOT NULL DEFAULT '',
+	added_at TEXT NOT NULL DEFAULT (datetime('now'))
+);
+
+CREATE TABLE workspaces (
+	id INTEGER PRIMARY KEY AUTOINCREMENT,
+	path TEXT NOT NULL UNIQUE,
+	label TEXT NOT NULL,
+	is_default INTEGER NOT NULL DEFAULT 0,
+	created_at TEXT NOT NULL DEFAULT (datetime('now'))
+);
+
+CREATE TABLE sessions (
+	telegram_user_id INTEGER PRIMARY KEY,
+	active_thread_id INTEGER,
+	active_workspace_id INTEGER,
+	model TEXT NOT NULL DEFAULT '',
+	sandbox TEXT NOT NULL DEFAULT 'workspace-write',
+	active_turn_id TEXT NOT NULL DEFAULT '',
+	updated_at TEXT NOT NULL DEFAULT (datetime('now')),
+	FOREIGN KEY(active_thread_id) REFERENCES threads(id) ON DELETE SET NULL,
+	FOREIGN KEY(active_workspace_id) REFERENCES workspaces(id) ON DELETE SET NULL
+);
+
+CREATE TABLE threads (
+	id INTEGER PRIMARY KEY AUTOINCREMENT,
+	telegram_user_id INTEGER NOT NULL,
+	codex_thread_id TEXT NOT NULL UNIQUE,
+	workspace_id INTEGER NOT NULL,
+	title TEXT NOT NULL DEFAULT '',
+	archived INTEGER NOT NULL DEFAULT 0,
+	created_at TEXT NOT NULL DEFAULT (datetime('now')),
+	updated_at TEXT NOT NULL DEFAULT (datetime('now')),
+	FOREIGN KEY(workspace_id) REFERENCES workspaces(id) ON DELETE RESTRICT
+);
+
+CREATE INDEX idx_threads_user_updated ON threads(telegram_user_id, archived, updated_at DESC);
+
+CREATE TABLE pending_approvals (
+	id INTEGER PRIMARY KEY AUTOINCREMENT,
+	telegram_user_id INTEGER NOT NULL,
+	codex_request_id TEXT NOT NULL,
+	codex_thread_id TEXT NOT NULL,
+	turn_id TEXT NOT NULL DEFAULT '',
+	item_id TEXT NOT NULL DEFAULT '',
+	kind TEXT NOT NULL,
+	payload_json TEXT NOT NULL,
+	message_chat_id INTEGER NOT NULL DEFAULT 0,
+	message_id INTEGER NOT NULL DEFAULT 0,
+	status TEXT NOT NULL DEFAULT 'pending',
+	created_at TEXT NOT NULL DEFAULT (datetime('now')),
+	resolved_at TEXT NOT NULL DEFAULT '',
+	UNIQUE(telegram_user_id, codex_request_id)
+);
+
+CREATE INDEX idx_pending_approvals_status ON pending_approvals(telegram_user_id, status);
+
+CREATE TABLE audit_log (
+	id INTEGER PRIMARY KEY AUTOINCREMENT,
+	telegram_user_id INTEGER NOT NULL DEFAULT 0,
+	action TEXT NOT NULL,
+	details TEXT NOT NULL DEFAULT '',
+	created_at TEXT NOT NULL DEFAULT (datetime('now'))
+);
+
+CREATE INDEX idx_audit_user_created ON audit_log(telegram_user_id, created_at DESC);
+`,
+	},
+	{
+		Name: "session_reasoning_effort",
+		SQL:  "ALTER TABLE sessions ADD COLUMN reasoning_effort TEXT NOT NULL DEFAULT ''",
+	},
+	{
+		Name: "session_settings_message",
+		SQL: `
+ALTER TABLE sessions ADD COLUMN settings_chat_id INTEGER NOT NULL DEFAULT 0;
+ALTER TABLE sessions ADD COLUMN settings_message_id INTEGER NOT NULL DEFAULT 0;
+`,
+	},
+}

internal/store/store.go

@@ -0,0 +1,516 @@
+package store
+
+import (
+	"context"
+	"database/sql"
+	"errors"
+	"fmt"
+	"os"
+	"path/filepath"
+	"strings"
+
+	_ "modernc.org/sqlite"
+)
+
+type Store struct {
+	db *sql.DB
+}
+
+type AllowedUser struct {
+	TelegramUserID int64
+	Username       string
+	Notes          string
+	AddedAt        string
+}
+
+type Workspace struct {
+	ID        int64
+	Path      string
+	Label     string
+	IsDefault bool
+	CreatedAt string
+}
+
+type Session struct {
+	TelegramUserID    int64
+	ActiveThreadID    int64
+	ActiveWorkspaceID int64
+	Model             string
+	ReasoningEffort   string
+	Sandbox           string
+	ActiveTurnID      string
+	SettingsChatID    int64
+	SettingsMessageID int
+	UpdatedAt         string
+}
+
+type Thread struct {
+	ID             int64
+	TelegramUserID int64
+	CodexThreadID  string
+	WorkspaceID    int64
+	Title          string
+	Archived       bool
+	CreatedAt      string
+	UpdatedAt      string
+}
+
+type PendingApproval struct {
+	ID             int64
+	TelegramUserID int64
+	CodexRequestID string
+	CodexThreadID  string
+	TurnID         string
+	ItemID         string
+	Kind           string
+	PayloadJSON    string
+	MessageChatID  int64
+	MessageID      int
+	Status         string
+	CreatedAt      string
+	ResolvedAt     string
+}
+
+func Open(ctx context.Context, path string) (*Store, error) {
+	if err := os.MkdirAll(filepath.Dir(path), 0o755); err != nil {
+		return nil, err
+	}
+	db, err := sql.Open("sqlite", path)
+	if err != nil {
+		return nil, err
+	}
+	db.SetMaxOpenConns(1)
+
+	s := &Store{db: db}
+	if err := s.configure(ctx); err != nil {
+		_ = db.Close()
+		return nil, err
+	}
+	if err := s.migrate(ctx); err != nil {
+		_ = db.Close()
+		return nil, err
+	}
+	return s, nil
+}
+
+func (s *Store) Close() error {
+	return s.db.Close()
+}
+
+func (s *Store) configure(ctx context.Context) error {
+	statements := []string{
+		"PRAGMA foreign_keys = ON",
+		"PRAGMA journal_mode = WAL",
+		"PRAGMA busy_timeout = 5000",
+	}
+	for _, statement := range statements {
+		if _, err := s.db.ExecContext(ctx, statement); err != nil {
+			return err
+		}
+	}
+	return nil
+}
+
+func (s *Store) migrate(ctx context.Context) error {
+	if _, err := s.db.ExecContext(ctx, `
+CREATE TABLE IF NOT EXISTS schema_migrations (
+	version INTEGER PRIMARY KEY,
+	name TEXT NOT NULL,
+	applied_at TEXT NOT NULL DEFAULT (datetime('now'))
+)`); err != nil {
+		return err
+	}
+
+	var current int
+	if err := s.db.QueryRowContext(ctx, "SELECT COALESCE(MAX(version), 0) FROM schema_migrations").Scan(&current); err != nil {
+		return err
+	}
+	for i := current; i < len(migrations); i++ {
+		version := i + 1
+		tx, err := s.db.BeginTx(ctx, nil)
+		if err != nil {
+			return err
+		}
+		if _, err := tx.ExecContext(ctx, migrations[i].SQL); err != nil {
+			_ = tx.Rollback()
+			return fmt.Errorf("migration %d %s: %w", version, migrations[i].Name, err)
+		}
+		if _, err := tx.ExecContext(ctx, "INSERT INTO schema_migrations (version, name) VALUES (?, ?)", version, migrations[i].Name); err != nil {
+			_ = tx.Rollback()
+			return err
+		}
+		if err := tx.Commit(); err != nil {
+			return err
+		}
+	}
+	return nil
+}
+
+func ValidateWorkspacePath(path string) (string, error) {
+	if path == "" {
+		return "", errors.New("workspace path is required")
+	}
+	if strings.ContainsRune(path, 0) {
+		return "", errors.New("workspace path contains a NUL byte")
+	}
+	if !filepath.IsAbs(path) {
+		return "", errors.New("workspace path must be absolute")
+	}
+	clean := filepath.Clean(path)
+	if clean == string(filepath.Separator) {
+		return "", errors.New("workspace path cannot be filesystem root")
+	}
+	return clean, nil
+}
+
+func (s *Store) IsAllowed(ctx context.Context, telegramUserID int64) (bool, error) {
+	var exists int
+	err := s.db.QueryRowContext(ctx, "SELECT 1 FROM allowed_users WHERE telegram_user_id = ?", telegramUserID).Scan(&exists)
+	if errors.Is(err, sql.ErrNoRows) {
+		return false, nil
+	}
+	return err == nil, err
+}
+
+func (s *Store) AddAllowedUser(ctx context.Context, telegramUserID int64, username, notes string) error {
+	_, err := s.db.ExecContext(ctx, `
+INSERT INTO allowed_users (telegram_user_id, username, notes)
+VALUES (?, ?, ?)
+ON CONFLICT(telegram_user_id) DO UPDATE SET username = excluded.username, notes = excluded.notes`,
+		telegramUserID, username, notes)
+	return err
+}
+
+func (s *Store) RemoveAllowedUser(ctx context.Context, telegramUserID int64) error {
+	_, err := s.db.ExecContext(ctx, "DELETE FROM allowed_users WHERE telegram_user_id = ?", telegramUserID)
+	return err
+}
+
+func (s *Store) ListAllowedUsers(ctx context.Context) ([]AllowedUser, error) {
+	rows, err := s.db.QueryContext(ctx, "SELECT telegram_user_id, username, notes, added_at FROM allowed_users ORDER BY telegram_user_id")
+	if err != nil {
+		return nil, err
+	}
+	defer rows.Close()
+
+	var users []AllowedUser
+	for rows.Next() {
+		var user AllowedUser
+		if err := rows.Scan(&user.TelegramUserID, &user.Username, &user.Notes, &user.AddedAt); err != nil {
+			return nil, err
+		}
+		users = append(users, user)
+	}
+	return users, rows.Err()
+}
+
+func (s *Store) AddWorkspace(ctx context.Context, path, label string, isDefault bool) (Workspace, error) {
+	clean, err := ValidateWorkspacePath(path)
+	if err != nil {
+		return Workspace{}, err
+	}
+	if label == "" {
+		label = filepath.Base(clean)
+	}
+
+	tx, err := s.db.BeginTx(ctx, nil)
+	if err != nil {
+		return Workspace{}, err
+	}
+	if isDefault {
+		if _, err := tx.ExecContext(ctx, "UPDATE workspaces SET is_default = 0"); err != nil {
+			_ = tx.Rollback()
+			return Workspace{}, err
+		}
+	}
+	result, err := tx.ExecContext(ctx, `
+INSERT INTO workspaces (path, label, is_default)
+VALUES (?, ?, ?)
+ON CONFLICT(path) DO UPDATE SET label = excluded.label, is_default = excluded.is_default`,
+		clean, label, boolInt(isDefault))
+	if err != nil {
+		_ = tx.Rollback()
+		return Workspace{}, err
+	}
+	if err := tx.Commit(); err != nil {
+		return Workspace{}, err
+	}
+
+	id, _ := result.LastInsertId()
+	if id == 0 {
+		return s.GetWorkspaceByPath(ctx, clean)
+	}
+	return s.GetWorkspaceByPath(ctx, clean)
+}
+
+func (s *Store) ListWorkspaces(ctx context.Context) ([]Workspace, error) {
+	rows, err := s.db.QueryContext(ctx, "SELECT id, path, label, is_default, created_at FROM workspaces ORDER BY is_default DESC, label, path")
+	if err != nil {
+		return nil, err
+	}
+	defer rows.Close()
+
+	var workspaces []Workspace
+	for rows.Next() {
+		workspace, err := scanWorkspace(rows)
+		if err != nil {
+			return nil, err
+		}
+		workspaces = append(workspaces, workspace)
+	}
+	return workspaces, rows.Err()
+}
+
+func (s *Store) GetWorkspaceByID(ctx context.Context, id int64) (Workspace, error) {
+	row := s.db.QueryRowContext(ctx, "SELECT id, path, label, is_default, created_at FROM workspaces WHERE id = ?", id)
+	return scanWorkspace(row)
+}
+
+func (s *Store) GetWorkspaceByPath(ctx context.Context, path string) (Workspace, error) {
+	row := s.db.QueryRowContext(ctx, "SELECT id, path, label, is_default, created_at FROM workspaces WHERE path = ?", path)
+	return scanWorkspace(row)
+}
+
+func (s *Store) DefaultWorkspace(ctx context.Context) (Workspace, error) {
+	row := s.db.QueryRowContext(ctx, "SELECT id, path, label, is_default, created_at FROM workspaces ORDER BY is_default DESC, id ASC LIMIT 1")
+	return scanWorkspace(row)
+}
+
+func (s *Store) GetOrCreateSession(ctx context.Context, telegramUserID int64, defaultModel, defaultSandbox string) (Session, error) {
+	if defaultSandbox == "" {
+		defaultSandbox = "workspace-write"
+	}
+	_, err := s.db.ExecContext(ctx, `
+INSERT INTO sessions (telegram_user_id, model, sandbox)
+VALUES (?, ?, ?)
+ON CONFLICT(telegram_user_id) DO NOTHING`, telegramUserID, defaultModel, defaultSandbox)
+	if err != nil {
+		return Session{}, err
+	}
+	return s.GetSession(ctx, telegramUserID)
+}
+
+func (s *Store) GetSession(ctx context.Context, telegramUserID int64) (Session, error) {
+	row := s.db.QueryRowContext(ctx, `
+SELECT telegram_user_id, COALESCE(active_thread_id, 0), COALESCE(active_workspace_id, 0), model, COALESCE(reasoning_effort, ''), sandbox, active_turn_id, COALESCE(settings_chat_id, 0), COALESCE(settings_message_id, 0), updated_at
+FROM sessions WHERE telegram_user_id = ?`, telegramUserID)
+	var session Session
+	err := row.Scan(&session.TelegramUserID, &session.ActiveThreadID, &session.ActiveWorkspaceID, &session.Model, &session.ReasoningEffort, &session.Sandbox, &session.ActiveTurnID, &session.SettingsChatID, &session.SettingsMessageID, &session.UpdatedAt)
+	return session, err
+}
+
+func (s *Store) SetSessionWorkspace(ctx context.Context, telegramUserID, workspaceID int64) error {
+	_, err := s.db.ExecContext(ctx, `
+UPDATE sessions SET active_workspace_id = ?, updated_at = datetime('now')
+WHERE telegram_user_id = ?`, workspaceID, telegramUserID)
+	return err
+}
+
+func (s *Store) SetSessionModel(ctx context.Context, telegramUserID int64, model string) error {
+	_, err := s.db.ExecContext(ctx, "UPDATE sessions SET model = ?, reasoning_effort = '', updated_at = datetime('now') WHERE telegram_user_id = ?", model, telegramUserID)
+	return err
+}
+
+func (s *Store) SetSessionReasoningEffort(ctx context.Context, telegramUserID int64, effort string) error {
+	_, err := s.db.ExecContext(ctx, "UPDATE sessions SET reasoning_effort = ?, updated_at = datetime('now') WHERE telegram_user_id = ?", effort, telegramUserID)
+	return err
+}
+
+func (s *Store) SetSessionSettingsMessage(ctx context.Context, telegramUserID int64, chatID int64, messageID int) error {
+	_, err := s.db.ExecContext(ctx, "UPDATE sessions SET settings_chat_id = ?, settings_message_id = ?, updated_at = datetime('now') WHERE telegram_user_id = ?", chatID, messageID, telegramUserID)
+	return err
+}
+
+func (s *Store) SetSessionSandbox(ctx context.Context, telegramUserID int64, sandbox string) error {
+	_, err := s.db.ExecContext(ctx, "UPDATE sessions SET sandbox = ?, updated_at = datetime('now') WHERE telegram_user_id = ?", sandbox, telegramUserID)
+	return err
+}
+
+func (s *Store) SetActiveThread(ctx context.Context, telegramUserID, threadID int64) error {
+	_, err := s.db.ExecContext(ctx, `
+UPDATE sessions SET active_thread_id = ?, active_turn_id = '', updated_at = datetime('now')
+WHERE telegram_user_id = ?`, threadID, telegramUserID)
+	return err
+}
+
+func (s *Store) SetActiveTurn(ctx context.Context, telegramUserID int64, turnID string) error {
+	_, err := s.db.ExecContext(ctx, "UPDATE sessions SET active_turn_id = ?, updated_at = datetime('now') WHERE telegram_user_id = ?", turnID, telegramUserID)
+	return err
+}
+
+func (s *Store) ClearActiveTurns(ctx context.Context) error {
+	_, err := s.db.ExecContext(ctx, "UPDATE sessions SET active_turn_id = '', updated_at = datetime('now') WHERE active_turn_id <> ''")
+	return err
+}
+
+func (s *Store) CreateThread(ctx context.Context, telegramUserID int64, codexThreadID string, workspaceID int64, title string) (Thread, error) {
+	result, err := s.db.ExecContext(ctx, `
+INSERT INTO threads (telegram_user_id, codex_thread_id, workspace_id, title)
+VALUES (?, ?, ?, ?)`, telegramUserID, codexThreadID, workspaceID, title)
+	if err != nil {
+		return Thread{}, err
+	}
+	id, err := result.LastInsertId()
+	if err != nil {
+		return Thread{}, err
+	}
+	return s.GetThreadByID(ctx, telegramUserID, id)
+}
+
+func (s *Store) GetThreadByID(ctx context.Context, telegramUserID, id int64) (Thread, error) {
+	row := s.db.QueryRowContext(ctx, `
+SELECT id, telegram_user_id, codex_thread_id, workspace_id, title, archived, created_at, updated_at
+FROM threads WHERE telegram_user_id = ? AND id = ?`, telegramUserID, id)
+	return scanThread(row)
+}
+
+func (s *Store) GetThreadByCodexID(ctx context.Context, codexThreadID string) (Thread, error) {
+	row := s.db.QueryRowContext(ctx, `
+SELECT id, telegram_user_id, codex_thread_id, workspace_id, title, archived, created_at, updated_at
+FROM threads WHERE codex_thread_id = ?`, codexThreadID)
+	return scanThread(row)
+}
+
+func (s *Store) ListThreads(ctx context.Context, telegramUserID int64, includeArchived bool) ([]Thread, error) {
+	return s.ListThreadsPage(ctx, telegramUserID, includeArchived, 20, 0)
+}
+
+func (s *Store) ListThreadsPage(ctx context.Context, telegramUserID int64, includeArchived bool, limit, offset int) ([]Thread, error) {
+	if limit <= 0 {
+		limit = 20
+	}
+	if offset < 0 {
+		offset = 0
+	}
+	query := `
+SELECT id, telegram_user_id, codex_thread_id, workspace_id, title, archived, created_at, updated_at
+FROM threads WHERE telegram_user_id = ?`
+	args := []any{telegramUserID}
+	if !includeArchived {
+		query += " AND archived = 0"
+	}
+	query += " ORDER BY updated_at DESC, id DESC LIMIT ? OFFSET ?"
+	args = append(args, limit, offset)
+
+	rows, err := s.db.QueryContext(ctx, query, args...)
+	if err != nil {
+		return nil, err
+	}
+	defer rows.Close()
+
+	var threads []Thread
+	for rows.Next() {
+		thread, err := scanThread(rows)
+		if err != nil {
+			return nil, err
+		}
+		threads = append(threads, thread)
+	}
+	return threads, rows.Err()
+}
+
+func (s *Store) ArchiveThread(ctx context.Context, telegramUserID, id int64) error {
+	_, err := s.db.ExecContext(ctx, `
+UPDATE threads SET archived = 1, updated_at = datetime('now')
+WHERE telegram_user_id = ? AND id = ?`, telegramUserID, id)
+	return err
+}
+
+func (s *Store) TouchThread(ctx context.Context, codexThreadID string) error {
+	_, err := s.db.ExecContext(ctx, "UPDATE threads SET updated_at = datetime('now') WHERE codex_thread_id = ?", codexThreadID)
+	return err
+}
+
+func (s *Store) UpsertPendingApproval(ctx context.Context, approval PendingApproval) (PendingApproval, error) {
+	_, err := s.db.ExecContext(ctx, `
+INSERT INTO pending_approvals (
+	telegram_user_id, codex_request_id, codex_thread_id, turn_id, item_id, kind, payload_json,
+	message_chat_id, message_id, status
+) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, 'pending')
+ON CONFLICT(telegram_user_id, codex_request_id) DO UPDATE SET
+	payload_json = excluded.payload_json,
+	message_chat_id = excluded.message_chat_id,
+	message_id = excluded.message_id,
+	status = 'pending',
+	resolved_at = ''`,
+		approval.TelegramUserID, approval.CodexRequestID, approval.CodexThreadID, approval.TurnID,
+		approval.ItemID, approval.Kind, approval.PayloadJSON, approval.MessageChatID, approval.MessageID)
+	if err != nil {
+		return PendingApproval{}, err
+	}
+	return s.GetPendingApprovalByRequest(ctx, approval.TelegramUserID, approval.CodexRequestID)
+}
+
+func (s *Store) UpdatePendingApprovalMessage(ctx context.Context, id int64, chatID int64, messageID int) error {
+	_, err := s.db.ExecContext(ctx, "UPDATE pending_approvals SET message_chat_id = ?, message_id = ? WHERE id = ?", chatID, messageID, id)
+	return err
+}
+
+func (s *Store) GetPendingApproval(ctx context.Context, telegramUserID, id int64) (PendingApproval, error) {
+	row := s.db.QueryRowContext(ctx, `
+SELECT id, telegram_user_id, codex_request_id, codex_thread_id, turn_id, item_id, kind, payload_json,
+       message_chat_id, message_id, status, created_at, COALESCE(resolved_at, '')
+FROM pending_approvals WHERE telegram_user_id = ? AND id = ?`, telegramUserID, id)
+	return scanPendingApproval(row)
+}
+
+func (s *Store) GetPendingApprovalByRequest(ctx context.Context, telegramUserID int64, requestID string) (PendingApproval, error) {
+	row := s.db.QueryRowContext(ctx, `
+SELECT id, telegram_user_id, codex_request_id, codex_thread_id, turn_id, item_id, kind, payload_json,
+       message_chat_id, message_id, status, created_at, COALESCE(resolved_at, '')
+FROM pending_approvals WHERE telegram_user_id = ? AND codex_request_id = ?`, telegramUserID, requestID)
+	return scanPendingApproval(row)
+}
+
+func (s *Store) ResolvePendingApproval(ctx context.Context, telegramUserID, id int64, status string) error {
+	_, err := s.db.ExecContext(ctx, `
+UPDATE pending_approvals SET status = ?, resolved_at = datetime('now')
+WHERE telegram_user_id = ? AND id = ? AND status = 'pending'`, status, telegramUserID, id)
+	return err
+}
+
+func (s *Store) Audit(ctx context.Context, telegramUserID int64, action, details string) error {
+	_, err := s.db.ExecContext(ctx, "INSERT INTO audit_log (telegram_user_id, action, details) VALUES (?, ?, ?)", telegramUserID, action, details)
+	return err
+}
+
+type scanner interface {
+	Scan(dest ...any) error
+}
+
+func scanWorkspace(row scanner) (Workspace, error) {
+	var workspace Workspace
+	var isDefault int
+	if err := row.Scan(&workspace.ID, &workspace.Path, &workspace.Label, &isDefault, &workspace.CreatedAt); err != nil {
+		return Workspace{}, err
+	}
+	workspace.IsDefault = isDefault != 0
+	return workspace, nil
+}
+
+func scanThread(row scanner) (Thread, error) {
+	var thread Thread
+	var archived int
+	if err := row.Scan(&thread.ID, &thread.TelegramUserID, &thread.CodexThreadID, &thread.WorkspaceID, &thread.Title, &archived, &thread.CreatedAt, &thread.UpdatedAt); err != nil {
+		return Thread{}, err
+	}
+	thread.Archived = archived != 0
+	return thread, nil
+}
+
+func scanPendingApproval(row scanner) (PendingApproval, error) {
+	var approval PendingApproval
+	if err := row.Scan(&approval.ID, &approval.TelegramUserID, &approval.CodexRequestID, &approval.CodexThreadID,
+		&approval.TurnID, &approval.ItemID, &approval.Kind, &approval.PayloadJSON, &approval.MessageChatID,
+		&approval.MessageID, &approval.Status, &approval.CreatedAt, &approval.ResolvedAt); err != nil {
+		return PendingApproval{}, err
+	}
+	return approval, nil
+}
+
+func boolInt(value bool) int {
+	if value {
+		return 1
+	}
+	return 0
+}

internal/store/store_test.go

@@ -0,0 +1,137 @@
+package store
+
+import (
+	"context"
+	"path/filepath"
+	"testing"
+)
+
+func TestStoreUsersWorkspacesSessions(t *testing.T) {
+	ctx := context.Background()
+	st, err := Open(ctx, filepath.Join(t.TempDir(), "bot.db"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer st.Close()
+
+	allowed, err := st.IsAllowed(ctx, 42)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if allowed {
+		t.Fatal("new user should not be allowed")
+	}
+	if err := st.AddAllowedUser(ctx, 42, "alice", "owner"); err != nil {
+		t.Fatal(err)
+	}
+	allowed, err = st.IsAllowed(ctx, 42)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if !allowed {
+		t.Fatal("user should be allowed")
+	}
+
+	workspacePath := t.TempDir()
+	ws, err := st.AddWorkspace(ctx, workspacePath, "repo", true)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if !ws.IsDefault {
+		t.Fatal("workspace should be default")
+	}
+
+	session, err := st.GetOrCreateSession(ctx, 42, "test-model", "read-only")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if session.Model != "test-model" || session.Sandbox != "read-only" || session.ReasoningEffort != "" {
+		t.Fatalf("unexpected session defaults: %+v", session)
+	}
+	if err := st.SetSessionWorkspace(ctx, 42, ws.ID); err != nil {
+		t.Fatal(err)
+	}
+	effort := "value-returned-by-server"
+	if err := st.SetSessionReasoningEffort(ctx, 42, effort); err != nil {
+		t.Fatal(err)
+	}
+	session, err = st.GetSession(ctx, 42)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if session.ActiveWorkspaceID != ws.ID || session.ReasoningEffort != effort {
+		t.Fatalf("workspace not saved: %+v", session)
+	}
+	if err := st.SetSessionSettingsMessage(ctx, 42, 1001, 2002); err != nil {
+		t.Fatal(err)
+	}
+	session, err = st.GetSession(ctx, 42)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if session.SettingsChatID != 1001 || session.SettingsMessageID != 2002 {
+		t.Fatalf("settings message not saved: %+v", session)
+	}
+	if err := st.SetActiveTurn(ctx, 42, "turn-123"); err != nil {
+		t.Fatal(err)
+	}
+	if err := st.ClearActiveTurns(ctx); err != nil {
+		t.Fatal(err)
+	}
+	session, err = st.GetSession(ctx, 42)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if session.ActiveTurnID != "" {
+		t.Fatalf("active turn not cleared: %+v", session)
+	}
+}
+
+func TestListThreadsPage(t *testing.T) {
+	ctx := context.Background()
+	st, err := Open(ctx, filepath.Join(t.TempDir(), "bot.db"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer st.Close()
+
+	ws, err := st.AddWorkspace(ctx, t.TempDir(), "repo", true)
+	if err != nil {
+		t.Fatal(err)
+	}
+	for i := 0; i < 3; i++ {
+		if _, err := st.CreateThread(ctx, 42, string(rune('a'+i)), ws.ID, "thread"); err != nil {
+			t.Fatal(err)
+		}
+	}
+	threads, err := st.ListThreadsPage(ctx, 42, false, 2, 0)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(threads) != 2 {
+		t.Fatalf("got %d threads, want 2", len(threads))
+	}
+	threads, err = st.ListThreadsPage(ctx, 42, false, 2, 2)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(threads) != 1 {
+		t.Fatalf("got %d threads on second page, want 1", len(threads))
+	}
+}
+
+func TestValidateWorkspacePath(t *testing.T) {
+	if _, err := ValidateWorkspacePath("relative/path"); err == nil {
+		t.Fatal("relative path should be rejected")
+	}
+	if _, err := ValidateWorkspacePath("/"); err == nil {
+		t.Fatal("filesystem root should be rejected")
+	}
+	clean, err := ValidateWorkspacePath("/tmp/../tmp/project")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if clean != "/tmp/project" {
+		t.Fatalf("unexpected clean path: %s", clean)
+	}
+}

internal/telegram/api.go

@@ -0,0 +1,211 @@
+package telegram
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"fmt"
+	"io"
+	"mime/multipart"
+	"net/http"
+	"net/url"
+	"path/filepath"
+	"time"
+)
+
+type Client struct {
+	token       string
+	baseURL     string
+	fileBaseURL string
+	httpClient  *http.Client
+}
+
+func NewClient(token string) *Client {
+	return &Client{
+		token:       token,
+		baseURL:     "https://api.telegram.org/bot" + token,
+		fileBaseURL: "https://api.telegram.org/file/bot" + token,
+		httpClient:  &http.Client{Timeout: 90 * time.Second},
+	}
+}
+
+func (c *Client) GetUpdates(ctx context.Context, offset int, timeoutSeconds int) ([]Update, error) {
+	params := map[string]any{
+		"offset":          offset,
+		"timeout":         timeoutSeconds,
+		"allowed_updates": []string{"message", "callback_query"},
+	}
+	var updates []Update
+	if err := c.postJSON(ctx, "getUpdates", params, &updates); err != nil {
+		return nil, err
+	}
+	return updates, nil
+}
+
+func (c *Client) SendMessage(ctx context.Context, chatID int64, text string, opts SendMessageOptions) (Message, error) {
+	params := map[string]any{
+		"chat_id": chatID,
+		"text":    text,
+	}
+	if opts.ParseMode != "" {
+		params["parse_mode"] = opts.ParseMode
+	}
+	if opts.ReplyMarkup != nil {
+		params["reply_markup"] = opts.ReplyMarkup
+	}
+	var message Message
+	if err := c.postJSON(ctx, "sendMessage", params, &message); err != nil {
+		return Message{}, err
+	}
+	return message, nil
+}
+
+func (c *Client) EditMessageText(ctx context.Context, chatID int64, messageID int, text string, opts EditMessageTextOptions) (Message, error) {
+	params := map[string]any{
+		"chat_id":    chatID,
+		"message_id": messageID,
+		"text":       text,
+	}
+	if opts.ParseMode != "" {
+		params["parse_mode"] = opts.ParseMode
+	}
+	if opts.ReplyMarkup != nil {
+		params["reply_markup"] = opts.ReplyMarkup
+	}
+	var message Message
+	if err := c.postJSON(ctx, "editMessageText", params, &message); err != nil {
+		return Message{}, err
+	}
+	return message, nil
+}
+
+func (c *Client) PinChatMessage(ctx context.Context, chatID int64, messageID int, disableNotification bool) error {
+	params := map[string]any{
+		"chat_id":              chatID,
+		"message_id":           messageID,
+		"disable_notification": disableNotification,
+	}
+	var ignored bool
+	return c.postJSON(ctx, "pinChatMessage", params, &ignored)
+}
+
+func (c *Client) AnswerCallbackQuery(ctx context.Context, callbackQueryID, text string) error {
+	params := map[string]any{
+		"callback_query_id": callbackQueryID,
+	}
+	if text != "" {
+		params["text"] = text
+	}
+	var ignored bool
+	return c.postJSON(ctx, "answerCallbackQuery", params, &ignored)
+}
+
+func (c *Client) GetFile(ctx context.Context, fileID string) (File, error) {
+	var file File
+	if err := c.postJSON(ctx, "getFile", map[string]any{"file_id": fileID}, &file); err != nil {
+		return File{}, err
+	}
+	return file, nil
+}
+
+func (c *Client) DownloadFile(ctx context.Context, filePath string) ([]byte, error) {
+	u := c.fileBaseURL + "/" + url.PathEscape(filePath)
+	req, err := http.NewRequestWithContext(ctx, http.MethodGet, u, nil)
+	if err != nil {
+		return nil, err
+	}
+	resp, err := c.httpClient.Do(req)
+	if err != nil {
+		return nil, err
+	}
+	defer resp.Body.Close()
+	if resp.StatusCode < 200 || resp.StatusCode >= 300 {
+		return nil, fmt.Errorf("download file: telegram returned %s", resp.Status)
+	}
+	return io.ReadAll(resp.Body)
+}
+
+func (c *Client) SendDocumentBytes(ctx context.Context, chatID int64, filename string, data []byte, caption string) (Message, error) {
+	var body bytes.Buffer
+	writer := multipart.NewWriter(&body)
+	if err := writer.WriteField("chat_id", fmt.Sprint(chatID)); err != nil {
+		return Message{}, err
+	}
+	if caption != "" {
+		if err := writer.WriteField("caption", caption); err != nil {
+			return Message{}, err
+		}
+	}
+	part, err := writer.CreateFormFile("document", filepath.Base(filename))
+	if err != nil {
+		return Message{}, err
+	}
+	if _, err := part.Write(data); err != nil {
+		return Message{}, err
+	}
+	if err := writer.Close(); err != nil {
+		return Message{}, err
+	}
+
+	req, err := http.NewRequestWithContext(ctx, http.MethodPost, c.baseURL+"/sendDocument", &body)
+	if err != nil {
+		return Message{}, err
+	}
+	req.Header.Set("Content-Type", writer.FormDataContentType())
+	resp, err := c.httpClient.Do(req)
+	if err != nil {
+		return Message{}, err
+	}
+	defer resp.Body.Close()
+	if resp.StatusCode < 200 || resp.StatusCode >= 300 {
+		payload, _ := io.ReadAll(io.LimitReader(resp.Body, 4096))
+		return Message{}, fmt.Errorf("sendDocument: telegram returned %s: %s", resp.Status, string(payload))
+	}
+	var decoded apiResponse[Message]
+	if err := json.NewDecoder(resp.Body).Decode(&decoded); err != nil {
+		return Message{}, err
+	}
+	if !decoded.OK {
+		return Message{}, fmt.Errorf("sendDocument: telegram error %d: %s", decoded.ErrorCode, decoded.Description)
+	}
+	return decoded.Result, nil
+}
+
+func (c *Client) postJSON(ctx context.Context, method string, params any, result any) error {
+	body, err := json.Marshal(params)
+	if err != nil {
+		return err
+	}
+	req, err := http.NewRequestWithContext(ctx, http.MethodPost, c.baseURL+"/"+method, bytes.NewReader(body))
+	if err != nil {
+		return err
+	}
+	req.Header.Set("Content-Type", "application/json")
+	resp, err := c.httpClient.Do(req)
+	if err != nil {
+		return err
+	}
+	defer resp.Body.Close()
+	if resp.StatusCode < 200 || resp.StatusCode >= 300 {
+		payload, _ := io.ReadAll(io.LimitReader(resp.Body, 4096))
+		return fmt.Errorf("%s: telegram returned %s: %s", method, resp.Status, string(payload))
+	}
+	var decoded apiResponse[json.RawMessage]
+	if err := json.NewDecoder(resp.Body).Decode(&decoded); err != nil {
+		return err
+	}
+	if !decoded.OK {
+		return fmt.Errorf("%s: telegram error %d: %s", method, decoded.ErrorCode, decoded.Description)
+	}
+	if result == nil {
+		return nil
+	}
+	return json.Unmarshal(decoded.Result, result)
+}
+
+type apiResponse[T any] struct {
+	OK          bool   `json:"ok"`
+	Result      T      `json:"result"`
+	ErrorCode   int    `json:"error_code,omitempty"`
+	Description string `json:"description,omitempty"`
+}

internal/telegram/download.go

@@ -0,0 +1,26 @@
+package telegram
+
+import (
+	"context"
+	"fmt"
+	"io"
+	"net/http"
+	"strings"
+)
+
+func (c *Client) DownloadFilePath(ctx context.Context, filePath string) ([]byte, error) {
+	u := c.fileBaseURL + "/" + strings.TrimLeft(filePath, "/")
+	req, err := http.NewRequestWithContext(ctx, http.MethodGet, u, nil)
+	if err != nil {
+		return nil, err
+	}
+	resp, err := c.httpClient.Do(req)
+	if err != nil {
+		return nil, err
+	}
+	defer resp.Body.Close()
+	if resp.StatusCode < 200 || resp.StatusCode >= 300 {
+		return nil, fmt.Errorf("download file: telegram returned %s", resp.Status)
+	}
+	return io.ReadAll(resp.Body)
+}

internal/telegram/render.go

@@ -0,0 +1,183 @@
+package telegram
+
+import (
+	"encoding/base64"
+	"fmt"
+	"html"
+	"strconv"
+	"strings"
+)
+
+const TelegramMessageLimit = 4096
+const TelegramHTMLMessageLimit = 3900
+
+func EscapeHTML(text string) string {
+	return html.EscapeString(text)
+}
+
+func SummaryDetailsHTML(summary, details string) string {
+	summary = strings.TrimSpace(summary)
+	details = strings.TrimSpace(details)
+	if details == "" {
+		return EscapeHTML(summary)
+	}
+	if summary == "" {
+		return ExpandableQuoteHTML(details)
+	}
+	return EscapeHTML(summary) + "\n" + ExpandableQuoteHTML(details)
+}
+
+func ExpandableQuoteHTML(text string) string {
+	text = strings.TrimSpace(text)
+	if text == "" {
+		return ""
+	}
+	return "<blockquote expandable>" + EscapeHTML(text) + "</blockquote>"
+}
+
+func SummaryDetailsHTMLLimited(summary, details string, limit int) string {
+	if limit <= 0 {
+		limit = TelegramHTMLMessageLimit
+	}
+	summary = strings.TrimSpace(summary)
+	details = strings.TrimSpace(details)
+	out := SummaryDetailsHTML(summary, details)
+	if len([]rune(out)) <= limit || details == "" {
+		return out
+	}
+
+	suffix := "\n...[truncated]"
+	runes := []rune(details)
+	for len(runes) > 0 {
+		candidateLen := len(runes) - max(1, (len([]rune(out))-limit)/2)
+		if candidateLen < 0 {
+			candidateLen = 0
+		}
+		if candidateLen > len(runes) {
+			candidateLen = len(runes)
+		}
+		candidate := strings.TrimSpace(string(runes[:candidateLen])) + suffix
+		out = SummaryDetailsHTML(summary, candidate)
+		if len([]rune(out)) <= limit || candidateLen == 0 {
+			return out
+		}
+		runes = runes[:candidateLen]
+	}
+	return SummaryDetailsHTML(summary, suffix)
+}
+
+func ChunkText(text string, max int) []string {
+	if max <= 0 {
+		max = TelegramMessageLimit
+	}
+	runes := []rune(text)
+	if len(runes) == 0 {
+		return nil
+	}
+	var chunks []string
+	for len(runes) > max {
+		cut := max
+		for i := max; i > max/2; i-- {
+			if runes[i-1] == '\n' {
+				cut = i
+				break
+			}
+		}
+		chunks = append(chunks, string(runes[:cut]))
+		runes = runes[cut:]
+	}
+	if len(runes) > 0 {
+		chunks = append(chunks, string(runes))
+	}
+	return chunks
+}
+
+func ApprovalCallbackData(id int64, decision string) string {
+	return fmt.Sprintf("approval:%d:%s", id, decision)
+}
+
+func ParseApprovalCallbackData(data string) (int64, string, bool) {
+	parts := strings.Split(data, ":")
+	if len(parts) != 3 || parts[0] != "approval" {
+		return 0, "", false
+	}
+	id, err := strconv.ParseInt(parts[1], 10, 64)
+	if err != nil || id <= 0 {
+		return 0, "", false
+	}
+	switch parts[2] {
+	case "accept", "acceptForSession", "decline", "cancel", "details":
+		return id, parts[2], true
+	default:
+		return 0, "", false
+	}
+}
+
+func WorkspaceCallbackData(id int64) string {
+	return fmt.Sprintf("workspace:%d", id)
+}
+
+func ParseWorkspaceCallbackData(data string) (int64, bool) {
+	if !strings.HasPrefix(data, "workspace:") {
+		return 0, false
+	}
+	id, err := strconv.ParseInt(strings.TrimPrefix(data, "workspace:"), 10, 64)
+	return id, err == nil && id > 0
+}
+
+func ResumeThreadCallbackData(id int64) string {
+	return fmt.Sprintf("resume:thread:%d", id)
+}
+
+func ParseResumeThreadCallbackData(data string) (int64, bool) {
+	if !strings.HasPrefix(data, "resume:thread:") {
+		return 0, false
+	}
+	id, err := strconv.ParseInt(strings.TrimPrefix(data, "resume:thread:"), 10, 64)
+	return id, err == nil && id > 0
+}
+
+func ResumePageCallbackData(page int) string {
+	return fmt.Sprintf("resume:page:%d", page)
+}
+
+func ParseResumePageCallbackData(data string) (int, bool) {
+	if !strings.HasPrefix(data, "resume:page:") {
+		return 0, false
+	}
+	page, err := strconv.Atoi(strings.TrimPrefix(data, "resume:page:"))
+	return page, err == nil && page >= 0
+}
+
+func ModelCallbackData(modelID string) (string, bool) {
+	encoded := base64.RawURLEncoding.EncodeToString([]byte(modelID))
+	data := "model:" + encoded
+	return data, len([]rune(data)) <= 64
+}
+
+func ParseModelCallbackData(data string) (string, bool) {
+	if !strings.HasPrefix(data, "model:") {
+		return "", false
+	}
+	decoded, err := base64.RawURLEncoding.DecodeString(strings.TrimPrefix(data, "model:"))
+	if err != nil || len(decoded) == 0 {
+		return "", false
+	}
+	return string(decoded), true
+}
+
+func EffortCallbackData(effort string) string {
+	encoded := base64.RawURLEncoding.EncodeToString([]byte(effort))
+	return "effort:" + encoded
+}
+
+func ParseEffortCallbackData(data string) (string, bool) {
+	if !strings.HasPrefix(data, "effort:") {
+		return "", false
+	}
+	decoded, err := base64.RawURLEncoding.DecodeString(strings.TrimPrefix(data, "effort:"))
+	if err != nil || len(decoded) == 0 {
+		return "", false
+	}
+	return string(decoded), true
+}

internal/telegram/render_test.go

@@ -0,0 +1,152 @@
+package telegram
+
+import (
+	"strings"
+	"testing"
+
+	"codex-telegram-bot/internal/store"
+)
+
+func TestEscapeHTML(t *testing.T) {
+	got := EscapeHTML(`<run & "test">`)
+	want := "&lt;run &amp; &#34;test&#34;&gt;"
+	if got != want {
+		t.Fatalf("EscapeHTML() = %q, want %q", got, want)
+	}
+}
+
+func TestChunkText(t *testing.T) {
+	text := strings.Repeat("a", 25)
+	chunks := ChunkText(text, 10)
+	if len(chunks) != 3 {
+		t.Fatalf("got %d chunks", len(chunks))
+	}
+	for _, chunk := range chunks {
+		if len([]rune(chunk)) > 10 {
+			t.Fatalf("chunk too long: %q", chunk)
+		}
+	}
+}
+
+func TestApprovalCallbackData(t *testing.T) {
+	data := ApprovalCallbackData(12, "accept")
+	id, decision, ok := ParseApprovalCallbackData(data)
+	if !ok || id != 12 || decision != "accept" {
+		t.Fatalf("unexpected callback parse: id=%d decision=%s ok=%v", id, decision, ok)
+	}
+	if _, _, ok := ParseApprovalCallbackData("approval:12:unknown"); ok {
+		t.Fatal("unknown decisions should be rejected")
+	}
+}
+
+func TestApprovalResponseForPermissions(t *testing.T) {
+	approval := store.PendingApproval{
+		Kind:        "item/permissions/requestApproval",
+		PayloadJSON: `{"permissions":{"network":{"enabled":true}}}`,
+	}
+	response, ok := approvalResponse(approval, "accept").(map[string]any)
+	if !ok {
+		t.Fatal("approval response should be a map")
+	}
+	if response["scope"] != "turn" {
+		t.Fatalf("scope = %v, want turn", response["scope"])
+	}
+	permissions, ok := response["permissions"].(map[string]any)
+	if !ok {
+		t.Fatal("permissions should be a map")
+	}
+	network, ok := permissions["network"].(map[string]any)
+	if !ok || network["enabled"] != true {
+		t.Fatalf("unexpected permissions: %#v", permissions)
+	}
+
+	denied, ok := approvalResponse(approval, "decline").(map[string]any)
+	if !ok {
+		t.Fatal("denied response should be a map")
+	}
+	deniedPermissions, ok := denied["permissions"].(map[string]any)
+	if !ok || len(deniedPermissions) != 0 {
+		t.Fatalf("denied permissions = %#v, want empty map", denied["permissions"])
+	}
+}
+
+func TestParseCommand(t *testing.T) {
+	name, args, ok := parseCommand("/resume@my_bot 123")
+	if !ok || name != "resume" || len(args) != 1 || args[0] != "123" {
+		t.Fatalf("unexpected command parse: %q %#v %v", name, args, ok)
+	}
+}
+
+func TestRenderCodexCommandExecutionItem(t *testing.T) {
+	output := "line 1\nline 2"
+	exitCode := 0
+	item := codexThreadItemView{
+		Type:             "commandExecution",
+		Command:          "go test ./...",
+		AggregatedOutput: &output,
+		ExitCode:         &exitCode,
+	}
+	text := renderCodexItemCompleted(item)
+	for _, want := range []string{"Tool call: command finished", "Command: go test ./...", "Exit code: 0", "line 1"} {
+		if !strings.Contains(text, want) {
+			t.Fatalf("rendered command item missing %q in %q", want, text)
+		}
+	}
+}
+
+func TestRenderCodexStartedItems(t *testing.T) {
+	text := renderCodexItemStarted(codexThreadItemView{Type: "webSearch", Query: "telegram bot api"})
+	if !strings.Contains(text, "web search started") || !strings.Contains(text, "telegram bot api") {
+		t.Fatalf("unexpected web search render: %q", text)
+	}
+}
+
+func TestResumeCallbackData(t *testing.T) {
+	threadID, ok := ParseResumeThreadCallbackData(ResumeThreadCallbackData(123))
+	if !ok || threadID != 123 {
+		t.Fatalf("unexpected resume thread callback: id=%d ok=%v", threadID, ok)
+	}
+	page, ok := ParseResumePageCallbackData(ResumePageCallbackData(2))
+	if !ok || page != 2 {
+		t.Fatalf("unexpected resume page callback: page=%d ok=%v", page, ok)
+	}
+}
+
+func TestResumeThreadListText(t *testing.T) {
+	threads := []store.Thread{{ID: 42, Title: "do xyz"}, {ID: 43, Title: "executed xxx command"}}
+	text := resumeThreadListText(threads, 0)
+	for _, want := range []string{"Thread ID 42: do xyz", "Thread ID 43: executed xxx command"} {
+		if !strings.Contains(text, want) {
+			t.Fatalf("resume list missing %q in %q", want, text)
+		}
+	}
+	markup := resumeThreadMarkup(threads, 0, true)
+	if len(markup.InlineKeyboard) != 2 || markup.InlineKeyboard[0][0].Text != "ID 42" || markup.InlineKeyboard[0][1].Text != "ID 43" {
+		t.Fatalf("unexpected resume buttons: %#v", markup.InlineKeyboard)
+	}
+	firstID, ok := ParseResumeThreadCallbackData(markup.InlineKeyboard[0][0].CallbackData)
+	if !ok || firstID != 42 {
+		t.Fatalf("first resume button targets id=%d ok=%v", firstID, ok)
+	}
+	secondID, ok := ParseResumeThreadCallbackData(markup.InlineKeyboard[0][1].CallbackData)
+	if !ok || secondID != 43 {
+		t.Fatalf("second resume button targets id=%d ok=%v", secondID, ok)
+	}
+}
+
+func TestModelAndEffortCallbackData(t *testing.T) {
+	modelID := strings.Join([]string{"server", "model", "id"}, "-")
+	data, ok := ModelCallbackData(modelID)
+	if !ok {
+		t.Fatal("model callback should fit")
+	}
+	model, ok := ParseModelCallbackData(data)
+	if !ok || model != modelID {
+		t.Fatalf("unexpected model callback parse: model=%q ok=%v", model, ok)
+	}
+	effortName := strings.Join([]string{"server", "effort"}, "-")
+	effort, ok := ParseEffortCallbackData(EffortCallbackData(effortName))
+	if !ok || effort != effortName {
+		t.Fatalf("unexpected effort callback parse: effort=%q ok=%v", effort, ok)
+	}
+}

internal/telegram/types.go

@@ -0,0 +1,76 @@
+package telegram
+
+type Update struct {
+	UpdateID      int            `json:"update_id"`
+	Message       *Message       `json:"message,omitempty"`
+	CallbackQuery *CallbackQuery `json:"callback_query,omitempty"`
+}
+
+type User struct {
+	ID        int64  `json:"id"`
+	IsBot     bool   `json:"is_bot"`
+	FirstName string `json:"first_name,omitempty"`
+	Username  string `json:"username,omitempty"`
+}
+
+type Chat struct {
+	ID   int64  `json:"id"`
+	Type string `json:"type"`
+}
+
+type Message struct {
+	MessageID     int         `json:"message_id"`
+	From          *User       `json:"from,omitempty"`
+	Chat          Chat        `json:"chat"`
+	Text          string      `json:"text,omitempty"`
+	Caption       string      `json:"caption,omitempty"`
+	Document      *Document   `json:"document,omitempty"`
+	Photo         []PhotoSize `json:"photo,omitempty"`
+	PinnedMessage *Message    `json:"pinned_message,omitempty"`
+}
+
+type Document struct {
+	FileID   string `json:"file_id"`
+	FileName string `json:"file_name,omitempty"`
+	MimeType string `json:"mime_type,omitempty"`
+	FileSize int64  `json:"file_size,omitempty"`
+}
+
+type PhotoSize struct {
+	FileID   string `json:"file_id"`
+	FileSize int64  `json:"file_size,omitempty"`
+	Width    int    `json:"width"`
+	Height   int    `json:"height"`
+}
+
+type CallbackQuery struct {
+	ID      string   `json:"id"`
+	From    User     `json:"from"`
+	Message *Message `json:"message,omitempty"`
+	Data    string   `json:"data,omitempty"`
+}
+
+type File struct {
+	FileID   string `json:"file_id"`
+	FilePath string `json:"file_path,omitempty"`
+	FileSize int64  `json:"file_size,omitempty"`
+}
+
+type InlineKeyboardMarkup struct {
+	InlineKeyboard [][]InlineKeyboardButton `json:"inline_keyboard"`
+}
+
+type InlineKeyboardButton struct {
+	Text         string `json:"text"`
+	CallbackData string `json:"callback_data,omitempty"`
+}
+
+type SendMessageOptions struct {
+	ParseMode   string                `json:"parse_mode,omitempty"`
+	ReplyMarkup *InlineKeyboardMarkup `json:"reply_markup,omitempty"`
+}
+
+type EditMessageTextOptions struct {
+	ParseMode   string                `json:"parse_mode,omitempty"`
+	ReplyMarkup *InlineKeyboardMarkup `json:"reply_markup,omitempty"`
+}

schemas/ApplyPatchApprovalParams.json

@@ -0,0 +1,114 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "ApplyPatchApprovalParams",
+  "type": "object",
+  "required": [
+    "callId",
+    "conversationId",
+    "fileChanges"
+  ],
+  "properties": {
+    "callId": {
+      "description": "Use to correlate this with [codex_protocol::protocol::PatchApplyBeginEvent] and [codex_protocol::protocol::PatchApplyEndEvent].",
+      "type": "string"
+    },
+    "conversationId": {
+      "$ref": "#/definitions/ThreadId"
+    },
+    "fileChanges": {
+      "type": "object",
+      "additionalProperties": {
+        "$ref": "#/definitions/FileChange"
+      }
+    },
+    "grantRoot": {
+      "description": "When set, the agent is asking the user to allow writes under this root for the remainder of the session (unclear if this is honored today).",
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "reason": {
+      "description": "Optional explanatory reason (e.g. request for extra write access).",
+      "type": [
+        "string",
+        "null"
+      ]
+    }
+  },
+  "definitions": {
+    "FileChange": {
+      "oneOf": [
+        {
+          "type": "object",
+          "required": [
+            "content",
+            "type"
+          ],
+          "properties": {
+            "content": {
+              "type": "string"
+            },
+            "type": {
+              "type": "string",
+              "enum": [
+                "add"
+              ],
+              "title": "AddFileChangeType"
+            }
+          },
+          "title": "AddFileChange"
+        },
+        {
+          "type": "object",
+          "required": [
+            "content",
+            "type"
+          ],
+          "properties": {
+            "content": {
+              "type": "string"
+            },
+            "type": {
+              "type": "string",
+              "enum": [
+                "delete"
+              ],
+              "title": "DeleteFileChangeType"
+            }
+          },
+          "title": "DeleteFileChange"
+        },
+        {
+          "type": "object",
+          "required": [
+            "type",
+            "unified_diff"
+          ],
+          "properties": {
+            "move_path": {
+              "type": [
+                "string",
+                "null"
+              ]
+            },
+            "type": {
+              "type": "string",
+              "enum": [
+                "update"
+              ],
+              "title": "UpdateFileChangeType"
+            },
+            "unified_diff": {
+              "type": "string"
+            }
+          },
+          "title": "UpdateFileChange"
+        }
+      ]
+    },
+    "ThreadId": {
+      "type": "string"
+    }
+  }
+}

schemas/ApplyPatchApprovalResponse.json

@@ -0,0 +1,124 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "ApplyPatchApprovalResponse",
+  "type": "object",
+  "required": [
+    "decision"
+  ],
+  "properties": {
+    "decision": {
+      "$ref": "#/definitions/ReviewDecision"
+    }
+  },
+  "definitions": {
+    "NetworkPolicyAmendment": {
+      "type": "object",
+      "required": [
+        "action",
+        "host"
+      ],
+      "properties": {
+        "action": {
+          "$ref": "#/definitions/NetworkPolicyRuleAction"
+        },
+        "host": {
+          "type": "string"
+        }
+      }
+    },
+    "NetworkPolicyRuleAction": {
+      "type": "string",
+      "enum": [
+        "allow",
+        "deny"
+      ]
+    },
+    "ReviewDecision": {
+      "description": "User's decision in response to an ExecApprovalRequest.",
+      "oneOf": [
+        {
+          "description": "User has approved this command and the agent should execute it.",
+          "type": "string",
+          "enum": [
+            "approved"
+          ]
+        },
+        {
+          "description": "User has approved this command and wants to apply the proposed execpolicy amendment so future matching commands are permitted.",
+          "type": "object",
+          "required": [
+            "approved_execpolicy_amendment"
+          ],
+          "properties": {
+            "approved_execpolicy_amendment": {
+              "type": "object",
+              "required": [
+                "proposed_execpolicy_amendment"
+              ],
+              "properties": {
+                "proposed_execpolicy_amendment": {
+                  "type": "array",
+                  "items": {
+                    "type": "string"
+                  }
+                }
+              }
+            }
+          },
+          "additionalProperties": false,
+          "title": "ApprovedExecpolicyAmendmentReviewDecision"
+        },
+        {
+          "description": "User has approved this request and wants future prompts in the same session-scoped approval cache to be automatically approved for the remainder of the session.",
+          "type": "string",
+          "enum": [
+            "approved_for_session"
+          ]
+        },
+        {
+          "description": "User chose to persist a network policy rule (allow/deny) for future requests to the same host.",
+          "type": "object",
+          "required": [
+            "network_policy_amendment"
+          ],
+          "properties": {
+            "network_policy_amendment": {
+              "type": "object",
+              "required": [
+                "network_policy_amendment"
+              ],
+              "properties": {
+                "network_policy_amendment": {
+                  "$ref": "#/definitions/NetworkPolicyAmendment"
+                }
+              }
+            }
+          },
+          "additionalProperties": false,
+          "title": "NetworkPolicyAmendmentReviewDecision"
+        },
+        {
+          "description": "User has denied this command and the agent should not execute it, but it should continue the session and try something else.",
+          "type": "string",
+          "enum": [
+            "denied"
+          ]
+        },
+        {
+          "description": "Automatic approval review timed out before reaching a decision.",
+          "type": "string",
+          "enum": [
+            "timed_out"
+          ]
+        },
+        {
+          "description": "User has denied this command and the agent should not do anything until the user's next command.",
+          "type": "string",
+          "enum": [
+            "abort"
+          ]
+        }
+      ]
+    }
+  }
+}

schemas/AttestationGenerateParams.json

@@ -0,0 +1,5 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "AttestationGenerateParams",
+  "type": "object"
+}

schemas/AttestationGenerateResponse.json

@@ -0,0 +1,14 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "AttestationGenerateResponse",
+  "type": "object",
+  "required": [
+    "token"
+  ],
+  "properties": {
+    "token": {
+      "description": "Opaque client attestation token.",
+      "type": "string"
+    }
+  }
+}

schemas/ChatgptAuthTokensRefreshParams.json

@@ -0,0 +1,33 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "ChatgptAuthTokensRefreshParams",
+  "type": "object",
+  "required": [
+    "reason"
+  ],
+  "properties": {
+    "previousAccountId": {
+      "description": "Workspace/account identifier that Codex was previously using.\n\nClients that manage multiple accounts/workspaces can use this as a hint to refresh the token for the correct workspace.\n\nThis may be `null` when the prior auth state did not include a workspace identifier (`chatgpt_account_id`).",
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "reason": {
+      "$ref": "#/definitions/ChatgptAuthTokensRefreshReason"
+    }
+  },
+  "definitions": {
+    "ChatgptAuthTokensRefreshReason": {
+      "oneOf": [
+        {
+          "description": "Codex attempted a backend request and received `401 Unauthorized`.",
+          "type": "string",
+          "enum": [
+            "unauthorized"
+          ]
+        }
+      ]
+    }
+  }
+}

schemas/ChatgptAuthTokensRefreshResponse.json

@@ -0,0 +1,23 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "ChatgptAuthTokensRefreshResponse",
+  "type": "object",
+  "required": [
+    "accessToken",
+    "chatgptAccountId"
+  ],
+  "properties": {
+    "accessToken": {
+      "type": "string"
+    },
+    "chatgptAccountId": {
+      "type": "string"
+    },
+    "chatgptPlanType": {
+      "type": [
+        "string",
+        "null"
+      ]
+    }
+  }
+}

schemas/ClientNotification.json

@@ -0,0 +1,22 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "ClientNotification",
+  "oneOf": [
+    {
+      "type": "object",
+      "required": [
+        "method"
+      ],
+      "properties": {
+        "method": {
+          "type": "string",
+          "enum": [
+            "initialized"
+          ],
+          "title": "InitializedNotificationMethod"
+        }
+      },
+      "title": "InitializedNotification"
+    }
+  ]
+}

schemas/CommandExecutionRequestApprovalParams.json

@@ -0,0 +1,616 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "CommandExecutionRequestApprovalParams",
+  "type": "object",
+  "required": [
+    "itemId",
+    "startedAtMs",
+    "threadId",
+    "turnId"
+  ],
+  "properties": {
+    "turnId": {
+      "type": "string"
+    },
+    "approvalId": {
+      "description": "Unique identifier for this specific approval callback.\n\nFor regular shell/unified_exec approvals, this is null.\n\nFor zsh-exec-bridge subcommand approvals, multiple callbacks can belong to one parent `itemId`, so `approvalId` is a distinct opaque callback id (a UUID) used to disambiguate routing.",
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "threadId": {
+      "type": "string"
+    },
+    "command": {
+      "description": "The command to be executed.",
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "commandActions": {
+      "description": "Best-effort parsed command actions for friendly display.",
+      "type": [
+        "array",
+        "null"
+      ],
+      "items": {
+        "$ref": "#/definitions/CommandAction"
+      }
+    },
+    "cwd": {
+      "description": "The command's working directory.",
+      "anyOf": [
+        {
+          "$ref": "#/definitions/AbsolutePathBuf"
+        },
+        {
+          "type": "null"
+        }
+      ]
+    },
+    "itemId": {
+      "type": "string"
+    },
+    "networkApprovalContext": {
+      "description": "Optional context for a managed-network approval prompt.",
+      "anyOf": [
+        {
+          "$ref": "#/definitions/NetworkApprovalContext"
+        },
+        {
+          "type": "null"
+        }
+      ]
+    },
+    "proposedExecpolicyAmendment": {
+      "description": "Optional proposed execpolicy amendment to allow similar commands without prompting.",
+      "type": [
+        "array",
+        "null"
+      ],
+      "items": {
+        "type": "string"
+      }
+    },
+    "proposedNetworkPolicyAmendments": {
+      "description": "Optional proposed network policy amendments (allow/deny host) for future requests.",
+      "type": [
+        "array",
+        "null"
+      ],
+      "items": {
+        "$ref": "#/definitions/NetworkPolicyAmendment"
+      }
+    },
+    "reason": {
+      "description": "Optional explanatory reason (e.g. request for network access).",
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "startedAtMs": {
+      "description": "Unix timestamp (in milliseconds) when this approval request started.",
+      "type": "integer",
+      "format": "int64"
+    }
+  },
+  "definitions": {
+    "AbsolutePathBuf": {
+      "description": "A path that is guaranteed to be absolute and normalized (though it is not guaranteed to be canonicalized or exist on the filesystem).\n\nIMPORTANT: When deserializing an `AbsolutePathBuf`, a base path must be set using [AbsolutePathBufGuard::new]. If no base path is set, the deserialization will fail unless the path being deserialized is already absolute.",
+      "type": "string"
+    },
+    "AdditionalFileSystemPermissions": {
+      "type": "object",
+      "properties": {
+        "entries": {
+          "type": [
+            "array",
+            "null"
+          ],
+          "items": {
+            "$ref": "#/definitions/FileSystemSandboxEntry"
+          }
+        },
+        "globScanMaxDepth": {
+          "type": [
+            "integer",
+            "null"
+          ],
+          "format": "uint",
+          "minimum": 1.0
+        },
+        "read": {
+          "description": "This will be removed in favor of `entries`.",
+          "type": [
+            "array",
+            "null"
+          ],
+          "items": {
+            "$ref": "#/definitions/AbsolutePathBuf"
+          }
+        },
+        "write": {
+          "description": "This will be removed in favor of `entries`.",
+          "type": [
+            "array",
+            "null"
+          ],
+          "items": {
+            "$ref": "#/definitions/AbsolutePathBuf"
+          }
+        }
+      }
+    },
+    "AdditionalNetworkPermissions": {
+      "type": "object",
+      "properties": {
+        "enabled": {
+          "type": [
+            "boolean",
+            "null"
+          ]
+        }
+      }
+    },
+    "AdditionalPermissionProfile": {
+      "type": "object",
+      "properties": {
+        "fileSystem": {
+          "anyOf": [
+            {
+              "$ref": "#/definitions/AdditionalFileSystemPermissions"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "network": {
+          "description": "Partial overlay used for per-command permission requests.",
+          "anyOf": [
+            {
+              "$ref": "#/definitions/AdditionalNetworkPermissions"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        }
+      }
+    },
+    "CommandAction": {
+      "oneOf": [
+        {
+          "type": "object",
+          "required": [
+            "command",
+            "name",
+            "path",
+            "type"
+          ],
+          "properties": {
+            "command": {
+              "type": "string"
+            },
+            "name": {
+              "type": "string"
+            },
+            "path": {
+              "$ref": "#/definitions/AbsolutePathBuf"
+            },
+            "type": {
+              "type": "string",
+              "enum": [
+                "read"
+              ],
+              "title": "ReadCommandActionType"
+            }
+          },
+          "title": "ReadCommandAction"
+        },
+        {
+          "type": "object",
+          "required": [
+            "command",
+            "type"
+          ],
+          "properties": {
+            "command": {
+              "type": "string"
+            },
+            "path": {
+              "type": [
+                "string",
+                "null"
+              ]
+            },
+            "type": {
+              "type": "string",
+              "enum": [
+                "listFiles"
+              ],
+              "title": "ListFilesCommandActionType"
+            }
+          },
+          "title": "ListFilesCommandAction"
+        },
+        {
+          "type": "object",
+          "required": [
+            "command",
+            "type"
+          ],
+          "properties": {
+            "command": {
+              "type": "string"
+            },
+            "path": {
+              "type": [
+                "string",
+                "null"
+              ]
+            },
+            "query": {
+              "type": [
+                "string",
+                "null"
+              ]
+            },
+            "type": {
+              "type": "string",
+              "enum": [
+                "search"
+              ],
+              "title": "SearchCommandActionType"
+            }
+          },
+          "title": "SearchCommandAction"
+        },
+        {
+          "type": "object",
+          "required": [
+            "command",
+            "type"
+          ],
+          "properties": {
+            "command": {
+              "type": "string"
+            },
+            "type": {
+              "type": "string",
+              "enum": [
+                "unknown"
+              ],
+              "title": "UnknownCommandActionType"
+            }
+          },
+          "title": "UnknownCommandAction"
+        }
+      ]
+    },
+    "CommandExecutionApprovalDecision": {
+      "oneOf": [
+        {
+          "description": "User approved the command.",
+          "type": "string",
+          "enum": [
+            "accept"
+          ]
+        },
+        {
+          "description": "User approved the command and future prompts in the same session-scoped approval cache should run without prompting.",
+          "type": "string",
+          "enum": [
+            "acceptForSession"
+          ]
+        },
+        {
+          "description": "User approved the command, and wants to apply the proposed execpolicy amendment so future matching commands can run without prompting.",
+          "type": "object",
+          "required": [
+            "acceptWithExecpolicyAmendment"
+          ],
+          "properties": {
+            "acceptWithExecpolicyAmendment": {
+              "type": "object",
+              "required": [
+                "execpolicy_amendment"
+              ],
+              "properties": {
+                "execpolicy_amendment": {
+                  "type": "array",
+                  "items": {
+                    "type": "string"
+                  }
+                }
+              }
+            }
+          },
+          "additionalProperties": false,
+          "title": "AcceptWithExecpolicyAmendmentCommandExecutionApprovalDecision"
+        },
+        {
+          "description": "User chose a persistent network policy rule (allow/deny) for this host.",
+          "type": "object",
+          "required": [
+            "applyNetworkPolicyAmendment"
+          ],
+          "properties": {
+            "applyNetworkPolicyAmendment": {
+              "type": "object",
+              "required": [
+                "network_policy_amendment"
+              ],
+              "properties": {
+                "network_policy_amendment": {
+                  "$ref": "#/definitions/NetworkPolicyAmendment"
+                }
+              }
+            }
+          },
+          "additionalProperties": false,
+          "title": "ApplyNetworkPolicyAmendmentCommandExecutionApprovalDecision"
+        },
+        {
+          "description": "User denied the command. The agent will continue the turn.",
+          "type": "string",
+          "enum": [
+            "decline"
+          ]
+        },
+        {
+          "description": "User denied the command. The turn will also be immediately interrupted.",
+          "type": "string",
+          "enum": [
+            "cancel"
+          ]
+        }
+      ]
+    },
+    "FileSystemAccessMode": {
+      "type": "string",
+      "enum": [
+        "read",
+        "write",
+        "none"
+      ]
+    },
+    "FileSystemPath": {
+      "oneOf": [
+        {
+          "type": "object",
+          "required": [
+            "path",
+            "type"
+          ],
+          "properties": {
+            "path": {
+              "$ref": "#/definitions/AbsolutePathBuf"
+            },
+            "type": {
+              "type": "string",
+              "enum": [
+                "path"
+              ],
+              "title": "PathFileSystemPathType"
+            }
+          },
+          "title": "PathFileSystemPath"
+        },
+        {
+          "type": "object",
+          "required": [
+            "pattern",
+            "type"
+          ],
+          "properties": {
+            "pattern": {
+              "type": "string"
+            },
+            "type": {
+              "type": "string",
+              "enum": [
+                "glob_pattern"
+              ],
+              "title": "GlobPatternFileSystemPathType"
+            }
+          },
+          "title": "GlobPatternFileSystemPath"
+        },
+        {
+          "type": "object",
+          "required": [
+            "type",
+            "value"
+          ],
+          "properties": {
+            "type": {
+              "type": "string",
+              "enum": [
+                "special"
+              ],
+              "title": "SpecialFileSystemPathType"
+            },
+            "value": {
+              "$ref": "#/definitions/FileSystemSpecialPath"
+            }
+          },
+          "title": "SpecialFileSystemPath"
+        }
+      ]
+    },
+    "FileSystemSandboxEntry": {
+      "type": "object",
+      "required": [
+        "access",
+        "path"
+      ],
+      "properties": {
+        "access": {
+          "$ref": "#/definitions/FileSystemAccessMode"
+        },
+        "path": {
+          "$ref": "#/definitions/FileSystemPath"
+        }
+      }
+    },
+    "FileSystemSpecialPath": {
+      "oneOf": [
+        {
+          "type": "object",
+          "required": [
+            "kind"
+          ],
+          "properties": {
+            "kind": {
+              "type": "string",
+              "enum": [
+                "root"
+              ]
+            }
+          },
+          "title": "RootFileSystemSpecialPath"
+        },
+        {
+          "type": "object",
+          "required": [
+            "kind"
+          ],
+          "properties": {
+            "kind": {
+              "type": "string",
+              "enum": [
+                "minimal"
+              ]
+            }
+          },
+          "title": "MinimalFileSystemSpecialPath"
+        },
+        {
+          "type": "object",
+          "required": [
+            "kind"
+          ],
+          "properties": {
+            "kind": {
+              "type": "string",
+              "enum": [
+                "project_roots"
+              ]
+            },
+            "subpath": {
+              "type": [
+                "string",
+                "null"
+              ]
+            }
+          },
+          "title": "KindFileSystemSpecialPath"
+        },
+        {
+          "type": "object",
+          "required": [
+            "kind"
+          ],
+          "properties": {
+            "kind": {
+              "type": "string",
+              "enum": [
+                "tmpdir"
+              ]
+            }
+          },
+          "title": "TmpdirFileSystemSpecialPath"
+        },
+        {
+          "type": "object",
+          "required": [
+            "kind"
+          ],
+          "properties": {
+            "kind": {
+              "type": "string",
+              "enum": [
+                "slash_tmp"
+              ]
+            }
+          },
+          "title": "SlashTmpFileSystemSpecialPath"
+        },
+        {
+          "type": "object",
+          "required": [
+            "kind",
+            "path"
+          ],
+          "properties": {
+            "kind": {
+              "type": "string",
+              "enum": [
+                "unknown"
+              ]
+            },
+            "path": {
+              "type": "string"
+            },
+            "subpath": {
+              "type": [
+                "string",
+                "null"
+              ]
+            }
+          }
+        }
+      ]
+    },
+    "NetworkApprovalContext": {
+      "type": "object",
+      "required": [
+        "host",
+        "protocol"
+      ],
+      "properties": {
+        "host": {
+          "type": "string"
+        },
+        "protocol": {
+          "$ref": "#/definitions/NetworkApprovalProtocol"
+        }
+      }
+    },
+    "NetworkApprovalProtocol": {
+      "type": "string",
+      "enum": [
+        "http",
+        "https",
+        "socks5Tcp",
+        "socks5Udp"
+      ]
+    },
+    "NetworkPolicyAmendment": {
+      "type": "object",
+      "required": [
+        "action",
+        "host"
+      ],
+      "properties": {
+        "action": {
+          "$ref": "#/definitions/NetworkPolicyRuleAction"
+        },
+        "host": {
+          "type": "string"
+        }
+      }
+    },
+    "NetworkPolicyRuleAction": {
+      "type": "string",
+      "enum": [
+        "allow",
+        "deny"
+      ]
+    }
+  }
+}

schemas/CommandExecutionRequestApprovalResponse.json

@@ -0,0 +1,116 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "CommandExecutionRequestApprovalResponse",
+  "type": "object",
+  "required": [
+    "decision"
+  ],
+  "properties": {
+    "decision": {
+      "$ref": "#/definitions/CommandExecutionApprovalDecision"
+    }
+  },
+  "definitions": {
+    "CommandExecutionApprovalDecision": {
+      "oneOf": [
+        {
+          "description": "User approved the command.",
+          "type": "string",
+          "enum": [
+            "accept"
+          ]
+        },
+        {
+          "description": "User approved the command and future prompts in the same session-scoped approval cache should run without prompting.",
+          "type": "string",
+          "enum": [
+            "acceptForSession"
+          ]
+        },
+        {
+          "description": "User approved the command, and wants to apply the proposed execpolicy amendment so future matching commands can run without prompting.",
+          "type": "object",
+          "required": [
+            "acceptWithExecpolicyAmendment"
+          ],
+          "properties": {
+            "acceptWithExecpolicyAmendment": {
+              "type": "object",
+              "required": [
+                "execpolicy_amendment"
+              ],
+              "properties": {
+                "execpolicy_amendment": {
+                  "type": "array",
+                  "items": {
+                    "type": "string"
+                  }
+                }
+              }
+            }
+          },
+          "additionalProperties": false,
+          "title": "AcceptWithExecpolicyAmendmentCommandExecutionApprovalDecision"
+        },
+        {
+          "description": "User chose a persistent network policy rule (allow/deny) for this host.",
+          "type": "object",
+          "required": [
+            "applyNetworkPolicyAmendment"
+          ],
+          "properties": {
+            "applyNetworkPolicyAmendment": {
+              "type": "object",
+              "required": [
+                "network_policy_amendment"
+              ],
+              "properties": {
+                "network_policy_amendment": {
+                  "$ref": "#/definitions/NetworkPolicyAmendment"
+                }
+              }
+            }
+          },
+          "additionalProperties": false,
+          "title": "ApplyNetworkPolicyAmendmentCommandExecutionApprovalDecision"
+        },
+        {
+          "description": "User denied the command. The agent will continue the turn.",
+          "type": "string",
+          "enum": [
+            "decline"
+          ]
+        },
+        {
+          "description": "User denied the command. The turn will also be immediately interrupted.",
+          "type": "string",
+          "enum": [
+            "cancel"
+          ]
+        }
+      ]
+    },
+    "NetworkPolicyAmendment": {
+      "type": "object",
+      "required": [
+        "action",
+        "host"
+      ],
+      "properties": {
+        "action": {
+          "$ref": "#/definitions/NetworkPolicyRuleAction"
+        },
+        "host": {
+          "type": "string"
+        }
+      }
+    },
+    "NetworkPolicyRuleAction": {
+      "type": "string",
+      "enum": [
+        "allow",
+        "deny"
+      ]
+    }
+  }
+}

schemas/DynamicToolCallParams.json

@@ -0,0 +1,33 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "DynamicToolCallParams",
+  "type": "object",
+  "required": [
+    "arguments",
+    "callId",
+    "threadId",
+    "tool",
+    "turnId"
+  ],
+  "properties": {
+    "arguments": true,
+    "callId": {
+      "type": "string"
+    },
+    "namespace": {
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "threadId": {
+      "type": "string"
+    },
+    "tool": {
+      "type": "string"
+    },
+    "turnId": {
+      "type": "string"
+    }
+  }
+}

schemas/DynamicToolCallResponse.json

@@ -0,0 +1,66 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "DynamicToolCallResponse",
+  "type": "object",
+  "required": [
+    "contentItems",
+    "success"
+  ],
+  "properties": {
+    "contentItems": {
+      "type": "array",
+      "items": {
+        "$ref": "#/definitions/DynamicToolCallOutputContentItem"
+      }
+    },
+    "success": {
+      "type": "boolean"
+    }
+  },
+  "definitions": {
+    "DynamicToolCallOutputContentItem": {
+      "oneOf": [
+        {
+          "type": "object",
+          "required": [
+            "text",
+            "type"
+          ],
+          "properties": {
+            "text": {
+              "type": "string"
+            },
+            "type": {
+              "type": "string",
+              "enum": [
+                "inputText"
+              ],
+              "title": "InputTextDynamicToolCallOutputContentItemType"
+            }
+          },
+          "title": "InputTextDynamicToolCallOutputContentItem"
+        },
+        {
+          "type": "object",
+          "required": [
+            "imageUrl",
+            "type"
+          ],
+          "properties": {
+            "imageUrl": {
+              "type": "string"
+            },
+            "type": {
+              "type": "string",
+              "enum": [
+                "inputImage"
+              ],
+              "title": "InputImageDynamicToolCallOutputContentItemType"
+            }
+          },
+          "title": "InputImageDynamicToolCallOutputContentItem"
+        }
+      ]
+    }
+  }
+}

schemas/ExecCommandApprovalParams.json

@@ -0,0 +1,165 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "ExecCommandApprovalParams",
+  "type": "object",
+  "required": [
+    "callId",
+    "command",
+    "conversationId",
+    "cwd",
+    "parsedCmd"
+  ],
+  "properties": {
+    "approvalId": {
+      "description": "Identifier for this specific approval callback.",
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "callId": {
+      "description": "Use to correlate this with [codex_protocol::protocol::ExecCommandBeginEvent] and [codex_protocol::protocol::ExecCommandEndEvent].",
+      "type": "string"
+    },
+    "command": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    },
+    "conversationId": {
+      "$ref": "#/definitions/ThreadId"
+    },
+    "cwd": {
+      "type": "string"
+    },
+    "parsedCmd": {
+      "type": "array",
+      "items": {
+        "$ref": "#/definitions/ParsedCommand"
+      }
+    },
+    "reason": {
+      "type": [
+        "string",
+        "null"
+      ]
+    }
+  },
+  "definitions": {
+    "ParsedCommand": {
+      "oneOf": [
+        {
+          "type": "object",
+          "required": [
+            "cmd",
+            "name",
+            "path",
+            "type"
+          ],
+          "properties": {
+            "cmd": {
+              "type": "string"
+            },
+            "name": {
+              "type": "string"
+            },
+            "path": {
+              "description": "(Best effort) Path to the file being read by the command. When possible, this is an absolute path, though when relative, it should be resolved against the `cwd`` that will be used to run the command to derive the absolute path.",
+              "type": "string"
+            },
+            "type": {
+              "type": "string",
+              "enum": [
+                "read"
+              ],
+              "title": "ReadParsedCommandType"
+            }
+          },
+          "title": "ReadParsedCommand"
+        },
+        {
+          "type": "object",
+          "required": [
+            "cmd",
+            "type"
+          ],
+          "properties": {
+            "cmd": {
+              "type": "string"
+            },
+            "path": {
+              "type": [
+                "string",
+                "null"
+              ]
+            },
+            "type": {
+              "type": "string",
+              "enum": [
+                "list_files"
+              ],
+              "title": "ListFilesParsedCommandType"
+            }
+          },
+          "title": "ListFilesParsedCommand"
+        },
+        {
+          "type": "object",
+          "required": [
+            "cmd",
+            "type"
+          ],
+          "properties": {
+            "cmd": {
+              "type": "string"
+            },
+            "path": {
+              "type": [
+                "string",
+                "null"
+              ]
+            },
+            "query": {
+              "type": [
+                "string",
+                "null"
+              ]
+            },
+            "type": {
+              "type": "string",
+              "enum": [
+                "search"
+              ],
+              "title": "SearchParsedCommandType"
+            }
+          },
+          "title": "SearchParsedCommand"
+        },
+        {
+          "type": "object",
+          "required": [
+            "cmd",
+            "type"
+          ],
+          "properties": {
+            "cmd": {
+              "type": "string"
+            },
+            "type": {
+              "type": "string",
+              "enum": [
+                "unknown"
+              ],
+              "title": "UnknownParsedCommandType"
+            }
+          },
+          "title": "UnknownParsedCommand"
+        }
+      ]
+    },
+    "ThreadId": {
+      "type": "string"
+    }
+  }
+}

schemas/ExecCommandApprovalResponse.json

@@ -0,0 +1,124 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "ExecCommandApprovalResponse",
+  "type": "object",
+  "required": [
+    "decision"
+  ],
+  "properties": {
+    "decision": {
+      "$ref": "#/definitions/ReviewDecision"
+    }
+  },
+  "definitions": {
+    "NetworkPolicyAmendment": {
+      "type": "object",
+      "required": [
+        "action",
+        "host"
+      ],
+      "properties": {
+        "action": {
+          "$ref": "#/definitions/NetworkPolicyRuleAction"
+        },
+        "host": {
+          "type": "string"
+        }
+      }
+    },
+    "NetworkPolicyRuleAction": {
+      "type": "string",
+      "enum": [
+        "allow",
+        "deny"
+      ]
+    },
+    "ReviewDecision": {
+      "description": "User's decision in response to an ExecApprovalRequest.",
+      "oneOf": [
+        {
+          "description": "User has approved this command and the agent should execute it.",
+          "type": "string",
+          "enum": [
+            "approved"
+          ]
+        },
+        {
+          "description": "User has approved this command and wants to apply the proposed execpolicy amendment so future matching commands are permitted.",
+          "type": "object",
+          "required": [
+            "approved_execpolicy_amendment"
+          ],
+          "properties": {
+            "approved_execpolicy_amendment": {
+              "type": "object",
+              "required": [
+                "proposed_execpolicy_amendment"
+              ],
+              "properties": {
+                "proposed_execpolicy_amendment": {
+                  "type": "array",
+                  "items": {
+                    "type": "string"
+                  }
+                }
+              }
+            }
+          },
+          "additionalProperties": false,
+          "title": "ApprovedExecpolicyAmendmentReviewDecision"
+        },
+        {
+          "description": "User has approved this request and wants future prompts in the same session-scoped approval cache to be automatically approved for the remainder of the session.",
+          "type": "string",
+          "enum": [
+            "approved_for_session"
+          ]
+        },
+        {
+          "description": "User chose to persist a network policy rule (allow/deny) for future requests to the same host.",
+          "type": "object",
+          "required": [
+            "network_policy_amendment"
+          ],
+          "properties": {
+            "network_policy_amendment": {
+              "type": "object",
+              "required": [
+                "network_policy_amendment"
+              ],
+              "properties": {
+                "network_policy_amendment": {
+                  "$ref": "#/definitions/NetworkPolicyAmendment"
+                }
+              }
+            }
+          },
+          "additionalProperties": false,
+          "title": "NetworkPolicyAmendmentReviewDecision"
+        },
+        {
+          "description": "User has denied this command and the agent should not execute it, but it should continue the session and try something else.",
+          "type": "string",
+          "enum": [
+            "denied"
+          ]
+        },
+        {
+          "description": "Automatic approval review timed out before reaching a decision.",
+          "type": "string",
+          "enum": [
+            "timed_out"
+          ]
+        },
+        {
+          "description": "User has denied this command and the agent should not do anything until the user's next command.",
+          "type": "string",
+          "enum": [
+            "abort"
+          ]
+        }
+      ]
+    }
+  }
+}

schemas/FileChangeRequestApprovalParams.json

@@ -0,0 +1,41 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "FileChangeRequestApprovalParams",
+  "type": "object",
+  "required": [
+    "itemId",
+    "startedAtMs",
+    "threadId",
+    "turnId"
+  ],
+  "properties": {
+    "grantRoot": {
+      "description": "[UNSTABLE] When set, the agent is asking the user to allow writes under this root for the remainder of the session (unclear if this is honored today).",
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "itemId": {
+      "type": "string"
+    },
+    "reason": {
+      "description": "Optional explanatory reason (e.g. request for extra write access).",
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "startedAtMs": {
+      "description": "Unix timestamp (in milliseconds) when this approval request started.",
+      "type": "integer",
+      "format": "int64"
+    },
+    "threadId": {
+      "type": "string"
+    },
+    "turnId": {
+      "type": "string"
+    }
+  }
+}

schemas/FileChangeRequestApprovalResponse.json

@@ -0,0 +1,47 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "FileChangeRequestApprovalResponse",
+  "type": "object",
+  "required": [
+    "decision"
+  ],
+  "properties": {
+    "decision": {
+      "$ref": "#/definitions/FileChangeApprovalDecision"
+    }
+  },
+  "definitions": {
+    "FileChangeApprovalDecision": {
+      "oneOf": [
+        {
+          "description": "User approved the file changes.",
+          "type": "string",
+          "enum": [
+            "accept"
+          ]
+        },
+        {
+          "description": "User approved the file changes and future changes to the same files should run without prompting.",
+          "type": "string",
+          "enum": [
+            "acceptForSession"
+          ]
+        },
+        {
+          "description": "User denied the file changes. The agent will continue the turn.",
+          "type": "string",
+          "enum": [
+            "decline"
+          ]
+        },
+        {
+          "description": "User denied the file changes. The turn will also be immediately interrupted.",
+          "type": "string",
+          "enum": [
+            "cancel"
+          ]
+        }
+      ]
+    }
+  }
+}

schemas/FuzzyFileSearchParams.json

@@ -0,0 +1,26 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "FuzzyFileSearchParams",
+  "type": "object",
+  "required": [
+    "query",
+    "roots"
+  ],
+  "properties": {
+    "cancellationToken": {
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "query": {
+      "type": "string"
+    },
+    "roots": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    }
+  }
+}

schemas/FuzzyFileSearchResponse.json

@@ -0,0 +1,66 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "FuzzyFileSearchResponse",
+  "type": "object",
+  "required": [
+    "files"
+  ],
+  "properties": {
+    "files": {
+      "type": "array",
+      "items": {
+        "$ref": "#/definitions/FuzzyFileSearchResult"
+      }
+    }
+  },
+  "definitions": {
+    "FuzzyFileSearchMatchType": {
+      "type": "string",
+      "enum": [
+        "file",
+        "directory"
+      ]
+    },
+    "FuzzyFileSearchResult": {
+      "description": "Superset of [`codex_file_search::FileMatch`]",
+      "type": "object",
+      "required": [
+        "file_name",
+        "match_type",
+        "path",
+        "root",
+        "score"
+      ],
+      "properties": {
+        "file_name": {
+          "type": "string"
+        },
+        "indices": {
+          "type": [
+            "array",
+            "null"
+          ],
+          "items": {
+            "type": "integer",
+            "format": "uint32",
+            "minimum": 0.0
+          }
+        },
+        "match_type": {
+          "$ref": "#/definitions/FuzzyFileSearchMatchType"
+        },
+        "path": {
+          "type": "string"
+        },
+        "root": {
+          "type": "string"
+        },
+        "score": {
+          "type": "integer",
+          "format": "uint32",
+          "minimum": 0.0
+        }
+      }
+    }
+  }
+}

schemas/FuzzyFileSearchSessionCompletedNotification.json

@@ -0,0 +1,13 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "FuzzyFileSearchSessionCompletedNotification",
+  "type": "object",
+  "required": [
+    "sessionId"
+  ],
+  "properties": {
+    "sessionId": {
+      "type": "string"
+    }
+  }
+}

schemas/FuzzyFileSearchSessionUpdatedNotification.json

@@ -0,0 +1,74 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "FuzzyFileSearchSessionUpdatedNotification",
+  "type": "object",
+  "required": [
+    "files",
+    "query",
+    "sessionId"
+  ],
+  "properties": {
+    "files": {
+      "type": "array",
+      "items": {
+        "$ref": "#/definitions/FuzzyFileSearchResult"
+      }
+    },
+    "query": {
+      "type": "string"
+    },
+    "sessionId": {
+      "type": "string"
+    }
+  },
+  "definitions": {
+    "FuzzyFileSearchMatchType": {
+      "type": "string",
+      "enum": [
+        "file",
+        "directory"
+      ]
+    },
+    "FuzzyFileSearchResult": {
+      "description": "Superset of [`codex_file_search::FileMatch`]",
+      "type": "object",
+      "required": [
+        "file_name",
+        "match_type",
+        "path",
+        "root",
+        "score"
+      ],
+      "properties": {
+        "file_name": {
+          "type": "string"
+        },
+        "indices": {
+          "type": [
+            "array",
+            "null"
+          ],
+          "items": {
+            "type": "integer",
+            "format": "uint32",
+            "minimum": 0.0
+          }
+        },
+        "match_type": {
+          "$ref": "#/definitions/FuzzyFileSearchMatchType"
+        },
+        "path": {
+          "type": "string"
+        },
+        "root": {
+          "type": "string"
+        },
+        "score": {
+          "type": "integer",
+          "format": "uint32",
+          "minimum": 0.0
+        }
+      }
+    }
+  }
+}

schemas/JSONRPCError.json

@@ -0,0 +1,48 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "JSONRPCError",
+  "description": "A response to a request that indicates an error occurred.",
+  "type": "object",
+  "required": [
+    "error",
+    "id"
+  ],
+  "properties": {
+    "error": {
+      "$ref": "#/definitions/JSONRPCErrorError"
+    },
+    "id": {
+      "$ref": "#/definitions/RequestId"
+    }
+  },
+  "definitions": {
+    "JSONRPCErrorError": {
+      "type": "object",
+      "required": [
+        "code",
+        "message"
+      ],
+      "properties": {
+        "code": {
+          "type": "integer",
+          "format": "int64"
+        },
+        "data": true,
+        "message": {
+          "type": "string"
+        }
+      }
+    },
+    "RequestId": {
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "integer",
+          "format": "int64"
+        }
+      ]
+    }
+  }
+}

schemas/JSONRPCErrorError.json

@@ -0,0 +1,19 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "JSONRPCErrorError",
+  "type": "object",
+  "required": [
+    "code",
+    "message"
+  ],
+  "properties": {
+    "code": {
+      "type": "integer",
+      "format": "int64"
+    },
+    "data": true,
+    "message": {
+      "type": "string"
+    }
+  }
+}

schemas/JSONRPCMessage.json

@@ -0,0 +1,137 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "JSONRPCMessage",
+  "description": "Refers to any valid JSON-RPC object that can be decoded off the wire, or encoded to be sent.",
+  "anyOf": [
+    {
+      "$ref": "#/definitions/JSONRPCRequest"
+    },
+    {
+      "$ref": "#/definitions/JSONRPCNotification"
+    },
+    {
+      "$ref": "#/definitions/JSONRPCResponse"
+    },
+    {
+      "$ref": "#/definitions/JSONRPCError"
+    }
+  ],
+  "definitions": {
+    "JSONRPCError": {
+      "description": "A response to a request that indicates an error occurred.",
+      "type": "object",
+      "required": [
+        "error",
+        "id"
+      ],
+      "properties": {
+        "error": {
+          "$ref": "#/definitions/JSONRPCErrorError"
+        },
+        "id": {
+          "$ref": "#/definitions/RequestId"
+        }
+      }
+    },
+    "JSONRPCErrorError": {
+      "type": "object",
+      "required": [
+        "code",
+        "message"
+      ],
+      "properties": {
+        "code": {
+          "type": "integer",
+          "format": "int64"
+        },
+        "data": true,
+        "message": {
+          "type": "string"
+        }
+      }
+    },
+    "JSONRPCNotification": {
+      "description": "A notification which does not expect a response.",
+      "type": "object",
+      "required": [
+        "method"
+      ],
+      "properties": {
+        "method": {
+          "type": "string"
+        },
+        "params": true
+      }
+    },
+    "JSONRPCRequest": {
+      "description": "A request that expects a response.",
+      "type": "object",
+      "required": [
+        "id",
+        "method"
+      ],
+      "properties": {
+        "id": {
+          "$ref": "#/definitions/RequestId"
+        },
+        "method": {
+          "type": "string"
+        },
+        "params": true,
+        "trace": {
+          "description": "Optional W3C Trace Context for distributed tracing.",
+          "anyOf": [
+            {
+              "$ref": "#/definitions/W3cTraceContext"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        }
+      }
+    },
+    "JSONRPCResponse": {
+      "description": "A successful (non-error) response to a request.",
+      "type": "object",
+      "required": [
+        "id",
+        "result"
+      ],
+      "properties": {
+        "id": {
+          "$ref": "#/definitions/RequestId"
+        },
+        "result": true
+      }
+    },
+    "RequestId": {
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "integer",
+          "format": "int64"
+        }
+      ]
+    },
+    "W3cTraceContext": {
+      "type": "object",
+      "properties": {
+        "traceparent": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "tracestate": {
+          "type": [
+            "string",
+            "null"
+          ]
+        }
+      }
+    }
+  }
+}

schemas/JSONRPCNotification.json

@@ -0,0 +1,15 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "JSONRPCNotification",
+  "description": "A notification which does not expect a response.",
+  "type": "object",
+  "required": [
+    "method"
+  ],
+  "properties": {
+    "method": {
+      "type": "string"
+    },
+    "params": true
+  }
+}

schemas/JSONRPCRequest.json

@@ -0,0 +1,60 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "JSONRPCRequest",
+  "description": "A request that expects a response.",
+  "type": "object",
+  "required": [
+    "id",
+    "method"
+  ],
+  "properties": {
+    "id": {
+      "$ref": "#/definitions/RequestId"
+    },
+    "method": {
+      "type": "string"
+    },
+    "params": true,
+    "trace": {
+      "description": "Optional W3C Trace Context for distributed tracing.",
+      "anyOf": [
+        {
+          "$ref": "#/definitions/W3cTraceContext"
+        },
+        {
+          "type": "null"
+        }
+      ]
+    }
+  },
+  "definitions": {
+    "RequestId": {
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "integer",
+          "format": "int64"
+        }
+      ]
+    },
+    "W3cTraceContext": {
+      "type": "object",
+      "properties": {
+        "traceparent": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "tracestate": {
+          "type": [
+            "string",
+            "null"
+          ]
+        }
+      }
+    }
+  }
+}

schemas/JSONRPCResponse.json

@@ -0,0 +1,29 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "JSONRPCResponse",
+  "description": "A successful (non-error) response to a request.",
+  "type": "object",
+  "required": [
+    "id",
+    "result"
+  ],
+  "properties": {
+    "id": {
+      "$ref": "#/definitions/RequestId"
+    },
+    "result": true
+  },
+  "definitions": {
+    "RequestId": {
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "integer",
+          "format": "int64"
+        }
+      ]
+    }
+  }
+}

schemas/McpServerElicitationRequestParams.json

@@ -0,0 +1,609 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "McpServerElicitationRequestParams",
+  "type": "object",
+  "oneOf": [
+    {
+      "type": "object",
+      "required": [
+        "message",
+        "mode",
+        "requestedSchema"
+      ],
+      "properties": {
+        "_meta": true,
+        "message": {
+          "type": "string"
+        },
+        "mode": {
+          "type": "string",
+          "enum": [
+            "form"
+          ]
+        },
+        "requestedSchema": {
+          "$ref": "#/definitions/McpElicitationSchema"
+        }
+      }
+    },
+    {
+      "type": "object",
+      "required": [
+        "elicitationId",
+        "message",
+        "mode",
+        "url"
+      ],
+      "properties": {
+        "_meta": true,
+        "elicitationId": {
+          "type": "string"
+        },
+        "message": {
+          "type": "string"
+        },
+        "mode": {
+          "type": "string",
+          "enum": [
+            "url"
+          ]
+        },
+        "url": {
+          "type": "string"
+        }
+      }
+    }
+  ],
+  "required": [
+    "serverName",
+    "threadId"
+  ],
+  "properties": {
+    "serverName": {
+      "type": "string"
+    },
+    "threadId": {
+      "type": "string"
+    },
+    "turnId": {
+      "description": "Active Codex turn when this elicitation was observed, if app-server could correlate one.\n\nThis is nullable because MCP models elicitation as a standalone server-to-client request identified by the MCP server request id. It may be triggered during a turn, but turn context is app-server correlation rather than part of the protocol identity of the elicitation itself.",
+      "type": [
+        "string",
+        "null"
+      ]
+    }
+  },
+  "definitions": {
+    "McpElicitationArrayType": {
+      "type": "string",
+      "enum": [
+        "array"
+      ]
+    },
+    "McpElicitationBooleanSchema": {
+      "type": "object",
+      "required": [
+        "type"
+      ],
+      "properties": {
+        "default": {
+          "type": [
+            "boolean",
+            "null"
+          ]
+        },
+        "description": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "title": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "type": {
+          "$ref": "#/definitions/McpElicitationBooleanType"
+        }
+      },
+      "additionalProperties": false
+    },
+    "McpElicitationBooleanType": {
+      "type": "string",
+      "enum": [
+        "boolean"
+      ]
+    },
+    "McpElicitationConstOption": {
+      "type": "object",
+      "required": [
+        "const",
+        "title"
+      ],
+      "properties": {
+        "const": {
+          "type": "string"
+        },
+        "title": {
+          "type": "string"
+        }
+      },
+      "additionalProperties": false
+    },
+    "McpElicitationEnumSchema": {
+      "anyOf": [
+        {
+          "$ref": "#/definitions/McpElicitationSingleSelectEnumSchema"
+        },
+        {
+          "$ref": "#/definitions/McpElicitationMultiSelectEnumSchema"
+        },
+        {
+          "$ref": "#/definitions/McpElicitationLegacyTitledEnumSchema"
+        }
+      ]
+    },
+    "McpElicitationLegacyTitledEnumSchema": {
+      "type": "object",
+      "required": [
+        "enum",
+        "type"
+      ],
+      "properties": {
+        "default": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "description": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "enum": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "enumNames": {
+          "type": [
+            "array",
+            "null"
+          ],
+          "items": {
+            "type": "string"
+          }
+        },
+        "title": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "type": {
+          "$ref": "#/definitions/McpElicitationStringType"
+        }
+      },
+      "additionalProperties": false
+    },
+    "McpElicitationMultiSelectEnumSchema": {
+      "anyOf": [
+        {
+          "$ref": "#/definitions/McpElicitationUntitledMultiSelectEnumSchema"
+        },
+        {
+          "$ref": "#/definitions/McpElicitationTitledMultiSelectEnumSchema"
+        }
+      ]
+    },
+    "McpElicitationNumberSchema": {
+      "type": "object",
+      "required": [
+        "type"
+      ],
+      "properties": {
+        "default": {
+          "type": [
+            "number",
+            "null"
+          ],
+          "format": "double"
+        },
+        "description": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "maximum": {
+          "type": [
+            "number",
+            "null"
+          ],
+          "format": "double"
+        },
+        "minimum": {
+          "type": [
+            "number",
+            "null"
+          ],
+          "format": "double"
+        },
+        "title": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "type": {
+          "$ref": "#/definitions/McpElicitationNumberType"
+        }
+      },
+      "additionalProperties": false
+    },
+    "McpElicitationNumberType": {
+      "type": "string",
+      "enum": [
+        "number",
+        "integer"
+      ]
+    },
+    "McpElicitationObjectType": {
+      "type": "string",
+      "enum": [
+        "object"
+      ]
+    },
+    "McpElicitationPrimitiveSchema": {
+      "anyOf": [
+        {
+          "$ref": "#/definitions/McpElicitationEnumSchema"
+        },
+        {
+          "$ref": "#/definitions/McpElicitationStringSchema"
+        },
+        {
+          "$ref": "#/definitions/McpElicitationNumberSchema"
+        },
+        {
+          "$ref": "#/definitions/McpElicitationBooleanSchema"
+        }
+      ]
+    },
+    "McpElicitationSchema": {
+      "description": "Typed form schema for MCP `elicitation/create` requests.\n\nThis matches the `requestedSchema` shape from the MCP 2025-11-25 `ElicitRequestFormParams` schema.",
+      "type": "object",
+      "required": [
+        "properties",
+        "type"
+      ],
+      "properties": {
+        "$schema": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "properties": {
+          "type": "object",
+          "additionalProperties": {
+            "$ref": "#/definitions/McpElicitationPrimitiveSchema"
+          }
+        },
+        "required": {
+          "type": [
+            "array",
+            "null"
+          ],
+          "items": {
+            "type": "string"
+          }
+        },
+        "type": {
+          "$ref": "#/definitions/McpElicitationObjectType"
+        }
+      },
+      "additionalProperties": false
+    },
+    "McpElicitationSingleSelectEnumSchema": {
+      "anyOf": [
+        {
+          "$ref": "#/definitions/McpElicitationUntitledSingleSelectEnumSchema"
+        },
+        {
+          "$ref": "#/definitions/McpElicitationTitledSingleSelectEnumSchema"
+        }
+      ]
+    },
+    "McpElicitationStringFormat": {
+      "type": "string",
+      "enum": [
+        "email",
+        "uri",
+        "date",
+        "date-time"
+      ]
+    },
+    "McpElicitationStringSchema": {
+      "type": "object",
+      "required": [
+        "type"
+      ],
+      "properties": {
+        "default": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "description": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "format": {
+          "anyOf": [
+            {
+              "$ref": "#/definitions/McpElicitationStringFormat"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "maxLength": {
+          "type": [
+            "integer",
+            "null"
+          ],
+          "format": "uint32",
+          "minimum": 0.0
+        },
+        "minLength": {
+          "type": [
+            "integer",
+            "null"
+          ],
+          "format": "uint32",
+          "minimum": 0.0
+        },
+        "title": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "type": {
+          "$ref": "#/definitions/McpElicitationStringType"
+        }
+      },
+      "additionalProperties": false
+    },
+    "McpElicitationStringType": {
+      "type": "string",
+      "enum": [
+        "string"
+      ]
+    },
+    "McpElicitationTitledEnumItems": {
+      "type": "object",
+      "required": [
+        "anyOf"
+      ],
+      "properties": {
+        "anyOf": {
+          "type": "array",
+          "items": {
+            "$ref": "#/definitions/McpElicitationConstOption"
+          }
+        }
+      },
+      "additionalProperties": false
+    },
+    "McpElicitationTitledMultiSelectEnumSchema": {
+      "type": "object",
+      "required": [
+        "items",
+        "type"
+      ],
+      "properties": {
+        "default": {
+          "type": [
+            "array",
+            "null"
+          ],
+          "items": {
+            "type": "string"
+          }
+        },
+        "description": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "items": {
+          "$ref": "#/definitions/McpElicitationTitledEnumItems"
+        },
+        "maxItems": {
+          "type": [
+            "integer",
+            "null"
+          ],
+          "format": "uint64",
+          "minimum": 0.0
+        },
+        "minItems": {
+          "type": [
+            "integer",
+            "null"
+          ],
+          "format": "uint64",
+          "minimum": 0.0
+        },
+        "title": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "type": {
+          "$ref": "#/definitions/McpElicitationArrayType"
+        }
+      },
+      "additionalProperties": false
+    },
+    "McpElicitationTitledSingleSelectEnumSchema": {
+      "type": "object",
+      "required": [
+        "oneOf",
+        "type"
+      ],
+      "properties": {
+        "default": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "description": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "oneOf": {
+          "type": "array",
+          "items": {
+            "$ref": "#/definitions/McpElicitationConstOption"
+          }
+        },
+        "title": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "type": {
+          "$ref": "#/definitions/McpElicitationStringType"
+        }
+      },
+      "additionalProperties": false
+    },
+    "McpElicitationUntitledEnumItems": {
+      "type": "object",
+      "required": [
+        "enum",
+        "type"
+      ],
+      "properties": {
+        "enum": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "type": {
+          "$ref": "#/definitions/McpElicitationStringType"
+        }
+      },
+      "additionalProperties": false
+    },
+    "McpElicitationUntitledMultiSelectEnumSchema": {
+      "type": "object",
+      "required": [
+        "items",
+        "type"
+      ],
+      "properties": {
+        "default": {
+          "type": [
+            "array",
+            "null"
+          ],
+          "items": {
+            "type": "string"
+          }
+        },
+        "description": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "items": {
+          "$ref": "#/definitions/McpElicitationUntitledEnumItems"
+        },
+        "maxItems": {
+          "type": [
+            "integer",
+            "null"
+          ],
+          "format": "uint64",
+          "minimum": 0.0
+        },
+        "minItems": {
+          "type": [
+            "integer",
+            "null"
+          ],
+          "format": "uint64",
+          "minimum": 0.0
+        },
+        "title": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "type": {
+          "$ref": "#/definitions/McpElicitationArrayType"
+        }
+      },
+      "additionalProperties": false
+    },
+    "McpElicitationUntitledSingleSelectEnumSchema": {
+      "type": "object",
+      "required": [
+        "enum",
+        "type"
+      ],
+      "properties": {
+        "default": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "description": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "enum": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "title": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "type": {
+          "$ref": "#/definitions/McpElicitationStringType"
+        }
+      },
+      "additionalProperties": false
+    }
+  }
+}

schemas/McpServerElicitationRequestResponse.json

@@ -0,0 +1,29 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "McpServerElicitationRequestResponse",
+  "type": "object",
+  "required": [
+    "action"
+  ],
+  "properties": {
+    "_meta": {
+      "description": "Optional client metadata for form-mode action handling."
+    },
+    "action": {
+      "$ref": "#/definitions/McpServerElicitationAction"
+    },
+    "content": {
+      "description": "Structured user input for accepted elicitations, mirroring RMCP `CreateElicitationResult`.\n\nThis is nullable because decline/cancel responses have no content."
+    }
+  },
+  "definitions": {
+    "McpServerElicitationAction": {
+      "type": "string",
+      "enum": [
+        "accept",
+        "decline",
+        "cancel"
+      ]
+    }
+  }
+}

schemas/PermissionsRequestApprovalParams.json

@@ -0,0 +1,322 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "PermissionsRequestApprovalParams",
+  "type": "object",
+  "required": [
+    "cwd",
+    "itemId",
+    "permissions",
+    "startedAtMs",
+    "threadId",
+    "turnId"
+  ],
+  "properties": {
+    "cwd": {
+      "$ref": "#/definitions/AbsolutePathBuf"
+    },
+    "itemId": {
+      "type": "string"
+    },
+    "permissions": {
+      "$ref": "#/definitions/RequestPermissionProfile"
+    },
+    "reason": {
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "startedAtMs": {
+      "description": "Unix timestamp (in milliseconds) when this approval request started.",
+      "type": "integer",
+      "format": "int64"
+    },
+    "threadId": {
+      "type": "string"
+    },
+    "turnId": {
+      "type": "string"
+    }
+  },
+  "definitions": {
+    "AbsolutePathBuf": {
+      "description": "A path that is guaranteed to be absolute and normalized (though it is not guaranteed to be canonicalized or exist on the filesystem).\n\nIMPORTANT: When deserializing an `AbsolutePathBuf`, a base path must be set using [AbsolutePathBufGuard::new]. If no base path is set, the deserialization will fail unless the path being deserialized is already absolute.",
+      "type": "string"
+    },
+    "AdditionalFileSystemPermissions": {
+      "type": "object",
+      "properties": {
+        "entries": {
+          "type": [
+            "array",
+            "null"
+          ],
+          "items": {
+            "$ref": "#/definitions/FileSystemSandboxEntry"
+          }
+        },
+        "globScanMaxDepth": {
+          "type": [
+            "integer",
+            "null"
+          ],
+          "format": "uint",
+          "minimum": 1.0
+        },
+        "read": {
+          "description": "This will be removed in favor of `entries`.",
+          "type": [
+            "array",
+            "null"
+          ],
+          "items": {
+            "$ref": "#/definitions/AbsolutePathBuf"
+          }
+        },
+        "write": {
+          "description": "This will be removed in favor of `entries`.",
+          "type": [
+            "array",
+            "null"
+          ],
+          "items": {
+            "$ref": "#/definitions/AbsolutePathBuf"
+          }
+        }
+      }
+    },
+    "AdditionalNetworkPermissions": {
+      "type": "object",
+      "properties": {
+        "enabled": {
+          "type": [
+            "boolean",
+            "null"
+          ]
+        }
+      }
+    },
+    "FileSystemAccessMode": {
+      "type": "string",
+      "enum": [
+        "read",
+        "write",
+        "none"
+      ]
+    },
+    "FileSystemPath": {
+      "oneOf": [
+        {
+          "type": "object",
+          "required": [
+            "path",
+            "type"
+          ],
+          "properties": {
+            "path": {
+              "$ref": "#/definitions/AbsolutePathBuf"
+            },
+            "type": {
+              "type": "string",
+              "enum": [
+                "path"
+              ],
+              "title": "PathFileSystemPathType"
+            }
+          },
+          "title": "PathFileSystemPath"
+        },
+        {
+          "type": "object",
+          "required": [
+            "pattern",
+            "type"
+          ],
+          "properties": {
+            "pattern": {
+              "type": "string"
+            },
+            "type": {
+              "type": "string",
+              "enum": [
+                "glob_pattern"
+              ],
+              "title": "GlobPatternFileSystemPathType"
+            }
+          },
+          "title": "GlobPatternFileSystemPath"
+        },
+        {
+          "type": "object",
+          "required": [
+            "type",
+            "value"
+          ],
+          "properties": {
+            "type": {
+              "type": "string",
+              "enum": [
+                "special"
+              ],
+              "title": "SpecialFileSystemPathType"
+            },
+            "value": {
+              "$ref": "#/definitions/FileSystemSpecialPath"
+            }
+          },
+          "title": "SpecialFileSystemPath"
+        }
+      ]
+    },
+    "FileSystemSandboxEntry": {
+      "type": "object",
+      "required": [
+        "access",
+        "path"
+      ],
+      "properties": {
+        "access": {
+          "$ref": "#/definitions/FileSystemAccessMode"
+        },
+        "path": {
+          "$ref": "#/definitions/FileSystemPath"
+        }
+      }
+    },
+    "FileSystemSpecialPath": {
+      "oneOf": [
+        {
+          "type": "object",
+          "required": [
+            "kind"
+          ],
+          "properties": {
+            "kind": {
+              "type": "string",
+              "enum": [
+                "root"
+              ]
+            }
+          },
+          "title": "RootFileSystemSpecialPath"
+        },
+        {
+          "type": "object",
+          "required": [
+            "kind"
+          ],
+          "properties": {
+            "kind": {
+              "type": "string",
+              "enum": [
+                "minimal"
+              ]
+            }
+          },
+          "title": "MinimalFileSystemSpecialPath"
+        },
+        {
+          "type": "object",
+          "required": [
+            "kind"
+          ],
+          "properties": {
+            "kind": {
+              "type": "string",
+              "enum": [
+                "project_roots"
+              ]
+            },
+            "subpath": {
+              "type": [
+                "string",
+                "null"
+              ]
+            }
+          },
+          "title": "KindFileSystemSpecialPath"
+        },
+        {
+          "type": "object",
+          "required": [
+            "kind"
+          ],
+          "properties": {
+            "kind": {
+              "type": "string",
+              "enum": [
+                "tmpdir"
+              ]
+            }
+          },
+          "title": "TmpdirFileSystemSpecialPath"
+        },
+        {
+          "type": "object",
+          "required": [
+            "kind"
+          ],
+          "properties": {
+            "kind": {
+              "type": "string",
+              "enum": [
+                "slash_tmp"
+              ]
+            }
+          },
+          "title": "SlashTmpFileSystemSpecialPath"
+        },
+        {
+          "type": "object",
+          "required": [
+            "kind",
+            "path"
+          ],
+          "properties": {
+            "kind": {
+              "type": "string",
+              "enum": [
+                "unknown"
+              ]
+            },
+            "path": {
+              "type": "string"
+            },
+            "subpath": {
+              "type": [
+                "string",
+                "null"
+              ]
+            }
+          }
+        }
+      ]
+    },
+    "RequestPermissionProfile": {
+      "type": "object",
+      "properties": {
+        "fileSystem": {
+          "anyOf": [
+            {
+              "$ref": "#/definitions/AdditionalFileSystemPermissions"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "network": {
+          "anyOf": [
+            {
+              "$ref": "#/definitions/AdditionalNetworkPermissions"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        }
+      },
+      "additionalProperties": false
+    }
+  }
+}

schemas/PermissionsRequestApprovalResponse.json

@@ -0,0 +1,315 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "PermissionsRequestApprovalResponse",
+  "type": "object",
+  "required": [
+    "permissions"
+  ],
+  "properties": {
+    "permissions": {
+      "$ref": "#/definitions/GrantedPermissionProfile"
+    },
+    "scope": {
+      "default": "turn",
+      "allOf": [
+        {
+          "$ref": "#/definitions/PermissionGrantScope"
+        }
+      ]
+    },
+    "strictAutoReview": {
+      "description": "Review every subsequent command in this turn before normal sandboxed execution.",
+      "type": [
+        "boolean",
+        "null"
+      ]
+    }
+  },
+  "definitions": {
+    "AbsolutePathBuf": {
+      "description": "A path that is guaranteed to be absolute and normalized (though it is not guaranteed to be canonicalized or exist on the filesystem).\n\nIMPORTANT: When deserializing an `AbsolutePathBuf`, a base path must be set using [AbsolutePathBufGuard::new]. If no base path is set, the deserialization will fail unless the path being deserialized is already absolute.",
+      "type": "string"
+    },
+    "AdditionalFileSystemPermissions": {
+      "type": "object",
+      "properties": {
+        "entries": {
+          "type": [
+            "array",
+            "null"
+          ],
+          "items": {
+            "$ref": "#/definitions/FileSystemSandboxEntry"
+          }
+        },
+        "globScanMaxDepth": {
+          "type": [
+            "integer",
+            "null"
+          ],
+          "format": "uint",
+          "minimum": 1.0
+        },
+        "read": {
+          "description": "This will be removed in favor of `entries`.",
+          "type": [
+            "array",
+            "null"
+          ],
+          "items": {
+            "$ref": "#/definitions/AbsolutePathBuf"
+          }
+        },
+        "write": {
+          "description": "This will be removed in favor of `entries`.",
+          "type": [
+            "array",
+            "null"
+          ],
+          "items": {
+            "$ref": "#/definitions/AbsolutePathBuf"
+          }
+        }
+      }
+    },
+    "AdditionalNetworkPermissions": {
+      "type": "object",
+      "properties": {
+        "enabled": {
+          "type": [
+            "boolean",
+            "null"
+          ]
+        }
+      }
+    },
+    "FileSystemAccessMode": {
+      "type": "string",
+      "enum": [
+        "read",
+        "write",
+        "none"
+      ]
+    },
+    "FileSystemPath": {
+      "oneOf": [
+        {
+          "type": "object",
+          "required": [
+            "path",
+            "type"
+          ],
+          "properties": {
+            "path": {
+              "$ref": "#/definitions/AbsolutePathBuf"
+            },
+            "type": {
+              "type": "string",
+              "enum": [
+                "path"
+              ],
+              "title": "PathFileSystemPathType"
+            }
+          },
+          "title": "PathFileSystemPath"
+        },
+        {
+          "type": "object",
+          "required": [
+            "pattern",
+            "type"
+          ],
+          "properties": {
+            "pattern": {
+              "type": "string"
+            },
+            "type": {
+              "type": "string",
+              "enum": [
+                "glob_pattern"
+              ],
+              "title": "GlobPatternFileSystemPathType"
+            }
+          },
+          "title": "GlobPatternFileSystemPath"
+        },
+        {
+          "type": "object",
+          "required": [
+            "type",
+            "value"
+          ],
+          "properties": {
+            "type": {
+              "type": "string",
+              "enum": [
+                "special"
+              ],
+              "title": "SpecialFileSystemPathType"
+            },
+            "value": {
+              "$ref": "#/definitions/FileSystemSpecialPath"
+            }
+          },
+          "title": "SpecialFileSystemPath"
+        }
+      ]
+    },
+    "FileSystemSandboxEntry": {
+      "type": "object",
+      "required": [
+        "access",
+        "path"
+      ],
+      "properties": {
+        "access": {
+          "$ref": "#/definitions/FileSystemAccessMode"
+        },
+        "path": {
+          "$ref": "#/definitions/FileSystemPath"
+        }
+      }
+    },
+    "FileSystemSpecialPath": {
+      "oneOf": [
+        {
+          "type": "object",
+          "required": [
+            "kind"
+          ],
+          "properties": {
+            "kind": {
+              "type": "string",
+              "enum": [
+                "root"
+              ]
+            }
+          },
+          "title": "RootFileSystemSpecialPath"
+        },
+        {
+          "type": "object",
+          "required": [
+            "kind"
+          ],
+          "properties": {
+            "kind": {
+              "type": "string",
+              "enum": [
+                "minimal"
+              ]
+            }
+          },
+          "title": "MinimalFileSystemSpecialPath"
+        },
+        {
+          "type": "object",
+          "required": [
+            "kind"
+          ],
+          "properties": {
+            "kind": {
+              "type": "string",
+              "enum": [
+                "project_roots"
+              ]
+            },
+            "subpath": {
+              "type": [
+                "string",
+                "null"
+              ]
+            }
+          },
+          "title": "KindFileSystemSpecialPath"
+        },
+        {
+          "type": "object",
+          "required": [
+            "kind"
+          ],
+          "properties": {
+            "kind": {
+              "type": "string",
+              "enum": [
+                "tmpdir"
+              ]
+            }
+          },
+          "title": "TmpdirFileSystemSpecialPath"
+        },
+        {
+          "type": "object",
+          "required": [
+            "kind"
+          ],
+          "properties": {
+            "kind": {
+              "type": "string",
+              "enum": [
+                "slash_tmp"
+              ]
+            }
+          },
+          "title": "SlashTmpFileSystemSpecialPath"
+        },
+        {
+          "type": "object",
+          "required": [
+            "kind",
+            "path"
+          ],
+          "properties": {
+            "kind": {
+              "type": "string",
+              "enum": [
+                "unknown"
+              ]
+            },
+            "path": {
+              "type": "string"
+            },
+            "subpath": {
+              "type": [
+                "string",
+                "null"
+              ]
+            }
+          }
+        }
+      ]
+    },
+    "GrantedPermissionProfile": {
+      "type": "object",
+      "properties": {
+        "fileSystem": {
+          "anyOf": [
+            {
+              "$ref": "#/definitions/AdditionalFileSystemPermissions"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "network": {
+          "anyOf": [
+            {
+              "$ref": "#/definitions/AdditionalNetworkPermissions"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        }
+      }
+    },
+    "PermissionGrantScope": {
+      "type": "string",
+      "enum": [
+        "turn",
+        "session"
+      ]
+    }
+  }
+}

schemas/RequestId.json

@@ -0,0 +1,13 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "RequestId",
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "integer",
+      "format": "int64"
+    }
+  ]
+}

schemas/ToolRequestUserInputParams.json

@@ -0,0 +1,84 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "ToolRequestUserInputParams",
+  "description": "EXPERIMENTAL. Params sent with a request_user_input event.",
+  "type": "object",
+  "required": [
+    "itemId",
+    "questions",
+    "threadId",
+    "turnId"
+  ],
+  "properties": {
+    "itemId": {
+      "type": "string"
+    },
+    "questions": {
+      "type": "array",
+      "items": {
+        "$ref": "#/definitions/ToolRequestUserInputQuestion"
+      }
+    },
+    "threadId": {
+      "type": "string"
+    },
+    "turnId": {
+      "type": "string"
+    }
+  },
+  "definitions": {
+    "ToolRequestUserInputOption": {
+      "description": "EXPERIMENTAL. Defines a single selectable option for request_user_input.",
+      "type": "object",
+      "required": [
+        "description",
+        "label"
+      ],
+      "properties": {
+        "description": {
+          "type": "string"
+        },
+        "label": {
+          "type": "string"
+        }
+      }
+    },
+    "ToolRequestUserInputQuestion": {
+      "description": "EXPERIMENTAL. Represents one request_user_input question and its required options.",
+      "type": "object",
+      "required": [
+        "header",
+        "id",
+        "question"
+      ],
+      "properties": {
+        "header": {
+          "type": "string"
+        },
+        "id": {
+          "type": "string"
+        },
+        "isOther": {
+          "default": false,
+          "type": "boolean"
+        },
+        "isSecret": {
+          "default": false,
+          "type": "boolean"
+        },
+        "options": {
+          "type": [
+            "array",
+            "null"
+          ],
+          "items": {
+            "$ref": "#/definitions/ToolRequestUserInputOption"
+          }
+        },
+        "question": {
+          "type": "string"
+        }
+      }
+    }
+  }
+}

schemas/ToolRequestUserInputResponse.json

@@ -0,0 +1,34 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "ToolRequestUserInputResponse",
+  "description": "EXPERIMENTAL. Response payload mapping question ids to answers.",
+  "type": "object",
+  "required": [
+    "answers"
+  ],
+  "properties": {
+    "answers": {
+      "type": "object",
+      "additionalProperties": {
+        "$ref": "#/definitions/ToolRequestUserInputAnswer"
+      }
+    }
+  },
+  "definitions": {
+    "ToolRequestUserInputAnswer": {
+      "description": "EXPERIMENTAL. Captures a user's answer to a request_user_input question.",
+      "type": "object",
+      "required": [
+        "answers"
+      ],
+      "properties": {
+        "answers": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        }
+      }
+    }
+  }
+}

schemas/v1/InitializeParams.json

@@ -0,0 +1,72 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "InitializeParams",
+  "type": "object",
+  "required": [
+    "clientInfo"
+  ],
+  "properties": {
+    "capabilities": {
+      "anyOf": [
+        {
+          "$ref": "#/definitions/InitializeCapabilities"
+        },
+        {
+          "type": "null"
+        }
+      ]
+    },
+    "clientInfo": {
+      "$ref": "#/definitions/ClientInfo"
+    }
+  },
+  "definitions": {
+    "ClientInfo": {
+      "type": "object",
+      "required": [
+        "name",
+        "version"
+      ],
+      "properties": {
+        "name": {
+          "type": "string"
+        },
+        "title": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "version": {
+          "type": "string"
+        }
+      }
+    },
+    "InitializeCapabilities": {
+      "description": "Client-declared capabilities negotiated during initialize.",
+      "type": "object",
+      "properties": {
+        "experimentalApi": {
+          "description": "Opt into receiving experimental API methods and fields.",
+          "default": false,
+          "type": "boolean"
+        },
+        "optOutNotificationMethods": {
+          "description": "Exact notification method names that should be suppressed for this connection (for example `thread/started`).",
+          "type": [
+            "array",
+            "null"
+          ],
+          "items": {
+            "type": "string"
+          }
+        },
+        "requestAttestation": {
+          "description": "Opt into `attestation/generate` requests for upstream `x-oai-attestation`.",
+          "default": false,
+          "type": "boolean"
+        }
+      }
+    }
+  }
+}

schemas/v1/InitializeResponse.json

@@ -0,0 +1,38 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "InitializeResponse",
+  "type": "object",
+  "required": [
+    "codexHome",
+    "platformFamily",
+    "platformOs",
+    "userAgent"
+  ],
+  "properties": {
+    "codexHome": {
+      "description": "Absolute path to the server's $CODEX_HOME directory.",
+      "allOf": [
+        {
+          "$ref": "#/definitions/AbsolutePathBuf"
+        }
+      ]
+    },
+    "platformFamily": {
+      "description": "Platform family for the running app-server target, for example `\"unix\"` or `\"windows\"`.",
+      "type": "string"
+    },
+    "platformOs": {
+      "description": "Operating system for the running app-server target, for example `\"macos\"`, `\"linux\"`, or `\"windows\"`.",
+      "type": "string"
+    },
+    "userAgent": {
+      "type": "string"
+    }
+  },
+  "definitions": {
+    "AbsolutePathBuf": {
+      "description": "A path that is guaranteed to be absolute and normalized (though it is not guaranteed to be canonicalized or exist on the filesystem).\n\nIMPORTANT: When deserializing an `AbsolutePathBuf`, a base path must be set using [AbsolutePathBufGuard::new]. If no base path is set, the deserialization will fail unless the path being deserialized is already absolute.",
+      "type": "string"
+    }
+  }
+}

schemas/v2/AccountLoginCompletedNotification.json

@@ -0,0 +1,25 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "AccountLoginCompletedNotification",
+  "type": "object",
+  "required": [
+    "success"
+  ],
+  "properties": {
+    "error": {
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "loginId": {
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "success": {
+      "type": "boolean"
+    }
+  }
+}

schemas/v2/AccountRateLimitsUpdatedNotification.json

@@ -0,0 +1,156 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "AccountRateLimitsUpdatedNotification",
+  "type": "object",
+  "required": [
+    "rateLimits"
+  ],
+  "properties": {
+    "rateLimits": {
+      "$ref": "#/definitions/RateLimitSnapshot"
+    }
+  },
+  "definitions": {
+    "CreditsSnapshot": {
+      "type": "object",
+      "required": [
+        "hasCredits",
+        "unlimited"
+      ],
+      "properties": {
+        "balance": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "hasCredits": {
+          "type": "boolean"
+        },
+        "unlimited": {
+          "type": "boolean"
+        }
+      }
+    },
+    "PlanType": {
+      "type": "string",
+      "enum": [
+        "free",
+        "go",
+        "plus",
+        "pro",
+        "prolite",
+        "team",
+        "self_serve_business_usage_based",
+        "business",
+        "enterprise_cbp_usage_based",
+        "enterprise",
+        "edu",
+        "unknown"
+      ]
+    },
+    "RateLimitReachedType": {
+      "type": "string",
+      "enum": [
+        "rate_limit_reached",
+        "workspace_owner_credits_depleted",
+        "workspace_member_credits_depleted",
+        "workspace_owner_usage_limit_reached",
+        "workspace_member_usage_limit_reached"
+      ]
+    },
+    "RateLimitSnapshot": {
+      "type": "object",
+      "properties": {
+        "credits": {
+          "anyOf": [
+            {
+              "$ref": "#/definitions/CreditsSnapshot"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "limitId": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "limitName": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "planType": {
+          "anyOf": [
+            {
+              "$ref": "#/definitions/PlanType"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "primary": {
+          "anyOf": [
+            {
+              "$ref": "#/definitions/RateLimitWindow"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "rateLimitReachedType": {
+          "anyOf": [
+            {
+              "$ref": "#/definitions/RateLimitReachedType"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "secondary": {
+          "anyOf": [
+            {
+              "$ref": "#/definitions/RateLimitWindow"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        }
+      }
+    },
+    "RateLimitWindow": {
+      "type": "object",
+      "required": [
+        "usedPercent"
+      ],
+      "properties": {
+        "resetsAt": {
+          "type": [
+            "integer",
+            "null"
+          ],
+          "format": "int64"
+        },
+        "usedPercent": {
+          "type": "integer",
+          "format": "int32"
+        },
+        "windowDurationMins": {
+          "type": [
+            "integer",
+            "null"
+          ],
+          "format": "int64"
+        }
+      }
+    }
+  }
+}

schemas/v2/AccountUpdatedNotification.json

@@ -0,0 +1,79 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "AccountUpdatedNotification",
+  "type": "object",
+  "properties": {
+    "authMode": {
+      "anyOf": [
+        {
+          "$ref": "#/definitions/AuthMode"
+        },
+        {
+          "type": "null"
+        }
+      ]
+    },
+    "planType": {
+      "anyOf": [
+        {
+          "$ref": "#/definitions/PlanType"
+        },
+        {
+          "type": "null"
+        }
+      ]
+    }
+  },
+  "definitions": {
+    "AuthMode": {
+      "description": "Authentication mode for OpenAI-backed providers.",
+      "oneOf": [
+        {
+          "description": "OpenAI API key provided by the caller and stored by Codex.",
+          "type": "string",
+          "enum": [
+            "apikey"
+          ]
+        },
+        {
+          "description": "ChatGPT OAuth managed by Codex (tokens persisted and refreshed by Codex).",
+          "type": "string",
+          "enum": [
+            "chatgpt"
+          ]
+        },
+        {
+          "description": "[UNSTABLE] FOR OPENAI INTERNAL USE ONLY - DO NOT USE.\n\nChatGPT auth tokens are supplied by an external host app and are only stored in memory. Token refresh must be handled by the external host app.",
+          "type": "string",
+          "enum": [
+            "chatgptAuthTokens"
+          ]
+        },
+        {
+          "description": "Programmatic Codex auth backed by a registered Agent Identity.",
+          "type": "string",
+          "enum": [
+            "agentIdentity"
+          ]
+        }
+      ]
+    },
+    "PlanType": {
+      "type": "string",
+      "enum": [
+        "free",
+        "go",
+        "plus",
+        "pro",
+        "prolite",
+        "team",
+        "self_serve_business_usage_based",
+        "business",
+        "enterprise_cbp_usage_based",
+        "enterprise",
+        "edu",
+        "unknown"
+      ]
+    }
+  }
+}

schemas/v2/AgentMessageDeltaNotification.json

@@ -0,0 +1,25 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "AgentMessageDeltaNotification",
+  "type": "object",
+  "required": [
+    "delta",
+    "itemId",
+    "threadId",
+    "turnId"
+  ],
+  "properties": {
+    "delta": {
+      "type": "string"
+    },
+    "itemId": {
+      "type": "string"
+    },
+    "threadId": {
+      "type": "string"
+    },
+    "turnId": {
+      "type": "string"
+    }
+  }
+}

schemas/v2/AppListUpdatedNotification.json

@@ -0,0 +1,276 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "AppListUpdatedNotification",
+  "description": "EXPERIMENTAL - notification emitted when the app list changes.",
+  "type": "object",
+  "required": [
+    "data"
+  ],
+  "properties": {
+    "data": {
+      "type": "array",
+      "items": {
+        "$ref": "#/definitions/AppInfo"
+      }
+    }
+  },
+  "definitions": {
+    "AppBranding": {
+      "description": "EXPERIMENTAL - app metadata returned by app-list APIs.",
+      "type": "object",
+      "required": [
+        "isDiscoverableApp"
+      ],
+      "properties": {
+        "category": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "developer": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "isDiscoverableApp": {
+          "type": "boolean"
+        },
+        "privacyPolicy": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "termsOfService": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "website": {
+          "type": [
+            "string",
+            "null"
+          ]
+        }
+      }
+    },
+    "AppInfo": {
+      "description": "EXPERIMENTAL - app metadata returned by app-list APIs.",
+      "type": "object",
+      "required": [
+        "id",
+        "name"
+      ],
+      "properties": {
+        "appMetadata": {
+          "anyOf": [
+            {
+              "$ref": "#/definitions/AppMetadata"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "branding": {
+          "anyOf": [
+            {
+              "$ref": "#/definitions/AppBranding"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "description": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "distributionChannel": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "id": {
+          "type": "string"
+        },
+        "installUrl": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "isAccessible": {
+          "default": false,
+          "type": "boolean"
+        },
+        "isEnabled": {
+          "description": "Whether this app is enabled in config.toml. Example: ```toml [apps.bad_app] enabled = false ```",
+          "default": true,
+          "type": "boolean"
+        },
+        "labels": {
+          "type": [
+            "object",
+            "null"
+          ],
+          "additionalProperties": {
+            "type": "string"
+          }
+        },
+        "logoUrl": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "logoUrlDark": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "name": {
+          "type": "string"
+        },
+        "pluginDisplayNames": {
+          "default": [],
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        }
+      }
+    },
+    "AppMetadata": {
+      "type": "object",
+      "properties": {
+        "categories": {
+          "type": [
+            "array",
+            "null"
+          ],
+          "items": {
+            "type": "string"
+          }
+        },
+        "developer": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "firstPartyRequiresInstall": {
+          "type": [
+            "boolean",
+            "null"
+          ]
+        },
+        "firstPartyType": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "review": {
+          "anyOf": [
+            {
+              "$ref": "#/definitions/AppReview"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "screenshots": {
+          "type": [
+            "array",
+            "null"
+          ],
+          "items": {
+            "$ref": "#/definitions/AppScreenshot"
+          }
+        },
+        "seoDescription": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "showInComposerWhenUnlinked": {
+          "type": [
+            "boolean",
+            "null"
+          ]
+        },
+        "subCategories": {
+          "type": [
+            "array",
+            "null"
+          ],
+          "items": {
+            "type": "string"
+          }
+        },
+        "version": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "versionId": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "versionNotes": {
+          "type": [
+            "string",
+            "null"
+          ]
+        }
+      }
+    },
+    "AppReview": {
+      "type": "object",
+      "required": [
+        "status"
+      ],
+      "properties": {
+        "status": {
+          "type": "string"
+        }
+      }
+    },
+    "AppScreenshot": {
+      "type": "object",
+      "required": [
+        "userPrompt"
+      ],
+      "properties": {
+        "fileId": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "url": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "userPrompt": {
+          "type": "string"
+        }
+      }
+    }
+  }
+}

schemas/v2/AppsListParams.json

@@ -0,0 +1,35 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "AppsListParams",
+  "description": "EXPERIMENTAL - list available apps/connectors.",
+  "type": "object",
+  "properties": {
+    "cursor": {
+      "description": "Opaque pagination cursor returned by a previous call.",
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "forceRefetch": {
+      "description": "When true, bypass app caches and fetch the latest data from sources.",
+      "type": "boolean"
+    },
+    "limit": {
+      "description": "Optional page size; defaults to a reasonable server-side value.",
+      "type": [
+        "integer",
+        "null"
+      ],
+      "format": "uint32",
+      "minimum": 0.0
+    },
+    "threadId": {
+      "description": "Optional thread id used to evaluate app feature gating from that thread's config.",
+      "type": [
+        "string",
+        "null"
+      ]
+    }
+  }
+}

schemas/v2/AppsListResponse.json

@@ -0,0 +1,283 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "AppsListResponse",
+  "description": "EXPERIMENTAL - app list response.",
+  "type": "object",
+  "required": [
+    "data"
+  ],
+  "properties": {
+    "data": {
+      "type": "array",
+      "items": {
+        "$ref": "#/definitions/AppInfo"
+      }
+    },
+    "nextCursor": {
+      "description": "Opaque cursor to pass to the next call to continue after the last item. If None, there are no more items to return.",
+      "type": [
+        "string",
+        "null"
+      ]
+    }
+  },
+  "definitions": {
+    "AppBranding": {
+      "description": "EXPERIMENTAL - app metadata returned by app-list APIs.",
+      "type": "object",
+      "required": [
+        "isDiscoverableApp"
+      ],
+      "properties": {
+        "category": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "developer": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "isDiscoverableApp": {
+          "type": "boolean"
+        },
+        "privacyPolicy": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "termsOfService": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "website": {
+          "type": [
+            "string",
+            "null"
+          ]
+        }
+      }
+    },
+    "AppInfo": {
+      "description": "EXPERIMENTAL - app metadata returned by app-list APIs.",
+      "type": "object",
+      "required": [
+        "id",
+        "name"
+      ],
+      "properties": {
+        "appMetadata": {
+          "anyOf": [
+            {
+              "$ref": "#/definitions/AppMetadata"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "branding": {
+          "anyOf": [
+            {
+              "$ref": "#/definitions/AppBranding"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "description": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "distributionChannel": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "id": {
+          "type": "string"
+        },
+        "installUrl": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "isAccessible": {
+          "default": false,
+          "type": "boolean"
+        },
+        "isEnabled": {
+          "description": "Whether this app is enabled in config.toml. Example: ```toml [apps.bad_app] enabled = false ```",
+          "default": true,
+          "type": "boolean"
+        },
+        "labels": {
+          "type": [
+            "object",
+            "null"
+          ],
+          "additionalProperties": {
+            "type": "string"
+          }
+        },
+        "logoUrl": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "logoUrlDark": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "name": {
+          "type": "string"
+        },
+        "pluginDisplayNames": {
+          "default": [],
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        }
+      }
+    },
+    "AppMetadata": {
+      "type": "object",
+      "properties": {
+        "categories": {
+          "type": [
+            "array",
+            "null"
+          ],
+          "items": {
+            "type": "string"
+          }
+        },
+        "developer": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "firstPartyRequiresInstall": {
+          "type": [
+            "boolean",
+            "null"
+          ]
+        },
+        "firstPartyType": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "review": {
+          "anyOf": [
+            {
+              "$ref": "#/definitions/AppReview"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "screenshots": {
+          "type": [
+            "array",
+            "null"
+          ],
+          "items": {
+            "$ref": "#/definitions/AppScreenshot"
+          }
+        },
+        "seoDescription": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "showInComposerWhenUnlinked": {
+          "type": [
+            "boolean",
+            "null"
+          ]
+        },
+        "subCategories": {
+          "type": [
+            "array",
+            "null"
+          ],
+          "items": {
+            "type": "string"
+          }
+        },
+        "version": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "versionId": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "versionNotes": {
+          "type": [
+            "string",
+            "null"
+          ]
+        }
+      }
+    },
+    "AppReview": {
+      "type": "object",
+      "required": [
+        "status"
+      ],
+      "properties": {
+        "status": {
+          "type": "string"
+        }
+      }
+    },
+    "AppScreenshot": {
+      "type": "object",
+      "required": [
+        "userPrompt"
+      ],
+      "properties": {
+        "fileId": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "url": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "userPrompt": {
+          "type": "string"
+        }
+      }
+    }
+  }
+}

schemas/v2/CancelLoginAccountParams.json

@@ -0,0 +1,13 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "CancelLoginAccountParams",
+  "type": "object",
+  "required": [
+    "loginId"
+  ],
+  "properties": {
+    "loginId": {
+      "type": "string"
+    }
+  }
+}

schemas/v2/CancelLoginAccountResponse.json

@@ -0,0 +1,22 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "CancelLoginAccountResponse",
+  "type": "object",
+  "required": [
+    "status"
+  ],
+  "properties": {
+    "status": {
+      "$ref": "#/definitions/CancelLoginAccountStatus"
+    }
+  },
+  "definitions": {
+    "CancelLoginAccountStatus": {
+      "type": "string",
+      "enum": [
+        "canceled",
+        "notFound"
+      ]
+    }
+  }
+}

schemas/v2/CommandExecOutputDeltaNotification.json

@@ -0,0 +1,55 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "CommandExecOutputDeltaNotification",
+  "description": "Base64-encoded output chunk emitted for a streaming `command/exec` request.\n\nThese notifications are connection-scoped. If the originating connection closes, the server terminates the process.",
+  "type": "object",
+  "required": [
+    "capReached",
+    "deltaBase64",
+    "processId",
+    "stream"
+  ],
+  "properties": {
+    "capReached": {
+      "description": "`true` on the final streamed chunk for a stream when `outputBytesCap` truncated later output on that stream.",
+      "type": "boolean"
+    },
+    "deltaBase64": {
+      "description": "Base64-encoded output bytes.",
+      "type": "string"
+    },
+    "processId": {
+      "description": "Client-supplied, connection-scoped `processId` from the original `command/exec` request.",
+      "type": "string"
+    },
+    "stream": {
+      "description": "Output stream for this chunk.",
+      "allOf": [
+        {
+          "$ref": "#/definitions/CommandExecOutputStream"
+        }
+      ]
+    }
+  },
+  "definitions": {
+    "CommandExecOutputStream": {
+      "description": "Stream label for `command/exec/outputDelta` notifications.",
+      "oneOf": [
+        {
+          "description": "stdout stream. PTY mode multiplexes terminal output here.",
+          "type": "string",
+          "enum": [
+            "stdout"
+          ]
+        },
+        {
+          "description": "stderr stream.",
+          "type": "string",
+          "enum": [
+            "stderr"
+          ]
+        }
+      ]
+    }
+  }
+}

schemas/v2/CommandExecParams.json

@@ -0,0 +1,258 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "CommandExecParams",
+  "description": "Run a standalone command (argv vector) in the server sandbox without creating a thread or turn.\n\nThe final `command/exec` response is deferred until the process exits and is sent only after all `command/exec/outputDelta` notifications for that connection have been emitted.",
+  "type": "object",
+  "required": [
+    "command"
+  ],
+  "properties": {
+    "command": {
+      "description": "Command argv vector. Empty arrays are rejected.",
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    },
+    "cwd": {
+      "description": "Optional working directory. Defaults to the server cwd.",
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "disableOutputCap": {
+      "description": "Disable stdout/stderr capture truncation for this request.\n\nCannot be combined with `outputBytesCap`.",
+      "type": "boolean"
+    },
+    "disableTimeout": {
+      "description": "Disable the timeout entirely for this request.\n\nCannot be combined with `timeoutMs`.",
+      "type": "boolean"
+    },
+    "env": {
+      "description": "Optional environment overrides merged into the server-computed environment.\n\nMatching names override inherited values. Set a key to `null` to unset an inherited variable.",
+      "type": [
+        "object",
+        "null"
+      ],
+      "additionalProperties": {
+        "type": [
+          "string",
+          "null"
+        ]
+      }
+    },
+    "outputBytesCap": {
+      "description": "Optional per-stream stdout/stderr capture cap in bytes.\n\nWhen omitted, the server default applies. Cannot be combined with `disableOutputCap`.",
+      "type": [
+        "integer",
+        "null"
+      ],
+      "format": "uint",
+      "minimum": 0.0
+    },
+    "tty": {
+      "description": "Enable PTY mode.\n\nThis implies `streamStdin` and `streamStdoutStderr`.",
+      "type": "boolean"
+    },
+    "processId": {
+      "description": "Optional client-supplied, connection-scoped process id.\n\nRequired for `tty`, `streamStdin`, `streamStdoutStderr`, and follow-up `command/exec/write`, `command/exec/resize`, and `command/exec/terminate` calls. When omitted, buffered execution gets an internal id that is not exposed to the client.",
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "sandboxPolicy": {
+      "description": "Optional sandbox policy for this command.\n\nUses the same shape as thread/turn execution sandbox configuration and defaults to the user's configured policy when omitted. Cannot be combined with `permissionProfile`.",
+      "anyOf": [
+        {
+          "$ref": "#/definitions/SandboxPolicy"
+        },
+        {
+          "type": "null"
+        }
+      ]
+    },
+    "size": {
+      "description": "Optional initial PTY size in character cells. Only valid when `tty` is true.",
+      "anyOf": [
+        {
+          "$ref": "#/definitions/CommandExecTerminalSize"
+        },
+        {
+          "type": "null"
+        }
+      ]
+    },
+    "streamStdin": {
+      "description": "Allow follow-up `command/exec/write` requests to write stdin bytes.\n\nRequires a client-supplied `processId`.",
+      "type": "boolean"
+    },
+    "streamStdoutStderr": {
+      "description": "Stream stdout/stderr via `command/exec/outputDelta` notifications.\n\nStreamed bytes are not duplicated into the final response and require a client-supplied `processId`.",
+      "type": "boolean"
+    },
+    "timeoutMs": {
+      "description": "Optional timeout in milliseconds.\n\nWhen omitted, the server default applies. Cannot be combined with `disableTimeout`.",
+      "type": [
+        "integer",
+        "null"
+      ],
+      "format": "int64"
+    }
+  },
+  "definitions": {
+    "AbsolutePathBuf": {
+      "description": "A path that is guaranteed to be absolute and normalized (though it is not guaranteed to be canonicalized or exist on the filesystem).\n\nIMPORTANT: When deserializing an `AbsolutePathBuf`, a base path must be set using [AbsolutePathBufGuard::new]. If no base path is set, the deserialization will fail unless the path being deserialized is already absolute.",
+      "type": "string"
+    },
+    "ActivePermissionProfile": {
+      "type": "object",
+      "required": [
+        "id"
+      ],
+      "properties": {
+        "extends": {
+          "description": "Parent profile identifier once permissions profiles support inheritance. This is currently always `null`.",
+          "default": null,
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "id": {
+          "description": "Identifier from `default_permissions` or the implicit built-in default, such as `:workspace` or a user-defined `[permissions.<id>]` profile.",
+          "type": "string"
+        }
+      }
+    },
+    "CommandExecTerminalSize": {
+      "description": "PTY size in character cells for `command/exec` PTY sessions.",
+      "type": "object",
+      "required": [
+        "cols",
+        "rows"
+      ],
+      "properties": {
+        "cols": {
+          "description": "Terminal width in character cells.",
+          "type": "integer",
+          "format": "uint16",
+          "minimum": 0.0
+        },
+        "rows": {
+          "description": "Terminal height in character cells.",
+          "type": "integer",
+          "format": "uint16",
+          "minimum": 0.0
+        }
+      }
+    },
+    "NetworkAccess": {
+      "type": "string",
+      "enum": [
+        "restricted",
+        "enabled"
+      ]
+    },
+    "SandboxPolicy": {
+      "oneOf": [
+        {
+          "type": "object",
+          "required": [
+            "type"
+          ],
+          "properties": {
+            "type": {
+              "type": "string",
+              "enum": [
+                "dangerFullAccess"
+              ],
+              "title": "DangerFullAccessSandboxPolicyType"
+            }
+          },
+          "title": "DangerFullAccessSandboxPolicy"
+        },
+        {
+          "type": "object",
+          "required": [
+            "type"
+          ],
+          "properties": {
+            "networkAccess": {
+              "default": false,
+              "type": "boolean"
+            },
+            "type": {
+              "type": "string",
+              "enum": [
+                "readOnly"
+              ],
+              "title": "ReadOnlySandboxPolicyType"
+            }
+          },
+          "title": "ReadOnlySandboxPolicy"
+        },
+        {
+          "type": "object",
+          "required": [
+            "type"
+          ],
+          "properties": {
+            "networkAccess": {
+              "default": "restricted",
+              "allOf": [
+                {
+                  "$ref": "#/definitions/NetworkAccess"
+                }
+              ]
+            },
+            "type": {
+              "type": "string",
+              "enum": [
+                "externalSandbox"
+              ],
+              "title": "ExternalSandboxSandboxPolicyType"
+            }
+          },
+          "title": "ExternalSandboxSandboxPolicy"
+        },
+        {
+          "type": "object",
+          "required": [
+            "type"
+          ],
+          "properties": {
+            "excludeSlashTmp": {
+              "default": false,
+              "type": "boolean"
+            },
+            "excludeTmpdirEnvVar": {
+              "default": false,
+              "type": "boolean"
+            },
+            "networkAccess": {
+              "default": false,
+              "type": "boolean"
+            },
+            "type": {
+              "type": "string",
+              "enum": [
+                "workspaceWrite"
+              ],
+              "title": "WorkspaceWriteSandboxPolicyType"
+            },
+            "writableRoots": {
+              "default": [],
+              "type": "array",
+              "items": {
+                "$ref": "#/definitions/AbsolutePathBuf"
+              }
+            }
+          },
+          "title": "WorkspaceWriteSandboxPolicy"
+        }
+      ]
+    }
+  }
+}

schemas/v2/CommandExecResizeParams.json

@@ -0,0 +1,48 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "CommandExecResizeParams",
+  "description": "Resize a running PTY-backed `command/exec` session.",
+  "type": "object",
+  "required": [
+    "processId",
+    "size"
+  ],
+  "properties": {
+    "processId": {
+      "description": "Client-supplied, connection-scoped `processId` from the original `command/exec` request.",
+      "type": "string"
+    },
+    "size": {
+      "description": "New PTY size in character cells.",
+      "allOf": [
+        {
+          "$ref": "#/definitions/CommandExecTerminalSize"
+        }
+      ]
+    }
+  },
+  "definitions": {
+    "CommandExecTerminalSize": {
+      "description": "PTY size in character cells for `command/exec` PTY sessions.",
+      "type": "object",
+      "required": [
+        "cols",
+        "rows"
+      ],
+      "properties": {
+        "cols": {
+          "description": "Terminal width in character cells.",
+          "type": "integer",
+          "format": "uint16",
+          "minimum": 0.0
+        },
+        "rows": {
+          "description": "Terminal height in character cells.",
+          "type": "integer",
+          "format": "uint16",
+          "minimum": 0.0
+        }
+      }
+    }
+  }
+}

schemas/v2/CommandExecResizeResponse.json

@@ -0,0 +1,6 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "CommandExecResizeResponse",
+  "description": "Empty success response for `command/exec/resize`.",
+  "type": "object"
+}

schemas/v2/CommandExecResponse.json

@@ -0,0 +1,26 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "CommandExecResponse",
+  "description": "Final buffered result for `command/exec`.",
+  "type": "object",
+  "required": [
+    "exitCode",
+    "stderr",
+    "stdout"
+  ],
+  "properties": {
+    "exitCode": {
+      "description": "Process exit code.",
+      "type": "integer",
+      "format": "int32"
+    },
+    "stderr": {
+      "description": "Buffered stderr capture.\n\nEmpty when stderr was streamed via `command/exec/outputDelta`.",
+      "type": "string"
+    },
+    "stdout": {
+      "description": "Buffered stdout capture.\n\nEmpty when stdout was streamed via `command/exec/outputDelta`.",
+      "type": "string"
+    }
+  }
+}

schemas/v2/CommandExecTerminateParams.json

@@ -0,0 +1,15 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "CommandExecTerminateParams",
+  "description": "Terminate a running `command/exec` session.",
+  "type": "object",
+  "required": [
+    "processId"
+  ],
+  "properties": {
+    "processId": {
+      "description": "Client-supplied, connection-scoped `processId` from the original `command/exec` request.",
+      "type": "string"
+    }
+  }
+}

schemas/v2/CommandExecTerminateResponse.json

@@ -0,0 +1,6 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "CommandExecTerminateResponse",
+  "description": "Empty success response for `command/exec/terminate`.",
+  "type": "object"
+}

schemas/v2/CommandExecWriteParams.json

@@ -0,0 +1,26 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "CommandExecWriteParams",
+  "description": "Write stdin bytes to a running `command/exec` session, close stdin, or both.",
+  "type": "object",
+  "required": [
+    "processId"
+  ],
+  "properties": {
+    "closeStdin": {
+      "description": "Close stdin after writing `deltaBase64`, if present.",
+      "type": "boolean"
+    },
+    "deltaBase64": {
+      "description": "Optional base64-encoded stdin bytes to write.",
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "processId": {
+      "description": "Client-supplied, connection-scoped `processId` from the original `command/exec` request.",
+      "type": "string"
+    }
+  }
+}

schemas/v2/CommandExecWriteResponse.json

@@ -0,0 +1,6 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "CommandExecWriteResponse",
+  "description": "Empty success response for `command/exec/write`.",
+  "type": "object"
+}

schemas/v2/CommandExecutionOutputDeltaNotification.json

@@ -0,0 +1,25 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "CommandExecutionOutputDeltaNotification",
+  "type": "object",
+  "required": [
+    "delta",
+    "itemId",
+    "threadId",
+    "turnId"
+  ],
+  "properties": {
+    "delta": {
+      "type": "string"
+    },
+    "itemId": {
+      "type": "string"
+    },
+    "threadId": {
+      "type": "string"
+    },
+    "turnId": {
+      "type": "string"
+    }
+  }
+}

schemas/v2/ConfigBatchWriteParams.json

@@ -0,0 +1,59 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "ConfigBatchWriteParams",
+  "type": "object",
+  "required": [
+    "edits"
+  ],
+  "properties": {
+    "edits": {
+      "type": "array",
+      "items": {
+        "$ref": "#/definitions/ConfigEdit"
+      }
+    },
+    "expectedVersion": {
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "filePath": {
+      "description": "Path to the config file to write; defaults to the user's `config.toml` when omitted.",
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "reloadUserConfig": {
+      "description": "When true, hot-reload the updated user config into all loaded threads after writing.",
+      "type": "boolean"
+    }
+  },
+  "definitions": {
+    "ConfigEdit": {
+      "type": "object",
+      "required": [
+        "keyPath",
+        "mergeStrategy",
+        "value"
+      ],
+      "properties": {
+        "keyPath": {
+          "type": "string"
+        },
+        "mergeStrategy": {
+          "$ref": "#/definitions/MergeStrategy"
+        },
+        "value": true
+      }
+    },
+    "MergeStrategy": {
+      "type": "string",
+      "enum": [
+        "replace",
+        "upsert"
+      ]
+    }
+  }
+}

schemas/v2/ConfigReadParams.json

@@ -0,0 +1,18 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "ConfigReadParams",
+  "type": "object",
+  "properties": {
+    "cwd": {
+      "description": "Optional working directory to resolve project config layers. If specified, return the effective config as seen from that directory (i.e., including any project layers between `cwd` and the project/repo root).",
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "includeLayers": {
+      "default": false,
+      "type": "boolean"
+    }
+  }
+}

schemas/v2/ConfigReadResponse.json

@@ -0,0 +1,913 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "ConfigReadResponse",
+  "type": "object",
+  "required": [
+    "config",
+    "origins"
+  ],
+  "properties": {
+    "config": {
+      "$ref": "#/definitions/Config"
+    },
+    "layers": {
+      "type": [
+        "array",
+        "null"
+      ],
+      "items": {
+        "$ref": "#/definitions/ConfigLayer"
+      }
+    },
+    "origins": {
+      "type": "object",
+      "additionalProperties": {
+        "$ref": "#/definitions/ConfigLayerMetadata"
+      }
+    }
+  },
+  "definitions": {
+    "AbsolutePathBuf": {
+      "description": "A path that is guaranteed to be absolute and normalized (though it is not guaranteed to be canonicalized or exist on the filesystem).\n\nIMPORTANT: When deserializing an `AbsolutePathBuf`, a base path must be set using [AbsolutePathBufGuard::new]. If no base path is set, the deserialization will fail unless the path being deserialized is already absolute.",
+      "type": "string"
+    },
+    "AnalyticsConfig": {
+      "type": "object",
+      "properties": {
+        "enabled": {
+          "type": [
+            "boolean",
+            "null"
+          ]
+        }
+      },
+      "additionalProperties": true
+    },
+    "AppConfig": {
+      "type": "object",
+      "properties": {
+        "default_tools_approval_mode": {
+          "anyOf": [
+            {
+              "$ref": "#/definitions/AppToolApproval"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "default_tools_enabled": {
+          "type": [
+            "boolean",
+            "null"
+          ]
+        },
+        "destructive_enabled": {
+          "type": [
+            "boolean",
+            "null"
+          ]
+        },
+        "enabled": {
+          "default": true,
+          "type": "boolean"
+        },
+        "open_world_enabled": {
+          "type": [
+            "boolean",
+            "null"
+          ]
+        },
+        "tools": {
+          "anyOf": [
+            {
+              "$ref": "#/definitions/AppToolsConfig"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        }
+      }
+    },
+    "AppToolApproval": {
+      "type": "string",
+      "enum": [
+        "auto",
+        "prompt",
+        "approve"
+      ]
+    },
+    "AppToolConfig": {
+      "type": "object",
+      "properties": {
+        "approval_mode": {
+          "anyOf": [
+            {
+              "$ref": "#/definitions/AppToolApproval"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "enabled": {
+          "type": [
+            "boolean",
+            "null"
+          ]
+        }
+      }
+    },
+    "AppToolsConfig": {
+      "type": "object"
+    },
+    "ApprovalsReviewer": {
+      "description": "Configures who approval requests are routed to for review. Examples include sandbox escapes, blocked network access, MCP approval prompts, and ARC escalations. Defaults to `user`. `auto_review` uses a carefully prompted subagent to gather relevant context and apply a risk-based decision framework before approving or denying the request. The legacy value `guardian_subagent` is accepted for compatibility.",
+      "type": "string",
+      "enum": [
+        "user",
+        "auto_review",
+        "guardian_subagent"
+      ]
+    },
+    "AppsConfig": {
+      "type": "object",
+      "properties": {
+        "_default": {
+          "default": null,
+          "anyOf": [
+            {
+              "$ref": "#/definitions/AppsDefaultConfig"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        }
+      }
+    },
+    "AppsDefaultConfig": {
+      "type": "object",
+      "properties": {
+        "destructive_enabled": {
+          "default": true,
+          "type": "boolean"
+        },
+        "enabled": {
+          "default": true,
+          "type": "boolean"
+        },
+        "open_world_enabled": {
+          "default": true,
+          "type": "boolean"
+        }
+      }
+    },
+    "AskForApproval": {
+      "oneOf": [
+        {
+          "type": "string",
+          "enum": [
+            "untrusted",
+            "on-failure",
+            "on-request",
+            "never"
+          ]
+        },
+        {
+          "type": "object",
+          "required": [
+            "granular"
+          ],
+          "properties": {
+            "granular": {
+              "type": "object",
+              "required": [
+                "mcp_elicitations",
+                "rules",
+                "sandbox_approval"
+              ],
+              "properties": {
+                "mcp_elicitations": {
+                  "type": "boolean"
+                },
+                "request_permissions": {
+                  "default": false,
+                  "type": "boolean"
+                },
+                "rules": {
+                  "type": "boolean"
+                },
+                "sandbox_approval": {
+                  "type": "boolean"
+                },
+                "skill_approval": {
+                  "default": false,
+                  "type": "boolean"
+                }
+              }
+            }
+          },
+          "additionalProperties": false,
+          "title": "GranularAskForApproval"
+        }
+      ]
+    },
+    "Config": {
+      "type": "object",
+      "properties": {
+        "analytics": {
+          "anyOf": [
+            {
+              "$ref": "#/definitions/AnalyticsConfig"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "approval_policy": {
+          "anyOf": [
+            {
+              "$ref": "#/definitions/AskForApproval"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "approvals_reviewer": {
+          "description": "[UNSTABLE] Optional default for where approval requests are routed for review.",
+          "anyOf": [
+            {
+              "$ref": "#/definitions/ApprovalsReviewer"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "web_search": {
+          "anyOf": [
+            {
+              "$ref": "#/definitions/WebSearchMode"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "compact_prompt": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "desktop": {
+          "type": [
+            "object",
+            "null"
+          ],
+          "additionalProperties": true
+        },
+        "developer_instructions": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "forced_chatgpt_workspace_id": {
+          "anyOf": [
+            {
+              "$ref": "#/definitions/ForcedChatgptWorkspaceIds"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "forced_login_method": {
+          "anyOf": [
+            {
+              "$ref": "#/definitions/ForcedLoginMethod"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "instructions": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "model": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "model_auto_compact_token_limit": {
+          "type": [
+            "integer",
+            "null"
+          ],
+          "format": "int64"
+        },
+        "model_context_window": {
+          "type": [
+            "integer",
+            "null"
+          ],
+          "format": "int64"
+        },
+        "model_provider": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "model_reasoning_effort": {
+          "anyOf": [
+            {
+              "$ref": "#/definitions/ReasoningEffort"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "model_reasoning_summary": {
+          "anyOf": [
+            {
+              "$ref": "#/definitions/ReasoningSummary"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "model_verbosity": {
+          "anyOf": [
+            {
+              "$ref": "#/definitions/Verbosity"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "profile": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "profiles": {
+          "default": {},
+          "type": "object",
+          "additionalProperties": {
+            "$ref": "#/definitions/ProfileV2"
+          }
+        },
+        "review_model": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "sandbox_mode": {
+          "anyOf": [
+            {
+              "$ref": "#/definitions/SandboxMode"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "sandbox_workspace_write": {
+          "anyOf": [
+            {
+              "$ref": "#/definitions/SandboxWorkspaceWrite"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "service_tier": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "tools": {
+          "anyOf": [
+            {
+              "$ref": "#/definitions/ToolsV2"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        }
+      },
+      "additionalProperties": true
+    },
+    "ConfigLayer": {
+      "type": "object",
+      "required": [
+        "config",
+        "name",
+        "version"
+      ],
+      "properties": {
+        "config": true,
+        "disabledReason": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "name": {
+          "$ref": "#/definitions/ConfigLayerSource"
+        },
+        "version": {
+          "type": "string"
+        }
+      }
+    },
+    "ConfigLayerMetadata": {
+      "type": "object",
+      "required": [
+        "name",
+        "version"
+      ],
+      "properties": {
+        "name": {
+          "$ref": "#/definitions/ConfigLayerSource"
+        },
+        "version": {
+          "type": "string"
+        }
+      }
+    },
+    "ConfigLayerSource": {
+      "oneOf": [
+        {
+          "description": "Managed preferences layer delivered by MDM (macOS only).",
+          "type": "object",
+          "required": [
+            "domain",
+            "key",
+            "type"
+          ],
+          "properties": {
+            "domain": {
+              "type": "string"
+            },
+            "key": {
+              "type": "string"
+            },
+            "type": {
+              "type": "string",
+              "enum": [
+                "mdm"
+              ],
+              "title": "MdmConfigLayerSourceType"
+            }
+          },
+          "title": "MdmConfigLayerSource"
+        },
+        {
+          "description": "Managed config layer from a file (usually `managed_config.toml`).",
+          "type": "object",
+          "required": [
+            "file",
+            "type"
+          ],
+          "properties": {
+            "file": {
+              "description": "This is the path to the system config.toml file, though it is not guaranteed to exist.",
+              "allOf": [
+                {
+                  "$ref": "#/definitions/AbsolutePathBuf"
+                }
+              ]
+            },
+            "type": {
+              "type": "string",
+              "enum": [
+                "system"
+              ],
+              "title": "SystemConfigLayerSourceType"
+            }
+          },
+          "title": "SystemConfigLayerSource"
+        },
+        {
+          "description": "User config layer from $CODEX_HOME/config.toml. This layer is special in that it is expected to be: - writable by the user - generally outside the workspace directory",
+          "type": "object",
+          "required": [
+            "file",
+            "type"
+          ],
+          "properties": {
+            "file": {
+              "description": "This is the path to the user's config.toml file, though it is not guaranteed to exist.",
+              "allOf": [
+                {
+                  "$ref": "#/definitions/AbsolutePathBuf"
+                }
+              ]
+            },
+            "profile": {
+              "description": "Name of the selected profile-v2 config layered on top of the base user config, when this layer represents one.",
+              "type": [
+                "string",
+                "null"
+              ]
+            },
+            "type": {
+              "type": "string",
+              "enum": [
+                "user"
+              ],
+              "title": "UserConfigLayerSourceType"
+            }
+          },
+          "title": "UserConfigLayerSource"
+        },
+        {
+          "description": "Path to a .codex/ folder within a project. There could be multiple of these between `cwd` and the project/repo root.",
+          "type": "object",
+          "required": [
+            "dotCodexFolder",
+            "type"
+          ],
+          "properties": {
+            "dotCodexFolder": {
+              "$ref": "#/definitions/AbsolutePathBuf"
+            },
+            "type": {
+              "type": "string",
+              "enum": [
+                "project"
+              ],
+              "title": "ProjectConfigLayerSourceType"
+            }
+          },
+          "title": "ProjectConfigLayerSource"
+        },
+        {
+          "description": "Session-layer overrides supplied via `-c`/`--config`.",
+          "type": "object",
+          "required": [
+            "type"
+          ],
+          "properties": {
+            "type": {
+              "type": "string",
+              "enum": [
+                "sessionFlags"
+              ],
+              "title": "SessionFlagsConfigLayerSourceType"
+            }
+          },
+          "title": "SessionFlagsConfigLayerSource"
+        },
+        {
+          "description": "`managed_config.toml` was designed to be a config that was loaded as the last layer on top of everything else. This scheme did not quite work out as intended, but we keep this variant as a \"best effort\" while we phase out `managed_config.toml` in favor of `requirements.toml`.",
+          "type": "object",
+          "required": [
+            "file",
+            "type"
+          ],
+          "properties": {
+            "file": {
+              "$ref": "#/definitions/AbsolutePathBuf"
+            },
+            "type": {
+              "type": "string",
+              "enum": [
+                "legacyManagedConfigTomlFromFile"
+              ],
+              "title": "LegacyManagedConfigTomlFromFileConfigLayerSourceType"
+            }
+          },
+          "title": "LegacyManagedConfigTomlFromFileConfigLayerSource"
+        },
+        {
+          "type": "object",
+          "required": [
+            "type"
+          ],
+          "properties": {
+            "type": {
+              "type": "string",
+              "enum": [
+                "legacyManagedConfigTomlFromMdm"
+              ],
+              "title": "LegacyManagedConfigTomlFromMdmConfigLayerSourceType"
+            }
+          },
+          "title": "LegacyManagedConfigTomlFromMdmConfigLayerSource"
+        }
+      ]
+    },
+    "ForcedChatgptWorkspaceIds": {
+      "description": "Backward-compatible API shape for ChatGPT workspace login restrictions.",
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        }
+      ]
+    },
+    "ForcedLoginMethod": {
+      "type": "string",
+      "enum": [
+        "chatgpt",
+        "api"
+      ]
+    },
+    "ProfileV2": {
+      "type": "object",
+      "properties": {
+        "approval_policy": {
+          "anyOf": [
+            {
+              "$ref": "#/definitions/AskForApproval"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "approvals_reviewer": {
+          "description": "[UNSTABLE] Optional profile-level override for where approval requests are routed for review. If omitted, the enclosing config default is used.",
+          "anyOf": [
+            {
+              "$ref": "#/definitions/ApprovalsReviewer"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "chatgpt_base_url": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "model": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "model_provider": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "model_reasoning_effort": {
+          "anyOf": [
+            {
+              "$ref": "#/definitions/ReasoningEffort"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "model_reasoning_summary": {
+          "anyOf": [
+            {
+              "$ref": "#/definitions/ReasoningSummary"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "model_verbosity": {
+          "anyOf": [
+            {
+              "$ref": "#/definitions/Verbosity"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "service_tier": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "tools": {
+          "anyOf": [
+            {
+              "$ref": "#/definitions/ToolsV2"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "web_search": {
+          "anyOf": [
+            {
+              "$ref": "#/definitions/WebSearchMode"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        }
+      },
+      "additionalProperties": true
+    },
+    "ReasoningEffort": {
+      "description": "See https://platform.openai.com/docs/guides/reasoning?api-mode=responses#get-started-with-reasoning",
+      "type": "string",
+      "enum": [
+        "none",
+        "minimal",
+        "low",
+        "medium",
+        "high",
+        "xhigh"
+      ]
+    },
+    "ReasoningSummary": {
+      "description": "A summary of the reasoning performed by the model. This can be useful for debugging and understanding the model's reasoning process. See https://platform.openai.com/docs/guides/reasoning?api-mode=responses#reasoning-summaries",
+      "oneOf": [
+        {
+          "type": "string",
+          "enum": [
+            "auto",
+            "concise",
+            "detailed"
+          ]
+        },
+        {
+          "description": "Option to disable reasoning summaries.",
+          "type": "string",
+          "enum": [
+            "none"
+          ]
+        }
+      ]
+    },
+    "SandboxMode": {
+      "type": "string",
+      "enum": [
+        "read-only",
+        "workspace-write",
+        "danger-full-access"
+      ]
+    },
+    "SandboxWorkspaceWrite": {
+      "type": "object",
+      "properties": {
+        "exclude_slash_tmp": {
+          "default": false,
+          "type": "boolean"
+        },
+        "exclude_tmpdir_env_var": {
+          "default": false,
+          "type": "boolean"
+        },
+        "network_access": {
+          "default": false,
+          "type": "boolean"
+        },
+        "writable_roots": {
+          "default": [],
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        }
+      }
+    },
+    "ToolsV2": {
+      "type": "object",
+      "properties": {
+        "web_search": {
+          "anyOf": [
+            {
+              "$ref": "#/definitions/WebSearchToolConfig"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        }
+      }
+    },
+    "Verbosity": {
+      "description": "Controls output length/detail on GPT-5 models via the Responses API. Serialized with lowercase values to match the OpenAI API.",
+      "type": "string",
+      "enum": [
+        "low",
+        "medium",
+        "high"
+      ]
+    },
+    "WebSearchContextSize": {
+      "type": "string",
+      "enum": [
+        "low",
+        "medium",
+        "high"
+      ]
+    },
+    "WebSearchLocation": {
+      "type": "object",
+      "properties": {
+        "city": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "country": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "region": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "timezone": {
+          "type": [
+            "string",
+            "null"
+          ]
+        }
+      },
+      "additionalProperties": false
+    },
+    "WebSearchMode": {
+      "type": "string",
+      "enum": [
+        "disabled",
+        "cached",
+        "live"
+      ]
+    },
+    "WebSearchToolConfig": {
+      "type": "object",
+      "properties": {
+        "allowed_domains": {
+          "type": [
+            "array",
+            "null"
+          ],
+          "items": {
+            "type": "string"
+          }
+        },
+        "context_size": {
+          "anyOf": [
+            {
+              "$ref": "#/definitions/WebSearchContextSize"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "location": {
+          "anyOf": [
+            {
+              "$ref": "#/definitions/WebSearchLocation"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        }
+      },
+      "additionalProperties": false
+    }
+  }
+}

schemas/v2/ConfigRequirementsReadResponse.json

@@ -0,0 +1,455 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "ConfigRequirementsReadResponse",
+  "type": "object",
+  "properties": {
+    "requirements": {
+      "description": "Null if no requirements are configured (e.g. no requirements.toml/MDM entries).",
+      "anyOf": [
+        {
+          "$ref": "#/definitions/ConfigRequirements"
+        },
+        {
+          "type": "null"
+        }
+      ]
+    }
+  },
+  "definitions": {
+    "ApprovalsReviewer": {
+      "description": "Configures who approval requests are routed to for review. Examples include sandbox escapes, blocked network access, MCP approval prompts, and ARC escalations. Defaults to `user`. `auto_review` uses a carefully prompted subagent to gather relevant context and apply a risk-based decision framework before approving or denying the request. The legacy value `guardian_subagent` is accepted for compatibility.",
+      "type": "string",
+      "enum": [
+        "user",
+        "auto_review",
+        "guardian_subagent"
+      ]
+    },
+    "AskForApproval": {
+      "oneOf": [
+        {
+          "type": "string",
+          "enum": [
+            "untrusted",
+            "on-failure",
+            "on-request",
+            "never"
+          ]
+        },
+        {
+          "type": "object",
+          "required": [
+            "granular"
+          ],
+          "properties": {
+            "granular": {
+              "type": "object",
+              "required": [
+                "mcp_elicitations",
+                "rules",
+                "sandbox_approval"
+              ],
+              "properties": {
+                "mcp_elicitations": {
+                  "type": "boolean"
+                },
+                "request_permissions": {
+                  "default": false,
+                  "type": "boolean"
+                },
+                "rules": {
+                  "type": "boolean"
+                },
+                "sandbox_approval": {
+                  "type": "boolean"
+                },
+                "skill_approval": {
+                  "default": false,
+                  "type": "boolean"
+                }
+              }
+            }
+          },
+          "additionalProperties": false,
+          "title": "GranularAskForApproval"
+        }
+      ]
+    },
+    "ConfigRequirements": {
+      "type": "object",
+      "properties": {
+        "allowManagedHooksOnly": {
+          "type": [
+            "boolean",
+            "null"
+          ]
+        },
+        "allowedApprovalPolicies": {
+          "type": [
+            "array",
+            "null"
+          ],
+          "items": {
+            "$ref": "#/definitions/AskForApproval"
+          }
+        },
+        "featureRequirements": {
+          "type": [
+            "object",
+            "null"
+          ],
+          "additionalProperties": {
+            "type": "boolean"
+          }
+        },
+        "allowedSandboxModes": {
+          "type": [
+            "array",
+            "null"
+          ],
+          "items": {
+            "$ref": "#/definitions/SandboxMode"
+          }
+        },
+        "allowedWebSearchModes": {
+          "type": [
+            "array",
+            "null"
+          ],
+          "items": {
+            "$ref": "#/definitions/WebSearchMode"
+          }
+        },
+        "enforceResidency": {
+          "anyOf": [
+            {
+              "$ref": "#/definitions/ResidencyRequirement"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        }
+      }
+    },
+    "ConfiguredHookHandler": {
+      "oneOf": [
+        {
+          "type": "object",
+          "required": [
+            "async",
+            "command",
+            "type"
+          ],
+          "properties": {
+            "async": {
+              "type": "boolean"
+            },
+            "command": {
+              "type": "string"
+            },
+            "commandWindows": {
+              "type": [
+                "string",
+                "null"
+              ]
+            },
+            "statusMessage": {
+              "type": [
+                "string",
+                "null"
+              ]
+            },
+            "timeoutSec": {
+              "type": [
+                "integer",
+                "null"
+              ],
+              "format": "uint64",
+              "minimum": 0.0
+            },
+            "type": {
+              "type": "string",
+              "enum": [
+                "command"
+              ],
+              "title": "CommandConfiguredHookHandlerType"
+            }
+          },
+          "title": "CommandConfiguredHookHandler"
+        },
+        {
+          "type": "object",
+          "required": [
+            "type"
+          ],
+          "properties": {
+            "type": {
+              "type": "string",
+              "enum": [
+                "prompt"
+              ],
+              "title": "PromptConfiguredHookHandlerType"
+            }
+          },
+          "title": "PromptConfiguredHookHandler"
+        },
+        {
+          "type": "object",
+          "required": [
+            "type"
+          ],
+          "properties": {
+            "type": {
+              "type": "string",
+              "enum": [
+                "agent"
+              ],
+              "title": "AgentConfiguredHookHandlerType"
+            }
+          },
+          "title": "AgentConfiguredHookHandler"
+        }
+      ]
+    },
+    "ConfiguredHookMatcherGroup": {
+      "type": "object",
+      "required": [
+        "hooks"
+      ],
+      "properties": {
+        "hooks": {
+          "type": "array",
+          "items": {
+            "$ref": "#/definitions/ConfiguredHookHandler"
+          }
+        },
+        "matcher": {
+          "type": [
+            "string",
+            "null"
+          ]
+        }
+      }
+    },
+    "ManagedHooksRequirements": {
+      "type": "object",
+      "required": [
+        "PermissionRequest",
+        "PostCompact",
+        "PostToolUse",
+        "PreCompact",
+        "PreToolUse",
+        "SessionStart",
+        "Stop",
+        "UserPromptSubmit"
+      ],
+      "properties": {
+        "PermissionRequest": {
+          "type": "array",
+          "items": {
+            "$ref": "#/definitions/ConfiguredHookMatcherGroup"
+          }
+        },
+        "PostCompact": {
+          "type": "array",
+          "items": {
+            "$ref": "#/definitions/ConfiguredHookMatcherGroup"
+          }
+        },
+        "PostToolUse": {
+          "type": "array",
+          "items": {
+            "$ref": "#/definitions/ConfiguredHookMatcherGroup"
+          }
+        },
+        "PreCompact": {
+          "type": "array",
+          "items": {
+            "$ref": "#/definitions/ConfiguredHookMatcherGroup"
+          }
+        },
+        "PreToolUse": {
+          "type": "array",
+          "items": {
+            "$ref": "#/definitions/ConfiguredHookMatcherGroup"
+          }
+        },
+        "SessionStart": {
+          "type": "array",
+          "items": {
+            "$ref": "#/definitions/ConfiguredHookMatcherGroup"
+          }
+        },
+        "Stop": {
+          "type": "array",
+          "items": {
+            "$ref": "#/definitions/ConfiguredHookMatcherGroup"
+          }
+        },
+        "UserPromptSubmit": {
+          "type": "array",
+          "items": {
+            "$ref": "#/definitions/ConfiguredHookMatcherGroup"
+          }
+        },
+        "managedDir": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "windowsManagedDir": {
+          "type": [
+            "string",
+            "null"
+          ]
+        }
+      }
+    },
+    "NetworkDomainPermission": {
+      "type": "string",
+      "enum": [
+        "allow",
+        "deny"
+      ]
+    },
+    "NetworkRequirements": {
+      "type": "object",
+      "properties": {
+        "allowLocalBinding": {
+          "type": [
+            "boolean",
+            "null"
+          ]
+        },
+        "allowUnixSockets": {
+          "description": "Legacy compatibility view derived from `unix_sockets`.",
+          "type": [
+            "array",
+            "null"
+          ],
+          "items": {
+            "type": "string"
+          }
+        },
+        "allowUpstreamProxy": {
+          "type": [
+            "boolean",
+            "null"
+          ]
+        },
+        "allowedDomains": {
+          "description": "Legacy compatibility view derived from `domains`.",
+          "type": [
+            "array",
+            "null"
+          ],
+          "items": {
+            "type": "string"
+          }
+        },
+        "dangerouslyAllowAllUnixSockets": {
+          "type": [
+            "boolean",
+            "null"
+          ]
+        },
+        "dangerouslyAllowNonLoopbackProxy": {
+          "type": [
+            "boolean",
+            "null"
+          ]
+        },
+        "deniedDomains": {
+          "description": "Legacy compatibility view derived from `domains`.",
+          "type": [
+            "array",
+            "null"
+          ],
+          "items": {
+            "type": "string"
+          }
+        },
+        "domains": {
+          "description": "Canonical network permission map for `experimental_network`.",
+          "type": [
+            "object",
+            "null"
+          ],
+          "additionalProperties": {
+            "$ref": "#/definitions/NetworkDomainPermission"
+          }
+        },
+        "enabled": {
+          "type": [
+            "boolean",
+            "null"
+          ]
+        },
+        "httpPort": {
+          "type": [
+            "integer",
+            "null"
+          ],
+          "format": "uint16",
+          "minimum": 0.0
+        },
+        "managedAllowedDomainsOnly": {
+          "description": "When true, only managed allowlist entries are respected while managed network enforcement is active.",
+          "type": [
+            "boolean",
+            "null"
+          ]
+        },
+        "socksPort": {
+          "type": [
+            "integer",
+            "null"
+          ],
+          "format": "uint16",
+          "minimum": 0.0
+        },
+        "unixSockets": {
+          "description": "Canonical unix socket permission map for `experimental_network`.",
+          "type": [
+            "object",
+            "null"
+          ],
+          "additionalProperties": {
+            "$ref": "#/definitions/NetworkUnixSocketPermission"
+          }
+        }
+      }
+    },
+    "NetworkUnixSocketPermission": {
+      "type": "string",
+      "enum": [
+        "allow",
+        "none"
+      ]
+    },
+    "ResidencyRequirement": {
+      "type": "string",
+      "enum": [
+        "us"
+      ]
+    },
+    "SandboxMode": {
+      "type": "string",
+      "enum": [
+        "read-only",
+        "workspace-write",
+        "danger-full-access"
+      ]
+    },
+    "WebSearchMode": {
+      "type": "string",
+      "enum": [
+        "disabled",
+        "cached",
+        "live"
+      ]
+    }
+  }
+}

schemas/v2/ConfigValueWriteParams.json

@@ -0,0 +1,41 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "ConfigValueWriteParams",
+  "type": "object",
+  "required": [
+    "keyPath",
+    "mergeStrategy",
+    "value"
+  ],
+  "properties": {
+    "expectedVersion": {
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "filePath": {
+      "description": "Path to the config file to write; defaults to the user's `config.toml` when omitted.",
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "keyPath": {
+      "type": "string"
+    },
+    "mergeStrategy": {
+      "$ref": "#/definitions/MergeStrategy"
+    },
+    "value": true
+  },
+  "definitions": {
+    "MergeStrategy": {
+      "type": "string",
+      "enum": [
+        "replace",
+        "upsert"
+      ]
+    }
+  }
+}

schemas/v2/ConfigWarningNotification.json

@@ -0,0 +1,77 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "ConfigWarningNotification",
+  "type": "object",
+  "required": [
+    "summary"
+  ],
+  "properties": {
+    "details": {
+      "description": "Optional extra guidance or error details.",
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "path": {
+      "description": "Optional path to the config file that triggered the warning.",
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "range": {
+      "description": "Optional range for the error location inside the config file.",
+      "anyOf": [
+        {
+          "$ref": "#/definitions/TextRange"
+        },
+        {
+          "type": "null"
+        }
+      ]
+    },
+    "summary": {
+      "description": "Concise summary of the warning.",
+      "type": "string"
+    }
+  },
+  "definitions": {
+    "TextPosition": {
+      "type": "object",
+      "required": [
+        "column",
+        "line"
+      ],
+      "properties": {
+        "column": {
+          "description": "1-based column number (in Unicode scalar values).",
+          "type": "integer",
+          "format": "uint",
+          "minimum": 0.0
+        },
+        "line": {
+          "description": "1-based line number.",
+          "type": "integer",
+          "format": "uint",
+          "minimum": 0.0
+        }
+      }
+    },
+    "TextRange": {
+      "type": "object",
+      "required": [
+        "end",
+        "start"
+      ],
+      "properties": {
+        "end": {
+          "$ref": "#/definitions/TextPosition"
+        },
+        "start": {
+          "$ref": "#/definitions/TextPosition"
+        }
+      }
+    }
+  }
+}

schemas/v2/ConfigWriteResponse.json

@@ -0,0 +1,244 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "ConfigWriteResponse",
+  "type": "object",
+  "required": [
+    "filePath",
+    "status",
+    "version"
+  ],
+  "properties": {
+    "filePath": {
+      "description": "Canonical path to the config file that was written.",
+      "allOf": [
+        {
+          "$ref": "#/definitions/AbsolutePathBuf"
+        }
+      ]
+    },
+    "overriddenMetadata": {
+      "anyOf": [
+        {
+          "$ref": "#/definitions/OverriddenMetadata"
+        },
+        {
+          "type": "null"
+        }
+      ]
+    },
+    "status": {
+      "$ref": "#/definitions/WriteStatus"
+    },
+    "version": {
+      "type": "string"
+    }
+  },
+  "definitions": {
+    "AbsolutePathBuf": {
+      "description": "A path that is guaranteed to be absolute and normalized (though it is not guaranteed to be canonicalized or exist on the filesystem).\n\nIMPORTANT: When deserializing an `AbsolutePathBuf`, a base path must be set using [AbsolutePathBufGuard::new]. If no base path is set, the deserialization will fail unless the path being deserialized is already absolute.",
+      "type": "string"
+    },
+    "ConfigLayerMetadata": {
+      "type": "object",
+      "required": [
+        "name",
+        "version"
+      ],
+      "properties": {
+        "name": {
+          "$ref": "#/definitions/ConfigLayerSource"
+        },
+        "version": {
+          "type": "string"
+        }
+      }
+    },
+    "ConfigLayerSource": {
+      "oneOf": [
+        {
+          "description": "Managed preferences layer delivered by MDM (macOS only).",
+          "type": "object",
+          "required": [
+            "domain",
+            "key",
+            "type"
+          ],
+          "properties": {
+            "domain": {
+              "type": "string"
+            },
+            "key": {
+              "type": "string"
+            },
+            "type": {
+              "type": "string",
+              "enum": [
+                "mdm"
+              ],
+              "title": "MdmConfigLayerSourceType"
+            }
+          },
+          "title": "MdmConfigLayerSource"
+        },
+        {
+          "description": "Managed config layer from a file (usually `managed_config.toml`).",
+          "type": "object",
+          "required": [
+            "file",
+            "type"
+          ],
+          "properties": {
+            "file": {
+              "description": "This is the path to the system config.toml file, though it is not guaranteed to exist.",
+              "allOf": [
+                {
+                  "$ref": "#/definitions/AbsolutePathBuf"
+                }
+              ]
+            },
+            "type": {
+              "type": "string",
+              "enum": [
+                "system"
+              ],
+              "title": "SystemConfigLayerSourceType"
+            }
+          },
+          "title": "SystemConfigLayerSource"
+        },
+        {
+          "description": "User config layer from $CODEX_HOME/config.toml. This layer is special in that it is expected to be: - writable by the user - generally outside the workspace directory",
+          "type": "object",
+          "required": [
+            "file",
+            "type"
+          ],
+          "properties": {
+            "file": {
+              "description": "This is the path to the user's config.toml file, though it is not guaranteed to exist.",
+              "allOf": [
+                {
+                  "$ref": "#/definitions/AbsolutePathBuf"
+                }
+              ]
+            },
+            "profile": {
+              "description": "Name of the selected profile-v2 config layered on top of the base user config, when this layer represents one.",
+              "type": [
+                "string",
+                "null"
+              ]
+            },
+            "type": {
+              "type": "string",
+              "enum": [
+                "user"
+              ],
+              "title": "UserConfigLayerSourceType"
+            }
+          },
+          "title": "UserConfigLayerSource"
+        },
+        {
+          "description": "Path to a .codex/ folder within a project. There could be multiple of these between `cwd` and the project/repo root.",
+          "type": "object",
+          "required": [
+            "dotCodexFolder",
+            "type"
+          ],
+          "properties": {
+            "dotCodexFolder": {
+              "$ref": "#/definitions/AbsolutePathBuf"
+            },
+            "type": {
+              "type": "string",
+              "enum": [
+                "project"
+              ],
+              "title": "ProjectConfigLayerSourceType"
+            }
+          },
+          "title": "ProjectConfigLayerSource"
+        },
+        {
+          "description": "Session-layer overrides supplied via `-c`/`--config`.",
+          "type": "object",
+          "required": [
+            "type"
+          ],
+          "properties": {
+            "type": {
+              "type": "string",
+              "enum": [
+                "sessionFlags"
+              ],
+              "title": "SessionFlagsConfigLayerSourceType"
+            }
+          },
+          "title": "SessionFlagsConfigLayerSource"
+        },
+        {
+          "description": "`managed_config.toml` was designed to be a config that was loaded as the last layer on top of everything else. This scheme did not quite work out as intended, but we keep this variant as a \"best effort\" while we phase out `managed_config.toml` in favor of `requirements.toml`.",
+          "type": "object",
+          "required": [
+            "file",
+            "type"
+          ],
+          "properties": {
+            "file": {
+              "$ref": "#/definitions/AbsolutePathBuf"
+            },
+            "type": {
+              "type": "string",
+              "enum": [
+                "legacyManagedConfigTomlFromFile"
+              ],
+              "title": "LegacyManagedConfigTomlFromFileConfigLayerSourceType"
+            }
+          },
+          "title": "LegacyManagedConfigTomlFromFileConfigLayerSource"
+        },
+        {
+          "type": "object",
+          "required": [
+            "type"
+          ],
+          "properties": {
+            "type": {
+              "type": "string",
+              "enum": [
+                "legacyManagedConfigTomlFromMdm"
+              ],
+              "title": "LegacyManagedConfigTomlFromMdmConfigLayerSourceType"
+            }
+          },
+          "title": "LegacyManagedConfigTomlFromMdmConfigLayerSource"
+        }
+      ]
+    },
+    "OverriddenMetadata": {
+      "type": "object",
+      "required": [
+        "effectiveValue",
+        "message",
+        "overridingLayer"
+      ],
+      "properties": {
+        "effectiveValue": true,
+        "message": {
+          "type": "string"
+        },
+        "overridingLayer": {
+          "$ref": "#/definitions/ConfigLayerMetadata"
+        }
+      }
+    },
+    "WriteStatus": {
+      "type": "string",
+      "enum": [
+        "ok",
+        "okOverridden"
+      ]
+    }
+  }
+}

schemas/v2/ContextCompactedNotification.json

@@ -0,0 +1,18 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "ContextCompactedNotification",
+  "description": "Deprecated: Use `ContextCompaction` item type instead.",
+  "type": "object",
+  "required": [
+    "threadId",
+    "turnId"
+  ],
+  "properties": {
+    "threadId": {
+      "type": "string"
+    },
+    "turnId": {
+      "type": "string"
+    }
+  }
+}

schemas/v2/DeprecationNoticeNotification.json

@@ -0,0 +1,21 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "DeprecationNoticeNotification",
+  "type": "object",
+  "required": [
+    "summary"
+  ],
+  "properties": {
+    "details": {
+      "description": "Optional extra guidance, such as migration steps or rationale.",
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "summary": {
+      "description": "Concise summary of what is deprecated.",
+      "type": "string"
+    }
+  }
+}

schemas/v2/ErrorNotification.json

@@ -0,0 +1,199 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "ErrorNotification",
+  "type": "object",
+  "required": [
+    "error",
+    "threadId",
+    "turnId",
+    "willRetry"
+  ],
+  "properties": {
+    "error": {
+      "$ref": "#/definitions/TurnError"
+    },
+    "threadId": {
+      "type": "string"
+    },
+    "turnId": {
+      "type": "string"
+    },
+    "willRetry": {
+      "type": "boolean"
+    }
+  },
+  "definitions": {
+    "CodexErrorInfo": {
+      "description": "This translation layer make sure that we expose codex error code in camel case.\n\nWhen an upstream HTTP status is available (for example, from the Responses API or a provider), it is forwarded in `httpStatusCode` on the relevant `codexErrorInfo` variant.",
+      "oneOf": [
+        {
+          "type": "string",
+          "enum": [
+            "contextWindowExceeded",
+            "usageLimitExceeded",
+            "serverOverloaded",
+            "cyberPolicy",
+            "internalServerError",
+            "unauthorized",
+            "badRequest",
+            "threadRollbackFailed",
+            "sandboxError",
+            "other"
+          ]
+        },
+        {
+          "type": "object",
+          "required": [
+            "httpConnectionFailed"
+          ],
+          "properties": {
+            "httpConnectionFailed": {
+              "type": "object",
+              "properties": {
+                "httpStatusCode": {
+                  "type": [
+                    "integer",
+                    "null"
+                  ],
+                  "format": "uint16",
+                  "minimum": 0.0
+                }
+              }
+            }
+          },
+          "additionalProperties": false,
+          "title": "HttpConnectionFailedCodexErrorInfo"
+        },
+        {
+          "description": "Failed to connect to the response SSE stream.",
+          "type": "object",
+          "required": [
+            "responseStreamConnectionFailed"
+          ],
+          "properties": {
+            "responseStreamConnectionFailed": {
+              "type": "object",
+              "properties": {
+                "httpStatusCode": {
+                  "type": [
+                    "integer",
+                    "null"
+                  ],
+                  "format": "uint16",
+                  "minimum": 0.0
+                }
+              }
+            }
+          },
+          "additionalProperties": false,
+          "title": "ResponseStreamConnectionFailedCodexErrorInfo"
+        },
+        {
+          "description": "The response SSE stream disconnected in the middle of a turn before completion.",
+          "type": "object",
+          "required": [
+            "responseStreamDisconnected"
+          ],
+          "properties": {
+            "responseStreamDisconnected": {
+              "type": "object",
+              "properties": {
+                "httpStatusCode": {
+                  "type": [
+                    "integer",
+                    "null"
+                  ],
+                  "format": "uint16",
+                  "minimum": 0.0
+                }
+              }
+            }
+          },
+          "additionalProperties": false,
+          "title": "ResponseStreamDisconnectedCodexErrorInfo"
+        },
+        {
+          "description": "Reached the retry limit for responses.",
+          "type": "object",
+          "required": [
+            "responseTooManyFailedAttempts"
+          ],
+          "properties": {
+            "responseTooManyFailedAttempts": {
+              "type": "object",
+              "properties": {
+                "httpStatusCode": {
+                  "type": [
+                    "integer",
+                    "null"
+                  ],
+                  "format": "uint16",
+                  "minimum": 0.0
+                }
+              }
+            }
+          },
+          "additionalProperties": false,
+          "title": "ResponseTooManyFailedAttemptsCodexErrorInfo"
+        },
+        {
+          "description": "Returned when `turn/start` or `turn/steer` is submitted while the current active turn cannot accept same-turn steering, for example `/review` or manual `/compact`.",
+          "type": "object",
+          "required": [
+            "activeTurnNotSteerable"
+          ],
+          "properties": {
+            "activeTurnNotSteerable": {
+              "type": "object",
+              "required": [
+                "turnKind"
+              ],
+              "properties": {
+                "turnKind": {
+                  "$ref": "#/definitions/NonSteerableTurnKind"
+                }
+              }
+            }
+          },
+          "additionalProperties": false,
+          "title": "ActiveTurnNotSteerableCodexErrorInfo"
+        }
+      ]
+    },
+    "NonSteerableTurnKind": {
+      "type": "string",
+      "enum": [
+        "review",
+        "compact"
+      ]
+    },
+    "TurnError": {
+      "type": "object",
+      "required": [
+        "message"
+      ],
+      "properties": {
+        "additionalDetails": {
+          "default": null,
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "codexErrorInfo": {
+          "anyOf": [
+            {
+              "$ref": "#/definitions/CodexErrorInfo"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "message": {
+          "type": "string"
+        }
+      }
+    }
+  }
+}

schemas/v2/ExperimentalFeatureEnablementSetParams.json

@@ -0,0 +1,17 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "ExperimentalFeatureEnablementSetParams",
+  "type": "object",
+  "required": [
+    "enablement"
+  ],
+  "properties": {
+    "enablement": {
+      "description": "Process-wide runtime feature enablement keyed by canonical feature name.\n\nOnly named features are updated. Omitted features are left unchanged. Send an empty map for a no-op.",
+      "type": "object",
+      "additionalProperties": {
+        "type": "boolean"
+      }
+    }
+  }
+}

schemas/v2/ExperimentalFeatureEnablementSetResponse.json

@@ -0,0 +1,17 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "ExperimentalFeatureEnablementSetResponse",
+  "type": "object",
+  "required": [
+    "enablement"
+  ],
+  "properties": {
+    "enablement": {
+      "description": "Feature enablement entries updated by this request.",
+      "type": "object",
+      "additionalProperties": {
+        "type": "boolean"
+      }
+    }
+  }
+}

schemas/v2/ExperimentalFeatureListParams.json

@@ -0,0 +1,30 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "ExperimentalFeatureListParams",
+  "type": "object",
+  "properties": {
+    "cursor": {
+      "description": "Opaque pagination cursor returned by a previous call.",
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "limit": {
+      "description": "Optional page size; defaults to a reasonable server-side value.",
+      "type": [
+        "integer",
+        "null"
+      ],
+      "format": "uint32",
+      "minimum": 0.0
+    },
+    "threadId": {
+      "description": "Optional loaded thread id. Pass this when showing feature state for an existing thread so enablement is computed from that thread's refreshed config, including project-local config for the thread's cwd.",
+      "type": [
+        "string",
+        "null"
+      ]
+    }
+  }
+}

schemas/v2/ExperimentalFeatureListResponse.json

@@ -0,0 +1,116 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "ExperimentalFeatureListResponse",
+  "type": "object",
+  "required": [
+    "data"
+  ],
+  "properties": {
+    "data": {
+      "type": "array",
+      "items": {
+        "$ref": "#/definitions/ExperimentalFeature"
+      }
+    },
+    "nextCursor": {
+      "description": "Opaque cursor to pass to the next call to continue after the last item. If None, there are no more items to return.",
+      "type": [
+        "string",
+        "null"
+      ]
+    }
+  },
+  "definitions": {
+    "ExperimentalFeature": {
+      "type": "object",
+      "required": [
+        "defaultEnabled",
+        "enabled",
+        "name",
+        "stage"
+      ],
+      "properties": {
+        "announcement": {
+          "description": "Announcement copy shown to users when the feature is introduced. Null when this feature is not in beta.",
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "defaultEnabled": {
+          "description": "Whether this feature is enabled by default.",
+          "type": "boolean"
+        },
+        "description": {
+          "description": "Short summary describing what the feature does. Null when this feature is not in beta.",
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "displayName": {
+          "description": "User-facing display name shown in the experimental features UI. Null when this feature is not in beta.",
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "enabled": {
+          "description": "Whether this feature is currently enabled in the loaded config.",
+          "type": "boolean"
+        },
+        "name": {
+          "description": "Stable key used in config.toml and CLI flag toggles.",
+          "type": "string"
+        },
+        "stage": {
+          "description": "Lifecycle stage of this feature flag.",
+          "allOf": [
+            {
+              "$ref": "#/definitions/ExperimentalFeatureStage"
+            }
+          ]
+        }
+      }
+    },
+    "ExperimentalFeatureStage": {
+      "oneOf": [
+        {
+          "description": "Feature is available for user testing and feedback.",
+          "type": "string",
+          "enum": [
+            "beta"
+          ]
+        },
+        {
+          "description": "Feature is still being built and not ready for broad use.",
+          "type": "string",
+          "enum": [
+            "underDevelopment"
+          ]
+        },
+        {
+          "description": "Feature is production-ready.",
+          "type": "string",
+          "enum": [
+            "stable"
+          ]
+        },
+        {
+          "description": "Feature is deprecated and should be avoided.",
+          "type": "string",
+          "enum": [
+            "deprecated"
+          ]
+        },
+        {
+          "description": "Feature flag is retained only for backwards compatibility.",
+          "type": "string",
+          "enum": [
+            "removed"
+          ]
+        }
+      ]
+    }
+  }
+}

schemas/v2/ExternalAgentConfigDetectParams.json

@@ -0,0 +1,21 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "ExternalAgentConfigDetectParams",
+  "type": "object",
+  "properties": {
+    "cwds": {
+      "description": "Zero or more working directories to include for repo-scoped detection.",
+      "type": [
+        "array",
+        "null"
+      ],
+      "items": {
+        "type": "string"
+      }
+    },
+    "includeHome": {
+      "description": "If true, include detection under the user's home (~/.claude, ~/.codex, etc.).",
+      "type": "boolean"
+    }
+  }
+}

schemas/v2/ExternalAgentConfigDetectResponse.json

@@ -0,0 +1,194 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "ExternalAgentConfigDetectResponse",
+  "type": "object",
+  "required": [
+    "items"
+  ],
+  "properties": {
+    "items": {
+      "type": "array",
+      "items": {
+        "$ref": "#/definitions/ExternalAgentConfigMigrationItem"
+      }
+    }
+  },
+  "definitions": {
+    "CommandMigration": {
+      "type": "object",
+      "required": [
+        "name"
+      ],
+      "properties": {
+        "name": {
+          "type": "string"
+        }
+      }
+    },
+    "ExternalAgentConfigMigrationItem": {
+      "type": "object",
+      "required": [
+        "description",
+        "itemType"
+      ],
+      "properties": {
+        "cwd": {
+          "description": "Null or empty means home-scoped migration; non-empty means repo-scoped migration.",
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "description": {
+          "type": "string"
+        },
+        "details": {
+          "anyOf": [
+            {
+              "$ref": "#/definitions/MigrationDetails"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "itemType": {
+          "$ref": "#/definitions/ExternalAgentConfigMigrationItemType"
+        }
+      }
+    },
+    "ExternalAgentConfigMigrationItemType": {
+      "type": "string",
+      "enum": [
+        "AGENTS_MD",
+        "CONFIG",
+        "SKILLS",
+        "PLUGINS",
+        "MCP_SERVER_CONFIG",
+        "SUBAGENTS",
+        "HOOKS",
+        "COMMANDS",
+        "SESSIONS"
+      ]
+    },
+    "HookMigration": {
+      "type": "object",
+      "required": [
+        "name"
+      ],
+      "properties": {
+        "name": {
+          "type": "string"
+        }
+      }
+    },
+    "McpServerMigration": {
+      "type": "object",
+      "required": [
+        "name"
+      ],
+      "properties": {
+        "name": {
+          "type": "string"
+        }
+      }
+    },
+    "MigrationDetails": {
+      "type": "object",
+      "properties": {
+        "commands": {
+          "default": [],
+          "type": "array",
+          "items": {
+            "$ref": "#/definitions/CommandMigration"
+          }
+        },
+        "hooks": {
+          "default": [],
+          "type": "array",
+          "items": {
+            "$ref": "#/definitions/HookMigration"
+          }
+        },
+        "mcpServers": {
+          "default": [],
+          "type": "array",
+          "items": {
+            "$ref": "#/definitions/McpServerMigration"
+          }
+        },
+        "plugins": {
+          "default": [],
+          "type": "array",
+          "items": {
+            "$ref": "#/definitions/PluginsMigration"
+          }
+        },
+        "sessions": {
+          "default": [],
+          "type": "array",
+          "items": {
+            "$ref": "#/definitions/SessionMigration"
+          }
+        },
+        "subagents": {
+          "default": [],
+          "type": "array",
+          "items": {
+            "$ref": "#/definitions/SubagentMigration"
+          }
+        }
+      }
+    },
+    "PluginsMigration": {
+      "type": "object",
+      "required": [
+        "marketplaceName",
+        "pluginNames"
+      ],
+      "properties": {
+        "marketplaceName": {
+          "type": "string"
+        },
+        "pluginNames": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        }
+      }
+    },
+    "SessionMigration": {
+      "type": "object",
+      "required": [
+        "cwd",
+        "path"
+      ],
+      "properties": {
+        "cwd": {
+          "type": "string"
+        },
+        "path": {
+          "type": "string"
+        },
+        "title": {
+          "type": [
+            "string",
+            "null"
+          ]
+        }
+      }
+    },
+    "SubagentMigration": {
+      "type": "object",
+      "required": [
+        "name"
+      ],
+      "properties": {
+        "name": {
+          "type": "string"
+        }
+      }
+    }
+  }
+}

schemas/v2/ExternalAgentConfigImportCompletedNotification.json

@@ -0,0 +1,5 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "ExternalAgentConfigImportCompletedNotification",
+  "type": "object"
+}

schemas/v2/ExternalAgentConfigImportParams.json

@@ -0,0 +1,194 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "ExternalAgentConfigImportParams",
+  "type": "object",
+  "required": [
+    "migrationItems"
+  ],
+  "properties": {
+    "migrationItems": {
+      "type": "array",
+      "items": {
+        "$ref": "#/definitions/ExternalAgentConfigMigrationItem"
+      }
+    }
+  },
+  "definitions": {
+    "CommandMigration": {
+      "type": "object",
+      "required": [
+        "name"
+      ],
+      "properties": {
+        "name": {
+          "type": "string"
+        }
+      }
+    },
+    "ExternalAgentConfigMigrationItem": {
+      "type": "object",
+      "required": [
+        "description",
+        "itemType"
+      ],
+      "properties": {
+        "cwd": {
+          "description": "Null or empty means home-scoped migration; non-empty means repo-scoped migration.",
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "description": {
+          "type": "string"
+        },
+        "details": {
+          "anyOf": [
+            {
+              "$ref": "#/definitions/MigrationDetails"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "itemType": {
+          "$ref": "#/definitions/ExternalAgentConfigMigrationItemType"
+        }
+      }
+    },
+    "ExternalAgentConfigMigrationItemType": {
+      "type": "string",
+      "enum": [
+        "AGENTS_MD",
+        "CONFIG",
+        "SKILLS",
+        "PLUGINS",
+        "MCP_SERVER_CONFIG",
+        "SUBAGENTS",
+        "HOOKS",
+        "COMMANDS",
+        "SESSIONS"
+      ]
+    },
+    "HookMigration": {
+      "type": "object",
+      "required": [
+        "name"
+      ],
+      "properties": {
+        "name": {
+          "type": "string"
+        }
+      }
+    },
+    "McpServerMigration": {
+      "type": "object",
+      "required": [
+        "name"
+      ],
+      "properties": {
+        "name": {
+          "type": "string"
+        }
+      }
+    },
+    "MigrationDetails": {
+      "type": "object",
+      "properties": {
+        "commands": {
+          "default": [],
+          "type": "array",
+          "items": {
+            "$ref": "#/definitions/CommandMigration"
+          }
+        },
+        "hooks": {
+          "default": [],
+          "type": "array",
+          "items": {
+            "$ref": "#/definitions/HookMigration"
+          }
+        },
+        "mcpServers": {
+          "default": [],
+          "type": "array",
+          "items": {
+            "$ref": "#/definitions/McpServerMigration"
+          }
+        },
+        "plugins": {
+          "default": [],
+          "type": "array",
+          "items": {
+            "$ref": "#/definitions/PluginsMigration"
+          }
+        },
+        "sessions": {
+          "default": [],
+          "type": "array",
+          "items": {
+            "$ref": "#/definitions/SessionMigration"
+          }
+        },
+        "subagents": {
+          "default": [],
+          "type": "array",
+          "items": {
+            "$ref": "#/definitions/SubagentMigration"
+          }
+        }
+      }
+    },
+    "PluginsMigration": {
+      "type": "object",
+      "required": [
+        "marketplaceName",
+        "pluginNames"
+      ],
+      "properties": {
+        "marketplaceName": {
+          "type": "string"
+        },
+        "pluginNames": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        }
+      }
+    },
+    "SessionMigration": {
+      "type": "object",
+      "required": [
+        "cwd",
+        "path"
+      ],
+      "properties": {
+        "cwd": {
+          "type": "string"
+        },
+        "path": {
+          "type": "string"
+        },
+        "title": {
+          "type": [
+            "string",
+            "null"
+          ]
+        }
+      }
+    },
+    "SubagentMigration": {
+      "type": "object",
+      "required": [
+        "name"
+      ],
+      "properties": {
+        "name": {
+          "type": "string"
+        }
+      }
+    }
+  }
+}

schemas/v2/ExternalAgentConfigImportResponse.json

@@ -0,0 +1,5 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "ExternalAgentConfigImportResponse",
+  "type": "object"
+}