@carlonicora/nestjs-neo4jsonapi 1.97.0 → 1.98.0

package/dist/agents/operator/controllers/operator.controller.js.map

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

package/dist/agents/operator/entities/operator.meta.d.ts

@@ -0,0 +1,8 @@
+import { DataMeta } from "../../../common/interfaces/datamodel.interface";
+/**
+ * Non-entity meta for the standalone operator endpoints (mirrors `authMeta`):
+ * the operator module exposes routes but has no Neo4j node of its own — the
+ * persisted resources are Assistants / AssistantMessages / AssistantActions.
+ */
+export declare const operatorMeta: DataMeta;
+//# sourceMappingURL=operator.meta.d.ts.map

package/dist/agents/operator/entities/operator.meta.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"operator.meta.d.ts","sourceRoot":"","sources":["../../../../src/agents/operator/entities/operator.meta.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,gDAAgD,CAAC;AAE1E;;;;GAIG;AACH,eAAO,MAAM,YAAY,EAAE,QAK1B,CAAC"}

package/dist/agents/operator/entities/operator.meta.js

@@ -0,0 +1,15 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.operatorMeta = void 0;
+/**
+ * Non-entity meta for the standalone operator endpoints (mirrors `authMeta`):
+ * the operator module exposes routes but has no Neo4j node of its own — the
+ * persisted resources are Assistants / AssistantMessages / AssistantActions.
+ */
+exports.operatorMeta = {
+    type: "operator",
+    endpoint: "operator",
+    nodeName: "operator",
+    labelName: "Operator",
+};
+//# sourceMappingURL=operator.meta.js.map

package/dist/agents/operator/entities/operator.meta.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"operator.meta.js","sourceRoot":"","sources":["../../../../src/agents/operator/entities/operator.meta.ts"],"names":[],"mappings":";;;AAEA;;;;GAIG;AACU,QAAA,YAAY,GAAa;IACpC,IAAI,EAAE,UAAU;IAChB,QAAQ,EAAE,UAAU;IACpB,QAAQ,EAAE,UAAU;IACpB,SAAS,EAAE,UAAU;CACtB,CAAC"}

package/dist/agents/operator/interfaces/operator.tool.interface.d.ts

@@ -0,0 +1,42 @@
+import { DynamicStructuredTool } from "@langchain/core/tools";
+import { MessageInterface } from "../../../common/interfaces/message.interface";
+import { DataLimits } from "../../../common/types/data.limits";
+import { ToolCallRecord, UserContext } from "../../graph/tools/tool.factory";
+export interface OperatorToolDefinition {
+    tool: DynamicStructuredTool;
+    destructive: boolean;
+    /** Human-readable line shown in the approval card. Required when destructive. */
+    summarise?: (args: Record<string, unknown>) => string;
+}
+/** Chunk citation pushed into the per-turn recorder by retrieval tools. */
+export interface OperatorChunkCitation {
+    chunkId: string;
+    relevance: number;
+}
+/**
+ * ToolCallRecord extended with the chunk citations a retrieval tool collected.
+ * Kept additive (operator-local) so the graph tools' recorder type is untouched.
+ */
+export interface OperatorToolCallRecord extends ToolCallRecord {
+    citations?: OperatorChunkCitation[];
+}
+/** Per-turn context the operator retrieval tools are built with. */
+export interface OperatorRetrievalContext extends UserContext {
+    contentId?: string;
+    contentType?: string;
+    dataLimits: DataLimits;
+    messages: MessageInterface[];
+}
+/**
+ * Factory contract for app-contributed operator tools.
+ * Built once per operator turn — like the built-ins — so contributed tools can
+ * apply company scoping from the request context and record their calls into
+ * the per-turn toolCalls audit trail.
+ */
+export interface OperatorToolContribution {
+    /** Called once per operator turn with the request context and the per-turn tool-call recorder. */
+    build(ctx: OperatorRetrievalContext, recorder: ToolCallRecord[]): OperatorToolDefinition;
+}
+/** Multi-provider DI token: consuming apps contribute OperatorToolContribution factories. */
+export declare const OPERATOR_TOOLS: unique symbol;
+//# sourceMappingURL=operator.tool.interface.d.ts.map

