@pylonsync/functions 0.4.22 → 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

@@ -266,6 +266,15 @@ export interface DbWriter extends DbReader {
  * 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 (`event: <name>` framing on the wire). */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pylonsync/functions",
-  "version": "0.4.22",
+  "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);
+}

package/src/agent.test.ts

@@ -0,0 +1,472 @@
+/**
+ * agent() unit tests: the validator→JSON-Schema converter and the tool
+ * loop driven against a scripted mock ctx (no Bun runner, no LLM).
+ */
+import { describe, expect, test } from "bun:test";
+import {
+  agent,
+  isAgentDefinition,
+  validatorSchemaToJsonSchema,
+} from "./agent";
+import { v } from "./validators";
+import type {
+  ActionCtx,
+  LlmCompleteRequest,
+  LlmCompleteResponse,
+  LlmStreamEvent,
+} from "./types";
+
+// ---------------------------------------------------------------------------
+// validator → JSON Schema
+// ---------------------------------------------------------------------------
+
+describe("validatorSchemaToJsonSchema", () => {
+  test("maps every validator shape losslessly", () => {
+    const schema = validatorSchemaToJsonSchema({
+      q: v.string(),
+      n: v.int(),
+      score: v.number(),
+      on: v.boolean(),
+      target: v.id("Doc"),
+      tags: v.array(v.string()),
+      opts: v.object({ deep: v.optional(v.boolean()) }),
+      kind: v.union(v.literal("a"), v.literal("b")),
+      blob: v.json(),
+      maybe: v.optional(v.string()),
+    });
+    expect(schema).toEqual({
+      type: "object",
+      properties: {
+        q: { type: "string" },
+        n: { type: "integer" },
+        score: { type: "number" },
+        on: { type: "boolean" },
+        target: { type: "string" },
+        tags: { type: "array", items: { type: "string" } },
+        opts: {
+          type: "object",
+          properties: { deep: { type: "boolean" } },
+        },
+        kind: { anyOf: [{ const: "a" }, { const: "b" }] },
+        blob: {},
+        maybe: { type: "string" },
+      },
+      required: ["q", "n", "score", "on", "target", "tags", "opts", "kind", "blob"],
+    });
+  });
+
+  test("empty schema produces an object schema with no required", () => {
+    expect(validatorSchemaToJsonSchema({})).toEqual({
+      type: "object",
+      properties: {},
+    });
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Mock ctx harness
+// ---------------------------------------------------------------------------
+
+interface WriteOp {
+  op: string;
+  [key: string]: unknown;
+}
+
+interface ReadOverride {
+  run?: Record<string, unknown>;
+  messages?: Array<Record<string, unknown>>;
+}
+
+function mockCtx(script: LlmCompleteResponse[], read?: ReadOverride) {
+  const writes: WriteOp[] = [];
+  const streamed: Array<{ event?: string; data: string }> = [];
+  let call = 0;
+  const ctx = {
+    auth: { userId: "u1", isAdmin: false, tenantId: null, roles: [] },
+    stream: {
+      id: "st_test",
+      write(data: string) {
+        streamed.push({ data });
+      },
+      writeEvent(event: string, data: string) {
+        streamed.push({ event, data });
+      },
+    },
+    llm: {
+      async stream(
+        _req: LlmCompleteRequest,
+        onEvent: (e: LlmStreamEvent) => void,
+      ): Promise<LlmCompleteResponse> {
+        const res = script[call];
+        call += 1;
+        if (!res) throw new Error("mock LLM script exhausted");
+        for (const block of res.content) {
+          if (block.type === "text") {
+            onEvent({ type: "text_delta", text: block.text });
+          }
+        }
+        onEvent({ type: "done", stop_reason: res.stop_reason, usage: res.usage });
+        return res;
+      },
+      async complete() {
+        throw new Error("not used");
+      },
+      async embed() {
+        throw new Error("not used");
+      },
+    },
+    async runQuery(name: string, args: Record<string, unknown>) {
+      if (name === "__pylon_agent_read") {
+        return {
+          run: {
+            id: String(args.runId),
+            agent: "helper",
+            status: "completed",
+            ...read?.run,
+          },
+          messages: read?.messages ?? [
+            { id: "m1", seq: 1, role: "user", content: "earlier question" },
+            {
+              id: "m2",
+              seq: 2,
+              role: "assistant",
+              content: [{ type: "text", text: "earlier answer" }],
+            },
+          ],
+        };
+      }
+      throw new Error(`unexpected query ${name}`);
+    },
+    async runMutation(name: string, args: Record<string, unknown>) {
+      if (name !== "__pylon_agent_write") throw new Error(`unexpected ${name}`);
+      writes.push(args as WriteOp);
+      if (args.op === "createRun") return { id: "run_1" };
+      if (args.op === "appendMessage") return { id: "m", seq: writes.length };
+      return { updated: true };
+    },
+    error(code: string, message: string) {
+      const err = new Error(message);
+      (err as { code?: string }).code = code;
+      return err;
+    },
+  };
+  return { ctx: ctx as unknown as ActionCtx, writes, streamed };
+}
+
+const done = (text: string): LlmCompleteResponse => ({
+  model: "m",
+  content: [{ type: "text", text }],
+  stop_reason: "end_turn",
+  usage: { input_tokens: 10, output_tokens: 5 },
+});
+
+const wantsTool = (
+  name: string,
+  input: Record<string, unknown>,
+): LlmCompleteResponse => ({
+  model: "m",
+  content: [
+    { type: "text", text: "Let me check." },
+    { type: "tool_use", id: "tu_1", name, input },
+  ],
+  stop_reason: "tool_use",
+  usage: { input_tokens: 20, output_tokens: 8 },
+});
+
+// ---------------------------------------------------------------------------
+// The loop
+// ---------------------------------------------------------------------------
+
+describe("agent loop", () => {
+  test("agent() produces a tagged action with the standard args", () => {
+    const def = agent({ system: "hi" });
+    expect((def as unknown as Record<string, unknown>).type).toBe("action");
+    expect((def as unknown as Record<string, unknown>).auth).toBe("user");
+    expect(isAgentDefinition(def)).toBe(true);
+    expect(isAgentDefinition(agent({}))).toBe(true);
+    expect(isAgentDefinition({ type: "action" })).toBe(false);
+  });
+
+  test("new run: tool round-trip, transcript order, terminal status", async () => {
+    const toolCalls: unknown[] = [];
+    const def = agent({
+      system: "You are helpful.",
+      tools: {
+        lookup: {
+          description: "Look something up",
+          args: { q: v.string() },
+          handler: async (_ctx, input) => {
+            toolCalls.push(input);
+            return { hits: 3 };
+          },
+        },
+      },
+    });
+    const { ctx, writes, streamed } = mockCtx([
+      wantsTool("lookup", { q: "pylon" }),
+      done("Found 3 hits."),
+    ]);
+
+    const result = await (def.handler as unknown as (
+      c: ActionCtx,
+      a: Record<string, unknown>,
+    ) => Promise<Record<string, unknown>>)(ctx, {
+      input: "search pylon",
+      __agentName: "helper",
+    });
+
+    expect(result.runId).toBe("run_1");
+    expect(result.text).toBe("Found 3 hits.");
+    expect(result.steps).toBe(2);
+    expect(result.usage).toEqual({ input_tokens: 30, output_tokens: 13 });
+    expect(toolCalls).toEqual([{ q: "pylon" }]);
+
+    // Write sequence: createRun, CLAIM (running, guarded, +streamId),
+    // user msg, assistant(tool_use), tool_result, assistant(final),
+    // completed. The claim precedes every message write so a losing
+    // racer never persists a stray turn.
+    expect(writes.map((w) => `${w.op}:${w.role ?? w.status ?? ""}`)).toEqual([
+      "createRun:",
+      "setStatus:running",
+      "appendMessage:user",
+      "appendMessage:assistant",
+      "appendMessage:user", // tool_result batch
+      "appendMessage:assistant",
+      "setStatus:completed",
+    ]);
+    const running = writes.find((w) => w.status === "running")!;
+    expect(running.streamId).toBe("st_test");
+    expect(running.guardNotRunning).toBe(true);
+    expect(Number(running.staleMs)).toBeGreaterThan(0);
+    const toolResultMsg = writes[4];
+    const blocks = toolResultMsg.content as Array<Record<string, unknown>>;
+    expect(blocks[0].type).toBe("tool_result");
+    expect(blocks[0].tool_use_id).toBe("tu_1");
+    expect(JSON.parse(String(blocks[0].content))).toEqual({ hits: 3 });
+
+    // Streaming: text deltas + a typed tool event.
+    expect(streamed.some((s) => s.data === "Let me check.")).toBe(true);
+    const toolEvent = streamed.find((s) => s.event === "tool")!;
+    expect(JSON.parse(toolEvent.data)).toEqual({
+      name: "lookup",
+      input: { q: "pylon" },
+      isError: false,
+    });
+  });
+
+  test("invalid tool input and unknown tools become is_error results", async () => {
+    const def = agent({
+      tools: {
+        strict: {
+          description: "needs a number",
+          args: { n: v.int() },
+          handler: async () => "never reached",
+        },
+      },
+    });
+    const { ctx, writes } = mockCtx([
+      {
+        model: "m",
+        content: [
+          { type: "tool_use", id: "tu_a", name: "strict", input: { n: "NaN" } },
+          { type: "tool_use", id: "tu_b", name: "ghost", input: {} },
+        ],
+        stop_reason: "tool_use",
+        usage: { input_tokens: 1, output_tokens: 1 },
+      },
+      done("Recovered."),
+    ]);
+
+    const result = await (def.handler as unknown as (
+      c: ActionCtx,
+      a: Record<string, unknown>,
+    ) => Promise<Record<string, unknown>>)(ctx, {
+      input: "go",
+      __agentName: "helper",
+    });
+    expect(result.text).toBe("Recovered.");
+
+    const toolResults = writes.find(
+      (w) =>
+        w.op === "appendMessage" &&
+        Array.isArray(w.content) &&
+        (w.content as Array<Record<string, unknown>>).some(
+          (b) => b.type === "tool_result",
+        ),
+    )!;
+    const blocks = (toolResults.content as Array<Record<string, unknown>>).filter(
+      (b) => b.type === "tool_result",
+    );
+    expect(blocks).toHaveLength(2);
+    expect(blocks.every((b) => b.is_error === true)).toBe(true);
+    expect(String(blocks[1].content)).toContain('Unknown tool "ghost"');
+  });
+
+  test("continuation loads history and rejects agent mismatch", async () => {
+    const def = agent({});
+    const { ctx, writes } = mockCtx([done("With context.")]);
+    const result = await (def.handler as unknown as (
+      c: ActionCtx,
+      a: Record<string, unknown>,
+    ) => Promise<Record<string, unknown>>)(ctx, {
+      input: "follow-up",
+      runId: "run_9",
+      __agentName: "helper",
+    });
+    expect(result.runId).toBe("run_9");
+    // No createRun for continuations.
+    expect(writes.some((w) => w.op === "createRun")).toBe(false);
+
+    // Wrong agent name → AGENT_MISMATCH.
+    const other = mockCtx([done("nope")]);
+    await expect(
+      (def.handler as unknown as (
+        c: ActionCtx,
+        a: Record<string, unknown>,
+      ) => Promise<unknown>)(other.ctx, {
+        input: "x",
+        runId: "run_9",
+        __agentName: "differentAgent",
+      }),
+    ).rejects.toThrow(/belongs to agent/);
+  });
+
+  test("a fresh running run is RUN_BUSY; a stale one is taken over", async () => {
+    const def = agent({ timeout: 600 });
+    const busy = mockCtx([done("never")], {
+      run: { status: "running", updatedAt: new Date().toISOString() },
+    });
+    await expect(
+      (def.handler as unknown as (
+        c: ActionCtx,
+        a: Record<string, unknown>,
+      ) => Promise<unknown>)(busy.ctx, {
+        input: "x",
+        runId: "run_9",
+        __agentName: "helper",
+      }),
+    ).rejects.toThrow(/already generating/);
+    expect(busy.writes).toHaveLength(0);
+
+    // updatedAt older than the timeout window → dead generation,
+    // continuation proceeds.
+    const stale = mockCtx([done("Took over.")], {
+      run: {
+        status: "running",
+        updatedAt: new Date(Date.now() - 700_000).toISOString(),
+      },
+    });
+    const result = await (def.handler as unknown as (
+      c: ActionCtx,
+      a: Record<string, unknown>,
+    ) => Promise<Record<string, unknown>>)(stale.ctx, {
+      input: "continue",
+      runId: "run_9",
+      __agentName: "helper",
+    });
+    expect(result.text).toBe("Took over.");
+  });
+
+  test("dangling tool_use in history is repaired with error results", async () => {
+    const def = agent({});
+    const { ctx, writes } = mockCtx([done("Recovered context.")], {
+      messages: [
+        { id: "m1", seq: 1, role: "user", content: "do the thing" },
+        {
+          id: "m2",
+          seq: 2,
+          role: "assistant",
+          content: [
+            { type: "text", text: "On it." },
+            { type: "tool_use", id: "tu_dead", name: "lookup", input: {} },
+          ],
+        },
+      ],
+    });
+    await (def.handler as unknown as (
+      c: ActionCtx,
+      a: Record<string, unknown>,
+    ) => Promise<unknown>)(ctx, {
+      input: "still there?",
+      runId: "run_9",
+      __agentName: "helper",
+    });
+    // The repair batch persists BEFORE the new user turn.
+    const repair = writes[1];
+    expect(repair.op).toBe("appendMessage");
+    const blocks = repair.content as Array<Record<string, unknown>>;
+    expect(blocks[0].type).toBe("tool_result");
+    expect(blocks[0].tool_use_id).toBe("tu_dead");
+    expect(blocks[0].is_error).toBe(true);
+    expect(String(blocks[0].content)).toContain("interrupted");
+    expect(writes[2].content).toBe("still there?");
+  });
+
+  test("oversized tool results are truncated before persisting", async () => {
+    const def = agent({
+      tools: {
+        dump: {
+          description: "returns a lot",
+          handler: async () => "x".repeat(80 * 1024),
+        },
+      },
+    });
+    const { ctx, writes } = mockCtx([
+      wantsTool("dump", {}),
+      done("Done."),
+    ]);
+    await (def.handler as unknown as (
+      c: ActionCtx,
+      a: Record<string, unknown>,
+    ) => Promise<unknown>)(ctx, { input: "go", __agentName: "helper" });
+    const toolResults = writes.find(
+      (w) =>
+        w.op === "appendMessage" &&
+        Array.isArray(w.content) &&
+        (w.content as Array<Record<string, unknown>>).some(
+          (b) => b.type === "tool_result",
+        ),
+    )!;
+    const block = (toolResults.content as Array<Record<string, unknown>>)[0];
+    const content = String(block.content);
+    expect(content.length).toBeLessThan(70 * 1024);
+    expect(content.endsWith("[truncated]")).toBe(true);
+  });
+
+  test("maxSteps overrun fails the run", async () => {
+    const def = agent({
+      maxSteps: 1,
+      tools: {
+        loop: {
+          description: "always called",
+          handler: async () => "again",
+        },
+      },
+    });
+    // The model asks for a tool every time — exceeds maxSteps=1.
+    const { ctx, writes } = mockCtx([
+      wantsTool("loop", {}),
+      wantsTool("loop", {}),
+    ]);
+    await expect(
+      (def.handler as unknown as (
+        c: ActionCtx,
+        a: Record<string, unknown>,
+      ) => Promise<unknown>)(ctx, { input: "go", __agentName: "helper" }),
+    ).rejects.toThrow(/tool round-trips/);
+    const failed = writes.find((w) => w.status === "failed")!;
+    expect(String(failed.error)).toContain("tool round-trips");
+  });
+
+  test("llm failure marks the run failed and rethrows", async () => {
+    const def = agent({});
+    const { ctx, writes } = mockCtx([]); // script exhausted immediately
+    await expect(
+      (def.handler as unknown as (
+        c: ActionCtx,
+        a: Record<string, unknown>,
+      ) => Promise<unknown>)(ctx, { input: "go", __agentName: "helper" }),
+    ).rejects.toThrow(/script exhausted/);
+    expect(writes.some((w) => w.status === "failed")).toBe(true);
+  });
+});

package/src/agent.ts

@@ -0,0 +1,430 @@
+/**
+ * `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 { action } from "./define";
+import { v, validateArgs } from "./validators";
+import type {
+  ActionCtx,
+  AnyValidator,
+  FnDefinition,
+  LlmContentBlock,
+  LlmMessage,
+  LlmTool,
+  ValidatorSchema,
+} from "./types";
+
+// ---------------------------------------------------------------------------
+// Public 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 };
+}
+
+// ---------------------------------------------------------------------------
+// Validators → JSON Schema (for LlmTool.input_schema)
+// ---------------------------------------------------------------------------
+
+/** Convert one `v.*` validator to a JSON-Schema fragment. */
+export function validatorToJsonSchema(val: AnyValidator): Record<string, unknown> {
+  const t = (val as { type: string }).type;
+  switch (t) {
+    case "string":
+      return { type: "string" };
+    case "int":
+      return { type: "integer" };
+    case "number":
+      return { type: "number" };
+    case "boolean":
+      return { type: "boolean" };
+    case "null":
+      return { type: "null" };
+    case "id":
+      return { type: "string" };
+    case "literal":
+      return { const: (val as { value: unknown }).value };
+    case "array":
+      return {
+        type: "array",
+        items: validatorToJsonSchema((val as { items: AnyValidator }).items),
+      };
+    case "object": {
+      const fields = (val as { fields: ValidatorSchema }).fields ?? {};
+      return validatorSchemaToJsonSchema(fields);
+    }
+    case "union": {
+      const variants = (val as { variants: AnyValidator[] }).variants ?? [];
+      return { anyOf: variants.map(validatorToJsonSchema) };
+    }
+    // json / any — anything goes; the empty schema is JSON Schema's
+    // "any value".
+    default:
+      return {};
+  }
+}
+
+/** Convert a validator schema (a tool's `args`) to a JSON-Schema
+ *  object with `required` derived from non-optional fields. */
+export function validatorSchemaToJsonSchema(
+  schema: ValidatorSchema,
+): Record<string, unknown> {
+  const properties: Record<string, unknown> = {};
+  const required: string[] = [];
+  for (const [name, val] of Object.entries(schema)) {
+    properties[name] = validatorToJsonSchema(val as AnyValidator);
+    if (!(val as { optional?: boolean }).optional) {
+      required.push(name);
+    }
+  }
+  const out: Record<string, unknown> = { type: "object", properties };
+  if (required.length > 0) out.required = required;
+  return out;
+}
+
+// ---------------------------------------------------------------------------
+// The define-type
+// ---------------------------------------------------------------------------
+
+/** Marker so the SDK's discoverFunctions can detect agents and inject
+ *  the AgentRun/AgentMessage entities into the manifest. */
+export const AGENT_MARKER = "__pylonAgent";
+
+export function agent(def: AgentDefinition): FnDefinition<AgentCallArgs, AgentResult> {
+  const fnDef = action({
+    args: {
+      input: v.string(),
+      runId: v.optional(v.string()),
+      title: v.optional(v.string()),
+    },
+    auth: def.auth ?? "user",
+    timeout: def.timeout ?? 600,
+    handler: (ctx: ActionCtx, args: AgentCallArgs) =>
+      runAgentLoop(def, ctx, args),
+  } as never) as FnDefinition<AgentCallArgs, AgentResult>;
+  (fnDef as unknown as Record<string, unknown>)[AGENT_MARKER] = true;
+  return fnDef;
+}
+
+export function isAgentDefinition(value: unknown): boolean {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    (value as Record<string, unknown>)[AGENT_MARKER] === true
+  );
+}
+
+// ---------------------------------------------------------------------------
+// The loop
+// ---------------------------------------------------------------------------
+
+const DEFAULT_MAX_STEPS = 16;
+
+/** Tool results persist into AgentMessage rows and replay into every
+ *  later completion's context — cap them so one oversized return can't
+ *  bloat the transcript (and the sync payloads) unboundedly. */
+const MAX_TOOL_RESULT_CHARS = 64 * 1024;
+
+function truncateToolResult(s: string): string {
+  if (s.length <= MAX_TOOL_RESULT_CHARS) return s;
+  return `${s.slice(0, MAX_TOOL_RESULT_CHARS)}\n[truncated]`;
+}
+
+interface StoredMessage {
+  id: string;
+  seq: number;
+  role: string;
+  content: unknown;
+}
+
+async function runAgentLoop(
+  def: AgentDefinition,
+  ctx: ActionCtx,
+  args: AgentCallArgs,
+): Promise<AgentResult> {
+  // The action's file-inferred name isn't visible here; the internal
+  // write mutation derives it from this marker arg set by the registry
+  // loader (see registerAgentInternals). Fallback "agent".
+  const agentName =
+    (args as unknown as Record<string, unknown>).__agentName?.toString() ??
+    "agent";
+
+  // A run left "running" longer than the agent's timeout is a dead
+  // generation (the process died before the terminal status write) —
+  // continuations may take it over instead of being RUN_BUSY forever.
+  const staleMs = Math.max(def.timeout ?? 600, 60) * 1000;
+
+  // 1. Create or load the run (ownership enforced inside the internal
+  // fns, which run under this caller's auth).
+  let runId: string;
+  let history: LlmMessage[] = [];
+  if (args.runId) {
+    const loaded = await ctx.runQuery<{
+      run: { id: string; agent: string; status: string; updatedAt?: string };
+      messages: StoredMessage[];
+    }>("__pylon_agent_read", { runId: args.runId });
+    if (loaded.run.agent !== agentName) {
+      throw ctx.error(
+        "AGENT_MISMATCH",
+        `Run ${args.runId} belongs to agent "${loaded.run.agent}"`,
+      );
+    }
+    if (loaded.run.status === "running") {
+      const updatedAt = Date.parse(String(loaded.run.updatedAt ?? "")) || 0;
+      if (Date.now() - updatedAt < staleMs) {
+        throw ctx.error(
+          "RUN_BUSY",
+          "This run is already generating — wait for it to finish",
+        );
+      }
+    }
+    runId = loaded.run.id;
+    history = loaded.messages.map(storedToLlmMessage);
+  } else {
+    const created = await ctx.runMutation<{ id: string }>(
+      "__pylon_agent_write",
+      { op: "createRun", agent: agentName, title: args.title ?? null },
+    );
+    runId = created.id;
+  }
+
+  const write = (op: Record<string, unknown>) =>
+    ctx.runMutation<Record<string, unknown>>("__pylon_agent_write", {
+      ...op,
+      runId,
+    });
+
+  // 2. Claim the run FIRST (guarded inside the mutation's transaction —
+  // the pre-flight check above races between concurrent turns), then
+  // write. The stream id lets other devices attach mid-generation.
+  await write({
+    op: "setStatus",
+    status: "running",
+    streamId: ctx.stream.id ?? null,
+    guardNotRunning: true,
+    staleMs,
+  });
+
+  // A crash between persisting an assistant tool_use turn and its
+  // tool_results leaves a transcript the LLM API rejects on replay.
+  // Repair with synthetic error results before the new user turn.
+  const lastMsg = history[history.length - 1];
+  if (lastMsg?.role === "assistant" && Array.isArray(lastMsg.content)) {
+    const dangling = lastMsg.content.filter(
+      (b): b is Extract<LlmContentBlock, { type: "tool_use" }> =>
+        (b as { type?: string }).type === "tool_use",
+    );
+    if (dangling.length > 0) {
+      const repairs: LlmContentBlock[] = dangling.map((b) => ({
+        type: "tool_result",
+        tool_use_id: b.id,
+        content: "tool execution was interrupted",
+        is_error: true,
+      }));
+      await write({ op: "appendMessage", role: "user", content: repairs });
+      history.push({ role: "user", content: repairs });
+    }
+  }
+
+  await write({ op: "appendMessage", role: "user", content: args.input });
+  history.push({ role: "user", content: args.input });
+
+  // Tool declarations for the model.
+  const tools: LlmTool[] = Object.entries(def.tools ?? {}).map(
+    ([name, tool]) => ({
+      name,
+      description: tool.description,
+      input_schema: validatorSchemaToJsonSchema(tool.args ?? {}),
+    }),
+  );
+
+  const maxSteps = def.maxSteps ?? DEFAULT_MAX_STEPS;
+  const usage = { input_tokens: 0, output_tokens: 0 };
+  let finalText = "";
+  let steps = 0;
+
+  try {
+    for (;;) {
+      steps += 1;
+      if (steps > maxSteps) {
+        throw ctx.error(
+          "AGENT_MAX_STEPS",
+          `Agent exceeded ${maxSteps} tool round-trips`,
+        );
+      }
+      const system =
+        typeof def.system === "function" ? def.system(ctx, args) : def.system;
+      const res = await ctx.llm.stream(
+        {
+          messages: history,
+          ...(system ? { system } : {}),
+          ...(tools.length > 0 ? { tools } : {}),
+          ...(def.model ? { model: def.model } : {}),
+          ...(def.maxTokens ? { max_tokens: def.maxTokens } : {}),
+        },
+        (e) => {
+          if (e.type === "text_delta") ctx.stream.write(e.text);
+        },
+      );
+      usage.input_tokens += res.usage.input_tokens;
+      usage.output_tokens += res.usage.output_tokens;
+
+      // Persist the assistant turn exactly as the model produced it
+      // (text + tool_use blocks) so history replays are faithful.
+      await write({ op: "appendMessage", role: "assistant", content: res.content });
+      history.push({ role: "assistant", content: res.content });
+      finalText = res.content
+        .filter((b): b is Extract<LlmContentBlock, { type: "text" }> => b.type === "text")
+        .map((b) => b.text)
+        .join("");
+
+      if (res.stop_reason !== "tool_use") break;
+
+      // 3. Execute every requested tool; failures become is_error
+      // results the model can react to rather than run-fatal throws.
+      const results: LlmContentBlock[] = [];
+      for (const block of res.content) {
+        if (block.type !== "tool_use") continue;
+        const tool = def.tools?.[block.name];
+        let content: string;
+        let isError = false;
+        if (!tool) {
+          content = `Unknown tool "${block.name}"`;
+          isError = true;
+        } else {
+          try {
+            if (tool.args) {
+              const check = validateArgs(block.input, tool.args);
+              if (!check.valid) {
+                throw new Error(`Invalid tool input: ${check.errors.join("; ")}`);
+              }
+            }
+            const value = await tool.handler(ctx, block.input);
+            content =
+              typeof value === "string" ? value : JSON.stringify(value ?? null);
+          } catch (err) {
+            content = err instanceof Error ? err.message : String(err);
+            isError = true;
+          }
+        }
+        content = truncateToolResult(content);
+        // Announce the tool call on the stream so live UIs can render
+        // "using searchDocs…" without polling the message rows.
+        ctx.stream.writeEvent(
+          "tool",
+          JSON.stringify({ name: block.name, input: block.input, isError }),
+        );
+        results.push({
+          type: "tool_result",
+          tool_use_id: block.id,
+          content,
+          ...(isError ? { is_error: true } : {}),
+        });
+      }
+      await write({ op: "appendMessage", role: "user", content: results });
+      history.push({ role: "user", content: results });
+    }
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    // Best-effort — the failure we surface is the loop's, not the
+    // bookkeeping write's.
+    await write({ op: "setStatus", status: "failed", error: message }).catch(
+      () => {},
+    );
+    throw err;
+  }
+
+  await write({ op: "setStatus", status: "completed" });
+  return { runId, text: finalText, steps, usage };
+}
+
+function storedToLlmMessage(m: StoredMessage): LlmMessage {
+  const role = m.role === "assistant" ? "assistant" : "user";
+  return { role, content: m.content as LlmMessage["content"] };
+}

package/src/index.ts

@@ -21,6 +21,18 @@
 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,

package/src/runtime.ts

@@ -788,8 +788,11 @@ function buildWriterOps(callId: string, unsafeOp: boolean): Omit<DbWriter, "unsa
   };
 }
 
-function buildStream(callId: string): Stream {
+function buildStream(callId: string, streamId?: string): Stream {
   return {
+    // Host-assigned resumable-stream id (SSE fn path only). Persist it
+    // to let other devices attach via GET /api/fn-streams/<id>.
+    id: streamId,
     write(data: string) {
       // Stream messages are fire-and-forget; they don't get a `result` reply.
       send({ type: "stream", call_id: callId, data });
@@ -1192,7 +1195,10 @@ async function handleCall(msg: CallMessage): Promise<void> {
   const abort = new AbortController();
   callAborts.set(msg.call_id, abort);
 
-  const stream = buildStream(msg.call_id);
+  const stream = buildStream(
+    msg.call_id,
+    (msg as { stream_id?: string }).stream_id,
+  );
   const scheduler = buildScheduler(msg.call_id);
   const email = buildEmail(msg.call_id);
   const llm = buildLlm(msg.call_id);
@@ -1405,6 +1411,8 @@ async function main() {
     files = [];
   }
 
+  const { isAgentDefinition, AGENT_MARKER } = await import("./agent");
+  let agentsPresent = false;
   for (const file of files) {
     const name = basename(file, file.endsWith(".ts") ? ".ts" : ".js");
     try {
@@ -1420,6 +1428,19 @@ async function main() {
         typeof anyDef.type === "string" &&
         typeof anyDef.handler === "function"
       ) {
+        if (isAgentDefinition(def)) {
+          // The agent loop needs its own registered name (for the
+          // AgentRun.agent column + continuation checks) but handlers
+          // don't know their filename — inject it post-validation.
+          agentsPresent = true;
+          const orig = anyDef.handler as (
+            ctx: unknown,
+            args: Record<string, unknown>,
+          ) => unknown;
+          anyDef.handler = (ctx: unknown, args: Record<string, unknown>) =>
+            orig(ctx, { ...args, __agentName: name });
+          void AGENT_MARKER;
+        }
         registry.set(name, def as FnDefinition);
       }
     } catch (err) {
@@ -1427,6 +1448,11 @@ async function main() {
     }
   }
 
+  if (agentsPresent) {
+    const { registerAgentInternals } = await import("./agent-internals");
+    registerAgentInternals(registry);
+  }
+
   // Workflows: scan the app's workflows/ dir (sibling of functions/).
   // Each file default-exports a `workflow(...)`. Declared names ride the
   // ready handshake so the host registers them with its WorkflowEngine;

package/src/types.ts

@@ -323,6 +323,16 @@ export interface DbWriter extends DbReader {
  * 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;