feat: implement the code mode runtime Actor

.actor/actor.json

@@ -0,0 +1,94 @@
+{
+    "actorSpecification": 1,
+    "name": "code-runtime",
+    "title": "Code Runtime",
+    "description": "Runs one JS script in a sandboxed Actor with an apify binding (Actors, datasets, KV stores). Worth it for bulk work: 50+ record filter/sort/aggregate, or 10+ item fan-out (e.g. many page visits). Skip for a single <10-item lookup \u2014 call the Actor directly instead. Read the README first.",
+    "version": "0.1",
+    "buildTag": "latest",
+    "usesStandbyMode": false,
+    "defaultRunOptions": {
+        "timeoutSecs": 900,
+        "memoryMbytes": 1024
+    },
+    "input": {
+        "title": "Code Runtime Input",
+        "description": "The program to run inside the sandbox.",
+        "type": "object",
+        "schemaVersion": 1,
+        "properties": {
+            "code": {
+                "title": "Code",
+                "type": "string",
+                "description": "JavaScript executed in the sandbox with `apify` and `console` globals; only console output is captured and pushed to the dataset as { stdout, stderr, exitCode, statusMessage } — a top-level `return` value is NOT captured. Before writing code that calls a specific Actor, check its real input field names first — via fetch-actor-details (outside this script, before you write it) or apify.actor.get({ actorId }) (inside it, for an Actor picked at runtime). Do not guess field names from memory; a wrong one throws a fast 400, but costs a wasted round trip. Print a small JSON summary of the result — never dump full datasets. Write top-level `await` statements directly in the script; do NOT wrap your logic in an async function you call without awaiting (e.g. `async function main(){...}; main()`) — the script returns as soon as the top-level body finishes, silently discarding anything still pending, with no error. Every apify.* method takes ONE options object keyed by id, e.g. apify.actor.call({ actorId, input }), apify.dataset.listItems({ datasetId, limit }) — this is NOT the public apify-client SDK's curried apify.actor(id).call(input) shape. If a prior attempt already logged a nested run's defaultDatasetId/defaultKeyValueStoreId (visible in your own earlier turns), reuse it — do NOT re-run the same Actor call with identical input, that wastes compute on a call that already succeeded. apify.actor.call/run.waitForFinish may return non-terminal (READY/RUNNING) once the 60s wait cap elapses — that is NOT a failure, poll again instead of throwing.",
+                "editor": "javascript"
+            },
+            "maxActorRuns": {
+                "title": "Max Actor runs",
+                "type": "integer",
+                "description": "Caps how many Actor runs this script may start in total across actor.start/actor.call/actor.callAndGetItems. Starting one more once the limit is reached throws inside the script. Omit for no limit.",
+                "minimum": 1
+            },
+            "maxTotalChargeUsd": {
+                "title": "Max total charge (USD)",
+                "type": "number",
+                "description": "Execution-wide spending budget across every Actor run this script starts — distinct from a single call's own maxTotalChargeUsd, which only caps that one run. Each run's own cap is clamped so the combined total never exceeds this budget; starting a run once it's exhausted throws inside the script. Omit for no limit.",
+                "minimum": 0
+            },
+            "defaultTimeoutSecs": {
+                "title": "Default Actor run timeout (seconds)",
+                "type": "integer",
+                "description": "Applied as timeoutSecs to actor.start/actor.call/actor.callAndGetItems calls that don't specify their own. Omit to use the Apify API's own default.",
+                "minimum": 1
+            }
+        },
+        "required": ["code"]
+    },
+    "output": {
+        "actorOutputSchemaVersion": 1,
+        "title": "Code Runtime Output",
+        "description": "One dataset item { stdout, stderr, exitCode, statusMessage } (exitCode: 0=returned, 1=threw); see the exitCode field description for the timeout/OOM case.",
+        "type": "object",
+        "properties": {
+            "output": {
+                "type": "string",
+                "title": "Execution output",
+                "template": "{{links.apiDefaultDatasetUrl}}/items"
+            }
+        }
+    },
+    "storages": {
+        "dataset": {
+            "actorSpecification": 1,
+            "description": "Present only if the script ran to completion (returned or threw). A run-level timeout or OOM kill produces zero items for that run — the calling Actor-run's own status (SUCCEEDED vs FAILED/TIMED-OUT) is the signal for that case, not item presence.",
+            "fields": {
+                "$schema": "http://json-schema.org/draft-07/schema#",
+                "type": "object",
+                "properties": {
+                    "stdout": {
+                        "type": "string",
+                        "title": "stdout",
+                        "description": "Captured console.log/console.info output."
+                    },
+                    "stderr": {
+                        "type": "string",
+                        "title": "stderr",
+                        "description": "Captured console.error/console.warn output, plus the thrown error (or compile failure) message when exitCode is 1."
+                    },
+                    "exitCode": {
+                        "type": "integer",
+                        "enum": [0, 1],
+                        "title": "Exit code",
+                        "description": "0 = script returned normally, 1 = script threw (or failed to compile)."
+                    },
+                    "statusMessage": {
+                        "type": "string",
+                        "title": "Status message",
+                        "description": "Prose form of the same signal: 'Script completed' / 'Script threw: ...' / 'Failed to compile: ...'."
+                    }
+                },
+                "required": ["stdout", "stderr", "exitCode", "statusMessage"]
+            }
+        }
+    },
+    "dockerfile": "../Dockerfile"
+}