package/dist/agents/operator/interfaces/operator.tool.interface.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"operator.tool.interface.d.ts","sourceRoot":"","sources":["../../../../src/agents/operator/interfaces/operator.tool.interface.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AAC9D,OAAO,EAAE,gBAAgB,EAAE,MAAM,8CAA8C,CAAC;AAChF,OAAO,EAAE,UAAU,EAAE,MAAM,mCAAmC,CAAC;AAC/D,OAAO,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,gCAAgC,CAAC;AAE7E,MAAM,WAAW,sBAAsB;IACrC,IAAI,EAAE,qBAAqB,CAAC;IAC5B,WAAW,EAAE,OAAO,CAAC;IACrB,iFAAiF;IACjF,SAAS,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,MAAM,CAAC;CACvD;AAED,2EAA2E;AAC3E,MAAM,WAAW,qBAAqB;IACpC,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;GAGG;AACH,MAAM,WAAW,sBAAuB,SAAQ,cAAc;IAC5D,SAAS,CAAC,EAAE,qBAAqB,EAAE,CAAC;CACrC;AAED,oEAAoE;AACpE,MAAM,WAAW,wBAAyB,SAAQ,WAAW;IAC3D,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,UAAU,EAAE,UAAU,CAAC;IACvB,QAAQ,EAAE,gBAAgB,EAAE,CAAC;CAC9B;AAED;;;;;GAKG;AACH,MAAM,WAAW,wBAAwB;IACvC,kGAAkG;IAClG,KAAK,CAAC,GAAG,EAAE,wBAAwB,EAAE,QAAQ,EAAE,cAAc,EAAE,GAAG,sBAAsB,CAAC;CAC1F;AAED,6FAA6F;AAC7F,eAAO,MAAM,cAAc,eAA2B,CAAC"}

package/dist/agents/operator/interfaces/operator.tool.interface.js

@@ -0,0 +1,6 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OPERATOR_TOOLS = void 0;
+/** Multi-provider DI token: consuming apps contribute OperatorToolContribution factories. */
+exports.OPERATOR_TOOLS = Symbol("OPERATOR_TOOLS");
+//# sourceMappingURL=operator.tool.interface.js.map

package/dist/agents/operator/interfaces/operator.tool.interface.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"operator.tool.interface.js","sourceRoot":"","sources":["../../../../src/agents/operator/interfaces/operator.tool.interface.ts"],"names":[],"mappings":";;;AA6CA,6FAA6F;AAChF,QAAA,cAAc,GAAG,MAAM,CAAC,gBAAgB,CAAC,CAAC"}

package/dist/agents/operator/operator.module.d.ts

@@ -0,0 +1,3 @@
+export declare class OperatorModule {
+}
+//# sourceMappingURL=operator.module.d.ts.map

package/dist/agents/operator/operator.module.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"operator.module.d.ts","sourceRoot":"","sources":["../../../src/agents/operator/operator.module.ts"],"names":[],"mappings":"AAcA,qBAgBa,cAAc;CAAG"}

package/dist/agents/operator/operator.module.js

@@ -0,0 +1,44 @@
+"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;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OperatorModule = void 0;
+const common_1 = require("@nestjs/common");
+const llm_module_1 = require("../../core/llm/llm.module");
+const assistant_module_1 = require("../../foundations/assistant/assistant.module");
+const contextualiser_module_1 = require("../contextualiser/contextualiser.module");
+const drift_module_1 = require("../drift/drift.module");
+const graph_module_1 = require("../graph/graph.module");
+const operator_controller_1 = require("./controllers/operator.controller");
+const operator_checkpointer_service_1 = require("./services/operator.checkpointer.service");
+const operator_service_1 = require("./services/operator.service");
+const operator_test_action_tool_1 = require("./tools/operator-test-action.tool");
+const operator_tool_registry_1 = require("./tools/operator.tool.registry");
+const search_communities_tool_1 = require("./tools/search-communities.tool");
+const search_documents_tool_1 = require("./tools/search-documents.tool");
+let OperatorModule = class OperatorModule {
+};
+exports.OperatorModule = OperatorModule;
+exports.OperatorModule = OperatorModule = __decorate([
+    (0, common_1.Module)({
+        // forwardRef: OperatorController needs AssistantService (operator turn
+        // orchestration) while AssistantModule imports this module for
+        // OperatorService — the cycle requires forwardRef on both sides.
+        imports: [llm_module_1.LLMModule, graph_module_1.GraphModule, contextualiser_module_1.ContextualiserModule, drift_module_1.DriftModule, (0, common_1.forwardRef)(() => assistant_module_1.AssistantModule)],
+        controllers: [operator_controller_1.OperatorController],
+        providers: [
+            operator_service_1.OperatorService,
+            operator_tool_registry_1.OperatorToolRegistry,
+            operator_checkpointer_service_1.OperatorCheckpointerService,
+            search_documents_tool_1.SearchDocumentsTool,
+            search_communities_tool_1.SearchCommunitiesTool,
+            operator_test_action_tool_1.OperatorTestActionTool,
+        ],
+        exports: [operator_service_1.OperatorService, operator_tool_registry_1.OperatorToolRegistry, operator_checkpointer_service_1.OperatorCheckpointerService],
+    })
+], OperatorModule);
+//# sourceMappingURL=operator.module.js.map

