Compuerta automática de sesión en horas punta: modo fin de semana + pausa automática en punta + veredicto bidimensional de fuentes oficiales + congelación a nivel de sesión + reintento automático del backend

English · 中文 · 日本語 · 한국어 · Français · Deutsch · Italiano · Русский · Español

" is not registered`. Habrá que esperar a que el DSH oficial añada los identificadores de configuración regional correspondientes. Los usuarios avanzados pueden mantener un fork de DSH para ampliarlo. > **▼ Compatibilidad de versiones de DSH** > > | Versión de DSH | Carga | Registro de ajustes | Eventos de sesión / compuerta | Mitad cliente | > | --- | --- | --- | --- | --- | > | 0.1.0-rc.7 ~ 0.1.1-rc.x | ➖ fuera de esta línea (versiones históricas anteriores a `legacy/0.1.2`) | `ctx.settings.register(ns, schema, { base })` | ✅ misma forma | ✅ sin importar valores de plataforma | > | 0.1.2-alpha.2+ / 0.1.2-rc.1 | ➖ fuera de esta línea → usar `legacy/0.1.2` (npm `@dsh-0.1.2`) | `register` se mantiene (se añade `installSection`) | ✅ misma forma | ✅ sin importar valores de plataforma | > | **0.2.0-rc.1+** | ✅ (**esta línea**, dist-tag `dsh-0.2.0`, npm `4.0.0`) | declarativo: los campos `.volatile()` del Config los proyecta el host como formularios, `register` eliminado | ✅ eventos leídos por la doble vía `snapshotEvents()` | ✅ tarjeta de ajustes del cliente migrada a `configForms` | > | 0.1.7-rc.1+ | ✅ (rama `compat/0.1.7`, dist-tag `dsh-0.1.7`) | declarativo: los campos `.volatile()` del Config los proyecta el host como formularios, `register` eliminado | ✅ eventos leídos por la doble vía `snapshotEvents()` | ✅ tarjeta de ajustes del cliente migrada a `configForms` | > | 0.1.5-rc.2 | ✅ (rama `compat/0.1.5`, dist-tag `dsh-0.1.5`) | `register` sigue presente (espacios de nombres como cadenas) | ✅ eventos leídos por la doble vía `snapshotEvents()` | ✅ | > > **Identidad de esta línea**: rama `compat/0.2.0`, número de versión npm **`4.0.0`** (semver), dist-tag **`dsh-0.2.0`**. > Los `engines.dsh` de `package.json` y `dsh.plugin.json` y los cuatro pares `@deepseek-ai/dsh-client-*` > se unifican en `0.1.0-rc.2 || 0.1.0-rc.3 || 0.1.0-rc.6 || 0.1.0-rc.7 || 0.1.0-rc.8 || 0.1.1-rc.1 || 0.1.1-rc.2 || 0.1.2-rc.1 || 0.1.5-rc.1 || 0.1.5-rc.2 || 0.1.5-rc.3 || 0.1.7-rc.1 || 0.1.7-rc.2 || 0.2.0-rc.1 || 0.2.0-rc.2 || 0.2.1-rc.1 || 0.2.1-rc.2 || 0.2.1-rc.3 || 0.2.1-rc.4 || 0.2.1-rc.5`; el límite inferior del par `@deepseek-ai/cordis` se alinea con el `^4.0.4` de la línea del host. > Históricamente el README usó «2.x / 3.x» como **apodos de línea**: era una costumbre narrativa, **no números de versión > descargables del registro** — guíate siempre por las versiones npm `0.3.1` (línea 0.1.2), `3.0.0`/`3.0.1` (línea 0.1.5), > `3.2.4` (línea 0.1.7) y `4.0.0` (línea 0.2.0). > > **Adaptación a 0.2.0 (rama compat/0.2.0, npm 4.0.0)**: > la API de plugins que usa este complemento (manifest/settings/HMR/slot/sesión V4) es en 0.2.0-rc.1 totalmente compatible con 0.1.7; > la adaptación es un simple relevo de metadatos (peer/engines/dist-tag/versión 4.0.0). Correcciones de ingeniería alineadas junto con la base: > ① `src/client/family-section.tsx` entra en el control de versiones (antes existía solo en el árbol de trabajo local, un checkout limpio no podía compilar); > ② la configuración de eslint elimina el `no-unused-vars` del núcleo, que marcaba erróneamente parámetros de firmas de tipos TS; la línea base de lint vuelve a estar toda en verde; > ③ las compuertas estáticas de firma de las rutas de escritura v4 (`tests/source-kind.test.mjs`) entran en esta línea junto con la base; > ④ el par `@deepseek-ai/cordis` se alinea con `^4.0.4` (los paquetes de UI del host 0.2.0-rc.1 declaran `~4.0.4`; el anterior `^4.0.1` no entraba en conflicto, pero su límite inferior era demasiado antiguo). > > **Dónde quedan las otras líneas**: para hosts DSH `0.1.2-rc.x` usa la rama **`legacy/0.1.2`** (dist-tag npm > `dsh-0.1.2`, versión `0.3.1`). **`main` está congelado en `0.2.0-beta.1` y ya no es la rama de publicaciones de la línea 0.1.2.** > Para hosts DSH `0.1.0-rc.7` ~ `0.1.1-rc.x` usa versiones históricas ≤ `0.1.2`. > Definiciones de las fuentes de los campos: > `mine-dsh-plugins/improve-dsh-plugins/DSH-PLUGIN-VERSION-DISTRIBUTION-STRATEGY.md` §2.2. > > **Adaptación a 0.1.5 (rama compat/0.1.5, npm 3.0.0)**: > ① doble vía para `agent.followup` — 0.1.5 convierte el Inbox en una proyección de solo lectura del bucle del agente; si `followup` > ya no existe, se recurre a `agent.send`, y si no existe ninguno de los dos se degrada a un warn sin lanzar errores (red de seguridad para la reanudación); > ② los mensajes de reanudación añaden a `source` el campo `form: 'instructions'` (contrato ContextFormed de 0.1.5, las versiones anteriores lo ignoran); > ③ `webServer.register` se envuelve en try/catch: un fallo de registro solo queda en el registro y no tumba la carga de plugins del host; > ④ 0.1.5 elimina el acceso de matriz a `session.events`; la lectura de eventos pasa por `snapshotEvents()` como vía principal + > respaldo en la matriz antigua (afecta solo a las dos rutas auxiliares `findToolOutcome` / `lastUserPrompt`, la comparación por tipo de evento no cambia). > Verificado que el contrato `WebRoute` de 0.1.5 (exact/prefix + SSE) no cambia: el cliente > `fetch('/session-guard/...')` no necesita el prefijo `/api`. > La tabla de compatibilidad de abajo abarca dos generaciones de API (0.1.1 / 0.1.2); esta línea solo reclama la fila 0.1.5. > `session/event`, `agent.cancel`, `goals.pause`, > `agent.followup`, `commands.register`, `timer.interval`, `webServer.register`, > `agent/request`, `llm.listConfigurableProviders`, `settings.register/get` tienen firmas > idénticas entre `dsh-v0.1.1-rc.2` y `dsh-v0.1.2-rc.1` (esta línea está verificada hasta `dsh-v0.1.5-rc.2`); > lo único que exige doble lectura es la forma del id de llamada que registra `tool/result` (prioridad de `content[].toolCallId`, > respaldo en `source.callId`), extraída a `src/tool-call-id.js` con pruebas unitarias — en los registros de reproducción de ambas versiones pueden aparecer ambas formas. > Desde 0.1.5 el acceso de matriz a `session.events` está eliminado; esta línea lee por `snapshotEvents()` (conservando el respaldo de la matriz antigua), > afectando solo a las dos rutas auxiliares `findToolOutcome` / `lastUserPrompt`. > El evento `model/selection` existe **solo desde 0.1.2**, sirve únicamente para acelerar el cambio de modelo y exige siempre detección de capacidad; la superficie de ajustes usa solo > la intersección de `register` + `get` (nunca `installSection` / el `installSettingsSection` eliminado). > Script centinela contra la deriva: `tools/check-api-drift.ps1` (esta línea verifica por defecto contra `dsh-v0.1.5-rc.2` la existencia de las interfaces necesarias). > Pausa automáticamente las sesiones en ejecución durante las horas punta y las reanuda automáticamente fuera de punta y los fines de semana; junto con el botón de congelación de input-traffic consigue un bloqueo **a nivel de sesión**; el **reintento automático** del backend cede el paso durante la congelación/la compuerta. El núcleo se basa en una **compuerta de sesión propia** (`agent.cancel keepInbox + goals.pause + session/event frontera segura + reanudación por followup`) y ya no depende de dsh-task-control. Plugin de cordis montado con el comando `dsh plugin` y un parche del bundle — sin modificar el código fuente de dsh y sin PR. > 💡 **Por qué se recomienda**: DeepSeek aplica desde el 2026-08-17 una **facturación por horas punta y valle** — en las horas punta (hora de Pekín 9:00-12:00, 14:00-18:00) el precio unitario es el **doble** que en horas valle (incluidas las de mediodía, noche, fines de semana y festivos). Este complemento detiene automáticamente las sesiones en ejecución durante la punta y las reanuda automáticamente al salir de ella; las ejecuciones largas escalonadas pueden ahorrar hasta un **50 %**; la congelación manual (con el botón de input-traffic) permite un control aún más preciso, sesión a sesión. ## Resumen de funciones - **Modo fin de semana**: identifica los fines de semana (con `Intl.DateTimeFormat` según la zona horaria configurada, evitando el clásico fallo de 8 horas en el límite UTC+8 del `getUTCDay()` desnudo para la hora de Pekín) → los fines de semana se ignoran punta y valle y se ejecuta con libertad. - **Pausa automática en punta (global)**: al entrar en punta (y si no es fin de semana), pausa automáticamente todas las sesiones raíz `running`; al salir de punta las reanuda todas automáticamente — **interruptor global, sin gestión manual**. - **Veredicto bidimensional de fuentes oficiales (providerGuard)**: en las horas punta solo se bloquea **si el destino de la solicitud es una fuente oficial de DeepSeek**; con proveedores locales/externos (como `local-35b`) la ejecución sigue con normalidad, sin que la afecte la compuerta de punta. Criterio de veredicto = lista explícita de id → endpoint de `baseURL` → endpoint por defecto del catalog → id integrado. - **Red de seguridad a nivel de solicitud + cola diferida**: las sesiones iniciadas tras el inicio de la punta, o cambiadas a mitad de camino a una fuente oficial, las captura la guardia a nivel de solicitud `agent/request` (por defecto `hold`: la solicitud queda suspendida sin error y se libera automáticamente al salir de punta). - **Congelación / reanudación a nivel de sesión**: puerto redundante `sessionGuard` + `POST /session-guard/rpc`, conectado sesión a sesión mediante el botón de congelación de input-traffic; también ofrece los comandos manuales `/pause /resume /cancel`. - **Reintento automático del backend (D9)**: los fallos transitorios de turn/end (error/429/max-tokens) se reanudan automáticamente con retroceso adaptativo; los fallos permanentes detienen; **cede el paso durante congelación/compuerta**, nunca la rodea. - **fail-open**: compuerta de sesión propia no disponible, session-guard no instalado, servicio de ajustes ausente — en todos los casos degradación silenciosa, nunca un fallo por causa de una dependencia. ## Vista previa de la interfaz Captura de una ejecución real (Windows, dsh web) — modo fin de semana activo:

