@pylonsync/functions 0.20.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/define.d.ts

@@ -44,7 +44,8 @@ interface CommonDef<TSchema extends ValidatorSchema | undefined = ValidatorSchem
      * 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.

package/dist/index.d.ts

@@ -20,10 +20,11 @@
 export { query, mutation, action } from "./define";
 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, VectorSearchQuery, VectorSearchResult, SearchResult, PaginationResult, Llm, LlmMessage, LlmContentBlock, LlmTool, LlmCompleteRequest, LlmCompleteResponse, LlmStreamEvent, Rooms, Domains, TenantDomainResult, 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/response.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Raw HTTP responses from webhook actions.
+ *
+ * An action called through `/api/webhooks/<name>` normally answers with its
+ * return value as JSON and status 200. Returning `ctx.response(...)` sends
+ * the given status, content type, headers, and body instead. Every other
+ * route (`/api/fn/<name>`, `ctx.runAction`) returns the value as ordinary
+ * JSON data.
+ *
+ * The host enforces the same rules (crates/router/src/raw_response.rs), so
+ * a hand-built object cannot bypass them. The two header lists must stay in
+ * sync.
+ */
+/** What `ctx.response` accepts. */
+export interface RawResponseInit {
+    /** HTTP status, 200-599. Default 200. */
+    status?: number;
+    /** Shorthand for the `Content-Type` header. Default `text/plain; charset=utf-8`. */
+    contentType?: string;
+    /** Extra response headers. Values must be visible ASCII. */
+    headers?: Record<string, string>;
+    /** Response body. Default empty. Must be empty for 204, 205, and 304. */
+    body?: string;
+}
+/** The marked value an action returns. Build it with `ctx.response`. */
+export interface RawResponse {
+    readonly __pylonResponse: 1;
+    readonly status: number;
+    readonly headers: Readonly<Record<string, string>>;
+    readonly body: string;
+}
+/**
+ * Build a raw HTTP response for a webhook action to return.
+ *
+ * ```ts
+ * return ctx.response({ contentType: "text/xml", body: "<Response/>" });
+ * ```
+ */
+export declare function response(init?: RawResponseInit): RawResponse;

package/dist/runtime.d.ts

@@ -14,7 +14,7 @@
  *   each ctx.db / ctx.scheduler / ctx.runMutation call), so the map never
  *   needs to queue multiple RPCs per call_id.
  */
-import type { DbReader, DbWriter, Llm, Rooms, Workflows } from "./types";
+import type { DbReader, DbWriter, Llm, Rooms, Workflows, Audit } from "./types";
 export declare function buildDbReader(callId: string, ssrRead?: boolean): DbReader;
 export declare function buildSsrFnCaller(callId: string): (name: string, args?: Record<string, unknown>) => Promise<unknown>;
 export declare function buildDbWriter(callId: string): DbWriter;
@@ -46,4 +46,6 @@ export declare function buildRooms(callId: string): Rooms;
  * takes it from there, so `start` returns the instance id immediately.
  * Uses the queued call_id-keyed `rpc` (the reply carries no op_id).
  */
+/** Build `ctx.audit` — round-trips `audit_op` frames to the host. */
+export declare function buildAudit(callId: string): Audit;
 export declare function buildWorkflows(callId: string): Workflows;

package/dist/ssr-runtime.d.ts

