Merge remote-tracking branch 'origin/main' into feat(webapp)-schedules-UI-improvement

samejr · samejr · commit a295a8bfec62 · 2026-06-16T13:45:59.000+01:00
# Conflicts:
#	apps/webapp/app/components/BlankStatePanels.tsx
#	apps/webapp/app/routes/_app.orgs.$organizationSlug.projects.$projectParam.env.$envParam.sessions._index/route.tsx
diff --git a/.server-changes/prevent-db-seed-script-hang.md b/.server-changes/prevent-db-seed-script-hang.md
@@ -0,0 +1,6 @@
+---
+area: webapp
+type: fix
+---
+
+Exit db:seed script on success to prevent hanging.
diff --git a/apps/webapp/app/components/BlankStatePanels.tsx b/apps/webapp/app/components/BlankStatePanels.tsx
@@ -207,14 +207,17 @@ export function SessionsNone() {
       }
     >
       <Paragraph spacing variant="small">
-        A session is a stateful execution of an agent. It includes two-way streaming and durable
-        compute. A session can have multiple “Runs” associated with it.
+        A session is a stateful execution of an agent, with two-way streaming and durable
+        compute. A single session can have multiple runs associated with it, so one conversation
+        can span many task triggers. The input stream carries incoming user messages, and the
+        output stream carries everything the agent produces, including AI generation parts (text,
+        reasoning, tool calls, etc.) and any custom data parts your task emits.
       </Paragraph>
       <Paragraph spacing variant="small">
         The easiest way to create one is to trigger a <InlineCode>chat.agent</InlineCode> task,
         which is built on sessions and handles the chat turn loop for you. You can also call{" "}
-        <InlineCode>sessions.start()</InlineCode> directly for non-chat patterns like agent inboxes,
-        approval flows, or server-to-server streaming.
+        <InlineCode>sessions.start()</InlineCode> directly for non-chat patterns like agent
+        inboxes, approval flows, or server-to-server streaming.
       </Paragraph>
     </InfoPanel>
   );
