Domain: Orchestration — Function Reference

Loads a declarative tool dependency graph from config/orchestration-graph.json (with legacy fallbacks) and provides status reporting, pattern enumeration, tool flow inspection, and sequence verification. Read-only — no mutations. The graph file is re-read on every call (no caching).

MCP Tools Exposed

Exposed through unified controller. Key tool names: orchestration_status, orchestration_list_patterns, orchestration_tool_flow, orchestration_pattern_flow, orchestration_verify_sequence.

Tool Name	Description	Key Inputs	Returns
orchestration_status	Graph coverage summary vs runtime	allTools?: []	{ success, status }
orchestration_list_patterns	List all defined patterns	allTools?: []	{ success, source, patterns[] }
orchestration_tool_flow	Get dependencies for a tool	toolName: string, allTools?: []	{ success, tool, dependencies, missingHard, missingRecommended, ... }
orchestration_pattern_flow	Get annotated pattern steps	patternName: string, allTools?: []	{ success, pattern, description, steps[], unresolvedTools[] }
orchestration_verify_sequence	Validate a tool call sequence	sequence: string[], allTools?: []	{ success, valid, issues[], hints[] }

Core Functions

orchestrationStatus(allTools)

Purpose: Compare graph node inventory vs runtime tool list; report coverage stats by category. Parameters: allTools?: Array<{ name: string }> (runtime tools from MCP server) Returns: { success, status: { source, meta, runtime, graph, coverage, patterns } }

orchestrationListPatterns(allTools)

Purpose: List all named patterns from the graph, counting steps and flagging unresolved tools. Parameters: allTools?: Array<{ name: string }> Returns: { success, source, patterns[{ name, description, stepCount, unresolvedTools[] }] }

orchestrationToolFlow(toolName, allTools)

Purpose: Return full dependency graph node info for a specific tool: dependencies, before/after, recommended, next, triggers. Parameters: toolName: string, allTools?: [] Returns: { success, source, tool, existsInRuntime, existsInGraph, category, acl, profile, requiredParams, optionalParams, defaultParams, failurePolicy, dependencies, missingHardDependencies[], missingRecommendedDependencies[], description } Side effects: Throws if toolName is empty.

orchestrationPatternFlow(patternName, allTools)

Purpose: Return all steps in a pattern with runtime existence annotations. Parameters: patternName: string, allTools?: [] Returns: { success, source, pattern, description, steps[], unresolvedTools[] } Side effects: Throws if pattern not found.

orchestrationVerifySequence(sequence, allTools)

Purpose: Walk a proposed tool call sequence and check hard dependency ordering. Issues = errors (missing hard deps, unknown tools). Hints = warnings (missing recommended, graph not found). Parameters: sequence: string[], allTools?: [] Returns: { success, source, sequence[], valid, issues[], hints[] } Notes for rewrite: Sequence must be non-empty array. Unknown tools produce issues. Tools missing from graph but present in runtime produce hints only.

Database Operations

None. This domain is entirely read-only from the filesystem.

Key Algorithms

Graph File Resolution

GRAPH_PATHS = [
  "config/orchestration-graph.json",           // canonical
  "docs/ideas/GRAPH_ORCHESTRATOR_CORE.json",   // optional fallback
  "docs/examplesofidea/GRAPH_ORCHESTRATOR_CORE.json",  // legacy
  "docs/audits/GRAPH_ORCHESTRATOR_CORE.json"   // legacy
]
return first path where fs.existsSync(path) == true
if none found: return { success: false, graph: empty, warnings: [warning] }

Tool Dependency Sets (getToolDependencySets)

From a graph node:
  hard = union(node.dependencies[], node.orchestration.before[])
  dependencies = node.dependencies[]
  before = node.orchestration.before[]
  implicit = node.orchestration.implicit[]
  after = node.orchestration.after[]
  recommended = node.recommended[]
  next = node.next[]
  triggers = node.triggers[]

hard deps are enforced in sequence verification (violations = issues). recommended deps produce hints only.

Sequence Verification

seen = Set()
for each tool in sequence:
  if tool not in runtimeTools: issues.push({ unknown_tool })
  elif tool not in graphNodes: hints.push({ graph_missing }); seen.add(tool)
  else:
    deps = getToolDependencySets(graphNode)
    missingHard = deps.hard.filter(d => not in seen)
    missingRecommended = deps.recommended.filter(d => not in seen)
    if missingHard: issues.push({ missing_hard_dependency, requiredBefore[] })
    if missingRecommended: hints.push({ missing_recommended_dependency })
    seen.add(tool)
valid = issues.length === 0

Pattern Step Annotation (annotatePatternSteps)

for each step in pattern.sequence:
  toolName = step.tool
  isPlaceholder = blank or starts with "["
  node = graphNodes[toolName] or null
  return { index, tool, required, auto, condition, params, placeholder,
           existsInRuntime, existsInGraph, category }

Graph Summary (getGraphSummary)

graphToolNames = Object.keys(graph.nodes)
runtimeToolNames = allTools.map(t => t.name)
inBoth = graphToolNames ∩ runtimeToolNames
missingInRuntime = graphToolNames - runtimeToolNames
missingInGraph = runtimeToolNames - graphToolNames
categoryCounts = count graph nodes by category

Graph Schema (expected JSON structure)

{
  "_meta": { ... },
  "nodes": {
    "tool_name": {
      "category": "string",
      "description": "string",
      "acl": "string|null",
      "profile": [],
      "required_params": [],
      "optional_params": [],
      "default_params": {},
      "failure_policy": "string|null",
      "dependencies": [],
      "orchestration": { "before": [], "implicit": [], "after": [] },
      "recommended": [],
      "next": [],
      "triggers": []
    }
  },
  "patterns": {
    "pattern_name": {
      "description": "string",
      "sequence": [{ "step": 1, "tool": "name", "required": true, "auto": false, "condition": null, "params": null }]
    }
  },
  "orchestration_rules": {}
}