@reasonlayer/sdk 0.0.1

package/dist/bundler/node.js

@@ -0,0 +1,55 @@
+import * as esbuild from "esbuild";
+async function buildNodeRunnerBundle(options) {
+    const { entryPath, outfile, sourcefile, startupLabel, exportName, compiledRef, errorPrefix, } = options;
+    const result = await esbuild.build({
+        stdin: {
+            contents: `
+import definition from ${JSON.stringify(entryPath)};
+import { compileWorkflow } from "@reasonlayer/sdk";
+const compiled = compileWorkflow(definition, { omitEnvironments: true });
+if (!compiled.ok) {
+  throw new Error(${JSON.stringify(startupLabel)} + JSON.stringify(compiled.errors));
+}
+export const ${exportName} = compiled.${compiledRef};
+`,
+            resolveDir: new URL(".", `file://${entryPath}`).pathname,
+            sourcefile,
+            loader: "js",
+        },
+        bundle: true,
+        format: "esm",
+        platform: "node",
+        target: "node22",
+        treeShaking: true,
+        legalComments: "none",
+        external: ["@flue/runtime", "@flue/runtime/*"],
+        outfile,
+        logLevel: "silent",
+        write: true,
+    });
+    if (result.errors.length > 0) {
+        throw new Error(`${errorPrefix} failed: ${result.errors.map((e) => e.text).join("; ")}`);
+    }
+}
+/** Code bundle: re-exports compiled run functions for cloud/device runners. */
+export async function buildStepsBundle(options) {
+    await buildNodeRunnerBundle({
+        ...options,
+        sourcefile: "rl-steps-entry.js",
+        startupLabel: "workflow failed to compile at runner start: ",
+        exportName: "STEP_RUNS",
+        compiledRef: "codeRefs",
+        errorPrefix: "steps bundle",
+    });
+}
+/** Agent bundle: re-exports compiled Flue defineAgent refs; the runner owns the runtime. */
+export async function buildAgentsBundle(options) {
+    await buildNodeRunnerBundle({
+        ...options,
+        sourcefile: "rl-agents-entry.js",
+        startupLabel: "workflow failed to compile at agent runner start: ",
+        exportName: "AGENT_RUNS",
+        compiledRef: "agentRefs",
+        errorPrefix: "agent bundle",
+    });
+}

package/dist/bundler/smoke.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Build-time cold-start smoke test (spec §7.5, mechanism 3): evaluate the
+ * emitted Worker once in a subprocess with the Buffer global deleted (to
+ * match workerd) and a 10s guard against top-level-await hangs, then probe
+ * its manifest. Import-time Node use must fail the build, not every
+ * dispatch after deploy.
+ */
+export interface SmokeResult {
+    workflowId: string;
+    steps: string[];
+}
+export declare function smokeTestWorker(workerPath: string): Promise<SmokeResult>;

package/dist/bundler/smoke.js

