@carlonicora/nestjs-neo4jsonapi 1.97.0 → 1.98.0

package/dist/agents/operator/services/operator.service.js

@@ -0,0 +1,341 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var OperatorService_1;
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OperatorService = void 0;
+const messages_1 = require("@langchain/core/messages");
+const langgraph_1 = require("@langchain/langgraph");
+const common_1 = require("@nestjs/common");
+const config_1 = require("@nestjs/config");
+const zod_1 = require("zod");
+const agentmessage_type_1 = require("../../../common/enums/agentmessage.type");
+const llm_service_1 = require("../../../core/llm/services/llm.service");
+const operator_context_1 = require("../contexts/operator.context");
+const operator_system_prompt_1 = require("../prompts/operator.system.prompt");
+const operator_tool_registry_1 = require("../tools/operator.tool.registry");
+const operator_checkpointer_service_1 = require("./operator.checkpointer.service");
+/** Max agent⇄tools iterations before the run is forced to finalise. */
+const MAX_TOOL_ITERATIONS = 15;
+/** Graph recursion limit sized for ~15 tool iterations (agent + tools per iteration). */
+const RECURSION_LIMIT = 40;
+const finalAnswerSchema = zod_1.z.object({
+    answer: zod_1.z.string(),
+    questions: zod_1.z.array(zod_1.z.string()),
+});
+/**
+ * OperatorService - the operator agent graph (START → agent ⇄ tools → finalise → END).
+ *
+ * - `agent` node: exactly one model invocation with all tools bound (LLMService.callStep).
+ * - `tools` node: executes the tool calls of the last AI message. Destructive
+ *   calls are processed FIRST and freeze the run via `interrupt()` until the
+ *   user approves or denies — at most ONE destructive call per pass (extra
+ *   destructive calls get a "not executed" ToolMessage and must be re-issued);
+ *   read-only tool errors become `Tool error: ...` ToolMessages so the model
+ *   self-corrects (never thrown).
+ * - `finalise` node: one structured LLMService.call() producing the final
+ *   answer + suggested questions. References and citations are collected
+ *   deterministically from the tool-call recorder, never from the LLM.
+ *
+ * The graph is compiled per turn (tools are per-request closures) with the
+ * shared checkpoint saver; `resume()` recompiles identically and resumes the
+ * frozen thread with `new Command({ resume: { approved } })`.
+ */
+let OperatorService = OperatorService_1 = class OperatorService {
+    constructor(llm, toolRegistry, checkpointer, configService) {
+        this.llm = llm;
+        this.toolRegistry = toolRegistry;
+        this.checkpointer = checkpointer;
+        this.configService = configService;
+        this.logger = new common_1.Logger(OperatorService_1.name);
+        const prompts = this.configService.get("prompts");
+        this.systemPrompt = prompts?.operator ?? operator_system_prompt_1.defaultOperatorSystemPrompt;
+    }
+    async run(params) {
+        const app = await this.compileGraph({
+            companyId: params.companyId,
+            userId: params.userId,
+            userModuleIds: params.userModuleIds,
+            contentId: params.contentId,
+            contentType: params.contentType,
+            dataLimits: {},
+            messages: params.messages,
+        });
+        const initialState = {
+            messages: this.buildInitialMessages(params.messages, params.question),
+            companyId: params.companyId,
+            userId: params.userId,
+            userModuleIds: params.userModuleIds,
+            contentId: params.contentId ?? null,
+            contentType: params.contentType ?? null,
+            question: params.question,
+        };
+        const finalState = (await app.invoke(initialState, {
+            configurable: { thread_id: params.threadId },
+            recursionLimit: RECURSION_LIMIT,
+        }));
+        return this.mapResult(finalState);
+    }
+    async resume(params) {
+        const app = await this.compileGraph({
+            companyId: params.companyId,
+            userId: params.userId,
+            userModuleIds: params.userModuleIds,
+            contentId: params.contentId,
+            contentType: params.contentType,
+            dataLimits: {},
+            messages: params.messages ?? [],
+        });
+        const finalState = (await app.invoke(new langgraph_1.Command({ resume: { approved: params.approved } }), {
+            configurable: { thread_id: params.threadId },
+            recursionLimit: RECURSION_LIMIT,
+        }));
+        return this.mapResult(finalState);
+    }
+    async compileGraph(ctx) {
+        const saver = await this.checkpointer.getSaver();
+        // Per-compile recorder: tool wrappers (registry-built closures) push
+        // ToolCallRecords here. It accumulates for the lifetime of the compiled
+        // graph — tools enforce cross-call contracts (e.g. describe-before-read)
+        // by inspecting it, so the tools node must NEVER drain it; it only copies
+        // the records new to each pass into checkpointed state. The array identity
+        // is shared with the tool closures: push into it, never reassign it.
+        const recorder = [];
+        const definitions = this.toolRegistry.build(ctx, recorder);
+        const toolMap = new Map(definitions.map((d) => [d.tool.name, d]));
+        const tools = definitions.map((d) => d.tool);
+        const workflow = new langgraph_1.StateGraph(operator_context_1.OperatorContext)
+            .addNode("agent", async (state) => {
+            const response = await this.llm.callStep({
+                systemPrompts: [this.systemPrompt],
+                messages: state.messages,
+                tools,
+                // Deterministic tool-following: at the config-default temperature the
+                // model intermittently relays recoverable tool errors to the user
+                // instead of retrying (observed live with gemini-2.5-flash-lite).
+                temperature: 0,
+                metadata: { agent: "operator", node: "agent", companyId: state.companyId },
+            });
+            return {
+                messages: [response.message],
+                iterations: state.iterations + 1,
+                tokens: response.tokenUsage,
+            };
+        })
+            .addNode("tools", async (state) => {
+            // Read the calls from the last AI message in checkpointed state so the
+            // node is deterministic on replay after an interrupt.
+            const last = state.messages[state.messages.length - 1];
+            const calls = last?.tool_calls ?? [];
+            const isDestructive = (name) => toolMap.get(name)?.destructive === true;
+            // Prime the recorder from checkpointed state. `resume()` recompiles the
+            // graph with a fresh (empty) recorder, but state.toolCalls is the
+            // durable superset of everything recorded so far — restoring the
+            // missing records keeps cross-pass tool contracts (describe-before-read)
+            // satisfied after an approval round-trip. Idempotent on node replays.
+            if (recorder.length < state.toolCalls.length) {
+                recorder.push(...state.toolCalls.slice(recorder.length));
+            }
+            // Everything pushed beyond this index during this pass is new and is
+            // what gets emitted into state (the toolCalls reducer concats).
+            const startIdx = recorder.length;
+            // Ordering rule: destructive calls are processed BEFORE read-only
+            // siblings, so no sibling effects are duplicated by node replay.
+            // Exactly-once rule: at most ONE destructive call is interrupted and
+            // executed per tools-node pass. LangGraph replays the whole node on
+            // every resume — a second `interrupt()` after a side effect would
+            // re-run that side effect on the next resume. Every destructive call
+            // after the first gets a "not executed" ToolMessage so the model can
+            // re-issue it on the next agent iteration.
+            const ordered = [...calls.filter((c) => isDestructive(c.name)), ...calls.filter((c) => !isDestructive(c.name))];
+            const toolMessages = [];
+            let destructiveHandled = false;
+            for (const [index, call] of ordered.entries()) {
+                const callId = call.id ?? `call_${index}`;
+                const definition = toolMap.get(call.name);
+                if (!definition) {
+                    toolMessages.push(new messages_1.ToolMessage({ content: `Tool error: unknown tool "${call.name}".`, tool_call_id: callId }));
+                    continue;
+                }
+                if (definition.destructive) {
+                    if (destructiveHandled) {
+                        toolMessages.push(new messages_1.ToolMessage({
+                            content: "Not executed — one action per step. Re-issue this action after the current one resolves.",
+                            tool_call_id: callId,
+                        }));
+                        continue;
+                    }
+                    destructiveHandled = true;
+                    const payload = {
+                        toolName: call.name,
+                        toolArgs: (call.args ?? {}),
+                        summary: definition.summarise?.(call.args ?? {}) ?? `${call.name}(${JSON.stringify(call.args ?? {})})`,
+                    };
+                    const decision = (0, langgraph_1.interrupt)(payload);
+                    if (!decision?.approved) {
+                        toolMessages.push(new messages_1.ToolMessage({ content: "Action denied by the user.", tool_call_id: callId }));
+                        continue;
+                    }
+                }
+                try {
+                    const result = await definition.tool.invoke(call.args ?? {});
+                    toolMessages.push(new messages_1.ToolMessage({
+                        content: typeof result === "string" ? result : JSON.stringify(result),
+                        tool_call_id: callId,
+                    }));
+                }
+                catch (err) {
+                    const message = err instanceof Error ? err.message : String(err);
+                    this.logger.warn(`operator tool "${call.name}" failed: ${message}`);
+                    toolMessages.push(new messages_1.ToolMessage({ content: `Tool error: ${message}`, tool_call_id: callId }));
+                }
+            }
+            // Only the records new to this pass go into state; re-deriving over
+            // primed records would duplicate toolCalls/references/citations
+            // because the state reducers concat.
+            const newRecords = recorder.slice(startIdx);
+            return {
+                messages: toolMessages,
+                toolCalls: newRecords,
+                references: this.collectReferences(newRecords),
+                citations: this.collectCitations(newRecords),
+            };
+        })
+            .addNode("finalise", async (state) => {
+            const transcript = state.messages
+                .map((m) => {
+                const content = typeof m.content === "string" ? m.content : JSON.stringify(m.content);
+                // AIMessages that only carry tool_calls stringify empty; surface the
+                // requested calls so cap-terminated runs expose the unfinished intent.
+                const toolCalls = m.tool_calls;
+                const requested = Array.isArray(toolCalls) && toolCalls.length > 0
+                    ? `${content ? " " : ""}[requested tools: ${toolCalls
+                        .map((c) => `${c.name}(${JSON.stringify(c.args ?? {})})`)
+                        .join(", ")}]`
+                    : "";
+                return `${m.getType()}: ${content}${requested}`;
+            })
+                .join("\n");
+            const result = await this.llm.call({
+                inputParams: { question: state.question, conversation: transcript },
+                outputSchema: finalAnswerSchema,
+                systemPrompts: [this.systemPrompt],
+                // LLMService.call() renders inputParams ONLY through {placeholder}
+                // substitution in this template — params without a matching
+                // placeholder are silently dropped and the model never sees them.
+                instructions: "The user asked:\n{question}\n\n" +
+                    "This is the full conversation of the operator run that just finished (model turns, tool calls and tool results):\n\n{conversation}\n\n" +
+                    "Produce the final reply: `answer` is the message for the user (built only from facts in the conversation above), `questions` is up to three short follow-up questions the user might ask next. " +
+                    "If the conversation contains no tool results that answer the question, `answer` must say plainly that the information could not be found — do not guess and do not invent records. " +
+                    "Never state that an action was performed (created, updated, deleted, executed) unless a tool result in the conversation confirms that exact action.",
+                metadata: { agent: "operator", node: "finalise", companyId: state.companyId },
+            });
+            return {
+                finalAnswer: { answer: result.answer ?? "", questions: result.questions ?? [] },
+                tokens: result.tokenUsage,
+            };
+        })
+            .addEdge(langgraph_1.START, "agent")
+            .addConditionalEdges("agent", (state) => {
+            const last = state.messages[state.messages.length - 1];
+            const hasToolCalls = Array.isArray(last?.tool_calls) && last.tool_calls.length > 0;
+            return hasToolCalls && state.iterations < MAX_TOOL_ITERATIONS ? "tools" : "finalise";
+        }, ["tools", "finalise"])
+            .addEdge("tools", "agent")
+            .addEdge("finalise", langgraph_1.END);
+        return workflow.compile({ checkpointer: saver });
+    }
+    /** Entity references derived deterministically from the tool-call recorder (never from the LLM). */
+    collectReferences(records) {
+        const references = [];
+        const seen = new Set();
+        const push = (type, id, reason) => {
+            if (typeof type !== "string" || typeof id !== "string" || !type || !id)
+                return;
+            const key = `${type}:${id}`;
+            if (seen.has(key))
+                return;
+            seen.add(key);
+            references.push({ type, id, relevance: 100, reason });
+        };
+        for (const record of records) {
+            if (record.error)
+                continue;
+            if (record.tool === "read_entity") {
+                push(record.input.type, record.input.id, "record read during the operator run");
+            }
+            else if (record.tool === "traverse") {
+                push(record.input.fromType, record.input.fromId, "record traversed during the operator run");
+            }
+        }
+        return references;
+    }
+    /** Chunk citations recorded by retrieval tool wrappers into the recorder. */
+    collectCitations(records) {
+        const citations = [];
+        for (const record of records) {
+            for (const citation of record.citations ?? []) {
+                citations.push({
+                    chunkId: citation.chunkId,
+                    relevance: citation.relevance,
+                    reason: `retrieved by ${record.tool}`,
+                });
+            }
+        }
+        return citations;
+    }
+    buildInitialMessages(messages, question) {
+        const converted = messages.map((m) => {
+            switch (m.type) {
+                case agentmessage_type_1.AgentMessageType.System:
+                    return new messages_1.SystemMessage(m.content);
+                case agentmessage_type_1.AgentMessageType.Assistant:
+                    return new messages_1.AIMessage(m.content);
+                default:
+                    return new messages_1.HumanMessage(m.content);
+            }
+        });
+        const last = converted[converted.length - 1];
+        if (!last || last.getType() !== "human" || last.content !== question) {
+            converted.push(new messages_1.HumanMessage(question));
+        }
+        return converted;
+    }
+    mapResult(finalState) {
+        const interrupts = finalState.__interrupt__;
+        if (interrupts && interrupts.length > 0) {
+            const payload = interrupts[0]?.value ?? {};
+            return {
+                kind: "pending_approval",
+                toolName: payload.toolName ?? "",
+                toolArgs: payload.toolArgs ?? {},
+                summary: payload.summary ?? "",
+            };
+        }
+        return {
+            kind: "completed",
+            answer: finalState.finalAnswer?.answer ?? "",
+            questions: finalState.finalAnswer?.questions ?? [],
+            references: finalState.references ?? [],
+            citations: finalState.citations ?? [],
+            toolCalls: finalState.toolCalls ?? [],
+            tokens: finalState.tokens ?? { input: 0, output: 0 },
+        };
+    }
+};
+exports.OperatorService = OperatorService;
+exports.OperatorService = OperatorService = OperatorService_1 = __decorate([
+    (0, common_1.Injectable)(),
+    __metadata("design:paramtypes", [llm_service_1.LLMService,
+        operator_tool_registry_1.OperatorToolRegistry,
+        operator_checkpointer_service_1.OperatorCheckpointerService,
+        config_1.ConfigService])
+], OperatorService);
+//# sourceMappingURL=operator.service.js.map

