Skip to content

feat: backscroll-as-tool — shared core + Pi adapter #102

Open

Description

@pablontiv

Objetivo

Exponer backscroll como herramienta nativa para agentes, de modo que el historial de sesiones relevante aparezca cuando haga falta sin depender de que el modelo recuerde invocar nada. Dos mecanismos combinados:

  1. Tool invocable por el modelo (consultas profundas on-demand).
  2. Hook determinístico de inyección de contexto que, en cada turno, corre una búsqueda barata y solo inyecta si el mejor score supera un umbral (evalúa siempre, inyecta solo si es relevante).

Un MCP puro NO basta: ofrece solo el tool "el modelo decide", sin la capa determinística. Por eso se usan adapters nativos.

Alcance de este issue

Este issue cubre la lógica compartida (core host-neutral) + el primer adapter (Pi). El adapter de Claude va en un issue aparte que depende de este.

Diseño espejo de a4s (packages/synagent/protocol.ts + adapters/*): un core neutral + adapters delgados por harness, con una sola suite de conformidad.

1. Core compartido (host-neutral, sin imports de SDK)

  • search(query, opts) → ejecuta backscroll search --json …, parsea y formatea los resultados.
  • decide(promptText) → extrae keywords del prompt, corre una búsqueda barata y devuelve { inject: boolean, context?: string } según un umbral de score configurable.
  • Funciones puras y testeables; cero dependencias de harness; una suite de conformidad que ambos adapters ejercitan por igual.

2. Adapter Pi (@pablontiv/pion ExtensionAPI)

  • Tool invocable: pi.registerTool({ name: 'backscroll_search', label, description, parameters: Type.Object({...}), async execute(...) }) → delega en core.search.
  • Inyección determinística: pi.on('before_agent_start', (event, ctx) => { ... }) → llama core.decide(event.prompt); si procede, inyecta el contexto mutando event.systemPromptOptions (p.ej. appendSystemPrompt o sections). Corre antes de cada llamada al LLM, no lo decide el modelo.

Criterios de aceptación

  • Core con search y decide como funciones puras, con tests unitarios.
  • Umbral de relevancia configurable.
  • Adapter Pi registra backscroll_search y lo ejecuta contra el core.
  • Adapter Pi inyecta contexto vía before_agent_start solo cuando el score supera el umbral.
  • Suite de conformidad del core reutilizable por futuros adapters.
  • El tool/hook corren backscroll search --json y degradan limpiamente si el binario o el índice no están disponibles.

Referencias

  • Patrón a4s: packages/synagent/protocol.ts (core neutral) + packages/synagent/adapters/pi/index.ts.
  • API Pi: @pablontiv/pion — registerTool / ToolDefinition.execute, on('before_agent_start'), systemPromptOptions (appendSystemPrompt, sections, promptGuidelines, contextFiles).

Activity

  1. pablontiv commented on Oct 13, 2026

    @pablontiv
    OwnerAuthor

    Estado de readiness en eeb9e8f2b0435ac07e3f00f91ea1eb24176df4b3: needs-info; no implementar todavía.

    Evidencia:

    • Este repositorio es un módulo Go y no contiene package.json, tsconfig, workspace packages/* ni imports de @pablontiv/pion; falta definir si el core/adapters viven aquí, en otro repo o en un paquete publicable nuevo.
    • backscroll search --json sí expone score, pero el valor no es una señal de relevancia calibrada: consultas por una sola tabla devuelven bm25() (menor es mejor), mientras la búsqueda sin filtro reemplaza ese valor por RRF (mayor es mejor y depende principalmente del rango; internal/storage/search.go:181-203,459-508, internal/hybrid/rrf.go:12-30). Un umbral configurable de “score supera” no tiene todavía una semántica estable para decide.
    • También faltan contratos de runtime/empaquetado y de ejecución del binario (Node/Bun, ESM/CJS, resolución/configuración de backscroll, timeout y límites de contexto).

    Decisiones necesarias antes de codificar:

    1. repositorio/ruta y artefacto publicable del core + adapter Pi;
    2. runtime y formato de módulo soportados;
    3. señal de relevancia estable para decide (no reutilizar score sin definir dirección/calibración);
    4. contrato de subprocess, timeout, tamaño de contexto y degradación.

    #103 permanece bloqueado por este contrato. Esto no rechaza la funcionalidad; evita introducir una segunda toolchain y una heurística no comparable sin una decisión explícita.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    questionFurther information is requested

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions