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 @@
1+import { describe, expect, it } from "@effect/vitest";
2+import * as Effect from "effect/Effect";
3+import { parse as parseYaml } from "yaml";
4+
5+import { extractOpenApiManifest } from "./parse-openapi";
6+
7+const cloudflareSpecUrl = "https://raw.githubusercontent.com/cloudflare/api-schemas/main/openapi.yaml";
8+const vercelSpecUrl = "https://openapi.vercel.sh/";
9+const httpMethods = ["get", "put", "post", "delete", "patch", "head", "options", "trace"] as const;
10+
11+const isRecord = (value: unknown): value is Record<string, unknown> =>
12+ typeof value === "object" && value !== null && !Array.isArray(value);
13+
14+const 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+
27+const 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+
36+const 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+
58+const unescapeJsonPointer = (value: string): string =>
59+ value.replace(/~1/g, "/").replace(/~0/g, "~");
60+
61+const 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+
92+const 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+
105+const 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+
127+const 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+
140+const 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+
149+const 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+
177+const 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+
213+const isUnknownLikeSchema = (value: unknown): boolean => !hasMeaningfulSchemaShape(value);
214+
215+type OperationExpectation = {
216+ parameterSchemas: Record<string, unknown>;
217+ requestBodySchema: unknown;
218+ responseSchema: unknown;
219+};
220+
221+const operationSignature = (method: string, path: string): string =>
222+ `${method.toLowerCase()} ${path}`;
223+
224+const 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+
289+const 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+
370+describe("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 @@
1+import { createHash } from "node:crypto";
2+
3+import { ConvexHttpClient } from "convex/browser";
4+import { parse as parseYaml } from "yaml";
5+
6+const maxBodyBytes = 256 * 1024;
7+const httpMethods = ["get", "put", "post", "delete", "patch", "head", "options", "trace"] as const;
8+
9+type HttpMethod = typeof httpMethods[number];
10+type OpenApiParameterLocation = "path" | "query" | "header" | "cookie";
11+
12+type 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+
39+type OpenApiManifest = {
40+ sourceHash: string;
41+ tools: Array<ExtractedTool>;
42+ refHintTable: Record<string, string>;
43+};
44+
45+const parseJsonDocument = (input: string): unknown => JSON.parse(input);
46+const parseYamlDocument = (input: string): unknown => parseYaml(input);
47+
48+const isRecord = (value: unknown): value is Record<string, unknown> =>
49+ typeof value === "object" && value !== null && !Array.isArray(value);
50+
51+const 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+
66+const hashUnknown = (value: unknown): string =>
67+ createHash("sha256").update(stableStringify(value)).digest("hex").slice(0, 16);
68+
69+const 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+
78+const normalizeSegment = (value: string): string =>
79+ value
80+ .toLowerCase()
81+ .replace(/[^a-z0-9]+/g, "_")
82+ .replace(/^_+|_+$/g, "");
83+
84+const normalizeToolId = (value: string): string =>
85+ value
86+ .toLowerCase()
87+ .replace(/[^a-z0-9]+/g, ".")
88+ .replace(/\.+/g, ".")
89+ .replace(/^\.|\.$/g, "");
90+
91+const escapeJsonPointer = (value: string): string =>
92+ value.replace(/~/g, "~0").replace(/\//g, "~1");
93+
94+const unescapeJsonPointer = (value: string): string =>
95+ value.replace(/~1/g, "/").replace(/~0/g, "~");
96+
97+const 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+
128+const 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+
141+const 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+
163+const 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+
196+const 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+
242+const 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+
283+const 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+
348+const 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+
378+const 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+
396+const 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+
430+export 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+
566+const 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+
587+const 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+
609+const 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+
618+const 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+
628+const sourceNamespace = (sourceName: string, sourceId: string): string => {
629+ const sourceIdSuffix = sourceId.slice(-6).toLowerCase();
630+ return `${normalizeNamespacePart(sourceName)}_${sourceIdSuffix}`;
631+};
632+
633+const parseSourceEnabled = (value: unknown): boolean =>
634+ typeof value === "boolean" ? value : true;
635+
636+const 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+
696+const 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+
800+export const config = {
801+ api: {
802+ bodyParser: false,
803+ },
804+};
805+
806+export 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+
3+CLI 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 @@
1+export {};
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+
3+Convex remote server app scaffold for Executor v2.
4+
5+Current 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+
3+Write your Convex functions here.
4+See https://docs.convex.dev/functions for more.
5+
6+A query function that takes two arguments looks like:
7+
8+```ts
9+// convex/myFunctions.ts
10+import { query } from "./_generated/server";
11+import { v } from "convex/values";
12+
13+export 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+
36+Using this query function in a React component looks like:
37+
38+```ts
39+const data = useQuery(api.myFunctions.myQueryFunction, {
40+ first: 10,
41+ second: "hello",
42+});
43+```
44+
45+A mutation function looks like:
46+
47+```ts
48+// convex/myFunctions.ts
49+import { mutation } from "./_generated/server";
50+import { v } from "convex/values";
51+
52+export 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+
73+Using this mutation function in a React component looks like:
74+
75+```ts
76+const mutation = useMutation(api.myFunctions.myMutationFunction);
77+function 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+
88+Use the Convex CLI to push your functions to a deployment. See everything
89+the Convex CLI can do by running `npx convex -h` in your project root
90+directory. 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+
11+import type * as controlPlane from "../controlPlane.js";
12+import type * as control_plane_actor from "../control_plane/actor.js";
13+import type * as control_plane_approvals from "../control_plane/approvals.js";
14+import type * as control_plane_credentials from "../control_plane/credentials.js";
15+import type * as control_plane_errors from "../control_plane/errors.js";
16+import type * as control_plane_http from "../control_plane/http.js";
17+import type * as control_plane_openapi_ingest from "../control_plane/openapi_ingest.js";
18+import type * as control_plane_organizations from "../control_plane/organizations.js";
19+import type * as control_plane_policies from "../control_plane/policies.js";
20+import type * as control_plane_service from "../control_plane/service.js";
21+import type * as control_plane_sources from "../control_plane/sources.js";
22+import type * as control_plane_storage from "../control_plane/storage.js";
23+import type * as control_plane_tool_registry from "../control_plane/tool_registry.js";
24+import type * as control_plane_tools from "../control_plane/tools.js";
25+import type * as control_plane_workspaces from "../control_plane/workspaces.js";
26+import type * as credential_crypto from "../credential_crypto.js";
27+import type * as credential_resolver from "../credential_resolver.js";
28+import type * as executor from "../executor.js";
29+import type * as http from "../http.js";
30+import type * as mcp from "../mcp.js";
31+import type * as mcp_auth from "../mcp_auth.js";
32+import type * as run_executor from "../run_executor.js";
33+import type * as runtimeCallbacks from "../runtimeCallbacks.js";
34+import type * as runtime_adapter from "../runtime_adapter.js";
35+import type * as runtime_execution_port from "../runtime_execution_port.js";
36+import type * as source_tool_registry from "../source_tool_registry.js";
37+import type * as task_runs from "../task_runs.js";
38+import type * as workflow from "../workflow.js";
39+
40+import type {
41+ ApiFromModules,
42+ FilterApi,
43+ FunctionReference,
44+} from "convex/server";
45+
46+declare 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+ */
85+export 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+ */
98+export declare const internal: FilterApi<
99+ typeof fullApi,
100+ FunctionReference<any, "internal">
101+>;
102+
103+export 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+
11+import { 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+ */
21+export const api = anyApi;
22+export const internal = anyApi;
23+export 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+
11+import type {
12+ DataModelFromSchemaDefinition,
13+ DocumentByName,
14+ TableNamesInDataModel,
15+ SystemTableNames,
16+} from "convex/server";
17+import type { GenericId } from "convex/values";
18+import schema from "../schema.js";
19+
20+/**
21+ * The names of all of your Convex tables.
22+ */
23+export 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+ */
30+export 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+ */
48+export 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+ */
60+export 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+
11+import {
12+ ActionBuilder,
13+ HttpActionBuilder,
14+ MutationBuilder,
15+ QueryBuilder,
16+ GenericActionCtx,
17+ GenericMutationCtx,
18+ GenericQueryCtx,
19+ GenericDatabaseReader,
20+ GenericDatabaseWriter,
21+} from "convex/server";
22+import 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+ */
32+export 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+ */
42+export 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+ */
52+export 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+ */
62+export 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+ */
75+export 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+ */
83+export 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+ */
96+export 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+ */
107+export 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+ */
115+export 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+ */
123+export 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+ */
132+export 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+ */
143+export 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+
11+import {
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+ */
29+export 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+ */
39+export 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+ */
49+export 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+ */
59+export 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+ */
72+export 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+ */
80+export 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+ */
93+export const httpAction = httpActionGeneric;
apps/convex/convex/controlPlane.ts+72−0
@@ -0,0 +1,72 @@
1+import {
2+ listApprovals as listApprovalsImpl,
3+ resolveApproval as resolveApprovalImpl,
4+} from "./control_plane/approvals";
5+import {
6+ listCredentialBindings as listCredentialBindingsImpl,
7+ removeCredentialBinding as removeCredentialBindingImpl,
8+ upsertCredentialBinding as upsertCredentialBindingImpl,
9+} from "./control_plane/credentials";
10+import { controlPlaneHttpHandler as controlPlaneHttpHandlerImpl } from "./control_plane/http";
11+import {
12+ listOrganizations as listOrganizationsImpl,
13+ upsertOrganization as upsertOrganizationImpl,
14+} from "./control_plane/organizations";
15+import {
16+ listPolicies as listPoliciesImpl,
17+ removePolicy as removePolicyImpl,
18+ upsertPolicy as upsertPolicyImpl,
19+} from "./control_plane/policies";
20+import {
21+ listSources as listSourcesImpl,
22+ removeSource as removeSourceImpl,
23+ upsertSource as upsertSourceImpl,
24+} from "./control_plane/sources";
25+import {
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";
35+import {
36+ getToolDetail as getToolDetailImpl,
37+ listSourceTools as listSourceToolsImpl,
38+ listWorkspaceTools as listWorkspaceToolsImpl,
39+} from "./control_plane/tools";
40+import {
41+ listWorkspaces as listWorkspacesImpl,
42+ upsertWorkspace as upsertWorkspaceImpl,
43+} from "./control_plane/workspaces";
44+
45+export const listSources = listSourcesImpl;
46+export const upsertSource = upsertSourceImpl;
47+export const removeSource = removeSourceImpl;
48+export const listCredentialBindings = listCredentialBindingsImpl;
49+export const upsertCredentialBinding = upsertCredentialBindingImpl;
50+export const removeCredentialBinding = removeCredentialBindingImpl;
51+export const listPolicies = listPoliciesImpl;
52+export const upsertPolicy = upsertPolicyImpl;
53+export const removePolicy = removePolicyImpl;
54+export const listOrganizations = listOrganizationsImpl;
55+export const upsertOrganization = upsertOrganizationImpl;
56+export const listWorkspaces = listWorkspacesImpl;
57+export const upsertWorkspace = upsertWorkspaceImpl;
58+export const listWorkspaceTools = listWorkspaceToolsImpl;
59+export const listSourceTools = listSourceToolsImpl;
60+export const getToolDetail = getToolDetailImpl;
61+export const listStorageInstances = listStorageInstancesImpl;
62+export const openStorageInstance = openStorageInstanceImpl;
63+export const closeStorageInstance = closeStorageInstanceImpl;
64+export const removeStorageInstance = removeStorageInstanceImpl;
65+export const listStorageDirectory = listStorageDirectoryImpl;
66+export const readStorageFile = readStorageFileImpl;
67+export const listStorageKv = listStorageKvImpl;
68+export const queryStorageSql = queryStorageSqlImpl;
69+export const listApprovals = listApprovalsImpl;
70+export const resolveApproval = resolveApprovalImpl;
71+
72+export const controlPlaneHttpHandler = controlPlaneHttpHandlerImpl;
apps/convex/convex/control_plane/actor.ts+307−0
@@ -0,0 +1,307 @@
1+import {
2+ ControlPlaneActorResolverLive,
3+ deriveWorkspaceMembershipsForPrincipal,
4+ requirePrincipalFromHeaders,
5+} from "@executor-v2/management-api";
6+import { ActorUnauthenticatedError, makeActor } from "@executor-v2/domain";
7+import {
8+ OrganizationMembershipSchema,
9+ WorkspaceSchema,
10+ type OrganizationMembership,
11+ type Workspace,
12+} from "@executor-v2/schema";
13+import { v } from "convex/values";
14+import * as Effect from "effect/Effect";
15+import * as Schema from "effect/Schema";
16+
17+import { internal } from "../_generated/api";
18+import {
19+ internalMutation,
20+ internalQuery,
21+ type ActionCtx,
22+} from "../_generated/server";
23+
24+const decodeWorkspace = Schema.decodeUnknownSync(WorkspaceSchema);
25+const decodeOrganizationMembership = Schema.decodeUnknownSync(
26+ OrganizationMembershipSchema,
27+);
28+
29+const stripConvexSystemFields = (
30+ value: Record<string, unknown>,
31+): Record<string, unknown> => {
32+ const { _id: _ignoredId, _creationTime: _ignoredCreationTime, ...rest } = value;
33+ return rest;
34+};
35+
36+const 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+
47+export 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+
67+export 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+
85+export 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+
113+export 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+
215+const 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+
227+export 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 @@
1+import {
2+ type ResolveApprovalPayload,
3+} from "@executor-v2/management-api";
4+import {
5+ ApprovalSchema,
6+ type Approval,
7+} from "@executor-v2/schema";
8+import { v } from "convex/values";
9+import * as Schema from "effect/Schema";
10+
11+import { mutation, query } from "../_generated/server";
12+
13+const decodeApproval = Schema.decodeUnknownSync(ApprovalSchema);
14+
15+const stripConvexSystemFields = (
16+ value: Record<string, unknown>,
17+): Record<string, unknown> => {
18+ const { _id: _ignoredId, _creationTime: _ignoredCreationTime, ...rest } = value;
19+ return rest;
20+};
21+
22+const approvalStatusValidator = v.union(
23+ v.literal("approved"),
24+ v.literal("denied"),
25+);
26+
27+const sortApprovals = (approvals: ReadonlyArray<Approval>): Array<Approval> =>
28+ [...approvals].sort((left, right) => right.requestedAt - left.requestedAt);
29+
30+export 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+
50+export 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 @@
1+import {
2+ buildCredentialHeaders,
3+ selectOAuthAccessToken,
4+} from "@executor-v2/engine";
5+import { type UpsertCredentialBindingPayload } from "@executor-v2/management-api";
6+import {
7+ OAuthTokenSchema,
8+ SourceCredentialBindingSchema,
9+ type OAuthToken,
10+ type SourceCredentialBinding,
11+} from "@executor-v2/schema";
12+import { v } from "convex/values";
13+import * as Schema from "effect/Schema";
14+
15+import { internal } from "../_generated/api";
16+import { decryptSecretValue, encryptSecretValue } from "../credential_crypto";
17+import {
18+ action,
19+ internalAction,
20+ internalMutation,
21+ internalQuery,
22+ mutation,
23+ query,
24+ type MutationCtx,
25+ type QueryCtx,
26+} from "../_generated/server";
27+
28+const runtimeInternal = internal as any;
29+
30+const decodeSourceCredentialBinding = Schema.decodeUnknownSync(
31+ SourceCredentialBindingSchema,
32+);
33+const decodeOAuthToken = Schema.decodeUnknownSync(OAuthTokenSchema);
34+
35+const stripConvexSystemFields = (
36+ value: Record<string, unknown>,
37+): Record<string, unknown> => {
38+ const { _id: _ignoredId, _creationTime: _ignoredCreationTime, ...rest } = value;
39+ return rest;
40+};
41+
42+const toSourceCredentialBinding = (
43+ document: Record<string, unknown>,
44+): SourceCredentialBinding =>
45+ decodeSourceCredentialBinding(stripConvexSystemFields(document));
46+
47+const credentialProviderValidator = v.union(
48+ v.literal("api_key"),
49+ v.literal("bearer"),
50+ v.literal("oauth2"),
51+ v.literal("custom"),
52+);
53+
54+const credentialSecretProviderValidator = v.literal("local");
55+
56+const credentialScopeTypeValidator = v.union(
57+ v.literal("workspace"),
58+ v.literal("organization"),
59+ v.literal("account"),
60+);
61+
62+const 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+
75+const 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+
89+const 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+
105+const 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+
115+const toOAuthToken = (document: Record<string, unknown>): OAuthToken =>
116+ decodeOAuthToken(stripConvexSystemFields(document));
117+
118+const sourceSlug = (value: string): string =>
119+ value
120+ .toLowerCase()
121+ .replaceAll(/[^a-z0-9]+/g, "_")
122+ .replaceAll(/^_+|_+$/g, "");
123+
124+const 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+
133+const 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+
168+const 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+
186+const 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+
222+const 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+
232+const defaultSecretProvider = (): "local" => "local";
233+
234+const resolveSecretRefForHeaders = async (
235+ binding: SourceCredentialBinding,
236+): Promise<string> => {
237+ requireLocalSecretProvider(binding.secretProvider);
238+ return await decryptSecretValue(binding.secretRef);
239+};
240+
241+const 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+
328+const 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+
339+export 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+
349+export 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+
383+export 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+
423+export 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+
491+export 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+
525+export 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 @@
1+import { SourceStoreError } from "@executor-v2/persistence-ports";
2+
3+type ControlPlaneErrorCode =
4+ | "bad_request"
5+ | "unauthorized"
6+ | "forbidden"
7+ | "not_found"
8+ | "method_not_allowed"
9+ | "internal";
10+
11+type ControlPlaneErrorResponse = {
12+ ok: false;
13+ error: {
14+ code: ControlPlaneErrorCode;
15+ message: string;
16+ details: string | null;
17+ };
18+};
19+
20+const renderCause = (cause: unknown): string => String(cause);
21+
22+export 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+
35+const 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+
52+export 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+
69+const isJsonResponse = (response: Response): boolean =>
70+ response.headers.get("content-type")?.toLowerCase().includes("application/json") ?? false;
71+
72+export 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 @@
1+import {
2+ ControlPlaneService,
3+ controlPlaneOpenApiSpec,
4+ makeControlPlaneWebHandler,
5+} from "@executor-v2/management-api";
6+import * as Effect from "effect/Effect";
7+import * as Layer from "effect/Layer";
8+
9+import { httpAction, type ActionCtx } from "../_generated/server";
10+import { ConvexControlPlaneActorLive } from "./actor";
11+import {
12+ controlPlaneErrorResponse,
13+ normalizeControlPlaneErrorResponse,
14+ toSourceStoreError,
15+} from "./errors";
16+import { makeConvexControlPlaneService } from "./service";
17+
18+const isOpenApiRequest = (request: Request): boolean =>
19+ new URL(request.url).pathname === "/v1/openapi.json";
20+
21+const 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+
65+export 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+
3+import { createHash } from "node:crypto";
4+
5+import { type Source } from "@executor-v2/schema";
6+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
7+import { SSEClientTransport } from "@modelcontextprotocol/sdk/client/sse.js";
8+import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
9+import { v } from "convex/values";
10+import * as Effect from "effect/Effect";
11+import * as Schema from "effect/Schema";
12+
13+import { internal } from "../_generated/api";
14+import { internalAction } from "../_generated/server";
15+
16+const runtimeInternal = internal as any;
17+
18+const graphqlExtractorVersion = "graphql_v1";
19+const mcpExtractorVersion = "mcp_v1";
20+const writeBatchSize = 500;
21+
22+const graphqlSchemaRootsQuery = `query SchemaRoots {
23+ __schema {
24+ queryType { name }
25+ mutationType { name }
26+ }
27+}`;
28+
29+const 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+
56+type 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+
66+type McpIngestTool = {
67+ toolId: string;
68+ name: string;
69+ description: string | null;
70+ toolName: string;
71+ operationHash: string;
72+ invocationJson: string;
73+};
74+
75+type McpTransport = "sse" | "streamable-http";
76+
77+type McpConnection = {
78+ client: Client;
79+ close: () => Promise<void>;
80+ transport: McpTransport;
81+};
82+
83+const SourceIngestStatusSchema = Schema.Union(
84+ Schema.Literal("error"),
85+ Schema.Literal("auth_required"),
86+);
87+
88+type SourceIngestStatus = typeof SourceIngestStatusSchema.Type;
89+
90+class SourceIngestError extends Schema.TaggedError<SourceIngestError>()(
91+ "SourceIngestError",
92+ {
93+ status: SourceIngestStatusSchema,
94+ message: Schema.String,
95+ },
96+) {}
97+
98+type 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+
108+const isUnknownRecord = (value: unknown): value is Record<string, unknown> =>
109+ typeof value === "object" && value !== null && !Array.isArray(value);
110+
111+const 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+
120+const 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+
135+const hashUnknown = (value: unknown): string =>
136+ createHash("sha256").update(stableStringify(value)).digest("hex").slice(0, 16);
137+
138+const 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+
147+const 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+
156+const 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+
166+const sourceNamespace = (source: Source): string => {
167+ const sourceIdSuffix = source.id.slice(-6).toLowerCase();
168+ return `${normalizeNamespacePart(source.name)}_${sourceIdSuffix}`;
169+};
170+
171+const sourceToolPath = (source: Source, toolId: string): string =>
172+ `${sourceNamespace(source)}.${toolId}`;
173+
174+const 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+
180+const 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+
199+const 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+
223+const 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+
232+const safeJsonStringify = (value: unknown): string | null => {
233+ try {
234+ return JSON.stringify(value);
235+ } catch {
236+ return null;
237+ }
238+};
239+
240+const 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+
251+const 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+
261+const 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+
285+const isRequiredType = (typeRef: unknown): boolean =>
286+ isUnknownRecord(typeRef) && normalizeString(typeRef.kind) === "NON_NULL";
287+
288+const 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+
297+const 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+
333+const 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+
352+const 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+
361+const collectMcpHeadersFromSourceConfig = (source: Source): Record<string, string> => {
362+ const config = parseSourceConfig(source.configJson);
363+ return {
364+ ...collectConfiguredHeadersFromSourceConfig(config),
365+ ...collectAuthHeadersFromSourceConfig(config),
366+ };
367+};
368+
369+const 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+
395+const graphqlAuthErrorCodes = new Set(["unauthenticated", "forbidden", "unauthorized"]);
396+
397+const 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+
421+const looksLikeAuthErrorMessage = (value: string): boolean => {
422+ const message = value.toLowerCase();
423+ return message.includes("unauthor") || message.includes("forbidden") || message.includes("auth required");
424+};
425+
426+const 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+
435+const 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+
449+const 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+
500+const 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+
535+const 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+
569+const 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+
587+const 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+
685+const 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+
700+const 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+
720+const 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+
736+const 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+
811+const 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+
823+const 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+
831+const 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+
849+const 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+
906+const formatError = (cause: unknown): string =>
907+ cause instanceof Error ? cause.message : String(cause);
908+
909+const 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+
922+const openApiParserUrl = process.env.OPENAPI_PARSE_API_URL?.trim() ?? "";
923+const openApiParserToken = process.env.OPENAPI_PARSE_API_TOKEN?.trim() ?? "";
924+
925+type 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+
937+const 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+
1016+type IngestOptions = {
1017+ rebuildIndex: boolean;
1018+ stageArtifactWrites: boolean;
1019+};
1020+
1021+const 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+
1042+const 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+
1199+const 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+
1374+export 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 @@
1+import { type UpsertOrganizationPayload } from "@executor-v2/management-api";
2+import {
3+ OrganizationSchema,
4+ type Organization,
5+ type OrganizationMembership,
6+} from "@executor-v2/schema";
7+import { v } from "convex/values";
8+import * as Schema from "effect/Schema";
9+
10+import { mutation, query } from "../_generated/server";
11+
12+const decodeOrganization = Schema.decodeUnknownSync(OrganizationSchema);
13+
14+const stripConvexSystemFields = (
15+ value: Record<string, unknown>,
16+): Record<string, unknown> => {
17+ const { _id: _ignoredId, _creationTime: _ignoredCreationTime, ...rest } = value;
18+ return rest;
19+};
20+
21+const toOrganization = (document: Record<string, unknown>): Organization =>
22+ decodeOrganization(stripConvexSystemFields(document));
23+
24+const organizationStatusValidator = v.union(
25+ v.literal("active"),
26+ v.literal("suspended"),
27+ v.literal("archived"),
28+);
29+
30+const 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+
44+export 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+
55+export 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 @@
1+import { type UpsertPolicyPayload } from "@executor-v2/management-api";
2+import { PolicySchema, type Policy } from "@executor-v2/schema";
3+import { v } from "convex/values";
4+import * as Schema from "effect/Schema";
5+
6+import { mutation, query } from "../_generated/server";
7+
8+const decodePolicy = Schema.decodeUnknownSync(PolicySchema);
9+
10+const stripConvexSystemFields = (
11+ value: Record<string, unknown>,
12+): Record<string, unknown> => {
13+ const { _id: _ignoredId, _creationTime: _ignoredCreationTime, ...rest } = value;
14+ return rest;
15+};
16+
17+const toPolicy = (document: Record<string, unknown>): Policy =>
18+ decodePolicy(stripConvexSystemFields(document));
19+
20+const policyDecisionValidator = v.union(
21+ v.literal("allow"),
22+ v.literal("require_approval"),
23+ v.literal("deny"),
24+);
25+
26+const 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+
38+export 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+
54+export 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+
96+export 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 @@
1+import {
2+ ControlPlaneService,
3+ type ControlPlaneServiceShape,
4+} from "@executor-v2/management-api";
5+import * as Effect from "effect/Effect";
6+
7+import { api } from "../_generated/api";
8+import type { ActionCtx } from "../_generated/server";
9+import { toSourceStoreError } from "./errors";
10+
11+export 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 @@
1+import { type UpsertSourcePayload } from "@executor-v2/management-api";
2+import { SourceSchema, type Source } from "@executor-v2/schema";
3+import { v } from "convex/values";
4+import * as Schema from "effect/Schema";
5+
6+import { internal } from "../_generated/api";
7+import { action, internalQuery, internalMutation, mutation, query } from "../_generated/server";
8+
9+const runtimeInternal = internal as any;
10+
11+const decodeSource = Schema.decodeUnknownSync(SourceSchema);
12+
13+const sourceStoreKey = (source: Source): string => `${source.workspaceId}:${source.id}`;
14+
15+const 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+
27+const toSource = (document: Record<string, unknown>): Source => {
28+ const { _id: _ignoredId, _creationTime: _ignoredCreationTime, ...source } = document;
29+ return decodeSource(source);
30+};
31+
32+const sourceKindValidator = v.union(
33+ v.literal("mcp"),
34+ v.literal("openapi"),
35+ v.literal("graphql"),
36+ v.literal("internal"),
37+);
38+
39+const 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+
47+export 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+
65+export 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+
119+export 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+
166+export 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+
184+export 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+
210+export 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 @@
1+import {
2+ type ListStorageDirectoryResult,
3+ type ListStorageKvResult,
4+ type OpenStorageInstancePayload,
5+ type QueryStorageSqlResult,
6+ type ReadStorageFileResult,
7+} from "@executor-v2/management-api";
8+import { StorageInstanceSchema, type StorageInstance } from "@executor-v2/schema";
9+import { v } from "convex/values";
10+import * as Schema from "effect/Schema";
11+
12+import {
13+ internalMutation,
14+ mutation,
15+ query,
16+ type MutationCtx,
17+ type QueryCtx,
18+} from "../_generated/server";
19+
20+const decodeStorageInstance = Schema.decodeUnknownSync(StorageInstanceSchema);
21+
22+const 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+
31+type StorageFileEntry = typeof StorageFileEntrySchema.Type;
32+const decodeStorageFileEntry = Schema.decodeUnknownSync(StorageFileEntrySchema);
33+
34+const 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+
42+type StorageKvEntry = typeof StorageKvEntrySchema.Type;
43+const decodeStorageKvEntry = Schema.decodeUnknownSync(StorageKvEntrySchema);
44+
45+const 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+
53+type StorageSqlKvEntry = typeof StorageSqlKvEntrySchema.Type;
54+const decodeStorageSqlKvEntry = Schema.decodeUnknownSync(StorageSqlKvEntrySchema);
55+
56+const DEFAULT_KV_LIMIT = 100;
57+const MAX_KV_LIMIT = 1000;
58+const DEFAULT_SQL_MAX_ROWS = 200;
59+const MAX_SQL_MAX_ROWS = 5000;
60+
61+const stripConvexSystemFields = (
62+ value: Record<string, unknown>,
63+): Record<string, unknown> => {
64+ const { _id: _ignoredId, _creationTime: _ignoredCreationTime, ...rest } = value;
65+ return rest;
66+};
67+
68+const toStorageInstance = (document: Record<string, unknown>): StorageInstance =>
69+ decodeStorageInstance(stripConvexSystemFields(document));
70+
71+const toStorageFileEntry = (document: Record<string, unknown>): StorageFileEntry =>
72+ decodeStorageFileEntry(stripConvexSystemFields(document));
73+
74+const toStorageKvEntry = (document: Record<string, unknown>): StorageKvEntry =>
75+ decodeStorageKvEntry(stripConvexSystemFields(document));
76+
77+const toStorageSqlKvEntry = (document: Record<string, unknown>): StorageSqlKvEntry =>
78+ decodeStorageSqlKvEntry(stripConvexSystemFields(document));
79+
80+const storageScopeTypeValidator = v.union(
81+ v.literal("scratch"),
82+ v.literal("account"),
83+ v.literal("workspace"),
84+ v.literal("organization"),
85+);
86+
87+const storageDurabilityValidator = v.union(
88+ v.literal("ephemeral"),
89+ v.literal("durable"),
90+);
91+
92+const storageProviderValidator = v.union(
93+ v.literal("agentfs-local"),
94+ v.literal("agentfs-cloudflare"),
95+);
96+
97+const readStorageEncodingValidator = v.union(
98+ v.literal("utf8"),
99+ v.literal("base64"),
100+);
101+
102+const 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+
113+const 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+
129+const 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+
142+const 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+
174+const 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+
187+const 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+
197+const parseJsonOrString = (value: string): unknown => {
198+ try {
199+ return JSON.parse(value) as unknown;
200+ } catch {
201+ return value;
202+ }
203+};
204+
205+const 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+
238+export 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+
291+export 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+
340+const decodeSqlStringLiteral = (value: string): string => value.replaceAll("''", "'");
341+
342+const 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+
369+const 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+
399+type SqlWrite =
400+ | {
401+ type: "upsert";
402+ key: string;
403+ value: string;
404+ insertOnly: boolean;
405+ }
406+ | {
407+ type: "delete";
408+ key: string;
409+ };
410+
411+const 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+
550+export 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+
587+export 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+
651+export 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+
690+export 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+
752+export 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+
872+export 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+
917+export 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+
964+export 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 @@
1+import { v } from "convex/values";
2+import { internal } from "../_generated/api";
3+
4+import { action, internalMutation, internalQuery } from "../_generated/server";
5+
6+const defaultSearchLimit = 50;
7+const maxSearchLimit = 5_000;
8+const writeBatchSize = 500;
9+const runtimeInternal = internal as any;
10+
11+const stripConvexSystemFields = (
12+ value: Record<string, unknown>,
13+): Record<string, unknown> => {
14+ const { _id: _ignoredId, _creationTime: _ignoredCreationTime, ...rest } = value;
15+ return rest;
16+};
17+
18+const normalizePathForLookup = (path: string): string =>
19+ path
20+ .trim()
21+ .toLowerCase()
22+ .replace(/[^a-z0-9]+/g, ".")
23+ .replace(/\.+/g, ".")
24+ .replace(/^\.|\.$/g, "");
25+
26+const 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+
34+const artifactSchemaRefId = (artifactId: string, refKey: string): string =>
35+ `${artifactId}:ref:${encodeURIComponent(refKey)}`;
36+
37+const 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+
47+const 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+
55+const 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+
70+const 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+
89+const 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+
95+const 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+
117+const 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+
151+const 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+
189+const 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+
200+const 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+
320+export 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+
447+export 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+
499+export 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+
517+export 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+
547+export 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+
561+export 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+
645+export 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+
677+export 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+
715+export 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+
736+export 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+
759+export 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+
831+export 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+
852+export 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+
962+export 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+
997+export 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+
1014+export 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+
1028+export 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+
1044+export 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+
1075+export 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+
1092+export 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+
1134+export 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+
1154+export 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+
1169+export 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+
1187+export 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 @@
1+import { type SourceToolDetail, type SourceToolSummary } from "@executor-v2/management-api";
2+import {
3+ SourceSchema,
4+ type OpenApiHttpMethod,
5+ type Source,
6+} from "@executor-v2/schema";
7+import { v } from "convex/values";
8+import * as Schema from "effect/Schema";
9+
10+import { query } from "../_generated/server";
11+
12+const decodeSource = Schema.decodeUnknownSync(SourceSchema);
13+
14+const stripConvexSystemFields = (
15+ value: Record<string, unknown>,
16+): Record<string, unknown> => {
17+ const { _id: _ignoredId, _creationTime: _ignoredCreationTime, ...rest } = value;
18+ return rest;
19+};
20+
21+const toSource = (document: Record<string, unknown>): Source =>
22+ decodeSource(stripConvexSystemFields(document));
23+
24+const 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+
39+const 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+
51+const asNullableString = (value: unknown): string | null =>
52+ typeof value === "string" && value.trim().length > 0 ? value : null;
53+
54+const 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+
64+const sourceNamespace = (source: Source): string => {
65+ const sourceIdSuffix = source.id.slice(-6).toLowerCase();
66+ return `${normalizeNamespacePart(source.name)}_${sourceIdSuffix}`;
67+};
68+
69+const 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+
81+const 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+
90+const 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+
114+const 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+
137+const 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+
193+const 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+
218+const 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+
237+export 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+
281+export 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+
327+export 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 @@
1+import { type UpsertWorkspacePayload } from "@executor-v2/management-api";
2+import { WorkspaceSchema, type Workspace } from "@executor-v2/schema";
3+import { v } from "convex/values";
4+import * as Schema from "effect/Schema";
5+
6+import { mutation, query } from "../_generated/server";
7+
8+const decodeWorkspace = Schema.decodeUnknownSync(WorkspaceSchema);
9+
10+const stripConvexSystemFields = (
11+ value: Record<string, unknown>,
12+): Record<string, unknown> => {
13+ const { _id: _ignoredId, _creationTime: _ignoredCreationTime, ...rest } = value;
14+ return rest;
15+};
16+
17+const toWorkspace = (document: Record<string, unknown>): Workspace =>
18+ decodeWorkspace(stripConvexSystemFields(document));
19+
20+const 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+
32+export 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+
43+export 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 @@
1+import workflow from "@convex-dev/workflow/convex.config.js";
2+import { defineApp } from "convex/server";
3+
4+const app = defineApp();
5+app.use(workflow);
6+
7+export default app;
apps/convex/convex/credential_crypto.ts+102−0
@@ -0,0 +1,102 @@
1+const encryptedPrefix = "enc:v1:";
2+
3+const encoder = new TextEncoder();
4+const decoder = new TextDecoder();
5+
6+const 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+
14+const 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+
23+const 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+
32+const 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+
46+const 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+
67+export const isEncryptedSecret = (value: string): boolean =>
68+ value.startsWith(encryptedPrefix);
69+
70+export 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+
85+export 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 @@
1+import {
2+ buildCredentialHeaders,
3+ CredentialResolverError,
4+ extractCredentialResolutionContext,
5+ makeCredentialResolver,
6+ selectCredentialBinding,
7+ selectOAuthAccessToken,
8+ sourceIdFromSourceKey,
9+ type ResolveToolCredentials,
10+} from "@executor-v2/engine";
11+import {
12+ OAuthTokenSchema,
13+ SourceCredentialBindingSchema,
14+ type OAuthToken,
15+ type SourceCredentialBinding,
16+} from "@executor-v2/schema";
17+import { v } from "convex/values";
18+import * as Effect from "effect/Effect";
19+import * as Schema from "effect/Schema";
20+
21+import { api } from "./_generated/api";
22+import { query, type ActionCtx } from "./_generated/server";
23+import { decryptSecretValue } from "./credential_crypto";
24+
25+const decodeSourceCredentialBinding = Schema.decodeUnknownSync(
26+ SourceCredentialBindingSchema,
27+);
28+const decodeOAuthToken = Schema.decodeUnknownSync(OAuthTokenSchema);
29+
30+const stripConvexSystemFields = (
31+ value: Record<string, unknown>,
32+): Record<string, unknown> => {
33+ const { _id: _ignoredId, _creationTime: _ignoredCreationTime, ...rest } = value;
34+ return rest;
35+};
36+
37+export 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+
72+export 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+
93+const toCredentialResolverError = (
94+ operation: string,
95+ message: string,
96+ details: string | null,
97+): CredentialResolverError =>
98+ new CredentialResolverError({
99+ operation,
100+ message,
101+ details,
102+ });
103+
104+const 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+
118+const 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+
128+export 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 @@
1+import { describe, expect, it } from "@effect/vitest";
2+import { extractOpenApiManifest } from "@executor-v2/management-api";
3+import { convexTest } from "convex-test";
4+import * as Effect from "effect/Effect";
5+
6+import { api, internal } from "./_generated/api";
7+import { executeRunImpl } from "./executor";
8+import schema from "./schema";
9+
10+const runtimeInternal = internal as any;
11+
12+const 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+
30+const 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+
44+describe("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 @@
1+import {
2+ createRunExecutor,
3+ type ToolRegistry,
4+} from "@executor-v2/engine";
5+import type { ExecuteRunInput, ExecuteRunResult } from "@executor-v2/sdk";
6+import * as Effect from "effect/Effect";
7+
8+import { createExecuteRuntimeRunInConvex } from "./runtime_execution_port";
9+
10+export type ExecuteRunImplOptions = {
11+ toolRegistry?: ToolRegistry;
12+ makeRunId?: () => string;
13+};
14+
15+export 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 @@
1+import { httpRouter } from "convex/server";
2+
3+import { controlPlaneHttpHandler } from "./controlPlane";
4+import { mcpHandler } from "./mcp";
5+import {
6+ oauthAuthorizationServerHandler,
7+ oauthProtectedResourceHandler,
8+} from "./mcp_auth";
9+import { handleToolCallHttp } from "./runtimeCallbacks";
10+
11+const http = httpRouter();
12+
13+http.route({ path: "/v1/mcp", method: "POST", handler: mcpHandler });
14+http.route({ path: "/v1/mcp", method: "GET", handler: mcpHandler });
15+http.route({ path: "/v1/mcp", method: "DELETE", handler: mcpHandler });
16+http.route({
17+ path: "/.well-known/oauth-protected-resource",
18+ method: "GET",
19+ handler: oauthProtectedResourceHandler,
20+});
21+http.route({
22+ path: "/.well-known/oauth-authorization-server",
23+ method: "GET",
24+ handler: oauthAuthorizationServerHandler,
25+});
26+http.route({
27+ path: "/v1/runtime/tool-call",
28+ method: "POST",
29+ handler: handleToolCallHttp,
30+});
31+http.route({
32+ pathPrefix: "/v1/",
33+ method: "GET",
34+ handler: controlPlaneHttpHandler,
35+});
36+http.route({
37+ pathPrefix: "/v1/",
38+ method: "POST",
39+ handler: controlPlaneHttpHandler,
40+});
41+http.route({
42+ pathPrefix: "/v1/",
43+ method: "PUT",
44+ handler: controlPlaneHttpHandler,
45+});
46+http.route({
47+ pathPrefix: "/v1/",
48+ method: "PATCH",
49+ handler: controlPlaneHttpHandler,
50+});
51+http.route({
52+ pathPrefix: "/v1/",
53+ method: "DELETE",
54+ handler: controlPlaneHttpHandler,
55+});
56+http.route({
57+ pathPrefix: "/v1/",
58+ method: "OPTIONS",
59+ handler: controlPlaneHttpHandler,
60+});
61+
62+export default http;
apps/convex/convex/mcp.ts+199−0
@@ -0,0 +1,199 @@
1+import {
2+ buildExecuteToolDescription,
3+ defaultExecuteToolDescription,
4+ defaultExecuteToolExposureMode,
5+ parseExecuteToolExposureMode,
6+ type ExecuteToolExposureMode,
7+} from "@executor-v2/engine";
8+import { handleMcpHttpRequest } from "@executor-v2/mcp-gateway";
9+import { createExecutorRunClient } from "@executor-v2/sdk";
10+import * as Effect from "effect/Effect";
11+
12+import { internal } from "./_generated/api";
13+import { httpAction, type ActionCtx } from "./_generated/server";
14+import { executeRunImpl } from "./executor";
15+import {
16+ getMcpAuthConfig,
17+ unauthorizedMcpResponse,
18+ verifyMcpToken,
19+} from "./mcp_auth";
20+import { createConvexSourceToolRegistry } from "./source_tool_registry";
21+
22+const readConfiguredWorkspaceId = (value: string | undefined): string => {
23+ const normalized = value?.trim();
24+ return normalized && normalized.length > 0 ? normalized : "ws_local";
25+};
26+
27+const 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+
32+const readRequestedWorkspaceId = (request: Request, fallbackWorkspaceId: string): string =>
33+ readWorkspaceIdFromRequest(request) ?? fallbackWorkspaceId;
34+
35+const 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+
48+const 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+
64+const 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+
99+const fallbackWorkspaceId = readConfiguredWorkspaceId(process.env.CONVEX_WORKSPACE_ID);
100+const defaultToolExposureMode =
101+ parseExecuteToolExposureMode(process.env.CONVEX_TOOL_EXPOSURE_MODE) ??
102+ defaultExecuteToolExposureMode;
103+const runtimeInternal = internal as any;
104+
105+export 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 @@
1+import { createRemoteJWKSet, jwtVerify } from "jose";
2+
3+import { httpAction } from "./_generated/server";
4+
5+export const MCP_PATH = "/v1/mcp";
6+
7+type McpAuthConfig = {
8+ required: boolean;
9+ enabled: boolean;
10+ authorizationServer: string | null;
11+ jwks: ReturnType<typeof createRemoteJWKSet> | null;
12+};
13+
14+type VerifiedMcpToken = {
15+ provider: "workos";
16+ subject: string;
17+};
18+
19+const isTruthyEnvValue = (value: string | undefined): boolean => {
20+ const normalized = value?.trim().toLowerCase();
21+ return normalized === "1" || normalized === "true" || normalized === "yes" || normalized === "on";
22+};
23+
24+const 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+
46+const 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+
53+export 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+
74+const 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+
84+const 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+
96+export 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+
114+export 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+
151+const 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+
161+export 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+
195+export 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 @@
1+import { type ExecuteRunInput } from "@executor-v2/sdk";
2+
3+import { executeRunImpl } from "./executor";
4+
5+export const executeRun = (input: ExecuteRunInput) => executeRunImpl(input);
apps/convex/convex/runtimeCallbacks.ts+124−0
@@ -0,0 +1,124 @@
1+import {
2+ RuntimeAdapterError,
3+ invokeRuntimeToolCallResult,
4+} from "@executor-v2/engine";
5+import type {
6+ RuntimeToolCallRequest,
7+ RuntimeToolCallResult,
8+} from "@executor-v2/sdk";
9+import * as Data from "effect/Data";
10+import * as Effect from "effect/Effect";
11+import * as ParseResult from "effect/ParseResult";
12+import * as Schema from "effect/Schema";
13+
14+import { httpAction, type ActionCtx } from "./_generated/server";
15+import { createConvexSourceToolRegistry } from "./source_tool_registry";
16+
17+class RuntimeToolCallBadRequestError extends Data.TaggedError(
18+ "RuntimeToolCallBadRequestError",
19+)<{
20+ message: string;
21+ details: string;
22+}> {}
23+
24+const 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+
31+const 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+
44+const decodeRuntimeToolCallRequest = Schema.decodeUnknown(RuntimeToolCallRequestSchema);
45+
46+const readConfiguredWorkspaceId = (value: string | undefined): string => {
47+ const normalized = value?.trim();
48+ return normalized && normalized.length > 0 ? normalized : "ws_local";
49+};
50+
51+const fallbackWorkspaceId = readConfiguredWorkspaceId(process.env.CONVEX_WORKSPACE_ID);
52+
53+const 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+
63+const formatBadRequestMessage = (error: RuntimeToolCallBadRequestError): string =>
64+ error.details.length > 0 ? `${error.message}: ${error.details}` : error.message;
65+
66+const formatRuntimeAdapterError = (error: RuntimeAdapterError): string =>
67+ error.details ? `${error.message}: ${error.details}` : error.message;
68+
69+const formatUnknownDetails = (cause: unknown): string => String(cause);
70+
71+const 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+
93+const 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+
122+export const handleToolCallHttp = httpAction((ctx, request) =>
123+ Effect.runPromise(handleToolCallHttpEffect(ctx, request)),
124+);
apps/convex/convex/runtime_adapter.ts+10−0
@@ -0,0 +1,10 @@
1+import {
2+ type RuntimeAdapter,
3+ type RuntimeExecuteError,
4+ type RuntimeExecuteInput,
5+} from "@executor-v2/engine";
6+import { makeCloudflareWorkerLoaderRuntimeAdapter } from "@executor-v2/runtime-cloudflare-worker-loader";
7+
8+export type { RuntimeAdapter, RuntimeExecuteError, RuntimeExecuteInput };
9+
10+export { makeCloudflareWorkerLoaderRuntimeAdapter };
apps/convex/convex/runtime_execution_port.ts+74−0
@@ -0,0 +1,74 @@
1+import {
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";
11+import { makeCloudflareWorkerLoaderRuntimeAdapter } from "@executor-v2/runtime-cloudflare-worker-loader";
12+import * as Effect from "effect/Effect";
13+
14+export type ConvexRuntimeExecutionPortOptions = {
15+ toolRegistry?: ToolRegistry;
16+};
17+
18+export 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+
74+export const executeRuntimeRunInConvex = createExecuteRuntimeRunInConvex();
apps/convex/convex/schema.ts+236−0
@@ -0,0 +1,236 @@
1+import { defineSchema, defineTable, type TablesFromSchemaDefinition } from "@executor-v2/confect";
2+import {
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";
17+import * as Schema from "effect/Schema";
18+
19+const 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+
28+const 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+
36+const 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+
44+const 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+
55+const 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+
72+const 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+
81+const 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+
89+const 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+
100+const 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+
125+export 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+
234+export type ExecutorConfectTables = TablesFromSchemaDefinition<typeof executorConfectSchema>;
235+
236+export default executorConfectSchema.convexSchemaDefinition;
apps/convex/convex/source_tool_registry.ts+1686−0
@@ -0,0 +1,1686 @@
1+import {
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";
20+import {
21+ ApprovalSchema,
22+ OpenApiInvocationPayloadSchema,
23+ type Approval,
24+ type CanonicalToolDescriptor,
25+ type Source,
26+} from "@executor-v2/schema";
27+import type { RuntimeToolCallResult } from "@executor-v2/sdk";
28+import { v } from "convex/values";
29+import * as Effect from "effect/Effect";
30+import * as ParseResult from "effect/ParseResult";
31+import * as Schema from "effect/Schema";
32+
33+import { internal } from "./_generated/api";
34+import { internalMutation, type ActionCtx } from "./_generated/server";
35+
36+const runtimeInternal = internal as any;
37+
38+const decodeApproval = Schema.decodeUnknownSync(ApprovalSchema);
39+const decodeOpenApiInvocationPayload = Schema.decodeUnknownSync(OpenApiInvocationPayloadSchema);
40+
41+const sourceToolRegistryRuntimeKind = "source-tool-registry";
42+const defaultPendingRetryAfterMs = 1_000;
43+const maxCatalogNamespacesLimit = 5_000;
44+const maxCatalogToolsLimit = 50_000;
45+const maxUnknownToolSuggestions = 3;
46+
47+const readBooleanFlag = (value: string | undefined): boolean => {
48+ const normalized = value?.trim().toLowerCase();
49+ return normalized === "1" || normalized === "true" || normalized === "yes";
50+};
51+
52+const requireToolApprovalsByDefault = readBooleanFlag(
53+ process.env.CONVEX_REQUIRE_TOOL_APPROVALS,
54+);
55+
56+const stripConvexSystemFields = (
57+ value: Record<string, unknown>,
58+): Record<string, unknown> => {
59+ const { _id: _ignoredId, _creationTime: _ignoredCreationTime, ...rest } = value;
60+ return rest;
61+};
62+
63+const 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+
75+const 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+
83+const 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+
92+const 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+
123+const serializeInputPreview = (input: Record<string, unknown> | undefined): string => {
124+ try {
125+ return JSON.stringify(input ?? {});
126+ } catch {
127+ return "{}";
128+ }
129+};
130+
131+const toPersistentApprovalStoreError = (
132+ operation: string,
133+ message: string,
134+ details: string | null,
135+): PersistentToolApprovalPolicyStoreError =>
136+ new PersistentToolApprovalPolicyStoreError({
137+ operation,
138+ message,
139+ details,
140+ });
141+
142+const 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+
154+const normalizeToolPathForLookup = (path: string): string =>
155+ path
156+ .trim()
157+ .toLowerCase()
158+ .replace(/[^a-z0-9]+/g, ".")
159+ .replace(/\.+/g, ".")
160+ .replace(/^\.|\.$/g, "");
161+
162+const safeJsonParse = (value: string): unknown => {
163+ try {
164+ return JSON.parse(value);
165+ } catch {
166+ return null;
167+ }
168+};
169+
170+const 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+
178+const 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+
187+const parseSourceConfig = (source: Source): Record<string, unknown> =>
188+ jsonObjectFromUnknown(safeJsonParse(source.configJson));
189+
190+const 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+
207+const 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+
240+const 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+
266+const 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+
298+const 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+
311+const 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+
319+const 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+
327+const GraphqlRawInvocationSchema = Schema.Struct({
328+ kind: Schema.Literal("graphql_raw"),
329+ endpoint: Schema.String,
330+});
331+
332+const 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+
340+const GraphqlInvocationPayloadSchema = Schema.Union(
341+ GraphqlRawInvocationSchema,
342+ GraphqlFieldInvocationSchema,
343+);
344+
345+type GraphqlInvocationPayload = typeof GraphqlInvocationPayloadSchema.Type;
346+
347+const decodeGraphqlInvocationPayload = Schema.decodeUnknownSync(GraphqlInvocationPayloadSchema);
348+
349+const 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+
362+type McpInvocationPayload = typeof McpInvocationPayloadSchema.Type;
363+
364+const decodeMcpInvocationPayload = Schema.decodeUnknownSync(McpInvocationPayloadSchema);
365+
366+const asOptionalString = (value: unknown): string | null =>
367+ typeof value === "string" && value.trim().length > 0 ? value : null;
368+
369+const 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+
377+const 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+
417+const 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+
426+const 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+
436+const 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+
462+const 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+
473+const 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+
485+const 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+
529+type 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+
549+type 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+
563+const toToolProviderDetails = (cause: unknown): string =>
564+ ParseResult.isParseError(cause)
565+ ? ParseResult.TreeFormatter.formatErrorSync(cause)
566+ : String(cause);
567+
568+const 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+
581+const 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+
614+const 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+
654+const 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+
672+const 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+
709+const 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+
716+const 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+
732+const 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+
752+const 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+
773+const 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+
799+const 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+
827+const 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+
846+const 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+
866+const 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+
885+const 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+
910+const 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+
1141+const 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+
1154+const 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+
1250+const approvalModeValidator = v.union(v.literal("auto"), v.literal("required"));
1251+
1252+export 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+
1375+const 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+
1396+const 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+
1434+const describeSource = (row: {
1435+ sourceName: string;
1436+ sourceKind: string;
1437+}): string => `${row.sourceKind.toUpperCase()} source: ${row.sourceName}`;
1438+
1439+export type ConvexSourceToolRegistryOptions = {
1440+ requireToolApprovals?: boolean;
1441+ approvalRetryAfterMs?: number;
1442+};
1443+
1444+export 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 @@
1+import { type TaskRun } from "@executor-v2/schema";
2+import { v } from "convex/values";
3+
4+import { internalMutation } from "./_generated/server";
5+
6+const taskRunTerminalStatusValidator = v.union(
7+ v.literal("completed"),
8+ v.literal("failed"),
9+ v.literal("timed_out"),
10+ v.literal("denied"),
11+);
12+
13+export 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+
51+export 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 @@
1+import { WorkflowManager } from "@convex-dev/workflow";
2+
3+import { components } from "./_generated/api";
4+
5+export 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 @@
1+export {};
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+
3+Local Process Manager app scaffold for Executor v2.
4+
5+Current 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+
15+App 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 @@
1+import {
2+ ControlPlaneActorResolverLive,
3+ deriveWorkspaceMembershipsForPrincipal,
4+ requirePrincipalFromHeaders,
5+} from "@executor-v2/management-api";
6+import {
7+ ActorUnauthenticatedError,
8+ makeActor,
9+ makeAllowAllActor,
10+} from "@executor-v2/domain";
11+import {
12+ type LocalStateSnapshot,
13+ type LocalStateStore,
14+} from "@executor-v2/persistence-local";
15+import {
16+ type OrganizationMembership,
17+ type WorkspaceMembership,
18+} from "@executor-v2/schema";
19+import * as PlatformHeaders from "@effect/platform/Headers";
20+import * as Effect from "effect/Effect";
21+import * as Option from "effect/Option";
22+
23+const isTruthy = (value: string | undefined): boolean => {
24+ const normalized = value?.trim().toLowerCase();
25+ return normalized === "1" || normalized === "true" || normalized === "yes";
26+};
27+
28+const 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+
38+const organizationMembershipsForAccount = (
39+ snapshot: LocalStateSnapshot,
40+ accountId: OrganizationMembership["accountId"],
41+): ReadonlyArray<OrganizationMembership> =>
42+ snapshot.organizationMemberships.filter(
43+ (membership) => membership.accountId === accountId,
44+ );
45+
46+const 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+
60+const 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+
98+export 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 @@
1+import {
2+ PersistentToolApprovalPolicyStoreError,
3+ createPersistentToolApprovalPolicy,
4+ type PersistentToolApprovalRecord,
5+ type PersistentToolApprovalStore,
6+ type ToolApprovalPolicy,
7+} from "@executor-v2/engine";
8+import { SourceStoreError } from "@executor-v2/persistence-ports";
9+import {
10+ type LocalStateSnapshot,
11+ type LocalStateStore,
12+ type LocalStateStoreError,
13+} from "@executor-v2/persistence-local";
14+import {
15+ makeControlPlaneApprovalsService,
16+ type ControlPlaneApprovalsServiceShape,
17+} from "@executor-v2/management-api";
18+import { type Approval } from "@executor-v2/schema";
19+import * as Effect from "effect/Effect";
20+import * as Option from "effect/Option";
21+
22+const 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+
36+const toSourceStoreErrorFromLocalState = (
37+ operation: string,
38+ error: LocalStateStoreError,
39+): SourceStoreError =>
40+ toSourceStoreError(operation, error.message, error.details ?? error.reason ?? null);
41+
42+const 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+
51+const sortApprovals = (approvals: ReadonlyArray<Approval>): Array<Approval> =>
52+ [...approvals].sort((left, right) => right.requestedAt - left.requestedAt);
53+
54+const toPersistentApprovalStoreError = (
55+ operation: string,
56+ message: string,
57+ details: string | null,
58+): PersistentToolApprovalPolicyStoreError =>
59+ new PersistentToolApprovalPolicyStoreError({
60+ operation,
61+ message,
62+ details,
63+ });
64+
65+const toPersistentApprovalStoreErrorFromLocalState = (
66+ operation: string,
67+ error: LocalStateStoreError,
68+): PersistentToolApprovalPolicyStoreError =>
69+ toPersistentApprovalStoreError(operation, error.message, error.details ?? error.reason ?? null);
70+
71+const 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+
81+const 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+
96+export type PmPersistentToolApprovalPolicyOptions = {
97+ requireApprovals?: boolean;
98+ retryAfterMs?: number;
99+};
100+
101+export 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+
183+export 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 @@
1+import * as Config from "effect/Config";
2+import * as Context from "effect/Context";
3+import * as Effect from "effect/Effect";
4+import * as Layer from "effect/Layer";
5+
6+export type PmConfigService = {
7+ port: number;
8+};
9+
10+export class PmConfig extends Context.Tag("@executor-v2/app-pm/PmConfig")<
11+ PmConfig,
12+ PmConfigService
13+>() {}
14+
15+export 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 @@
1+import {
2+ buildCredentialHeaders,
3+ CredentialResolverError,
4+ extractCredentialResolutionContext,
5+ makeCredentialResolver,
6+ selectCredentialBinding,
7+ selectOAuthAccessToken,
8+ sourceIdFromSourceKey,
9+ type ResolveToolCredentials,
10+} from "@executor-v2/engine";
11+import { type LocalStateStore } from "@executor-v2/persistence-local";
12+import * as Effect from "effect/Effect";
13+import * as Option from "effect/Option";
14+
15+const toCredentialResolverError = (
16+ operation: string,
17+ message: string,
18+ details: string | null,
19+): CredentialResolverError =>
20+ new CredentialResolverError({
21+ operation,
22+ message,
23+ details,
24+ });
25+
26+export 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 @@
1+import { SourceStoreError } from "@executor-v2/persistence-ports";
2+import {
3+ type LocalStateSnapshot,
4+ type LocalStateStore,
5+ type LocalStateStoreError,
6+} from "@executor-v2/persistence-local";
7+import {
8+ makeControlPlaneCredentialsService,
9+ type ControlPlaneCredentialsServiceShape,
10+} from "@executor-v2/management-api";
11+import {
12+ type OrganizationId,
13+ type SourceCredentialBinding,
14+ type WorkspaceId,
15+} from "@executor-v2/schema";
16+import * as Effect from "effect/Effect";
17+import * as Option from "effect/Option";
18+
19+const 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+
33+const toSourceStoreErrorFromLocalState = (
34+ operation: string,
35+ error: LocalStateStoreError,
36+): SourceStoreError =>
37+ toSourceStoreError(operation, error.message, error.details ?? error.reason ?? null);
38+
39+const 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+
52+const 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+
61+const 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+
76+const appendCredentialBinding = (
77+ snapshot: LocalStateSnapshot,
78+ binding: SourceCredentialBinding,
79+): LocalStateSnapshot => ({
80+ ...snapshot,
81+ generatedAt: Date.now(),
82+ credentialBindings: [...snapshot.credentialBindings, binding],
83+});
84+
85+const 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+
120+export 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 @@
1+import { spawn } from "node:child_process";
2+import { createServer } from "node:net";
3+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
4+import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
5+import { describe, expect, it } from "@effect/vitest";
6+import * as Data from "effect/Data";
7+import * as Effect from "effect/Effect";
8+
9+const pmAppDir = new URL("..", import.meta.url).pathname;
10+
11+type McpCallToolResult = {
12+ isError?: boolean;
13+ content?: Array<{ type?: string; text?: string }>;
14+};
15+
16+class ExecuteE2eError extends Data.TaggedError("ExecuteE2eError")<{
17+ message: string;
18+ details: string | null;
19+}> {}
20+
21+const toExecuteE2eError = (message: string, cause: unknown): ExecuteE2eError =>
22+ new ExecuteE2eError({
23+ message,
24+ details: cause instanceof Error ? cause.message : String(cause),
25+ });
26+
27+const 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+
61+const 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+
87+const 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+
107+const 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+
136+describe("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 @@
1+import { controlPlaneOpenApiSpec } from "@executor-v2/management-api";
2+
3+export 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+
10+export type PmHttpServer = {
11+ stop: () => void;
12+};
13+
14+const methodNotAllowed = (allowed: string): Response =>
15+ Response.json(
16+ {
17+ ok: false,
18+ error: `Method not allowed. Expected ${allowed}`,
19+ },
20+ { status: 405 },
21+ );
22+
23+const notFound = (): Response =>
24+ Response.json(
25+ {
26+ ok: false,
27+ error: "Not found",
28+ },
29+ { status: 404 },
30+ );
31+
32+const isControlPlaneMethod = (method: string): boolean =>
33+ method === "GET" ||
34+ method === "POST" ||
35+ method === "PUT" ||
36+ method === "PATCH" ||
37+ method === "DELETE" ||
38+ method === "OPTIONS";
39+
40+export 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 @@
1+import * as BunContext from "@effect/platform-bun/BunContext";
2+import {
3+ ControlPlaneService,
4+ makeControlPlaneService,
5+ makeControlPlaneSourcesService,
6+ fetchOpenApiDocument,
7+ makeControlPlaneWebHandler,
8+ makeSourceCatalogService,
9+ makeSourceManagerService,
10+} from "@executor-v2/management-api";
11+import {
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";
24+import {
25+ makeLocalSourceStore,
26+ makeLocalStateStore,
27+ makeLocalToolArtifactStore,
28+} from "@executor-v2/persistence-local";
29+import { type RuntimeToolCallResult } from "@executor-v2/sdk";
30+import { makeCloudflareWorkerLoaderRuntimeAdapter } from "@executor-v2/runtime-cloudflare-worker-loader";
31+import { makeDenoSubprocessRuntimeAdapter } from "@executor-v2/runtime-deno-subprocess";
32+import { makeLocalInProcessRuntimeAdapter } from "@executor-v2/runtime-local-inproc";
33+import * as Effect from "effect/Effect";
34+import * as Layer from "effect/Layer";
35+
36+import { PmActorLive } from "./actor";
37+import {
38+ createPmApprovalsService,
39+ createPmPersistentToolApprovalPolicy,
40+} from "./approvals-service";
41+import { startPmHttpServer } from "./http-server";
42+import { createPmPoliciesService } from "./policies-service";
43+import { createPmCredentialsService } from "./credentials-service";
44+import { createPmOrganizationsService } from "./organizations-service";
45+import { createPmStorageService } from "./storage-service";
46+import { createPmToolsService } from "./tools-service";
47+import { createPmWorkspacesService } from "./workspaces-service";
48+import { createPmMcpHandler } from "./mcp-handler";
49+import { createPmExecuteRuntimeRun } from "./runtime-execution-port";
50+import { createPmToolCallHttpHandler } from "./tool-call-handler";
51+
52+const pmStateRootDir = process.env.PM_STATE_ROOT_DIR ?? ".executor-v2/pm-state";
53+
54+const parsePort = (value: string | undefined): number => {
55+ const parsed = Number.parseInt(value ?? "", 10);
56+ return Number.isFinite(parsed) && parsed > 0 ? parsed : 8787;
57+};
58+
59+const 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+
68+const readConfiguredWorkspaceId = (value: string | undefined): string => {
69+ const normalized = value?.trim();
70+ return normalized && normalized.length > 0 ? normalized : "ws_local";
71+};
72+
73+const readBooleanFlag = (value: string | undefined): boolean => {
74+ const normalized = value?.trim().toLowerCase();
75+ return normalized === "1" || normalized === "true" || normalized === "yes";
76+};
77+
78+const readConfiguredToolExposureMode = (
79+ value: string | undefined,
80+): "all_tools" | "sources_only" =>
81+ parseExecuteToolExposureMode(value ?? undefined) ??
82+ defaultExecuteToolExposureMode;
83+
84+const formatRuntimeAdapterError = (error: RuntimeAdapterError): string =>
85+ error.details ? `${error.message}: ${error.details}` : error.message;
86+
87+const port = parsePort(process.env.PORT);
88+const workspaceId = readConfiguredWorkspaceId(process.env.PM_WORKSPACE_ID);
89+const requireToolApprovals = readBooleanFlag(process.env.PM_REQUIRE_TOOL_APPROVALS);
90+const defaultToolExposureMode = readConfiguredToolExposureMode(
91+ process.env.PM_TOOL_EXPOSURE_MODE,
92+);
93+
94+const pmRuntimeAdapters = [
95+ makeLocalInProcessRuntimeAdapter(),
96+ makeDenoSubprocessRuntimeAdapter(),
97+ makeCloudflareWorkerLoaderRuntimeAdapter(),
98+];
99+
100+const runtimeAdapters = makeRuntimeAdapterRegistry(pmRuntimeAdapters);
101+const defaultRuntimeKind =
102+ readConfiguredRuntimeKind(process.env.PM_RUNTIME_KIND) ?? pmRuntimeAdapters[0].kind;
103+
104+const sourceStore = await Effect.runPromise(
105+ makeLocalSourceStore({
106+ rootDir: pmStateRootDir,
107+ }).pipe(Effect.provide(BunContext.layer)),
108+);
109+
110+const localStateStore = await Effect.runPromise(
111+ makeLocalStateStore({
112+ rootDir: pmStateRootDir,
113+ }).pipe(Effect.provide(BunContext.layer)),
114+);
115+
116+const toolArtifactStore = await Effect.runPromise(
117+ makeLocalToolArtifactStore({
118+ rootDir: pmStateRootDir,
119+ }).pipe(Effect.provide(BunContext.layer)),
120+);
121+
122+const sourceCatalog = makeSourceCatalogService(sourceStore);
123+const sourceManager = makeSourceManagerService(toolArtifactStore);
124+const baseSourcesService = makeControlPlaneSourcesService(sourceCatalog);
125+const 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+
155+const credentialsService = createPmCredentialsService(localStateStore);
156+const policiesService = createPmPoliciesService(localStateStore);
157+const organizationsService = createPmOrganizationsService(localStateStore);
158+const workspacesService = createPmWorkspacesService(localStateStore);
159+const toolsService = createPmToolsService(sourceStore, toolArtifactStore);
160+const storageService = createPmStorageService(localStateStore, {
161+ stateRootDir: pmStateRootDir,
162+});
163+const approvalsService = createPmApprovalsService(localStateStore);
164+const 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+
175+const controlPlaneWebHandler = makeControlPlaneWebHandler(
176+ Layer.succeed(ControlPlaneService, controlPlaneService),
177+ PmActorLive(localStateStore),
178+);
179+
180+const toolProviderRegistry = makeToolProviderRegistry([
181+ makeOpenApiToolProvider(),
182+ makeMcpToolProvider(),
183+ makeGraphqlToolProvider(),
184+]);
185+const persistentApprovalPolicy = createPmPersistentToolApprovalPolicy(localStateStore, {
186+ requireApprovals: requireToolApprovals,
187+});
188+const toolRegistry = createSourceToolRegistry({
189+ workspaceId,
190+ sourceStore,
191+ toolArtifactStore,
192+ toolProviderRegistry,
193+ approvalPolicy: persistentApprovalPolicy,
194+});
195+const executeRuntimeRun = createPmExecuteRuntimeRun({
196+ defaultRuntimeKind,
197+ runtimeAdapters,
198+ toolRegistry,
199+});
200+
201+const runExecutor = createRunExecutor(executeRuntimeRun);
202+const handleMcp = createPmMcpHandler(runExecutor.executeRun, {
203+ toolRegistry,
204+ defaultToolExposureMode,
205+});
206+
207+const 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+
221+const server = startPmHttpServer({
222+ port,
223+ handleMcp,
224+ handleToolCall: handleToolCallHttp,
225+ handleControlPlane: controlPlaneWebHandler.handler,
226+});
227+
228+const shutdown = async () => {
229+ server.stop();
230+ await controlPlaneWebHandler.dispose();
231+};
232+
233+process.on("SIGINT", () => {
234+ void shutdown().finally(() => process.exit(0));
235+});
236+
237+process.on("SIGTERM", () => {
238+ void shutdown().finally(() => process.exit(0));
239+});
apps/pm/src/mcp-handler.ts+76−0
@@ -0,0 +1,76 @@
1+import {
2+ buildExecuteToolDescription,
3+ defaultExecuteToolDescription,
4+ defaultExecuteToolExposureMode,
5+ parseExecuteToolExposureMode,
6+ type ExecuteToolExposureMode,
7+ type ToolRegistry,
8+} from "@executor-v2/engine";
9+import {
10+ type ExecuteRunInput,
11+ type ExecuteRunResult,
12+ createExecutorRunClient,
13+} from "@executor-v2/sdk";
14+import { handleMcpHttpRequest } from "@executor-v2/mcp-gateway";
15+import * as Effect from "effect/Effect";
16+
17+export type PmMcpHandlerOptions = {
18+ toolRegistry: ToolRegistry;
19+ defaultToolExposureMode?: ExecuteToolExposureMode;
20+};
21+
22+const 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+
35+const 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+
51+export 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 @@
1+import { SourceStoreError } from "@executor-v2/persistence-ports";
2+import {
3+ makeControlPlaneOrganizationsService,
4+ type ControlPlaneOrganizationsServiceShape,
5+} from "@executor-v2/management-api";
6+import {
7+ type LocalStateSnapshot,
8+ type LocalStateStore,
9+ type LocalStateStoreError,
10+} from "@executor-v2/persistence-local";
11+import {
12+ type Organization,
13+ type OrganizationMembership,
14+} from "@executor-v2/schema";
15+import * as Effect from "effect/Effect";
16+import * as Option from "effect/Option";
17+
18+const 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+
32+const toSourceStoreErrorFromLocalState = (
33+ operation: string,
34+ error: LocalStateStoreError,
35+): SourceStoreError =>
36+ toSourceStoreError(operation, error.message, error.details ?? error.reason ?? null);
37+
38+const 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+
52+const 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+
67+const appendOrganization = (
68+ snapshot: LocalStateSnapshot,
69+ organization: Organization,
70+): LocalStateSnapshot => ({
71+ ...snapshot,
72+ generatedAt: Date.now(),
73+ organizations: [...snapshot.organizations, organization],
74+});
75+
76+const appendOrganizationMembership = (
77+ snapshot: LocalStateSnapshot,
78+ membership: OrganizationMembership,
79+): LocalStateSnapshot => ({
80+ ...snapshot,
81+ generatedAt: Date.now(),
82+ organizationMemberships: [...snapshot.organizationMemberships, membership],
83+});
84+
85+export 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 @@
1+import { describe, expect, it } from "@effect/vitest";
2+import type {
3+ LocalStateSnapshot,
4+ LocalStateStore,
5+} from "@executor-v2/persistence-local";
6+import * as Effect from "effect/Effect";
7+import * as Option from "effect/Option";
8+
9+import {
10+ createPmApprovalsService,
11+ createPmPersistentToolApprovalPolicy,
12+} from "./approvals-service";
13+
14+const 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+
40+describe("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 @@
1+import { SourceStoreError } from "@executor-v2/persistence-ports";
2+import {
3+ type LocalStateSnapshot,
4+ type LocalStateStore,
5+ type LocalStateStoreError,
6+} from "@executor-v2/persistence-local";
7+import {
8+ makeControlPlanePoliciesService,
9+ type ControlPlanePoliciesServiceShape,
10+} from "@executor-v2/management-api";
11+import { type Policy } from "@executor-v2/schema";
12+import * as Effect from "effect/Effect";
13+import * as Option from "effect/Option";
14+
15+const 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+
29+const toSourceStoreErrorFromLocalState = (
30+ operation: string,
31+ error: LocalStateStoreError,
32+): SourceStoreError =>
33+ toSourceStoreError(operation, error.message, error.details ?? error.reason ?? null);
34+
35+const 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+
46+const 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+
61+const appendPolicy = (
62+ snapshot: LocalStateSnapshot,
63+ policy: Policy,
64+): LocalStateSnapshot => ({
65+ ...snapshot,
66+ generatedAt: Date.now(),
67+ policies: [...snapshot.policies, policy],
68+});
69+
70+const 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+
99+export 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 @@
1+import {
2+ createRuntimeToolCallService,
3+ RuntimeExecutionPortError,
4+ type ExecuteRuntimeRun,
5+ type ExecuteRuntimeRunInput,
6+ type RuntimeAdapterRegistry,
7+ type RuntimeExecuteError,
8+ type ToolRegistry,
9+} from "@executor-v2/engine";
10+import * as Effect from "effect/Effect";
11+
12+export type PmRuntimeExecutionPortOptions = {
13+ defaultRuntimeKind: string;
14+ runtimeAdapters: RuntimeAdapterRegistry;
15+ toolRegistry: ToolRegistry;
16+};
17+
18+export 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 @@
1+import { describe, expect, it } from "@effect/vitest";
2+import type {
3+ LocalStateSnapshot,
4+ LocalStateStore,
5+} from "@executor-v2/persistence-local";
6+import type { StorageInstance, WorkspaceId } from "@executor-v2/schema";
7+import * as Effect from "effect/Effect";
8+import * as Option from "effect/Option";
9+import { mkdtemp, rm, writeFile } from "node:fs/promises";
10+import { tmpdir } from "node:os";
11+import * as path from "node:path";
12+
13+import { createPmStorageService } from "./storage-service";
14+
15+const 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+
50+describe("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 @@
1+import {
2+ makeControlPlaneStorageService,
3+ type ControlPlaneStorageServiceShape,
4+} from "@executor-v2/management-api";
5+import { SourceStoreError } from "@executor-v2/persistence-ports";
6+import {
7+ type LocalStateSnapshot,
8+ type LocalStateStore,
9+ type LocalStateStoreError,
10+} from "@executor-v2/persistence-local";
11+import {
12+ type OrganizationId,
13+ type StorageInstance,
14+ type WorkspaceId,
15+} from "@executor-v2/schema";
16+import * as Effect from "effect/Effect";
17+import * as Option from "effect/Option";
18+import {
19+ mkdir,
20+ readdir,
21+ readFile,
22+ rm,
23+ stat,
24+ writeFile,
25+} from "node:fs/promises";
26+import * as path from "node:path";
27+
28+const DEFAULT_EPHEMERAL_TTL_HOURS = 24;
29+const DEFAULT_KV_LIMIT = 100;
30+const MAX_KV_LIMIT = 1000;
31+const DEFAULT_SQL_MAX_ROWS = 200;
32+const MAX_SQL_MAX_ROWS = 5000;
33+const MILLIS_PER_HOUR = 3_600_000;
34+const STORAGE_ROOT_DIRECTORY = "storage";
35+const STORAGE_FS_DIRECTORY = "fs";
36+const STORAGE_KV_FILE = "kv-store.json";
37+const STORAGE_SQLITE_FILE = "storage.sqlite";
38+
39+type 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+
48+type SqliteDatabaseConstructor = new (
49+ filename: string,
50+ options?: {
51+ create?: boolean;
52+ },
53+) => SqliteDatabaseInstance;
54+
55+const 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+
64+const 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+
78+const toSourceStoreErrorFromLocalState = (
79+ operation: string,
80+ error: LocalStateStoreError,
81+): SourceStoreError =>
82+ toSourceStoreError(operation, error.message, error.details ?? error.reason ?? null);
83+
84+const 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+
95+const 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+
108+const canAccessStorageInstance = (
109+ instance: StorageInstance,
110+ workspaceId: WorkspaceId,
111+ organizationId: OrganizationId,
112+): boolean =>
113+ instance.workspaceId === workspaceId
114+ || (instance.workspaceId === null && instance.organizationId === organizationId);
115+
116+const 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+
127+const 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+
142+const appendStorageInstance = (
143+ snapshot: LocalStateSnapshot,
144+ storageInstance: StorageInstance,
145+): LocalStateSnapshot => ({
146+ ...snapshot,
147+ generatedAt: Date.now(),
148+ storageInstances: [...snapshot.storageInstances, storageInstance],
149+});
150+
151+const 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+
191+const storageInstanceRootPath = (stateRootDir: string, storageInstanceId: string): string =>
192+ path.resolve(stateRootDir, STORAGE_ROOT_DIRECTORY, storageInstanceId);
193+
194+const storageInstanceFsRootPath = (
195+ stateRootDir: string,
196+ storageInstanceId: string,
197+): string =>
198+ path.resolve(
199+ storageInstanceRootPath(stateRootDir, storageInstanceId),
200+ STORAGE_FS_DIRECTORY,
201+ );
202+
203+const storageInstanceKvPath = (stateRootDir: string, storageInstanceId: string): string =>
204+ path.resolve(
205+ storageInstanceRootPath(stateRootDir, storageInstanceId),
206+ STORAGE_KV_FILE,
207+ );
208+
209+const storageInstanceSqlitePath = (
210+ stateRootDir: string,
211+ storageInstanceId: string,
212+): string =>
213+ path.resolve(
214+ storageInstanceRootPath(stateRootDir, storageInstanceId),
215+ STORAGE_SQLITE_FILE,
216+ );
217+
218+const 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+
249+const 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+
276+const toStorageEntryPath = (absolutePath: string, fsRootPath: string): string => {
277+ const relativePath = path.relative(fsRootPath, absolutePath);
278+ return `/${relativePath.split(path.sep).join("/")}`;
279+};
280+
281+const 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+
294+const 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+
325+const 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+
347+export 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 @@
1+import {
2+ createRuntimeToolCallHandler,
3+ createUnimplementedRuntimeToolInvoker,
4+} from "@executor-v2/engine";
5+import { describe, expect, it } from "@effect/vitest";
6+import * as Effect from "effect/Effect";
7+import * as Option from "effect/Option";
8+
9+import { createPmResolveToolCredentials } from "./credential-resolver";
10+
11+const emptyLocalStateStore = {
12+ getSnapshot: () => Effect.succeed(Option.none()),
13+ writeSnapshot: () => Effect.void,
14+ readEvents: () => Effect.succeed([]),
15+ appendEvents: () => Effect.void,
16+};
17+
18+describe("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 @@
1+import {
2+ type RuntimeToolCallResult,
3+ type RuntimeToolCallRequest,
4+} from "@executor-v2/sdk";
5+import * as Data from "effect/Data";
6+import * as Effect from "effect/Effect";
7+import * as ParseResult from "effect/ParseResult";
8+import * as Schema from "effect/Schema";
9+
10+class PmToolCallHttpRequestError extends Data.TaggedError(
11+ "PmToolCallHttpRequestError",
12+)<{
13+ message: string;
14+ details: string | null;
15+}> {}
16+
17+const 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+
24+const 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+
37+const decodeRuntimeToolCallRequest = Schema.decodeUnknown(RuntimeToolCallRequestSchema);
38+
39+const decodeRequestBodyError = (cause: unknown): PmToolCallHttpRequestError =>
40+ new PmToolCallHttpRequestError({
41+ message: "Invalid runtime callback request body",
42+ details: String(cause),
43+ });
44+
45+const 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+
53+const formatHttpRequestError = (error: PmToolCallHttpRequestError): string =>
54+ error.details && error.details.length > 0
55+ ? `${error.message}: ${error.details}`
56+ : error.message;
57+
58+const 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+
75+export 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 @@
1+import {
2+ SourceStoreError,
3+ ToolArtifactStoreError,
4+ type SourceStore,
5+ type ToolArtifactStore,
6+} from "@executor-v2/persistence-ports";
7+import {
8+ makeControlPlaneToolsService,
9+ type ControlPlaneToolsServiceShape,
10+ type SourceToolDetail,
11+ type SourceToolSummary,
12+} from "@executor-v2/management-api";
13+import {
14+ OpenApiToolManifestSchema,
15+ type Source,
16+ type SourceId,
17+ type ToolArtifact,
18+ type WorkspaceId,
19+} from "@executor-v2/schema";
20+import * as Effect from "effect/Effect";
21+import * as Option from "effect/Option";
22+import * as ParseResult from "effect/ParseResult";
23+import * as Schema from "effect/Schema";
24+
25+const decodeOpenApiToolManifest = Schema.decodeUnknown(OpenApiToolManifestSchema);
26+
27+const 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+
41+const toSourceStoreErrorFromSourceStore = (
42+ operation: string,
43+ error: SourceStoreError,
44+): SourceStoreError =>
45+ toSourceStoreError(operation, error.message, error.details ?? error.reason ?? null);
46+
47+const toSourceStoreErrorFromToolArtifactStore = (
48+ operation: string,
49+ error: ToolArtifactStoreError,
50+): SourceStoreError =>
51+ toSourceStoreError(operation, error.message, error.details ?? error.reason ?? null);
52+
53+const 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+
92+const 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+
111+const 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+
147+export 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 @@
1+import { SourceStoreError } from "@executor-v2/persistence-ports";
2+import {
3+ makeControlPlaneWorkspacesService,
4+ type ControlPlaneWorkspacesServiceShape,
5+} from "@executor-v2/management-api";
6+import {
7+ type LocalStateSnapshot,
8+ type LocalStateStore,
9+ type LocalStateStoreError,
10+} from "@executor-v2/persistence-local";
11+import { type Workspace } from "@executor-v2/schema";
12+import * as Effect from "effect/Effect";
13+import * as Option from "effect/Option";
14+
15+const 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+
29+const toSourceStoreErrorFromLocalState = (
30+ operation: string,
31+ error: LocalStateStoreError,
32+): SourceStoreError =>
33+ toSourceStoreError(operation, error.message, error.details ?? error.reason ?? null);
34+
35+const 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+
47+const 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+
62+const appendWorkspace = (
63+ snapshot: LocalStateSnapshot,
64+ workspace: Workspace,
65+): LocalStateSnapshot => ({
66+ ...snapshot,
67+ generatedAt: Date.now(),
68+ workspaces: [...snapshot.workspaces, workspace],
69+});
70+
71+export 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+
3+Basic 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+
8+Run:
9+
10+- `bun run --cwd apps/web dev`
11+- Open `http://127.0.0.1:3000`
12+
13+By default, control-plane API calls go directly to `http://127.0.0.1:8788`.
14+Override with `NEXT_PUBLIC_CONTROL_PLANE_BASE_URL` (and optionally `CONTROL_PLANE_SERVER_BASE_URL` for SSR).
15+
16+MCP 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+
22+WorkOS 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+
29+When WorkOS is configured, the app requires sign-in and forwards the authenticated WorkOS user id to control-plane as `x-executor-account-id`.
30+For 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+
3+This file defines how we write Effect Atom code in this app.
4+
5+## Goal
6+
7+Keep 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+
36+Create once at module scope:
37+
38+```ts
39+const sourcesResultByWorkspace = Atom.family((workspaceId: WorkspaceId) =>
40+ controlPlaneClient.query("sources", "list", {
41+ path: { workspaceId },
42+ }),
43+);
44+```
45+
46+Then in component:
47+
48+```ts
49+const result = useAtomValue(sourcesResultByWorkspace(workspaceId));
50+```
51+
52+No `useMemo` needed.
53+
54+### 2) Derived state atom for UI projection
55+
56+Map `Result` once in atom-land:
57+
58+```ts
59+const 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+
79+Components switch on `sources.state`, not raw result internals.
80+
81+### 3) Mutations as atoms
82+
83+Define mutation atoms once:
84+
85+```ts
86+const upsertSource = controlPlaneClient.mutation("sources", "upsert");
87+const removeSource = controlPlaneClient.mutation("sources", "remove");
88+```
89+
90+In 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 @@
1+import { ApprovalsView } from "../../../components/approvals/approvals-view";
2+
3+const ApprovalsPage = () => <ApprovalsView />;
4+
5+export default ApprovalsPage;
apps/web/app/(console)/console-shell.tsx+56−0
@@ -0,0 +1,56 @@
1+"use client";
2+
3+import { memo, type ReactNode } from "react";
4+import { useAtomValue } from "@effect-atom/atom-react";
5+
6+import { AppShell } from "../../components/shell/app-shell";
7+import { WorkspaceProvider, useWorkspace } from "../../lib/hooks/use-workspace";
8+import { approvalsByWorkspace } from "../../lib/control-plane/atoms";
9+
10+type ConsoleShellProps = {
11+ authEnabled: boolean;
12+ initialWorkspaceId: string;
13+ children: ReactNode;
14+};
15+
16+export 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+
26+function 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. */
44+const 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 @@
1+import { CredentialsView } from "../../../components/credentials/credentials-view";
2+
3+const CredentialsPage = () => <CredentialsView />;
4+
5+export default CredentialsPage;
apps/web/app/(console)/layout.tsx+42−0
@@ -0,0 +1,42 @@
1+import { withAuth } from "@workos-inc/authkit-nextjs";
2+import { redirect } from "next/navigation";
3+import type { ReactNode } from "react";
4+
5+import { isWorkosEnabled } from "../../lib/workos";
6+import { ConsoleShell } from "./console-shell";
7+
8+type ConsoleLayoutProps = {
9+ children: ReactNode;
10+};
11+
12+const 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+
42+export default ConsoleLayout;
apps/web/app/(console)/policies/page.tsx+5−0
@@ -0,0 +1,5 @@
1+import { PoliciesView } from "../../../components/policies/policies-view";
2+
3+const PoliciesPage = () => <PoliciesView />;
4+
5+export default PoliciesPage;
apps/web/app/(console)/settings/page.tsx+5−0
@@ -0,0 +1,5 @@
1+import SettingsView from "../../../components/settings/settings-view";
2+
3+const SettingsPage = () => <SettingsView />;
4+
5+export default SettingsPage;
apps/web/app/(console)/storage/page.tsx+5−0
@@ -0,0 +1,5 @@
1+import StorageView from "../../../components/storage/storage-view";
2+
3+const StoragePage = () => <StorageView />;
4+
5+export default StoragePage;
apps/web/app/(console)/tools/page.tsx+28−0
@@ -0,0 +1,28 @@
1+import { ToolsView } from "../../../components/tools/tools-view";
2+
3+const 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+
26+const ToolsPage = () => <ToolsView mcpBaseUrl={resolveMcpBaseUrl()} />;
27+
28+export default ToolsPage;
apps/web/app/callback/route.ts+11−0
@@ -0,0 +1,11 @@
1+import type { NextRequest } from "next/server";
2+import { handleAuth } from "@workos-inc/authkit-nextjs";
3+
4+import { externalOriginFromRequest } from "../../lib/workos";
5+
6+export 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 @@
1+import type { Metadata } from "next";
2+import { Fraunces, IBM_Plex_Sans } from "next/font/google";
3+import type { ReactNode } from "react";
4+
5+import { Providers } from "./providers";
6+import "./globals.css";
7+
8+const bodyFont = IBM_Plex_Sans({
9+ subsets: ["latin"],
10+ variable: "--font-body",
11+ weight: ["400", "500", "600"],
12+});
13+
14+const displayFont = Fraunces({
15+ subsets: ["latin"],
16+ variable: "--font-display",
17+ weight: ["500", "700"],
18+});
19+
20+export const metadata: Metadata = {
21+ title: "Executor v2 Control Plane",
22+ description: "Basic Next.js frontend for Executor v2 control plane",
23+};
24+
25+type RootLayoutProps = {
26+ children: ReactNode;
27+};
28+
29+const 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+
38+export default RootLayout;
apps/web/app/mcp/oauth/callback/route.ts+169−0
@@ -0,0 +1,169 @@
1+import { auth } from "@modelcontextprotocol/sdk/client/auth.js";
2+import type { NextRequest } from "next/server";
3+import { NextResponse } from "next/server";
4+
5+import { fetchMcpOAuth } from "../../../../lib/mcp/oauth-fetch";
6+import { getExternalOrigin, isExternalHttps } from "../../../../lib/mcp/oauth-request";
7+import { parseMcpSourceUrl } from "../../../../lib/mcp/oauth-url";
8+import {
9+ buildPendingCookieName,
10+ decodePendingCookieValue,
11+ encodePopupResultCookieValue,
12+ MCP_OAUTH_RESULT_COOKIE,
13+ McpPopupOAuthProvider,
14+ type McpOAuthPopupResult,
15+} from "../../../../lib/mcp/oauth-provider";
16+
17+const MCP_OAUTH_CALLBACK_FLOW_TIMEOUT_MS = 75_000;
18+const MCP_OAUTH_CALLBACK_REQUEST_TIMEOUT_MS = 20_000;
19+
20+const 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+
42+const 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+
72+const toErrorMessage = (error: unknown, fallback: string): string =>
73+ error instanceof Error ? error.message : fallback;
74+
75+export 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+
3+import { useEffect, useRef, useState } from "react";
4+
5+type 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+
23+const 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+
29+const 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+
44+export 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 @@
1+import { discoverOAuthProtectedResourceMetadata, extractWWWAuthenticateParams } from "@modelcontextprotocol/sdk/client/auth.js";
2+import { LATEST_PROTOCOL_VERSION } from "@modelcontextprotocol/sdk/types.js";
3+
4+import { fetchMcpOAuth } from "../../../../lib/mcp/oauth-fetch";
5+import { parseMcpSourceUrl } from "../../../../lib/mcp/oauth-url";
6+
7+type DetectResponse = {
8+ oauth: boolean;
9+ authorizationServers: Array<string>;
10+ detail?: string;
11+};
12+
13+const MCP_OAUTH_CHALLENGE_PROBE_TIMEOUT_MS = 2_500;
14+const MCP_OAUTH_METADATA_TIMEOUT_MS = 12_000;
15+
16+const noStoreDetectJson = (payload: DetectResponse, status = 200): Response =>
17+ Response.json(payload, {
18+ status,
19+ headers: {
20+ "cache-control": "no-store",
21+ },
22+ });
23+
24+const 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+
46+const 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+
90+const toErrorDetail = (error: unknown, fallback: string): string =>
91+ error instanceof Error ? error.message : fallback;
92+
93+export 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 @@
1+import type { NextRequest } from "next/server";
2+import { NextResponse } from "next/server";
3+
4+import {
5+ decodePopupResultCookieValue,
6+ MCP_OAUTH_RESULT_COOKIE,
7+ type McpOAuthPopupResult,
8+} from "../../../../lib/mcp/oauth-provider";
9+
10+type 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+
28+const 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+
69+export 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 @@
1+import { auth } from "@modelcontextprotocol/sdk/client/auth.js";
2+import type { NextRequest } from "next/server";
3+import { NextResponse } from "next/server";
4+
5+import { fetchMcpOAuth } from "../../../../lib/mcp/oauth-fetch";
6+import { getExternalOrigin, isExternalHttps } from "../../../../lib/mcp/oauth-request";
7+import { parseMcpSourceUrl } from "../../../../lib/mcp/oauth-url";
8+import {
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+
18+const MCP_OAUTH_FLOW_TIMEOUT_MS = 75_000;
19+const MCP_OAUTH_REQUEST_TIMEOUT_MS = 20_000;
20+
21+const 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+
43+const 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+
63+const badPopupResponse = (request: NextRequest, message: string): Response =>
64+ popupResultRedirect(request, { ok: false, error: message });
65+
66+const toErrorMessage = (error: unknown, fallback: string): string =>
67+ error instanceof Error ? error.message : fallback;
68+
69+export 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 @@
1+import { redirect } from "next/navigation";
2+
3+const Page = () => {
4+ redirect("/tools");
5+};
6+
7+export default Page;
apps/web/app/providers.tsx+20−0
@@ -0,0 +1,20 @@
1+"use client";
2+
3+import { RegistryProvider } from "@effect-atom/atom-react";
4+import { ThemeProvider } from "next-themes";
5+import type { ReactNode } from "react";
6+
7+type ProvidersProps = {
8+ children: ReactNode;
9+};
10+
11+export 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 @@
1+import type { NextRequest } from "next/server";
2+import { NextResponse } from "next/server";
3+import { getSignInUrl } from "@workos-inc/authkit-nextjs";
4+
5+import { isWorkosEnabled, resolveWorkosRedirectUri } from "../../lib/workos";
6+
7+export 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 @@
1+import type { NextRequest } from "next/server";
2+import { NextResponse } from "next/server";
3+import { signOut } from "@workos-inc/authkit-nextjs";
4+
5+import { externalOriginFromRequest, isWorkosEnabled } from "../../lib/workos";
6+
7+export 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+
3+import { useAtomSet, useAtomValue } from "@effect-atom/atom-react";
4+import type { Approval, ApprovalId } from "@executor-v2/schema";
5+import { useMemo, useState } from "react";
6+
7+import { useWorkspace } from "../../lib/hooks/use-workspace";
8+import {
9+ approvalsByWorkspace,
10+ optimisticResolveApproval,
11+ resolveApproval,
12+} from "../../lib/control-plane/atoms";
13+import { Button } from "../ui/button";
14+import {
15+ Card,
16+ CardContent,
17+ CardDescription,
18+ CardHeader,
19+ CardTitle,
20+} from "../ui/card";
21+import { Input } from "../ui/input";
22+import { Select } from "../ui/select";
23+import { Badge } from "../ui/badge";
24+import { cn, formatTimestamp } from "../../lib/utils";
25+import { matchState } from "../shared/match-state";
26+import { PageHeader } from "../shared/page-header";
27+import { StatusMessage } from "../shared/status-message";
28+
29+type ApprovalFilterValue = "pending" | "resolved" | "all";
30+
31+const 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+
49+const 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+
65+export 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+
72+export 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+
3+import { useMemo, useState, type FormEvent } from "react";
4+import {
5+ useAtomSet,
6+ useAtomValue,
7+} from "@effect-atom/atom-react";
8+
9+import { useWorkspace } from "../../lib/hooks/use-workspace";
10+import {
11+ credentialBindingsByWorkspace,
12+ removeCredentialBinding,
13+ toCredentialBindingRemoveResult,
14+ toCredentialBindingUpsertPayload,
15+ upsertCredentialBinding,
16+} from "../../lib/control-plane/atoms";
17+import type {
18+ CredentialProvider,
19+ CredentialScopeType,
20+ SourceCredentialBinding,
21+} from "@executor-v2/schema";
22+
23+import { Badge } from "../ui/badge";
24+import { Button } from "../ui/button";
25+import { Card, CardContent, CardHeader } from "../ui/card";
26+import { Input } from "../ui/input";
27+import { Select } from "../ui/select";
28+import { matchState } from "../shared/match-state";
29+import { PageHeader } from "../shared/page-header";
30+import { StatusMessage } from "../shared/status-message";
31+import { cn, createLocalId } from "../../lib/utils";
32+
33+const providerOptions: ReadonlyArray<CredentialProvider> = [
34+ "api_key",
35+ "bearer",
36+ "oauth2",
37+ "custom",
38+];
39+
40+const scopeTypeOptions: ReadonlyArray<CredentialScopeType> = [
41+ "workspace",
42+ "organization",
43+ "account",
44+];
45+
46+export 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+
3+import { useAtomSet, useAtomValue } from "@effect-atom/atom-react";
4+import type { Policy, PolicyDecision, PolicyId } from "@executor-v2/schema";
5+import { useMemo, useState } from "react";
6+import type { FormEvent } from "react";
7+
8+import { useWorkspace } from "../../lib/hooks/use-workspace";
9+import {
10+ optimisticRemovePolicy,
11+ optimisticUpsertPolicy,
12+ policiesByWorkspace,
13+ removePolicy,
14+ toPolicyRemoveResult,
15+ toPolicyUpsertPayload,
16+ upsertPolicy,
17+} from "../../lib/control-plane/atoms";
18+import { Badge } from "../ui/badge";
19+import { Button } from "../ui/button";
20+import { Card, CardContent, CardDescription, CardHeader, CardTitle } from "../ui/card";
21+import { Input } from "../ui/input";
22+import { Select } from "../ui/select";
23+import { cn, createLocalId, formatTimestamp } from "../../lib/utils";
24+import { matchState } from "../shared/match-state";
25+import { PageHeader } from "../shared/page-header";
26+import { StatusMessage } from "../shared/status-message";
27+
28+const policyDecisionOptions: ReadonlyArray<PolicyDecision> = ["allow", "require_approval", "deny"];
29+
30+const decisionBadgeVariant = (decision: PolicyDecision): "secondary" | "pending" | "denied" => {
31+ if (decision === "allow") return "secondary";
32+ if (decision === "require_approval") return "pending";
33+ return "denied";
34+};
35+
36+export 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+
3+import { useEffect, useState, type FormEvent } from "react";
4+import { useAtomSet, useAtomValue } from "@effect-atom/atom-react";
5+import type { Organization, Workspace } from "@executor-v2/schema";
6+
7+import { useWorkspace } from "../../lib/hooks/use-workspace";
8+import {
9+ organizationsState,
10+ upsertOrganization,
11+ upsertWorkspace,
12+ toOrganizationUpsertPayload,
13+ toWorkspaceUpsertPayload,
14+ workspacesState,
15+} from "../../lib/control-plane/atoms";
16+import { Badge } from "../ui/badge";
17+import { Button } from "../ui/button";
18+import {
19+ Card,
20+ CardContent,
21+ CardDescription,
22+ CardHeader,
23+ CardTitle,
24+} from "../ui/card";
25+import { Input } from "../ui/input";
26+import { Select } from "../ui/select";
27+import { matchState } from "../shared/match-state";
28+import { PageHeader } from "../shared/page-header";
29+import { StatusMessage } from "../shared/status-message";
30+
31+type OrganizationForm = {
32+ id: string;
33+ slug: string;
34+ name: string;
35+ status: Organization["status"];
36+};
37+
38+type WorkspaceForm = {
39+ id: string;
40+ name: string;
41+ organizationId: string;
42+};
43+
44+const organizationStatusOptions: ReadonlyArray<Organization["status"]> = [
45+ "active",
46+ "suspended",
47+ "archived",
48+];
49+
50+const defaultOrganizationForm = (): OrganizationForm => ({
51+ id: "",
52+ slug: "",
53+ name: "",
54+ status: "active",
55+});
56+
57+const defaultWorkspaceForm = (): WorkspaceForm => ({
58+ id: "",
59+ name: "",
60+ organizationId: "",
61+});
62+
63+const createOrganizationId = (): Organization["id"] =>
64+ `org_${crypto.randomUUID()}` as Organization["id"];
65+
66+const createWorkspaceId = (): Workspace["id"] =>
67+ `ws_${crypto.randomUUID()}` as Workspace["id"];
68+
69+const errorMessage = (cause: unknown, fallback: string): string =>
70+ cause instanceof Error && cause.message.trim().length > 0
71+ ? cause.message
72+ : fallback;
73+
74+const 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+
86+const statusVariant = (message: string | null): "info" | "error" => {
87+ return message?.toLowerCase().includes("failed") ? "error" : "info";
88+};
89+
90+export 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 @@
1+import { cn } from "../../lib/utils";
2+
3+type EmptyStateProps = {
4+ message: string;
5+ className?: string;
6+};
7+
8+export 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 @@
1+import { cn } from "../../lib/utils";
2+
3+type LoadingStateProps = {
4+ message?: string;
5+ className?: string;
6+};
7+
8+export 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 @@
1+import type { ReactNode } from "react";
2+
3+import type { EntityState } from "../../lib/control-plane/atoms";
4+import { EmptyState } from "./empty-state";
5+import { LoadingState } from "./loading-state";
6+import { 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+
23+type MatchStateOptions<T> = {
24+ loading?: string;
25+ empty: string | null;
26+ ready: (items: ReadonlyArray<T>) => ReactNode;
27+ filteredCount?: number;
28+};
29+
30+export 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 @@
1+import type { ReactNode } from "react";
2+
3+type PageHeaderProps = {
4+ title: string;
5+ description?: string;
6+ actions?: ReactNode;
7+};
8+
9+export 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 @@
1+import { cn } from "../../lib/utils";
2+
3+type StatusMessageProps = {
4+ message: string | null;
5+ variant?: "info" | "error";
6+ className?: string;
7+};
8+
9+export 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+
3+import Link from "next/link";
4+import { usePathname } from "next/navigation";
5+import type { ReactNode } from "react";
6+
7+import { cn } from "../../lib/utils";
8+import { ThemeSwitcher } from "./theme-switcher";
9+import { WorkspaceSelector } from "./workspace-selector";
10+
11+type NavItem = {
12+ href: string;
13+ label: string;
14+ icon: ReactNode;
15+ matchPrefixes?: ReadonlyArray<string>;
16+ children?: ReadonlyArray<NavItem>;
17+ badge?: ReactNode;
18+};
19+
20+const 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+
99+const 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+
109+type AppShellProps = {
110+ children: ReactNode;
111+ authEnabled: boolean;
112+ approvalsBadge?: ReactNode;
113+};
114+
115+export 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