@baochunli/flakes 0.0.3 → 0.0.5

package/dist/node_modules/@flakes/control-plane/dist/managed-sandbox-provisioner.d.ts

@@ -0,0 +1,71 @@
+import { type FliesSandboxConfig, type ManagedSandboxPoolConfig } from "@flies/core";
+import type { DurableStore, StoreManagedSandboxInstance, StoreTask } from "@flies/store";
+import type { SandboxStreamRegistry } from "./sandbox-stream-registry.js";
+/** Input handed to a provider-specific managed sandbox starter. */
+export interface StartManagedSandboxInput {
+    pool: ManagedSandboxPoolConfig;
+    instance: StoreManagedSandboxInstance;
+    sandboxConfig: FliesSandboxConfig;
+}
+/** Provider result after launching a managed sandbox daemon environment. */
+export type StartManagedSandboxResult = {
+    status: "started";
+    providerResourceId?: string | undefined;
+} | {
+    status: "ambiguous";
+    providerResourceId?: string | undefined;
+    lastError?: string | undefined;
+};
+/** Narrow provider boundary owned by control-plane provisioning. */
+export interface ManagedSandboxStarter {
+    start(input: StartManagedSandboxInput): Promise<StartManagedSandboxResult>;
+}
+export interface ManagedSandboxProvisionerOptions {
+    store: DurableStore;
+    /** Live stream boundary used to distinguish truly schedulable live slots from durable rows. */
+    registry?: SandboxStreamRegistry | undefined;
+    pools: readonly ManagedSandboxPoolConfig[];
+    starter: ManagedSandboxStarter;
+    cleaner?: ManagedSandboxCleaner | undefined;
+    pollIntervalMs: number;
+    queuedTaskLimit?: number | undefined;
+    /**
+     * Registers a per-instance sandbox-pinned credential so the minted token is
+     * accepted by sandbox-pinned routes (e.g. pi-session). Without it the instance
+     * would have no pinned sandbox credential and those routes reject with 403.
+     */
+    registerSandboxCredential?: ((credential: {
+        sandboxId: string;
+        token: string;
+    }) => void) | undefined;
+}
+/** Input handed to a provider-specific managed sandbox cleanup action. */
+export interface StopManagedSandboxInput {
+    instance: StoreManagedSandboxInstance;
+    providerResourceId: string;
+}
+/** Narrow provider boundary used for managed sandbox cleanup. */
+export interface ManagedSandboxCleaner {
+    stop(input: StopManagedSandboxInput): Promise<void>;
+}
+export interface StopManagedSandboxInstancesInput {
+    store: DurableStore;
+    cleaner: ManagedSandboxCleaner;
+}
+/** Periodically starts managed sandbox instances to satisfy queued compatible demand. */
+export declare class ManagedSandboxProvisioner {
+    #private;
+    constructor(options: ManagedSandboxProvisionerOptions);
+    /** Runs one provisioning pass. At most one instance is started per pool. */
+    tick(): Promise<void>;
+    /** Starts background provisioning; repeated calls are no-ops. */
+    start(): void;
+    /** Stops background provisioning if active. */
+    stop(): void;
+}
+/** Best-effort stop for every nonterminal managed instance. */
+export declare function stopManagedSandboxInstances(input: StopManagedSandboxInstancesInput): Promise<void>;
+export declare function createManagedSandboxConfig(pool: ManagedSandboxPoolConfig, sandboxId: string, token: string): FliesSandboxConfig;
+/** MVP pre-launch match: only target adapter and required capabilities. */
+export declare function isPreLaunchCompatible(task: StoreTask, pool: ManagedSandboxPoolConfig): boolean;
+//# sourceMappingURL=managed-sandbox-provisioner.d.ts.map

