@pylonsync/functions 0.4.17 → 0.4.20

package/src/types.ts

@@ -156,6 +156,32 @@ export interface DbReader {
     query: Record<string, unknown>
   ): Promise<SearchResult>;
 
+  /**
+   * Exact k-nearest-neighbor search over a `field.vector(dims)` field.
+   * Cosine similarity by default (`metric: "dot" | "l2"` to change);
+   * hits come back best-first with the full row on `doc` (vector
+   * fields stripped — re-fetch by id if you need the embedding).
+   *
+   * ```ts
+   * const [embedding] = await ctx.llm.embed(["how do I reset my password?"]);
+   * const { hits } = await ctx.db.vectorSearch("Doc", {
+   *   field: "embedding",
+   *   vector: embedding,
+   *   limit: 5,
+   *   filter: { status: "published" },   // equality / IN pre-filter
+   * });
+   * ```
+   *
+   * Exact scan, not ANN: every non-NULL embedding is scored. Fine to
+   * ~100k rows per entity; past that, a dedicated vector store wins.
+   * Throws `VECTOR_FIELD_NOT_FOUND` when `field` isn't a vector field
+   * and `INVALID_QUERY` on dimension mismatch or bad filters.
+   */
+  vectorSearch(
+    entity: string,
+    query: VectorSearchQuery
+  ): Promise<VectorSearchResult>;
+
   /**
    * Cursor-paginated list. Pass `cursor` from a previous page's `nextCursor`
    * to continue; pass `null` for the first page.
@@ -196,6 +222,30 @@ export interface SearchResult<T = Record<string, unknown>> {
   tookMs: number;
 }
 
+/** Request shape for [`DbReader.vectorSearch`]. */
+export interface VectorSearchQuery {
+  /** The `vector(dims)` field to search. */
+  field: string;
+  /** Query embedding; length must equal the field's declared dims. */
+  vector: number[];
+  /** Max hits. Default 10, capped at 200. */
+  limit?: number;
+  /** Similarity metric. Default "cosine" (higher = closer);
+   *  "dot" (higher = closer); "l2" (Euclidean distance, lower = closer). */
+  metric?: "cosine" | "dot" | "l2";
+  /** Equality pre-filter applied in SQL before scoring. A plain value
+   *  means equality; an array means SQL `IN`; `null` means IS NULL. */
+  filter?: Record<string, unknown>;
+}
+
+/** Result shape for [`DbReader.vectorSearch`]. */
+export interface VectorSearchResult<T = Record<string, unknown>> {
+  /** Best-first hits for the chosen metric. */
+  hits: Array<{ id: string; score: number; doc: T }>;
+  /** Milliseconds spent scanning + scoring. */
+  tookMs: number;
+}
+
 // ---------------------------------------------------------------------------
 // Database — write operations (extends read)
 // ---------------------------------------------------------------------------
@@ -422,6 +472,32 @@ export interface Llm {
     request: LlmCompleteRequest,
     onEvent: (event: LlmStreamEvent) => void,
   ): Promise<LlmCompleteResponse>;