@@ -0,0 +1,70 @@
+/**
+ * Build-time cold-start smoke test (spec §7.5, mechanism 3): evaluate the
+ * emitted Worker once in a subprocess with the Buffer global deleted (to
+ * match workerd) and a 10s guard against top-level-await hangs, then probe
+ * its manifest. Import-time Node use must fail the build, not every
+ * dispatch after deploy.
+ */
+import { execFile } from "node:child_process";
+import { pathToFileURL } from "node:url";
+const CHILD_SCRIPT = `
+// Buffer is deleted for MODULE EVALUATION only — that matches workerd's
+// missing global at cold start. It is restored before the probe because
+// Node's own Request/Response (undici) needs it.
+const savedBuffer = globalThis.Buffer;
+delete globalThis.Buffer;
+const workerUrl = process.env.RL_WORKER_URL;
+const timer = setTimeout(() => {
+  console.error("worker module evaluation timed out after 10s — top-level await that never settles?");
+  process.exit(3);
+}, 10_000);
+try {
+  const mod = await import(workerUrl);
+  clearTimeout(timer);
+  globalThis.Buffer = savedBuffer;
+  const handler = mod.default && mod.default.fetch;
+  if (typeof handler !== "function") {
+    console.error("worker has no default { fetch } handler");
+    process.exit(4);
+  }
+  const res = await handler(
+    new Request("http://rl-smoke/", {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({ probe: "manifest" }),
+    }),
+  );
+  const body = await res.json();
+  if (!body || !body.manifest) {
+    console.error("manifest probe returned no manifest: " + JSON.stringify(body));
+    process.exit(5);
+  }
+  console.log(JSON.stringify(body.manifest));
+  process.exit(0);
+} catch (err) {
+  clearTimeout(timer);
+  console.error(String((err && err.stack) || err));
+  process.exit(2);
+}
+`;
+export async function smokeTestWorker(workerPath) {
+    return new Promise((resolve, reject) => {
+        const child = execFile(process.execPath, ["--input-type=module", "-e", CHILD_SCRIPT], {
+            env: { ...process.env, RL_WORKER_URL: pathToFileURL(workerPath).href },
+            timeout: 15_000,
+        }, (error, stdout, stderr) => {
+            if (error) {
+                reject(new Error(`worker cold-start smoke test failed — the Worker would crash at cold start in production.\n${stderr.trim()}`));
+                return;
+            }
+            try {
+                const manifest = JSON.parse(stdout.trim());
+                resolve(manifest);
+            }
+            catch {
+                reject(new Error(`smoke test produced unparseable output: ${stdout}`));
+            }
+        });
+        child.on("error", reject);
+    });
+}

package/dist/bundler/worker.d.ts

@@ -0,0 +1,31 @@
+/**
+ * The Workers-target build (spec §7.5): a self-contained ESM user Worker.
+ * Node builtins are stubbed to empty modules (mechanism 1) so the whole
+ * workflow module bundles even when device/sandbox-only steps use Node APIs
+ * — that code is inert behind entrypoints the Worker never calls. A
+ * process.env getter shim (banner) makes `process.env.FOO` read the
+ * per-invocation env.
+ */
+import type { Plugin } from "esbuild";
+export declare function nodeBuiltinStubPlugin(): Plugin;
+export declare function flueRuntimeWorkerStubPlugin(): Plugin;
+export interface WorkerBuildResult {
+    outfile: string;
+    bytes: number;
+}
+export declare function buildWorkerBundle(options: {
+    entryPath: string;
+    workflowId: string;
+    workerStepIds: string[];
+    outfile: string;
+}): Promise<WorkerBuildResult>;
+/** The Node-target steps bundle for sandbox/device runners (spec §7.1). */
+export declare function buildStepsBundle(options: {
+    entryPath: string;
+    outfile: string;
+}): Promise<void>;
+/** Agent bundle: re-exports compiled Flue defineAgent refs; the runner owns the runtime. */
+export declare function buildAgentsBundle(options: {
+    entryPath: string;
+    outfile: string;
+}): Promise<void>;

package/dist/bundler/worker.js

