@reasonlayer/sdk 0.0.1-rc.3

package/dist/selectors.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Proxy wiring → SelectorIR (spec §4.2). Wiring callbacks run at compile
+ * time against proxies that record property accesses; lowering turns the
+ * recorded accesses (plus plain objects/arrays/literals) into SelectorIR.
+ */
+import type { SelectorIR } from "@reasonlayer/protocol";
+/** Compile-time stand-in for a value of type T; property access is recorded, nothing else is allowed. */
+export type Wire<T> = T extends object ? {
+    [K in keyof T]: Wire<T[K]>;
+} : T;
+export declare class WiringError extends Error {
+}
+export declare function inputProxy(): unknown;
+export declare function stepProxy(stepId: string): unknown;
+export declare function variableProxy(name: string): unknown;
+export declare function mapItemProxy(): unknown;
+/**
+ * The `steps` argument handed to wiring callbacks: exposes exactly the
+ * steps declared so far — later steps are invisible (spec §4.2), and an
+ * unknown id is a compile error with the known ids listed.
+ */
+export declare function stepsProxy(knownStepIds: readonly string[]): unknown;
+/** Lower a wiring result to SelectorIR. Throws WiringError on non-serializable leaves. */
+export declare function lower(value: unknown): SelectorIR;
+export { referencedStepIds, usesMapItem } from "@reasonlayer/protocol";

package/dist/selectors.js

@@ -0,0 +1,99 @@
+/**
+ * Proxy wiring → SelectorIR (spec §4.2). Wiring callbacks run at compile
+ * time against proxies that record property accesses; lowering turns the
+ * recorded accesses (plus plain objects/arrays/literals) into SelectorIR.
+ */
+const NODE = Symbol.for("reasonlayer.selectorNode");
+export class WiringError extends Error {
+}
+function makeProxy(node) {
+    return new Proxy(Object.create(null), {
+        get(_target, prop) {
+            if (prop === NODE)
+                return node;
+            // Wiring values are opaque at compile time; block the traps that
+            // silently corrupt recording (await, spread, JSON.stringify).
+            if (prop === "then" || prop === Symbol.toPrimitive || prop === "toJSON") {
+                return undefined;
+            }
+            if (typeof prop === "symbol")
+                return undefined;
+            return makeProxy({ ...node, path: [...node.path, prop] });
+        },
+        has(_target, prop) {
+            return prop === NODE;
+        },
+        ownKeys() {
+            throw new WiringError("wiring values cannot be spread or enumerated — wire whole values or individual fields");
+        },
+        set() {
+            throw new WiringError("wiring values are read-only");
+        },
+    });
+}
+export function inputProxy() {
+    return makeProxy({ kind: "input", path: [] });
+}
+export function stepProxy(stepId) {
+    return makeProxy({ kind: "step", stepId, path: [] });
+}
+export function variableProxy(name) {
+    return makeProxy({ kind: "variable", name, path: [] });
+}
+export function mapItemProxy() {
+    return makeProxy({ kind: "mapItem", path: [] });
+}
+/**
+ * The `steps` argument handed to wiring callbacks: exposes exactly the
+ * steps declared so far — later steps are invisible (spec §4.2), and an
+ * unknown id is a compile error with the known ids listed.
+ */
+export function stepsProxy(knownStepIds) {
+    const known = new Set(knownStepIds);
+    return new Proxy(Object.create(null), {
+        get(_target, prop) {
+            if (typeof prop === "symbol")
+                return undefined;
+            if (!known.has(prop)) {
+                throw new WiringError(`unknown step "${prop}" — steps declared so far: ${knownStepIds.length > 0 ? knownStepIds.join(", ") : "(none)"}. Steps can only wire to earlier steps.`);
+            }
+            return stepProxy(prop);
+        },
+    });
+}
+function nodeOf(value) {
+    if (value === null || (typeof value !== "object" && typeof value !== "function")) {
+        return undefined;
+    }
+    return value[NODE];
+}
+function isPlainObject(value) {
+    if (value === null || typeof value !== "object")
+        return false;
+    const proto = Object.getPrototypeOf(value);
+    return proto === Object.prototype || proto === null;
+}
+/** Lower a wiring result to SelectorIR. Throws WiringError on non-serializable leaves. */
+export function lower(value) {
+    const node = nodeOf(value);
+    if (node)
+        return node;
+    if (Array.isArray(value)) {
+        return { kind: "array", items: value.map(lower) };
+    }
+    if (isPlainObject(value)) {
+        const fields = {};
+        for (const [key, field] of Object.entries(value)) {
+            fields[key] = lower(field);
+        }
+        return { kind: "object", fields };
+    }
+    if (value === null ||
+        typeof value === "string" ||
+        typeof value === "number" ||
+        typeof value === "boolean") {
+        return { kind: "literal", value };
+    }
+    throw new WiringError(`cannot wire a value of type ${typeof value} — wiring supports step/input references, plain objects, arrays, and JSON literals`);
+}
+export { referencedStepIds, usesMapItem } from "@reasonlayer/protocol";

