@pylonsync/functions 0.3.368 → 0.3.371

package/dist/index.d.ts

@@ -22,4 +22,4 @@ export { v } from "./validators";
 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, } from "./types";
+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";

package/dist/og-fixture-GZKcjt/app/opengraph-image.d.ts

@@ -0,0 +1,20 @@
+import React from "react";
+export default function OG(): {
+    __pylonImageResponse: boolean;
+    element: React.DetailedReactHTMLElement<{
+        style: {
+            display: "flex";
+            width: string;
+            height: string;
+            fontSize: number;
+            fontFamily: "Inter";
+        };
+    }, HTMLElement>;
+    options: {
+        width: number;
+        height: number;
+        headers: {
+            "cache-control": string;
+        };
+    };
+};

package/dist/og-fixture-GuniPy/app/opengraph-image.d.ts

@@ -0,0 +1 @@
+export default function OG(): void;

package/dist/og-fixture-IqNlbN/app/opengraph-image.d.ts

@@ -0,0 +1,20 @@
+import React from "react";
+export default function OG(): {
+    __pylonImageResponse: boolean;
+    element: React.DetailedReactHTMLElement<{
+        style: {
+            display: "flex";
+            width: string;
+            height: string;
+            fontSize: number;
+            fontFamily: "Inter";
+        };
+    }, HTMLElement>;
+    options: {
+        width: number;
+        height: number;
+        headers: {
+            "cache-control": string;
+        };
+    };
+};

package/dist/og-fixture-O6yotr/app/opengraph-image.d.ts

@@ -0,0 +1 @@
+export default function OG(): void;

package/dist/og-fixture-bCvDUF/app/opengraph-image.d.ts

@@ -0,0 +1 @@
+export default function OG(): void;

package/dist/og-fixture-fbkkcz/app/opengraph-image.d.ts

@@ -0,0 +1,20 @@
+import React from "react";
+export default function OG(): {
+    __pylonImageResponse: boolean;
+    element: React.DetailedReactHTMLElement<{
+        style: {
+            display: "flex";
+            width: string;
+            height: string;
+            fontSize: number;
+            fontFamily: "Inter";
+        };
+    }, HTMLElement>;
+    options: {
+        width: number;
+        height: number;
+        headers: {
+            "cache-control": string;
+        };
+    };
+};

package/dist/og-fixture-oY8CpY/app/opengraph-image.d.ts

@@ -0,0 +1,12 @@
+import React from "react";
+export declare const size: {
+    width: number;
+    height: number;
+};
+export default function OG(): React.DetailedReactHTMLElement<{
+    style: {
+        display: "flex";
+        fontSize: number;
+        fontFamily: "Inter";
+    };
+}, HTMLElement>;

package/dist/og-fixture-osS4Ik/app/opengraph-image.d.ts

@@ -0,0 +1,12 @@
+import React from "react";
+export declare const size: {
+    width: number;
+    height: number;
+};
+export default function OG(): React.DetailedReactHTMLElement<{
+    style: {
+        display: "flex";
+        fontSize: number;
+        fontFamily: "Inter";
+    };
+}, HTMLElement>;

package/dist/og-fixture-vRTMew/app/opengraph-image.d.ts

@@ -0,0 +1,20 @@
+import React from "react";
+export default function OG(): {
+    __pylonImageResponse: boolean;
+    element: React.DetailedReactHTMLElement<{
+        style: {
+            display: "flex";
+            width: string;
+            height: string;
+            fontSize: number;
+            fontFamily: "Inter";
+        };
+    }, HTMLElement>;
+    options: {
+        width: number;
+        height: number;
+        headers: {
+            "cache-control": string;
+        };
+    };
+};

package/dist/og-fixture-x2747s/app/opengraph-image.d.ts

