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

main
ts 444 lines 15.1 KB
Raw
1 import * as aiplatform from "@distilled.cloud/gcp/aiplatform_v1";
2 import { Unowned } from "alchemy/AdoptPolicy";
3 import { isResolved } from "alchemy/Diff";
4 import * as Provider from "alchemy/Provider";
5 import { Resource } from "alchemy/Resource";
6 import { tagRecord } from "alchemy/Tags";
7 import * as Data from "effect/Data";
8 import * as Effect from "effect/Effect";
9 import * as Schedule from "effect/Schedule";
10 import { GcpEnvironment } from "../Environment.ts";
11 import { createInternalLabels, hasAlchemyLabels, toLabels } from "../Labels.ts";
12 import type { Providers } from "../Providers.ts";
13 import { listLocations } from "./names.ts";
14 import { resourceNameFromOperation, waitForOperation } from "./operations.ts";
15 import {
16 AiPlatformNotResolved,
17 AiPlatformStillExists,
18 collectPages,
19 jsonEqual,
20 locationParent,
21 normalizeLocation,
22 parseResourceName,
23 toPhysicalId,
24 userLabels,
25 type EncryptionSpec,
26 type MachineSpec,
27 type NetworkSpec,
28 type PersistentDiskSpec,
29 } from "./shared.ts";
30
31 const COLLECTION = "notebookRuntimeTemplates";
32 const DEFAULT_MACHINE_TYPE = "e2-standard-4";
33
34 export type NotebookEnvVar = {
35 /** Environment variable name. */
36 name?: string;
37 /** Environment variable value. */
38 value?: string;
39 };
40
41 export type ColabImage = {
42 /** Colab Enterprise release name (e.g. `colab-enterprise-release`). */
43 releaseName?: string;
44 };
45
46 export type PostStartupScriptConfig = {
47 /** Inline post-startup script. */
48 postStartupScript?: string;
49 /** Cloud Storage URI of a post-startup script. */
50 postStartupScriptUrl?: string;
51 /** When the script runs (`RUN_ONCE`, `RUN_EVERY_START`). */
52 postStartupScriptBehavior?: string;
53 };
54
55 export type NotebookSoftwareConfig = {
56 /** Google-managed Colab image. */
57 colabImage?: ColabImage;
58 /** Environment variables passed to the runtime. */
59 env?: NotebookEnvVar[];
60 /** Post-startup script configuration. */
61 postStartupScriptConfig?: PostStartupScriptConfig;
62 };
63
64 export type NotebookReservationAffinity = {
65 /** Affinity type (`NO_RESERVATION`, `ANY_RESERVATION`, `SPECIFIC_RESERVATION`). */
66 reservationAffinityType?: string;
67 /** Label key of the reservation. */
68 key?: string;
69 /** Reservation resource names. */
70 values?: string[];
71 };
72
73 export type NotebookRuntimeTemplateProps = {
74 /**
75 * Template id (the `{notebook_runtime_template}` segment). If omitted,
76 * a unique RFC1035 name is generated. Immutable — changing it replaces
77 * the template.
78 */
79 notebookRuntimeTemplateId?: string;
80 /**
81 * Vertex AI location. Immutable — changing it replaces the template.
82 * `US-CENTRAL1` is accepted and normalized to `us-central1`.
83 * @default the stack's GCP region (`GCP.Region`, else the profile region, else `us-central1`)
84 */
85 location?: string;
86 /**
87 * Display name (max 128 UTF-8 characters). Defaults to the template id.
88 */
89 displayName?: string;
90 /**
91 * Human-readable description. Vertex AI cannot update it, so changing
92 * it replaces the template.
93 */
94 description?: string;
95 /**
96 * User labels. Alchemy ownership labels are merged in automatically.
97 * Vertex AI cannot update them, so changing them replaces the template.
98 */
99 labels?: Record<string, string>;
100 /**
101 * Runtime type. Immutable.
102 * `USER_DEFINED` or `ONE_CLICK`.
103 */
104 notebookRuntimeType?: string;
105 /**
106 * Machine spec. Immutable — changing it replaces the template.
107 * @default { machineType: "e2-standard-4" }
108 */
109 machineSpec?: MachineSpec;
110 /**
111 * Persistent data disk attached to the runtime.
112 */
113 dataPersistentDiskSpec?: PersistentDiskSpec;
114 /**
115 * Network spec.
116 */
117 networkSpec?: NetworkSpec;
118 /**
119 * Notebook software configuration.
120 */
121 softwareConfig?: NotebookSoftwareConfig;
122 /**
123 * Customer-managed encryption key.
124 */
125 encryptionSpec?: EncryptionSpec;
126 /**
127 * Compute Engine network tags.
128 */
129 networkTags?: string[];
130 /**
131 * Idle shutdown configuration.
132 */
133 idleShutdownConfig?: {
134 idleTimeout?: string;
135 idleShutdownDisabled?: boolean;
136 };
137 /**
138 * Shielded VM config. Immutable.
139 */
140 shieldedVmConfig?: { enableSecureBoot?: boolean };
141 /**
142 * Reservation affinity.
143 */
144 reservationAffinity?: NotebookReservationAffinity;
145 };
146
147 export type NotebookRuntimeTemplate = Resource<
148 "GCP.AIPlatform.NotebookRuntimeTemplate",
149 NotebookRuntimeTemplateProps,
150 {
151 /** Full resource name. */
152 name: string;
153 /** Template id (last path segment). */
154 notebookRuntimeTemplateId: string;
155 /** Project id. */
156 project: string;
157 /** Location id. */
158 location: string;
159 /** Display name. */
160 displayName: string | undefined;
161 /** Description. */
162 description: string | undefined;
163 /** User labels (Alchemy ownership labels stripped). */
164 labels: Record<string, string>;
165 /** Runtime type. */
166 notebookRuntimeType: string | undefined;
167 /** Machine type. */
168 machineType: string | undefined;
169 /** RFC3339 creation timestamp. */
170 createTime: string | undefined;
171 /** RFC3339 last-update timestamp. */
172 updateTime: string | undefined;
173 /** Etag for read-modify-write. */
174 etag: string | undefined;
175 },
176 never,
177 Providers
178 >;
179
180 /**
181 * A Vertex AI notebook runtime template — machine, disk, network, and
182 * software defaults used to create Colab Enterprise runtimes.
183 *
184 * Only `displayName` and `softwareConfig` update in place; changing
185 * `notebookRuntimeTemplateId`, `location`, `machineSpec`,
186 * `notebookRuntimeType`, `description`, or `labels` replaces the template.
187 *
188 * ### Creating a Template
189 * **Example:** Generated name
190 * ```typescript
191 * const template = yield* GCP.AIPlatform.NotebookRuntimeTemplate("Runtime", {
192 * machineSpec: { machineType: "e2-standard-4" },
193 * });
194 * ```
195 *
196 * **Example:** Named template with labels
197 * ```typescript
198 * const template = yield* GCP.AIPlatform.NotebookRuntimeTemplate("Runtime", {
199 * notebookRuntimeTemplateId: "colab-default",
200 * displayName: "colab default",
201 * labels: { env: "prod" },
202 * machineSpec: { machineType: "e2-standard-4" },
203 * networkSpec: { enableInternetAccess: true },
204 * });
205 * ```
206 *
207 * @resource
208 * @category AIPlatform
209 */
210 export const NotebookRuntimeTemplate = Resource<NotebookRuntimeTemplate>(
211 "GCP.AIPlatform.NotebookRuntimeTemplate",
212 );
213
214 export class NotebookRuntimeTemplateNotResolved extends Data.TaggedError(
215 "GCP.AIPlatform.NotebookRuntimeTemplateNotResolved",
216 )<{
217 resourceName: string;
218 }> {}
219
220 const resourceName = (project: string, location: string, id: string) =>
221 `${locationParent(project, location)}/${COLLECTION}/${id}`;
222
223 const toAttrs = (
224 template: aiplatform.GoogleCloudAiplatformV1NotebookRuntimeTemplate,
225 project: string,
226 ) => {
227 const name = template.name ?? "";
228 const parsed = parseResourceName(name, COLLECTION);
229 return {
230 name,
231 notebookRuntimeTemplateId: parsed.id,
232 project: parsed.project || project,
233 location: parsed.location,
234 displayName: template.displayName,
235 description: template.description,
236 labels: userLabels(template.labels),
237 notebookRuntimeType: template.notebookRuntimeType,
238 machineType: template.machineSpec?.machineType,
239 createTime: template.createTime,
240 updateTime: template.updateTime,
241 etag: template.etag,
242 };
243 };
244
245 const getByName = (name: string) =>
246 aiplatform
247 .getProjectsLocationsNotebookRuntimeTemplates({ name })
248 .pipe(Effect.catchTag("NotFound", () => Effect.undefined));
249
250 const waitUntilExists = (name: string) =>
251 getByName(name).pipe(
252 Effect.filterOrFail(
253 (template): template is aiplatform.GoogleCloudAiplatformV1NotebookRuntimeTemplate =>
254 template !== undefined,
255 () => new AiPlatformNotResolved({ resourceName: name }),
256 ),
257 Effect.retry({
258 while: (error) => error._tag === "GCP.AIPlatform.NotResolved",
259 times: 8,
260 schedule: Schedule.spaced("2 seconds"),
261 }),
262 );
263
264 const waitUntilGone = (name: string) =>
265 getByName(name).pipe(
266 Effect.filterOrFail(
267 (template) => template === undefined,
268 () => new AiPlatformStillExists({ resourceName: name }),
269 ),
270 Effect.asVoid,
271 Effect.retry({
272 while: (error) => error._tag === "GCP.AIPlatform.StillExists",
273 times: 10,
274 schedule: Schedule.spaced("2 seconds"),
275 }),
276 );
277
278 const desiredMachine = (spec: MachineSpec | undefined): MachineSpec => ({
279 machineType: spec?.machineType ?? DEFAULT_MACHINE_TYPE,
280 acceleratorType: spec?.acceleratorType,
281 acceleratorCount: spec?.acceleratorCount,
282 gpuPartitionSize: spec?.gpuPartitionSize,
283 tpuTopology: spec?.tpuTopology,
284 });
285
286 export const NotebookRuntimeTemplateProvider = () =>
287 Provider.succeed(NotebookRuntimeTemplate, {
288 stables: ["name", "notebookRuntimeTemplateId", "project", "location", "createTime"],
289
290 diff: Effect.fn(function* ({ news, olds, output }) {
291 const env = yield* GcpEnvironment.current;
292 if (!isResolved(news)) return undefined;
293 const previousId = olds?.notebookRuntimeTemplateId ?? output?.notebookRuntimeTemplateId;
294 const nextId = news.notebookRuntimeTemplateId ?? previousId;
295 const previousLocation = normalizeLocation(olds?.location ?? output?.location, env.region);
296 const nextLocation = normalizeLocation(news.location ?? output?.location, env.region);
297 const previousMachine = olds?.machineSpec?.machineType ?? output?.machineType;
298 const nextMachine = desiredMachine(news.machineSpec).machineType;
299 const typeChanged =
300 (news.notebookRuntimeType ?? olds?.notebookRuntimeType) !==
301 (olds?.notebookRuntimeType ?? output?.notebookRuntimeType);
302 const replace =
303 (previousId !== undefined && nextId !== undefined && nextId !== previousId) ||
304 previousLocation !== nextLocation ||
305 (previousMachine !== undefined && previousMachine !== nextMachine) ||
306 (olds?.notebookRuntimeType !== undefined && typeChanged) ||
307 (olds !== undefined &&
308 ((news.description ?? "") !== (olds.description ?? "") ||
309 JSON.stringify(news.labels ?? {}) !== JSON.stringify(olds.labels ?? {})));
310 if (!replace) return undefined;
311 return {
312 action: "replace" as const,
313 deleteFirst:
314 previousLocation === nextLocation && previousId !== undefined && nextId === previousId,
315 };
316 }),
317
318 read: Effect.fn(function* ({ id, olds, output }) {
319 const env = yield* GcpEnvironment.current;
320 const templateId = yield* toPhysicalId(
321 id,
322 olds?.notebookRuntimeTemplateId,
323 output?.notebookRuntimeTemplateId,
324 );
325 const location = normalizeLocation(olds?.location ?? output?.location, env.region);
326 const name = output?.name ?? resourceName(env.project, location, templateId);
327 const existing = yield* getByName(name);
328 if (existing === undefined) return undefined;
329 const attrs = toAttrs(existing, env.project);
330 return (yield* hasAlchemyLabels(id, tagRecord(existing.labels))) ? attrs : Unowned(attrs);
331 }),
332
333 list: () =>
334 Effect.gen(function* () {
335 const env = yield* GcpEnvironment.current;
336 const pages = (yield* Effect.forEach(listLocations(env.region), (location) =>
337 collectPages(
338 aiplatform.listProjectsLocationsNotebookRuntimeTemplates.pages({
339 parent: locationParent(env.project, location),
340 pageSize: 100,
341 }),
342 ).pipe(Effect.catchTag("NotFound", () => Effect.succeed([]))),
343 )).flat();
344 return pages.flatMap((page) =>
345 (page.notebookRuntimeTemplates ?? [])
346 .filter((template) =>
347 Object.keys(template.labels ?? {}).some((key) => key.startsWith("alchemy-")),
348 )
349 .map((template) => toAttrs(template, env.project)),
350 );
351 }),
352
353 reconcile: Effect.fn(function* ({ id, news, output }) {
354 const env = yield* GcpEnvironment.current;
355 const templateId = yield* toPhysicalId(
356 id,
357 news.notebookRuntimeTemplateId,
358 output?.notebookRuntimeTemplateId,
359 );
360 const location = normalizeLocation(news.location ?? output?.location, env.region);
361 const name = resourceName(env.project, location, templateId);
362 const desiredLabels = {
363 ...toLabels(news.labels),
364 ...(yield* createInternalLabels(id)),
365 };
366 const displayName = news.displayName ?? templateId;
367 const machineSpec = desiredMachine(news.machineSpec);
368
369 let current = yield* getByName(output?.name ?? name);
370
371 if (current === undefined) {
372 const created = yield* aiplatform
373 .createProjectsLocationsNotebookRuntimeTemplates({
374 parent: locationParent(env.project, location),
375 notebookRuntimeTemplateId: templateId,
376 body: {
377 displayName,
378 description: news.description,
379 labels: desiredLabels,
380 notebookRuntimeType: news.notebookRuntimeType,
381 machineSpec,
382 dataPersistentDiskSpec: news.dataPersistentDiskSpec,
383 networkSpec: news.networkSpec,
384 softwareConfig: news.softwareConfig,
385 encryptionSpec: news.encryptionSpec,
386 networkTags: news.networkTags,
387 idleShutdownConfig: news.idleShutdownConfig,
388 shieldedVmConfig: news.shieldedVmConfig,
389 reservationAffinity: news.reservationAffinity,
390 },
391 })
392 .pipe(Effect.catchTag("Conflict", () => Effect.undefined));
393 if (created !== undefined) {
394 yield* waitForOperation(created, { alreadyExistsOk: true });
395 }
396 const createdName = resourceNameFromOperation(created ?? {}) ?? output?.name ?? name;
397 current = yield* waitUntilExists(createdName);
398 }
399
400 if (current === undefined) {
401 return yield* new NotebookRuntimeTemplateNotResolved({ resourceName: name });
402 }
403
404 const observedName = current.name ?? name;
405 // Only display name and software config are updatable; label and
406 // description changes replace the template (see `diff`).
407 const displayChanged = (current.displayName ?? "") !== displayName;
408 const softwareChanged =
409 news.softwareConfig !== undefined &&
410 !jsonEqual(current.softwareConfig, news.softwareConfig);
411
412 if (displayChanged || softwareChanged) {
413 const updateMask = [
414 displayChanged ? "display_name" : undefined,
415 softwareChanged ? "software_config" : undefined,
416 ].filter((field): field is string => field !== undefined);
417 const patched = yield* aiplatform.patchProjectsLocationsNotebookRuntimeTemplates({
418 name: observedName,
419 updateMask: updateMask.join(","),
420 body: {
421 name: observedName,
422 displayName,
423 softwareConfig: news.softwareConfig,
424 etag: current.etag,
425 },
426 });
427 current = patched ?? current;
428 }
429
430 return toAttrs(current, env.project);
431 }),
432
433 delete: Effect.fn(function* ({ output }) {
434 const operation = yield* aiplatform
435 .deleteProjectsLocationsNotebookRuntimeTemplates({
436 name: output.name,
437 })
438 .pipe(Effect.catchTag("NotFound", () => Effect.undefined));
439 if (operation !== undefined) {
440 yield* waitForOperation(operation, { notFoundOk: true });
441 }
442 yield* waitUntilGone(output.name);
443 }),
444 });