@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.
Files changed (112) hide show
  1. package/LICENSE +201 -0
  2. package/README.md +160 -0
  3. package/dist/_contracts/connection-ticket.d.ts +21 -0
  4. package/dist/_contracts/connection-ticket.js +49 -0
  5. package/dist/_contracts/event-envelope.d.ts +276 -0
  6. package/dist/_contracts/event-envelope.js +324 -0
  7. package/dist/_contracts/event-stream-client.d.ts +47 -0
  8. package/dist/_contracts/event-stream-client.js +141 -0
  9. package/dist/_contracts/http.d.ts +35 -0
  10. package/dist/_contracts/http.js +114 -0
  11. package/dist/_contracts/index.d.ts +28 -0
  12. package/dist/_contracts/index.js +29 -0
  13. package/dist/_contracts/managed-key.d.ts +74 -0
  14. package/dist/_contracts/managed-key.js +110 -0
  15. package/dist/_contracts/operations.d.ts +237 -0
  16. package/dist/_contracts/operations.js +632 -0
  17. package/dist/_contracts/provider-support.d.ts +220 -0
  18. package/dist/_contracts/provider-support.js +90 -0
  19. package/dist/_contracts/proxy-protocol.d.ts +257 -0
  20. package/dist/_contracts/proxy-protocol.js +234 -0
  21. package/dist/_contracts/proxy-validation.d.ts +19 -0
  22. package/dist/_contracts/proxy-validation.js +51 -0
  23. package/dist/_contracts/run-artifacts.d.ts +47 -0
  24. package/dist/_contracts/run-artifacts.js +101 -0
  25. package/dist/_contracts/run-config.d.ts +304 -0
  26. package/dist/_contracts/run-config.js +659 -0
  27. package/dist/_contracts/run-cost.d.ts +125 -0
  28. package/dist/_contracts/run-cost.js +616 -0
  29. package/dist/_contracts/run-custody.d.ts +226 -0
  30. package/dist/_contracts/run-custody.js +465 -0
  31. package/dist/_contracts/run-record.d.ts +127 -0
  32. package/dist/_contracts/run-record.js +177 -0
  33. package/dist/_contracts/run-retention.d.ts +213 -0
  34. package/dist/_contracts/run-retention.js +484 -0
  35. package/dist/_contracts/run-unit.d.ts +194 -0
  36. package/dist/_contracts/run-unit.js +215 -0
  37. package/dist/_contracts/runner-event.d.ts +114 -0
  38. package/dist/_contracts/runner-event.js +187 -0
  39. package/dist/_contracts/runtime-manifest.d.ts +106 -0
  40. package/dist/_contracts/runtime-manifest.js +98 -0
  41. package/dist/_contracts/runtime-security-profile.d.ts +27 -0
  42. package/dist/_contracts/runtime-security-profile.js +82 -0
  43. package/dist/_contracts/runtime-sizes.d.ts +144 -0
  44. package/dist/_contracts/runtime-sizes.js +136 -0
  45. package/dist/_contracts/runtime-types.d.ts +212 -0
  46. package/dist/_contracts/runtime-types.js +2 -0
  47. package/dist/_contracts/sdk-errors.d.ts +34 -0
  48. package/dist/_contracts/sdk-errors.js +52 -0
  49. package/dist/_contracts/sdk-secrets.d.ts +31 -0
  50. package/dist/_contracts/sdk-secrets.js +220 -0
  51. package/dist/_contracts/side-effect-audit.d.ts +129 -0
  52. package/dist/_contracts/side-effect-audit.js +494 -0
  53. package/dist/_contracts/sse.d.ts +74 -0
  54. package/dist/_contracts/sse.js +0 -0
  55. package/dist/_contracts/stable.d.ts +26 -0
  56. package/dist/_contracts/stable.js +44 -0
  57. package/dist/_contracts/status.d.ts +19 -0
  58. package/dist/_contracts/status.js +61 -0
  59. package/dist/_contracts/submission.d.ts +383 -0
  60. package/dist/_contracts/submission.js +1380 -0
  61. package/dist/agents-md.d.ts +46 -0
  62. package/dist/agents-md.js +83 -0
  63. package/dist/agents-md.js.map +1 -0
  64. package/dist/asset-upload.d.ts +66 -0
  65. package/dist/asset-upload.js +168 -0
  66. package/dist/asset-upload.js.map +1 -0
  67. package/dist/bundle.d.ts +33 -0
  68. package/dist/bundle.js +89 -0
  69. package/dist/bundle.js.map +1 -0
  70. package/dist/cli.mjs +4140 -0
  71. package/dist/cli.mjs.sha256 +1 -0
  72. package/dist/client.d.ts +460 -0
  73. package/dist/client.js +857 -0
  74. package/dist/client.js.map +1 -0
  75. package/dist/fetch-archive.d.ts +16 -0
  76. package/dist/fetch-archive.js +170 -0
  77. package/dist/fetch-archive.js.map +1 -0
  78. package/dist/file.d.ts +57 -0
  79. package/dist/file.js +153 -0
  80. package/dist/file.js.map +1 -0
  81. package/dist/index.d.ts +30 -0
  82. package/dist/index.js +34 -0
  83. package/dist/index.js.map +1 -0
  84. package/dist/mcp-server.d.ts +84 -0
  85. package/dist/mcp-server.js +114 -0
  86. package/dist/mcp-server.js.map +1 -0
  87. package/dist/node-fs.d.ts +12 -0
  88. package/dist/node-fs.js +44 -0
  89. package/dist/node-fs.js.map +1 -0
  90. package/dist/proxy-endpoint.d.ts +131 -0
  91. package/dist/proxy-endpoint.js +147 -0
  92. package/dist/proxy-endpoint.js.map +1 -0
  93. package/dist/skill.d.ts +117 -0
  94. package/dist/skill.js +169 -0
  95. package/dist/skill.js.map +1 -0
  96. package/dist/version.d.ts +9 -0
  97. package/dist/version.js +10 -0
  98. package/dist/version.js.map +1 -0
  99. package/docs/cleanup.md +38 -0
  100. package/docs/credentials.md +153 -0
  101. package/docs/events.md +76 -0
  102. package/docs/mcp.md +47 -0
  103. package/docs/outputs.md +157 -0
  104. package/docs/product-boundaries.md +57 -0
  105. package/docs/provider-runtime-capabilities.md +103 -0
  106. package/docs/quickstart.md +110 -0
  107. package/docs/release.md +99 -0
  108. package/docs/run-config.md +53 -0
  109. package/docs/run-record.md +39 -0
  110. package/docs/skills.md +139 -0
  111. package/docs/testing.md +29 -0
  112. 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>;