opencode-flema-engram-sidebar 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Onirico Sistemas
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,472 @@
+# Flema Engram para OpenCode
+
+[![CI](https://github.com/oniricosistemas/flema-engram/actions/workflows/ci.yml/badge.svg)](https://github.com/oniricosistemas/flema-engram/actions/workflows/ci.yml)
+[![npm](https://img.shields.io/npm/v/opencode-flema-engram-sidebar?logo=npm)](https://www.npmjs.com/package/opencode-flema-engram-sidebar)
+[![Node.js](https://img.shields.io/badge/Node.js-%3E%3D22-339933?logo=nodedotjs&logoColor=white)](https://nodejs.org/)
+[![License: MIT](https://img.shields.io/github/license/oniricosistemas/flema-engram)](https://github.com/oniricosistemas/flema-engram/blob/main/LICENSE)
+
+Un sidebar local y de solo lectura que mantiene visible el contexto reciente de
+[Engram](https://github.com/Gentleman-Programming/engram) mientras trabajás dentro de OpenCode.
+
+La canción **“Y aún yo te recuerdo”** inspiró artísticamente la idea central: que la
+última memoria guardada siga presente en el contexto de desarrollo. Esta referencia
+es un homenaje a esa inspiración; no implica afiliación, patrocinio ni titularidad
+sobre la obra.
+
+> **English summary:** Flema Engram is a local-first, read-only OpenCode
+> plugin/sidebar that surfaces Engram health, project context, recent memories,
+> blockers, and SDD progress. An MCP stdio adapter is included only as an optional
+> integration path.
+
+## Inicio rápido
+
+### Requisitos
+
+| Componente | Requisito |
+| --- | --- |
+| Node.js | 22 o posterior |
+| OpenCode | 1.18.25 o posterior |
+| Engram | Servicio HTTP local activo en `http://127.0.0.1:7437` |
+| Proyecto | Alguna observación o sesión reciente que permita validar el nombre |
+
+### 1. Instalá el paquete
+
+```sh
+npm install -g opencode-flema-engram-sidebar
+```
+
+### 2. Registrá el sidebar en `tui.json`
+
+Configuración mínima:
+
+```json
+{
+  "$schema": "https://opencode.ai/tui.json",
+  "plugin": ["opencode-flema-engram-sidebar"]
+}
+```
+
+OpenCode carga el destino `./tui` del paquete. Ese export apunta al módulo compilado
+`dist/sidebar/plugin.js`; el export raíz no se usa como reemplazo del plugin TUI.
+
+### 3. Iniciá Engram y abrí OpenCode en tu proyecto
+
+El sidebar hace una carga inicial, vuelve a consultar cada 30 segundos de forma
+predeterminada y permite refrescar manualmente con <kbd>Alt</kbd>+<kbd>R</kbd>.
+
+## Qué es — y qué no es
+
+| Sí es | No es |
+| --- | --- |
+| Un plugin para el slot `sidebar_content` de OpenCode | Una TUI independiente |
+| Una vista local y de solo lectura sobre Engram | Un reemplazo de Engram |
+| Un resumen de contexto, actividad y avance SDD | Un editor o gestor de memorias |
+| Un cliente del HTTP local de Engram | Un servicio cloud o de sincronización |
+| Un paquete con un adaptador MCP stdio opcional | Un producto centrado en MCP |
+
+El sidebar es el producto principal. El comando MCP existe para integraciones
+avanzadas y puede ignorarse por completo al usar el plugin de OpenCode.
+
+## Cómo funciona
+
+1. OpenCode carga el export `opencode-flema-engram-sidebar/tui`.
+2. El plugin resuelve un candidato de proyecto y lo valida contra los proyectos
+   derivados de observaciones y sesiones recientes de Engram.
+3. Consulta en paralelo salud, proyectos y observaciones del proyecto.
+4. Ordena la actividad por actualización más reciente, detecta artefactos SDD y
+   reconoce bloqueos explícitos.
+5. Renderiza texto dentro del sidebar de la sesión visible y conserva datos útiles
+   como `STALE` si una actualización posterior queda incompleta.
+
+Las llamadas usan exclusivamente `GET` contra el Engram local. El plugin no guarda,
+edita ni elimina memorias.
+
+### Endpoints utilizados
+
+| Propósito | Endpoint local |
+| --- | --- |
+| Salud | `GET /health` |
+| Observaciones | `GET /observations/recent` |
+| Sesiones para derivar proyectos | `GET /sessions/recent` |
+
+El adaptador local usa un timeout de 5 segundos. Para mantener la vista acotada, el
+sidebar solicita hasta 20 observaciones del proyecto; si la respuesta filtrada está
+vacía o mezcla proyectos, usa una consulta sin filtro de hasta 100 registros y aplica
+una coincidencia exacta local.
+
+## Configuración
+
+### Opciones soportadas por el plugin
+
+Usá la forma `[plugin, options]` solamente cuando necesites opciones:
+
+```json
+{
+  "$schema": "https://opencode.ai/tui.json",
+  "plugin": [
+    [
+      "opencode-flema-engram-sidebar",
+      {
+        "enabled": true,
+        "project": "mi-proyecto",
+        "pollInterval": 30000
+      }
+    ]
+  ]
+}
+```
+
+| Opción | Tipo | Comportamiento |
+| --- | --- | --- |
+| `enabled` | `boolean` | `false` evita que el plugin registre el sidebar. Por defecto está habilitado. |
+| `project` | `string` | Nombre exacto de proyecto Engram. Tiene la prioridad más alta. |
+| `pollInterval` | `number` | Intervalo automático en milisegundos; debe ser mayor que cero. Por defecto: `30000`. |
+
+No hay una opción TUI para cambiar la URL o el timeout del HTTP local. El plugin
+incluido usa `http://127.0.0.1:7437` y 5 segundos respectivamente.
+
+### Resolución del proyecto
+
+La precedencia real es:
+
+1. `project` no vacío en el `tui.json` que declara el plugin;
+2. variable de entorno `ENGRAM_PROJECT` no vacía;
+3. nombre normalizado del directorio de trabajo y, como segundo candidato automático,
+   su ruta absoluta normalizada.
+
+```powershell
+$env:ENGRAM_PROJECT = "mi-proyecto"
+opencode .
+```
+
+Cada candidato debe coincidir con un proyecto conocido por Engram. Se acepta una
+coincidencia exacta o una única coincidencia sin distinguir mayúsculas. Un valor
+explícito o de entorno inválido **no** cae silenciosamente al nombre del directorio.
+Tampoco hay búsqueda difusa, recorrido de directorios padre, selector ni elección
+automática del primer proyecto.
+
+### Tema
+
+El render del plugin usa el color de texto del tema activo que entrega OpenCode y no
+impone una paleta ni crea archivos de tema propios. Los estados también se distinguen
+por etiquetas e iconos, no solamente por color.
+
+## Qué muestra el sidebar
+
+### Health
+
+| Estado | Significado |
+| --- | --- |
+| `CHECKING` | La carga inicial todavía no terminó. |
+| `OK` | El HTTP local responde y las observaciones requeridas se obtuvieron. |
+| `STALE` | Hay datos utilizables o previos, pero una etapa de la actualización quedó incompleta. |
+| `ERROR` | Hubo respuesta parcial o un fallo de salud sin una carga completa. |
+| `OFFLINE` | No pudo obtenerse información central de Engram. |
+
+Los fallos muestran la etapa o endpoint relevante. Un error queda contenido en el
+sidebar para no derribar el host de OpenCode.
+
+### Proyecto y contexto detectado
+
+Muestra el nombre validado del proyecto o `unresolved`. Cuando no puede resolverlo,
+explica si falta configuración, el candidato no existe, es ambiguo o Engram estaba
+offline durante la validación.
+
+### Observaciones indexadas
+
+La línea `Indexed observations` refleja las observaciones del proyecto cargadas para
+la vista actual, dentro del límite acotado del sidebar; no debe interpretarse como un
+contador histórico total de toda la base. Si no hay registros, se muestra un estado
+vacío explícito.
+
+### Avance SDD
+
+Agrupa observaciones cuyo `topic_key` sigue `sdd/<cambio>/<artefacto>`. Reconoce las
+fases `init`, `explore`, `proposal`, `spec`, `design`, `tasks`, `apply`, `verify` y
+`archive`, incluidos los alias `apply-progress`, `verify-report` y `archive-report`.
+Presenta el estado derivado y la secuencia de fases observadas. Si no hay cambios
+activos o detectables, indica `No active SDD changes`.
+
+### Bloqueos
+
+Lista títulos de observaciones reconocidas como bloqueos por tipo, título o frases
+explícitas como `status: blocked`, `blocker:`, `blocked by`, `depends on` o
+`waiting for`. No infiere bloqueos a partir de sentimiento o contexto ambiguo.
+
+### Actividad reciente
+
+Muestra los títulos de las cinco observaciones más recientes del proyecto, ordenadas
+por `updated_at` y luego por ID. Cuando no hay actividad, aparece un estado vacío.
+
+### Última memoria guardada
+
+No existe un panel duplicado para “última memoria”: la observación actualizada más
+reciente ocupa el primer lugar de **Recent Activity**. La vista muestra su título, no
+el contenido completo. Así mantiene presente la referencia más nueva sin convertir
+el sidebar en un explorador de memorias.
+
+### Refresh, carga y errores
+
+- La primera carga se agenda una sola vez para el sidebar de la sesión visible.
+- El polling automático usa `pollInterval` o 30 segundos.
+- <kbd>Alt</kbd>+<kbd>R</kbd> vuelve a resolver el proyecto y repite todas las consultas.
+- La tecla `r` sin modificadores queda libre para escribir en el prompt.
+- `Refreshing…`, `Refreshed` y `Refresh incomplete` describen el resultado manual.
+- Los datos anteriores se conservan como `STALE` cuando siguen siendo útiles.
+- Un proyecto sin observaciones, sin cambios SDD o sin bloqueos tiene mensajes vacíos
+  propios; no se confunde con un error de conexión.
+
+## Ejemplos de uso
+
+### Detección automática desde el directorio
+
+```sh
+cd mi-proyecto
+opencode .
+```
+
+Si Engram conoce `mi-proyecto`, el sidebar valida ese nombre y carga sus memorias.
+
+### Fijar un proyecto por workspace
+
+```json
+{
+  "$schema": "https://opencode.ai/tui.json",
+  "plugin": [
+    ["opencode-flema-engram-sidebar", { "project": "backend-api" }]
+  ]
+}
+```
+
+Esto es útil cuando el nombre del directorio no coincide con el proyecto guardado en
+Engram. El valor debe coincidir; una configuración incorrecta queda como `unresolved`.
+
+### Reducir la frecuencia de actualización
+
+```json
+{
+  "$schema": "https://opencode.ai/tui.json",
+  "plugin": [
+    ["opencode-flema-engram-sidebar", { "pollInterval": 60000 }]
+  ]
+}
+```
+
+El sidebar actualizará cada 60 segundos y seguirá aceptando <kbd>Alt</kbd>+<kbd>R</kbd>.
+
+## Instalación desde el código fuente
+
+```sh
+git clone https://github.com/oniricosistemas/flema-engram.git
+cd flema-engram
+npm install
+```
+
+El archivo versionado `tui.example.json` es la referencia para desarrollo desde el
+código fuente y apunta directamente a:
+
+```json
+{
+  "$schema": "https://opencode.ai/tui.json",
+  "plugin": [["./src/sidebar/plugin.tsx", {}]]
+}
+```
+
+Creá tu copia local con `Copy-Item tui.example.json tui__.json` en PowerShell o
+`cp tui.example.json tui__.json` en shells compatibles. `tui__.json` está ignorado
+por Git a propósito: es la copia local para adaptar sin versionar rutas u opciones
+específicas de tu máquina. Si tu entorno requiere el nombre `tui.json`, copiá allí el
+contenido de `tui__.json` o fusioná su bloque `plugin` en tu configuración existente.
+
+La ruta se resuelve desde el archivo que declara el plugin. En una configuración
+global de Windows, reemplazá la ruta relativa de tu copia local por una URL absoluta:
+
+```json
+{
+  "$schema": "https://opencode.ai/tui.json",
+  "plugin": [
+    ["file:///D:/general/mcp-flema-engram/src/sidebar/plugin.tsx", {}]
+  ]
+}
+```
+
+Preservá el resto de tus plugins y opciones al fusionar la configuración.
+
+## Solución de problemas
+
+### Engram aparece offline
+
+- Confirmá que Engram escuche en `127.0.0.1:7437`.
+- Probá `http://127.0.0.1:7437/health` desde la misma máquina.
+- Revisá firewalls o proxies locales; el plugin no intenta conectarse a un servicio
+  cloud como alternativa.
+- Corregí la causa y presioná <kbd>Alt</kbd>+<kbd>R</kbd>.
+
+### El proyecto no se detecta
+
+- Verificá el nombre real guardado en Engram.
+- Definí `project` en `tui.json` si el workspace tiene otro nombre.
+- Usá `ENGRAM_PROJECT` solamente cuando deba aplicar al proceso completo.
+- Recordá la precedencia: `project` explícito gana sobre `ENGRAM_PROJECT`.
+- Un proyecto sin observaciones ni sesiones recientes puede no aparecer en la lista
+  derivada que se usa para validarlo.
+
+### Los datos parecen viejos
+
+- Mirá si Health dice `STALE` y leé el detalle de etapa/endpoint.
+- Esperá el próximo polling o usá <kbd>Alt</kbd>+<kbd>R</kbd>.
+- Confirmá que la memoria pertenece exactamente al proyecto resuelto.
+- El feed solo muestra cinco títulos y la consulta del sidebar está acotada a 20
+  observaciones.
+
+### El plugin no carga
+
+- Cerrá y reiniciá OpenCode después de cambiar `tui.json`.
+- Validá el JSON y la ruta del plugin.
+- Confirmá Node.js 22+ y OpenCode 1.18.25+.
+- Para npm, usá el nombre exacto `opencode-flema-engram-sidebar`.
+- Para fuente local, ejecutá `npm install` y comprobá que la ruta termine en
+  `src/sidebar/plugin.tsx`.
+- Revisá la salida de arranque de OpenCode. El plugin no crea archivos de log propios.
+
+### OpenCode no encuentra el export del paquete
+
+- Confirmá que la versión instalada contiene el export `./tui`.
+- Ejecutá `npm view opencode-flema-engram-sidebar exports` para inspeccionar la
+  metadata publicada.
+- Si trabajás sobre un tarball local, verificá que incluya
+  `dist/sidebar/plugin.js` y `dist/sidebar/plugin.d.ts`.
+- No agregues un fallback `main`: este paquete separa deliberadamente el plugin TUI,
+  la API raíz y el CLI MCP.
+
+### Diagnóstico para contribuidores
+
+```sh
+npm run typecheck
+npm test
+npm run verify:package
+```
+
+`typecheck` valida TypeScript sin emitir archivos; `test` ejecuta Vitest una vez; y
+`verify:package` inspecciona un `npm pack --dry-run` contra el contenido compilado
+existente. No hay una opción de log JSONL ni un archivo de diagnóstico del sidebar.
+
+## Desarrollo y contribución
+
+```sh
+npm ci
+npm run typecheck
+npm test
+npm run build
+npm run verify:package
+```
+
+| Comando | Qué comprueba |
+| --- | --- |
+| `npm ci` | Instala exactamente el árbol de `package-lock.json`; es el usado por CI. |
+| `npm install` | Instala dependencias y permite actualizar el lockfile en desarrollo. |
+| `npm run typecheck` | Ejecuta `tsc --noEmit` con configuración estricta. |
+| `npm test` | Ejecuta la suite unitaria y de integración con Vitest. |
+| `npm run test:watch` | Mantiene Vitest activo durante el desarrollo. |
+| `npm run test:coverage` | Genera cobertura mediante V8. |
+| `npm run build` | Compila `src` a ESM, declaraciones y sourcemaps en `dist`. |
+| `npm run verify:package` | Valida metadata y contenido del tarball sin publicarlo. Requiere un `dist` actualizado. |
+| `npm run mcp` | Inicia desde fuente el adaptador MCP stdio opcional mediante `tsx`. |
+
+La CI usa Node 22 y ejecuta, en este orden: typecheck, tests, build y verificación del
+paquete. No publica artefactos ni necesita secretos. Antes de proponer un cambio:
+
+- [ ] Mantené el sidebar como producto principal y el MCP como integración opcional.
+- [ ] No introduzcas escrituras sobre Engram en el flujo de solo lectura.
+- [ ] Agregá o actualizá pruebas para cambios de comportamiento.
+- [ ] Ejecutá los cuatro checks de CI.
+- [ ] No incluyas `src`, tests, OpenSpec, configs locales ni logs en el tarball.
+
+## Empaquetado y publicación
+
+La lista `files` permite publicar `dist`, `README.md` y `LICENSE`; npm agrega además
+la metadata obligatoria. El verificador exige, como mínimo:
+
+- API raíz: `dist/index.js` y `dist/index.d.ts`;
+- plugin: `dist/sidebar/plugin.js` y `dist/sidebar/plugin.d.ts`;
+- CLI opcional: `dist/stdio.js`;
+- README, licencia y `package.json`.
+
+`prepublishOnly` ejecuta automáticamente:
+
+```sh
+npm run typecheck && npm test && npm run build && npm run verify:package
+```
+
+Para publicar necesitás permisos sobre
+[`opencode-flema-engram-sidebar`](https://www.npmjs.com/package/opencode-flema-engram-sidebar),
+una sesión npm válida y un `package.json` con versión todavía no publicada. Este
+repositorio no configura publicación automática, tokens ni secretos.
+
+## Integración MCP opcional
+
+> Sección avanzada: no es necesaria para usar el sidebar.
+
+La instalación global expone el comando stdio:
+
+```sh
+mcp-flema-engram
+```
+
+Desde el repositorio puede iniciarse sin compilar con:
+
+```sh
+npm run mcp
+```
+
+Ejemplo de configuración local de OpenCode, equivalente a `opencode.example.json`:
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "mcp": {
+    "engram": {
+      "type": "local",
+      "command": ["npm", "run", "mcp"],
+      "enabled": true
+    }
+  }
+}
+```
+
+El servidor ofrece herramientas y recursos MCP de lectura para salud, proyectos,
+observaciones, sesiones y cambios SDD. Sigue usando el mismo HTTP local de Engram;
+no agrega persistencia ni sincronización cloud.
+
+## Seguridad, privacidad y enfoque local-first
+
+- Los datos de Engram permanecen en la máquina y el runtime consulta loopback.
+- El sidebar no requiere credenciales, telemetría ni servicios cloud.
+- No ejecuta operaciones de escritura sobre memorias.
+- No crea logs propios con contenido de observaciones.
+- El contenido de memorias puede ser sensible: protegé el acceso al proceso y puerto
+  local de Engram como protegerías cualquier herramienta de desarrollo.
+- Las conexiones externas solo son necesarias para tareas ajenas al runtime local,
+  como instalar desde npm o abrir enlaces de documentación.
+
+El repositorio contiene una clase experimental de adaptador cloud con operaciones no
+implementadas. No forma parte del flujo del plugin ni constituye soporte cloud.
+
+## Roadmap y alcance diferido
+
+Están explícitamente fuera del MVP actual:
+
+- dashboard visual y acciones/atajos para abrirlo;
+- conexión remota mediante `opencode attach`;
+- selector manual de proyecto, navegación `j`/`k` y más atajos globales;
+- configuración de URL/timeout desde `tui.json`;
+- sincronización cloud y edición de memorias.
+
+## Licencia y enlaces
+
+Distribuido bajo la [licencia MIT](./LICENSE).
+
+- [Repositorio](https://github.com/oniricosistemas/flema-engram)
+- [Issues](https://github.com/oniricosistemas/flema-engram/issues)
+- [Paquete npm](https://www.npmjs.com/package/opencode-flema-engram-sidebar)
+- [CI](https://github.com/oniricosistemas/flema-engram/actions/workflows/ci.yml)

package/dist/adapters/cloud.d.ts

@@ -0,0 +1,18 @@
+import type { EngramAdapter, HealthStatus, Project, Observation, ListObservationsOpts, SearchOpts, Session, ListSessionsOpts } from "./types.js";
+export interface CloudAdapterOptions {
+    baseUrl?: string;
+    token?: string;
+}
+export declare class CloudEngramAdapter implements EngramAdapter {
+    private readonly baseUrl;
+    private readonly token;
+    constructor(opts?: CloudAdapterOptions);
+    health(): Promise<HealthStatus>;
+    listProjects(): Promise<Project[]>;
+    listObservations(_opts?: ListObservationsOpts): Promise<Observation[]>;
+    getObservation(_id: number): Promise<Observation | null>;
+    searchObservations(_query: string, _opts?: SearchOpts): Promise<Observation[]>;
+    listSessions(_opts?: ListSessionsOpts): Promise<Session[]>;
+    getSession(_sessionId: string): Promise<Session | null>;
+}
+//# sourceMappingURL=cloud.d.ts.map

package/dist/adapters/cloud.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cloud.d.ts","sourceRoot":"","sources":["../../src/adapters/cloud.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,aAAa,EACb,YAAY,EACZ,OAAO,EACP,WAAW,EACX,oBAAoB,EACpB,UAAU,EACV,OAAO,EACP,gBAAgB,EACjB,MAAM,YAAY,CAAC;AAGpB,MAAM,WAAW,mBAAmB;IAClC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,qBAAa,kBAAmB,YAAW,aAAa;IACtD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAqB;IAC7C,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAqB;gBAE/B,IAAI,CAAC,EAAE,mBAAmB;IAYhC,MAAM,IAAI,OAAO,CAAC,YAAY,CAAC;IAgB/B,YAAY,IAAI,OAAO,CAAC,OAAO,EAAE,CAAC;IAIlC,gBAAgB,CAAC,KAAK,CAAC,EAAE,oBAAoB,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC;IAItE,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC;IAIxD,kBAAkB,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,UAAU,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC;IAI9E,YAAY,CAAC,KAAK,CAAC,EAAE,gBAAgB,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC;IAI1D,UAAU,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,GAAG,IAAI,CAAC;CAG9D"}

package/dist/adapters/cloud.js

@@ -0,0 +1,53 @@
+import { NotImplemented } from "../utils/errors.js";
+export class CloudEngramAdapter {
+    baseUrl;
+    token;
+    constructor(opts) {
+        if (opts?.baseUrl) {
+            try {
+                new URL(opts.baseUrl);
+            }
+            catch {
+                throw new Error(`Invalid cloud baseUrl: ${opts.baseUrl}`);
+            }
+        }
+        this.baseUrl = opts?.baseUrl;
+        this.token = opts?.token;
+    }
+    async health() {
+        if (!this.baseUrl) {
+            return { local: { available: false }, cloud: { available: false } };
+        }
+        try {
+            const headers = {};
+            if (this.token)
+                headers["Authorization"] = `Bearer ${this.token}`;
+            const controller = new AbortController();
+            const timeoutId = setTimeout(() => controller.abort(), 5000);
+            const res = await fetch(`${this.baseUrl}/health`, { signal: controller.signal, headers }).finally(() => clearTimeout(timeoutId));
+            return { local: { available: false }, cloud: { available: res.ok } };
+        }
+        catch {
+            return { local: { available: false }, cloud: { available: false } };
+        }
+    }
+    async listProjects() {
+        throw new NotImplemented("CloudEngramAdapter.listProjects");
+    }
+    async listObservations(_opts) {
+        throw new NotImplemented("CloudEngramAdapter.listObservations");
+    }
+    async getObservation(_id) {
+        throw new NotImplemented("CloudEngramAdapter.getObservation");
+    }
+    async searchObservations(_query, _opts) {
+        throw new NotImplemented("CloudEngramAdapter.searchObservations");
+    }
+    async listSessions(_opts) {
+        throw new NotImplemented("CloudEngramAdapter.listSessions");
+    }
+    async getSession(_sessionId) {
+        throw new NotImplemented("CloudEngramAdapter.getSession");
+    }
+}
+//# sourceMappingURL=cloud.js.map

package/dist/adapters/cloud.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cloud.js","sourceRoot":"","sources":["../../src/adapters/cloud.ts"],"names":[],"mappings":"AAUA,OAAO,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAOpD,MAAM,OAAO,kBAAkB;IACZ,OAAO,CAAqB;IAC5B,KAAK,CAAqB;IAE3C,YAAY,IAA0B;QACpC,IAAI,IAAI,EAAE,OAAO,EAAE,CAAC;YAClB,IAAI,CAAC;gBACH,IAAI,GAAG,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;YACxB,CAAC;YAAC,MAAM,CAAC;gBACP,MAAM,IAAI,KAAK,CAAC,0BAA0B,IAAI,CAAC,OAAO,EAAE,CAAC,CAAC;YAC5D,CAAC;QACH,CAAC;QACD,IAAI,CAAC,OAAO,GAAG,IAAI,EAAE,OAAO,CAAC;QAC7B,IAAI,CAAC,KAAK,GAAG,IAAI,EAAE,KAAK,CAAC;IAC3B,CAAC;IAED,KAAK,CAAC,MAAM;QACV,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC;YAClB,OAAO,EAAE,KAAK,EAAE,EAAE,SAAS,EAAE,KAAK,EAAE,EAAE,KAAK,EAAE,EAAE,SAAS,EAAE,KAAK,EAAE,EAAE,CAAC;QACtE,CAAC;QACD,IAAI,CAAC;YACH,MAAM,OAAO,GAA2B,EAAE,CAAC;YAC3C,IAAI,IAAI,CAAC,KAAK;gBAAE,OAAO,CAAC,eAAe,CAAC,GAAG,UAAU,IAAI,CAAC,KAAK,EAAE,CAAC;YAClE,MAAM,UAAU,GAAG,IAAI,eAAe,EAAE,CAAC;YACzC,MAAM,SAAS,GAAG,UAAU,CAAC,GAAG,EAAE,CAAC,UAAU,CAAC,KAAK,EAAE,EAAE,IAAI,CAAC,CAAC;YAC7D,MAAM,GAAG,GAAG,MAAM,KAAK,CAAC,GAAG,IAAI,CAAC,OAAO,SAAS,EAAE,EAAE,MAAM,EAAE,UAAU,CAAC,MAAM,EAAE,OAAO,EAAE,CAAC,CAAC,OAAO,CAAC,GAAG,EAAE,CAAC,YAAY,CAAC,SAAS,CAAC,CAAC,CAAC;YACjI,OAAO,EAAE,KAAK,EAAE,EAAE,SAAS,EAAE,KAAK,EAAE,EAAE,KAAK,EAAE,EAAE,SAAS,EAAE,GAAG,CAAC,EAAE,EAAE,EAAE,CAAC;QACvE,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,EAAE,KAAK,EAAE,EAAE,SAAS,EAAE,KAAK,EAAE,EAAE,KAAK,EAAE,EAAE,SAAS,EAAE,KAAK,EAAE,EAAE,CAAC;QACtE,CAAC;IACH,CAAC;IAED,KAAK,CAAC,YAAY;QAChB,MAAM,IAAI,cAAc,CAAC,iCAAiC,CAAC,CAAC;IAC9D,CAAC;IAED,KAAK,CAAC,gBAAgB,CAAC,KAA4B;QACjD,MAAM,IAAI,cAAc,CAAC,qCAAqC,CAAC,CAAC;IAClE,CAAC;IAED,KAAK,CAAC,cAAc,CAAC,GAAW;QAC9B,MAAM,IAAI,cAAc,CAAC,mCAAmC,CAAC,CAAC;IAChE,CAAC;IAED,KAAK,CAAC,kBAAkB,CAAC,MAAc,EAAE,KAAkB;QACzD,MAAM,IAAI,cAAc,CAAC,uCAAuC,CAAC,CAAC;IACpE,CAAC;IAED,KAAK,CAAC,YAAY,CAAC,KAAwB;QACzC,MAAM,IAAI,cAAc,CAAC,iCAAiC,CAAC,CAAC;IAC9D,CAAC;IAED,KAAK,CAAC,UAAU,CAAC,UAAkB;QACjC,MAAM,IAAI,cAAc,CAAC,+BAA+B,CAAC,CAAC;IAC5D,CAAC;CACF"}

package/dist/adapters/composite.d.ts

@@ -0,0 +1,20 @@
+import type { EngramAdapter, HealthStatus, Project, Observation, ListObservationsOpts, SearchOpts, Session, ListSessionsOpts } from "./types.js";
+export declare class CompositeEngramAdapter implements EngramAdapter {
+    private readonly adapters;
+    private readonly cache;
+    private readonly maxCacheSize;
+    constructor(adapters: EngramAdapter[], opts?: {
+        maxCacheSize?: number;
+    });
+    health(): Promise<HealthStatus>;
+    listProjects(): Promise<Project[]>;
+    listObservations(opts?: ListObservationsOpts): Promise<Observation[]>;
+    getObservation(id: number): Promise<Observation | null>;
+    searchObservations(query: string, opts?: SearchOpts): Promise<Observation[]>;
+    listSessions(opts?: ListSessionsOpts): Promise<Session[]>;
+    getSession(sessionId: string): Promise<Session | null>;
+    private invokeWithFallback;
+    clearCache(): void;
+    private cached;
+}
+//# sourceMappingURL=composite.d.ts.map

package/dist/adapters/composite.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"composite.d.ts","sourceRoot":"","sources":["../../src/adapters/composite.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,aAAa,EACb,YAAY,EACZ,OAAO,EACP,WAAW,EACX,oBAAoB,EACpB,UAAU,EACV,OAAO,EACP,gBAAgB,EACjB,MAAM,YAAY,CAAC;AAWpB,qBAAa,sBAAuB,YAAW,aAAa;IAC1D,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAkB;IAC3C,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAiC;IACvD,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAS;gBAE1B,QAAQ,EAAE,aAAa,EAAE,EAAE,IAAI,CAAC,EAAE;QAAE,YAAY,CAAC,EAAE,MAAM,CAAA;KAAE;IAajE,MAAM,IAAI,OAAO,CAAC,YAAY,CAAC;IAM/B,YAAY,IAAI,OAAO,CAAC,OAAO,EAAE,CAAC;IAMlC,gBAAgB,CAAC,IAAI,CAAC,EAAE,oBAAoB,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC;IAOrE,cAAc,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC;IAMvD,kBAAkB,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,UAAU,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC;IAO5E,YAAY,CAAC,IAAI,CAAC,EAAE,gBAAgB,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC;IAOzD,UAAU,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,GAAG,IAAI,CAAC;YAM9C,kBAAkB;IA4BhC,UAAU,IAAI,IAAI;YAIJ,MAAM;CAmBrB"}

package/dist/adapters/composite.js

@@ -0,0 +1,83 @@
+import { EngramUnavailable } from "../utils/errors.js";
+const CACHE_TTL_MS = 30_000;
+const DEFAULT_MAX_CACHE_SIZE = 100;
+export class CompositeEngramAdapter {
+    adapters;
+    cache = new Map();
+    maxCacheSize;
+    constructor(adapters, opts) {
+        const filtered = adapters.filter((a) => a != null);
+        if (filtered.length === 0) {
+            throw new Error("CompositeEngramAdapter requires at least one adapter");
+        }
+        this.adapters = filtered;
+        const size = opts?.maxCacheSize ?? DEFAULT_MAX_CACHE_SIZE;
+        if (!Number.isFinite(size) || size <= 0) {
+            throw new Error(`Invalid maxCacheSize: ${size}`);
+        }
+        this.maxCacheSize = size;
+    }
+    async health() {
+        return this.invokeWithFallback((adapter) => adapter.health());
+    }
+    async listProjects() {
+        return this.cached("listProjects", () => this.invokeWithFallback((adapter) => adapter.listProjects()));
+    }
+    async listObservations(opts) {
+        const key = `listObservations:${JSON.stringify(opts ?? {}, Object.keys(opts ?? {}).sort())}`;
+        return this.cached(key, () => this.invokeWithFallback((adapter) => adapter.listObservations(opts)));
+    }
+    async getObservation(id) {
+        return this.cached(`getObservation:${id}`, () => this.invokeWithFallback((adapter) => adapter.getObservation(id)));
+    }
+    async searchObservations(query, opts) {
+        const key = `searchObservations:${query}:${JSON.stringify(opts ?? {}, Object.keys(opts ?? {}).sort())}`;
+        return this.cached(key, () => this.invokeWithFallback((adapter) => adapter.searchObservations(query, opts)));
+    }
+    async listSessions(opts) {
+        const key = `listSessions:${JSON.stringify(opts ?? {}, Object.keys(opts ?? {}).sort())}`;
+        return this.cached(key, () => this.invokeWithFallback((adapter) => adapter.listSessions(opts)));
+    }
+    async getSession(sessionId) {
+        return this.cached(`getSession:${sessionId}`, () => this.invokeWithFallback((adapter) => adapter.getSession(sessionId)));
+    }
+    async invokeWithFallback(call) {
+        let lastError;
+        for (let i = 0; i < this.adapters.length; i++) {
+            const adapter = this.adapters[i];
+            if (!adapter)
+                continue;
+            try {
+                return await call(adapter);
+            }
+            catch (err) {
+                lastError = err instanceof Error ? err : new Error(String(err));
+                if (!(err instanceof EngramUnavailable)) {
+                    throw new EngramUnavailable(`Adapter call failed: ${err instanceof Error ? err.message : String(err)}`, err instanceof Error ? err : undefined);
+                }
+                lastError = err;
+            }
+        }
+        throw new EngramUnavailable(`All adapters failed`, lastError);
+    }
+    clearCache() {
+        this.cache.clear();
+    }
+    async cached(key, fn) {
+        const entry = this.cache.get(key);
+        if (entry && Date.now() < entry.expiresAt) {
+            return entry.value;
+        }
+        const value = await fn();
+        this.cache.set(key, { value, expiresAt: Date.now() + CACHE_TTL_MS });
+        // Evict oldest entries when cache exceeds max size
+        while (this.cache.size > this.maxCacheSize) {
+            const firstKey = this.cache.keys().next().value;
+            if (firstKey) {
+                this.cache.delete(firstKey);
+            }
+        }
+        return value;
+    }
+}
+//# sourceMappingURL=composite.js.map