+
+  /**
+   * Batch-embed texts via the configured embeddings provider. One
+   * embedding per input, in input order. Pair with a
+   * `field.vector(dims)` field and `ctx.db.vectorSearch` for
+   * retrieval:
+   *
+   * ```ts
+   * const [vec] = await ctx.llm.embed([doc.body]);
+   * await ctx.db.update("Doc", doc.id, { embedding: vec });
+   * ```
+   *
+   * The embeddings provider is a separate axis from chat: with
+   * `OPENAI_API_KEY` set it defaults to OpenAI
+   * `text-embedding-3-small` (1536 dims) even when chat runs
+   * Anthropic; `PYLON_EMBEDDINGS_PROVIDER=voyage` + `VOYAGE_API_KEY`
+   * selects Voyage `voyage-3.5` (1024 dims).
+   * `PYLON_EMBEDDINGS_MODEL` overrides the model.
+   *
+   * Not available in queries (reactive re-runs would re-bill the
+   * provider) — embed in a mutation/action and store the vector.
+   * Errors carry `err.code`: `EMBEDDINGS_NOT_CONFIGURED`,
+   * `PROVIDER_HTTP_<code>`, `PROVIDER_UNREACHABLE`,
+   * `INVALID_REQUEST`.
+   */
+  embed(input: string[], opts?: { model?: string }): Promise<number[][]>;
 }
 
 /**
@@ -471,6 +547,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 +800,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 +824,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 +855,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 +875,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/src/workflows.test.ts

@@ -0,0 +1,199 @@
+/**
+ * Tests for the workflow slice executor (workflows.ts).
+ *
+ * The replay contract under test, in terms of the Rust engine's
+ * request/response protocol:
+ *   - a step at the current index EXECUTES and yields step_complete
+ *   - a step below the current index REPLAYS its recorded output
+ *   - sleep / waitForEvent at the frontier pause the run
+ *   - a delivered event (recorded as `event:<name>`) resumes with data
+ *   - falling off the end of the workflow fn yields complete
+ *   - a throwing step yields fail with the step's name
+ *   - a nondeterministic replay (missing recorded step) yields fail
+ */
+import { describe, expect, test } from "bun:test";
+import {
+  executeWorkflowSlice,
+  isWorkflowDefinition,
+  workflow,
+  type WorkflowRunRequest,
+  type WorkflowStepResult,
+} from "./workflows";
+import type { ActionCtx } from "./types";
+
+// The executor never touches ctx itself — it only passes it through to
+// step closures. A cast-through-unknown stub is enough.
+const ctx = {} as unknown as ActionCtx;
+
+function req(
+  currentStep: number,
+  completed: WorkflowStepResult[],
+  input: unknown = { userId: "u1" },
+): WorkflowRunRequest {
+  return {
+    workflow_id: "wf_1",
+    workflow_name: "onboarding",
+    input,
+    current_step: currentStep,
+    completed_steps: completed,
+  };
+}
+
+function done(name: string, output: unknown): WorkflowStepResult {
+  return { step_id: "s", name, status: "completed", output };
+}
+
+const executed: string[] = [];
+
+const def = workflow("onboarding", async (wf, _ctx) => {
+  const user = await wf.step("load-user", () => {
+    executed.push("load-user");
+    return { email: "a@b.co" };
+  });
+  await wf.step("send-welcome", () => {
+    executed.push("send-welcome");
+    return { sent: true, to: user.email };
+  });
+  await wf.sleep("24h");
+  const confirmation = await wf.waitForEvent<{ ok: boolean }>("confirmed");
+  return { finished: true, ok: confirmation.ok };
+});
+
+describe("executeWorkflowSlice", () => {
+  test("workflow() output passes the loader's shape check", () => {
+    expect(isWorkflowDefinition(def)).toBe(true);
+    expect(isWorkflowDefinition({ name: "x" })).toBe(false);
+  });
+
+  test("slice 0: executes the first step only", async () => {
+    executed.length = 0;
+    const res = await executeWorkflowSlice(def, req(0, []), ctx);
+    expect(res).toMatchObject({
+      action: "step_complete",
+      step_name: "load-user",
+      output: { email: "a@b.co" },
+    });
+    expect(executed).toEqual(["load-user"]);
+  });
+
+  test("slice 1: replays step 0's output, executes step 1", async () => {
+    executed.length = 0;
+    const res = await executeWorkflowSlice(
+      def,
+      req(1, [done("load-user", { email: "recorded@b.co" })]),
+      ctx,
+    );
+    expect(res).toMatchObject({
+      action: "step_complete",
+      step_name: "send-welcome",
+      // Proof the replay fed the RECORDED output into the live closure.
+      output: { sent: true, to: "recorded@b.co" },
+    });
+    expect(executed).toEqual(["send-welcome"]);
+  });
+
+  test("slice 2: pauses at sleep without re-executing steps", async () => {
+    executed.length = 0;
+    const res = await executeWorkflowSlice(
+      def,
+      req(2, [
+        done("load-user", { email: "a@b.co" }),
+        done("send-welcome", { sent: true }),
+      ]),
+      ctx,
+    );
+    expect(res).toEqual({ action: "sleep", duration: "24h" });
+    expect(executed).toEqual([]);
+  });
+
+  test("slice 3 (woken): pauses at waitForEvent", async () => {
+    const res = await executeWorkflowSlice(
+      def,
+      req(3, [
+        done("load-user", { email: "a@b.co" }),
+        done("send-welcome", { sent: true }),
+      ]),
+      ctx,
+    );
+    expect(res).toEqual({ action: "wait_event", event: "confirmed" });
+  });
+
+  test("slice 4 (event delivered): completes with the event data", async () => {
+    const res = await executeWorkflowSlice(
+      def,
+      req(4, [
+        done("load-user", { email: "a@b.co" }),
+        done("send-welcome", { sent: true }),
+        done("event:confirmed", { ok: true }),
+      ]),
+      ctx,
+    );
+    expect(res).toEqual({
+      action: "complete",
+      output: { finished: true, ok: true },
+    });
+  });
+
+  test("a throwing step fails with its name — engine retry accounting keys on it", async () => {
+    const failing = workflow("boom", async (wf) => {
+      await wf.step("explode", () => {
+        throw new Error("provider 500");
+      });
+    });
+    const res = await executeWorkflowSlice(failing, req(0, []), ctx);
+    expect(res).toEqual({
+      action: "fail",
+      error: "provider 500",
+      step_name: "explode",
+    });
+  });
+
+  test("nondeterministic replay (missing recorded step) fails loudly", async () => {
+    // current_step says 2 steps are done, but only one was recorded
+    // under a DIFFERENT name — the author reordered/renamed steps.
+    const res = await executeWorkflowSlice(
+      def,
+      req(2, [done("some-old-name", {})]),
+      ctx,
+    );
+    expect(res.action).toBe("fail");
+    expect((res as { error: string }).error).toContain("replay mismatch");
+  });
+
+  test("duplicate step names fail loudly instead of replaying the wrong output", async () => {
+    // The replay cache is name-keyed: without the uniqueness check, the
+    // second "fetch" would silently replay the FIRST record's output on
+    // every later slice — wrong data in a durability primitive.
+    const dup = workflow("dup", async (wf) => {
+      await wf.step("fetch", () => "A");
+      await wf.step("fetch", () => "B");
+    });
+    const res = await executeWorkflowSlice(
+      dup,
+      req(1, [done("fetch", "A")]),
+      ctx,
+    );
+    expect(res.action).toBe("fail");
+    expect((res as { error: string }).error).toContain("duplicate step name");
+  });
+
+  test("duplicate waitForEvent names fail loudly too", async () => {
+    const dup = workflow("dup-ev", async (wf) => {
+      await wf.waitForEvent("go");
+      await wf.waitForEvent("go");
+    });
+    const res = await executeWorkflowSlice(
+      dup,
+      req(1, [done("event:go", { n: 1 })]),
+      ctx,
+    );
+    expect(res.action).toBe("fail");
+    expect((res as { error: string }).error).toContain("duplicate event name");
+  });
+
+  test("a stepless workflow completes on its first slice", async () => {
+    const trivial = workflow("noop", async (wf) => ({ echoed: wf.input }));
+    const res = await executeWorkflowSlice(trivial, req(0, [], 42), ctx);
+    expect(res).toEqual({ action: "complete", output: { echoed: 42 } });
+  });
+});

