Skip to content

armgit / eve

Public Imported from GitHub
0

The Open Framework for Building Agents

research(eve): channel session reset (#217)

Andrew Barba69aba4f8b130
diff --git a/AGENTS.md b/AGENTS.md
index 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`, which
runs in the CI lint job. If the guard fails, fix the violation rather than
editing 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.
+
## Testing
Tests belong in one of four tiers. Pick the tightest tier that can express the
diff --git a/research/channel-session-reset.md b/research/channel-session-reset.md
new file mode 100644
index 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.mjs
index 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 31
violations.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;