@reasonlayer/sdk 0.0.1-rc.3

package/node_modules/@reasonlayer/runner/dist/index.js

@@ -0,0 +1,884 @@
+import { createHash } from "node:crypto";
+import { spawn } from "node:child_process";
+import { existsSync, realpathSync } from "node:fs";
+import { mkdir, symlink, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { ConvexHttpClient } from "convex/browser";
+import { makeFunctionReference } from "convex/server";
+import { catalogActionById } from "@reasonlayer/integrations";
+import { FN, isTerminalRunStatus, LEASE_DEFAULT_MS, LEASE_FLOOR_MS, } from "@reasonlayer/protocol";
+import { FlueTranscriptMapper } from "./flue-transcript.js";
+import { materializeEnvironment, verifyEnvironmentBinaries, } from "./environment-materializer.js";
+import { startMcpServers } from "./mcp-supervisor.js";
+import { createNodeSandboxSessionEnv, killProcessGroup } from "./sandbox-env.js";
+function fn(kind, name) {
+    return makeFunctionReference(name);
+}
+export class RunnerConvexClient {
+    config;
+    client;
+    constructor(config) {
+        this.config = config;
+        this.client = new ConvexHttpClient(config.convexUrl, {
+            logger: false,
+            skipConvexDeploymentUrlCheck: true,
+        });
+    }
+    query(name, args) {
+        return this.client.query(fn("query", name), args);
+    }
+    mutation(name, args) {
+        return this.client.mutation(fn("mutation", name), args, { skipQueue: true });
+    }
+    action(name, args) {
+        return this.client.action(fn("action", name), args);
+    }
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+export function defaultDeviceRunnerId() {
+    return `device-${process.pid}`;
+}
+export function defaultOrgRunnerId() {
+    return `runner-${process.pid}`;
+}
+// Resolution order mirrors who is expected to provide the package: the
+// project the runner was started in (customers install @flue/runtime in
+// their own repo), then the runner package itself (a direct dependency
+// since M7), so local execution works from any working directory.
+// This walks node_modules on disk rather than using require.resolve —
+// @flue/runtime is ESM-only, so require-condition resolution throws
+// ERR_PACKAGE_PATH_NOT_EXPORTED even when the package is installed, and
+// only the package *directory* is needed for the cache symlink.
+function resolvePackageRoot(specifier) {
+    const segments = specifier.split("/");
+    const bases = [process.cwd(), dirname(fileURLToPath(import.meta.url))];
+    for (const base of bases) {
+        for (let dir = base;; dir = dirname(dir)) {
+            const candidate = join(dir, "node_modules", ...segments);
+            if (existsSync(join(candidate, "package.json"))) {
+                try {
+                    return realpathSync(candidate);
+                }
+                catch {
+                    return candidate;
+                }
+            }
+            const parent = dirname(dir);
+            if (parent === dir)
+                break;
+        }
+    }
+    return null;
+}
+async function linkFlueRuntimeIntoCache(cacheDir, required) {
+    const runtimeRoot = resolvePackageRoot("@flue/runtime");
+    if (!runtimeRoot) {
+        if (required) {
+            throw new Error("@flue/runtime is not resolvable from this host; agent bundles import it " +
+                "as an external dependency (spec §7.5). Install it in the project " +
+                "running the runner or run `rl dev` from a directory where " +
+                "it resolves.");
+        }
+        return;
+    }
+    const linkPath = join(cacheDir, "node_modules", "@flue", "runtime");
+    if (existsSync(linkPath))
+        return;
+    await mkdir(dirname(linkPath), { recursive: true });
+    try {
+        await symlink(runtimeRoot, linkPath, process.platform === "win32" ? "junction" : "dir");
+    }
+    catch (err) {
+        if (err.code !== "EEXIST")
+            throw err;
+    }
+}
+async function loadBundle(task, cacheDir) {
+    if (!task.bundleUrl)
+        throw new Error(`task ${task.taskId} has no runner bundle URL`);
+    if (!task.bundleSha256)
+        throw new Error(`task ${task.taskId} is missing runner bundle sha256`);
+    const fetched = await fetch(task.bundleUrl);
+    if (!fetched.ok) {
+        throw new Error(`cannot fetch runner bundle (HTTP ${fetched.status}): ${await fetched.text()}`);
+    }
+    const bytes = Buffer.from(await fetched.arrayBuffer());
+    const sha256 = createHash("sha256").update(bytes).digest("hex");
+    if (task.bundleSha256 !== sha256) {
+        throw new Error(`runner bundle sha256 mismatch for task ${task.taskId}`);
+    }
+    await mkdir(cacheDir, { recursive: true });
+    await linkFlueRuntimeIntoCache(cacheDir, task.kind === "agent");
+    const file = join(cacheDir, `${sha256}.mjs`);
+    await writeFile(file, bytes);
+    return (await import(pathToFileURL(file).href));
+}
+export const TASK_ENV_CONCURRENCY = 1;
+export const DEFAULT_DEVICE_POLL_INTERVAL_MS = 30_000;
+let envQueue = Promise.resolve();
+async function withTaskEnv(env, fn) {
+    const previousQueue = envQueue;
+    let release;
+    envQueue = previousQueue.then(() => new Promise((resolve) => (release = resolve)));
+    await previousQueue;
+    const previous = new Map();
+    for (const [key, value] of Object.entries(env)) {
+        previous.set(key, process.env[key]);
+        process.env[key] = value;
+    }
+    try {
+        return await fn();
+    }
+    finally {
+        for (const [key, value] of previous) {
+            if (value === undefined)
+                delete process.env[key];
+            else
+                process.env[key] = value;
+        }
+        release();
+    }
+}
+const MAX_TRANSCRIPT_BATCH_EVENTS = 20;
+const TRANSCRIPT_FLUSH_INTERVAL_MS = 1000;
+const MAX_TRANSCRIPT_STRING_CHARS = 4096;
+const TRUNCATED = "[truncated]";
+function truncateString(value) {
+    if (value.length <= MAX_TRANSCRIPT_STRING_CHARS)
+        return value;
+    return `${value.slice(0, MAX_TRANSCRIPT_STRING_CHARS - TRUNCATED.length)}${TRUNCATED}`;
+}
+function sanitizeTranscriptValue(value, secrets) {
+    if (typeof value === "string") {
+        const redacted = secrets.reduce((acc, secret) => (secret ? acc.split(secret).join("[redacted]") : acc), value);
+        return truncateString(redacted);
+    }
+    if (Array.isArray(value))
+        return value.map((item) => sanitizeTranscriptValue(item, secrets));
+    if (value && typeof value === "object") {
+        return Object.fromEntries(Object.entries(value).map(([key, nested]) => [
+            key,
+            sanitizeTranscriptValue(nested, secrets),
+        ]));
+    }
+    return value;
+}
+export class TranscriptReporter {
+    client;
+    claim;
+    secrets;
+    buffer = [];
+    flushing = Promise.resolve();
+    flushTimer;
+    constructor(client, claim, secrets) {
+        this.client = client;
+        this.claim = claim;
+        this.secrets = secrets;
+        this.flushTimer = setInterval(() => void this.flush(), TRANSCRIPT_FLUSH_INTERVAL_MS);
+        this.flushTimer.unref?.();
+    }
+    async push(event) {
+        this.buffer.push(sanitizeTranscriptValue(event, this.secrets));
+        if (this.buffer.length >= MAX_TRANSCRIPT_BATCH_EVENTS)
+            await this.flush();
+    }
+    async flush() {
+        if (this.buffer.length === 0)
+            return;
+        const batch = this.buffer.splice(0, this.buffer.length);
+        this.flushing = this.flushing
+            .then(() => this.client.mutation(FN.transcriptsIngest, {
+            taskId: this.claim.task.taskId,
+            taskToken: this.claim.taskToken,
+            events: batch,
+        }))
+            .catch((err) => {
+            console.error(`[reasonlayer-runner] transcript flush failed: ${err.message}`);
+        });
+        await this.flushing;
+    }
+    async close() {
+        clearInterval(this.flushTimer);
+        await this.flush();
+        await this.flushing;
+    }
+}
+async function executeCodeTask(module, task) {
+    const runs = module["STEP_RUNS"];
+    const run = runs?.[task.entryStepId] ??
+        module[task.exportName];
+    if (typeof run !== "function")
+        throw new Error(`code export not found for ${task.entryStepId}`);
+    return await withTaskEnv(task.env, async () => await run(task.input));
+}
+async function executeAgentTask(module, task, reporter, signal) {
+    if (task.framework !== "flue") {
+        throw new Error(`unsupported agent framework: ${task.framework ?? "unknown"}`);
+    }
+    const agents = module["AGENT_RUNS"];
+    const agent = agents?.[task.entryStepId] ?? module[task.exportName];
+    if (!agent)
+        throw new Error(`agent export not found for ${task.entryStepId}`);
+    const catalogTools = catalogToolDefinitions(task.catalogTools);
+    if (typeof agent === "function") {
+        if (catalogTools.length > 0) {
+            throw new Error(`inline function agent ${task.entryStepId} cannot use catalog tools; use a Flue defineAgent() definition`);
+        }
+        return await withTaskEnv(task.env, async () => await agent(task.input));
+    }
+    const mcp = await startMcpServers(task.environment, { taskEnv: task.env, signal });
+    const env = { ...task.env, ...mcp.env };
+    try {
+        return await withTaskEnv(env, async () => await runFlueStep(withMcpTools(agent, [...catalogTools, ...mcp.tools]), task.input, {
+            env,
+            signal,
+            emit: (event) => reporter.push(event),
+            runId: task.runId,
+            stepId: task.stepId,
+            outputSchemaJsonText: task.outputSchemaJsonText,
+            host: task.host,
+        }));
+    }
+    finally {
+        await mcp.close();
+    }
+}
+export function catalogToolDefinitions(actionIds) {
+    return actionIds.map((actionId) => {
+        const descriptor = catalogActionById(actionId);
+        if (!descriptor) {
+            throw new Error(`unknown catalog tool "${actionId}" in agent task`);
+        }
+        return {
+            name: descriptor.id,
+            description: descriptor.description,
+            input: descriptor.input,
+            output: descriptor.output,
+            run: async ({ input }) => await descriptor(input),
+        };
+    });
+}
+/**
+ * Inject runner-owned tools into the agent's resolved runtime config — the
+ * definition alone can't know them (the runner owns catalog access and MCP
+ * server startup/port allocation).
+ */
+export function withMcpTools(agent, tools) {
+    if (tools.length === 0)
+        return agent;
+    const definition = agent;
+    if (typeof definition?.initialize !== "function") {
+        throw new Error("declared MCP servers require a defineAgent() agent definition");
+    }
+    const initialize = definition.initialize.bind(definition);
+    return {
+        __flueAgentDefinition: true,
+        initialize: async (context) => {
+            const config = (await initialize(context));
+            return { ...config, tools: [...(config.tools ?? []), ...tools] };
+        },
+    };
+}
+export function createDefaultFlueSessionEnv(_host, cwd = process.cwd()) {
+    return createNodeSandboxSessionEnv(cwd);
+}
+async function runFlueStep(agent, input, context) {
+    const runtimeSpecifier = "@flue/runtime";
+    const internalSpecifier = "@flue/runtime/internal";
+    const nodeSpecifier = "@flue/runtime/node";
+    const runtime = (await import(runtimeSpecifier));
+    const internal = (await import(internalSpecifier));
+    const node = (await import(nodeSpecifier));
+    const adapter = node.sqlite();
+    if (adapter.migrate)
+        await adapter.migrate();
+    const { executionStore } = await adapter.connect();
+    const activityGate = internal.createRuntimeActivityGate();
+    const env = { ...process.env, ...context.env };
+    const createDefaultEnv = async () => createDefaultFlueSessionEnv(context.host);
+    const coordinator = internal.createNodeAgentCoordinator({
+        submissions: executionStore.submissions,
+        agents: [{ name: "reasonlayer-agent", definition: agent }],
+        activityGate,
+        createContext: ({ id, agentName, request, initialEventIndex, dispatchId }) => internal.createFlueContext({
+            id,
+            agentName,
+            dispatchId,
+            initialEventIndex,
+            env,
+            req: request,
+            agentConfig: { resolveModel: internal.resolveModel },
+            createDefaultEnv,
+        }),
+    });
+    const runtimeAdapter = {
+        observe: runtime.observe,
+        createInstrumentationOwner: internal.createInstrumentationOwner,
+        runWithInstrumentationOwner: internal.runWithInstrumentationOwner,
+    };
+    return await runFlueStepWithCoordinator(input, context, {
+        runtime: runtimeAdapter,
+        coordinator,
+    });
+}
+export async function runFlueStepWithCoordinator(input, context, adapters) {
+    const mapper = new FlueTranscriptMapper();
+    const { runtime, coordinator } = adapters;
+    const owner = runtime.createInstrumentationOwner();
+    const instanceId = `${context.runId}:${context.stepId}`;
+    const keepAlive = setInterval(() => { }, 1000);
+    const onAbort = () => void coordinator.abortInstance("reasonlayer-agent", instanceId).catch(() => { });
+    context.signal.addEventListener("abort", onAbort, { once: true });
+    let terminalErrorEmitted = false;
+    try {
+        return await runtime.runWithInstrumentationOwner(owner, async () => {
+            let lastPromptOperation;
+            let maxSeq = -1;
+            const unsubscribe = runtime.observe((event) => {
+                if (typeof event.eventIndex === "number" && event.eventIndex > maxSeq)
+                    maxSeq = event.eventIndex;
+                if (event.type === "operation" && event.operationKind === "prompt") {
+                    lastPromptOperation = event;
+                }
+                for (const mapped of mapper.map(event))
+                    void context.emit(mapped);
+            });
+            try {
+                const admit = coordinator.createAdmission("reasonlayer-agent", instanceId);
+                void admit({ message: toMessage(input) }, () => { }, true).catch(() => { });
+                await coordinator.waitForIdle();
+                if (lastPromptOperation?.isError) {
+                    terminalErrorEmitted = true;
+                    await context.emit(mapper.terminalError(maxSeq + 1, lastPromptOperation.error));
+                    throw new Error(String(lastPromptOperation.error?.message ?? lastPromptOperation.error));
+                }
+                return extractOutput(lastPromptOperation?.result, context.outputSchemaJsonText);
+            }
+            catch (err) {
+                if (!terminalErrorEmitted) {
+                    terminalErrorEmitted = true;
+                    await context.emit(mapper.terminalError(maxSeq + 1, err));
+                }
+                throw err;
+            }
+            finally {
+                unsubscribe();
+            }
+        });
+    }
+    finally {
+        context.signal.removeEventListener("abort", onAbort);
+        clearInterval(keepAlive);
+        await coordinator.shutdown(0).catch(() => { });
+    }
+}
+function outputSchemaType(outputSchemaJsonText) {
+    try {
+        const parsed = JSON.parse(outputSchemaJsonText);
+        return typeof parsed.type === "string" ? parsed.type : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+export function extractOutput(result, outputSchemaJsonText) {
+    const shouldParseJsonText = outputSchemaType(outputSchemaJsonText) !== "string";
+    const parseJsonText = (value) => {
+        if (typeof value !== "string")
+            return value;
+        if (!shouldParseJsonText)
+            return value;
+        const trimmed = value.trim();
+        try {
+            return JSON.parse(trimmed);
+        }
+        catch {
+            return value;
+        }
+    };
+    if (result && typeof result === "object") {
+        const record = result;
+        // Flue may surface model text through either field; parse JSON text
+        // uniformly (schema-aware) so a string payload validates against
+        // object/array output schemas regardless of which field carried it.
+        if (record.data !== undefined)
+            return parseJsonText(record.data);
+        if ("text" in record)
+            return parseJsonText(record.text);
+    }
+    return parseJsonText(result);
+}
+function toMessage(input) {
+    return typeof input === "string" ? input : JSON.stringify(input ?? null);
+}
+class TaskAbortError extends Error {
+}
+async function runAbortable(signal, fn) {
+    if (signal.aborted)
+        throw new TaskAbortError("task aborted");
+    let onAbort;
+    try {
+        return await Promise.race([
+            fn(),
+            new Promise((_resolve, reject) => {
+                onAbort = () => reject(new TaskAbortError("task aborted"));
+                signal.addEventListener("abort", onAbort, { once: true });
+            }),
+        ]);
+    }
+    finally {
+        if (onAbort)
+            signal.removeEventListener("abort", onAbort);
+    }
+}
+function integrationTaskEnv(claim, convexUrl) {
+    return {
+        RL_TASK_ID: claim.task.taskId,
+        RL_TASK_TOKEN: claim.taskToken,
+        RL_CONVEX_URL: convexUrl,
+    };
+}
+export async function executeClaimTask(claim, options) {
+    if (claim.task.kind === "action") {
+        throw new Error("catalog actions execute through the backend provider boundary");
+    }
+    let task = claim.task;
+    if (options.verifyDeviceEnvironments &&
+        task.host.kind === "device" &&
+        task.environment) {
+        await verifyEnvironmentBinaries(task.environment);
+    }
+    if (options.materializeEnvironments && task.environment) {
+        const materialized = await materializeEnvironment(task.environment);
+        task = {
+            ...task,
+            env: {
+                ...task.env,
+                ...materialized.env,
+            },
+        };
+    }
+    task = {
+        ...task,
+        env: {
+            ...task.env,
+            ...integrationTaskEnv(claim, options.convexUrl),
+        },
+    };
+    const module = await loadBundle(task, options.cacheDir ?? join(process.cwd(), ".rl", "runner-cache"));
+    return await runAbortable(options.signal, async () => task.kind === "agent"
+        ? await executeAgentTask(module, task, options.reporter, options.signal)
+        : await executeCodeTask(module, task));
+}
+export function createInProcessTaskProcessAdapter() {
+    return {
+        run: async (claim, options) => await executeClaimTask(claim, options),
+    };
+}
+function childEntryPath() {
+    return fileURLToPath(new URL("./task-child.js", import.meta.url));
+}
+function resultError(result) {
+    const error = new Error(result.message);
+    if (result.stack)
+        error.stack = result.stack;
+    return error;
+}
+async function runTaskChildProcess(claim, options, childPath = childEntryPath()) {
+    if (options.signal.aborted)
+        throw new TaskAbortError("task aborted");
+    if (claim.task.kind === "action") {
+        throw new Error("catalog actions cannot enter the task subprocess");
+    }
+    const child = spawn(process.execPath, [childPath], {
+        detached: process.platform !== "win32",
+        env: {
+            ...process.env,
+            ...claim.task.env,
+            ...integrationTaskEnv(claim, options.convexUrl),
+        },
+        stdio: ["ignore", "inherit", "inherit", "ipc"],
+    });
+    let killTimer;
+    let resultReceived = false;
+    let settled = false;
+    return await new Promise((resolve, reject) => {
+        const cleanup = () => {
+            options.signal.removeEventListener("abort", onAbort);
+            if (killTimer)
+                clearTimeout(killTimer);
+        };
+        const settle = (fn) => {
+            if (settled)
+                return;
+            settled = true;
+            cleanup();
+            fn();
+        };
+        const onAbort = () => {
+            killProcessGroup(child, "SIGTERM");
+            killTimer = setTimeout(() => killProcessGroup(child, "SIGKILL"), 5_000);
+            killTimer.unref?.();
+        };
+        options.signal.addEventListener("abort", onAbort, { once: true });
+        child.once("error", (err) => settle(() => reject(err)));
+        child.once("exit", (code, signal) => {
+            if (resultReceived)
+                return;
+            settle(() => reject(new Error(`task child exited before reporting a result (code ${code ?? "null"}, signal ${signal ?? "null"})`)));
+        });
+        child.on("message", (message) => {
+            if (!message || typeof message !== "object")
+                return;
+            if (message.type === "transcript") {
+                void options.reporter.push(message.event);
+                return;
+            }
+            if (message.type === "result") {
+                resultReceived = true;
+                const result = message.result;
+                if (result.kind === "ok") {
+                    settle(() => resolve(result.output));
+                }
+                else if (result.kind === "error") {
+                    settle(() => reject(resultError(result)));
+                }
+                else {
+                    settle(() => reject(new TaskAbortError("task aborted")));
+                }
+            }
+        });
+        child.send?.({
+            type: "run",
+            claim,
+            options: {
+                convexUrl: options.convexUrl,
+                ...(options.cacheDir !== undefined ? { cacheDir: options.cacheDir } : {}),
+                ...(options.materializeEnvironments !== undefined
+                    ? { materializeEnvironments: options.materializeEnvironments }
+                    : {}),
+                ...(options.verifyDeviceEnvironments !== undefined
+                    ? { verifyDeviceEnvironments: options.verifyDeviceEnvironments }
+                    : {}),
+            },
+        });
+        if (options.signal.aborted)
+            onAbort();
+    });
+}
+export function createSubprocessTaskProcessAdapter(options = {}) {
+    return {
+        run: async (claim, runOptions) => await runTaskChildProcess(claim, runOptions, options.childEntryPath),
+    };
+}
+function heartbeatIntervalMs(options) {
+    const raw = options.heartbeatIntervalMs ??
+        Math.floor((options.leaseMs ?? LEASE_DEFAULT_MS) / 3);
+    if (!Number.isFinite(raw))
+        return LEASE_FLOOR_MS;
+    return Math.max(LEASE_FLOOR_MS, Math.floor(raw));
+}
+export async function runClaim(config, claim, options = {}) {
+    const client = options.client ?? new RunnerConvexClient(config);
+    const controller = new AbortController();
+    let cancelRequested = false;
+    const onExternalAbort = () => {
+        cancelRequested = true;
+        controller.abort();
+    };
+    if (options.signal?.aborted) {
+        onExternalAbort();
+    }
+    else {
+        options.signal?.addEventListener("abort", onExternalAbort, { once: true });
+    }
+    const heartbeatMs = heartbeatIntervalMs(options);
+    const heartbeat = setInterval(() => {
+        void client
+            .mutation(FN.tasksHeartbeat, {
+            taskId: claim.task.taskId,
+            taskToken: claim.taskToken,
+            leaseMs: options.leaseMs,
+        })
+            .then((status) => {
+            if (status.cancelRequested) {
+                cancelRequested = true;
+                controller.abort();
+            }
+        })
+            .catch(() => { });
+    }, heartbeatMs);
+    let timedOut = false;
+    const timeout = claim.task.timeoutMs
+        ? setTimeout(() => {
+            timedOut = true;
+            controller.abort();
+        }, claim.task.timeoutMs)
+        : undefined;
+    const reporter = new TranscriptReporter(client, claim, claim.task.kind === "action" ? [] : Object.values(claim.task.env));
+    const processAdapter = options.processAdapter ?? createSubprocessTaskProcessAdapter();
+    let result;
+    try {
+        const output = claim.task.kind === "action"
+            // The runner owns task lifecycle; Convex owns provider I/O so catalog
+            // credentials and connection references never enter the subprocess.
+            ? await runAbortable(controller.signal, async () => await client.action(FN.integrationsExecuteTaskAction, {
+                taskId: claim.task.taskId,
+                taskToken: claim.taskToken,
+            }))
+            : await processAdapter.run(claim, {
+                convexUrl: config.convexUrl,
+                ...(options.cacheDir !== undefined ? { cacheDir: options.cacheDir } : {}),
+                ...(options.materializeEnvironments !== undefined
+                    ? { materializeEnvironments: options.materializeEnvironments }
+                    : {}),
+                ...(options.verifyDeviceEnvironments !== undefined
+                    ? { verifyDeviceEnvironments: options.verifyDeviceEnvironments }
+                    : {}),
+                signal: controller.signal,
+                reporter,
+            });
+        result = { kind: "ok", output };
+    }
+    catch (err) {
+        if (cancelRequested)
+            result = { kind: "canceled" };
+        else if (timedOut) {
+            result = {
+                kind: "error",
+                message: `task timed out after ${claim.task.timeoutMs}ms`,
+            };
+        }
+        else {
+            result = { kind: "error", message: err instanceof Error ? err.message : String(err) };
+        }
+    }
+    finally {
+        options.signal?.removeEventListener("abort", onExternalAbort);
+        clearInterval(heartbeat);
+        if (timeout)
+            clearTimeout(timeout);
+        await reporter.close();
+    }
+    await client.mutation(FN.tasksComplete, {
+        taskId: claim.task.taskId,
+        taskToken: claim.taskToken,
+        result,
+    });
+    return result;
+}
+export function runScopedSource(options) {
+    return {
+        label: "run claim",
+        async claim(client, runnerId, leaseMs) {
+            return await client.mutation(FN.tasksClaimNextForRun, {
+                runId: options.runId,
+                executorToken: options.executorToken,
+                runnerId,
+                leaseMs,
+            });
+        },
+    };
+}
+export function deviceJwtSource(options) {
+    if (!options.deviceToken && !options.deviceTokenProvider) {
+        throw new Error("device claim loop requires deviceToken or deviceTokenProvider");
+    }
+    return {
+        label: "device claim",
+        taskOptions: { verifyDeviceEnvironments: true },
+        async claim(client, runnerId, leaseMs) {
+            const deviceToken = options.deviceTokenProvider
+                ? await options.deviceTokenProvider()
+                : options.deviceToken;
+            return await client.mutation(FN.tasksClaimDeviceNext, {
+                deviceToken,
+                runnerId,
+                leaseMs,
+            });
+        },
+    };
+}
+export function dispatchTokenSource(options) {
+    let claimed = false;
+    return {
+        label: "dispatch claim",
+        stopWhenIdle: true,
+        async claim(client, runnerId, leaseMs) {
+            if (claimed)
+                return null;
+            if (options.sandboxId !== undefined) {
+                await client.mutation(FN.tasksRecordSpawned, {
+                    taskId: options.taskId,
+                    dispatchToken: options.dispatchToken,
+                    sandboxId: options.sandboxId,
+                });
+            }
+            const claim = await client.mutation(FN.tasksClaimDispatched, {
+                taskId: options.taskId,
+                dispatchToken: options.dispatchToken,
+                runnerId,
+                leaseMs,
+            });
+            claimed = true;
+            return claim;
+        },
+    };
+}
+export async function runTaskLoop(options) {
+    const client = options.client ?? new RunnerConvexClient(options);
+    const runnerId = options.runnerId ?? defaultOrgRunnerId();
+    const pollIntervalMs = options.pollIntervalMs ?? 1000;
+    const executor = options.executor ??
+        {
+            run: async (claim, runOptions) => await runClaim(options, claim, runOptions),
+        };
+    let lastResult;
+    for (;;) {
+        try {
+            const claim = await options.source.claim(client, runnerId, options.leaseMs);
+            if (claim) {
+                lastResult = await executor.run(claim, claimOptions(options, options.source.taskOptions));
+                if (options.once || options.source.stopWhenIdle)
+                    return lastResult;
+                continue;
+            }
+            if (options.once || options.source.stopWhenIdle)
+                return lastResult;
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            console.error(`[reasonlayer-runner] ${options.source.label} poll failed: ${message}`);
+        }
+        await sleep(pollIntervalMs);
+    }
+}
+export async function runTestRun(options) {
+    const client = options.client ?? new RunnerConvexClient(options);
+    const runnerId = options.runnerId ?? defaultOrgRunnerId();
+    const pollIntervalMs = options.pollIntervalMs ?? 1000;
+    const concurrency = Math.max(1, Math.floor(options.concurrency ?? 4));
+    const source = runScopedSource({
+        runId: options.runId,
+        executorToken: options.executorToken,
+    });
+    const executor = options.executor ??
+        {
+            run: async (claim, runOptions) => await runClaim(options, claim, runOptions),
+        };
+    const inFlight = new Set();
+    let cancelPromise;
+    // In-flight tasks must abort both when the CLI is interrupted and when the
+    // run goes terminal underneath them (external cancel / sibling failure) —
+    // they report their canceled result before the process exits.
+    const taskAbort = new AbortController();
+    if (options.signal?.aborted)
+        taskAbort.abort();
+    else
+        options.signal?.addEventListener("abort", () => taskAbort.abort(), { once: true });
+    const getRun = async () => await client.query(FN.runsGet, {
+        token: options.token,
+        runId: options.runId,
+    });
+    const requestCancel = () => {
+        if (cancelPromise)
+            return;
+        cancelPromise = client
+            .mutation(FN.runsCancel, { token: options.token, runId: options.runId })
+            .catch((err) => {
+            const message = err instanceof Error ? err.message : String(err);
+            console.error(`[reasonlayer-runner] test run cancel failed: ${message}`);
+        });
+    };
+    const startClaim = async () => {
+        const claim = await source.claim(client, runnerId, options.leaseMs);
+        if (!claim)
+            return false;
+        const task = executor
+            .run(claim, {
+            ...claimOptions(options),
+            materializeEnvironments: true,
+            signal: taskAbort.signal,
+        })
+            .catch((err) => {
+            const message = err instanceof Error ? err.message : String(err);
+            console.error(`[reasonlayer-runner] test task execution failed: ${message}`);
+        })
+            .then(() => undefined);
+        inFlight.add(task);
+        task.finally(() => inFlight.delete(task));
+        return true;
+    };
+    for (;;) {
+        if (options.signal?.aborted)
+            requestCancel();
+        while (!options.signal?.aborted && inFlight.size < concurrency) {
+            try {
+                const claimed = await startClaim();
+                if (!claimed)
+                    break;
+            }
+            catch (err) {
+                const message = err instanceof Error ? err.message : String(err);
+                console.error(`[reasonlayer-runner] ${source.label} poll failed: ${message}`);
+                break;
+            }
+        }
+        const run = await getRun();
+        if (isTerminalRunStatus(run.status)) {
+            if (inFlight.size > 0) {
+                taskAbort.abort();
+                await Promise.race([Promise.allSettled([...inFlight]), sleep(10_000)]);
+            }
+            return run;
+        }
+        if (inFlight.size === 0) {
+            await sleep(pollIntervalMs);
+        }
+        else {
+            await Promise.race([...inFlight, sleep(pollIntervalMs)]);
+        }
+    }
+}
+export async function runDispatchedTask(options) {
+    const result = await runTaskLoop({
+        ...options,
+        runnerId: options.runnerId ?? defaultOrgRunnerId(),
+        once: true,
+        source: dispatchTokenSource({
+            taskId: options.taskId,
+            dispatchToken: options.dispatchToken,
+            ...(options.sandboxId !== undefined ? { sandboxId: options.sandboxId } : {}),
+        }),
+    });
+    if (!result)
+        throw new Error("dispatched task was not claimed");
+    return result;
+}
+export async function runDeviceClaimLoop(options) {
+    await runTaskLoop({
+        ...options,
+        pollIntervalMs: options.pollIntervalMs ?? DEFAULT_DEVICE_POLL_INTERVAL_MS,
+        runnerId: options.runnerId ?? defaultDeviceRunnerId(),
+        source: deviceJwtSource(options),
+    });
+}
+function claimOptions(options, sourceOptions = {}) {
+    return {
+        ...(options.cacheDir !== undefined ? { cacheDir: options.cacheDir } : {}),
+        ...(options.leaseMs !== undefined ? { leaseMs: options.leaseMs } : {}),
+        ...(options.materializeEnvironments !== undefined
+            ? { materializeEnvironments: options.materializeEnvironments }
+            : {}),
+        ...(options.verifyDeviceEnvironments !== undefined
+            ? { verifyDeviceEnvironments: options.verifyDeviceEnvironments }
+            : {}),
+        ...(sourceOptions.verifyDeviceEnvironments !== undefined
+            ? { verifyDeviceEnvironments: sourceOptions.verifyDeviceEnvironments }
+            : {}),
+        ...(options.signal !== undefined ? { signal: options.signal } : {}),
+    };
+}