@pylonsync/functions 0.4.17 → 0.4.19

package/dist/define.d.ts

@@ -41,18 +41,28 @@ interface CommonDef<TSchema extends ValidatorSchema | undefined = ValidatorSchem
      */
     internal?: boolean;
     /**
-     * Max wall-clock SECONDS this function may run before the runtime
-     * recycles its worker as wedged. Defaults to `PYLON_FN_CALL_TIMEOUT`
-     * (30s). Raise it for legitimately long-running work — heavy renders,
-     * big batch jobs, slow external calls — so the call isn't force-killed
-     * mid-flight. This also lifts the runtime's wedge backstop for the
-     * worker while such a call is in flight, so a busy-but-progressing
-     * worker (e.g. one doing synchronous canvas/image work that blocks the
-     * event loop) isn't respawned out from under the work.
+     * IDLE-timeout SECONDS for this function: how long it may go without
+     * producing any activity (a stream chunk, a `ctx.db` op, an LLM
+     * event) before the host cancels the call. Defaults to
+     * `PYLON_FN_CALL_TIMEOUT` (30s). Activity restarts the budget, so a
+     * streaming agent run stays alive as long as it keeps producing; a
+     * silent hang is cancelled at the budget. Total lifetime is capped at
+     * 10× this value however chatty the call is.
      *
-     * Keep it as small as the work honestly needs: a genuinely stuck call
-     * still ties up its worker until this deadline. Prefer offloading very
-     * heavy CPU work to a dedicated service over setting a huge timeout.
+     * Cancellation is per-call: the handler's next `ctx.*` call throws
+     * `CALL_CANCELLED` and `ctx.signal` aborts — other in-flight calls on
+     * the same worker are untouched. CAVEAT: the database transaction
+     * rolls back on cancel, but non-ctx work already in flight (a `fetch`,
+     * a payment SDK call) runs to completion unless you pass
+     * `{ signal: ctx.signal }` — a cancelled call can otherwise leave an
+     * external effect committed with its DB writes rolled back. Thread
+     * ctx.signal into every external call that must not outlive the
+     * handler. Raise the timeout for legitimately long
+     * SILENT work (a single slow external call, synchronous CPU work);
+     * this also lifts the runtime's wedge backstop for the worker while
+     * such a call is in flight, so a busy-but-progressing worker (e.g.
+     * one doing synchronous canvas/image work that blocks the event loop)
+     * isn't respawned out from under the work.
      */
     timeout?: number;
 }

package/dist/index.d.ts

@@ -19,7 +19,9 @@
  */
 export { query, mutation, action } from "./define";
 export { v } from "./validators";
+export { workflow } from "./workflows";
+export type { WorkflowDefinition, WorkflowRun, WorkflowRunRequest, WorkflowRunnerResponse, WorkflowStepResult, } from "./workflows";
 export { resetDb, installTestIsolation } from "./testing";
 export { slugifyName, availableSlug } from "./slugify";
 export type { SsrResponse, SsrCookieOptions, SsrMetadata, Sitemap, SitemapEntry, Robots, RobotsRule, } from "./ssr-runtime";
-export type { QueryCtx, MutationCtx, ActionCtx, DbReader, DbWriter, Stream, Scheduler, AuthInfo, AuthMode, AuthRequirement, FnDefinition, Validator, AnyValidator, ValidatorSchema, InferValidator, InferArgs, RequireMember, RequireMemberOptions, MemberRow, Llm, LlmMessage, LlmContentBlock, LlmTool, LlmCompleteRequest, LlmCompleteResponse, LlmStreamEvent, Rooms, } from "./types";
+export type { QueryCtx, MutationCtx, ActionCtx, DbReader, DbWriter, Stream, Scheduler, AuthInfo, AuthMode, AuthRequirement, FnDefinition, Validator, AnyValidator, ValidatorSchema, InferValidator, InferArgs, RequireMember, RequireMemberOptions, MemberRow, Workflows, Llm, LlmMessage, LlmContentBlock, LlmTool, LlmCompleteRequest, LlmCompleteResponse, LlmStreamEvent, Rooms, } from "./types";

