1
>
/*---------------------------------------------------------------------------------------------
errors.ts
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
>
// allow-any-unicode-comment-file
7
>
// DO NOT EDIT -- auto-generated by scripts/sync-agent-host-protocol.ts
8
>
9
>
import type { ProtectedResourceMetadata } from './state.js';
10
>
import type { ResourceRequestParams } from './commands.js';
11
>
12
>
// ─── Standard JSON-RPC Codes ─────────────────────────────────────────────────
13
>
14
>
/**
15
>
* Standard JSON-RPC 2.0 error codes.
16
>
*
17
>
* @category Standard JSON-RPC Codes
18
>
*/
19
>
export const JsonRpcErrorCodes = {
20
>
/** Invalid JSON */
21
>
ParseError: -32700,
22
>
/** Not a valid JSON-RPC request */
23
>
InvalidRequest: -32600,
24
>
/** Unknown method name */
25
>
MethodNotFound: -32601,
26
>
/** Invalid method parameters */
27
>
InvalidParams: -32602,
28
>
/** Unspecified server error */
29
>
InternalError: -32603,
30
>
} as const;
31
>
32
>
// ─── AHP Application Codes ──────────────────────────────────────────────────
33
>
34
>
/**
35
>
* AHP application-specific error codes.
36
>
*
37
>
* @category AHP Application Codes
38
>
* @version 1
39
>
*/
40
>
export const AhpErrorCodes = {
41
>
/** The referenced session URI does not exist */
42
>
SessionNotFound: -32001,
43
>
/** The requested agent provider is not registered */
44
>
ProviderNotFound: -32002,
45
>
/** A session with the given URI already exists */
46
>
SessionAlreadyExists: -32003,
47
>
/** The operation requires no active turn, but one is in progress */
48
>
TurnInProgress: -32004,
49
>
/**
50
>
* The server cannot speak any of the protocol versions offered by the
51
>
* client in `InitializeParams.protocolVersions`. The `data` field of the
52
>
* JSON-RPC error MAY be an `UnsupportedProtocolVersionErrorData` advertising
53
>
* the protocol versions the server is willing to speak.
54
>
*/
55
>
UnsupportedProtocolVersion: -32005,
56
>
/** The requested content URI does not exist */
57
>
ContentNotFound: -32006,
58
>
/**
59
>
* A command failed because the client has not authenticated for a required
60
>
* protected resource. The `data` field of the JSON-RPC error MUST be an
61
>
* `AuthRequiredErrorData` describing the resources that require
62
>
* authentication.
63
>
*
64
>
* @see {@link /specification/authentication | Authentication}
65
>
*/
66
>
AuthRequired: -32007,
67
>
/** The requested file, folder, or URI does not exist */
68
>
NotFound: -32008,
69
>
/**
70
>
* The client is not permitted to access the requested resource.
71
>
*
72
>
* Servers SHOULD return this when a client attempts to read or browse
73
>
* a path outside the allowed set (e.g. outside the session's working
74
>
* directory or workspace roots).
75
>
*
76
>
* The `data` field of the JSON-RPC error MAY be a
77
>
* `PermissionDeniedErrorData` advertising a `resourceRequest` that, if
78
>
* granted, would unlock the operation.
79
>
*/
80
>
PermissionDenied: -32009,
81
>
/**
82
>
* The target resource already exists and the operation does not allow
83
>
* overwriting (e.g. `resourceWrite` with `createOnly: true`).
84
>
*/
85
>
AlreadyExists: -32010,
86
>
/**
87
>
* An optimistic-concurrency precondition failed.
88
>
*
89
>
* Returned when a request carries a precondition token that no longer
90
>
* matches the receiver's current state — for example, `resourceWrite`
91
>
* with an `ifMatch` etag that has been superseded by a concurrent
92
>
* write. Callers SHOULD re-read the resource (e.g. via
93
>
* `resourceResolve`) and decide whether to retry the operation with the
94
>
* fresh token or surface the conflict to the user.
95
>
*/
96
>
Conflict: -32011,
97
>
} as const;
98
>
99
>
/** Union type of all AHP application error codes. */
100
>
export type AhpErrorCode = (typeof AhpErrorCodes)[keyof typeof AhpErrorCodes];
101
>
102
>
/** Union type of all JSON-RPC error codes. */
103
>
export type JsonRpcErrorCode = (typeof JsonRpcErrorCodes)[keyof typeof JsonRpcErrorCodes];
104
>
105
>
// ─── Error Detail Types ──────────────────────────────────────────────────────
106
>
107
>
/**
108
>
* Details carried in the `data` field of an `AuthRequired` (-32007) error.
109
>
*
110
>
* Wraps the protected resource list in `{ resources: [...] }` rather than
111
>
* returning a bare array, so additional fields can be added in future
112
>
* versions without breaking the wire shape.
113
>
*
114
>
* @category Error Details
115
>
* @version 1
116
>
*/
117
>
export interface AuthRequiredErrorData {
118
>
/** Protected resources that require authentication. */
119
>
resources: ProtectedResourceMetadata[];
120
>
}
121
>
122
>
/**
123
>
* Details carried in the `data` field of a `PermissionDenied` (-32009) error.
124
>
*
125
>
* The receiver MAY advertise a `resourceRequest` payload describing the
126
>
* access that, if granted, would unlock the operation. The caller MAY then
127
>
* issue `resourceRequest` with that payload to negotiate access.
128
>
*
129
>
* @category Error Details
130
>
* @version 1
131
>
*/
132
>
export interface PermissionDeniedErrorData {
133
>
/**
134
>
* The resource access that, if granted via `resourceRequest`, would unlock
135
>
* the operation. Omitted when no specific access grant would resolve the
136
>
* denial (for example, when the resource is fundamentally inaccessible).
137
>
*/
138
>
request?: ResourceRequestParams;
139
>
}
140
>
141
>
/**
142
>
* Details carried in the `data` field of an `UnsupportedProtocolVersion`
143
>
* (-32005) error.
144
>
*
145
>
* @category Error Details
146
>
* @version 1
147
>
*/
148
>
export interface UnsupportedProtocolVersionErrorData {
149
>
/**
150
>
* Protocol versions the server is willing to speak.
151
>
*
152
>
* Each entry is either a [SemVer](https://semver.org) `MAJOR.MINOR.PATCH`
153
>
* string (e.g. `"0.1.0"`) or a [SemVer range](https://semver.org/#spec-item-11)
154
>
* constraint (e.g. `">=0.1.0 <0.3.0"` or `"^0.2.0"`).
155
>
*/
156
>
supportedVersions: string[];
157
>
}
158
>
159
>
/**
160
>
* Maps each AHP error code that carries structured `data` to the type of
161
>
* that data.
162
>
*
163
>
* Error codes not present in this map either have no `data` payload or
164
>
* carry an unspecified payload that callers SHOULD treat as `unknown`.
165
>
*
166
>
* @category Error Details
167
>
* @version 1
168
>
*/
169
>
export interface AhpErrorDetailsMap {
170
>
[AhpErrorCodes.AuthRequired]: AuthRequiredErrorData;
171
>
[AhpErrorCodes.PermissionDenied]: PermissionDeniedErrorData;
172
>
[AhpErrorCodes.UnsupportedProtocolVersion]: UnsupportedProtocolVersionErrorData;
173
>
}
174
>
175
>
/** AHP error codes that carry a structured `data` payload. */
176
>
export type AhpErrorCodeWithData = keyof AhpErrorDetailsMap;
177
>
178
>
/**
179
>
* A typed JSON-RPC error object whose `data` is narrowed by `code`.
180
>
*
181
>
* Distributes over the `AhpErrorCode` union so narrowing on `code` reveals
182
>
* the precise `data` type. For codes listed in {@link AhpErrorDetailsMap}
183
>
* `data` is required; for all other codes `data` is an optional `unknown`.
184
>
*
185
>
* ```ts
186
>
* function handle(err: AhpError) {
187
>
* if (err.code === AhpErrorCodes.PermissionDenied) {
188
>
* err.data.request; // typed as ResourceRequestParams | undefined
189
>
* }
190
>
* }
191
>
* ```
192
>
*
193
>
* @category Error Details
194
>
* @version 1
195
>
*/
196
>
export type AhpError<C extends AhpErrorCode = AhpErrorCode> =
197
>
C extends AhpErrorCode
198
>
? C extends keyof AhpErrorDetailsMap
199
>
? {
200
>
/** The error code. */
201
>
readonly code: C;
202
>
/** Human-readable error message. */
203
>
readonly message: string;
204
>
/** Structured detail payload mandated by `AhpErrorDetailsMap`. */
205
>
readonly data: AhpErrorDetailsMap[C];
206
>
}
207
>
: {
208
>
/** The error code. */
209
>
readonly code: C;
210
>
/** Human-readable error message. */
211
>
readonly message: string;
212
>
/** Optional, unspecified detail payload. */
213
>
readonly data?: unknown;
214
>
}
215
>
: never;