@pylonsync/functions 0.21.0 → 0.22.0

package/dist/agent.d.ts

@@ -36,6 +36,20 @@
  * including tool calls, with zero extra plumbing.
  */
 import type { ActionCtx, AnyValidator, FnDefinition, ValidatorSchema } from "./types";
+/** The run a tool call belongs to: the third argument of every tool
+ *  handler. */
+export interface AgentToolRun {
+    runId: string;
+    /** The agent's name (its file name in `functions/`). */
+    agent: string;
+    /** The user the run belongs to. */
+    userId: string | null;
+    /** The `context` server code passed to `ctx.agents.run`, or the one
+     *  stored on the run by an earlier `ctx.agents.run`. `null` when the
+     *  run has none (a run a client started with `streamFn`). Set only by
+     *  server code, so a tool can trust it to identify what it acts on. */
+    context: Record<string, unknown> | null;
+}
 /** One tool an agent can call. */
 export interface AgentTool {
     /** Shown to the model — say when to use the tool, not how it works. */
@@ -45,10 +59,11 @@ export interface AgentTool {
      *  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;
+     *  email, …). `run` identifies the run, including the server-set
+     *  `context` from `ctx.agents.run`. 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>, run: AgentToolRun) => unknown;
 }
 export interface AgentDefinition {
     /** System prompt. A function receives the ctx + call args for
@@ -83,8 +98,10 @@ export interface AgentCallArgs {
     /** Optional display title, stored on new runs. */
     title?: string;
     /** Ask the run to stop. Requires `runId`, ignores `input`, and
-     *  returns as soon as the request is recorded — a live generation
-     *  stops at its next turn boundary. */
+     *  returns as soon as the request is recorded. The running loop
+     *  notices within a few seconds: a model response in progress is
+     *  aborted (the provider stops generating), and a running tool sees
+     *  `ctx.signal` abort. */
     cancel?: boolean;
 }
 /** What the agent action resolves with (also the `event: result`
@@ -115,5 +132,9 @@ export declare function validatorSchemaToJsonSchema(schema: ValidatorSchema): Re
 /** Marker so the SDK's discoverFunctions can detect agents and inject
  *  the AgentRun/AgentMessage entities into the manifest. */
 export declare const AGENT_MARKER = "__pylonAgent";
+/** ctx key the runtime sets when server code started this call with
+ *  `ctx.agents.run`: `{ context }`. A symbol, so no JSON a client sends
+ *  can set it. */
+export declare const AGENT_INVOCATION: unique symbol;
 export declare function agent(def: AgentDefinition): FnDefinition<AgentCallArgs, AgentResult>;
 export declare function isAgentDefinition(value: unknown): boolean;

package/dist/index.d.ts

@@ -22,9 +22,9 @@ export { v } from "./validators";
 export { workflow } from "./workflows";
 export type { RawResponse, RawResponseInit } from "./response";
 export { agent, isAgentDefinition, validatorToJsonSchema, validatorSchemaToJsonSchema, } from "./agent";
-export type { AgentDefinition, AgentTool, AgentCallArgs, AgentResult, } from "./agent";
+export type { AgentDefinition, AgentTool, AgentToolRun, AgentCallArgs, AgentResult, } from "./agent";
 export type { WorkflowDefinition, WorkflowRun, WorkflowRunRequest, WorkflowRunnerResponse, WorkflowStepResult, } from "./workflows";
 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, Shards, ShardsReader, ShardsWriter, ShardInfo, ShardTransfer, MemberRow, Workflows, WorkflowRunSummary, WorkflowRunStatus, Audit, AuditLog, AuditEntry, VectorSearchQuery, VectorSearchResult, SearchResult, PaginationResult, Llm, LlmMessage, LlmContentBlock, LlmTool, LlmCompleteRequest, LlmCompleteResponse, LlmStreamEvent, Rooms, Domains, TenantDomainResult, TenantDomainRecord, TenantDomainDns, DomainAvailability, DomainContact, RegisterDomainOptions, RegisteredDomainResult, } from "./types";
+export type { QueryCtx, MutationCtx, ActionCtx, DbReader, DbWriter, Stream, Scheduler, AuthInfo, AuthMode, AuthRequirement, FnDefinition, Validator, AnyValidator, ValidatorSchema, InferValidator, InferArgs, RequireMember, RequireMemberOptions, Shards, ShardsReader, ShardsWriter, ShardInfo, ShardTransfer, MemberRow, Workflows, WorkflowRunSummary, WorkflowRunStatus, Audit, AuditLog, AuditEntry, Agents, AgentRunOptions, VectorSearchQuery, VectorSearchResult, SearchResult, PaginationResult, Llm, LlmMessage, LlmContentBlock, LlmTool, LlmCompleteRequest, LlmCompleteResponse, LlmStreamEvent, Rooms, Domains, TenantDomainResult, TenantDomainRecord, TenantDomainDns, DomainAvailability, DomainContact, RegisterDomainOptions, RegisteredDomainResult, } from "./types";

package/dist/types.d.ts

@@ -427,16 +427,24 @@ export interface Llm {
      * 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.
+     * The function's call timeout (PYLON_FN_CALL_TIMEOUT, 30s default, or
+     * the function's own `timeout`) is an idle timeout. A running stream
+     * counts as activity, but no call outlives 10× its timeout, so a long
+     * agent run should still declare its own `timeout`.
+     *
+     * Pass `{ signal }` to stop a stream early. When the signal aborts,
+     * the promise rejects with `err.code === "LLM_CANCELLED"` and the
+     * server closes the provider connection, so the model stops
+     * generating (and billing) tokens. A stream still running when the
+     * function returns or times out is cancelled the same way.
      *
      * 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>;
+    stream(request: LlmCompleteRequest, onEvent: (event: LlmStreamEvent) => void, options?: {
+        signal?: AbortSignal;
+    }): Promise<LlmCompleteResponse>;
     /**
      * Batch-embed texts via the configured embeddings provider. One
      * embedding per input, in input order. Pair with a
@@ -1237,6 +1245,49 @@ export interface Domains {
      *  itself serve the app — attach a host with `add()` afterward. */
     register(domainName: string, opts?: RegisterDomainOptions): Promise<RegisteredDomainResult>;
 }
