Commit Graph
38 Commits
Author SHA1 Message Date
jif 0768988e55 Resolve skill display names in read and installations tools (#59954)
## What changed

Allow `skills.read` and `skills.installations` to resolve visible skills by their full display name or the truncated name returned by `skills.list`. Preserve package locator and alias precedence, merged installation locations, and source filtering.

Reject ambiguous names with guidance to use `skills.list` and pass the intended package locator. Hidden and disabled skills remain unavailable through name lookup.

## Testing

Add regression coverage for name resolution, package and alias precedence, truncated UTF-8 names, merged locations, source filters, and ambiguous names.

GitOrigin-RevId: 5a2526d94f259cadb184563807127cb49955106d
2026-11-06 18:43:32 +00:00
Anthony Tafoya 75aba6768a Add outcome metrics for skill reads and installation listings (#59295)
## What changed

- Record `codex.skills.read.result` and `codex.skills.installations.result` counters with bounded outcome labels for successes and failures.
- Tag both counters with `discovery_version` and installation listings with `source_filter`.
- Make session telemetry available through the step store so skill tools emit metrics with the current step's model metadata.

## Testing

Add coverage for read metrics in both discovery versions, installation listing outcomes and source filters, and extension metrics retaining the current model metadata after a model switch.

GitOrigin-RevId: 0b5418e2b94a89149a20877f32ca2b2e196884e7
2026-11-04 02:29:41 +00:00
bkotsopoulos b82d542aef Add turn, tool, and skill attribution to traces (#56524)
## What changed

- Emit `codex.turn_profile` events with finalized sampling request and retry counts when turns complete or abort, and preserve the caller's tracing span for detached extension interrupts.
- Add conversation and turn identifiers to turn and tool dispatch spans, identify tool sources, and include dispatch-to-result-ready duration on tool completion events.
- Emit `codex.skill_read.source_selected` before cache or provider access, recording the selected cloud or executor source, skill and plugin identity, resource kind, and continuation status.

## Testing

Add regression coverage for trace correlation, tool completion timing, turn profile counters on completion and interruption, detached interrupt span propagation, and skill source attribution including cached cloud reads.

GitOrigin-RevId: db78aa270bbcb8dc9e4558d202c109ad54141811
2026-10-23 16:55:32 +00:00
Anthony Tafoya 9b865ab31e Prepare skill catalogs before building step tools (#55357)
## Why

Skill tools depended on World State rendering to initialize their catalogs and could return `skill catalog is not ready for this step` before rendering completed.

## What changed

- Add an asynchronous `ToolContributor::prepare_for_step` hook and await all contributors before constructing tools.
- Prepare immutable skill catalogs, aliases, plugin policy, and configuration for each step. Tools, invocation detection, and World State rendering consume the prepared state without relying on rendering to perform discovery.
- Apply configuration reloads to subsequent steps while preserving live authorization checks for skill reads.

## Testing

Add coverage for preparation completing before tool construction and World State rendering, skill tools working before rendering, catalogs remaining stable across steps, and configuration reloads during discovery.

GitOrigin-RevId: 1fb95c58c412488353f3bd4403824d6d1476d3d0
2026-10-19 19:33:11 +00:00
Anthony Tafoya 03478b4b92 Expose skill installations and stabilize package aliases (#55330)
## Why

A skill can be available from Cloud and multiple executor environments. Reading its instructions needs to expose where supporting files live and allow discovery of locations omitted by response limits. Package aliases also need to keep identifying the same roots as catalogs change.

## What changed

- With executor capability discovery V2, add `skills.installations` to list enabled locations with source filtering and pagination, without reading skill contents.
- Let `skills.read` select Cloud or a specific executor environment through `source`. Return bounded installation metadata and an `installations_truncated` flag so callers can retrieve omitted locations.
- Share bounded, append-only alias assignments between catalog rendering and tools within a live thread. Preserve each step's alias snapshot and render only root mappings used by its catalog entries.
- Use discovery-root metadata when constructing executor skill locators, with a fallback when it is absent. Preserve the legacy read response and tool set outside discovery V2.

## Testing

Add coverage for installation filtering and pagination, response budgets, source-specific reads and cursors, and alias stability across catalog and plugin changes. Add an end-to-end scenario that discovers an omitted installation and reads its instructions from the selected environment.

GitOrigin-RevId: a04e51e8242b21288d9d7b822780f9f1e093151d
2026-10-19 17:37:49 +00:00
Anthony Tafoya a309f9206a Integrate discovery V2 with step-scoped skill catalogs (#55322)
## What changed

- Build executor skill catalogs from discovery V2 inventories without reopening host paths or falling back to legacy discovery.
- Merge Cloud and executor skills by remote plugin identity and skill name, retaining Cloud metadata and accepted provider read routes. Apply plugin selection and disablement before merging.
- Share a stable catalog across each step's rendering, list/read tools, and explicit and implicit skill invocations.
- Preserve unmatched executor entries when Cloud catalogs are unavailable or partial; only complete Cloud catalogs disable unmatched remote entries.
- Bind discovery caches to captured environments and executor sessions, and refresh MCP when V2 inventories change. Preserve pending invalidations when forced MCP refreshes fail.

## Testing

Add regression coverage for V2 inventory sharing and refresh, environment isolation, catalog merging, partial Cloud results, disabled plugins, and catalog consistency across steps and read routes.

GitOrigin-RevId: 842bdcbc9e19364dd69a9abf9e48330b7425a76c
2026-10-19 17:02:20 +00:00
Anthony Tafoya f6e03d4eac Route skill reads by alias source (#55303)
## Why

Skill aliases already identify their source, but `skills.read` searched the cloud catalog before the executor catalog even for executor aliases.

## What changed

Parse package locators to recognize cloud (`c0/...`), executor (`e0/...`), and host (`r0/...`) aliases. Restrict cloud and executor alias lookups to the matching catalog, while retaining the existing search order for other package strings.

Share the source-to-prefix mapping between alias generation and parsing, and preserve the string representation and tool schema for package locators.

## Testing

Extend alias tests to cover source recognition, JSON round trips, and malformed alias strings, including leading zeros, missing suffixes, non-ASCII prefixes, and overflowing indices.

GitOrigin-RevId: f835e47a244aa0cf9eb95980ea23f4d7fcedd511
2026-10-19 15:19:47 +00:00
Alex Zamoshchin c9e0fffbbc Enable parallel execution for read-only tools (#52245)
## Why

Tools that do not opt into parallel execution acquire an exclusive scheduler lock, serializing independent reads.

## What changed

Allow skill listing and reading, memory listing, reading and searching, conversation history search and reading, plugin listing, agent listing, current time, remaining context, and `get_goal` to run in parallel. Keep goal creation and updates serialized.

## Testing

Add `cloud_skill_reads_run_in_parallel`, which uses a barrier to require two cloud skill reads to overlap and verifies that each returns the expected resource contents.

GitOrigin-RevId: 97b5634f1f84be2ba092be89e6e9c634ca75c07b
2026-10-08 19:29:47 +00:00
Adam Perry @ OpenAI da2e174a66 Scope extension filesystem access to callback permissions (#49898)
## Why

Executor skill reads need to use the environments and permissions captured for the current step, including newly approved grants. Cached continuation pages must remain bound to the filesystem and permissions that produced them.

## What changed

- Supply borrowed `EnvironmentAccess` to turn-input contributors and extension tools, with session and originating-turn grants already applied.
- Require executor skill reads to use filesystem access from an environment available to the callback, and replace separate optional read contexts with `SkillReadContext`.
- Bind skill pagination snapshots to `EnvironmentAccessKey`, which identifies the source filesystem and callback permissions.
- Route image-generation filesystem operations through the same accessor.

## Testing

Extend skill-read integration coverage to verify that a denied reference becomes readable after a turn-scoped grant is captured by the next model step. Update Windows coverage to verify that restricted reads fail when the executor cannot enforce a sandbox, and add a test requiring turn environment selection before exposing capability roots.

GitOrigin-RevId: 825b49302319965835d61c77fc5bcdb951e10543
2026-10-01 06:29:03 +00:00
vkg-oai 0f8df3d214 Move shadow skill ranking off the turn preparation path (#49812)
## Why

Shadow skill selection runs synchronously during turn input construction, making turn preparation wait for experimental rankings.

## What changed

Run ranking on background blocking workers with a process-wide limit of two concurrent rankings. Wait for capacity in the background and hold each slot until its blocking worker finishes, even if the async evaluation is cancelled.

Freeze catalog, query, and relevance history at turn start. Record eligible invocations immediately for future turns, then score queued observations against the frozen rankings once they are ready, including observations queued before the turn state is dropped.

## Testing

Add tests for turn preparation and history updates while ranking is blocked, deferred invocation scoring against each turn's history, and shared ranking capacity that remains occupied until cancelled workers finish. Update existing metric assertions to collect asynchronous observations across snapshots.

GitOrigin-RevId: f7776e9aaeb45d3a792de167abbe35f7ec5a513e
2026-10-01 01:49:59 +00:00
jif 0a76a2520f Export skill invocation events through OpenTelemetry (#49689)
## What changed

Emit `codex.skill_invocation` logs for explicit skill injection and detected implicit use, including skill-tool reads. Include skill name, invocation type, conversation, turn, model, and client metadata, plus scope, plugin ID, and ChatGPT user and account IDs when available.

Exclude skill contents, resource paths, email addresses, prompts, and tool payloads. Use the existing OTEL log exporter without an additional opt-in; `otel.exporter = "none"` continues to export no logs.

Document the event fields, exporter configuration, and detection semantics in `codex-rs/otel/README.md`.

GitOrigin-RevId: 0f9c492c3f224455f3de3660be89692d776c1951
2026-09-30 17:45:25 +00:00
Eddie Chen 6a601c00da Preserve originating turn metadata for yielded skill calls (#47106)
## Why

Code Mode callbacks can retain skill tools after another turn becomes active. Looking up the active turn when a delayed skill invocation completes can lose access to the originating turn's metrics and metadata.

## What changed

- Capture and retain the originating `SkillTurnMetrics` when constructing skill analytics.
- Expose turn analytics metadata through the turn extension store and carry it into skill telemetry.
- Add optional turn metadata to `TrackEventsContext` and pass it from app, skill, and plugin usage call sites.

## Testing

Add a regression test that yields a Code Mode cell, starts another turn, and releases both skill reads through a shared barrier. Assert that each `skill_invocation` event retains its originating `turn_id`.

GitOrigin-RevId: aa629dd5f84563d558aa6a86bfbdfc356f1b98e4
2026-09-21 20:34:46 +00:00
Anthony Tafoya f3037cafd3 Refresh host-supplied cloud skills at turn startup (#47074)
## What changed

- Replace the built-in orchestrator skill provider with a host-supplied cloud provider, using `cloud` authority and `c` root aliases in skill tools and prompts.
- Add `cloud.skills.enabled`, defaulting to true but requiring a supplied provider. Keep `orchestrator.skills` accepted as a legacy no-op setting, and remove the app server's automatic orchestrator provider registration.
- Discover cloud skills once per turn during cancellable startup. Serve catalog snapshots to prompts and tools without triggering discovery or retries.
- Scope cached catalogs and resources to authentication state. Preserve them on refresh failures within the same scope, invalidate them when that scope changes, and reject late discovery or read results from replaced cache generations.
- Reuse executor discovery catalogs only when successful discovery inputs and bundled-skill settings match.

## Testing

Add coverage for per-turn refresh, skill removal, same-account failures and reconnects, authentication changes, and stale in-flight results. Update configuration and tool tests for cloud authority, provider gating, and resource reads without an executor.

GitOrigin-RevId: c57e38ec7dcc880c0d4c8a2995adfd3e28301079
2026-09-21 17:28:14 +00:00
Charlie Marsh f3803587c9 Share tool output schemas and defer MCP envelope construction (#45439)
## Why

MCP tool parsing eagerly cloned structured output schemas and built full call-result envelopes. Cloning tool definitions also copied their output-schema JSON, even before a consumer needed it.

## What changed

- Introduce `ToolOutputSchema` with immutable `Arc` storage so tool definitions share output schemas when cloned.
- Retain MCP structured output schemas and materialize the call-result envelope only when JSON is requested.
- Update code-mode consumers and schema mutation sites to materialize JSON explicitly, reusing uniquely owned storage when possible.
- Move structured content into the MCP envelope without an extra clone, preserving property order.

## Testing

Add tests for JSON preservation, mutation isolation, equality between lazy and materialized schemas, reuse of uniquely owned storage, and equivalent code-mode definitions.

GitOrigin-RevId: e98ba4c2f0efedc99f7cbc7bba206cc63a3bd8f4
2026-09-14 15:05:16 +00:00
Adam Perry @ OpenAI 81e180044d Scope extension capabilities to invocation lifetimes (#41020)
## What changed

- Add callback lifetimes to extension `ToolCall`, `ToolEnvironment`, turn-input context, and skill-read request types.
- Require extension tool executors to handle calls for any invocation lifetime and tie their returned futures to that lifetime.
- Update built-in extensions, adapters, and tests to use the lifetime-scoped APIs without retaining host-owned environment capabilities.

GitOrigin-RevId: aca9ce3a1b6870df550bc84ec9308cc65533f161
2026-08-27 02:00:31 +00:00
jwang-openai c51e7b3736 Add plugin-attributed skill telemetry (#40724)
## What changed

- Add `plugin_id`, `model_slug`, and `reasoning_effort` dimensions to
  `codex.skill.injected` metrics for explicit and implicit skill invocations.
- Propagate plugin IDs from orchestrator skill metadata so resource-backed skill
  invocations can emit the same attribution.
- Record `codex.skill.turn.duration_seconds` once per plugin used in a turn,
  tagged with the model, reasoning effort, and completed, aborted, or error
  status.

GitOrigin-RevId: d249a9c4e85682b1106ac49d9e598535c6cbb06d
2026-08-25 22:29:14 +00:00
Tamir Duberstein c941572917 Honor response budgets when reading skill resources (#40491)
## Why

`skills.read` paginated resources against a fixed response limit, so a page could exceed a smaller tool-call response budget.

## What changed

- Size each serialized `skills.read` page to the current call's response budget, accounting for JSON escaping and UTF-8 boundaries.
- Cache one bounded executor-resource snapshot per thread so cursor continuations return consistent contents without rereading the file. Replace the snapshot when another resource is read, and reject stale cursors after a reread.
- Tie cached executor snapshots to the selected environment and sandbox context without keeping the environment alive.

## Testing

- Cover budget-constrained reads, escaped and multibyte contents, multi-page reconstruction, changed resources, snapshot eviction, and expired turn-scoped access.

GitOrigin-RevId: e515935b82771b3f29b3fb91ea7a7a72e19a65ee
2026-08-24 23:00:57 +00:00
Tamir Duberstein a25e986323 Honor response budgets when listing skills (#40413)
## What changed

- Build `skills.list` pages against the current tool-call response-byte budget.
- Skip entries that cannot fit, preserve pagination across retained entries, and report oversized metadata without repeating the warning for the same budget.
- Keep existing cursors compatible while encoding the response budget in new cursors.

## Testing

- Cover direct and Code Mode listing, budget changes between pages, provider and omission warnings, oversized entries, legacy cursors, and budgets too small to return discovery warnings.

GitOrigin-RevId: 4b34cd2714e4849fe9155ce3f0021b218763c395
2026-08-24 14:54:31 +00:00
Tamir Duberstein e3609f2d02 Expose invocation sources to extension tools (#40382)
## What changed

- Add `ToolCallSource` to extension `ToolCall`s and propagate direct or Code Mode
  invocation metadata, including the runtime cell and nested tool-call IDs.
- Add `ToolCall::response_byte_budget` so extension tools can bound direct-call
  responses by the host truncation policy while allowing Code Mode responses up
  to the tool's own limit.
- Share the skills extension's response-size limit between its `list` and `read`
  tools.

## Testing

- Verify that Code Mode source metadata is preserved when core constructs an
  extension tool call.

GitOrigin-RevId: b10aef01be30d35b67bee3af24a1a4175c9ee112
2026-08-24 11:02:14 +00:00
rphilizaire-openai 280d56b1d8 Attribute executor skill invocations to plugins (#39309)
## What changed

- Carry selected plugin identities from MCP discovery into per-turn extension data, limited to capability roots that are ready for the turn.
- Annotate executor skill catalog entries with the matching plugin ID and `user` scope.
- Include that attribution in `skill_invocation` analytics for both explicit and implicit executor skill invocations.

## Testing

- Extend the executor skills app-server test to verify plugin ID, skill scope, and invocation type for explicit and implicit analytics events.

GitOrigin-RevId: 9345600ae29bcb8eb894fffd2d6f7b05f22ebf74
2026-08-18 22:53:31 +00:00
jif 5664a5c07c Expose executor skill roots from skills.read (#38268)
## Why

Executor-backed skills can include bundled scripts, so skill readers need the
skill directory in the executor filesystem to locate them.

## What changed

- Add `skill_root` to `skills.read` responses for executor-backed skills.
- Derive the root from the parent directory of the skill's main resource and
  omit the field for other skill authorities.

## Testing

- Verify executor skill reads return the expected root for both `SKILL.md` and
  a referenced resource.

GitOrigin-RevId: b7035c7e2e62155890795fb508fefe3a1c17805b
2026-08-12 22:54:35 +00:00
jif 130c7c93a9 Resolve skill package aliases in skills.read (#38261)
## Why

Skill catalogs can present shortened package locators, but callers previously had
to expand those aliases before reading a skill.

## What changed

- Resolve catalog aliases automatically when `skills.read` looks up a
  model-visible executor or orchestrator skill package.
- Update skill prompts and tool documentation to tell models to pass the listed
  package locator directly.

## Testing

- Exercise reading an executor skill through its shortened package locator when
  the skills catalog exceeds its context budget.

GitOrigin-RevId: d1cdfd64002510b616146929deb5b7077850b951
2026-08-12 22:10:55 +00:00
rphilizaire-openai 69ae78291d Read executor skill packages directly (#38167)
## Why

Executor skills required a `skills.list` lookup before their contents could be
read, even when the catalog already identified the skill.

## What changed

- Render executor skill catalog entries as package locators, including shortened
  locators when skill roots are aliased.
- Tell the model to pass those packages directly to `skills.read`, while keeping
  `skills.list` as the fallback when no package is available.
- Use the shorter package locators when applying the skills context budget.

## Testing

Update catalog, aliasing, budget-pressure, and selected-skill coverage, including
an executor package ID containing a literal backslash.

GitOrigin-RevId: 2ace5e527dc4f29651a8f3214475ccc90d52c73f
2026-08-12 10:34:25 +00:00
rphilizaire-openai c8f673fddc Track resource-backed skill invocations (#38066)
## What changed

- Emit skill invocation analytics when a resource-backed skill is explicitly selected or its main resource is successfully read from the first page.
- Preserve provider-supplied skill IDs and user scope when available, and derive a stable ID from the main resource otherwise.
- Deduplicate repeated implicit reads of the same main resource within a turn.

## Testing

- Extend the orchestrator skill integration test to cover explicit and implicit invocation events, stable fallback IDs, failed reads, and repeated-read deduplication.

GitOrigin-RevId: 7d8453b31b5a2205847e65cda2c46183d6c97b45
2026-08-11 19:52:54 +00:00
jif 09f47c8785 Simplify package-based skill reads (#37808)
## What changed

- Make `package` the only required argument to `skills.read`, resolving the
  owning orchestrator or executor catalog automatically.
- Default omitted `resource` values to the package's main `SKILL.md`.
- Render orchestrator skills as package locators and instruct the model to read
  them directly without first calling `skills.list`.
- Update skill extension and app-server coverage for direct main-resource
  reads, referenced resources, aliases, and the revised tool schema.

GitOrigin-RevId: 9faf57a8d0935566a15094931eaabaa8f0613e9e
2026-08-10 11:10:01 +00:00
rphilizaire-openai a1890b6998 Project orchestrator skills through world state (#37149)
## What changed

- Move the orchestrator skill catalog from thread context into its own
  `orchestrator_skills` world-state section so unchanged catalogs remain
  incremental across turns.
- Discover executor, orchestrator, and host catalogs together and render them
  against one context-window-aware metadata budget, preserving executor entries
  before orchestrator and host entries under pressure.
- Emit catalog metrics and budget warnings when each world-state section is
  rendered.

## Testing

- Cover incremental orchestrator catalogs across production turns, combined
  catalog budgeting, disabled and unavailable providers, caching, warnings, and
  metrics.

GitOrigin-RevId: a0fb25d39dcaf43c978aff9da7972a1206f736e4
2026-08-05 20:14:31 +00:00
rphilizaire-openai 1b90b1d16b Honor explicit-only orchestrator skills (#36976)
## Why

Orchestrator skills with `allow_implicit_invocation: false` were still exposed in the model-visible skill catalog.

## What changed

- Hide explicit-only orchestrator skills from the prompt catalog while keeping them available for direct invocation.
- Include orchestrator resource-access metadata with injected instructions so `skills.read` can load referenced resources.
- Track visible and hidden discovery limits separately, and record discovery duration and resource-count metrics.

## Testing

Add an integration test that verifies an explicit-only orchestrator skill stays out of the prompt catalog, can be selected explicitly, and can read a referenced resource.

GitOrigin-RevId: 9cab5a61eb27c96bec9d1346c7dcdbc97376f7dc
2026-08-04 21:42:03 +00:00
jif 3d805abdf0 Sandbox executor skill resource reads (#36121)
## Why

Executor-backed skill resources must honor the active filesystem permission profile instead of reading outside its allowed roots.

## What changed

- Propagate each environment's filesystem sandbox context into `skills.read` calls.
- Apply turn-scoped permission grants when reading executor skill resources.
- Fail closed when no matching sandbox context exists or a restricted Windows read cannot be sandboxed.
- Preserve the existing resource size limit for both sandboxed and streamed reads.

## Testing

- Cover reads within permitted roots and reads that succeed after a permission grant.
- Verify denied references do not expose their contents and disabled Windows sandboxing is rejected.

GitOrigin-RevId: 5cc679b9385b0621665ff20cf5848863cc6396a4
2026-07-30 09:46:11 +00:00
jif fe8500c0a0 Enable resource reads for explicit executor skills (#35198)
## Why

Executor skills that disallow implicit invocation are omitted from `skills.list`, so an explicitly selected skill did not provide the authority and package identifiers needed to read its referenced resources.

## What changed

- Add `resource_access` metadata to injected instructions for explicit-only executor skills.
- Teach the `skills.read` description to accept that metadata as well as values returned by `skills.list`.
- Keep discoverable executor skill instructions unchanged.

## Testing

Add an app-server integration scenario that selects an explicit-only executor skill, confirms it remains absent from `skills.list`, and reads a referenced file through `skills.read`.

GitOrigin-RevId: 97d3b93d1618c013363788452303c8a31e32cc56
2026-07-24 14:48:04 +00:00
jif 7c71783135 Expose executor skills through skill tools (#35184)
## What changed

- Add executor authority support to `skills.list` and `skills.read` for skills from selected capability roots.
- Allow `skills.read` to load package-relative resources referenced by an executor skill while keeping reads within the selected package.
- Paginate skill listings and resource contents with bounded response sizes and stale-cursor validation.
- Resolve executor filesystems per sampling step so skill tools use the active selected capability roots.

## Testing

- Extend the app-server executor skill test to list an executor skill, read its main `SKILL.md`, and read a paginated reference resource.
- Cover visibility filtering, metadata bounds, pagination, invalid cursors, package boundaries, and resource size limits.

GitOrigin-RevId: 1b5de95d5d1b9f79c34d2879d6e67f24401e9c29
2026-07-24 13:46:20 +00:00
felixxia-oai 5dd992acd3 Route extension warnings to app-server threads (#35168)
## Why

Extension warnings need a stable thread target even when they are emitted outside an active turn.

## What changed

- Add `ExtensionWarning` and a dedicated `ExtensionEventSink::emit_warning` path with an explicit thread ID and optional turn ID.
- Deliver extension warnings as thread-scoped app-server `warning` notifications, preserving listener ordering and waiting briefly for a subscriber when no listener is active.
- Move skills warnings to the new path, limiting provider catalog warnings to four messages of 256 bytes each.

## Testing

- Cover warning routing, ordering, UTF-8-safe truncation, subscriber fallback, and invalid thread IDs.
- Verify skills warning bounds and app-server delivery of executor catalog budget warnings.

GitOrigin-RevId: 4dcb1ba7f17c0edb1a9d548f9568e0c734bffc15
2026-07-24 12:28:29 +00:00
Bryan Ashley 08e30a2e4e Add batched executor capability discovery (#33852)
## Why

Selected capability roots can contribute plugins, MCP servers, connectors, and
skills. Discovering each contribution separately requires repeated access to the
executor filesystem.

## What changed

- Add the `capabilityRoots/discoverV1` exec-server RPC to scan selected roots and
  materialize recognized plugin manifests, configuration files, skill
  instructions, and skill metadata in one bounded request.
- Add the opt-in `executor_capability_discovery` feature, with a thread-scoped
  cache and per-step snapshot shared by MCP and skill discovery.
- Parse MCP, connector, and skill contributions from the materialized snapshot,
  including serving cached skill instructions without another filesystem read.

## Testing

- Cover discovery limits, manifest precedence, root-local failures, cache reuse,
  plugin contributions, and parity with the existing environment skill loader.

GitOrigin-RevId: f98fd2321cafb58c596db02da1f83c09d8eb375d
2026-07-17 15:45:48 +00:00
jif c100109280 Add shadow metrics for lexical skill selection (#32761)
## What changed

- Add an opt-in `skill_search` feature that ranks prompt-visible skills against each turn's user input with a bounded weighted lexical selector.
- Keep the ranked selection out of model-visible context and record metrics for selection cost, catalog reduction, and whether later implicit or `skills.read` invocations matched the ranked candidates.
- Include host-provided skills in the experiment catalog without changing the rendered skill catalog.

## Testing

- Add selector unit tests covering ranking, limits, truncation, stop words, and deterministic tie-breaking.
- Add extension tests covering turn-local invocation recording and host-skill shadow selection.

GitOrigin-RevId: 4d00a1c805ea8b391d6c6ac6a8450afa88ca3e25
2026-07-13 10:38:37 +00:00
charlesgong-openai 64bdeed9f7 [codex] Preserve skill descriptions outside model context (#29006)
## Why

Skill descriptions are used in model-visible lists: the default
available-skills catalog that supports implicit selection, and the
on-demand `skills.list` tool response used to discover orchestrator
skills. A single overlong description should not consume a
disproportionate share of either list.

Enforcing the 1024-character limit while loading or migrating skills is
the wrong boundary: it rejects otherwise-valid skills and discards
metadata that non-model consumers and full skill reads may need. Skill
metadata and `SKILL.md` content should remain intact; the cap belongs at
model-visible list rendering boundaries.

## What changed

- Preserve full `description` and `metadata.short-description` values
when loading skills.
- Preserve full external-agent command descriptions during
`source-command-*` migration instead of skipping commands solely because
their descriptions exceed 1024 characters.
- Preserve full normalized orchestrator descriptions in the underlying
skills catalog.
- Cap each description at 1024 Unicode characters when rendering the
default available-skills context in `codex-core-skills` and
`codex-skills-extension`.
- Apply the same cap when serializing descriptions in the model-visible
`skills.list` response.
- Render truncated descriptions as 1021 original characters plus `...`.
- Leave explicit `$skill` injection, `skills.read`, underlying metadata,
and on-disk `SKILL.md` files unchanged and full-fidelity.

## Implicit skill selection

Codex injects a bounded catalog containing each implicitly allowed
skill's name, description, and source locator, together with
instructions to use a skill when the task clearly matches its
description. The model makes that semantic choice; after selecting a
skill, it reads the full `SKILL.md` from its filesystem or provider
resource. Explicit `$skill` mentions remain a separate path that injects
the full skill instructions. For orchestrator skills, `skills.list`
provides bounded discovery metadata before `skills.read` returns the
full selected resource.

## Test plan

- `just test -p codex-core-skills`
- `just test -p codex-skills-extension`
- `just test -p codex-external-agent-migration`

The focused regressions verify that overlong metadata is preserved at
load and migration boundaries while default available-skills rendering
and `skills.list` output produce the 1021-character prefix plus `...`.
2026-06-19 12:47:53 -07:00
jif 0318381762 Replace SkillsManager with SkillsService (#28705)
## Why

Host skill discovery was still exposed as a manager even though it is a
process-owned service shared by sessions, the app-server catalog, and
file-watcher invalidation. The skills extension also consumed an ad hoc
loaded-skills wrapper instead of a named immutable snapshot.

## What changed

- replace `SkillsManager` with concrete `SkillsService`
- make the service cache and return immutable `HostSkillsSnapshot`
values
- migrate the skills extension host provider to the snapshot boundary
- migrate app-server catalog, watcher, and invalidation paths to the
service

This keeps the service limited to host discovery, caching, roots, and
invalidation. Catalog rendering and invocation remain extension
responsibilities for the next stacked change.
2026-06-17 17:01:06 +02:00
jif 0afe559318 skills: cache orchestrator resources per thread (#28336)
## Why

Hosted orchestrator skills are read through the remote MCP resource
server. Within one thread, the same catalog or skill resource can be
requested multiple times by prompt injection and the `skills.list` /
`skills.read` tools. Re-fetching adds latency and can make those
surfaces observe different remote contents during the same thread.

This is a follow-up to #28333: orchestrator skills remain limited to
threads without a local executor, and those threads now get a stable
per-thread view of the remote skill data they use.

## What changed

- Reuse the existing per-thread orchestrator catalog snapshot for
`skills.list` and `skills.read` availability checks.
- Cache successful orchestrator resource reads by authority, package,
and resource so prompt injection and tool calls share the same contents.
- Keep the cache memory-only and bounded to 100 resources and 8 MiB per
thread.
- Leave host and executor skill reads unchanged, and do not cache failed
remote reads.

## Verification

- Extended the app-server MCP resource integration test to read the same
hosted skill resource twice and verify that the remote server receives
one read.
- The same test verifies that catalog discovery and the selected skill's
main prompt are each fetched only once per thread.
2026-06-15 20:20:19 +02:00
jif e6757bba91 nit: cap error (#27585)
Just cap an error that could end up in the model context
2026-06-11 12:52:46 +02:00
jif 7b3eb8e4bc skills: expose remote skill resource tools (#27388)
## Why

PR #27387 makes backend plugin skills discoverable and invocable without
an executor, but resources referenced by those skills still sit behind
the generic MCP resource surface. The model needs a skills-owned API
that preserves the provider authority and package boundary instead of
treating remote resources like local files.

This is stacked on #27387.

## What

- Adds one `skills` namespace with bounded `list` and `read` tools for
remote skill providers.
- Revalidates `authority + package` against the live remote catalog on
every read, then routes the opaque resource ID back through that
provider.
- Allows the backend provider to read canonical child `skill://`
resources while rejecting cross-package, non-canonical, query, fragment,
and traversal-shaped URIs.
- Caps each serialized tool result at 8 KB. Lists are paginated; reads
return an opaque continuation cursor.
- Marks the JSON output as external context so memory generation can
apply its normal suppression policy.
- Deliberately does not add `skills.search`; that waits for a bounded
plugin-service search contract.

## Tool contract

Pseudo-Python matching the wire shape:

```python
from typing import Literal, NotRequired, TypedDict


class RemoteSkillAuthority(TypedDict):
    kind: Literal["remote"]
    id: str  # e.g. "codex_apps"


class RemoteSkill(TypedDict):
    authority: RemoteSkillAuthority
    package: str  # opaque provider-owned package ID
    name: str
    description: str
    main_resource: str  # opaque provider-owned SKILL.md ID


class SkillsListParams(TypedDict):
    cursor: NotRequired[str]


class SkillsListResult(TypedDict):
    skills: list[RemoteSkill]
    next_cursor: str | None
    warnings: list[str]
    truncated: bool


class SkillsReadParams(TypedDict):
    authority: RemoteSkillAuthority  # copied from skills.list
    package: str  # copied from skills.list
    resource: str  # provider-owned child resource ID
    cursor: NotRequired[str]  # copy next_cursor to continue


class SkillsReadResult(TypedDict):
    resource: str
    contents: str
    next_cursor: str | None
    truncated: bool


class Skills:
    def list(self, params: SkillsListParams) -> SkillsListResult: ...
    def read(self, params: SkillsReadParams) -> SkillsReadResult: ...
```

There is one namespace for all remote skills, not one tool or MCP server
per skill. No resource ID is converted into a filesystem path.

## Backend dependency

`/ps/mcp` must support direct reads of child resources such as
`skill://plugin_demo/deploy/references/deploy.md`. This PR implements
and tests the Codex side of that contract; production child reads remain
dependent on the corresponding plugin-service support. Search remains
out of scope until that service exposes a bounded search/resource API.

## Validation

- Added an app-server integration test covering `skills.list` followed
by `skills.read` with no executor.
- Ran `just fmt`.
- Ran `just bazel-lock-update` and `just bazel-lock-check`.
- Did not run Rust tests or Clippy locally, per request; CI will run
them.
2026-06-11 12:38:04 +02:00