@@ -0,0 +1,214 @@
+/**
+ * The Workers-target build (spec §7.5): a self-contained ESM user Worker.
+ * Node builtins are stubbed to empty modules (mechanism 1) so the whole
+ * workflow module bundles even when device/sandbox-only steps use Node APIs
+ * — that code is inert behind entrypoints the Worker never calls. A
+ * process.env getter shim (banner) makes `process.env.FOO` read the
+ * per-invocation env.
+ */
+import { builtinModules } from "node:module";
+import * as esbuild from "esbuild";
+const BUILTINS = new Set([
+    ...builtinModules,
+    ...builtinModules.map((m) => `node:${m}`),
+]);
+export function nodeBuiltinStubPlugin() {
+    return {
+        name: "rl-node-builtin-stubs",
+        setup(build) {
+            build.onResolve({ filter: /.*/ }, (args) => {
+                if (BUILTINS.has(args.path)) {
+                    return { path: args.path, namespace: "rl-node-stub" };
+                }
+                return null;
+            });
+            build.onLoad({ filter: /.*/, namespace: "rl-node-stub" }, () => ({
+                contents: "module.exports = {};",
+                loader: "js",
+            }));
+        },
+    };
+}
+export function flueRuntimeWorkerStubPlugin() {
+    return {
+        name: "rl-flue-runtime-worker-stub",
+        setup(build) {
+            build.onResolve({ filter: /^@flue\/runtime(?:\/.*)?$/ }, (args) => ({
+                path: args.path,
+                namespace: "rl-flue-runtime-stub",
+            }));
+            build.onLoad({ filter: /.*/, namespace: "rl-flue-runtime-stub" }, () => ({
+                contents: `
+const unavailable = (name) => () => {
+  throw new Error("@flue/runtime " + name + " is not available in function-hosted Reasonlayer code steps");
+};
+
+export function defineAgent(initialize) {
+  return { __flueAgentDefinition: true, initialize };
+}
+export function createAgent(initialize) {
+  return defineAgent(initialize);
+}
+export function registerProvider() {}
+export function registerApiProvider() {}
+export function defineTool(config) {
+  return config;
+}
+export function defineSkill(config) {
+  return config;
+}
+
+export const bash = unavailable("bash");
+export const connectMcpServer = unavailable("connectMcpServer");
+export const createSandboxSessionEnv = unavailable("createSandboxSessionEnv");
+export const dispatch = unavailable("dispatch");
+export const getRun = unavailable("getRun");
+export const instrument = unavailable("instrument");
+export const invoke = unavailable("invoke");
+export const listAgents = unavailable("listAgents");
+export const listRuns = unavailable("listRuns");
+export const observe = () => () => {};
+`,
+                loader: "js",
+            }));
+        },
+    };
+}
+/**
+ * The per-invocation env shim: `process.env` resolves to the env posted with
+ * the request, reset after the call (spec §7.2 — secrets are never stored as
+ * Worker secrets).
+ */
+const PROCESS_ENV_BANNER = `const process = { get env() { return globalThis.__RL_ENV ?? {}; } };`;
+function workerEntrySource(entryPath, workflowId, workerStepIds) {
+    return `
+import definition from ${JSON.stringify(entryPath)};
+import { compileWorkflow } from "@reasonlayer/sdk";
+
+const compiled = compileWorkflow(definition, { omitEnvironments: true });
+if (!compiled.ok) {
+  throw new Error("workflow failed to compile at Worker cold start: " + JSON.stringify(compiled.errors));
+}
+const WORKER_STEPS = new Set(${JSON.stringify(workerStepIds)});
+const MANIFEST = { workflowId: ${JSON.stringify(workflowId)}, steps: ${JSON.stringify(workerStepIds)} };
+
+const json = (status, body) =>
+  new Response(JSON.stringify(body), { status, headers: { "content-type": "application/json" } });
+
+export default {
+  async fetch(request) {
+    if (request.method !== "POST") return json(405, { error: "POST only" });
+    let body;
+    try {
+      body = await request.json();
+    } catch {
+      return json(400, { error: "invalid JSON body" });
+    }
+    if (body && body.probe === "manifest") return json(200, { manifest: MANIFEST });
+
+    const { stepId, input, env } = body ?? {};
+    if (!WORKER_STEPS.has(stepId)) {
+      return json(404, {
+        status: "failed",
+        error: { message: "unknown Reasonlayer code step: " + stepId },
+      });
+    }
+    const run = compiled.codeRefs[stepId];
+    globalThis.__RL_ENV = env ?? {};
+    try {
+      const output = await run(input);
+      return json(200, { status: "succeeded", output });
+    } catch (err) {
+      return json(200, {
+        status: "failed",
+        error: { message: String(err && err.message ? err.message : err), stack: err && err.stack },
+      });
+    } finally {
+      globalThis.__RL_ENV = {};
+    }
+  },
+};
+`;
+}
+export async function buildWorkerBundle(options) {
+    const { entryPath, workflowId, workerStepIds, outfile } = options;
+    const result = await esbuild.build({
+        stdin: {
+            contents: workerEntrySource(entryPath, workflowId, workerStepIds),
+            resolveDir: new URL(".", `file://${entryPath}`).pathname,
+            sourcefile: "rl-worker-entry.js",
+            loader: "js",
+        },
+        bundle: true,
+        format: "esm",
+        platform: "browser",
+        target: "es2022",
+        treeShaking: true,
+        legalComments: "none",
+        banner: { js: PROCESS_ENV_BANNER },
+        plugins: [flueRuntimeWorkerStubPlugin(), nodeBuiltinStubPlugin()],
+        outfile,
+        logLevel: "silent",
+        write: true,
+    });
+    if (result.errors.length > 0) {
+        throw new Error(`worker bundle failed: ${result.errors.map((e) => e.text).join("; ")}`);
+    }
+    const { statSync } = await import("node:fs");
+    return { outfile, bytes: statSync(outfile).size };
+}
+/** The Node-target steps bundle for sandbox/device runners (spec §7.1). */
+async function buildNodeRunnerBundle(options) {
+    const { entryPath, outfile, sourcefile, startupLabel, exportName, compiledRef, errorPrefix, } = options;
+    const result = await esbuild.build({
+        stdin: {
+            contents: `
+import definition from ${JSON.stringify(entryPath)};
+import { compileWorkflow } from "@reasonlayer/sdk";
+const compiled = compileWorkflow(definition, { omitEnvironments: true });
+if (!compiled.ok) {
+  throw new Error(${JSON.stringify(startupLabel)} + JSON.stringify(compiled.errors));
+}
+export const ${exportName} = compiled.${compiledRef};
+`,
+            resolveDir: new URL(".", `file://${entryPath}`).pathname,
+            sourcefile,
+            loader: "js",
+        },
+        bundle: true,
+        format: "esm",
+        platform: "node",
+        target: "node22",
+        treeShaking: true,
+        legalComments: "none",
+        external: ["@flue/runtime", "@flue/runtime/*"],
+        outfile,
+        logLevel: "silent",
+        write: true,
+    });
+    if (result.errors.length > 0) {
+        throw new Error(`${errorPrefix} failed: ${result.errors.map((e) => e.text).join("; ")}`);
+    }
+}
+/** The Node-target steps bundle for sandbox/device runners (spec §7.1). */
+export async function buildStepsBundle(options) {
+    await buildNodeRunnerBundle({
+        ...options,
+        sourcefile: "rl-steps-entry.js",
+        startupLabel: "workflow failed to compile at runner start: ",
+        exportName: "STEP_RUNS",
+        compiledRef: "codeRefs",
+        errorPrefix: "steps bundle",
+    });
+}
+/** Agent bundle: re-exports compiled Flue defineAgent refs; the runner owns the runtime. */
+export async function buildAgentsBundle(options) {
+    await buildNodeRunnerBundle({
+        ...options,
+        sourcefile: "rl-agents-entry.js",
+        startupLabel: "workflow failed to compile at agent runner start: ",
+        exportName: "AGENT_RUNS",
+        compiledRef: "agentRefs",
+        errorPrefix: "agent bundle",
+    });
+}