@@ -0,0 +1,12 @@
+import React from "react";
+export declare const size: {
+    width: number;
+    height: number;
+};
+export default function OG(): React.DetailedReactHTMLElement<{
+    style: {
+        display: "flex";
+        fontSize: number;
+        fontFamily: "Inter";
+    };
+}, HTMLElement>;

package/dist/runtime.d.ts

@@ -14,6 +14,27 @@
  *   each ctx.db / ctx.scheduler / ctx.runMutation call), so the map never
  *   needs to queue multiple RPCs per call_id.
  */
-import type { DbReader, DbWriter } from "./types";
+import type { DbReader, DbWriter, Llm, Rooms } from "./types";
 export declare function buildDbReader(callId: string, ssrRead?: boolean): DbReader;
 export declare function buildDbWriter(callId: string): DbWriter;
+/**
+ * Build the LLM client that round-trips through the host runtime.
+ *
+ * Each call emits an `llm_complete` protocol message; the runtime
+ * forwards to the configured provider (PYLON_LLM_PROVIDER) and replies
+ * with the parsed response. The host enforces model-allowlist gating
+ * for non-admin callers — that's why the API key never leaves the
+ * server process.
+ *
+ * Errors carry an `err.code` so handlers can branch on `LLM_NOT_CONFIGURED`
+ * vs `PROVIDER_HTTP_429` vs `MODEL_NOT_ALLOWED` without parsing message
+ * strings.
+ */
+export declare function buildLlm(callId: string): Llm;
+/**
+ * Build the room broadcaster. One `room_broadcast` message per call;
+ * the host fans the event out through the same RoomManager the
+ * `/api/rooms/*` routes use, so a server push and a member push land
+ * on subscribers identically.
+ */
+export declare function buildRooms(callId: string): Rooms;

package/dist/types.d.ts