package/dist/agents/operator/services/operator.service.js.map

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

package/dist/agents/operator/tools/operator-test-action.tool.d.ts

@@ -0,0 +1,12 @@
+import { ToolCallRecord, ToolFactory } from "../../graph/tools/tool.factory";
+import { OperatorToolDefinition } from "../interfaces/operator.tool.interface";
+/**
+ * Test-only destructive tool: echoes its note as "executed". Used to exercise
+ * the approval-gate flow end to end. Registered only when NODE_ENV !== "production".
+ */
+export declare class OperatorTestActionTool {
+    private readonly factory;
+    constructor(factory: ToolFactory);
+    buildDefinition(recorder: ToolCallRecord[]): OperatorToolDefinition;
+}
+//# sourceMappingURL=operator-test-action.tool.d.ts.map

package/dist/agents/operator/tools/operator-test-action.tool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"operator-test-action.tool.d.ts","sourceRoot":"","sources":["../../../../src/agents/operator/tools/operator-test-action.tool.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,gCAAgC,CAAC;AAC7E,OAAO,EAAE,sBAAsB,EAAE,MAAM,uCAAuC,CAAC;AAM/E;;;GAGG;AACH,qBACa,sBAAsB;IACrB,OAAO,CAAC,QAAQ,CAAC,OAAO;gBAAP,OAAO,EAAE,WAAW;IAEjD,eAAe,CAAC,QAAQ,EAAE,cAAc,EAAE,GAAG,sBAAsB;CAkBpE"}