package/dist/testkit.d.ts

@@ -0,0 +1,32 @@
+/**
+ * The workflow test kit (spec §4.6): run a compiled workflow in-process with
+ * a fake task executor — no Convex, no workflow component, no network. This
+ * consumes the same scheduling core as the Convex engine for readiness waves,
+ * map dedupe/fan-out, and output evaluation.
+ */
+export { setIntegrationTransport, type IntegrationTransport, type IntegrationTransportRequest, } from "@reasonlayer/integrations/testkit";
+import { type MapChildStepIR, type StepIR, type WorkflowIR } from "@reasonlayer/protocol";
+import type { WorkflowDefinition } from "./types.js";
+export interface TestRunOptions {
+    input: unknown;
+    /**
+     * Executes one task (code, agent, or catalog action step). Defaults to calling the
+     * workflow's own code-step functions; agent and action steps must be supplied here
+     * or via `stepOutputs`.
+     */
+    executeTask?: (step: StepIR | MapChildStepIR, input: unknown) => Promise<unknown> | unknown;
+    /** Hard overrides: step id → output. Skips execution entirely for that step. */
+    stepOutputs?: Record<string, unknown>;
+    /** Workflow-variable overrides; undeclared names and schema-invalid values are rejected. */
+    variables?: Record<string, unknown>;
+    /** Resolves review steps; receives an output-shaped draft and returns its approved or edited value. */
+    onReview?: (stepId: string, content: unknown) => Promise<unknown> | unknown;
+}
+export interface TestRunResult {
+    output: unknown;
+    stepOutputs: Record<string, unknown>;
+    /** Step ids in the order they completed (waves are deterministic: declaration order within a wave). */
+    completionOrder: string[];
+}
+export declare function runWorkflowTest(definition: WorkflowDefinition, options: TestRunOptions): Promise<TestRunResult>;
+export declare function runCompiledWorkflowTest(ir: WorkflowIR, codeRefs: Record<string, (input: never) => unknown>, options: TestRunOptions): Promise<TestRunResult>;

package/dist/testkit.js

