@dbx-tools/appkit-lakebox 0.0.0-stage → 0.9.131

package/src/services.ts

@@ -0,0 +1,239 @@
+import {
+  createLakeboxServiceRequestSchema,
+  lakeboxServiceKindSchema,
+  lakeboxServiceStateSchema,
+  type CreateLakeboxServiceRequest,
+  type LakeboxBuiltInServiceName,
+  type LakeboxService,
+  type LakeboxUser,
+} from "@dbx-tools/shared-lakebox";
+import { lakeboxServicePath } from "@dbx-tools/shared-lakebox/client";
+import { z } from "zod";
+import { desktopEnvironment, desktopHtmlHead, desktopOpenUrl } from "./desktop.ts";
+import { LAKEBOX_RUNTIME_ROOT, lakeboxServicePort } from "./user.ts";
+
+const TTYD_CLIENT_OPTIONS = [
+  "term=xterm-256color",
+  "rendererType=webgl",
+  "cursorStyle=bar",
+  "copyOnSelect=true",
+  "rightClickSelectsWord=true",
+  "disableLeaveAlert=true",
+  "disableResizeOverlay=true",
+];
+
+export const LakeboxControllerDefinitionSchema = z
+  .object({
+    name: z.string().describe("Service name."),
+    kind: lakeboxServiceKindSchema,
+    image: z.string().optional().describe("OCI image for image services."),
+    pull: z.enum(["missing", "always"]).default("missing").describe("Image pull policy."),
+    command: z
+      .array(z.string())
+      .optional()
+      .describe("Argv; omitted to use the image entrypoint and command."),
+    env: z
+      .record(z.string(), z.string())
+      .describe("Container environment, including injected values."),
+    workingDirectory: z.string().optional().describe("Container working directory."),
+    mounts: z
+      .array(
+        z
+          .object({
+            source: z
+              .string()
+              .startsWith("/")
+              .describe("Absolute host path beneath the user's home."),
+            target: z.string().startsWith("/").describe("Container path."),
+            readOnly: z.boolean().describe("Read-only bind."),
+          })
+          .strict(),
+      )
+      .describe("Bind mounts."),
+    port: z.number().int().describe("Derived loopback port."),
+    readiness: z.enum(["tcp", "none"]).describe("Readiness check."),
+    readySeconds: z.number().int().positive().describe("Maximum readiness wait."),
+    autostart: z.boolean().describe("Whether the service restarts when the Lakebox starts."),
+    route: z.boolean().describe("Whether AppKit routes the service."),
+    stripPrefix: z.boolean().describe("Whether the route prefix is removed before forwarding."),
+    openPath: z.string().optional().describe("Entry path appended to the route."),
+  })
+  .strict()
+  .describe("Service definition persisted in the user's Lakebox home and read by the controller.");
+/** Service definition persisted in the user's Lakebox home. */
+export type LakeboxControllerDefinition = z.output<typeof LakeboxControllerDefinitionSchema>;
+
+export const LakeboxControllerServiceSchema = z
+  .object({
+    name: z.string(),
+    state: lakeboxServiceStateSchema,
+    definition: LakeboxControllerDefinitionSchema,
+    error: z.string().optional(),
+    log: z.string().optional(),
+  })
+  .passthrough()
+  .describe("One service as reported by the remote controller.");
+/** One service as reported by the remote controller. */
+export type LakeboxControllerService = z.infer<typeof LakeboxControllerServiceSchema>;
+
+/** Routing behavior derived from a saved definition. */
+export interface LakeboxServiceRoute {
+  port: number;
+  stripPrefix: boolean;
+  redirectToSlash: boolean;
+  htmlHead?: string;
+}
+
+/** Builds the package-owned definition for a built-in service. */
+export function builtInDefinition(
+  name: LakeboxBuiltInServiceName,
+  user: LakeboxUser,
+): LakeboxControllerDefinition {
+  const port = lakeboxServicePort(user.hash, name);
+  const common = {
+    name,
+    kind: name,
+    pull: "missing" as const,
+    mounts: [],
+    port,
+    readiness: "tcp" as const,
+    autostart: false,
+    route: true,
+    stripPrefix: true,
+  };
+  if (name === "terminal") {
+    return {
+      ...common,
+      readySeconds: 60,
+      env: injectedEnvironment(user, name, port),
+      command: [
+        `${LAKEBOX_RUNTIME_ROOT}/bin/ttyd`,
+        "--interface",
+        "127.0.0.1",
+        "--port",
+        String(port),
+        "--writable",
+        ...TTYD_CLIENT_OPTIONS.flatMap((option) => ["--client-option", option]),
+        "/bin/bash",
+        "-l",
+      ],
+    };
+  }
+  return {
+    ...common,
+    readySeconds: 180,
+    env: { ...desktopEnvironment(), ...injectedEnvironment(user, name, port) },
+    command: ["/bin/sh", `${LAKEBOX_RUNTIME_ROOT}/bin/desktop-session`],
+  };
+}
+
+/**
+ * Validates an agent or REST service request and resolves it to a persisted
+ * definition with injected variables and home-relative mounts.
+ */
+export function imageDefinition(
+  input: CreateLakeboxServiceRequest,
+  user: LakeboxUser,
+): LakeboxControllerDefinition {
+  const request = createLakeboxServiceRequestSchema.parse(input);
+  const port = lakeboxServicePort(user.hash, request.name);
+  return {
+    name: request.name,
+    kind: "image",
+    image: request.image,
+    pull: request.pull,
+    ...(request.command ? { command: request.command } : {}),
+    env: { ...request.env, ...injectedEnvironment(user, request.name, port, request.route) },
+    ...(request.workingDirectory ? { workingDirectory: request.workingDirectory } : {}),
+    mounts: request.mounts.map((mount) => ({
+      source: `${user.home}/${mount.source.replace(/^\.\/+|\/+$/g, "")}`,
+      target: mount.target,
+      readOnly: mount.readOnly,
+    })),
+    port,
+    readiness: request.route ? "tcp" : "none",
+    readySeconds: 300,
+    autostart: true,
+    route: request.route,
+    stripPrefix: request.stripPrefix,
+    ...(request.openPath ? { openPath: request.openPath.replace(/^\/+/, "") } : {}),
+  };
+}
+
+/** Returns route behavior for a saved definition. */
+export function serviceRoute(definition: LakeboxControllerDefinition): LakeboxServiceRoute {
+  return {
+    port: definition.port,
+    stripPrefix: definition.stripPrefix,
+    redirectToSlash: true,
+    ...(definition.kind === "desktop" ? { htmlHead: desktopHtmlHead } : {}),
+  };
+}
+
+/** Maps a controller report to the shared service shape. */
+export function toLakeboxService(
+  service: LakeboxControllerService,
+  user: LakeboxUser,
+  routePrefix: string,
+): LakeboxService {
+  const { definition } = service;
+  const path = lakeboxServicePath(routePrefix, user.hash, definition.name);
+  return {
+    name: definition.name,
+    kind: definition.kind,
+    ...(definition.image ? { image: definition.image } : {}),
+    ...(definition.openPath ? { openPath: definition.openPath } : {}),
+    state: service.state,
+    port: definition.port,
+    route: definition.route,
+    path,
+    ...(definition.route ? { openUrl: openUrl(definition, path) } : {}),
+    ...(service.error ? { error: service.error } : {}),
+    ...(service.log !== undefined ? { log: service.log } : {}),
+  };
+}
+
+/** Resolve a routed service path against the browser app origin for agent output. */
+export function withServiceOrigin(service: LakeboxService, origin?: string): LakeboxService {
+  if (!service.openUrl || !origin) return service;
+  try {
+    const base = new URL(origin);
+    if (base.protocol !== "http:" && base.protocol !== "https:") return service;
+    return { ...service, openUrl: new URL(service.openUrl, base).href };
+  } catch {
+    return service;
+  }
+}
+
+/** Returns the stopped placeholder for a built-in service that has never started. */
+export function idleBuiltInService(
+  name: LakeboxBuiltInServiceName,
+  user: LakeboxUser,
+  routePrefix: string,
+): LakeboxService {
+  return toLakeboxService(
+    { name, state: "stopped", definition: builtInDefinition(name, user) },
+    user,
+    routePrefix,
+  );
+}
+
+function openUrl(definition: LakeboxControllerDefinition, path: string): string {
+  if (definition.kind === "desktop") return desktopOpenUrl(path);
+  return `${path}/${definition.openPath ?? ""}`;
+}
+
+function injectedEnvironment(
+  user: LakeboxUser,
+  name: string,
+  port: number,
+  route = true,
+): Record<string, string> {
+  const value = String(port);
+  return {
+    SERVICE_NAME: name,
+    SERVICE_PATH: route ? `${user.routePrefix}/${name}` : "",
+    SERVICE_PORT: value,
+    PORT: value,
+  };
+}

