runline 0.19.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

@@ -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

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/shiftOcr/src/index.js

@@ -0,0 +1,153 @@
+import { readFile, stat } from "node:fs/promises";
+import { extname } from "node:path";
+import * as t from "typebox";
+import { request, STRICT_OBJECT } from "../../_shared/shiftCloud.js";
+/**
+ * Shift OCR — text and structured-field extraction from images and
+ * PDFs through the Shift cloud OCR service. The API key is the tenant
+ * authority; no organization ID is ever sent (SHFT-852).
+ */
+const IMAGE_TYPES = {
+    avif: "image/avif",
+    gif: "image/gif",
+    jpeg: "image/jpeg",
+    jpg: "image/jpeg",
+    png: "image/png",
+    webp: "image/webp",
+};
+const DOCUMENT_TYPES = {
+    pdf: "application/pdf",
+};
+/**
+ * Raw-file ceiling for inlining as a base64 data URL. Base64 inflates
+ * by 4/3, so 20 MiB raw stays well inside provider request limits.
+ */
+const MAX_FILE_BYTES = 20 * 1024 * 1024;
+async function documentFromPath(path) {
+    const extension = extname(path).slice(1).toLowerCase();
+    const imageType = IMAGE_TYPES[extension];
+    const documentType = DOCUMENT_TYPES[extension];
+    if (!imageType && !documentType) {
+        throw new Error(`Unsupported file extension for ${path}. Supported: ${[
+            ...Object.keys(IMAGE_TYPES),
+            ...Object.keys(DOCUMENT_TYPES),
+        ].join(", ")}`);
+    }
+    const file = await stat(path);
+    if (!file.isFile())
+        throw new Error(`${path} is not a file`);
+    if (file.size === 0)
+        throw new Error("File is empty");
+    if (file.size > MAX_FILE_BYTES) {
+        throw new Error(`File is ${file.size} bytes; inline OCR uploads are capped at ${MAX_FILE_BYTES} bytes. Host the file and pass url instead.`);
+    }
+    const mediaType = imageType ?? documentType;
+    const url = `data:${mediaType};base64,${(await readFile(path)).toString("base64")}`;
+    return imageType
+        ? { type: "image", url }
+        : { type: "document", url, name: path.replace(/.*\//, "") };
+}
+function documentFromUrl(url, kind) {
+    if (kind)
+        return { type: kind, url };
+    // Data URLs carry their media type, not an extension.
+    if (url.startsWith("data:")) {
+        return url.startsWith("data:application/pdf")
+            ? { type: "document", url }
+            : { type: "image", url };
+    }
+    const extension = new URL(url).pathname.replace(/.*\./, "").toLowerCase();
+    return DOCUMENT_TYPES[extension]
+        ? { type: "document", url }
+        : { type: "image", url };
+}
+export default function shiftOcr(rl) {
+    rl.setName("shiftOcr");
+    rl.setVersion("0.1.0");
+    rl.setConnectionSchema(t.Object({
+        // Same Shift Labs API key as the shiftLabs plugin; the cloud
+        // derives the organization from it, so no org ID is needed.
+        apiKey: t.String({
+            description: "Shift Labs API key",
+            env: "SHIFT_LABS_API_KEY",
+        }),
+    }));
+    rl.registerAction("ocr.extract", {
+        access: "write",
+        description: "Extract markdown text — and optionally schema-constrained JSON — " +
+            "from an image or PDF. Pass a local file path (inlined as a data " +
+            "URL) or an https URL. Provide schema to get structured fields " +
+            "back instead of parsing the text yourself.",
+        inputSchema: t.Object({
+            path: t.Optional(t.String({
+                minLength: 1,
+                pattern: "\\S",
+                description: "Host path of an image or PDF (max 20 MiB)",
+            })),
+            url: t.Optional(t.String({
+                minLength: 1,
+                pattern: "\\S",
+                description: "https or data URL of the image or PDF",
+            })),
+            kind: t.Optional(t.Union([t.Literal("image"), t.Literal("document")], {
+                description: "Override for URLs whose extension does not reveal the type. " +
+                    "Inferred from the extension otherwise.",
+            })),
+            pages: t.Optional(t.String({
+                minLength: 1,
+                pattern: "^\\d+(-\\d+)?(,\\d+(-\\d+)?)*$",
+                description: "Zero-based pages for PDFs, e.g. '0', '0-5', or '0,2-4'",
+            })),
+            schema: t.Optional(t.Record(t.String(), t.Unknown(), {
+                description: "JSON schema for structured extraction across the document",
+            })),
+            schemaName: t.Optional(t.String({
+                minLength: 1,
+                pattern: "\\S",
+                description: "Extractor name for provenance. Default: extraction",
+            })),
+            prompt: t.Optional(t.String({
+                minLength: 1,
+                pattern: "\\S",
+                description: "Guidance for structured extraction; requires schema",
+            })),
+        }, STRICT_OBJECT),
+        async execute(input, ctx) {
+            const fields = input;
+            if (!fields.path === !fields.url) {
+                throw new Error("Provide exactly one of path or url");
+            }
+            if (fields.prompt && !fields.schema) {
+                throw new Error("prompt requires schema");
+            }
+            const document = fields.path
+                ? await documentFromPath(fields.path)
+                : documentFromUrl(fields.url, fields.kind);
+            return await request(ctx, "/v1/services/ocr/extract", {
+                method: "POST",
+                body: JSON.stringify({
+                    document,
+                    ...(fields.pages ? { pages: fields.pages } : {}),
+                    ...(fields.schema
+                        ? {
+                            structured: {
+                                name: fields.schemaName ?? "extraction",
+                                schema: fields.schema,
+                                ...(fields.prompt ? { prompt: fields.prompt } : {}),
+                            },
+                        }
+                        : {}),
+                }),
+            });
+        },
+    });
+    rl.registerAction("ocr.providers", {
+        access: "read",
+        description: "List the OCR providers and models available.",
+        inputSchema: t.Object({}, STRICT_OBJECT),
+        async execute(_input, ctx) {
+            const body = await request(ctx, "/v1/services/ocr/providers");
+            return body.providers;
+        },
+    });
+}

package/dist/sdk.d.ts

@@ -1,4 +1,4 @@
-import { type ExecuteResult } from "./core/engine.js";
+import { type ActionInvocation, type ExecuteResult } from "./core/engine.js";
 import type { PluginFunction } from "./plugin/api.js";
 import type { ActionAccess, ConnectionConfig, InputSchema, PluginDef } from "./plugin/types.js";
 export interface RunlineOptions {
@@ -11,6 +11,15 @@ export interface RunlineOptions {
      * `ExecutionEngine` — this bounds cross-run contamination, not memory.
      */
     maxRunsPerWorker?: number;
+    /**
+     * Observer fired in the host process for every action invocation
+     * that enters a plugin's `execute()` — unknown paths and failed
+     * input validation never reach plugin code and are not reported.
+     * Exceptions thrown by the observer are swallowed: observability
+     * never breaks a run. Not part of `RunlineConfig` on purpose —
+     * config round-trips through JSON (`fromProject`), functions do not.
+     */
+    onAction?: (info: ActionInvocation) => void;
 }
 export interface RunlineExecuteOptions {
     timeoutMs?: number;
@@ -25,6 +34,7 @@ export declare class Runline {
      * leak) a fresh worker every time — the exact bug pooling exists to fix.
      */
     private _engine;
+    private readonly _onAction;
     private constructor();
     private engine;
     /**

package/dist/sdk.js

@@ -1,7 +1,7 @@
 import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import { DEFAULT_CONFIG } from "./config/types.js";
-import { ExecutionEngine } from "./core/engine.js";
+import { ExecutionEngine, } from "./core/engine.js";
 import { resolvePluginExport } from "./plugin/api.js";
 import { discoverPlugins } from "./plugin/loader.js";
 import { PluginRegistry } from "./plugin/registry.js";
@@ -14,8 +14,10 @@ export class Runline {
      * leak) a fresh worker every time — the exact bug pooling exists to fix.
      */
     _engine = null;
+    _onAction;
     constructor(options) {
         this._registry = new PluginRegistry();
+        this._onAction = options.onAction;
         for (const pluginOrFn of options.plugins ?? []) {
             const plugin = resolvePluginExport(pluginOrFn, "unknown");
             this._registry.register(plugin);
@@ -31,7 +33,9 @@ export class Runline {
     }
     engine() {
         if (!this._engine) {
-            this._engine = new ExecutionEngine(this._registry, this._config);
+            this._engine = new ExecutionEngine(this._registry, this._config, {
+                onAction: this._onAction,
+            });
         }
         return this._engine;
     }

package/package.json

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