@indexnetwork/protocol 0.1.0

package/dist/types/chat-streaming.types.js

@@ -0,0 +1,260 @@
+/**
+ * SSE Event types for Chat Graph streaming.
+ *
+ * These types define the structure of events sent during streaming chat responses.
+ * Events are sent as Server-Sent Events (SSE) with JSON payloads.
+ */
+/**
+ * Formats a chat stream event as an SSE message. If JSON.stringify throws (e.g. circular ref,
+ * non-serializable value), returns a minimal error event so the stream stays valid.
+ *
+ * @param event - The event to format
+ * @returns SSE-formatted string with "data: " prefix and double newline
+ */
+export function formatSSEEvent(event) {
+    try {
+        return `data: ${JSON.stringify(event)}\n\n`;
+    }
+    catch (serializeError) {
+        const fallback = {
+            type: "error",
+            sessionId: typeof event.sessionId === "string"
+                ? event.sessionId
+                : "unknown",
+            timestamp: new Date().toISOString(),
+            message: "Response could not be serialized. Please try again.",
+            code: "SERIALIZATION_ERROR",
+        };
+        return `data: ${JSON.stringify(fallback)}\n\n`;
+    }
+}
+/**
+ * Creates a chat stream event with common fields populated.
+ *
+ * @param type - Event type
+ * @param sessionId - Session ID
+ * @param data - Event-specific data (excluding type, sessionId, timestamp)
+ * @returns Complete event object
+ *
+ * @example
+ * ```ts
+ * const statusEvent = createStreamEvent<StatusEvent>('status', 'session-123', {
+ *   message: 'Processing your request...'
+ * });
+ * ```
+ */
+export function createStreamEvent(type, sessionId, data) {
+    return {
+        ...data,
+        type,
+        sessionId,
+        timestamp: new Date().toISOString(),
+    };
+}
+/**
+ * Type guard to check if an event is a specific type.
+ */
+export function isEventType(event, type) {
+    return event.type === type;
+}
+/**
+ * Creates a formatted status event.
+ */
+export function createStatusEvent(sessionId, message) {
+    return createStreamEvent("status", sessionId, { message });
+}
+/**
+ * Creates a formatted routing event.
+ */
+export function createRoutingEvent(sessionId, target, reasoning) {
+    return createStreamEvent("routing", sessionId, {
+        target,
+        reasoning,
+    });
+}
+/**
+ * Creates a formatted subgraph start event.
+ */
+export function createSubgraphStartEvent(sessionId, subgraph) {
+    return createStreamEvent("subgraph_start", sessionId, {
+        subgraph,
+    });
+}
+/**
+ * Creates a formatted subgraph result event.
+ */
+export function createSubgraphResultEvent(sessionId, subgraph, data) {
+    return createStreamEvent("subgraph_result", sessionId, {
+        subgraph,
+        data,
+    });
+}
+/**
+ * Creates a formatted token event.
+ */
+export function createTokenEvent(sessionId, content) {
+    return createStreamEvent("token", sessionId, { content });
+}
+/**
+ * Creates a formatted done event.
+ */
+export function createDoneEvent(sessionId, response, options) {
+    return createStreamEvent("done", sessionId, {
+        ...options,
+        response,
+    });
+}
+/**
+ * Creates a formatted error event.
+ */
+export function createErrorEvent(sessionId, message, code) {
+    return createStreamEvent("error", sessionId, { message, code });
+}
+/**
+ * Creates a formatted thinking event.
+ */
+export function createThinkingEvent(sessionId, content, step) {
+    return createStreamEvent("thinking", sessionId, {
+        content,
+        step,
+    });
+}
+// ════════════════════════════════════════════════════════════════════════════
+// AGENT LOOP EVENT CREATORS
+// ════════════════════════════════════════════════════════════════════════════
+/**
+ * Creates a formatted tool start event.
+ */
+export function createToolStartEvent(sessionId, toolName, toolArgs) {
+    return createStreamEvent("tool_start", sessionId, {
+        toolName,
+        toolArgs,
+    });
+}
+/**
+ * Creates a formatted tool end event.
+ */
+export function createToolEndEvent(sessionId, toolName, success, resultSummary) {
+    return createStreamEvent("tool_end", sessionId, {
+        toolName,
+        success,
+        resultSummary,
+    });
+}
+/**
+ * Creates a formatted agent thinking event.
+ */
+export function createAgentThinkingEvent(sessionId, iteration, toolsUsed) {
+    return createStreamEvent("agent_thinking", sessionId, {
+        iteration,
+        toolsUsed,
+    });
+}
+// ════════════════════════════════════════════════════════════════════════════
+// AGENT LOOP TRACE EVENT CREATORS
+// ════════════════════════════════════════════════════════════════════════════
+/**
+ * Creates a formatted iteration start event.
+ */
+export function createIterationStartEvent(sessionId, iteration) {
+    return createStreamEvent("iteration_start", sessionId, {
+        iteration,
+    });
+}
+/**
+ * Creates a formatted LLM start event.
+ */
+export function createLlmStartEvent(sessionId, iteration) {
+    return createStreamEvent("llm_start", sessionId, {
+        iteration,
+    });
+}
+/**
+ * Creates a formatted LLM end event.
+ */
+export function createLlmEndEvent(sessionId, iteration, hasToolCalls, toolNames) {
+    return createStreamEvent("llm_end", sessionId, {
+        iteration,
+        hasToolCalls,
+        toolNames,
+    });
+}
+// ════════════════════════════════════════════════════════════════════════════
+// STREAMING NARRATION EVENT CREATORS
+// ════════════════════════════════════════════════════════════════════════════
+/**
+ * Creates a formatted tool activity event (inline narration).
+ */
+export function createToolActivityEvent(sessionId, toolName, description, phase, success, summary, steps) {
+    return createStreamEvent("tool_activity", sessionId, {
+        toolName,
+        description,
+        phase,
+        success,
+        summary,
+        steps,
+    });
+}
+// ════════════════════════════════════════════════════════════════════════════
+// INTERNAL RESPONSE TRACKING EVENT CREATORS
+// ════════════════════════════════════════════════════════════════════════════
+/**
+ * Creates a formatted response complete event.
+ */
+export function createResponseCompleteEvent(sessionId, response) {
+    return createStreamEvent("response_complete", sessionId, { response });
+}
+/**
+ * Creates a formatted response reset event.
+ * Tells the frontend to discard all previously streamed tokens.
+ */
+export function createResponseResetEvent(sessionId, reason) {
+    return createStreamEvent("response_reset", sessionId, { reason });
+}
+/**
+ * Creates a hallucination detected event for the trace panel.
+ */
+export function createHallucinationDetectedEvent(sessionId, blockType, tool) {
+    return createStreamEvent("hallucination_detected", sessionId, { blockType, tool });
+}
+// ════════════════════════════════════════════════════════════════════════════
+// DEBUG META EVENT CREATORS
+// ════════════════════════════════════════════════════════════════════════════
+/**
+ * Creates a formatted debug meta event (per-turn graph and tool usage).
+ */
+export function createDebugMetaEvent(sessionId, graph, iterations, tools) {
+    return createStreamEvent("debug_meta", sessionId, {
+        graph,
+        iterations,
+        tools,
+    });
+}
+// ════════════════════════════════════════════════════════════════════════════
+// TRACE HIERARCHY EVENT CREATORS
+// ════════════════════════════════════════════════════════════════════════════
+/**
+ * Creates a graph start event emitted when a LangGraph sub-graph begins inside a tool.
+ */
+export function createGraphStartEvent(sessionId, graphName) {
+    return createStreamEvent("graph_start", sessionId, { graphName });
+}
+/**
+ * Creates a graph end event emitted when a LangGraph sub-graph completes.
+ */
+export function createGraphEndEvent(sessionId, graphName, durationMs) {
+    return createStreamEvent("graph_end", sessionId, { graphName, durationMs });
+}
+/**
+ * Creates an agent start event emitted when an LLM agent begins inside a graph node.
+ */
+export function createAgentStartEvent(sessionId, agentName) {
+    return createStreamEvent("agent_start", sessionId, { agentName });
+}
+/**
+ * Creates an agent end event emitted when an LLM agent completes.
+ */
+export function createAgentEndEvent(sessionId, agentName, durationMs, summary) {
+    return createStreamEvent("agent_end", sessionId, { agentName, durationMs, summary });
+}
+//# sourceMappingURL=chat-streaming.types.js.map

package/dist/types/chat-streaming.types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"chat-streaming.types.js","sourceRoot":"","sources":["../../src/types/chat-streaming.types.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@indexnetwork/protocol",
+  "version": "0.1.0",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": ["dist"],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "prepublishOnly": "bun run build"
+  },
+  "dependencies": {
+    "@langchain/core": "^1.1.17",
+    "@langchain/langgraph": "^1.1.2",
+    "@langchain/langgraph-checkpoint-postgres": "^1.0.0",
+    "@langchain/openai": "^1.2.3",
+    "@modelcontextprotocol/server": "^2.0.0-alpha.2",
+    "dotenv": "^16.3.1",
+    "zod": "^3.22.4"
+  },
+  "devDependencies": {
+    "@types/node": "^25.5.2",
+    "typescript": "^5.0.0"
+  }
+}