package/dist/cli/args.d.ts

@@ -0,0 +1,9 @@
+export interface ParsedCliArgs {
+    command: string | undefined;
+    positionals: string[];
+    flags: Record<string, string | boolean>;
+}
+export declare function parseCliArgs(argv: readonly string[]): ParsedCliArgs;
+export declare function hasFlag(parsed: ParsedCliArgs, name: string): boolean;
+export declare function stringFlag(parsed: ParsedCliArgs, name: string): string | undefined;
+export declare function numberFlag(parsed: ParsedCliArgs, name: string): number | undefined;

package/dist/cli/args.js

@@ -0,0 +1,71 @@
+const BOOLEAN_FLAGS = new Set([
+    "bootstrap",
+    "disable",
+    "enable",
+    "help",
+    "json",
+    "local",
+    "no-wait",
+    "once",
+    "value-stdin",
+    "version",
+    "watch",
+    "wait",
+]);
+export function parseCliArgs(argv) {
+    let command;
+    const positionals = [];
+    const flags = {};
+    for (let i = 0; i < argv.length; i += 1) {
+        const arg = argv[i];
+        if (!command && !arg.startsWith("-")) {
+            command = arg;
+            continue;
+        }
+        if (arg === "--") {
+            positionals.push(...argv.slice(i + 1));
+            break;
+        }
+        if (!arg.startsWith("--")) {
+            positionals.push(arg);
+            continue;
+        }
+        const raw = arg.slice(2);
+        const eq = raw.indexOf("=");
+        if (eq !== -1) {
+            flags[raw.slice(0, eq)] = raw.slice(eq + 1);
+            continue;
+        }
+        if (BOOLEAN_FLAGS.has(raw)) {
+            flags[raw] = true;
+            continue;
+        }
+        const next = argv[i + 1];
+        if (next !== undefined && !next.startsWith("--")) {
+            flags[raw] = next;
+            i += 1;
+        }
+        else {
+            flags[raw] = true;
+        }
+    }
+    return { command, positionals, flags };
+}
+export function hasFlag(parsed, name) {
+    return parsed.flags[name] === true;
+}
+export function stringFlag(parsed, name) {
+    const value = parsed.flags[name];
+    if (typeof value === "string")
+        return value;
+    return undefined;
+}
+export function numberFlag(parsed, name) {
+    const value = stringFlag(parsed, name);
+    if (value === undefined)
+        return undefined;
+    const n = Number(value);
+    if (!Number.isFinite(n))
+        throw new Error(`--${name} must be a number`);
+    return n;
+}