package/dist/agents/operator/tools/operator-test-action.tool.js

@@ -0,0 +1,46 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OperatorTestActionTool = void 0;
+const tools_1 = require("@langchain/core/tools");
+const common_1 = require("@nestjs/common");
+const zod_1 = require("zod");
+const tool_factory_1 = require("../../graph/tools/tool.factory");
+const inputSchema = zod_1.z.object({
+    note: zod_1.z.string().describe("A short note describing the test action to execute."),
+});
+/**
+ * Test-only destructive tool: echoes its note as "executed". Used to exercise
+ * the approval-gate flow end to end. Registered only when NODE_ENV !== "production".
+ */
+let OperatorTestActionTool = class OperatorTestActionTool {
+    constructor(factory) {
+        this.factory = factory;
+    }
+    buildDefinition(recorder) {
+        return {
+            tool: new tools_1.DynamicStructuredTool({
+                name: "operator_test_action",
+                description: "Execute a test action (development/test environments only). This action requires user approval before it runs.",
+                schema: inputSchema,
+                func: async (input) => this.factory.capture({ tool: "operator_test_action", input }, async () => `Executed test action: ${input.note}`, recorder),
+            }),
+            destructive: true,
+            summarise: (args) => `Run test action: ${args.note}`,
+        };
+    }
+};
+exports.OperatorTestActionTool = OperatorTestActionTool;
+exports.OperatorTestActionTool = OperatorTestActionTool = __decorate([
+    (0, common_1.Injectable)(),
+    __metadata("design:paramtypes", [tool_factory_1.ToolFactory])
+], OperatorTestActionTool);
+//# sourceMappingURL=operator-test-action.tool.js.map