@@ -276,6 +276,84 @@ export interface Llm {
      * `PROVIDER_UNREACHABLE`, `INVALID_REQUEST`.
      */
     complete(request: LlmCompleteRequest): Promise<LlmCompleteResponse>;
+    /**
+     * Streaming completion. `onEvent` fires for each event as the
+     * provider emits it; the promise resolves with the same assembled
+     * response `complete` returns, so a tool-use loop can inspect
+     * `stop_reason` after the text has already been streamed out.
+     *
+     * The typical agent shape pumps deltas straight to the client:
+     *
+     * ```ts
+     * const res = await ctx.llm.stream(
+     *   { messages, tools },
+     *   (e) => { if (e.type === "text_delta") ctx.stream.write(e.text); },
+     * );
+     * if (res.stop_reason === "tool_use") { ...run tools, loop... }
+     * ```
+     *
+     * Streaming does NOT extend the function's call deadline — it is an
+     * absolute wall clock from invocation (PYLON_FN_CALL_TIMEOUT, 30s
+     * default). A long agent run must declare its own `timeout` on the
+     * function def.
+     *
+     * Same errors and same gating as {@link Llm.complete} — including
+     * the model allowlist, so streaming can't be used to reach a model
+     * `complete` would refuse.
+     */
+    stream(request: LlmCompleteRequest, onEvent: (event: LlmStreamEvent) => void): Promise<LlmCompleteResponse>;
+}
+/**
+ * One event from an in-flight {@link Llm.stream} call.
+ *
+ * `tool_use_start` opens a tool call; the `tool_input_delta` events
+ * that follow carry its arguments as raw JSON fragments — concatenate
+ * them and parse once, rather than parsing each fragment. `done`
+ * always fires last, including on a partial failure.
+ */
+export type LlmStreamEvent = {
+    type: "text_delta";
+    text: string;
+} | {
+    type: "tool_use_start";
+    id: string;
+    name: string;
+} | {
+    type: "tool_input_delta";
+    partial_json: string;
+} | {
+    type: "done";
+    stop_reason: string;
+    usage: {
+        input_tokens: number;
+        output_tokens: number;
+    };
+};
+/**
+ * Server-originated realtime push. Broadcasts an event to every
+ * subscriber of a presence room — the same rooms clients join with
+ * `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.
+ *
+ * Not available in queries — a reactive handler re-runs on every dep
+ * change, which would re-broadcast each time.
+ */
+export interface Rooms {
+    /**
+     * Push `data` to every subscriber of `room` under `topic`.
+     * Resolves `{ delivered: false }` when the room has no members —
+     * broadcasting into an empty room is a no-op, not an error, so an
+     * agent doesn't need to know whether anyone is watching.
+     */
+    broadcast(room: string, topic: string, data?: unknown): Promise<{
+        delivered: boolean;
+    }>;
 }
 export interface LlmMessage {
     role: "user" | "assistant" | "system" | "tool";
@@ -469,6 +547,8 @@ export interface MutationCtx<R extends AuthRequirement = "optional"> {
     env: Record<string, string>;
     /** Provider-abstracted LLM client. */
     llm: Llm;
+    /** Server-originated realtime push — see {@link Rooms}. */
+    rooms: Rooms;
     /** Per-user OAuth connection registry. */
     connections: Connections;
     /** Create a typed error that triggers rollback. */
@@ -485,6 +565,8 @@ export interface ActionCtx<R extends AuthRequirement = "optional"> {
     email: EmailSender;
     /** Provider-abstracted LLM client. */
     llm: Llm;
+    /** Server-originated realtime push — see {@link Rooms}. */
+    rooms: Rooms;
     /** Per-user OAuth connection registry. */
     connections: Connections;
     /** Environment variables / secrets. */

package/package.json

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

package/src/index.ts

@@ -54,4 +54,15 @@ export type {
   RequireMember,
   RequireMemberOptions,
   MemberRow,
+  // 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.
+  Llm,
+  LlmMessage,
+  LlmContentBlock,
+  LlmTool,
+  LlmCompleteRequest,
+  LlmCompleteResponse,
+  LlmStreamEvent,
+  Rooms,
 } from "./types";

package/src/og-fixture-GZKcjt/app/opengraph-image.tsx

@@ -0,0 +1,10 @@
+import React from "react";
+       export default function OG() {
+         return {
+           __pylonImageResponse: true,
+           element: React.createElement("div",
+             { style: { display: "flex", width: "100%", height: "100%", fontSize: 40, fontFamily: "Inter" } },
+             "Branded"),
+           options: { width: 500, height: 300, headers: { "cache-control": "public, max-age=60" } },
+         };
+       }

package/src/og-fixture-GuniPy/app/opengraph-image.tsx

@@ -0,0 +1 @@
+export default function OG() { throw new Error("boom"); }

package/src/og-fixture-IqNlbN/app/opengraph-image.tsx

@@ -0,0 +1,10 @@
+import React from "react";
+       export default function OG() {
+         return {
+           __pylonImageResponse: true,
+           element: React.createElement("div",
+             { style: { display: "flex", width: "100%", height: "100%", fontSize: 40, fontFamily: "Inter" } },
+             "Branded"),
+           options: { width: 500, height: 300, headers: { "cache-control": "public, max-age=60" } },
+         };
+       }

package/src/og-fixture-O6yotr/app/opengraph-image.tsx

@@ -0,0 +1 @@
+export default function OG() { throw new Error("boom"); }

package/src/og-fixture-bCvDUF/app/opengraph-image.tsx

@@ -0,0 +1 @@
+export default function OG() { throw new Error("boom"); }

package/src/og-fixture-fbkkcz/app/opengraph-image.tsx

@@ -0,0 +1,10 @@
+import React from "react";
+       export default function OG() {
+         return {
+           __pylonImageResponse: true,
+           element: React.createElement("div",
+             { style: { display: "flex", width: "100%", height: "100%", fontSize: 40, fontFamily: "Inter" } },
+             "Branded"),
+           options: { width: 500, height: 300, headers: { "cache-control": "public, max-age=60" } },
+         };
+       }

package/src/og-fixture-oY8CpY/app/opengraph-image.tsx

@@ -0,0 +1,6 @@
+import React from "react";
+       export const size = { width: 640, height: 360 };
+       export default function OG() {
+         return React.createElement("div",
+           { style: { display: "flex", fontSize: 32, fontFamily: "Inter" } }, "Bare");
+       }

package/src/og-fixture-osS4Ik/app/opengraph-image.tsx

@@ -0,0 +1,6 @@
+import React from "react";
+       export const size = { width: 640, height: 360 };
+       export default function OG() {
+         return React.createElement("div",
+           { style: { display: "flex", fontSize: 32, fontFamily: "Inter" } }, "Bare");
+       }

package/src/og-fixture-vRTMew/app/opengraph-image.tsx

@@ -0,0 +1,10 @@
+import React from "react";
+       export default function OG() {
+         return {
+           __pylonImageResponse: true,
+           element: React.createElement("div",
+             { style: { display: "flex", width: "100%", height: "100%", fontSize: 40, fontFamily: "Inter" } },
+             "Branded"),
+           options: { width: 500, height: 300, headers: { "cache-control": "public, max-age=60" } },
+         };
+       }

package/src/og-fixture-x2747s/app/opengraph-image.tsx

@@ -0,0 +1,6 @@
+import React from "react";
+       export const size = { width: 640, height: 360 };
+       export default function OG() {
+         return React.createElement("div",
+           { style: { display: "flex", fontSize: 32, fontFamily: "Inter" } }, "Bare");
+       }

package/src/runtime-llm-stream.test.ts

@@ -0,0 +1,186 @@
+/**
+ * Tests for `ctx.llm.stream` and `ctx.rooms.broadcast` (runtime.ts).
+ *
+ * The contract under test:
+ *
+ *   1. `stream()` emits ONE `llm_stream` frame carrying an `op_id`.
+ *   2. `llm_event` frames addressed to that op_id reach the caller's
+ *      `onEvent` in order, WITHOUT settling the promise.
+ *   3. The terminal `result` for that op_id resolves the promise with
+ *      the assembled response.
+ *   4. Events for a different op_id never leak into this stream's
+ *      callback — two concurrent streams stay separated.
+ *   5. A throwing `onEvent` doesn't abandon the RPC; the stream still
+ *      resolves.
+ *   6. `rooms.broadcast` emits a `room_broadcast` frame and resolves
+ *      with the host's `{delivered}` verdict.
+ *
+ * runtime.ts runs main() on import (it IS the bun runner entrypoint),
+ * so this drives the REAL dispatcher in a child process: we write host
+ * frames to its stdin and read what it emits on 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 { buildLlm, buildRooms } from ${JSON.stringify(RUNTIME)};
+
+const llm = buildLlm("c_1");
+const rooms = buildRooms("c_2");
+
+const seen = [];
+const other = [];
+
+// Stream A — the one under test. Its onEvent records every event.
+const a = llm.stream({ messages: [] }, (e) => { seen.push(e); });
+// Stream B — concurrent, and its callback THROWS. Neither may disturb A.
+const b = llm.stream({ messages: [] }, (e) => {
+  other.push(e);
+  throw new Error("handler callback blew up");
+});
+const r = rooms.broadcast("room-1", "agent.delta", { text: "hi" });
+
+const [aRes, bRes, rRes] = await Promise.all([a, b, r]);
+
+console.error("RESULT " + JSON.stringify({
+  seen,
+  other,
+  aStop: aRes.stop_reason,
+  bStop: bRes.stop_reason,
+  delivered: rRes.delivered,
+}));
+process.exit(0);
+`;
+
+/** Collect NDJSON frames from a chunk of the child's stdout. */
+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("llm.stream routes events by op_id, resolves on result; rooms.broadcast round-trips", async () => {
+  const dir = mkdtempSync(join(tmpdir(), "pylon-fn-llm-"));
+  const scriptPath = join(dir, "probe.ts");
+  writeFileSync(scriptPath, SCRIPT);
+
+  // Spawn the bun that's already running, by absolute path — resolving
+  // "bun" off PATH depends on the process cwd, which other test files
+  // in this suite move around.
+  const proc = Bun.spawn([process.execPath, scriptPath], {
+    stdin: "pipe",
+    stdout: "pipe",
+    stderr: "pipe",
+  });
+
+  // Read the child's request frames incrementally — we need its op_ids
+  // before we can address replies back to it.
+  const reader = proc.stdout.getReader();
+  const decoder = new TextDecoder();
+  let buffered = "";
+  // Wait for the three frames we care about. main() also emits a
+  // one-shot `ready` handshake on import, so count by type rather than
+  // by total frames.
+  let requests: Record<string, unknown>[] = [];
+  const wanted = (fs: Record<string, unknown>[]) =>
+    fs.filter((f) => f.type === "llm_stream").length >= 2 &&
+    fs.some((f) => f.type === "room_broadcast");
+  while (!wanted(requests)) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    buffered += decoder.decode(value, { stream: true });
+    requests = parseFrames(buffered);
+  }
+
+  const streams = requests.filter((f) => f.type === "llm_stream");
+  const broadcasts = requests.filter((f) => f.type === "room_broadcast");
+  expect(streams).toHaveLength(2);
+  expect(broadcasts).toHaveLength(1);
+
+  // 1. Each stream frame carries a distinct op_id — that's what makes
+  //    concurrent streams routable.
+  const opA = streams[0].op_id as string;
+  const opB = streams[1].op_id as string;
+  expect(opA).toBeTruthy();
+  expect(opB).toBeTruthy();
+  expect(opA).not.toBe(opB);
+
+  // 2. Broadcast frame carries the room, topic, and payload verbatim.
+  expect(broadcasts[0]).toMatchObject({
+    room: "room-1",
+    topic: "agent.delta",
+    data: { text: "hi" },
+  });
+
+  const send = (msg: Record<string, unknown>) =>
+    proc.stdin.write(JSON.stringify(msg) + "\n");
+
+  // Interleave A's and B's events so a routing bug (e.g. keying on
+  // call_id, or a single global sink) shows up as cross-talk.
+  send({ type: "llm_event", call_id: "c_1", op_id: opA, event: { type: "text_delta", text: "He" } });
+  send({ type: "llm_event", call_id: "c_1", op_id: opB, event: { type: "text_delta", text: "XX" } });
+  send({ type: "llm_event", call_id: "c_1", op_id: opA, event: { type: "text_delta", text: "llo" } });
+  send({
+    type: "llm_event",
+    call_id: "c_1",
+    op_id: opA,
+    event: { type: "tool_use_start", id: "t1", name: "search" },
+  });
+  send({
+    type: "llm_event",
+    call_id: "c_1",
+    op_id: opA,
+    event: { type: "tool_input_delta", partial_json: '{"q":' },
+  });
+
+  // Terminal results settle each stream.
+  send({
+    type: "result",
+    call_id: "c_1",
+    op_id: opA,
+    data: { model: "m", content: [], stop_reason: "tool_use", usage: { input_tokens: 1, output_tokens: 2 } },
+  });
+  send({
+    type: "result",
+    call_id: "c_1",
+    op_id: opB,
+    data: { model: "m", content: [], stop_reason: "end_turn", usage: { input_tokens: 0, output_tokens: 0 } },
+  });
+  send({
+    type: "result",
+    call_id: "c_2",
+    op_id: broadcasts[0].op_id,
+    data: { delivered: true },
+  });
+  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));
+
+  // 3+4. A saw exactly its own events, in order — B's "XX" never leaked.
+  expect(out.seen).toEqual([
+    { type: "text_delta", text: "He" },
+    { type: "text_delta", text: "llo" },
+    { type: "tool_use_start", id: "t1", name: "search" },
+    { type: "tool_input_delta", partial_json: '{"q":' },
+  ]);
+  expect(out.other).toEqual([{ type: "text_delta", text: "XX" }]);
+
+  // 5. Both promises resolved with their OWN response — including B,
+  //    whose callback threw on every event.
+  expect(out.aStop).toBe("tool_use");
+  expect(out.bStop).toBe("end_turn");
+
+  // 6. rooms.broadcast surfaced the host's verdict.
+  expect(out.delivered).toBe(true);
+});

