Skip to content

Commit 79527c7

Browse files
committed
docs: use one canonical definition of a Session everywhere
Adopt a single description of a Session wherever one is shown to users: "A session is a stateful execution of an agent. It includes two-way streaming and durable compute, and can have multiple runs associated with it." Applies to the Sessions concept doc, the how-it-works overview, the dashboard sessions blank state and help tooltip, and the sessions.start() JSDoc. Behavior copy, code comments, and changelogs are unchanged.
1 parent 3b91999 commit 79527c7

5 files changed

Lines changed: 21 additions & 15 deletions

File tree

apps/webapp/app/components/BlankStatePanels.tsx

Lines changed: 5 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -207,10 +207,11 @@ export function SessionsNone() {
207207
}
208208
>
209209
<Paragraph spacing variant="small">
210-
A session is a pair of streams: input for incoming user messages, and output for
211-
everything the agent produces, including AI generation parts (text, reasoning, tool
212-
calls, etc.) and any custom data parts your task emits. Sessions also orchestrate the
213-
execution of agent runs, so a single conversation can span many task triggers.
210+
A session is a stateful execution of an agent, with two-way streaming and durable
211+
compute. A single session can have multiple runs associated with it, so one conversation
212+
can span many task triggers. The input stream carries incoming user messages, and the
213+
output stream carries everything the agent produces, including AI generation parts (text,
214+
reasoning, tool calls, etc.) and any custom data parts your task emits.
214215
</Paragraph>
215216
<Paragraph spacing variant="small">
216217
The easiest way to create one is to trigger a <InlineCode>chat.agent</InlineCode> task,

apps/webapp/app/routes/_app.orgs.$organizationSlug.projects.$projectParam.env.$envParam.sessions._index/route.tsx

Lines changed: 6 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -129,10 +129,12 @@ function SessionsHelpTooltip() {
129129
<div>
130130
<Paragraph variant="small/bright">What is a session?</Paragraph>
131131
<Paragraph variant="small" className="mt-1">
132-
A session is a pair of streams: input for incoming user messages, and output for
133-
everything the agent produces, including AI generation parts (text, reasoning, tool
134-
calls, etc.) and any custom data parts your task emits. Sessions also orchestrate the
135-
execution of agent runs, so a single conversation can span many task triggers.
132+
A session is a stateful execution of an agent, with two-way streaming and durable
133+
compute. A single session can have multiple runs associated with it, so one
134+
conversation can span many task triggers. The input stream carries incoming user
135+
messages, and the output stream carries everything the agent produces, including AI
136+
generation parts (text, reasoning, tool calls, etc.) and any custom data parts your
137+
task emits.
136138
</Paragraph>
137139
</div>
138140
<div className="flex flex-col gap-2.5 border-t border-grid-dimmed pt-3">

docs/ai-chat/how-it-works.mdx

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -14,9 +14,9 @@ This page explains how `chat.agent` is put together, what each piece does on a s
1414
**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.
1515
</Note>
1616

17-
## The primary noun: a chat session is a pair of streams and a task
17+
## The primary noun: the chat session
1818

19-
A **chat session** is the unit chat.agent owns. It is three things bound together:
19+
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:
2020

2121
- An **inbox** channel called `.in` — every user message lands here as a record.
2222
- An **outbox** channel called `.out` — every assistant chunk leaves through here.

docs/ai-chat/sessions.mdx

Lines changed: 5 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,16 +1,18 @@
11
---
22
title: "Sessions"
33
sidebarTitle: "Sessions"
4-
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."
4+
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."
55
---
66

77
import RcBanner from "/snippets/ai-chat-rc-banner.mdx";
88

99
<RcBanner />
1010

11-
**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.
11+
**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.
1212

13-
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.
13+
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.
14+
15+
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.
1416

1517
```mermaid
1618
flowchart LR

packages/trigger-sdk/src/v3/sessions.ts

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -86,8 +86,9 @@ export function __setSessionStartImplForTests(impl: SessionStartImpl | undefined
8686
}
8787

8888
/**
89-
* Start a {@link Session} — a durable, task-bound, bidirectional I/O
90-
* primitive. The server creates the row (idempotent on `externalId`)
89+
* Start a {@link Session} — a stateful execution of an agent, with
90+
* two-way streaming and durable compute, that can span multiple runs.
91+
* The server creates the row (idempotent on `externalId`)
9192
* and triggers the first run from `triggerConfig` in one round-trip.
9293
* Returns the new run's id and a session-scoped public access token
9394
* for browser-side use against `.in/append`, `.out` SSE, and

0 commit comments

Comments
 (0)