Project Roadmap

Vision
Product Principles
Current Feature Matrix
Milestone Progress
Current Maintainer Priority
V1 Readiness Checklist
Security Audit Follow-Up
Live App-Server Findings
Live Testing Expansion Plan
Previous V1 Release Slice
Decisions Made For The First Interactive Lifecycle
Milestone 0: Package And Repo Baseline
Milestone 1: Wire Model And Codegen Foundation
Milestone 2: Stdio Transport And Typed Protocol Slice
Milestone 3: Public Client Actor And First Lifecycle API
Milestone 4: Event Streams And Ergonomic Handles
Milestone 5: Approvals, Richer Notifications, And Broader Protocol Coverage
Milestone 6: Public Docs, Examples, And Release Readiness
Open Tickets
Backlog Candidates
History

Vision

Make SwiftASB a small, dependable Swift package for talking to the local Codex app-server with a public API that feels native to Swift rather than like a thin JSON-RPC dump.

Product Principles

Keep the public API compact and easy to reason about.
Keep generated wire models internal unless a public exposure case is clearly earned.
Prefer explicit data models, actor ownership, and typed async streams over stringly fallback surfaces.
Grow the package from real lifecycle use cases instead of speculative abstraction.
Keep tests, maintainer notes, and roadmap status aligned with the actual shipped surface.

Current Feature Matrix

