@indexnetwork/protocol 0.1.0

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

@@ -0,0 +1,218 @@
+import { BaseMessage } from "@langchain/core/messages";
+import { type ToolContext } from "../tools/index.js";
+import type { DebugMetaToolCall } from "../types/chat-streaming.types.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: "agent_start";
+    name: string;
+} | {
+    type: "agent_end";
+    name: string;
+    durationMs: number;
+    summary: string;
+};
+/**
+ * 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 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/index identity from DB during tool initialization.
+     */
+    static create(context: ToolContext): 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;
+    /**
+     * When create_opportunities returned createIntentSuggested, call create_intent then create_opportunities.
+     * Returns the new create_opportunities result string or null if no callback / create_intent failed.
+     */
+    private handleCreateIntentCallback;
+    /**
+     * 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 STEP_DETAIL_MAX;
+    private static readonly STEP_NAME_MAX;
+    /**
+     * Post-process a tool result: strip _graphTimings, extract summary/debugSteps,
+     * and optionally run create_opportunities → 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[];
+        };
+    }>;
+}
+//# sourceMappingURL=chat.agent.d.ts.map

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

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