package/dist/node_modules/@flakes/control-plane/dist/managed-sandbox-provisioner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"managed-sandbox-provisioner.d.ts","sourceRoot":"","sources":["../src/managed-sandbox-provisioner.ts"],"names":[],"mappings":"AACA,OAAO,EAEL,KAAK,kBAAkB,EACvB,KAAK,wBAAwB,EAC9B,MAAM,aAAa,CAAC;AACrB,OAAO,KAAK,EACV,YAAY,EAEZ,2BAA2B,EAC3B,SAAS,EACV,MAAM,cAAc,CAAC;AACtB,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,8BAA8B,CAAC;AAG1E,mEAAmE;AACnE,MAAM,WAAW,wBAAwB;IACvC,IAAI,EAAE,wBAAwB,CAAC;IAC/B,QAAQ,EAAE,2BAA2B,CAAC;IACtC,aAAa,EAAE,kBAAkB,CAAC;CACnC;AAED,4EAA4E;AAC5E,MAAM,MAAM,yBAAyB,GACjC;IACE,MAAM,EAAE,SAAS,CAAC;IAClB,kBAAkB,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CACzC,GACD;IACE,MAAM,EAAE,WAAW,CAAC;IACpB,kBAAkB,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACxC,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAChC,CAAC;AAEN,oEAAoE;AACpE,MAAM,WAAW,qBAAqB;IACpC,KAAK,CAAC,KAAK,EAAE,wBAAwB,GAAG,OAAO,CAAC,yBAAyB,CAAC,CAAC;CAC5E;AAED,MAAM,WAAW,gCAAgC;IAC/C,KAAK,EAAE,YAAY,CAAC;IACpB,+FAA+F;IAC/F,QAAQ,CAAC,EAAE,qBAAqB,GAAG,SAAS,CAAC;IAC7C,KAAK,EAAE,SAAS,wBAAwB,EAAE,CAAC;IAC3C,OAAO,EAAE,qBAAqB,CAAC;IAC/B,OAAO,CAAC,EAAE,qBAAqB,GAAG,SAAS,CAAC;IAC5C,cAAc,EAAE,MAAM,CAAC;IACvB,eAAe,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACrC;;;;OAIG;IACH,yBAAyB,CAAC,EACtB,CAAC,CAAC,UAAU,EAAE;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,KAAK,IAAI,CAAC,GAC5D,SAAS,CAAC;CACf;AAED,0EAA0E;AAC1E,MAAM,WAAW,uBAAuB;IACtC,QAAQ,EAAE,2BAA2B,CAAC;IACtC,kBAAkB,EAAE,MAAM,CAAC;CAC5B;AAED,iEAAiE;AACjE,MAAM,WAAW,qBAAqB;IACpC,IAAI,CAAC,KAAK,EAAE,uBAAuB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACrD;AAED,MAAM,WAAW,gCAAgC;IAC/C,KAAK,EAAE,YAAY,CAAC;IACpB,OAAO,EAAE,qBAAqB,CAAC;CAChC;AAoBD,yFAAyF;AACzF,qBAAa,yBAAyB;;gBAcxB,OAAO,EAAE,gCAAgC;IAWrD,4EAA4E;IAC5E,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAWrB,iEAAiE;IACjE,KAAK;IAUL,+CAA+C;IAC/C,IAAI;CA0KL;AAED,+DAA+D;AAC/D,wBAAsB,2BAA2B,CAC/C,KAAK,EAAE,gCAAgC,GACtC,OAAO,CAAC,IAAI,CAAC,CAcf;AAoBD,wBAAgB,0BAA0B,CACxC,IAAI,EAAE,wBAAwB,EAC9B,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,MAAM,GACZ,kBAAkB,CAMpB;AASD,2EAA2E;AAC3E,wBAAgB,qBAAqB,CACnC,IAAI,EAAE,SAAS,EACf,IAAI,EAAE,wBAAwB,WAW/B"}

package/dist/node_modules/@flakes/control-plane/dist/managed-sandbox-provisioner.js