Area	Current Status	Notes
Bundled schema-driven wire generation	`Shipped internally`	`scripts/generate-wire-types.sh` derives from the bundled v2 schema, patches dynamic JSON to `CodexWireJSONValue`, and validates the staged Swift output.
Promoted generated v2 wire snapshot	`Shipped internally`	`Sources/SwiftASB/Generated/CodexWire/Latest/` now contains a wider lifecycle batch covering bootstrap, stored and loaded thread reads, filesystem reads and watches, config reads, extension inventory, remote-control status plus pairing/client-management wire families, thread goals, and many thread, turn, item, reasoning, and tool-progress notifications, alongside the hand-owned `CodexWireInitializeResponse` shim.
Codex CLI schema review	`Shipped / ongoing`	The current reviewed compatibility window is `codex-cli 0.143.x plus 0.142.x when feasible`; the staged `v0.143.0` refresh promoted the generated v2 lifecycle batch internally, renamed the stored item paging route to `thread/items/list`, kept new thread-start fallback/history fields internal, preserved source compatibility for SwiftASB's older `.onFailure` approval policy while the upstream wire enum now encodes it as `on-request`, added internal npm plugin-source metadata, and preserved the repeatable dump and generation path through `scripts/dump-codex-schemas.sh` and `scripts/generate-wire-types.sh`.
Stdio subprocess transport	`Shipped internally`	The transport launches `codex app-server --listen stdio://`, frames newline-delimited JSON, correlates request IDs, and captures stderr for diagnostics.
Raw server-event fanout	`Shipped internally`	Transport can stream raw JSON-RPC notifications and server requests to higher layers.
Typed protocol request encoding	`Shipped internally`	`initialize`, `initialized`, core thread and turn methods, archive-state actions, filesystem reads and watches, config reads, app/skill/plugin/collaboration-mode inventory, model/MCP/hook reads, MCP resource reads, and thread-goal methods are encoded through the protocol layer.
Typed protocol response decoding	`Shipped internally`	`initialize`, core thread and turn methods, archive-state actions, filesystem reads and watches, config reads, app/skill/plugin/collaboration-mode inventory, model/MCP/hook reads, MCP resource reads, and thread-goal responses are decoded and validated against request IDs.
Typed protocol notification decoding	`Partially shipped`	The protocol layer now maps a broader batch of app, thread, turn, item, reasoning, hook, MCP-status, config-warning, deprecation, remote-control, and reroute notifications, plus the item lifecycle needed to drive the current observable tool, MCP, file-edit, hook, and compaction summaries.
Public owning client actor	`Shipped`	`CodexAppServer` owns transport plus protocol and exposes startup, shutdown, initialize, thread start, and turn start.
Public value-typed request and result models	`Shipped`	Public API uses hand-owned Swift value types rather than exposing `CodexWire...` directly.
App-wide capability surfaces	`Partially shipped`	`CodexExtensions.Inventory` now provides observable model capabilities, global MCP summaries, hook diagnostics, apps, skills, plugins, and collaboration modes with SwiftASB-owned refresh from app-server inventory notifications. Direct methods such as `listModels(...)`, `readModelCapabilities()`, `listHooks(...)`, `extensions.mcp.statusSnapshot()`, and `extensions.mcp.readResource(...)` remain available for one-off reads and inspector-style detail. Broader app-wide settings and actions still need deliberate public models before promotion.
Initialize handshake	`Shipped`	`initialize(...)` automatically sends the follow-up `initialized` notification.
Thread start flow	`Shipped`	`startThread(...)` returns `CodexThread`, which carries thread metadata plus a back-reference to the shared app-server owner.
Stored thread list flow	`Shipped`	`listThreads(...)` wraps `thread/list`, returns typed stored-thread pages, and now reconciles local thread metadata plus explicit archived or unarchived list results back into the internal history store.
Stored thread read flow	`Shipped`	`readThread(...)` wraps `thread/read`, returns typed thread and turn values, and hydrates the internal history store when turns are requested.
Stored thread resume flow	`Shipped`	`resumeThread(...)` wraps `thread/resume`, returns a normal `CodexThread`, restores thread defaults, clears stale archived state for the reopened thread, and hydrates any resumed persisted turns into the same local history store without resetting completeness to a fresh-thread state. Callers can set `excludeTurns` when they plan to page history separately through `thread/turns/list`.
Stored thread fork flow	`Shipped`	`forkThread(...)` wraps `thread/fork`, returns a normal `CodexThread`, persists copied fork history into thread-scoped local turn rows, and records explicit fork lineage through the source thread id plus the last shared turn id. Callers can set `excludeTurns` when they want the fork metadata first and copied turn history through paged reads afterward.
Thread management actions	`Partially shipped`	`CodexThread.setName(...)` wraps `thread/name/set`, `CodexThread.archive()` wraps `thread/archive`, `CodexThread.unarchive()` wraps `thread/unarchive`, `CodexThread.updateMetadata(...)` wraps `thread/metadata/update`, and `CodexThread.rollbackLastTurns(...)` wraps `thread/rollback`. Metadata patches use an explicit replace/clear/unchanged field model so callers can express upstream null-vs-omitted semantics. Rollback reconciles visible local history to the app-server response, records a rollback marker, and now has opt-in live coverage against a disposable non-ephemeral thread, but it does not preserve full removed turn payloads as forensic archive data yet.
App-server filesystem reads and watches	`Partially shipped`	`CodexAppServer.fs` now exposes the `CodexFS` namespace for app-server-routed metadata, directory listing, file-byte reads, bounded file discovery, SwiftASB-owned fuzzy ranking over app-server-returned entries, UI-ready discovery match metadata, and filesystem watch notifications. This gives sandboxed clients a Codex-owned path for basic filesystem facts and picker/search views instead of requiring direct local disk reads. File mutations are now internally promoted for protocol work; public mutation and repository-root surfaces still need deliberate shape decisions.
App-server config reads	`Partially shipped`	`CodexAppServer.config` now exposes `CodexConfig` for effective config and requirements reads through the app-server. Effective config stays JSON-shaped for now so SwiftASB does not turn unstable config keys into long-lived public Swift fields too early.
App-server extension inventory and maintenance	`Partially shipped`	Routine app, skill, plugin, MCP, and collaboration-mode inventory now flows through top-level `CodexExtensions`. `CodexAppServer.extensions` exposes family surfaces for custom pagination, selected plugin-detail reads, MCP status/resource reads, unified MCP installs, and plugin marketplace upgrades through app-server `command/exec` under the `extensionMaintenance` feature category. Plugin installs, removals, marketplace reads/writes, sharing changes, and skills config writes remain high-priority promotion candidates once their permission and review model is clearer.
SwiftASB feature permission policy	`Fifth slice shipped`	`SwiftASBFeaturePolicy`, `SwiftASBFeatureCategory`, and `SwiftASBHostAccess` now describe feature-category defaults and host access declarations, and `CodexAppServer.Configuration` accepts the app-wide feature policy. SwiftASB also has an internal `command/exec` protocol/executor path for future typed Git/GitHub helper intents, `CodexAppServer.Library` selected-worktree Git status refresh through the default-enabled `gitObservability` category, `CodexAppServer.featureOperationEvents()` for human-readable SwiftASB-owned mutation records, and a typed marketplace-upgrade maintenance intent. Maintainer planning targets quiet read-only Git/config/extension inventory by default, one-time mutation-category enablement, and human-readable mutation events instead of repeated prompts. See `docs/maintainers/feature-permission-policy-plan.md`.
Thread goals	`Partially shipped`	`CodexThread.readGoal()`, `setGoal(...)`, and `clearGoal()` wrap `thread/goal/get`, `thread/goal/set`, and `thread/goal/clear`, thread event streams now surface goal updated and cleared notifications, and `CodexThread.Agenda` provides UI-friendly `setGoal(...)`, `pauseGoal()`, `resumeGoal()`, and `clearGoal()` actions.
Thread shell commands	`Partially shipped`	`CodexThread.sendShellCommand(_:)` wraps app-server `thread/shellCommand` as a thread-scoped, literal shell-string action. This is deliberately separate from SwiftASB's internal `command/exec` helper path because `thread/shellCommand` preserves shell syntax and is documented upstream as unsandboxed full-user shell access. The public method is gated behind the disabled-by-default high-impact `shellCommandExecution` feature category.
Code review start flow	`Partially shipped`	`CodexThread.startReview(against:placement:)` wraps app-server `review/start` with hand-owned review subjects and placement names. Inline reviews run on the source thread; detached reviews run on the returned review thread and surface that id through `CodexReviewHandle.reviewThreadID`.
Paged turn-history flow	`Shipped`	`listThreadTurns(...)` wraps `thread/turns/list`, returns typed paged turn values, and can now seed the local history cache even before that thread has been loaded locally.
Typed async thread event stream	`Partially shipped`	`CodexThread.events` now streams `thread/started`, `thread/status/changed`, `thread/archived`, `thread/unarchived`, `thread/name/updated`, `thread/tokenUsage/updated`, `thread/goal/updated`, `thread/goal/cleared`, and `thread/closed`, but broader thread lifecycle coverage is still pending.
Turn start flow	`Shipped`	`startTurn(...)` returns `CodexTurnHandle`, and turn requests can opt into app-server collaboration mode through `CodexAppServer.TurnCollaborationMode`.
Typed async turn event stream	`Partially shipped`	`CodexTurnHandle.events` now streams `turn/started`, `turn/plan/updated`, `turn/diff/updated`, item lifecycle updates, message deltas, reasoning deltas, and `turn/completed`, but broader item and thread events still remain internal.
Multiple active threads per app-server	`Shipped`	One `CodexAppServer` now supports many concurrently held `CodexThread` handles, and the package tests plus live probes treat cross-thread concurrency as a supported model.
Multiple simultaneous turns on one thread	`Resolved for now`	Live probing showed that same-thread overlap is not independently routable at the app-server layer today, so `SwiftASB` rejects overlapping same-thread turns client-side with `CodexAppServerError.invalidState`.
`CodexThread` convenience wrapper	`Partially shipped`	`CodexThread` exists, owns thread-scoped turn creation, includes `startTextTurn(...)` and `startPlanningTurn(...)` helpers, exposes a typed thread event stream, wraps `compactContext()`, and can now vend live `Dashboard` and `Agenda` observable mirrors for status plus plan/goal state.
Thread-scoped recent-turn observable	`Partially shipped`	`CodexThread.makeRecentTurns(limit:)` now vends a bounded recent-turn observable that prewarms from the local history store, supports explicit older/newer whole-turn window expansion, seeds upstream paging cursors even when the visible initial window came from local history, and falls back to `thread/turns/list` when needed. Live probing showed that upstream turn paging is available only after a non-ephemeral thread has materialized at least one user turn, so recent observable startup now degrades to an empty local-only view for the known ephemeral and pre-materialized live runtime responses instead of surfacing raw protocol text. `RecentTurns` now ships named cache-policy presets for chat UIs, full inspectors, and compact history rails; tracks both resident item counts and weighted resident item cost; slims low-value payloads out of older non-visible completed turns before evicting whole turns; rehydrates slimmed turns when they become visible again; and uses scroll-position, visibility, phase, and velocity signals to drive protected residency plus earlier prefetch. Richer weighting heuristics and deeper policy tuning are still open.
Thread-scoped recent-file observable	`Partially shipped`	`CodexThread.makeRecentFiles(limit:)` and `makeRecentFiles(_:)` now vend a file-centric recent-files observable that hydrates from persisted file-change items, keeps one resident entry per file-change item, enriches live entries from `item/fileChange/outputDelta` and `item/fileChange/patchUpdated`, can load older file entries from the same turn before stepping farther back through older turns, and supports selection-aware shell-versus-payload slimming with automatic payload rehydration for protected files. `CodexThread.RecentFilesQD` gives callers a repeatable descriptor for the initial resident file window and cache policy. Live probing exercises a real create/edit/delete scenario, and recent-file startup now inherits the same empty local-only degradation as recent-turns for the known live history-unavailable responses. The current weighting now accounts for diff structure and line volume, and shell summaries prefer concise edit summaries over raw terminal status when sealed payload is available. The remaining open work is better payload-cost calibration at the margins and richer structured patch presentation beyond the current text preview.
Thread-scoped recent-command observable	`Partially shipped`	`CodexThread.makeRecentCommands(limit:)` and `makeRecentCommands(_:)` now vend a command-centric recent-commands observable that hydrates from persisted `commandExecution` items, keeps one resident entry per command item, enriches live entries from `item/commandExecution/outputDelta`, can load older command entries from the same turn before stepping farther back through older turns, and supports selection-aware shell-versus-output slimming with automatic output rehydration for protected commands. `CodexThread.RecentCommandsQD` gives callers a repeatable descriptor for the initial resident command window and cache policy. Recent-command startup now inherits the same empty local-only degradation as recent-turns for the known live history-unavailable responses. Current output weighting accounts for output size and line structure, and shell summaries prefer concise command and output summaries over raw transport detail. The remaining open work is better output-cost calibration and sharper shell-summary heuristics.
App-wide observable companions	`Partially shipped`	`CodexExtensions.makeInventory()` now exposes the app-wide observable for routine model capabilities, global MCP summaries, hook diagnostics, apps, skills, plugins, and collaboration modes, while `CodexAppServer.makeInventory()` remains a deprecated forwarding convenience until the next major version. `CodexAppServer.makeLibrary()` and `CodexAppServer.Library` expose Core Data-backed stored-thread lists, cwd and repository grouping, stable worktree groups, repository/worktree thread filters, project/worktree identity, bindable sort/grouping policies, scoped refresh actions, library-local selection, selected worktree Git status, and optional model/MCP/hook snapshots beside thread lists. Broader app-wide settings/actions still need deliberate public models before promotion.
Public query descriptors	`Partially shipped`	`CodexAppServer.ThreadListQD` now provides repeatable thread-list intent for direct app-server `thread/list` reads and app-wide `Library` loading, `CodexFS.FileDiscoveryQD` provides repeatable bounded file-discovery intent over app-server `fs/readDirectory` reads, `CodexThread.HistoryWindowQD` provides repeatable local completed-turn window intent for recent, older, newer, turn-centered, and item-centered reads, and `CodexThread.RecentFilesQD` plus `CodexThread.RecentCommandsQD` describe recent-activity companion startup. Repository grouping now uses `CodexWorkspace.ProjectInfo`, and per-thread UI state can read `CodexWorkspace.WorktreeSnapshot`, both of which identify a project by Codex-reported Git origin when available and fall back to cwd. Remaining descriptor work includes broader public cursor semantics, selection-centered reads if a concrete caller needs them, and later search-hit hydration.
Non-UI local history-reading helpers	`Partially shipped`	`CodexThread` now exposes a lightweight `HistoryWindow` page shape for recent local history, older or newer local windows around a known boundary turn id, centered `windowAroundTurn(...)` reads, centered `windowAroundItem(...)` reads, direct `ClosedTurn` reads for one turn, and convenience array helpers over those same windows. This gives non-UI callers an intentional path into the local history store without binding a UI-oriented observable, while still deferring a broader public cursor model, transcript search surface, and richer history-query helpers.
Public API curation	`Shipped / ongoing`	The source-organization pass has split app-wide model, MCP, thread-management, history, and observable companion values into focused public files while preserving `CodexAppServer`, `CodexThread`, and `CodexTurnHandle` as the three real owners. The connected public-surface review closed the v1 ownership model; post-v1 curation now includes app-server-owned project identity and thread source facts for launcher UI without exposing generated wire models. Future curation should stay tied to concrete public API additions.
DocC documentation	`Shipped / ongoing`	`Sources/SwiftASB/SwiftASB.docc/` contains a package landing page, public-handle extension pages, conceptual articles for app-wide capabilities, interactive lifecycle, thread management, history/observable companions, generated-wire boundary notes, and copy-pasteable walkthroughs for startup, progress/approval handling, diagnostics/history, and SwiftUI observable companions. The catalog is validated through Xcode `docbuild`; future work is ordinary stale-link, prose, and symbol-comment refinement as the public API grows.
Swift Package Index readiness	`Shipped`	`.spi.yml` declares `SwiftASB` as the documentation target, and Swift Package Index lists `gaelic-ghost/SwiftASB` with a documentation link, compatibility/build results, and Package ID `9B5839D9-9551-473F-A939-841534A3FC55`.
Contributor documentation split	`Shipped`	`README.md` is now focused on Swift and SwiftUI package users, while `CONTRIBUTING.md` owns contributor setup, validation, DocC, live-test flags, generated-wire refresh, and PR expectations.
`CodexTurnHandle` live observable companion	`Partially shipped`	`CodexTurnHandle` owns a live `Minimap` companion that is attached when the handle is created and maintains current-state call snapshots for command, file-edit, dynamic-tool, collab-tool, and MCP item activity. It also now mirrors whether thread context compaction is active for the turn and supports explicit `complete()` handoff into a caller-owned sealed turn snapshot.
Additional turn event mapping	`Partially shipped`	The public event layer covers the current interactive lifecycle plus the item-start and item-complete events needed for observable call-state mirrors. Raw command-output and file-change-output deltas now stay internal as transport detail but drive the shipped `RecentCommands` and `RecentFiles` companions, and streamed or patch-updated payloads are preserved when later completed snapshots are thinner. Richer MCP-progress detail still remains internal, while warning, guardian-warning, config-warning, deprecation, MCP-server-status, remote-control-status, model-reroute, and model-verification notifications now surface through hand-owned diagnostic events.
Server request / approval handling	`Partially shipped`	Typed approval and elicitation request models now surface on thread and turn event streams, explicit response APIs exist on `CodexThread` and `CodexTurnHandle`, request resolution is tracked by JSON-RPC request id, and deterministic command-approval plus permissions-approval completion are covered through the real app-server with a mock Responses provider. Diagnostics are now separated from control flows: passive warning/model/guardian signals are public diagnostics, while guardian denied-action approvals now flow through SwiftASB's existing approval-needed model so auto-review denial cases can be answered through the same consumer path.
Internal thread history persistence	`Partially shipped`	The package now has a Core Data-backed `ThreadHistoryStore` that persists live-built thread and turn history, hydrates stored turns from `thread/read`, `thread/resume`, `thread/fork`, and `thread/turns/list`, seeds previously unknown local threads from paged history, widens persisted turn identity to stay thread-scoped across forks, and records explicit fork lineage while preserving conservative reconciliation that keeps richer local detail when upstream stored history is thinner. Public history paging/search helpers and archive-retention policy are still open.
Direct local Codex thread storage	`Planned / prototyped`	SwiftASB now has a maintainer plan for an opt-in, read-only local Codex storage reader that can inventory threads through Codex's SQLite metadata and lazily hydrate JSONL evidence without forcing every caller through the app-server JSONL pipe. AgentSB prototypes the inspection shape for reports only; the package API, version gates, privacy defaults, and fallback behavior remain separate SwiftASB design work. See `docs/maintainers/codex-direct-thread-storage-plan.md`.
Convenience run API	`Not started`	No `run(...)` or one-shot text convenience layer yet.
Binary discovery and compatibility policy	`Partially shipped`	Explicit binary override exists, the docs now define a current-reviewed Codex CLI support window of `0.143.x plus 0.142.x when feasible`, transport startup checks PATH, common Homebrew paths, and the npm global prefix on macOS, and `cliExecutableDiagnostics()` now exposes the resolved binary, version string, and documented support-window assessment. Any further diagnostics work is now expansion rather than a missing baseline surface.
README-level consumer docs	`Shipped / ongoing`	The README covers installation, runtime assumptions, first-use examples, the supported lifecycle, SwiftUI companion surfaces, and the current Codex CLI compatibility window. Future README work should track new public API additions rather than prerelease readiness.
AgentSB maintainer automation	`Report-first maintainer app`	`Tools/AgentSB/` is a repo-local Python maintainer app that inspects SwiftASB deterministically, writes tracked reports under `docs/agents/reports/`, evaluates safety-boundary cases, diffs schema dumps, writes reviewable maintenance drafts, and prototypes local Codex thread-index inspection for future SwiftASB planning. The v1 boundary stays report-first: safe auto-apply is classifier-gated and limited to AgentSB-owned report artifacts, and it must not mutate Swift source, generated wire snapshots, public API, releases, or behavior-changing docs.
Agent workflow guidance	`Shipped / ongoing`	SwiftASB-specific Codex guidance now ships through `socket`'s `swiftasb-skills` plugin, with skills for explaining SwiftASB, choosing an integration shape, building SwiftUI-facing app state, and diagnosing integration failures. This repo now points package users and maintainers at that plugin while keeping SwiftASB source, DocC, tests, generated-wire review, and release notes here as the package source of truth.
End-to-end subprocess integration tests	`Shipped / ongoing`	The package includes opt-in live Codex CLI integration tests with temp workspaces and time limits, including raw transport startup, single-turn completion, cross-thread completion, app-wide model/MCP/hook diagnostics snapshots, thread-name mutation, stored-history materialization, same-thread concurrency probing, deterministic command and permissions approvals through a mock Responses provider, a best-effort prompt-driven approval-path probe, a disposable live rollback scenario, and a multi-turn file-mutation scenario that creates, edits, and deletes files through the real CLI. The umbrella runner is `scripts/run-live-codex-integration-tests.sh`; it defaults to the release-gate set and exposes focused modes for smoke, transport, capability, thread, turn, approval, file-scenario, rollback, same-thread, and all opt-in live tests. Stored-history materialization remains in focused `thread`/`all` runs instead of the release-gate smoke group because the live app-server can delay history materialization.
Apache 2.0 licensing	`Shipped`	Current public versions use the Apache License 2.0 through the root `LICENSE` and `NOTICE` files.

