@boardwalk-labs/runner 0.2.7 → 0.2.9

package/dist/runtime/program_runner.d.ts

@@ -91,6 +91,7 @@ export type ProgramResult = {
     error: {
         code: string;
         message: string;
+        hint?: string;
     };
 };
 /**

package/dist/runtime/program_runner.js

@@ -100,6 +100,36 @@ export function assertProgramRootOutsideWorkspace(programRoot, workspaceRoot) {
         throw new AppError(ErrorCode.VALIDATION_FAILED, `The program root "${programRoot}" is inside the workspace "${workspaceRoot}"; the extracted program must live outside it.`);
     }
 }
+/** An engine `EngineError` carries a one-line actionable `hint` alongside its message. It reaches us
+ *  as a thrown value across the SDK/engine package boundary, so DUCK-TYPE it rather than `instanceof`
+ *  (a dual-package copy of the class would defeat the check) — any thrown error carrying a non-empty
+ *  string `hint` is surfaced. Without this the hint is dropped here, and on a hosted run there is no
+ *  other place it could survive: the runner reports a failure as `{ code, message, hint? }` and the
+ *  broker persists exactly that. */
+function errorHint(err) {
+    if (typeof err !== "object" || err === null)
+        return undefined;
+    const hint = err.hint;
+    return typeof hint === "string" && hint !== "" ? hint : undefined;
+}
+/** A machine-readable error code shaped like one: SCREAMING_SNAKE, as an engine `EngineError.code`
+ *  (`VALIDATION`, `PROVIDER_ERROR`, …) and a Node syscall error (`ENOENT`) both are. */
+const ERROR_CODE_RE = /^[A-Z][A-Z0-9_]{0,63}$/;
+/**
+ * The SEMANTIC code of a thrown error, preferred over its class name. An engine `EngineError` carries
+ * `code: "VALIDATION"`; reporting `err.name` instead surfaced the useless `"EngineError"` on every
+ * hosted failure (and `"Error"` for anything else). Duck-typed for the same reason as {@link errorHint}.
+ *
+ * Two guards, because a thrown value is author-controlled: the SCREAMING_SNAKE shape keeps prose (or a
+ * stray object field) out of a field the UI renders as a code, and the CALLER redacts the result — an
+ * uppercase-alnum secret would satisfy the pattern, so the shape check is hygiene, not the boundary.
+ */
+function errorCode(err) {
+    if (typeof err !== "object" || err === null)
+        return undefined;
+    const code = err.code;
+    return typeof code === "string" && ERROR_CODE_RE.test(code) ? code : undefined;
+}
 /**
  * Run a workflow program to completion. Installs the host + input, extracts the VERIFIED artifact +
  * dynamic-imports its entry (which runs the body), and returns the terminal result. Always tears the
@@ -137,14 +167,26 @@ export async function runWorkflowProgram(args, deps) {
         const redactText = deps.redactText ?? ((s) => s);
         // Redact BEFORE both sinks: the message can carry a secret the program resolved then threw.
         const message = redactText(err instanceof Error ? err.message : String(err));
+        // The hint is author-facing guidance ("write `builtins: [...]`"); redact it too — it is built from
+        // the same untrusted inputs as the message and could echo a resolved secret.
+        const rawHint = errorHint(err);
+        const hint = rawHint === undefined ? undefined : redactText(rawHint);
+        // The error's own code when it has one ("VALIDATION"), else the class name ("Error"). Redacted
+        // like the rest: it is read off an author-controlled throw, not trusted to be a literal.
+        const rawCode = errorCode(err);
+        const code = rawCode !== undefined
+            ? redactText(rawCode)
+            : err instanceof Error
+                ? err.name
+                : "PROGRAM_ERROR";
         log.error("program_failed", { runId: args.runId, error: message });
         return {
             kind: "failed",
             output: null,
             error: {
-                // `code` is the error class name (e.g. "Error", "AppError"), not user content — left as-is.
-                code: err instanceof Error ? err.name : "PROGRAM_ERROR",
+                code,
                 message,
+                ...(hint === undefined ? {} : { hint }),
             },
         };
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@boardwalk-labs/runner",
-  "version": "0.2.7",
+  "version": "0.2.9",
   "description": "Boardwalk self-hosted runner: execute cloud-scheduled runs on your own machines. Currently: the canonical runner contract types.",
   "license": "Apache-2.0",
   "repository": {
@@ -53,7 +53,7 @@
     "prebuild": "prebuildify --napi --strip -t 24.0.0"
   },
   "dependencies": {
-    "@boardwalk-labs/engine": "0.2.6",
+    "@boardwalk-labs/engine": "0.2.7",
     "@boardwalk-labs/workflow": "0.2.2",
     "@modelcontextprotocol/sdk": "^1.29.0",
     "node-gyp-build": "^4.8.4",