mirror of
https://github.com/pchuan98/codex.git
synced 2026-07-01 00:31:56 +08:00
jif
89ac3ec27c
## Why
CCA is moving toward a split runtime where the orchestrator may not have
a filesystem, while executors can expose preinstalled plugins and
skills. A thread therefore needs to select capabilities without asking
app-server or core to interpret executor-owned paths through the
orchestrator's filesystem.
The longer-term model is broader than executor skills:
- A plugin is a bundle of skills, MCP servers, connectors/apps, and
hooks.
- A plugin root can be local, executor-owned, or hosted by a backend.
- Components inside one plugin can use different access and execution
mechanisms. A skill may be read from a filesystem or through backend
tools; an HTTP MCP server can run without an executor; a stdio MCP
server or hook needs an execution environment.
- Core should carry generic extension initialization data. The extension
that owns a component should discover it, expose it to the model, and
invoke it through the appropriate runtime.
This PR establishes that architecture through one complete vertical:
selecting a root on an executor, discovering the skills beneath it,
exposing those skills to the model, and reading an explicitly invoked
`SKILL.md` through the same executor.
## Contract
`thread/start` gains an experimental `selectedCapabilityRoots` field:
```json
{
"selectedCapabilityRoots": [
{
"id": "deploy-plugin@1",
"location": {
"type": "environment",
"environmentId": "workspace",
"path": "/opt/codex/plugins/deploy"
}
}
]
}
```
The root is intentionally not classified as a "plugin" or "skill" in the
API. It can point at a standalone skill, a directory containing several
skills, or a plugin containing skills and other components. This PR only
teaches the skills extension how to consume it; later extensions can
resolve MCP, connector, and hook components from the same selection.
The platform-supplied `id` is stable selection identity. The location
says which runtime owns the root and gives that runtime an opaque path.
App-server does not inspect or canonicalize the path.
## What changed
### Generic thread extension initialization
App-server converts selected roots into `ExtensionDataInit`. Core
carries that generic initialization value until the final thread ID is
known, then creates thread-scoped `ExtensionData` before lifecycle
contributors run.
This keeps `Session` and core independent of the capability-selection
contract. The initialization value is consumed during construction; it
is not retained as another long-lived `Session` field.
### Executor-backed skills
The skills extension now owns an `ExecutorSkillProvider` that:
- resolves the selected environment through `EnvironmentManager`
- discovers, canonicalizes, and reads skills through that environment's
`ExecutorFileSystem`
- contributes the bounded selected-skill catalog as stable developer
context
- reads an explicitly invoked skill body through the authority that
listed it
- warns when an environment or root is unavailable
- never falls back to the orchestrator filesystem for an executor-owned
root
Skill catalog and instruction fragments have hard byte bounds, which
also bound them below the 10K-token per-item context limit. If a
selected executor skill has the same name as a legacy local skill, the
executor selection owns that invocation and the local body is not
injected a second time.
Existing local and bundled skill loading remains in place. Omitting
`selectedCapabilityRoots` therefore preserves current local-only
behavior.
## Current semantics
- Only environment-owned locations are represented in this first
contract.
- Roots are resolved by the destination extension, not by app-server or
core.
- An unavailable executor or invalid root produces a warning and no
capabilities from that root; it does not trigger a local-filesystem
fallback.
- Selection applies to a newly started active thread.
- MCP servers, connectors, and hooks beneath a selected plugin root are
not activated yet.
- Selection is not yet persisted or inherited across resume, fork, or
subagent creation. Existing local capabilities continue to behave as
they do today in those flows.
## Planned vertical follow-ups
1. **Hosted HTTP MCP:** add an extension-backed HTTP MCP source that
works without an executor, then replace the special-purpose MCP plugins
loader with that implementation.
2. **Executor MCP:** register and execute stdio MCP servers through the
environment that owns the selected plugin root.
3. **Backend skills:** add a hosted skill source whose catalog and
bodies are accessed through extension tools rather than a filesystem.
4. **Connectors and hooks:** activate those components through their
owning extensions, using the same selected-root boundary and
component-specific runtime.
5. **Durable selection:** define the desired-selection lifecycle,
persist it, and make resume, fork, and subagent inheritance explicit
rather than accidental.
6. **Local convergence:** incrementally route existing local plugin,
skill, and MCP loading through the same extension model while preserving
current local behavior.
Each follow-up remains reviewable as an end-to-end capability. The
platform selects roots, generic thread extension data carries the
selection, and the owning extension resolves and operates its component.
## Verification
Coverage added for:
- app-server end-to-end discovery and explicit invocation of a skill
inside an executor-selected plugin root
- exclusive invocation when a selected executor skill collides with a
local skill name
- executor filesystem authority for discovery, canonicalization, and
reads
- thread extension initialization before lifecycle contributors run
- stable executor catalog context, explicit invocation, context
rebuilding, hidden skills, and preserved host/remote catalog behavior
Targeted protocol, core-skills, skills-extension, core lifecycle, and
app-server executor-skill tests were run during development.
133 lines
4.1 KiB
TOML
133 lines
4.1 KiB
TOML
[package]
|
|
name = "codex-app-server"
|
|
version.workspace = true
|
|
edition.workspace = true
|
|
license.workspace = true
|
|
|
|
[[bin]]
|
|
name = "codex-app-server"
|
|
path = "src/main.rs"
|
|
|
|
[[bin]]
|
|
name = "codex-app-server-test-notify-capture"
|
|
path = "src/bin/notify_capture.rs"
|
|
|
|
[lib]
|
|
name = "codex_app_server"
|
|
path = "src/lib.rs"
|
|
doctest = false
|
|
|
|
[lints]
|
|
workspace = true
|
|
|
|
[dependencies]
|
|
anyhow = { workspace = true }
|
|
async-trait = { workspace = true }
|
|
base64 = { workspace = true }
|
|
axum = { workspace = true, default-features = false, features = [
|
|
"http1",
|
|
"json",
|
|
"tokio",
|
|
"ws",
|
|
] }
|
|
codex-analytics = { workspace = true }
|
|
codex-arg0 = { workspace = true }
|
|
codex-cloud-config = { workspace = true }
|
|
codex-config = { workspace = true }
|
|
codex-core = { workspace = true }
|
|
codex-core-plugins = { workspace = true }
|
|
codex-exec-server = { workspace = true }
|
|
codex-extension-api = { workspace = true }
|
|
codex-external-agent-migration = { workspace = true }
|
|
codex-external-agent-sessions = { workspace = true }
|
|
codex-features = { workspace = true }
|
|
codex-goal-extension = { workspace = true }
|
|
codex-guardian = { workspace = true }
|
|
codex-git-utils = { workspace = true }
|
|
codex-file-watcher = { workspace = true }
|
|
codex-hooks = { workspace = true }
|
|
codex-otel = { workspace = true }
|
|
codex-plugin = { workspace = true }
|
|
codex-shell-command = { workspace = true }
|
|
codex-skills-extension = { workspace = true }
|
|
codex-utils-cli = { workspace = true }
|
|
codex-utils-pty = { workspace = true }
|
|
codex-backend-client = { workspace = true }
|
|
codex-file-search = { workspace = true }
|
|
codex-chatgpt = { workspace = true }
|
|
codex-login = { workspace = true }
|
|
codex-image-generation-extension = { workspace = true }
|
|
codex-memories-extension = { workspace = true }
|
|
codex-web-search-extension = { workspace = true }
|
|
codex-memories-write = { workspace = true }
|
|
codex-mcp = { workspace = true }
|
|
codex-model-provider = { workspace = true }
|
|
codex-models-manager = { workspace = true }
|
|
codex-protocol = { workspace = true }
|
|
codex-app-server-protocol = { workspace = true }
|
|
codex-app-server-transport = { workspace = true }
|
|
codex-feedback = { workspace = true }
|
|
codex-rmcp-client = { workspace = true }
|
|
codex-rollout = { workspace = true }
|
|
codex-sandboxing = { workspace = true }
|
|
codex-state = { workspace = true }
|
|
codex-thread-store = { workspace = true }
|
|
codex-tools = { workspace = true }
|
|
codex-utils-absolute-path = { workspace = true }
|
|
codex-utils-json-to-toml = { workspace = true }
|
|
chrono = { workspace = true }
|
|
clap = { workspace = true, features = ["derive"] }
|
|
futures = { workspace = true }
|
|
serde = { workspace = true, features = ["derive"] }
|
|
serde_json = { workspace = true }
|
|
tempfile = { workspace = true }
|
|
thiserror = { workspace = true }
|
|
time = { workspace = true }
|
|
toml = { workspace = true }
|
|
toml_edit = { workspace = true }
|
|
tokio = { workspace = true, features = [
|
|
"io-std",
|
|
"macros",
|
|
"process",
|
|
"rt-multi-thread",
|
|
"signal",
|
|
] }
|
|
tokio-util = { workspace = true }
|
|
tracing = { workspace = true, features = ["log"] }
|
|
tracing-subscriber = { workspace = true, features = ["env-filter", "fmt", "json"] }
|
|
uuid = { workspace = true, features = ["serde", "v7"] }
|
|
|
|
[target.'cfg(windows)'.dependencies]
|
|
codex-windows-sandbox = { workspace = true }
|
|
|
|
[dev-dependencies]
|
|
app_test_support = { workspace = true }
|
|
axum = { workspace = true, default-features = false, features = [
|
|
"http1",
|
|
"json",
|
|
"tokio",
|
|
] }
|
|
base64 = { workspace = true }
|
|
codex-model-provider-info = { workspace = true }
|
|
codex-utils-cargo-bin = { workspace = true }
|
|
core_test_support = { workspace = true }
|
|
flate2 = { workspace = true }
|
|
hmac = { workspace = true }
|
|
opentelemetry = { workspace = true }
|
|
opentelemetry_sdk = { workspace = true }
|
|
pretty_assertions = { workspace = true }
|
|
reqwest = { workspace = true, features = ["rustls-tls"] }
|
|
rmcp = { workspace = true, default-features = false, features = [
|
|
"elicitation",
|
|
"server",
|
|
"transport-streamable-http-server",
|
|
] }
|
|
serial_test = { workspace = true }
|
|
sha2 = { workspace = true }
|
|
shlex = { workspace = true }
|
|
tar = { workspace = true }
|
|
tokio-tungstenite = { workspace = true }
|
|
tracing-opentelemetry = { workspace = true }
|
|
url = { workspace = true }
|
|
wiremock = { workspace = true }
|