@nomad-e/bluma-cli 0.1.24 → 0.1.25

package/README.md

@@ -231,22 +231,33 @@ The JSON payload must follow this envelope:
 
 ```json
 {
-  "message_id": "job-123",           // Optional but recommended
-  "from_agent": "sandbox-api",       // Who is calling BluMa
-  "to_agent": "bluma",               // Target agent (for routing)
-  "action": "generate_app",          // High-level action label
-  "context": {                       // Arbitrary JSON with task details
+  "session_id": "conv-uuid-stable",  // Recomendado: mesma sessão entre jobs (histórico + workspace)
+  "message_id": "job-123",           // Opcional mas recomendado
+  "from_agent": "sandbox-api",
+  "to_agent": "bluma",
+  "action": "generate_app",
+  "context": {
     "user_request": "Criar dashboard de vendas",
     "erp_models": ["sale.order"],
     "permissions": ["sales"]
   },
-  "metadata": {                      // Free-form metadata for the orchestrator
+  "user_context": {
+    "userId": "13",
+    "userName": "Nome",
+    "userEmail": "user@example.com",
+    "companyId": "4",
+    "companyName": "Empresa",
+    "conversationId": null
+  },
+  "metadata": {
     "sandbox": true,
     "caller": "agiweb"
   }
 }
 ```
 
+O campo **`user_context`** (opcional) é enviado ao FactorRouter nos headers `X-User-*` / `X-Company-*` para custos e auditoria. `context.user_request` (primeiros 300 caracteres) vai em `X-User-Message` (URL-encoded).
+
 Internally, BluMa will:
 
 - Initialize the agent with a dedicated `eventBus`.
@@ -479,10 +490,41 @@ Notes
 ---
 
 ## <a name="configuration-and-environment-variables"></a>Configuration and Environment Variables