@@ -0,0 +1,161 @@
+/**
+ * The workflow test kit (spec §4.6): run a compiled workflow in-process with
+ * a fake task executor — no Convex, no workflow component, no network. This
+ * consumes the same scheduling core as the Convex engine for readiness waves,
+ * map dedupe/fan-out, and output evaluation.
+ */
+export { setIntegrationTransport, } from "@reasonlayer/integrations/testkit";
+import { collapseMapChildren, evaluateStepInput, evaluateWorkflowOutput, expandMapStep, readySteps, validateAgainstSchema, } from "@reasonlayer/protocol";
+import { compileWorkflow } from "./compile.js";
+export async function runWorkflowTest(definition, options) {
+    const compiled = compileWorkflow(definition);
+    if (!compiled.ok) {
+        throw new Error(`workflow does not compile:\n${compiled.errors
+            .map((e) => `  ${e.stepId ? `[${e.stepId}] ` : ""}${e.message}`)
+            .join("\n")}`);
+    }
+    return runCompiledWorkflowTest(compiled.ir, compiled.codeRefs, options);
+}
+export async function runCompiledWorkflowTest(ir, codeRefs, options) {
+    const variables = resolveTestVariables(ir, options.variables);
+    const selectorVariables = variables !== undefined ? { variables } : {};
+    const outputs = { ...options.stepOutputs };
+    const completionOrder = [];
+    const stepById = new Map(Object.values(ir.steps).map((step) => [step.id, step]));
+    for (const [stepId, output] of Object.entries(outputs)) {
+        const step = stepById.get(stepId);
+        if (!step)
+            throw new Error(`unknown stepOutputs key "${stepId}"`);
+        validateStepOutput(step, output);
+    }
+    const executeTask = options.executeTask ??
+        ((step, input) => {
+            if (step.kind === "code") {
+                const run = codeRefs[step.id];
+                if (!run)
+                    throw new Error(`no code ref for step "${step.id}"`);
+                return run(input);
+            }
+            throw new Error(`step "${step.id}" is an ${step.kind} step — supply executeTask or a stepOutputs override`);
+        });
+    const runStep = async (step) => {
+        switch (step.kind) {
+            case "code":
+            case "agent":
+            case "action": {
+                const input = evaluateStepInput(step, { input: options.input, stepOutputs: outputs, ...selectorVariables });
+                return executeTask(step, input);
+            }
+            case "review": {
+                const content = evaluateStepInput(step, { input: options.input, stepOutputs: outputs, ...selectorVariables });
+                if (!options.onReview) {
+                    throw new Error(`review step "${step.id}" reached but no onReview handler supplied`);
+                }
+                return options.onReview(step.id, content);
+            }
+            case "map": {
+                const children = [];
+                for (const { key, item, childIndex } of expandMapStep(step, {
+                    input: options.input,
+                    stepOutputs: outputs,
+                    ...selectorVariables,
+                })) {
+                    const childInput = evaluateStepInput(step.step, {
+                        input: options.input,
+                        stepOutputs: outputs,
+                        mapItem: item,
+                        ...selectorVariables,
+                    });
+                    let output;
+                    if (step.step.kind === "review") {
+                        if (!options.onReview) {
+                            throw new Error(`review child of "${step.id}" reached but no onReview handler`);
+                        }
+                        output = await options.onReview(step.step.id, childInput);
+                    }
+                    else {
+                        try {
+                            output = await executeTask(step.step, childInput);
+                        }
+                        catch (err) {
+                            children.push({
+                                status: "failed",
+                                invocationKey: key,
+                                childIndex,
+                                error: err.message,
+                            });
+                            continue;
+                        }
+                    }
+                    try {
+                        validateStepOutput(step.step, output);
+                        children.push({ status: "succeeded", invocationKey: key, childIndex, output });
+                    }
+                    catch (err) {
+                        children.push({
+                            status: "failed",
+                            invocationKey: key,
+                            childIndex,
+                            error: err.message,
+                        });
+                    }
+                }
+                const collapsed = collapseMapChildren(children);
+                if (!collapsed.ok) {
+                    throw new Error(`map step "${step.id}" failed: ${collapsed.error}`);
+                }
+                return collapsed.output;
+            }
+        }
+    };
+    const stepList = Object.values(ir.steps);
+    const completed = new Set(stepList.map((s) => s.id).filter((id) => id in outputs));
+    while (completed.size < stepList.length) {
+        const wave = readySteps(ir, { outputs, startedStepIds: completed });
+        if (wave.length === 0) {
+            const pending = stepList.map((s) => s.id).filter((id) => !completed.has(id));
+            throw new Error(`no step is ready but ${pending.length} remain (${pending.join(", ")}) — dependency deadlock`);
+        }
+        for (const step of wave) {
+            outputs[step.id] = await runStep(step);
+            if (step.kind !== "map")
+                validateStepOutput(step, outputs[step.id]);
+            completionOrder.push(step.id);
+            completed.add(step.id);
+        }
+    }
+    const output = evaluateWorkflowOutput(ir, { input: options.input, stepOutputs: outputs, ...selectorVariables });
+    validateAgainstSchema(output, ir.outputSchemaJson, "workflow output");
+    return { output, stepOutputs: outputs, completionOrder };
+}
+function resolveTestVariables(ir, overrides) {
+    const declarations = ir.variables ?? [];
+    if (declarations.length === 0 && !overrides)
+        return undefined;
+    const declared = new Map(declarations.map((variable) => [variable.name, variable]));
+    const resolved = Object.create(null);
+    for (const variable of declarations)
+        resolved[variable.name] = variable.defaultJson;
+    for (const [name, value] of Object.entries(overrides ?? {})) {
+        const variable = declared.get(name);
+        if (!variable)
+            throw new Error(`unknown variable override "${name}"`);
+        validateAgainstSchema(value, variable.schemaJson, `variable "${name}" override`);
+        resolved[name] = value;
+    }
+    return resolved;
+}
+function validateStepOutput(step, output) {
+    try {
+        validateAgainstSchema(output, stepOutputSchema(step), "step output");
+    }
+    catch (err) {
+        throw new Error(`step "${step.id}" failed output validation: ${err.message}`);
+    }
+}
+function stepOutputSchema(step) {
+    if (step.kind === "map") {
+        return { type: "array", items: step.step.outputSchemaJson };
+    }
+    return step.outputSchemaJson;
+}

