@pylonsync/functions 0.4.21 → 0.4.23

package/dist/agent-internals.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Internal functions backing the `agent()` loop. Registered by the
+ * runtime loader only when the app declares at least one agent.
+ *
+ * Both run under the CALLING user's auth (internal fns inherit the
+ * wrapping handler's auth — they are not admin), so every op verifies
+ * run ownership itself and stamps identity from `ctx.auth`, never from
+ * args. `internal: true` keeps them off the HTTP surface; the
+ * `__pylon_` prefix keeps their timeout out of the runner's
+ * wedge-probe budget.
+ */
+import type { FnDefinition } from "./types";
+export declare function registerAgentInternals(registry: Map<string, FnDefinition>): void;

package/dist/agent.d.ts

@@ -0,0 +1,103 @@
+/**
+ * `agent()` — a define-type for LLM agents with durable run state.
+ *
+ * ```ts
+ * // functions/researcher.ts
+ * export default agent({
+ *   system: "You are a research assistant.",
+ *   tools: {
+ *     searchDocs: {
+ *       description: "Search the document library",
+ *       args: { query: v.string() },
+ *       handler: async (ctx, { query }) => ctx.runQuery("findSimilar", { query }),
+ *     },
+ *   },
+ * });
+ * ```
+ *
+ * An agent compiles to an ordinary streaming ACTION (named after its
+ * file, callable via `streamFn("researcher", { input })`), whose
+ * handler runs the tool loop:
+ *
+ *   1. Create an `AgentRun` row (or load one when `runId` is passed —
+ *      that's how a conversation continues) and append the user's
+ *      input as an `AgentMessage`.
+ *   2. `ctx.llm.stream` with the declared tools; text deltas flow to
+ *      `ctx.stream` (resumable — the run row records the stream id).
+ *   3. On `stop_reason === "tool_use"`: validate each tool call's
+ *      input against its validators, run the handler, record the
+ *      call + result as messages, loop.
+ *   4. Terminal: run marked completed/failed.
+ *
+ * `AgentRun` and `AgentMessage` are real synced entities (injected
+ * into the manifest by the SDK when any agent exists), owner-scoped by
+ * policy — so `db.useQuery("AgentMessage", { where: { runId } })`
+ * shows the transcript live on every one of the user's devices,
+ * including tool calls, with zero extra plumbing.
+ */
+import type { ActionCtx, AnyValidator, FnDefinition, ValidatorSchema } from "./types";
+/** One tool an agent can call. */
+export interface AgentTool {
+    /** Shown to the model — say when to use the tool, not how it works. */
+    description: string;
+    /** Argument validators (same `v.*` schema as functions). The model's
+     *  JSON is validated before the handler runs; invalid input becomes
+     *  a tool_result error the model can react to. Omit for no-arg tools. */
+    args?: ValidatorSchema;
+    /** Runs with the agent action's ctx (runQuery/runMutation, llm,
+     *  email, …). The return value is JSON-serialized into the
+     *  tool_result the model sees. Throwing marks the result is_error —
+     *  the model sees the message and can recover. */
+    handler: (ctx: ActionCtx, input: Record<string, unknown>) => unknown;
+}
+export interface AgentDefinition {
+    /** System prompt. A function receives the ctx + call args for
+     *  per-user prompts. */
+    system?: string | ((ctx: ActionCtx, args: AgentCallArgs) => string);
+    tools?: Record<string, AgentTool>;
+    /** Model override (subject to the server's allowlist). */
+    model?: string;
+    /** Max model↔tool round-trips per invocation (default 16). Hitting
+     *  the cap fails the run rather than looping forever. */
+    maxSteps?: number;
+    /** max_tokens per completion (default: server default). */
+    maxTokens?: number;
+    /** Auth gate for the action (default "user" — runs are owner-scoped,
+     *  so an authenticated caller is the natural default). */
+    auth?: "user" | "admin";
+    /** Idle timeout in seconds (default 600; activity extends it). */
+    timeout?: number;
+}
+/** The synthesized action's args. */
+export interface AgentCallArgs {
+    /** The user's message for this turn. */
+    input: string;
+    /** Continue an existing run (must belong to the caller and this
+     *  agent). Omit to start a new run. */
+    runId?: string;
+    /** Optional display title, stored on new runs. */
+    title?: string;
+}
+/** What the agent action resolves with (also the `event: result`
+ *  payload on the SSE stream). */
+export interface AgentResult {
+    runId: string;
+    /** Concatenated text of the final assistant message. */
+    text: string;
+    /** Round-trips consumed. */
+    steps: number;
+    usage: {
+        input_tokens: number;
+        output_tokens: number;
+    };
+}
+/** Convert one `v.*` validator to a JSON-Schema fragment. */
+export declare function validatorToJsonSchema(val: AnyValidator): Record<string, unknown>;
+/** Convert a validator schema (a tool's `args`) to a JSON-Schema
+ *  object with `required` derived from non-optional fields. */
+export declare function validatorSchemaToJsonSchema(schema: ValidatorSchema): Record<string, unknown>;
+/** Marker so the SDK's discoverFunctions can detect agents and inject
+ *  the AgentRun/AgentMessage entities into the manifest. */
+export declare const AGENT_MARKER = "__pylonAgent";
+export declare function agent(def: AgentDefinition): FnDefinition<AgentCallArgs, AgentResult>;
+export declare function isAgentDefinition(value: unknown): boolean;

