agentic-api 2.0.585 → 2.0.592

package/dist/src/agents/job.runner.d.ts

@@ -0,0 +1,130 @@
+export type JobStatus = 'planned' | 'running' | 'done' | 'failed';
+export type TaskStatus = 'todo' | 'doing' | 'done' | 'failed';
+export interface TaskSpec {
+    id: string;
+    title: string;
+    type?: string;
+    dependsOn?: string[];
+    input?: any;
+    acceptance?: string[];
+}
+export interface TaskResult {
+    taskId: string;
+    ok: boolean;
+    summary: string;
+    data?: any;
+    artifacts?: {
+        kind: string;
+        ref: string;
+        meta?: any;
+    }[];
+    error?: string;
+}
+export interface JobPlan {
+    jobId: string;
+    goal: string;
+    beneficiary?: string;
+    tasks: TaskSpec[];
+}
+export interface ReducedJobMemory {
+    memory: string;
+    index: Record<string, any>;
+    statusLine?: string;
+}
+export interface JobRunnerState {
+    jobId: string;
+    plan?: JobPlan;
+    jobStatus: JobStatus;
+    taskStatus: Record<string, TaskStatus>;
+    lastMemory: ReducedJobMemory | null;
+    lastError?: string;
+}
+export type PlannerFn = (input: any, seedMemory?: ReducedJobMemory | null) => Promise<JobPlan>;
+export type ExecutorFn = (task: TaskSpec, memory: ReducedJobMemory | null) => Promise<TaskResult>;
+export type ReducerFn = (previous: ReducedJobMemory | null, task: TaskSpec, result: TaskResult) => Promise<ReducedJobMemory>;
+export type JobEventType = 'job_created' | 'plan_ready' | 'task_started' | 'task_done' | 'memory_reduced' | 'job_done' | 'job_failed';
+export interface JobEvent<T = any> {
+    type: JobEventType;
+    at: string;
+    payload?: T;
+}
+export interface JobRunnerConfig {
+    planner: PlannerFn;
+    executor: ExecutorFn;
+    reducer: ReducerFn;
+    /**
+     * Directory where snapshots and events are persisted.
+     * If not provided, persistence is disabled.
+     */
+    storeDir?: string;
+    /**
+     * Max attempts per task when schema validation fails or executor throws.
+     * (Logical failure with ok=false does not trigger retry)
+     */
+    maxAttempts?: number;
+    onEvent?: (event: JobEvent) => void;
+}
+export interface RunJobOptions {
+    jobId?: string;
+    seedMemory?: ReducedJobMemory | null;
+    resume?: boolean;
+}
+export interface JobRunSuccess {
+    ok: true;
+    jobId: string;
+    plan: JobPlan;
+    finalSummary: string;
+    artifactsIndex: Record<string, any>;
+    memory: ReducedJobMemory | null;
+    taskStatus: Record<string, TaskStatus>;
+    snapshotFile?: string;
+    eventsFile?: string;
+}
+export interface JobRunFailure {
+    ok: false;
+    jobId: string;
+    plan?: JobPlan;
+    failedTaskId?: string;
+    error: string;
+    errorSummary: {
+        taskId?: string;
+        taskTitle?: string;
+        nature: string;
+        progress?: string;
+        nextAction: string;
+    };
+    memory: ReducedJobMemory | null;
+    taskStatus: Record<string, TaskStatus>;
+    snapshotFile?: string;
+    eventsFile?: string;
+}
+export type JobRunOutcome = JobRunSuccess | JobRunFailure;
+export declare class JobRunner {
+    private readonly storeDir?;
+    private readonly maxAttempts;
+    private readonly planner;
+    private readonly executor;
+    private readonly reducer;
+    private readonly onEvent?;
+    constructor(config: JobRunnerConfig);
+    /**
+     * Run a job end-to-end (Plan → Execute → Reduce) with persistence and retries.
+     */
+    run(input: any, options?: RunJobOptions): Promise<JobRunOutcome>;
+    private planJob;
+    private initTaskStatus;
+    private nextReadyTask;
+    private executeWithRetry;
+    private reduceWithRetry;
+    private handleFailure;
+    private validateJobPlan;
+    private validateTaskResult;
+    private validateMemory;
+    private persistState;
+    private loadState;
+    private ensureStoreDir;
+    private snapshotPath;
+    private eventsPath;
+    private logEvent;
+    private emit;
+}

package/dist/src/agents/job.runner.js