.dockerignore

@@ -0,0 +1,4 @@
+node_modules
+.git
+*.log
+.DS_Store

.github/workflows/remote-smoke.yml

@@ -0,0 +1,41 @@
+name: Remote smoke tests
+
+on:
+  push:
+    branches: [master]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: remote-smoke-${{ github.ref }}
+  cancel-in-progress: false
+
+jobs:
+  remote-smoke:
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    steps:
+      - name: Check out source
+        uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
+
+      - name: Set up pnpm
+        uses: pnpm/action-setup@f40ffcd9367d9f12939873eb1018b921a783ffaa # v4
+
+      - name: Set up Node.js
+        uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4
+        with:
+          node-version: 24
+          cache: pnpm
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Set up Apify CLI
+        uses: apify/setup-apify-cli-action@8b19e6a52312e8948b3b10cdb06bd3fa39e8db4a
+        with:
+          token: ${{ secrets.APIFY_TOKEN }}
+
+      - name: Run remote smoke tests
+        run: ./test.sh

.github/workflows/typecheck.yml

@@ -0,0 +1,46 @@
+name: Typecheck and test
+
+on:
+  push:
+    branches: [master]
+  pull_request:
+
+jobs:
+  typecheck:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: pnpm/action-setup@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 24
+          cache: pnpm
+      - run: pnpm install --frozen-lockfile
+      - run: pnpm run typecheck
+
+  # Token-free unit tests for guard and redirect logic.
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: pnpm/action-setup@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 24
+          cache: pnpm
+      - run: pnpm install --frozen-lockfile
+      - run: pnpm run test
+
+  # Real workerd integration tests with a local API mock.
+  test-integration:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: pnpm/action-setup@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 24
+          cache: pnpm
+      - run: pnpm install --frozen-lockfile
+      - run: pnpm build
+      - run: pnpm run test:integration

.gitignore

@@ -0,0 +1,11 @@
+node_modules/
+# Generated at container startup by entrypoint.sh (never checked in):
+worker/usercode.js
+# Compiled from worker/*.ts and tests/*.ts by `pnpm build` (tsconfig.json emits next to source):
+worker/runner.js
+worker/guard.js
+tests/*.js
+tests/unit/*.js
+tests/integration/*.js
+*.log
+.DS_Store

Dockerfile

@@ -0,0 +1,28 @@
+# Build with Node; run with only workerd and required utilities.
+FROM node:24-bookworm-slim AS builder
+WORKDIR /build
+COPY package.json pnpm-lock.yaml tsconfig.json ./
+COPY worker/ ./worker/
+# The binary ships in an optional dependency; compile worker files directly.
+RUN corepack enable \
+    && pnpm install --frozen-lockfile --ignore-scripts \
+    && pnpm exec tsc -p tsconfig.json \
+    && BIN="$(node -e "process.stdout.write(require('workerd').default)")" \
+    && cp "$BIN" /workerd \
+    && chmod +x /workerd
+
+# Minimal runtime image: workerd, compiled JS, and certificates.
+FROM debian:bookworm-slim
+
+# curl fetches input; jq extracts user code.
+RUN apt-get update \
+    && apt-get install -y --no-install-recommends ca-certificates curl jq \
+    && rm -rf /var/lib/apt/lists/*
+
+COPY --from=builder /workerd /usr/local/bin/workerd
+
+WORKDIR /app
+COPY worker/entrypoint.sh worker/config.capnp ./worker/
+COPY --from=builder /build/worker/runner.js /build/worker/guard.js ./worker/
+
+ENTRYPOINT ["sh", "/app/worker/entrypoint.sh"]