feat: Sessions dashboard, task_kind, and chat-ready hardening (1/4) (#3542)

## Summary

A `/sessions` dashboard for inspecting durable Sessions, an `AGENT` /
`SCHEDULED` task-kind filter for the runs list, and the server-side
hardening (rate-limit exemption for packets, retry-with-backoff on
stream appends, typed too-large-chunk error) that the `chat.agent`
runtime in #3543 needs. Builds on the Sessions primitive shipped in
#3417.

## Design

The Sessions list + detail routes mirror the run inspector pattern.
`TaskTriggerSource` gains `AGENT` and `SCHEDULED` values, persisted on
`BackgroundWorker.taskKind` and `TaskRun.taskKind` (plus a matching
Clickhouse column), so the runs list can filter by kind.

New `@trigger.dev/core` modules — `sessionStreams`, `inputStreams`, a
`sessionStreamInstance` for realtime streams, and the
`realtime-streams-api` / `session-streams-api` surfaces — expose the
typed shapes that chat.agent will use to drive `session.out`.
`ChatChunkTooLargeError` lets the runtime drop oversized chunks with a
typed surface instead of failing the run. `s2Append` retries transient
failures with exponential backoff. `/api/v[12]/packets/*` is exempt from
customer rate limits so chat snapshot reads and writes don't get
throttled under load.

## Stack

Part of a 4-PR stack. Merge bottom-up.

1. **This PR** (#3542) → `main`
2. #3543 → #3542 — `chat.agent` runtime + browser transport
3. #3545 → #3543 — agent-view dashboard
4. #3546 → #3545 — ai-chat reference + MCP tooling

Replaces #3173 (closed).

<!-- GitButler Footer Boundary Top -->
---
This is **part 5 of 5 in a stack** made with GitButler:
- <kbd>&nbsp;5&nbsp;</kbd> #3612
- <kbd>&nbsp;4&nbsp;</kbd> #3546
- <kbd>&nbsp;3&nbsp;</kbd> #3545
- <kbd>&nbsp;2&nbsp;</kbd> #3543
- <kbd>&nbsp;1&nbsp;</kbd> #3542 👈 
<!-- GitButler Footer Boundary Bottom -->

Author: ericallam

.changeset/chat-ready-core-additions.md

@@ -0,0 +1,5 @@
+---
+"@trigger.dev/core": patch
+---
+
+Add `ChatChunkTooLargeError` and ApiClient methods for subscribing to session streams. Lays the groundwork for the upcoming `chat.agent`.

.changeset/sessions-primitive.md

@@ -0,0 +1,9 @@
+---
+"@trigger.dev/sdk": minor
+"@trigger.dev/core": patch
+---
+
+Adds the Sessions primitive — a durable, run-aware stream channel keyed
+on a stable `externalId`. Public SDK additions: `tasks.triggerAndSubscribe()`
+and the `chat.agent` runtime built on top of Sessions. See
+https://trigger.dev/docs/ai-chat/overview for the full feature surface.

.gitignore

@@ -65,6 +65,10 @@ apps/**/public/build
 /packages/trigger-sdk/src/package.json
 /packages/python/src/package.json
 **/.claude/settings.local.json
+.claude/architecture/
+.claude/docs-plans/
+.claude/review-guides/
+.claude/scheduled_tasks.lock
 .mcp.log
 .mcp.json
 .cursor/debug.log

.server-changes/sessions-dashboard-and-task-source-filter.md

@@ -0,0 +1,6 @@
+---
+area: webapp
+type: feature
+---
+
+New Sessions page in the dashboard for inspecting `chat.agent` Session rows alongside their underlying runs, plus a "Task source" filter on the Runs list (Standard / Scheduled / Agent) so agent runs can be sliced out of mixed workloads at a glance.

CLAUDE.md

@@ -6,6 +6,8 @@ This file provides guidance to Claude Code when working with this repository. Su
 
 This is a pnpm 10.33.2 monorepo using Turborepo. Run commands from root with `pnpm run`.
 
+**Adding dependencies:** Edit `package.json` directly instead of using `pnpm add`, then run `pnpm i` from the repo root. See `.claude/rules/package-installation.md` for the full process.
+
 ```bash
 pnpm run docker              # Start Docker services (PostgreSQL, Redis, Electric)
 pnpm run db:migrate           # Run database migrations

apps/webapp/app/components/BlankStatePanels.tsx

@@ -1,4 +1,5 @@
 import {
+  ArrowsRightLeftIcon,
   BeakerIcon,
   BellAlertIcon,
   BookOpenIcon,
@@ -189,6 +190,28 @@ export function BatchesNone() {
   );
 }
 
+export function SessionsNone() {
+  return (
+    <InfoPanel
+      title="Sessions"
+      icon={ArrowsRightLeftIcon}
+      iconClassName="text-teal-500"
+      panelClassName="max-w-full"
+      accessory={
+        <LinkButton to={docsPath("/ai-chat/overview")} variant="docs/small" LeadingIcon={BookOpenIcon}>
+          Sessions docs
+        </LinkButton>
+      }
+    >
+      <Paragraph spacing variant="small">
+        You have no sessions in this environment. Sessions are durable, typed, bidirectional I/O
+        primitives that outlive a single run — used by <InlineCode>chat.agent</InlineCode> and any
+        long-running task that needs streaming input and output.
+      </Paragraph>
+    </InfoPanel>
+  );
+}
+
 export function TestHasNoTasks() {
   const organization = useOrganization();
   const project = useProject();

apps/webapp/app/components/BulkActionFilterSummary.tsx

@@ -240,6 +240,19 @@ export function BulkActionFilterSummary({
                     />
                   );
                 }
+                case "sources": {
+                  const values = Array.isArray(value) ? value : [`${value}`];
+                  return (
+                    <AppliedFilter
+                      variant="minimal/medium"
+                      key={key}
+                      label={filterTitle(key)}
+                      icon={filterIcon(key)}
+                      value={appliedSummary(values)}
+                      removable={false}
+                    />
+                  );
+                }
                 default: {
                   assertNever(typedKey);
                 }

apps/webapp/app/components/runs/v3/RunFilters.tsx

@@ -2,6 +2,7 @@ import * as Ariakit from "@ariakit/react";
 import {
   CalendarIcon,
   ClockIcon,
+  CpuChipIcon,
   FingerPrintIcon,
   PlusIcon,
   RectangleStackIcon,
@@ -190,6 +191,9 @@ export const TaskRunListSearchFilters = z.object({
     `Machine presets to filter by (${machines.join(", ")})`
   ),
   errorId: z.string().optional().describe("Error ID to filter runs by (e.g. error_abc123)"),
+  sources: StringOrStringArray.describe(
+    "Task trigger sources to filter by (STANDARD, SCHEDULED, AGENT)"
+  ),
 });
 
 export type TaskRunListSearchFilters = z.infer<typeof TaskRunListSearchFilters>;
@@ -231,6 +235,8 @@ export function filterTitle(filterKey: string) {
       return "Version";
     case "errorId":
       return "Error ID";
+    case "sources":
+      return "Source";
     default:
       return filterKey;
   }
@@ -271,6 +277,8 @@ export function filterIcon(filterKey: string): ReactNode | undefined {
       return <IconRotateClockwise2 className="size-4" />;
     case "errorId":
       return <IconBugFilled className="size-4" />;
+    case "sources":
+      return <CpuChipIcon className="size-4" />;
     default:
       return undefined;
   }
@@ -318,6 +326,10 @@ export function getRunFiltersFromSearchParams(
         ? searchParams.getAll("versions")
         : undefined,
     errorId: searchParams.get("errorId") ?? undefined,
+    sources:
+      searchParams.getAll("sources").filter((v) => v.length > 0).length > 0
+        ? searchParams.getAll("sources")
+        : undefined,
   };
 
   const parsed = TaskRunListSearchFilters.safeParse(params);
@@ -359,7 +371,8 @@ export function RunsFilters(props: RunFiltersProps) {
     searchParams.has("queues") ||
     searchParams.has("machines") ||
     searchParams.has("versions") ||
-    searchParams.has("errorId");
+    searchParams.has("errorId") ||
+    searchParams.has("sources");
 
   return (
     <div className="flex flex-row flex-wrap items-center gap-1.5">
@@ -395,6 +408,7 @@ const filterTypes = [
   { name: "schedule", title: "Schedule ID", icon: <ClockIcon className="size-4" /> },
   { name: "bulk", title: "Bulk action", icon: <ListCheckedIcon className="size-4" /> },
   { name: "error", title: "Error ID", icon: <IconBugFilled className="size-4" /> },
+  { name: "source", title: "Source", icon: <CpuChipIcon className="size-4" /> },
 ] as const;
 
 type FilterType = (typeof filterTypes)[number]["name"];
@@ -448,6 +462,7 @@ function AppliedFilters({ bulkActions }: RunFiltersProps) {
       <AppliedScheduleIdFilter />
       <AppliedBulkActionsFilter bulkActions={bulkActions} />
       <AppliedErrorIdFilter />
+      <AppliedSourceFilter />
     </>
   );
 }
@@ -482,6 +497,8 @@ function Menu(props: MenuProps) {
       return <VersionsDropdown onClose={() => props.setFilterType(undefined)} {...props} />;
     case "error":
       return <ErrorIdDropdown onClose={() => props.setFilterType(undefined)} {...props} />;
+    case "source":
+      return <SourceDropdown onClose={() => props.setFilterType(undefined)} {...props} />;
   }
 }
 
@@ -1739,3 +1756,101 @@ function AppliedErrorIdFilter() {
     </FilterMenuProvider>
   );
 }
+
+const sourceOptions: { value: TaskTriggerSource; title: string }[] = [
+  { value: "STANDARD", title: "Standard" },
+  { value: "SCHEDULED", title: "Scheduled" },
+  { value: "AGENT", title: "Agent" },
+];
+
+function SourceDropdown({
+  trigger,
+  clearSearchValue,
+  searchValue,
+  onClose,
+}: {
+  trigger: ReactNode;
+  clearSearchValue: () => void;
+  searchValue: string;
+  onClose?: () => void;
+}) {
+  const { values, replace } = useSearchParams();
+
+  const handleChange = (values: string[]) => {
+    clearSearchValue();
+    replace({ sources: values, cursor: undefined, direction: undefined });
+  };
+
+  const filtered = useMemo(() => {
+    return sourceOptions.filter((item) =>
+      item.title.toLowerCase().includes(searchValue.toLowerCase())
+    );
+  }, [searchValue]);
+
+  return (
+    <SelectProvider value={values("sources")} setValue={handleChange} virtualFocus={true}>
+      {trigger}
+      <SelectPopover
+        className="min-w-0 max-w-[min(240px,var(--popover-available-width))]"
+        hideOnEscape={() => {
+          if (onClose) {
+            onClose();
+            return false;
+          }
+          return true;
+        }}
+      >
+        <ComboBox placeholder={"Filter by source..."} value={searchValue} />
+        <SelectList>
+          {filtered.map((item, index) => (
+            <SelectItem
+              key={item.value}
+              value={item.value}
+              icon={
+                <TaskTriggerSourceIcon source={item.value} className="size-4 flex-none" />
+              }
+              shortcut={shortcutFromIndex(index, { shortcutsEnabled: true })}
+            >
+              {item.title}
+            </SelectItem>
+          ))}
+        </SelectList>
+      </SelectPopover>
+    </SelectProvider>
+  );
+}
+
+function AppliedSourceFilter() {
+  const { values, del } = useSearchParams();
+  const sources = values("sources");
+
+  if (sources.length === 0 || sources.every((v) => v === "")) {
+    return null;
+  }
+
+  return (
+    <FilterMenuProvider>
+      {(search, setSearch) => (
+        <SourceDropdown
+          trigger={
+            <Ariakit.Select render={<div className="group cursor-pointer focus-custom" />}>
+              <AppliedFilter
+                label="Source"
+                icon={<CpuChipIcon className="size-4" />}
+                value={appliedSummary(
+                  sources.map(
+                    (v) => sourceOptions.find((o) => o.value === v)?.title ?? v
+                  )
+                )}
+                onRemove={() => del(["sources", "cursor", "direction"])}
+                variant="secondary/small"
+              />
+            </Ariakit.Select>
+          }
+          searchValue={search}
+          clearSearchValue={() => setSearch("")}
+        />
+      )}
+    </FilterMenuProvider>
+  );
+}

apps/webapp/app/components/runs/v3/TaskRunsTable.tsx

@@ -55,8 +55,10 @@ import {
   filterableTaskRunStatuses,
   TaskRunStatusCombo,
 } from "./TaskRunStatus";
+import { TaskTriggerSourceIcon } from "./TaskTriggerSource";
 import { useOptimisticLocation } from "~/hooks/useOptimisticLocation";
 import { useSearchParams } from "~/hooks/useSearchParam";
+import type { TaskTriggerSource } from "@trigger.dev/database";
 
 type RunsTableProps = {
   total: number;
@@ -352,6 +354,10 @@ export function TaskRunsTable({
                 </TableCell>
                 <TableCell to={path}>
                   <span className="flex items-center gap-x-1">
+                    <TaskTriggerSourceIcon
+                      source={run.taskKind as TaskTriggerSource}
+                      className="size-3.5 flex-none"
+                    />
                     {run.taskIdentifier}
                     {run.rootTaskRunId === null ? <Badge variant="extra-small">Root</Badge> : null}
                   </span>

apps/webapp/app/components/runs/v3/TaskTriggerSource.tsx

@@ -1,4 +1,4 @@
-import { ClockIcon } from "@heroicons/react/20/solid";
+import { ClockIcon, CpuChipIcon } from "@heroicons/react/20/solid";
 import type { TaskTriggerSource } from "@trigger.dev/database";
 import { TaskIconSmall } from "~/assets/icons/TaskIcon";
 import { cn } from "~/utils/cn";
@@ -12,13 +12,20 @@ export function TaskTriggerSourceIcon({
 }) {
   switch (source) {
     case "STANDARD": {
-      return <TaskIconSmall className="size-[1.125rem] min-w-[1.125rem] text-tasks" />;
+      return (
+        <TaskIconSmall className={cn("size-[1.125rem] min-w-[1.125rem] text-tasks", className)} />
+      );
     }
     case "SCHEDULED": {
       return (
         <ClockIcon className={cn("size-[1.125rem] min-w-[1.125rem] text-schedules", className)} />
       );
     }
+    case "AGENT": {
+      return (
+        <CpuChipIcon className={cn("size-[1.125rem] min-w-[1.125rem] text-indigo-500", className)} />
+      );
+    }
   }
 }
 
@@ -30,5 +37,8 @@ export function taskTriggerSourceDescription(source: TaskTriggerSource) {
     case "SCHEDULED": {
       return "Scheduled task";
     }
+    case "AGENT": {
+      return "Agent";
+    }
   }
 }