@aexhq/sdk 0.13.6
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/LICENSE +201 -0
- package/README.md +160 -0
- package/dist/_contracts/connection-ticket.d.ts +21 -0
- package/dist/_contracts/connection-ticket.js +49 -0
- package/dist/_contracts/event-envelope.d.ts +276 -0
- package/dist/_contracts/event-envelope.js +324 -0
- package/dist/_contracts/event-stream-client.d.ts +47 -0
- package/dist/_contracts/event-stream-client.js +141 -0
- package/dist/_contracts/http.d.ts +35 -0
- package/dist/_contracts/http.js +114 -0
- package/dist/_contracts/index.d.ts +28 -0
- package/dist/_contracts/index.js +29 -0
- package/dist/_contracts/managed-key.d.ts +74 -0
- package/dist/_contracts/managed-key.js +110 -0
- package/dist/_contracts/operations.d.ts +237 -0
- package/dist/_contracts/operations.js +632 -0
- package/dist/_contracts/provider-support.d.ts +220 -0
- package/dist/_contracts/provider-support.js +90 -0
- package/dist/_contracts/proxy-protocol.d.ts +257 -0
- package/dist/_contracts/proxy-protocol.js +234 -0
- package/dist/_contracts/proxy-validation.d.ts +19 -0
- package/dist/_contracts/proxy-validation.js +51 -0
- package/dist/_contracts/run-artifacts.d.ts +47 -0
- package/dist/_contracts/run-artifacts.js +101 -0
- package/dist/_contracts/run-config.d.ts +304 -0
- package/dist/_contracts/run-config.js +659 -0
- package/dist/_contracts/run-cost.d.ts +125 -0
- package/dist/_contracts/run-cost.js +616 -0
- package/dist/_contracts/run-custody.d.ts +226 -0
- package/dist/_contracts/run-custody.js +465 -0
- package/dist/_contracts/run-record.d.ts +127 -0
- package/dist/_contracts/run-record.js +177 -0
- package/dist/_contracts/run-retention.d.ts +213 -0
- package/dist/_contracts/run-retention.js +484 -0
- package/dist/_contracts/run-unit.d.ts +194 -0
- package/dist/_contracts/run-unit.js +215 -0
- package/dist/_contracts/runner-event.d.ts +114 -0
- package/dist/_contracts/runner-event.js +187 -0
- package/dist/_contracts/runtime-manifest.d.ts +106 -0
- package/dist/_contracts/runtime-manifest.js +98 -0
- package/dist/_contracts/runtime-security-profile.d.ts +27 -0
- package/dist/_contracts/runtime-security-profile.js +82 -0
- package/dist/_contracts/runtime-sizes.d.ts +144 -0
- package/dist/_contracts/runtime-sizes.js +136 -0
- package/dist/_contracts/runtime-types.d.ts +212 -0
- package/dist/_contracts/runtime-types.js +2 -0
- package/dist/_contracts/sdk-errors.d.ts +34 -0
- package/dist/_contracts/sdk-errors.js +52 -0
- package/dist/_contracts/sdk-secrets.d.ts +31 -0
- package/dist/_contracts/sdk-secrets.js +220 -0
- package/dist/_contracts/side-effect-audit.d.ts +129 -0
- package/dist/_contracts/side-effect-audit.js +494 -0
- package/dist/_contracts/sse.d.ts +74 -0
- package/dist/_contracts/sse.js +0 -0
- package/dist/_contracts/stable.d.ts +26 -0
- package/dist/_contracts/stable.js +44 -0
- package/dist/_contracts/status.d.ts +19 -0
- package/dist/_contracts/status.js +61 -0
- package/dist/_contracts/submission.d.ts +383 -0
- package/dist/_contracts/submission.js +1380 -0
- package/dist/agents-md.d.ts +46 -0
- package/dist/agents-md.js +83 -0
- package/dist/agents-md.js.map +1 -0
- package/dist/asset-upload.d.ts +66 -0
- package/dist/asset-upload.js +168 -0
- package/dist/asset-upload.js.map +1 -0
- package/dist/bundle.d.ts +33 -0
- package/dist/bundle.js +89 -0
- package/dist/bundle.js.map +1 -0
- package/dist/cli.mjs +4140 -0
- package/dist/cli.mjs.sha256 +1 -0
- package/dist/client.d.ts +460 -0
- package/dist/client.js +857 -0
- package/dist/client.js.map +1 -0
- package/dist/fetch-archive.d.ts +16 -0
- package/dist/fetch-archive.js +170 -0
- package/dist/fetch-archive.js.map +1 -0
- package/dist/file.d.ts +57 -0
- package/dist/file.js +153 -0
- package/dist/file.js.map +1 -0
- package/dist/index.d.ts +30 -0
- package/dist/index.js +34 -0
- package/dist/index.js.map +1 -0
- package/dist/mcp-server.d.ts +84 -0
- package/dist/mcp-server.js +114 -0
- package/dist/mcp-server.js.map +1 -0
- package/dist/node-fs.d.ts +12 -0
- package/dist/node-fs.js +44 -0
- package/dist/node-fs.js.map +1 -0
- package/dist/proxy-endpoint.d.ts +131 -0
- package/dist/proxy-endpoint.js +147 -0
- package/dist/proxy-endpoint.js.map +1 -0
- package/dist/skill.d.ts +117 -0
- package/dist/skill.js +169 -0
- package/dist/skill.js.map +1 -0
- package/dist/version.d.ts +9 -0
- package/dist/version.js +10 -0
- package/dist/version.js.map +1 -0
- package/docs/cleanup.md +38 -0
- package/docs/credentials.md +153 -0
- package/docs/events.md +76 -0
- package/docs/mcp.md +47 -0
- package/docs/outputs.md +157 -0
- package/docs/product-boundaries.md +57 -0
- package/docs/provider-runtime-capabilities.md +103 -0
- package/docs/quickstart.md +110 -0
- package/docs/release.md +99 -0
- package/docs/run-config.md +53 -0
- package/docs/run-record.md +39 -0
- package/docs/skills.md +139 -0
- package/docs/testing.md +29 -0
- package/package.json +47 -0
|
@@ -0,0 +1,220 @@
|
|
|
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
|
+
export interface SupportPointer {
|
|
5
|
+
readonly label: string;
|
|
6
|
+
/** Markdown href, relative to `packages/sdk/docs/provider-runtime-capabilities.md`. */
|
|
7
|
+
readonly href: string;
|
|
8
|
+
}
|
|
9
|
+
export interface ProviderPublicSupport {
|
|
10
|
+
readonly displayName: string;
|
|
11
|
+
readonly status: ProviderSupportStatus;
|
|
12
|
+
readonly docsAnchor: string;
|
|
13
|
+
readonly docs: readonly SupportPointer[];
|
|
14
|
+
readonly evidence: readonly SupportPointer[];
|
|
15
|
+
readonly runtimeEvidence: Readonly<Partial<Record<RuntimeKind, readonly SupportPointer[]>>>;
|
|
16
|
+
}
|
|
17
|
+
export interface RuntimeValidationSupport {
|
|
18
|
+
readonly docsAnchor: string;
|
|
19
|
+
readonly docs: readonly SupportPointer[];
|
|
20
|
+
readonly evidence: readonly SupportPointer[];
|
|
21
|
+
readonly enforcement: string;
|
|
22
|
+
}
|
|
23
|
+
export declare const RUNTIME_VALIDATION_SUPPORT: {
|
|
24
|
+
readonly feature_runtime_mismatch: {
|
|
25
|
+
readonly docsAnchor: "managed-unsupported-features";
|
|
26
|
+
readonly docs: readonly [{
|
|
27
|
+
readonly label: "Runtime routing";
|
|
28
|
+
readonly href: "provider-runtime-capabilities.md#runtime-routing";
|
|
29
|
+
}];
|
|
30
|
+
readonly evidence: readonly [{
|
|
31
|
+
readonly label: "Submission parser and routing parity";
|
|
32
|
+
readonly href: "../../contracts/test/submission.test.ts";
|
|
33
|
+
}];
|
|
34
|
+
readonly enforcement: "collectManagedUnsupportedFeatures + selectRuntime";
|
|
35
|
+
};
|
|
36
|
+
};
|
|
37
|
+
/**
|
|
38
|
+
* Public provider support facts for generated SDK docs. Keep this metadata
|
|
39
|
+
* public-facing only: provider names, support status, docs anchors, and
|
|
40
|
+
* evidence pointers.
|
|
41
|
+
*/
|
|
42
|
+
export declare const PROVIDER_PUBLIC_SUPPORT: {
|
|
43
|
+
readonly anthropic: {
|
|
44
|
+
readonly displayName: "Anthropic";
|
|
45
|
+
readonly status: "supported";
|
|
46
|
+
readonly docsAnchor: "anthropic";
|
|
47
|
+
readonly docs: readonly [{
|
|
48
|
+
readonly label: "Credentials";
|
|
49
|
+
readonly href: "credentials.md";
|
|
50
|
+
}, {
|
|
51
|
+
readonly label: "Events";
|
|
52
|
+
readonly href: "events.md";
|
|
53
|
+
}];
|
|
54
|
+
readonly evidence: readonly [{
|
|
55
|
+
readonly label: "Submission parser and routing parity";
|
|
56
|
+
readonly href: "../../contracts/test/submission.test.ts";
|
|
57
|
+
}, {
|
|
58
|
+
readonly label: "Runtime support validator";
|
|
59
|
+
readonly href: "../../contracts/test/runtime-support.test.ts";
|
|
60
|
+
}, {
|
|
61
|
+
readonly label: "Generated matrix freshness";
|
|
62
|
+
readonly href: "../../../scripts/validate/capability-matrix.test.ts";
|
|
63
|
+
}, {
|
|
64
|
+
readonly label: "Installed-SDK live user matrix";
|
|
65
|
+
readonly href: "../../../apps/user-tests/test/live/live-sdk-comprehensive.test.ts";
|
|
66
|
+
}, {
|
|
67
|
+
readonly label: "Runtime support validator";
|
|
68
|
+
readonly href: "../../contracts/test/runtime-support.test.ts";
|
|
69
|
+
}];
|
|
70
|
+
readonly runtimeEvidence: {
|
|
71
|
+
readonly managed: readonly [{
|
|
72
|
+
readonly label: "Installed-SDK live user matrix";
|
|
73
|
+
readonly href: "../../../apps/user-tests/test/live/live-sdk-comprehensive.test.ts";
|
|
74
|
+
}, {
|
|
75
|
+
readonly label: "Runtime support validator";
|
|
76
|
+
readonly href: "../../contracts/test/runtime-support.test.ts";
|
|
77
|
+
}];
|
|
78
|
+
};
|
|
79
|
+
};
|
|
80
|
+
readonly deepseek: {
|
|
81
|
+
readonly displayName: "DeepSeek";
|
|
82
|
+
readonly status: "supported";
|
|
83
|
+
readonly docsAnchor: "deepseek";
|
|
84
|
+
readonly docs: readonly [{
|
|
85
|
+
readonly label: "Credentials";
|
|
86
|
+
readonly href: "credentials.md";
|
|
87
|
+
}, {
|
|
88
|
+
readonly label: "Events";
|
|
89
|
+
readonly href: "events.md";
|
|
90
|
+
}];
|
|
91
|
+
readonly evidence: readonly [{
|
|
92
|
+
readonly label: "Submission parser and routing parity";
|
|
93
|
+
readonly href: "../../contracts/test/submission.test.ts";
|
|
94
|
+
}, {
|
|
95
|
+
readonly label: "Runtime support validator";
|
|
96
|
+
readonly href: "../../contracts/test/runtime-support.test.ts";
|
|
97
|
+
}, {
|
|
98
|
+
readonly label: "Generated matrix freshness";
|
|
99
|
+
readonly href: "../../../scripts/validate/capability-matrix.test.ts";
|
|
100
|
+
}, {
|
|
101
|
+
readonly label: "Installed-SDK live user matrix";
|
|
102
|
+
readonly href: "../../../apps/user-tests/test/live/live-sdk-comprehensive.test.ts";
|
|
103
|
+
}, {
|
|
104
|
+
readonly label: "Runtime support validator";
|
|
105
|
+
readonly href: "../../contracts/test/runtime-support.test.ts";
|
|
106
|
+
}];
|
|
107
|
+
readonly runtimeEvidence: {
|
|
108
|
+
readonly managed: readonly [{
|
|
109
|
+
readonly label: "Installed-SDK live user matrix";
|
|
110
|
+
readonly href: "../../../apps/user-tests/test/live/live-sdk-comprehensive.test.ts";
|
|
111
|
+
}, {
|
|
112
|
+
readonly label: "Runtime support validator";
|
|
113
|
+
readonly href: "../../contracts/test/runtime-support.test.ts";
|
|
114
|
+
}];
|
|
115
|
+
};
|
|
116
|
+
};
|
|
117
|
+
readonly openai: {
|
|
118
|
+
readonly displayName: "OpenAI";
|
|
119
|
+
readonly status: "live-unverified";
|
|
120
|
+
readonly docsAnchor: "openai";
|
|
121
|
+
readonly docs: readonly [{
|
|
122
|
+
readonly label: "Credentials";
|
|
123
|
+
readonly href: "credentials.md";
|
|
124
|
+
}, {
|
|
125
|
+
readonly label: "Events";
|
|
126
|
+
readonly href: "events.md";
|
|
127
|
+
}];
|
|
128
|
+
readonly evidence: readonly [{
|
|
129
|
+
readonly label: "Submission parser and routing parity";
|
|
130
|
+
readonly href: "../../contracts/test/submission.test.ts";
|
|
131
|
+
}, {
|
|
132
|
+
readonly label: "Runtime support validator";
|
|
133
|
+
readonly href: "../../contracts/test/runtime-support.test.ts";
|
|
134
|
+
}, {
|
|
135
|
+
readonly label: "Generated matrix freshness";
|
|
136
|
+
readonly href: "../../../scripts/validate/capability-matrix.test.ts";
|
|
137
|
+
}];
|
|
138
|
+
readonly runtimeEvidence: {
|
|
139
|
+
readonly managed: readonly [{
|
|
140
|
+
readonly label: "Submission parser and routing parity";
|
|
141
|
+
readonly href: "../../contracts/test/submission.test.ts";
|
|
142
|
+
}, {
|
|
143
|
+
readonly label: "Runtime support validator";
|
|
144
|
+
readonly href: "../../contracts/test/runtime-support.test.ts";
|
|
145
|
+
}, {
|
|
146
|
+
readonly label: "Generated matrix freshness";
|
|
147
|
+
readonly href: "../../../scripts/validate/capability-matrix.test.ts";
|
|
148
|
+
}];
|
|
149
|
+
};
|
|
150
|
+
};
|
|
151
|
+
readonly gemini: {
|
|
152
|
+
readonly displayName: "Gemini";
|
|
153
|
+
readonly status: "live-unverified";
|
|
154
|
+
readonly docsAnchor: "gemini";
|
|
155
|
+
readonly docs: readonly [{
|
|
156
|
+
readonly label: "Credentials";
|
|
157
|
+
readonly href: "credentials.md";
|
|
158
|
+
}, {
|
|
159
|
+
readonly label: "Events";
|
|
160
|
+
readonly href: "events.md";
|
|
161
|
+
}];
|
|
162
|
+
readonly evidence: readonly [{
|
|
163
|
+
readonly label: "Submission parser and routing parity";
|
|
164
|
+
readonly href: "../../contracts/test/submission.test.ts";
|
|
165
|
+
}, {
|
|
166
|
+
readonly label: "Runtime support validator";
|
|
167
|
+
readonly href: "../../contracts/test/runtime-support.test.ts";
|
|
168
|
+
}, {
|
|
169
|
+
readonly label: "Generated matrix freshness";
|
|
170
|
+
readonly href: "../../../scripts/validate/capability-matrix.test.ts";
|
|
171
|
+
}];
|
|
172
|
+
readonly runtimeEvidence: {
|
|
173
|
+
readonly managed: readonly [{
|
|
174
|
+
readonly label: "Submission parser and routing parity";
|
|
175
|
+
readonly href: "../../contracts/test/submission.test.ts";
|
|
176
|
+
}, {
|
|
177
|
+
readonly label: "Runtime support validator";
|
|
178
|
+
readonly href: "../../contracts/test/runtime-support.test.ts";
|
|
179
|
+
}, {
|
|
180
|
+
readonly label: "Generated matrix freshness";
|
|
181
|
+
readonly href: "../../../scripts/validate/capability-matrix.test.ts";
|
|
182
|
+
}];
|
|
183
|
+
};
|
|
184
|
+
};
|
|
185
|
+
readonly mistral: {
|
|
186
|
+
readonly displayName: "Mistral";
|
|
187
|
+
readonly status: "live-unverified";
|
|
188
|
+
readonly docsAnchor: "mistral";
|
|
189
|
+
readonly docs: readonly [{
|
|
190
|
+
readonly label: "Credentials";
|
|
191
|
+
readonly href: "credentials.md";
|
|
192
|
+
}, {
|
|
193
|
+
readonly label: "Events";
|
|
194
|
+
readonly href: "events.md";
|
|
195
|
+
}];
|
|
196
|
+
readonly evidence: readonly [{
|
|
197
|
+
readonly label: "Submission parser and routing parity";
|
|
198
|
+
readonly href: "../../contracts/test/submission.test.ts";
|
|
199
|
+
}, {
|
|
200
|
+
readonly label: "Runtime support validator";
|
|
201
|
+
readonly href: "../../contracts/test/runtime-support.test.ts";
|
|
202
|
+
}, {
|
|
203
|
+
readonly label: "Generated matrix freshness";
|
|
204
|
+
readonly href: "../../../scripts/validate/capability-matrix.test.ts";
|
|
205
|
+
}];
|
|
206
|
+
readonly runtimeEvidence: {
|
|
207
|
+
readonly managed: readonly [{
|
|
208
|
+
readonly label: "Submission parser and routing parity";
|
|
209
|
+
readonly href: "../../contracts/test/submission.test.ts";
|
|
210
|
+
}, {
|
|
211
|
+
readonly label: "Runtime support validator";
|
|
212
|
+
readonly href: "../../contracts/test/runtime-support.test.ts";
|
|
213
|
+
}, {
|
|
214
|
+
readonly label: "Generated matrix freshness";
|
|
215
|
+
readonly href: "../../../scripts/validate/capability-matrix.test.ts";
|
|
216
|
+
}];
|
|
217
|
+
};
|
|
218
|
+
};
|
|
219
|
+
};
|
|
220
|
+
export declare function providerPublicSupport(provider: RunProvider): ProviderPublicSupport;
|
|
@@ -0,0 +1,90 @@
|
|
|
1
|
+
export const PROVIDER_SUPPORT_STATUSES = [
|
|
2
|
+
"supported",
|
|
3
|
+
"live-unverified",
|
|
4
|
+
"rejected"
|
|
5
|
+
];
|
|
6
|
+
const COMMON_DOCS = [
|
|
7
|
+
{ label: "Credentials", href: "credentials.md" },
|
|
8
|
+
{ label: "Events", href: "events.md" }
|
|
9
|
+
];
|
|
10
|
+
const COMMON_EVIDENCE = [
|
|
11
|
+
{ label: "Submission parser and routing parity", href: "../../contracts/test/submission.test.ts" },
|
|
12
|
+
{ label: "Runtime support validator", href: "../../contracts/test/runtime-support.test.ts" },
|
|
13
|
+
{ label: "Generated matrix freshness", href: "../../../scripts/validate/capability-matrix.test.ts" }
|
|
14
|
+
];
|
|
15
|
+
const LIVE_USER_MATRIX_EVIDENCE = [
|
|
16
|
+
{ label: "Installed-SDK live user matrix", href: "../../../apps/user-tests/test/live/live-sdk-comprehensive.test.ts" }
|
|
17
|
+
];
|
|
18
|
+
const MANAGED_PROXY_EVIDENCE = [
|
|
19
|
+
...LIVE_USER_MATRIX_EVIDENCE,
|
|
20
|
+
{ label: "Runtime support validator", href: "../../contracts/test/runtime-support.test.ts" }
|
|
21
|
+
];
|
|
22
|
+
export const RUNTIME_VALIDATION_SUPPORT = {
|
|
23
|
+
feature_runtime_mismatch: {
|
|
24
|
+
docsAnchor: "managed-unsupported-features",
|
|
25
|
+
docs: [{ label: "Runtime routing", href: "provider-runtime-capabilities.md#runtime-routing" }],
|
|
26
|
+
evidence: [{ label: "Submission parser and routing parity", href: "../../contracts/test/submission.test.ts" }],
|
|
27
|
+
enforcement: "collectManagedUnsupportedFeatures + selectRuntime"
|
|
28
|
+
}
|
|
29
|
+
};
|
|
30
|
+
/**
|
|
31
|
+
* Public provider support facts for generated SDK docs. Keep this metadata
|
|
32
|
+
* public-facing only: provider names, support status, docs anchors, and
|
|
33
|
+
* evidence pointers.
|
|
34
|
+
*/
|
|
35
|
+
export const PROVIDER_PUBLIC_SUPPORT = {
|
|
36
|
+
anthropic: {
|
|
37
|
+
displayName: "Anthropic",
|
|
38
|
+
status: "supported",
|
|
39
|
+
docsAnchor: "anthropic",
|
|
40
|
+
docs: COMMON_DOCS,
|
|
41
|
+
evidence: [...COMMON_EVIDENCE, ...MANAGED_PROXY_EVIDENCE],
|
|
42
|
+
runtimeEvidence: {
|
|
43
|
+
managed: MANAGED_PROXY_EVIDENCE
|
|
44
|
+
}
|
|
45
|
+
},
|
|
46
|
+
deepseek: {
|
|
47
|
+
displayName: "DeepSeek",
|
|
48
|
+
status: "supported",
|
|
49
|
+
docsAnchor: "deepseek",
|
|
50
|
+
docs: COMMON_DOCS,
|
|
51
|
+
evidence: [...COMMON_EVIDENCE, ...MANAGED_PROXY_EVIDENCE],
|
|
52
|
+
runtimeEvidence: {
|
|
53
|
+
managed: MANAGED_PROXY_EVIDENCE
|
|
54
|
+
}
|
|
55
|
+
},
|
|
56
|
+
openai: {
|
|
57
|
+
displayName: "OpenAI",
|
|
58
|
+
status: "live-unverified",
|
|
59
|
+
docsAnchor: "openai",
|
|
60
|
+
docs: COMMON_DOCS,
|
|
61
|
+
evidence: COMMON_EVIDENCE,
|
|
62
|
+
runtimeEvidence: {
|
|
63
|
+
managed: COMMON_EVIDENCE
|
|
64
|
+
}
|
|
65
|
+
},
|
|
66
|
+
gemini: {
|
|
67
|
+
displayName: "Gemini",
|
|
68
|
+
status: "live-unverified",
|
|
69
|
+
docsAnchor: "gemini",
|
|
70
|
+
docs: COMMON_DOCS,
|
|
71
|
+
evidence: COMMON_EVIDENCE,
|
|
72
|
+
runtimeEvidence: {
|
|
73
|
+
managed: COMMON_EVIDENCE
|
|
74
|
+
}
|
|
75
|
+
},
|
|
76
|
+
mistral: {
|
|
77
|
+
displayName: "Mistral",
|
|
78
|
+
status: "live-unverified",
|
|
79
|
+
docsAnchor: "mistral",
|
|
80
|
+
docs: COMMON_DOCS,
|
|
81
|
+
evidence: COMMON_EVIDENCE,
|
|
82
|
+
runtimeEvidence: {
|
|
83
|
+
managed: COMMON_EVIDENCE
|
|
84
|
+
}
|
|
85
|
+
}
|
|
86
|
+
};
|
|
87
|
+
export function providerPublicSupport(provider) {
|
|
88
|
+
return PROVIDER_PUBLIC_SUPPORT[provider];
|
|
89
|
+
}
|
|
90
|
+
//# sourceMappingURL=provider-support.js.map
|
|
@@ -0,0 +1,257 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Wire-protocol version. Bumped on any breaking change to the request or
|
|
3
|
+
* response shape. The CLI sends this in the `X-Aex-Proxy-Protocol`
|
|
4
|
+
* header on every request; the BFF rejects mismatches with HTTP 426
|
|
5
|
+
* `unsupported_protocol`.
|
|
6
|
+
*
|
|
7
|
+
* Bumps are coordinated: CLI and BFF release together, the worker
|
|
8
|
+
* bundles the matching CLI artifact, and the e2e suite runs both with
|
|
9
|
+
* the new version.
|
|
10
|
+
*/
|
|
11
|
+
export declare const PROXY_PROTOCOL_VERSION: "1";
|
|
12
|
+
export declare const PROXY_PROTOCOL_HEADER = "x-aex-proxy-protocol";
|
|
13
|
+
/**
|
|
14
|
+
* Default `User-Agent` the proxy attaches to every outbound request when
|
|
15
|
+
* the caller did not supply one via `allowHeaders`. Some upstreams reject
|
|
16
|
+
* requests that arrive without a meaningful UA — notably the Wikimedia
|
|
17
|
+
* family (Wikidata, Wikipedia, Wikimedia Commons), whose policy requires
|
|
18
|
+
* a contactable identifier and otherwise returns HTTP 403 with a
|
|
19
|
+
* `Please identify your user agent` body.
|
|
20
|
+
*
|
|
21
|
+
* Callers can override per request by listing `user-agent` in their
|
|
22
|
+
* endpoint's `allowHeaders` and setting it on the proxy call; the
|
|
23
|
+
* default only fires when nothing was forwarded.
|
|
24
|
+
*
|
|
25
|
+
* See <https://meta.wikimedia.org/wiki/User-Agent_policy>.
|
|
26
|
+
*/
|
|
27
|
+
export declare const PROXY_DEFAULT_USER_AGENT = "aex-proxy/1.0 (+https://aex.dev/contact)";
|
|
28
|
+
export declare const PROXY_METHOD_HEADER = "x-aex-method";
|
|
29
|
+
export declare const PROXY_PATH_HEADER = "x-aex-path";
|
|
30
|
+
export declare const PROXY_QUERY_HEADER = "x-aex-query";
|
|
31
|
+
export declare const PROXY_HEADERS_HEADER = "x-aex-headers";
|
|
32
|
+
export declare const PROXY_RESPONSE_MODE_HEADER = "x-aex-response-mode";
|
|
33
|
+
export declare const PROXY_ALLOWED_METHODS: readonly ["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD"];
|
|
34
|
+
export type ProxyMethod = (typeof PROXY_ALLOWED_METHODS)[number];
|
|
35
|
+
export declare const PROXY_RESPONSE_MODES: readonly ["status_only", "headers_only", "full"];
|
|
36
|
+
export type ProxyResponseMode = (typeof PROXY_RESPONSE_MODES)[number];
|
|
37
|
+
/**
|
|
38
|
+
* Returns the narrower of the two response modes (lower width wins).
|
|
39
|
+
* Pure function so the CLI and BFF can both call it without import cycles.
|
|
40
|
+
*/
|
|
41
|
+
export declare function narrowResponseMode(policy: ProxyResponseMode, requested: ProxyResponseMode): ProxyResponseMode;
|
|
42
|
+
/**
|
|
43
|
+
* Error codes returned by the proxy route. Stable strings — the CLI
|
|
44
|
+
* matches against them in scripts. Adding a new code is non-breaking;
|
|
45
|
+
* removing or renaming an existing code requires a protocol bump.
|
|
46
|
+
*/
|
|
47
|
+
export declare const PROXY_ERROR_CODES: readonly ["unsupported_protocol", "unauthorized", "endpoint_not_found", "policy_denied", "rate_limited", "budget_exceeded", "ssrf_denied", "upstream_timeout", "upstream_error", "exceeded_cap", "bad_request", "internal_error"];
|
|
48
|
+
export type ProxyErrorCode = (typeof PROXY_ERROR_CODES)[number];
|
|
49
|
+
/**
|
|
50
|
+
* Shape of the JSON written to the per-run manifest mounted inside
|
|
51
|
+
* the container (`/mnt/session/uploads/aex/index.json`).
|
|
52
|
+
*
|
|
53
|
+
* Always present (every run), regardless of whether any proxy endpoints
|
|
54
|
+
* were declared. With zero endpoints, `endpoints` is `[]` and
|
|
55
|
+
* `proxyBaseUrl` is `null` — this keeps `aex --help` working
|
|
56
|
+
* uniformly and makes the always-on surface observable in tests.
|
|
57
|
+
*
|
|
58
|
+
* Auth values NEVER appear in this file. The file is mounted into the
|
|
59
|
+
* container; treat it as world-readable from the agent's perspective.
|
|
60
|
+
*/
|
|
61
|
+
export interface ProxyIndexFile {
|
|
62
|
+
readonly protocolVersion: typeof PROXY_PROTOCOL_VERSION;
|
|
63
|
+
readonly runId: string;
|
|
64
|
+
readonly proxyBaseUrl: string | null;
|
|
65
|
+
readonly endpoints: readonly ProxyIndexEntry[];
|
|
66
|
+
}
|
|
67
|
+
export interface ProxyIndexEntry {
|
|
68
|
+
readonly name: string;
|
|
69
|
+
readonly baseUrl: string;
|
|
70
|
+
readonly authShape: ProxyAuthShape;
|
|
71
|
+
readonly allowMethods: readonly ProxyMethod[];
|
|
72
|
+
readonly allowPathPrefixes: readonly string[];
|
|
73
|
+
readonly allowHeaders: readonly string[];
|
|
74
|
+
readonly responseMode: ProxyResponseMode;
|
|
75
|
+
readonly maxRequestBytes: number;
|
|
76
|
+
readonly maxResponseBytes: number;
|
|
77
|
+
readonly timeoutMs: number;
|
|
78
|
+
readonly perCallBudget: number;
|
|
79
|
+
readonly responseByteBudget: number;
|
|
80
|
+
}
|
|
81
|
+
/**
|
|
82
|
+
* Default caps for a proxy endpoint when the submission doesn't specify
|
|
83
|
+
* one. Conservative on purpose. Lives in the protocol module (next to the
|
|
84
|
+
* index-file shape) so {@link buildProxyIndexFile} can fill every optional
|
|
85
|
+
* cap with a concrete value; the submission parser re-exports it.
|
|
86
|
+
*/
|
|
87
|
+
export declare const PROXY_ENDPOINT_DEFAULTS: {
|
|
88
|
+
readonly allowHeaders: readonly string[];
|
|
89
|
+
readonly responseMode: ProxyResponseMode;
|
|
90
|
+
readonly maxRequestBytes: number;
|
|
91
|
+
readonly maxResponseBytes: number;
|
|
92
|
+
readonly timeoutMs: 10000;
|
|
93
|
+
readonly perCallBudget: 60;
|
|
94
|
+
readonly responseByteBudget: number;
|
|
95
|
+
};
|
|
96
|
+
/**
|
|
97
|
+
* Non-secret endpoint policy the index builder consumes. Structurally a
|
|
98
|
+
* subset of `PlatformProxyEndpoint` (submission.ts) — declared here so the
|
|
99
|
+
* protocol module stays free of an import cycle with the submission parser.
|
|
100
|
+
*/
|
|
101
|
+
export interface ProxyEndpointPolicy {
|
|
102
|
+
readonly name: string;
|
|
103
|
+
readonly baseUrl: string;
|
|
104
|
+
readonly authShape: ProxyAuthShape;
|
|
105
|
+
readonly allowMethods: readonly ProxyMethod[];
|
|
106
|
+
readonly allowPathPrefixes: readonly string[];
|
|
107
|
+
readonly allowHeaders?: readonly string[];
|
|
108
|
+
readonly responseMode?: ProxyResponseMode;
|
|
109
|
+
readonly maxRequestBytes?: number;
|
|
110
|
+
readonly maxResponseBytes?: number;
|
|
111
|
+
readonly timeoutMs?: number;
|
|
112
|
+
readonly perCallBudget?: number;
|
|
113
|
+
readonly responseByteBudget?: number;
|
|
114
|
+
}
|
|
115
|
+
export interface BuildProxyIndexFileInput {
|
|
116
|
+
readonly runId: string;
|
|
117
|
+
/**
|
|
118
|
+
* Dashboard host that serves `/api/runs/:runId/proxy/:endpointName`
|
|
119
|
+
* (the BFF proxy route). Distinct from the api Worker host. When unset
|
|
120
|
+
* (or empty) the run has no reachable proxy plane and `proxyBaseUrl`
|
|
121
|
+
* resolves to `null`.
|
|
122
|
+
*/
|
|
123
|
+
readonly proxyPublicBaseUrl?: string;
|
|
124
|
+
readonly endpoints?: readonly ProxyEndpointPolicy[];
|
|
125
|
+
}
|
|
126
|
+
/**
|
|
127
|
+
* Build the per-run {@link ProxyIndexFile} mounted into the container at
|
|
128
|
+
* `/mnt/session/uploads/aex/index.json`. Pure: applies
|
|
129
|
+
* {@link PROXY_ENDPOINT_DEFAULTS} so every optional cap is concrete, and
|
|
130
|
+
* carries ONLY the non-secret endpoint policy — auth values never appear.
|
|
131
|
+
*
|
|
132
|
+
* ALWAYS emits a file (the always-on surface). With zero endpoints OR no
|
|
133
|
+
* `proxyPublicBaseUrl`, `proxyBaseUrl` is `null` and `endpoints` is `[]`.
|
|
134
|
+
* Otherwise `proxyBaseUrl` is `<trimmed base>/api/runs/<runId>/proxy`, the
|
|
135
|
+
* prefix the in-container runtime bridge appends `/<endpointName>` to (proxy.ts).
|
|
136
|
+
*/
|
|
137
|
+
export declare function buildProxyIndexFile(input: BuildProxyIndexFileInput): ProxyIndexFile;
|
|
138
|
+
/**
|
|
139
|
+
* Structural description of how the upstream endpoint expects auth.
|
|
140
|
+
* The actual auth value lives in the run's Vault bundle under
|
|
141
|
+
* `secrets.proxyEndpointAuth[i].value` and is never reflected back
|
|
142
|
+
* into the container or index file.
|
|
143
|
+
*
|
|
144
|
+
* The `none` variant declares an upstream that takes no auth (public
|
|
145
|
+
* APIs like Wikimedia Commons or NASA Images). It still routes through
|
|
146
|
+
* the proxy for unified egress, audit, and budget enforcement, but
|
|
147
|
+
* carries no `proxyEndpointAuth[]` entry and the BFF injects no
|
|
148
|
+
* header or query value.
|
|
149
|
+
*/
|
|
150
|
+
export type ProxyAuthShape = {
|
|
151
|
+
readonly type: "none";
|
|
152
|
+
} | {
|
|
153
|
+
readonly type: "bearer";
|
|
154
|
+
} | {
|
|
155
|
+
readonly type: "basic";
|
|
156
|
+
} | {
|
|
157
|
+
readonly type: "header";
|
|
158
|
+
readonly name: string;
|
|
159
|
+
} | {
|
|
160
|
+
readonly type: "query";
|
|
161
|
+
readonly name: string;
|
|
162
|
+
};
|
|
163
|
+
export type ProxyAuthType = ProxyAuthShape["type"];
|
|
164
|
+
/**
|
|
165
|
+
* Header name (lowercase) that an upstream auth shape uses as its
|
|
166
|
+
* carrier. Returns `undefined` for query-based and keyless auth.
|
|
167
|
+
*
|
|
168
|
+
* Used by the submission parser to forbid `allowHeaders` from listing
|
|
169
|
+
* the auth header (avoids leaks via caller-supplied headers), and by
|
|
170
|
+
* the proxy route to strip any caller header that would collide with
|
|
171
|
+
* the auth carrier at request time.
|
|
172
|
+
*/
|
|
173
|
+
export declare function authShapeHeaderName(shape: ProxyAuthShape): string | undefined;
|
|
174
|
+
/**
|
|
175
|
+
* Query-string key that an upstream query-based auth shape uses as its
|
|
176
|
+
* carrier. Returns `undefined` for non-query shapes (including "none").
|
|
177
|
+
*/
|
|
178
|
+
export declare function authShapeQueryName(shape: ProxyAuthShape): string | undefined;
|
|
179
|
+
/**
|
|
180
|
+
* Inbound request headers every Aex proxy plane STRIPS before
|
|
181
|
+
* forwarding a runtime/runner request upstream. Three categories:
|
|
182
|
+
*
|
|
183
|
+
* - Credential carriers (`authorization`, `x-api-key`, `cookie`,
|
|
184
|
+
* `proxy-authorization`) — these belong to Aex's own auth gate
|
|
185
|
+
* (the per-run bearer) or to the caller, never the upstream. The
|
|
186
|
+
* legitimate upstream credential is injected server-side from the
|
|
187
|
+
* run's Vault bundle / endpoint auth shape AFTER this strip, so it is
|
|
188
|
+
* never sourced from an inbound header.
|
|
189
|
+
* - Hop-by-hop fields (RFC 7230 §6.1: `connection`, `keep-alive`,
|
|
190
|
+
* `transfer-encoding`, `te`, `trailer`, `upgrade`, `expect`,
|
|
191
|
+
* `proxy-authenticate`, `proxy-connection`) — must not survive a
|
|
192
|
+
* proxy hop.
|
|
193
|
+
* - Routing primitives a compromised runner could spoof to bypass an
|
|
194
|
+
* upstream's IP allowlist / rate-limit (`host`, `content-length`,
|
|
195
|
+
* `x-forwarded-*`, `x-real-ip`, `forwarded`).
|
|
196
|
+
*
|
|
197
|
+
* The api Worker provider-proxy and the dashboard MCP proxy strip exactly
|
|
198
|
+
* this set (both inject upstream auth separately — the provider key, or the
|
|
199
|
+
* Vault MCP-bundle headers, applied AFTER the strip). The dashboard
|
|
200
|
+
* customer HTTP proxy hard-denies this set MINUS `x-api-key`, because a
|
|
201
|
+
* customer endpoint may legitimately declare `x-api-key` as its auth
|
|
202
|
+
* carrier; it derives from this constant so the hop-by-hop + routing
|
|
203
|
+
* entries never drift. Keeping the membership here is the single source of
|
|
204
|
+
* truth that stops those surfaces diverging.
|
|
205
|
+
*/
|
|
206
|
+
export declare const PROXY_STRIPPED_INBOUND_HEADERS: ReadonlySet<string>;
|
|
207
|
+
/**
|
|
208
|
+
* JSON body returned on a successful proxy call. The actual HTTP
|
|
209
|
+
* response from the BFF to the CLI is always 200 once the BFF accepts
|
|
210
|
+
* the request; the upstream's status/headers/body are reflected inside
|
|
211
|
+
* this envelope so the CLI can decide what to write to stdout/stderr.
|
|
212
|
+
*/
|
|
213
|
+
export interface ProxyResponseEnvelope {
|
|
214
|
+
readonly endpointName: string;
|
|
215
|
+
readonly upstreamStatus: number;
|
|
216
|
+
/** Lowercase header names → values. Allowlist-filtered by the BFF. */
|
|
217
|
+
readonly upstreamHeaders: Readonly<Record<string, string>>;
|
|
218
|
+
/**
|
|
219
|
+
* Base64-encoded upstream body. Present only when the effective
|
|
220
|
+
* response mode is `full`. Truncated to `maxResponseBytes`; if the
|
|
221
|
+
* upstream exceeded the cap, `truncated` is `true`.
|
|
222
|
+
*/
|
|
223
|
+
readonly upstreamBodyBase64?: string;
|
|
224
|
+
readonly truncated?: boolean;
|
|
225
|
+
/**
|
|
226
|
+
* Echoed back so the CLI can warn the agent when its requested mode
|
|
227
|
+
* was clamped against the policy ceiling.
|
|
228
|
+
*/
|
|
229
|
+
readonly effectiveResponseMode: ProxyResponseMode;
|
|
230
|
+
readonly modeClamped: boolean;
|
|
231
|
+
/** Remaining per-endpoint per-run budget after this call. */
|
|
232
|
+
readonly remainingCalls: number;
|
|
233
|
+
readonly remainingResponseBytes: number;
|
|
234
|
+
}
|
|
235
|
+
/**
|
|
236
|
+
* JSON body returned on any error. The CLI emits this verbatim on
|
|
237
|
+
* stderr and exits non-zero. Audit row carries the same `code`.
|
|
238
|
+
*/
|
|
239
|
+
export interface ProxyErrorBody {
|
|
240
|
+
readonly error: ProxyErrorCode;
|
|
241
|
+
/** Human-readable message. Never includes auth values. */
|
|
242
|
+
readonly message: string;
|
|
243
|
+
/**
|
|
244
|
+
* Optional diagnostic fields. Always safe to surface — auth values
|
|
245
|
+
* and full URLs are stripped at the BFF.
|
|
246
|
+
*/
|
|
247
|
+
readonly endpointName?: string;
|
|
248
|
+
readonly upstreamStatus?: number;
|
|
249
|
+
/** Server-supplied protocol version on `unsupported_protocol`. */
|
|
250
|
+
readonly serverProtocolVersion?: string;
|
|
251
|
+
}
|
|
252
|
+
/**
|
|
253
|
+
* Status code → error code mapping used by the BFF to ensure the audit
|
|
254
|
+
* row's error code and the HTTP response line up. Kept here so callers
|
|
255
|
+
* can do a sanity check in tests.
|
|
256
|
+
*/
|
|
257
|
+
export declare const PROXY_ERROR_HTTP_STATUS: Record<ProxyErrorCode, number>;
|