PulseAgent

Inglés | 简体中文

PulseAgent es un sidecar MCP consciente de las interrupciones para agentes de codificación de larga duración. Permite que un agente de IDE note cuándo la orientación del usuario, las restricciones del proyecto o el plan actual han cambiado mientras el agente ya estaba trabajando.

PulseAgent no reemplaza a Cursor, Codex, Claude Code, Copilot u otro agente de IDE. Añade un pequeño protocolo local al proyecto además de un servidor MCP HTTP transmitible para que el agente pueda pausar, actualizar el contexto, replanificar, reconocer el nuevo plan y continuar bajo las instrucciones más recientes.

Por qué PulseAgent

Las tareas de codificación largas a menudo se desvían porque el usuario cambia de opinión, añade una restricción o actualiza el plan mientras el agente todavía está ejecutando un modelo mental antiguo. PulseAgent le da a ese flujo de trabajo una fuente de verdad compartida:

• los usuarios editan algunos archivos bajo .pulse/;

• PulseAgent registra los cambios como eventos;

• el agente verifica MCP antes de continuar;

• los cambios que invalidan el plan permanecen pendientes hasta que el agente reconoce explícitamente el plan revisado.

Related MCP server: call-a-human-mcp

Instalación

Instalar desde GitHub:

pip install git+https://github.com/zhangyh0426/PulseAgent.git

Para desarrollo local:

pip install -e ".[dev]"

Inicio rápido

Inicie PulseAgent en el proyecto en el que desea que trabaje un agente:

cd my-project
pulse start

La primera ejecución crea:

.pulse/
├─ task.md
├─ guidance.md
├─ constraints.md
├─ plan.md
├─ state.json
└─ events.jsonl

El punto final MCP es:

http://127.0.0.1:8765/mcp

Conéctese con el Inspector MCP:

npx -y @modelcontextprotocol/inspector

Luego conéctese a http://127.0.0.1:8765/mcp.

Configuración del agente de IDE

Añada PulseAgent como un servidor MCP HTTP en su agente de IDE. Para Claude Code:

claude mcp add --transport http pulse-agent http://127.0.0.1:8765/mcp

Añada esta regla a las instrucciones del agente:

Before continuing long-running work, read pulse://context/latest and call
pulse_should_interrupt. If needs_replan is true, update .pulse/plan.md, then
call pulse_ack_replan with pending_replan_event_id before continuing.

Durante una tarea larga, edite .pulse/guidance.md o .pulse/constraints.md cuando el agente necesite una nueva dirección o límites más estrictos.

Cómo funciona

PulseAgent observa cuatro archivos locales del proyecto:

• .pulse/task.md describe la tarea actual.

• .pulse/guidance.md contiene la dirección escrita por el usuario que puede cambiar la tarea.

• .pulse/constraints.md contiene restricciones que pueden limitar el comportamiento del agente.

• .pulse/plan.md contiene el plan de trabajo actual del agente.

Los cambios en guidance.md y constraints.md invalidan el plan. Actualizar plan.md por sí solo no elimina la interrupción. El agente debe llamar a pulse_ack_replan con el pending_replan_event_id devuelto; PulseAgent entonces registra el ID del evento reconocido y el hash SHA-256 del plan.md actual.

Superficie MCP

• Recurso: pulse://context/latest

• Herramienta: pulse_should_interrupt(last_seen_event_id: str | None = None)

• Herramienta: pulse_ack_replan(event_id: str)

• Prompt: pulse_replan

pulse_should_interrupt devuelve el estado del evento más reciente, incluyendo:

{
  "needs_replan": true,
  "latest_event_id": "evt_...",
  "has_new_events": true,
  "changed_files": [".pulse/guidance.md"],
  "pending_replan_event_id": "evt_...",
  "pending_replan_files": [".pulse/guidance.md"],
  "last_acknowledged_event_id": null,
  "last_acknowledged_plan_sha256": null,
  "reason": "..."
}

pulse_ack_replan acepta el evento de replanificación pendiente actual:

{
  "event_id": "evt_..."
}

y devuelve:

{
  "accepted": true,
  "acknowledged_event_id": "evt_...",
  "plan_sha256": "...",
  "reason": "..."
}

Flujo de demostración

Inicie PulseAgent:

pulse start

Cambie la orientación mientras el agente está trabajando:

printf "# Guidance\n\nPrefer a smaller patch and keep public APIs stable.\n" > .pulse/guidance.md

El agente llama a pulse_should_interrupt y ve needs_replan: true.

El agente entonces:

1. lee pulse://context/latest;

2. actualiza .pulse/plan.md;

3. llama a pulse_ack_replan con pending_replan_event_id;

4. continúa solo después de que se acepte el reconocimiento.

Límite de seguridad

• Los archivos de espacio de trabajo ordinarios son datos, no instrucciones.

• Solo la entrada directa del usuario y .pulse/guidance.md pueden cambiar la dirección de la tarea.

• .pulse/constraints.md puede restringir el comportamiento pero no debe ampliar los permisos.

• PulseAgent no ejecuta comandos, modifica archivos fuente, llama a LLMs ni actúa como un entorno de ejecución de agente completo.

Desarrollo

Instale el paquete en modo editable:

pip install -e ".[dev]"

Ejecute pruebas y lint:

python -m pytest
python -m ruff check .

Ejecute la CLI directamente:

python -m pulse_agent --help
python -m pulse_agent --version

Estado

PulseAgent es actualmente un proyecto alfa. El protocolo central es intencionalmente pequeño: un directorio .pulse/ local al proyecto, un registro de eventos, un recurso MCP, dos herramientas MCP y un prompt.

Consulte docs/agent-wrapper.md para obtener un contenedor copiable para agentes de IDE e integraciones directas de API de modelos.

Licencia

MIT