+/** Options for {@link Agents.run}. */
+export interface AgentRunOptions {
+    /** The message for this turn. */
+    input: string;
+    /** Continue this run. It must belong to `as.userId` and this agent. */
+    runId?: string;
+    /** Display title, stored on a new run. */
+    title?: string;
+    /**
+     * The user the run belongs to and runs as. The run shows up in that
+     * user's synced `AgentRun`/`AgentMessage` rows. `admin: true` also
+     * gives the run admin rights (needed for an agent declared
+     * `auth: "admin"`), and is allowed only when the caller is an admin.
+     */
+    as: {
+        userId: string;
+        admin?: boolean;
+    };
+    /**
+     * JSON the agent's tool handlers receive as `run.context` (their third
+     * argument), for example the conversation a webhook turn belongs to.
+     * Stored on the run as `AgentRun.context`, so later turns of the run
+     * see it too. The run's owner can read it; do not put secrets in it.
+     */
+    context?: Record<string, unknown>;
+}
+/**
+ * Run an `agent()` from server code. See {@link ActionCtx.agents}.
+ */
+export interface Agents {
+    /**
+     * Run agent `name` (its file name in `functions/`) as `options.as`.
+     * Resolves with the agent's result once the turn finishes, like a
+     * `streamFn` call's final `result` event. The agent's tokens are not
+     * streamed to this caller; they are in the run's `AgentMessage` rows.
+     *
+     * Only server code can do this: the calling action must be
+     * `internal: true` (jobs, workflows, scheduled work) or run with admin
+     * rights (an admin session, or a webhook after `ctx.auth.elevate`).
+     * Otherwise it throws `AGENT_RUN_FORBIDDEN`.
+     */
+    run(name: string, options: AgentRunOptions): Promise<import("./agent").AgentResult>;
+}
 export interface ActionCtx<R extends AuthRequirement = "optional"> {
     auth: AuthInfo<R>;
     stream: Stream;
@@ -1253,6 +1304,8 @@ export interface ActionCtx<R extends AuthRequirement = "optional"> {
     workflows: Workflows;
     /** Application audit log — see {@link Audit}. */
     audit: Audit;
+    /** Run an `agent()` as a named user from server code — see {@link Agents}. */
+    agents: Agents;
     /** Attach / register custom domains for your app's OWN end-customers
      *  (platform domains) — see {@link Domains}. Cloud-only. */
     domains: Domains;

package/package.json

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

package/src/agent-internals.ts

@@ -128,6 +128,10 @@ export function registerAgentInternals(
             pendingInput: [],
             cancelRequested: false,
             steps: 0,
+            // Only written when present, so an app that declares its own
+            // AgentRun without a `context` column keeps working until it
+            // uses ctx.agents.run with a context.
+            ...(args.context != null ? { context: args.context } : {}),
             createdAt: nowIso(),
             updatedAt: nowIso(),
           });
@@ -188,6 +192,7 @@ export function registerAgentInternals(
           if (args.error !== undefined) patch.error = args.error;
           if (args.streamId !== undefined) patch.streamId = args.streamId;
           if (args.steps !== undefined) patch.steps = Number(args.steps) || 0;
+          if (args.context != null) patch.context = args.context;
           // Claiming the run starts a new generation, which supersedes
           // a cancel left set by one that died before acting on it.
           // Terminal statuses clear it because it has been honoured.

package/src/agent.test.ts

@@ -4,6 +4,7 @@
  */
 import { describe, expect, test } from "bun:test";
 import {
+  AGENT_INVOCATION,
   agent,
   isAgentDefinition,
   validatorSchemaToJsonSchema,
@@ -793,6 +794,210 @@ describe("agent loop", () => {
     expect(state.status).toBe("cancelled");
   }, 10_000);
 
+  test("a cancel raised while the model streams aborts the stream and keeps the partial text", async () => {
+    const def = agent({});
+    const { ctx, state, writes, streamed } = mockCtx([]);
+    let aborted = false;
+    let deltasAfterAbort = 0;
+    // A provider that keeps generating until the signal aborts, the way
+    // the host's ctx.llm.stream behaves.
+    (ctx.llm as { stream: unknown }).stream = (
+      _req: LlmCompleteRequest,
+      onEvent: (e: LlmStreamEvent) => void,
+      options?: { signal?: AbortSignal },
+    ) =>
+      new Promise<LlmCompleteResponse>((_resolve, reject) => {
+        const timer = setInterval(() => {
+          if (aborted) deltasAfterAbort += 1;
+          onEvent({ type: "text_delta", text: "tok " });
+        }, 20);
+        options?.signal?.addEventListener("abort", () => {
+          aborted = true;
+          clearInterval(timer);
+          const err = new Error("ctx.llm.stream was cancelled");
+          (err as { code?: string }).code = "LLM_CANCELLED";
+          reject(err);
+        });
+      });
+    setTimeout(() => {
+      state.cancelRequested = true;
+      state.pendingInput.push("queued while generating");
+    }, 50);
+
+    const result = await (def.handler as unknown as (
+      c: ActionCtx,
+      a: Record<string, unknown>,
+    ) => Promise<Record<string, unknown>>)(ctx, {
+      input: "write a long essay",
+      __agentName: "helper",
+    });
+
+    expect(result.cancelled).toBe(true);
+    expect(aborted).toBe(true);
+    expect(deltasAfterAbort).toBe(0);
+    expect(state.status).toBe("cancelled");
+    const tokens = streamed.filter((s) => s.event === undefined).length;
+    expect(tokens).toBeGreaterThan(0);
+    // The text the user saw is persisted as the assistant turn, and the
+    // queued message is not lost.
+    const appended = writes.filter((w) => w.op === "appendMessage");
+    expect(appended.map((w) => w.role)).toEqual(["user", "assistant", "user"]);
+    expect(appended[1].content).toEqual([
+      { type: "text", text: "tok ".repeat(tokens) },
+    ]);
+    expect(appended[2].content).toBe("queued while generating");
+    expect(result.text).toBe("tok ".repeat(tokens));
+  }, 10_000);
+
+  test("ctx.agents.run context reaches every tool and is stored on the new run", async () => {
+    const seen: unknown[] = [];
+    const def = agent({
+      tools: {
+        whoami: {
+          description: "who",
+          handler: async (_ctx, _input, run) => {
+            seen.push(run);
+            return "ok";
+          },
+        },
+      },
+    });
+    const { ctx, writes } = mockCtx([wantsTool("whoami", {}), done("bye")]);
+    (ctx as unknown as Record<symbol, unknown>)[AGENT_INVOCATION] = {
+      context: { conversationId: "conv-1" },
+    };
+    await (def.handler as unknown as (
+      c: ActionCtx,
+      a: Record<string, unknown>,
+    ) => Promise<unknown>)(ctx, { input: "hi", __agentName: "helper" });
+
+    expect(seen).toEqual([
+      {
+        runId: "run_1",
+        agent: "helper",
+        userId: "u1",
+        context: { conversationId: "conv-1" },
+      },
+    ]);
+    expect(writes.find((w) => w.op === "createRun")?.context).toEqual({
+      conversationId: "conv-1",
+    });
+  });
+
+  test("a continued run uses its stored context; a new invocation context replaces it", async () => {
+    const runs: unknown[] = [];
+    const def = agent({
+      tools: {
+        whoami: {
+          description: "who",
+          handler: async (_ctx, _input, run) => {
+            runs.push(run.context);
+            return "ok";
+          },
+        },
+      },
+    });
+    const call = (ctx: ActionCtx) =>
+      (def.handler as unknown as (
+        c: ActionCtx,
+        a: Record<string, unknown>,
+      ) => Promise<unknown>)(ctx, {
+        input: "again",
+        runId: "run_7",
+        __agentName: "helper",
+      });
+    const stored = { run: { userId: "owner", context: { conversationId: "old" } } };
+
+    // A client continuing over HTTP: no invocation, the stored context.
+    const first = mockCtx([wantsTool("whoami", {}), done("bye")], stored);
+    await call(first.ctx);
+    expect(
+      first.writes.find((w) => w.op === "setStatus" && w.status === "running")
+        ?.context,
+    ).toBeUndefined();
+
+    // Server code continuing with a new context: it wins and is stored.
+    const second = mockCtx([wantsTool("whoami", {}), done("bye")], stored);
+    (second.ctx as unknown as Record<symbol, unknown>)[AGENT_INVOCATION] = {
+      context: { conversationId: "new" },
+    };
+    await call(second.ctx);
+    expect(
+      second.writes.find((w) => w.op === "setStatus" && w.status === "running")
+        ?.context,
+    ).toEqual({ conversationId: "new" });
+
+    expect(runs).toEqual([{ conversationId: "old" }, { conversationId: "new" }]);
+  });
+
+  test("ctx.agents.run refuses a live run instead of queueing, and ignores a non-object context", async () => {
+    const seen: unknown[] = [];
+    const def = agent({
+      tools: {
+        whoami: {
+          description: "who",
+          handler: async (_ctx, _input, run) => {
+            seen.push(run.context);
+            return "ok";
+          },
+        },
+      },
+    });
+    const call = (ctx: ActionCtx, runId?: string) =>
+      (def.handler as unknown as (
+        c: ActionCtx,
+        a: Record<string, unknown>,
+      ) => Promise<unknown>)(ctx, {
+        input: "hi",
+        ...(runId ? { runId } : {}),
+        __agentName: "helper",
+      });
+
+    const busy = mockCtx([], {
+      run: { status: "running", updatedAt: new Date().toISOString() },
+    });
+    (busy.ctx as unknown as Record<symbol, unknown>)[AGENT_INVOCATION] = {
+      context: { conversationId: "c" },
+    };
+    await expect(call(busy.ctx, "run_7")).rejects.toMatchObject({ code: "RUN_BUSY" });
+    expect(busy.writes.some((w) => w.op === "enqueueInput")).toBe(false);
+
+    const odd = mockCtx([wantsTool("whoami", {}), done("bye")]);
+    (odd.ctx as unknown as Record<symbol, unknown>)[AGENT_INVOCATION] = {
+      context: ["not", "an", "object"],
+    };
+    await call(odd.ctx);
+    expect(seen).toEqual([null]);
+    expect(odd.writes.find((w) => w.op === "createRun")?.context).toBeUndefined();
+  });
+
+  test("a run a client started has no context, and args cannot supply one", async () => {
+    let context: unknown = "unset";
+    const def = agent({
+      tools: {
+        whoami: {
+          description: "who",
+          handler: async (_ctx, _input, run) => {
+            context = run.context;
+            return "ok";
+          },
+        },
+      },
+    });
+    const { ctx, writes } = mockCtx([wantsTool("whoami", {}), done("bye")]);
+    await (def.handler as unknown as (
+      c: ActionCtx,
+      a: Record<string, unknown>,
+    ) => Promise<unknown>)(ctx, {
+      input: "hi",
+      __agentName: "helper",
+      context: { conversationId: "forged" },
+      __agentContext: { conversationId: "forged" },
+    });
+    expect(context).toBeNull();
+    expect(writes.find((w) => w.op === "createRun")?.context).toBeUndefined();
+  });
+
   test("the default step budget is high enough for a real tool loop", async () => {
     // 16 was the old default and is nowhere near enough for an agent
     // that reads files before answering.

package/src/agent.ts

@@ -52,6 +52,21 @@ import type {
 // Public types
 // ---------------------------------------------------------------------------
 
+/** The run a tool call belongs to: the third argument of every tool
+ *  handler. */
+export interface AgentToolRun {
+  runId: string;
+  /** The agent's name (its file name in `functions/`). */
+  agent: string;
+  /** The user the run belongs to. */
+  userId: string | null;
+  /** The `context` server code passed to `ctx.agents.run`, or the one
+   *  stored on the run by an earlier `ctx.agents.run`. `null` when the
+   *  run has none (a run a client started with `streamFn`). Set only by
+   *  server code, so a tool can trust it to identify what it acts on. */
+  context: Record<string, unknown> | null;
+}
+
 /** One tool an agent can call. */
 export interface AgentTool {
   /** Shown to the model — say when to use the tool, not how it works. */
@@ -61,10 +76,15 @@ export interface AgentTool {
    *  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;
+   *  email, …). `run` identifies the run, including the server-set
+   *  `context` from `ctx.agents.run`. 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>,
+    run: AgentToolRun,
+  ) => unknown;
 }
 
 export interface AgentDefinition {
@@ -101,8 +121,10 @@ export interface AgentCallArgs {
   /** Optional display title, stored on new runs. */
   title?: string;
   /** Ask the run to stop. Requires `runId`, ignores `input`, and
-   *  returns as soon as the request is recorded — a live generation
-   *  stops at its next turn boundary. */
+   *  returns as soon as the request is recorded. The running loop
+   *  notices within a few seconds: a model response in progress is
+   *  aborted (the provider stops generating), and a running tool sees
+   *  `ctx.signal` abort. */
   cancel?: boolean;
 }
 
@@ -192,6 +214,26 @@ export function validatorSchemaToJsonSchema(
  *  the AgentRun/AgentMessage entities into the manifest. */
 export const AGENT_MARKER = "__pylonAgent";
 
+/** ctx key the runtime sets when server code started this call with
+ *  `ctx.agents.run`: `{ context }`. A symbol, so no JSON a client sends
+ *  can set it. */
+export const AGENT_INVOCATION = Symbol.for("pylon.agentInvocation");
+
+interface AgentInvocation {
+  context: Record<string, unknown> | null;
+}
+
+function invocationOf(ctx: ActionCtx): AgentInvocation | null {
+  const value = (ctx as unknown as Record<symbol, unknown>)[AGENT_INVOCATION];
+  return (value as AgentInvocation | undefined) ?? null;
+}
+
+function asContext(value: unknown): Record<string, unknown> | null {
+  return typeof value === "object" && value !== null && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : null;
+}
+
 export function agent(def: AgentDefinition): FnDefinition<AgentCallArgs, AgentResult> {
   const fnDef = action({
     args: {
@@ -223,10 +265,8 @@ export function isAgentDefinition(value: unknown): boolean {
 
 const DEFAULT_MAX_STEPS = 64;
 
-/** How often the loop asks whether cancel was requested while a tool
- *  handler is running. Only runs during a tool batch: the host blocks
- *  its per-call read loop for the whole of `ctx.llm.stream`, so no RPC
- *  the child issues during a generation would be serviced anyway. */
+/** How often the loop asks whether cancel was requested while a model
+ *  response streams or a tool handler runs. */
 const CANCEL_POLL_MS = 2000;
 
 /** Tool results persist into AgentMessage rows and replay into every
@@ -258,10 +298,7 @@ interface DrainResult {
  *  run. Prototype-based rather than a spread: ctx's methods keep
  *  working when invoked on the derived object. */
 function ctxWithSignal(ctx: ActionCtx, signal: AbortSignal): ActionCtx {
-  const combined =
-    ctx.signal && typeof AbortSignal.any === "function"
-      ? AbortSignal.any([ctx.signal, signal])
-      : signal;
+  const combined = anySignal(ctx.signal, signal);
   const derived = Object.create(ctx) as ActionCtx;
   Object.defineProperty(derived, "signal", {
     value: combined,
@@ -270,6 +307,56 @@ function ctxWithSignal(ctx: ActionCtx, signal: AbortSignal): ActionCtx {
   return derived;
 }
 
+/** Watches the run row for a cancel request while the loop is busy.
+ *
+ *  A poll rather than a push because a cancel can be requested on a
+ *  different machine than the loop runs on, and the run row is the only
+ *  thing both sides share. `signal` aborts once a cancel is seen; the
+ *  loop passes it to `ctx.llm.stream` (which then drops the provider
+ *  request) and to tool handlers through `ctx.signal`. */
+interface CancelWatch {
+  readonly signal: AbortSignal;
+  readonly cancelled: boolean;
+  stop(): void;
+}
+
+function watchCancel(ctx: ActionCtx, runId: string): CancelWatch {
+  const controller = new AbortController();
+  let polling = false;
+  const timer = setInterval(() => {
+    // Skip rather than stack: a slow poll must not queue more.
+    if (polling || controller.signal.aborted) return;
+    polling = true;
+    void ctx
+      .runQuery<{ cancelRequested: boolean }>("__pylon_agent_poll", { runId })
+      .then((s) => {
+        if (s.cancelRequested && !controller.signal.aborted) {
+          controller.abort(new Error("agent run cancelled"));
+        }
+      })
+      .catch(() => {})
+      .finally(() => {
+        polling = false;
+      });
+  }, CANCEL_POLL_MS);
+  return {
+    signal: controller.signal,
+    get cancelled() {
+      return controller.signal.aborted;
+    },
+    stop() {
+      clearInterval(timer);
+    },
+  };
+}
+
+/** `a` and `b` combined, for runtimes without `AbortSignal.any`. */
+function anySignal(a: AbortSignal | undefined, b: AbortSignal): AbortSignal {
+  if (!a) return b;
+  if (typeof AbortSignal.any === "function") return AbortSignal.any([a, b]);
+  return b;
+}
+
 async function runAgentLoop(
   def: AgentDefinition,
   ctx: ActionCtx,
@@ -321,6 +408,13 @@ async function runAgentLoop(
   // continuations may take it over instead of waiting forever.
   const staleMs = Math.max(def.timeout ?? 600, 60) * 1000;
 
+  // Server code that started this run with ctx.agents.run may pass a
+  // context for the tools. It wins over one stored on the run.
+  const invocation = invocationOf(ctx);
+  const invocationContext = asContext(invocation?.context);
+  let runContext = invocationContext;
+  let runUserId: string | null = ctx.auth.userId ?? null;
+
   // 1. Create or load the run (ownership enforced inside the internal
   // fns, which run under this caller's auth).
   let runId: string;
@@ -334,6 +428,8 @@ async function runAgentLoop(
         status: string;
         updatedAt?: string;
         steps?: number;
+        userId?: string | null;
+        context?: unknown;
       };
       messages: StoredMessage[];
     }>("__pylon_agent_read", { runId: args.runId });
@@ -345,6 +441,15 @@ async function runAgentLoop(
     }
     if (loaded.run.status === "running") {
       const updatedAt = Date.parse(String(loaded.run.updatedAt ?? "")) || 0;
+      if (Date.now() - updatedAt < staleMs && invocation) {
+        // Server code (ctx.agents.run) waits for this turn's reply and
+        // brings its own context; queueing would return an empty result
+        // and answer the input later under the running turn's context.
+        throw ctx.error(
+          "RUN_BUSY",
+          "This run is already generating — wait for it to finish",
+        );
+      }
       if (Date.now() - updatedAt < staleMs) {
         // The generation is alive. Hand it the message rather than
         // refusing the call: the loop drains the queue at its next
@@ -369,10 +474,17 @@ async function runAgentLoop(
     runId = loaded.run.id;
     priorSteps = Number(loaded.run.steps) || 0;
     history = loaded.messages.map(storedToLlmMessage);
+    runUserId = loaded.run.userId ?? runUserId;
+    runContext ??= asContext(loaded.run.context);
   } else {
     const created = await ctx.runMutation<{ id: string }>(
       "__pylon_agent_write",
-      { op: "createRun", agent: agentName, title: args.title ?? null },
+      {
+        op: "createRun",
+        agent: agentName,
+        title: args.title ?? null,
+        ...(invocationContext ? { context: invocationContext } : {}),
+      },
     );
     runId = created.id;
   }
@@ -392,6 +504,7 @@ async function runAgentLoop(
     streamId: ctx.stream.id ?? null,
     guardNotRunning: true,
     staleMs,
+    ...(args.runId && invocationContext ? { context: invocationContext } : {}),
   });
 
   // A crash between persisting an assistant tool_use turn and its
@@ -445,6 +558,10 @@ async function runAgentLoop(
       unknown
     > as Promise<DrainResult>;
 
+  const watch = watchCancel(ctx, runId);
+  const streamSignal = anySignal(ctx.signal, watch.signal);
+  const toolCtx = ctxWithSignal(ctx, watch.signal);
+
   try {
     for (;;) {
       steps += 1;
@@ -456,18 +573,44 @@ async function runAgentLoop(
       }
       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);
-        },
-      );
+      let partial = "";
+      let res: Awaited<ReturnType<ActionCtx["llm"]["stream"]>>;
+      try {
+        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") {
+              partial += e.text;
+              ctx.stream.write(e.text);
+            }
+          },
+          { signal: streamSignal },
+        );
+      } catch (err) {
+        if (!watch.cancelled) throw err;
+        // Stopped mid-response. Keep the text the user already saw, then
+        // take whatever was queued so it is not lost with the run.
+        if (partial !== "") {
+          const content: LlmContentBlock[] = [{ type: "text", text: partial }];
+          await write({ op: "appendMessage", role: "assistant", content });
+          history.push({ role: "assistant", content });
+          finalText = partial;
+        }
+        const pending = await drain({});
+        const text = pending.input.join("\n\n");
+        if (text !== "") {
+          await write({ op: "appendMessage", role: "user", content: text });
+          history.push({ role: "user", content: text });
+        }
+        cancelled = true;
+        break;
+      }
       usage.input_tokens += res.usage.input_tokens;
       usage.output_tokens += res.usage.output_tokens;
 
@@ -508,7 +651,12 @@ async function runAgentLoop(
 
       // 3. Execute every requested tool; failures become is_error
       // results the model can react to rather than run-fatal throws.
-      const batch = await runToolBatch(def, ctx, runId, res.content);
+      const batch = await runToolBatch(def, ctx, toolCtx, watch, res.content, {
+        runId,
+        agent: agentName,
+        userId: runUserId,
+        context: runContext,
+      });
 
       // Tool boundary. Every tool_use needs its tool_result even when
       // the batch stopped early, or the transcript can't be replayed.
@@ -536,6 +684,8 @@ async function runAgentLoop(
       steps: priorSteps + steps,
     }).catch(() => {});
     throw err;
+  } finally {
+    watch.stop();
   }
 
   if (cancelled) {
@@ -558,18 +708,15 @@ async function runAgentLoop(
   return { runId, text: finalText, steps, usage };
 }
 
-/** Run one turn's tool calls, watching for a cancel while they run.
- *
- *  The watch is a poll rather than a push because a cancel can be
- *  requested on a different machine than the loop runs on — the run
- *  row is the only thing both sides share. It runs only for the
- *  duration of the batch: during `ctx.llm.stream` the host blocks its
- *  per-call read loop, so an RPC issued then would not be answered. */
+/** Run one turn's tool calls. Stops starting new ones once `watch`
+ *  sees a cancel; a handler already running sees `ctx.signal` abort. */
 async function runToolBatch(
   def: AgentDefinition,
   ctx: ActionCtx,
-  runId: string,
+  toolCtx: ActionCtx,
+  watch: CancelWatch,
   turn: LlmContentBlock[],
+  run: AgentToolRun,
 ): Promise<{ results: LlmContentBlock[]; cancelled: boolean }> {
   const calls = turn.filter(
     (b): b is Extract<LlmContentBlock, { type: "tool_use" }> =>
@@ -578,77 +725,51 @@ async function runToolBatch(
   const results: LlmContentBlock[] = [];
   if (calls.length === 0) return { results, cancelled: false };
 
-  const controller = new AbortController();
-  const toolCtx = ctxWithSignal(ctx, controller.signal);
-  let cancelled = false;
-  let polling = false;
-  const timer = setInterval(() => {
-    // Skip rather than stack: a slow poll must not queue more.
-    if (polling || cancelled) return;
-    polling = true;
-    void ctx
-      .runQuery<{ cancelRequested: boolean }>("__pylon_agent_poll", { runId })
-      .then((s) => {
-        if (s.cancelRequested && !cancelled) {
-          cancelled = true;
-          controller.abort(new Error("agent run cancelled"));
-        }
-      })
-      .catch(() => {})
-      .finally(() => {
-        polling = false;
-      });
-  }, CANCEL_POLL_MS);
-
-  try {
-    for (const block of calls) {
-      let content: string;
-      let isError = false;
-      if (cancelled) {
-        // Stop starting new work, but still answer the call so the
-        // model sees why it has no result.
-        content = "cancelled by user";
+  for (const block of calls) {
+    let content: string;
+    let isError = false;
+    if (watch.cancelled) {
+      // Stop starting new work, but still answer the call so the
+      // model sees why it has no result.
+      content = "cancelled by user";
+      isError = true;
+    } else {
+      const tool = def.tools?.[block.name];
+      if (!tool) {
+        content = `Unknown tool "${block.name}"`;
         isError = true;
       } else {
-        const tool = def.tools?.[block.name];
-        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("; ")}`);
-              }
+        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(toolCtx, block.input);
-            content =
-              typeof value === "string" ? value : JSON.stringify(value ?? null);
-          } catch (err) {
-            content = err instanceof Error ? err.message : String(err);
-            isError = true;
           }
+          const value = await tool.handler(toolCtx, block.input, run);
+          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 } : {}),
-      });
     }
-  } finally {
-    clearInterval(timer);
+    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 } : {}),
+    });
   }
-  return { results, cancelled };
+  return { results, cancelled: watch.cancelled };
 }
 
 function storedToLlmMessage(m: StoredMessage): LlmMessage {

package/src/index.ts

@@ -31,6 +31,7 @@ export {
 export type {
   AgentDefinition,
   AgentTool,
+  AgentToolRun,
   AgentCallArgs,
   AgentResult,
 } from "./agent";
@@ -86,6 +87,8 @@ export type {
   Audit,
   AuditLog,
   AuditEntry,
+  Agents,
+  AgentRunOptions,
   VectorSearchQuery,
   VectorSearchResult,
   SearchResult,

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

@@ -184,3 +184,88 @@ test("llm.stream routes events by op_id, resolves on result; rooms.broadcast rou
   // 6. rooms.broadcast surfaced the host's verdict.
   expect(out.delivered).toBe(true);
 });
+
+const ABORT_SCRIPT = `
+import { buildLlm } from ${JSON.stringify(RUNTIME)};
+
+const llm = buildLlm("c_9");
+const seen = [];
+const controller = new AbortController();
+
+// Aborted before it starts: rejects without sending a frame.
+const early = await llm
+  .stream({ messages: [] }, () => {}, { signal: AbortSignal.abort("stopped") })
+  .then(() => "resolved", (e) => e.code);
+
+const running = llm
+  .stream({ messages: [] }, (e) => {
+    seen.push(e.text);
+    if (seen.length === 2) controller.abort(new Error("user pressed stop"));
+  }, { signal: controller.signal })
+  .then(() => ({ code: "resolved" }), (e) => ({ code: e.code, message: e.message }));
+
+const out = await running;
+// Give late host frames time to arrive; they must be ignored.
+await new Promise((r) => setTimeout(r, 200));
+console.error("RESULT " + JSON.stringify({ early, out, seen }));
+process.exit(0);
+`;
+
+test("an aborted llm.stream rejects with LLM_CANCELLED and sends llm_cancel", async () => {
+  const dir = mkdtempSync(join(tmpdir(), "pylon-fn-llm-abort-"));
+  const scriptPath = join(dir, "probe.ts");
+  writeFileSync(scriptPath, ABORT_SCRIPT);
+  const proc = Bun.spawn([process.execPath, scriptPath], {
+    stdin: "pipe",
+    stdout: "pipe",
+    stderr: "pipe",
+  });
+  const reader = proc.stdout.getReader();
+  const decoder = new TextDecoder();
+  let buffered = "";
+  const frames = () => parseFrames(buffered);
+  const readUntil = async (
+    pred: (fs: Record<string, unknown>[]) => boolean,
+  ) => {
+    while (!pred(frames())) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      buffered += decoder.decode(value, { stream: true });
+    }
+  };
+  const send = (msg: Record<string, unknown>) =>
+    proc.stdin.write(JSON.stringify(msg) + "\n");
+
+  await readUntil((fs) => fs.some((f) => f.type === "llm_stream"));
+  const streams = frames().filter((f) => f.type === "llm_stream");
+  // The pre-aborted stream never reached the host.
+  expect(streams).toHaveLength(1);
+  const opId = streams[0].op_id as string;
+
+  send({ type: "llm_event", call_id: "c_9", op_id: opId, event: { type: "text_delta", text: "a" } });
+  send({ type: "llm_event", call_id: "c_9", op_id: opId, event: { type: "text_delta", text: "b" } });
+  await proc.stdin.flush();
+  await readUntil((fs) => fs.some((f) => f.type === "llm_cancel"));
+  const cancel = frames().find((f) => f.type === "llm_cancel");
+  expect(cancel).toEqual({ type: "llm_cancel", call_id: "c_9", op_id: opId });
+
+  // Frames the host sent before it saw the cancel are dropped.
+  send({ type: "llm_event", call_id: "c_9", op_id: opId, event: { type: "text_delta", text: "c" } });
+  send({
+    type: "result",
+    call_id: "c_9",
+    op_id: opId,
+    data: { model: "m", content: [], stop_reason: "end_turn", usage: { input_tokens: 0, output_tokens: 0 } },
+  });
+  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));
+  expect(out.early).toBe("LLM_CANCELLED");
+  expect(out.out.code).toBe("LLM_CANCELLED");
+  expect(out.out.message).toContain("user pressed stop");
+  expect(out.seen).toEqual(["a", "b"]);
+});

package/src/runtime.ts

@@ -49,6 +49,7 @@ import type {
   AuthInfo,
 } from "./types";
 import { normalizeAuthClaims } from "./auth";
+import { AGENT_INVOCATION, isAgentDefinition } from "./agent";
 import { makeRequireMember } from "./member";
 import { response } from "./response";
 import { isDevMode } from "./ssr-runtime";
@@ -56,7 +57,8 @@ import { validateArgs } from "./validators";
 import { serverBundle } from "./server-bundle";
 import { fenceStdout } from "./stdout-fence";
 import { readdirSync } from "fs";
-import { join, basename } from "path";
+import { join, basename, resolve } from "path";
+import { pathToFileURL } from "url";
 
 // Bun runtime globals this process uses. The runtime executes under Bun, but
 // consuming apps type-check this source under node/DOM where the `Bun` global
@@ -84,6 +86,9 @@ interface CallMessage {
   fn_type: "query" | "mutation" | "action";
   args: Record<string, unknown>;
   auth: AuthInfo;
+  /** Present only when server code started this call with
+   *  `ctx.agents.run`; the host sets it, never a client. */
+  agent?: { context?: Record<string, unknown> | null };
 }
 
 interface ResultMessage {
@@ -392,19 +397,37 @@ function rpcDb(
  * 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.
+ *
+ * When `signal` aborts, the promise rejects with `LLM_CANCELLED` at
+ * once and an `llm_cancel` frame tells the host to drop the provider
+ * request. Events and the result that arrive after that are ignored.
  */
 function rpcStreaming(
   callId: string,
   msg: Record<string, unknown>,
   onEvent: (event: unknown) => void,
+  signal?: AbortSignal,
 ): Promise<unknown> {
   throwIfCancelled(callId);
+  if (signal?.aborted) return Promise.reject(streamCancelledError(signal));
   const opId = nextOpId(callId);
   return new Promise((resolve, reject) => {
+    const onAbort = () => {
+      const pending = pendingRpcs.get(opId);
+      if (!pending) return;
+      pendingRpcs.delete(opId);
+      streamSinks.delete(opId);
+      clearTimeout(pending.timeout);
+      send({ type: "llm_cancel", call_id: callId, op_id: opId });
+      reject(streamCancelledError(signal));
+    };
     const fail = () => {
       if (pendingRpcs.has(opId)) {
         pendingRpcs.delete(opId);
         streamSinks.delete(opId);
+        signal?.removeEventListener("abort", onAbort);
+        // Nothing waits for this stream any more; stop the provider.
+        send({ type: "llm_cancel", call_id: callId, op_id: opId });
         reject(
           new Error(
             `RPC timed out after ${RPC_TIMEOUT_MS}ms with no stream activity (call_id=${callId} op_id=${opId})`,
@@ -415,14 +438,17 @@ function rpcStreaming(
     const entry = {
       resolve: (data: unknown) => {
         streamSinks.delete(opId);
+        signal?.removeEventListener("abort", onAbort);
         resolve(data);
       },
       reject: (err: Error) => {
         streamSinks.delete(opId);
+        signal?.removeEventListener("abort", onAbort);
         reject(err);
       },
       timeout: setTimeout(fail, RPC_TIMEOUT_MS),
     };
+    signal?.addEventListener("abort", onAbort, { once: true });
     pendingRpcs.set(opId, entry);
     streamSinks.set(opId, (event) => {
       clearTimeout(entry.timeout);
@@ -440,6 +466,17 @@ function rpcStreaming(
   });
 }
 
+function streamCancelledError(signal?: AbortSignal): Error {
+  const reason = signal?.reason;
+  const detail =
+    reason instanceof Error ? reason.message : reason ? String(reason) : "";
+  const err = new Error(
+    detail ? `ctx.llm.stream was cancelled: ${detail}` : "ctx.llm.stream was cancelled",
+  );
+  (err as { code?: string }).code = "LLM_CANCELLED";
+  return err;
+}
+
 /**
  * Tail of the in-order queue of legacy (call_id-keyed) RPCs, per call.
  * See {@link rpc} for why these serialize.
@@ -941,11 +978,13 @@ export function buildLlm(callId: string): Llm {
     async stream(
       request: LlmCompleteRequest,
       onEvent: (event: LlmStreamEvent) => void,
+      options?: { signal?: AbortSignal },
     ): Promise<LlmCompleteResponse> {
       return (await rpcStreaming(
         callId,
         { type: "llm_stream", request },
         (event) => onEvent(event as LlmStreamEvent),
+        options?.signal,
       )) as LlmCompleteResponse;
     },
 
@@ -1242,6 +1281,38 @@ function buildActionCtx(
     connections,
     workflows: buildWorkflows(callId),
     audit: buildAudit(callId),
+    agents: {
+      async run(name, options) {
+        if (!options || typeof options.as?.userId !== "string") {
+          const err = new Error(
+            "ctx.agents.run needs as.userId: the user the run belongs to",
+          );
+          (err as { code?: string }).code = "INVALID_ARGS";
+          throw err;
+        }
+        const context = options.context;
+        if (
+          context !== undefined &&
+          context !== null &&
+          (typeof context !== "object" || Array.isArray(context))
+        ) {
+          const err = new Error("ctx.agents.run: context must be a plain object");
+          (err as { code?: string }).code = "INVALID_ARGS";
+          throw err;
+        }
+        const args: Record<string, unknown> = { input: options.input };
+        if (options.runId !== undefined) args.runId = options.runId;
+        if (options.title !== undefined) args.title = options.title;
+        return rpc(callId, {
+          type: "run_agent",
+          agent: name,
+          args,
+          user_id: options.as.userId,
+          admin: options.as.admin === true,
+          context: options.context ?? null,
+        }) as Promise<any>;
+      },
+    },
     domains: buildDomains(),
     env: process.env as Record<string, string>,
     async runQuery(fnName, args) {
@@ -1304,6 +1375,32 @@ registry.set("__pylonMemberLookup", {
 // Handler
 // ---------------------------------------------------------------------------
 
+/** Why a `ctx.agents.run` target may not run, or null when it may. */
+function agentInvocationRefusal(
+  def: FnDefinition,
+  rawAuth: AuthInfo,
+): { code: string; message: string } | null {
+  if (!isAgentDefinition(def)) {
+    return {
+      code: "AGENT_NOT_FOUND",
+      message: "ctx.agents.run can only run a function defined with agent()",
+    };
+  }
+  const auth = normalizeAuthClaims(rawAuth as unknown as Record<string, unknown>);
+  const mode = (def as { auth?: string }).auth ?? "user";
+  if (mode === "admin" && !auth.isAdmin) {
+    return {
+      code: "FORBIDDEN",
+      message:
+        "this agent is declared auth: \"admin\"; pass as: { userId, admin: true } from an admin caller",
+    };
+  }
+  if ((mode === "user" || mode === "admin") && !auth.userId) {
+    return { code: "UNAUTHENTICATED", message: "the agent needs a user" };
+  }
+  return null;
+}
+
 async function handleCall(msg: CallMessage): Promise<void> {
   const def = registry.get(msg.fn_name);
 
@@ -1332,6 +1429,18 @@ async function handleCall(msg: CallMessage): Promise<void> {
     return;
   }
 
+  // `ctx.agents.run`: the host checked who may start this and as whom.
+  // What is left is the target: it must be an agent, and the identity
+  // must satisfy the agent's own auth mode, exactly as an HTTP call to
+  // it would have to.
+  if (msg.agent) {
+    const refusal = agentInvocationRefusal(def, msg.auth);
+    if (refusal) {
+      send({ type: "error", call_id: msg.call_id, ...refusal });
+      return;
+    }
+  }
+
   if (def.args) {
     const { valid, errors } = validateArgs(msg.args, def.args);
     if (!valid) {
@@ -1469,6 +1578,13 @@ async function handleCall(msg: CallMessage): Promise<void> {
   // the switch so all three ctx shapes get it without threading another
   // parameter through each builder.
   (ctx as { signal?: AbortSignal }).signal = abort.signal;
+  if (msg.agent) {
+    // Read by the agent loop only. A symbol key, so nothing a client
+    // sends (args are plain JSON) can set it.
+    (ctx as unknown as Record<symbol, unknown>)[AGENT_INVOCATION] = {
+      context: msg.agent.context ?? null,
+    };
+  }
 
   try {
     const result = await def.handler(ctx, msg.args);
@@ -1561,19 +1677,29 @@ function firstStackFrame(err: unknown): string {
  */
 function listModuleFiles(
   dir: string,
+  opts: { reportMissing?: boolean } = {},
 ): Array<{ name: string; file: string; load: () => Promise<any> }> {
   let files: string[];
   try {
     files = readdirSync(dir).filter(
       (f) => f.endsWith(".ts") || f.endsWith(".js"),
     );
-  } catch {
+  } catch (err) {
+    // A missing default directory is normal (see above). Anything else, or
+    // a directory the app named explicitly, means its functions would
+    // silently not register, so say why.
+    const missing = (err as NodeJS.ErrnoException)?.code === "ENOENT";
+    if (!missing || opts.reportMissing) {
+      console.error(`[functions] Cannot read ${dir}:`, err);
+    }
     return [];
   }
   return files.map((file) => ({
     name: basename(file, file.endsWith(".ts") ? ".ts" : ".js"),
     file,
-    load: () => import(join(dir, file)),
+    // A file URL: a bare Windows path ("D:\\app\\x.ts") is not a module
+    // specifier everywhere.
+    load: () => import(pathToFileURL(join(dir, file)).href),
   }));
 }
 
@@ -1584,6 +1710,9 @@ async function main() {
   fenceStdout();
 
   const fnDir = process.argv[2] || "./functions";
+  // `resolve`, not `join`: an absolute PYLON_FUNCTIONS_DIR (including a
+  // Windows drive path) must be used as is, not appended to the cwd.
+  const fnDirIsDefault = fnDir === "functions" || fnDir === "./functions";
   const bundle = serverBundle();
 
   const fnSources = bundle
@@ -1592,7 +1721,9 @@ async function main() {
         file: `${name} (bundled)`,
         load: bundle.functions[name],
       }))
-    : listModuleFiles(join(process.cwd(), fnDir));
+    : listModuleFiles(resolve(process.cwd(), fnDir), {
+        reportMissing: !fnDirIsDefault,
+      });
 
   const { isAgentDefinition, AGENT_MARKER } = await import("./agent");
   let agentsPresent = false;
@@ -1650,7 +1781,7 @@ async function main() {
         file: `${name} (bundled)`,
         load: bundle.workflows[name],
       }))
-    : listModuleFiles(join(process.cwd(), "workflows"));
+    : listModuleFiles(resolve(process.cwd(), "workflows"));
   for (const { file, load } of wfSources) {
     try {
       const mod = await load();

package/src/types.ts

@@ -508,10 +508,16 @@ export interface Llm {
    * 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.
+   * The function's call timeout (PYLON_FN_CALL_TIMEOUT, 30s default, or
+   * the function's own `timeout`) is an idle timeout. A running stream
+   * counts as activity, but no call outlives 10× its timeout, so a long
+   * agent run should still declare its own `timeout`.
+   *
+   * Pass `{ signal }` to stop a stream early. When the signal aborts,
+   * the promise rejects with `err.code === "LLM_CANCELLED"` and the
+   * server closes the provider connection, so the model stops
+   * generating (and billing) tokens. A stream still running when the
+   * function returns or times out is cancelled the same way.
    *
    * Same errors and same gating as {@link Llm.complete} — including
    * the model allowlist, so streaming can't be used to reach a model
@@ -520,6 +526,7 @@ export interface Llm {
   stream(
     request: LlmCompleteRequest,
     onEvent: (event: LlmStreamEvent) => void,
+    options?: { signal?: AbortSignal },
   ): Promise<LlmCompleteResponse>;
 
   /**
@@ -1363,6 +1370,48 @@ export interface Domains {
   ): Promise<RegisteredDomainResult>;
 }
 
+/** Options for {@link Agents.run}. */
+export interface AgentRunOptions {
+  /** The message for this turn. */
+  input: string;
+  /** Continue this run. It must belong to `as.userId` and this agent. */
+  runId?: string;
+  /** Display title, stored on a new run. */
+  title?: string;
+  /**
+   * The user the run belongs to and runs as. The run shows up in that
+   * user's synced `AgentRun`/`AgentMessage` rows. `admin: true` also
+   * gives the run admin rights (needed for an agent declared
+   * `auth: "admin"`), and is allowed only when the caller is an admin.
+   */
+  as: { userId: string; admin?: boolean };
+  /**
+   * JSON the agent's tool handlers receive as `run.context` (their third
+   * argument), for example the conversation a webhook turn belongs to.
+   * Stored on the run as `AgentRun.context`, so later turns of the run
+   * see it too. The run's owner can read it; do not put secrets in it.
+   */
+  context?: Record<string, unknown>;
+}
+
+/**
+ * Run an `agent()` from server code. See {@link ActionCtx.agents}.
+ */
+export interface Agents {
+  /**
+   * Run agent `name` (its file name in `functions/`) as `options.as`.
+   * Resolves with the agent's result once the turn finishes, like a
+   * `streamFn` call's final `result` event. The agent's tokens are not
+   * streamed to this caller; they are in the run's `AgentMessage` rows.
+   *
+   * Only server code can do this: the calling action must be
+   * `internal: true` (jobs, workflows, scheduled work) or run with admin
+   * rights (an admin session, or a webhook after `ctx.auth.elevate`).
+   * Otherwise it throws `AGENT_RUN_FORBIDDEN`.
+   */
+  run(name: string, options: AgentRunOptions): Promise<import("./agent").AgentResult>;
+}
+
 export interface ActionCtx<R extends AuthRequirement = "optional"> {
   auth: AuthInfo<R>;
   stream: Stream;
@@ -1379,6 +1428,8 @@ export interface ActionCtx<R extends AuthRequirement = "optional"> {
   workflows: Workflows;
   /** Application audit log — see {@link Audit}. */
   audit: Audit;
+  /** Run an `agent()` as a named user from server code — see {@link Agents}. */
+  agents: Agents;
   /** Attach / register custom domains for your app's OWN end-customers
    *  (platform domains) — see {@link Domains}. Cloud-only. */
   domains: Domains;