@pylonsync/functions 0.4.16 → 0.4.19

package/src/runtime-workflows.test.ts

@@ -0,0 +1,263 @@
+/**
+ * End-to-end protocol test for workflow execution through the REAL
+ * runtime (runtime.ts child process) — the seam the 2026-08 audit
+ * flagged: the old workflow surface type-checked everywhere and
+ * executed nowhere.
+ *
+ * The contract under test, wire-for-wire what the Rust host does:
+ *
+ *   1. A `workflows/` dir next to the functions dir is discovered at
+ *      boot; the ready handshake declares each workflow AND registers
+ *      the internal `__pylon_workflow_run` action.
+ *   2. A `call` frame for `__pylon_workflow_run` with the engine's
+ *      advance request executes ONE slice and returns the runner
+ *      verdict as a normal `return` frame.
+ *   3. Step code runs with a live ActionCtx — proven by a step that
+ *      round-trips `ctx.runQuery` through the host (this test) before
+ *      producing its output.
+ */
+import { expect, test } from "bun:test";
+import { mkdirSync, mkdtempSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+const RUNTIME = join(import.meta.dir, "runtime.ts");
+const WORKFLOWS_MOD = join(import.meta.dir, "workflows.ts");
+
+const WORKFLOW_FILE = `
+import { workflow } from ${JSON.stringify(WORKFLOWS_MOD)};
+
+export default workflow("greet", async (wf, ctx) => {
+  const user = await wf.step("load-user", () =>
+    ctx.runQuery("getUser", { id: wf.input.userId }),
+  );
+  const greeting = await wf.step("compose", () => \`Hello \${user.name}\`);
+  return { greeting };
+});
+`;
+
+function parseFrames(text: string): Record<string, unknown>[] {
+  return text
+    .split("\n")
+    .filter((l) => l.trim().startsWith("{"))
+    .map((l) => JSON.parse(l) as Record<string, unknown>);
+}
+
+const START_ACTION = `
+export default {
+  type: "action",
+  auth: "user",
+  handler: async (ctx, args) => {
+    const started = await ctx.workflows.start("greet", { userId: args.userId });
+    return { workflowId: started.id };
+  },
+};
+`;
+
+test("workflows/ dir boots, declares in ready, and slices execute with a live ctx", async () => {
+  // App root: one action (exercises ctx.workflows.start) + one workflow.
+  const appDir = mkdtempSync(join(tmpdir(), "pylon-wf-e2e-"));
+  mkdirSync(join(appDir, "functions"));
+  writeFileSync(join(appDir, "functions", "kickoff.ts"), START_ACTION);
+  mkdirSync(join(appDir, "workflows"));
+  writeFileSync(join(appDir, "workflows", "greet.ts"), WORKFLOW_FILE);
+
+  // Spawn the real runtime exactly as the host does: cwd = app root,
+  // argv[2] = functions dir.
+  const proc = Bun.spawn([process.execPath, "run", RUNTIME, "functions"], {
+    cwd: appDir,
+    stdin: "pipe",
+    stdout: "pipe",
+    stderr: "pipe",
+  });
+
+  const reader = proc.stdout.getReader();
+  const decoder = new TextDecoder();
+  let buffered = "";
+  const frames: Record<string, unknown>[] = [];
+  async function readUntil(
+    pred: (fs: Record<string, unknown>[]) => boolean,
+  ): Promise<void> {
+    while (!pred(frames)) {
+      const { done, value } = await reader.read();
+      if (done) throw new Error(`child exited early; frames: ${buffered}`);
+      buffered += decoder.decode(value, { stream: true });
+      frames.length = 0;
+      frames.push(...parseFrames(buffered));
+    }
+  }
+  const send = (msg: Record<string, unknown>) =>
+    proc.stdin.write(JSON.stringify(msg) + "\n");
+
+  // 1. Ready declares the workflow + the implicit runner action.
+  await readUntil((fs) => fs.some((f) => f.type === "ready"));
+  const ready = frames.find((f) => f.type === "ready") as {
+    functions: Array<{ name: string; internal: boolean; auth: string }>;
+    workflows: Array<{
+      name: string;
+      description: string;
+      max_retries: number | null;
+    }>;
+  };
+  expect(ready.workflows).toEqual([
+    { name: "greet", description: "", max_retries: null },
+  ]);
+  const runFn = ready.functions.find((f) => f.name === "__pylon_workflow_run");
+  expect(runFn).toBeDefined();
+  expect(runFn!.internal).toBe(true);
+  expect(runFn!.auth).toBe("admin");
+
+  // 2. Slice 0: executes "load-user", whose body calls ctx.runQuery —
+  //    answer it like the host's RunFn arm would.
+  send({
+    type: "call",
+    call_id: "c_1",
+    fn_name: "__pylon_workflow_run",
+    fn_type: "action",
+    auth: { user_id: null, is_admin: true },
+    args: {
+      workflow_id: "wf_1",
+      workflow_name: "greet",
+      input: { userId: "u1" },
+      current_step: 0,
+      completed_steps: [],
+    },
+  });
+  await readUntil((fs) => fs.some((f) => f.type === "run_fn"));
+  const runReq = frames.find((f) => f.type === "run_fn") as {
+    call_id: string;
+    fn_name: string;
+    args: unknown;
+  };
+  expect(runReq.fn_name).toBe("getUser");
+  expect(runReq.args).toEqual({ id: "u1" });
+  send({
+    type: "result",
+    call_id: runReq.call_id,
+    data: { id: "u1", name: "Ada" },
+  });
+
+  await readUntil((fs) =>
+    fs.some((f) => f.type === "return" && f.call_id === "c_1"),
+  );
+  const slice0 = frames.find(
+    (f) => f.type === "return" && f.call_id === "c_1",
+  ) as { value: Record<string, unknown> };
+  expect(slice0.value).toMatchObject({
+    action: "step_complete",
+    step_name: "load-user",
+    output: { id: "u1", name: "Ada" },
+  });
+
+  // 3. Slice 1: replays load-user from the recorded output (NO run_fn
+  //    round-trip this time), executes "compose".
+  send({
+    type: "call",
+    call_id: "c_2",
+    fn_name: "__pylon_workflow_run",
+    fn_type: "action",
+    auth: { user_id: null, is_admin: true },
+    args: {
+      workflow_id: "wf_1",
+      workflow_name: "greet",
+      input: { userId: "u1" },
+      current_step: 1,
+      completed_steps: [
+        {
+          step_id: "step_0",
+          name: "load-user",
+          status: "completed",
+          output: { id: "u1", name: "Ada" },
+        },
+      ],
+    },
+  });
+  await readUntil((fs) =>
+    fs.some((f) => f.type === "return" && f.call_id === "c_2"),
+  );
+  const slice1 = frames.find(
+    (f) => f.type === "return" && f.call_id === "c_2",
+  ) as { value: Record<string, unknown> };
+  expect(slice1.value).toMatchObject({
+    action: "step_complete",
+    step_name: "compose",
+    output: "Hello Ada",
+  });
+  // Replay must not have re-fetched the user.
+  expect(frames.filter((f) => f.type === "run_fn")).toHaveLength(1);
+
+  // 4. Slice 2: both steps replay; the workflow completes.
+  send({
+    type: "call",
+    call_id: "c_3",
+    fn_name: "__pylon_workflow_run",
+    fn_type: "action",
+    auth: { user_id: null, is_admin: true },
+    args: {
+      workflow_id: "wf_1",
+      workflow_name: "greet",
+      input: { userId: "u1" },
+      current_step: 2,
+      completed_steps: [
+        {
+          step_id: "step_0",
+          name: "load-user",
+          status: "completed",
+          output: { id: "u1", name: "Ada" },
+        },
+        {
+          step_id: "step_1",
+          name: "compose",
+          status: "completed",
+          output: "Hello Ada",
+        },
+      ],
+    },
+  });
+  await readUntil((fs) =>
+    fs.some((f) => f.type === "return" && f.call_id === "c_3"),
+  );
+  const slice2 = frames.find(
+    (f) => f.type === "return" && f.call_id === "c_3",
+  ) as { value: Record<string, unknown> };
+  expect(slice2.value).toEqual({
+    action: "complete",
+    output: { greeting: "Hello Ada" },
+  });
+
+  // 5. App code starts a workflow: the kickoff action's
+  //    ctx.workflows.start emits a workflow_op frame; answer it as the
+  //    host's engine hook would and confirm the id flows back out.
+  send({
+    type: "call",
+    call_id: "c_4",
+    fn_name: "kickoff",
+    fn_type: "action",
+    auth: { user_id: "u1", is_admin: false },
+    args: { userId: "u1" },
+  });
+  await readUntil((fs) => fs.some((f) => f.type === "workflow_op"));
+  const wfOp = frames.find((f) => f.type === "workflow_op") as {
+    call_id: string;
+    op: string;
+    name: string;
+    input: unknown;
+  };
+  expect(wfOp).toMatchObject({
+    call_id: "c_4",
+    op: "start",
+    name: "greet",
+    input: { userId: "u1" },
+  });
+  send({ type: "result", call_id: "c_4", data: { id: "wf_777" } });
+  await readUntil((fs) =>
+    fs.some((f) => f.type === "return" && f.call_id === "c_4"),
+  );
+  const kicked = frames.find(
+    (f) => f.type === "return" && f.call_id === "c_4",
+  ) as { value: Record<string, unknown> };
+  expect(kicked.value).toEqual({ workflowId: "wf_777" });
+
+  proc.kill();
+  await proc.exited;
+}, 30_000);

package/src/runtime.ts

@@ -29,6 +29,7 @@ import type {
   LlmCompleteResponse,
   LlmStreamEvent,
   Rooms,
+  Workflows,
   Connections,
   QueryCtx,
   MutationCtx,
@@ -188,6 +189,36 @@ const pendingRpcs = new Map<
  */
 const streamSinks = new Map<string, (event: unknown) => void>();
 
+/**
+ * Calls the host cancelled (idle-timeout exceeded), keyed by call_id →
+ * reason. The host stops listening the moment it sends `cancel` — its
+ * demux route is gone — so the goals here are to stop the handler from
+ * doing further work, not to answer:
+ *   - the call's AbortController fires (ctx.signal → fetch/LLM SDKs stop),
+ *   - its in-flight RPC promises reject,
+ *   - its FUTURE RPCs throw CALL_CANCELLED (this is what actually stops
+ *     a typical handler at its next ctx.db/ctx.scheduler touch),
+ *   - its return/error frames are suppressed (the host would drop them
+ *     as unknown-route frames anyway; suppressing skips the wasted send).
+ * Entries expire after CANCEL_TOMBSTONE_MS so a late cancel for an
+ * already-finished call can't leak forever.
+ */
+const cancelledCalls = new Map<string, string>();
+const callAborts = new Map<string, AbortController>();
+const CANCEL_TOMBSTONE_MS = 5 * 60_000;
+
+function cancelledError(callId: string): Error {
+  const reason = cancelledCalls.get(callId) ?? "cancelled by host";
+  const err = new Error(`call cancelled by host: ${reason}`);
+  (err as { code?: string }).code = "CALL_CANCELLED";
+  return err;
+}
+
+/** Throw when the host has cancelled this call — RPC entry gate. */
+function throwIfCancelled(callId: string): void {
+  if (cancelledCalls.has(callId)) throw cancelledError(callId);
+}
+
 let opSeq = 0;
 function nextOpId(callId: string): string {
   opSeq += 1;
@@ -320,6 +351,23 @@ function dispatch(line: string): void {
           error: err?.message || String(err),
         });
       });
