Sesiones

Una session es un canvas scratch-pad de drafting donde el operador elige items upstream, attachea variantes de generación (cada una con su propio preset, prompt, style y — opcionalmente — su propia credencial de LLM), e itera por rounds hasta tener algo que valga la pena exportar.

Las sessions son independientes de los pipelines: cualquier combinación de items de cualquier source puede aterrizar en el mismo canvas. El modelo de session es lo que renderiza la página /sessions/[id] del workbench.

Modelo mental

Cada canvas está scopeado a un único par (organization, user). Items, variantes, rounds y exports se borran en cascada cuando se elimina el canvas.

Entidades

session_canvas

Nivel top. Trackea lastActiveAt para ordenamiento, name (nullable) y timestamps. Indexado por (organizationId, lastActiveAt desc) y (userId).

session_item

Un snapshot inmutable de un item upstream en el momento de la selección. Guarda:

• sourceKind — x / webpage / rss / custom
• externalItemId — nullable, para resolver de vuelta al upstream
• title, snippet, capturedAt
• metrics (engagement data jsonb) y raw (payload original jsonb)

Lo crítico: los cambios upstream no se propagan — el canvas conserva el title y las metrics que capturó al momento de la selección. Si necesitás data fresca, remové el item y agregalo de nuevo.

session_variant

Slot de generación. Contiene:

• presetId — slug built-in (x-thread, blog-with-images, linkedin-long, newsletter-section, tldr-brief, custom) o user-saved
• userPresetId — uuid que apunta a user_preset cuando presetId=user-saved
• prompt, style, typeTag
• status — idle / queued / streaming / done / error
• errorMessage — populado cuando status=error
• activeRoundIndex — base 0; -1 significa "todavía no hay rounds"
• llmCredentialId — nullable; override del LLM default del workspace

variant_round

Historia de generación append-only por variante. Cada row captura:

• output (prosa generada)
• promptSnapshot y styleSnapshot (cómo lucía la variante cuando se generó este round)
• llmProvider, llmModel (el LLM efectivamente usado)
• generatedAt

Seleccionar un round más viejo vía session_select_round no borra los nuevos; solo mueve activeRoundIndex.

user_preset

Tupla (prompt, style, typeTag) guardada por un usuario. Scopeada por (org, user). Los presets built-in no se guardan como rows — viven como slugs estables en el codebase. UNIQUE(organizationId, userId, name) evita duplicados.

session_export

Evento de export registrado: (sessionId, variantId, roundId?, format). Hoy el format es solo markdown. El row alimenta el KPI EXPORTS 7D en /console.

session_activity

Log append-only de eventos que afectan a la session:

• client — ui / claude-code / cursor / claude-desktop / cline / other-mcp
• tool — nombre con dots (ej. session.add_variant, ui:expand)
• detail — contexto legible

Alimenta el NowFeed de /console. Útil para lecturas tipo "¿qué estaba haciendo esta session?" — tanto para humanos como para agentes.

Lifecycle

1. Create — session_create({ name? }) devuelve un canvas. Sin items, sin variantes. name opcional (se puede setear después).
2. Select items — session_add_item snapshottea un X post / webpage / entrada RSS upstream. Pasá un upstreamItemId para resolver desde el registry de sources del workbench, o pasá directamente los campos del snapshot (title, snippet, capturedAt, metrics, raw).
3. Attach variants — session_add_variant({ sessionId, presetId, prompt, style, typeTag, llmCredentialId? }). Las variantes arrancan con status=idle.
4. Generate — session_generate_variant({ variantId, sessionId }) encola una call al LLM. Cada call appendea un variant_round. session_generate_all({ sessionId }) hace fanout a todas las variantes del canvas.
5. Compare rounds — session_select_round({ variantId, roundIndex }) cambia el round visible; el resto queda en la historia. session_variant_rounds({ variantId }) lista la historia completa.
6. Export — session_export_variant({ sessionId, variantId, roundId?, format }) escribe un row session_export (loguea para el KPI EXPORTS 7D). El render real de markdown lo hace el caller (la UI usa el route de export; los agentes loguean vía MCP).
7. Save preset (opcional) — session_save_preset({ name, description, prompt, style, typeTag }) persiste la config de una variante como user preset reutilizable.
8. Delete — session_delete({ sessionId }) borra en cascada items, variantes, rounds y exports. Irreversible.

Superficie de API

MCP

Las 18 tools viven en apps/web/lib/mcp/tools/sessions.ts. Ver la referencia de tools MCP para las signatures completas.

Grupo	Tools
Lifecycle	session_create, session_list, session_get, session_update, session_delete
Selection	session_add_item, session_remove_item, session_clear_selection
Variants	session_add_variant, session_update_variant, session_remove_variant, session_select_round, session_generate_variant, session_generate_all, session_variant_rounds
Exports + presets	session_export_variant, session_save_preset
Sources	session_list_sources

Web (workbench + facade)

Método	Path	Para qué
GET	/api/sessions/activity	Últimas entradas de activity en las sessions de la org. Alimenta el NowFeed de /console. Param ?limit (1–100, default 20).
POST	/api/sessions/:sessionId/items	Bridge server-side que espeja session_add_item para callers in-app que prefieren REST.
POST	/api/sessions/:sessionId/variants/:variantId/regenerate	Dispara regeneración de una variante (una call al LLM que produce un round nuevo).
POST	/api/sessions/sources/:id/refresh	Refrescar una source upstream de manera async (arranca un job de scrape).

El resto del CRUD de sessions ocurre vía transport MCP (/api/mcp) o directamente en la UI a través de server actions en apps/web/lib/session/.

Lo que las sessions NO son

• No son un pipeline — las sessions no ingieren con un schedule. Agregar un item es una captura one-shot.
• No son un destino persistente — los exports son eventos, no output guardado. El workbench no conserva archivos markdown (todavía); el caller es responsable de tomar el texto del round y hacer algo con él.
• No son una cadena de refinements — las sessions conviven con el modelo de refinement (que sigue viviendo sobre artifacts). Un round no es un artifact.
• No son compartidas — cada canvas está scopeado a (org, user); los teammates no ven los canvas de otros. Las superficies cross-user (dashboards, pipelines) son separadas.

Ver también

• Conceptos — modelo de alto nivel que ubica a las sessions junto a los pipelines.
• MCP tools · sessions — signatures completas de las tools.
• Glosario — términos en una sola tabla.