@@ -0,0 +1,243 @@
+import { randomBytes } from "node:crypto";
+import { createManagedSandboxConfig as createCoreManagedSandboxConfig, } from "@flies/core";
+import { toError } from "./utils.js";
+const defaultQueuedTaskLimit = 100;
+const capacityStatuses = [
+    "starting",
+    "live",
+    "draining",
+];
+/** Periodically starts managed sandbox instances to satisfy queued compatible demand. */
+export class ManagedSandboxProvisioner {
+    #timer;
+    #tickInFlight;
+    #store;
+    #registry;
+    #pools;
+    #starter;
+    #cleaner;
+    #pollIntervalMs;
+    #queuedTaskLimit;
+    #registerSandboxCredential;
+    constructor(options) {
+        this.#store = options.store;
+        this.#registry = options.registry;
+        this.#pools = options.pools;
+        this.#starter = options.starter;
+        this.#cleaner = options.cleaner;
+        this.#pollIntervalMs = options.pollIntervalMs;
+        this.#queuedTaskLimit = options.queuedTaskLimit ?? defaultQueuedTaskLimit;
+        this.#registerSandboxCredential = options.registerSandboxCredential;
+    }
+    /** Runs one provisioning pass. At most one instance is started per pool. */
+    tick() {
+        if (this.#tickInFlight) {
+            return this.#tickInFlight;
+        }
+        this.#tickInFlight = this.#runTick().finally(() => {
+            this.#tickInFlight = undefined;
+        });
+        return this.#tickInFlight;
+    }
+    /** Starts background provisioning; repeated calls are no-ops. */
+    start() {
+        if (this.#timer) {
+            return;
+        }
+        this.#timer = globalThis.setInterval(() => {
+            void this.tick().catch(() => undefined);
+        }, this.#pollIntervalMs);
+    }
+    /** Stops background provisioning if active. */
+    stop() {
+        if (!this.#timer) {
+            return;
+        }
+        globalThis.clearInterval(this.#timer);
+        this.#timer = undefined;
+    }
+    async #runTick() {
+        const tasks = await this.#store.listQueuedTasks({
+            limit: this.#queuedTaskLimit,
+        });
+        for (const pool of this.#pools) {
+            const compatibleQueuedDemand = countCompatibleQueuedDemand(tasks, pool);
+            const capacity = await this.#poolCapacity(pool);
+            if (compatibleQueuedDemand === 0) {
+                continue;
+            }
+            if (compatibleQueuedDemand <=
+                capacity.liveAvailableSlots + capacity.startingSlots) {
+                continue;
+            }
+            if (capacity.activeInstances >= pool.maxInstances) {
+                continue;
+            }
+            await this.#startInstance(pool);
+        }
+    }
+    async #poolCapacity(pool) {
+        const instances = await this.#store.listManagedSandboxInstances({
+            poolId: pool.poolId,
+            statuses: capacityStatuses,
+        });
+        let liveAvailableSlots = 0;
+        let startingSlots = 0;
+        let activeInstances = 0;
+        for (const instance of instances) {
+            if (instance.status === "starting") {
+                activeInstances += 1;
+                startingSlots += pool.maxConcurrency;
+                continue;
+            }
+            if (instance.status === "draining") {
+                activeInstances += 1;
+                continue;
+            }
+            const liveCapacity = await this.#liveCapacity(instance);
+            if (liveCapacity.activeInstance) {
+                activeInstances += 1;
+            }
+            liveAvailableSlots += liveCapacity.availableSlots;
+        }
+        return {
+            liveAvailableSlots,
+            startingSlots,
+            activeInstances,
+        };
+    }
+    async #liveCapacity(instance) {
+        const sandbox = await this.#store.getSandbox(instance.sandboxId);
+        if (!sandbox || sandbox.status === "offline") {
+            await this.#store.markManagedSandboxInstanceFailed({
+                instanceId: instance.instanceId,
+                lastError: sandbox
+                    ? "managed sandbox live instance is offline"
+                    : "managed sandbox live instance has no sandbox record",
+            });
+            return { activeInstance: false, availableSlots: 0 };
+        }
+        if (sandbox.status !== "active" ||
+            sandbox.descriptor?.draining === true ||
+            (this.#registry && !this.#registry.latest(instance.sandboxId))) {
+            return { activeInstance: true, availableSlots: 0 };
+        }
+        const load = await this.#store.getSandboxLoad(instance.sandboxId);
+        return { activeInstance: true, availableSlots: load.availableCapacity };
+    }
+    async #startInstance(pool) {
+        // Mint a credential pinned to this instance's sandboxId so sandbox-pinned
+        // routes accept the daemon's token.
+        const sandboxToken = randomBytes(32).toString("hex");
+        const instance = await this.#store.createManagedSandboxInstance({
+            poolId: pool.poolId,
+            sandboxToken,
+        });
+        this.#registerSandboxCredential?.({
+            sandboxId: instance.sandboxId,
+            token: sandboxToken,
+        });
+        const sandboxConfig = createManagedSandboxConfig(pool, instance.sandboxId, sandboxToken);
+        try {
+            const result = await this.#starter.start({
+                pool,
+                instance,
+                sandboxConfig,
+            });
+            if (result.providerResourceId) {
+                await this.#store.setManagedSandboxProviderResource({
+                    instanceId: instance.instanceId,
+                    providerResourceId: result.providerResourceId,
+                });
+            }
+            if (result.status === "ambiguous") {
+                const lastError = result.lastError ??
+                    "managed sandbox starter returned ambiguous result";
+                if (result.providerResourceId && this.#cleaner) {
+                    try {
+                        await this.#cleaner.stop({
+                            instance: {
+                                ...instance,
+                                providerResourceId: result.providerResourceId,
+                            },
+                            providerResourceId: result.providerResourceId,
+                        });
+                        await this.#store.markManagedSandboxInstanceStopped({
+                            instanceId: instance.instanceId,
+                            lastError,
+                        });
+                        return;
+                    }
+                    catch (error) {
+                        await this.#store.markManagedSandboxInstanceFailed({
+                            instanceId: instance.instanceId,
+                            lastError: `${lastError}; cleanup failed: ${toError(error).message}`,
+                        });
+                        return;
+                    }
+                }
+                await this.#store.markManagedSandboxInstanceFailed({
+                    instanceId: instance.instanceId,
+                    lastError,
+                });
+                return;
+            }
+        }
+        catch (error) {
+            const lastError = toError(error).message;
+            await this.#store.markManagedSandboxInstanceFailed({
+                instanceId: instance.instanceId,
+                lastError,
+            });
+        }
+    }
+}
+/** Best-effort stop for every nonterminal managed instance. */
+export async function stopManagedSandboxInstances(input) {
+    const instances = await input.store.listManagedSandboxInstances({
+        statuses: capacityStatuses,
+    });
+    for (const instance of instances) {
+        try {
+            await stopManagedSandboxInstance({ ...input, instance });
+        }
+        catch (error) {
+            await input.store.markManagedSandboxInstanceFailed({
+                instanceId: instance.instanceId,
+                lastError: `managed sandbox cleanup failed: ${toError(error).message}`,
+            });
+        }
+    }
+}
+async function stopManagedSandboxInstance(input) {
+    if (!input.instance.providerResourceId) {
+        return;
+    }
+    await input.cleaner.stop({
+        instance: input.instance,
+        providerResourceId: input.instance.providerResourceId,
+    });
+    await input.store.markManagedSandboxInstanceStopped({
+        instanceId: input.instance.instanceId,
+    });
+}
+export function createManagedSandboxConfig(pool, sandboxId, token) {
+    return createCoreManagedSandboxConfig({
+        pool,
+        sandboxId,
+        token,
+    });
+}
+function countCompatibleQueuedDemand(tasks, pool) {
+    return tasks.filter((task) => isPreLaunchCompatible(task, pool)).length;
+}
+/** MVP pre-launch match: only target adapter and required capabilities. */
+export function isPreLaunchCompatible(task, pool) {
+    const targetAdapter = task.target?.adapter;
+    if (targetAdapter && targetAdapter !== pool.adapter) {
+        return false;
+    }
+    const poolCapabilities = new Set([pool.adapter]);
+    return task.requiredCapabilities.every((capability) => poolCapabilities.has(capability));
+}
+//# sourceMappingURL=managed-sandbox-provisioner.js.map

