runline 0.24.0 → 0.26.0

package/dist/core/engine.js

@@ -2,7 +2,7 @@ import { randomUUID } from "node:crypto";
 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";
+import { formatValidationError, helpInputs, isTypedInputSchema, normalizeActionInput, validateTypedInput, } from "../plugin/schema.js";
 /**
  * How many bodies one worker may run before it is retired.
  *
@@ -161,6 +161,16 @@ export class ExecutionEngine {
         try {
             acquired = this.acquire(shape, () => new Worker(buildWorkerSource(pluginNames, helpData), {
                 eval: true,
+                // Empty by construction: without an `env` option the worker
+                // inherits a copy of the host's entire environment, and
+                // Runline lives inside credential-bearing hosts (vex's
+                // server process, the pi agent process). Bodies hold a real
+                // `require` and a live `process`, so an inherited env is one
+                // line of agent code away from every host secret. Nothing
+                // in the worker needs an environment: actions execute
+                // host-side, connection configs are hydrated host-side, and
+                // ferrosearch is required by absolute path.
+                env: {},
                 resourceLimits: { maxOldGenerationSizeMb: memoryLimitMb },
             }));
         }
@@ -295,7 +305,10 @@ export class ExecutionEngine {
             reply({ t: "run", runId, body });
         });
     }
-    async invokeAction(path, args) {
+    async invokeAction(path, rawArgs) {
+        // A call written with no arguments reaches the action as `{}`, not
+        // `undefined`, so plugins can read `input.foo` without guarding.
+        const args = normalizeActionInput(rawArgs);
         const resolved = this.registry.resolveAction(path);
         if (!resolved) {
             throw new Error(`Unknown action: ${path}${this.selfPrefixHint(path)}`);

package/dist/plugin/schema.d.ts

@@ -15,5 +15,17 @@ export declare function legacyFields(schema: InputSchema | undefined): LegacyInp
 export declare function connectionFields(schema: ConnectionSchema | undefined): LegacyConnectionSchema;
 export declare function helpInputs(schema: InputSchema | undefined): Record<string, HelpInput>;
 export declare function validateLegacyInput(schema: LegacyInputSchema, input: unknown): ValidationResult;
-export declare function validateTypedInput(schema: TypedInputSchema, input: unknown): ValidationResult;
+/**
+ * A call written with no arguments is a call with an empty argument set.
+ *
+ * `linear.user.me()` is the most natural way to invoke an action that
+ * takes nothing, and validating `undefined` against an object schema
+ * rejected it every time. It also made a genuinely missing input report
+ * "must be object" instead of naming the field.
+ *
+ * Only `undefined` is normalized: an explicit `null` or `42` is an
+ * argument, and a wrong one.
+ */
+export declare function normalizeActionInput(input: unknown): unknown;
+export declare function validateTypedInput(schema: TypedInputSchema, rawInput: unknown): ValidationResult;
 export declare function formatValidationError(path: string, result: ValidationResult): string;

package/dist/plugin/schema.js

@@ -1,9 +1,18 @@
 import { Check, Errors } from "typebox/value";
