@nredd/pi-subagents 0.22.0-nredd.6 → 0.22.0-nredd.8

package/src/workflow/saved.ts

@@ -39,7 +39,7 @@
 
 import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
 import { isAbsolute, join } from "node:path";
-import { getAgentDir } from "@earendil-works/pi-coding-agent";
+import { resolveAgentDir } from "../home-paths.js";
 import { isSymlink, isUnsafeName, safeReadFile } from "../memory.js";
 import { isPackageResourceExcluded, packageWorkflowDirs, packageWorkflowFiles } from "../package-resources.js";
 import { hasMetaDeclaration } from "./meta.js";
@@ -61,12 +61,12 @@ const WORKFLOW_EXTENSION = ".js";
  * reaches this without an options bag travelling through `resolveWorkflowScript`,
  * `resolveWorkflowSource` and `readSavedWorkflow` purely to be consulted once.
  */
-export function savedWorkflowRoots(cwd: string): string[] {
+export function savedWorkflowRoots(cwd: string, homeDir?: string): string[] {
   return [
     join(cwd, ".pi", "workflows"),
     join(cwd, ".agents", "workflows"),
-    join(getAgentDir(), "workflows"),
-    ...packageWorkflowDirs(cwd),
+    join(resolveAgentDir(homeDir), "workflows"),
+    ...packageWorkflowDirs(cwd, { homeDir }),
   ];
 }
 
@@ -81,7 +81,7 @@ export type SavedWorkflow =
  * names that do exist — a model that guessed the name can correct itself from
  * the error instead of spending a turn asking.
  */
-export function readSavedWorkflow(name: string, cwd: string): SavedWorkflow {
+export function readSavedWorkflow(name: string, cwd: string, homeDir?: string): SavedWorkflow {
   const trimmed = name.trim();
   if (isUnsafeName(trimmed)) {
     return {
@@ -92,13 +92,13 @@ export function readSavedWorkflow(name: string, cwd: string): SavedWorkflow {
     };
   }
 
-  const roots = savedWorkflowRoots(cwd);
+  const roots = savedWorkflowRoots(cwd, homeDir);
   for (const root of roots) {
     if (isSymlink(root)) continue; // reject a symlinked root entirely, as skill-loader does
     const path = join(root, `${trimmed}${WORKFLOW_EXTENSION}`);
     // A `!` entry in the declaring package's manifest. Only ever true for a path
     // under a package root, so the local roots pay one set lookup for it.
-    if (isPackageResourceExcluded(path, cwd, "workflows")) continue;
+    if (isPackageResourceExcluded(path, cwd, "workflows", { homeDir })) continue;
     const script = safeReadFile(path);
     if (script === undefined) continue;
     // Found the file, so stop looking — a shadowing name that turns out not to
@@ -117,7 +117,7 @@ export function readSavedWorkflow(name: string, cwd: string): SavedWorkflow {
   // Last: a package that declared an individual file rather than a directory.
   // It carries no root to look a name up in, so it is matched by name here
   // instead — after every root, which keeps package scripts lowest-precedence.
-  const declared = packageWorkflowFiles(cwd).get(trimmed);
+  const declared = packageWorkflowFiles(cwd, { homeDir }).get(trimmed);
   if (declared !== undefined) {
     const script = safeReadFile(declared);
     if (script !== undefined) {
@@ -133,7 +133,7 @@ export function readSavedWorkflow(name: string, cwd: string): SavedWorkflow {
     }
   }
 
-  const known = listSavedWorkflows(cwd);
+  const known = listSavedWorkflows(cwd, homeDir);
   return {
     ok: false,
     message:
@@ -154,6 +154,7 @@ export function readSavedWorkflow(name: string, cwd: string): SavedWorkflow {
 export function resolveWorkflowSource(
   ref: { name?: string; scriptPath?: string },
   cwd: string,
+  homeDir?: string,
 ): SavedWorkflow {
   const path = ref.scriptPath?.trim();
   if (path !== undefined && path !== "") {
@@ -168,14 +169,14 @@ export function resolveWorkflowSource(
     }
   }
   const name = ref.name?.trim();
-  if (name !== undefined && name !== "") return readSavedWorkflow(name, cwd);
+  if (name !== undefined && name !== "") return readSavedWorkflow(name, cwd, homeDir);
   return { ok: false, message: "A workflow reference needs a `name` or a `scriptPath`." };
 }
 
 /** Every saved workflow name, de-duplicated across roots and sorted. */
-export function listSavedWorkflows(cwd: string): string[] {
+export function listSavedWorkflows(cwd: string, homeDir?: string): string[] {
   const names = new Set<string>();
-  for (const root of savedWorkflowRoots(cwd)) {
+  for (const root of savedWorkflowRoots(cwd, homeDir)) {
     if (!existsSync(root) || isSymlink(root)) continue;
     let entries: string[];
     try {
@@ -188,11 +189,11 @@ export function listSavedWorkflows(cwd: string): string[] {
       const name = entry.slice(0, -WORKFLOW_EXTENSION.length);
       if (isUnsafeName(name)) continue;
       const path = join(root, entry);
-      if (isPackageResourceExcluded(path, cwd, "workflows")) continue;
+      if (isPackageResourceExcluded(path, cwd, "workflows", { homeDir })) continue;
       if (isWorkflowFile(path)) names.add(name);
     }
   }
-  for (const [name, path] of packageWorkflowFiles(cwd)) {
+  for (const [name, path] of packageWorkflowFiles(cwd, { homeDir })) {
     if (isUnsafeName(name)) continue;
     if (isWorkflowFile(path)) names.add(name);
   }
@@ -228,10 +229,11 @@ function isWorkflowFile(path: string): boolean {
 export function resolveWorkflowScript(
   params: { script?: string; scriptPath?: string; name?: string },
   cwd: string,
+  homeDir?: string,
 ): { ok: true; script: string; scriptPath?: string } | { ok: false; message: string } {
   const path = params.scriptPath?.trim();
   if (path !== undefined && path !== "") {
-    const resolved = resolveWorkflowSource({ scriptPath: path }, cwd);
+    const resolved = resolveWorkflowSource({ scriptPath: path }, cwd, homeDir);
     return resolved.ok ? { ok: true, script: resolved.script, scriptPath: resolved.path } : resolved;
   }
   const script = params.script;
@@ -244,11 +246,11 @@ export function resolveWorkflowScript(
   // reference means.
   const name = params.name?.trim();
   if (name !== undefined && name !== "") {
-    const saved = resolveWorkflowSource({ name }, cwd);
+    const saved = resolveWorkflowSource({ name }, cwd, homeDir);
     return saved.ok ? { ok: true, script: saved.script, scriptPath: saved.path } : saved;
   }
 
-  const known = listSavedWorkflows(cwd);
+  const known = listSavedWorkflows(cwd, homeDir);
   return {
     ok: false,
     message:

package/src/workflow/task.ts

@@ -86,6 +86,8 @@ export interface WorkflowTask {
   /** The script's return value, once the run produced one. */
   value?: unknown;
   error?: string;
+  /** Full authored stack for the result; the compact status keeps only error. */
+  errorStack?: string;
 }
 
 export function createWorkflowTask(init: {
@@ -205,6 +207,7 @@ export function completeWorkflowTask(task: WorkflowTask, result: WorkflowRunResu
   task.replayedCount = result.replayedCount;
   task.value = result.value;
   task.error = result.error;
+  task.errorStack = result.errorStack;
   task.endTime = Date.now();
 }
 
@@ -222,6 +225,13 @@ export function failWorkflowTask(task: WorkflowTask, error: string): void {
 
 /** The run's outcome as text, for the notification and the LLM-facing result. */
 export function workflowResultText(task: WorkflowTask): string {
+  if (task.errorStack !== undefined) {
+    const stack = task.errorStack.slice(0, 16384);
+    const firstLine = stack.split("\n", 1)[0];
+    const message = task.error;
+    if (message === undefined || message === "" || firstLine === message || firstLine.endsWith(`: ${message}`)) return stack;
+    return `${message}\n${stack}`;
+  }
   if (task.error !== undefined) return task.error;
   if (task.value === undefined) return "No output.";
   if (typeof task.value === "string") return task.value;

package/src/workflow/worker-source.ts

@@ -26,10 +26,11 @@
  *
  * That said: our injected globals are themselves host closures, so
  * `agent.constructor` is still the host `Function`. The hygiene shrinks the
- * surface; it does not close the hole. **`codeGeneration: { strings: false }` is
- * the load-bearing defense** — it makes `Function("…")` and `eval("…")` throw
- * `EvalError`, so a captured host `Function` cannot compile anything. Treat this
- * as a determinism boundary, not a security boundary against a hostile script.
+ * surface; it does not close the hole. `codeGeneration: { strings: false }`
+ * makes realm-local `Function` and `eval` throw `EvalError`, but does not stop a
+ * captured host `Function`. The stack formatter stays realm-native rather than
+ * adding another host callback. Treat this as a determinism boundary, not a
+ * security boundary against a hostile script.
  *
  * ## Why determinism is a prelude and not a stub
  *
@@ -48,9 +49,8 @@
 /**
  * Runs inside the realm, ahead of the script body, on a single line.
  *
- * One line matters: the body is compiled at `\n` + line 1, and the host passes
- * `lineOffset: -1` so reported line numbers match the file the author wrote. Any
- * newline in here shifts every stack frame in every workflow script.
+ * The shared compiler puts this and the wrapper on the body's first line.
+ * No lineOffset is needed (Bun ignores it); only first-line columns need mapping.
  */
 const DETERMINISM_PRELUDE =
   "const Date = (function () {" +
@@ -96,13 +96,13 @@ const pendingCalls = new Map();
  */
 let spentOutput = 0;
 
-function callHost(method, payload) {
+function callHost(method, payload, onModelNote) {
   // Drain first, so the phase() that named this agent reaches the host ahead of
   // the agent entry rather than a tick behind it.
   flushProgress();
   return new Promise(function (resolve, reject) {
     const callId = nextCallId++;
-    pendingCalls.set(callId, { resolve: resolve, reject: reject });
+    pendingCalls.set(callId, { resolve: resolve, reject: reject, onModelNote: onModelNote });
     port.postMessage({ type: "call", callId: callId, method: method, payload: payload });
   });
 }
@@ -114,6 +114,7 @@ port.on("message", function (message) {
   if (!waiter) return;
   pendingCalls.delete(message.callId);
   if (message.ok) {
+    if (message.modelNote !== undefined && waiter.onModelNote) waiter.onModelNote(message.modelNote);
     waiter.resolve(message.value);
     return;
   }
@@ -523,6 +524,8 @@ async function agentIn(scope, prompt, opts) {
   const phaseIndex = phaseName !== undefined ? definePhaseIn(scope, phaseName) : scope.ambientPhaseIndex;
   const phaseTitle = phaseName !== undefined ? scopedTitle(scope, phaseName) : scope.ambientPhaseTitle;
 
+  // Set when the host ran the child on another model than configured.
+  let modelNote;
   const result = await callHost("agent", {
     prompt: text,
     label: label,
@@ -535,20 +538,60 @@ async function agentIn(scope, prompt, opts) {
     resume: resume,
     effort: effort,
     schema: schema,
-  });
-  if (result === undefined || result === null) return null;
+  }, function (note) { modelNote = note; });
+  if (result === undefined || result === null) {
+    // A failed child is a null; its note would otherwise be lost with it.
+    if (modelNote !== undefined) logIn(scope, modelNote);
+    return null;
+  }
   if (schema === undefined) return result;
   // Parsed with the realm's own JSON.parse so the script gets an object whose
   // prototype is its own — \`x instanceof Object\` and \`x.list instanceof Array\`
   // both hold, and it survives assertBoundary if the script returns it.
   try {
-    return realmParse(result);
+    const parsed = realmParse(result);
+    // A schema'd payload must stay exactly what the schema describes, so the
+    // note cannot lead it as text. It goes to the run log, and onto a plain
+    // object payload as a sibling \`_modelNote\` the script can read.
+    if (modelNote !== undefined) {
+      logIn(scope, modelNote);
+      if (parsed !== null && typeof parsed === "object" && !Array.isArray(parsed) && canCarryModelNote(schema) && !Object.prototype.hasOwnProperty.call(parsed, "_modelNote")) parsed._modelNote = modelNote;
+    }
+    return parsed;
   } catch (error) {
     logIn(scope, "agent(): the host returned a structured result that is not JSON");
     return null;
   }
 }
 
+/**
+ * Whether the host may add a sibling \`_modelNote\` to a schema'd payload.
+ *
+ * Deliberately conservative: only a PLAIN object-with-properties schema, using
+ * nothing but the keywords below, qualifies. Anything that could declare the
+ * field somewhere we do not look (allOf/anyOf/oneOf/$ref/patternProperties/
+ * if-then-else/dependent schemas/a schema-valued additionalProperties) or forbid
+ * it (additionalProperties: false) never gets an injected field, and the note
+ * goes to the run log instead.
+ */
+var PLAIN_SCHEMA_KEYS = ["$schema", "type", "properties", "required", "description", "title"];
+function canCarryModelNote(schema) {
+  if (!schema || typeof schema !== "object" || Array.isArray(schema)) return false;
+  if (schema.type !== "object") return false;
+  const props = schema.properties;
+  if (!props || typeof props !== "object" || Array.isArray(props)) return false;
+  if (Object.prototype.hasOwnProperty.call(props, "_modelNote")) return false;
+  const keys = Object.keys(schema);
+  for (let i = 0; i < keys.length; i++) {
+    if (PLAIN_SCHEMA_KEYS.indexOf(keys[i]) === -1) {
+      // \`additionalProperties: true\` changes nothing, so it stays plain.
+      if (keys[i] === "additionalProperties" && schema.additionalProperties === true) continue;
+      return false;
+    }
+  }
+  return true;
+}
+
 /**
  * A barrier: every thunk starts now, and nothing past the await runs until all
  * of them have settled. A thunk that throws resolves to null rather than
@@ -675,19 +718,7 @@ async function workflowIn(scope, nameOrRef, args) {
   child.ambientPhaseIndex = definePhaseIn(child, undefined);
   child.ambientPhaseTitle = scopedTitle(child, undefined);
 
-  let run;
-  try {
-    const compiled = new vm.Script(
-      // \`meta\` is deliberately not a parameter: the body still opens with its
-      // own \`const meta = { ... }\` (extractMeta strips only the \`export\`), so a
-      // parameter of that name would collide with it.
-      "(async (agent, phase, log, workflow, console, args) => {" + PRELUDE + "\\n" + loaded.body + "\\n})",
-      { filename: "workflow:" + loaded.name + ".js", lineOffset: -1 }
-    );
-    run = compiled.runInContext(realmContext);
-  } catch (error) {
-    throw new Error('workflow("' + label + '"): ' + describe(error));
-  }
+  const run = compileWorkflow(loaded.body, "workflow:" + loaded.name + ".js");
 
   const value = await run(child.agent, child.phase, child.log, child.workflow, child.console, args);
   checkBoundary(value, 'the result of workflow("' + label + '")');
@@ -721,6 +752,73 @@ function makeBudget() {
   };
 }
 
+/* ------------------------------------------------------------------ *
+ * Authored source locations
+ * ------------------------------------------------------------------ */
+
+// Neither lineOffset nor columnOffset is implemented by Bun 1.3/1.4. Keep
+// authored lines intact and map only the prefix on line 1. Both entry points
+// compile the same function; calling it outside the VM adds no synthetic frame.
+const WORKFLOW_PREFIX = "(async (agent, phase, log, workflow, console, args) => {" + PRELUDE;
+let registerWorkflowFile = null;
+
+// Compiled from source in the realm, not installed as a host callback. Only
+// primitive prefix length and filenames cross into its private realm-native Set.
+function installAuthoredStacks(prefixLength) {
+  const workflowFiles = new Set();
+  function authoredFrame(frame) {
+    const text = String(frame);
+    const file = frame.getFileName();
+    if (!workflowFiles.has(file) || frame.getLineNumber() !== 1) return text;
+    const location = file + ":1:";
+    const at = text.lastIndexOf(location);
+    if (at === -1) return text;
+    const start = at + location.length;
+    // Bun 1.3's getColumnNumber() is zero-based, but CallSite.toString()
+    // is one-based on all supported engines.
+    const column = Number.parseInt(text.slice(start), 10);
+    if (column <= prefixLength) return text;
+    const digits = String(column).length;
+    return text.slice(0, start) + (column - prefixLength) + text.slice(start + digits);
+  }
+  Error.prepareStackTrace = function (error, frames) {
+    return Error.prototype.toString.call(error) + frames.map(function (frame) {
+      return "\\n    at " + authoredFrame(frame);
+    }).join("");
+  };
+  return function (filename) { workflowFiles.add(filename); };
+}
+
+function compileWorkflow(body, filename) {
+  registerWorkflowFile(filename);
+  try {
+    return new vm.Script(WORKFLOW_PREFIX + body + "\\n})", { filename: filename }).runInContext(realmContext);
+  } catch (error) {
+    // Parser errors are created outside the realm. Retain the actual error,
+    // but remove the generated prefix from a first-line source/caret excerpt.
+    if (error && typeof error.stack === "string") {
+      if (error.stack.startsWith(filename + ":1\\n")) {
+        const lines = error.stack.split("\\n");
+        if (lines[1]?.startsWith(WORKFLOW_PREFIX)) {
+          lines[1] = lines[1].slice(WORKFLOW_PREFIX.length);
+          if (lines[2] !== undefined) lines[2] = lines[2].slice(WORKFLOW_PREFIX.length);
+          error.stack = lines.join("\\n");
+        }
+      } else if (error.sourceURL === filename && error.stack.startsWith("[native code]:0\\n")) {
+        // Bun 1.3 defers parsing until runInContext and loses the source
+        // excerpt/column. It still supplies the authored line; don't invent
+        // a caret for a column the engine did not report.
+        const line = error.line;
+        const sourceLines = body.split(/\\r\\n|[\\n\\r\\u2028\\u2029]/);
+        if (Number.isInteger(line) && line > 0 && line <= sourceLines.length) {
+          error.stack = filename + ":" + line + "\\n" + sourceLines[line - 1] + "\\n" + error.stack.slice(error.stack.indexOf("\\n") + 1);
+        }
+      }
+    }
+    throw error;
+  }
+}
+
 /* ------------------------------------------------------------------ *
  * Run
  * ------------------------------------------------------------------ */
@@ -754,14 +852,15 @@ async function main() {
   sandbox.meta = realmParse(workerData.metaJson);
   sandbox.args = workerData.argsJson === undefined ? undefined : realmParse(workerData.argsJson);
 
-  const script = new vm.Script("(async () => {" + PRELUDE + "\\n" + workerData.body + "\\n})()", {
-    filename: "workflow.js",
-    // The wrapper adds exactly one line above the body; undo it so a thrown
-    // error points at the line the author wrote.
-    lineOffset: -1,
-  });
-
-  const value = await script.runInContext(context);
+  // Structured CallSites retain constructor-expression columns on both V8 and
+  // JSC. Formatting changes no Error constructor, prototype, identity or cause.
+  registerWorkflowFile = vm.runInContext(
+    "(" + installAuthoredStacks.toString() + ")(" + WORKFLOW_PREFIX.length + ")",
+    context,
+    { filename: "workflow-stack.js" }
+  );
+  const run = compileWorkflow(workerData.body, "workflow.js");
+  const value = await run(rootScope.agent, rootScope.phase, rootScope.log, rootScope.workflow, rootScope.console, sandbox.args);
   checkBoundary(value, "the workflow result");
   flushProgress();
   port.postMessage({
@@ -770,12 +869,31 @@ async function main() {
   });
 }
 
+/** Serialize diagnostics only: keep realm errors untouched and bound cause traversal/output. */
+function failureDetails(error) {
+  const limit = 16384;
+  let message = "Workflow threw an unreadable error.";
+  let stack = "";
+  const seen = new Set();
+  try {
+    message = String(error && error.message ? error.message : error).slice(0, 4096);
+    let current = error;
+    for (let depth = 0; depth < 8 && stack.length < limit; depth++) {
+      if (seen.has(current)) break;
+      seen.add(current);
+      const text = current && typeof current.stack === "string" ? current.stack : String(current);
+      stack += (depth === 0 ? "" : "\\nCaused by: ") + text.slice(0, limit - stack.length);
+      if (!current || current.cause === undefined) break;
+      current = current.cause;
+    }
+  } catch {
+    // A diagnostic getter must not prevent the failed run from settling.
+  }
+  return { type: "error", message: message, stack: stack.slice(0, limit) || undefined };
+}
+
 main().catch(function (error) {
   flushProgress();
-  port.postMessage({
-    type: "error",
-    message: error && error.message ? String(error.message) : String(error),
-    stack: error && error.stack ? String(error.stack) : undefined,
-  });
+  port.postMessage(failureDetails(error));
 });
 `;