runline 0.15.0 → 0.16.0

package/dist/core/engine.d.ts

@@ -37,5 +37,13 @@ export declare class ExecutionEngine {
     constructor(registry: PluginRegistry, config: RunlineConfig);
     execute(code: string, options?: EngineOptions): Promise<ExecuteResult>;
     private invokeAction;
+    /**
+     * A miss on "salesforce.status" is often a plugin that registered
+     * its action name with the plugin prefix ("salesforce.status" inside
+     * plugin "salesforce"), making the real path
+     * "salesforce.salesforce.status". Detect exactly that shape and
+     * teach the caller — agents read error messages and self-correct.
+     */
+    private selfPrefixHint;
     private resolveConnection;
 }

package/dist/core/engine.js

@@ -158,7 +158,7 @@ export class ExecutionEngine {
     async invokeAction(path, args) {
         const resolved = this.registry.resolveAction(path);
         if (!resolved) {
-            throw new Error(`Unknown action: ${path}`);
+            throw new Error(`Unknown action: ${path}${this.selfPrefixHint(path)}`);
         }
         const { plugin, action } = resolved;
         const connection = this.resolveConnection(plugin);
@@ -184,6 +184,25 @@ export class ExecutionEngine {
         }
         return action.execute(args, ctx);
     }
+    /**
+     * A miss on "salesforce.status" is often a plugin that registered
+     * its action name with the plugin prefix ("salesforce.status" inside
+     * plugin "salesforce"), making the real path
+     * "salesforce.salesforce.status". Detect exactly that shape and
+     * teach the caller — agents read error messages and self-correct.
+     */
+    selfPrefixHint(path) {
+        // A dot-less miss can still be the exact-name case: plugin "ping"
+        // registering action "ping" makes the callable path "ping.ping".
+        const dot = path.indexOf(".");
+        const pluginName = dot < 0 ? path : path.slice(0, dot);
+        const doubled = `${pluginName}.${path}`;
+        if (!this.registry.resolveAction(doubled))
+            return "";
+        return (`. Did you mean "${doubled}"? Plugin "${pluginName}" registered its ` +
+            `action name with the plugin prefix ("${path}"), so the full callable ` +
+            `path is "${doubled}".`);
+    }
     resolveConnection(plugin) {
         const conn = this.config.connections.find((c) => c.plugin === plugin.name);
         const base = conn ?? {

package/dist/plugin/api.js

@@ -59,14 +59,39 @@ export function createPluginAPI(pluginId) {
 export function isPluginFunction(val) {
     return typeof val === "function";
 }
+/**
+ * Action names are plugin-relative: plugin "salesforce" registering
+ * "salesforce.status" is callable as "salesforce.salesforce.status",
+ * which is almost never what the author meant. Warn at resolve time —
+ * the earliest point where both the final plugin name and the full
+ * action list are known (setName may be called after registerAction,
+ * and object exports never go through createPluginAPI).
+ */
+function warnSelfPrefixedActions(plugin) {
+    for (const action of plugin.actions) {
+        const prefixed = action.name.startsWith(`${plugin.name}.`);
+        if (!prefixed && action.name !== plugin.name)
+            continue;
+        const advice = prefixed
+            ? `Rename the action to "${action.name.slice(plugin.name.length + 1)}".`
+            : "Choose an action name that does not repeat the plugin name.";
+        console.warn(`[runline] Plugin "${plugin.name}" registered action "${action.name}", which repeats the plugin name. ` +
+            `Action names are plugin-relative, so this action is callable as "${plugin.name}.${action.name}" — ` +
+            `not "${action.name}". ${advice}`);
+    }
+}
 export function resolvePluginExport(exported, pluginId) {
     if (isPluginFunction(exported)) {
         const { api, resolve } = createPluginAPI(pluginId);
         exported(api);
-        return resolve();
+        const plugin = resolve();
+        warnSelfPrefixedActions(plugin);
+        return plugin;
     }
     if (exported && typeof exported === "object" && "actions" in exported) {
-        return exported;
+        const plugin = exported;
+        warnSelfPrefixedActions(plugin);
+        return plugin;
     }
     throw new Error(`Invalid plugin export from "${pluginId}": expected a function or { name, actions } object`);
 }

package/dist/plugins/_shared/emailJsx.js

@@ -0,0 +1,97 @@
+/**
+ * Render agent-authored React Email JSX into wire-ready email HTML
+ * plus a plain-text alternative.
+ *
+ * Why JSX instead of hand-written HTML: email-grade HTML (table
+ * layouts, inlined styles, client quirks) is exactly what agents get
+ * wrong; @react-email/components encodes that knowledge, and agents
+ * write JSX fluently. Evaluating agent-supplied JSX adds no new risk
+ * class — runline's executor is already a coding surface.
+ *
+ * All heavy dependencies (react, sucrase, react-email) are optional
+ * peers of runline — like playwright for browser actions — loaded
+ * lazily on first use. Hosts that never render JSX pay nothing;
+ * hosts without the packages get an install hint instead of a
+ * module-resolution stack trace.
+ */
+const PEER_INSTALL_HINT = "jsx email bodies require optional peer packages. Install them in the host project: " +
+    "react react-dom @react-email/components @react-email/render sucrase. " +
+    "Alternatively pass `html` or `text` instead of `jsx`.";
+let modulesPromise;
+async function loadModules() {
+    modulesPromise ??= Promise.all([
+        import("react"),
+        import("@react-email/components"),
+        import("@react-email/render"),
+        import("sucrase"),
+    ]).then(([react, components, renderMod, sucrase]) => ({
+        React: react.default ?? react,
+        components: components,
+        render: renderMod.render,
+        transform: sucrase.transform,
+    }), (err) => {
+        // Don't cache the failure — the host can install the peers and
+        // retry without restarting the process.
+        modulesPromise = undefined;
+        const msg = err instanceof Error ? err.message : String(err);
+        throw new Error(`${PEER_INSTALL_HINT} (${msg})`);
+    });
+    return modulesPromise;
+}
+/**
+ * Components become named parameters of the evaluation function, so
+ * only exports that are valid JS identifiers (the React components —
+ * capitalized) can be exposed. Lowercase utility exports are omitted
+ * on purpose: the JSX surface is components-only.
+ */
+function componentScope(components) {
+    const names = [];
+    const values = [];
+    for (const [key, value] of Object.entries(components)) {
+        if (!/^[A-Z][A-Za-z0-9_$]*$/.test(key))
+            continue;
+        names.push(key);
+        values.push(value);
+    }
+    return { names, values };
+}
+export async function renderEmailJsx(jsx) {
+    const source = jsx.trim();
+    if (!source)
+        throw new Error("jsx body is empty");
+    const { React, components, render, transform } = await loadModules();
+    let compiled;
+    try {
+        // Wrap as an expression statement so a bare `<Html>…</Html>` is a
+        // valid program for sucrase. The parentheses nudge the surface
+        // toward a single expression (statement forms like `const x = 1`
+        // fail to parse) — a shape hint, not a boundary: the executor is
+        // already a coding surface, so escaping it grants nothing.
+        compiled = transform(`__element = (${source});`, {
+            transforms: ["jsx"],
+            production: true,
+        }).code;
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        throw new Error(`jsx parse failed: ${msg}`);
+    }
+    const { names, values } = componentScope(components);
+    let element;
+    try {
+        const fn = new Function("React", ...names, `let __element; ${compiled}; return __element;`);
+        element = fn(React, ...values);
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        throw new Error(`jsx evaluation failed: ${msg}. Available components: ${names.join(", ")}`);
+    }
+    if (!React.isValidElement(element)) {
+        throw new Error("jsx must evaluate to a single React element");
+    }
+    const [html, text] = await Promise.all([
+        render(element),
+        render(element, { plainText: true }),
+    ]);
+    return { html, text };
+}

package/dist/plugins/gmail/src/index.js

@@ -21,6 +21,7 @@
  * or parsed `payload` tree for format=full).
  */
 import * as t from "typebox";
+import { renderEmailJsx } from "../../_shared/emailJsx.js";
 import { googleAccessToken } from "../../_shared/googleAuth.js";
 import { GoogleTimestamp, Id, NonEmptyString, stringEnum, } from "../../_shared/googleSchemas.js";
 // ─── Auth ────────────────────────────────────────────────────────
@@ -282,6 +283,32 @@ function normalizeAddressList(input) {
         .map((p) => (p.includes("<") && p.includes(">") ? p : `<${p}>`))
         .join(", ");
 }
+// ─── Body resolution ─────────────────────────────────────────────
+/**
+ * Resolve the outgoing body for send/reply/draft: `jsx` renders to
+ * html with a generated plain-text alternative; an explicit `text`
+ * wins over the generated fallback so every jsx email still ships
+ * multipart/alternative.
+ * Composing inputs carry no `html` field — jsx is the only HTML path
+ * (raw HTML embeds go through dangerouslySetInnerHTML inside jsx).
+ */
+async function resolveBody(p) {
+    let text = p.text;
+    let html;
+    if (typeof p.jsx === "string" && p.jsx.trim()) {
+        let rendered;
+        try {
+            rendered = await renderEmailJsx(p.jsx);
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            throw new Error(`gmail: ${msg}`);
+        }
+        html = rendered.html;
+        text ??= rendered.text;
+    }
+    return { text, html };
+}
 function findHeader(payload, name) {
     if (!payload?.headers)
         return undefined;
@@ -444,6 +471,9 @@ async function replyToMessage(ctx, messageId, p) {
     if (p.replyToSenderOnly && p.replyToRecipientsOnly) {
         throw new Error("gmail: replyToSenderOnly and replyToRecipientsOnly are mutually exclusive");
     }
+    // Render before any network round-trip so malformed jsx fails
+    // without spending Gmail API calls.
+    const { text, html } = await resolveBody(p);
     const original = (await gmailRequest(ctx, "GET", `/messages/${messageId}`, undefined, { format: "metadata", metadataHeaders: REPLY_METADATA_HEADERS }));
     const subject = findHeader(original.payload, "Subject") ?? "";
     const messageIdHeader = findHeader(original.payload, "Message-ID") ?? "";
@@ -487,8 +517,8 @@ async function replyToMessage(ctx, messageId, p) {
         subject: subject.toLowerCase().startsWith("re:")
             ? subject
             : `Re: ${subject}`,
-        text: p.text,
-        html: p.html,
+        text,
+        html,
         inReplyTo: messageIdHeader,
         references: messageIdHeader,
         attachments: p.attachments,
@@ -532,6 +562,9 @@ const Attachment = t.Object({
     contentBase64: AttachmentContent,
 }, strict);
 const Attachments = t.Array(Attachment);
+const Jsx = t.Optional(t.String({
+    description: 'React Email JSX expression rendered server-side into client-safe HTML with an auto-generated plain-text alternative — handles cross-client rendering (iOS Mail, Gmail, Outlook). For Hebrew/Arabic set dir on the root: `<Html dir="rtl" lang="he"><Container><Heading>שלום</Heading><Text>גוף ההודעה</Text><Button href="...">אישור</Button></Container></Html>`. To embed pre-rendered HTML from elsewhere: `<Html><Body><div dangerouslySetInnerHTML={{ __html: theHtml }} /></Body></Html>`.',
+}));
 const HasMessageContent = {
     anyOf: [
         {
@@ -539,8 +572,8 @@ const HasMessageContent = {
             properties: { text: { type: "string", minLength: 1, pattern: "\\S" } },
         },
         {
-            required: ["html"],
-            properties: { html: { type: "string", minLength: 1, pattern: "\\S" } },
+            required: ["jsx"],
+            properties: { jsx: { type: "string", minLength: 1, pattern: "\\S" } },
         },
         {
             required: ["attachments"],
@@ -550,7 +583,7 @@ const HasMessageContent = {
 };
 const ReplyFields = {
     text: t.Optional(t.String()),
-    html: t.Optional(t.String()),
+    jsx: Jsx,
     cc: t.Optional(t.String()),
     bcc: t.Optional(t.String()),
     replyToSenderOnly: t.Optional(t.Boolean()),
@@ -695,12 +728,12 @@ export default function gmail(rl) {
     // ── Message ───────────────────────────────────────────
     rl.registerAction("message.send", {
         access: "write",
-        description: "Send an email",
+        description: "Send an email. `text` for plain bodies; `jsx` (React Email) for formatted or RTL (Hebrew/Arabic) bodies — renders client-safe HTML with a text fallback.",
         inputSchema: t.Object({
             to: NonEmptyString,
             subject: t.String(),
             text: t.Optional(t.String({ description: "Plain body" })),
-            html: t.Optional(t.String({ description: "HTML body" })),
+            jsx: Jsx,
             cc: t.Optional(t.String()),
             bcc: t.Optional(t.String()),
             replyTo: t.Optional(t.String()),
@@ -710,6 +743,7 @@ export default function gmail(rl) {
         }, { ...strict, ...HasMessageContent }),
         async execute(input, ctx) {
             const p = (input ?? {});
+            const { text, html } = await resolveBody(p);
             const email = {
                 to: normalizeAddressList(p.to),
                 cc: normalizeAddressList(p.cc),
@@ -717,8 +751,8 @@ export default function gmail(rl) {
                 replyTo: normalizeAddressList(p.replyTo),
                 from: p.from,
                 subject: p.subject ?? "",
-                text: p.text,
-                html: p.html,
+                text,
+                html,
                 attachments: p.attachments,
             };
             const body = { raw: encodeEmail(email) };
@@ -729,7 +763,7 @@ export default function gmail(rl) {
     });
     rl.registerAction("message.reply", {
         access: "write",
-        description: "Reply to a message, preserving threadId and In-Reply-To/References headers",
+        description: "Reply to a message, preserving threadId and In-Reply-To/References headers. `text` for plain bodies; `jsx` (React Email) for formatted ones.",
         inputSchema: t.Object({ messageId: Id, ...ReplyFields }, ReplyOptions),
         async execute(input, ctx) {
             const p = (input ?? {});
@@ -943,7 +977,7 @@ export default function gmail(rl) {
     });
     rl.registerAction("thread.reply", {
         access: "write",
-        description: "Reply to the last message in a thread (convenience wrapper over message.reply)",
+        description: "Reply to the last message in a thread (convenience wrapper over message.reply). `text` for plain bodies; `jsx` (React Email) for formatted ones.",
         inputSchema: t.Object({ id: Id, ...ReplyFields }, ReplyOptions),
         async execute(input, ctx) {
             const p = (input ?? {});
@@ -958,12 +992,12 @@ export default function gmail(rl) {
     // ── Draft ─────────────────────────────────────────────
     rl.registerAction("draft.create", {
         access: "write",
-        description: "Create a draft",
+        description: "Create a draft. `text` for plain bodies; `jsx` (React Email) for formatted ones.",
         inputSchema: t.Object({
             to: t.Optional(t.String()),
             subject: t.Optional(t.String()),
             text: t.Optional(t.String()),
-            html: t.Optional(t.String()),
+            jsx: Jsx,
             cc: t.Optional(t.String()),
             bcc: t.Optional(t.String()),
             replyTo: t.Optional(t.String()),
@@ -977,6 +1011,7 @@ export default function gmail(rl) {
         async execute(input, ctx) {
             const p = (input ?? {});
             const from = p.from ?? p.fromAlias;
+            const { text, html } = await resolveBody(p);
             const email = {
                 to: normalizeAddressList(p.to) ?? "",
                 cc: normalizeAddressList(p.cc),
@@ -984,8 +1019,8 @@ export default function gmail(rl) {
                 replyTo: normalizeAddressList(p.replyTo),
                 from,
                 subject: p.subject ?? "",
-                text: p.text,
-                html: p.html,
+                text,
+                html,
                 attachments: p.attachments,
             };
             // When threading a draft, fetch the last Message-ID in the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "runline",
-  "version": "0.15.0",
+  "version": "0.16.0",
   "description": "Code mode for agents — turn any API or command into a callable action",
   "type": "module",
   "main": "dist/index.js",
@@ -63,11 +63,31 @@
     "typescript": "^5.8.0"
   },
   "peerDependencies": {
-    "playwright": "^1.57.0"
+    "@react-email/components": "^1.0.12",
+    "@react-email/render": "^2.1.0",
+    "playwright": "^1.57.0",
+    "react": "^19.2.7",
+    "react-dom": "^19.2.7",
+    "sucrase": "^3.35.1"
   },
   "peerDependenciesMeta": {
+    "@react-email/components": {
+      "optional": true
+    },
+    "@react-email/render": {
+      "optional": true
+    },
     "playwright": {
       "optional": true
+    },
+    "react": {
+      "optional": true
+    },
+    "react-dom": {
+      "optional": true
+    },
+    "sucrase": {
+      "optional": true
     }
   },
   "dependencies": {