package/dist/runtime.d.ts

@@ -14,7 +14,7 @@
  *   each ctx.db / ctx.scheduler / ctx.runMutation call), so the map never
  *   needs to queue multiple RPCs per call_id.
  */
-import type { DbReader, DbWriter, Llm, Rooms } from "./types";
+import type { DbReader, DbWriter, Llm, Rooms, Workflows } from "./types";
 export declare function buildDbReader(callId: string, ssrRead?: boolean): DbReader;
 export declare function buildSsrFnCaller(callId: string): (name: string, args?: Record<string, unknown>) => Promise<unknown>;
 export declare function buildDbWriter(callId: string): DbWriter;
@@ -39,3 +39,11 @@ export declare function buildLlm(callId: string): Llm;
  * on subscribers identically.
  */
 export declare 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 declare function buildWorkflows(callId: string): Workflows;

package/dist/types.d.ts

@@ -392,6 +392,29 @@ export interface Rooms {
         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[];
@@ -607,6 +630,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). */
 export interface MutationCtx<R extends AuthRequirement = "optional"> {
@@ -622,12 +653,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). */
 export interface ActionCtx<R extends AuthRequirement = "optional"> {
@@ -642,6 +683,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}. */
@@ -654,6 +697,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

package/dist/workflows.d.ts

