@trigger.dev/convex 4.8.2 → 4.8.4

package/README.md

@@ -6,6 +6,12 @@ Use Convex for application state and Trigger.dev for work that needs longer exec
 
 **Experimental MVP.** No HTTP routes, webhooks, Trigger lifecycle hooks, or changes to your Trigger server are required.
 
+## Example
+
+[Try the live demo](https://ardent-rabbit-965.convex.site).
+
+The [image-editing example](https://github.com/triggerdotdev/trigger.dev/tree/main/packages/convex/example) demonstrates private image processing, Realtime progress, and Convex synchronization. It uses Trigger.dev `4.8.3` from npmjs and runs as a standalone pnpm workspace. The example is not included in npm packages or component builds.
+
 ## Install
 
 ```sh
@@ -119,11 +125,27 @@ const run = useQuery(api.jobs.status, { jobId });
 
 The ID returned by `trigger.trigger` identifies the **component record**, not the Trigger.dev run. The latter becomes available as `run.runId` after submission.
 
+## Agent skill
+
+The package ships a versioned [`trigger-convex` skill](https://github.com/triggerdotdev/trigger.dev/blob/main/packages/convex/skills/trigger-convex/SKILL.md) covering transactional triggering, owned reactive queries, callbacks, Realtime + refresh, reload recovery, and token safety.
+
+Ask your coding assistant to read `node_modules/@trigger.dev/convex/skills/trigger-convex/SKILL.md`, or copy it into your assistant's native skill directory. For example, from a project with this package installed:
+
+```sh
+mkdir -p .agents/skills/trigger-convex
+cp node_modules/@trigger.dev/convex/skills/trigger-convex/SKILL.md .agents/skills/trigger-convex/SKILL.md
+```
+
+Use `.claude/skills/`, `.cursor/skills/`, or `.github/skills/` instead if appropriate for your assistant. Re-copy after upgrading `@trigger.dev/convex`; copied files do not update automatically. For non-hoisted installs, locate the package with `node -p "require.resolve('@trigger.dev/convex/package.json')"`.
+
+This skill is installed manually, not through `npx trigger.dev@latest skills`. Older package versions may not contain it.
+
 ## API
 
 - `trigger(ctx, taskId, payload, options?)`: enqueue work. Calling from a mutation makes the request atomic with your application's writes.
 - `getRun(ctx, id)`: read one record reactively.
 - `listRuns(ctx, paginationOpts)`: paginate records, newest first, up to 100 per page and a bounded read budget.
+- `refresh(ctx, id)`: schedule an earlier status check for an active, submitted run. Returns `null` after scheduling, not the updated run.
 - `resume(ctx, id)`: resume paused synchronization using the current credentials.
 
 Trigger options include tags, delay, queue name, concurrency key, machine, metadata, max attempts, max duration, TTL, and a component-level idempotency key.
@@ -134,6 +156,35 @@ The constructor accepts `secretKey` (defaults to `TRIGGER_SECRET_KEY`), `baseUrl
 
 **Authorization belongs in your application's functions.** The component has no tenant or user model. Do not expose arbitrary record IDs or `listRuns` to clients without enforcing ownership. Queries never return stored credentials or request payloads.
 
+## Realtime progress and faster result delivery
+
+Use [Trigger Realtime](https://trigger.dev/docs/realtime/overview) for responsive browser progress, and Convex queries for durable application state. When Realtime reports that a run is complete, call an ownership-checked application mutation that requests a component refresh:
+
+```ts
+// convex/jobs.ts
+export const refresh = mutation({
+  args: { jobId: v.id("jobs") },
+  handler: async (ctx, { jobId }) => {
+    const user = await ctx.auth.getUserIdentity();
+    const job = await ctx.db.get(jobId);
+    if (!user || !job || job.owner !== user.subject) throw new Error("Unauthorized");
+    if (job.runId) await trigger.refresh(ctx, job.runId);
+  },
+});
+```
+
+Pass the component record ID to `refresh`, not the remote Trigger run ID. Your browser subscribes to the latter, available as `run.runId` from `getRun`.
+
+A refresh is only a hint: the component retrieves status and output directly from Trigger and uses the same validation, completion callback, and credential cleanup as normal polling. It never accepts client-supplied status or output. Observe `getRun` or your application query for the persisted result; awaiting `refresh` does not wait for that result.
+
+- Refresh requests are coalesced per run. Status checks requested this way start at least five seconds after the previous status check.
+- A hint received during a check queues one follow-up instead of interrupting or discarding the in-flight response. If that response completes the run, no follow-up is needed.
+- Pending submissions, paused synchronization, and completed records are no-ops. Refresh never submits a task or resumes paused work; use `resume` after repairing a paused synchronization.
+- Call refresh when Realtime observes completion, including an already-completed run after reconnecting. Do not call it on every metadata update to animate progress.
+- Scheduled polling and its watchdog remain enabled. Convex can still finish the run if the browser closes, the subscription disconnects, or the refresh request fails. No persistent subscription inside a Convex action is required.
+
+**Realtime token safety:** authenticate the token request, verify job ownership, and issue a short-lived token scoped to the exact remote run. Keep the root Trigger key server-side. A run-read token can also read the run through REST, including its payload; Realtime `skipColumns` is not a restriction on REST access. Keep worker credentials, storage-upload capabilities, and other secrets out of token-readable payloads, outputs, metadata, and errors. Application mutations must enforce ownership even when component refreshes are coalesced.
+
 ## Execution and reliability
 
 1. The calling mutation writes a component record and schedules submission. If the transaction rolls back, neither survives.

package/dist/client/index.d.ts

@@ -30,5 +30,10 @@ export declare class Trigger {
         isDone: boolean;
         continueCursor: string;
     }>;
+    /**
+     * Request an earlier status check without accepting client-supplied run data.
+     * The check is scheduled, coalesced, and rate-limited; observe getRun for its result.
+     */
+    refresh(ctx: MutationCtx, id: string): Promise<null>;
     resume(ctx: MutationCtx, id: string): Promise<null>;
 }

package/dist/client/index.js

@@ -39,6 +39,13 @@ export class Trigger {
     async listRuns(ctx, paginationOpts) {
         return ctx.runQuery(this.component.runs.list, { paginationOpts });
     }
+    /**
+     * Request an earlier status check without accepting client-supplied run data.
+     * The check is scheduled, coalesced, and rate-limited; observe getRun for its result.
+     */
+    async refresh(ctx, id) {
+        return ctx.runMutation(this.component.runs.refresh, { id });
+    }
     async resume(ctx, id) {
         return ctx.runMutation(this.component.runs.resume, { id, config: this.runtimeConfig() });
     }

package/dist/component/runs.d.ts

@@ -58,6 +58,10 @@ export declare const list: import("convex/server").RegisteredQuery<"public", {
     isDone: boolean;
     continueCursor: string;
 }>>;
+export declare function scheduleRefresh(ctx: GenericMutationCtx<DataModel>, run: RunDoc): Promise<void>;
+export declare const refresh: import("convex/server").RegisteredMutation<"public", {
+    id: string;
+}, Promise<null>>;
 export declare const resume: import("convex/server").RegisteredMutation<"public", {
     config: {
         baseUrl: string;
@@ -72,15 +76,18 @@ export declare const load: import("convex/server").RegisteredQuery<"internal", {
         _creationTime: number;
         _id: import("convex/values").GenericId<"runs">;
         callback?: string | undefined;
+        checking?: boolean | undefined;
         checks: number;
         error?: any;
         failures: number;
         generation: number;
         idempotencyKey?: string | undefined;
+        lastCheckAt?: number | undefined;
         metadata?: any;
         output?: any;
         outputOmitted?: boolean | undefined;
         outputPresignedUrl?: string | undefined;
+        refreshRequested?: boolean | undefined;
         runId?: string | undefined;
         status: string;
         syncError?: string | undefined;

package/dist/component/runs.js

@@ -2,9 +2,9 @@ import { paginationOptsValidator, } from "convex/server";
 import { v } from "convex/values";
 import { internal } from "./api.js";
 import { internalMutation, internalQuery, mutation, query } from "./server.js";
-import { MAX_INLINE_BYTES, MAX_PAGE_BYTES, SUBMISSION_WINDOW_MS, vConfig, vRun, vTriggerOptions, } from "./shared.js";
+import { MAX_INLINE_BYTES, MAX_PAGE_BYTES, MIN_REFRESH_INTERVAL_MS, SUBMISSION_WINDOW_MS, vConfig, vRun, vTriggerOptions, } from "./shared.js";
 export function toRun(run) {
-    const { _id, _creationTime, generation, checks, failures, callback, ...fields } = run;
+    const { _id, _creationTime, generation, checks, failures, callback, checking, refreshRequested, lastCheckAt, ...fields } = run;
     return { id: _id, createdAt: _creationTime, ...fields };
 }
 export const trigger = mutation({
@@ -83,6 +83,34 @@ export const list = query({
         };
     },
 });
+export async function scheduleRefresh(ctx, run) {
+    if (!run.refreshRequested)
+        return;
+    const delay = run.lastCheckAt === undefined
+        ? 0
+        : Math.max(0, run.lastCheckAt + MIN_REFRESH_INTERVAL_MS - Date.now());
+    await ctx.scheduler.runAfter(delay, internal.worker.tick, {
+        id: run._id,
+        generation: run.generation,
+    });
+}
+export const refresh = mutation({
+    args: { id: v.string() },
+    returns: v.null(),
+    handler: async (ctx, { id }) => {
+        const runId = ctx.db.normalizeId("runs", id);
+        const run = runId ? await ctx.db.get("runs", runId) : null;
+        if (!run)
+            throw new Error("Run not found");
+        if (!run.runId || run.syncStatus !== "active" || run.refreshRequested)
+            return null;
+        await ctx.db.patch(run._id, { refreshRequested: true });
+        // Preserve the in-flight observation; its result will schedule any requested follow-up.
+        if (!run.checking)
+            await scheduleRefresh(ctx, { ...run, refreshRequested: true });
+        return null;
+    },
+});
 export const resume = mutation({
     args: { id: v.string(), config: vConfig },
     returns: v.null(),
@@ -110,6 +138,8 @@ export const resume = mutation({
             failures: 0,
             checks: 0,
             generation,
+            checking: undefined,
+            refreshRequested: undefined,
             updatedAt: Date.now(),
         });
         await ctx.scheduler.runAfter(0, internal.worker.tick, { id: run._id, generation });
@@ -141,6 +171,7 @@ export const recordSubmission = internalMutation({
             syncError: undefined,
             failures: 0,
             checks: 0,
+            checking: undefined,
             updatedAt: Date.now(),
         });
         return null;
@@ -168,6 +199,8 @@ export const recordStatus = internalMutation({
             syncStatus: completed ? "complete" : "active",
             syncError: undefined,
             failures: 0,
+            checking: undefined,
+            refreshRequested: completed ? undefined : run.refreshRequested,
             updatedAt: Date.now(),
         };
         await ctx.db.patch("runs", id, updates);
@@ -184,6 +217,9 @@ export const recordStatus = internalMutation({
             if (request)
                 await ctx.db.delete("requests", request._id);
         }
+        else {
+            await scheduleRefresh(ctx, run);
+        }
         return null;
     },
 });
@@ -191,6 +227,8 @@ export async function pause(ctx, run, message) {
     await ctx.db.patch("runs", run._id, {
         syncStatus: "paused",
         syncError: message,
+        checking: undefined,
+        refreshRequested: undefined,
         updatedAt: Date.now(),
     });
 }

package/dist/component/schema.d.ts

@@ -1,15 +1,18 @@
 declare const _default: import("convex/server").SchemaDefinition<{
     runs: import("convex/server").TableDefinition<import("convex/values").VObject<{
         callback?: string | undefined;
+        checking?: boolean | undefined;
         checks: number;
         error?: any;
         failures: number;
         generation: number;
         idempotencyKey?: string | undefined;
+        lastCheckAt?: number | undefined;
         metadata?: any;
         output?: any;
         outputOmitted?: boolean | undefined;
         outputPresignedUrl?: string | undefined;
+        refreshRequested?: boolean | undefined;
         runId?: string | undefined;
         status: string;
         syncError?: string | undefined;
@@ -32,8 +35,11 @@ declare const _default: import("convex/server").SchemaDefinition<{
         generation: import("convex/values").VFloat64<number, "required">;
         checks: import("convex/values").VFloat64<number, "required">;
         failures: import("convex/values").VFloat64<number, "required">;
+        checking: import("convex/values").VBoolean<boolean | undefined, "optional">;
+        refreshRequested: import("convex/values").VBoolean<boolean | undefined, "optional">;
+        lastCheckAt: import("convex/values").VFloat64<number | undefined, "optional">;
         callback: import("convex/values").VString<string | undefined, "optional">;
-    }, "required", "callback" | "checks" | "error" | "failures" | "generation" | "idempotencyKey" | "metadata" | "output" | "outputOmitted" | "outputPresignedUrl" | "runId" | "status" | "syncError" | "syncStatus" | "taskId" | "updatedAt" | `error.${string}` | `metadata.${string}` | `output.${string}`>, {
+    }, "required", "callback" | "checking" | "checks" | "error" | "failures" | "generation" | "idempotencyKey" | "lastCheckAt" | "metadata" | "output" | "outputOmitted" | "outputPresignedUrl" | "refreshRequested" | "runId" | "status" | "syncError" | "syncStatus" | "taskId" | "updatedAt" | `error.${string}` | `metadata.${string}` | `output.${string}`>, {
         by_key: ["idempotencyKey", "_creationTime"];
     }, {}, {}>;
     requests: import("convex/server").TableDefinition<import("convex/values").VObject<{

package/dist/component/schema.js

@@ -7,6 +7,9 @@ export default defineSchema({
         generation: v.number(),
         checks: v.number(),
         failures: v.number(),
+        checking: v.optional(v.boolean()),
+        refreshRequested: v.optional(v.boolean()),
+        lastCheckAt: v.optional(v.number()),
         callback: v.optional(v.string()),
     }).index("by_key", ["idempotencyKey"]),
     requests: defineTable({

package/dist/component/shared.d.ts

@@ -82,6 +82,7 @@ export type Run = Infer<typeof vRun>;
 export type TriggerOptions = Infer<typeof vTriggerOptions>;
 export type Config = Infer<typeof vConfig>;
 export declare const REQUEST_TIMEOUT_MS = 10000;
+export declare const MIN_REFRESH_INTERVAL_MS = 5000;
 export declare const WATCHDOG_MARGIN_MS = 5000;
 export declare const MAX_SYNC_FAILURES = 8;
 export declare const SUBMISSION_WINDOW_MS: number;

package/dist/component/shared.js

@@ -36,6 +36,7 @@ export const vRun = v.object({
 const FIRST_POLL_MS = 15_000;
 const MAX_POLL_MS = 60_000;
 export const REQUEST_TIMEOUT_MS = 10_000;
+export const MIN_REFRESH_INTERVAL_MS = 5_000;
 export const WATCHDOG_MARGIN_MS = 5_000;
 export const MAX_SYNC_FAILURES = 8;
 export const SUBMISSION_WINDOW_MS = 60 * 60 * 1_000;

package/dist/component/worker.js

@@ -1,7 +1,7 @@
 import { v } from "convex/values";
 import { internal } from "./api.js";
 import { internalAction, internalMutation } from "./server.js";
-import { pause } from "./runs.js";
+import { pause, scheduleRefresh } from "./runs.js";
 import { ApiError, inlineValue, request } from "./apiClient.js";
 import { IDEMPOTENCY_TTL, MAX_SYNC_FAILURES, REQUEST_TIMEOUT_MS, SUBMISSION_WINDOW_MS, WATCHDOG_MARGIN_MS, pollDelay, } from "./shared.js";
 const jobArgs = { id: v.id("runs"), generation: v.number() };
@@ -20,7 +20,13 @@ export const tick = internalMutation({
             return null;
         }
         const nextGeneration = generation + 1;
-        await ctx.db.patch("runs", id, { generation: nextGeneration, checks: run.checks + 1 });
+        await ctx.db.patch("runs", id, {
+            generation: nextGeneration,
+            checks: run.checks + 1,
+            checking: true,
+            refreshRequested: undefined,
+            lastCheckAt: run.runId ? Date.now() : run.lastCheckAt,
+        });
         // Schedule the watchdog transactionally before starting an action that can be interrupted.
         await ctx.scheduler.runAfter(Math.max(pollDelay(run.checks), REQUEST_TIMEOUT_MS + WATCHDOG_MARGIN_MS), internal.worker.tick, { id, generation: nextGeneration });
         await ctx.scheduler.runAfter(0, internal.worker.step, { id, generation: nextGeneration });
@@ -97,9 +103,16 @@ export const recordError = internalMutation({
         if (!run || run.generation !== generation || run.syncStatus === "complete")
             return null;
         const failures = run.failures + 1;
-        await ctx.db.patch("runs", id, { failures, syncError: message, updatedAt: Date.now() });
+        await ctx.db.patch("runs", id, {
+            failures,
+            syncError: message,
+            checking: undefined,
+            updatedAt: Date.now(),
+        });
         if (permanent || failures >= MAX_SYNC_FAILURES)
             await pause(ctx, run, message);
+        else
+            await scheduleRefresh(ctx, run);
         return null;
     },
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trigger.dev/convex",
-  "version": "4.8.2",
+  "version": "4.8.4",
   "description": "Run Trigger.dev tasks from Convex mutations and query their results reactively",
   "license": "Apache-2.0",
   "type": "module",
@@ -15,7 +15,9 @@
   "files": [
     "dist",
     "src/component",
-    "!src/component/**/*.test.ts"
+    "skills/*/SKILL.md",
+    "!src/component/**/*.test.ts",
+    "!example/**"
   ],
   "exports": {
     ".": {

package/skills/trigger-convex/SKILL.md

@@ -0,0 +1,264 @@
+---
+name: trigger-convex
+description: >
+  Integrates Trigger.dev background tasks with Convex using @trigger.dev/convex.
+  Use when triggering work transactionally from a Convex mutation, showing reactive
+  run state, handling completion callbacks, combining Trigger Realtime with Convex,
+  restoring jobs after reload, or repairing paused synchronization. Covers ownership,
+  idempotency, scoped browser tokens, and credential-safe task payloads. Not for
+  Convex-only applications or Trigger.dev applications without Convex.
+license: Apache-2.0
+---
+
+# Trigger.dev with Convex
+
+## Check the installed contract first
+
+Locate `@trigger.dev/convex/package.json`, then read the adjacent `README.md` and
+`dist/client/index.d.ts`. In a non-hoisted installation, resolve the package with:
+
+```bash
+node -p "require.resolve('@trigger.dev/convex/package.json')"
+```
+
+Use the installed declarations as authority. Older releases do not expose
+`refresh()`. If it is absent, use durable polling or upgrade to a compatible
+release; do not invent a replacement method or accept browser-supplied run state.
+Keep the application's Convex version compatible with the package's peer dependency.
+Do not pin an arbitrary preview URL unless the user explicitly needs that preview.
+
+Choose the relevant flow:
+
+| Request | Approach |
+| --- | --- |
+| Enqueue a report, render, import, or AI task | Call `trigger.trigger` inside the application's authenticated mutation. |
+| Display durable status/results | Authorize the application's job, then call `trigger.getRun` from a query. |
+| Update application records on completion | Register a short internal mutation using `vRun`. |
+| Display responsive browser progress | Subscribe to Trigger Realtime; request an authorized Convex refresh on terminal events. |
+| Restore an edit after reload or leaving the page | Persist the selected application job/request ID and inputs; recover owned work from Convex. |
+| Recover paused status synchronization | Repair credentials/callback failures, then call authorized `resume`; do not enqueue another task. |
+
+## Install and configure
+
+Install `@trigger.dev/convex` and `convex`. Deploy the actual task separately with
+Trigger.dev; the component does not deploy task code. Keep `TRIGGER_SECRET_KEY`
+only in the Convex server environment, for the intended Trigger environment.
+
+```typescript
+// convex/convex.config.ts
+import { defineApp } from "convex/server";
+import triggerComponent from "@trigger.dev/convex/convex.config.js";
+
+const app = defineApp();
+app.use(triggerComponent);
+export default app;
+```
+
+Run `npx convex dev` to generate the application's component references.
+
+```typescript
+// convex/trigger.ts
+import { Trigger } from "@trigger.dev/convex";
+import { components } from "./_generated/api";
+
+export const trigger: Trigger = new Trigger(components.trigger);
+```
+
+Constructor options are `secretKey`, `baseUrl`, and `onComplete`. The default API
+is `https://api.trigger.dev`; `TRIGGER_API_URL` is not automatically read by the
+component. Set `baseUrl` explicitly for a different API host. HTTP is allowed only
+for localhost development. Keep server keys out of `VITE_`/`NEXT_PUBLIC_` variables.
+
+## Enqueue atomically and authorize reads
+
+Maintain an application-owned job table. The component has no user/tenant model.
+This example assumes an existing deployed `process-text` task that accepts `{ text }`.
+Validate business limits and authorize any referenced documents/files before enqueueing.
+
+```typescript
+// convex/schema.ts
+import { defineSchema, defineTable } from "convex/server";
+import { v } from "convex/values";
+
+export default defineSchema({
+  jobs: defineTable({
+    owner: v.string(),
+    requestId: v.string(),
+    text: v.string(),
+    componentRunId: v.optional(v.string()),
+  }).index("by_owner_request", ["owner", "requestId"])
+    .index("by_componentRunId", ["componentRunId"]),
+});
+```
+
+```typescript
+// convex/jobs.ts
+import { vRun } from "@trigger.dev/convex";
+import { v } from "convex/values";
+import { mutation, query } from "./_generated/server";
+import { trigger } from "./trigger";
+
+export const request = mutation({
+  args: { text: v.string(), requestId: v.string() },
+  returns: v.id("jobs"),
+  handler: async (ctx, args) => {
+    const user = await ctx.auth.getUserIdentity();
+    if (!user) throw new Error("Unauthorized");
+    const owner = user.tokenIdentifier;
+    const existing = await ctx.db.query("jobs")
+      .withIndex("by_owner_request", q => q.eq("owner", owner).eq("requestId", args.requestId))
+      .unique();
+    if (existing) {
+      if (existing.text !== args.text) throw new Error("Request ID reused for different input");
+      return existing._id;
+    }
+    const jobId = await ctx.db.insert("jobs", { owner, ...args });
+    const componentRunId = await trigger.trigger(ctx, "process-text", { text: args.text }, {
+      idempotencyKey: `process-text:${owner}:${args.requestId}`,
+    });
+    await ctx.db.patch(jobId, { componentRunId });
+    return jobId;
+  },
+});
+
+export const status = query({
+  args: { jobId: v.id("jobs") },
+  returns: v.union(vRun, v.null()),
+  handler: async (ctx, { jobId }) => {
+    const user = await ctx.auth.getUserIdentity();
+    const job = await ctx.db.get(jobId);
+    if (!user || !job || job.owner !== user.tokenIdentifier) return null;
+    return job.componentRunId ? trigger.getRun(ctx, job.componentRunId) : null;
+  },
+});
+```
+
+Preserve the same request ID when retrying an unconfirmed submission. Namespace
+component idempotency keys by tenant/owner, task, and logical request. They dedupe
+across the entire component instance, not just a task, and do not compare payloads.
+An application mutation rollback also rolls back the component enqueue/scheduling.
+Do not replace this with a direct SDK trigger from an action if atomicity is required.
+Use type-only task imports when adding task payload inference; do not bundle task
+implementations, Sharp, or provider clients into the Convex mutation runtime.
+
+There are three distinct identifiers:
+
+- Application `jobId`: accept this from the browser and enforce ownership.
+- Component `run.id`: returned by `trigger.trigger`; pass it to `getRun`, `refresh`, and `resume`.
+- Remote `run.runId`: available after submission; subscribe to this with Trigger Realtime.
+
+For React, use an application query such as `useQuery(api.jobs.status, { jobId })`.
+Only persist/display results verified by Convex. `getRun` omits stored credentials
+and request payloads, but its output, errors, and metadata can still contain private data.
+Do not expose `listRuns` as a global client-visible feed; use indexed owned jobs and
+bounded lookups instead.
+
+## Apply completion to application state
+
+When an application record must change on completion, extend its schema with the
+task-specific status/result fields, then add an internal mutation with
+`args: { run: vRun }` and `returns: v.null()`. Find its job through the
+`by_componentRunId` index using `run.id`, validate the task's output, and update it.
+Configure the client with `onComplete: internal.jobs.complete`; keep the explicit
+`Trigger` type annotation to avoid circular inference through the generated API.
+
+Keep the callback short and transactional. It runs with the component's terminal
+update; throwing rolls both back and schedules a retry. Do network I/O in separate
+actions, not in the callback mutation. A callback is optional for reactive reads.
+Treat omitted output and expiring output URLs explicitly rather than assuming every
+completed run has an inline result.
+
+## Combine Realtime progress with authoritative Convex state
+
+Install `@trigger.dev/react-hooks` in a React frontend and `@trigger.dev/sdk` in the
+server that mints tokens. These are separate from the component-only polling setup.
+
+Only use the following wrapper if the installed component exposes `refresh()`:
+
+```typescript
+// Add to convex/jobs.ts
+export const refresh = mutation({
+  args: { jobId: v.id("jobs") },
+  returns: v.null(),
+  handler: async (ctx, { jobId }) => {
+    const user = await ctx.auth.getUserIdentity();
+    const job = await ctx.db.get(jobId);
+    if (!user || !job || job.owner !== user.tokenIdentifier) throw new Error("Unauthorized");
+    if (job.componentRunId) await trigger.refresh(ctx, job.componentRunId);
+    return null;
+  },
+});
+```
+
+1. Authenticate a server-side token request and verify the application job's owner.
+   Derive its remote run ID on the server; never grant access to a caller-chosen run.
+2. Mint a short-lived `auth.createPublicToken` scoped to `read: { runs: [runId] }`.
+   Use an SDK-capable server runtime, such as a Convex Node action, and scoped
+   `auth.withAuth` configuration rather than mutating shared global credentials.
+   The SDK spells its API host option `baseURL`, unlike the component's `baseUrl`.
+   Match the key/host environment, bound expiry to the application's access lifetime,
+   and return only the token, remote ID, expiry, and required public connection URL.
+3. Subscribe with `useRealtimeRun` or `runs.subscribeToRun` only after the remote ID
+   exists. Limit the browser to the selected owned run, renew credentials through
+   the authorized endpoint, and clean up on job/session changes. Reject late token
+   responses and metadata for a previous selection.
+4. On completion, including an already-terminal snapshot after reconnecting, call
+   the owned `refresh` mutation. Include failed, canceled, expired, and timed-out
+   runs. Do not refresh on every metadata update or retry a failed effect in a loop.
+5. Observe the Convex query for persisted status/results. A refresh returns `null`
+   after scheduling; it does not wait for completion or return a new run snapshot.
+   Keep scheduled polling/watchdog recovery enabled when the browser goes away.
+
+Refresh hints are coalesced per run, with refresh-driven checks at least five seconds
+after the previous status check. An in-flight hint queues a follow-up without
+invalidating that observation. Pending submissions, paused synchronization, and
+completed records are no-ops; refresh neither submits work nor resumes paused work.
+
+**Token safety:** a run-read token also authorizes REST reads of its payload.
+Realtime `skipColumns: ["payload", "output"]` reduces streamed data; it does not
+restrict REST access. Remove worker keys, upload capabilities, and other credentials
+from token-readable payloads, outputs, metadata, and errors before issuing browser
+tokens. Do not mint tokens for legacy runs that still contain credentials; deploying
+new code or changing column filters does not rewrite old remote payloads. Derive worker authorization server-side or use server-only signing instead.
+Authorize private artifact delivery separately; a public run token is not a file
+access policy. Keep browser run tokens in memory and never log credentials.
+
+Persist the selected application job ID, draft inputs, and unconfirmed request ID
+before sending a request. Restore owned active jobs from Convex after reload;
+otherwise restore only explicit selections, not any old result with matching defaults.
+Use actual task metadata for phase progress, explain disabled submission states,
+and do not publish results solely because Realtime reports completion.
+
+## Troubleshoot without duplicating work
+
+| Symptom | Fix |
+| --- | --- |
+| Duplicate jobs after a lost response | Reuse the logical request ID and query the owned job before enqueueing again. |
+| Wrong run or a null remote ID | Distinguish application/component/remote IDs; wait for confirmed submission before subscribing. |
+| Browser refresh resolves but results lag | Observe Convex; refresh is asynchronous, coalesced, and rate-limited. |
+| Component/validator types are incompatible | Check for duplicate Convex installations or peer contexts; align component/consumer dependencies rather than hiding mismatches with casts. |
+| `refresh` is missing | Check installed declarations; upgrade deliberately or retain polling, not a fabricated API. |
+| `syncStatus === "paused"` | Inspect `syncError`, repair credentials/callbacks, then authorize `resume(ctx, componentId)`. |
+| Old work disappears after reload | Persist selection/inputs/request ID; recover owned active work instead of resetting to defaults. |
+| Token leaks worker access | Remove credentials from all readable run fields; column filtering cannot repair this. |
+| Data from another tenant appears | Authorize every query/mutation/token/artifact request; never trust arbitrary IDs or shared tags. |
+| Successful remote work never commits | Check callback errors and output validation; retries roll back application completion too. |
+| Large or missing results | Use storage references; inspect `outputOmitted`/`outputPresignedUrl` and refresh expired URLs server-side. |
+| Run exists in a different environment | Align API host/key; resume does not migrate remote runs between environments. |
+
+Polling normally backs off from about 15 to 60 seconds. Account for Convex executions
+and Trigger API requests at scale; use Realtime for responsive UI, not rapid polling.
+Payload plus trigger options must fit within 256 KiB, as must each inline output,
+error, and metadata value. Component records are retained; paused requests retain
+credentials and payloads for recovery, so plan application retention separately.
+Remote submission uses a 24-hour idempotency TTL, but automatic submission retries
+stop within one hour. After that window, reconcile remotely before creating new work;
+do not claim unlimited exactly-once execution or blindly retry expensive tasks.
+
+## Verify the integration
+
+Check mutation rollback, duplicate request IDs, cross-owner denial, callback failures,
+and reconnecting to an already-terminal run. Verify that leaving the page does not
+prevent durable completion. If tokens are issued, test cross-run denial and inspect
+the full REST-readable payload for credentials. Add focused integration coverage;
+do not spend on real provider calls or deploy without the user's authorization.

package/src/component/runs.test.ts

@@ -6,7 +6,7 @@ import { defineSchema, defineTable } from "convex/server";
 import { v } from "convex/values";
 import { Trigger, vRun, type ComponentApi } from "../client/index.js";
 import schema from "./schema.js";
-import { MAX_INLINE_BYTES } from "./shared.js";
+import { MAX_INLINE_BYTES, MIN_REFRESH_INTERVAL_MS } from "./shared.js";
 
 const modules = {
   "./_generated/component.ts": () => import("./_generated/component.js"),
@@ -63,6 +63,10 @@ const { createTest, api, internal } = app.defineModules({
         return id;
       },
     }),
+    refresh: app.mutation({
+      args: { id: v.string() },
+      handler: async (ctx, { id }) => new Trigger(app.components.trigger).refresh(ctx, id),
+    }),
   },
 });
 
@@ -92,6 +96,8 @@ let remoteStatus: string;
 let remoteIsCompleted: boolean;
 let largeOutput: boolean;
 let submittedOptions: Record<string, unknown>;
+let holdNextPoll: boolean;
+let releasePoll: (() => void) | undefined;
 
 beforeAll(async () => {
   server = createServer(async (req, res) => {
@@ -125,19 +131,26 @@ beforeAll(async () => {
         return;
       }
       const completed = activePolls-- <= 0;
-      res.end(
-        JSON.stringify({
-          id: "run_1",
-          status: completed ? remoteStatus : "EXECUTING",
-          isCompleted: completed && remoteIsCompleted,
-          output: completed
-            ? largeOutput
-              ? "x".repeat(MAX_INLINE_BYTES + 1)
-              : { url: "https://example.com/video.mp4" }
-            : undefined,
-          metadata: { progress: completed ? 100 : 50 },
-        })
-      );
+      const body = JSON.stringify({
+        id: "run_1",
+        status: completed ? remoteStatus : "EXECUTING",
+        isCompleted: completed && remoteIsCompleted,
+        output: completed
+          ? largeOutput
+            ? "x".repeat(MAX_INLINE_BYTES + 1)
+            : { url: "https://example.com/video.mp4" }
+          : undefined,
+        metadata: { progress: completed ? 100 : 50 },
+      });
+      if (holdNextPoll) {
+        holdNextPoll = false;
+        releasePoll = () => {
+          if (!res.writableEnded) res.end(body);
+          releasePoll = undefined;
+        };
+      } else {
+        res.end(body);
+      }
     }
   });
   server.listen(0, "127.0.0.1");
@@ -162,8 +175,13 @@ beforeEach(() => {
   remoteIsCompleted = true;
   largeOutput = false;
   submittedOptions = {};
+  holdNextPoll = false;
+  releasePoll = undefined;
+});
+afterEach(() => {
+  releasePoll?.();
+  vi.useRealTimers();
 });
-afterEach(() => vi.useRealTimers());
 afterAll(
   () =>
     new Promise<void>((resolve, reject) => {
@@ -344,6 +362,135 @@ test("a failing callback rolls back completion and can be retried without duplic
   expect(await t.run((ctx) => ctx.db.query("completions").collect())).toHaveLength(1);
 });
 
+async function runScheduled(t: ReturnType<typeof createTest>, advanceMs = 0): Promise<void> {
+  // Convex timestamps have sub-millisecond precision, so zero-delay jobs may fall just after now.
+  vi.advanceTimersByTime(advanceMs + 1);
+  await t.finishInProgressScheduledFunctions();
+  vi.advanceTimersByTime(1);
+  await t.finishInProgressScheduledFunctions();
+}
+
+// Catches: refresh bursts bypassing the check cooldown or racing the polling callback.
+test("refreshes promptly, bounds repeated checks, and completes once alongside polling", async () => {
+  activePolls = 1;
+  const t = createTest();
+  const id = await t.mutation(api.jobs.request, {});
+  await runScheduled(t);
+  expect(submissions).toBe(1);
+  expect(polls).toBe(0);
+
+  await Promise.all(Array.from({ length: 3 }, () => t.mutation(api.jobs.refresh, { id })));
+  await runScheduled(t);
+  expect(polls).toBe(1);
+  expect(await t.query(app.components.trigger.runs.get, { id })).toMatchObject({
+    status: "EXECUTING",
+    metadata: { progress: 50 },
+  });
+
+  await Promise.all(Array.from({ length: 3 }, () => t.mutation(api.jobs.refresh, { id })));
+  await runScheduled(t, MIN_REFRESH_INTERVAL_MS / 2);
+  expect(polls).toBe(1);
+  await runScheduled(t, MIN_REFRESH_INTERVAL_MS / 2);
+  expect(polls).toBe(2);
+  expect(await t.query(app.components.trigger.runs.get, { id })).toMatchObject({
+    status: "COMPLETED",
+    syncStatus: "complete",
+    output: { url: "https://example.com/video.mp4" },
+  });
+  await t.mutation(api.jobs.refresh, { id });
+  await drain(t);
+  expect(polls).toBe(2);
+  expect(submissions).toBe(1);
+  expect(await t.run((ctx) => ctx.db.query("completions").collect())).toHaveLength(1);
+});
+
+// Catches: refresh fencing out an in-flight observation or losing its completion hint.
+test("coalesces hints during an in-flight request and follows it with another check", async () => {
+  activePolls = 1;
+  const t = createTest();
+  const id = await t.mutation(api.jobs.request, {});
+  await runScheduled(t);
+  holdNextPoll = true;
+  const received = once(server, "request");
+  await t.mutation(api.jobs.refresh, { id });
+  vi.advanceTimersByTime(1);
+  await t.finishInProgressScheduledFunctions();
+  vi.advanceTimersByTime(1);
+  const checking = t.finishInProgressScheduledFunctions();
+  await received;
+  try {
+    await t.mutation(api.jobs.refresh, { id });
+    await t.mutation(api.jobs.refresh, { id });
+    vi.advanceTimersByTime(MIN_REFRESH_INTERVAL_MS);
+    expect(polls).toBe(1);
+    releasePoll!();
+    await checking;
+    expect(await t.query(app.components.trigger.runs.get, { id })).toMatchObject({
+      status: "EXECUTING",
+      syncStatus: "active",
+      metadata: { progress: 50 },
+    });
+    await runScheduled(t);
+    expect(polls).toBe(2);
+    expect(await t.query(app.components.trigger.runs.get, { id })).toMatchObject({
+      status: "COMPLETED",
+      syncStatus: "complete",
+    });
+    expect(await t.run((ctx) => ctx.db.query("completions").collect())).toHaveLength(1);
+  } finally {
+    releasePoll?.();
+    await checking;
+  }
+});
+
+// Catches: a failed status request leaving refresh permanently blocked as in-flight.
+test("allows a refresh after a retryable status error", async () => {
+  pollFailures = 1;
+  const t = createTest();
+  const id = await t.mutation(api.jobs.request, {});
+  await runScheduled(t);
+  await t.mutation(api.jobs.refresh, { id });
+  await runScheduled(t);
+  expect(polls).toBe(1);
+  expect(await t.query(app.components.trigger.runs.get, { id })).toMatchObject({
+    syncStatus: "active",
+  });
+  await t.mutation(api.jobs.refresh, { id });
+  await runScheduled(t, MIN_REFRESH_INTERVAL_MS);
+  expect(polls).toBe(2);
+  expect(await t.query(app.components.trigger.runs.get, { id })).toMatchObject({
+    syncStatus: "complete",
+  });
+});
+
+// Catches: browser hints resubmitting pending work or bypassing a permanent synchronization failure.
+test("does not submit pending work early or resume paused synchronization", async () => {
+  pollFailures = 1;
+  pollFailureStatus = 401;
+  const t = createTest();
+  const id = await t.mutation(api.jobs.request, {});
+  await t.mutation(api.jobs.refresh, { id });
+  expect(submissions).toBe(0);
+  await runScheduled(t);
+  await t.mutation(api.jobs.refresh, { id });
+  await runScheduled(t);
+  expect(await t.query(app.components.trigger.runs.get, { id })).toMatchObject({
+    syncStatus: "paused",
+  });
+  await t.mutation(api.jobs.refresh, { id });
+  await runScheduled(t, MIN_REFRESH_INTERVAL_MS);
+  expect(polls).toBe(1);
+  expect(submissions).toBe(1);
+  await t.mutation(app.components.trigger.runs.resume, {
+    id,
+    config: { secretKey: "test-only-key", baseUrl },
+  });
+  await drain(t);
+  expect(await t.query(app.components.trigger.runs.get, { id })).toMatchObject({
+    syncStatus: "complete",
+  });
+});
+
 test("rejects large inputs before scheduling remote work", async () => {
   const t = createTest();
   await expect(

package/src/component/runs.ts

@@ -9,6 +9,7 @@ import { internalMutation, internalQuery, mutation, query, type DataModel } from
 import {
   MAX_INLINE_BYTES,
   MAX_PAGE_BYTES,
+  MIN_REFRESH_INTERVAL_MS,
   SUBMISSION_WINDOW_MS,
   vConfig,
   vRun,
@@ -19,7 +20,18 @@ import {
 type RunDoc = DataModel["runs"]["document"];
 
 export function toRun(run: RunDoc): Run {
-  const { _id, _creationTime, generation, checks, failures, callback, ...fields } = run;
+  const {
+    _id,
+    _creationTime,
+    generation,
+    checks,
+    failures,
+    callback,
+    checking,
+    refreshRequested,
+    lastCheckAt,
+    ...fields
+  } = run;
   return { id: _id, createdAt: _creationTime, ...fields };
 }
 
@@ -110,6 +122,36 @@ export const list = query({
   },
 });
 
+export async function scheduleRefresh(
+  ctx: GenericMutationCtx<DataModel>,
+  run: RunDoc
+): Promise<void> {
+  if (!run.refreshRequested) return;
+  const delay =
+    run.lastCheckAt === undefined
+      ? 0
+      : Math.max(0, run.lastCheckAt + MIN_REFRESH_INTERVAL_MS - Date.now());
+  await ctx.scheduler.runAfter(delay, internal.worker.tick, {
+    id: run._id,
+    generation: run.generation,
+  });
+}
+
+export const refresh = mutation({
+  args: { id: v.string() },
+  returns: v.null(),
+  handler: async (ctx, { id }): Promise<null> => {
+    const runId = ctx.db.normalizeId("runs", id);
+    const run = runId ? await ctx.db.get("runs", runId) : null;
+    if (!run) throw new Error("Run not found");
+    if (!run.runId || run.syncStatus !== "active" || run.refreshRequested) return null;
+    await ctx.db.patch(run._id, { refreshRequested: true });
+    // Preserve the in-flight observation; its result will schedule any requested follow-up.
+    if (!run.checking) await scheduleRefresh(ctx, { ...run, refreshRequested: true });
+    return null;
+  },
+});
+
 export const resume = mutation({
   args: { id: v.string(), config: vConfig },
   returns: v.null(),
@@ -136,6 +178,8 @@ export const resume = mutation({
       failures: 0,
       checks: 0,
       generation,
+      checking: undefined,
+      refreshRequested: undefined,
       updatedAt: Date.now(),
     });
     await ctx.scheduler.runAfter(0, internal.worker.tick, { id: run._id, generation });
@@ -168,6 +212,7 @@ export const recordSubmission = internalMutation({
       syncError: undefined,
       failures: 0,
       checks: 0,
+      checking: undefined,
       updatedAt: Date.now(),
     });
     return null;
@@ -195,6 +240,8 @@ export const recordStatus = internalMutation({
       syncStatus: completed ? ("complete" as const) : ("active" as const),
       syncError: undefined,
       failures: 0,
+      checking: undefined,
+      refreshRequested: completed ? undefined : run.refreshRequested,
       updatedAt: Date.now(),
     };
     await ctx.db.patch("runs", id, updates);
@@ -209,6 +256,8 @@ export const recordStatus = internalMutation({
         .withIndex("by_run", (q) => q.eq("run", id))
         .unique();
       if (request) await ctx.db.delete("requests", request._id);
+    } else {
+      await scheduleRefresh(ctx, run);
     }
     return null;
   },
@@ -222,6 +271,8 @@ export async function pause(
   await ctx.db.patch("runs", run._id, {
     syncStatus: "paused",
     syncError: message,
+    checking: undefined,
+    refreshRequested: undefined,
     updatedAt: Date.now(),
   });
 }

package/src/component/schema.ts

@@ -8,6 +8,9 @@ export default defineSchema({
     generation: v.number(),
     checks: v.number(),
     failures: v.number(),
+    checking: v.optional(v.boolean()),
+    refreshRequested: v.optional(v.boolean()),
+    lastCheckAt: v.optional(v.number()),
     callback: v.optional(v.string()),
   }).index("by_key", ["idempotencyKey"]),
   requests: defineTable({

package/src/component/shared.ts

@@ -49,6 +49,7 @@ export type Config = Infer<typeof vConfig>;
 const FIRST_POLL_MS = 15_000;
 const MAX_POLL_MS = 60_000;
 export const REQUEST_TIMEOUT_MS = 10_000;
+export const MIN_REFRESH_INTERVAL_MS = 5_000;
 export const WATCHDOG_MARGIN_MS = 5_000;
 export const MAX_SYNC_FAILURES = 8;
 export const SUBMISSION_WINDOW_MS = 60 * 60 * 1_000;

package/src/component/worker.ts

@@ -1,7 +1,7 @@
 import { v } from "convex/values";
 import { internal } from "./api.js";
 import { internalAction, internalMutation } from "./server.js";
-import { pause } from "./runs.js";
+import { pause, scheduleRefresh } from "./runs.js";
 import { ApiError, inlineValue, request } from "./apiClient.js";
 import {
   IDEMPOTENCY_TTL,
@@ -35,7 +35,13 @@ export const tick = internalMutation({
       return null;
     }
     const nextGeneration = generation + 1;
-    await ctx.db.patch("runs", id, { generation: nextGeneration, checks: run.checks + 1 });
+    await ctx.db.patch("runs", id, {
+      generation: nextGeneration,
+      checks: run.checks + 1,
+      checking: true,
+      refreshRequested: undefined,
+      lastCheckAt: run.runId ? Date.now() : run.lastCheckAt,
+    });
     // Schedule the watchdog transactionally before starting an action that can be interrupted.
     await ctx.scheduler.runAfter(
       Math.max(pollDelay(run.checks), REQUEST_TIMEOUT_MS + WATCHDOG_MARGIN_MS),
@@ -124,8 +130,14 @@ export const recordError = internalMutation({
     const run = await ctx.db.get("runs", id);
     if (!run || run.generation !== generation || run.syncStatus === "complete") return null;
     const failures = run.failures + 1;
-    await ctx.db.patch("runs", id, { failures, syncError: message, updatedAt: Date.now() });
+    await ctx.db.patch("runs", id, {
+      failures,
+      syncError: message,
+      checking: undefined,
+      updatedAt: Date.now(),
+    });
     if (permanent || failures >= MAX_SYNC_FAILURES) await pause(ctx, run, message);
+    else await scheduleRefresh(ctx, run);
     return null;
   },
 });