package/dist/agents/operator/tools/operator-test-action.tool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"operator-test-action.tool.js","sourceRoot":"","sources":["../../../../src/agents/operator/tools/operator-test-action.tool.ts"],"names":[],"mappings":";;;;;;;;;;;;AAAA,iDAA8D;AAC9D,2CAA4C;AAC5C,6BAAwB;AACxB,iEAA6E;AAG7E,MAAM,WAAW,GAAG,OAAC,CAAC,MAAM,CAAC;IAC3B,IAAI,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,qDAAqD,CAAC;CACjF,CAAC,CAAC;AAEH;;;GAGG;AAEI,IAAM,sBAAsB,GAA5B,MAAM,sBAAsB;IACjC,YAA6B,OAAoB;QAApB,YAAO,GAAP,OAAO,CAAa;IAAG,CAAC;IAErD,eAAe,CAAC,QAA0B;QACxC,OAAO;YACL,IAAI,EAAE,IAAI,6BAAqB,CAAC;gBAC9B,IAAI,EAAE,sBAAsB;gBAC5B,WAAW,EACT,gHAAgH;gBAClH,MAAM,EAAE,WAAW;gBACnB,IAAI,EAAE,KAAK,EAAE,KAAkC,EAAE,EAAE,CACjD,IAAI,CAAC,OAAO,CAAC,OAAO,CAClB,EAAE,IAAI,EAAE,sBAAsB,EAAE,KAAK,EAAE,EACvC,KAAK,IAAI,EAAE,CAAC,yBAAyB,KAAK,CAAC,IAAI,EAAE,EACjD,QAAQ,CACT;aACJ,CAAC;YACF,WAAW,EAAE,IAAI;YACjB,SAAS,EAAE,CAAC,IAA6B,EAAE,EAAE,CAAC,oBAAoB,IAAI,CAAC,IAAI,EAAE;SAC9E,CAAC;IACJ,CAAC;CACF,CAAA;AArBY,wDAAsB;iCAAtB,sBAAsB;IADlC,IAAA,mBAAU,GAAE;qCAE2B,0BAAW;GADtC,sBAAsB,CAqBlC"}

