src/vs/platform/agentHost/node/codex/codexClientCustomizations.ts
179 LOC · 178 covered · 1 uncovered · 31 ranges · 34 concepts · 8 introducers · 19 tests
File neighbourhood
The centred file is linked to every concept that introduces one of its ranges, every test that runs code from the file, and the gray connector concepts standing between those tests and the file's own introducer concepts. Undirected links join concepts to every file where they introduce source and concepts to the tests they introduce; arrows show specialization between the displayed concepts and bridge only concepts omitted from this view. Concept colors match the source ranges below; connector concepts have no source color and are shown in gray.
Focused file, its introducer and connector concepts, their introduced files, and tests that run code from the file
In the embedded map, ordinary wheel input scrolls the page; use the visible controls to zoom and drag to pan. Open the full-screen map for canvas navigation: wheel pans, Ctrl/Command plus wheel zooms, and arrow keys pan when this region is focused. On touch screens, open the full-screen map to pan or pinch. If JavaScript or WebGL is unavailable, use the related-file, concept, and source links on this page.
Graph controls are ready.
Interactive rendering requires JavaScript and WebGL. Use the related-file, concept, and source links on this page while the interactive map is unavailable.
1
>
/*---------------------------------------------------------------------------------------------
codexClientCustomizations.ts ×13
2
>
* Copyright (c) Microsoft Corporation. All rights reserved.
3
>
* Licensed under the MIT License. See License.txt in the project root for license information.
4
>
*--------------------------------------------------------------------------------------------*/
5
>
6
>
import { dirname } from '../../../../base/common/path.js';
7
>
import type { IMcpServerDefinition, IParsedPlugin } from '../../../agentPlugins/common/pluginParsers.js';
8
>
import type { ISyncedCustomization } from '../../common/agentPluginManager.js';
9
>
import { type ChildCustomization, type PluginCustomization } from '../../common/state/sessionState.js';
10
>
import { toCodexMcpServerJson, type ICodexMcpServerConfigJson } from './codexMcpServers.js';
11
>
12
>
/**
13
>
* Codex ingests **client-pushed** plugin customizations (the "Open Plugins"
14
>
* the workbench syncs via {@link IActiveClient.customizations}) differently
15
>
* from the `.agents`/`.codex` files it discovers itself. This module holds the
16
>
* per-session store for those synced+parsed plugins plus the pure mappers that
17
>
* project them into (a) the AHP {@link PluginCustomization} surface, (b) codex
18
>
* per-thread `thread/start.config.mcp_servers`, and (c) process-global
19
>
* `skills/extraRoots/set` roots.
20
>
*
21
>
* Feeding strategy (see the phase investigation):
22
>
* - MCP servers are attached **per session** via `thread/start.config`
23
>
* (verified: codex starts the server for that thread only), so a plugin's
24
>
* server only runs for sessions that enable it.
25
>
* - Skills are process-global in codex (`skills/extraRoots/set` replaces a
26
>
* single shared root list), so the store exposes the union of enabled skill
27
>
* roots and the agent sets it across all live sessions. This matches the
28
>
* semantics of client customizations, which are global user choices.
29
>
*/
30
>
31
>
/** A single client-pushed plugin: its sync result plus the parsed components (when the sync succeeded). */
32
>
export interface ICodexClientPlugin {
33
>
readonly synced: ISyncedCustomization;
34
>
readonly parsed: IParsedPlugin | undefined;
35
>
}
36
>
37
>
/**
38
>
* Per-session store of client-pushed plugin customizations, keyed by the
39
>
* contributing client id, with a per-customization enablement overlay
40
>
* (absent = enabled, `false` = disabled). Merges every client's contribution
41
>
* deduplicated by customization id (first client wins). Pure state holder —
42
>
* the agent reads the projections below and drives codex.
43
>
*/
44
>
export class CodexClientCustomizationStore {
46
>
private readonly _byClient = new Map<string, readonly ICodexClientPlugin[]>();
47
>
private readonly _enablement = new Map<string, boolean>();
49
>
/** Replace one client's synced+parsed plugin set. */
50
>
setClient(clientId: string, plugins: readonly ICodexClientPlugin[]): void {
52
>
}
54
>
/** Drop a client's contribution. Returns whether anything was removed. */
55
>
removeClient(clientId: string): boolean {
57
>
}
59
>
/**
60
>
* Toggle a client-pushed customization on/off. Returns whether the
61
>
* enablement actually changed (so callers can skip a no-op refresh).
62
>
*/
63
>
setEnabled(id: string, enabled: boolean): boolean {
65
>
const effective = current !== false; // absent counts as enabled
66
>
if (effective === enabled) {
68
>
}
70
this._enablement.delete(id);
72
>
this._enablement.set(id, false);
73
>
}
74
>
return true;
75
>
}
77
>
/** Whether a client-pushed customization with this id exists in the store. */
78
>
has(id: string): boolean {
79
>
return this._merged().some(p => p.synced.customization.id === id);
codexClientCustomizations.ts ×4
80
>
}
82
>
/** Whether the store holds any client-pushed customizations. */
83
>
isEmpty(): boolean {
85
>
}
87
>
/** Merge of every client's plugins, deduplicated by customization id (first client wins). */
88
>
private _merged(): readonly ICodexClientPlugin[] {
90
>
const out: ICodexClientPlugin[] = [];
91
>
for (const plugins of this._byClient.values()) {
92
>
for (const plugin of plugins) {
93
>
const id = plugin.synced.customization.id;
94
>
if (seen.has(id)) {
96
>
}
98
>
out.push(plugin);
99
>
}
100
>
}
101
>
return out;
102
>
}
104
>
private _isEnabled(id: string): boolean {
106
>
}
108
>
/** The merged plugins that are currently enabled and successfully parsed. */
109
>
enabledPlugins(): readonly ICodexClientPlugin[] {
110
>
return this._merged().filter(p => p.parsed !== undefined && this._isEnabled(p.synced.customization.id));
codexClientCustomizations.ts ×2
111
>
}
113
>
/**
114
>
* Projects the store onto the AHP {@link PluginCustomization} surface, with
115
>
* the enablement overlay applied and each plugin's parsed children folded
116
>
* in (skills, MCP servers, agents, instructions, hooks).
117
>
*/
118
>
toCustomizations(): PluginCustomization[] {
120
>
const base = plugin.synced.customization;
121
>
const children = plugin.parsed ? parsedPluginChildren(plugin.parsed) : base.children;
122
>
return {
123
>
...base,
124
>
enabled: this._isEnabled(base.id),
125
>
...(children ? { children } : {}),
126
>
};
127
>
});
128
>
}
130
>
131
>
/** Collects every child customization a parsed plugin exposes, deduped by id. */
132
>
function parsedPluginChildren(parsed: IParsedPlugin): ChildCustomization[] {
codexClientCustomizations.ts ×2
133
>
const byId = new Map<string, ChildCustomization>();
134
>
const add = (c: ChildCustomization) => { if (!byId.has(c.id)) { byId.set(c.id, c); } };
135
>
for (const a of parsed.agents) { add(a.customization); }
136
>
for (const s of parsed.skills) { add(s.customization); }
137
>
for (const r of parsed.instructions) { add(r.customization); }
138
>
for (const h of parsed.hooks) { add(h.customization); }
139
>
for (const m of parsed.mcpServers) { add(m.customization); }
140
>
return [...byId.values()];
141
>
}
143
>
/**
144
>
* Builds the `mcp_servers` object for `thread/start.config` from a set of
145
>
* client plugins. Later servers do not overwrite earlier ones (first
146
>
* definition of a given name wins), matching the dedupe used elsewhere.
147
>
* Returns an empty object when the plugins declare no MCP servers.
148
>
*/
149
>
export function codexMcpServersFromPlugins(plugins: readonly ICodexClientPlugin[]): Record<string, ICodexMcpServerConfigJson> {
151
>
for (const plugin of plugins) {
152
>
for (const def of plugin.parsed?.mcpServers ?? emptyMcpDefs) {
153
>
if (!Object.prototype.hasOwnProperty.call(out, def.name)) {
154
>
out[def.name] = toCodexMcpServerJson(def.configuration);
155
>
}
156
>
}
157
>
}
158
>
return out;
159
>
}
161
>
const emptyMcpDefs: readonly IMcpServerDefinition[] = [];
162
>
163
>
/**
164
>
* Derives the codex skill roots (absolute fsPaths) for a set of client
165
>
* plugins: the parent directory of each skill's `<name>/SKILL.md`, i.e. the
166
>
* plugin's `skills` root, which codex scans for `<name>/SKILL.md` entries.
167
>
* De-duplicated and sorted for a stable `skills/extraRoots/set` payload.
168
>
*/
169
>
export function codexSkillRootsFromPlugins(plugins: readonly ICodexClientPlugin[]): string[] {
171
>
for (const plugin of plugins) {
172
>
for (const skill of plugin.parsed?.skills ?? []) {
173
>
// skill.uri === <pluginDir>/<skillsDir>/<name>/SKILL.md
174
>
// dirname twice === <pluginDir>/<skillsDir> (the root codex scans).
175
>
roots.add(dirname(dirname(skill.uri.fsPath)));
176
>
}
177
>
}
178
>
return [...roots].sort();
179
>
}