@@ -0,0 +1,128 @@
+/**
+ * Durable workflows: authoring surface + the per-slice executor.
+ *
+ * A workflow is a TS function that composes `step` / `sleep` /
+ * `waitForEvent` calls. The Rust WorkflowEngine owns the durable state
+ * (instance, step results, wake timers — persisted in SQLite); this
+ * module executes ONE slice at a time by REPLAY: on every advance the
+ * whole workflow function re-runs, already-completed steps return their
+ * recorded outputs without executing, and the first not-yet-done
+ * primitive either executes (a `step` at the current index) or pauses
+ * the run (`sleep` / `waitForEvent`).
+ *
+ * Determinism contract for authors: the sequence of step/sleep/
+ * waitForEvent calls must be identical on every replay for the same
+ * input + recorded outputs. Branch on `input` and on step OUTPUTS all
+ * you like — never on wall-clock time, randomness, or external state
+ * read outside a step.
+ *
+ * Files live in the app's `workflows/` directory (sibling of
+ * `functions/`), one default-exported `workflow(...)` per file. The
+ * runtime reports them in its ready handshake; the host registers them
+ * and drives execution back through the function pool as an internal
+ * `__pylon_workflow_run` action call — so step code runs with a full
+ * ActionCtx (ctx.db, ctx.llm, ctx.scheduler, the idle timeout, and
+ * cancellation) rather than in a bespoke side-channel process.
+ */
+import type { ActionCtx } from "./types";
+/** Wire shape of one recorded step — mirrors Rust `StepResult` exactly. */
+export interface WorkflowStepResult {
+    step_id: string;
+    name: string;
+    status: "pending" | "running" | "completed" | "failed" | "skipped";
+    output?: unknown;
+    error?: string | null;
+    started_at?: string | null;
+    completed_at?: string | null;
+    duration_ms?: number | null;
+    retry_count?: number;
+}
+/** The advance request the Rust engine sends for one slice. */
+export interface WorkflowRunRequest {
+    workflow_id: string;
+    workflow_name: string;
+    input: unknown;
+    current_step: number;
+    completed_steps: WorkflowStepResult[];
+}
+/** The verdict of one slice — mirrors Rust `apply_response`'s actions. */
+export type WorkflowRunnerResponse = {
+    action: "step_complete";
+    step_name: string;
+    output: unknown;
+    duration_ms: number;
+} | {
+    action: "sleep";
+    duration: string;
+} | {
+    action: "wait_event";
+    event: string;
+} | {
+    action: "complete";
+    output: unknown;
+} | {
+    action: "fail";
+    error: string;
+    step_name?: string;
+};
+/** What a workflow function receives, besides the per-slice ActionCtx. */
+export interface WorkflowRun<TInput = unknown> {
+    /** The workflow instance id (stable across slices + restarts). */
+    id: string;
+    /** The input `start()` was called with. */
+    input: TInput;
+    /**
+     * Run a named step exactly once. On replay a completed step returns
+     * its recorded output without executing. Step names must be unique
+     * within one workflow run — the replay cache is name-keyed.
+     */
+    step<T>(name: string, fn: () => Promise<T> | T): Promise<T>;
+    /** Pause the workflow for a duration ("30s", "5m", "24h", "7d"). */
+    sleep(duration: string): Promise<void>;
+    /**
+     * Pause until `POST /api/workflows/<id>/event` delivers this event.
+     * Resolves with the event's data payload.
+     */
+    waitForEvent<T = unknown>(eventName: string): Promise<T>;
+}
+export interface WorkflowDefinition<TInput = unknown> {
+    readonly __pylonWorkflow: true;
+    name: string;
+    description?: string;
+    /** Max retries per step before the workflow fails (engine default: 3). */
+    maxRetries?: number;
+    fn: (wf: WorkflowRun<TInput>, ctx: ActionCtx) => Promise<unknown>;
+}
+/**
+ * Declare a workflow. Default-export the result from a file in the
+ * app's `workflows/` directory:
+ *
+ * ```ts
+ * // workflows/onboarding.ts
+ * import { workflow } from "@pylonsync/functions";
+ *
+ * export default workflow("onboarding", async (wf, ctx) => {
+ *   const user = await wf.step("load-user", () =>
+ *     ctx.runQuery("getUser", { id: wf.input.userId }),
+ *   );
+ *   await wf.step("send-welcome", () =>
+ *     ctx.email.send({ to: user.email, subject: "Welcome!", text: "..." }),
+ *   );
+ *   await wf.sleep("24h");
+ *   const confirmed = await wf.waitForEvent("email_confirmed");
+ *   return { done: true, confirmed };
+ * });
+ * ```
+ */
+export declare function workflow<TInput = unknown>(name: string, fn: (wf: WorkflowRun<TInput>, ctx: ActionCtx) => Promise<unknown>, opts?: {
+    description?: string;
+    maxRetries?: number;
+}): WorkflowDefinition<TInput>;
+/** Runtime shape check for a `workflows/` file's default export. */
+export declare function isWorkflowDefinition(v: unknown): v is WorkflowDefinition;
+/**
+ * Execute one slice of `def` for `request`, returning the engine verdict.
+ * Never throws for handler errors — a step failure becomes
+ * `{action: "fail"}` so the engine's retry accounting runs.
+ */
+export declare function executeWorkflowSlice(def: WorkflowDefinition, request: WorkflowRunRequest, ctx: ActionCtx): Promise<WorkflowRunnerResponse>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pylonsync/functions",
-  "version": "0.4.17",
+  "version": "0.4.19",
   "description": "TypeScript function runtime for pylon — defines server-side queries, mutations, and actions.",
   "type": "module",
   "main": "src/index.ts",

package/src/define.ts

@@ -56,18 +56,28 @@ interface CommonDef<
    */
   internal?: boolean;
   /**
-   * Max wall-clock SECONDS this function may run before the runtime
-   * recycles its worker as wedged. Defaults to `PYLON_FN_CALL_TIMEOUT`
-   * (30s). Raise it for legitimately long-running work — heavy renders,
-   * big batch jobs, slow external calls — so the call isn't force-killed
-   * mid-flight. This also lifts the runtime's wedge backstop for the
-   * worker while such a call is in flight, so a busy-but-progressing
-   * worker (e.g. one doing synchronous canvas/image work that blocks the
-   * event loop) isn't respawned out from under the work.
+   * IDLE-timeout SECONDS for this function: how long it may go without
+   * producing any activity (a stream chunk, a `ctx.db` op, an LLM
+   * event) before the host cancels the call. Defaults to
+   * `PYLON_FN_CALL_TIMEOUT` (30s). Activity restarts the budget, so a
+   * streaming agent run stays alive as long as it keeps producing; a
+   * silent hang is cancelled at the budget. Total lifetime is capped at
+   * 10× this value however chatty the call is.
    *
-   * Keep it as small as the work honestly needs: a genuinely stuck call
-   * still ties up its worker until this deadline. Prefer offloading very
-   * heavy CPU work to a dedicated service over setting a huge timeout.
+   * Cancellation is per-call: the handler's next `ctx.*` call throws
+   * `CALL_CANCELLED` and `ctx.signal` aborts — other in-flight calls on
+   * the same worker are untouched. CAVEAT: the database transaction
+   * rolls back on cancel, but non-ctx work already in flight (a `fetch`,
+   * a payment SDK call) runs to completion unless you pass
+   * `{ signal: ctx.signal }` — a cancelled call can otherwise leave an
+   * external effect committed with its DB writes rolled back. Thread
+   * ctx.signal into every external call that must not outlive the
+   * handler. Raise the timeout for legitimately long
+   * SILENT work (a single slow external call, synchronous CPU work);
+   * this also lifts the runtime's wedge backstop for the worker while
+   * such a call is in flight, so a busy-but-progressing worker (e.g.
+   * one doing synchronous canvas/image work that blocks the event loop)
+   * isn't respawned out from under the work.
    */
   timeout?: number;
 }

package/src/index.ts

@@ -20,6 +20,14 @@
 
 export { query, mutation, action } from "./define";
 export { v } from "./validators";
+export { workflow } from "./workflows";
+export type {
+  WorkflowDefinition,
+  WorkflowRun,
+  WorkflowRunRequest,
+  WorkflowRunnerResponse,
+  WorkflowStepResult,
+} from "./workflows";
 export { resetDb, installTestIsolation } from "./testing";
 export { slugifyName, availableSlug } from "./slugify";
 // SSR page response controller — pages/layouts receive `response` in
