Skip to content

app-server: add app/installed runtime snapshot API#31487

Draft
mzeng-openai wants to merge 1 commit into
dev/mzeng/apps-runtime-state-request-stablefrom
dev/mzeng/apps-runtime-state-api
Draft

app-server: add app/installed runtime snapshot API#31487
mzeng-openai wants to merge 1 commit into
dev/mzeng/apps-runtime-state-request-stablefrom
dev/mzeng/apps-runtime-state-api

Conversation

@mzeng-openai

Copy link
Copy Markdown
Collaborator

Summary

  • add the feature-gated v2 app/installed API backed by the committed connector runtime snapshot
  • project tool-derived connector identities through effective global, workspace, local, managed, MCP-tool, and app-tool policy at read time
  • keep app/list behavior unchanged and add the M4 installed-read telemetry seam

This is PR 4 of the connector runtime-state stack and is based on #31476.

Public contract

app/installed { threadId?: string, reload: boolean }
  -> { apps: Array<{ id: string, enabled: boolean, callable: boolean }> }

reload is required. reload: false performs a committed-snapshot/cache-only read. reload: true refreshes workspace policy and, when Apps are permitted, performs exactly one uncached hosted-connector refresh under the shared lock before returning the committed result.

The response deliberately omits Tool[] and all canonical connector metadata. IDs are sorted, deduplicated, non-empty connector IDs derived from non-synthetic /ps/mcp tools/list metadata. Consequently, zero-tool connectors are absent. This deliberately narrows the RFC draft and does not consume _meta.installedApps.

Canonical names, descriptions, branding, labels, and install URLs remain an M3 app/read / ConnectorMetadataStore dependency once that lands. Tool-level connector names and descriptions remain compact runtime/search metadata only.

Behavior and ownership

  • ConnectorRuntimeManager remains the owner of persisted/committed raw runtime snapshots and adds a non-activating peek used only for failure telemetry.
  • McpConnectionManager remains the owner of generic MCP filtering and publication; the read-time callable projection reuses its effective MCP tool-filter semantics.
  • local and managed configuration is never persisted in the snapshot.
  • disabled global/workspace policy skips the network tools refresh, retains prior identities, and projects them disabled/non-callable.
  • failed refreshes return an error and retain the prior committed snapshot.
  • the method is disabled by default behind apps_runtime_state_refactor; legacy app/list remains available with its existing response and forceRefetch behavior.

Telemetry

  • new-path installed duration with reload, refresh disposition, outcome, and retained-previous labels
  • installed response bytes, connector count, raw snapshot tool count, and snapshot age
  • distinct workspace-policy error/disable dispositions

The strict refresh trigger/outcome metrics are emitted by the preceding refresh-manager PR. This does not duplicate turn-start availability analytics.

Testing

  • just test -p codex-app-server-protocol (253 passed)
  • just test -p codex-mcp (118 passed)
  • just test -p codex-app-server app_installed (10 passed)
  • just test -p codex-core callable_app_ids_apply_effective_mcp_tool_filter
  • focused workspace-settings and effective app-enable tests were also run
  • just fix for codex-mcp, codex-core, codex-app-server-protocol, codex-chatgpt, and codex-app-server
  • just fmt

Coverage includes feature gating, reload false/true, empty and zero-tool results, synthetic identities, MCP/app policy, thread config, concurrent serialization, failure retention, context changes, atomic publication, and legacy app/list compatibility.

@mzeng-openai mzeng-openai force-pushed the dev/mzeng/apps-runtime-state-request-stable branch from 59a9dac to 4f515b5 Compare July 8, 2026 00:00
@mzeng-openai mzeng-openai force-pushed the dev/mzeng/apps-runtime-state-api branch from 123c5f2 to 353b3b7 Compare July 8, 2026 00:00
@mzeng-openai mzeng-openai force-pushed the dev/mzeng/apps-runtime-state-api branch from 353b3b7 to 16f827c Compare July 8, 2026 00:34
@mzeng-openai mzeng-openai force-pushed the dev/mzeng/apps-runtime-state-request-stable branch from 4f515b5 to 7a93f9a Compare July 8, 2026 00:34
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant