@indexnetwork/protocol 22.0.0-rc.499.1 → 64.0.0-rc.604.2

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

@@ -1,297 +0,0 @@
-/**
- * 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 {
-        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, llm, orchestratorNegotiations) {
-    return createStreamEvent("debug_meta", sessionId, {
-        graph,
-        iterations,
-        tools,
-        llm,
-        ...(orchestratorNegotiations !== undefined && { orchestratorNegotiations }),
-    });
-}
-// ════════════════════════════════════════════════════════════════════════════
-// 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 });
-}
-export function createPhaseStartEvent(sessionId, phaseName) {
-    return createStreamEvent("phase_start", sessionId, { phaseName });
-}
-export function createPhaseEndEvent(sessionId, phaseName, durationMs) {
-    return createStreamEvent("phase_end", sessionId, { phaseName, 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 });
-}
-export function createNegotiationSessionStartEvent(sessionId, payload) {
-    return createStreamEvent("negotiation_session_start", sessionId, payload);
-}
-export function createNegotiationSessionEndEvent(sessionId, payload) {
-    return createStreamEvent("negotiation_session_end", sessionId, payload);
-}
-export function createNegotiationTurnEvent(sessionId, payload) {
-    return createStreamEvent("negotiation_turn", sessionId, payload);
-}
-export function createNegotiationOutcomeEvent(sessionId, payload) {
-    return createStreamEvent("negotiation_outcome", sessionId, payload);
-}
-export function createChatSummarizerStartEvent(sessionId, payload) {
-    return createStreamEvent("chat_summarizer_start", sessionId, { payload });
-}
-export function createChatSummarizerEndEvent(sessionId, payload) {
-    return createStreamEvent("chat_summarizer_end", sessionId, { payload });
-}
-export function createDecisionQuestionsEvent(sessionId, payload) {
-    return createStreamEvent("decision_questions", sessionId, payload);
-}
-/**
- * Creates a steer-or-queue event injected into the active stream by the interrupt endpoint.
- */
-export function createSteerOrQueueEvent(sessionId, decision, messageId) {
-    return createStreamEvent("steer_or_queue", sessionId, {
-        decision,
-        messageId,
-    });
-}

package/dist/chat/chat.agent.d.ts