-You must create a `.env` file (copy if needed from `.env.example`) with the following variable:
-- `OPENROUTER_API_KEY` (required; get from [openrouter.ai](https://openrouter.ai))
 
-And others required by your agent/context.
+**Recommended:** set **`FACTOR_ROUTER_KEY`** and **`FACTOR_ROUTER_URL`** in your **user or system environment** (shell profile, Windows User env, CI secrets, etc.) so every process sees them.
+
+BluMa also **loads** `~/.bluma/.env` if that file exists (optional merge via `dotenv`); use `.env.example` as a template only if you prefer a local file.
+
+**LLM routing** uses the FactorRouter gateway (OpenAI-compatible API):
+
+- `FACTOR_ROUTER_KEY` (required) — e.g. `sk-fai-...` from your FactorRouter admin  
+- `FACTOR_ROUTER_URL` (required) — gateway base URL (e.g. `http://host:8003/router-api`; the client appends `/v1` if missing)
+
+These replace legacy `NOMAD_API_KEY`, `NOMAD_BASE_URL`, and `MODEL_NOMAD` (the router picks the model; requests use `model: "auto"`).
+
+Optional: `BLUMA_SANDBOX`, `BLUMA_SANDBOX_NAME`, MCP tokens, etc.
+
+### FactorRouter — headers HTTP (CLI vs sandbox)
+
+O SDK OpenAI (`openai` npm) envia metadados no **2.º argumento** da chamada `chat.completions.create(body, { headers })` — são **headers HTTP normais**, não um campo `extra_headers` no JSON do body.
+
+**Modo CLI interativo** (Ink, sem envelope): em cada request ao gateway são acrescentados:
+
+| Header | Conteúdo típico (exemplo) |
+|--------|---------------------------|
+| `X-Turn-Id` | UUID novo por turno (igual em todo o loop de tools desse turno) |
+| `X-Session-Id` | ID da sessão BluMa (`~/.bluma/sessions/…`) |
+| `X-Conversation-Id` | `null` |
+| `X-User-Message` | Primeiros 300 caracteres do pedido (URL-encoded) |
+| `X-User-Id` | MAC da 1.ª interface não-interna, ou `host:<hostname>` se não houver MAC útil |
+| `X-User-Name` | Utilizador do SO (`os.userInfo().username`, URL-encoded) |
+| `X-User-Email` | `null` |
+| `X-Company-Id` | Igual a `X-User-Id` (identificador da máquina) |
+| `X-Company-Name` | Igual (URL-encoded) |
+
+**Privacidade (desenvolvedores):** na CLI, estes valores servem para **agregação de custos** no FactorRouter. Não substituem o utilizador real no **agent mode**: aí prevalece o bloco `user_context` do JSON (sandbox / Severino).
+
+**Agent mode** (`bluma agent`): os mesmos nomes de header; valores vêm do envelope (`session_id`, `user_context`, `context.user_request`). Se `user_context` for omitido, user/company ficam `null` nos headers (não se usa a heurística MAC da CLI).
 
 Advanced config files are located in `src/app/agent/config/`.
 
@@ -495,7 +537,7 @@ Advanced config files are located in `src/app/agent/config/`.
 - Bundler: esbuild, with `esbuild-plugin-node-externals`
 - Test Runner: Jest 30 + babel-jest
 - Transpilers: Babel presets (env, react, typescript)
-- LLM/Agent: OpenRouter via API; MCP via `@modelcontextprotocol/sdk`
+- LLM/Agent: FactorRouter (OpenAI-compatible API); MCP via `@modelcontextprotocol/sdk`
 - Config loading: dotenv
 - Utilities: uuid, diff, react-devtools-core
 

package/dist/main.js

@@ -332,7 +332,7 @@ import React11 from "react";
 import { render } from "ink";
 import { EventEmitter as EventEmitter2 } from "events";
 import fs14 from "fs";
-import { v4 as uuidv43 } from "uuid";
+import { v4 as uuidv46 } from "uuid";
 
 // src/app/ui/App.tsx
 import { useState as useState7, useEffect as useEffect6, useRef as useRef5, useCallback as useCallback2, memo as memo11 } from "react";
@@ -1485,7 +1485,7 @@ var ConfirmationPrompt = memo4(ConfirmationPromptComponent);
 // src/app/agent/agent.ts
 import * as dotenv from "dotenv";
 import path16 from "path";
-import os9 from "os";
+import os10 from "os";
 
 // src/app/agent/tool_invoker.ts
 import { promises as fs8 } from "fs";
@@ -3704,6 +3704,7 @@ var AdvancedFeedbackSystem = class {
 
 // src/app/agent/bluma/core/bluma.ts
 import path15 from "path";
+import { v4 as uuidv43 } from "uuid";
 
 // src/app/agent/session_manager/session_manager.ts
 import path12 from "path";
@@ -4913,21 +4914,243 @@ function createApiContextWindow(fullHistory, maxTurns) {
   return finalContext;
 }
 
+// src/app/agent/core/llm/llm.ts
+import os8 from "os";
+import OpenAI from "openai";
+function defaultBlumaUserContextInput(sessionId, userMessage) {
+  const msg = String(userMessage || "").slice(0, 300);
+  return {
+    sessionId,
+    conversationId: null,
+    userMessage: msg,
+    userId: null,
+    userName: null,
+    userEmail: null,
+    companyId: null,
+    companyName: null
+  };
+}
+function getPreferredMacAddress() {
+  try {
+    const ifaces = os8.networkInterfaces();
+    for (const name of Object.keys(ifaces)) {
+      const addrs = ifaces[name];
+      if (!addrs) continue;
+      for (const addr of addrs) {
+        if (addr.internal) continue;
+        const mac = (addr.mac || "").toLowerCase();
+        if (mac && mac !== "00:00:00:00:00:00") {
+          return mac;
+        }
+      }
+    }
+  } catch {
+  }
+  try {
+    return `host:${os8.hostname()}`;
+  } catch {
+    return "unknown";
+  }
+}
+function defaultInteractiveCliUserContextInput(sessionId, userMessage) {
+  const base = defaultBlumaUserContextInput(sessionId, userMessage);
+  const machineId = getPreferredMacAddress();
+  let userName = null;
+  try {
+    userName = os8.userInfo().username || null;
+  } catch {
+    userName = null;
+  }
+  return {
+    ...base,
+    userId: machineId,
+    userName,
+    userEmail: null,
+    companyId: machineId,
+    companyName: machineId
+  };
+}
+function encodeHeader(value, maxLen = 300) {
+  if (value == null || value === "") return "null";
+  return encodeURIComponent(String(value).slice(0, maxLen));
+}
+function buildFactorHeaders(ctx) {
+  return {
+    "X-Turn-Id": ctx.turnId,
+    "X-Session-Id": ctx.sessionId,
+    "X-Conversation-Id": ctx.conversationId ?? "null",
+    "X-User-Message": encodeHeader(ctx.userMessage),
+    "X-User-Id": ctx.userId ?? "null",
+    "X-User-Name": encodeHeader(ctx.userName),
+    "X-User-Email": ctx.userEmail ?? "null",
+    "X-Company-Id": ctx.companyId ?? "null",
+    "X-Company-Name": encodeHeader(ctx.companyName)
+  };
+}
+function normalizeFactorBaseUrl(raw) {
+  let u = raw.trim().replace(/\/$/, "");
+  u = u.replace(/^http:\/\/http:\/\//i, "http://");
+  if (!u.endsWith("/v1")) {
+    u = `${u}/v1`;
+  }
+  return u;
+}
+async function notifyFactorRouterTurnEnd(params) {
+  const frUrl = (process.env.FACTOR_ROUTER_URL ?? "").trim();
+  const frKey = (process.env.FACTOR_ROUTER_KEY ?? "").trim();
+  if (!frUrl || !frKey) return;
+  const base = normalizeFactorBaseUrl(frUrl);
+  const url = `${base}/turns/${encodeURIComponent(params.turnId)}/end`;
+  try {
+    await fetch(url, {
+      method: "POST",
+      headers: {
+        Authorization: `Bearer ${frKey}`,
+        "Content-Type": "application/json",
+        ...buildFactorHeaders(params.userContext)
+      },
+      body: JSON.stringify({ reason: params.reason ?? "message_result" })
+    });
+  } catch {
+  }
+}
+function hasLegacyNomadEnvVars() {
+  return Boolean(
+    (process.env.NOMAD_API_KEY || "").trim() || (process.env.NOMAD_BASE_URL || "").trim() || (process.env.MODEL_NOMAD || "").trim()
+  );
+}
+var LLMService = class {
+  client;
+  constructor() {
+    const frUrl = (process.env.FACTOR_ROUTER_URL ?? "").trim();
+    const frKey = (process.env.FACTOR_ROUTER_KEY ?? "").trim();
+    if (!frUrl || !frKey) {
+      let msg = "FACTOR_ROUTER_URL and FACTOR_ROUTER_KEY must be set in the environment (e.g. export in your shell profile or OS user variables).";
+      if (hasLegacyNomadEnvVars()) {
+        msg += " You still have NOMAD_API_KEY, NOMAD_BASE_URL, and/or MODEL_NOMAD set \u2014 remove those and use FactorRouter variables instead.";
+      }
+      throw new Error(msg);
+    }
+    const baseURL = normalizeFactorBaseUrl(frUrl);
+    this.client = new OpenAI({
+      apiKey: frKey,
+      baseURL
+    });
+  }
+  requestHeaders(ctx) {
+    return buildFactorHeaders(ctx);
+  }
+  async chatCompletion(params) {
+    if (!params.userContext) {
+      throw new Error("LLMService.chatCompletion: userContext \xE9 obrigat\xF3rio");
+    }
+    const tools = params.tools;
+    const hasTools = Array.isArray(tools) && tools.length > 0;
+    const resp = await this.client.chat.completions.create(
+      {
+        model: "auto",
+        messages: params.messages,
+        tools: hasTools ? tools : void 0,
+        tool_choice: hasTools ? "auto" : void 0,
+        parallel_tool_calls: params.parallel_tool_calls ?? false,
+        temperature: params.temperature ?? 0,
+        max_tokens: params.max_tokens
+      },
+      { headers: this.requestHeaders(params.userContext) }
+    );
+    return resp;
+  }
+  /**
+   * Streaming — mesmo turnId em todas as chamadas do loop de tools (via params.userContext).
+   */
+  async *chatCompletionStream(params) {
+    if (!params.userContext) {
+      throw new Error("LLMService.chatCompletionStream: userContext \xE9 obrigat\xF3rio");
+    }
+    const tools = params.tools;
+    const hasTools = Array.isArray(tools) && tools.length > 0;
+    const stream = await this.client.chat.completions.create(
+      {
+        model: "auto",
+        messages: params.messages,
+        tools: hasTools ? tools : void 0,
+        tool_choice: hasTools ? "auto" : void 0,
+        parallel_tool_calls: params.parallel_tool_calls ?? false,
+        temperature: params.temperature ?? 0,
+        max_tokens: params.max_tokens,
+        stream: true
+      },
+      { headers: this.requestHeaders(params.userContext) }
+    );
+    const toolCallsAccumulator = /* @__PURE__ */ new Map();
+    for await (const chunk of stream) {
+      const choice = chunk.choices[0];
+      if (!choice) continue;
+      const delta = choice.delta;
+      if (delta?.tool_calls) {
+        for (const tc of delta.tool_calls) {
+          const idx = tc.index;
+          if (!toolCallsAccumulator.has(idx)) {
+            toolCallsAccumulator.set(idx, {
+              id: tc.id || "",
+              type: tc.type || "function",
+              function: { name: "", arguments: "" }
+            });
+          }
+          const acc = toolCallsAccumulator.get(idx);
+          if (tc.id) acc.id = tc.id;
+          if (tc.function?.name) acc.function.name = tc.function.name;
+          if (tc.function?.arguments) acc.function.arguments += tc.function.arguments;
+        }
+      }
+      const reasoning = delta?.reasoning_content || delta?.reasoning || "";
+      yield {
+        delta: delta?.content || "",
+        reasoning,
+        tool_calls: choice.finish_reason === "tool_calls" ? Array.from(toolCallsAccumulator.values()) : void 0,
+        finish_reason: choice.finish_reason
+      };
+    }
+    if (toolCallsAccumulator.size > 0) {
+      yield {
+        delta: "",
+        tool_calls: Array.from(toolCallsAccumulator.values()),
+        finish_reason: "tool_calls"
+      };
+    }
+  }
+  /** Compat: modelo efectivo é decidido pelo gateway (`auto`). */
+  getDefaultModel() {
+    return "auto";
+  }
+};
+
 // src/app/agent/core/llm/tool_call_normalizer.ts
 import { randomUUID } from "crypto";
 var ToolCallNormalizer = class {
+  /**
+   * Com tool_calls e sem texto visível: content deve ser null (API OpenAI-compatible), nunca "" nem undefined.
+   */
+  static assistantContentWithToolCalls(content) {
+    if (content === void 0 || content === null) return null;
+    if (typeof content === "string") return content.trim() === "" ? null : content;
+    return null;
+  }
   /**
    * Normaliza a mensagem do assistant, convertendo diferentes formatos de tool calls
    */
   static normalizeAssistantMessage(message2) {
     if (message2.tool_calls && this.isOpenAIFormat(message2.tool_calls)) {
-      return message2;
+      return {
+        ...message2,
+        content: this.assistantContentWithToolCalls(message2.content)
+      };
     }
     const toolCalls = this.extractToolCalls(message2);
     if (toolCalls.length > 0) {
       return {
         role: message2.role || "assistant",
-        content: message2.content || null,
+        content: this.assistantContentWithToolCalls(message2.content),
         tool_calls: toolCalls
       };
     }
@@ -5064,7 +5287,6 @@ var ToolCallNormalizer = class {
 // src/app/agent/bluma/core/bluma.ts
 var BluMaAgent = class {
   llm;
-  model;
   sessionId;
   sessionFile = "";
   history = [];
@@ -5074,11 +5296,12 @@ var BluMaAgent = class {
   skillLoader;
   maxContextTurns = 5;
   isInterrupted = false;
-  constructor(sessionId, eventBus, llm, model, mcpClient, feedbackSystem) {
+  /** Mesmo turnId durante processTurn + todo o loop de tool_calls (FactorRouter). */
+  activeTurnContext = null;
+  constructor(sessionId, eventBus, llm, mcpClient, feedbackSystem) {
     this.sessionId = sessionId;
     this.eventBus = eventBus;
     this.llm = llm;
-    this.model = model;
     this.mcpClient = mcpClient;
     this.feedbackSystem = feedbackSystem;
     this.skillLoader = new SkillLoader(process.cwd());
@@ -5143,9 +5366,15 @@ var BluMaAgent = class {
   getUiToolsDetailed() {
     return this.mcpClient.getAvailableToolsDetailed();
   }
-  async processTurn(userInput) {
+  async processTurn(userInput, userContextInput) {
     this.isInterrupted = false;
     const inputText = String(userInput.content || "").trim();
+    const turnId = uuidv43();
+    this.activeTurnContext = {
+      ...userContextInput,
+      turnId,
+      sessionId: userContextInput.sessionId || this.sessionId
+    };
     this.history.push({ role: "user", content: inputText });
     if (inputText === "/init") {
       this.eventBus.emit("dispatch", inputText);
@@ -5265,6 +5494,13 @@ var BluMaAgent = class {
         try {
           const resultObj = typeof toolResultContent === "string" ? JSON.parse(toolResultContent) : toolResultContent;
           if (resultObj.message_type === "result") {
+            if (this.activeTurnContext) {
+              await notifyFactorRouterTurnEnd({
+                turnId: this.activeTurnContext.turnId,
+                userContext: this.activeTurnContext,
+                reason: "message_result"
+              });
+            }
             shouldContinueConversation = false;
             this.eventBus.emit("backend_message", { type: "done", status: "completed" });
           }
@@ -5302,6 +5538,12 @@ ${editData.error.display}`;
       return `An unexpected error occurred while generating the edit preview: ${e.message}`;
     }
   }
+  getLlmUserContext() {
+    if (!this.activeTurnContext) {
+      throw new Error("BluMaAgent: activeTurnContext ausente (processTurn n\xE3o iniciou o turno).");
+    }
+    return this.activeTurnContext;
+  }
   async _continueConversation() {
     try {
       if (this.isInterrupted) {
@@ -5330,12 +5572,11 @@ ${editData.error.display}`;
     let hasEmittedStart = false;
     let reasoningContent = "";
     const stream = llmService.chatCompletionStream({
-      model: this.model,
       messages: contextWindow,
       temperature: 0,
       tools: this.mcpClient.getAvailableTools(),
-      //tool_choice: 'required',
-      parallel_tool_calls: false
+      parallel_tool_calls: false,
+      userContext: this.getLlmUserContext()
     });
     for await (const chunk of stream) {
       if (this.isInterrupted) {
@@ -5368,11 +5609,14 @@ ${editData.error.display}`;
         }
       }
     }
+    const trimmedText = accumulatedContent.trim();
+    const hasToolCalls = Boolean(toolCalls && toolCalls.length > 0);
+    const content = trimmedText === "" ? null : accumulatedContent;
     const message2 = {
       role: "assistant",
-      content: accumulatedContent || null
+      content
     };
-    if (toolCalls && toolCalls.length > 0) {
+    if (hasToolCalls) {
       message2.tool_calls = toolCalls;
     }
     const normalizedMessage = ToolCallNormalizer.normalizeAssistantMessage(message2);
@@ -5420,7 +5664,7 @@ ${editData.error.display}`;
           this.eventBus.emit("backend_message", { type: "confirmation_request", tool_calls: validToolCalls });
         }
       }
-    } else if (accumulatedContent) {
+    } else if (trimmedText) {
       this.eventBus.emit("backend_message", { type: "assistant_message", content: accumulatedContent });
       const feedback = this.feedbackSystem.generateFeedback({
         event: "protocol_violation_direct_text",
@@ -5435,12 +5679,11 @@ ${editData.error.display}`;
   }
   async _handleNonStreamingResponse(contextWindow) {
     const response = await this.llm.chatCompletion({
-      model: this.model,
       messages: contextWindow,
       temperature: 0,
       tools: this.mcpClient.getAvailableTools(),
-      //tool_choice: 'required',
-      parallel_tool_calls: false
+      parallel_tool_calls: false,
+      userContext: this.getLlmUserContext()
     });
     if (this.isInterrupted) {
       this.eventBus.emit("backend_message", { type: "info", message: "Agent task cancelled by user." });
@@ -5493,7 +5736,7 @@ ${editData.error.display}`;
           this.eventBus.emit("backend_message", { type: "confirmation_request", tool_calls: validToolCalls });
         }
       }
-    } else if (message2.content) {
+    } else if (typeof message2.content === "string" && message2.content.trim()) {
       this.eventBus.emit("backend_message", { type: "assistant_message", content: message2.content });
       const feedback = this.feedbackSystem.generateFeedback({
         event: "protocol_violation_direct_text",
@@ -5509,105 +5752,6 @@ ${editData.error.display}`;
   }
 };
 
-// src/app/agent/core/llm/llm.ts
-import OpenAI from "openai";
-var LLMService = class {
-  client;
-  defaultModel;
-  constructor(config2) {
-    this.client = new OpenAI({
-      apiKey: config2.apiKey,
-      baseURL: config2.baseUrl || "",
-      defaultHeaders: {
-        "HTTP-Referer": "https://bluma.ai",
-        // Optional. Site URL for rankings on openrouter.ai.
-        "X-Title": "Bluma"
-        // Optional. Site title for rankings on openrouter.ai.
-      }
-    });
-    this.defaultModel = config2.model || "";
-  }
-  /**
-   * Chamada tradicional (não-streaming) - retorna resposta completa
-   */
-  async chatCompletion(params) {
-    const resp = await this.client.chat.completions.create({
-      model: params.model || this.defaultModel,
-      messages: params.messages,
-      tools: params.tools,
-      //tool_choice: params.tool_choice,
-      parallel_tool_calls: params.parallel_tool_calls,
-      temperature: params.temperature,
-      max_tokens: params.max_tokens
-    });
-    return resp;
-  }
-  /**
-   * Chamada com streaming - retorna chunks em tempo real
-   * 
-   * Uso:
-   * ```
-   * for await (const chunk of llm.chatCompletionStream(params)) {
-   *   process.stdout.write(chunk.delta);
-   * }
-   * ```
-   */
-  async *chatCompletionStream(params) {
-    const stream = await this.client.chat.completions.create({
-      model: params.model || this.defaultModel,
-      messages: params.messages,
-      tools: params.tools,
-      //tool_choice: params.tool_choice,
-      parallel_tool_calls: params.parallel_tool_calls,
-      temperature: params.temperature,
-      max_tokens: params.max_tokens,
-      stream: true
-    });
-    const toolCallsAccumulator = /* @__PURE__ */ new Map();
-    for await (const chunk of stream) {
-      const choice = chunk.choices[0];
-      if (!choice) continue;
-      const delta = choice.delta;
-      if (delta?.tool_calls) {
-        for (const tc of delta.tool_calls) {
-          const idx = tc.index;
-          if (!toolCallsAccumulator.has(idx)) {
-            toolCallsAccumulator.set(idx, {
-              id: tc.id || "",
-              type: tc.type || "function",
-              function: { name: "", arguments: "" }
-            });
-          }
-          const acc = toolCallsAccumulator.get(idx);
-          if (tc.id) acc.id = tc.id;
-          if (tc.function?.name) acc.function.name = tc.function.name;
-          if (tc.function?.arguments) acc.function.arguments += tc.function.arguments;
-        }
-      }
-      const reasoning = delta?.reasoning_content || delta?.reasoning || "";
-      yield {
-        delta: delta?.content || "",
-        reasoning,
-        tool_calls: choice.finish_reason === "tool_calls" ? Array.from(toolCallsAccumulator.values()) : void 0,
-        finish_reason: choice.finish_reason
-      };
-    }
-    if (toolCallsAccumulator.size > 0) {
-      yield {
-        delta: "",
-        tool_calls: Array.from(toolCallsAccumulator.values()),
-        finish_reason: "tool_calls"
-      };
-    }
-  }
-  /**
-   * Retorna o modelo padrão configurado
-   */
-  getDefaultModel() {
-    return this.defaultModel;
-  }
-};
-
 // src/app/agent/subagents/registry.ts
 var subAgentRegistry = {};
 function registerSubAgent(subAgent) {
@@ -5619,8 +5763,14 @@ function getSubAgentByCommand(cmd) {
   return subAgentRegistry[cmd];
 }
 
+// src/app/agent/subagents/init/init_subagent.ts
+import { v4 as uuidv45 } from "uuid";
+
+// src/app/agent/subagents/base_llm_subagent.ts
+import { v4 as uuidv44 } from "uuid";
+
 // src/app/agent/subagents/init/init_system_prompt.ts
-import os8 from "os";
+import os9 from "os";
 var SYSTEM_PROMPT2 = `
 
 ### YOU ARE BluMa CLI \u2014 INIT SUBAGENT \u2014 AUTONOMOUS SENIOR SOFTWARE ENGINEER @ NOMADENGENUITY
@@ -5783,12 +5933,12 @@ Rule Summary:
 function getInitPrompt() {
   const now = /* @__PURE__ */ new Date();
   const collectedData = {
-    os_type: os8.type(),
-    os_version: os8.release(),
-    architecture: os8.arch(),
+    os_type: os9.type(),
+    os_version: os9.release(),
+    architecture: os9.arch(),
     workdir: process.cwd(),
     shell_type: process.env.SHELL || process.env.COMSPEC || "Unknown",
-    username: os8.userInfo().username || "Unknown",
+    username: os9.userInfo().username || "Unknown",
     current_date: now.toISOString().split("T")[0],
     // Formato YYYY-MM-DD
     timezone: Intl.DateTimeFormat().resolvedOptions().timeZone || "Unknown",
@@ -5822,6 +5972,8 @@ var BaseLLMSubAgent = class {
   sessionFile = "";
   maxContextTurns = 160;
   isInterrupted = false;
+  /** Um turnId por execute(); reutilizado em todo o loop de tools do subagente. */
+  subagentTurnContext = null;
   async execute(input, ctx) {
     this.ctx = ctx;
     this.isInterrupted = false;
@@ -5829,7 +5981,15 @@ var BaseLLMSubAgent = class {
       this.isInterrupted = true;
     });
     await this.initializeHistory();
-    this.history.push({ role: "user", content: typeof input === "string" ? input : JSON.stringify(input) });
+    const rawUser = typeof input === "string" ? input : JSON.stringify(input);
+    const base = ctx.blumaUserContextInput ?? defaultBlumaUserContextInput(`subagent:${this.id}`, rawUser.slice(0, 300));
+    const turnId = uuidv44();
+    this.subagentTurnContext = {
+      ...base,
+      turnId,
+      sessionId: base.sessionId || `subagent:${this.id}`
+    };
+    this.history.push({ role: "user", content: rawUser });
     await this._continueConversation();
     return { history: this.history };
   }
@@ -5868,12 +6028,14 @@ ${editData.error.display}`;
         return;
       }
       const contextWindow = this.history.slice(-this.maxContextTurns);
+      if (!this.subagentTurnContext) {
+        throw new Error("BaseLLMSubAgent: subagentTurnContext n\xE3o inicializado");
+      }
       const response = await this.ctx.llm.chatCompletion({
-        model: this.ctx.policy?.llmDeployment || "default",
         messages: contextWindow,
         tools: this.ctx.mcpClient.getAvailableTools(),
-        //tool_choice: 'required',
-        parallel_tool_calls: false
+        parallel_tool_calls: false,
+        userContext: this.subagentTurnContext
       });
       if (this.isInterrupted) {
         this.emitEvent("info", { message: "SubAgent task cancelled byuserr." });
@@ -5963,6 +6125,13 @@ var InitAgentImpl = class extends BaseLLMSubAgent {
       this.isInterrupted = true;
     });
     await this.initializeHistory();
+    const preview = typeof input === "string" ? input.slice(0, 300) : JSON.stringify(input ?? "").slice(0, 300);
+    const base = ctx.blumaUserContextInput ?? defaultBlumaUserContextInput(`subagent:${this.id}`, preview);
+    this.subagentTurnContext = {
+      ...base,
+      turnId: uuidv45(),
+      sessionId: base.sessionId || `subagent:${this.id}`
+    };
     const seed = `
     Scan the current project repository comprehensively. 
     Map the directory structure (excluding heavy/ignored folders), infer the technology stack from manifests and configs, identify entry points and useful scripts, and analyze module relationships and architectural patterns. 
@@ -5985,7 +6154,6 @@ var SubAgentsBluMa = class {
   mcpClient;
   toolInvoker;
   llm;
-  model;
   projectRoot;
   policy;
   logger;
@@ -5994,7 +6162,6 @@ var SubAgentsBluMa = class {
     this.mcpClient = params.mcpClient;
     this.toolInvoker = params.toolInvoker;
     this.llm = params.llm;
-    this.model = params.model;
     this.projectRoot = params.projectRoot || process.cwd();
     this.policy = params.policy;
     this.logger = params.logger;
@@ -6002,7 +6169,7 @@ var SubAgentsBluMa = class {
   // Recebe dados do front (ex.: { content: inputText } vindo de /init)
   // e faz o roteamento para o subagente adequado com base no comando.
   async registerAndDispatch(frontPayload) {
-    const { command, content, ...rest } = frontPayload || {};
+    const { command, content, userContext, ...rest } = frontPayload || {};
     const resolvedCommand = this.resolveCommand({ command, content });
     if (!resolvedCommand) {
       this.emit("error", { message: "Nenhum comando/subagente correspondente encontrado." });
@@ -6013,16 +6180,18 @@ var SubAgentsBluMa = class {
       this.emit("error", { message: `Subagente n\xE3o registrado para ${resolvedCommand}` });
       return { ok: false, error: "unregistered_subagent" };
     }
+    const inputForAgent = content ?? JSON.stringify({ content, ...rest });
+    const msgPreview = String(inputForAgent).slice(0, 300);
     const ctx = {
       projectRoot: this.projectRoot,
       eventBus: this.eventBus,
       mcpClient: this.mcpClient,
       toolInvoker: this.toolInvoker,
       llm: this.llm,
-      policy: { llmDeployment: this.model, ...this.policy || {} },
-      logger: this.logger
+      policy: { llmDeployment: "auto", ...this.policy || {} },
+      logger: this.logger,
+      blumaUserContextInput: userContext ?? defaultBlumaUserContextInput(`subagent:${resolvedCommand}`, msgPreview)
     };
-    const inputForAgent = content ?? JSON.stringify({ content, ...rest });
     this.emit("info", { message: `[SubAgentsBluMa] Dispatch -> ${resolvedCommand}` });
     return subAgent.execute(inputForAgent, ctx);
   }
@@ -6055,17 +6224,18 @@ var RouteManager = class {
   }
   async handleRoute(payload) {
     const inputText = String(payload.content || "").trim();
+    const { userContext } = payload;
     for (const [path18, handler] of this.routeHandlers) {
       if (inputText === path18 || inputText.startsWith(`${path18} `)) {
-        return handler({ content: inputText });
+        return handler({ content: inputText, userContext });
       }
     }
-    await this.core.processTurn({ content: inputText });
+    await this.core.processTurn({ content: inputText }, userContext);
   }
 };
 
 // src/app/agent/agent.ts
-var globalEnvPath = path16.join(os9.homedir(), ".bluma", ".env");
+var globalEnvPath = path16.join(os10.homedir(), ".bluma", ".env");
 dotenv.config({ path: globalEnvPath });
 var Agent = class {
   sessionId;
@@ -6074,7 +6244,6 @@ var Agent = class {
   feedbackSystem;
   llm;
   routeManager;
-  model;
   core;
   subAgents;
   toolInvoker;
@@ -6085,55 +6254,77 @@ var Agent = class {
     this.toolInvoker = nativeToolInvoker;
     this.mcpClient = new MCPClient(nativeToolInvoker, eventBus);
     this.feedbackSystem = new AdvancedFeedbackSystem();
-    const apiKey = process.env.NOMAD_API_KEY;
-    const baseUrl = process.env.NOMAD_BASE_URL;
-    this.model = process.env.MODEL_NOMAD || "";
-    const requiredEnvVars = ["NOMAD_API_KEY", "NOMAD_BASE_URL"];
-    const missingEnvVars = requiredEnvVars.filter((v) => !process.env[v]);
+    const requiredEnvVars = ["FACTOR_ROUTER_KEY", "FACTOR_ROUTER_URL"];
+    const missingEnvVars = requiredEnvVars.filter((v) => !process.env[v]?.trim());
     if (missingEnvVars.length > 0) {
       const platform = process.platform;
       let guidance = "";
       if (platform === "win32") {
         guidance = [
-          "Windows (PowerShell):",
+          "Current PowerShell session (quick test):",
           ...missingEnvVars.map((v) => `  $env:${v}="<your-value>"`),
-          "  # Para persistir:",
-          ...missingEnvVars.map((v) => `  [System.Environment]::SetEnvironmentVariable("${v}", "<your-value>", "User")`)
+          "",
+          "Persistent (User environment \u2014 restart terminal after):",
+          ...missingEnvVars.map(
+            (v) => `  [System.Environment]::SetEnvironmentVariable("${v}", "<your-value>", "User")`
+          )
         ].join("\n");
-      } else if (platform === "darwin" || platform === "linux") {
+      } else if (platform === "darwin" || platform === "linux" || platform === "freebsd") {
+        const osLabel = platform === "darwin" ? "macOS" : platform === "linux" ? "Linux" : "BSD";
+        const sh = (process.env.SHELL || "").toLowerCase();
+        let rcFile = "~/.profile";
+        if (sh.includes("zsh")) rcFile = "~/.zshrc";
+        else if (sh.includes("bash")) rcFile = platform === "darwin" ? "~/.bash_profile" : "~/.bashrc";
         guidance = [
-          "macOS/Linux (bash/zsh):",
-          ...missingEnvVars.map((v) => `  echo 'export ${v}="<your-value>"' >> ~/.bashrc`),
-          "  source ~/.bashrc"
+          `${osLabel} \u2014 current shell only (quick test):`,
+          ...missingEnvVars.map((v) => `  export ${v}="<your-value>"`),
+          "",
+          `${osLabel} \u2014 persistent (append to ${rcFile} for your current $SHELL):`,
+          ...missingEnvVars.map((v) => `  echo 'export ${v}="<your-value>"' >> ${rcFile}`),
+          `  source ${rcFile}   # or open a new terminal`
         ].join("\n");
       } else {
-        guidance = missingEnvVars.map((v) => `  export ${v}="<your-value>"`).join("\n");
+        guidance = [
+          `${platform} \u2014 current shell:`,
+          ...missingEnvVars.map((v) => `  export ${v}="<your-value>"`)
+        ].join("\n");
       }
-      const message2 = [
+      const messageParts = [
         `Missing required environment variables: ${missingEnvVars.join(", ")}.`,
-        `Configure them globally using the commands below, or set them in: ${globalEnvPath}`,
         "",
-        guidance
-      ].join("\n");
+        "Set them in your user or system environment so the BluMa process inherits them."
+      ];
+      if (hasLegacyNomadEnvVars()) {
+        messageParts.push(
+          "",
+          "You still have NOMAD_API_KEY, NOMAD_BASE_URL, and/or MODEL_NOMAD set. Remove those and use FACTOR_ROUTER_KEY and FACTOR_ROUTER_URL instead."
+        );
+      }
+      messageParts.push("", guidance);
+      const message2 = messageParts.join("\n");
       this.eventBus.emit("backend_message", {
         type: "error",
         code: "missing_env",
         missing: missingEnvVars,
-        path: globalEnvPath,
         message: message2
       });
       throw new Error(message2);
     }
-    this.llm = new LLMService({
-      apiKey,
-      baseUrl,
-      model: this.model
-    });
+    try {
+      this.llm = new LLMService();
+    } catch (e) {
+      const message2 = e?.message || String(e);
+      this.eventBus.emit("backend_message", {
+        type: "error",
+        code: "llm_config",
+        message: message2
+      });
+      throw e;
+    }
     this.core = new BluMaAgent(
       this.sessionId,
       this.eventBus,
       this.llm,
-      this.model,
       this.mcpClient,
       this.feedbackSystem
     );
@@ -6142,7 +6333,6 @@ var Agent = class {
       mcpClient: this.mcpClient,
       toolInvoker: this.toolInvoker,
       llm: this.llm,
-      model: this.model,
       projectRoot: process.cwd()
     });
     this.routeManager = new RouteManager(this.subAgents, this.core);
@@ -6156,12 +6346,13 @@ var Agent = class {
   getUiToolsDetailed() {
     return this.core.getUiToolsDetailed();
   }
-  async processTurn(userInput) {
+  async processTurn(userInput, userContextInput) {
     const inputText = String(userInput.content || "").trim();
+    const resolvedUserContext = userContextInput ?? defaultInteractiveCliUserContextInput(this.sessionId, inputText.slice(0, 300));
     if (inputText === "/init" || inputText.startsWith("/init ")) {
       this.routeManager.registerRoute("/init", this.dispatchToSubAgent);
     }
-    await this.routeManager.handleRoute({ content: inputText });
+    await this.routeManager.handleRoute({ content: inputText, userContext: resolvedUserContext });
   }
   async handleToolResponse(decisionData) {
     await this.core.handleToolResponse(decisionData);
@@ -7709,6 +7900,18 @@ function stopTitleKeeper() {
 }
 
 // src/main.ts
+function extractUserMessage(envelope) {
+  const c = envelope.context;
+  if (c && typeof c === "object" && typeof c.user_request === "string") {
+    return String(c.user_request).slice(0, 300);
+  }
+  if (typeof c === "string") return c.slice(0, 300);
+  try {
+    return JSON.stringify(c ?? {}).slice(0, 300);
+  } catch {
+    return "";
+  }
+}
 function writeJsonl(event) {
   try {
     process.stdout.write(JSON.stringify(event) + "\n");
@@ -7763,7 +7966,18 @@ async function runAgentMode() {
     }
   }
   const eventBus = new EventEmitter2();
-  const sessionId = envelope.session_id || envelope.message_id || uuidv43();
+  const sessionId = envelope.session_id || envelope.message_id || uuidv46();
+  const uc = envelope.user_context;
+  const userContextInput = {
+    sessionId,
+    conversationId: uc?.conversationId ?? null,
+    userMessage: extractUserMessage(envelope),
+    userId: uc?.userId ?? null,
+    userName: uc?.userName ?? null,
+    userEmail: uc?.userEmail ?? null,
+    companyId: uc?.companyId ?? null,
+    companyName: uc?.companyName ?? null
+  };
   let lastAssistantMessage = null;
   let reasoningBuffer = null;
   let lastAttachments = null;
@@ -7848,7 +8062,7 @@ async function runAgentMode() {
       action: envelope.action || "unknown",
       context: envelope.context || {}
     });
-    await agent.processTurn({ content: userContent });
+    await agent.processTurn({ content: userContent }, userContextInput);
     if (!resultEmitted) {
       resultEmitted = true;
       writeJsonl({
@@ -7884,7 +8098,7 @@ function runCliMode() {
   const BLUMA_TITLE = process.env.BLUMA_TITLE || "BluMa - NomadEngenuity";
   startTitleKeeper(BLUMA_TITLE);
   const eventBus = new EventEmitter2();
-  const sessionId = uuidv43();
+  const sessionId = uuidv46();
   const props = {
     eventBus,
     sessionId

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@nomad-e/bluma-cli",
-	"version": "0.1.24",
+	"version": "0.1.25",
 	"description": "BluMa independent agent for automation and advanced software engineering.",
 	"author": "Alex Fonseca",
 	"license": "Apache-2.0",