Milestone Progress

Milestone 0: Package And Repo Baseline - Completed
Milestone 1: Wire Model And Codegen Foundation - Completed
Milestone 2: Stdio Transport And Typed Protocol Slice - Completed
Milestone 3: Public Client Actor And First Lifecycle API - Completed
Milestone 4: Event Streams And Ergonomic Handles - Completed
Milestone 5: Approvals, Richer Notifications, And Broader Protocol Coverage - Completed
Milestone 6: Public Docs, Examples, And Release Readiness - Completed

Current Maintainer Priority

The next meaningful package step is no longer proving the v1 interactive lifecycle, SPI visibility, basic history hydration, first-pass reconciliation, or command-approval completion. Those slices now exist and shipped in the v1.7.1 baseline.

The next meaningful work after the v1.8.1 patch release is to probe and deliberately shape the newly promoted Codex CLI 0.143.x wire families before widening public API further. The v0.143.0 promotion refreshes the internal wire snapshot, moves the stored item paging wire route from thread/turns/items/list to thread/items/list, adds internal npm plugin-source metadata, removes the upstream on-failure approval-policy enum case, and adds internal thread-start fallback/history fields without adding new public request or action surfaces. Capability roots, plugin sharing metadata, remote-control pairing/client management and pairing status, account token usage, turn moderation metadata, plugin app templates, richer turn-start context, runtime workspace roots, environments, structured output schemas, rollout-path forking, thread settings, injected items, realtime routes, and background-terminal routes still need live behavior evidence before SwiftASB turns them into stable Swift surfaces. Descriptors should compile against Codex-owned workspace, Git, file, and thread facts wherever possible, rather than making SwiftASB or a sandboxed client infer repository identity by walking the local filesystem.

The 2026-05-11 repository-wide security audit added two patch-sized hardening items that landed before broadening more protocol surface: preserving or rejecting out-of-range numeric JSON-RPC IDs instead of narrowing through NSNumber.intValue, and failing closed for unknown network-policy amendment actions instead of representing them as allow. See docs/security-audits/82ea49d_20260511T213956-0400/report.md.

The package can now:

start turns through CodexThread
stream typed thread and turn progress
answer approval and elicitation requests through typed public models
steer an active turn
interrupt an active turn
mirror per-turn command, file-edit, and MCP activity through CodexTurnHandle.Minimap.callSnapshots
mirror thread-level tool, MCP, hook, and compaction status through CodexThread.Dashboard
read a stored thread through thread/read
list stored threads through thread/list
page stored turn history through thread/turns/list
hydrate the internal history store from both live item streams and upstream stored-history reads
read centered local history windows around a known turn or item through windowAroundTurn(...) and windowAroundItem(...)
set thread names, patch stored Git metadata, and roll back trailing turns through CodexThread
archive and unarchive stored threads through CodexThread
publish app-wide model, MCP-summary, hook, app, skill, plugin, and collaboration-mode inventory through CodexExtensions.Inventory
expose MCP full status, resource detail, and unified MCP install through CodexAppServer.extensions
document the supported lifecycle in the README without sending consumers into the tests

The current broader priority order is to complete app-server command families that SwiftASB has already started wrapping, then turn the coherent families into "we do it for you" surfaces that are observable, permission-aware, and easy for consuming apps to adopt:

Implement the feature permission policy described in docs/maintainers/feature-permission-policy-plan.md: read-only and inventory features stay enabled by default, mutation categories are enabled once by the consuming app, and every write/mutation emits human-readable observable operation events instead of recurring prompts.
Finish the filesystem family now that reads, watches, and internal mutations exist: decide the public mutation shape, repository-root discovery boundary, observable operation events, and sandbox/app-access story together instead of exposing isolated write methods.
Promote more app settings, config writes, rules, and thread settings in one settings-oriented family. The useful consumer outcome is a SwiftASB-owned way to inspect current Codex behavior, apply explicit config edits, and show reviewable before/after changes without consumers hand-writing TOML.
Design a house-style config system as an optional SwiftASB policy surface. It should support repo-local defaults, language-specific auto-enhance for automatically adding language skills or guidance to repos, idempotent config writes, observable mutation events, and rollback where the app-server gives enough information to do that honestly.
Promote marketplace, plugin, and skill-management routes as a coherent extension-management family: inventory, detail, install or remove, upgrade, sharing, skill config reads/writes, and marketplace configuration changes. Treat this as a high-value "we do it for you" surface because consumers should not need to understand every app-server extension route to keep a user's Codex environment useful.
Rework thread settings and promote thread/inject_items together. Saved prompts, automated setup messages, and agent-driven thread preparation need an intentional model that distinguishes user-authored prompt material, app-injected setup context, and automation-added items.
Add a WebKit-based auth helper flow for both Codex and MCP setup. This should help a macOS consuming app complete browser/OAuth-style auth without forcing users to bounce through unrelated terminals, while preserving a clear boundary between Codex account auth and MCP server auth.
Continue promoting app-server-owned workspace and Git facts beyond the current cwd, origin metadata, runtime permission-profile provenance, and CodexWorkspace.WorktreeSnapshot: Git worktree root if upstream exposes it, branch/SHA observables, and any workspace listing/search/status actions that upstream already owns. Use sandboxed command/exec fallback only for typed Git fact intents that upstream does not expose yet; do not use unsandboxed process/spawn for permission-sensitive helpers.
Add a deliberate codex mcp-server support plan as a separate integration lane from codex app-server. The current MCP mode should be treated as an external-agent bridge with a smaller stdio tool surface, not as a replacement for the app-server lifecycle SwiftASB already wraps. Verify the live initialize, tools/list, resources/list, and prompts/list surface before deciding whether SwiftASB should expose client helpers, examples, or a dedicated package module for it.
Evaluate runtime/process routes as a command-organization problem before promoting them. The public shape should connect to the existing command-observable and feature-permission model, distinguish app-server command helpers from raw process control, and avoid creating a second, less-safe command surface beside command/exec and thread/shellCommand.
Evaluate a Worktrunk-based worktree system only after the workspace and Git fact boundary is clearer. The useful shape is a SwiftASB-supported way for clients to ask Codex-owned services for workspace/worktree identity, branch/status facts, and safe handoff points, without committing machine-local paths or turning SwiftASB into a Worktrunk clone. Richer local file-write, repository-root, and working-tree status enrichment should live behind a separate optional app-access layer where a consuming macOS app can report user-granted directory access or pass a security-scoped bookmark, following Apple's sandbox model instead of treating local disk access as an implicit SwiftASB capability.
Plan command-execution-backed Git and GitHub actions for consuming apps that want Codex-like repository operations through SwiftASB. The first useful shape should route explicit user-reviewed actions through installed git and optional gh binaries when available, keep command output and approval decisions observable, and reuse the app-access/perms model instead of silently expanding filesystem authority.
Explore a custom approval auto-reviewer after the answerable server-request model is stable enough to distinguish advisory review from action approval. The first useful slice should classify approval requests and produce review recommendations; automatically answering requests should wait for an explicit policy model and tests that prove dangerous actions stay user-controlled.
Treat attestation as an internal auth/trust-adjacent request until a consumer workflow proves it should be public. In the schema, requestAttestation opts the client into attestation/generate requests, whose response is only an opaque token; SwiftASB should avoid inventing semantics beyond handing that token to the app-server path that requested it.
Keep realtime routes in the backlog until a concrete live-collaboration consumer needs them.
Keep search as a SwiftASB-owned/local-app concern for now. The likely path is Core Data for stored thread and item facts plus SearchKit-backed indexing for transcript and artifact search, with upstream fuzzy file search promoted only if its schema grows a stable cursor and result contract.
Explore direct local Codex thread storage as an opt-in acceleration path for thread inventory and evidence hydration, not as a replacement for the app-server lifecycle API. The first SwiftASB design pass should use version-gated read-only SQLite metadata reads, lazy JSONL evidence loading, private-text redaction by default, and app-server fallback whenever the local storage shape is missing or incompatible.
Finish the next descriptor increment beyond the current list, history, and recent-activity descriptors: broader public cursor semantics, any selection-centered reads that become necessary, and later search-hit hydration.
Keep tuning RecentTurns, RecentFiles, and RecentCommands after v1 as real UI usage teaches better calibration. The v1 review keeps the separate turn/file/command companions, current cache-policy names and defaults, selection/visibility protection, slimming behavior, and rehydration model as stable enough; remaining work is calibration and richer previews, not proving the model exists.
Keep future Codex CLI schema additions classified before public promotion: excludeTurns remains public on resume/fork request models because it directly supports the existing paged history model; permission-profile families stay internal until SwiftASB owns a deliberate public permission model; hooks, models, MCP status, MCP resource reads, thread goals, and guardian denied-action approval now have internal or public paths to build from; realtime, upstream fuzzy file search sessions, marketplace mutations, account-management families, thread settings, injected items, and config writes still need promotion decisions.
Flesh out archive-aware retention and eviction beyond the current list-driven archive-state drift correction.
Add any sharper binary-discovery diagnostics we want alongside the current-reviewed compatibility window before a broader compatibility release.
Revisit whether a convenience run(...) API is earned only after the lower-level lifecycle has more production mileage.