package/dist/agents/operator/operator.module.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"operator.module.js","sourceRoot":"","sources":["../../../src/agents/operator/operator.module.ts"],"names":[],"mappings":";;;;;;;;;AAAA,2CAAoD;AACpD,0DAAsD;AACtD,mFAA+E;AAC/E,mFAA+E;AAC/E,wDAAoD;AACpD,wDAAoD;AACpD,2EAAuE;AACvE,4FAAuF;AACvF,kEAA8D;AAC9D,iFAA2E;AAC3E,2EAAsE;AACtE,6EAAwE;AACxE,yEAAoE;AAkB7D,IAAM,cAAc,GAApB,MAAM,cAAc;CAAG,CAAA;AAAjB,wCAAc;yBAAd,cAAc;IAhB1B,IAAA,eAAM,EAAC;QACN,uEAAuE;QACvE,+DAA+D;QAC/D,iEAAiE;QACjE,OAAO,EAAE,CAAC,sBAAS,EAAE,0BAAW,EAAE,4CAAoB,EAAE,0BAAW,EAAE,IAAA,mBAAU,EAAC,GAAG,EAAE,CAAC,kCAAe,CAAC,CAAC;QACvG,WAAW,EAAE,CAAC,wCAAkB,CAAC;QACjC,SAAS,EAAE;YACT,kCAAe;YACf,6CAAoB;YACpB,2DAA2B;YAC3B,2CAAmB;YACnB,+CAAqB;YACrB,kDAAsB;SACvB;QACD,OAAO,EAAE,CAAC,kCAAe,EAAE,6CAAoB,EAAE,2DAA2B,CAAC;KAC9E,CAAC;GACW,cAAc,CAAG"}

package/dist/agents/operator/prompts/operator.system.prompt.d.ts

@@ -0,0 +1,2 @@
+export declare const defaultOperatorSystemPrompt = "# Role\n\nYou are an operator agent for a company ERP. You answer the user's request by calling tools in a loop: inspect the data, walk relationships, and \u2014 when the user asks for it \u2014 perform actions.\n\nEvery fact in your final reply must come from a tool call that returned it. Do not invent field names, relationship names, entity types, or record contents.\n\n## How to work\n\n- Call tools step by step. A typical request needs several tool calls; keep going until you have what you need, then reply without calling further tools.\n- If a tool returns an error message (for example \"Tool error: ...\" or \"{ error: ... }\"), read it, correct your input, and try again. Never stop on the first error and never apologise to the user for a tool error.\n- When an error tells you how to recover, recover immediately in the same run: if it suggests a corrected value (a \"suggestion\" field, or \"Retry this call with ...\"), retry the same tool with that value; if it says another tool must be called first (for example describe_entity), call that tool and then retry the original call. Never relay a tool error to the user as a question, and never ask permission to continue \u2014 you already have it.\n- Some tools perform real actions (they create, change, or delete data). When you call one of these, the system pauses and asks the user to approve the action before it runs. If the user denies it, you will see \"Action denied by the user.\" \u2014 accept the decision, do not retry the action, and wrap up by telling the user what was and was not done.\n- Never ask the user a clarifying question mid-run; make the most reasonable assumption, state it in your reply, and proceed.\n\n## Output\n\nWhen you are done, reply in plain prose with the answer or a summary of the actions performed. Quote real field values from tool results.\n\n- If the tool results do not contain the information needed to answer, say so plainly (\"I could not find ...\") instead of guessing.\n- Never claim to have performed, created, updated, or deleted anything unless a tool result in this conversation confirms that exact action. You have no ability to act outside your tools.\n";
+//# sourceMappingURL=operator.system.prompt.d.ts.map

