lynkr 9.5.0 → 9.6.0

package/src/clients/tool-call-repair.js

@@ -0,0 +1,130 @@
+/**
+ * Tool-call id repair for OpenAI-format message arrays.
+ *
+ * OpenAI-compatible providers (Moonshot/Kimi, OpenAI, OpenRouter, …) reject a
+ * request with `Invalid request: tool_call_id <x> is not found` whenever a
+ * `tool` message references an id that has no matching entry in a preceding
+ * assistant `tool_calls` array. This happens in practice when:
+ *
+ *   1. A `tool` message's tool_call_id is empty/missing — e.g. Codex Desktop's
+ *      bundled-plugin (Browser/Computer-use) function_call_output items, and
+ *      synthetic "unsupported call: shell" outputs, arrive without a usable
+ *      `call_id`, so both the assistant tool_call id and the tool_call_id
+ *      flatten to "". (The error shows a blank id: "tool_call_id  is not found".)
+ *   2. An assistant tool_calls entry has an empty/missing id.
+ *   3. Ids drift across multiple conversion layers (Responses↔Chat↔Anthropic),
+ *      leaving a `tool` message pointing at an id no assistant ever issued.
+ *
+ * This helper repairs all three in place: it backfills synthetic ids onto
+ * assistant tool_calls that lack one, re-links each `tool` message to an unused
+ * tool_call id on the nearest preceding assistant, and drops any `tool` message
+ * that has no assistant tool_call to attach to (a dangling result is a hard
+ * 400 at the provider, so dropping it is strictly safer than forwarding it).
+ *
+ * @module clients/tool-call-repair
+ */
+
+const logger = require("../logger");
+
+function isBlankId(id) {
+  return !id || String(id).trim() === "";
+}
+
+/**
+ * Repair tool_call_id linkage in an OpenAI chat-format message array, in place.
+ *
+ * @param {Array} messages - OpenAI chat-format messages (role/content, with
+ *   assistant `tool_calls` and `tool` `tool_call_id`). Mutated in place.
+ * @returns {Array} the same array reference, with orphan tool messages removed.
+ */
+function repairToolCallIds(messages) {
+  if (!Array.isArray(messages) || messages.length === 0) return messages;
+
+  let synthCounter = 0;
+  const nextSyntheticId = () => `call_auto_${synthCounter++}`;
+
+  // Pass 1 — guarantee every assistant tool_call has a non-empty id.
+  for (const msg of messages) {
+    if (msg && msg.role === "assistant" && Array.isArray(msg.tool_calls)) {
+      for (const tc of msg.tool_calls) {
+        if (tc && isBlankId(tc.id)) {
+          tc.id = nextSyntheticId();
+          logger.info({ assignedId: tc.id }, "Backfilled missing assistant tool_call id");
+        }
+      }
+    }
+  }
+
+  // Pass 2 — relink (or drop) every tool message.
+  const repaired = [];
+  let dropped = 0;
+  for (let i = 0; i < messages.length; i++) {
+    const msg = messages[i];
+    if (!msg || msg.role !== "tool") {
+      repaired.push(msg);
+      continue;
+    }
+
+    // Nearest preceding assistant that carries tool_calls (stop at a user turn).
+    let assistant = null;
+    for (let j = i - 1; j >= 0; j--) {
+      const prev = messages[j];
+      if (!prev) continue;
+      if (prev.role === "user") break;
+      if (prev.role === "assistant" && Array.isArray(prev.tool_calls) && prev.tool_calls.length > 0) {
+        assistant = prev;
+        break;
+      }
+    }
+
+    const matches =
+      assistant &&
+      !isBlankId(msg.tool_call_id) &&
+      assistant.tool_calls.some((tc) => tc.id === msg.tool_call_id);
+
+    if (matches) {
+      repaired.push(msg);
+      continue;
+    }
+
+    if (assistant) {
+      // Pick the first tool_call id not already consumed by an earlier result.
+      const usedIds = new Set(
+        repaired.filter((r) => r && r.role === "tool" && r.tool_call_id).map((r) => r.tool_call_id)
+      );
+      const available = assistant.tool_calls.find((tc) => !usedIds.has(tc.id));
+      if (available) {
+        logger.info(
+          { from: isBlankId(msg.tool_call_id) ? "(blank)" : msg.tool_call_id, to: available.id },
+          "Repaired tool_call_id linkage"
+        );
+        msg.tool_call_id = available.id;
+        repaired.push(msg);
+        continue;
+      }
+    }
+
+    // No assistant tool_call to attach to — drop the orphan rather than let it
+    // 400 the whole request at the provider.
+    dropped++;
+    logger.warn(
+      {
+        tool_call_id: isBlankId(msg.tool_call_id) ? "(blank)" : msg.tool_call_id,
+        contentPreview: typeof msg.content === "string" ? msg.content.slice(0, 80) : "",
+      },
+      "Dropped orphan tool message with no matching tool_call"
+    );
+  }
+
+  if (dropped > 0) {
+    logger.info({ dropped, before: messages.length, after: repaired.length }, "Removed orphan tool messages");
+  }
+
+  // Rewrite the array contents in place so callers holding this reference see
+  // the repaired result.
+  messages.length = 0;
+  for (const m of repaired) messages.push(m);
+  return messages;
+}
+
+module.exports = { repairToolCallIds, isBlankId };