package/dist/types.d.ts

@@ -0,0 +1,184 @@
+import * as v from "valibot";
+import type { CatalogActionDescriptor, CatalogActionInput } from "@reasonlayer/integrations";
+import type { HostIR, JsonSchema, RetryPolicyIR, ReviewViewIR } from "@reasonlayer/protocol";
+import type { Wire } from "./selectors.js";
+export type AnySchema = v.GenericSchema<any, any>;
+export type Out<S extends AnySchema> = v.InferOutput<S>;
+export interface VariableConfig<S extends AnySchema> {
+    schema: S;
+    default: Out<S>;
+    description?: string;
+}
+export interface VariableDefinition {
+    schemaJson: JsonSchema;
+    defaultJson: unknown;
+    description?: string;
+}
+export declare function defineVariable<const S extends AnySchema>(name: string, config: VariableConfig<S>): Wire<Out<S>>;
+export declare function variableDefinitionForCompile(name: string): VariableDefinition | undefined;
+export declare function resetVariableRegistryForTests(): void;
+/** A declared secret dependency (spec §11); the value is injected as env at run time, never held in the definition. */
+export interface SecretRef {
+    readonly __rlSecret: string;
+}
+export declare function secret(name: string): SecretRef;
+/** A declared org-side placement handle (spec §4.3); source never names a physical device. */
+export interface DeviceRef {
+    readonly __rlDeviceHandle: string;
+}
+export declare function device(handle: string): DeviceRef;
+export interface ScheduleTrigger {
+    readonly __rlTrigger: "schedule";
+    readonly name: string;
+    readonly cron: string;
+    readonly timezone?: string;
+}
+export declare function schedule(name: string, config: {
+    cron: string;
+    timezone?: string;
+}): ScheduleTrigger;
+export interface EnvironmentDefinition<McpNames extends string = string> {
+    readonly __rlEnvironment: true;
+    readonly config: EnvironmentConfig;
+    readonly __rlMcpNames?: McpNames;
+}
+export interface LocalMcpServerConfig {
+    command: string;
+    transport: "http";
+    env?: Record<string, SecretRef>;
+}
+export interface RemoteMcpServerConfig {
+    url: string;
+    headers?: Record<string, SecretRef>;
+}
+export type McpServerConfig = LocalMcpServerConfig | RemoteMcpServerConfig;
+export interface EnvironmentConfig {
+    npm?: string[];
+    pip?: string[];
+    apt?: string[];
+    /** Executables to verify on PATH, e.g. apt package "ripgrep" provides binary "rg". */
+    binaries?: string[];
+    /** local source path -> absolute path inside the sandbox template */
+    files?: Record<string, string>;
+    setup?: string[];
+    mcp?: Record<string, McpServerConfig>;
+}
+export declare function defineEnvironment<const Config extends EnvironmentConfig>(config: Config): EnvironmentDefinition<Extract<keyof NonNullable<Config["mcp"]>, string>>;
+export type EnvironmentMcpName<Env extends EnvironmentDefinition> = Env extends EnvironmentDefinition<infer Name> ? Name : never;
+export declare function mcpUrl<const Env extends EnvironmentDefinition>(environment: Env, name: EnvironmentMcpName<Env>): string;
+export declare function mcpUrl(name: string): string;
+/** `steps` as seen by wiring callbacks: earlier steps only, typed by their output schemas. */
+export type StepsOf<Steps> = {
+    readonly [K in keyof Steps]: Wire<Steps[K]>;
+};
+export type InputWiring<Steps, Input, T> = (steps: StepsOf<Steps>, input: Wire<Input>) => Wire<T>;
+export interface WorkflowConfig<InS extends AnySchema, OutS extends AnySchema> {
+    id: string;
+    input: InS;
+    output: OutS;
+    description?: string;
+    secrets?: SecretRef[];
+    devices?: DeviceRef[];
+    triggers?: ScheduleTrigger[];
+}
+export interface CodeStepConfig<Steps, Input, TIn, OutS extends AnySchema> {
+    input?: InputWiring<Steps, Input, TIn>;
+    output: OutS;
+    run: (input: TIn) => Out<OutS> | Promise<Out<OutS>>;
+    host: HostIR;
+    browserProfile?: string;
+    timeoutMs?: number;
+    retries?: RetryPolicyIR;
+    secrets?: SecretRef[];
+    environment?: EnvironmentDefinition;
+}
+export interface AgentStepConfig<Steps, Input, TIn, OutS extends AnySchema> {
+    /** A Flue `defineAgent` — imported directly from @flue/runtime, never wrapped (spec §1.4). */
+    agent: unknown;
+    input?: InputWiring<Steps, Input, TIn>;
+    output: OutS;
+    tools?: readonly CatalogActionDescriptor[];
+    host: HostIR;
+    browserProfile?: string;
+    timeoutMs?: number;
+    retries?: RetryPolicyIR;
+    secrets?: SecretRef[];
+    environment?: EnvironmentDefinition;
+}
+export interface ReviewStepConfig<Steps, Input, OutS extends AnySchema> {
+    input: InputWiring<Steps, Input, NoInfer<Out<OutS>>>;
+    output: OutS;
+    view?: ReviewViewIR;
+    deadlineMs?: number;
+}
+export interface ActionStepConfig<Steps, Input, Action extends CatalogActionDescriptor> {
+    action: Action;
+    input: InputWiring<Steps, Input, CatalogActionInput<Action>>;
+    timeoutMs?: number;
+    retries?: RetryPolicyIR;
+}
+/** Child-step configs (inside map) take a composed wire VALUE, not a wiring callback (spec §4.1). */
+interface ChildExecutableStepConfig<TIn, OutS extends AnySchema> {
+    input: Wire<TIn>;
+    output: OutS;
+    host: HostIR;
+    browserProfile?: string;
+    timeoutMs?: number;
+    retries?: RetryPolicyIR;
+    secrets?: SecretRef[];
+    environment?: EnvironmentDefinition;
+}
+export interface ChildCodeStepConfig<TIn, OutS extends AnySchema> extends ChildExecutableStepConfig<TIn, OutS> {
+    run: (input: TIn) => Out<OutS> | Promise<Out<OutS>>;
+}
+export interface ChildAgentStepConfig<TIn, OutS extends AnySchema> extends ChildExecutableStepConfig<TIn, OutS> {
+    agent: unknown;
+    tools?: readonly CatalogActionDescriptor[];
+}
+export interface ChildReviewStepConfig<OutS extends AnySchema> {
+    input: Wire<NoInfer<Out<OutS>>>;
+    output: OutS;
+    view?: ReviewViewIR;
+    deadlineMs?: number;
+}
+/** Built by the standalone code/agent/review constructors. */
+export interface ChildStepDef<OutS extends AnySchema = AnySchema> {
+    readonly __rlChildStep: "code" | "agent" | "review";
+    readonly config: ChildCodeStepConfig<any, OutS> | ChildAgentStepConfig<any, OutS> | ChildReviewStepConfig<OutS>;
+}
+export interface MapStepConfig<Steps, Input, Item, ChildOutS extends AnySchema> {
+    over: InputWiring<Steps, Input, Item[]>;
+    /** Per-item identity for dedupe + resume (spec §4.1); must select a string off the item. */
+    key: (item: Wire<Item>) => Wire<string>;
+    step: (item: Wire<Item>) => ChildStepDef<ChildOutS>;
+    concurrency?: number;
+    retries?: RetryPolicyIR;
+}
+/** Internal accumulated step record; wiring callbacks run at compile time. */
+export interface InternalStepDef {
+    kind: "code" | "agent" | "review" | "action" | "map";
+    id: string;
+    config: unknown;
+}
+export interface WorkflowDefinition<Input = unknown, Output = unknown> {
+    readonly __rlWorkflow: true;
+    readonly config: WorkflowConfig<AnySchema, AnySchema>;
+    readonly steps: readonly InternalStepDef[];
+    readonly outputWiring: (steps: unknown, input: unknown) => unknown;
+}
+export interface CompileError {
+    stepId?: string;
+    message: string;
+}
+export type CompileResult = {
+    ok: true;
+    ir: import("@reasonlayer/protocol").WorkflowIR;
+    /** stepId → the concrete run function the bundler emits into steps.js. */
+    codeRefs: Record<string, (input: never) => unknown>;
+    /** stepId → the concrete defineAgent the bundler emits into agents.js. */
+    agentRefs: Record<string, unknown>;
+} | {
+    ok: false;
+    errors: CompileError[];
+};
+export {};