package/src/workflows.ts

@@ -0,0 +1,252 @@
+/**
+ * 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 function workflow<TInput = unknown>(
+  name: string,
+  fn: (wf: WorkflowRun<TInput>, ctx: ActionCtx) => Promise<unknown>,
+  opts?: { description?: string; maxRetries?: number },
+): WorkflowDefinition<TInput> {
+  return {
+    __pylonWorkflow: true,
+    name,
+    description: opts?.description,
+    maxRetries: opts?.maxRetries,
+    fn,
+  };
+}
+
+/** Runtime shape check for a `workflows/` file's default export. */
+export function isWorkflowDefinition(v: unknown): v is WorkflowDefinition {
+  const w = v as WorkflowDefinition | undefined;
+  return (
+    !!w &&
+    w.__pylonWorkflow === true &&
+    typeof w.name === "string" &&
+    typeof w.fn === "function"
+  );
+}
+
+/** Control-flow sentinel: the slice reached a pause point. */
+class WorkflowPaused extends Error {
+  constructor(public response: WorkflowRunnerResponse) {
+    super("workflow paused");
+  }
+}
+
+/** Control-flow sentinel: a step past the current index was reached. */
+class SliceBoundary extends Error {
+  constructor(public response: WorkflowRunnerResponse) {
+    super("slice boundary");
+  }
+}
+
+/**
+ * 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 async function executeWorkflowSlice(
+  def: WorkflowDefinition,
+  request: WorkflowRunRequest,
+  ctx: ActionCtx,
+): Promise<WorkflowRunnerResponse> {
+  let index = 0;
+  let currentStepName = "";
+  // Name uniqueness is enforced, not just documented: the replay cache
+  // is name-keyed, so a duplicate step name would silently replay the
+  // FIRST record's output into the second call — wrong data in a
+  // durability primitive. Same for repeated waitForEvent names.
+  const seenNames = new Set<string>();
+  const claimName = (kind: "step" | "event", name: string) => {
+    const key = `${kind}:${name}`;
+    if (seenNames.has(key)) {
+      throw new Error(
+        `duplicate ${kind} name "${name}" in one workflow run — names must be unique (the replay cache is name-keyed)`,
+      );
+    }
+    seenNames.add(key);
+  };
+
+  const wf: WorkflowRun = {
+    id: request.workflow_id,
+    input: request.input,
+
+    async step<T>(name: string, fn: () => Promise<T> | T): Promise<T> {
+      claimName("step", name);
+      const myIndex = index++;
+      if (myIndex < request.current_step) {
+        // Replay: return the recorded output. Name-keyed lookup so an
+        // author inserting a step ahead of a recorded one fails loudly
+        // (missing name) instead of silently reusing the wrong output.
+        const done = request.completed_steps.find(
+          (s) => s.name === name && s.status === "completed",
+        );
+        if (!done) {
+          throw new Error(
+            `workflow replay mismatch: step "${name}" (index ${myIndex}) has no recorded result — ` +
+              "the step sequence must be deterministic across replays",
+          );
+        }
+        return done.output as T;
+      }
+      if (myIndex === request.current_step) {
+        currentStepName = name;
+        const started = Date.now();
+        const output = await fn();
+        throw new SliceBoundary({
+          action: "step_complete",
+          step_name: name,
+          output: output ?? null,
+          duration_ms: Date.now() - started,
+        });
+      }
+      throw new SliceBoundary({
+        action: "fail",
+        error: `internal: step "${name}" (index ${myIndex}) reached past the current slice`,
+        step_name: name,
+      });
+    },
+
+    async sleep(duration: string): Promise<void> {
+      const myIndex = index++;
+      if (myIndex < request.current_step) return; // already slept
+      throw new WorkflowPaused({ action: "sleep", duration });
+    },
+
+    async waitForEvent<T>(eventName: string): Promise<T> {
+      claimName("event", eventName);
+      const myIndex = index++;
+      // A delivered event is recorded as a completed step named
+      // `event:<name>` (the Rust engine's send_event writes it).
+      const delivered = request.completed_steps.find(
+        (s) => s.name === `event:${eventName}` && s.status === "completed",
+      );
+      if (myIndex < request.current_step && delivered) {
+        return delivered.output as T;
+      }
+      throw new WorkflowPaused({ action: "wait_event", event: eventName });
+    },
+  };
+
+  try {
+    const output = await def.fn(wf, ctx);
+    return { action: "complete", output: output ?? null };
+  } catch (err) {
+    if (err instanceof SliceBoundary) return err.response;
+    if (err instanceof WorkflowPaused) return err.response;
+    const message =
+      err instanceof Error ? err.message : String(err ?? "unknown error");
+    return {
+      action: "fail",
+      error: message,
+      step_name: currentStepName || undefined,
+    };
+  }
+}