@goodandready/dsh-agent-orchestrator 0.1.6

package/lib/pipeline/dag-engine.js

@@ -0,0 +1,290 @@
+/**
+ * Directed Acyclic Graph (DAG) Execution Engine for DSH Multi-Agent Pipelines.
+ *
+ * Implements:
+ * - Topological dependency resolution and cycle detection
+ * - Concurrency control with dependency-aware scheduling (parallel independent nodes)
+ * - Blockers propagation: dependent nodes get marked as 'blocked' if a prerequisite fails
+ * - Event hooks: onNodeStart, onNodeComplete, onNodeFail, onNodeBlocked
+ * - Pure logic: completely testable without DSH runtime or network
+ */
+
+export const NODE_STATUS = {
+  PENDING: 'pending',
+  RUNNING: 'running',
+  COMPLETED: 'completed',
+  FAILED: 'failed',
+  BLOCKED: 'blocked',
+  SKIPPED: 'skipped',
+}
+
+/**
+ * Validates stage definitions and checks for circular dependencies.
+ * @param {Array<object>} stages List of stages { id, name, dependsOn: string[], roleId, ... }
+ * @throws {Error} if stages are invalid or contain cycles
+ */
+export function validateGraph(stages) {
+  if (!Array.isArray(stages) || stages.length === 0) {
+    throw new Error('Pipeline must have at least one stage')
+  }
+
+  const ids = new Set()
+  for (const s of stages) {
+    if (!s.id || typeof s.id !== 'string') {
+      throw new Error(`Invalid stage ID: ${JSON.stringify(s)}`)
+    }
+    if (ids.has(s.id)) {
+      throw new Error(`Duplicate stage ID: ${s.id}`)
+    }
+    ids.add(s.id)
+  }
+
+  // Check that all dependsOn references exist
+  for (const s of stages) {
+    const deps = s.dependsOn || []
+    for (const dep of deps) {
+      if (!ids.has(dep)) {
+        throw new Error(`Stage "${s.id}" depends on non-existent stage "${dep}"`)
+      }
+      if (dep === s.id) {
+        throw new Error(`Stage "${s.id}" cannot depend on itself`)
+      }
+    }
+  }
+
+  // Cycle detection via DFS
+  const visited = new Map() // id -> 0 (unvisited), 1 (visiting), 2 (visited)
+  const adj = new Map()
+  for (const s of stages) {
+    visited.set(s.id, 0)
+    adj.set(s.id, s.dependsOn || [])
+  }
+
+  function dfs(nodeId, path = []) {
+    visited.set(nodeId, 1)
+    const currentPath = [...path, nodeId]
+    const neighbors = adj.get(nodeId) || []
+    for (const n of neighbors) {
+      const state = visited.get(n)
+      if (state === 1) {
+        const cycle = [...currentPath.slice(currentPath.indexOf(n)), n].join(' -> ')
+        throw new Error(`Circular dependency detected: ${cycle}`)
+      }
+      if (state === 0) {
+        dfs(n, currentPath)
+      }
+    }
+    visited.set(nodeId, 2)
+  }
+
+  for (const s of stages) {
+    if (visited.get(s.id) === 0) {
+      dfs(s.id)
+    }
+  }
+
+  return true
+}
+
+/**
+ * Returns stages whose dependencies are 100% completed.
+ */
+export function getRunnableStages(stages, stateMap) {
+  return stages.filter((s) => {
+    const currentState = stateMap.get(s.id)?.status || NODE_STATUS.PENDING
+    if (currentState !== NODE_STATUS.PENDING) {
+      return false
+    }
+    const deps = s.dependsOn || []
+    return deps.every((d) => stateMap.get(d)?.status === NODE_STATUS.COMPLETED)
+  })
+}
+
+/**
+ * Identifies stages blocked by upstream failures.
+ */
+export function markBlockedStages(stages, stateMap) {
+  let changed = false
+  for (const s of stages) {
+    const state = stateMap.get(s.id)
+    if (state.status === NODE_STATUS.PENDING) {
+      const deps = s.dependsOn || []
+      const failedDep = deps.find((d) => {
+        const ds = stateMap.get(d)?.status
+        return ds === NODE_STATUS.FAILED || ds === NODE_STATUS.BLOCKED
+      })
+      if (failedDep) {
+        state.status = NODE_STATUS.BLOCKED
+        state.blockedBy = failedDep
+        state.error = `Blocked due to failure of upstream stage: ${failedDep}`
+        changed = true
+      }
+    }
+  }
+  return changed
+}
+
+/**
+ * Executes a pipeline of stages respecting DAG dependencies, concurrency, and blockers.
+ *
+ * @param {object} options
+ * @param {Array<object>} options.stages
+ * @param {function} options.executor async (stage, context) => stageResult
+ * @param {number} [options.concurrency=4] max parallel tasks
+ * @param {object} [options.initialContext={}]
+ * @param {function} [options.onNodeStart]
+ * @param {function} [options.onNodeComplete]
+ * @param {function} [options.onNodeFail]
+ * @param {function} [options.onNodeBlocked]
+/**
+ * Executes a pipeline of stages respecting DAG dependencies, concurrency, and blockers.
+ * Supports both object ({ stages, executor, concurrency }) and positional (stages, executor, options) calls.
+ */
+export async function executeDAG(stagesOrOptions, executorArg, optionsArg = {}) {
+  let stages
+  let executor
+  let concurrency = 4
+  let initialContext = {}
+  let onNodeStart = () => {}
+  let onNodeComplete = () => {}
+  let onNodeFail = () => {}
+  let onNodeBlocked = () => {}
+
+  if (Array.isArray(stagesOrOptions)) {
+    stages = stagesOrOptions
+    executor = executorArg
+    concurrency = optionsArg.concurrency || optionsArg.maxConcurrency || 4
+    initialContext = optionsArg.initialContext || {}
+    if (typeof optionsArg.onNodeStart === 'function') onNodeStart = optionsArg.onNodeStart
+    if (typeof optionsArg.onNodeComplete === 'function') onNodeComplete = optionsArg.onNodeComplete
+    if (typeof optionsArg.onNodeFail === 'function') onNodeFail = optionsArg.onNodeFail
+    if (typeof optionsArg.onNodeBlocked === 'function') onNodeBlocked = optionsArg.onNodeBlocked
+  } else if (stagesOrOptions && typeof stagesOrOptions === 'object') {
+    stages = stagesOrOptions.stages
+    executor = stagesOrOptions.executor
+    concurrency = stagesOrOptions.concurrency || stagesOrOptions.maxConcurrency || 4
+    initialContext = stagesOrOptions.initialContext || {}
+    if (typeof stagesOrOptions.onNodeStart === 'function') onNodeStart = stagesOrOptions.onNodeStart
+    if (typeof stagesOrOptions.onNodeComplete === 'function') onNodeComplete = stagesOrOptions.onNodeComplete
+    if (typeof stagesOrOptions.onNodeFail === 'function') onNodeFail = stagesOrOptions.onNodeFail
+    if (typeof stagesOrOptions.onNodeBlocked === 'function') onNodeBlocked = stagesOrOptions.onNodeBlocked
+  }
+
+  validateGraph(stages)
+
+  const startTime = Date.now()
+  const stateMap = new Map()
+  const artifacts = new Map() // stageId -> artifact output
+
+  for (const s of stages) {
+    stateMap.set(s.id, {
+      id: s.id,
+      name: s.name || s.id,
+      roleId: s.roleId,
+      status: NODE_STATUS.PENDING,
+      dependsOn: s.dependsOn || [],
+      startedAt: null,
+      completedAt: null,
+      durationMs: 0,
+      output: null,
+      error: null,
+      metrics: null,
+    })
+  }
+
+  let runningCount = 0
+  let isDone = false
+
+  return new Promise((resolvePromise, rejectPromise) => {
+    function checkCompletion() {
+      const allDone = stages.every((s) => {
+        const st = stateMap.get(s.id).status
+        return st === NODE_STATUS.COMPLETED || st === NODE_STATUS.FAILED || st === NODE_STATUS.BLOCKED || st === NODE_STATUS.SKIPPED
+      })
+
+      if (allDone && runningCount === 0 && !isDone) {
+        isDone = true
+        const hasFailures = stages.some((s) => {
+          const st = stateMap.get(s.id).status
+          return st === NODE_STATUS.FAILED || st === NODE_STATUS.BLOCKED
+        })
+        resolvePromise({
+          success: !hasFailures,
+          durationMs: Date.now() - startTime,
+          stateMap: Object.fromEntries(stateMap),
+          artifacts: Object.fromEntries(artifacts),
+        })
+      }
+    }
+
+    function triggerNext() {
+      if (isDone) return
+
+      // Propagate blockers first
+      if (markBlockedStages(stages, stateMap)) {
+        for (const s of stages) {
+          const st = stateMap.get(s.id)
+          if (st.status === NODE_STATUS.BLOCKED && !st.notifiedBlocked) {
+            st.notifiedBlocked = true
+            onNodeBlocked(st)
+          }
+        }
+      }
+
+      // Find runnable candidates
+      const runnable = getRunnableStages(stages, stateMap)
+
+      while (runnable.length > 0 && runningCount < concurrency) {
+        const nextStage = runnable.shift()
+        const nodeState = stateMap.get(nextStage.id)
+        nodeState.status = NODE_STATUS.RUNNING
+        nodeState.startedAt = Date.now()
+        runningCount++
+
+        onNodeStart(nodeState)
+
+        // Run task asynchronously
+        const upstreamOutputs = {}
+        for (const dep of nextStage.dependsOn || []) {
+          upstreamOutputs[dep] = artifacts.get(dep)
+        }
+
+        const runContext = {
+          ...initialContext,
+          upstreamOutputs,
+          allArtifacts: Object.fromEntries(artifacts),
+        }
+
+        Promise.resolve()
+          .then(() => executor(nextStage, runContext))
+          .then((result) => {
+            nodeState.status = NODE_STATUS.COMPLETED
+            nodeState.completedAt = Date.now()
+            nodeState.durationMs = nodeState.completedAt - nodeState.startedAt
+            nodeState.output = result?.output ?? result
+            nodeState.metrics = result?.metrics ?? null
+
+            artifacts.set(nextStage.id, nodeState.output)
+            runningCount--
+            onNodeComplete(nodeState)
+            triggerNext()
+          })
+          .catch((err) => {
+            nodeState.status = NODE_STATUS.FAILED
+            nodeState.completedAt = Date.now()
+            nodeState.durationMs = nodeState.completedAt - nodeState.startedAt
+            nodeState.error = err?.message || String(err)
+
+            runningCount--
+            onNodeFail(nodeState, err)
+            triggerNext()
+          })
+      }
+
+      checkCompletion()
+    }
+
+    // Initial trigger
+    triggerNext()
+  })
+}

