runline 0.19.0 → 0.21.0

package/dist/core/engine.d.ts

@@ -9,6 +9,32 @@ 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 present exactly when execute rejected: the
+ * thrown value as-is, except a nullish throw, which is substituted
+ * with an Error so failure is never mistaken for success. 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 +74,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 +98,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/shiftAtlas/src/graph.js

@@ -0,0 +1,324 @@
+import * as t from "typebox";
+import { ATLAS_BASE, cursorSchema, enumSchema, GRAPH_ACTOR_KIND, GRAPH_ASSIGNMENT_ROLE, GRAPH_BINDING_EXECUTOR, GRAPH_BINDING_STATUS, GRAPH_CHANGE_ENTITY_TYPE, GRAPH_EVIDENCE_KIND, GRAPH_JOURNEY_STATUS, GRAPH_RELATION_KIND, GRAPH_TASK_MODE, idSchema, pathSegment, request, STRICT_OBJECT, STRICT_UPDATE_OBJECT, } from "./shared.js";
+/**
+ * The operational graph behind the Atlas view: a business spec of how
+ * a company operates, in its own language. Four fixed levels — line →
+ * journey → stage → task — plus named actors, RACI assignments,
+ * level-typed relations, execution bindings, and evidence. Automation
+ * status is always derived from bindings, never declared.
+ */
+const name = (description) => t.String({ minLength: 1, maxLength: 300, pattern: "\\S", description });
+const longText = (description) => t.String({ maxLength: 5_000, description });
+const position = t.Integer({
+    minimum: 0,
+    maximum: 100_000,
+    description: "Sort position within the parent (0-based)",
+});
+const urlField = t.String({
+    minLength: 1,
+    maxLength: 2_000,
+    description: "Link URL",
+});
+const referenceField = t.String({
+    minLength: 1,
+    maxLength: 1_000,
+    pattern: "\\S",
+    description: "External reference (system-specific identifier)",
+});
+export function registerGraphActions(rl) {
+    /* -------------------------------------------------------------- */
+    /* Reads                                                          */
+    /* -------------------------------------------------------------- */
+    rl.registerAction("summary", {
+        access: "read",
+        description: "The operational graph's structure without task bodies: every " +
+            "line, journey, and stage with rollups (total/liveAi/planned/" +
+            "human counts), plus actors and level labels. Small at any org " +
+            "size; the right default read.",
+        inputSchema: t.Object({}, STRICT_OBJECT),
+        async execute(_input, ctx) {
+            const body = await request(ctx, `${ATLAS_BASE}/summary`);
+            return body.summary;
+        },
+    });
+    rl.registerAction("graph.get", {
+        access: "read",
+        description: "The entire operational graph including every task body, " +
+            "assignment, binding, and evidence. Payload grows with task " +
+            "count — prefer summary plus stage.get.",
+        inputSchema: t.Object({}, STRICT_OBJECT),
+        async execute(_input, ctx) {
+            const body = await request(ctx, `${ATLAS_BASE}/graph`);
+            return body.graph;
+        },
+    });
+    rl.registerAction("stage.get", {
+        access: "read",
+        description: "One stage in full: its ordered tasks with participants, owner, " +
+            "bindings, evidence, and derived automation status.",
+        inputSchema: t.Object({ id: idSchema("Stage ID") }, STRICT_OBJECT),
+        async execute(input, ctx) {
+            const { id } = input;
+            const body = await request(ctx, `${ATLAS_BASE}/stages/${pathSegment(id)}`);
+            return body.stage;
+        },
+    });
+    rl.registerAction("actor.list", {
+        access: "read",
+        description: "List the named workers of the graph: agents and human roles.",
+        inputSchema: t.Object({}, STRICT_OBJECT),
+        async execute(_input, ctx) {
+            const body = await request(ctx, `${ATLAS_BASE}/actors`);
+            return body.actors;
+        },
+    });
+    rl.registerAction("line.list", {
+        access: "read",
+        description: "List business lines. Every organization has one default line; " +
+            "journeys created without a lineId land there.",
+        inputSchema: t.Object({}, STRICT_OBJECT),
+        async execute(_input, ctx) {
+            const body = await request(ctx, `${ATLAS_BASE}/lines`);
+            return body.lines;
+        },
+    });
+    rl.registerAction("journey.list", {
+        access: "read",
+        description: "List journeys (id, name, outcome, status, line).",
+        inputSchema: t.Object({}, STRICT_OBJECT),
+        async execute(_input, ctx) {
+            const body = await request(ctx, `${ATLAS_BASE}/journeys`);
+            return body.journeys;
+        },
+    });
+    rl.registerAction("journey.get", {
+        access: "read",
+        description: "One journey in full: its stages, their tasks, triggers, and rollups.",
+        inputSchema: t.Object({ id: idSchema("Journey ID") }, STRICT_OBJECT),
+        async execute(input, ctx) {
+            const { id } = input;
+            const body = await request(ctx, `${ATLAS_BASE}/journeys/${pathSegment(id)}`);
+            return body.journey;
+        },
+    });
+    rl.registerAction("labels.get", {
+        access: "read",
+        description: "What this organization calls each level (line/journey/stage/task).",
+        inputSchema: t.Object({}, STRICT_OBJECT),
+        async execute(_input, ctx) {
+            const body = await request(ctx, `${ATLAS_BASE}/labels`);
+            return body.labels;
+        },
+    });
+    rl.registerAction("change.list", {
+        access: "read",
+        description: "Append-only change log of the graph, newest first, cursor-" +
+            "paginated. Returns { changes, nextCursor? }.",
+        inputSchema: t.Object({
+            entityType: t.Optional(enumSchema("Entity type", GRAPH_CHANGE_ENTITY_TYPE)),
+            entityId: t.Optional(idSchema("Entity ID")),
+            cursor: t.Optional(cursorSchema()),
+            limit: t.Optional(t.Integer({ minimum: 1, maximum: 200 })),
+        }, 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));
+            }
+            return request(ctx, `${ATLAS_BASE}/changes?${params}`);
+        },
+    });
+    /* -------------------------------------------------------------- */
+    /* Mutations — each mirrors one service input schema.             */
+    /* -------------------------------------------------------------- */
+    /**
+     * Sub-resource creates carry one routing key (journeyId, stageId,
+     * taskId) that belongs in the path, not the body. It is named as the
+     * key to omit — rather than allowlisting body fields — so a field
+     * added to the schema later flows through by default instead of
+     * being silently dropped.
+     */
+    function create(action, entity, path, description, fields, routingKey) {
+        rl.registerAction(action, {
+            access: "write",
+            description,
+            inputSchema: t.Object(fields, STRICT_OBJECT),
+            async execute(input, ctx) {
+                const all = input;
+                const body = { ...all };
+                if (routingKey)
+                    delete body[routingKey];
+                const response = await request(ctx, path(all), { method: "POST", body: JSON.stringify(body) });
+                return response[entity];
+            },
+        });
+    }
+    function update(action, entity, collection, description, fields) {
+        rl.registerAction(action, {
+            access: "write",
+            description,
+            inputSchema: t.Object({ id: idSchema(`${entity} ID`), ...fields }, STRICT_UPDATE_OBJECT),
+            async execute(input, ctx) {
+                const { id, ...patch } = input;
+                const response = await request(ctx, `${ATLAS_BASE}/${collection}/${pathSegment(id)}`, { method: "PATCH", body: JSON.stringify(patch) });
+                return response[entity];
+            },
+        });
+    }
+    function remove(action, entity, collection, description) {
+        rl.registerAction(action, {
+            access: "write",
+            description,
+            inputSchema: t.Object({ id: idSchema(`${entity} ID`) }, STRICT_OBJECT),
+            async execute(input, ctx) {
+                const { id } = input;
+                await request(ctx, `${ATLAS_BASE}/${collection}/${pathSegment(id)}`, { method: "DELETE" });
+                return { deleted: true, id };
+            },
+        });
+    }
+    /* Actors */
+    create("actor.create", "actor", () => `${ATLAS_BASE}/actors`, "Create a named worker: an agent (e.g. Jarvis) or a human role (e.g. CFO).", {
+        name: name("Actor name"),
+        kind: enumSchema("Actor kind", GRAPH_ACTOR_KIND),
+        description: t.Optional(longText("What this actor does")),
+    });
+    update("actor.update", "actor", "actors", "Update an actor.", {
+        name: t.Optional(name("Actor name")),
+        kind: t.Optional(enumSchema("Actor kind", GRAPH_ACTOR_KIND)),
+        description: t.Optional(longText("What this actor does")),
+    });
+    remove("actor.delete", "actor", "actors", "Delete an actor. Refused (409 actor_in_use) while assignments reference it.");
+    /* Lines */
+    create("line.create", "line", () => `${ATLAS_BASE}/lines`, "Create a business line — the widest grouping of journeys.", {
+        name: name("Line name"),
+        blurb: t.Optional(longText("One-sentence description")),
+        position: t.Optional(position),
+    });
+    update("line.update", "line", "lines", "Update a business line.", {
+        name: t.Optional(name("Line name")),
+        blurb: t.Optional(longText("One-sentence description")),
+        position: t.Optional(position),
+    });
+    remove("line.delete", "line", "lines", "Delete a business line. Refused while journeys reference it (line_in_use) or it is the last line (last_line).");
+    /* Journeys */
+    create("journey.create", "journey", () => `${ATLAS_BASE}/journeys`, "Create a journey: an end-to-end flow with a business outcome. " +
+        "Omitting lineId places it in the organization's default line.", {
+        lineId: t.Optional(idSchema("Business line ID")),
+        name: name("Journey name"),
+        outcome: t.Optional(longText("The business outcome it delivers")),
+        position: t.Optional(position),
+        status: t.Optional(enumSchema("Journey status", GRAPH_JOURNEY_STATUS)),
+    });
+    update("journey.update", "journey", "journeys", "Update a journey.", {
+        lineId: t.Optional(idSchema("Business line ID")),
+        name: t.Optional(name("Journey name")),
+        outcome: t.Optional(longText("The business outcome it delivers")),
+        position: t.Optional(position),
+        status: t.Optional(enumSchema("Journey status", GRAPH_JOURNEY_STATUS)),
+    });
+    remove("journey.delete", "journey", "journeys", "Delete a journey and, in cascade, its stages and tasks.");
+    /* Stages */
+    create("stage.create", "stage", (input) => `${ATLAS_BASE}/journeys/${pathSegment(input.journeyId)}/stages`, "Create an ordered stage inside a journey.", {
+        journeyId: idSchema("Journey ID"),
+        name: name("Stage name"),
+        intent: t.Optional(longText("What this stage exists to ensure")),
+        position: t.Optional(position),
+    }, "journeyId");
+    update("stage.update", "stage", "stages", "Update a stage.", {
+        name: t.Optional(name("Stage name")),
+        intent: t.Optional(longText("What this stage exists to ensure")),
+        position: t.Optional(position),
+    });
+    remove("stage.delete", "stage", "stages", "Delete a stage and, in cascade, its tasks.");
+    /* Tasks */
+    create("task.create", "task", (input) => `${ATLAS_BASE}/stages/${pathSegment(input.stageId)}/tasks`, "Create a task — the atomic responsibility inside a stage. " +
+        "actorId also creates the matching `does` assignment (the owner).", {
+        stageId: idSchema("Stage ID"),
+        description: t.String({
+            minLength: 1,
+            maxLength: 2_000,
+            pattern: "\\S",
+            description: "What the work is, in the business's own words",
+        }),
+        position: t.Optional(position),
+        intendedMode: enumSchema("Intended mode", GRAPH_TASK_MODE),
+        actorId: t.Optional(idSchema("Owner actor ID")),
+    }, "stageId");
+    update("task.update", "task", "tasks", "Update a task. actorId replaces the `does` assignment; null clears the owner.", {
+        description: t.Optional(t.String({ minLength: 1, maxLength: 2_000, pattern: "\\S" })),
+        position: t.Optional(position),
+        intendedMode: t.Optional(enumSchema("Intended mode", GRAPH_TASK_MODE)),
+        actorId: t.Optional(t.Union([idSchema("Owner actor ID"), t.Null()])),
+    });
+    remove("task.delete", "task", "tasks", "Delete a task.");
+    /* Assignments */
+    create("assignment.create", "assignment", (input) => `${ATLAS_BASE}/tasks/${pathSegment(input.taskId)}/assignments`, "Add an actor to a task in a RACI role. `does` is the owner; a task has at most one.", {
+        taskId: idSchema("Task ID"),
+        actorId: idSchema("Actor ID"),
+        role: t.Optional(enumSchema("Assignment role", GRAPH_ASSIGNMENT_ROLE)),
+    }, "taskId");
+    remove("assignment.delete", "assignment", "assignments", "Remove an actor's part in a task.");
+    /* Relations */
+    create("relation.create", "relation", () => `${ATLAS_BASE}/relations`, "Create a level-typed link: `follows` joins two tasks in one stage " +
+        "(cycles rejected); `triggers` joins two journeys (cycles allowed).", {
+        kind: enumSchema("Relation kind", GRAPH_RELATION_KIND),
+        fromId: idSchema("Source task or journey ID"),
+        toId: idSchema("Target task or journey ID"),
+    });
+    remove("relation.delete", "relation", "relations", "Delete a relation.");
+    /* Bindings */
+    create("binding.create", "binding", (input) => `${ATLAS_BASE}/tasks/${pathSegment(input.taskId)}/bindings`, "Bind a task to how it is executed: a Vex deployment, an external " +
+        "system, or manual work. A live non-manual binding is what makes " +
+        "a task count as live AI.", {
+        taskId: idSchema("Task ID"),
+        executor: enumSchema("Executor", GRAPH_BINDING_EXECUTOR),
+        label: name("Human-readable binding label"),
+        status: t.Optional(enumSchema("Binding status", GRAPH_BINDING_STATUS)),
+        deploymentId: t.Optional(idSchema("Vex deployment ID")),
+        reference: t.Optional(referenceField),
+        url: t.Optional(urlField),
+    }, "taskId");
+    update("binding.update", "binding", "bindings", "Update a binding; null clears deploymentId, reference, or url.", {
+        executor: t.Optional(enumSchema("Executor", GRAPH_BINDING_EXECUTOR)),
+        label: t.Optional(name("Human-readable binding label")),
+        status: t.Optional(enumSchema("Binding status", GRAPH_BINDING_STATUS)),
+        deploymentId: t.Optional(t.Union([idSchema("Vex deployment ID"), t.Null()])),
+        reference: t.Optional(t.Union([referenceField, t.Null()])),
+        url: t.Optional(t.Union([urlField, t.Null()])),
+    });
+    remove("binding.delete", "binding", "bindings", "Delete a binding.");
+    /* Evidence */
+    create("evidence.create", "evidence", (input) => `${ATLAS_BASE}/tasks/${pathSegment(input.taskId)}/evidence`, "Attach proof the work happens: a report, artifact, or dashboard. " +
+        "Requires url or artifactRef.", {
+        taskId: idSchema("Task ID"),
+        title: name("Evidence title"),
+        kind: enumSchema("Evidence kind", GRAPH_EVIDENCE_KIND),
+        url: t.Optional(urlField),
+        artifactRef: t.Optional(referenceField),
+    }, "taskId");
+    update("evidence.update", "evidence", "evidence", "Update evidence; null clears url or artifactRef.", {
+        title: t.Optional(name("Evidence title")),
+        kind: t.Optional(enumSchema("Evidence kind", GRAPH_EVIDENCE_KIND)),
+        url: t.Optional(t.Union([urlField, t.Null()])),
+        artifactRef: t.Optional(t.Union([referenceField, t.Null()])),
+    });
+    remove("evidence.delete", "evidence", "evidence", "Delete an evidence entry.");
+    /* Labels */
+    rl.registerAction("labels.update", {
+        access: "write",
+        description: "Rename what this organization calls each level — display only, " +
+            "no structural consequence.",
+        inputSchema: t.Object({
+            line: t.Optional(name("Label for the line level")),
+            journey: t.Optional(name("Label for the journey level")),
+            stage: t.Optional(name("Label for the stage level")),
+            task: t.Optional(name("Label for the task level")),
+        }, { additionalProperties: false, minProperties: 1 }),
+        async execute(input, ctx) {
+            const body = await request(ctx, `${ATLAS_BASE}/labels`, { method: "PATCH", body: JSON.stringify(input) });
+            return body.labels;
+        },
+    });
+}

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

