@pylonsync/functions 0.20.0 → 0.22.0

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/define.ts

@@ -59,7 +59,8 @@ interface CommonDef<
    * IDLE-timeout SECONDS for this function: how long it may go without
    * producing any activity (a stream chunk, a `ctx.db` op, an LLM
    * event) before the host cancels the call. Defaults to
-   * `PYLON_FN_CALL_TIMEOUT` (30s). Activity restarts the budget, so a
+   * `PYLON_FN_CALL_TIMEOUT` (30s; Stack0 Cloud sets 300s). Activity
+   * restarts the budget, so a
    * streaming agent run stays alive as long as it keeps producing; a
    * silent hang is cancelled at the budget. Total lifetime is capped at
    * 10× this value however chatty the call is.