Task & Run Hooks

[ericallam]

We should give users the ability to hook into the task and run lifecycle

import { prisma } from "./db";import { prisma } from "./db";
import { TriggerClient } from "@trigger.dev/sdk";

const client = new TriggerClient({
  id: "my-app",
  hooks: {
    onTaskCompleted: (task, job, payload, ctx) =>
      prisma.tasks.upsert({
        where: { id: task.idempotencyKey },
        create: { id: task.idempotencyKey, data: task.output },
        update: { data: task.output },
      }), // keep a local record of all tasks if you want to
    beforeTaskRun: async (task, job, payload, ctx) => {
      const existingTask = await prisma.tasks.findUnique({
        id: task.idempotencyKey,
      });

      return existingTask?.data; // Can keep a local cache of tasks and provide output
    },
    onTaskFailed: async (task, error, job, payload, ctx) => {
      // Do something when a task fails
    },
    onRunFinished: async (job, run, payload, ctx) => {
      // Do something when a run is completed/cancelled/failed
    },
    onRunCompleted: async (job, run, payload, ctx) => {
      // Do something when a run is completed
    },
    onRunCancelled: async (job, run, payload, ctx) => {
      // Do something when a run is cancelled
    },
    onRunFailed: async (job, run, payload, ctx) => {
      // Do something when a run is cancelled
    },
  },
});

// They can also be defined on at the job level
client.defineJob({
  id: "my-job",
  onTaskCompleted: (task, payload, ctx) => {},
  beforeTaskRun: async (task, payload, ctx) => {
  },
  onTaskFailed: async (task, error, payload, ctx) => {
    // Do something when a task fails
  },
  onRunFinished: async (run, payload, ctx) => {
    // Do something when a run is completed/cancelled/failed
  },
  onRunCompleted: async (run, payload, ctx) => {
    // Do something when a run is completed
  },
  onRunCancelled: async (run, payload, ctx) => {
    // Do something when a run is cancelled
  },
  onRunFailed: async (run, payload, ctx) => {
    // Do something when a run is cancelled
  },
});

[kinthaiofficial]

Task and run hooks are one of those features that seem simple but unlock a lot of patterns when you're building complex workflows.

A few use cases where pre/post hooks have been most valuable in agent-style workloads:

Cost tracking: A beforeRun hook to record start time + estimated token budget, afterRun hook to log actual usage and alert if over budget:

export const myTask = task({
  id: "agent-task",
  onStart: async ({ payload, ctx }) => {
    await db.runs.create({
      runId: ctx.run.id,
      startedAt: new Date(),
      estimatedCost: estimateCost(payload),
    });
  },
  onSuccess: async ({ payload, output, ctx }) => {
    await db.runs.update(ctx.run.id, {
      completedAt: new Date(),
      actualCost: output.tokensUsed * COST_PER_TOKEN,
    });
  },
  run: async (payload) => {
    // main logic
  },
});

Audit receipts: afterRun hook to sign and store what the agent did — useful for compliance-sensitive workflows where you need a tamper-evident record.

Memory consolidation: After each task, a hook that summarizes what was learned and writes to the agent's long-term memory store.

The pattern where hooks can themselves trigger tasks gets powerful quickly — just watch out for cycles.

More on economic tracking for autonomous agents: https://blog.kinthai.ai/agent-wallet-economic-models-autonomous-agents