@@ -0,0 +1,339 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.JobRunner = void 0;
+const crypto_1 = require("crypto");
+const fs_1 = require("fs");
+const path_1 = __importDefault(require("path"));
+class JobRunner {
+    constructor(config) {
+        this.planner = config.planner;
+        this.executor = config.executor;
+        this.reducer = config.reducer;
+        this.storeDir = config.storeDir;
+        this.maxAttempts = config.maxAttempts || 2;
+        this.onEvent = config.onEvent;
+    }
+    /**
+     * Run a job end-to-end (Plan → Execute → Reduce) with persistence and retries.
+     */
+    async run(input, options) {
+        const seedMemory = options?.seedMemory ?? null;
+        const jobId = options?.jobId || (0, crypto_1.randomUUID)();
+        let state = null;
+        if (options?.resume && this.storeDir) {
+            state = await this.loadState(jobId);
+        }
+        if (!state) {
+            const plan = await this.planJob(jobId, input, seedMemory);
+            state = {
+                jobId: plan.jobId,
+                plan,
+                jobStatus: 'running',
+                taskStatus: this.initTaskStatus(plan.tasks),
+                lastMemory: seedMemory || null
+            };
+            await this.persistState(state);
+            this.emit({ type: 'job_created', at: new Date().toISOString(), payload: { jobId: state.jobId } });
+        }
+        if (!state.plan) {
+            return {
+                ok: false,
+                jobId,
+                error: 'Missing plan in restored state',
+                errorSummary: {
+                    nature: 'state_corruption',
+                    nextAction: 'Re-run planner to regenerate plan'
+                },
+                memory: state.lastMemory,
+                taskStatus: state.taskStatus
+            };
+        }
+        this.emit({ type: 'plan_ready', at: new Date().toISOString(), payload: { jobId: state.jobId, tasks: state.plan.tasks.length } });
+        const plan = state.plan;
+        state.jobStatus = 'running';
+        while (true) {
+            const nextTask = this.nextReadyTask(plan.tasks, state.taskStatus);
+            if (!nextTask)
+                break;
+            state.taskStatus[nextTask.id] = 'doing';
+            await this.persistState(state);
+            const execResult = await this.executeWithRetry(nextTask, state.lastMemory);
+            if (!execResult.valid) {
+                return await this.handleFailure(state, plan, nextTask, execResult.error || 'Execution failed');
+            }
+            const result = execResult.result;
+            this.emit({ type: 'task_done', at: new Date().toISOString(), payload: { jobId: plan.jobId, taskId: nextTask.id, ok: result.ok } });
+            const reduced = await this.reduceWithRetry(state.lastMemory, nextTask, result);
+            if (!reduced.valid) {
+                return await this.handleFailure(state, plan, nextTask, reduced.error || 'Reducer failed');
+            }
+            state.lastMemory = reduced.memory;
+            state.taskStatus[nextTask.id] = result.ok ? 'done' : 'failed';
+            await this.persistState(state);
+            this.emit({ type: 'memory_reduced', at: new Date().toISOString(), payload: { jobId: plan.jobId, taskId: nextTask.id } });
+            if (!result.ok) {
+                return await this.handleFailure(state, plan, nextTask, result.error || 'Task reported logical failure');
+            }
+        }
+        state.jobStatus = 'done';
+        await this.persistState(state);
+        this.emit({ type: 'job_done', at: new Date().toISOString(), payload: { jobId: plan.jobId } });
+        return {
+            ok: true,
+            jobId: plan.jobId,
+            plan,
+            finalSummary: state.lastMemory?.memory || '',
+            artifactsIndex: state.lastMemory?.index || {},
+            memory: state.lastMemory,
+            taskStatus: state.taskStatus,
+            snapshotFile: this.snapshotPath(plan.jobId),
+            eventsFile: this.eventsPath(plan.jobId)
+        };
+    }
+    async planJob(jobId, input, seedMemory) {
+        const plan = await this.planner(input, seedMemory);
+        const finalPlan = {
+            ...plan,
+            jobId: plan.jobId || jobId
+        };
+        this.validateJobPlan(finalPlan, true);
+        return finalPlan;
+    }
+    initTaskStatus(tasks) {
+        return tasks.reduce((acc, task) => {
+            acc[task.id] = 'todo';
+            return acc;
+        }, {});
+    }
+    nextReadyTask(tasks, status) {
+        return tasks.find(task => {
+            if (status[task.id] !== 'todo')
+                return false;
+            if (!task.dependsOn || task.dependsOn.length === 0)
+                return true;
+            return task.dependsOn.every(dep => status[dep] === 'done');
+        }) || null;
+    }
+    async executeWithRetry(task, memory) {
+        for (let attempt = 1; attempt <= this.maxAttempts; attempt++) {
+            this.emit({ type: 'task_started', at: new Date().toISOString(), payload: { taskId: task.id, attempt } });
+            try {
+                const result = await this.executor(task, memory);
+                const errors = this.validateTaskResult(result);
+                if (errors.length === 0) {
+                    return { valid: true, result, attempts: attempt };
+                }
+                if (attempt >= this.maxAttempts) {
+                    return { valid: false, error: `TaskResult validation failed: ${errors.join(', ')}`, attempts: attempt };
+                }
+            }
+            catch (err) {
+                if (attempt >= this.maxAttempts) {
+                    return { valid: false, error: err?.message || 'Executor error', attempts: attempt };
+                }
+            }
+        }
+        return { valid: false, error: 'Unknown execution failure', attempts: this.maxAttempts };
+    }
+    async reduceWithRetry(previous, task, result) {
+        for (let attempt = 1; attempt <= this.maxAttempts; attempt++) {
+            try {
+                const nextMemory = await this.reducer(previous, task, result);
+                const errors = this.validateMemory(nextMemory);
+                if (errors.length === 0) {
+                    return { valid: true, memory: nextMemory };
+                }
+                if (attempt >= this.maxAttempts) {
+                    return { valid: false, error: `Reducer validation failed: ${errors.join(', ')}` };
+                }
+            }
+            catch (err) {
+                if (attempt >= this.maxAttempts) {
+                    return { valid: false, error: err?.message || 'Reducer error' };
+                }
+            }
+        }
+        return { valid: false, error: 'Unknown reducer failure' };
+    }
+    async handleFailure(state, plan, task, reason) {
+        state.jobStatus = 'failed';
+        state.taskStatus[task.id] = state.taskStatus[task.id] === 'done' ? 'done' : 'failed';
+        state.lastError = reason;
+        await this.persistState(state);
+        const errorSummary = {
+            taskId: task.id,
+            taskTitle: task.title,
+            nature: reason,
+            progress: state.lastMemory?.memory,
+            nextAction: 'Inspect executor/reducer outputs or planner schema, then retry'
+        };
+        this.emit({ type: 'job_failed', at: new Date().toISOString(), payload: { jobId: plan.jobId, taskId: task.id, reason } });
+        return {
+            ok: false,
+            jobId: plan.jobId,
+            plan,
+            failedTaskId: task.id,
+            error: reason,
+            errorSummary,
+            memory: state.lastMemory,
+            taskStatus: state.taskStatus,
+            snapshotFile: this.snapshotPath(plan.jobId),
+            eventsFile: this.eventsPath(plan.jobId)
+        };
+    }
+    validateJobPlan(plan, throwOnError = false) {
+        const errors = [];
+        if (!plan || typeof plan !== 'object') {
+            errors.push('plan must be an object');
+        }
+        if (!plan.jobId || typeof plan.jobId !== 'string' || !plan.jobId.trim()) {
+            errors.push('jobId is required');
+        }
+        if (!plan.goal || typeof plan.goal !== 'string' || !plan.goal.trim()) {
+            errors.push('goal is required');
+        }
+        if (!Array.isArray(plan.tasks) || plan.tasks.length === 0) {
+            errors.push('tasks must be a non-empty array');
+        }
+        else {
+            plan.tasks.forEach((task, idx) => {
+                if (!task || typeof task !== 'object') {
+                    errors.push(`task[${idx}] must be an object`);
+                    return;
+                }
+                if (!task.id || typeof task.id !== 'string' || !task.id.trim()) {
+                    errors.push(`task[${idx}].id is required`);
+                }
+                if (!task.title || typeof task.title !== 'string' || !task.title.trim()) {
+                    errors.push(`task[${idx}].title is required`);
+                }
+                if (task.dependsOn && !Array.isArray(task.dependsOn)) {
+                    errors.push(`task[${idx}].dependsOn must be an array if provided`);
+                }
+                if (task.acceptance && !Array.isArray(task.acceptance)) {
+                    errors.push(`task[${idx}].acceptance must be an array if provided`);
+                }
+            });
+        }
+        if (throwOnError && errors.length) {
+            throw new Error(`Invalid JobPlan: ${errors.join(', ')}`);
+        }
+        return errors;
+    }
+    validateTaskResult(result) {
+        const errors = [];
+        if (!result || typeof result !== 'object') {
+            errors.push('TaskResult must be an object');
+            return errors;
+        }
+        if (!result.taskId || typeof result.taskId !== 'string' || !result.taskId.trim()) {
+            errors.push('taskId is required');
+        }
+        if (typeof result.ok !== 'boolean') {
+            errors.push('ok must be boolean');
+        }
+        if (!result.summary || typeof result.summary !== 'string') {
+            errors.push('summary is required');
+        }
+        if (result.artifacts && !Array.isArray(result.artifacts)) {
+            errors.push('artifacts must be an array if provided');
+        }
+        else if (Array.isArray(result.artifacts)) {
+            result.artifacts.forEach((artifact, idx) => {
+                if (!artifact || typeof artifact !== 'object') {
+                    errors.push(`artifacts[${idx}] must be an object`);
+                    return;
+                }
+                if (!artifact.kind || !artifact.ref) {
+                    errors.push(`artifacts[${idx}] requires kind and ref`);
+                }
+            });
+        }
+        return errors;
+    }
+    validateMemory(memory) {
+        const errors = [];
+        if (!memory || typeof memory !== 'object') {
+            errors.push('memory must be an object');
+            return errors;
+        }
+        if (typeof memory.memory !== 'string') {
+            errors.push('memory.memory must be a string');
+        }
+        if (!memory.index || typeof memory.index !== 'object') {
+            errors.push('memory.index must be an object');
+        }
+        if (memory.statusLine && typeof memory.statusLine !== 'string') {
+            errors.push('memory.statusLine must be a string if provided');
+        }
+        return errors;
+    }
+    async persistState(state) {
+        if (!this.storeDir)
+            return;
+        await this.ensureStoreDir();
+        const file = this.snapshotPath(state.jobId);
+        if (!file)
+            return;
+        const snapshot = JSON.stringify(state, null, 2);
+        await fs_1.promises.writeFile(file, snapshot, 'utf-8');
+    }
+    async loadState(jobId) {
+        if (!this.storeDir)
+            return null;
+        const file = this.snapshotPath(jobId);
+        if (!file)
+            return null;
+        try {
+            const data = await fs_1.promises.readFile(file, 'utf-8');
+            return JSON.parse(data);
+        }
+        catch {
+            return null;
+        }
+    }
+    async ensureStoreDir() {
+        if (!this.storeDir)
+            return;
+        await fs_1.promises.mkdir(this.storeDir, { recursive: true });
+    }
+    snapshotPath(jobId) {
+        if (!this.storeDir)
+            return undefined;
+        return path_1.default.join(this.storeDir, `${jobId}.json`);
+    }
+    eventsPath(jobId) {
+        if (!this.storeDir)
+            return undefined;
+        return path_1.default.join(this.storeDir, `${jobId}.events.jsonl`);
+    }
+    async logEvent(jobId, event) {
+        if (!this.storeDir)
+            return;
+        await this.ensureStoreDir();
+        const file = this.eventsPath(jobId);
+        if (!file)
+            return;
+        const line = JSON.stringify(event);
+        await fs_1.promises.appendFile(file, `${line}\n`, 'utf-8');
+    }
+    emit(event) {
+        if (!event.at) {
+            event.at = new Date().toISOString();
+        }
+        if (this.onEvent) {
+            this.onEvent(event);
+        }
+        // Persist events only when jobId is present in payload or snapshot is known
+        const jobId = (event.payload && event.payload.jobId) || undefined;
+        if (jobId && this.storeDir) {
+            this.logEvent(jobId, event).catch(() => {
+                /* silent */
+            });
+        }
+    }
+}
+exports.JobRunner = JobRunner;

