The Open Framework for Building Agents
research(eve): channel session reset (#217)
Andrew Barba69aba4f8b130
diff --git a/AGENTS.md b/AGENTS.mdindex 1c44cff17..c917d073d 100644--- a/AGENTS.md+++ b/AGENTS.md@@ -22,6 +22,7 @@ docs, prompts, comments, and headings.- `apps/frameworks`, `apps/templates`, `apps/docs` — framework integrations, templates, docs site- `docs` — published documentation content- `e2e/` — fixture-owned `eve eval` end-to-end tests+- `research` — issue-backed implementation plans for proposed changes## Git workflow@@ -97,6 +98,16 @@ Machine-checkable invariants are enforced by `pnpm guard:invariants`, whichruns in the CI lint job. If the guard fails, fix the violation rather thanediting the baseline — baselines may only shrink.+## Research plans++Research documents live in the top-level `research/` directory and require+`issue`, `status`, and `last_updated` frontmatter. Keep plans concise and focus+primarily on the proposed authoring API and externally observable semantics.+Include only the architecture needed to explain boundaries, data flow, and+invariants; avoid speculative implementation detail, repeated rationale, and+exhaustive task inventories. Use a compact diagram when it makes a lifecycle+or ownership relationship materially clearer.+## TestingTests belong in one of four tiers. Pick the tightest tier that can express thediff --git a/research/channel-session-reset.md b/research/channel-session-reset.mdnew file mode 100644index 000000000..f124f5caf--- /dev/null+++ b/research/channel-session-reset.md@@ -0,0 +1,227 @@+---+issue: https://github.com/vercel/eve/issues/216+last_updated: "2026-06-23"+status: proposed+---++# Channel session reset and scoped cancellation++## Summary++Telegram private chats and Twilio conversations reuse a stable continuation identity, so one durable+session can accumulate history and state forever. eve should recognize `/new` on those channels and+terminate the current session before the identity is reused.++Cancellation has two explicit scopes:++- **turn:** stop the active turn and its descendants; keep the entry session resumable;+- **session:** stop the entry session and its complete execution tree; the next message starts with+ empty history and authored state.++Slash commands are one consumer of a general cancellation API. The same semantics must be available+to the eve HTTP channel, TypeScript client, custom channels, higher-level channel handlers, session+callbacks, and evals.++## Authoring API++### eve HTTP channel++Expose one authenticated route:++`POST /eve/v1/session/:sessionId/cancel`++The body is a strict union with no default scope:++```json+{ "scope": "turn", "cancelToken": "<active-turn capability>" }+```++```json+{ "scope": "session", "continuationToken": "<current session capability>" }+```++The route authenticates first, then verifies that the capability belongs to `:sessionId`. Invalid+bodies return `400`; stale or mismatched capabilities return a non-disclosing `409`; accepted+cancellation returns `202`.++Every request that starts a turn returns a fresh `cancelToken` alongside `sessionId` and the current+`continuationToken`. A cancel token is valid only for that active turn. It cannot cancel the entry+session or a later turn.++### TypeScript client++- `MessageResponse.cancel()` cancels the turn represented by that response.+- `ClientSession.cancel()` cancels the current entry session.+- Both use the client's normal auth, headers, redirects, and error handling.+- Session cancellation clears the client's resumable cursor so a later send cannot accidentally+ target the cancelled entry.+- Aborting a request or stream with `AbortSignal` remains local transport cancellation; it does not+ request server-side cancellation.++### Channel authors++Custom `defineChannel` route handlers receive separate operations to:++- cancel a turn using its session id and turn cancel token;+- cancel a session using its channel-local continuation token;+- restart a session with replacement input after the old session releases its identity.++The operations own token namespacing and ordering. Authors do not call workflow APIs or manually+compose “cancel, then hope delivery starts fresh.”++Higher-level channel handlers can return a `reset-session` decision with auth, optional context, and+optional replacement content. This lets a Slack mention or direct-message handler request the same+behavior without receiving low-level route operations.++In-session callbacks and event subscribers use an explicit cancellation operation with a required+`turn` or `session` scope. Requesting cancellation exits normal authored execution; code after the+request must not continue.++### Evals++Evals expose first-class controls for cancelling an active turn and its entry session. An eval can+retain a cancellable handle while work is active, request cancellation, and continue observing the+resulting event boundary. Expected cancellation is assertable behavior, not an automatic eval+failure.++Eval cancellation uses the TypeScript client and public channel APIs. It must work for sessions+created by custom channels as well as the built-in eve channel.++## Semantics++### Turn cancellation++The cancel token is minted per turn and bound to `(sessionId, turnId)`.++```text+TURN START++ClientSession.send()+`-- POST message+ `-- eve channel / runtime+ |-- resume entry session S1 through continuation C1+ |-- start turn T7+ |-- bind cancel token K7 -> (S1, T7)+ `-- return { sessionId: S1, continuationToken: C1, cancelToken: K7 }+ `-- MessageResponse stores K7++TURN CANCEL++MessageResponse.cancel()+`-- POST /eve/v1/session/S1/cancel+ `-- { scope: "turn", cancelToken: K7 }+ `-- eve channel / runtime+ |-- authenticate the request+ |-- resolve K7 -> (S1, T7)+ |-- verify the URL session is S1+ |-- durably accept cancellation and return 202+ |-- cancel T7 and its descendants+ |-- retire K7 when T7 settles+ `-- keep C1 -> S1 and emit session.waiting+```++When T7 completes, fails, or is cancelled, K7 becomes stale. The next turn receives a new token K8.+K7 can never cancel K8 or session S1.++### Session cancellation++Session cancellation binds the current continuation token to the session id in the request. The+runtime releases the continuation before tearing down the tree; that release is the reset+linearization point.++```text+SESSION CANCEL++ClientSession.cancel() or authenticated /new handler+`-- request session cancellation for (S1, C1)+ `-- channel / runtime+ |-- verify C1 currently belongs to S1+ |-- mark S1 as closing+ |-- release C1 from S1 [reset linearization point]+ |-- acknowledge accepted cancellation+ |-- cancel the complete S1 tree+ | `-- active turn+ | |-- model and tools+ | `-- local and remote delegates+ |-- wait for every branch to settle+ `-- emit session.cancelled and close S1++IDENTITY REUSE++Stable Telegram / Twilio identity R+`-- channel continuation C1+ |-- before reset: C1 -> S1+ |-- after release: C1 -> no active session+ `-- next message: C1 -> new session S2 with empty history and state++Old cleanup remains bound to S1.+`-- a stale request naming S1 cannot cancel S2, even though S2 reuses C1+```++For bare `/new`, the flow ends after S1 is cancelled. For `/new <message>` or `/new` with an+attachment, restart waits for the release barrier and creates S2 with that replacement content.++### Runtime guarantees++- Cancellation follows ownership from entry session → turn → tools and delegated agents, including+ remote descendants.+- A cancelling session cannot accept input, launch work, or reclaim its continuation.+- Cooperative abort reaches models, tools, sandboxes, and delegates; the runtime remains responsible+ for terminating work that does not cooperate.+- Late descendant results cannot resume a cancelled ancestor or mutate a replacement session.+- Turn cancellation ends at `session.waiting`; session cancellation ends at `session.cancelled`.+- Cancellation is intentional control flow and does not trigger generic user-facing failure output.+- Completed external side effects remain recorded and are not rolled back.++## `/new` behavior++Telegram and Twilio expose:++```ts+resetCommands?: false | readonly string[];+```++- omitted: `['new']`;+- `false`: disabled;+- array: replace the default names.++Inbound handling verifies the provider request and runs authored gating/auth before matching the+command. A `null` authored result drops the input without cancellation.++- Bare `/new` silently cancels the session and creates no empty workflow.+- `/new <message>` starts a fresh session with the stripped message.+- Telegram attachments on `/new` belong to the fresh session.+- `/new@botname` matches only the configured Telegram bot.+- Prefixes such as `/newspaper`, unknown commands, and disabled commands remain normal model input.+- The command itself is never added to history and successful reset sends no confirmation.+- Slack has no default reset command; authors opt in through their inbound handler.++## Delivery and verification++Implementation must cover the HTTP contract, cancellation outcomes and events, ownership-tree+propagation, TypeScript client, eval driver, custom-channel operations, Telegram and Twilio `/new`,+docs, and a patch changeset.++Add a new `e2e/fixtures/agent-cancellation` fixture. Its custom `defineChannel` must use only public+channel APIs—no runtime/workflow imports and no proxy through the built-in eve cancellation route.+The fixture includes independent evals for:++- **turn cancellation:** cancel active work, observe the turn boundary and `session.waiting`, then+ prove a follow-up resumes the same session and context;+- **session cancellation:** cancel active work, observe `session.cancelled`, reuse the same channel+ identity, then prove the new session id, history, and authored state are fresh.++The evals use the new eval cancellation controls, assert events and identities directly, work+locally and against deployed targets, and require no external service beyond model credentials.++Also cover malformed/scoped HTTP requests, auth before capability inspection, stale tokens, command+parsing, attachments, duplicate cancellation, delivery/completion races, nested local and remote+delegates, client cursor updates, and the distinction between `AbortSignal` and server cancellation.++Run the repository's required unit, integration, scenario, typecheck, lint, format, invariant, docs,+and build checks, plus:++```sh+cd e2e/fixtures/agent-cancellation+pnpm exec eve eval --strict+```diff --git a/scripts/guard-invariants.mjs b/scripts/guard-invariants.mjsindex 17d0f5ffb..1804136df 100644--- a/scripts/guard-invariants.mjs+++ b/scripts/guard-invariants.mjs@@ -72,6 +72,11 @@* for project creation and the dedicated current commands* (`eve link`, `eve channels add`, `eve deploy`) afterward.* Changelogs and changesets are historical records and excluded.+ * rule 32 — Every Markdown file under `research/` must have valid YAML+ * frontmatter with non-empty `issue` and `status` fields plus an+ * ISO `last_updated` date. Research documents are implementation+ * plans attached to tracked GitHub work, not an unowned parallel+ * backlog.** Baselines for rules with pre-existing violations live in* `guard-invariants-baseline.json`. Counts and allowlists in that file@@ -665,6 +670,88 @@ async function checkRule31RemovedCliReferences() {return violations;}+// ---------- Rule 32: research document frontmatter ----------++const RESEARCH_DIR = "research";+const RESEARCH_LAST_UPDATED_RE = /^\d{4}-\d{2}-\d{2}$/;++/**+ * @returns {Promise<Violation[]>}+ */+async function checkRule32ResearchFrontmatter() {+ /** @type {Violation[]} */+ const violations = [];+ const researchRoot = join(REPO_ROOT, RESEARCH_DIR);++ try {+ await readdir(researchRoot);+ } catch (error) {+ if (error && typeof error === "object" && "code" in error && error.code === "ENOENT") {+ return violations;+ }+ throw error;+ }++ for await (const { absPath, relPath } of walkFiles(researchRoot)) {+ const posix = toPosix(relPath);+ if (!posix.endsWith(".md")) continue;++ const content = await readFile(absPath, "utf8");+ if (!matter.test(content)) {+ violations.push({+ rule: 32,+ file: posix,+ message:+ "research documents must start with YAML frontmatter containing `issue`, `status`, and `last_updated` fields.",+ });+ continue;+ }++ let data;+ try {+ data = matter(content).data;+ } catch (error) {+ violations.push({+ rule: 32,+ file: posix,+ message: `research frontmatter must be valid YAML: ${error instanceof Error ? error.message : String(error)}`,+ });+ continue;+ }++ if (data === null || typeof data !== "object" || Array.isArray(data)) {+ violations.push({+ rule: 32,+ file: posix,+ message: "research frontmatter must parse to an object.",+ });+ continue;+ }++ for (const field of ["issue", "status"]) {+ if (typeof data[field] === "string" && data[field].trim().length > 0) continue;+ violations.push({+ rule: 32,+ file: posix,+ message: `research frontmatter must set \`${field}\` to a non-empty string.`,+ });+ }++ if (+ typeof data.last_updated !== "string" ||+ !RESEARCH_LAST_UPDATED_RE.test(data.last_updated)+ ) {+ violations.push({+ rule: 32,+ file: posix,+ message: "research frontmatter must set `last_updated` to a quoted `YYYY-MM-DD` string.",+ });+ }+ }++ return violations;+}+/*** @returns {Promise<Set<string>>}*/@@ -920,6 +1007,9 @@ async function main() {// Rule 31violations.push(...(await checkRule31RemovedCliReferences()));+ // Rule 32+ violations.push(...(await checkRule32ResearchFrontmatter()));+if (violations.length === 0) {process.stdout.write("[eve:guard:invariants] ok — all mechanical lints passed.\n");return;