The best way to control Claude Code, Codex and more from any computer or phone

main
ts 666 lines 19.8 KB
Raw
1 import * as ces from "@distilled.cloud/gcp/ces_v1";
2 import { createPhysicalName } from "alchemy/PhysicalName";
3 import { tagRecord } from "alchemy/Tags";
4 import * as Data from "effect/Data";
5 import * as Effect from "effect/Effect";
6 import * as Schedule from "effect/Schedule";
7 import * as Stream from "effect/Stream";
8 import { isTransientGcpError } from "../Errors.ts";
9 import {
10 alchemyLabelKeys,
11 createInternalLabels,
12 hasAlchemyLabels,
13 stripInternalLabels,
14 } from "../Labels.ts";
15
16 // CES resource ids must match `[a-zA-Z0-9][a-zA-Z0-9-_]{4,35}`.
17 export const MAX_ID_LENGTH = 36;
18 export const MAX_DISPLAY_NAME_LENGTH = 128;
19 export const MAX_DESCRIPTION_LENGTH = 8000;
20
21 export class CesPending extends Data.TaggedError("GCP.CES.Pending")<{
22 resourceName: string;
23 }> {}
24
25 export const lastSegment = (value: string) => {
26 const trimmed = value.replace(/\/+$/, "");
27 const parts = trimmed.split("/");
28 return parts[parts.length - 1] || trimmed;
29 };
30
31 export const parentOf = (name: string) => {
32 const parts = name.split("/").filter((part) => part.length > 0);
33 return parts.slice(0, -2).join("/");
34 };
35
36 export const locationParent = (project: string, location: string) =>
37 `projects/${project}/locations/${location}`;
38
39 export const normalizeLocation = (location: string | undefined, fallback: string) =>
40 lastSegment(location ?? fallback).toLowerCase();
41
42 export const parseResourceName = (name: string, collection: string, fallbackLocation: string) => {
43 const parts = name.split("/").filter((part) => part.length > 0);
44 const collectionAt = parts.lastIndexOf(collection);
45 const locationsAt = parts.lastIndexOf("locations");
46 const projectsAt = parts.lastIndexOf("projects");
47 const appsAt = parts.lastIndexOf("apps");
48 return {
49 project: projectsAt >= 0 && parts[projectsAt + 1] ? parts[projectsAt + 1]! : "",
50 location:
51 locationsAt >= 0 && parts[locationsAt + 1] ? parts[locationsAt + 1]! : fallbackLocation,
52 appId: appsAt >= 0 && parts[appsAt + 1] ? parts[appsAt + 1]! : "",
53 app: appsAt >= 0 ? parts.slice(0, appsAt + 2).join("/") : parentOf(name),
54 id: collectionAt >= 0 && parts[collectionAt + 1] ? parts[collectionAt + 1]! : lastSegment(name),
55 parent:
56 collectionAt > 0
57 ? parts.slice(0, collectionAt).join("/")
58 : parts.slice(0, Math.max(0, parts.length - 1)).join("/"),
59 };
60 };
61
62 export const expandApp = (value: string, project: string, location: string) =>
63 value.includes("/apps/")
64 ? value.replace(/\/+$/, "")
65 : `${locationParent(project, location)}/apps/${value}`;
66
67 export const sameText = (left: string | undefined, right: string | undefined) =>
68 (left ?? "") === (right ?? "");
69
70 export const canonical = (value: unknown): unknown => {
71 if (value === undefined || value === null) return undefined;
72 if (typeof value === "boolean" || typeof value === "number") return value;
73 if (typeof value === "string") {
74 return value.length === 0 ? undefined : value;
75 }
76 if (Array.isArray(value)) {
77 const items = value.map(canonical).filter((item) => item !== undefined);
78 return items.length === 0 ? undefined : items;
79 }
80 if (typeof value === "object") {
81 const entries = Object.entries(value as Record<string, unknown>)
82 .map(([key, item]) => [key, canonical(item)] as const)
83 .filter(([, item]) => item !== undefined)
84 .sort(([left], [right]) => left.localeCompare(right));
85 if (entries.length === 0) return undefined;
86 return Object.fromEntries(entries);
87 }
88 return undefined;
89 };
90
91 export const fingerprint = (value: unknown): string => JSON.stringify(canonical(value) ?? null);
92
93 export const sameJson = (left: unknown, right: unknown) => fingerprint(left) === fingerprint(right);
94
95 export const updateMaskOf = (...fields: Array<string | undefined>) =>
96 fields.filter((field): field is string => field !== undefined).join(",");
97
98 export const toPhysicalId = (
99 id: string,
100 explicit: string | undefined,
101 existing: string | undefined,
102 maxLength = MAX_ID_LENGTH,
103 ) =>
104 Effect.gen(function* () {
105 if (explicit !== undefined) return explicit;
106 if (existing !== undefined) return existing;
107 const generated = yield* createPhysicalName({
108 id,
109 maxLength,
110 lowercase: true,
111 });
112 const next = /^[a-z]/.test(generated) ? generated : `c${generated}`.slice(0, maxLength);
113 return next.length >= 4 ? next : `${next}xxxx`.slice(0, maxLength);
114 });
115
116 export const userMetadata = (
117 metadata: Record<string, string | undefined> | null | undefined,
118 ): Record<string, string> => stripInternalLabels(tagRecord(metadata));
119
120 export const hasAlchemyLabelMap = (labels: Record<string, string | undefined> | null | undefined) =>
121 Object.keys(labels ?? {}).some((key) => key.startsWith("alchemy-"));
122
123 const markerOf = (labels: Record<string, string>, stack: string, stage: string, id: string) =>
124 `[alchemy ${alchemyLabelKeys.stack}=${stack} ${alchemyLabelKeys.stage}=${stage} ${alchemyLabelKeys.id}=${id}]`;
125
126 const compactMarkerOf = (stack: string, stage: string, id: string) =>
127 `[alc ${stack} ${stage} ${id}]`;
128
129 const shrinkMarker = (
130 labels: Record<string, string>,
131 maxLength: number,
132 build: (stack: string, stage: string, id: string) => string,
133 ) => {
134 let stack = labels[alchemyLabelKeys.stack] ?? "x";
135 let stage = labels[alchemyLabelKeys.stage] ?? "x";
136 let id = labels[alchemyLabelKeys.id] ?? "x";
137 let marker = build(stack, stage, id);
138 while (marker.length > maxLength && (stack.length > 1 || stage.length > 1 || id.length > 1)) {
139 if (stack.length >= stage.length && stack.length >= id.length) {
140 stack = stack.slice(0, -1);
141 } else if (stage.length >= id.length) {
142 stage = stage.slice(0, -1);
143 } else {
144 id = id.slice(0, -1);
145 }
146 marker = build(stack, stage, id);
147 }
148 return marker.slice(0, maxLength);
149 };
150
151 export const encodeOwnership = (
152 labels: Record<string, string>,
153 text: string | undefined,
154 ): string => {
155 const marker = shrinkMarker(labels, MAX_DESCRIPTION_LENGTH, (stack, stage, id) =>
156 markerOf(labels, stack, stage, id),
157 );
158 const trimmed = text?.trim();
159 return trimmed && trimmed.length > 0 ? `${marker}\n${trimmed}` : marker;
160 };
161
162 export const encodeOwnershipLine = (
163 labels: Record<string, string>,
164 text: string | undefined,
165 maxLength = MAX_DISPLAY_NAME_LENGTH,
166 ): string => {
167 const trimmed = text?.replace(/[\r\n]+/g, " ").trim();
168 // Shrink the marker, not the user text, so the display name round-trips.
169 const budget = trimmed ? Math.max(maxLength - trimmed.length - 1, 16) : maxLength;
170 const marker =
171 budget < 54
172 ? shrinkMarker(labels, budget, compactMarkerOf)
173 : shrinkMarker(labels, budget, (stack, stage, id) => markerOf(labels, stack, stage, id));
174 if (!trimmed) return marker;
175 return `${marker} ${trimmed}`.slice(0, maxLength);
176 };
177
178 export const parseOwnership = (
179 text: string | undefined,
180 ): {
181 labels: Record<string, string>;
182 text: string | undefined;
183 } => {
184 if (text?.startsWith("[alc ")) {
185 const end = text.indexOf("]");
186 if (end < 0) return { labels: {}, text };
187 const parts = text.slice("[alc ".length, end).trim().split(/\s+/);
188 const labels: Record<string, string> = {};
189 if (parts[0]) labels[alchemyLabelKeys.stack] = parts[0]!;
190 if (parts[1]) labels[alchemyLabelKeys.stage] = parts[1]!;
191 if (parts[2]) labels[alchemyLabelKeys.id] = parts[2]!;
192 const rest = text.slice(end + 1).replace(/^[\s\n]+/, "");
193 return { labels, text: rest.length > 0 ? rest : undefined };
194 }
195 if (!text?.startsWith("[alchemy ")) {
196 return { labels: {}, text };
197 }
198 const end = text.indexOf("]");
199 if (end < 0) return { labels: {}, text };
200 const labels: Record<string, string> = {};
201 for (const part of text.slice("[alchemy ".length, end).split(/\s+/)) {
202 const eq = part.indexOf("=");
203 if (eq > 0) {
204 labels[part.slice(0, eq)] = part.slice(eq + 1);
205 }
206 }
207 const rest = text.slice(end + 1).replace(/^[\s\n]+/, "");
208 return { labels, text: rest.length > 0 ? rest : undefined };
209 };
210
211 export const hasOwnershipMarker = (text: string | undefined) =>
212 Object.keys(parseOwnership(text).labels).some((key) => key.startsWith("alchemy-"));
213
214 const prefixMatch = (expected: string, observed: string) =>
215 expected === observed || expected.startsWith(observed) || observed.startsWith(expected);
216
217 export const ownedByAlchemy = (id: string, text: string | undefined) =>
218 Effect.gen(function* () {
219 const expected = yield* createInternalLabels(id);
220 const { labels } = parseOwnership(text);
221 if (!hasOwnershipMarker(text)) return false;
222 const exact = yield* hasAlchemyLabels(id, labels);
223 if (exact) return true;
224 return (
225 prefixMatch(expected[alchemyLabelKeys.stack] ?? "", labels[alchemyLabelKeys.stack] ?? "") &&
226 prefixMatch(expected[alchemyLabelKeys.stage] ?? "", labels[alchemyLabelKeys.stage] ?? "") &&
227 prefixMatch(expected[alchemyLabelKeys.id] ?? "", labels[alchemyLabelKeys.id] ?? "")
228 );
229 });
230
231 export const ownedByAlchemyLabels = (
232 id: string,
233 labels: Record<string, string | undefined> | null | undefined,
234 ) =>
235 Effect.gen(function* () {
236 const expected = yield* createInternalLabels(id);
237 const observed = tagRecord(labels);
238 if (!hasAlchemyLabelMap(observed)) return false;
239 const exact = yield* hasAlchemyLabels(id, observed);
240 if (exact) return true;
241 return (
242 prefixMatch(expected[alchemyLabelKeys.stack] ?? "", observed[alchemyLabelKeys.stack] ?? "") &&
243 prefixMatch(expected[alchemyLabelKeys.stage] ?? "", observed[alchemyLabelKeys.stage] ?? "") &&
244 prefixMatch(expected[alchemyLabelKeys.id] ?? "", observed[alchemyLabelKeys.id] ?? "")
245 );
246 });
247
248 export const replaceOnIdentity = (input: {
249 previousId?: string;
250 nextId?: string;
251 previousParent?: string;
252 nextParent?: string;
253 extra?: boolean;
254 }) => {
255 if (input.extra === true) {
256 return { action: "replace" as const, deleteFirst: false };
257 }
258 if (
259 input.previousId !== undefined &&
260 input.nextId !== undefined &&
261 input.previousId !== input.nextId
262 ) {
263 return { action: "replace" as const, deleteFirst: false };
264 }
265 if (
266 input.previousParent !== undefined &&
267 input.nextParent !== undefined &&
268 input.previousParent !== input.nextParent
269 ) {
270 return { action: "replace" as const, deleteFirst: false };
271 }
272 return undefined;
273 };
274
275 export const retryTransient = <A, E extends { readonly _tag: string }, R>(
276 effect: Effect.Effect<A, E, R>,
277 ) =>
278 effect.pipe(
279 Effect.retry({
280 while: isTransientGcpError,
281 times: 8,
282 schedule: Schedule.exponential("250 millis"),
283 }),
284 );
285
286 export class DeleteNotConfirmed extends Data.TaggedError("GCP.CES.DeleteNotConfirmed")<{}> {}
287
288 /** Poll until the resource is gone; fails if it is still readable after ~60s. */
289 export const waitUntilGone = <A, E, R>(get: Effect.Effect<A | undefined, E, R>) =>
290 get.pipe(
291 Effect.repeat({
292 schedule: Schedule.spaced("2 seconds"),
293 until: (value) => value === undefined,
294 times: 30,
295 }),
296 Effect.flatMap((value): Effect.Effect<void, DeleteNotConfirmed> =>
297 value === undefined ? Effect.void : Effect.fail(new DeleteNotConfirmed()),
298 ),
299 );
300
301 export const waitForVisible = <A, E, R>(get: Effect.Effect<A | undefined, E, R>) =>
302 get.pipe(
303 Effect.filterOrFail(
304 (value): value is A => value !== undefined,
305 () => new CesPending({ resourceName: "" }),
306 ),
307 Effect.retry({
308 // New apps can take a couple of minutes to become readable.
309 while: (error) => error instanceof CesPending,
310 times: 40,
311 schedule: Schedule.spaced("3 seconds"),
312 }),
313 Effect.catchIf(
314 (error): error is CesPending => error instanceof CesPending,
315 () => Effect.undefined,
316 ),
317 );
318
319 const emptyList = <A>() => Effect.succeed<A[]>([]);
320
321 type ListedError = ces.NotFound | ces.Forbidden | ces.GcpOpError;
322
323 export const collectPages = <Page, Item, R>(
324 pages: Stream.Stream<Page, ListedError, R>,
325 items: (page: Page) => readonly Item[] | null | undefined,
326 ) =>
327 pages.pipe(
328 Stream.flatMap((page) => Stream.fromIterable(items(page) ?? [])),
329 Stream.runCollect,
330 Effect.map((chunk) => Array.from(chunk)),
331 Effect.catchTag("NotFound", () => emptyList<Item>()),
332 );
333
334 export const listApps = (parent: string) =>
335 parent.length === 0
336 ? emptyList<ces.App>()
337 : collectPages(
338 ces.listProjectsLocationsApps.pages({ parent, pageSize: 100 }),
339 (page) => page.apps,
340 );
341
342 export const namedApps = (project: string, location: string) =>
343 listApps(locationParent(project, location)).pipe(
344 Effect.map((apps) =>
345 apps.filter(
346 (app): app is ces.App & { name: string } =>
347 typeof app.name === "string" && app.name.length > 0,
348 ),
349 ),
350 );
351
352 export const forEachApp = <A, E, R>(
353 project: string,
354 list: (parent: string) => Effect.Effect<A[], E, R>,
355 location: string,
356 ) =>
357 Effect.gen(function* () {
358 // Children of Alchemy-owned apps (ownership lives in app metadata).
359 const apps = (yield* namedApps(project, location)).filter((app) =>
360 hasAlchemyLabelMap(app.metadata),
361 );
362 const groups = yield* Effect.forEach(apps, (app) => list(app.name), {
363 concurrency: 4,
364 });
365 return groups.flat();
366 });
367
368 export const DEFAULT_OPENAPI_SCHEMA = JSON.stringify({
369 openapi: "3.0.0",
370 info: { title: "Alchemy", version: "1.0.0" },
371 paths: {
372 "/ping": {
373 get: {
374 operationId: "ping",
375 responses: {
376 "200": { description: "ok" },
377 },
378 },
379 },
380 },
381 });
382
383 export const DEFAULT_CHANNEL_PROFILE: ces.ChannelProfile = {
384 channelType: "API",
385 profileId: "api",
386 };
387
388 export const toolKind = (tool: {
389 fileSearchTool?: unknown;
390 pythonFunction?: unknown;
391 googleSearchTool?: unknown;
392 mcpTool?: unknown;
393 remoteAgentTool?: unknown;
394 widgetTool?: unknown;
395 systemTool?: unknown;
396 openApiTool?: unknown;
397 connectorTool?: unknown;
398 dataStoreTool?: unknown;
399 agentTool?: unknown;
400 clientFunction?: unknown;
401 }) => {
402 if (tool.fileSearchTool) return "fileSearchTool";
403 if (tool.pythonFunction) return "pythonFunction";
404 if (tool.googleSearchTool) return "googleSearchTool";
405 if (tool.mcpTool) return "mcpTool";
406 if (tool.remoteAgentTool) return "remoteAgentTool";
407 if (tool.widgetTool) return "widgetTool";
408 if (tool.systemTool) return "systemTool";
409 if (tool.openApiTool) return "openApiTool";
410 if (tool.connectorTool) return "connectorTool";
411 if (tool.dataStoreTool) return "dataStoreTool";
412 if (tool.agentTool) return "agentTool";
413 return "clientFunction";
414 };
415
416 export const toolsetKind = (toolset: {
417 openApiToolset?: unknown;
418 mcpToolset?: unknown;
419 connectorToolset?: unknown;
420 }) => {
421 if (toolset.mcpToolset) return "mcpToolset";
422 if (toolset.connectorToolset) return "connectorToolset";
423 return "openApiToolset";
424 };
425
426 export const toolOwnershipText = (tool: ces.Tool) =>
427 tool.clientFunction?.description ??
428 tool.pythonFunction?.description ??
429 tool.googleSearchTool?.description ??
430 tool.fileSearchTool?.description ??
431 tool.remoteAgentTool?.description ??
432 tool.widgetTool?.description ??
433 tool.openApiTool?.description ??
434 tool.connectorTool?.description ??
435 tool.dataStoreTool?.description ??
436 tool.agentTool?.description ??
437 tool.systemTool?.description ??
438 tool.mcpTool?.description;
439
440 export const stampToolDescription = (
441 tool: ces.Tool,
442 ownership: Record<string, string>,
443 ): ces.Tool => {
444 const stamp = (text: string | undefined) => encodeOwnership(ownership, text);
445 if (tool.pythonFunction) {
446 return {
447 ...tool,
448 pythonFunction: {
449 ...tool.pythonFunction,
450 description: stamp(tool.pythonFunction.description),
451 },
452 };
453 }
454 if (tool.googleSearchTool) {
455 return {
456 ...tool,
457 googleSearchTool: {
458 ...tool.googleSearchTool,
459 description: stamp(tool.googleSearchTool.description),
460 },
461 };
462 }
463 if (tool.fileSearchTool) {
464 return {
465 ...tool,
466 fileSearchTool: {
467 ...tool.fileSearchTool,
468 description: stamp(tool.fileSearchTool.description),
469 },
470 };
471 }
472 if (tool.remoteAgentTool) {
473 return {
474 ...tool,
475 remoteAgentTool: {
476 ...tool.remoteAgentTool,
477 description: stamp(tool.remoteAgentTool.description),
478 },
479 };
480 }
481 if (tool.widgetTool) {
482 return {
483 ...tool,
484 widgetTool: {
485 ...tool.widgetTool,
486 description: stamp(tool.widgetTool.description),
487 },
488 };
489 }
490 if (tool.openApiTool) {
491 return {
492 ...tool,
493 openApiTool: {
494 ...tool.openApiTool,
495 description: stamp(tool.openApiTool.description),
496 },
497 };
498 }
499 if (tool.connectorTool) {
500 return {
501 ...tool,
502 connectorTool: {
503 ...tool.connectorTool,
504 description: stamp(tool.connectorTool.description),
505 },
506 };
507 }
508 if (tool.dataStoreTool) {
509 return {
510 ...tool,
511 dataStoreTool: {
512 ...tool.dataStoreTool,
513 description: stamp(tool.dataStoreTool.description),
514 },
515 };
516 }
517 if (tool.agentTool) {
518 return {
519 ...tool,
520 agentTool: {
521 ...tool.agentTool,
522 description: stamp(tool.agentTool.description),
523 },
524 };
525 }
526 if (tool.systemTool) {
527 return {
528 ...tool,
529 systemTool: {
530 ...tool.systemTool,
531 description: stamp(tool.systemTool.description),
532 },
533 };
534 }
535 if (tool.mcpTool) {
536 return {
537 ...tool,
538 mcpTool: {
539 ...tool.mcpTool,
540 description: stamp(tool.mcpTool.description),
541 },
542 };
543 }
544 return {
545 ...tool,
546 clientFunction: {
547 name: tool.clientFunction?.name ?? "alchemy_fn",
548 description: stamp(tool.clientFunction?.description),
549 parameters: tool.clientFunction?.parameters,
550 response: tool.clientFunction?.response,
551 },
552 };
553 };
554
555 export const unstampToolDescription = (tool: ces.Tool): ces.Tool => {
556 const unstamp = (text: string | undefined) => parseOwnership(text).text;
557 if (tool.pythonFunction) {
558 return {
559 ...tool,
560 pythonFunction: {
561 ...tool.pythonFunction,
562 description: unstamp(tool.pythonFunction.description),
563 },
564 };
565 }
566 if (tool.googleSearchTool) {
567 return {
568 ...tool,
569 googleSearchTool: {
570 ...tool.googleSearchTool,
571 description: unstamp(tool.googleSearchTool.description),
572 },
573 };
574 }
575 if (tool.fileSearchTool) {
576 return {
577 ...tool,
578 fileSearchTool: {
579 ...tool.fileSearchTool,
580 description: unstamp(tool.fileSearchTool.description),
581 },
582 };
583 }
584 if (tool.remoteAgentTool) {
585 return {
586 ...tool,
587 remoteAgentTool: {
588 ...tool.remoteAgentTool,
589 description: unstamp(tool.remoteAgentTool.description),
590 },
591 };
592 }
593 if (tool.widgetTool) {
594 return {
595 ...tool,
596 widgetTool: {
597 ...tool.widgetTool,
598 description: unstamp(tool.widgetTool.description),
599 },
600 };
601 }
602 if (tool.openApiTool) {
603 return {
604 ...tool,
605 openApiTool: {
606 ...tool.openApiTool,
607 description: unstamp(tool.openApiTool.description),
608 },
609 };
610 }
611 if (tool.connectorTool) {
612 return {
613 ...tool,
614 connectorTool: {
615 ...tool.connectorTool,
616 description: unstamp(tool.connectorTool.description),
617 },
618 };
619 }
620 if (tool.dataStoreTool) {
621 return {
622 ...tool,
623 dataStoreTool: {
624 ...tool.dataStoreTool,
625 description: unstamp(tool.dataStoreTool.description),
626 },
627 };
628 }
629 if (tool.agentTool) {
630 return {
631 ...tool,
632 agentTool: {
633 ...tool.agentTool,
634 description: unstamp(tool.agentTool.description),
635 },
636 };
637 }
638 if (tool.systemTool) {
639 return {
640 ...tool,
641 systemTool: {
642 ...tool.systemTool,
643 description: unstamp(tool.systemTool.description),
644 },
645 };
646 }
647 if (tool.mcpTool) {
648 return {
649 ...tool,
650 mcpTool: {
651 ...tool.mcpTool,
652 description: unstamp(tool.mcpTool.description),
653 },
654 };
655 }
656 if (tool.clientFunction) {
657 return {
658 ...tool,
659 clientFunction: {
660 ...tool.clientFunction,
661 description: unstamp(tool.clientFunction.description),
662 },
663 };
664 }
665 return tool;
666 };