package/lib/pipeline/decision-trace.js

@@ -0,0 +1,124 @@
+/**
+ * Multi-layered Decision Trace Ledger.
+ *
+ * Implements Issue #108:
+ * - Records reasons for agent selection, model resolution, tool filtering, and execution timings.
+ * - Formatted for injection into `presentationMeta` so UI can inspect the trace without polluting LLM context.
+ * - Strict size limiter (`assertTraceSize <= 4096B`) with cascade truncation of secondary fields:
+ *   logs -> checks -> calls -> summary.
+ */
+
+export const MAX_TRACE_BYTES = 4096
+
+/**
+ * Validates and measures the JSON-serialized byte size of a decision trace.
+ * @param {object} trace
+ * @returns {number}
+ */
+export function getTraceByteLength(trace) {
+  return Buffer.byteLength(JSON.stringify(trace || {}), 'utf-8')
+}
+
+/**
+ * Truncates trace cascadingly if it exceeds MAX_TRACE_BYTES.
+ * Hierarchy of reduction:
+ * 1. Truncate long log messages (to max 64 chars)
+ * 2. Drop debug logs array entirely
+ * 3. Truncate droppedTools array
+ * 4. Truncate reasoning/rationale text
+ * 5. Minimal fallback summary
+ *
+ * @param {object} rawTrace
+ * @param {number} [maxBytes=MAX_TRACE_BYTES]
+ * @returns {object} Guaranteed <= maxBytes
+ */
+export function sanitizeDecisionTrace(rawTrace, maxBytes = MAX_TRACE_BYTES) {
+  if (!rawTrace || typeof rawTrace !== 'object') {
+    return { error: 'Empty trace' }
+  }
+
+  let trace = JSON.parse(JSON.stringify(rawTrace))
+  if (getTraceByteLength(trace) <= maxBytes) {
+    return trace
+  }
+
+  // Level 1: Truncate logs items
+  if (Array.isArray(trace.logs)) {
+    trace.logs = trace.logs.map((l) =>
+      typeof l === 'string' && l.length > 64 ? `${l.slice(0, 61)}...` : l
+    )
+    if (getTraceByteLength(trace) <= maxBytes) return trace
+  }
+
+  // Level 2: Drop logs array completely
+  if (trace.logs) {
+    delete trace.logs
+    if (getTraceByteLength(trace) <= maxBytes) return trace
+  }
+
+  // Level 3: Compact droppedTools
+  if (Array.isArray(trace.droppedTools) && trace.droppedTools.length > 5) {
+    const count = trace.droppedTools.length
+    trace.droppedTools = trace.droppedTools.slice(0, 5)
+    trace.droppedToolsCount = count
+    if (getTraceByteLength(trace) <= maxBytes) return trace
+  }
+
+  // Level 4: Truncate rationale / context
+  if (typeof trace.rationale === 'string' && trace.rationale.length > 120) {
+    trace.rationale = `${trace.rationale.slice(0, 117)}...`
+    if (getTraceByteLength(trace) <= maxBytes) return trace
+  }
+
+  // Level 5: Aggressive compaction to minimal essence
+  return {
+    executionId: trace.executionId,
+    roleId: trace.roleId,
+    model: trace.model,
+    decision: trace.decision || 'delegated',
+    droppedCount: Array.isArray(rawTrace.droppedTools) ? rawTrace.droppedTools.length : 0,
+    truncated: true,
+  }
+}
+
+/**
+ * Creates a structured Decision Trace object.
+ */
+export function createDecisionTrace({
+  executionId,
+  roleId,
+  roleName,
+  requestedModel,
+  assignedModel,
+  selectionReason = 'preset_match',
+  toolSummary,
+  droppedTools = [],
+  depth = 1,
+  durationMs,
+  status = 'completed',
+  rationale,
+}) {
+  const trace = {
+    executionId,
+    timestamp: Date.now(),
+    roleId,
+    roleName,
+    depth,
+    model: {
+      requested: requestedModel,
+      assigned: assignedModel,
+      reason: selectionReason,
+    },
+    tools: {
+      allowedCount: toolSummary?.allowed?.length ?? 0,
+      strippedCount: toolSummary?.strippedSecurity?.length ?? 0,
+      deniedCount: toolSummary?.denied?.length ?? 0,
+    },
+    droppedTools: droppedTools.slice(0, 15),
+    rationale,
+    durationMs,
+    status,
+  }
+
+  return sanitizeDecisionTrace(trace, MAX_TRACE_BYTES)
+}