package/dist/agents/operator/tools/operator.tool.registry.d.ts

@@ -0,0 +1,32 @@
+import { DescribeEntityTool } from "../../graph/tools/describe-entity.tool";
+import { ReadEntityTool } from "../../graph/tools/read-entity.tool";
+import { ResolveEntityTool } from "../../graph/tools/resolve-entity.tool";
+import { SearchEntitiesTool } from "../../graph/tools/search-entities.tool";
+import { ToolCallRecord } from "../../graph/tools/tool.factory";
+import { TraverseTool } from "../../graph/tools/traverse.tool";
+import { OperatorRetrievalContext, OperatorToolContribution, OperatorToolDefinition } from "../interfaces/operator.tool.interface";
+import { OperatorTestActionTool } from "./operator-test-action.tool";
+import { SearchCommunitiesTool } from "./search-communities.tool";
+import { SearchDocumentsTool } from "./search-documents.tool";
+/**
+ * Composes the operator's tool set for a single turn:
+ * - the five graph tools (read-only, built per request with ctx + recorder)
+ * - the two retrieval tools (search_documents, search_communities)
+ * - the test-only destructive tool (non-production environments only)
+ * - any app-contributed factories registered under the OPERATOR_TOOLS token,
+ *   built per turn with the same ctx + recorder as the built-ins
+ */
+export declare class OperatorToolRegistry {
+    private readonly resolveEntityTool;
+    private readonly describeEntityTool;
+    private readonly searchEntitiesTool;
+    private readonly readEntityTool;
+    private readonly traverseTool;
+    private readonly searchDocumentsTool;
+    private readonly searchCommunitiesTool;
+    private readonly operatorTestActionTool;
+    private readonly contributed?;
+    constructor(resolveEntityTool: ResolveEntityTool, describeEntityTool: DescribeEntityTool, searchEntitiesTool: SearchEntitiesTool, readEntityTool: ReadEntityTool, traverseTool: TraverseTool, searchDocumentsTool: SearchDocumentsTool, searchCommunitiesTool: SearchCommunitiesTool, operatorTestActionTool: OperatorTestActionTool, contributed?: OperatorToolContribution[]);
+    build(ctx: OperatorRetrievalContext, recorder: ToolCallRecord[]): OperatorToolDefinition[];
+}
+//# sourceMappingURL=operator.tool.registry.d.ts.map