## Instalación ```bash # Hosts DSH 0.1.5-rc.x (esta línea, dist-tag dsh-0.1.5) dsh plugin --profile web add dsh-session-guard@dsh-0.1.5 # o directamente desde la rama git dsh plugin --profile web add github:drscrewdriver/dsh-session-guard#compat/0.1.5 # Los hosts DSH 0.1.2-rc.x deben usar la línea 0.1.2 dsh plugin --profile web add dsh-session-guard@dsh-0.1.2 ``` `compat/0.1.5` es la línea dedicada a DSH `0.1.5-rc.x`, número de versión npm **`3.0.0`**; los hosts DSH `0.1.2-rc.x` deben usar la rama **`legacy/0.1.2`** (dist-tag npm `dsh-0.1.2`, versión `0.3.1`). **`main` está congelado en `0.2.0-beta.1`, ya no es la rama de publicaciones de la línea 0.1.2.** > ⚠️ No confíes en el nombre de paquete desnudo `dsh-session-guard`: la etiqueta `latest` de npm no puede servir a la vez dos líneas de > versión mutuamente excluyentes (sus `engines.dsh` son excluyentes según las reglas de semver para prerelease) — hay que indicar siempre el dist-tag de forma explícita. Tras instalar, reinicia dsh web y actualiza la página. ## Ajustes (Ajustes → Plugins → session-guard, interruptores simples) | Interruptor | Por defecto | Descripción | |---|---|---| | `enabled` | on | **Pausa/congelación automática de sesiones en punta**: pausa automáticamente las sesiones en ejecución durante las horas punta | | `stepLevelPause` | on | **Compuerta a nivel de paso**: en punta cierra la compuerta **antes** de la solicitud al modelo del siguiente paso (antes y con más ahorro que la pausa a nivel de turno); off vuelve a la pausa a nivel de turno | | `providerGuard` | on | **Veredicto bidimensional de fuentes oficiales**: en punta solo se bloquean las fuentes oficiales de DeepSeek, los proveedores locales/externos siguen con normalidad | | `guardSubagents` | on | **Incluir solicitudes de subagentes**: las solicitudes de subagentes también se facturan, por defecto se bloquean igualmente | | `offPeakAutoResume` | on | **Reanudación automática en horas valle**: las sesiones pausadas se reanudan automáticamente en horas valle; off no hay reanudación automática al salir de punta (hace falta acción manual) | | `weekendMode` | on | **Modo fin de semana**: identifica los fines de semana → sin pausa automática los fines de semana (no hay punta, se ejecuta con libertad) | | `deferredResume` | on | **Reanudación automática tras la punta**: off las solicitudes/sesiones diferidas no se reanudan solas, hace falta un `/resume` manual | | `queueFallback` | on | Respaldo en la cola de espera bajo bloqueo cuando la compuerta de sesión propia no está disponible (fail-open) | | `retryEnabled` | off | **Reintento automático (backend)**: reanudación automática tras fallos transitorios (desactivado por defecto, conservador) | Configuración adicional: - `timezone` (por defecto Asia/Shanghai) — zona usada para la **detección del fin de semana** y la visualización de la insignia; **no afecta a la detección de punta/valle** (siempre hora de Pekín); - `peakWindows` (por defecto 09:00–12:00 / 14:00–18:00) — ventanas de punta/valle en hora de Pekín (UTC+8), en línea con la facturación oficial de DeepSeek; - `pauseMode` (`safe`/`force`), `pauseReason` (`wait`/`stop`) — forma de efectuar la pausa; - `stepGateTimeoutMs` (por defecto 300000) — tiempo máximo de espera de la compuerta de paso; al vencer, se libera la compuerta y **se escala a una pausa a nivel de turno** (antibloqueo, sin «un paso cada 5 minutos» y el goteo de tokens que supone); - Veredicto de fuentes oficiales: `officialProviders` (id de proveedores oficiales adicionales, separados por comas, prioridad máxima), `officialBaseURLs` (lista de hosts de endpoints oficiales, por defecto `api.deepseek.com`); - Cola diferida: `deferredMode` (`hold` mantiene en espera / `error` da error y difiere), `deferredResumeText` (texto de reanudación al salir de punta), `deferredMaxHoldMs` (límite de espera, 6 horas por defecto, al vencer pasa a error); - Parámetros de reintento: `retryText`, `retryGraceMs`, `retryCooldownMs`, `retryBackoffFactor`, `retryBackoffMaxMs`, `retryMaxConsecutive`. ## Comportamiento ### Compuerta automática de punta (global) - **Entrada en punta** (y no fin de semana): con `stepLevelPause` activado el turno **ya no se interrumpe de inmediato** — la sesión avanza con naturalidad hasta el siguiente límite `agent/pre-step`, donde se cierra la compuerta de paso (ver la sección siguiente); desactivado, se llama a `gate.stopNextTurn` sobre todas las sesiones raíz `running` (pausa real mediante la compuerta de sesión propia, o respaldo en la cola de espera bajo bloqueo según `queueFallback`); - **Salida de punta / fin de semana**: primero `releaseAll` libera los pasos retenidos (el turno continúa en su sitio), después `gate.resume` sobre **todas** las sesiones — controlado por el interruptor `offPeakAutoResume`, desactivado no hay reanudación automática al salir de punta; - **Zona horaria de punta/valle**: siempre hora de Pekín (`Asia/Shanghai`), en línea con la base de facturación oficial de DeepSeek, sin verse afectada por el ajuste `timezone`; - Máquina de estados: instancia única `NORMAL ↔ PAUSED_PEAK` (`scheduler.js`), impulsada por un único tick de 30 s. ### Compuerta a nivel de paso (v0.2.0, la clave del ahorro de tokens) Enganchada a la cascada `agent/pre-step`: el turno se suspende **antes de que ocurra la solicitud al modelo del siguiente paso**. - **Condiciones de cierre** (todas necesarias): `enabled` + `stepLevelPause` + `step > 1` + punta (hora de Pekín, no fin de semana) + proveedor de destino oficial (`providerGuard`, si está desactivado se bloquean todos) + sesión no retenida ya a nivel de solicitud + no saltada manualmente en esta punta; - **Por qué `step > 1`**: el primer paso de un turno lo cubre la guardia a nivel de solicitud, para que las dos compuertas no se solapen; - **Vías de liberación**: ① botón «⏸ en pausa (continuar)» / `POST /session-guard/rpc {action:'stepResume'}` / `/resume` → deja pasar el paso actual y **deja de bloquear esta sesión por el resto de la punta**; ② salida de punta → todo se libera, el turno continúa en su sitio (**no hace falta followup**); ③ botón de congelación / `/pause` / `/cancel` → se libera la compuerta y se pasa a la pausa a nivel de turno; ④ abort de la `signal` (cancelación del usuario) → liberación; - **Escalado por tiempo**: una suspensión mayor que `stepGateTimeoutMs` (5 minutos por defecto) → se libera la compuerta y **se escala a una pausa force a nivel de turno**, con reanudación uniforme al salir de punta (sin bloqueos definitivos ni goteo de tokens durante la punta); - **Estado**: `GET /session-guard/state?session=` devuelve `paused: { step, turn }` y `stepGate: { held, since, bypass }`; el `paused` del puerto de servicio `state()` **sigue siendo booleano** (compatibilidad hacia atrás), el estado del paso va en `pausedStep`; - **No se persiste**: la suspensión es una Promise en el proceso, se pierde al reiniciar (evita estados fantasma). #### Botones «Pausar sesión / Reanudar sesión» (proporcionados por session-guard) El botón «Pausar sesión» a la derecha del área de entrada (slot `conversation.input.right`, id `session-guard-pause`, order 20, a la izquierda del «❄ Congelar y añadir» de input-traffic): - sin pausar → «Pausar sesión», **pulsable**: el clic llama a `stepPause` y pausa la sesión **antes de la solicitud al modelo del siguiente paso** (sin interrumpir el paso actual; el paso 1 también se retiene, sin condiciones de punta/valle ni de proveedor); - pausado → «Reanudar sesión», el clic llama a `stepResume`: deja pasar el paso actual y deja de bloquear esta sesión por el resto de la punta; - **Empuje de eventos**: `GET /session-guard/events?session=` (SSE) notifica **al instante** los cambios de estado de la compuerta de paso — cuando la punta cierra la compuerta automáticamente el botón pasa enseguida a «Reanudar sesión», sin esperar al sondeo; además, un sondeo de `/session-guard/state` cada 10 segundos actúa de red de seguridad (converge incluso con el SSE no disponible/desconectado); - estilo alineado con los botones de input-traffic de la misma fila (24 px de alto / 6 px de radio / fuente de 12 px / los mismos tokens CSS), con respuesta visual al pasar el ratón y en estado de pausa. ### Bloqueo de sesión (congelación) - **Puerto redundante**: `ctx.provide('sessionGuard', service)` — `stopNextTurn(sessionId)` / `resume(sessionId)` / `lockQueue(sessionId)` / `unlockQueue(sessionId)` / `state(sessionId)`; - **Puente RPC**: `POST /session-guard/rpc { action, sessionId }` — el botón de congelación de input-traffic llama a `stopNextTurn` / `resume` **sesión a sesión** según `sessionId`; se omite silenciosamente si este complemento no está instalado (fail-open D8); - **Comandos manuales**: `/pause [force|safe] [stop|wait]`, `/resume [confirm] [rerun|skip]`, `/cancel` — actúan sobre la sesión que los invoca (tomando `invocation.agent.id`). ### Reintento automático del backend (D9) Escucha `turn/end` y clasifica los fallos: - **Fallos transitorios** (error/429/max-tokens, etc.) → reanudación automática `followup(retryText)` con retroceso adaptativo; - **Fallos permanentes** (autenticación/saldo/modelo/límite de contexto) → parada; - **Cede el paso durante congelación/compuerta**: no reintenta cuando `isFrozen(sessionId)` es verdadero (queueLocked / paused / taskControl paused); - La intervención del usuario o un turno con éxito reinician el contador de fallos consecutivos. ### Insignia de estado (visualización en el frontend) A la derecha del área de entrada aparece una insignia de estado **puramente informativa** que refleja en tiempo real la fase actual: | Fase | Texto de la insignia | Clase CSS | Significado | |---|---|---|---| | `peak` (veredicto bidimensional activo) | 高峰·拦官方 | `sg-peak` | Horas punta, solo se bloquean las solicitudes a fuentes oficiales de DeepSeek | | `peak` (veredicto bidimensional inactivo) | 高峰·全部暂停 | `sg-peak` | Horas punta, todas las sesiones en pausa | | `off-peak` | 谷时 | `sg-off` | Fuera de punta, las sesiones funcionan con normalidad | | `weekend` | 周末 | `sg-weekend` | Fin de semana (con el modo fin de semana activo), se ignoran punta y valle | - **Sondeo**: cada 15 segundos se solicita `GET /session-guard/status`, para obtener el `phase` global, `providerGuard`, `held`, `deferred`, `stepHeld`; - **fail-open**: ruta inaccesible, error de red o `enabled` desactivado → la insignia se oculta en silencio, sin afectar a ninguna sesión; - **Independiente de input-traffic**: la insignia la dibuja únicamente el cliente de session-guard, se muestra **sin necesidad de instalar el complemento input-traffic**. input-traffic solo aporta el botón de congelación, sin relación de dependencia con la insignia; - **Tooltip**: al pasar el ratón muestra `fase · zona horaria · modo fin de semana · criterio de veredicto · números de retenciones/diferidos/retenciones de paso`. ### Criterio de veredicto de fuentes oficiales (providerGuard) En punta no se detienen las sesiones sin más: primero se comprueba si «la ruta por la que realmente irá esta solicitud es una fuente oficial de DeepSeek»: | Prioridad | Base | `matchedBy` | Ejemplo | |---|---|---|---| | 1 | lista explícita de id en `officialProviders` | `explicit` | el usuario declara oficial su propia pasarela | | 2 | host de la `baseURL` normalizada en tiempo real | `endpoint` | `deepseek-official` apuntado a un relé → **no se bloquea** | | 3 | endpoint por defecto integrado en el catalog | `endpoint-default` | la ruta `deepseek` de pi-ai apunta por defecto a la API oficial → **se bloquea** | | 4 | lista de id integrada (`deepseek-official`) | `route-id` | respaldo cuando el endpoint no es legible | | 5 | cualquier otra cosa | `unknown` | no oficial, se deja pasar | - **El endpoint pesa más que el id**: una configuración llamada `deepseek-official` pero con `baseURL` apuntando a un relé **no** se bloquea por error; al revés, la ruta `deepseek` integrada de pi-ai tiene por defecto la API oficial como endpoint y **no** escapa del bloqueo. - **Origen de los endpoints**: `ctx.get('llm').listConfigurableProviders()` localiza la entrada del catálogo → `ctx.settings.get(settingsNs)` lee la `baseURL` vía `settingsPath` (solo se leen campos no secretos, el valor de `apiKeyEnv` jamás se lee). Se recalcula en cada solicitud y no se cachea → los cambios en caliente de la configuración de un proveedor surten efecto al instante. - **Cambiar a no oficial reanuda la sesión**: si tras la pausa de punta la sesión se cambia a un proveedor local/externo (evento `model/selection` desde 0.1.2+) → esa sesión se reanuda automáticamente (sujeto a `deferredResume`); solo se tocan las sesiones que este complemento pausó al entrar en punta, las pausadas manualmente con `/pause` **jamás** se tocan. Sin ese evento en 0.1.1 → se degrada a «la siguiente solicitud o un `/resume` manual». - **Endpoint ilegible**: servicio `llm` ausente, estructura del espacio de nombres cambiada, campo no cadena — siempre se degrada al veredicto por id / endpoint integrado registrando el `matchedBy`, **nunca se lanza una excepción**. - **Investigar un veredicto erróneo**: `GET /session-guard/provider?provider=` devuelve `{ official, matchedBy, endpoint }`. ### Guardia a nivel de solicitud y cola diferida - **Por qué a nivel de solicitud**: el tick de 30 s solo atiende, en el salto `NORMAL → PAUSED_PEAK`, a las sesiones que estaban `running` en ese momento; las sesiones iniciadas tras el inicio de la punta o cambiadas a mitad de camino a una fuente oficial se le escapan. La cascada `agent/request` es la red que pasa **con cada solicitud**. - **El veredicto se basa en el valor devuelto por `next()`**: el middleware de selección de modelo sobrescribe provider/model dentro de la cascada con los valores elegidos en la interfaz, así que hay que hacer primero `await next()` y juzgar después. - **Modo hold (por defecto)**: la solicitud queda suspendida, **sin enviarse ni dar error**, y se libera en el instante exacto de salida de punta (`msUntilOffPeak` con temporización precisa, tick de 30 s como red de seguridad); la cancelación del usuario (abort) interrumpe con normalidad. - **Modo error**: lanza un error reconocible `PEAK_DEFERRED` + apunta en la cola diferida, con reanudación al salir de punta mediante `deferredResumeText` (sin reanudación automática si `deferredResume` está desactivado). - **Protección de tope**: si `deferredMaxHoldMs` (6 horas por defecto) vence sin que acabe la punta → pasa a error, para evitar suspensiones infinitas. - **Regla férrea de exclusión mutua**: durante un hold **jamás** se pide además la pausa por la compuerta de sesión (la pausa espera una frontera segura a la que una solicitud retenida nunca llegará → se esperarían mutuamente). Al entrar en punta se saltan las sesiones ya retenidas. - **Sin persistencia**: la cola diferida es una promise en el proceso, desaparece al reiniciar. ### Límites (explícitamente fuera de alcance) - **Sin cambio de proveedor / sin redirección**: solo bloquea, no enruta; - **La compaction no pasa por `agent/request`**: no puede ocurrir mientras una sesión esté en pausa; una compresión disparada manualmente durante la punta puede alcanzar la fuente oficial (este complemento no intercepta la capa `ctx.llm.stream`); - **0.1.1 no tiene el evento `model/selection`**: la reanudación automática tras cambiar a una fuente no oficial se degrada a «esperar a la siguiente solicitud o un `/resume` manual» (inmediato desde 0.1.2); - **Sin nuevas dependencias npm**, sin lectura ni escritura de credenciales, y los reintentos 429 / de capa de transporte de `dsh-llm-retry` no se tocan. ### Manejo y validación de zonas horarias - La detección de zona se basa en **nombres de zona IANA** (como `Asia/Shanghai`, `Asia/Tokyo`, `Asia/Seoul`), proyectados mediante `Intl.DateTimeFormat` sobre el reloj de pared de la zona configurada, **sin depender del `getUTCDay()` desnudo** — evitando el clásico fallo de 8 horas en el límite UTC+8 de la hora de Pekín (sábado 00:30 hora de Pekín: en UTC aún es viernes); - `Intl.DateTimeFormat` es a la vez la capa de validación: un nombre de zona no válido (como `Foo/Bar`) lanza una `RangeError`, que un try-catch externo degrada en silencio a la zona por defecto `Asia/Shanghai` (fail-open); - Las ventanas de punta son **cerradas por la izquierda y abiertas por la derecha** `[start, end)`, con soporte de ventanas que cruzan la medianoche (como `22:00–06:00`); - El ajuste `timezone` se comporta igual en todos los idiomas (zh/en/ja/ko) — los nombres de zona IANA de `Intl.DateTimeFormat` no dependen de la configuración regional: con interfaz japonesa/coreana el comportamiento de la zona es idéntico al del chino. ### Reparto de tareas con input-traffic: uno «detiene», el otro «hace cola» Ambos actúan sobre **eslabones distintos de la misma cadena**, y la frontera la fija el propio modelo de inbox de DSH: ``` Entrada del usuario ──(input-traffic elige el tramo)──▶ colas de espera next-step / next-turn │ agent/pre-step ──(compuerta de paso de este complemento)──▶ dejar pasar / retener │ agent/request ──(retención a nivel de solicitud de este complemento)──▶ dejar pasar / retener │ llamada al modelo ``` **Semántica de las colas de DSH (dos colas, no confundirlas)** | Cola | Significado | Cuándo se consume | |---|---|---| | `next-step` | «Entrada a la espera del siguiente límite de paso» | En el siguiente `agent/pre-step`: **al mismo nivel que un resultado de herramienta**, otro paso dentro del mismo turno | | `next-turn` | «Prompt a la espera de un turno independiente» | Al cerrarse el turno actual, arrancado como **turno nuevo** | `Inbox.claim()` **vacía siempre primero `next-step`** y solo toma además **1** elemento de `next-turn` cuando ese límite abre un turno nuevo; el primer paso de un turno lee next-turn, todos los siguientes leen next-step. **Reparto de responsabilidades** - **session-guard = detener**: solo decide «cuándo se puede avanzar» y **jamás toca el contenido ni el orden de las colas**. - compuerta de paso (`agent/pre-step`): retiene **antes** de la solicitud al modelo del siguiente paso; - pausa a nivel de turno (`agent.cancel({keepInbox:true})` + `goals.pause` + frontera segura): detiene el turno actual, **las colas quedan tal cual**; - guardia a nivel de solicitud (hold en `agent/request`): retiene **esta única solicitud al modelo**. - **input-traffic = hacer cola**: solo decide «a qué cola va la entrada del usuario, con qué tramo y cuándo se consume». - tres tramos = a qué cola va: rojo «interrumpir» hace primero `cancel()` y luego `steer`; amarillo «intercalar» hace `steer` (→ `next-step`, el siguiente paso del mismo turno); verde «a la cola» se queda en `next-turn`; - congelación = extraer las filas `queued` + `steering` (conservando el tramo) + bloqueo del composer + llamada a `sessionGuard.stopNextTurn`; reanudación = quitar el bloqueo → primero `sessionGuard.resume` → reenvío según el tramo. **Dos reglas férreas en el punto de encuentro** 1. **La congelación debe dejar que este complemento libere primero la compuerta de paso**: la compuerta de paso está enganchada a `agent/pre-step`, mientras que la pausa a nivel de turno espera un evento en la frontera segura — se esperarían mutuamente (`pauseTask` / `cancelTask` de este complemento hacen primero `release`); 2. **Con la compuerta de paso retenida, los mensajes ya fueron tomados**: `preStep()` hace `inbox.claim()` antes de despachar la cascada, así que las entradas nuevas hacen cola detrás del lote ya tomado; `keepInbox` solo aplica a la pausa a nivel de turno. **Ninguna invasión mutua**: input-traffic no escucha `agent/pre-step` / `agent/request` (única excepción el `cancel()` explícito del tramo «interrumpir», pedido por el propio usuario); este complemento nunca reescribe el contenido ni el orden de `next-step` / `next-turn`. En cuanto a los botones: los botones «Pausar sesión / Reanudar sesión» de este complemento (order 20) y los de input-traffic «❄ Congelar y añadir / Reanudar y añadir» (order 30) aparecen uno al lado del otro sin sustituirse — los primeros gobiernan la compuerta de paso, los segundos la extracción de la cola + la congelación a nivel de turno. ## Puerto redundante `sessionGuard` ```js { stopNextTurn(sessionId, opts), // detiene el próximo turno de la sesión (compuerta de sesión propia / respaldo en cola bajo bloqueo) resume(sessionId, opts), // reanuda (confirm + choice: rerun|skip) lockQueue(sessionId, reason), // bloquea explícitamente la cola unlockQueue(sessionId), // desbloquea explícitamente stepPause(sessionId), // solicita manualmente una pausa a nivel de paso (cierre en el siguiente límite pre-step, también el paso 1) stepResume(sessionId, opts), // abre la compuerta de paso (v0.2.0); con opts.bypass=false no se salta esta punta state(sessionId), // { queueLocked, lockReason, paused, pausedStep, stepHeldSince, stepBypass, taskControlAvailable, taskControl } } ``` ## Rutas HTTP - `GET /session-guard/state?session=` — estado de la sesión (con `paused: { step, turn, manual }` / `stepGate` / último destino / en retención o no / diferida o no) - `GET /session-guard/events?session=` — **SSE**: notificación inmediata de cambios de estado de la compuerta de paso (el botón se actualiza gracias a esto) - `GET /session-guard/settings` — ajustes + disponibilidad de taskControl - `GET /session-guard/status` — fase global actual (sondeo de la insignia de estado; incluye `stepHeld`) - `GET /session-guard/provider?provider=` — diagnóstico del veredicto de fuente oficial (`official` / `matchedBy` / `endpoint`) - `GET /session-guard/diag` — diagnóstico en tiempo de ejecución (incluye `stepGate`) - `POST /session-guard/rpc` — `{ action: stopNextTurn|resume|lockQueue|unlockQueue|stepPause|stepResume|state, sessionId }` ## Almacenamiento del estado JSON por sesión: `$DSH_HOME/.dsh/session-guard/.json` (escritura atómica; se puede anular con `DSH_SESSION_GUARD_STATE_DIR`). ## Pruebas ```bash npm test # node --test tests/*.test.mjs (zonas horarias/fin de semana/máquina de estados/compuerta de sesión/puente/reintento) ``` ## Módulos | Archivo | Responsabilidad | |---|---| | `src/time.js` | Detección de punta/fin de semana (con zona horaria correcta) + `msUntilOffPeak` (temporización precisa de la salida de punta) | | `src/scheduler.js` | Máquina de estados pura NORMAL ↔ PAUSED_PEAK | | `src/provider.js` | Veredicto de fuentes oficiales a cinco niveles (función pura: normalización de endpoint + matriz de decisión) | | `src/provider-directory.js` | Catálogo de endpoints (`llm.listConfigurableProviders` + `settings.get`, degradación en toda la cadena) | | `src/deferrals.js` | Registro de diferidos (retención / liberación / superación del límite / `PeakDeferredError`) | | `src/request-guard.js` | Guardia a nivel de solicitud en `agent/request` (dos modos hold / error) | | `src/step-gate.js` | **Compuerta a nivel de paso en `agent/pre-step`** (v0.2.0: cierre / liberación / escalado por tiempo / bypass, el `decideStepHold` puro es unitestable) | | `src/targets.js` | Seguimiento del «último destino real» de la sesión (`request/header` + `model/selection`) | | `src/wiring.js` | Orquestación del cableado (filtro de entrada en punta / cableado de la compuerta de paso / liberación al salir de punta / temporización precisa / limpieza al descargar) | | `src/pause-gate.js` | Motor de la compuerta de sesión propia (agent.cancel keepInbox + goals.pause + frontera segura + reanudación por followup; libera antes la compuerta de paso antes de pausar) | | `src/pause-store.js` | Persistencia del estado de pausa propio | | `src/gate.js` | Controlador de la compuerta de sesión (pausa real propia / respaldo en cola bajo bloqueo, fail-open) | | `src/bridge.js` | Puerto redundante `sessionGuard` | | `src/retry.js` | Reintento automático del backend (clasificación de fallos/retroceso/cesión durante congelación; cortocircuito solo con el código exacto `PEAK_DEFERRED`) | | `src/detect.js` | Detección automática (taskControl del host / puente cliente input-traffic) | | `src/store.js` | Estado persistente por sesión | | `src/settings.js` | Subsección de ajustes (esquema schemastery + registro fail-open) | | `src/index.js` | apply en el host (ajustes/rutas/tick/provisión del servicio/cableado del reintento/guardia de solicitudes) | | `src/client/` | Mitad de navegador (**botón de pausa de sesión** + insignia de estado + tarjeta de ajustes) | ## Licencia MIT — véase [LICENSE](LICENSE).