@goodandready/dsh-agent-orchestrator 0.1.6

package/lib/pipeline/guidance.js

@@ -0,0 +1,94 @@
+/**
+ * System Prompt Guidance and Specialist Roster Injection.
+ *
+ * Injects section `orchestrator:roster` into the main chat agent's system prompt:
+ * - Informs the agent of all active specialized roles and their capabilities
+ * - Filters disabled roles (r.enabled !== false) (Issue #101)
+ * - Provides instructions on when to call `orchestrator_delegate_specialist`
+ * - Enforces Strict Separation of Duties (Design/Frontend vs Backend)
+ */
+
+import { toRolesArray } from './delegation.js'
+
+export const ORCHESTRATOR_SECTION_NAME = 'orchestrator:roster'
+export const ORCHESTRATOR_SECTION_ORDER = 55
+
+/**
+ * Pure projection of available roles onto system prompt guidance.
+ *
+ * @param {Array<object>|object} roles Available roles list or dict
+ * @param {string} [toolName] Delegation tool name
+ * @returns {string}
+ */
+export function renderOrchestratorRoster(roles = [], toolName = 'orchestrator_delegate_specialist') {
+  const allRoles = toRolesArray(roles)
+  // Enabled Roster Filter (Issue #101): only advertise active/enabled roles
+  const rolesList = allRoles.filter((r) => r.enabled !== false)
+  if (!rolesList || rolesList.length === 0) return ''
+
+  const lines = [
+    '### Multi-Agent Orchestrator: Specialized Subagent Roster',
+    'You have access to a pool of specialized autonomous subagents. When the user asks you to give a task to a specialist or subagent (e.g. "дай задачу субагенту...", "попроси дизайнера...", "проверь через QA..."), NEVER do that specialized work yourself in a generic way — DELEGATE it immediately using the `' +
+      toolName +
+      '` tool.',
+    '',
+    '**Available Specialist Roles (use exact role ID in tool calls):**',
+  ]
+
+  for (const role of rolesList) {
+    const modelTag = role.defaultModel
+      ? ` [Model: ${role.defaultModel.provider}:${role.defaultModel.model}]`
+      : ''
+    lines.push(
+      `- **${role.id}** (${role.displayName})${modelTag}: ${role.description}`
+    )
+    lines.push(`  → Delegate via: \`${toolName}({ roleId: "${role.id}", task: "..." })\``)
+  }
+
+  lines.push('')
+  lines.push('**Core Delegation & Governance Rules:**')
+  lines.push(
+    '1. **Single Specialist Delegation**: When the user requests a single domain task ("дай задачу субагенту дизайнеру...", "пусть архитектор опишет..."), invoke `' +
+      toolName +
+      '` with the appropriate role ID and full context. Report the specialist\'s deliverable back to the user.'
+  )
+  lines.push(
+    '2. **Full Multi-Agent Pipeline**: When the user requests an end-to-end coordinated project ("сделай через оркестратор...", "/orchestrate <task>"), dispatch a full orchestrated DAG pipeline via `orchestrator_dispatch`.'
+  )
+  lines.push(
+    '3. **Strict Separation of Duties**: Design/Frontend specialists must NEVER implement database schemas or server backend endpoints. Backend specialists must NEVER design UI layouts or CSS styles. QA specialists must independently test contracts.'
+  )
+  lines.push(
+    '4. **Visual Deliverable Status Callout**: Whenever presenting the output of a subagent delegation to the user in chat, you MUST ALWAYS include a clean, prominent callout banner at the very top of your response:\n' +
+    '   - When you have reviewed the subagent deliverable and accepted it without issues:\n' +
+    '     `> 🟢 **Получен результат работы от субагента [<Имя роли>] и принят агентом**`\n' +
+    '   - When the deliverable had issues, needed changes, or you re-invoked the subagent for revisions:\n' +
+    '     `> 🟡 **Результат получен от субагента [<Имя роли>] и отправлен на доработку (итерация X)**`\n' +
+    '   - When the user asks you to send work back for rework or revisions:\n' +
+    '     `> 🔄 **Задача отправлена на доработку субагенту [<Имя роли>]**`'
+  )
+
+  return lines.join('\n')
+}
+
+/**
+ * Registers the specialist roster with the systemPrompt service.
+ *
+ * @param {object} ctx Cordis context
+ * @param {function} getRoles Function returning current roles snapshot
+ * @param {string} [toolName] Delegation tool name to reference
+ */
+export function applyGuidance(ctx, getRoles, toolName = 'orchestrator_delegate_specialist', options = {}) {
+  ctx.inject(['systemPrompt'], (sctx) => {
+    try {
+      sctx.systemPrompt.addSection({
+        name: ORCHESTRATOR_SECTION_NAME,
+        order: ORCHESTRATOR_SECTION_ORDER,
+        render: () => renderOrchestratorRoster(getRoles(), toolName),
+      })
+    } catch (e) {
+      const log = options.logger || ctx.logger || null
+      if (log?.warn) log.warn('[dsh-agent-orchestrator] Guidance section registration warning:', e?.message || e)
+    }
+  })
+}