package/dist/agents/operator/prompts/operator.system.prompt.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"operator.system.prompt.d.ts","sourceRoot":"","sources":["../../../../src/agents/operator/prompts/operator.system.prompt.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,2BAA2B,yoEAoBvC,CAAC"}

package/dist/agents/operator/prompts/operator.system.prompt.js

@@ -0,0 +1,25 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.defaultOperatorSystemPrompt = void 0;
+exports.defaultOperatorSystemPrompt = `# Role
+
+You are an operator agent for a company ERP. You answer the user's request by calling tools in a loop: inspect the data, walk relationships, and — when the user asks for it — perform actions.
+
+Every fact in your final reply must come from a tool call that returned it. Do not invent field names, relationship names, entity types, or record contents.
+
+## How to work
+
+- Call tools step by step. A typical request needs several tool calls; keep going until you have what you need, then reply without calling further tools.
+- If a tool returns an error message (for example "Tool error: ..." or "{ error: ... }"), read it, correct your input, and try again. Never stop on the first error and never apologise to the user for a tool error.
+- When an error tells you how to recover, recover immediately in the same run: if it suggests a corrected value (a "suggestion" field, or "Retry this call with ..."), retry the same tool with that value; if it says another tool must be called first (for example describe_entity), call that tool and then retry the original call. Never relay a tool error to the user as a question, and never ask permission to continue — you already have it.
+- Some tools perform real actions (they create, change, or delete data). When you call one of these, the system pauses and asks the user to approve the action before it runs. If the user denies it, you will see "Action denied by the user." — accept the decision, do not retry the action, and wrap up by telling the user what was and was not done.
+- Never ask the user a clarifying question mid-run; make the most reasonable assumption, state it in your reply, and proceed.
+
+## Output
+
+When you are done, reply in plain prose with the answer or a summary of the actions performed. Quote real field values from tool results.
+
+- If the tool results do not contain the information needed to answer, say so plainly ("I could not find ...") instead of guessing.
+- Never claim to have performed, created, updated, or deleted anything unless a tool result in this conversation confirms that exact action. You have no ability to act outside your tools.
+`;
+//# sourceMappingURL=operator.system.prompt.js.map

package/dist/agents/operator/prompts/operator.system.prompt.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"operator.system.prompt.js","sourceRoot":"","sources":["../../../../src/agents/operator/prompts/operator.system.prompt.ts"],"names":[],"mappings":";;;AAAa,QAAA,2BAA2B,GAAG;;;;;;;;;;;;;;;;;;;;CAoB1C,CAAC"}

package/dist/agents/operator/services/operator.checkpointer.service.d.ts

@@ -0,0 +1,57 @@
+import { BaseCheckpointSaver } from "@langchain/langgraph";
+import { OnModuleDestroy } from "@nestjs/common";
+import { ConfigService } from "@nestjs/config";
+import { BaseConfigInterface } from "../../../config/interfaces/base.config.interface";
+/** Default number of days an operator approval may stay pending. */
+export declare const OPERATOR_DEFAULT_APPROVAL_TTL_DAYS = 7;
+/**
+ * OperatorCheckpointerService - Durable checkpoint storage for the operator agent.
+ *
+ * Lazily constructs and caches a LangGraph checkpoint saver:
+ * - `RedisSaver` (from `@langchain/langgraph-checkpoint-redis`) when a Redis
+ *   connection is configured, using the same `redis` config block the
+ *   QueueModule reads from ConfigService.
+ * - `MemorySaver` fallback when no Redis config is present (tests).
+ *
+ * Checkpoints expire after `(operator.approvalTtlDays ?? 7) + 1` days, one day
+ * past the approval expiry so a pending approval never outlives its checkpoint.
+ */
+export declare class OperatorCheckpointerService implements OnModuleDestroy {
+    private readonly configService;
+    private readonly logger;
+    private saverPromise?;
+    constructor(configService: ConfigService<BaseConfigInterface>);
+    /** Lazily constructs and caches the saver; MemorySaver fallback when redis config is absent (tests). */
+    getSaver(): Promise<BaseCheckpointSaver>;
+    /** Closes the Redis connection on shutdown; never throws. */
+    onModuleDestroy(): Promise<void>;
+    private createSaver;
+    /**
+     * Probes the Redis server for the module commands RedisSaver depends on,
+     * using a short-lived ioredis client (already a dependency of this package —
+     * the node-redis `redis` package used by the saver is not resolvable from
+     * here under pnpm's strict isolation).
+     *
+     * `COMMAND INFO <name>` replies with a single-element array whose element is
+     * nil (`[null]`) when the command is unknown, and a populated array when it
+     * exists. It is preferred over `MODULE LIST` because on Redis 8+ the JSON
+     * and search commands are built into core (no module entry), while
+     * COMMAND INFO reports them uniformly on redis-stack, module-loaded Redis,
+     * and Redis 8+.
+     *
+     * Connection failures reject and propagate to the caller, exactly like a
+     * `RedisSaver.fromUrl` failure: getSaver() clears the cached promise so the
+     * next call retries.
+     */
+    private probeMissingRedisCommands;
+    /**
+     * RedisSaver.fromUrl creates its node-redis client without an "error"
+     * listener, so a socket error after startup would crash the process. The
+     * client is a TypeScript-private but runtime-reachable field; attach a
+     * logging handler when it is reachable, and degrade silently when a future
+     * library version hides it.
+     */
+    private attachSaverErrorHandler;
+    private buildRedisUrl;
+}
+//# sourceMappingURL=operator.checkpointer.service.d.ts.map