package/dist/src/agents/reducer.core.d.ts

@@ -12,13 +12,23 @@ export interface AgentReducerConfig {
     /** Default agent name to use if task doesn't specify one */
     defaultAgent: string;
 }
+/**
+ * Options for MapLLM constructor
+ */
+export interface MapLLMOptions {
+    /** Whether to execute a final reduce pass after all chunks (default: true) */
+    finalReduce?: boolean;
+    /** Threshold in bytes to trigger automatic intermediate reduce (optional) */
+    reduceThresholdBytes?: number;
+}
 /**
  * MapLLM - Orchestrateur principal pour le reduce hiérarchique
  */
 export declare class MapLLM {
     private loader;
     private agentConfig?;
-    constructor(loader: NativeLoader);
+    private readonly options;
+    constructor(loader: NativeLoader, options?: MapLLMOptions);
     /**
      * Vérifie si le loader fournit des agents (TaskListLoader)
      */

package/dist/src/agents/reducer.core.js

@@ -5,13 +5,17 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.MapLLM = void 0;
 const execute_1 = require("../execute");
-const llm_1 = require("../llm");
 /**
  * MapLLM - Orchestrateur principal pour le reduce hiérarchique
  */
 class MapLLM {
-    constructor(loader) {
+    constructor(loader, options) {
         this.loader = loader;
+        // Default options
+        this.options = {
+            finalReduce: options?.finalReduce ?? true,
+            reduceThresholdBytes: options?.reduceThresholdBytes ?? 0
+        };
         //
         // ✅ Si pas d'agentConfig fourni, essayer d'extraire depuis le loader
         if (this.hasAgents(loader)) {
@@ -53,11 +57,7 @@ class MapLLM {
         let position = 0;
         let totalChunkSize = 0;
         let totalReduce = 0;
-        const model = (0, execute_1.modelConfig)(result.model);
-        const openai = (0, llm_1.llmInstance)();
-        const llm = Object.assign({}, model);
-        llm.stream = false;
-        delete llm.stream_options;
+        const modelName = result.model || 'LOW-fast';
         //
         // maxIterations is set by the callback
         while (!result.maxIterations) {
@@ -118,35 +118,23 @@ class MapLLM {
                 }
                 else {
                     //
-                    // ══════════════════════════════════════
-                    // MODE DOCUMENT : openai.chat direct
-                    // ══════════════════════════════════════
-                    const messages = isFirstChunk ? [
-                        { role: "system", content: config.digestPrompt },
-                        { role: "user", content: chunk.content }
-                    ] : [
-                        { role: "system", content: config.digestPrompt },
-                        { role: "assistant", content: accContent },
-                        { role: "user", content: chunk.content }
+                    // ══════════════════════════════════════════════════════════
+                    // MODE DOCUMENT : executeQuery() avec API Responses unifiée
+                    // ══════════════════════════════════════════════════════════
+                    const messages = isFirstChunk ? [] : [
+                        { role: "assistant", content: accContent }
                     ];
-                    llm.messages = messages;
-                    //
-                    // Configure structured output if format is specified
-                    if (result.format) {
-                        llm.response_format = {
-                            type: "json_schema",
-                            json_schema: {
-                                name: result.format.name,
-                                schema: result.format.schema,
-                                strict: result.format.strict ?? true
-                            }
-                        };
-                    }
-                    const chat = await openai.chat.completions.create(llm);
-                    const digestMessage = chat.choices[0]?.message;
-                    //
-                    // Parse JSON if structured output is enabled
-                    digestContent = digestMessage.content || '';
+                    const execResult = await (0, execute_1.executeQuery)({
+                        query: chunk.content,
+                        model: modelName,
+                        instructions: config.digestPrompt,
+                        messages,
+                        schema: result.format ? result.format.schema : undefined,
+                        verbose: verbose,
+                        stdout: init.stdout || execute_1.DummyWritable
+                    });
+                    // executeQuery returns content - parse if structured output is enabled
+                    digestContent = execResult.content;
                     if (result.format && digestContent) {
                         try {
                             digestContent = JSON.parse(digestContent);
@@ -169,31 +157,31 @@ class MapLLM {
                     }
                     break;
                 }
-                // Décision de réduction basée sur callback
-                if (!result.continue) {
+                // Auto-reduce if accumulator exceeds threshold (if configured)
+                const accSize = typeof result.acc === 'string' ? result.acc.length : JSON.stringify(result.acc).length;
+                const shouldAutoReduce = this.options.reduceThresholdBytes > 0 && accSize > this.options.reduceThresholdBytes;
+                // Décision de réduction basée sur callback ou auto-threshold
+                if (!result.continue && !shouldAutoReduce) {
                     continue;
                 }
-                const accForReduce = typeof result.acc === 'string' ? result.acc : JSON.stringify(result.acc);
-                llm.messages = [
-                    { role: "system", content: config.reducePrompt },
-                    { role: "user", content: accForReduce }
-                ];
-                // Configure structured output if format is specified
-                if (result.format) {
-                    llm.response_format = {
-                        type: "json_schema",
-                        json_schema: {
-                            name: result.format.name,
-                            schema: result.format.schema,
-                            strict: result.format.strict ?? true
-                        }
-                    };
+                if (verbose && shouldAutoReduce) {
+                    console.log(`🔄 Auto-reduce triggered: acc size ${accSize} > threshold ${this.options.reduceThresholdBytes}`);
                 }
-                const reduce = await openai.chat.completions.create(llm);
-                const reduceMessage = reduce.choices[0]?.message;
+                const accForReduce = typeof result.acc === 'string' ? result.acc : JSON.stringify(result.acc);
+                //
+                // Intermediate reduce avec executeQuery
+                const reduceResult = await (0, execute_1.executeQuery)({
+                    query: accForReduce,
+                    model: modelName,
+                    instructions: config.reducePrompt,
+                    messages: [],
+                    schema: result.format ? result.format.schema : undefined,
+                    verbose: verbose,
+                    stdout: init.stdout || execute_1.DummyWritable
+                });
                 //
                 // should not happen
-                if (!reduceMessage.content) {
+                if (!reduceResult.content) {
                     continue;
                 }
                 // 3. Reduce with system - Update result.acc (replace)
@@ -201,15 +189,15 @@ class MapLLM {
                 // Parse JSON if structured output is enabled
                 if (result.format) {
                     try {
-                        result.acc = JSON.parse(reduceMessage.content);
+                        result.acc = JSON.parse(reduceResult.content);
                     }
                     catch (e) {
-                        console.warn('Failed to parse reduce result as JSON:', reduceMessage.content);
-                        result.acc = reduceMessage.content;
+                        console.warn('Failed to parse reduce result as JSON:', reduceResult.content);
+                        result.acc = reduceResult.content;
                     }
                 }
                 else {
-                    result.acc = reduceMessage.content;
+                    result.acc = reduceResult.content;
                 }
                 if (verbose) {
                     console.log(`✅ Reduce ${result.metadata?.iterations} processed (${chunk.content.length} chars)`);
@@ -224,38 +212,40 @@ class MapLLM {
                 throw new Error(`Failed to process chunk ${result.metadata?.iterations}: ${error}`);
             }
         }
-        // Final reduce
-        const finalAccContent = typeof result.acc === 'string' ? result.acc : JSON.stringify(result.acc);
-        const messages = [
-            { role: "system", content: config.reducePrompt },
-            { role: "user", content: finalAccContent }
-        ];
-        llm.messages = messages;
-        // Configure structured output if format is specified
-        if (result.format) {
-            llm.response_format = {
-                type: "json_schema",
-                json_schema: {
-                    name: result.format.name,
-                    schema: result.format.schema,
-                    strict: result.format.strict ?? true
+        // Final reduce (optional, controlled by options.finalReduce)
+        if (this.options.finalReduce) {
+            const finalAccContent = typeof result.acc === 'string' ? result.acc : JSON.stringify(result.acc);
+            //
+            // Final reduce avec executeQuery
+            const finalResult = await (0, execute_1.executeQuery)({
+                query: finalAccContent,
+                model: modelName,
+                instructions: config.reducePrompt,
+                messages: [],
+                schema: result.format ? result.format.schema : undefined,
+                verbose: verbose,
+                stdout: init.stdout || execute_1.DummyWritable
+            });
+            const finalContent = finalResult.content || '';
+            // Parse JSON if structured output is enabled
+            if (result.format && finalContent) {
+                try {
+                    result.acc = JSON.parse(finalContent);
+                }
+                catch (e) {
+                    console.warn('Failed to parse final result as JSON:', finalContent);
+                    result.acc = finalContent;
                 }
-            };
-        }
-        const reduce = await openai.chat.completions.create(llm);
-        const finalContent = reduce.choices[0]?.message.content || '';
-        // Parse JSON if structured output is enabled
-        if (result.format && finalContent) {
-            try {
-                result.acc = JSON.parse(finalContent);
             }
-            catch (e) {
-                console.warn('Failed to parse final result as JSON:', finalContent);
+            else {
                 result.acc = finalContent;
             }
+            if (verbose) {
+                console.log('🎯 Final reduce completed');
+            }
         }
-        else {
-            result.acc = finalContent;
+        else if (verbose) {
+            console.log('⏭️ Final reduce skipped (finalReduce=false)');
         }
         const endTime = Date.now();
         const processingTimeMs = endTime - startTime;

package/dist/src/agents/reducer.d.ts

@@ -1,3 +1,4 @@
 export * from './reducer.core';
 export * from './reducer.loaders';
 export * from './reducer.types';
+export * from './reducer.factory';

package/dist/src/agents/reducer.factory.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Factory to create a ReducerFn compatible with JobRunner using MapLLM
+ */
+import type { StructuredOutputFormat } from './reducer.types';
+import type { ReducerFn } from './job.runner';
+/**
+ * Options for createMapLLMReducer factory
+ */
+export interface CreateMapLLMReducerOptions {
+    /** Prompt for digesting task + result into facts */
+    digestPrompt: string;
+    /** Prompt for reducing/fusing with previous memory */
+    reducePrompt: string;
+    /** Custom JSON schema for ReducedJobMemory (optional, uses default if not provided) */
+    format?: StructuredOutputFormat;
+    /** Model to use (default: 'LOW') */
+    model?: string;
+    /** Whether to execute final reduce pass (default: true) */
+    finalReduce?: boolean;
+    /** Threshold in bytes to trigger auto intermediate reduce (optional) */
+    reduceThresholdBytes?: number;
+    /** Enable verbose logging (default: false) */
+    verbose?: boolean;
+}
+/**
+ * Creates a ReducerFn compatible with JobRunner that uses MapLLM internally.
+ *
+ * This factory bridges JobRunner and MapLLM, allowing LLM-powered reduction
+ * with structured outputs while keeping both modules independent.
+ *
+ * @example
+ * ```typescript
+ * const reducer = createMapLLMReducer({
+ *   digestPrompt: "Analyze this task result and extract key facts...",
+ *   reducePrompt: "Merge with previous memory to produce updated canonical memory...",
+ *   model: 'LOW'
+ * });
+ *
+ * const runner = new JobRunner({
+ *   planner: myPlanner,
+ *   executor: myExecutor,
+ *   reducer: reducer  // ← ReducerFn compatible
+ * });
+ * ```
+ */
+export declare function createMapLLMReducer(options: CreateMapLLMReducerOptions): ReducerFn;

package/dist/src/agents/reducer.factory.js

@@ -0,0 +1,154 @@
+"use strict";
+/**
+ * Factory to create a ReducerFn compatible with JobRunner using MapLLM
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createMapLLMReducer = createMapLLMReducer;
+const reducer_core_1 = require("./reducer.core");
+const reducer_loaders_1 = require("./reducer.loaders");
+/**
+ * Default JSON schema for ReducedJobMemory
+ * Note: For strict mode, all properties must be in required array and
+ * all nested objects need additionalProperties: false
+ */
+const DEFAULT_MEMORY_SCHEMA = {
+    name: 'ReducedJobMemory',
+    schema: {
+        type: 'object',
+        properties: {
+            memory: {
+                type: 'string',
+                description: 'Short canonical memory summarizing progress and key facts'
+            },
+            index: {
+                type: 'object',
+                description: 'Stable references: artifact IDs, data tables, error traces',
+                properties: {
+                    artifacts: {
+                        type: 'array',
+                        items: { type: 'string' },
+                        description: 'List of artifact references'
+                    },
+                    taskIds: {
+                        type: 'array',
+                        items: { type: 'string' },
+                        description: 'List of completed task IDs'
+                    },
+                    errors: {
+                        type: 'array',
+                        items: { type: 'string' },
+                        description: 'List of error messages'
+                    }
+                },
+                required: ['artifacts', 'taskIds', 'errors'],
+                additionalProperties: false
+            },
+            statusLine: {
+                type: 'string',
+                description: 'UI progress line'
+            }
+        },
+        required: ['memory', 'index', 'statusLine'],
+        additionalProperties: false
+    },
+    strict: true
+};
+/**
+ * Creates a ReducerFn compatible with JobRunner that uses MapLLM internally.
+ *
+ * This factory bridges JobRunner and MapLLM, allowing LLM-powered reduction
+ * with structured outputs while keeping both modules independent.
+ *
+ * @example
+ * ```typescript
+ * const reducer = createMapLLMReducer({
+ *   digestPrompt: "Analyze this task result and extract key facts...",
+ *   reducePrompt: "Merge with previous memory to produce updated canonical memory...",
+ *   model: 'LOW'
+ * });
+ *
+ * const runner = new JobRunner({
+ *   planner: myPlanner,
+ *   executor: myExecutor,
+ *   reducer: reducer  // ← ReducerFn compatible
+ * });
+ * ```
+ */
+function createMapLLMReducer(options) {
+    const { digestPrompt, reducePrompt, format = DEFAULT_MEMORY_SCHEMA, model = 'LOW', finalReduce = true, reduceThresholdBytes, verbose = false } = options;
+    return async (previous, task, result) => {
+        // Serialize context for reduction
+        const context = JSON.stringify({
+            previousMemory: previous,
+            task: {
+                id: task.id,
+                title: task.title,
+                type: task.type
+            },
+            result: {
+                taskId: result.taskId,
+                ok: result.ok,
+                summary: result.summary,
+                error: result.error,
+                artifacts: result.artifacts,
+                // Include data if small enough, otherwise just note its presence
+                data: result.data && JSON.stringify(result.data).length < 2000
+                    ? result.data
+                    : (result.data ? '[data truncated]' : undefined)
+            }
+        }, null, 2);
+        // Create loader with single-chunk strategy (the context is already compact)
+        const loader = new reducer_loaders_1.StringNativeLoader(context, { type: 'paragraphs', size: 10 });
+        // Create MapLLM with options
+        const mapllmOptions = {
+            finalReduce,
+            reduceThresholdBytes
+        };
+        const mapper = new reducer_core_1.MapLLM(loader, mapllmOptions);
+        // Config for MapLLM
+        const config = {
+            digestPrompt,
+            reducePrompt
+        };
+        // Callback: accumulate structured output
+        const callback = (res, current) => {
+            // If current is already an object (structured output), use it directly
+            if (typeof current === 'object' && current !== null) {
+                res.acc = current;
+            }
+            else if (typeof current === 'string') {
+                // Try to parse as JSON
+                try {
+                    res.acc = JSON.parse(current);
+                }
+                catch {
+                    // Fallback: wrap in memory field
+                    res.acc = {
+                        memory: current,
+                        index: res.acc?.index || {}
+                    };
+                }
+            }
+            return res;
+        };
+        // Init with previous memory or empty
+        const init = {
+            acc: previous || { memory: '', index: {} },
+            config,
+            format,
+            model,
+            verbose
+        };
+        // Execute MapLLM reduce
+        const out = await mapper.reduce(callback, init);
+        // Validate and return
+        const result_acc = out.acc;
+        // Ensure required fields exist
+        const reducedMemory = {
+            memory: typeof result_acc.memory === 'string' ? result_acc.memory : JSON.stringify(result_acc.memory || ''),
+            index: typeof result_acc.index === 'object' ? result_acc.index : {},
+            statusLine: result_acc.statusLine
+        };
+        return reducedMemory;
+    };
+}

package/dist/src/agents/reducer.js

@@ -17,3 +17,4 @@ Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./reducer.core"), exports);
 __exportStar(require("./reducer.loaders"), exports);
 __exportStar(require("./reducer.types"), exports);
+__exportStar(require("./reducer.factory"), exports);

package/dist/src/index.d.ts

@@ -14,6 +14,7 @@ export * from './scrapper';
 export * from './agents/reducer';
 export * from './agents/semantic';
 export * from './agents/system';
+export * from './agents/job.runner';
 export * from './rag';
 export * from './usecase';
 export * from './rules';

package/dist/src/index.js

@@ -51,6 +51,7 @@ __exportStar(require("./scrapper"), exports);
 __exportStar(require("./agents/reducer"), exports);
 __exportStar(require("./agents/semantic"), exports);
 __exportStar(require("./agents/system"), exports);
+__exportStar(require("./agents/job.runner"), exports);
 // RAG Library
 __exportStar(require("./rag"), exports);
 // Usecase

package/dist/src/rag/rag.manager.d.ts

@@ -47,6 +47,9 @@ export declare class RAGManager {
     /**
      * Notifie les embeddings chargés de se mettre à jour
      *
+     * Cette méthode est publique pour permettre aux applications de notifier
+     * les utilisateurs actifs du RAG (tools, search) qu'il a été mis à jour.
+     *
      * @param name Nom du RAG à mettre à jour
      * @param opts Options de mise à jour (action: 'rename' pour renommer un document)
      *
@@ -59,18 +62,22 @@ export declare class RAGManager {
      *
      * @example
      * ```typescript
-     * // Après un build
-     * this.notifyUpdate('procedures-stable');
+     * // Après un build externe
+     * ragManager.notifyUpdate('procedures-stable');
      *
      * // Après un rename de document
-     * this.notifyUpdate('procedures-stable', {
+     * ragManager.notifyUpdate('procedures-stable', {
      *   action: 'rename',
      *   oldFile: 'old.md',
      *   newFile: 'new.md'
      * });
      * ```
      */
-    private notifyUpdate;
+    notifyUpdate(name: string, opts?: {
+        action?: 'rename';
+        oldFile?: string;
+        newFile?: string;
+    }): void;
     /**
      * Génère un nom d'archive avec timestamp YYYMMDD
      */

package/dist/src/rag/rag.manager.js

@@ -213,6 +213,9 @@ class RAGManager {
     /**
      * Notifie les embeddings chargés de se mettre à jour
      *
+     * Cette méthode est publique pour permettre aux applications de notifier
+     * les utilisateurs actifs du RAG (tools, search) qu'il a été mis à jour.
+     *
      * @param name Nom du RAG à mettre à jour
      * @param opts Options de mise à jour (action: 'rename' pour renommer un document)
      *
@@ -225,11 +228,11 @@ class RAGManager {
      *
      * @example
      * ```typescript
-     * // Après un build
-     * this.notifyUpdate('procedures-stable');
+     * // Après un build externe
+     * ragManager.notifyUpdate('procedures-stable');
      *
      * // Après un rename de document
-     * this.notifyUpdate('procedures-stable', {
+     * ragManager.notifyUpdate('procedures-stable', {
      *   action: 'rename',
      *   oldFile: 'old.md',
      *   newFile: 'new.md'

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentic-api",
-  "version": "2.0.585",
+  "version": "2.0.592",
   "description": "API pour l'orchestration d'agents intelligents avec séquences et escalades automatiques",
   "main": "dist/src/index.js",
   "types": "dist/src/index.d.ts",