package/dist/agents/operator/tools/operator.tool.registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"operator.tool.registry.d.ts","sourceRoot":"","sources":["../../../../src/agents/operator/tools/operator.tool.registry.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,kBAAkB,EAAE,MAAM,wCAAwC,CAAC;AAC5E,OAAO,EAAE,cAAc,EAAE,MAAM,oCAAoC,CAAC;AACpE,OAAO,EAAE,iBAAiB,EAAE,MAAM,uCAAuC,CAAC;AAC1E,OAAO,EAAE,kBAAkB,EAAE,MAAM,wCAAwC,CAAC;AAC5E,OAAO,EAAE,cAAc,EAAe,MAAM,gCAAgC,CAAC;AAC7E,OAAO,EAAE,YAAY,EAAE,MAAM,iCAAiC,CAAC;AAC/D,OAAO,EAEL,wBAAwB,EACxB,wBAAwB,EACxB,sBAAsB,EACvB,MAAM,uCAAuC,CAAC;AAC/C,OAAO,EAAE,sBAAsB,EAAE,MAAM,6BAA6B,CAAC;AACrE,OAAO,EAAE,qBAAqB,EAAE,MAAM,2BAA2B,CAAC;AAClE,OAAO,EAAE,mBAAmB,EAAE,MAAM,yBAAyB,CAAC;AAE9D;;;;;;;GAOG;AACH,qBACa,oBAAoB;IAE7B,OAAO,CAAC,QAAQ,CAAC,iBAAiB;IAClC,OAAO,CAAC,QAAQ,CAAC,kBAAkB;IACnC,OAAO,CAAC,QAAQ,CAAC,kBAAkB;IACnC,OAAO,CAAC,QAAQ,CAAC,cAAc;IAC/B,OAAO,CAAC,QAAQ,CAAC,YAAY;IAC7B,OAAO,CAAC,QAAQ,CAAC,mBAAmB;IACpC,OAAO,CAAC,QAAQ,CAAC,qBAAqB;IACtC,OAAO,CAAC,QAAQ,CAAC,sBAAsB;IACH,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAC;gBARhD,iBAAiB,EAAE,iBAAiB,EACpC,kBAAkB,EAAE,kBAAkB,EACtC,kBAAkB,EAAE,kBAAkB,EACtC,cAAc,EAAE,cAAc,EAC9B,YAAY,EAAE,YAAY,EAC1B,mBAAmB,EAAE,mBAAmB,EACxC,qBAAqB,EAAE,qBAAqB,EAC5C,sBAAsB,EAAE,sBAAsB,EACV,WAAW,CAAC,EAAE,wBAAwB,EAAE;IAG/F,KAAK,CAAC,GAAG,EAAE,wBAAwB,EAAE,QAAQ,EAAE,cAAc,EAAE,GAAG,sBAAsB,EAAE;CAyC3F"}

package/dist/agents/operator/tools/operator.tool.registry.js

@@ -0,0 +1,95 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OperatorToolRegistry = void 0;
+const common_1 = require("@nestjs/common");
+const describe_entity_tool_1 = require("../../graph/tools/describe-entity.tool");
+const read_entity_tool_1 = require("../../graph/tools/read-entity.tool");
+const resolve_entity_tool_1 = require("../../graph/tools/resolve-entity.tool");
+const search_entities_tool_1 = require("../../graph/tools/search-entities.tool");
+const traverse_tool_1 = require("../../graph/tools/traverse.tool");
+const operator_tool_interface_1 = require("../interfaces/operator.tool.interface");
+const operator_test_action_tool_1 = require("./operator-test-action.tool");
+const search_communities_tool_1 = require("./search-communities.tool");
+const search_documents_tool_1 = require("./search-documents.tool");
+/**
+ * Composes the operator's tool set for a single turn:
+ * - the five graph tools (read-only, built per request with ctx + recorder)
+ * - the two retrieval tools (search_documents, search_communities)
+ * - the test-only destructive tool (non-production environments only)
+ * - any app-contributed factories registered under the OPERATOR_TOOLS token,
+ *   built per turn with the same ctx + recorder as the built-ins
+ */
+let OperatorToolRegistry = class OperatorToolRegistry {
+    constructor(resolveEntityTool, describeEntityTool, searchEntitiesTool, readEntityTool, traverseTool, searchDocumentsTool, searchCommunitiesTool, operatorTestActionTool, contributed) {
+        this.resolveEntityTool = resolveEntityTool;
+        this.describeEntityTool = describeEntityTool;
+        this.searchEntitiesTool = searchEntitiesTool;
+        this.readEntityTool = readEntityTool;
+        this.traverseTool = traverseTool;
+        this.searchDocumentsTool = searchDocumentsTool;
+        this.searchCommunitiesTool = searchCommunitiesTool;
+        this.operatorTestActionTool = operatorTestActionTool;
+        this.contributed = contributed;
+    }
+    build(ctx, recorder) {
+        const userCtx = {
+            companyId: ctx.companyId,
+            userId: ctx.userId,
+            userModuleIds: ctx.userModuleIds,
+        };
+        const definitions = [
+            { tool: this.resolveEntityTool.build(userCtx, recorder), destructive: false },
+            { tool: this.describeEntityTool.build(userCtx, recorder), destructive: false },
+            { tool: this.searchEntitiesTool.build(userCtx, recorder), destructive: false },
+            { tool: this.readEntityTool.build(userCtx, recorder), destructive: false },
+            { tool: this.traverseTool.build(userCtx, recorder), destructive: false },
+            { tool: this.searchDocumentsTool.build(ctx, recorder), destructive: false },
+            { tool: this.searchCommunitiesTool.build(recorder), destructive: false },
+        ];
+        if (process.env.NODE_ENV !== "production") {
+            definitions.push(this.operatorTestActionTool.buildDefinition(recorder));
+        }
+        // Contributions are factories: build them per turn so they receive the
+        // request context (company scoping) and the shared tool-call recorder.
+        const all = [...definitions, ...(this.contributed ?? []).map((contribution) => contribution.build(ctx, recorder))];
+        // Guard against name collisions: a contributed tool named like a built-in
+        // would silently shadow it in the service's toolMap while both get bound to the model.
+        const seen = new Set();
+        for (const definition of all) {
+            const name = definition.tool.name;
+            if (seen.has(name)) {
+                throw new Error(`OperatorToolRegistry: duplicate tool name "${name}". ` +
+                    `A contributed OPERATOR_TOOLS contribution must not reuse the name of a built-in or another contributed tool.`);
+            }
+            seen.add(name);
+        }
+        return all;
+    }
+};
+exports.OperatorToolRegistry = OperatorToolRegistry;
+exports.OperatorToolRegistry = OperatorToolRegistry = __decorate([
+    (0, common_1.Injectable)(),
+    __param(8, (0, common_1.Optional)()),
+    __param(8, (0, common_1.Inject)(operator_tool_interface_1.OPERATOR_TOOLS)),
+    __metadata("design:paramtypes", [resolve_entity_tool_1.ResolveEntityTool,
+        describe_entity_tool_1.DescribeEntityTool,
+        search_entities_tool_1.SearchEntitiesTool,
+        read_entity_tool_1.ReadEntityTool,
+        traverse_tool_1.TraverseTool,
+        search_documents_tool_1.SearchDocumentsTool,
+        search_communities_tool_1.SearchCommunitiesTool,
+        operator_test_action_tool_1.OperatorTestActionTool, Array])
+], OperatorToolRegistry);
+//# sourceMappingURL=operator.tool.registry.js.map