package/dist/cli/config.d.ts

@@ -0,0 +1,38 @@
+export declare const TOKEN_ONBOARDING_HINT: string;
+/** What operations consume: a deployment URL plus a bearer token. */
+export interface RlConfig {
+    convexUrl: string;
+    token: string;
+}
+/** Non-secret account metadata persisted for user-facing diagnostics. */
+export interface RlAccount {
+    email?: string;
+    orgId?: string;
+}
+/**
+ * Global (per-user) config lives in `$HOME/.rl/config.json`. `RL_HOME`
+ * overrides the directory — production override and test isolation seam.
+ */
+export declare function globalConfigPath(): string;
+export declare function resolvedConvexUrl(): string;
+export declare function resolvedTargetLabel(): "production" | "dev override";
+export declare function loadConfig(options?: {
+    optional?: false;
+}): Promise<RlConfig>;
+export declare function loadConfig(options: {
+    optional: true;
+}): Promise<RlConfig | undefined>;
+export interface SavedLogin {
+    configPath: string;
+}
+/**
+ * Persist a successful login: token to the OS keychain, non-secret account
+ * metadata to the global config file. There is deliberately no plaintext-file
+ * fallback (spec §11) — if the keychain is unavailable we fail with guidance to
+ * use RL_TOKEN with a scoped `rl_pt_` token, which is the headless/CI path.
+ */
+export declare function saveLogin(convexUrl: string, token: string, account?: RlAccount): Promise<SavedLogin>;
+/** Remove the stored token for the currently resolved deployment. */
+export declare function clearLogin(convexUrl?: string): Promise<{
+    convexUrl: string;
+}>;

package/dist/cli/config.js