Current Patch Release Slice

This slice records the v1.7.4 patch release prep. Its job is to ship the first usable ASBSwiftUI components, record the immediate coverage audit, and turn the audit findings into follow-up work without widening the core app-server API boundary.

Planned for v1.7.4

Add the first real ASBSwiftUI component surface. Decision: ASBThreadSidebar wraps the AppKit-backed source-list renderer, while ASBAgendaPanel and ASBDashboardPanel render light current-state snapshots natively in SwiftUI. The old scaffold-only module marker is gone.
Add package tests for the new SwiftUI component inputs. Decision: ASBSwiftUITests now covers the public snapshots and intent handlers accepted by the new SwiftUI components, while ASBAppKitTests continues to cover the underlying sidebar view adapter behavior.
Add high-impact README and maintainer-plan docs for the new UI products. Decision: the README now shows the ASBPresentation, ASBAppKit, and ASBSwiftUI products plus a compact component usage example, and the presentation UI plan marks Slice 5 complete.
Run a SwiftPM test coverage audit before release. Decision: swift test --enable-code-coverage passed on 2026-06-14. The source-only coverage report, excluding .build, generated wire, and test files, reported 78.46% line coverage. The all-file report reported 78.17% line coverage. These numbers are directional rather than a release gate because SwiftUI body coverage stays low in ordinary package tests unless a renderer or preview harness actually evaluates view bodies.
Follow up on coverage findings after the patch release. Action: add renderer-focused tests for ASBSwiftUI display helpers and view state once the first consumer usage clarifies which labels, statuses, and action affordances are stable enough to test directly. Action: add more presentation projection tests for agenda, dashboard, timeline, and recent-activity variants instead of relying only on pure value construction. Action: add targeted transport/error/workspace edge tests for the lower coverage files that still affect operator-facing diagnostics: CodexTransportError, CodexWorkspace, CodexAppServerTransport, and CodexErrors. Action: keep generated-wire coverage out of the goal because generated scaffolding remains internal and is validated by schema generation plus protocol mapping tests.
Run the full release-branch validation set before tagging v1.7.4. Required: swift build, swift test, swift test --enable-code-coverage, bash scripts/repo-maintenance/validate-all.sh, uv run pytest from Tools/AgentSB, git diff --check, and scripts/run-live-codex-release-gate.sh.

Previous Patch Release Slice

This slice records the v1.7.3 patch release prep. It does not widen the public SwiftASB API boundary. Its job is to keep SwiftASB aligned with the latest reviewed Codex CLI 0.139.x app-server schema while preserving the generated wire layer as internal scaffolding until a stronger public ownership model is earned for any newly added schema families.

Planned for v1.7.3

Classify the Codex CLI v0.139.0 schema diff before promotion. Decision: refresh the promoted v2 lifecycle batch, update the reviewed CLI window to 0.139.x, promote the optional mcpServer/startupStatus/updated.threadId field internally, and keep that new MCP status target out of public API until SwiftASB owns a deliberate thread-scoped MCP diagnostic model.
Update the reviewed compatibility window, generator defaults, and binary diagnostics for Codex CLI 0.139.x.
Add checked-in v1.7.3 release notes that describe the schema refresh, public-boundary decision, migration notes, and verification performed.
Run the full release-branch validation set before tagging v1.7.3. Decision: swift build, swift test, bash scripts/repo-maintenance/validate-all.sh, uv run pytest from Tools/AgentSB, git diff --check, and scripts/run-live-codex-release-gate.sh all passed on 2026-06-13.

Shipped in v1.7.1

Refresh the promoted generated v2 lifecycle wire snapshot from the v0.137.0 schema dump.
Update the reviewed Codex CLI compatibility window to 0.137.x across README, maintainer docs, release-boundary notes, and binary diagnostics.
Keep remote-control pairing/client-management and skills extra-roots request families internal until their permission, auth, pairing, and filesystem-root ownership model is deliberately designed.
Preserve enterprise-managed config layer metadata in the public config diagnostic model without promoting broader enterprise policy semantics.
Keep richer turn/thread context fields such as runtime workspace roots, environments, additional context, structured output schemas, and rollout-path forking probe-first instead of promising stable public request parameters in this patch.
Exercise deterministic Swift and AgentSB tests before tagging the patch.

Follow-Up Probes

Investigate the Codex GUI remote-control pairing/auth setup and decide whether SwiftASB should expose a public app-server auth-flow helper, a diagnostics-only view, or no public surface yet.
Probe skills/extra_roots/set behavior and decide whether it belongs in a future extension-management family, a repo/app-access policy surface, or a private maintainer-only helper.
Probe turn-start hydration fields, especially runtime workspace roots, environments, additional context, and structured output schemas, before widening TurnStartRequest.
Treat rollout-path forking as unstable until live side-chat behavior and direct local thread-storage plans agree on a safe read/fork boundary.

V1 Readiness Checklist

This checklist records the work that made SwiftASB ready for the v1.7.1 tag. The goal was not to make every possible app-server feature public before v1. The goal was to make the supported lifecycle honest, durable, well documented, and intentionally shaped.

Release Boundary Decision

Decide whether the shipped interactive lifecycle is a credible v1 surface: thread start/resume/fork/read/list, turn start/control, typed progress, approvals, elicitation, diagnostics, local history hydration, recent observables, rollback, and app-wide model/MCP snapshots. Decision: yes. Treat v1 as the first stable Swift-native client surface for the core Codex app-server lifecycle, not as a promise that every generated app-server feature is public.
Explicitly classify each remaining Milestone 5 gap as v1 blocker, v1 docs-only note, or post-v1. Decision: the remaining unpromoted generated families listed below are post-v1 unless a real consumer workflow reclassifies one before the v1 API freeze.
Keep guardian denied-action approval internal for v1. Decision: post-v1 at the v1 boundary. It is now internally promoted through the existing approval-needed model so SwiftASB can answer auto-review denial approvals without inventing a parallel consumer flow.
Keep marketplace upgrade, account-management variants, richer MCP progress, external-agent config import, structured patch rendering, and mixed recent activity out of v1. Decision: post-v1. The v1 surface should not widen just because the generated schema contains those families.
Decide whether the current rollback behavior is enough for v1. Decision: yes. CodexThread.rollbackLastTurns(...) may be stable for v1 without preserving full removed-turn payloads as forensic archive data; richer rollback forensics are post-v1.

Post-V1 Deferred Items

These are intentionally outside the v1 promise unless a concrete consumer workflow earns them in a later feature release.

Public API Curation

Inventory every public type, initializer, method, enum case, and default argument under Sources/SwiftASB/Public/. Decision: docs/maintainers/v1-public-api-symbol-inventory.md now records the SwiftPM public symbol graph for the v1 freeze, while docs/maintainers/v1-public-api-audit.md remains the durable decision checklist.
For each public symbol, decide whether it is stable for v1, should be renamed before v1, should become internal, or should move behind a narrower owning type. Progress: the access-control audit is now explicit. The first tightening pass removes the stale public SwiftASB namespace placeholder and narrows app-server-authored interactive request and passive diagnostic payload constructors so the package no longer exports template-era, request fabrication, or diagnostic-emission surfaces that consumers should not depend on. The second pass also removes marketplace-adjacent model upgrade fields from the public model-list shape while keeping the generated wire decode internal. Decision: completed in docs/maintainers/v1-public-api-audit.md and the regenerated symbol inventory. The final pre-v1 public graph records 1,107 public/open symbols after the v0.128 sandbox-field cleanup, with no generated CodexWire... names exposed through the SwiftASB product.
Audit access control symbol-by-symbol before docs/examples: remove stale public placeholders, keep observable snapshots read-only unless callers need to construct them, keep request/response values constructible where consumers need to send or test them, and regenerate the public symbol inventory after each tightening pass. Decision: observable companion state has been reviewed. Companion construction stays internal, presentation state is read-only or public private(set), and the mutable public companion fields are limited to caller-owned UI inputs. App-server-authored request identifiers and passive diagnostic payload constructors remain internal, while request and response values that callers need to send or test remain constructible.
Review CodexAppServer, CodexThread, CodexTurnHandle, Dashboard, Minimap, RecentTurns, RecentFiles, RecentCommands, history-window helpers, diagnostics, approval, elicitation, model, MCP, and thread-management surfaces as one connected API rather than as separate shipped slices. Decision: keep the connected v1 owner model. CodexAppServer remains the root subprocess owner and low-level app-wide operation surface; CodexThread remains the high-level conversation handle for thread-scoped actions, history, request routing, and SwiftUI companions; CodexTurnHandle remains the active-turn control and completion surface. Dashboard, minimap, recent-turn, recent-file, and recent-command companions are current-state or bounded-history mirrors, not alternate protocol owners. Diagnostics remain passive events, and model/MCP reads remain app-wide snapshots.
Split any remaining oversized public source files where the split removes real navigation cost or clarifies ownership boundaries. Decision: no additional pre-v1 split is needed. The remaining large public actor source carries runtime entrypoints and internal mapping work; the consumer-facing request, result, model, MCP, thread-management, observable, diagnostics, approval, and elicitation values already live in focused files.
Tighten public names and parameter labels so callers can understand the operation without reading generated-wire terminology. Decision: the final connected-surface pass keeps the current owner and naming model for v1. The first field/default/enum vocabulary pass corrected the public execution-policy approval response case to acceptWithExecPolicyAmendment(_:), matching the already-corrected proposedExecPolicyAmendment request field while keeping the private app-server wire spelling for compatibility.
Review default arguments for compatibility risk before v1, especially cache-policy defaults, history limits, binary-discovery defaults, and request options that mirror upstream Codex behavior. Decision: the audit now classifies defaults as compatibility promises. The first source-level documentation pass now covers the main default-bearing public initializers and methods, including nil app-server request omissions, SwiftASB local-history/UI page sizes, cache-policy derivation, and explicit response/update safety defaults.
Make sure public stream semantics are consistent: when streams buffer, when they finish, whether they throw, and which owner is responsible for answering or observing each event. Decision: documented in source comments, DocC, and the v1 audit. Thread and turn lifecycle streams are the canonical public event surfaces; diagnostics are passive app-wide signals; observable companions are current-state mirrors over live feeds rather than replayable logs.

Documentation And Examples