@@ -0,0 +1,22 @@
+import * as t from "typebox";
+import { registerGraphActions } from "./graph.js";
+/**
+ * Shift Atlas — the operational graph of a Shift cloud organization:
+ * the map of how the business runs. Independent of the shiftLabs
+ * plugin the same way shiftCrm is, but authenticated with the same
+ * Shift cloud API key; the cloud derives the organization from the
+ * key, so no organization ID is ever sent (SHFT-852).
+ */
+export default function shiftAtlas(rl) {
+    rl.setName("shiftAtlas");
+    rl.setVersion("0.1.0");
+    rl.setConnectionSchema(t.Object({
+        // Same Shift Labs API key family as the shiftLabs plugin; needs
+        // the service:operational-graph:use scope.
+        apiKey: t.String({
+            description: "Shift Labs API key",
+            env: "SHIFT_LABS_API_KEY",
+        }),
+    }));
+    registerGraphActions(rl);
+}

package/dist/plugins/shiftAtlas/src/shared.js

@@ -0,0 +1,28 @@
+export { cursorSchema, enumSchema, idSchema, pathSegment, request, STRICT_OBJECT, STRICT_UPDATE_OBJECT, } from "../../_shared/shiftCloud.js";
+/** Base path of the operational graph service in the Shift cloud API. */
+export const ATLAS_BASE = "/v1/services/operational-graph";
+export const GRAPH_ACTOR_KIND = ["agent", "human_role"];
+export const GRAPH_JOURNEY_STATUS = ["draft", "published", "retired"];
+export const GRAPH_ASSIGNMENT_ROLE = [
+    "does",
+    "approves",
+    "consulted",
+    "informed",
+];
+export const GRAPH_RELATION_KIND = ["follows", "triggers"];
+export const GRAPH_TASK_MODE = ["ai", "human", "hybrid"];
+export const GRAPH_BINDING_EXECUTOR = ["vex", "external", "manual"];
+export const GRAPH_BINDING_STATUS = ["planned", "live", "paused"];
+export const GRAPH_EVIDENCE_KIND = ["report", "artifact", "dashboard"];
+export const GRAPH_CHANGE_ENTITY_TYPE = [
+    "actor",
+    "line",
+    "journey",
+    "stage",
+    "task",
+    "assignment",
+    "relation",
+    "binding",
+    "evidence",
+    "labels",
+];

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.21.0",
+  "description": "Code mode for agents \u2014 turn any API or command into a callable action",
   "type": "module",
   "main": "dist/index.js",
   "exports": {