package/dist/node_modules/@flakes/control-plane/dist/managed-sandbox-provisioner.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"managed-sandbox-provisioner.js","sourceRoot":"","sources":["../src/managed-sandbox-provisioner.ts"],"names":[],"mappings":"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"}

package/dist/node_modules/@flakes/control-plane/dist/routes/hosts.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"hosts.d.ts","sourceRoot":"","sources":["../../src/routes/hosts.ts"],"names":[],"mappings":"AAeA,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,cAAc,CAAC;AAE7D,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,wBAAwB,QAKnE"}
+{"version":3,"file":"hosts.d.ts","sourceRoot":"","sources":["../../src/routes/hosts.ts"],"names":[],"mappings":"AAiBA,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,cAAc,CAAC;AAE7D,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,wBAAwB,QAMnE"}

package/dist/node_modules/@flakes/control-plane/dist/routes/hosts.js

@@ -1,3 +1,4 @@
+import { ProjectKeySchema } from "@flakes/core";
 import { HOST_PROVISIONING_QUOTAS, HostProvisioningQuotaError, } from "@flakes/store";
 import { mustUserAuth } from "../auth.js";
 import { handleHostStream } from "../host-stream.js";
@@ -7,6 +8,7 @@ export function registerHostRoutes(context) {
     registerHostStreamRoutes(context);
     registerHostCrudRoutes(context);
     registerHostPoolRoutes(context);
+    registerHostProjectRoutes(context);
     registerHostCredentialRoutes(context);
 }
 function registerHostStreamRoutes(context) {
@@ -171,6 +173,112 @@ function registerHostPoolRoutes(context) {
         return pool ? reply.send(hostPoolDto(pool)) : notFound(reply);
     });
 }