package/src/runtime.ts

@@ -24,6 +24,8 @@ import type {
   Llm,
   LlmCompleteRequest,
   LlmCompleteResponse,
+  LlmStreamEvent,
+  Rooms,
   Connections,
   QueryCtx,
   MutationCtx,
@@ -175,6 +177,13 @@ const pendingRpcs = new Map<
   }
 >();
 
+/**
+ * Event sinks for in-flight streaming RPCs, keyed by op_id. Separate
+ * from `pendingRpcs` because these fire many times and never settle
+ * the promise — the terminal `result` message does that.
+ */
+const streamSinks = new Map<string, (event: unknown) => void>();
+
 let opSeq = 0;
 function nextOpId(callId: string): string {
   opSeq += 1;
@@ -307,6 +316,14 @@ function dispatch(line: string): void {
           error: err?.message || String(err),
         });
       });
+  } else if (msg.type === "llm_event") {
+    const ev = msg as unknown as {
+      call_id: string;
+      op_id?: string;
+      event: unknown;
+    };
+    const sink = streamSinks.get(ev.op_id ?? ev.call_id);
+    if (sink) sink(ev.event);
   } else if (msg.type === "result") {
     const res = msg as unknown as ResultMessage & { op_id?: string };
     // Prefer op_id when the host sent it. Fall back to call_id for replies
@@ -353,6 +370,63 @@ function rpcDb(
   });
 }
 
