@aexhq/sdk 0.24.0 → 0.25.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +36 -125
- package/dist/_contracts/index.d.ts +0 -1
- package/dist/_contracts/index.js +0 -1
- package/dist/_contracts/models.js +1 -2
- package/dist/_contracts/operations.d.ts +13 -5
- package/dist/_contracts/operations.js +220 -10
- package/dist/_contracts/provider-support.d.ts +18 -29
- package/dist/_contracts/provider-support.js +3 -22
- package/dist/_contracts/proxy-protocol.d.ts +4 -2
- package/dist/_contracts/proxy-protocol.js +10 -3
- package/dist/_contracts/run-config.d.ts +28 -4
- package/dist/_contracts/run-config.js +10 -5
- package/dist/_contracts/run-cost.d.ts +3 -11
- package/dist/_contracts/run-cost.js +2 -57
- package/dist/_contracts/run-custody.d.ts +1 -52
- package/dist/_contracts/run-custody.js +3 -87
- package/dist/_contracts/run-retention.d.ts +1 -5
- package/dist/_contracts/run-retention.js +2 -14
- package/dist/_contracts/run-unit.d.ts +2 -2
- package/dist/_contracts/run-unit.js +3 -1
- package/dist/_contracts/runtime-security-profile.js +1 -1
- package/dist/_contracts/runtime-types.d.ts +38 -12
- package/dist/_contracts/side-effect-audit.d.ts +4 -5
- package/dist/_contracts/side-effect-audit.js +1 -4
- package/dist/_contracts/status.d.ts +3 -4
- package/dist/_contracts/status.js +3 -8
- package/dist/_contracts/submission.d.ts +68 -42
- package/dist/_contracts/submission.js +144 -30
- package/dist/bundle.d.ts +13 -0
- package/dist/bundle.js +51 -0
- package/dist/bundle.js.map +1 -1
- package/dist/cli.mjs +232 -58
- package/dist/cli.mjs.sha256 +1 -1
- package/dist/client.d.ts +25 -21
- package/dist/client.js +59 -15
- package/dist/client.js.map +1 -1
- package/dist/index.d.ts +6 -5
- package/dist/index.js +4 -3
- package/dist/index.js.map +1 -1
- package/dist/tool.d.ts +41 -0
- package/dist/tool.js +138 -0
- package/dist/tool.js.map +1 -0
- package/dist/version.d.ts +1 -1
- package/dist/version.js +1 -1
- package/docs/concepts/agent-tools.md +53 -0
- package/docs/concepts/composition.md +43 -0
- package/docs/concepts/providers-and-runtimes.md +53 -0
- package/docs/concepts/runs.md +40 -0
- package/docs/credentials.md +8 -4
- package/docs/events.md +12 -0
- package/docs/limits.md +53 -0
- package/docs/outputs.md +58 -0
- package/docs/provider-runtime-capabilities.md +53 -55
- package/docs/public-surface.json +81 -0
- package/docs/quickstart.md +28 -105
- package/docs/release.md +1 -1
- package/docs/run-config.md +2 -2
- package/docs/secrets.md +123 -0
- package/docs/skills.md +3 -3
- package/docs/vision-skills.md +14 -19
- package/package.json +2 -2
- package/dist/_contracts/managed-key.d.ts +0 -101
- package/dist/_contracts/managed-key.js +0 -181
- package/docs/product-boundaries.md +0 -57
|
@@ -1,6 +1,4 @@
|
|
|
1
1
|
import type { RunProvider, RuntimeKind } from "./submission.js";
|
|
2
|
-
export declare const PROVIDER_SUPPORT_STATUSES: readonly ["supported", "live-unverified", "rejected"];
|
|
3
|
-
export type ProviderSupportStatus = (typeof PROVIDER_SUPPORT_STATUSES)[number];
|
|
4
2
|
export interface SupportPointer {
|
|
5
3
|
readonly label: string;
|
|
6
4
|
/** Markdown href, relative to `packages/sdk/docs/provider-runtime-capabilities.md`. */
|
|
@@ -8,7 +6,6 @@ export interface SupportPointer {
|
|
|
8
6
|
}
|
|
9
7
|
export interface ProviderPublicSupport {
|
|
10
8
|
readonly displayName: string;
|
|
11
|
-
readonly status: ProviderSupportStatus;
|
|
12
9
|
readonly docsAnchor: string;
|
|
13
10
|
readonly docs: readonly SupportPointer[];
|
|
14
11
|
readonly evidence: readonly SupportPointer[];
|
|
@@ -36,17 +33,16 @@ export declare const RUNTIME_VALIDATION_SUPPORT: {
|
|
|
36
33
|
};
|
|
37
34
|
/**
|
|
38
35
|
* Public provider support facts for generated SDK docs. Keep this metadata
|
|
39
|
-
* public-facing only: provider names,
|
|
40
|
-
*
|
|
36
|
+
* public-facing only: provider names, docs anchors, and evidence pointers.
|
|
37
|
+
* Inclusion in this registry means the provider is supported.
|
|
41
38
|
*/
|
|
42
39
|
export declare const PROVIDER_PUBLIC_SUPPORT: {
|
|
43
40
|
readonly anthropic: {
|
|
44
41
|
readonly displayName: "Anthropic";
|
|
45
|
-
readonly status: "supported";
|
|
46
42
|
readonly docsAnchor: "anthropic";
|
|
47
43
|
readonly docs: readonly [{
|
|
48
|
-
readonly label: "
|
|
49
|
-
readonly href: "
|
|
44
|
+
readonly label: "Secrets";
|
|
45
|
+
readonly href: "secrets.md";
|
|
50
46
|
}, {
|
|
51
47
|
readonly label: "Events";
|
|
52
48
|
readonly href: "events.md";
|
|
@@ -79,11 +75,10 @@ export declare const PROVIDER_PUBLIC_SUPPORT: {
|
|
|
79
75
|
};
|
|
80
76
|
readonly deepseek: {
|
|
81
77
|
readonly displayName: "DeepSeek";
|
|
82
|
-
readonly status: "supported";
|
|
83
78
|
readonly docsAnchor: "deepseek";
|
|
84
79
|
readonly docs: readonly [{
|
|
85
|
-
readonly label: "
|
|
86
|
-
readonly href: "
|
|
80
|
+
readonly label: "Secrets";
|
|
81
|
+
readonly href: "secrets.md";
|
|
87
82
|
}, {
|
|
88
83
|
readonly label: "Events";
|
|
89
84
|
readonly href: "events.md";
|
|
@@ -122,11 +117,10 @@ export declare const PROVIDER_PUBLIC_SUPPORT: {
|
|
|
122
117
|
};
|
|
123
118
|
readonly openai: {
|
|
124
119
|
readonly displayName: "OpenAI";
|
|
125
|
-
readonly status: "live-unverified";
|
|
126
120
|
readonly docsAnchor: "openai";
|
|
127
121
|
readonly docs: readonly [{
|
|
128
|
-
readonly label: "
|
|
129
|
-
readonly href: "
|
|
122
|
+
readonly label: "Secrets";
|
|
123
|
+
readonly href: "secrets.md";
|
|
130
124
|
}, {
|
|
131
125
|
readonly label: "Events";
|
|
132
126
|
readonly href: "events.md";
|
|
@@ -156,11 +150,10 @@ export declare const PROVIDER_PUBLIC_SUPPORT: {
|
|
|
156
150
|
};
|
|
157
151
|
readonly gemini: {
|
|
158
152
|
readonly displayName: "Gemini";
|
|
159
|
-
readonly status: "live-unverified";
|
|
160
153
|
readonly docsAnchor: "gemini";
|
|
161
154
|
readonly docs: readonly [{
|
|
162
|
-
readonly label: "
|
|
163
|
-
readonly href: "
|
|
155
|
+
readonly label: "Secrets";
|
|
156
|
+
readonly href: "secrets.md";
|
|
164
157
|
}, {
|
|
165
158
|
readonly label: "Events";
|
|
166
159
|
readonly href: "events.md";
|
|
@@ -190,11 +183,10 @@ export declare const PROVIDER_PUBLIC_SUPPORT: {
|
|
|
190
183
|
};
|
|
191
184
|
readonly mistral: {
|
|
192
185
|
readonly displayName: "Mistral";
|
|
193
|
-
readonly status: "live-unverified";
|
|
194
186
|
readonly docsAnchor: "mistral";
|
|
195
187
|
readonly docs: readonly [{
|
|
196
|
-
readonly label: "
|
|
197
|
-
readonly href: "
|
|
188
|
+
readonly label: "Secrets";
|
|
189
|
+
readonly href: "secrets.md";
|
|
198
190
|
}, {
|
|
199
191
|
readonly label: "Events";
|
|
200
192
|
readonly href: "events.md";
|
|
@@ -224,11 +216,10 @@ export declare const PROVIDER_PUBLIC_SUPPORT: {
|
|
|
224
216
|
};
|
|
225
217
|
readonly openrouter: {
|
|
226
218
|
readonly displayName: "OpenRouter";
|
|
227
|
-
readonly status: "live-unverified";
|
|
228
219
|
readonly docsAnchor: "openrouter";
|
|
229
220
|
readonly docs: readonly [{
|
|
230
|
-
readonly label: "
|
|
231
|
-
readonly href: "
|
|
221
|
+
readonly label: "Secrets";
|
|
222
|
+
readonly href: "secrets.md";
|
|
232
223
|
}, {
|
|
233
224
|
readonly label: "Events";
|
|
234
225
|
readonly href: "events.md";
|
|
@@ -258,11 +249,10 @@ export declare const PROVIDER_PUBLIC_SUPPORT: {
|
|
|
258
249
|
};
|
|
259
250
|
readonly doubao: {
|
|
260
251
|
readonly displayName: "Doubao";
|
|
261
|
-
readonly status: "live-unverified";
|
|
262
252
|
readonly docsAnchor: "doubao";
|
|
263
253
|
readonly docs: readonly [{
|
|
264
|
-
readonly label: "
|
|
265
|
-
readonly href: "
|
|
254
|
+
readonly label: "Secrets";
|
|
255
|
+
readonly href: "secrets.md";
|
|
266
256
|
}, {
|
|
267
257
|
readonly label: "Events";
|
|
268
258
|
readonly href: "events.md";
|
|
@@ -292,11 +282,10 @@ export declare const PROVIDER_PUBLIC_SUPPORT: {
|
|
|
292
282
|
};
|
|
293
283
|
readonly "doubao-cn": {
|
|
294
284
|
readonly displayName: "Doubao (China)";
|
|
295
|
-
readonly status: "live-unverified";
|
|
296
285
|
readonly docsAnchor: "doubao-cn";
|
|
297
286
|
readonly docs: readonly [{
|
|
298
|
-
readonly label: "
|
|
299
|
-
readonly href: "
|
|
287
|
+
readonly label: "Secrets";
|
|
288
|
+
readonly href: "secrets.md";
|
|
300
289
|
}, {
|
|
301
290
|
readonly label: "Events";
|
|
302
291
|
readonly href: "events.md";
|
|
@@ -1,10 +1,5 @@
|
|
|
1
|
-
export const PROVIDER_SUPPORT_STATUSES = [
|
|
2
|
-
"supported",
|
|
3
|
-
"live-unverified",
|
|
4
|
-
"rejected"
|
|
5
|
-
];
|
|
6
1
|
const COMMON_DOCS = [
|
|
7
|
-
{ label: "
|
|
2
|
+
{ label: "Secrets", href: "secrets.md" },
|
|
8
3
|
{ label: "Events", href: "events.md" }
|
|
9
4
|
];
|
|
10
5
|
const COMMON_EVIDENCE = [
|
|
@@ -46,13 +41,12 @@ export const RUNTIME_VALIDATION_SUPPORT = {
|
|
|
46
41
|
};
|
|
47
42
|
/**
|
|
48
43
|
* Public provider support facts for generated SDK docs. Keep this metadata
|
|
49
|
-
* public-facing only: provider names,
|
|
50
|
-
*
|
|
44
|
+
* public-facing only: provider names, docs anchors, and evidence pointers.
|
|
45
|
+
* Inclusion in this registry means the provider is supported.
|
|
51
46
|
*/
|
|
52
47
|
export const PROVIDER_PUBLIC_SUPPORT = {
|
|
53
48
|
anthropic: {
|
|
54
49
|
displayName: "Anthropic",
|
|
55
|
-
status: "supported",
|
|
56
50
|
docsAnchor: "anthropic",
|
|
57
51
|
docs: COMMON_DOCS,
|
|
58
52
|
evidence: [...COMMON_EVIDENCE, ...ANTHROPIC_MANAGED_EVIDENCE],
|
|
@@ -62,7 +56,6 @@ export const PROVIDER_PUBLIC_SUPPORT = {
|
|
|
62
56
|
},
|
|
63
57
|
deepseek: {
|
|
64
58
|
displayName: "DeepSeek",
|
|
65
|
-
status: "supported",
|
|
66
59
|
docsAnchor: "deepseek",
|
|
67
60
|
docs: COMMON_DOCS,
|
|
68
61
|
evidence: [...COMMON_EVIDENCE, ...DEEPSEEK_MANAGED_EVIDENCE],
|
|
@@ -72,7 +65,6 @@ export const PROVIDER_PUBLIC_SUPPORT = {
|
|
|
72
65
|
},
|
|
73
66
|
openai: {
|
|
74
67
|
displayName: "OpenAI",
|
|
75
|
-
status: "live-unverified",
|
|
76
68
|
docsAnchor: "openai",
|
|
77
69
|
docs: COMMON_DOCS,
|
|
78
70
|
evidence: COMMON_EVIDENCE,
|
|
@@ -82,7 +74,6 @@ export const PROVIDER_PUBLIC_SUPPORT = {
|
|
|
82
74
|
},
|
|
83
75
|
gemini: {
|
|
84
76
|
displayName: "Gemini",
|
|
85
|
-
status: "live-unverified",
|
|
86
77
|
docsAnchor: "gemini",
|
|
87
78
|
docs: COMMON_DOCS,
|
|
88
79
|
evidence: COMMON_EVIDENCE,
|
|
@@ -92,7 +83,6 @@ export const PROVIDER_PUBLIC_SUPPORT = {
|
|
|
92
83
|
},
|
|
93
84
|
mistral: {
|
|
94
85
|
displayName: "Mistral",
|
|
95
|
-
status: "live-unverified",
|
|
96
86
|
docsAnchor: "mistral",
|
|
97
87
|
docs: COMMON_DOCS,
|
|
98
88
|
evidence: COMMON_EVIDENCE,
|
|
@@ -102,7 +92,6 @@ export const PROVIDER_PUBLIC_SUPPORT = {
|
|
|
102
92
|
},
|
|
103
93
|
openrouter: {
|
|
104
94
|
displayName: "OpenRouter",
|
|
105
|
-
status: "live-unverified",
|
|
106
95
|
docsAnchor: "openrouter",
|
|
107
96
|
docs: COMMON_DOCS,
|
|
108
97
|
evidence: COMMON_EVIDENCE,
|
|
@@ -111,13 +100,8 @@ export const PROVIDER_PUBLIC_SUPPORT = {
|
|
|
111
100
|
}
|
|
112
101
|
},
|
|
113
102
|
// Doubao (ByteDance) via the official Ark API — international BytePlus gateway.
|
|
114
|
-
// Wired + parser/routing-verified but not yet proven against a live BytePlus
|
|
115
|
-
// account, so `live-unverified`. Promote to `supported` (and swap COMMON_EVIDENCE
|
|
116
|
-
// for a DOUBAO_MANAGED_EVIDENCE pointer to live-sdk-doubao.test.ts) once the
|
|
117
|
-
// live run passes.
|
|
118
103
|
doubao: {
|
|
119
104
|
displayName: "Doubao",
|
|
120
|
-
status: "live-unverified",
|
|
121
105
|
docsAnchor: "doubao",
|
|
122
106
|
docs: COMMON_DOCS,
|
|
123
107
|
evidence: COMMON_EVIDENCE,
|
|
@@ -126,11 +110,8 @@ export const PROVIDER_PUBLIC_SUPPORT = {
|
|
|
126
110
|
}
|
|
127
111
|
},
|
|
128
112
|
// Doubao (ByteDance) via the official Ark API — China Volcengine gateway.
|
|
129
|
-
// Same wiring as `doubao`; additionally gated on CF Worker egress reaching the
|
|
130
|
-
// Beijing host (see apps/egress-probe). `live-unverified` until proven live.
|
|
131
113
|
"doubao-cn": {
|
|
132
114
|
displayName: "Doubao (China)",
|
|
133
|
-
status: "live-unverified",
|
|
134
115
|
docsAnchor: "doubao-cn",
|
|
135
116
|
docs: COMMON_DOCS,
|
|
136
117
|
evidence: COMMON_EVIDENCE,
|
|
@@ -134,14 +134,16 @@ export interface ProxyIndexEntry {
|
|
|
134
134
|
* default. A customer can opt into a per-response truncation cap by setting a
|
|
135
135
|
* positive value. There is no cumulative per-run call/byte budget: it needed a
|
|
136
136
|
* per-call counter on the hot path and only existed to bound memory, which
|
|
137
|
-
* streaming already does.
|
|
137
|
+
* streaming already does. The platform records named-proxy request bytes,
|
|
138
|
+
* response bytes, attempts, and retries as run-log usage telemetry only; no
|
|
139
|
+
* pricing/charging model is derived here.
|
|
138
140
|
*/
|
|
139
141
|
export declare const PROXY_ENDPOINT_DEFAULTS: {
|
|
140
142
|
readonly allowHeaders: readonly string[];
|
|
141
143
|
readonly responseMode: ProxyResponseMode;
|
|
142
144
|
readonly maxRequestBytes: number;
|
|
143
145
|
readonly maxResponseBytes: 0;
|
|
144
|
-
readonly timeoutMs:
|
|
146
|
+
readonly timeoutMs: number;
|
|
145
147
|
};
|
|
146
148
|
/**
|
|
147
149
|
* Non-secret endpoint policy the index builder consumes. Structurally a
|
|
@@ -140,16 +140,23 @@ export const PROXY_ERROR_CODES = [
|
|
|
140
140
|
* default. A customer can opt into a per-response truncation cap by setting a
|
|
141
141
|
* positive value. There is no cumulative per-run call/byte budget: it needed a
|
|
142
142
|
* per-call counter on the hot path and only existed to bound memory, which
|
|
143
|
-
* streaming already does.
|
|
143
|
+
* streaming already does. The platform records named-proxy request bytes,
|
|
144
|
+
* response bytes, attempts, and retries as run-log usage telemetry only; no
|
|
145
|
+
* pricing/charging model is derived here.
|
|
144
146
|
*/
|
|
145
147
|
export const PROXY_ENDPOINT_DEFAULTS = {
|
|
146
148
|
allowHeaders: [],
|
|
147
149
|
responseMode: "headers_only",
|
|
148
|
-
|
|
150
|
+
// 10 MiB. The body is buffered into the Worker to enforce this cap, while the
|
|
151
|
+
// launch default fits practical multimodal/tool POSTs without every endpoint
|
|
152
|
+
// needing an override.
|
|
153
|
+
maxRequestBytes: 10 * 1024 * 1024,
|
|
149
154
|
// Unlimited (0). The request body is buffered to enforce its cap, so that
|
|
150
155
|
// stays finite; the response is streamed, so it does not need one.
|
|
151
156
|
maxResponseBytes: 0,
|
|
152
|
-
|
|
157
|
+
// 5 minutes. Long-running upstream tool/model calls should not fail under a
|
|
158
|
+
// development-oriented 10s ceiling; endpoints can still set a smaller value.
|
|
159
|
+
timeoutMs: 5 * 60 * 1000
|
|
153
160
|
};
|
|
154
161
|
/**
|
|
155
162
|
* Build the per-run {@link ProxyIndexFile} mounted into the container at
|
|
@@ -47,6 +47,12 @@ export declare const SKILL_ID_PATTERN: RegExp;
|
|
|
47
47
|
* surface so callers fail at the boundary rather than in the BFF.
|
|
48
48
|
*/
|
|
49
49
|
export declare const SKILL_NAME_PATTERN: RegExp;
|
|
50
|
+
/**
|
|
51
|
+
* Provider-safe submitted tool name. Tool names share the same lowercase
|
|
52
|
+
* kebab/underscore envelope as skills. Submission parsing rejects `__`
|
|
53
|
+
* because SessionDO reserves that separator for MCP namespace routing.
|
|
54
|
+
*/
|
|
55
|
+
export declare const TOOL_NAME_PATTERN: RegExp;
|
|
50
56
|
/**
|
|
51
57
|
* Hard caps applied at upload time. The SDK enforces these before
|
|
52
58
|
* computing the zip hash so a clearly-too-big bundle never wastes
|
|
@@ -87,6 +93,23 @@ export interface AssetRef {
|
|
|
87
93
|
readonly name: string;
|
|
88
94
|
readonly mountPath?: string;
|
|
89
95
|
}
|
|
96
|
+
type ToolJsonPrimitive = string | number | boolean | null;
|
|
97
|
+
type ToolJsonValue = ToolJsonPrimitive | ToolJsonValue[] | {
|
|
98
|
+
readonly [key: string]: ToolJsonValue;
|
|
99
|
+
};
|
|
100
|
+
export type ToolInputSchema = {
|
|
101
|
+
readonly [key: string]: ToolJsonValue;
|
|
102
|
+
};
|
|
103
|
+
/**
|
|
104
|
+
* User-supplied executable tool bundle. The bytes are addressed by the same
|
|
105
|
+
* content-addressed asset ref used by Skills/Files, while the provider-visible
|
|
106
|
+
* manifest rides as value-free metadata on the submission.
|
|
107
|
+
*/
|
|
108
|
+
export interface ToolRef extends AssetRef {
|
|
109
|
+
readonly description: string;
|
|
110
|
+
readonly input_schema: ToolInputSchema;
|
|
111
|
+
readonly entry: string;
|
|
112
|
+
}
|
|
90
113
|
export interface ProviderSkillRef {
|
|
91
114
|
readonly kind: "provider";
|
|
92
115
|
readonly vendor: "anthropic" | "custom";
|
|
@@ -141,10 +164,10 @@ export declare function parseSkillRef(input: unknown, path: string): SkillRef;
|
|
|
141
164
|
*/
|
|
142
165
|
export declare function parseAssetRefFields(record: Record<string, unknown>, path: string): AssetRef;
|
|
143
166
|
/**
|
|
144
|
-
* Manifest entry persisted in `skill_bundles.manifest` and
|
|
145
|
-
*
|
|
146
|
-
*
|
|
147
|
-
*
|
|
167
|
+
* Manifest entry persisted in `skill_bundles.manifest` and in run-owned
|
|
168
|
+
* snapshots. `path` is forward-slash, relative, normalised. `mode` is the
|
|
169
|
+
* stored POSIX mode (sanitised, NOT the user's filesystem mode) — see
|
|
170
|
+
* `SKILL_BUNDLE_LIMITS.defaultFileMode`.
|
|
148
171
|
*/
|
|
149
172
|
export interface SkillBundleEntry {
|
|
150
173
|
readonly path: string;
|
|
@@ -330,3 +353,4 @@ export interface NormalisedRunRequestConfig {
|
|
|
330
353
|
}>;
|
|
331
354
|
}
|
|
332
355
|
export declare function normaliseRunRequestConfig(config: RunRequestConfig): NormalisedRunRequestConfig;
|
|
356
|
+
export {};
|
|
@@ -48,6 +48,12 @@ export const SKILL_ID_PATTERN = /^skl_[A-Za-z0-9_-]{8,128}$/;
|
|
|
48
48
|
* surface so callers fail at the boundary rather than in the BFF.
|
|
49
49
|
*/
|
|
50
50
|
export const SKILL_NAME_PATTERN = /^[a-z0-9][a-z0-9_-]{0,127}$/;
|
|
51
|
+
/**
|
|
52
|
+
* Provider-safe submitted tool name. Tool names share the same lowercase
|
|
53
|
+
* kebab/underscore envelope as skills. Submission parsing rejects `__`
|
|
54
|
+
* because SessionDO reserves that separator for MCP namespace routing.
|
|
55
|
+
*/
|
|
56
|
+
export const TOOL_NAME_PATTERN = SKILL_NAME_PATTERN;
|
|
51
57
|
// ---------------------------------------------------------------------------
|
|
52
58
|
// Skill bundle limits (uploaded bundles)
|
|
53
59
|
// ---------------------------------------------------------------------------
|
|
@@ -465,11 +471,10 @@ export function rejectStdioMcpShape(record) {
|
|
|
465
471
|
/**
|
|
466
472
|
* Reasons an IP-literal host should be refused. Returns null when the
|
|
467
473
|
* literal is a routable public address (or not an IP literal at all — name
|
|
468
|
-
* resolution is the caller's concern). This
|
|
469
|
-
*
|
|
470
|
-
*
|
|
471
|
-
*
|
|
472
|
-
* `submission.parseProxyBaseUrl` all classify the same bytes.
|
|
474
|
+
* resolution is the caller's concern). This numeric-range deny-list is kept
|
|
475
|
+
* in parity across the public contract parser and platform shared parser so
|
|
476
|
+
* the MCP parser, BYOK proxy handlers, and `submission.parseProxyBaseUrl`
|
|
477
|
+
* classify the same bytes.
|
|
473
478
|
*
|
|
474
479
|
* `host` is the already-bracket-stripped, lowercased hostname.
|
|
475
480
|
*
|
|
@@ -1,14 +1,13 @@
|
|
|
1
|
-
import type { CredentialMode } from "./
|
|
2
|
-
import type { RunProvider, RuntimeKind } from "./submission.js";
|
|
1
|
+
import type { CredentialMode, RunProvider, RuntimeKind } from "./submission.js";
|
|
3
2
|
export declare const RUN_COST_TELEMETRY_SCHEMA_VERSION = 1;
|
|
4
3
|
export declare const RUN_USAGE_SAMPLE_SCHEMA_VERSION = 1;
|
|
5
4
|
export declare const RUN_COST_SUMMARY_STATUSES: readonly ["pending", "partial", "complete", "unavailable", "not_applicable"];
|
|
6
5
|
export type RunCostSummaryStatus = (typeof RUN_COST_SUMMARY_STATUSES)[number];
|
|
7
6
|
export declare const RUN_USAGE_SAMPLE_UNITS: readonly ["token", "millisecond", "byte", "byte_millisecond", "count", "file", "credit_unit"];
|
|
8
7
|
export type RunUsageSampleUnit = (typeof RUN_USAGE_SAMPLE_UNITS)[number];
|
|
9
|
-
export declare const RUN_USAGE_SAMPLE_SOURCE_TYPES: readonly ["coordinator-event", "run-event", "usage-ledger", "output-object", "proxy-call", "runtime-job", "provider-session", "storage-accrual", "
|
|
8
|
+
export declare const RUN_USAGE_SAMPLE_SOURCE_TYPES: readonly ["coordinator-event", "run-event", "usage-ledger", "output-object", "proxy-call", "runtime-job", "provider-session", "storage-accrual", "manual-adjustment"];
|
|
10
9
|
export type RunUsageSampleSourceType = (typeof RUN_USAGE_SAMPLE_SOURCE_TYPES)[number];
|
|
11
|
-
export declare const RUN_USAGE_SAMPLE_METRICS: readonly ["provider.input_tokens", "provider.output_tokens", "provider.cache_read_input_tokens", "provider.cache_creation_input_tokens", "provider.total_tokens", "runtime.queued_ms", "runtime.active_ms", "runtime.output_capture_ms", "runtime.cleanup_ms", "run.total_ms", "output.discovered_files", "output.captured_files", "output.failed_files", "output.captured_bytes", "retry.runtime_attempts", "retry.provider_poll", "retry.output_capture", "retry.output_upload", "capture.uploaded_files", "capture.failed_files", "capture.total_bytes", "storage.current_bytes", "storage.byte_milliseconds", "proxy.call_count", "proxy.failed_call_count", "proxy.request_bytes", "proxy.response_bytes", "proxy.duration_ms"
|
|
10
|
+
export declare const RUN_USAGE_SAMPLE_METRICS: readonly ["provider.input_tokens", "provider.output_tokens", "provider.cache_read_input_tokens", "provider.cache_creation_input_tokens", "provider.total_tokens", "runtime.queued_ms", "runtime.active_ms", "runtime.output_capture_ms", "runtime.cleanup_ms", "run.total_ms", "output.discovered_files", "output.captured_files", "output.failed_files", "output.captured_bytes", "retry.runtime_attempts", "retry.provider_poll", "retry.output_capture", "retry.output_upload", "capture.uploaded_files", "capture.failed_files", "capture.total_bytes", "storage.current_bytes", "storage.byte_milliseconds", "proxy.call_count", "proxy.failed_call_count", "proxy.request_bytes", "proxy.response_bytes", "proxy.duration_ms"];
|
|
12
11
|
export type RunUsageSampleMetric = (typeof RUN_USAGE_SAMPLE_METRICS)[number];
|
|
13
12
|
export interface RunUsageSampleSource {
|
|
14
13
|
readonly type: RunUsageSampleSourceType;
|
|
@@ -86,12 +85,6 @@ export interface RunCostProxyTelemetry {
|
|
|
86
85
|
readonly responseBytes?: number;
|
|
87
86
|
readonly durationMs?: number;
|
|
88
87
|
}
|
|
89
|
-
export interface RunCostManagedKeyBudgetTelemetry {
|
|
90
|
-
readonly credentialMode?: CredentialMode;
|
|
91
|
-
readonly reservedCreditUnits?: number;
|
|
92
|
-
readonly chargedCreditUnits?: number;
|
|
93
|
-
readonly releasedCreditUnits?: number;
|
|
94
|
-
}
|
|
95
88
|
/**
|
|
96
89
|
* The basis for a {@link RunCostTelemetry.billedCostUsd}: an honest marker of
|
|
97
90
|
* whether the figure is a settle-time ESTIMATE or has been RECONCILED against
|
|
@@ -122,7 +115,6 @@ export interface RunCostTelemetry {
|
|
|
122
115
|
readonly providerUsage?: readonly RunCostProviderUsage[];
|
|
123
116
|
readonly storage?: RunCostStorageTelemetry;
|
|
124
117
|
readonly proxy?: RunCostProxyTelemetry;
|
|
125
|
-
readonly managedKey?: RunCostManagedKeyBudgetTelemetry;
|
|
126
118
|
/**
|
|
127
119
|
* Customer-facing AEX cost of serving this run, USD — a REPORTED ESTIMATE,
|
|
128
120
|
* not a charge (telemetry/showback only; no invoicing or credit deduction).
|
|
@@ -25,9 +25,6 @@ export const RUN_USAGE_SAMPLE_SOURCE_TYPES = [
|
|
|
25
25
|
"runtime-job",
|
|
26
26
|
"provider-session",
|
|
27
27
|
"storage-accrual",
|
|
28
|
-
"billing-reservation",
|
|
29
|
-
"billing-settlement",
|
|
30
|
-
"billing-release",
|
|
31
28
|
"manual-adjustment"
|
|
32
29
|
];
|
|
33
30
|
export const RUN_USAGE_SAMPLE_METRICS = [
|
|
@@ -58,10 +55,7 @@ export const RUN_USAGE_SAMPLE_METRICS = [
|
|
|
58
55
|
"proxy.failed_call_count",
|
|
59
56
|
"proxy.request_bytes",
|
|
60
57
|
"proxy.response_bytes",
|
|
61
|
-
"proxy.duration_ms"
|
|
62
|
-
"managed_key.reserved_credit_units",
|
|
63
|
-
"managed_key.charged_credit_units",
|
|
64
|
-
"managed_key.released_credit_units"
|
|
58
|
+
"proxy.duration_ms"
|
|
65
59
|
];
|
|
66
60
|
const RUN_USAGE_SAMPLE_METRIC_UNITS = {
|
|
67
61
|
"provider.input_tokens": "token",
|
|
@@ -91,10 +85,7 @@ const RUN_USAGE_SAMPLE_METRIC_UNITS = {
|
|
|
91
85
|
"proxy.failed_call_count": "count",
|
|
92
86
|
"proxy.request_bytes": "byte",
|
|
93
87
|
"proxy.response_bytes": "byte",
|
|
94
|
-
"proxy.duration_ms": "millisecond"
|
|
95
|
-
"managed_key.reserved_credit_units": "credit_unit",
|
|
96
|
-
"managed_key.charged_credit_units": "credit_unit",
|
|
97
|
-
"managed_key.released_credit_units": "credit_unit"
|
|
88
|
+
"proxy.duration_ms": "millisecond"
|
|
98
89
|
};
|
|
99
90
|
/**
|
|
100
91
|
* The basis for a {@link RunCostTelemetry.billedCostUsd}: an honest marker of
|
|
@@ -144,7 +135,6 @@ export function buildRunCostTelemetry(input) {
|
|
|
144
135
|
...(input.providerUsage ? { providerUsage: input.providerUsage.map(normalizeProviderUsage) } : {}),
|
|
145
136
|
...(input.storage ? { storage: normalizeStorage(input.storage) } : {}),
|
|
146
137
|
...(input.proxy ? { proxy: normalizeProxy(input.proxy) } : {}),
|
|
147
|
-
...(input.managedKey ? { managedKey: normalizeManagedKey(input.managedKey) } : {}),
|
|
148
138
|
...(input.billedCostUsd !== undefined ? { billedCostUsd: nonNegativeFinite(input.billedCostUsd, "billedCostUsd") } : {}),
|
|
149
139
|
...(input.costBasis ? { costBasis: normalizeCostBasis(input.costBasis) } : {})
|
|
150
140
|
});
|
|
@@ -170,10 +160,8 @@ export function buildRunCostTelemetryFromUsageSamples(input) {
|
|
|
170
160
|
const capture = {};
|
|
171
161
|
const storage = {};
|
|
172
162
|
const proxy = {};
|
|
173
|
-
const managedKey = {};
|
|
174
163
|
const providerUsage = new Map();
|
|
175
164
|
let captureAttempted = false;
|
|
176
|
-
let managedKeyCredentialMode;
|
|
177
165
|
for (const sample of samples) {
|
|
178
166
|
switch (sample.metric) {
|
|
179
167
|
case "provider.input_tokens":
|
|
@@ -263,18 +251,6 @@ export function buildRunCostTelemetryFromUsageSamples(input) {
|
|
|
263
251
|
case "proxy.duration_ms":
|
|
264
252
|
addDraftNumber(proxy, "durationMs", sample.quantity);
|
|
265
253
|
break;
|
|
266
|
-
case "managed_key.reserved_credit_units":
|
|
267
|
-
managedKeyCredentialMode = sample.credentialMode ?? managedKeyCredentialMode;
|
|
268
|
-
addDraftNumber(managedKey, "reservedCreditUnits", sample.quantity);
|
|
269
|
-
break;
|
|
270
|
-
case "managed_key.charged_credit_units":
|
|
271
|
-
managedKeyCredentialMode = sample.credentialMode ?? managedKeyCredentialMode;
|
|
272
|
-
addDraftNumber(managedKey, "chargedCreditUnits", sample.quantity);
|
|
273
|
-
break;
|
|
274
|
-
case "managed_key.released_credit_units":
|
|
275
|
-
managedKeyCredentialMode = sample.credentialMode ?? managedKeyCredentialMode;
|
|
276
|
-
addDraftNumber(managedKey, "releasedCreditUnits", sample.quantity);
|
|
277
|
-
break;
|
|
278
254
|
}
|
|
279
255
|
}
|
|
280
256
|
if (Object.keys(durations).length > 0)
|
|
@@ -293,12 +269,6 @@ export function buildRunCostTelemetryFromUsageSamples(input) {
|
|
|
293
269
|
telemetry.storage = storage;
|
|
294
270
|
if (Object.keys(proxy).length > 0)
|
|
295
271
|
telemetry.proxy = proxy;
|
|
296
|
-
if (Object.keys(managedKey).length > 0 || managedKeyCredentialMode) {
|
|
297
|
-
telemetry.managedKey = {
|
|
298
|
-
...(managedKeyCredentialMode ? { credentialMode: managedKeyCredentialMode } : {}),
|
|
299
|
-
...managedKey
|
|
300
|
-
};
|
|
301
|
-
}
|
|
302
272
|
return buildRunCostTelemetry(telemetry);
|
|
303
273
|
}
|
|
304
274
|
export function summarizeUsageSamples(samples) {
|
|
@@ -329,7 +299,6 @@ export function mergeRunCostTelemetry(base, next) {
|
|
|
329
299
|
const providerUsage = [...(base.providerUsage ?? []), ...(patch.providerUsage ?? [])];
|
|
330
300
|
const storage = sumStorage(base.storage, patch.storage);
|
|
331
301
|
const proxy = sumProxy(base.proxy, patch.proxy);
|
|
332
|
-
const managedKey = mergeManagedKey(base.managedKey, patch.managedKey);
|
|
333
302
|
// Derived cost fields are LAST-WRITER-WINS (a re-derivation supersedes the
|
|
334
303
|
// prior estimate), not summed — they are projections of the whole sample set,
|
|
335
304
|
// not additive metrics.
|
|
@@ -361,8 +330,6 @@ export function mergeRunCostTelemetry(base, next) {
|
|
|
361
330
|
merged.storage = storage;
|
|
362
331
|
if (proxy)
|
|
363
332
|
merged.proxy = proxy;
|
|
364
|
-
if (managedKey)
|
|
365
|
-
merged.managedKey = managedKey;
|
|
366
333
|
if (billedCostUsd !== undefined)
|
|
367
334
|
merged.billedCostUsd = billedCostUsd;
|
|
368
335
|
if (costBasis)
|
|
@@ -435,16 +402,6 @@ function normalizeProxy(input) {
|
|
|
435
402
|
durationMs: input.durationMs
|
|
436
403
|
});
|
|
437
404
|
}
|
|
438
|
-
function normalizeManagedKey(input) {
|
|
439
|
-
return Object.freeze({
|
|
440
|
-
...(input.credentialMode ? { credentialMode: input.credentialMode } : {}),
|
|
441
|
-
...freezeOptionalNumbers({
|
|
442
|
-
reservedCreditUnits: input.reservedCreditUnits,
|
|
443
|
-
chargedCreditUnits: input.chargedCreditUnits,
|
|
444
|
-
releasedCreditUnits: input.releasedCreditUnits
|
|
445
|
-
})
|
|
446
|
-
});
|
|
447
|
-
}
|
|
448
405
|
function normalizeSourceSummary(input) {
|
|
449
406
|
return Object.freeze({
|
|
450
407
|
sampleCount: nonNegativeFinite(input.sampleCount, "sourceSummary.sampleCount"),
|
|
@@ -599,18 +556,6 @@ function mergeCapture(base, next) {
|
|
|
599
556
|
...(failureReasons.length > 0 ? { failureReasons } : {})
|
|
600
557
|
});
|
|
601
558
|
}
|
|
602
|
-
function mergeManagedKey(base, next) {
|
|
603
|
-
if (!base && !next) {
|
|
604
|
-
return undefined;
|
|
605
|
-
}
|
|
606
|
-
const credentialMode = next?.credentialMode ?? base?.credentialMode;
|
|
607
|
-
return normalizeManagedKey({
|
|
608
|
-
...(credentialMode ? { credentialMode } : {}),
|
|
609
|
-
reservedCreditUnits: (base?.reservedCreditUnits ?? 0) + (next?.reservedCreditUnits ?? 0),
|
|
610
|
-
chargedCreditUnits: (base?.chargedCreditUnits ?? 0) + (next?.chargedCreditUnits ?? 0),
|
|
611
|
-
releasedCreditUnits: (base?.releasedCreditUnits ?? 0) + (next?.releasedCreditUnits ?? 0)
|
|
612
|
-
});
|
|
613
|
-
}
|
|
614
559
|
function mergeSourceSummary(base, next) {
|
|
615
560
|
if (!base && !next) {
|
|
616
561
|
return undefined;
|
|
@@ -1,11 +1,8 @@
|
|
|
1
|
-
import type { CredentialMode } from "./managed-key.js";
|
|
2
1
|
import type { RunStatus } from "./status.js";
|
|
3
|
-
import type { RunProvider, RuntimeKind } from "./submission.js";
|
|
2
|
+
import type { CredentialMode, RunProvider, RuntimeKind } from "./submission.js";
|
|
4
3
|
export declare const CUSTODY_MANIFEST_SCHEMA_VERSION = 1;
|
|
5
|
-
export declare const CUSTODY_TOMBSTONE_SCHEMA_VERSION = 1;
|
|
6
4
|
export declare const CUSTODY_REDACTION_SCANNER_VERSION = 1;
|
|
7
5
|
export declare const CUSTODY_MANIFEST_KIND = "aex.custody_manifest.v1";
|
|
8
|
-
export declare const CUSTODY_TOMBSTONE_KIND = "aex.custody_tombstone.v1";
|
|
9
6
|
export declare const CUSTODY_MANIFEST_CONTENT_TYPE = "application/json; charset=utf-8";
|
|
10
7
|
export declare const CUSTODY_MANIFEST_RUN_REL_PATH = "metadata/custody.json";
|
|
11
8
|
export declare const CUSTODY_SECRET_CLASSES: readonly ["provider_api_key", "mcp_credential", "proxy_endpoint_auth", "runner_bearer", "managed_system_credential"];
|
|
@@ -26,10 +23,6 @@ export declare const CUSTODY_EVIDENCE_SOURCES: readonly ["run_row", "runtime_man
|
|
|
26
23
|
export type CustodyEvidenceSource = (typeof CUSTODY_EVIDENCE_SOURCES)[number];
|
|
27
24
|
export declare const CUSTODY_MANIFEST_EXCLUDED_VALUE_CLASSES: readonly ["raw_secret_values", "bearer_hashes", "provider_response_bodies", "signed_urls", "object_store_keys", "vault_ids", "private_resource_handles"];
|
|
28
25
|
export type CustodyManifestExcludedValueClass = (typeof CUSTODY_MANIFEST_EXCLUDED_VALUE_CLASSES)[number];
|
|
29
|
-
export declare const CUSTODY_TOMBSTONE_MANIFEST_STATUSES: readonly ["written", "not_written", "write_failed", "purged"];
|
|
30
|
-
export type CustodyTombstoneManifestStatus = (typeof CUSTODY_TOMBSTONE_MANIFEST_STATUSES)[number];
|
|
31
|
-
export declare const CUSTODY_TOMBSTONE_DELETION_STATUSES: readonly ["not_deleted", "pending_delete", "deleted"];
|
|
32
|
-
export type CustodyTombstoneDeletionStatus = (typeof CUSTODY_TOMBSTONE_DELETION_STATUSES)[number];
|
|
33
26
|
export interface CustodyManifestRunV1 {
|
|
34
27
|
readonly runId: string;
|
|
35
28
|
readonly workspaceId: string;
|
|
@@ -137,48 +130,6 @@ export interface CustodyManifestInput {
|
|
|
137
130
|
readonly resources?: readonly CustodyManifestResourceClassInput[];
|
|
138
131
|
readonly cleanup?: CustodyManifestCleanupInput;
|
|
139
132
|
}
|
|
140
|
-
export interface CustodyTombstoneRunV1 {
|
|
141
|
-
readonly runId: string;
|
|
142
|
-
readonly workspaceId: string;
|
|
143
|
-
readonly terminalStatus: RunStatus | string;
|
|
144
|
-
readonly terminalAt?: string;
|
|
145
|
-
}
|
|
146
|
-
export interface CustodyTombstoneManifestV1 {
|
|
147
|
-
readonly schemaVersion: typeof CUSTODY_MANIFEST_SCHEMA_VERSION;
|
|
148
|
-
readonly status: CustodyTombstoneManifestStatus;
|
|
149
|
-
readonly generatedAt?: string;
|
|
150
|
-
readonly finalizedAt?: string;
|
|
151
|
-
readonly tombstonedAt: string;
|
|
152
|
-
}
|
|
153
|
-
export interface CustodyTombstoneDeletionV1 {
|
|
154
|
-
readonly status: CustodyTombstoneDeletionStatus;
|
|
155
|
-
readonly pendingAt?: string;
|
|
156
|
-
readonly deletedAt?: string;
|
|
157
|
-
}
|
|
158
|
-
export interface CustodyTombstoneRetentionV1 {
|
|
159
|
-
readonly defaultPolicy: "retain_indefinitely";
|
|
160
|
-
readonly userAction: "purge_or_anonymize_later";
|
|
161
|
-
}
|
|
162
|
-
export interface CustodyTombstoneV1 {
|
|
163
|
-
readonly schemaVersion: typeof CUSTODY_TOMBSTONE_SCHEMA_VERSION;
|
|
164
|
-
readonly kind: typeof CUSTODY_TOMBSTONE_KIND;
|
|
165
|
-
readonly run: CustodyTombstoneRunV1;
|
|
166
|
-
readonly manifest: CustodyTombstoneManifestV1;
|
|
167
|
-
readonly summary: CustodyManifestSummaryV1;
|
|
168
|
-
readonly deletion: CustodyTombstoneDeletionV1;
|
|
169
|
-
readonly retention: CustodyTombstoneRetentionV1;
|
|
170
|
-
}
|
|
171
|
-
export interface CustodyTombstoneInput {
|
|
172
|
-
readonly run: CustodyTombstoneRunV1;
|
|
173
|
-
readonly manifest: Omit<CustodyTombstoneManifestV1, "schemaVersion">;
|
|
174
|
-
readonly summary: CustodyManifestSummaryV1;
|
|
175
|
-
readonly deletion?: CustodyTombstoneDeletionV1;
|
|
176
|
-
}
|
|
177
|
-
export interface CustodyTombstoneFromManifestInput {
|
|
178
|
-
readonly manifestStatus?: CustodyTombstoneManifestStatus;
|
|
179
|
-
readonly tombstonedAt: string;
|
|
180
|
-
readonly deletion?: CustodyTombstoneDeletionV1;
|
|
181
|
-
}
|
|
182
133
|
export interface CustodyManifestWriteObject {
|
|
183
134
|
readonly key: string;
|
|
184
135
|
readonly contentType: typeof CUSTODY_MANIFEST_CONTENT_TYPE;
|
|
@@ -220,7 +171,5 @@ export declare function custodyManifestObjectKey(runId: string): string;
|
|
|
220
171
|
export declare function createCustodyManifestWriter(store: CustodyManifestObjectStore): CustodyManifestWriter;
|
|
221
172
|
export declare function writeCustodyManifest(store: CustodyManifestObjectStore, input: CustodyManifestInput): Promise<CustodyManifestWriteResult>;
|
|
222
173
|
export declare function buildCustodyManifest(input: CustodyManifestInput): CustodyManifestV1;
|
|
223
|
-
export declare function buildCustodyTombstone(input: CustodyTombstoneInput): CustodyTombstoneV1;
|
|
224
|
-
export declare function buildCustodyTombstoneFromManifest(manifest: CustodyManifestV1, input: CustodyTombstoneFromManifestInput): CustodyTombstoneV1;
|
|
225
174
|
export declare function scanCustodyPayloadForSensitiveValues(input: unknown): readonly CustodyRedactionFinding[];
|
|
226
175
|
export declare function assertPublicSafeCustodyPayload(input: unknown): void;
|