ad hoc playwright code exec API (#84)

- add node, playwright, and tsx to the images
- add an endpoint that takes in code and executes it within a shim that
provides a `page` Playwright object

<!-- CURSOR_SUMMARY -->
---

> [!NOTE]
> Adds POST /playwright/execute to run user TypeScript/Playwright code
via tsx against Chromium, updates images with Node.js 22 + Playwright,
and includes an e2e test.
> 
> - **API**:
> - **New Endpoint**: `POST /playwright/execute` to run
Playwright/TypeScript code with timeout; returns
`{success,result,error,stdout,stderr}`
(`server/cmd/api/api/playwright.go`).
> - **OpenAPI + Generated Client/Server**: Spec and codegen updated to
expose request/response types and routing (`server/openapi.yaml`,
`server/lib/oapi/oapi.go`).
> - **Runtime**:
> - **Executor**: Add `server/runtime/playwright-executor.ts` invoked
via `tsx`, connecting to `ws://127.0.0.1:9222` and evaluating provided
code.
> - **Containers**:
> - Install Node.js 22, `typescript`, `playwright-core`, and `tsx`; copy
executor into image (`images/chromium-headful/Dockerfile`,
`images/chromium-headless/image/Dockerfile`).
> - **Tests**:
> - Add e2e test executing a simple Playwright script and asserting
result (`server/e2e/e2e_chromium_test.go`).
> 
> <sup>Written by [Cursor
Bugbot](https://cursor.com/dashboard?tab=bugbot) for commit
8251b07. This will update automatically
on new commits. Configure
[here](https://cursor.com/dashboard?tab=bugbot).</sup>
<!-- /CURSOR_SUMMARY -->

---------

Co-authored-by: tembo[bot] <208362400+tembo-io[bot]@users.noreply.github.com>

Author: rgarcia

images/chromium-headful/Dockerfile

@@ -55,6 +55,7 @@ RUN set -eux; \
 
 FROM ghcr.io/onkernel/neko/base:3.0.8-v1.3.0 AS neko
 # ^--- now has event.SYSTEM_PONG with legacy support to keepalive
+FROM node:22-bullseye-slim AS node-22
 FROM docker.io/ubuntu:22.04
 
 ENV DEBIAN_FRONTEND=noninteractive
@@ -161,6 +162,20 @@ RUN set -eux; \
 RUN add-apt-repository -y ppa:xtradeb/apps
 RUN apt update -y && apt install -y chromium sqlite3
 
+# install Node.js 22.x by copying from the node:22-bullseye-slim stage
+COPY --from=node-22 /usr/local/bin/node /usr/local/bin/node
+COPY --from=node-22 /usr/local/lib/node_modules /usr/local/lib/node_modules
+# Recreate symlinks for npm/npx/corepack to point into node_modules
+RUN set -eux; \
+    ln -sf /usr/local/lib/node_modules/npm/bin/npm-cli.js /usr/local/bin/npm; \
+    ln -sf /usr/local/lib/node_modules/npm/bin/npx-cli.js /usr/local/bin/npx; \
+    if [ -e /usr/local/lib/node_modules/corepack/dist/corepack.js ]; then \
+    ln -sf /usr/local/lib/node_modules/corepack/dist/corepack.js /usr/local/bin/corepack; \
+    fi
+
+# Install TypeScript and Playwright globally
+RUN npm install -g typescript playwright-core tsx
+
 # setup desktop env & app
 ENV DISPLAY_NUM=1
 ENV HEIGHT=768
@@ -185,6 +200,9 @@ COPY images/chromium-headful/supervisor/services/ /etc/supervisor/conf.d/service
 COPY --from=server-builder /out/kernel-images-api /usr/local/bin/kernel-images-api
 COPY --from=server-builder /out/chromium-launcher /usr/local/bin/chromium-launcher
 
+# Copy the Playwright executor runtime
+COPY server/runtime/playwright-executor.ts /usr/local/lib/playwright-executor.ts
+
 RUN useradd -m -s /bin/bash kernel
 
 ENTRYPOINT [ "/wrapper.sh" ]

images/chromium-headless/image/Dockerfile

@@ -21,6 +21,7 @@ RUN GOOS=${TARGETOS:-linux} GOARCH=${TARGETARCH:-amd64} \
 RUN GOOS=${TARGETOS:-linux} GOARCH=${TARGETARCH:-amd64} \
     go build -ldflags="-s -w" -o /out/chromium-launcher ./cmd/chromium-launcher
 
+FROM node:22-bullseye-slim AS node-22
 FROM docker.io/ubuntu:22.04
 
 RUN set -xe; \
@@ -73,6 +74,20 @@ RUN set -eux; \
 # Remove upower to prevent spurious D-Bus activations and logs
 RUN apt-get -yqq purge upower || true && rm -rf /var/lib/apt/lists/*
 
+# install Node.js 22.x by copying from the node:22-bullseye-slim stage
+COPY --from=node-22 /usr/local/bin/node /usr/local/bin/node
+COPY --from=node-22 /usr/local/lib/node_modules /usr/local/lib/node_modules
+# Recreate symlinks for npm/npx/corepack to point into node_modules
+RUN set -eux; \
+    ln -sf /usr/local/lib/node_modules/npm/bin/npm-cli.js /usr/local/bin/npm; \
+    ln -sf /usr/local/lib/node_modules/npm/bin/npx-cli.js /usr/local/bin/npx; \
+    if [ -e /usr/local/lib/node_modules/corepack/dist/corepack.js ]; then \
+    ln -sf /usr/local/lib/node_modules/corepack/dist/corepack.js /usr/local/bin/corepack; \
+    fi
+
+# Install TypeScript and Playwright globally
+RUN npm install -g typescript playwright-core tsx
+
 ENV WITHDOCKER=true
 
 # Create a non-root user with a home directory
@@ -93,4 +108,7 @@ COPY images/chromium-headless/image/supervisor/services/ /etc/supervisor/conf.d/
 COPY --from=server-builder /out/kernel-images-api /usr/local/bin/kernel-images-api
 COPY --from=server-builder /out/chromium-launcher /usr/local/bin/chromium-launcher
 
+# Copy the Playwright executor runtime
+COPY server/runtime/playwright-executor.ts /usr/local/lib/playwright-executor.ts
+
 ENTRYPOINT [ "/usr/bin/wrapper.sh" ]

server/cmd/api/api/api.go

@@ -39,6 +39,9 @@ type ApiService struct {
 
 	// inputMu serializes input-related operations (mouse, keyboard, screenshot)
 	inputMu sync.Mutex
+
+	// playwrightMu serializes Playwright code execution (only one execution at a time)
+	playwrightMu sync.Mutex
 }
 
 var _ oapi.StrictServerInterface = (*ApiService)(nil)

server/cmd/api/api/playwright.go

@@ -0,0 +1,135 @@
+package api
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"os"
+	"os/exec"
+	"time"
+
+	"github.com/onkernel/kernel-images/server/lib/logger"
+	"github.com/onkernel/kernel-images/server/lib/oapi"
+)
+
+// ExecutePlaywrightCode implements the Playwright code execution endpoint
+func (s *ApiService) ExecutePlaywrightCode(ctx context.Context, request oapi.ExecutePlaywrightCodeRequestObject) (oapi.ExecutePlaywrightCodeResponseObject, error) {
+	// Serialize Playwright execution - only one execution at a time
+	s.playwrightMu.Lock()
+	defer s.playwrightMu.Unlock()
+
+	log := logger.FromContext(ctx)
+
+	// Validate request
+	if request.Body == nil || request.Body.Code == "" {
+		return oapi.ExecutePlaywrightCode400JSONResponse{
+			BadRequestErrorJSONResponse: oapi.BadRequestErrorJSONResponse{
+				Message: "code is required",
+			},
+		}, nil
+	}
+
+	// Determine timeout (default to 60 seconds)
+	timeout := 60 * time.Second
+	if request.Body.TimeoutSec != nil && *request.Body.TimeoutSec > 0 {
+		timeout = time.Duration(*request.Body.TimeoutSec) * time.Second
+	}
+
+	// Create a temporary file for the user code
+	tmpFile, err := os.CreateTemp("", "playwright-code-*.ts")
+	if err != nil {
+		log.Error("failed to create temp file", "error", err)
+		return oapi.ExecutePlaywrightCode500JSONResponse{
+			InternalErrorJSONResponse: oapi.InternalErrorJSONResponse{
+				Message: fmt.Sprintf("failed to create temp file: %v", err),
+			},
+		}, nil
+	}
+	tmpFilePath := tmpFile.Name()
+	defer os.Remove(tmpFilePath) // Clean up the temp file
+
+	// Write the user code to the temp file
+	if _, err := tmpFile.WriteString(request.Body.Code); err != nil {
+		tmpFile.Close()
+		log.Error("failed to write code to temp file", "error", err)
+		return oapi.ExecutePlaywrightCode500JSONResponse{
+			InternalErrorJSONResponse: oapi.InternalErrorJSONResponse{
+				Message: fmt.Sprintf("failed to write code to temp file: %v", err),
+			},
+		}, nil
+	}
+	tmpFile.Close()
+
+	// Create context with timeout
+	execCtx, cancel := context.WithTimeout(ctx, timeout)
+	defer cancel()
+
+	// Execute the Playwright code via the executor script
+	cmd := exec.CommandContext(execCtx, "tsx", "/usr/local/lib/playwright-executor.ts", tmpFilePath)
+
+	output, err := cmd.CombinedOutput()
+
+	if err != nil {
+		if execCtx.Err() == context.DeadlineExceeded {
+			log.Error("playwright execution timed out", "timeout", timeout)
+			success := false
+			errorMsg := fmt.Sprintf("execution timed out after %v", timeout)
+			return oapi.ExecutePlaywrightCode200JSONResponse{
+				Success: success,
+				Error:   &errorMsg,
+			}, nil
+		}
+
+		log.Error("playwright execution failed", "error", err, "output", string(output))
+
+		// Try to parse the error output as JSON
+		var result struct {
+			Success bool        `json:"success"`
+			Result  interface{} `json:"result,omitempty"`
+			Error   string      `json:"error,omitempty"`
+			Stack   string      `json:"stack,omitempty"`
+		}
+		if jsonErr := json.Unmarshal(output, &result); jsonErr == nil {
+			success := result.Success
+			errorMsg := result.Error
+			stderr := string(output)
+			return oapi.ExecutePlaywrightCode200JSONResponse{
+				Success: success,
+				Error:   &errorMsg,
+				Stderr:  &stderr,
+			}, nil
+		}
+
+		// If we can't parse the output, return a generic error
+		success := false
+		errorMsg := fmt.Sprintf("execution failed: %v", err)
+		stderr := string(output)
+		return oapi.ExecutePlaywrightCode200JSONResponse{
+			Success: success,
+			Error:   &errorMsg,
+			Stderr:  &stderr,
+		}, nil
+	}
+
+	// Parse successful output
+	var result struct {
+		Success bool        `json:"success"`
+		Result  interface{} `json:"result,omitempty"`
+	}
+	if err := json.Unmarshal(output, &result); err != nil {
+		log.Error("failed to parse playwright output", "error", err, "output", string(output))
+		success := false
+		errorMsg := fmt.Sprintf("failed to parse output: %v", err)
+		stdout := string(output)
+		return oapi.ExecutePlaywrightCode200JSONResponse{
+			Success: success,
+			Error:   &errorMsg,
+			Stdout:  &stdout,
+		}, nil
+	}
+
+	return oapi.ExecutePlaywrightCode200JSONResponse{
+		Success: result.Success,
+		Result:  &result.Result,
+	}, nil
+}

server/e2e/e2e_chromium_test.go

@@ -5,6 +5,7 @@ import (
 	"bytes"
 	"context"
 	"encoding/base64"
+	"encoding/json"
 	"fmt"
 	"io"
 	"mime/multipart"
@@ -729,3 +730,83 @@ func getXvfbResolution(ctx context.Context) (width, height int, err error) {
 
 	return 0, 0, fmt.Errorf("Xvfb process not found in ps aux output")
 }
+
+func TestPlaywrightExecuteAPI(t *testing.T) {
+	image := headlessImage
+	name := containerName + "-playwright-api"
+
+	logger := slog.New(slog.NewTextHandler(t.Output(), &slog.HandlerOptions{Level: slog.LevelInfo}))
+	baseCtx := logctx.AddToContext(context.Background(), logger)
+
+	if _, err := exec.LookPath("docker"); err != nil {
+		require.NoError(t, err, "docker not available: %v", err)
+	}
+
+	// Clean slate
+	_ = stopContainer(baseCtx, name)
+
+	env := map[string]string{}
+
+	// Start container
+	_, exitCh, err := runContainer(baseCtx, image, name, env)
+	require.NoError(t, err, "failed to start container: %v", err)
+	defer stopContainer(baseCtx, name)
+
+	ctx, cancel := context.WithTimeout(baseCtx, 2*time.Minute)
+	defer cancel()
+
+	require.NoError(t, waitHTTPOrExit(ctx, apiBaseURL+"/spec.yaml", exitCh), "api not ready: %v", err)
+
+	client, err := apiClient()
+	require.NoError(t, err)
+
+	// Test simple Playwright script that navigates to a page and returns the title
+	playwrightCode := `
+		await page.goto('https://example.com');
+		const title = await page.title();
+		return title;
+	`
+
+	logger.Info("[test]", "action", "executing playwright code")
+	req := instanceoapi.ExecutePlaywrightCodeJSONRequestBody{
+		Code: playwrightCode,
+	}
+
+	rsp, err := client.ExecutePlaywrightCodeWithResponse(ctx, req)
+	require.NoError(t, err, "playwright execute request error: %v", err)
+	require.Equal(t, http.StatusOK, rsp.StatusCode(), "unexpected status for playwright execute: %s body=%s", rsp.Status(), string(rsp.Body))
+	require.NotNil(t, rsp.JSON200, "expected JSON200 response, got nil")
+
+	// Log the full response for debugging
+	if !rsp.JSON200.Success {
+		var errorMsg string
+		if rsp.JSON200.Error != nil {
+			errorMsg = *rsp.JSON200.Error
+		}
+		var stdout, stderr string
+		if rsp.JSON200.Stdout != nil {
+			stdout = *rsp.JSON200.Stdout
+		}
+		if rsp.JSON200.Stderr != nil {
+			stderr = *rsp.JSON200.Stderr
+		}
+		logger.Error("[test]", "error", errorMsg, "stdout", stdout, "stderr", stderr)
+	}
+
+	require.True(t, rsp.JSON200.Success, "expected success=true, got success=false. Error: %s", func() string {
+		if rsp.JSON200.Error != nil {
+			return *rsp.JSON200.Error
+		}
+		return "nil"
+	}())
+	require.NotNil(t, rsp.JSON200.Result, "expected result to be non-nil")
+
+	// Verify the result contains "Example Domain" (the title of example.com)
+	resultBytes, err := json.Marshal(rsp.JSON200.Result)
+	require.NoError(t, err, "failed to marshal result: %v", err)
+	resultStr := string(resultBytes)
+	logger.Info("[test]", "result", resultStr)
+	require.Contains(t, resultStr, "Example Domain", "expected result to contain 'Example Domain'")
+
+	logger.Info("[test]", "result", "playwright execute API test passed")
+}