package/dist/agents/operator/services/operator.checkpointer.service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"operator.checkpointer.service.d.ts","sourceRoot":"","sources":["../../../../src/agents/operator/services/operator.checkpointer.service.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAe,MAAM,sBAAsB,CAAC;AAExE,OAAO,EAAsB,eAAe,EAAE,MAAM,gBAAgB,CAAC;AACrE,OAAO,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAE/C,OAAO,EAAE,mBAAmB,EAAE,MAAM,kDAAkD,CAAC;AAIvF,oEAAoE;AACpE,eAAO,MAAM,kCAAkC,IAAI,CAAC;AAQpD;;;;;;;;;;;GAWG;AACH,qBACa,2BAA4B,YAAW,eAAe;IAKrD,OAAO,CAAC,QAAQ,CAAC,aAAa;IAJ1C,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAgD;IAEvE,OAAO,CAAC,YAAY,CAAC,CAA+B;gBAEvB,aAAa,EAAE,aAAa,CAAC,mBAAmB,CAAC;IAE9E,wGAAwG;IAClG,QAAQ,IAAI,OAAO,CAAC,mBAAmB,CAAC;IAY9C,6DAA6D;IACvD,eAAe,IAAI,OAAO,CAAC,IAAI,CAAC;YAexB,WAAW;IAoCzB;;;;;;;;;;;;;;;;OAgBG;YACW,yBAAyB;IAgCvC;;;;;;OAMG;IACH,OAAO,CAAC,uBAAuB;IAc/B,OAAO,CAAC,aAAa;CAWtB"}

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