Update stale release references after the v1.7.1 release. Decision: README named v1.7.1 as the current released baseline and no longer described the package as early development. The v1.7.3 patch prep updates the current release reference again.
Finish DocC symbol comments for the supported lifecycle, not just the conceptual articles. Decision: the source-level documentation pass now covers CodexAppServer, CodexThread, and CodexTurnHandle lifecycle entrypoints, defaults, response routing, completion handoff, diagnostics, and history access, plus the stable public value types for model, MCP, thread-management, approval, elicitation, diagnostics, compatibility, and app-server bootstrap surfaces.
Add copy-pasteable DocC walkthroughs for: starting and initializing an app-server, starting a thread and turn, observing turn progress, answering an approval request, handling diagnostics, reading recent history, and using recent file/command companions in a SwiftUI view model. Decision: covered by the startup, progress/approval, diagnostics/history, and SwiftUI observable companion walkthroughs in Sources/SwiftASB/SwiftASB.docc/.
Keep README product-facing and concise, but make sure it names every v1-supported surface that a new consumer is expected to trust. Decision: README stays consumer-facing and names the supported app-server lifecycle, SwiftUI observable companions, diagnostics, model/MCP snapshots, local history, live probes, and the v1 compatibility boundary without duplicating maintainer workflow details.
Keep CONTRIBUTING.md focused on contributor workflow, generated schema refreshes, live-test flags, validation commands, release workflow, and temporary compatibility-shim policy. Decision: CONTRIBUTING remains the maintainer workflow home for local validation, schema generation, opt-in live tests, release steps, and temporary compatibility cleanup policy.
Run and keep clean the Xcode DocC validation path before the v1 tag. Decision: xcodebuild docbuild -scheme SwiftASB -destination generic/platform=macOS -derivedDataPath tmp/xcode-docc/DerivedData passed on 2026-05-02 after the walkthrough and source-comment pass.

Test And Runtime Confidence

Keep default swift test deterministic and local, with fake transport coverage for public API behavior. Decision: the default deterministic suite passed on 2026-05-02 with 147 Swift Testing tests; live Codex tests remained skipped unless their explicit environment flags or wrapper scripts were used.
Keep live Codex CLI tests opt-in, because the installed CLI and prompt behavior remain external local dependencies. Decision: live probes remain opt-in through SWIFTASB_ENABLE_LIVE_CODEX_* flags, focused wrapper scripts, and the umbrella scripts/run-live-codex-integration-tests.sh runner.
Run the opt-in live probes before v1 and record any observed behavior changes in ROADMAP.md or maintainer docs. Decision: the 2026-05-02 live confidence run passed the approval probe, multi-turn file mutation scenario, and rollback scenario against codex-cli 0.128.0; observed approval behavior changes are recorded in Live App-Server Findings.
Resolve or deliberately narrow the subprocess timing flake where child process exit can sometimes surface as unexpectedEndOfStream with retained stderr instead of processTerminated. Decision: narrowed to the stable consumer contract. The subprocess-edge test now accepts either process termination or stdout EOF when the same fake child process exits after writing stderr, while still asserting that the retained stderr ring contains the expected last 20 lines.
Decide whether the existing multi-turn live file-mutation scenario is enough live coverage for v1, or whether v1 needs another deterministic real app-server scenario. Decision: enough for v1 when paired with the deterministic raw command approval probe and rollback probe. Additional permissions/MCP server-request families are post-v1 expansion work, not a v1 blocker.
Confirm approval/server-request coverage still proves the request, response, serverRequest/resolved, and terminal-turn path through the real app-server with a mock Responses provider. Decision: scripts/run-live-codex-approval-probe.sh passed on 2026-05-02, including the deterministic raw command approval path through real app-server request delivery, SwiftASB response, serverRequest/resolved, command completion, follow-up mock Responses call, and terminal turn/completed.

Compatibility And Generated Wire

History And Observable Companions

Review RecentTurns, RecentFiles, and RecentCommands cache-policy names, defaults, selection behavior, slimming behavior, and rehydration semantics before v1. Decision: keep the separate companion families for v1. RecentTurns keeps named chatUI, inspector, and historyRail presets, while RecentFiles and RecentCommands keep automatic page-size-derived policies until real UI usage justifies more presets. Selection and visible-ID inputs remain caller-owned UI hints; presentation snapshots stay read-only. Payload and item slimming remains a cache-residency detail, and protected slimmed entries rehydrate from local history when selected or visible. Unsafe numeric cache-policy inputs are normalized consistently across all three companion families.
Decide whether archive-aware retention and eviction is a v1 blocker or a documented post-v1 history-store enhancement. Decision: post-v1. The v1 local-history promise is current non-archived cache use plus archive-state drift correction, not a durable archived-thread retention contract.
Decide whether broader public cursor semantics, transcript search, or richer non-UI history query helpers are post-v1. Decision: post-v1. Keep the current local HistoryWindow reads plus centered turn/item windows as the v1 non-UI surface; do not expose a broader public cursor or transcript-search contract before the local completeness model has more production mileage.
Keep RecentActivity out of v1 unless a real consumer workflow needs a mixed timeline; the current decision is to keep file, command, and turn companions separate. Decision: keep RecentTurns, RecentFiles, and RecentCommands separate for v1. A mixed feed remains post-v1 unless a concrete app workflow proves it improves scanning more than it muddies the ownership model.
Confirm history reads prefer local data only when local completeness is trustworthy, and still expose upstream failures through low-level APIs where callers need them. Decision: recent observables and local window helpers prefer the local history store only after SwiftASB has useful local completeness, and they degrade to empty local-only startup for known ephemeral or pre-materialized live history responses. Low-level CodexAppServer.listThreadTurns(...) remains the direct app-server paging surface and still reports upstream protocol failures.

Packaging And Release Verification

Confirm Swift Package Index listing and DocC rendering after the latest public tag is indexed. Decision: completed on 2026-05-06. Swift Package Index lists gaelic-ghost/SwiftASB, selects v1.1.1, exposes a Documentation link, shows compatibility/build results, and reports Package ID 9B5839D9-9551-473F-A939-841534A3FC55.
Run swift test, git diff --check, and bash scripts/repo-maintenance/validate-all.sh before the v1 release branch. Decision: swift build, swift test, bash scripts/repo-maintenance/validate-all.sh, and git diff --check passed on the release/v1.0.0 branch on 2026-05-02.
Run Xcode DocC validation before the v1 release branch. Decision: xcodebuild docbuild -scheme SwiftASB -destination generic/platform=macOS -derivedDataPath tmp/xcode-docc/DerivedData passed on the release/v1.0.0 branch on 2026-05-02 and on the release/v1.0.1-prep branch on 2026-05-02.
Decide whether another targeted v0.9.x patch release is needed before v1.7.1, or whether the remaining work should go straight into the v1 release branch. Decision: no additional v0.9.x patch is needed. The remaining work should go straight into the v1.7.1 release branch.
Prepare v1 release notes with explicit sections for public surface, intentionally internal surfaces, compatibility window, migration notes, validation performed, and known post-v1 work. Decision: the v1 release notes draft below is the source text for the GitHub release object.

V1 Release Notes Draft

Public Surface

CodexAppServer is the root owner for starting/stopping the local Codex app-server subprocess, initializing the session, starting/resuming/forking threads, paging stored threads and turns, listing models, listing MCP server statuses, and reading passive diagnostics.
CodexThread is the conversation-scoped owner for starting turns, observing thread events, naming threads, updating thread metadata, compacting context, rolling back trailing turns, reading local history windows, and creating SwiftUI-friendly observable companions.
CodexTurnHandle is the active-turn owner for observing turn events, answering approval and elicitation requests, steering text, interrupting work, reading the minimap, and completing into a sealed turn snapshot.
SwiftUI companion surfaces are stable for v1: Dashboard, Minimap, RecentTurns, RecentFiles, and RecentCommands.
Public diagnostics cover runtime warnings, guardian warnings, config warnings, deprecation notices, MCP-server status changes, remote-control status changes, model reroutes, and model-verification events through hand-owned Swift values.

Intentionally Internal Surfaces

Generated CodexWire... models remain internal scaffolding and are not part of the public Swift API.
Broader app-server families remain post-v1 until their consumer workflows are clearer, including guardian denied-action approval, plugin sharing and remote marketplace management, standalone process control, Windows sandbox readiness, remote-control management, thread goals, realtime, fuzzy file search, hook mutation, external-agent config import, richer MCP progress, and structured patch previews.
A one-shot run(...) convenience API is intentionally deferred until the lower-level lifecycle has more production mileage.

Compatibility Window

The compatibility promise is intentionally narrow while app-server schema is moving quickly: reviewed support for current Codex CLI 0.142.x plus the latest prior minor 0.141.x when feasible.
SwiftASB discovers codex from an explicit executable URL, PATH, common Homebrew locations, or the npm global prefix, and exposes startup diagnostics through cliExecutableDiagnostics().
Future Codex CLI schema dumps must be classified before generated shapes are promoted to public or observable behavior.

Migration Notes

Existing v0.9.x consumers should update the SwiftPM dependency to from: "1.8.1" once the tag is published.
The v1 API surface has removed stale pre-v1 compatibility shims and phantom fields that no longer exist in the reviewed v0.128.0 schema.
Same-thread overlapping turns are rejected client-side with CodexAppServerError.invalidState; use separate threads for concurrent turns.
Prompt-driven approval behavior remains runtime-dependent. Deterministic approval regression coverage uses the real app-server with a local mock Responses provider.

Validation Performed

swift build
swift test
bash scripts/repo-maintenance/validate-all.sh
git diff --check
xcodebuild docbuild -scheme SwiftASB -destination generic/platform=macOS -derivedDataPath tmp/xcode-docc/DerivedData
scripts/run-live-codex-approval-probe.sh
scripts/run-live-codex-file-scenario.sh
scripts/run-live-codex-rollback-scenario.sh

Known Post-V1 Work

Keep an eye on future Swift Package Index builds after compatibility-window or DocC changes; the v1.1.1 listing and documentation link are live, and v1.8.1 should be rechecked after the patch tag is indexed.
Add broader live server-request coverage for permissions and MCP elicitation if those become stronger public runtime guarantees.
Continue tuning recent companion cache calibration, richer file previews, archive-aware retention, and rollback forensic archival.

Security Audit Follow-Up

The repository-wide Codex Security audit on 2026-05-11 found no critical or high-severity issues in the reviewed SwiftASB surfaces. It did identify two medium-severity protocol/policy hardening tasks and several deferred audit rows that should stay visible until closed.

Audit bundle: docs/security-audits/82ea49d_20260511T213956-0400/report.md.

Fix JSON-RPC numeric ID narrowing. CodexRPCEnvelope.parseRequestID(_:) currently checks whole-number shape and then uses NSNumber.intValue. Replace that with a range-preserving conversion or explicit out-of-range rejection, then add boundary tests around 32-bit and platform Int limits.
Fix fail-open network-policy amendment mapping. CodexProtocolNetworkPolicyAmendment.publicValue currently maps unknown wire action strings to .allow. Preserve unknown values or fail closed so approval UI and app logic cannot misrepresent malformed or future actions as permission-widening approvals.
Add a focused resource-limit review for stdio line framing and JSON materialization. LineDelimitedDataBuffer and the JSON-RPC envelope path currently do not have a documented line-size cap. The audit deferred this because the peer is the local Codex app-server, but bounded framing would make the transport contract clearer.
Complete a focused ThreadHistoryStore audit. The audit identified local command, file, thread, and token history as sensitive local metadata but did not close a full line-by-line persistence review.
Complete generated-wire parser/codec review when the upstream wire layer next changes materially. Generated models remain internal, but schema refreshes should keep parser and conversion assumptions visible before public mapping expands.

