@pylonsync/functions 0.4.20 → 0.4.22

package/dist/types.d.ts

@@ -134,11 +134,15 @@ export interface DbReader {
      * hits come back best-first with the full row on `doc` (vector
      * fields stripped — re-fetch by id if you need the embedding).
      *
+     * Available wherever `ctx.db` is — queries and mutations. Actions
+     * have no `ctx.db`: embed there, then `ctx.runQuery` a query that
+     * searches with the vector.
+     *
      * ```ts
-     * const [embedding] = await ctx.llm.embed(["how do I reset my password?"]);
+     * // In a query: the vector arrives as an arg (an action embedded it).
      * const { hits } = await ctx.db.vectorSearch("Doc", {
      *   field: "embedding",
-     *   vector: embedding,
+     *   vector,
      *   limit: 5,
      *   filter: { status: "published" },   // equality / IN pre-filter
      * });
@@ -251,10 +255,20 @@ export interface DbWriter extends DbReader {
      */
     advisoryLock(key: string): Promise<void>;
 }
+/**
+ * Progressive output to the calling client (SSE). Every fn stream is
+ * RESUMABLE: the host buffers each chunk under a server-assigned
+ * stream id (the `X-Pylon-Stream-Id` response header) with a
+ * monotonically increasing sequence, so a client that loses its
+ * connection reconnects to `GET /api/fn-streams/<id>` from its last
+ * cursor and misses nothing — including the terminal result after the
+ * handler already returned. The handler never blocks on (or notices)
+ * client disconnects; it just keeps writing.
+ */
 export interface Stream {
     /** Write a text chunk to the client (SSE). */
     write(data: string): void;
-    /** Write a typed SSE event. */
+    /** Write a typed SSE event (`event: <name>` framing on the wire). */
     writeEvent(event: string, data: string): void;
 }
 export interface Scheduler {
@@ -391,11 +405,12 @@ export interface Llm {
      * 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:
+     * retrieval. From an action (which has no `ctx.db`), store via a
+     * mutation:
      *
      * ```ts
      * const [vec] = await ctx.llm.embed([doc.body]);
-     * await ctx.db.update("Doc", doc.id, { embedding: vec });
+     * await ctx.runMutation("saveEmbedding", { docId: doc.id, embedding: vec });
      * ```
      *
      * The embeddings provider is a separate axis from chat: with
@@ -447,11 +462,16 @@ export type LlmStreamEvent = {
  * `useRoom(roomId, userId)`, and the same delivery path a member's
  * `broadcast()` uses.
  *
- * This is the surface for streaming agent output that must survive a
- * closed tab or reach a second device: write tokens to the room, and
- * every watcher gets them, not just the caller holding the HTTP
- * response. `ctx.stream.write` reaches only the one client that made
- * the call.
+ * This is the surface for fanning agent output out to a second device
+ * or a second tab that is CONNECTED RIGHT NOW: write tokens to the
+ * room and every current watcher gets them, not just the caller
+ * holding the HTTP response. Delivery is live-only — a subscriber that
+ * reconnects does NOT replay messages sent during its gap. For output
+ * that must survive a closed tab or a dropped connection, rely on the
+ * fn stream itself: every `ctx.stream` stream is buffered server-side
+ * and resumable by stream id (`streamFn`'s `onStreamId` +
+ * `resumeStream` in the clients), including the final result after the
+ * handler finished.
  *
  * Not available in queries — a reactive handler re-runs on every dep
  * change, which would re-broadcast each time.

package/package.json

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

package/src/types.ts

@@ -162,11 +162,15 @@ export interface DbReader {
    * hits come back best-first with the full row on `doc` (vector
    * fields stripped — re-fetch by id if you need the embedding).
    *
+   * Available wherever `ctx.db` is — queries and mutations. Actions
+   * have no `ctx.db`: embed there, then `ctx.runQuery` a query that
+   * searches with the vector.
+   *
    * ```ts
-   * const [embedding] = await ctx.llm.embed(["how do I reset my password?"]);
+   * // In a query: the vector arrives as an arg (an action embedded it).
    * const { hits } = await ctx.db.vectorSearch("Doc", {
    *   field: "embedding",
-   *   vector: embedding,
+   *   vector,
    *   limit: 5,
    *   filter: { status: "published" },   // equality / IN pre-filter
    * });
@@ -308,11 +312,21 @@ export interface DbWriter extends DbReader {
 // Streaming
 // ---------------------------------------------------------------------------
 
+/**
+ * Progressive output to the calling client (SSE). Every fn stream is
+ * RESUMABLE: the host buffers each chunk under a server-assigned
+ * stream id (the `X-Pylon-Stream-Id` response header) with a
+ * monotonically increasing sequence, so a client that loses its
+ * connection reconnects to `GET /api/fn-streams/<id>` from its last
+ * cursor and misses nothing — including the terminal result after the
+ * handler already returned. The handler never blocks on (or notices)
+ * client disconnects; it just keeps writing.
+ */
 export interface Stream {
   /** Write a text chunk to the client (SSE). */
   write(data: string): void;
 
-  /** Write a typed SSE event. */
+  /** Write a typed SSE event (`event: <name>` framing on the wire). */
   writeEvent(event: string, data: string): void;
 }
 
@@ -477,11 +491,12 @@ export interface Llm {
    * 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:
+   * retrieval. From an action (which has no `ctx.db`), store via a
+   * mutation:
    *
    * ```ts
    * const [vec] = await ctx.llm.embed([doc.body]);
-   * await ctx.db.update("Doc", doc.id, { embedding: vec });
+   * await ctx.runMutation("saveEmbedding", { docId: doc.id, embedding: vec });
    * ```
    *
    * The embeddings provider is a separate axis from chat: with
@@ -524,11 +539,16 @@ export type LlmStreamEvent =
  * `useRoom(roomId, userId)`, and the same delivery path a member's
  * `broadcast()` uses.
  *
- * This is the surface for streaming agent output that must survive a
- * closed tab or reach a second device: write tokens to the room, and
- * every watcher gets them, not just the caller holding the HTTP
- * response. `ctx.stream.write` reaches only the one client that made
- * the call.
+ * This is the surface for fanning agent output out to a second device
+ * or a second tab that is CONNECTED RIGHT NOW: write tokens to the
+ * room and every current watcher gets them, not just the caller
+ * holding the HTTP response. Delivery is live-only — a subscriber that
+ * reconnects does NOT replay messages sent during its gap. For output
+ * that must survive a closed tab or a dropped connection, rely on the
+ * fn stream itself: every `ctx.stream` stream is buffered server-side
+ * and resumable by stream id (`streamFn`'s `onStreamId` +
+ * `resumeStream` in the clients), including the final result after the
+ * handler finished.
  *
  * Not available in queries — a reactive handler re-runs on every dep
  * change, which would re-broadcast each time.