package/dist/index.d.ts

@@ -20,6 +20,8 @@
 export { query, mutation, action } from "./define";
 export { v } from "./validators";
 export { workflow } from "./workflows";
+export { agent, isAgentDefinition, validatorToJsonSchema, validatorSchemaToJsonSchema, } from "./agent";
+export type { AgentDefinition, AgentTool, AgentCallArgs, AgentResult, } from "./agent";
 export type { WorkflowDefinition, WorkflowRun, WorkflowRunRequest, WorkflowRunnerResponse, WorkflowStepResult, } from "./workflows";
 export { resetDb, installTestIsolation } from "./testing";
 export { slugifyName, availableSlug } from "./slugify";

package/dist/types.d.ts

@@ -255,10 +255,29 @@ 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 {
+    /**
+     * The host-assigned resumable-stream id for THIS call, present when
+     * the caller connected over SSE (`streamFn`). Persist it — e.g. on a
+     * run row — and any device can attach to the live stream (or fetch
+     * the buffered replay + final result) via `resumeStream(id)` /
+     * `GET /api/fn-streams/<id>`. Absent for non-streaming invocations
+     * (plain JSON calls, scheduled jobs).
+     */
+    readonly id?: string;
     /** 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 {
@@ -452,11 +471,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.21",
+  "version": "0.4.23",
   "description": "TypeScript function runtime for pylon — defines server-side queries, mutations, and actions.",
   "type": "module",
   "main": "src/index.ts",

package/src/agent-internals.ts

@@ -0,0 +1,161 @@
+/**
+ * Internal functions backing the `agent()` loop. Registered by the
+ * runtime loader only when the app declares at least one agent.
+ *
+ * Both run under the CALLING user's auth (internal fns inherit the
+ * wrapping handler's auth — they are not admin), so every op verifies
+ * run ownership itself and stamps identity from `ctx.auth`, never from
+ * args. `internal: true` keeps them off the HTTP surface; the
+ * `__pylon_` prefix keeps their timeout out of the runner's
+ * wedge-probe budget.
+ */
+
+import type { FnDefinition, MutationCtx, QueryCtx } from "./types";
+
+interface RunRow {
+  id: string;
+  agent: string;
+  status: string;
+  userId: string | null;
+  [key: string]: unknown;
+}
+
+function nowIso(): string {
+  return new Date().toISOString();
+}
+
+/** Ownership fence: admins pass; otherwise the run must belong to the
+ *  caller. Missing and foreign runs are indistinguishable (NOT_FOUND). */
+function requireOwnedRun(
+  ctx: QueryCtx | MutationCtx,
+  run: Record<string, unknown> | null,
+): RunRow {
+  const owned =
+    run &&
+    (ctx.auth.isAdmin ||
+      (typeof run.userId === "string" && run.userId === ctx.auth.userId));
+  if (!owned) {
+    const err = new Error("Run not found");
+    (err as { code?: string }).code = "RUN_NOT_FOUND";
+    throw err;
+  }
+  return run as unknown as RunRow;
+}
+
+export function registerAgentInternals(
+  registry: Map<string, FnDefinition>,
+): void {
+  registry.set("__pylon_agent_read", {
+    type: "query",
+    internal: true,
+    auth: "user",
+    handler: async (ctx: QueryCtx, args: Record<string, unknown>) => {
+      const runId = String(args.runId ?? "");
+      const run = await ctx.db.get("AgentRun", runId);
+      const owned = requireOwnedRun(ctx, run);
+      const messages = await ctx.db.query("AgentMessage", {
+        runId,
+        $order: { seq: "asc" },
+      });
+      return { run: owned, messages };
+    },
+  } as unknown as FnDefinition);
+
+  registry.set("__pylon_agent_write", {
+    type: "mutation",
+    internal: true,
+    auth: "user",
+    handler: async (ctx: MutationCtx, args: Record<string, unknown>) => {
+      const op = String(args.op ?? "");
+      switch (op) {
+        case "createRun": {
+          // Owner-scoped or nothing: a null-owner row would be
+          // invisible to everyone (policies guard with
+          // `auth.userId != null`), and before that guard existed it
+          // was readable by ANONYMOUS callers (null == null evaluates
+          // true in the policy engine). Refuse instead of storing an
+          // orphan — cron/system invocations must call the agent under
+          // a service user's auth.
+          const userId = ctx.auth.userId;
+          if (typeof userId !== "string" || userId === "") {
+            const err = new Error(
+              "Agent runs require a signed-in user; invoke the agent under a service user for system/cron calls",
+            );
+            (err as { code?: string }).code = "AGENT_REQUIRES_USER";
+            throw err;
+          }
+          const id = await ctx.db.insert("AgentRun", {
+            agent: String(args.agent ?? "agent"),
+            status: "idle",
+            userId,
+            title: args.title ?? null,
+            streamId: null,
+            error: null,
+            createdAt: nowIso(),
+            updatedAt: nowIso(),
+          });
+          return { id };
+        }
+        case "appendMessage": {
+          const runId = String(args.runId ?? "");
+          const run = requireOwnedRun(
+            ctx,
+            await ctx.db.get("AgentRun", runId),
+          );
+          // Single-writer per run (the loop rejects concurrent turns),
+          // so a read-then-insert seq is race-free in practice; the
+          // mutation's transaction covers the rest.
+          const last = await ctx.db.query("AgentMessage", {
+            runId,
+            $order: { seq: "desc" },
+            $limit: 1,
+          });
+          const seq =
+            last.length > 0 ? (Number(last[0].seq) || 0) + 1 : 1;
+          const id = await ctx.db.insert("AgentMessage", {
+            runId,
+            userId: run.userId,
+            seq,
+            role: String(args.role ?? "user"),
+            content: args.content ?? null,
+            createdAt: nowIso(),
+          });
+          await ctx.db.update("AgentRun", runId, { updatedAt: nowIso() });
+          return { id, seq };
+        }
+        case "setStatus": {
+          const runId = String(args.runId ?? "");
+          const run = requireOwnedRun(ctx, await ctx.db.get("AgentRun", runId));
+          // The loop's pre-flight RUN_BUSY check races with itself
+          // across concurrent turns; this in-transaction guard is the
+          // authoritative claim. A "running" row older than staleMs is
+          // a dead generation (process crash) and may be taken over.
+          if (args.guardNotRunning === true && run.status === "running") {
+            const staleMs = Number(args.staleMs) || 0;
+            const updatedAt = Date.parse(String(run.updatedAt ?? "")) || 0;
+            if (Date.now() - updatedAt < staleMs) {
+              const err = new Error(
+                "This run is already generating — wait for it to finish",
+              );
+              (err as { code?: string }).code = "RUN_BUSY";
+              throw err;
+            }
+          }
+          const patch: Record<string, unknown> = {
+            status: String(args.status ?? "idle"),
+            updatedAt: nowIso(),
+          };
+          if (args.error !== undefined) patch.error = args.error;
+          if (args.streamId !== undefined) patch.streamId = args.streamId;
+          const updated = await ctx.db.update("AgentRun", runId, patch);
+          return { updated };
+        }
+        default: {
+          const err = new Error(`Unknown agent write op "${op}"`);
+          (err as { code?: string }).code = "INVALID_OP";
+          throw err;
+        }
+      }
+    },
+  } as unknown as FnDefinition);
+}