runline 0.18.0 → 0.20.0

package/dist/core/engine.d.ts

@@ -9,6 +9,30 @@ export interface EngineOptions {
     timeoutMs?: number;
     memoryLimitBytes?: number;
 }
+/**
+ * One resolved action call, observed at the engine's dispatch point.
+ *
+ * Fired only around `action.execute()` — an unknown path or a failed
+ * input validation throws before plugin code runs and is not an
+ * invocation. `error` is the thrown value, unmodified, when execute
+ * rejected; the hook sees it in the host process even though the
+ * worker only ever receives the message string.
+ */
+export interface ActionInvocation {
+    plugin: string;
+    action: string;
+    /** The full callable path, "plugin.action". */
+    path: string;
+    durationMs: number;
+    error?: unknown;
+}
+export interface EngineHooks {
+    /**
+     * Observer for every action invocation. Must not throw — but if it
+     * does, the engine swallows it: observability never breaks a run.
+     */
+    onAction?: (info: ActionInvocation) => void;
+}
 /**
  * Whether to arm the host-side RSS watchdog for a worker run.
  *
@@ -48,9 +72,10 @@ export declare function shouldArmRssWatchdog(versions?: Partial<Record<string, s
 export declare class ExecutionEngine {
     private registry;
     private config;
+    private hooks;
     private pooled;
     private readonly maxRunsPerWorker;
-    constructor(registry: PluginRegistry, config: RunlineConfig);
+    constructor(registry: PluginRegistry, config: RunlineConfig, hooks?: EngineHooks);
     /** Retire the pooled worker, if any. Safe to call repeatedly. */
     dispose(): void;
     /**
@@ -71,6 +96,7 @@ export declare class ExecutionEngine {
     private release;
     execute(code: string, options?: EngineOptions): Promise<ExecuteResult>;
     private invokeAction;
+    private fireOnAction;
     /**
      * A miss on "salesforce.status" is often a plugin that registered
      * its action name with the plugin prefix ("salesforce.status" inside

package/dist/core/engine.js

@@ -1,5 +1,5 @@
 import { randomUUID } from "node:crypto";
-import { readFileSync } from "node:fs";
+import { createRequire } from "node:module";
 import { Worker } from "node:worker_threads";
 import { applyEnvOverrides, updateConnectionConfig } from "../config/loader.js";
 import { formatValidationError, helpInputs, isTypedInputSchema, validateTypedInput, } from "../plugin/schema.js";
@@ -81,11 +81,13 @@ const RSS_WATCHDOG_SLACK_BYTES = 128 * 1024 * 1024;
 export class ExecutionEngine {
     registry;
     config;
+    hooks;
     pooled = null;
     maxRunsPerWorker;
-    constructor(registry, config) {
+    constructor(registry, config, hooks = {}) {
         this.registry = registry;
         this.config = config;
+        this.hooks = hooks;
         this.maxRunsPerWorker =
             config.maxRunsPerWorker ?? DEFAULT_MAX_RUNS_PER_WORKER;
     }
@@ -320,7 +322,35 @@ export class ExecutionEngine {
                 throw new Error(formatValidationError(path, validation));
             }
         }
-        return action.execute(args, ctx);
+        const started = performance.now();
+        try {
+            const value = await action.execute(args, ctx);
+            this.fireOnAction(plugin.name, action.name, path, started, false);
+            return value;
+        }
+        catch (err) {
+            // `failed` is a flag, not `error !== undefined` — a plugin that
+            // does `throw undefined` still failed.
+            this.fireOnAction(plugin.name, action.name, path, started, true, err);
+            throw err;
+        }
+    }
+    fireOnAction(pluginName, actionName, path, started, failed, error) {
+        const onAction = this.hooks.onAction;
+        if (!onAction)
+            return;
+        try {
+            onAction({
+                plugin: pluginName,
+                action: actionName,
+                path,
+                durationMs: performance.now() - started,
+                ...(failed ? { error: error ?? new Error("Unknown error") } : {}),
+            });
+        }
+        catch {
+            // Observability never breaks a run.
+        }
     }
     /**
      * A miss on "salesforce.status" is often a plugin that registered
@@ -385,14 +415,12 @@ function formatError(cause) {
     }
     return String(cause);
 }
-// MiniSearch UMD bundle, vendored at the package root and inlined into the
-// worker source. Inside the worker it is evaluated in a local scope with a
-// fresh `module`/`exports` pair so the UMD takes its CommonJS branch.
-//
-// `../../vendor/...` resolves identically from src/core/engine.ts (dev) and
-// dist/core/engine.js (published) because tsc preserves the `core/` subdir.
-// See vendor/README.md for the upgrade procedure.
-const minisearchSource = readFileSync(new URL("../../vendor/minisearch.umd.js", import.meta.url), "utf8");
+// ferrosearch is a Rust native addon, so unlike the old minisearch UMD it
+// cannot be inlined into the worker source as text. Resolve its entry point
+// host-side and require it by absolute path inside the worker: eval'd worker
+// code gets a cwd-relative `require`, so a bare specifier would resolve
+// against the caller's cwd instead of runline's own node_modules.
+const ferrosearchPath = createRequire(import.meta.url).resolve("@shift-labs/ferrosearch");
 function buildHelpData(plugins) {
     const data = {};
     for (const p of plugins) {
@@ -432,7 +460,7 @@ function buildWorkerSource(pluginNames = [], helpData = {}) {
         "console",
         "fetch",
         "require",
-        "MiniSearch",
+        "FerroSearch",
     ];
     const wrapped = `"use strict";
 const { parentPort: __port } = require("node:worker_threads");
@@ -522,14 +550,11 @@ const __fmtErr = (e) => {
 // structured-clone-safe and preserves JSON value semantics.
 const __toJson = (v) => v === undefined ? undefined : JSON.parse(JSON.stringify(v));
 
-// Inlined MiniSearch UMD, evaluated with a local module/exports so the UMD
-// takes its CommonJS branch regardless of the worker's module scope.
-const MiniSearch = (function () {
-  const module = { exports: {} };
-  const exports = module.exports;
-  ${minisearchSource}
-  return module.exports;
-})();
+// ferrosearch native addon, resolved to an absolute path by the host. Its
+// index memory lives outside the V8 heap, which is the point — minisearch's
+// JS index counted against maxOldGenerationSizeMb and grew worker RSS — but
+// also means an index built by agent code is invisible to that limit.
+const { FerroSearch } = require(${JSON.stringify(ferrosearchPath)});
 
 const __help = ${JSON.stringify(helpData)};
 
@@ -563,7 +588,7 @@ const __formatSignature = (plugin, entry) => {
   return plugin + '.' + entry.action + (fields ? '({ ' + fields + ' })' : '()');
 };
 
-// Build a MiniSearch index over every action path. Indexed at worker
+// Build a FerroSearch index over every action path. Indexed at worker
 // startup, queried by actions.find().
 const __search = (() => {
   const docs = [];
@@ -577,7 +602,7 @@ const __search = (() => {
       description: entry.description || '',
     });
   }
-  const ms = new MiniSearch({
+  const index = new FerroSearch({
     fields: ['path', 'plugin', 'action', 'description'],
     storeFields: ['path', 'description'],
     searchOptions: {
@@ -586,8 +611,8 @@ const __search = (() => {
       boost: { path: 3, action: 2, plugin: 2 },
     },
   });
-  ms.addAll(docs);
-  return ms;
+  index.addAll(docs);
+  return index;
 })();
 
 const __actionsApi = {
@@ -813,7 +838,7 @@ const __injectValues = __injectNames.map((n) => {
     case "console": return console;
     case "fetch": return fetch;
     case "require": return __bodyRequire;
-    case "MiniSearch": return MiniSearch;
+    case "FerroSearch": return FerroSearch;
     default: return __makeProxy([n]);
   }
 });

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 export { addConnection, findConfigDir, getConnection, loadConfig, removeConnection, saveConfig, updateConnectionConfig, } from "./config/loader.js";
 export type { RunlineConfig } from "./config/types.js";
 export { DEFAULT_CONFIG } from "./config/types.js";
-export type { EngineOptions, ExecuteResult } from "./core/engine.js";
+export type { ActionInvocation, EngineHooks, EngineOptions, ExecuteResult, } from "./core/engine.js";
 export { ExecutionEngine } from "./core/engine.js";
 export type { BuildAuthUrlOptions, ExchangeCodeOptions, OAuthTokens, PKCEPair, RunOAuthOptions, } from "./core/oauth.js";
 export { buildAuthUrl, exchangeAuthCode, generatePKCE, OAUTH_CALLBACK_PORT, OAUTH_CALLBACK_URI, runOAuth, } from "./core/oauth.js";

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

@@ -1,6 +1,7 @@
 import * as t from "typebox";
 import { registerIssueViewActions } from "./issue-views.js";
 import { registerIssueActions } from "./issues.js";
+import { registerObjectActions } from "./objects.js";
 import { registerPageActions } from "./pages.js";
 import { registerProjectActions } from "./projects.js";
 import { registerTranscriptionActions } from "./transcription.js";
@@ -8,18 +9,17 @@ export default function shiftLabs(rl) {
     rl.setName("shiftLabs");
     rl.setVersion("0.1.0");
     rl.setConnectionSchema(t.Object({
+        // The API key is the tenant authority for every action; the cloud
+        // derives the organization from it (SHFT-852), so no org ID is needed.
         apiKey: t.String({
             description: "Shift Labs API key",
             env: "SHIFT_LABS_API_KEY",
         }),
-        organizationId: t.Optional(t.String({
-            description: "Shift Labs organization ID (required for transcription actions)",
-            env: "SHIFT_LABS_ORG_ID",
-        })),
     }));
     registerProjectActions(rl);
     registerIssueActions(rl);
     registerIssueViewActions(rl);
     registerPageActions(rl);
     registerTranscriptionActions(rl);
+    registerObjectActions(rl);
 }

package/dist/plugins/shiftLabs/src/objects.js

@@ -0,0 +1,249 @@
+import { openAsBlob } from "node:fs";
+import { readFile, stat, writeFile } from "node:fs/promises";
+import { basename, extname } from "node:path";
+import * as t from "typebox";
+import { enumSchema, pathSegment, request } from "./shared.js";
+const OBJECTS_BASE = "/v1/services/objects";
+export const OBJECT_STATUS = ["pending_upload", "ready", "archived"];
+export const OBJECT_LINK_TARGET = [
+    "session",
+    "artifact",
+    "eval_case",
+    "db_record",
+];
+/** Mirrors the public service contract's 5 GiB object ceiling. */
+const MAX_OBJECT_BYTES = 5 * 1024 * 1024 * 1024;
+const STRICT_OBJECT = { additionalProperties: false };
+const Id = t.String({ minLength: 1, pattern: "\\S" });
+const MEDIA_TYPES = {
+    csv: "text/csv",
+    doc: "application/msword",
+    docx: "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+    gif: "image/gif",
+    html: "text/html",
+    jpeg: "image/jpeg",
+    jpg: "image/jpeg",
+    json: "application/json",
+    md: "text/markdown",
+    mp3: "audio/mpeg",
+    mp4: "video/mp4",
+    pdf: "application/pdf",
+    png: "image/png",
+    txt: "text/plain",
+    wav: "audio/wav",
+    webp: "image/webp",
+    xlsx: "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+    zip: "application/zip",
+};
+function mediaTypeFor(path, override) {
+    if (override)
+        return override;
+    return (MEDIA_TYPES[extname(path).slice(1).toLowerCase()] ??
+        "application/octet-stream");
+}
+async function fileBody(path, sizeBytes) {
+    try {
+        return await openAsBlob(path);
+    }
+    catch {
+        // Runtimes without fs.openAsBlob fall back to buffering; refuse to
+        // buffer files that would strain the host process.
+        if (sizeBytes > 512 * 1024 * 1024) {
+            throw new Error("This runtime cannot stream uploads and the file is too large to buffer.");
+        }
+        return await readFile(path);
+    }
+}
+function linkSchema() {
+    return t.Object({
+        targetType: enumSchema("Link target type", OBJECT_LINK_TARGET),
+        targetId: t.String({
+            minLength: 1,
+            maxLength: 500,
+            pattern: "\\S",
+            description: "Target ID; db_record targets use source_system/table/row style ids, e.g. R2M_Sys/GoodsReceiptLog/42",
+        }),
+        role: t.Optional(t.String({
+            minLength: 1,
+            maxLength: 200,
+            pattern: "\\S",
+            description: "Link role, e.g. source",
+        })),
+    }, STRICT_OBJECT);
+}
+const provenanceFields = {
+    workspaceId: t.Optional(Id),
+    sessionId: t.Optional(Id),
+    artifactId: t.Optional(Id),
+};
+export function registerObjectActions(rl) {
+    rl.registerAction("object.upload", {
+        access: "write",
+        description: "Persist a local binary file (image, PDF, document, export) in the " +
+            "organization's durable object bucket. Uploads through a short-lived " +
+            "signed grant and returns the ready object with its stable ID — use " +
+            "that ID as a durable sourceObjectId in DB rows and artifact links.",
+        inputSchema: t.Object({
+            path: t.String({
+                minLength: 1,
+                pattern: "\\S",
+                description: "Host path of the file to store",
+            }),
+            contentType: t.Optional(t.String({
+                minLength: 1,
+                maxLength: 200,
+                pattern: "\\S",
+                description: "Explicit MIME type; inferred from the extension when omitted",
+            })),
+            filename: t.Optional(t.String({
+                minLength: 1,
+                maxLength: 500,
+                pattern: "\\S",
+                description: "Original filename; defaults to the path's basename",
+            })),
+            metadata: t.Optional(t.Record(t.String(), t.Unknown(), {
+                description: "Small caller-defined metadata object",
+            })),
+            ...provenanceFields,
+        }, STRICT_OBJECT),
+        async execute(input, ctx) {
+            const fields = input;
+            const contentType = mediaTypeFor(fields.path, fields.contentType);
+            const file = await stat(fields.path);
+            if (!file.isFile())
+                throw new Error(`${fields.path} is not a file`);
+            if (file.size === 0)
+                throw new Error("File is empty");
+            if (file.size > MAX_OBJECT_BYTES) {
+                throw new Error(`File is larger than the ${MAX_OBJECT_BYTES}-byte service limit`);
+            }
+            const created = await request(ctx, `${OBJECTS_BASE}/objects`, {
+                method: "POST",
+                // The API key is the tenant authority; no organizationId is sent.
+                body: JSON.stringify({
+                    contentType,
+                    sizeBytes: file.size,
+                    filename: fields.filename ?? basename(fields.path),
+                    workspaceId: fields.workspaceId,
+                    sessionId: fields.sessionId,
+                    artifactId: fields.artifactId,
+                    metadata: fields.metadata,
+                }),
+            });
+            const uploadHeaders = new Headers(created.upload.headers);
+            if (!uploadHeaders.has("content-type")) {
+                uploadHeaders.set("content-type", contentType);
+            }
+            const upload = await fetch(created.upload.url, {
+                method: created.upload.method,
+                headers: uploadHeaders,
+                body: await fileBody(fields.path, file.size),
+            });
+            if (!upload.ok) {
+                throw new Error(`Object upload failed: HTTP ${upload.status}`);
+            }
+            return request(ctx, `${OBJECTS_BASE}/objects/${pathSegment(created.object.id)}/complete`, { method: "POST" });
+        },
+    });
+    rl.registerAction("object.list", {
+        access: "read",
+        description: "List stored objects, newest first. Archived objects appear only " +
+            "when filtered for by status.",
+        inputSchema: t.Object({
+            status: t.Optional(enumSchema("Object status", OBJECT_STATUS)),
+            contentType: t.Optional(t.String({ minLength: 1, maxLength: 200, pattern: "\\S" })),
+            ...provenanceFields,
+        }, STRICT_OBJECT),
+        async execute(input, ctx) {
+            const params = new URLSearchParams();
+            for (const [key, value] of Object.entries(input)) {
+                if (value !== undefined)
+                    params.set(key, String(value));
+            }
+            const query = params.toString();
+            const body = await request(ctx, `${OBJECTS_BASE}/objects${query ? `?${query}` : ""}`);
+            return body.objects;
+        },
+    });
+    rl.registerAction("object.get", {
+        access: "read",
+        description: "Get a stored object's metadata by ID.",
+        inputSchema: t.Object({ id: Id }, STRICT_OBJECT),
+        async execute(input, ctx) {
+            const { id } = input;
+            return request(ctx, `${OBJECTS_BASE}/objects/${pathSegment(id)}`);
+        },
+    });
+    rl.registerAction("object.download", {
+        access: "read",
+        description: "Mint a short-lived signed download URL for a ready object. Set " +
+            "savePath to also download the bytes to a host file.",
+        inputSchema: t.Object({
+            id: Id,
+            savePath: t.Optional(t.String({
+                minLength: 1,
+                pattern: "\\S",
+                description: "Host path to write the downloaded bytes to",
+            })),
+        }, STRICT_OBJECT),
+        async execute(input, ctx) {
+            const fields = input;
+            const grant = await request(ctx, `${OBJECTS_BASE}/objects/${pathSegment(fields.id)}/download`, {
+                method: "POST",
+            });
+            if (!fields.savePath)
+                return grant;
+            const response = await fetch(grant.url, { method: grant.method });
+            if (!response.ok) {
+                throw new Error(`Object download failed: HTTP ${response.status}`);
+            }
+            const bytes = Buffer.from(await response.arrayBuffer());
+            await writeFile(fields.savePath, bytes);
+            return { savedTo: fields.savePath, sizeBytes: bytes.byteLength };
+        },
+    });
+    rl.registerAction("object.attach", {
+        access: "write",
+        description: "Link an object to what produced or consumed it: a session, " +
+            "artifact, eval case, or customer DB record. Links are append-only " +
+            "provenance; duplicates are rejected.",
+        inputSchema: t.Object({
+            id: Id,
+            links: t.Array(linkSchema(), { minItems: 1, maxItems: 20 }),
+        }, STRICT_OBJECT),
+        async execute(input, ctx) {
+            const fields = input;
+            const body = await request(ctx, `${OBJECTS_BASE}/objects/${pathSegment(fields.id)}/links`, { method: "POST", body: JSON.stringify({ links: fields.links }) });
+            return body.links;
+        },
+    });
+    rl.registerAction("object.links", {
+        access: "read",
+        description: "List an object's provenance links.",
+        inputSchema: t.Object({ id: Id }, STRICT_OBJECT),
+        async execute(input, ctx) {
+            const { id } = input;
+            const body = await request(ctx, `${OBJECTS_BASE}/objects/${pathSegment(id)}/links`);
+            return body.links;
+        },
+    });
+    rl.registerAction("object.archive", {
+        access: "write",
+        description: "Archive a stored object (idempotent). Archived objects drop out of " +
+            "default listings and refuse download grants; nothing is deleted.",
+        inputSchema: t.Object({ id: Id }, STRICT_OBJECT),
+        async execute(input, ctx) {
+            const { id } = input;
+            return request(ctx, `${OBJECTS_BASE}/objects/${pathSegment(id)}/archive`, { method: "POST" });
+        },
+    });
+    rl.registerAction("object.bucket", {
+        access: "read",
+        description: "Get the organization's durable object bucket, provisioning it on " +
+            "first use.",
+        inputSchema: t.Object({}, STRICT_OBJECT),
+        async execute(_input, ctx) {
+            return request(ctx, `${OBJECTS_BASE}/bucket`);
+        },
+    });
+}

