Pulse assistant operations

This runbook covers the Pulse floating assistant: how messages move through the platform, what to configure, and how to smoke-test the pipeline.

Architecture (short)

1. Admin — POST /api/assistant-workflow opens an SSE connection, subscribes to Redis chat:{correlationId}, and POSTs a JSON body to the HTTP receiver (same shape as buildAssistantReceiverPayload in loadtest).
2. Receiver → Kinesis → Consumer — The consumer runs the system assistant workflow (org/env from ASSISTANT_WORKFLOW_ORG_ID / ASSISTANT_WORKFLOW_ENV_ID).
3. Workflow — Uses V8 scripts from @rocketwave/stream-shared (assistantResearch, pubsub, optional pinecone). mcpCall hits the admin API with ADMIN_SERVICE_TOKEN.
4. Redis — Workflow publishes progress and the final done / error event; admin forwards them as SSE to the browser.

Canonical reference in the admin repo: docs/ASSISTANT_ARCHITECTURE.md and docs/ASSISTANT_WORKFLOW_PROMPTS.md.

Configuration checklist

Admin (Next.js)

Variable	Purpose
ASSISTANT_WORKFLOW_ORG_ID	UUID of org where the assistant workflow lives
ASSISTANT_WORKFLOW_ENV_ID	UUID of that environment
RECEIVER_URL	HTTP receiver base URL
REDIS_URL	Same Redis the consumer uses for pubsubPublish
ADMIN_SERVICE_TOKEN	Shared secret; consumer sends Authorization: Bearer …

Consumer (ECS / .env)

Variable	Purpose
ASSISTANT_WORKFLOW_ORG_ID / ASSISTANT_WORKFLOW_ENV_ID	Must match admin
ADMIN_API_URL	Admin base URL (e.g. https://console.rocketwavelabs.io)
ADMIN_SERVICE_TOKEN	Same token as admin
ASSISTANT_VECTOR_BACKEND	openai (default) or pinecone for vectorSearch in assistantResearch
ASSISTANT_PINECONE_EXAMPLES_NAMESPACE	Pinecone sub-namespace for examples (default assistant-examples)
OPENAI_VECTOR_*	When using OpenAI vector store
PINECONE_*, EMBEDDING_MODEL_ID, AWS_REGION	When using Pinecone path

Bootstrap a new assistant env (optional)

From the admin repo:

ADMIN_SERVICE_TOKEN=… BASE_URL=https://console.rocketwavelabs.io \
  npm run assistant:bootstrap -- --org <organizationUuid>

This creates an environment and an inactive skeleton workflow, then prints IDs to set as ASSISTANT_WORKFLOW_*.

Smoke test (receiver → consumer)

Use k6 in rocketwave-stream-loadtest:

k6 run --iterations 1 --vus 1 \
  --env ASSISTANT_ORG_ID=<system_assistant_org> \
  --env ASSISTANT_ENV_ID=<system_assistant_env> \
  --env CLIENT_ORG_ID=<tenant_org> \
  --env CLIENT_ENV_ID=<tenant_env> \
  scripts/assistant-pipeline.js

Then verify consumer logs and (for full SSE) Redis/admin behavior.

Troubleshooting

Symptom	Checks
SSE never completes	Redis connectivity from admin and consumer; correlationId channel chat:{id}
MCP failures in consumer logs	ADMIN_API_URL, ADMIN_SERVICE_TOKEN, network from ECS to admin
Wrong tenant data	Payload clientOrganizationId / clientEnvironmentId vs user session org/env
Vector errors	ASSISTANT_VECTOR_BACKEND and matching credentials (OpenAI vs Pinecone + Bedrock)

MCP clients

External tools can call assistant_chat → POST /api/assistant-workflow; the server parses SSE into a JSON summary for non-browser callers. See admin app/api/mcp/lib/apiCaller.ts.