src/vs/platform/agentHost/node/codex/codexGuardianReview.ts
201 LOC · 189 covered · 12 uncovered · 41 ranges · 33 concepts · 8 introducers · 18 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
>
/*---------------------------------------------------------------------------------------------
codexGuardianReview.ts ×9
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 type { GuardianApprovalReviewAction } from './protocol/generated/v2/GuardianApprovalReviewAction.js';
7
>
import type { ItemGuardianApprovalReviewCompletedNotification } from './protocol/generated/v2/ItemGuardianApprovalReviewCompletedNotification.js';
8
>
import type { RequestPermissionProfile } from './protocol/generated/v2/RequestPermissionProfile.js';
9
>
import type { JsonValue } from './protocol/generated/serde_json/JsonValue.js';
10
>
import { unwrapShellInvocation } from './codexShellCommand.js';
11
>
12
>
/**
13
>
* Auto-review (guardian) notifications are emitted by the app-server with
14
>
* `ts-rs`-generated camelCase field names. The `thread/approveGuardianDeniedAction`
15
>
* request, however, echoes back a `codex_protocol::protocol::GuardianAssessmentEvent`
16
>
* that is (de)serialized with plain `serde` — which uses **snake_case** for enum
17
>
* variants, enum values, and the tagged-union `type` discriminant. The two shapes
18
>
* therefore diverge (`inProgress` vs `in_progress`, `networkAccess` vs
19
>
* `network_access`, `unifiedExec` vs `unified_exec`, `toolName` vs `tool_name`, …),
20
>
* so we cannot round-trip the notification payload verbatim.
21
>
*
22
>
* These helpers translate the camelCase completed-review notification into the
23
>
* snake_case `GuardianAssessmentEvent` JSON that the app-server can deserialize,
24
>
* and summarise a review action for display on the approval card.
25
>
*/
26
>
27
>
/** camelCase {@link GuardianApprovalReviewStatus} value -> snake_case `GuardianAssessmentStatus`. */
29
>
switch (status) {
30
>
case 'inProgress': return 'in_progress';
31
>
case 'timedOut': return 'timed_out';
32
>
// `approved`, `denied`, `aborted` are identical in both casings.
33
>
default: return status;
34
>
}
35
>
}
37
>
/** camelCase {@link GuardianCommandSource} value -> snake_case. */
38
function commandSourceToEvent(source: string): string {
39
return source === 'unifiedExec' ? 'unified_exec' : source;
40
}
42
>
/** camelCase {@link NetworkApprovalProtocol} value -> snake_case. */
44
>
switch (protocol) {
45
>
case 'socks5Tcp': return 'socks5_tcp';
46
>
case 'socks5Udp': return 'socks5_udp';
47
>
// `http`, `https` are identical in both casings.
48
>
default: return protocol;
49
>
}
50
>
}
52
>
/**
53
>
* camelCase {@link RequestPermissionProfile} -> snake_case. The `network`
54
>
* profile (`{ enabled }`) is identical in both casings, but the file-system
55
>
* profile renames `fileSystem` -> `file_system` and `globScanMaxDepth` ->
56
>
* `glob_scan_max_depth`. Its `read`/`write`/`entries` members (and the entry
57
>
* `path`/`access` fields) are already snake_case in the notification, so they
58
>
* round-trip verbatim.
59
>
*/
60
>
function requestPermissionProfileToEvent(profile: RequestPermissionProfile): JsonValue {
codexGuardianReview.ts ×2
61
>
const fs = profile.fileSystem;
62
>
let fileSystem: JsonValue = null;
63
>
if (fs) {
64
>
const mapped: Record<string, JsonValue> = { read: fs.read, write: fs.write };
65
>
if (fs.globScanMaxDepth !== undefined) {
66
>
mapped.glob_scan_max_depth = fs.globScanMaxDepth;
67
>
}
68
>
if (fs.entries !== undefined) {
69
>
mapped.entries = fs.entries as JsonValue;
70
>
}
71
>
fileSystem = mapped;
72
>
}
73
>
return { network: profile.network as JsonValue, file_system: fileSystem };
74
>
}
76
>
/**
77
>
* Translate the camelCase notification action into the snake_case
78
>
* `GuardianAssessmentAction` (`#[serde(tag = "type", rename_all = "snake_case")]`)
79
>
* that `thread/approveGuardianDeniedAction` deserializes.
80
>
*/
81
>
export function guardianReviewActionToEventAction(action: GuardianApprovalReviewAction): JsonValue {
83
>
case 'command':
84
return { type: 'command', source: commandSourceToEvent(action.source), command: action.command, cwd: action.cwd };
86
return { type: 'execve', source: commandSourceToEvent(action.source), program: action.program, argv: action.argv, cwd: action.cwd };
88
return { type: 'apply_patch', cwd: action.cwd, files: action.files };
90
>
return { type: 'network_access', target: action.target, host: action.host, protocol: networkProtocolToEvent(action.protocol), port: action.port };
codexGuardianReview.ts ×5
92
return { type: 'mcp_tool_call', server: action.server, tool_name: action.toolName, connector_id: action.connectorId, connector_name: action.connectorName, tool_title: action.toolTitle };
94
>
return { type: 'request_permissions', reason: action.reason, permissions: requestPermissionProfileToEvent(action.permissions) };
codexGuardianReview.ts ×2
96
>
}
98
>
/**
99
>
* Build the snake_case `GuardianAssessmentEvent` JSON expected by
100
>
* `thread/approveGuardianDeniedAction` from a completed-review notification.
101
>
* Optional fields are omitted when absent (the Rust struct defaults them).
102
>
*/
103
>
export function toGuardianAssessmentEventJson(notification: ItemGuardianApprovalReviewCompletedNotification): JsonValue {
105
>
id: notification.reviewId,
106
>
turn_id: notification.turnId,
107
>
started_at_ms: notification.startedAtMs,
108
>
status: guardianStatusToEvent(notification.review.status),
109
>
action: guardianReviewActionToEventAction(notification.action),
110
>
};
111
>
if (notification.targetItemId !== null) {
112
event.target_item_id = notification.targetItemId;
113
}
114
>
if (notification.completedAtMs !== null && notification.completedAtMs !== undefined) {
codexGuardianReview.ts ×13
115
>
event.completed_at_ms = notification.completedAtMs;
116
>
}
117
>
if (notification.review.riskLevel !== null) {
119
>
}
122
>
}
125
>
}
126
>
if (notification.decisionSource !== null && notification.decisionSource !== undefined) {
codexGuardianReview.ts ×13
127
>
event.decision_source = notification.decisionSource;
128
>
}
129
>
return event;
130
>
}
132
>
/** A human-readable summary of a reviewed action for the approval card. */
133
>
export interface IGuardianActionSummary {
134
>
/** Short title (e.g. `"Network access"`). */
135
>
readonly title: string;
136
>
/** Detail line describing the specific action (e.g. the command or host). */
137
>
readonly detail: string;
138
>
/** Closest matching tool kind for iconography, when one applies. */
139
>
readonly toolKind?: 'terminal' | 'search';
140
>
}
141
>
142
>
/** Summarise a review action for display on the denied-action approval card. */
143
>
export function summarizeGuardianReviewAction(action: GuardianApprovalReviewAction): IGuardianActionSummary {
145
>
case 'command':
146
>
// Display-only: unwrap the OS shell wrapper (`/bin/zsh -lc '…'`) so the
codexGuardianReview.ts ×2
147
>
// denial notice and "Approve anyway" card show the same clean command
148
>
// as the terminal pill. The raw action is still round-tripped verbatim
149
>
// to the app-server via toGuardianAssessmentEventJson on approval.
150
>
return { title: 'Run command', detail: unwrapShellInvocation(action.command), toolKind: 'terminal' };
152
>
return { title: 'Run program', detail: unwrapShellInvocation([action.program, ...action.argv].join(' ')), toolKind: 'terminal' };
codexGuardianReview.ts ×2
154
return { title: 'Apply file changes', detail: action.files.join(', ') };
156
>
return { title: 'Network access', detail: action.target || `${action.protocol}://${action.host}:${action.port}`, toolKind: 'search' };
codexGuardianReview.ts ×1
158
return { title: 'MCP tool call', detail: `${action.server}/${action.toolName}` };
160
return { title: 'Elevated permissions', detail: action.reason ?? 'Requested additional permissions' };
162
>
}
164
>
/** Escape the inline-code span so an embedded backtick can't break out of it. */
166
>
// Use a fence long enough to contain any run of backticks in the text, per
167
>
// CommonMark's variable-length code-span rule, and pad with spaces when the
168
>
// content itself starts/ends with a backtick.
169
>
const longestRun = (text.match(/`+/g) ?? []).reduce((max, run) => Math.max(max, run.length), 0);
170
>
const fence = '`'.repeat(longestRun + 1);
171
>
const padding = text.startsWith('`') || text.endsWith('`') ? ' ' : '';
172
>
return `${fence}${padding}${text}${padding}${fence}`;
173
>
}
175
>
/**
176
>
* Compose the durable denial notice for an auto-review denial, rendered as a
177
>
* Markdown response part (which survives turn completion and, unlike a transient
178
>
* progress/system-notification message, is not dropped by the live streaming
179
>
* path) so the user always learns *why* an action was blocked — including the
180
>
* reviewer rationale — even when the turn ends before the best-effort "Approve
181
>
* anyway" card can be acted on. The notice is emitted as a blockquote so it
182
>
* stays visually distinct from the model's own prose even when adjacent
183
>
* Markdown parts are concatenated into one rendered block.
184
>
*/
185
>
export function formatGuardianDenialNotification(summary: IGuardianActionSummary, rationale: string | null): string {
187
>
const header = '**Auto-review denied**';
188
>
const lines: string[] = [
189
>
detail
190
>
? `⚠️ ${header} — ${summary.title}: ${inlineCode(detail)}`
191
>
: `⚠️ ${header} — ${summary.title}`,
192
>
];
193
>
const reason = rationale?.trim();
194
>
if (reason) {
195
>
lines.push('', ...reason.split('\n'));
196
>
}
197
>
const quoted = lines.map(line => (line ? `> ${line}` : '>')).join('\n');
198
>
// Leading blank line separates the blockquote from any preceding Markdown
199
>
// part; trailing newline keeps subsequent model output on its own block.
200
>
return `\n\n${quoted}\n`;
201
>
}