package/lib/pipeline/intent.js

@@ -0,0 +1,98 @@
+/**
+ * Natural language intent detection for Multi-Agent Orchestrator.
+ *
+ * Recognizes:
+ * - Slash commands: /orchestrate, /orc
+ * - Russian triggers: "сделай через оркестратор", "запусти оркестратор", "используй режим оркестратора"
+ * - English triggers: "orchestrate:", "orchestrate <task>", "use orchestrate mode"
+ */
+
+const KNOWN_SCENARIOS = ['hotfix', 'simple', 'medium', 'complex', 'enterprise', 'auto']
+
+/**
+ * Extracts optional scenario keyword if the first token is a known scenario.
+ */
+function extractScenarioAndTask(rawText) {
+  const trimmed = (rawText || '').trim()
+  if (!trimmed) {
+    return { scenarioId: 'auto', taskTitle: 'Interactive Orchestrated Task' }
+  }
+
+  const parts = trimmed.split(/\s+/)
+  const first = parts[0].toLowerCase().replace(/^[:#]/, '')
+  if (KNOWN_SCENARIOS.includes(first) && parts.length > 1) {
+    return {
+      scenarioId: first,
+      taskTitle: parts.slice(1).join(' ').trim(),
+    }
+  }
+
+  return {
+    scenarioId: 'auto',
+    taskTitle: trimmed,
+  }
+}
+
+/**
+ * Detects whether an incoming chat message is an orchestration request.
+ *
+ * @param {string} text Raw message text
+ * @returns {{ isTrigger: boolean, action?: 'on' | 'off', scenarioId?: string, taskTitle?: string }}
+ */
+export function detectOrchestratorIntent(text) {
+  if (typeof text !== 'string' || !text.trim()) {
+    return { isTrigger: false }
+  }
+
+  const trimmed = text.trim()
+
+  // 1. Slash command: /orchestrate [scenario] [task] or /orc [scenario] [task]
+  const slashMatch = trimmed.match(/^\/(?:orchestrate|orc)(?:\s+(.*))?$/i)
+  if (slashMatch) {
+    const rest = (slashMatch[1] || '').trim()
+    if (rest.toLowerCase() === 'off') {
+      return { isTrigger: true, action: 'off' }
+    }
+    const { scenarioId, taskTitle } = extractScenarioAndTask(rest)
+    return {
+      isTrigger: true,
+      action: 'on',
+      scenarioId,
+      taskTitle,
+    }
+  }
+
+  // 2. Russian natural language triggers
+  // e.g. "сделай через оркестратор: ...", "запусти оркестратор: ...", "используй режим оркестратора ..."
+  const ruMatch = trimmed.match(
+    /^(?:пожалуйста[, ]*)?(?:сделай(?:\s+это)?\s+через\s+оркестратор|запусти(?:\s+задачу\s+через)?\s+оркестратор|используй\s+режим\s+оркестратора)(?:[\s:]+(.*))?$/i
+  )
+  if (ruMatch) {
+    const rest = (ruMatch[1] || '').trim()
+    const { scenarioId, taskTitle } = extractScenarioAndTask(rest)
+    return {
+      isTrigger: true,
+      action: 'on',
+      scenarioId,
+      taskTitle,
+    }
+  }
+
+  // 3. English natural language triggers
+  // e.g. "orchestrate: ...", "use orchestrate mode: ...", "run in orchestrator mode: ..."
+  const enMatch = trimmed.match(
+    /^(?:please\s+)?(?:orchestrate|use\s+orchestrate\s+mode|run\s+(?:this\s+)?in\s+orchestrator\s+mode)(?:[\s:]+(.*))?$/i
+  )
+  if (enMatch) {
+    const rest = (enMatch[1] || '').trim()
+    const { scenarioId, taskTitle } = extractScenarioAndTask(rest)
+    return {
+      isTrigger: true,
+      action: 'on',
+      scenarioId,
+      taskTitle,
+    }
+  }
+
+  return { isTrigger: false }
+}

package/lib/pipeline/intersection.js

@@ -0,0 +1,235 @@
+/**
+ * Tool Intersection & Security Narrowing Engine.
+ *
+ * Enforces the core invariants:
+ * 1. A subagent/specialist MUST NEVER receive more capabilities or tools than its parent.
+ * 2. Anti-Redelegation Shield (Issue #103): child subagents cannot receive delegation tools
+ *    (agent_run, orchestrator_*, delegate, list_subagents).
+ * 3. Leaf Experts Guard (Issue #102): leaf specialized experts run with maxDepth: 1 and cannot spawn child tasks.
+ * 4. Adaptive Tool Filter Sanitization & droppedTools (Issue #111):
+ *    - Automatic intersection of role tools with parent/host capabilities.
+ *    - Detailed droppedTools diagnostics categorized into 'security', 'denied', 'unknown', or 'session-local'.
+ * 5. Bidirectional Tool Synonym Resolution: bridges DSH native tool names
+ *    (read, edit, write, glob, grep, bash) with canonical agent aliases (view_file,
+ *    replace_file_content, write_to_file, find_by_name, grep_search, run_command).
+ * 6. Fail-Closed Allowlist Guard (Issue #104): If the role expects a non-empty toolset
+ *    but the allowed tools set resolves to empty, delegation is blocked with FailClosedAllowlistError.
+ */
+
+export class FailClosedAllowlistError extends Error {
+  constructor(message, details = {}) {
+    super(message)
+    this.name = 'Error'
+    this.code = 'ERR_FAIL_CLOSED_ALLOWLIST'
+    this.isFailClosed = true
+    this.details = details
+  }
+}
+
+export const FORBIDDEN_SECURITY_TOOLS = new Set([
+  'run_code',
+  'code_exec',
+  'system_exec',
+  'terminal_exec',
+])
+
+export const FORBIDDEN_DELEGATION_TOOLS = new Set([
+  'agent_run',
+  'orchestrator_delegate_specialist',
+  'orchestrator_dispatch',
+  'orchestrator_run',
+  'delegate',
+  'list_subagents',
+  'subagent',
+])
+
+export const TOOL_SYNONYMS = {
+  // Read
+  read: ['read', 'view_file', 'read_file', 'cat'],
+  view_file: ['read', 'view_file', 'read_file', 'cat'],
+  read_file: ['read', 'view_file', 'read_file', 'cat'],
+
+  // Write
+  write: ['write', 'write_to_file', 'create_file'],
+  write_to_file: ['write', 'write_to_file', 'create_file'],
+
+  // Edit
+  edit: ['edit', 'replace_file_content', 'edit_file', 'str_replace_editor'],
+  replace_file_content: ['edit', 'replace_file_content', 'edit_file', 'str_replace_editor'],
+  edit_file: ['edit', 'replace_file_content', 'edit_file', 'str_replace_editor'],
+
+  // Glob / Find
+  glob: ['glob', 'find_by_name', 'find_files', 'find'],
+  find_by_name: ['glob', 'find_by_name', 'find_files', 'find'],
+
+  // Grep / Search
+  grep: ['grep', 'grep_search', 'search_text'],
+  grep_search: ['grep', 'grep_search', 'search_text'],
+
+  // Command / Bash
+  bash: ['bash', 'run_command', 'execute_command', 'shell'],
+  run_command: ['bash', 'run_command', 'execute_command', 'shell'],
+
+  // Web
+  search_web: ['search_web', 'web_search', 'google_search'],
+  web_search: ['search_web', 'web_search', 'google_search'],
+  read_url_content: ['read_url_content', 'web_fetch', 'fetch_url', 'curl'],
+  web_fetch: ['read_url_content', 'web_fetch', 'fetch_url', 'curl'],
+}
+
+/**
+ * Normalizes tool list from strings or tool schemas.
+ * @param {Array<string|object>} tools
+ * @returns {string[]}
+ */
+export function normalizeToolNames(tools) {
+  if (!tools || !Array.isArray(tools)) return []
+  return tools
+    .map((t) => (typeof t === 'string' ? t : t?.name))
+    .filter((n) => typeof n === 'string' && n.trim() !== '')
+}
+
+/**
+ * Finds if a candidate tool or any of its known synonyms exists in parentSet.
+ * Returns the exact tool name available in parentSet, or null.
+ */
+function matchParentTool(toolName, parentSet) {
+  if (!parentSet) return toolName
+  if (parentSet.has(toolName)) return toolName
+
+  const synonyms = TOOL_SYNONYMS[toolName] || []
+  for (const syn of synonyms) {
+    if (parentSet.has(syn)) {
+      return syn
+    }
+  }
+  return null
+}
+
+/**
+ * Calculates the safe tool intersection for a specialist child session with
+ * comprehensive droppedTools diagnostics (Issue #111) and fail-closed allowlist guard (Issue #104).
+ *
+ * @param {object} params
+ * @param {Array<string|object>} [params.parentTools] Tools available to parent session (undefined = standalone/test mode)
+ * @param {Array<string|object>} [params.roleTools] Tools declared/requested by the role
+ * @param {Array<string>} [params.denyList] Additional tools explicitly denied by config
+ * @param {boolean} [params.failLoud=true] Throw error if intersection is empty
+ * @param {string} [params.roleId] Role identifier for diagnostic error reporting
+ * @returns {{ tools: string[], droppedTools: Array<{ tool: string, reason: string }>, diff: object }}
+ */
+export function resolveToolIntersection({
+  parentTools = undefined,
+  roleTools = undefined,
+  denyList = [],
+  failLoud = true,
+  roleId = 'specialist',
+} = {}) {
+  const normParent = parentTools !== undefined ? normalizeToolNames(parentTools) : undefined
+  const normRole = roleTools !== undefined ? normalizeToolNames(roleTools) : undefined
+  const normDeny = new Set(normalizeToolNames(denyList))
+
+  const parentSet = normParent !== undefined ? new Set(normParent) : null
+  const strippedSecurity = new Set()
+  const denied = new Set()
+  const allowed = new Set()
+  const droppedTools = []
+
+  const candidates = normRole !== undefined ? normRole : normParent !== undefined ? normParent : []
+
+  // Security shield: track dangerous tools present in parent that are never allowed in children
+  if (normParent !== undefined) {
+    for (const tool of normParent) {
+      if (FORBIDDEN_SECURITY_TOOLS.has(tool)) {
+        strippedSecurity.add(tool)
+        droppedTools.push({ tool, reason: 'security' })
+      } else if (FORBIDDEN_DELEGATION_TOOLS.has(tool)) {
+        strippedSecurity.add(tool)
+        droppedTools.push({ tool, reason: 'anti-redelegation' })
+      }
+    }
+  }
+
+  for (const tool of candidates) {
+    if (FORBIDDEN_SECURITY_TOOLS.has(tool)) {
+      strippedSecurity.add(tool)
+      if (!droppedTools.some((d) => d.tool === tool)) {
+        droppedTools.push({ tool, reason: 'security' })
+      }
+      continue
+    }
+    if (FORBIDDEN_DELEGATION_TOOLS.has(tool)) {
+      strippedSecurity.add(tool)
+      if (!droppedTools.some((d) => d.tool === tool)) {
+        droppedTools.push({ tool, reason: 'anti-redelegation' })
+      }
+      continue
+    }
+    if (normDeny.has(tool)) {
+      denied.add(tool)
+      if (!droppedTools.some((d) => d.tool === tool)) {
+        droppedTools.push({ tool, reason: 'denied' })
+      }
+      continue
+    }
+
+    // Intersection with parent if parent tools constraint is provided
+    if (parentSet !== null) {
+      const parentMatch = matchParentTool(tool, parentSet)
+      if (!parentMatch) {
+        denied.add(tool)
+        if (!droppedTools.some((d) => d.tool === tool)) {
+          droppedTools.push({ tool, reason: 'unknown-or-unsupported' })
+        }
+        continue
+      }
+      // Granted with the parent's actual tool name
+      allowed.add(parentMatch)
+    } else {
+      allowed.add(tool)
+    }
+  }
+
+  const allowedList = Array.from(allowed)
+  const strippedList = Array.from(strippedSecurity)
+  const deniedList = Array.from(denied)
+
+  // Fail-Closed Allowlist Guard (Issue #104)
+  // If role explicitly defines tools, but intersection ends up completely empty,
+  // we MUST fail closed rather than quietly continuing without tools.
+  if (normRole && normRole.length > 0 && allowedList.length === 0) {
+    throw new FailClosedAllowlistError(
+      `[ToolIntersection] SecurityViolation: Tool intersection for role "${roleId}" is empty. Fail-closed allowlist triggered. ` +
+      `Role requested: [${normRole.join(', ')}]. Parent available: [${normParent ? normParent.join(', ') : 'all'}]. ` +
+      `Stripped by policy: [${strippedList.join(', ')}]. Denied: [${deniedList.join(', ')}].`,
+      {
+        roleId,
+        roleRequested: normRole,
+        parentAvailable: normParent || [],
+        strippedSecurity: strippedList,
+        denied: deniedList,
+        droppedTools,
+      }
+    )
+  }
+
+  if (failLoud && allowedList.length === 0 && (normRole ? normRole.length > 0 : true)) {
+    throw new Error(
+      `[ToolIntersection] SecurityViolation: Tool intersection for role "${roleId}" is empty. ` +
+      `Role requested: [${normRole?.join(', ')}]. Parent available: [${normParent?.join(', ')}]. ` +
+      `Stripped by policy: [${strippedList.join(', ')}]. Denied: [${deniedList.join(', ')}].`
+    )
+  }
+
+  return {
+    tools: allowedList,
+    droppedTools,
+    diff: {
+      allowed: allowedList,
+      strippedSecurity: strippedList,
+      denied: deniedList,
+      roleRequested: normRole || [],
+      parentAvailable: normParent || [],
+    },
+  }
+}