History

flatten repo: move v2 to root, archive old root in legacy

Rhys Sullivan committed 8 months ago

Commit a4f61291 parent e0ea8b41206 files · +132354 −4854Browse files

Showing the changes to apps (216 of 1206 files). Show all

Unified · Split

216 files
  1. apps/api/.gitignore +1 −0
  2. apps/api/api/parse-openapi.fidelity.test.ts +461 −0
  3. apps/api/api/parse-openapi.ts +806 −0
  4. apps/api/node_modules/.bin/convex +1 −0
  5. apps/api/node_modules/.bin/tsc +1 −0
  6. apps/api/node_modules/.bin/tsserver +1 −0
  7. apps/api/node_modules/.bin/vitest +1 −0
  8. apps/api/node_modules/.bin/yaml +1 −0
  9. apps/api/node_modules/.vite/vitest/da39a3ee5e6b4b0d3255bfef95601890afd80709/results.json +1 −0
  10. apps/api/node_modules/@effect/vitest +1 −0
  11. apps/api/node_modules/@types/node +1 −0
  12. apps/api/node_modules/convex +1 −0
  13. apps/api/node_modules/effect +1 −0
  14. apps/api/node_modules/typescript +1 −0
  15. apps/api/node_modules/vitest +1 −0
  16. apps/api/node_modules/yaml +1 −0
  17. apps/api/package.json +19 −0
  18. apps/api/vercel.json +9 −0
  19. apps/cli/README.md +3 −0
  20. apps/cli/package.json +8 −0
  21. apps/cli/src/main.ts +1 −0
  22. apps/cli/tsconfig.json +4 −0
  23. apps/convex/.gitignore +2 −0
  24. apps/convex/README.md +11 −0
  25. apps/convex/convex/README.md +90 −0
  26. apps/convex/convex/_generated/api.d.ts +558 −0
  27. apps/convex/convex/_generated/api.js +23 −0
  28. apps/convex/convex/_generated/dataModel.d.ts +60 −0
  29. apps/convex/convex/_generated/server.d.ts +143 −0
  30. apps/convex/convex/_generated/server.js +93 −0
  31. apps/convex/convex/controlPlane.ts +72 −0
  32. apps/convex/convex/control_plane/actor.ts +307 −0
  33. apps/convex/convex/control_plane/approvals.ts +95 −0
  34. apps/convex/convex/control_plane/credentials.ts +564 −0
  35. apps/convex/convex/control_plane/errors.ts +82 −0
  36. apps/convex/convex/control_plane/http.ts +67 −0
  37. apps/convex/convex/control_plane/openapi_ingest.ts +1437 −0
  38. apps/convex/convex/control_plane/organizations.ts +124 −0
  39. apps/convex/convex/control_plane/policies.ts +120 −0
  40. apps/convex/convex/control_plane/service.ts +247 −0
  41. apps/convex/convex/control_plane/sources.ts +239 −0
  42. apps/convex/convex/control_plane/storage.ts +1069 −0
  43. apps/convex/convex/control_plane/tool_registry.ts +1237 −0
  44. apps/convex/convex/control_plane/tools.ts +393 −0
  45. apps/convex/convex/control_plane/workspaces.ts +78 −0
  46. apps/convex/convex/convex.config.ts +7 −0
  47. apps/convex/convex/credential_crypto.ts +102 −0
  48. apps/convex/convex/credential_resolver.ts +198 −0
  49. apps/convex/convex/executor.test.ts +1489 −0
  50. apps/convex/convex/executor.ts +29 −0
  51. apps/convex/convex/http.ts +62 −0
  52. apps/convex/convex/mcp.ts +199 −0
  53. apps/convex/convex/mcp_auth.ts +216 −0
  54. apps/convex/convex/run_executor.ts +5 −0
  55. apps/convex/convex/runtimeCallbacks.ts +124 −0
  56. apps/convex/convex/runtime_adapter.ts +10 −0
  57. apps/convex/convex/runtime_execution_port.ts +74 −0
  58. apps/convex/convex/schema.ts +236 −0
  59. apps/convex/convex/source_tool_registry.ts +1686 −0
  60. apps/convex/convex/task_runs.ts +78 −0
  61. apps/convex/convex/tsconfig.json +25 −0
  62. apps/convex/convex/workflow.ts +15 −0
  63. apps/convex/node_modules/.bin/convex +1 −0
  64. apps/convex/node_modules/.bin/vitest +1 −0
  65. apps/convex/node_modules/.vite/vitest/da39a3ee5e6b4b0d3255bfef95601890afd80709/results.json +1 −0
  66. apps/convex/node_modules/@convex-dev/workflow +1 −0
  67. apps/convex/node_modules/@effect/vitest +1 −0
  68. apps/convex/node_modules/@executor-v2/confect +1 −0
  69. apps/convex/node_modules/@executor-v2/control-plane +1 −0
  70. apps/convex/node_modules/@executor-v2/domain +1 −0
  71. apps/convex/node_modules/@executor-v2/engine +1 −0
  72. apps/convex/node_modules/@executor-v2/management-api +1 −0
  73. apps/convex/node_modules/@executor-v2/mcp-gateway +1 −0
  74. apps/convex/node_modules/@executor-v2/persistence-convex +1 −0
  75. apps/convex/node_modules/@executor-v2/persistence-ports +1 −0
  76. apps/convex/node_modules/@executor-v2/rpc +1 −0
  77. apps/convex/node_modules/@executor-v2/runtime-cloudflare-worker-loader +1 −0
  78. apps/convex/node_modules/@executor-v2/runtime-local-inproc +1 −0
  79. apps/convex/node_modules/@executor-v2/schema +1 −0
  80. apps/convex/node_modules/@executor-v2/sdk +1 −0
  81. apps/convex/node_modules/@executor-v2/state-convex +1 −0
  82. apps/convex/node_modules/@modelcontextprotocol/sdk +1 −0
  83. apps/convex/node_modules/@workos-inc/node +1 −0
  84. apps/convex/node_modules/convex +1 −0
  85. apps/convex/node_modules/convex-test +1 −0
  86. apps/convex/node_modules/effect +1 −0
  87. apps/convex/node_modules/jose +1 −0
  88. apps/convex/node_modules/vitest +1 −0
  89. apps/convex/package.json +32 −0
  90. apps/convex/src/main.ts +1 −0
  91. apps/convex/tsconfig.json +4 −0
  92. apps/pm/README.md +19 −0
  93. apps/pm/node_modules/.bin/vitest +1 −0
  94. apps/pm/node_modules/.vite/vitest/da39a3ee5e6b4b0d3255bfef95601890afd80709/results.json +1 −0
  95. apps/pm/node_modules/@effect/platform +1 −0
  96. apps/pm/node_modules/@effect/platform-bun +1 −0
  97. apps/pm/node_modules/@effect/vitest +1 −0
  98. apps/pm/node_modules/@executor-v2/control-plane +1 −0
  99. apps/pm/node_modules/@executor-v2/domain +1 −0
  100. apps/pm/node_modules/@executor-v2/engine +1 −0
  101. apps/pm/node_modules/@executor-v2/management-api +1 −0
  102. apps/pm/node_modules/@executor-v2/mcp-gateway +1 −0
  103. apps/pm/node_modules/@executor-v2/persistence-local +1 −0
  104. apps/pm/node_modules/@executor-v2/persistence-ports +1 −0
  105. apps/pm/node_modules/@executor-v2/rpc +1 −0
  106. apps/pm/node_modules/@executor-v2/runtime-cloudflare-worker-loader +1 −0
  107. apps/pm/node_modules/@executor-v2/runtime-deno-subprocess +1 −0
  108. apps/pm/node_modules/@executor-v2/runtime-local-inproc +1 −0
  109. apps/pm/node_modules/@executor-v2/schema +1 −0
  110. apps/pm/node_modules/@executor-v2/sdk +1 −0
  111. apps/pm/node_modules/@executor-v2/source-manager +1 −0
  112. apps/pm/node_modules/@modelcontextprotocol/sdk +1 −0
  113. apps/pm/node_modules/effect +1 −0
  114. apps/pm/node_modules/vitest +1 −0
  115. apps/pm/package.json +30 −0
  116. apps/pm/src/actor.ts +143 −0
  117. apps/pm/src/approvals-service.ts +264 −0
  118. apps/pm/src/config.ts +26 −0
  119. apps/pm/src/credential-resolver.ts +78 −0
  120. apps/pm/src/credentials-service.ts +263 −0
  121. apps/pm/src/execute.e2e.test.ts +167 −0
  122. apps/pm/src/http-server.ts +92 −0
  123. apps/pm/src/main.ts +239 −0
  124. apps/pm/src/mcp-handler.ts +76 −0
  125. apps/pm/src/organizations-service.ts +180 −0
  126. apps/pm/src/persistent-approval-policy.test.ts +134 −0
  127. apps/pm/src/policies-service.ts +208 −0
  128. apps/pm/src/runtime-execution-port.ts +65 −0
  129. apps/pm/src/storage-service.test.ts +161 −0
  130. apps/pm/src/storage-service.ts +939 −0
  131. apps/pm/src/tool-call-handler.test.ts +42 −0
  132. apps/pm/src/tool-call-handler.ts +107 −0
  133. apps/pm/src/tools-service.ts +253 −0
  134. apps/pm/src/workspaces-service.ts +135 −0
  135. apps/pm/tsconfig.json +7 −0
  136. apps/web/README.md +30 −0
  137. apps/web/agents.md +114 −0
  138. apps/web/app/(console)/approvals/page.tsx +5 −0
  139. apps/web/app/(console)/console-shell.tsx +56 −0
  140. apps/web/app/(console)/credentials/page.tsx +5 −0
  141. apps/web/app/(console)/layout.tsx +42 −0
  142. apps/web/app/(console)/policies/page.tsx +5 −0
  143. apps/web/app/(console)/settings/page.tsx +5 −0
  144. apps/web/app/(console)/storage/page.tsx +5 −0
  145. apps/web/app/(console)/tools/page.tsx +28 −0
  146. apps/web/app/callback/route.ts +11 −0
  147. apps/web/app/globals.css +127 −0
  148. apps/web/app/layout.tsx +38 −0
  149. apps/web/app/mcp/oauth/callback/route.ts +169 −0
  150. apps/web/app/mcp/oauth/complete/page.tsx +86 −0
  151. apps/web/app/mcp/oauth/detect/route.ts +178 −0
  152. apps/web/app/mcp/oauth/result/route.ts +89 −0
  153. apps/web/app/mcp/oauth/start/route.ts +152 −0
  154. apps/web/app/page.tsx +7 −0
  155. apps/web/app/providers.tsx +20 −0
  156. apps/web/app/sign-in/route.ts +22 −0
  157. apps/web/app/sign-out/route.ts +17 −0
  158. apps/web/components.json +20 −0
  159. apps/web/components/approvals/approvals-view.tsx +284 −0
  160. apps/web/components/credentials/credentials-view.tsx +520 −0
  161. apps/web/components/policies/policies-view.tsx +285 −0
  162. apps/web/components/settings/settings-view.tsx +522 −0
  163. apps/web/components/shared/empty-state.tsx +19 −0
  164. apps/web/components/shared/loading-state.tsx +23 −0
  165. apps/web/components/shared/match-state.tsx +55 −0
  166. apps/web/components/shared/page-header.tsx +21 −0
  167. apps/web/components/shared/status-message.tsx +25 −0
  168. apps/web/components/shell/app-shell.tsx +205 −0
  169. apps/web/components/shell/theme-switcher.tsx +82 −0
  170. apps/web/components/shell/workspace-selector.tsx +557 −0
  171. apps/web/components/storage/storage-view.tsx +852 −0
  172. apps/web/components/tools/install-configs.ts +16 −0
  173. apps/web/components/tools/schema-fields.tsx +399 −0
  174. apps/web/components/tools/source-favicon.tsx +82 −0
  175. apps/web/components/tools/source-management-panel.tsx +945 −0
  176. apps/web/components/tools/tools-view.tsx +1333 −0
  177. apps/web/components/ui/badge.tsx +29 −0
  178. apps/web/components/ui/button.tsx +40 −0
  179. apps/web/components/ui/card.tsx +41 −0
  180. apps/web/components/ui/input.tsx +16 −0
  181. apps/web/components/ui/select.tsx +17 −0
  182. apps/web/lib/control-plane/atoms/approvals.ts +70 −0
  183. apps/web/lib/control-plane/atoms/credentials.ts +87 −0
  184. apps/web/lib/control-plane/atoms/entity.ts +80 −0
  185. apps/web/lib/control-plane/atoms/index.ts +108 −0
  186. apps/web/lib/control-plane/atoms/keys.ts +22 −0
  187. apps/web/lib/control-plane/atoms/policies.ts +92 −0
  188. apps/web/lib/control-plane/atoms/settings.ts +78 −0
  189. apps/web/lib/control-plane/atoms/sources.ts +141 −0
  190. apps/web/lib/control-plane/atoms/storage.ts +124 −0
  191. apps/web/lib/control-plane/atoms/tools.ts +63 −0
  192. apps/web/lib/control-plane/client.ts +32 −0
  193. apps/web/lib/control-plane/legacy-source.ts +266 −0
  194. apps/web/lib/hooks/use-workspace.tsx +44 −0
  195. apps/web/lib/mcp/oauth-fetch.ts +112 −0
  196. apps/web/lib/mcp/oauth-popup.ts +128 −0
  197. apps/web/lib/mcp/oauth-provider.ts +249 −0
  198. apps/web/lib/mcp/oauth-request.ts +59 −0
  199. apps/web/lib/mcp/oauth-url.ts +30 −0
  200. apps/web/lib/tool/openapi-schema-refs.ts +130 −0
  201. apps/web/lib/tool/schema-traverse.ts +386 −0
  202. apps/web/lib/tools/source-helpers.ts +129 −0
  203. apps/web/lib/utils.ts +35 −0
  204. apps/web/lib/workos.ts +85 −0
  205. apps/web/middleware.ts +24 −0
  206. apps/web/next-env.d.ts +6 −0
  207. apps/web/next.config.ts +11 −0
  208. apps/web/node_modules/.bin/next +1 −0
  209. apps/web/node_modules/.bin/tldts +1 −0
  210. apps/web/node_modules/.bin/vite +1 −0
  211. apps/web/node_modules/.bin/vitest +1 −0
  212. apps/web/node_modules/.vite/deps/@effect-atom_atom-react.js +294 −0
  213. apps/web/node_modules/.vite/deps/@effect-atom_atom-react.js.map +7 −0
  214. apps/web/node_modules/.vite/deps/@effect-atom_atom.js +34 −0
  215. apps/web/node_modules/.vite/deps/@effect-atom_atom.js.map +7 −0
  216. apps/web/node_modules/.vite/deps/@effect_platform.js +6731 −0
apps/api/.gitignore+1−0
@@ -0,0 +1 @@
1.vercel
apps/api/api/parse-openapi.fidelity.test.ts+461−0
@@ -0,0 +1,461 @@
1import { describe, expect, it } from "@effect/vitest";
2import * as Effect from "effect/Effect";
3import { parse as parseYaml } from "yaml";
4
5import { extractOpenApiManifest } from "./parse-openapi";
6
7const cloudflareSpecUrl = "https://raw.githubusercontent.com/cloudflare/api-schemas/main/openapi.yaml";
8const vercelSpecUrl = "https://openapi.vercel.sh/";
9const httpMethods = ["get", "put", "post", "delete", "patch", "head", "options", "trace"] as const;
10
11const isRecord = (value: unknown): value is Record<string, unknown> =>
12 typeof value === "object" && value !== null && !Array.isArray(value);
13
14const parseSpecDocument = (input: string): unknown => {
15 const trimmed = input.trim();
16 if (trimmed.length === 0) {
17 throw new Error("Spec document is empty");
18 }
19
20 try {
21 return JSON.parse(trimmed);
22 } catch {
23 return parseYaml(trimmed);
24 }
25};
26
27const loadSpec = async (url: string): Promise<unknown> => {
28 const response = await fetch(url);
29 if (!response.ok) {
30 throw new Error(`Failed to fetch spec ${url}: ${response.status} ${response.statusText}`);
31 }
32
33 return parseSpecDocument(await response.text());
34};
35
36const collectRefKeys = (value: unknown, refs: Set<string>): void => {
37 if (Array.isArray(value)) {
38 for (const item of value) {
39 collectRefKeys(item, refs);
40 }
41 return;
42 }
43
44 if (!isRecord(value)) {
45 return;
46 }
47
48 const refValue = value.$ref;
49 if (typeof refValue === "string" && refValue.startsWith("#/")) {
50 refs.add(refValue);
51 }
52
53 for (const nested of Object.values(value)) {
54 collectRefKeys(nested, refs);
55 }
56};
57
58const unescapeJsonPointer = (value: string): string =>
59 value.replace(/~1/g, "/").replace(/~0/g, "~");
60
61const getByJsonPointer = (root: unknown, pointer: string): unknown => {
62 if (!pointer.startsWith("#/")) {
63 return null;
64 }
65
66 const segments = pointer
67 .slice(2)
68 .split("/")
69 .map((segment) => unescapeJsonPointer(segment));
70
71 let current: unknown = root;
72 for (const segment of segments) {
73 if (Array.isArray(current)) {
74 const index = Number(segment);
75 if (!Number.isInteger(index) || index < 0 || index >= current.length) {
76 return null;
77 }
78 current = current[index];
79 continue;
80 }
81
82 if (!isRecord(current) || !(segment in current)) {
83 return null;
84 }
85
86 current = current[segment];
87 }
88
89 return current;
90};
91
92const resolveLocalRef = (root: unknown, value: unknown, depth = 0): unknown => {
93 if (depth > 8 || !isRecord(value) || typeof value.$ref !== "string") {
94 return value;
95 }
96
97 const resolved = getByJsonPointer(root, value.$ref);
98 if (resolved === null) {
99 return value;
100 }
101
102 return resolveLocalRef(root, resolved, depth + 1);
103};
104
105const extractSchemaFromContent = (content: unknown): unknown | null => {
106 if (!isRecord(content)) {
107 return null;
108 }
109
110 const jsonMedia =
111 (content["application/json"] as Record<string, unknown> | undefined)
112 ?? (content["application/*+json"] as Record<string, unknown> | undefined);
113
114 if (jsonMedia && isRecord(jsonMedia.schema)) {
115 return jsonMedia.schema;
116 }
117
118 for (const mediaType of Object.values(content)) {
119 if (isRecord(mediaType) && isRecord(mediaType.schema)) {
120 return mediaType.schema;
121 }
122 }
123
124 return null;
125};
126
127const extractParameterSchema = (root: unknown, value: unknown): unknown => {
128 const parameter = resolveLocalRef(root, value);
129 if (!isRecord(parameter)) {
130 return null;
131 }
132
133 if (isRecord(parameter.schema)) {
134 return parameter.schema;
135 }
136
137 return extractSchemaFromContent(parameter.content);
138};
139
140const extractRequestBodySchema = (root: unknown, operation: Record<string, unknown>): unknown => {
141 const requestBody = resolveLocalRef(root, operation.requestBody);
142 if (!isRecord(requestBody)) {
143 return null;
144 }
145
146 return extractSchemaFromContent(requestBody.content);
147};
148
149const extractResponseSchema = (root: unknown, operation: Record<string, unknown>): unknown => {
150 const responses = resolveLocalRef(root, operation.responses);
151 if (!isRecord(responses)) {
152 return null;
153 }
154
155 const preferred = Object.keys(responses)
156 .filter((key) => /^2\d\d$/.test(key))
157 .sort();
158 if ("default" in responses) {
159 preferred.push("default");
160 }
161
162 for (const key of preferred) {
163 const response = resolveLocalRef(root, responses[key]);
164 if (!isRecord(response)) {
165 continue;
166 }
167
168 const schema = extractSchemaFromContent(response.content);
169 if (schema !== null) {
170 return schema;
171 }
172 }
173
174 return null;
175};
176
177const hasMeaningfulSchemaShape = (value: unknown): boolean => {
178 if (!isRecord(value)) {
179 return false;
180 }
181
182 if (typeof value.$ref === "string") {
183 return true;
184 }
185
186 if (typeof value.type === "string") {
187 return true;
188 }
189
190 if (Array.isArray(value.enum) && value.enum.length > 0) {
191 return true;
192 }
193
194 if (isRecord(value.properties) && Object.keys(value.properties).length > 0) {
195 return true;
196 }
197
198 if (value.items !== undefined && value.items !== null) {
199 return true;
200 }
201
202 if (Array.isArray(value.oneOf) || Array.isArray(value.anyOf) || Array.isArray(value.allOf)) {
203 return true;
204 }
205
206 if (value.additionalProperties !== undefined) {
207 return true;
208 }
209
210 return false;
211};
212
213const isUnknownLikeSchema = (value: unknown): boolean => !hasMeaningfulSchemaShape(value);
214
215type OperationExpectation = {
216 parameterSchemas: Record<string, unknown>;
217 requestBodySchema: unknown;
218 responseSchema: unknown;
219};
220
221const operationSignature = (method: string, path: string): string =>
222 `${method.toLowerCase()} ${path}`;
223
224const buildOperationExpectations = (spec: unknown): Map<string, OperationExpectation> => {
225 if (!isRecord(spec) || !isRecord(spec.paths)) {
226 throw new Error("Spec missing paths object");
227 }
228
229 const expectations = new Map<string, OperationExpectation>();
230
231 for (const [path, pathItemValue] of Object.entries(spec.paths)) {
232 if (!isRecord(pathItemValue)) {
233 continue;
234 }
235
236 const pathLevelParameters = Array.isArray(pathItemValue.parameters)
237 ? pathItemValue.parameters
238 : [];
239
240 for (const method of httpMethods) {
241 const operationValue = pathItemValue[method];
242 if (!isRecord(operationValue)) {
243 continue;
244 }
245
246 const parameterSchemas: Record<string, unknown> = {};
247 const operationLevelParameters = Array.isArray(operationValue.parameters)
248 ? operationValue.parameters
249 : [];
250
251 const parameters = [...pathLevelParameters, ...operationLevelParameters];
252 for (const parameter of parameters) {
253 const resolved = resolveLocalRef(spec, parameter);
254 if (!isRecord(resolved)) {
255 continue;
256 }
257
258 const name = typeof resolved.name === "string" ? resolved.name.trim() : "";
259 const location = typeof resolved.in === "string" ? resolved.in.trim().toLowerCase() : "";
260 if (
261 name.length === 0
262 || (
263 location !== "path"
264 && location !== "query"
265 && location !== "header"
266 && location !== "cookie"
267 )
268 ) {
269 continue;
270 }
271
272 const schema = extractParameterSchema(spec, resolved);
273 if (schema !== null) {
274 parameterSchemas[name] = schema;
275 }
276 }
277
278 expectations.set(operationSignature(method, path), {
279 parameterSchemas,
280 requestBodySchema: extractRequestBodySchema(spec, operationValue),
281 responseSchema: extractResponseSchema(spec, operationValue),
282 });
283 }
284 }
285
286 return expectations;
287};
288
289const assertManifestFidelityForSpec = (
290 specName: string,
291 spec: unknown,
292): void => {
293 const manifest = extractOpenApiManifest(specName, spec);
294 const expectations = buildOperationExpectations(spec);
295
296 for (const tool of manifest.tools) {
297 const signature = operationSignature(tool.method, tool.path);
298 const expectation = expectations.get(signature);
299 expect(expectation, `Missing operation expectation for ${signature}`).toBeDefined();
300
301 const inputSchema = tool.typing?.inputSchemaJson
302 ? JSON.parse(tool.typing.inputSchemaJson)
303 : null;
304 const outputSchema = tool.typing?.outputSchemaJson
305 ? JSON.parse(tool.typing.outputSchemaJson)
306 : null;
307
308 if (expectation) {
309 const expectedParamSchemas = Object.entries(expectation.parameterSchemas);
310 const hasStructuredParams = expectedParamSchemas.some(([, schema]) => hasMeaningfulSchemaShape(schema));
311 const hasStructuredBody = hasMeaningfulSchemaShape(expectation.requestBodySchema);
312 const hasStructuredOutput = hasMeaningfulSchemaShape(expectation.responseSchema);
313
314 if (hasStructuredParams || hasStructuredBody) {
315 expect(tool.typing?.inputSchemaJson, `Missing input schema for ${signature}`).toBeDefined();
316 expect(isRecord(inputSchema)).toBe(true);
317 expect(isRecord(inputSchema?.properties)).toBe(true);
318 }
319
320 if (hasStructuredParams && isRecord(inputSchema) && isRecord(inputSchema.properties)) {
321 for (const [paramName, sourceSchema] of expectedParamSchemas) {
322 if (!hasMeaningfulSchemaShape(sourceSchema)) {
323 continue;
324 }
325
326 expect(
327 inputSchema.properties[paramName],
328 `Missing input property '${paramName}' for ${signature}`,
329 ).toBeDefined();
330 expect(
331 isUnknownLikeSchema(inputSchema.properties[paramName]),
332 `Unknown-like input schema for '${paramName}' in ${signature}`,
333 ).toBe(false);
334 }
335 }
336
337 if (hasStructuredBody && isRecord(inputSchema) && isRecord(inputSchema.properties)) {
338 expect(inputSchema.properties.body, `Missing body schema for ${signature}`).toBeDefined();
339 expect(
340 isUnknownLikeSchema(inputSchema.properties.body),
341 `Unknown-like body schema for ${signature}`,
342 ).toBe(false);
343 }
344
345 if (hasStructuredOutput) {
346 expect(tool.typing?.outputSchemaJson, `Missing output schema for ${signature}`).toBeDefined();
347 expect(
348 isUnknownLikeSchema(outputSchema),
349 `Unknown-like output schema for ${signature}`,
350 ).toBe(false);
351 }
352 }
353
354 const refs = new Set<string>();
355 if (inputSchema) {
356 collectRefKeys(inputSchema, refs);
357 }
358 if (outputSchema) {
359 collectRefKeys(outputSchema, refs);
360 }
361
362 for (const refKey of refs) {
363 const resolvedRef = manifest.refHintTable[refKey];
364 expect(resolvedRef, `Missing refHintTable entry ${refKey} for ${signature}`).toBeDefined();
365 expect(() => JSON.parse(resolvedRef!)).not.toThrow();
366 }
367 }
368};
369
370describe("parse-openapi extractor fidelity against real specs", () => {
371 it.effect("Cloudflare path params and output refs are preserved", () =>
372 Effect.gen(function* () {
373 const cloudflareSpec = yield* Effect.tryPromise(() => loadSpec(cloudflareSpecUrl));
374 const manifest = extractOpenApiManifest("cloudflare", cloudflareSpec);
375
376 expect(manifest.tools.length).toBeGreaterThan(2000);
377
378 const accessDeleteTool = manifest.tools.find(
379 (tool) =>
380 tool.method === "delete"
381 && tool.path === "/accounts/{account_id}/access/apps/{app_id}",
382 );
383 expect(accessDeleteTool).toBeDefined();
384 expect(accessDeleteTool?.typing?.inputSchemaJson).toBeDefined();
385
386 const inputSchema = JSON.parse(accessDeleteTool!.typing!.inputSchemaJson!);
387 expect(inputSchema.type).toBe("object");
388 expect(Array.isArray(inputSchema.required)).toBe(true);
389 expect(inputSchema.required).toContain("account_id");
390 expect(inputSchema.required).toContain("app_id");
391 expect(isRecord(inputSchema.properties)).toBe(true);
392 expect(isRecord(inputSchema.properties.account_id)).toBe(true);
393 expect(isRecord(inputSchema.properties.app_id)).toBe(true);
394
395 const ipDetailsTool = manifest.tools.find(
396 (tool) =>
397 tool.name.toLowerCase().includes("jd cloud ip details")
398 || (tool.method === "get" && tool.path === "/ips"),
399 );
400 expect(ipDetailsTool).toBeDefined();
401 expect(ipDetailsTool?.typing?.outputSchemaJson).toBeDefined();
402
403 const outputSchema = JSON.parse(ipDetailsTool!.typing!.outputSchemaJson!);
404 const outputRefs = new Set<string>();
405 collectRefKeys(outputSchema, outputRefs);
406 expect(outputRefs.size).toBeGreaterThan(0);
407
408 for (const refKey of outputRefs) {
409 const schemaJson = manifest.refHintTable[refKey];
410 expect(schemaJson).toBeDefined();
411 expect(() => JSON.parse(schemaJson)).not.toThrow();
412 }
413 }),
414 30_000,
415 );
416
417 it.effect("Vercel extract keeps typed invocation + schema coverage", () =>
418 Effect.gen(function* () {
419 const vercelSpec = yield* Effect.tryPromise(() => loadSpec(vercelSpecUrl));
420 const manifest = extractOpenApiManifest("vercel", vercelSpec);
421
422 expect(manifest.tools.length).toBeGreaterThan(100);
423
424 const toolWithPathParams = manifest.tools.find(
425 (tool) => tool.invocation.parameters.some((parameter) => parameter.location === "path"),
426 );
427 expect(toolWithPathParams).toBeDefined();
428 expect(toolWithPathParams?.typing?.inputSchemaJson).toBeDefined();
429
430 const inputSchema = JSON.parse(toolWithPathParams!.typing!.inputSchemaJson!);
431 expect(isRecord(inputSchema)).toBe(true);
432 expect(inputSchema.type).toBe("object");
433 expect(isRecord(inputSchema.properties)).toBe(true);
434
435 for (const pathParameter of toolWithPathParams!.invocation.parameters.filter(
436 (parameter) => parameter.location === "path",
437 )) {
438 expect(Array.isArray(inputSchema.required)).toBe(true);
439 expect(inputSchema.required).toContain(pathParameter.name);
440 expect(inputSchema.properties[pathParameter.name]).toBeDefined();
441 }
442 }),
443 30_000,
444 );
445
446 it.effect("Cloudflare has no unknown-like schemas for structured operations", () =>
447 Effect.gen(function* () {
448 const cloudflareSpec = yield* Effect.tryPromise(() => loadSpec(cloudflareSpecUrl));
449 assertManifestFidelityForSpec("cloudflare", cloudflareSpec);
450 }),
451 60_000,
452 );
453
454 it.effect("Vercel has no unknown-like schemas for structured operations", () =>
455 Effect.gen(function* () {
456 const vercelSpec = yield* Effect.tryPromise(() => loadSpec(vercelSpecUrl));
457 assertManifestFidelityForSpec("vercel", vercelSpec);
458 }),
459 60_000,
460 );
461});
apps/api/api/parse-openapi.ts+806−0
@@ -0,0 +1,806 @@
1import { createHash } from "node:crypto";
2
3import { ConvexHttpClient } from "convex/browser";
4import { parse as parseYaml } from "yaml";
5
6const maxBodyBytes = 256 * 1024;
7const httpMethods = ["get", "put", "post", "delete", "patch", "head", "options", "trace"] as const;
8
9type HttpMethod = typeof httpMethods[number];
10type OpenApiParameterLocation = "path" | "query" | "header" | "cookie";
11
12type ExtractedTool = {
13 toolId: string;
14 name: string;
15 description: string | null;
16 method: HttpMethod;
17 path: string;
18 invocation: {
19 method: HttpMethod;
20 pathTemplate: string;
21 parameters: Array<{
22 name: string;
23 location: OpenApiParameterLocation;
24 required: boolean;
25 }>;
26 requestBody: {
27 required: boolean;
28 contentTypes: Array<string>;
29 } | null;
30 };
31 operationHash: string;
32 typing?: {
33 inputSchemaJson?: string;
34 outputSchemaJson?: string;
35 refHintKeys?: Array<string>;
36 };
37};
38
39type OpenApiManifest = {
40 sourceHash: string;
41 tools: Array<ExtractedTool>;
42 refHintTable: Record<string, string>;
43};
44
45const parseJsonDocument = (input: string): unknown => JSON.parse(input);
46const parseYamlDocument = (input: string): unknown => parseYaml(input);
47
48const isRecord = (value: unknown): value is Record<string, unknown> =>
49 typeof value === "object" && value !== null && !Array.isArray(value);
50
51const stableStringify = (value: unknown): string => {
52 if (Array.isArray(value)) {
53 return `[${value.map((entry) => stableStringify(entry)).join(",")}]`;
54 }
55
56 if (isRecord(value)) {
57 const keys = Object.keys(value).sort();
58 return `{${keys
59 .map((key) => `${JSON.stringify(key)}:${stableStringify(value[key])}`)
60 .join(",")}}`;
61 }
62
63 return JSON.stringify(value);
64};
65
66const hashUnknown = (value: unknown): string =>
67 createHash("sha256").update(stableStringify(value)).digest("hex").slice(0, 16);
68
69const normalizeText = (value: unknown): string | null => {
70 if (typeof value !== "string") {
71 return null;
72 }
73
74 const trimmed = value.trim();
75 return trimmed.length > 0 ? trimmed : null;
76};
77
78const normalizeSegment = (value: string): string =>
79 value
80 .toLowerCase()
81 .replace(/[^a-z0-9]+/g, "_")
82 .replace(/^_+|_+$/g, "");
83
84const normalizeToolId = (value: string): string =>
85 value
86 .toLowerCase()
87 .replace(/[^a-z0-9]+/g, ".")
88 .replace(/\.+/g, ".")
89 .replace(/^\.|\.$/g, "");
90
91const escapeJsonPointer = (value: string): string =>
92 value.replace(/~/g, "~0").replace(/\//g, "~1");
93
94const unescapeJsonPointer = (value: string): string =>
95 value.replace(/~1/g, "/").replace(/~0/g, "~");
96
97const getByJsonPointer = (root: unknown, pointer: string): unknown => {
98 if (!pointer.startsWith("#/")) {
99 return null;
100 }
101
102 const segments = pointer
103 .slice(2)
104 .split("/")
105 .map((segment) => unescapeJsonPointer(segment));
106
107 let current: unknown = root;
108 for (const segment of segments) {
109 if (Array.isArray(current)) {
110 const index = Number(segment);
111 if (!Number.isInteger(index) || index < 0 || index >= current.length) {
112 return null;
113 }
114 current = current[index];
115 continue;
116 }
117
118 if (!isRecord(current) || !(segment in current)) {
119 return null;
120 }
121
122 current = current[segment];
123 }
124
125 return current;
126};
127
128const resolveLocalRef = (root: unknown, value: unknown, depth = 0): unknown => {
129 if (depth > 8 || !isRecord(value) || typeof value.$ref !== "string") {
130 return value;
131 }
132
133 const resolved = getByJsonPointer(root, value.$ref);
134 if (resolved === null) {
135 return value;
136 }
137
138 return resolveLocalRef(root, resolved, depth + 1);
139};
140
141const collectLocalRefKeys = (value: unknown, target: Set<string>): void => {
142 if (Array.isArray(value)) {
143 for (const entry of value) {
144 collectLocalRefKeys(entry, target);
145 }
146 return;
147 }
148
149 if (!isRecord(value)) {
150 return;
151 }
152
153 for (const [key, entry] of Object.entries(value)) {
154 if (key === "$ref" && typeof entry === "string" && entry.startsWith("#/")) {
155 target.add(entry);
156 continue;
157 }
158
159 collectLocalRefKeys(entry, target);
160 }
161};
162
163const extractParameterSchema = (
164 root: unknown,
165 parameter: Record<string, unknown>,
166): unknown => {
167 const resolved = resolveLocalRef(root, parameter);
168 if (!isRecord(resolved)) {
169 return {};
170 }
171
172 if (isRecord(resolved.schema)) {
173 return resolved.schema;
174 }
175
176 const content = resolved.content;
177 if (isRecord(content)) {
178 const jsonMedia =
179 (content["application/json"] as Record<string, unknown> | undefined)
180 ?? (content["application/*+json"] as Record<string, unknown> | undefined);
181
182 if (jsonMedia && isRecord(jsonMedia.schema)) {
183 return jsonMedia.schema;
184 }
185
186 for (const mediaType of Object.values(content)) {
187 if (isRecord(mediaType) && isRecord(mediaType.schema)) {
188 return mediaType.schema;
189 }
190 }
191 }
192
193 return {};
194};
195
196const extractRequestBody = (
197 root: unknown,
198 operation: Record<string, unknown>,
199): {
200 required: boolean;
201 contentTypes: Array<string>;
202 schema: unknown;
203} | null => {
204 const requestBodyValue = resolveLocalRef(root, operation.requestBody);
205 if (!isRecord(requestBodyValue)) {
206 return null;
207 }
208
209 const content = requestBodyValue.content;
210 if (!isRecord(content)) {
211 return {
212 required: requestBodyValue.required === true,
213 contentTypes: [],
214 schema: {},
215 };
216 }
217
218 const contentTypes = Object.keys(content).filter((entry) => entry.trim().length > 0);
219 const jsonMedia =
220 (content["application/json"] as Record<string, unknown> | undefined)
221 ?? (content["application/*+json"] as Record<string, unknown> | undefined);
222 let schema: unknown = {};
223
224 if (jsonMedia && isRecord(jsonMedia.schema)) {
225 schema = jsonMedia.schema;
226 } else {
227 for (const mediaType of Object.values(content)) {
228 if (isRecord(mediaType) && isRecord(mediaType.schema)) {
229 schema = mediaType.schema;
230 break;
231 }
232 }
233 }
234
235 return {
236 required: requestBodyValue.required === true,
237 contentTypes,
238 schema,
239 };
240};
241
242const extractResponseSchema = (
243 root: unknown,
244 operation: Record<string, unknown>,
245): unknown | null => {
246 const responsesValue = resolveLocalRef(root, operation.responses);
247 if (!isRecord(responsesValue)) {
248 return null;
249 }
250
251 const preferredKeys = Object.keys(responsesValue)
252 .filter((key) => /^2\d\d$/.test(key))
253 .sort();
254 if ("default" in responsesValue) {
255 preferredKeys.push("default");
256 }
257
258 for (const key of preferredKeys) {
259 const candidate = resolveLocalRef(root, responsesValue[key]);
260 if (!isRecord(candidate) || !isRecord(candidate.content)) {
261 continue;
262 }
263
264 const content = candidate.content;
265 const jsonMedia =
266 (content["application/json"] as Record<string, unknown> | undefined)
267 ?? (content["application/*+json"] as Record<string, unknown> | undefined);
268
269 if (jsonMedia && isRecord(jsonMedia.schema)) {
270 return jsonMedia.schema;
271 }
272
273 for (const mediaType of Object.values(content)) {
274 if (isRecord(mediaType) && isRecord(mediaType.schema)) {
275 return mediaType.schema;
276 }
277 }
278 }
279
280 return null;
281};
282
283const buildInputSchema = (
284 root: unknown,
285 parameters: Array<Record<string, unknown>>,
286 requestBody: {
287 required: boolean;
288 schema: unknown;
289 } | null,
290): { schemaJson: string; refHintKeys: Array<string> } | null => {
291 const properties: Record<string, unknown> = {};
292 const required = new Set<string>();
293 const refKeys = new Set<string>();
294
295 for (const parameter of parameters) {
296 const resolved = resolveLocalRef(root, parameter);
297 if (!isRecord(resolved)) {
298 continue;
299 }
300
301 const location = normalizeText(resolved.in)?.toLowerCase();
302 if (
303 location !== "path"
304 && location !== "query"
305 && location !== "header"
306 && location !== "cookie"
307 ) {
308 continue;
309 }
310
311 const name = normalizeText(resolved.name);
312 if (!name) {
313 continue;
314 }
315
316 const schema = extractParameterSchema(root, resolved);
317 properties[name] = schema;
318 collectLocalRefKeys(schema, refKeys);
319
320 const isRequired = resolved.required === true || location === "path";
321 if (isRequired) {
322 required.add(name);
323 }
324 }
325
326 if (requestBody) {
327 properties.body = requestBody.schema;
328 collectLocalRefKeys(requestBody.schema, refKeys);
329 if (requestBody.required) {
330 required.add("body");
331 }
332 }
333
334 if (Object.keys(properties).length === 0) {
335 return null;
336 }
337
338 return {
339 schemaJson: JSON.stringify({
340 type: "object",
341 properties,
342 ...(required.size > 0 ? { required: Array.from(required).sort() } : {}),
343 }),
344 refHintKeys: Array.from(refKeys).sort(),
345 };
346};
347
348const buildToolId = (
349 method: HttpMethod,
350 path: string,
351 operation: Record<string, unknown>,
352): string => {
353 const operationId = normalizeText(operation.operationId);
354 if (operationId) {
355 const normalized = normalizeToolId(operationId);
356 if (normalized.length > 0) {
357 return normalized;
358 }
359 }
360
361 const rawSegments = path
362 .split("/")
363 .map((segment) => segment.trim())
364 .filter((segment) => segment.length > 0)
365 .map((segment) => {
366 if (segment.startsWith("{") && segment.endsWith("}")) {
367 return segment.slice(1, -1);
368 }
369 return segment;
370 })
371 .map((segment) => normalizeSegment(segment))
372 .filter((segment) => segment.length > 0);
373
374 const segments = rawSegments.length > 0 ? rawSegments.slice(0, 6) : ["operation"];
375 return normalizeToolId(`${segments.join(".")}.${method}`);
376};
377
378const dedupeToolIds = (tools: Array<ExtractedTool>): Array<ExtractedTool> => {
379 const counts = new Map<string, number>();
380
381 return tools.map((tool) => {
382 const count = (counts.get(tool.toolId) ?? 0) + 1;
383 counts.set(tool.toolId, count);
384
385 if (count === 1) {
386 return tool;
387 }
388
389 return {
390 ...tool,
391 toolId: `${tool.toolId}_${count}`,
392 };
393 });
394};
395
396const buildRefHintTable = (
397 root: unknown,
398 initialRefs: ReadonlyArray<string>,
399): Record<string, string> => {
400 const table: Record<string, string> = {};
401 const queue = [...initialRefs];
402 const visited = new Set<string>();
403
404 while (queue.length > 0) {
405 const ref = queue.shift();
406 if (!ref || visited.has(ref)) {
407 continue;
408 }
409 visited.add(ref);
410
411 const resolved = getByJsonPointer(root, ref);
412 if (resolved === null) {
413 continue;
414 }
415
416 table[ref] = JSON.stringify(resolved);
417
418 const nestedRefs = new Set<string>();
419 collectLocalRefKeys(resolved, nestedRefs);
420 for (const nestedRef of nestedRefs) {
421 if (!visited.has(nestedRef)) {
422 queue.push(nestedRef);
423 }
424 }
425 }
426
427 return table;
428};
429
430export const extractOpenApiManifest = (
431 _sourceName: string,
432 openApiSpec: unknown,
433): OpenApiManifest => {
434 if (!isRecord(openApiSpec)) {
435 throw new Error("OpenAPI document must be an object");
436 }
437
438 const paths = openApiSpec.paths;
439 if (!isRecord(paths)) {
440 throw new Error("OpenAPI document is missing paths");
441 }
442
443 const tools: Array<ExtractedTool> = [];
444 const globalRefKeys = new Set<string>();
445
446 for (const [path, pathItemValue] of Object.entries(paths)) {
447 if (!isRecord(pathItemValue)) {
448 continue;
449 }
450
451 const sharedParameters = Array.isArray(pathItemValue.parameters)
452 ? pathItemValue.parameters.filter((entry): entry is Record<string, unknown> => isRecord(entry))
453 : [];
454
455 for (const method of httpMethods) {
456 const operationValue = pathItemValue[method];
457 if (!isRecord(operationValue)) {
458 continue;
459 }
460
461 const operationParameters = Array.isArray(operationValue.parameters)
462 ? operationValue.parameters.filter((entry): entry is Record<string, unknown> => isRecord(entry))
463 : [];
464 const parameters = [...sharedParameters, ...operationParameters];
465 const requestBody = extractRequestBody(openApiSpec, operationValue);
466
467 const invocation = {
468 method,
469 pathTemplate: path,
470 parameters: parameters
471 .map((parameter) => resolveLocalRef(openApiSpec, parameter))
472 .filter((parameter): parameter is Record<string, unknown> => isRecord(parameter))
473 .map((parameter) => ({
474 name: normalizeText(parameter.name) ?? "",
475 location:
476 (normalizeText(parameter.in)?.toLowerCase() as OpenApiParameterLocation | undefined)
477 ?? "query",
478 required:
479 parameter.required === true
480 || normalizeText(parameter.in)?.toLowerCase() === "path",
481 }))
482 .filter((parameter) =>
483 parameter.name.length > 0
484 && (
485 parameter.location === "path"
486 || parameter.location === "query"
487 || parameter.location === "header"
488 || parameter.location === "cookie"
489 ))
490 .sort((left, right) =>
491 left.location === right.location
492 ? left.name.localeCompare(right.name)
493 : left.location.localeCompare(right.location)),
494 requestBody: requestBody
495 ? {
496 required: requestBody.required,
497 contentTypes: requestBody.contentTypes,
498 }
499 : null,
500 };
501
502 const inputTyping = buildInputSchema(openApiSpec, parameters, requestBody);
503 const outputSchema = extractResponseSchema(openApiSpec, operationValue);
504 const outputSchemaJson = outputSchema === null ? null : JSON.stringify(outputSchema);
505 if (outputSchema !== null) {
506 collectLocalRefKeys(outputSchema, globalRefKeys);
507 }
508
509 if (inputTyping) {
510 for (const refKey of inputTyping.refHintKeys) {
511 globalRefKeys.add(refKey);
512 }
513 }
514
515 const name =
516 normalizeText(operationValue.summary)
517 ?? normalizeText(operationValue.operationId)
518 ?? `${method.toUpperCase()} ${path}`;
519 const description =
520 normalizeText(operationValue.description)
521 ?? normalizeText(operationValue.summary)
522 ?? null;
523 const toolId = buildToolId(method, path, operationValue);
524
525 tools.push({
526 toolId,
527 name,
528 description,
529 method,
530 path,
531 invocation,
532 operationHash: hashUnknown({
533 method,
534 path,
535 invocation,
536 inputSchemaJson: inputTyping?.schemaJson ?? null,
537 outputSchemaJson,
538 }),
539 typing: {
540 ...(inputTyping ? { inputSchemaJson: inputTyping.schemaJson } : {}),
541 ...(outputSchemaJson ? { outputSchemaJson } : {}),
542 ...(inputTyping && inputTyping.refHintKeys.length > 0
543 ? { refHintKeys: inputTyping.refHintKeys }
544 : {}),
545 },
546 });
547 }
548 }
549
550 const deduped = dedupeToolIds(tools);
551 const refHintTable = buildRefHintTable(openApiSpec, Array.from(globalRefKeys));
552
553 return {
554 sourceHash: hashUnknown({
555 tools: deduped.map((tool) => ({
556 toolId: tool.toolId,
557 operationHash: tool.operationHash,
558 })),
559 refKeys: Object.keys(refHintTable).sort(),
560 }),
561 tools: deduped,
562 refHintTable,
563 };
564};
565
566const parseOpenApiDocument = (input: string): unknown => {
567 const text = input.trim();
568 if (text.length === 0) {
569 throw new Error("OpenAPI document is empty");
570 }
571
572 try {
573 return parseJsonDocument(text);
574 } catch {
575 try {
576 return parseYamlDocument(text);
577 } catch (cause) {
578 throw new Error(
579 `Unable to parse OpenAPI document as JSON or YAML: ${
580 cause instanceof Error ? cause.message : String(cause)
581 }`,
582 );
583 }
584 }
585};
586
587const readRawBody = async (request: AsyncIterable<unknown>): Promise<string> => {
588 const chunks: Array<Buffer> = [];
589 let bytes = 0;
590
591 for await (const chunk of request) {
592 const buffer = Buffer.isBuffer(chunk)
593 ? chunk
594 : typeof chunk === "string"
595 ? Buffer.from(chunk)
596 : chunk instanceof Uint8Array
597 ? Buffer.from(chunk)
598 : Buffer.from(String(chunk));
599 bytes += buffer.length;
600 if (bytes > maxBodyBytes) {
601 throw new Error("Request body too large");
602 }
603 chunks.push(buffer);
604 }
605
606 return Buffer.concat(chunks).toString("utf8");
607};
608
609const json = (
610 response: any,
611 status: number,
612 payload: Record<string, unknown>,
613): void => {
614 response.status(status).setHeader("content-type", "application/json; charset=utf-8");
615 response.send(JSON.stringify(payload));
616};
617
618const normalizeNamespacePart = (value: string): string => {
619 const normalized = value
620 .trim()
621 .toLowerCase()
622 .replace(/[^a-z0-9]+/g, "_")
623 .replace(/^_+|_+$/g, "");
624
625 return normalized.length > 0 ? normalized : "source";
626};
627
628const sourceNamespace = (sourceName: string, sourceId: string): string => {
629 const sourceIdSuffix = sourceId.slice(-6).toLowerCase();
630 return `${normalizeNamespacePart(sourceName)}_${sourceIdSuffix}`;
631};
632
633const parseSourceEnabled = (value: unknown): boolean =>
634 typeof value === "boolean" ? value : true;
635
636const toIngestPayload = async (
637 openApiSpec: unknown,
638 input: {
639 convexUrl: string;
640 ingestToken: string;
641 workspaceId: string;
642 sourceId: string;
643 sourceName: string;
644 sourceEndpoint: string;
645 sourceEnabled: boolean;
646 },
647): Promise<{
648 artifactId: string;
649 sourceHash: string;
650 toolCount: number;
651 namespace: string;
652}> => {
653 const manifest = extractOpenApiManifest(input.sourceName, openApiSpec);
654
655 const refs = Object.entries(manifest.refHintTable ?? {}).map(([refKey, schemaJson]) => ({
656 refKey,
657 schemaJson,
658 }));
659
660 const tools = manifest.tools.map((tool) => ({
661 toolId: tool.toolId,
662 name: tool.name,
663 description: tool.description,
664 method: tool.method,
665 path: tool.path,
666 operationHash: tool.operationHash,
667 invocationJson: JSON.stringify(tool.invocation),
668 inputSchemaJson: tool.typing?.inputSchemaJson ?? null,
669 outputSchemaJson: tool.typing?.outputSchemaJson ?? null,
670 }));
671
672 const convex = new ConvexHttpClient(input.convexUrl);
673 const result = await (convex as any).action("control_plane/tool_registry:ingestOpenApiManifest", {
674 token: input.ingestToken,
675 workspaceId: input.workspaceId,
676 sourceId: input.sourceId,
677 sourceName: input.sourceName,
678 sourceEndpoint: input.sourceEndpoint,
679 sourceEnabled: input.sourceEnabled,
680 sourceHash: manifest.sourceHash,
681 toolCount: manifest.tools.length,
682 refs,
683 tools,
684 }) as {
685 artifactId: string;
686 };
687
688 return {
689 artifactId: result.artifactId,
690 sourceHash: manifest.sourceHash,
691 toolCount: manifest.tools.length,
692 namespace: sourceNamespace(input.sourceName, input.sourceId),
693 };
694};
695
696const parseEndpoint = async (request: any, response: any) => {
697 if (request.method !== "POST") {
698 response.setHeader("allow", "POST");
699 json(response, 405, { error: "Method not allowed" });
700 return;
701 }
702
703 try {
704 const expectedToken = process.env.OPENAPI_PARSE_API_TOKEN?.trim();
705 const provided =
706 typeof request.headers["x-openapi-parse-token"] === "string"
707 ? request.headers["x-openapi-parse-token"].trim()
708 : "";
709 if (expectedToken && expectedToken.length > 0 && provided !== expectedToken) {
710 json(response, 401, { error: "Unauthorized" });
711 return;
712 }
713
714 const rawBody = await readRawBody(request);
715 const payload = JSON.parse(rawBody) as Record<string, unknown>;
716 const specUrl = typeof payload.specUrl === "string" ? payload.specUrl.trim() : "";
717
718 if (specUrl.length === 0) {
719 json(response, 400, { error: "specUrl is required" });
720 return;
721 }
722
723 const parsedUrl = new URL(specUrl);
724 const protocol = parsedUrl.protocol.toLowerCase();
725 if (protocol !== "https:" && protocol !== "http:") {
726 json(response, 400, { error: "specUrl must use http:// or https://" });
727 return;
728 }
729
730 const upstream = await fetch(specUrl);
731 if (!upstream.ok) {
732 json(response, 502, {
733 error: "Failed fetching OpenAPI document",
734 status: upstream.status,
735 statusText: upstream.statusText,
736 });
737 return;
738 }
739
740 const bodyText = await upstream.text();
741 const openApiSpec = parseOpenApiDocument(bodyText);
742
743 const workspaceId = typeof payload.workspaceId === "string" ? payload.workspaceId.trim() : "";
744 const sourceId = typeof payload.sourceId === "string" ? payload.sourceId.trim() : "";
745 const sourceName = typeof payload.sourceName === "string" ? payload.sourceName.trim() : "";
746
747 const convexUrl =
748 process.env.CONVEX_URL?.trim()
749 || process.env.NEXT_PUBLIC_CONVEX_URL?.trim()
750 || "";
751 const ingestToken =
752 process.env.OPENAPI_INGEST_SERVICE_TOKEN?.trim()
753 || process.env.OPENAPI_PARSE_API_TOKEN?.trim()
754 || "";
755
756 const shouldIngest =
757 workspaceId.length > 0
758 && sourceId.length > 0
759 && sourceName.length > 0
760 && convexUrl.length > 0;
761
762 if (shouldIngest) {
763 const ingested = await toIngestPayload(openApiSpec, {
764 convexUrl,
765 ingestToken,
766 workspaceId,
767 sourceId,
768 sourceName,
769 sourceEndpoint: specUrl,
770 sourceEnabled: parseSourceEnabled(payload.sourceEnabled),
771 });
772
773 json(response, 200, {
774 ok: true,
775 mode: "ingested",
776 specUrl,
777 artifactId: ingested.artifactId,
778 sourceHash: ingested.sourceHash,
779 toolCount: ingested.toolCount,
780 namespace: ingested.namespace,
781 artifactBatchCount: 0,
782 });
783 return;
784 }
785
786 json(response, 200, {
787 ok: true,
788 mode: "parsed",
789 specUrl,
790 openApiSpec,
791 });
792 } catch (cause) {
793 json(response, 500, {
794 ok: false,
795 error: cause instanceof Error ? cause.message : String(cause),
796 });
797 }
798};
799
800export const config = {
801 api: {
802 bodyParser: false,
803 },
804};
805
806export default parseEndpoint;
apps/api/node_modules/.bin/convex+1−0
@@ -0,0 +1 @@
1../convex/bin/main.js
apps/api/node_modules/.bin/tsc+1−0
@@ -0,0 +1 @@
1../typescript/bin/tsc
apps/api/node_modules/.bin/tsserver+1−0
@@ -0,0 +1 @@
1../typescript/bin/tsserver
apps/api/node_modules/.bin/vitest+1−0
@@ -0,0 +1 @@
1../vitest/vitest.mjs
apps/api/node_modules/.bin/yaml+1−0
@@ -0,0 +1 @@
1../yaml/bin.mjs
apps/api/node_modules/.vite/vitest/da39a3ee5e6b4b0d3255bfef95601890afd80709/results.json+1−0
@@ -0,0 +1 @@
1{"version":"3.2.4","results":[[":api/parse-openapi.fidelity.test.ts",{"duration":15450.162534,"failed":false}]]}
apps/api/node_modules/@effect/vitest+1−0
@@ -0,0 +1 @@
1../../../../node_modules/.bun/@effect+vitest@0.27.0+745106daec5afff3/node_modules/@effect/vitest
apps/api/node_modules/@types/node+1−0
@@ -0,0 +1 @@
1../../../../node_modules/.bun/@types+node@20.19.33/node_modules/@types/node
apps/api/node_modules/convex+1−0
@@ -0,0 +1 @@
1../../../node_modules/.bun/convex@1.32.0+b1ab299f0a400331/node_modules/convex
apps/api/node_modules/effect+1−0
@@ -0,0 +1 @@
1../../../node_modules/.bun/effect@3.19.19/node_modules/effect
apps/api/node_modules/typescript+1−0
@@ -0,0 +1 @@
1../../../node_modules/.bun/typescript@5.9.3/node_modules/typescript
apps/api/node_modules/vitest+1−0
@@ -0,0 +1 @@
1../../../node_modules/.bun/vitest@3.2.4+dddfa60a3fc73abb/node_modules/vitest
apps/api/node_modules/yaml+1−0
@@ -0,0 +1 @@
1../../../node_modules/.bun/yaml@2.8.2/node_modules/yaml
apps/api/package.json+19−0
@@ -0,0 +1,19 @@
1{
2 "name": "@executor-v2/app-api",
3 "private": true,
4 "type": "module",
5 "scripts": {
6 "dev:disabled": "bunx vercel dev --listen 8788"
7 },
8 "dependencies": {
9 "convex": "^1.32.0",
10 "yaml": "^2.8.1"
11 },
12 "devDependencies": {
13 "@effect/vitest": "^0.27.0",
14 "@types/node": "^20.19.9",
15 "effect": "^3.19.8",
16 "typescript": "^5.9.3",
17 "vitest": "^3.2.4"
18 }
19}
apps/api/vercel.json+9−0
@@ -0,0 +1,9 @@
1{
2 "$schema": "https://openapi.vercel.sh/vercel.json",
3 "rewrites": [
4 {
5 "source": "/parse-openapi",
6 "destination": "/api/parse-openapi"
7 }
8 ]
9}
apps/cli/README.md+3−0
@@ -0,0 +1,3 @@
1# app-cli
2
3CLI app scaffold for Executor v2.
apps/cli/package.json+8−0
@@ -0,0 +1,8 @@
1{
2 "name": "@executor-v2/app-cli",
3 "private": true,
4 "type": "module",
5 "scripts": {
6 "typecheck": "bunx tsc --noEmit -p tsconfig.json"
7 }
8}
apps/cli/src/main.ts+1−0
@@ -0,0 +1 @@
1export {};
apps/cli/tsconfig.json+4−0
@@ -0,0 +1,4 @@
1{
2 "extends": "../../tsconfig.json",
3 "include": ["src"]
4}
apps/convex/.gitignore+2−0
@@ -0,0 +1,2 @@
1
2.env.local
apps/convex/README.md+11−0
@@ -0,0 +1,11 @@
1# app-convex
2
3Convex remote server app scaffold for Executor v2.
4
5Current scaffold includes:
6 Convex schema wiring lives directly in `convex/schema.ts`
7 MCP HTTP endpoint at `GET/POST/DELETE /v1/mcp` via `convex/http.ts` and `convex/mcp.ts`
8 runtime callback endpoint at `POST /v1/runtime/tool-call`
9 control-plane source endpoints at `GET/POST /v1/workspaces/:workspaceId/sources`
10 control-plane source removal endpoint at `DELETE /v1/workspaces/:workspaceId/sources/:sourceId`
11 generated OpenAPI spec endpoint at `GET /v1/openapi.json`
apps/convex/convex/README.md+90−0
@@ -0,0 +1,90 @@
1# Welcome to your Convex functions directory!
2
3Write your Convex functions here.
4See https://docs.convex.dev/functions for more.
5
6A query function that takes two arguments looks like:
7
8```ts
9// convex/myFunctions.ts
10import { query } from "./_generated/server";
11import { v } from "convex/values";
12
13export const myQueryFunction = query({
14 // Validators for arguments.
15 args: {
16 first: v.number(),
17 second: v.string(),
18 },
19
20 // Function implementation.
21 handler: async (ctx, args) => {
22 // Read the database as many times as you need here.
23 // See https://docs.convex.dev/database/reading-data.
24 const documents = await ctx.db.query("tablename").collect();
25
26 // Arguments passed from the client are properties of the args object.
27 console.log(args.first, args.second);
28
29 // Write arbitrary JavaScript here: filter, aggregate, build derived data,
30 // remove non-public properties, or create new objects.
31 return documents;
32 },
33});
34```
35
36Using this query function in a React component looks like:
37
38```ts
39const data = useQuery(api.myFunctions.myQueryFunction, {
40 first: 10,
41 second: "hello",
42});
43```
44
45A mutation function looks like:
46
47```ts
48// convex/myFunctions.ts
49import { mutation } from "./_generated/server";
50import { v } from "convex/values";
51
52export const myMutationFunction = mutation({
53 // Validators for arguments.
54 args: {
55 first: v.string(),
56 second: v.string(),
57 },
58
59 // Function implementation.
60 handler: async (ctx, args) => {
61 // Insert or modify documents in the database here.
62 // Mutations can also read from the database like queries.
63 // See https://docs.convex.dev/database/writing-data.
64 const message = { body: args.first, author: args.second };
65 const id = await ctx.db.insert("messages", message);
66
67 // Optionally, return a value from your mutation.
68 return await ctx.db.get("messages", id);
69 },
70});
71```
72
73Using this mutation function in a React component looks like:
74
75```ts
76const mutation = useMutation(api.myFunctions.myMutationFunction);
77function handleButtonPress() {
78 // fire and forget, the most common way to use mutations
79 mutation({ first: "Hello!", second: "me" });
80 // OR
81 // use the result once the mutation has completed
82 mutation({ first: "Hello!", second: "me" }).then((result) =>
83 console.log(result),
84 );
85}
86```
87
88Use the Convex CLI to push your functions to a deployment. See everything
89the Convex CLI can do by running `npx convex -h` in your project root
90directory. To learn more, launch the docs with `npx convex docs`.
apps/convex/convex/_generated/api.d.ts+558−0
@@ -0,0 +1,558 @@
1/* eslint-disable */
2/**
3 * Generated `api` utility.
4 *
5 * THIS CODE IS AUTOMATICALLY GENERATED.
6 *
7 * To regenerate, run `npx convex dev`.
8 * @module
9 */
10
11import type * as controlPlane from "../controlPlane.js";
12import type * as control_plane_actor from "../control_plane/actor.js";
13import type * as control_plane_approvals from "../control_plane/approvals.js";
14import type * as control_plane_credentials from "../control_plane/credentials.js";
15import type * as control_plane_errors from "../control_plane/errors.js";
16import type * as control_plane_http from "../control_plane/http.js";
17import type * as control_plane_openapi_ingest from "../control_plane/openapi_ingest.js";
18import type * as control_plane_organizations from "../control_plane/organizations.js";
19import type * as control_plane_policies from "../control_plane/policies.js";
20import type * as control_plane_service from "../control_plane/service.js";
21import type * as control_plane_sources from "../control_plane/sources.js";
22import type * as control_plane_storage from "../control_plane/storage.js";
23import type * as control_plane_tool_registry from "../control_plane/tool_registry.js";
24import type * as control_plane_tools from "../control_plane/tools.js";
25import type * as control_plane_workspaces from "../control_plane/workspaces.js";
26import type * as credential_crypto from "../credential_crypto.js";
27import type * as credential_resolver from "../credential_resolver.js";
28import type * as executor from "../executor.js";
29import type * as http from "../http.js";
30import type * as mcp from "../mcp.js";
31import type * as mcp_auth from "../mcp_auth.js";
32import type * as run_executor from "../run_executor.js";
33import type * as runtimeCallbacks from "../runtimeCallbacks.js";
34import type * as runtime_adapter from "../runtime_adapter.js";
35import type * as runtime_execution_port from "../runtime_execution_port.js";
36import type * as source_tool_registry from "../source_tool_registry.js";
37import type * as task_runs from "../task_runs.js";
38import type * as workflow from "../workflow.js";
39
40import type {
41 ApiFromModules,
42 FilterApi,
43 FunctionReference,
44} from "convex/server";
45
46declare const fullApi: ApiFromModules<{
47 controlPlane: typeof controlPlane;
48 "control_plane/actor": typeof control_plane_actor;
49 "control_plane/approvals": typeof control_plane_approvals;
50 "control_plane/credentials": typeof control_plane_credentials;
51 "control_plane/errors": typeof control_plane_errors;
52 "control_plane/http": typeof control_plane_http;
53 "control_plane/openapi_ingest": typeof control_plane_openapi_ingest;
54 "control_plane/organizations": typeof control_plane_organizations;
55 "control_plane/policies": typeof control_plane_policies;
56 "control_plane/service": typeof control_plane_service;
57 "control_plane/sources": typeof control_plane_sources;
58 "control_plane/storage": typeof control_plane_storage;
59 "control_plane/tool_registry": typeof control_plane_tool_registry;
60 "control_plane/tools": typeof control_plane_tools;
61 "control_plane/workspaces": typeof control_plane_workspaces;
62 credential_crypto: typeof credential_crypto;
63 credential_resolver: typeof credential_resolver;
64 executor: typeof executor;
65 http: typeof http;
66 mcp: typeof mcp;
67 mcp_auth: typeof mcp_auth;
68 run_executor: typeof run_executor;
69 runtimeCallbacks: typeof runtimeCallbacks;
70 runtime_adapter: typeof runtime_adapter;
71 runtime_execution_port: typeof runtime_execution_port;
72 source_tool_registry: typeof source_tool_registry;
73 task_runs: typeof task_runs;
74 workflow: typeof workflow;
75}>;
76
77/**
78 * A utility for referencing Convex functions in your app's public API.
79 *
80 * Usage:
81 * ```js
82 * const myFunctionReference = api.myModule.myFunction;
83 * ```
84 */
85export declare const api: FilterApi<
86 typeof fullApi,
87 FunctionReference<any, "public">
88>;
89
90/**
91 * A utility for referencing Convex functions in your app's internal API.
92 *
93 * Usage:
94 * ```js
95 * const myFunctionReference = internal.myModule.myFunction;
96 * ```
97 */
98export declare const internal: FilterApi<
99 typeof fullApi,
100 FunctionReference<any, "internal">
101>;
102
103export declare const components: {
104 workflow: {
105 event: {
106 create: FunctionReference<
107 "mutation",
108 "internal",
109 { name: string; workflowId: string },
110 string
111 >;
112 send: FunctionReference<
113 "mutation",
114 "internal",
115 {
116 eventId?: string;
117 name?: string;
118 result:
119 | { kind: "success"; returnValue: any }
120 | { error: string; kind: "failed" }
121 | { kind: "canceled" };
122 workflowId?: string;
123 workpoolOptions?: {
124 defaultRetryBehavior?: {
125 base: number;
126 initialBackoffMs: number;
127 maxAttempts: number;
128 };
129 logLevel?: "DEBUG" | "TRACE" | "INFO" | "REPORT" | "WARN" | "ERROR";
130 maxParallelism?: number;
131 retryActionsByDefault?: boolean;
132 };
133 },
134 string
135 >;
136 };
137 journal: {
138 load: FunctionReference<
139 "query",
140 "internal",
141 { shortCircuit?: boolean; workflowId: string },
142 {
143 blocked?: boolean;
144 journalEntries: Array<{
145 _creationTime: number;
146 _id: string;
147 step:
148 | {
149 args: any;
150 argsSize: number;
151 completedAt?: number;
152 functionType: "query" | "mutation" | "action";
153 handle: string;
154 inProgress: boolean;
155 kind?: "function";
156 name: string;
157 runResult?:
158 | { kind: "success"; returnValue: any }
159 | { error: string; kind: "failed" }
160 | { kind: "canceled" };
161 startedAt: number;
162 workId?: string;
163 }
164 | {
165 args: any;
166 argsSize: number;
167 completedAt?: number;
168 handle: string;
169 inProgress: boolean;
170 kind: "workflow";
171 name: string;
172 runResult?:
173 | { kind: "success"; returnValue: any }
174 | { error: string; kind: "failed" }
175 | { kind: "canceled" };
176 startedAt: number;
177 workflowId?: string;
178 }
179 | {
180 args: { eventId?: string };
181 argsSize: number;
182 completedAt?: number;
183 eventId?: string;
184 inProgress: boolean;
185 kind: "event";
186 name: string;
187 runResult?:
188 | { kind: "success"; returnValue: any }
189 | { error: string; kind: "failed" }
190 | { kind: "canceled" };
191 startedAt: number;
192 };
193 stepNumber: number;
194 workflowId: string;
195 }>;
196 logLevel: "DEBUG" | "TRACE" | "INFO" | "REPORT" | "WARN" | "ERROR";
197 ok: boolean;
198 workflow: {
199 _creationTime: number;
200 _id: string;
201 args: any;
202 generationNumber: number;
203 logLevel?: any;
204 name?: string;
205 onComplete?: { context?: any; fnHandle: string };
206 runResult?:
207 | { kind: "success"; returnValue: any }
208 | { error: string; kind: "failed" }
209 | { kind: "canceled" };
210 startedAt?: any;
211 state?: any;
212 workflowHandle: string;
213 };
214 }
215 >;
216 startSteps: FunctionReference<
217 "mutation",
218 "internal",
219 {
220 generationNumber: number;
221 steps: Array<{
222 retry?:
223 | boolean
224 | { base: number; initialBackoffMs: number; maxAttempts: number };
225 schedulerOptions?: { runAt?: number } | { runAfter?: number };
226 step:
227 | {
228 args: any;
229 argsSize: number;
230 completedAt?: number;
231 functionType: "query" | "mutation" | "action";
232 handle: string;
233 inProgress: boolean;
234 kind?: "function";
235 name: string;
236 runResult?:
237 | { kind: "success"; returnValue: any }
238 | { error: string; kind: "failed" }
239 | { kind: "canceled" };
240 startedAt: number;
241 workId?: string;
242 }
243 | {
244 args: any;
245 argsSize: number;
246 completedAt?: number;
247 handle: string;
248 inProgress: boolean;
249 kind: "workflow";
250 name: string;
251 runResult?:
252 | { kind: "success"; returnValue: any }
253 | { error: string; kind: "failed" }
254 | { kind: "canceled" };
255 startedAt: number;
256 workflowId?: string;
257 }
258 | {
259 args: { eventId?: string };
260 argsSize: number;
261 completedAt?: number;
262 eventId?: string;
263 inProgress: boolean;
264 kind: "event";
265 name: string;
266 runResult?:
267 | { kind: "success"; returnValue: any }
268 | { error: string; kind: "failed" }
269 | { kind: "canceled" };
270 startedAt: number;
271 };
272 }>;
273 workflowId: string;
274 workpoolOptions?: {
275 defaultRetryBehavior?: {
276 base: number;
277 initialBackoffMs: number;
278 maxAttempts: number;
279 };
280 logLevel?: "DEBUG" | "TRACE" | "INFO" | "REPORT" | "WARN" | "ERROR";
281 maxParallelism?: number;
282 retryActionsByDefault?: boolean;
283 };
284 },
285 Array<{
286 _creationTime: number;
287 _id: string;
288 step:
289 | {
290 args: any;
291 argsSize: number;
292 completedAt?: number;
293 functionType: "query" | "mutation" | "action";
294 handle: string;
295 inProgress: boolean;
296 kind?: "function";
297 name: string;
298 runResult?:
299 | { kind: "success"; returnValue: any }
300 | { error: string; kind: "failed" }
301 | { kind: "canceled" };
302 startedAt: number;
303 workId?: string;
304 }
305 | {
306 args: any;
307 argsSize: number;
308 completedAt?: number;
309 handle: string;
310 inProgress: boolean;
311 kind: "workflow";
312 name: string;
313 runResult?:
314 | { kind: "success"; returnValue: any }
315 | { error: string; kind: "failed" }
316 | { kind: "canceled" };
317 startedAt: number;
318 workflowId?: string;
319 }
320 | {
321 args: { eventId?: string };
322 argsSize: number;
323 completedAt?: number;
324 eventId?: string;
325 inProgress: boolean;
326 kind: "event";
327 name: string;
328 runResult?:
329 | { kind: "success"; returnValue: any }
330 | { error: string; kind: "failed" }
331 | { kind: "canceled" };
332 startedAt: number;
333 };
334 stepNumber: number;
335 workflowId: string;
336 }>
337 >;
338 };
339 workflow: {
340 cancel: FunctionReference<
341 "mutation",
342 "internal",
343 { workflowId: string },
344 null
345 >;
346 cleanup: FunctionReference<
347 "mutation",
348 "internal",
349 { workflowId: string },
350 boolean
351 >;
352 complete: FunctionReference<
353 "mutation",
354 "internal",
355 {
356 generationNumber: number;
357 runResult:
358 | { kind: "success"; returnValue: any }
359 | { error: string; kind: "failed" }
360 | { kind: "canceled" };
361 workflowId: string;
362 },
363 null
364 >;
365 create: FunctionReference<
366 "mutation",
367 "internal",
368 {
369 maxParallelism?: number;
370 onComplete?: { context?: any; fnHandle: string };
371 startAsync?: boolean;
372 workflowArgs: any;
373 workflowHandle: string;
374 workflowName: string;
375 },
376 string
377 >;
378 getStatus: FunctionReference<
379 "query",
380 "internal",
381 { workflowId: string },
382 {
383 inProgress: Array<{
384 _creationTime: number;
385 _id: string;
386 step:
387 | {
388 args: any;
389 argsSize: number;
390 completedAt?: number;
391 functionType: "query" | "mutation" | "action";
392 handle: string;
393 inProgress: boolean;
394 kind?: "function";
395 name: string;
396 runResult?:
397 | { kind: "success"; returnValue: any }
398 | { error: string; kind: "failed" }
399 | { kind: "canceled" };
400 startedAt: number;
401 workId?: string;
402 }
403 | {
404 args: any;
405 argsSize: number;
406 completedAt?: number;
407 handle: string;
408 inProgress: boolean;
409 kind: "workflow";
410 name: string;
411 runResult?:
412 | { kind: "success"; returnValue: any }
413 | { error: string; kind: "failed" }
414 | { kind: "canceled" };
415 startedAt: number;
416 workflowId?: string;
417 }
418 | {
419 args: { eventId?: string };
420 argsSize: number;
421 completedAt?: number;
422 eventId?: string;
423 inProgress: boolean;
424 kind: "event";
425 name: string;
426 runResult?:
427 | { kind: "success"; returnValue: any }
428 | { error: string; kind: "failed" }
429 | { kind: "canceled" };
430 startedAt: number;
431 };
432 stepNumber: number;
433 workflowId: string;
434 }>;
435 logLevel: "DEBUG" | "TRACE" | "INFO" | "REPORT" | "WARN" | "ERROR";
436 workflow: {
437 _creationTime: number;
438 _id: string;
439 args: any;
440 generationNumber: number;
441 logLevel?: any;
442 name?: string;
443 onComplete?: { context?: any; fnHandle: string };
444 runResult?:
445 | { kind: "success"; returnValue: any }
446 | { error: string; kind: "failed" }
447 | { kind: "canceled" };
448 startedAt?: any;
449 state?: any;
450 workflowHandle: string;
451 };
452 }
453 >;
454 list: FunctionReference<
455 "query",
456 "internal",
457 {
458 order: "asc" | "desc";
459 paginationOpts: {
460 cursor: string | null;
461 endCursor?: string | null;
462 id?: number;
463 maximumBytesRead?: number;
464 maximumRowsRead?: number;
465 numItems: number;
466 };
467 },
468 {
469 continueCursor: string;
470 isDone: boolean;
471 page: Array<{
472 args: any;
473 context?: any;
474 name?: string;
475 runResult?:
476 | { kind: "success"; returnValue: any }
477 | { error: string; kind: "failed" }
478 | { kind: "canceled" };
479 workflowId: string;
480 }>;
481 pageStatus?: "SplitRecommended" | "SplitRequired" | null;
482 splitCursor?: string | null;
483 }
484 >;
485 listByName: FunctionReference<
486 "query",
487 "internal",
488 {
489 name: string;
490 order: "asc" | "desc";
491 paginationOpts: {
492 cursor: string | null;
493 endCursor?: string | null;
494 id?: number;
495 maximumBytesRead?: number;
496 maximumRowsRead?: number;
497 numItems: number;
498 };
499 },
500 {
501 continueCursor: string;
502 isDone: boolean;
503 page: Array<{
504 args: any;
505 context?: any;
506 name?: string;
507 runResult?:
508 | { kind: "success"; returnValue: any }
509 | { error: string; kind: "failed" }
510 | { kind: "canceled" };
511 workflowId: string;
512 }>;
513 pageStatus?: "SplitRecommended" | "SplitRequired" | null;
514 splitCursor?: string | null;
515 }
516 >;
517 listSteps: FunctionReference<
518 "query",
519 "internal",
520 {
521 order: "asc" | "desc";
522 paginationOpts: {
523 cursor: string | null;
524 endCursor?: string | null;
525 id?: number;
526 maximumBytesRead?: number;
527 maximumRowsRead?: number;
528 numItems: number;
529 };
530 workflowId: string;
531 },
532 {
533 continueCursor: string;
534 isDone: boolean;
535 page: Array<{
536 args: any;
537 completedAt?: number;
538 eventId?: string;
539 kind: "function" | "workflow" | "event";
540 name: string;
541 nestedWorkflowId?: string;
542 runResult?:
543 | { kind: "success"; returnValue: any }
544 | { error: string; kind: "failed" }
545 | { kind: "canceled" };
546 startedAt: number;
547 stepId: string;
548 stepNumber: number;
549 workId?: string;
550 workflowId: string;
551 }>;
552 pageStatus?: "SplitRecommended" | "SplitRequired" | null;
553 splitCursor?: string | null;
554 }
555 >;
556 };
557 };
558};
apps/convex/convex/_generated/api.js+23−0
@@ -0,0 +1,23 @@
1/* eslint-disable */
2/**
3 * Generated `api` utility.
4 *
5 * THIS CODE IS AUTOMATICALLY GENERATED.
6 *
7 * To regenerate, run `npx convex dev`.
8 * @module
9 */
10
11import { anyApi, componentsGeneric } from "convex/server";
12
13/**
14 * A utility for referencing Convex functions in your app's API.
15 *
16 * Usage:
17 * ```js
18 * const myFunctionReference = api.myModule.myFunction;
19 * ```
20 */
21export const api = anyApi;
22export const internal = anyApi;
23export const components = componentsGeneric();
apps/convex/convex/_generated/dataModel.d.ts+60−0
@@ -0,0 +1,60 @@
1/* eslint-disable */
2/**
3 * Generated data model types.
4 *
5 * THIS CODE IS AUTOMATICALLY GENERATED.
6 *
7 * To regenerate, run `npx convex dev`.
8 * @module
9 */
10
11import type {
12 DataModelFromSchemaDefinition,
13 DocumentByName,
14 TableNamesInDataModel,
15 SystemTableNames,
16} from "convex/server";
17import type { GenericId } from "convex/values";
18import schema from "../schema.js";
19
20/**
21 * The names of all of your Convex tables.
22 */
23export type TableNames = TableNamesInDataModel<DataModel>;
24
25/**
26 * The type of a document stored in Convex.
27 *
28 * @typeParam TableName - A string literal type of the table name (like "users").
29 */
30export type Doc<TableName extends TableNames> = DocumentByName<
31 DataModel,
32 TableName
33>;
34
35/**
36 * An identifier for a document in Convex.
37 *
38 * Convex documents are uniquely identified by their `Id`, which is accessible
39 * on the `_id` field. To learn more, see [Document IDs](https://docs.convex.dev/using/document-ids).
40 *
41 * Documents can be loaded using `db.get(tableName, id)` in query and mutation functions.
42 *
43 * IDs are just strings at runtime, but this type can be used to distinguish them from other
44 * strings when type checking.
45 *
46 * @typeParam TableName - A string literal type of the table name (like "users").
47 */
48export type Id<TableName extends TableNames | SystemTableNames> =
49 GenericId<TableName>;
50
51/**
52 * A type describing your Convex data model.
53 *
54 * This type includes information about what tables you have, the type of
55 * documents stored in those tables, and the indexes defined on them.
56 *
57 * This type is used to parameterize methods like `queryGeneric` and
58 * `mutationGeneric` to make them type-safe.
59 */
60export type DataModel = DataModelFromSchemaDefinition<typeof schema>;
apps/convex/convex/_generated/server.d.ts+143−0
@@ -0,0 +1,143 @@
1/* eslint-disable */
2/**
3 * Generated utilities for implementing server-side Convex query and mutation functions.
4 *
5 * THIS CODE IS AUTOMATICALLY GENERATED.
6 *
7 * To regenerate, run `npx convex dev`.
8 * @module
9 */
10
11import {
12 ActionBuilder,
13 HttpActionBuilder,
14 MutationBuilder,
15 QueryBuilder,
16 GenericActionCtx,
17 GenericMutationCtx,
18 GenericQueryCtx,
19 GenericDatabaseReader,
20 GenericDatabaseWriter,
21} from "convex/server";
22import type { DataModel } from "./dataModel.js";
23
24/**
25 * Define a query in this Convex app's public API.
26 *
27 * This function will be allowed to read your Convex database and will be accessible from the client.
28 *
29 * @param func - The query function. It receives a {@link QueryCtx} as its first argument.
30 * @returns The wrapped query. Include this as an `export` to name it and make it accessible.
31 */
32export declare const query: QueryBuilder<DataModel, "public">;
33
34/**
35 * Define a query that is only accessible from other Convex functions (but not from the client).
36 *
37 * This function will be allowed to read from your Convex database. It will not be accessible from the client.
38 *
39 * @param func - The query function. It receives a {@link QueryCtx} as its first argument.
40 * @returns The wrapped query. Include this as an `export` to name it and make it accessible.
41 */
42export declare const internalQuery: QueryBuilder<DataModel, "internal">;
43
44/**
45 * Define a mutation in this Convex app's public API.
46 *
47 * This function will be allowed to modify your Convex database and will be accessible from the client.
48 *
49 * @param func - The mutation function. It receives a {@link MutationCtx} as its first argument.
50 * @returns The wrapped mutation. Include this as an `export` to name it and make it accessible.
51 */
52export declare const mutation: MutationBuilder<DataModel, "public">;
53
54/**
55 * Define a mutation that is only accessible from other Convex functions (but not from the client).
56 *
57 * This function will be allowed to modify your Convex database. It will not be accessible from the client.
58 *
59 * @param func - The mutation function. It receives a {@link MutationCtx} as its first argument.
60 * @returns The wrapped mutation. Include this as an `export` to name it and make it accessible.
61 */
62export declare const internalMutation: MutationBuilder<DataModel, "internal">;
63
64/**
65 * Define an action in this Convex app's public API.
66 *
67 * An action is a function which can execute any JavaScript code, including non-deterministic
68 * code and code with side-effects, like calling third-party services.
69 * They can be run in Convex's JavaScript environment or in Node.js using the "use node" directive.
70 * They can interact with the database indirectly by calling queries and mutations using the {@link ActionCtx}.
71 *
72 * @param func - The action. It receives an {@link ActionCtx} as its first argument.
73 * @returns The wrapped action. Include this as an `export` to name it and make it accessible.
74 */
75export declare const action: ActionBuilder<DataModel, "public">;
76
77/**
78 * Define an action that is only accessible from other Convex functions (but not from the client).
79 *
80 * @param func - The function. It receives an {@link ActionCtx} as its first argument.
81 * @returns The wrapped function. Include this as an `export` to name it and make it accessible.
82 */
83export declare const internalAction: ActionBuilder<DataModel, "internal">;
84
85/**
86 * Define an HTTP action.
87 *
88 * The wrapped function will be used to respond to HTTP requests received
89 * by a Convex deployment if the requests matches the path and method where
90 * this action is routed. Be sure to route your httpAction in `convex/http.js`.
91 *
92 * @param func - The function. It receives an {@link ActionCtx} as its first argument
93 * and a Fetch API `Request` object as its second.
94 * @returns The wrapped function. Import this function from `convex/http.js` and route it to hook it up.
95 */
96export declare const httpAction: HttpActionBuilder;
97
98/**
99 * A set of services for use within Convex query functions.
100 *
101 * The query context is passed as the first argument to any Convex query
102 * function run on the server.
103 *
104 * This differs from the {@link MutationCtx} because all of the services are
105 * read-only.
106 */
107export type QueryCtx = GenericQueryCtx<DataModel>;
108
109/**
110 * A set of services for use within Convex mutation functions.
111 *
112 * The mutation context is passed as the first argument to any Convex mutation
113 * function run on the server.
114 */
115export type MutationCtx = GenericMutationCtx<DataModel>;
116
117/**
118 * A set of services for use within Convex action functions.
119 *
120 * The action context is passed as the first argument to any Convex action
121 * function run on the server.
122 */
123export type ActionCtx = GenericActionCtx<DataModel>;
124
125/**
126 * An interface to read from the database within Convex query functions.
127 *
128 * The two entry points are {@link DatabaseReader.get}, which fetches a single
129 * document by its {@link Id}, or {@link DatabaseReader.query}, which starts
130 * building a query.
131 */
132export type DatabaseReader = GenericDatabaseReader<DataModel>;
133
134/**
135 * An interface to read from and write to the database within Convex mutation
136 * functions.
137 *
138 * Convex guarantees that all writes within a single mutation are
139 * executed atomically, so you never have to worry about partial writes leaving
140 * your data in an inconsistent state. See [the Convex Guide](https://docs.convex.dev/understanding/convex-fundamentals/functions#atomicity-and-optimistic-concurrency-control)
141 * for the guarantees Convex provides your functions.
142 */
143export type DatabaseWriter = GenericDatabaseWriter<DataModel>;
apps/convex/convex/_generated/server.js+93−0
@@ -0,0 +1,93 @@
1/* eslint-disable */
2/**
3 * Generated utilities for implementing server-side Convex query and mutation functions.
4 *
5 * THIS CODE IS AUTOMATICALLY GENERATED.
6 *
7 * To regenerate, run `npx convex dev`.
8 * @module
9 */
10
11import {
12 actionGeneric,
13 httpActionGeneric,
14 queryGeneric,
15 mutationGeneric,
16 internalActionGeneric,
17 internalMutationGeneric,
18 internalQueryGeneric,
19} from "convex/server";
20
21/**
22 * Define a query in this Convex app's public API.
23 *
24 * This function will be allowed to read your Convex database and will be accessible from the client.
25 *
26 * @param func - The query function. It receives a {@link QueryCtx} as its first argument.
27 * @returns The wrapped query. Include this as an `export` to name it and make it accessible.
28 */
29export const query = queryGeneric;
30
31/**
32 * Define a query that is only accessible from other Convex functions (but not from the client).
33 *
34 * This function will be allowed to read from your Convex database. It will not be accessible from the client.
35 *
36 * @param func - The query function. It receives a {@link QueryCtx} as its first argument.
37 * @returns The wrapped query. Include this as an `export` to name it and make it accessible.
38 */
39export const internalQuery = internalQueryGeneric;
40
41/**
42 * Define a mutation in this Convex app's public API.
43 *
44 * This function will be allowed to modify your Convex database and will be accessible from the client.
45 *
46 * @param func - The mutation function. It receives a {@link MutationCtx} as its first argument.
47 * @returns The wrapped mutation. Include this as an `export` to name it and make it accessible.
48 */
49export const mutation = mutationGeneric;
50
51/**
52 * Define a mutation that is only accessible from other Convex functions (but not from the client).
53 *
54 * This function will be allowed to modify your Convex database. It will not be accessible from the client.
55 *
56 * @param func - The mutation function. It receives a {@link MutationCtx} as its first argument.
57 * @returns The wrapped mutation. Include this as an `export` to name it and make it accessible.
58 */
59export const internalMutation = internalMutationGeneric;
60
61/**
62 * Define an action in this Convex app's public API.
63 *
64 * An action is a function which can execute any JavaScript code, including non-deterministic
65 * code and code with side-effects, like calling third-party services.
66 * They can be run in Convex's JavaScript environment or in Node.js using the "use node" directive.
67 * They can interact with the database indirectly by calling queries and mutations using the {@link ActionCtx}.
68 *
69 * @param func - The action. It receives an {@link ActionCtx} as its first argument.
70 * @returns The wrapped action. Include this as an `export` to name it and make it accessible.
71 */
72export const action = actionGeneric;
73
74/**
75 * Define an action that is only accessible from other Convex functions (but not from the client).
76 *
77 * @param func - The function. It receives an {@link ActionCtx} as its first argument.
78 * @returns The wrapped function. Include this as an `export` to name it and make it accessible.
79 */
80export const internalAction = internalActionGeneric;
81
82/**
83 * Define an HTTP action.
84 *
85 * The wrapped function will be used to respond to HTTP requests received
86 * by a Convex deployment if the requests matches the path and method where
87 * this action is routed. Be sure to route your httpAction in `convex/http.js`.
88 *
89 * @param func - The function. It receives an {@link ActionCtx} as its first argument
90 * and a Fetch API `Request` object as its second.
91 * @returns The wrapped function. Import this function from `convex/http.js` and route it to hook it up.
92 */
93export const httpAction = httpActionGeneric;
apps/convex/convex/controlPlane.ts+72−0
@@ -0,0 +1,72 @@
1import {
2 listApprovals as listApprovalsImpl,
3 resolveApproval as resolveApprovalImpl,
4} from "./control_plane/approvals";
5import {
6 listCredentialBindings as listCredentialBindingsImpl,
7 removeCredentialBinding as removeCredentialBindingImpl,
8 upsertCredentialBinding as upsertCredentialBindingImpl,
9} from "./control_plane/credentials";
10import { controlPlaneHttpHandler as controlPlaneHttpHandlerImpl } from "./control_plane/http";
11import {
12 listOrganizations as listOrganizationsImpl,
13 upsertOrganization as upsertOrganizationImpl,
14} from "./control_plane/organizations";
15import {
16 listPolicies as listPoliciesImpl,
17 removePolicy as removePolicyImpl,
18 upsertPolicy as upsertPolicyImpl,
19} from "./control_plane/policies";
20import {
21 listSources as listSourcesImpl,
22 removeSource as removeSourceImpl,
23 upsertSource as upsertSourceImpl,
24} from "./control_plane/sources";
25import {
26 closeStorageInstance as closeStorageInstanceImpl,
27 listStorageDirectory as listStorageDirectoryImpl,
28 listStorageInstances as listStorageInstancesImpl,
29 listStorageKv as listStorageKvImpl,
30 openStorageInstance as openStorageInstanceImpl,
31 queryStorageSql as queryStorageSqlImpl,
32 readStorageFile as readStorageFileImpl,
33 removeStorageInstance as removeStorageInstanceImpl,
34} from "./control_plane/storage";
35import {
36 getToolDetail as getToolDetailImpl,
37 listSourceTools as listSourceToolsImpl,
38 listWorkspaceTools as listWorkspaceToolsImpl,
39} from "./control_plane/tools";
40import {
41 listWorkspaces as listWorkspacesImpl,
42 upsertWorkspace as upsertWorkspaceImpl,
43} from "./control_plane/workspaces";
44
45export const listSources = listSourcesImpl;
46export const upsertSource = upsertSourceImpl;
47export const removeSource = removeSourceImpl;
48export const listCredentialBindings = listCredentialBindingsImpl;
49export const upsertCredentialBinding = upsertCredentialBindingImpl;
50export const removeCredentialBinding = removeCredentialBindingImpl;
51export const listPolicies = listPoliciesImpl;
52export const upsertPolicy = upsertPolicyImpl;
53export const removePolicy = removePolicyImpl;
54export const listOrganizations = listOrganizationsImpl;
55export const upsertOrganization = upsertOrganizationImpl;
56export const listWorkspaces = listWorkspacesImpl;
57export const upsertWorkspace = upsertWorkspaceImpl;
58export const listWorkspaceTools = listWorkspaceToolsImpl;
59export const listSourceTools = listSourceToolsImpl;
60export const getToolDetail = getToolDetailImpl;
61export const listStorageInstances = listStorageInstancesImpl;
62export const openStorageInstance = openStorageInstanceImpl;
63export const closeStorageInstance = closeStorageInstanceImpl;
64export const removeStorageInstance = removeStorageInstanceImpl;
65export const listStorageDirectory = listStorageDirectoryImpl;
66export const readStorageFile = readStorageFileImpl;
67export const listStorageKv = listStorageKvImpl;
68export const queryStorageSql = queryStorageSqlImpl;
69export const listApprovals = listApprovalsImpl;
70export const resolveApproval = resolveApprovalImpl;
71
72export const controlPlaneHttpHandler = controlPlaneHttpHandlerImpl;
apps/convex/convex/control_plane/actor.ts+307−0
@@ -0,0 +1,307 @@
1import {
2 ControlPlaneActorResolverLive,
3 deriveWorkspaceMembershipsForPrincipal,
4 requirePrincipalFromHeaders,
5} from "@executor-v2/management-api";
6import { ActorUnauthenticatedError, makeActor } from "@executor-v2/domain";
7import {
8 OrganizationMembershipSchema,
9 WorkspaceSchema,
10 type OrganizationMembership,
11 type Workspace,
12} from "@executor-v2/schema";
13import { v } from "convex/values";
14import * as Effect from "effect/Effect";
15import * as Schema from "effect/Schema";
16
17import { internal } from "../_generated/api";
18import {
19 internalMutation,
20 internalQuery,
21 type ActionCtx,
22} from "../_generated/server";
23
24const decodeWorkspace = Schema.decodeUnknownSync(WorkspaceSchema);
25const decodeOrganizationMembership = Schema.decodeUnknownSync(
26 OrganizationMembershipSchema,
27);
28
29const stripConvexSystemFields = (
30 value: Record<string, unknown>,
31): Record<string, unknown> => {
32 const { _id: _ignoredId, _creationTime: _ignoredCreationTime, ...rest } = value;
33 return rest;
34};
35
36const toOrganizationSlug = (accountId: string): string => {
37 const slug = accountId
38 .trim()
39 .toLowerCase()
40 .replace(/[^a-z0-9]+/g, "-")
41 .replace(/^-+/, "")
42 .replace(/-+$/, "");
43
44 return slug.length > 0 ? `acct-${slug}` : `acct-${crypto.randomUUID().slice(0, 8)}`;
45};
46
47export const getWorkspaceForActor = internalQuery({
48 args: {
49 workspaceId: v.string(),
50 },
51 handler: async (ctx, args): Promise<Workspace | null> => {
52 const row = await ctx.db
53 .query("workspaces")
54 .withIndex("by_domainId", (q) => q.eq("id", args.workspaceId))
55 .first();
56
57 if (row === null) {
58 return null;
59 }
60
61 return decodeWorkspace(
62 stripConvexSystemFields(row as unknown as Record<string, unknown>),
63 );
64 },
65});
66
67export const listOrganizationMembershipsForActor = internalQuery({
68 args: {
69 accountId: v.string(),
70 },
71 handler: async (ctx, args): Promise<ReadonlyArray<OrganizationMembership>> => {
72 const rows = await ctx.db
73 .query("organizationMemberships")
74 .withIndex("by_accountId", (q) => q.eq("accountId", args.accountId))
75 .collect();
76
77 return rows.map((row) =>
78 decodeOrganizationMembership(
79 stripConvexSystemFields(row as unknown as Record<string, unknown>),
80 ),
81 );
82 },
83});
84
85export const listWorkspacesForActor = internalQuery({
86 args: {
87 accountId: v.string(),
88 organizationIds: v.array(v.string()),
89 },
90 handler: async (ctx, args): Promise<ReadonlyArray<Workspace>> => {
91 const ownRows = await ctx.db
92 .query("workspaces")
93 .withIndex("by_createdByAccountId", (q) => q.eq("createdByAccountId", args.accountId))
94 .collect();
95
96 const organizationRows = await Promise.all(
97 args.organizationIds.map((organizationId) =>
98 ctx.db
99 .query("workspaces")
100 .withIndex("by_organizationId", (q) => q.eq("organizationId", organizationId))
101 .collect(),
102 ),
103 );
104
105 const workspaces = [...ownRows, ...organizationRows.flat()].map((row) =>
106 decodeWorkspace(stripConvexSystemFields(row as unknown as Record<string, unknown>)),
107 );
108
109 return Array.from(new Map(workspaces.map((workspace) => [workspace.id, workspace])).values());
110 },
111});
112
113export const ensureWorkspaceForActor = internalMutation({
114 args: {
115 workspaceId: v.string(),
116 accountId: v.string(),
117 },
118 handler: async (ctx, args): Promise<Workspace> => {
119 const now = Date.now();
120
121 const ensureOrganizationMembership = async (organizationId: string) => {
122 const existingOrganization = await ctx.db
123 .query("organizations")
124 .withIndex("by_domainId", (q) => q.eq("id", organizationId))
125 .first();
126
127 if (existingOrganization === null) {
128 await ctx.db.insert("organizations", {
129 id: organizationId,
130 slug: toOrganizationSlug(args.accountId),
131 name: `${args.accountId} Organization`,
132 status: "active",
133 createdByAccountId: args.accountId,
134 createdAt: now,
135 updatedAt: now,
136 });
137 }
138
139 const existingMembership = await ctx.db
140 .query("organizationMemberships")
141 .withIndex("by_organizationId_accountId", (q) =>
142 q.eq("organizationId", organizationId).eq("accountId", args.accountId)
143 )
144 .first();
145
146 if (existingMembership !== null) {
147 return;
148 }
149
150 await ctx.db.insert("organizationMemberships", {
151 id: `org_member_${crypto.randomUUID()}`,
152 organizationId,
153 accountId: args.accountId,
154 role: "owner",
155 status: "active",
156 billable: false,
157 invitedByAccountId: null,
158 joinedAt: now,
159 createdAt: now,
160 updatedAt: now,
161 });
162 };
163
164 const existing = await ctx.db
165 .query("workspaces")
166 .withIndex("by_domainId", (q) => q.eq("id", args.workspaceId))
167 .first();
168
169 if (existing !== null) {
170 const existingWorkspace = decodeWorkspace(
171 stripConvexSystemFields(existing as unknown as Record<string, unknown>),
172 );
173
174 await ensureOrganizationMembership(existingWorkspace.organizationId);
175
176 if (existingWorkspace.createdByAccountId !== null) {
177 return existingWorkspace;
178 }
179
180 await ctx.db.patch(existing._id, {
181 createdByAccountId: args.accountId,
182 updatedAt: now,
183 });
184
185 return decodeWorkspace({
186 ...existingWorkspace,
187 createdByAccountId: args.accountId,
188 updatedAt: now,
189 });
190 }
191
192 const organizationId = `org_${args.accountId}`;
193 await ensureOrganizationMembership(organizationId);
194
195 await ctx.db.insert("workspaces", {
196 id: args.workspaceId,
197 organizationId,
198 name: args.workspaceId,
199 createdByAccountId: args.accountId,
200 createdAt: now,
201 updatedAt: now,
202 });
203
204 return decodeWorkspace({
205 id: args.workspaceId,
206 organizationId,
207 name: args.workspaceId,
208 createdByAccountId: args.accountId,
209 createdAt: now,
210 updatedAt: now,
211 });
212 },
213});
214
215const runQueryEffect = <A>(
216 operation: string,
217 run: () => Promise<A>,
218): Effect.Effect<A, ActorUnauthenticatedError> =>
219 Effect.tryPromise({
220 try: run,
221 catch: (cause) =>
222 new ActorUnauthenticatedError({
223 message: `Failed resolving actor (${operation}): ${String(cause)}`,
224 }),
225 });
226
227export const ConvexControlPlaneActorLive = (ctx: ActionCtx) =>
228 ControlPlaneActorResolverLive({
229 resolveActor: (input) =>
230 Effect.gen(function* () {
231 const principal = yield* requirePrincipalFromHeaders(input.headers);
232
233 const organizationMemberships = yield* runQueryEffect(
234 "organizationMembership.list",
235 () =>
236 ctx.runQuery(internal.control_plane.actor.listOrganizationMembershipsForActor, {
237 accountId: principal.accountId,
238 }),
239 );
240
241 const organizationIds = organizationMemberships.map(
242 (membership) => membership.organizationId,
243 );
244
245 const workspaces = yield* runQueryEffect("workspace.list", () =>
246 ctx.runQuery(internal.control_plane.actor.listWorkspacesForActor, {
247 accountId: principal.accountId,
248 organizationIds,
249 }),
250 );
251
252 const workspaceMemberships = workspaces.flatMap((workspace) =>
253 deriveWorkspaceMembershipsForPrincipal({
254 principalAccountId: principal.accountId,
255 workspaceId: workspace.id,
256 workspace,
257 organizationMemberships,
258 }),
259 );
260
261 return yield* makeActor({
262 principal,
263 workspaceMemberships,
264 organizationMemberships,
265 });
266 }),
267 resolveWorkspaceActor: (input) =>
268 Effect.gen(function* () {
269 const principal = yield* requirePrincipalFromHeaders(input.headers);
270
271 let workspace = yield* runQueryEffect("workspace.read", () =>
272 ctx.runQuery(internal.control_plane.actor.getWorkspaceForActor, {
273 workspaceId: input.workspaceId,
274 }),
275 );
276
277 if (workspace === null || workspace.createdByAccountId === null) {
278 workspace = yield* runQueryEffect("workspace.ensure", () =>
279 ctx.runMutation(internal.control_plane.actor.ensureWorkspaceForActor, {
280 workspaceId: input.workspaceId,
281 accountId: principal.accountId,
282 }),
283 );
284 }
285
286 const organizationMemberships = yield* runQueryEffect(
287 "organizationMembership.list",
288 () =>
289 ctx.runQuery(internal.control_plane.actor.listOrganizationMembershipsForActor, {
290 accountId: principal.accountId,
291 }),
292 );
293
294 const workspaceMemberships = deriveWorkspaceMembershipsForPrincipal({
295 principalAccountId: principal.accountId,
296 workspaceId: input.workspaceId,
297 workspace,
298 organizationMemberships,
299 });
300
301 return yield* makeActor({
302 principal,
303 workspaceMemberships,
304 organizationMemberships,
305 });
306 }),
307 });
apps/convex/convex/control_plane/approvals.ts+95−0
@@ -0,0 +1,95 @@
1import {
2 type ResolveApprovalPayload,
3} from "@executor-v2/management-api";
4import {
5 ApprovalSchema,
6 type Approval,
7} from "@executor-v2/schema";
8import { v } from "convex/values";
9import * as Schema from "effect/Schema";
10
11import { mutation, query } from "../_generated/server";
12
13const decodeApproval = Schema.decodeUnknownSync(ApprovalSchema);
14
15const stripConvexSystemFields = (
16 value: Record<string, unknown>,
17): Record<string, unknown> => {
18 const { _id: _ignoredId, _creationTime: _ignoredCreationTime, ...rest } = value;
19 return rest;
20};
21
22const approvalStatusValidator = v.union(
23 v.literal("approved"),
24 v.literal("denied"),
25);
26
27const sortApprovals = (approvals: ReadonlyArray<Approval>): Array<Approval> =>
28 [...approvals].sort((left, right) => right.requestedAt - left.requestedAt);
29
30export const listApprovals = query({
31 args: {
32 workspaceId: v.string(),
33 },
34 handler: async (ctx, args): Promise<Array<Approval>> => {
35 const rows = await ctx.db
36 .query("approvals")
37 .withIndex("by_workspaceId", (q) => q.eq("workspaceId", args.workspaceId))
38 .collect();
39
40 return sortApprovals(
41 rows.map((row) =>
42 decodeApproval(
43 stripConvexSystemFields(row as unknown as Record<string, unknown>),
44 ),
45 ),
46 );
47 },
48});
49
50export const resolveApproval = mutation({
51 args: {
52 workspaceId: v.string(),
53 approvalId: v.string(),
54 payload: v.object({
55 status: approvalStatusValidator,
56 reason: v.optional(v.union(v.string(), v.null())),
57 }),
58 },
59 handler: async (ctx, args): Promise<Approval> => {
60 const row = await ctx.db
61 .query("approvals")
62 .withIndex("by_domainId", (q) => q.eq("id", args.approvalId))
63 .unique();
64
65 if (!row || row.workspaceId !== args.workspaceId) {
66 throw new Error(`Approval not found: ${args.approvalId}`);
67 }
68
69 const approval = decodeApproval(
70 stripConvexSystemFields(row as unknown as Record<string, unknown>),
71 );
72
73 if (approval.status !== "pending") {
74 throw new Error(`Approval is not pending: ${args.approvalId}`);
75 }
76
77 const payload = args.payload as ResolveApprovalPayload;
78 const updatedAt = Date.now();
79
80 const resolvedApproval: Approval = {
81 ...approval,
82 status: payload.status,
83 reason: payload.reason ?? approval.reason ?? null,
84 resolvedAt: updatedAt,
85 };
86
87 await ctx.db.patch(row._id, {
88 status: resolvedApproval.status,
89 reason: resolvedApproval.reason,
90 resolvedAt: resolvedApproval.resolvedAt,
91 });
92
93 return resolvedApproval;
94 },
95});
apps/convex/convex/control_plane/credentials.ts+564−0
@@ -0,0 +1,564 @@
1import {
2 buildCredentialHeaders,
3 selectOAuthAccessToken,
4} from "@executor-v2/engine";
5import { type UpsertCredentialBindingPayload } from "@executor-v2/management-api";
6import {
7 OAuthTokenSchema,
8 SourceCredentialBindingSchema,
9 type OAuthToken,
10 type SourceCredentialBinding,
11} from "@executor-v2/schema";
12import { v } from "convex/values";
13import * as Schema from "effect/Schema";
14
15import { internal } from "../_generated/api";
16import { decryptSecretValue, encryptSecretValue } from "../credential_crypto";
17import {
18 action,
19 internalAction,
20 internalMutation,
21 internalQuery,
22 mutation,
23 query,
24 type MutationCtx,
25 type QueryCtx,
26} from "../_generated/server";
27
28const runtimeInternal = internal as any;
29
30const decodeSourceCredentialBinding = Schema.decodeUnknownSync(
31 SourceCredentialBindingSchema,
32);
33const decodeOAuthToken = Schema.decodeUnknownSync(OAuthTokenSchema);
34
35const stripConvexSystemFields = (
36 value: Record<string, unknown>,
37): Record<string, unknown> => {
38 const { _id: _ignoredId, _creationTime: _ignoredCreationTime, ...rest } = value;
39 return rest;
40};
41
42const toSourceCredentialBinding = (
43 document: Record<string, unknown>,
44): SourceCredentialBinding =>
45 decodeSourceCredentialBinding(stripConvexSystemFields(document));
46
47const credentialProviderValidator = v.union(
48 v.literal("api_key"),
49 v.literal("bearer"),
50 v.literal("oauth2"),
51 v.literal("custom"),
52);
53
54const credentialSecretProviderValidator = v.literal("local");
55
56const credentialScopeTypeValidator = v.union(
57 v.literal("workspace"),
58 v.literal("organization"),
59 v.literal("account"),
60);
61
62const sourceCredentialBindingPayloadValidator = v.object({
63 id: v.optional(v.string()),
64 credentialId: v.string(),
65 scopeType: credentialScopeTypeValidator,
66 sourceKey: v.string(),
67 provider: credentialProviderValidator,
68 secretProvider: v.optional(credentialSecretProviderValidator),
69 secretRef: v.string(),
70 accountId: v.optional(v.union(v.string(), v.null())),
71 additionalHeadersJson: v.optional(v.union(v.string(), v.null())),
72 boundAuthFingerprint: v.optional(v.union(v.string(), v.null())),
73});
74
75const sortSourceCredentialBindings = (
76 bindings: ReadonlyArray<SourceCredentialBinding>,
77): Array<SourceCredentialBinding> =>
78 [...bindings].sort((left, right) => {
79 const leftKey = `${left.sourceKey}:${left.provider}`.toLowerCase();
80 const rightKey = `${right.sourceKey}:${right.provider}`.toLowerCase();
81
82 if (leftKey === rightKey) {
83 return left.id.localeCompare(right.id);
84 }
85
86 return leftKey.localeCompare(rightKey);
87 });
88
89const resolveWorkspaceOrganizationId = async (
90 ctx: QueryCtx | MutationCtx,
91 workspaceId: string,
92): Promise<string> => {
93 const workspace = await ctx.db
94 .query("workspaces")
95 .withIndex("by_domainId", (q) => q.eq("id", workspaceId))
96 .unique();
97
98 if (!workspace) {
99 throw new Error(`Workspace not found: ${workspaceId}`);
100 }
101
102 return workspace.organizationId;
103};
104
105const canAccessSourceCredentialBinding = (
106 binding: SourceCredentialBinding,
107 input: {
108 workspaceId: string;
109 organizationId: string;
110 },
111): boolean =>
112 binding.workspaceId === input.workspaceId
113 || (binding.workspaceId === null && binding.organizationId === input.organizationId);
114
115const toOAuthToken = (document: Record<string, unknown>): OAuthToken =>
116 decodeOAuthToken(stripConvexSystemFields(document));
117
118const sourceSlug = (value: string): string =>
119 value
120 .toLowerCase()
121 .replaceAll(/[^a-z0-9]+/g, "_")
122 .replaceAll(/^_+|_+$/g, "");
123
124const parseHostname = (endpoint: string): string | null => {
125 try {
126 const hostname = new URL(endpoint).hostname.trim().toLowerCase();
127 return hostname.length > 0 ? hostname : null;
128 } catch {
129 return null;
130 }
131};
132
133const sourceKeyCandidatesForIngest = (input: {
134 sourceId: string;
135 sourceName: string;
136 sourceEndpoint: string;
137}): Array<string> => {
138 const values = new Set<string>();
139
140 const addCandidate = (value: string | null): void => {
141 if (!value) {
142 return;
143 }
144
145 const trimmed = value.trim();
146 if (trimmed.length > 0) {
147 values.add(trimmed);
148 }
149 };
150
151 addCandidate(`source:${input.sourceId}`);
152 addCandidate(input.sourceId);
153 addCandidate(input.sourceName.toLowerCase());
154 addCandidate(sourceSlug(input.sourceName));
155
156 const hostname = parseHostname(input.sourceEndpoint);
157 addCandidate(hostname);
158 if (hostname) {
159 const hostnameWithoutApi = hostname.replace(/^api\./, "");
160 addCandidate(hostnameWithoutApi);
161 const firstLabel = hostnameWithoutApi.split(".")[0] ?? null;
162 addCandidate(firstLabel);
163 }
164
165 return [...values];
166};
167
168const bindingScopeScore = (
169 binding: SourceCredentialBinding,
170 input: {
171 workspaceId: string;
172 organizationId: string;
173 },
174): number => {
175 if (binding.scopeType === "workspace") {
176 return binding.workspaceId === input.workspaceId ? 20 : -1;
177 }
178
179 if (binding.scopeType === "organization") {
180 return binding.organizationId === input.organizationId ? 10 : -1;
181 }
182
183 return -1;
184};
185
186const selectBestIngestBinding = (
187 candidates: ReadonlyArray<{
188 binding: SourceCredentialBinding;
189 sourceKeyRank: number;
190 }>,
191 input: {
192 workspaceId: string;
193 organizationId: string;
194 },
195): SourceCredentialBinding | null => {
196 const ranked = candidates
197 .map((candidate) => ({
198 binding: candidate.binding,
199 scopeScore: bindingScopeScore(candidate.binding, input),
200 sourceKeyRank: candidate.sourceKeyRank,
201 }))
202 .filter((candidate) => candidate.scopeScore >= 0)
203 .sort((left, right) => {
204 if (left.scopeScore !== right.scopeScore) {
205 return right.scopeScore - left.scopeScore;
206 }
207
208 if (left.sourceKeyRank !== right.sourceKeyRank) {
209 return right.sourceKeyRank - left.sourceKeyRank;
210 }
211
212 if (left.binding.updatedAt !== right.binding.updatedAt) {
213 return right.binding.updatedAt - left.binding.updatedAt;
214 }
215
216 return right.binding.createdAt - left.binding.createdAt;
217 });
218
219 return ranked[0]?.binding ?? null;
220};
221
222const requireLocalSecretProvider = (
223 secretProvider: SourceCredentialBinding["secretProvider"],
224): "local" => {
225 if (secretProvider !== "local") {
226 throw new Error("Convex credentials require secretProvider 'local'");
227 }
228
229 return "local";
230};
231
232const defaultSecretProvider = (): "local" => "local";
233
234const resolveSecretRefForHeaders = async (
235 binding: SourceCredentialBinding,
236): Promise<string> => {
237 requireLocalSecretProvider(binding.secretProvider);
238 return await decryptSecretValue(binding.secretRef);
239};
240
241const resolveIngestSelection = async (
242 ctx: QueryCtx,
243 args: {
244 workspaceId: string;
245 sourceId: string;
246 sourceName: string;
247 sourceEndpoint: string;
248 },
249): Promise<{
250 binding: SourceCredentialBinding | null;
251 oauthAccessToken: string | null;
252}> => {
253 const organizationId = await resolveWorkspaceOrganizationId(ctx, args.workspaceId);
254 const sourceKeys = sourceKeyCandidatesForIngest({
255 sourceId: args.sourceId,
256 sourceName: args.sourceName,
257 sourceEndpoint: args.sourceEndpoint,
258 });
259
260 const candidateRows = await Promise.all(
261 sourceKeys.map((sourceKey) =>
262 ctx.db
263 .query("sourceCredentialBindings")
264 .withIndex("by_sourceKey", (q) => q.eq("sourceKey", sourceKey))
265 .collect()
266 .then((rows) =>
267 rows.map((row) => ({
268 binding: toSourceCredentialBinding(row as unknown as Record<string, unknown>),
269 sourceKey,
270 })),
271 ),
272 ),
273 );
274
275 const flattened = candidateRows.flat();
276 const dedupedById = new Map<string, { binding: SourceCredentialBinding; sourceKey: string }>();
277 for (const candidate of flattened) {
278 if (!dedupedById.has(candidate.binding.id)) {
279 dedupedById.set(candidate.binding.id, candidate);
280 }
281 }
282
283 const sourceKeyRankByKey = new Map<string, number>();
284 sourceKeys.forEach((sourceKey, index) => {
285 sourceKeyRankByKey.set(sourceKey, sourceKeys.length - index);
286 });
287
288 const binding = selectBestIngestBinding(
289 [...dedupedById.values()].map((candidate) => ({
290 binding: candidate.binding,
291 sourceKeyRank: sourceKeyRankByKey.get(candidate.sourceKey) ?? 0,
292 })),
293 {
294 workspaceId: args.workspaceId,
295 organizationId,
296 },
297 );
298
299 if (!binding || !canAccessSourceCredentialBinding(binding, { workspaceId: args.workspaceId, organizationId })) {
300 return {
301 binding: null,
302 oauthAccessToken: null,
303 };
304 }
305
306 const oauthTokens = binding.provider === "oauth2"
307 ? (await ctx.db
308 .query("oauthTokens")
309 .withIndex("by_sourceId", (q) => q.eq("sourceId", args.sourceId))
310 .collect()).map((row) => toOAuthToken(row as unknown as Record<string, unknown>))
311 : [];
312
313 const oauthAccessToken = binding.provider === "oauth2"
314 ? selectOAuthAccessToken(oauthTokens, {
315 workspaceId: args.workspaceId,
316 organizationId,
317 accountId: null,
318 sourceKey: binding.sourceKey,
319 }, args.sourceId)
320 : null;
321
322 return {
323 binding,
324 oauthAccessToken,
325 };
326};
327
328const withDecryptedSecret = async (
329 binding: SourceCredentialBinding,
330): Promise<SourceCredentialBinding> => {
331 const secretRef = await resolveSecretRefForHeaders(binding);
332 return {
333 ...binding,
334 secretProvider: "local",
335 secretRef,
336 };
337};
338
339export const resolveSourceCredentialSelectionForIngest = internalQuery({
340 args: {
341 workspaceId: v.string(),
342 sourceId: v.string(),
343 sourceName: v.string(),
344 sourceEndpoint: v.string(),
345 },
346 handler: async (ctx, args) => resolveIngestSelection(ctx, args),
347});
348
349export const resolveSourceCredentialHeadersForIngest = internalAction({
350 args: {
351 workspaceId: v.string(),
352 sourceId: v.string(),
353 sourceName: v.string(),
354 sourceEndpoint: v.string(),
355 },
356 handler: async (ctx, args): Promise<{
357 headers: Record<string, string>;
358 }> => {
359 const selected = await ctx.runQuery(
360 runtimeInternal.control_plane.credentials.resolveSourceCredentialSelectionForIngest,
361 args,
362 ) as {
363 binding: SourceCredentialBinding | null;
364 oauthAccessToken: string | null;
365 };
366
367 if (!selected.binding) {
368 return {
369 headers: {},
370 };
371 }
372
373 const decrypted = await withDecryptedSecret(selected.binding);
374
375 const headers = buildCredentialHeaders(decrypted, {
376 oauthAccessToken: selected.oauthAccessToken,
377 });
378
379 return { headers };
380 },
381});
382
383export const listCredentialBindings = query({
384 args: {
385 workspaceId: v.string(),
386 },
387 handler: async (ctx, args): Promise<Array<SourceCredentialBinding>> => {
388 const organizationId = await resolveWorkspaceOrganizationId(ctx, args.workspaceId);
389
390 const workspaceRows = await ctx.db
391 .query("sourceCredentialBindings")
392 .withIndex("by_workspaceId", (q) => q.eq("workspaceId", args.workspaceId))
393 .collect();
394
395 const organizationRows = await ctx.db
396 .query("sourceCredentialBindings")
397 .withIndex("by_organizationId", (q) => q.eq("organizationId", organizationId))
398 .collect();
399
400 const bindings = [...workspaceRows, ...organizationRows]
401 .map((row) =>
402 toSourceCredentialBinding(row as unknown as Record<string, unknown>),
403 )
404 .filter((binding) =>
405 canAccessSourceCredentialBinding(binding, {
406 workspaceId: args.workspaceId,
407 organizationId,
408 })
409 );
410
411 const uniqueBindings = Array.from(
412 new Map(bindings.map((binding) => [binding.id, binding])).values(),
413 );
414
415 const decryptedBindings = await Promise.all(
416 uniqueBindings.map((binding) => withDecryptedSecret(binding)),
417 );
418
419 return sortSourceCredentialBindings(decryptedBindings);
420 },
421});
422
423export const upsertCredentialBindingRecord = internalMutation({
424 args: {
425 workspaceId: v.string(),
426 payload: sourceCredentialBindingPayloadValidator,
427 },
428 handler: async (ctx, args): Promise<SourceCredentialBinding> => {
429 const payload = args.payload as UpsertCredentialBindingPayload;
430
431 if (payload.scopeType === "account" && payload.accountId === null) {
432 throw new Error("Account scope credentials require accountId");
433 }
434
435 const organizationId = await resolveWorkspaceOrganizationId(ctx, args.workspaceId);
436 const now = Date.now();
437 const bindingId = payload.id ?? `credential_binding_${crypto.randomUUID()}`;
438
439 const existing = await ctx.db
440 .query("sourceCredentialBindings")
441 .withIndex("by_domainId", (q) => q.eq("id", bindingId))
442 .unique();
443
444 const existingBinding = existing
445 ? toSourceCredentialBinding(existing as unknown as Record<string, unknown>)
446 : null;
447
448 if (
449 existingBinding !== null
450 && !canAccessSourceCredentialBinding(existingBinding, {
451 workspaceId: args.workspaceId,
452 organizationId,
453 })
454 ) {
455 throw new Error(`Credential binding not found: ${bindingId}`);
456 }
457
458 const secretProvider = requireLocalSecretProvider(
459 payload.secretProvider
460 ?? existingBinding?.secretProvider
461 ?? defaultSecretProvider(),
462 );
463
464 const nextBinding = decodeSourceCredentialBinding({
465 id: bindingId,
466 credentialId: payload.credentialId,
467 organizationId,
468 workspaceId: payload.scopeType === "workspace" ? args.workspaceId : null,
469 accountId: payload.scopeType === "account" ? (payload.accountId ?? null) : null,
470 scopeType: payload.scopeType,
471 sourceKey: payload.sourceKey,
472 provider: payload.provider,
473 secretProvider,
474 secretRef: payload.secretRef,
475 additionalHeadersJson: payload.additionalHeadersJson ?? null,
476 boundAuthFingerprint: payload.boundAuthFingerprint ?? null,
477 createdAt: existingBinding?.createdAt ?? now,
478 updatedAt: now,
479 });
480
481 if (existing) {
482 await ctx.db.patch(existing._id, nextBinding);
483 } else {
484 await ctx.db.insert("sourceCredentialBindings", nextBinding);
485 }
486
487 return nextBinding;
488 },
489});
490
491export const upsertCredentialBinding = action({
492 args: {
493 workspaceId: v.string(),
494 payload: sourceCredentialBindingPayloadValidator,
495 },
496 handler: async (ctx, args): Promise<SourceCredentialBinding> => {
497 const payload = args.payload as UpsertCredentialBindingPayload;
498 const requestedSecretRef = payload.secretRef.trim();
499 if (requestedSecretRef.length === 0) {
500 throw new Error("Credential secret is required");
501 }
502
503 const encryptedSecretRef = await encryptSecretValue(requestedSecretRef);
504
505 const written = await ctx.runMutation(
506 runtimeInternal.control_plane.credentials.upsertCredentialBindingRecord,
507 {
508 workspaceId: args.workspaceId,
509 payload: {
510 ...payload,
511 secretProvider: "local",
512 secretRef: encryptedSecretRef,
513 },
514 },
515 ) as SourceCredentialBinding;
516
517 return {
518 ...written,
519 secretProvider: "local",
520 secretRef: requestedSecretRef,
521 };
522 },
523});
524
525export const removeCredentialBinding = mutation({
526 args: {
527 workspaceId: v.string(),
528 credentialBindingId: v.string(),
529 },
530 handler: async (
531 ctx,
532 args,
533 ): Promise<{
534 removed: boolean;
535 }> => {
536 const organizationId = await resolveWorkspaceOrganizationId(ctx, args.workspaceId);
537
538 const existing = await ctx.db
539 .query("sourceCredentialBindings")
540 .withIndex("by_domainId", (q) => q.eq("id", args.credentialBindingId))
541 .unique();
542
543 if (!existing) {
544 return { removed: false };
545 }
546
547 const existingBinding = toSourceCredentialBinding(
548 existing as unknown as Record<string, unknown>,
549 );
550
551 if (
552 !canAccessSourceCredentialBinding(existingBinding, {
553 workspaceId: args.workspaceId,
554 organizationId,
555 })
556 ) {
557 return { removed: false };
558 }
559
560 await ctx.db.delete(existing._id);
561
562 return { removed: true };
563 },
564});
apps/convex/convex/control_plane/errors.ts+82−0
@@ -0,0 +1,82 @@
1import { SourceStoreError } from "@executor-v2/persistence-ports";
2
3type ControlPlaneErrorCode =
4 | "bad_request"
5 | "unauthorized"
6 | "forbidden"
7 | "not_found"
8 | "method_not_allowed"
9 | "internal";
10
11type ControlPlaneErrorResponse = {
12 ok: false;
13 error: {
14 code: ControlPlaneErrorCode;
15 message: string;
16 details: string | null;
17 };
18};
19
20const renderCause = (cause: unknown): string => String(cause);
21
22export const toSourceStoreError = (
23 operation: string,
24 cause: unknown,
25): SourceStoreError =>
26 new SourceStoreError({
27 operation,
28 backend: "convex",
29 location: "control-plane",
30 message: "Convex control plane call failed",
31 reason: null,
32 details: renderCause(cause),
33 });
34
35const toErrorCode = (status: number): ControlPlaneErrorCode => {
36 switch (status) {
37 case 400:
38 return "bad_request";
39 case 401:
40 return "unauthorized";
41 case 403:
42 return "forbidden";
43 case 404:
44 return "not_found";
45 case 405:
46 return "method_not_allowed";
47 default:
48 return "internal";
49 }
50};
51
52export const controlPlaneErrorResponse = (
53 status: number,
54 message: string,
55 details: string | null,
56): Response =>
57 Response.json(
58 {
59 ok: false,
60 error: {
61 code: toErrorCode(status),
62 message,
63 details,
64 },
65 } satisfies ControlPlaneErrorResponse,
66 { status },
67 );
68
69const isJsonResponse = (response: Response): boolean =>
70 response.headers.get("content-type")?.toLowerCase().includes("application/json") ?? false;
71
72export const normalizeControlPlaneErrorResponse = (response: Response): Response => {
73 if (response.ok || isJsonResponse(response)) {
74 return response;
75 }
76
77 return controlPlaneErrorResponse(
78 response.status,
79 "Control plane request failed",
80 response.statusText || null,
81 );
82};
apps/convex/convex/control_plane/http.ts+67−0
@@ -0,0 +1,67 @@
1import {
2 ControlPlaneService,
3 controlPlaneOpenApiSpec,
4 makeControlPlaneWebHandler,
5} from "@executor-v2/management-api";
6import * as Effect from "effect/Effect";
7import * as Layer from "effect/Layer";
8
9import { httpAction, type ActionCtx } from "../_generated/server";
10import { ConvexControlPlaneActorLive } from "./actor";
11import {
12 controlPlaneErrorResponse,
13 normalizeControlPlaneErrorResponse,
14 toSourceStoreError,
15} from "./errors";
16import { makeConvexControlPlaneService } from "./service";
17
18const isOpenApiRequest = (request: Request): boolean =>
19 new URL(request.url).pathname === "/v1/openapi.json";
20
21const handleControlPlaneRequest = (
22 ctx: ActionCtx,
23 request: Request,
24): Effect.Effect<Response, never> =>
25 Effect.scoped(
26 Effect.gen(function* () {
27 if (isOpenApiRequest(request)) {
28 return Response.json(controlPlaneOpenApiSpec, { status: 200 });
29 }
30
31 const webHandler = makeControlPlaneWebHandler(
32 Layer.succeed(ControlPlaneService, makeConvexControlPlaneService(ctx)),
33 ConvexControlPlaneActorLive(ctx),
34 );
35
36 yield* Effect.addFinalizer(() =>
37 Effect.tryPromise({
38 try: () => webHandler.dispose(),
39 catch: (cause) => toSourceStoreError("controlPlane.dispose", cause),
40 }).pipe(
41 Effect.asVoid,
42 Effect.catchAll(() => Effect.void),
43 ),
44 );
45
46 const response = yield* Effect.tryPromise({
47 try: () => webHandler.handler(request),
48 catch: (cause) => toSourceStoreError("controlPlane.http", cause),
49 });
50
51 return normalizeControlPlaneErrorResponse(response);
52 }),
53 ).pipe(
54 Effect.catchAll((error) =>
55 Effect.succeed(
56 controlPlaneErrorResponse(
57 500,
58 "Control plane request failed",
59 error.details,
60 ),
61 ),
62 ),
63 );
64
65export const controlPlaneHttpHandler = httpAction((ctx, request) =>
66 Effect.runPromise(handleControlPlaneRequest(ctx, request)),
67);
apps/convex/convex/control_plane/openapi_ingest.ts+1437−0
@@ -0,0 +1,1437 @@
1"use node";
2
3import { createHash } from "node:crypto";
4
5import { type Source } from "@executor-v2/schema";
6import { Client } from "@modelcontextprotocol/sdk/client/index.js";
7import { SSEClientTransport } from "@modelcontextprotocol/sdk/client/sse.js";
8import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
9import { v } from "convex/values";
10import * as Effect from "effect/Effect";
11import * as Schema from "effect/Schema";
12
13import { internal } from "../_generated/api";
14import { internalAction } from "../_generated/server";
15
16const runtimeInternal = internal as any;
17
18const graphqlExtractorVersion = "graphql_v1";
19const mcpExtractorVersion = "mcp_v1";
20const writeBatchSize = 500;
21
22const graphqlSchemaRootsQuery = `query SchemaRoots {
23 __schema {
24 queryType { name }
25 mutationType { name }
26 }
27}`;
28
29const graphqlRootFieldsQuery = `query RootFields($name: String!) {
30 __type(name: $name) {
31 name
32 fields {
33 name
34 description
35 args {
36 name
37 description
38 defaultValue
39 type {
40 kind
41 name
42 ofType {
43 kind
44 name
45 ofType {
46 kind
47 name
48 }
49 }
50 }
51 }
52 }
53 }
54}`;
55
56type GraphqlIngestTool = {
57 toolId: string;
58 name: string;
59 description: string | null;
60 operationType: string;
61 fieldName: string;
62 operationHash: string;
63 invocationJson: string;
64};
65
66type McpIngestTool = {
67 toolId: string;
68 name: string;
69 description: string | null;
70 toolName: string;
71 operationHash: string;
72 invocationJson: string;
73};
74
75type McpTransport = "sse" | "streamable-http";
76
77type McpConnection = {
78 client: Client;
79 close: () => Promise<void>;
80 transport: McpTransport;
81};
82
83const SourceIngestStatusSchema = Schema.Union(
84 Schema.Literal("error"),
85 Schema.Literal("auth_required"),
86);
87
88type SourceIngestStatus = typeof SourceIngestStatusSchema.Type;
89
90class SourceIngestError extends Schema.TaggedError<SourceIngestError>()(
91 "SourceIngestError",
92 {
93 status: SourceIngestStatusSchema,
94 message: Schema.String,
95 },
96) {}
97
98type SourceIngestPrepared = {
99 protocol: "openapi" | "graphql" | "mcp";
100 artifactId: string;
101 sourceHash: string;
102 toolCount: number;
103 namespace: string;
104 refHintTableJson: string | null;
105 artifactBatchCount: number;
106};
107
108const isUnknownRecord = (value: unknown): value is Record<string, unknown> =>
109 typeof value === "object" && value !== null && !Array.isArray(value);
110
111const normalizeString = (value: unknown): string | null => {
112 if (typeof value !== "string") {
113 return null;
114 }
115
116 const trimmed = value.trim();
117 return trimmed.length > 0 ? trimmed : null;
118};
119
120const stableStringify = (value: unknown): string => {
121 if (Array.isArray(value)) {
122 return `[${value.map((entry) => stableStringify(entry)).join(",")}]`;
123 }
124
125 if (isUnknownRecord(value)) {
126 const keys = Object.keys(value).sort();
127 return `{${keys
128 .map((key) => `${JSON.stringify(key)}:${stableStringify(value[key])}`)
129 .join(",")}}`;
130 }
131
132 return JSON.stringify(value);
133};
134
135const hashUnknown = (value: unknown): string =>
136 createHash("sha256").update(stableStringify(value)).digest("hex").slice(0, 16);
137
138const sourceSlug = (name: string): string => {
139 const slug = name
140 .toLowerCase()
141 .replaceAll(/[^a-z0-9]+/g, "_")
142 .replaceAll(/^_+|_+$/g, "");
143
144 return slug.length > 0 ? slug : "graphql";
145};
146
147const toolSegment = (value: string): string => {
148 const segment = value
149 .toLowerCase()
150 .replaceAll(/[^a-z0-9]+/g, "_")
151 .replaceAll(/^_+|_+$/g, "");
152
153 return segment.length > 0 ? segment : "field";
154};
155
156const normalizeNamespacePart = (value: string): string => {
157 const normalized = value
158 .trim()
159 .toLowerCase()
160 .replace(/[^a-z0-9]+/g, "_")
161 .replace(/^_+|_+$/g, "");
162
163 return normalized.length > 0 ? normalized : "source";
164};
165
166const sourceNamespace = (source: Source): string => {
167 const sourceIdSuffix = source.id.slice(-6).toLowerCase();
168 return `${normalizeNamespacePart(source.name)}_${sourceIdSuffix}`;
169};
170
171const sourceToolPath = (source: Source, toolId: string): string =>
172 `${sourceNamespace(source)}.${toolId}`;
173
174const normalizedSearchText = (...parts: ReadonlyArray<string | null | undefined>): string =>
175 parts
176 .map((part) => (typeof part === "string" ? part.trim().toLowerCase() : ""))
177 .filter((part) => part.length > 0)
178 .join(" ");
179
180const metadataSearchTerms = (metadataJson: string | null | undefined): ReadonlyArray<string> => {
181 if (!metadataJson) {
182 return [];
183 }
184
185 const parsed = parseJsonObject(metadataJson);
186 const keys = ["method", "path", "operationType", "fieldName", "toolName"] as const;
187 const terms: Array<string> = [];
188
189 for (const key of keys) {
190 const value = parsed[key];
191 if (typeof value === "string" && value.trim().length > 0) {
192 terms.push(value);
193 }
194 }
195
196 return terms;
197};
198
199const toWorkspaceToolMethod = (protocol: string, metadataJson: string | null | undefined): string => {
200 if (protocol !== "openapi") {
201 return "post";
202 }
203
204 const parsed = metadataJson ? parseJsonObject(metadataJson) : {};
205 const method = typeof parsed.method === "string" ? parsed.method.trim().toLowerCase() : "";
206
207 if (
208 method === "get" ||
209 method === "post" ||
210 method === "put" ||
211 method === "patch" ||
212 method === "delete" ||
213 method === "head" ||
214 method === "options" ||
215 method === "trace"
216 ) {
217 return method;
218 }
219
220 return "get";
221};
222
223const parseJsonObject = (value: string): Record<string, unknown> => {
224 try {
225 const parsed = JSON.parse(value) as unknown;
226 return isUnknownRecord(parsed) ? parsed : {};
227 } catch {
228 return {};
229 }
230};
231
232const safeJsonStringify = (value: unknown): string | null => {
233 try {
234 return JSON.stringify(value);
235 } catch {
236 return null;
237 }
238};
239
240const chunkArray = <A>(values: ReadonlyArray<A>, size: number): Array<Array<A>> => {
241 const chunkSize = Math.max(1, Math.floor(size));
242 const chunks: Array<Array<A>> = [];
243
244 for (let index = 0; index < values.length; index += chunkSize) {
245 chunks.push(values.slice(index, index + chunkSize));
246 }
247
248 return chunks;
249};
250
251const extractMcpSchemas = (
252 invocationJson: string,
253): { inputSchemaJson: string | null; outputSchemaJson: string | null } => {
254 const parsed = parseJsonObject(invocationJson);
255 return {
256 inputSchemaJson: safeJsonStringify(parsed.inputSchema) ?? null,
257 outputSchemaJson: safeJsonStringify(parsed.outputSchema) ?? null,
258 };
259};
260
261const typeRefToLabel = (typeRef: unknown): string => {
262 if (!isUnknownRecord(typeRef)) {
263 return "Unknown";
264 }
265
266 const kind = normalizeString(typeRef.kind);
267 const name = normalizeString(typeRef.name);
268 const ofType = typeRef.ofType;
269
270 if (kind === "NON_NULL") {
271 return `${typeRefToLabel(ofType)}!`;
272 }
273
274 if (kind === "LIST") {
275 return `[${typeRefToLabel(ofType)}]`;
276 }
277
278 if (name) {
279 return name;
280 }
281
282 return kind ?? "Unknown";
283};
284
285const isRequiredType = (typeRef: unknown): boolean =>
286 isUnknownRecord(typeRef) && normalizeString(typeRef.kind) === "NON_NULL";
287
288const parseSourceConfig = (configJson: string): Record<string, unknown> => {
289 try {
290 const parsed = JSON.parse(configJson) as unknown;
291 return isUnknownRecord(parsed) ? parsed : {};
292 } catch {
293 return {};
294 }
295};
296
297const collectAuthHeadersFromSourceConfig = (config: Record<string, unknown>): Record<string, string> => {
298 const headers: Record<string, string> = {};
299
300 const auth = config.auth;
301 if (!isUnknownRecord(auth)) {
302 return headers;
303 }
304
305 const authType = normalizeString(auth.type)?.toLowerCase();
306
307 if (authType === "bearer") {
308 const token = normalizeString(auth.token) ?? normalizeString(auth.value);
309 if (token) {
310 headers.Authorization = `Bearer ${token}`;
311 }
312 }
313
314 if (authType === "apikey" || authType === "api_key") {
315 const value = normalizeString(auth.value) ?? normalizeString(auth.token);
316 if (value) {
317 const headerName = normalizeString(auth.header) ?? "Authorization";
318 headers[headerName] = value;
319 }
320 }
321
322 if (authType === "basic") {
323 const username = normalizeString(auth.username);
324 const password = normalizeString(auth.password);
325 if (username && password) {
326 headers.Authorization = `Basic ${Buffer.from(`${username}:${password}`).toString("base64")}`;
327 }
328 }
329
330 return headers;
331};
332
333const collectConfiguredHeadersFromSourceConfig = (config: Record<string, unknown>): Record<string, string> => {
334 const headers: Record<string, string> = {};
335 const configuredHeaders = config.headers;
336
337 if (!isUnknownRecord(configuredHeaders)) {
338 return headers;
339 }
340
341 for (const [headerKey, headerValue] of Object.entries(configuredHeaders)) {
342 const key = normalizeString(headerKey);
343 const value = normalizeString(headerValue);
344 if (key && value) {
345 headers[key] = value;
346 }
347 }
348
349 return headers;
350};
351
352const collectGraphqlHeadersFromSourceConfig = (source: Source): Record<string, string> => {
353 const config = parseSourceConfig(source.configJson);
354 return {
355 "content-type": "application/json",
356 ...collectConfiguredHeadersFromSourceConfig(config),
357 ...collectAuthHeadersFromSourceConfig(config),
358 };
359};
360
361const collectMcpHeadersFromSourceConfig = (source: Source): Record<string, string> => {
362 const config = parseSourceConfig(source.configJson);
363 return {
364 ...collectConfiguredHeadersFromSourceConfig(config),
365 ...collectAuthHeadersFromSourceConfig(config),
366 };
367};
368
369const mergeHeaders = (...sets: ReadonlyArray<Record<string, string>>): Record<string, string> => {
370 const merged: Record<string, string> = {};
371 const keyByLower = new Map<string, string>();
372
373 for (const headers of sets) {
374 for (const [rawKey, rawValue] of Object.entries(headers)) {
375 const key = rawKey.trim();
376 const value = rawValue.trim();
377 if (key.length === 0 || value.length === 0) {
378 continue;
379 }
380
381 const normalizedKey = key.toLowerCase();
382 const existingKey = keyByLower.get(normalizedKey);
383 if (existingKey && existingKey !== key) {
384 delete merged[existingKey];
385 }
386
387 keyByLower.set(normalizedKey, key);
388 merged[key] = value;
389 }
390 }
391
392 return merged;
393};
394
395const graphqlAuthErrorCodes = new Set(["unauthenticated", "forbidden", "unauthorized"]);
396
397const payloadHasGraphqlAuthError = (payload: unknown): boolean => {
398 if (!isUnknownRecord(payload) || !Array.isArray(payload.errors)) {
399 return false;
400 }
401
402 return payload.errors.some((entry) => {
403 if (!isUnknownRecord(entry)) {
404 return false;
405 }
406
407 const message = normalizeString(entry.message)?.toLowerCase();
408 if (message && (message.includes("unauthor") || message.includes("forbidden") || message.includes("auth"))) {
409 return true;
410 }
411
412 if (!isUnknownRecord(entry.extensions)) {
413 return false;
414 }
415
416 const code = normalizeString(entry.extensions.code)?.toLowerCase();
417 return code ? graphqlAuthErrorCodes.has(code) : false;
418 });
419};
420
421const looksLikeAuthErrorMessage = (value: string): boolean => {
422 const message = value.toLowerCase();
423 return message.includes("unauthor") || message.includes("forbidden") || message.includes("auth required");
424};
425
426const sourceIngestStatusFromCause = (cause: unknown): SourceIngestStatus => {
427 if (cause instanceof SourceIngestError) {
428 return cause.status;
429 }
430
431 const message = formatError(cause);
432 return looksLikeAuthErrorMessage(message) ? "auth_required" : "error";
433};
434
435const extractGraphqlErrorMessage = (payload: unknown, status: number): string => {
436 if (isUnknownRecord(payload) && Array.isArray(payload.errors) && payload.errors.length > 0) {
437 const firstError = payload.errors[0];
438 if (isUnknownRecord(firstError)) {
439 const message = normalizeString(firstError.message);
440 if (message) {
441 return message;
442 }
443 }
444 }
445
446 return `GraphQL schema request failed (${status})`;
447};
448
449const fetchGraphqlPayload = (
450 source: Source,
451 headers: Record<string, string>,
452 body: Record<string, unknown>,
453): Effect.Effect<Record<string, unknown>, SourceIngestError> =>
454 Effect.gen(function* () {
455 const response = yield* Effect.tryPromise({
456 try: () =>
457 fetch(source.endpoint, {
458 method: "POST",
459 headers,
460 body: JSON.stringify(body),
461 cache: "no-store",
462 }),
463 catch: (cause) =>
464 SourceIngestError.make({
465 status: "error",
466 message: `GraphQL schema request failed: ${formatError(cause)}`,
467 }),
468 });
469
470 const payload = yield* Effect.tryPromise({
471 try: () => response.json().catch(() => null),
472 catch: (cause) =>
473 SourceIngestError.make({
474 status: "error",
475 message: `GraphQL schema response parse failed: ${formatError(cause)}`,
476 }),
477 });
478
479 if (!response.ok) {
480 const message = extractGraphqlErrorMessage(payload, response.status);
481 const authRequired =
482 response.status === 401 || response.status === 403 || payloadHasGraphqlAuthError(payload);
483
484 return yield* SourceIngestError.make({
485 status: authRequired ? "auth_required" : "error",
486 message,
487 });
488 }
489
490 if (!isUnknownRecord(payload)) {
491 return yield* SourceIngestError.make({
492 status: "error",
493 message: "GraphQL response is not an object",
494 });
495 }
496
497 return payload;
498 });
499
500const loadGraphqlSchemaRoots = (
501 source: Source,
502 headers: Record<string, string>,
503): Effect.Effect<
504 {
505 queryTypeName: string | null;
506 mutationTypeName: string | null;
507 },
508 SourceIngestError
509> =>
510 Effect.gen(function* () {
511 const payload = yield* fetchGraphqlPayload(source, headers, {
512 query: graphqlSchemaRootsQuery,
513 });
514
515 const data = payload.data;
516 const schema = isUnknownRecord(data) && isUnknownRecord(data.__schema)
517 ? data.__schema
518 : null;
519
520 if (!schema) {
521 return yield* SourceIngestError.make({
522 status: "error",
523 message: "GraphQL schema roots payload is missing __schema",
524 });
525 }
526
527 return {
528 queryTypeName: isUnknownRecord(schema.queryType) ? normalizeString(schema.queryType.name) : null,
529 mutationTypeName: isUnknownRecord(schema.mutationType)
530 ? normalizeString(schema.mutationType.name)
531 : null,
532 };
533 });
534
535const loadGraphqlRootFields = (
536 source: Source,
537 headers: Record<string, string>,
538 rootTypeName: string | null,
539): Effect.Effect<Array<Record<string, unknown>>, SourceIngestError> =>
540 Effect.gen(function* () {
541 if (!rootTypeName) {
542 return [];
543 }
544
545 const payload = yield* fetchGraphqlPayload(source, headers, {
546 query: graphqlRootFieldsQuery,
547 variables: {
548 name: rootTypeName,
549 },
550 });
551
552 const data = payload.data;
553 const rootType = isUnknownRecord(data) && isUnknownRecord(data.__type)
554 ? data.__type
555 : null;
556
557 if (!rootType) {
558 return [];
559 }
560
561 const fields = rootType.fields;
562 if (!Array.isArray(fields)) {
563 return [];
564 }
565
566 return fields.filter((field): field is Record<string, unknown> => isUnknownRecord(field));
567 });
568
569const ensureUniqueToolIds = (tools: Array<GraphqlIngestTool>): Array<GraphqlIngestTool> => {
570 const counts = new Map<string, number>();
571
572 return tools.map((tool) => {
573 const count = (counts.get(tool.toolId) ?? 0) + 1;
574 counts.set(tool.toolId, count);
575
576 if (count === 1) {
577 return tool;
578 }
579
580 return {
581 ...tool,
582 toolId: `${tool.toolId}_${count}`,
583 };
584 });
585};
586
587const extractGraphqlTools = (
588 source: Source,
589 roots: {
590 queryTypeName: string | null;
591 mutationTypeName: string | null;
592 },
593 queryFields: ReadonlyArray<Record<string, unknown>>,
594 mutationFields: ReadonlyArray<Record<string, unknown>>,
595): {
596 schemaHash: string;
597 tools: Array<GraphqlIngestTool>;
598} => {
599 const slug = sourceSlug(source.name);
600
601 const rawInvocation = {
602 kind: "graphql_raw",
603 endpoint: source.endpoint,
604 };
605
606 const tools: Array<GraphqlIngestTool> = [
607 {
608 toolId: `${slug}.graphql`,
609 name: `${source.name} GraphQL`,
610 description: `Run raw GraphQL queries against ${source.name}.`,
611 operationType: "raw",
612 fieldName: "graphql",
613 operationHash: hashUnknown(rawInvocation),
614 invocationJson: JSON.stringify(rawInvocation),
615 },
616 ];
617
618 const fieldSignatures: Array<unknown> = [];
619
620 const addOperationTools = (
621 operationType: "query" | "mutation",
622 fields: ReadonlyArray<Record<string, unknown>>,
623 ): void => {
624 for (const field of fields) {
625 const fieldName = normalizeString(field.name);
626 if (!fieldName) {
627 continue;
628 }
629
630 const args = Array.isArray(field.args)
631 ? field.args
632 .filter((arg): arg is Record<string, unknown> => isUnknownRecord(arg))
633 .map((arg) => ({
634 name: normalizeString(arg.name) ?? "arg",
635 description: normalizeString(arg.description),
636 required: isRequiredType(arg.type),
637 type: typeRefToLabel(arg.type),
638 defaultValue: normalizeString(arg.defaultValue),
639 }))
640 : [];
641
642 const invocation = {
643 kind: "graphql_field",
644 endpoint: source.endpoint,
645 operationType,
646 fieldName,
647 args,
648 };
649
650 tools.push({
651 toolId: `${slug}.${operationType}.${toolSegment(fieldName)}`,
652 name: fieldName,
653 description: normalizeString(field.description),
654 operationType,
655 fieldName,
656 operationHash: hashUnknown(invocation),
657 invocationJson: JSON.stringify(invocation),
658 });
659
660 fieldSignatures.push({
661 operationType,
662 fieldName,
663 args: args.map((arg) => ({
664 name: arg.name,
665 required: arg.required,
666 type: arg.type,
667 })),
668 });
669 }
670 };
671
672 addOperationTools("query", queryFields);
673 addOperationTools("mutation", mutationFields);
674
675 return {
676 schemaHash: hashUnknown({
677 queryTypeName: roots.queryTypeName,
678 mutationTypeName: roots.mutationTypeName,
679 fieldSignatures,
680 }),
681 tools: ensureUniqueToolIds(tools),
682 };
683};
684
685const parseMcpTransportPreference = (source: Source): McpTransport | null => {
686 const config = parseSourceConfig(source.configJson);
687 const transport = normalizeString(config.transport)?.toLowerCase();
688
689 if (transport === "sse") {
690 return "sse";
691 }
692
693 if (transport === "streamable-http" || transport === "streamable_http") {
694 return "streamable-http";
695 }
696
697 return null;
698};
699
700const parseMcpQueryParams = (source: Source): Record<string, string> => {
701 const config = parseSourceConfig(source.configJson);
702 const queryParams = config.queryParams;
703
704 if (!isUnknownRecord(queryParams)) {
705 return {};
706 }
707
708 const normalized: Record<string, string> = {};
709 for (const [rawKey, rawValue] of Object.entries(queryParams)) {
710 const key = normalizeString(rawKey);
711 const value = normalizeString(rawValue);
712 if (key && value) {
713 normalized[key] = value;
714 }
715 }
716
717 return normalized;
718};
719
720const withMcpHeaders = (
721 input: RequestInfo | URL,
722 init: RequestInit | undefined,
723 headers: Record<string, string>,
724): Promise<Response> => {
725 const mergedHeaders = new Headers(init?.headers ?? {});
726 for (const [key, value] of Object.entries(headers)) {
727 mergedHeaders.set(key, value);
728 }
729
730 return fetch(input, {
731 ...init,
732 headers: mergedHeaders,
733 });
734};
735
736const connectMcp = (
737 source: Source,
738 headers: Record<string, string>,
739): Effect.Effect<McpConnection, SourceIngestError> =>
740 Effect.gen(function* () {
741 const endpoint = yield* Effect.try({
742 try: () => new URL(source.endpoint),
743 catch: () =>
744 SourceIngestError.make({
745 status: "error",
746 message: `Invalid MCP endpoint URL: ${source.endpoint}`,
747 }),
748 });
749
750 const queryParams = parseMcpQueryParams(source);
751 for (const [key, value] of Object.entries(queryParams)) {
752 endpoint.searchParams.set(key, value);
753 }
754
755 const connectWithTransport = (
756 transport: McpTransport,
757 ): Effect.Effect<McpConnection, SourceIngestError> =>
758 Effect.tryPromise({
759 try: async () => {
760 const client = new Client(
761 {
762 name: "executor-v2-control-plane",
763 version: "0.1.0",
764 },
765 { capabilities: {} },
766 );
767
768 if (transport === "streamable-http") {
769 await client.connect(new StreamableHTTPClientTransport(endpoint, {
770 requestInit: { headers },
771 }));
772 } else {
773 await client.connect(new SSEClientTransport(endpoint, {
774 requestInit: { headers },
775 eventSourceInit: {
776 fetch: (input, init) => withMcpHeaders(input, init, headers),
777 },
778 }));
779 }
780
781 return {
782 client,
783 close: () => client.close(),
784 transport,
785 };
786 },
787 catch: (cause) =>
788 SourceIngestError.make({
789 status: sourceIngestStatusFromCause(cause),
790 message: `Failed to connect to MCP source: ${formatError(cause)}`,
791 }),
792 });
793
794 const preferred = parseMcpTransportPreference(source);
795 if (preferred === "streamable-http") {
796 return yield* connectWithTransport("streamable-http");
797 }
798
799 if (preferred === "sse") {
800 return yield* connectWithTransport("sse");
801 }
802
803 const streamableAttempt = yield* connectWithTransport("streamable-http").pipe(Effect.either);
804 if (streamableAttempt._tag === "Right") {
805 return streamableAttempt.right;
806 }
807
808 return yield* connectWithTransport("sse");
809 });
810
811const normalizeJsonSchema = (value: unknown): Record<string, unknown> => {
812 if (value === true) {
813 return {};
814 }
815
816 if (value === false) {
817 return { not: {} };
818 }
819
820 return isUnknownRecord(value) ? value : {};
821};
822
823const extractMcpListedToolRows = (value: unknown): Array<Record<string, unknown>> => {
824 if (!isUnknownRecord(value) || !Array.isArray(value.tools)) {
825 return [];
826 }
827
828 return value.tools.filter((tool): tool is Record<string, unknown> => isUnknownRecord(tool));
829};
830
831const ensureUniqueMcpToolIds = (tools: Array<McpIngestTool>): Array<McpIngestTool> => {
832 const counts = new Map<string, number>();
833
834 return tools.map((tool) => {
835 const count = (counts.get(tool.toolId) ?? 0) + 1;
836 counts.set(tool.toolId, count);
837
838 if (count === 1) {
839 return tool;
840 }
841
842 return {
843 ...tool,
844 toolId: `${tool.toolId}_${count}`,
845 };
846 });
847};
848
849const extractMcpTools = (
850 source: Source,
851 transport: McpTransport,
852 listedTools: ReadonlyArray<Record<string, unknown>>,
853): {
854 sourceHash: string;
855 tools: Array<McpIngestTool>;
856} => {
857 const slug = sourceSlug(source.name);
858 const queryParams = parseMcpQueryParams(source);
859
860 const tools: Array<McpIngestTool> = [];
861 const toolSignatures: Array<unknown> = [];
862
863 for (const tool of listedTools) {
864 const toolName = normalizeString(tool.name);
865 if (!toolName) {
866 continue;
867 }
868
869 const inputSchema = normalizeJsonSchema(tool.inputSchema);
870 const outputSchema = normalizeJsonSchema(tool.outputSchema);
871 const invocation = {
872 kind: "mcp_tool",
873 endpoint: source.endpoint,
874 transport,
875 queryParams,
876 toolName,
877 };
878
879 tools.push({
880 toolId: `${slug}.mcp.${toolSegment(toolName)}`,
881 name: toolName,
882 description: normalizeString(tool.description),
883 toolName,
884 operationHash: hashUnknown({ invocation, inputSchema, outputSchema }),
885 invocationJson: JSON.stringify({
886 ...invocation,
887 inputSchema,
888 outputSchema,
889 }),
890 });
891
892 toolSignatures.push({ toolName, inputSchema, outputSchema });
893 }
894
895 return {
896 sourceHash: hashUnknown({
897 endpoint: source.endpoint,
898 transport,
899 queryParams,
900 toolSignatures,
901 }),
902 tools: ensureUniqueMcpToolIds(tools),
903 };
904};
905
906const formatError = (cause: unknown): string =>
907 cause instanceof Error ? cause.message : String(cause);
908
909const trySourceIngestPromise = <A>(
910 promise: () => Promise<A>,
911 message: string,
912): Effect.Effect<A, SourceIngestError> =>
913 Effect.tryPromise({
914 try: promise,
915 catch: (cause) =>
916 SourceIngestError.make({
917 status: "error",
918 message: `${message}: ${formatError(cause)}`,
919 }),
920 });
921
922const openApiParserUrl = process.env.OPENAPI_PARSE_API_URL?.trim() ?? "";
923const openApiParserToken = process.env.OPENAPI_PARSE_API_TOKEN?.trim() ?? "";
924
925type OpenApiParserIngestedPayload = {
926 ok?: boolean;
927 mode?: string;
928 artifactId?: string;
929 sourceHash?: string;
930 toolCount?: number;
931 namespace?: string;
932 refHintTableJson?: string | null;
933 artifactBatchCount?: number;
934 error?: string;
935};
936
937const fetchOpenApiDocumentForIngest = async (
938 source: Source,
939): Promise<{
940 artifactId: string;
941 sourceHash: string;
942 toolCount: number;
943 namespace: string;
944 refHintTableJson: string | null;
945 artifactBatchCount: number;
946}> => {
947 if (openApiParserUrl.length === 0) {
948 throw new Error("OPENAPI_PARSE_API_URL is required for OpenAPI ingestion");
949 }
950
951 const response = await fetch(openApiParserUrl, {
952 method: "POST",
953 headers: {
954 "content-type": "application/json",
955 ...(openApiParserToken.length > 0
956 ? { "x-openapi-parse-token": openApiParserToken }
957 : {}),
958 },
959 body: JSON.stringify({
960 specUrl: source.endpoint,
961 workspaceId: source.workspaceId,
962 sourceId: source.id,
963 sourceName: source.name,
964 sourceEnabled: source.enabled,
965 }),
966 });
967
968 if (!response.ok) {
969 const details = await response.text().catch(() => "");
970 throw new Error(
971 `Parser endpoint failed (${response.status}): ${
972 details.trim().length > 0 ? details.trim() : response.statusText
973 }`,
974 );
975 }
976
977 const payload = (await response.json()) as OpenApiParserIngestedPayload;
978
979 if (payload.ok !== true) {
980 throw new Error(
981 payload.error && payload.error.trim().length > 0
982 ? payload.error
983 : "Parser endpoint returned an invalid payload",
984 );
985 }
986
987 if (payload.mode !== "ingested") {
988 throw new Error("Parser endpoint must return mode='ingested' for OpenAPI ingestion");
989 }
990
991 const artifactId = normalizeString(payload.artifactId);
992 const sourceHash = normalizeString(payload.sourceHash);
993 const namespace = normalizeString(payload.namespace);
994 const toolCount = Number.isFinite(payload.toolCount)
995 ? Math.max(0, Math.floor(payload.toolCount ?? 0))
996 : null;
997 const artifactBatchCount = Number.isFinite(payload.artifactBatchCount)
998 ? Math.max(0, Math.floor(payload.artifactBatchCount ?? 0))
999 : 0;
1000
1001 if (!artifactId || !sourceHash || !namespace || toolCount === null) {
1002 throw new Error("Parser endpoint returned an invalid ingested payload");
1003 }
1004
1005 return {
1006 artifactId,
1007 sourceHash,
1008 toolCount,
1009 namespace,
1010 refHintTableJson:
1011 typeof payload.refHintTableJson === "string" ? payload.refHintTableJson : null,
1012 artifactBatchCount,
1013 };
1014};
1015
1016type IngestOptions = {
1017 rebuildIndex: boolean;
1018 stageArtifactWrites: boolean;
1019};
1020
1021const ingestOpenApiSource = (
1022 ctx: any,
1023 source: Source,
1024): Effect.Effect<SourceIngestPrepared, SourceIngestError> =>
1025 Effect.gen(function* () {
1026 const ingested = yield* trySourceIngestPromise(
1027 () => fetchOpenApiDocumentForIngest(source),
1028 "Failed to fetch OpenAPI document",
1029 );
1030
1031 return {
1032 protocol: "openapi",
1033 artifactId: ingested.artifactId,
1034 sourceHash: ingested.sourceHash,
1035 toolCount: ingested.toolCount,
1036 namespace: ingested.namespace,
1037 refHintTableJson: ingested.refHintTableJson,
1038 artifactBatchCount: ingested.artifactBatchCount,
1039 };
1040 });
1041
1042const ingestGraphqlSource = (
1043 ctx: any,
1044 source: Source,
1045 options: IngestOptions,
1046): Effect.Effect<SourceIngestPrepared, SourceIngestError> =>
1047 Effect.gen(function* () {
1048 const credentialHeadersResult = yield* trySourceIngestPromise<{
1049 headers: Record<string, string>;
1050 }>(
1051 () =>
1052 ctx.runAction(runtimeInternal.control_plane.credentials.resolveSourceCredentialHeadersForIngest, {
1053 workspaceId: source.workspaceId,
1054 sourceId: source.id,
1055 sourceName: source.name,
1056 sourceEndpoint: source.endpoint,
1057 }),
1058 "Failed to resolve source credentials for GraphQL ingest",
1059 );
1060
1061 const headers = mergeHeaders(
1062 collectGraphqlHeadersFromSourceConfig(source),
1063 credentialHeadersResult.headers,
1064 );
1065
1066 const roots = yield* loadGraphqlSchemaRoots(source, headers);
1067 const queryFields = yield* loadGraphqlRootFields(source, headers, roots.queryTypeName);
1068 const mutationFields = yield* loadGraphqlRootFields(source, headers, roots.mutationTypeName);
1069 const extracted = extractGraphqlTools(source, roots, queryFields, mutationFields);
1070
1071 const artifactMeta = yield* trySourceIngestPromise<{
1072 artifactId: string;
1073 created: boolean;
1074 }>(
1075 () =>
1076 ctx.runMutation(runtimeInternal.control_plane.tool_registry.upsertArtifactMeta, {
1077 protocol: "graphql",
1078 contentHash: extracted.schemaHash,
1079 extractorVersion: graphqlExtractorVersion,
1080 toolCount: extracted.tools.length,
1081 }),
1082 "Failed to upsert GraphQL artifact metadata",
1083 );
1084
1085 if (artifactMeta.created) {
1086 const artifactRows = extracted.tools.map((tool) => ({
1087 toolId: tool.toolId,
1088 name: tool.name,
1089 description: tool.description,
1090 canonicalPath: `${tool.operationType}.${tool.fieldName}`,
1091 operationHash: tool.operationHash,
1092 invocationJson: tool.invocationJson,
1093 metadataJson: safeJsonStringify({
1094 operationType: tool.operationType,
1095 fieldName: tool.fieldName,
1096 }),
1097 }));
1098
1099 if (options.stageArtifactWrites) {
1100 const serializedBatches = chunkArray(artifactRows, stagedArtifactBatchSize).map((batch) =>
1101 JSON.stringify(batch),
1102 );
1103
1104 yield* trySourceIngestPromise(
1105 () =>
1106 ctx.runMutation(
1107 runtimeInternal.control_plane.tool_registry.replaceSourceIngestArtifactBatches,
1108 {
1109 workspaceId: source.workspaceId,
1110 sourceId: source.id,
1111 artifactId: artifactMeta.artifactId,
1112 protocol: "graphql",
1113 batches: serializedBatches,
1114 },
1115 ),
1116 "Failed to stage GraphQL artifact tool batches",
1117 );
1118 } else {
1119 for (let index = 0; index < artifactRows.length; index += writeBatchSize) {
1120 const batch = artifactRows.slice(index, index + writeBatchSize);
1121 yield* trySourceIngestPromise(
1122 () =>
1123 ctx.runMutation(runtimeInternal.control_plane.tool_registry.putArtifactToolsBatch, {
1124 artifactId: artifactMeta.artifactId,
1125 protocol: "graphql",
1126 insertOnly: true,
1127 tools: batch,
1128 }),
1129 "Failed to write GraphQL artifact tools",
1130 );
1131 }
1132 }
1133 }
1134
1135 yield* trySourceIngestPromise(
1136 () =>
1137 ctx.runMutation(runtimeInternal.control_plane.tool_registry.bindSourceToArtifact, {
1138 workspaceId: source.workspaceId,
1139 sourceId: source.id,
1140 artifactId: artifactMeta.artifactId,
1141 }),
1142 "Failed to bind source to GraphQL artifact",
1143 );
1144
1145 const namespace = sourceNamespace(source);
1146 const indexRows = extracted.tools.map((tool) => ({
1147 toolId: tool.toolId,
1148 protocol: "graphql",
1149 method: "post",
1150 path: sourceToolPath(source, tool.toolId),
1151 operationPath: null,
1152 name: tool.name,
1153 description: tool.description,
1154 searchText: normalizedSearchText(
1155 source.name,
1156 source.endpoint,
1157 namespace,
1158 tool.toolId,
1159 tool.name,
1160 tool.description,
1161 tool.operationType,
1162 tool.fieldName,
1163 ),
1164 operationHash: tool.operationHash,
1165 approvalMode: "auto",
1166 status: source.enabled ? "active" : "disabled",
1167 }));
1168
1169 if (options.rebuildIndex) {
1170 yield* trySourceIngestPromise(
1171 () =>
1172 ctx.runMutation(runtimeInternal.control_plane.tool_registry.replaceWorkspaceSourceToolIndex, {
1173 workspaceId: source.workspaceId,
1174 sourceId: source.id,
1175 sourceName: source.name,
1176 sourceKind: source.kind,
1177 artifactId: artifactMeta.artifactId,
1178 namespace,
1179 refHintTableJson: null,
1180 rows: indexRows,
1181 }),
1182 "Failed to rebuild workspace tool index for GraphQL source",
1183 );
1184 }
1185
1186 return {
1187 protocol: "graphql",
1188 artifactId: artifactMeta.artifactId,
1189 sourceHash: extracted.schemaHash,
1190 toolCount: extracted.tools.length,
1191 namespace,
1192 refHintTableJson: null,
1193 artifactBatchCount: artifactMeta.created && options.stageArtifactWrites
1194 ? Math.ceil(extracted.tools.length / stagedArtifactBatchSize)
1195 : 0,
1196 };
1197 });
1198
1199const ingestMcpSource = (
1200 ctx: any,
1201 source: Source,
1202 options: IngestOptions,
1203): Effect.Effect<SourceIngestPrepared, SourceIngestError> =>
1204 Effect.gen(function* () {
1205 const credentialHeadersResult = yield* trySourceIngestPromise<{
1206 headers: Record<string, string>;
1207 }>(
1208 () =>
1209 ctx.runAction(runtimeInternal.control_plane.credentials.resolveSourceCredentialHeadersForIngest, {
1210 workspaceId: source.workspaceId,
1211 sourceId: source.id,
1212 sourceName: source.name,
1213 sourceEndpoint: source.endpoint,
1214 }),
1215 "Failed to resolve source credentials for MCP ingest",
1216 );
1217
1218 const headers = mergeHeaders(
1219 collectMcpHeadersFromSourceConfig(source),
1220 credentialHeadersResult.headers,
1221 );
1222
1223 const connection = yield* connectMcp(source, headers);
1224
1225 const listedResult = yield* Effect.tryPromise({
1226 try: () => connection.client.listTools(),
1227 catch: (cause) =>
1228 SourceIngestError.make({
1229 status: sourceIngestStatusFromCause(cause),
1230 message: `Failed to list MCP tools: ${formatError(cause)}`,
1231 }),
1232 }).pipe(
1233 Effect.ensuring(
1234 Effect.promise(() => connection.close().catch(() => undefined)),
1235 ),
1236 );
1237
1238 const listedTools = extractMcpListedToolRows(listedResult);
1239 const extracted = extractMcpTools(source, connection.transport, listedTools);
1240
1241 const artifactMeta = yield* trySourceIngestPromise<{
1242 artifactId: string;
1243 created: boolean;
1244 }>(
1245 () =>
1246 ctx.runMutation(runtimeInternal.control_plane.tool_registry.upsertArtifactMeta, {
1247 protocol: "mcp",
1248 contentHash: extracted.sourceHash,
1249 extractorVersion: mcpExtractorVersion,
1250 toolCount: extracted.tools.length,
1251 }),
1252 "Failed to upsert MCP artifact metadata",
1253 );
1254
1255 if (artifactMeta.created) {
1256 const artifactRows = extracted.tools.map((tool) => {
1257 const schemas = extractMcpSchemas(tool.invocationJson);
1258 return {
1259 toolId: tool.toolId,
1260 name: tool.name,
1261 description: tool.description,
1262 canonicalPath: tool.toolName,
1263 operationHash: tool.operationHash,
1264 invocationJson: tool.invocationJson,
1265 inputSchemaJson: schemas.inputSchemaJson,
1266 outputSchemaJson: schemas.outputSchemaJson,
1267 metadataJson: safeJsonStringify({
1268 toolName: tool.toolName,
1269 }),
1270 };
1271 });
1272
1273 if (options.stageArtifactWrites) {
1274 const serializedBatches = chunkArray(artifactRows, stagedArtifactBatchSize).map((batch) =>
1275 JSON.stringify(batch),
1276 );
1277
1278 yield* trySourceIngestPromise(
1279 () =>
1280 ctx.runMutation(
1281 runtimeInternal.control_plane.tool_registry.replaceSourceIngestArtifactBatches,
1282 {
1283 workspaceId: source.workspaceId,
1284 sourceId: source.id,
1285 artifactId: artifactMeta.artifactId,
1286 protocol: "mcp",
1287 batches: serializedBatches,
1288 },
1289 ),
1290 "Failed to stage MCP artifact tool batches",
1291 );
1292 } else {
1293 for (let index = 0; index < artifactRows.length; index += writeBatchSize) {
1294 const batch = artifactRows.slice(index, index + writeBatchSize);
1295 yield* trySourceIngestPromise(
1296 () =>
1297 ctx.runMutation(runtimeInternal.control_plane.tool_registry.putArtifactToolsBatch, {
1298 artifactId: artifactMeta.artifactId,
1299 protocol: "mcp",
1300 insertOnly: true,
1301 tools: batch,
1302 }),
1303 "Failed to write MCP artifact tools",
1304 );
1305 }
1306 }
1307 }
1308
1309 yield* trySourceIngestPromise(
1310 () =>
1311 ctx.runMutation(runtimeInternal.control_plane.tool_registry.bindSourceToArtifact, {
1312 workspaceId: source.workspaceId,
1313 sourceId: source.id,
1314 artifactId: artifactMeta.artifactId,
1315 }),
1316 "Failed to bind source to MCP artifact",
1317 );
1318
1319 const namespace = sourceNamespace(source);
1320 const indexRows = extracted.tools.map((tool) => {
1321 return {
1322 toolId: tool.toolId,
1323 protocol: "mcp",
1324 method: "post",
1325 path: sourceToolPath(source, tool.toolId),
1326 operationPath: null,
1327 name: tool.name,
1328 description: tool.description,
1329 searchText: normalizedSearchText(
1330 source.name,
1331 source.endpoint,
1332 namespace,
1333 tool.toolId,
1334 tool.name,
1335 tool.description,
1336 tool.toolName,
1337 ),
1338 operationHash: tool.operationHash,
1339 approvalMode: "auto",
1340 status: source.enabled ? "active" : "disabled",
1341 };
1342 });
1343
1344 if (options.rebuildIndex) {
1345 yield* trySourceIngestPromise(
1346 () =>
1347 ctx.runMutation(runtimeInternal.control_plane.tool_registry.replaceWorkspaceSourceToolIndex, {
1348 workspaceId: source.workspaceId,
1349 sourceId: source.id,
1350 sourceName: source.name,
1351 sourceKind: source.kind,
1352 artifactId: artifactMeta.artifactId,
1353 namespace,
1354 refHintTableJson: null,
1355 rows: indexRows,
1356 }),
1357 "Failed to rebuild workspace tool index for MCP source",
1358 );
1359 }
1360
1361 return {
1362 protocol: "mcp",
1363 artifactId: artifactMeta.artifactId,
1364 sourceHash: extracted.sourceHash,
1365 toolCount: extracted.tools.length,
1366 namespace,
1367 refHintTableJson: null,
1368 artifactBatchCount: artifactMeta.created && options.stageArtifactWrites
1369 ? Math.ceil(extracted.tools.length / stagedArtifactBatchSize)
1370 : 0,
1371 };
1372 });
1373
1374export const ingestSourceArtifact = internalAction({
1375 args: {
1376 workspaceId: v.string(),
1377 sourceId: v.string(),
1378 },
1379 handler: async (ctx, args): Promise<void> => {
1380 const source = await ctx.runQuery(runtimeInternal.control_plane.sources.getSourceForIngest, {
1381 sourceId: args.sourceId,
1382 });
1383
1384 if (!source || source.workspaceId !== args.workspaceId) {
1385 return;
1386 }
1387
1388 await ctx.runMutation(runtimeInternal.control_plane.sources.setSourceIngestState, {
1389 sourceId: source.id,
1390 status: "probing",
1391 lastError: null,
1392 });
1393
1394 const ingestEffect = source.kind === "openapi"
1395 ? ingestOpenApiSource(ctx, source)
1396 : source.kind === "graphql"
1397 ? ingestGraphqlSource(ctx, source, {
1398 rebuildIndex: true,
1399 stageArtifactWrites: false,
1400 })
1401 : source.kind === "mcp"
1402 ? ingestMcpSource(ctx, source, {
1403 rebuildIndex: true,
1404 stageArtifactWrites: false,
1405 })
1406 : Effect.fail(
1407 SourceIngestError.make({
1408 status: "error",
1409 message: `Source ingest for kind '${source.kind}' is not implemented yet`,
1410 }),
1411 );
1412
1413 const result = await Effect.runPromise(
1414 ingestEffect.pipe(
1415 Effect.match({
1416 onFailure: (error) => ({
1417 status: error.status,
1418 sourceHash: null as string | null,
1419 lastError: error.message,
1420 }),
1421 onSuccess: (prepared) => ({
1422 status: "connected" as const,
1423 sourceHash: prepared.sourceHash,
1424 lastError: null as string | null,
1425 }),
1426 }),
1427 ),
1428 );
1429
1430 await ctx.runMutation(runtimeInternal.control_plane.sources.setSourceIngestState, {
1431 sourceId: source.id,
1432 status: result.status,
1433 sourceHash: result.sourceHash,
1434 lastError: result.lastError,
1435 });
1436 },
1437});
apps/convex/convex/control_plane/organizations.ts+124−0
@@ -0,0 +1,124 @@
1import { type UpsertOrganizationPayload } from "@executor-v2/management-api";
2import {
3 OrganizationSchema,
4 type Organization,
5 type OrganizationMembership,
6} from "@executor-v2/schema";
7import { v } from "convex/values";
8import * as Schema from "effect/Schema";
9
10import { mutation, query } from "../_generated/server";
11
12const decodeOrganization = Schema.decodeUnknownSync(OrganizationSchema);
13
14const stripConvexSystemFields = (
15 value: Record<string, unknown>,
16): Record<string, unknown> => {
17 const { _id: _ignoredId, _creationTime: _ignoredCreationTime, ...rest } = value;
18 return rest;
19};
20
21const toOrganization = (document: Record<string, unknown>): Organization =>
22 decodeOrganization(stripConvexSystemFields(document));
23
24const organizationStatusValidator = v.union(
25 v.literal("active"),
26 v.literal("suspended"),
27 v.literal("archived"),
28);
29
30const sortOrganizations = (
31 organizations: ReadonlyArray<Organization>,
32): Array<Organization> =>
33 [...organizations].sort((left, right) => {
34 const leftName = left.name.toLowerCase();
35 const rightName = right.name.toLowerCase();
36
37 if (leftName === rightName) {
38 return left.id.localeCompare(right.id);
39 }
40
41 return leftName.localeCompare(rightName);
42 });
43
44export const listOrganizations = query({
45 args: {},
46 handler: async (ctx): Promise<Array<Organization>> => {
47 const rows = await ctx.db.query("organizations").collect();
48
49 return sortOrganizations(
50 rows.map((row) => toOrganization(row as unknown as Record<string, unknown>)),
51 );
52 },
53});
54
55export const upsertOrganization = mutation({
56 args: {
57 payload: v.object({
58 id: v.optional(v.string()),
59 slug: v.string(),
60 name: v.string(),
61 status: v.optional(organizationStatusValidator),
62 createdByAccountId: v.optional(v.union(v.string(), v.null())),
63 }),
64 },
65 handler: async (ctx, args): Promise<Organization> => {
66 const payload = args.payload as UpsertOrganizationPayload;
67 const now = Date.now();
68 const organizationId = payload.id ?? `org_${crypto.randomUUID()}`;
69
70 const existing = await ctx.db
71 .query("organizations")
72 .withIndex("by_domainId", (q) => q.eq("id", organizationId))
73 .unique();
74
75 const nextOrganization = decodeOrganization({
76 id: organizationId,
77 slug: payload.slug,
78 name: payload.name,
79 status: payload.status ?? existing?.status ?? "active",
80 createdByAccountId:
81 existing?.createdByAccountId
82 ?? payload.createdByAccountId
83 ?? null,
84 createdAt: existing?.createdAt ?? now,
85 updatedAt: now,
86 });
87
88 if (existing) {
89 await ctx.db.patch(existing._id, nextOrganization);
90 } else {
91 await ctx.db.insert("organizations", nextOrganization);
92
93 if (nextOrganization.createdByAccountId !== null) {
94 const existingMembership = await ctx.db
95 .query("organizationMemberships")
96 .withIndex("by_organizationId_accountId", (q) =>
97 q
98 .eq("organizationId", nextOrganization.id)
99 .eq("accountId", nextOrganization.createdByAccountId as string)
100 )
101 .first();
102
103 if (!existingMembership) {
104 const membership: OrganizationMembership = {
105 id: `org_member_${crypto.randomUUID()}` as OrganizationMembership["id"],
106 organizationId: nextOrganization.id,
107 accountId: nextOrganization.createdByAccountId,
108 role: "owner",
109 status: "active",
110 billable: false,
111 invitedByAccountId: null,
112 joinedAt: now,
113 createdAt: now,
114 updatedAt: now,
115 };
116
117 await ctx.db.insert("organizationMemberships", membership);
118 }
119 }
120 }
121
122 return nextOrganization;
123 },
124});
apps/convex/convex/control_plane/policies.ts+120−0
@@ -0,0 +1,120 @@
1import { type UpsertPolicyPayload } from "@executor-v2/management-api";
2import { PolicySchema, type Policy } from "@executor-v2/schema";
3import { v } from "convex/values";
4import * as Schema from "effect/Schema";
5
6import { mutation, query } from "../_generated/server";
7
8const decodePolicy = Schema.decodeUnknownSync(PolicySchema);
9
10const stripConvexSystemFields = (
11 value: Record<string, unknown>,
12): Record<string, unknown> => {
13 const { _id: _ignoredId, _creationTime: _ignoredCreationTime, ...rest } = value;
14 return rest;
15};
16
17const toPolicy = (document: Record<string, unknown>): Policy =>
18 decodePolicy(stripConvexSystemFields(document));
19
20const policyDecisionValidator = v.union(
21 v.literal("allow"),
22 v.literal("require_approval"),
23 v.literal("deny"),
24);
25
26const sortPolicies = (policies: ReadonlyArray<Policy>): Array<Policy> =>
27 [...policies].sort((left, right) => {
28 const leftPattern = left.toolPathPattern.toLowerCase();
29 const rightPattern = right.toolPathPattern.toLowerCase();
30
31 if (leftPattern === rightPattern) {
32 return left.id.localeCompare(right.id);
33 }
34
35 return leftPattern.localeCompare(rightPattern);
36 });
37
38export const listPolicies = query({
39 args: {
40 workspaceId: v.string(),
41 },
42 handler: async (ctx, args): Promise<Array<Policy>> => {
43 const rows = await ctx.db
44 .query("policies")
45 .withIndex("by_workspaceId", (q) => q.eq("workspaceId", args.workspaceId))
46 .collect();
47
48 return sortPolicies(
49 rows.map((row) => toPolicy(row as unknown as Record<string, unknown>)),
50 );
51 },
52});
53
54export const upsertPolicy = mutation({
55 args: {
56 workspaceId: v.string(),
57 payload: v.object({
58 id: v.optional(v.string()),
59 toolPathPattern: v.string(),
60 decision: policyDecisionValidator,
61 }),
62 },
63 handler: async (ctx, args): Promise<Policy> => {
64 const payload = args.payload as UpsertPolicyPayload;
65 const now = Date.now();
66 const policyId = payload.id ?? `pol_${crypto.randomUUID()}`;
67
68 const existing = await ctx.db
69 .query("policies")
70 .withIndex("by_domainId", (q) => q.eq("id", policyId))
71 .unique();
72
73 if (existing && existing.workspaceId !== args.workspaceId) {
74 throw new Error(`Policy not found: ${policyId}`);
75 }
76
77 const nextPolicy = decodePolicy({
78 id: policyId,
79 workspaceId: args.workspaceId,
80 toolPathPattern: payload.toolPathPattern,
81 decision: payload.decision,
82 createdAt: existing?.createdAt ?? now,
83 updatedAt: now,
84 });
85
86 if (existing) {
87 await ctx.db.patch(existing._id, nextPolicy);
88 } else {
89 await ctx.db.insert("policies", nextPolicy);
90 }
91
92 return nextPolicy;
93 },
94});
95
96export const removePolicy = mutation({
97 args: {
98 workspaceId: v.string(),
99 policyId: v.string(),
100 },
101 handler: async (
102 ctx,
103 args,
104 ): Promise<{
105 removed: boolean;
106 }> => {
107 const existing = await ctx.db
108 .query("policies")
109 .withIndex("by_domainId", (q) => q.eq("id", args.policyId))
110 .unique();
111
112 if (!existing || existing.workspaceId !== args.workspaceId) {
113 return { removed: false };
114 }
115
116 await ctx.db.delete(existing._id);
117
118 return { removed: true };
119 },
120});
apps/convex/convex/control_plane/service.ts+247−0
@@ -0,0 +1,247 @@
1import {
2 ControlPlaneService,
3 type ControlPlaneServiceShape,
4} from "@executor-v2/management-api";
5import * as Effect from "effect/Effect";
6
7import { api } from "../_generated/api";
8import type { ActionCtx } from "../_generated/server";
9import { toSourceStoreError } from "./errors";
10
11export const makeConvexControlPlaneService = (
12 ctx: ActionCtx,
13): ControlPlaneServiceShape =>
14 ControlPlaneService.of({
15 listSources: (workspaceId) =>
16 Effect.tryPromise({
17 try: () =>
18 ctx.runQuery(api.controlPlane.listSources, {
19 workspaceId,
20 }),
21 catch: (cause) => toSourceStoreError("controlPlane.listSources", cause),
22 }),
23 upsertSource: (input) =>
24 Effect.tryPromise({
25 try: () =>
26 ctx.runAction(api.controlPlane.upsertSource, {
27 workspaceId: input.workspaceId,
28 payload: input.payload,
29 }),
30 catch: (cause) => toSourceStoreError("controlPlane.upsertSource", cause),
31 }),
32 removeSource: (input) =>
33 Effect.tryPromise({
34 try: () =>
35 ctx.runMutation(api.controlPlane.removeSource, {
36 workspaceId: input.workspaceId,
37 sourceId: input.sourceId,
38 }),
39 catch: (cause) => toSourceStoreError("controlPlane.removeSource", cause),
40 }),
41 listCredentialBindings: (workspaceId) =>
42 Effect.tryPromise({
43 try: () =>
44 ctx.runQuery(api.controlPlane.listCredentialBindings, {
45 workspaceId,
46 }),
47 catch: (cause) =>
48 toSourceStoreError("controlPlane.listCredentialBindings", cause),
49 }),
50 upsertCredentialBinding: (input) =>
51 Effect.tryPromise({
52 try: () =>
53 ctx.runAction(api.controlPlane.upsertCredentialBinding, {
54 workspaceId: input.workspaceId,
55 payload: input.payload,
56 }),
57 catch: (cause) =>
58 toSourceStoreError("controlPlane.upsertCredentialBinding", cause),
59 }),
60 removeCredentialBinding: (input) =>
61 Effect.tryPromise({
62 try: () =>
63 ctx.runMutation(api.controlPlane.removeCredentialBinding, {
64 workspaceId: input.workspaceId,
65 credentialBindingId: input.credentialBindingId,
66 }),
67 catch: (cause) =>
68 toSourceStoreError("controlPlane.removeCredentialBinding", cause),
69 }),
70 listPolicies: (workspaceId) =>
71 Effect.tryPromise({
72 try: () =>
73 ctx.runQuery(api.controlPlane.listPolicies, {
74 workspaceId,
75 }),
76 catch: (cause) => toSourceStoreError("controlPlane.listPolicies", cause),
77 }),
78 upsertPolicy: (input) =>
79 Effect.tryPromise({
80 try: () =>
81 ctx.runMutation(api.controlPlane.upsertPolicy, {
82 workspaceId: input.workspaceId,
83 payload: input.payload,
84 }),
85 catch: (cause) => toSourceStoreError("controlPlane.upsertPolicy", cause),
86 }),
87 removePolicy: (input) =>
88 Effect.tryPromise({
89 try: () =>
90 ctx.runMutation(api.controlPlane.removePolicy, {
91 workspaceId: input.workspaceId,
92 policyId: input.policyId,
93 }),
94 catch: (cause) => toSourceStoreError("controlPlane.removePolicy", cause),
95 }),
96 listOrganizations: () =>
97 Effect.tryPromise({
98 try: () => ctx.runQuery(api.controlPlane.listOrganizations, {}),
99 catch: (cause) => toSourceStoreError("controlPlane.listOrganizations", cause),
100 }),
101 upsertOrganization: (input) =>
102 Effect.tryPromise({
103 try: () =>
104 ctx.runMutation(api.controlPlane.upsertOrganization, {
105 payload: input.payload,
106 }),
107 catch: (cause) => toSourceStoreError("controlPlane.upsertOrganization", cause),
108 }),
109 listWorkspaces: () =>
110 Effect.tryPromise({
111 try: () => ctx.runQuery(api.controlPlane.listWorkspaces, {}),
112 catch: (cause) => toSourceStoreError("controlPlane.listWorkspaces", cause),
113 }),
114 upsertWorkspace: (input) =>
115 Effect.tryPromise({
116 try: () =>
117 ctx.runMutation(api.controlPlane.upsertWorkspace, {
118 payload: input.payload,
119 }),
120 catch: (cause) => toSourceStoreError("controlPlane.upsertWorkspace", cause),
121 }),
122 listWorkspaceTools: (workspaceId) =>
123 Effect.tryPromise({
124 try: () =>
125 ctx.runQuery(api.controlPlane.listWorkspaceTools, {
126 workspaceId,
127 }),
128 catch: (cause) => toSourceStoreError("controlPlane.listWorkspaceTools", cause),
129 }),
130 listSourceTools: (input) =>
131 Effect.tryPromise({
132 try: () =>
133 ctx.runQuery(api.controlPlane.listSourceTools, {
134 workspaceId: input.workspaceId,
135 sourceId: input.sourceId,
136 }),
137 catch: (cause) => toSourceStoreError("controlPlane.listSourceTools", cause),
138 }),
139 getToolDetail: (input) =>
140 Effect.tryPromise({
141 try: () =>
142 ctx.runQuery(api.controlPlane.getToolDetail, {
143 workspaceId: input.workspaceId,
144 sourceId: input.sourceId,
145 operationHash: input.operationHash,
146 }),
147 catch: (cause) => toSourceStoreError("controlPlane.getToolDetail", cause),
148 }),
149 listStorageInstances: (workspaceId) =>
150 Effect.tryPromise({
151 try: () =>
152 ctx.runQuery(api.controlPlane.listStorageInstances, {
153 workspaceId,
154 }),
155 catch: (cause) =>
156 toSourceStoreError("controlPlane.listStorageInstances", cause),
157 }),
158 openStorageInstance: (input) =>
159 Effect.tryPromise({
160 try: () =>
161 ctx.runMutation(api.controlPlane.openStorageInstance, {
162 workspaceId: input.workspaceId,
163 payload: input.payload,
164 }),
165 catch: (cause) =>
166 toSourceStoreError("controlPlane.openStorageInstance", cause),
167 }),
168 closeStorageInstance: (input) =>
169 Effect.tryPromise({
170 try: () =>
171 ctx.runMutation(api.controlPlane.closeStorageInstance, {
172 workspaceId: input.workspaceId,
173 storageInstanceId: input.storageInstanceId,
174 }),
175 catch: (cause) =>
176 toSourceStoreError("controlPlane.closeStorageInstance", cause),
177 }),
178 removeStorageInstance: (input) =>
179 Effect.tryPromise({
180 try: () =>
181 ctx.runMutation(api.controlPlane.removeStorageInstance, {
182 workspaceId: input.workspaceId,
183 storageInstanceId: input.storageInstanceId,
184 }),
185 catch: (cause) =>
186 toSourceStoreError("controlPlane.removeStorageInstance", cause),
187 }),
188 listStorageDirectory: (input) =>
189 Effect.tryPromise({
190 try: () =>
191 ctx.runQuery(api.controlPlane.listStorageDirectory, {
192 workspaceId: input.workspaceId,
193 storageInstanceId: input.storageInstanceId,
194 payload: input.payload,
195 }),
196 catch: (cause) =>
197 toSourceStoreError("controlPlane.listStorageDirectory", cause),
198 }),
199 readStorageFile: (input) =>
200 Effect.tryPromise({
201 try: () =>
202 ctx.runQuery(api.controlPlane.readStorageFile, {
203 workspaceId: input.workspaceId,
204 storageInstanceId: input.storageInstanceId,
205 payload: input.payload,
206 }),
207 catch: (cause) => toSourceStoreError("controlPlane.readStorageFile", cause),
208 }),
209 listStorageKv: (input) =>
210 Effect.tryPromise({
211 try: () =>
212 ctx.runQuery(api.controlPlane.listStorageKv, {
213 workspaceId: input.workspaceId,
214 storageInstanceId: input.storageInstanceId,
215 payload: input.payload,
216 }),
217 catch: (cause) => toSourceStoreError("controlPlane.listStorageKv", cause),
218 }),
219 queryStorageSql: (input) =>
220 Effect.tryPromise({
221 try: () =>
222 ctx.runMutation(api.controlPlane.queryStorageSql, {
223 workspaceId: input.workspaceId,
224 storageInstanceId: input.storageInstanceId,
225 payload: input.payload,
226 }),
227 catch: (cause) => toSourceStoreError("controlPlane.queryStorageSql", cause),
228 }),
229 listApprovals: (workspaceId) =>
230 Effect.tryPromise({
231 try: () =>
232 ctx.runQuery(api.controlPlane.listApprovals, {
233 workspaceId,
234 }),
235 catch: (cause) => toSourceStoreError("controlPlane.listApprovals", cause),
236 }),
237 resolveApproval: (input) =>
238 Effect.tryPromise({
239 try: () =>
240 ctx.runMutation(api.controlPlane.resolveApproval, {
241 workspaceId: input.workspaceId,
242 approvalId: input.approvalId,
243 payload: input.payload,
244 }),
245 catch: (cause) => toSourceStoreError("controlPlane.resolveApproval", cause),
246 }),
247 });
apps/convex/convex/control_plane/sources.ts+239−0
@@ -0,0 +1,239 @@
1import { type UpsertSourcePayload } from "@executor-v2/management-api";
2import { SourceSchema, type Source } from "@executor-v2/schema";
3import { v } from "convex/values";
4import * as Schema from "effect/Schema";
5
6import { internal } from "../_generated/api";
7import { action, internalQuery, internalMutation, mutation, query } from "../_generated/server";
8
9const runtimeInternal = internal as any;
10
11const decodeSource = Schema.decodeUnknownSync(SourceSchema);
12
13const sourceStoreKey = (source: Source): string => `${source.workspaceId}:${source.id}`;
14
15const sortSources = (sources: ReadonlyArray<Source>): Array<Source> =>
16 [...sources].sort((left, right) => {
17 const leftName = left.name.toLowerCase();
18 const rightName = right.name.toLowerCase();
19
20 if (leftName === rightName) {
21 return sourceStoreKey(left).localeCompare(sourceStoreKey(right));
22 }
23
24 return leftName.localeCompare(rightName);
25 });
26
27const toSource = (document: Record<string, unknown>): Source => {
28 const { _id: _ignoredId, _creationTime: _ignoredCreationTime, ...source } = document;
29 return decodeSource(source);
30};
31
32const sourceKindValidator = v.union(
33 v.literal("mcp"),
34 v.literal("openapi"),
35 v.literal("graphql"),
36 v.literal("internal"),
37);
38
39const sourceStatusValidator = v.union(
40 v.literal("draft"),
41 v.literal("probing"),
42 v.literal("auth_required"),
43 v.literal("connected"),
44 v.literal("error"),
45);
46
47export const listSources = query({
48 args: {
49 workspaceId: v.string(),
50 },
51 handler: async (ctx, args): Promise<Array<Source>> => {
52 const documents = await ctx.db
53 .query("sources")
54 .withIndex("by_workspaceId", (q) => q.eq("workspaceId", args.workspaceId))
55 .collect();
56
57 return sortSources(
58 documents.map((document) =>
59 toSource(document as unknown as Record<string, unknown>),
60 ),
61 );
62 },
63});
64
65export const upsertSourceRecord = internalMutation({
66 args: {
67 workspaceId: v.string(),
68 payload: v.object({
69 id: v.optional(v.string()),
70 name: v.string(),
71 kind: sourceKindValidator,
72 endpoint: v.string(),
73 status: v.optional(sourceStatusValidator),
74 enabled: v.optional(v.boolean()),
75 configJson: v.optional(v.string()),
76 sourceHash: v.optional(v.union(v.string(), v.null())),
77 lastError: v.optional(v.union(v.string(), v.null())),
78 }),
79 },
80 handler: async (ctx, args): Promise<Source> => {
81 const now = Date.now();
82 const sourceId = args.payload.id ?? `src_${crypto.randomUUID()}`;
83
84 const existing = await ctx.db
85 .query("sources")
86 .withIndex("by_domainId", (q) => q.eq("id", sourceId))
87 .unique();
88
89 const existingInWorkspace =
90 existing && existing.workspaceId === args.workspaceId ? existing : null;
91
92 const payload = args.payload as UpsertSourcePayload;
93
94 const source = decodeSource({
95 id: sourceId,
96 workspaceId: args.workspaceId,
97 name: payload.name,
98 kind: payload.kind,
99 endpoint: payload.endpoint,
100 status: payload.status ?? "draft",
101 enabled: payload.enabled ?? true,
102 configJson: payload.configJson ?? "{}",
103 sourceHash: payload.sourceHash ?? null,
104 lastError: payload.lastError ?? null,
105 createdAt: existingInWorkspace?.createdAt ?? now,
106 updatedAt: now,
107 });
108
109 if (existingInWorkspace) {
110 await ctx.db.patch(existingInWorkspace._id, source);
111 } else {
112 await ctx.db.insert("sources", source);
113 }
114
115 return source;
116 },
117});
118
119export const upsertSource = action({
120 args: {
121 workspaceId: v.string(),
122 payload: v.object({
123 id: v.optional(v.string()),
124 name: v.string(),
125 kind: sourceKindValidator,
126 endpoint: v.string(),
127 status: v.optional(sourceStatusValidator),
128 enabled: v.optional(v.boolean()),
129 configJson: v.optional(v.string()),
130 sourceHash: v.optional(v.union(v.string(), v.null())),
131 lastError: v.optional(v.union(v.string(), v.null())),
132 }),
133 },
134 handler: async (ctx, args): Promise<Source> => {
135 const shouldIngest = args.payload.status !== "draft";
136 const source = await ctx.runMutation(runtimeInternal.control_plane.sources.upsertSourceRecord, {
137 workspaceId: args.workspaceId,
138 payload: {
139 ...args.payload,
140 status: args.payload.status ?? (shouldIngest ? "probing" : "draft"),
141 },
142 });
143
144 if (shouldIngest && source.kind !== "internal") {
145 if (source.kind === "openapi") {
146 await ctx.runAction(runtimeInternal.control_plane.openapi_ingest.ingestSourceArtifact, {
147 workspaceId: source.workspaceId,
148 sourceId: source.id,
149 });
150 } else {
151 await ctx.scheduler.runAfter(
152 0,
153 runtimeInternal.control_plane.openapi_ingest.ingestSourceArtifact,
154 {
155 workspaceId: source.workspaceId,
156 sourceId: source.id,
157 },
158 );
159 }
160 }
161
162 return source;
163 },
164});
165
166export const getSourceForIngest = internalQuery({
167 args: {
168 sourceId: v.string(),
169 },
170 handler: async (ctx, args): Promise<Source | null> => {
171 const sourceRow = await ctx.db
172 .query("sources")
173 .withIndex("by_domainId", (q) => q.eq("id", args.sourceId))
174 .unique();
175
176 if (!sourceRow) {
177 return null;
178 }
179
180 return toSource(sourceRow as unknown as Record<string, unknown>);
181 },
182});
183
184export const setSourceIngestState = internalMutation({
185 args: {
186 sourceId: v.string(),
187 status: sourceStatusValidator,
188 sourceHash: v.optional(v.union(v.string(), v.null())),
189 lastError: v.optional(v.union(v.string(), v.null())),
190 },
191 handler: async (ctx, args): Promise<void> => {
192 const sourceRow = await ctx.db
193 .query("sources")
194 .withIndex("by_domainId", (q) => q.eq("id", args.sourceId))
195 .unique();
196
197 if (!sourceRow) {
198 return;
199 }
200
201 await ctx.db.patch(sourceRow._id, {
202 status: args.status,
203 sourceHash: args.sourceHash !== undefined ? args.sourceHash : sourceRow.sourceHash,
204 lastError: args.lastError !== undefined ? args.lastError : sourceRow.lastError,
205 updatedAt: Date.now(),
206 });
207 },
208});
209
210export const removeSource = mutation({
211 args: {
212 workspaceId: v.string(),
213 sourceId: v.string(),
214 },
215 handler: async (
216 ctx,
217 args,
218 ): Promise<{
219 removed: boolean;
220 }> => {
221 const existing = await ctx.db
222 .query("sources")
223 .withIndex("by_domainId", (q) => q.eq("id", args.sourceId))
224 .unique();
225
226 if (!existing || existing.workspaceId !== args.workspaceId) {
227 return { removed: false };
228 }
229
230 await ctx.runMutation(runtimeInternal.control_plane.tool_registry.removeSourceBindingsAndIndex, {
231 workspaceId: args.workspaceId,
232 sourceId: args.sourceId,
233 });
234
235 await ctx.db.delete(existing._id);
236
237 return { removed: true };
238 },
239});
apps/convex/convex/control_plane/storage.ts+1069−0
@@ -0,0 +1,1069 @@
1import {
2 type ListStorageDirectoryResult,
3 type ListStorageKvResult,
4 type OpenStorageInstancePayload,
5 type QueryStorageSqlResult,
6 type ReadStorageFileResult,
7} from "@executor-v2/management-api";
8import { StorageInstanceSchema, type StorageInstance } from "@executor-v2/schema";
9import { v } from "convex/values";
10import * as Schema from "effect/Schema";
11
12import {
13 internalMutation,
14 mutation,
15 query,
16 type MutationCtx,
17 type QueryCtx,
18} from "../_generated/server";
19
20const decodeStorageInstance = Schema.decodeUnknownSync(StorageInstanceSchema);
21
22const StorageFileEntrySchema = Schema.Struct({
23 id: Schema.String,
24 storageInstanceId: Schema.String,
25 path: Schema.String,
26 contentBase64: Schema.String,
27 sizeBytes: Schema.Number,
28 updatedAt: Schema.Number,
29});
30
31type StorageFileEntry = typeof StorageFileEntrySchema.Type;
32const decodeStorageFileEntry = Schema.decodeUnknownSync(StorageFileEntrySchema);
33
34const StorageKvEntrySchema = Schema.Struct({
35 id: Schema.String,
36 storageInstanceId: Schema.String,
37 key: Schema.String,
38 valueJson: Schema.String,
39 updatedAt: Schema.Number,
40});
41
42type StorageKvEntry = typeof StorageKvEntrySchema.Type;
43const decodeStorageKvEntry = Schema.decodeUnknownSync(StorageKvEntrySchema);
44
45const StorageSqlKvEntrySchema = Schema.Struct({
46 id: Schema.String,
47 storageInstanceId: Schema.String,
48 key: Schema.String,
49 value: Schema.String,
50 updatedAt: Schema.Number,
51});
52
53type StorageSqlKvEntry = typeof StorageSqlKvEntrySchema.Type;
54const decodeStorageSqlKvEntry = Schema.decodeUnknownSync(StorageSqlKvEntrySchema);
55
56const DEFAULT_KV_LIMIT = 100;
57const MAX_KV_LIMIT = 1000;
58const DEFAULT_SQL_MAX_ROWS = 200;
59const MAX_SQL_MAX_ROWS = 5000;
60
61const stripConvexSystemFields = (
62 value: Record<string, unknown>,
63): Record<string, unknown> => {
64 const { _id: _ignoredId, _creationTime: _ignoredCreationTime, ...rest } = value;
65 return rest;
66};
67
68const toStorageInstance = (document: Record<string, unknown>): StorageInstance =>
69 decodeStorageInstance(stripConvexSystemFields(document));
70
71const toStorageFileEntry = (document: Record<string, unknown>): StorageFileEntry =>
72 decodeStorageFileEntry(stripConvexSystemFields(document));
73
74const toStorageKvEntry = (document: Record<string, unknown>): StorageKvEntry =>
75 decodeStorageKvEntry(stripConvexSystemFields(document));
76
77const toStorageSqlKvEntry = (document: Record<string, unknown>): StorageSqlKvEntry =>
78 decodeStorageSqlKvEntry(stripConvexSystemFields(document));
79
80const storageScopeTypeValidator = v.union(
81 v.literal("scratch"),
82 v.literal("account"),
83 v.literal("workspace"),
84 v.literal("organization"),
85);
86
87const storageDurabilityValidator = v.union(
88 v.literal("ephemeral"),
89 v.literal("durable"),
90);
91
92const storageProviderValidator = v.union(
93 v.literal("agentfs-local"),
94 v.literal("agentfs-cloudflare"),
95);
96
97const readStorageEncodingValidator = v.union(
98 v.literal("utf8"),
99 v.literal("base64"),
100);
101
102const sortStorageInstances = (
103 storageInstances: ReadonlyArray<StorageInstance>,
104): Array<StorageInstance> =>
105 [...storageInstances].sort((left, right) => {
106 if (left.updatedAt !== right.updatedAt) {
107 return right.updatedAt - left.updatedAt;
108 }
109
110 return left.id.localeCompare(right.id);
111 });
112
113const resolveWorkspaceOrganizationId = async (
114 ctx: QueryCtx | MutationCtx,
115 workspaceId: string,
116): Promise<string> => {
117 const workspace = await ctx.db
118 .query("workspaces")
119 .withIndex("by_domainId", (q) => q.eq("id", workspaceId))
120 .unique();
121
122 if (!workspace) {
123 throw new Error(`Workspace not found: ${workspaceId}`);
124 }
125
126 return workspace.organizationId;
127};
128
129const canAccessStorageInstance = (
130 storageInstance: StorageInstance,
131 input: {
132 workspaceId: string;
133 organizationId: string;
134 },
135): boolean =>
136 storageInstance.workspaceId === input.workspaceId
137 || (
138 storageInstance.workspaceId === null
139 && storageInstance.organizationId === input.organizationId
140 );
141
142const normalizeStoragePath = (pathValue: string): string => {
143 const trimmed = pathValue.trim().replaceAll("\\", "/");
144 const prefixed = trimmed.length > 0
145 ? (trimmed.startsWith("/") ? trimmed : `/${trimmed}`)
146 : "/";
147
148 const parts = prefixed.split("/");
149 const normalized: Array<string> = [];
150
151 for (const part of parts) {
152 if (part.length === 0 || part === ".") {
153 continue;
154 }
155
156 if (part === "..") {
157 if (normalized.length === 0) {
158 throw new Error("Path escapes storage root");
159 }
160 normalized.pop();
161 continue;
162 }
163
164 normalized.push(part);
165 }
166
167 if (normalized.length === 0) {
168 return "/";
169 }
170
171 return `/${normalized.join("/")}`;
172};
173
174const encodeUtf8Base64 = (value: string): string => {
175 if (typeof Buffer !== "undefined") {
176 return Buffer.from(value, "utf8").toString("base64");
177 }
178
179 const bytes = new TextEncoder().encode(value);
180 let binary = "";
181 for (const byte of bytes) {
182 binary += String.fromCharCode(byte);
183 }
184 return btoa(binary);
185};
186
187const decodeBase64Utf8 = (value: string): string => {
188 if (typeof Buffer !== "undefined") {
189 return Buffer.from(value, "base64").toString("utf8");
190 }
191
192 const binary = atob(value);
193 const bytes = Uint8Array.from(binary, (char) => char.charCodeAt(0));
194 return new TextDecoder().decode(bytes);
195};
196
197const parseJsonOrString = (value: string): unknown => {
198 try {
199 return JSON.parse(value) as unknown;
200 } catch {
201 return value;
202 }
203};
204
205const resolveAccessibleStorageInstance = async (
206 ctx: QueryCtx | MutationCtx,
207 input: {
208 workspaceId: string;
209 storageInstanceId: string;
210 },
211): Promise<StorageInstance | null> => {
212 const organizationId = await resolveWorkspaceOrganizationId(ctx, input.workspaceId);
213 const storageInstanceRow = await ctx.db
214 .query("storageInstances")
215 .withIndex("by_domainId", (q) => q.eq("id", input.storageInstanceId))
216 .unique();
217
218 if (!storageInstanceRow) {
219 return null;
220 }
221
222 const storageInstance = toStorageInstance(
223 storageInstanceRow as unknown as Record<string, unknown>,
224 );
225
226 if (
227 !canAccessStorageInstance(storageInstance, {
228 workspaceId: input.workspaceId,
229 organizationId,
230 })
231 ) {
232 return null;
233 }
234
235 return storageInstance;
236};
237
238export const upsertStorageFileEntry = internalMutation({
239 args: {
240 workspaceId: v.string(),
241 storageInstanceId: v.string(),
242 payload: v.object({
243 path: v.string(),
244 content: v.string(),
245 }),
246 },
247 handler: async (ctx, args): Promise<StorageFileEntry> => {
248 const storageInstance = await resolveAccessibleStorageInstance(ctx, {
249 workspaceId: args.workspaceId,
250 storageInstanceId: args.storageInstanceId,
251 });
252
253 if (!storageInstance) {
254 throw new Error(`Storage instance not found: ${args.storageInstanceId}`);
255 }
256
257 const normalizedPath = normalizeStoragePath(args.payload.path);
258 const now = Date.now();
259 const contentBase64 = encodeUtf8Base64(args.payload.content);
260 const sizeBytes = args.payload.content.length;
261
262 const existingRow = await ctx.db
263 .query("storageFileEntries")
264 .withIndex("by_storageInstanceId_path", (q) =>
265 q.eq("storageInstanceId", args.storageInstanceId).eq("path", normalizedPath)
266 )
267 .unique();
268
269 const nextEntry = decodeStorageFileEntry({
270 id:
271 (existingRow
272 ? toStorageFileEntry(existingRow as unknown as Record<string, unknown>).id
273 : `storage_file_${crypto.randomUUID()}`),
274 storageInstanceId: args.storageInstanceId,
275 path: normalizedPath,
276 contentBase64,
277 sizeBytes,
278 updatedAt: now,
279 });
280
281 if (existingRow) {
282 await ctx.db.patch(existingRow._id, nextEntry);
283 } else {
284 await ctx.db.insert("storageFileEntries", nextEntry);
285 }
286
287 return nextEntry;
288 },
289});
290
291export const upsertStorageKvEntry = internalMutation({
292 args: {
293 workspaceId: v.string(),
294 storageInstanceId: v.string(),
295 payload: v.object({
296 key: v.string(),
297 valueJson: v.string(),
298 }),
299 },
300 handler: async (ctx, args): Promise<StorageKvEntry> => {
301 const storageInstance = await resolveAccessibleStorageInstance(ctx, {
302 workspaceId: args.workspaceId,
303 storageInstanceId: args.storageInstanceId,
304 });
305
306 if (!storageInstance) {
307 throw new Error(`Storage instance not found: ${args.storageInstanceId}`);
308 }
309
310 const now = Date.now();
311
312 const existingRow = await ctx.db
313 .query("storageKvEntries")
314 .withIndex("by_storageInstanceId_key", (q) =>
315 q.eq("storageInstanceId", args.storageInstanceId).eq("key", args.payload.key)
316 )
317 .unique();
318
319 const nextEntry = decodeStorageKvEntry({
320 id:
321 (existingRow
322 ? toStorageKvEntry(existingRow as unknown as Record<string, unknown>).id
323 : `storage_kv_${crypto.randomUUID()}`),
324 storageInstanceId: args.storageInstanceId,
325 key: args.payload.key,
326 valueJson: args.payload.valueJson,
327 updatedAt: now,
328 });
329
330 if (existingRow) {
331 await ctx.db.patch(existingRow._id, nextEntry);
332 } else {
333 await ctx.db.insert("storageKvEntries", nextEntry);
334 }
335
336 return nextEntry;
337 },
338});
339
340const decodeSqlStringLiteral = (value: string): string => value.replaceAll("''", "'");
341
342const parseSqlWhere = (
343 whereClause: string | undefined,
344): ((key: string) => boolean) => {
345 if (whereClause === undefined) {
346 return () => true;
347 }
348
349 const equalsMatch = /^key\s*=\s*'((?:''|[^'])*)'$/i.exec(whereClause.trim());
350 if (equalsMatch) {
351 const expectedKey = decodeSqlStringLiteral(equalsMatch[1] ?? "");
352 return (key) => key === expectedKey;
353 }
354
355 const likeMatch = /^key\s+like\s+'((?:''|[^'])*)'$/i.exec(whereClause.trim());
356 if (likeMatch) {
357 const pattern = decodeSqlStringLiteral(likeMatch[1] ?? "");
358 if (!pattern.endsWith("%") || pattern.slice(0, -1).includes("%")) {
359 throw new Error("Only trailing % LIKE patterns are supported");
360 }
361
362 const prefix = pattern.slice(0, -1);
363 return (key) => key.startsWith(prefix);
364 }
365
366 throw new Error("Unsupported SQL WHERE clause for kv_store");
367};
368
369const parseSelectColumns = (columnsClause: string): Array<"key" | "value"> => {
370 const normalized = columnsClause.trim().toLowerCase();
371 if (normalized === "*") {
372 return ["key", "value"];
373 }
374
375 const columns = normalized
376 .split(",")
377 .map((column) => column.trim())
378 .filter((column) => column.length > 0);
379
380 if (columns.length === 0) {
381 throw new Error("SQL SELECT columns are required");
382 }
383
384 const parsedColumns: Array<"key" | "value"> = [];
385
386 for (const column of columns) {
387 if (column !== "key" && column !== "value") {
388 throw new Error("Only key/value columns are supported for kv_store");
389 }
390
391 if (!parsedColumns.includes(column)) {
392 parsedColumns.push(column);
393 }
394 }
395
396 return parsedColumns;
397};
398
399type SqlWrite =
400 | {
401 type: "upsert";
402 key: string;
403 value: string;
404 insertOnly: boolean;
405 }
406 | {
407 type: "delete";
408 key: string;
409 };
410
411const executeSqlForStorage = (
412 sqlText: string,
413 sqlRows: ReadonlyArray<StorageSqlKvEntry>,
414 maxRows: number,
415): {
416 result: QueryStorageSqlResult;
417 writes: Array<SqlWrite>;
418} => {
419 const trimmed = sqlText.trim();
420
421 if (/^create\s+table\s+if\s+not\s+exists\s+kv_store\b/i.test(trimmed)) {
422 return {
423 result: {
424 rows: [],
425 columns: [],
426 rowCount: 0,
427 },
428 writes: [],
429 };
430 }
431
432 if (/^(begin|commit|rollback)\b/i.test(trimmed)) {
433 return {
434 result: {
435 rows: [],
436 columns: [],
437 rowCount: 0,
438 },
439 writes: [],
440 };
441 }
442
443 const sortedRows = [...sqlRows].sort((left, right) => left.key.localeCompare(right.key));
444
445 const selectMatch = /^select\s+(.+?)\s+from\s+kv_store(?:\s+where\s+(.+?))?(?:\s+limit\s+(\d+))?\s*;?$/i.exec(trimmed);
446 if (selectMatch) {
447 const columns = parseSelectColumns(selectMatch[1] ?? "");
448 const where = parseSqlWhere(selectMatch[2]);
449 const sqlLimit =
450 selectMatch[3] !== undefined
451 ? Math.max(1, Math.min(maxRows, Number.parseInt(selectMatch[3], 10)))
452 : maxRows;
453
454 const rows = sortedRows
455 .filter((row) => where(row.key))
456 .slice(0, sqlLimit)
457 .map((row) => {
458 const resultRow: Record<string, unknown> = {};
459
460 for (const column of columns) {
461 if (column === "key") {
462 resultRow.key = row.key;
463 } else {
464 resultRow.value = row.value;
465 }
466 }
467
468 return resultRow;
469 });
470
471 return {
472 result: {
473 rows,
474 columns,
475 rowCount: rows.length,
476 },
477 writes: [],
478 };
479 }
480
481 const insertMatch = /^insert\s+into\s+kv_store\s*\(\s*key\s*,\s*value\s*\)\s*values\s*\(\s*'((?:''|[^'])*)'\s*,\s*'((?:''|[^'])*)'\s*\)\s*;?$/i.exec(trimmed);
482 if (insertMatch) {
483 return {
484 result: {
485 rows: [],
486 columns: [],
487 rowCount: 0,
488 },
489 writes: [{
490 type: "upsert",
491 key: decodeSqlStringLiteral(insertMatch[1] ?? ""),
492 value: decodeSqlStringLiteral(insertMatch[2] ?? ""),
493 insertOnly: true,
494 }],
495 };
496 }
497
498 const replaceMatch = /^replace\s+into\s+kv_store\s*\(\s*key\s*,\s*value\s*\)\s*values\s*\(\s*'((?:''|[^'])*)'\s*,\s*'((?:''|[^'])*)'\s*\)\s*;?$/i.exec(trimmed);
499 if (replaceMatch) {
500 return {
501 result: {
502 rows: [],
503 columns: [],
504 rowCount: 0,
505 },
506 writes: [{
507 type: "upsert",
508 key: decodeSqlStringLiteral(replaceMatch[1] ?? ""),
509 value: decodeSqlStringLiteral(replaceMatch[2] ?? ""),
510 insertOnly: false,
511 }],
512 };
513 }
514
515 const updateMatch = /^update\s+kv_store\s+set\s+value\s*=\s*'((?:''|[^'])*)'\s+where\s+key\s*=\s*'((?:''|[^'])*)'\s*;?$/i.exec(trimmed);
516 if (updateMatch) {
517 return {
518 result: {
519 rows: [],
520 columns: [],
521 rowCount: 0,
522 },
523 writes: [{
524 type: "upsert",
525 key: decodeSqlStringLiteral(updateMatch[2] ?? ""),
526 value: decodeSqlStringLiteral(updateMatch[1] ?? ""),
527 insertOnly: false,
528 }],
529 };
530 }
531
532 const deleteMatch = /^delete\s+from\s+kv_store\s+where\s+key\s*=\s*'((?:''|[^'])*)'\s*;?$/i.exec(trimmed);
533 if (deleteMatch) {
534 return {
535 result: {
536 rows: [],
537 columns: [],
538 rowCount: 0,
539 },
540 writes: [{
541 type: "delete",
542 key: decodeSqlStringLiteral(deleteMatch[1] ?? ""),
543 }],
544 };
545 }
546
547 throw new Error("Unsupported SQL statement for Convex storage inspector");
548};
549
550export const listStorageInstances = query({
551 args: {
552 workspaceId: v.string(),
553 },
554 handler: async (ctx, args): Promise<Array<StorageInstance>> => {
555 const organizationId = await resolveWorkspaceOrganizationId(ctx, args.workspaceId);
556
557 const workspaceRows = await ctx.db
558 .query("storageInstances")
559 .withIndex("by_workspaceId", (q) => q.eq("workspaceId", args.workspaceId))
560 .collect();
561
562 const organizationRows = await ctx.db
563 .query("storageInstances")
564 .withIndex("by_organizationId", (q) => q.eq("organizationId", organizationId))
565 .collect();
566
567 const storageInstances = [...workspaceRows, ...organizationRows]
568 .map((row) =>
569 toStorageInstance(row as unknown as Record<string, unknown>),
570 )
571 .filter((storageInstance) =>
572 canAccessStorageInstance(storageInstance, {
573 workspaceId: args.workspaceId,
574 organizationId,
575 })
576 );
577
578 const uniqueStorageInstances = Array.from(
579 new Map(storageInstances.map((storageInstance) => [storageInstance.id, storageInstance]))
580 .values(),
581 );
582
583 return sortStorageInstances(uniqueStorageInstances);
584 },
585});
586
587export const openStorageInstance = mutation({
588 args: {
589 workspaceId: v.string(),
590 payload: v.object({
591 scopeType: storageScopeTypeValidator,
592 durability: storageDurabilityValidator,
593 provider: v.optional(storageProviderValidator),
594 purpose: v.optional(v.string()),
595 ttlHours: v.optional(v.number()),
596 accountId: v.optional(v.string()),
597 sessionId: v.optional(v.string()),
598 }),
599 },
600 handler: async (ctx, args): Promise<StorageInstance> => {
601 const payload = args.payload as OpenStorageInstancePayload;
602
603 if (payload.scopeType === "account" && payload.accountId === undefined) {
604 throw new Error("Account scope storage requires accountId");
605 }
606
607 const organizationId = await resolveWorkspaceOrganizationId(ctx, args.workspaceId);
608 const now = Date.now();
609 const storageInstanceId = `storage_${crypto.randomUUID()}`;
610 const ttlHours =
611 payload.ttlHours !== undefined && Number.isFinite(payload.ttlHours)
612 ? Math.max(1, Math.floor(payload.ttlHours))
613 : 24;
614
615 const nextStorageInstance = decodeStorageInstance({
616 id: storageInstanceId,
617 scopeType: payload.scopeType,
618 durability: payload.durability,
619 status: "active",
620 provider: payload.provider ?? "agentfs-local",
621 backendKey: `convex:${storageInstanceId}`,
622 organizationId,
623 workspaceId:
624 payload.scopeType === "workspace" || payload.scopeType === "scratch"
625 ? args.workspaceId
626 : null,
627 accountId: payload.scopeType === "account" ? (payload.accountId ?? null) : null,
628 createdByAccountId: payload.accountId ?? null,
629 purpose:
630 payload.purpose !== undefined && payload.purpose.trim().length > 0
631 ? payload.purpose.trim()
632 : null,
633 sizeBytes: null,
634 fileCount: null,
635 createdAt: now,
636 updatedAt: now,
637 lastSeenAt: now,
638 closedAt: null,
639 expiresAt:
640 payload.durability === "ephemeral"
641 ? now + ttlHours * 3_600_000
642 : null,
643 });
644
645 await ctx.db.insert("storageInstances", nextStorageInstance);
646
647 return nextStorageInstance;
648 },
649});
650
651export const closeStorageInstance = mutation({
652 args: {
653 workspaceId: v.string(),
654 storageInstanceId: v.string(),
655 },
656 handler: async (ctx, args): Promise<StorageInstance> => {
657 const existingStorageInstance = await resolveAccessibleStorageInstance(ctx, {
658 workspaceId: args.workspaceId,
659 storageInstanceId: args.storageInstanceId,
660 });
661
662 if (!existingStorageInstance) {
663 throw new Error(`Storage instance not found: ${args.storageInstanceId}`);
664 }
665
666 const existingRow = await ctx.db
667 .query("storageInstances")
668 .withIndex("by_domainId", (q) => q.eq("id", args.storageInstanceId))
669 .unique();
670
671 if (!existingRow) {
672 throw new Error(`Storage instance not found: ${args.storageInstanceId}`);
673 }
674
675 const now = Date.now();
676 const nextStorageInstance = decodeStorageInstance({
677 ...existingStorageInstance,
678 status: "closed",
679 updatedAt: now,
680 lastSeenAt: now,
681 closedAt: existingStorageInstance.closedAt ?? now,
682 });
683
684 await ctx.db.patch(existingRow._id, nextStorageInstance);
685
686 return nextStorageInstance;
687 },
688});
689
690export const removeStorageInstance = mutation({
691 args: {
692 workspaceId: v.string(),
693 storageInstanceId: v.string(),
694 },
695 handler: async (
696 ctx,
697 args,
698 ): Promise<{
699 removed: boolean;
700 }> => {
701 const existingStorageInstance = await resolveAccessibleStorageInstance(ctx, {
702 workspaceId: args.workspaceId,
703 storageInstanceId: args.storageInstanceId,
704 });
705
706 if (!existingStorageInstance) {
707 return { removed: false };
708 }
709
710 const storageInstanceRow = await ctx.db
711 .query("storageInstances")
712 .withIndex("by_domainId", (q) => q.eq("id", args.storageInstanceId))
713 .unique();
714
715 if (!storageInstanceRow) {
716 return { removed: false };
717 }
718
719 const storageFileRows = await ctx.db
720 .query("storageFileEntries")
721 .withIndex("by_storageInstanceId", (q) => q.eq("storageInstanceId", args.storageInstanceId))
722 .collect();
723
724 for (const storageFileRow of storageFileRows) {
725 await ctx.db.delete(storageFileRow._id);
726 }
727
728 const storageKvRows = await ctx.db
729 .query("storageKvEntries")
730 .withIndex("by_storageInstanceId", (q) => q.eq("storageInstanceId", args.storageInstanceId))
731 .collect();
732
733 for (const storageKvRow of storageKvRows) {
734 await ctx.db.delete(storageKvRow._id);
735 }
736
737 const storageSqlKvRows = await ctx.db
738 .query("storageSqlKvEntries")
739 .withIndex("by_storageInstanceId", (q) => q.eq("storageInstanceId", args.storageInstanceId))
740 .collect();
741
742 for (const storageSqlKvRow of storageSqlKvRows) {
743 await ctx.db.delete(storageSqlKvRow._id);
744 }
745
746 await ctx.db.delete(storageInstanceRow._id);
747
748 return { removed: true };
749 },
750});
751
752export const listStorageDirectory = query({
753 args: {
754 workspaceId: v.string(),
755 storageInstanceId: v.string(),
756 payload: v.object({
757 path: v.string(),
758 }),
759 },
760 handler: async (ctx, args): Promise<ListStorageDirectoryResult> => {
761 const storageInstance = await resolveAccessibleStorageInstance(ctx, {
762 workspaceId: args.workspaceId,
763 storageInstanceId: args.storageInstanceId,
764 });
765
766 if (!storageInstance) {
767 throw new Error(`Storage instance not found: ${args.storageInstanceId}`);
768 }
769
770 const normalizedPath = normalizeStoragePath(args.payload.path);
771
772 const storageFileRows = await ctx.db
773 .query("storageFileEntries")
774 .withIndex("by_storageInstanceId", (q) => q.eq("storageInstanceId", args.storageInstanceId))
775 .collect();
776
777 const storageFiles = storageFileRows.map((row) =>
778 toStorageFileEntry(row as unknown as Record<string, unknown>),
779 );
780
781 const exactFile = storageFiles.find((storageFile) => storageFile.path === normalizedPath);
782 if (exactFile) {
783 throw new Error(`Cannot list a file path as directory: ${normalizedPath}`);
784 }
785
786 const prefix = normalizedPath === "/" ? "/" : `${normalizedPath}/`;
787 const directoryByPath = new Map<string, {
788 name: string;
789 path: string;
790 kind: "directory";
791 sizeBytes: null;
792 updatedAt: number;
793 }>();
794 const fileEntries: Array<{
795 name: string;
796 path: string;
797 kind: "file";
798 sizeBytes: number;
799 updatedAt: number;
800 }> = [];
801
802 for (const storageFile of storageFiles) {
803 if (!storageFile.path.startsWith(prefix)) {
804 continue;
805 }
806
807 const remainder = storageFile.path.slice(prefix.length);
808 if (remainder.length === 0) {
809 continue;
810 }
811
812 const separatorIndex = remainder.indexOf("/");
813 if (separatorIndex < 0) {
814 const fileName = remainder;
815 fileEntries.push({
816 name: fileName,
817 path: storageFile.path,
818 kind: "file",
819 sizeBytes: storageFile.sizeBytes,
820 updatedAt: storageFile.updatedAt,
821 });
822 continue;
823 }
824
825 const directoryName = remainder.slice(0, separatorIndex);
826 const directoryPath = normalizedPath === "/"
827 ? `/${directoryName}`
828 : `${normalizedPath}/${directoryName}`;
829 const existingDirectory = directoryByPath.get(directoryPath);
830
831 if (!existingDirectory) {
832 directoryByPath.set(directoryPath, {
833 name: directoryName,
834 path: directoryPath,
835 kind: "directory",
836 sizeBytes: null,
837 updatedAt: storageFile.updatedAt,
838 });
839 continue;
840 }
841
842 if (storageFile.updatedAt > existingDirectory.updatedAt) {
843 directoryByPath.set(directoryPath, {
844 ...existingDirectory,
845 updatedAt: storageFile.updatedAt,
846 });
847 }
848 }
849
850 if (
851 normalizedPath !== "/"
852 && directoryByPath.size === 0
853 && fileEntries.length === 0
854 ) {
855 throw new Error(`Directory not found: ${normalizedPath}`);
856 }
857
858 const directoryEntries = [...directoryByPath.values()].sort((left, right) =>
859 left.name.localeCompare(right.name)
860 );
861 const sortedFileEntries = [...fileEntries].sort((left, right) =>
862 left.name.localeCompare(right.name)
863 );
864
865 return {
866 path: normalizedPath,
867 entries: [...directoryEntries, ...sortedFileEntries],
868 };
869 },
870});
871
872export const readStorageFile = query({
873 args: {
874 workspaceId: v.string(),
875 storageInstanceId: v.string(),
876 payload: v.object({
877 path: v.string(),
878 encoding: v.optional(readStorageEncodingValidator),
879 }),
880 },
881 handler: async (ctx, args): Promise<ReadStorageFileResult> => {
882 const storageInstance = await resolveAccessibleStorageInstance(ctx, {
883 workspaceId: args.workspaceId,
884 storageInstanceId: args.storageInstanceId,
885 });
886
887 if (!storageInstance) {
888 throw new Error(`Storage instance not found: ${args.storageInstanceId}`);
889 }
890
891 const normalizedPath = normalizeStoragePath(args.payload.path);
892 const storageFileRow = await ctx.db
893 .query("storageFileEntries")
894 .withIndex("by_storageInstanceId_path", (q) =>
895 q.eq("storageInstanceId", args.storageInstanceId).eq("path", normalizedPath)
896 )
897 .unique();
898
899 if (!storageFileRow) {
900 throw new Error(`Storage file not found: ${normalizedPath}`);
901 }
902
903 const storageFile = toStorageFileEntry(storageFileRow as unknown as Record<string, unknown>);
904 const encoding = args.payload.encoding ?? "utf8";
905
906 return {
907 path: normalizedPath,
908 encoding,
909 content: encoding === "base64"
910 ? storageFile.contentBase64
911 : decodeBase64Utf8(storageFile.contentBase64),
912 bytes: storageFile.sizeBytes,
913 };
914 },
915});
916
917export const listStorageKv = query({
918 args: {
919 workspaceId: v.string(),
920 storageInstanceId: v.string(),
921 payload: v.object({
922 prefix: v.optional(v.string()),
923 limit: v.optional(v.number()),
924 }),
925 },
926 handler: async (ctx, args): Promise<ListStorageKvResult> => {
927 const storageInstance = await resolveAccessibleStorageInstance(ctx, {
928 workspaceId: args.workspaceId,
929 storageInstanceId: args.storageInstanceId,
930 });
931
932 if (!storageInstance) {
933 throw new Error(`Storage instance not found: ${args.storageInstanceId}`);
934 }
935
936 const prefix = args.payload.prefix ?? "";
937 const requestedLimit =
938 args.payload.limit !== undefined && Number.isFinite(args.payload.limit)
939 ? Math.floor(args.payload.limit)
940 : DEFAULT_KV_LIMIT;
941 const limit = Math.max(1, Math.min(MAX_KV_LIMIT, requestedLimit));
942
943 const storageKvRows = await ctx.db
944 .query("storageKvEntries")
945 .withIndex("by_storageInstanceId", (q) => q.eq("storageInstanceId", args.storageInstanceId))
946 .collect();
947
948 const items = storageKvRows
949 .map((row) => toStorageKvEntry(row as unknown as Record<string, unknown>))
950 .filter((entry) => entry.key.startsWith(prefix))
951 .sort((left, right) => left.key.localeCompare(right.key))
952 .slice(0, limit)
953 .map((entry) => ({
954 key: entry.key,
955 value: parseJsonOrString(entry.valueJson),
956 }));
957
958 return {
959 items,
960 };
961 },
962});
963
964export const queryStorageSql = mutation({
965 args: {
966 workspaceId: v.string(),
967 storageInstanceId: v.string(),
968 payload: v.object({
969 sql: v.string(),
970 maxRows: v.optional(v.number()),
971 }),
972 },
973 handler: async (ctx, args): Promise<QueryStorageSqlResult> => {
974 const storageInstance = await resolveAccessibleStorageInstance(ctx, {
975 workspaceId: args.workspaceId,
976 storageInstanceId: args.storageInstanceId,
977 });
978
979 if (!storageInstance) {
980 throw new Error(`Storage instance not found: ${args.storageInstanceId}`);
981 }
982
983 const sqlText = args.payload.sql.trim();
984 if (sqlText.length === 0) {
985 throw new Error("SQL query is required");
986 }
987
988 const requestedMaxRows =
989 args.payload.maxRows !== undefined && Number.isFinite(args.payload.maxRows)
990 ? Math.floor(args.payload.maxRows)
991 : DEFAULT_SQL_MAX_ROWS;
992 const maxRows = Math.max(1, Math.min(MAX_SQL_MAX_ROWS, requestedMaxRows));
993
994 const sqlRowsRaw = await ctx.db
995 .query("storageSqlKvEntries")
996 .withIndex("by_storageInstanceId", (q) => q.eq("storageInstanceId", args.storageInstanceId))
997 .collect();
998
999 const sqlRows = sqlRowsRaw.map((row) =>
1000 toStorageSqlKvEntry(row as unknown as Record<string, unknown>),
1001 );
1002 const byKey = new Map<string, {
1003 row: StorageSqlKvEntry;
1004 docId: unknown;
1005 }>();
1006
1007 for (let index = 0; index < sqlRows.length; index += 1) {
1008 const row = sqlRows[index];
1009 const rawRow = sqlRowsRaw[index];
1010 if (row && rawRow) {
1011 byKey.set(row.key, {
1012 row,
1013 docId: rawRow._id,
1014 });
1015 }
1016 }
1017
1018 const execution = executeSqlForStorage(sqlText, sqlRows, maxRows);
1019
1020 for (const write of execution.writes) {
1021 if (write.type === "delete") {
1022 const existing = byKey.get(write.key);
1023 if (existing) {
1024 await ctx.db.delete(existing.docId as any);
1025 byKey.delete(write.key);
1026 }
1027 continue;
1028 }
1029
1030 const existing = byKey.get(write.key);
1031 if (existing && write.insertOnly) {
1032 throw new Error(`UNIQUE constraint failed: kv_store.key (${write.key})`);
1033 }
1034
1035 const now = Date.now();
1036
1037 if (existing) {
1038 const nextRow = decodeStorageSqlKvEntry({
1039 ...existing.row,
1040 value: write.value,
1041 updatedAt: now,
1042 });
1043
1044 await ctx.db.patch(existing.docId as any, nextRow);
1045 byKey.set(write.key, {
1046 row: nextRow,
1047 docId: existing.docId,
1048 });
1049 continue;
1050 }
1051
1052 const nextRow = decodeStorageSqlKvEntry({
1053 id: `storage_sql_kv_${crypto.randomUUID()}`,
1054 storageInstanceId: args.storageInstanceId,
1055 key: write.key,
1056 value: write.value,
1057 updatedAt: now,
1058 });
1059
1060 const insertedId = await ctx.db.insert("storageSqlKvEntries", nextRow);
1061 byKey.set(write.key, {
1062 row: nextRow,
1063 docId: insertedId,
1064 });
1065 }
1066
1067 return execution.result;
1068 },
1069});
apps/convex/convex/control_plane/tool_registry.ts+1237−0
@@ -0,0 +1,1237 @@
1import { v } from "convex/values";
2import { internal } from "../_generated/api";
3
4import { action, internalMutation, internalQuery } from "../_generated/server";
5
6const defaultSearchLimit = 50;
7const maxSearchLimit = 5_000;
8const writeBatchSize = 500;
9const runtimeInternal = internal as any;
10
11const stripConvexSystemFields = (
12 value: Record<string, unknown>,
13): Record<string, unknown> => {
14 const { _id: _ignoredId, _creationTime: _ignoredCreationTime, ...rest } = value;
15 return rest;
16};
17
18const normalizePathForLookup = (path: string): string =>
19 path
20 .trim()
21 .toLowerCase()
22 .replace(/[^a-z0-9]+/g, ".")
23 .replace(/\.+/g, ".")
24 .replace(/^\.|\.$/g, "");
25
26const normalizeLimit = (value: number | undefined): number => {
27 if (!Number.isFinite(value)) {
28 return defaultSearchLimit;
29 }
30
31 return Math.max(1, Math.min(maxSearchLimit, Math.floor(value ?? defaultSearchLimit)));
32};
33
34const artifactSchemaRefId = (artifactId: string, refKey: string): string =>
35 `${artifactId}:ref:${encodeURIComponent(refKey)}`;
36
37const normalizeNamespacePart = (value: string): string => {
38 const normalized = value
39 .trim()
40 .toLowerCase()
41 .replace(/[^a-z0-9]+/g, "_")
42 .replace(/^_+|_+$/g, "");
43
44 return normalized.length > 0 ? normalized : "source";
45};
46
47const sourceNamespace = (source: {
48 id: string;
49 name: string;
50}): string => {
51 const sourceIdSuffix = source.id.slice(-6).toLowerCase();
52 return `${normalizeNamespacePart(source.name)}_${sourceIdSuffix}`;
53};
54
55const parseJsonObject = (value: string | null | undefined): Record<string, unknown> => {
56 if (!value) {
57 return {};
58 }
59
60 try {
61 const parsed = JSON.parse(value) as unknown;
62 return parsed && typeof parsed === "object" && !Array.isArray(parsed)
63 ? (parsed as Record<string, unknown>)
64 : {};
65 } catch {
66 return {};
67 }
68};
69
70const metadataSearchTerms = (metadataJson: string | null | undefined): ReadonlyArray<string> => {
71 if (!metadataJson) {
72 return [];
73 }
74
75 const parsed = parseJsonObject(metadataJson);
76 const keys = ["method", "path", "operationType", "fieldName", "toolName"] as const;
77 const terms: Array<string> = [];
78
79 for (const key of keys) {
80 const value = parsed[key];
81 if (typeof value === "string" && value.trim().length > 0) {
82 terms.push(value);
83 }
84 }
85
86 return terms;
87};
88
89const normalizedSearchText = (...parts: ReadonlyArray<string | null | undefined>): string =>
90 parts
91 .map((part) => (typeof part === "string" ? part.trim().toLowerCase() : ""))
92 .filter((part) => part.length > 0)
93 .join(" ");
94
95const methodFromCanonicalPath = (canonicalPath: string | null | undefined): string | null => {
96 if (!canonicalPath) {
97 return null;
98 }
99
100 const candidate = canonicalPath.trim().split(/\s+/)[0]?.toLowerCase() ?? null;
101 if (
102 candidate === "get" ||
103 candidate === "post" ||
104 candidate === "put" ||
105 candidate === "patch" ||
106 candidate === "delete" ||
107 candidate === "head" ||
108 candidate === "options" ||
109 candidate === "trace"
110 ) {
111 return candidate;
112 }
113
114 return null;
115};
116
117const toWorkspaceToolMethod = (
118 protocol: string | null | undefined,
119 metadataJson: string | null | undefined,
120 canonicalPath: string | null | undefined,
121): string => {
122 const canonicalMethod = methodFromCanonicalPath(canonicalPath);
123 if (canonicalMethod) {
124 return canonicalMethod;
125 }
126
127 const normalizedProtocol = (protocol ?? "").toLowerCase();
128 if (normalizedProtocol !== "openapi") {
129 return "post";
130 }
131
132 const metadata = parseJsonObject(metadataJson);
133 const method = typeof metadata.method === "string" ? metadata.method.trim().toLowerCase() : "";
134
135 if (
136 method === "get" ||
137 method === "post" ||
138 method === "put" ||
139 method === "patch" ||
140 method === "delete" ||
141 method === "head" ||
142 method === "options" ||
143 method === "trace"
144 ) {
145 return method;
146 }
147
148 return "get";
149};
150
151const scoreSearchRow = (row: Record<string, unknown>, queryLower: string): number => {
152 const path = String(row.path ?? "").toLowerCase();
153 const name = String(row.name ?? "").toLowerCase();
154 const description = String(row.description ?? "").toLowerCase();
155 const sourceName = String(row.sourceName ?? "").toLowerCase();
156 const searchText = String(row.searchText ?? "").toLowerCase();
157
158 if (path === queryLower) {
159 return 100;
160 }
161
162 if (path.startsWith(queryLower)) {
163 return 85;
164 }
165
166 if (name.includes(queryLower)) {
167 return 75;
168 }
169
170 if (path.includes(queryLower)) {
171 return 70;
172 }
173
174 if (sourceName.includes(queryLower)) {
175 return 60;
176 }
177
178 if (description.includes(queryLower)) {
179 return 50;
180 }
181
182 if (searchText.includes(queryLower)) {
183 return 40;
184 }
185
186 return 0;
187};
188
189const chunkArray = <A>(values: ReadonlyArray<A>, size: number): Array<Array<A>> => {
190 const chunkSize = Math.max(1, Math.floor(size));
191 const chunks: Array<Array<A>> = [];
192
193 for (let index = 0; index < values.length; index += chunkSize) {
194 chunks.push(values.slice(index, index + chunkSize));
195 }
196
197 return chunks;
198};
199
200const buildWorkspaceToolRows = async (
201 ctx: any,
202 args: {
203 workspaceId: string;
204 sourceId?: string;
205 namespace?: string;
206 includeDisabled?: boolean;
207 },
208): Promise<Array<Record<string, unknown>>> => {
209 const sourceRows = await ctx.db
210 .query("sources")
211 .withIndex("by_workspaceId", (q: any) => q.eq("workspaceId", args.workspaceId))
212 .collect();
213
214 const bindingRows = await ctx.db
215 .query("sourceArtifactBindings")
216 .withIndex("by_workspaceId", (q: any) => q.eq("workspaceId", args.workspaceId))
217 .collect();
218
219 const bindingBySourceId = new Map<string, Record<string, unknown>>();
220 for (const row of bindingRows) {
221 bindingBySourceId.set(String(row.sourceId), row as unknown as Record<string, unknown>);
222 }
223
224 const rows: Array<Record<string, unknown>> = [];
225
226 for (const sourceRow of sourceRows) {
227 const source = sourceRow as unknown as Record<string, unknown>;
228 const sourceId = String(source.id ?? "");
229 const sourceName = String(source.name ?? "");
230 const sourceKind = String(source.kind ?? "");
231 const sourceEnabled = source.enabled === true;
232
233 if (args.sourceId && sourceId !== args.sourceId) {
234 continue;
235 }
236
237 const status = sourceEnabled ? "active" : "disabled";
238 if (args.includeDisabled !== true && status !== "active") {
239 continue;
240 }
241
242 const binding = bindingBySourceId.get(sourceId);
243 if (!binding) {
244 continue;
245 }
246
247 const artifactId = String(binding.artifactId ?? "");
248 if (artifactId.length === 0) {
249 continue;
250 }
251
252 const namespace = sourceNamespace({ id: sourceId, name: sourceName });
253 if (args.namespace && namespace !== args.namespace) {
254 continue;
255 }
256
257 const artifactTools = await ctx.db
258 .query("artifactTools")
259 .withIndex("by_artifactId", (q: any) => q.eq("artifactId", artifactId))
260 .collect();
261
262 for (const artifactToolRow of artifactTools) {
263 const artifactTool = artifactToolRow as unknown as Record<string, unknown>;
264 const toolId = String(artifactTool.toolId ?? "");
265 const protocol = String(artifactTool.protocol ?? "openapi");
266 const canonicalPath =
267 typeof artifactTool.canonicalPath === "string" && artifactTool.canonicalPath.trim().length > 0
268 ? artifactTool.canonicalPath.trim()
269 : null;
270 const method = toWorkspaceToolMethod(
271 protocol,
272 typeof artifactTool.metadataJson === "string" ? artifactTool.metadataJson : null,
273 canonicalPath,
274 );
275 const path = `${namespace}.${toolId}`;
276 const description = typeof artifactTool.description === "string" ? artifactTool.description : null;
277 const name = String(artifactTool.name ?? toolId);
278
279 rows.push({
280 id: `wti_${args.workspaceId}_${sourceId}_${toolId}`,
281 workspaceId: args.workspaceId,
282 sourceId,
283 sourceName,
284 sourceKind,
285 artifactId,
286 toolId,
287 protocol,
288 method,
289 namespace,
290 path,
291 pathLower: path.toLowerCase(),
292 normalizedPath: normalizePathForLookup(path),
293 operationPath: canonicalPath,
294 name,
295 description,
296 searchText: normalizedSearchText(
297 sourceName,
298 String(source.endpoint ?? ""),
299 namespace,
300 toolId,
301 name,
302 description,
303 ...metadataSearchTerms(
304 typeof artifactTool.metadataJson === "string" ? artifactTool.metadataJson : null,
305 ),
306 ),
307 operationHash: String(artifactTool.operationHash ?? ""),
308 approvalMode: "auto",
309 status,
310 refHintTableJson: null,
311 updatedAt: Number(binding.updatedAt ?? Date.now()),
312 });
313 }
314 }
315
316 rows.sort((left, right) => String(left.path).localeCompare(String(right.path)));
317 return rows;
318};
319
320export const ingestOpenApiManifest = action({
321 args: {
322 token: v.string(),
323 workspaceId: v.string(),
324 sourceId: v.string(),
325 sourceName: v.string(),
326 sourceEndpoint: v.string(),
327 sourceEnabled: v.boolean(),
328 sourceHash: v.string(),
329 toolCount: v.number(),
330 refs: v.array(
331 v.object({
332 refKey: v.string(),
333 schemaJson: v.string(),
334 }),
335 ),
336 tools: v.array(
337 v.object({
338 toolId: v.string(),
339 name: v.string(),
340 description: v.union(v.string(), v.null()),
341 method: v.string(),
342 path: v.string(),
343 operationHash: v.string(),
344 invocationJson: v.string(),
345 inputSchemaJson: v.union(v.string(), v.null()),
346 outputSchemaJson: v.union(v.string(), v.null()),
347 }),
348 ),
349 },
350 handler: async (ctx, args) => {
351 const expectedToken =
352 process.env.OPENAPI_INGEST_SERVICE_TOKEN?.trim()
353 || process.env.OPENAPI_PARSE_API_TOKEN?.trim()
354 || "";
355 if (expectedToken.length > 0 && args.token.trim() !== expectedToken) {
356 throw new Error("Unauthorized OpenAPI ingest request");
357 }
358
359 const artifactMeta = await ctx.runMutation(
360 runtimeInternal.control_plane.tool_registry.upsertArtifactMeta,
361 {
362 protocol: "openapi",
363 contentHash: args.sourceHash,
364 extractorVersion: "openapi_v2",
365 toolCount: args.toolCount,
366 refHintTableJson: null,
367 },
368 );
369
370 if (args.refs.length > 0) {
371 let shouldPersistRefs = artifactMeta.created;
372
373 if (!shouldPersistRefs) {
374 const existingRefCount = await ctx.runQuery(
375 runtimeInternal.control_plane.tool_registry.countArtifactSchemaRefs,
376 {
377 artifactId: artifactMeta.artifactId,
378 },
379 );
380 shouldPersistRefs = existingRefCount !== args.refs.length;
381 }
382
383 if (shouldPersistRefs) {
384 await ctx.runMutation(
385 runtimeInternal.control_plane.tool_registry.clearArtifactSchemaRefs,
386 {
387 artifactId: artifactMeta.artifactId,
388 },
389 );
390
391 for (const batch of chunkArray(args.refs, writeBatchSize)) {
392 await ctx.runMutation(
393 runtimeInternal.control_plane.tool_registry.putArtifactSchemaRefsBatch,
394 {
395 artifactId: artifactMeta.artifactId,
396 refs: batch,
397 },
398 );
399 }
400 }
401 }
402
403 if (artifactMeta.created && args.tools.length > 0) {
404 const artifactRows = args.tools.map((tool) => ({
405 toolId: tool.toolId,
406 name: tool.name,
407 description: tool.description,
408 canonicalPath: `${tool.method.toUpperCase()} ${tool.path}`,
409 operationHash: tool.operationHash,
410 invocationJson: tool.invocationJson,
411 inputSchemaJson: tool.inputSchemaJson,
412 outputSchemaJson: tool.outputSchemaJson,
413 metadataJson: JSON.stringify({
414 method: tool.method,
415 path: tool.path,
416 }),
417 }));
418
419 for (const batch of chunkArray(artifactRows, writeBatchSize)) {
420 await ctx.runMutation(runtimeInternal.control_plane.tool_registry.putArtifactToolsBatch, {
421 artifactId: artifactMeta.artifactId,
422 protocol: "openapi",
423 insertOnly: true,
424 tools: batch,
425 });
426 }
427 }
428
429 await ctx.runMutation(runtimeInternal.control_plane.tool_registry.bindSourceToArtifact, {
430 workspaceId: args.workspaceId,
431 sourceId: args.sourceId,
432 artifactId: artifactMeta.artifactId,
433 });
434
435 return {
436 artifactId: artifactMeta.artifactId,
437 created: artifactMeta.created,
438 sourceHash: args.sourceHash,
439 toolCount: args.toolCount,
440 sourceName: args.sourceName,
441 sourceEndpoint: args.sourceEndpoint,
442 sourceEnabled: args.sourceEnabled,
443 };
444 },
445});
446
447export const upsertArtifactMeta = internalMutation({
448 args: {
449 protocol: v.string(),
450 contentHash: v.string(),
451 extractorVersion: v.string(),
452 toolCount: v.number(),
453 refHintTableJson: v.optional(v.union(v.string(), v.null())),
454 },
455 handler: async (ctx, args) => {
456 const now = Date.now();
457 const existing = await ctx.db
458 .query("artifacts")
459 .withIndex("by_protocol_contentHash_extractorVersion", (q) =>
460 q
461 .eq("protocol", args.protocol)
462 .eq("contentHash", args.contentHash)
463 .eq("extractorVersion", args.extractorVersion),
464 )
465 .unique();
466
467 if (existing) {
468 await ctx.db.patch(existing._id, {
469 toolCount: args.toolCount,
470 refHintTableJson: args.refHintTableJson ?? null,
471 updatedAt: now,
472 });
473
474 return {
475 artifactId: existing.id,
476 created: false,
477 };
478 }
479
480 const artifactId = `art_${args.protocol}_${args.contentHash}_${args.extractorVersion}`;
481 await ctx.db.insert("artifacts", {
482 id: artifactId,
483 protocol: args.protocol,
484 contentHash: args.contentHash,
485 extractorVersion: args.extractorVersion,
486 toolCount: args.toolCount,
487 refHintTableJson: args.refHintTableJson ?? null,
488 createdAt: now,
489 updatedAt: now,
490 });
491
492 return {
493 artifactId,
494 created: true,
495 };
496 },
497});
498
499export const clearArtifactSchemaRefs = internalMutation({
500 args: {
501 artifactId: v.string(),
502 },
503 handler: async (ctx, args) => {
504 const existing = await ctx.db
505 .query("artifactSchemaRefs")
506 .withIndex("by_artifactId", (q) => q.eq("artifactId", args.artifactId))
507 .collect();
508
509 for (const row of existing) {
510 await ctx.db.delete(row._id);
511 }
512
513 return { removedCount: existing.length };
514 },
515});
516
517export const putArtifactSchemaRefsBatch = internalMutation({
518 args: {
519 artifactId: v.string(),
520 refs: v.array(
521 v.object({
522 refKey: v.string(),
523 schemaJson: v.string(),
524 }),
525 ),
526 },
527 handler: async (ctx, args) => {
528 const now = Date.now();
529 let insertedCount = 0;
530
531 for (const ref of args.refs) {
532 await ctx.db.insert("artifactSchemaRefs", {
533 id: artifactSchemaRefId(args.artifactId, ref.refKey),
534 artifactId: args.artifactId,
535 refKey: ref.refKey,
536 schemaJson: ref.schemaJson,
537 createdAt: now,
538 updatedAt: now,
539 });
540 insertedCount += 1;
541 }
542
543 return { insertedCount };
544 },
545});
546
547export const countArtifactSchemaRefs = internalQuery({
548 args: {
549 artifactId: v.string(),
550 },
551 handler: async (ctx, args) => {
552 const rows = await ctx.db
553 .query("artifactSchemaRefs")
554 .withIndex("by_artifactId", (q) => q.eq("artifactId", args.artifactId))
555 .collect();
556
557 return rows.length;
558 },
559});
560
561export const putArtifactToolsBatch = internalMutation({
562 args: {
563 artifactId: v.string(),
564 protocol: v.string(),
565 insertOnly: v.optional(v.boolean()),
566 tools: v.array(
567 v.object({
568 toolId: v.string(),
569 name: v.string(),
570 description: v.union(v.string(), v.null()),
571 canonicalPath: v.string(),
572 operationHash: v.string(),
573 invocationJson: v.string(),
574 inputSchemaJson: v.optional(v.union(v.string(), v.null())),
575 outputSchemaJson: v.optional(v.union(v.string(), v.null())),
576 metadataJson: v.optional(v.union(v.string(), v.null())),
577 }),
578 ),
579 },
580 handler: async (ctx, args) => {
581 const now = Date.now();
582 let insertedCount = 0;
583
584 if (args.insertOnly === true) {
585 for (const tool of args.tools) {
586 await ctx.db.insert("artifactTools", {
587 id: `${args.artifactId}:${tool.toolId}`,
588 artifactId: args.artifactId,
589 protocol: args.protocol,
590 toolId: tool.toolId,
591 name: tool.name,
592 description: tool.description,
593 canonicalPath: tool.canonicalPath,
594 operationHash: tool.operationHash,
595 invocationJson: tool.invocationJson,
596 inputSchemaJson: tool.inputSchemaJson ?? null,
597 outputSchemaJson: tool.outputSchemaJson ?? null,
598 metadataJson: tool.metadataJson ?? null,
599 createdAt: now,
600 updatedAt: now,
601 });
602 insertedCount += 1;
603 }
604
605 return { insertedCount };
606 }
607
608 for (const tool of args.tools) {
609 const existing = await ctx.db
610 .query("artifactTools")
611 .withIndex("by_artifactId_toolId", (q) =>
612 q.eq("artifactId", args.artifactId).eq("toolId", tool.toolId),
613 )
614 .unique();
615
616 const row = {
617 id: `${args.artifactId}:${tool.toolId}`,
618 artifactId: args.artifactId,
619 protocol: args.protocol,
620 toolId: tool.toolId,
621 name: tool.name,
622 description: tool.description,
623 canonicalPath: tool.canonicalPath,
624 operationHash: tool.operationHash,
625 invocationJson: tool.invocationJson,
626 inputSchemaJson: tool.inputSchemaJson ?? null,
627 outputSchemaJson: tool.outputSchemaJson ?? null,
628 metadataJson: tool.metadataJson ?? null,
629 createdAt: existing?.createdAt ?? now,
630 updatedAt: now,
631 };
632
633 if (existing) {
634 await ctx.db.patch(existing._id, row);
635 } else {
636 await ctx.db.insert("artifactTools", row);
637 insertedCount += 1;
638 }
639 }
640
641 return { insertedCount };
642 },
643});
644
645export const bindSourceToArtifact = internalMutation({
646 args: {
647 workspaceId: v.string(),
648 sourceId: v.string(),
649 artifactId: v.string(),
650 },
651 handler: async (ctx, args) => {
652 const existing = await ctx.db
653 .query("sourceArtifactBindings")
654 .withIndex("by_workspaceId_sourceId", (q) =>
655 q.eq("workspaceId", args.workspaceId).eq("sourceId", args.sourceId),
656 )
657 .unique();
658
659 const row = {
660 id: existing?.id ?? `sab_${args.workspaceId}_${args.sourceId}`,
661 workspaceId: args.workspaceId,
662 sourceId: args.sourceId,
663 artifactId: args.artifactId,
664 updatedAt: Date.now(),
665 };
666
667 if (existing) {
668 await ctx.db.patch(existing._id, row);
669 } else {
670 await ctx.db.insert("sourceArtifactBindings", row);
671 }
672
673 return row;
674 },
675});
676
677export const replaceSourceIngestArtifactBatches = internalMutation({
678 args: {
679 workspaceId: v.string(),
680 sourceId: v.string(),
681 artifactId: v.string(),
682 protocol: v.string(),
683 batches: v.array(v.string()),
684 },
685 handler: async (ctx, args) => {
686 const existing = await ctx.db
687 .query("sourceIngestArtifactBatches")
688 .withIndex("by_workspaceId_sourceId", (q) =>
689 q.eq("workspaceId", args.workspaceId).eq("sourceId", args.sourceId),
690 )
691 .collect();
692
693 for (const row of existing) {
694 await ctx.db.delete(row._id);
695 }
696
697 const now = Date.now();
698 for (let batchIndex = 0; batchIndex < args.batches.length; batchIndex += 1) {
699 await ctx.db.insert("sourceIngestArtifactBatches", {
700 id: `siab_${args.workspaceId}_${args.sourceId}_${args.artifactId}_${batchIndex}`,
701 workspaceId: args.workspaceId,
702 sourceId: args.sourceId,
703 artifactId: args.artifactId,
704 protocol: args.protocol,
705 batchIndex,
706 toolsJson: args.batches[batchIndex] ?? "[]",
707 updatedAt: now,
708 });
709 }
710
711 return { batchCount: args.batches.length };
712 },
713});
714
715export const clearSourceIngestArtifactBatches = internalMutation({
716 args: {
717 workspaceId: v.string(),
718 sourceId: v.string(),
719 },
720 handler: async (ctx, args) => {
721 const existing = await ctx.db
722 .query("sourceIngestArtifactBatches")
723 .withIndex("by_workspaceId_sourceId", (q) =>
724 q.eq("workspaceId", args.workspaceId).eq("sourceId", args.sourceId),
725 )
726 .collect();
727
728 for (const row of existing) {
729 await ctx.db.delete(row._id);
730 }
731
732 return { removedCount: existing.length };
733 },
734});
735
736export const getSourceIngestArtifactBatch = internalQuery({
737 args: {
738 workspaceId: v.string(),
739 sourceId: v.string(),
740 artifactId: v.string(),
741 batchIndex: v.number(),
742 },
743 handler: async (ctx, args) => {
744 const row = await ctx.db
745 .query("sourceIngestArtifactBatches")
746 .withIndex("by_workspaceId_sourceId_artifactId_batchIndex", (q) =>
747 q
748 .eq("workspaceId", args.workspaceId)
749 .eq("sourceId", args.sourceId)
750 .eq("artifactId", args.artifactId)
751 .eq("batchIndex", Math.max(0, Math.floor(args.batchIndex))),
752 )
753 .unique();
754
755 return row ? stripConvexSystemFields(row as unknown as Record<string, unknown>) : null;
756 },
757});
758
759export const replaceWorkspaceSourceToolIndex = internalMutation({
760 args: {
761 workspaceId: v.string(),
762 sourceId: v.string(),
763 sourceName: v.string(),
764 sourceKind: v.string(),
765 artifactId: v.string(),
766 namespace: v.string(),
767 refHintTableJson: v.optional(v.union(v.string(), v.null())),
768 rows: v.array(
769 v.object({
770 toolId: v.string(),
771 protocol: v.string(),
772 method: v.string(),
773 path: v.string(),
774 operationPath: v.optional(v.union(v.string(), v.null())),
775 name: v.string(),
776 description: v.union(v.string(), v.null()),
777 searchText: v.string(),
778 operationHash: v.string(),
779 approvalMode: v.string(),
780 status: v.string(),
781 }),
782 ),
783 },
784 handler: async (ctx, args) => {
785 const existingRows = await ctx.db
786 .query("workspaceToolIndex")
787 .withIndex("by_workspaceId_sourceId", (q) =>
788 q.eq("workspaceId", args.workspaceId).eq("sourceId", args.sourceId),
789 )
790 .collect();
791
792 for (const row of existingRows) {
793 await ctx.db.delete(row._id);
794 }
795
796 const now = Date.now();
797 let insertedCount = 0;
798
799 for (const row of args.rows) {
800 await ctx.db.insert("workspaceToolIndex", {
801 id: `wti_${args.workspaceId}_${args.sourceId}_${row.toolId}`,
802 workspaceId: args.workspaceId,
803 sourceId: args.sourceId,
804 sourceName: args.sourceName,
805 sourceKind: args.sourceKind,
806 artifactId: args.artifactId,
807 toolId: row.toolId,
808 protocol: row.protocol,
809 method: row.method,
810 namespace: args.namespace,
811 path: row.path,
812 pathLower: row.path.toLowerCase(),
813 normalizedPath: normalizePathForLookup(row.path),
814 operationPath: row.operationPath ?? null,
815 name: row.name,
816 description: row.description,
817 searchText: row.searchText,
818 operationHash: row.operationHash,
819 approvalMode: row.approvalMode,
820 status: row.status,
821 refHintTableJson: args.refHintTableJson ?? null,
822 updatedAt: now,
823 });
824 insertedCount += 1;
825 }
826
827 return { insertedCount };
828 },
829});
830
831export const clearWorkspaceSourceToolIndex = internalMutation({
832 args: {
833 workspaceId: v.string(),
834 sourceId: v.string(),
835 },
836 handler: async (ctx, args) => {
837 const existingRows = await ctx.db
838 .query("workspaceToolIndex")
839 .withIndex("by_workspaceId_sourceId", (q) =>
840 q.eq("workspaceId", args.workspaceId).eq("sourceId", args.sourceId),
841 )
842 .collect();
843
844 for (const row of existingRows) {
845 await ctx.db.delete(row._id);
846 }
847
848 return { removedCount: existingRows.length };
849 },
850});
851
852export const appendWorkspaceSourceToolIndexChunk = internalMutation({
853 args: {
854 workspaceId: v.string(),
855 sourceId: v.string(),
856 sourceName: v.string(),
857 sourceKind: v.string(),
858 artifactId: v.string(),
859 namespace: v.string(),
860 refHintTableJson: v.optional(v.union(v.string(), v.null())),
861 insertOnly: v.optional(v.boolean()),
862 rows: v.array(
863 v.object({
864 toolId: v.string(),
865 protocol: v.string(),
866 method: v.string(),
867 path: v.string(),
868 operationPath: v.optional(v.union(v.string(), v.null())),
869 name: v.string(),
870 description: v.union(v.string(), v.null()),
871 searchText: v.string(),
872 operationHash: v.string(),
873 approvalMode: v.string(),
874 status: v.string(),
875 }),
876 ),
877 },
878 handler: async (ctx, args) => {
879 const now = Date.now();
880 let insertedCount = 0;
881 let updatedCount = 0;
882
883 if (args.insertOnly === true) {
884 for (const row of args.rows) {
885 const nextRow = {
886 id: `wti_${args.workspaceId}_${args.sourceId}_${row.toolId}`,
887 workspaceId: args.workspaceId,
888 sourceId: args.sourceId,
889 sourceName: args.sourceName,
890 sourceKind: args.sourceKind,
891 artifactId: args.artifactId,
892 toolId: row.toolId,
893 protocol: row.protocol,
894 method: row.method,
895 namespace: args.namespace,
896 path: row.path,
897 pathLower: row.path.toLowerCase(),
898 normalizedPath: normalizePathForLookup(row.path),
899 operationPath: row.operationPath ?? null,
900 name: row.name,
901 description: row.description,
902 searchText: row.searchText,
903 operationHash: row.operationHash,
904 approvalMode: row.approvalMode,
905 status: row.status,
906 refHintTableJson: args.refHintTableJson ?? null,
907 updatedAt: now,
908 };
909
910 await ctx.db.insert("workspaceToolIndex", nextRow);
911 insertedCount += 1;
912 }
913
914 return { insertedCount, updatedCount };
915 }
916
917 for (const row of args.rows) {
918 const id = `wti_${args.workspaceId}_${args.sourceId}_${row.toolId}`;
919 const existing = await ctx.db
920 .query("workspaceToolIndex")
921 .withIndex("by_domainId", (q) => q.eq("id", id))
922 .unique();
923
924 const nextRow = {
925 id,
926 workspaceId: args.workspaceId,
927 sourceId: args.sourceId,
928 sourceName: args.sourceName,
929 sourceKind: args.sourceKind,
930 artifactId: args.artifactId,
931 toolId: row.toolId,
932 protocol: row.protocol,
933 method: row.method,
934 namespace: args.namespace,
935 path: row.path,
936 pathLower: row.path.toLowerCase(),
937 normalizedPath: normalizePathForLookup(row.path),
938 operationPath: row.operationPath ?? null,
939 name: row.name,
940 description: row.description,
941 searchText: row.searchText,
942 operationHash: row.operationHash,
943 approvalMode: row.approvalMode,
944 status: row.status,
945 refHintTableJson: args.refHintTableJson ?? null,
946 updatedAt: now,
947 };
948
949 if (existing) {
950 await ctx.db.patch(existing._id, nextRow);
951 updatedCount += 1;
952 } else {
953 await ctx.db.insert("workspaceToolIndex", nextRow);
954 insertedCount += 1;
955 }
956 }
957
958 return { insertedCount, updatedCount };
959 },
960});
961
962export const removeSourceBindingsAndIndex = internalMutation({
963 args: {
964 workspaceId: v.string(),
965 sourceId: v.string(),
966 },
967 handler: async (ctx, args) => {
968 const binding = await ctx.db
969 .query("sourceArtifactBindings")
970 .withIndex("by_workspaceId_sourceId", (q) =>
971 q.eq("workspaceId", args.workspaceId).eq("sourceId", args.sourceId),
972 )
973 .unique();
974
975 if (binding) {
976 await ctx.db.delete(binding._id);
977 }
978
979 const indexRows = await ctx.db
980 .query("workspaceToolIndex")
981 .withIndex("by_workspaceId_sourceId", (q) =>
982 q.eq("workspaceId", args.workspaceId).eq("sourceId", args.sourceId),
983 )
984 .collect();
985
986 for (const row of indexRows) {
987 await ctx.db.delete(row._id);
988 }
989
990 return {
991 removedBinding: Boolean(binding),
992 removedIndexRows: indexRows.length,
993 };
994 },
995});
996
997export const getSourceArtifactBinding = internalQuery({
998 args: {
999 workspaceId: v.string(),
1000 sourceId: v.string(),
1001 },
1002 handler: async (ctx, args) => {
1003 const binding = await ctx.db
1004 .query("sourceArtifactBindings")
1005 .withIndex("by_workspaceId_sourceId", (q) =>
1006 q.eq("workspaceId", args.workspaceId).eq("sourceId", args.sourceId),
1007 )
1008 .unique();
1009
1010 return binding ? stripConvexSystemFields(binding as unknown as Record<string, unknown>) : null;
1011 },
1012});
1013
1014export const getArtifactById = internalQuery({
1015 args: {
1016 artifactId: v.string(),
1017 },
1018 handler: async (ctx, args) => {
1019 const artifact = await ctx.db
1020 .query("artifacts")
1021 .withIndex("by_domainId", (q) => q.eq("id", args.artifactId))
1022 .unique();
1023
1024 return artifact ? stripConvexSystemFields(artifact as unknown as Record<string, unknown>) : null;
1025 },
1026});
1027
1028export const listArtifactTools = internalQuery({
1029 args: {
1030 artifactId: v.string(),
1031 },
1032 handler: async (ctx, args) => {
1033 const rows = await ctx.db
1034 .query("artifactTools")
1035 .withIndex("by_artifactId", (q) => q.eq("artifactId", args.artifactId))
1036 .collect();
1037
1038 return rows
1039 .map((row) => stripConvexSystemFields(row as unknown as Record<string, unknown>))
1040 .sort((left, right) => String(left.toolId).localeCompare(String(right.toolId)));
1041 },
1042});
1043
1044export const listArtifactToolIndexSlice = internalQuery({
1045 args: {
1046 artifactId: v.string(),
1047 offset: v.optional(v.number()),
1048 limit: v.optional(v.number()),
1049 },
1050 handler: async (ctx, args) => {
1051 const rows = await ctx.db
1052 .query("artifactTools")
1053 .withIndex("by_artifactId", (q) => q.eq("artifactId", args.artifactId))
1054 .collect();
1055
1056 const ordered = rows
1057 .map((row) => stripConvexSystemFields(row as unknown as Record<string, unknown>))
1058 .sort((left, right) => String(left.toolId).localeCompare(String(right.toolId)));
1059
1060 const offset = Math.max(0, Math.floor(args.offset ?? 0));
1061 const limit = normalizeLimit(args.limit);
1062
1063 return ordered.slice(offset, offset + limit).map((row) => ({
1064 toolId: String(row.toolId),
1065 protocol: String(row.protocol),
1066 name: String(row.name),
1067 description: typeof row.description === "string" ? row.description : null,
1068 canonicalPath: typeof row.canonicalPath === "string" ? row.canonicalPath : null,
1069 operationHash: String(row.operationHash),
1070 metadataJson: typeof row.metadataJson === "string" ? row.metadataJson : null,
1071 }));
1072 },
1073});
1074
1075export const getArtifactTool = internalQuery({
1076 args: {
1077 artifactId: v.string(),
1078 toolId: v.string(),
1079 },
1080 handler: async (ctx, args) => {
1081 const row = await ctx.db
1082 .query("artifactTools")
1083 .withIndex("by_artifactId_toolId", (q) =>
1084 q.eq("artifactId", args.artifactId).eq("toolId", args.toolId),
1085 )
1086 .unique();
1087
1088 return row ? stripConvexSystemFields(row as unknown as Record<string, unknown>) : null;
1089 },
1090});
1091
1092export const searchWorkspaceTools = internalQuery({
1093 args: {
1094 workspaceId: v.string(),
1095 query: v.string(),
1096 limit: v.optional(v.number()),
1097 sourceId: v.optional(v.string()),
1098 namespace: v.optional(v.string()),
1099 includeDisabled: v.optional(v.boolean()),
1100 },
1101 handler: async (ctx, args) => {
1102 const trimmedQuery = args.query.trim();
1103 const limit = normalizeLimit(args.limit);
1104 if (trimmedQuery.length === 0) {
1105 return [];
1106 }
1107
1108 const rows = await buildWorkspaceToolRows(ctx, {
1109 workspaceId: args.workspaceId,
1110 sourceId: args.sourceId,
1111 namespace: args.namespace,
1112 includeDisabled: args.includeDisabled,
1113 });
1114
1115 const queryLower = trimmedQuery.toLowerCase();
1116 const ranked = rows
1117 .map((row) => ({
1118 row,
1119 score: scoreSearchRow(row, queryLower),
1120 }))
1121 .filter((entry) => entry.score > 0)
1122 .sort((left, right) => {
1123 if (left.score !== right.score) {
1124 return right.score - left.score;
1125 }
1126
1127 return String(left.row.path).localeCompare(String(right.row.path));
1128 });
1129
1130 return ranked.slice(0, limit).map((entry) => entry.row);
1131 },
1132});
1133
1134export const listWorkspaceTools = internalQuery({
1135 args: {
1136 workspaceId: v.string(),
1137 limit: v.optional(v.number()),
1138 sourceId: v.optional(v.string()),
1139 namespace: v.optional(v.string()),
1140 includeDisabled: v.optional(v.boolean()),
1141 },
1142 handler: async (ctx, args) => {
1143 const rows = await buildWorkspaceToolRows(ctx, {
1144 workspaceId: args.workspaceId,
1145 sourceId: args.sourceId,
1146 namespace: args.namespace,
1147 includeDisabled: args.includeDisabled,
1148 });
1149
1150 return rows.slice(0, normalizeLimit(args.limit));
1151 },
1152});
1153
1154export const getWorkspaceToolByPath = internalQuery({
1155 args: {
1156 workspaceId: v.string(),
1157 pathLower: v.string(),
1158 },
1159 handler: async (ctx, args) => {
1160 const rows = await buildWorkspaceToolRows(ctx, {
1161 workspaceId: args.workspaceId,
1162 includeDisabled: true,
1163 });
1164
1165 return rows.find((row) => String(row.pathLower) === args.pathLower) ?? null;
1166 },
1167});
1168
1169export const listWorkspaceToolsByNormalizedPath = internalQuery({
1170 args: {
1171 workspaceId: v.string(),
1172 normalizedPath: v.string(),
1173 limit: v.optional(v.number()),
1174 },
1175 handler: async (ctx, args) => {
1176 const rows = await buildWorkspaceToolRows(ctx, {
1177 workspaceId: args.workspaceId,
1178 includeDisabled: false,
1179 });
1180
1181 return rows
1182 .filter((row) => String(row.normalizedPath) === args.normalizedPath)
1183 .slice(0, normalizeLimit(args.limit));
1184 },
1185});
1186
1187export const listWorkspaceNamespaces = internalQuery({
1188 args: {
1189 workspaceId: v.string(),
1190 limit: v.optional(v.number()),
1191 },
1192 handler: async (ctx, args) => {
1193 const rows = await buildWorkspaceToolRows(ctx, {
1194 workspaceId: args.workspaceId,
1195 includeDisabled: false,
1196 });
1197
1198 const grouped = new Map<
1199 string,
1200 {
1201 sourceName: string;
1202 sourceId: string;
1203 sourceKind: string;
1204 paths: Array<string>;
1205 }
1206 >();
1207
1208 for (const row of rows) {
1209 const namespace = String(row.namespace);
1210 const existing = grouped.get(namespace);
1211 if (existing) {
1212 existing.paths.push(String(row.path));
1213 continue;
1214 }
1215
1216 grouped.set(namespace, {
1217 sourceName: String(row.sourceName),
1218 sourceId: String(row.sourceId),
1219 sourceKind: String(row.sourceKind),
1220 paths: [String(row.path)],
1221 });
1222 }
1223
1224 const namespaces = [...grouped.entries()]
1225 .map(([namespace, value]) => ({
1226 namespace,
1227 source: value.sourceName,
1228 sourceId: value.sourceId,
1229 sourceKind: value.sourceKind,
1230 toolCount: value.paths.length,
1231 samplePaths: value.paths.sort((left, right) => left.localeCompare(right)).slice(0, 3),
1232 }))
1233 .sort((left, right) => left.namespace.localeCompare(right.namespace));
1234
1235 return namespaces.slice(0, normalizeLimit(args.limit));
1236 },
1237});
apps/convex/convex/control_plane/tools.ts+393−0
@@ -0,0 +1,393 @@
1import { type SourceToolDetail, type SourceToolSummary } from "@executor-v2/management-api";
2import {
3 SourceSchema,
4 type OpenApiHttpMethod,
5 type Source,
6} from "@executor-v2/schema";
7import { v } from "convex/values";
8import * as Schema from "effect/Schema";
9
10import { query } from "../_generated/server";
11
12const decodeSource = Schema.decodeUnknownSync(SourceSchema);
13
14const stripConvexSystemFields = (
15 value: Record<string, unknown>,
16): Record<string, unknown> => {
17 const { _id: _ignoredId, _creationTime: _ignoredCreationTime, ...rest } = value;
18 return rest;
19};
20
21const toSource = (document: Record<string, unknown>): Source =>
22 decodeSource(stripConvexSystemFields(document));
23
24const parseJsonObject = (value: string | null | undefined): Record<string, unknown> => {
25 if (!value) {
26 return {};
27 }
28
29 try {
30 const parsed = JSON.parse(value) as unknown;
31 return parsed && typeof parsed === "object" && !Array.isArray(parsed)
32 ? (parsed as Record<string, unknown>)
33 : {};
34 } catch {
35 return {};
36 }
37};
38
39const parseJsonValue = (value: string | null | undefined): unknown | null => {
40 if (!value) {
41 return null;
42 }
43
44 try {
45 return JSON.parse(value) as unknown;
46 } catch {
47 return null;
48 }
49};
50
51const asNullableString = (value: unknown): string | null =>
52 typeof value === "string" && value.trim().length > 0 ? value : null;
53
54const normalizeNamespacePart = (value: string): string => {
55 const normalized = value
56 .trim()
57 .toLowerCase()
58 .replace(/[^a-z0-9]+/g, "_")
59 .replace(/^_+|_+$/g, "");
60
61 return normalized.length > 0 ? normalized : "source";
62};
63
64const sourceNamespace = (source: Source): string => {
65 const sourceIdSuffix = source.id.slice(-6).toLowerCase();
66 return `${normalizeNamespacePart(source.name)}_${sourceIdSuffix}`;
67};
68
69const isMethod = (
70 value: string | null,
71): value is OpenApiHttpMethod | "post" =>
72 value === "get" ||
73 value === "post" ||
74 value === "put" ||
75 value === "patch" ||
76 value === "delete" ||
77 value === "head" ||
78 value === "options" ||
79 value === "trace";
80
81const methodFromCanonicalPath = (canonicalPath: string | null | undefined): OpenApiHttpMethod | "post" | null => {
82 if (!canonicalPath) {
83 return null;
84 }
85
86 const candidate = canonicalPath.trim().split(/\s+/)[0]?.toLowerCase() ?? null;
87 return isMethod(candidate) ? candidate : null;
88};
89
90const toMethod = (protocol: string, metadataJson: string | null | undefined): OpenApiHttpMethod | "post" => {
91 if (protocol !== "openapi") {
92 return "post";
93 }
94
95 const metadata = parseJsonObject(metadataJson);
96 const method = asNullableString(metadata.method)?.toLowerCase();
97
98 if (
99 method === "get" ||
100 method === "post" ||
101 method === "put" ||
102 method === "patch" ||
103 method === "delete" ||
104 method === "head" ||
105 method === "options" ||
106 method === "trace"
107 ) {
108 return method;
109 }
110
111 return "get";
112};
113
114const collectRefKeys = (value: unknown, refs: Set<string>): void => {
115 if (Array.isArray(value)) {
116 for (const item of value) {
117 collectRefKeys(item, refs);
118 }
119 return;
120 }
121
122 if (!value || typeof value !== "object") {
123 return;
124 }
125
126 const record = value as Record<string, unknown>;
127 const refValue = record.$ref;
128 if (typeof refValue === "string" && refValue.startsWith("#/")) {
129 refs.add(refValue);
130 }
131
132 for (const nestedValue of Object.values(record)) {
133 collectRefKeys(nestedValue, refs);
134 }
135};
136
137const resolveToolRefHintTableJson = async (
138 ctx: any,
139 artifactId: string,
140 inputSchemaJson: string | null | undefined,
141 outputSchemaJson: string | null | undefined,
142): Promise<string | null> => {
143 const initialRefs = new Set<string>();
144 collectRefKeys(parseJsonValue(inputSchemaJson), initialRefs);
145 collectRefKeys(parseJsonValue(outputSchemaJson), initialRefs);
146
147 if (initialRefs.size === 0) {
148 return null;
149 }
150
151 const queue = [...initialRefs];
152 const seen = new Set<string>();
153 const table: Record<string, string> = {};
154 const maxRefs = 5_000;
155
156 while (queue.length > 0 && seen.size < maxRefs) {
157 const refKey = queue.shift();
158 if (!refKey || seen.has(refKey)) {
159 continue;
160 }
161
162 seen.add(refKey);
163
164 const row = await ctx.db
165 .query("artifactSchemaRefs")
166 .withIndex("by_artifactId_refKey", (q) =>
167 q.eq("artifactId", artifactId).eq("refKey", refKey),
168 )
169 .unique();
170
171 if (!row || typeof row.schemaJson !== "string") {
172 continue;
173 }
174
175 table[refKey] = row.schemaJson;
176
177 const nestedRefs = new Set<string>();
178 collectRefKeys(parseJsonValue(row.schemaJson), nestedRefs);
179 for (const nestedRef of nestedRefs) {
180 if (!seen.has(nestedRef)) {
181 queue.push(nestedRef);
182 }
183 }
184 }
185
186 if (Object.keys(table).length === 0) {
187 return null;
188 }
189
190 return JSON.stringify(table);
191};
192
193const toSummary = (
194 source: Source,
195 toolRow: Record<string, unknown>,
196 metadataJson: string | null | undefined,
197): SourceToolSummary => {
198 const protocol = asNullableString(toolRow.protocol) ?? "openapi";
199 const canonicalPath = asNullableString(toolRow.canonicalPath);
200 const method = methodFromCanonicalPath(canonicalPath) ?? toMethod(protocol, metadataJson);
201 const toolId = asNullableString(toolRow.toolId) ?? "unknown";
202 const path = `${sourceNamespace(source)}.${toolId}`;
203
204 return {
205 sourceId: source.id,
206 sourceName: source.name,
207 sourceKind: source.kind,
208 toolId,
209 name: asNullableString(toolRow.name) ?? "Unnamed Tool",
210 description: asNullableString(toolRow.description),
211 method,
212 path,
213 operationPath: canonicalPath,
214 operationHash: asNullableString(toolRow.operationHash) ?? "",
215 };
216};
217
218const sortTools = (tools: ReadonlyArray<SourceToolSummary>): Array<SourceToolSummary> =>
219 [...tools].sort((left, right) => {
220 const leftSource = left.sourceName.toLowerCase();
221 const rightSource = right.sourceName.toLowerCase();
222
223 if (leftSource !== rightSource) {
224 return leftSource.localeCompare(rightSource);
225 }
226
227 const leftName = left.name.toLowerCase();
228 const rightName = right.name.toLowerCase();
229
230 if (leftName !== rightName) {
231 return leftName.localeCompare(rightName);
232 }
233
234 return left.toolId.localeCompare(right.toolId);
235 });
236
237export const listWorkspaceTools = query({
238 args: {
239 workspaceId: v.string(),
240 },
241 handler: async (ctx, args): Promise<Array<SourceToolSummary>> => {
242 const sourceRows = await ctx.db
243 .query("sources")
244 .withIndex("by_workspaceId", (q) => q.eq("workspaceId", args.workspaceId))
245 .collect();
246
247 const sources = sourceRows
248 .map((row) => toSource(row as unknown as Record<string, unknown>))
249 .filter((source) => source.enabled);
250 const bindings = await ctx.db
251 .query("sourceArtifactBindings")
252 .withIndex("by_workspaceId", (q) => q.eq("workspaceId", args.workspaceId))
253 .collect();
254 const bindingBySourceId = new Map<string, string>(
255 bindings.map((row) => [String(row.sourceId), String(row.artifactId)] as const),
256 );
257
258 const summaries: Array<SourceToolSummary> = [];
259
260 for (const source of sources) {
261 const artifactId = bindingBySourceId.get(source.id);
262 if (!artifactId) {
263 continue;
264 }
265
266 const artifactTools = await ctx.db
267 .query("artifactTools")
268 .withIndex("by_artifactId", (q) => q.eq("artifactId", artifactId))
269 .collect();
270
271 for (const artifactTool of artifactTools) {
272 const row = stripConvexSystemFields(artifactTool as unknown as Record<string, unknown>);
273 summaries.push(toSummary(source, row, asNullableString(row.metadataJson)));
274 }
275 }
276
277 return sortTools(summaries);
278 },
279});
280
281export const listSourceTools = query({
282 args: {
283 workspaceId: v.string(),
284 sourceId: v.string(),
285 },
286 handler: async (ctx, args): Promise<Array<SourceToolSummary>> => {
287 const sourceRow = await ctx.db
288 .query("sources")
289 .withIndex("by_domainId", (q) => q.eq("id", args.sourceId))
290 .unique();
291
292 if (!sourceRow || sourceRow.workspaceId !== args.workspaceId) {
293 return [];
294 }
295
296 const source = toSource(sourceRow as unknown as Record<string, unknown>);
297 if (!source.enabled) {
298 return [];
299 }
300
301 const binding = await ctx.db
302 .query("sourceArtifactBindings")
303 .withIndex("by_workspaceId_sourceId", (q) =>
304 q.eq("workspaceId", args.workspaceId).eq("sourceId", args.sourceId),
305 )
306 .unique();
307 if (!binding) {
308 return [];
309 }
310
311 const artifactTools = await ctx.db
312 .query("artifactTools")
313 .withIndex("by_artifactId", (q) => q.eq("artifactId", binding.artifactId))
314 .collect();
315
316 const summaries: Array<SourceToolSummary> = [];
317
318 for (const artifactTool of artifactTools) {
319 const row = stripConvexSystemFields(artifactTool as unknown as Record<string, unknown>);
320 summaries.push(toSummary(source, row, asNullableString(row.metadataJson)));
321 }
322
323 return sortTools(summaries);
324 },
325});
326
327export const getToolDetail = query({
328 args: {
329 workspaceId: v.string(),
330 sourceId: v.string(),
331 operationHash: v.string(),
332 },
333 handler: async (ctx, args): Promise<SourceToolDetail | null> => {
334 const sourceRow = await ctx.db
335 .query("sources")
336 .withIndex("by_domainId", (q) => q.eq("id", args.sourceId))
337 .unique();
338
339 if (!sourceRow || sourceRow.workspaceId !== args.workspaceId) {
340 return null;
341 }
342
343 const source = toSource(sourceRow as unknown as Record<string, unknown>);
344 const binding = await ctx.db
345 .query("sourceArtifactBindings")
346 .withIndex("by_workspaceId_sourceId", (q) =>
347 q.eq("workspaceId", args.workspaceId).eq("sourceId", args.sourceId),
348 )
349 .unique();
350 if (!binding) {
351 return null;
352 }
353
354 const artifactRows = await ctx.db
355 .query("artifactTools")
356 .withIndex("by_artifactId", (q) => q.eq("artifactId", binding.artifactId))
357 .collect();
358
359 const artifactTool = artifactRows.find((row) => row.operationHash === args.operationHash);
360 if (!artifactTool) {
361 return null;
362 }
363
364 const artifact = await ctx.db
365 .query("artifacts")
366 .withIndex("by_domainId", (q) => q.eq("id", binding.artifactId))
367 .unique();
368
369 const resolvedRefHintTableJson = source.kind === "openapi"
370 ? await resolveToolRefHintTableJson(
371 ctx,
372 binding.artifactId,
373 artifactTool.inputSchemaJson ?? null,
374 artifactTool.outputSchemaJson ?? null,
375 )
376 : null;
377
378 const summary = toSummary(
379 source,
380 stripConvexSystemFields(artifactTool as unknown as Record<string, unknown>),
381 artifactTool.metadataJson ?? null,
382 );
383
384 return {
385 ...summary,
386 inputSchemaJson: artifactTool.inputSchemaJson ?? null,
387 outputSchemaJson: artifactTool.outputSchemaJson ?? null,
388 refHintTableJson: resolvedRefHintTableJson
389 ?? artifact?.refHintTableJson
390 ?? null,
391 };
392 },
393});
apps/convex/convex/control_plane/workspaces.ts+78−0
@@ -0,0 +1,78 @@
1import { type UpsertWorkspacePayload } from "@executor-v2/management-api";
2import { WorkspaceSchema, type Workspace } from "@executor-v2/schema";
3import { v } from "convex/values";
4import * as Schema from "effect/Schema";
5
6import { mutation, query } from "../_generated/server";
7
8const decodeWorkspace = Schema.decodeUnknownSync(WorkspaceSchema);
9
10const stripConvexSystemFields = (
11 value: Record<string, unknown>,
12): Record<string, unknown> => {
13 const { _id: _ignoredId, _creationTime: _ignoredCreationTime, ...rest } = value;
14 return rest;
15};
16
17const toWorkspace = (document: Record<string, unknown>): Workspace =>
18 decodeWorkspace(stripConvexSystemFields(document));
19
20const sortWorkspaces = (workspaces: ReadonlyArray<Workspace>): Array<Workspace> =>
21 [...workspaces].sort((left, right) => {
22 const leftName = left.name.toLowerCase();
23 const rightName = right.name.toLowerCase();
24
25 if (leftName === rightName) {
26 return left.id.localeCompare(right.id);
27 }
28
29 return leftName.localeCompare(rightName);
30 });
31
32export const listWorkspaces = query({
33 args: {},
34 handler: async (ctx): Promise<Array<Workspace>> => {
35 const rows = await ctx.db.query("workspaces").collect();
36
37 return sortWorkspaces(
38 rows.map((row) => toWorkspace(row as unknown as Record<string, unknown>)),
39 );
40 },
41});
42
43export const upsertWorkspace = mutation({
44 args: {
45 payload: v.object({
46 id: v.optional(v.string()),
47 organizationId: v.string(),
48 name: v.string(),
49 }),
50 },
51 handler: async (ctx, args): Promise<Workspace> => {
52 const payload = args.payload as UpsertWorkspacePayload;
53 const now = Date.now();
54 const workspaceId = payload.id ?? `ws_${crypto.randomUUID()}`;
55
56 const existing = await ctx.db
57 .query("workspaces")
58 .withIndex("by_domainId", (q) => q.eq("id", workspaceId))
59 .unique();
60
61 const nextWorkspace = decodeWorkspace({
62 id: workspaceId,
63 organizationId: payload.organizationId,
64 name: payload.name,
65 createdByAccountId: existing?.createdByAccountId ?? null,
66 createdAt: existing?.createdAt ?? now,
67 updatedAt: now,
68 });
69
70 if (existing) {
71 await ctx.db.patch(existing._id, nextWorkspace);
72 } else {
73 await ctx.db.insert("workspaces", nextWorkspace);
74 }
75
76 return nextWorkspace;
77 },
78});
apps/convex/convex/convex.config.ts+7−0
@@ -0,0 +1,7 @@
1import workflow from "@convex-dev/workflow/convex.config.js";
2import { defineApp } from "convex/server";
3
4const app = defineApp();
5app.use(workflow);
6
7export default app;
apps/convex/convex/credential_crypto.ts+102−0
@@ -0,0 +1,102 @@
1const encryptedPrefix = "enc:v1:";
2
3const encoder = new TextEncoder();
4const decoder = new TextDecoder();
5
6const bytesToBase64 = (bytes: Uint8Array): string => {
7 let binary = "";
8 for (const byte of bytes) {
9 binary += String.fromCharCode(byte);
10 }
11 return btoa(binary);
12};
13
14const base64ToBytes = (base64: string): Uint8Array => {
15 const binary = atob(base64);
16 const bytes = new Uint8Array(binary.length);
17 for (let i = 0; i < binary.length; i += 1) {
18 bytes[i] = binary.charCodeAt(i);
19 }
20 return bytes;
21};
22
23const resolveEncryptionPassphrase = (): string => {
24 const passphrase = process.env.CREDENTIAL_ENCRYPTION_KEY?.trim() ?? "";
25 if (passphrase.length === 0) {
26 throw new Error("Encrypted credential storage requires CREDENTIAL_ENCRYPTION_KEY");
27 }
28
29 return passphrase;
30};
31
32const deriveAesKey = async (): Promise<CryptoKey> => {
33 const passphraseBytes = encoder.encode(resolveEncryptionPassphrase());
34 const hashBuffer = await crypto.subtle.digest("SHA-256", passphraseBytes);
35 return await crypto.subtle.importKey(
36 "raw",
37 hashBuffer,
38 {
39 name: "AES-GCM",
40 },
41 false,
42 ["encrypt", "decrypt"],
43 );
44};
45
46const parseEncryptedValue = (value: string): { iv: Uint8Array; cipher: Uint8Array } | null => {
47 if (!value.startsWith(encryptedPrefix)) {
48 return null;
49 }
50
51 const payload = value.slice(encryptedPrefix.length);
52 const parts = payload.split(":");
53 if (parts.length !== 2) {
54 return null;
55 }
56
57 try {
58 return {
59 iv: base64ToBytes(parts[0] ?? ""),
60 cipher: base64ToBytes(parts[1] ?? ""),
61 };
62 } catch {
63 return null;
64 }
65};
66
67export const isEncryptedSecret = (value: string): boolean =>
68 value.startsWith(encryptedPrefix);
69
70export const encryptSecretValue = async (plainText: string): Promise<string> => {
71 const key = await deriveAesKey();
72 const iv = crypto.getRandomValues(new Uint8Array(12));
73 const encrypted = await crypto.subtle.encrypt(
74 {
75 name: "AES-GCM",
76 iv,
77 },
78 key,
79 encoder.encode(plainText),
80 );
81
82 return `${encryptedPrefix}${bytesToBase64(iv)}:${bytesToBase64(new Uint8Array(encrypted))}`;
83};
84
85export const decryptSecretValue = async (storedValue: string): Promise<string> => {
86 const parsed = parseEncryptedValue(storedValue);
87 if (parsed === null) {
88 throw new Error("Credential secret is not encrypted");
89 }
90
91 const key = await deriveAesKey();
92 const decrypted = await crypto.subtle.decrypt(
93 {
94 name: "AES-GCM",
95 iv: parsed.iv as unknown as BufferSource,
96 },
97 key,
98 parsed.cipher as unknown as BufferSource,
99 );
100
101 return decoder.decode(decrypted);
102};
apps/convex/convex/credential_resolver.ts+198−0
@@ -0,0 +1,198 @@
1import {
2 buildCredentialHeaders,
3 CredentialResolverError,
4 extractCredentialResolutionContext,
5 makeCredentialResolver,
6 selectCredentialBinding,
7 selectOAuthAccessToken,
8 sourceIdFromSourceKey,
9 type ResolveToolCredentials,
10} from "@executor-v2/engine";
11import {
12 OAuthTokenSchema,
13 SourceCredentialBindingSchema,
14 type OAuthToken,
15 type SourceCredentialBinding,
16} from "@executor-v2/schema";
17import { v } from "convex/values";
18import * as Effect from "effect/Effect";
19import * as Schema from "effect/Schema";
20
21import { api } from "./_generated/api";
22import { query, type ActionCtx } from "./_generated/server";
23import { decryptSecretValue } from "./credential_crypto";
24
25const decodeSourceCredentialBinding = Schema.decodeUnknownSync(
26 SourceCredentialBindingSchema,
27);
28const decodeOAuthToken = Schema.decodeUnknownSync(OAuthTokenSchema);
29
30const stripConvexSystemFields = (
31 value: Record<string, unknown>,
32): Record<string, unknown> => {
33 const { _id: _ignoredId, _creationTime: _ignoredCreationTime, ...rest } = value;
34 return rest;
35};
36
37export const listCredentialBindingsForSource = query({
38 args: {
39 workspaceId: v.string(),
40 sourceKey: v.string(),
41 organizationId: v.optional(v.string()),
42 accountId: v.optional(v.string()),
43 },
44 handler: async (ctx, args): Promise<Array<SourceCredentialBinding>> => {
45 const rows = await ctx.db
46 .query("sourceCredentialBindings")
47 .withIndex("by_sourceKey", (q) => q.eq("sourceKey", args.sourceKey))
48 .collect();
49
50 return rows
51 .map((row) =>
52 decodeSourceCredentialBinding(
53 stripConvexSystemFields(row as unknown as Record<string, unknown>),
54 ),
55 )
56 .filter((binding) => {
57 if (binding.scopeType === "workspace") {
58 return binding.workspaceId === args.workspaceId;
59 }
60
61 if (binding.scopeType === "organization") {
62 return args.organizationId
63 ? binding.organizationId === args.organizationId
64 : true;
65 }
66
67 return args.accountId ? binding.accountId === args.accountId : true;
68 });
69 },
70});
71
72export const listOAuthTokensForSource = query({
73 args: {
74 workspaceId: v.string(),
75 sourceId: v.string(),
76 },
77 handler: async (ctx, args): Promise<Array<OAuthToken>> => {
78 const rows = await ctx.db
79 .query("oauthTokens")
80 .withIndex("by_sourceId", (q) => q.eq("sourceId", args.sourceId))
81 .collect();
82
83 return rows
84 .map((row) =>
85 decodeOAuthToken(
86 stripConvexSystemFields(row as unknown as Record<string, unknown>),
87 ),
88 )
89 .filter((token) => token.workspaceId === args.workspaceId);
90 },
91});
92
93const toCredentialResolverError = (
94 operation: string,
95 message: string,
96 details: string | null,
97): CredentialResolverError =>
98 new CredentialResolverError({
99 operation,
100 message,
101 details,
102 });
103
104const runQueryEffect = <T>(
105 operation: string,
106 run: () => Promise<T>,
107): Effect.Effect<T, CredentialResolverError> =>
108 Effect.tryPromise({
109 try: run,
110 catch: (cause) =>
111 toCredentialResolverError(
112 operation,
113 "Convex credential query failed",
114 String(cause),
115 ),
116 });
117
118const requireLocalSecretProvider = (
119 secretProvider: SourceCredentialBinding["secretProvider"],
120): "local" => {
121 if (secretProvider !== "local") {
122 throw new Error("Convex credentials require secretProvider 'local'");
123 }
124
125 return "local";
126};
127
128export const createConvexResolveToolCredentials = (
129 ctx: ActionCtx,
130): ResolveToolCredentials =>
131 makeCredentialResolver((input) =>
132 Effect.gen(function* () {
133 const context = extractCredentialResolutionContext(input);
134 if (context === null) {
135 return {
136 headers: {},
137 };
138 }
139
140 const bindings = yield* runQueryEffect(
141 "list_credential_bindings",
142 () =>
143 ctx.runQuery(api.credential_resolver.listCredentialBindingsForSource, {
144 workspaceId: context.workspaceId,
145 sourceKey: context.sourceKey,
146 organizationId: context.organizationId ?? undefined,
147 accountId: context.accountId ?? undefined,
148 }),
149 );
150
151 const binding = selectCredentialBinding(bindings, context);
152 if (binding === null) {
153 return {
154 headers: {},
155 };
156 }
157
158 const sourceId = sourceIdFromSourceKey(context.sourceKey);
159
160 const oauthAccessToken =
161 binding.provider === "oauth2" && sourceId
162 ? yield* runQueryEffect("list_oauth_tokens", () =>
163 ctx
164 .runQuery(api.credential_resolver.listOAuthTokensForSource, {
165 workspaceId: context.workspaceId,
166 sourceId,
167 })
168 .then((tokens) =>
169 selectOAuthAccessToken(tokens, context, sourceId),
170 ),
171 )
172 : null;
173
174 requireLocalSecretProvider(binding.secretProvider);
175
176 const secretRef = yield* Effect.tryPromise({
177 try: () => decryptSecretValue(binding.secretRef),
178 catch: (cause) =>
179 toCredentialResolverError(
180 "decrypt_credential_secret",
181 "Convex credential decryption failed",
182 String(cause),
183 ),
184 });
185
186 return {
187 headers: buildCredentialHeaders(
188 {
189 ...binding,
190 secretRef,
191 },
192 {
193 oauthAccessToken,
194 },
195 ),
196 };
197 }),
198 );
apps/convex/convex/executor.test.ts+1489−0
@@ -0,0 +1,1489 @@
1import { describe, expect, it } from "@effect/vitest";
2import { extractOpenApiManifest } from "@executor-v2/management-api";
3import { convexTest } from "convex-test";
4import * as Effect from "effect/Effect";
5
6import { api, internal } from "./_generated/api";
7import { executeRunImpl } from "./executor";
8import schema from "./schema";
9
10const runtimeInternal = internal as any;
11
12const setup = () =>
13 convexTest(schema, {
14 "./http.ts": () => import("./http"),
15 "./mcp.ts": () => import("./mcp"),
16 "./executor.ts": () => import("./executor"),
17 "./runtimeCallbacks.ts": () => import("./runtimeCallbacks"),
18 "./source_tool_registry.ts": () => import("./source_tool_registry"),
19 "./task_runs.ts": () => import("./task_runs"),
20 "./control_plane/storage.ts": () => import("./control_plane/storage"),
21 "./control_plane/credentials.ts": () => import("./control_plane/credentials"),
22 "./control_plane/sources.ts": () => import("./control_plane/sources"),
23 "./control_plane/tool_registry.ts": () => import("./control_plane/tool_registry"),
24 "./control_plane/openapi_ingest.ts": () => import("./control_plane/openapi_ingest"),
25 "./workflow.ts": () => import("./workflow"),
26 "./controlPlane.ts": () => import("./controlPlane"),
27 "./_generated/api.js": () => import("./_generated/api.js"),
28 });
29
30const ensureWorkspace = async (
31 t: ReturnType<typeof setup>,
32 workspaceId: string,
33 organizationId: string,
34): Promise<void> => {
35 await t.mutation(api.controlPlane.upsertWorkspace, {
36 payload: {
37 id: workspaceId,
38 organizationId,
39 name: workspaceId,
40 },
41 });
42};
43
44describe("Convex executor and control-plane", () => {
45 it.effect("executes code via executeRunImpl", () =>
46 Effect.gen(function* () {
47 const originalEnv = {
48 runUrl: process.env.CLOUDFLARE_SANDBOX_RUN_URL,
49 authToken: process.env.CLOUDFLARE_SANDBOX_AUTH_TOKEN,
50 callbackUrl: process.env.CLOUDFLARE_SANDBOX_CALLBACK_URL,
51 };
52 const originalFetch = globalThis.fetch;
53
54 try {
55 process.env.CLOUDFLARE_SANDBOX_RUN_URL = "https://sandbox.local/run";
56 process.env.CLOUDFLARE_SANDBOX_AUTH_TOKEN = "sandbox-token";
57 process.env.CLOUDFLARE_SANDBOX_CALLBACK_URL = "https://convex.local/callback";
58
59 globalThis.fetch = (async (
60 input: RequestInfo | URL,
61 init?: RequestInit,
62 ) => {
63 const url = typeof input === "string" ? input : input.toString();
64 if (url !== "https://sandbox.local/run") {
65 throw new Error(`Unexpected URL: ${url}`);
66 }
67
68 expect(init?.method).toBe("POST");
69 const headers = new Headers(init?.headers as HeadersInit | undefined);
70 expect(headers.get("authorization")).toBe(
71 "Bearer sandbox-token",
72 );
73
74 return new Response(
75 JSON.stringify({
76 status: "completed",
77 result: 42,
78 }),
79 {
80 status: 200,
81 headers: {
82 "content-type": "application/json",
83 },
84 },
85 );
86 }) as unknown as typeof fetch;
87
88 const result = yield* executeRunImpl({
89 code: "return 6 * 7;",
90 });
91
92 expect(result.status).toBe("completed");
93 expect(result.result).toBe(42);
94 } finally {
95 globalThis.fetch = originalFetch;
96
97 if (originalEnv.runUrl === undefined) {
98 delete process.env.CLOUDFLARE_SANDBOX_RUN_URL;
99 } else {
100 process.env.CLOUDFLARE_SANDBOX_RUN_URL = originalEnv.runUrl;
101 }
102
103 if (originalEnv.authToken === undefined) {
104 delete process.env.CLOUDFLARE_SANDBOX_AUTH_TOKEN;
105 } else {
106 process.env.CLOUDFLARE_SANDBOX_AUTH_TOKEN = originalEnv.authToken;
107 }
108
109 if (originalEnv.callbackUrl === undefined) {
110 delete process.env.CLOUDFLARE_SANDBOX_CALLBACK_URL;
111 } else {
112 process.env.CLOUDFLARE_SANDBOX_CALLBACK_URL = originalEnv.callbackUrl;
113 }
114 }
115 }),
116 );
117
118 it.effect("upserts, lists, and removes sources", () =>
119 Effect.gen(function* () {
120 const t = setup();
121
122 const added = (yield* Effect.tryPromise(() =>
123 t.action(api.controlPlane.upsertSource as any, {
124 workspaceId: "ws_1",
125 payload: {
126 id: "src_1",
127 name: "Weather",
128 kind: "openapi",
129 endpoint: "https://example.com/openapi.json",
130 enabled: true,
131 configJson: "{}",
132 status: "draft",
133 sourceHash: null,
134 lastError: null,
135 },
136 }),
137 )) as {
138 id: string;
139 workspaceId: string;
140 name: string;
141 };
142
143 yield* Effect.tryPromise(() => t.finishAllScheduledFunctions(() => {}));
144
145 expect(added.id).toBe("src_1");
146 expect(added.workspaceId).toBe("ws_1");
147 expect(added.name).toBe("Weather");
148
149 const listed = (yield* Effect.tryPromise(() =>
150 t.query(api.controlPlane.listSources, {
151 workspaceId: "ws_1",
152 }),
153 )) as Array<{
154 id: string;
155 }>;
156
157 expect(listed).toHaveLength(1);
158 expect(listed[0]?.id).toBe("src_1");
159
160 const removed = (yield* Effect.tryPromise(() =>
161 t.mutation(api.controlPlane.removeSource, {
162 workspaceId: "ws_1",
163 sourceId: "src_1",
164 }),
165 )) as {
166 removed: boolean;
167 };
168
169 expect(removed.removed).toBe(true);
170
171 const listedAfterRemove = (yield* Effect.tryPromise(() =>
172 t.query(api.controlPlane.listSources, {
173 workspaceId: "ws_1",
174 }),
175 )) as Array<unknown>;
176
177 expect(listedAfterRemove).toHaveLength(0);
178 }),
179 );
180
181 it.effect("upserts, lists, and removes credentials, policies, and storage", () =>
182 Effect.gen(function* () {
183 const t = setup();
184
185 yield* Effect.tryPromise(() => ensureWorkspace(t, "ws_1", "org_1"));
186
187 const addedCredential = (yield* Effect.tryPromise(() =>
188 t.action(api.controlPlane.upsertCredentialBinding, {
189 workspaceId: "ws_1",
190 payload: {
191 id: "credential_binding_1",
192 credentialId: "cred_1",
193 scopeType: "workspace",
194 sourceKey: "github",
195 provider: "bearer",
196 secretRef: "secret://github/token",
197 accountId: null,
198 additionalHeadersJson: null,
199 boundAuthFingerprint: null,
200 },
201 }),
202 )) as {
203 id: string;
204 workspaceId: string | null;
205 };
206
207 expect(addedCredential.id).toBe("credential_binding_1");
208 expect(addedCredential.workspaceId).toBe("ws_1");
209
210 const listedCredentials = (yield* Effect.tryPromise(() =>
211 t.query(api.controlPlane.listCredentialBindings, {
212 workspaceId: "ws_1",
213 }),
214 )) as Array<{
215 id: string;
216 }>;
217
218 expect(listedCredentials).toHaveLength(1);
219 expect(listedCredentials[0]?.id).toBe("credential_binding_1");
220
221 const removedCredential = (yield* Effect.tryPromise(() =>
222 t.mutation(api.controlPlane.removeCredentialBinding, {
223 workspaceId: "ws_1",
224 credentialBindingId: "credential_binding_1",
225 }),
226 )) as {
227 removed: boolean;
228 };
229
230 expect(removedCredential.removed).toBe(true);
231
232 const listedCredentialsAfterRemove = (yield* Effect.tryPromise(() =>
233 t.query(api.controlPlane.listCredentialBindings, {
234 workspaceId: "ws_1",
235 }),
236 )) as Array<unknown>;
237
238 expect(listedCredentialsAfterRemove).toHaveLength(0);
239
240 const addedPolicy = (yield* Effect.tryPromise(() =>
241 t.mutation(api.controlPlane.upsertPolicy, {
242 workspaceId: "ws_1",
243 payload: {
244 id: "pol_1",
245 toolPathPattern: "github.repos.*",
246 decision: "require_approval",
247 },
248 }),
249 )) as {
250 id: string;
251 workspaceId: string;
252 };
253
254 expect(addedPolicy.id).toBe("pol_1");
255 expect(addedPolicy.workspaceId).toBe("ws_1");
256
257 const listedPolicies = (yield* Effect.tryPromise(() =>
258 t.query(api.controlPlane.listPolicies, {
259 workspaceId: "ws_1",
260 }),
261 )) as Array<{
262 id: string;
263 }>;
264
265 expect(listedPolicies).toHaveLength(1);
266 expect(listedPolicies[0]?.id).toBe("pol_1");
267
268 const removedPolicy = (yield* Effect.tryPromise(() =>
269 t.mutation(api.controlPlane.removePolicy, {
270 workspaceId: "ws_1",
271 policyId: "pol_1",
272 }),
273 )) as {
274 removed: boolean;
275 };
276
277 expect(removedPolicy.removed).toBe(true);
278
279 const listedPoliciesAfterRemove = (yield* Effect.tryPromise(() =>
280 t.query(api.controlPlane.listPolicies, {
281 workspaceId: "ws_1",
282 }),
283 )) as Array<unknown>;
284
285 expect(listedPoliciesAfterRemove).toHaveLength(0);
286
287 const openedStorage = (yield* Effect.tryPromise(() =>
288 t.mutation(api.controlPlane.openStorageInstance, {
289 workspaceId: "ws_1",
290 payload: {
291 scopeType: "workspace",
292 durability: "ephemeral",
293 provider: "agentfs-local",
294 purpose: "test storage",
295 ttlHours: 1,
296 sessionId: "session_1",
297 },
298 }),
299 )) as {
300 id: string;
301 status: string;
302 };
303
304 expect(openedStorage.status).toBe("active");
305
306 const listedStorage = (yield* Effect.tryPromise(() =>
307 t.query(api.controlPlane.listStorageInstances, {
308 workspaceId: "ws_1",
309 }),
310 )) as Array<{
311 id: string;
312 }>;
313
314 expect(listedStorage).toHaveLength(1);
315 expect(listedStorage[0]?.id).toBe(openedStorage.id);
316
317 yield* Effect.tryPromise(() =>
318 t.mutation(runtimeInternal.control_plane.storage.upsertStorageFileEntry, {
319 workspaceId: "ws_1",
320 storageInstanceId: openedStorage.id,
321 payload: {
322 path: "/notes/today.txt",
323 content: "hello convex storage",
324 },
325 }),
326 );
327
328 const listedDirectory = (yield* Effect.tryPromise(() =>
329 t.query(api.controlPlane.listStorageDirectory, {
330 workspaceId: "ws_1",
331 storageInstanceId: openedStorage.id,
332 payload: {
333 path: "/",
334 },
335 }),
336 )) as {
337 path: string;
338 entries: ReadonlyArray<{
339 name: string;
340 path: string;
341 kind: "file" | "directory";
342 }>;
343 };
344
345 expect(listedDirectory.path).toBe("/");
346 expect(listedDirectory.entries).toHaveLength(1);
347 expect(listedDirectory.entries[0]?.name).toBe("notes");
348 expect(listedDirectory.entries[0]?.kind).toBe("directory");
349
350 const listedNestedDirectory = (yield* Effect.tryPromise(() =>
351 t.query(api.controlPlane.listStorageDirectory, {
352 workspaceId: "ws_1",
353 storageInstanceId: openedStorage.id,
354 payload: {
355 path: "/notes",
356 },
357 }),
358 )) as {
359 path: string;
360 entries: ReadonlyArray<{
361 name: string;
362 path: string;
363 kind: "file" | "directory";
364 }>;
365 };
366
367 expect(listedNestedDirectory.path).toBe("/notes");
368 expect(listedNestedDirectory.entries).toHaveLength(1);
369 expect(listedNestedDirectory.entries[0]?.name).toBe("today.txt");
370 expect(listedNestedDirectory.entries[0]?.kind).toBe("file");
371
372 const readStorageFile = (yield* Effect.tryPromise(() =>
373 t.query(api.controlPlane.readStorageFile, {
374 workspaceId: "ws_1",
375 storageInstanceId: openedStorage.id,
376 payload: {
377 path: "/notes/today.txt",
378 encoding: "utf8",
379 },
380 }),
381 )) as {
382 content: string;
383 };
384
385 expect(readStorageFile.content).toBe("hello convex storage");
386
387 yield* Effect.tryPromise(() =>
388 t.mutation(runtimeInternal.control_plane.storage.upsertStorageKvEntry, {
389 workspaceId: "ws_1",
390 storageInstanceId: openedStorage.id,
391 payload: {
392 key: "feature.enabled",
393 valueJson: "true",
394 },
395 }),
396 );
397
398 const listedKv = (yield* Effect.tryPromise(() =>
399 t.query(api.controlPlane.listStorageKv, {
400 workspaceId: "ws_1",
401 storageInstanceId: openedStorage.id,
402 payload: {
403 prefix: "feature.",
404 },
405 }),
406 )) as {
407 items: Array<{
408 key: string;
409 value: unknown;
410 }>;
411 };
412
413 expect(listedKv.items).toHaveLength(1);
414 expect(listedKv.items[0]?.key).toBe("feature.enabled");
415 expect(listedKv.items[0]?.value).toBe(true);
416
417 yield* Effect.tryPromise(() =>
418 t.mutation(api.controlPlane.queryStorageSql, {
419 workspaceId: "ws_1",
420 storageInstanceId: openedStorage.id,
421 payload: {
422 sql: "CREATE TABLE IF NOT EXISTS kv_store (key TEXT PRIMARY KEY, value TEXT NOT NULL);",
423 },
424 }),
425 );
426
427 yield* Effect.tryPromise(() =>
428 t.mutation(api.controlPlane.queryStorageSql, {
429 workspaceId: "ws_1",
430 storageInstanceId: openedStorage.id,
431 payload: {
432 sql: "INSERT INTO kv_store (key, value) VALUES ('hello', 'world');",
433 },
434 }),
435 );
436
437 const queriedSql = (yield* Effect.tryPromise(() =>
438 t.mutation(api.controlPlane.queryStorageSql, {
439 workspaceId: "ws_1",
440 storageInstanceId: openedStorage.id,
441 payload: {
442 sql: "SELECT key, value FROM kv_store LIMIT 10;",
443 },
444 }),
445 )) as {
446 rowCount: number;
447 columns: Array<string>;
448 rows: Array<Record<string, unknown>>;
449 };
450
451 expect(queriedSql.rowCount).toBe(1);
452 expect(queriedSql.columns).toEqual(["key", "value"]);
453 expect(queriedSql.rows[0]).toEqual({ key: "hello", value: "world" });
454
455 const closedStorage = (yield* Effect.tryPromise(() =>
456 t.mutation(api.controlPlane.closeStorageInstance, {
457 workspaceId: "ws_1",
458 storageInstanceId: openedStorage.id,
459 }),
460 )) as {
461 id: string;
462 status: string;
463 };
464
465 expect(closedStorage.id).toBe(openedStorage.id);
466 expect(closedStorage.status).toBe("closed");
467
468 const removedStorage = (yield* Effect.tryPromise(() =>
469 t.mutation(api.controlPlane.removeStorageInstance, {
470 workspaceId: "ws_1",
471 storageInstanceId: openedStorage.id,
472 }),
473 )) as {
474 removed: boolean;
475 };
476
477 expect(removedStorage.removed).toBe(true);
478
479 const listedStorageAfterRemove = (yield* Effect.tryPromise(() =>
480 t.query(api.controlPlane.listStorageInstances, {
481 workspaceId: "ws_1",
482 }),
483 )) as Array<unknown>;
484
485 expect(listedStorageAfterRemove).toHaveLength(0);
486 }),
487 );
488
489 it.effect("upserts and lists organizations/workspaces and tool views", () =>
490 Effect.gen(function* () {
491 const t = setup();
492
493 const organization = (yield* Effect.tryPromise(() =>
494 t.mutation(api.controlPlane.upsertOrganization, {
495 payload: {
496 id: "org_1",
497 slug: "acme",
498 name: "Acme Inc",
499 status: "active",
500 },
501 }),
502 )) as {
503 id: string;
504 name: string;
505 };
506
507 expect(organization.id).toBe("org_1");
508 expect(organization.name).toBe("Acme Inc");
509
510 const organizations = (yield* Effect.tryPromise(() =>
511 t.query(api.controlPlane.listOrganizations, {}),
512 )) as Array<{
513 id: string;
514 }>;
515
516 expect(organizations).toHaveLength(1);
517 expect(organizations[0]?.id).toBe("org_1");
518
519 const workspace = (yield* Effect.tryPromise(() =>
520 t.mutation(api.controlPlane.upsertWorkspace, {
521 payload: {
522 id: "ws_1",
523 organizationId: "org_1",
524 name: "Primary Workspace",
525 },
526 }),
527 )) as {
528 id: string;
529 organizationId: string;
530 };
531
532 expect(workspace.id).toBe("ws_1");
533 expect(workspace.organizationId).toBe("org_1");
534
535 const workspaces = (yield* Effect.tryPromise(() =>
536 t.query(api.controlPlane.listWorkspaces, {}),
537 )) as Array<{
538 id: string;
539 }>;
540
541 expect(workspaces).toHaveLength(1);
542 expect(workspaces[0]?.id).toBe("ws_1");
543
544 const nowForOpenApiSource = Date.now();
545 yield* Effect.tryPromise(() =>
546 t.run(async (ctx) => {
547 await ctx.db.insert("sources", {
548 id: "src_1",
549 workspaceId: "ws_1",
550 name: "Weather API",
551 kind: "openapi",
552 endpoint: "https://example.com/openapi.json",
553 enabled: true,
554 configJson: "{}",
555 status: "draft",
556 sourceHash: null,
557 lastError: null,
558 createdAt: nowForOpenApiSource,
559 updatedAt: nowForOpenApiSource,
560 });
561 }),
562 );
563
564 const manifest = yield* extractOpenApiManifest("Weather API", {
565 openapi: "3.0.0",
566 info: {
567 title: "Weather API",
568 version: "1.0.0",
569 },
570 paths: {
571 "/weather": {
572 get: {
573 operationId: "getWeather",
574 responses: {
575 "200": {
576 description: "ok",
577 },
578 },
579 },
580 },
581 },
582 });
583
584 const now = Date.now();
585 const openApiArtifactMeta = (yield* Effect.tryPromise(() =>
586 t.mutation(runtimeInternal.control_plane.tool_registry.upsertArtifactMeta, {
587 protocol: "openapi",
588 contentHash: manifest.sourceHash,
589 extractorVersion: "openapi_v2",
590 toolCount: manifest.tools.length,
591 refHintTableJson: manifest.refHintTable ? JSON.stringify(manifest.refHintTable) : null,
592 }),
593 )) as {
594 artifactId: string;
595 created: boolean;
596 };
597
598 yield* Effect.tryPromise(() =>
599 t.mutation(runtimeInternal.control_plane.tool_registry.putArtifactToolsBatch, {
600 artifactId: openApiArtifactMeta.artifactId,
601 protocol: "openapi",
602 insertOnly: true,
603 tools: manifest.tools.map((tool) => ({
604 toolId: tool.toolId,
605 name: tool.name,
606 description: tool.description,
607 canonicalPath: `${tool.method.toUpperCase()} ${tool.path}`,
608 operationHash: tool.operationHash,
609 invocationJson: JSON.stringify(tool.invocation),
610 inputSchemaJson: tool.typing?.inputSchemaJson ?? null,
611 outputSchemaJson: tool.typing?.outputSchemaJson ?? null,
612 metadataJson: JSON.stringify({
613 method: tool.method,
614 path: tool.path,
615 }),
616 })),
617 }),
618 );
619
620 yield* Effect.tryPromise(() =>
621 t.mutation(runtimeInternal.control_plane.tool_registry.bindSourceToArtifact, {
622 workspaceId: "ws_1",
623 sourceId: "src_1",
624 artifactId: openApiArtifactMeta.artifactId,
625 }),
626 );
627
628 yield* Effect.tryPromise(() =>
629 t.mutation(runtimeInternal.control_plane.tool_registry.replaceWorkspaceSourceToolIndex, {
630 workspaceId: "ws_1",
631 sourceId: "src_1",
632 sourceName: "Weather API",
633 sourceKind: "openapi",
634 artifactId: openApiArtifactMeta.artifactId,
635 namespace: "weather_api_src_1",
636 refHintTableJson: manifest.refHintTable ? JSON.stringify(manifest.refHintTable) : null,
637 rows: manifest.tools.map((tool) => ({
638 toolId: tool.toolId,
639 protocol: "openapi",
640 method: tool.method,
641 path: `weather_api_src_1.${tool.toolId}`,
642 name: tool.name,
643 description: tool.description,
644 searchText: `weather api ${tool.name.toLowerCase()} ${tool.path.toLowerCase()} ${tool.method.toLowerCase()}`,
645 operationHash: tool.operationHash,
646 approvalMode: "auto",
647 status: "active",
648 })),
649 }),
650 );
651
652 const workspaceTools = (yield* Effect.tryPromise(() =>
653 t.query(api.controlPlane.listWorkspaceTools, {
654 workspaceId: "ws_1",
655 }),
656 )) as Array<{
657 sourceId: string;
658 }>;
659
660 expect(workspaceTools).toHaveLength(1);
661 expect(workspaceTools[0]?.sourceId).toBe("src_1");
662
663 const sourceTools = (yield* Effect.tryPromise(() =>
664 t.query(api.controlPlane.listSourceTools, {
665 workspaceId: "ws_1",
666 sourceId: "src_1",
667 }),
668 )) as Array<{
669 sourceId: string;
670 }>;
671
672 expect(sourceTools).toHaveLength(1);
673 expect(sourceTools[0]?.sourceId).toBe("src_1");
674
675 const nowForGraphqlSource = Date.now();
676 yield* Effect.tryPromise(() =>
677 t.run(async (ctx) => {
678 await ctx.db.insert("sources", {
679 id: "src_graphql_1",
680 workspaceId: "ws_1",
681 name: "Linear API",
682 kind: "graphql",
683 endpoint: "https://api.linear.app/graphql",
684 enabled: true,
685 configJson: "{}",
686 status: "draft",
687 sourceHash: null,
688 lastError: null,
689 createdAt: nowForGraphqlSource,
690 updatedAt: nowForGraphqlSource,
691 });
692 }),
693 );
694
695 const graphqlArtifactMeta = (yield* Effect.tryPromise(() =>
696 t.mutation(runtimeInternal.control_plane.tool_registry.upsertArtifactMeta, {
697 protocol: "graphql",
698 contentHash: "graphql_schema_hash_1",
699 extractorVersion: "graphql_v1",
700 toolCount: 2,
701 refHintTableJson: null,
702 }),
703 )) as {
704 artifactId: string;
705 created: boolean;
706 };
707
708 expect(graphqlArtifactMeta.created).toBe(true);
709
710 yield* Effect.tryPromise(() =>
711 t.mutation(runtimeInternal.control_plane.tool_registry.putArtifactToolsBatch, {
712 artifactId: graphqlArtifactMeta.artifactId,
713 protocol: "graphql",
714 insertOnly: true,
715 tools: [
716 {
717 toolId: "linear.graphql",
718 name: "Linear GraphQL",
719 description: "Run raw GraphQL queries against Linear",
720 canonicalPath: "raw.graphql",
721 operationHash: "raw_hash",
722 invocationJson: "{}",
723 metadataJson: JSON.stringify({
724 operationType: "raw",
725 fieldName: "graphql",
726 }),
727 },
728 {
729 toolId: "linear.query.viewer",
730 name: "viewer",
731 description: "Current viewer",
732 canonicalPath: "query.viewer",
733 operationHash: "viewer_hash",
734 invocationJson: "{}",
735 metadataJson: JSON.stringify({
736 operationType: "query",
737 fieldName: "viewer",
738 }),
739 },
740 ],
741 }),
742 );
743
744 yield* Effect.tryPromise(() =>
745 t.mutation(runtimeInternal.control_plane.tool_registry.bindSourceToArtifact, {
746 workspaceId: "ws_1",
747 sourceId: "src_graphql_1",
748 artifactId: graphqlArtifactMeta.artifactId,
749 }),
750 );
751
752 yield* Effect.tryPromise(() =>
753 t.mutation(runtimeInternal.control_plane.tool_registry.replaceWorkspaceSourceToolIndex, {
754 workspaceId: "ws_1",
755 sourceId: "src_graphql_1",
756 sourceName: "Linear API",
757 sourceKind: "graphql",
758 artifactId: graphqlArtifactMeta.artifactId,
759 namespace: "linear_api_phql_1",
760 refHintTableJson: null,
761 rows: [
762 {
763 toolId: "linear.graphql",
764 protocol: "graphql",
765 method: "post",
766 path: "linear_api_phql_1.linear.graphql",
767 name: "Linear GraphQL",
768 description: "Run raw GraphQL queries against Linear",
769 searchText: "linear api graphql linear.graphql",
770 operationHash: "raw_hash",
771 approvalMode: "auto",
772 status: "active",
773 },
774 {
775 toolId: "linear.query.viewer",
776 protocol: "graphql",
777 method: "post",
778 path: "linear_api_phql_1.linear.query.viewer",
779 name: "viewer",
780 description: "Current viewer",
781 searchText: "linear api graphql viewer linear.query.viewer",
782 operationHash: "viewer_hash",
783 approvalMode: "auto",
784 status: "active",
785 },
786 ],
787 }),
788 );
789
790 const graphqlSourceTools = (yield* Effect.tryPromise(() =>
791 t.query(api.controlPlane.listSourceTools, {
792 workspaceId: "ws_1",
793 sourceId: "src_graphql_1",
794 }),
795 )) as Array<{
796 sourceId: string;
797 toolId: string;
798 method: string;
799 }>;
800
801 expect(graphqlSourceTools).toHaveLength(2);
802 expect(graphqlSourceTools[0]?.sourceId).toBe("src_graphql_1");
803 expect(graphqlSourceTools[0]?.method).toBe("post");
804
805 const workspaceToolsWithGraphql = (yield* Effect.tryPromise(() =>
806 t.query(api.controlPlane.listWorkspaceTools, {
807 workspaceId: "ws_1",
808 }),
809 )) as Array<{
810 sourceId: string;
811 }>;
812
813 expect(workspaceToolsWithGraphql.some((tool) => tool.sourceId === "src_graphql_1")).toBe(
814 true,
815 );
816
817 const nowForMcpSource = Date.now();
818
819 yield* Effect.tryPromise(() =>
820 t.run(async (ctx) => {
821 await ctx.db.insert("sources", {
822 id: "src_mcp_1",
823 workspaceId: "ws_1",
824 name: "Deepwiki",
825 kind: "mcp",
826 endpoint: "https://example.com/mcp",
827 enabled: true,
828 configJson: "{}",
829 status: "draft",
830 sourceHash: null,
831 lastError: null,
832 createdAt: nowForMcpSource,
833 updatedAt: nowForMcpSource,
834 });
835 }),
836 );
837
838 const mcpArtifactMeta = (yield* Effect.tryPromise(() =>
839 t.mutation(runtimeInternal.control_plane.tool_registry.upsertArtifactMeta, {
840 protocol: "mcp",
841 contentHash: "mcp_source_hash_1",
842 extractorVersion: "mcp_v1",
843 toolCount: 1,
844 refHintTableJson: null,
845 }),
846 )) as {
847 artifactId: string;
848 created: boolean;
849 };
850
851 expect(mcpArtifactMeta.created).toBe(true);
852
853 yield* Effect.tryPromise(() =>
854 t.mutation(runtimeInternal.control_plane.tool_registry.putArtifactToolsBatch, {
855 artifactId: mcpArtifactMeta.artifactId,
856 protocol: "mcp",
857 insertOnly: true,
858 tools: [
859 {
860 toolId: "deepwiki.mcp.search_docs",
861 name: "search_docs",
862 description: "Search docs",
863 canonicalPath: "search_docs",
864 operationHash: "mcp_hash_1",
865 invocationJson: "{}",
866 metadataJson: JSON.stringify({
867 toolName: "search_docs",
868 }),
869 },
870 ],
871 }),
872 );
873
874 yield* Effect.tryPromise(() =>
875 t.mutation(runtimeInternal.control_plane.tool_registry.bindSourceToArtifact, {
876 workspaceId: "ws_1",
877 sourceId: "src_mcp_1",
878 artifactId: mcpArtifactMeta.artifactId,
879 }),
880 );
881
882 yield* Effect.tryPromise(() =>
883 t.mutation(runtimeInternal.control_plane.tool_registry.replaceWorkspaceSourceToolIndex, {
884 workspaceId: "ws_1",
885 sourceId: "src_mcp_1",
886 sourceName: "Deepwiki",
887 sourceKind: "mcp",
888 artifactId: mcpArtifactMeta.artifactId,
889 namespace: "deepwiki_mcp_1",
890 refHintTableJson: null,
891 rows: [
892 {
893 toolId: "deepwiki.mcp.search_docs",
894 protocol: "mcp",
895 method: "post",
896 path: "deepwiki_mcp_1.deepwiki.mcp.search_docs",
897 name: "search_docs",
898 description: "Search docs",
899 searchText: "deepwiki mcp search docs",
900 operationHash: "mcp_hash_1",
901 approvalMode: "auto",
902 status: "active",
903 },
904 ],
905 }),
906 );
907
908 const mcpSourceTools = (yield* Effect.tryPromise(() =>
909 t.query(api.controlPlane.listSourceTools, {
910 workspaceId: "ws_1",
911 sourceId: "src_mcp_1",
912 }),
913 )) as Array<{
914 sourceId: string;
915 path: string;
916 }>;
917
918 expect(mcpSourceTools).toHaveLength(1);
919 expect(mcpSourceTools[0]?.sourceId).toBe("src_mcp_1");
920 expect(mcpSourceTools[0]?.path).toContain("deepwiki.mcp.search_docs");
921
922 const workspaceToolsWithMcp = (yield* Effect.tryPromise(() =>
923 t.query(api.controlPlane.listWorkspaceTools, {
924 workspaceId: "ws_1",
925 }),
926 )) as Array<{
927 sourceId: string;
928 }>;
929
930 expect(workspaceToolsWithMcp.some((tool) => tool.sourceId === "src_mcp_1")).toBe(true);
931
932 const sourceToolsFromWrongWorkspace = (yield* Effect.tryPromise(() =>
933 t.query(api.controlPlane.listSourceTools, {
934 workspaceId: "ws_2",
935 sourceId: "src_1",
936 }),
937 )) as Array<unknown>;
938
939 expect(sourceToolsFromWrongWorkspace).toHaveLength(0);
940 }),
941 );
942
943 it.effect("marks graphql sources auth_required when introspection is unauthorized", () =>
944 Effect.gen(function* () {
945 const t = setup();
946 const originalFetch = globalThis.fetch;
947
948 yield* Effect.tryPromise(() => ensureWorkspace(t, "ws_auth", "org_auth"));
949
950 globalThis.fetch = (async () =>
951 new Response(
952 JSON.stringify({
953 errors: [
954 {
955 message: "Unauthorized",
956 },
957 ],
958 }),
959 {
960 status: 401,
961 headers: {
962 "content-type": "application/json",
963 },
964 },
965 )) as unknown as typeof fetch;
966
967 try {
968 const now = Date.now();
969
970 yield* Effect.tryPromise(() =>
971 t.run(async (ctx) => {
972 await ctx.db.insert("sources", {
973 id: "src_graphql_auth_1",
974 workspaceId: "ws_auth",
975 name: "Linear API",
976 kind: "graphql",
977 endpoint: "https://api.linear.app/graphql",
978 enabled: true,
979 configJson: "{}",
980 status: "draft",
981 sourceHash: null,
982 lastError: null,
983 createdAt: now,
984 updatedAt: now,
985 });
986 }),
987 );
988
989 yield* Effect.tryPromise(() =>
990 t.action(runtimeInternal.control_plane.openapi_ingest.ingestSourceArtifact, {
991 workspaceId: "ws_auth",
992 sourceId: "src_graphql_auth_1",
993 }),
994 );
995
996 const sources = (yield* Effect.tryPromise(() =>
997 t.query(api.controlPlane.listSources, {
998 workspaceId: "ws_auth",
999 }),
1000 )) as Array<{
1001 status: string;
1002 lastError: string | null;
1003 }>;
1004
1005 expect(sources).toHaveLength(1);
1006 expect(sources[0]?.status).toBe("auth_required");
1007 expect(sources[0]?.lastError?.toLowerCase()).toContain("unauthor");
1008 } finally {
1009 globalThis.fetch = originalFetch;
1010 }
1011 }),
1012 );
1013
1014 it.effect("uses credential bindings when ingesting graphql sources", () =>
1015 Effect.gen(function* () {
1016 const t = setup();
1017 const originalFetch = globalThis.fetch;
1018
1019 yield* Effect.tryPromise(() => ensureWorkspace(t, "ws_cred", "org_cred"));
1020
1021 globalThis.fetch = (async (_input: unknown, init?: RequestInit) => {
1022 const authHeader = new Headers(init?.headers).get("authorization");
1023 if (authHeader !== "Bearer linear_token") {
1024 return new Response(
1025 JSON.stringify({
1026 errors: [
1027 {
1028 message: "Unauthorized",
1029 },
1030 ],
1031 }),
1032 {
1033 status: 401,
1034 headers: {
1035 "content-type": "application/json",
1036 },
1037 },
1038 );
1039 }
1040
1041 const bodyText = typeof init?.body === "string" ? init.body : "{}";
1042 const payload = JSON.parse(bodyText) as {
1043 query?: string;
1044 variables?: {
1045 name?: string;
1046 };
1047 };
1048
1049 if (payload.query?.includes("SchemaRoots")) {
1050 return new Response(
1051 JSON.stringify({
1052 data: {
1053 __schema: {
1054 queryType: { name: "Query" },
1055 mutationType: null,
1056 },
1057 },
1058 }),
1059 {
1060 status: 200,
1061 headers: {
1062 "content-type": "application/json",
1063 },
1064 },
1065 );
1066 }
1067
1068 if (payload.query?.includes("RootFields") && payload.variables?.name === "Query") {
1069 return new Response(
1070 JSON.stringify({
1071 data: {
1072 __type: {
1073 name: "Query",
1074 fields: [
1075 {
1076 name: "viewer",
1077 description: "Current viewer",
1078 args: [],
1079 },
1080 ],
1081 },
1082 },
1083 }),
1084 {
1085 status: 200,
1086 headers: {
1087 "content-type": "application/json",
1088 },
1089 },
1090 );
1091 }
1092
1093 return new Response(
1094 JSON.stringify({
1095 data: {
1096 __type: {
1097 name: payload.variables?.name ?? "Unknown",
1098 fields: [],
1099 },
1100 },
1101 }),
1102 {
1103 status: 200,
1104 headers: {
1105 "content-type": "application/json",
1106 },
1107 },
1108 );
1109 }) as unknown as typeof fetch;
1110
1111 try {
1112 const now = Date.now();
1113
1114 yield* Effect.tryPromise(() =>
1115 t.action(api.controlPlane.upsertCredentialBinding, {
1116 workspaceId: "ws_cred",
1117 payload: {
1118 id: "credential_binding_linear",
1119 credentialId: "cred_linear",
1120 scopeType: "workspace",
1121 sourceKey: "source:src_graphql_cred_1",
1122 provider: "bearer",
1123 secretRef: "linear_token",
1124 accountId: null,
1125 additionalHeadersJson: null,
1126 boundAuthFingerprint: null,
1127 },
1128 }),
1129 );
1130
1131 yield* Effect.tryPromise(() =>
1132 t.run(async (ctx) => {
1133 await ctx.db.insert("sources", {
1134 id: "src_graphql_cred_1",
1135 workspaceId: "ws_cred",
1136 name: "Linear API",
1137 kind: "graphql",
1138 endpoint: "https://api.linear.app/graphql",
1139 enabled: true,
1140 configJson: "{}",
1141 status: "draft",
1142 sourceHash: null,
1143 lastError: null,
1144 createdAt: now,
1145 updatedAt: now,
1146 });
1147 }),
1148 );
1149
1150 yield* Effect.tryPromise(() =>
1151 t.action(runtimeInternal.control_plane.openapi_ingest.ingestSourceArtifact, {
1152 workspaceId: "ws_cred",
1153 sourceId: "src_graphql_cred_1",
1154 }),
1155 );
1156
1157 const sources = (yield* Effect.tryPromise(() =>
1158 t.query(api.controlPlane.listSources, {
1159 workspaceId: "ws_cred",
1160 }),
1161 )) as Array<{
1162 status: string;
1163 sourceHash: string | null;
1164 }>;
1165
1166 expect(sources).toHaveLength(1);
1167 expect(sources[0]?.status).toBe("connected");
1168 expect(sources[0]?.sourceHash).toBeTypeOf("string");
1169
1170 const sourceTools = (yield* Effect.tryPromise(() =>
1171 t.query(api.controlPlane.listSourceTools, {
1172 workspaceId: "ws_cred",
1173 sourceId: "src_graphql_cred_1",
1174 }),
1175 )) as Array<{
1176 toolId: string;
1177 }>;
1178
1179 expect(sourceTools.length).toBeGreaterThan(0);
1180 } finally {
1181 globalThis.fetch = originalFetch;
1182 }
1183 }),
1184 );
1185
1186 it.effect("ingests mcp sources with credential headers", () =>
1187 Effect.gen(function* () {
1188 const t = setup();
1189 const originalFetch = globalThis.fetch;
1190
1191 yield* Effect.tryPromise(() =>
1192 ensureWorkspace(t, "ws_mcp_ingest", "org_mcp_ingest")
1193 );
1194
1195 globalThis.fetch = (async (_input: unknown, init?: RequestInit) => {
1196 const authHeader = new Headers(init?.headers).get("authorization");
1197 if (authHeader !== "Bearer mcp_token") {
1198 return new Response(
1199 JSON.stringify({
1200 error: {
1201 code: 401,
1202 message: "Unauthorized",
1203 },
1204 }),
1205 {
1206 status: 401,
1207 headers: {
1208 "content-type": "application/json",
1209 },
1210 },
1211 );
1212 }
1213
1214 const bodyText = typeof init?.body === "string" ? init.body : "{}";
1215 const payload = JSON.parse(bodyText) as {
1216 id?: string | number;
1217 method?: string;
1218 };
1219
1220 if (payload.method === "initialize") {
1221 return new Response(
1222 JSON.stringify({
1223 jsonrpc: "2.0",
1224 id: payload.id,
1225 result: {
1226 protocolVersion: "2025-03-26",
1227 capabilities: {
1228 tools: {},
1229 },
1230 serverInfo: {
1231 name: "fake-mcp",
1232 version: "0.1.0",
1233 },
1234 },
1235 }),
1236 {
1237 status: 200,
1238 headers: {
1239 "content-type": "application/json",
1240 },
1241 },
1242 );
1243 }
1244
1245 if (payload.method === "notifications/initialized") {
1246 return new Response(null, {
1247 status: 204,
1248 });
1249 }
1250
1251 if (payload.method === "tools/list") {
1252 return new Response(
1253 JSON.stringify({
1254 jsonrpc: "2.0",
1255 id: payload.id,
1256 result: {
1257 tools: [
1258 {
1259 name: "search_docs",
1260 description: "Search docs",
1261 inputSchema: {
1262 type: "object",
1263 properties: {},
1264 },
1265 outputSchema: {
1266 type: "object",
1267 properties: {
1268 results: {
1269 type: "array",
1270 },
1271 },
1272 },
1273 },
1274 ],
1275 },
1276 }),
1277 {
1278 status: 200,
1279 headers: {
1280 "content-type": "application/json",
1281 },
1282 },
1283 );
1284 }
1285
1286 return new Response(
1287 JSON.stringify({
1288 jsonrpc: "2.0",
1289 id: payload.id,
1290 error: {
1291 code: -32601,
1292 message: "Method not found",
1293 },
1294 }),
1295 {
1296 status: 200,
1297 headers: {
1298 "content-type": "application/json",
1299 },
1300 },
1301 );
1302 }) as unknown as typeof fetch;
1303
1304 try {
1305 const now = Date.now();
1306
1307 yield* Effect.tryPromise(() =>
1308 t.action(api.controlPlane.upsertCredentialBinding, {
1309 workspaceId: "ws_mcp_ingest",
1310 payload: {
1311 id: "credential_binding_mcp",
1312 credentialId: "cred_mcp",
1313 scopeType: "workspace",
1314 sourceKey: "source:src_mcp_ingest_1",
1315 provider: "bearer",
1316 secretRef: "mcp_token",
1317 accountId: null,
1318 additionalHeadersJson: null,
1319 boundAuthFingerprint: null,
1320 },
1321 }),
1322 );
1323
1324 yield* Effect.tryPromise(() =>
1325 t.run(async (ctx) => {
1326 await ctx.db.insert("sources", {
1327 id: "src_mcp_ingest_1",
1328 workspaceId: "ws_mcp_ingest",
1329 name: "Deepwiki",
1330 kind: "mcp",
1331 endpoint: "https://example.com/mcp",
1332 enabled: true,
1333 configJson: "{}",
1334 status: "draft",
1335 sourceHash: null,
1336 lastError: null,
1337 createdAt: now,
1338 updatedAt: now,
1339 });
1340 }),
1341 );
1342
1343 yield* Effect.tryPromise(() =>
1344 t.action(runtimeInternal.control_plane.openapi_ingest.ingestSourceArtifact, {
1345 workspaceId: "ws_mcp_ingest",
1346 sourceId: "src_mcp_ingest_1",
1347 }),
1348 );
1349
1350 const sources = (yield* Effect.tryPromise(() =>
1351 t.query(api.controlPlane.listSources, {
1352 workspaceId: "ws_mcp_ingest",
1353 }),
1354 )) as Array<{
1355 status: string;
1356 sourceHash: string | null;
1357 }>;
1358
1359 expect(sources).toHaveLength(1);
1360 expect(sources[0]?.status).toBe("connected");
1361 expect(sources[0]?.sourceHash).toBeTypeOf("string");
1362
1363 const sourceTools = (yield* Effect.tryPromise(() =>
1364 t.query(api.controlPlane.listSourceTools, {
1365 workspaceId: "ws_mcp_ingest",
1366 sourceId: "src_mcp_ingest_1",
1367 }),
1368 )) as Array<{
1369 sourceId: string;
1370 path: string;
1371 }>;
1372
1373 expect(sourceTools).toHaveLength(1);
1374 expect(sourceTools[0]?.sourceId).toBe("src_mcp_ingest_1");
1375 expect(sourceTools[0]?.path).toContain("deepwiki.mcp.search_docs");
1376 } finally {
1377 globalThis.fetch = originalFetch;
1378 }
1379 }),
1380 );
1381
1382 it.effect("persists approval state for runtime tool calls", () =>
1383 Effect.gen(function* () {
1384 const t = setup();
1385
1386 const missingRunDecision = (yield* Effect.tryPromise(() =>
1387 t.mutation(runtimeInternal.source_tool_registry.evaluateToolApproval, {
1388 workspaceId: "ws_1",
1389 runId: "run_approval_1",
1390 callId: "call_approval_1",
1391 toolPath: "github.repos.delete",
1392 inputPreviewJson: "{}",
1393 defaultMode: "auto",
1394 requireApprovals: true,
1395 retryAfterMs: 333,
1396 }),
1397 )) as {
1398 kind: "approved" | "pending" | "denied";
1399 error?: string;
1400 };
1401
1402 expect(missingRunDecision.kind).toBe("denied");
1403 expect(missingRunDecision.error).toContain("Unknown run for approval request");
1404
1405 yield* Effect.tryPromise(() =>
1406 t.mutation(runtimeInternal.task_runs.startTaskRun, {
1407 workspaceId: "ws_1",
1408 runId: "run_approval_1",
1409 }),
1410 );
1411
1412 // First evaluation writes a pending approval row when this runId/callId is unseen.
1413 const firstDecision = (yield* Effect.tryPromise(() =>
1414 t.mutation(runtimeInternal.source_tool_registry.evaluateToolApproval, {
1415 workspaceId: "ws_1",
1416 runId: "run_approval_1",
1417 callId: "call_approval_1",
1418 toolPath: "github.repos.delete",
1419 inputPreviewJson: "{}",
1420 defaultMode: "auto",
1421 requireApprovals: true,
1422 retryAfterMs: 333,
1423 }),
1424 )) as {
1425 kind: "approved" | "pending" | "denied";
1426 approvalId?: string;
1427 retryAfterMs?: number;
1428 };
1429
1430 expect(firstDecision.kind).toBe("pending");
1431 expect(firstDecision.retryAfterMs).toBe(333);
1432 expect(firstDecision.approvalId).toBeTypeOf("string");
1433
1434 const secondDecision = (yield* Effect.tryPromise(() =>
1435 t.mutation(runtimeInternal.source_tool_registry.evaluateToolApproval, {
1436 workspaceId: "ws_1",
1437 runId: "run_approval_1",
1438 callId: "call_approval_1",
1439 toolPath: "github.repos.delete",
1440 inputPreviewJson: "{}",
1441 defaultMode: "auto",
1442 requireApprovals: true,
1443 retryAfterMs: 333,
1444 }),
1445 )) as {
1446 kind: "approved" | "pending" | "denied";
1447 approvalId?: string;
1448 };
1449
1450 expect(secondDecision.kind).toBe("pending");
1451 expect(secondDecision.approvalId).toBe(firstDecision.approvalId);
1452
1453 const approvalId = firstDecision.approvalId;
1454 if (!approvalId) {
1455 throw new Error("expected approval id");
1456 }
1457
1458 yield* Effect.tryPromise(() =>
1459 t.mutation(api.controlPlane.resolveApproval, {
1460 workspaceId: "ws_1",
1461 approvalId,
1462 payload: {
1463 status: "approved",
1464 reason: "approved by test",
1465 },
1466 }),
1467 );
1468
1469 const resolvedDecision = (yield* Effect.tryPromise(() =>
1470 t.mutation(runtimeInternal.source_tool_registry.evaluateToolApproval, {
1471 workspaceId: "ws_1",
1472 runId: "run_approval_1",
1473 callId: "call_approval_1",
1474 toolPath: "github.repos.delete",
1475 inputPreviewJson: "{}",
1476 defaultMode: "auto",
1477 requireApprovals: true,
1478 retryAfterMs: 333,
1479 }),
1480 )) as {
1481 kind: "approved" | "pending" | "denied";
1482 };
1483
1484 expect(resolvedDecision).toEqual({
1485 kind: "approved",
1486 });
1487 }),
1488 );
1489});
apps/convex/convex/executor.ts+29−0
@@ -0,0 +1,29 @@
1import {
2 createRunExecutor,
3 type ToolRegistry,
4} from "@executor-v2/engine";
5import type { ExecuteRunInput, ExecuteRunResult } from "@executor-v2/sdk";
6import * as Effect from "effect/Effect";
7
8import { createExecuteRuntimeRunInConvex } from "./runtime_execution_port";
9
10export type ExecuteRunImplOptions = {
11 toolRegistry?: ToolRegistry;
12 makeRunId?: () => string;
13};
14
15export const executeRunImpl = (
16 input: ExecuteRunInput,
17 options: ExecuteRunImplOptions = {},
18): Effect.Effect<ExecuteRunResult> => {
19 const runExecutor = createRunExecutor(
20 createExecuteRuntimeRunInConvex({
21 toolRegistry: options.toolRegistry,
22 }),
23 {
24 makeRunId: options.makeRunId,
25 },
26 );
27
28 return runExecutor.executeRun(input);
29};
apps/convex/convex/http.ts+62−0
@@ -0,0 +1,62 @@
1import { httpRouter } from "convex/server";
2
3import { controlPlaneHttpHandler } from "./controlPlane";
4import { mcpHandler } from "./mcp";
5import {
6 oauthAuthorizationServerHandler,
7 oauthProtectedResourceHandler,
8} from "./mcp_auth";
9import { handleToolCallHttp } from "./runtimeCallbacks";
10
11const http = httpRouter();
12
13http.route({ path: "/v1/mcp", method: "POST", handler: mcpHandler });
14http.route({ path: "/v1/mcp", method: "GET", handler: mcpHandler });
15http.route({ path: "/v1/mcp", method: "DELETE", handler: mcpHandler });
16http.route({
17 path: "/.well-known/oauth-protected-resource",
18 method: "GET",
19 handler: oauthProtectedResourceHandler,
20});
21http.route({
22 path: "/.well-known/oauth-authorization-server",
23 method: "GET",
24 handler: oauthAuthorizationServerHandler,
25});
26http.route({
27 path: "/v1/runtime/tool-call",
28 method: "POST",
29 handler: handleToolCallHttp,
30});
31http.route({
32 pathPrefix: "/v1/",
33 method: "GET",
34 handler: controlPlaneHttpHandler,
35});
36http.route({
37 pathPrefix: "/v1/",
38 method: "POST",
39 handler: controlPlaneHttpHandler,
40});
41http.route({
42 pathPrefix: "/v1/",
43 method: "PUT",
44 handler: controlPlaneHttpHandler,
45});
46http.route({
47 pathPrefix: "/v1/",
48 method: "PATCH",
49 handler: controlPlaneHttpHandler,
50});
51http.route({
52 pathPrefix: "/v1/",
53 method: "DELETE",
54 handler: controlPlaneHttpHandler,
55});
56http.route({
57 pathPrefix: "/v1/",
58 method: "OPTIONS",
59 handler: controlPlaneHttpHandler,
60});
61
62export default http;
apps/convex/convex/mcp.ts+199−0
@@ -0,0 +1,199 @@
1import {
2 buildExecuteToolDescription,
3 defaultExecuteToolDescription,
4 defaultExecuteToolExposureMode,
5 parseExecuteToolExposureMode,
6 type ExecuteToolExposureMode,
7} from "@executor-v2/engine";
8import { handleMcpHttpRequest } from "@executor-v2/mcp-gateway";
9import { createExecutorRunClient } from "@executor-v2/sdk";
10import * as Effect from "effect/Effect";
11
12import { internal } from "./_generated/api";
13import { httpAction, type ActionCtx } from "./_generated/server";
14import { executeRunImpl } from "./executor";
15import {
16 getMcpAuthConfig,
17 unauthorizedMcpResponse,
18 verifyMcpToken,
19} from "./mcp_auth";
20import { createConvexSourceToolRegistry } from "./source_tool_registry";
21
22const readConfiguredWorkspaceId = (value: string | undefined): string => {
23 const normalized = value?.trim();
24 return normalized && normalized.length > 0 ? normalized : "ws_local";
25};
26
27const readWorkspaceIdFromRequest = (request: Request): string | null => {
28 const value = new URL(request.url).searchParams.get("workspaceId")?.trim();
29 return value && value.length > 0 ? value : null;
30};
31
32const readRequestedWorkspaceId = (request: Request, fallbackWorkspaceId: string): string =>
33 readWorkspaceIdFromRequest(request) ?? fallbackWorkspaceId;
34
35const readToolExposureModeFromRequest = (
36 request: Request,
37 fallbackMode: ExecuteToolExposureMode,
38): ExecuteToolExposureMode => {
39 const url = new URL(request.url);
40 const rawMode =
41 url.searchParams.get("toolExposureMode") ??
42 url.searchParams.get("toolContextMode") ??
43 undefined;
44
45 return parseExecuteToolExposureMode(rawMode ?? undefined) ?? fallbackMode;
46};
47
48const resolveExecuteToolDescription = async (
49 mode: ExecuteToolExposureMode,
50 toolRegistry: ReturnType<typeof createConvexSourceToolRegistry>,
51): Promise<string> => {
52 try {
53 return await Effect.runPromise(
54 buildExecuteToolDescription({
55 toolRegistry,
56 mode,
57 }),
58 );
59 } catch {
60 return defaultExecuteToolDescription;
61 }
62};
63
64const hasWorkspaceAccess = async (
65 ctx: ActionCtx,
66 workspaceId: string,
67 accountId: string,
68): Promise<boolean> => {
69 try {
70 const workspace = (await ctx.runQuery(
71 runtimeInternal.control_plane.actor.getWorkspaceForActor,
72 { workspaceId },
73 )) as {
74 organizationId: string;
75 createdByAccountId: string | null;
76 } | null;
77
78 if (!workspace) {
79 return false;
80 }
81
82 if (workspace.createdByAccountId === accountId) {
83 return true;
84 }
85
86 const memberships = (await ctx.runQuery(
87 runtimeInternal.control_plane.actor.listOrganizationMembershipsForActor,
88 { accountId },
89 )) as Array<{
90 organizationId: string;
91 }>;
92
93 return memberships.some((membership) => membership.organizationId === workspace.organizationId);
94 } catch {
95 return false;
96 }
97};
98
99const fallbackWorkspaceId = readConfiguredWorkspaceId(process.env.CONVEX_WORKSPACE_ID);
100const defaultToolExposureMode =
101 parseExecuteToolExposureMode(process.env.CONVEX_TOOL_EXPOSURE_MODE) ??
102 defaultExecuteToolExposureMode;
103const runtimeInternal = internal as any;
104
105export const mcpHandler = httpAction(async (ctx, request) => {
106 const mcpAuthConfig = getMcpAuthConfig();
107 const requestWorkspaceId = readWorkspaceIdFromRequest(request);
108 const workspaceId = readRequestedWorkspaceId(request, fallbackWorkspaceId);
109
110 if (!mcpAuthConfig.enabled) {
111 if (mcpAuthConfig.required) {
112 return Response.json(
113 {
114 error: "MCP OAuth must be configured for cloud deployments",
115 },
116 { status: 503 },
117 );
118 }
119 } else {
120 const auth = await verifyMcpToken(request, mcpAuthConfig);
121 if (!auth) {
122 return unauthorizedMcpResponse(request, "No valid bearer token provided.");
123 }
124
125 if (!requestWorkspaceId) {
126 return Response.json(
127 {
128 error: "workspaceId query parameter is required when MCP OAuth is enabled",
129 },
130 { status: 400 },
131 );
132 }
133
134 const authorized = await hasWorkspaceAccess(ctx, requestWorkspaceId, auth.subject);
135 if (!authorized) {
136 return Response.json(
137 {
138 error: "Workspace authorization failed",
139 },
140 { status: 403 },
141 );
142 }
143 }
144
145 const toolRegistry = createConvexSourceToolRegistry(ctx, workspaceId);
146 const toolExposureMode = readToolExposureModeFromRequest(
147 request,
148 defaultToolExposureMode,
149 );
150 const executeToolDescription = await resolveExecuteToolDescription(
151 toolExposureMode,
152 toolRegistry,
153 );
154
155 const runClient = createExecutorRunClient(async (input) => {
156 const runId = `run_${crypto.randomUUID()}`;
157
158 await ctx.runMutation(runtimeInternal.task_runs.startTaskRun, {
159 workspaceId,
160 runId,
161 sessionId: "session_mcp",
162 runtimeId: "runtime_local_inproc",
163 codeHash: `code_length_${input.code.length}`,
164 });
165
166 try {
167 const result = await Effect.runPromise(
168 executeRunImpl(input, {
169 toolRegistry,
170 makeRunId: () => runId,
171 }),
172 );
173
174 await ctx.runMutation(runtimeInternal.task_runs.finishTaskRun, {
175 workspaceId,
176 runId,
177 status: result.status,
178 error: result.error ?? null,
179 });
180
181 return result;
182 } catch (cause) {
183 await ctx.runMutation(runtimeInternal.task_runs.finishTaskRun, {
184 workspaceId,
185 runId,
186 status: "failed",
187 error: String(cause),
188 });
189 throw cause;
190 }
191 });
192
193 return handleMcpHttpRequest(request, {
194 serverName: "executor-v2-convex",
195 serverVersion: "0.0.0",
196 runClient,
197 executeToolDescription,
198 });
199});
apps/convex/convex/mcp_auth.ts+216−0
@@ -0,0 +1,216 @@
1import { createRemoteJWKSet, jwtVerify } from "jose";
2
3import { httpAction } from "./_generated/server";
4
5export const MCP_PATH = "/v1/mcp";
6
7type McpAuthConfig = {
8 required: boolean;
9 enabled: boolean;
10 authorizationServer: string | null;
11 jwks: ReturnType<typeof createRemoteJWKSet> | null;
12};
13
14type VerifiedMcpToken = {
15 provider: "workos";
16 subject: string;
17};
18
19const isTruthyEnvValue = (value: string | undefined): boolean => {
20 const normalized = value?.trim().toLowerCase();
21 return normalized === "1" || normalized === "true" || normalized === "yes" || normalized === "on";
22};
23
24const mcpAuthRequired = (): boolean => {
25 const deploymentMode = (process.env.EXECUTOR_DEPLOYMENT_MODE ?? "").trim().toLowerCase();
26 if (
27 deploymentMode === "cloud"
28 || deploymentMode === "hosted"
29 || deploymentMode === "production"
30 || deploymentMode === "prod"
31 ) {
32 return true;
33 }
34
35 if (
36 deploymentMode === "self-hosted"
37 || deploymentMode === "self_hosted"
38 || deploymentMode === "selfhosted"
39 ) {
40 return false;
41 }
42
43 return isTruthyEnvValue(process.env.EXECUTOR_ENFORCE_MCP_AUTH);
44};
45
46const getMcpAuthorizationServer = (): string | null =>
47 process.env.MCP_AUTHORIZATION_SERVER
48 ?? process.env.MCP_AUTHORIZATION_SERVER_URL
49 ?? process.env.WORKOS_AUTHKIT_ISSUER
50 ?? process.env.WORKOS_AUTHKIT_DOMAIN
51 ?? null;
52
53export const getMcpAuthConfig = (): McpAuthConfig => {
54 const required = mcpAuthRequired();
55 const authorizationServer = getMcpAuthorizationServer();
56
57 if (!authorizationServer) {
58 return {
59 required,
60 enabled: false,
61 authorizationServer: null,
62 jwks: null,
63 };
64 }
65
66 return {
67 required,
68 enabled: true,
69 authorizationServer,
70 jwks: createRemoteJWKSet(new URL("/oauth2/jwks", authorizationServer)),
71 };
72};
73
74const parseBearerToken = (request: Request): string | null => {
75 const header = request.headers.get("authorization");
76 if (!header || !header.startsWith("Bearer ")) {
77 return null;
78 }
79
80 const token = header.slice("Bearer ".length).trim();
81 return token.length > 0 ? token : null;
82};
83
84const resourceMetadataUrl = (request: Request): string => {
85 const url = new URL(request.url);
86 const metadata = new URL("/.well-known/oauth-protected-resource", url.origin);
87 metadata.search = url.search;
88
89 const resource = new URL(url.pathname, url.origin);
90 resource.search = url.search;
91 metadata.searchParams.set("resource", resource.toString());
92
93 return metadata.toString();
94};
95
96export const unauthorizedMcpResponse = (request: Request, message: string): Response => {
97 const challenge = [
98 'Bearer error="unauthorized"',
99 'error_description="Authorization needed"',
100 `resource_metadata="${resourceMetadataUrl(request)}"`,
101 ].join(", ");
102
103 return Response.json(
104 { error: message },
105 {
106 status: 401,
107 headers: {
108 "WWW-Authenticate": challenge,
109 },
110 },
111 );
112};
113
114export const verifyMcpToken = async (
115 request: Request,
116 config: McpAuthConfig,
117): Promise<VerifiedMcpToken | null> => {
118 if (!config.enabled || !config.jwks || !config.authorizationServer) {
119 return null;
120 }
121
122 const token = parseBearerToken(request);
123 if (!token) {
124 return null;
125 }
126
127 try {
128 const { payload } = await jwtVerify(token, config.jwks, {
129 issuer: config.authorizationServer,
130 });
131
132 if (typeof payload.sub !== "string" || payload.sub.length === 0) {
133 return null;
134 }
135
136 const providerClaim = typeof payload.provider === "string" ? payload.provider : undefined;
137 if (providerClaim === "anonymous") {
138 return null;
139 }
140
141 return {
142 provider: "workos",
143 subject: payload.sub,
144 };
145 } catch (error) {
146 console.error("MCP token verification failed:", error instanceof Error ? error.message : String(error));
147 return null;
148 }
149};
150
151const errorResponseForMissingConfig = (config: McpAuthConfig): Response =>
152 Response.json(
153 {
154 error: config.required
155 ? "MCP OAuth must be configured for cloud deployments"
156 : "MCP OAuth is not configured",
157 },
158 { status: config.required ? 503 : 404 },
159 );
160
161export const oauthProtectedResourceHandler = httpAction(async (_ctx, request) => {
162 const config = getMcpAuthConfig();
163 if (!config.enabled || !config.authorizationServer) {
164 return errorResponseForMissingConfig(config);
165 }
166
167 const url = new URL(request.url);
168 let resource = new URL(MCP_PATH, url.origin);
169 resource.search = url.search;
170
171 const resourceHint = url.searchParams.get("resource");
172 if (resourceHint) {
173 try {
174 const parsed = new URL(resourceHint);
175 if (parsed.origin !== url.origin) {
176 return Response.json({ error: "resource hint origin must match this server" }, { status: 400 });
177 }
178
179 if (parsed.pathname === MCP_PATH) {
180 resource = new URL(MCP_PATH, url.origin);
181 resource.search = parsed.search;
182 }
183 } catch {
184 return Response.json({ error: "Invalid resource hint" }, { status: 400 });
185 }
186 }
187
188 return Response.json({
189 resource: resource.toString(),
190 authorization_servers: [config.authorizationServer],
191 bearer_methods_supported: ["header"],
192 });
193});
194
195export const oauthAuthorizationServerHandler = httpAction(async (_ctx, _request) => {
196 const config = getMcpAuthConfig();
197 if (!config.enabled || !config.authorizationServer) {
198 return errorResponseForMissingConfig(config);
199 }
200
201 const upstream = new URL("/.well-known/oauth-authorization-server", config.authorizationServer);
202 const response = await fetch(upstream.toString(), {
203 headers: {
204 accept: "application/json",
205 },
206 });
207
208 const body = await response.text();
209
210 return new Response(body, {
211 status: response.status,
212 headers: {
213 "content-type": response.headers.get("content-type") ?? "application/json",
214 },
215 });
216});
apps/convex/convex/run_executor.ts+5−0
@@ -0,0 +1,5 @@
1import { type ExecuteRunInput } from "@executor-v2/sdk";
2
3import { executeRunImpl } from "./executor";
4
5export const executeRun = (input: ExecuteRunInput) => executeRunImpl(input);
apps/convex/convex/runtimeCallbacks.ts+124−0
@@ -0,0 +1,124 @@
1import {
2 RuntimeAdapterError,
3 invokeRuntimeToolCallResult,
4} from "@executor-v2/engine";
5import type {
6 RuntimeToolCallRequest,
7 RuntimeToolCallResult,
8} from "@executor-v2/sdk";
9import * as Data from "effect/Data";
10import * as Effect from "effect/Effect";
11import * as ParseResult from "effect/ParseResult";
12import * as Schema from "effect/Schema";
13
14import { httpAction, type ActionCtx } from "./_generated/server";
15import { createConvexSourceToolRegistry } from "./source_tool_registry";
16
17class RuntimeToolCallBadRequestError extends Data.TaggedError(
18 "RuntimeToolCallBadRequestError",
19)<{
20 message: string;
21 details: string;
22}> {}
23
24const RuntimeToolCallCredentialContextSchema = Schema.Struct({
25 workspaceId: Schema.String,
26 sourceKey: Schema.String,
27 organizationId: Schema.optional(Schema.NullOr(Schema.String)),
28 accountId: Schema.optional(Schema.NullOr(Schema.String)),
29});
30
31const RuntimeToolCallRequestSchema = Schema.Struct({
32 runId: Schema.String,
33 callId: Schema.String,
34 toolPath: Schema.String,
35 input: Schema.optional(
36 Schema.Record({
37 key: Schema.String,
38 value: Schema.Unknown,
39 }),
40 ),
41 credentialContext: Schema.optional(RuntimeToolCallCredentialContextSchema),
42});
43
44const decodeRuntimeToolCallRequest = Schema.decodeUnknown(RuntimeToolCallRequestSchema);
45
46const readConfiguredWorkspaceId = (value: string | undefined): string => {
47 const normalized = value?.trim();
48 return normalized && normalized.length > 0 ? normalized : "ws_local";
49};
50
51const fallbackWorkspaceId = readConfiguredWorkspaceId(process.env.CONVEX_WORKSPACE_ID);
52
53const badRequest = (message: string): Response =>
54 Response.json(
55 {
56 ok: false,
57 kind: "failed",
58 error: message,
59 } satisfies RuntimeToolCallResult,
60 { status: 400 },
61 );
62
63const formatBadRequestMessage = (error: RuntimeToolCallBadRequestError): string =>
64 error.details.length > 0 ? `${error.message}: ${error.details}` : error.message;
65
66const formatRuntimeAdapterError = (error: RuntimeAdapterError): string =>
67 error.details ? `${error.message}: ${error.details}` : error.message;
68
69const formatUnknownDetails = (cause: unknown): string => String(cause);
70
71const decodeToolCallRequest = (request: Request): Effect.Effect<RuntimeToolCallRequest, RuntimeToolCallBadRequestError> =>
72 Effect.gen(function* () {
73 const body = yield* Effect.tryPromise({
74 try: () => request.json(),
75 catch: (cause) =>
76 new RuntimeToolCallBadRequestError({
77 message: "Invalid runtime callback request body",
78 details: formatUnknownDetails(cause),
79 }),
80 });
81
82 return yield* decodeRuntimeToolCallRequest(body).pipe(
83 Effect.mapError(
84 (cause) =>
85 new RuntimeToolCallBadRequestError({
86 message: "Runtime callback request body is invalid",
87 details: ParseResult.TreeFormatter.formatErrorSync(cause),
88 }),
89 ),
90 );
91 });
92
93const handleToolCallHttpEffect = (
94 ctx: ActionCtx,
95 request: Request,
96): Effect.Effect<Response, never> =>
97 Effect.gen(function* () {
98 const input = yield* decodeToolCallRequest(request);
99
100 const workspaceId =
101 input.credentialContext?.workspaceId?.trim() || fallbackWorkspaceId;
102
103 const toolRegistry = createConvexSourceToolRegistry(ctx, workspaceId);
104
105 const result = yield* invokeRuntimeToolCallResult(toolRegistry, input).pipe(
106 Effect.catchTag("RuntimeAdapterError", (error) =>
107 Effect.succeed<RuntimeToolCallResult>({
108 ok: false,
109 kind: "failed",
110 error: formatRuntimeAdapterError(error),
111 }),
112 ),
113 );
114
115 return Response.json(result, { status: 200 });
116 }).pipe(
117 Effect.catchTag("RuntimeToolCallBadRequestError", (error) =>
118 Effect.succeed(badRequest(formatBadRequestMessage(error))),
119 ),
120 );
121
122export const handleToolCallHttp = httpAction((ctx, request) =>
123 Effect.runPromise(handleToolCallHttpEffect(ctx, request)),
124);
apps/convex/convex/runtime_adapter.ts+10−0
@@ -0,0 +1,10 @@
1import {
2 type RuntimeAdapter,
3 type RuntimeExecuteError,
4 type RuntimeExecuteInput,
5} from "@executor-v2/engine";
6import { makeCloudflareWorkerLoaderRuntimeAdapter } from "@executor-v2/runtime-cloudflare-worker-loader";
7
8export type { RuntimeAdapter, RuntimeExecuteError, RuntimeExecuteInput };
9
10export { makeCloudflareWorkerLoaderRuntimeAdapter };
apps/convex/convex/runtime_execution_port.ts+74−0
@@ -0,0 +1,74 @@
1import {
2 RuntimeExecutionPortError,
3 createRuntimeToolCallService,
4 createStaticToolRegistry,
5 type ExecuteRuntimeRun,
6 type ExecuteRuntimeRunInput,
7 type ToolRegistry,
8 makeRuntimeAdapterRegistry,
9 type RuntimeExecuteError,
10} from "@executor-v2/engine";
11import { makeCloudflareWorkerLoaderRuntimeAdapter } from "@executor-v2/runtime-cloudflare-worker-loader";
12import * as Effect from "effect/Effect";
13
14export type ConvexRuntimeExecutionPortOptions = {
15 toolRegistry?: ToolRegistry;
16};
17
18export const createExecuteRuntimeRunInConvex = (
19 options: ConvexRuntimeExecutionPortOptions = {},
20): ExecuteRuntimeRun => {
21 const convexRuntimeAdapter = makeCloudflareWorkerLoaderRuntimeAdapter();
22 const runtimeAdapters = makeRuntimeAdapterRegistry([convexRuntimeAdapter]);
23
24 const toolRegistry =
25 options.toolRegistry ??
26 createStaticToolRegistry({
27 tools: {},
28 });
29 const toolCallService = createRuntimeToolCallService(toolRegistry);
30
31 return (input: ExecuteRuntimeRunInput) =>
32 Effect.gen(function* () {
33 const runtimeAdapter = yield* runtimeAdapters.get(convexRuntimeAdapter.kind).pipe(
34 Effect.mapError(
35 (error) =>
36 new RuntimeExecutionPortError({
37 operation: "resolve_runtime_adapter",
38 message: error.message,
39 details: null,
40 }),
41 ),
42 );
43
44 const isAvailable = yield* runtimeAdapter.isAvailable();
45 if (!isAvailable) {
46 return yield* new RuntimeExecutionPortError({
47 operation: "runtime_available",
48 message: `Runtime '${convexRuntimeAdapter.kind}' is not configured in this convex process.`,
49 details:
50 "Set CLOUDFLARE_SANDBOX_RUN_URL, CLOUDFLARE_SANDBOX_AUTH_TOKEN, and CLOUDFLARE_SANDBOX_CALLBACK_URL.",
51 });
52 }
53
54 return yield* runtimeAdapter
55 .execute({
56 runId: input.runId,
57 code: input.code,
58 timeoutMs: input.timeoutMs,
59 toolCallService,
60 })
61 .pipe(
62 Effect.mapError(
63 (error: RuntimeExecuteError) =>
64 new RuntimeExecutionPortError({
65 operation: "runtime_execute",
66 message: error.message,
67 details: error.details,
68 }),
69 ),
70 );
71 });
72};
73
74export const executeRuntimeRunInConvex = createExecuteRuntimeRunInConvex();
apps/convex/convex/schema.ts+236−0
@@ -0,0 +1,236 @@
1import { defineSchema, defineTable, type TablesFromSchemaDefinition } from "@executor-v2/confect";
2import {
3 ApprovalSchema,
4 EventEnvelopeSchema,
5 OAuthTokenSchema,
6 OrganizationMembershipSchema,
7 OrganizationSchema,
8 PolicySchema,
9 ProfileSchema,
10 SourceCredentialBindingSchema,
11 SourceSchema,
12 StorageInstanceSchema,
13 SyncStateSchema,
14 TaskRunSchema,
15 WorkspaceSchema,
16} from "@executor-v2/schema";
17import * as Schema from "effect/Schema";
18
19const StorageFileEntrySchema = Schema.Struct({
20 id: Schema.String,
21 storageInstanceId: Schema.String,
22 path: Schema.String,
23 contentBase64: Schema.String,
24 sizeBytes: Schema.Number,
25 updatedAt: Schema.Number,
26});
27
28const StorageKvEntrySchema = Schema.Struct({
29 id: Schema.String,
30 storageInstanceId: Schema.String,
31 key: Schema.String,
32 valueJson: Schema.String,
33 updatedAt: Schema.Number,
34});
35
36const StorageSqlKvEntrySchema = Schema.Struct({
37 id: Schema.String,
38 storageInstanceId: Schema.String,
39 key: Schema.String,
40 value: Schema.String,
41 updatedAt: Schema.Number,
42});
43
44const ArtifactSchema = Schema.Struct({
45 id: Schema.String,
46 protocol: Schema.String,
47 contentHash: Schema.String,
48 extractorVersion: Schema.String,
49 toolCount: Schema.Number,
50 refHintTableJson: Schema.optional(Schema.NullOr(Schema.String)),
51 createdAt: Schema.Number,
52 updatedAt: Schema.Number,
53});
54
55const ArtifactToolSchema = Schema.Struct({
56 id: Schema.String,
57 artifactId: Schema.String,
58 protocol: Schema.String,
59 toolId: Schema.String,
60 name: Schema.String,
61 description: Schema.NullOr(Schema.String),
62 canonicalPath: Schema.String,
63 operationHash: Schema.String,
64 invocationJson: Schema.String,
65 inputSchemaJson: Schema.optional(Schema.NullOr(Schema.String)),
66 outputSchemaJson: Schema.optional(Schema.NullOr(Schema.String)),
67 metadataJson: Schema.optional(Schema.NullOr(Schema.String)),
68 createdAt: Schema.Number,
69 updatedAt: Schema.Number,
70});
71
72const ArtifactSchemaRefSchema = Schema.Struct({
73 id: Schema.String,
74 artifactId: Schema.String,
75 refKey: Schema.String,
76 schemaJson: Schema.String,
77 createdAt: Schema.Number,
78 updatedAt: Schema.Number,
79});
80
81const SourceArtifactBindingSchema = Schema.Struct({
82 id: Schema.String,
83 workspaceId: Schema.String,
84 sourceId: Schema.String,
85 artifactId: Schema.String,
86 updatedAt: Schema.Number,
87});
88
89const SourceIngestArtifactBatchSchema = Schema.Struct({
90 id: Schema.String,
91 workspaceId: Schema.String,
92 sourceId: Schema.String,
93 artifactId: Schema.String,
94 protocol: Schema.String,
95 batchIndex: Schema.Number,
96 toolsJson: Schema.String,
97 updatedAt: Schema.Number,
98});
99
100const WorkspaceToolIndexSchema = Schema.Struct({
101 id: Schema.String,
102 workspaceId: Schema.String,
103 sourceId: Schema.String,
104 sourceName: Schema.String,
105 sourceKind: Schema.String,
106 artifactId: Schema.String,
107 toolId: Schema.String,
108 protocol: Schema.String,
109 method: Schema.String,
110 namespace: Schema.String,
111 path: Schema.String,
112 pathLower: Schema.String,
113 normalizedPath: Schema.String,
114 operationPath: Schema.optional(Schema.NullOr(Schema.String)),
115 name: Schema.String,
116 description: Schema.NullOr(Schema.String),
117 searchText: Schema.String,
118 operationHash: Schema.String,
119 approvalMode: Schema.String,
120 status: Schema.String,
121 refHintTableJson: Schema.optional(Schema.NullOr(Schema.String)),
122 updatedAt: Schema.Number,
123});
124
125export const executorConfectSchema = defineSchema({
126 profiles: defineTable(ProfileSchema).index("by_domainId", ["id"]),
127 organizations: defineTable(OrganizationSchema)
128 .index("by_domainId", ["id"])
129 .index("by_slug", ["slug"]),
130 organizationMemberships: defineTable(OrganizationMembershipSchema)
131 .index("by_domainId", ["id"])
132 .index("by_organizationId", ["organizationId"])
133 .index("by_accountId", ["accountId"])
134 .index("by_organizationId_accountId", ["organizationId", "accountId"]),
135 workspaces: defineTable(WorkspaceSchema)
136 .index("by_domainId", ["id"])
137 .index("by_organizationId", ["organizationId"])
138 .index("by_createdByAccountId", ["createdByAccountId"]),
139 sources: defineTable(SourceSchema)
140 .index("by_domainId", ["id"])
141 .index("by_workspaceId", ["workspaceId"]),
142 artifacts: defineTable(ArtifactSchema)
143 .index("by_domainId", ["id"])
144 .index("by_protocol_contentHash_extractorVersion", [
145 "protocol",
146 "contentHash",
147 "extractorVersion",
148 ]),
149 artifactTools: defineTable(ArtifactToolSchema)
150 .index("by_domainId", ["id"])
151 .index("by_artifactId", ["artifactId"])
152 .index("by_artifactId_toolId", ["artifactId", "toolId"]),
153 artifactSchemaRefs: defineTable(ArtifactSchemaRefSchema)
154 .index("by_domainId", ["id"])
155 .index("by_artifactId", ["artifactId"])
156 .index("by_artifactId_refKey", ["artifactId", "refKey"]),
157 sourceArtifactBindings: defineTable(SourceArtifactBindingSchema)
158 .index("by_domainId", ["id"])
159 .index("by_workspaceId", ["workspaceId"])
160 .index("by_workspaceId_sourceId", ["workspaceId", "sourceId"])
161 .index("by_artifactId", ["artifactId"]),
162 sourceIngestArtifactBatches: defineTable(SourceIngestArtifactBatchSchema)
163 .index("by_domainId", ["id"])
164 .index("by_workspaceId_sourceId", ["workspaceId", "sourceId"])
165 .index("by_workspaceId_sourceId_artifactId_batchIndex", [
166 "workspaceId",
167 "sourceId",
168 "artifactId",
169 "batchIndex",
170 ])
171 .index("by_artifactId", ["artifactId"]),
172 workspaceToolIndex: defineTable(WorkspaceToolIndexSchema)
173 .index("by_domainId", ["id"])
174 .index("by_workspaceId", ["workspaceId"])
175 .index("by_workspaceId_sourceId", ["workspaceId", "sourceId"])
176 .index("by_workspaceId_namespace", ["workspaceId", "namespace"])
177 .index("by_workspaceId_pathLower", ["workspaceId", "pathLower"])
178 .index("by_workspaceId_normalizedPath", ["workspaceId", "normalizedPath"])
179 .index("by_workspaceId_operationHash", ["workspaceId", "operationHash"])
180 .searchIndex("search_text", {
181 searchField: "searchText",
182 filterFields: ["workspaceId", "sourceId", "status", "namespace"],
183 }),
184 sourceCredentialBindings: defineTable(SourceCredentialBindingSchema)
185 .index("by_domainId", ["id"])
186 .index("by_credentialId", ["credentialId"])
187 .index("by_workspaceId", ["workspaceId"])
188 .index("by_organizationId", ["organizationId"])
189 .index("by_accountId", ["accountId"])
190 .index("by_sourceKey", ["sourceKey"]),
191 oauthTokens: defineTable(OAuthTokenSchema)
192 .index("by_domainId", ["id"])
193 .index("by_workspaceId", ["workspaceId"])
194 .index("by_organizationId", ["organizationId"])
195 .index("by_accountId", ["accountId"])
196 .index("by_sourceId", ["sourceId"]),
197 policies: defineTable(PolicySchema)
198 .index("by_domainId", ["id"])
199 .index("by_workspaceId", ["workspaceId"]),
200 storageInstances: defineTable(StorageInstanceSchema)
201 .index("by_domainId", ["id"])
202 .index("by_workspaceId", ["workspaceId"])
203 .index("by_organizationId", ["organizationId"]),
204 storageFileEntries: defineTable(StorageFileEntrySchema)
205 .index("by_domainId", ["id"])
206 .index("by_storageInstanceId", ["storageInstanceId"])
207 .index("by_storageInstanceId_path", ["storageInstanceId", "path"]),
208 storageKvEntries: defineTable(StorageKvEntrySchema)
209 .index("by_domainId", ["id"])
210 .index("by_storageInstanceId", ["storageInstanceId"])
211 .index("by_storageInstanceId_key", ["storageInstanceId", "key"]),
212 storageSqlKvEntries: defineTable(StorageSqlKvEntrySchema)
213 .index("by_domainId", ["id"])
214 .index("by_storageInstanceId", ["storageInstanceId"])
215 .index("by_storageInstanceId_key", ["storageInstanceId", "key"]),
216 approvals: defineTable(ApprovalSchema)
217 .index("by_domainId", ["id"])
218 .index("by_workspaceId", ["workspaceId"])
219 .index("by_taskRunId", ["taskRunId"])
220 .index("by_taskRunId_callId", ["taskRunId", "callId"]),
221 taskRuns: defineTable(TaskRunSchema)
222 .index("by_domainId", ["id"])
223 .index("by_workspaceId", ["workspaceId"])
224 .index("by_sessionId", ["sessionId"]),
225 syncStates: defineTable(SyncStateSchema)
226 .index("by_domainId", ["id"])
227 .index("by_workspaceId", ["workspaceId"]),
228 events: defineTable(EventEnvelopeSchema)
229 .index("by_domainId", ["id"])
230 .index("by_workspaceId", ["workspaceId"])
231 .index("by_workspaceId_sequence", ["workspaceId", "sequence"]),
232});
233
234export type ExecutorConfectTables = TablesFromSchemaDefinition<typeof executorConfectSchema>;
235
236export default executorConfectSchema.convexSchemaDefinition;
apps/convex/convex/source_tool_registry.ts+1686−0
@@ -0,0 +1,1686 @@
1import {
2 PersistentToolApprovalPolicyStoreError,
3 RuntimeAdapterError,
4 ToolProviderError,
5 createPersistentToolApprovalPolicy,
6 makeOpenApiToolProvider,
7 makeToolProviderRegistry,
8 type PersistentToolApprovalRecord,
9 type PersistentToolApprovalStore,
10 type ToolApprovalPolicy,
11 type ToolRegistry,
12 type ToolRegistryCatalogNamespacesInput,
13 type ToolRegistryCatalogNamespacesOutput,
14 type ToolRegistryCatalogToolsInput,
15 type ToolRegistryCatalogToolsOutput,
16 type ToolRegistryDiscoverInput,
17 type ToolRegistryDiscoverOutput,
18 type ToolRegistryToolSummary,
19} from "@executor-v2/engine";
20import {
21 ApprovalSchema,
22 OpenApiInvocationPayloadSchema,
23 type Approval,
24 type CanonicalToolDescriptor,
25 type Source,
26} from "@executor-v2/schema";
27import type { RuntimeToolCallResult } from "@executor-v2/sdk";
28import { v } from "convex/values";
29import * as Effect from "effect/Effect";
30import * as ParseResult from "effect/ParseResult";
31import * as Schema from "effect/Schema";
32
33import { internal } from "./_generated/api";
34import { internalMutation, type ActionCtx } from "./_generated/server";
35
36const runtimeInternal = internal as any;
37
38const decodeApproval = Schema.decodeUnknownSync(ApprovalSchema);
39const decodeOpenApiInvocationPayload = Schema.decodeUnknownSync(OpenApiInvocationPayloadSchema);
40
41const sourceToolRegistryRuntimeKind = "source-tool-registry";
42const defaultPendingRetryAfterMs = 1_000;
43const maxCatalogNamespacesLimit = 5_000;
44const maxCatalogToolsLimit = 50_000;
45const maxUnknownToolSuggestions = 3;
46
47const readBooleanFlag = (value: string | undefined): boolean => {
48 const normalized = value?.trim().toLowerCase();
49 return normalized === "1" || normalized === "true" || normalized === "yes";
50};
51
52const requireToolApprovalsByDefault = readBooleanFlag(
53 process.env.CONVEX_REQUIRE_TOOL_APPROVALS,
54);
55
56const stripConvexSystemFields = (
57 value: Record<string, unknown>,
58): Record<string, unknown> => {
59 const { _id: _ignoredId, _creationTime: _ignoredCreationTime, ...rest } = value;
60 return rest;
61};
62
63const toRuntimeAdapterError = (
64 operation: string,
65 message: string,
66 details: string | null,
67): RuntimeAdapterError =>
68 new RuntimeAdapterError({
69 operation,
70 runtimeKind: sourceToolRegistryRuntimeKind,
71 message,
72 details,
73 });
74
75const normalizePendingRetryAfterMs = (value: number | undefined): number => {
76 if (typeof value !== "number" || !Number.isFinite(value) || value < 0) {
77 return defaultPendingRetryAfterMs;
78 }
79
80 return Math.round(value);
81};
82
83const normalizeDeniedError = (value: string | undefined, toolPath: string): string => {
84 const normalized = value?.trim();
85 if (normalized && normalized.length > 0) {
86 return normalized;
87 }
88
89 return `Tool call denied: ${toolPath}`;
90};
91
92const toToolCallResultFromDecision = (
93 decision:
94 | { kind: "approved" }
95 | { kind: "pending"; approvalId: string; retryAfterMs?: number; error?: string }
96 | { kind: "denied"; error: string },
97 toolPath: string,
98): RuntimeToolCallResult => {
99 if (decision.kind === "approved") {
100 return {
101 ok: true,
102 value: undefined,
103 };
104 }
105
106 if (decision.kind === "pending") {
107 return {
108 ok: false,
109 kind: "pending",
110 approvalId: decision.approvalId,
111 retryAfterMs: normalizePendingRetryAfterMs(decision.retryAfterMs),
112 error: decision.error,
113 };
114 }
115
116 return {
117 ok: false,
118 kind: "denied",
119 error: normalizeDeniedError(decision.error, toolPath),
120 };
121};
122
123const serializeInputPreview = (input: Record<string, unknown> | undefined): string => {
124 try {
125 return JSON.stringify(input ?? {});
126 } catch {
127 return "{}";
128 }
129};
130
131const toPersistentApprovalStoreError = (
132 operation: string,
133 message: string,
134 details: string | null,
135): PersistentToolApprovalPolicyStoreError =>
136 new PersistentToolApprovalPolicyStoreError({
137 operation,
138 message,
139 details,
140 });
141
142const toPersistentApprovalRecord = (
143 approval: Approval,
144): PersistentToolApprovalRecord => ({
145 approvalId: approval.id,
146 workspaceId: approval.workspaceId,
147 runId: approval.taskRunId,
148 callId: approval.callId,
149 toolPath: approval.toolPath,
150 status: approval.status,
151 reason: approval.reason,
152});
153
154const normalizeToolPathForLookup = (path: string): string =>
155 path
156 .trim()
157 .toLowerCase()
158 .replace(/[^a-z0-9]+/g, ".")
159 .replace(/\.+/g, ".")
160 .replace(/^\.|\.$/g, "");
161
162const safeJsonParse = (value: string): unknown => {
163 try {
164 return JSON.parse(value);
165 } catch {
166 return null;
167 }
168};
169
170const jsonObjectFromUnknown = (value: unknown): Record<string, unknown> => {
171 if (!value || typeof value !== "object" || Array.isArray(value)) {
172 return {};
173 }
174
175 return value as Record<string, unknown>;
176};
177
178const normalizeHeaderString = (value: unknown): string | null => {
179 if (typeof value !== "string") {
180 return null;
181 }
182
183 const trimmed = value.trim();
184 return trimmed.length > 0 ? trimmed : null;
185};
186
187const parseSourceConfig = (source: Source): Record<string, unknown> =>
188 jsonObjectFromUnknown(safeJsonParse(source.configJson));
189
190const collectConfiguredHeadersFromSourceConfig = (
191 config: Record<string, unknown>,
192): Record<string, string> => {
193 const headers = jsonObjectFromUnknown(config.headers);
194 const nextHeaders: Record<string, string> = {};
195
196 for (const [rawKey, rawValue] of Object.entries(headers)) {
197 const key = normalizeHeaderString(rawKey);
198 const value = normalizeHeaderString(rawValue);
199 if (key && value) {
200 nextHeaders[key] = value;
201 }
202 }
203
204 return nextHeaders;
205};
206
207const collectAuthHeadersFromSourceConfig = (
208 config: Record<string, unknown>,
209): Record<string, string> => {
210 const auth = jsonObjectFromUnknown(config.auth);
211 const authType = normalizeHeaderString(auth.type)?.toLowerCase();
212 const nextHeaders: Record<string, string> = {};
213
214 if (authType === "bearer") {
215 const token = normalizeHeaderString(auth.token) ?? normalizeHeaderString(auth.value);
216 if (token) {
217 nextHeaders.Authorization = `Bearer ${token}`;
218 }
219 }
220
221 if (authType === "apikey" || authType === "api_key") {
222 const token = normalizeHeaderString(auth.value) ?? normalizeHeaderString(auth.token);
223 if (token) {
224 const headerName = normalizeHeaderString(auth.header) ?? "Authorization";
225 nextHeaders[headerName] = token;
226 }
227 }
228
229 if (authType === "basic") {
230 const username = normalizeHeaderString(auth.username);
231 const password = normalizeHeaderString(auth.password);
232 if (username && password && typeof btoa === "function") {
233 nextHeaders.Authorization = `Basic ${btoa(`${username}:${password}`)}`;
234 }
235 }
236
237 return nextHeaders;
238};
239
240const mergeHeaders = (...sets: ReadonlyArray<Record<string, string>>): Record<string, string> => {
241 const merged: Record<string, string> = {};
242 const keyByLower = new Map<string, string>();
243
244 for (const headers of sets) {
245 for (const [rawKey, rawValue] of Object.entries(headers)) {
246 const key = rawKey.trim();
247 const value = rawValue.trim();
248 if (key.length === 0 || value.length === 0) {
249 continue;
250 }
251
252 const normalizedKey = key.toLowerCase();
253 const existingKey = keyByLower.get(normalizedKey);
254 if (existingKey && existingKey !== key) {
255 delete merged[existingKey];
256 }
257
258 keyByLower.set(normalizedKey, key);
259 merged[key] = value;
260 }
261 }
262
263 return merged;
264};
265
266const resolveSourceCredentialHeadersForInvocation = async (
267 ctx: ActionCtx,
268 source: Source,
269): Promise<Record<string, string>> => {
270 try {
271 const resolved = (await ctx.runAction(
272 runtimeInternal.control_plane.credentials.resolveSourceCredentialHeadersForIngest,
273 {
274 workspaceId: source.workspaceId,
275 sourceId: source.id,
276 sourceName: source.name,
277 sourceEndpoint: source.endpoint,
278 },
279 )) as { headers?: unknown };
280
281 const headers = jsonObjectFromUnknown(resolved.headers);
282 const normalized: Record<string, string> = {};
283
284 for (const [rawKey, rawValue] of Object.entries(headers)) {
285 const key = normalizeHeaderString(rawKey);
286 const value = normalizeHeaderString(rawValue);
287 if (key && value) {
288 normalized[key] = value;
289 }
290 }
291
292 return normalized;
293 } catch {
294 return {};
295 }
296};
297
298const resolveSourceHeadersForInvocation = async (
299 ctx: ActionCtx,
300 source: Source,
301): Promise<Record<string, string>> => {
302 const config = parseSourceConfig(source);
303
304 return mergeHeaders(
305 collectConfiguredHeadersFromSourceConfig(config),
306 collectAuthHeadersFromSourceConfig(config),
307 await resolveSourceCredentialHeadersForInvocation(ctx, source),
308 );
309};
310
311const headersToRecord = (headers: Headers): Record<string, string> => {
312 const record: Record<string, string> = {};
313 headers.forEach((value, key) => {
314 record[key] = value;
315 });
316 return record;
317};
318
319const GraphqlInvocationArgSchema = Schema.Struct({
320 name: Schema.String,
321 description: Schema.NullOr(Schema.String),
322 required: Schema.Boolean,
323 type: Schema.String,
324 defaultValue: Schema.NullOr(Schema.String),
325});
326
327const GraphqlRawInvocationSchema = Schema.Struct({
328 kind: Schema.Literal("graphql_raw"),
329 endpoint: Schema.String,
330});
331
332const GraphqlFieldInvocationSchema = Schema.Struct({
333 kind: Schema.Literal("graphql_field"),
334 endpoint: Schema.String,
335 operationType: Schema.Literal("query", "mutation"),
336 fieldName: Schema.String,
337 args: Schema.Array(GraphqlInvocationArgSchema),
338});
339
340const GraphqlInvocationPayloadSchema = Schema.Union(
341 GraphqlRawInvocationSchema,
342 GraphqlFieldInvocationSchema,
343);
344
345type GraphqlInvocationPayload = typeof GraphqlInvocationPayloadSchema.Type;
346
347const decodeGraphqlInvocationPayload = Schema.decodeUnknownSync(GraphqlInvocationPayloadSchema);
348
349const McpInvocationPayloadSchema = Schema.Struct({
350 kind: Schema.Literal("mcp_tool"),
351 endpoint: Schema.String,
352 transport: Schema.Literal("streamable-http", "sse"),
353 queryParams: Schema.Record({
354 key: Schema.String,
355 value: Schema.String,
356 }),
357 toolName: Schema.String,
358 inputSchema: Schema.optional(Schema.Unknown),
359 outputSchema: Schema.optional(Schema.Unknown),
360});
361
362type McpInvocationPayload = typeof McpInvocationPayloadSchema.Type;
363
364const decodeMcpInvocationPayload = Schema.decodeUnknownSync(McpInvocationPayloadSchema);
365
366const asOptionalString = (value: unknown): string | null =>
367 typeof value === "string" && value.trim().length > 0 ? value : null;
368
369const normalizeInvokeInput = (input: unknown): Record<string, unknown> => {
370 if (!input || typeof input !== "object" || Array.isArray(input)) {
371 return {};
372 }
373
374 return input as Record<string, unknown>;
375};
376
377const createGraphqlOperationQuery = (
378 payload: Extract<GraphqlInvocationPayload, { kind: "graphql_field" }>,
379 args: Record<string, unknown>,
380): {
381 query: string;
382 variables: Record<string, unknown>;
383} => {
384 const definitions: Array<string> = [];
385 const callArgs: Array<string> = [];
386 const variables: Record<string, unknown> = {};
387
388 for (const arg of payload.args) {
389 const value = args[arg.name];
390
391 if (value === undefined || value === null) {
392 if (arg.required) {
393 throw new Error(`Missing required GraphQL argument: ${arg.name}`);
394 }
395
396 continue;
397 }
398
399 const varType = arg.type.trim().length > 0 ? arg.type : "String";
400 definitions.push(`$${arg.name}: ${varType}`);
401 callArgs.push(`${arg.name}: $${arg.name}`);
402 variables[arg.name] = value;
403 }
404
405 const variableDefs = definitions.length > 0 ? `(${definitions.join(", ")})` : "";
406 const fieldArgs = callArgs.length > 0 ? `(${callArgs.join(", ")})` : "";
407 const selectionSet = asOptionalString(args.selectionSet);
408 const fieldSelection =
409 selectionSet && selectionSet.length > 0
410 ? `${payload.fieldName}${fieldArgs} { ${selectionSet} }`
411 : `${payload.fieldName}${fieldArgs}`;
412 const query = `${payload.operationType}${variableDefs} { ${fieldSelection} }`;
413
414 return { query, variables };
415};
416
417const graphqlResponseBody = async (response: Response): Promise<unknown> => {
418 const contentType = response.headers.get("content-type")?.toLowerCase() ?? "";
419 if (contentType.includes("application/json")) {
420 return await response.json();
421 }
422
423 return await response.text();
424};
425
426const createMcpEndpointUrl = (payload: McpInvocationPayload): URL => {
427 const url = new URL(payload.endpoint);
428
429 for (const [key, value] of Object.entries(payload.queryParams)) {
430 url.searchParams.set(key, value);
431 }
432
433 return url;
434};
435
436const postMcpJsonRpc = async (
437 endpoint: URL,
438 body: unknown,
439 sessionId: string | null,
440 sourceHeaders: Record<string, string>,
441): Promise<Response> => {
442 const headers = new Headers({
443 "content-type": "application/json",
444 accept: "application/json, text/event-stream",
445 });
446
447 for (const [key, value] of Object.entries(sourceHeaders)) {
448 headers.set(key, value);
449 }
450
451 if (sessionId && sessionId.trim().length > 0) {
452 headers.set("mcp-session-id", sessionId);
453 }
454
455 return await fetch(endpoint, {
456 method: "POST",
457 headers,
458 body: JSON.stringify(body),
459 });
460};
461
462const decodeMcpJsonResponse = async (response: Response): Promise<Record<string, unknown>> => {
463 const contentType = response.headers.get("content-type")?.toLowerCase() ?? "";
464
465 if (!contentType.includes("application/json")) {
466 const text = await response.text();
467 return { raw: text };
468 }
469
470 return jsonObjectFromUnknown(await response.json());
471};
472
473const describeOutput = (value: unknown): string => {
474 if (typeof value === "string") {
475 return value;
476 }
477
478 try {
479 return JSON.stringify(value);
480 } catch {
481 return String(value);
482 }
483};
484
485const deriveHintFromSchemaJson = (
486 schemaJson: string | null | undefined,
487 fallback: string,
488): string => {
489 if (!schemaJson) {
490 return fallback;
491 }
492
493 const schema = safeJsonParse(schemaJson);
494 if (!schema || typeof schema !== "object" || Array.isArray(schema)) {
495 return fallback;
496 }
497
498 const schemaRecord = schema as Record<string, unknown>;
499 const title = schemaRecord.title;
500 if (typeof title === "string" && title.trim().length > 0) {
501 return title.trim();
502 }
503
504 const type = schemaRecord.type;
505 if (type === "object") {
506 const properties = schemaRecord.properties;
507 if (properties && typeof properties === "object" && !Array.isArray(properties)) {
508 const keys = Object.keys(properties);
509 if (keys.length > 0) {
510 const shown = keys.slice(0, 3).join(", ");
511 return keys.length <= 3 ? `object { ${shown} }` : `object { ${shown}, ... }`;
512 }
513 }
514
515 return "object";
516 }
517
518 if (type === "array") {
519 return "array";
520 }
521
522 if (typeof type === "string") {
523 return type;
524 }
525
526 return fallback;
527};
528
529type WorkspaceToolIndexRow = {
530 workspaceId: string;
531 sourceId: string;
532 sourceName: string;
533 sourceKind: string;
534 artifactId: string;
535 toolId: string;
536 protocol: string;
537 namespace: string;
538 path: string;
539 pathLower: string;
540 normalizedPath: string;
541 name: string;
542 description: string | null;
543 operationHash: string;
544 approvalMode: string;
545 status: string;
546 refHintTableJson?: string | null;
547};
548
549type ArtifactToolRow = {
550 artifactId: string;
551 protocol: string;
552 toolId: string;
553 name: string;
554 description: string | null;
555 canonicalPath: string;
556 operationHash: string;
557 invocationJson: string;
558 inputSchemaJson?: string | null;
559 outputSchemaJson?: string | null;
560 metadataJson?: string | null;
561};
562
563const toToolProviderDetails = (cause: unknown): string =>
564 ParseResult.isParseError(cause)
565 ? ParseResult.TreeFormatter.formatErrorSync(cause)
566 : String(cause);
567
568const toToolProviderError = (
569 providerKind: "openapi" | "graphql" | "mcp",
570 operation: string,
571 message: string,
572 cause: unknown,
573): ToolProviderError =>
574 new ToolProviderError({
575 providerKind,
576 operation,
577 message,
578 details: toToolProviderDetails(cause),
579 });
580
581const scoreSummary = (summary: ToolRegistryToolSummary, query: string): number => {
582 if (query.length === 0) {
583 return 1;
584 }
585
586 const lowerQuery = query.toLowerCase();
587 const lowerPath = summary.path.toLowerCase();
588 const lowerSource = (summary.source ?? "").toLowerCase();
589 const lowerDescription = (summary.description ?? "").toLowerCase();
590
591 if (lowerPath === lowerQuery) {
592 return 100;
593 }
594
595 if (lowerPath.startsWith(lowerQuery)) {
596 return 80;
597 }
598
599 if (lowerPath.includes(lowerQuery)) {
600 return 60;
601 }
602
603 if (lowerSource.includes(lowerQuery)) {
604 return 40;
605 }
606
607 if (lowerDescription.includes(lowerQuery)) {
608 return 30;
609 }
610
611 return 0;
612};
613
614const levenshteinDistance = (left: string, right: string): number => {
615 if (left === right) {
616 return 0;
617 }
618
619 if (left.length === 0) {
620 return right.length;
621 }
622
623 if (right.length === 0) {
624 return left.length;
625 }
626
627 const previous = new Array<number>(right.length + 1);
628 const current = new Array<number>(right.length + 1);
629
630 for (let column = 0; column <= right.length; column += 1) {
631 previous[column] = column;
632 }
633
634 for (let row = 1; row <= left.length; row += 1) {
635 current[0] = row;
636
637 for (let column = 1; column <= right.length; column += 1) {
638 const substitutionCost = left[row - 1] === right[column - 1] ? 0 : 1;
639 current[column] = Math.min(
640 previous[column] + 1,
641 current[column - 1] + 1,
642 previous[column - 1] + substitutionCost,
643 );
644 }
645
646 for (let column = 0; column <= right.length; column += 1) {
647 previous[column] = current[column];
648 }
649 }
650
651 return previous[right.length] ?? right.length;
652};
653
654const uniquePaths = (paths: ReadonlyArray<string>): Array<string> => {
655 const seen = new Set<string>();
656 const ordered: Array<string> = [];
657
658 for (const path of paths) {
659 if (!seen.has(path)) {
660 seen.add(path);
661 ordered.push(path);
662 }
663
664 if (ordered.length >= maxUnknownToolSuggestions) {
665 break;
666 }
667 }
668
669 return ordered;
670};
671
672const toToolSummary = (
673 row: WorkspaceToolIndexRow,
674 options: {
675 includeSchemas: boolean;
676 compact: boolean;
677 artifactTool?: ArtifactToolRow | null;
678 },
679): ToolRegistryToolSummary => {
680 const inputSchemaJson = options.artifactTool?.inputSchemaJson ?? undefined;
681 const outputSchemaJson = options.artifactTool?.outputSchemaJson ?? undefined;
682
683 return {
684 path: row.path,
685 source: row.sourceName,
686 approval: row.approvalMode === "required" ? "required" : "auto",
687 description: options.compact ? undefined : row.description ?? undefined,
688 inputHint: options.compact
689 ? undefined
690 : options.artifactTool
691 ? deriveHintFromSchemaJson(inputSchemaJson ?? null, "input")
692 : undefined,
693 outputHint: options.compact
694 ? undefined
695 : options.artifactTool
696 ? deriveHintFromSchemaJson(outputSchemaJson ?? null, "output")
697 : undefined,
698 typing:
699 options.includeSchemas && (inputSchemaJson || outputSchemaJson)
700 ? {
701 inputSchemaJson,
702 outputSchemaJson,
703 refHintKeys: [],
704 }
705 : undefined,
706 };
707};
708
709const toSearchScoringSummary = (row: WorkspaceToolIndexRow): ToolRegistryToolSummary => ({
710 path: row.path,
711 source: row.sourceName,
712 approval: row.approvalMode === "required" ? "required" : "auto",
713 description: row.description ?? undefined,
714});
715
716const hydrateRowsWithArtifactTools = (
717 ctx: ActionCtx,
718 rows: ReadonlyArray<WorkspaceToolIndexRow>,
719): Effect.Effect<Array<{ row: WorkspaceToolIndexRow; artifactTool: ArtifactToolRow | null }>, RuntimeAdapterError> =>
720 Effect.forEach(
721 rows,
722 (row) =>
723 getArtifactToolEffect(ctx, row.artifactId, row.toolId).pipe(
724 Effect.map((artifactTool) => ({
725 row,
726 artifactTool,
727 })),
728 ),
729 { concurrency: 8 },
730 );
731
732const parseRefHintTableJson = (value: string | null | undefined): Record<string, string> | null => {
733 if (!value) {
734 return null;
735 }
736
737 const parsed = safeJsonParse(value);
738 if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
739 return null;
740 }
741
742 const next: Record<string, string> = {};
743 for (const [key, raw] of Object.entries(parsed as Record<string, unknown>)) {
744 if (typeof raw === "string") {
745 next[key] = raw;
746 }
747 }
748
749 return Object.keys(next).length > 0 ? next : null;
750};
751
752const mergeRefHintTables = (
753 rows: ReadonlyArray<WorkspaceToolIndexRow>,
754 includeSchemas: boolean,
755): Record<string, string> | undefined => {
756 if (!includeSchemas) {
757 return undefined;
758 }
759
760 const merged: Record<string, string> = {};
761 for (const row of rows) {
762 const table = parseRefHintTableJson(row.refHintTableJson ?? null);
763 if (!table) {
764 continue;
765 }
766
767 Object.assign(merged, table);
768 }
769
770 return Object.keys(merged).length > 0 ? merged : undefined;
771};
772
773const listWorkspaceToolsEffect = (
774 ctx: ActionCtx,
775 workspaceId: string,
776 options: {
777 limit: number;
778 sourceId?: string;
779 namespace?: string;
780 },
781): Effect.Effect<Array<WorkspaceToolIndexRow>, RuntimeAdapterError> =>
782 Effect.tryPromise({
783 try: async () =>
784 (await ctx.runQuery(runtimeInternal.control_plane.tool_registry.listWorkspaceTools, {
785 workspaceId,
786 limit: options.limit,
787 sourceId: options.sourceId,
788 namespace: options.namespace,
789 includeDisabled: false,
790 })) as Array<WorkspaceToolIndexRow>,
791 catch: (cause) =>
792 toRuntimeAdapterError(
793 "list_workspace_tools",
794 "Failed to list indexed workspace tools",
795 String(cause),
796 ),
797 });
798
799const searchWorkspaceToolsEffect = (
800 ctx: ActionCtx,
801 workspaceId: string,
802 options: {
803 query: string;
804 limit: number;
805 sourceId?: string;
806 namespace?: string;
807 },
808): Effect.Effect<Array<WorkspaceToolIndexRow>, RuntimeAdapterError> =>
809 Effect.tryPromise({
810 try: async () =>
811 (await ctx.runQuery(runtimeInternal.control_plane.tool_registry.searchWorkspaceTools, {
812 workspaceId,
813 query: options.query,
814 limit: options.limit,
815 sourceId: options.sourceId,
816 namespace: options.namespace,
817 includeDisabled: false,
818 })) as Array<WorkspaceToolIndexRow>,
819 catch: (cause) =>
820 toRuntimeAdapterError(
821 "search_workspace_tools",
822 "Failed to search indexed workspace tools",
823 String(cause),
824 ),
825 });
826
827const getWorkspaceToolByPathEffect = (
828 ctx: ActionCtx,
829 workspaceId: string,
830 toolPath: string,
831): Effect.Effect<WorkspaceToolIndexRow | null, RuntimeAdapterError> =>
832 Effect.tryPromise({
833 try: async () =>
834 (await ctx.runQuery(runtimeInternal.control_plane.tool_registry.getWorkspaceToolByPath, {
835 workspaceId,
836 pathLower: toolPath.toLowerCase(),
837 })) as WorkspaceToolIndexRow | null,
838 catch: (cause) =>
839 toRuntimeAdapterError(
840 "resolve_tool_path",
841 "Failed to resolve tool path",
842 String(cause),
843 ),
844 });
845
846const listWorkspaceToolsByNormalizedPathEffect = (
847 ctx: ActionCtx,
848 workspaceId: string,
849 normalizedPath: string,
850): Effect.Effect<Array<WorkspaceToolIndexRow>, RuntimeAdapterError> =>
851 Effect.tryPromise({
852 try: async () =>
853 (await ctx.runQuery(runtimeInternal.control_plane.tool_registry.listWorkspaceToolsByNormalizedPath, {
854 workspaceId,
855 normalizedPath,
856 limit: 25,
857 })) as Array<WorkspaceToolIndexRow>,
858 catch: (cause) =>
859 toRuntimeAdapterError(
860 "resolve_tool_path",
861 "Failed to resolve normalized tool path",
862 String(cause),
863 ),
864 });
865
866const getArtifactToolEffect = (
867 ctx: ActionCtx,
868 artifactId: string,
869 toolId: string,
870): Effect.Effect<ArtifactToolRow | null, RuntimeAdapterError> =>
871 Effect.tryPromise({
872 try: async () =>
873 (await ctx.runQuery(runtimeInternal.control_plane.tool_registry.getArtifactTool, {
874 artifactId,
875 toolId,
876 })) as ArtifactToolRow | null,
877 catch: (cause) =>
878 toRuntimeAdapterError(
879 "load_artifact_tool",
880 `Failed to load artifact tool: ${artifactId}:${toolId}`,
881 String(cause),
882 ),
883 });
884
885const getSourceForInvocationEffect = (
886 ctx: ActionCtx,
887 workspaceId: string,
888 sourceId: string,
889): Effect.Effect<Source | null, RuntimeAdapterError> =>
890 Effect.tryPromise({
891 try: async () => {
892 const source = (await ctx.runQuery(runtimeInternal.control_plane.sources.getSourceForIngest, {
893 sourceId,
894 })) as Source | null;
895
896 if (!source || source.workspaceId !== workspaceId || !source.enabled) {
897 return null;
898 }
899
900 return source;
901 },
902 catch: (cause) =>
903 toRuntimeAdapterError(
904 "load_source",
905 `Failed to load source for invocation: ${sourceId}`,
906 String(cause),
907 ),
908 });
909
910const invokeToolWithRegistry = (
911 ctx: ActionCtx,
912 source: Source,
913 artifactTool: ArtifactToolRow,
914 args: Record<string, unknown>,
915): Effect.Effect<{ output: unknown; isError: boolean }, RuntimeAdapterError> =>
916 Effect.gen(function* () {
917 const openApiProvider = makeOpenApiToolProvider();
918
919 const graphqlProvider = {
920 kind: "graphql" as const,
921 invoke: (input: { source: Source | null; tool: CanonicalToolDescriptor; args: unknown }) =>
922 Effect.tryPromise({
923 try: async () => {
924 if (!input.source) {
925 throw new Error("GraphQL provider requires a source");
926 }
927
928 const payload = decodeGraphqlInvocationPayload(input.tool.providerPayload);
929 const invokeArgs = normalizeInvokeInput(input.args);
930
931 let query: string;
932 let variables: Record<string, unknown> | undefined;
933 let operationName: string | undefined;
934
935 if (payload.kind === "graphql_raw") {
936 const rawQuery = asOptionalString(invokeArgs.query);
937 if (!rawQuery) {
938 throw new Error("Missing required GraphQL query string at args.query");
939 }
940
941 query = rawQuery;
942 variables = jsonObjectFromUnknown(invokeArgs.variables);
943 operationName = asOptionalString(invokeArgs.operationName) ?? undefined;
944 } else {
945 const built = createGraphqlOperationQuery(payload, invokeArgs);
946 query = built.query;
947 variables = built.variables;
948 operationName = payload.fieldName;
949 }
950
951 const sourceHeaders = await resolveSourceHeadersForInvocation(ctx, input.source);
952
953 const response = await fetch(payload.endpoint, {
954 method: "POST",
955 headers: mergeHeaders(
956 {
957 "content-type": "application/json",
958 },
959 sourceHeaders,
960 ),
961 body: JSON.stringify({
962 query,
963 variables,
964 operationName,
965 }),
966 });
967
968 const body = await graphqlResponseBody(response);
969 const bodyRecord = jsonObjectFromUnknown(body);
970 const hasErrors = Array.isArray(bodyRecord.errors);
971
972 return {
973 output: {
974 status: response.status,
975 headers: headersToRecord(response.headers),
976 body,
977 },
978 isError: response.status >= 400 || hasErrors,
979 };
980 },
981 catch: (cause) =>
982 toToolProviderError(
983 "graphql",
984 "invoke_tool",
985 `GraphQL invocation failed for tool: ${input.tool.toolId}`,
986 cause,
987 ),
988 }),
989 };
990
991 const mcpProvider = {
992 kind: "mcp" as const,
993 invoke: (input: { source: Source | null; tool: CanonicalToolDescriptor; args: unknown }) =>
994 Effect.tryPromise({
995 try: async () => {
996 if (!input.source) {
997 throw new Error("MCP provider requires a source");
998 }
999
1000 const payload = decodeMcpInvocationPayload(input.tool.providerPayload);
1001 const invokeArgs = normalizeInvokeInput(input.args);
1002 const sourceHeaders = await resolveSourceHeadersForInvocation(ctx, input.source);
1003
1004 if (payload.transport !== "streamable-http") {
1005 throw new Error(
1006 `Unsupported MCP transport for runtime invocation: ${payload.transport}`,
1007 );
1008 }
1009
1010 const endpoint = createMcpEndpointUrl(payload);
1011 const initializeResponse = await postMcpJsonRpc(
1012 endpoint,
1013 {
1014 jsonrpc: "2.0",
1015 id: `init_${crypto.randomUUID()}`,
1016 method: "initialize",
1017 params: {
1018 protocolVersion: "2024-11-05",
1019 capabilities: {},
1020 clientInfo: {
1021 name: "executor-v2-runtime",
1022 version: "0.1.0",
1023 },
1024 },
1025 },
1026 null,
1027 sourceHeaders,
1028 );
1029 const initializeBody = await decodeMcpJsonResponse(initializeResponse);
1030
1031 const sessionId = initializeResponse.headers.get("mcp-session-id");
1032
1033 if (initializeResponse.status >= 400 || initializeBody.error !== undefined) {
1034 return {
1035 output: {
1036 status: initializeResponse.status,
1037 headers: headersToRecord(initializeResponse.headers),
1038 body: initializeBody,
1039 },
1040 isError: true,
1041 };
1042 }
1043
1044 await postMcpJsonRpc(
1045 endpoint,
1046 {
1047 jsonrpc: "2.0",
1048 method: "notifications/initialized",
1049 params: {},
1050 },
1051 sessionId,
1052 sourceHeaders,
1053 );
1054
1055 const callResponse = await postMcpJsonRpc(
1056 endpoint,
1057 {
1058 jsonrpc: "2.0",
1059 id: `call_${crypto.randomUUID()}`,
1060 method: "tools/call",
1061 params: {
1062 name: payload.toolName,
1063 arguments: invokeArgs,
1064 },
1065 },
1066 sessionId,
1067 sourceHeaders,
1068 );
1069 const callBody = await decodeMcpJsonResponse(callResponse);
1070
1071 return {
1072 output: {
1073 status: callResponse.status,
1074 headers: headersToRecord(callResponse.headers),
1075 body: callBody,
1076 },
1077 isError: callResponse.status >= 400 || callBody.error !== undefined,
1078 };
1079 },
1080 catch: (cause) =>
1081 toToolProviderError(
1082 "mcp",
1083 "invoke_tool",
1084 `MCP invocation failed for tool: ${input.tool.toolId}`,
1085 cause,
1086 ),
1087 }),
1088 };
1089
1090 const registry = makeToolProviderRegistry([
1091 {
1092 kind: "openapi",
1093 invoke: (input) => openApiProvider.invoke(input),
1094 },
1095 graphqlProvider,
1096 mcpProvider,
1097 ]);
1098
1099 const providerKind = artifactTool.protocol;
1100 const invocationPayload = safeJsonParse(artifactTool.invocationJson);
1101
1102 const descriptor: CanonicalToolDescriptor = {
1103 providerKind: providerKind as any,
1104 sourceId: source.id,
1105 workspaceId: source.workspaceId,
1106 toolId: artifactTool.toolId,
1107 name: artifactTool.name,
1108 description: artifactTool.description,
1109 invocationMode:
1110 providerKind === "graphql"
1111 ? "graphql"
1112 : providerKind === "mcp"
1113 ? "mcp"
1114 : "http",
1115 availability: "remote_capable",
1116 providerPayload:
1117 providerKind === "openapi"
1118 ? decodeOpenApiInvocationPayload(invocationPayload)
1119 : providerKind === "graphql"
1120 ? decodeGraphqlInvocationPayload(invocationPayload)
1121 : decodeMcpInvocationPayload(invocationPayload),
1122 };
1123
1124 const invocation = yield* registry
1125 .invoke({
1126 source,
1127 tool: descriptor,
1128 args,
1129 })
1130 .pipe(
1131 Effect.mapError((cause) =>
1132 cause._tag === "ToolProviderError"
1133 ? toRuntimeAdapterError("invoke_tool", cause.message, cause.details)
1134 : toRuntimeAdapterError("invoke_tool", cause.message, null),
1135 ),
1136 );
1137
1138 return invocation;
1139 });
1140
1141const unknownToolPathErrorMessage = (
1142 requestedPath: string,
1143 suggestions: ReadonlyArray<string>,
1144): string => {
1145 const hintQuery = requestedPath.trim().length > 0 ? requestedPath.trim() : "tool";
1146 const suggestionText =
1147 suggestions.length > 0 ? ` Did you mean: ${suggestions.join(", ")}.` : "";
1148
1149 return `Unknown tool path: ${requestedPath}.${suggestionText} Use tools.discover({ query: ${JSON.stringify(
1150 hintQuery,
1151 )} }) or tools.catalog.tools({ query: ${JSON.stringify(hintQuery)} }) to find available tool paths.`;
1152};
1153
1154const resolveToolPath = (
1155 ctx: ActionCtx,
1156 workspaceId: string,
1157 requestedPath: string,
1158): Effect.Effect<
1159 { row: WorkspaceToolIndexRow | null; suggestions: Array<string> },
1160 RuntimeAdapterError
1161> =>
1162 Effect.gen(function* () {
1163 const trimmedPath = requestedPath.trim();
1164 if (trimmedPath.length === 0) {
1165 return {
1166 row: null,
1167 suggestions: [],
1168 };
1169 }
1170
1171 const exact = yield* getWorkspaceToolByPathEffect(ctx, workspaceId, trimmedPath);
1172 if (exact && exact.status === "active") {
1173 return {
1174 row: exact,
1175 suggestions: [],
1176 };
1177 }
1178
1179 const normalizedPath = normalizeToolPathForLookup(trimmedPath);
1180 const normalizedMatches = yield* listWorkspaceToolsByNormalizedPathEffect(
1181 ctx,
1182 workspaceId,
1183 normalizedPath,
1184 );
1185
1186 if (normalizedMatches.length === 1) {
1187 return {
1188 row: normalizedMatches[0] ?? null,
1189 suggestions: [],
1190 };
1191 }
1192
1193 if (normalizedMatches.length > 1) {
1194 const preferred = [...normalizedMatches].sort((left, right) => {
1195 if (left.path.length !== right.path.length) {
1196 return left.path.length - right.path.length;
1197 }
1198
1199 return left.path.localeCompare(right.path);
1200 })[0];
1201
1202 return {
1203 row: preferred ?? null,
1204 suggestions: [],
1205 };
1206 }
1207
1208 const candidates = yield* searchWorkspaceToolsEffect(ctx, workspaceId, {
1209 query: trimmedPath,
1210 limit: 20,
1211 });
1212
1213 if (candidates.length === 0) {
1214 return {
1215 row: null,
1216 suggestions: [],
1217 };
1218 }
1219
1220 const lowerRequested = trimmedPath.toLowerCase();
1221 const closest = [...candidates]
1222 .map((candidate) => ({
1223 candidate,
1224 distance: levenshteinDistance(candidate.path.toLowerCase(), lowerRequested),
1225 }))
1226 .sort((left, right) => {
1227 if (left.distance !== right.distance) {
1228 return left.distance - right.distance;
1229 }
1230
1231 return left.candidate.path.localeCompare(right.candidate.path);
1232 });
1233
1234 const best = closest[0];
1235 const maxDistance = Math.max(2, Math.floor(trimmedPath.length * 0.2));
1236
1237 if (best && best.distance <= maxDistance) {
1238 return {
1239 row: best.candidate,
1240 suggestions: [],
1241 };
1242 }
1243
1244 return {
1245 row: null,
1246 suggestions: uniquePaths(closest.map((item) => item.candidate.path)),
1247 };
1248 });
1249
1250const approvalModeValidator = v.union(v.literal("auto"), v.literal("required"));
1251
1252export const evaluateToolApproval = internalMutation({
1253 args: {
1254 workspaceId: v.string(),
1255 runId: v.string(),
1256 callId: v.string(),
1257 toolPath: v.string(),
1258 inputPreviewJson: v.string(),
1259 defaultMode: approvalModeValidator,
1260 requireApprovals: v.optional(v.boolean()),
1261 retryAfterMs: v.optional(v.number()),
1262 },
1263 handler: async (ctx, args) => {
1264 const taskRunRow = await ctx.db
1265 .query("taskRuns")
1266 .withIndex("by_domainId", (q) => q.eq("id", args.runId))
1267 .unique();
1268
1269 if (!taskRunRow || taskRunRow.workspaceId !== args.workspaceId) {
1270 return {
1271 kind: "denied" as const,
1272 error: `Unknown run for approval request: ${args.runId}`,
1273 };
1274 }
1275
1276 const store: PersistentToolApprovalStore = {
1277 findByRunAndCall: (input) =>
1278 Effect.tryPromise({
1279 try: async () => {
1280 const rows = await ctx.db
1281 .query("approvals")
1282 .withIndex("by_taskRunId_callId", (q) =>
1283 q.eq("taskRunId", input.runId).eq("callId", input.callId),
1284 )
1285 .collect();
1286
1287 const row = rows.find((candidate) => candidate.workspaceId === input.workspaceId) ?? null;
1288 if (!row) {
1289 return null;
1290 }
1291
1292 const approval = decodeApproval(
1293 stripConvexSystemFields(row as unknown as Record<string, unknown>),
1294 );
1295
1296 return toPersistentApprovalRecord(approval);
1297 },
1298 catch: (cause) =>
1299 toPersistentApprovalStoreError(
1300 "approvals.find",
1301 "Failed to query approval",
1302 String(cause),
1303 ),
1304 }),
1305
1306 createPending: (input) =>
1307 Effect.tryPromise({
1308 try: async () => {
1309 const existingRows = await ctx.db
1310 .query("approvals")
1311 .withIndex("by_taskRunId_callId", (q) =>
1312 q.eq("taskRunId", input.runId).eq("callId", input.callId),
1313 )
1314 .collect();
1315
1316 const existingRow =
1317 existingRows.find((candidate) => candidate.workspaceId === input.workspaceId) ?? null;
1318 if (existingRow) {
1319 return toPersistentApprovalRecord(
1320 decodeApproval(
1321 stripConvexSystemFields(existingRow as unknown as Record<string, unknown>),
1322 ),
1323 );
1324 }
1325
1326 const approval = {
1327 id: `apr_${crypto.randomUUID()}`,
1328 workspaceId: input.workspaceId,
1329 taskRunId: input.runId,
1330 callId: input.callId,
1331 toolPath: input.toolPath,
1332 status: "pending",
1333 inputPreviewJson: input.inputPreviewJson,
1334 reason: null,
1335 requestedAt: Date.now(),
1336 resolvedAt: null,
1337 } as Approval;
1338
1339 await ctx.db.insert("approvals", approval);
1340 return toPersistentApprovalRecord(approval);
1341 },
1342 catch: (cause) =>
1343 toPersistentApprovalStoreError(
1344 "approvals.create",
1345 "Failed to create pending approval",
1346 String(cause),
1347 ),
1348 }),
1349 };
1350
1351 const policy = createPersistentToolApprovalPolicy({
1352 store,
1353 requireApprovals: args.requireApprovals === true,
1354 retryAfterMs: args.retryAfterMs,
1355 serializeInputPreview: () => args.inputPreviewJson,
1356 onStoreError: (error) => ({
1357 kind: "denied",
1358 error:
1359 error.details && error.details.length > 0
1360 ? `${error.message}: ${error.details}`
1361 : error.message,
1362 }),
1363 });
1364
1365 return await policy.evaluate({
1366 workspaceId: args.workspaceId,
1367 runId: args.runId,
1368 callId: args.callId,
1369 toolPath: args.toolPath,
1370 defaultMode: args.defaultMode,
1371 });
1372 },
1373});
1374
1375const createConvexPersistentToolApprovalPolicy = (
1376 ctx: ActionCtx,
1377 workspaceId: string,
1378 options: {
1379 requireApprovals: boolean;
1380 retryAfterMs: number;
1381 },
1382): ToolApprovalPolicy => ({
1383 evaluate: (input) =>
1384 ctx.runMutation(runtimeInternal.source_tool_registry.evaluateToolApproval, {
1385 workspaceId,
1386 runId: input.runId,
1387 callId: input.callId,
1388 toolPath: input.toolPath,
1389 inputPreviewJson: serializeInputPreview(input.input),
1390 defaultMode: input.defaultMode,
1391 requireApprovals: options.requireApprovals,
1392 retryAfterMs: options.retryAfterMs,
1393 }),
1394});
1395
1396const evaluateApprovalDecisionEffect = (
1397 policy: ToolApprovalPolicy,
1398 input: {
1399 workspaceId: string;
1400 runId: string;
1401 callId: string;
1402 toolPath: string;
1403 source: string;
1404 defaultMode: "auto" | "required";
1405 args: Record<string, unknown>;
1406 },
1407): Effect.Effect<
1408 | { kind: "approved" }
1409 | { kind: "pending"; approvalId: string; retryAfterMs?: number; error?: string }
1410 | { kind: "denied"; error: string },
1411 RuntimeAdapterError
1412> =>
1413 Effect.tryPromise({
1414 try: () =>
1415 Promise.resolve(
1416 policy.evaluate({
1417 workspaceId: input.workspaceId,
1418 runId: input.runId,
1419 callId: input.callId,
1420 toolPath: input.toolPath,
1421 source: input.source,
1422 input: input.args,
1423 defaultMode: input.defaultMode,
1424 }),
1425 ),
1426 catch: (cause) =>
1427 toRuntimeAdapterError(
1428 "evaluate_approval",
1429 `Tool approval evaluation failed: ${input.toolPath}`,
1430 String(cause),
1431 ),
1432 });
1433
1434const describeSource = (row: {
1435 sourceName: string;
1436 sourceKind: string;
1437}): string => `${row.sourceKind.toUpperCase()} source: ${row.sourceName}`;
1438
1439export type ConvexSourceToolRegistryOptions = {
1440 requireToolApprovals?: boolean;
1441 approvalRetryAfterMs?: number;
1442};
1443
1444export const createConvexSourceToolRegistry = (
1445 ctx: ActionCtx,
1446 workspaceId: string,
1447 options: ConvexSourceToolRegistryOptions = {},
1448): ToolRegistry => {
1449 const requireApprovals = options.requireToolApprovals ?? requireToolApprovalsByDefault;
1450 const approvalRetryAfterMs =
1451 typeof options.approvalRetryAfterMs === "number" &&
1452 Number.isFinite(options.approvalRetryAfterMs) &&
1453 options.approvalRetryAfterMs >= 0
1454 ? Math.round(options.approvalRetryAfterMs)
1455 : defaultPendingRetryAfterMs;
1456
1457 const approvalPolicy = createConvexPersistentToolApprovalPolicy(ctx, workspaceId, {
1458 requireApprovals,
1459 retryAfterMs: approvalRetryAfterMs,
1460 });
1461
1462 return {
1463 callTool: (input) =>
1464 Effect.gen(function* () {
1465 const resolved = yield* resolveToolPath(ctx, workspaceId, input.toolPath);
1466 if (!resolved.row) {
1467 return {
1468 ok: false,
1469 kind: "failed",
1470 error: unknownToolPathErrorMessage(input.toolPath, resolved.suggestions),
1471 } satisfies RuntimeToolCallResult;
1472 }
1473
1474 const args = normalizeInvokeInput(input.input);
1475 const toolPath = resolved.row.path;
1476 const approval = yield* evaluateApprovalDecisionEffect(approvalPolicy, {
1477 workspaceId,
1478 runId: input.runId,
1479 callId: input.callId,
1480 toolPath,
1481 source: resolved.row.sourceName,
1482 defaultMode:
1483 resolved.row.approvalMode === "required"
1484 ? "required"
1485 : "auto",
1486 args,
1487 });
1488
1489 if (approval.kind !== "approved") {
1490 return toToolCallResultFromDecision(approval, toolPath);
1491 }
1492
1493 const artifactTool = yield* getArtifactToolEffect(
1494 ctx,
1495 resolved.row.artifactId,
1496 resolved.row.toolId,
1497 );
1498
1499 if (!artifactTool) {
1500 return {
1501 ok: false,
1502 kind: "failed",
1503 error: `Missing artifact tool payload for ${resolved.row.path}`,
1504 } satisfies RuntimeToolCallResult;
1505 }
1506
1507 const source = yield* getSourceForInvocationEffect(ctx, workspaceId, resolved.row.sourceId);
1508 if (!source) {
1509 return {
1510 ok: false,
1511 kind: "failed",
1512 error: `Source unavailable for tool: ${resolved.row.path}`,
1513 } satisfies RuntimeToolCallResult;
1514 }
1515
1516 const invocation = yield* invokeToolWithRegistry(ctx, source, artifactTool, args);
1517 if (invocation.isError) {
1518 return {
1519 ok: false,
1520 kind: "failed",
1521 error: describeOutput(invocation.output),
1522 } satisfies RuntimeToolCallResult;
1523 }
1524
1525 return {
1526 ok: true,
1527 value: invocation.output,
1528 } satisfies RuntimeToolCallResult;
1529 }),
1530
1531 discover: (input: ToolRegistryDiscoverInput) =>
1532 Effect.gen(function* () {
1533 const limit = Math.max(1, Math.min(50, input.limit ?? 8));
1534 const queryText = (input.query ?? "").trim();
1535 const compact = input.compact === true;
1536 const includeSchemas = input.includeSchemas === true;
1537 const fetchLimit = Math.max(limit * 6, 50);
1538
1539 const rows =
1540 queryText.length > 0
1541 ? yield* searchWorkspaceToolsEffect(ctx, workspaceId, {
1542 query: queryText,
1543 limit: fetchLimit,
1544 })
1545 : yield* listWorkspaceToolsEffect(ctx, workspaceId, {
1546 limit: fetchLimit,
1547 });
1548
1549 const rankedRows = rows
1550 .map((row) => ({
1551 row,
1552 score: scoreSummary(toSearchScoringSummary(row), queryText.toLowerCase()),
1553 }))
1554 .filter((item) => item.score > 0)
1555 .sort((left, right) => right.score - left.score)
1556 .slice(0, limit);
1557
1558 const selectedRows = rankedRows.map((item) => item.row);
1559
1560 const summaries = includeSchemas
1561 ? (
1562 yield* hydrateRowsWithArtifactTools(ctx, selectedRows).pipe(
1563 Effect.map((entries) =>
1564 entries.map(({ row, artifactTool }) =>
1565 toToolSummary(row, {
1566 includeSchemas,
1567 compact,
1568 artifactTool,
1569 }),
1570 ),
1571 ),
1572 )
1573 )
1574 : selectedRows.map((row) =>
1575 toToolSummary(row, {
1576 includeSchemas,
1577 compact,
1578 }),
1579 );
1580
1581 return {
1582 bestPath: summaries[0]?.path ?? null,
1583 results: summaries,
1584 total: summaries.length,
1585 refHintTable: mergeRefHintTables(rows, includeSchemas),
1586 } satisfies ToolRegistryDiscoverOutput;
1587 }),
1588
1589 catalogNamespaces: (input: ToolRegistryCatalogNamespacesInput) =>
1590 Effect.gen(function* () {
1591 const limit = Math.max(1, Math.min(maxCatalogNamespacesLimit, input.limit ?? 50));
1592
1593 const rows = yield* Effect.tryPromise({
1594 try: async () =>
1595 (await ctx.runQuery(runtimeInternal.control_plane.tool_registry.listWorkspaceNamespaces, {
1596 workspaceId,
1597 limit,
1598 })) as Array<{
1599 namespace: string;
1600 source: string;
1601 sourceId: string;
1602 sourceKind: string;
1603 toolCount: number;
1604 samplePaths: Array<string>;
1605 }>,
1606 catch: (cause) =>
1607 toRuntimeAdapterError(
1608 "catalog_namespaces",
1609 "Failed to catalog namespaces",
1610 String(cause),
1611 ),
1612 });
1613
1614 return {
1615 namespaces: rows.map((row) => ({
1616 namespace: row.namespace,
1617 toolCount: row.toolCount,
1618 samplePaths: row.samplePaths,
1619 source: row.source,
1620 sourceKey: row.sourceId,
1621 description: describeSource({ sourceName: row.source, sourceKind: row.sourceKind }),
1622 })),
1623 total: rows.length,
1624 } satisfies ToolRegistryCatalogNamespacesOutput;
1625 }),
1626
1627 catalogTools: (input: ToolRegistryCatalogToolsInput) =>
1628 Effect.gen(function* () {
1629 const limit = Math.max(1, Math.min(maxCatalogToolsLimit, input.limit ?? 50));
1630 const queryText = (input.query ?? "").trim();
1631 const compact = input.compact === true;
1632 const includeSchemas = input.includeSchemas === true;
1633 const namespace = input.namespace?.trim();
1634
1635 const rows =
1636 queryText.length > 0
1637 ? yield* searchWorkspaceToolsEffect(ctx, workspaceId, {
1638 query: queryText,
1639 namespace,
1640 limit: Math.max(limit * 4, 50),
1641 })
1642 : yield* listWorkspaceToolsEffect(ctx, workspaceId, {
1643 namespace,
1644 limit: Math.max(limit * 4, 50),
1645 });
1646
1647 const rankedRows = rows
1648 .map((row) => ({
1649 row,
1650 score: scoreSummary(toSearchScoringSummary(row), queryText.toLowerCase()),
1651 }))
1652 .filter((item) => item.score > 0)
1653 .sort((left, right) => right.score - left.score)
1654 .slice(0, limit);
1655
1656 const selectedRows = rankedRows.map((item) => item.row);
1657
1658 const summaries = includeSchemas
1659 ? (
1660 yield* hydrateRowsWithArtifactTools(ctx, selectedRows).pipe(
1661 Effect.map((entries) =>
1662 entries.map(({ row, artifactTool }) =>
1663 toToolSummary(row, {
1664 includeSchemas,
1665 compact,
1666 artifactTool,
1667 }),
1668 ),
1669 ),
1670 )
1671 )
1672 : selectedRows.map((row) =>
1673 toToolSummary(row, {
1674 includeSchemas,
1675 compact,
1676 }),
1677 );
1678
1679 return {
1680 results: summaries,
1681 total: summaries.length,
1682 refHintTable: mergeRefHintTables(rows, includeSchemas),
1683 } satisfies ToolRegistryCatalogToolsOutput;
1684 }),
1685 } as ToolRegistry;
1686};
apps/convex/convex/task_runs.ts+78−0
@@ -0,0 +1,78 @@
1import { type TaskRun } from "@executor-v2/schema";
2import { v } from "convex/values";
3
4import { internalMutation } from "./_generated/server";
5
6const taskRunTerminalStatusValidator = v.union(
7 v.literal("completed"),
8 v.literal("failed"),
9 v.literal("timed_out"),
10 v.literal("denied"),
11);
12
13export const startTaskRun = internalMutation({
14 args: {
15 workspaceId: v.string(),
16 runId: v.string(),
17 sessionId: v.optional(v.string()),
18 runtimeId: v.optional(v.string()),
19 codeHash: v.optional(v.string()),
20 },
21 handler: async (ctx, args): Promise<void> => {
22 const existing = await ctx.db
23 .query("taskRuns")
24 .withIndex("by_domainId", (q) => q.eq("id", args.runId))
25 .unique();
26
27 if (existing) {
28 if (existing.workspaceId !== args.workspaceId) {
29 throw new Error(`Task run workspace mismatch: ${args.runId}`);
30 }
31 return;
32 }
33
34 const taskRun = {
35 id: args.runId,
36 workspaceId: args.workspaceId,
37 sessionId: args.sessionId ?? "session_runtime",
38 runtimeId: args.runtimeId ?? "runtime",
39 codeHash: args.codeHash ?? "runtime",
40 status: "running",
41 startedAt: Date.now(),
42 completedAt: null,
43 exitCode: null,
44 error: null,
45 } as TaskRun;
46
47 await ctx.db.insert("taskRuns", taskRun);
48 },
49});
50
51export const finishTaskRun = internalMutation({
52 args: {
53 workspaceId: v.string(),
54 runId: v.string(),
55 status: taskRunTerminalStatusValidator,
56 error: v.optional(v.union(v.string(), v.null())),
57 },
58 handler: async (ctx, args): Promise<void> => {
59 const existing = await ctx.db
60 .query("taskRuns")
61 .withIndex("by_domainId", (q) => q.eq("id", args.runId))
62 .unique();
63
64 if (!existing) {
65 return;
66 }
67
68 if (existing.workspaceId !== args.workspaceId) {
69 throw new Error(`Task run workspace mismatch: ${args.runId}`);
70 }
71
72 await ctx.db.patch(existing._id, {
73 status: args.status,
74 completedAt: Date.now(),
75 error: args.error ?? null,
76 });
77 },
78});
apps/convex/convex/tsconfig.json+25−0
@@ -0,0 +1,25 @@
1{
2 /* This TypeScript project config describes the environment that
3 * Convex functions run in and is used to typecheck them.
4 * You can modify it, but some settings are required to use Convex.
5 */
6 "compilerOptions": {
7 /* These settings are not required by Convex and can be modified. */
8 "allowJs": true,
9 "strict": true,
10 "moduleResolution": "Bundler",
11 "jsx": "react-jsx",
12 "skipLibCheck": true,
13 "allowSyntheticDefaultImports": true,
14
15 /* These compiler options are required by Convex */
16 "target": "ESNext",
17 "lib": ["ES2021", "dom"],
18 "forceConsistentCasingInFileNames": true,
19 "module": "ESNext",
20 "isolatedModules": true,
21 "noEmit": true
22 },
23 "include": ["./**/*"],
24 "exclude": ["./_generated"]
25}
apps/convex/convex/workflow.ts+15−0
@@ -0,0 +1,15 @@
1import { WorkflowManager } from "@convex-dev/workflow";
2
3import { components } from "./_generated/api";
4
5export const workflow = new WorkflowManager(components.workflow, {
6 workpoolOptions: {
7 defaultRetryBehavior: {
8 maxAttempts: 3,
9 initialBackoffMs: 250,
10 base: 2,
11 },
12 retryActionsByDefault: true,
13 maxParallelism: 8,
14 },
15});
apps/convex/node_modules/.bin/convex+1−0
@@ -0,0 +1 @@
1../convex/bin/main.js
apps/convex/node_modules/.bin/vitest+1−0
@@ -0,0 +1 @@
1../vitest/vitest.mjs
apps/convex/node_modules/.vite/vitest/da39a3ee5e6b4b0d3255bfef95601890afd80709/results.json+1−0
@@ -0,0 +1 @@
1{"version":"3.2.4","results":[[":convex/executor.test.ts",{"duration":746.3599650000001,"failed":false}],[":convex/sources.test.ts",{"duration":235.0589490000002,"failed":false}]]}
apps/convex/node_modules/@convex-dev/workflow+1−0
@@ -0,0 +1 @@
1../../../../node_modules/.bun/@convex-dev+workflow@0.3.4+e4a957bbb87593a0/node_modules/@convex-dev/workflow
apps/convex/node_modules/@effect/vitest+1−0
@@ -0,0 +1 @@
1../../../../node_modules/.bun/@effect+vitest@0.27.0+745106daec5afff3/node_modules/@effect/vitest
apps/convex/node_modules/@executor-v2/confect+1−0
@@ -0,0 +1 @@
1../../../../packages/confect
apps/convex/node_modules/@executor-v2/control-plane+1−0
@@ -0,0 +1 @@
1../../../../packages/control-plane
apps/convex/node_modules/@executor-v2/domain+1−0
@@ -0,0 +1 @@
1../../../../packages/domain
apps/convex/node_modules/@executor-v2/engine+1−0
@@ -0,0 +1 @@
1../../../../packages/engine
apps/convex/node_modules/@executor-v2/management-api+1−0
@@ -0,0 +1 @@
1../../../../packages/management-api
apps/convex/node_modules/@executor-v2/mcp-gateway+1−0
@@ -0,0 +1 @@
1../../../../packages/mcp-gateway
apps/convex/node_modules/@executor-v2/persistence-convex+1−0
@@ -0,0 +1 @@
1../../../../packages/state-convex
apps/convex/node_modules/@executor-v2/persistence-ports+1−0
@@ -0,0 +1 @@
1../../../../packages/state-contracts
apps/convex/node_modules/@executor-v2/rpc+1−0
@@ -0,0 +1 @@
1../../../../packages/rpc
apps/convex/node_modules/@executor-v2/runtime-cloudflare-worker-loader+1−0
@@ -0,0 +1 @@
1../../../../packages/runtime-cloudflare-worker-loader
apps/convex/node_modules/@executor-v2/runtime-local-inproc+1−0
@@ -0,0 +1 @@
1../../../../packages/runtime-local-inproc
apps/convex/node_modules/@executor-v2/schema+1−0
@@ -0,0 +1 @@
1../../../../packages/schema
apps/convex/node_modules/@executor-v2/sdk+1−0
@@ -0,0 +1 @@
1../../../../packages/sdk
apps/convex/node_modules/@executor-v2/state-convex+1−0
@@ -0,0 +1 @@
1../../../../packages/state-convex
apps/convex/node_modules/@modelcontextprotocol/sdk+1−0
@@ -0,0 +1 @@
1../../../../node_modules/.bun/@modelcontextprotocol+sdk@1.27.1/node_modules/@modelcontextprotocol/sdk
apps/convex/node_modules/@workos-inc/node+1−0
@@ -0,0 +1 @@
1../../../../node_modules/.bun/@workos-inc+node@8.7.0/node_modules/@workos-inc/node
apps/convex/node_modules/convex+1−0
@@ -0,0 +1 @@
1../../../node_modules/.bun/convex@1.32.0+b1ab299f0a400331/node_modules/convex
apps/convex/node_modules/convex-test+1−0
@@ -0,0 +1 @@
1../../../packages/convex-test
apps/convex/node_modules/effect+1−0
@@ -0,0 +1 @@
1../../../node_modules/.bun/effect@3.19.19/node_modules/effect
apps/convex/node_modules/jose+1−0
@@ -0,0 +1 @@
1../../../node_modules/.bun/jose@6.1.3/node_modules/jose
apps/convex/node_modules/vitest+1−0
@@ -0,0 +1 @@
1../../../node_modules/.bun/vitest@3.2.4+dddfa60a3fc73abb/node_modules/vitest
apps/convex/package.json+32−0
@@ -0,0 +1,32 @@
1{
2 "name": "@executor-v2/app-convex",
3 "private": true,
4 "type": "module",
5 "scripts": {
6 "dev": "CREDENTIAL_ENCRYPTION_KEY=dev-credential-encryption-key bunx convex dev",
7 "test": "CREDENTIAL_ENCRYPTION_KEY=test-credential-encryption-key bunx vitest run --no-watch convex/*.test.ts",
8 "typecheck": "bunx tsc --noEmit -p tsconfig.json",
9 "convex:codegen": "bunx convex codegen"
10 },
11 "dependencies": {
12 "@convex-dev/workflow": "^0.3.4",
13 "@modelcontextprotocol/sdk": "^1.27.1",
14 "@executor-v2/confect": "workspace:*",
15 "@executor-v2/domain": "workspace:*",
16 "@executor-v2/engine": "workspace:*",
17 "@executor-v2/management-api": "workspace:*",
18 "@executor-v2/mcp-gateway": "workspace:*",
19 "@executor-v2/persistence-ports": "workspace:*",
20 "@executor-v2/runtime-cloudflare-worker-loader": "workspace:*",
21 "@executor-v2/schema": "workspace:*",
22 "@executor-v2/sdk": "workspace:*",
23 "convex": "catalog:",
24 "effect": "catalog:",
25 "jose": "^6.1.0"
26 },
27 "devDependencies": {
28 "@effect/vitest": "catalog:",
29 "convex-test": "workspace:*",
30 "vitest": "catalog:"
31 }
32}
apps/convex/src/main.ts+1−0
@@ -0,0 +1 @@
1export {};
apps/convex/tsconfig.json+4−0
@@ -0,0 +1,4 @@
1{
2 "extends": "../../tsconfig.json",
3 "include": ["src", "convex"]
4}
apps/pm/README.md+19−0
@@ -0,0 +1,19 @@
1# app-pm
2
3Local Process Manager app scaffold for Executor v2.
4
5Current scaffold includes:
6- local MCP endpoint at `GET/POST/DELETE /v1/mcp`
7- health endpoint at `GET /healthz`
8- MCP tool routing via `@executor-v2/mcp-gateway`
9- runtime selection via `PM_RUNTIME_KIND` (`local-inproc`, `deno-subprocess`, `cloudflare-worker-loader`)
10- runtime callback endpoint at `POST /v1/runtime/tool-call`
11- control-plane source endpoints at `GET/POST /v1/workspaces/:workspaceId/sources`
12- control-plane source removal endpoint at `DELETE /v1/workspaces/:workspaceId/sources/:sourceId`
13- generated OpenAPI spec endpoint at `GET /v1/openapi.json`
14
15App wiring is now split by responsibility:
16- `src/config.ts`: Effect config service (`PORT`)
17- `src/mcp-handler.ts`: MCP transport wiring to shared run execution service
18- `src/http-server.ts`: Effect HTTP server startup
19- `src/main.ts`: Layer composition + process entrypoint
apps/pm/node_modules/.bin/vitest+1−0
@@ -0,0 +1 @@
1../vitest/vitest.mjs
apps/pm/node_modules/.vite/vitest/da39a3ee5e6b4b0d3255bfef95601890afd80709/results.json+1−0
@@ -0,0 +1 @@
1{"version":"3.2.4","results":[[":src/tool-call-handler.test.ts",{"duration":65.40639299999975,"failed":false}],[":src/execute.e2e.test.ts",{"duration":1312.0678289999998,"failed":false}],[":src/sources-handler.test.ts",{"duration":90.26854400000002,"failed":false}],[":src/persistent-approval-policy.test.ts",{"duration":66.12446200000022,"failed":false}],[":src/storage-service.test.ts",{"duration":96.20161000000007,"failed":false}]]}
apps/pm/node_modules/@effect/platform+1−0
@@ -0,0 +1 @@
1../../../../node_modules/.bun/@effect+platform@0.93.8+a91c478e54a5dd97/node_modules/@effect/platform
apps/pm/node_modules/@effect/platform-bun+1−0
@@ -0,0 +1 @@
1../../../../node_modules/.bun/@effect+platform-bun@0.86.0+e085871485f58d8a/node_modules/@effect/platform-bun
apps/pm/node_modules/@effect/vitest+1−0
@@ -0,0 +1 @@
1../../../../node_modules/.bun/@effect+vitest@0.27.0+745106daec5afff3/node_modules/@effect/vitest
apps/pm/node_modules/@executor-v2/control-plane+1−0
@@ -0,0 +1 @@
1../../../../packages/control-plane
apps/pm/node_modules/@executor-v2/domain+1−0
@@ -0,0 +1 @@
1../../../../packages/domain
apps/pm/node_modules/@executor-v2/engine+1−0
@@ -0,0 +1 @@
1../../../../packages/engine
apps/pm/node_modules/@executor-v2/management-api+1−0
@@ -0,0 +1 @@
1../../../../packages/management-api
apps/pm/node_modules/@executor-v2/mcp-gateway+1−0
@@ -0,0 +1 @@
1../../../../packages/mcp-gateway
apps/pm/node_modules/@executor-v2/persistence-local+1−0
@@ -0,0 +1 @@
1../../../../packages/state-local-file
apps/pm/node_modules/@executor-v2/persistence-ports+1−0
@@ -0,0 +1 @@
1../../../../packages/state-contracts
apps/pm/node_modules/@executor-v2/rpc+1−0
@@ -0,0 +1 @@
1../../../../packages/rpc
apps/pm/node_modules/@executor-v2/runtime-cloudflare-worker-loader+1−0
@@ -0,0 +1 @@
1../../../../packages/runtime-cloudflare-worker-loader
apps/pm/node_modules/@executor-v2/runtime-deno-subprocess+1−0
@@ -0,0 +1 @@
1../../../../packages/runtime-deno-subprocess
apps/pm/node_modules/@executor-v2/runtime-local-inproc+1−0
@@ -0,0 +1 @@
1../../../../packages/runtime-local-inproc
apps/pm/node_modules/@executor-v2/schema+1−0
@@ -0,0 +1 @@
1../../../../packages/schema
apps/pm/node_modules/@executor-v2/sdk+1−0
@@ -0,0 +1 @@
1../../../../packages/sdk
apps/pm/node_modules/@executor-v2/source-manager+1−0
@@ -0,0 +1 @@
1../../../../packages/source-manager
apps/pm/node_modules/@modelcontextprotocol/sdk+1−0
@@ -0,0 +1 @@
1../../../../node_modules/.bun/@modelcontextprotocol+sdk@1.27.1/node_modules/@modelcontextprotocol/sdk
apps/pm/node_modules/effect+1−0
@@ -0,0 +1 @@
1../../../node_modules/.bun/effect@3.19.19/node_modules/effect
apps/pm/node_modules/vitest+1−0
@@ -0,0 +1 @@
1../../../node_modules/.bun/vitest@3.2.4+dddfa60a3fc73abb/node_modules/vitest
apps/pm/package.json+30−0
@@ -0,0 +1,30 @@
1{
2 "name": "@executor-v2/app-pm",
3 "private": true,
4 "type": "module",
5 "scripts": {
6 "dev": "bun --watch src/main.ts",
7 "start": "bun src/main.ts",
8 "test": "bunx vitest run --no-watch src/*.test.ts",
9 "typecheck": "bunx tsc --noEmit -p tsconfig.json"
10 },
11 "dependencies": {
12 "@effect/platform": "catalog:",
13 "@effect/platform-bun": "^0.86.0",
14 "@executor-v2/management-api": "workspace:*",
15 "@executor-v2/domain": "workspace:*",
16 "@executor-v2/engine": "workspace:*",
17 "@executor-v2/mcp-gateway": "workspace:*",
18 "@executor-v2/persistence-local": "workspace:*",
19 "@executor-v2/runtime-cloudflare-worker-loader": "workspace:*",
20 "@executor-v2/runtime-deno-subprocess": "workspace:*",
21 "@executor-v2/runtime-local-inproc": "workspace:*",
22 "@executor-v2/sdk": "workspace:*",
23 "effect": "catalog:"
24 },
25 "devDependencies": {
26 "@effect/vitest": "catalog:",
27 "@modelcontextprotocol/sdk": "^1.26.0",
28 "vitest": "catalog:"
29 }
30}
apps/pm/src/actor.ts+143−0
@@ -0,0 +1,143 @@
1import {
2 ControlPlaneActorResolverLive,
3 deriveWorkspaceMembershipsForPrincipal,
4 requirePrincipalFromHeaders,
5} from "@executor-v2/management-api";
6import {
7 ActorUnauthenticatedError,
8 makeActor,
9 makeAllowAllActor,
10} from "@executor-v2/domain";
11import {
12 type LocalStateSnapshot,
13 type LocalStateStore,
14} from "@executor-v2/persistence-local";
15import {
16 type OrganizationMembership,
17 type WorkspaceMembership,
18} from "@executor-v2/schema";
19import * as PlatformHeaders from "@effect/platform/Headers";
20import * as Effect from "effect/Effect";
21import * as Option from "effect/Option";
22
23const isTruthy = (value: string | undefined): boolean => {
24 const normalized = value?.trim().toLowerCase();
25 return normalized === "1" || normalized === "true" || normalized === "yes";
26};
27
28const localAdminFallbackEnabled = (() => {
29 const configured = process.env.PM_ALLOW_LOCAL_ADMIN;
30
31 if (configured === undefined || configured.trim().length === 0) {
32 return process.env.NODE_ENV !== "production";
33 }
34
35 return isTruthy(configured);
36})();
37
38const organizationMembershipsForAccount = (
39 snapshot: LocalStateSnapshot,
40 accountId: OrganizationMembership["accountId"],
41): ReadonlyArray<OrganizationMembership> =>
42 snapshot.organizationMemberships.filter(
43 (membership) => membership.accountId === accountId,
44 );
45
46const workspaceMembershipsForAccount = (
47 snapshot: LocalStateSnapshot,
48 accountId: OrganizationMembership["accountId"],
49 organizationMemberships: ReadonlyArray<OrganizationMembership>,
50): ReadonlyArray<WorkspaceMembership> =>
51 snapshot.workspaces.flatMap((workspace) =>
52 deriveWorkspaceMembershipsForPrincipal({
53 principalAccountId: accountId,
54 workspaceId: workspace.id,
55 workspace,
56 organizationMemberships,
57 }),
58 );
59
60const resolveActorFromSnapshot = (
61 localStateStore: LocalStateStore,
62 headers: PlatformHeaders.Headers,
63) =>
64 Effect.gen(function* () {
65 const principal = yield* requirePrincipalFromHeaders(headers);
66
67 const snapshotOption = yield* localStateStore.getSnapshot().pipe(
68 Effect.mapError(
69 (error) =>
70 new ActorUnauthenticatedError({
71 message: `Unable to read local auth state (${error.operation})`,
72 }),
73 ),
74 );
75
76 const snapshot = Option.getOrNull(snapshotOption);
77
78 if (snapshot === null && localAdminFallbackEnabled) {
79 return makeAllowAllActor(principal);
80 }
81
82 const organizationMemberships =
83 snapshot === null
84 ? []
85 : organizationMembershipsForAccount(snapshot, principal.accountId);
86 const workspaceMemberships =
87 snapshot === null
88 ? []
89 : workspaceMembershipsForAccount(snapshot, principal.accountId, organizationMemberships);
90
91 return yield* makeActor({
92 principal,
93 workspaceMemberships,
94 organizationMemberships,
95 });
96 });
97
98export const PmActorLive = (localStateStore: LocalStateStore) =>
99 ControlPlaneActorResolverLive({
100 resolveActor: (input) => resolveActorFromSnapshot(localStateStore, input.headers),
101 resolveWorkspaceActor: (input) =>
102 Effect.gen(function* () {
103 const principal = yield* requirePrincipalFromHeaders(input.headers);
104
105 const snapshotOption = yield* localStateStore.getSnapshot().pipe(
106 Effect.mapError(
107 (error) =>
108 new ActorUnauthenticatedError({
109 message: `Unable to read local auth state (${error.operation})`,
110 }),
111 ),
112 );
113
114 const snapshot = Option.getOrNull(snapshotOption);
115
116 if (snapshot === null && localAdminFallbackEnabled) {
117 return makeAllowAllActor(principal);
118 }
119
120 const organizationMemberships =
121 snapshot === null
122 ? []
123 : organizationMembershipsForAccount(snapshot, principal.accountId);
124
125 const workspace =
126 snapshot === null
127 ? null
128 : snapshot.workspaces.find((item) => item.id === input.workspaceId) ?? null;
129
130 const workspaceMemberships = deriveWorkspaceMembershipsForPrincipal({
131 principalAccountId: principal.accountId,
132 workspaceId: input.workspaceId,
133 workspace,
134 organizationMemberships,
135 });
136
137 return yield* makeActor({
138 principal,
139 workspaceMemberships,
140 organizationMemberships,
141 });
142 }),
143 });
apps/pm/src/approvals-service.ts+264−0
@@ -0,0 +1,264 @@
1import {
2 PersistentToolApprovalPolicyStoreError,
3 createPersistentToolApprovalPolicy,
4 type PersistentToolApprovalRecord,
5 type PersistentToolApprovalStore,
6 type ToolApprovalPolicy,
7} from "@executor-v2/engine";
8import { SourceStoreError } from "@executor-v2/persistence-ports";
9import {
10 type LocalStateSnapshot,
11 type LocalStateStore,
12 type LocalStateStoreError,
13} from "@executor-v2/persistence-local";
14import {
15 makeControlPlaneApprovalsService,
16 type ControlPlaneApprovalsServiceShape,
17} from "@executor-v2/management-api";
18import { type Approval } from "@executor-v2/schema";
19import * as Effect from "effect/Effect";
20import * as Option from "effect/Option";
21
22const toSourceStoreError = (
23 operation: string,
24 message: string,
25 details: string | null,
26): SourceStoreError =>
27 new SourceStoreError({
28 operation,
29 backend: "local-file",
30 location: "snapshot.json",
31 message,
32 reason: null,
33 details,
34 });
35
36const toSourceStoreErrorFromLocalState = (
37 operation: string,
38 error: LocalStateStoreError,
39): SourceStoreError =>
40 toSourceStoreError(operation, error.message, error.details ?? error.reason ?? null);
41
42const findApprovalIndex = (
43 approvals: ReadonlyArray<Approval>,
44 workspaceId: string,
45 approvalId: string,
46): number =>
47 approvals.findIndex(
48 (approval) => approval.workspaceId === workspaceId && approval.id === approvalId,
49 );
50
51const sortApprovals = (approvals: ReadonlyArray<Approval>): Array<Approval> =>
52 [...approvals].sort((left, right) => right.requestedAt - left.requestedAt);
53
54const toPersistentApprovalStoreError = (
55 operation: string,
56 message: string,
57 details: string | null,
58): PersistentToolApprovalPolicyStoreError =>
59 new PersistentToolApprovalPolicyStoreError({
60 operation,
61 message,
62 details,
63 });
64
65const toPersistentApprovalStoreErrorFromLocalState = (
66 operation: string,
67 error: LocalStateStoreError,
68): PersistentToolApprovalPolicyStoreError =>
69 toPersistentApprovalStoreError(operation, error.message, error.details ?? error.reason ?? null);
70
71const toPersistentApprovalRecord = (approval: Approval): PersistentToolApprovalRecord => ({
72 approvalId: approval.id,
73 workspaceId: approval.workspaceId,
74 runId: approval.taskRunId,
75 callId: approval.callId,
76 toolPath: approval.toolPath,
77 status: approval.status,
78 reason: approval.reason,
79});
80
81const updateApproval = (
82 snapshot: LocalStateSnapshot,
83 index: number,
84 nextApproval: Approval,
85): LocalStateSnapshot => {
86 const approvals = [...snapshot.approvals];
87 approvals[index] = nextApproval;
88
89 return {
90 ...snapshot,
91 generatedAt: Date.now(),
92 approvals,
93 };
94};
95
96export type PmPersistentToolApprovalPolicyOptions = {
97 requireApprovals?: boolean;
98 retryAfterMs?: number;
99};
100
101export const createPmPersistentToolApprovalPolicy = (
102 localStateStore: LocalStateStore,
103 options: PmPersistentToolApprovalPolicyOptions = {},
104): ToolApprovalPolicy => {
105 const missingSnapshotError = (operation: string): PersistentToolApprovalPolicyStoreError =>
106 toPersistentApprovalStoreError(
107 operation,
108 "Persistent approvals require an initialized local state snapshot",
109 null,
110 );
111
112 const store: PersistentToolApprovalStore = {
113 findByRunAndCall: (input) =>
114 localStateStore.getSnapshot().pipe(
115 Effect.mapError((error) =>
116 toPersistentApprovalStoreErrorFromLocalState("approvals.read", error),
117 ),
118 Effect.flatMap((snapshotOption) => {
119 const snapshot = Option.getOrNull(snapshotOption);
120 if (snapshot === null) {
121 return Effect.fail(missingSnapshotError("approvals.read"));
122 }
123
124 const approval =
125 snapshot.approvals.find(
126 (candidate) =>
127 candidate.workspaceId === input.workspaceId &&
128 candidate.taskRunId === input.runId &&
129 candidate.callId === input.callId,
130 ) ?? null;
131
132 return Effect.succeed(approval ? toPersistentApprovalRecord(approval) : null);
133 }),
134 ),
135
136 createPending: (input) =>
137 localStateStore.getSnapshot().pipe(
138 Effect.mapError((error) =>
139 toPersistentApprovalStoreErrorFromLocalState("approvals.read", error),
140 ),
141 Effect.flatMap((snapshotOption) => {
142 const snapshot = Option.getOrNull(snapshotOption);
143 if (snapshot === null) {
144 return Effect.fail(missingSnapshotError("approvals.create"));
145 }
146
147 const pendingApproval = {
148 id: `apr_${crypto.randomUUID()}`,
149 workspaceId: input.workspaceId,
150 taskRunId: input.runId,
151 callId: input.callId,
152 toolPath: input.toolPath,
153 status: "pending",
154 inputPreviewJson: input.inputPreviewJson,
155 reason: null,
156 requestedAt: Date.now(),
157 resolvedAt: null,
158 } as Approval;
159
160 const nextSnapshot: LocalStateSnapshot = {
161 ...snapshot,
162 generatedAt: Date.now(),
163 approvals: [...snapshot.approvals, pendingApproval],
164 };
165
166 return localStateStore.writeSnapshot(nextSnapshot).pipe(
167 Effect.mapError((error) =>
168 toPersistentApprovalStoreErrorFromLocalState("approvals.write", error),
169 ),
170 Effect.as(toPersistentApprovalRecord(pendingApproval)),
171 );
172 }),
173 ),
174 };
175
176 return createPersistentToolApprovalPolicy({
177 store,
178 requireApprovals: options.requireApprovals,
179 retryAfterMs: options.retryAfterMs,
180 });
181};
182
183export const createPmApprovalsService = (
184 localStateStore: LocalStateStore,
185): ControlPlaneApprovalsServiceShape =>
186 makeControlPlaneApprovalsService({
187 listApprovals: (workspaceId) =>
188 Effect.gen(function* () {
189 const snapshotOption = yield* localStateStore.getSnapshot().pipe(
190 Effect.mapError((error) =>
191 toSourceStoreErrorFromLocalState("approvals.list", error),
192 ),
193 );
194
195 const snapshot = Option.getOrNull(snapshotOption);
196 if (snapshot === null) {
197 return [];
198 }
199
200 const approvals = snapshot.approvals.filter(
201 (approval) => approval.workspaceId === workspaceId,
202 );
203
204 return sortApprovals(approvals);
205 }),
206
207 resolveApproval: (input) =>
208 Effect.gen(function* () {
209 const snapshotOption = yield* localStateStore.getSnapshot().pipe(
210 Effect.mapError((error) =>
211 toSourceStoreErrorFromLocalState("approvals.resolve", error),
212 ),
213 );
214
215 const snapshot = Option.getOrNull(snapshotOption);
216 if (snapshot === null) {
217 return yield* toSourceStoreError(
218 "approvals.resolve",
219 "Approval snapshot not found",
220 `workspace=${input.workspaceId} approval=${input.approvalId}`,
221 );
222 }
223
224 const index = findApprovalIndex(
225 snapshot.approvals,
226 input.workspaceId,
227 input.approvalId,
228 );
229
230 if (index < 0) {
231 return yield* toSourceStoreError(
232 "approvals.resolve",
233 "Approval not found",
234 `workspace=${input.workspaceId} approval=${input.approvalId}`,
235 );
236 }
237
238 const approval = snapshot.approvals[index];
239 if (approval.status !== "pending") {
240 return yield* toSourceStoreError(
241 "approvals.resolve",
242 "Approval is not pending",
243 `approval=${input.approvalId} status=${approval.status}`,
244 );
245 }
246
247 const resolvedApproval: Approval = {
248 ...approval,
249 status: input.payload.status,
250 reason: input.payload.reason ?? approval.reason ?? null,
251 resolvedAt: Date.now(),
252 };
253
254 const nextSnapshot = updateApproval(snapshot, index, resolvedApproval);
255
256 yield* localStateStore.writeSnapshot(nextSnapshot).pipe(
257 Effect.mapError((error) =>
258 toSourceStoreErrorFromLocalState("approvals.resolve_write", error),
259 ),
260 );
261
262 return resolvedApproval;
263 }),
264 });
apps/pm/src/config.ts+26−0
@@ -0,0 +1,26 @@
1import * as Config from "effect/Config";
2import * as Context from "effect/Context";
3import * as Effect from "effect/Effect";
4import * as Layer from "effect/Layer";
5
6export type PmConfigService = {
7 port: number;
8};
9
10export class PmConfig extends Context.Tag("@executor-v2/app-pm/PmConfig")<
11 PmConfig,
12 PmConfigService
13>() {}
14
15export const PmConfigLive = Layer.effect(
16 PmConfig,
17 Effect.gen(function* () {
18 const port = yield* Config.integer("PORT").pipe(
19 Config.orElse(() => Config.succeed(8788)),
20 );
21
22 return PmConfig.of({
23 port,
24 });
25 }),
26);
apps/pm/src/credential-resolver.ts+78−0
@@ -0,0 +1,78 @@
1import {
2 buildCredentialHeaders,
3 CredentialResolverError,
4 extractCredentialResolutionContext,
5 makeCredentialResolver,
6 selectCredentialBinding,
7 selectOAuthAccessToken,
8 sourceIdFromSourceKey,
9 type ResolveToolCredentials,
10} from "@executor-v2/engine";
11import { type LocalStateStore } from "@executor-v2/persistence-local";
12import * as Effect from "effect/Effect";
13import * as Option from "effect/Option";
14
15const toCredentialResolverError = (
16 operation: string,
17 message: string,
18 details: string | null,
19): CredentialResolverError =>
20 new CredentialResolverError({
21 operation,
22 message,
23 details,
24 });
25
26export const createPmResolveToolCredentials = (
27 localStateStore: LocalStateStore,
28): ResolveToolCredentials =>
29 makeCredentialResolver((input) =>
30 Effect.gen(function* () {
31 const context = extractCredentialResolutionContext(input);
32 if (context === null) {
33 return {
34 headers: {},
35 };
36 }
37
38 const snapshotOption = yield* localStateStore.getSnapshot().pipe(
39 Effect.mapError((error) =>
40 toCredentialResolverError(
41 "read_local_state_snapshot",
42 "Failed reading local snapshot while resolving credentials",
43 error.details ?? error.message,
44 ),
45 ),
46 );
47
48 const snapshot = Option.getOrNull(snapshotOption);
49 if (snapshot === null) {
50 return {
51 headers: {},
52 };
53 }
54
55 const binding = selectCredentialBinding(
56 snapshot.credentialBindings,
57 context,
58 );
59 if (binding === null) {
60 return {
61 headers: {},
62 };
63 }
64
65 const sourceId = sourceIdFromSourceKey(context.sourceKey);
66
67 const oauthAccessToken =
68 binding.provider === "oauth2" && sourceId
69 ? selectOAuthAccessToken(snapshot.oauthTokens, context, sourceId)
70 : null;
71
72 return {
73 headers: buildCredentialHeaders(binding, {
74 oauthAccessToken,
75 }),
76 };
77 }),
78 );
apps/pm/src/credentials-service.ts+263−0
@@ -0,0 +1,263 @@
1import { SourceStoreError } from "@executor-v2/persistence-ports";
2import {
3 type LocalStateSnapshot,
4 type LocalStateStore,
5 type LocalStateStoreError,
6} from "@executor-v2/persistence-local";
7import {
8 makeControlPlaneCredentialsService,
9 type ControlPlaneCredentialsServiceShape,
10} from "@executor-v2/management-api";
11import {
12 type OrganizationId,
13 type SourceCredentialBinding,
14 type WorkspaceId,
15} from "@executor-v2/schema";
16import * as Effect from "effect/Effect";
17import * as Option from "effect/Option";
18
19const toSourceStoreError = (
20 operation: string,
21 message: string,
22 details: string | null,
23): SourceStoreError =>
24 new SourceStoreError({
25 operation,
26 backend: "local-file",
27 location: "snapshot.json",
28 message,
29 reason: null,
30 details,
31 });
32
33const toSourceStoreErrorFromLocalState = (
34 operation: string,
35 error: LocalStateStoreError,
36): SourceStoreError =>
37 toSourceStoreError(operation, error.message, error.details ?? error.reason ?? null);
38
39const resolveWorkspaceOrganizationId = (
40 snapshot: LocalStateSnapshot,
41 workspaceId: WorkspaceId,
42): OrganizationId => {
43 const workspace = snapshot.workspaces.find((item) => item.id === workspaceId);
44
45 if (!workspace) {
46 throw new Error(`Workspace not found: ${workspaceId}`);
47 }
48
49 return workspace.organizationId;
50};
51
52const sortCredentialBindings = (
53 bindings: ReadonlyArray<SourceCredentialBinding>,
54): Array<SourceCredentialBinding> =>
55 [...bindings].sort((left, right) => {
56 const leftKey = `${left.sourceKey}:${left.provider}:${left.id}`.toLowerCase();
57 const rightKey = `${right.sourceKey}:${right.provider}:${right.id}`.toLowerCase();
58 return leftKey.localeCompare(rightKey);
59 });
60
61const replaceCredentialBindingAt = (
62 snapshot: LocalStateSnapshot,
63 index: number,
64 binding: SourceCredentialBinding,
65): LocalStateSnapshot => {
66 const next = [...snapshot.credentialBindings];
67 next[index] = binding;
68
69 return {
70 ...snapshot,
71 generatedAt: Date.now(),
72 credentialBindings: next,
73 };
74};
75
76const appendCredentialBinding = (
77 snapshot: LocalStateSnapshot,
78 binding: SourceCredentialBinding,
79): LocalStateSnapshot => ({
80 ...snapshot,
81 generatedAt: Date.now(),
82 credentialBindings: [...snapshot.credentialBindings, binding],
83});
84
85const removeCredentialBindingForWorkspace = (
86 snapshot: LocalStateSnapshot,
87 workspaceId: WorkspaceId,
88 credentialBindingId: string,
89): { snapshot: LocalStateSnapshot; removed: boolean } => {
90 const organizationId = resolveWorkspaceOrganizationId(snapshot, workspaceId);
91 const removeIndex = snapshot.credentialBindings.findIndex(
92 (binding) =>
93 binding.id === credentialBindingId
94 && (
95 binding.workspaceId === workspaceId
96 || (binding.workspaceId === null && binding.organizationId === organizationId)
97 ),
98 );
99
100 if (removeIndex < 0) {
101 return {
102 snapshot,
103 removed: false,
104 };
105 }
106
107 const next = [...snapshot.credentialBindings];
108 next.splice(removeIndex, 1);
109
110 return {
111 removed: true,
112 snapshot: {
113 ...snapshot,
114 generatedAt: Date.now(),
115 credentialBindings: next,
116 },
117 };
118};
119
120export const createPmCredentialsService = (
121 localStateStore: LocalStateStore,
122): ControlPlaneCredentialsServiceShape =>
123 makeControlPlaneCredentialsService({
124 listCredentialBindings: (workspaceId) =>
125 Effect.gen(function* () {
126 const snapshotOption = yield* localStateStore.getSnapshot().pipe(
127 Effect.mapError((error) =>
128 toSourceStoreErrorFromLocalState("credentials.list", error),
129 ),
130 );
131
132 const snapshot = Option.getOrNull(snapshotOption);
133 if (snapshot === null) {
134 return [];
135 }
136
137 const organizationId = resolveWorkspaceOrganizationId(snapshot, workspaceId);
138
139 return sortCredentialBindings(
140 snapshot.credentialBindings.filter(
141 (binding) =>
142 binding.workspaceId === workspaceId
143 || (binding.workspaceId === null && binding.organizationId === organizationId),
144 ),
145 );
146 }),
147
148 upsertCredentialBinding: (input) =>
149 Effect.gen(function* () {
150 const snapshotOption = yield* localStateStore.getSnapshot().pipe(
151 Effect.mapError((error) =>
152 toSourceStoreErrorFromLocalState("credentials.upsert", error),
153 ),
154 );
155
156 const snapshot = Option.getOrNull(snapshotOption);
157 if (snapshot === null) {
158 return yield* toSourceStoreError(
159 "credentials.upsert",
160 "Credential snapshot not found",
161 `workspace=${input.workspaceId}`,
162 );
163 }
164
165 if (input.payload.scopeType === "account" && input.payload.accountId === null) {
166 return yield* toSourceStoreError(
167 "credentials.upsert",
168 "Account scope credentials require accountId",
169 `workspace=${input.workspaceId}`,
170 );
171 }
172
173 const now = Date.now();
174 const requestedId = input.payload.id;
175
176 const existingIndex = requestedId
177 ? snapshot.credentialBindings.findIndex(
178 (binding) =>
179 binding.workspaceId === input.workspaceId && binding.id === requestedId,
180 )
181 : -1;
182
183 const existing = existingIndex >= 0 ? snapshot.credentialBindings[existingIndex] : null;
184 const organizationId = resolveWorkspaceOrganizationId(snapshot, input.workspaceId);
185
186 const nextBinding: SourceCredentialBinding = {
187 id:
188 existing?.id
189 ?? (requestedId
190 ?? (`credential_binding_${crypto.randomUUID()}` as SourceCredentialBinding["id"])),
191 credentialId: input.payload.credentialId,
192 organizationId,
193 workspaceId:
194 input.payload.scopeType === "workspace" ? input.workspaceId : null,
195 accountId:
196 input.payload.scopeType === "account"
197 ? (input.payload.accountId ?? null)
198 : null,
199 scopeType: input.payload.scopeType,
200 sourceKey: input.payload.sourceKey,
201 provider: input.payload.provider,
202 secretProvider:
203 input.payload.secretProvider
204 ?? existing?.secretProvider
205 ?? "local",
206 secretRef: input.payload.secretRef,
207 additionalHeadersJson: input.payload.additionalHeadersJson ?? null,
208 boundAuthFingerprint: input.payload.boundAuthFingerprint ?? null,
209 createdAt: existing?.createdAt ?? now,
210 updatedAt: now,
211 };
212
213 const nextSnapshot = existingIndex >= 0
214 ? replaceCredentialBindingAt(snapshot, existingIndex, nextBinding)
215 : appendCredentialBinding(snapshot, nextBinding);
216
217 yield* localStateStore.writeSnapshot(nextSnapshot).pipe(
218 Effect.mapError((error) =>
219 toSourceStoreErrorFromLocalState("credentials.upsert_write", error),
220 ),
221 );
222
223 return nextBinding;
224 }),
225
226 removeCredentialBinding: (input) =>
227 Effect.gen(function* () {
228 const snapshotOption = yield* localStateStore.getSnapshot().pipe(
229 Effect.mapError((error) =>
230 toSourceStoreErrorFromLocalState("credentials.remove", error),
231 ),
232 );
233
234 const snapshot = Option.getOrNull(snapshotOption);
235 if (snapshot === null) {
236 return {
237 removed: false,
238 };
239 }
240
241 const next = removeCredentialBindingForWorkspace(
242 snapshot,
243 input.workspaceId,
244 input.credentialBindingId,
245 );
246
247 if (!next.removed) {
248 return {
249 removed: false,
250 };
251 }
252
253 yield* localStateStore.writeSnapshot(next.snapshot).pipe(
254 Effect.mapError((error) =>
255 toSourceStoreErrorFromLocalState("credentials.remove_write", error),
256 ),
257 );
258
259 return {
260 removed: true,
261 };
262 }),
263 });
apps/pm/src/execute.e2e.test.ts+167−0
@@ -0,0 +1,167 @@
1import { spawn } from "node:child_process";
2import { createServer } from "node:net";
3import { Client } from "@modelcontextprotocol/sdk/client/index.js";
4import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
5import { describe, expect, it } from "@effect/vitest";
6import * as Data from "effect/Data";
7import * as Effect from "effect/Effect";
8
9const pmAppDir = new URL("..", import.meta.url).pathname;
10
11type McpCallToolResult = {
12 isError?: boolean;
13 content?: Array<{ type?: string; text?: string }>;
14};
15
16class ExecuteE2eError extends Data.TaggedError("ExecuteE2eError")<{
17 message: string;
18 details: string | null;
19}> {}
20
21const toExecuteE2eError = (message: string, cause: unknown): ExecuteE2eError =>
22 new ExecuteE2eError({
23 message,
24 details: cause instanceof Error ? cause.message : String(cause),
25 });
26
27const findFreePort = Effect.async<number, ExecuteE2eError, never>((resume) => {
28 const server = createServer();
29
30 server.once("error", (cause) => {
31 resume(Effect.fail(toExecuteE2eError("Failed to allocate free TCP port", cause)));
32 });
33
34 server.listen(0, "127.0.0.1", () => {
35 const address = server.address();
36 const port = typeof address === "object" && address ? address.port : null;
37
38 server.close((cause) => {
39 if (cause) {
40 resume(Effect.fail(toExecuteE2eError("Failed closing port probe server", cause)));
41 return;
42 }
43
44 if (!port) {
45 resume(
46 Effect.fail(
47 new ExecuteE2eError({
48 message: "Failed to allocate free TCP port",
49 details: "No port returned from node:net server",
50 }),
51 ),
52 );
53 return;
54 }
55
56 resume(Effect.succeed(port));
57 });
58 });
59});
60
61const waitForHealth = (port: number) =>
62 Effect.gen(function* () {
63 for (let attempt = 0; attempt < 80; attempt += 1) {
64 const healthy = yield* Effect.tryPromise({
65 try: async () => {
66 const signal = AbortSignal.timeout(250);
67 const response = await fetch(`http://127.0.0.1:${port}/healthz`, { signal });
68 return response.status === 200;
69 },
70 catch: (cause) =>
71 toExecuteE2eError("Failed polling PM health endpoint", cause),
72 }).pipe(Effect.catchAll(() => Effect.succeed(false)));
73
74 if (healthy) {
75 return;
76 }
77
78 yield* Effect.sleep("100 millis");
79 }
80
81 return yield* new ExecuteE2eError({
82 message: "PM server did not become healthy in time",
83 details: `http://127.0.0.1:${port}/healthz`,
84 });
85 });
86
87const withPmProcess = (port: number) =>
88 Effect.acquireRelease(
89 Effect.sync(() =>
90 spawn("bun", ["src/main.ts"], {
91 cwd: pmAppDir,
92 env: {
93 ...process.env,
94 PORT: String(port),
95 },
96 stdio: "pipe",
97 }),
98 ),
99 (child) =>
100 Effect.sync(() => {
101 if (!child.killed) {
102 child.kill("SIGTERM");
103 }
104 }),
105 );
106
107const withMcpClient = (port: number) =>
108 Effect.acquireRelease(
109 Effect.tryPromise({
110 try: async () => {
111 const transport = new StreamableHTTPClientTransport(
112 new URL(`http://127.0.0.1:${port}/v1/mcp`),
113 );
114 const client = new Client(
115 { name: "executor-v2-pm-e2e", version: "0.0.0" },
116 { capabilities: {} },
117 );
118
119 await client.connect(transport);
120 return { client, transport };
121 },
122 catch: (cause) =>
123 toExecuteE2eError("Failed to initialize MCP client transport", cause),
124 }),
125 ({ client, transport }) =>
126 Effect.tryPromise({
127 try: async () => {
128 await transport.close().catch(() => undefined);
129 await client.close().catch(() => undefined);
130 },
131 catch: (cause) =>
132 toExecuteE2eError("Failed closing MCP client transport", cause),
133 }).pipe(Effect.orDie),
134 );
135
136describe("PM execute E2E", () => {
137 it.live(
138 "runs executor.execute code through MCP",
139 () =>
140 Effect.scoped(
141 Effect.gen(function* () {
142 const port = yield* findFreePort;
143 yield* withPmProcess(port);
144 yield* waitForHealth(port);
145
146 const { client } = yield* withMcpClient(port);
147
148 const result = (yield* Effect.tryPromise({
149 try: () =>
150 client.callTool({
151 name: "executor.execute",
152 arguments: {
153 code: "return 2 + 3;",
154 },
155 }),
156 catch: (cause) =>
157 toExecuteE2eError("Failed calling executor.execute over MCP", cause),
158 })) as McpCallToolResult;
159
160 expect(result.isError).toBe(false);
161 const textPart = result.content?.find((part) => part.type === "text");
162 expect(textPart?.text).toBe("5");
163 }),
164 ),
165 30_000,
166 );
167});
apps/pm/src/http-server.ts+92−0
@@ -0,0 +1,92 @@
1import { controlPlaneOpenApiSpec } from "@executor-v2/management-api";
2
3export type StartPmHttpServerOptions = {
4 port: number;
5 handleMcp: (request: Request) => Promise<Response>;
6 handleToolCall: (request: Request) => Promise<Response>;
7 handleControlPlane: (request: Request) => Promise<Response>;
8};
9
10export type PmHttpServer = {
11 stop: () => void;
12};
13
14const methodNotAllowed = (allowed: string): Response =>
15 Response.json(
16 {
17 ok: false,
18 error: `Method not allowed. Expected ${allowed}`,
19 },
20 { status: 405 },
21 );
22
23const notFound = (): Response =>
24 Response.json(
25 {
26 ok: false,
27 error: "Not found",
28 },
29 { status: 404 },
30 );
31
32const isControlPlaneMethod = (method: string): boolean =>
33 method === "GET" ||
34 method === "POST" ||
35 method === "PUT" ||
36 method === "PATCH" ||
37 method === "DELETE" ||
38 method === "OPTIONS";
39
40export const startPmHttpServer = (options: StartPmHttpServerOptions): PmHttpServer => {
41 const server = Bun.serve({
42 port: options.port,
43 hostname: "127.0.0.1",
44 fetch: async (request) => {
45 const { pathname } = new URL(request.url);
46
47 if (pathname === "/healthz") {
48 return Response.json({ ok: true, service: "pm" });
49 }
50
51 if (pathname === "/v1/mcp") {
52 if (
53 request.method !== "GET" &&
54 request.method !== "POST" &&
55 request.method !== "DELETE"
56 ) {
57 return methodNotAllowed("GET, POST, DELETE");
58 }
59
60 return options.handleMcp(request);
61 }
62
63 if (pathname === "/v1/runtime/tool-call") {
64 if (request.method !== "POST") {
65 return methodNotAllowed("POST");
66 }
67
68 return options.handleToolCall(request);
69 }
70
71 if (pathname === "/v1/openapi.json") {
72 if (request.method !== "GET") {
73 return methodNotAllowed("GET");
74 }
75
76 return Response.json(controlPlaneOpenApiSpec);
77 }
78
79 if (pathname.startsWith("/v1/") && isControlPlaneMethod(request.method)) {
80 return options.handleControlPlane(request);
81 }
82
83 return notFound();
84 },
85 });
86
87 return {
88 stop: () => {
89 server.stop(true);
90 },
91 };
92};
apps/pm/src/main.ts+239−0
@@ -0,0 +1,239 @@
1import * as BunContext from "@effect/platform-bun/BunContext";
2import {
3 ControlPlaneService,
4 makeControlPlaneService,
5 makeControlPlaneSourcesService,
6 fetchOpenApiDocument,
7 makeControlPlaneWebHandler,
8 makeSourceCatalogService,
9 makeSourceManagerService,
10} from "@executor-v2/management-api";
11import {
12 RuntimeAdapterError,
13 makeGraphqlToolProvider,
14 makeMcpToolProvider,
15 createRunExecutor,
16 createSourceToolRegistry,
17 defaultExecuteToolExposureMode,
18 invokeRuntimeToolCallResult,
19 makeOpenApiToolProvider,
20 makeRuntimeAdapterRegistry,
21 makeToolProviderRegistry,
22 parseExecuteToolExposureMode,
23} from "@executor-v2/engine";
24import {
25 makeLocalSourceStore,
26 makeLocalStateStore,
27 makeLocalToolArtifactStore,
28} from "@executor-v2/persistence-local";
29import { type RuntimeToolCallResult } from "@executor-v2/sdk";
30import { makeCloudflareWorkerLoaderRuntimeAdapter } from "@executor-v2/runtime-cloudflare-worker-loader";
31import { makeDenoSubprocessRuntimeAdapter } from "@executor-v2/runtime-deno-subprocess";
32import { makeLocalInProcessRuntimeAdapter } from "@executor-v2/runtime-local-inproc";
33import * as Effect from "effect/Effect";
34import * as Layer from "effect/Layer";
35
36import { PmActorLive } from "./actor";
37import {
38 createPmApprovalsService,
39 createPmPersistentToolApprovalPolicy,
40} from "./approvals-service";
41import { startPmHttpServer } from "./http-server";
42import { createPmPoliciesService } from "./policies-service";
43import { createPmCredentialsService } from "./credentials-service";
44import { createPmOrganizationsService } from "./organizations-service";
45import { createPmStorageService } from "./storage-service";
46import { createPmToolsService } from "./tools-service";
47import { createPmWorkspacesService } from "./workspaces-service";
48import { createPmMcpHandler } from "./mcp-handler";
49import { createPmExecuteRuntimeRun } from "./runtime-execution-port";
50import { createPmToolCallHttpHandler } from "./tool-call-handler";
51
52const pmStateRootDir = process.env.PM_STATE_ROOT_DIR ?? ".executor-v2/pm-state";
53
54const parsePort = (value: string | undefined): number => {
55 const parsed = Number.parseInt(value ?? "", 10);
56 return Number.isFinite(parsed) && parsed > 0 ? parsed : 8787;
57};
58
59const readConfiguredRuntimeKind = (value: string | undefined): string | undefined => {
60 if (!value) {
61 return undefined;
62 }
63
64 const normalized = value.trim();
65 return normalized.length > 0 ? normalized : undefined;
66};
67
68const readConfiguredWorkspaceId = (value: string | undefined): string => {
69 const normalized = value?.trim();
70 return normalized && normalized.length > 0 ? normalized : "ws_local";
71};
72
73const readBooleanFlag = (value: string | undefined): boolean => {
74 const normalized = value?.trim().toLowerCase();
75 return normalized === "1" || normalized === "true" || normalized === "yes";
76};
77
78const readConfiguredToolExposureMode = (
79 value: string | undefined,
80): "all_tools" | "sources_only" =>
81 parseExecuteToolExposureMode(value ?? undefined) ??
82 defaultExecuteToolExposureMode;
83
84const formatRuntimeAdapterError = (error: RuntimeAdapterError): string =>
85 error.details ? `${error.message}: ${error.details}` : error.message;
86
87const port = parsePort(process.env.PORT);
88const workspaceId = readConfiguredWorkspaceId(process.env.PM_WORKSPACE_ID);
89const requireToolApprovals = readBooleanFlag(process.env.PM_REQUIRE_TOOL_APPROVALS);
90const defaultToolExposureMode = readConfiguredToolExposureMode(
91 process.env.PM_TOOL_EXPOSURE_MODE,
92);
93
94const pmRuntimeAdapters = [
95 makeLocalInProcessRuntimeAdapter(),
96 makeDenoSubprocessRuntimeAdapter(),
97 makeCloudflareWorkerLoaderRuntimeAdapter(),
98];
99
100const runtimeAdapters = makeRuntimeAdapterRegistry(pmRuntimeAdapters);
101const defaultRuntimeKind =
102 readConfiguredRuntimeKind(process.env.PM_RUNTIME_KIND) ?? pmRuntimeAdapters[0].kind;
103
104const sourceStore = await Effect.runPromise(
105 makeLocalSourceStore({
106 rootDir: pmStateRootDir,
107 }).pipe(Effect.provide(BunContext.layer)),
108);
109
110const localStateStore = await Effect.runPromise(
111 makeLocalStateStore({
112 rootDir: pmStateRootDir,
113 }).pipe(Effect.provide(BunContext.layer)),
114);
115
116const toolArtifactStore = await Effect.runPromise(
117 makeLocalToolArtifactStore({
118 rootDir: pmStateRootDir,
119 }).pipe(Effect.provide(BunContext.layer)),
120);
121
122const sourceCatalog = makeSourceCatalogService(sourceStore);
123const sourceManager = makeSourceManagerService(toolArtifactStore);
124const baseSourcesService = makeControlPlaneSourcesService(sourceCatalog);
125const sourcesService = {
126 ...baseSourcesService,
127 upsertSource: (input: Parameters<typeof baseSourcesService.upsertSource>[0]) =>
128 Effect.gen(function* () {
129 const source = yield* baseSourcesService.upsertSource(input);
130
131 if (source.kind !== "openapi") {
132 return source;
133 }
134
135 const openApiSpecResult = yield* Effect.tryPromise({
136 try: () => fetchOpenApiDocument(source.endpoint),
137 catch: (cause) => String(cause),
138 }).pipe(Effect.either);
139
140 if (openApiSpecResult._tag === "Left") {
141 return source;
142 }
143
144 yield* sourceManager
145 .refreshOpenApiArtifact({
146 source,
147 openApiSpec: openApiSpecResult.right,
148 })
149 .pipe(Effect.ignore);
150
151 return source;
152 }),
153};
154
155const credentialsService = createPmCredentialsService(localStateStore);
156const policiesService = createPmPoliciesService(localStateStore);
157const organizationsService = createPmOrganizationsService(localStateStore);
158const workspacesService = createPmWorkspacesService(localStateStore);
159const toolsService = createPmToolsService(sourceStore, toolArtifactStore);
160const storageService = createPmStorageService(localStateStore, {
161 stateRootDir: pmStateRootDir,
162});
163const approvalsService = createPmApprovalsService(localStateStore);
164const controlPlaneService = makeControlPlaneService({
165 sources: sourcesService,
166 credentials: credentialsService,
167 policies: policiesService,
168 organizations: organizationsService,
169 workspaces: workspacesService,
170 tools: toolsService,
171 storage: storageService,
172 approvals: approvalsService,
173});
174
175const controlPlaneWebHandler = makeControlPlaneWebHandler(
176 Layer.succeed(ControlPlaneService, controlPlaneService),
177 PmActorLive(localStateStore),
178);
179
180const toolProviderRegistry = makeToolProviderRegistry([
181 makeOpenApiToolProvider(),
182 makeMcpToolProvider(),
183 makeGraphqlToolProvider(),
184]);
185const persistentApprovalPolicy = createPmPersistentToolApprovalPolicy(localStateStore, {
186 requireApprovals: requireToolApprovals,
187});
188const toolRegistry = createSourceToolRegistry({
189 workspaceId,
190 sourceStore,
191 toolArtifactStore,
192 toolProviderRegistry,
193 approvalPolicy: persistentApprovalPolicy,
194});
195const executeRuntimeRun = createPmExecuteRuntimeRun({
196 defaultRuntimeKind,
197 runtimeAdapters,
198 toolRegistry,
199});
200
201const runExecutor = createRunExecutor(executeRuntimeRun);
202const handleMcp = createPmMcpHandler(runExecutor.executeRun, {
203 toolRegistry,
204 defaultToolExposureMode,
205});
206
207const handleToolCallHttp = createPmToolCallHttpHandler((input) =>
208 Effect.runPromise(
209 invokeRuntimeToolCallResult(toolRegistry, input).pipe(
210 Effect.catchTag("RuntimeAdapterError", (error) =>
211 Effect.succeed<RuntimeToolCallResult>({
212 ok: false,
213 kind: "failed",
214 error: formatRuntimeAdapterError(error),
215 }),
216 ),
217 ),
218 ),
219);
220
221const server = startPmHttpServer({
222 port,
223 handleMcp,
224 handleToolCall: handleToolCallHttp,
225 handleControlPlane: controlPlaneWebHandler.handler,
226});
227
228const shutdown = async () => {
229 server.stop();
230 await controlPlaneWebHandler.dispose();
231};
232
233process.on("SIGINT", () => {
234 void shutdown().finally(() => process.exit(0));
235});
236
237process.on("SIGTERM", () => {
238 void shutdown().finally(() => process.exit(0));
239});
apps/pm/src/mcp-handler.ts+76−0
@@ -0,0 +1,76 @@
1import {
2 buildExecuteToolDescription,
3 defaultExecuteToolDescription,
4 defaultExecuteToolExposureMode,
5 parseExecuteToolExposureMode,
6 type ExecuteToolExposureMode,
7 type ToolRegistry,
8} from "@executor-v2/engine";
9import {
10 type ExecuteRunInput,
11 type ExecuteRunResult,
12 createExecutorRunClient,
13} from "@executor-v2/sdk";
14import { handleMcpHttpRequest } from "@executor-v2/mcp-gateway";
15import * as Effect from "effect/Effect";
16
17export type PmMcpHandlerOptions = {
18 toolRegistry: ToolRegistry;
19 defaultToolExposureMode?: ExecuteToolExposureMode;
20};
21
22const readToolExposureModeFromRequest = (
23 request: Request,
24 fallback: ExecuteToolExposureMode,
25): ExecuteToolExposureMode => {
26 const url = new URL(request.url);
27 const rawMode =
28 url.searchParams.get("toolExposureMode") ??
29 url.searchParams.get("toolContextMode") ??
30 undefined;
31
32 return parseExecuteToolExposureMode(rawMode ?? undefined) ?? fallback;
33};
34
35const resolveExecuteToolDescription = async (
36 toolRegistry: ToolRegistry,
37 mode: ExecuteToolExposureMode,
38): Promise<string> => {
39 try {
40 return await Effect.runPromise(
41 buildExecuteToolDescription({
42 toolRegistry,
43 mode,
44 }),
45 );
46 } catch {
47 return defaultExecuteToolDescription;
48 }
49};
50
51export const createPmMcpHandler = (
52 executeRun: (input: ExecuteRunInput) => Effect.Effect<ExecuteRunResult>,
53 options: PmMcpHandlerOptions,
54): ((request: Request) => Promise<Response>) => {
55 const runClient = createExecutorRunClient((input) =>
56 Effect.runPromise(executeRun(input)),
57 );
58
59 const defaultMode =
60 options.defaultToolExposureMode ?? defaultExecuteToolExposureMode;
61
62 return async (request: Request) => {
63 const mode = readToolExposureModeFromRequest(request, defaultMode);
64 const executeToolDescription = await resolveExecuteToolDescription(
65 options.toolRegistry,
66 mode,
67 );
68
69 return handleMcpHttpRequest(request, {
70 serverName: "executor-v2-pm",
71 serverVersion: "0.0.0",
72 runClient,
73 executeToolDescription,
74 });
75 };
76};
apps/pm/src/organizations-service.ts+180−0
@@ -0,0 +1,180 @@
1import { SourceStoreError } from "@executor-v2/persistence-ports";
2import {
3 makeControlPlaneOrganizationsService,
4 type ControlPlaneOrganizationsServiceShape,
5} from "@executor-v2/management-api";
6import {
7 type LocalStateSnapshot,
8 type LocalStateStore,
9 type LocalStateStoreError,
10} from "@executor-v2/persistence-local";
11import {
12 type Organization,
13 type OrganizationMembership,
14} from "@executor-v2/schema";
15import * as Effect from "effect/Effect";
16import * as Option from "effect/Option";
17
18const toSourceStoreError = (
19 operation: string,
20 message: string,
21 details: string | null,
22): SourceStoreError =>
23 new SourceStoreError({
24 operation,
25 backend: "local-file",
26 location: "snapshot.json",
27 message,
28 reason: null,
29 details,
30 });
31
32const toSourceStoreErrorFromLocalState = (
33 operation: string,
34 error: LocalStateStoreError,
35): SourceStoreError =>
36 toSourceStoreError(operation, error.message, error.details ?? error.reason ?? null);
37
38const sortOrganizations = (
39 organizations: ReadonlyArray<Organization>,
40): Array<Organization> =>
41 [...organizations].sort((left, right) => {
42 const leftName = left.name.toLowerCase();
43 const rightName = right.name.toLowerCase();
44
45 if (leftName === rightName) {
46 return left.id.localeCompare(right.id);
47 }
48
49 return leftName.localeCompare(rightName);
50 });
51
52const replaceOrganizationAt = (
53 snapshot: LocalStateSnapshot,
54 index: number,
55 organization: Organization,
56): LocalStateSnapshot => {
57 const next = [...snapshot.organizations];
58 next[index] = organization;
59
60 return {
61 ...snapshot,
62 generatedAt: Date.now(),
63 organizations: next,
64 };
65};
66
67const appendOrganization = (
68 snapshot: LocalStateSnapshot,
69 organization: Organization,
70): LocalStateSnapshot => ({
71 ...snapshot,
72 generatedAt: Date.now(),
73 organizations: [...snapshot.organizations, organization],
74});
75
76const appendOrganizationMembership = (
77 snapshot: LocalStateSnapshot,
78 membership: OrganizationMembership,
79): LocalStateSnapshot => ({
80 ...snapshot,
81 generatedAt: Date.now(),
82 organizationMemberships: [...snapshot.organizationMemberships, membership],
83});
84
85export const createPmOrganizationsService = (
86 localStateStore: LocalStateStore,
87): ControlPlaneOrganizationsServiceShape =>
88 makeControlPlaneOrganizationsService({
89 listOrganizations: () =>
90 Effect.gen(function* () {
91 const snapshotOption = yield* localStateStore.getSnapshot().pipe(
92 Effect.mapError((error) =>
93 toSourceStoreErrorFromLocalState("organizations.list", error),
94 ),
95 );
96
97 const snapshot = Option.getOrNull(snapshotOption);
98 if (snapshot === null) {
99 return [];
100 }
101
102 return sortOrganizations(snapshot.organizations);
103 }),
104
105 upsertOrganization: (input) =>
106 Effect.gen(function* () {
107 const snapshotOption = yield* localStateStore.getSnapshot().pipe(
108 Effect.mapError((error) =>
109 toSourceStoreErrorFromLocalState("organizations.upsert", error),
110 ),
111 );
112
113 const snapshot = Option.getOrNull(snapshotOption);
114 if (snapshot === null) {
115 return yield* toSourceStoreError(
116 "organizations.upsert",
117 "Organization snapshot not found",
118 null,
119 );
120 }
121
122 const now = Date.now();
123 const existingIndex = input.payload.id
124 ? snapshot.organizations.findIndex((organization) => organization.id === input.payload.id)
125 : snapshot.organizations.findIndex(
126 (organization) => organization.slug === input.payload.slug,
127 );
128 const existing = existingIndex >= 0 ? snapshot.organizations[existingIndex] : null;
129
130 const nextOrganization: Organization = {
131 id:
132 existing?.id
133 ?? (input.payload.id ?? (`org_${crypto.randomUUID()}` as Organization["id"])),
134 slug: input.payload.slug,
135 name: input.payload.name,
136 status: input.payload.status ?? existing?.status ?? "active",
137 createdByAccountId:
138 existing?.createdByAccountId
139 ?? input.payload.createdByAccountId
140 ?? null,
141 createdAt: existing?.createdAt ?? now,
142 updatedAt: now,
143 };
144
145 let nextSnapshot = existingIndex >= 0
146 ? replaceOrganizationAt(snapshot, existingIndex, nextOrganization)
147 : appendOrganization(snapshot, nextOrganization);
148
149 if (existing === null && nextOrganization.createdByAccountId !== null) {
150 const existingMembership = nextSnapshot.organizationMemberships.find(
151 (membership) =>
152 membership.organizationId === nextOrganization.id
153 && membership.accountId === nextOrganization.createdByAccountId,
154 );
155
156 if (!existingMembership) {
157 nextSnapshot = appendOrganizationMembership(nextSnapshot, {
158 id: `org_member_${crypto.randomUUID()}` as OrganizationMembership["id"],
159 organizationId: nextOrganization.id,
160 accountId: nextOrganization.createdByAccountId,
161 role: "owner",
162 status: "active",
163 billable: false,
164 invitedByAccountId: null,
165 joinedAt: now,
166 createdAt: now,
167 updatedAt: now,
168 });
169 }
170 }
171
172 yield* localStateStore.writeSnapshot(nextSnapshot).pipe(
173 Effect.mapError((error) =>
174 toSourceStoreErrorFromLocalState("organizations.upsert_write", error),
175 ),
176 );
177
178 return nextOrganization;
179 }),
180 });
apps/pm/src/persistent-approval-policy.test.ts+134−0
@@ -0,0 +1,134 @@
1import { describe, expect, it } from "@effect/vitest";
2import type {
3 LocalStateSnapshot,
4 LocalStateStore,
5} from "@executor-v2/persistence-local";
6import * as Effect from "effect/Effect";
7import * as Option from "effect/Option";
8
9import {
10 createPmApprovalsService,
11 createPmPersistentToolApprovalPolicy,
12} from "./approvals-service";
13
14const createTestSnapshot = (): LocalStateSnapshot =>
15 ({
16 schemaVersion: 1,
17 generatedAt: Date.now(),
18 profile: {
19 id: "profile_local",
20 defaultWorkspaceId: "ws_local",
21 displayName: "Local",
22 runtimeMode: "local",
23 createdAt: Date.now(),
24 updatedAt: Date.now(),
25 },
26 organizations: [],
27 organizationMemberships: [],
28 workspaces: [],
29 sources: [],
30 toolArtifacts: [],
31 credentialBindings: [],
32 oauthTokens: [],
33 policies: [],
34 approvals: [],
35 taskRuns: [],
36 storageInstances: [],
37 syncStates: [],
38 }) as unknown as LocalStateSnapshot;
39
40describe("PM persistent approval policy", () => {
41 it.effect("creates pending approval records and reuses resolved decisions", () =>
42 Effect.gen(function* () {
43 let snapshot: LocalStateSnapshot = createTestSnapshot();
44
45 const localStateStore: LocalStateStore = {
46 getSnapshot: () => Effect.succeed(Option.some(snapshot)),
47 writeSnapshot: (nextSnapshot) =>
48 Effect.sync(() => {
49 snapshot = nextSnapshot;
50 }),
51 readEvents: () => Effect.succeed([]),
52 appendEvents: () => Effect.void,
53 };
54
55 const policy = createPmPersistentToolApprovalPolicy(localStateStore, {
56 requireApprovals: true,
57 retryAfterMs: 250,
58 });
59
60 const first = yield* Effect.promise(() =>
61 Promise.resolve(
62 policy.evaluate({
63 runId: "run_approval_1",
64 callId: "call_approval_1",
65 toolPath: "github.repos.delete",
66 input: {
67 owner: "octocat",
68 repo: "hello-world",
69 },
70 workspaceId: "ws_local",
71 source: "github",
72 defaultMode: "auto",
73 }),
74 ),
75 );
76
77 expect(first.kind).toBe("pending");
78 if (first.kind === "pending") {
79 expect(first.retryAfterMs).toBe(250);
80 }
81 expect(snapshot.approvals).toHaveLength(1);
82 expect(snapshot.approvals[0]?.status).toBe("pending");
83 expect(snapshot.approvals[0]?.callId).toBe("call_approval_1");
84
85 const second = yield* Effect.promise(() =>
86 Promise.resolve(
87 policy.evaluate({
88 runId: "run_approval_1",
89 callId: "call_approval_1",
90 toolPath: "github.repos.delete",
91 workspaceId: "ws_local",
92 source: "github",
93 defaultMode: "auto",
94 }),
95 ),
96 );
97
98 expect(second).toEqual(first);
99 expect(snapshot.approvals).toHaveLength(1);
100
101 const approvalsService = createPmApprovalsService(localStateStore);
102 const createdApproval = snapshot.approvals[0];
103 if (!createdApproval) {
104 throw new Error("expected pending approval record");
105 }
106
107 yield* approvalsService.resolveApproval({
108 workspaceId: "ws_local" as any,
109 approvalId: createdApproval.id,
110 payload: {
111 status: "approved",
112 reason: "approved by test",
113 },
114 });
115
116 const finalDecision = yield* Effect.promise(() =>
117 Promise.resolve(
118 policy.evaluate({
119 runId: "run_approval_1",
120 callId: "call_approval_1",
121 toolPath: "github.repos.delete",
122 workspaceId: "ws_local",
123 source: "github",
124 defaultMode: "auto",
125 }),
126 ),
127 );
128
129 expect(finalDecision).toEqual({
130 kind: "approved",
131 });
132 }),
133 );
134});
apps/pm/src/policies-service.ts+208−0
@@ -0,0 +1,208 @@
1import { SourceStoreError } from "@executor-v2/persistence-ports";
2import {
3 type LocalStateSnapshot,
4 type LocalStateStore,
5 type LocalStateStoreError,
6} from "@executor-v2/persistence-local";
7import {
8 makeControlPlanePoliciesService,
9 type ControlPlanePoliciesServiceShape,
10} from "@executor-v2/management-api";
11import { type Policy } from "@executor-v2/schema";
12import * as Effect from "effect/Effect";
13import * as Option from "effect/Option";
14
15const toSourceStoreError = (
16 operation: string,
17 message: string,
18 details: string | null,
19): SourceStoreError =>
20 new SourceStoreError({
21 operation,
22 backend: "local-file",
23 location: "snapshot.json",
24 message,
25 reason: null,
26 details,
27 });
28
29const toSourceStoreErrorFromLocalState = (
30 operation: string,
31 error: LocalStateStoreError,
32): SourceStoreError =>
33 toSourceStoreError(operation, error.message, error.details ?? error.reason ?? null);
34
35const sortPolicies = (policies: ReadonlyArray<Policy>): Array<Policy> =>
36 [...policies].sort((left, right) => {
37 const leftPattern = left.toolPathPattern.toLowerCase();
38 const rightPattern = right.toolPathPattern.toLowerCase();
39 if (leftPattern === rightPattern) {
40 return right.updatedAt - left.updatedAt;
41 }
42
43 return leftPattern.localeCompare(rightPattern);
44 });
45
46const replacePolicyAt = (
47 snapshot: LocalStateSnapshot,
48 index: number,
49 policy: Policy,
50): LocalStateSnapshot => {
51 const next = [...snapshot.policies];
52 next[index] = policy;
53
54 return {
55 ...snapshot,
56 generatedAt: Date.now(),
57 policies: next,
58 };
59};
60
61const appendPolicy = (
62 snapshot: LocalStateSnapshot,
63 policy: Policy,
64): LocalStateSnapshot => ({
65 ...snapshot,
66 generatedAt: Date.now(),
67 policies: [...snapshot.policies, policy],
68});
69
70const removePolicyForWorkspace = (
71 snapshot: LocalStateSnapshot,
72 workspaceId: Policy["workspaceId"],
73 policyId: string,
74): { snapshot: LocalStateSnapshot; removed: boolean } => {
75 const removeIndex = snapshot.policies.findIndex(
76 (policy) => policy.workspaceId === workspaceId && policy.id === policyId,
77 );
78
79 if (removeIndex < 0) {
80 return {
81 snapshot,
82 removed: false,
83 };
84 }
85
86 const next = [...snapshot.policies];
87 next.splice(removeIndex, 1);
88
89 return {
90 removed: true,
91 snapshot: {
92 ...snapshot,
93 generatedAt: Date.now(),
94 policies: next,
95 },
96 };
97};
98
99export const createPmPoliciesService = (
100 localStateStore: LocalStateStore,
101): ControlPlanePoliciesServiceShape =>
102 makeControlPlanePoliciesService({
103 listPolicies: (workspaceId) =>
104 Effect.gen(function* () {
105 const snapshotOption = yield* localStateStore.getSnapshot().pipe(
106 Effect.mapError((error) =>
107 toSourceStoreErrorFromLocalState("policies.list", error),
108 ),
109 );
110
111 const snapshot = Option.getOrNull(snapshotOption);
112 if (snapshot === null) {
113 return [];
114 }
115
116 return sortPolicies(
117 snapshot.policies.filter((policy) => policy.workspaceId === workspaceId),
118 );
119 }),
120
121 upsertPolicy: (input) =>
122 Effect.gen(function* () {
123 const snapshotOption = yield* localStateStore.getSnapshot().pipe(
124 Effect.mapError((error) =>
125 toSourceStoreErrorFromLocalState("policies.upsert", error),
126 ),
127 );
128
129 const snapshot = Option.getOrNull(snapshotOption);
130 if (snapshot === null) {
131 return yield* toSourceStoreError(
132 "policies.upsert",
133 "Policy snapshot not found",
134 `workspace=${input.workspaceId}`,
135 );
136 }
137
138 const now = Date.now();
139 const requestedId = input.payload.id;
140
141 const existingIndex = requestedId
142 ? snapshot.policies.findIndex(
143 (policy) =>
144 policy.workspaceId === input.workspaceId && policy.id === requestedId,
145 )
146 : -1;
147
148 const existing = existingIndex >= 0 ? snapshot.policies[existingIndex] : null;
149
150 const nextPolicy: Policy = {
151 id: existing?.id ?? (requestedId ?? (`pol_${crypto.randomUUID()}` as Policy["id"])),
152 workspaceId: input.workspaceId,
153 toolPathPattern: input.payload.toolPathPattern,
154 decision: input.payload.decision,
155 createdAt: existing?.createdAt ?? now,
156 updatedAt: now,
157 };
158
159 const nextSnapshot = existingIndex >= 0
160 ? replacePolicyAt(snapshot, existingIndex, nextPolicy)
161 : appendPolicy(snapshot, nextPolicy);
162
163 yield* localStateStore.writeSnapshot(nextSnapshot).pipe(
164 Effect.mapError((error) =>
165 toSourceStoreErrorFromLocalState("policies.upsert_write", error),
166 ),
167 );
168
169 return nextPolicy;
170 }),
171
172 removePolicy: (input) =>
173 Effect.gen(function* () {
174 const snapshotOption = yield* localStateStore.getSnapshot().pipe(
175 Effect.mapError((error) =>
176 toSourceStoreErrorFromLocalState("policies.remove", error),
177 ),
178 );
179
180 const snapshot = Option.getOrNull(snapshotOption);
181 if (snapshot === null) {
182 return {
183 removed: false,
184 };
185 }
186
187 const next = removePolicyForWorkspace(
188 snapshot,
189 input.workspaceId,
190 input.policyId,
191 );
192 if (!next.removed) {
193 return {
194 removed: false,
195 };
196 }
197
198 yield* localStateStore.writeSnapshot(next.snapshot).pipe(
199 Effect.mapError((error) =>
200 toSourceStoreErrorFromLocalState("policies.remove_write", error),
201 ),
202 );
203
204 return {
205 removed: true,
206 };
207 }),
208 });
apps/pm/src/runtime-execution-port.ts+65−0
@@ -0,0 +1,65 @@
1import {
2 createRuntimeToolCallService,
3 RuntimeExecutionPortError,
4 type ExecuteRuntimeRun,
5 type ExecuteRuntimeRunInput,
6 type RuntimeAdapterRegistry,
7 type RuntimeExecuteError,
8 type ToolRegistry,
9} from "@executor-v2/engine";
10import * as Effect from "effect/Effect";
11
12export type PmRuntimeExecutionPortOptions = {
13 defaultRuntimeKind: string;
14 runtimeAdapters: RuntimeAdapterRegistry;
15 toolRegistry: ToolRegistry;
16};
17
18export const createPmExecuteRuntimeRun = (
19 options: PmRuntimeExecutionPortOptions,
20): ExecuteRuntimeRun => {
21 const runtimeToolCallService = createRuntimeToolCallService(options.toolRegistry);
22
23 return (input: ExecuteRuntimeRunInput) =>
24 Effect.gen(function* () {
25 const runtimeAdapter = yield* options.runtimeAdapters
26 .get(options.defaultRuntimeKind)
27 .pipe(
28 Effect.mapError(
29 (error) =>
30 new RuntimeExecutionPortError({
31 operation: "resolve_runtime_adapter",
32 message: error.message,
33 details: null,
34 }),
35 ),
36 );
37
38 const isAvailable = yield* runtimeAdapter.isAvailable();
39 if (!isAvailable) {
40 return yield* new RuntimeExecutionPortError({
41 operation: "runtime_available",
42 message: `Runtime '${options.defaultRuntimeKind}' is not available in this pm process.`,
43 details: null,
44 });
45 }
46
47 return yield* runtimeAdapter
48 .execute({
49 runId: input.runId,
50 code: input.code,
51 timeoutMs: input.timeoutMs,
52 toolCallService: runtimeToolCallService,
53 })
54 .pipe(
55 Effect.mapError(
56 (error: RuntimeExecuteError) =>
57 new RuntimeExecutionPortError({
58 operation: "runtime_execute",
59 message: error.message,
60 details: error.details,
61 }),
62 ),
63 );
64 });
65};
apps/pm/src/storage-service.test.ts+161−0
@@ -0,0 +1,161 @@
1import { describe, expect, it } from "@effect/vitest";
2import type {
3 LocalStateSnapshot,
4 LocalStateStore,
5} from "@executor-v2/persistence-local";
6import type { StorageInstance, WorkspaceId } from "@executor-v2/schema";
7import * as Effect from "effect/Effect";
8import * as Option from "effect/Option";
9import { mkdtemp, rm, writeFile } from "node:fs/promises";
10import { tmpdir } from "node:os";
11import * as path from "node:path";
12
13import { createPmStorageService } from "./storage-service";
14
15const createTestSnapshot = (): LocalStateSnapshot =>
16 ({
17 schemaVersion: 1,
18 generatedAt: Date.now(),
19 profile: {
20 id: "profile_local",
21 defaultWorkspaceId: "ws_local",
22 displayName: "Local",
23 runtimeMode: "local",
24 createdAt: Date.now(),
25 updatedAt: Date.now(),
26 },
27 organizations: [],
28 organizationMemberships: [],
29 workspaces: [
30 {
31 id: "ws_local",
32 organizationId: "org_local",
33 name: "Local Workspace",
34 createdByAccountId: null,
35 createdAt: Date.now(),
36 updatedAt: Date.now(),
37 },
38 ],
39 sources: [],
40 toolArtifacts: [],
41 credentialBindings: [],
42 oauthTokens: [],
43 policies: [],
44 approvals: [],
45 taskRuns: [],
46 storageInstances: [],
47 syncStates: [],
48 }) as unknown as LocalStateSnapshot;
49
50describe("PM storage service", () => {
51 it.effect("opens, inspects, queries, and removes storage instances", () =>
52 Effect.gen(function* () {
53 const stateRootDir = yield* Effect.promise(() =>
54 mkdtemp(path.join(tmpdir(), "executor-v2-pm-storage-")),
55 );
56
57 let snapshot: LocalStateSnapshot = createTestSnapshot();
58
59 const localStateStore: LocalStateStore = {
60 getSnapshot: () => Effect.succeed(Option.some(snapshot)),
61 writeSnapshot: (nextSnapshot) =>
62 Effect.sync(() => {
63 snapshot = nextSnapshot;
64 }),
65 readEvents: () => Effect.succeed([]),
66 appendEvents: () => Effect.void,
67 };
68
69 const service = createPmStorageService(localStateStore, {
70 stateRootDir,
71 });
72
73 const workspaceId = "ws_local" as WorkspaceId;
74
75 const storageInstance = yield* service.openStorageInstance({
76 workspaceId,
77 payload: {
78 scopeType: "workspace",
79 durability: "ephemeral",
80 ttlHours: 24,
81 },
82 });
83
84 expect(storageInstance.status).toBe("active");
85
86 const listed = yield* service.listStorageInstances(workspaceId);
87 expect(listed).toHaveLength(1);
88
89 const directoryBeforeWrite = yield* service.listStorageDirectory({
90 workspaceId,
91 storageInstanceId: storageInstance.id,
92 payload: {
93 path: "/",
94 },
95 });
96 expect(directoryBeforeWrite.entries).toHaveLength(0);
97
98 const storageFsPath = path.resolve(
99 stateRootDir,
100 "storage",
101 storageInstance.id,
102 "fs",
103 "hello.txt",
104 );
105
106 yield* Effect.promise(() =>
107 writeFile(storageFsPath, "hello from storage", "utf8"),
108 );
109
110 const directoryAfterWrite = yield* service.listStorageDirectory({
111 workspaceId,
112 storageInstanceId: storageInstance.id,
113 payload: {
114 path: "/",
115 },
116 });
117 expect(directoryAfterWrite.entries.some((entry) => entry.name === "hello.txt")).toBe(
118 true,
119 );
120
121 const filePreview = yield* service.readStorageFile({
122 workspaceId,
123 storageInstanceId: storageInstance.id,
124 payload: {
125 path: "/hello.txt",
126 encoding: "utf8",
127 },
128 });
129 expect(filePreview.content).toBe("hello from storage");
130
131 const kvResult = yield* service.listStorageKv({
132 workspaceId,
133 storageInstanceId: storageInstance.id,
134 payload: {
135 prefix: "",
136 limit: 20,
137 },
138 });
139 expect(kvResult.items).toHaveLength(0);
140
141 const closedStorage = yield* service.closeStorageInstance({
142 workspaceId,
143 storageInstanceId: storageInstance.id,
144 });
145 expect(closedStorage.status).toBe("closed");
146
147 const removed = yield* service.removeStorageInstance({
148 workspaceId,
149 storageInstanceId: storageInstance.id,
150 });
151 expect(removed.removed).toBe(true);
152
153 const listedAfterRemove = yield* service.listStorageInstances(workspaceId);
154 expect(listedAfterRemove).toHaveLength(0);
155
156 yield* Effect.promise(() =>
157 rm(stateRootDir, { recursive: true, force: true }),
158 );
159 }),
160 );
161});
apps/pm/src/storage-service.ts+939−0
@@ -0,0 +1,939 @@
1import {
2 makeControlPlaneStorageService,
3 type ControlPlaneStorageServiceShape,
4} from "@executor-v2/management-api";
5import { SourceStoreError } from "@executor-v2/persistence-ports";
6import {
7 type LocalStateSnapshot,
8 type LocalStateStore,
9 type LocalStateStoreError,
10} from "@executor-v2/persistence-local";
11import {
12 type OrganizationId,
13 type StorageInstance,
14 type WorkspaceId,
15} from "@executor-v2/schema";
16import * as Effect from "effect/Effect";
17import * as Option from "effect/Option";
18import {
19 mkdir,
20 readdir,
21 readFile,
22 rm,
23 stat,
24 writeFile,
25} from "node:fs/promises";
26import * as path from "node:path";
27
28const DEFAULT_EPHEMERAL_TTL_HOURS = 24;
29const DEFAULT_KV_LIMIT = 100;
30const MAX_KV_LIMIT = 1000;
31const DEFAULT_SQL_MAX_ROWS = 200;
32const MAX_SQL_MAX_ROWS = 5000;
33const MILLIS_PER_HOUR = 3_600_000;
34const STORAGE_ROOT_DIRECTORY = "storage";
35const STORAGE_FS_DIRECTORY = "fs";
36const STORAGE_KV_FILE = "kv-store.json";
37const STORAGE_SQLITE_FILE = "storage.sqlite";
38
39type SqliteDatabaseInstance = {
40 exec: (sql: string) => void;
41 query: (sql: string) => {
42 all: () => Array<Record<string, unknown>>;
43 };
44 run: (sql: string) => unknown;
45 close: () => void;
46};
47
48type SqliteDatabaseConstructor = new (
49 filename: string,
50 options?: {
51 create?: boolean;
52 },
53) => SqliteDatabaseInstance;
54
55const loadSqliteDatabase = async (): Promise<SqliteDatabaseConstructor | null> => {
56 try {
57 const sqliteModule = await import("bun:sqlite");
58 return sqliteModule.Database as SqliteDatabaseConstructor;
59 } catch {
60 return null;
61 }
62};
63
64const toSourceStoreError = (
65 operation: string,
66 message: string,
67 details: string | null,
68): SourceStoreError =>
69 new SourceStoreError({
70 operation,
71 backend: "local-file",
72 location: "snapshot.json",
73 message,
74 reason: null,
75 details,
76 });
77
78const toSourceStoreErrorFromLocalState = (
79 operation: string,
80 error: LocalStateStoreError,
81): SourceStoreError =>
82 toSourceStoreError(operation, error.message, error.details ?? error.reason ?? null);
83
84const toSourceStoreErrorFromCause = (
85 operation: string,
86 cause: unknown,
87 details?: string,
88): SourceStoreError =>
89 toSourceStoreError(
90 operation,
91 cause instanceof Error ? cause.message : String(cause),
92 details ?? null,
93 );
94
95const resolveWorkspaceOrganizationId = (
96 snapshot: LocalStateSnapshot,
97 workspaceId: WorkspaceId,
98): OrganizationId => {
99 const workspace = snapshot.workspaces.find((item) => item.id === workspaceId);
100
101 if (!workspace) {
102 throw new Error(`Workspace not found: ${workspaceId}`);
103 }
104
105 return workspace.organizationId;
106};
107
108const canAccessStorageInstance = (
109 instance: StorageInstance,
110 workspaceId: WorkspaceId,
111 organizationId: OrganizationId,
112): boolean =>
113 instance.workspaceId === workspaceId
114 || (instance.workspaceId === null && instance.organizationId === organizationId);
115
116const sortStorageInstances = (
117 storageInstances: ReadonlyArray<StorageInstance>,
118): Array<StorageInstance> =>
119 [...storageInstances].sort((left, right) => {
120 if (left.updatedAt !== right.updatedAt) {
121 return right.updatedAt - left.updatedAt;
122 }
123
124 return left.id.localeCompare(right.id);
125 });
126
127const replaceStorageInstanceAt = (
128 snapshot: LocalStateSnapshot,
129 index: number,
130 storageInstance: StorageInstance,
131): LocalStateSnapshot => {
132 const next = [...snapshot.storageInstances];
133 next[index] = storageInstance;
134
135 return {
136 ...snapshot,
137 generatedAt: Date.now(),
138 storageInstances: next,
139 };
140};
141
142const appendStorageInstance = (
143 snapshot: LocalStateSnapshot,
144 storageInstance: StorageInstance,
145): LocalStateSnapshot => ({
146 ...snapshot,
147 generatedAt: Date.now(),
148 storageInstances: [...snapshot.storageInstances, storageInstance],
149});
150
151const removeStorageInstanceById = (
152 snapshot: LocalStateSnapshot,
153 input: {
154 workspaceId: WorkspaceId;
155 organizationId: OrganizationId;
156 storageInstanceId: StorageInstance["id"];
157 },
158): { snapshot: LocalStateSnapshot; removed: boolean } => {
159 let removed = false;
160
161 const next = snapshot.storageInstances.filter((instance) => {
162 const matches =
163 instance.id === input.storageInstanceId
164 && canAccessStorageInstance(instance, input.workspaceId, input.organizationId);
165
166 if (matches) {
167 removed = true;
168 return false;
169 }
170
171 return true;
172 });
173
174 if (!removed) {
175 return {
176 snapshot,
177 removed: false,
178 };
179 }
180
181 return {
182 removed: true,
183 snapshot: {
184 ...snapshot,
185 generatedAt: Date.now(),
186 storageInstances: next,
187 },
188 };
189};
190
191const storageInstanceRootPath = (stateRootDir: string, storageInstanceId: string): string =>
192 path.resolve(stateRootDir, STORAGE_ROOT_DIRECTORY, storageInstanceId);
193
194const storageInstanceFsRootPath = (
195 stateRootDir: string,
196 storageInstanceId: string,
197): string =>
198 path.resolve(
199 storageInstanceRootPath(stateRootDir, storageInstanceId),
200 STORAGE_FS_DIRECTORY,
201 );
202
203const storageInstanceKvPath = (stateRootDir: string, storageInstanceId: string): string =>
204 path.resolve(
205 storageInstanceRootPath(stateRootDir, storageInstanceId),
206 STORAGE_KV_FILE,
207 );
208
209const storageInstanceSqlitePath = (
210 stateRootDir: string,
211 storageInstanceId: string,
212): string =>
213 path.resolve(
214 storageInstanceRootPath(stateRootDir, storageInstanceId),
215 STORAGE_SQLITE_FILE,
216 );
217
218const initializeStorageInstanceFiles = async (
219 stateRootDir: string,
220 storageInstanceId: string,
221): Promise<void> => {
222 const rootPath = storageInstanceRootPath(stateRootDir, storageInstanceId);
223 const fsRootPath = storageInstanceFsRootPath(stateRootDir, storageInstanceId);
224 const kvPath = storageInstanceKvPath(stateRootDir, storageInstanceId);
225 const sqlitePath = storageInstanceSqlitePath(stateRootDir, storageInstanceId);
226
227 await mkdir(rootPath, { recursive: true });
228 await mkdir(fsRootPath, { recursive: true });
229
230 const kvJson = JSON.stringify({}, null, 2);
231 await writeFile(kvPath, kvJson, { encoding: "utf8" });
232
233 const SqliteDatabase = await loadSqliteDatabase();
234 if (SqliteDatabase === null) {
235 await writeFile(sqlitePath, "", { encoding: "utf8" });
236 return;
237 }
238
239 const db = new SqliteDatabase(sqlitePath, { create: true });
240 try {
241 db.exec(
242 "CREATE TABLE IF NOT EXISTS kv_store (key TEXT PRIMARY KEY, value TEXT NOT NULL);",
243 );
244 } finally {
245 db.close();
246 }
247};
248
249const resolvePathWithinRoot = (
250 rootPath: string,
251 requestedPath: string,
252): {
253 normalizedPath: string;
254 absolutePath: string;
255} => {
256 const trimmed = requestedPath.trim();
257 const normalizedPath = path.posix.normalize(
258 trimmed.length > 0
259 ? (trimmed.startsWith("/") ? trimmed : `/${trimmed}`)
260 : "/",
261 );
262
263 const relativePath = normalizedPath.replace(/^\/+/, "");
264 const absolutePath = path.resolve(rootPath, relativePath);
265
266 if (absolutePath !== rootPath && !absolutePath.startsWith(`${rootPath}${path.sep}`)) {
267 throw new Error("Path escapes storage root");
268 }
269
270 return {
271 normalizedPath,
272 absolutePath,
273 };
274};
275
276const toStorageEntryPath = (absolutePath: string, fsRootPath: string): string => {
277 const relativePath = path.relative(fsRootPath, absolutePath);
278 return `/${relativePath.split(path.sep).join("/")}`;
279};
280
281const readKvStore = async (
282 kvPath: string,
283): Promise<Record<string, unknown>> => {
284 const raw = await readFile(kvPath, "utf8");
285 const parsed = JSON.parse(raw) as unknown;
286
287 if (parsed !== null && typeof parsed === "object" && !Array.isArray(parsed)) {
288 return parsed as Record<string, unknown>;
289 }
290
291 return {};
292};
293
294const findStorageInstance = (
295 snapshot: LocalStateSnapshot,
296 input: {
297 workspaceId: WorkspaceId;
298 storageInstanceId: StorageInstance["id"];
299 },
300): {
301 storageInstance: StorageInstance;
302 storageInstanceIndex: number;
303} | null => {
304 const organizationId = resolveWorkspaceOrganizationId(snapshot, input.workspaceId);
305 const storageInstanceIndex = snapshot.storageInstances.findIndex((instance) =>
306 instance.id === input.storageInstanceId
307 && canAccessStorageInstance(instance, input.workspaceId, organizationId)
308 );
309
310 if (storageInstanceIndex < 0) {
311 return null;
312 }
313
314 const storageInstance = snapshot.storageInstances[storageInstanceIndex];
315 if (!storageInstance) {
316 return null;
317 }
318
319 return {
320 storageInstance,
321 storageInstanceIndex,
322 };
323};
324
325const touchStorageInstance = (
326 snapshot: LocalStateSnapshot,
327 storageInstanceIndex: number,
328): {
329 snapshot: LocalStateSnapshot;
330 storageInstance: StorageInstance;
331} => {
332 const existing = snapshot.storageInstances[storageInstanceIndex];
333 const now = Date.now();
334
335 const touchedStorageInstance: StorageInstance = {
336 ...existing,
337 updatedAt: now,
338 lastSeenAt: now,
339 };
340
341 return {
342 storageInstance: touchedStorageInstance,
343 snapshot: replaceStorageInstanceAt(snapshot, storageInstanceIndex, touchedStorageInstance),
344 };
345};
346
347export const createPmStorageService = (
348 localStateStore: LocalStateStore,
349 options: {
350 stateRootDir: string;
351 },
352): ControlPlaneStorageServiceShape =>
353 makeControlPlaneStorageService({
354 listStorageInstances: (workspaceId) =>
355 Effect.gen(function* () {
356 const snapshotOption = yield* localStateStore.getSnapshot().pipe(
357 Effect.mapError((error) =>
358 toSourceStoreErrorFromLocalState("storage.list", error),
359 ),
360 );
361
362 const snapshot = Option.getOrNull(snapshotOption);
363 if (snapshot === null) {
364 return [];
365 }
366
367 const organizationId = resolveWorkspaceOrganizationId(snapshot, workspaceId);
368
369 return sortStorageInstances(
370 snapshot.storageInstances.filter((instance) =>
371 canAccessStorageInstance(instance, workspaceId, organizationId)
372 ),
373 );
374 }),
375
376 openStorageInstance: (input) =>
377 Effect.gen(function* () {
378 const snapshotOption = yield* localStateStore.getSnapshot().pipe(
379 Effect.mapError((error) =>
380 toSourceStoreErrorFromLocalState("storage.open", error),
381 ),
382 );
383
384 const snapshot = Option.getOrNull(snapshotOption);
385 if (snapshot === null) {
386 return yield* toSourceStoreError(
387 "storage.open",
388 "Storage snapshot not found",
389 `workspace=${input.workspaceId}`,
390 );
391 }
392
393 if (input.payload.scopeType === "account" && input.payload.accountId === undefined) {
394 return yield* toSourceStoreError(
395 "storage.open",
396 "Account scope storage requires accountId",
397 `workspace=${input.workspaceId}`,
398 );
399 }
400
401 const now = Date.now();
402 const organizationId = resolveWorkspaceOrganizationId(snapshot, input.workspaceId);
403 const storageInstanceId =
404 `storage_${crypto.randomUUID()}` as StorageInstance["id"];
405 const ttlHours =
406 input.payload.ttlHours !== undefined && Number.isFinite(input.payload.ttlHours)
407 ? Math.max(1, Math.floor(input.payload.ttlHours))
408 : DEFAULT_EPHEMERAL_TTL_HOURS;
409
410 yield* Effect.tryPromise({
411 try: () => initializeStorageInstanceFiles(options.stateRootDir, storageInstanceId),
412 catch: (cause) =>
413 toSourceStoreErrorFromCause(
414 "storage.open_initialize",
415 cause,
416 `storageInstance=${storageInstanceId}`,
417 ),
418 });
419
420 const nextStorageInstance: StorageInstance = {
421 id: storageInstanceId,
422 scopeType: input.payload.scopeType,
423 durability: input.payload.durability,
424 status: "active",
425 provider: input.payload.provider ?? "agentfs-local",
426 backendKey: `local:${storageInstanceId}`,
427 organizationId,
428 workspaceId:
429 input.payload.scopeType === "workspace" || input.payload.scopeType === "scratch"
430 ? input.workspaceId
431 : null,
432 accountId:
433 input.payload.scopeType === "account"
434 ? (input.payload.accountId ?? null)
435 : null,
436 createdByAccountId: input.payload.accountId ?? null,
437 purpose:
438 input.payload.purpose !== undefined && input.payload.purpose.trim().length > 0
439 ? input.payload.purpose.trim()
440 : null,
441 sizeBytes: null,
442 fileCount: null,
443 createdAt: now,
444 updatedAt: now,
445 lastSeenAt: now,
446 closedAt: null,
447 expiresAt:
448 input.payload.durability === "ephemeral"
449 ? now + ttlHours * MILLIS_PER_HOUR
450 : null,
451 };
452
453 const nextSnapshot = appendStorageInstance(snapshot, nextStorageInstance);
454
455 yield* localStateStore.writeSnapshot(nextSnapshot).pipe(
456 Effect.mapError((error) =>
457 toSourceStoreErrorFromLocalState("storage.open_write", error),
458 ),
459 );
460
461 return nextStorageInstance;
462 }),
463
464 closeStorageInstance: (input) =>
465 Effect.gen(function* () {
466 const snapshotOption = yield* localStateStore.getSnapshot().pipe(
467 Effect.mapError((error) =>
468 toSourceStoreErrorFromLocalState("storage.close", error),
469 ),
470 );
471
472 const snapshot = Option.getOrNull(snapshotOption);
473 if (snapshot === null) {
474 return yield* toSourceStoreError(
475 "storage.close",
476 "Storage snapshot not found",
477 `workspace=${input.workspaceId}`,
478 );
479 }
480
481 const found = findStorageInstance(snapshot, {
482 workspaceId: input.workspaceId,
483 storageInstanceId: input.storageInstanceId,
484 });
485
486 if (found === null) {
487 return yield* toSourceStoreError(
488 "storage.close",
489 "Storage instance not found",
490 `workspace=${input.workspaceId} id=${input.storageInstanceId}`,
491 );
492 }
493
494 const now = Date.now();
495
496 const nextStorageInstance: StorageInstance = {
497 ...found.storageInstance,
498 status: "closed",
499 updatedAt: now,
500 lastSeenAt: now,
501 closedAt: found.storageInstance.closedAt ?? now,
502 };
503
504 const nextSnapshot = replaceStorageInstanceAt(
505 snapshot,
506 found.storageInstanceIndex,
507 nextStorageInstance,
508 );
509
510 yield* localStateStore.writeSnapshot(nextSnapshot).pipe(
511 Effect.mapError((error) =>
512 toSourceStoreErrorFromLocalState("storage.close_write", error),
513 ),
514 );
515
516 return nextStorageInstance;
517 }),
518
519 removeStorageInstance: (input) =>
520 Effect.gen(function* () {
521 const snapshotOption = yield* localStateStore.getSnapshot().pipe(
522 Effect.mapError((error) =>
523 toSourceStoreErrorFromLocalState("storage.remove", error),
524 ),
525 );
526
527 const snapshot = Option.getOrNull(snapshotOption);
528 if (snapshot === null) {
529 return {
530 removed: false,
531 };
532 }
533
534 const organizationId = resolveWorkspaceOrganizationId(snapshot, input.workspaceId);
535
536 const next = removeStorageInstanceById(snapshot, {
537 workspaceId: input.workspaceId,
538 organizationId,
539 storageInstanceId: input.storageInstanceId,
540 });
541
542 if (!next.removed) {
543 return {
544 removed: false,
545 };
546 }
547
548 yield* Effect.tryPromise({
549 try: () =>
550 rm(
551 storageInstanceRootPath(options.stateRootDir, input.storageInstanceId),
552 {
553 recursive: true,
554 force: true,
555 },
556 ),
557 catch: (cause) =>
558 toSourceStoreErrorFromCause(
559 "storage.remove_files",
560 cause,
561 `storageInstance=${input.storageInstanceId}`,
562 ),
563 });
564
565 yield* localStateStore.writeSnapshot(next.snapshot).pipe(
566 Effect.mapError((error) =>
567 toSourceStoreErrorFromLocalState("storage.remove_write", error),
568 ),
569 );
570
571 return {
572 removed: true,
573 };
574 }),
575
576 listStorageDirectory: (input) =>
577 Effect.gen(function* () {
578 const snapshotOption = yield* localStateStore.getSnapshot().pipe(
579 Effect.mapError((error) =>
580 toSourceStoreErrorFromLocalState("storage.listDirectory", error),
581 ),
582 );
583
584 const snapshot = Option.getOrNull(snapshotOption);
585 if (snapshot === null) {
586 return yield* toSourceStoreError(
587 "storage.listDirectory",
588 "Storage snapshot not found",
589 `workspace=${input.workspaceId}`,
590 );
591 }
592
593 const found = findStorageInstance(snapshot, {
594 workspaceId: input.workspaceId,
595 storageInstanceId: input.storageInstanceId,
596 });
597
598 if (found === null) {
599 return yield* toSourceStoreError(
600 "storage.listDirectory",
601 "Storage instance not found",
602 `workspace=${input.workspaceId} id=${input.storageInstanceId}`,
603 );
604 }
605
606 const fsRootPath = storageInstanceFsRootPath(
607 options.stateRootDir,
608 found.storageInstance.id,
609 );
610
611 const result = yield* Effect.tryPromise({
612 try: async () => {
613 await mkdir(fsRootPath, { recursive: true });
614
615 const resolved = resolvePathWithinRoot(
616 fsRootPath,
617 input.payload.path,
618 );
619
620 const entries = await readdir(resolved.absolutePath, {
621 withFileTypes: true,
622 });
623
624 const mapped = await Promise.all(
625 entries.map(async (entry) => {
626 const entryAbsolutePath = path.resolve(
627 resolved.absolutePath,
628 entry.name,
629 );
630 const entryStat = await stat(entryAbsolutePath);
631
632 return {
633 name: entry.name,
634 path: toStorageEntryPath(entryAbsolutePath, fsRootPath),
635 kind: entry.isDirectory() ? "directory" : "file",
636 sizeBytes: entry.isDirectory() ? null : entryStat.size,
637 updatedAt: entryStat.mtimeMs,
638 } as const;
639 }),
640 );
641
642 mapped.sort((left, right) => {
643 if (left.kind !== right.kind) {
644 return left.kind === "directory" ? -1 : 1;
645 }
646
647 return left.name.localeCompare(right.name);
648 });
649
650 return {
651 path: resolved.normalizedPath,
652 entries: mapped,
653 };
654 },
655 catch: (cause) =>
656 toSourceStoreErrorFromCause(
657 "storage.listDirectory_read",
658 cause,
659 `storageInstance=${found.storageInstance.id} path=${input.payload.path}`,
660 ),
661 });
662
663 const touched = touchStorageInstance(snapshot, found.storageInstanceIndex);
664
665 yield* localStateStore.writeSnapshot(touched.snapshot).pipe(
666 Effect.mapError((error) =>
667 toSourceStoreErrorFromLocalState(
668 "storage.listDirectory_touch",
669 error,
670 ),
671 ),
672 );
673
674 return result;
675 }),
676
677 readStorageFile: (input) =>
678 Effect.gen(function* () {
679 const snapshotOption = yield* localStateStore.getSnapshot().pipe(
680 Effect.mapError((error) =>
681 toSourceStoreErrorFromLocalState("storage.readFile", error),
682 ),
683 );
684
685 const snapshot = Option.getOrNull(snapshotOption);
686 if (snapshot === null) {
687 return yield* toSourceStoreError(
688 "storage.readFile",
689 "Storage snapshot not found",
690 `workspace=${input.workspaceId}`,
691 );
692 }
693
694 const found = findStorageInstance(snapshot, {
695 workspaceId: input.workspaceId,
696 storageInstanceId: input.storageInstanceId,
697 });
698
699 if (found === null) {
700 return yield* toSourceStoreError(
701 "storage.readFile",
702 "Storage instance not found",
703 `workspace=${input.workspaceId} id=${input.storageInstanceId}`,
704 );
705 }
706
707 const fsRootPath = storageInstanceFsRootPath(
708 options.stateRootDir,
709 found.storageInstance.id,
710 );
711 const encoding = input.payload.encoding ?? "utf8";
712
713 const result = yield* Effect.tryPromise({
714 try: async () => {
715 await mkdir(fsRootPath, { recursive: true });
716
717 const resolved = resolvePathWithinRoot(fsRootPath, input.payload.path);
718 const entryStat = await stat(resolved.absolutePath);
719
720 if (entryStat.isDirectory()) {
721 throw new Error("Cannot read a directory");
722 }
723
724 const contentBuffer = await readFile(resolved.absolutePath);
725
726 return {
727 path: resolved.normalizedPath,
728 encoding,
729 content:
730 encoding === "base64"
731 ? contentBuffer.toString("base64")
732 : contentBuffer.toString("utf8"),
733 bytes: contentBuffer.byteLength,
734 };
735 },
736 catch: (cause) =>
737 toSourceStoreErrorFromCause(
738 "storage.readFile_read",
739 cause,
740 `storageInstance=${found.storageInstance.id} path=${input.payload.path}`,
741 ),
742 });
743
744 const touched = touchStorageInstance(snapshot, found.storageInstanceIndex);
745
746 yield* localStateStore.writeSnapshot(touched.snapshot).pipe(
747 Effect.mapError((error) =>
748 toSourceStoreErrorFromLocalState("storage.readFile_touch", error),
749 ),
750 );
751
752 return result;
753 }),
754
755 listStorageKv: (input) =>
756 Effect.gen(function* () {
757 const snapshotOption = yield* localStateStore.getSnapshot().pipe(
758 Effect.mapError((error) =>
759 toSourceStoreErrorFromLocalState("storage.listKv", error),
760 ),
761 );
762
763 const snapshot = Option.getOrNull(snapshotOption);
764 if (snapshot === null) {
765 return yield* toSourceStoreError(
766 "storage.listKv",
767 "Storage snapshot not found",
768 `workspace=${input.workspaceId}`,
769 );
770 }
771
772 const found = findStorageInstance(snapshot, {
773 workspaceId: input.workspaceId,
774 storageInstanceId: input.storageInstanceId,
775 });
776
777 if (found === null) {
778 return yield* toSourceStoreError(
779 "storage.listKv",
780 "Storage instance not found",
781 `workspace=${input.workspaceId} id=${input.storageInstanceId}`,
782 );
783 }
784
785 const kvPath = storageInstanceKvPath(
786 options.stateRootDir,
787 found.storageInstance.id,
788 );
789
790 const result = yield* Effect.tryPromise({
791 try: async () => {
792 const kvStore = await readKvStore(kvPath);
793 const prefix = input.payload.prefix ?? "";
794 const requestedLimit =
795 input.payload.limit !== undefined && Number.isFinite(input.payload.limit)
796 ? Math.floor(input.payload.limit)
797 : DEFAULT_KV_LIMIT;
798 const limit = Math.max(1, Math.min(MAX_KV_LIMIT, requestedLimit));
799
800 const items = Object.entries(kvStore)
801 .filter(([key]) => key.startsWith(prefix))
802 .sort(([leftKey], [rightKey]) => leftKey.localeCompare(rightKey))
803 .slice(0, limit)
804 .map(([key, value]) => ({ key, value }));
805
806 return {
807 items,
808 };
809 },
810 catch: (cause) =>
811 toSourceStoreErrorFromCause(
812 "storage.listKv_read",
813 cause,
814 `storageInstance=${found.storageInstance.id}`,
815 ),
816 });
817
818 const touched = touchStorageInstance(snapshot, found.storageInstanceIndex);
819
820 yield* localStateStore.writeSnapshot(touched.snapshot).pipe(
821 Effect.mapError((error) =>
822 toSourceStoreErrorFromLocalState("storage.listKv_touch", error),
823 ),
824 );
825
826 return result;
827 }),
828
829 queryStorageSql: (input) =>
830 Effect.gen(function* () {
831 const snapshotOption = yield* localStateStore.getSnapshot().pipe(
832 Effect.mapError((error) =>
833 toSourceStoreErrorFromLocalState("storage.querySql", error),
834 ),
835 );
836
837 const snapshot = Option.getOrNull(snapshotOption);
838 if (snapshot === null) {
839 return yield* toSourceStoreError(
840 "storage.querySql",
841 "Storage snapshot not found",
842 `workspace=${input.workspaceId}`,
843 );
844 }
845
846 const found = findStorageInstance(snapshot, {
847 workspaceId: input.workspaceId,
848 storageInstanceId: input.storageInstanceId,
849 });
850
851 if (found === null) {
852 return yield* toSourceStoreError(
853 "storage.querySql",
854 "Storage instance not found",
855 `workspace=${input.workspaceId} id=${input.storageInstanceId}`,
856 );
857 }
858
859 const sqlText = input.payload.sql.trim();
860 if (sqlText.length === 0) {
861 return yield* toSourceStoreError(
862 "storage.querySql",
863 "SQL query is required",
864 `workspace=${input.workspaceId} id=${input.storageInstanceId}`,
865 );
866 }
867
868 const sqlitePath = storageInstanceSqlitePath(
869 options.stateRootDir,
870 found.storageInstance.id,
871 );
872
873 const result = yield* Effect.tryPromise({
874 try: async () => {
875 await mkdir(path.dirname(sqlitePath), { recursive: true });
876
877 const SqliteDatabase = await loadSqliteDatabase();
878 if (SqliteDatabase === null) {
879 throw new Error("SQLite runtime is unavailable in this environment");
880 }
881
882 const db = new SqliteDatabase(sqlitePath, { create: true });
883
884 try {
885 db.exec(
886 "CREATE TABLE IF NOT EXISTS kv_store (key TEXT PRIMARY KEY, value TEXT NOT NULL);",
887 );
888
889 const maxRows =
890 input.payload.maxRows !== undefined && Number.isFinite(input.payload.maxRows)
891 ? Math.max(1, Math.min(MAX_SQL_MAX_ROWS, Math.floor(input.payload.maxRows)))
892 : DEFAULT_SQL_MAX_ROWS;
893
894 try {
895 const statement = db.query(sqlText);
896 const rawRows = statement.all() as Array<Record<string, unknown>>;
897 const rows = rawRows.slice(0, maxRows);
898 const columns =
899 rows.length > 0
900 ? Array.from(new Set(rows.flatMap((row) => Object.keys(row))))
901 : [];
902
903 return {
904 rows,
905 columns,
906 rowCount: rows.length,
907 };
908 } catch {
909 db.run(sqlText);
910
911 return {
912 rows: [],
913 columns: [],
914 rowCount: 0,
915 };
916 }
917 } finally {
918 db.close();
919 }
920 },
921 catch: (cause) =>
922 toSourceStoreErrorFromCause(
923 "storage.querySql_run",
924 cause,
925 `storageInstance=${found.storageInstance.id}`,
926 ),
927 });
928
929 const touched = touchStorageInstance(snapshot, found.storageInstanceIndex);
930
931 yield* localStateStore.writeSnapshot(touched.snapshot).pipe(
932 Effect.mapError((error) =>
933 toSourceStoreErrorFromLocalState("storage.querySql_touch", error),
934 ),
935 );
936
937 return result;
938 }),
939 });
apps/pm/src/tool-call-handler.test.ts+42−0
@@ -0,0 +1,42 @@
1import {
2 createRuntimeToolCallHandler,
3 createUnimplementedRuntimeToolInvoker,
4} from "@executor-v2/engine";
5import { describe, expect, it } from "@effect/vitest";
6import * as Effect from "effect/Effect";
7import * as Option from "effect/Option";
8
9import { createPmResolveToolCredentials } from "./credential-resolver";
10
11const emptyLocalStateStore = {
12 getSnapshot: () => Effect.succeed(Option.none()),
13 writeSnapshot: () => Effect.void,
14 readEvents: () => Effect.succeed([]),
15 appendEvents: () => Effect.void,
16};
17
18describe("PM runtime tool-call handling", () => {
19 it.effect("returns failed callback result for unimplemented invoker", () =>
20 Effect.gen(function* () {
21 const resolveCredentials = createPmResolveToolCredentials(emptyLocalStateStore);
22 const invokeRuntimeTool = createUnimplementedRuntimeToolInvoker("pm");
23 const handleToolCall = createRuntimeToolCallHandler({
24 resolveCredentials,
25 invokeRuntimeTool,
26 });
27
28 const result = yield* handleToolCall({
29 runId: "run_2",
30 callId: "call_2",
31 toolPath: "tools.example.weather",
32 input: { city: "London" },
33 });
34
35 expect(result.ok).toBe(false);
36 if (!result.ok) {
37 expect(result.kind).toBe("failed");
38 expect(result.error).toContain("tools.example.weather");
39 }
40 }),
41 );
42});
apps/pm/src/tool-call-handler.ts+107−0
@@ -0,0 +1,107 @@
1import {
2 type RuntimeToolCallResult,
3 type RuntimeToolCallRequest,
4} from "@executor-v2/sdk";
5import * as Data from "effect/Data";
6import * as Effect from "effect/Effect";
7import * as ParseResult from "effect/ParseResult";
8import * as Schema from "effect/Schema";
9
10class PmToolCallHttpRequestError extends Data.TaggedError(
11 "PmToolCallHttpRequestError",
12)<{
13 message: string;
14 details: string | null;
15}> {}
16
17const RuntimeToolCallCredentialContextSchema = Schema.Struct({
18 workspaceId: Schema.String,
19 sourceKey: Schema.String,
20 organizationId: Schema.optional(Schema.NullOr(Schema.String)),
21 accountId: Schema.optional(Schema.NullOr(Schema.String)),
22});
23
24const RuntimeToolCallRequestSchema = Schema.Struct({
25 runId: Schema.String,
26 callId: Schema.String,
27 toolPath: Schema.String,
28 input: Schema.optional(
29 Schema.Record({
30 key: Schema.String,
31 value: Schema.Unknown,
32 }),
33 ),
34 credentialContext: Schema.optional(RuntimeToolCallCredentialContextSchema),
35});
36
37const decodeRuntimeToolCallRequest = Schema.decodeUnknown(RuntimeToolCallRequestSchema);
38
39const decodeRequestBodyError = (cause: unknown): PmToolCallHttpRequestError =>
40 new PmToolCallHttpRequestError({
41 message: "Invalid runtime callback request body",
42 details: String(cause),
43 });
44
45const decodeRequestPayloadError = (cause: unknown): PmToolCallHttpRequestError =>
46 new PmToolCallHttpRequestError({
47 message: "Runtime callback request body is invalid",
48 details: ParseResult.isParseError(cause)
49 ? ParseResult.TreeFormatter.formatErrorSync(cause)
50 : String(cause),
51 });
52
53const formatHttpRequestError = (error: PmToolCallHttpRequestError): string =>
54 error.details && error.details.length > 0
55 ? `${error.message}: ${error.details}`
56 : error.message;
57
58const decodeToolCallRequest = async (
59 request: Request,
60): Promise<RuntimeToolCallRequest> => {
61 let body: unknown;
62 try {
63 body = await request.json();
64 } catch (cause) {
65 throw decodeRequestBodyError(cause);
66 }
67
68 try {
69 return await Effect.runPromise(decodeRuntimeToolCallRequest(body));
70 } catch (cause) {
71 throw decodeRequestPayloadError(cause);
72 }
73};
74
75export const createPmToolCallHttpHandler = (
76 handleToolCall: (
77 input: RuntimeToolCallRequest,
78 ) => Promise<RuntimeToolCallResult>,
79): ((request: Request) => Promise<Response>) => {
80 return async (request: Request) => {
81 try {
82 const input = await decodeToolCallRequest(request);
83 const result = await handleToolCall(input);
84 return Response.json(result, { status: 200 });
85 } catch (error) {
86 if (error instanceof PmToolCallHttpRequestError) {
87 return Response.json(
88 {
89 ok: false,
90 kind: "failed",
91 error: formatHttpRequestError(error),
92 } satisfies RuntimeToolCallResult,
93 { status: 400 },
94 );
95 }
96
97 return Response.json(
98 {
99 ok: false,
100 kind: "failed",
101 error: String(error),
102 } satisfies RuntimeToolCallResult,
103 { status: 500 },
104 );
105 }
106 };
107};
apps/pm/src/tools-service.ts+253−0
@@ -0,0 +1,253 @@
1import {
2 SourceStoreError,
3 ToolArtifactStoreError,
4 type SourceStore,
5 type ToolArtifactStore,
6} from "@executor-v2/persistence-ports";
7import {
8 makeControlPlaneToolsService,
9 type ControlPlaneToolsServiceShape,
10 type SourceToolDetail,
11 type SourceToolSummary,
12} from "@executor-v2/management-api";
13import {
14 OpenApiToolManifestSchema,
15 type Source,
16 type SourceId,
17 type ToolArtifact,
18 type WorkspaceId,
19} from "@executor-v2/schema";
20import * as Effect from "effect/Effect";
21import * as Option from "effect/Option";
22import * as ParseResult from "effect/ParseResult";
23import * as Schema from "effect/Schema";
24
25const decodeOpenApiToolManifest = Schema.decodeUnknown(OpenApiToolManifestSchema);
26
27const toSourceStoreError = (
28 operation: string,
29 message: string,
30 details: string | null,
31): SourceStoreError =>
32 new SourceStoreError({
33 operation,
34 backend: "local-file",
35 location: "tool-artifacts.json",
36 message,
37 reason: null,
38 details,
39 });
40
41const toSourceStoreErrorFromSourceStore = (
42 operation: string,
43 error: SourceStoreError,
44): SourceStoreError =>
45 toSourceStoreError(operation, error.message, error.details ?? error.reason ?? null);
46
47const toSourceStoreErrorFromToolArtifactStore = (
48 operation: string,
49 error: ToolArtifactStoreError,
50): SourceStoreError =>
51 toSourceStoreError(operation, error.message, error.details ?? error.reason ?? null);
52
53const parseArtifactManifest = (
54 source: Source,
55 artifact: ToolArtifact,
56): Effect.Effect<ReadonlyArray<SourceToolSummary>, SourceStoreError> =>
57 Effect.try({
58 try: () => JSON.parse(artifact.manifestJson) as unknown,
59 catch: (cause) =>
60 toSourceStoreError(
61 "tools.decode_manifest_json",
62 cause instanceof Error ? cause.message : String(cause),
63 `sourceId=${source.id}`,
64 ),
65 }).pipe(
66 Effect.flatMap((manifestJson) =>
67 decodeOpenApiToolManifest(manifestJson).pipe(
68 Effect.mapError((cause) =>
69 toSourceStoreError(
70 "tools.decode_manifest",
71 "Unable to decode OpenAPI manifest",
72 ParseResult.TreeFormatter.formatErrorSync(cause),
73 ),
74 ),
75 )
76 ),
77 Effect.map((manifest) =>
78 manifest.tools.map((tool) => ({
79 sourceId: source.id,
80 sourceName: source.name,
81 sourceKind: source.kind,
82 toolId: tool.toolId,
83 name: tool.name,
84 description: tool.description,
85 method: tool.method,
86 path: tool.path,
87 operationHash: tool.operationHash,
88 })),
89 ),
90 );
91
92const sortTools = (tools: ReadonlyArray<SourceToolSummary>): Array<SourceToolSummary> =>
93 [...tools].sort((left, right) => {
94 const leftSource = left.sourceName.toLowerCase();
95 const rightSource = right.sourceName.toLowerCase();
96
97 if (leftSource !== rightSource) {
98 return leftSource.localeCompare(rightSource);
99 }
100
101 const leftName = left.name.toLowerCase();
102 const rightName = right.name.toLowerCase();
103
104 if (leftName !== rightName) {
105 return leftName.localeCompare(rightName);
106 }
107
108 return left.toolId.localeCompare(right.toolId);
109 });
110
111const listSourceTools = (
112 sourceStore: SourceStore,
113 toolArtifactStore: ToolArtifactStore,
114 input: {
115 workspaceId: WorkspaceId;
116 sourceId: SourceId;
117 },
118): Effect.Effect<ReadonlyArray<SourceToolSummary>, SourceStoreError> =>
119 Effect.gen(function* () {
120 const sourceOption = yield* sourceStore.getById(input.workspaceId, input.sourceId).pipe(
121 Effect.mapError((error) =>
122 toSourceStoreErrorFromSourceStore("tools.get_source", error),
123 ),
124 );
125
126 const source = Option.getOrNull(sourceOption);
127 if (source === null) {
128 return [];
129 }
130
131 const artifactOption = yield* toolArtifactStore
132 .getBySource(input.workspaceId, input.sourceId)
133 .pipe(
134 Effect.mapError((error) =>
135 toSourceStoreErrorFromToolArtifactStore("tools.get_artifact", error),
136 ),
137 );
138
139 const artifact = Option.getOrNull(artifactOption);
140 if (artifact === null) {
141 return [];
142 }
143
144 return yield* parseArtifactManifest(source, artifact);
145 });
146
147export const createPmToolsService = (
148 sourceStore: SourceStore,
149 toolArtifactStore: ToolArtifactStore,
150): ControlPlaneToolsServiceShape =>
151 makeControlPlaneToolsService({
152 listWorkspaceTools: (workspaceId) =>
153 Effect.gen(function* () {
154 const sources = yield* sourceStore.listByWorkspace(workspaceId).pipe(
155 Effect.mapError((error) =>
156 toSourceStoreErrorFromSourceStore("tools.list_sources", error),
157 ),
158 );
159
160 const toolGroups = yield* Effect.forEach(
161 sources,
162 (source) =>
163 listSourceTools(sourceStore, toolArtifactStore, {
164 workspaceId,
165 sourceId: source.id,
166 }),
167 {
168 concurrency: "unbounded",
169 },
170 );
171
172 return sortTools(toolGroups.flat());
173 }),
174
175 listSourceTools: (input) =>
176 listSourceTools(sourceStore, toolArtifactStore, {
177 workspaceId: input.workspaceId,
178 sourceId: input.sourceId,
179 }),
180
181 getToolDetail: (input) =>
182 Effect.gen(function* () {
183 const sourceOption = yield* sourceStore
184 .getById(input.workspaceId, input.sourceId)
185 .pipe(
186 Effect.mapError((error) =>
187 toSourceStoreErrorFromSourceStore("tools.get_detail_source", error),
188 ),
189 );
190
191 const source = Option.getOrNull(sourceOption);
192 if (source === null) {
193 return null;
194 }
195
196 const artifactOption = yield* toolArtifactStore
197 .getBySource(input.workspaceId, input.sourceId)
198 .pipe(
199 Effect.mapError((error) =>
200 toSourceStoreErrorFromToolArtifactStore("tools.get_detail_artifact", error),
201 ),
202 );
203
204 const artifact = Option.getOrNull(artifactOption);
205 if (artifact === null) {
206 return null;
207 }
208
209 const manifestResult = yield* Effect.try({
210 try: () => JSON.parse(artifact.manifestJson) as unknown,
211 catch: () => null as never,
212 }).pipe(Effect.option);
213
214 if (Option.isNone(manifestResult)) {
215 return null;
216 }
217
218 const decoded = yield* decodeOpenApiToolManifest(manifestResult.value).pipe(
219 Effect.option,
220 );
221
222 if (Option.isNone(decoded)) {
223 return null;
224 }
225
226 const manifest = decoded.value;
227 const tool = manifest.tools.find((t) => t.operationHash === input.operationHash);
228 if (!tool) {
229 return null;
230 }
231
232
233
234 const detail: SourceToolDetail = {
235 sourceId: source.id,
236 sourceName: source.name,
237 sourceKind: source.kind,
238 toolId: tool.toolId,
239 name: tool.name,
240 description: tool.description,
241 method: tool.method,
242 path: tool.path,
243 operationHash: tool.operationHash,
244 inputSchemaJson: tool.typing?.inputSchemaJson ?? null,
245 outputSchemaJson: tool.typing?.outputSchemaJson ?? null,
246 refHintTableJson: manifest.refHintTable
247 ? JSON.stringify(manifest.refHintTable)
248 : null,
249 };
250
251 return detail;
252 }),
253 });
apps/pm/src/workspaces-service.ts+135−0
@@ -0,0 +1,135 @@
1import { SourceStoreError } from "@executor-v2/persistence-ports";
2import {
3 makeControlPlaneWorkspacesService,
4 type ControlPlaneWorkspacesServiceShape,
5} from "@executor-v2/management-api";
6import {
7 type LocalStateSnapshot,
8 type LocalStateStore,
9 type LocalStateStoreError,
10} from "@executor-v2/persistence-local";
11import { type Workspace } from "@executor-v2/schema";
12import * as Effect from "effect/Effect";
13import * as Option from "effect/Option";
14
15const toSourceStoreError = (
16 operation: string,
17 message: string,
18 details: string | null,
19): SourceStoreError =>
20 new SourceStoreError({
21 operation,
22 backend: "local-file",
23 location: "snapshot.json",
24 message,
25 reason: null,
26 details,
27 });
28
29const toSourceStoreErrorFromLocalState = (
30 operation: string,
31 error: LocalStateStoreError,
32): SourceStoreError =>
33 toSourceStoreError(operation, error.message, error.details ?? error.reason ?? null);
34
35const sortWorkspaces = (workspaces: ReadonlyArray<Workspace>): Array<Workspace> =>
36 [...workspaces].sort((left, right) => {
37 const leftName = left.name.toLowerCase();
38 const rightName = right.name.toLowerCase();
39
40 if (leftName === rightName) {
41 return left.id.localeCompare(right.id);
42 }
43
44 return leftName.localeCompare(rightName);
45 });
46
47const replaceWorkspaceAt = (
48 snapshot: LocalStateSnapshot,
49 index: number,
50 workspace: Workspace,
51): LocalStateSnapshot => {
52 const next = [...snapshot.workspaces];
53 next[index] = workspace;
54
55 return {
56 ...snapshot,
57 generatedAt: Date.now(),
58 workspaces: next,
59 };
60};
61
62const appendWorkspace = (
63 snapshot: LocalStateSnapshot,
64 workspace: Workspace,
65): LocalStateSnapshot => ({
66 ...snapshot,
67 generatedAt: Date.now(),
68 workspaces: [...snapshot.workspaces, workspace],
69});
70
71export const createPmWorkspacesService = (
72 localStateStore: LocalStateStore,
73): ControlPlaneWorkspacesServiceShape =>
74 makeControlPlaneWorkspacesService({
75 listWorkspaces: () =>
76 Effect.gen(function* () {
77 const snapshotOption = yield* localStateStore.getSnapshot().pipe(
78 Effect.mapError((error) =>
79 toSourceStoreErrorFromLocalState("workspaces.list", error),
80 ),
81 );
82
83 const snapshot = Option.getOrNull(snapshotOption);
84 if (snapshot === null) {
85 return [];
86 }
87
88 return sortWorkspaces(snapshot.workspaces);
89 }),
90
91 upsertWorkspace: (input) =>
92 Effect.gen(function* () {
93 const snapshotOption = yield* localStateStore.getSnapshot().pipe(
94 Effect.mapError((error) =>
95 toSourceStoreErrorFromLocalState("workspaces.upsert", error),
96 ),
97 );
98
99 const snapshot = Option.getOrNull(snapshotOption);
100 if (snapshot === null) {
101 return yield* toSourceStoreError(
102 "workspaces.upsert",
103 "Workspace snapshot not found",
104 null,
105 );
106 }
107
108 const now = Date.now();
109 const existingIndex = input.payload.id
110 ? snapshot.workspaces.findIndex((workspace) => workspace.id === input.payload.id)
111 : -1;
112 const existing = existingIndex >= 0 ? snapshot.workspaces[existingIndex] : null;
113
114 const nextWorkspace: Workspace = {
115 id: existing?.id ?? (input.payload.id ?? (`ws_${crypto.randomUUID()}` as Workspace["id"])),
116 organizationId: input.payload.organizationId,
117 name: input.payload.name,
118 createdByAccountId: existing?.createdByAccountId ?? null,
119 createdAt: existing?.createdAt ?? now,
120 updatedAt: now,
121 };
122
123 const nextSnapshot = existingIndex >= 0
124 ? replaceWorkspaceAt(snapshot, existingIndex, nextWorkspace)
125 : appendWorkspace(snapshot, nextWorkspace);
126
127 yield* localStateStore.writeSnapshot(nextSnapshot).pipe(
128 Effect.mapError((error) =>
129 toSourceStoreErrorFromLocalState("workspaces.upsert_write", error),
130 ),
131 );
132
133 return nextWorkspace;
134 }),
135 });
apps/pm/tsconfig.json+7−0
@@ -0,0 +1,7 @@
1{
2 "extends": "../../tsconfig.json",
3 "compilerOptions": {
4 "types": ["bun"]
5 },
6 "include": ["src"]
7}
apps/web/README.md+30−0
@@ -0,0 +1,30 @@
1# app-web
2
3Basic Next.js frontend for Executor v2 control plane.
4
5- Uses `@executor-v2/control-plane` Effect HttpApi client
6- Uses Effect Atom (`@effect-atom/atom`, `@effect-atom/atom-react`) for query state
7
8Run:
9
10- `bun run --cwd apps/web dev`
11- Open `http://127.0.0.1:3000`
12
13By default, control-plane API calls go directly to `http://127.0.0.1:8788`.
14Override with `NEXT_PUBLIC_CONTROL_PLANE_BASE_URL` (and optionally `CONTROL_PLANE_SERVER_BASE_URL` for SSR).
15
16MCP install URL generation:
17
18- Derives from existing control-plane/frontend config.
19- Prioritizes server-side `CONTROL_PLANE_UPSTREAM_URL` (or server/base control-plane URL) when available.
20- In local dev, defaults to direct Convex MCP URL: `http://127.0.0.1:8788/v1/mcp?...`
21
22WorkOS auth setup (optional but recommended):
23
24- `WORKOS_CLIENT_ID`
25- `WORKOS_API_KEY`
26- `WORKOS_COOKIE_PASSWORD` (32+ chars)
27- `WORKOS_REDIRECT_URI` or `NEXT_PUBLIC_WORKOS_REDIRECT_URI` (for example `http://localhost:4312/callback`)
28
29When WorkOS is configured, the app requires sign-in and forwards the authenticated WorkOS user id to control-plane as `x-executor-account-id`.
30For local non-WorkOS testing, you can still set `NEXT_PUBLIC_CONTROL_PLANE_ACCOUNT_ID` to send a static account id.
apps/web/agents.md+114−0
@@ -0,0 +1,114 @@
1# Effect Atom guide for `apps/web`
2
3This file defines how we write Effect Atom code in this app.
4
5## Goal
6
7Keep React components dumb. Put async/result orchestration in atoms, and render from typed state objects.
8
9## Hard rules
10
11- Do not create query atoms in render with `useMemo`.
12- Do not hand-roll `isLoading` / `hasError` booleans from `_tag` checks in components.
13- Do not manually mirror server state with React local state.
14- Prefer `Atom.family` + derived state atoms over component-level branching.
15
16## Baseline stack
17
18- `@effect-atom/atom`
19- `@effect-atom/atom-react`
20- `@executor-v2/control-plane` client (Effect HttpApi)
21
22## Recommended structure
23
24- `lib/control-plane/client.ts`
25 - Export one shared `createControlPlaneAtomClient(...)` instance.
26- `lib/control-plane/atoms.ts`
27 - Export query/mutation atoms and derived state atoms.
28- `app/.../page.tsx`
29 - Use `useAtomValue`, `useAtomSet`, and `useAtomRefresh`.
30 - Render from derived state atom output.
31
32## Preferred patterns
33
34### 1) Parametrized query atom with `Atom.family`
35
36Create once at module scope:
37
38```ts
39const sourcesResultByWorkspace = Atom.family((workspaceId: WorkspaceId) =>
40 controlPlaneClient.query("sources", "list", {
41 path: { workspaceId },
42 }),
43);
44```
45
46Then in component:
47
48```ts
49const result = useAtomValue(sourcesResultByWorkspace(workspaceId));
50```
51
52No `useMemo` needed.
53
54### 2) Derived state atom for UI projection
55
56Map `Result` once in atom-land:
57
58```ts
59const sourcesByWorkspace = Atom.family((workspaceId: WorkspaceId) =>
60 Atom.make((get) => {
61 const result = get(sourcesResultByWorkspace(workspaceId));
62 return Result.match(result, {
63 onInitial: () => ({ state: "loading" as const, items: [] as const, message: null }),
64 onFailure: (failure) => ({
65 state: "error" as const,
66 items: Option.getOrElse(Result.value(result), () => []),
67 message: Cause.pretty(failure.cause),
68 }),
69 onSuccess: (success) => ({
70 state: success.waiting ? ("refreshing" as const) : ("ready" as const),
71 items: success.value,
72 message: null,
73 }),
74 });
75 }),
76);
77```
78
79Components switch on `sources.state`, not raw result internals.
80
81### 3) Mutations as atoms
82
83Define mutation atoms once:
84
85```ts
86const upsertSource = controlPlaneClient.mutation("sources", "upsert");
87const removeSource = controlPlaneClient.mutation("sources", "remove");
88```
89
90In components, execute with `useAtomSet(..., { mode: "promise" })`, then refresh the related query atom.
91
92## React hooks usage
93
94- `useAtomValue(atom)` for reads.
95- `useAtomSet(writableAtom, { mode: "promise" })` for mutation execution.
96- `useAtomRefresh(atom)` for explicit refresh.
97- `useAtomSuspense(...)` is preferred when route is Suspense-driven.
98
99## Error formatting
100
101- Prefer `Cause.pretty(...)` for UI/debug text when surfacing failures.
102- Keep raw `Cause` in atom-derived state when useful; do not stringify ad-hoc in JSX.
103
104## Internal references
105
106- `@effect-atom/atom` d.ts: `dist/dts/Atom.d.ts`, `dist/dts/Result.d.ts`, `dist/dts/AtomHttpApi.d.ts`
107- `@effect-atom/atom-react` d.ts: `dist/dts/Hooks.d.ts`, `dist/dts/RegistryContext.d.ts`
108
109## Anti-pattern checklist (reject in review)
110
111- `useMemo(() => client.query(...), [deps])`
112- `const isLoading = result._tag === "Initial" || ...`
113- component-level `if/else` trees over raw `Result` in many places
114- duplicating remote state into `useState` unless it is true form draft state
apps/web/app/(console)/approvals/page.tsx+5−0
@@ -0,0 +1,5 @@
1import { ApprovalsView } from "../../../components/approvals/approvals-view";
2
3const ApprovalsPage = () => <ApprovalsView />;
4
5export default ApprovalsPage;
apps/web/app/(console)/console-shell.tsx+56−0
@@ -0,0 +1,56 @@
1"use client";
2
3import { memo, type ReactNode } from "react";
4import { useAtomValue } from "@effect-atom/atom-react";
5
6import { AppShell } from "../../components/shell/app-shell";
7import { WorkspaceProvider, useWorkspace } from "../../lib/hooks/use-workspace";
8import { approvalsByWorkspace } from "../../lib/control-plane/atoms";
9
10type ConsoleShellProps = {
11 authEnabled: boolean;
12 initialWorkspaceId: string;
13 children: ReactNode;
14};
15
16export function ConsoleShell({ authEnabled, initialWorkspaceId, children }: ConsoleShellProps) {
17 return (
18 <WorkspaceProvider initialWorkspaceId={initialWorkspaceId}>
19 <ConsoleShellInner authEnabled={authEnabled}>
20 {children}
21 </ConsoleShellInner>
22 </WorkspaceProvider>
23 );
24}
25
26function ConsoleShellInner({
27 authEnabled,
28 children,
29}: {
30 authEnabled: boolean;
31 children: ReactNode;
32}) {
33 return (
34 <AppShell
35 authEnabled={authEnabled}
36 approvalsBadge={<ApprovalsBadge />}
37 >
38 {children}
39 </AppShell>
40 );
41}
42
43/** Isolated subscription boundary: only this component re-renders when approvals change. */
44const ApprovalsBadge = memo(function ApprovalsBadge() {
45 const { workspaceId } = useWorkspace();
46 const approvalsState = useAtomValue(approvalsByWorkspace(workspaceId));
47 const pendingCount = approvalsState.items.filter((a) => a.status === "pending").length;
48
49 if (pendingCount === 0) return null;
50
51 return (
52 <span className="flex size-5 items-center justify-center rounded-full bg-primary/80 text-[10px] font-semibold text-primary-foreground">
53 {pendingCount}
54 </span>
55 );
56});
apps/web/app/(console)/credentials/page.tsx+5−0
@@ -0,0 +1,5 @@
1import { CredentialsView } from "../../../components/credentials/credentials-view";
2
3const CredentialsPage = () => <CredentialsView />;
4
5export default CredentialsPage;
apps/web/app/(console)/layout.tsx+42−0
@@ -0,0 +1,42 @@
1import { withAuth } from "@workos-inc/authkit-nextjs";
2import { redirect } from "next/navigation";
3import type { ReactNode } from "react";
4
5import { isWorkosEnabled } from "../../lib/workos";
6import { ConsoleShell } from "./console-shell";
7
8type ConsoleLayoutProps = {
9 children: ReactNode;
10};
11
12const ConsoleLayout = async ({ children }: ConsoleLayoutProps) => {
13 const authEnabled = isWorkosEnabled();
14
15 if (authEnabled) {
16 const { user } = await withAuth();
17
18 if (!user) {
19 redirect("/sign-in");
20 }
21
22 return (
23 <ConsoleShell
24 authEnabled
25 initialWorkspaceId={`ws_${user.id}`}
26 >
27 {children}
28 </ConsoleShell>
29 );
30 }
31
32 return (
33 <ConsoleShell
34 authEnabled={false}
35 initialWorkspaceId="ws_demo"
36 >
37 {children}
38 </ConsoleShell>
39 );
40};
41
42export default ConsoleLayout;
apps/web/app/(console)/policies/page.tsx+5−0
@@ -0,0 +1,5 @@
1import { PoliciesView } from "../../../components/policies/policies-view";
2
3const PoliciesPage = () => <PoliciesView />;
4
5export default PoliciesPage;
apps/web/app/(console)/settings/page.tsx+5−0
@@ -0,0 +1,5 @@
1import SettingsView from "../../../components/settings/settings-view";
2
3const SettingsPage = () => <SettingsView />;
4
5export default SettingsPage;
apps/web/app/(console)/storage/page.tsx+5−0
@@ -0,0 +1,5 @@
1import StorageView from "../../../components/storage/storage-view";
2
3const StoragePage = () => <StorageView />;
4
5export default StoragePage;
apps/web/app/(console)/tools/page.tsx+28−0
@@ -0,0 +1,28 @@
1import { ToolsView } from "../../../components/tools/tools-view";
2
3const resolveMcpBaseUrl = (): string | null => {
4 const candidates = [
5 process.env.CONTROL_PLANE_UPSTREAM_URL,
6 process.env.CONTROL_PLANE_SERVER_BASE_URL,
7 process.env.NEXT_PUBLIC_CONTROL_PLANE_BASE_URL,
8 ];
9
10 for (const candidate of candidates) {
11 const value = candidate?.trim();
12 if (!value) {
13 continue;
14 }
15
16 try {
17 return new URL(value).origin;
18 } catch {
19 // ignore invalid URL and continue
20 }
21 }
22
23 return null;
24};
25
26const ToolsPage = () => <ToolsView mcpBaseUrl={resolveMcpBaseUrl()} />;
27
28export default ToolsPage;
apps/web/app/callback/route.ts+11−0
@@ -0,0 +1,11 @@
1import type { NextRequest } from "next/server";
2import { handleAuth } from "@workos-inc/authkit-nextjs";
3
4import { externalOriginFromRequest } from "../../lib/workos";
5
6export async function GET(request: NextRequest): Promise<Response> {
7 return handleAuth({
8 baseURL: externalOriginFromRequest(request),
9 returnPathname: "/",
10 })(request);
11}
apps/web/app/globals.css+127−0
@@ -0,0 +1,127 @@
1@import "tailwindcss";
2@import "tw-animate-css";
3
4@custom-variant dark (&:is(.dark *));
5
6@theme inline {
7 --font-sans: var(--font-body), "IBM Plex Sans", ui-sans-serif, sans-serif;
8 --font-mono: "IBM Plex Mono", ui-monospace, monospace;
9 --font-display: var(--font-display), "Fraunces", serif;
10
11 --color-background: var(--background);
12 --color-foreground: var(--foreground);
13 --color-card: var(--card);
14 --color-card-foreground: var(--card-foreground);
15 --color-popover: var(--popover);
16 --color-popover-foreground: var(--popover-foreground);
17 --color-primary: var(--primary);
18 --color-primary-foreground: var(--primary-foreground);
19 --color-secondary: var(--secondary);
20 --color-secondary-foreground: var(--secondary-foreground);
21 --color-muted: var(--muted);
22 --color-muted-foreground: var(--muted-foreground);
23 --color-accent: var(--accent);
24 --color-accent-foreground: var(--accent-foreground);
25 --color-destructive: var(--destructive);
26 --color-border: var(--border);
27 --color-input: var(--input);
28 --color-ring: var(--ring);
29
30 --color-sidebar: var(--sidebar);
31 --color-sidebar-foreground: var(--sidebar-foreground);
32 --color-sidebar-border: var(--sidebar-border);
33 --color-sidebar-active: var(--sidebar-active);
34}
35
36:root {
37 --background: oklch(0.985 0.002 260);
38 --foreground: oklch(0.18 0.01 260);
39 --card: oklch(1 0 0);
40 --card-foreground: oklch(0.18 0.01 260);
41 --popover: oklch(1 0 0);
42 --popover-foreground: oklch(0.18 0.01 260);
43 --primary: oklch(0.45 0.18 155);
44 --primary-foreground: oklch(0.98 0.005 155);
45 --secondary: oklch(0.95 0.005 260);
46 --secondary-foreground: oklch(0.30 0.01 260);
47 --muted: oklch(0.94 0.005 260);
48 --muted-foreground: oklch(0.45 0.01 260);
49 --accent: oklch(0.94 0.008 260);
50 --accent-foreground: oklch(0.18 0.01 260);
51 --destructive: oklch(0.55 0.22 25);
52 --border: oklch(0.88 0.008 260);
53 --input: oklch(0.88 0.008 260);
54 --ring: oklch(0.45 0.18 155);
55
56 --sidebar: oklch(0.97 0.004 260);
57 --sidebar-foreground: oklch(0.30 0.01 260);
58 --sidebar-border: oklch(0.88 0.008 260);
59 --sidebar-active: oklch(0.93 0.01 260);
60
61 --shiki-light: #24292e;
62 --shiki-light-bg: #ffffff;
63 --shiki-dark: #e1e4e8;
64 --shiki-dark-bg: #0d1117;
65}
66
67.dark {
68 --background: oklch(0.11 0.005 260);
69 --foreground: oklch(0.88 0.01 250);
70 --card: oklch(0.15 0.005 260);
71 --card-foreground: oklch(0.88 0.01 250);
72 --popover: oklch(0.15 0.005 260);
73 --popover-foreground: oklch(0.88 0.01 250);
74 --primary: oklch(0.75 0.18 155);
75 --primary-foreground: oklch(0.13 0.01 155);
76 --secondary: oklch(0.2 0.008 260);
77 --secondary-foreground: oklch(0.75 0.01 250);
78 --muted: oklch(0.18 0.005 260);
79 --muted-foreground: oklch(0.55 0.01 250);
80 --accent: oklch(0.2 0.01 260);
81 --accent-foreground: oklch(0.88 0.01 250);
82 --destructive: oklch(0.65 0.22 25);
83 --border: oklch(0.24 0.008 260);
84 --input: oklch(0.2 0.008 260);
85 --ring: oklch(0.75 0.18 155);
86
87 --sidebar: oklch(0.13 0.005 260);
88 --sidebar-foreground: oklch(0.75 0.01 250);
89 --sidebar-border: oklch(0.22 0.008 260);
90 --sidebar-active: oklch(0.2 0.01 260);
91}
92
93@layer base {
94 * {
95 @apply border-border;
96 }
97
98 html,
99 body {
100 min-height: 100%;
101 }
102
103 body {
104 @apply bg-background font-sans text-foreground antialiased;
105 }
106}
107
108[style*="--shiki-light"] {
109 color: var(--shiki-light) !important;
110 background-color: transparent !important;
111}
112
113.dark [style*="--shiki-dark"] {
114 color: var(--shiki-dark) !important;
115 background-color: transparent !important;
116}
117
118.dark [style*="--shiki-light"] {
119 color: var(--shiki-dark) !important;
120 background-color: transparent !important;
121}
122
123[data-streamdown="code-block-body"] {
124 background-color: var(--muted) !important;
125 border: 1px solid var(--border);
126 border-radius: 0.375rem;
127}
apps/web/app/layout.tsx+38−0
@@ -0,0 +1,38 @@
1import type { Metadata } from "next";
2import { Fraunces, IBM_Plex_Sans } from "next/font/google";
3import type { ReactNode } from "react";
4
5import { Providers } from "./providers";
6import "./globals.css";
7
8const bodyFont = IBM_Plex_Sans({
9 subsets: ["latin"],
10 variable: "--font-body",
11 weight: ["400", "500", "600"],
12});
13
14const displayFont = Fraunces({
15 subsets: ["latin"],
16 variable: "--font-display",
17 weight: ["500", "700"],
18});
19
20export const metadata: Metadata = {
21 title: "Executor v2 Control Plane",
22 description: "Basic Next.js frontend for Executor v2 control plane",
23};
24
25type RootLayoutProps = {
26 children: ReactNode;
27};
28
29const RootLayout = ({ children }: RootLayoutProps) => (
30 <html lang="en" suppressHydrationWarning className={`${bodyFont.variable} ${displayFont.variable}`}>
31 <body className="antialiased">
32 <Providers>{children}</Providers>
33 </body>
34 </html>
35);
36
37
38export default RootLayout;
apps/web/app/mcp/oauth/callback/route.ts+169−0
@@ -0,0 +1,169 @@
1import { auth } from "@modelcontextprotocol/sdk/client/auth.js";
2import type { NextRequest } from "next/server";
3import { NextResponse } from "next/server";
4
5import { fetchMcpOAuth } from "../../../../lib/mcp/oauth-fetch";
6import { getExternalOrigin, isExternalHttps } from "../../../../lib/mcp/oauth-request";
7import { parseMcpSourceUrl } from "../../../../lib/mcp/oauth-url";
8import {
9 buildPendingCookieName,
10 decodePendingCookieValue,
11 encodePopupResultCookieValue,
12 MCP_OAUTH_RESULT_COOKIE,
13 McpPopupOAuthProvider,
14 type McpOAuthPopupResult,
15} from "../../../../lib/mcp/oauth-provider";
16
17const MCP_OAUTH_CALLBACK_FLOW_TIMEOUT_MS = 75_000;
18const MCP_OAUTH_CALLBACK_REQUEST_TIMEOUT_MS = 20_000;
19
20const withTimeout = async <T>(
21 factory: () => Promise<T>,
22 timeoutMs: number,
23 label: string,
24): Promise<T> =>
25 await new Promise<T>((resolve, reject) => {
26 const timeoutId = setTimeout(() => {
27 reject(new Error(`${label} timed out after ${timeoutMs}ms`));
28 }, timeoutMs);
29
30 factory().then(
31 (value) => {
32 clearTimeout(timeoutId);
33 resolve(value);
34 },
35 (error) => {
36 clearTimeout(timeoutId);
37 reject(error);
38 },
39 );
40 });
41
42const popupResultRedirect = (
43 request: NextRequest,
44 pendingCookieName: string | null,
45 payload: McpOAuthPopupResult,
46): Response => {
47 const origin = getExternalOrigin(request);
48 const response = NextResponse.redirect(new URL("/mcp/oauth/complete", origin));
49
50 response.cookies.set({
51 name: MCP_OAUTH_RESULT_COOKIE,
52 value: encodePopupResultCookieValue(payload),
53 httpOnly: true,
54 secure: isExternalHttps(request),
55 sameSite: "lax",
56 maxAge: 2 * 60,
57 path: "/",
58 });
59
60 if (pendingCookieName) {
61 response.cookies.set({
62 name: pendingCookieName,
63 value: "",
64 expires: new Date(0),
65 path: "/",
66 });
67 }
68
69 return response;
70};
71
72const toErrorMessage = (error: unknown, fallback: string): string =>
73 error instanceof Error ? error.message : fallback;
74
75export async function GET(request: NextRequest): Promise<Response> {
76 const code = request.nextUrl.searchParams.get("code")?.trim() ?? "";
77 const state = request.nextUrl.searchParams.get("state")?.trim() ?? "";
78 const oauthError = request.nextUrl.searchParams.get("error")?.trim() ?? "";
79
80 if (!state) {
81 return popupResultRedirect(request, null, {
82 ok: false,
83 error: "Missing OAuth state",
84 });
85 }
86
87 const pendingCookieName = buildPendingCookieName(state);
88 const rawPending = request.cookies.get(pendingCookieName)?.value ?? "";
89 const pending = rawPending ? decodePendingCookieValue(rawPending) : null;
90
91 if (!pending) {
92 return popupResultRedirect(request, pendingCookieName, {
93 ok: false,
94 error: "OAuth session expired. Try connecting again.",
95 });
96 }
97
98 if (oauthError.length > 0) {
99 return popupResultRedirect(request, pendingCookieName, {
100 ok: false,
101 error: `OAuth error: ${oauthError}`,
102 });
103 }
104
105 if (code.length === 0) {
106 return popupResultRedirect(request, pendingCookieName, {
107 ok: false,
108 error: "Missing OAuth authorization code",
109 });
110 }
111
112 let sourceUrl: URL;
113 try {
114 sourceUrl = parseMcpSourceUrl(pending.sourceUrl);
115 } catch {
116 return popupResultRedirect(request, pendingCookieName, {
117 ok: false,
118 error: "Invalid MCP source URL",
119 });
120 }
121
122 const provider = new McpPopupOAuthProvider({
123 redirectUrl: pending.redirectUrl,
124 state: pending.state,
125 codeVerifier: pending.codeVerifier,
126 clientInformation: pending.clientInformation,
127 });
128
129 try {
130 await withTimeout(
131 () =>
132 auth(provider, {
133 serverUrl: sourceUrl,
134 authorizationCode: code,
135 fetchFn: (input, init) =>
136 fetchMcpOAuth(input, init ?? {}, {
137 timeoutMs: MCP_OAUTH_CALLBACK_REQUEST_TIMEOUT_MS,
138 label: "OAuth callback request",
139 }),
140 }),
141 MCP_OAUTH_CALLBACK_FLOW_TIMEOUT_MS,
142 "OAuth callback",
143 );
144 } catch (error) {
145 return popupResultRedirect(request, pendingCookieName, {
146 ok: false,
147 error: toErrorMessage(error, "Failed to finish OAuth"),
148 });
149 }
150
151 const tokens = provider.getTokens();
152 const accessToken = tokens?.access_token?.trim() ?? "";
153
154 if (accessToken.length === 0) {
155 return popupResultRedirect(request, pendingCookieName, {
156 ok: false,
157 error: "OAuth completed without an access token",
158 });
159 }
160
161 return popupResultRedirect(request, pendingCookieName, {
162 ok: true,
163 sourceUrl: pending.sourceUrl,
164 accessToken,
165 refreshToken: tokens?.refresh_token,
166 scope: tokens?.scope,
167 expiresIn: typeof tokens?.expires_in === "number" ? tokens.expires_in : undefined,
168 });
169}
apps/web/app/mcp/oauth/complete/page.tsx+86−0
@@ -0,0 +1,86 @@
1"use client";
2
3import { useEffect, useRef, useState } from "react";
4
5type PopupMessage =
6 | {
7 type: "executor-v2:mcp-oauth-result";
8 ok: true;
9 sourceUrl: string;
10 payload: {
11 accessToken: string;
12 refreshToken?: string;
13 scope?: string;
14 expiresIn?: number;
15 };
16 }
17 | {
18 type: "executor-v2:mcp-oauth-result";
19 ok: false;
20 error: string;
21 };
22
23const fallbackErrorMessage = (error: unknown): PopupMessage => ({
24 type: "executor-v2:mcp-oauth-result",
25 ok: false,
26 error: error instanceof Error ? error.message : "Failed to finalize OAuth",
27});
28
29const fetchPopupResult = async (): Promise<PopupMessage> => {
30 const response = await fetch("/mcp/oauth/result", {
31 method: "GET",
32 cache: "no-store",
33 credentials: "same-origin",
34 });
35
36 const data = (await response.json()) as PopupMessage;
37 if (!data || data.type !== "executor-v2:mcp-oauth-result") {
38 throw new Error("Invalid OAuth completion payload");
39 }
40
41 return data;
42};
43
44export default function McpOAuthCompletePage() {
45 const sentRef = useRef(false);
46 const [statusText, setStatusText] = useState("Finishing OAuth");
47
48 useEffect(() => {
49 if (sentRef.current) {
50 return;
51 }
52
53 sentRef.current = true;
54
55 void fetchPopupResult()
56 .then((message) => {
57 setStatusText("OAuth complete");
58
59 if (window.opener) {
60 window.opener.postMessage(message, window.location.origin);
61 }
62 })
63 .catch((error) => {
64 const message = fallbackErrorMessage(error);
65 setStatusText("OAuth failed");
66
67 if (window.opener) {
68 window.opener.postMessage(message, window.location.origin);
69 }
70 })
71 .finally(() => {
72 window.close();
73 });
74 }, []);
75
76 return (
77 <main className="min-h-screen flex items-center justify-center bg-background p-6">
78 <div className="text-center space-y-2">
79 <h1 className="text-base font-medium">{statusText}</h1>
80 <p className="text-sm text-muted-foreground">
81 You can close this window if it does not close automatically.
82 </p>
83 </div>
84 </main>
85 );
86}
apps/web/app/mcp/oauth/detect/route.ts+178−0
@@ -0,0 +1,178 @@
1import { discoverOAuthProtectedResourceMetadata, extractWWWAuthenticateParams } from "@modelcontextprotocol/sdk/client/auth.js";
2import { LATEST_PROTOCOL_VERSION } from "@modelcontextprotocol/sdk/types.js";
3
4import { fetchMcpOAuth } from "../../../../lib/mcp/oauth-fetch";
5import { parseMcpSourceUrl } from "../../../../lib/mcp/oauth-url";
6
7type DetectResponse = {
8 oauth: boolean;
9 authorizationServers: Array<string>;
10 detail?: string;
11};
12
13const MCP_OAUTH_CHALLENGE_PROBE_TIMEOUT_MS = 2_500;
14const MCP_OAUTH_METADATA_TIMEOUT_MS = 12_000;
15
16const noStoreDetectJson = (payload: DetectResponse, status = 200): Response =>
17 Response.json(payload, {
18 status,
19 headers: {
20 "cache-control": "no-store",
21 },
22 });
23
24const withTimeout = async <T>(
25 factory: () => Promise<T>,
26 timeoutMs: number,
27 label: string,
28): Promise<T> =>
29 await new Promise<T>((resolve, reject) => {
30 const timeoutId = setTimeout(() => {
31 reject(new Error(`${label} timed out after ${timeoutMs}ms`));
32 }, timeoutMs);
33
34 factory().then(
35 (value) => {
36 clearTimeout(timeoutId);
37 resolve(value);
38 },
39 (error) => {
40 clearTimeout(timeoutId);
41 reject(error);
42 },
43 );
44 });
45
46const probeOAuthChallenge = async (sourceUrl: URL): Promise<boolean> => {
47 const response = await fetchMcpOAuth(
48 sourceUrl,
49 {
50 method: "POST",
51 headers: {
52 "content-type": "application/json",
53 accept: "application/json, text/event-stream",
54 "mcp-protocol-version": LATEST_PROTOCOL_VERSION,
55 },
56 body: JSON.stringify({
57 jsonrpc: "2.0",
58 id: "oauth-detect",
59 method: "initialize",
60 params: {
61 protocolVersion: LATEST_PROTOCOL_VERSION,
62 capabilities: {},
63 clientInfo: {
64 name: "Executor v2 OAuth Detector",
65 version: "1.0.0",
66 },
67 },
68 }),
69 },
70 {
71 timeoutMs: MCP_OAUTH_CHALLENGE_PROBE_TIMEOUT_MS,
72 label: "OAuth challenge probe",
73 },
74 );
75
76 const hasBearerChallenge = /^Bearer\s/i.test(
77 response.headers.get("WWW-Authenticate") ?? "",
78 );
79 const challenge = extractWWWAuthenticateParams(response);
80
81 await response.body?.cancel();
82
83 if ((response.status === 401 || response.status === 403) && hasBearerChallenge) {
84 return true;
85 }
86
87 return Boolean(challenge.resourceMetadataUrl);
88};
89
90const toErrorDetail = (error: unknown, fallback: string): string =>
91 error instanceof Error ? error.message : fallback;
92
93export async function GET(request: Request): Promise<Response> {
94 const requestUrl = new URL(request.url);
95 const sourceUrlRaw = requestUrl.searchParams.get("sourceUrl")?.trim() ?? "";
96
97 if (!sourceUrlRaw) {
98 return noStoreDetectJson(
99 {
100 oauth: false,
101 authorizationServers: [],
102 detail: "Missing sourceUrl",
103 },
104 400,
105 );
106 }
107
108 let sourceUrl: URL;
109 try {
110 sourceUrl = parseMcpSourceUrl(sourceUrlRaw);
111 } catch (error) {
112 return noStoreDetectJson(
113 {
114 oauth: false,
115 authorizationServers: [],
116 detail: toErrorDetail(error, "Invalid sourceUrl"),
117 },
118 400,
119 );
120 }
121
122 try {
123 const oauthByChallenge = await probeOAuthChallenge(sourceUrl);
124 if (oauthByChallenge) {
125 return noStoreDetectJson({
126 oauth: true,
127 authorizationServers: [],
128 detail: "OAuth detected from endpoint challenge",
129 });
130 }
131 } catch {
132 // Continue to metadata discovery.
133 }
134
135 let metadata: unknown;
136 try {
137 metadata = await withTimeout(
138 () =>
139 discoverOAuthProtectedResourceMetadata(
140 sourceUrl,
141 undefined,
142 (input, init) =>
143 fetchMcpOAuth(input, init ?? {}, {
144 timeoutMs: MCP_OAUTH_METADATA_TIMEOUT_MS,
145 label: "OAuth metadata lookup",
146 }),
147 ),
148 MCP_OAUTH_METADATA_TIMEOUT_MS,
149 "OAuth metadata lookup",
150 );
151 } catch (error) {
152 return noStoreDetectJson(
153 {
154 oauth: false,
155 authorizationServers: [],
156 detail: toErrorDetail(error, "OAuth metadata lookup failed"),
157 },
158 502,
159 );
160 }
161
162 const authorizationServersRaw =
163 metadata && typeof metadata === "object" && !Array.isArray(metadata)
164 ? (metadata as { authorization_servers?: unknown }).authorization_servers
165 : undefined;
166
167 const authorizationServers = Array.isArray(authorizationServersRaw)
168 ? authorizationServersRaw
169 .filter((entry): entry is string => typeof entry === "string")
170 .map((entry) => entry.trim())
171 .filter((entry) => entry.length > 0)
172 : [];
173
174 return noStoreDetectJson({
175 oauth: authorizationServers.length > 0,
176 authorizationServers,
177 });
178}
apps/web/app/mcp/oauth/result/route.ts+89−0
@@ -0,0 +1,89 @@
1import type { NextRequest } from "next/server";
2import { NextResponse } from "next/server";
3
4import {
5 decodePopupResultCookieValue,
6 MCP_OAUTH_RESULT_COOKIE,
7 type McpOAuthPopupResult,
8} from "../../../../lib/mcp/oauth-provider";
9
10type PopupMessage =
11 | {
12 type: "executor-v2:mcp-oauth-result";
13 ok: true;
14 sourceUrl: string;
15 payload: {
16 accessToken: string;
17 refreshToken?: string;
18 scope?: string;
19 expiresIn?: number;
20 };
21 }
22 | {
23 type: "executor-v2:mcp-oauth-result";
24 ok: false;
25 error: string;
26 };
27
28const toPopupMessage = (result: McpOAuthPopupResult | null): PopupMessage => {
29 if (!result) {
30 return {
31 type: "executor-v2:mcp-oauth-result",
32 ok: false,
33 error: "OAuth result is missing or expired",
34 };
35 }
36
37 if (!result.ok) {
38 return {
39 type: "executor-v2:mcp-oauth-result",
40 ok: false,
41 error: result.error ?? "OAuth failed",
42 };
43 }
44
45 const accessToken = result.accessToken?.trim() ?? "";
46 if (accessToken.length === 0) {
47 return {
48 type: "executor-v2:mcp-oauth-result",
49 ok: false,
50 error: "OAuth finished without an access token",
51 };
52 }
53
54 return {
55 type: "executor-v2:mcp-oauth-result",
56 ok: true,
57 sourceUrl: result.sourceUrl ?? "",
58 payload: {
59 accessToken,
60 ...(result.refreshToken ? { refreshToken: result.refreshToken } : {}),
61 ...(result.scope ? { scope: result.scope } : {}),
62 ...(typeof result.expiresIn === "number"
63 ? { expiresIn: result.expiresIn }
64 : {}),
65 },
66 };
67};
68
69export async function GET(request: NextRequest): Promise<Response> {
70 const encoded = request.cookies.get(MCP_OAUTH_RESULT_COOKIE)?.value ?? "";
71 const parsed = encoded ? decodePopupResultCookieValue(encoded) : null;
72 const message = toPopupMessage(parsed);
73
74 const response = NextResponse.json(message, {
75 status: message.ok ? 200 : 400,
76 headers: {
77 "cache-control": "no-store",
78 },
79 });
80
81 response.cookies.set({
82 name: MCP_OAUTH_RESULT_COOKIE,
83 value: "",
84 expires: new Date(0),
85 path: "/",
86 });
87
88 return response;
89}
apps/web/app/mcp/oauth/start/route.ts+152−0
@@ -0,0 +1,152 @@
1import { auth } from "@modelcontextprotocol/sdk/client/auth.js";
2import type { NextRequest } from "next/server";
3import { NextResponse } from "next/server";
4
5import { fetchMcpOAuth } from "../../../../lib/mcp/oauth-fetch";
6import { getExternalOrigin, isExternalHttps } from "../../../../lib/mcp/oauth-request";
7import { parseMcpSourceUrl } from "../../../../lib/mcp/oauth-url";
8import {
9 buildPendingCookieName,
10 createOAuthState,
11 encodePendingCookieValue,
12 encodePopupResultCookieValue,
13 MCP_OAUTH_RESULT_COOKIE,
14 McpPopupOAuthProvider,
15 type McpOAuthPopupResult,
16} from "../../../../lib/mcp/oauth-provider";
17
18const MCP_OAUTH_FLOW_TIMEOUT_MS = 75_000;
19const MCP_OAUTH_REQUEST_TIMEOUT_MS = 20_000;
20
21const withTimeout = async <T>(
22 factory: () => Promise<T>,
23 timeoutMs: number,
24 label: string,
25): Promise<T> =>
26 await new Promise<T>((resolve, reject) => {
27 const timeoutId = setTimeout(() => {
28 reject(new Error(`${label} timed out after ${timeoutMs}ms`));
29 }, timeoutMs);
30
31 factory().then(
32 (value) => {
33 clearTimeout(timeoutId);
34 resolve(value);
35 },
36 (error) => {
37 clearTimeout(timeoutId);
38 reject(error);
39 },
40 );
41 });
42
43const popupResultRedirect = (
44 request: NextRequest,
45 payload: McpOAuthPopupResult,
46): Response => {
47 const origin = getExternalOrigin(request);
48 const response = NextResponse.redirect(new URL("/mcp/oauth/complete", origin));
49
50 response.cookies.set({
51 name: MCP_OAUTH_RESULT_COOKIE,
52 value: encodePopupResultCookieValue(payload),
53 httpOnly: true,
54 secure: isExternalHttps(request),
55 sameSite: "lax",
56 maxAge: 2 * 60,
57 path: "/",
58 });
59
60 return response;
61};
62
63const badPopupResponse = (request: NextRequest, message: string): Response =>
64 popupResultRedirect(request, { ok: false, error: message });
65
66const toErrorMessage = (error: unknown, fallback: string): string =>
67 error instanceof Error ? error.message : fallback;
68
69export async function GET(request: NextRequest): Promise<Response> {
70 const sourceUrlRaw = request.nextUrl.searchParams.get("sourceUrl")?.trim() ?? "";
71 if (sourceUrlRaw.length === 0) {
72 return badPopupResponse(request, "Missing sourceUrl");
73 }
74
75 let sourceUrl: URL;
76 try {
77 sourceUrl = parseMcpSourceUrl(sourceUrlRaw);
78 } catch (error) {
79 return badPopupResponse(request, toErrorMessage(error, "Invalid sourceUrl"));
80 }
81
82 const state = createOAuthState();
83 const redirectUrl = `${getExternalOrigin(request)}/mcp/oauth/callback`;
84 const provider = new McpPopupOAuthProvider({
85 redirectUrl,
86 state,
87 });
88
89 let authResult: "AUTHORIZED" | "REDIRECT";
90 try {
91 authResult = await withTimeout(
92 () =>
93 auth(provider, {
94 serverUrl: sourceUrl,
95 fetchFn: (input, init) =>
96 fetchMcpOAuth(input, init ?? {}, {
97 timeoutMs: MCP_OAUTH_REQUEST_TIMEOUT_MS,
98 label: "OAuth startup request",
99 }),
100 }),
101 MCP_OAUTH_FLOW_TIMEOUT_MS,
102 "OAuth startup",
103 );
104 } catch (error) {
105 return badPopupResponse(
106 request,
107 toErrorMessage(error, "Failed to start OAuth flow"),
108 );
109 }
110
111 if (authResult === "AUTHORIZED") {
112 const tokens = provider.getTokens();
113 const accessToken = tokens?.access_token?.trim() ?? "";
114 if (accessToken.length === 0) {
115 return badPopupResponse(
116 request,
117 "OAuth flow completed without an access token",
118 );
119 }
120
121 return popupResultRedirect(request, {
122 ok: true,
123 sourceUrl: sourceUrl.toString(),
124 accessToken,
125 refreshToken: tokens?.refresh_token,
126 scope: tokens?.scope,
127 expiresIn:
128 typeof tokens?.expires_in === "number" ? tokens.expires_in : undefined,
129 });
130 }
131
132 const authorizationUrl = provider.getAuthorizationUrl();
133 if (!authorizationUrl) {
134 return badPopupResponse(
135 request,
136 "Server did not request an OAuth authorization step",
137 );
138 }
139
140 const response = NextResponse.redirect(authorizationUrl);
141 response.cookies.set({
142 name: buildPendingCookieName(state),
143 value: encodePendingCookieValue(provider.toPending(sourceUrl.toString())),
144 httpOnly: true,
145 secure: isExternalHttps(request),
146 sameSite: "lax",
147 maxAge: 10 * 60,
148 path: "/",
149 });
150
151 return response;
152}
apps/web/app/page.tsx+7−0
@@ -0,0 +1,7 @@
1import { redirect } from "next/navigation";
2
3const Page = () => {
4 redirect("/tools");
5};
6
7export default Page;
apps/web/app/providers.tsx+20−0
@@ -0,0 +1,20 @@
1"use client";
2
3import { RegistryProvider } from "@effect-atom/atom-react";
4import { ThemeProvider } from "next-themes";
5import type { ReactNode } from "react";
6
7type ProvidersProps = {
8 children: ReactNode;
9};
10
11export const Providers = ({ children }: ProvidersProps) => (
12 <ThemeProvider
13 attribute="class"
14 defaultTheme="dark"
15 enableSystem
16 enableColorScheme
17 >
18 <RegistryProvider>{children}</RegistryProvider>
19 </ThemeProvider>
20);
apps/web/app/sign-in/route.ts+22−0
@@ -0,0 +1,22 @@
1import type { NextRequest } from "next/server";
2import { NextResponse } from "next/server";
3import { getSignInUrl } from "@workos-inc/authkit-nextjs";
4
5import { isWorkosEnabled, resolveWorkosRedirectUri } from "../../lib/workos";
6
7export async function GET(request: NextRequest): Promise<Response> {
8 if (!isWorkosEnabled()) {
9 return NextResponse.redirect(new URL("/", request.url));
10 }
11
12 const redirectUri = resolveWorkosRedirectUri(request);
13 if (!redirectUri) {
14 return NextResponse.redirect(new URL("/", request.url));
15 }
16
17 const signInUrl = await getSignInUrl({
18 redirectUri,
19 });
20
21 return NextResponse.redirect(signInUrl);
22}
apps/web/app/sign-out/route.ts+17−0
@@ -0,0 +1,17 @@
1import type { NextRequest } from "next/server";
2import { NextResponse } from "next/server";
3import { signOut } from "@workos-inc/authkit-nextjs";
4
5import { externalOriginFromRequest, isWorkosEnabled } from "../../lib/workos";
6
7export async function GET(request: NextRequest): Promise<Response> {
8 if (!isWorkosEnabled()) {
9 return NextResponse.redirect(new URL("/", request.url));
10 }
11
12 await signOut({
13 returnTo: `${externalOriginFromRequest(request)}/`,
14 });
15
16 return NextResponse.redirect(new URL("/", request.url));
17}
apps/web/components.json+20−0
@@ -0,0 +1,20 @@
1{
2 "$schema": "https://ui.shadcn.com/schema.json",
3 "style": "new-york",
4 "rsc": true,
5 "tsx": true,
6 "tailwind": {
7 "config": "",
8 "css": "app/globals.css",
9 "baseColor": "neutral",
10 "cssVariables": true,
11 "prefix": ""
12 },
13 "iconLibrary": "lucide",
14 "aliases": {
15 "components": "./components",
16 "utils": "./lib/utils",
17 "ui": "./components/ui",
18 "lib": "./lib"
19 }
20}
apps/web/components/approvals/approvals-view.tsx+284−0
@@ -0,0 +1,284 @@
1"use client";
2
3import { useAtomSet, useAtomValue } from "@effect-atom/atom-react";
4import type { Approval, ApprovalId } from "@executor-v2/schema";
5import { useMemo, useState } from "react";
6
7import { useWorkspace } from "../../lib/hooks/use-workspace";
8import {
9 approvalsByWorkspace,
10 optimisticResolveApproval,
11 resolveApproval,
12} from "../../lib/control-plane/atoms";
13import { Button } from "../ui/button";
14import {
15 Card,
16 CardContent,
17 CardDescription,
18 CardHeader,
19 CardTitle,
20} from "../ui/card";
21import { Input } from "../ui/input";
22import { Select } from "../ui/select";
23import { Badge } from "../ui/badge";
24import { cn, formatTimestamp } from "../../lib/utils";
25import { matchState } from "../shared/match-state";
26import { PageHeader } from "../shared/page-header";
27import { StatusMessage } from "../shared/status-message";
28
29type ApprovalFilterValue = "pending" | "resolved" | "all";
30
31const statusBadgeVariant = (
32 status: Approval["status"],
33): "pending" | "approved" | "denied" | "outline" => {
34 if (status === "pending") {
35 return "pending";
36 }
37
38 if (status === "approved") {
39 return "approved";
40 }
41
42 if (status === "denied") {
43 return "denied";
44 }
45
46 return "outline";
47};
48
49const previewFromInputJson = (inputPreviewJson: string): string => {
50 const trimmed = inputPreviewJson.trim();
51
52 if (trimmed.length === 0) {
53 return "{}";
54 }
55
56 try {
57 const parsed = JSON.parse(trimmed) as unknown;
58 const pretty = JSON.stringify(parsed, null, 2);
59 return pretty.length > 640 ? `${pretty.slice(0, 640)}\n...` : pretty;
60 } catch {
61 return trimmed.length > 640 ? `${trimmed.slice(0, 640)}...` : trimmed;
62 }
63};
64
65export function usePendingApprovalCount(): number {
66 const { workspaceId } = useWorkspace();
67 const approvalsState = useAtomValue(approvalsByWorkspace(workspaceId));
68
69 return approvalsState.items.filter((approval) => approval.status === "pending").length;
70}
71
72export function ApprovalsView() {
73 const { workspaceId } = useWorkspace();
74
75 const [approvalFilter, setApprovalFilter] = useState<ApprovalFilterValue>("pending");
76 const [approvalSearchQuery, setApprovalSearchQuery] = useState("");
77 const [approvalStatusText, setApprovalStatusText] = useState<string | null>(null);
78 const [approvalStatusVariant, setApprovalStatusVariant] = useState<"info" | "error">("info");
79 const [approvalBusyId, setApprovalBusyId] = useState<ApprovalId | null>(null);
80 const [optimisticApprovals, setOptimisticApprovals] = useState<
81 ReadonlyArray<Approval> | null
82 >(null);
83
84 const approvalsState = useAtomValue(approvalsByWorkspace(workspaceId));
85 const runResolveApproval = useAtomSet(resolveApproval, { mode: "promise" });
86
87 const approvalItems = optimisticApprovals ?? approvalsState.items;
88
89 const filteredApprovals = useMemo(() => {
90 const query = approvalSearchQuery.trim().toLowerCase();
91
92 return approvalItems.filter((approval) => {
93 if (approvalFilter === "pending" && approval.status !== "pending") {
94 return false;
95 }
96
97 if (
98 approvalFilter === "resolved" &&
99 (approval.status === "pending" || approval.status === "expired")
100 ) {
101 return false;
102 }
103
104 if (query.length === 0) {
105 return true;
106 }
107
108 return (
109 approval.toolPath.toLowerCase().includes(query) ||
110 approval.status.toLowerCase().includes(query) ||
111 approval.callId.toLowerCase().includes(query) ||
112 approval.taskRunId.toLowerCase().includes(query) ||
113 (approval.reason ?? "").toLowerCase().includes(query)
114 );
115 });
116 }, [approvalFilter, approvalItems, approvalSearchQuery]);
117
118 const setStatus = (message: string | null, variant: "info" | "error" = "info") => {
119 setApprovalStatusText(message);
120 setApprovalStatusVariant(variant);
121 };
122
123 const handleResolveApproval = (approvalId: ApprovalId, status: "approved" | "denied") => {
124 if (approvalBusyId !== null) {
125 return;
126 }
127
128 setApprovalBusyId(approvalId);
129
130 const nextOptimistic = optimisticResolveApproval(approvalItems, {
131 approvalId,
132 payload: {
133 status,
134 reason: null,
135 },
136 });
137
138 setOptimisticApprovals(nextOptimistic);
139
140 void runResolveApproval({
141 path: {
142 workspaceId,
143 approvalId,
144 },
145 payload: {
146 status,
147 reason: null,
148 },
149 })
150 .then(() => {
151 setStatus(status === "approved" ? "Approval granted." : "Approval denied.");
152 setOptimisticApprovals(null);
153 })
154 .catch(() => {
155 setStatus("Approval update failed.", "error");
156 setOptimisticApprovals(null);
157 })
158 .finally(() => {
159 setApprovalBusyId(null);
160 });
161 };
162
163 return (
164 <section className="mx-auto flex w-full max-w-5xl flex-col gap-4">
165 <PageHeader title="Approvals" description="Review and resolve tool-call approvals." />
166
167 <Card className="border-border/70">
168 <CardHeader className="pb-3">
169 <CardTitle>Approval Requests</CardTitle>
170 <CardDescription>Manage request status and inspect input previews.</CardDescription>
171 </CardHeader>
172
173 <CardContent className="space-y-4">
174 <div className="grid gap-3 sm:grid-cols-2">
175 <div className="grid gap-1.5">
176 <label className="text-xs text-muted-foreground" htmlFor="approval-filter">
177 Filter
178 </label>
179 <Select
180 id="approval-filter"
181 value={approvalFilter}
182 onChange={(event) =>
183 setApprovalFilter(event.target.value as ApprovalFilterValue)
184 }
185 >
186 <option value="pending">pending</option>
187 <option value="resolved">resolved</option>
188 <option value="all">all</option>
189 </Select>
190 </div>
191
192 <div className="grid gap-1.5">
193 <label className="text-xs text-muted-foreground" htmlFor="approval-search">
194 Search
195 </label>
196 <Input
197 id="approval-search"
198 value={approvalSearchQuery}
199 onChange={(event) => {
200 setApprovalSearchQuery(event.target.value);
201 }}
202 placeholder="tool path, status, task run, call id"
203 />
204 </div>
205 </div>
206
207 <StatusMessage message={approvalStatusText} variant={approvalStatusVariant} />
208
209 {matchState(approvalsState, {
210 loading: "Loading approvals...",
211 empty:
212 approvalsState.items.length === 0
213 ? "No approvals found for this workspace."
214 : "No approvals match your filter and search.",
215 filteredCount: filteredApprovals.length,
216 ready: () => (
217 <div className="space-y-2">
218 {filteredApprovals.map((approval) => {
219 const isBusy = approvalBusyId === approval.id;
220 const canResolve = approval.status === "pending";
221
222 return (
223 <article
224 key={approval.id}
225 className={cn(
226 "rounded-lg border border-border bg-background/70 p-3",
227 isBusy && "opacity-80",
228 )}
229 >
230 <div className="flex flex-col gap-3 sm:flex-row sm:items-start sm:justify-between">
231 <div className="min-w-0 space-y-1">
232 <p className="break-all text-sm font-medium">{approval.toolPath}</p>
233 <div className="flex flex-wrap items-center gap-1.5 text-xs text-muted-foreground">
234 <Badge variant={statusBadgeVariant(approval.status)}>{approval.status}</Badge>
235 <span>requested {formatTimestamp(approval.requestedAt)}</span>
236 <span>resolved {formatTimestamp(approval.resolvedAt)}</span>
237 </div>
238 <p className="break-all text-xs text-muted-foreground">task {approval.taskRunId}</p>
239 <p className="break-all text-xs text-muted-foreground">call {approval.callId}</p>
240 {approval.reason ? (
241 <p className="break-all text-xs text-muted-foreground">
242 reason: {approval.reason}
243 </p>
244 ) : null}
245 </div>
246
247 {canResolve ? (
248 <div className="flex items-center gap-2">
249 <Button
250 type="button"
251 size="sm"
252 variant="outline"
253 onClick={() => handleResolveApproval(approval.id, "approved")}
254 disabled={isBusy}
255 >
256 {isBusy ? "Working..." : "Approve"}
257 </Button>
258 <Button
259 type="button"
260 size="sm"
261 variant="destructive"
262 onClick={() => handleResolveApproval(approval.id, "denied")}
263 disabled={isBusy}
264 >
265 {isBusy ? "Working..." : "Deny"}
266 </Button>
267 </div>
268 ) : null}
269 </div>
270
271 <pre className="mt-3 max-h-56 overflow-auto rounded-md border border-border bg-muted/45 p-3 text-[11px] leading-5 text-muted-foreground">
272 {previewFromInputJson(approval.inputPreviewJson)}
273 </pre>
274 </article>
275 );
276 })}
277 </div>
278 ),
279 })}
280 </CardContent>
281 </Card>
282 </section>
283 );
284}
apps/web/components/credentials/credentials-view.tsx+520−0
@@ -0,0 +1,520 @@
1"use client";
2
3import { useMemo, useState, type FormEvent } from "react";
4import {
5 useAtomSet,
6 useAtomValue,
7} from "@effect-atom/atom-react";
8
9import { useWorkspace } from "../../lib/hooks/use-workspace";
10import {
11 credentialBindingsByWorkspace,
12 removeCredentialBinding,
13 toCredentialBindingRemoveResult,
14 toCredentialBindingUpsertPayload,
15 upsertCredentialBinding,
16} from "../../lib/control-plane/atoms";
17import type {
18 CredentialProvider,
19 CredentialScopeType,
20 SourceCredentialBinding,
21} from "@executor-v2/schema";
22
23import { Badge } from "../ui/badge";
24import { Button } from "../ui/button";
25import { Card, CardContent, CardHeader } from "../ui/card";
26import { Input } from "../ui/input";
27import { Select } from "../ui/select";
28import { matchState } from "../shared/match-state";
29import { PageHeader } from "../shared/page-header";
30import { StatusMessage } from "../shared/status-message";
31import { cn, createLocalId } from "../../lib/utils";
32
33const providerOptions: ReadonlyArray<CredentialProvider> = [
34 "api_key",
35 "bearer",
36 "oauth2",
37 "custom",
38];
39
40const scopeTypeOptions: ReadonlyArray<CredentialScopeType> = [
41 "workspace",
42 "organization",
43 "account",
44];
45
46export function CredentialsView() {
47 const { workspaceId } = useWorkspace();
48
49 const credentialBindingsState = useAtomValue(credentialBindingsByWorkspace(workspaceId));
50 const runUpsertCredentialBinding = useAtomSet(upsertCredentialBinding, {
51 mode: "promise",
52 });
53 const runRemoveCredentialBinding = useAtomSet(removeCredentialBinding, {
54 mode: "promise",
55 });
56
57 const [credentialSourceKey, setCredentialSourceKey] = useState("");
58 const [credentialProvider, setCredentialProvider] = useState<CredentialProvider>(
59 "api_key",
60 );
61 const [credentialScopeType, setCredentialScopeType] =
62 useState<CredentialScopeType>("workspace");
63 const [credentialIdInput, setCredentialIdInput] = useState("");
64 const [credentialSecretRef, setCredentialSecretRef] = useState("");
65 const [credentialAccountId, setCredentialAccountId] = useState("");
66 const [credentialAdditionalHeadersJson, setCredentialAdditionalHeadersJson] =
67 useState("");
68 const [credentialBoundAuthFingerprint, setCredentialBoundAuthFingerprint] =
69 useState("");
70
71 const [credentialEditingId, setCredentialEditingId] = useState<
72 SourceCredentialBinding["id"] | null
73 >(null);
74 const [credentialSearchQuery, setCredentialSearchQuery] = useState("");
75
76 const [credentialStatusText, setCredentialStatusText] = useState<string | null>(
77 null,
78 );
79 const [credentialStatusIsError, setCredentialStatusIsError] = useState(false);
80
81 const [credentialBusyId, setCredentialBusyId] =
82 useState<SourceCredentialBinding["id"] | null>(null);
83
84 const filteredCredentialBindings = useMemo(() => {
85 const query = credentialSearchQuery.trim().toLowerCase();
86 if (query.length === 0) {
87 return credentialBindingsState.items;
88 }
89
90 return credentialBindingsState.items.filter((binding) => {
91 return (
92 binding.sourceKey.toLowerCase().includes(query) ||
93 binding.provider.toLowerCase().includes(query) ||
94 binding.scopeType.toLowerCase().includes(query) ||
95 binding.credentialId.toLowerCase().includes(query) ||
96 binding.secretRef.toLowerCase().includes(query) ||
97 (binding.accountId ?? "").toLowerCase().includes(query)
98 );
99 });
100 }, [credentialBindingsState.items, credentialSearchQuery]);
101
102 const setInfoStatus = (message: string) => {
103 setCredentialStatusIsError(false);
104 setCredentialStatusText(message);
105 };
106
107 const setErrorStatus = (message: string) => {
108 setCredentialStatusIsError(true);
109 setCredentialStatusText(message);
110 };
111
112 const resetCredentialForm = () => {
113 setCredentialEditingId(null);
114 setCredentialSourceKey("");
115 setCredentialProvider("api_key");
116 setCredentialScopeType("workspace");
117 setCredentialIdInput("");
118 setCredentialSecretRef("");
119 setCredentialAccountId("");
120 setCredentialAdditionalHeadersJson("");
121 setCredentialBoundAuthFingerprint("");
122 };
123
124 const handleEditCredential = (credentialBindingId: SourceCredentialBinding["id"]) => {
125 const binding = credentialBindingsState.items.find((item) => item.id === credentialBindingId);
126 if (!binding) {
127 setErrorStatus("Unable to load selected credential binding.");
128 return;
129 }
130
131 setCredentialEditingId(binding.id);
132 setCredentialSourceKey(binding.sourceKey);
133 setCredentialProvider(binding.provider);
134 setCredentialScopeType(binding.scopeType);
135 setCredentialIdInput(binding.credentialId);
136 setCredentialSecretRef(binding.secretRef);
137 setCredentialAccountId(binding.accountId ?? "");
138 setCredentialAdditionalHeadersJson(binding.additionalHeadersJson ?? "");
139 setCredentialBoundAuthFingerprint(binding.boundAuthFingerprint ?? "");
140 setInfoStatus(`Loaded binding ${binding.sourceKey} for editing.`);
141 };
142
143 const handleCancelCredentialEdit = () => {
144 resetCredentialForm();
145 setInfoStatus("Credential edit cancelled.");
146 };
147
148 const handleUpsertCredential = (event: FormEvent<HTMLFormElement>) => {
149 event.preventDefault();
150
151 if (credentialBusyId !== null) {
152 return;
153 }
154
155 const sourceKey = credentialSourceKey.trim();
156 const credentialId = credentialIdInput.trim();
157 const secretRef = credentialSecretRef.trim();
158 const accountId = credentialAccountId.trim();
159 const additionalHeadersJson = credentialAdditionalHeadersJson.trim();
160 const boundAuthFingerprint = credentialBoundAuthFingerprint.trim();
161
162 if (sourceKey.length === 0 || credentialId.length === 0 || secretRef.length === 0) {
163 setErrorStatus("Source key, credential id, and secret ref are required.");
164 return;
165 }
166
167 if (credentialScopeType === "account" && accountId.length === 0) {
168 setErrorStatus("Account scope credentials require account id.");
169 return;
170 }
171
172 const requestId =
173 credentialEditingId ??
174 (createLocalId("credential_binding_") as SourceCredentialBinding["id"]);
175
176 setCredentialBusyId(requestId);
177
178 void runUpsertCredentialBinding({
179 path: { workspaceId },
180 payload: toCredentialBindingUpsertPayload({
181 id: credentialEditingId ?? undefined,
182 credentialId: credentialId as SourceCredentialBinding["credentialId"],
183 scopeType: credentialScopeType,
184 sourceKey,
185 provider: credentialProvider,
186 secretRef,
187 accountId:
188 credentialScopeType === "account"
189 ? (accountId as SourceCredentialBinding["accountId"])
190 : null,
191 additionalHeadersJson: additionalHeadersJson.length > 0 ? additionalHeadersJson : null,
192 boundAuthFingerprint: boundAuthFingerprint.length > 0 ? boundAuthFingerprint : null,
193 }),
194 })
195 .then(() => {
196 setInfoStatus(
197 credentialEditingId
198 ? `Updated credential binding ${sourceKey}.`
199 : `Added credential binding ${sourceKey}.`,
200 );
201 resetCredentialForm();
202 })
203 .catch(() => {
204 setErrorStatus("Credential save failed.");
205 })
206 .finally(() => {
207 setCredentialBusyId(null);
208 });
209 };
210
211 const handleRemoveCredential = (credentialBindingId: SourceCredentialBinding["id"]) => {
212 if (credentialBusyId !== null) {
213 return;
214 }
215
216 setCredentialBusyId(credentialBindingId);
217
218 void runRemoveCredentialBinding({
219 path: {
220 workspaceId,
221 credentialBindingId,
222 },
223 })
224 .then((result) => {
225 const removed = toCredentialBindingRemoveResult(result);
226 setInfoStatus(
227 removed ? "Credential binding removed." : "Credential binding not found.",
228 );
229
230 if (credentialEditingId === credentialBindingId) {
231 handleCancelCredentialEdit();
232 }
233
234 })
235 .catch(() => {
236 setErrorStatus("Credential removal failed.");
237 })
238 .finally(() => {
239 setCredentialBusyId(null);
240 });
241 };
242
243 return (
244 <div className="grid gap-5 lg:grid-cols-2">
245 <Card className="border-border/70">
246 <CardHeader className="pb-3">
247 <PageHeader
248 title={
249 credentialEditingId ? "Edit Credential Binding" : "Add Credential Binding"
250 }
251 description="Bind workspace credentials to sources and providers."
252 />
253 </CardHeader>
254 <CardContent className="space-y-4">
255 <form className="space-y-3" onSubmit={handleUpsertCredential}>
256 <div className="grid gap-1.5">
257 <label className="text-xs text-muted-foreground" htmlFor="credential-source-key">
258 Source key
259 </label>
260 <Input
261 id="credential-source-key"
262 value={credentialSourceKey}
263 onChange={(event) => setCredentialSourceKey(event.target.value)}
264 placeholder="source_github"
265 required
266 disabled={credentialBusyId !== null}
267 />
268 </div>
269
270 <div className="grid gap-3 sm:grid-cols-2">
271 <div className="grid gap-1.5">
272 <label className="text-xs text-muted-foreground" htmlFor="credential-provider">
273 Provider
274 </label>
275 <Select
276 id="credential-provider"
277 value={credentialProvider}
278 onChange={(event) =>
279 setCredentialProvider(event.target.value as CredentialProvider)
280 }
281 disabled={credentialBusyId !== null}
282 >
283 {providerOptions.map((provider) => (
284 <option key={provider} value={provider}>
285 {provider}
286 </option>
287 ))}
288 </Select>
289 </div>
290
291 <div className="grid gap-1.5">
292 <label
293 className="text-xs text-muted-foreground"
294 htmlFor="credential-scope-type"
295 >
296 Scope
297 </label>
298 <Select
299 id="credential-scope-type"
300 value={credentialScopeType}
301 onChange={(event) =>
302 setCredentialScopeType(event.target.value as CredentialScopeType)
303 }
304 disabled={credentialBusyId !== null}
305 >
306 {scopeTypeOptions.map((scopeType) => (
307 <option key={scopeType} value={scopeType}>
308 {scopeType}
309 </option>
310 ))}
311 </Select>
312 </div>
313 </div>
314
315 <div className="grid gap-3 sm:grid-cols-2">
316 <div className="grid gap-1.5">
317 <label className="text-xs text-muted-foreground" htmlFor="credential-id">
318 Credential id
319 </label>
320 <Input
321 id="credential-id"
322 value={credentialIdInput}
323 onChange={(event) => setCredentialIdInput(event.target.value)}
324 placeholder="cred_123"
325 required
326 disabled={credentialBusyId !== null}
327 />
328 </div>
329
330 <div className="grid gap-1.5">
331 <label
332 className="text-xs text-muted-foreground"
333 htmlFor="credential-secret-ref"
334 >
335 Secret ref
336 </label>
337 <Input
338 id="credential-secret-ref"
339 value={credentialSecretRef}
340 onChange={(event) => setCredentialSecretRef(event.target.value)}
341 placeholder="secrets/github-token"
342 required
343 disabled={credentialBusyId !== null}
344 />
345 </div>
346 </div>
347
348 {credentialScopeType === "account" ? (
349 <div className="grid gap-1.5">
350 <label
351 className="text-xs text-muted-foreground"
352 htmlFor="credential-account-id"
353 >
354 Account id
355 </label>
356 <Input
357 id="credential-account-id"
358 value={credentialAccountId}
359 onChange={(event) => setCredentialAccountId(event.target.value)}
360 placeholder="acct_123"
361 required
362 disabled={credentialBusyId !== null}
363 />
364 </div>
365 ) : null}
366
367 <div className="grid gap-1.5">
368 <label
369 className="text-xs text-muted-foreground"
370 htmlFor="credential-headers-json"
371 >
372 Additional headers JSON (optional)
373 </label>
374 <Input
375 id="credential-headers-json"
376 value={credentialAdditionalHeadersJson}
377 onChange={(event) =>
378 setCredentialAdditionalHeadersJson(event.target.value)
379 }
380 placeholder='{"X-Team": "tools"}'
381 disabled={credentialBusyId !== null}
382 />
383 </div>
384
385 <div className="grid gap-1.5">
386 <label
387 className="text-xs text-muted-foreground"
388 htmlFor="credential-auth-fingerprint"
389 >
390 Bound auth fingerprint (optional)
391 </label>
392 <Input
393 id="credential-auth-fingerprint"
394 value={credentialBoundAuthFingerprint}
395 onChange={(event) =>
396 setCredentialBoundAuthFingerprint(event.target.value)
397 }
398 placeholder="fingerprint hash"
399 disabled={credentialBusyId !== null}
400 />
401 </div>
402
403 <div className="grid gap-2 sm:grid-cols-2">
404 <Button type="submit" disabled={credentialBusyId !== null}>
405 {credentialBusyId !== null
406 ? "Saving..."
407 : credentialEditingId
408 ? "Save Binding"
409 : "Add Binding"}
410 </Button>
411 {credentialEditingId ? (
412 <Button
413 type="button"
414 variant="outline"
415 onClick={handleCancelCredentialEdit}
416 disabled={credentialBusyId !== null}
417 >
418 Cancel
419 </Button>
420 ) : null}
421 </div>
422 </form>
423
424 <StatusMessage
425 message={credentialStatusText}
426 variant={credentialStatusIsError ? "error" : "info"}
427 />
428 </CardContent>
429 </Card>
430
431 <Card className="border-border/70">
432 <CardHeader className="pb-3">
433 <PageHeader
434 title="Credential Bindings"
435 description="Credentials currently linked to sources."
436 />
437 </CardHeader>
438 <CardContent className="space-y-4">
439 <div className="grid gap-1.5">
440 <label className="text-xs text-muted-foreground" htmlFor="credential-search">
441 Search
442 </label>
443 <Input
444 id="credential-search"
445 value={credentialSearchQuery}
446 onChange={(event) => setCredentialSearchQuery(event.target.value)}
447 placeholder="source key, provider, scope, credential id, secret"
448 disabled={credentialBindingsState.state === "loading"}
449 />
450 </div>
451
452 {matchState(credentialBindingsState, {
453 loading: "Loading credential bindings...",
454 empty:
455 credentialSearchQuery.trim().length > 0
456 ? "No credentials match this search."
457 : "No credential bindings found.",
458 filteredCount: filteredCredentialBindings.length,
459 ready: () => (
460 <div className="space-y-2">
461 {filteredCredentialBindings.map((binding) => {
462 const isBusy = credentialBusyId === binding.id;
463
464 return (
465 <div
466 key={binding.id}
467 className={cn(
468 "rounded-lg border border-border bg-background/70 p-3",
469 isBusy && "opacity-75",
470 )}
471 >
472 <div className="flex flex-col gap-3 sm:flex-row sm:items-start sm:justify-between">
473 <div className="min-w-0 space-y-1">
474 <p className="truncate text-sm font-medium">{binding.sourceKey}</p>
475 <div className="flex flex-wrap items-center gap-1.5 text-xs text-muted-foreground">
476 <Badge variant="outline">{binding.provider}</Badge>
477 <Badge variant="outline">{binding.scopeType}</Badge>
478 <span>{binding.credentialId}</span>
479 </div>
480 <p className="break-all text-xs text-muted-foreground">
481 secret {binding.secretRef}
482 </p>
483 {binding.accountId ? (
484 <p className="break-all text-xs text-muted-foreground">
485 account {binding.accountId}
486 </p>
487 ) : null}
488 </div>
489 <div className="flex items-center gap-2">
490 <Button
491 type="button"
492 size="sm"
493 variant="outline"
494 onClick={() => handleEditCredential(binding.id)}
495 disabled={credentialBusyId !== null}
496 >
497 Edit
498 </Button>
499 <Button
500 type="button"
501 size="sm"
502 variant="destructive"
503 onClick={() => handleRemoveCredential(binding.id)}
504 disabled={credentialBusyId !== null}
505 >
506 {isBusy ? "Working..." : "Remove"}
507 </Button>
508 </div>
509 </div>
510 </div>
511 );
512 })}
513 </div>
514 ),
515 })}
516 </CardContent>
517 </Card>
518 </div>
519 );
520}
apps/web/components/policies/policies-view.tsx+285−0
@@ -0,0 +1,285 @@
1"use client";
2
3import { useAtomSet, useAtomValue } from "@effect-atom/atom-react";
4import type { Policy, PolicyDecision, PolicyId } from "@executor-v2/schema";
5import { useMemo, useState } from "react";
6import type { FormEvent } from "react";
7
8import { useWorkspace } from "../../lib/hooks/use-workspace";
9import {
10 optimisticRemovePolicy,
11 optimisticUpsertPolicy,
12 policiesByWorkspace,
13 removePolicy,
14 toPolicyRemoveResult,
15 toPolicyUpsertPayload,
16 upsertPolicy,
17} from "../../lib/control-plane/atoms";
18import { Badge } from "../ui/badge";
19import { Button } from "../ui/button";
20import { Card, CardContent, CardDescription, CardHeader, CardTitle } from "../ui/card";
21import { Input } from "../ui/input";
22import { Select } from "../ui/select";
23import { cn, createLocalId, formatTimestamp } from "../../lib/utils";
24import { matchState } from "../shared/match-state";
25import { PageHeader } from "../shared/page-header";
26import { StatusMessage } from "../shared/status-message";
27
28const policyDecisionOptions: ReadonlyArray<PolicyDecision> = ["allow", "require_approval", "deny"];
29
30const decisionBadgeVariant = (decision: PolicyDecision): "secondary" | "pending" | "denied" => {
31 if (decision === "allow") return "secondary";
32 if (decision === "require_approval") return "pending";
33 return "denied";
34};
35
36export function PoliciesView() {
37 const { workspaceId } = useWorkspace();
38
39 const [policyEditingId, setPolicyEditingId] = useState<PolicyId | null>(null);
40 const [policyPattern, setPolicyPattern] = useState("");
41 const [policyDecision, setPolicyDecision] = useState<PolicyDecision>("require_approval");
42 const [policySearchQuery, setPolicySearchQuery] = useState("");
43 const [policyBusyId, setPolicyBusyId] = useState<PolicyId | null>(null);
44 const [policyStatusText, setPolicyStatusText] = useState<string | null>(null);
45 const [policyStatusVariant, setPolicyStatusVariant] = useState<"info" | "error">("info");
46 const [optimisticPolicies, setOptimisticPolicies] = useState<ReadonlyArray<Policy> | null>(null);
47
48 const policiesState = useAtomValue(policiesByWorkspace(workspaceId));
49 const runUpsertPolicy = useAtomSet(upsertPolicy, { mode: "promise" });
50 const runRemovePolicy = useAtomSet(removePolicy, { mode: "promise" });
51
52 const policyItems = optimisticPolicies ?? policiesState.items;
53 const filteredPolicies = useMemo(() => {
54 const query = policySearchQuery.trim().toLowerCase();
55 if (query.length === 0) return policyItems;
56 return policyItems.filter((policy) =>
57 policy.toolPathPattern.toLowerCase().includes(query) ||
58 policy.decision.toLowerCase().includes(query),
59 );
60 }, [policyItems, policySearchQuery]);
61
62 const setStatus = (message: string | null, variant: "info" | "error" = "info") => {
63 setPolicyStatusText(message);
64 setPolicyStatusVariant(variant);
65 };
66
67 const clearPolicyForm = () => {
68 setPolicyEditingId(null);
69 setPolicyPattern("");
70 setPolicyDecision("require_approval");
71 };
72
73 const handleEditPolicy = (policyId: PolicyId) => {
74 if (policyBusyId !== null) return;
75 const target = policyItems.find((policy) => policy.id === policyId);
76 if (!target) return;
77 setPolicyEditingId(policyId);
78 setPolicyPattern(target.toolPathPattern);
79 setPolicyDecision(target.decision);
80 setStatus(`Editing policy ${target.toolPathPattern}.`);
81 };
82
83 const handleCancelPolicyEdit = () => {
84 if (policyBusyId !== null) return;
85 clearPolicyForm();
86 setStatus("Policy edit cancelled.");
87 };
88
89 const handleUpsertPolicy = (event: FormEvent<HTMLFormElement>) => {
90 event.preventDefault();
91 if (policyBusyId !== null) return;
92
93 const toolPathPattern = policyPattern.trim();
94 if (toolPathPattern.length === 0) {
95 setStatus("Tool path pattern is required.", "error");
96 return;
97 }
98
99 const policyId = policyEditingId ?? (createLocalId("pol_") as PolicyId);
100 const nextPolicies = optimisticUpsertPolicy(policyItems, {
101 workspaceId,
102 policyId,
103 toolPathPattern,
104 decision: policyDecision,
105 });
106
107 setPolicyBusyId(policyId);
108 setOptimisticPolicies(nextPolicies);
109
110 void runUpsertPolicy({
111 path: { workspaceId },
112 payload: toPolicyUpsertPayload({
113 id: policyEditingId ?? undefined,
114 toolPathPattern,
115 decision: policyDecision,
116 }),
117 })
118 .then(() => {
119 setStatus(policyEditingId ? `Updated policy ${toolPathPattern}.` : `Added policy ${toolPathPattern}.`);
120 clearPolicyForm();
121 setOptimisticPolicies(null);
122 })
123 .catch(() => {
124 setStatus("Policy save failed.", "error");
125 setOptimisticPolicies(null);
126 })
127 .finally(() => {
128 setPolicyBusyId(null);
129 });
130 };
131
132 const handleRemovePolicy = (policyId: PolicyId) => {
133 if (policyBusyId !== null) return;
134
135 const nextPolicies = optimisticRemovePolicy(policyItems, policyId);
136 setPolicyBusyId(policyId);
137 setOptimisticPolicies(nextPolicies);
138
139 void runRemovePolicy({ path: { workspaceId, policyId } })
140 .then((result) => {
141 const removed = toPolicyRemoveResult(result);
142 setStatus(removed ? "Policy removed." : "Policy not found.");
143 if (policyEditingId === policyId) clearPolicyForm();
144 setOptimisticPolicies(null);
145 })
146 .catch(() => {
147 setStatus("Policy removal failed.", "error");
148 setOptimisticPolicies(null);
149 })
150 .finally(() => {
151 setPolicyBusyId(null);
152 });
153 };
154
155 const emptyMessage =
156 policySearchQuery.trim().length > 0
157 ? "No policies match your search."
158 : policyItems.length === 0
159 ? "No policies configured for this workspace."
160 : null;
161
162 return (
163 <div className="mx-auto flex w-full max-w-5xl flex-col gap-4">
164 <PageHeader title="Policies" description="Define and manage tool path policy behavior." />
165 <Card className={cn("border-border/70")}>
166 <CardHeader className="pb-3">
167 <CardTitle>Policies</CardTitle>
168 <CardDescription>Use these rules to control default policy decisions.</CardDescription>
169 </CardHeader>
170 <CardContent className="space-y-4">
171 <form className="space-y-3" onSubmit={handleUpsertPolicy}>
172 <div className="grid gap-1.5">
173 <label className="text-xs text-muted-foreground" htmlFor="policy-pattern">
174 Tool path pattern
175 </label>
176 <Input
177 id="policy-pattern"
178 value={policyPattern}
179 onChange={(event) => {
180 setPolicyPattern(event.target.value);
181 }}
182 placeholder="source:* or source:github/*"
183 required
184 />
185 </div>
186 <div className="grid gap-1.5">
187 <label className="text-xs text-muted-foreground" htmlFor="policy-decision">
188 Decision
189 </label>
190 <Select
191 id="policy-decision"
192 value={policyDecision}
193 onChange={(event) => {
194 setPolicyDecision(event.target.value as PolicyDecision);
195 }}
196 >
197 {policyDecisionOptions.map((decision) => (
198 <option key={decision} value={decision}>
199 {decision}
200 </option>
201 ))}
202 </Select>
203 </div>
204 <div className="grid gap-2 sm:grid-cols-2">
205 <Button type="submit" disabled={policyBusyId !== null}>
206 {policyBusyId !== null
207 ? "Saving..."
208 : policyEditingId
209 ? "Save Policy"
210 : "Add Policy"}
211 </Button>
212 <Button
213 type="button"
214 variant="outline"
215 onClick={handleCancelPolicyEdit}
216 disabled={policyBusyId !== null || policyEditingId === null}
217 >
218 Cancel
219 </Button>
220 </div>
221 </form>
222
223 <StatusMessage message={policyStatusText} variant={policyStatusVariant} />
224
225 <div className="grid gap-1.5">
226 <label className="text-xs text-muted-foreground" htmlFor="policy-search">
227 Search policies
228 </label>
229 <Input
230 id="policy-search"
231 value={policySearchQuery}
232 onChange={(event) => {
233 setPolicySearchQuery(event.target.value);
234 }}
235 placeholder="pattern or decision"
236 />
237 </div>
238
239 {matchState(policiesState, {
240 loading: "Loading policies...",
241 empty: emptyMessage,
242 filteredCount: filteredPolicies.length,
243 ready: () => (
244 <div className="space-y-2">
245 {filteredPolicies.map((policy) => (
246 <div key={policy.id} className="rounded-lg border border-border bg-background/70 p-3">
247 <div className="flex flex-col gap-3 sm:flex-row sm:items-start sm:justify-between">
248 <div className="min-w-0 space-y-1">
249 <p className="break-all text-sm font-medium">{policy.toolPathPattern}</p>
250 <div className="flex flex-wrap items-center gap-1.5 text-xs text-muted-foreground">
251 <Badge variant={decisionBadgeVariant(policy.decision)}>{policy.decision}</Badge>
252 <span>updated {formatTimestamp(policy.updatedAt)}</span>
253 </div>
254 </div>
255 <div className="flex items-center gap-2">
256 <Button
257 type="button"
258 size="sm"
259 variant="outline"
260 onClick={() => handleEditPolicy(policy.id)}
261 disabled={policyBusyId !== null}
262 >
263 Edit
264 </Button>
265 <Button
266 type="button"
267 size="sm"
268 variant="destructive"
269 onClick={() => handleRemovePolicy(policy.id)}
270 disabled={policyBusyId !== null}
271 >
272 {policyBusyId === policy.id ? "Working..." : "Remove"}
273 </Button>
274 </div>
275 </div>
276 </div>
277 ))}
278 </div>
279 ),
280 })}
281 </CardContent>
282 </Card>
283 </div>
284 );
285}
apps/web/components/settings/settings-view.tsx+522−0
@@ -0,0 +1,522 @@
1"use client";
2
3import { useEffect, useState, type FormEvent } from "react";
4import { useAtomSet, useAtomValue } from "@effect-atom/atom-react";
5import type { Organization, Workspace } from "@executor-v2/schema";
6
7import { useWorkspace } from "../../lib/hooks/use-workspace";
8import {
9 organizationsState,
10 upsertOrganization,
11 upsertWorkspace,
12 toOrganizationUpsertPayload,
13 toWorkspaceUpsertPayload,
14 workspacesState,
15} from "../../lib/control-plane/atoms";
16import { Badge } from "../ui/badge";
17import { Button } from "../ui/button";
18import {
19 Card,
20 CardContent,
21 CardDescription,
22 CardHeader,
23 CardTitle,
24} from "../ui/card";
25import { Input } from "../ui/input";
26import { Select } from "../ui/select";
27import { matchState } from "../shared/match-state";
28import { PageHeader } from "../shared/page-header";
29import { StatusMessage } from "../shared/status-message";
30
31type OrganizationForm = {
32 id: string;
33 slug: string;
34 name: string;
35 status: Organization["status"];
36};
37
38type WorkspaceForm = {
39 id: string;
40 name: string;
41 organizationId: string;
42};
43
44const organizationStatusOptions: ReadonlyArray<Organization["status"]> = [
45 "active",
46 "suspended",
47 "archived",
48];
49
50const defaultOrganizationForm = (): OrganizationForm => ({
51 id: "",
52 slug: "",
53 name: "",
54 status: "active",
55});
56
57const defaultWorkspaceForm = (): WorkspaceForm => ({
58 id: "",
59 name: "",
60 organizationId: "",
61});
62
63const createOrganizationId = (): Organization["id"] =>
64 `org_${crypto.randomUUID()}` as Organization["id"];
65
66const createWorkspaceId = (): Workspace["id"] =>
67 `ws_${crypto.randomUUID()}` as Workspace["id"];
68
69const errorMessage = (cause: unknown, fallback: string): string =>
70 cause instanceof Error && cause.message.trim().length > 0
71 ? cause.message
72 : fallback;
73
74const organizationStatusVariant = (
75 status: Organization["status"],
76): "approved" | "pending" | "denied" | "outline" => {
77 if (status === "active") {
78 return "approved";
79 }
80 if (status === "suspended") {
81 return "pending";
82 }
83 return "denied";
84};
85
86const statusVariant = (message: string | null): "info" | "error" => {
87 return message?.toLowerCase().includes("failed") ? "error" : "info";
88};
89
90export default function SettingsView() {
91 const { workspaceId, setWorkspaceId } = useWorkspace();
92
93 const organizations = useAtomValue(organizationsState);
94 const workspaces = useAtomValue(workspacesState);
95 const runUpsertOrganization = useAtomSet(upsertOrganization, { mode: "promise" });
96 const runUpsertWorkspace = useAtomSet(upsertWorkspace, { mode: "promise" });
97
98 const [organizationForm, setOrganizationForm] = useState<OrganizationForm>(defaultOrganizationForm);
99 const [workspaceForm, setWorkspaceForm] = useState<WorkspaceForm>(defaultWorkspaceForm);
100 const [organizationStatusText, setOrganizationStatusText] = useState<string | null>(null);
101 const [workspaceStatusText, setWorkspaceStatusText] = useState<string | null>(null);
102
103 const organizationsLoading = organizations.state === "loading";
104 const workspacesLoading = workspaces.state === "loading";
105
106 useEffect(() => {
107 if (workspaceForm.name.trim().length > 0) {
108 return;
109 }
110
111 const currentWorkspace = workspaces.items.find((workspace) => workspace.id === workspaceId);
112 if (!currentWorkspace) {
113 return;
114 }
115
116 setWorkspaceForm((current) => ({
117 ...current,
118 id: currentWorkspace.id,
119 name: currentWorkspace.name,
120 organizationId: currentWorkspace.organizationId,
121 }));
122 }, [workspaceId, workspaceForm.name, workspaces.items]);
123
124 useEffect(() => {
125 if (organizationForm.id.trim().length > 0) {
126 return;
127 }
128
129 const currentWorkspace = workspaces.items.find((workspace) => workspace.id === workspaceId);
130 if (!currentWorkspace) {
131 return;
132 }
133
134 const currentOrganization = organizations.items.find(
135 (organization) => organization.id === currentWorkspace.organizationId,
136 );
137 if (!currentOrganization) {
138 return;
139 }
140
141 setOrganizationForm({
142 id: currentOrganization.id,
143 slug: currentOrganization.slug,
144 name: currentOrganization.name,
145 status: currentOrganization.status,
146 });
147 }, [organizationForm.id, organizations.items, workspaceId, workspaces.items]);
148
149 const handleUpsertOrganization = (event: FormEvent<HTMLFormElement>) => {
150 event.preventDefault();
151
152 const slug = organizationForm.slug.trim();
153 const name = organizationForm.name.trim();
154 const inputId = organizationForm.id.trim();
155 const organizationId = inputId.length > 0
156 ? (inputId as Organization["id"])
157 : createOrganizationId();
158
159 if (slug.length === 0 || name.length === 0) {
160 setOrganizationStatusText("Organization slug and name are required.");
161 return;
162 }
163
164 const payload = toOrganizationUpsertPayload({
165 id: organizationId,
166 slug,
167 name,
168 status: organizationForm.status,
169 });
170
171 void runUpsertOrganization({ payload })
172 .then((organization) => {
173 setOrganizationStatusText(`Saved organization ${organization.slug}.`);
174 setOrganizationForm({
175 id: organization.id,
176 slug: organization.slug,
177 name: organization.name,
178 status: organization.status,
179 });
180 })
181 .catch((cause) => {
182 setOrganizationStatusText(errorMessage(cause, "Organization save failed."));
183 });
184 };
185
186 const handleUpsertWorkspace = (event: FormEvent<HTMLFormElement>) => {
187 event.preventDefault();
188
189 const name = workspaceForm.name.trim();
190 const inputId = workspaceForm.id.trim();
191 const organizationId = workspaceForm.organizationId.trim();
192 const workspaceId = inputId.length > 0
193 ? (inputId as Workspace["id"])
194 : createWorkspaceId();
195
196 if (name.length === 0) {
197 setWorkspaceStatusText("Workspace name is required.");
198 return;
199 }
200
201 if (organizationId.length === 0) {
202 setWorkspaceStatusText("Workspace organization is required.");
203 return;
204 }
205
206 const payload = toWorkspaceUpsertPayload({
207 id: workspaceId,
208 name,
209 organizationId: organizationId as Workspace["organizationId"],
210 });
211
212 void runUpsertWorkspace({ payload })
213 .then((workspace) => {
214 setWorkspaceStatusText(`Saved workspace ${workspace.name}.`);
215 setWorkspaceForm({
216 id: workspace.id,
217 name: workspace.name,
218 organizationId: workspace.organizationId,
219 });
220 setWorkspaceId(workspace.id);
221 })
222 .catch((cause) => {
223 setWorkspaceStatusText(errorMessage(cause, "Workspace save failed."));
224 });
225 };
226
227 const handleLoadOrganization = (organization: Organization) => {
228 setOrganizationForm({
229 id: organization.id,
230 slug: organization.slug,
231 name: organization.name,
232 status: organization.status,
233 });
234 setOrganizationStatusText(`Loaded organization ${organization.slug}.`);
235 };
236
237 const handleLoadWorkspace = (workspace: Workspace) => {
238 setWorkspaceForm({
239 id: workspace.id,
240 name: workspace.name,
241 organizationId: workspace.organizationId,
242 });
243 setWorkspaceId(workspace.id);
244 setWorkspaceStatusText(`Loaded workspace ${workspace.id}.`);
245 };
246
247 return (
248 <section className="space-y-8">
249 <PageHeader
250 title="Settings"
251 description="Manage organizations and workspaces in a single combined view."
252 />
253
254 <section className="space-y-5">
255 <div className="grid gap-5 lg:grid-cols-2">
256 <Card className="border-border/70">
257 <CardHeader className="pb-3">
258 <CardTitle>Organization Profile</CardTitle>
259 <CardDescription>
260 Create and edit organization records used by workspace definitions.
261 </CardDescription>
262 </CardHeader>
263
264 <CardContent className="space-y-4">
265 <form className="space-y-3" onSubmit={handleUpsertOrganization}>
266 <div className="grid gap-1.5">
267 <label className="text-xs text-muted-foreground" htmlFor="organization-id">
268 ID (optional)
269 </label>
270 <Input
271 id="organization-id"
272 value={organizationForm.id}
273 onChange={(event) =>
274 setOrganizationForm((current) => ({ ...current, id: event.target.value }))
275 }
276 placeholder="org_local"
277 disabled={organizationsLoading}
278 />
279 </div>
280 <div className="grid gap-1.5">
281 <label className="text-xs text-muted-foreground" htmlFor="organization-slug">
282 Slug
283 </label>
284 <Input
285 id="organization-slug"
286 value={organizationForm.slug}
287 onChange={(event) =>
288 setOrganizationForm((current) => ({ ...current, slug: event.target.value }))
289 }
290 placeholder="acme"
291 required
292 disabled={organizationsLoading}
293 />
294 </div>
295 <div className="grid gap-1.5">
296 <label className="text-xs text-muted-foreground" htmlFor="organization-name">
297 Name
298 </label>
299 <Input
300 id="organization-name"
301 value={organizationForm.name}
302 onChange={(event) =>
303 setOrganizationForm((current) => ({ ...current, name: event.target.value }))
304 }
305 placeholder="Acme"
306 required
307 disabled={organizationsLoading}
308 />
309 </div>
310 <div className="grid gap-1.5">
311 <label className="text-xs text-muted-foreground" htmlFor="organization-status">
312 Status
313 </label>
314 <Select
315 id="organization-status"
316 value={organizationForm.status}
317 onChange={(event) =>
318 setOrganizationForm((current) => ({
319 ...current,
320 status: event.target.value as Organization["status"],
321 }))
322 }
323 disabled={organizationsLoading}
324 >
325 {organizationStatusOptions.map((status) => (
326 <option key={status} value={status}>
327 {status}
328 </option>
329 ))}
330 </Select>
331 </div>
332
333 <div className="flex gap-2">
334 <Button type="submit" disabled={organizationsLoading}>
335 Save Organization
336 </Button>
337 </div>
338 </form>
339
340 <StatusMessage
341 message={organizationStatusText}
342 variant={statusVariant(organizationStatusText)}
343 className="text-[13px]"
344 />
345 </CardContent>
346 </Card>
347
348 <Card className="border-border/70">
349 <CardHeader className="pb-3">
350 <CardTitle>Organizations</CardTitle>
351 <CardDescription>Available organizations from the control plane.</CardDescription>
352 </CardHeader>
353
354 <CardContent className="space-y-3">
355 {matchState(organizations, {
356 loading: "Loading organizations...",
357 empty: "No organizations yet.",
358 ready: (organizationItems) => (
359 <>
360 {organizationItems.map((organization) => (
361 <div
362 key={organization.id}
363 className="rounded-lg border border-border bg-background/70 p-3"
364 >
365 <div className="flex flex-col gap-3 sm:flex-row sm:items-start sm:justify-between">
366 <div className="min-w-0 space-y-1">
367 <p className="truncate text-sm font-medium">{organization.name}</p>
368 <div className="flex flex-wrap items-center gap-1.5 text-xs text-muted-foreground">
369 <Badge variant={organizationStatusVariant(organization.status)}>{organization.status}</Badge>
370 <span className="break-all">{organization.slug}</span>
371 <span className="break-all">{organization.id}</span>
372 </div>
373 </div>
374 <Button
375 type="button"
376 size="sm"
377 variant="outline"
378 onClick={() => {
379 handleLoadOrganization(organization);
380 }}
381 >
382 Load
383 </Button>
384 </div>
385 </div>
386 ))}
387 </>
388 ),
389 })}
390 </CardContent>
391 </Card>
392 </div>
393 </section>
394
395 <section className="space-y-5">
396 <div className="grid gap-5 lg:grid-cols-2">
397 <Card className="border-border/70">
398 <CardHeader className="pb-3">
399 <CardTitle>Workspace Profile</CardTitle>
400 <CardDescription>
401 Create or update workspace records scoped to an organization.
402 </CardDescription>
403 </CardHeader>
404
405 <CardContent className="space-y-4">
406 <form className="space-y-3" onSubmit={handleUpsertWorkspace}>
407 <div className="grid gap-1.5">
408 <label className="text-xs text-muted-foreground" htmlFor="workspace-id">
409 ID (optional)
410 </label>
411 <Input
412 id="workspace-id"
413 value={workspaceForm.id}
414 onChange={(event) =>
415 setWorkspaceForm((current) => ({ ...current, id: event.target.value }))
416 }
417 placeholder="ws_local"
418 disabled={workspacesLoading}
419 />
420 </div>
421 <div className="grid gap-1.5">
422 <label className="text-xs text-muted-foreground" htmlFor="workspace-name">
423 Name
424 </label>
425 <Input
426 id="workspace-name"
427 value={workspaceForm.name}
428 onChange={(event) =>
429 setWorkspaceForm((current) => ({ ...current, name: event.target.value }))
430 }
431 placeholder="Local Workspace"
432 required
433 disabled={workspacesLoading}
434 />
435 </div>
436 <div className="grid gap-1.5">
437 <label className="text-xs text-muted-foreground" htmlFor="workspace-organization-id">
438 Organization
439 </label>
440 <Select
441 id="workspace-organization-id"
442 value={workspaceForm.organizationId}
443 onChange={(event) =>
444 setWorkspaceForm((current) => ({
445 ...current,
446 organizationId: event.target.value,
447 }))
448 }
449 disabled={workspacesLoading}
450 >
451 <option value="">Select organization</option>
452 {organizations.items.map((organization) => (
453 <option key={organization.id} value={organization.id}>
454 {organization.name}
455 </option>
456 ))}
457 </Select>
458 </div>
459
460 <div className="flex gap-2">
461 <Button type="submit" disabled={workspacesLoading}>
462 Save Workspace
463 </Button>
464 </div>
465 </form>
466
467 <StatusMessage
468 message={workspaceStatusText}
469 variant={statusVariant(workspaceStatusText)}
470 className="text-[13px]"
471 />
472 </CardContent>
473 </Card>
474
475 <Card className="border-border/70">
476 <CardHeader className="pb-3">
477 <CardTitle>Workspaces</CardTitle>
478 <CardDescription>Available workspaces from the control plane.</CardDescription>
479 </CardHeader>
480
481 <CardContent className="space-y-3">
482 {matchState(workspaces, {
483 loading: "Loading workspaces...",
484 empty: "No workspaces yet.",
485 ready: (workspaceItems) => (
486 <>
487 {workspaceItems.map((workspace) => (
488 <div
489 key={workspace.id}
490 className="rounded-lg border border-border bg-background/70 p-3"
491 >
492 <div className="flex flex-col gap-3 sm:flex-row sm:items-start sm:justify-between">
493 <div className="min-w-0 space-y-1">
494 <p className="truncate text-sm font-medium">{workspace.name}</p>
495 <div className="flex flex-wrap items-center gap-1.5 text-xs text-muted-foreground">
496 <span className="break-all">{workspace.id}</span>
497 <span className="break-all">org {workspace.organizationId}</span>
498 </div>
499 </div>
500 <Button
501 type="button"
502 size="sm"
503 variant="outline"
504 onClick={() => {
505 handleLoadWorkspace(workspace);
506 }}
507 >
508 Load
509 </Button>
510 </div>
511 </div>
512 ))}
513 </>
514 ),
515 })}
516 </CardContent>
517 </Card>
518 </div>
519 </section>
520 </section>
521 );
522}
apps/web/components/shared/empty-state.tsx+19−0
@@ -0,0 +1,19 @@
1import { cn } from "../../lib/utils";
2
3type EmptyStateProps = {
4 message: string;
5 className?: string;
6};
7
8export function EmptyState({ message, className }: EmptyStateProps) {
9 return (
10 <div
11 className={cn(
12 "flex items-center justify-center rounded-md border border-dashed border-border py-8 text-[13px] text-muted-foreground",
13 className,
14 )}
15 >
16 {message}
17 </div>
18 );
19}
apps/web/components/shared/loading-state.tsx+23−0
@@ -0,0 +1,23 @@
1import { cn } from "../../lib/utils";
2
3type LoadingStateProps = {
4 message?: string;
5 className?: string;
6};
7
8export function LoadingState({ message = "Loading...", className }: LoadingStateProps) {
9 return (
10 <div
11 className={cn(
12 "flex items-center gap-2 rounded-md border border-border bg-muted/30 px-3 py-2 text-[13px] text-muted-foreground",
13 className,
14 )}
15 >
16 <svg className="size-3.5 animate-spin" viewBox="0 0 16 16" fill="none">
17 <circle cx="8" cy="8" r="6" stroke="currentColor" strokeWidth="1.5" opacity="0.25" />
18 <path d="M14 8a6 6 0 00-6-6" stroke="currentColor" strokeWidth="1.5" strokeLinecap="round" />
19 </svg>
20 {message}
21 </div>
22 );
23}
apps/web/components/shared/match-state.tsx+55−0
@@ -0,0 +1,55 @@
1import type { ReactNode } from "react";
2
3import type { EntityState } from "../../lib/control-plane/atoms";
4import { EmptyState } from "./empty-state";
5import { LoadingState } from "./loading-state";
6import { StatusMessage } from "./status-message";
7
8// ---------------------------------------------------------------------------
9// matchState — eliminates the repeated loading/error/empty conditionals
10// across every view component.
11//
12// Usage:
13// matchState(state, {
14// loading: "Loading sources...",
15// empty: sourceItems.length === 0 ? "No sources yet." : "No matches.",
16// ready: (items) => <SourceList items={items} />,
17// })
18//
19// The `filteredCount` option lets you provide a filtered subset for the empty
20// check while the full item list is still used for the "ready" callback.
21// ---------------------------------------------------------------------------
22
23type MatchStateOptions<T> = {
24 loading?: string;
25 empty: string | null;
26 ready: (items: ReadonlyArray<T>) => ReactNode;
27 filteredCount?: number;
28};
29
30export function matchState<T>(
31 state: EntityState<T>,
32 options: MatchStateOptions<T>,
33): ReactNode {
34 if (state.state === "loading") {
35 return <LoadingState message={options.loading ?? "Loading..."} />;
36 }
37
38 const isEmpty =
39 options.filteredCount !== undefined
40 ? options.filteredCount === 0
41 : state.items.length === 0;
42
43 return (
44 <>
45 {state.state === "error" ? (
46 <StatusMessage message={state.message} variant="error" />
47 ) : null}
48 {isEmpty
49 ? options.empty !== null
50 ? <EmptyState message={options.empty} />
51 : null
52 : options.ready(state.items)}
53 </>
54 );
55}
apps/web/components/shared/page-header.tsx+21−0
@@ -0,0 +1,21 @@
1import type { ReactNode } from "react";
2
3type PageHeaderProps = {
4 title: string;
5 description?: string;
6 actions?: ReactNode;
7};
8
9export function PageHeader({ title, description, actions }: PageHeaderProps) {
10 return (
11 <div className="flex items-start justify-between border-b border-border px-6 py-4">
12 <div className="min-w-0">
13 <h1 className="font-display text-lg font-semibold tracking-tight">{title}</h1>
14 {description ? (
15 <p className="mt-0.5 text-[13px] text-muted-foreground">{description}</p>
16 ) : null}
17 </div>
18 {actions ? <div className="flex shrink-0 items-center gap-2">{actions}</div> : null}
19 </div>
20 );
21}
apps/web/components/shared/status-message.tsx+25−0
@@ -0,0 +1,25 @@
1import { cn } from "../../lib/utils";
2
3type StatusMessageProps = {
4 message: string | null;
5 variant?: "info" | "error";
6 className?: string;
7};
8
9export function StatusMessage({ message, variant = "info", className }: StatusMessageProps) {
10 if (!message) return null;
11
12 return (
13 <div
14 className={cn(
15 "rounded-md border px-3 py-2 text-[13px]",
16 variant === "error"
17 ? "border-destructive/25 bg-destructive/5 text-destructive"
18 : "border-border bg-muted/40 text-muted-foreground",
19 className,
20 )}
21 >
22 {message}
23 </div>
24 );
25}
apps/web/components/shell/app-shell.tsx+205−0
@@ -0,0 +1,205 @@
1"use client";
2
3import Link from "next/link";
4import { usePathname } from "next/navigation";
5import type { ReactNode } from "react";
6
7import { cn } from "../../lib/utils";
8import { ThemeSwitcher } from "./theme-switcher";
9import { WorkspaceSelector } from "./workspace-selector";
10
11type NavItem = {
12 href: string;
13 label: string;
14 icon: ReactNode;
15 matchPrefixes?: ReadonlyArray<string>;
16 children?: ReadonlyArray<NavItem>;
17 badge?: ReactNode;
18};
19
20const NAV_ITEMS: ReadonlyArray<NavItem> = [
21 {
22 href: "/tools",
23 label: "Tools",
24 icon: (
25 <svg viewBox="0 0 16 16" fill="none" className="size-4">
26 <path
27 d="M10.5 2.5L13.5 5.5L6 13H3V10L10.5 2.5Z"
28 stroke="currentColor"
29 strokeWidth="1.3"
30 strokeLinejoin="round"
31 />
32 </svg>
33 ),
34 },
35 {
36 href: "/credentials",
37 label: "Credentials",
38 icon: (
39 <svg viewBox="0 0 16 16" fill="none" className="size-4">
40 <rect x="2" y="6" width="12" height="7" rx="1.5" stroke="currentColor" strokeWidth="1.3" />
41 <path d="M5 6V4.5a3 3 0 016 0V6" stroke="currentColor" strokeWidth="1.3" />
42 <circle cx="8" cy="10" r="1" fill="currentColor" />
43 </svg>
44 ),
45 },
46 {
47 href: "/policies",
48 label: "Policies",
49 icon: (
50 <svg viewBox="0 0 16 16" fill="none" className="size-4">
51 <path
52 d="M8 1.5L13 4v4c0 3-2.5 5-5 6.5C5.5 13 3 11 3 8V4l5-2.5z"
53 stroke="currentColor"
54 strokeWidth="1.3"
55 strokeLinejoin="round"
56 />
57 <path d="M6 8l1.5 1.5L10.5 6" stroke="currentColor" strokeWidth="1.3" strokeLinecap="round" strokeLinejoin="round" />
58 </svg>
59 ),
60 },
61 {
62 href: "/storage",
63 label: "Storage",
64 icon: (
65 <svg viewBox="0 0 16 16" fill="none" className="size-4">
66 <ellipse cx="8" cy="4" rx="5" ry="2" stroke="currentColor" strokeWidth="1.3" />
67 <path d="M3 4v8c0 1.1 2.24 2 5 2s5-.9 5-2V4" stroke="currentColor" strokeWidth="1.3" />
68 <path d="M3 8c0 1.1 2.24 2 5 2s5-.9 5-2" stroke="currentColor" strokeWidth="1.3" />
69 </svg>
70 ),
71 },
72 {
73 href: "/approvals",
74 label: "Approvals",
75 icon: (
76 <svg viewBox="0 0 16 16" fill="none" className="size-4">
77 <circle cx="8" cy="8" r="6" stroke="currentColor" strokeWidth="1.3" />
78 <path d="M5.5 8l2 2 3.5-4" stroke="currentColor" strokeWidth="1.3" strokeLinecap="round" strokeLinejoin="round" />
79 </svg>
80 ),
81 },
82 {
83 href: "/settings",
84 label: "Settings",
85 icon: (
86 <svg viewBox="0 0 16 16" fill="none" className="size-4">
87 <circle cx="8" cy="8" r="2" stroke="currentColor" strokeWidth="1.3" />
88 <path
89 d="M8 1v2M8 13v2M1 8h2M13 8h2M3 3l1.4 1.4M11.6 11.6L13 13M13 3l-1.4 1.4M4.4 11.6L3 13"
90 stroke="currentColor"
91 strokeWidth="1.3"
92 strokeLinecap="round"
93 />
94 </svg>
95 ),
96 },
97];
98
99const isActivePath = (pathname: string, item: NavItem): boolean => {
100 if (item.matchPrefixes) {
101 return item.matchPrefixes.some((prefix) => pathname.startsWith(prefix));
102 }
103 if (item.href === "/") {
104 return pathname === "/";
105 }
106 return pathname.startsWith(item.href);
107};
108
109type AppShellProps = {
110 children: ReactNode;
111 authEnabled: boolean;
112 approvalsBadge?: ReactNode;
113};
114
115export function AppShell({
116 children,
117 authEnabled,
118 approvalsBadge,
119}: AppShellProps) {
120 const pathname = usePathname();
121
122 // Compact chrome: pages that manage their own scroll (full-viewport layout)
123 const useCompactChrome =
124 pathname.startsWith("/tools") ||
125 pathname.startsWith("/approvals");
126 return (
127 <div className="flex h-screen overflow-hidden">
128 {/* ---- Sidebar ---- */}
129 <aside className="flex w-[220px] shrink-0 flex-col border-r border-sidebar-border bg-sidebar">
130 {/* Logo / brand */}
131 <div className="border-b border-sidebar-border px-3 py-2">
132 <div className="min-w-0">
133 <WorkspaceSelector />
134 </div>
135 </div>
136
137 {/* Nav items */}
138 <nav className="flex-1 overflow-y-auto px-2 py-2">
139 <ul className="space-y-0.5">
140 {NAV_ITEMS.map((item) => {
141 const active = isActivePath(pathname, item);
142 const isApprovals = item.href === "/approvals";
143

62 more lines aren’t shown here.

apps/web/components/shell/theme-switcher.tsx+82−0

This diff is large: its 83 lines aren’t shown here.

apps/web/components/shell/workspace-selector.tsx+557−0

This diff is large: its 558 lines aren’t shown here.

apps/web/components/storage/storage-view.tsx+852−0

This diff is large: its 853 lines aren’t shown here.

apps/web/components/tools/install-configs.ts+16−0

This diff is large: its 17 lines aren’t shown here.

apps/web/components/tools/schema-fields.tsx+399−0

This diff is large: its 400 lines aren’t shown here.

apps/web/components/tools/source-favicon.tsx+82−0

This diff is large: its 83 lines aren’t shown here.

apps/web/components/tools/source-management-panel.tsx+945−0

This diff is large: its 946 lines aren’t shown here.

apps/web/components/tools/tools-view.tsx+1333−0

This diff is large: its 1334 lines aren’t shown here.

apps/web/components/ui/badge.tsx+29−0

This diff is large: its 30 lines aren’t shown here.

apps/web/components/ui/button.tsx+40−0

This diff is large: its 41 lines aren’t shown here.

apps/web/components/ui/card.tsx+41−0

This diff is large: its 42 lines aren’t shown here.

apps/web/components/ui/input.tsx+16−0

This diff is large: its 17 lines aren’t shown here.

apps/web/components/ui/select.tsx+17−0

This diff is large: its 18 lines aren’t shown here.

apps/web/lib/control-plane/atoms/approvals.ts+70−0

This diff is large: its 71 lines aren’t shown here.

apps/web/lib/control-plane/atoms/credentials.ts+87−0

This diff is large: its 88 lines aren’t shown here.

apps/web/lib/control-plane/atoms/entity.ts+80−0

This diff is large: its 81 lines aren’t shown here.

apps/web/lib/control-plane/atoms/index.ts+108−0

This diff is large: its 109 lines aren’t shown here.

apps/web/lib/control-plane/atoms/keys.ts+22−0

This diff is large: its 23 lines aren’t shown here.

apps/web/lib/control-plane/atoms/policies.ts+92−0

This diff is large: its 93 lines aren’t shown here.

apps/web/lib/control-plane/atoms/settings.ts+78−0

This diff is large: its 79 lines aren’t shown here.

apps/web/lib/control-plane/atoms/sources.ts+141−0

This diff is large: its 142 lines aren’t shown here.

apps/web/lib/control-plane/atoms/storage.ts+124−0

This diff is large: its 125 lines aren’t shown here.

apps/web/lib/control-plane/atoms/tools.ts+63−0

This diff is large: its 64 lines aren’t shown here.

apps/web/lib/control-plane/client.ts+32−0

This diff is large: its 33 lines aren’t shown here.

apps/web/lib/control-plane/legacy-source.ts+266−0

This diff is large: its 267 lines aren’t shown here.

apps/web/lib/hooks/use-workspace.tsx+44−0

This diff is large: its 45 lines aren’t shown here.

apps/web/lib/mcp/oauth-fetch.ts+112−0

This diff is large: its 113 lines aren’t shown here.

apps/web/lib/mcp/oauth-popup.ts+128−0

This diff is large: its 129 lines aren’t shown here.

apps/web/lib/mcp/oauth-provider.ts+249−0

This diff is large: its 250 lines aren’t shown here.

apps/web/lib/mcp/oauth-request.ts+59−0

This diff is large: its 60 lines aren’t shown here.

apps/web/lib/mcp/oauth-url.ts+30−0

This diff is large: its 31 lines aren’t shown here.

apps/web/lib/tool/openapi-schema-refs.ts+130−0

This diff is large: its 131 lines aren’t shown here.

apps/web/lib/tool/schema-traverse.ts+386−0

This diff is large: its 387 lines aren’t shown here.

apps/web/lib/tools/source-helpers.ts+129−0

This diff is large: its 130 lines aren’t shown here.

apps/web/lib/utils.ts+35−0

This diff is large: its 36 lines aren’t shown here.

apps/web/lib/workos.ts+85−0

This diff is large: its 86 lines aren’t shown here.

apps/web/middleware.ts+24−0

This diff is large: its 25 lines aren’t shown here.

apps/web/next-env.d.ts+6−0

This diff is large: its 7 lines aren’t shown here.

apps/web/next.config.ts+11−0

This diff is large: its 12 lines aren’t shown here.

apps/web/node_modules/.bin/next+1−0

This diff is large: its 2 lines aren’t shown here.

apps/web/node_modules/.bin/tldts+1−0

This diff is large: its 2 lines aren’t shown here.

apps/web/node_modules/.bin/vite+1−0

This diff is large: its 2 lines aren’t shown here.

apps/web/node_modules/.bin/vitest+1−0

This diff is large: its 2 lines aren’t shown here.

apps/web/node_modules/.vite/deps/@effect-atom_atom-react.js+294−0

This diff is large: its 295 lines aren’t shown here.

apps/web/node_modules/.vite/deps/@effect-atom_atom-react.js.map+7−0

This diff is large: its 8 lines aren’t shown here.

apps/web/node_modules/.vite/deps/@effect-atom_atom.js+34−0

This diff is large: its 35 lines aren’t shown here.

apps/web/node_modules/.vite/deps/@effect-atom_atom.js.map+7−0

This diff is large: its 8 lines aren’t shown here.

apps/web/node_modules/.vite/deps/@effect_platform.js+6731−0

This diff is large: its 6732 lines aren’t shown here.

This diff is larger than a page shows: the files after these aren’t listed. Clone the repository to see all of it.

Keyboard shortcuts

General

Show keyboard shortcuts
?
Focus the current search
/

Issues and pull requests

Open filters
f

Issues, pull requests and Inbox

Select next item
j↓
Select previous item
k↑
Open selected item
Enter
Dismiss filters or clear selection
Esc

Repository code

Go to file
t