package/dist/types.js

@@ -0,0 +1,110 @@
+import * as v from "valibot";
+import { toJsonSchema } from "@valibot/to-json-schema";
+import { VARIABLE_NAME_PATTERN, mcpUrlEnvName, stableJson, } from "@reasonlayer/protocol";
+import { variableProxy } from "./selectors.js";
+const VARIABLE_REGISTRY = Symbol.for("reasonlayer.variableRegistry");
+const globals = globalThis;
+const variableRegistry = (() => {
+    const existing = globals[VARIABLE_REGISTRY];
+    if (existing instanceof Map)
+        return existing;
+    const registry = new Map();
+    globals[VARIABLE_REGISTRY] = registry;
+    return registry;
+})();
+const MAX_VARIABLE_JSON_LENGTH = 16 * 1024;
+export function defineVariable(name, config) {
+    if (!VARIABLE_NAME_PATTERN.test(name)) {
+        throw new Error(`variable name "${name}" must match ${VARIABLE_NAME_PATTERN}`);
+    }
+    let parsed;
+    try {
+        parsed = v.parse(config.schema, config.default);
+    }
+    catch (error) {
+        throw new Error(`variable "${name}" default does not match schema — ${error.message}`);
+    }
+    let schemaJson;
+    try {
+        schemaJson = toJsonSchema(config.schema);
+    }
+    catch (error) {
+        throw new Error(`variable "${name}" schema cannot convert to JSON Schema — ${error.message}`);
+    }
+    let serialized;
+    try {
+        const json = JSON.stringify(parsed);
+        if (json === undefined)
+            throw new Error("value is not JSON-serializable");
+        serialized = json;
+    }
+    catch (error) {
+        throw new Error(`variable "${name}" default is not JSON-serializable — ${error.message}`);
+    }
+    if (serialized.length > MAX_VARIABLE_JSON_LENGTH) {
+        throw new Error(`variable "${name}" default exceeds the 16KB serialized limit`);
+    }
+    const defaultJson = JSON.parse(serialized);
+    try {
+        v.parse(config.schema, defaultJson);
+    }
+    catch (error) {
+        throw new Error(`variable "${name}" default changes during JSON serialization — ${error.message}`);
+    }
+    const definition = {
+        schemaJson,
+        defaultJson,
+        ...(config.description !== undefined ? { description: config.description } : {}),
+    };
+    const existing = variableRegistry.get(name);
+    if (existing) {
+        if (stableJson(existing) !== stableJson(definition)) {
+            throw new Error(`variable "${name}" is already defined with a different configuration`);
+        }
+    }
+    else {
+        variableRegistry.set(name, definition);
+    }
+    return variableProxy(name);
+}
+export function variableDefinitionForCompile(name) {
+    return variableRegistry.get(name);
+}
+export function resetVariableRegistryForTests() {
+    variableRegistry.clear();
+}
+export function secret(name) {
+    if (!name)
+        throw new Error("secret() requires a name");
+    return { __rlSecret: name };
+}
+export function device(handle) {
+    if (!handle)
+        throw new Error("device() requires a handle");
+    return { __rlDeviceHandle: handle };
+}
+export function schedule(name, config) {
+    if (!name)
+        throw new Error("schedule() requires a name");
+    if (!config.cron.trim())
+        throw new Error("schedule() requires a cron expression");
+    return {
+        __rlTrigger: "schedule",
+        name,
+        cron: config.cron,
+        ...(config.timezone !== undefined ? { timezone: config.timezone } : {}),
+    };
+}
+export function defineEnvironment(config) {
+    return { __rlEnvironment: true, config };
+}
+export function mcpUrl(environmentOrName, maybeName) {
+    const name = typeof environmentOrName === "string" ? environmentOrName : maybeName;
+    if (!name)
+        throw new Error("mcpUrl() requires an MCP server name");
+    const key = mcpUrlEnvName(name);
+    const value = process.env[key];
+    if (!value)
+        throw new Error(`MCP server "${name}" is not available in this task`);
+    return value;
+}