package/src/skills.ts

@@ -0,0 +1,23 @@
+import { existsSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import type { LocalSkillDirectoryMount } from "@dbx-tools/appkit-mastra";
+
+/** Default agent-workspace path for packaged Lakebox service recipes. */
+export const LAKEBOX_SKILLS_MOUNT = "/.dbx-tools/skills";
+
+/** Returns the packaged Lakebox recipe tree as a Mastra local skill mount. */
+export function lakeboxSkillMounts(): LocalSkillDirectoryMount[] {
+  return [{ root: lakeboxSkillsRoot(), mountPath: LAKEBOX_SKILLS_MOUNT }];
+}
+
+function lakeboxSkillsRoot(): string {
+  const moduleDirectory = dirname(fileURLToPath(import.meta.url));
+  const candidates = [
+    resolve(moduleDirectory, "../skills"),
+    resolve(moduleDirectory, "../../skills"),
+  ];
+  const root = candidates.find((candidate) => existsSync(candidate));
+  if (!root) throw new Error("Packaged Lakebox skills are unavailable");
+  return root;
+}

package/src/user.ts

@@ -0,0 +1,88 @@
+/**
+ * Deterministic Lakebox user and service-port derivation.
+ *
+ * One FNV-1a hash of the authenticated identity is the only routing key. It
+ * selects the Linux account, UID, persistent home, AppKit route segment, and,
+ * with a service name, the loopback service port. Nothing here is persisted:
+ * every caller recomputes the same values, and collisions fail closed where
+ * they are observed.
+ *
+ * @module
+ */
+
+import { hash } from "@dbx-tools/shared-core";
+import type { LakeboxUser } from "@dbx-tools/shared-lakebox";
+
+/** Platform account that owns the persistent volume and the SSH session. */
+export const LAKEBOX_AGENT_USER = "sandbox-agent";
+/** Persistent home mounted by the platform. Only this path survives a restart. */
+export const LAKEBOX_AGENT_HOME = `/home/${LAKEBOX_AGENT_USER}`;
+/** Root of package-owned persistent state. */
+export const LAKEBOX_STATE_ROOT = `${LAKEBOX_AGENT_HOME}/.dbx-tools`;
+/** Persistent backing directories for Lakebox user homes. */
+export const LAKEBOX_USERS_ROOT = `${LAKEBOX_STATE_ROOT}/users`;
+/** Shared read-only runtime binaries, such as the container bundle and ttyd. */
+export const LAKEBOX_RUNTIME_ROOT = `${LAKEBOX_STATE_ROOT}/runtime`;
+/** Per-boot runtime state root; reset with the root filesystem. */
+export const LAKEBOX_RUN_ROOT = "/run/lakebox";
+
+/** First derived Linux UID. The persistent idmapped volume stores UIDs below 65536. */
+export const LAKEBOX_UID_MIN = 20_000;
+/** Number of derivable UIDs. */
+export const LAKEBOX_UID_COUNT = 40_000;
+/** First derived service port. Platform listeners stay below this value. */
+export const LAKEBOX_PORT_MIN = 20_000;
+/** Number of derivable service ports; the kernel ephemeral range starts at 32768. */
+export const LAKEBOX_PORT_COUNT = 12_000;
+
+const USER_PREFIX = "lakebox-";
+const HASH_ALPHABET = "0123456789abcdefghijklmnopqrstuv";
+
+/** Normalizes an authenticated identity before hashing. */
+export function normalizeLakeboxIdentity(identity: string): string {
+  const normalized = identity.trim().toLowerCase();
+  if (!normalized) throw new Error("Lakebox users require an authenticated identity");
+  return normalized;
+}
+
+/**
+ * Derives the Lakebox account for one authenticated identity.
+ *
+ * @param routePrefix - AppKit root for user service routes.
+ */
+export function lakeboxUser(identity: string, routePrefix: string): LakeboxUser {
+  const userHash = digestText("lakebox-user", normalizeLakeboxIdentity(identity));
+  const name = `${USER_PREFIX}${userHash}`;
+  return {
+    hash: userHash,
+    name,
+    uid: LAKEBOX_UID_MIN + (digestValue("lakebox-uid", userHash) % LAKEBOX_UID_COUNT),
+    home: `/home/${name}`,
+    routePrefix: `${routePrefix.replace(/\/+$/, "")}/${userHash}`,
+  };
+}
+
+/** Returns the persistent backing directory for a user hash. */
+export function lakeboxPersistentHome(userHash: string): string {
+  return `${LAKEBOX_USERS_ROOT}/${userHash}`;
+}
+
+/** Derives the loopback port for one user's service. */
+export function lakeboxServicePort(userHash: string, serviceName: string): number {
+  return (
+    LAKEBOX_PORT_MIN + (digestValue("lakebox-port", userHash, serviceName) % LAKEBOX_PORT_COUNT)
+  );
+}
+
+/** Returns whether a route segment has the shape of a user hash. */
+export function isLakeboxUserHash(value: string): boolean {
+  return /^[0-9a-v]{7}$/.test(value);
+}
+
+function digestText(...values: string[]): string {
+  return hash.fnvHashWithOptions({ length: 7, alphabet: HASH_ALPHABET }, ...values);
+}
+
+function digestValue(...values: string[]): number {
+  return Number.parseInt(digestText(...values), 32);
+}

package/src/workspace.ts

@@ -0,0 +1,185 @@
+import { ConfigurationError } from "@databricks/appkit";
+import { MASTRA_USER_KEY, type User } from "@dbx-tools/appkit-mastra";
+import {
+  MastraSandbox,
+  type CommandResult,
+  type ExecuteCommandOptions,
+  type SandboxInfo,
+  type SandboxStartOptions,
+  type SandboxStartResult,
+  type WorkspaceSandbox,
+  type WorkspaceSandboxResolver,
+} from "@mastra/core/workspace";
+import type { LakeboxRuntime } from "./runtime.ts";
+
+const INSTRUCTIONS = `Commands run on the app's shared Databricks Lakebox as your own locked, non-sudo Linux account with a persistent home. Other users have separate accounts and cannot reach your files or service ports. The Lakebox is created and started on first use and stops after its idle timeout; files and saved services persist.
+
+Run long-lived servers as services, not background commands. Call create_lakebox_service with an OCI image; it starts the service detached, waits until it is ready, and returns openUrl. The runtime injects SERVICE_NAME, SERVICE_PATH, SERVICE_PORT, and PORT. Routed services must listen on 127.0.0.1:$SERVICE_PORT. There is no Docker CLI, daemon, port publishing, privileged mode, or device access. Bind mounts come from your home through the mounts field. Services restart from their saved definition when the Lakebox starts; process memory does not resume.
+
+For a minimal routed Python service:
+
+{
+  "name": "hello",
+  "image": "docker.io/library/python:3.12-alpine",
+  "command": ["python", "-c", "import http.server, os; name=os.environ['SERVICE_NAME']; H=type('H',(http.server.BaseHTTPRequestHandler,),{'do_GET':lambda s:(s.send_response(200),s.send_header('Content-Type','text/plain'),s.end_headers(),s.wfile.write(f'hello from {name}\\\\n'.encode())),'log_message':lambda *a:None}); http.server.ThreadingHTTPServer(('127.0.0.1',int(os.environ['SERVICE_PORT'])),H).serve_forever()"]
+}
+
+Terminal and desktop are built-in services: call start_lakebox_service with name "terminal" or "desktop" and return the openUrl. Graphical applications belong on the desktop; never start, stop, or reconfigure the desktop display yourself.
+
+With execute_lakebox_command, pass command "sh" and put the script in args ["-lc", "..."]; never pass an executable and its arguments together as command. Commands never receive Databricks credentials. Never return localhost, a loopback port, or a direct Lakebox URL; use the returned openUrl. Services must use relative asset and API URLs beneath their route. Derive ws:// or wss:// from the browser origin.`;
+
+/** Options for the Lakebox-backed Mastra workspace sandbox. */
+export interface LakeboxWorkspaceSandboxOptions {
+  /** Optional display name presented by Mastra instead of Lakebox. */
+  displayName?: string;
+}
+
+/**
+ * Mastra workspace sandbox backed by the app Lakebox.
+ *
+ * Commands run as the requesting user's Lakebox account through the shared
+ * {@link LakeboxRuntime}, so identity, credential scrubbing, and transport
+ * policy match the AppKit plugin tools and routes.
+ */
+export class LakeboxWorkspaceSandbox extends MastraSandbox {
+  readonly provider = "appkit-lakebox";
+  status: WorkspaceSandbox["status"] = "pending";
+
+  constructor(
+    readonly id: string,
+    readonly name: string,
+    private readonly runtime: LakeboxRuntime,
+    private readonly identity: string,
+  ) {
+    super({ name });
+  }
+
+  /** Creates or starts the app Lakebox. */
+  async start(options?: SandboxStartOptions): Promise<SandboxStartResult> {
+    await this.runtime.start(options?.abortSignal);
+    this.status = "running";
+    return { outcome: "connected" };
+  }
+
+  /** Leaves the shared Lakebox running; its platform idle timeout stops it. */
+  async stop(): Promise<void> {
+    this.status = "stopped";
+  }
+
+  /** Releases this handle without changing the shared Lakebox. */
+  async destroy(): Promise<void> {
+    this.status = "destroyed";
+  }
+
+  /** Mastra snapshot hook. Lakeboxes do not expose snapshot operations. */
+  async snapshot(): Promise<void> {}
+
+  /** Runs a command as the current user's Lakebox account. */
+  override async executeCommand(
+    command: string,
+    args: string[] = [],
+    options: ExecuteCommandOptions = {},
+  ): Promise<CommandResult> {
+    const execution = this.runtime.execute(
+      this.identity,
+      {
+        command,
+        args,
+        ...(options.cwd ? { cwd: options.cwd } : {}),
+        ...(options.env
+          ? {
+              env: Object.fromEntries(
+                Object.entries(options.env).filter(
+                  (entry): entry is [string, string] => typeof entry[1] === "string",
+                ),
+              ),
+            }
+          : {}),
+        ...(options.timeout ? { timeoutMs: options.timeout } : {}),
+      },
+      options.abortSignal,
+    );
+    if (options.onStdout) execution.stdout.on("data", (chunk: string) => options.onStdout?.(chunk));
+    if (options.onStderr) execution.stderr.on("data", (chunk: string) => options.onStderr?.(chunk));
+    const result = await execution.result;
+    const stdout = retainCommandOutput(result.stdout, options.maxRetainedBytes);
+    const stderr = retainCommandOutput(result.stderr, options.maxRetainedBytes);
+    return {
+      ...result,
+      stdout: stdout.value,
+      stderr: stderr.value,
+      ...(stdout.droppedBytes > 0
+        ? { stdoutTruncated: true, stdoutDroppedBytes: stdout.droppedBytes }
+        : {}),
+      ...(stderr.droppedBytes > 0
+        ? { stderrTruncated: true, stderrDroppedBytes: stderr.droppedBytes }
+        : {}),
+    };
+  }
+
+  /** Returns the current Lakebox status in Mastra's sandbox shape. */
+  async getInfo(): Promise<SandboxInfo> {
+    const summary = await this.runtime.summary(this.identity);
+    this.status =
+      summary.status === "missing" || summary.status === "unknown" ? "pending" : summary.status;
+    return {
+      id: this.id,
+      name: this.name,
+      provider: this.provider,
+      status: this.status,
+      createdAt: new Date(0),
+      metadata: { lakeboxId: summary.id, user: summary.user.name, services: summary.services },
+    };
+  }
+
+  /** Returns agent instructions for services, routes, and command execution. */
+  getInstructions(): string {
+    return INSTRUCTIONS;
+  }
+}
+
+/**
+ * Creates a request-scoped Mastra workspace resolver for the app Lakebox.
+ *
+ * Resolution never creates compute; the first command or service does.
+ */
+export function lakeboxWorkspaceSandbox(
+  runtime: LakeboxRuntime,
+  options: LakeboxWorkspaceSandboxOptions = {},
+): WorkspaceSandboxResolver {
+  return async ({ requestContext }) => {
+    const user = requestContext.get(MASTRA_USER_KEY) as User | undefined;
+    if (!user) {
+      throw ConfigurationError.resourceNotFound(
+        "Lakebox user context",
+        "Invoke Code Mode from an agent turn served by the Mastra plugin.",
+      );
+    }
+    return new LakeboxWorkspaceSandbox(
+      runtime.config.application,
+      options.displayName ?? "Lakebox",
+      runtime,
+      user.id,
+    );
+  };
+}
+
+function retainCommandOutput(
+  output: string,
+  maxRetainedBytes: number | undefined,
+): { value: string; droppedBytes: number } {
+  if (maxRetainedBytes === undefined || maxRetainedBytes === Infinity) {
+    return { value: output, droppedBytes: 0 };
+  }
+  const limit = Number.isFinite(maxRetainedBytes) ? Math.max(0, Math.floor(maxRetainedBytes)) : 0;
+  const bytes = Buffer.from(output);
+  if (bytes.length <= limit) return { value: output, droppedBytes: 0 };
+  let retainedStart = bytes.length - limit;
+  while (retainedStart < bytes.length && (bytes[retainedStart]! & 0xc0) === 0x80) {
+    retainedStart++;
+  }
+  return {
+    value: bytes.subarray(retainedStart).toString("utf8"),
+    droppedBytes: retainedStart,
+  };
+}