@@ -54,6 +62,7 @@ export type {
   RequireMember,
   RequireMemberOptions,
   MemberRow,
+  Workflows,
   // LLM + realtime surfaces. A handler writing an agent tool loop
   // builds its own message array and branches on stream events, so
   // these have to be nameable from app code.

package/src/runtime-cancel.test.ts

@@ -0,0 +1,137 @@
+/**
+ * Tests for host-initiated call cancellation (runtime.ts `cancel` frames).
+ *
+ * The contract under test:
+ *
+ *   1. A `cancel` frame for a call REJECTS that call's in-flight RPC
+ *      promises with code CALL_CANCELLED (the handler's `await ctx.db.*`
+ *      unwinds instead of hanging on a reply that will never come).
+ *   2. Any LATER ctx RPC from the cancelled call throws CALL_CANCELLED —
+ *      this is what actually stops a typical handler mid-loop.
+ *   3. A different call on the same runner is untouched: its RPCs still
+ *      round-trip normally. This is the whole point of the change — the
+ *      host used to kill the entire child on one call's timeout.
+ *
+ * Same child-process harness as runtime-llm-stream.test.ts: runtime.ts
+ * runs main() on import, so we drive the REAL dispatcher over NDJSON on
+ * stdin/stdout exactly as the Rust host would.
+ */
+import { expect, test } from "bun:test";
+import { mkdtempSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+const RUNTIME = join(import.meta.dir, "runtime.ts");
+
+const SCRIPT = `
+import { buildDbReader } from ${JSON.stringify(RUNTIME)};
+
+const victim = buildDbReader("c_1");
+const bystander = buildDbReader("c_2");
+
+const out = {};
+
+// In-flight RPC on the call the host will cancel.
+const victimFirst = victim.get("User", "u1").then(
+  () => ({ outcome: "resolved" }),
+  (e) => ({ outcome: "rejected", code: e.code }),
+);
+// Concurrent RPC on an UNRELATED call — must complete normally.
+const bystanderGet = bystander.get("User", "u2").then(
+  (data) => ({ outcome: "resolved", data }),
+  (e) => ({ outcome: "rejected", code: e.code }),
+);
+
+out.victimFirst = await victimFirst;
+out.bystander = await bystanderGet;
+
+// A LATER RPC from the cancelled call must throw synchronously.
+try {
+  await victim.get("User", "u3");
+  out.victimSecond = { outcome: "resolved" };
+} catch (e) {
+  out.victimSecond = { outcome: "rejected", code: e.code };
+}
+
+console.error("RESULT " + JSON.stringify(out));
+process.exit(0);
+`;
+
+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>);
+}
+
+test("cancel rejects the call's RPCs, poisons later ones, and spares co-tenant calls", async () => {
+  const dir = mkdtempSync(join(tmpdir(), "pylon-fn-cancel-"));
+  const scriptPath = join(dir, "probe.ts");
+  writeFileSync(scriptPath, SCRIPT);
+
+  const proc = Bun.spawn([process.execPath, scriptPath], {
+    stdin: "pipe",
+    stdout: "pipe",
+    stderr: "pipe",
+  });
+
+  // Wait for both db frames (c_1's and c_2's) so we know their op_ids.
+  const reader = proc.stdout.getReader();
+  const decoder = new TextDecoder();
+  let buffered = "";
+  let requests: Record<string, unknown>[] = [];
+  const wanted = (fs: Record<string, unknown>[]) =>
+    fs.filter((f) => f.type === "db").length >= 2;
+  while (!wanted(requests)) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    buffered += decoder.decode(value, { stream: true });
+    requests = parseFrames(buffered);
+  }
+
+  const dbFrames = requests.filter((f) => f.type === "db");
+  const victimOp = dbFrames.find((f) => f.call_id === "c_1")?.op_id as string;
+  const bystanderOp = dbFrames.find((f) => f.call_id === "c_2")
+    ?.op_id as string;
+  expect(victimOp).toBeTruthy();
+  expect(bystanderOp).toBeTruthy();
+
+  const send = (msg: Record<string, unknown>) =>
+    proc.stdin.write(JSON.stringify(msg) + "\n");
+
+  // Cancel c_1 while its RPC is in flight; answer c_2 normally.
+  send({ type: "cancel", call_id: "c_1", reason: "idle timeout 30s exceeded" });
+  send({
+    type: "result",
+    call_id: "c_2",
+    op_id: bystanderOp,
+    data: { id: "u2", name: "Bystander" },
+  });
+  await proc.stdin.flush();
+
+  const stderr = await new Response(proc.stderr).text();
+  await proc.exited;
+
+  const line = stderr.split("\n").find((l) => l.includes("RESULT "));
+  expect(line).toBeDefined();
+  const out = JSON.parse(line!.slice(line!.indexOf("RESULT ") + 7));
+
+  // 1. The in-flight RPC rejected with the cancellation code — no hang,
+  //    no generic RPC-timeout 60s later.
+  expect(out.victimFirst).toEqual({
+    outcome: "rejected",
+    code: "CALL_CANCELLED",
+  });
+
+  // 2. The later RPC threw immediately with the same code.
+  expect(out.victimSecond).toEqual({
+    outcome: "rejected",
+    code: "CALL_CANCELLED",
+  });
+
+  // 3. The co-tenant call was untouched.
+  expect(out.bystander).toEqual({
+    outcome: "resolved",
+    data: { id: "u2", name: "Bystander" },
+  });
+});