2 Commits

• Make selected plugin roots URI-native (#28918)

  ## Why
  
  Selected capability roots belong to the executor filesystem, not the
  app-server host. Converting their path strings into the host's native
  `Path` breaks whenever the two machines use different path conventions,
  such as a Windows executor behind a Unix app-server.
  
  This PR establishes `PathUri` as the selected-plugin boundary so the
  executor remains authoritative for its paths.
  
  ## What changed
  
  - Require `selectedCapabilityRoots[].location.path` to be a canonical
  `file:` URI and deserialize it directly as `PathUri`; native path
  strings are rejected.
  - Update the app-server schema, generated TypeScript, examples, and
  request coverage for the URI contract.
  - Keep selected roots, resolved plugin locations, manifest paths, and
  manifest resources as `PathUri`.
  - Inspect and read plugin roots and manifests only through the selected
  environment's `ExecutorFileSystem`.
  - Parse executor manifests with the shared URI-native parser from #29620
  instead of projecting them onto the host filesystem.
  - Enforce resource containment lexically and preserve the root URI's
  POSIX or Windows path convention.
  - Cover foreign Windows plugin roots and URI-native manifest resources.
  
  ```text
  thread/start
    selectedCapabilityRoots[].location.path = "file:///C:/plugins/demo"
                                | PathUri
                                v
                      ExecutorFileSystem
                                |
                                +--> plugin.json
                                +--> manifest resources
  ```
  
  This PR stops at the shared selected-plugin representation. The next two
  PRs remove the remaining host-path projections in the skill and MCP
  consumers.
  
  ## Stack
  
  1. #29614 — add lexical `PathUri` containment.
  2. #29620 — share URI-native manifest path resolution.
  3. **This PR** — keep selected plugin roots and resources URI-native.
  4. #29626 — load executor skills without host path conversion.
  5. #29628 — resolve executor MCP working directories without host path
  conversion.

  jif · 2026-06-23 22:51:19 +01:00
  2e69966cd8
• Load selected executor skills through extensions (#27184)

  ## 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.

  jif · 2026-06-09 19:51:54 +02:00
  89ac3ec27c