@@ -0,0 +1,171 @@
+"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 OperatorCheckpointerService_1;
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OperatorCheckpointerService = exports.OPERATOR_DEFAULT_APPROVAL_TTL_DAYS = void 0;
+const langgraph_1 = require("@langchain/langgraph");
+const langgraph_checkpoint_redis_1 = require("@langchain/langgraph-checkpoint-redis");
+const common_1 = require("@nestjs/common");
+const config_1 = require("@nestjs/config");
+const ioredis_1 = require("ioredis");
+/** Default number of days an operator approval may stay pending. */
+exports.OPERATOR_DEFAULT_APPROVAL_TTL_DAYS = 7;
+/**
+ * Commands RedisSaver depends on that only exist when the RedisJSON and
+ * RediSearch modules are loaded (redis-stack / Redis 8+ where they are core).
+ */
+const OPERATOR_REQUIRED_REDIS_COMMANDS = ["JSON.SET", "FT.CREATE"];
+/**
+ * OperatorCheckpointerService - Durable checkpoint storage for the operator agent.
+ *
+ * Lazily constructs and caches a LangGraph checkpoint saver:
+ * - `RedisSaver` (from `@langchain/langgraph-checkpoint-redis`) when a Redis
+ *   connection is configured, using the same `redis` config block the
+ *   QueueModule reads from ConfigService.
+ * - `MemorySaver` fallback when no Redis config is present (tests).
+ *
+ * Checkpoints expire after `(operator.approvalTtlDays ?? 7) + 1` days, one day
+ * past the approval expiry so a pending approval never outlives its checkpoint.
+ */
+let OperatorCheckpointerService = OperatorCheckpointerService_1 = class OperatorCheckpointerService {
+    constructor(configService) {
+        this.configService = configService;
+        this.logger = new common_1.Logger(OperatorCheckpointerService_1.name);
+    }
+    /** Lazily constructs and caches the saver; MemorySaver fallback when redis config is absent (tests). */
+    async getSaver() {
+        if (!this.saverPromise) {
+            this.saverPromise = this.createSaver();
+            // A rejected saver (e.g. Redis briefly down) must not be cached forever:
+            // clear the cache so the next getSaver() call retries the connection.
+            // Callers awaiting the current promise still observe the rejection.
+            this.saverPromise.catch(() => (this.saverPromise = undefined));
+        }
+        return this.saverPromise;
+    }
+    /** Closes the Redis connection on shutdown; never throws. */
+    async onModuleDestroy() {
+        if (!this.saverPromise) {
+            return;
+        }
+        try {
+            const saver = (await this.saverPromise);
+            if (typeof saver.end === "function") {
+                await saver.end();
+            }
+        }
+        catch (error) {
+            this.logger.warn(`Failed to close operator checkpointer on shutdown: ${error}`);
+        }
+    }
+    async createSaver() {
+        const redis = this.configService.get("redis");
+        if (!redis?.host) {
+            this.logger.warn("Operator checkpointer falling back to MemorySaver — checkpoints will not survive restarts. Configure redis.host for durable checkpoints.");
+            return new langgraph_1.MemorySaver();
+        }
+        const url = this.buildRedisUrl(redis);
+        // RedisSaver.fromUrl SUCCEEDS against a Redis without RedisJSON/RediSearch
+        // (its ensureIndexes only logs the FT.CREATE failure); the first checkpoint
+        // write then dies on JSON.SET and the rejection crashes the process. Probe
+        // the server BEFORE adopting RedisSaver so plain Redis degrades gracefully.
+        const missingCommands = await this.probeMissingRedisCommands(url);
+        if (missingCommands.length > 0) {
+            this.logger.error(`Operator checkpointer: Redis at ${redis.host}:${redis.port} lacks the RedisJSON/RediSearch modules required for durable checkpoints (missing commands: ${missingCommands.join(", ")}; Redis 8+ or redis-stack needed). Falling back to MemorySaver — pending approvals will NOT survive restarts.`);
+            return new langgraph_1.MemorySaver();
+        }
+        const operator = this.configService.get("operator");
+        const approvalTtlDays = operator?.approvalTtlDays ?? exports.OPERATOR_DEFAULT_APPROVAL_TTL_DAYS;
+        // RedisSaver's `defaultTTL` option is expressed in MINUTES (the saver
+        // multiplies by 60 internally), so (approvalTtlDays + 1) days in seconds
+        // equals (approvalTtlDays + 1) * 24 * 60 minutes here.
+        const defaultTTL = (approvalTtlDays + 1) * 24 * 60;
+        const saver = await langgraph_checkpoint_redis_1.RedisSaver.fromUrl(url, { defaultTTL });
+        this.attachSaverErrorHandler(saver);
+        return saver;
+    }
+    /**
+     * Probes the Redis server for the module commands RedisSaver depends on,
+     * using a short-lived ioredis client (already a dependency of this package —
+     * the node-redis `redis` package used by the saver is not resolvable from
+     * here under pnpm's strict isolation).
+     *
+     * `COMMAND INFO <name>` replies with a single-element array whose element is
+     * nil (`[null]`) when the command is unknown, and a populated array when it
+     * exists. It is preferred over `MODULE LIST` because on Redis 8+ the JSON
+     * and search commands are built into core (no module entry), while
+     * COMMAND INFO reports them uniformly on redis-stack, module-loaded Redis,
+     * and Redis 8+.
+     *
+     * Connection failures reject and propagate to the caller, exactly like a
+     * `RedisSaver.fromUrl` failure: getSaver() clears the cached promise so the
+     * next call retries.
+     */
+    async probeMissingRedisCommands(url) {
+        const probe = new ioredis_1.Redis(url, {
+            lazyConnect: true,
+            maxRetriesPerRequest: 1,
+            retryStrategy: () => null,
+        });
+        // ioredis clients emit "error" events; without a listener an emitted error
+        // crashes the process. Connection failures are still surfaced through the
+        // rejected connect()/call() promises — the listener only absorbs the
+        // duplicate event emission.
+        probe.on("error", () => undefined);
+        try {
+            await probe.connect();
+            const missing = [];
+            for (const command of OPERATOR_REQUIRED_REDIS_COMMANDS) {
+                const reply = await probe.call("COMMAND", "INFO", command);
+                const supported = Array.isArray(reply) && reply.length > 0 && reply[0] !== null && reply[0] !== undefined;
+                if (!supported) {
+                    missing.push(command);
+                }
+            }
+            return missing;
+        }
+        finally {
+            // disconnect() closes immediately and never throws (quit() can hang or
+            // reject on an already-broken connection).
+            probe.disconnect();
+        }
+    }
+    /**
+     * RedisSaver.fromUrl creates its node-redis client without an "error"
+     * listener, so a socket error after startup would crash the process. The
+     * client is a TypeScript-private but runtime-reachable field; attach a
+     * logging handler when it is reachable, and degrade silently when a future
+     * library version hides it.
+     */
+    attachSaverErrorHandler(saver) {
+        const client = saver.client;
+        if (client && typeof client.on === "function") {
+            client.on("error", (error) => this.logger.error(`Operator checkpointer Redis client error: ${error}`));
+        }
+        else {
+            this.logger.warn("Operator checkpointer: could not attach an error handler to the RedisSaver client (internal client not reachable).");
+        }
+    }
+    buildRedisUrl(redis) {
+        const credentials = redis.username || redis.password
+            ? `${encodeURIComponent(redis.username ?? "")}:${encodeURIComponent(redis.password ?? "")}@`
+            : "";
+        // IPv6 hosts must be bracketed to form a valid URL (e.g. redis://[::1]:6379).
+        const host = redis.host.includes(":") ? `[${redis.host}]` : redis.host;
+        return `redis://${credentials}${host}:${redis.port}`;
+    }
+};
+exports.OperatorCheckpointerService = OperatorCheckpointerService;
+exports.OperatorCheckpointerService = OperatorCheckpointerService = OperatorCheckpointerService_1 = __decorate([
+    (0, common_1.Injectable)(),
+    __metadata("design:paramtypes", [config_1.ConfigService])
+], OperatorCheckpointerService);
+//# sourceMappingURL=operator.checkpointer.service.js.map

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

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