+/**
+ * RPC that receives interim events before its terminal reply
+ * (`ctx.llm.stream`). Mints an op_id like {@link rpcDb}, and also
+ * registers an event sink the dispatcher routes `llm_event` messages
+ * to. The promise resolves only on the final `result`.
+ *
+ * Each event RESTARTS the idle timeout: a stream that keeps producing
+ * is alive, however long it runs in total, while one whose provider
+ * goes silent still trips the safety net. The host's own call deadline
+ * remains the real upper bound.
+ */
+function rpcStreaming(
+  callId: string,
+  msg: Record<string, unknown>,
+  onEvent: (event: unknown) => void,
+): Promise<unknown> {
+  const opId = nextOpId(callId);
+  return new Promise((resolve, reject) => {
+    const fail = () => {
+      if (pendingRpcs.has(opId)) {
+        pendingRpcs.delete(opId);
+        streamSinks.delete(opId);
+        reject(
+          new Error(
+            `RPC timed out after ${RPC_TIMEOUT_MS}ms with no stream activity (call_id=${callId} op_id=${opId})`,
+          ),
+        );
+      }
+    };
+    const entry = {
+      resolve: (data: unknown) => {
+        streamSinks.delete(opId);
+        resolve(data);
+      },
+      reject: (err: Error) => {
+        streamSinks.delete(opId);
+        reject(err);
+      },
+      timeout: setTimeout(fail, RPC_TIMEOUT_MS),
+    };
+    pendingRpcs.set(opId, entry);
+    streamSinks.set(opId, (event) => {
+      clearTimeout(entry.timeout);
+      entry.timeout = setTimeout(fail, RPC_TIMEOUT_MS);
+      // A throwing sink must not abandon the pending RPC — the host is
+      // still going to send a terminal result, and swallowing here
+      // keeps the handler's own error the one that surfaces.
+      try {
+        onEvent(event);
+      } catch {
+        /* handler-side callback error; the stream continues */
+      }
+    });
+    send({ ...msg, call_id: callId, op_id: opId });
+  });
+}
+
 /**
  * RPC for non-db protocol replies (scheduler.runAfter, nested function
  * calls, etc.) where at-most-one in-flight per call_id is the right
@@ -657,7 +731,7 @@ function buildEmail(callId: string): EmailSender {
  * vs `PROVIDER_HTTP_429` vs `MODEL_NOT_ALLOWED` without parsing message
  * strings.
  */
