runline 0.26.0 → 0.27.1

package/dist/core/engine.d.ts

@@ -8,6 +8,8 @@ export interface ExecuteResult {
 export interface EngineOptions {
     timeoutMs?: number;
     memoryLimitBytes?: number;
+    /** Delivered to every action's `ctx.context` for this run. */
+    context?: unknown;
 }
 /**
  * One resolved action call, observed at the engine's dispatch point.
@@ -44,6 +46,13 @@ export interface EngineHooks {
  * ignores resourceLimits, so the watchdog is the only memory backstop.
  */
 export declare function shouldArmRssWatchdog(versions?: Partial<Record<string, string>>): boolean;
+/**
+ * Ceiling on an armed timeout: setTimeout stores its delay in an int32,
+ * so past ~24.8 days it overflows and fires at 0ms. Oversized values are
+ * rejected with an error that teaches the caller to pass 0 — the explicit
+ * "no timeout" — instead of overflowing into an instant kill.
+ */
+export declare const MAX_TIMEOUT_MS: number;
 /**
  * Executes agent code in a node:worker_threads worker.
  *

package/dist/core/engine.js

@@ -48,6 +48,13 @@ function workerShape(pluginNames, helpData, memoryLimitMb) {
 export function shouldArmRssWatchdog(versions = process.versions) {
     return Boolean(versions.bun);
 }
+/**
+ * Ceiling on an armed timeout: setTimeout stores its delay in an int32,
+ * so past ~24.8 days it overflows and fires at 0ms. Oversized values are
+ * rejected with an error that teaches the caller to pass 0 — the explicit
+ * "no timeout" — instead of overflowing into an instant kill.
+ */
+export const MAX_TIMEOUT_MS = 2 ** 31 - 1;
 // Extra slack on top of the configured memory limit for the RSS watchdog,
 // since whole-process RSS includes the host's own working set.
 const RSS_WATCHDOG_SLACK_BYTES = 128 * 1024 * 1024;
@@ -149,6 +156,16 @@ export class ExecutionEngine {
         const timeoutMs = options?.timeoutMs ?? this.config.timeoutMs;
         const memoryLimitBytes = options?.memoryLimitBytes ?? this.config.memoryLimitBytes;
         const logs = [];
+        if (!Number.isFinite(timeoutMs) ||
+            timeoutMs < 0 ||
+            timeoutMs > MAX_TIMEOUT_MS) {
+            return {
+                result: null,
+                error: `Invalid timeoutMs: ${timeoutMs}. ` +
+                    `Pass 0 (no timeout) or 1..${MAX_TIMEOUT_MS} ms.`,
+                logs,
+            };
+        }
         const plugins = this.registry.listPlugins();
         const pluginNames = plugins.map((p) => p.name);
         const helpData = buildHelpData(plugins);
@@ -190,21 +207,28 @@ export class ExecutionEngine {
                 settled = true;
                 clearTimeout(timeoutTimer);
                 clearInterval(rssTimer);
+                worker.unref?.();
                 worker.off("message", onMessage);
                 worker.off("error", onError);
                 worker.off("exit", onExit);
                 this.release(entry, pooled, retire);
                 resolve(r);
             };
+            // The acquire-time unref must not let the host exit mid-run: hold
+            // the loop for the run's duration, whether or not a timer is armed.
+            worker.ref?.();
             // A spinning body blocks the worker's event loop, so it can never be
             // asked to stop — terminate is the only remedy and the worker is gone.
-            const timeoutTimer = setTimeout(() => {
-                finish({
-                    result: null,
-                    error: `Execution timed out after ${timeoutMs}ms`,
-                    logs,
-                }, true);
-            }, timeoutMs);
+            // 0 means no timeout: the caller explicitly opted out of the backstop.
+            const timeoutTimer = timeoutMs === 0
+                ? undefined
+                : setTimeout(() => {
+                    finish({
+                        result: null,
+                        error: `Execution timed out after ${timeoutMs}ms`,
+                        logs,
+                    }, true);
+                }, timeoutMs);
             let rssTimer;
             if (shouldArmRssWatchdog()) {
                 const baselineRss = process.memoryUsage().rss;
@@ -243,7 +267,7 @@ export class ExecutionEngine {
                     logs.push(`[${msg.level}] ${msg.line}`);
                 }
                 else if (msg.t === "invoke") {
-                    this.invokeAction(msg.path, msg.args).then((value) => {
+                    this.invokeAction(msg.path, msg.args, options?.context).then((value) => {
                         let serialized;
                         try {
                             serialized = toPlainJson(value);
@@ -305,7 +329,7 @@ export class ExecutionEngine {
             reply({ t: "run", runId, body });
         });
     }
-    async invokeAction(path, rawArgs) {
+    async invokeAction(path, rawArgs, context) {
         // A call written with no arguments reaches the action as `{}`, not
         // `undefined`, so plugins can read `input.foo` without guarding.
         const args = normalizeActionInput(rawArgs);
@@ -317,6 +341,7 @@ export class ExecutionEngine {
         const connection = this.resolveConnection(plugin);
         const ctx = {
             connection,
+            context,
             log: {
                 info: (msg) => console.log(`[${plugin.name}] ${msg}`),
                 warn: (msg) => console.warn(`[${plugin.name}] ${msg}`),

package/dist/plugin/types.d.ts

@@ -51,6 +51,13 @@ export interface ConnectionConfig {
 }
 export interface ActionContext {
     connection: ConnectionConfig;
+    /**
+     * Opaque per-run value from the embedder's `execute()` options.
+     * Host-supplied and invisible to worker code, so actions may
+     * derive authority from it (e.g. per-call identity on a shared
+     * engine). Absent when the embedder passed none.
+     */
+    context?: unknown;
     log: {
         info(msg: string): void;
         warn(msg: string): void;

package/dist/sdk.d.ts

@@ -24,6 +24,8 @@ export interface RunlineOptions {
 export interface RunlineExecuteOptions {
     timeoutMs?: number;
     memoryLimitBytes?: number;
+    /** Delivered to every action's `ctx.context` for this run. */
+    context?: unknown;
 }
 export declare class Runline {
     private _registry;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "runline",
-  "version": "0.26.0",
+  "version": "0.27.1",
   "description": "Code mode for agents \u2014 turn any API or command into a callable action",
   "type": "module",
   "main": "dist/index.js",