package/dist/agents/operator/tools/operator.tool.registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"operator.tool.registry.js","sourceRoot":"","sources":["../../../../src/agents/operator/tools/operator.tool.registry.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;AAAA,2CAA8D;AAC9D,iFAA4E;AAC5E,yEAAoE;AACpE,+EAA0E;AAC1E,iFAA4E;AAE5E,mEAA+D;AAC/D,mFAK+C;AAC/C,2EAAqE;AACrE,uEAAkE;AAClE,mEAA8D;AAE9D;;;;;;;GAOG;AAEI,IAAM,oBAAoB,GAA1B,MAAM,oBAAoB;IAC/B,YACmB,iBAAoC,EACpC,kBAAsC,EACtC,kBAAsC,EACtC,cAA8B,EAC9B,YAA0B,EAC1B,mBAAwC,EACxC,qBAA4C,EAC5C,sBAA8C,EACV,WAAwC;QAR5E,sBAAiB,GAAjB,iBAAiB,CAAmB;QACpC,uBAAkB,GAAlB,kBAAkB,CAAoB;QACtC,uBAAkB,GAAlB,kBAAkB,CAAoB;QACtC,mBAAc,GAAd,cAAc,CAAgB;QAC9B,iBAAY,GAAZ,YAAY,CAAc;QAC1B,wBAAmB,GAAnB,mBAAmB,CAAqB;QACxC,0BAAqB,GAArB,qBAAqB,CAAuB;QAC5C,2BAAsB,GAAtB,sBAAsB,CAAwB;QACV,gBAAW,GAAX,WAAW,CAA6B;IAC5F,CAAC;IAEJ,KAAK,CAAC,GAA6B,EAAE,QAA0B;QAC7D,MAAM,OAAO,GAAgB;YAC3B,SAAS,EAAE,GAAG,CAAC,SAAS;YACxB,MAAM,EAAE,GAAG,CAAC,MAAM;YAClB,aAAa,EAAE,GAAG,CAAC,aAAa;SACjC,CAAC;QAEF,MAAM,WAAW,GAA6B;YAC5C,EAAE,IAAI,EAAE,IAAI,CAAC,iBAAiB,CAAC,KAAK,CAAC,OAAO,EAAE,QAAQ,CAAC,EAAE,WAAW,EAAE,KAAK,EAAE;YAC7E,EAAE,IAAI,EAAE,IAAI,CAAC,kBAAkB,CAAC,KAAK,CAAC,OAAO,EAAE,QAAQ,CAAC,EAAE,WAAW,EAAE,KAAK,EAAE;YAC9E,EAAE,IAAI,EAAE,IAAI,CAAC,kBAAkB,CAAC,KAAK,CAAC,OAAO,EAAE,QAAQ,CAAC,EAAE,WAAW,EAAE,KAAK,EAAE;YAC9E,EAAE,IAAI,EAAE,IAAI,CAAC,cAAc,CAAC,KAAK,CAAC,OAAO,EAAE,QAAQ,CAAC,EAAE,WAAW,EAAE,KAAK,EAAE;YAC1E,EAAE,IAAI,EAAE,IAAI,CAAC,YAAY,CAAC,KAAK,CAAC,OAAO,EAAE,QAAQ,CAAC,EAAE,WAAW,EAAE,KAAK,EAAE;YACxE,EAAE,IAAI,EAAE,IAAI,CAAC,mBAAmB,CAAC,KAAK,CAAC,GAAG,EAAE,QAAQ,CAAC,EAAE,WAAW,EAAE,KAAK,EAAE;YAC3E,EAAE,IAAI,EAAE,IAAI,CAAC,qBAAqB,CAAC,KAAK,CAAC,QAAQ,CAAC,EAAE,WAAW,EAAE,KAAK,EAAE;SACzE,CAAC;QAEF,IAAI,OAAO,CAAC,GAAG,CAAC,QAAQ,KAAK,YAAY,EAAE,CAAC;YAC1C,WAAW,CAAC,IAAI,CAAC,IAAI,CAAC,sBAAsB,CAAC,eAAe,CAAC,QAAQ,CAAC,CAAC,CAAC;QAC1E,CAAC;QAED,uEAAuE;QACvE,uEAAuE;QACvE,MAAM,GAAG,GAAG,CAAC,GAAG,WAAW,EAAE,GAAG,CAAC,IAAI,CAAC,WAAW,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,YAAY,EAAE,EAAE,CAAC,YAAY,CAAC,KAAK,CAAC,GAAG,EAAE,QAAQ,CAAC,CAAC,CAAC,CAAC;QAEnH,0EAA0E;QAC1E,uFAAuF;QACvF,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC;QAC/B,KAAK,MAAM,UAAU,IAAI,GAAG,EAAE,CAAC;YAC7B,MAAM,IAAI,GAAG,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC;YAClC,IAAI,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC;gBACnB,MAAM,IAAI,KAAK,CACb,8CAA8C,IAAI,KAAK;oBACrD,8GAA8G,CACjH,CAAC;YACJ,CAAC;YACD,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QACjB,CAAC;QAED,OAAO,GAAG,CAAC;IACb,CAAC;CACF,CAAA;AAtDY,oDAAoB;+BAApB,oBAAoB;IADhC,IAAA,mBAAU,GAAE;IAWR,WAAA,IAAA,iBAAQ,GAAE,CAAA;IAAE,WAAA,IAAA,eAAM,EAAC,wCAAc,CAAC,CAAA;qCARC,uCAAiB;QAChB,yCAAkB;QAClB,yCAAkB;QACtB,iCAAc;QAChB,4BAAY;QACL,2CAAmB;QACjB,+CAAqB;QACpB,kDAAsB;GATtD,oBAAoB,CAsDhC"}