@@ -0,0 +1,94 @@
+import { mkdir, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { PRODUCTION_CONVEX_URL } from "@reasonlayer/protocol";
+import * as keychain from "./keychain.js";
+import { KeychainAccessError, KeychainUnavailableError } from "./keychain.js";
+export const TOKEN_ONBOARDING_HINT = "Create a platform token in the Reasonlayer console under Capabilities > Tokens, then " +
+    'run "rl login --token <token>". Inside the repo, run "pnpm rl login --token <token>" ' +
+    "to log in to the local dev deployment.";
+/**
+ * Global (per-user) config lives in `$HOME/.rl/config.json`. `RL_HOME`
+ * overrides the directory — production override and test isolation seam.
+ */
+export function globalConfigPath() {
+    const home = process.env["RL_HOME"];
+    return home ? join(resolve(home), "config.json") : join(homedir(), ".rl", "config.json");
+}
+async function writeConfigFile(path, file) {
+    await mkdir(dirname(path), { recursive: true, mode: 0o700 });
+    await writeFile(path, `${JSON.stringify(file, null, 2)}\n`, { mode: 0o600 });
+}
+function isKeychainError(err) {
+    return err instanceof KeychainUnavailableError || err instanceof KeychainAccessError;
+}
+export function resolvedConvexUrl() {
+    return process.env["RL_CONVEX_URL"] ?? PRODUCTION_CONVEX_URL;
+}
+export function resolvedTargetLabel() {
+    return process.env["RL_CONVEX_URL"] === undefined ? "production" : "dev override";
+}
+export async function loadConfig(options = {}) {
+    const convexUrl = resolvedConvexUrl();
+    const envToken = process.env["RL_TOKEN"];
+    if (envToken !== undefined)
+        return { convexUrl, token: envToken };
+    let token;
+    let keychainError;
+    try {
+        token = (await keychain.getToken(convexUrl)) ?? undefined;
+    }
+    catch (err) {
+        if (err instanceof KeychainAccessError)
+            keychainError = err;
+        else if (!(err instanceof KeychainUnavailableError))
+            throw err;
+    }
+    if (token !== undefined)
+        return { convexUrl, token };
+    if (options.optional)
+        return undefined;
+    // A keychain that holds the token but refused to read it is a distinct
+    // failure from "no login" — surface it rather than a misleading prompt.
+    if (keychainError) {
+        throw new Error(`${keychainError.message}. Your keychain may be locked or the access prompt was denied — ` +
+            "re-run and approve it, or set RL_TOKEN with a scoped token.");
+    }
+    throw notLoggedIn();
+}
+function notLoggedIn() {
+    return new Error(`not logged in: ${TOKEN_ONBOARDING_HINT}`);
+}
+/**
+ * Persist a successful login: token to the OS keychain, non-secret account
+ * metadata to the global config file. There is deliberately no plaintext-file
+ * fallback (spec §11) — if the keychain is unavailable we fail with guidance to
+ * use RL_TOKEN with a scoped `rl_pt_` token, which is the headless/CI path.
+ */
+export async function saveLogin(convexUrl, token, account = {}) {
+    try {
+        await keychain.setToken(convexUrl, token);
+    }
+    catch (err) {
+        if (isKeychainError(err)) {
+            throw new Error(`${err.message}. Unlock your keychain and retry, or for headless/CI use ` +
+                "RL_TOKEN with a scoped token instead of an interactive login.");
+        }
+        throw err;
+    }
+    const path = globalConfigPath();
+    const hasAccount = account.email !== undefined || account.orgId !== undefined;
+    await writeConfigFile(path, hasAccount ? { account } : {});
+    return { configPath: path };
+}
+/** Remove the stored token for the currently resolved deployment. */
+export async function clearLogin(convexUrl = resolvedConvexUrl()) {
+    try {
+        await keychain.deleteToken(convexUrl);
+    }
+    catch (err) {
+        if (!isKeychainError(err))
+            throw err;
+    }
+    return { convexUrl };
+}

package/dist/cli/convex.d.ts

@@ -0,0 +1,9 @@
+import type { RlConfig } from "./config.js";
+export declare class RlConvexClient {
+    readonly config: RlConfig;
+    private readonly client;
+    constructor(config: RlConfig);
+    query<T>(name: string, args: Record<string, unknown>): Promise<T>;
+    mutation<T>(name: string, args: Record<string, unknown>): Promise<T>;
+    action<T>(name: string, args: Record<string, unknown>): Promise<T>;
+}

package/dist/cli/convex.js

@@ -0,0 +1,25 @@
+import { ConvexHttpClient } from "convex/browser";
+import { makeFunctionReference } from "convex/server";
+function fn(kind, name) {
+    return makeFunctionReference(name);
+}
+export class RlConvexClient {
+    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);
+    }
+}

package/dist/cli/format.d.ts

@@ -0,0 +1,11 @@
+export declare function serializeCliValue(value: unknown, key?: string): unknown;
+export declare function jsonText(value: unknown): string;
+export declare function parseVariableValue(raw: string): unknown;
+export declare function formatVariableList(value: unknown): string;
+export declare function formatCompileErrors(result: {
+    errors: {
+        stepId?: string;
+        message: string;
+    }[];
+}): string;
+export declare function formatInspect(value: unknown): string;