+/**
+ * How deep `describe` will follow a schema. Nesting past this is
+ * vanishingly rare, and a self-referential schema would otherwise
+ * recurse until the stack gave out. A field cut off here says so, so
+ * that "no properties" and "stopped looking" stay distinguishable.
+ */
+const MAX_DESCRIBE_DEPTH = 5;
 export function isTypedInputSchema(schema) {
     if (!schema || typeof schema !== "object")
         return false;
     const candidate = schema;
-    return typeof candidate.type === "string" || Array.isArray(candidate.anyOf);
+    // A bare union is a typed schema too. Missing that here would classify
+    // it as legacy and iterate its JSON Schema keywords as field names.
+    return typeof candidate.type === "string" || Boolean(branchesOf(candidate));
 }
 export function legacyFields(schema) {
     if (!schema || isTypedInputSchema(schema))
@@ -47,19 +56,79 @@ export function helpInputs(schema) {
     const metadata = schema;
     if (metadata.type !== "object")
         return {};
-    const required = new Set(metadata.required ?? []);
-    return Object.fromEntries(Object.entries(metadata.properties ?? {}).map(([key, field]) => [
+    return describeProperties(metadata, 0);
+}
+function describeProperties(schema, depth) {
+    const required = new Set(schema.required ?? []);
+    return Object.fromEntries(Object.entries(schema.properties ?? {}).map(([key, field]) => [
         key,
-        {
-            type: baseType(field),
-            displayType: displayType(field),
-            required: required.has(key),
-            description: field.description,
-            enum: enumValues(field),
-            const: field.const,
-        },
+        describeField(field, required.has(key), depth),
     ]));
 }
+/**
+ * Describe one input, following arrays into their item shape, objects
+ * into their properties, and unions into each branch.
+ *
+ * A parameter typed only as "array" tells an agent nothing about what to
+ * put in it, so the shape has to be guessed and the first call is a coin
+ * flip. "object | object" is the same dead end wearing a union: two
+ * shapes are on offer and neither is shown. Reporting the nested shape
+ * is the difference between describe being documentation and being a
+ * type name.
+ */
+function describeField(field, required, depth) {
+    const described = {
+        type: baseType(field),
+        displayType: displayType(field),
+        required,
+        description: field.description,
+        enum: enumValues(field),
+        const: field.const,
+    };
+    const branches = unionBranches(field);
+    if (depth >= MAX_DESCRIBE_DEPTH) {
+        // Only claim truncation where something was actually left unread.
+        if (field.items || field.properties || branches)
+            described.truncated = true;
+        return described;
+    }
+    if (field.items) {
+        // An array element is not "required"; the flag has no meaning here.
+        described.items = describeField(field.items, false, depth + 1);
+    }
+    if (field.properties) {
+        described.properties = describeProperties(field, depth + 1);
+    }
+    if (branches) {
+        described.variants = branches.map((branch) => describeField(branch, false, depth + 1));
+    }
+    return described;
+}
+/**
+ * The branches of a union worth describing individually.
+ *
+ * Two unions need no expansion. A union of literals is already fully
+ * described by `enum`, and a union of bare scalars is already fully
+ * described by `displayType` — `string | null` is Linear's clearable
+ * pattern and repeating it as two empty branches only buries the unions
+ * that do carry shape.
+ */
+function unionBranches(field) {
+    const branches = branchesOf(field);
+    if (!branches)
+        return undefined;
+    if (enumValues(field))
+        return undefined;
+    return branches.some(hasShape) ? branches : undefined;
+}
+/** Whether a schema says more than its type name does. */
+function hasShape(schema) {
+    return Boolean(schema.properties ||
+        schema.items ||
+        branchesOf(schema) ||
+        schema.enum?.length ||
+        schema.description);
+}
 export function validateLegacyInput(schema, input) {
     const provided = input && typeof input === "object"
         ? input
@@ -86,7 +155,22 @@ export function validateLegacyInput(schema, input) {
     }
     return validationResult({ missing, unknown, typeErrors });
 }
-export function validateTypedInput(schema, input) {
+/**
+ * A call written with no arguments is a call with an empty argument set.
+ *
+ * `linear.user.me()` is the most natural way to invoke an action that
+ * takes nothing, and validating `undefined` against an object schema
+ * rejected it every time. It also made a genuinely missing input report
+ * "must be object" instead of naming the field.
+ *
+ * Only `undefined` is normalized: an explicit `null` or `42` is an
+ * argument, and a wrong one.
+ */
+export function normalizeActionInput(input) {
+    return input === undefined ? {} : input;
+}
+export function validateTypedInput(schema, rawInput) {
+    const input = normalizeActionInput(rawInput);
     if (Check(schema, input))
         return validationResult({});
     return validationResult({
@@ -130,9 +214,20 @@ function validationResult(input) {
         errors,
     };
 }
+/**
+ * The alternatives of a union, however the schema spells it. TypeBox
+ * emits `anyOf`; hand-written schemas in the plugins use `oneOf`. Every
+ * reader here has to treat them the same, so they are unified once, and
+ * an empty branch list is reported as no union at all.
+ */
+function branchesOf(schema) {
+    const branches = schema.anyOf ?? schema.oneOf;
+    return branches?.length ? branches : undefined;
+}
 function displayType(schema) {
-    if (schema.anyOf?.length)
-        return schema.anyOf.map(displayType).join(" | ");
+    const branches = branchesOf(schema);
+    if (branches)
+        return branches.map(displayType).join(" | ");
     if (schema.enum?.length)
         return schema.enum.map(String).join(" | ");
     if (schema.const !== undefined)
@@ -140,8 +235,9 @@ function displayType(schema) {
     return schema.type ?? "unknown";
 }
 function baseType(schema) {
-    if (schema.anyOf?.length) {
-        const types = [...new Set(schema.anyOf.map(baseType))];
+    const branches = branchesOf(schema);
+    if (branches) {
+        const types = [...new Set(branches.map(baseType))];
         return types.length === 1 ? types[0] : types.join(" | ");
     }
     if (schema.type)
@@ -153,9 +249,9 @@ function baseType(schema) {
 function enumValues(schema) {
     if (schema.enum?.length)
         return schema.enum;
-    if (schema.anyOf?.length &&
-        schema.anyOf.every((s) => s.const !== undefined)) {
-        return schema.anyOf.map((s) => s.const);
+    const branches = branchesOf(schema);
+    if (branches?.every((s) => s.const !== undefined)) {
+        return branches.map((s) => s.const);
     }
     return undefined;
 }

package/dist/plugin/types.d.ts

@@ -24,6 +24,17 @@ export interface HelpInput {
     description?: string;
     enum?: unknown[];
     const?: unknown;
+    /** Element shape, for array inputs. */
+    items?: HelpInput;
+    /** Nested field shapes, for object inputs. */
+    properties?: Record<string, HelpInput>;
+    /**
+     * Branches of a union, where at least one carries shape the display
+     * type cannot express. Absent for unions of literals or bare scalars.
+     */
+    variants?: HelpInput[];
+    /** Set when nesting ran past the describe depth limit and was not read. */
+    truncated?: boolean;
 }
 export type ActionAccess = "read" | "write";
 export interface ActionDef {

package/package.json

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