package/dist/agents/operator/services/operator.service.d.ts

@@ -0,0 +1,81 @@
+import { ConfigService } from "@nestjs/config";
+import { MessageInterface } from "../../../common/interfaces/message.interface";
+import { BaseConfigInterface } from "../../../config/interfaces";
+import { LLMService } from "../../../core/llm/services/llm.service";
+import type { ToolCallRecord } from "../../graph/tools/tool.factory";
+import type { EntityReference } from "../../responder/interfaces/entity.reference.interface";
+import { OperatorCitation } from "../contexts/operator.context";
+import { OperatorToolRegistry } from "../tools/operator.tool.registry";
+import { OperatorCheckpointerService } from "./operator.checkpointer.service";
+export type OperatorRunResult = {
+    kind: "completed";
+    answer: string;
+    questions: string[];
+    references: EntityReference[];
+    citations: OperatorCitation[];
+    toolCalls: ToolCallRecord[];
+    tokens: {
+        input: number;
+        output: number;
+    };
+} | {
+    kind: "pending_approval";
+    toolName: string;
+    toolArgs: Record<string, unknown>;
+    summary: 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 } })`.
+ */
+export declare class OperatorService {
+    private readonly llm;
+    private readonly toolRegistry;
+    private readonly checkpointer;
+    private readonly configService;
+    private readonly logger;
+    private readonly systemPrompt;
+    constructor(llm: LLMService, toolRegistry: OperatorToolRegistry, checkpointer: OperatorCheckpointerService, configService: ConfigService<BaseConfigInterface>);
+    run(params: {
+        companyId: string;
+        userId: string;
+        userModuleIds: string[];
+        contentId?: string;
+        contentType?: string;
+        messages: MessageInterface[];
+        question: string;
+        threadId: string;
+    }): Promise<OperatorRunResult>;
+    resume(params: {
+        threadId: string;
+        approved: boolean;
+        companyId: string;
+        userId: string;
+        userModuleIds: string[];
+        contentId?: string;
+        contentType?: string;
+        messages?: MessageInterface[];
+    }): Promise<OperatorRunResult>;
+    private compileGraph;
+    /** Entity references derived deterministically from the tool-call recorder (never from the LLM). */
+    private collectReferences;
+    /** Chunk citations recorded by retrieval tool wrappers into the recorder. */
+    private collectCitations;
+    private buildInitialMessages;
+    private mapResult;
+}
+//# sourceMappingURL=operator.service.d.ts.map

package/dist/agents/operator/services/operator.service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"operator.service.d.ts","sourceRoot":"","sources":["../../../../src/agents/operator/services/operator.service.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAG/C,OAAO,EAAE,gBAAgB,EAAE,MAAM,8CAA8C,CAAC;AAChF,OAAO,EAAE,mBAAmB,EAA0B,MAAM,4BAA4B,CAAC;AACzF,OAAO,EAAE,UAAU,EAAE,MAAM,wCAAwC,CAAC;AACpE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,gCAAgC,CAAC;AACrE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,uDAAuD,CAAC;AAC7F,OAAO,EAAE,gBAAgB,EAAyC,MAAM,8BAA8B,CAAC;AAOvG,OAAO,EAAE,oBAAoB,EAAE,MAAM,iCAAiC,CAAC;AACvE,OAAO,EAAE,2BAA2B,EAAE,MAAM,iCAAiC,CAAC;AAmB9E,MAAM,MAAM,iBAAiB,GACzB;IACE,IAAI,EAAE,WAAW,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,UAAU,EAAE,eAAe,EAAE,CAAC;IAC9B,SAAS,EAAE,gBAAgB,EAAE,CAAC;IAC9B,SAAS,EAAE,cAAc,EAAE,CAAC;IAC5B,MAAM,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;CAC3C,GACD;IAAE,IAAI,EAAE,kBAAkB,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAEvG;;;;;;;;;;;;;;;;;GAiBG;AACH,qBACa,eAAe;IAKxB,OAAO,CAAC,QAAQ,CAAC,GAAG;IACpB,OAAO,CAAC,QAAQ,CAAC,YAAY;IAC7B,OAAO,CAAC,QAAQ,CAAC,YAAY;IAC7B,OAAO,CAAC,QAAQ,CAAC,aAAa;IAPhC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAoC;IAC3D,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAS;gBAGnB,GAAG,EAAE,UAAU,EACf,YAAY,EAAE,oBAAoB,EAClC,YAAY,EAAE,2BAA2B,EACzC,aAAa,EAAE,aAAa,CAAC,mBAAmB,CAAC;IAM9D,GAAG,CAAC,MAAM,EAAE;QAChB,SAAS,EAAE,MAAM,CAAC;QAClB,MAAM,EAAE,MAAM,CAAC;QACf,aAAa,EAAE,MAAM,EAAE,CAAC;QACxB,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,QAAQ,EAAE,gBAAgB,EAAE,CAAC;QAC7B,QAAQ,EAAE,MAAM,CAAC;QACjB,QAAQ,EAAE,MAAM,CAAC;KAClB,GAAG,OAAO,CAAC,iBAAiB,CAAC;IA6BxB,MAAM,CAAC,MAAM,EAAE;QACnB,QAAQ,EAAE,MAAM,CAAC;QACjB,QAAQ,EAAE,OAAO,CAAC;QAClB,SAAS,EAAE,MAAM,CAAC;QAClB,MAAM,EAAE,MAAM,CAAC;QACf,aAAa,EAAE,MAAM,EAAE,CAAC;QACxB,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,QAAQ,CAAC,EAAE,gBAAgB,EAAE,CAAC;KAC/B,GAAG,OAAO,CAAC,iBAAiB,CAAC;YAmBhB,YAAY;IAgL1B,oGAAoG;IACpG,OAAO,CAAC,iBAAiB;IAsBzB,6EAA6E;IAC7E,OAAO,CAAC,gBAAgB;IAcxB,OAAO,CAAC,oBAAoB;IAmB5B,OAAO,CAAC,SAAS;CAyBlB"}