+function registerHostProjectRoutes(context) {
+    const { app, options, requireScope } = context;
+    app.put("/v1/hosts/:hostId/project-workspace-root", { preValidation: requireScope("client") }, async (request, reply) => {
+        const auth = mustUserAuth(request);
+        const body = requestBody(request, reply);
+        if (!body) {
+            return;
+        }
+        const projectWorkspaceRoot = absoluteHostPath(body.path, "path", reply);
+        if (!projectWorkspaceRoot) {
+            return;
+        }
+        const host = await options.store.setHostProjectWorkspaceRoot({
+            ownerKey: auth.ownerKey,
+            hostId: request.params.hostId,
+            projectWorkspaceRoot,
+        });
+        return host
+            ? reply.send(hostProjectWorkspaceRootDto(host))
+            : notFound(reply);
+    });
+    app.put("/v1/hosts/:hostId/project-bindings/:projectKey", { preValidation: requireScope("client") }, async (request, reply) => {
+        const auth = mustUserAuth(request);
+        const projectKey = routeProjectKey(request.params.projectKey, reply);
+        if (!projectKey) {
+            return;
+        }
+        const body = requestBody(request, reply);
+        if (!body) {
+            return;
+        }
+        const poolKeys = poolKeysField(body.poolKeys, "poolKeys", reply);
+        if (!poolKeys) {
+            return;
+        }
+        const host = await options.store.getHost({
+            ownerKey: auth.ownerKey,
+            hostId: request.params.hostId,
+        });
+        if (!host) {
+            return notFound(reply);
+        }
+        if (!host.projectWorkspaceRoot) {
+            return hostProjectWorkspaceRootRequired(reply);
+        }
+        const projectWorkspaceRoot = host.projectWorkspaceRoot;
+        const project = await options.store.getProject({
+            ownerKey: auth.ownerKey,
+            projectKey,
+        });
+        if (!project) {
+            return projectNotFound(reply);
+        }
+        if (project.status !== "active") {
+            return reply.code(409).send({
+                error: "project_archived",
+                message: "project is archived",
+                projectKey,
+            });
+        }
+        const existingPools = await options.store.listHostPools({
+            ownerKey: auth.ownerKey,
+            hostId: request.params.hostId,
+        });
+        const existingPoolKeys = new Set(existingPools.map((pool) => pool.poolKey));
+        const unknownPoolKeys = poolKeys.filter((poolKey) => !existingPoolKeys.has(poolKey));
+        if (unknownPoolKeys.length > 0) {
+            return reply.code(400).send({
+                error: "unknown_host_pool_keys",
+                message: "one or more pool keys are not configured for this host",
+                poolKeys: unknownPoolKeys,
+            });
+        }
+        const binding = await handleHostQuotaError(reply, () => options.store.upsertHostProjectBinding({
+            ownerKey: auth.ownerKey,
+            hostId: request.params.hostId,
+            projectKey,
+            allowedPoolKeys: poolKeys,
+        }));
+        if (!binding) {
+            return;
+        }
+        return reply.send(hostProjectBindingDto(binding, projectWorkspaceRoot));
+    });
+    app.get("/v1/hosts/:hostId/project-bindings", { preValidation: requireScope("client") }, async (request, reply) => {
+        const auth = mustUserAuth(request);
+        const host = await options.store.getHost({
+            ownerKey: auth.ownerKey,
+            hostId: request.params.hostId,
+        });
+        if (!host) {
+            return notFound(reply);
+        }
+        if (!host.projectWorkspaceRoot) {
+            return hostProjectWorkspaceRootRequired(reply);
+        }
+        const projectWorkspaceRoot = host.projectWorkspaceRoot;
+        const bindings = await options.store.listHostProjectBindings({
+            ownerKey: auth.ownerKey,
+            hostId: request.params.hostId,
+        });
+        return reply.send({
+            bindings: bindings.map((binding) => hostProjectBindingDto(binding, projectWorkspaceRoot)),
+        });
+    });
+}
 function registerHostCredentialRoutes(context) {
     const { app, options, requireScope } = context;
     app.post("/v1/hosts/setup", { preValidation: requireScope("client") }, async (request, reply) => {
@@ -376,6 +484,85 @@ function requiredBodyString(value, field, reply) {
     }
     return value;
 }
+function absoluteHostPath(value, field, reply) {
+    if (typeof value !== "string") {
+        reply.code(400).send({
+            error: "invalid_request",
+            message: `${field} must be an absolute path`,
+            field,
+        });
+        return undefined;
+    }
+    const trimmed = value.trim();
+    if (!isAbsoluteHostPath(trimmed)) {
+        reply.code(400).send({
+            error: "invalid_request",
+            message: `${field} must be an absolute path`,
+            field,
+        });
+        return undefined;
+    }
+    return trimmed;
+}
+function isAbsoluteHostPath(value) {
+    return (value.startsWith("/") ||
+        /^[A-Za-z]:[\\/]/.test(value) ||
+        value.startsWith("\\\\"));
+}
+function routeProjectKey(value, reply) {
+    const parsed = ProjectKeySchema.safeParse(value);
+    if (!parsed.success) {
+        reply.code(400).send({
+            error: "invalid_request",
+            message: "projectKey is invalid",
+            field: "projectKey",
+        });
+        return undefined;
+    }
+    return parsed.data;
+}
+function poolKeysField(value, field, reply) {
+    if (!Array.isArray(value)) {
+        reply.code(400).send({
+            error: "invalid_request",
+            message: `${field} must be a non-empty array of strings`,
+            field,
+        });
+        return undefined;
+    }
+    const parsed = value.map((item) => poolKeyString(item));
+    if (parsed.length === 0 || !parsed.every(isString)) {
+        reply.code(400).send({
+            error: "invalid_request",
+            message: `${field} must be a non-empty array of strings`,
+            field,
+        });
+        return undefined;
+    }
+    return [...new Set(parsed)];
+}
+function poolKeyString(value) {
+    if (typeof value !== "string") {
+        return undefined;
+    }
+    const trimmed = value.trim();
+    return trimmed.length > 0 ? trimmed : undefined;
+}
+function isString(value) {
+    return value !== undefined;
+}
+function projectNotFound(reply) {
+    return reply.code(404).send({
+        error: "project_not_found",
+        message: "project not found",
+    });
+}
+function hostProjectWorkspaceRootRequired(reply) {
+    return reply.code(409).send({
+        error: "host_project_workspace_root_required",
+        message: "host project workspace root is not configured",
+    });
+}
 const invalidMetadata = Symbol("invalidMetadata");
 const allowedHostUpdateFields = new Set(["name", "metadata"]);
 const forbiddenHostUserMetadataKeys = new Set([
@@ -497,6 +684,7 @@ function hostDto(host) {
         hostId: host.hostId,
         name: host.name,
         status: host.status,
+        projectWorkspaceRoot: host.projectWorkspaceRoot,
         lastSeenAt: host.lastSeenAt,
         platform: host.platform,
         arch: host.arch,
@@ -506,6 +694,37 @@ function hostDto(host) {
         updatedAt: host.updatedAt,
     };
 }
+function hostProjectWorkspaceRootDto(host) {
+    return {
+        hostId: host.hostId,
+        projectWorkspaceRoot: host.projectWorkspaceRoot,
+        updatedAt: host.updatedAt,
+    };
+}
+function hostProjectBindingDto(binding, projectWorkspaceRoot) {
+    return {
+        hostProjectBindingId: binding.bindingId,
+        hostId: binding.hostId,
+        projectId: binding.projectId,
+        projectKey: binding.projectKey,
+        workspacePath: hostProjectWorkspacePath(projectWorkspaceRoot, binding.projectKey),
+        poolKeys: binding.allowedPoolKeys,
+        availability: binding.availability,
+        lastValidatedAt: binding.lastValidatedAt,
+        validationReason: binding.unavailableReason,
+        createdAt: binding.createdAt,
+        updatedAt: binding.updatedAt,
+    };
+}
+function hostProjectWorkspacePath(projectWorkspaceRoot, projectKey) {
+    const separator = projectWorkspaceRoot.includes("\\") && !projectWorkspaceRoot.includes("/")
+        ? "\\"
+        : "/";
+    return projectWorkspaceRoot.endsWith("/") ||
+        projectWorkspaceRoot.endsWith("\\")
+        ? `${projectWorkspaceRoot}${projectKey}`
+        : `${projectWorkspaceRoot}${separator}${projectKey}`;
+}
 function hostPoolDto(pool) {
     return {
         hostPoolId: pool.hostPoolId,