@@ -337,6 +337,13 @@ export declare function moduleExistsIn(fs: any, path: any, cwd: string, dir: str
  * in the process.
  */
 export declare function findBoundaryIn(fs: any, path: any, cwd: string, componentPath: string, fileName: string): string | null;
+/** Loopback host? `host` is a lowercase authority (`host[:port]`,
+ *  `[ipv6]:port`). True for exactly `localhost`, dotted 127.0.0.0/8
+ *  without leading zeros, `::1`, or `0.0.0.0`, with an optional numeric
+ *  port. The match is exact, so
+ *  `localhost.example.com` is not loopback. Mirrors `is_loopback_host` in
+ *  crates/router/src/public_url.rs. Exported for tests. */
+export declare function isLoopbackHost(host: string): boolean;
 /** Pure origin resolution (exported for tests).
  *
  *  SECURITY: the request `Host` (and `X-Forwarded-Proto`) is attacker-

package/dist/types.d.ts

@@ -1,6 +1,7 @@
 /**
  * Type definitions for the function system.
  */
+import type { RawResponse, RawResponseInit } from "./response";
 /**
  * Declarative auth requirement for a function. The framework
  * enforces this BEFORE the handler runs — if the caller doesn't
@@ -296,8 +297,23 @@ export interface Scheduler {
     runAfter(delayMs: number, fnName: string, args: Record<string, unknown>): Promise<string>;
     /** Schedule a function to run at a specific time (Unix ms). */
     runAt(timestamp: number, fnName: string, args: Record<string, unknown>): Promise<string>;
-    /** Cancel a previously scheduled function. */
-    cancel(scheduleId: string): Promise<void>;
+    /**
+     * Cancel a scheduled function that has not started. Pass the id
+     * `runAfter` or `runAt` returned.
+     *
+     * Resolves `{ cancelled: true }` when the job will not run, and
+     * `{ cancelled: false }` when the id is unknown or the job already
+     * started or finished (a running job is not interrupted). Rejects with
+     * `SCHEDULE_CANCEL_FAILED` when the cancel could not be saved; the job
+     * then still runs.
+     *
+     * Inside a mutation, the cancel commits or rolls back with the
+     * mutation: if the mutation throws, the job stays scheduled. From an
+     * action, it takes effect at once.
+     */
+    cancel(scheduleId: string): Promise<{
+        cancelled: boolean;
+    }>;
 }
 /**
  * Transactional email transport.
@@ -411,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
@@ -523,18 +547,153 @@ export interface Workflows {
     /**
      * Start a workflow instance by name. Returns immediately with the
      * instance id — the engine's background driver executes the steps.
+     *
+     * With `key` (for example a lead id), at most one non-terminal run
+     * exists per workflow name and key. If one exists, no new run starts
+     * and its id is returned with `created: false`. A finished run frees
+     * the key.
      */
