@agentprojectcontext/apx 1.15.6 → 1.17.0

package/src/daemon/index.js

@@ -21,6 +21,8 @@ import { PluginManager } from "./plugins/index.js";
 import { RoutineScheduler } from "./routines.js";
 import { buildApi } from "./api.js";
 import { triggerWakeup } from "./wakeup.js";
+import { registerOverlayClient } from "./overlay-ws.js";
+import { log as logToUnified } from "../core/logging.js";
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
@@ -32,8 +34,41 @@ const PKG = JSON.parse(
 // to ~/.apx/daemon.log via `stdio: ["ignore", out, out]`. So a single
 // process.stdout.write reaches the file once. In foreground (npm start), it
 // still prints to the console. No double-append.
+//
+// Beyond the legacy stdout sink we also fan out every line to the unified
+// ~/.apx/logs/apx.log via core/logging.js so `apx log` and `apx log -f`
+// see everything that any plugin/module writes through the daemon's log fn.
+//
+// Heuristic for level/module inference: messages prefixed "fatal:" /
+// "uncaughtException:" / "error:" are ERROR; "warn:" / "could not" / "skipping"
+// are WARN; everything else INFO. Plugins normally pass `plugin <id> ...` or
+// `<id>[<name>] ...` — we use the first bracketed token (or first word before
+// ":") as the module tag.
+function inferLevel(msg) {
+  if (/^fatal:|^uncaughtException:|^error:|failed|crash/i.test(msg)) return "ERROR";
+  if (/^warn:|could not|skipping|orphan|broken pipe/i.test(msg)) return "WARN";
+  return "INFO";
+}
+function inferModule(msg) {
+  // "plugin telegram initialized" → telegram
+  const plug = msg.match(/^plugin\s+([a-z_-]+)/i);
+  if (plug) return plug[1];
+  // "telegram[default] ..." → telegram
+  const bracket = msg.match(/^([a-z_-]+)\[/i);
+  if (bracket) return bracket[1];
+  // "whisper: preloading ..." → whisper
+  const colon = msg.match(/^([a-z_-]+):\s/i);
+  if (colon) return colon[1];
+  // "overlay: ..." caught above; "loaded project ..." → daemon
+  return "daemon";
+}
 const log = (msg) => {
   process.stdout.write(`[${new Date().toISOString()}] ${msg}\n`);
+  try {
+    logToUnified(inferLevel(msg), inferModule(msg), msg);
+  } catch {
+    // logger is best-effort, never throw
+  }
 };
 
 function ensureHome() {
@@ -170,6 +205,25 @@ async function main() {
     scheduler.start();
     // Fire wake-up message after a short delay so plugins (Telegram) are ready
     setTimeout(() => triggerWakeup(cfg, log), 3000);
+    // Preload whisper-server in the background so first overlay transcription is fast.
+    // Adopts an existing one if already on the port; otherwise spawns fresh.
+    import("./transcription.js").then(({ preloadWhisperServer }) => {
+      preloadWhisperServer((m) => log(m));
+    }).catch(() => {});
+  });
+
+  // Attach WebSocket upgrade for overlay channel on /overlay/ws
+  server.on("upgrade", async (req, socket, head) => {
+    if (req.url !== "/overlay/ws") { socket.destroy(); return; }
+    // Lazy-import ws to avoid hard dep on startup
+    let WebSocketServer;
+    try { ({ WebSocketServer } = await import("ws")); } catch {
+      socket.destroy(); return;
+    }
+    const wss = new WebSocketServer({ noServer: true });
+    wss.handleUpgrade(req, socket, head, (ws) => {
+      registerOverlayClient(ws);
+    });
   });
 
   server.on("error", (e) => {
@@ -185,6 +239,10 @@ async function main() {
     scheduler.stop();
     plugins.stopAll();
     registries.shutdown();
+    // Best-effort shutdown of whisper-server subprocess.
+    import("./transcription.js").then(({ shutdownWhisperServer }) => {
+      shutdownWhisperServer().catch(() => {});
+    }).catch(() => {});
     server.close(() => {
       clearPid();
       process.exit(0);

package/src/daemon/overlay-ws.js

@@ -0,0 +1,40 @@
+// Singleton WebSocket hub for the overlay channel.
+// Imported by api.js (to register connections) and by plugins/overlay.js (to broadcast).
+
+const _clients = new Set(); // Set<WebSocket>
+let _messageHandler = null; // (ws, data) => void — set by overlay plugin
+
+export const overlayClients = _clients;
+
+export function setOverlayMessageHandler(fn) {
+  _messageHandler = fn;
+}
+
+export function registerOverlayClient(ws) {
+  _clients.add(ws);
+  ws.on("close", () => _clients.delete(ws));
+  ws.on("error", () => _clients.delete(ws));
+  ws.on("message", (raw) => {
+    if (typeof _messageHandler === "function") {
+      let data;
+      try { data = JSON.parse(raw.toString()); } catch { data = { type: "raw", raw: raw.toString() }; }
+      _messageHandler(ws, data);
+    }
+  });
+}
+
+export function broadcastOverlay(msg) {
+  const payload = typeof msg === "string" ? msg : JSON.stringify(msg);
+  for (const ws of _clients) {
+    try {
+      if (ws.readyState === 1) ws.send(payload); // 1 = OPEN
+    } catch {}
+  }
+}
+
+export function sendToClient(ws, msg) {
+  const payload = typeof msg === "string" ? msg : JSON.stringify(msg);
+  try {
+    if (ws.readyState === 1) ws.send(payload);
+  } catch {}
+}

package/src/daemon/plugins/index.js

@@ -13,8 +13,9 @@
 // Plugins are discovered by static import here. Adding a new plugin = importing
 // it and pushing into PLUGINS.
 import telegramPlugin from "./telegram.js";
+import overlayPlugin from "./overlay.js";
 
-export const PLUGINS = [telegramPlugin];
+export const PLUGINS = [telegramPlugin, overlayPlugin];
 
 export class PluginManager {
   constructor({ projects, config, log, registries }) {

package/src/daemon/plugins/overlay.js

@@ -0,0 +1,177 @@
+// Overlay plugin — voice/floating-window channel for the APX daemon.
+//
+// This plugin:
+//   1. Registers as a super-agent channel (type "overlay")
+//   2. Routes inbound messages (POST /overlay/message) to the super-agent
+//   3. Streams tokens + tool events back to overlay clients via WebSocket
+//
+// Overlay history is kept in-memory per session (not persisted to disk).
+// Each new overlay window starts a fresh session.
+//
+// Config (in ~/.apx/config.json):
+//   "overlay": {
+//     "enabled": true,
+//     "route_to_agent": "",        // leave empty = use super-agent
+//     "model": "",                 // override model; leave empty = super-agent.model
+//     "max_history": 20            // turns to keep in context
+//   }
+
+import {
+  broadcastOverlay,
+  sendToClient,
+  setOverlayMessageHandler,
+} from "../overlay-ws.js";
+import { runSuperAgent, isSuperAgentEnabled } from "../super-agent.js";
+import { appendGlobalMessage } from "../../core/messages-store.js";
+
+const CHANNEL = "overlay";
+
+export default {
+  id: "overlay",
+
+  init({ projects, config, log, plugins }) {
+    const cfg = config.overlay || {};
+    const enabled = cfg.enabled !== false; // enabled by default
+
+    // In-memory conversation history per connected client.
+    // Map<WebSocket, Array<{role, content}>>
+    const histories = new WeakMap();
+
+    function getHistory(ws) {
+      if (!histories.has(ws)) histories.set(ws, []);
+      return histories.get(ws);
+    }
+
+    // Handle messages sent from the overlay renderer via WebSocket
+    setOverlayMessageHandler(async (ws, data) => {
+      if (data.type === "message") {
+        await _handleMessage({ ws, text: data.text, previousMessages: getHistory(ws) }, { projects, config, log, plugins, cfg, histories });
+      } else if (data.type === "cancel") {
+        // Signal to abort current generation (handled via AbortController below)
+        ws._overlayAbort?.abort();
+      } else if (data.type === "ping") {
+        sendToClient(ws, { type: "pong" });
+      }
+    });
+
+    const instance = {
+      start() {
+        if (enabled) log("overlay: plugin started");
+      },
+      stop() {},
+      status() { return { enabled }; },
+
+      // Called by the /overlay/message REST endpoint
+      async handleMessage({ text, previousMessages = [] }) {
+        if (!enabled) throw new Error("overlay plugin not enabled");
+        broadcastOverlay({ type: "user_message", text });
+        await _handleMessage({ ws: null, text, previousMessages }, { projects, config, log, plugins, cfg, histories });
+      },
+    };
+
+    return instance;
+  },
+};
+
+// ---------------------------------------------------------------------------
+// Core message handler
+// ---------------------------------------------------------------------------
+
+async function _handleMessage({ ws, text, previousMessages }, { projects, config, log, plugins, cfg, histories }) {
+  // Append user turn to history
+  if (ws && histories) {
+    const hist = _getHistory(ws, histories);
+    hist.push({ role: "user", content: text });
+  }
+
+  const maxHistory = cfg.max_history ?? 20;
+  const history = ws ? _getHistory(ws, histories).slice(-(maxHistory)) : previousMessages.slice(-(maxHistory));
+
+  // AbortController for cancel support
+  const controller = new AbortController();
+  if (ws) ws._overlayAbort = controller;
+
+  // Emit "thinking" indicator
+  _send(ws, { type: "thinking" });
+
+  // Persist to overlay message log
+  try {
+    await appendGlobalMessage(CHANNEL, { role: "user", content: text, ts: new Date().toISOString() });
+  } catch {}
+
+  let fullResponse = "";
+  let toolsExecuted = [];
+
+  try {
+    if (!isSuperAgentEnabled(config)) {
+      throw new Error("super-agent not enabled — set super_agent.enabled + super_agent.model in ~/.apx/config.json");
+    }
+
+    const result = await runSuperAgent({
+      globalConfig: config,
+      projects,
+      plugins,
+      prompt: text,
+      contextNote: "# Channel context\nChannel: overlay (floating voice window). Reply concisely.",
+      previousMessages: history.slice(0, -1),
+      overrideModel: cfg.model || null,
+      signal: controller.signal,
+      onToken: (chunk) => {
+        fullResponse += chunk;
+        _send(ws, { type: "token", text: chunk });
+      },
+      onEvent: async (event) => {
+        if (event.type === "tool_start") {
+          const t = event.trace;
+          toolsExecuted.push(t.tool);
+          _send(ws, { type: "tool_start", name: t.tool, args: t.args });
+        } else if (event.type === "tool_result") {
+          _send(ws, { type: "tool_done", name: event.trace.tool });
+        } else if (event.type === "assistant_text" && event.text && !fullResponse) {
+          _send(ws, { type: "token", text: event.text });
+          fullResponse += event.text;
+        }
+      },
+    });
+    const finalText = fullResponse || result.text || "";
+
+    // Emit done with full text
+    _send(ws, { type: "done", text: finalText });
+
+    // Append assistant turn to history
+    if (ws && histories) {
+      const hist = _getHistory(ws, histories);
+      hist.push({ role: "assistant", content: finalText });
+      // Trim history
+      if (hist.length > (cfg.max_history ?? 20)) {
+        hist.splice(0, hist.length - (cfg.max_history ?? 20));
+      }
+    }
+
+    // Persist assistant response
+    try {
+      await appendGlobalMessage(CHANNEL, { role: "assistant", content: finalText, ts: new Date().toISOString() });
+    } catch {}
+
+  } catch (e) {
+    if (e.name === "AbortError") {
+      _send(ws, { type: "cancelled" });
+    } else {
+      log(`overlay: error — ${e.message}`);
+      _send(ws, { type: "error", message: e.message });
+    }
+  }
+}
+
+function _send(ws, msg) {
+  if (ws) {
+    sendToClient(ws, msg);
+  } else {
+    broadcastOverlay(msg);
+  }
+}
+
+function _getHistory(ws, histories) {
+  if (!histories.has(ws)) histories.set(ws, []);
+  return histories.get(ws);
+}

package/src/daemon/plugins/telegram.js

@@ -554,7 +554,13 @@ class ChannelPoller {
       },
     });
 
-    if (!this.channel.respond_with_engine) return;
+    // Super-agent is ALWAYS active on Telegram: respond_with_engine === false
+    // used to silently drop user messages, which looked to the user like the
+    // bot ignored them. Honour the legacy flag only as a soft hint (skip the
+    // routed-agent shortcut so we fall straight to super-agent) but never let
+    // it short-circuit the whole reply. To genuinely silence the bot, disable
+    // the channel entirely (telegram.enabled = false in config).
+    const skipRoutedAgent = this.channel.respond_with_engine === false;
     if (!text) return;
 
     // Short-circuit /reset / /new: send an ack and don't engage the engine.
@@ -586,8 +592,9 @@ class ChannelPoller {
     let replyAuthor;
     const projectCfg = target.config || this.globalConfig;
 
-    // Try the project's chosen agent first
-    const routeSlug = this.channel.route_to_agent;
+    // Try the project's chosen agent first (skipped if the legacy
+    // respond_with_engine === false hint asked to bypass routed agents).
+    const routeSlug = skipRoutedAgent ? null : this.channel.route_to_agent;
     if (routeSlug) {
       const agent = readAgents(target.path).find((a) => a.slug === routeSlug);
       if (agent && agent.fields.Model) {
@@ -642,6 +649,11 @@ class ChannelPoller {
           return; // don't send reply if aborted
         }
         this.log(`telegram[${this.channel.name}] super-agent failed: ${e.message}`);
+        // Surface the failure to the user instead of silently dropping the
+        // turn — otherwise from the chat side it looks like the bot ignored
+        // the message. Keep the message short and non-leaking.
+        replyText = `⚠️ Could not generate a reply right now (${e.message || "internal error"}).`;
+        replyAuthor = "apx";
       }
     }
 

package/src/daemon/super-agent-langchain.js

@@ -0,0 +1,296 @@
+// LangChain adapter for the APX super-agent.
+//
+// Lives alongside the native loop in super-agent.js. Selected via
+// config.super_agent.engine === "langchain" (default: "native"). The two
+// implementations expose the same shape:
+//
+//   { text, usage, name, trace }   ← return value
+//   { globalConfig, projects, plugins, registries, prompt,
+//     previousMessages, contextNote, onEvent, onToken, signal }   ← input
+//
+// Why a toggle and not a replacement: the native loop carries APX-specific
+// features (pseudo-tool fallback for Ollama 500, ghost-response detection,
+// permission_mode gates wired through tool handlers, identity-block injection,
+// ACK_ONLY_TOOLS streak guard). Re-implementing all of those inside LangChain
+// is a large refactor; meanwhile the toggle lets us A/B both paths and pick
+// the one that actually behaves better with gemma4-class models on the
+// user's hardware.
+//
+// LangChain version compat: written against @langchain/core ^0.3 +
+// langchain ^0.3 + @langchain/anthropic ^0.3 + @langchain/ollama ^0.2.
+//
+// Limitations vs native loop (acknowledged in v1):
+//   - permission_mode confirmations are still enforced inside each tool
+//     handler (they return {error: "requires_confirmation: ..."}), but
+//     the loop has no UI to ask the user mid-run, so confirmable tools
+//     just fail-fast as they do today.
+//   - Pseudo-tool fallback (for Ollama 500 on structured tools) is NOT
+//     implemented here — if the underlying engine fails, the call
+//     propagates. Use engine === "native" for that case.
+
+import { AgentExecutor, createToolCallingAgent } from "langchain/agents";
+import { ChatPromptTemplate, MessagesPlaceholder } from "@langchain/core/prompts";
+import { DynamicStructuredTool } from "@langchain/core/tools";
+import { HumanMessage, AIMessage, ToolMessage } from "@langchain/core/messages";
+import { z } from "zod";
+
+import { TOOL_SCHEMAS, makeToolHandlers } from "./super-agent-tools.js";
+import { readIdentity } from "../core/identity.js";
+import { logInfo, logWarn, logError } from "../core/logging.js";
+
+const MAX_ITER_DEFAULT = 15;
+
+// ---------------------------------------------------------------------------
+// JSON-Schema → Zod converter
+// ---------------------------------------------------------------------------
+// LangChain's DynamicStructuredTool wants a Zod schema. APX's tools ship JSON
+// Schema (in the OpenAI function-calling shape). We translate just enough for
+// the parameter types APX actually uses: string, number, boolean, object,
+// array, enum, optional/required. Anything more exotic falls back to z.any().
+function jsonSchemaToZod(schema) {
+  if (!schema || typeof schema !== "object") return z.any();
+  // OpenAI function shape: { type: "function", function: { parameters: {...} } }
+  const root = schema.function?.parameters || schema.parameters || schema;
+  return objectToZod(root);
+}
+
+function objectToZod(obj) {
+  if (!obj || obj.type !== "object" || !obj.properties) {
+    return z.object({}).passthrough();
+  }
+  const required = new Set(obj.required || []);
+  const shape = {};
+  for (const [key, prop] of Object.entries(obj.properties)) {
+    let s = propToZod(prop);
+    if (!required.has(key)) s = s.optional();
+    if (prop?.description) s = s.describe(prop.description);
+    shape[key] = s;
+  }
+  return z.object(shape);
+}
+
+function propToZod(prop) {
+  if (!prop || typeof prop !== "object") return z.any();
+  if (Array.isArray(prop.enum) && prop.enum.length > 0) {
+    return z.enum(prop.enum);
+  }
+  switch (prop.type) {
+    case "string":  return z.string();
+    case "number":  return z.number();
+    case "integer": return z.number().int();
+    case "boolean": return z.boolean();
+    case "array":   return z.array(prop.items ? propToZod(prop.items) : z.any());
+    case "object":  return objectToZod(prop);
+    default:        return z.any();
+  }
+}
+
+// ---------------------------------------------------------------------------
+// APX tool → LangChain DynamicStructuredTool
+// ---------------------------------------------------------------------------
+function buildLangChainTools(handlers, schemas, { trace, onEvent }) {
+  return schemas.map((s) => {
+    const name = s.function.name;
+    const handler = handlers[name];
+    if (!handler) {
+      logWarn("super-agent-lc", `no handler for tool ${name} — skipping`);
+      return null;
+    }
+    return new DynamicStructuredTool({
+      name,
+      description: s.function.description || "",
+      schema: jsonSchemaToZod(s),
+      func: async (args) => {
+        const traceId = `lc:${trace.length + 1}`;
+        if (typeof onEvent === "function") {
+          try {
+            await onEvent({
+              type: "tool_start",
+              trace: { id: traceId, tool: name, args, pending: true },
+            });
+          } catch {}
+        }
+        try {
+          const result = await handler(args || {});
+          trace.push({ id: traceId, tool: name, args, result });
+          if (typeof onEvent === "function") {
+            try { await onEvent({ type: "tool_result", trace: { id: traceId, tool: name, args, result } }); } catch {}
+          }
+          return typeof result === "string" ? result : JSON.stringify(result);
+        } catch (e) {
+          const errObj = { error: e.message };
+          trace.push({ id: traceId, tool: name, args, result: errObj });
+          if (typeof onEvent === "function") {
+            try { await onEvent({ type: "tool_result", trace: { id: traceId, tool: name, args, result: errObj } }); } catch {}
+          }
+          return JSON.stringify(errObj);
+        }
+      },
+    });
+  }).filter(Boolean);
+}
+
+// ---------------------------------------------------------------------------
+// Engine factory — picks an @langchain ChatModel based on modelId
+// ---------------------------------------------------------------------------
+async function makeLangChainModel(modelId, config) {
+  // modelId grammar matches engines/index.js: "<provider>:<model>" or
+  // an inferable bare model id ("claude-…" → anthropic, etc).
+  const [providerRaw, ...rest] = String(modelId || "").split(":");
+  let provider = providerRaw.toLowerCase();
+  let model = rest.join(":");
+  if (!model) {
+    // bare id — infer like engines/index.js
+    if (/^claude/i.test(providerRaw)) { provider = "anthropic"; model = providerRaw; }
+    else if (/^gpt|^o[134]/i.test(providerRaw)) { provider = "openai"; model = providerRaw; }
+    else if (/^gemini/i.test(providerRaw)) { provider = "gemini"; model = providerRaw; }
+    else { provider = "ollama"; model = providerRaw; }
+  }
+  const providerCfg = (config && config.engines && config.engines[provider]) || {};
+
+  if (provider === "anthropic") {
+    const { ChatAnthropic } = await import("@langchain/anthropic");
+    const apiKey = providerCfg.api_key || process.env.ANTHROPIC_API_KEY;
+    if (!apiKey) throw new Error("anthropic: no api_key set");
+    return new ChatAnthropic({ apiKey, model, temperature: 1.0, maxTokens: 1024 });
+  }
+  if (provider === "ollama") {
+    const { ChatOllama } = await import("@langchain/ollama");
+    const baseUrl = providerCfg.base_url || process.env.OLLAMA_HOST || "http://localhost:11434";
+    return new ChatOllama({ baseUrl, model, temperature: 0.7 });
+  }
+  if (provider === "openai") {
+    // Lazy import — only required if the user picks openai.
+    const { ChatOpenAI } = await import("@langchain/openai").catch(() => ({}));
+    if (!ChatOpenAI) throw new Error("openai: install @langchain/openai to use this provider with the langchain engine");
+    const apiKey = providerCfg.api_key || process.env.OPENAI_API_KEY;
+    if (!apiKey) throw new Error("openai: no api_key set");
+    return new ChatOpenAI({ apiKey, model, temperature: 1.0 });
+  }
+  throw new Error(`langchain engine: unknown provider "${provider}" (modelId="${modelId}")`);
+}
+
+// ---------------------------------------------------------------------------
+// Convert APX "previousMessages" rows ({role, content}) → LangChain messages
+// ---------------------------------------------------------------------------
+function toLangChainHistory(previousMessages) {
+  return (previousMessages || []).map((m) => {
+    if (m.role === "user")      return new HumanMessage(m.content || "");
+    if (m.role === "assistant") return new AIMessage(m.content || "");
+    if (m.role === "tool") {
+      // LangChain ToolMessage requires a tool_call_id; APX doesn't track ids
+      // in the FS history, so we use a synthetic one. The agent only sees
+      // the content anyway.
+      return new ToolMessage({ content: m.content || "", tool_call_id: m.tool_name || "tool" });
+    }
+    return new HumanMessage(m.content || "");
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Public entry — same contract as runSuperAgent in super-agent.js
+// ---------------------------------------------------------------------------
+export async function runSuperAgentLangChain({
+  globalConfig,
+  projects,
+  plugins,
+  registries,
+  prompt,
+  previousMessages = [],
+  contextNote = "",
+  systemOverride = null,
+  onEvent,
+  onToken,
+  signal,
+}) {
+  const sa = globalConfig?.super_agent || {};
+  if (!sa.model) throw new Error("super-agent (langchain): no model configured");
+
+  const identity = (() => { try { return readIdentity(); } catch { return null; } })();
+  const userLang = globalConfig?.user?.language || "en";
+
+  // System prompt — we reuse the native module's DEFAULT_SYSTEM unless the
+  // caller passes systemOverride. This keeps the personality / language /
+  // hard-rules consistent across both engines.
+  const { DEFAULT_SYSTEM, buildIdentityBlock } = await import("./super-agent.js");
+  const identityBlock = buildIdentityBlock(identity, userLang);
+  const systemPieces = [
+    systemOverride || sa.system || DEFAULT_SYSTEM,
+    identityBlock,
+    contextNote,
+  ].filter(Boolean);
+  // LangChain ChatPromptTemplate uses f-string formatting and will try to
+  // resolve any `{name}` it finds in the system text as an input variable.
+  // The APX prompt naturally contains literal `{path: <CWD>}` examples and
+  // JSON-like snippets, so we double every `{` and `}` to escape them.
+  const systemText = systemPieces.join("\n\n").replace(/[{}]/g, (c) => c + c);
+
+  const trace = [];
+  const handlers = makeToolHandlers({
+    projects, plugins, registries, globalConfig,
+    implicitConfirmation: false,
+  });
+  const tools = buildLangChainTools(handlers, TOOL_SCHEMAS, { trace, onEvent });
+
+  logInfo("super-agent-lc", "starting AgentExecutor", {
+    model: sa.model, tools: tools.length, prev: previousMessages.length,
+  });
+
+  const llm = await makeLangChainModel(sa.model, globalConfig);
+
+  const promptTemplate = ChatPromptTemplate.fromMessages([
+    ["system", systemText],
+    new MessagesPlaceholder("chat_history"),
+    ["human", "{input}"],
+    new MessagesPlaceholder("agent_scratchpad"),
+  ]);
+
+  const agent = await createToolCallingAgent({ llm, tools, prompt: promptTemplate });
+
+  const executor = new AgentExecutor({
+    agent,
+    tools,
+    maxIterations: Number(sa.max_iterations) > 0 ? Number(sa.max_iterations) : MAX_ITER_DEFAULT,
+    returnIntermediateSteps: true,
+    handleParsingErrors: true,
+    // verbose is noisy; we already log via core/logging.js
+  });
+
+  const t0 = Date.now();
+  let result;
+  try {
+    if (typeof onEvent === "function") {
+      try { await onEvent({ type: "model_start", iteration: 1 }); } catch {}
+    }
+    result = await executor.invoke({
+      input: prompt,
+      chat_history: toLangChainHistory(previousMessages),
+    }, { signal });
+  } catch (e) {
+    logError("super-agent-lc", `executor failed in ${Date.now() - t0}ms`, { error: e.message });
+    throw e;
+  }
+
+  // result.output is the final text. result.intermediateSteps is an array
+  // of { action, observation }; we already pushed each into `trace` from the
+  // DynamicStructuredTool wrappers, so we don't double-record them here.
+  const text = String(result.output || "");
+  logInfo("super-agent-lc", `done in ${Date.now() - t0}ms`, {
+    text_len: text.length,
+    tool_calls: trace.length,
+  });
+
+  return {
+    text,
+    // LangChain doesn't surface token counts uniformly across providers;
+    // leave 0/0 so the caller's bookkeeping doesn't break. Real values
+    // would require provider-specific callback handlers.
+    usage: { input_tokens: 0, output_tokens: 0 },
+    name: sa.name || "apx",
+    trace,
+  };
+}
+
+export function isLangChainEngineSelected(cfg) {
+  return cfg?.super_agent?.engine === "langchain";
+}