package/dist/plugins/shiftLabs/src/transcription.js

@@ -25,13 +25,6 @@ const MAX_MEDIA_BYTES = 5 * 1024 * 1024 * 1024;
 const MAX_TRANSCRIPT_BYTES = 2 * 1024 * 1024;
 const STRICT_OBJECT = { additionalProperties: false };
 const Id = t.String({ minLength: 1, pattern: "\\S" });
-function organizationId(ctx) {
-    const value = ctx.connection.config.organizationId;
-    if (typeof value !== "string" || !value) {
-        throw new Error("SHIFT_LABS_ORG_ID is not set. Transcription actions need the organization ID that owns the API key.");
-    }
-    return value;
-}
 function mediaTypeFor(path) {
     const mediaType = MEDIA_TYPES[extname(path).slice(1).toLowerCase()];
     if (!mediaType) {
@@ -83,7 +76,6 @@ export function registerTranscriptionActions(rl) {
         }, STRICT_OBJECT),
         async execute(input, ctx) {
             const fields = input;
-            const org = organizationId(ctx);
             const contentType = mediaTypeFor(fields.path);
             const file = await stat(fields.path);
             if (!file.isFile())
@@ -95,8 +87,8 @@ export function registerTranscriptionActions(rl) {
             }
             const created = await request(ctx, "/v1/services/transcription/assets", {
                 method: "POST",
+                // The API key is the tenant authority; no organizationId is sent.
                 body: JSON.stringify({
-                    organizationId: org,
                     contentType,
                     sizeBytes: file.size,
                 }),
@@ -117,7 +109,6 @@ export function registerTranscriptionActions(rl) {
             const job = await request(ctx, "/v1/services/transcription/jobs", {
                 method: "POST",
                 body: JSON.stringify({
-                    organizationId: org,
                     assetId: created.asset.id,
                     language: fields.language,
                     diarize: fields.diarize,
@@ -135,7 +126,7 @@ export function registerTranscriptionActions(rl) {
         description: "List transcription jobs for the API key's organization, newest first.",
         inputSchema: t.Object({}, STRICT_OBJECT),
         async execute(_input, ctx) {
-            const body = await request(ctx, `/v1/services/transcription/jobs?organizationId=${pathSegment(organizationId(ctx))}`);
+            const body = await request(ctx, "/v1/services/transcription/jobs");
             return body.jobs;
         },
     });