+  } else if (msg.type === "cancel") {
+    // Host cancelled one call (idle timeout). See cancelledCalls above.
+    const c = msg as unknown as { call_id: string; reason?: string };
+    cancelledCalls.set(c.call_id, c.reason ?? "cancelled by host");
+    setTimeout(() => cancelledCalls.delete(c.call_id), CANCEL_TOMBSTONE_MS);
+    callAborts.get(c.call_id)?.abort(cancelledError(c.call_id));
+    for (const [key, pending] of pendingRpcs) {
+      if (key === c.call_id || key.startsWith(`${c.call_id}#`)) {
+        pendingRpcs.delete(key);
+        streamSinks.delete(key);
+        clearTimeout(pending.timeout);
+        pending.reject(cancelledError(c.call_id));
+      }
+    }
+    console.error(
+      `[functions] host cancelled call ${c.call_id}: ${c.reason ?? "(no reason)"}`,
+    );
   } else if (msg.type === "llm_event") {
     const ev = msg as unknown as {
       call_id: string;
@@ -357,6 +405,7 @@ function rpcDb(
   callId: string,
   msg: Record<string, unknown>,
 ): Promise<unknown> {
+  throwIfCancelled(callId);
   const opId = nextOpId(callId);
   return new Promise((resolve, reject) => {
     const timeout = setTimeout(() => {
@@ -390,6 +439,7 @@ function rpcStreaming(
   msg: Record<string, unknown>,
   onEvent: (event: unknown) => void,
 ): Promise<unknown> {
+  throwIfCancelled(callId);
   const opId = nextOpId(callId);
   return new Promise((resolve, reject) => {
     const fail = () => {
@@ -459,6 +509,7 @@ const rpcQueues = new Map<string, Promise<unknown>>();
  * the rest of the queue.
  */
 function rpc(callId: string, msg: Record<string, unknown>): Promise<unknown> {
+  throwIfCancelled(callId);
   const prev = rpcQueues.get(callId) ?? Promise.resolve();
   const run = prev
     .then(
@@ -886,6 +937,35 @@ export function buildRooms(callId: string): Rooms {
   };
 }
 
+/**
+ * Build `ctx.workflows` — start a durable workflow or deliver an event
+ * to a waiting one, from mutation/action code. Round-trips a
+ * `workflow_op` frame to the host's WorkflowEngine; the engine's driver
+ * takes it from there, so `start` returns the instance id immediately.
+ * Uses the queued call_id-keyed `rpc` (the reply carries no op_id).
+ */
+export function buildWorkflows(callId: string): Workflows {
+  return {
+    async start(name: string, input?: unknown) {
+      return (await rpc(callId, {
+        type: "workflow_op",
+        op: "start",
+        name,
+        input: input ?? null,
+      })) as { id: string };
+    },
+    async sendEvent(workflowId: string, event: string, data?: unknown) {
+      return (await rpc(callId, {
+        type: "workflow_op",
+        op: "send_event",
+        workflow_id: workflowId,
+        event,
+        data: data ?? null,
+      })) as { delivered: boolean };
+    },
+  };
+}
+
 /**
  * Build the connection registry that round-trips through the host.
  * Each method emits a `{type:"connection", op:"..."}` message;
@@ -983,6 +1063,7 @@ function buildActionCtx(
     llm,
     rooms,
     connections,
+    workflows: buildWorkflows(callId),
     env: process.env as Record<string, string>,
     async runQuery(fnName, args) {
       return rpc(callId, {
@@ -1083,6 +1164,12 @@ async function handleCall(msg: CallMessage): Promise<void> {
     }
   }
 
+  // Cooperative cancellation. The host's `cancel` frame aborts this
+  // controller; ctx.signal lets a handler thread it into fetch / SDK
+  // calls so a cancelled call stops burning tokens, not just replies.
+  const abort = new AbortController();
+  callAborts.set(msg.call_id, abort);
+
   const stream = buildStream(msg.call_id);
   const scheduler = buildScheduler(msg.call_id);
   const email = buildEmail(msg.call_id);
@@ -1163,6 +1250,7 @@ async function handleCall(msg: CallMessage): Promise<void> {
         llm,
         rooms,
         connections,
+        workflows: buildWorkflows(msg.call_id),
         error(code, message) {
           const err = new Error(message);
           (err as any).code = code;
@@ -1190,14 +1278,25 @@ async function handleCall(msg: CallMessage): Promise<void> {
       break;
   }
 
+  // Expose the cancellation signal on every ctx variant. Assigned after
+  // the switch so all three ctx shapes get it without threading another
+  // parameter through each builder.
+  (ctx as { signal?: AbortSignal }).signal = abort.signal;
+
   try {
     const result = await def.handler(ctx, msg.args);
+    if (cancelledCalls.has(msg.call_id)) return;
     send({
       type: "return",
       call_id: msg.call_id,
       value: result ?? null,
     });
   } catch (err: any) {
+    // A cancelled call's host stopped listening — its demux route is
+    // gone, so any frame we send is dropped unread. Skip the send (and
+    // the redaction logging: CALL_CANCELLED is the expected way a
+    // cancelled handler unwinds, not an app error worth a stack trace).
+    if (cancelledCalls.has(msg.call_id)) return;
     // Redact. Handler errors historically shipped raw `err.message` to the
     // caller, which leaked DB error text, stack-trace-looking strings, and
     // internal concurrency-invariant messages. Authors can still surface a
@@ -1239,6 +1338,8 @@ async function handleCall(msg: CallMessage): Promise<void> {
         message: `Internal handler error${devDetail}`,
       });
     }
+  } finally {
+    callAborts.delete(msg.call_id);
   }
 }
 
@@ -1304,6 +1405,83 @@ async function main() {
     }
   }
 
+  // Workflows: scan the app's workflows/ dir (sibling of functions/).
+  // Each file default-exports a `workflow(...)`. Declared names ride the
+  // ready handshake so the host registers them with its WorkflowEngine;
+  // execution comes back through the implicit internal action below.
+  const { isWorkflowDefinition, executeWorkflowSlice } = await import(
+    "./workflows"
+  );
+  type WorkflowDefinition = import("./workflows").WorkflowDefinition;
+  const workflowRegistry = new Map<string, WorkflowDefinition>();
+  const wfDir = join(process.cwd(), "workflows");
+  let wfFiles: string[] = [];
+  try {
+    wfFiles = readdirSync(wfDir).filter(
+      (f) => f.endsWith(".ts") || f.endsWith(".js"),
+    );
+  } catch {
+    // No workflows/ directory — the common case; declare nothing.
+  }
+  for (const file of wfFiles) {
+    try {
+      const mod = await import(join(wfDir, file));
+      const def = mod.default;
+      if (isWorkflowDefinition(def)) {
+        if (workflowRegistry.has(def.name)) {
+          console.error(
+            `[workflows] duplicate workflow name "${def.name}" (${file}) — keeping the first`,
+          );
+          continue;
+        }
+        workflowRegistry.set(def.name, def);
+      } else {
+        console.error(
+          `[workflows] ${file} has no default-exported workflow(...) — skipped`,
+        );
+      }
+    } catch (err) {
+      console.error(`[workflows] Failed to load ${file}:`, err);
+    }
+  }
+  if (workflowRegistry.size > 0) {
+    // The host drives every workflow slice through this internal action,
+    // so step code gets a full ActionCtx (db, llm, scheduler, idle
+    // timeout, cancellation). admin auth + internal: only the host's
+    // engine hook may invoke it. timeout 600: one slice is one step —
+    // long AGENT steps stream (extending the idle budget); a silent 10
+    // minutes is a hang.
+    registry.set("__pylon_workflow_run", {
+      type: "action",
+      internal: true,
+      auth: "admin",
+      timeout: 600,
+      handler: async (ctx: unknown, args: unknown) => {
+        const req = args as import("./workflows").WorkflowRunRequest;
+        const def = workflowRegistry.get(req.workflow_name);
+        if (!def) {
+          return {
+            action: "fail",
+            error: `workflow "${req.workflow_name}" is not registered in this runtime`,
+          };
+        }
+        return executeWorkflowSlice(
+          def,
+          req,
+          ctx as import("./types").ActionCtx,
+        );
+      },
+    } as unknown as FnDefinition);
+  }
+  const workflows = Array.from(workflowRegistry.values()).map((w) => ({
+    name: w.name,
+    description: w.description ?? "",
+    max_retries:
+      typeof w.maxRetries === "number" && w.maxRetries >= 0
+        ? Math.floor(w.maxRetries)
+        : null,
+  }));
+
   const functions = Array.from(registry.entries()).map(([name, def]) => ({
     name,
     fn_type: def.type,
@@ -1326,7 +1504,7 @@ async function main() {
         ? Math.floor(def.timeout)
         : null,
   }));
-  send({ type: "ready", functions });
+  send({ type: "ready", functions, workflows });
 
   // Belt-and-suspenders against orphaning: if the host dies in a way that
   // somehow leaves our stdin open, we'll have been REPARENTED — our ppid

package/src/types.ts

@@ -471,6 +471,30 @@ export interface Rooms {
   ): Promise<{ delivered: boolean }>;
 }
 
+/**
+ * Durable workflows, driven from app code (`ctx.workflows` on mutations
+ * and actions — not queries, whose reactive re-runs would re-start).
+ * Workflows are declared in the app's `workflows/` directory; see the
+ * `workflow()` export.
+ */
+export interface Workflows {
+  /**
+   * Start a workflow instance by name. Returns immediately with the
+   * instance id — the engine's background driver executes the steps.
+   */
+  start(name: string, input?: unknown): Promise<{ id: string }>;
+  /**
+   * Deliver an event to an instance paused on
+   * `wf.waitForEvent(event)`. Rejects when the instance isn't waiting
+   * for that event.
+   */
+  sendEvent(
+    workflowId: string,
+    event: string,
+    data?: unknown,
+  ): Promise<{ delivered: boolean }>;
+}
+
 export interface LlmMessage {
   role: "user" | "assistant" | "system" | "tool";
   content: string | LlmContentBlock[];
@@ -700,6 +724,14 @@ export interface QueryCtx<R extends AuthRequirement = "optional"> {
   requireMember: RequireMember;
   /** Signed file-download URLs — see {@link Files}. */
   files: Files;
+  /**
+   * Fires when the host cancels this call (idle timeout exceeded).
+   * Thread it into `fetch(url, { signal: ctx.signal })` or SDK calls so
+   * a cancelled call stops its outbound work too — the runtime already
+   * makes every later `ctx.*` call throw `CALL_CANCELLED`. Optional
+   * because older hosts don't send cancel frames.
+   */
+  signal?: AbortSignal;
 }
 
 /** Context for mutation handlers (read + write, transactional). */
@@ -716,12 +748,22 @@ export interface MutationCtx<R extends AuthRequirement = "optional"> {
   rooms: Rooms;
   /** Per-user OAuth connection registry. */
   connections: Connections;
+  /** Durable workflows: start / deliver events — see {@link Workflows}. */
+  workflows: Workflows;
   /** Signed file-download URLs — see {@link Files}. */
   files: Files;
   /** Create a typed error that triggers rollback. */
   error(code: string, message: string): Error;
   /** Assert org membership (optionally a role) — see {@link RequireMember}. */
   requireMember: RequireMember;
+  /**
+   * Fires when the host cancels this call (idle timeout exceeded).
+   * Thread it into `fetch(url, { signal: ctx.signal })` or SDK calls so
+   * a cancelled call stops its outbound work too — the runtime already
+   * makes every later `ctx.*` call throw `CALL_CANCELLED`. Optional
+   * because older hosts don't send cancel frames.
+   */
+  signal?: AbortSignal;
 }
 
 /** Context for action handlers (external I/O, non-transactional). */
@@ -737,6 +779,8 @@ export interface ActionCtx<R extends AuthRequirement = "optional"> {
   rooms: Rooms;
   /** Per-user OAuth connection registry. */
   connections: Connections;
+  /** Durable workflows: start / deliver events — see {@link Workflows}. */
+  workflows: Workflows;
   /** Environment variables / secrets. */
   env: Record<string, string>;
   /** Signed file-download URLs — see {@link Files}. */
@@ -755,6 +799,14 @@ export interface ActionCtx<R extends AuthRequirement = "optional"> {
   error(code: string, message: string): Error;
   /** Assert org membership (optionally a role) — see {@link RequireMember}. */
   requireMember: RequireMember;
+  /**
+   * Fires when the host cancels this call (idle timeout exceeded).
+   * Thread it into `fetch(url, { signal: ctx.signal })` or SDK calls so
+   * a cancelled call stops its outbound work too — the runtime already
+   * makes every later `ctx.*` call throw `CALL_CANCELLED`. Optional
+   * because older hosts don't send cancel frames.
+   */
+  signal?: AbortSignal;
   /**
    * HTTP request metadata — present only when the action was invoked via
    * a `defineRoute` HTTP binding. Missing when the action is called from