Live App-Server Findings

The current live Codex CLI probes have found real app-server behavior that should shape SwiftASB rather than stay as one-off test knowledge.

thread/turns/list rejects ephemeral threads. Recent observable startup now treats that known response as an empty local-only initial view instead of surfacing raw protocol text.
thread/turns/list also rejects a non-ephemeral thread before the first user message materializes stored thread history. Recent-turn, recent-file, and recent-command observable startup now treats that known response as an empty local-only initial view. Unexpected thread/turns/list failures still remain failures.
Approval prompts remain nondeterministic for prompt-driven live tests. Live scenarios should accept approval requests when they surface, but durable assertions should focus on terminal turn status, observable call snapshots, and filesystem or history outcomes.
Upstream Codex app-server coverage proves the JSON-RPC server-request path is deterministic when the model stream is controlled. Their v2 app-server tests trigger CommandExecutionRequestApproval, FileChangeRequestApproval, PermissionsRequestApproval, and MCP elicitation requests with a mock Responses provider and then answer the JSON-RPC request before waiting for serverRequest/resolved. SwiftASB should mirror that shape with a local mock Responses server instead of treating prompt-driven live approval behavior as the only possible real-CLI test path.
For ordinary command and file-change approvals, upstream uses mocked Responses tool-call events such as shell command and apply-patch calls under approval_policy = "untrusted" and sandbox_mode = "read-only" to force app-server request emission. For request-permissions coverage, upstream enables [features] request_permissions_tool = true and emits a request_permissions tool call. That gives SwiftASB a reproducible protocol path while still launching the real installed codex app-server.
SwiftASB now has opt-in real-app-server coverage for the deterministic command approval path: an isolated CODEX_HOME, local mock Responses provider, command item, waitingOnApproval thread state, raw item/commandExecution/requestApproval JSON-RPC delivery, SwiftASB's response, serverRequest/resolved, command completion, and final turn/completed. The root cause of the former gap was local: the JSON-RPC envelope parser treated numeric request id 0 as a boolean because JSONSerialization bridges JSON numbers through NSNumber. SwiftASB now checks CoreFoundation boolean identity before accepting numeric request IDs. Upstream app-server protocol structs are intentionally JSON-RPC-like rather than strict JSON-RPC 2.0 and do not send or expect a jsonrpc version member, so SwiftASB should keep generated outbound envelopes aligned with that shape unless upstream changes the wire contract.
approvalPolicy: .onRequest plus approvalsReviewer: .user does not force approval requests for workspace-write command, file-create, or file-edit turns in the current live runtime. The approval/server-request probe records those turns as completed command calls with no accepted approval kinds.
Current v1 confidence run, 2026-05-02 with codex-cli 0.128.0: the isolated live-test Codex config using approval_policy = "untrusted", approvals_reviewer = "user", sandbox_mode = "workspace-write", and an untrusted project now produces clean typed approval flow for command read, file create, file edit, and a read-only sandbox write candidate. SwiftASB accepted those approvals through the public surfaces, each turn completed, and the report recorded concrete command/file-edit call kinds plus expected file outcomes. This supersedes the earlier timeout finding from the exploratory .onRequest/strict-probe attempts.
scripts/run-live-codex-approval-probe.sh is the preferred exploratory validation for approval/server-request candidates. It opts into the live probe and writes live-approval-server-request-probe.json under tmp/live-codex-reports/ so maintainers can inspect attempted Codex config, observed call kinds, approval kinds, terminal text, file outcomes, and probe errors after a real CLI run.
scripts/run-live-codex-file-scenario.sh is the preferred validation for the create/edit/delete path. It opts into the live file scenario and writes a JSON diagnostic report under tmp/live-codex-reports/ so maintainers can inspect observed call kinds, approval kinds, recent-file snapshots, and recent-command snapshots after a real CLI run.
Test coverage audit, 2026-04-28: protocol encode/decode tests should assert the app-server's JSON-RPC-like envelope shape directly. The upstream protocol does not include jsonrpc = "2.0" on requests, notifications, or responses, and initialized has no params field. Keep the default fake-transport tests responsible for public-client routing and history behavior, and keep opt-in live tests responsible for installed-runtime behavior. Raw command-approval request delivery plus serverRequest/resolved is now covered through the real app-server; the remaining live approval findings are prompt-driven runtime behavior and additional server-request families.
Test coverage audit, 2026-05-02: the default deterministic suite now has 147 Swift Testing tests and directly covers the public CodexAppServerError description/wrapping contract in addition to the existing protocol, transport, public-client, observable companion, generated-wire, diagnostics, approval, elicitation, model, MCP, thread-management, and history coverage. The remaining intentional gap is not local unit coverage; it is live breadth for future server-request families such as permissions and MCP elicitation when SwiftASB chooses to promote those as stronger public runtime guarantees.
Test coverage audit, 2026-05-06: deterministic promoted-schema coverage now exercises CodexFS.FileDiscoveryQD depth, hidden-entry, no-match, and fuzzy ranking behavior over app-server fs/readDirectory fixtures; richer CodexConfig and CodexAppServer.CodexExtensions optional fields; and thread/resume plus thread/fork workspace-permission selection encoding.

Test Coverage Gap Register

Keep this register current after 1.0.0; tests are part of the public contract because consumers are wrapping a fast-moving local runtime.

Approval/server-request completion now has deterministic SwiftASB-owned coverage and a focused live app-server completion probe. Fake-transport public-client tests prove typed approval events surface through CodexTurnHandle, respond(...) writes the expected JSON-RPC result, serverRequest/resolved clears the route, and wrong-surface, wrong-kind, already-resolved, and wrong-thread responses fail with descriptive errors. The opt-in live raw mock-Responses probe now proves the real app-server can reach a command item plus waitingOnApproval, deliver an answerable item/commandExecution/requestApproval request with numeric id 0, accept SwiftASB's response, emit serverRequest/resolved, complete the command, make the follow-up mock Responses call, and finish the turn.
Malformed server-originated request coverage now covers missing-params notifications, unknown server-request methods, unsupported request ID types, malformed command approval, malformed file-change approval, malformed permissions approval, malformed tool user input, malformed MCP elicitation, route disappearance after resolution, wrong response surfaces, and request/response IDs routed through the wrong active thread.
Live history coverage now includes an opt-in mock-Responses wrapper proving that a real non-ephemeral stored thread can complete harmless text-only turns, then read those turns back through thread/read and page them through thread/turns/list.
Transport edge coverage now covers both envelope/line-buffer parsing and real subprocess failure modes. The default tests cover versionless app-server envelopes, optional tolerated jsonrpc fields, boolean/fractional/object request IDs, notifications without params, partial line draining, duplicate pending request IDs, pending response failure when the child process exits, recent-stderr retention, malformed stdout followed by a later valid response, and late duplicate response lines after a pending request has already been fulfilled.
The subprocess-exit versus stdout-end ordering is intentionally tested by stable consumer contract now: pending responses must fail and retain recent stderr, whether the child-process race surfaces as process termination or stdout EOF first.
Public app-server error coverage now directly asserts that invalid-state reasons pass through unchanged and that internal transport/protocol failures wrap into descriptive operation-scoped CodexAppServerError values.
Schema drift guardrails now include generated-wire fixture payloads for thread/read, thread/turns/list, command-execution thread items, active thread status flags, additive thread fields, and serverRequest/resolved. Keep adding one fixture whenever a promoted schema family graduates from generated-internal to public or observable behavior. The policy is: promotion from generated-internal to public or observable behavior must include at least one representative fixture in the same PR, including one additive unknown field when the upstream shape is expected to remain forward-compatible.
Promoted app-server surface coverage now includes deterministic request-shape assertions for skills/list, plugin/list, plugin/read, thread/resume, and thread/fork, plus representative optional-field decoding for app, skill, plugin, config layer, config origin, and file-discovery descriptors. Keep extending these deterministic fixtures before moving broader live runtime breadth into the release-gate matrix.

Live Testing Expansion Plan

Now that SwiftASB has a v1 public API, live testing is a release-maintenance surface. Its job is to prove the package still matches the installed Codex CLI when app-server behavior changes underneath the Swift API.

Release-Gate Live Probes

These are the small, high-signal live probes that should run before ordinary releases:

Consolidate the current release-gate probes behind scripts/run-live-codex-release-gate.sh.
Add a clearer umbrella live integration-test runner at scripts/run-live-codex-integration-tests.sh.
Keep startup, initialize, binary diagnostics, app-wide model/MCP snapshot, single-turn, and cross-thread coverage in the release-gate set when their runtime cost stays reasonable.
Keep deterministic command approval with a mock Responses provider in the release-gate set.
Keep the multi-turn create/edit/delete file scenario in the release-gate set.
Keep the disposable stored-thread rollback scenario in the release-gate set.

Release-gate probes should fail when SwiftASB's documented v1 contract is broken. They should stay small enough that maintainers can run them during release prep without turning every release into an exploratory runtime study.

Compatibility And Behavior Probes

These probes are observational and should write JSON reports. They should fail only when SwiftASB's documented contract breaks; otherwise behavior drift should be recorded in this roadmap or maintainer docs.

Approval-policy matrix: .never, .onRequest, .untrusted, and .granular.
Sandbox matrix: .readOnly and .workspaceWrite. Keep tightly isolated danger-full-access coverage out of the first matrix until the test workspace makes the risk clear.
Same-thread overlap probe, kept observational until upstream app-server semantics become independently routable.
Ephemeral and pre-materialized thread-history behavior probes.
Codex CLI version/support-window diagnostics probe that records the installed runtime, schema dump availability, and SwiftASB compatibility result.

Server-Request Family Probes

Every promoted answerable server-request family should have both deterministic fake-transport unit coverage and an opt-in real app-server probe when the real runtime can be driven with a mock Responses provider.

Permissions approval / request-permissions tool path.
Tool user input. Decision: deterministic fake-transport coverage proves public routing and response behavior, and the opt-in live server-request runner now drives the real app-server with a mock Responses request_user_input call in plan collaboration mode. The probe asserts item/tool/requestUserInput delivery, SwiftASB's JSON-RPC response, serverRequest/resolved, and terminal turn completion.
MCP server elicitation. Decision: deterministic fake-transport coverage proves public routing and response behavior. The opt-in live server-request runner keeps an app-connector MCP fixture in the release gate, but current Codex CLI behavior may complete the turn without routing that fixture to the MCP event stream. When the app-server emits the MCP tool call, the probe still asserts mcpServer/elicitation/request delivery, SwiftASB's JSON-RPC response, serverRequest/resolved, and terminal turn completion. The regular stdio MCP fixture remains available as an explicitly opted-in observational probe.
Guardian denied-action approval after SwiftASB owns a stable public model.
Model capability snapshot through CodexAppServer.readModelCapabilities().