-    start(name: string, input?: unknown): Promise<{
+    start(name: string, input?: unknown, opts?: {
+        key?: string;
+    }): Promise<{
         id: string;
+        created: boolean;
     }>;
     /**
-     * Deliver an event to an instance paused on
-     * `wf.waitForEvent(event)`. Rejects when the instance isn't waiting
-     * for that event.
+     * Send an event to a run. If the run is waiting for it
+     * (`wf.waitForEvent(event)`), the run resumes and `delivered` is true.
+     * Otherwise the event is buffered (`buffered: true`) and the run's next
+     * `waitForEvent(event)` consumes it. Rejects when the run has finished
+     * or already holds 100 buffered events. Events sent without data
+     * arrive as `{}`.
      */
     sendEvent(workflowId: string, event: string, data?: unknown): Promise<{
         delivered: boolean;
+        buffered: boolean;
     }>;
+    /**
+     * Cancel a run. No further step runs. A step already in progress may
+     * finish, but its result is discarded. Resolves `cancelled: false` when
+     * the run had already finished. Rejects for an unknown id.
+     */
+    cancel(workflowId: string, opts?: {
+        reason?: string;
+    }): Promise<{
+        cancelled: boolean;
+    }>;
+    /** Read one run, or null if the id is unknown. */
+    get(workflowId: string): Promise<WorkflowRunSummary | null>;
+    /**
+     * List runs, newest first. `status: "active"` matches every
+     * non-terminal status. `limit` defaults to 100 (max 1000).
+     *
+     * ```ts
+     * // Seller texted STOP: end every cadence for the lead.
+     * const runs = await ctx.workflows.list({ key: leadId, status: "active" });
+     * for (const run of runs) {
+     *   await ctx.workflows.cancel(run.id, { reason: "STOP" });
+     * }
+     * ```
+     */
+    list(filter?: {
+        name?: string;
+        key?: string;
+        status?: WorkflowRunStatus | "active";
+        limit?: number;
+    }): Promise<WorkflowRunSummary[]>;
+}
+/**
+ * The application audit log (`ctx.audit` on mutations and actions).
+ * Append-only, stored with the auth audit events.
+ */
+export interface AuditLog {
+    /**
+     * Record an event. The actor and tenant come from the caller's session.
+     * `action` is a short dotted name (`lead.export`, `script.update`) and
+     * is stored as `app.<action>`. `meta` values are stored as strings
+     * (non-strings as JSON text); keep secrets out of it.
+     *
+     * Inside a mutation the event is written after the mutation commits and
+     * dropped if it rolls back. Rejects with `AUDIT_WRITE_FAILED` when an
+     * action's event could not be stored.
+     */
+    log(event: {
+        action: string;
+        entity?: string;
+        entityId?: string;
+        /** The user the event is about, when not the actor. */
+        subject?: string;
+        meta?: Record<string, unknown>;
+    }): Promise<{
+        id: string;
+    }>;
+}
+/**
+ * `ctx.audit` on actions: {@link AuditLog.log} plus reads. Mutations get
+ * only `log`: in a Postgres mutation the transaction holds a connection,
+ * and a read would need a second.
+ */
+export interface Audit extends AuditLog {
+    /**
+     * Read events, newest first. A caller with a tenant reads that tenant's
+     * events; a caller without one reads only events it performed. Admin
+     * callers may pass `tenant` or read all tenants. `action` matches
+     * `lead.export` as `app.lead.export`; framework actions
+     * (`entity.update`, `retention.delete`) and auth action names match as
+     * given. `limit` defaults to 100 (max 1000). To page,
+     * pass `beforeId` set to the last event's `id`. `before` (unix seconds)
+     * limits by time.
+     */
+    list(filter?: {
+        entity?: string;
+        entityId?: string;
+        actor?: string;
+        action?: string;
+        tenant?: string;
+        before?: number;
+        beforeId?: string;
+        limit?: number;
+    }): Promise<AuditEntry[]>;
+}
+export interface AuditEntry {
+    id: string;
+    /** Unix seconds. */
+    createdAt: number;
+    /** `app.<action>`, `entity.insert|update|delete`, `retention.delete`, or an auth action. */
+    action: string;
+    actor: string | null;
+    subject: string | null;
+    tenant: string | null;
+    entity: string | null;
+    entityId: string | null;
+    ip: string | null;
+    success: boolean;
+    reason: string | null;
+    /** For `entity.*` events, `fields` lists the changed field names. */
+    meta: Record<string, string>;
+}
+export type WorkflowRunStatus = "pending" | "running" | "sleeping" | "waiting" | "completed" | "failed" | "cancelled";
+/** A workflow run without its step history. Times are unix seconds. */
+export interface WorkflowRunSummary {
+    id: string;
+    name: string;
+    key: string | null;
+    status: WorkflowRunStatus;
+    input: unknown;
+    output: unknown;
+    error: string | null;
+    cancelReason: string | null;
+    /** Event name the run is waiting for, when `status` is "waiting". */
+    waitingFor: string | null;
+    /** When the current wait times out, if it has a timeout. */
+    waitDeadline: number | null;
+    /** When the current sleep ends. */
+    wakeAt: number | null;
+    /** Events sent but not yet consumed by a `waitForEvent`. */
+    bufferedEvents: number;
+    createdAt: number | null;
+    startedAt: number | null;
+    completedAt: number | null;
 }
 export interface LlmMessage {
     role: "user" | "assistant" | "system" | "tool";
@@ -915,6 +1074,8 @@ export interface MutationCtx<R extends AuthRequirement = "optional"> {
     connections: Connections;
     /** Durable workflows: start / deliver events — see {@link Workflows}. */
     workflows: Workflows;
+    /** Application audit log (write only in mutations) — see {@link AuditLog}. */
+    audit: AuditLog;
     /** Signed file-download URLs — see {@link Files}. */
     files: Files;
     /** Shard tickets, reads, and inputs after the commit — see {@link Shards}. */
@@ -947,8 +1108,18 @@ export interface TenantDomainResult {
     status: string;
     /** Whether the hostname + TLS certificate are both active. */
     active?: boolean;
-    /** The single CNAME the customer points their hostname at. */
-    cnameTarget: string;
+    /**
+     * True for an apex domain (`acme.com`). An apex cannot be a CNAME, so the
+     * customer adds A/AAAA records pointing at the app instead.
+     */
+    apex?: boolean;
+    /**
+     * Every DNS record the customer adds, for both kinds of domain: a CNAME
+     * (subdomain) or A/AAAA (apex), plus ownership and certificate records.
+     */
+    records?: TenantDomainRecord[];
+    /** The CNAME the customer points a subdomain at; null for an apex. */
+    cnameTarget: string | null;
     /** TXT record proving domain ownership before DNS cutover (or null). */
     ownership: TenantDomainDns | null;
     /** TXT records that issue the DV certificate. */
@@ -956,6 +1127,13 @@ export interface TenantDomainResult {
     /** Human-readable provisioning errors, empty when healthy. */
     errors: string[];
 }
+export interface TenantDomainRecord {
+    type: "A" | "AAAA" | "CNAME" | "TXT";
+    name: string;
+    value: string;
+    /** What the record is for, to show the customer. */
+    purpose: string;
+}
 /**
  * Platform domains: attach / register / detach custom domains for your app's
  * OWN end-customers, so each tenant can reach your app on their own hostname.
@@ -1067,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;
@@ -1081,6 +1302,10 @@ export interface ActionCtx<R extends AuthRequirement = "optional"> {
     connections: Connections;
     /** Durable workflows: start / deliver events — see {@link Workflows}. */
     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;
@@ -1125,12 +1350,34 @@ export interface ActionCtx<R extends AuthRequirement = "optional"> {
      * ```
      */
     request?: RequestInfo;
+    /**
+     * Build a raw HTTP response. When an action called through
+     * `/api/webhooks/<name>` returns it, the route sends this status,
+     * content type, headers, and body instead of JSON. Other routes return
+     * it as ordinary JSON data. Throws on an invalid status or header.
+     *
+     * ```ts
+     * // Twilio expects TwiML, not JSON.
+     * return ctx.response({ contentType: "text/xml", body: "<Response/>" });
+     * ```
+     */
+    response(init?: RawResponseInit): RawResponse;
 }
 /** HTTP request metadata available on an action's ctx when invoked via an
  *  HTTP route binding. Header names are lowercased. */
 export interface RequestInfo {
     method: string;
+    /** Request path with the query string, as received. */
     path: string;
+    /**
+     * The full URL the client requested: scheme, host, path, and query.
+     * Behind a proxy, the host comes from `X-Forwarded-Host` or `Host`
+     * only when it is trusted (loopback, the `PYLON_PUBLIC_URL` host,
+     * `PYLON_CANONICAL_HOST`, a `PYLON_TRUSTED_HOSTS` entry, or one of the
+     * app's domains); otherwise the `PYLON_PUBLIC_URL` origin is used. Use
+     * it to verify providers that sign the whole URL, such as Twilio.
+     */
+    url: string;
     headers: Record<string, string>;
     rawBody: string;
 }

package/dist/workflows.d.ts

@@ -57,6 +57,7 @@ export type WorkflowRunnerResponse = {
 } | {
     action: "wait_event";
     event: string;
+    timeout?: string;
 } | {
     action: "complete";
     output: unknown;
@@ -80,10 +81,26 @@ export interface WorkflowRun<TInput = unknown> {
     /** Pause the workflow for a duration ("30s", "5m", "24h", "7d"). */
     sleep(duration: string): Promise<void>;
     /**
-     * Pause until `POST /api/workflows/<id>/event` delivers this event.
-     * Resolves with the event's data payload.
+     * Pause until the event arrives through `ctx.workflows.sendEvent` or
+     * `POST /api/workflows/<id>/event`. Resolves with the event's data
+     * (`{}` when it was sent without data).
+     *
+     * Events sent while the run is not waiting for them are buffered. The
+     * next `waitForEvent` with that name consumes the oldest buffered
+     * event, so an event that arrives during a step is not lost.
+     *
+     * The same event name can be awaited more than once in a run; each
+     * call consumes one event.
      */
     waitForEvent<T = unknown>(eventName: string): Promise<T>;
+    /**
+     * Same as above, but resolves with `null` if no event arrives within
+     * `timeout` ("60s", "5m", "24h", "7d"). The timeout is durable: it
+     * survives restarts, like `sleep`.
+     */
+    waitForEvent<T = unknown>(eventName: string, opts: {
+        timeout: string;
+    }): Promise<T | null>;
 }
 export interface WorkflowDefinition<TInput = unknown> {
     readonly __pylonWorkflow: true;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pylonsync/functions",
-  "version": "0.20.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.