package/dist/agents/operator/tools/search-communities.tool.d.ts

@@ -0,0 +1,16 @@
+import { DynamicStructuredTool } from "@langchain/core/tools";
+import { z } from "zod";
+import { DriftSearchService } from "../../drift/services/drift.search.service";
+import { ToolCallRecord, ToolFactory } from "../../graph/tools/tool.factory";
+declare const inputSchema: z.ZodObject<{
+    question: z.ZodString;
+}, z.core.$strip>;
+export declare class SearchCommunitiesTool {
+    private readonly factory;
+    private readonly driftSearchService;
+    constructor(factory: ToolFactory, driftSearchService: DriftSearchService);
+    build(recorder: ToolCallRecord[]): DynamicStructuredTool;
+    invoke(input: z.infer<typeof inputSchema>, recorder: ToolCallRecord[]): Promise<string>;
+}
+export {};
+//# sourceMappingURL=search-communities.tool.d.ts.map

package/dist/agents/operator/tools/search-communities.tool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"search-communities.tool.d.ts","sourceRoot":"","sources":["../../../../src/agents/operator/tools/search-communities.tool.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AAE9D,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,kBAAkB,EAAE,MAAM,2CAA2C,CAAC;AAC/E,OAAO,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,gCAAgC,CAAC;AAE7E,QAAA,MAAM,WAAW;;iBAEf,CAAC;AAMH,qBACa,qBAAqB;IAE9B,OAAO,CAAC,QAAQ,CAAC,OAAO;IACxB,OAAO,CAAC,QAAQ,CAAC,kBAAkB;gBADlB,OAAO,EAAE,WAAW,EACpB,kBAAkB,EAAE,kBAAkB;IAGzD,KAAK,CAAC,QAAQ,EAAE,cAAc,EAAE,GAAG,qBAAqB;IAUlD,MAAM,CAAC,KAAK,EAAE,CAAC,CAAC,KAAK,CAAC,OAAO,WAAW,CAAC,EAAE,QAAQ,EAAE,cAAc,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC;CAW9F"}