-function buildLlm(callId: string): Llm {
+export function buildLlm(callId: string): Llm {
   return {
     async complete(request: LlmCompleteRequest): Promise<LlmCompleteResponse> {
       return (await rpc(callId, {
@@ -665,6 +739,36 @@ function buildLlm(callId: string): Llm {
         request,
       })) as LlmCompleteResponse;
     },
+
+    async stream(
+      request: LlmCompleteRequest,
+      onEvent: (event: LlmStreamEvent) => void,
+    ): Promise<LlmCompleteResponse> {
+      return (await rpcStreaming(
+        callId,
+        { type: "llm_stream", request },
+        (event) => onEvent(event as LlmStreamEvent),
+      )) as LlmCompleteResponse;
+    },
+  };
+}
+
+/**
+ * Build the room broadcaster. One `room_broadcast` message per call;
+ * the host fans the event out through the same RoomManager the
+ * `/api/rooms/*` routes use, so a server push and a member push land
+ * on subscribers identically.
+ */
+export function buildRooms(callId: string): Rooms {
+  return {
+    async broadcast(room: string, topic: string, data?: unknown) {
+      return (await rpcDb(callId, {
+        type: "room_broadcast",
+        room,
+        topic,
+        data: data ?? {},
+      })) as { delivered: boolean };
+    },
   };
 }
 
@@ -740,6 +844,7 @@ function buildActionCtx(
   scheduler: Scheduler,
   email: EmailSender,
   llm: Llm,
+  rooms: Rooms,
   connections: Connections,
   request?: unknown
 ): ActionCtx {
@@ -762,6 +867,7 @@ function buildActionCtx(
     scheduler,
     email,
     llm,
+    rooms,
     connections,
     env: process.env as Record<string, string>,
     async runQuery(fnName, args) {
@@ -866,6 +972,7 @@ async function handleCall(msg: CallMessage): Promise<void> {
   const scheduler = buildScheduler(msg.call_id);
   const email = buildEmail(msg.call_id);
   const llm = buildLlm(msg.call_id);
+  const rooms = buildRooms(msg.call_id);
   const connections = buildConnections(msg.call_id);
 
   // Normalize the Rust-side auth envelope (snake_case) to the camelCase
@@ -942,6 +1049,7 @@ async function handleCall(msg: CallMessage): Promise<void> {
         scheduler,
         env,
         llm,
+        rooms,
         connections,
         error(code, message) {
           const err = new Error(message);
@@ -962,6 +1070,7 @@ async function handleCall(msg: CallMessage): Promise<void> {
         scheduler,
         email,
         llm,
+        rooms,
         connections,
         (msg as unknown as { request?: unknown }).request,
       );

package/src/ssr-runtime.test.ts

@@ -279,7 +279,12 @@ const tmpDirs: string[] = [];
 function makeApp(): string {
   const dir = fs.mkdtempSync(path.join(os.tmpdir(), "pylon-og-"));
   tmpDirs.push(dir);
-  prevCwd = process.cwd();
+  // Only the FIRST call records the restore target. A second makeApp()
+  // in the same test would otherwise capture the previous temp dir,
+  // and afterEach would chdir back into it right before deleting it —
+  // leaving the whole process on a deleted cwd, which breaks every
+  // later test file that spawns a subprocess.
+  if (prevCwd === null) prevCwd = process.cwd();
   process.chdir(dir);
   return dir;
 }

package/src/types.ts

@@ -353,6 +353,83 @@ export interface Llm {
    * `PROVIDER_UNREACHABLE`, `INVALID_REQUEST`.
    */
   complete(request: LlmCompleteRequest): Promise<LlmCompleteResponse>;
+
+  /**
+   * Streaming completion. `onEvent` fires for each event as the
+   * provider emits it; the promise resolves with the same assembled
+   * response `complete` returns, so a tool-use loop can inspect
+   * `stop_reason` after the text has already been streamed out.
+   *
+   * The typical agent shape pumps deltas straight to the client:
+   *
+   * ```ts
+   * const res = await ctx.llm.stream(
+   *   { messages, tools },
+   *   (e) => { if (e.type === "text_delta") ctx.stream.write(e.text); },
+   * );
+   * if (res.stop_reason === "tool_use") { ...run tools, loop... }
+   * ```
+   *
+   * Streaming does NOT extend the function's call deadline — it is an
+   * absolute wall clock from invocation (PYLON_FN_CALL_TIMEOUT, 30s
+   * default). A long agent run must declare its own `timeout` on the
+   * function def.
+   *
+   * Same errors and same gating as {@link Llm.complete} — including
+   * the model allowlist, so streaming can't be used to reach a model
+   * `complete` would refuse.
+   */
+  stream(
+    request: LlmCompleteRequest,
+    onEvent: (event: LlmStreamEvent) => void,
+  ): Promise<LlmCompleteResponse>;
+}
+
+/**
+ * One event from an in-flight {@link Llm.stream} call.
+ *
+ * `tool_use_start` opens a tool call; the `tool_input_delta` events
+ * that follow carry its arguments as raw JSON fragments — concatenate
+ * them and parse once, rather than parsing each fragment. `done`
+ * always fires last, including on a partial failure.
+ */
+export type LlmStreamEvent =
+  | { type: "text_delta"; text: string }
+  | { type: "tool_use_start"; id: string; name: string }
+  | { type: "tool_input_delta"; partial_json: string }
+  | {
+      type: "done";
+      stop_reason: string;
+      usage: { input_tokens: number; output_tokens: number };
+    };
+
+/**
+ * Server-originated realtime push. Broadcasts an event to every
+ * subscriber of a presence room — the same rooms clients join with
+ * `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.
+ *
+ * Not available in queries — a reactive handler re-runs on every dep
+ * change, which would re-broadcast each time.
+ */
+export interface Rooms {
+  /**
+   * Push `data` to every subscriber of `room` under `topic`.
+   * Resolves `{ delivered: false }` when the room has no members —
+   * broadcasting into an empty room is a no-op, not an error, so an
+   * agent doesn't need to know whether anyone is watching.
+   */
+  broadcast(
+    room: string,
+    topic: string,
+    data?: unknown,
+  ): Promise<{ delivered: boolean }>;
 }
 
 export interface LlmMessage {
@@ -563,6 +640,8 @@ export interface MutationCtx<R extends AuthRequirement = "optional"> {
   env: Record<string, string>;
   /** Provider-abstracted LLM client. */
   llm: Llm;
+  /** Server-originated realtime push — see {@link Rooms}. */
+  rooms: Rooms;
   /** Per-user OAuth connection registry. */
   connections: Connections;
   /** Create a typed error that triggers rollback. */
@@ -580,6 +659,8 @@ export interface ActionCtx<R extends AuthRequirement = "optional"> {
   email: EmailSender;
   /** Provider-abstracted LLM client. */
   llm: Llm;
+  /** Server-originated realtime push — see {@link Rooms}. */
+  rooms: Rooms;
   /** Per-user OAuth connection registry. */
   connections: Connections;
   /** Environment variables / secrets. */