package/src/config/index.js

@@ -518,6 +518,12 @@ const agentsDefaultModel = process.env.AGENTS_DEFAULT_MODEL ?? "haiku";
 const agentsMaxSteps = Number.parseInt(process.env.AGENTS_MAX_STEPS ?? "15", 10);
 const agentsTimeout = Number.parseInt(process.env.AGENTS_TIMEOUT ?? "120000", 10);
 
+// Task decomposition configuration (opt-in; builds on the agents subsystem).
+// Single env toggle; everything else is hardcoded below.
+const taskDecompositionEnabled = process.env.TASK_DECOMPOSITION_ENABLED === "true";
+
+// Tier-aware fallback (escalate-then-demote) is always on (hardcoded).
+
 // LLM Audit logging configuration
 const auditEnabled = process.env.LLM_AUDIT_ENABLED === "true"; // default false
 const auditLogFile = process.env.LLM_AUDIT_LOG_FILE ?? path.join(process.cwd(), "logs", "llm-audit.log");
@@ -775,6 +781,23 @@ var config = {
     maxSteps: Number.isNaN(agentsMaxSteps) ? 15 : agentsMaxSteps,
     timeout: Number.isNaN(agentsTimeout) ? 120000 : agentsTimeout,
   },
+  taskDecomposition: {
+    enabled: taskDecompositionEnabled, // only env-driven knob (TASK_DECOMPOSITION_ENABLED)
+    // Hardcoded defaults — tune here if needed.
+    shadow: false,
+    planModel: "sonnet",
+    synthModel: "sonnet",
+    minConfidence: 0.5,
+    gate: {
+      minComplexity: 60,
+      minTokens: 3000,
+      maxSubtasks: 6,
+      minIndependentUnits: 2,
+    },
+  },
+  tierFallback: {
+    enabled: true, // always on (hardcoded): escalate-then-demote on provider failure; floor = SIMPLE
+  },
   tests: {
     defaultCommand: testDefaultCommand ? testDefaultCommand.trim() : null,
     defaultArgs: testDefaultArgs,

package/src/context/output-format-guard.js

@@ -0,0 +1,99 @@
+/**
+ * Output Format Guard
+ *
+ * Appends a short formatting instruction to the system prompt so weaker
+ * backends (Moonshot/Kimi, Ollama, etc.) stop emitting mangled ASCII/Unicode
+ * box-drawing "diagrams" that render as garbage in clients. The actual backend
+ * is decided by tier routing — so even when the client asks for "claude-opus",
+ * the request may be served by a model that formats poorly. This normalizes the
+ * presentation without changing which model serves the request.
+ *
+ * Always-on (no env flag). It is skipped only for Claude-family backends, which
+ * already produce clean GitHub-flavored markdown — injecting there would just
+ * waste tokens. The skip biases toward injecting: if we can't tell, we inject
+ * (a false-inject is harmless ~50 tokens; a false-skip leaves the garble).
+ *
+ * Keyed off the ROUTING-RESOLVED provider/model, never the client's requested
+ * body.model (which is just a label once tier routing is on).
+ *
+ * @module context/output-format-guard
+ */
+
+const logger = require("../logger");
+
+const MARKER = "[fmt-guard]";
+
+// Model names that already produce clean markdown.
+const CLEAN_FORMATTER_RE = /\b(claude|sonnet|opus|haiku)\b/i;
+// Providers that are always Claude-backed.
+const CLEAN_PROVIDERS = new Set(["azure-anthropic"]);
+
+const GUARD_TEXT =
+  `${MARKER} Formatting rules for your response: use plain GitHub-flavored markdown only. ` +
+  "Do NOT draw diagrams or boxes with ASCII or Unicode line-drawing characters " +
+  "(such as ┌ ─ │ └ ├ ┤ ┬ ┴ ╔ ═ ║), and do NOT wrap headings or code in decorative borders. " +
+  "Represent structure and relationships with normal markdown headings, nested bullet lists, " +
+  "numbered lists, or tables. Use standard triple-backtick fenced code blocks for code. " +
+  "Keep code, file paths, commands, and URLs exact.";
+
+/**
+ * Whether the resolved backend already formats cleanly (→ skip injection).
+ * @param {string} provider - routing-resolved provider
+ * @param {string} model - routing-resolved model (NOT the client's requested model)
+ * @returns {boolean}
+ */
+function producesCleanMarkdown(provider, model) {
+  if (CLEAN_PROVIDERS.has(String(provider || "").toLowerCase())) return true;
+  if (model && CLEAN_FORMATTER_RE.test(String(model))) return true;
+  return false;
+}
+
+/**
+ * Append the guard text to a system prompt that may be a string or an array of
+ * Anthropic content blocks. Idempotent via MARKER. Pure — returns the new value.
+ */
+function appendToSystem(system, text) {
+  // String (or empty) system prompt.
+  if (system == null || typeof system === "string") {
+    const base = system || "";
+    if (base.includes(MARKER)) return base;
+    return base ? `${base}\n\n${text}` : text;
+  }
+  // Anthropic array-of-blocks system prompt.
+  if (Array.isArray(system)) {
+    const already = system.some(
+      (b) => typeof b?.text === "string" && b.text.includes(MARKER)
+    );
+    if (already) return system;
+    return [...system, { type: "text", text }];
+  }
+  return system;
+}
+
+/**
+ * Inject the formatting guard into body.system in place, unless the resolved
+ * backend already formats cleanly. Always-on; idempotent.
+ *
+ * @param {object} body - request body (mutated in place)
+ * @param {object} [opts]
+ * @param {string} [opts.provider] - routing-resolved provider
+ * @param {string} [opts.model] - routing-resolved model
+ * @returns {object} body
+ */
+function injectFormatGuard(body, opts = {}) {
+  if (!body) return body;
+  const { provider, model } = opts;
+  if (producesCleanMarkdown(provider, model)) return body;
+
+  body.system = appendToSystem(body.system, GUARD_TEXT);
+  logger.debug({ provider, model }, "[FormatGuard] Injected markdown formatting guard");
+  return body;
+}
+
+module.exports = {
+  injectFormatGuard,
+  producesCleanMarkdown,
+  appendToSystem,
+  MARKER,
+  GUARD_TEXT,
+};

package/src/routing/index.js

@@ -697,6 +697,14 @@ function getRoutingHeaders(decision) {
     headers['X-Lynkr-Cost-Optimized'] = 'true';
   }
 
+  // Tier-aware fallback surfacing (never silent).
+  if (decision.fallback) {
+    headers['X-Lynkr-Fallback'] = 'true';
+    if (decision.fromTier) headers['X-Lynkr-Fallback-From-Tier'] = decision.fromTier;
+    if (decision.servedTier) headers['X-Lynkr-Served-Tier'] = decision.servedTier;
+    if (decision.fallbackDirection) headers['X-Lynkr-Fallback-Direction'] = decision.fallbackDirection;
+  }
+
   if (decision.risk?.level) {
     headers['X-Lynkr-Risk'] = decision.risk.level;
     const hits = Array.from(new Set([

package/src/routing/tier-fallback.js

@@ -0,0 +1,91 @@
+/**
+ * Tier-aware fallback chain (escalate-then-demote).
+ *
+ * When a tier's provider fails, prefer a MORE capable tier first (climb toward
+ * REASONING), and only if every higher tier is also unavailable do we fall
+ * downward — all the way to the local SIMPLE tier as a last resort. This biases
+ * for correctness/availability over cost, matching a conservative routing policy.
+ *
+ * Example ladder: SIMPLE → MEDIUM → COMPLEX → REASONING
+ *   - COMPLEX fails  → [REASONING, MEDIUM, SIMPLE]
+ *   - REASONING fails → [COMPLEX, MEDIUM, SIMPLE]
+ *   - MEDIUM fails    → [COMPLEX, REASONING, SIMPLE]
+ *
+ * Pure and dependency-injectable so it can be unit-tested without real providers.
+ */
+
+const logger = require("../logger");
+
+const TIER_ORDER = ["SIMPLE", "MEDIUM", "COMPLEX", "REASONING"];
+
+/** Default availability check: a provider is unavailable if its circuit is OPEN. */
+function defaultIsProviderAvailable(provider) {
+  try {
+    const { getCircuitBreakerRegistry } = require("../clients/circuit-breaker");
+    const registry = getCircuitBreakerRegistry();
+    const all = typeof registry.getAll === "function" ? registry.getAll() : [];
+    const entry = Array.isArray(all) ? all.find((b) => b.name === provider) : null;
+    return !(entry && entry.state === "OPEN");
+  } catch {
+    return true; // fail open — never block fallback on a health-check error
+  }
+}
+
+/** Resolve a tier name to { tier, provider, model }, or null if not configured. */
+function resolveTier(tier, selector) {
+  try {
+    const sel = selector || require("./model-tiers").getModelTierSelector();
+    const r = sel.selectModel(tier);
+    if (!r || !r.provider || !r.model) return null;
+    return { tier, provider: r.provider, model: r.model };
+  } catch {
+    return null; // tier not configured (TIER_<X> unset) — skip it
+  }
+}
+
+/**
+ * Build the escalate-then-demote fallback chain for a failed tier.
+ *
+ * @param {string} currentTier - the tier whose provider just failed
+ * @param {Object} [opts]
+ * @param {Object} [opts.selector] - model-tiers selector (injected for tests)
+ * @param {Function} [opts.isProviderAvailable] - (provider) => boolean (injected for tests)
+ * @returns {Array<{tier,provider,model,demotedFrom,direction}>} ordered candidates
+ */
+function getFallbackChain(currentTier, opts = {}) {
+  const isAvailable = opts.isProviderAvailable || defaultIsProviderAvailable;
+  const idx = TIER_ORDER.indexOf(currentTier);
+  if (idx === -1) return [];
+
+  const higher = TIER_ORDER.slice(idx + 1); // ascending toward REASONING
+  const lower = TIER_ORDER.slice(0, idx).reverse(); // descending toward SIMPLE
+  const ordered = [...higher, ...lower];
+
+  const seen = new Set();
+  // Never re-attempt the exact provider:model that just failed.
+  const current = resolveTier(currentTier, opts.selector);
+  if (current) seen.add(`${current.provider}:${current.model}`);
+
+  const chain = [];
+  for (const tier of ordered) {
+    const resolved = resolveTier(tier, opts.selector);
+    if (!resolved) continue;
+    const key = `${resolved.provider}:${resolved.model}`;
+    if (seen.has(key)) continue;
+    seen.add(key);
+    if (!isAvailable(resolved.provider)) continue;
+    chain.push({
+      ...resolved,
+      demotedFrom: currentTier,
+      direction: TIER_ORDER.indexOf(tier) > idx ? "up" : "down",
+    });
+  }
+
+  logger.debug(
+    { currentTier, chain: chain.map((c) => `${c.tier}:${c.provider}`) },
+    "[TierFallback] Built fallback chain"
+  );
+  return chain;
+}
+
+module.exports = { getFallbackChain, resolveTier, TIER_ORDER };

package/src/server.js

@@ -29,6 +29,7 @@ const { registerTaskTools } = require("./tools/tasks");
 const { registerTestTools } = require("./tools/tests");
 const { registerMcpTools } = require("./tools/mcp");
 const { registerAgentTaskTool } = require("./tools/agent-task");
+const { registerDecomposeTool } = require("./tools/decompose");
 const { initConfigWatcher, getConfigWatcher } = require("./config/watcher");
 const { initializeHeadroom, shutdownHeadroom, getHeadroomManager } = require("./headroom");
 const { getWorkerPool, isWorkerPoolReady } = require("./workers/pool");
@@ -62,6 +63,7 @@ if (LAZY_TOOLS_ENABLED) {
   registerTestTools();
   registerMcpTools();
   registerAgentTaskTool();
+  registerDecomposeTool();
   logger.info({ mode: "eager" }, "All tools loaded at startup");
 }
 

package/src/tools/decompose.js

@@ -0,0 +1,91 @@
+const { registerTool } = require(".");
+const { runDecomposedTask } = require("../agents/decomposition");
+const logger = require("../logger");
+
+/**
+ * DecomposeTask tool — breaks a complex task into focused subtasks with isolated
+ * context, runs them (parallel where independent), and synthesizes the result.
+ *
+ * Opt-in: requires TASK_DECOMPOSITION_ENABLED=true and AGENTS_ENABLED=true.
+ * Degrades gracefully — if the gate decides decomposition isn't worth it (or
+ * planning fails), it returns ok:true with decomposed:false and a reason so the
+ * caller can solve the task monolithically.
+ */
+function registerDecomposeTool() {
+  registerTool(
+    "DecomposeTask",
+    async ({ args = {} }, context = {}) => {
+      const task = args.task || args.prompt || args.description;
+
+      if (!task || typeof task !== "string") {
+        return {
+          ok: false,
+          status: 400,
+          content: JSON.stringify({ error: "task is required" }, null, 2),
+        };
+      }
+
+      logger.info(
+        { task: task.slice(0, 100), sessionId: context.sessionId },
+        "DecomposeTask: evaluating task for decomposition"
+      );
+
+      try {
+        const result = await runDecomposedTask(task, {
+          sessionId: context.sessionId,
+          cwd: context.cwd,
+          riskLevel: args.riskLevel || context.riskLevel,
+        });
+
+        if (result.decomposed) {
+          return {
+            ok: true,
+            status: 200,
+            content: result.result,
+            metadata: {
+              decomposed: true,
+              subtasks: result.plan?.subtasks?.length,
+              levels: result.stats?.levels,
+              strategy: result.plan?.strategy,
+              confidence: result.quality?.confidence,
+              recommendFallback: result.recommendFallback,
+              savedTokens: result.savings?.savedTokens,
+            },
+          };
+        }
+
+        // Not decomposed — signal the caller to solve monolithically.
+        return {
+          ok: true,
+          status: 200,
+          content: JSON.stringify(
+            {
+              decomposed: false,
+              reason: result.reason,
+              guidance: "Solve this task directly without decomposition.",
+            },
+            null,
+            2
+          ),
+          metadata: { decomposed: false, reason: result.reason },
+        };
+      } catch (error) {
+        logger.error({ error: error.message }, "DecomposeTask: error");
+        return {
+          ok: false,
+          status: 500,
+          content: JSON.stringify(
+            { error: "Decomposition error", message: error.message },
+            null,
+            2
+          ),
+        };
+      }
+    },
+    { category: "decompose" }
+  );
+
+  logger.info("DecomposeTask tool registered");
+}
+
+module.exports = { registerDecomposeTool };

package/src/tools/lazy-loader.js

@@ -77,6 +77,11 @@ const TOOL_CATEGORIES = {
     loader: () => require('./agent-task').registerAgentTaskTool,
     priority: 2,
   },
+  decompose: {
+    keywords: ['decompose', 'subtask', 'break down', 'break into', 'split task', 'plan and execute'],
+    loader: () => require('./decompose').registerDecomposeTool,
+    priority: 2,
+  },
   'code-mode': {
     keywords: ['mcp', 'execute', 'server', 'tool', 'code mode'],
     loader: () => require('./code-mode').registerCodeModeTools,
@@ -296,6 +301,9 @@ function loadCategoryForTool(toolName) {
     // TinyFish (web agent)
     'web_agent': 'tinyfish',
     'agent_task': 'agentTask',
+
+    // Task decomposition
+    'decomposetask': 'decompose',
   };
 
   // Direct mapping