Harness And Script Shape

Live tests should grow a shared harness instead of more one-off setup code. The harness should own temporary workspaces, isolated CODEX_HOME, Codex config generation, mock Responses provider startup, report writing, timeouts, cleanup, and optional workspace retention for debugging.

Planned script entrypoints:

scripts/run-live-codex-integration-tests.sh
scripts/run-live-codex-release-gate.sh
scripts/run-live-codex-behavior-matrix.sh
Add a focused mode or companion script for remaining answerable server-request families once tool-user-input and MCP elicitation probes are promoted into live coverage.

The live script surface should support these environment knobs consistently:

SWIFTASB_LIVE_CODEX_TIMEOUT_SECONDS
SWIFTASB_LIVE_CODEX_REPORT_DIR
SWIFTASB_LIVE_CODEX_KEEP_WORKSPACES=1
SWIFTASB_LIVE_CODEX_BIN=/path/to/codex

First Implementation Slice

The first post-v1 live-testing slice is the consolidated release-gate runner. It runs the currently proven high-signal probes in order: broad smoke coverage for startup, raw transport initialize/thread/turn, binary diagnostics, app-wide model/MCP/hook snapshots, thread-name mutation, single-turn, cross-thread, and same-thread behavior; deterministic approval/server-request coverage; the multi-turn file mutation scenario; and rollback. The permissions approval mock-Responses probe now covers the largest answerable server-request family gap. The umbrella live integration-test runner now gives maintainers one entrypoint for release-gate, focused, and full opt-in live coverage, with SWIFTASB_LIVE_CODEX_TIMEOUT_SECONDS available when a slower runtime needs a longer per-operation timeout.

Previous V1 Release Slice

This section records the release-hardening slice that produced the first interactive lifecycle release. Keep it as historical release-boundary context, not as the current maintainer priority.

Shipped in the v0.9.x lifecycle slice

Enough notification coverage that a consumer can build a multi-turn interactive flow without dropping to raw payloads.
Observable current-state companions for in-flight call activity and blocked thread state so UI consumers can show "what is happening right now" without replaying raw deltas themselves.
A written release boundary that says what is public, what stays internal scaffolding, and what is intentionally unsupported.
A maintainer-facing classification of generated notification families as public now, observable-only for now, or internal-only for now.
The first deliberate public thread-management expansion beyond thread/start, with thread/list, thread/read, thread/resume, thread/fork, and thread/turns/list now landed.
Version-compatibility guidance and baseline discovery diagnostics for the local Codex CLI runtime.
Protocol/event promotion required to support the current release boundary, with richer tool, file-edit, and MCP detail feeding companion observables rather than widening into raw generated public payloads.
A written and implemented boundary for recent completed turns: thread-scoped recent-turn observables for UI, plus explicit CodexTurnHandle.complete() for caller-owned sealed turn values.
Centered local history reads through windowAroundTurn(...) and windowAroundItem(...) before any broader cursor or transcript-search contract.
A v0.135.0 experimental schema compatibility pass has refreshed the staging generator, updated the Codex CLI compatibility window, promoted new thread-search wire types internally, and kept thread-search as a future public API decision while treating turn additional context, thread-scoped MCP status filtering, broader image detail values, and removed v2 config profiles as internal wire compatibility changes for now.
A v0.137.0 experimental schema compatibility pass has refreshed the staging generator again, updated the Codex CLI compatibility window, and promoted new remote-control pairing/client-management plus skills extra-roots wire types internally while leaving public API ownership for those request families as future design work.
A v0.138.0 experimental schema compatibility pass has refreshed the staging generator again, updated the Codex CLI compatibility window, and promoted account token usage, remote-control pairing status, turn moderation metadata, plugin app-template, encrypted-content, and response-item author/recipient wire changes internally while leaving public API ownership for those families as future design work.
A v0.139.0 experimental schema compatibility pass refreshed the staging generator again, updated the Codex CLI compatibility window, promoted an optional thread target on mcpServer/startupStatus/updated into the internal wire snapshot, and kept that field out of public diagnostics until SwiftASB defines a stronger thread-scoped MCP status model.
A v0.143.0 experimental schema compatibility pass refreshed the staging generator again, updated the Codex CLI compatibility window, promoted broader generated Sendable coverage, exposed the new sleep turn-item kind, kept deprecated multi-agent mode fields internal for compatibility, and typed external-agent config import completion internally without adding new public request or action surfaces.
API curation and DocC docs good enough that a Swift consumer can understand the supported package surface without reading maintainer notes, including walkthroughs for the primary v1 lifecycle jobs.

Remaining post-v1 follow-up

Complete the public API inventory and freeze decisions recorded in docs/maintainers/v1-public-api-audit.md.
Finish the targeted source-level symbol documentation skim for the supported lifecycle.
Keep default local tests deterministic, narrow or document the known subprocess timing flake, and run the opt-in live probes before the v1 tag.
Audit active compatibility shims and tie each removal trigger to the current reviewed Codex CLI support window.
Confirm Swift Package Index listing and DocC rendering after the latest public tag is indexed. Decision: completed on 2026-05-06 for v1.1.1.

Deferred By The V1 Release Boundary

A one-shot run(...) convenience API.
Broader sugar beyond startTextTurn(...).
Public exposure of generated wire models.
Expanding the public API just because the generated schema contains more message types.
Guardian denied-action approval until SwiftASB owns a stable request and response model for that control flow.
Marketplace upgrade and account-management variants, including provider-specific account families such as Amazon Bedrock.
Richer MCP progress detail beyond the current dashboard/minimap summaries.
External-agent config import surfaces.
Structured patch rendering for RecentFiles.
Broader history cursor semantics, transcript search, and richer non-UI history query helpers beyond the current local windows.
Archive-aware retention/eviction and rollback forensic archival of removed turn payloads.
A mixed RecentActivity feed; keep RecentTurns, RecentFiles, and RecentCommands as separate first-class surfaces for v1.
Treating the prompt-driven live approval-path probe as a deterministic release gate while that runtime repro remains non-deterministic.

Exit signal for this slice

This slice is done when a Swift consumer can:

start the app-server
initialize a session
start a thread
start a turn
observe meaningful thread and turn progress
respond to approval or elicitation requests
steer or interrupt an active turn through the public handle API
understand, from the docs alone, which lifecycle surfaces are supported today
understand which generated or protocol surfaces are intentionally not public yet

without needing raw JSON-RPC access or generated wire types.

Decisions Made For The First Interactive Lifecycle

Keep the current ownership model:
- CodexAppServer owns transport, protocol, fanout, and server-request routing.
- CodexThread remains the ergonomic thread handle.
- CodexTurnHandle remains the ergonomic turn handle.
Keep typed async streams as the canonical lifecycle surface.
Keep Dashboard and Minimap as current-state mirrors of typed public events, not as a second control path.
Use a stream-first model for approval and elicitation requests.
Keep ThreadItem activity stream-first, with observable companions mirroring only selected latest-state summaries when useful.
Keep RecentTurns, RecentFiles, and RecentCommands as separate public companions. Do not add a mixed RecentActivity surface for v1 because it would blur three already-clear consumer jobs.
Promote additional notification families by supported-release intent, not by schema breadth alone.
Keep public lifecycle failures unified under CodexAppServerError.
Defer a one-shot run(...) API until the lower-level interactive lifecycle is complete enough to hide honestly.
Do not add a CodexSession type at this layer; the package should keep connection ownership on CodexAppServer and conversation ownership on CodexThread.
Keep app-wide configuration, settings, and actions on CodexAppServer when they describe the shared app-server connection rather than one thread or one turn. CodexAppServer.Configuration remains local process-launch configuration, not a remote settings model.
Do not add a new top-level CodexApp, CodexSettings, or app-wide session owner for v1. Split CodexAppServer source files by responsibility during API curation if the file size gets in the way, but preserve one connection-wide public owner.
If reusable execution knobs need a shared public value type later, prefer a narrow thread-scoped shape such as CodexThreadDefaults instead of a new top-level owner or a vague global config wrapper.
Treat app-level defaults as inputs to new thread creation, and treat later user changes as persisted thread-scoped overrides so one thread's settings do not silently affect another.

Milestone 0: Package And Repo Baseline

Status

Completed

Scope

Establish the initial SwiftPM package, baseline guidance, and first smoke-testable public namespace.

Tickets

Create the SwiftPM library package scaffold.
Enable Swift 6 language mode.
Add repo-local guidance for package work.
Add a minimal public namespace and smoke-test coverage.
Add root ROADMAP.md so project planning has a durable home.

Exit Criteria

swift build passes.
swift test passes.

Milestone 1: Wire Model And Codegen Foundation

Status

Completed

Scope

Make the bundled Codex app-server v2 schema the repeatable generated-wire source of truth while keeping generated models internal.

Tickets

Decide that the bundled Codex app-server v2 schema is the primary generated-wire source of truth.
Build a repeatable derivation flow that turns the bundled schema into a quicktype-friendly root.
Patch dynamic JSON holes to CodexWireJSONValue.
Promote the generated v2 lifecycle batch into Sources/SwiftASB/Generated/CodexWire/Latest/.
Expand the generated v2 lifecycle batch to include a broader notification/event family rather than only the minimal bootstrap slice.
Keep CodexWireInitializeResponse hand-owned until the upstream v2 schema exposes it directly.

Exit Criteria

scripts/generate-wire-types.sh regenerates the staged wire layer successfully.
The promoted generated v2 batch compiles cleanly with the package.
The v1 generated batch is no longer required as a promoted compiled artifact.

Milestone 2: Stdio Transport And Typed Protocol Slice

Status

Completed

Scope

Build the internal subprocess transport and typed protocol helpers needed for the first initialize, thread, and turn lifecycle.

Tickets

Implement an internal stdio transport around codex app-server --listen stdio://.
Correlate JSON-RPC responses by request ID.
Fan out non-response inbound messages as raw server events.
Build typed protocol helpers for initialize, initialized, thread/start, and turn/start.
Add focused tests that prove envelope classification and protocol encode/decode behavior.

Exit Criteria

Transport and protocol layers are buildable and covered by Swift Testing suites.
Protocol errors are descriptive and carry method-specific context.
The package has a stable internal seam between transport and protocol responsibilities.

Milestone 3: Public Client Actor And First Lifecycle API

Status

Completed

Scope

Expose the first hand-owned public Swift API around startup, initialize, thread start, and turn start.

Tickets

Implement a public CodexAppServer actor that owns transport plus protocol.
Keep the public request and response models hand-owned and Swift-shaped.
Expose start(), stop(), initialize(...), startThread(...), and startTurn(...).
Enforce initialize-before-thread and initialize-before-turn lifecycle guards.
Map internal transport and protocol failures into public-facing CodexAppServerError.
Add deterministic public-client tests using an internal fake transport seam.

Exit Criteria

The public client can complete initialize, thread start, and turn start in tests.
The initialize handshake sends initialized automatically.
The public API does not expose generated CodexWire... types.

Milestone 4: Event Streams And Ergonomic Handles

Status

Completed

Scope

Shape the ergonomic thread and turn handles, event streams, and observable companions that make the package usable for interactive Swift clients.

Tickets

Exit Criteria

A started turn can emit at least one typed async event through a handle-owned stream.
CodexThread exists as a public ergonomic wrapper with a clear ownership model.
The documented concurrency model is explicit for both cross-thread and same-thread turn starts.
The remaining open questions for Milestone 4 are narrow enough that Milestone 5 can build on the current handles without likely reshaping them again.
Thread and turn handles plus their observable companions feel like the real public surface rather than transitional wrappers.

Milestone 5: Approvals, Richer Notifications, And Broader Protocol Coverage

Status

Completed

Scope

Promote the interactive request, richer notification, and live subprocess coverage needed for a credible first interactive lifecycle release.

Tickets

Exit Criteria

The repo has a deliberate answer for where approval requests, elicitation requests, and item-level activity belong in the public model.
The public API can represent the most important server-driven lifecycle events without dropping back to raw payloads.
Approval and user-input request handling has a deliberate public model.
The package covers a meaningful multi-turn interactive lifecycle rather than only the happy-path bootstrap, including thread management, diagnostics, approvals, local history hydration, recent observables, rollback, and live file-mutation coverage. Decision: richer MCP progress, guardian denied-action approval, external-agent import, patch previews, mixed recent activity, and broader history/search surfaces are post-v1 rather than Milestone 5 blockers.

Milestone 6: Public Docs, Examples, And Release Readiness

Status

Completed

Scope

Keep the package understandable, verifiable, and releasable for Swift consumers without requiring them to read generated wire code or maintainer chat history.

Tickets

Exit Criteria

A new consumer can understand what SwiftASB is, what it depends on, and how to use the first supported lifecycle slice.
The release boundary between public API, internal wire scaffolding, and unsupported protocol surfaces is explicit.
A new consumer can discover the supported interactive lifecycle, including approval handling if shipped, from docs and examples without reading tests or maintainer notes.
The roadmap can identify a credible v0.x release candidate instead of only an exploration phase.

Open Tickets

Backlog Candidates

History

2026-06-30: Refreshed the reviewed Codex CLI window to 0.142.x plus 0.141.x when feasible, promoted the v0.142.4 generated wire snapshot internally, exposed the new sleep turn-item kind, kept deprecated multi-agent mode fields internal for compatibility, and typed external-agent config import completion internally without adding new public request or action surfaces.
2026-06-13: Prepared the v1.7.3 release branch for the Codex CLI 0.139.x compatibility refresh, promoted the v0.139.0 generated wire snapshot internally, kept the new optional MCP status thread target out of public API, and cleared the full repo-owned live Codex release gate.
2026-06-09: Published v1.7.2 with the ASBPresentation foundation, first ASBAppKit thread sidebar view, and Codex CLI 0.138.x generated-wire refresh.
2026-06-09: Prepared the v1.7.2 release branch with the ASBPresentation foundation, first ASBAppKit thread sidebar view, and Codex CLI 0.138.x generated-wire refresh.
2026-06-06: Used the AgentSB schema-review and auto-apply-safe reports as the basis for the Codex CLI 0.137.x compatibility refresh, promoted the v0.137.0 generated wire snapshot internally, and kept new remote-control and skills extra-roots request families out of public API until their ownership model is designed.
2026-06-09: Used AgentSB schema check, dump, diff, and maintenance-draft reports for the Codex CLI 0.138.x compatibility refresh, promoted the v0.138.0 generated wire snapshot internally, and kept account token usage, remote-control pairing status, turn moderation metadata, plugin app-template, encrypted-content, and response-item author/recipient changes out of public API pending live behavior review.
2026-06-11: Refreshed the reviewed Codex CLI window to 0.139.x, promoted the v0.139.0 generated wire snapshot internally, and kept the new optional thread target on mcpServer/startupStatus/updated out of the public diagnostics surface pending a clearer thread-scoped MCP status design.
2026-06-05: Took AgentSB through an AI-enabled schema-report and auto-apply-safe shakedown, dumped local codex-cli 0.137.0 schemas with the existing script, and recorded follow-up work for CLI ergonomics, installed Codex version detection, Homebrew update checks, OpenAI/Codex docs enrichment, AI model policy, and patch execution.
2026-06-05: Integrated AgentSB with scripts/dump-codex-schemas.sh for installed Codex CLI drift checks, dump-if-newer schema acquisition, optional Homebrew outdated checks, explicit Codex Homebrew upgrade-and-dump mode, and explicit AI model selection for reports and evals.
2026-06-04: Added AgentSB maintainer automation planning, eval scaffolding, schema-diff reporting, local Codex thread-index prototype work, and a SwiftASB-specific direct local thread storage plan for future package work.
2026-06-04: Finished AgentSB's report-first maintainer loop with schema diff evidence in generated reports, maintain --draft, and classifier-gated maintain --auto-apply-safe for AgentSB-owned report artifacts only.
2026-04-25: Added Xcode docbuild DocC validation, Swift Package Index metadata, and warning-clean DocC links.
2026-04-25: Split README package-user guidance from contributor workflow in CONTRIBUTING.md.
2026-05-06: Marked the v1.1.1 SPI listing confirmed, closed the completed v1 milestone status drift, and moved the active maintainer priority to post-v1 query descriptors plus app-library grouping.
2026-05-06: Reprioritized the next post-v1 slice around broader app-server schema and protocol promotion before additional query descriptors, so sandboxed clients can rely on Codex-owned workspace and Git facts instead of SwiftASB filesystem inference.
2026-05-06: Promoted the first read-only app-server filesystem slice through CodexFS, covering fs/getMetadata, fs/readDirectory, and fs/readFile, and added thread/loaded/list for loaded runtime thread ids.
2026-05-06: Removed the older CodexThread local workspace-file helpers after CodexFS became the promoted app-server-routed filesystem namespace.
2026-05-06: Promoted filesystem watches, config reads, extension inventory, and thread goals through CodexFS, CodexConfig, CodexAppServer.CodexExtensions, and CodexThread goal APIs.
2026-05-06: Added recent-file and recent-command descriptors, and taught app-wide library grouping to use app-server Git origin metadata with cwd fallback.
2026-05-06: Promoted workspace permission-profile selections and runtime permission facts through CodexWorkspace, and exposed active permission profiles on thread sessions and handles.
2026-05-06: Promoted bounded file discovery and fuzzy file lookup through CodexFS.FileDiscoveryQD and CodexFS.discoverFiles(_:), keeping traversal on app-server fs/readDirectory while SwiftASB owns local ranking over returned entries.
2026-05-06: Expanded deterministic coverage for promoted file discovery, config, extension inventory, and workspace-permission request descriptors.
2026-05-07: Added UI-ready CodexFS.FileDiscoveryHit search metadata for match kind, matched file-name and relative-path character ranges, and stable ranking reasons.
2026-05-08: Added CodexWorkspace.WorktreeSnapshot so thread, session, and library snapshots expose a single app-server-owned cwd plus Git-facts value without inferring repository roots from local disk.
2026-05-08: Added post-v1 roadmap candidates for codex mcp-server support, a custom approval auto-reviewer, and a Worktrunk-based worktree system.
2026-05-08: Added stable CodexAppServer.Library.worktreeGroups, selected worktree/repository context, and repository/worktree thread filters for app-wide sidebars without changing the caller-selected visible grouping mode.
2026-05-08: Added a future optional macOS app-access layer for user-granted directory access and security-scoped bookmark handoff, keeping richer local repository and file-write enrichment separate from app-server-reported workspace facts.
2026-05-08: Added future command-execution-backed Git and GitHub actions through installed git and optional gh, scoped by explicit user-reviewed command intents and the app-access permission model.
2026-05-09: Added the feature permission policy implementation plan, shifting the next app-wide action work toward quiet read-only defaults, one-time mutation-category enablement, proactive Git observability, and human-readable mutation events.
2026-05-11: Added the first repository-wide Codex Security audit bundle and tracked follow-up hardening for JSON-RPC numeric ID parsing, network-policy amendment fail-closed behavior, transport resource limits, history-store sensitivity, and generated-wire parser review.

Uh oh!

FilesExpand file tree

ROADMAP.md

Latest commit

History

ROADMAP.md

File metadata and controls

Project Roadmap

Table of Contents

Vision

Product Principles

Current Feature Matrix

Milestone Progress

Current Maintainer Priority

Current Patch Release Slice

Planned for v1.7.4

Previous Patch Release Slice

Planned for v1.7.3

Shipped in v1.7.1

Follow-Up Probes

V1 Readiness Checklist

Release Boundary Decision

Post-V1 Deferred Items

Public API Curation

Documentation And Examples

Test And Runtime Confidence

Compatibility And Generated Wire

History And Observable Companions

Packaging And Release Verification

V1 Release Notes Draft

Public Surface

Intentionally Internal Surfaces

Compatibility Window

Migration Notes

Validation Performed

Known Post-V1 Work

Security Audit Follow-Up

Live App-Server Findings

Test Coverage Gap Register

Live Testing Expansion Plan

Release-Gate Live Probes

Compatibility And Behavior Probes

Server-Request Family Probes

Harness And Script Shape

First Implementation Slice

Previous V1 Release Slice

Shipped in the v0.9.x lifecycle slice

Remaining post-v1 follow-up

Deferred By The V1 Release Boundary

Exit signal for this slice

Decisions Made For The First Interactive Lifecycle

Milestone 0: Package And Repo Baseline

Status

Scope

Tickets

Exit Criteria

Milestone 1: Wire Model And Codegen Foundation

Status

Scope

Tickets

Exit Criteria

Milestone 2: Stdio Transport And Typed Protocol Slice

Status

Scope

Tickets

Exit Criteria

Milestone 3: Public Client Actor And First Lifecycle API

Status

Scope

Tickets

Exit Criteria

Milestone 4: Event Streams And Ergonomic Handles

Status

Scope

Tickets

Exit Criteria

Milestone 5: Approvals, Richer Notifications, And Broader Protocol Coverage

Status

Scope

Tickets