package/lib/pipeline/decomposer.js

@@ -0,0 +1,102 @@
+/**
+ * Task Decomposition Engine for DSH Multi-Agent Orchestrator.
+ *
+ * Automatically or semi-automatically breaks down tasks received from
+ * DSH chat or Gitea Kanban into concrete subtask stages based on chosen or inferred scenario.
+ */
+
+import { getDefaultScenarios, getDefaultRoles, validateScenario } from './scenarios.js'
+
+/**
+ * Infers scenario complexity based on task description cues.
+ *
+ * @param {string} taskText
+ * @returns {'simple' | 'medium' | 'complex'}
+ */
+/**
+ * Natural language complexity triggers for English and Russian input (Issue #133).
+ */
+export const COMPLEXITY_TRIGGERS = {
+  complex: /новый плагин|с нуля|полная архитектур|рефакторинг всего|from scratch|new plugin|system design|major refactor|complex pipeline|5-6 этап|сложн/i,
+  simple: /баг|опечатк|поправь|быстро|мелк|hotfix|bugfix|typo|quick fix|minor|bump|1-2 этап|прост/i,
+}
+
+export function inferScenarioComplexity(taskText = '') {
+  const text = (taskText || '').toLowerCase()
+
+  if (COMPLEXITY_TRIGGERS.complex.test(text)) {
+    return 'complex'
+  }
+
+  if (COMPLEXITY_TRIGGERS.simple.test(text)) {
+    return 'simple'
+  }
+
+  return 'medium'
+}
+
+/**
+ * Decomposes a task into a customized execution plan using a scenario preset.
+ *
+ * @param {object} params
+ * @param {string} params.taskTitle
+ * @param {string} params.taskDescription
+ * @param {string} [params.scenarioId] 'simple' | 'medium' | 'complex' or 'auto'
+ * @param {object} [params.customScenarios]
+ * @param {object} [params.customRoles]
+ * @returns {object} Decomposed pipeline plan { scenarioId, stages, taskTitle, taskDescription }
+ */
+export function decomposeTask({
+  taskTitle = '',
+  taskDescription = '',
+  scenarioId = 'auto',
+  customScenarios = null,
+  customRoles = null,
+}) {
+  const scenarios = customScenarios || getDefaultScenarios()
+  const roles = customRoles || getDefaultRoles()
+
+  let selectedScenarioId = scenarioId
+  if (!selectedScenarioId || selectedScenarioId === 'auto') {
+    selectedScenarioId = inferScenarioComplexity(`${taskTitle}\n${taskDescription}`)
+  }
+
+  const scenario = scenarios[selectedScenarioId] || scenarios.medium
+  if (!scenario) {
+    throw new Error(`Scenario "${selectedScenarioId}" not found and fallback scenario "medium" is missing`)
+  }
+  validateScenario(scenario)
+
+  // Clone stages and inject customized task scope
+  const instantiatedStages = scenario.stages.map((stage) => {
+    const role = roles[stage.roleId] || {}
+    let customizedScope = stage.subtaskScope || ''
+
+    // Contextualize subtask instructions with the overall goal
+    customizedScope = [
+      `Overall Objective: "${taskTitle}"`,
+      `Deliverable Category: ${role.category || stage.roleId}`,
+      `Specific Guidance: ${customizedScope}`,
+      `Task Details:\n${taskDescription.trim()}`,
+    ].join('\n\n')
+
+    return {
+      ...stage,
+      subtaskScope: customizedScope,
+      roleName: role.name || stage.roleId,
+      assignedModel: role.defaultModel || { provider: 'deepseek', model: 'deepseek-chat' },
+      skills: role.skills || [],
+    }
+  })
+
+  return {
+    pipelineId: `pipe-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 6)}`,
+    scenarioId: selectedScenarioId,
+    scenarioTitle: scenario.title,
+    taskTitle: taskTitle || 'Untitled Pipeline Task',
+    taskDescription: taskDescription || '',
+    stages: instantiatedStages,
+    createdAt: Date.now(),
+  }
+}
+