@@ -1,292 +0,0 @@
-import { BaseMessage } from "@langchain/core/messages";
-import type { ToolContext } from "../shared/agent/tool.factory.js";
-import type { ChatPersonaConfig } from "./chat.persona.js";
-import type { DebugMetaToolCall, DebugMetaLlm, DebugMetaOrchestratorNegotiations } from "./chat-streaming.types.js";
-import type { Question } from "../questions/question.module.js";
-export { ITERATION_NUDGE } from "./chat.prompt.js";
-/**
- * Writer callback for streaming custom data out of the graph node.
- * Matches the `config.writer` signature from LangGraphRunnableConfig.
- */
-export type StreamWriter = (data: unknown) => void;
-/**
- * Events emitted by `streamRun()` via the writer callback.
- *
- * - `iteration_start` — new agent loop iteration begins
- * - `llm_start`       — LLM begins generating response
- * - `text_chunk`      — a token (or group of tokens) of model text
- * - `llm_end`         — LLM finished generating (may have tool calls)
- * - `tool_activity`   — tool starts or finishes execution
- * - `graph_start`     — a LangGraph sub-graph begins inside a tool
- * - `graph_end`       — a LangGraph sub-graph completes
- * - `agent_start`     — an LLM agent begins inside a graph node
- * - `agent_end`       — an LLM agent completes
- */
-export type AgentStreamEvent = {
-    type: "iteration_start";
-    iteration: number;
-} | {
-    type: "llm_start";
-    iteration: number;
-} | {
-    type: "text_chunk";
-    content: string;
-} | {
-    type: "llm_end";
-    iteration: number;
-    hasToolCalls: boolean;
-    toolNames?: string[];
-} | {
-    type: "tool_activity";
-    phase: "start";
-    name: string;
-} | {
-    type: "tool_activity";
-    phase: "end";
-    name: string;
-    success: boolean;
-    summary?: string;
-    steps?: Array<{
-        step: string;
-        detail?: string;
-        data?: Record<string, unknown>;
-    }>;
-} | {
-    type: "response_reset";
-    reason: string;
-} | {
-    type: "hallucination_detected";
-    blockType: string;
-    tool: string;
-} | {
-    type: "graph_start";
-    name: string;
-} | {
-    type: "graph_end";
-    name: string;
-    durationMs: number;
-} | {
-    type: "phase_start";
-    name: string;
-} | {
-    type: "phase_end";
-    name: string;
-    durationMs: number;
-} | {
-    type: "agent_start";
-    name: string;
-} | {
-    type: "agent_end";
-    name: string;
-    durationMs: number;
-    summary: string;
-} | {
-    type: "negotiation_session_start";
-    opportunityId: string;
-    negotiationConversationId: string;
-    sourceUserId: string;
-    candidateUserId: string;
-    candidateName?: string;
-    startedAt: number;
-} | {
-    type: "negotiation_session_end";
-    opportunityId: string;
-    negotiationConversationId: string;
-    durationMs: number;
-} | {
-    type: "negotiation_turn";
-    opportunityId: string;
-    negotiationConversationId: string;
-    turnIndex: number;
-    actor: "source" | "candidate";
-    action: "propose" | "accept" | "reject" | "counter" | "question" | "outreach" | "withdraw" | "decline" | "ask_user";
-    reasoning?: string;
-    message?: string;
-    suggestedRoles?: {
-        ownUser?: string;
-        otherUser?: string;
-    };
-    durationMs: number;
-} | {
-    type: "negotiation_outcome";
-    opportunityId: string;
-    outcome: "accepted" | "rejected_stalled" | "waiting_for_agent" | "timed_out" | "turn_cap" | "screened_out";
-    turnCount: number;
-    reasoning?: string;
-    agreedRoles?: {
-        ownUser?: string;
-        otherUser?: string;
-    };
-} | {
-    type: "status";
-    message: string;
-} | {
-    type: "decision_questions";
-    questions: Question[];
-} | {
-    type: "chat_summarizer_start";
-    payload: {
-        sessionId: string;
-    };
-} | {
-    type: "chat_summarizer_end";
-    payload: {
-        durationMs: number;
-    };
-};
-/**
- * Soft limit: After this many iterations, inject a nudge message.
- */
-export declare const SOFT_ITERATION_LIMIT = 8;
-/**
- * Hard limit: Force exit after this many iterations to prevent infinite loops.
- */
-export declare const HARD_ITERATION_LIMIT = 12;
-/**
- * Result of a single agent iteration.
- */
-export interface AgentIterationResult {
-    /** Whether the agent wants to continue (made tool calls) or stop (produced final response) */
-    shouldContinue: boolean;
-    /** Tool calls made in this iteration (if any) */
-    toolCalls?: Array<{
-        id: string;
-        name: string;
-        args: Record<string, unknown>;
-    }>;
-    /** Tool results from executing the tool calls */
-    toolResults?: Array<{
-        toolCallId: string;
-        name: string;
-        result: string;
-    }>;
-    /** Final response text (if agent is done) */
-    responseText?: string;
-    /** Updated messages array */
-    messages: BaseMessage[];
-}
-/**
- * ChatAgent: ReAct-style agent that uses tools to help users.
- *
- * The agent operates in a loop:
- * 1. Receive messages (conversation history + tool results)
- * 2. Decide: call tools OR respond to user
- * 3. If tools called: execute them, add results, loop back
- * 4. If response: return final text
- *
- * Use `ChatAgent.create(context)` to construct (async factory).
- */
-export declare class ChatAgent {
-    private resolvedContext;
-    private persona;
-    private model;
-    private tools;
-    private toolsByName;
-    /**
-     * Private constructor — use `ChatAgent.create()` instead.
-     */
-    private constructor();
-    /**
-     * Extracts the text content of the most recent HumanMessage.
-     */
-    private static getCurrentUserMessage;
-    /**
-     * Async factory: creates a ChatAgent with resolved user/index context.
-     * Resolves user/network identity from DB during tool initialization.
-     *
-     * @param context - Tool context (database, userId, scope, deps)
-     * @param persona - Persona config (prompt builder, toolset, loop behaviors).
-     *                  Required — there is no default persona.
-     */
-    static create(context: ToolContext, persona: ChatPersonaConfig): Promise<ChatAgent>;
-    /**
-     * Run a single iteration of the agent loop.
-     *
-     * @param messages - Current conversation including any tool results
-     * @param iterationCount - Current iteration number (for soft limit)
-     * @returns Result indicating whether to continue and any tool calls/response
-     */
-    runIteration(messages: BaseMessage[], iterationCount: number): Promise<AgentIterationResult>;
-    /**
-     * Execute tool calls, potentially in parallel.
-     */
-    private executeToolCalls;
-    /**
-     * Check whether `list_opportunities` returned valid opportunity blocks.
-     * Persisted cards from that tool are the only valid source.
-     */
-    private static hasOpportunitySource;
-    /**
-     * Detect hallucinated ```intent_proposal or ```opportunity blocks in model text
-     * that were NOT generated by the corresponding tool call.
-     *
-     * A tool call that returned 0 cards (e.g. "Found 0 match(es)") counts as
-     * NOT having produced valid blocks — the LLM must not fabricate them.
-     *
-     * @returns Block info if hallucination detected, null otherwise
-     */
-    private detectHallucinatedBlock;
-    /**
-     * Strip ```opportunity and ```intent_proposal code blocks from text
-     * when no corresponding successful tool call was made.
-     * Defense-in-depth: catches hallucinated blocks that slip past detectHallucinatedBlock
-     * (e.g. after a correction iteration that still hallucinates).
-     *
-     * @param text - The response text to sanitize
-     * @param toolsUsed - Tool call records from the agent loop
-     * @returns Sanitized text with unbacked blocks removed
-     */
-    private stripUnbackedBlocks;
-    private static readonly PHANTOM_WRITE_PATTERNS;
-    /**
-     * Detect when the model claims to have performed a write action
-     * without having called any tools in the turn.
-     */
-    private static detectPhantomWrite;
-    private static readonly STEP_DETAIL_MAX;
-    private static readonly STEP_NAME_MAX;
-    /**
-     * Post-process a tool result: strip _graphTimings, extract summary/debugSteps,
-     * and optionally normalize a tool result before a create_intent callback.
-     *
-     * Returns the normalized result string and extracted debug metadata so both
-     * the normal streaming tool loop and the hallucination-recovery branch
-     * produce identical LLM-facing payloads.
-     */
-    private normalizeToolResult;
-    /**
-     * Run the full agent loop until completion or hard limit.
-     *
-     * @param initialMessages - Starting conversation messages
-     * @returns Final response text and full message history
-     */
-    run(initialMessages: BaseMessage[]): Promise<{
-        responseText: string;
-        messages: BaseMessage[];
-        iterationCount: number;
-    }>;
-    /**
-     * Run the full agent loop with streaming narration.
-     *
-     * Instead of returning a single blob at the end, this method calls
-     * `writer()` for every text token and tool-activity event so the
-     * consumer (graph node) can push them out via `config.writer`.
-     *
-     * @param initialMessages - Starting conversation messages
-     * @param writer - Callback to emit streaming events (from `config.writer`)
-     * @param signal - Optional AbortSignal to cancel the streaming LLM call and tool execution
-     * @returns Final response metadata (same shape as `run()`)
-     */
-    streamRun(initialMessages: BaseMessage[], writer?: StreamWriter, signal?: AbortSignal): Promise<{
-        responseText: string;
-        messages: BaseMessage[];
-        iterationCount: number;
-        debugMeta: {
-            graph: string;
-            iterations: number;
-            tools: DebugMetaToolCall[];
-            llm: DebugMetaLlm;
-            orchestratorNegotiations?: DebugMetaOrchestratorNegotiations;
-        };
-    }>;
-}