diff --git a/apps/webapp/app/routes/_app.orgs.$organizationSlug.projects.$projectParam.env.$envParam.sessions._index/route.tsx b/apps/webapp/app/routes/_app.orgs.$organizationSlug.projects.$projectParam.env.$envParam.sessions._index/route.tsx
@@ -129,7 +129,12 @@ function SessionsHelpTooltip() {
           <div>
             <Paragraph variant="small/bright">What is a session?</Paragraph>
             <Paragraph variant="small" className="mt-1">
-            A session is a stateful execution of an agent. It includes two-way streaming and durable compute. A session can have multiple “Runs” associated with it.
+              A session is a stateful execution of an agent, with two-way streaming and durable
+              compute. A single session can have multiple runs associated with it, so one
+              conversation can span many task triggers. The input stream carries incoming user
+              messages, and the output stream carries everything the agent produces, including AI
+              generation parts (text, reasoning, tool calls, etc.) and any custom data parts your
+              task emits.
             </Paragraph>
           </div>
           <div className="flex flex-col gap-2.5 border-t border-grid-dimmed pt-3">
diff --git a/apps/webapp/seed.mts b/apps/webapp/seed.mts
@@ -168,6 +168,7 @@ seed()
   })
   .finally(async () => {
     await prisma.$disconnect();
+    process.exit(0);
   });
 
 async function findOrCreateOrganization(
diff --git a/docs/ai-chat/how-it-works.mdx b/docs/ai-chat/how-it-works.mdx
@@ -14,9 +14,9 @@ This page explains how `chat.agent` is put together, what each piece does on a s
 **What you don't have to think about**: SSE reconnects, WebSocket backpressure, container cold starts, whether a worker is currently running, or how to re-deliver chunks the client missed during a reload. The platform handles those. **What you do have to think about**: idempotency in your `run()` function, and how much state you keep in memory between turns versus persist in your own database.
 </Note>
 
-## The primary noun: a chat session is a pair of streams and a task
+## The primary noun: the chat session
 
-A **chat session** is the unit chat.agent owns. It is three things bound together:
+A **chat session** is a stateful execution of an agent: two-way streaming plus durable compute, able to span multiple runs. It is the unit chat.agent owns, and it is three things bound together:
 
 - An **inbox** channel called `.in` — every user message lands here as a record.
 - An **outbox** channel called `.out` — every assistant chunk leaves through here.
diff --git a/docs/ai-chat/sessions.mdx b/docs/ai-chat/sessions.mdx
@@ -1,16 +1,18 @@
 ---
 title: "Sessions"
 sidebarTitle: "Sessions"
-description: "A Session is a pair of durable streams — input carries your users' messages to the agent, output carries everything the agent produces back — plus orchestration of the runs that process them."
+description: "A Session is a stateful execution of an agent, with two-way streaming and durable compute. A single Session can have multiple runs associated with it."
 ---
 
 import RcBanner from "/snippets/ai-chat-rc-banner.mdx";
 
 <RcBanner />
 
-**A Session is a pair of durable streams.** The input stream (`.in`) carries incoming user messages to your task. The output stream (`.out`) carries everything the agent produces back to your clients: AI generation parts (text, reasoning, tool calls) and any custom data parts you write.
+**A Session is a stateful execution of an agent.** It includes two-way streaming and durable compute, and a single Session can have multiple runs associated with it.
 
-Sessions also **orchestrate the runs that process those streams**. A Session is keyed on your stable id (`externalId` — for chat, the `chatId`) and owns its current run: when a run suspends, idles out, or hands off to a new version, the Session starts or swaps to a fresh run and the streams carry on. Clients keep sending and reading against the same id; they never know a run changed underneath.
+The **two-way streaming** is a pair of durable streams. The input stream (`.in`) carries incoming user messages to your task. The output stream (`.out`) carries everything the agent produces back to your clients: AI generation parts (text, reasoning, tool calls) and any custom data parts you write.
+
+The **durable compute** is the runs that process those streams. A Session is keyed on your stable id (`externalId` — for chat, the `chatId`) and owns its current run: when a run suspends, idles out, or hands off to a new version, the Session starts or swaps to a fresh run and the streams carry on. Clients keep sending and reading against the same id; they never know a run changed underneath.
 
 ```mermaid
 flowchart LR
diff --git a/docs/troubleshooting.mdx b/docs/troubleshooting.mdx
@@ -53,6 +53,10 @@ If you see "Connection error" when running `trigger login` (or "Failed to create
 2. **VPN or firewall:** Disconnect from VPN or check firewall/proxy; try `npx trigger.dev@latest login --log-level debug` for more detail.
 3. **TLS / certificate store:** Node may use a different CA store than your OS (e.g. `curl` works but the CLI fails). Try `export NODE_EXTRA_CA_CERTS=/etc/ssl/cert.pem` (macOS/Linux) then login again, or reinstall Node so it gets updated certs. Behind a corporate proxy or custom CA? Set `NODE_EXTRA_CA_CERTS` to that CA file.
 
+### Runs never dequeue in dev
+
+If runs sit in the queue and never start while running `trigger.dev dev`, check whether you have more than one local instance running against the same project. Each project has a single dev environment, and only one `trigger.dev dev` instance can consume from it at a time, so a second instance causes runs to be split between them and some appear stuck. Keep a single `trigger.dev dev` running per project. [Upvote isolated dev sessions](https://triggerdev.featurebase.app/p/isolated-dev-sessions-for-multiple-local-trigger-dev-instances) if you need to run multiple local instances.
+
 ## Deployment
 
 Running the [trigger.dev deploy] command builds and deploys your code. Sometimes there can be issues building your code.
diff --git a/package.json b/package.json
@@ -123,7 +123,11 @@
       "semver@>=5 <5.7.2": "^5.7.2",
       "defu@>=6 <6.1.5": "^6.1.5",
       "fast-uri@<3.1.2": "^3.1.2",
-      "fast-xml-builder@<1.1.7": "^1.1.7"
+      "js-cookie@<3.0.8": "3.0.8",
+      "tmp@<0.2.7": "0.2.7",
+      "brace-expansion@<1.1.13": "1.1.13",
+      "brace-expansion@>=2 <2.0.3": "2.0.3",
+      "brace-expansion@>=5 <5.0.6": "5.0.6"
     },
     "onlyBuiltDependencies": [
       "@depot/cli",
diff --git a/packages/plugins/package.json b/packages/plugins/package.json
@@ -14,7 +14,8 @@
     "dist"
   ],
   "dependencies": {
-    "@trigger.dev/core": "workspace:*"
+    "@trigger.dev/core": "workspace:*",
+    "neverthrow": "^8.2.0"
   },
   "scripts": {
     "clean": "rimraf dist .turbo",
diff --git a/packages/plugins/src/index.ts b/packages/plugins/src/index.ts
@@ -18,3 +18,26 @@ export type {
 } from "./rbac.js";
 
 export { buildJwtAbility } from "./rbac.js";
+
+export type {
+  SsoPlugin,
+  SsoController,
+  OrgSsoStatus,
+  SsoRouteDecision,
+  SsoFlow,
+  SsoProfile,
+  SsoConnectionState,
+  SsoDomainState,
+  SsoDomainStatus,
+  SsoResolutionDecision,
+  SsoDecisionError,
+  SsoBeginError,
+  SsoCompleteError,
+  SsoMutationError,
+  SsoPortalError,
+  SsoValidateError,
+  SsoWebhookError,
+  SsoWebhookEvent,
+} from "./sso.js";
+
+export { SSO_FLOWS } from "./sso.js";
diff --git a/packages/plugins/src/sso.ts b/packages/plugins/src/sso.ts
@@ -0,0 +1,230 @@
+import type { ResultAsync } from "neverthrow";
+
+// === Domain types ===
+
+export type SsoConnectionState = "active" | "inactive";
+
+export type SsoDomainState = "pending" | "verified" | "failed";
+
+export type SsoDomainStatus = {
+  domain: string;
+  verified: boolean;
+  state: SsoDomainState;
+  // Vendor-supplied reason code present when state === "failed".
+  // Plugin keeps it opaque; the host UI surfaces it to the admin so
+  // they know which knob to turn before retrying verification.
+  verificationFailedReason: string | null;
+};
+
+export type OrgSsoStatus = {
+  hasIdpOrg: boolean;
+  enforced: boolean;
+  jitProvisioningEnabled: boolean;
+  jitDefaultRoleId: string | null;
+  idpOrgId: string | null;
+  primaryConnectionId: string | null;
+  domains: ReadonlyArray<SsoDomainStatus>;
+  connections: ReadonlyArray<{
+    id: string;
+    name: string | null;
+    connectionType: string;
+    state: SsoConnectionState;
+  }>;
+};
+
+export type SsoRouteDecision =
+  | { kind: "no_sso" }
+  | { kind: "sso_required"; idpOrgId: string };
+
+export const SSO_FLOWS = [
+  "user_initiated",
+  "auto_discovery_magic",
+  "auto_discovery_oauth",
+  "auto_discovery_vercel",
+  "idp_initiated",
+] as const;
+
+export type SsoFlow = (typeof SSO_FLOWS)[number];
+
+export type SsoProfile = {
+  // Lowercase-normalized at the plugin / host boundary.
+  email: string;
+  firstName: string | null;
+  lastName: string | null;
+  idpSubjectId: string;
+  idpOrgId: string;
+  idpConnectionId: string;
+};
+
+export type SsoResolutionDecision =
+  | { kind: "existing_user_by_idp"; userId: string }
+  | { kind: "linked_by_email"; userId: string }
+  | { kind: "create_new_user"; profile: SsoProfile };
+
+// === Errors ===
+
+export type SsoDecisionError = "internal";
+
+export type SsoBeginError =
+  | "no_org_for_domain"
+  | "no_active_connection"
+  | "feature_disabled";
+
+export type SsoCompleteError =
+  | "state_replayed_or_expired"
+  | "state_invalid_signature"
+  | "code_exchange_failed"
+  | "org_mismatch"
+  | "email_mismatch"
+  | "connection_unknown";
+
+export type SsoMutationError = "feature_disabled" | "rbac_role_invalid" | "internal";
+
+// Vendor-neutral name for "the identity-provider organisation isn't available".
+export type SsoPortalError = "idp_org_unavailable" | "internal";
+
+// The only failure a session re-validation can report is "internal" —
+// callers MUST treat it as fail-open (keep the session). An invalid
+// session is NOT an error: it's a successful result of `{ valid: false }`.
+export type SsoValidateError = "internal";
+
+// Inbound webhook handling. `invalid_signature` → reject (4xx, no retry);
+// `feature_disabled` → no plugin installed (host returns 404); `internal`
+// → transient, the host returns 5xx so the provider retries.
+export type SsoWebhookError = "invalid_signature" | "feature_disabled" | "internal";
+
+// A verified, JSON-serializable inbound event. Vendor-neutral envelope —
+// `event` is the provider's event-type string, `data` its opaque payload.
+export type SsoWebhookEvent = { id: string; event: string; data: unknown };
+
+// === Controller ===
+
+export interface SsoController {
+  // True when a real SSO plugin is loaded. Hosts gate behaviour that's
+  // only meaningful when the plugin is present (e.g. rendering the
+  // settings tab, registering the SSO strategy actively).
+  isUsingPlugin(): Promise<boolean>;
+
+  // --- Provisioning + admin UI ---
+
+  getStatus(organizationId: string): ResultAsync<OrgSsoStatus, SsoDecisionError>;
+
+  // Returns an admin-portal link the customer's IT admin uses to
+  // configure their identity provider. First call also performs any lazy
+  // initialization the plugin needs (no separate enable() method).
+  generatePortalLink(params: {
+    organizationId: string;
+    userId: string;
+    intent: "sso" | "domain_verification";
+    returnUrl: string;
+  }): ResultAsync<{ url: string }, SsoPortalError>;
+
+  setEnforced(params: {
+    organizationId: string;
+    enforced: boolean;
+  }): ResultAsync<void, SsoMutationError>;
+
+  setJitProvisioningEnabled(params: {
+    organizationId: string;
+    enabled: boolean;
+  }): ResultAsync<void, SsoMutationError>;
+
+  setJitDefaultRole(params: {
+    organizationId: string;
+    roleId: string | null;
+  }): ResultAsync<void, SsoMutationError>;
+
+  // --- Auth flow ---
+
+  // Called by every login entry point BEFORE the strategy proceeds.
+  // Composite gate (plan tier + feature flags + config + enforced) is
+  // implemented here. Fail-open: returns no_sso on internal error so a
+  // plugin outage doesn't lock users out.
+  decideRouteForEmail(email: string): ResultAsync<SsoRouteDecision, SsoDecisionError>;
+
+  // Returns the URL the user should be redirected to in order to
+  // authenticate with their identity provider. Internally mints a
+  // single-use signed state token; the implementation is opaque to
+  // OSS callers. Email is lowercase-normalized before lookup.
+  beginAuthorization(params: {
+    email: string;
+    redirectTo: string;
+    flow: SsoFlow;
+  }): ResultAsync<{ url: string }, SsoBeginError>;
+
+  // SP-initiated callback. Verifies and consumes the signed state token
+  // single-use, exchanges the code with the SSO provider, cross-checks
+  // the returned profile against the state claims. Returns profile +
+  // state-carried redirectTo + flow.
+  completeAuthorization(params: {
+    code: string;
+    state: string;
+  }): ResultAsync<{ profile: SsoProfile; redirectTo: string; flow: SsoFlow }, SsoCompleteError>;
+
+  // IdP-initiated callback (no state). Validates the returned connection
+  // identifier is one of ours. Default redirectTo is "/".
+  completeIdpInitiatedAuthorization(params: {
+    code: string;
+  }): ResultAsync<{ profile: SsoProfile; redirectTo: string }, SsoCompleteError>;
+
+  // Re-validate a live SSO session against the IdP. Called periodically
+  // (throttled by the host) for sessions that were established via SSO.
+  // The available signal is whether the user's identity-provider
+  // connection is still active, so `valid` reflects that. Returns an
+  // `internal` error on any infrastructure failure (e.g. the identity
+  // provider is unreachable) — the host MUST fail-open on the error and
+  // only invalidate the session on an explicit `{ valid: false }`.
+  validateSession(params: {
+    userId: string;
+    idpOrgId: string;
+    connectionId: string;
+  }): ResultAsync<{ valid: boolean }, SsoValidateError>;
+
+  // Look up an existing identity by IdP subject, or by lowercased email.
+  // Returns a decision the OSS callback handler uses to drive
+  // User/OrgMember writes. The plugin DOES NOT write to OSS public.*
+  // tables — those writes are the host's responsibility.
+  resolveSsoIdentity(params: {
+    profile: SsoProfile;
+  }): ResultAsync<SsoResolutionDecision, SsoMutationError>;
+
+  // After the host has created/found the User row, the plugin attaches
+  // the IdP identity row in its own storage.
+  attachSsoIdentity(params: {
+    userId: string;
+    profile: SsoProfile;
+  }): ResultAsync<void, SsoMutationError>;
+
+  // Returns whether JIT should provision a membership for the given
+  // (userId, idpOrgId), and the resolved roleId to assign (the org's
+  // JIT default role, or null when no RBAC plugin is installed).
+  // The host performs the actual OrgMember insert.
+  evaluateJit(params: {
+    userId: string;
+    idpOrgId: string;
+  }): ResultAsync<
+    { shouldProvision: boolean; organizationId: string; roleId: string | null },
+    SsoMutationError
+  >;
+
+  // --- Inbound webhooks ---
+
+  // Verify the signature of a raw inbound webhook request and return the
+  // parsed, JSON-serializable event. The host forwards the raw body +
+  // headers from a thin proxy route; the plugin owns the vendor-specific
+  // signature scheme. The host enqueues the returned event for async
+  // processing (it never enqueues an unverified request).
+  verifyWebhook(params: {
+    rawBody: string;
+    headers: Record<string, string>;
+  }): ResultAsync<{ event: SsoWebhookEvent }, SsoWebhookError>;
+
+  // Process a previously-verified webhook event (the host's background
+  // worker calls this). Performs the plugin's own state writes; throws
+  // nothing — failures surface as `internal` so the worker retries.
+  processWebhookEvent(event: SsoWebhookEvent): ResultAsync<void, SsoWebhookError>;
+}
+
+export interface SsoPlugin {
+  create(): SsoController | Promise<SsoController>;
+}
diff --git a/packages/trigger-sdk/src/v3/sessions.ts b/packages/trigger-sdk/src/v3/sessions.ts
@@ -86,8 +86,9 @@ export function __setSessionStartImplForTests(impl: SessionStartImpl | undefined
 }
 
 /**
- * Start a {@link Session} — a durable, task-bound, bidirectional I/O
- * primitive. The server creates the row (idempotent on `externalId`)
+ * Start a {@link Session} — a stateful execution of an agent, with
+ * two-way streaming and durable compute, that can span multiple runs.
+ * The server creates the row (idempotent on `externalId`)
  * and triggers the first run from `triggerConfig` in one round-trip.
  * Returns the new run's id and a session-scoped public access token
  * for browser-side use against `.in/append`, `.out` SSE, and
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
diff --git a/scripts/enhance-release-pr.mjs b/scripts/enhance-release-pr.mjs
